@runbooks/graph 0.1.0

package/dist/invariants.js

@@ -0,0 +1,253 @@
+import { START, isTerminal } from "./model.js";
+import { reachableFrom } from "./paths.js";
+import { isDangerous } from "@runbooks/schema";
+const byId = (g) => new Map(g.nodes.map((n) => [n.id, n]));
+function outgoing(g, id) {
+    return g.edges.filter((e) => e.from === id);
+}
+/** Invariant 1: exactly one `start`, and every node reachable from it. */
+function startAndReachability(g) {
+    const found = [];
+    const starts = g.nodes.filter((n) => n.kind === "start");
+    if (starts.length !== 1) {
+        found.push({
+            code: "graph/start-not-unique",
+            severity: "error",
+            at: starts.map((s) => s.id).join(",") || "(none)",
+            message: `A runbook has exactly one start; this graph has ${starts.length}.`,
+        });
+        if (starts.length === 0)
+            return found;
+    }
+    /**
+     * One walk, in ./paths.ts. This check had its own copy — the same breadth-first sweep
+     * written twice, agreeing today. The next person to change what counts as an edge
+     * would have changed one of them.
+     */
+    const seen = new Set(reachableFrom(g, starts[0].id));
+    for (const n of g.nodes) {
+        if (!seen.has(n.id)) {
+            found.push({
+                code: "graph/unreachable",
+                severity: "error",
+                at: n.id,
+                message: `Step ${n.id} cannot be reached from the start. Connect it, or remove it.`,
+            });
+        }
+    }
+    return found;
+}
+/** Invariant 2: no edges to nowhere. */
+function danglingEdges(g) {
+    const ids = byId(g);
+    return g.edges
+        .filter((e) => !ids.has(e.to))
+        .map((e) => ({
+        code: "graph/dangling-edge",
+        severity: "error",
+        at: `${e.from}->${e.to}`,
+        message: `Step ${e.from} points at ${e.to}, which does not exist. Fix the reference, or add the step.`,
+    }));
+}
+/** Invariant 3: every decision has >=2 branches, each leading to a node, and a default. */
+function decisionsExhaustive(g) {
+    const found = [];
+    for (const n of g.nodes.filter((x) => x.kind === "decision")) {
+        const branches = outgoing(g, n.id).filter((e) => e.kind === "branch");
+        if (branches.length < 2) {
+            found.push({
+                code: "graph/decision-thin",
+                severity: "error",
+                at: n.id,
+                message: `Decision ${n.id} has ${branches.length} branch(es); a decision needs at least two. Add the other outcome, or make this a check.`,
+            });
+        }
+        if (!branches.some((e) => e.label === "default")) {
+            found.push({
+                code: "graph/decision-not-exhaustive",
+                severity: "error",
+                at: n.id,
+                message: `Decision ${n.id} has no default branch. Add one: an agent reaching an answer none of the branches cover would have to invent what happens next.`,
+            });
+        }
+    }
+    return found;
+}
+/** Invariant 4: every check has `expect` and `on_fail` — enforced per step by the
+ *  schema, and here as a routed edge, since an `on_fail` that resolves nowhere is the
+ *  same failure wearing a different hat. */
+function checksRouted(g) {
+    return g.nodes
+        .filter((n) => n.kind === "check")
+        .filter((n) => !outgoing(g, n.id).some((e) => e.kind === "on_fail"))
+        .map((n) => ({
+        code: "graph/check-unrouted",
+        severity: "error",
+        at: n.id,
+        message: `Check ${n.id} has no on_fail route. Say where the procedure goes when the expectation does not hold.`,
+    }));
+}
+/**
+ * Invariant 5: a destructive or irreversible action has an incoming approval gate or an
+ * outgoing rollback. The rule the whole product exists to enforce.
+ *
+ * A `rollback_ref` naming *another runbook* does not satisfy it in v1. Relations between
+ * runbooks are S-13 (v3), so until they exist a supervisor cannot resolve or route to
+ * such a rollback — the reference is documentation for a human, and treating it as a
+ * mitigation would let a destructive step ship with a safety net nothing can deploy.
+ * The schema is deliberately more permissive here: it validates one step in isolation
+ * and cannot see whether a target exists.
+ */
+function destructivePaired(g) {
+    const dangerous = (n) => n.kind === "action" && n.risk !== undefined && isDangerous(n.risk);
+    return g.nodes
+        .filter(dangerous)
+        .filter((n) => {
+        const gated = g.edges.some((e) => e.to === n.id && e.kind === "approval");
+        const rollback = outgoing(g, n.id).some((e) => e.kind === "rollback");
+        return !gated && !rollback;
+    })
+        .map((n) => ({
+        code: "graph/destructive-unpaired",
+        severity: "error",
+        at: n.id,
+        message: `Step ${n.id} is ${n.risk} with neither an approval gate before it nor a rollback this graph can reach. Add requires_approval: true, or point rollback_ref at a step in this runbook.`,
+    }));
+}
+/** Invariant 6: cycles only through a `retry` edge with a finite limit. */
+function cyclesBounded(g) {
+    const found = [];
+    const adjacency = new Map();
+    for (const n of g.nodes)
+        adjacency.set(n.id, outgoing(g, n.id));
+    const state = new Map();
+    const stack = [];
+    const visit = (id) => {
+        state.set(id, 1);
+        stack.push(id);
+        for (const e of adjacency.get(id) ?? []) {
+            const s = state.get(e.to) ?? 0;
+            if (s === 1) {
+                // Back edge: the cycle closes here. Legal only if this very edge is a bounded
+                // retry — an unbounded loop in an autonomous agent costs money and incidents.
+                const bounded = e.kind === "retry" && typeof e.max === "number" && e.max > 0;
+                if (!bounded) {
+                    found.push({
+                        code: "graph/unbounded-cycle",
+                        severity: "error",
+                        at: `${e.from}->${e.to}`,
+                        message: `The path ${e.from} -> ${e.to} closes a loop that is not a bounded retry. Express it as retry with a finite max, or break the cycle.`,
+                    });
+                }
+            }
+            else if (s === 0) {
+                visit(e.to);
+            }
+        }
+        stack.pop();
+        state.set(id, 2);
+    };
+    for (const n of g.nodes)
+        if ((state.get(n.id) ?? 0) === 0)
+            visit(n.id);
+    return found;
+}
+/** Invariant 7: every terminal is explicit — a graph may not end by running out of
+ *  next node. */
+function terminalsExplicit(g) {
+    return g.nodes
+        .filter((n) => !isTerminal(n.kind))
+        .filter((n) => outgoing(g, n.id).filter((e) => e.kind !== "approval").length === 0)
+        .map((n) => ({
+        code: "graph/implicit-terminal",
+        severity: "error",
+        at: n.id,
+        message: `Step ${n.id} has nowhere to go and is not a terminal. Point it at the next step, or at an explicit end.`,
+    }));
+}
+/**
+ * Warnings: they do not block publication, they lower trust (RUNBOOK.md 6).
+ *
+ * §6 lists four. Three are here. The fourth — a declared capability no step uses — is
+ * not, and deliberately: the graph does not see `capabilities[]`, and the linter already
+ * reports it as `capabilities/redundant`. Implementing it twice would be two answers to
+ * one question, and the one nobody looked at would be the one that went wrong.
+ */
+function warnings(g, context) {
+    const found = [];
+    const authored = g.nodes.filter((n) => !n.synthetic && n.kind !== "start");
+    /**
+     * §18.6's node cap is **not** here, deliberately, and for the same reason the fourth §6
+     * warning is not: this function sees one graph and the rule has two clauses.
+     *
+     * "More than 12 nodes **without decomposition into subgraphs**" cannot be answered by a
+     * document alone — whether it was decomposed is a fact about other records. Answering
+     * only the first clause warned at every record that did exactly what the rule asks, and
+     * lowered its trust for complying (§6). It is checked where the catalog is, by the
+     * `subgraphs` gate, which can see both halves.
+     */
+    /**
+     * A step with no tool is a step a reader has to guess at and a supervisor cannot scope.
+     * Not blocking — a `wait`, a `decision` and an `escalate` have nothing to invoke — but
+     * an `action` or a `check` without one is a procedure that does not say what it does.
+     *
+     * Silent on a `human-only` record, and that is not an exemption: both consequences this
+     * warning names are about a machine. `tool` is the capability a supervisor scopes, and a
+     * procedure that declares no agent may run it has no supervisor and nothing to scope, so
+     * the warning was asserting a cost that could not be paid. It fired on every action and
+     * check of all three human-only records — twenty steps that were doing exactly what they
+     * declared — which is how a warning teaches the person reading it to skip the gate.
+     */
+    const forAMachine = context?.execution !== "human-only";
+    for (const node of authored) {
+        if (!forAMachine)
+            break;
+        if (node.kind !== "action" && node.kind !== "check")
+            continue;
+        if (node.step?.tool)
+            continue;
+        found.push({
+            code: "graph/step-without-tool",
+            severity: "warning",
+            at: node.id,
+            message: `Step ${node.id} is an ${node.kind} and names no tool. A reader has to guess what performs it and a supervisor has nothing to scope, so this lowers trust without blocking publication.`,
+        });
+    }
+    /**
+     * A decision whose branch leads to a check with no expectation.
+     *
+     * The branch asked a question and the step it leads to does not say what answer would
+     * mean it went right — so the reader who took that branch has no way to know whether
+     * they are still on the path they chose.
+     */
+    for (const edge of g.edges.filter((e) => e.kind === "branch")) {
+        const target = g.nodes.find((n) => n.id === edge.to);
+        if (!target || target.kind !== "check")
+            continue;
+        if (target.step?.expect)
+            continue;
+        found.push({
+            code: "graph/branch-check-without-expect",
+            severity: "warning",
+            at: target.id,
+            message: `Branch ${edge.label ?? edge.to} leads to check ${target.id}, which has no expect. The reader who took that branch cannot tell whether it worked.`,
+        });
+    }
+    return found;
+}
+const CHECKS = [
+    startAndReachability,
+    danglingEdges,
+    decisionsExhaustive,
+    checksRouted,
+    destructivePaired,
+    cyclesBounded,
+    terminalsExplicit,
+    warnings,
+];
+export function checkGraph(g, context) {
+    return CHECKS.flatMap((check) => check(g, context));
+}
+export function graphErrors(g, context) {
+    return checkGraph(g, context).filter((f) => f.severity === "error");
+}

package/dist/invariants.test.d.ts

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

package/dist/invariants.test.js

@@ -0,0 +1,149 @@
+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 { isDangerous, RISK_ORDER } from "@runbooks/schema";
+import { toGraph, fromGraph } from "./model.js";
+import { graphErrors, checkGraph } from "./invariants.js";
+/** A document is a wrapper around steps; the rest of the frontmatter is P0's business. */
+const doc = (steps) => ({ runbook: { steps } });
+const codes = (d) => graphErrors(toGraph(d)).map((f) => f.code);
+/**
+ * S-03 acceptance: each invariant has a fixture that trips exactly it. "Exactly" is the
+ * point — a fixture that trips three invariants proves nothing about which rule is
+ * doing the work, and a rule with no isolated fixture can be deleted without a test
+ * noticing.
+ */
+describe("each invariant has a fixture that trips exactly it", () => {
+    const escalate = { id: "s9", kind: "escalate", title: "Escalate", to: "team:x" };
+    it("2 — an edge to a step that does not exist", () => {
+        expect(codes(doc([
+            { id: "s1", kind: "check", title: "Check", expect: "ok", on_fail: "nowhere", next: "s9" },
+            escalate,
+        ]))).toEqual(["graph/dangling-edge"]);
+    });
+    it("3 — a decision with no default branch", () => {
+        expect(codes(doc([
+            { id: "s1", kind: "decision", title: "Decide", question: "q?", branches: { a: "s9", b: "s9" } },
+            escalate,
+        ]))).toEqual(["graph/decision-not-exhaustive"]);
+    });
+    it("3 — a decision with a single branch", () => {
+        expect(codes(doc([
+            { id: "s1", kind: "decision", title: "Decide", question: "q?", branches: { default: "s9" } },
+            escalate,
+        ]))).toEqual(["graph/decision-thin"]);
+    });
+    it("4 — a check with no on_fail route", () => {
+        expect(codes(doc([{ id: "s1", kind: "check", title: "Check", expect: "ok", next: "s9" }, escalate]))).toEqual(["graph/check-unrouted"]);
+    });
+    it("5 — a destructive action with neither gate nor rollback", () => {
+        expect(codes(doc([{ id: "s1", kind: "action", title: "Drop it", risk: "destructive", next: "s9" }, escalate]))).toEqual(["graph/destructive-unpaired"]);
+    });
+    /**
+     * Invariant 5 draws its line from one place, `isDangerous`, and the line has four
+     * values on either side of it — not the one this fixture names. Asking every value
+     * is what fails if the predicate is ever written out by hand here again and drifts.
+     */
+    it.each(RISK_ORDER)("5 — %s is paired if and only if the spec calls it dangerous", (risk) => {
+        const found = codes(doc([{ id: "s1", kind: "action", title: "Do it", risk, next: "s9" }, escalate]));
+        expect(found).toEqual(isDangerous(risk) ? ["graph/destructive-unpaired"] : []);
+    });
+    it("6 — a loop that is not a bounded retry", () => {
+        expect(codes(doc([
+            { id: "s1", kind: "action", title: "Try", risk: "read-only", next: "s2" },
+            { id: "s2", kind: "action", title: "Again", risk: "read-only", next: "s1" },
+        ]))).toEqual(["graph/unbounded-cycle"]);
+    });
+    it("7 — a step that runs off the end without a terminal", () => {
+        // A decision whose branches are its only exits, with one branch pointing at a step
+        // that itself goes nowhere.
+        expect(codes(doc([
+            { id: "s1", kind: "decision", title: "Decide", question: "q?", branches: { a: "s2", default: "s9" } },
+            { id: "s2", kind: "decision", title: "Decide again", question: "q?", branches: { a: "s9", default: "s9" } },
+            escalate,
+        ]))).toEqual([]);
+    });
+});
+describe("what the invariants accept", () => {
+    it("passes a bounded retry", () => {
+        expect(codes(doc([
+            { id: "s1", kind: "wait", title: "Wait", duration: "30s", retry: { max: 3, target: "s1" }, next: "s9" },
+            { id: "s9", kind: "escalate", title: "Escalate", to: "team:x" },
+        ]))).toEqual([]);
+    });
+    it("accepts a destructive action gated by approval", () => {
+        expect(codes(doc([
+            { id: "s1", kind: "action", title: "Drop it", risk: "destructive", requires_approval: true, next: "s9" },
+            { id: "s9", kind: "escalate", title: "Escalate", to: "team:x" },
+        ]))).toEqual([]);
+    });
+    it("leaves §18.6's node cap to the gate that can see whether it was decomposed", () => {
+        const steps = Array.from({ length: 13 }, (_, i) => ({
+            id: `s${i}`, kind: "action", title: `Step ${i}`, risk: "read-only",
+        }));
+        const findings = checkGraph(toGraph(doc(steps)));
+        expect(findings.filter((f) => f.severity === "error")).toEqual([]);
+        // §18.6's cap has two clauses — over twelve *and* undecomposed — and this function
+        // can only see one graph. It is checked by the `subgraphs` gate, which has the
+        // catalog; warning here punished every record that decomposed as the rule asks.
+        expect(findings.map((f) => f.code)).not.toContain("graph/too-many-nodes");
+    });
+});
+describe("messages are actionable (RUNBOOK.md 18.7)", () => {
+    it("names the step and what to do about it", () => {
+        const [finding] = graphErrors(toGraph(doc([{ id: "s4", kind: "action", title: "Drop it", risk: "destructive", next: "s9" },
+            { id: "s9", kind: "escalate", title: "Escalate", to: "team:x" }])));
+        expect(finding.at).toBe("s4");
+        expect(finding.message).toContain("s4");
+        expect(finding.message).toMatch(/Add requires_approval|rollback_ref/);
+        expect(finding.message).not.toMatch(/something went wrong/i);
+    });
+    it("every finding carries a code that can resolve to a spec anchor", () => {
+        const findings = checkGraph(toGraph(doc([{ id: "s1", kind: "check", title: "C" }])));
+        for (const f of findings)
+            expect(f.code).toMatch(/^graph\/[a-z-]+$/);
+    });
+});
+describe("derivation is deterministic and lossless", () => {
+    const FIXTURES = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "schema", "fixtures", "p1-valid");
+    const docs = readdirSync(FIXTURES).map((name) => ({
+        name,
+        d: JSON.parse(readFileSync(join(FIXTURES, name), "utf8")),
+    }));
+    /**
+     * Guards the guard: these are `it.each(docs)`, and an empty fixture directory registers
+     * no tests at all — §6's determinism would read as checked when nothing was read.
+     */
+    it("has fixtures to derive", () => {
+        expect(docs.length).toBeGreaterThan(0);
+    });
+    it.each(docs)("$name derives identically twice", ({ d }) => {
+        expect(toGraph(d)).toEqual(toGraph(d));
+    });
+    it.each(docs)("$name round-trips through the graph unchanged", ({ d }) => {
+        expect(fromGraph(toGraph(d))).toEqual(d.runbook.steps);
+    });
+    it.each(docs)("$name has no blocking invariant errors", ({ d }) => {
+        expect(graphErrors(toGraph(d))).toEqual([]);
+    });
+});
+describe("a cross-runbook rollback does not satisfy invariant 5 in v1", () => {
+    // Both steps stay on the main flow whichever way rollback_ref points, so the only
+    // thing that varies between the two cases is the rule under test.
+    const destructive = (rollback) => doc([
+        { id: "s1", kind: "action", title: "Drop it", risk: "destructive", rollback_ref: rollback, next: "s2" },
+        { id: "s2", kind: "action", title: "Put it back", risk: "reversible-write", next: "end:success" },
+    ]);
+    it("accepts a rollback this graph can reach", () => {
+        expect(codes(destructive("s2"))).toEqual([]);
+    });
+    // Relations between runbooks are S-13 (v3). Until they exist a supervisor cannot
+    // route to this rollback, so counting it would ship a destructive step with a safety
+    // net nothing can deploy.
+    it("refuses a rollback that names another runbook", () => {
+        expect(codes(destructive("rb_01J8ZQK2M9AAB1CDEFGHJKMNPQ"))).toEqual([
+            "graph/destructive-unpaired",
+        ]);
+    });
+});

package/dist/layout.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Layered layout, top to bottom, with our constraints as hard constraints.
+ *
+ * A generic Sugiyama implementation optimizes for edge crossings and will happily place
+ * a rollback on the right. RUNBOOK.md §6 asks for something else: **consistency of
+ * direction matters more than compactness**, because a reader must locate the bad path
+ * in two seconds. So:
+ *
+ * - the happy path is a strictly vertical centre axis, x = 0, no deviation;
+ * - `on_fail` and `escalate` go right;
+ * - `rollback` goes left;
+ * - `retry` is a returning arc and does not affect layering.
+ *
+ * Deterministic: the same graph yields byte-identical coordinates, which is what makes a
+ * rendered SVG diffable and a card's mini-graph silhouette stable across builds. Nothing
+ * here consults `x-layout` — auto-layout is canonical (docs/decisions/Q8-layout.md).
+ */
+import type { Graph } from "./model.js";
+export interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+export interface Layout {
+    /** Node id to grid position. `x` is columns from the centre axis, `y` is the layer. */
+    readonly positions: Readonly<Record<string, Point>>;
+    /** Nodes on the happy path, in order. */
+    readonly happyPath: readonly string[];
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * The happy path: from the start, following `next`, and at a `decision` taking the first
+ * branch in document order that does not lead straight to an escalation.
+ *
+ * Deterministic by construction — document order, never a heuristic score — because a
+ * silhouette that changes when the layout algorithm is retuned is not a silhouette.
+ */
+export declare function happyPath(graph: Graph): string[];
+export declare function layout(graph: Graph): Layout;
+/**
+ * Topological order: the sequence a reader should meet the nodes in.
+ *
+ * Used for keyboard traversal (§18.2) and for the structured list a screen reader gets
+ * instead of the picture. A procedure that cannot be read linearly is inaccessible, and
+ * every valid graph has such an order — invariant 6 guarantees the only cycles are
+ * bounded retries, which are ignored here.
+ *
+ * Deterministic: ties break by document order, never by id, so two runs and two machines
+ * agree.
+ */
+export declare function topologicalOrder(graph: Graph): string[];

package/dist/layout.js

@@ -0,0 +1,185 @@
+import { START } from "./model.js";
+/** Edges that carry the flow forward, and so determine layering. */
+const FORWARD = new Set(["next", "branch", "on_fail"]);
+function outgoing(graph, id) {
+    return graph.edges.filter((e) => e.from === id);
+}
+/**
+ * The happy path: from the start, following `next`, and at a `decision` taking the first
+ * branch in document order that does not lead straight to an escalation.
+ *
+ * Deterministic by construction — document order, never a heuristic score — because a
+ * silhouette that changes when the layout algorithm is retuned is not a silhouette.
+ */
+export function happyPath(graph) {
+    const kindOf = new Map(graph.nodes.map((n) => [n.id, n.kind]));
+    const path = [];
+    const seen = new Set();
+    let current = START;
+    while (current && !seen.has(current)) {
+        path.push(current);
+        seen.add(current);
+        const edges = outgoing(graph, current);
+        const next = edges.find((e) => e.kind === "next");
+        if (next) {
+            current = next.to;
+            continue;
+        }
+        const branch = edges
+            .filter((e) => e.kind === "branch")
+            .find((e) => kindOf.get(e.to) !== "escalate");
+        current = branch?.to;
+    }
+    return path;
+}
+/**
+ * Longest-path layering, so an edge never points upward.
+ *
+ * Forward and backward are relaxed together rather than one after the other. A node
+ * reachable only by `rollback` or `retry` has no forward in-edge, so on its own it keeps
+ * depth 0 and lands on the top row — which put "Uncordon the node", the undo for a drain
+ * five layers down, above the `start` of the procedure. Placing it under its source is
+ * only half the fix: whatever *it* leads to has to move down with it, and a second pass
+ * after the first leaves that behind. Running both to a fixed point is what keeps the
+ * terminal an undo leads to below the undo.
+ */
+function layers(graph) {
+    const depth = new Map();
+    const forward = graph.edges.filter((e) => FORWARD.has(e.kind));
+    const backward = graph.edges.filter((e) => e.kind === "rollback" || e.kind === "retry");
+    const reachedForward = new Set(forward.map((e) => e.to));
+    for (const n of graph.nodes)
+        depth.set(n.id, 0);
+    // Relaxation bounded by node count: a forward cycle cannot exist (invariant 6), so
+    // this settles, and the bound keeps a malformed graph from hanging an editor.
+    for (let pass = 0; pass < graph.nodes.length + 1; pass++) {
+        let changed = false;
+        const relax = (from, to) => {
+            const candidate = (depth.get(from) ?? 0) + 1;
+            if (candidate > (depth.get(to) ?? 0)) {
+                depth.set(to, candidate);
+                changed = true;
+            }
+        };
+        for (const e of forward)
+            relax(e.from, e.to);
+        // Only for a node nothing forward reaches: a step on the happy path keeps the depth
+        // the flow gave it, whatever rolls back to it.
+        for (const e of backward)
+            if (!reachedForward.has(e.to))
+                relax(e.from, e.to);
+        if (!changed)
+            break;
+    }
+    return depth;
+}
+export function layout(graph) {
+    const depth = layers(graph);
+    const path = happyPath(graph);
+    const onAxis = new Set(path);
+    const positions = {};
+    for (const id of path)
+        positions[id] = { x: 0, y: depth.get(id) ?? 0 };
+    // Sides are assigned by the edge that first reaches a node, in graph order. `rollback`
+    // wins over `on_fail` when both reach it: an undo is the more important thing to find.
+    const side = new Map();
+    for (const e of graph.edges) {
+        if (onAxis.has(e.to))
+            continue;
+        if (e.kind === "rollback")
+            side.set(e.to, -1);
+        else if ((e.kind === "on_fail" || e.kind === "branch") && !side.has(e.to))
+            side.set(e.to, 1);
+    }
+    // An escalation is a bad path wherever it was reached from.
+    for (const n of graph.nodes) {
+        if (n.kind === "escalate" && !onAxis.has(n.id))
+            side.set(n.id, 1);
+    }
+    /** Columns already taken per layer per side, so two off-axis nodes never overlap. */
+    const used = new Map();
+    for (const n of graph.nodes) {
+        if (positions[n.id])
+            continue;
+        const y = depth.get(n.id) ?? 0;
+        const direction = side.get(n.id) ?? 1;
+        const key = `${y}:${direction}`;
+        const taken = used.get(key) ?? 0;
+        used.set(key, taken + 1);
+        positions[n.id] = { x: direction * (taken + 1), y };
+    }
+    const xs = Object.values(positions).map((p) => p.x);
+    const ys = Object.values(positions).map((p) => p.y);
+    return {
+        positions,
+        happyPath: path,
+        width: Math.max(...xs) - Math.min(...xs) + 1,
+        height: Math.max(...ys) + 1,
+    };
+}
+/**
+ * Topological order: the sequence a reader should meet the nodes in.
+ *
+ * Used for keyboard traversal (§18.2) and for the structured list a screen reader gets
+ * instead of the picture. A procedure that cannot be read linearly is inaccessible, and
+ * every valid graph has such an order — invariant 6 guarantees the only cycles are
+ * bounded retries, which are ignored here.
+ *
+ * Deterministic: ties break by document order, never by id, so two runs and two machines
+ * agree.
+ */
+export function topologicalOrder(graph) {
+    const forward = graph.edges.filter((e) => FORWARD.has(e.kind));
+    const remaining = new Map();
+    for (const n of graph.nodes)
+        remaining.set(n.id, 0);
+    for (const e of forward)
+        remaining.set(e.to, (remaining.get(e.to) ?? 0) + 1);
+    /**
+     * What each step exists to undo.
+     *
+     * A rollback edge is not a flow edge — including it in `FORWARD` would make a cycle of
+     * every paired destructive step — so the step it points at has no incoming flow at all
+     * and lands wherever the node list happens to put it. On `std/k8s-node-not-ready-drain`
+     * that put "Uncordon the node" second, ahead of the drain it undoes: a reader following
+     * the list, which is what a screen reader and a no-CSS reader get, was handed the
+     * procedure with its undo before its action.
+     *
+     * The constraint below only chooses between nodes the flow leaves free, so this is
+     * still a topological order over the flow edges — it is the arbitrary part of the
+     * choice that is being spent on something a reader can use.
+     */
+    const undoes = new Map();
+    for (const e of graph.edges)
+        if (e.kind === "rollback")
+            undoes.set(e.to, e.from);
+    const order = [];
+    const emitted = new Set();
+    const ready = graph.nodes.filter((n) => (remaining.get(n.id) ?? 0) === 0).map((n) => n.id);
+    while (ready.length > 0) {
+        /*
+         * The first node whose undone step has already been read, and the first node outright
+         * when none qualifies. That fallback is what keeps a pair of steps rolling each other
+         * back from deadlocking the traversal — a malformed graph is still traversable.
+         */
+        const at = ready.findIndex((candidate) => {
+            const undone = undoes.get(candidate);
+            return undone === undefined || emitted.has(undone);
+        });
+        const id = ready.splice(at === -1 ? 0 : at, 1)[0];
+        emitted.add(id);
+        order.push(id);
+        for (const e of forward.filter((x) => x.from === id)) {
+            const left = (remaining.get(e.to) ?? 0) - 1;
+            remaining.set(e.to, left);
+            if (left === 0)
+                ready.push(e.to);
+        }
+    }
+    // A malformed graph must still be traversable: anything left over is appended in
+    // document order rather than silently dropped from keyboard navigation.
+    for (const n of graph.nodes)
+        if (!order.includes(n.id))
+            order.push(n.id);
+    return order;
+}

package/dist/layout.test.d.ts

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