runctl

type AbortResult struct {
	RunID string
	Epoch Epoch
	// Reason is one of the stable Reason* values.
	Reason string
	// Detached reports that the worker outlived AbortJoinBudget. Correctness is
	// unaffected because the run is already fenced; only resource release is
	// delayed.
	Detached  bool
	AbortedAt time.Time
	// Partial lists collectors that had already switched when the run died.
	Partial []string
}

type BaselineCollector interface {
	// Name identifies the snapshot section this collector fills.
	Name() string

	// CaptureBaseline samples the opening boundary and returns an immutable
	// handle carrying the sampled values.
	CaptureBaseline(ctx context.Context, runID string, ep Epoch) (SampleResult, error)

	// CaptureFinal samples the closing boundary.
	CaptureFinal(ctx context.Context, runID string, ep Epoch) (SampleResult, error)

	// Collect derives the interval value from two frozen samples. The only
	// legal inputs are base.Sample() and final.Sample(); it must not touch the
	// collector's own fields, the database, or /proc. A type mismatch must be
	// returned as an error, never a panic — measurement may not break the
	// measured application.
	Collect(base, final BaselineHandle) (any, error)

	// Release frees whatever the handle pins. Idempotent.
	Release(h BaselineHandle)
}

type BaselineHandle struct {
	RunID     string
	Epoch     Epoch
	Collector string
	Phase     Phase
	SampledAt time.Time
	// contains filtered or unexported fields
}

type BoundaryResult struct {
	Handle GenerationHandle
	// At is the measured moment of the swap or freeze.
	At time.Time
	// Committed states whether the switch is in effect for this run ID. It is
	// a state predicate, not a "did this call do it" flag, so a retry of the
	// same (runID, epoch) returns the same value.
	Committed bool
}

type BoundaryWindow struct {
	Min    time.Time     `json:"min"`
	Max    time.Time     `json:"max"`
	Spread time.Duration `json:"spread"`
}

type BudgetAware interface {
	Budget() time.Duration
}

type Budgets struct {
	StartRun      time.Duration
	FinishSync    time.Duration
	PhaseBoundary time.Duration // BeginBoundary phase (start side)
	PhaseBaseline time.Duration // CaptureBaseline phase (start side)
	PhaseFreeze   time.Duration // Freeze phase (finish side)
	PhaseFinal    time.Duration // CaptureFinal phase (finish side)

	PerCollectorGeneration time.Duration
	PerCollectorBaseline   time.Duration

	Drain         time.Duration
	SnapshotBuild time.Duration
	Enrich        time.Duration
	AbortJoin     time.Duration
	DetachedReap  time.Duration

	FinishLease  time.Duration
	StartedTTL   time.Duration
	FinishedTTL  time.Duration
	TombstoneTTL time.Duration
	NonceTTL     time.Duration
	Watchdog     time.Duration

	SpreadGeneration time.Duration
	SpreadBoundary   time.Duration
}

type CollectorBoundary struct {
	Name      string    `json:"name"`
	Kind      string    `json:"kind"`
	Required  bool      `json:"required"`
	Phase     Phase     `json:"phase"`
	At        time.Time `json:"at"`
	Committed bool      `json:"committed"`
	// Code is a stable machine-readable code; empty means success.
	Code string `json:"code,omitempty"`
	// Err is the human-readable original message.
	Err string `json:"err,omitempty"`
	// Dropped marks the section as excluded from the snapshot.
	Dropped bool `json:"dropped,omitempty"`
}

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

type Epoch uint64

type FinishAccepted struct {
	RunID            string
	Epoch            Epoch
	Validity         Validity
	Collectors       []CollectorBoundary
	GenerationWindow BoundaryWindow
	BoundaryWindow   BoundaryWindow
	AcceptedAt       time.Time
}

type GenerationCollector interface {
	// Name identifies the snapshot section this collector fills.
	Name() string

	// BeginBoundary swaps in a fresh generation and returns a handle to the
	// generation it just closed. Fast and non-blocking.
	BeginBoundary(ctx context.Context, runID string, ep Epoch) (BoundaryResult, error)

	// Freeze seals the current generation and returns its handle. Observations
	// made after Freeze belong to the next generation, outside the run.
	Freeze(ctx context.Context, runID string, ep Epoch) (BoundaryResult, error)

	// Drain settles in-flight work pinned to the handle's generation only. It
	// must return within DrainCancelGrace of ctx being done and must leave no
	// goroutine that will later modify that generation.
	//
	// Implementations must wait on a per-generation done channel. sync.Cond
	// cannot be interrupted by a context, so a cond-based wait makes this
	// contract impossible to honour when a request never returns.
	Drain(ctx context.Context, h GenerationHandle) error

	// Collect reads the drained generation's fixed data. It must not read the
	// collector's mutable current state.
	Collect(h GenerationHandle) (any, error)

	// Release frees whatever the handle pins. Idempotent: a second Release,
	// or a Release racing the owner's own cleanup, is a no-op.
	Release(h GenerationHandle)
}

type GenerationHandle struct {
	RunID     string
	Epoch     Epoch
	Collector string
	Gen       uint64
	// contains filtered or unexported fields
}

type HealthRecorder interface {
	Set(collector string, status health.Status, message string)
}

type Options struct {
	// Budgets overrides the timing table. Zero fields keep their constants.
	Budgets Budgets
	// Now overrides the clock. Tests inject a controllable clock so leases and
	// TTLs can be exercised without waiting them out.
	Now func() time.Time
	// Health receives the runctl-* keys. Nil disables health reporting.
	Health HealthRecorder
	// Enrich runs after Collect and before the snapshot is published, bounded
	// by the enrich budget. It is how post-freeze extras such as EXPLAIN
	// output are attached without widening the freeze boundary.
	Enrich func(ctx context.Context, s *Snapshot) error
	// DisableWatchdog stops the Controller from starting its lease/TTL sweeper
	// goroutine. Tests that drive Sweep by hand set this.
	DisableWatchdog bool
}

type Phase string

type Registration struct {
	// Name identifies the snapshot section this collector fills.
	Name string
	// Required marks a collector whose failure invalidates the run rather than
	// merely degrading it.
	Required bool
	// SerialOnly excludes the collector from the parallel baseline group. It
	// widens the boundary window, so it is only for collectors that are
	// genuinely unsafe to sample concurrently.
	SerialOnly bool
}

type RunState string

type RunStatus struct {
	RunID    string   `json:"run_id"`
	Epoch    Epoch    `json:"epoch"`
	State    RunState `json:"state"`
	Validity Validity `json:"validity"`
	Reason   string   `json:"reason,omitempty"`
	// AckedBy is one of the stable AckedBy* values.
	AckedBy  string    `json:"acked_by,omitempty"`
	Detached bool      `json:"detached,omitempty"`
	Since    time.Time `json:"since"`
}

type SampleResult struct {
	Handle BaselineHandle
	// At is the measured moment of sampling and equals Handle.SampledAt.
	At time.Time
	// Committed states whether the sample is fixed for this run ID.
	Committed bool
}

type Snapshot struct {
	RunID            string
	Epoch            Epoch
	Validity         Validity
	Trigger          string
	Sections         map[string]any
	Collectors       []CollectorBoundary
	GenerationWindow BoundaryWindow
	BoundaryWindow   BoundaryWindow
	StartedAt        time.Time
	FinishedAt       time.Time
}

type StartResult struct {
	RunID            string
	Nonce            string
	Epoch            Epoch
	State            RunState
	Validity         Validity
	Collectors       []CollectorBoundary
	GenerationWindow BoundaryWindow
	BoundaryWindow   BoundaryWindow
	// PreemptedRunID names the run this one displaced, if any.
	PreemptedRunID string
	StartedAt      time.Time
}

type StartRunOptions struct {
	// Nonce makes the call idempotent. Empty means the Controller mints one.
	Nonce string
	// Preempt aborts an in-flight run instead of failing with ErrRunActive.
	// This is how "the last initialize wins" is made deterministic.
	Preempt bool
	// Reason records who asked: "api", "initialize", "http", "hub".
	Reason string
	// Trigger is recorded on the run as its reset trigger.
	Trigger string
}

type Validity string