ledger

type AgentSnapshot struct {
	Digest       string `json:"digest"`
	Version      int    `json:"version,omitempty"`
	ProviderName string `json:"provider_name,omitempty"`
	Model        string `json:"model,omitempty"`
}

type ApprovalRecord struct {
	ApprovalID   string     `json:"approval_id"`
	RunID        string     `json:"run_id"`
	StepID       string     `json:"step_id"`
	Status       string     `json:"status"` // pending | approved | rejected
	Actor        string     `json:"actor,omitempty"`
	Reason       string     `json:"reason,omitempty"`
	EvidenceJSON []byte     `json:"evidence_json,omitempty"`
	CreatedAt    time.Time  `json:"created_at"`
	ResolvedAt   *time.Time `json:"resolved_at,omitempty"`
}

type ApprovalView struct {
	ApprovalID string `json:"approval_id"`
	Step       string `json:"step"`
	Status     string `json:"status"`
	Actor      string `json:"actor,omitempty"`
	Reason     string `json:"reason,omitempty"`
}

type AttemptOutcome struct {
	Status           AttemptStatus
	CoordinatorRunID string
	TaskID           string
	OutputRef        string
	OutputDigest     string
	ErrorRef         string
	ToStepID         string
	TransitionIndex  int
	MatchDigest      string
	DecisionJSON     []byte
	EvidenceJSON     []byte
}

type AttemptStatus string

type AttemptView struct {
	Step             string `json:"step"`
	Attempt          int    `json:"attempt"`
	Status           string `json:"status"`
	ToStep           string `json:"to_step,omitempty"`
	OutputDigest     string `json:"output_digest,omitempty"`
	OutputRef        string `json:"output_ref,omitempty"`
	ErrorRef         string `json:"error_ref,omitempty"`
	CoordinatorRunID string `json:"coordinator_run_id,omitempty"`
	TaskID           string `json:"task_id,omitempty"`
	Verdict          string `json:"verdict,omitempty"`
	MatchDigest      string `json:"match_digest,omitempty"`
	StartedAt        string `json:"started_at,omitempty"`
	FinishedAt       string `json:"finished_at,omitempty"`
	ElapsedSeconds   int64  `json:"elapsed_seconds,omitempty"`
	// LastHeartbeatAt is the latest liveness observation for a RUNNING
	// attempt, RFC3339 UTC, or empty when none was recorded.
	LastHeartbeatAt string `json:"last_heartbeat_at,omitempty"`
	// LastHeartbeatStalenessSeconds is the seconds elapsed since the latest
	// heartbeat, or 0 when none was recorded (or the clock is skewed).
	LastHeartbeatStalenessSeconds int64 `json:"last_heartbeat_staleness_seconds,omitempty"`
}

type CancelResult struct {
	RunID  string `json:"run_id"`
	Status string `json:"status"`
}

type DeleteResult struct {
	RunID   string `json:"run_id"`
	Status  string `json:"status"`
	Deleted bool   `json:"deleted"`
}

type DeliverResult struct {
	RunID   string `json:"run_id"`
	Status  string `json:"status"`
	URL     string `json:"url,omitempty"`
	Mode    string `json:"mode,omitempty"`
	Refused bool   `json:"refused,omitempty"`
	Reason  string `json:"reason,omitempty"`
}

type DeliveryRecord struct {
	RunID          string `json:"run_id"`
	IdempotencyKey string `json:"idempotency_key"`
	Mode           string `json:"mode"`
	BaseRef        string `json:"base_ref"`
	HeadRef        string `json:"head_ref,omitempty"`
	CommitSHA      string `json:"commit_sha,omitempty"`
	TreeSHA        string `json:"tree_sha,omitempty"`
	Provider       string `json:"provider,omitempty"`
	RemoteID       string `json:"remote_id,omitempty"`
	URL            string `json:"url,omitempty"`
	Status         string `json:"status"`
	ErrorRef       string `json:"error_ref,omitempty"`
	DiffRef        string `json:"diff_ref,omitempty"`
	// DeferredFiles is the host-computed split decision of a deferred-split
	// delivery (spec-auto-split-oversized-prs.md §5.2, revised per §10): a
	// JSON-encoded array of workspace-relative paths whose edits ship in a
	// separate follow-up commit on DeferredBranchName, never on the pushed
	// branch. It is recorded on the pending stage record BEFORE the delivered
	// commit is created, so a crash or transient failure mid-split can be
	// resumed by delivery.resumeDeliveryCommitSplit instead of the retry
	// committing or adopting the deferred scope onto the pushed branch
	// (commitWorktreeFollowUp/adoptOwnFollowUpCommit never see a split state).
	// Empty means no split attempt.
	DeferredFiles string `json:"deferred_files,omitempty"`
	// StackRemainingCommits is the count of commits still on the delivered
	// branch after the one that was pushed (git rev-list --count, a derived
	// integer, never an LLM-authored claim), set when a diff-size repair
	// commits a review-sized slice plus deferred scope as trailing commits on
	// the same branch (spec-auto-split-oversized-prs.md §5.2-5.3). Zero means
	// no split: nothing downstream changes from a chunk that delivered
	// cleanly. The stack driver reads this to admit the trailing commits as
	// follow-up chunk runs stacked on this one.
	StackRemainingCommits int       `json:"stack_remaining_commits,omitempty"`
	UpdatedAt             time.Time `json:"updated_at"`
}

type DeliverySnapshot struct {
	Mode     string `json:"mode"`
	Provider string `json:"provider"`
	Base     string `json:"base,omitempty"`
}

type DeliveryView struct {
	IdempotencyKey string `json:"idempotency_key"`
	Status         string `json:"status"`
	Mode           string `json:"mode,omitempty"`
	URL            string `json:"url,omitempty"`
	CommitSHA      string `json:"commit_sha,omitempty"`
	ErrorRef       string `json:"error_ref,omitempty"`
	// ErrorText carries the resolved failure hint for a failed delivery, so
	// the run status surfaces why delivery is pending without an extra lookup.
	ErrorText string `json:"error_text,omitempty"`
}

type Engine interface {
	// Start admits a run and advances it in a background goroutine.
	// It returns as soon as the run ID is durable (non-blocking).
	Start(ctx context.Context, req StartRequest) (StartResult, error)
	// Cancel settles a non-terminal run to canceled (idempotent).
	Cancel(ctx context.Context, runID string) (CancelResult, error)
	// Deliver publishes a delivery_pending run when allow_publish is true.
	Deliver(ctx context.Context, runID string, allowPublish bool) (DeliverResult, error)
	// Delete removes a run from the durable ledger. Settled runs (terminal or
	// delivery_pending) are always deletable; with force, a non-terminal run
	// (pending/running/waiting_approval) is deletable too — the crash-recovery
	// override for runs stranded by a dead executor. A fresh claim held by a
	// live executor is refused either way; only an expired lease is taken over.
	Delete(ctx context.Context, runID string, force bool) (DeleteResult, error)
}

type EventRecord struct {
	ID        string
	Kind      string
	Sequence  int
	CreatedAt time.Time
	Summary   string
}

type EventView struct {
	Seq       int    `json:"seq"`
	Timestamp string `json:"timestamp"`
	Kind      string `json:"kind"`
	Detail    string `json:"detail"`
}

type EventsPage struct {
	RunID  string      `json:"run_id"`
	Events []EventView `json:"events"`
	Limit  int         `json:"limit"`
	Offset int         `json:"offset"`
	Count  int         `json:"count"`
}

type InspectView struct {
	RunID             string          `json:"run_id"`
	Step              string          `json:"step"`
	Attempt           int             `json:"attempt"`
	Status            string          `json:"status"`
	CoordinatorRunID  string          `json:"coordinator_run_id,omitempty"`
	TaskID            string          `json:"task_id,omitempty"`
	Output            any             `json:"output,omitempty"`
	OutputRef         string          `json:"output_ref,omitempty"`
	OutputDigest      string          `json:"output_digest,omitempty"`
	OutputText        string          `json:"output_text,omitempty"`
	OutputBytes       int             `json:"output_bytes,omitempty"`
	OutputOffset      int             `json:"output_offset,omitempty"`
	OutputNextOffset  int             `json:"output_next_offset,omitempty"`
	ErrorRef          string          `json:"error_ref,omitempty"`
	ErrorText         string          `json:"error_text,omitempty"`
	EvidenceSelection any             `json:"evidence_selection,omitempty"`
	Transition        *TransitionView `json:"transition,omitempty"`
	StartedAt         string          `json:"started_at,omitempty"`
	FinishedAt        string          `json:"finished_at,omitempty"`
	ElapsedSeconds    int64           `json:"elapsed_seconds,omitempty"`
}

type ListRunsView struct {
	Runs   []RunListItem `json:"runs"`
	Limit  int           `json:"limit"`
	Offset int           `json:"offset"`
	Count  int           `json:"count"`
}

type LoopCounter struct {
	RunID      string `json:"run_id"`
	LoopName   string `json:"loop_name"`
	Iterations int    `json:"iterations"`
}

type LoopView struct {
	Name       string `json:"name"`
	Iterations int    `json:"iterations"`
}

type PanelBindingSnapshot struct {
	StepID         string `json:"step_id"`
	MemberID       string `json:"member_id"`
	AgentName      string `json:"agent_name"`
	AgentDigest    string `json:"agent_digest"`
	ProviderName   string `json:"provider_name"`
	Model          string `json:"model"`
	SkillDigest    string `json:"skill_digest"`
	TemplateDigest string `json:"template_digest"`
	SchemaDigest   string `json:"schema_digest"`
}

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

type PanelExecution struct {
	Members         []PanelMemberExecution   `json:"members"`
	SynthesisRunID  string                   `json:"synthesis_run_id"`
	SynthesisTaskID string                   `json:"synthesis_task_id"`
	Synthesis       *PanelSynthesisExecution `json:"synthesis,omitempty"`
	Phase           PanelPhase               `json:"phase"`
}

type PanelMemberExecution struct {
	MemberID         string        `json:"member_id"`
	CoordinatorRunID string        `json:"coordinator_run_id"`
	TaskID           string        `json:"task_id"`
	Work             PanelTaskSpec `json:"work"`
	Order            int           `json:"order"`
}

type PanelPhase string

type PanelSynthesisExecution struct {
	Work PanelTaskSpec `json:"work"`
}

type PanelTaskSpec struct {
	TaskName                      string               `json:"task_name"`
	DependsOn                     []string             `json:"depends_on"`
	InputRef                      string               `json:"input_ref"`
	InputDigest                   string               `json:"input_digest"`
	InputSchemaRef                string               `json:"input_schema_ref"`
	InputSchemaDigest             string               `json:"input_schema_digest"`
	Budget                        int                  `json:"budget"`
	Scope                         string               `json:"scope"`
	AgentName                     string               `json:"agent_name"`
	AgentDigest                   string               `json:"agent_digest"`
	Skill                         string               `json:"skill"`
	Provider                      string               `json:"provider"`
	Model                         string               `json:"model"`
	OutputSchemaDigest            string               `json:"output_schema_digest"`
	OutputSchemaRef               string               `json:"output_schema_ref"`
	Timeout                       time.Duration        `json:"timeout"`
	DeadlineAt                    time.Time            `json:"deadline_at"`
	WorkLimits                    PanelWorkLimits      `json:"work_limits"`
	Policy                        ledgercore.RunPolicy `json:"policy"`
	WorkFingerprint               string               `json:"work_fingerprint"`
	CoordinatorRequestFingerprint string               `json:"coordinator_request_fingerprint"`
}

type PanelWorkLimits = runtime.WorkLimits

type Plan struct {
	ID         string    `json:"id"`
	Scope      Scope     `json:"scope"`
	Schema     string    `json:"schema,omitempty"`
	PayloadRef string    `json:"payload_ref,omitempty"`
	CreatedAt  time.Time `json:"created_at,omitempty"`
}

type Projection struct {
	// Run is the current run snapshot. ActiveStepID is the DERIVED active
	// step (see below); all other fields replay the wf_run_created payload
	// plus status changes. nil when no wf events exist for the run.
	Run *RunSnapshot
	// SnapshotJSON is the canonical snapshot blob from wf_run_created.
	SnapshotJSON []byte
	// Attempts is ordered by event sequence.
	Attempts []StepAttempt
	// Transitions is derived from completed attempts that carried a route,
	// ordered by event sequence.
	Transitions  []TransitionRecord
	LoopCounters []LoopCounter
	Approvals    []ApprovalRecord
	Deliveries   []DeliveryRecord
	// ActiveStepID is the transition target of the NEWEST step-bearing event:
	// a completion's to_step_id, else an attempt's step_id, else the initial
	// step from wf_run_created. Loop/approval/delivery/status events carry no
	// step and are skipped. When the newest target is a reserved terminal step
	// ("success"/"failure") the workflow is done even if the run status CAS
	// was never recorded.
	ActiveStepID string
	// HasRun reports whether any wf_run_created event was seen.
	HasRun bool
}

type RecoveredRun struct {
	RunID          string
	WorkflowName   string
	Status         RunStatus
	WasInterrupted bool
	CreatedAt      time.Time
}

type RecoveryPlan struct {
	// Run is the current run snapshot.
	Run RunSnapshot
	// AttemptsInFlight are recorded attempts that never reached a terminal
	// status. Each names its stored CoordinatorRunID/TaskID: the caller must
	// JOIN those coordinator runs (query their recorded outcome) before
	// dispatching anything — a recorded attempt is never re-dispatched.
	AttemptsInFlight []StepAttempt
	// NextAttemptNo is the next fresh attempt number for the active step
	// (max recorded attempt_no for that step + 1).
	NextAttemptNo int
	// Terminal is true when the run cannot resume: it is already terminal, or
	// its derived active step is a reserved terminal step (success/failure)
	// even though the status CAS was not recorded.
	Terminal bool
	// TerminalStatus is the status the caller should record when Terminal is
	// true (succeeded for "success", failed for "failure", else the run's
	// current status).
	TerminalStatus RunStatus
	// Reason is a human-readable explanation.
	Reason string
}

type RefSnapshot struct {
	Digest  string `json:"digest"`
	Version int    `json:"version,omitempty"`
	Bytes   []byte `json:"bytes,omitempty"`
}

type RepoFactory func(ctx context.Context) (Repository, func(), error)

type Repository interface {
	// CreateRun admits a run: persists the run snapshot (typed fields + the
	// canonical snapshot JSON) and records the wf_run_created event. Returns
	// ErrDuplicate if the run already exists, ErrInvalidTransition if the
	// snapshot status is not pending.
	CreateRun(ctx context.Context, snap RunSnapshot, snapshotJSON []byte) error

	// GetRun returns the current run snapshot with the DERIVED active step
	// (see Projection.ActiveStepID). Returns ErrNotFound if absent.
	GetRun(ctx context.Context, runID string) (RunSnapshot, error)

	// ListRuns returns bounded snapshots, optionally filtered by status.
	ListRuns(ctx context.Context, status ...RunStatus) ([]RunSnapshot, error)

	// GetRunSnapshot returns the canonical snapshot JSON stored at admission.
	// Returns ErrNotFound if absent.
	GetRunSnapshot(ctx context.Context, runID string) ([]byte, error)

	// CompareAndSetRunStatus atomically transitions the run status, bumping
	// the run version. Returns ErrConflict on version mismatch, ErrInvalidTransition
	// on an illegal edge. finishedAt is persisted when the new status is terminal.
	CompareAndSetRunStatus(ctx context.Context, runID string, expectedVersion uint64, status RunStatus, finishedAt *time.Time) error

	// CreateStepAttempt records a fresh numbered attempt for a step. The
	// (runID, stepID, attemptNo) triple is unique: a second create for the
	// same triple never appends a second event (ErrDuplicate in-process, or
	// ErrConflict when a concurrent writer took the deterministic event ID).
	CreateStepAttempt(ctx context.Context, attempt StepAttempt) error

	// GetStepAttempt returns one attempt. Returns ErrNotFound if absent.
	GetStepAttempt(ctx context.Context, runID, attemptID string) (StepAttempt, error)

	// ListStepAttempts returns the run's attempts ordered by event sequence.
	ListStepAttempts(ctx context.Context, runID string) ([]StepAttempt, error)

	// CompleteStepAttempt atomically records an attempt's terminal outcome
	// (status + optional route/output evidence in ONE event) under CAS on the
	// attempt version. Returns ErrConflict on version mismatch, ErrInvalidTransition
	// for a non-terminal outcome status or an illegal status edge.
	CompleteStepAttempt(ctx context.Context, runID, attemptID string, expectedVersion uint64, outcome AttemptOutcome) error

	// RecordStepAttemptOutcome records a fresh numbered attempt and its
	// TERMINAL outcome in ONE durable wf_attempt_completed event: the attempt
	// is never observable in a non-terminal state. It mirrors
	// CreateStepAttempt's (runID, stepID, attemptNo) triple and AttemptID
	// uniqueness (ErrDuplicate for a taken key) and CompleteStepAttempt's
	// outcome rules (ErrInvalidTransition for a non-terminal outcome status or
	// an illegal status edge, including the no-route-on-interrupted/canceled/
	// timed_out rule and the MaxEvidenceBytes cap). The recorded attempt
	// carries Version 1 and StartedAt == FinishedAt == the append instant.
	// Returns ErrNotFound if the run is absent.
	RecordStepAttemptOutcome(ctx context.Context, attempt StepAttempt, outcome AttemptOutcome) error

	// CompareAndSetPanelPhase records one claim-fenced panel phase intent.
	CompareAndSetPanelPhase(ctx context.Context, runID string, attemptID string, expectedVersion uint64, from PanelPhase, to PanelPhase, synthesis *PanelSynthesisExecution) error

	// SetStepAttemptPrompt records the content-addressed prompt reference for
	// one attempt (the prompt body lives in content-addressed storage and is
	// looked up via PromptRef; the event log never carries prompt text). The
	// attempt may still be Running — the prompt is persisted at dispatch time,
	// before completion — and its status/version are never changed. Setting the
	// same promptRef twice is an idempotent no-op. Returns ErrNotFound if the
	// run or attempt is absent; ErrConflict if the attempt already carries a
	// prompt ref different from promptRef (attempts are immutable after
	// dispatch) or a concurrent writer took the deterministic event ID with a
	// different payload.
	SetStepAttemptPrompt(ctx context.Context, runID, attemptID, promptRef string) error

	// SetStepAttemptExecution durably records the child identity used by the
	// current execution of an attempt, together with the reason for a
	// re-dispatch when one exists (a transient retry records the provider
	// error text that triggered it; an initial dispatch records none). It is
	// idempotent for the same identity.
	SetStepAttemptExecution(ctx context.Context, runID, attemptID, coordinatorRunID, taskID, reason string) error

	// SetStepAttemptHeartbeat durably records one liveness observation for a
	// RUNNING attempt. Each call appends a DISTINCT wf_attempt_heartbeat event
	// (the event ID embeds the heartbeat timestamp), so successive ticks never
	// conflict and a retried append of the same heartbeat is an idempotent
	// no-op (nil). The attempt's status/version are never changed. Returns
	// ErrNotFound if the run or attempt is absent.
	SetStepAttemptHeartbeat(ctx context.Context, runID, attemptID string, heartbeatAt time.Time) error

	// ListTransitions returns the route decisions derived from completed
	// attempts, ordered by event sequence.
	ListTransitions(ctx context.Context, runID string) ([]TransitionRecord, error)

	// IncrementLoopCounter mints the next iteration number for a named loop
	// under the run claim, after catch-up. Counters are derived state: the
	// returned number is persisted via a wf_loop_incremented event and rebuilt
	// on reopen. Returns ErrNotFound if the run is absent.
	IncrementLoopCounter(ctx context.Context, runID, loopName string) (int, error)

	// GetLoopCounters returns the run's derived loop counters.
	GetLoopCounters(ctx context.Context, runID string) ([]LoopCounter, error)

	// CreateApproval records a pending human-gate request (provisional).
	CreateApproval(ctx context.Context, a ApprovalRecord) error

	// ResolveApproval resolves a pending approval to approved or rejected.
	ResolveApproval(ctx context.Context, runID, approvalID, actor, status, reason string) error

	// ListApprovals returns the run's approval records.
	ListApprovals(ctx context.Context, runID string) ([]ApprovalRecord, error)

	// UpsertDelivery records a delivery attempt keyed by idempotency key.
	UpsertDelivery(ctx context.Context, d DeliveryRecord) error

	// GetDeliveryByIdempotencyKey returns the delivery record for a key.
	// Returns ErrNotFound if absent.
	GetDeliveryByIdempotencyKey(ctx context.Context, key string) (DeliveryRecord, error)

	// ListDeliveries returns the run's delivery records.
	ListDeliveries(ctx context.Context, runID string) ([]DeliveryRecord, error)

	// ListEvents returns the run's audit trail, ordered by event sequence,
	// paged (limit <= 0 means DefaultEventPageSize, offset skips events).
	// Summaries are bounded and never contain raw payloads. Unknown kinds
	// and undecodable payloads are skipped. Returns ErrNotFound when the
	// run is absent.
	ListEvents(ctx context.Context, runID string, limit, offset int) ([]EventRecord, error)

	// DeleteRun removes a settled run's durable record: the wf_run_deleted
	// tombstone plus every prior event and the run's claim are removed from
	// the store, and the in-memory projection is dropped. Shared
	// content-addressed blobs are never deleted. Returns ErrNotFound when
	// the run has no record (never created or already deleted). The caller
	// must hold the execution lock and a claim (or otherwise guarantee no
	// concurrent writer) before calling.
	DeleteRun(ctx context.Context, runID string) error

	// RecordRunResumed appends the wf_run_resumed audit event for a run that
	// is being resumed (crash recovery, operator resume, or controller
	// re-entry). It mutates no run state; the event is purely observational.
	// Returns ErrNotFound when the run is absent.
	RecordRunResumed(ctx context.Context, runID string) error

	// ClaimRun acquires the exclusive execution claim on a run. Returns
	// ErrClaimHeld if another holder owns it. Same-holder refresh succeeds.
	ClaimRun(ctx context.Context, runID, holder string) error

	// RefreshRunClaim refreshes the claim's acquired_at ONLY when holder
	// already owns the claim row. It never inserts a missing row: a holder
	// whose claim is gone returns ErrClaimNotHeld. Run execution heartbeats
	// use this so a displaced or expired holder is treated as lost instead of
	// reclaiming itself (F2).
	RefreshRunClaim(ctx context.Context, runID, holder string) error

	// TakeoverRunClaim atomically replaces any existing claim with holder.
	TakeoverRunClaim(ctx context.Context, runID, holder string) error
	TakeoverExpiredRunClaim(ctx context.Context, runID, holder string, maxAge time.Duration) error

	// ReleaseRun releases the claim; only the current holder may. Returns
	// ErrClaimNotHeld otherwise.
	ReleaseRun(ctx context.Context, runID, holder string) error

	// ClearRunClaim force-releases any claim regardless of holder (explicit
	// operator force-release for stale claims; Recover clears claims only on
	// terminal runs).
	ClearRunClaim(ctx context.Context, runID string) error

	// GetRunClaim reads the run's current execution claim as a read-only
	// liveness probe: the holder and the claim's last acquired_at (the
	// holder's heartbeat refreshes it). ok=false means the run has no claim
	// or the backend cannot expose claims; err is reserved for backend
	// failures. It never mutates claim state.
	GetRunClaim(ctx context.Context, runID string) (holder string, acquiredAt time.Time, ok bool, err error)

	// StoreContent persists bytes under a content-addressed reference
	// (shared content store; idempotent).
	StoreContent(ctx context.Context, ref string, data []byte) error

	// LoadContent retrieves stored bytes. Returns ErrContentNotFound if absent.
	LoadContent(ctx context.Context, ref string) ([]byte, error)

	// Recover brings the projection up to date, classifies every run, and
	// clears stale claims on terminal runs only. It mutates no run status.
	Recover(ctx context.Context) ([]RecoveredRun, error)
}

type RunListItem struct {
	RunID     string `json:"run_id"`
	Workflow  string `json:"workflow"`
	Status    string `json:"status"`
	Age       string `json:"age,omitempty"`
	StartedAt string `json:"started_at,omitempty"`
	// ActiveStep is the run's current step id, empty for a terminal run or
	// one that hasn't started its first step yet.
	ActiveStep string `json:"active_step,omitempty"`
	// LastHeartbeatAt mirrors AttemptView's field of the same name, for the
	// active step's newest attempt - RFC3339 UTC, empty when the run is
	// terminal, has no active step, or that attempt hasn't heartbeated yet.
	// A caller rendering a live list (e.g. a desktop app's run list) needs
	// this without a second per-run round trip through workflow_status.
	LastHeartbeatAt string `json:"last_heartbeat_at,omitempty"`
	// DeliveryClaimHeld and DeliveryClaimAt mirror the TUI's own delivery
	// liveness surface (internal/cli/workflow_run_dialog.go's
	// workflowRunDeliveryClaim / workflowDeliveryClaimLine): only populated
	// for a DELIVERY_PENDING run. Held=true with a fresh ClaimAt means a
	// delivery attempt is actually in flight right now; Held=true with a
	// stale ClaimAt means one crashed mid-publish; Held=false means the run
	// is simply parked waiting for someone to call workflow_deliver. Without
	// this a caller has no way to distinguish "actively delivering" from
	// "waiting indefinitely" for a DELIVERY_PENDING run - LastHeartbeatAt
	// freezes once the run's last step attempt finishes and says nothing
	// about delivery activity.
	DeliveryClaimHeld bool   `json:"delivery_claim_held,omitempty"`
	DeliveryClaimAt   string `json:"delivery_claim_at,omitempty"`
}

type RunSnapshot struct {
	RunID            string     `json:"run_id"`
	InvocationKey    string     `json:"invocation_key,omitempty"`
	WorkflowName     string     `json:"workflow_name"`
	WorkflowDigest   string     `json:"workflow_digest"`
	SnapshotDigest   string     `json:"snapshot_digest"`
	InputDigest      string     `json:"input_digest"`
	Status           RunStatus  `json:"status"`
	ActiveStepID     string     `json:"active_step_id"`
	BaseRef          string     `json:"base_ref,omitempty"`
	BaseCommit       string     `json:"base_commit,omitempty"`
	OriginBaseCommit string     `json:"origin_base_commit,omitempty"`
	WorktreeName     string     `json:"worktree_name,omitempty"`
	RemoteURL        string     `json:"remote_url,omitempty"`
	Version          uint64     `json:"version"`
	StartedAt        time.Time  `json:"started_at"`
	DeadlineAt       *time.Time `json:"deadline_at,omitempty"`
	FinishedAt       *time.Time `json:"finished_at,omitempty"`
}

type RunStatus string

type Scope struct {
	Type string `json:"type"`
	ID   string `json:"id"`
}

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

type ServiceOptions struct {
	// Engine performs run/cancel/deliver. Nil refuses mutating calls.
	Engine Engine
	// Repo opens the workflow ledger. Required for read tools.
	Repo RepoFactory
	// Optional result budget overrides (bytes). Zero keeps package defaults.
	StatusBudgetBytes  int
	EventsBudgetBytes  int
	InspectBudgetBytes int
	ListBudgetBytes    int
}

type Snapshot struct {
	SchemaVersion    int    `json:"schema_version"`
	DefinitionTOML   []byte `json:"definition_toml"`
	DefinitionDigest string `json:"definition_digest"`
	// MCPConfigDigest pins the enabled MCP authority without storing server
	// commands, URLs, headers, environment names, or values.
	MCPConfigDigest string                          `json:"mcp_config_digest,omitempty"`
	Inputs          map[string]string               `json:"inputs,omitempty"`
	Agents          map[string]AgentSnapshot        `json:"agents,omitempty"`
	PanelBindings   map[string]PanelBindingSnapshot `json:"panel_bindings,omitempty"`
	Schemas         map[string]RefSnapshot          `json:"schemas,omitempty"`
	Templates       map[string]RefSnapshot          `json:"templates,omitempty"`
	Skills          map[string]RefSnapshot          `json:"skills,omitempty"`
	Verifiers       map[string]RefSnapshot          `json:"verifiers,omitempty"`
	// VerifierPinsVersion marks snapshots admitted by a binary that pins
	// verifier definitions (verifier-def: keys in Verifiers). 0 means the run
	// predates definition pinning and resumes without definition
	// verification; >= 1 means a referenced definition whose key is absent
	// was stripped, not merely never written, and resume fails closed.
	VerifierPinsVersion int               `json:"verifier_pins_version,omitempty"`
	Delivery            *DeliverySnapshot `json:"delivery,omitempty"`
}

type StartRequest struct {
	// Workflow is the discovered workflow name (required for a new run).
	Workflow string
	// Inputs are validated name→value pairs from the tool call.
	Inputs map[string]any
	// InvocationKey identifies one caller request across retries. When set for
	// a new run, the engine derives a stable run ID and admits it once.
	InvocationKey string
	// AllowPublish is the explicit publication gate for the workflow_deliver
	// tool and the CLI --allow-publish flag. The session harness does NOT
	// consult it for auto-delivery: a workflow whose [delivery] policy is
	// active is published automatically (the policy is the publication
	// grant), so a delivery-capable run is never stranded by a missing flag.
	AllowPublish bool
	// Resume, when true, resumes RunID from the durable ledger snapshot.
	Resume bool
	// RunID is required when Resume is true.
	RunID string
	// Force clears a stale claim before resume (operator-confirmed).
	Force bool
}

type StartResult struct {
	RunID    string `json:"run_id"`
	Status   string `json:"status"`
	Workflow string `json:"workflow,omitempty"`
	Resumed  bool   `json:"resumed,omitempty"`
}

type StatusView struct {
	RunID      string         `json:"run_id"`
	Workflow   string         `json:"workflow"`
	Status     string         `json:"status"`
	ActiveStep string         `json:"active_step"`
	Version    uint64         `json:"version"`
	StartedAt  string         `json:"started_at,omitempty"`
	DeadlineAt string         `json:"deadline_at,omitempty"`
	FinishedAt string         `json:"finished_at,omitempty"`
	BaseRef    string         `json:"base_ref,omitempty"`
	BaseCommit string         `json:"base_commit,omitempty"`
	Worktree   string         `json:"worktree,omitempty"`
	Attempts   []AttemptView  `json:"attempts"`
	Loops      []LoopView     `json:"loops,omitempty"`
	Delivery   []DeliveryView `json:"delivery,omitempty"`
	Approvals  []ApprovalView `json:"approvals,omitempty"`
	// DeliveryClaimHeld/DeliveryClaimAt mirror RunListItem's fields of the
	// same name - see that doc comment. Only populated for a
	// DELIVERY_PENDING run.
	DeliveryClaimHeld bool   `json:"delivery_claim_held,omitempty"`
	DeliveryClaimAt   string `json:"delivery_claim_at,omitempty"`
}

type StepAttempt struct {
	AttemptID        string          `json:"attempt_id"`
	RunID            string          `json:"run_id"`
	StepID           string          `json:"step_id"`
	AttemptNo        int             `json:"attempt_no"`
	Status           AttemptStatus   `json:"status"`
	CoordinatorRunID string          `json:"coordinator_run_id,omitempty"`
	TaskID           string          `json:"task_id,omitempty"`
	Executions       []StepExecution `json:"executions,omitempty"`
	OutputRef        string          `json:"output_ref,omitempty"`
	OutputDigest     string          `json:"output_digest,omitempty"`
	ErrorRef         string          `json:"error_ref,omitempty"`
	ToStepID         string          `json:"to_step_id,omitempty"`
	TransitionIndex  int             `json:"transition_index,omitempty"`
	MatchDigest      string          `json:"match_digest,omitempty"`
	PromptRef        string          `json:"prompt_ref,omitempty"`
	DecisionJSON     []byte          `json:"decision_json,omitempty"`
	EvidenceJSON     []byte          `json:"evidence_json,omitempty"`
	PanelExecution   *PanelExecution `json:"panel_execution,omitempty"`
	LastHeartbeatAt  time.Time       `json:"last_heartbeat_at,omitempty"`
	StartedAt        time.Time       `json:"started_at"`
	FinishedAt       *time.Time      `json:"finished_at,omitempty"`
	Version          uint64          `json:"version"`
}

type StepExecution struct {
	ExecutionNo      int       `json:"execution_no"`
	CoordinatorRunID string    `json:"coordinator_run_id"`
	TaskID           string    `json:"task_id"`
	StartedAt        time.Time `json:"started_at"`
}

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

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

type Task struct {
	ID        string   `json:"id"`
	PlanRef   string   `json:"plan_ref"`
	Scope     Scope    `json:"scope"`
	Status    string   `json:"status"`
	RunRef    string   `json:"run_ref,omitempty"`
	PRNumber  string   `json:"pr_number,omitempty"`
	Deps      []string `json:"deps,omitempty"`
	Attempts  int      `json:"attempts,omitempty"`
	LastError string   `json:"last_error,omitempty"`
}

type Tool interface {
	Name() string
	Description() string
	Parameters() map[string]any
	Execute(ctx context.Context, args json.RawMessage) (string, error)
	ResultBudgetBytes() int
	// Class is "read" or "write" for capability scheduling.
	Class() string
}

type Transition struct {
	PlanRef    string    `json:"plan_ref"`
	TaskID     string    `json:"task_id"`
	FromStatus string    `json:"from_status"`
	ToStatus   string    `json:"to_status"`
	At         time.Time `json:"at"`
}

type TransitionRecord struct {
	RunID           string    `json:"run_id"`
	FromAttemptID   string    `json:"from_attempt_id"`
	ToStepID        string    `json:"to_step_id"`
	TransitionIndex int       `json:"transition_index"`
	MatchDigest     string    `json:"match_digest"`
	DecisionJSON    []byte    `json:"decision_json"`
	CreatedAt       time.Time `json:"created_at"`
}

type TransitionView struct {
	Index       int            `json:"index"`
	ToStep      string         `json:"to_step,omitempty"`
	MatchDigest string         `json:"match_digest,omitempty"`
	Selected    map[string]any `json:"selected,omitempty"`
}