@runbooks/graph 0.1.0

package/dist/relations.test.js

@@ -0,0 +1,140 @@
+import { describe, it, expect } from "vitest";
+import { checkRelations, relationCycles, compositionTrust, parseRef, inheritsUpstream, RELATION_KINDS, MUST_PIN, MAY_CROSS_PUBLISHER, } from "./relations.js";
+const known = {
+    refs: new Set(["std/drain-node", "std/cordon-node", "acme/restart-db"]),
+    versions: {
+        "std/drain-node": ["1.0.0", "1.1.0"],
+        "std/cordon-node": ["1.0.0"],
+        "acme/restart-db": ["2.0.0"],
+    },
+};
+const self = (relations) => ({ publisher: "std", slug: "playbook", relations });
+const check = (relations) => checkRelations(self(relations), known);
+/** "Every edge kind has a validation rule and a fixture." */
+describe("each kind is validated by what it asserts", () => {
+    it("has four kinds and a rule for each", () => {
+        expect([...RELATION_KINDS].sort()).toEqual(["escalates_to", "part_of", "requires", "rollback_of"]);
+        for (const kind of RELATION_KINDS) {
+            expect(MUST_PIN[kind], kind).toBeTypeOf("boolean");
+            expect(MAY_CROSS_PUBLISHER[kind], kind).toBeTypeOf("boolean");
+        }
+    });
+    it("accepts a pinned requires", () => {
+        expect(check([{ kind: "requires", ref: "std/cordon-node@1.0.0" }])).toEqual([]);
+    });
+    it("refuses an unpinned requires, because it asserts what another record does", () => {
+        const [problem] = check([{ kind: "requires", ref: "std/cordon-node" }]);
+        expect(problem.code).toBe("relations/must-pin");
+        expect(problem.message).toMatch(/only true of a version/);
+    });
+    it("refuses a pinned part_of, because a frozen structure rots", () => {
+        const [problem] = check([{ kind: "part_of", ref: "std/drain-node@1.0.0" }]);
+        expect(problem.code).toBe("relations/must-not-pin");
+        expect(problem.message).toMatch(/keep pointing at 1\.0\.0 while/);
+    });
+    it("accepts a structural escalates_to with no version", () => {
+        expect(check([{ kind: "escalates_to", ref: "std/drain-node" }])).toEqual([]);
+    });
+    it("accepts a cross-publisher requires and refuses a cross-publisher part_of", () => {
+        expect(check([{ kind: "requires", ref: "acme/restart-db@2.0.0" }])).toEqual([]);
+        const [problem] = check([{ kind: "part_of", ref: "acme/restart-db" }]);
+        expect(problem.code).toBe("relations/cross-publisher");
+        expect(problem.message).toMatch(/only they can make it/);
+    });
+    it("refuses a record relating to itself", () => {
+        expect(check([{ kind: "requires", ref: "std/playbook@1.0.0" }])[0].code).toBe("relations/self");
+    });
+    it("refuses a reference that is not a reference", () => {
+        expect(check([{ kind: "requires", ref: "not a ref" }])[0].code).toBe("relations/unparseable");
+    });
+});
+/** "A dangling relation is a broken record." */
+describe("a relation that does not resolve", () => {
+    it("fails on a record the catalog does not hold", () => {
+        const [problem] = check([{ kind: "requires", ref: "std/nothing@1.0.0" }]);
+        expect(problem.code).toBe("relations/dangling");
+        expect(problem.message).toMatch(/a reader following it arrives nowhere/);
+    });
+    it("fails on a version that record does not have, and says which it does", () => {
+        const [problem] = check([{ kind: "requires", ref: "std/cordon-node@9.9.9" }]);
+        expect(problem.code).toBe("relations/dangling");
+        expect(problem.message).toMatch(/Pin one it has: 1\.0\.0/);
+    });
+    it("accepts any version that record does have", () => {
+        expect(check([{ kind: "requires", ref: "std/drain-node@1.1.0" }])).toEqual([]);
+    });
+});
+/** All four are acyclic, for reasons that differ by kind and agree in outcome. */
+describe("cycles", () => {
+    const records = [
+        { ref: "std/a", relations: [{ kind: "requires", ref: "std/b@1.0.0" }] },
+        { ref: "std/b", relations: [{ kind: "requires", ref: "std/a@1.0.0" }] },
+        { ref: "std/c", relations: [{ kind: "part_of", ref: "std/a" }] },
+    ];
+    it("finds a requires cycle nobody can satisfy first", () => {
+        const cycles = relationCycles(records, "requires");
+        expect(cycles.length).toBeGreaterThan(0);
+        expect(cycles[0]).toContain("std/a");
+        expect(cycles[0]).toContain("std/b");
+    });
+    it("finds no cycle where there is none", () => {
+        expect(relationCycles(records, "part_of")).toEqual([]);
+        expect(relationCycles(records, "escalates_to")).toEqual([]);
+    });
+    it("finds an escalation loop, which is the failure escalation exists to prevent", () => {
+        const loop = [
+            { ref: "std/a", relations: [{ kind: "escalates_to", ref: "std/b" }] },
+            { ref: "std/b", relations: [{ kind: "escalates_to", ref: "std/a" }] },
+        ];
+        expect(relationCycles(loop, "escalates_to").length).toBeGreaterThan(0);
+    });
+    it("finds a containment that contains itself", () => {
+        const loop = [
+            { ref: "std/a", relations: [{ kind: "part_of", ref: "std/b" }] },
+            { ref: "std/b", relations: [{ kind: "part_of", ref: "std/a" }] },
+        ];
+        expect(relationCycles(loop, "part_of").length).toBeGreaterThan(0);
+    });
+});
+/** "The trust of a composition is defined, not left to intuition." */
+describe("a composition is as trustworthy as its weakest member", () => {
+    it("takes the minimum", () => {
+        expect(compositionTrust(["T4", "T1"])).toBe("T1");
+        expect(compositionTrust(["T3", "T3", "T2"])).toBe("T2");
+        expect(compositionTrust(["T4"])).toBe("T4");
+    });
+    it("does not average, which would let one good member launder four bad ones", () => {
+        expect(compositionTrust(["T4", "T4", "T4", "T4", "T0"])).toBe("T0");
+    });
+    it("is T0 for an empty composition rather than undefined", () => {
+        expect(compositionTrust([])).toBe("T0");
+    });
+});
+/** "A relation to a `gone` upstream record has defined behaviour." */
+describe("a member whose upstream is gone", () => {
+    it("is not a broken relation: the record is still here", () => {
+        expect(check([{ kind: "requires", ref: "acme/restart-db@2.0.0" }])).toEqual([]);
+    });
+    it("reads its upstream state rather than guessing one", () => {
+        expect(inheritsUpstream("gone")).toBe("gone");
+        expect(inheritsUpstream("changed")).toBe("changed");
+        expect(inheritsUpstream(undefined)).toBe("unknown");
+        expect(inheritsUpstream("something-else")).toBe("unknown");
+    });
+    it("shows up in the composition's trust through that member's own level", () => {
+        // Nothing special-cases `gone` here: the member's level already fell when its
+        // upstream did (I-03), and the composition takes the minimum.
+        expect(compositionTrust(["T3", "T1"])).toBe("T1");
+    });
+});
+describe("references", () => {
+    it("parses both forms", () => {
+        expect(parseRef("std/x")).toEqual({ publisher: "std", slug: "x" });
+        expect(parseRef("std/x@1.2.3")).toEqual({ publisher: "std", slug: "x", semver: "1.2.3" });
+    });
+    it("refuses a form that is neither", () => {
+        for (const bad of ["std", "std/", "/x", "std/x@1", "Std/X", "std/x@v1.0.0"]) {
+            expect(parseRef(bad), bad).toBeUndefined();
+        }
+    });
+});

package/dist/simulate.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The dry pass (W-15, §18.3 rule 6, NG1).
+ *
+ * A simulation walks the graph and stops at every point where the document does not say
+ * on its own which way a run goes. Nothing executes: this is a reading of the procedure,
+ * and it is the answer to the neighbours' playground that does not require us to become
+ * one — the questions a reader has before trusting a runbook are answerable from its
+ * structure, and this answers them.
+ *
+ * The walk is here rather than in the page because `paths.ts` already owns reachability
+ * and enumeration, and a second traversal in a component would be the same sweep written
+ * twice: agreeing until somebody changed what counts as an edge in one of them.
+ *
+ * Two edge kinds are deliberately not choices. An `approval` edge is a duplicate of the
+ * transition it gates, so following it would double every gated step; a `rollback` edge
+ * is not a route forward at all. A `retry` is a route, but not one anybody chooses — it
+ * is what the runtime does with a failure under a budget, and offering it as an option
+ * would invite a reader to simulate a decision no operator ever makes.
+ */
+import { type EndOutcome, type Graph, type GraphEdge } from "./model.js";
+/** How a run leaves the procedure. `escalated` is a handoff, not a failure. */
+export type Ending = EndOutcome | "escalated";
+export interface Option {
+    /** Stable answer key: a branch label, or `next` / `on_fail` at an outcome fork. */
+    readonly id: string;
+    readonly label: string;
+    readonly to: string;
+    readonly kind: GraphEdge["kind"];
+}
+export interface Fork {
+    readonly stepId: string;
+    readonly question: string;
+    readonly options: readonly Option[];
+}
+export interface Walk {
+    /** Node ids in the order the run reaches them, starting at the first step. */
+    readonly path: readonly string[];
+    /** Where the walk stopped for an answer. Absent once the run has ended. */
+    readonly fork?: Fork;
+    readonly ending?: Ending;
+    /** Steps on the path an operator must release by hand before they run. */
+    readonly approvals: readonly string[];
+    /**
+     * How far back the nearest undo is from where the walk stopped, in steps.
+     *
+     * The question a reader asks at a destructive step is not "does a rollback exist"
+     * but "how much of this do I have to unwind". Zero means this step names its own
+     * rollback; absent means nothing on the path does, which is worth seeing plainly.
+     */
+    readonly stepsToRollback?: number;
+}
+export type Answers = Readonly<Record<string, string>>;
+/** The transitions a run may take from a node, in document order. */
+export declare function continuations(graph: Graph, from: string): GraphEdge[];
+/**
+ * Walk as far as the answers allow.
+ *
+ * A missing answer is a stop, never a default. The whole point of the exercise is that
+ * the reader says which way their environment goes; guessing for them would produce a
+ * confident picture of a run nobody is going to have.
+ */
+export declare function walk(graph: Graph, answers?: Answers, limit?: number): Walk;
+/** Per-node state for the renderer: what has been passed, where the reader is now. */
+export declare function statesFor(walkResult: Walk): Record<string, "current" | "passed">;

package/dist/simulate.js

@@ -0,0 +1,115 @@
+/**
+ * The dry pass (W-15, §18.3 rule 6, NG1).
+ *
+ * A simulation walks the graph and stops at every point where the document does not say
+ * on its own which way a run goes. Nothing executes: this is a reading of the procedure,
+ * and it is the answer to the neighbours' playground that does not require us to become
+ * one — the questions a reader has before trusting a runbook are answerable from its
+ * structure, and this answers them.
+ *
+ * The walk is here rather than in the page because `paths.ts` already owns reachability
+ * and enumeration, and a second traversal in a component would be the same sweep written
+ * twice: agreeing until somebody changed what counts as an edge in one of them.
+ *
+ * Two edge kinds are deliberately not choices. An `approval` edge is a duplicate of the
+ * transition it gates, so following it would double every gated step; a `rollback` edge
+ * is not a route forward at all. A `retry` is a route, but not one anybody chooses — it
+ * is what the runtime does with a failure under a budget, and offering it as an option
+ * would invite a reader to simulate a decision no operator ever makes.
+ */
+import { isTerminal, START } from "./model.js";
+/** The transitions a run may take from a node, in document order. */
+export function continuations(graph, from) {
+    return graph.edges.filter((edge) => edge.from === from && (edge.kind === "next" || edge.kind === "branch" || edge.kind === "on_fail"));
+}
+function question(graph, id, options) {
+    const node = graph.nodes.find((n) => n.id === id);
+    const asked = node?.step?.question;
+    if (asked)
+        return asked;
+    if (node?.kind === "decision")
+        return node.title;
+    // Not a decision, but the document still forks here: a postcondition that holds and one
+    // that does not are two runs, and which one a reader is looking at is their answer.
+    return options.some((option) => option.kind === "on_fail")
+        ? `Did this step do what it expected? — ${node?.title ?? id}`
+        : (node?.title ?? id);
+}
+function optionsAt(graph, edges) {
+    return edges.map((edge) => ({
+        id: edge.kind === "branch" ? (edge.label ?? edge.to) : edge.kind,
+        label: edge.kind === "branch"
+            ? (edge.label ?? edge.to)
+            : edge.kind === "on_fail"
+                ? "it failed"
+                : "as expected",
+        to: edge.to,
+        kind: edge.kind,
+    }));
+}
+/**
+ * Walk as far as the answers allow.
+ *
+ * A missing answer is a stop, never a default. The whole point of the exercise is that
+ * the reader says which way their environment goes; guessing for them would produce a
+ * confident picture of a run nobody is going to have.
+ */
+export function walk(graph, answers = {}, limit = 256) {
+    const path = [];
+    const approvals = [];
+    const byId = new Map(graph.nodes.map((node) => [node.id, node]));
+    let rollbackAt;
+    let current = continuations(graph, START)[0]?.to;
+    for (let guard = 0; current !== undefined && guard < limit; guard++) {
+        const node = byId.get(current);
+        if (!node) {
+            // A dangling transition. Invariant 2 blocks publication on it, so this only shows
+            // up in a draft — and stopping with the id named is more use than an empty walk.
+            return { path, approvals, ...(rollbackAt === undefined ? {} : { stepsToRollback: path.length - 1 - rollbackAt }) };
+        }
+        path.push(current);
+        if (node.requiresApproval)
+            approvals.push(current);
+        if (graph.edges.some((edge) => edge.from === current && edge.kind === "rollback")) {
+            rollbackAt = path.length - 1;
+        }
+        const distance = rollbackAt === undefined ? {} : { stepsToRollback: path.length - 1 - rollbackAt };
+        if (node.kind === "end") {
+            return { path, approvals, ...(node.outcome ? { ending: node.outcome } : {}), ...distance };
+        }
+        if (isTerminal(node.kind)) {
+            return { path, approvals, ending: "escalated", ...distance };
+        }
+        const edges = continuations(graph, current);
+        if (edges.length === 0) {
+            // Invariant 7 makes this impossible in a published record; a draft can still get
+            // here, and a walk that ends nowhere is exactly what the reader should see.
+            return { path, approvals, ...distance };
+        }
+        if (edges.length === 1) {
+            current = edges[0].to;
+            continue;
+        }
+        const options = optionsAt(graph, edges);
+        const answer = answers[current];
+        const chosen = options.find((option) => option.id === answer);
+        if (!chosen) {
+            return {
+                path,
+                approvals,
+                fork: { stepId: current, question: question(graph, current, options), options },
+                ...distance,
+            };
+        }
+        current = chosen.to;
+    }
+    return { path, approvals, ...(rollbackAt === undefined ? {} : { stepsToRollback: path.length - 1 - rollbackAt }) };
+}
+/** Per-node state for the renderer: what has been passed, where the reader is now. */
+export function statesFor(walkResult) {
+    const states = {};
+    walkResult.path.forEach((id, index) => {
+        states[id] = index === walkResult.path.length - 1 ? "current" : "passed";
+    });
+    return states;
+}

package/dist/simulate.test.d.ts

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

package/dist/simulate.test.js

@@ -0,0 +1,109 @@
+import { describe, it, expect } from "vitest";
+import { toGraph } from "./model.js";
+import { walk, statesFor, continuations } from "./simulate.js";
+const doc = (steps) => ({ runbook: { steps } });
+const linear = toGraph(doc([
+    { id: "s1", kind: "check", title: "Look", tool: "cli:df", expect: "it is there", on_fail: "escalate:s9", next: "s2" },
+    { id: "s2", kind: "action", title: "Fix it", tool: "cli:rm", next: "end:success" },
+    { id: "s9", kind: "escalate", title: "Escalate", to: "team:x" },
+]));
+const branching = toGraph(doc([
+    { id: "s1", kind: "decision", title: "Which way", question: "Is the kubelet reachable?", branches: { yes: "s2", no: "s3" } },
+    { id: "s2", kind: "action", title: "Left", tool: "cli:a", next: "end:success" },
+    { id: "s3", kind: "action", title: "Right", tool: "cli:b", next: "end:failed" },
+]));
+const gated = toGraph(doc([
+    { id: "s1", kind: "check", title: "Look", tool: "cli:df", next: "s2" },
+    {
+        id: "s2", kind: "action", title: "Drain", tool: "cli:kubectl", risk: "destructive",
+        requires_approval: true, rollback_ref: "s3", next: "end:success",
+    },
+    { id: "s3", kind: "action", title: "Uncordon", tool: "cli:kubectl", next: "end:success" },
+]));
+/**
+ * A dry pass is a reading of the document, so it stops wherever the document stops
+ * saying which way a run goes — and nowhere else.
+ */
+describe("the walk goes as far as the document decides on its own", () => {
+    it("stops at the first fork with the question the author wrote", () => {
+        const result = walk(branching);
+        expect(result.path).toEqual(["s1"]);
+        expect(result.fork?.question).toBe("Is the kubelet reachable?");
+        expect(result.fork?.options.map((o) => o.id).sort()).toEqual(["no", "yes"]);
+        expect(result.ending).toBeUndefined();
+    });
+    it("takes the branch the reader chose", () => {
+        expect(walk(branching, { s1: "yes" }).path).toEqual(["s1", "s2", "__end_success"]);
+        expect(walk(branching, { s1: "no" }).ending).toBe("failed");
+    });
+    it("treats a postcondition as a fork too, since a failure is a different run", () => {
+        const result = walk(linear);
+        expect(result.fork?.stepId).toBe("s1");
+        expect(result.fork?.options.map((o) => o.id).sort()).toEqual(["next", "on_fail"]);
+        expect(result.fork?.question).toMatch(/Did this step do what it expected\?/);
+    });
+    it("reaches an ending down each answer", () => {
+        expect(walk(linear, { s1: "next" }).ending).toBe("success");
+        expect(walk(linear, { s1: "on_fail" }).ending).toBe("escalated");
+    });
+    it("never guesses an answer it was not given", () => {
+        // The reader's answer describes their production environment. A default would draw a
+        // confident picture of a run nobody is going to have.
+        expect(walk(branching, { s1: "maybe" }).fork?.stepId).toBe("s1");
+    });
+    it("terminates on a graph with a retry loop rather than following it forever", () => {
+        const retrying = toGraph(doc([
+            { id: "s1", kind: "check", title: "Settled", tool: "cli:test", on_fail: "s2", next: "end:success" },
+            { id: "s2", kind: "wait", title: "Wait", duration: "5s", retry: { max: 2, target: "s1" }, next: "end:failed" },
+        ]));
+        expect(walk(retrying, { s1: "on_fail" }).ending).toBe("failed");
+    });
+});
+/** What the reader came for: the collected outputs along the path they chose. */
+describe("what the chosen path collects", () => {
+    it("names where a person has to release the run by hand", () => {
+        expect(walk(gated).approvals).toEqual(["s2"]);
+    });
+    it("counts how far back the nearest undo is", () => {
+        // s2 names its own rollback; the walk runs on to the ending, one step past it.
+        expect(walk(gated).stepsToRollback).toBe(1);
+        expect(walk(gated, {}).path.indexOf("s2")).toBe(1);
+        expect(walk(gated).path).toEqual(["s1", "s2", "__end_success"]);
+    });
+    it("says nothing about a rollback where the path has none, rather than zero", () => {
+        expect(walk(branching, { s1: "yes" }).stepsToRollback).toBeUndefined();
+    });
+    it("marks where the reader is and what is behind them, and nothing else", () => {
+        const states = statesFor(walk(branching, { s1: "yes" }));
+        expect(states["s1"]).toBe("passed");
+        expect(states["__end_success"]).toBe("current");
+        expect(states["s3"]).toBeUndefined();
+    });
+});
+/**
+ * An approval edge is a duplicate of the transition it gates and a rollback is not a
+ * route forward. Following either would double a gated step or walk the undo as though
+ * it were the procedure.
+ */
+describe("the walk follows routes a run can take", () => {
+    it("offers no approval or rollback edge as a way forward", () => {
+        for (const node of gated.nodes) {
+            expect(continuations(gated, node.id).every((e) => e.kind !== "approval" && e.kind !== "rollback")).toBe(true);
+        }
+    });
+    it("passes a gated step once", () => {
+        expect(walk(gated).path.filter((id) => id === "s2").length).toBe(1);
+    });
+});
+/** A draft is where a broken graph lives. Stopping with the id named beats an empty walk. */
+describe("a graph that does not hold up still walks", () => {
+    it("stops at a transition to a step that is not there", () => {
+        const dangling = toGraph(doc([{ id: "s1", kind: "check", title: "Look", next: "s404" }]));
+        const result = walk(dangling);
+        expect(result.path).toEqual(["s1"]);
+        expect(result.ending).toBeUndefined();
+    });
+    it("walks an empty document without throwing", () => {
+        expect(walk(toGraph(doc([]))).path).toEqual([]);
+    });
+});

package/dist/subgraph.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Subgraphs (W-21, §18.6, Q7).
+ *
+ * §18.6 caps a graph at twelve nodes and sends the rest into a subgraph linked by
+ * `part_of`. Because `part_of` is an edge between **records** (S-13), a subgraph already
+ * has a publisher, a trust level, a provenance chain and a page — so nothing expands in
+ * place, and the parent shows the aggregate instead
+ * (docs/decisions/Q7-subgraph-expansion.md).
+ *
+ * The aggregate is the part a reader cannot afford to have hidden: **a collapsed subgraph
+ * that hides a destructive step is a correctness bug, not a display choice.** So it is
+ * computed transitively — a destructive step two levels down marks the node at the top —
+ * while what is *shown* stays one level deep.
+ */
+import { type RunbookDocument } from "./model.js";
+import { type Relation } from "./relations.js";
+import type { Risk } from "@runbooks/schema";
+/** How deep aggregation walks before it decides the graph of records is malformed. */
+export declare const MAX_ROLLUP_DEPTH = 16;
+export interface SubgraphRecord {
+    readonly ref: string;
+    readonly document: RunbookDocument & {
+        runbook?: {
+            relations?: readonly Relation[];
+            capabilities?: readonly string[];
+        };
+    };
+}
+export interface Aggregate {
+    readonly ref: string;
+    /** The step of the parent this record expands, when it says which. */
+    readonly step?: string;
+    readonly nodes: number;
+    /** The worst risk anywhere inside, including inside its own subgraphs. */
+    readonly highestRisk: Risk;
+    /** Everything it needs, transitively: a reader granting this grants all of it. */
+    readonly capabilities: readonly string[];
+    /** True when something inside forces an approval. Shown, never inferred by the reader. */
+    readonly containsDangerous: boolean;
+    /** How deep the walk actually went, so a cut-off is visible rather than silent. */
+    readonly depth: number;
+    /** Set when the walk stopped early, with why. */
+    readonly truncated?: string;
+}
+/** The children that decompose a record: the ones declaring `part_of` against it. */
+export declare function childrenOf(parentRef: string, records: readonly SubgraphRecord[]): SubgraphRecord[];
+/**
+ * What a collapsed node stands for, computed all the way down.
+ *
+ * The cycle guard is not defensive programming: `part_of` is acyclic by S-13's rule and
+ * the gate refuses a cycle, so reaching one here means the catalog moved underneath us —
+ * and hanging on it would be a worse answer than a truncated one that says so.
+ */
+export declare function aggregate(child: SubgraphRecord, parentRef: string, records: readonly SubgraphRecord[], seen?: ReadonlySet<string>): Aggregate;
+/**
+ * The decomposition of one record, one level deep and summarised all the way down.
+ *
+ * Ordered by the parent's own steps, so following them with a keyboard walks the procedure
+ * in the order it runs rather than in the order the children happen to be filed.
+ */
+export declare function decomposition(parent: SubgraphRecord, records: readonly SubgraphRecord[]): Aggregate[];
+/**
+ * §18.6 rule 2, as a question about one record: is this graph over the cap and undecomposed?
+ *
+ * A warning rather than an error (§6), and it stays one: twelve is a rule about what a
+ * reader can take in, and a procedure that genuinely needs thirteen steps is not invalid.
+ */
+export declare const NODE_CAP = 12;
+export declare function overCap(record: SubgraphRecord, records: readonly SubgraphRecord[]): boolean;

package/dist/subgraph.js

@@ -0,0 +1,119 @@
+/**
+ * Subgraphs (W-21, §18.6, Q7).
+ *
+ * §18.6 caps a graph at twelve nodes and sends the rest into a subgraph linked by
+ * `part_of`. Because `part_of` is an edge between **records** (S-13), a subgraph already
+ * has a publisher, a trust level, a provenance chain and a page — so nothing expands in
+ * place, and the parent shows the aggregate instead
+ * (docs/decisions/Q7-subgraph-expansion.md).
+ *
+ * The aggregate is the part a reader cannot afford to have hidden: **a collapsed subgraph
+ * that hides a destructive step is a correctness bug, not a display choice.** So it is
+ * computed transitively — a destructive step two levels down marks the node at the top —
+ * while what is *shown* stays one level deep.
+ */
+import { toGraph } from "./model.js";
+import { parseRef } from "./relations.js";
+import { isDangerous } from "@runbooks/schema";
+const RISK_ORDER = ["read-only", "reversible-write", "destructive", "irreversible"];
+/** How deep aggregation walks before it decides the graph of records is malformed. */
+export const MAX_ROLLUP_DEPTH = 16;
+function riskOf(document) {
+    const steps = (document.runbook?.steps ?? []);
+    return steps.reduce((worst, step) => step.risk && RISK_ORDER.indexOf(step.risk) > RISK_ORDER.indexOf(worst) ? step.risk : worst, "read-only");
+}
+/** The children that decompose a record: the ones declaring `part_of` against it. */
+export function childrenOf(parentRef, records) {
+    return records.filter((record) => (record.document.runbook?.relations ?? []).some((relation) => {
+        if (relation.kind !== "part_of")
+            return false;
+        const parsed = parseRef(relation.ref);
+        return parsed !== undefined && `${parsed.publisher}/${parsed.slug}` === parentRef;
+    }));
+}
+function stepOf(child, parentRef) {
+    const relation = (child.document.runbook?.relations ?? []).find((candidate) => {
+        if (candidate.kind !== "part_of")
+            return false;
+        const parsed = parseRef(candidate.ref);
+        return parsed !== undefined && `${parsed.publisher}/${parsed.slug}` === parentRef;
+    });
+    return relation?.step;
+}
+/**
+ * What a collapsed node stands for, computed all the way down.
+ *
+ * The cycle guard is not defensive programming: `part_of` is acyclic by S-13's rule and
+ * the gate refuses a cycle, so reaching one here means the catalog moved underneath us —
+ * and hanging on it would be a worse answer than a truncated one that says so.
+ */
+export function aggregate(child, parentRef, records, seen = new Set()) {
+    const visited = new Set([...seen, child.ref]);
+    const graph = toGraph(child.document);
+    const own = graph.nodes.filter((node) => !node.synthetic);
+    let nodes = own.length;
+    let highestRisk = riskOf(child.document);
+    const capabilities = new Set(child.document.runbook?.capabilities ?? []);
+    let depth = 1;
+    let truncated;
+    if (visited.size <= MAX_ROLLUP_DEPTH) {
+        for (const grandchild of childrenOf(child.ref, records)) {
+            if (visited.has(grandchild.ref)) {
+                truncated = `${grandchild.ref} is already on this path: \`part_of\` has a cycle, which the relations gate refuses to publish.`;
+                continue;
+            }
+            const inner = aggregate(grandchild, child.ref, records, visited);
+            nodes += inner.nodes;
+            if (RISK_ORDER.indexOf(inner.highestRisk) > RISK_ORDER.indexOf(highestRisk)) {
+                highestRisk = inner.highestRisk;
+            }
+            for (const capability of inner.capabilities)
+                capabilities.add(capability);
+            depth = Math.max(depth, inner.depth + 1);
+            truncated = truncated ?? inner.truncated;
+        }
+    }
+    else {
+        truncated = `Stopped at ${MAX_ROLLUP_DEPTH} levels. A decomposition this deep is not a decomposition.`;
+    }
+    const step = stepOf(child, parentRef);
+    return {
+        ref: child.ref,
+        ...(step ? { step } : {}),
+        nodes,
+        highestRisk,
+        capabilities: [...capabilities].sort(),
+        // The one thing that must never be hidden by collapsing.
+        containsDangerous: isDangerous(highestRisk),
+        depth,
+        ...(truncated ? { truncated } : {}),
+    };
+}
+/**
+ * The decomposition of one record, one level deep and summarised all the way down.
+ *
+ * Ordered by the parent's own steps, so following them with a keyboard walks the procedure
+ * in the order it runs rather than in the order the children happen to be filed.
+ */
+export function decomposition(parent, records) {
+    const order = (parent.document.runbook?.steps ?? []).map((step) => step.id);
+    return childrenOf(parent.ref, records)
+        .map((child) => aggregate(child, parent.ref, records))
+        .sort((a, b) => {
+        const left = a.step ? order.indexOf(a.step) : Number.MAX_SAFE_INTEGER;
+        const right = b.step ? order.indexOf(b.step) : Number.MAX_SAFE_INTEGER;
+        return left !== right ? left - right : a.ref < b.ref ? -1 : 1;
+    });
+}
+/**
+ * §18.6 rule 2, as a question about one record: is this graph over the cap and undecomposed?
+ *
+ * A warning rather than an error (§6), and it stays one: twelve is a rule about what a
+ * reader can take in, and a procedure that genuinely needs thirteen steps is not invalid.
+ */
+export const NODE_CAP = 12;
+export function overCap(record, records) {
+    const graph = toGraph(record.document);
+    const own = graph.nodes.filter((node) => !node.synthetic).length;
+    return own > NODE_CAP && childrenOf(record.ref, records).length === 0;
+}

package/dist/subgraph.test.d.ts

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