Module journal 

Local Approval Use Journal – v0.9.9 PR 2.

Per-workspace append-only memory of consumed Approval Grants. The journal turns the v0.9.6 “package-local only” replay finding into a local-journal replay finding: with this module wired through, verify can say “use 1/1 – local Approval Use Journal passed” instead of “no global ledger consulted.”

Scope of THIS PR:

• journal storage (records/, heads/, indexes/, locks/)
• append-only writes with file lock + atomic temp+rename
• hash chain via previous_record_digest
• read-only check_replay lookup
• verify_integrity chain walk
• rebuild_indexes from records (records are truth)

Out of scope (later PRs):

• consume-before-action wiring inside treeship attest action (PR 3)
• package export of journal records (PR 4)
• Hub checkpoint signing (PR 6 scaffold)

Privacy rules baked into the layout:

• nonce_digest, never raw nonce
• no commands, prompts, file contents, bearer tokens, or API keys are stored. The journal answers the single question “has this (grant_id, nonce_digest) been consumed before, and if so how many times?” – everything else stays in the signed grant + receipt where it already is.

Structs

Head

Journal

Directory layout under .treeship/journals/approval-use/.

Enums

JournalError

Functions

append_checkpoint

Append a JournalCheckpoint over a contiguous range of prior records.

append_revocation

Append an ApprovalRevocation. Sibling of append_use.

append_use

Append an ApprovalUse to the journal. The caller MUST set previous_record_digest to the current head’s digest on the incoming record; we re-validate before write. record_digest is computed from the canonical form and stamped on the stored record.

check_replay

Check whether (grant_id, nonce_digest) has already been consumed, and how many times. Returns a ReplayCheck carrying the strongest level the journal can speak to:

find_use_for_action

Find the recorded ApprovalUse for an already-signed action. Returns the matching use record plus a ReplayCheck that answers the verify-time question – “is the recorded use within max_uses?” – as opposed to check_replay’s consume-time question – “would the next use exceed?”. The two questions look the same but have different boundary semantics:

list_uses_for_grant

Every ApprovalUse for grant_id. Reads the by-grant index, then loads each record. Quiet on missing journal.

rebuild_indexes

Delete and rebuild every index from the records directory. Records are truth; indexes are cache. Useful as a recovery tool when an index file is corrupt or out of sync.

reserve_use

Atomic check-and-append for the consume path. Combines check_replay + append under a single journal lock so concurrent consume paths cannot bypass max_uses via TOCTOU race.

verify_integrity

Walk every record in order, recompute each record_digest, and check that each record’s previous_record_digest matches the prior record’s stored record_digest. Returns the number of records walked or an error pinpointing the first integrity failure.