Module commit_transaction 

The commit transaction in the incumbent’s order, up to the settled policies. What: The commit transaction in the incumbent’s order, up to the settled policies: layout capture, the published workspace, the preparation base, preparing.json, the shadow repository, the private index under capture order, interactive selection, and the bounded policy convergence. Why: The incumbent (src/policy-engine/commit-transaction.ts) captures before it mutates, publishes the directory before the base is read, and takes the landing lock only inside the landing attempt, never through preparation: holding it here would serialize concurrent commits. The conclusion (commit_conclusion.rs) takes the settled state to a landed commit.

In TS you’d write (pseudocode):

const result = await runCommitTransaction({ args, gitPath, policyOptions, concurrency });

Structs

CommitInvocation

What: Everything the invocation fixes before the transaction starts. Why: The steps share one identity, one parsed commit region and one configuration; passing them together keeps a step from reading another invocation’s state.

Selection

What: The commit-region facts the transaction decides from, derived once. Why: The mode and the selection flags are read in several steps.

TransactionResult

What: What the transaction decided. Why: The command prints the events, runs the post-commit lifecycle for a landed commit, and exits with the code.

Enums

TransactionStop

What: Why the transaction stopped without a policy result. Why: The incumbent’s boundary maps each to a different ending: Git’s own exit code with no wrapper text, a message with exit status 1, a finding with exit status 2, or a verbatim stop text.

Functions

base_object

What: The recorded base as an object ID, or nothing for an unborn branch. Why: The candidate listing compares the private index with this commit.

decide_selection

What: Decide the selection facts of one commit invocation. Why: Invalid combinations reach native Git unchanged, so it rejects them.

failed

What: A transaction failure with the generic code. Why: Most unexpected failures are reported the same way.

private_checks

What: Rebuild the shipped checks over the private commit index: rule facts stay real, the candidates come from the private index against the recorded base. Why: The incumbent’s rules ask real Git about the real index, while the content policies read what the transaction corrects.

run_commit_transaction

What: Run one commit through the transaction: capture, private preparation, serial landing and post-landing completion. Why: Every non-dry-run commit runs through it, including clean commits and commit -a, because native git commit keeps index.lock on disk through hooks and the editor.

settled_passes

What: How many passes changed the state when the convergence settled; any other ending counts none. Why: The fix summary names the passes of a settled convergence only.

staged_at_base

What: The candidate request for the paths a private index changes against the recorded base. Why: The policies check exactly the paths the commit changes; each path is literal and rooted at the top level, so a name with glob characters or a directory below the current one still names one file.

stages_worktree

What: Whether the capture lists worktree changes that the commit stages: -a stages every tracked change and --include stages the named paths. Why: The capture record names those paths, so recovery copies exactly the worktree files the commit staged.

transaction_directory

What: The transaction directory’s names, derived from the registry root and the transaction ID. Why: Callers that build facts before the transaction creates anything use the same names.

write_journal_record

What: Write one journal record durably: exclusively, then the directory entry. Why: A state file is never rewritten, so a crash leaves the newest complete state readable.