@runbooks/supervise 0.1.0

package/dist/budgets.test.js

@@ -0,0 +1,148 @@
+import { describe, it, expect } from "vitest";
+import { loadCorpus } from "@runbooks/fixtures";
+import { derivePolicy } from "./policy.js";
+import { startRun, advance, propose, outOfTime } from "./run.js";
+import { report } from "./report.js";
+const flaky = () => {
+    const record = loadCorpus().find((r) => r.name.startsWith("flaky-check"));
+    return derivePolicy(record.doc);
+};
+function begin(envelope = flaky(), options = {}) {
+    const started = startRun(envelope, { agentIdentity: "agent-7", ...options });
+    if (!started.ok)
+        throw new Error(JSON.stringify(started.refusals));
+    return started.state;
+}
+/**
+ * Invariant 6 exists because an unbounded loop in an autonomous agent costs money and
+ * causes incidents. The linter guarantees the graph has no illegal cycle; this
+ * guarantees the legal one terminates.
+ */
+describe("a loop that would run forever stops", () => {
+    const envelope = flaky();
+    const loop = Object.keys(envelope.budgets)[0];
+    const max = envelope.budgets[loop];
+    const [from, to] = loop.split("->");
+    it("has a fixture whose cycle really is a cycle", () => {
+        expect(max).toBeGreaterThan(0);
+        expect(envelope.steps[to].transitions).toContain(from);
+        expect(envelope.steps[from].transitions).toContain(to);
+    });
+    /**
+     * Take the cycle as an agent would: back and forth, forever, if nothing stopped it.
+     * Bounded here so a wrong turn fails the test instead of hanging it.
+     */
+    function spin() {
+        let state = begin(envelope);
+        let last;
+        let laps = 0;
+        for (let i = 0; i < (max + 5) * 2 && state.status === "running"; i++) {
+            last = advance(envelope, state, state.current === to ? from : to);
+            if (state.current === from)
+                laps += 1;
+            state = last.state;
+        }
+        return { state, laps, ...(last ? { last } : {}) };
+    }
+    it("terminates instead of looping", () => {
+        expect(spin().state.status).toBe("ended");
+    });
+    it("stops at the limit the document declared, not one past it", () => {
+        expect(spin().laps).toBe(max + 1);
+    });
+    it("gives up with its own outcome rather than reporting a failed step", () => {
+        const { state } = spin();
+        expect(state.outcome).toBe("budget-exhausted");
+        expect(report(state).caveats.join(" ")).toMatch(/not a report of a step that failed/);
+    });
+    it("says which edge ran out and that the step decided nothing", () => {
+        const { last } = spin();
+        expect(last.events[0].message).toMatch(new RegExp(`${from}->${to}`));
+        expect(last.events[0].message).toMatch(/decided nothing/);
+    });
+});
+/** Two independent loops must not consume each other's budget. */
+describe("counters are per edge", () => {
+    const envelope = {
+        ...flaky(),
+        steps: {
+            a: { id: "a", kind: "wait", risk: "read-only", tools: [], undeclared: [], gated: false, title: "a", transitions: ["a", "b"] },
+            b: { id: "b", kind: "wait", risk: "read-only", tools: [], undeclared: [], gated: false, title: "b", transitions: ["b", "c"] },
+            c: { id: "c", kind: "check", risk: "read-only", tools: [], undeclared: [], gated: false, title: "c", transitions: [] },
+        },
+        entry: "a",
+        terminals: [],
+        budgets: { "a->a": 1, "b->b": 1 },
+    };
+    it("does not let one loop spend another's budget", () => {
+        let state = begin(envelope);
+        state = advance(envelope, state, "a").state; // a->a, 1 of 1
+        state = advance(envelope, state, "b").state;
+        const second = advance(envelope, state, "b"); // b->b, 1 of 1 — its own budget
+        expect(second.state.status).toBe("running");
+        expect(second.state.retries).toEqual({ "a->a": 1, "b->b": 1 });
+    });
+    it("stops the loop that actually exhausted, not the run's first loop", () => {
+        let state = begin(envelope);
+        state = advance(envelope, state, "b").state;
+        state = advance(envelope, state, "b").state;
+        const over = advance(envelope, state, "b");
+        expect(over.state.outcome).toBe("budget-exhausted");
+        expect(over.events[0].message).toMatch(/b->b/);
+    });
+    it("reports each edge's usage against its limit", () => {
+        let state = begin(envelope);
+        state = advance(envelope, state, "a").state;
+        const r = report(state, [], { envelope });
+        expect(r.budgets.retries).toContainEqual({ edge: "a->a", used: 1, max: 1 });
+    });
+});
+/**
+ * A procedure can be slow without looping, so time is counted separately. The budget is
+ * the operator's: the document's `duration` is a bucket written to set a reader's
+ * expectation, and enforcing it would turn a hint into a kill switch.
+ */
+describe("the wall clock is the operator's budget, not the document's", () => {
+    it("suggests a limit from the duration bucket without enforcing one", () => {
+        const record = loadCorpus().find((r) => r.name.startsWith("disk-pressure"));
+        const envelope = derivePolicy(record.doc);
+        expect(envelope.suggestedWallClockSeconds).toBe(300);
+        expect(begin(envelope, { inputs: { mount: "/tmp" } }).wallClockSeconds).toBeUndefined();
+    });
+    it("does not bound a run for which no budget was set", () => {
+        const state = begin(flaky(), { now: 0 });
+        expect(outOfTime(state, 10_000_000)).toBe(false);
+    });
+    it("says in the report that nothing was bounding the run in time", () => {
+        expect(report(begin()).caveats.join(" ")).toMatch(/An absent limit is not a generous one/);
+    });
+    it("ends the run once the budget passes, with its own outcome", () => {
+        const state = begin(flaky(), { now: 100, wallClockSeconds: 60 });
+        const late = advance(flaky(), state, state.current === "s1" ? "s2" : "s1", 200);
+        expect(late.state.status).toBe("ended");
+        expect(late.state.outcome).toBe("timed-out");
+    });
+    it("blocks a proposed call after the budget rather than authorizing it", () => {
+        const state = begin(flaky(), { now: 100, wallClockSeconds: 60 });
+        const decided = propose(flaky(), state, { tool: "cli:kubectl", now: 200 });
+        expect(decided.authorization.verdict).toBe("block");
+        expect(decided.state.outcome).toBe("timed-out");
+    });
+    it("keeps authorizing while the run is inside its budget", () => {
+        const envelope = flaky();
+        const declared = envelope.steps[envelope.entry].tools[0];
+        const state = begin(envelope, { now: 100, wallClockSeconds: 600 });
+        expect(propose(envelope, state, { tool: declared, now: 200 }).state.outcome).toBeUndefined();
+    });
+    it("reports elapsed against the limit", () => {
+        const state = begin(flaky(), { now: 100, wallClockSeconds: 600 });
+        expect(report(state, [], { now: 250 }).budgets.wallClock)
+            .toEqual({ limitSeconds: 600, elapsedSeconds: 150, exhausted: false });
+    });
+    /** The core has no clock: the same state and the same `now` decide the same way. */
+    it("reads no clock of its own", () => {
+        const state = begin(flaky(), { now: 0, wallClockSeconds: 1 });
+        expect(outOfTime(state, undefined)).toBe(false);
+        expect(outOfTime(state, 2)).toBe(true);
+    });
+});

package/dist/contract.d.ts

@@ -0,0 +1,38 @@
+import type { Risk, RuntimeProfile } from "@runbooks/schema";
+import type { AdapterCoverage } from "./index.js";
+export declare const RUNTIME_ORDER: readonly RuntimeProfile[];
+export declare function atLeast(actual: RuntimeProfile, required: RuntimeProfile): boolean;
+export type Execution = "human-only" | "human-with-agent" | "agent-autonomous";
+export interface Deployment {
+    /** What the client claims to enforce. */
+    readonly profile: RuntimeProfile;
+    /** What its adapter can actually observe. A claim above coverage is not a profile. */
+    readonly coverage: AdapterCoverage;
+    /** Highest risk the operator has permitted for this run. */
+    readonly riskCeiling?: Risk;
+}
+export interface Procedure {
+    readonly maxRisk: Risk;
+    readonly execution: Execution;
+    readonly minRuntimeProfile?: RuntimeProfile;
+}
+export type RefusalCode = "runtime/profile-too-low" | "runtime/coverage-insufficient" | "runtime/risk-above-ceiling" | "runtime/autonomous-unsupervised";
+export interface Refusal {
+    readonly code: RefusalCode;
+    readonly message: string;
+}
+/**
+ * Whether a deployment may start a procedure at all.
+ *
+ * Refusing before the first step rather than failing halfway is itself normative
+ * (§13.4): a run that stops in the middle has already done some of the work, and "some
+ * of a destructive procedure" is the worst available outcome.
+ */
+export declare function refusalsToStart(p: Procedure, d: Deployment): Refusal[];
+export declare function mayStart(p: Procedure, d: Deployment): boolean;
+/**
+ * The lowest runtime profile that can honestly run a procedure, given nothing but the
+ * procedure itself. Used to fill `min_runtime_profile` when an author leaves it out,
+ * and to warn when an author declares one lower than the content justifies.
+ */
+export declare function impliedMinimum(p: Pick<Procedure, "maxRisk" | "execution">): RuntimeProfile;

package/dist/contract.js

@@ -0,0 +1,77 @@
+/**
+ * The execution contract: runtime profiles and what each one binds a client to.
+ *
+ * P0/P1/P2 describe how much structure a *document* has. R0/R1/R2 describe how much of
+ * the contract a *client* actually enforces. They are independent axes, and the catalog
+ * should be able to say so: a perfect P2 document read by an R0 client is unsupervised.
+ */
+import { isDangerous } from "@runbooks/schema";
+import { mayRunUnder } from "./index.js";
+export const RUNTIME_ORDER = ["R0", "R1", "R2"];
+export function atLeast(actual, required) {
+    return RUNTIME_ORDER.indexOf(actual) >= RUNTIME_ORDER.indexOf(required);
+}
+/**
+ * Whether a deployment may start a procedure at all.
+ *
+ * Refusing before the first step rather than failing halfway is itself normative
+ * (§13.4): a run that stops in the middle has already done some of the work, and "some
+ * of a destructive procedure" is the worst available outcome.
+ */
+export function refusalsToStart(p, d) {
+    const out = [];
+    if (p.minRuntimeProfile && !atLeast(d.profile, p.minRuntimeProfile)) {
+        out.push({
+            code: "runtime/profile-too-low",
+            message: `This runbook requires ${p.minRuntimeProfile}; this client enforces ${d.profile}. Run it under a client that enforces ${p.minRuntimeProfile}, or run it by hand.`,
+        });
+    }
+    // §13.3, stated once. This condition was written out here as well as in `mayRunUnder`,
+    // in the same two terms — identical, and two places to tighten when the rule moves.
+    if (!mayRunUnder(p.maxRisk, d.coverage)) {
+        out.push({
+            code: "runtime/coverage-insufficient",
+            message: `This runbook contains ${p.maxRisk} steps, and this adapter cannot observe every tool invocation. An adapter that cannot see a call cannot bound it. Use a tool-call hook rather than a proxy.`,
+        });
+    }
+    if (d.riskCeiling && !riskAtMostLocal(p.maxRisk, d.riskCeiling)) {
+        out.push({
+            code: "runtime/risk-above-ceiling",
+            message: `This runbook contains ${p.maxRisk} steps and the configured ceiling is ${d.riskCeiling}. Raise the ceiling deliberately, or pick a different procedure.`,
+        });
+    }
+    // An autonomous agent under an advisory client has nothing between it and the tools
+    // but its own judgement — which is the arrangement this specification exists to
+    // replace, so it is an error rather than a warning.
+    if (p.execution === "agent-autonomous" && d.profile === "R0") {
+        out.push({
+            code: "runtime/autonomous-unsupervised",
+            message: `This runbook declares agent-autonomous execution and this client enforces nothing (R0). Autonomous execution needs at least R1: an allowlist, per-step scope and approval gates.`,
+        });
+    }
+    return out;
+}
+export function mayStart(p, d) {
+    return refusalsToStart(p, d).length === 0;
+}
+const RISK_RANK = {
+    "read-only": 0,
+    "reversible-write": 1,
+    destructive: 2,
+    irreversible: 3,
+};
+function riskAtMostLocal(actual, ceiling) {
+    return RISK_RANK[actual] <= RISK_RANK[ceiling];
+}
+/**
+ * The lowest runtime profile that can honestly run a procedure, given nothing but the
+ * procedure itself. Used to fill `min_runtime_profile` when an author leaves it out,
+ * and to warn when an author declares one lower than the content justifies.
+ */
+export function impliedMinimum(p) {
+    if (isDangerous(p.maxRisk))
+        return "R2";
+    if (p.execution === "agent-autonomous")
+        return "R1";
+    return "R0";
+}

package/dist/contract.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/contract.test.js

@@ -0,0 +1,131 @@
+import { describe, it, expect } from "vitest";
+import { refusalsToStart, mayStart, impliedMinimum, atLeast } from "./contract.js";
+import { mayRunUnder } from "./index.js";
+const proxy = { mcpCalls: true, shell: false, fileEdits: false };
+const hook = { mcpCalls: true, shell: true, fileEdits: true };
+const deployment = (over = {}) => ({
+    profile: "R1",
+    coverage: hook,
+    ...over,
+});
+const procedure = (over = {}) => ({
+    maxRisk: "reversible-write",
+    execution: "human-with-agent",
+    ...over,
+});
+const codes = (p, d) => refusalsToStart(p, d).map((r) => r.code);
+/**
+ * S-14 acceptance: each MUST is phrased so a conformance test could be written for it.
+ * These are those tests — if a rule here cannot be expressed as an assertion, the rule
+ * is wrong rather than the test.
+ */
+describe("a client MUST refuse a document whose minimum exceeds what it enforces", () => {
+    it("refuses R2 work on an R1 client", () => {
+        expect(codes(procedure({ minRuntimeProfile: "R2" }), deployment({ profile: "R1" })))
+            .toContain("runtime/profile-too-low");
+    });
+    it("allows a client that enforces more than the minimum", () => {
+        expect(mayStart(procedure({ minRuntimeProfile: "R1" }), deployment({ profile: "R2" })))
+            .toBe(true);
+    });
+    it("orders the profiles least to most enforcing", () => {
+        expect(atLeast("R2", "R1")).toBe(true);
+        expect(atLeast("R0", "R1")).toBe(false);
+    });
+});
+describe("a profile is bounded by coverage, not by the client's claim (13.3)", () => {
+    // The rule someone will want to bypass under time pressure.
+    it("refuses destructive work under a proxy that cannot see shell access", () => {
+        expect(codes(procedure({ maxRisk: "destructive" }), deployment({ coverage: proxy })))
+            .toContain("runtime/coverage-insufficient");
+    });
+    it("still refuses when the client claims R2", () => {
+        expect(codes(procedure({ maxRisk: "irreversible" }), deployment({ profile: "R2", coverage: proxy }))).toContain("runtime/coverage-insufficient");
+    });
+    it("permits reversible work under a proxy", () => {
+        expect(mayStart(procedure({ maxRisk: "reversible-write" }), deployment({ coverage: proxy })))
+            .toBe(true);
+    });
+    it("permits destructive work under an adapter that sees everything", () => {
+        expect(mayStart(procedure({ maxRisk: "destructive" }), deployment({ coverage: hook })))
+            .toBe(true);
+    });
+});
+describe("refusal happens before the first step, not halfway", () => {
+    // "Some of a destructive procedure" is the worst available outcome, so every reason
+    // to refuse is collected up front rather than discovered in sequence.
+    it("reports every reason at once", () => {
+        const found = codes(procedure({ maxRisk: "irreversible", execution: "agent-autonomous", minRuntimeProfile: "R2" }), deployment({ profile: "R0", coverage: proxy, riskCeiling: "read-only" }));
+        expect(found).toEqual(expect.arrayContaining([
+            "runtime/profile-too-low",
+            "runtime/coverage-insufficient",
+            "runtime/risk-above-ceiling",
+            "runtime/autonomous-unsupervised",
+        ]));
+    });
+});
+describe("autonomous execution needs supervision", () => {
+    it("refuses an autonomous runbook on an advisory client", () => {
+        expect(codes(procedure({ execution: "agent-autonomous" }), deployment({ profile: "R0" })))
+            .toContain("runtime/autonomous-unsupervised");
+    });
+    it("leaves human-only procedures alone at R0", () => {
+        expect(mayStart(procedure({ execution: "human-only" }), deployment({ profile: "R0" })))
+            .toBe(true);
+    });
+});
+describe("the risk ceiling is the operator's, and it is honoured", () => {
+    it("refuses work above the configured ceiling", () => {
+        expect(codes(procedure({ maxRisk: "destructive" }), deployment({ riskCeiling: "reversible-write" })))
+            .toContain("runtime/risk-above-ceiling");
+    });
+});
+describe("implied minimum profile", () => {
+    it("puts destructive work at R2", () => {
+        expect(impliedMinimum({ maxRisk: "destructive", execution: "human-with-agent" })).toBe("R2");
+    });
+    it("puts autonomous execution at R1", () => {
+        expect(impliedMinimum({ maxRisk: "read-only", execution: "agent-autonomous" })).toBe("R1");
+    });
+    it("leaves a human read-only procedure at R0", () => {
+        expect(impliedMinimum({ maxRisk: "read-only", execution: "human-only" })).toBe("R0");
+    });
+});
+describe("refusals say what to do", () => {
+    it("names the fix rather than the failure", () => {
+        const [refusal] = refusalsToStart(procedure({ maxRisk: "destructive" }), deployment({ coverage: proxy }));
+        expect(refusal.message).toMatch(/tool-call hook/);
+        expect(refusal.message).not.toMatch(/something went wrong|invalid|error/i);
+    });
+});
+/**
+ * §13.3 said twice.
+ *
+ * `mayRunUnder` and the coverage refusal were written out separately, in the same two
+ * terms. Identical is not the problem — two places to change when the rule moves is, and
+ * the copy on the package's public surface was the one nothing exercised. This walks the
+ * whole matrix rather than the interesting corner, because a divergence would arrive in
+ * whichever cell somebody forgot.
+ */
+describe("the coverage rule has one statement", () => {
+    const risks = ["read-only", "reversible-write", "destructive", "irreversible"];
+    const coverages = [
+        { mcpCalls: false, shell: false, fileEdits: false },
+        { mcpCalls: true, shell: false, fileEdits: false },
+        { mcpCalls: true, shell: true, fileEdits: false },
+        { mcpCalls: false, shell: true, fileEdits: true },
+        { mcpCalls: true, shell: true, fileEdits: true },
+    ];
+    it("refuses on coverage exactly when the run may not proceed under the adapter", () => {
+        for (const maxRisk of risks) {
+            for (const coverage of coverages) {
+                const refused = codes(procedure({ maxRisk }), deployment({ coverage, profile: "R2" })).includes("runtime/coverage-insufficient");
+                expect(refused, `${maxRisk} under ${JSON.stringify(coverage)}`).toBe(!mayRunUnder(maxRisk, coverage));
+            }
+        }
+    });
+    it("covers both answers, so agreement is not agreement on one of them", () => {
+        const answers = risks.flatMap((maxRisk) => coverages.map((c) => mayRunUnder(maxRisk, c)));
+        expect(new Set(answers)).toEqual(new Set([true, false]));
+    });
+});

package/dist/deviations.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Deviations: recording and escalation (R-06).
+ *
+ * "Anything not in the graph is a deviation: blocked, recorded, and optionally
+ * escalated" (§13.2). Blocking is the safety half. This is the diagnostic half, and it
+ * is the more valuable one over time: **a procedure that constantly provokes deviations
+ * is a procedure whose graph does not match reality.** No other signal surfaces that,
+ * and it is the most useful thing a supervised run can tell a runbook's author.
+ *
+ * Which means the record has to aggregate, and a record that aggregates cannot contain
+ * free text. §14's rule applies to everything that might leave the operator's
+ * environment: a deviation carries its class, its step and the *class* of capability
+ * involved — never the command, never an argument, never the value that made it fail.
+ */
+import type { DeviationClass } from "./index.js";
+import type { RunEvent, RunState } from "./run.js";
+export interface DeviationRecord {
+    readonly class: DeviationClass;
+    /** Where in the graph, which is what an author needs to fix their step 4. */
+    readonly stepId?: string;
+    /**
+     * The capability class alone: `cli`, `mcp`, `http`. Not `cli:kubectl`, and above all
+     * not what it was pointed at. The tool name is already close to a payload — it names
+     * the system — and the aggregate question ("what kind of thing do agents keep
+     * reaching for here") is answered by the class.
+     */
+    readonly capabilityClass?: string;
+    /** Ordering without a clock, so the core stays pure and the sequence is reproducible. */
+    readonly sequence: number;
+}
+/** `cli:kubectl` -> `cli`. Anything unrecognisable contributes nothing rather than itself. */
+export declare function capabilityClassOf(capability: string | undefined): string | undefined;
+/** What the supervisor does about a class of deviation, beyond blocking the call. */
+export type DeviationResponse = "abort" | "block-and-continue";
+export type EscalationPolicy = {
+    readonly responses: Readonly<Record<DeviationClass, DeviationResponse>>;
+    /**
+     * How many deviations of any class a run may accumulate before it is stopped.
+     *
+     * An agent that keeps proposing things the document does not allow is not having one
+     * bad moment; either the graph does not match reality or the agent is off the
+     * procedure, and both are reasons to stop rather than to keep blocking calls forever.
+     */
+    readonly maxTotal: number;
+};
+/**
+ * The default, and it is conservative on purpose.
+ *
+ * Anything that breaks control flow aborts: if the run is not where the graph says it
+ * is, every later authorization is being decided against the wrong step, and continuing
+ * would mean enforcing a policy that no longer describes the run. A tool the runbook
+ * declares but this step does not is the one case that merely blocks — it is the classic
+ * agent-runs-ahead mistake, the call is refused, and the procedure is still on its
+ * rails.
+ */
+export declare const DEFAULT_ESCALATION: EscalationPolicy;
+export interface DeviationInput {
+    readonly class: DeviationClass;
+    readonly stepId?: string;
+    /** A capability URN. Only its class is kept. */
+    readonly capability?: string;
+}
+/**
+ * Record a deviation and apply the policy.
+ *
+ * One place, because there were seven: every path that blocked something appended to the
+ * same array in its own way, and a taxonomy maintained in seven places is one that
+ * disagrees with itself as soon as a class is added.
+ */
+export declare function recordDeviation(state: RunState, input: DeviationInput): {
+    state: RunState;
+    events: readonly RunEvent[];
+};
+/** How many, by class — the aggregate an author reads. */
+export declare function countByClass(deviations: readonly DeviationRecord[]): Readonly<Record<string, number>>;
+/** How many, by step — the aggregate that says which step does not match reality. */
+export declare function countByStep(deviations: readonly DeviationRecord[]): Readonly<Record<string, number>>;

package/dist/deviations.js

@@ -0,0 +1,81 @@
+/** `cli:kubectl` -> `cli`. Anything unrecognisable contributes nothing rather than itself. */
+export function capabilityClassOf(capability) {
+    if (!capability)
+        return undefined;
+    const head = capability.split(":", 1)[0];
+    return /^[a-z][a-z0-9-]*$/.test(head) ? head : undefined;
+}
+/**
+ * The default, and it is conservative on purpose.
+ *
+ * Anything that breaks control flow aborts: if the run is not where the graph says it
+ * is, every later authorization is being decided against the wrong step, and continuing
+ * would mean enforcing a policy that no longer describes the run. A tool the runbook
+ * declares but this step does not is the one case that merely blocks — it is the classic
+ * agent-runs-ahead mistake, the call is refused, and the procedure is still on its
+ * rails.
+ */
+export const DEFAULT_ESCALATION = {
+    responses: {
+        "undeclared-tool": "abort",
+        "out-of-scope-tool": "block-and-continue",
+        "out-of-order-step": "abort",
+        "unchecked-advance": "abort",
+        "budget-exhausted": "abort",
+        "unrouted-failure": "abort",
+        "terminal-not-reached": "abort",
+    },
+    maxTotal: 3,
+};
+/**
+ * Record a deviation and apply the policy.
+ *
+ * One place, because there were seven: every path that blocked something appended to the
+ * same array in its own way, and a taxonomy maintained in seven places is one that
+ * disagrees with itself as soon as a class is added.
+ */
+export function recordDeviation(state, input) {
+    const stepId = input.stepId ?? state.current;
+    const record = {
+        class: input.class,
+        ...(stepId ? { stepId } : {}),
+        ...(capabilityClassOf(input.capability) ? { capabilityClass: capabilityClassOf(input.capability) } : {}),
+        sequence: state.deviations.length,
+    };
+    const deviations = [...state.deviations, record];
+    const policy = state.escalation;
+    const response = policy.responses[input.class];
+    const overRun = deviations.length > policy.maxTotal;
+    if (state.status === "ended" || (response !== "abort" && !overRun)) {
+        return { state: { ...state, deviations }, events: [] };
+    }
+    return {
+        state: { ...state, deviations, status: "ended", outcome: state.outcome ?? "aborted" },
+        events: [
+            {
+                kind: "escalated",
+                code: overRun ? "run/deviation-limit" : `run/escalated-${input.class}`,
+                message: overRun
+                    ? `${deviations.length} deviations in one run, past the limit of ${policy.maxTotal}. Stopping: either the graph does not match reality or the run has left the procedure, and both are reasons to stop rather than to keep refusing calls.`
+                    : `${input.class} at ${stepId ?? "an unknown step"} stops the run. The run is not where the graph says it is, so every later decision would be made against the wrong step.`,
+                ...(stepId ? { at: stepId } : {}),
+            },
+        ],
+    };
+}
+/** How many, by class — the aggregate an author reads. */
+export function countByClass(deviations) {
+    const counts = {};
+    for (const d of deviations)
+        counts[d.class] = (counts[d.class] ?? 0) + 1;
+    return counts;
+}
+/** How many, by step — the aggregate that says which step does not match reality. */
+export function countByStep(deviations) {
+    const counts = {};
+    for (const d of deviations) {
+        if (d.stepId)
+            counts[d.stepId] = (counts[d.stepId] ?? 0) + 1;
+    }
+    return counts;
+}

package/dist/deviations.test.d.ts

@@ -0,0 +1 @@
+export {};