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, the private index and the hooks directory. The hooks directory and the silenced hook events come from the hook dispatcher, which this lane does not build: they arrive through PreparationHooks. 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, worktreeRoot, hooksDirectory, commitIndexPath });

Structs

PreparationHooks

What: The hook dispatcher facts preparation needs: the directory holding the dispatcher shim, and the events whose hooks the shim runs instead of Git. Why: The dispatcher is built by another lane. This seam keeps the preparation code independent of that lane, and the incumbent’s silenced events are supplied by the caller, not duplicated here.

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 and hook output reach 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.