fix(core): key a refused argument so it never matches a valid call (#765)

[b3hr4d]

Closes #765

Branch fix/core-refused-arg-keys, one commit on top of #764's head (fix/core-display-arg-forms-key). It changes the same key walk, packages/core/src/utils/args-key.ts.

What was wrong

The args segment of a query key is the JSON of the arguments. JSON writes some values a reactor refuses exactly as it writes values the reactor takes. So when the valid call was cached, fetchQuery or a query hook answered the refused call from the cache instead of failing. Measured on #764's head:

position	refused	taken	shared args segment
null, both reactors	undefined	null	[null]
record {}, both	undefined	null	[null]
text, both	10n	"10"	["10"]
nat, nat32, float64, DisplayReactor	10n	"10"	["10"]
nat, Reactor	"10"	10n	["10"]
principal, both	{ __principal__: "aaaaa-aa" }, which is what JSON.parse returns for a Principal	the Principal	[{"__principal__":"aaaaa-aa"}]
variant, Reactor	{ All: null, ByMemo: undefined }	{ All: null }	[{"All":null}]
record, Reactor	the record without Object.prototype	the plain record	the same
record { id: nat; old: reserved }, Reactor	{ id: 1n }	{ id: 1n, old: undefined }	[{"id":"1"}]
vec record { text; nat }, DisplayReactor	a Date's text	the Date, which the map codec takes as no entries	["1970-01-01T00:00:00.000Z"]

Boxed values collide the same way. For example, new Boolean(true) is refused for a bool but has the JSON of true.

One case gave wrong data between two accepted calls. A Reactor's variant of reserved arms takes { A: undefined } and { B: undefined }. They send different arms, but both keyed as [{}], so the second call got the first one's result.

Item 2 of the issue: some forms that send the same bytes got separate keys, which meant extra calls.

What changed

All in the key walk that Reactor.argsForQueryKey and DisplayReactor.argsForQueryKey run since #757 and #764.

Refused values (item 1). The walk checks each value the way the codec or IDL.encode checks it. A value they refuse is written as a RefusedKey, which generateKey writes as "\u0000refused:" followed by the value's own key. That is the U+0000 tag that also leads a blob's key (#757). No argument can produce it, because a string that starts with U+0000 gets another one. Checked:

• null: anything but null. bool: not a boolean. text: not a string.
• A Reactor's integers: not a bigint or a number. A DisplayReactor's nat, int and 64-bit integers: not text. Its integers of 32 bits or fewer and its floats: not a number or text.
• principal: in a Reactor, not marked _isPrincipal, which is all IDL.encode asks. In a DisplayReactor, neither text nor a Principal.
• A record: not an object, or null when the record has fields. In a Reactor, also an object without Object.prototype, since IDL.encode calls the value's own hasOwnProperty.
• A Reactor's variant given as a plain object: refused unless it has exactly one own key, and that key names an arm. Also refused when it has no Object.prototype.
• A DisplayReactor's map: fix(core): key DisplayReactor args by the value they send, not the form given (#761, #762) #764 read only a plain object as entries. The codec reads any object that is not an array, so the walk now does too.

A value of the right JavaScript type that is still refused keeps its key, because no accepted value has the same JSON. Examples are -1 for a nat and "abc" for a DisplayReactor's nat. A Reactor's floats are not checked. IDL.encode takes any number there, boxed or not, and the values it refuses have no number's JSON. The one collision left there is a boxed NaN: IDL.encode takes it, and JSON writes it as null, which is also the key of a refused null.

Forms that send the same bytes (item 2).

• A DisplayReactor's float or integer of 32 bits or fewer given as text is keyed as the number its codec sends. 10, "10" and "010" share a key, and an integer's -0 and "-0" share the key of 0. The text is read with the codec's own parsing, which moved from inside the two codecs to fixedNumberOf / floatNumberOf in display/visitor.ts, with the same checks and messages. The key and the codec cannot drift apart.
• A DisplayReactor's Principal is keyed as its text.
• Fields a record does not declare are left out, in both reactors. Neither IDL.encode nor the record codec sends them.
• Every value of reserved is keyed as null, the value it decodes to, in both reactors. A DisplayReactor also keys an absent reserved field as null, since its record codec takes it. And it leaves a reserved arm's payload out, as for a null arm. This fixes the variant-of-reserved case above.

Not merged, and why:

• A typed array vs a plain array for a non-blob vector: fix(core): key a blob argument by its bytes, whatever form it is passed in (#748) #757 pins both keys, and a canonical form would have to be chosen.
• A Reactor's number vs bigint: not in the issue.
• Other spellings of a DisplayReactor's nat text ("010", " 10 ", "0x0a"): merging them means a BigInt parse of every nat on every key.
• A Reactor tuple's extra elements, and an empty record given null, an array or a boxed value.

A value already in the form the codecs return comes back as the same object, so its key is byte-identical to #764's.

Docs: one sentence group each in docs/.../framework/query-caching.mdx, docs/.../reference/Reactor.mdx and packages/core/README.md, after #764's. The doc comments of both argsForQueryKey methods say the same.

Evidence

pnpm verify:test-fails tests/reactor-refused-args-query-key.test.ts --package core --base origin/fix/core-display-arg-forms-key:

 23 caught the bug   (fail on origin/fix/core-display-arg-forms-key, pass now)
      ✓ a refused argument (#765) undefined for null in a Reactor is not answered from the valid call's cache entry
      ✓ a refused argument (#765) undefined for null in a DisplayReactor is not answered from the valid call's cache entry
      ✓ a refused argument (#765) undefined for an empty record in a Reactor is not answered from the valid call's cache entry
      ✓ a refused argument (#765) undefined for an empty record in a DisplayReactor is not answered from the valid call's cache entry
      ✓ a refused argument (#765) a bigint for text in a Reactor is not answered from the valid call's cache entry
      ✓ a refused argument (#765) a bigint for text in a DisplayReactor is not answered from the valid call's cache entry
      ✓ a refused argument (#765) text for a nat in a Reactor is not answered from the valid call's cache entry
      ✓ a refused argument (#765) a bigint for a nat in a DisplayReactor is not answered from the valid call's cache entry
      ✓ a refused argument (#765) a bigint for a nat32 in a DisplayReactor is not answered from the valid call's cache entry
      ✓ a refused argument (#765) a bigint for a float64 in a DisplayReactor is not answered from the valid call's cache entry
      ✓ a refused argument (#765) a parsed Principal for a principal in a Reactor is not answered from the valid call's cache entry
      ✓ a refused argument (#765) a parsed Principal for a principal in a DisplayReactor is not answered from the valid call's cache entry
      ✓ a refused argument (#765) a variant with an undefined beside its arm in a Reactor is not answered from the valid call's cache entry
      ✓ a refused argument (#765) a record without Object.prototype in a Reactor is not answered from the valid call's cache entry
      ✓ a refused argument (#765) a record without its reserved field in a Reactor is not answered from the valid call's cache entry
      ✓ a refused argument (#765) the text of a Date for a map in a DisplayReactor is not answered from the valid call's cache entry
      ✓ a refused argument (#765) keeps apart two arms of a Reactor's variant whose payload is reserved
      ✓ a refused argument (#765) writes a refused value behind a tag no argument can spell
      ✓ forms of one value, which send the same bytes (#765) gets one key for a DisplayReactor's small integer as a number or as text
      ✓ forms of one value, which send the same bytes (#765) gets one key for a DisplayReactor's float as a number or as text
      ✓ forms of one value, which send the same bytes (#765) gets one key for a principal as a Principal or as its text
      ✓ forms of one value, which send the same bytes (#765) leaves out the fields a record does not declare
      ✓ forms of one value, which send the same bytes (#765) gets one key for every value of reserved

  2 passed either way  (invariant guards, or vacuous — check each)
      • forms of one value, which send the same bytes (#765) keeps distinct values distinct
      • the key of an argument in the forms the codecs return is byte-identical to the key before

--base origin/main gives the same 23 and 2. Main now contains #764 (7a843dee2), with the same tree as its head.

• Each refused-value test first caches the valid call, then expects fetchQuery of the refused one to reject. It also asserts the premise: callMethod with the refused value rejects before reaching the agent.
• Each merged-form test checks the bytes the agent receives: the forms given one key send identical bytes.
• The two guards are not vacuous. I broke the fix five ways, one at a time: numeric text keyed as 0; declared fields dropped along with undeclared ones; every text refused; reserved keyed as undefined; a Reactor's Principal keyed as its text. Each break fails at least one guard.

Fuzz. Not committed; it extends #764's harness. It runs 49 argument shapes: #764's 26, plus primitives, principals, an ICRC account, reserved fields and arms, empty records and a five-argument list. Each shape runs in Reactor and DisplayReactor mode, in the codecs' forms and in all merged forms, with and without refused values: 392 cases of 4,000 values each. The refused values include a "twin" of each generated value built to have the same JSON: a bigint for numeric text, text for a bigint, undefined for null, boxed values, { __principal__ }, a variant with an undefined arm, and a record without Object.prototype.

• It checks that one key never names two outcomes, where a refusal counts as one outcome. Where only merged forms vary, it also checks that one encoding has one key.
• On fix(core): key DisplayReactor args by the value they send, not the form given (#761, #762) #764's head (seed 20260923), 169 of 392 cases break the first check. 168 have a refused call under an accepted call's key; 1 has two accepted calls with different bytes (the reserved arms). 25 more break the second check.
• This branch passes all 392 on five seeds (1, 7, 424242, 99991, 20260923). fix(core): key DisplayReactor args by the value they send, not the form given (#761, #762) #764's own harness, 156 cases, still passes at 4,000 values.

Keys of accepted values. The same generated values were keyed under #764's head and this branch: 294,000 accepted values in all.

• All 147,000 in the forms the codecs return have byte-identical keys.
• Of the 147,000 in other forms, 18,986 keys changed. 17,915 now equal the key of the codec form that sends the same bytes. The other 1,071 are the same key with an undeclared field removed, a Principal written as its text, or reserved written as null. None changed in any other way.

Cost. generateQueryKey with a 100,000-element argument, mean of 10 calls, 3 runs each, #764's head and this branch measured back to back:

argument	#764 head	this PR
Reactor: records { principal; nat }	99–103 ms	109–111 ms
Reactor: records with an opt and a variant	140–143 ms	165–173 ms
Reactor: vec nat / vec text	8–9 / 9 ms	10 / 7–10 ms
DisplayReactor: records { principal; nat }	32–33 ms	41–43 ms
DisplayReactor: records with an opt and a variant, codec forms	81–82 ms	95–99 ms
DisplayReactor: the same records in other forms	108–109 ms	108–111 ms
DisplayReactor: records { nat32; float64 } as numbers	34 ms	44 ms
DisplayReactor: the same as text	32–34 ms	56–57 ms
DisplayReactor: a map of 100,000 entries, as an object / as pairs	33–34 / 16 ms	46 / 24–25 ms
DisplayReactor: vec text	5.6 ms	6.8 ms

In the forms the codecs return, keys cost 6–30% more, and the map cases 36–50%. The text-number row is 68% more: it now parses the text and copies each record, which is the merge.

Gates

• pnpm --filter @ic-reactor/core build, then tests: core 814 passed / 2 skipped; react 720 passed / 15 skipped; candid 649 passed.
• pnpm --filter @ic-reactor/core --filter @ic-reactor/react --filter @ic-reactor/candid typecheck: clean.
• npx eslint packages/core packages/react packages/candid: clean.
• prettier --check on the nine changed files: clean.
• pnpm --filter @ic-reactor/core size: 36.39 kB of 50 kB (35.82 kB on fix(core): key DisplayReactor args by the value they send, not the form given (#761, #762) #764).

Not changed (noted for follow-up)

• A record or variant given as a class instance is not walked, as in fix(core): key a blob argument by its bytes, whatever form it is passed in (#748) #757 and fix(core): key DisplayReactor args by the value they send, not the form given (#761, #762) #764, so a refused value inside one keeps its old key. A DisplayReactor's record codec also reads a class's getters, which JSON leaves out. Two instances whose getters return different amounts both keyed as [{}] and sent different bytes, measured on this branch and on main.
• A JS Map given for a DisplayReactor's vec record { text; T } is sent as an empty vector, because the codec reads Object.entries, which is [] for a Map. The key now matches what is sent, but the entries are dropped without an error.
• A DisplayReactor's validator sees the arguments as given. The key cannot account for a validator that reads a field the codec ignores, and fetchQuery returns a cached entry without running the validator, as before.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 271b753f8a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Tag records that shadow hasOwnProperty

When a raw Reactor receives a nonempty record with an undeclared own hasOwnProperty value—for example, { a: 1n, hasOwnProperty: false }—the SDK rejects it because RecordClass invokes x.hasOwnProperty(...). This call strips that undeclared field before serialization, producing the same query key as the valid { a: 1n }; if that valid call is cached, fetchQuery returns its data without reaching the encoder. Detect a shadowed hasOwnProperty before dropping undeclared fields and key the argument as refused.

Useful? React with 👍 / 👎.