@runbooks/supervise 0.1.0

package/dist/policy.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The policy envelope: what a runbook authorizes at run time.
+ *
+ * Derived from the document, never authored separately (RUNBOOK.md 13.2). That is the
+ * load-bearing decision of this file: a policy that can drift from the procedure it
+ * governs is worse than no policy, because it is trusted while being wrong. An author
+ * who writes a valid P1 runbook has already written the policy.
+ *
+ * Derivation is a pure function. Two implementations must produce the same envelope for
+ * the same document, or the contract is not portable and "any client can enforce this"
+ * becomes "our client can enforce this".
+ */
+import type { Risk, RuntimeProfile } from "@runbooks/schema";
+import { type RunbookDocument } from "@runbooks/graph";
+import { type Execution } from "./contract.js";
+import type { DeviationClass } from "./index.js";
+import type { Assertion } from "./expect.js";
+export declare const ENVELOPE_SCHEMA: "runbook-policy-envelope/v1";
+export interface StepScope {
+    readonly id: string;
+    readonly kind: string;
+    readonly risk: Risk;
+    /**
+     * What this step alone may invoke. Not the union of the runbook: granting an agent
+     * every capability a procedure will eventually need is how a diagnostic session ends
+     * in a deletion.
+     */
+    readonly tools: readonly string[];
+    /** Arrival at this step passes an approval gate. */
+    readonly gated: boolean;
+    /** Steps this step may hand control to. */
+    readonly transitions: readonly string[];
+    /**
+     * Tools the step names that the manifest does not declare. Never granted - the
+     * envelope carries no more authority than the document - and reported so the linter
+     * can fail the record (P-06).
+     */
+    readonly undeclared: readonly string[];
+    /** The command template, for rendering an approval request. */
+    readonly command?: string;
+    readonly title: string;
+    readonly rollbackTo?: string;
+    /**
+     * The machine-checkable postcondition, if the step has one. Its absence is what makes
+     * a step unevaluable at R2 (Q12); the envelope carries the absence rather than
+     * inventing a predicate from the prose.
+     */
+    readonly assert?: Assertion;
+    /** Where a failed postcondition sends the run. Chosen by the document, not the agent. */
+    readonly onFail?: string;
+    /** Where a passed postcondition sends the run, when the graph leaves no choice. */
+    readonly onPass?: string;
+}
+export interface InputDeclaration {
+    readonly type: "string" | "number" | "boolean";
+    readonly required: boolean;
+    readonly default?: unknown;
+    /** Redacted wherever the run is shown to a human, an approval request above all. */
+    readonly secret: boolean;
+}
+export interface PolicyEnvelope {
+    readonly schema: typeof ENVELOPE_SCHEMA;
+    readonly allowlist: readonly string[];
+    /** Declared parameters. Bound and validated before the graph is entered, never
+     *  lazily at first use: interpolating an empty string is how a scoped operation
+     *  silently becomes an unscoped one. */
+    readonly inputs: Readonly<Record<string, InputDeclaration>>;
+    readonly maxRisk: Risk;
+    readonly minRuntimeProfile: RuntimeProfile;
+    readonly entry: string | undefined;
+    readonly terminals: readonly string[];
+    readonly steps: Readonly<Record<string, StepScope>>;
+    /** Retry limits, keyed `from->to`. Absent means the transition is not a loop. */
+    readonly budgets: Readonly<Record<string, number>>;
+    /**
+     * What the document's `duration` suggests a whole-run limit could be, in seconds.
+     *
+     * A suggestion and nothing more. `duration` is a coarse bucket an author wrote to set
+     * a reader's expectation, and enforcing it would turn a hint into a kill switch nobody
+     * agreed to. `>30m` has no upper bound at all, so it suggests nothing. Whether to set
+     * a budget, and what it should be, is the operator's decision.
+     */
+    readonly suggestedWallClockSeconds?: number;
+}
+interface Doc extends RunbookDocument {
+    runbook?: RunbookDocument["runbook"] & {
+        capabilities?: string[];
+        execution?: Execution;
+        min_runtime_profile?: RuntimeProfile;
+        duration?: string;
+        inputs?: Record<string, {
+            type?: string;
+            required?: boolean;
+            default?: unknown;
+            secret?: boolean;
+        }>;
+    };
+}
+export declare function derivePolicy(doc: Doc): PolicyEnvelope;
+/**
+ * What may be invoked right now.
+ *
+ * The gate is the whole point: a gated step's capabilities do not exist until a human
+ * has decided. So the destructive capability is in scope only while the destructive step
+ * is current *and* its gate has been passed - never before, and never after the step
+ * hands control on.
+ */
+export declare function scopeFor(envelope: PolicyEnvelope, stepId: string, approved?: ReadonlySet<string>): readonly string[];
+export interface AuthorizationRequest {
+    readonly stepId: string;
+    readonly tool: string;
+    readonly approved?: ReadonlySet<string>;
+}
+export interface Authorization {
+    readonly verdict: "permit" | "block" | "require-approval";
+    readonly reason: string;
+    readonly deviation?: DeviationClass;
+}
+export declare function authorize(envelope: PolicyEnvelope, req: AuthorizationRequest): Authorization;
+/** Steps whose risk forces an approval gate (RUNBOOK.md 12). */
+export declare function dangerousSteps(envelope: PolicyEnvelope): readonly StepScope[];
+export {};

package/dist/policy.js

@@ -0,0 +1,147 @@
+import { isDangerous, RISK_ORDER } from "@runbooks/schema";
+import { toGraph } from "@runbooks/graph";
+import { impliedMinimum } from "./contract.js";
+export const ENVELOPE_SCHEMA = "runbook-policy-envelope/v1";
+function highestRisk(risks) {
+    let worst = "read-only";
+    for (const r of risks) {
+        if (r && RISK_ORDER.indexOf(r) > RISK_ORDER.indexOf(worst))
+            worst = r;
+    }
+    return worst;
+}
+/**
+ * `document -> envelope`. Deterministic: keys are emitted in document order, and
+ * nothing sorts by anything else.
+ */
+/** The document's own failure route, resolved to a node id. */
+function onFailTarget(graph, id) {
+    return graph.edges.find((e) => e.from === id && e.kind === "on_fail")?.to;
+}
+/**
+ * The success route, but only where the graph leaves exactly one.
+ *
+ * A branching step has no single successor, and a supervisor that picked one would be
+ * making the author's decision for them. Where there is a choice, the run stays put and
+ * the choice is made where it belongs.
+ */
+function onPassTarget(graph, id) {
+    const forward = graph.edges.filter((e) => e.from === id && e.kind === "next");
+    return forward.length === 1 ? forward[0].to : undefined;
+}
+/** The upper edge of each duration bucket. `>30m` is open, so it suggests nothing. */
+const SUGGESTED_WALL_CLOCK = {
+    "<5m": 300,
+    "5-30m": 1800,
+};
+export function derivePolicy(doc) {
+    const rb = doc.runbook;
+    const allowlist = [...(rb?.capabilities ?? [])];
+    const declared = new Set(allowlist);
+    const graph = toGraph(doc);
+    const steps = rb?.steps ?? [];
+    const gatedIds = new Set(graph.edges.filter((e) => e.kind === "approval").map((e) => e.to));
+    const scopes = {};
+    for (const step of steps) {
+        const named = step.tool ? [step.tool] : [];
+        scopes[step.id] = {
+            id: step.id,
+            kind: step.kind,
+            risk: step.risk ?? "read-only",
+            tools: named.filter((t) => declared.has(t)),
+            undeclared: named.filter((t) => !declared.has(t)),
+            gated: gatedIds.has(step.id),
+            title: step.title,
+            ...(step.command ? { command: step.command } : {}),
+            ...(step.rollback_ref ? { rollbackTo: step.rollback_ref } : {}),
+            transitions: graph.edges
+                .filter((e) => e.from === step.id && e.kind !== "approval")
+                .map((e) => e.to),
+            ...(step.assert ? { assert: step.assert } : {}),
+            ...(onFailTarget(graph, step.id) ? { onFail: onFailTarget(graph, step.id) } : {}),
+            ...(onPassTarget(graph, step.id) ? { onPass: onPassTarget(graph, step.id) } : {}),
+        };
+    }
+    const budgets = {};
+    for (const e of graph.edges) {
+        if (e.kind === "retry" && typeof e.max === "number") {
+            budgets[`${e.from}->${e.to}`] = e.max;
+        }
+    }
+    const maxRisk = highestRisk(steps.map((s) => s.risk));
+    const inputs = {};
+    for (const [name, decl] of Object.entries(rb?.inputs ?? {})) {
+        inputs[name] = {
+            type: decl.type ?? "string",
+            required: decl.required === true,
+            secret: decl.secret === true,
+            ...(decl.default !== undefined ? { default: decl.default } : {}),
+        };
+    }
+    return {
+        schema: ENVELOPE_SCHEMA,
+        allowlist,
+        inputs,
+        maxRisk,
+        minRuntimeProfile: rb?.min_runtime_profile ??
+            impliedMinimum({ maxRisk, execution: rb?.execution ?? "human-only" }),
+        entry: steps[0]?.id,
+        terminals: graph.nodes.filter((n) => n.kind === "escalate" || n.kind === "end").map((n) => n.id),
+        steps: scopes,
+        budgets,
+        ...(SUGGESTED_WALL_CLOCK[rb?.duration ?? ""] !== undefined
+            ? { suggestedWallClockSeconds: SUGGESTED_WALL_CLOCK[rb?.duration ?? ""] }
+            : {}),
+    };
+}
+/**
+ * What may be invoked right now.
+ *
+ * The gate is the whole point: a gated step's capabilities do not exist until a human
+ * has decided. So the destructive capability is in scope only while the destructive step
+ * is current *and* its gate has been passed - never before, and never after the step
+ * hands control on.
+ */
+export function scopeFor(envelope, stepId, approved = new Set()) {
+    const scope = envelope.steps[stepId];
+    if (!scope)
+        return [];
+    if (scope.gated && !approved.has(stepId))
+        return [];
+    return scope.tools;
+}
+export function authorize(envelope, req) {
+    const scope = envelope.steps[req.stepId];
+    if (!scope) {
+        return {
+            verdict: "block",
+            reason: `Step ${req.stepId} is not part of this runbook.`,
+            deviation: "out-of-order-step",
+        };
+    }
+    if (!envelope.allowlist.includes(req.tool)) {
+        return {
+            verdict: "block",
+            reason: `${req.tool} is not declared in this runbook's capabilities. Nothing outside the allowlist may be invoked for the duration of the run.`,
+            deviation: "undeclared-tool",
+        };
+    }
+    if (!scope.tools.includes(req.tool)) {
+        return {
+            verdict: "block",
+            reason: `${req.tool} is declared by this runbook but not by step ${req.stepId}. Scope is the current step, not the union of the procedure.`,
+            deviation: "out-of-scope-tool",
+        };
+    }
+    if (scope.gated && !(req.approved?.has(req.stepId) ?? false)) {
+        return {
+            verdict: "require-approval",
+            reason: `Step ${req.stepId} is ${scope.risk} and needs a human decision before it runs.`,
+        };
+    }
+    return { verdict: "permit", reason: `Step ${req.stepId} declares ${req.tool}.` };
+}
+/** Steps whose risk forces an approval gate (RUNBOOK.md 12). */
+export function dangerousSteps(envelope) {
+    return Object.values(envelope.steps).filter((s) => isDangerous(s.risk));
+}

package/dist/policy.test.d.ts

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

package/dist/policy.test.js

@@ -0,0 +1,124 @@
+import { describe, it, expect } from "vitest";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { derivePolicy, scopeFor, authorize, dangerousSteps } from "./policy.js";
+/** Typed at the boundary so a fixture that drifts from the model is a compile error
+ *  rather than a test that passes against a shape the code will never see. */
+const runbook = (r) => ({ runbook: r });
+const CORPUS = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "schema", "fixtures", "p1-valid");
+const corpus = readdirSync(CORPUS).map((name) => ({
+    name,
+    doc: JSON.parse(readFileSync(join(CORPUS, name), "utf8")),
+}));
+describe("derivation is a pure function", () => {
+    it.each(corpus)("$name derives identically twice", ({ doc }) => {
+        expect(JSON.stringify(derivePolicy(doc))).toBe(JSON.stringify(derivePolicy(doc)));
+    });
+    it.each(corpus)("$name derivation does not mutate the document", ({ doc }) => {
+        const before = JSON.stringify(doc);
+        derivePolicy(doc);
+        expect(JSON.stringify(doc)).toBe(before);
+    });
+});
+/**
+ * S-15's central invariant, asserted over the derivation rather than over examples:
+ * an envelope may never grant a capability the document does not declare. Stated as a
+ * property because the failure it prevents - an envelope quietly wider than the runbook
+ * that authorized it - is invisible in any single example.
+ */
+describe("the envelope carries no more authority than the document", () => {
+    it.each(corpus)("$name grants nothing outside capabilities[]", ({ doc }) => {
+        const env = derivePolicy(doc);
+        const declared = new Set(env.allowlist);
+        for (const scope of Object.values(env.steps)) {
+            for (const tool of scope.tools)
+                expect(declared.has(tool)).toBe(true);
+        }
+    });
+    it("moves an undeclared tool out of scope rather than granting it", () => {
+        const env = derivePolicy(runbook({
+            capabilities: ["cli:kubectl"],
+            steps: [
+                { id: "s1", kind: "action", title: "Drop it", risk: "read-only", tool: "mcp:postgres" },
+            ],
+        }));
+        expect(env.steps.s1.tools).toEqual([]);
+        expect(env.steps.s1.undeclared).toEqual(["mcp:postgres"]);
+    });
+});
+/**
+ * The other half of S-15: there is no reachable state in which a destructive capability
+ * is in scope and the approval gate has not been passed.
+ */
+describe("a destructive capability is never in scope before its gate", () => {
+    const destructive = runbook({
+        capabilities: ["mcp:postgres"],
+        execution: "human-with-agent",
+        steps: [
+            {
+                id: "s1", kind: "action", title: "Drop the slot", risk: "destructive",
+                tool: "mcp:postgres", requires_approval: true, next: "end:success",
+            },
+        ],
+    });
+    it("holds for every step of every corpus record", () => {
+        for (const { doc } of corpus) {
+            const env = derivePolicy(doc);
+            for (const scope of dangerousSteps(env)) {
+                expect(scopeFor(env, scope.id, new Set()), `${scope.id} is ${scope.risk} and had capabilities in scope with no approval`).toEqual([]);
+            }
+        }
+    });
+    it("withholds the capability until approval and grants it after", () => {
+        const env = derivePolicy(destructive);
+        expect(scopeFor(env, "s1", new Set())).toEqual([]);
+        expect(scopeFor(env, "s1", new Set(["s1"]))).toEqual(["mcp:postgres"]);
+    });
+    it("asks for approval rather than blocking outright", () => {
+        const env = derivePolicy(destructive);
+        expect(authorize(env, { stepId: "s1", tool: "mcp:postgres" }).verdict)
+            .toBe("require-approval");
+    });
+});
+describe("scope is the current step, not the union of the runbook", () => {
+    const env = derivePolicy(runbook({
+        capabilities: ["cli:kubectl", "mcp:postgres"],
+        steps: [
+            { id: "s1", kind: "check", title: "Look", risk: "read-only", tool: "cli:kubectl", expect: "ok", on_fail: "s2", next: "s2" },
+            { id: "s2", kind: "action", title: "Write", risk: "reversible-write", tool: "mcp:postgres", next: "end:success" },
+        ],
+    }));
+    // The rule that does the most work: granting the union for the whole run is how a
+    // diagnostic session ends in a deletion.
+    it("blocks a capability the runbook declares but this step does not", () => {
+        const d = authorize(env, { stepId: "s1", tool: "mcp:postgres" });
+        expect(d.verdict).toBe("block");
+        expect(d.deviation).toBe("out-of-scope-tool");
+        expect(d.reason).toMatch(/not the union/);
+    });
+    it("permits the capability this step declares", () => {
+        expect(authorize(env, { stepId: "s1", tool: "cli:kubectl" }).verdict).toBe("permit");
+    });
+    it("distinguishes undeclared from out-of-scope", () => {
+        expect(authorize(env, { stepId: "s1", tool: "cli:rm" }).deviation).toBe("undeclared-tool");
+    });
+    it("blocks an invocation attributed to a step that is not in the runbook", () => {
+        expect(authorize(env, { stepId: "s99", tool: "cli:kubectl" }).deviation)
+            .toBe("out-of-order-step");
+    });
+});
+describe("budgets and terminals come from the graph", () => {
+    it("records a finite retry budget per edge", () => {
+        const env = derivePolicy(runbook({
+            capabilities: [],
+            steps: [
+                { id: "s1", kind: "wait", title: "Wait", duration: "30s", retry: { max: 3, target: "s1" }, next: "end:success" },
+            ],
+        }));
+        expect(env.budgets["s1->s1"]).toBe(3);
+    });
+    it.each(corpus)("$name has at least one terminal", ({ doc }) => {
+        expect(derivePolicy(doc).terminals.length).toBeGreaterThan(0);
+    });
+});

package/dist/purity.test.d.ts

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

package/dist/purity.test.js

@@ -0,0 +1,191 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { builtinModules } from "node:module";
+import { specifiers, moduleOf, reachesNetwork } from "@runbooks/fixtures";
+/**
+ * R-01: the supervisor core must acquire no filesystem or network dependency anywhere
+ * in its tree — "check the dependency tree, not just the source". That is what keeps
+ * the core auditable, and it is exactly the kind of rule that erodes through a
+ * transitive import nobody looked at, so it is enforced rather than trusted.
+ *
+ * The walk follows real imports from the entry point. Scanning every file in a package
+ * would be wrong in both directions: it flags a Node-only entry point nothing imports
+ * (`@runbooks/schema/node`), and it would miss a dependency reached through one.
+ */
+function repoRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 8; i++) {
+        if (existsSync(join(dir, "pnpm-workspace.yaml")))
+            return dir;
+        dir = resolve(dir, "..");
+    }
+    throw new Error("repo root not found");
+}
+const ROOT = repoRoot();
+/**
+ * The extractor lives in `@runbooks/fixtures`, because five test files each had a copy of
+ * this rule and every copy recognised `from "node:fs"` and nothing else. Probed by
+ * mutation — one import at the top of the supervisor's entry point, then this file — five
+ * of seven forms passed:
+ *
+ * | put in the core                                   | before |
+ * |---|---|
+ * | `import { readFileSync } from "fs"`               | passed |
+ * | `import "node:fs"`                                | passed |
+ * | `const fs = await import("node:fs")`              | passed |
+ * | `import { createRequire } from "node:module"`     | passed |
+ * | `import { Worker } from "node:worker_threads"`    | passed |
+ * | `import { readFileSync } from "node:fs/promises"` | caught |
+ * | `import { connect } from "node:http2"`            | caught, and by accident |
+ *
+ * The last one is the tell: `node:http2` was caught by the *other* rule below, whose
+ * pattern happened to lack a word boundary after `node:http`. A check that passes for the
+ * reason it was written to fail is the shape this repository keeps finding.
+ */
+/**
+ * The list comes from the runtime, not from here.
+ *
+ * The rule it enforces is also stronger than the one it replaces: the supervisor's tree
+ * imports **no Node builtin at all**, which is true of all 28 modules in it today. A
+ * hand-typed set of eight I/O modules is a list somebody has to remember to extend —
+ * `worker_threads` and `module` were not on it, and either one reaches the filesystem in
+ * two lines.
+ */
+const BUILTIN = new Set(builtinModules);
+function entry(spec) {
+    const ws = /^@runbooks\/([a-z-]+)(\/(.+))?$/.exec(spec);
+    if (!ws)
+        return undefined;
+    const sub = ws[3] ? `${ws[3]}.ts` : "index.ts";
+    const file = join(ROOT, "packages", ws[1], "src", sub);
+    return existsSync(file) ? file : undefined;
+}
+/** Every module reachable from `start`, with the Node builtins each one imports. */
+function reachable(start) {
+    const seen = new Map();
+    const queue = [start];
+    while (queue.length) {
+        const file = queue.pop();
+        if (seen.has(file) || !existsSync(file))
+            continue;
+        const source = readFileSync(file, "utf8");
+        const builtins = [];
+        for (const specifier of specifiers(source)) {
+            if (BUILTIN.has(moduleOf(specifier))) {
+                builtins.push(specifier);
+            }
+            else if (specifier.startsWith(".")) {
+                queue.push(resolve(dirname(file), specifier.replace(/\.js$/, ".ts")));
+            }
+            else {
+                const next = entry(specifier);
+                if (next)
+                    queue.push(next);
+            }
+        }
+        seen.set(file, builtins);
+    }
+    return seen;
+}
+describe("supervisor core purity (R-01)", () => {
+    const modules = reachable(join(ROOT, "packages", "supervise", "src", "index.ts"));
+    it("reaches more than its own entry point", () => {
+        // Guards the guard: a walk that resolves nothing would pass vacuously.
+        expect(modules.size).toBeGreaterThan(1);
+    });
+    it("imports no Node builtin anywhere in its tree", () => {
+        const offenders = [...modules]
+            .filter(([, builtins]) => builtins.length > 0)
+            .map(([file, builtins]) => `${file.slice(ROOT.length + 1)} imports ${builtins.join(", ")}`);
+        expect(offenders, "anything that fetches, reads or spawns belongs in apps/cli, not in the supervisor's tree").toEqual([]);
+    });
+    /**
+     * The extractor, checked against the forms it exists to see. Without this the walk above
+     * is a rule whose reach nobody states, which is how it came to see one form of five.
+     */
+    it.each([
+        ['import { readFileSync } from "fs";', "fs"],
+        ["import { readFileSync } from 'node:fs';", "node:fs"],
+        ['import "node:fs";', "node:fs"],
+        ['const fs = await import("node:fs");', "node:fs"],
+        ['const fs = require("node:fs");', "node:fs"],
+        ['import { readFileSync } from "node:fs/promises";', "node:fs/promises"],
+        ['export { x } from "node:fs";', "node:fs"],
+    ])("sees %s", (line, expected) => {
+        expect(specifiers(line)).toContain(expected);
+    });
+});
+/**
+ * R-10 acceptance: every network call in the runtime chain is in the resolver, and
+ * nowhere else. Checked across the repository rather than by inspection, because the
+ * rule is only worth stating if something notices when it stops being true.
+ */
+describe("network access is confined to the resolver", () => {
+    /**
+     * `dgram` and `http2` count now. Neither did: `http2` was caught only because the
+     * pattern this replaces had no word boundary after `node:http`, and `dgram` was on the
+     * *other* rule's list and not on this one. Two hand-written lists of one rule
+     * disagreeing with each other is why the list is not written here any more.
+     */
+    /**
+     * Two files, each named, each with a reason. Not a directory and not a pattern: an
+     * allowlist that admits a whole app is not confinement, it is a rule that has been
+     * turned off politely.
+     *
+     * - the resolver, which is how a runbook is fetched at run time (R-10);
+     * - the reindex command, which asks a source whether it still says what it said (I-03).
+     *   Ingest exists to read other people's repositories, so it cannot be network-free;
+     *   what it can be is a single file, with the decision about what a fetch *means* kept
+     *   somewhere that never makes one.
+     * - the Microsoft triage command (C-03), for exactly that reason: the adapter takes an
+     *   injected `list()` and cannot fetch, the classifier is a pure function over text, and
+     *   the socket lives in the CLI a person runs on purpose. Nothing in the build or the
+     *   serving path calls it.
+     *
+     * The property this protects is unchanged: nothing the supervisor depends on, and
+     * nothing in the serving path, reaches the network.
+     */
+    const ALLOWED = [
+        "apps/cli/src/resolve.ts",
+        "apps/ingest/src/reindex.cli.ts",
+        "apps/ingest/src/microsoft.cli.ts",
+    ];
+    function sources(dir) {
+        const root = join(ROOT, dir);
+        if (!existsSync(root))
+            return [];
+        const out = [];
+        const walk = (d) => {
+            for (const entry of readdirSync(d, { withFileTypes: true })) {
+                const full = join(d, entry.name);
+                if (entry.isDirectory()) {
+                    if (entry.name !== "node_modules" && entry.name !== "dist")
+                        walk(full);
+                }
+                else if (entry.name.endsWith(".ts") && !entry.name.endsWith(".test.ts")) {
+                    out.push(full);
+                }
+            }
+        };
+        walk(root);
+        return out;
+    }
+    /**
+     * The half of the ingest rule that keeps the allowance honest: the file that fetches
+     * makes no decisions, and the file that decides never fetches. Otherwise "one file"
+     * becomes one very large file.
+     */
+    it("the reindex command decides nothing about what a fetch means", () => {
+        const decider = readFileSync(join(ROOT, "apps", "ingest", "src", "upstream.ts"), "utf8");
+        expect(reachesNetwork(decider), "the decision about a fetch must not make one").toBe(false);
+    });
+    it("no package or app reaches the network outside the resolver", () => {
+        const offenders = [...sources("packages"), ...sources("apps")]
+            .map((file) => ({ file: file.slice(ROOT.length + 1), src: readFileSync(file, "utf8") }))
+            .filter(({ file, src }) => reachesNetwork(src) && !ALLOWED.includes(file))
+            .map(({ file }) => file);
+        expect(offenders, `fetching belongs in one of ${ALLOWED.join(" or ")}, so that the supervisor's tree can be checked for having none`).toEqual([]);
+    });
+});

package/dist/report.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The run report.
+ *
+ * What a person reads afterwards, and what an attestation would be built from. Its one
+ * job is to say what actually happened, which means never rounding an undecided
+ * postcondition off to a decided one: `unevaluable` appears here as its own count, and a
+ * check a person decided is marked as theirs rather than as something the supervisor
+ * verified.
+ */
+import type { CheckRecord, RunEvent, RunState } from "./run.js";
+import type { DeviationRecord } from "./deviations.js";
+export interface RunReport {
+    readonly status: RunState["status"];
+    readonly outcome?: RunState["outcome"];
+    readonly complete: boolean;
+    readonly stepsVisited: readonly string[];
+    readonly checks: {
+        readonly passed: number;
+        readonly failed: number;
+        /** Never folded into either of the above. */
+        readonly unevaluable: number;
+        /** Of the decided ones, how many a person decided rather than the supervisor. */
+        readonly adjudicated: number;
+    };
+    /**
+     * What deviated, aggregated. The count is the headline §13.4 asks for; the breakdowns
+     * are what tell an author that agents keep trying something their step 4 forbids.
+     */
+    readonly deviations: {
+        readonly count: number;
+        readonly byClass: Readonly<Record<string, number>>;
+        readonly byStep: Readonly<Record<string, number>>;
+        /** The records themselves: class, step, capability class. No payload, ever. */
+        readonly records: readonly DeviationRecord[];
+    };
+    /**
+     * Both budgets, so a step that chronically exhausts one is visible in aggregate rather
+     * than only in the moment it stopped a run.
+     */
+    readonly budgets: {
+        /** Traversals per retry edge, against the limit the document set. */
+        readonly retries: readonly {
+            readonly edge: string;
+            readonly used: number;
+            readonly max?: number;
+        }[];
+        readonly wallClock: {
+            readonly limitSeconds?: number;
+            readonly elapsedSeconds?: number;
+            readonly exhausted: boolean;
+        };
+    };
+    /** Set while a postcondition is waiting on a person. */
+    readonly awaiting?: {
+        readonly stepId: string;
+        readonly why: string;
+    };
+    readonly detail: readonly CheckRecord[];
+    /**
+     * What this report does and does not establish, stated in the report rather than in
+     * documentation someone may not read (§13.5, §19).
+     */
+    readonly caveats: readonly string[];
+}
+export interface ReportOptions {
+    readonly envelope?: {
+        readonly budgets: Readonly<Record<string, number>>;
+    };
+    /** The clock, supplied rather than read. Without it, elapsed time is simply unknown. */
+    readonly now?: number;
+}
+export declare function report(state: RunState, events?: readonly RunEvent[], options?: ReportOptions): RunReport;