plan: A4 compaction — phase 3 — trigger + summarizer step + seeding (source #552) #950

Plan header

Intent lock

In scope: the compaction trigger — the route computes the fold budget (consuming #944's foldBudgetTokens) + decides to compact; passes a serializable compact: { cutIndex } into start(); the workflow runs a new 'use step' summarizer before the first model round; the loop seeds [summaryRow, ...retainedTail, user].

Out of scope: persist seam (Phase 2 landed it), docs (Phase 5).

Forbidden: mid-turn compaction · Wasm-running summarizer · dual DOM chat · a second window-source fork off #944 · adding a maxOutputTokens knob.

Depends on

Phase 2 merged (needs compactionPointer carrier + checkpoint persist + route checkpoint-preference read).

Current baseline (live code @ main)

Design

Trigger (route, pre-start). After the route rebuilds the seeded projection and computes foldBudgetTokens(windowMap, byok.modelId) (#944), it decides to compact when shouldCompact (Phase 1 compactionBudget.ts) is true — i.e. the seed that would otherwise be trimmed by trimModelMessagesToBudget still carries a meaningful pre-checkpoint span worth summarizing instead of blind-truncating. The route runs findCompactionCut (Phase 1) over the built rows. On a clean cut, it passes compact: { cutIndex } into start() as a serializable arg. On no clean cut (single-turn span) → fall back to today's trimModelMessagesToBudget behavior; never compact on a lie, never block the turn.

Summarize (first step). lib/workflows/compactionStep.ts — new 'use step'. When TurnWorkflowArgs.compact is set, the workflow invokes compactionStep before the first model round. The step feeds the compaction span (rows.slice(0, cutIndex), each tool result already truncated to MODEL_MSG_TOOL_RESULT_MAX_CHARS) to one generateOneRound on the session's modelId (BYOK re-resolved in-step, same 1h wall-clock discipline, same step maxDuration) with a locked summarizer system prompt. It returns { summary, filesTouched }. Failure → fail-open: seed from the full (trimmed) projection, never a doomed turn.

Seed (loop). lib/workflows/turnWorkflow.ts + lib/workflows/turnLoop.ts — accept the serializable compact arg; the loop seeds [summaryRow, ...retainedTail, user] where summaryRow = renderSummaryRow(summary, filesTouched) (Phase 1) and retainedTail = rows.slice(cutIndex) re-paired. The persona snapshot + working notes + skills catalog still ride the system prefix independently — the checkpoint only replaces the message history.

Persist linkage. The loop's terminal persist passes the compaction result to derivePersistFold; the Phase-2 seam writes the checkpoint Blob + patch.compactionPointer.

Caps table

No existing cap changed → no human gate.

Implementation order

1. app/api/turns/route.ts — compute shouldCompact + findCompactionCut; pass compact?: { cutIndex } into start(); prefer compaction over blind trim when a clean cut exists.
2. lib/workflows/compactionStep.ts — new 'use step' summarizer round.
3. lib/workflows/turnWorkflow.ts — add serializable compact to TurnWorkflowArgs; invoke compactionStep pre-loop.
4. lib/workflows/turnLoop.ts — seed [summaryRow, ...retainedTail, user]; route compaction result into derivePersistFold.
5. Unit tests.

Testing

Minimum locked for DoD: 1, 2, 3, 5, 7.

Definition of done

• Maps to parent checklist: "Compaction triggers on the selected model's window − reserve (consumed from plan: context-window fold budget (A3, source #551) #944)" + "Wasm never runs the summarizer"
• Cloud ops: N/A — no Production mutate
• Living docs: N/A this phase (parent Phase 5 owns docs)
• No existing cap value changed; no human gate
• The summarizer round runs in a step server-side; Wasm untouched; no bridge/protocol change

Corrections / refinements vs parent

IMPLEMENTED (2026-09-06) — PR #955: #955

All locked rows shipped: pre-trim trigger (review-note 1), fail-open summarizer + seed [summaryRow, ...retainedTail, user], checkpoint writer wired into derivePersistFold (review-note 2), COMPACTION_SPAN_MAX_BYTES (new cap, no human gate), no maxOutputTokens. Gates: typecheck clean, full vitest 181 files / 3483 tests green. Awaiting adversarial review.