store

type AcknowledgeIPCMessagesInput struct {
	TenantID       string
	ConsumerName   string
	MessageIDs     []uuid.UUID
	AcknowledgedAt time.Time
}

type AcknowledgeIPCMessagesResult struct {
	Acknowledged        []uuid.UUID
	AlreadyAcknowledged []uuid.UUID
}

type AcquireAttemptInput struct {
	TenantID           string
	AttemptID          uuid.UUID
	LeaseID            uuid.UUID
	RunID              uuid.UUID
	ExpectedRunVersion int64
	RuntimeClass       string
	RuntimeInstanceID  string
	TTL                time.Duration
}

type AdmissionReason struct {
	Code    string `json:"code"`
	Message string `json:"message"`
	Field   string `json:"field,omitempty"`
}

type AgentAddress struct {
	AgentVersionRef string
	Instance        string
}

type AgentVersion struct {
	ID               uuid.UUID
	TenantID         string
	Namespace        string
	Name             string
	Version          string
	Spec             json.RawMessage
	SpecDigest       [sha256.Size]byte
	ResourceVersion  int64
	CreatedAt        time.Time
	PackageSignature *PackageSignature
}

type AgentVersionStore interface {
	CreateAgentVersion(context.Context, CreateAgentVersionInput) (CreateAgentVersionResult, error)
	GetAgentVersion(context.Context, string, uuid.UUID) (AgentVersion, error)
	GetAgentVersionByRef(context.Context, string, string) (AgentVersion, error)
}

type AppendIPCMessageInput struct {
	TenantID            string
	ID                  uuid.UUID
	FromAgentVersionRef string
	To                  AgentAddress
	Kind                string
	// Payload is the message body as a JSON document. An empty body is
	// written as {}.
	Payload json.RawMessage
	// Attachments is a JSON array of reference objects. It is stored without
	// being interpreted; a payload above IPCPayloadLimit must travel this way.
	Attachments   json.RawMessage
	CorrelationID string
	// ReplyToMessageID is uuid.Nil when the message is not a reply.
	ReplyToMessageID uuid.UUID
	IdempotencyKey   string
	TraceID          string
	SentAt           time.Time
	// Deadline is optional; the zero time stores no deadline.
	Deadline time.Time
}

type AppendIPCMessageResult struct {
	Message  IPCMessage
	Replayed bool
}

type ArtifactReference struct {
	ID        uuid.UUID
	URI       string
	SHA256    [sha256.Size]byte
	SizeBytes int64
	MediaType string
}

type Attempt struct {
	ID                uuid.UUID
	TenantID          string
	RunID             uuid.UUID
	Ordinal           int
	Phase             domain.AttemptPhase
	RuntimeClass      string
	RuntimePoolID     string
	RuntimeInstanceID string
	FencingToken      int64
	FailureCode       string
	FailureMessage    string
	ResourceVersion   int64
	CreatedAt         time.Time
	UpdatedAt         time.Time
	StartedAt         *time.Time
	FinishedAt        *time.Time
}

type AttemptLease struct {
	Attempt Attempt
	Lease   Lease
	Run     Run
}

type AuditEvent struct {
	ID           uuid.UUID
	TenantID     string
	Seq          int64
	PrevHash     [sha256.Size]byte
	ChainHash    [sha256.Size]byte
	EventType    string
	ResourceType string
	ResourceID   uuid.UUID
	Actor        string
	Details      json.RawMessage
	OccurredAt   time.Time
}

type AuditStore interface {
	ListAudit(context.Context, ListAuditInput) ([]AuditEvent, error)
	GetAuditEvent(context.Context, string, uuid.UUID) (AuditEvent, error)
	VerifyAuditChain(context.Context, string) (AuditVerification, error)
	ExportAuditChain(context.Context, string) ([]AuditEvent, error)
}

type AuditVerification struct {
	Valid          bool
	Checked        int64
	FirstBrokenSeq int64 // 0 when the chain is valid
	HeadSeq        int64
	HeadHash       [sha256.Size]byte
}

type BudgetStore interface {
	// GetTaskBudget returns the reservation and cumulative consumption of a
	// task, or ErrBudgetNotReserved when the task carries no budget.
	GetTaskBudget(context.Context, string, uuid.UUID) (TaskBudgetStatus, error)
	// SettleTaskUsage appends one idempotent usage settlement. A settlement
	// that would exceed the reservation is rejected with ErrBudgetExceeded and
	// marks the ledger exhausted without being recorded. Replays of an
	// already-recorded settlement return the current status.
	SettleTaskUsage(context.Context, SettleTaskUsageInput) (TaskBudgetStatus, error)
	// SettleTaskUsageDelta settles the remainder between a family's already
	// settled usage and a cumulative target, exactly once per IdempotencyKey.
	// The hard stop and replay semantics match SettleTaskUsage; a family that
	// already settled at least the target settles nothing.
	SettleTaskUsageDelta(context.Context, SettleTaskUsageDeltaInput) (TaskBudgetStatus, error)
	// ReserveTaskUsage atomically protects headroom before a provider or tool
	// call starts. Replays with the same key and amount are idempotent.
	ReserveTaskUsage(context.Context, ReserveTaskUsageInput) error
	// ReleaseTaskUsageReservation is idempotent and must run on every terminal
	// call path. Expired reservations are reclaimed by reconciliation.
	ReleaseTaskUsageReservation(context.Context, string, uuid.UUID, string) error
}

type CancelAttemptInput struct {
	TenantID               string
	AttemptID              uuid.UUID
	FencingToken           int64
	ExpectedAttemptVersion int64
	IdempotencyKey         string
}

type CancelAttemptResult struct {
	Attempt Attempt
	Run     Run
	Task    Task
}

type Checkpoint struct {
	ID                  uuid.UUID
	TenantID            string
	RunID               uuid.UUID
	AttemptID           uuid.UUID
	Ordinal             int
	FencingToken        int64
	AgentVersionRef     string
	RuntimeClass        string
	Provider            string
	RuntimeABI          string
	SchemaVersion       string
	State               ArtifactReference
	ConfirmedReceiptIDs []string
	EnvelopeSHA256      [sha256.Size]byte
	CreatedAt           time.Time
}

type ClaimOutboxInput struct {
	DispatcherID string
	Limit        int
	LockTTL      time.Duration
}

type ClaimTasksInput struct {
	Kind    ControllerKind
	Phase   domain.TaskPhase
	OwnerID string
	Limit   int
	TTL     time.Duration
	// ShardIndex / ShardCount are the tenant-consistent shard filter
	// (ADR-016): when ShardCount > 0, only tasks whose tenant maps to
	// ShardIndex are claimable. Zero values mean no sharding (every instance
	// claims every tenant). All instances must share the same shard count.
	ShardIndex int
	ShardCount int
}

type ClaimWorkflowsInput struct {
	Owner     string
	Batch     int
	Lease     time.Duration
	MaxTokens int64
}

type CommitCheckpointInput struct {
	TenantID               string
	AttemptID              uuid.UUID
	FencingToken           int64
	ExpectedAttemptVersion int64
	IdempotencyKey         string
	CheckpointID           uuid.UUID
	AgentVersionRef        string
	Provider               string
	RuntimeABI             string
	SchemaVersion          string
	State                  ArtifactReference
	ConfirmedReceiptIDs    []string
}

type CompleteAttemptInput struct {
	TenantID               string
	AttemptID              uuid.UUID
	FencingToken           int64
	ExpectedAttemptVersion int64
	IdempotencyKey         string
	Result                 ArtifactReference
}

type CompleteAttemptResult struct {
	Attempt Attempt
	Run     Run
	Task    Task
}

type CompleteRunInput struct {
	TenantID           string
	RunID              uuid.UUID
	AttemptID          uuid.UUID
	FencingToken       int64
	ExpectedRunVersion int64
	ResultRef          string
}

type ControlStore interface {
	GetTask(context.Context, string, uuid.UUID) (Task, error)
	ClaimTasks(context.Context, ClaimTasksInput) ([]TaskClaim, error)
	ReleaseTaskClaim(context.Context, TaskClaim) error
	DecideAdmission(context.Context, DecideAdmissionInput) (Task, error)
	ScheduleTask(context.Context, ScheduleTaskInput) (AttemptLease, error)
	DeferTaskSchedule(context.Context, DeferTaskScheduleInput) (Task, error)
	ClaimOutbox(context.Context, ClaimOutboxInput) ([]OutboxEvent, error)
	MarkOutboxPublished(context.Context, uuid.UUID, string, int64, time.Time) error
	MarkOutboxFailed(context.Context, uuid.UUID, string, int64, string, time.Time) error
	GetAgentVersionByRef(context.Context, string, string) (AgentVersion, error)
}

type ControllerKind string

type CreateAgentVersionInput struct {
	ID               uuid.UUID
	TenantID         string
	Namespace        string
	Name             string
	Version          string
	Spec             json.RawMessage
	PackageSignature *PackageSignature
}

type CreateAgentVersionResult struct {
	AgentVersion AgentVersion
	Existing     bool
}

type CreateModelCallInput struct {
	ID        uuid.UUID
	TenantID  string
	TaskID    uuid.UUID
	RunID     uuid.UUID
	AttemptID uuid.UUID
	ModelRef  string
	// PriceRevision pins the price table the call is metered against.
	PriceRevision  string
	IdempotencyKey string
}

type CreateModelCallResult struct {
	ModelCall ModelCall
	Existing  bool
}

type CreateRunInput struct {
	ID                  uuid.UUID
	TenantID            string
	TaskID              uuid.UUID
	ExpectedTaskVersion int64
}

type CreateTaskInput struct {
	ID               uuid.UUID
	TenantID         string
	Namespace        string
	AgentVersionRef  string
	Goal             string
	Spec             json.RawMessage
	IdempotencyKey   string
	WorkflowID       *uuid.UUID
	WorkflowStepID   *uuid.UUID
	WorkflowStepName string
	WorkflowAttempt  int
	ParentTaskID     *uuid.UUID
}

type CreateTaskResult struct {
	Task     Task
	Existing bool
}

type CreateToolApprovalInput struct {
	ID          uuid.UUID
	TenantID    string
	CallID      uuid.UUID
	TaskID      uuid.UUID
	RunID       uuid.UUID
	AttemptID   uuid.UUID
	ToolName    string
	ToolVersion string
	Action      string
	Resource    string
	ArgsHash    [sha256.Size]byte
	RequestedAt time.Time
	ExpiresAt   time.Time
}

type CreateToolApprovalResult struct {
	ToolApproval ToolApproval
	Existing     bool
}

type CreateToolCallInput struct {
	ID             uuid.UUID
	TenantID       string
	TaskID         uuid.UUID
	RunID          uuid.UUID
	AttemptID      uuid.UUID
	ToolName       string
	ToolVersion    string
	Action         string
	Resource       string
	ArgsHash       [sha256.Size]byte
	IdempotencyKey string
}

type CreateToolCallResult struct {
	ToolCall ToolCall
	Existing bool
}

type CreateWorkflowInput struct {
	ID             uuid.UUID
	TenantID       string
	Namespace      string
	IdempotencyKey string
	Goal           string
	Spec           json.RawMessage
	Steps          []CreateWorkflowStepInput
	// Budget ceilings decoded from the workflow document; zero leaves
	// the dimension unbounded.
	BudgetMaxTasks        int64
	BudgetMaxTokens       int64
	BudgetMaxCostMicroUSD money.MicroUSD
	DeadlineAt            *time.Time
}

type CreateWorkflowResult struct {
	Workflow Workflow
	Existing bool
}

type CreateWorkflowStepInput struct {
	Name              string
	Spec              json.RawMessage // per-step workload spec overlay
	AgentVersionRef   string
	Goal              string
	DependsOn         []string
	ConditionStep     string
	ConditionContains string
	ConditionEquals   string
	RequiresApproval  bool
	MaxAttempts       int
}

type DecideAdmissionInput struct {
	TaskID              uuid.UUID
	TenantID            string
	OwnerID             string
	ClaimFencingToken   int64
	ExpectedTaskVersion int64
	Admit               bool
	ReasonCode          string
	Reasons             []AdmissionReason
	EvaluatorVersion    string
	// AgentVersionID binds the task to the immutable published version its
	// reference resolved to. It is set by the admission controller whenever
	// the reference is resolvable, regardless of the admission outcome.
	AgentVersionID *uuid.UUID
	// Budget is the task's reserved ceiling, derived from its workload spec
	// by the admission controller. When set and the task is admitted, the
	// ledger row is created in the same transaction as the admission
	// decision; nil means the task carries no budget.
	Budget *TaskBudget
	// PolicyRevision records the Rego policy revision that produced the
	// decision; empty when no policy engine participated.
	PolicyRevision string
}

type DecideToolApprovalInput struct {
	TenantID        string
	ApprovalID      uuid.UUID
	ExpectedVersion int64
	Decision        ToolApprovalStatus
	DecidedBy       string
	Now             time.Time
}

type DecideWorkflowStepApprovalInput struct {
	TenantID        string
	WorkflowID      uuid.UUID
	StepName        string
	ExpectedVersion int64
	Approved        bool
	DecidedBy       string
}

type DeferTaskScheduleInput struct {
	TaskID              uuid.UUID
	TenantID            string
	OwnerID             string
	ClaimFencingToken   int64
	ExpectedTaskVersion int64
	Until               time.Time
	Rejection           json.RawMessage
}

type FinishModelCallInput struct {
	TenantID          string
	ModelCallID       uuid.UUID
	ExpectedVersion   int64
	Status            ModelCallStatus
	InputTokens       int64
	OutputTokens      int64
	CostMicroUSD      money.MicroUSD
	PriceRevision     string
	ProviderRequestID string
	FinishReason      string
	UsageCertainty    ModelUsageCertainty
}

type HeartbeatLeaseInput struct {
	TenantID             string
	AttemptID            uuid.UUID
	FencingToken         int64
	ExpectedLeaseVersion int64
	TTL                  time.Duration
}

type HeartbeatStatus struct {
	CancelRequested bool
	AttemptVersion  int64
}

type IPCMessage struct {
	Sequence            int64
	ID                  uuid.UUID
	TenantID            string
	FromAgentVersionRef string
	To                  AgentAddress
	Kind                string
	Payload             json.RawMessage
	Attachments         json.RawMessage
	CorrelationID       string
	// ReplyToMessageID is uuid.Nil when the message is not a reply.
	ReplyToMessageID uuid.UUID
	TraceID          string
	SentAt           time.Time
	// Deadline is the zero time when the message carries no deadline.
	Deadline time.Time
}

type IPCStore interface {
	// AppendIPCMessage stores one message in the recipient's mailbox. A
	// replay of the same idempotency key returns the message the first attempt
	// stored, with Replayed=true; the same key carrying a different message is
	// ErrIdempotencyConflict.
	//
	// A message that is stored for the first time also enqueues one
	// IPCMessageStoredEventType event into outbox_events in the same
	// transaction. A replay enqueues nothing: the message it resolves to was
	// already announced, and announcing it again would turn one send into two
	// events.
	AppendIPCMessage(context.Context, AppendIPCMessageInput) (AppendIPCMessageResult, error)
	// GetIPCMessage returns one message or ErrNotFound. A message belonging to
	// another tenant is not found.
	GetIPCMessage(context.Context, string, uuid.UUID) (IPCMessage, error)
	// ListMailbox returns the messages addressed to To with a sequence above
	// the cursor that the consumer has not receipted, in mailbox order.
	ListMailbox(context.Context, ListMailboxInput) ([]IPCMessage, error)
	// AcknowledgeIPCMessages records the consumer's receipts for a batch. Only
	// messages that exist in the tenant may be acknowledged: a receipt for an
	// unknown id would hide the real message if it arrived later.
	AcknowledgeIPCMessages(context.Context, AcknowledgeIPCMessagesInput) (AcknowledgeIPCMessagesResult, error)
}

type KernelStore interface {
	CreateTask(context.Context, CreateTaskInput) (CreateTaskResult, error)
	TransitionTask(context.Context, string, uuid.UUID, int64, domain.TaskPhase) (Task, error)
	CreateRun(context.Context, CreateRunInput) (Run, error)
	AcquireAttempt(context.Context, AcquireAttemptInput) (AttemptLease, error)
	TransitionAttempt(context.Context, TransitionAttemptInput) (Attempt, error)
	HeartbeatLease(context.Context, HeartbeatLeaseInput) (Lease, error)
	CompleteRun(context.Context, CompleteRunInput) (Run, Task, error)
}

type Lease struct {
	ID              uuid.UUID
	TenantID        string
	RunID           uuid.UUID
	AttemptID       uuid.UUID
	FencingToken    int64
	ResourceVersion int64
	AcquiredAt      time.Time
	HeartbeatAt     time.Time
	ExpiresAt       time.Time
}

type ListAuditInput struct {
	TenantID string
	// AfterSeq returns events with seq > AfterSeq (cursor semantics).
	AfterSeq int64
	Limit    int
}

type ListMailboxInput struct {
	TenantID string
	To       AgentAddress
	// AfterSequence is exclusive cursor semantics, matching
	// ListAuditInput.AfterSeq.
	AfterSequence int64
	Limit         int
	// ConsumerName scopes the receipt. Messages already receipted for this
	// consumer are not returned. Use IPCMailboxConsumerName to derive it from
	// the receiving run id.
	ConsumerName string
}

type MailboxScopeStore interface {
	// GetRunMailboxScope returns the scope of runID within the tenant, or
	// ErrNotFound when no such run exists in that tenant.
	GetRunMailboxScope(context.Context, string, uuid.UUID) (RunMailboxScope, error)
}

type MemoryRecord struct {
	ID                uuid.UUID
	TenantID          string
	Namespace         string
	Key               string
	ContentType       string
	Content           string
	Embedding         []float32
	EmbeddingProvider string
	Sensitivity       string
	SourceTaskID      *uuid.UUID
	SourceRunID       *uuid.UUID
	SourceAttemptID   *uuid.UUID
	Provenance        json.RawMessage
	RetentionUntil    *time.Time
	TombstoneAt       *time.Time
	SupersededBy      *uuid.UUID
	ResourceVersion   int64
	CreatedAt         time.Time
	UpdatedAt         time.Time
}

type MemoryStore interface {
	// PutMemory inserts or updates the record with the given stable
	// (tenant, namespace, key). An identical document replays idempotently
	// (Existing=true, no version bump); a different document is a new
	// version (correction) and resurrects a tombstoned record.
	PutMemory(context.Context, PutMemoryInput) (MemoryRecord, bool, error)
	// GetMemory returns the record (including tombstone state) or
	// ErrMemoryNotFound.
	GetMemory(context.Context, string, uuid.UUID) (MemoryRecord, error)
	// SearchMemory returns live (non-tombstoned, unexpired) records scored
	// by keyword FTS/trigram similarity and optional vector cosine distance,
	// tenant- and sensitivity-filtered before scoring.
	SearchMemory(context.Context, SearchMemoryInput) ([]MemoryRecord, error)
	// TombstoneMemory soft-deletes a record (ADR-009 deletion intent), CAS on
	// resource version.
	TombstoneMemory(context.Context, string, uuid.UUID, int64) (MemoryRecord, error)
}

type MetricsStore interface {
	AggregateMetrics(context.Context, string, time.Time) (*observability.Metrics, error)
}

type ModelCall struct {
	ID                uuid.UUID
	TenantID          string
	TaskID            uuid.UUID
	RunID             uuid.UUID
	AttemptID         uuid.UUID
	ModelRef          string
	Status            ModelCallStatus
	IdempotencyKey    string
	RequestHash       [sha256.Size]byte
	InputTokens       int64
	OutputTokens      int64
	CostMicroUSD      money.MicroUSD
	PriceRevision     string
	ProviderRequestID string
	FinishReason      string
	UsageCertainty    ModelUsageCertainty
	ResourceVersion   int64
	CreatedAt         time.Time
	UpdatedAt         time.Time
}

type ModelCallStatus string

type ModelDescriptor struct {
	ID                            uuid.UUID
	TenantID                      string
	Provider                      string
	ModelName                     string
	SupportsStreaming             bool
	InputPriceMicroUSDPerMillion  money.MicroUSD
	OutputPriceMicroUSDPerMillion money.MicroUSD
	PriceRevision                 string
	SpecHash                      [sha256.Size]byte
	CreatedAt                     time.Time
}

type ModelStore interface {
	RegisterModelDescriptor(context.Context, RegisterModelDescriptorInput) (ModelDescriptor, error)
	GetModelDescriptor(context.Context, string, string, string) (ModelDescriptor, error)
	CreateModelCall(context.Context, CreateModelCallInput) (CreateModelCallResult, error)
	GetModelCall(context.Context, string, uuid.UUID) (ModelCall, error)
	FinishModelCall(context.Context, FinishModelCallInput) (ModelCall, error)
}

type ModelUsageCertainty string

type OutboxEvent struct {
	ID               uuid.UUID
	TenantID         string
	AggregateType    string
	AggregateID      uuid.UUID
	AggregateVersion int64
	EventType        string
	Payload          json.RawMessage
	OccurredAt       time.Time
	PublishAttempts  int
	LockedBy         string
	LockedUntil      time.Time
	LockFencingToken int64
}

type PackageSignature struct {
	KeyID          string // signing key identity in the trust registry
	Signature      string // base64 raw std ed25519 signature over the manifest digest
	ManifestDigest string // hex sha256 of the canonical signed manifest
}

type PoolHealthStore interface {
	// PoolInstanceHealth reports whether each runtime instance is presumed
	// alive at now. An instance is unhealthy while it holds an unreleased
	// lease whose heartbeat is stale: the lease expired (expires_at <= now)
	// or was not renewed within the freshness window (heartbeat_at <= now -
	// freshness). An instance with no unreleased leases is healthy — idling
	// is not a failure signal. Every requested instance ID appears in the
	// result; callers treat an ID missing from the map as unhealthy
	// (fail-closed).
	PoolInstanceHealth(context.Context, []string, time.Time, time.Duration) (map[string]bool, error)
}

type PutMemoryInput struct {
	TenantID          string
	Namespace         string
	Key               string
	ContentType       string
	Content           string
	Embedding         []float32
	EmbeddingProvider string
	Sensitivity       string
	SourceTaskID      *uuid.UUID
	SourceRunID       *uuid.UUID
	SourceAttemptID   *uuid.UUID
	Provenance        json.RawMessage
	RetentionUntil    *time.Time
}

type ReceiptStore interface {
	GetRuntimeReceipt(context.Context, string, uuid.UUID, string, string) (RuntimeReceipt, error)
	WriteRuntimeReceipt(context.Context, WriteRuntimeReceiptInput) error
}

type RecoverExpiredAttemptInput struct {
	TenantID     string
	AttemptID    uuid.UUID
	FencingToken int64
	NewAttemptID uuid.UUID
	NewLeaseID   uuid.UUID
	LeaseTTL     time.Duration
	MaxAttempts  int
	// DeadlineExceeded terminally stops the task even if the worker lease is
	// still healthy. It must never create a retry attempt.
	DeadlineExceeded bool
}

type RecoveryCandidate struct {
	TenantID         string
	AttemptID        uuid.UUID
	FencingToken     int64
	TaskSpec         json.RawMessage
	DeadlineExceeded bool
}

type RecoveryResult struct {
	Retried bool
	Lease   AttemptLease
}

type RegisterModelDescriptorInput struct {
	TenantID                      string
	Provider                      string
	ModelName                     string
	SupportsStreaming             bool
	InputPriceMicroUSDPerMillion  money.MicroUSD
	OutputPriceMicroUSDPerMillion money.MicroUSD
	PriceRevision                 string
}

type RegisterToolDescriptorInput struct {
	TenantID         string
	Name             string
	Version          string
	SideEffectRisk   ToolRisk
	Actions          []string
	ResourcePatterns []string
	ParamsSchema     json.RawMessage
}

type ReserveTaskUsageInput struct {
	TenantID       string
	TaskID         uuid.UUID
	ReservationKey string
	Amount         TaskBudget
	ExpiresAt      time.Time
}

type Run struct {
	ID                  uuid.UUID
	TenantID            string
	TaskID              uuid.UUID
	Ordinal             int
	Phase               domain.RunPhase
	ActiveAttemptID     *uuid.UUID
	CurrentFencingToken int64
	ResultRef           string
	ResourceVersion     int64
	CreatedAt           time.Time
	UpdatedAt           time.Time
	CompletedAt         *time.Time
}

type RunMailboxScope struct {
	TenantID string
	RunID    string
	TaskID   string
	// AgentVersionRef is the version reference of the run's task. A send that
	// pairs a run with any other version reference names a mailbox that no
	// attempt will ever drain.
	AgentVersionRef string
}

type RuntimeAssignment struct {
	Task Task
	// AgentVersion is the immutable publication resolved during admission.
	// Runtime providers receive this declaration so adapter selection and
	// capability grants never come from mutable Task input.
	AgentVersion     *AgentVersion
	Run              Run
	Attempt          Attempt
	Lease            Lease
	ResumeCheckpoint *Checkpoint
	// PendingApprovalID is the approval a WAITING_APPROVAL attempt must
	// re-present to the Tool Gateway to resume execution.
	PendingApprovalID *uuid.UUID
}

type RuntimePolicy struct {
	SpawnGuards SpawnGuards
}

type RuntimePoolOperatorStore interface {
	UpdateRuntimePoolStatus(context.Context, UpdateRuntimePoolStatusInput) (RuntimePoolState, error)
}

type RuntimePoolState struct {
	ID              string `json:"id"`
	Status          string `json:"status"`
	ResourceVersion int64  `json:"resourceVersion"`
}

type RuntimeReceipt struct {
	RequestHash [sha256.Size]byte
	Response    json.RawMessage
	ProcessedAt time.Time
}

type RuntimeStore interface {
	KernelStore
	// WorkflowLineage resolves the workflow origin from the task's explicit
	// lineage columns; ok=false marks standalone tasks. The version is the
	// workflow's current resource version at read time.
	WorkflowLineage(context.Context, string, uuid.UUID) (workflowID uuid.UUID, stepName string, version int64, ok bool, err error)
	PollRuntimeAssignment(context.Context, string, string) (RuntimeAssignment, error)
	GetRuntimeAssignment(context.Context, string, uuid.UUID, int64) (RuntimeAssignment, error)
	GetHeartbeatStatus(context.Context, string, uuid.UUID, int64) (HeartbeatStatus, error)
	CommitCheckpoint(context.Context, CommitCheckpointInput) (Checkpoint, Attempt, error)
	CompleteAttempt(context.Context, CompleteAttemptInput) (CompleteAttemptResult, error)
	AcknowledgeCancellation(context.Context, CancelAttemptInput) (CancelAttemptResult, error)
	ListExpiredAttempts(context.Context, time.Time, int) ([]RecoveryCandidate, error)
	RecoverExpiredAttempt(context.Context, RecoverExpiredAttemptInput) (RecoveryResult, error)
}

type ScheduleTaskInput struct {
	TaskID              uuid.UUID
	TenantID            string
	OwnerID             string
	ClaimFencingToken   int64
	ExpectedTaskVersion int64
	RunID               uuid.UUID
	AttemptID           uuid.UUID
	LeaseID             uuid.UUID
	RuntimePoolID       string
	RuntimeClass        string
	RuntimeInstanceID   string
	LeaseTTL            time.Duration
	RequestedCPU        int64
	RequestedMemory     int64
	RequestedLLMSlots   int
}

type SearchMemoryInput struct {
	TenantID    string
	Query       string
	Embedding   []float32
	Namespace   string
	Sensitivity string
	Limit       int
}

type SetTenantQuotaInput struct {
	TenantID      string
	WindowSeconds int64
	Limits        TaskBudget
}

type SettleTaskUsageDeltaInput struct {
	TenantID string
	TaskID   uuid.UUID
	// FamilyPrefix scopes the already-settled sum (e.g. "model:<callID>").
	// Wildcards are rejected so the prefix can never widen the match.
	FamilyPrefix string
	// Target is the cumulative usage the family must reach.
	Target TaskBudget
	// IdempotencyKey is the key of the delta settlement row.
	IdempotencyKey string
	ReservationKey string
}

type SettleTaskUsageInput struct {
	TenantID       string
	TaskID         uuid.UUID
	IdempotencyKey string
	Usage          TaskBudget
	// ReservationKey identifies the active pre-consumption reservation that
	// this settlement replaces. It is excluded from concurrent headroom.
	ReservationKey string
}

type SpawnDenial struct {
	Code    string
	Message string
}

type SpawnGuards struct {
	Enabled              bool
	MaxDynamicSteps      int64
	MaxChildrenPerStep   int64
	MaxSpawnDepth        int
	MaxWorkflowSteps     int64
	MaxSpawnTasks        int64
	MaxSpawnTokens       int64
	MaxSpawnCostMicroUSD money.MicroUSD
}

type SpawnWorkflowStepInput struct {
	WorkflowID      uuid.UUID
	TenantID        string
	WorkflowVersion int64
	ParentStepName  string
	Name            string
	Goal            string
	AgentVersionRef string
	Spec            json.RawMessage
	MaxAttempts     int
	Guards          SpawnGuards
	IdempotencyKey  string
	Arguments       json.RawMessage
}

type SpawnWorkflowStepResult struct {
	Step              WorkflowStep
	Workflow          Workflow
	WorkflowExhausted bool
	Created           bool
	Usage             WorkflowUsage
}

type StepStatus string

type Task struct {
	ID                  uuid.UUID
	TenantID            string
	Namespace           string
	AgentVersionRef     string
	AgentVersionID      *uuid.UUID
	Goal                string
	Spec                json.RawMessage
	RequestHash         [32]byte
	IdempotencyKey      string
	Phase               domain.TaskPhase
	AdmissionReasonCode string
	AdmittedAt          *time.Time
	CancelRequestedAt   *time.Time
	ActiveRunID         *uuid.UUID
	ResultRef           string
	WorkflowID          *uuid.UUID
	WorkflowStepID      *uuid.UUID
	WorkflowStepName    string
	WorkflowAttempt     int
	ParentTaskID        *uuid.UUID
	// ExecutionDeadlineAt is the hard stop computed when execution begins:
	// min(workload deadline, start + wallSeconds).
	ExecutionDeadlineAt *time.Time
	// NextScheduleAttemptAt gates scheduling-claim eligibility (O6): a task
	// deferred after a no-placement is not claimable by the scheduler until
	// this deadline. Nil means eligible immediately.
	NextScheduleAttemptAt *time.Time
	// ScheduleRetryCount is the number of consecutive no-placement
	// deferrals; it drives the exponential scheduling backoff and resets on
	// successful placement.
	ScheduleRetryCount    int64
	LastScheduleRejection json.RawMessage
	ResourceVersion       int64
	CreatedAt             time.Time
	UpdatedAt             time.Time
}

type TaskBudget struct {
	Tokens       int64
	CostMicroUSD money.MicroUSD
	ToolCalls    int64
	WallSeconds  int64
}

type TaskBudgetStatus struct {
	TaskID          uuid.UUID
	TenantID        string
	Reserved        TaskBudget
	Consumed        TaskBudget
	Exhausted       bool
	ResourceVersion int64
	UpdatedAt       time.Time
}

type TaskCancellationStore interface {
	RequestTaskCancellation(context.Context, string, uuid.UUID, int64) (Task, error)
}

type TaskClaim struct {
	Task         Task
	Kind         ControllerKind
	OwnerID      string
	FencingToken int64
	ExpiresAt    time.Time
}

type TenantQuota struct {
	TenantID        string
	WindowSeconds   int64
	Limits          TaskBudget
	ResourceVersion int64
	UpdatedAt       time.Time
}

type TenantQuotaStore interface {
	// SetTenantQuota configures or replaces the tenant's quota. Existing
	// window consumption is preserved; only the limits and window length
	// change.
	SetTenantQuota(context.Context, SetTenantQuotaInput) (TenantQuota, error)
	// GetTenantQuota returns the tenant's configured quota or ErrNotFound.
	GetTenantQuota(context.Context, string) (TenantQuota, error)
	// DeleteTenantQuota removes the tenant's quota configuration. Window
	// consumption rows become inert; future admissions are unlimited until a
	// new quota is configured.
	DeleteTenantQuota(context.Context, string) error
	// GetTenantQuotaUsage returns the consumption of the window containing at.
	GetTenantQuotaUsage(context.Context, string, time.Time) (TenantWindowUsage, error)
}

type TenantWindowUsage struct {
	TenantID        string
	WindowStart     time.Time
	Consumed        TaskBudget
	Reserved        TaskBudget
	ResourceVersion int64
	UpdatedAt       time.Time
}

type ToolApproval struct {
	ID              uuid.UUID
	TenantID        string
	CallID          uuid.UUID
	TaskID          uuid.UUID
	RunID           uuid.UUID
	AttemptID       uuid.UUID
	ToolName        string
	ToolVersion     string
	Action          string
	Resource        string
	ArgsHash        [sha256.Size]byte
	Status          ToolApprovalStatus
	RequestedAt     time.Time
	ExpiresAt       time.Time
	DecidedAt       *time.Time
	DecidedBy       string
	ResourceVersion int64
}

type ToolApprovalStatus string

type ToolCall struct {
	ID              uuid.UUID
	TenantID        string
	TaskID          uuid.UUID
	RunID           uuid.UUID
	AttemptID       uuid.UUID
	ToolName        string
	ToolVersion     string
	Action          string
	Resource        string
	ArgsHash        [sha256.Size]byte
	Status          ToolCallStatus
	DecisionReasons []string
	PolicyRevision  string
	ApprovalID      *uuid.UUID
	IdempotencyKey  string
	RequestHash     [sha256.Size]byte
	ResourceVersion int64
	CreatedAt       time.Time
	UpdatedAt       time.Time
}

type ToolCallStatus string

type ToolDescriptor struct {
	ID               uuid.UUID
	TenantID         string
	Name             string
	Version          string
	SideEffectRisk   ToolRisk
	Actions          []string
	ResourcePatterns []string
	ParamsSchema     json.RawMessage
	SpecHash         [sha256.Size]byte
	CreatedAt        time.Time
}

type ToolRisk string

type ToolStore interface {
	RegisterToolDescriptor(context.Context, RegisterToolDescriptorInput) (ToolDescriptor, error)
	GetToolDescriptor(context.Context, string, string, string) (ToolDescriptor, error)
	ListToolDescriptors(context.Context, string) ([]ToolDescriptor, error)
	CreateToolCall(context.Context, CreateToolCallInput) (CreateToolCallResult, error)
	GetToolCall(context.Context, string, uuid.UUID) (ToolCall, error)
	UpdateToolCall(context.Context, UpdateToolCallInput) (ToolCall, error)
	CreateToolApproval(context.Context, CreateToolApprovalInput) (CreateToolApprovalResult, error)
	GetToolApproval(context.Context, string, uuid.UUID) (ToolApproval, error)
	DecideToolApproval(context.Context, DecideToolApprovalInput) (ToolApproval, error)
}

type TransitionAttemptInput struct {
	TenantID               string
	AttemptID              uuid.UUID
	FencingToken           int64
	ExpectedAttemptVersion int64
	To                     domain.AttemptPhase
	FailureCode            string
	FailureMessage         string
}

type TransitionWorkflowInput struct {
	TenantID        string
	WorkflowID      uuid.UUID
	ExpectedVersion int64
	To              WorkflowStatus
	FailureCode     string
	ExpectedOwner   string
}

type TransitionWorkflowStepInput struct {
	TenantID        string
	WorkflowID      uuid.UUID
	StepName        string
	ExpectedVersion int64
	To              StepStatus
	TaskID          *uuid.UUID
	AttemptCount    *int
	ResultSummary   json.RawMessage
	FailureCode     string
	ExpectedOwner   string
}

type UpdateRuntimePoolStatusInput struct {
	TenantID string
	PoolID   string
	Status   string
	// OperatorSubject is the authenticated principal requesting the status
	// change. It must hold a runtime_pool_operator_grants row for the pool;
	// the tenant usage grant alone is never sufficient.
	OperatorSubject string
	ExpectedVersion int64
}

type UpdateToolCallInput struct {
	TenantID        string
	ToolCallID      uuid.UUID
	ExpectedVersion int64
	Status          ToolCallStatus
	DecisionReasons []string
	PolicyRevision  string
	ApprovalID      *uuid.UUID
}

type Workflow struct {
	ID                uuid.UUID
	TenantID          string
	Namespace         string
	IdempotencyKey    string
	Goal              string
	Spec              json.RawMessage
	Status            WorkflowStatus
	FailureCode       string
	CancelRequestedAt *time.Time
	// Budget ceilings. Zero means the dimension is unbounded.
	BudgetMaxTasks        int64
	BudgetMaxTokens       int64
	BudgetMaxCostMicroUSD money.MicroUSD
	BudgetExhaustedAt     *time.Time
	DeadlineAt            *time.Time
	DeadlineExceededAt    *time.Time
	// NeedsBudgetReconciliation is set when a step's token/cost reservation may
	// be understated relative to its derived task spec — e.g. after the 000028
	// upgrade backfilled task-count slots but could not re-derive merged specs
	// in pure SQL. While set, dynamic spawning is paused (a stale-low commitment
	// could slip a spawn past a ceiling); the controller's reconcile loop
	// re-derives the reservations and clears the flag.
	NeedsBudgetReconciliation bool
	ResourceVersion           int64
	CreatedAt                 time.Time
	UpdatedAt                 time.Time
}

type WorkflowStatus string

type WorkflowStep struct {
	ID               uuid.UUID
	TenantID         string
	WorkflowID       uuid.UUID
	Name             string
	Ordinal          int
	Status           StepStatus
	AttemptCount     int
	TaskID           *uuid.UUID
	ResultSummary    json.RawMessage
	FailureCode      string
	DecidedBy        string
	ApprovalDecision string
	DecidedAt        *time.Time
	ParentStepName   string
	SpawnDepth       int
	IsDynamic        bool
	SpawnKey         string
	Goal             string
	AgentVersionRef  string
	Spec             json.RawMessage
	MaxAttempts      int
	// Reserved* is the outstanding workflow budget reservation held by an
	// undispatched or retrying step: the future Task's token/cost ceiling
	// plus its task-count slot. It transfers to the task's own budget
	// ledger at admission and returns to zero when the step reaches a
	// terminal state without one.
	ReservedTasks        int64
	ReservedTokens       int64
	ReservedCostMicroUSD money.MicroUSD
	ResourceVersion      int64
	CreatedAt            time.Time
	UpdatedAt            time.Time
}

type WorkflowStore interface {
	CreateWorkflow(context.Context, CreateWorkflowInput) (CreateWorkflowResult, error)
	GetWorkflow(context.Context, string, uuid.UUID) (Workflow, error)
	// ListActiveWorkflows returns non-terminal workflows oldest-first for
	// the orchestrator reconcile loop (all tenants; creation is where
	// tenant scoping is enforced).
	ListActiveWorkflows(context.Context, int) ([]Workflow, error)
	ListWorkflowSteps(context.Context, string, uuid.UUID) ([]WorkflowStep, error)
	GetWorkflowStep(context.Context, string, uuid.UUID, string) (WorkflowStep, error)
	TransitionWorkflow(context.Context, TransitionWorkflowInput) (Workflow, error)
	TransitionWorkflowStep(context.Context, TransitionWorkflowStepInput) (WorkflowStep, error)
	DecideWorkflowStepApproval(context.Context, DecideWorkflowStepApprovalInput) (WorkflowStep, error)
	// RequestWorkflowCancellation records the durable cancellation intent;
	// the orchestrator propagates it to active steps and finalizes.
	RequestWorkflowCancellation(context.Context, string, uuid.UUID, int64) (Workflow, error)
	// ArtifactMetadata reads the digest, size and media type of one stored
	// artifact URI so the orchestrator can open task result documents.
	ArtifactMetadata(context.Context, string, string) ([]byte, int64, string, error)
	// ClaimWorkflows leases active workflows to one orchestrator instance
	// Expired claims are stolen, so a dead instance's workflows are
	// taken over by its peers. Tenants are claimed round-robin.
	ClaimWorkflows(context.Context, ClaimWorkflowsInput) ([]Workflow, error)
	// SpawnWorkflowStep creates one dynamic step with all recursion, fan-out
	// and budget guards applied in the same transaction. A spawn_key
	// replay returns the existing step.
	SpawnWorkflowStep(context.Context, SpawnWorkflowStepInput) (SpawnWorkflowStepResult, error)
	// MarkWorkflowBudgetExhausted records the durable budget-stop intent.
	MarkWorkflowBudgetExhausted(context.Context, string, uuid.UUID, int64) (Workflow, error)
	// MarkWorkflowDeadlineExceeded records the durable deadline-stop intent.
	MarkWorkflowDeadlineExceeded(context.Context, string, uuid.UUID, int64) (Workflow, error)
	// WorkflowUsageSnapshot aggregates a workflow's task count and settled
	// usage.
	WorkflowUsageSnapshot(context.Context, string, uuid.UUID) (WorkflowUsage, error)
}

type WorkflowUsage struct {
	Tasks                 int64
	Tokens                int64
	CostMicroUSD          money.MicroUSD
	ReservedTokens        int64
	ReservedCostMicroUSD  money.MicroUSD
	PendingOverage        bool
	BudgetMaxTasks        int64
	BudgetMaxTokens       int64
	BudgetMaxCostMicroUSD money.MicroUSD
	// StepReserved* counts the workflow budget reservations still held by
	// undispatched (or retrying) steps: the outstanding future commitment
	// that exists before any task budget ledger does.
	StepReservedTasks        int64
	StepReservedTokens       int64
	StepReservedCostMicroUSD money.MicroUSD
}

type WriteRuntimeReceiptInput struct {
	TenantID       string
	AttemptID      uuid.UUID
	Operation      string
	IdempotencyKey string
	RequestHash    [sha256.Size]byte
	Response       json.RawMessage
}