@runbooks/supervise 0.1.0

package/dist/report.js

@@ -0,0 +1,67 @@
+import { countByClass, countByStep } from "./deviations.js";
+import { isComplete } from "./run.js";
+import { plural } from "@runbooks/schema";
+export function report(state, events = [], options = {}) {
+    const passed = state.checks.filter((c) => c.outcome === "pass");
+    const failed = state.checks.filter((c) => c.outcome === "fail");
+    const unevaluable = state.checks.filter((c) => c.outcome === "unevaluable");
+    const adjudicated = state.checks.filter((c) => c.adjudicatedBy !== undefined);
+    const retries = Object.entries(state.retries).map(([edge, used]) => ({
+        edge,
+        used,
+        ...(options.envelope?.budgets[edge] !== undefined ? { max: options.envelope.budgets[edge] } : {}),
+    }));
+    const elapsed = options.now !== undefined && state.startedAt !== undefined
+        ? options.now - state.startedAt
+        : undefined;
+    const caveats = [
+        "The supervisor authorized calls and decided postconditions. It did not contain what a permitted call then did.",
+    ];
+    if (unevaluable.length > 0) {
+        caveats.push(`${plural(unevaluable.length, "postcondition")} could not be decided. Undecided is not passed: nothing here says those steps succeeded.`);
+    }
+    if (adjudicated.length > 0) {
+        caveats.push(`${plural(adjudicated.length, "check")} ${adjudicated.length === 1 ? "was" : "were"} decided by a person, not verified by the supervisor.`);
+    }
+    if (state.wallClockSeconds === undefined) {
+        caveats.push("No wall-clock budget was set for this run, so nothing bounded it in time. An absent limit is not a generous one; it is none.");
+    }
+    if (state.outcome === "budget-exhausted") {
+        caveats.push("The run gave up on a retry budget. The step it was retrying decided nothing — this is not a report of a step that failed.");
+    }
+    if (!isComplete(state)) {
+        caveats.push("The run did not reach a terminal, so this is an account of an unfinished procedure.");
+    }
+    if (state.deviations.length > 0) {
+        caveats.push(`The run deviated from the procedure ${plural(state.deviations.length, "time")}. A procedure that provokes deviations is one whose graph may not match reality.`);
+    }
+    return {
+        status: state.status,
+        ...(state.outcome ? { outcome: state.outcome } : {}),
+        complete: isComplete(state),
+        stepsVisited: state.visited,
+        checks: {
+            passed: passed.length,
+            failed: failed.length,
+            unevaluable: unevaluable.length,
+            adjudicated: adjudicated.length,
+        },
+        deviations: {
+            count: state.deviations.length,
+            byClass: countByClass(state.deviations),
+            byStep: countByStep(state.deviations),
+            records: state.deviations,
+        },
+        budgets: {
+            retries,
+            wallClock: {
+                ...(state.wallClockSeconds !== undefined ? { limitSeconds: state.wallClockSeconds } : {}),
+                ...(elapsed !== undefined ? { elapsedSeconds: elapsed } : {}),
+                exhausted: state.outcome === "timed-out",
+            },
+        },
+        ...(state.awaiting ? { awaiting: state.awaiting } : {}),
+        detail: state.checks,
+        caveats,
+    };
+}

package/dist/run.d.ts

@@ -0,0 +1,216 @@
+/**
+ * The run state machine.
+ *
+ * Pure: every function takes state and returns new state plus the events it decided.
+ * Nothing here performs I/O, holds a credential, or reaches a network — an adapter sits
+ * in the call path, this decides (RUNBOOK.md 13.1). The same envelope and the same
+ * sequence of proposals must produce identical decisions, or a supervised run is not
+ * reproducible and an attestation about one means nothing.
+ */
+import type { PolicyEnvelope } from "./policy.js";
+import type { Authorization } from "./policy.js";
+import type { Grant, GateRefusal } from "./approval.js";
+import type { DeviationRecord, EscalationPolicy } from "./deviations.js";
+import type { Evaluation, Observation } from "./expect.js";
+export type RunStatus = "running" | "awaiting-approval"
+/**
+ * The postcondition could not be decided, so the run is stopped until a person says
+ * what happened. Distinct from every other status on purpose: "I could not tell" is
+ * neither a pass nor a failure, and collapsing it into either is the failure mode Q12
+ * exists to prevent.
+ */
+ | "awaiting-adjudication" | "ended";
+export type RunOutcome = "success" | "failed"
+/** Stopped deliberately: a rollback, an operator, a refused gate. */
+ | "aborted"
+/**
+ * A retry budget ran out. Distinct from a failure on purpose: the step did not decide
+ * anything, the run gave up on it — and a chronically exhausting step is a fact about
+ * the runbook, which a generic "failed" would hide.
+ */
+ | "budget-exhausted"
+/** The run outlasted the wall-clock budget the operator set for it. */
+ | "timed-out";
+export interface RunEvent {
+    readonly kind: "started" | "entered" | "authorized" | "blocked" | "approval-requested" | "approved" | "deviation" | "escalated" | "budget-exhausted" | "ended" | "expectation-passed" | "expectation-failed" | "expectation-unevaluable" | "adjudicated";
+    /** Resolves to a spec anchor, so a blocked call can always be explained. */
+    readonly code: string;
+    readonly message: string;
+    readonly at?: string;
+}
+export interface RunState {
+    readonly status: RunStatus;
+    readonly current?: string;
+    readonly visited: readonly string[];
+    /**
+     * The decision authorizing the current entry into the current step, if one has been
+     * made. Discarded when the run leaves the step — including when a retry returns to
+     * it, which is the realistic way one approval would otherwise cover many attempts.
+     */
+    readonly grant?: Grant;
+    /**
+     * Why the run stopped, when it stopped because somebody said no.
+     *
+     * Present only on a refused gate. Its absence on an `aborted` run is what distinguishes
+     * an expiry — a question nobody answered — from a considered refusal, which is a
+     * different fact about the same outcome.
+     */
+    readonly refusal?: GateRefusal;
+    /** Who is running this. A decision from this identity is not an approval. */
+    readonly agentIdentity: string;
+    /** Traversals per retry edge, keyed `from->to`. */
+    readonly retries: Readonly<Record<string, number>>;
+    /** Structured, aggregatable, and carrying no payload (§14). */
+    readonly deviations: readonly DeviationRecord[];
+    /** What the operator wants done about each class. Conservative unless they said otherwise. */
+    readonly escalation: EscalationPolicy;
+    readonly outcome?: RunOutcome;
+    readonly inputs: Readonly<Record<string, unknown>>;
+    /**
+     * Whether this run evaluates postconditions at all. R0 and R1 never do, so they never
+     * need one; R2 does, and the requirement attaches to the profile rather than to the
+     * document (Q12).
+     */
+    readonly mustCheck: boolean;
+    /** When the run started, in seconds. Supplied by the adapter: the core has no clock. */
+    readonly startedAt?: number;
+    /**
+     * How long this run may take in total, if the operator set a limit.
+     *
+     * Deliberately not derived from the document. `duration` there is a coarse bucket
+     * written to set a reader's expectation (`<5m`, `5-30m`, `>30m`), and turning a
+     * reader's hint into a kill switch would stop runs for a reason nobody wrote down.
+     * A budget is the operator's decision; the envelope only suggests one.
+     */
+    readonly wallClockSeconds?: number;
+    /** The step whose postcondition has been decided for the current entry into it. */
+    readonly decided?: string;
+    /** The postcondition waiting on a person, while one is. */
+    readonly awaiting?: {
+        readonly stepId: string;
+        readonly why: string;
+    };
+    /** Every postcondition decided so far, in order. The run report is built from this. */
+    readonly checks: readonly CheckRecord[];
+}
+export interface CheckRecord {
+    readonly stepId: string;
+    readonly outcome: "pass" | "fail" | "unevaluable";
+    readonly why: string;
+    /** Present when a person decided what the supervisor could not. */
+    readonly adjudicatedBy?: string;
+}
+export interface StartRefusal {
+    readonly code: string;
+    readonly message: string;
+}
+export type StartResult = {
+    readonly ok: true;
+    readonly state: RunState;
+    readonly events: readonly RunEvent[];
+} | {
+    readonly ok: false;
+    readonly refusals: readonly StartRefusal[];
+};
+/**
+ * Bind and validate inputs, then enter the graph.
+ *
+ * Binding happens before the first node rather than at first use. A missing required
+ * input aborts: interpolating an empty string does not make a command narrower, it makes
+ * it a different command, and `--group ""` against a production cluster is not a
+ * degraded version of `--group checkout`.
+ */
+export interface StartOptions {
+    readonly inputs?: Readonly<Record<string, unknown>>;
+    /** Defaults to a placeholder; an adapter supplies the real one so that a decision
+     *  from the agent can be recognised and refused (§13.4). */
+    readonly agentIdentity?: string;
+    /** Set by an adapter running R2. Off, a run behaves as R1 did. */
+    readonly evaluatePostconditions?: boolean;
+    /** The clock, supplied rather than read: the core stays pure and reproducible. */
+    readonly now?: number;
+    /** The operator's escalation policy. Omitted means the conservative default. */
+    readonly escalation?: EscalationPolicy;
+    /** A whole-run limit, in seconds. Absent means there is none, and the report says so. */
+    readonly wallClockSeconds?: number;
+}
+export declare function startRun(envelope: PolicyEnvelope, options?: StartOptions | Readonly<Record<string, unknown>>): StartResult;
+export interface Proposal {
+    readonly tool: string;
+    /** The clock, when the adapter has one. Absent means the wall clock is not checked. */
+    readonly now?: number;
+}
+/**
+ * Has the run outlasted its wall-clock budget?
+ *
+ * A procedure can be slow without looping, so this is counted separately from retries.
+ * With no budget set, or no clock supplied, the answer is no — an absent limit is not a
+ * zero one, and the report says plainly that nothing was bounding the run in time.
+ */
+export declare function outOfTime(state: RunState, now: number | undefined): boolean;
+export interface Decided {
+    readonly state: RunState;
+    readonly authorization: Authorization;
+    readonly events: readonly RunEvent[];
+}
+/** Authorize a proposed invocation against the current step. */
+export declare function propose(envelope: PolicyEnvelope, state: RunState, proposal: Proposal): Decided;
+/**
+ * Attach a decision to the run.
+ *
+ * The grant is produced by `grant()` in ./approval.js, which is where self-approval is
+ * refused — the core never mints one itself, so there is no path by which a run
+ * approves itself.
+ */
+export declare function applyGrant(state: RunState, granted: Grant): Decided;
+export interface Advanced {
+    readonly state: RunState;
+    readonly events: readonly RunEvent[];
+}
+/** Move to the next step, counting retry budgets and detecting terminals. */
+export declare function advance(envelope: PolicyEnvelope, state: RunState, to: string, now?: number): Advanced;
+/** A run that stopped anywhere but a terminal is incomplete, and says so (13.4). */
+export declare function isComplete(state: RunState): boolean;
+/** The result of deciding a step's postcondition. */
+export interface Observed {
+    readonly state: RunState;
+    readonly events: readonly RunEvent[];
+    readonly evaluation: Evaluation;
+}
+/**
+ * Decide whether the current step did what the procedure said it would, and route.
+ *
+ * This is the behaviour that separates R2 from R1. The route on failure is the
+ * document's `on_fail`, taken by the supervisor: at no point does the agent's own
+ * account of what happened choose the next node. Where the postcondition cannot be
+ * decided the run stops and waits for a person — it does not proceed, and it does not
+ * fail.
+ */
+export declare function observe(envelope: PolicyEnvelope, state: RunState, observation: Observation, now?: number): Observed;
+export declare class SelfAdjudicationError extends Error {
+    constructor(identity: string);
+}
+export interface Adjudication {
+    readonly verdict: "pass" | "fail";
+    readonly decidedBy: string;
+    readonly note?: string;
+}
+/**
+ * A person decides what the supervisor could not, and the run resumes on that decision.
+ *
+ * The decision is recorded as theirs. A run report that showed an adjudicated check as
+ * simply "passed" would be claiming the supervisor verified something it did not.
+ */
+export declare function adjudicate(envelope: PolicyEnvelope, state: RunState, decision: Adjudication): {
+    state: RunState;
+    events: readonly RunEvent[];
+};
+/**
+ * Close out a run that stopped somewhere other than a terminal.
+ *
+ * §13.4: an incomplete run says so. An adapter that loses its client, or an operator who
+ * walks away, leaves a run whose outcome is genuinely unknown — and "unknown" recorded
+ * as success is the one reading that would be a lie. Reaching an escalate node is not
+ * this case: an escalation the runbook anticipated is where the procedure meant to end.
+ */
+export declare function conclude(envelope: PolicyEnvelope, state: RunState): Advanced;