Module transaction_journal

Expand description

The schema-version-2 journal records of one commit transaction and their filenames. What: The schema-version-2 journal records of one commit transaction and their filenames; encoding and parsing live in transaction_journal_encode.rs and transaction_journal_parse.rs. Why: State files are created exclusively and never rewritten, so a crash leaves the newest complete state readable; recovery in either wrapper reads the records the other wrote (src/policy-engine/commit-transaction-journal-states.ts and commit-transaction-journal-parse.ts). Every missing or mistyped field fails closed with the record and field named.

In TS you’d write (pseudocode):

const preparing = parsePreparingRecord(bytes); await writeJournalRecord({ directory, filename, record });

Structs§

AddedPath: What: One policy-added path, or one selected path whose worktree copy receives settled bytes: its mode, the blob before the commit and the blob the commit lands. Why: After landing, the worktree copy is replaced only while it still holds the original.
FileIdentity: What: A file identity recorded without hashes: device and inode as decimal text. Why: Recovery proves an artifact is the exact file written, not one put in its place.
IndexLockRecord: What: index-lock-<n>.json: identity of the real index.lock attempt n created, written right after creating it. Why: Recovery can prove ownership of the lock before any landing record exists.
LandingRecord: What: landing-<n>.json: one landing attempt inside the critical section. Why: Recovery decides from it whether the attempt landed and completes or discards it.
LockIdentity: What: The identity of the real index.lock a transaction created. Why: Recovery removes a real index.lock only when it is provably the transaction’s own.
PreparedRecord: What: prepared.json: the verified prepared commit in the shadow repository. Why: Landing and recovery need the commit, its tree and the worktree completions.
PreparingRecord: What: preparing.json: invocation capture facts written before any Git mutation. Why: Recovery learns from it where every piece of the transaction lives.

Enums§

Base: What: The target at invocation, or the expected old target of a landing. Why: An unborn branch has no commit; compare-and-swap then expects the all-zero OID.
Conclusion: What: The commit kind that decides whether a moved target fails instead of replaying. Why: An amend or a conclusion cannot replay onto a moved branch.
LandingOperation: What: What a landing attempt installs: a commit, or a normalization that installs only index and worktree bytes. Why: A normalization never moves the target, so recovery checks it did not move.
RefFormat: What: The ref storage backend of the real repository. Why: The shadow ref snapshot and the conclusion pseudorefs differ by backend.
SymbolicHead: What: The symbolic HEAD target at invocation. Why: A branch switch between preparation and landing fails the commit.
TransactionMode: What: How the commit selects its content. Why: Explicit-path commits build the tree from the base plus selected paths; index commits use the captured index.

Constants§

INDEX_INSTALLED_FILENAME: Index installation completion marker filename.
JOURNAL_SCHEMA_VERSION: Journal schema version of every per-transaction state record.
PREPARED_FILENAME: Prepared commit record filename.
PREPARING_FILENAME: Invocation capture record filename.
REF_UPDATED_FILENAME: Landed commit record filename.

Functions§

index_lock_record_filename: What: The index-lock record filename of one attempt. Why: See pre_landing_index_filename.
landing_record_filename: What: The landing record filename of one attempt. Why: See pre_landing_index_filename.
post_index_filename: What: The post-index artifact filename of one attempt. Why: See pre_landing_index_filename.
pre_landing_index_filename: What: The numbered artifact and record filenames of one landing attempt. Why: Every writer and reader names them the same way.