Module commit_preparation 

Native git commit in the shadow, the prepared commit read back and prepared.json. What: Native git commit in the shadow repository against the private commit index, the prepared commit read back from the shadow, and prepared.json. Why: Git owns the hooks, the editor, the templates, the message cleanup and the signing; this module only points Git at the shadow and the private index. Every hook is off in the shadow (its config switches the commit events off and the hooks-off option comes first), so Git starts no external program for a hook and never starts the wrapper. A failing preparation removes the shadow so no shadow outlives the failure (src/policy-engine/commit-preparation-native.ts, src/shadow-repository/shadow-repository.ts).

In TS you’d write (pseudocode):

await runNativePreparation({ gitPath, cwd, globalArgs, commitArgs, shadowPath, hookPlan, commitIndexPath });

Structs

PreparationRequest

What: Everything one native preparation needs from its transaction. Why: The incumbent passes these as separate options, and grouping them keeps the call short.

PreparedCommit

What: The prepared commit read back from the shadow HEAD. Why: Replay rebuilds every later commit from the exact object bytes, and the tree and signature decide what landing may do.

PreparedPaths

What: The facts prepared.json records beyond what the shadow and the index already answer. Why: The landing decides what to replay from these lists, and the policy pass that fills them is a later slice.

Enums

PreparationError

What: Why a preparation stopped. Why: A nonzero native exit is the invocation’s own exit code, while a start failure is an error.

Constants

NATIVE_UNSET_VARIABLES

Variables native Git must not inherit, so every object it writes lands in the shadow store.

PREPARED_FILENAME

Name of the journal record a preparation writes.

Functions

install_guard_when_free

What: Install the signal guard, waiting while another thread of this process holds it. Why: One wrapper process runs one Git child at a time, so the wait never happens there; library tests run several preparations in threads of one process, and the guard is process-wide.

prepare_native_commit

What: Runs native preparation end to end: native commit, the prepared commit read back, and prepared.json. Why: A failure removes the shadow before it returns, so no shadow outlives a failed preparation, and the exit code of a failed native commit is the invocation’s exit code.

read_prepared_commit

What: Reads the prepared commit from the shadow HEAD: its object, its tree and whether it is signed. Why: The header block ends at the first empty line; a signature header in it marks the commit signed.

retry_while_active

What: Run install again while it fails only because another holder is active, up to limit more times. Why: Any other failure, and a holder that never lets go, end the wait with the failure itself.

run_native_commit

What: Runs native git commit in the shadow with the terminal attached and returns its exit code. Why: The editor output reaches the user unchanged, so the child inherits standard streams.

write_prepared_record

What: Writes prepared.json exclusively and makes it durable. Why: Recovery reads the prepared record to decide what a dead transaction had prepared.