workflow

type ClaimLeaseInput struct {
	WorkflowRunID  string
	Owner          string
	Now            time.Time
	LeaseExpiresAt time.Time
}

type CreateNodeRunInput struct {
	NodeID            string
	NodeIndex         int
	NodeType          string
	Needs             []string
	IssueAccess       string
	TargetAgentID     *string
	AgentName         string
	AgentDescription  string
	AgentInstructions string
	AgentRevision     int
	Prompt            string
	Bindings          []StepBinding
	OutputSchema      *string
	Status            string
}

type CreateRunInput struct {
	WorkflowID       string
	WorkflowRevision int
	IssueID          *string
	// Input is the run's immutable input JSON, already validated against the
	// definition's input_schema. Nil when the definition declares no input_schema.
	Input     *string
	Status    string
	CreatedBy string
	StartedAt *time.Time
}

type Definition struct {
	// SchemaVersion names the definition contract this plan is written for. It must
	// equal DefinitionSchemaVersion; publication refuses anything else rather than
	// guessing an unversioned shape.
	SchemaVersion int `json:"schema_version"`
	// InputSchema, when set, is a JSON Schema (in the shared subset) that a run's
	// immutable input must satisfy at admission and that drives the Portal input
	// form. Absent means the run takes no declared input. Publication rejects a
	// schema outside the subset.
	InputSchema json.RawMessage `json:"input_schema,omitempty"`
	// Policy, when set, carries run-wide execution policy. Absent leaves every
	// field at its default.
	Policy *DefinitionPolicy `json:"policy,omitempty"`
	// Nodes is the definition's unordered set of nodes. JSON represents it as an
	// array, but array position is not control flow: a node's dependencies come
	// from its `needs` edges, and the execution order is the topological order of
	// the resulting DAG.
	Nodes []DefinitionNode `json:"nodes"`
	// Result, when set, selects the WorkflowRun result from one node's output
	// envelope. The selected node must exist. Absent leaves the run without a
	// declared result.
	Result *ResultSelector `json:"result,omitempty"`
}

type DefinitionNode struct {
	ID   string `json:"id"`
	Type string `json:"type"`
	// Needs lists the ids of the nodes that must succeed before this one becomes
	// ready. It forms a directed acyclic graph; array position is not control
	// flow. An empty list is a root that is ready at run start.
	Needs []string `json:"needs,omitempty"`
	// Agent names the Agent this node runs as.
	Agent NodeAgent `json:"agent"`
	// Input is the node's task instruction and the values bound into it.
	Input NodeInput `json:"input"`
	// IssueAccess controls whether this node's Task receives the run's Issue.
	// One of "none" (default), "if_bound", or "required". Empty means "none".
	IssueAccess string `json:"issue_access,omitempty"`
	// OutputSchema, when set, is a JSON Schema (in the shared subset) the node's
	// agent run must satisfy as its final answer. Publication rejects a schema
	// outside the subset. The node succeeds only when the run returns a value
	// that validates against it. Empty leaves the node free text. See
	// docs/design/structured-output.md.
	OutputSchema json.RawMessage `json:"output_schema,omitempty"`
}

type DefinitionPolicy struct {
	// MaxParallelNodes bounds how many of a run's nodes may execute at once. Zero
	// (absent) means no definition-set limit, so the run uses the deployment
	// ceiling. Publication rejects a value above MaxParallelNodesCeiling.
	MaxParallelNodes int `json:"max_parallel_nodes,omitempty"`
}

type FinalizeFailedRunInput struct {
	WorkflowRunID string
	NodeRunID     string
	NodeExpected  NodeRunStatus
	NodeStatus    NodeRunStatus
	RunExpected   RunStatus
	RunStatus     RunStatus
	TaskRunID     *string
	ErrorMessage  *string
	StartedAt     *time.Time
	EndedAt       *time.Time
}

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

type NodeAgent struct {
	ID       string `json:"id"`
	Revision int    `json:"revision,omitempty"`
}

type NodeInput struct {
	Instruction string `json:"instruction"`
	// Bindings feed selected values into this node's input. Each names a value
	// (Name) taken from a source (the run's input, or a transitive predecessor
	// node's output envelope) at an RFC 6901 pointer. The bound value reaches the
	// Task as labelled untrusted context, never the agent's instructions.
	Bindings []StepBinding `json:"bindings,omitempty"`
}

type NodeOutputArtifact struct {
	ID        string `json:"id"`
	Path      string `json:"path,omitempty"`
	MediaType string `json:"media_type,omitempty"`
}

type NodeOutputEnvelope struct {
	Text       string               `json:"text"`
	Structured json.RawMessage      `json:"structured"`
	Artifacts  []NodeOutputArtifact `json:"artifacts"`
	TaskID     string               `json:"task_id,omitempty"`
	TaskRunID  string               `json:"task_run_id,omitempty"`
}

type NodeRun struct {
	ID            string `json:"id"`
	WorkflowRunID string `json:"workflow_run_id"`
	NodeID        string `json:"node_id"`
	NodeIndex     int    `json:"node_index"`
	NodeType      string `json:"node_type"`
	// Needs is the run's snapshot of this node's dependency edges (the ids of the
	// nodes that must succeed before it becomes ready), taken at start so a later
	// definition edit cannot change what an in-flight run waits on.
	Needs []string `json:"needs,omitempty"`
	// IssueAccess is the run's snapshot of this node's Issue access mode, so a
	// later definition edit cannot change what an in-flight node's Task can reach.
	IssueAccess   string  `json:"issue_access,omitempty"`
	TargetAgentID *string `json:"target_agent_id,omitempty"`
	// AgentName, AgentDescription, and AgentInstructions capture the target agent
	// definition as it was when the run started, so later edits to the agent cannot
	// change what a step in flight sends to the model.
	AgentName         string `json:"agent_name,omitempty"`
	AgentDescription  string `json:"agent_description,omitempty"`
	AgentInstructions string `json:"agent_instructions,omitempty"`
	AgentRevision     int    `json:"agent_revision,omitempty"`
	Prompt            string `json:"prompt"`
	// Bindings is the run's snapshot of this node's input bindings, taken at start
	// so a later definition edit cannot change what an in-flight node receives.
	Bindings []StepBinding `json:"bindings,omitempty"`
	// OutputSchema is the run's snapshot of this node's output schema, taken at
	// start so a later definition edit cannot change what an in-flight node must
	// satisfy. Nil for a free-text node.
	OutputSchema *string `json:"output_schema,omitempty"`
	Status       string  `json:"status"`
	TaskID       *string `json:"task_id,omitempty"`
	TaskRunID    *string `json:"task_run_id,omitempty"`
	// ResolvedInput is the full Task input this node received -- its prompt with
	// every binding materialized -- captured when the node started so the run
	// record shows exactly what the agent was given. Nil until the node is
	// dispatched.
	ResolvedInput *string `json:"resolved_input,omitempty"`
	// Output is the node's full output: the whole text its accepted TaskRun
	// produced, not a truncated summary, so downstream bindings and the run
	// result read it without re-reading the Task plane. Nil until the node
	// succeeds, or when it produced no text.
	Output *string `json:"output,omitempty"`
	// Structured is the validated structured-output value the accepted run
	// produced, as JSON text. Nil for a free-text step, or when the value did not
	// validate (which fails the step).
	Structured   *string    `json:"structured,omitempty"`
	ErrorMessage *string    `json:"error_message,omitempty"`
	CreatedAt    time.Time  `json:"created_at"`
	StartedAt    *time.Time `json:"started_at,omitempty"`
	EndedAt      *time.Time `json:"ended_at,omitempty"`
}

type NodeRunStatus string

type ReleaseLeaseInput struct {
	WorkflowRunID   string
	Owner           string
	NextReconcileAt *time.Time
}

type RenewLeaseInput struct {
	WorkflowRunID  string
	Owner          string
	LeaseExpiresAt time.Time
}

type ResultSelector struct {
	Source  string `json:"source"`
	Pointer string `json:"pointer"`
}

type Revision struct {
	WorkflowID  string    `json:"workflow_id"`
	Revision    int       `json:"revision"`
	Name        string    `json:"name"`
	Description string    `json:"description"`
	Definition  string    `json:"definition"`
	Status      string    `json:"status"`
	CreatedBy   string    `json:"created_by"`
	CreatedAt   time.Time `json:"created_at"`
}

type Run struct {
	ID         string `json:"id"`
	WorkflowID string `json:"workflow_id"`
	// WorkflowRevision is the workflow revision this run expanded. It is 0 for
	// runs started before workflows recorded revisions.
	WorkflowRevision int     `json:"workflow_revision,omitempty"`
	IssueID          *string `json:"issue_id,omitempty"`
	// Input is the run's immutable input JSON, validated against the definition's
	// input_schema at admission. Nil when the definition declares no input_schema.
	Input     *string `json:"input,omitempty"`
	Status    string  `json:"status"`
	CreatedBy string  `json:"created_by"`
	// Result is the run's declared result JSON: the value the definition's result
	// selector resolved to when the run succeeded, stored independently of the
	// node runs so a reader has one authoritative answer. Nil when the definition
	// declares no result or the run did not succeed. Immutable once set.
	Result       *string    `json:"result,omitempty"`
	CreatedAt    time.Time  `json:"created_at"`
	StartedAt    *time.Time `json:"started_at,omitempty"`
	EndedAt      *time.Time `json:"ended_at,omitempty"`
	ErrorMessage *string    `json:"error_message,omitempty"`
	// Reconciliation scheduling and ownership. ReconcileOwner and LeaseExpiresAt
	// are a bounded lease that reduces duplicate reconciliation work; they are not
	// the correctness mechanism. NextReconcileAt is when this run next wants a
	// reconciliation pass. All three are cleared when the run becomes terminal.
	ReconcileOwner  *string    `json:"reconcile_owner,omitempty"`
	LeaseExpiresAt  *time.Time `json:"lease_expires_at,omitempty"`
	NextReconcileAt *time.Time `json:"next_reconcile_at,omitempty"`
}

type RunStatus string

type StepBinding struct {
	Name    string `json:"name"`
	Source  string `json:"source"`
	Pointer string `json:"pointer"`
}

type Store interface {
	ListWorkflowsBySpace(ctx context.Context, spaceID string) ([]Workflow, error)
	CreateWorkflow(ctx context.Context, spaceID, createdBy, name, description, definition string) (*Workflow, error)
	GetWorkflow(ctx context.Context, workflowID string) (*Workflow, error)
	UpdateWorkflow(ctx context.Context, workflowID, spaceID string, in UpdateInput) (*Workflow, error)
	CreateWorkflowRun(ctx context.Context, in CreateRunInput) (*Run, error)
	ListWorkflowRunsByWorkflow(ctx context.Context, workflowID string, limit, offset int) ([]Run, int, error)
	ListWorkflowRunsByIssue(ctx context.Context, issueID string, limit, offset int) ([]Run, int, error)
	GetWorkflowRun(ctx context.Context, workflowRunID string) (*Run, error)
	ListWorkflowNodeRuns(ctx context.Context, workflowRunID string) ([]NodeRun, error)
	CreateWorkflowNodeRuns(ctx context.Context, workflowRunID string, steps []CreateNodeRunInput) ([]NodeRun, error)
	// TransitionWorkflowRun and TransitionWorkflowNodeRun apply one guarded
	// status change each; a false result means the row was not at the expected
	// status, so another actor won the transition. FinalizeFailedWorkflowRun
	// ends a run and blocks its remaining steps in one transaction.
	TransitionWorkflowRun(ctx context.Context, in TransitionRunInput) (bool, error)
	TransitionWorkflowNodeRun(ctx context.Context, in TransitionNodeRunInput) (bool, error)
	FinalizeFailedWorkflowRun(ctx context.Context, in FinalizeFailedRunInput) (bool, error)
	// ListDueWorkflowRuns returns non-terminal runs that need a reconciliation
	// pass at now -- their scheduled time has arrived or their lease expired --
	// in stable oldest-due order, bounded by limit (a documented default when
	// limit <= 0). ClaimWorkflowRunLease, RenewWorkflowRunLease, and
	// ReleaseWorkflowRunLease are guarded writes: a false result means the run was
	// terminal, already leased to another unexpired owner, or held by someone
	// else, so this caller did not win the lease.
	ListDueWorkflowRuns(ctx context.Context, now time.Time, limit int) ([]Run, error)
	ClaimWorkflowRunLease(ctx context.Context, in ClaimLeaseInput) (bool, error)
	RenewWorkflowRunLease(ctx context.Context, in RenewLeaseInput) (bool, error)
	ReleaseWorkflowRunLease(ctx context.Context, in ReleaseLeaseInput) (bool, error)
	GetWorkflowNodeRunByTaskID(ctx context.Context, taskID string) (*NodeRun, error)
	GetWorkflowNodeRunByTaskRunID(ctx context.Context, taskRunID string) (*NodeRun, error)
	// ListWorkflowRevisions returns a workflow's revisions, newest first, with
	// the total count.
	ListWorkflowRevisions(ctx context.Context, workflowID string, limit, offset int) ([]Revision, int, error)
	// GetWorkflowRevision returns one revision, or nil when the workflow has no
	// such revision number.
	GetWorkflowRevision(ctx context.Context, workflowID string, revision int) (*Revision, error)
}

type TransitionNodeRunInput struct {
	NodeRunID      string
	ExpectedStatus NodeRunStatus
	NewStatus      NodeRunStatus
	TaskID         *string
	TaskRunID      *string
	ResolvedInput  *string
	Output         *string
	Structured     *string
	ErrorMessage   *string
	StartedAt      *time.Time
	EndedAt        *time.Time
}

type TransitionRunInput struct {
	WorkflowRunID  string
	ExpectedStatus RunStatus
	NewStatus      RunStatus
	StartedAt      *time.Time
	EndedAt        *time.Time
	ErrorMessage   *string
	// Result is the run's declared result JSON, written when the run moves to
	// succeeded. Nil leaves the column untouched, so a definition with no result
	// selector or a non-success transition stores nothing.
	Result *string
}

type UpdateInput struct {
	Name        *string
	Description *string
	Definition  *string
	Status      *string
	// ExpectedRevision is the revision the service observed before this edit. The
	// store guards the workflow row update on it and appends the next revision in
	// the same transaction, so a second writer that started from the same revision
	// loses the compare-and-set and gets ErrRevisionConflict rather than
	// overwriting the winner or leaking the duplicate-key error.
	ExpectedRevision int
	// UpdatedBy is recorded as the author of the revision this update appends.
	UpdatedBy string
}

type Workflow struct {
	ID          string `json:"id"`
	SpaceID     string `json:"space_id"`
	Name        string `json:"name"`
	Description string `json:"description"`
	Definition  string `json:"definition"`
	Status      string `json:"status"`
	// Revision numbers the workflow_revision row holding this content. It
	// starts at 1 and advances every time the name, description, definition,
	// or status changes.
	Revision  int       `json:"revision"`
	CreatedBy string    `json:"created_by"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}