port

type AttemptObserver func(session.NetworkAttemptPayload)

type AuthorityDecision struct {
	Allowed bool
	Reason  string
}

type AuthorityEvaluator interface {
	AuthorizeTool(context.Context, AuthorityRequest) (AuthorityDecision, error)
}

type AuthorityOwnerRequirement interface {
	RequiresOwnerIdentity() bool
}

type AuthorityPrincipal struct {
	Definition   string
	Instance     string
	OwnerIssuer  string
	OwnerSubject string
}

type AuthorityRequest struct {
	CapabilitySet   governance.CapabilitySet
	ToolName        string
	Action          string
	DelegationDepth int
	Principal       AuthorityPrincipal
	Resource        *AuthorityResource
}

type AuthorityResource struct {
	Kind      AuthorityResourceKind
	Path      string
	Workspace string
}

type AuthorityResourceKind string

type Chunk struct {
	// Kind discriminates the payload.
	Kind ChunkKind
	// Text carries the assistant text on ChunkText, the human-readable reasoning
	// summary on ChunkReasoning (display-only), the provider's opaque reasoning
	// replay blob on ChunkReasoningItem (e.g. OpenAI encrypted_content or Anthropic
	// (thinking,signature); never displayed), and the provider's opaque phase
	// marker on ChunkPhase (stored on Message.Phase, replayed verbatim).
	Text string
	// ReasoningItemID is set on ChunkReasoningItem. It carries the provider's
	// opaque reasoning ITEM id (e.g. OpenAI's "rs_…" id on a reasoning output
	// item), which the loop stores on Message.ReasoningItemID and the adapter
	// stamps back verbatim on subsequent stateless calls: the OpenAI Responses
	// reasoning item's id field is api:"required" with no omitzero, so a replay
	// without the captured id serialises "id":"" and strict OpenAI-compatible
	// gateways reject it (HTTP 400). Like the Text blob it accompanies, it is
	// never displayed, interpreted, or validated — the STRUCTURE is neutral
	// (one opaque id per reasoning item), the CONTENTS are provider-private.
	// Same discipline as ToolCall.ItemID and the ChunkPhase carrier.
	ReasoningItemID string
	// ToolCall is set on ChunkToolCall.
	ToolCall *session.ToolCall
	// Usage is set on ChunkUsage.
	Usage *session.Usage
	// Stop is set on ChunkDone.
	Stop session.StopReason
}

type ChunkKind int

type Clock interface {
	// Now returns the current time.
	Now() time.Time
}

type ConditionalPrunableStore interface {
	DeleteSessionIfUnchanged(ctx context.Context, expected SessionDiscoveryMeta) (bool, error)
}

type Cursor string

type CursorEventLog interface {
	EventLog

	// AppendEvent durably records ev and returns the cursor positioned after it.
	//
	// It carries the SAME durability obligation as EventLog.Append — nil means
	// the record is on stable storage — and the same at-most-once, no-retry
	// contract. It exists alongside Append rather than replacing it because
	// EventLog is a shipped port with consumers that do not want a cursor.
	AppendEvent(ctx context.Context, id session.SessionID, ev session.Event) (Cursor, error)

	// AppendGap durably records a gap marker at the next position.
	//
	// This is the best-effort, cross-process tier of ADR 0250's three-tier
	// append-gap guarantee: when an append fails, one gap marker is attempted, and
	// if it lands then every watcher everywhere learns of the gap deterministically
	// rather than silently skipping it. It covers the LIKELY failure — one
	// rejected or unencodable record — and not a total backend outage, which by
	// construction cannot record its own failure.
	AppendGap(ctx context.Context, id session.SessionID, reason string) (Cursor, error)

	// ReadAfter yields the log's records STRICTLY AFTER the given cursor.
	//
	// The zero cursor starts from the beginning. A cursor from a superseded log
	// generation yields ErrCursorExpired; one that cannot be decoded or aligned
	// yields ErrCursorMalformed. Neither is ever coerced to a position — a cursor
	// that cannot be honoured exactly must fail, because resuming from
	// approximately the right place is indistinguishable from resuming from the
	// right place until data is already lost.
	//
	// As with EventLog.Read, an error is yielded on a zero-value record and the
	// iterator then stops, a miss is an empty sequence rather than an error, and
	// resources are released when the consumer breaks out early.
	ReadAfter(ctx context.Context, id session.SessionID, after Cursor, opts ReadOptions) iter.Seq2[LogRecord, error]
}

type DeliveryNote struct {
	// Seq is the monotonic per-session sequence assigned at Enqueue time. It is
	// the exactly-once ledger key: the drain records MarkDelivered(origin, seq)
	// so a note is delivered exactly once, and the seq survives the run it was
	// queued during (the ledger is session-scoped).
	Seq uint64
	// SessionID is the ORIGIN session the note is destined for (the queue's key).
	SessionID session.SessionID
	// Text is the opaque rendered note (the renderer's output, stored verbatim).
	Text string
	// EnqueuedAt is when the note was enqueued (for diagnostics/backlog
	// observability; NOT a ledger key).
	EnqueuedAt time.Time
}

type DeliveryQueue interface {
	// Enqueue appends a rendered note for the origin session, assigning the
	// next monotonic per-session seq. It returns the assigned note (the caller
	// may surface its seq to the fire path). When the pending backlog for the
	// origin exceeds the configured cap, the OLDEST pending note is DROPPED
	// (with a WARN via the injected Diagnostics) rather than growing
	// unboundedly on an overloaded origin; the cap 0 means UNBOUNDED (no drop).
	// Enqueue is NOT idempotent: each call mints a fresh seq and a fresh note.
	Enqueue(ctx context.Context, origin session.SessionID, text string) (DeliveryNote, error)

	// Pending returns the origin's not-yet-delivered notes in ENQUEUE order
	// (oldest first). The drain reads this at the origin's next turn boundary
	// / run-entry and records each via MarkDelivered. A miss (no notes for the
	// origin) returns an empty slice, not an error: absence is data.
	Pending(ctx context.Context, origin session.SessionID) ([]DeliveryNote, error)

	// MarkDelivered records that seq was delivered to the origin, removing it
	// from the pending set. It is IDEMPOTENT: a re-mark of an already-delivered
	// (or unknown) seq is a no-op success, never an error. This is the
	// exactly-once ledger: a seq marked delivered is never re-delivered.
	MarkDelivered(ctx context.Context, origin session.SessionID, seq uint64) error
}

type Diagnostics interface {
	// Log emits one record at level with msg and zero or more alternating
	// key/value args (slog-style). The ctx is a trace/baggage carrier only:
	// implementers MUST NOT derive cancellation or deadlines from it.
	Log(ctx context.Context, level Level, msg string, args ...any)
	// With returns a child Diagnostics that carries the supplied key/value args
	// bound onto every subsequent record, leaving the receiver unchanged.
	With(args ...any) Diagnostics
}

type EventLog interface {
	// Append durably records ev under the session id.
	//
	// DURABILITY OBLIGATION: Append must be durable before it returns nil — the
	// record is on stable storage (or committed to the backing service) by the
	// time nil is returned. An implementation that CANNOT guarantee that returns
	// an error rather than buffering silently. A non-nil error may have happened
	// before OR after the record committed (for example, a post-write sync can
	// fail), so the commit outcome is indeterminate to the caller. The caller
	// therefore MUST NOT retry: retrying could duplicate a committed event. (The
	// relay logs a WARN on failure and never aborts the run — a broken log must not
	// break the live stream — but it relies on nil meaning durable, so a silent
	// in-memory buffer that may lose the record on crash is a contract violation,
	// not a valid optimisation.)
	//
	// AT-MOST-ONCE / NO DEDUP: the caller appends each event AT MOST ONCE and
	// never retries, so implementations need NOT deduplicate. The log is keyed by
	// APPEND ORDER: session.Event.Seq is monotonic within a run, but the contract
	// is raw append order — implementations MUST NOT reorder by Seq (or anything
	// else); Read returns events in the exact order Append received them.
	Append(ctx context.Context, id session.SessionID, ev session.Event) error

	// Read returns the session's recorded events in APPEND order as a lazy
	// iterator, matching the LLMProvider.Stream idiom: it is streamable (maps
	// 1:1 to a server-streaming Read RPC and avoids a unary size cap on a long
	// log) and yields each event with a per-item error.
	//
	// IMPLEMENTER OBLIGATION: on an infrastructure fault (an undecodable record,
	// an unknown format tag, an I/O fault) Read yields (session.Event{}, err) and
	// then RETURNS — it yields no further events after an error. A MISS — no log
	// recorded for the id — yields an EMPTY sequence, not an error: absence is
	// data, exactly like an empty conversation. An implementation MUST release any
	// resource it opened (file handle, stream) when the consumer breaks out of the
	// range early, exactly like a well-behaved iter.Seq2.
	Read(ctx context.Context, id session.SessionID) iter.Seq2[session.Event, error]
}

type EventSink interface {
	// Emit publishes a single Event. The ctx is the run's context: telemetry
	// implementers may read a trace span from it (so concurrent runs correlate
	// their spans/metrics to the originating request) but MUST NOT retain it past
	// the call. Implementations must not block the loop indefinitely.
	//
	// The ctx is a trace/baggage carrier ONLY: implementers MUST NOT derive
	// cancellation or deadlines from it. Terminal-event emits (e.g. the final
	// EvResult after Run.Cancel) deliberately pass an already-cancelled ctx, and
	// correctness relies on sinks reading only the span context from it — a sink
	// that bailed on ctx.Err() would drop those terminal events.
	Emit(ctx context.Context, ev session.Event)
}

type HookApprovalLearner interface {
	// LearnHookApproval records that the human authorized the hook-blocked call
	// described by ev (its SessionID/Tool/Input). The consumer decides the waiver
	// scope; the engine only reports the verdict. It is called synchronously at the
	// verdict site and MUST be cheap and non-blocking.
	LearnHookApproval(ctx context.Context, ev governance.HookEvent)
}

type HookRunner interface {
	// Run executes the hook(s) registered for ev.Phase and returns the outcome.
	Run(ctx context.Context, ev governance.HookEvent) (governance.HookOutcome, error)
}

type LLMProvider interface {
	Stream(ctx context.Context, req LLMRequest) (iter.Seq2[Chunk, error], error)
	Capabilities() ProviderCapabilities
}

type LLMRequest struct {
	// System is the layered system prompt.
	System prompt.Layered
	// Messages is the conversation history to send.
	Messages []session.Message
	// Tools are the tool schemas the model may call.
	Tools []tool.ToolSpec
	// Model is the provider model identifier (an opaque string; the adapter maps it
	// to the concrete wire model). Provider-neutral — see the struct doc-comment.
	Model string
}

type Lease struct {
	// SessionID is the session this lease guards.
	SessionID session.SessionID
	// Owner is the holding process's owner-identity string (e.g.
	// "<hostname>-<pid>-<build-nonce>"). Composition builds it once per Build so
	// two Builds in one process get distinct owners.
	Owner string
	// Token is the monotonic fencing epoch for this session id: it advances only
	// on a TAKEOVER Acquire (a free/expired/other-owner lease being granted to a
	// new holder) and is STABLE across a successful Renew. A future CAS-Save can
	// reject a writer holding a stale token; V1 plumbs the token but does not
	// consult it (the enforcement is the lease grant itself).
	Token uint64
	// Expiry is the wall-clock instant the lease lapses if not renewed before it.
	Expiry time.Time
}

type Level int

type LogRecord struct {
	// Kind says whether this position holds an event or a gap marker.
	Kind LogRecordKind

	// Event is the recorded event. It is the zero Event when Kind is
	// LogRecordGap.
	Event session.Event

	// GapReason describes why an append failed, when Kind is LogRecordGap. It is
	// operator-facing diagnostic text and may be empty.
	GapReason string

	// Cursor is the resume token positioned AFTER this record. Handing it back to
	// ReadAfter yields the NEXT record, so a consumer that persists it after
	// processing each record gets at-least-once delivery across a reconnect.
	Cursor Cursor

	// Live reports whether this record arrived AFTER the read had drained
	// everything present when it started.
	//
	// It is the replay/live boundary a follower needs in order to tell a caller
	// "you are now caught up". Computing it in the backend is free — each one
	// already knows where its initial snapshot ended — whereas a consumer cannot
	// recover it afterwards without a second round-trip to ask for the tail.
	Live bool
}

type LogRecordKind string

type MetaLister interface {
	// MetaList returns every stored session's picker metadata, reading only the
	// last snapshot line of each (never the full conversation).
	MetaList(ctx context.Context) ([]SessionMeta, error)
}

type MisfirePolicy int

type NopDeliveryQueue struct{}

type NopDiagnostics struct{}

type PermanentError interface {
	error
	// Permanent returns true when the error is a permanent client-side rejection.
	Permanent() bool
}

type PermissionPolicy interface {
	// Evaluate returns the permission decision for tool call c under mode, scoped
	// to sessionID so per-session LEARNED rules (see Learn) are consulted in
	// addition to the static rule set. The learned rules only ever ADD allows at
	// the lowest scope: a static deny/ask still wins, and plan mode still
	// hard-denies mutations BEFORE any learned rule is consulted.
	//
	// ws is the session's workspace, taken as a READ-ONLY tool.WorkspaceReader
	// (Root + Read + Stat) — the policy only ever LOOKS at the workspace, never
	// mutates it. It is the discovery root for FILE-BASED permission config
	// (issue #13): a RuleResolver re-resolves the project-level
	// `.mecatl/settings.yaml` (and Claude-imported rules) against ws.Root() per
	// session, so two sessions rooted at different workspaces can resolve the SAME
	// tool call differently. ws may be nil (e.g. a child/member engine with no
	// resolver wired) — implementations must treat a nil ws as "no project config".
	Evaluate(ctx context.Context, sessionID session.SessionID, mode session.PermissionMode, c session.ToolCall, ws tool.WorkspaceReader) governance.PermissionDecision

	// Learn records a per-session allow rule derived from tool call c (the model's
	// "allow always" verdict). It is a no-op when c is not safely learnable (a
	// compound/substituted Bash command, or a call with no targetable pattern —
	// see governance.LearnableRule). It NEVER overrides a deny or bypasses plan
	// mode: the learned rule is consulted by Evaluate at the lowest scope only.
	Learn(sessionID session.SessionID, c session.ToolCall)
}

type PermissionStore interface {
	// Record stores a learned rule for sessionID. Implementations should dedupe
	// identical rules so repeated "allow always" for the same call does not grow
	// the set unbounded.
	Record(sessionID session.SessionID, rule governance.Rule)
	// Rules returns a snapshot (copy) of the rules learned for sessionID, safe for
	// the caller to read without holding any lock. An unknown session yields nil.
	Rules(sessionID session.SessionID) []governance.Rule
}

type ProviderCapabilities struct {
	// Image reports whether the provider consumes image parts.
	Image bool
	// Audio reports whether the provider consumes audio parts.
	Audio bool
	// EmbeddedContext reports whether the provider ADVERTISES embedded-context
	// support. Inline-text resources always flatten into the prompt text
	// regardless; this gates whether the adapter declares the capability.
	EmbeddedContext bool
}

type ProviderErrorMetadataError interface {
	error
	ProviderHTTPStatus() int
	ProviderInBandStatus() int
	ProviderErrorCode() string
	ProviderErrorCorrelationKind() string
	ProviderErrorCorrelationID() string
}

type PrunableStore interface {
	// List returns every stored session's id and last-modified time, in no
	// guaranteed order.
	List(ctx context.Context) ([]StoredSession, error)
	// Delete removes the session stored under id. An unknown id is success
	// (idempotent); any returned error is an infrastructure failure.
	Delete(ctx context.Context, id session.SessionID) error
}

type ReadOptions struct {
	// Limit caps the number of records yielded. Zero means unbounded.
	//
	// This is the bounded paging the legacy Read cannot express: it reads the
	// whole log and stops, so a long transcript has no way to arrive in pieces.
	//
	// Zero bounds the SEQUENCE, not the FETCH. It means "yield records until the
	// log ends or the context is cancelled" — it is NOT permission to pull an
	// unbounded response out of storage in one round trip. A backend may, and for
	// a large log should, page internally at whatever size it likes while
	// continuing to yield; that choice is invisible through the iterator, so it
	// is a backend decision rather than a contract term. Stated because the
	// natural reading of "unbounded" is to pass the caller's zero straight
	// through to the storage call, which turns a long transcript into one large
	// allocation (raised in review on #868).
	//
	// When Limit is POSITIVE it is a TOTAL budget for the call, not a per-wake-up
	// one: reaching it ends the read even with Follow set. A follower wanting an
	// unbounded tail sets Limit to zero — under the per-wake-up reading a total
	// cap would be inexpressible, whereas this way both are.
	Limit int

	// Follow keeps the iterator open at the tail instead of ending there,
	// yielding records as they are appended until ctx is done.
	//
	// A follow that ends because ctx was cancelled returns WITHOUT yielding an
	// error: cancellation is how a watch is meant to end, and reporting it as a
	// fault would make every clean detach look like a failure in the logs.
	//
	// A positive Limit still applies and still ends the read: Follow means "do
	// not stop at the tail", not "ignore the budget".
	Follow bool
}

type RetryDisposition = session.RetryDisposition

type RetryDispositionError interface {
	error
	RetryDisposition() session.RetryDisposition
}

type Schedule struct {
	Spec  ScheduleSpec
	State ScheduleState
}

type ScheduleCreator interface {
	// Create atomically creates a NEW schedule under s.Spec.Name: if a schedule
	// already exists under that name, it returns ErrScheduleAlreadyExists
	// (wrapped) and leaves the existing record untouched; otherwise it creates
	// the schedule exactly as Save would for a brand-new name (including the
	// zero-State-defaults-to-enabled convention). The check-and-create is a
	// SINGLE atomic operation from the backend's perspective — two concurrent
	// Create calls for the same name must yield exactly one success and one
	// ErrScheduleAlreadyExists, never two successes.
	Create(ctx context.Context, s Schedule) error
}

type ScheduleFire struct {
	// ID is the fire's unique identifier (caller-assigned at RecordFire time).
	ID string
	// ScheduleName is the schedule this fire belongs to (the foreign key back to
	// ScheduleSpec.Name).
	ScheduleName string
	// SessionID is the session the fire ran as. The fire's full conversation/state
	// is loaded from the SessionStore under this id.
	SessionID session.SessionID
	// FiredAt is when the fire was Claimed (its start instant). It is the same
	// instant recorded as LastFireAt on the schedule.
	FiredAt time.Time
	// StartedAt is when the fire's run actually began (RecordFireStart). It is
	// distinct from FiredAt (the Claim instant): a fire is Claimed BEFORE its run
	// starts, so StartedAt >= FiredAt. A fire written by RecordFireStart is
	// IN-FLIGHT (Stop empty, StartedAt set); a fire written by RecordFire is
	// terminal. Zero on a terminal-only fire (one never observed in-flight by the
	// store, e.g. a legacy record). Issue #386.
	StartedAt time.Time
	// ProgressAt is the last observed progress instant for the fire
	// (RecordFireProgress). Zero means "no progress observed". Issue #386.
	ProgressAt time.Time
	// Deadline is the fire's wall-clock deadline (RecordFireStart): start +
	// ScheduleSpec.FireTimeout (or zero when FireTimeout is zero / the deployment
	// default applies). Zero means "no explicit deadline". Issue #386.
	Deadline time.Time
	// Stop is the terminal stop reason of the fire's run (the same
	// session.StopReason EvResult carries). Empty if the fire has not yet
	// completed.
	Stop session.StopReason
	// Err is the error string if the fire's run failed (Stop == StopError), empty
	// otherwise. It is a flat string (no structured error crosses the store) so a
	// consumer can render it without importing the run's error types.
	Err string
}

type ScheduleManager interface {
	// CreateSchedule validates the spec fail-closed (trigger XOR, cron grammar,
	// the Mutating/Mode invariant, the profile-aware workspace check), applies
	// the create-seam defaults (Singleton=true), computes the first NextFireAt,
	// and saves the schedule. A duplicate name is rejected (create never
	// clobbers an existing schedule).
	CreateSchedule(ctx context.Context, spec ScheduleSpec) (Schedule, error)
	// GetSchedule loads a schedule by name; the not-found case wraps
	// ErrScheduleNotFound.
	GetSchedule(ctx context.Context, name string) (Schedule, error)
	// ListSchedules returns all stored schedules (no guaranteed order).
	ListSchedules(ctx context.Context) ([]Schedule, error)
	// UpdateSchedule re-validates and overwrites the Spec half while preserving
	// the firing State (progress). The not-found case wraps ErrScheduleNotFound.
	UpdateSchedule(ctx context.Context, spec ScheduleSpec) (Schedule, error)
	// DeleteSchedule removes a schedule by name. It is idempotent (deleting an
	// unknown name is success).
	DeleteSchedule(ctx context.Context, name string) error
	// PauseSchedule disables a schedule (Enabled=false) without deleting it.
	PauseSchedule(ctx context.Context, name string) error
	// ResumeSchedule re-enables a paused schedule (Enabled=true).
	ResumeSchedule(ctx context.Context, name string) error
	// FireNow manually fires a schedule by name, SYNCHRONOUSLY-TO-TERMINAL: it
	// claims the slot, mints the fire's session (a "sched--"-prefixed id), runs
	// it, and returns the fire record (ID == SessionID, plus the terminal Stop
	// reason). A paused/done schedule, an exhausted one-shot, or a singleton
	// overlap is rejected (the same sentinels the REST FireNow maps).
	FireNow(ctx context.Context, name string) (ScheduleFire, error)
	// ListFires returns the fire records for a schedule (no guaranteed order).
	ListFires(ctx context.Context, scheduleName string) ([]ScheduleFire, error)
}

type ScheduleOneShotReArmer interface {
	// ReArmOneShot re-enables the named one-shot schedule, sets its NextFireAt to
	// nextFire, and increments OneShotRetryCount — atomically. It is the re-arm
	// primitive the tick loop calls for a crashed one-shot retry. The not-found
	// case wraps ErrScheduleNotFound.
	ReArmOneShot(ctx context.Context, name string, nextFire time.Time) error
}

type ScheduleProviderSelector struct {
	// ProviderID is the opaque provider identifier (the same inert label a session
	// stores on ProviderID). "" means the deployment default.
	ProviderID string
	// ModelID is the opaque model identifier (the same inert label a session stores
	// on ModelID). "" means the deployment default for the provider.
	ModelID string
}

type ScheduleSpec struct {
	Name      string
	Prompt    string
	Parts     []session.Content
	Trigger   TriggerSpec
	Selector  ScheduleProviderSelector
	Profile   string
	Workspace string
	Mode      session.PermissionMode
	Limits    session.Limits
	Mutating  bool
	MaxFires  int
	Misfire   MisfirePolicy
	Singleton bool
	// Timezone is the IANA timezone name (e.g. "America/New_York") the cron
	// expression fires in. Empty means UTC (the recommended default for infra
	// schedules — avoids the 1–3am DST danger zone). The store stores it
	// verbatim (it never interprets it); composition's cronparse call loads
	// it and passes it to NextFire. A one-shot trigger ignores it (a
	// one-shot is an absolute wall-clock instant, already tz-aware via
	// time.Time).
	Timezone  string
	CreatedAt time.Time
	// OneShotRetry is the opt-in at-least-once retry for a one-shot (see the
	// field-by-field contract above). Default false (at-most-once).
	OneShotRetry bool
	// OneShotMaxRetries bounds the re-arm budget when OneShotRetry is true. 0
	// means off (the create-seam applies a default of 3 when OneShotRetry is
	// true and this is 0). One-shot-only; ignored for cron.
	OneShotMaxRetries int
	// CarryContext renders the prior fire's conversation as a fenced untrusted
	// preamble (NOT seeded history — carried context is untrusted). See the
	// field-by-field contract above.
	CarryContext bool
	// OriginSessionID is the session whose terminal result delivery should
	// receive the fire's outcome. Empty means no delivery — the fire's result
	// is discoverable only through the pull-only GetFire/ListFires channel
	// (the v1 pre-delivery posture). A non-empty value names the session the
	// fire's terminal EvResult is delivered to (per ADR 0075, fire-result-
	// delivery). The field is METADATA-ONLY: it is NEVER rendered into a
	// prompt, NEVER surfaced to the model, and NEVER appears in any
	// model-visible surface. It is an infrastructure-level routing key the
	// fire path reads to route the outcome; the model has no access to it.
	//
	// The create-seam validates it: a non-empty OriginSessionID that names a
	// non-existent session is rejected fail-closed (the same ErrInvalidArgument
	// class as the other spec rejections). An empty OriginSessionID is always
	// valid (delivery is OFF — the byte-identical pre-delivery posture).
	OriginSessionID session.SessionID
	// Owner is the verified caller the schedule is attributed to (ADR 0204
	// decision 6). It is captured ONCE at create time — never derived at fire
	// time, because the origin session may be swept by retention while the
	// schedule lives on. The capture rule is the CREATE SEAM's business (the
	// Schedule-tool path reads the executing session's owner via the origin
	// binder; an out-of-band REST/CLI create reads the context principal); the
	// store is identity-blind and round-trips the value verbatim. A nil Owner is
	// an ownerless schedule (the unauthenticated path) — never a fabricated
	// principal.
	//
	// A fire mints its "sched--" session under this owner with GrantType
	// client_credentials (the fire is automated, not interactive), injected via
	// the explicit owner seam so the scheduler's system principal does not become
	// the fire's owner.
	Owner *session.Principal
	// FireTimeout is the per-fire wall-clock deadline (issue #386, the in-flight
	// scheduled-fire state). Zero means "use the deployment default" (the operator-
	// tier default applied by composition; a zero here is NOT "no timeout" — it
	// defers to the deployment default, which may itself be zero for "no explicit
	// deadline"). When non-zero, RecordFireStart stamps FireDeadline = start +
	// FireTimeout on the ScheduleState, and a watchdog reads FireDeadline to
	// terminate the in-flight run with session.StopTimeout when it lapses (a CLEAN,
	// recoverable terminal, like StopBudget). It bounds a single fire's RUN, not
	// the schedule's lifetime (MaxFires bounds the count). Per-fire: each fire gets
	// a fresh deadline from its own start instant. The store stores it inertly
	// (the store never interprets it); composition reads it at fire-start.
	FireTimeout time.Duration
}

type ScheduleState struct {
	// NextFireAt is the ground-truth next fire instant. It is advanced by Claim
	// BEFORE the fire runs (claim-before-fire) and is the field Due compares against.
	// The zero time means "no next fire" (a one-shot that fired, or a cron whose
	// MaxFires is exhausted) — the schedule is effectively done.
	NextFireAt time.Time
	// LastFireAt is the instant of the most recent Claim (the start of the most
	// recent fire), not its completion. Updated atomically in Claim.
	LastFireAt time.Time
	// FireCount is the total number of fires that have been Claimed (a Claim
	// increments it). It is the counter MaxFires is checked against.
	FireCount int
	// Enabled is whether the schedule is active. A schedule may be disabled without
	// deletion (pause/resume). Disabled schedules are excluded from Due even if
	// NextFireAt is in the past. Claim sets Enabled=false when a cron exhausts
	// MaxFires or a one-shot fires.
	Enabled bool
	// LastFireSessionID is the session id of the prior fire. The per-session LEASE
	// on it is the authoritative cross-replica liveness oracle for the singleton
	// check: a still-held lease means the prior fire is running (skip the next
	// fire); a released/expired lease means it finished or crashed (fire freely).
	// Claim sets this to port.PendingFireSessionID; RecordFire overwrites it with
	// the real fire's session id.
	LastFireSessionID session.SessionID
	// OneShotRetryCount is the durable counter of one-shot re-arms (ADR 0059
	// Phase 2). It is incremented atomically by ScheduleOneShotReArmer.ReArmOneShot
	// on each re-arm. When it exceeds ScheduleSpec.OneShotMaxRetries the schedule
	// stays disabled (the one-shot is permanently done — the retry budget is
	// exhausted). The DEFAULT is 0 (no re-arms yet). It is one-shot-only: a cron
	// schedule never re-arms (a cron self-heals via misfire) so the counter stays
	// 0 for cron.
	OneShotRetryCount int
	// LastFireStartedAt is when the current fire's RUN actually began — the instant
	// the fire's session was driven (RecordFireStart), DISTINCT from LastFireAt
	// which is the Claim instant (a claim-before-fire advance happens BEFORE the
	// run starts, so LastFireStartedAt >= LastFireAt). It is the in-flight liveness
	// marker: zero means "the current fire has not started its run yet" (the
	// crash-after-Claim state — Claim happened, RecordFireStart did not). Set by
	// RecordFireStart, cleared by RecordFire (a terminal fire has no in-flight run).
	// Issue #386.
	LastFireStartedAt time.Time
	// LastFireProgressAt is the last observed progress instant for the current
	// fire (RecordFireProgress), advanced as the fire's run produces events. Zero
	// means "no progress observed yet" (the run started but has not emitted, or
	// RecordFireProgress was never called). It is best-effort liveness: a stale
	// value (far behind the wall-clock) is a stuck-fire signal a watchdog may act
	// on. Set by RecordFireStart (seeded to the start instant) and RecordFireProgress;
	// cleared by RecordFire. Issue #386.
	LastFireProgressAt time.Time
	// FireDeadline is the current fire's wall-clock deadline — the instant at
	// which the fire is considered to have exceeded its per-fire timeout
	// (ScheduleSpec.FireTimeout, the deployment default when zero). It is set by
	// RecordFireStart (start + FireTimeout, or zero when FireTimeout is zero / the
	// deployment default applies) and cleared by RecordFire. A watchdog reads it to
	// decide whether to terminate the in-flight run with StopTimeout. Zero means
	// "no explicit deadline (default or not set)". Issue #386.
	FireDeadline time.Time
}

type ScheduleStore interface {
	// Save upserts the schedule by Spec.Name. A schedule with the same name is
	// overwritten; the State half is preserved on overwrite (a Save with a fresh
	// State does not reset firing progress — call Delete + Save to reset). An
	// implementation that cannot store schedules returns ErrScheduleUnsupported
	// (wrapped).
	Save(ctx context.Context, s Schedule) error

	// Load returns the schedule stored under name. The not-found case MUST wrap
	// ErrScheduleNotFound; any other error is an infrastructure failure (or
	// ErrScheduleUnsupported if the backend cannot store schedules at all).
	Load(ctx context.Context, name string) (Schedule, error)

	// Delete removes the schedule stored under name. It is IDEMPOTENT: deleting an
	// unknown name is success (the PrunableStore.Delete discipline), so callers
	// tolerate List/Delete races by construction. Any returned error is an
	// infrastructure failure (or ErrScheduleUnsupported).
	Delete(ctx context.Context, name string) error

	// List returns ALL stored schedules, in no guaranteed order. It applies NO
	// filtering — retention policy (which schedules are prunable, age thresholds)
	// is entirely the CALLER's business (the PrunableStore.List discipline).
	// An implementation that cannot enumerate returns ErrScheduleUnsupported
	// (wrapped).
	List(ctx context.Context) ([]Schedule, error)

	// Due returns the schedules whose NextFireAt is <= now AND Enabled AND (when
	// MaxFires > 0) FireCount < MaxFires. This is the poll-the-store pattern: the
	// in-memory timer in composition is a DERIVED lookahead, the store is ground
	// truth. A schedule returned by Due is NOT yet claimed — the caller must Claim
	// it to win the slot. Due is idempotent and side-effect-free; it does not
	// advance state.
	Due(ctx context.Context, now time.Time) ([]Schedule, error)

	// Claim is the AT-MOST-ONCE atomic advance. It atomically: sets LastFireAt=now,
	// advances NextFireAt to nextFire (the caller-computed next cron fire, or the
	// zero time for a one-shot / a MaxFires-exhausted cron), increments FireCount,
	// sets LastFireSessionID to port.PendingFireSessionID (the caller overwrites it
	// via RecordFire with the real fire's session id), and (for a one-shot or an
	// exhausted cron) sets Enabled=false and zeroes NextFireAt. It returns the
	// claimed schedule (with the advanced State).
	//
	// nextFire is computed by the CALLER (composition, which has the cronparse
	// dependency) — the store is parser-free and never interprets the cron
	// expression. A zero nextFire means "no further fire" (one-shot done, or cron
	// exhausted): Claim sets Enabled=false and zeroes NextFireAt.
	//
	// The at-most-once fence is the durable NextFireAt advance itself — there is no
	// owner/claim-holder field (unlike SessionLease, whose Owner fences concurrent
	// writers on the SAME id). A schedule's fire slot is claimed by advancing
	// NextFireAt past `now`; a peer replica's Due then no longer returns it, so a
	// second Claim on the same slot is structurally impossible (the slot is no
	// longer due). Cross-replica overlap of a STILL-RUNNING prior fire is a
	// SEPARATE concern, handled by the caller's trial-lease on
	// ScheduleState.LastFireSessionID (the singleton check), not by Claim.
	//
	// A crash mid-fire SKIPS the slot — the advance already happened, so a retry
	// does not re-fire. The not-found case wraps ErrScheduleNotFound (a Claim on a
	// deleted schedule is an error, not a silent no-op).
	Claim(ctx context.Context, name string, now, nextFire time.Time) (Schedule, error)

	// ClaimNow is the manual-trigger variant of Claim: it performs the SAME atomic
	// advance (LastFireAt=now, NextFireAt=nextFire, FireCount++,
	// LastFireSessionID=PendingFireSessionID, disable on zero nextFire) but does
	// NOT enforce the NextFireAt <= now due-check — it claims the slot regardless of
	// whether it is due. It is the FireNow primitive (an explicit manual trigger
	// bypasses the cadence but still claims atomically for at-most-once). The
	// Enabled + MaxFires checks STILL apply (a disabled or exhausted schedule
	// cannot be force-fired). The not-found case wraps ErrScheduleNotFound.
	//
	// At-most-once WITHOUT the due-check: Claim's fence is "NextFireAt is past now
	// (a peer's Claim advanced it)", which a not-yet-due slot fails. ClaimNow cannot
	// use that fence (a future slot would pass), so it fences on LastFireAt: a
	// ClaimNow at the SAME now as a prior ClaimNow is rejected (LastFireAt == now
	// ⇒ the advance already happened). This mirrors Claim's discipline — the durable
	// advance IS the fence, there is no owner/claim-holder field. It is
	// crash-recoverable by design (unlike a pending-sentinel fence, which would
	// wedge a schedule forever after a hard crash between ClaimNow and RecordFire —
	// the exact wedge the singleton check's doc warns against): a crash leaves
	// LastFireAt == now, but a later ClaimNow at a new now sees a stale LastFireAt
	// != now and proceeds, so the schedule self-heals instead of wedging. The
	// tick-loop Claim is UNAFFECTED — it keeps its due-check (a due slot is the only
	// thing the tick loop should fire).
	ClaimNow(ctx context.Context, name string, now, nextFire time.Time) (Schedule, error)

	// SetEnabled atomically sets the schedule's Enabled flag WITHOUT touching
	// any other State field (unlike Save, which preserves State on a Spec
	// overwrite — Save CANNOT mutate Enabled because it preserves the existing
	// State half). It is the pause/resume primitive: PauseSchedule sets
	// Enabled=false; ResumeSchedule sets Enabled=true. The not-found case wraps
	// ErrScheduleNotFound. An implementation that cannot store schedules returns
	// ErrScheduleUnsupported (wrapped).
	SetEnabled(ctx context.Context, name string, enabled bool) error

	// RecordFire records the outcome of a fire (f) and updates the schedule's
	// LastFireSessionID to f.SessionID (overwriting the port.PendingFireSessionID
	// value Claim set). It is IDEMPOTENT per fire id: recording the same f.ID twice is
	// a no-op (the second call returns nil without mutating state), so a caller
	// may safely retry after a transient infrastructure failure. The not-found
	// case (the schedule was deleted between Claim and RecordFire) wraps
	// ErrScheduleNotFound.
	//
	// It FLIPS the fire terminal and clears the in-flight ScheduleState fields
	// (LastFireStartedAt/LastFireProgressAt/FireDeadline) — a recorded (terminal)
	// fire has no in-flight run. It overwrites any in-flight fire record the same
	// f.ID had under RecordFireStart with the terminal one (Stop/Err set). Issue #386.
	RecordFire(ctx context.Context, f ScheduleFire) error

	// RecordFireStart persists the IN-FLIGHT fire (issue #386, the in-flight
	// scheduled-fire state) — the fire's run has begun but not yet produced a
	// terminal outcome. It persists the fire record f (ID, SessionID, StartedAt,
	// Deadline) as IN-FLIGHT: Stop empty, StartedAt set. It also sets
	// ScheduleState.LastFireSessionID to the REAL session id f.SessionID
	// (overwriting the port.PendingFireSessionID sentinel Claim stamped) and
	// ScheduleState.LastFireStartedAt to f.StartedAt (and seeds
	// LastFireProgressAt to f.StartedAt when the caller passed a zero ProgressAt).
	// The FireDeadline field on the state is set to f.Deadline (zero when no
	// explicit deadline applies). The not-found case (the schedule was deleted
	// between Claim and RecordFireStart) wraps ErrScheduleNotFound.
	//
	// It is IDEMPOTENT per fire id: recording the same f.ID twice (with the same
	// StartedAt) is a no-op for the in-flight record (it does not re-stamp or
	// double-advance), so a caller may safely retry after a transient
	// infrastructure failure. A RecordFireStart for a fire id that is ALREADY
	// terminal (a prior RecordFire recorded it) is a no-op too (a terminal fire
	// is not re-opened) — the caller should not interleave RecordFireStart after
	// RecordFire, but the store is honest about it. Issue #386.
	RecordFireStart(ctx context.Context, name string, fire ScheduleFire) error

	// RecordFireProgress advances the in-flight fire's last-observed-progress
	// instant (issue #386). It updates ScheduleState.LastFireProgressAt to `at`
	// (when `at` is after the stored value; an earlier `at` is ignored so a
	// reordered/delayed update cannot rewind progress) and the in-flight fire
	// record's ProgressAt to `at`.
	//
	// fireID is the id of the in-flight fire record the caller's RecordFireStart
	// wrote (the same `fire.ID` RecordFireStart took). It targets the SINGLE fire
	// record by its known key directly — there is NO directory/keyspace scan to
	// locate the schedule's in-flight fire (review finding M1: scanning every fire
	// record under the store mutex on every turn boundary is O(N) in the fire
	// population, up to ~10k with 7d retention, and blocks Claim/RecordFire/List/
	// Due). The caller (the fire loop) has fireID in scope.
	//
	// It is BEST-EFFORT and IDEMPOTENT: a missing in-flight fire record (no prior
	// RecordFireStart, or it was already flipped terminal) is a no-op success (the
	// progress is recorded on the state alone), and a not-found SCHEDULE wraps
	// ErrScheduleNotFound. It never re-opens a terminal fire: a progress write to
	// an already-TERMINAL fire record is a no-op for the record (it MUST NOT
	// revert the record from terminal back to in-flight — review finding M2, the
	// cross-replica race a non-atomic GET-then-SET had where a concurrent terminal
	// RecordFire's SET landing between the GET and SET reverted the record). Issue
	// #386.
	RecordFireProgress(ctx context.Context, name string, fireID string, at time.Time) error

	// LoadFire returns the fire record stored under fireID. The not-found case
	// wraps ErrScheduleNotFound; any other error is an infrastructure failure. It
	// is the pull-only result-delivery read path for v1.
	LoadFire(ctx context.Context, fireID string) (ScheduleFire, error)

	// ListFires returns the fire records for a schedule, in no guaranteed order.
	// It is the list companion to LoadFire. The not-found case for the SCHEDULE
	// wraps ErrScheduleNotFound; an empty fire list for an existing schedule is a
	// successful empty slice (not an error). An implementation that cannot store
	// schedules returns ErrScheduleUnsupported (wrapped).
	ListFires(ctx context.Context, scheduleName string) ([]ScheduleFire, error)
}

type SessionCreator interface {
	Create(ctx context.Context, s *session.Session) error
}

type SessionDeleteSupport interface {
	SupportsSessionDelete() bool
}

type SessionDiscoveryMeta struct {
	ID              session.SessionID
	ModifiedAt      time.Time
	State           session.State
	Turns           int
	ModelID         string
	CreatedAt       time.Time
	Title           string
	TitleProvenance session.TitleProvenance
	Owner           *session.Principal
	Workspace       string
	Kind            session.SessionKind
	Relationship    session.SessionRelationship
	// EstimatedBytes is a content-free backend estimate of bytes reclaimed by
	// deleting this session family. Zero means unavailable, never a measured
	// assertion that the family occupies no storage.
	EstimatedBytes int64
}

type SessionLease interface {
	// Acquire grants the lease for id to owner. It SUCCEEDS (returning the
	// granted Lease) when the lease is free, expired, or already held by owner;
	// a takeover (free/expired/other-owner→owner) returns a STRICTLY GREATER
	// Token than any prior grant for that id, while a same-owner re-acquire need
	// not advance the token. It returns ErrLeaseHeld (wrapped) when the lease is
	// held by a DIFFERENT, still-live owner, and ErrLeaseUnsupported (wrapped)
	// when the backend cannot lease at all.
	Acquire(ctx context.Context, id session.SessionID, owner string) (Lease, error)

	// Renew extends a lease the caller still holds, returning a REFRESHED Lease
	// (new Expiry, SAME Token — the immutable-value-object discipline; the caller
	// stores the returned value). It returns ErrLeaseHeld (wrapped) when the
	// caller no longer holds the lease — it expired and was taken by another
	// owner, was released, or the owner/token no longer match. That error is the
	// LOSS SIGNAL: the renewer treats it as "cancel the run". ErrLeaseUnsupported
	// is wrapped only by a backend that never supported leasing (an
	// already-acquired lease implies the backend supports it, so a healthy seam
	// never starts returning Unsupported mid-hold).
	Renew(ctx context.Context, l Lease) (Lease, error)

	// Release relinquishes a lease the caller holds; it is IDEMPOTENT (releasing
	// an unheld/unknown lease, or one whose owner/token no longer match, is
	// success and a no-op — Release only ever drops the caller's OWN hold). A
	// non-nil error is an infrastructure failure, never "not held".
	Release(ctx context.Context, l Lease) error
}

type SessionLineageQuery struct {
	RootID          session.SessionID
	RootIncarnation session.IncarnationID
	Limit           int
}

type SessionLineageReader interface {
	ReadSessionLineage(ctx context.Context, query SessionLineageQuery) (SessionLineageResult, error)
}

type SessionLineageRecord struct {
	ID           session.SessionID
	Kind         session.SessionKind
	Relationship session.SessionRelationship
	OwnerScope   [32]byte
	Incarnation  string
	State        SessionLineageState
	DeletedAt    time.Time
}

type SessionLineageResult struct {
	Records   []SessionLineageRecord
	Truncated bool
}

type SessionLineageState string

type SessionLiveness interface {
	Register(ctx context.Context, id session.SessionID, cancel context.CancelFunc) (release func(), err error)
	IsLive(session.SessionID) bool
}

type SessionMeta struct {
	// ID is the stored session's opaque logical id, byte-exact. A backend whose
	// physical key or filename is a LOSSY transform of the id (so that two
	// distinct ids could share one) MUST recover the id from stored content
	// instead of from the key. A lossless key is free to be the source: keying
	// verbatim, or trimming a fixed prefix, satisfies this.
	ID session.SessionID
	// ModifiedAt is the last-write timestamp (file mtime, or the store's
	// nearest equivalent).
	ModifiedAt time.Time
	// State is the persisted lifecycle state (idle/running/awaiting/completed/
	// ...). Empty when the snapshot could not be decoded or carries an unknown
	// state.
	State session.State
	// Turns is the persisted model-call count. Zero when the snapshot could not
	// be decoded.
	Turns int
	// ModelID is the resolved model id this session ran on (bare string, no
	// provider context). Empty when the session never resolved a model or the
	// snapshot could not be decoded.
	ModelID string
	// CreatedAt is the creation timestamp. Zero when the snapshot could not be
	// decoded.
	CreatedAt time.Time
	// Title is the human-readable session label (seeded once from the first
	// genuine user prompt, clamped). Populated from the snapshot Title ONLY — a
	// session whose Title was never seeded (a pre-Title snapshot, or a
	// multimodal-only first prompt) carries "" here; the caller may fall back to
	// the lazy deriveTitle walk via a full Load if it needs the derived value.
	Title string
	// Owner is the verified caller the session is attributed to (ADR 0204), or
	// nil when the session is ownerless.
	Owner *session.Principal
}

type SessionMetadataCursor struct {
	ModifiedAt   time.Time
	ID           session.SessionID
	Generation   string
	Scope        string
	Continuation string
}

type SessionMetadataPage struct {
	Sessions   []SessionDiscoveryMeta
	NextCursor *SessionMetadataCursor
	TotalCount int
}

type SessionMetadataPageRequest struct {
	Limit             int
	Cursor            *SessionMetadataCursor
	OwnershipEnforced bool
	Owner             *session.Principal
}

type SessionMetadataPager interface {
	PageSessionMetadata(ctx context.Context, request SessionMetadataPageRequest) (SessionMetadataPage, error)
}

type SessionMigrationError struct {
	ItemHandle string `json:"item_handle"`
	ReasonCode string `json:"reason_code"`
	Message    string `json:"message"`
}

type SessionMigrationFamily struct {
	ID          session.SessionID   `json:"-"`
	Handle      string              `json:"handle"`
	Fingerprint string              `json:"fingerprint"`
	OwnerKey    string              `json:"owner_key"`
	Kind        session.SessionKind `json:"kind"`
	State       session.State       `json:"state"`
	Bytes       int64               `json:"bytes"`
}

type SessionMigrationInspection struct {
	Available         bool
	UnavailableReason string
	Generation        string
	V1Families        int64
	V2Families        int64
	InvalidFamilies   int64
	SkippedFamilies   int64
	CurrentBytes      int64
	ReclaimableBytes  int64
	TemporaryBytes    int64
	Families          []SessionMigrationFamily
}

type SessionMigrationJob struct {
	ID               string                  `json:"id"`
	PrincipalKey     string                  `json:"principal_key"`
	State            SessionMigrationState   `json:"state"`
	Generation       string                  `json:"generation"`
	CreatedAt        time.Time               `json:"created_at"`
	UpdatedAt        time.Time               `json:"updated_at"`
	V1Families       int64                   `json:"v1_families"`
	V2Families       int64                   `json:"v2_families"`
	InvalidFamilies  int64                   `json:"invalid_families"`
	SkippedFamilies  int64                   `json:"skipped_families"`
	CurrentBytes     int64                   `json:"current_bytes"`
	ReclaimableBytes int64                   `json:"reclaimable_bytes"`
	TemporaryBytes   int64                   `json:"temporary_bytes"`
	Processed        int64                   `json:"processed"`
	Migrated         int64                   `json:"migrated"`
	Failed           int64                   `json:"failed"`
	Errors           []SessionMigrationError `json:"errors,omitempty"`
	TerminalItems    map[string]bool         `json:"terminal_items,omitempty"`
}

type SessionMigrationState string

type SessionMigrationStore interface {
	InspectSessionMigration(context.Context) (SessionMigrationInspection, error)
	MigrateSessionFamily(context.Context, SessionMigrationFamily) (string, error)
	AcquireSessionMigrationJob(context.Context, string) (acquired context.Context, release func() error, err error)
	CheckSessionMigrationJobOwnership(context.Context) error
	SaveSessionMigrationJob(context.Context, SessionMigrationJob) error
	LoadSessionMigrationJob(context.Context, string) (SessionMigrationJob, error)
}

type SessionStorageHealth struct {
	Available                 bool
	UnavailableReason         string
	CurrentBytes              int64
	CurrentBytesAvailable     bool
	ReclaimableBytes          int64
	ReclaimableBytesAvailable bool
	SessionCount              int64
	FileCount                 int64
	V1Count                   int64
	V2Count                   int64
	MainCount                 int64
	ChildCount                int64
	ScheduledCount            int64
	UnknownCount              int64
	CorruptCount              int64
}

type SessionStorageHealthProvider interface {
	SessionStorageHealth(ctx context.Context) (SessionStorageHealth, error)
}

type SessionStore interface {
	// Save persists the current state of s.
	Save(ctx context.Context, s *session.Session) error
	// Load retrieves the session with the given id. The not-found case MUST wrap
	// port.ErrSessionNotFound; any other error is an infrastructure failure.
	Load(ctx context.Context, id session.SessionID) (*session.Session, error)
}

type StoredSession struct {
	ID         session.SessionID
	ModifiedAt time.Time
}

type StreamProgress = session.StreamProgress

type StreamProgressError interface {
	error
	StreamProgress() session.StreamProgress
}

type ToolCallRecorder interface {
	// ToolCall records that a tool was executed, with its result, the time it
	// spent waiting in the dispatch queue before execution started (queued), and
	// the wall time its execution then took (took).
	//
	// queued is the coordinated-omission measure: it is the gap between when the
	// call ENTERED dispatch and when its execution actually began. For a read-only
	// call cleared to run immediately it is near-zero; for a mutating call held by
	// the read-parallel/mutate-serial ordering (or behind a permission ask) it is
	// the real wait the model's call sat through. Both durations are 0 when no
	// Clock is injected.
	ToolCall(id session.SessionID, call session.ToolCall, result session.ToolResult, queued, took time.Duration)
}

type TriggerKind int

type TriggerSpec struct {
	// Cron is the cron expression (5-field or @-macro). Mutually exclusive with
	// OneShot. Empty unless this is a cron trigger.
	Cron string
	// OneShot is the single wall-clock instant to fire at. Mutually exclusive with
	// Cron. The zero time means "not set". It MUST be in the future at schedule
	// creation; the store does not re-validate this on save.
	OneShot time.Time
}