feat(orchestrate): C5a — resumable saga engine (spec 09)

[gustavobertoi]

Chunk C5a (M2-remainder) — the saga engine

The load-bearing spine of the up saga: an ordered Phase driver that is resumable, crash-safe, compensating, and observable. It owns no domain logic — it sequences Phases under the lock+ledger spine. Per spec 09.

The spec calls C5 the largest chunk and recommends splitting it. This PR is C5a (the engine); the concrete daemon-phase wiring (clone/network/shared/provision/generate/compose-up/hooks) + the shared-postgres host-port coupling (the flagged design item) + the daemon integration test are C5b.

What

• Phase — Name/Scope, Mutating, AlwaysRun, Fingerprint, Run, Compensate.
• Saga.Run — per phase: compute fingerprint → skip iff saga_phase is satisfied for that exact fingerprint (a changed fingerprint, or a started-but-not-satisfied row, re-arms it → crash mid-phase re-runs) → StartPhase under the flock → run the body lock-free (the phase owns its short mutating critical sections) → Satisfy/Fail under the flock. A panic in Run becomes a failure, never a CLI crash.
• Compensation — on a downstream failure the succeeded mutating phases unwind in reverse (best-effort; a comp error is logged, not fatal), and each unwound phase row is cleared so a re-run redoes it. Intentionally-kept mutations (the shared network, provisioned data) declare no Compensate — a failed up never destroys data (spec 09 hard rule).
• Output contract — a Record per phase ({phase,scope,status,durationMs,error,detail}, error null on success) for --json; FormatPlain for non-TTY; an Emit callback for live streaming; AnyFailed for the exit code. Every transition also writes an event_log row.

Tests

Against a real temp ledger + fake phases: happy path, skip-on-satisfied, fingerprint re-arm, AlwaysRun (secrets), failure→reverse compensation, resume-after-failure (crash recovery), panic→failure, the JSON error:null contract, plain rendering, fingerprint stability, Emit streaming.

Gate

make ci green (race included).

🤖 Generated with Claude Code