controller

type Admission struct {
	InvocationKey    string
	BaseRef          string
	BaseCommit       string
	OriginBaseCommit string
	WorktreeName     string
	InputDigest      string
	DeadlineAt       *time.Time
	RemoteURL        string
	// WorkflowDigest is the digest RECORDED when the run was admitted. A
	// resume must pass it; a fresh admission leaves it empty.
	//
	// The digest is a hash of the marshalled definition struct, so it moves
	// whenever those types gain a field, even when the workflow text does not
	// change by one byte. Comparing a resumed run against a digest THIS binary
	// recomputed therefore asserts that this binary hashes the definition the
	// way the admitting binary did, which is a fact about the binary. Two
	// field additions moved it in one day, and every run admitted before them
	// became permanently unresumable.
	//
	// The definition text is proven by other means on the resume path: the
	// snapshot digest covers the raw snapshot bytes, StartNew compares those
	// bytes directly, and the two recorded digests are compared to each other.
	WorkflowDigest string
}

type AgentStepRequest struct {
	WorkflowRunID    string
	StepID           string
	AttemptNo        int
	TaskID           string
	CoordinatorRunID string
	AgentName        string
	AgentDigest      string
	Skill            string
	ProviderName     string
	Model            string
	Scope            string
	Permission       string
	Timeout          time.Duration
	Budget           int
	ForceResume      bool
	Template         string
	Inputs           map[string]any
	Evidence         map[string]any
	MaxBindingBytes  int
	MaxContextBytes  int
	OutputSchema     map[string]any
	// Prompt is the fully rendered step prompt (including the evidence-refs
	// block), produced by the controller. An empty value means the runner
	// must render the prompt from Template/Inputs/Evidence.
	Prompt string
	// EvidenceRefs names the artifact references bound into the prompt,
	// keyed by evidence name. Nil when the step binds no artifact
	// references.
	EvidenceRefs map[string]ArtifactRef
}

type AgentStepResult struct {
	CoordinatorRunID string
	TaskID           string
	Output           json.RawMessage
	ValidatedOutput  any
	EvidenceJSON     []byte
	// Status is the child task's terminal status from the coordinator result
	// ("completed", "failed", "timed_out", "canceled", "blocked"). It is
	// empty when the step runner produced no child result (for example a
	// pre-dispatch failure).
	Status string
	// ErrorRef names content-addressed failure detail for a failed attempt.
	// It is set by the controller from the step error; an empty value means
	// no error detail was persisted.
	ErrorRef string
}

type AgentStepRunner interface {
	RunStep(context.Context, AgentStepRequest) (AgentStepResult, error)
}

type ArtifactRef struct {
	Step    string `json:"step"`
	Attempt int    `json:"attempt"`
	Ref     string `json:"ref"`
	Bytes   int    `json:"bytes"`
	Digest  string `json:"digest"`
}

type CanonicalSourceKey struct {
	MemberID  string
	FindingID string
}

type ChunkPlanValidation struct {
	Valid   bool
	Reasons []string
}

type CoordinatorRunner struct {
	Coordinator coordinator.Coordinator
	// JoinWatchdog bounds a coordinator join from the controller side. The
	// coordinator's own Join (internal/coordinator/coordinator.go) waits on
	// the child run's done channel with no bound of its own, so a child that
	// never settles (hung pool worker, stuck referral wait, dead executor)
	// would park the controller forever. A value <= 0 uses
	// defaultJoinWatchdog; tests set it short to exercise the join-timeout
	// path.
	JoinWatchdog time.Duration
	// RegisterChildRun is an optional host hook. The runner calls it once per
	// ensured child run, right after EnsureRun returns a handle whose run ID
	// matches the request. The host uses it to register the child in the
	// orchestration handle registry, so the standard control tools
	// (inspect_agents, join_run, cancel_run) can reach the child. The hook is
	// nil-safe, and the controller stays free of any registry dependency: the
	// host owns the owner identity and calls the registry seam.
	RegisterChildRun func(ctx context.Context, runID string, handle *coordinator.RunHandle)
	// contains filtered or unexported fields
}

type LinearController struct {
	Repo           workflowledger.Repository
	Runner         AgentStepRunner
	Workflow       *definition.CompiledWorkflow
	Steps          map[string]StepRuntime
	Inputs         map[string]any
	RunID          string
	Snapshot       []byte
	Holder         string
	Verifiers      *definition.Catalogue
	WorkDir        string
	ModuleBaseline *definition.GoModuleBaseline
	SecretPolicy   secretpath.Policy

	// WritePathBlocklist is the host write-path denylist for workflow agents
	// (internal/tools enforced): paths under it can never be written by an
	// agent step. The controller uses it to recognize a succeeded step whose
	// output admits a write it cannot perform (blocked_paths, a claimed
	// files_changed entry, or a review finding demanding a blocked edit) and
	// fail the run honestly instead of looping it into review.
	WritePathBlocklist []string
	PanelLimiter       *PanelActorLimiter
	// PanelLimits bounds every agent_panel step's member and synthesis
	// children (panel_attempt.go/panel_synthesis.go). Defaults to
	// DefaultPanelLimits(); a host overrides it via SetPanelLimits
	// before Start, resolved from [workflows.panels] config.
	PanelLimits PanelLimits
	// contains filtered or unexported fields
}

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

type PanelCancelCoordinator interface {
	CancelOrTombstoneMember(ctx context.Context, attemptID, memberID string) (bool, error)
	CancelOrTombstoneSynthesis(ctx context.Context, attemptID string) (bool, error)
}

type PanelDisposition string

type PanelFinalReport struct {
	HostVerdict  string                   `json:"host_verdict"`
	Dispositions []PanelSourceDisposition `json:"dispositions"`
	Summary      string                   `json:"summary"`
}

type PanelFinding struct {
	ID          string `json:"id"`
	Title       string `json:"title"`
	Severity    string `json:"severity"`
	Description string `json:"description"`
}

type PanelLimits struct {
	MemberMaxOutputPerCall    int
	MemberMaxToolCalls        int
	SynthesisMaxOutputPerCall int
	SynthesisMaxToolCalls     int
	// MemberDeadlineDefault bounds one panel member attempt's wall
	// clock when the workflow declares no run deadline
	// (max_duration_seconds = 0). The workflow's declared deadline is
	// the real contract and always wins when earlier; this default
	// only fills the gap so the durable PanelTaskSpec keeps its
	// fail-closed non-zero DeadlineAt invariant. Long multi-hour
	// agentic reviews are the intended workload (bug-fix.toml
	// documents "24h+ agentic reviews" with max_duration_seconds = 0),
	// so the default is generous; workflow authors tighten it by
	// declaring max_duration_seconds, or a host lowers the default via
	// config.
	MemberDeadlineDefault time.Duration
}

type PanelMemberCoordinator interface {
	EnsureMember(context.Context, string, string) (*coordinator.RunHandle, error)
	JoinMember(context.Context, string, string, *coordinator.RunHandle) (*coordinator.RunResult, error)
}

type PanelMemberPermitProbe interface {
	MemberNeedsActorPermit(context.Context, string, string) (bool, error)
}

type PanelMemberProvenance struct {
	StepID            string `json:"step_id"`
	MemberID          string `json:"member_id"`
	AgentName         string `json:"agent_name"`
	AgentDigest       string `json:"agent_digest"`
	Provider          string `json:"provider"`
	Model             string `json:"model"`
	CoordinatorRunID  string `json:"coordinator_run_id"`
	CoordinatorTaskID string `json:"coordinator_task_id"`
	TerminalStatus    string `json:"terminal_status"`
	OutputDigest      string `json:"output_digest"`
	FindingCount      int    `json:"finding_count"`
	SourceKeyDigest   string `json:"source_key_digest"`
}

type PanelMemberRemoteJoiner interface {
	EnsureRemoteMember(context.Context, string, string) (*coordinator.RunHandle, error)
}

type PanelMemberReport struct {
	Verdict  string         `json:"verdict"`
	Findings []PanelFinding `json:"findings"`
}

type PanelMemberRequest struct {
	MemberID string
	RunID    string
}

type PanelMemberResult struct {
	MemberID string
	Result   *coordinator.RunResult
	Err      error
}

type PanelMembersRequest struct {
	AttemptID   string
	Members     []PanelMemberRequest
	Coordinator PanelMemberCoordinator
}

type PanelMembersResult struct {
	Members []PanelMemberResult
}

type PanelSourceDisposition struct {
	MemberID       string           `json:"member_id"`
	FindingID      string           `json:"finding_id"`
	Disposition    PanelDisposition `json:"disposition"`
	FinalFindingID string           `json:"final_finding_id"`
}

type PanelSynthesisEnvelope struct {
	StepID      string                         `json:"step_id"`
	HostVerdict string                         `json:"host_verdict"`
	Members     []PanelSynthesisMemberEnvelope `json:"members"`
	// DroppedFindings records, per member id, the finding ids the host
	// chunk-scope filter removed before synthesis. Nil when nothing was
	// dropped. Host-authored audit data: it lets an auditor reconcile the
	// member raw output digest against the filtered report in the envelope.
	DroppedFindings map[string][]string `json:"dropped_findings,omitempty"`
}

type PanelSynthesisMemberEnvelope struct {
	Provenance PanelMemberProvenance `json:"provenance"`
	Report     PanelMemberReport     `json:"report"`
}

type PanelSynthesisMemberInput struct {
	MemberID          string
	AgentName         string
	AgentDigest       string
	Provider          string
	Model             string
	CoordinatorRunID  string
	CoordinatorTaskID string
	TerminalStatus    string
	RawOutput         []byte
}

type PanelSynthesisOutput struct {
	Dispositions []PanelSourceDisposition `json:"dispositions"`
	Summary      string                   `json:"summary"`
}

type ProgressEvent struct {
	Kind             ProgressKind
	RunID            string
	StepID           string
	TaskID           string
	CoordinatorRunID string
	AttemptNo        int
	Detail           string
	Timestamp        time.Time
}

type ProgressKind string

type ProgressSink interface {
	// Emit delivers one progress event to the consumer.
	Emit(ProgressEvent)
}

type RouteDecision struct {
	ToStepID        string
	TransitionIndex int
	MatchDigest     string
	DecisionJSON    []byte
	// Loop is set when the selected transition is a named back-edge.
	// The controller checks the loop cap before route selection returns, and
	// increments the counter only after the attempt completion is durable.
	Loop          string
	MaxIterations int
	// PartialAccept marks a loop-exhaustion escape: the run advanced to the
	// declared partial_target with verified outputs salvaged into evidence.
	PartialAccept bool
}

type SalvagedAttempt struct {
	StepID       string `json:"step_id"`
	AttemptNo    int    `json:"attempt_no"`
	OutputRef    string `json:"output_ref,omitempty"`
	OutputDigest string `json:"output_digest,omitempty"`
}

type SchemaValidationError struct {
	StepID string
	Err    error
}

type StepRunJoiner interface {
	// JoinStep joins the coordinator run named by spec.CoordinatorRunID and
	// waits for its terminal outcome. joined=true means the child ran (or is
	// being joined to completion) and result carries its terminal status
	// ("completed", "failed", "timed_out", "canceled"); the caller must
	// complete the attempt with that outcome instead of re-dispatching.
	// joined=false means there was nothing to join (the child never ran, the
	// run is unknown, or the join could not be completed) and the caller may
	// interrupt the stale attempt and re-dispatch fresh.
	JoinStep(context.Context, AgentStepRequest) (AgentStepResult, bool, error)
}

type StepRuntime struct {
	Agent        agents.ResolvedAgent
	Digest       string
	ProviderName string
	Model        string
	Template     string
	Schema       map[string]any
}