oka_supervisor library
Declarative supervisor (ADR-0040): steady-state convergence over the
resource_composition substrate.
Declare desired state as typed specs, run Supervisor.converge to observe → diff → act once, and read the JSONL facts. The substrate keeps every contract (validation, readiness, events, evidence); this package adds only the policy layer: budgeted restarts, cession-based ownership, and the advisory machine registry.
Classes
- AppSupervisorSession
- Retain one instance per app/project scope. Loading plans never enables it. Calls during an active pass join that pass; a later tick reads fresh plans.
- CodemapCorruptReceipt
- Receipt evidence that names a lane but fails receipt validation.
- CodemapIndexHealth
- Structured health is independent of process liveness. Unknown evidence never promotes a process to dead or grants restart/signal authority.
- CodemapIndexProvider
- CodemapIndexRecipe
- Explicit declaration; scope remains Codemap-owned JSON, never reconstructed from a different watcher filter in Oka.
- CodemapLane
- One declared lane, read (never executed) from a codemap snapshot.
- CodemapLaneFinding
- One lane's projection: the declared shape plus the newest receipt observation, judged against the lane's cadence.
- CodemapLaneSnapshot
-
A parsed lanes snapshot: codemap's data form (
{"lanes": [...]}) or the runner's--listaudit document (which adds adeclarationpath — tolerated here). - CodemapProjection
- The whole read-only projection: one finding per declared lane plus the receipts summary.
- CodemapReceipt
- One observed lane receipt. Codemap emits these as stdout JSON lines carrying no wall clock, so receivedAt is when the carrying file was last modified.
- CodemapReceiptScan
-
Everything a receipts scan observed. Pure evidence: scanned counts
receipt-shaped inputs examined (valid plus corrupt; the runner's
ready/run_start/exitcontrol events are neither). - ComponentSpec
- One declared component of the desired state.
- ComponentStatus
- One component's converged-so-far status.
- ConvergenceReport
- What one converge pass did.
- DesiredState
- The whole desired state: specs plus the defaults the substrate needs.
- IntervalTrigger
-
Run at most once per period (the recorded nightly-lane shape: an
interval, not a cron parser — an ADR-0040 non-goal). The optional
at anchor ("HH:mm", local wall clock) keeps human schedules
honest — "daily at 03:00" stays at 03:00 across restarts and
catch-up runs: the next run is the first anchor occurrence at or
after
last + period(nextRunAfter). - MachineRegistry
- Advisory, machine-wide record store. Two repos cannot collide: the scope is a short hash of the canonical project root.
- NoTrigger
- Nothing scheduled; services converge to running, jobs run once per revision.
- RegistrySnapshot
- One scope's records plus any files that could not be parsed — corrupt records are surfaced as findings, never silently dropped (the ADR-0018 advisory-lease posture).
- SpecCodec
- Decodes and encodes plan documents.
- SpecStore
- A directory of named plan documents.
- SupervisionPolicy
- Steady-state policy: the budgeted restart ledger a spec declares (ADR-0040 decision 3). The one-shot runner never restarts anything; only the supervisor does, only within this budget, only for records it owns.
- Supervisor
- Steady-state supervisor bound to one project scope.
- SupervisorAction
- SupervisorFinding
- A steady-state observation that is not an action. Evidence only.
- SupervisorPlan
- The diff: actions to apply (in dependency order) and findings to emit.
- SupervisorProcessProvider
-
Routes the substrate's provider seam to one
LeasedProcessProviderper declared component: a ProviderFactory sees only the provider name, while start/stop/inspect calls always carry the component identity, so per-component commands stay constructor-injected. - SupervisorRecord
- The durable record of one supervised component.
- Trigger
-
When a component should run. A property of any spec, never a kind.
Rung-1 enforcement: intervals gate job re-runs in
converge; watch triggers are declared and recorded, enforced by the resident rung — rung 1 adds no second file watcher (ADR-0040 decision 4). - WatchTrigger
- Run when files under roots change (declarative; the resident rung or an existing watcher enforces).
Enums
- KillPolicy
- Who may stop (and therefore restart) a recorded component.
- SupervisionShape
- What "desired" means for a component between converges.
- SupervisorActionKind
- What the driver should do to one component.
Functions
-
planConvergence(
{required DesiredState desired, required RegistrySnapshot snapshot, required Map< String, Observation> observations, required DateTime now}) → SupervisorPlan - Computes the convergence plan.
-
projectCodemapLaneFindings(
{required CodemapLaneSnapshot snapshot, required CodemapReceiptScan scan, required DateTime now}) → List< CodemapLaneFinding> - Pure projection: declared lanes + observed receipts → findings. Highest-effort rule: per lane, the newest valid receipt wins; a corrupt receipt only becomes the lane's finding when no valid receipt exists for it.
-
projectCodemapLanes(
{required CodemapLaneSnapshot snapshot, String? receiptsPath, DateTime clock()?}) → CodemapProjection -
Scans receipts when
receiptsPathis given, projects the lanes, and counts orphan receipts. Read-only;clockdefaults to DateTime.now so tests pin time. -
projectionJson(
CodemapProjection projection) → String -
One JSON document:
{lanes: [{id, trigger, lastReceiptAt?, ageS?, finding: {code, message}}], receipts: {scanned, corrupt, orphan}}— the wire shape for CLI--jsonand a future CI gate. -
projectStatus(
{required RegistrySnapshot snapshot, DesiredState? desired}) → List< ComponentStatus> - Projects one status line per component: desired specs in declaration order (record-backed or not), then record-only ids in id order.
-
renderProjection(
CodemapProjection projection) → String - Aligned plain-text rendering for terminals.
-
renderStatus(
List< ComponentStatus> statuses) → String - Aligned plain-text rendering for terminals.
-
scanCodemapReceipts(
String path) → CodemapReceiptScan -
Reads receipt evidence from
path: a directory (each direct child file is one capture; dotfiles are skipped) or a single file. Each capture may be a pretty-printed JSON document (a saved--onceoutput) or a JSONL line stream (a redirected daemon log). Read-only. -
statusJson(
{required List< ComponentStatus> statuses, List<String> corruptPaths = const <String>[]}) → String -
One JSON document: statuses plus the snapshot's corrupt-record paths —
the wire shape for CLI
--json, embedding UIs, and (later) mesh supervisor-state frames (ADR-0041).
Typedefs
- ProviderFactory = ResourceProvider Function(String name)
- Creates providers by declared name. Pure at composition time: the returned provider must not be contacted until the converge driver acts.
Exceptions / Errors
- SpecFormatException
- A structurally invalid plan document. Never a provider fault: nothing was contacted, nothing was started.