Module save 

Shared save primitive for capture / commit / checkpoint / ready auto-capture.

CLI verbs become thin shells that build a SavePlan and call execute_save. Repo keeps atomic tree/state mutation; this module owns the composition of preflight-adjacent routing, Heddle snapshot, and optional Git-overlay write-through.

Structs

CaptureAgentReport

CaptureAttribution

Attribution resolved lazily after capture’s non-mutating safety checks.

CaptureDiagnostics

CaptureOptions

Fully-resolved inputs for the normal local capture operation.

CapturePrincipalReport

CaptureProfile

Capture-specific timings owned by the operation implementation.

CaptureReport

Final semantic report returned by the capture seam.

CommitGitIndexPlan

Pure commit index plan for internal Git projection writes.

SavePlan

Inputs for execute_save. Attribution is resolved by the caller so CLI env/harness/agent precedence stays at the embedding surface.

SaveReport

Result of a successful save.

Enums

GitScope

How far a save should write through into Git (Git-overlay only).

SaveVerb

Public CLI / facade verb that requested the save.

Functions

capture

Capture the current worktree as one synchronous local operation.

commit_next_action_from_trust

Next-action after a git-projection commit from verification facts only.

commit_scope_text

Human scope line for git-projection commit text mode.

complete_current_thread_manual_resolution

Complete a captured manual resolution and return its contextual land action.

execute_save

Execute a save: optional Heddle snapshot + optional Git checkpoint write-through.

plan_commit_git_index

Plan commit scope from staged + extra worktree paths and --all.

plan_commit_git_index_only

Index-only plan: commit staged paths, preserve all extras.

plan_creates_new_state

Whether this plan should create a new Heddle state (vs reusing HEAD).

plan_git_scope

Pure routing helper: which Git write-through scope a verb should use.

plan_writes_git_checkpoint

Whether this plan should perform a Git-overlay write-through.

recover_published_git_checkpoint

Finish the metadata/oplog half of a checkpoint whose Git ref was already published before a crash. Returns None when no matching published intent exists, so callers can continue with their own recovery policy.

split_git_extra_paths

Split unstaged: / untracked: prefixed extra paths from status rows.

staged_commit_summary

Annotate a commit summary when staged-only commit leaves extras behind.

tree_leaf_name

Leaf path component for Git index → Heddle tree entry names.