Define and test the §4 snapshot-compaction contract

[christian-byrne]

XREF-1 current-state verification

Verified 2026-08-30 against comfy-multi-player origin/main at 5f880f6c0e534d94dd3d381c4f1cee69fbbd0dad and GitHub PR state.

PR #33 merged on 2026-08-21, so the original instruction to resolve this risk before merge is stale. The residual gap remains:

• docs/multiplayer-schema.md §4 requires host snapshot compaction when bookkeeping exceeds 25% of document bytes or 10,000 __applied entries.
• The same section records the digest representation at about 32% bookkeeping in the measured session, so the percentage trigger is crossed during ordinary operation.
• src/doc.ts explicitly says per-actor watermark compaction is not implemented and delegates snapshot compaction to the host. The package exposes no tested host-facing compaction contract.

The bounded SHA-256 digest from PR #33 fixed unbounded payload-sized entries, but it did not bring bookkeeping below the schema trigger or implement that trigger. __applied therefore remains O(ops). This is no longer a merge blocker for an already-merged PR; it is current implementation debt requiring a shared-package contract plus consumer-host work.

Upstream tracking: #130

Glossary

• __applied: replicated map used to recognize an already-consumed operation ID.
• Compaction: minting a fresh document epoch that preserves semantic state while discarding bounded historical bookkeeping.
• Host: the merge-authority process that owns the canonical shared Yjs document.
• PR fix: reject op id payload reuse #33: the merged payload-digest change, fix: reject op id payload reuse #33.

[christian-byrne]

Current-state __applied growth and ceiling evidence, verified 2026-08-31 against comfy-multi-player@9f1a555cd5502755c626bf50c2e5f575a0340a5d (release 0.2.1) and cloud@623c3bd636346189b7c50b4fa8c7bfe1c826c62d:

Growth characterization:

• __applied is an unbounded root Y.Map keyed by creator-minted op_id; each value is the 64-lowercase-hex SHA-256 digest of the complete canonical op. Legacy numeric 1 values remain accepted as duplicates.
• Every accepted unique op consumes one entry, including delete-wins and LWW-dropped semantic no-ops. Exact duplicate retries, rejected envelopes, and op_id_reuse conflicts do not grow it.
• No current package path deletes, clears, prunes, watermarks, or re-mints this map. The 10,000-entry / 25%-of-doc trigger in schema section 4 is target design, not implemented behavior.
• The evidenced encoded cost is approximately 96-112 bytes per entry. Use 112 B/entry as the conservative average; it is not a source-level constant because Yjs structural overhead and workload shape vary.

Ceiling model:

• Cloud's MaxDocFrameB64Len = 8 << 20 is an 8 MiB base64-field limit, approximately 6 MiB binary, not an 8 MiB binary snapshot limit.
• At 112 B/entry, the ledger alone reaches that binary budget near 56,173 entries. The optimistic edge of the measured range is 65,536 entries at 96 B/entry, so the ledger-only cap estimate is about 56.2k-65.5k consumed ops.
• The older whole-document growth measurement gives a tighter practical cold-subscribe ceiling: (6,291,456 - 268) / 134.5 ~= 46,775, so about 46.8k consumed ops for the measured minimal set_widget workload.
• At 100 accepted unique ops/minute, that whole-doc estimate reaches the catch-up cap in about 7.8 hours. A 24-hour workload at that rate would produce about 144,000 consumed ops without compaction.
• To keep the ledger under 50% of the 6 MiB binary catch-up budget, the conservative threshold is about 28,086 entries; for the measured whole-doc slope, 50% lands around 23,386 consumed ops. That makes 23k-28k the useful decision band, while the schema's existing 10,000-entry trigger remains below both estimates.

Boundary/caveat: this evidence characterizes current growth and transport pressure only; it does not select a compaction policy or establish a guaranteed universal failure threshold. Op mix, identifier lengths, churn/tombstones, add/delete-heavy workflows, and graph growth can move the boundary earlier. Deleting old __applied keys inside the same long-lived Y.Doc also may not reclaim encoded Yjs history; any implementation for this issue still needs a lineage-safe contract preserving dedupe semantics and dispatching doc_reset before new-lineage projection.

Source artifacts: reports/audit/current-applied-map-growth.md and reports/audit/current-applied-map-ceiling.md in the in-app-agent program repo.