Module commit 

The wrapper’s commit path: arguments, preparation, convergence, conclusion and timing. What: The wrapper’s commit path: arguments, preparation, convergence, conclusion and timing. Why: A commit is the central transaction of the wrapper.

In TS you’d write (pseudocode):

// commit/index.ts: one `export * from './file'` per module below.

Modules

capture_invocation

The invocation capture: repository layout, symbolic HEAD, conclusion kind, ref backend and base. What: The transaction facts recorded before any Git mutation: the repository layout, the symbolic HEAD target, the conclusion kind, the ref storage backend, and the preparation base. Why: Every later read of HEAD inside a transaction uses the recorded base or the landed commit, never live HEAD, because another landing may have moved it since the invocation started. The layout query and the base read run as separate steps, so pruning sees the transaction before the base is read (src/policy-engine/commit-transaction-capture.ts, captureInvocationLayout and captureInvocationBase).

commit_args

Argument transforms of native preparation: normalisation, global split, -a removal and private arguments. What: Argument transforms of native preparation: the normalised commit argument region, the split of global options from the commit region, the removal of -a/--all, and the arguments of the real git commit that run against the complete private index. Why: Native git commit must see the policy-settled index, not worktree bytes again, so selection controls and pathspecs are removed once the private index already holds them (src/policy-engine/commit-preparation-native.ts, commit-transaction-selection.ts, src/parser/commit-normalise.ts). The removals match the incumbent token for token, including its use of lastIndexOf, so a -m value equal to a pathspec is removed from the same position.

commit_command

The git commit command: the transaction, the settled events, the post-commit gate and the backup. What: The git commit command of the native wrapper: the preparation and landing through the resident service, the settled events, the post-commit gate and the handoff of the automatic backup. Why: The wrapper runs the commit instead of forwarding it, prints the pre-forward events only after the commit returned, then runs the post-commit gate for a landed commit and, when the gate passes, hands the push to the service. A commit that landed nothing exits with its own status.

commit_conclusion

The conclusion of a settled commit transaction: preparation, landing and post-landing completion. What: The events of a settled commit with the fix summary the policies’ corrections earned. Why: The summary appears only after some pass changed candidate bytes, and a normalization that removed every change always reports it. The conclusion that once landed the commit itself (hook dispatcher, native preparation in the shadow, the landing loop) is gone: the resident service is the only writer of a commit.

commit_convergence

Slice 6: the commit path’s bounded policy convergence over the private index. What: The commit path’s bounded policy convergence over the private commit index: each changed pass writes its corrections into the index, then the whole ordered pass restarts until it proposes nothing. Why: The commit path must end with the corrections the policies settled on, and must stop when they repeat a state or do not settle. The loop is the shared converge; this module supplies the commit path’s three operations, as the direct fix does for the worktree. Exact prior states are compared in memory; the incumbent also streams them to snapshot files, which only serve the same comparison.

commit_facts

Rule facts from the real repository with candidates read from the private index. What: The repository facts of a commit transaction: every rule fact is read from the real repository, and the candidate files are read from the private index and the shadow object store against the recorded base. Why: The incumbent’s rules (commit-only, commit-index, commit-sequencer) ask real Git about the real index and the real sequencer state, while the content policies read the private commit index that the transaction corrects. Pointing every fact at the private index would answer the rules about a state the user never staged.

commit_index

The private commit index: copies, selection modes, pathspec files and listings. What: The private commit index of one transaction: its timestamp-preserving copies of the real index, its initialization for each selection mode, the intended tree written from it, its path listings, the pathspec-file source, and interactive and patch selection run against it. Why: Git’s staging and selection run against a private index and the shadow object store, so the real index and object store change only at landing. A copy keeps the real index’s timestamps, because Git re-reads a stat entry whose time is not older than the index file (index-file-timestamps.ts, issue #544).

commit_no_change

The normalization-only transaction for a correction that removed every change. What: The normalization-only commit: a correction whose complete intended tree equals the recorded base ends without an empty commit, and says so. Why: The preparation (service_prepare.rs) decides it before anything is sent to the service; this module holds the finding’s identity and its message, so the words of the finding stay in one place (src/policy-engine/commit-transaction-no-change.ts).

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).

commit_staged_additions

The finding for a staged deletion that an explicit-path commit cannot record. What: The staged additions an explicit-path commit must carry into its private index, and the pathspec-file reader that tells which selection they belong to. Why: A path staged as an addition in the real index is tracked there, so native git commit -- <path> takes its worktree content without asking any ignore rule. The private index of an explicit-path commit starts from the recorded base, where such a path is untracked, so git add applies the ignore rules: a directory pathspec silently matches nothing, and a file pathspec fails with a hint to force-add that commit does not accept. Carrying the real index’s entry first makes the path tracked in the private index, and git add then refreshes it from the worktree exactly as native Git does.

commit_staged_deletions

What: The commit-only finding for a staged deletion that an explicit-path commit cannot record because the path is still on disk. Why: An explicit pathspec selects worktree content, never index state, so a deletion staged with git rm --cached for a path that stays on disk (an ignored editor file, for example) is not the content the pathspec selects. Without this finding Git answers “nothing to commit”, or a private git add fails with a hint to force-add the ignored path, which would re-track the file instead of recording its removal.

commit_timing

The record of where one wrapped commit spent its time, appended beside the discard audit. What: The record of where one wrapped git commit spent its time, appended to a size-capped file in the common Git directory beside the discard audit: preparation, building, setting up the service, reaching it, waiting for its answer, the work after landing, the post-commit gate and the hand-over of the push. Why: A commit that took seventeen seconds could not be split afterwards, because nothing outside verbose mode said which phase held the time. The numbers are taken from the monotonic clock as the commit runs (one Instant read per phase edge, no Git start, no flush to disk) and written once, in one append, when the command ends. The record goes to the file only: the person’s terminal never shows it.

commit_transaction

The commit transaction in the incumbent’s order, up to the settled policies. What: The values every commit of the service route shares: the invocation, how it can stop, what it came to, the selection the command line makes, and the policy checks over the private index. Why: The preparation (service_prepare.rs) and the commit command (commit_command.rs) pass these between them. The transaction that once landed a commit itself, with its registry, recovery and replay, is gone: the resident service is the only writer of a commit (doc/planning/cli-git-resident-service.md, “Landing every command line”).

commit_worktree_records

The worktree completion records of selected corrections and of hook changes. What: The worktree completion records a landed commit owes the worktree: selected final-newline corrections. Why: The commit keeps what the private index holds, so the real worktree still holds the bytes the user wrote. After the landing, each recorded file takes the committed bytes only while it still holds its earlier bytes (src/policy-engine/commit-transaction-selected-worktree.ts).

conclusion_cleanup

Native conclusion cleanup reproduced in the owning worktree. What: Native conclusion cleanup reproduced in the owning worktree’s Git directory after a merge, cherry-pick or revert conclusion lands, and the names of that state. Why: Native git commit removes MERGE_HEAD and its siblings in the shadow; the real worktree must end the same way, but an entry is removed only while it still holds the bytes or value copied at preparation, because a changed entry belongs to a later command (src/shadow-repository/shadow-conclusion-cleanup.ts, -files.ts, -names.ts).

conclusion_copy

The shadow conclusion copies at preparation. What: The merge, cherry-pick and revert conclusion state copied into the shadow at preparation, and into the transaction’s comparison copies. Why: Native git commit in the shadow reads the conclusion state the real worktree holds at invocation. Landing later compares the real entries with these copies, so an entry changed by another command after invocation is kept (conclusion_cleanup.rs holds the landing side). Pseudorefs of a reftable repository live in the ref store and are copied with update-ref (src/shadow-repository/shadow-conclusion-state.ts).

post_commit

The post-commit gate over a landed commit: its events, its blocking and the backup it allows. What: The post-commit policy gate over a landed commit’s own changes. Why: The incumbent (src/policy-engine/post-commit-lifecycle.ts) checks the committed bytes of every path a landed commit changed, and only a gate that passes lets the commit reach auto-push. The push itself is the service’s work item, handed over by commit_command.rs after a passing gate. A blocked gate keeps the commit local and names it in a commit-landed event; the command exits 2. The landed commit is an input, so the integrator can call this after any landing.

private_index_request

The private index and object store a commit’s preparation selects, and the Git request that carries them. What: The private index and object store a commit’s preparation reads and writes, and the Git request that selects them. Why: Staging and listing read the private commit index, and only staging writes objects, into the scratch object store; GIT_INDEX_FILE and GIT_OBJECT_DIRECTORY select that private state while the invocation’s global options are ignored, as the incumbent does.

private_index_stage

Slice 6: writes one corrected file into the private commit index as a blob and an index entry. What: Write one corrected file into the private commit index: its bytes as a blob, then the index entry that names that blob. Why: Corrections land in the private index, never in the real index or the worktree. The incumbent patches the private index with git apply --cached; here the policy already holds the corrected bytes, so the blob and the entry are written directly.

rule_commit_index

Pure core of the index-against-HEAD check. What: The pure core of the index-against-HEAD check used by the commit-only transform. Why: The caller runs real Git; this module only says which command to run and what its exit status means, so the decision is testable without a process.

rule_commit_only

Pure decision of the commit-only transform. What: The pure decision of the commit-only transform: insert -o after git commit, or say why not. Why: Every commit must name the paths it includes. Two decisions need a repository fact (sequencer state, index against HEAD); this module asks for the fact by returning a Needs... variant and the caller answers through a resolve_... function, so no process or file is touched here.

rule_commit_only_message

User-facing diagnostics of the commit-only transform. What: The user-facing diagnostics of the commit-only transform. Why: Each message names the rejected form and every valid way forward; keeping the text apart from the decision keeps both files readable.

rule_commit_sequencer

Pure core of the merge, cherry-pick and revert conclusion check. What: The pure core of the “is a merge, cherry-pick or revert awaiting its commit” check. Why: The caller runs real Git and probes the filesystem; this module says which query to run, reads its output exactly, and decides from three presence facts.