engine

type AdapterResolver interface {
	AgentResolver() agent.Resolver
}

type AgentEventData struct {
	Kind           string `json:"kind"`                       // adapter-specific (e.g. Claude Code: "system", "assistant", "user", "tool_use", "tool_result", "thinking", "result", "rate_limit")
	Stream         string `json:"stream,omitempty"`           // "stdout" | "stderr"
	Size           int    `json:"size"`                       // payload byte count (whether inline or offloaded)
	Live           bool   `json:"live,omitempty"`             // true means payload/display fields follow live normalized/redacted policy
	DisplayClass   string `json:"display_class,omitempty"`    // sanitized scalar copy of agent.EventDisplay.Class for live events
	DisplayTool    string `json:"display_tool,omitempty"`     // sanitized scalar copy of EventDisplay.Tool for live events
	DisplaySummary string `json:"display_summary,omitempty"`  // sanitized scalar copy of EventDisplay.Text for live events
	DisplayLines   int    `json:"display_lines,omitempty"`    // scalar copy of EventDisplay.Lines for live tool results
	DisplayBytes   int    `json:"display_bytes,omitempty"`    // scalar copy of EventDisplay.Bytes for live tool results
	DisplayIsError bool   `json:"display_is_error,omitempty"` // scalar copy of EventDisplay.IsError for live events
	PayloadInline  []byte `json:"payload_inline,omitempty"`   // strict: raw event bytes; live: normalized/redacted bytes when Size < threshold
	PayloadRef     string `json:"payload_ref,omitempty"`      // CAS pointer when Size >= threshold
}

type AttemptResult struct {
	N              int
	AttemptOutcome string
	Verdict        map[string]any
}

type BranchTakenData struct {
	Which string `json:"which"` // "then" | "else"
}

type CallStartedData struct {
	InputRef   string            `json:"input_ref"`
	InputFiles map[string]string `json:"input_files,omitempty"`
	Runtimes   []ResolvedRuntime `json:"runtimes,omitempty"`
}

type CallStartedRecord struct {
	Input      map[string]any
	InputRef   string
	InputFiles map[string]string
	Runtimes   []ResolvedRuntime
}

type DispatchResult struct {
	Outcome  Outcome
	ExitCode *int
	Outputs  map[string]any           // pre-commit typed outputs (nil if step has no output_schema or parse failed)
	Stdout   []byte                   // pre-commit raw stdout
	Files    []container.CapturedFile // pre-commit captured file contents (path + bytes)
	Err      error                    // set on non-ok outcomes; nil on Outcome == ok

	// RetryAfter is an optional server-supplied "wait this long before retrying"
	// hint surfaced on a retryable_failure — parsed by an adapter from a provider
	// Retry-After header or a rate-limit reset time (e.g. Anthropic
	// anthropic-ratelimit-*-reset, or the Claude Code rate_limit event's resetsAt).
	// Zero means "no hint, use the policy curve". RunWithRetry feeds it to
	// retry.Policy.EffectiveBackoff so the next sleep waits at least this long
	// (capped at retry.MaxHonoredRetryAfter). Runtime-only: never journaled —
	// Commit reads named fields off DispatchResult, not this one.
	RetryAfter time.Duration

	// Slice 5.2 — agent-step events. The dispatcher's runAgent drains the
	// adapter's <-chan AgentEvent and buffers each here for the
	// interpreter-level engine/agent_step.go to write as agent.event log
	// entries (Blobs-offload ≥ 4 KiB). Nil for code steps. Per CLAUDE.md
	// "interpreter is the only writer to state" — the dispatcher does NOT
	// call Log.Append; it buffers and returns.
	AgentEvents []agent.AgentEvent

	// Slice 6.1 — the adapter's per-step metrics (cost/tokens/turns), produced
	// by runAgent from agent.AgentResult.Metrics. nil for code/signal steps.
	// Commit persists it VERBATIM on node.completed; the engine never
	// interprets it. obs (Phase 6) projects it into awf.cost.* / gen_ai.usage.*.
	Metrics *agent.MetricSet

	// Transcript is the adapter-provided verbatim {user, assistant} pair. Commit
	// content-addresses it when the step participates in a conversation. The engine
	// never holds a with:-derived prompt — closes the opacity gap.
	Transcript agent.ThreadTurn

	// Live is an optional data-only live dispatch handoff. If present, the
	// interpreter calls RunOptions.LiveFinalizer after node.completed commits.
	Live *LiveDispatchRecord

	// SnapshotRef is the CoW workspace diff captured by the dispatcher after a
	// successful exec, for a snapshot:workspace container (empty otherwise).
	// The Backend already Put it to Blobs; Commit records it, never re-Puts.
	SnapshotRef string
	// Container is the step's bare container name (for node.completed.container —
	// resume's snapshot→container mapping + obs's awf.container.name).
	Container string

	// SessionTranscript is the captured claude session `projects/` subtree as a
	// gzip-tar, read by the dispatcher (via Backend.ReadTreeAt) after a
	// successful agent turn. Commit content-addresses it into Blobs and records
	// SessionRef. json:"-" — never journaled raw (mirrors Transcript at :185).
	SessionTranscript []byte `json:"-"`
	// SessionRef is set by Commit after Put. Operational, ref-only.
	SessionRef string

	// Node and InputRefs are populated ONLY on the code-step dispatch path
	// (engine/interpreter.go) so Commit can compute the NodeKey for deterministic
	// nodes. All other Commit call sites (agent_step, react, reduce) leave these
	// zero (nil Node → isDeterministicNode returns false → empty key). Do NOT
	// populate these from non-code paths.
	Node      ir.Node  // the ir.CodeStep node; nil for all non-code paths
	InputRefs []string // sorted CAS refs of the resolved input_files blobs; nil if no input_files
}

type Dispatcher interface {
	Run(ctx context.Context, intent NodeIntent) (DispatchResult, <-chan container.IOChunk, error)
}

type ErrContainerRequired struct {
	Ref string
}

type ErrRuntimeDrift struct {
	Ref       string
	Container string
	Recorded  string
	Current   string
}

type GateAttemptData struct {
	N              int    `json:"n"`
	AttemptOutcome string `json:"attempt_outcome"`
	VerdictRef     string `json:"verdict_ref,omitempty"`
}

type LiveDispatchRecord struct {
	AdapterRef     string
	SessionKey     string
	SessionKeyHash string
	LeaseID        string
	ActiveTurnID   string
	ProviderTurnID string
	RunID          string
	NodePath       string
	Epoch          uint32
	CommittedUnix  int64
}

type LiveHomePin struct {
	Path   string `json:"path"`
	Digest string `json:"digest"`
}

type LocalDispatcher struct {
	Backend container.Backend
	Handles map[string]container.Handle
	// RuntimeParent scopes declared container names for call workflows. Empty
	// means root workflow; non-empty handles are keyed as
	// QualifiedContainerKey(RuntimeParent, container).
	RuntimeParent string
	// ComposeFiles is the workflow's compose-file bytes by workflow-relative
	// path — sourced from ir.LoadedDefinition.ComposeFiles at construction.
	// engine/map.go reads this when Creating per-item containers for compose-
	// mode `containers:` entries; image-mode entries ignore it. Nil-safe (an
	// image-mode-only workflow may leave this unset).
	ComposeFiles map[string][]byte

	// Slice 5.2 — agent-step seam.
	//
	// Resolver is the agent.Resolver the dispatcher consults to look up
	// agent adapters by AgentStep.Uses. Nil means no agents registered —
	// any AgentStep dispatch returns *agent.ErrAdapterNotFound (mapped to
	// permanent_failure: the workflow references a `uses:` ref the
	// operator didn't register). Production wiring lives in cli/execute.go
	// (Task 11); tests inject *agent.Registry directly.
	//
	// Concurrency: Resolver.Lookup MUST be safe for concurrent use (Phase
	// 3 parallel branches dispatch concurrently). agent.Registry from
	// slice 5.1 satisfies this via sync.RWMutex.
	Resolver agent.Resolver

	// AgentEventTap is the io.Writer the dispatcher writes one-line-per-
	// AgentEvent stderr output to. Nil disables the live tap entirely
	// (tests). The CLI sets this to stderr (Task 11). Separate from the
	// io.Writer threaded through engine.Run (which is for IOChunks) so
	// agent events render with their own per-kind formatting without
	// interleaving with code-step stdout.
	AgentEventTap io.Writer

	// RenderAgentEvent formats each live AgentEvent to the AgentEventTap writer.
	// nil → the built-in terse fallback (writeAgentEventTap). cli injects a
	// TTY-aware, per-kind renderer; the engine stays presentation-agnostic.
	RenderAgentEvent func(io.Writer, agent.AgentEvent)

	// StepCostLine, when true, makes runAgent write one cost/token line per
	// agent step to AgentEventTap (slice 6.2 live renderer). Default false so
	// engine unit tests' exact tap-write-count assertions are unaffected; the
	// CLI (cli/execute.go) sets it true. Sourced from the adapter's already-
	// extracted MetricSet — never parses harness output, never touches obs.
	StepCostLine bool

	// M1 session restore — read-only access for the agent restore site.
	//
	// RunState is the folded run state for the current run. When non-nil and
	// RunState.SessionRefs[path] is set, runAgent restores the committed session
	// transcript into the container BEFORE launching the agent (the inverse of the
	// capture block). Nil means no prior session map (first run or non-session step).
	// The interpreter sets this in interpreter.go (engine.Run's LocalDispatcher
	// construction); direct LocalDispatcher callers (tests) can set it too.
	//
	// NOTE: the dispatcher NEVER writes to RunState; only the interpreter (via
	// engine.Commit + runstate.RecordCompleted) updates it. The restore path only
	// calls RunState.SessionRefs (read) + Blobs.Get (read) + Backend.WriteFileAt.
	RunState *RunState

	// Blobs is the shared content-addressed store. Read-only from the dispatcher:
	// the restore path calls Blobs.Get to materialize the committed session transcript.
	// Only engine.Commit (interpreter-side) calls Blobs.Put — never the dispatcher.
	Blobs state.Blobs
}

type LoopIterData struct {
	N int `json:"n"` // 1-based iteration number
}

type MapFrontierData struct {
	Items []MapItemData `json:"items"`
}

type MapItemData struct {
	N      int    `json:"n"`
	Status string `json:"status"`
	// ImageDigest is the content digest of the runtime-resolved image this
	// element booted (P6a) — empty for a statically-imaged map. omitempty keeps
	// pre-P6a logs and static maps byte-identical (additive, like SnapshotRef).
	ImageDigest string `json:"image_digest,omitempty"`
	// Reason is a machine-readable INFRA cause for a tolerated item_failed (P6a):
	// currently only ReasonImageUnavailable (a non-empty runtime image ref that
	// could not be booted). Empty for item_passed and for a plain body failure.
	// It distinguishes "couldn't boot this element" from "this element ran and
	// produced a negative result" (the Tekton/Temporal infra-vs-result split)
	// WITHOUT a new status — the three-value Status tally (item_passed /
	// item_failed / item_pruned) and MinSuccess math are untouched; it is NOT a
	// quality/result verdict (that is the gate's job). A
	// deterministic render/definition fault is NOT a reason — it fails the whole
	// map as permanent_failure. Audit/forensic field: no production reader today
	// (consumers are the docker RepoDigests follow-up + a future obs projection).
	Reason string `json:"reason,omitempty"`
	// Outcome is the item body's rolled-up mechanical outcome when Status ==
	// item_failed: "retryable_failure" | "permanent_failure" | "rejected".
	// Empty for item_passed / item_pruned, for the image_unavailable path, and
	// for pre-this-change logs. Resume re-run selection (see runMap reconciliation)
	// re-runs ONLY a retryable item; permanent / rejected / absent replay-as-failed.
	Outcome string `json:"outcome,omitempty"`
	// Cause is a bounded, human-readable rendering of the item body's failure
	// (bodyErr) when Status == item_failed. Forensic only — empty for passed/
	// pruned and pre-this-change logs (omitempty). Distinct from Outcome (the
	// mechanical class) and Reason (the infra cause). Not equality-checked by
	// the fold → determinism-safe.
	Cause string `json:"cause,omitempty"`
}

type MapItemRecord struct {
	N         int
	ItemValue any
	Status    string
	// Outcome mirrors MapItemData.Outcome (the item body's mechanical outcome on
	// failure). Drives resume re-run selection; empty for passed/pruned/image.
	// Read ONLY from the FOLDED record (engine.Fold's map.item arm). Like
	// ImageDigest/Reason, the live mirror is intentionally NOT maintained
	// post-commit (updateMapItemStatus sets only Status) — the sole reader, the
	// resume reconciliation, runs on a freshly-Folded RunState, so the live value
	// is never observed. A future live reader MUST add write-through here first.
	Outcome string
	// ImageDigest / Reason are folded from the map.item event (P6a) — the durable
	// record of what this committed element booted and, on failure, why. Read-back,
	// never re-derived (run state; ItemValue is re-derived from `over`).
	// Audit/forensic only: NO production reader today — committed map items are
	// replayed-as-skipped on resume and never re-boot, so the digest is not a
	// re-pin input. Consumers are the docker RepoDigests follow-up + a future obs
	// projection.
	ImageDigest string
	Reason      string
	// Cause mirrors MapItemData.Cause. Forensic; read from the FOLDED record.
	Cause string
}

type NodeCompletedData struct {
	Outcome    string            `json:"outcome"` // always "ok" — only ok-steps commit
	ExitCode   *int              `json:"exit_code,omitempty"`
	OutputsRef string            `json:"outputs_ref,omitempty"`
	StdoutRef  string            `json:"stdout_ref,omitempty"` // CAS pointer; empty if step produced no stdout (or has none — agent/signal)
	Files      map[string]string `json:"files,omitempty"`      // declared path → CAS ref
	// Slice 6.1 — the adapter's per-step metrics, persisted VERBATIM (zero engine
	// interpretation). nil/omitted for code & signal steps. omitempty keeps
	// legacy logs decoding to nil (additive, like Backend slice 4.5 / Runtimes
	// slice 5.1). obs projects this into awf.cost.* / gen_ai.usage.*.
	Metrics *agent.MetricSet `json:"metrics,omitempty"`
	// Slice 7.1 — recorded ONLY when snapshot:workspace captured a CoW diff
	// (the dispatcher Put it to Blobs pre-commit; Commit records the ref, never
	// re-Puts). omitempty keeps pre-Phase-7 logs and non-snapshot steps byte-
	// identical (additive, like Metrics slice 6.1). Resume folds these into a
	// separate snapshot map; obs reads them off this event.
	SnapshotRef string `json:"snapshot_ref,omitempty"` // CoW workspace diff ref (snapshot:workspace only)
	Container   string `json:"container,omitempty"`    // bare container name (resume snapshot mapping + obs)
	// TranscriptRef is the CAS pointer for the participating turn's verbatim {user,
	// assistant} pair (continues: threading). Empty for non-participating steps.
	// omitempty keeps non-conversation logs byte-identical (additive, like SnapshotRef).
	TranscriptRef string `json:"transcript_ref,omitempty"`
	// NodeKey is the content-address cache key for deterministic (code) steps —
	// H(nodeSubtreeDigest ‖ sorted CAS refs of resolved input_files ‖ ∅ runtime pins).
	// Empty for non-deterministic steps (agent, react, reduce, signal, etc.).
	// omitempty keeps pre-WS6b logs byte-identical (additive, no fold breakage).
	// Task 6 (resume reuse) reads this to skip re-execution when inputs are unchanged.
	NodeKey string `json:"node_key,omitempty"`
	// NodeSubtreeDigest is the structural hash of the node definition (ir.NodeSubtreeDigest)
	// for deterministic (code) steps — the subtree component of NodeKey, recorded separately
	// so Task 6b2 (resume verifying-trace) can compare it against the current node definition
	// without recomputing NodeKey. Empty for non-deterministic steps (agent, react, reduce,
	// signal, etc.). omitempty keeps pre-WS6b2 logs byte-identical (additive, no fold breakage).
	NodeSubtreeDigest string `json:"node_subtree_digest,omitempty"`
	SessionRef        string `json:"session_ref,omitempty"` // native-session transcript blob ref (session adapters only)
}

type NodeFailedData struct {
	Outcome string `json:"outcome"`
	Error   string `json:"error,omitempty"`
}

type NodeIntent struct {
	Path           string
	Node           ir.Node
	ResolvedInputs ResolvedInputs
	IdempotencyKey string
	IsGateEvaluate bool
	RunContext     agent.RunContext
	// contains filtered or unexported fields
}

type NodeInvalidatedData struct {
	Paths []string `json:"paths"`
}

type NodeResult struct {
	Outcome    Outcome
	ExitCode   *int              // code step only (nil for agent/signal)
	Outputs    map[string]any    // typed; materialized from OutputsRef. READ-ONLY (see NodeResult doc).
	OutputsRef string            // CAS pointer (validates against Outputs)
	Stdout     []byte            // materialized stdout; READ-ONLY (see NodeResult doc). nil if step produced no stdout.
	StdoutRef  string            // CAS pointer (validates against Stdout)
	Files      map[string]string // declared path → CAS ref. READ-ONLY (see NodeResult doc).
	Transcript agent.ThreadTurn  // materialized from TranscriptRef by Fold (continues: threading). READ-ONLY. Zero value when the step didn't participate.
	// NodeKey is the content-address cache key folded from NodeCompletedData.NodeKey.
	// Non-empty only for deterministic (code) steps. Task 6 reads this during resume
	// to skip re-execution when the key matches the expected key for the current inputs.
	NodeKey string
	// NodeSubtreeDigest is the structural hash of the node definition folded from
	// NodeCompletedData.NodeSubtreeDigest. Non-empty only for deterministic (code) steps.
	// Task 6b2 (resume verifying-trace) compares this against the current node's
	// ir.NodeSubtreeDigest to decide per-node reuse.
	NodeSubtreeDigest string
}

type NodeSkippedData struct {
	Path   string `json:"path,omitempty"`
	Reason string `json:"reason,omitempty"`
}

type NodeStartedData struct {
	Kind string `json:"kind"`
}

type Outcome string

type OutputFileContract struct {
	Format string
	Schema *ir.JSONSchema
}

type PauseMarker struct {
	NodePath string
	Reason   string
}

type ReactRoundData struct {
	N int `json:"n"`
}

type ReactRoundRecord struct {
	N int // 1-based round number; finish_reason is read from the .model leaf (spec §4.1)
}

type ResolvedInputs struct {
	Command               string
	Env                   map[string]string
	OutputFiles           []string
	OutputFileContracts   map[string]OutputFileContract
	OutputSchema          *ir.JSONSchema
	NonRetryableExitCodes []int
	Timeout               time.Duration

	// InputFiles are the resolved (path → bytes) artifacts to stage via
	// Backend.CopyTo BEFORE Exec/Launch. The interpreter resolves each ref to a
	// CAS blob and Blobs.Get's the bytes (the dispatcher never touches Blobs).
	InputFiles []container.InputFile

	// ContainerlessFiles are the resolved input_files for a CONTAINERLESS agent
	// step — delivered to the adapter as inline message parts (each a label +
	// content + sniffed MIME) instead of staged into a container. Populated by
	// engine/agent_step.go's runAgentStep only when the step omits container:;
	// nil for container-backed steps (which use InputFiles) and code steps.
	ContainerlessFiles []agent.InputFile

	// Snapshot is "workspace" iff the step's container is a snapshot:workspace
	// container; the dispatcher captures a CoW diff after a successful exec.
	Snapshot string

	// SessionConfigDirRel is the per-run claude config directory (the value mapped
	// to CLAUDE_CONFIG_DIR), in StagingRoot form (native relative `.awf/...`, docker
	// absolute `/work/.awf/...`); empty for non-claude-family steps. The dispatcher
	// resolves it to an absolute path and threads it via inv.SessionConfigDir. Set
	// by the interpreter for container-backed IsolatedConfigDir adapters.
	SessionConfigDirRel string

	// SessionDir is the per-run claude session `projects/` directory to
	// capture/restore, in StagingRoot form (= SessionConfigDirRel + "/projects");
	// empty for non-session steps. The engine captures the whole subtree at commit
	// (Backend.ReadTreeAt) and restores it on the generator frontier
	// (Backend.WriteTreeAt). Set by the interpreter for PersistentSession adapters;
	// Milestone-1 tests set it directly.
	SessionDir string

	// Slice 5.2 — agent-step fields. Zero values when the node is a CodeStep
	// (runCode ignores them); populated by engine/agent_step.go runAgentStep
	// before dispatch.
	Uses string       // matches AgentStep.Uses; LocalDispatcher.runAgent looks up resolver.Lookup(Uses)
	With ir.RawConfig // post-template-substitution opaque adapter config; adapter.ValidateConfig + adapter.Launch read it

	// Slice 5.3 — agent-step gate feedback (the prior evaluator verdict on
	// repair attempts N>1). Populated by engine/agent_step.go runAgentStep
	// from the enclosing gate's runstate.LookupGateAttempts(gatePath) when
	// the step's path is inside a `.generate.` subtree. Nil on attempt 1 of
	// a gate, on non-gate paths, and for non-agent steps.
	//
	// The dispatcher's runAgent threads this into AgentInvocation.Feedback,
	// where adapters that consume an implicit "previous verdict:" preamble
	// (the Claude Code adapter, slice 5.3) read it. This is the SECONDARY
	// channel for gate feedback; the PRIMARY channel is the author-controlled
	// template substitution `{{ evaluate.<field> }}` that lands in With.prompt
	// before the dispatcher runs (Phase 3.3 wiring, unchanged).
	Feedback ir.RawConfig

	// Thread mirrors Feedback's plumbing: assembled by engine/agent_step.go from the
	// committed log via stepRuntimePath, copied into AgentInvocation.Thread by runAgent.
	// The dispatcher has no RunState access, so assembly happens interpreter-side.
	Thread []agent.ThreadTurn

	// ContextEvidence carries evaluator-only source evidence assembled by the
	// interpreter. It is copied into AgentInvocation.ContextEvidence by runAgent
	// and must not be rendered as active prior conversation.
	ContextEvidence []agent.ThreadTurn
}

type ResolvedRuntime struct {
	Ref       string `json:"ref"`
	Version   string `json:"version"`
	Container string `json:"container,omitempty"` // slice 5.1 — IR-declared container name (spec §3); different containers may have different binary versions
}

type RetryAttemptData struct {
	N       int    `json:"n"`
	Outcome string `json:"outcome"`
	Error   string `json:"error,omitempty"`
}

type RunCancelledData struct {
	Reason string `json:"reason,omitempty"`
}

type RunFinishedData struct {
	Outcome string `json:"outcome"`
}

type RunOptions struct {
	// Tap, if non-nil, receives the live-tap output: one "[step.id] <chunk>" per
	// IOChunk produced by each step. nil disables the tap entirely.
	Tap io.Writer

	// Broker is the signal broker for pause/cancel IPC. nil is valid — signal
	// steps fail with a clear error when reached with a nil broker.
	Broker *signal.Broker

	// Assets is the recorded run-start asset manifest. Task 5 consumes it when
	// resolving asset.<id> input_files; nil preserves pre-assets behavior.
	Assets map[string]RunStartedAsset

	// InputFiles is the supplied top-level workflow input-file manifest:
	// input-file name → CAS blob ref of the bytes supplied at run start. Seeds
	// runstate.InputFiles so a step referencing input.files.<name> resolves to
	// the supplied bytes; nil preserves pre-input-files behavior. Only set on
	// first run — on resume it is nil and runstate.InputFiles is fold-restored.
	InputFiles map[string]string

	// LiveFinalizer, if non-nil, is called after a successful live agent step's
	// node.completed event has been appended and synced.
	LiveFinalizer func(context.Context, LiveDispatchRecord) error

	// Resume is true on `awf resume` re-entry; the map reconciliation re-runs
	// transiently-failed items only when set (spec §6.3). false on fresh `awf run`.
	Resume bool

	// RerunFrom, when non-empty, is a committed node runtime path. At resume
	// start the engine invalidates that node's subtree + everything after its
	// top-level ancestor (engine/rerun.go), re-running them. Set by
	// `awf resume --from`.
	RerunFrom string
}

type RunPausedData struct {
	NodePath string `json:"node_path,omitempty"`
	Reason   string `json:"reason,omitempty"`
}

type RunResumedData struct {
	Epoch uint32 `json:"epoch"`
}

type RunStartedAsset struct {
	DeclaredPath string                `json:"declared_path"`
	IsDir        bool                  `json:"is_dir"`
	Files        []RunStartedAssetFile `json:"files"`
}

type RunStartedAssetFile struct {
	Path   string `json:"path"`
	Ref    string `json:"ref"`
	Size   int64  `json:"size"`
	SHA256 string `json:"sha256"`
}

type RunStartedData struct {
	RunID            string                     `json:"run_id"`
	WorkflowDigest   string                     `json:"workflow_digest"`
	StructuralDigest string                     `json:"structural_digest,omitempty"` // WS-6a; "" in pre-WS6 logs (omitempty)
	WorkflowID       string                     `json:"workflow_id,omitempty"`       // slice 6.1 — obs awf.workflow.id (standard §9); empty in pre-6.1 logs
	WorkflowVersion  int                        `json:"workflow_version,omitempty"`  // slice 6.1 — obs awf.workflow.version; 0 in pre-6.1 logs
	InputRef         string                     `json:"input_ref,omitempty"`         // empty if Workflow.Input is nil
	Backend          string                     `json:"backend,omitempty"`           // slice 4.5; "" → BackendDocker on resume
	Assets           map[string]RunStartedAsset `json:"assets,omitempty"`
	// InputFiles records the supplied top-level workflow input-file manifest:
	// input-file name → CAS blob ref of the bytes supplied at run start. Folded
	// back into RunState.InputFiles on resume (mirrors Assets) so input.files.<name>
	// resolves identically on first run and resume. Empty in logs from before
	// top-level input files were a supply channel (omitempty).
	InputFiles map[string]string `json:"input_files,omitempty"`
	LiveHome   *LiveHomePin      `json:"live_home,omitempty"`
	Runtimes   []ResolvedRuntime `json:"runtimes,omitempty"`
	// DefinitionRef is a CAS blob ref to the run's full canonical definition (the JSON of
	// ir.LoadedDefinition), snapshotted once at run start. It lets read-only viewers (e.g.
	// `awf ui`) render a past run faithfully against the structure it executed against, even
	// after the on-disk file is edited. View-only: NEVER consulted for resume/pinning — §8
	// drift is always decided against the live file. Empty in logs from before the snapshot
	// landed (omitempty); viewers fall back to the current file then.
	DefinitionRef string `json:"definition_ref,omitempty"`
}

type RunState struct {
	RunID            string
	WorkflowDigest   string
	StructuralDigest string         // WS-6a; "" for pre-WS6 logs (field absent in legacy run.started)
	Input            map[string]any // resolved from run.started.Data.input_ref via Blobs.Get
	// Assets is the recorded run-start asset manifest. Fold restores it from
	// run.started without dereferencing refs; engine.Run may also seed it from
	// RunOptions for first-run execution before any resume fold exists.
	Assets map[string]RunStartedAsset
	// InputFiles is the supplied top-level workflow input-file manifest:
	// input-file name → CAS blob ref. Fold restores it from run.started
	// (mirrors Assets); engine.Run seeds it from RunOptions on first run. The
	// root scope (interpreter_context.go) reads it so input.files.<name>
	// resolves to the supplied bytes both on first run and on resume.
	InputFiles map[string]string
	// Epoch is the *runtime* resume-invocation counter — set to 1 on run.started, then
	// overwritten by each run.resumed event's payload (see Fold). This is NOT the same
	// counter as state.Event.Epoch (which is auto-stamped by state.Log on each Append
	// and bumped by OpenLog on each reopen — see state/log.go). The two counters can
	// diverge if the writer makes a mistake: slice 2.6's cli resume MUST emit
	// RunResumedData{Epoch: rs.Epoch + 1} after each fold, otherwise the runtime
	// counter goes stale while state.Event.Epoch keeps incrementing.
	Epoch uint32

	Completed map[string]NodeResult // node.path → result
	Branches  map[string]string     // if-node path → "then" | "else"
	LoopIters map[string]int        // loop-node path → max completed iteration (1-based)

	// GateAttempts records the per-attempt verdicts for every gate that has
	// committed at least one attempt. Slice 3.3 addition; gate path → ordered
	// slice of AttemptResult (oldest first). The slice grows as the gate
	// executor records additional attempts; resume's Fold rebuilds it from
	// gate.attempt events.
	//
	// The template evaluator's `evaluate.*` scope reads the LAST element for
	// the enclosing gate path on attempt n > 1 (slice 3.3 engine/scope.go).
	GateAttempts map[string][]AttemptResult

	// ReactRounds records committed rounds per react node (react[N] path →
	// ordered slice, oldest first). startK := len(ReactRounds[R])+1 is the
	// resume cursor for a react: step at path R. P3 A3 addition.
	//
	// The template evaluator does NOT read this; it is used exclusively by the
	// react executor (engine/react.go, Phase 4) for resume continuation and by
	// Fold for replay. READ-ONLY aliasing contract: LookupReactRounds returns
	// the live backing array — callers MUST NOT mutate elements.
	ReactRounds map[string][]ReactRoundRecord

	// MapItems records the per-item status for every map that has committed
	// at least one map.item event. Slice 3.4 addition; map path → ordered
	// slice of MapItemRecord in arrival order (the order RecordMapItem was
	// called, which mirrors log-append order). NOT N-ascending: concurrent
	// item-body goroutines may commit out-of-N-order, so item N=3 can land
	// in the slice before N=1. Pinned by TestRunStateMapItemsRoundTrip.
	//
	// LookupByN(N) helpers are NOT provided — the map handler walks the
	// slice (typically ≤ Concurrency items in flight) when it needs to
	// check "is item N already committed?"
	//
	// The template evaluator's `<as>` resolution scope (engine/scope.go)
	// reads MapItems to find the bound value for an enclosing map's item.
	MapItems map[string][]MapItemRecord

	// Signals records per-name signal deliveries observationally — slice 3.5
	// addition. Signal name → ordered slice of SignalEntry{Seq, PayloadRef}.
	// Fold rebuilds from signal.received events on resume; the await step
	// (engine/signal_step.go) appends to it after each commit. PURELY
	// OBSERVATIONAL: no handler reads it for control flow (the path-keyed
	// SignalReceivedAt below is the half-commit-resume lookup). Phase 6 obs
	// will project this as a per-signal delivery timeline.
	//
	// Each Append is single-writer (interpreter is the only writer); concurrent
	// Lookups are safe under the mu.
	Signals map[string][]SignalEntry

	// CallStarted records durable subworkflow-call input pins. Call path →
	// materialized input + input ref + per-call runtime resolutions. Built by
	// Fold from call.started events; runtime writers mirror fresh commits via
	// RecordCallStarted.
	CallStarted map[string]CallStartedRecord

	// Paused is the latest non-cleared pause marker. Nil if no pause is
	// active. Slice 3.5 addition.
	Paused *PauseMarker

	// Cancelled is true iff a run.cancelled event has been folded in OR the
	// background poller (engine/controls.go) detected cancel.json mid-run.
	Cancelled bool

	// CancelReason is the operator-supplied free-text from cancel.json's
	// Reason field. Set by the poller alongside Cancelled. engine.Run reads
	// it when appending the run.cancelled event.
	CancelReason string

	// SignalReceivedAt is the path-keyed half-commit-resume mechanism (slice
	// 3.5 design Q7). Populated by Fold from signal.received events; read by
	// runSignalStep before calling broker.Receive — if a SignalReceivedEntry
	// exists for the await's path, the prior run committed signal.received
	// but not node.completed; the handler skips the Receive call + the
	// signal.received append and writes only node.completed.
	SignalReceivedAt map[string]SignalReceivedEntry

	// SnapshotRefs maps a container name to its latest committed snapshot ref
	// (snapshot:workspace containers only); resume restores each from this ref.
	// Slice 7.1 addition. Built by Fold from node.completed events' SnapshotRef
	// / Container fields — last write wins per container (a container is
	// snapshotted at every commit, so the last one is the resume point). Empty
	// for non-snapshot containers and pre-Phase-7 logs (the event fields are
	// omitempty, so the Fold guard skips them).
	SnapshotRefs map[string]string

	// SessionRefs maps a generate NODE PATH to its latest committed native-session
	// transcript ref. Unlike SnapshotRefs (container-keyed), a session belongs to a
	// specific generate node. Fold-populated (pre-Run), then read-only during Run.
	// IMPORTANT: unlike SnapshotRefs, SessionRefs IS cleared by clearInvalidatedPaths
	// (rerun.go) — a re-run generate node must drop its stale session.
	SessionRefs map[string]string

	// SelectedSkills records skills.selected decisions by runtime node path.
	// Agent steps consult it on resume to replay routed skill IDs without
	// re-running the router against a possibly changed query.
	SelectedSkills map[string]SkillsSelectedData
	// contains filtered or unexported fields
}

type RuntimeRef struct {
	ModuleID      string
	NodePath      string
	RuntimeParent string
	Uses          string
	Container     string
}

type Scope struct {
	// contains filtered or unexported fields
}

type SelectedSkill struct {
	ID    string  `json:"id"`
	Score float64 `json:"score"`
}

type SignalEntry struct {
	Seq        int
	PayloadRef string
}

type SignalReceivedData struct {
	Name       string `json:"name"`
	Seq        int    `json:"seq"`
	PayloadRef string `json:"payload_ref,omitempty"`
}

type SignalReceivedEntry struct {
	Seq        int
	PayloadRef string
}

type SkillsSelectedData struct {
	Library       string             `json:"library"`
	LibraryDigest string             `json:"library_digest"`
	Router        string             `json:"router"`
	RouterVersion string             `json:"router_version"`
	RouterParams  map[string]float64 `json:"router_params"`
	Selected      []SelectedSkill    `json:"selected"`
}

type SkipUnwind struct {
	TargetPath string
	Reason     string
}

type WorkflowExportResult struct {
	Outputs map[string]any
	Files   map[string]string
}