Module session_draft 

The in-flight turn draft: sessions/<id>.turn.

The session snapshot is saved at every round boundary (the engine’s round checkpoints), so it always holds a VALID history. What it cannot hold is the response still being streamed — partial text is not a valid history entry until the turn stops. This small draft carries it instead:

• written when a turn starts (the “turn is open” signal), then at most once a second while text streams, and removed when the turn ends;
• base_len = how many messages of the saved history the in-flight response follows, so a draft that outlived its round is recognised as stale;
• partial_text = the text the model has streamed so far in that response (text only: unsigned thinking and unfinished tool calls are never replayable).

Only the holder of the session lock writes a draft, and only the holder reads one back: a draft found when the holder loads the session means the previous holder died with a turn open, and it is folded into history as a real assistant message plus an interruption marker (agent_engine::engine::interrupt). The session actor’s background writer (agent_engine::session::persister) applies draft writes and removals in order with the snapshot saves: the draft is removed only after the history that ends its turn is saved.

Separate from the snapshot on purpose: O(partial text) bytes per write in every persistence mode, and the snapshot bytes stay exactly those of the last completed round. Same confined, private (0600), atomic writes as the snapshot. The .turn name keeps the session id as the file stem and is invisible to *.json listings; deleting a session (and retention) removes its draft with it.

Structs

TurnDraft

Constants

TURN_DRAFT_MAX_FILE_BYTES

Upper bound on a draft file read at load: the capped text JSON-escaped in the worst case (\u00XX = 6 bytes per input byte) plus framing. A larger file was not written by Synaps and is rejected unread.

TURN_DRAFT_MAX_TEXT_BYTES

Upper bound on persisted partial text (a response is bounded by the model’s max output tokens; this only guards pathological streams).

Functions

read_turn_draft

Read the draft for id. Ok(None) when absent (the normal case); an InvalidData error for an oversized (TURN_DRAFT_MAX_FILE_BYTES) or malformed file.

remove_turn_draft

Remove the draft for id. Idempotent.

write_turn_draft

Atomically (re)write the draft for id (0600, confined).