store

type Accounts interface {
	// CreateSession records a signed-in browser. The token itself is never
	// stored, only its digest, so a copy of the database signs nobody in.
	CreateSession(ctx context.Context, session Session) error
	// FindSession is the live session with this digest; found is false for
	// one that never existed, was revoked, or has expired.
	FindSession(ctx context.Context, tokenHash string) (Session, bool, error)
	// RevokeSession ends a session at once, which is what signing out is.
	RevokeSession(ctx context.Context, tokenHash string) error
	// SaveUser records what a sign-in provider said about a person, replacing
	// what it said last time: organizations and groups are read at sign-in,
	// so a person removed from a team loses it at their next.
	SaveUser(ctx context.Context, user User) error
	// FindUser is the person an actor names, as last recorded.
	FindUser(ctx context.Context, actor string) (User, bool, error)
	// RegisterClient records an agent that registered itself to connect to
	// exports (RFC 7591), refusing one past limit: registration answers
	// anybody, so its table must not grow without bound. Before counting it
	// evicts clients holding no token that are older than UnusedClientTTL.
	RegisterClient(ctx context.Context, client OAuthClient, limit int) error
	FindClient(ctx context.Context, id string) (OAuthClient, bool, error)
	// IssueToken records a token by its digest, never the token.
	IssueToken(ctx context.Context, token OAuthToken) error
	// FindToken is the live token with this digest: unexpired, unrevoked.
	FindToken(ctx context.Context, tokenHash string) (OAuthToken, bool, error)
	// RevokeToken ends one token, which is what rotating a refresh token does
	// to the old one. revoked is false for a token already ended: of two
	// refreshes racing with one token, only the one that ended it may mint.
	RevokeToken(ctx context.Context, tokenHash string) (revoked bool, err error)
	// RevokeGrant ends every token a person gave one client for one export: disconnecting it.
	RevokeGrant(ctx context.Context, grant Grant) error
	// Grants are the live connections — a grant with a token still good —
	// newest first, narrowed by filter's non-empty fields.
	Grants(ctx context.Context, filter Grant) ([]Connection, error)
	Close() error
}

type Activity interface {
	// RecordActivity appends one entry and trims the whole log, across every
	// pipeline, to the newest limit entries (zero is no limit). The log is
	// one per database because who did what is a question about the daemon,
	// not about any one pipeline.
	RecordActivity(ctx context.Context, entry ActivityEntry, limit int) error
}

type ActivityEntry struct {
	ID int64
	// Pipeline is the name it was done to, as it was named then.
	Pipeline string
	// Actor is who did it, actor.Actor's stored form; empty where nobody
	// signs in.
	Actor string
	// Action is the verb: set, trigger, rerun, abort, approve, reject,
	// answer, pause, unpause, release, rename, destroy, mcp.connect, mcp.test.
	Action string
	// Target is what the verb was done to: a job, a run id, a revision sha.
	Target string
	// Detail is a JSON object of anything else worth reading, never secrets.
	Detail string
	At     time.Time
}

type ActivityFilter struct {
	// Pipeline matches the name an entry was recorded under, or the current
	// name of the pipeline it was recorded against, so a rename keeps its
	// history.
	Pipeline string
	Actor    string
	Action   string
	// Actions keeps entries with any of these actions; empty keeps all. Beside Action because a page about one thing — an export — asks for every verb that thing has.
	Actions []string
	// Target matches what the verb was done to: a job, a run, an export.
	Target string
	// Since keeps only entries at or after it; zero keeps all.
	Since time.Time
	// Before pages: only entries older than this id.
	Before int64
	Limit  int
}

type AgentUsage struct {
	RunID     string
	StepIndex int
	StepName  string
	JobName   string
	// Kind is UsageStep, UsageHook or UsageFix; empty records as UsageStep.
	Kind string
	// NodeHash is empty for a hook or a fix, which are never hashed: their
	// rows hang off the run alone.
	NodeHash string
	// StepID is the run_events row the spend is drawn on — a hook's own, a fix's task's — or 0 when it ran outside a published step.
	StepID       int64
	ModelReq     string
	ModelServed  string
	Prompt       int
	Completion   int
	Total        int
	Cached       int
	Reasoning    int
	CostUSD      *float64
	FinishReason string
	DurationMS   int64
	RawMeta      string
}

type Approval struct {
	ID          int64
	JobName     string
	Message     string
	Status      ApprovalStatus
	RequestedAt time.Time
	// DecidedAt is zero while the approval is pending.
	DecidedAt time.Time
	DecidedBy string
	Reason    string
}

type ApprovalStatus string

type Approvals interface {
	RequestApproval(ctx context.Context, jobName, message string) (int64, error)
	// RequestApprovalFor is RequestApproval for one step of one run, and asking twice for the same pair is one request: a daemon that restarts while a run waits resumes it, the step asks again, and it must find the approval it already made — pending, or already granted while nobody was looking — instead of a second row nobody is waiting on. A refused or expired one is not found: a retry asks a person afresh. An empty runID is a request with no run to tie it to, and always new.
	RequestApprovalFor(ctx context.Context, runID, stepKey, jobName, message string) (int64, error)
	DecideApproval(ctx context.Context, id int64, status ApprovalStatus, by, reason string) error
	ApprovalStatus(ctx context.Context, id int64) (Approval, error)
	// Approvals is the audit trail newest first, capped by limit (zero means
	// no limit). pendingOnly lists only what is still waiting, OLDEST first —
	// the order to work through them in — and its callers pass zero, because
	// a waiting build that scrolled off the list waits forever.
	Approvals(ctx context.Context, pendingOnly bool, limit int) ([]Approval, error)
}

type Blobs interface {
	RecordStepBlobs(ctx context.Context, actionKey string, outputs map[string]string) error
	StepBlobs(ctx context.Context, actionKey string) (map[string]string, error)
}

type Cache interface {
	// RecordChainSucceeded adds a whole chain to the skip index.
	// ForgetChain removes it: a chain that ran again and failed — a --force
	// rerun, a hook — must not be skipped on the strength of the older
	// success. Failure is a removal rather than a row because the index
	// holds only what a rerun may skip; a failed run's classification lives
	// on its run and its nodes, and a job failing through fresh content
	// every time must not be able to crowd the green chains out of a
	// count-capped table.
	RecordChainSucceeded(ctx context.Context, jobName, rootHash string) error
	ForgetChain(ctx context.Context, jobName, rootHash string) error
	HasSucceededBatch(ctx context.Context, jobName string, rootHashes []string) (map[string]bool, error)
	RecordNode(ctx context.Context, node NodeRecord, jobName string, status NodeStatus, result map[string]any, execErr error) error
	HasNodeSucceeded(ctx context.Context, jobName, hash string) (bool, error)
	// HasNodesSucceeded is HasNodeSucceeded for many hashes in one read; a
	// hash that has not succeeded is absent rather than false.
	HasNodesSucceeded(ctx context.Context, jobName string, hashes []string) (map[string]bool, error)
	ListNodes(ctx context.Context, jobName string, limit int) ([]NodeRow, error)
	NodesByHash(ctx context.Context, hashes []string) (map[string]NodeRow, error)
	// SaveNodeTranscript replaces the transcript of a node, truncated to
	// MaxTranscriptBytes along whole events so it stays valid JSON.
	SaveNodeTranscript(ctx context.Context, hash, transcript string) error
	NodeTranscript(ctx context.Context, hash string) (string, bool, error)
}

type CheckError struct {
	Name     string
	Message  string
	FailedAt time.Time
}

type CheckedResource struct {
	Name      string
	Version   VersionKey
	CheckedAt time.Time
}

type CheckedSwap struct {
	Resource      string
	Expected      VersionKey
	ExpectedFound bool
	Next          VersionKey
}

type ClaimedJob struct {
	ID      int64
	JobName string
	// Manual is a person's trigger, which the breaker does not hold back.
	Manual bool
	// RerunOf is the run this one retries against the versions it was
	// created with, empty for any other trigger.
	RerunOf string
	// Resume is the run a restart interrupted, which this claim continues rather than starting a new one; empty for any other trigger.
	Resume string
}

type Connection struct {
	Grant
	// Client is what the agent called itself, and RedirectURIs where it said to send people back.
	Client       string
	RedirectURIs []string
	// AuthorizedAt is when the person first agreed, the oldest of the grant's live tokens.
	AuthorizedAt time.Time
}

type Control interface {
	// Pause is the circuit breaker for the whole pipeline: nothing polls, nothing is admitted, until Unpause.
	Pause(ctx context.Context) error
	Unpause(ctx context.Context) error
	Paused(ctx context.Context) (bool, error)
	// Rename is one UPDATE and keeps history; the handle goes on answering under its old name, so a caller closes it and re-opens under the new one.
	Rename(ctx context.Context, name string) error
	// Delete forgets the pipeline and everything that cascades off it; the handle is spent afterwards and must be closed.
	Delete(ctx context.Context) error
	// SetSourcePath records where this pipeline's YAML lives, so a reader of
	// the database can tell two checkouts apart. Only a command that LOADED
	// the pipeline calls it.
	SetSourcePath(ctx context.Context, source string) error
}

type Credentials interface {
	// Credential is the sealed value saved under name; found is false when there is none.
	Credential(ctx context.Context, name string) (sealed []byte, found bool, err error)
	// SaveCredential replaces whatever name held.
	SaveCredential(ctx context.Context, name string, sealed []byte) error
	// CredentialScope is what a sealed value is bound to, so a row copied onto another pipeline does not open: stable across a rename, never reused after a destroy.
	CredentialScope() string
}

type CrossRunRow struct {
	RunRow

	Pipeline string
}

type Deliveries interface {
	// RecordDelivery files a delivery as the newest version of resourceName, keeps its payload, and dispatches it, all in one transaction — a sender that was answered 2xx has had all of it happen. A version already recorded (a redelivery) changes nothing and reports false.
	RecordDelivery(ctx context.Context, resourceName string, delivery Delivery, dispatch Dispatch, limit int) (bool, error)
	// Delivery is the payload recorded with a version; found is false once version_history: has pruned it.
	Delivery(ctx context.Context, resourceName string, version VersionKey) (Delivery, bool, error)
}

type Delivery struct {
	Version map[string]any
	Body    []byte
	Headers map[string]string
}

type Dispatch struct {
	Jobs []string
	Held bool
	// By is who the queued rows say asked (actor.Actor's stored form).
	By string
}

type Events interface {
	AppendRunEvent(ctx context.Context, row RunEventRow) error
	RunEvents(ctx context.Context, runID string, afterSeq int64, limit int) ([]RunEventRow, error)
	// MaxStepID is the highest display-tree id a run's events carry, 0 for none: a resumed run mints past it, or its steps fold into the attempt before.
	MaxStepID(ctx context.Context, runID string) (int64, error)
	// DeleteStepEvents removes every event of one type a step recorded, which is how a step's output chunks make way for its one output record (events.TypeStepOutputChunk).
	DeleteStepEvents(ctx context.Context, runID string, stepID int64, eventType string) error
}

type Grant struct {
	ClientID string
	Actor    string
	Pipeline string
	Export   string
}

type HeldJob struct {
	Name        string
	Consecutive int
	HeldAt      time.Time
}

type Memories interface {
	// Remember files text under memory.Scope as its newest entry, then evicts
	// the oldest past limit (zero means no limit; a negative limit caps at
	// DefaultMemoryEntries). Text the scope already holds is not filed twice:
	// the entry already there comes back, reporting false.
	Remember(ctx context.Context, memory Memory, limit int) (Memory, bool, error)
	// ListMemories is scope's entries, newest first, capped by limit (zero
	// means no limit).
	ListMemories(ctx context.Context, scope string, limit int) ([]Memory, error)
	// Forget deletes one entry of scope. An id that is another scope's reports
	// false and deletes nothing — the id comes from a model.
	Forget(ctx context.Context, scope string, id int64) (bool, error)
	// ForgetScope deletes every entry of scope, reporting how many went.
	ForgetScope(ctx context.Context, scope string) (int, error)
	// MemoryScopes is every scope holding an entry, by name.
	MemoryScopes(ctx context.Context) ([]MemoryScope, error)
}

type Memory struct {
	ID    int64
	Scope string
	Text  string
	// RunID is the run that remembered it, "" once run_history: has reaped
	// that run — the memory outlives it, which is the point of keeping one.
	RunID     string
	CreatedAt time.Time
}

type MemoryScope struct {
	Scope   string
	Entries int
	// LastAt is when its newest entry was remembered.
	LastAt time.Time
}

type Meta interface {
	// Pipeline is the name this handle is scoped to.
	Pipeline() string

	// Description identifies the database behind this handle, in a form safe
	// to print: the file path for SQLite, a credential-free URL for a network
	// database. It is stable, so two handles reporting the same description
	// share a database — which is how a caller groups handles before asking
	// one Reader about several pipelines at once.
	Description() string

	// Reader reads across every pipeline in this database, unscoped by
	// construction.
	Reader() Reader

	// Close releases the connection, after whatever reclaim the driver owes
	// for what retention deleted. A handle obtained by RESOLVING a pipeline
	// rather than registering one must not write here: a command whose whole
	// contract is that it only asks changes no bytes.
	Close() error
}

type NewRun struct {
	ID      string
	JobName string
	// Workspace is the directory the run's steps execute in, and what a
	// resume continues from.
	Workspace string
	// ConfigSHA is the configuration the run executes, empty for a caller
	// that loaded no pipeline file.
	ConfigSHA string
	// QueueID is the trigger_queue row that started this run, zero for a run no queue started; recorded on that row, so a restart knows which run to resume.
	QueueID int64
	// CreatedBy is who started a run no queue row did. A queued run takes its row's requester instead, read in the same statement that records the run, so nothing between the claim and the start can lose it.
	CreatedBy string
}

type NodeRecord struct {
	Hash       string
	ParentHash string
	Kind       string
	StepIndex  int
	Resource   string // resource name (get/put) or task name (task); metadata only
	Content    map[string]any
}

type NodeRow struct {
	Hash      string
	Kind      string
	JobName   string
	Resource  string
	StepIndex int
	Status    NodeStatus
	Error     string
	Result    string
	CreatedAt time.Time
	// Content and ParentHash are what the hash is MADE of — populated by
	// NodesByHash (the node-detail read), left empty by the list queries,
	// whose callers want a table row rather than a whole content map.
	Content    string
	ParentHash string
}

type NodeStatus string

type OAuthClient struct {
	ID string
	// Name is what the client calls itself, which nothing verifies.
	Name         string
	RedirectURIs []string
	CreatedAt    time.Time
}

type OAuthToken struct {
	TokenHash string
	Kind      TokenKind
	Grant     Grant
	CreatedAt time.Time
	ExpiresAt time.Time
}

type Pass struct {
	JobName  string
	Resource string
	Version  VersionKey
	BuildID  string
}

type PassedVersion struct {
	Resource   string
	Version    VersionKey
	RecordedAt time.Time
}

type PipelineRow struct {
	Name string
	Path string
	// CurrentSHA is the revision a `steps pipeline set` made current, empty for a pipeline that only ever ran by hand; a daemon serves exactly the rows that have one.
	CurrentSHA string
	Paused     bool
}

type Placement struct {
	RunID     string
	StepIndex int
	StepName  string
	JobName   string
	// Slot is what makes this placement unique within its run: a plan step's
	// node hash, or a hook's scope label. A hook is not merkle-hashed, so it
	// has no node to be keyed on.
	Slot string
	// NodeHash is the node this placement belongs to, EMPTY for a hook. It is
	// what lets retention reaping a node take the placement with it; a hook
	// row has no node and cascades off its run instead.
	//
	// A string rather than a pointer, unlike InstanceID and UID beside it: a
	// hash is never legitimately empty, so there is no zero value to confuse
	// with absence, and a node's parent hash already spells the same
	// distinction this way.
	NodeHash   string
	Tag        string
	Address    string
	InstanceID *string
	GOOS       string
	GOARCH     string
	Workdir    string
	UID        *int
	GID        *int
	Image      string
	BytesSent  int64
	// BytesReceived is the tree that came back from that machine. Together
	// with BytesSent it is the whole cost of the placement in bytes, and
	// the pair is what says whether a produced tree ever had to leave the
	// worker at all.
	BytesReceived int64
	// VolumeBytes is what the step's own volumes held on the worker when it ended: its outputs, its overlays' upper layers, and any tree poured into the worker's cache for it — never a cached tree it only read. Nil where nothing weighed them — a worker that keeps no volumes (ssh://), a step that held no output there (the weighing rides in that output's digest run) — which is not the same answer as zero.
	VolumeBytes *int64
}

type Placements interface {
	RecordPlacement(ctx context.Context, placement Placement) error
	// RunPlacements returns a run's placements in plan order.
	RunPlacements(ctx context.Context, runID string) ([]Placement, error)
}

type Pruning interface {
	// Prune applies one retention policy at the end of a build: the job's runs
	// and its finished queue rows are capped by COUNT, newest kept, and a
	// reaped run takes its events, steps, usage, placements, questions and
	// inputs with it. keepRunID is never reaped, however the counts fall.
	//
	// Newest is by start time, with insertion order breaking a tie: two runs
	// can land in the same instant, and the one to keep is the one recorded
	// last.
	//
	// The merkle caches are bounded here too, and by count alone — see Cache.
	// A transcript hangs off the node cache, not the run, and goes with its
	// node. Every call also sweeps the configuration revisions nothing refers
	// to any more; a wholly zero Retention is that sweep alone.
	Prune(ctx context.Context, policy Retention, keepRunID string) error
}

type Question struct {
	ID      int64
	RunID   string
	JobName string
	// AgentName is the agent as the step KNOWS it (across: cells report under
	// their labelled identity), so a parked question names something a reader
	// can find in the plan.
	AgentName string
	Question  string
	Options   []string
	// OptionsRequired is recorded rather than only enforced in the asking
	// process, because the process that ANSWERS is usually a different one:
	// `steps questions answer` and the web UI both write this row directly, and a fence
	// only the asker knew about would be no fence on either of them.
	OptionsRequired bool
	Default         string
	Status          QuestionStatus
	AskedAt         time.Time
	// AnsweredAt is zero while the question is pending.
	AnsweredAt time.Time
	AnsweredBy string
	Answer     string
}

type QuestionStatus string

type Questions interface {
	// AskQuestion records a pending question, or returns the one this run
	// already asked under the same memo key — reporting false when it did.
	// The memo is the row, so twelve across: cells asking the same thing all
	// reach one row rather than one person twelve times.
	AskQuestion(ctx context.Context, question Question) (Question, bool, error)
	// AnswerQuestion is a person's answer, ErrQuestionNotPending if somebody
	// or something got there first.
	AnswerQuestion(ctx context.Context, id int64, answer, by string) error
	// CloseQuestion resolves a question with a status the caller chooses, for
	// the endings nobody answered.
	CloseQuestion(ctx context.Context, id int64, status QuestionStatus, answer, by string) error
	QuestionStatus(ctx context.Context, id int64) (Question, error)
	// Questions is the audit trail, what is still waiting first and then
	// newest first, capped by limit (zero means no limit). pendingOnly lists
	// only what is waiting, OLDEST first, and its callers pass zero — for the
	// same reason Approvals' do.
	Questions(ctx context.Context, pendingOnly bool, limit int) ([]Question, error)
}

type Queue interface {
	// EnqueueJob and its two siblings take by, the stored form of who or what asked (actor.Actor.String), which the run the row starts inherits.
	EnqueueJob(ctx context.Context, jobName, reason, by string) error
	// EnqueueManualJob is EnqueueJob for a person's trigger: the row is marked manual, and a pending row it merges into becomes manual too, because the breaker holds back only what was triggered automatically. The merged row takes this person as its requester, since they are why it is manual.
	EnqueueManualJob(ctx context.Context, jobName, reason, by string) error
	// EnqueueRerunJob queues a retry of a recorded run. It is a person's request, so it is manual; it is not merged into the job's ordinary pending row, since it builds different versions.
	EnqueueRerunJob(ctx context.Context, jobName, reason, runID, by string) error
	// ClaimNextJob takes the oldest pending row admitted by serial: and
	// max_in_flight, atomically, and reports false when nothing is ready. The
	// row comes back from the statement that claimed it, so nothing can be
	// read between the claim and what the trigger asked for.
	ClaimNextJob(ctx context.Context) (ClaimedJob, bool, error)
	CompleteJob(ctx context.Context, id int64, status QueueStatus, runErr error) error
	// AbortQueuedJob finalizes the job's pending row as aborted so it is never claimed, reporting false when nothing was pending. A running row is not its to touch: that build is stopped through its context, and holds its serial slot until it actually ends.
	AbortQueuedJob(ctx context.Context, jobName string) (bool, error)
	// ResetStaleRunning reclaims every running row as an abandoned leftover.
	// It is only true when nothing else is alive, which is why steps runs one
	// daemon per database.
	// A row whose run is still running goes back to pending carrying that run (ClaimedJob.Resume); a row whose run already finished is closed with the run's status, so a run somebody aborted is never built again.
	ResetStaleRunning(ctx context.Context) error
	ListTriggerQueue(ctx context.Context, limit int) ([]QueueRow, error)
	// SyncJobLimits replaces both admission mirrors from one configuration, in
	// one transaction. A job in neither map has no serial group and is
	// admitted one at a time: a missing row means the job left the pipeline
	// between enqueue and claim, and serializing what nobody can describe is
	// the conservative reading.
	SyncJobLimits(ctx context.Context, groups map[string][]string, limits map[string]int) error
	SerialGroupHolder(ctx context.Context, jobName string) (string, error)
	RecordJobOutcome(ctx context.Context, jobName string, succeeded bool, maxFailures int) (held bool, consecutive int, err error)
	ResetJobFailures(ctx context.Context, jobName string) error
	IsJobHeld(ctx context.Context, jobName string) (bool, error)
	HeldJobs(ctx context.Context) ([]HeldJob, error)
}

type QueueRow struct {
	ID         int64
	JobName    string
	Reason     string
	Status     QueueStatus
	EnqueuedAt time.Time
	StartedAt  time.Time
	FinishedAt time.Time
	Error      string
}

type QueueStatus string

type Reader interface {
	// Pipelines is what this database actually holds.
	Pipelines(ctx context.Context) ([]PipelineRow, error)
	// RecentRuns interleaves the named pipelines' runs, newest first. A name
	// the database has never heard of contributes nothing rather than failing:
	// the caller asked about a set, not about each one.
	RecentRuns(ctx context.Context, pipelines []string, limit int) ([]CrossRunRow, error)
	// Activity is the log of what people did, newest first, across every
	// pipeline — including ones since destroyed, by the name they had.
	Activity(ctx context.Context, filter ActivityFilter) ([]ActivityEntry, error)
	// Close releases the connection, unless this Reader borrowed one from a
	// Store — in which case closing is the Store's to do.
	Close() error
}

type Retention struct {
	// JobName is the job whose history is being bounded. Per job rather than
	// globally, so one busy job cannot evict a quiet one's only run — a global
	// cap makes the least active job the least inspectable, which is backwards.
	JobName string
	// Runs is how many of that job's runs to keep, newest first.
	Runs int
	// TriggerQueue is how many of its FINISHED queue rows to keep. A separate
	// number because the queue is a work list rather than history: see
	// DefaultTriggerQueueHistory, which is what the run passes.
	TriggerQueue int
}

type Revision struct {
	SHA      string
	Source   string
	Includes map[string]string
}

type Revisions interface {
	// RecordRevision interns a configuration with the include contents it folded in; the same sha twice is one row.
	RecordRevision(ctx context.Context, sha, source string, includes map[string]string) error
	FindRevision(ctx context.Context, sha string) (Revision, bool, error)
	// SetCurrentRevision names the recorded revision a `steps pipeline set` made current and, in the same write, records from as the pipeline's source path, so the two cannot disagree; the current one is never reaped.
	SetCurrentRevision(ctx context.Context, sha, from string) error
	// CurrentRevision is what a daemon serves for this pipeline at startup; false for a pipeline that only ever ran by hand.
	CurrentRevision(ctx context.Context) (Revision, bool, error)
}

type RunEventRow struct {
	Seq       int64
	RunID     string
	Type      string
	StepIndex int
	StepName  string
	StepKind  string
	// StepID/ParentStepID carry the display tree — see events.Event, which
	// documents why it is minted rather than read off the merkle chain.
	StepID       int64
	ParentStepID int64
	Status       string
	Hash         string
	Text         string
	Name         string
	Detail       string
	DurationMS   int64
	// Worker is where a placed step ran; empty for this machine. See
	// events.Event.Worker.
	Worker string
	At     time.Time
}

type RunInput struct {
	Input    string
	Resource string
	Version  VersionKey
}

type RunRow struct {
	ID         string
	JobName    string
	Workspace  string
	Status     RunStatus
	StartedAt  time.Time
	FinishedAt time.Time
	// ParentRunID is the run a replay forked from, empty for an ordinary run.
	// It is what lets a tuning session read as a session rather than as a pile
	// of unrelated runs that happen to share a job.
	//
	// Filled by EVERY query that builds a RunRow, deliberately: it was briefly
	// selected by only one of them, which made Replayed() answer differently
	// depending on which call site had loaded the row — the jobs list said a
	// forked run was ordinary while its own page linked its parent. That is
	// what the driver's one shared column list exists to make impossible.
	ParentRunID string
	// ConfigSHA is the configuration this run executed, empty for a run
	// started by a caller that loaded no pipeline file. Selected by every
	// RunRow query for the same reason ParentRunID is.
	ConfigSHA string
	// RerunOf is the run this one re-ran against the versions it was created with, empty for any other run. Selected by every RunRow query for the same reason ParentRunID is.
	RerunOf string
	// CreatedBy is the stored form of who or what started the run (actor.Parse reads it), empty for a run recorded before anyone was. Selected by every RunRow query for the same reason ParentRunID is.
	CreatedBy string
}

type RunStatus string

type RunStep struct {
	BuildID string
	Index   int
	Name    string
}

type RunTotals struct {
	RunID    string
	Tokens   int
	Cached   int
	CostUSD  *float64
	Steps    int
	Unpriced int
}

type Runs interface {
	// StartRun mints a run. An id some run already holds is ErrRunExists,
	// never an overwrite.
	StartRun(ctx context.Context, run NewRun) error
	// ResumeRun continues a run this pipeline already has, ErrNoSuchRun
	// otherwise.
	ResumeRun(ctx context.Context, id, workspaceDir, configSHA string) error
	// ResumableRuns is every run of this pipeline still recorded running, or that a queue row still waits to resume (a restart before its resume started): at startup, the ones a restart may resume, whose workspaces must survive the stale-build sweep.
	ResumableRuns(ctx context.Context) ([]RunRow, error)
	FinishRun(ctx context.Context, id string, status RunStatus) error
	// RecordRunStep marks a step of a run done. buildID is "<run>#0" inside
	// the build a get triggers and the bare run id before it.
	RecordRunStep(ctx context.Context, runID string, step RunStep) error
	RecordRunParent(ctx context.Context, runID, parentID string) error
	// RecordRunRerun marks a run as a rerun of another (fly rerun-build).
	RecordRunRerun(ctx context.Context, runID, originalID string) error
	// CompletedRunSteps returns what a run finished, in completion order.
	CompletedRunSteps(ctx context.Context, runID string) ([]RunStep, error)
	// ListRuns returns a job's runs newest first. Zero means no limit, the
	// convention everywhere here.
	ListRuns(ctx context.Context, jobName string, limit int) ([]RunRow, error)
	LatestRunByJob(ctx context.Context) (map[string]RunRow, error)
	// LatestFinishedRunByJob is each job's newest run that is no longer
	// running, reruns included, as ListRuns includes them.
	LatestFinishedRunByJob(ctx context.Context) (map[string]RunRow, error)
	RunsUsingNode(ctx context.Context, hash string, limit int) ([]RunRow, error)
	FindRunRow(ctx context.Context, id string) (RunRow, bool, error)
	FirstRunSince(ctx context.Context, jobName string, since time.Time) (RunRow, bool, error)
}

type Session struct {
	TokenHash string
	// Actor is who it signed in as, actor.Actor's stored form.
	Actor     string
	CreatedAt time.Time
	ExpiresAt time.Time
}

type Store interface {
	Meta
	Runs
	Cache
	Blobs
	Versions
	Queue
	Approvals
	Questions
	Placements
	Usage
	Events
	Revisions
	Control
	Pruning
	Deliveries
	Memories
	Activity
	Credentials
}

type TokenKind string

type Usage interface {
	RecordAgentUsage(ctx context.Context, usage AgentUsage) error
	RunTokensSpent(ctx context.Context, runID string) (int, error)
	RunUsage(ctx context.Context, runID string) ([]AgentUsage, error)
	RunCostTotals(ctx context.Context, limit int) ([]RunTotals, error)
}

type User struct {
	// Actor is who they are to every record, actor.Actor's stored form.
	Actor string
	// AccountID is the provider's own id for the account, which survives a rename where the name in Actor does not: GitHub's numeric user id, Google's subject.
	AccountID string
	// Email is the address the provider gave, empty when it gave none.
	Email string
	// Organizations and Groups are what permission rules match on: GitHub
	// organizations and "org/team" teams, a Google Workspace domain.
	Organizations []string
	Groups        []string
	RefreshedAt   time.Time
}

type VersionKey string

type VersionRun struct {
	Version VersionKey
	Run     RunRow
}

type Versions interface {
	// RecordVersions files what a check reported and prunes beyond limit,
	// returning how many were new to check-history. A version already filed
	// keeps its discovery order. Zero means no limit, as Retention's fields
	// do; a negative limit prunes at DefaultResourceVersionCap.
	RecordVersions(ctx context.Context, resourceName string, versions []map[string]any, limit int) (int, error)
	ResourceVersionsJSON(ctx context.Context, resourceName string) ([]VersionKey, error)
	VersionOrders(ctx context.Context, resourceName string) (map[VersionKey]int64, error)
	RecordVersionOrder(ctx context.Context, resourceName string, version VersionKey) (int64, error)
	GreenVersions(ctx context.Context, resourceName string, upstreamJobs []string) ([]map[string]any, error)
	RecordCheckedVersion(ctx context.Context, resourceName string, version VersionKey) error
	// CompareAndSetCheckedVersion moves the checked version to next only if it is still expected — or, with expectedFound false, still absent — reporting whether it moved. It is how a poll advances a resource something else may have advanced since the poll read it.
	CompareAndSetCheckedVersion(ctx context.Context, swap CheckedSwap) (bool, error)
	LastChecked(ctx context.Context, resourceName string) (CheckedResource, bool, error)
	CheckedResources(ctx context.Context) ([]CheckedResource, error)
	// RecordCheckError files why a resource's check failed; an empty message
	// clears what was filed. A check that errors leaves the recorded version
	// exactly where it was — which is correct, and which is why a failing
	// resource is otherwise indistinguishable from a quiet one.
	RecordCheckError(ctx context.Context, resourceName, message string) error
	// CheckErrors is every resource whose last check failed, by name. It is
	// kept apart from CheckedResources because the two answer different
	// questions about different rows: a resource that has never checked
	// successfully has an error and no version at all.
	CheckErrors(ctx context.Context) ([]CheckError, error)
	RecordPassedVersion(ctx context.Context, pass Pass) error
	// RecordPassedVersions is RecordPassedVersion for a whole build's
	// versions in one transaction: all of them land or none does.
	RecordPassedVersions(ctx context.Context, passes []Pass) error
	PassedVersions(ctx context.Context, jobName string, limit int) ([]PassedVersion, error)
	HasPassedVersionSet(ctx context.Context, jobName string, want map[string]VersionKey) (bool, error)
	ConsumedMark(ctx context.Context, jobName, resourceName string) (int64, error)
	RecordConsumedMark(ctx context.Context, jobName, resourceName string, order int64) error
	RecordRunInput(ctx context.Context, runID string, input RunInput) error
	RunInputs(ctx context.Context, runID string) ([]RunInput, error)
	// VersionRuns is every run that took one of versions of the resource as
	// an input, newest first. Naming the versions bounds the read by what a
	// caller shows rather than by run history, which zero leaves unbounded;
	// none named is none read.
	VersionRuns(ctx context.Context, resourceName string, versions []VersionKey) ([]VersionRun, error)
}