docs: scope the reference-idempotence promise to what holds

[b2m9]

Item 2 of the four flagged design choices. The verdict there was keep the behavior, fix the claim — so this is documentation, one test comment, and one law. No behavior change.

The defect

The Semantics list contradicted itself in consecutive bullets:

:195 — replaced values count as unchanged only when they are the very same reference
:196 — Every valid delta is deterministic and idempotent: re-applying the same delta returns the previous result by reference, so a store can drop duplicate frames with one equality check

Only the first is unconditional. The second holds for the same delta object — but websocket reducers are the headline use case in the intro, and they decode every frame afresh.

Where the line actually falls

A replacement is unchanged only under Object.is. Ordinary JSON parsing satisfies that for primitives and never for objects or arrays. Measured:

re-decoded frame carries	same reference?
scalars only	✅
keyed list	✅
replace path → string / number / null	✅
replace path → object / array	❌
unkeyed array	❌

All are still toEqual; only the reference churns.

My first attempt drew the line at "carries a replacement," which review caught as wrong — a replace path holding a primitive costs nothing. The line falls at what decoding allocates.

Changed

Three sites, because the claim lived in three places and the third is the one that would regenerate it:

• README Semantics bullet — states the Object.is rule, then the ordinary-JSON consequence, then the dedup guidance scoped to when it actually works.
• test/laws.test.ts — the comment inside "re-applying the same delta returns the same reference" carried the overclaim as the law's own justification. It now says the law applies the same delta object twice and points at the boundary.
• AGENTS.md — the "deterministic and idempotent" constraint had the same unconditional wording, plus an explicit "Do not promise more than that."

Plus a law, a re-decoded frame keeps the reference only for Object.is-equal replacements, pinning three cases: merged values re-decoded are toBe; an unkeyed array and a configured replace path are not.toBe but toEqual; a primitive at a replace path is toBe. Both replacement routes are covered so neither can start comparing by value unnoticed.

Review

Two rounds with GPT-5.6-sol. Round one caught the "carries a replacement" overcorrection; round two grounded the rule in Object.is rather than allocation, added the object-valued replace case, and replaced a cast of invalid data into Delta<Shape> with a dedicated typed merger.

118 tests, vp run check green.

---

Summary by cubic

Scopes the reference-idempotence claim to what actually holds and pins the boundary with a law; no behavior change. Prevents overstating dedup-by-reference for re-decoded frames (e.g., websocket reducers).

• README: states Object.is as the equality rule for wholesale replacements, so primitive replacements are unchanged without shared refs; scopes idempotence to re-applying the same delta object and notes re-decoded frames keep refs only when all replacements are Object.is-equal (primitives, not objects/arrays). Dedup by a single equality check works only while no replacements are objects/arrays.
• AGENTS.md: aligns the constraint with the same scope; explicitly says not to promise more.
• test/laws.test.ts: updates the justification in the same-delta-object law; adds a law that fixes the boundary: merged values remain toBe after re-decode; unkeyed arrays and object-valued replace paths are not.toBe but toEqual; primitive replace remains toBe.

^{Written for commit 1ff0ce5. Summary will update on new commits.}

[cubic-dev-ai]

No issues found across 3 files

_{Re-trigger cubic}