Add object reference support via ref field in protocol

Introduces the object reference and registry pattern for persisting objects across requests. The runner now includes a ref field in requests when the expected result is a reference, allowing handlers to store and reuse objects like contexts, blocks, and chains throughout the tests.

Documents the ref field and registry pattern in handler-spec.md.

Author: stringintech

docs/handler-spec.md

@@ -17,14 +17,16 @@ Handlers communicate with the test runner via **stdin/stdout**:
 {
   "id": "unique-request-id",
   "method": "method_name",
-  "params": { /* method-specific parameters */ }
+  "params": { /* method-specific parameters */ },
+  "ref": "reference-name"
 }
 ```
 
 **Fields:**
 - `id` (string, required): Unique identifier for this request
 - `method` (string, required): The operation to perform. Each unique method must be implemented by the handler to exercise the corresponding binding API operation.
 - `params` (object, optional): Method-specific parameters
+- `ref` (string, optional): Reference name for storing the returned object. Required for methods that return object references (see [Object References and Registry](#object-references-and-registry))
 
 ### Response
 
@@ -59,6 +61,30 @@ Handlers communicate with the test runner via **stdin/stdout**:
 4. **Error Handling**: Return error responses for invalid requests or failed operations
 5. **Exit Behavior**: Exit cleanly when stdin closes
 
+## Object References and Registry
+
+Many operations return objects (contexts, blocks, chains, etc.) that must persist across requests. The protocol uses named references and a registry pattern:
+
+**Creating Objects**: Methods that return objects require a `ref` field in the request. The handler stores the object in a registry under that name and returns the reference name as the result.
+
+```json
+// Request
+{"id": "1", "method": "btck_context_create", "params": {...}, "ref": "$ctx1"}
+// Response
+{"id": "1", "result": "$ctx1", "error": null}
+// Handler action: registry["$ctx1"] = created_context_ptr
+```
+
+**Using Objects**: When a parameter is marked as `(reference, required)`, the runner passes the reference name and the handler looks it up:
+
+```json
+// Request
+{"id": "2", "method": "btck_chainstate_manager_create", "params": {"context": "$ctx1"}, "ref": "$csm1"}
+// Handler action: Look up registry["$ctx1"], create manager, store as registry["$csm1"]
+```
+
+**Implementation**: Handlers must maintain a registry (map of reference names to object pointers) throughout their lifetime. Objects remain alive until explicitly destroyed or handler exit.
+
 ## Test Suites and Expected Responses
 
 The conformance tests are organized into suites, each testing a specific aspect of the Bitcoin Kernel bindings. Test files are located in [`../testdata/`](../testdata/).

runner/runner.go

@@ -156,6 +156,11 @@ func (tr *TestRunner) runTest(ctx context.Context, test TestCase) SingleTestResu
 		Params: test.Params,
 	}
 
+	// If the expected result is a reference, include it as ref in the request
+	if ref := extractRefFromExpected(test.Expected); ref != "" {
+		req.Ref = ref
+	}
+
 	err := tr.SendRequest(req)
 	if err != nil {
 		return SingleTestResult{
@@ -241,6 +246,19 @@ func validateResponseForError(test TestCase, resp *Response) error {
 	return nil
 }
 
+// extractRefFromExpected extracts a reference name from the expected result if it's a
+// string starting with "$". Returns empty string if not a reference.
+func extractRefFromExpected(expected TestExpectation) string {
+	var resultStr string
+	if err := json.Unmarshal(expected.Result, &resultStr); err != nil {
+		return ""
+	}
+	if len(resultStr) > 1 && resultStr[0] == '$' {
+		return resultStr
+	}
+	return ""
+}
+
 // validateResponseForSuccess validates that a response correctly represents a success case.
 // It ensures the response contains no error, and if a result is expected, it matches the
 // expected value.

runner/types.go

@@ -40,6 +40,7 @@ type Request struct {
 	ID     string          `json:"id"`
 	Method string          `json:"method"`
 	Params json.RawMessage `json:"params"`
+	Ref    string          `json:"ref,omitempty"`
 }
 
 // Response represents a response from the handler.