Redesign post-compaction ledger rebuild without a compaction hook

[frap129]

Question

The v1 compaction flow (experimental.session.compacting → rebuild Working-context paths + delivery-ledger identity) has no v2 hook equivalent. Redesign it on v2 primitives:

• Candidate sources: events (session.next.compaction.started/delta/ended, session.compacted) and ctx.session.context({ sessionID }) reads at dispatch time.
• Chosen posture (decided during charting): degraded-then-healed — after compaction, durable rules may re-append once while the ledger rebuilds lazily; document as known beta limitation.
• Deliver: (1) pick the mechanism (event listener vs lazy rebuild at context-hook time), (2) implement ledger rebuild + Working-context projection from v2 message shapes, (3) update src/session/ modules (message-extraction, working-context) to parse v2 message/part shapes, (4) note the limitation in README + map when done.

[frap129]

Resolution

Mechanism chosen: event listener for invalidation + lazy revision-guarded ledger re-decode at durable-turn time. No eager rebuild and no new hook surface.

API verification (beta-18999)

The live v2 event surface (via @opencode-ai/client v2 generated types, which the plugin's event domain wraps) has session.compaction.started / session.compaction.ended / session.compaction.failed, all carrying data.sessionID (started/ended also carry reason: "auto" | "manual"; ended carries the summary text + recent). session.compacted is a different event (session-list/properties shape) — not the compaction lifecycle event. The existing listener names were already correct; the redesign is in the post-event flow, not the subscription.

What changed

1. Ledger heal on the first post-compaction durable turn (src/delivery/rule-delivery.ts, delivery-state.ts): markCompacted now sets a pendingCompactionHeal flag alongside needsRescan. Previously deliverDurableTurn deferred unconditionally while needsRescan was set, so the heal only landed on turn 2 with a transient duplicate in between. Now the first durable turn after compaction re-decodes history once, guarded by ledgerRevision (a mid-read re-invalidation discards the decode and leaves the heal pending). This implements the decided degraded-then-healed posture exactly: durable rules dropped by the compaction summary re-append once, on the next durable turn, not every turn.

2. Seed-path separation (seedFromHistory): needsRescan from unavailable history still defers without per-turn re-reads (preserved contract); a dispatch-supplied message source may still replace the ledger from supplied messages unless a compaction heal is pending (the heal's own guarded re-read wins, preventing a clobber).

3. Working-context projection made event-driven (orchestrator.ts, session-store.ts): the orchestrator's private compactedSessions set moved to a compacted flag on SessionState, set by the session.compaction.started/ended handler and consumed exactly once by the next session-context dispatch (one-shot, survives any store churn). Projection remains transient (never persisted).

4. No further changes needed for v2 message parsing: src/session/message-extraction.ts (v2 tool parts with state.input/output) and the src/session/v2-messages.ts adapters (fromSessionMessages, fromContextMessages, synthetic-message metadata at message level) landed with the Port server entry + orchestrator to v2 plugin contract #71/Port delivery engine to session.synthetic + context hook #72 work and already parse the v2 shapes the projection and ledger decode consume.

5. Test infrastructure (test-fixtures.ts): the mock event.subscribe now drains an injectable queue with a pushEvent() wake, so tests drive compaction through the runtime's real event loop instead of bypassing it.

Known beta limitations (documented)

• session.compaction.failed is not handled: a failed compaction changes nothing (history intact), so no state action is correct; noted in case the beta later emits compensating events.
• Rules whose owning synthetic messages survive compaction are never re-appended (ledger keys persist) — intended.
• Re-append happens at the next durable turn; tool-only continuations before that see the deduped (possibly rule-less) ledger — the accepted degraded window.

README updated: "How It Works" item 8 (Compaction Persistence), hook section 5, Experimental API Notice (placeholder language removed), and a stale v1 message.removed reference corrected to session.revert.*.

Verification

aube run lint clean, aubx tsc --noEmit clean, aube run test:run 548/548 passing — including two new event-driven integration tests: compaction re-appends dropped durable rules exactly once (asserting the second post-compaction turn stays silent), and the projection rides exactly one dispatch.

[frap129]

Resolved: event listener + lazy revision-guarded ledger heal, durable re-append exactly once post-compaction.