Module session_journal 

Session snapshots with opt-in delta journals and durable checkpoints.

New journal snapshots carry a storage-only _journal_generation UUID; v2 journals replay ONLY against that exact generation. Publishing a new snapshot is the logical commit, even if a crash leaves the old journal. Unmarked legacy snapshots still accept v1 journals. Their pre-migration crash ambiguity cannot be repaired retrospectively. Old binaries can read the Session-shaped snapshot but cannot replay v2 deltas; downgrade/export should first fold the journal with a JSON save using this implementation.

Normal JSON saves retain the legacy bytes when no journal/generation has ever been present. Once bound, all snapshot replacements (including JSON saves) rotate the generation so leftover journals cannot resurrect history. Metadata is not a Session field: serde exports/mirrors ignore it. Stripping it loses v2 deltas, rather than applying a potentially unrelated journal.

Journal appends write O(delta) bytes; a streaming history hash checks the entire saved prefix for edits (O(history) CPU, no history-sized allocation). Journal-bound snapshot rotation syncs the snapshot directory before removing old deltas; JSON-only normal saves retain their prior best-effort behavior. Durable saves always publish a full snapshot and sync through cleanup. Errors can follow logical commit; callers must stop and reload/retry, not assume rollback. All saves of one session must be externally serialized; no multi-writer transaction is offered.

Private 0700/0600, no-symlink handle-relative I/O is preserved on Unix. Normal saves retain the documented non-Unix best effort; durable saves fail closed there rather than pretend directory fsync is supported.

Structs

JournalMetaTail

Freshest journaled metadata, read from a bounded tail window — lets session listings stay accurate without parsing the full journal.

SaveReceipt

Machine-readable receipt for benchmarks and delta-proportionality tests.

SessionDirEntry

One strictly-resolved directory entry for session listings.

Enums

SaveMode

How a save landed on disk.

SessionPersistence

Which on-disk persistence strategy Session::save uses.

Constants

JOURNAL_SCHEMA_VERSION

Journal record schema version (line-level "v" field).

JOURNAL_SNAPSHOT_MIN_BYTES

Journal size floor before a periodic snapshot is forced.

JOURNAL_SNAPSHOT_RATIO

A snapshot is due when the journal outgrows snapshot / RATIO (bounded write amplification: large sessions stretch the threshold proportionally).

MAX_PERSISTED_READ_BYTES

Hard cap on any single persisted-session artifact read (snapshot or journal). Reads are bounded on the OPENED handle; an artifact past the cap is refused rather than slurped.

Functions

delete_session_files_in_dir

Remove a session’s snapshot, journal AND turn draft (session_draft) (compaction rollback, retention). Idempotent — missing files are not errors.

journal_meta_tail

Freshest meta record from a bounded journal tail window, for listing freshness without a full journal read. None when no journal, no complete supported-version meta record, or a refused (non-confined) artifact — a symlinked journal discloses nothing.

journal_path

sessions/<id>.journal — single-extension name so the session id stays the file stem (chain-head protection and retention pair on the stem).

load_session_in_dir

Load <id>.json and, when a journal exists, replay it idempotently. Old-format sessions (no journal) load exactly as before; a session with a torn or stale journal recovers to its last consistent state. Both reads are confined nofollow bounded handle reads (fix1 I1).

save_session_durable_in_dir

Blocking body of Session::save_durable: a full generation-bound snapshot in either mode. Fsync the file, rename it, fsync the directory, then clean up the journal and fsync the directory again. Snapshot rename is the logical commit; any later error is returned without rollback. Retry/reload is safe with stale journals. Concurrent saves of the same session are NOT supported.

save_session_in_dir

Persist under the configured mode. Journal-bound replacement syncs the snapshot directory before discarding old deltas; normal JSON-only saves do not promise directory durability. Use save_session_durable_in_dir for a full context-head barrier. Snapshot replacements are generation-safe in both.

session_dir_entries

Enumerate the sessions dir through the SAME strict handle resolution as every other T35 operation (fix2): handle-relative readdir + fstatat(AT_SYMLINK_NOFOLLOW) — a symlinked ancestor refuses, a missing dir lists empty, and entry mtimes are of the entries themselves, never symlink targets.

snapshot_due

Snapshot threshold: journal bytes ≥ max(256 KiB, snapshot / 4).