Module journal 

Validated-writeback journal (ClawVM §3).

Every lifecycle transition that touches durable state — compaction, save, reset — goes through a three-phase transaction:

1. Staging. The caller proposes a typed Op; the journal reserves a TxnId and records the staged entry.
2. Validation. The caller checks schema, provenance, scope, non-destructive semantics, and page-invariant compliance. The outcome is recorded.
3. Commit. A validated transaction commits; a rejected one stays in the journal with its reason code and does not mutate the owning state.

Rejections are not errors — they are load-bearing evidence that the enforcement layer caught a would-be regression. ClawVM’s LRU ablation shows fault elimination comes from this structural contract, not from clever selection heuristics.

Format

The journal is an append-only JSONL file named <session-id>.journal.jsonl co-located with the session JSON. Each line is a JournalEntry — cheap to tail, safe under concurrent append, and inspectable by hand during debugging.

Phase A scope

This module delivers the type layer plus the in-memory transaction state machine. The consumers (compaction writeback, page-invariant validation hooks) come online in Phase B alongside DerivePolicy::Incremental.

Examples

use codetether_agent::session::journal::{JournalEntry, Op, RejectReason, WritebackJournal};

let mut journal = WritebackJournal::new("session-42");
let txn = journal.stage(Op::Compaction {
    before: 120,
    after: 24,
});
journal
    .commit(txn)
    .expect("no pending validation => commit is allowed");
assert_eq!(journal.entries().len(), 2);
assert!(matches!(journal.entries()[1], JournalEntry::Committed { .. }));

Structs

TxnId

Opaque handle returned from WritebackJournal::stage and required by [WritebackJournal::validate] / WritebackJournal::commit.

WritebackJournal

In-memory, per-session writeback journal.

Enums

JournalEntry

A single line in the journal.

Op

Typed operation being journalled.

RejectReason

Reason codes for a rejected writeback.