Skip to main content

Workflow Execution & Configuration Snapshots

A workflow execution is a single run of a workflow, scoped to a workspace. Every launch creates one, and it becomes the permanent record of that run: its status, timing, cost (derived from its logs), and — the architecturally interesting part — four immutable snapshots that freeze the complete runtime context.

The four snapshots​

At launch, before dispatching anything, the core captures four JSONB NOT NULL snapshots on the execution:

  • workflow_config_snapshot (core-built) — agent/model/prompt assignments and their parameters.
  • service_config_snapshot (core-built) — service assignments with headers and compiled URLs (placeholders resolved).
  • system_snapshot (core-built) — system context, system-wide config with overrides resolved, plus workflow metadata and guardrails.
  • workspace_snapshot (plugin-built) — the plugin's domain context, produced by its workspaceSnapshotProvider.

Together these fully reconstruct the webhook payload — there is no separate "fetch context" endpoint; the payload is the four snapshots.

Why immutable​

The reason for freezing is historical reproducibility. Configuration is mutable and changes constantly as operators iterate; an execution must not. Because the snapshots are captured at start and never change, a run is unaffected by later edits, a completed run's log always shows the settings that actually applied, and a retry reproduces the original conditions exactly by replaying the same four snapshots rather than re-reading current config. The execution keeps foreign keys back to the live config rows for lineage, but the snapshot — not the FK — is the source of truth for what ran.

One deliberate exception: pricing​

Snapshots capture consumption metadata (a service's unit/per_unit, an agent's model identity) but not pricing. Cost is computed at log-ingestion time from current registry pricing, not frozen snapshot pricing — so a price change applies to future calculations without rewriting history, and pricing lives in exactly one place. This is a considered split: the run's inputs are frozen for reproducibility; the price of those inputs is looked up live, because that's the number the business wants current. The full field shapes are documented for workflow authors in the Workflow Developer snapshot articles.