scheduler

type Config struct {
	// Store is the durable schedule registry. Required.
	Store port.ScheduleStore
	// Lease is the cross-process leader-lease backend for the
	// `port.SchedulerLeaderLeaseID` ("__scheduler__") leader lease. nil means
	// single-replica by affinity: the scheduler runs standalone (no
	// cross-process leader gate) — the byte-identical default when no lease
	// backend is wired, exactly as the run-entry lease defaults off.
	Lease port.SessionLease
	// LeaseOwner is the per-process owner string composition builds once per
	// Build (the same "<hostname>-<pid>-<nonce>" shape the run-entry seam
	// uses). Required when Lease != nil; ignored otherwise.
	LeaseOwner string
	// LeaseTTL is the leader-lease lifetime requested at Acquire. A non-positive
	// value defaults to defaultLeaderLeaseTTL. Ignored when Lease == nil.
	LeaseTTL time.Duration
	// LeaseRenewInterval is how often the leader-lease renewer refreshes the
	// held lease. A non-positive value defaults to LeaseTTL/3. Ignored when
	// Lease == nil.
	LeaseRenewInterval time.Duration
	// Fire is the composition-supplied run-entry callback. Composition wires
	// this in Phase 1f; for Phase 1e's unit tests a stub records fires. Required.
	Fire FireFunc
	// CanProcess admits only schedules this scheduler may touch. A nil function
	// preserves the compatibility path. OIDC composition supplies a predicate that
	// excludes ownerless pre-cutover schedules before Claim, so a background worker
	// cannot adopt, fire, or repeatedly mutate an inaccessible resource.
	CanProcess func(port.Schedule) bool
	// PresentScheduleName projects the authoritative stored schedule to its
	// caller-visible name for lifecycle events and metric labels. It must never be
	// used for store operations; nil preserves Spec.Name.
	PresentScheduleName func(port.Schedule) string
	// Clock supplies `now` for the tick loop and Claim. Required.
	Clock port.Clock
	// Diagnostics is the operational logging seam. A nil value is treated as
	// port.NopDiagnostics so the scheduler is nil-safe by construction.
	Diagnostics port.Diagnostics
	// TickInterval is how often the tick loop polls ScheduleStore.Due. A
	// non-positive value defaults to defaultTickInterval.
	TickInterval time.Duration
	// MinInterval is the frequency floor the composition create-seam enforces at
	// Save time (a schedule whose cadence is tighter than this is rejected,
	// fail-closed). It is NOT read by the tick loop — it lives on Config so a
	// future self-pushing lookahead can consult it without widening the
	// constructor. Documented here to keep it honest.
	MinInterval time.Duration
	// MaxConcurrentFires bounds the per-tick fire fan-out via an errgroup with
	// SetLimit. A non-positive value defaults to defaultMaxConcurrentFires.
	MaxConcurrentFires int
	// StopFireGrace is how long Stop waits for in-flight fires to drain before
	// abandoning them. A non-positive value defaults to stopFireGrace. It is a
	// Config field (not a flag) so a test can shrink it.
	StopFireGrace time.Duration
	// EmitScheduleEvent is the OPTIONAL composition-injected callback the
	// scheduler invokes to emit an EvScheduleFired/Skipped/Failed event. It is
	// nil-safe (nil = no event emitted — the byte-identical no-emit path).
	// Composition wires it to emit into the fire session's event log / the
	// Service's event sink. The scheduler pkg stays EventSink-free (testable, no
	// engine/agent import): the payload is a plain session.SchedulePayload value
	// object, not an EventSink/port import. The scheduler invokes it from
	// fireClaimed (fired/failed) and fireOne/FireNow (skipped) — the caller
	// decides the kind; the callback decides where it lands. The ctx is the
	// firing caller's, so the durable append can attribute the event to whoever
	// acted (a tick fire descends from Start's system-principal root; a manual
	// FireNow keeps its requester) — ADR 0204 decision 5.
	EmitScheduleEvent func(ctx context.Context, payload session.SchedulePayload)
	// ScheduleMetrics is the OPTIONAL composition-injected metrics callback
	// (issue #233, Phase 2b). It is nil-safe (nil = no metrics recorded — the
	// byte-identical no-metrics path). The scheduler invokes it from
	// fireClaimed (fired/failed, with the Claim→terminal duration) and
	// fireOne/FireNow (skipped, duration 0). Composition wires it over the
	// telemetry adapter's Metrics.EmitSchedule — the scheduler pkg stays
	// telemetry-import-free (the metrics seam is a plain callback, mirroring
	// EmitScheduleEvent). The payload's Kind ("fired"/"skipped"/"failed")
	// labels the outcome; duration > 0 only for a fired/failed fire.
	ScheduleMetrics func(payload session.SchedulePayload, duration time.Duration)
	// DeliverFireResult is the OPTIONAL composition-injected callback
	// (ADR 0075, fire-result-delivery) the scheduler invokes from fireClaimed
	// AFTER RecordFire, to route a fire's terminal result back into its origin
	// conversation. It is nil-safe (nil = the byte-identical no-delivery path,
	// matching the pre-ADR-0075 pull-only posture). Composition wires it to
	// deliverFireResult(svc, queue) which: skips an empty OriginSessionID (no
	// delivery), renders the note (renderFireDelivery), enqueues it to the
	// durable DeliveryQueue, and drives a delivery run into an idle/completed/
	// cancelled/failed origin via StartRunContent (loadAndReopen reopens/
	// recovers); a BUSY or AWAITING origin is left queued (the loop's Step 2a
	// drain records it at the next turn boundary); a deleted/child/sched--
	// origin degrades to pull-only with a WARN. A delivery error WARNs and
	// NEVER fails the fire (delivery is decoupled — the fire already recorded).
	// The scheduler invokes it for fired/failed fires alike (a failed fire may
	// still have an origin that should know it errored); the callback decides
	// whether to deliver based on the stop reason (it may skip a StopError
	// fire's delivery, or deliver it — the ADR does not mandate either).
	DeliverFireResult func(ctx context.Context, sched port.Schedule, fire port.ScheduleFire)
	// ReconcileStaleFire is the OPTIONAL composition-injected callback
	// (issue #386 Phase 4b, the stale-fire reconciler) the scheduler invokes
	// from the tick loop's reconcile scan when it DETECTS a stale in-flight
	// fire — a claimed-but-never-terminal fire left behind by a crashed
	// process (acceptance criterion #7). It is nil-safe (nil = the
	// byte-identical no-reconcile path, the pre-Phase-4b posture): detection
	// is store-only (the scheduler CAN do it — it reads ScheduleStore + the
	// leader-lease/isPriorFireLive seam it already has), but the SETTLE
	// (session-load + cancel + RecordFire) needs Service methods the scheduler
	// package must not import (the layering rule: the scheduler is
	// storage-agnostic and must NOT import internal/adapter/server). So the
	// reconcile callback is composition-injected, mirroring Fire/
	// DeliverFireResult/DeliverFireStarted.
	//
	// Two crash cases the detector hands the callback:
	//  1. Crash after Claim, before session creation: LastFireSessionID ==
	//     port.PendingFireSessionID (the sentinel) and stale (LastFireAt older
	//     than the stale window). No session exists. The callback records a
	//     terminal StopError fire ("fire lost: process crashed between claim
	//     and session creation") via RecordFire with a minted id, and clears
	//     the in-flight fields.
	//  2. Crash after session creation, before RecordFire: LastFireSessionID
	//     is a real "sched--" id, the fire record is still in-flight (Stop
	//     empty), the session's lease is released/expired (not live — the
	//     detector's isPriorFireLive trial-lease check acquired freely), and
	//     LastFireStartedAt is older than the stale window. The callback
	//     settles the terminal: marks the session snapshot cancelled
	//     (Interrupt-recoverable) and RecordFire-ing a StopError fire ("fire
	//     lost: process crashed during run").
	//
	// The detector must NOT flag a genuinely-live fire (lease held → skip), and
	// must NOT flag a freshly-claimed fire within the stale window (a fire
	// Claimed moments ago is in flight, not crashed). The callback is
	// idempotent: a fire already terminal is a no-op (RecordFire is idempotent
	// per fire id). Composition wires it over svc.GetSession/svc.Persist/
	// store.RecordFire (reusing settleFireTerminalSnapshot from #388 for the
	// session-settle).
	ReconcileStaleFire func(ctx context.Context, sched port.Schedule)
}

type FireFunc func(ctx context.Context, sched port.Schedule, now time.Time) (port.ScheduleFire, error)

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