plan: A4 compaction — phase 5 — living docs (source #552) #952

Plan header

Review notes (2026-09-07)

Verdict: HANDOFF-READY — all findings are resolved in this issue. Phase 4 is merged through PR #956, so this phase documents shipped behavior only. No cap is added, raised, or lowered; no human cap decision is required.

Intent lock

In scope: capture the shipped compaction behavior in the four living-document surfaces assigned by the parent. The text must be timeless product/agent truth: it explains what the current system does, its ownership boundaries, data safety, and existing limits without phase/issue history.

Out of scope: application code, tests, migrations, deployment configuration, schema/Redis/Blob data changes, cap changes, and visitor-front-door or secret-policy changes.

Forbidden: phase/issue theater in product docs; “see issue #NN” as an explanation; a simplified seed-order statement that loses the honest-live-projection preference; laptop-primary ops notes; describing compaction as deleting transcript or model-history objects; suggesting that the Wasm harness or DOM host runs the summarizer.

Depends on

Phase 4 is merged (PR #956), following merged Phases 1–3. The documentation therefore describes current main behavior, not an intended or speculative design.

Current baseline (live code @ main)

Documentation design

docs/session-model.md — new timeless Compaction section

Document the model-facing compaction lifecycle alongside the existing durable-turn model-messages section:

1. Checkpoint carrier and durability. meta.compactionPointer is only a Redis-safe, session-bound object id. Its Blob object holds { summary, filesTouched, retainedTail }; the checkpoint body never rides envelope meta. A host flatten envelope PUT omits this worker-authored key, and the store copy-forwards the existing valid value; a new successful compaction replaces it. The transcript and earlier model-messages objects remain retained in Blob — compaction changes the model seed, not stored history.
2. Trigger and cut. At POST /api/turns, the backend resolves the selected model’s joined catalog window and its existing fold budget, evaluates the pre-trim seed, and compacts only when that seed exceeds the budget and a safe user-turn boundary exists. The cut is re-paired so an assistant tool call cannot be separated from its tool result. If there is no legal cut, the established route trim remains the fail-open fallback; no turn is blocked.
3. Server-only summary. The Workflow runs one tools-off summarizer step before the first normal model round, with the selected model and in-step authorization. The Wasm harness and DOM host do not summarize, receive credentials, or gain a new bridge/protocol surface. A failed, empty, or unusable summary fails open to the ordinary bounded seed and must not create a fabricated checkpoint.
4. Exact next-turn seed selection. Validate every pointer against the requesting {tenantId, userId, sessionId} and re-validate/re-pair decoded rows. Prefer a valid model-messages object when its first row is the labeled compaction honesty row (the post-compact live warehouse, preserving work done after compaction); otherwise prefer a valid checkpoint rendered as [summaryRow, ...retainedTail]; then use an ordinary valid model-messages projection; finally fall back to the host’s legacy promptHistory sidecar. Unbound, missing, malformed, or invalid objects do not seed another session and fall through safely.
5. Honesty. The summary is a user-role row beginning exactly Summary of earlier session (compacted, not live assistant prose):; it is context, never a claim that the assistant just said it live. filesTouched supplies the bounded Files read/modified: context.

Update the reserved-meta/key table and full-replace exception text to include compactionPointer with the other worker-authored pointers, including its clear/copy-forward behavior. Keep explanations timeless; do not mention plans, phases, PRs, or issue numbers.

docs/harness-limits.md — compaction limits rows

Add a Compaction limits row/table near the existing durable model-message rails. State units, carrier, and behavior, not only constant names. Distinguish a Blob-object ceiling from workflow-start-argument and summarizer-input ceilings. Cross-reference the existing model window/fold-budget and model-seed rails rather than duplicating their values.

docs/feature-divide.md — ownership table

Add a durable-turn/compaction ownership row, or extend the current durable-turn row, that makes the split explicit: Vercel backend reads the bound seed, decides/cuts, runs the server-side workflow summary, and writes the checkpoint; DOM remains the thin submit/bridge host; Wasm remains the primary transcript/composer and never runs the summary or accesses Blob/Redis/Gateway credentials. Preserve the no-dual-chat rule.

AGENTS.md — timeless “Where to change” entry

Add one compact, durable table row covering the compaction seam: lib/agent/compaction*.ts, app/api/turns/route.ts, lib/workflows/{compactionStep,turnLoop}.ts, lib/agent/turnPersistSeam.ts, and lib/sessions/sessionStore.ts. State the pre-trim selected-model trigger, server-only tools-off step, session-bound meta.compactionPointer, honest summary row, copy-forward, and logical-not-physical deletion rules. Reference the docs by name, not phase/issue history. Do not duplicate the full implementation map already present elsewhere in AGENTS.

Other durable surfaces reviewed

Caps table

This documentation phase adds and changes no cap. It documents these already-shipped values exactly; the existing CONTEXT_* fold-budget and MODEL_MSG_SEED_* rails remain documented at their own locations and are not redefined here.

Cap governance: all values above already exist on main. This plan only documents them; it raises, lowers, adds, and removes none. No human cap decision is requested.

Implementation order

1. Update docs/session-model.md with the exact durable checkpoint, trigger, fail-open, seed-selection, honesty, and copy-forward semantics.
2. Add the six existing compaction-cap rows to docs/harness-limits.md, cross-linking existing model-window/seed rails instead of duplicating or changing them.
3. Update the docs/feature-divide.md ownership table to place compaction fully on the Vercel backend and explicitly exclude Wasm/DOM summarization.
4. Add one concise timeless compaction-seam entry to the AGENTS “Where to change” table.
5. Review the complete documentation diff for source accuracy, relative-link correctness, no phase/issue/process language, and consistency across all four surfaces; then run the required repository gates in a cloud agent workspace or CI.

Testing / verification

Definition of done

• docs/session-model.md accurately documents checkpoint carrier, session binding, pre-trim trigger, safe/re-paired cut, fail-open behavior, honest summary row, exact seed selector, and logical compaction without physical deletion
• docs/harness-limits.md documents all six existing compaction limits with units, code locations, and Blob/workflow carrier distinction; no cap value changed
• docs/feature-divide.md assigns compaction entirely to the Vercel backend and preserves Wasm-primary/no-dual-chat ownership
• AGENTS.md has one concise, timeless compaction seam entry including meta.compactionPointer and copy-forward rules
• The documentation contains no phase/issue/PR narrative; README.md, SECURITY.md, and .env.example remain N/A for the reasons above
• Source-to-doc review, link/diff review, npm run typecheck, npm test, and npm run build are green in a cloud agent workspace or CI and recorded in the PR
• Parent Phase 5 and parent living-doc DoD items can be checked off after the merged documentation PR
• Cloud ops: N/A — no Production mutate

Parent adherence

Corrections / refinements vs parent

IMPLEMENTED (2026-09-07) — PR #957: #957

All locked doc rows shipped in the four parent surfaces: docs/session-model.md (timeless Compaction section + compactionPointer reserved-key carrier), docs/harness-limits.md (all six existing caps incl. COMPACTION_START_MAX_BYTES), docs/feature-divide.md (backend-only ownership), AGENTS.md (one compaction-seam row). Source-to-doc review done against live main (seed preference route.ts:498–505, caps sessionCloudCaps.ts:631–721, fail-closed checkpoint write, fail-open loop). Gates: typecheck clean, full vitest 177 files / 3527 tests green, npm run build green in this cloud workspace; git diff --check clean; all new relative links resolve. No caps changed; no Production mutate. Awaiting adversarial review.