ledger

type AttemptID string

type AttemptSnapshot struct {
	AttemptID  string
	TaskID     string
	RunID      string
	AttemptNum int
	StartedAt  time.Time
	FinishedAt *time.Time
	Status     string
}

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

type LeaseRepository interface {
	TakeoverExpiredRunClaim(context.Context, string, string, time.Duration) error
}

type LedgerRepository interface {
	AdmitSingleTask(context.Context, SingleTaskAdmission) error
	// CreateRun creates a new run record. Returns ErrDuplicate if an
	// idempotency-key matched run already exists.
	CreateRun(ctx context.Context, key string, snapshot RunSnapshot) error

	// GetRun returns a defensive copy of the current run snapshot.
	// Returns ErrNotFound if the run does not exist.
	GetRun(ctx context.Context, runID string) (RunSnapshot, error)

	// GetRunByIdempotencyKey returns the run previously created with key.
	// Returns ErrNotFound for an empty or unknown key.
	GetRunByIdempotencyKey(ctx context.Context, key string) (RunSnapshot, error)

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

	// CreateTask creates a new task record within a run.
	// Returns ErrDuplicate if the task ID already exists.
	// Returns ErrNotFound if the run does not exist.
	// Returns ErrClosed if the run has been closed/deleted.
	CreateTask(ctx context.Context, snap TaskSnapshot) error

	// GetTask returns a defensive copy of a task snapshot.
	// Returns ErrNotFound if the task does not exist.
	GetTask(ctx context.Context, runID, taskID string) (TaskSnapshot, error)

	// ListTasks returns all task snapshots for a run, ordered by creation.
	ListTasks(ctx context.Context, runID string) ([]TaskSnapshot, error)

	// AppendEvent records a lifecycle event with idempotency-key dedup.
	// Returns ErrDuplicate if the event ID already exists.
	AppendEvent(ctx context.Context, event LifecycleEvent) error

	// ListEvents returns all events for a run, ordered by sequence.
	ListEvents(ctx context.Context, runID string) ([]LifecycleEvent, error)

	// CompareAndSetTaskStatus atomically transitions a task's status and
	// increments its version. Returns ErrConflict if the current version
	// does not match expectedVersion. Returns ErrInvalidTransition if
	// the status change is not valid.
	CompareAndSetTaskStatus(ctx context.Context, runID, taskID string,
		expectedVersion uint64, newStatus string) error

	// SetTaskOutput stores a bounded redacted output/error/tool-calls
	// reference for a task. toolCallsRef is "" when the task made no tool
	// calls or none were recorded.
	SetTaskOutput(ctx context.Context, runID, taskID string,
		outputRef, errorRef, toolCallsRef string) error

	// SetTaskAttempt records the terminal state of one persisted attempt.
	// An attempt ID that is not yet present starts a new attempt rather than
	// erroring, so a re-execution (a retry, or a resumed run) records its own
	// outcome instead of overwriting the record of the execution before it.
	SetTaskAttempt(ctx context.Context, runID, taskID, attemptID, status string,
		finishedAt *time.Time) error

	// CloseRun marks a run as closed. No further state transitions are allowed.
	// Returns ErrNotFound if the run does not exist.
	// Returns ErrInvalidTransition if already closed.
	CloseRun(ctx context.Context, runID string) error

	// DeleteRun removes all data for a run. Returns ErrNotFound if not found.
	DeleteRun(ctx context.Context, runID string) error

	// ClaimRun acquires an exclusive execution claim on a run. The holder is
	// a random per-process ID - never a principal, session ID or role. Returns
	// ErrClaimHeld if another holder already holds the claim. The same holder
	// calling ClaimRun again refreshes the claim successfully.
	ClaimRun(ctx context.Context, runID, holder string) error

	// ReleaseRun releases the execution claim on a run. Only the current
	// holder may release. Returns ErrClaimNotHeld if the caller does not hold
	// the claim.
	ReleaseRun(ctx context.Context, runID, holder string) error

	// ClearRunClaim force-releases any execution claim on a run, regardless
	// of holder. Used during crash recovery to clear stale claims on runs
	// that have reached a terminal state.
	ClearRunClaim(ctx context.Context, runID string) error

	// StoreContent persists raw bytes keyed by a content-addressed reference
	// (e.g. "ref:output:xxxx"). The same ref may be stored multiple times;
	// subsequent stores are idempotent. Recorded content is never reclaimed,
	// including when the run that stored it is deleted.
	StoreContent(ctx context.Context, ref string, data []byte) error

	// LoadContent retrieves bytes previously stored by StoreContent.
	// Returns ErrContentNotFound if the ref is unknown.
	LoadContent(ctx context.Context, ref string) ([]byte, error)
}

type LifecycleEvent struct {
	ID        string // unique event identifier (idempotency key)
	RunID     string
	Sequence  uint64 // monotonic per-run
	Kind      string // e.g. "task_created", "task_completed", "run_canceled"
	TaskID    string // empty for run-level events
	AttemptID string // empty for task-level or run-level events
	// SessionID is carried when the task's session is known; it is empty for
	// run-level events and for cancel/recovery events where the task session is
	// not retained. It lets a workflow run be correlated across surfaces
	// (workflow run -> coordinator run -> bus).
	SessionID string `json:"session_id,omitempty"`
	Payload   []byte // bounded, redacted; nil for most events
	CreatedAt time.Time
}

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

type RecoveredRun struct {
	RunID          string
	DisplayName    string
	Status         RunStatus
	WasInterrupted bool
	// CreatedAt is when the run was created, carried through so callers can tell
	// a run interrupted moments ago from one abandoned days back. Both classify
	// identically, and only the first is worth telling the user about.
	CreatedAt time.Time
}

type RunID string

type RunPolicy = ledgercore.RunPolicy

type RunSnapshot struct {
	RunID              string
	DisplayName        string
	Status             RunStatus // created, queued, running, completed, failed, canceled
	RequestFingerprint string    // canonical coordinator request identity, when provided
	Tasks              []TaskSnapshot
	CreatedAt          time.Time
	CompletedAt        *time.Time
	Labels             map[string]string // caller-provided optional aliases only
	// IdempotencyKey is the caller-supplied deduplication key the run was
	// created under. It is persisted with the run_created payload so a fresh
	// repository replaying the store re-registers the key and refuses a
	// second CreateRun with it, instead of executing the same work twice.
	IdempotencyKey string    `json:"idempotency_key,omitempty"`
	Policy         RunPolicy `json:"policy"`
}

type RunStatus string

type SingleTaskAdmission struct {
	IdempotencyKey string
	Run            RunSnapshot
	Task           TaskSnapshot
}

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

type TaskID string

type TaskSnapshot struct {
	RunID        string
	TaskID       string
	ParentTaskID string // empty for root tasks
	// RawID is the model-supplied task id verbatim, before dispatch_tasks
	// namespaces it into TaskID for harness-level uniqueness (see
	// subagents.Task.RawID). Empty for any task not built through
	// dispatch_tasks.
	RawID       string `json:"raw_id,omitempty"`
	DisplayName string
	Status      string // queued, running, completed, failed, timed_out, canceled, blocked, cancel_requested
	Attempts    []AttemptSnapshot
	DependsOn   []string // TaskIDs this task depends on
	CreatedAt   time.Time
	CompletedAt *time.Time
	OutputRef   string // bounded redacted reference; empty until completion
	ErrorRef    string // bounded redacted reference; empty unless failed
	// ToolCallsRef is a bounded, redacted reference to this task's recorded
	// tool-call step trace (subagent tool name/input/output pairs). Result
	// envelopes hand it to the model as tool_calls_ref, pageable via
	// ledger_read. Empty when the task made no tool calls, or for any task
	// recorded before this field existed. Set once at task completion, on
	// the same SetTaskOutput call as OutputRef/ErrorRef.
	ToolCallsRef string `json:"tool_calls_ref,omitempty"`
	Version      uint64 // per-task monotonic version for compare-and-set
	// HandlerName is the registered handler name for the sub-agent task.
	// Stored so ResumeInterruptedRun can rebuild the task config.
	HandlerName string `json:"handler_name,omitempty"`
	// Agent routing metadata describes work, never a durable authority grant.
	// Resume must resolve this name against its current authorized registry.
	AgentName    string `json:"agent_name,omitempty"`
	AgentDigest  string `json:"agent_digest,omitempty"`
	Skill        string `json:"skill,omitempty"`
	ProviderName string `json:"provider_name,omitempty"`
	Model        string `json:"model,omitempty"`
	// Scope is a non-authority execution serialization key. It must survive resume.
	Scope string `json:"scope,omitempty"`
	// OutputSchema is part of the work request and must survive coordinator recovery.
	OutputSchema map[string]any `json:"output_schema,omitempty"`
	// InputSchema is part of the work request and must survive coordinator recovery.
	InputSchema map[string]any `json:"input_schema,omitempty"`
	// Input is the task payload, stored so a resumed task re-executes the work
	// it was given rather than an empty request.
	//
	// Only fields describing the WORK live here. Permission, scope, role,
	// session and turn are deliberately absent: the ledger is a file in the
	// workspace and the agent has file tools, so a persisted permission would be
	// a privilege grant the agent could write for itself.
	//
	// ParentTaskID above is the one identity-shaped field that IS persisted - it
	// is derived from Task.Owner (coordinator/spawn.go, via parentTaskID) and
	// records DAG parentage, which resume needs. It is deliberately NOT restored
	// into Task.Owner: doing so would make a resumed run'"'"'s dispatcher ParentID and
	// provenance attributable to a workspace-writable file.
	// TestResumeDoesNotRestoreAuthorityFields is the tripwire. See plan 12 §3.
	Input json.RawMessage `json:"input,omitempty"`
	// Timeout, Budget and Depth are resource limits: restored on resume, but
	// clamped to the live configuration so the ledger cannot raise a ceiling.
	Timeout               time.Duration      `json:"timeout,omitempty"`
	Budget                int                `json:"budget,omitempty"`
	Depth                 int                `json:"depth,omitempty"`
	WorkLimits            runtime.WorkLimits `json:"work_limits,omitempty"`
	DisableProviderReplay bool               `json:"disable_provider_replay,omitempty"`
}

type TaskStatus string