saga

Overview ¶

Persistence for the saga Store - same reasoning as internal/approval's: a proxy restart mid-run must not silently lose the ability to compensate steps that already executed. Best-effort writes; a storage hiccup is logged, never blocks or fails the in-memory operation.

Postgres-backed persistence for multi-instance/HA deployments - same reasoning as internal/approval/postgres.go: the in-memory map + mutex is correct for one process, but a saga step's Seq assignment (len(s.runs[runID]) today) would collide across two instances appending to the same run concurrently. Postgres mode locks a run's existing rows before assigning the next Seq, serializing that assignment across instances the same way the in-process mutex does within one. MarkCompensated/MarkCompensationFailed need no such locking - they're idempotent single-row UPDATEs, and two instances marking the same step compensated concurrently land on the identical end state.

Package saga records each run's execution trace so it can be walked back. It is simpler than a "dynamic DAG" once one fact is taken seriously: an agent's tool-calling loop is sequential from this proxy's vantage point - one call, one result, one next decision. There is no concurrent branching to reconcile here. So the "graph" a run's steps need is just an ordered list, appended to as calls actually execute, with no workflow pre-declared anywhere. That's the literal meaning of "built from the execution trace, not a static declaration" - branching or retrying earlier in an agent's reasoning never has to be modeled, because only what actually executed ever lands in the trace.

Only Class A steps are ever compensated - that's what Class A means. Class B/C steps still get recorded for a human's visibility into the full run, they're just never walked back.