Documentation / guides
Safe Boundaries
Describe the safe transcript boundaries used by compaction.
Compaction changes the actor-owned context only at a safe boundary. A pending request freezes the current input inbox so a new user message cannot start or fold while the compaction obligation is unresolved.
Boundary kinds
The control actor consumes a pending attempt only at compactionBoundaryStep or
compactionBoundaryTurn. It first applies a bounded snapshot of priority
controls. Shutdown and interrupt signals outrank starting compaction. Once an
attempt is in progress, another boundary does not start a second one.
%%{init: {"theme":"dark"}}%%
flowchart TD
I[input or control queue] --> B{Step or Turn boundary?}
B -->|no| Q[keep pending]
B -->|yes| P[bounded priority snapshot]
P --> X{shutdown or interrupt?}
X -->|shutdown| S[reject shutting down]
X -->|interrupt| R[reject interrupted]
X -->|no| C[publish Started, then execute]
C --> T[durable terminal clears block]Proof: boundary arbitration and safe-boundary tests.
Bounded control lanes
One Loop has one coalescing compaction slot and at most 64 waiter commands. Duplicate command IDs return a duplicate admission. Additional waiters return lane-full and later receive typed rejection through the control failure path. The priority control snapshot is capped at 8 commands; the ordinary FIFO input lane is not unboundedly drained at a boundary.
Compaction control is separate from the ordinary user-input queue. The pending slot blocks new input until a durable terminal event clears it.
Proof: control capacities and capacity tests.
Publication boundary
CompactionStarted is published before the executor is invoked. If start
publication fails, the executor is not called and the runtime does not invent a
false CompactionRejected. Fatal journal or coordination failures travel as
typed infrastructure errors. After successful start publication, exactly one
durable terminal event resolves the attempt.
Proof: compaction publication ordering and start publication tests.