Repair a JSON-RPC regression
Input: an observed bug with actual and expected wire values, optionally the
method name and the protocol/reference behavior.
This lane repairs a regression; it does not add unrelated methods or refactor a
namespace. Work in this order:
- Locate the nearest public boundary that reproduces the report: the JSON-RPC
dispatcher, HTTP/WebSocket/IPC server, or memory client. Trace inward through
the response type, native engine request, and conversion helper. Read the
equivalent neighboring method before editing.
- Write the smallest focused test first and run it against the unmodified
implementation. Record that it fails for the reported reason. Use real
createTevmNode()/createMemoryClient() objects and recorded RPC fixtures;
do not mock TEVM objects.
- Pin the expected behavior to the supplied reference. If no reference was
supplied, use a repository conformance fixture or an established neighboring
method. If those disagree or do not define the edge case, stop and report
the ambiguity rather than inventing Ethereum semantics.
- Make the minimum implementation change. Review the complete contract matrix
for this method even when only one conversion changes:
request/params type, result/response type, handler, procedure, namespace
unions, native dispatch table, memory-client exposure,
named barrels, and
tevm facade.
- Assert the wire shape exactly and prove
JSON.stringify(response) succeeds.
JSON-RPC outputs contain no Promise, bigint, typed array, Error, or
undefined. Quantities use minimal hex; byte data is even-length; fixed
storage words are 32-byte left-padded; spec-nullable fields are null.
- Cover the report's alternate/negative branch: null and error provider
responses, short and full-width encodings, legacy transaction fields,
missing transport, manual mining, or state transitions as applicable. Assert
the stable error class and JSON-RPC numeric code. Do not share mutable clients,
Common instances, caches, or timers between test cases.
- Correct JSDoc and guide text only where the repaired public contract was
wrong. Examples are executable, fully imported, and type-valid.
- Add a patch changeset naming every published package whose runtime behavior
changed. Run all declared gates and keep the diff focused on this method.
Do not update snapshots until the focused semantic assertions pass. Never turn
an unexpected error snapshot into the new expected behavior merely to make the
suite green.
Execution and state belong to sibling ZEVM, Voltaire, and Guillotine Mini repositories. This action may fix TEVM host adapters. If the regression requires a native patch, identify the owning files and required regression in the result; do not recreate a JavaScript engine or edit outside the candidate write set.
1---2name: repair-rpc-regression3description: Repair a JSON-RPC regression4---5# Repair a JSON-RPC regression67Input: an observed bug with actual and expected wire values, optionally the8method name and the protocol/reference behavior.910This lane repairs a regression; it does not add unrelated methods or refactor a11namespace. Work in this order:12131. Locate the nearest public boundary that reproduces the report: the JSON-RPC14 dispatcher, HTTP/WebSocket/IPC server, or memory client. Trace inward through15 the response type, native engine request, and conversion helper. Read the16 equivalent neighboring method before editing.172. Write the smallest focused test first and run it against the unmodified18 implementation. Record that it fails for the reported reason. Use real19 `createTevmNode()`/`createMemoryClient()` objects and recorded RPC fixtures;20 do not mock TEVM objects.213. Pin the expected behavior to the supplied reference. If no reference was22 supplied, use a repository conformance fixture or an established neighboring23 method. If those disagree or do not define the edge case, stop and report24 the ambiguity rather than inventing Ethereum semantics.254. Make the minimum implementation change. Review the complete contract matrix26 for this method even when only one conversion changes:27 request/params type, result/response type, handler, procedure, namespace28 unions, native dispatch table, memory-client exposure,29 named barrels, and `tevm` facade.305. Assert the wire shape exactly and prove `JSON.stringify(response)` succeeds.31 JSON-RPC outputs contain no `Promise`, `bigint`, typed array, `Error`, or32 `undefined`. Quantities use minimal hex; byte data is even-length; fixed33 storage words are 32-byte left-padded; spec-nullable fields are `null`.346. Cover the report's alternate/negative branch: null and error provider35 responses, short and full-width encodings, legacy transaction fields,36 missing transport, manual mining, or state transitions as applicable. Assert37 the stable error class and JSON-RPC numeric code. Do not share mutable clients,38 `Common` instances, caches, or timers between test cases.397. Correct JSDoc and guide text only where the repaired public contract was40 wrong. Examples are executable, fully imported, and type-valid.418. Add a patch changeset naming every published package whose runtime behavior42 changed. Run all declared gates and keep the diff focused on this method.4344Do not update snapshots until the focused semantic assertions pass. Never turn45an unexpected error snapshot into the new expected behavior merely to make the46suite green.4748Execution and state belong to sibling ZEVM, Voltaire, and Guillotine Mini repositories. This action may fix TEVM host adapters. If the regression requires a native patch, identify the owning files and required regression in the result; do not recreate a JavaScript engine or edit outside the candidate write set.