script

type ApprovalStore interface {
	// ApproveVersion stamps the named version as approved by approver, binds
	// grants to it, and points the script's execution gate at it.
	//
	// The grant's Roles are ignored: the implementation copies them from the
	// version's own author, so an approval can never widen authority beyond
	// what the author held. It returns the approved version as stored.
	//
	// Approving a draft applies its snapshot to the live row, so the served
	// script and the executed version are the same code. Any other pending
	// draft is superseded. It returns ErrVersionConflict when the version was
	// already resolved or the script moved underneath the reviewer.
	ApproveVersion(ctx context.Context, scriptID string, version int, approver string, grants Grants) (*Version, error)
}

type Author struct {
	// Email identifies the person recorded on the version.
	Email string
	// Roles is the authority they held when they wrote it.
	Roles []string
}

type AutoApprovalStore interface {
	// AutoApproveVersion stamps the named version approved on the owner's own
	// authorship, binds grants to it, marks it as an approval nobody reviewed,
	// and points the script's execution gate at it.
	//
	// The grant's Roles are ignored here exactly as they are in ApproveVersion:
	// the implementation copies them from the version's author, who for an
	// automatic approval is the owner. It returns ErrVersionConflict when the
	// version was already resolved or the script moved underneath the write.
	AutoApproveVersion(ctx context.Context, scriptID string, version int, owner string, grants Grants) (*Version, error)
}

type AutoApprover interface {
	// Consider decides whether this script's next version can be approved with
	// no reviewer, and what it would be approved to reach. It writes nothing.
	Consider(ctx context.Context, sc *Script, author Author) AutoDecision

	// Approve binds a decision Consider admitted to the named version, and
	// advances sc to what the write left behind. A decision that was not
	// approvable is answered with its own reason and nothing is written.
	Approve(ctx context.Context, sc *Script, version int, decision AutoDecision) AutoOutcome
}

type AutoDecision struct {
	// Approvable reports that the grant below can be bound with no reviewer.
	Approvable bool
	// Reason states why it cannot, in the owner's terms; empty when Approvable
	// and empty when the script was never a candidate.
	Reason string
	// Grants is what the version would be approved to reach.
	Grants Grants
	// Approved is the version the script executes today, nil when it has none.
	// It is carried so binding can tell an approval that would change nothing
	// from one that would, without reading the row again.
	Approved *Version
}

type AutoOutcome struct {
	// Approved reports that the version is now the script's approved version,
	// bound to a grant the platform minted.
	Approved bool

	// Reason states why it was not, in the owner's terms, so the answer to
	// "why is nothing running this" is on the response that saved it. It is
	// empty when the version was approved, and equally empty when the script was
	// never a candidate — a shared script and an edit somebody else wrote are
	// not refusals, they are the ordinary review path.
	Reason string
}

type Contract struct {
	ID          string   `json:"id" example:"script_a1b2c3d4"`
	Name        string   `json:"name" example:"daily-sales-report"`
	DisplayName string   `json:"display_name,omitempty" example:"Daily Sales Report"`
	Description string   `json:"description,omitempty" example:"Summarize yesterday's sales by region"`
	OwnerEmail  string   `json:"owner_email,omitempty" example:"jane@example.com"`
	Scope       string   `json:"scope" example:"personal"`
	Personas    []string `json:"personas,omitempty" example:"analyst"`
	Category    string   `json:"category,omitempty" example:"reporting"`
	Tags        []string `json:"tags,omitempty" example:"sales,reporting"`
	Status      string   `json:"status" example:"active"`
	Enabled     bool     `json:"enabled" example:"true"`

	// Params is the typed parameter contract a run binds against: the approved
	// version's when one is approved, the live record's otherwise.
	Params []Param `json:"params"`

	Approval ContractApproval `json:"approval"`

	// Schedule is the cadence this script fires on, nil when it has none.
	Schedule *ContractSchedule `json:"schedule,omitempty"`

	// LastRun is the most recent successful run, nil when the script has never
	// completed one. It answers "what does this produce" with evidence rather
	// than with a promise.
	LastRun *ContractRun `json:"last_successful_run,omitempty"`
}

type ContractApproval struct {
	// Approved reports whether a version is approved for execution.
	Approved bool `json:"approved" example:"true"`
	// Version is the approved version number, zero when none is approved.
	Version int `json:"version,omitempty" example:"3"`
	// ApprovedBy and ApprovedAt stamp who admitted that version and when.
	ApprovedBy string     `json:"approved_by,omitempty" example:"admin@example.com"`
	ApprovedAt *time.Time `json:"approved_at,omitempty"`
	// Automatic reports that the platform approved this version itself, because
	// the script is personal and its owner wrote it (#1367). Nobody reviewed it,
	// and a reader of the contract is told so rather than reading ApprovedBy as
	// a decision somebody made.
	Automatic bool `json:"automatic,omitempty" example:"false"`

	// Refusal states why a run requested now would be refused, and is empty when
	// one would be admitted. It is the gate's own answer (RefuseNewRun), not a
	// second reading of it, so a caller is never told a script is runnable that
	// run_script would then decline.
	Refusal string `json:"refusal,omitempty" example:"the script has no approved version, so nothing may execute it"`
}

type ContractOutput struct {
	Name string `json:"name" example:"sales_by_region"`
	Kind string `json:"kind" example:"portal_asset"`
	// Destination is the granted destination the output went to; "portal" for an
	// output that named none.
	Destination string `json:"destination" example:"portal"`
	Format      string `json:"format,omitempty" example:"csv"`
	RowCount    int    `json:"row_count,omitempty" example:"1420"`
	Bytes       int    `json:"bytes,omitempty" example:"98304"`

	// AssetID and AssetVersion locate an OutputKindAsset output.
	AssetID      string `json:"asset_id,omitempty" example:"asset_a1b2c3d4"`
	AssetVersion int    `json:"asset_version,omitempty" example:"7"`

	// Bucket and Key locate an OutputKindObject output.
	Bucket string `json:"bucket,omitempty" example:"acme-exports"`
	Key    string `json:"key,omitempty" example:"weekly/2026/08/sales.csv"`
}

type ContractRun struct {
	RunID      string           `json:"run_id" example:"run_a1b2c3d4"`
	Version    int              `json:"version" example:"3"`
	FinishedAt *time.Time       `json:"finished_at,omitempty"`
	Outputs    []ContractOutput `json:"outputs,omitempty"`
}

type ContractSchedule struct {
	CronSpec string `json:"cron_spec" example:"0 7 * * 1-5"`
	Timezone string `json:"timezone" example:"America/Los_Angeles"`
	Enabled  bool   `json:"enabled" example:"true"`
	// NextRunAt is the next due fire, nil when the schedule is disabled or its
	// expression has no further fire.
	NextRunAt *time.Time `json:"next_run_at,omitempty"`
}

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

type Destination struct {
	// Name is what a script writes as destination="...", unique within a grant.
	Name string `json:"name" example:"acme-drop"`

	// Kind is one of DestinationKinds.
	Kind string `json:"kind" example:"s3"`

	// Connection is the named platform S3 connection the object is written
	// over, empty for the portal. It is also the name the authorization
	// middleware checks independently when the write is issued, so a
	// destination whose connection the script's persona cannot reach is
	// refused a second time, by the authority of record.
	Connection string `json:"connection,omitempty" example:"acme-s3"`

	// Bucket is the bucket objects land in, empty for the portal.
	Bucket string `json:"bucket,omitempty" example:"acme-exports"`

	// Prefix is the key prefix every object written here sits under, empty for
	// the portal and optional for a bucket. It is the boundary of the grant:
	// the script chooses a key beneath it and can never write outside it.
	Prefix string `json:"prefix,omitempty" example:"weekly"`
}

type DryRun struct {
	// ID is the run id the draft executed under, which is also its session id,
	// so the audit rows the run produced are reachable from this account.
	ID       string `json:"id" example:"run_a1b2c3d4"`
	ScriptID string `json:"script_id"`
	// SourceSHA256 is the digest of the source that executed. It is what links
	// this account to a version, and it is a raw digest rather than its hex
	// spelling because that is what the column stores.
	SourceSHA256 []byte `json:"-"`
	RequestedBy  string `json:"requested_by,omitempty" example:"jane@example.com"`
	// Status is RunStatusSucceeded or RunStatusFailed. A draft run has no
	// pending state: it is executed inline, and the caller waits for it.
	Status string `json:"status" example:"succeeded"`
	// Error is why a failed draft failed, including the interpreter traceback.
	Error string `json:"error,omitempty"`
	// Log is what the run printed, bounded when it was captured.
	Log          string         `json:"log,omitempty"`
	LogTruncated bool           `json:"log_truncated,omitempty"`
	Metrics      RunMetrics     `json:"metrics"`
	Outputs      []DryRunOutput `json:"outputs,omitempty"`
	CreatedAt    time.Time      `json:"created_at"`
}

type DryRunOutput struct {
	Name        string `json:"name" example:"daily_sales"`
	Destination string `json:"destination,omitempty" example:"portal"`
	Format      string `json:"format" example:"csv"`
	RowCount    int    `json:"row_count" example:"1200"`
	// Bytes is the serialized length in the declared format. A preview
	// serializes to measure rather than estimating, so it is the size a real
	// run of the same rows would write.
	Bytes int `json:"bytes" example:"48213"`
}

type DryRunStore interface {
	// RecordDryRun stores one account, trimming the author's older accounts of
	// the same script so the table is bounded by the authoring loop's working
	// set rather than by how many times somebody pressed the button.
	RecordDryRun(ctx context.Context, d *DryRun) error

	// LatestDryRun returns the newest account of one script's exact source, or
	// nil when nobody has run it. Nil is the ordinary answer — most versions
	// were never dry-run — so it is not an error.
	LatestDryRun(ctx context.Context, scriptID string, sourceSHA256 []byte) (*DryRun, error)
}

type Edit struct {
	// Before is the persisted pre-edit state and After the fully mutated copy.
	Before *Script
	After  *Script
	// Author is recorded on any version produced, together with the authority
	// they held, which becomes the ceiling on what approving that version can
	// grant (see Author).
	Author Author
	// Auto mints the approval a personal script's own version carries (#1367).
	// Nil is a deployment with no automatic approval, where every version waits
	// for a reviewer.
	Auto AutoApprover
}

type EditOutcome struct {
	// Applied is true when the live row was updated.
	Applied bool `json:"applied"`
	// PendingVersion is the draft version number when the edit was deferred for
	// review; zero when Applied.
	PendingVersion int `json:"pending_version,omitempty"`
	// Auto is what automatic approval did with an applied version (#1367). It is
	// the zero value on a deferred edit, which is a version waiting for a
	// reviewer by definition.
	Auto AutoOutcome `json:"-"`
}

type Grants struct {
	// Roles is the authority the run presents to the authorization middleware,
	// copied from the approved version's author. The middleware resolves them
	// to a persona exactly as it does for a human caller, and that persona —
	// not this struct — is the authority of record.
	Roles []string `json:"roles"`

	// Connections is the set of named connections the script may query. A
	// query that names no connection is refused rather than defaulted: the
	// grant cannot verify a connection the call did not name.
	Connections []string `json:"connections"`

	// Capabilities is the set of host bindings the script may call.
	Capabilities []string `json:"capabilities"`

	// Destinations is the set of places the script may write output, each one a
	// resolved address rather than a label. An empty list means the script may
	// compute but not persist.
	Destinations []Destination `json:"destinations"`
}

type ListFilter struct {
	Scope      string   // "global", "persona", "personal", or "" for all
	Personas   []string // filter by persona membership (OR match)
	OwnerEmail string   // filter by owner
	Enabled    *bool    // filter by enabled state
	Status     string   // filter by lifecycle status; "" for all
	// Category narrows to one category slug; "" for all. Tags narrows to the
	// scripts carrying ANY of the named tags, which is the same OR match the
	// persona axis uses: a reader filtering by two tags is asking for the union
	// of two shelves, not for the scripts on both.
	Category string
	Tags     []string
	Search   string // free-text search on name, display_name, description
	Limit    int    // cap the number of rows returned; 0 means the store default

	// VisibleTo and VisiblePersona apply the scope rules of Script.VisibleTo as
	// a query predicate: global scripts, the persona-scoped scripts of
	// VisiblePersona, and the personal scripts of VisibleTo. They exist as a
	// pair because filtering by owner alone would hide the shared scripts a
	// caller is entitled to see, and filtering by nothing would list the
	// persona-scoped scripts of personas they do not hold. Empty VisibleTo
	// disables the predicate, which is the admin case.
	VisibleTo      string
	VisiblePersona string
}

type Materialization string

type Missing struct {
	Capabilities []string
	Connections  []string
	Destinations []string
}

type Param struct {
	Name        string `json:"name" example:"report_date"`
	Type        string `json:"type" example:"date"`
	Description string `json:"description,omitempty" example:"The business date to report on"`
	Required    bool   `json:"required" example:"true"`
	// Default supplies the value when the caller omits an optional parameter.
	// It is bound through exactly the same coercion and checking as a
	// caller-supplied value, so a default cannot smuggle in a type the
	// parameter does not accept.
	Default any `json:"default,omitempty"`
	// Values enumerates the allowed values of an enum parameter, and is
	// meaningless (and refused) on every other type.
	Values []string `json:"values,omitempty" example:"daily,weekly"`
}

type PendingReview struct {
	ScriptID    string `json:"script_id" example:"script_a1b2c3d4"`
	ScriptName  string `json:"script_name" example:"daily-sales-report"`
	DisplayName string `json:"display_name" example:"Daily Sales Report"`
	Description string `json:"description" example:"Summarize yesterday's sales by region"`
	OwnerEmail  string `json:"owner_email" example:"jane@example.com"`
	Scope       string `json:"scope" example:"global"`
	// Version is the number a reviewer would approve, and VersionStatus is that
	// version's row status — "draft" for a proposed change, "applied" for the
	// snapshot a never-approved script is already serving.
	Version       int    `json:"version" example:"3"`
	VersionID     string `json:"version_id" example:"sver_a1b2c3d4"`
	VersionStatus string `json:"version_status" example:"draft"`
	// Author is who wrote the version and AuthorRoles is the authority
	// approving it would bind, which approval copies rather than accepts.
	Author      string   `json:"author" example:"jane@example.com"`
	AuthorRoles []string `json:"author_roles" example:"analyst"`
	// FirstApproval marks a script that has never had an approved version, so
	// nothing of it executes today. The distinction matters to a reviewer:
	// approving a change alters what already runs unattended, while approving a
	// first version starts something running.
	FirstApproval bool `json:"first_approval" example:"true"`
	// CreatedAt is when the version was authored, which is how long the
	// decision has been outstanding.
	CreatedAt time.Time `json:"created_at" example:"2026-08-14T09:00:00Z"`
}

type Referenced struct {
	Capabilities []string
	Connections  []string
	Destinations []string

	// Incomplete is true when a call computes its connection or its destination
	// instead of naming one, so the lists above are known to be short. A grant
	// derived from a short list is a grant the run then refuses itself on, so it
	// is a refusal to derive rather than a partial answer.
	Incomplete bool
}

type RejectionStore interface {
	// RejectVersion marks a pending draft rejected, leaving the live script and
	// its approved version untouched.
	//
	// Only a draft can be rejected. The live version of a never-approved script
	// is also awaiting review, but rejecting it would mark the code the script
	// is serving as rejected while it kept being served; declining that version
	// means leaving it unapproved, which is already what it is. Returns
	// ErrVersionConflict when the version is not a pending draft.
	RejectVersion(ctx context.Context, scriptID string, version int) error
}

type ReviewStore interface {
	// ListPendingReviews returns every version awaiting approval across all
	// scripts, oldest first, which is the order a queue is worked.
	//
	// Two states qualify, and both mean "the platform is not executing this
	// version": a pending draft, and the live version of a script that has no
	// approved version at all. A script the execution gate would refuse anyway
	// — disabled, deprecated, or superseded — is excluded, because approving it
	// would change nothing and nothing could clear it from the queue.
	ListPendingReviews(ctx context.Context) ([]PendingReview, error)
}

type Run struct {
	ID string `json:"id" example:"run_a1b2c3d4"`

	ScriptID  string `json:"script_id"`
	VersionID string `json:"version_id"`
	// Version is the version NUMBER executed, carried alongside the id so a
	// run reads as "daily-sales v3" without a second lookup.
	Version int `json:"version" example:"3"`

	Trigger string `json:"trigger" example:"tool"`
	Status  string `json:"status" example:"succeeded"`

	// ScheduleID names the schedule that materialized this run, and is empty
	// for every other trigger. It is what the single-fire guarantee is written
	// against: the run's (schedule, fire time) pair is unique, so however many
	// replicas notice the same fire, exactly one run exists for it.
	ScheduleID string `json:"schedule_id,omitempty"`

	// Params are the bound, type-checked parameter values the run executes
	// with. They are bound once, when the run is created, so a re-read of the
	// row explains the run exactly.
	Params map[string]any `json:"params,omitempty"`

	// RequestedBy is the email of whoever asked for this run.
	RequestedBy string `json:"requested_by,omitempty" example:"jane@example.com"`

	// FireTime is the instant the run computes against, handed to the script as
	// run.fire_time. It is pinned when the run is created and never moves,
	// which is what ScheduledFor cannot promise: an infrastructure retry pushes
	// the due time out, and a run delayed that way must still produce the report
	// it was asked for rather than one shifted by the delay.
	FireTime     time.Time  `json:"fire_time"`
	ScheduledFor time.Time  `json:"scheduled_for"`
	StartedAt    *time.Time `json:"started_at,omitempty"`
	FinishedAt   *time.Time `json:"finished_at,omitempty"`

	// Attempt counts claims of this run, and LockedUntil / LockedBy carry the
	// current worker's lease. Together they are the fencing token: a write
	// from a worker whose lease expired and was reclaimed matches no row.
	Attempt     int        `json:"attempt"`
	LockedUntil *time.Time `json:"locked_until,omitempty"`
	LockedBy    string     `json:"locked_by,omitempty"`

	Error        string      `json:"error,omitempty"`
	Log          string      `json:"log,omitempty"`
	LogTruncated bool        `json:"log_truncated,omitempty"`
	Metrics      RunMetrics  `json:"metrics"`
	Outputs      []RunOutput `json:"outputs,omitempty"`

	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type RunFilter struct {
	// ScriptID scopes the listing to one script; empty lists across scripts.
	ScriptID string
	// Status scopes the listing to one lifecycle status.
	Status string
	// Limit caps the rows returned; zero means the store default.
	Limit int
}

type RunLease struct {
	RunID   string
	Worker  string
	Attempt int
}

type RunMetrics struct {
	Steps      uint64 `json:"steps"`
	DurationMS int64  `json:"duration_ms"`
	Queries    int    `json:"queries"`
	Exports    int    `json:"exports"`
}

type RunOutput struct {
	Name string `json:"name"`
	// Destination is the granted destination's name. It is empty on rows
	// written before destinations existed, which Destination() reads as the
	// portal.
	Destination string `json:"destination,omitempty"`

	// AssetID and AssetVersion identify a portal output.
	AssetID      string `json:"asset_id,omitempty"`
	AssetVersion int    `json:"asset_version,omitempty"`

	// Bucket and Key locate a delivered object.
	Bucket string `json:"bucket,omitempty"`
	Key    string `json:"key,omitempty"`

	Format   string `json:"format"`
	RowCount int    `json:"row_count"`
	Bytes    int    `json:"bytes"`
}

type RunResult struct {
	// Status is RunStatusSucceeded or RunStatusFailed.
	Status string
	// Error is the failure message, carrying the Starlark backtrace when the
	// script itself failed.
	Error        string
	Log          string
	LogTruncated bool
	Metrics      RunMetrics
}

type RunStore interface {
	// Enqueue inserts a pending run, assigning ID when empty.
	Enqueue(ctx context.Context, r *Run) error

	// GetRun returns one run by id, or ErrRunNotFound.
	GetRun(ctx context.Context, id string) (*Run, error)

	// ListRuns returns runs matching the filter, newest first.
	ListRuns(ctx context.Context, filter RunFilter) ([]Run, error)

	// Claim takes the next due run for worker, holding it for lease. It
	// returns ErrNoWork when nothing is due.
	Claim(ctx context.Context, worker string, lease time.Duration) (*Run, error)

	// RecordOutput appends one persisted output to the run. It is written as
	// soon as the output exists, not at the end of the run, so a reclaimed run
	// can tell what it already wrote.
	RecordOutput(ctx context.Context, lease RunLease, out RunOutput) error

	// Finish records a terminal result for the claimed run.
	Finish(ctx context.Context, lease RunLease, res RunResult) error

	// Retry returns the claimed run to pending, due after backoff, recording
	// the cause. Reserved for infrastructure failures: a script error is
	// deterministic and retrying it changes nothing.
	Retry(ctx context.Context, lease RunLease, cause string, backoff time.Duration) error

	// PurgeRuns deletes terminal runs older than retention, returning the
	// number removed.
	PurgeRuns(ctx context.Context, retention time.Duration) (int64, error)
}

type Schedule struct {
	ID       string `json:"id"`
	ScriptID string `json:"script_id"`

	// CronSpec is a standard five-field cron expression or one of the
	// descriptors (@daily, @hourly, @every 30m).
	CronSpec string `json:"cron_spec" example:"0 7 * * 1-5"`
	// Timezone is the IANA zone the spec is read in.
	Timezone string `json:"timezone" example:"America/Los_Angeles"`

	// Params are the values every fire binds, with tokens unexpanded. They are
	// stored as written so the schedule reads as what it means ("report on the
	// day it fires") rather than as whatever date happened to be current when
	// somebody set it.
	Params map[string]any `json:"params,omitempty"`

	Enabled bool `json:"enabled"`

	// NextRunAt is when the next fire is due, and zero when the expression has
	// no further fire at all. It is the materializer's efficiency index, not
	// its correctness guarantee: two replicas may read the same due schedule,
	// and what stops them producing two runs is the unique index on the run
	// they insert.
	//
	// While the schedule is disabled the field still holds the fire it was
	// paused on, because resuming picks up from there. What a READER is told is
	// DueAt, which is empty for a paused schedule; see MarshalJSON.
	NextRunAt time.Time `json:"next_run_at,omitzero"`
	// LastFireAt is the fire time of the most recent run this schedule
	// produced, empty until it has produced one.
	LastFireAt *time.Time `json:"last_fire_at,omitempty"`
	// MissedFires counts fires that came due while the platform was not
	// materializing them, cumulatively. Catching up on them is deliberately
	// not attempted (see NextFire), so the count is the visible record of the
	// gap.
	MissedFires int `json:"missed_fires"`

	CreatedBy string    `json:"created_by,omitempty" example:"jane@example.com"`
	UpdatedBy string    `json:"updated_by,omitempty" example:"jane@example.com"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type ScheduleAdvance struct {
	// ID names the schedule and From is where the caller found NextRunAt. The
	// update applies only if the row still carries From, which is what makes
	// the step idempotent across replicas.
	ID   string
	From time.Time
	// Next is the fire time to store — zero when the expression has no further
	// fire, which parks the schedule rather than leaving it perpetually due —
	// and Fired, when non-zero, is the fire this pass materialized.
	Next  time.Time
	Fired time.Time
	// Missed is added to the schedule's cumulative missed-fire count.
	Missed int
}

type ScheduleFilter struct {
	// ScriptID scopes the listing to one script.
	ScriptID string
	// ScriptIDs scopes the listing to a set of scripts, which is how a caller
	// lists the schedules it may see without reading the rest and discarding
	// them. An EMPTY, non-nil slice means "no scripts" and matches nothing —
	// the distinction matters, because a caller who can see nothing must not
	// fall through to an unfiltered listing.
	ScriptIDs []string
	// Enabled, when set, scopes the listing to enabled or disabled schedules.
	Enabled *bool
	// Limit caps the rows returned; zero means the store default.
	Limit int
}

type ScheduleFire struct {
	// At is the fire to materialize, meaningful only when Due is true.
	At time.Time
	// Missed counts the fires stepped over without materializing.
	Missed int
	// Next is the due time to store, zero when the expression has no further
	// fire.
	Next time.Time
	// Due reports whether At should be materialized at all.
	Due bool
}

type ScheduleRequest struct {
	CronSpec string
	Timezone string
	// Params are the bindings, with tokens as written.
	Params map[string]any
	// Enabled is a pointer so a request that does not mention it leaves an
	// existing schedule's state alone; a new schedule with nothing said is on,
	// because setting a schedule is asking for it to run.
	Enabled *bool
	// Actor is who is making the change, recorded on the row.
	Actor string
}

type ScheduleStore interface {
	// SetSchedule creates or replaces the schedule of one script, assigning ID
	// when empty. A script has at most one schedule: a second cadence is a
	// second script, which keeps the run history of "the 07:00 report" from
	// interleaving with another cadence's.
	SetSchedule(ctx context.Context, s *Schedule) error

	// GetSchedule returns one script's schedule, or ErrScheduleNotFound.
	GetSchedule(ctx context.Context, scriptID string) (*Schedule, error)

	// ListSchedules returns schedules matching the filter.
	ListSchedules(ctx context.Context, filter ScheduleFilter) ([]Schedule, error)

	// SetScheduleEnabled turns one script's schedule on or off, recording who
	// did it. Disabling is how a schedule is retired: the row stays, because a
	// schedule that produced runs is part of the explanation of those runs.
	SetScheduleEnabled(ctx context.Context, scriptID string, enabled bool, actor string) error

	// DueSchedules returns enabled schedules whose next fire has arrived.
	DueSchedules(ctx context.Context, now time.Time, limit int) ([]Schedule, error)

	// MaterializeRun inserts one scheduled run, reporting what happened: the
	// run was created, it was skipped because the previous one is still open,
	// or another replica got there first.
	MaterializeRun(ctx context.Context, r *Run) (Materialization, error)

	// AdvanceSchedule moves a schedule forward after a materialization pass.
	// It is conditional on the schedule still being where the caller found it,
	// so two replicas that walked the same fire do not double-count the misses
	// or move the schedule twice. It reports whether the row moved.
	AdvanceSchedule(ctx context.Context, adv ScheduleAdvance) (bool, error)
}

type ScoredScript struct {
	Script Script  `json:"script"`
	Score  float64 `json:"score"`
}

type Script struct {
	ID          string   `json:"id" example:"script_a1b2c3d4"`
	Name        string   `json:"name" example:"daily-sales-report"`
	DisplayName string   `json:"display_name" example:"Daily Sales Report"`
	Description string   `json:"description" example:"Summarize yesterday's sales by region"`
	Source      string   `json:"source" example:"rows = platform.query(connection='primary', sql='SELECT 1')"`
	Params      []Param  `json:"params"`
	Scope       string   `json:"scope" example:"personal"`
	Personas    []string `json:"personas" example:"analyst"`
	OwnerEmail  string   `json:"owner_email" example:"jane@example.com"`
	// Category files the script under one lowercase slug, the axis a listing
	// filters on and a reader scans. It is the same axis a resource and an
	// insight carry, written the same way (#1369).
	Category string   `json:"category,omitempty" example:"reporting"`
	Tags     []string `json:"tags" example:"sales,reporting"`
	Enabled  bool     `json:"enabled" example:"true"`

	// Lifecycle.
	Status       string     `json:"status" example:"draft"`
	SupersededBy string     `json:"superseded_by,omitempty" example:"daily-sales-report-v2"`
	DeprecatedAt *time.Time `json:"deprecated_at,omitempty"`

	// Version is the number of the snapshot the live row currently carries.
	// Pending draft versions above this number exist in the history and are not
	// served.
	Version int `json:"version" example:"3"`

	// ApprovedVersionID is THE execution gate: the id of the one version the
	// platform may execute. Empty means the script has no approved version and
	// nothing will run it — which is every script today, because the approval
	// action and the runner that reads this pointer arrive with the execution
	// gate. Draft execution (manage_script run_draft) deliberately never reads
	// it: a draft runs under its author's own identity and authority, so it
	// needs no approval, and it also cannot stand in for one.
	ApprovedVersionID string `json:"approved_version_id,omitempty"`

	CreatedAt time.Time `json:"created_at" example:"2026-08-13T14:30:00Z"`
	UpdatedAt time.Time `json:"updated_at" example:"2026-08-13T14:30:00Z"`
}

type SearchQuery struct {
	// Embedding is the query vector. A nil Embedding selects lexical-only
	// ranking, which is exactly the behavior a deployment with no embedding
	// provider has always had; a non-nil one selects hybrid ranking over the
	// vectors the indexjobs scripts consumer writes.
	Embedding []float32
	// QueryText is the raw intent text the lexical ranking matches.
	QueryText string
	// OwnerEmail is the caller identity, for personal-scope visibility. Empty
	// leaves the caller seeing no personal scripts at all, including their own.
	OwnerEmail string
	// Personas is every persona the caller belongs to, for persona-scope
	// visibility.
	Personas []string
	// Limit caps the candidates returned; see EffectiveLimit.
	Limit int
}

type Searcher interface {
	Search(ctx context.Context, q SearchQuery) ([]ScoredScript, error)

	// Contract composes the contract document for one script: the script's own
	// record, the approved version's parameter contract and approval stamp, its
	// cadence when it has one, and its last successful run. It applies no
	// visibility rule of its own — the caller has already established that this
	// script may be seen.
	Contract(ctx context.Context, id string) (*Contract, error)
}

type Store interface {
	// Create persists a new script and its first version, assigning ID when
	// empty. The author is recorded on that version along with the authority
	// they held, which is the ceiling on what approving it can grant.
	Create(ctx context.Context, s *Script, author Author) error

	// Get retrieves a shared (global or persona) script by its globally unique
	// name. Returns nil, nil if not found.
	Get(ctx context.Context, name string) (*Script, error)

	// GetPersonal retrieves a personal script by owner and name. Returns
	// nil, nil if not found.
	GetPersonal(ctx context.Context, ownerEmail, name string) (*Script, error)

	// GetByID retrieves a script by ID. Returns nil, nil if not found.
	GetByID(ctx context.Context, id string) (*Script, error)

	// Update modifies an existing script.
	Update(ctx context.Context, s *Script) error

	// Delete removes a script by ID.
	Delete(ctx context.Context, id string) error

	// List returns scripts matching the filter, newest first.
	List(ctx context.Context, filter ListFilter) ([]Script, error)
}

type Version struct {
	ID          string   `json:"id" example:"sver_a1b2c3d4"`
	ScriptID    string   `json:"script_id" example:"script_a1b2c3d4"`
	Version     int      `json:"version" example:"3"`
	DisplayName string   `json:"display_name" example:"Daily Sales Report"`
	Description string   `json:"description" example:"Summarize yesterday's sales by region"`
	Category    string   `json:"category,omitempty" example:"reporting"`
	Source      string   `json:"source"`
	Params      []Param  `json:"params"`
	Tags        []string `json:"tags" example:"sales,reporting"`
	Author      string   `json:"author" example:"jane@example.com"`
	// AuthorRoles is the authority the author held when this snapshot was
	// written — the ceiling on what approving it can grant. See Author.
	AuthorRoles []string   `json:"author_roles,omitempty" example:"analyst"`
	Status      string     `json:"status" example:"applied"`
	ApprovedBy  string     `json:"approved_by,omitempty" example:"admin@example.com"`
	ApprovedAt  *time.Time `json:"approved_at,omitempty"`
	// AutoApproved marks an approval the PLATFORM made rather than a person
	// (#1367): a personal script's own owner wrote this version, so the grant
	// was minted from what its code reaches instead of being asked of a
	// reviewer. ApprovedBy still names the owner, because they are accountable
	// for it; this is what separates their authorship from somebody's decision,
	// so an operator reading the history can tell which scripts nobody reviewed.
	AutoApproved bool `json:"auto_approved,omitempty" example:"false"`
	// Grants is the capability set bound to this version at approval: what the
	// approver approved this code to be able to do. It is empty on every
	// version that was never approved, and the approval action is the only
	// writer — changing what a script may reach means approving it again, which
	// re-stamps the approval alongside the new grant.
	Grants    Grants    `json:"grants"`
	CreatedAt time.Time `json:"created_at" example:"2026-08-13T14:30:00Z"`
}

type VersionStore interface {
	// UpdateWithVersion persists s like Store.Update and, when any versioned
	// snapshot field differs from the stored row, records a new applied version
	// authored by author and advances s.Version to it.
	//
	// ungated carries the edit funnel's verdict that this edit needs no review,
	// which the store cannot re-derive: an edit to a script with an approved
	// version reaches the live row ONLY when automatic approval decided it
	// covers it (#1367), and that decision needs a static read of the source
	// this layer has no business doing. Everything else is re-validated against
	// the row as locked and refused as a conflict, which is what stops an edit
	// racing an approval from swapping code out from under it.
	UpdateWithVersion(ctx context.Context, s *Script, author Author, ungated bool) error

	// CreateDraftVersion snapshots proposed's versioned fields as a new draft
	// version without touching the live row, returning the new version number.
	// The approved version keeps executing until the draft is approved.
	CreateDraftVersion(ctx context.Context, scriptID string, proposed *Script, author Author) (int, error)

	// ListVersions returns every version of the script, newest first.
	ListVersions(ctx context.Context, scriptID string) ([]Version, error)

	// GetVersion returns one version with its full source, or nil, nil when the
	// script has no such version.
	GetVersion(ctx context.Context, scriptID string, version int) (*Version, error)

	// GetVersionByID returns one version by its id, or nil, nil when no such
	// version exists. It is how a run loads the code it is allowed to execute:
	// the execution gate is an id, so the runner resolves that id and never a
	// version number, which could be renumbered or point at a later draft.
	GetVersionByID(ctx context.Context, id string) (*Version, error)
}