@runbooks/supervise 0.1.0

package/dist/run.js

@@ -0,0 +1,445 @@
+import { authorize } from "./policy.js";
+import { evaluate } from "./expect.js";
+import { recordDeviation, DEFAULT_ESCALATION } from "./deviations.js";
+import { plural } from "@runbooks/schema";
+export function startRun(envelope, options = {}) {
+    const opts = "inputs" in options || "agentIdentity" in options
+        ? options
+        : { inputs: options };
+    const provided = opts.inputs ?? {};
+    const refusals = [];
+    const bound = {};
+    for (const [name, decl] of Object.entries(envelope.inputs)) {
+        const value = provided[name] ?? decl.default;
+        if (value === undefined) {
+            if (decl.required) {
+                refusals.push({
+                    code: "run/input-missing",
+                    message: `Input "${name}" is required and was not supplied. Provide it, or run a procedure that does not need it.`,
+                });
+            }
+            continue;
+        }
+        if (typeof value !== decl.type) {
+            refusals.push({
+                code: "run/input-type",
+                message: `Input "${name}" must be a ${decl.type}; got ${typeof value}.`,
+            });
+            continue;
+        }
+        bound[name] = value;
+    }
+    for (const name of Object.keys(provided)) {
+        if (!(name in envelope.inputs)) {
+            refusals.push({
+                code: "run/input-undeclared",
+                message: `Input "${name}" is not declared by this runbook. Nothing would bind it, so it is more likely a typo than an extra.`,
+            });
+        }
+    }
+    if (!envelope.entry) {
+        refusals.push({
+            code: "run/no-entry",
+            message: "This runbook has no steps, so there is nothing to supervise.",
+        });
+    }
+    if (refusals.length > 0)
+        return { ok: false, refusals };
+    return {
+        ok: true,
+        state: {
+            status: "running",
+            current: envelope.entry,
+            visited: [envelope.entry],
+            agentIdentity: opts.agentIdentity ?? "agent",
+            retries: {},
+            deviations: [],
+            escalation: opts.escalation ?? DEFAULT_ESCALATION,
+            checks: [],
+            mustCheck: opts.evaluatePostconditions === true,
+            ...(opts.now !== undefined ? { startedAt: opts.now } : {}),
+            ...(opts.wallClockSeconds !== undefined ? { wallClockSeconds: opts.wallClockSeconds } : {}),
+            inputs: bound,
+        },
+        events: [
+            { kind: "started", code: "run/started", message: `Entering ${envelope.entry}.`, at: envelope.entry },
+        ],
+    };
+}
+/**
+ * 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 function outOfTime(state, now) {
+    if (now === undefined || state.startedAt === undefined || state.wallClockSeconds === undefined) {
+        return false;
+    }
+    return now - state.startedAt > state.wallClockSeconds;
+}
+function timeOut(state) {
+    return {
+        state: { ...state, status: "ended", outcome: "timed-out" },
+        events: [
+            {
+                kind: "budget-exhausted",
+                code: "run/wall-clock-exhausted",
+                message: `The run passed its wall-clock budget of ${state.wallClockSeconds}s. Stopping: a procedure that has run long past what the operator allowed is not one to keep authorizing calls for.`,
+                ...(state.current ? { at: state.current } : {}),
+            },
+        ],
+    };
+}
+/** Authorize a proposed invocation against the current step. */
+export function propose(envelope, state, proposal) {
+    if (state.status === "ended" || !state.current) {
+        const authorization = {
+            verdict: "block",
+            reason: "The run has ended; nothing further is authorized.",
+            deviation: "out-of-order-step",
+        };
+        const recorded = recordDeviation(state, { class: "out-of-order-step" });
+        return {
+            state: recorded.state,
+            authorization,
+            events: [
+                { kind: "deviation", code: "run/after-end", message: authorization.reason },
+                ...recorded.events,
+            ],
+        };
+    }
+    if (outOfTime(state, proposal.now)) {
+        const timedOut = timeOut(state);
+        return {
+            state: timedOut.state,
+            authorization: {
+                verdict: "block",
+                reason: timedOut.events[0].message,
+                deviation: "budget-exhausted",
+            },
+            events: timedOut.events,
+        };
+    }
+    const approved = new Set(state.grant && state.grant.stepId === state.current ? [state.current] : []);
+    const authorization = authorize(envelope, {
+        stepId: state.current,
+        tool: proposal.tool,
+        approved,
+    });
+    if (authorization.verdict === "permit") {
+        return {
+            state,
+            authorization,
+            events: [
+                { kind: "authorized", code: "run/permitted", message: authorization.reason, at: state.current },
+            ],
+        };
+    }
+    if (authorization.verdict === "require-approval") {
+        return {
+            state: { ...state, status: "awaiting-approval" },
+            authorization,
+            events: [
+                { kind: "approval-requested", code: "run/approval-required", message: authorization.reason, at: state.current },
+            ],
+        };
+    }
+    const deviation = authorization.deviation ?? "undeclared-tool";
+    const recorded = recordDeviation(state, { class: deviation, capability: proposal.tool });
+    return {
+        state: recorded.state,
+        authorization,
+        events: [
+            { kind: "deviation", code: `run/${deviation}`, message: authorization.reason, at: state.current },
+            ...recorded.events,
+        ],
+    };
+}
+/**
+ * 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 function applyGrant(state, granted) {
+    return {
+        state: {
+            ...state,
+            grant: granted,
+            status: state.status === "awaiting-approval" ? "running" : state.status,
+        },
+        authorization: { verdict: "permit", reason: `Step ${granted.stepId} approved by ${granted.decidedBy}.` },
+        events: [
+            {
+                kind: "approved",
+                code: "run/approved",
+                message: `Step ${granted.stepId} approved by ${granted.decidedBy}.`,
+                at: granted.stepId,
+            },
+        ],
+    };
+}
+/** Move to the next step, counting retry budgets and detecting terminals. */
+export function advance(envelope, state, to, now) {
+    if (outOfTime(state, now))
+        return timeOut(state);
+    if (!state.current || state.status === "ended") {
+        return {
+            state,
+            events: [{ kind: "deviation", code: "run/after-end", message: "The run has already ended." }],
+        };
+    }
+    const from = envelope.steps[state.current];
+    /**
+     * A step whose postcondition has not been decided cannot be left.
+     *
+     * Without this, "the supervisor routes" is true only of the routes it was asked
+     * about: an agent could simply advance past a check along a declared edge and never
+     * report a result. The edge is legal; taking it before the check is not.
+     */
+    if (state.mustCheck && from?.assert && state.decided !== state.current) {
+        const recorded = recordDeviation(state, { class: "unchecked-advance" });
+        return {
+            state: recorded.state,
+            events: [
+                {
+                    kind: "deviation",
+                    code: "run/unchecked-advance",
+                    message: `${state.current} declares a postcondition that has not been decided. At R2 a check is left by its result, not by proposal.`,
+                    at: state.current,
+                },
+                ...recorded.events,
+            ],
+        };
+    }
+    const scope = envelope.steps[state.current];
+    if (!scope || !scope.transitions.includes(to)) {
+        const recorded = recordDeviation(state, { class: "out-of-order-step" });
+        return {
+            state: recorded.state,
+            events: [
+                {
+                    kind: "deviation",
+                    code: "run/out-of-order-step",
+                    message: `Step ${state.current} does not lead to ${to}. The graph decides where a run goes, not the agent.`,
+                    at: state.current,
+                },
+                ...recorded.events,
+            ],
+        };
+    }
+    const edge = `${state.current}->${to}`;
+    const budget = envelope.budgets[edge];
+    if (budget !== undefined) {
+        const used = (state.retries[edge] ?? 0) + 1;
+        if (used > budget) {
+            return {
+                state: {
+                    ...recordDeviation(state, { class: "budget-exhausted" }).state,
+                    status: "ended",
+                    outcome: "budget-exhausted",
+                },
+                events: [
+                    {
+                        kind: "budget-exhausted",
+                        code: "run/budget-exhausted",
+                        message: `Retry budget of ${budget} on ${edge} is exhausted after ${plural(used - 1, "traversal")}. Stopping rather than looping: an unbounded loop in an autonomous agent costs money and causes incidents. This is not a failure of ${state.current} — the step decided nothing; the run gave up on it.`,
+                        at: state.current,
+                    },
+                ],
+            };
+        }
+        state = { ...state, retries: { ...state.retries, [edge]: used } };
+    }
+    // A grant covers one entry into one step. Leaving discards it, and a retry that
+    // returns here is a new entry needing a new decision. The same is true of a decided
+    // postcondition: coming back means checking again.
+    const { grant: _spent, decided: _checked, ...rest } = state;
+    state = rest;
+    if (envelope.terminals.includes(to)) {
+        const outcome = to.startsWith("__end_")
+            ? to.slice("__end_".length)
+            : "failed";
+        return {
+            state: { ...state, status: "ended", current: to, visited: [...state.visited, to], outcome },
+            events: [{ kind: "ended", code: "run/ended", message: `Run ended: ${outcome}.`, at: to }],
+        };
+    }
+    return {
+        state: { ...state, current: to, visited: [...state.visited, to] },
+        events: [{ kind: "entered", code: "run/entered", message: `Entering ${to}.`, at: to }],
+    };
+}
+/** A run that stopped anywhere but a terminal is incomplete, and says so (13.4). */
+export function isComplete(state) {
+    return state.status === "ended" && state.outcome !== undefined;
+}
+/**
+ * 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 function observe(envelope, state, observation, now) {
+    if (!state.current || state.status === "ended") {
+        return {
+            state,
+            events: [{ kind: "deviation", code: "run/after-end", message: "The run has already ended." }],
+            evaluation: { outcome: "unevaluable", predicates: [], why: "The run has already ended." },
+        };
+    }
+    const stepId = state.current;
+    const scope = envelope.steps[stepId];
+    const evaluation = evaluate(scope?.assert, observation);
+    const why = evaluation.outcome === "pass" ? "The postcondition holds." : evaluation.why;
+    const record = { stepId, outcome: evaluation.outcome, why };
+    const withCheck = { ...state, checks: [...state.checks, record], decided: stepId };
+    if (evaluation.outcome === "unevaluable") {
+        return {
+            state: { ...withCheck, status: "awaiting-adjudication", awaiting: { stepId, why } },
+            events: [
+                {
+                    kind: "expectation-unevaluable",
+                    code: "run/expectation-unevaluable",
+                    message: `${stepId}: ${why} The run stops here for a person to decide.`,
+                    at: stepId,
+                },
+            ],
+            evaluation,
+        };
+    }
+    const routed = route(envelope, withCheck, evaluation.outcome, why, now);
+    return { ...routed, evaluation };
+}
+/**
+ * Where a decided postcondition sends the run.
+ *
+ * Routing goes through `advance`, so a retry edge is still counted, a terminal still
+ * ends the run, and a grant is still discarded on the way out. A second mover here
+ * would be a second set of rules about the same graph.
+ */
+function route(envelope, state, outcome, why, now) {
+    const stepId = state.current;
+    const scope = envelope.steps[stepId];
+    const target = outcome === "pass" ? scope?.onPass : scope?.onFail;
+    const kind = outcome === "pass" ? "expectation-passed" : "expectation-failed";
+    const decided = {
+        kind,
+        code: `run/expectation-${outcome === "pass" ? "passed" : "failed"}`,
+        message: `${stepId}: ${why}`,
+        at: stepId,
+    };
+    if (!target) {
+        // A check whose failure routes nowhere is a defect in the document (invariant 4).
+        // Continuing past it would be the supervisor deciding what the author did not.
+        if (outcome === "fail") {
+            return {
+                state: {
+                    ...recordDeviation(state, { class: "unrouted-failure", stepId }).state,
+                    status: "ended",
+                    outcome: "aborted",
+                },
+                events: [
+                    decided,
+                    {
+                        kind: "deviation",
+                        code: "run/unrouted-failure",
+                        message: `${stepId} failed its postcondition and declares no on_fail. Aborting: where to go next is the author's decision, and it was not made.`,
+                        at: stepId,
+                    },
+                ],
+            };
+        }
+        // A pass with more than one way forward is a choice the graph left open.
+        return { state, events: [decided] };
+    }
+    const moved = advance(envelope, state, target, now);
+    return { state: moved.state, events: [decided, ...moved.events] };
+}
+export class SelfAdjudicationError extends Error {
+    constructor(identity) {
+        super(`${identity} is running this procedure and cannot also decide whether its own step ` +
+            `succeeded. A supervisor that asks the agent how it did has stopped supervising.`);
+        this.name = "SelfAdjudicationError";
+    }
+}
+/**
+ * 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 function adjudicate(envelope, state, decision) {
+    if (state.status !== "awaiting-adjudication" || !state.awaiting) {
+        return {
+            state,
+            events: [
+                {
+                    kind: "deviation",
+                    code: "run/nothing-to-adjudicate",
+                    message: "No postcondition is waiting on a decision.",
+                },
+            ],
+        };
+    }
+    if (decision.decidedBy === state.agentIdentity)
+        throw new SelfAdjudicationError(decision.decidedBy);
+    const stepId = state.awaiting.stepId;
+    const why = `${decision.decidedBy} decided the step ${decision.verdict === "pass" ? "succeeded" : "failed"}.${decision.note ? ` ${decision.note}` : ""}`;
+    const checks = state.checks.map((check, index) => index === state.checks.length - 1 && check.stepId === stepId
+        ? { ...check, outcome: decision.verdict, why, adjudicatedBy: decision.decidedBy }
+        : check);
+    const { awaiting: _resolved, ...rest } = state;
+    const resumed = { ...rest, status: "running", checks, decided: stepId };
+    const routed = route(envelope, resumed, decision.verdict, why);
+    return {
+        state: routed.state,
+        events: [
+            {
+                kind: "adjudicated",
+                code: "run/adjudicated",
+                message: `${stepId}: ${why}`,
+                at: stepId,
+            },
+            ...routed.events,
+        ],
+    };
+}
+/**
+ * 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 function conclude(envelope, state) {
+    if (state.status === "ended")
+        return { state, events: [] };
+    const atTerminal = state.current !== undefined && envelope.terminals.includes(state.current);
+    if (atTerminal) {
+        return {
+            state: { ...state, status: "ended", outcome: "success" },
+            events: [{ kind: "ended", code: "run/ended", message: "Run ended: success.", at: state.current }],
+        };
+    }
+    const recorded = recordDeviation(state, { class: "terminal-not-reached" });
+    return {
+        state: { ...recorded.state, status: "ended", outcome: "aborted" },
+        events: [
+            {
+                kind: "deviation",
+                code: "run/terminal-not-reached",
+                message: `The run stopped at ${state.current ?? "no step"}, which is not a terminal. What happened after that is not something this supervisor saw.`,
+                ...(state.current ? { at: state.current } : {}),
+            },
+            ...recorded.events,
+        ],
+    };
+}

package/dist/run.test.d.ts

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

package/dist/run.test.js

@@ -0,0 +1,198 @@
+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 } from "./policy.js";
+import { startRun, propose, applyGrant, advance, isComplete } from "./run.js";
+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")),
+}));
+const runbook = (r) => ({ runbook: r });
+const started = (doc, inputs = {}) => {
+    const env = derivePolicy(doc);
+    const result = startRun(env, inputs);
+    if (!result.ok)
+        throw new Error("expected the run to start");
+    return { env, state: result.state };
+};
+/**
+ * R-01 acceptance: inputs are bound and validated before the graph is entered. Not
+ * lazily at first use — interpolating an empty string does not make a command narrower,
+ * it makes it a different one.
+ */
+describe("inputs are bound before the first step", () => {
+    const needsGroup = runbook({
+        capabilities: ["cli:kafka"],
+        inputs: { group: { type: "string", required: true } },
+        steps: [{ id: "s1", kind: "action", title: "Restart", risk: "read-only", tool: "cli:kafka", next: "end:success" }],
+    });
+    it("aborts before entering the graph when a required input is missing", () => {
+        const result = startRun(derivePolicy(needsGroup), {});
+        expect(result.ok).toBe(false);
+        if (result.ok)
+            return;
+        expect(result.refusals[0].code).toBe("run/input-missing");
+        expect(result.refusals[0].message).toContain("group");
+    });
+    it("starts once the input is supplied", () => {
+        const result = startRun(derivePolicy(needsGroup), { group: "checkout" });
+        expect(result.ok).toBe(true);
+        if (result.ok)
+            expect(result.state.inputs.group).toBe("checkout");
+    });
+    it("applies a declared default", () => {
+        const doc = runbook({
+            inputs: { dry_run: { type: "boolean", required: false, default: true } },
+            steps: [{ id: "s1", kind: "action", title: "Go", risk: "read-only", next: "end:success" }],
+        });
+        const result = startRun(derivePolicy(doc), {});
+        expect(result.ok && result.state.inputs.dry_run).toBe(true);
+    });
+    it("refuses a value of the wrong type", () => {
+        const result = startRun(derivePolicy(needsGroup), { group: 42 });
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.refusals[0].code).toBe("run/input-type");
+    });
+    // More likely a typo than an extra, and a typo that silently does nothing is how a
+    // run proceeds against the wrong target.
+    it("refuses an input the runbook does not declare", () => {
+        const result = startRun(derivePolicy(needsGroup), { group: "checkout", gruop: "x" });
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.refusals[0].code).toBe("run/input-undeclared");
+    });
+});
+describe("authorization follows the current step", () => {
+    const doc = 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" },
+        ],
+    });
+    it("permits what the current step declares", () => {
+        const { env, state } = started(doc);
+        expect(propose(env, state, { tool: "cli:kubectl" }).authorization.verdict).toBe("permit");
+    });
+    it("blocks a capability that belongs to a later step", () => {
+        const { env, state } = started(doc);
+        const decided = propose(env, state, { tool: "mcp:postgres" });
+        expect(decided.authorization.verdict).toBe("block");
+        expect(decided.state.deviations.map((d) => d.class)).toEqual(["out-of-scope-tool"]);
+    });
+    it("permits it once the run has reached that step", () => {
+        const { env, state } = started(doc);
+        const { state: at2 } = advance(env, state, "s2");
+        expect(propose(env, at2, { tool: "mcp:postgres" }).authorization.verdict).toBe("permit");
+    });
+});
+describe("approval gates", () => {
+    const doc = runbook({
+        capabilities: ["mcp:postgres"],
+        steps: [
+            {
+                id: "s1", kind: "action", title: "Drop it", risk: "destructive",
+                tool: "mcp:postgres", requires_approval: true, next: "end:success",
+            },
+        ],
+    });
+    it("asks rather than blocking, and holds the run", () => {
+        const { env, state } = started(doc);
+        const decided = propose(env, state, { tool: "mcp:postgres" });
+        expect(decided.authorization.verdict).toBe("require-approval");
+        expect(decided.state.status).toBe("awaiting-approval");
+    });
+    it("permits only after the decision is recorded", () => {
+        const { env, state } = started(doc);
+        const held = propose(env, state, { tool: "mcp:postgres" }).state;
+        const resumed = applyGrant(held, { requestId: "r1", stepId: "s1", decidedBy: "operator" }).state;
+        expect(resumed.status).toBe("running");
+        expect(propose(env, resumed, { tool: "mcp:postgres" }).authorization.verdict).toBe("permit");
+    });
+});
+describe("the graph decides where a run goes, not the agent", () => {
+    const doc = runbook({
+        capabilities: [],
+        steps: [
+            { id: "s1", kind: "check", title: "Look", risk: "read-only", expect: "ok", on_fail: "s2", next: "s2" },
+            { id: "s2", kind: "action", title: "Act", risk: "read-only", next: "end:success" },
+            { id: "s3", kind: "action", title: "Elsewhere", risk: "read-only", next: "end:success" },
+        ],
+    });
+    it("records a transition the graph does not permit as a deviation", () => {
+        const { env, state } = started(doc);
+        const moved = advance(env, state, "s3");
+        expect(moved.state.deviations.map((d) => d.class)).toEqual(["out-of-order-step"]);
+        expect(moved.state.current).toBe("s1");
+    });
+});
+describe("retry budgets are counted and terminate the run", () => {
+    const doc = runbook({
+        capabilities: [],
+        steps: [
+            { id: "s1", kind: "wait", title: "Wait", duration: "5s", retry: { max: 2, target: "s1" }, next: "end:success" },
+        ],
+    });
+    it("aborts once the budget is exhausted rather than looping", () => {
+        const { env } = started(doc);
+        let s = started(doc).state;
+        s = advance(env, s, "s1").state;
+        s = advance(env, s, "s1").state;
+        const third = advance(env, s, "s1");
+        expect(third.state.status).toBe("ended");
+        // Its own outcome, not a generic abort: the step decided nothing, the run gave up.
+        expect(third.state.outcome).toBe("budget-exhausted");
+        expect(third.events[0].code).toBe("run/budget-exhausted");
+    });
+});
+describe("the core is deterministic and side-effect free", () => {
+    it.each(corpus)("$name decides identically for the same sequence", ({ doc }) => {
+        const env = derivePolicy(doc);
+        const once = startRun(env, sampleInputs(doc));
+        const twice = startRun(env, sampleInputs(doc));
+        expect(JSON.stringify(once)).toBe(JSON.stringify(twice));
+    });
+    it("does not mutate the state it is given", () => {
+        const { env, state } = started(runbook({
+            capabilities: ["cli:x"],
+            steps: [{ id: "s1", kind: "action", title: "Go", risk: "read-only", tool: "cli:x", next: "end:success" }],
+        }));
+        const before = JSON.stringify({ ...state });
+        propose(env, state, { tool: "cli:x" });
+        advance(env, state, "__end_success");
+        expect(JSON.stringify({ ...state })).toBe(before);
+    });
+});
+describe("every event carries a code that resolves to a spec anchor", () => {
+    it("codes are namespaced and lowercase", () => {
+        const { env, state } = started(runbook({
+            capabilities: [],
+            steps: [{ id: "s1", kind: "action", title: "Go", risk: "read-only", next: "end:success" }],
+        }));
+        const events = [
+            ...propose(env, state, { tool: "cli:nope" }).events,
+            ...advance(env, state, "__end_success").events,
+        ];
+        expect(events.length).toBeGreaterThan(0);
+        for (const e of events)
+            expect(e.code).toMatch(/^run\/[a-z-]+$/);
+    });
+    it("a run that ended is complete; one that stopped elsewhere is not", () => {
+        const { env, state } = started(runbook({
+            capabilities: [],
+            steps: [{ id: "s1", kind: "action", title: "Go", risk: "read-only", next: "end:success" }],
+        }));
+        expect(isComplete(state)).toBe(false);
+        expect(isComplete(advance(env, state, "__end_success").state)).toBe(true);
+    });
+});
+function sampleInputs(doc) {
+    const out = {};
+    for (const [name, decl] of Object.entries(doc.runbook?.inputs ?? {})) {
+        out[name] = decl.type === "boolean" ? true : decl.type === "number" ? 1 : "x";
+    }
+    return out;
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@runbooks/supervise",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Supervisor core: pure decision logic. No I/O, no network.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@runbooks/schema": "^0.1.0",
+    "@runbooks/graph": "^0.1.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/runbooks-directory/runbooks.directory"
+  },
+  "engines": {
+    "node": ">=20.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@runbooks/fixtures": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run --passWithNoTests",
+    "lint": "eslint src"
+  }
+}