Add object reference support via ref field in protocol

Introduces the object reference and registry pattern for persisting objects across requests. Test cases now include a ref field directly in the request when the expected result is a reference, allowing handlers to store and reuse objects like context, block, and chain throughout the tests.

Extends response validation unit tests to test scenarios where reference is expected in response.

Author: stringintech

runner/runner.go

@@ -254,6 +254,19 @@ func validateResponseForSuccess(test TestCase, resp *Response) error {
 		return fmt.Errorf("expected result with value, got null or omitted result")
 	}
 
+	// If the request has a ref field, validate that the response is a reference object
+	if test.Request.Ref != "" {
+		refValue, ok := ParseRefObject(resp.Result)
+		if !ok {
+			return fmt.Errorf("expected reference object result for request with ref field, got: %s", string(resp.Result))
+		}
+		if refValue != test.Request.Ref {
+			return fmt.Errorf("reference mismatch: expected ref %q, got %q", test.Request.Ref, refValue)
+		}
+		return nil
+	}
+
+	// For non-ref results, normalize and compare
 	expectedNorm, err := test.ExpectedResponse.Result.Normalize()
 	if err != nil {
 		return fmt.Errorf("failed to normalize expected result: %w", err)

runner/runner_test.go

@@ -170,7 +170,7 @@ func TestValidateResponse(t *testing.T) {
 		{
 			name: "protocol violation with result not null when error present",
 			testCaseJSON: `{
-				"request": {"id": "11"},
+				"request": {"id": "10"},
 				"expected_response": {
 					"error": {
 						"code": {
@@ -195,7 +195,7 @@ func TestValidateResponse(t *testing.T) {
 		{
 			name: "error generic without code",
 			testCaseJSON: `{
-				"request": {"id": "12"},
+				"request": {"id": "11"},
 				"expected_response": {
 					"error": {}
 				}
@@ -206,6 +206,41 @@ func TestValidateResponse(t *testing.T) {
 			}`,
 			wantErr: false,
 		},
+		{
+			name: "ref object success",
+			testCaseJSON: `{
+				"request": {"id": "12", "ref": "$ctx1"},
+				"expected_response": {"result": {"ref": "$ctx1"}}
+			}`,
+			responseJSON: `{
+				"result": {"ref": "$ctx1"}
+			}`,
+			wantErr: false,
+		},
+		{
+			name: "ref object mismatch",
+			testCaseJSON: `{
+				"request": {"id": "13", "ref": "$ctx1"},
+				"expected_response": {"result": {"ref": "$ctx1"}}
+			}`,
+			responseJSON: `{
+				"result": {"ref": "$ctx2"}
+			}`,
+			wantErr:    true,
+			wantErrMsg: "reference mismatch",
+		},
+		{
+			name: "ref in request but response not a ref object",
+			testCaseJSON: `{
+				"request": {"id": "14", "ref": "$ctx1"},
+				"expected_response": {"result": {"ref": "$ctx1"}}
+			}`,
+			responseJSON: `{
+				"result": true
+			}`,
+			wantErr:    true,
+			wantErrMsg: "expected reference object result",
+		},
 	}
 
 	for _, tt := range tests {

runner/types.go

@@ -30,6 +30,9 @@ type Request struct {
 	ID     string          `json:"id"`
 	Method string          `json:"method"`
 	Params json.RawMessage `json:"params,omitempty"`
+	// Ref specifies the name the handler should use to store the returned object reference
+	// in its registry. Required for methods that return object handles.
+	Ref string `json:"ref,omitempty"`
 }
 
 // Response represents a response from the handler.
@@ -82,3 +85,22 @@ func (r Result) Normalize() (string, error) {
 	}
 	return string(normalized), nil
 }
+
+// RefObject represents a reference type result structure.
+type RefObject struct {
+	Ref string `json:"ref"`
+}
+
+// ParseRefObject extracts the ref value from a reference object.
+// Returns the ref string and true if the result is a valid ref object,
+// or empty string and false otherwise.
+func ParseRefObject[T ~[]byte](r T) (string, bool) {
+	var refObj RefObject
+	if err := json.Unmarshal(r, &refObj); err != nil {
+		return "", false
+	}
+	if refObj.Ref == "" {
+		return "", false
+	}
+	return refObj.Ref, true
+}