docs: correct nine claims the code does not deliver

[b2m9]

A follow-on from #13. Reviewing the reference-idempotence overclaim surfaced the same defect class elsewhere, so I swept the whole README and AGENTS.md. No behavior change — documentation, one comment, one test.

Nine statements were stronger than the implementation. Each was verified against running code before and after the edit.

Claim	Reality
"cost scales with the delta, not with the state"	a one-field delta onto a 500-field object reads 501 fields — every changed object is shallow-copied in full, ancestors included
a replace path "swaps in whatever the delta supplies without inspecting it"	at items[], reconciliation validates the item before the boundary applies
replaced values "never scanned"	same exception
"keyfold does not inspect untrusted data"	it reads keys, values, identities and tombstones
a keyBy policy on the wrong shape "usually throws"	a plain object there merges ({a:1} + {b:2} → {a:1,b:2}); only an array reaches reconciliation
KeyfoldMergeError covers "base or delta data [that] violates the contract"	much is undetected; a recursed cycle throws native RangeError
"a tombstone carrying patch fields throws"	unsafe keys on a tombstone are ignored
DELETE_TOKEN "can no longer be stored as ordinary field data"	it survives inside a replacement or an unkeyed array — as the Deletes section already said
"matching items merge in place"	read as mutation

The AGENTS.md constraint was titled "Work remains delta-proportional" — the same false claim, in the file a future writer would consult to restate it. It is now named for what it actually forbids: never recursively traverse an unmentioned subtree.

Test

One new test pins the cyclic-input limit at all four positions, since the README now makes a specific promise about it: a cycle in an unmentioned branch, at a replace path, and inside an unkeyed array all pass through untouched, while one the fold recurses through raises RangeError.

Review

Three rounds with GPT-5.6-sol, and it caught me overcorrecting in each one — "carries a replacement", then "never validates", then "unsafe keys are ignored everywhere". Precise statements about these semantics are genuinely hard to write, which is the honest argument for pinning them with tests rather than prose wherever possible.

Not included: the replacement-equality premise at README:197, which belongs with #13 since that PR rewrites the adjacent line.

118 tests, vp run check green.

---

Summary by cubic

Corrects nine documentation claims that overstated keyfold semantics and renames an agent constraint; behavior is unchanged. Adds a test pinning the documented cycle limit.

• Docs sweep in README.md and AGENTS.md; one new test in test/merge.test.ts; no runtime changes.
• Cost: merges never traverse unmentioned subtrees; changed plain objects are shallow-copied across own fields; keyed reconciliation indexes delta, scans base, and builds a candidate list.
• Replacement boundaries: replacement contents are never traversed; at items[], reconciliation still reads identity and tombstone form before the boundary applies.
• Keyed lists: a keyBy policy engages only when the delta at that path is an array; a non-array delta merges; when the base is an array, base items are validated too.
• Errors: KeyfoldMergeError covers only detected keyed-list protocol violations; other invalid inputs may pass; a cycle the fold recurses through raises native RangeError.
• Deletes: unsafe keys on tombstones are ignored; DELETE_TOKEN remains data inside replacements and unkeyed arrays.
• Wording fixes: “matching items are folded at their existing positions” (avoid mutation wording); agent constraint renamed to “Never recursively traverse an unmentioned subtree.”
• Cycle behavior: new test confirms pass-through for cycles in unmentioned branches, at replace paths, and in unkeyed arrays; recursion into a cycle throws RangeError.

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

[cubic-dev-ai]

No issues found across 3 files

_{Re-trigger cubic}