Module sync 

Sync orchestrator — M3 Stage B slice 6.

Glues the building blocks shipped in slices 1–5b into a single runnable pipeline:

1. Walk a pack tree via crate::tree::sync_meta + crate::tree::build_graph + FsPackLoader + a GitBackend.
2. Run plan-phase validators (manifest-level + graph-level).
3. Execute every action via a pluggable ActionExecutor (PlanExecutor for dry-run, FsExecutor for wet-run).
4. Record each step as an Event::Sync entry in the pack-root’s .grex/events.jsonl event log.

Traversal order

Nodes are executed in depth-first post-order: children fully install before their parent. Rationale: parent packs commonly require: artifacts created by children (e.g. a parent symlink whose src lives inside a child). Running the root last matches the overlay-style dotfile-install intent authors expect, and it matches how walker.walk is structured (children are hydrated before the recursion returns).

Decoupling

The CLI crate drives this module through a thin run() entry point; SyncOptions is #[non_exhaustive] so new knobs (parallelism, filter expressions, ref overrides) can land in later milestones without breaking CLI callers. Errors aggregate into SyncError with a small, stable variant set.

Structs

DanglingStart

One ActionStarted event in the manifest log that has no matching ActionCompleted or ActionHalted peer.

HaltedContext

Rich context attached to a SyncError::Halted variant.

RecoveryReport

Summary of teardown artifacts found under a pack root before a sync begins.

SyncOptions

Inputs to run.

SyncReport

Outcome of a run invocation.

SyncStep

One executed (or planned) action step in a sync run.

WorkspaceMigration

One legacy-layout migration attempt. outcome distinguishes the move-succeeded case from the don’t-clobber-user-data case so CLI renderers can present different advice to the operator.

Enums

MigrationOutcome

Outcome of one legacy-layout migration attempt.

SyncError

Error taxonomy surfaced by run.

Functions

pack_display_name

Re-export a cheap helper so CLI renderers can label halted steps by node name without reaching into the graph twice.

run

Run a full sync over the pack tree rooted at pack_root.

scan_recovery

Walk workspace and the manifest log to find crash-recovery artifacts.

teardown

Run a full teardown over the pack tree rooted at pack_root.