@runbooks/graph 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikhail Dorokhovich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# `@runbooks/graph`
+
+The graph model, the seven blocking invariants, and layered layout.
+
+**Tasks:** [P-07](../../tasks/v0/P-07-graph-model-package.md),
+[P-08](../../tasks/v0/P-08-graph-layout.md) · **Normative:** RUNBOOK.md §6
+
+One model, three consumers: the linter, the renderer, the editor. If the editor grows
+its own graph representation, the two drift and the constructor starts producing
+documents the linter rejects for reasons the editor cannot explain.
+
+No dependency on React, the DOM, or Node — it runs in the browser for live editing and
+in CI for linting.
+
+Layout is not generic Sugiyama: the happy path is a strictly vertical centre axis,
+`on_fail`/`escalate` go right, `rollback` goes left. Consistency of direction beats
+compactness, because a reader must locate the bad path in two seconds.

package/dist/diff.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Graph diff (W-17, §18.4).
+ *
+ * `/r/{…}/diff/{a}..{b}` answers one question a textual diff buries: **did anything get
+ * more dangerous?** A version bump that turns a `reversible-write` into a `destructive`
+ * and one that renames a step are not comparable events, and a unified diff shows them as
+ * the same number of changed lines.
+ *
+ * So risk changes are their own class here, and so are capability changes — a new
+ * capability in a new version is a new privilege request, and it deserves the prominence
+ * that word implies rather than a green plus sign.
+ *
+ * Alignment is by id first. Ids are how a document refers to its own steps, and two
+ * versions that kept them are telling us what corresponds to what. Where an id vanished
+ * and another appeared, the structural match is offered as a *candidate* and marked as
+ * one: an alignment that guessed silently would draw a correspondence nobody wrote.
+ */
+import type { Graph, GraphEdge, GraphNode } from "./model.js";
+import type { Risk } from "@runbooks/schema";
+export type Change = "added" | "removed" | "unchanged" | "modified";
+export interface NodeDiff {
+    readonly id: string;
+    readonly change: Change;
+    readonly before?: GraphNode;
+    readonly after?: GraphNode;
+    /** Set when the risk moved. `escalated` is the one this whole view exists for. */
+    readonly risk?: {
+        readonly from?: Risk;
+        readonly to?: Risk;
+        readonly direction: "escalated" | "reduced";
+    };
+    /** Set when a matched pair was matched structurally rather than by id. */
+    readonly matchedBy?: "position";
+    /** What else moved: title, command, tool, approval. Named, never counted. */
+    readonly fields?: readonly string[];
+}
+export interface EdgeDiff {
+    readonly from: string;
+    readonly to: string;
+    readonly kind: GraphEdge["kind"];
+    readonly change: Exclude<Change, "modified">;
+}
+export interface GraphDiff {
+    readonly nodes: readonly NodeDiff[];
+    readonly edges: readonly EdgeDiff[];
+    /** Risk escalations, first, because they are the reason this page exists. */
+    readonly escalations: readonly NodeDiff[];
+    /** A new capability is a new privilege request (§13.2). */
+    readonly capabilities: {
+        readonly added: readonly string[];
+        readonly removed: readonly string[];
+    };
+    /** True when nothing about what this procedure does or may invoke changed. */
+    readonly safe: boolean;
+}
+/**
+ * The union of both graphs, for a layout both renderings share.
+ *
+ * This is what makes "unchanged regions do not shift" true rather than approximately
+ * true: the coordinates are computed once, over every node either version has, and each
+ * picture draws its own subset at those coordinates. Laying out each version separately
+ * would move everything below an inserted step, and a reader would compare two pictures
+ * that disagree about where the procedure is.
+ */
+export declare function unionGraph(before: Graph, after: Graph): Graph;
+export declare function diffGraphs(before: Graph, after: Graph): GraphDiff;
+/**
+ * What a reader is told first.
+ *
+ * Ordered by what can hurt them: a risk escalation, then a new privilege, then structure.
+ * A diff that led with "three steps renamed" would bury the one line that matters in the
+ * only case where the page is being read urgently.
+ */
+export declare function summarise(diff: GraphDiff): string[];

package/dist/diff.js

@@ -0,0 +1,148 @@
+import { plural } from "@runbooks/schema";
+const RISK_ORDER = ["read-only", "reversible-write", "destructive", "irreversible"];
+const edgeKey = (edge) => `${edge.from}->${edge.to}:${edge.kind}`;
+/**
+ * The union of both graphs, for a layout both renderings share.
+ *
+ * This is what makes "unchanged regions do not shift" true rather than approximately
+ * true: the coordinates are computed once, over every node either version has, and each
+ * picture draws its own subset at those coordinates. Laying out each version separately
+ * would move everything below an inserted step, and a reader would compare two pictures
+ * that disagree about where the procedure is.
+ */
+export function unionGraph(before, after) {
+    const nodes = new Map();
+    for (const node of before.nodes)
+        nodes.set(node.id, node);
+    // The later version wins on shape and risk: the union exists to place things, and where
+    // a node changed, its current form is the one a reader is being asked about.
+    for (const node of after.nodes)
+        nodes.set(node.id, node);
+    const edges = new Map();
+    for (const edge of [...before.edges, ...after.edges])
+        edges.set(edgeKey(edge), edge);
+    return { nodes: [...nodes.values()], edges: [...edges.values()] };
+}
+function fieldsThatMoved(before, after) {
+    const moved = [];
+    if (before.title !== after.title)
+        moved.push("title");
+    if (before.step?.command !== after.step?.command)
+        moved.push("command");
+    if (before.step?.tool !== after.step?.tool)
+        moved.push("tool");
+    if (before.requiresApproval !== after.requiresApproval)
+        moved.push("requires_approval");
+    if (before.kind !== after.kind)
+        moved.push("kind");
+    return moved;
+}
+/**
+ * A structural candidate for a node that lost its id.
+ *
+ * Deliberately narrow: same kind, same command, and no other unmatched node shares them.
+ * Anything looser would pair two steps because they are both actions, which is not
+ * evidence of anything.
+ */
+function structuralMatch(node, candidates) {
+    const same = candidates.filter((candidate) => candidate.kind === node.kind && candidate.step?.command === node.step?.command);
+    return same.length === 1 ? same[0] : undefined;
+}
+export function diffGraphs(before, after) {
+    const beforeById = new Map(before.nodes.map((node) => [node.id, node]));
+    const afterById = new Map(after.nodes.map((node) => [node.id, node]));
+    const nodes = [];
+    const matchedAfter = new Set();
+    for (const node of before.nodes) {
+        const counterpart = afterById.get(node.id);
+        if (counterpart) {
+            matchedAfter.add(counterpart.id);
+            nodes.push(compare(node, counterpart));
+            continue;
+        }
+        const candidate = structuralMatch(node, after.nodes.filter((other) => !beforeById.has(other.id) && !matchedAfter.has(other.id)));
+        if (candidate) {
+            matchedAfter.add(candidate.id);
+            nodes.push({ ...compare(node, candidate), matchedBy: "position" });
+            continue;
+        }
+        nodes.push({ id: node.id, change: "removed", before: node });
+    }
+    for (const node of after.nodes) {
+        if (matchedAfter.has(node.id) || beforeById.has(node.id))
+            continue;
+        nodes.push({ id: node.id, change: "added", after: node });
+    }
+    const beforeEdges = new Map(before.edges.map((edge) => [edgeKey(edge), edge]));
+    const afterEdges = new Map(after.edges.map((edge) => [edgeKey(edge), edge]));
+    const edges = [];
+    for (const [key, edge] of beforeEdges) {
+        edges.push({ from: edge.from, to: edge.to, kind: edge.kind, change: afterEdges.has(key) ? "unchanged" : "removed" });
+    }
+    for (const [key, edge] of afterEdges) {
+        if (!beforeEdges.has(key))
+            edges.push({ from: edge.from, to: edge.to, kind: edge.kind, change: "added" });
+    }
+    const capabilitiesBefore = capabilitiesOf(before);
+    const capabilitiesAfter = capabilitiesOf(after);
+    const escalations = nodes.filter((node) => node.risk?.direction === "escalated");
+    return {
+        nodes: nodes.sort((a, b) => (a.id < b.id ? -1 : 1)),
+        edges: edges.sort((a, b) => (`${a.from}${a.to}${a.kind}` < `${b.from}${b.to}${b.kind}` ? -1 : 1)),
+        escalations,
+        capabilities: {
+            added: [...capabilitiesAfter].filter((capability) => !capabilitiesBefore.has(capability)).sort(),
+            removed: [...capabilitiesBefore].filter((capability) => !capabilitiesAfter.has(capability)).sort(),
+        },
+        safe: escalations.length === 0 &&
+            [...capabilitiesAfter].every((capability) => capabilitiesBefore.has(capability)),
+    };
+}
+function compare(before, after) {
+    const fields = fieldsThatMoved(before, after);
+    const from = before.risk;
+    const to = after.risk;
+    const moved = from !== to;
+    const direction = RISK_ORDER.indexOf(to ?? "read-only") > RISK_ORDER.indexOf(from ?? "read-only") ? "escalated" : "reduced";
+    return {
+        id: after.id,
+        change: moved || fields.length > 0 ? "modified" : "unchanged",
+        before,
+        after,
+        ...(moved ? { risk: { ...(from ? { from } : {}), ...(to ? { to } : {}), direction } } : {}),
+        ...(fields.length > 0 ? { fields } : {}),
+    };
+}
+function capabilitiesOf(graph) {
+    const out = new Set();
+    for (const node of graph.nodes) {
+        if (node.step?.tool)
+            out.add(node.step.tool);
+    }
+    return out;
+}
+/**
+ * What a reader is told first.
+ *
+ * Ordered by what can hurt them: a risk escalation, then a new privilege, then structure.
+ * A diff that led with "three steps renamed" would bury the one line that matters in the
+ * only case where the page is being read urgently.
+ */
+export function summarise(diff) {
+    const lines = [];
+    for (const node of diff.escalations) {
+        lines.push(`${node.id} became ${node.risk?.to ?? "more dangerous"}: it was ${node.risk?.from ?? "unclassified"}. A step that changed class is not a step that was renamed.`);
+    }
+    for (const capability of diff.capabilities.added) {
+        lines.push(`${capability} is new in this version. A new capability is a new privilege request: check it against your allowlist before running.`);
+    }
+    const added = diff.nodes.filter((node) => node.change === "added").length;
+    const removed = diff.nodes.filter((node) => node.change === "removed").length;
+    const modified = diff.nodes.filter((node) => node.change === "modified").length;
+    if (added || removed || modified) {
+        lines.push(`${plural(added, "step")} added, ${removed} removed, ${modified} changed.`);
+    }
+    if (lines.length === 0)
+        lines.push("Nothing changed in the graph.");
+    return lines;
+}

package/dist/diff.test.d.ts

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

package/dist/diff.test.js

@@ -0,0 +1,140 @@
+import { describe, it, expect } from "vitest";
+import { toGraph } from "./model.js";
+import { layout } from "./layout.js";
+import { diffGraphs, unionGraph, summarise } from "./diff.js";
+const doc = (steps) => ({ runbook: { steps } });
+const v1 = toGraph(doc([
+    { id: "s1", kind: "check", title: "Look", tool: "cli:df", command: "df -h", risk: "read-only", next: "s2" },
+    { id: "s2", kind: "action", title: "Clean up", tool: "cli:rm", command: "rm /tmp/x", risk: "reversible-write", next: "end:success" },
+]));
+/** Same procedure, one step now destructive and a new tool. */
+const v2 = toGraph(doc([
+    { id: "s1", kind: "check", title: "Look", tool: "cli:df", command: "df -h", risk: "read-only", next: "s2" },
+    { id: "s2", kind: "action", title: "Clean up", tool: "cli:rm", command: "rm -rf /var/lib/x", risk: "destructive", requires_approval: true, next: "s3" },
+    { id: "s3", kind: "check", title: "Confirm", tool: "cli:kubectl", command: "kubectl get pods", risk: "read-only", next: "end:success" },
+]));
+/** "A risk escalation is visible without reading labels" — and named, first, in words. */
+describe("what got more dangerous comes first", () => {
+    it("reports the escalation as its own class", () => {
+        const diff = diffGraphs(v1, v2);
+        expect(diff.escalations.map((node) => node.id)).toEqual(["s2"]);
+        expect(diff.escalations[0].risk).toEqual({ from: "reversible-write", to: "destructive", direction: "escalated" });
+    });
+    it("leads with it, before anything structural", () => {
+        const lines = summarise(diffGraphs(v1, v2));
+        expect(lines[0]).toMatch(/s2 became destructive/);
+        expect(lines[0]).toMatch(/not a step that was renamed/);
+    });
+    it("distinguishes a reduction from an escalation", () => {
+        const diff = diffGraphs(v2, v1);
+        expect(diff.escalations).toEqual([]);
+        expect(diff.nodes.find((node) => node.id === "s2").risk.direction).toBe("reduced");
+    });
+    it("carries the risk into both pictures, where hue already says it", () => {
+        // §18.2: risk owns the colour channel, so a class change repaints the node. The diff
+        // does not invent a second encoding for it; it names the change in words as well.
+        const diff = diffGraphs(v1, v2);
+        const s2 = diff.nodes.find((node) => node.id === "s2");
+        expect(s2.before?.risk).toBe("reversible-write");
+        expect(s2.after?.risk).toBe("destructive");
+    });
+});
+/** "A capability added between versions is called out, not left to the reader to notice." */
+describe("a new capability is a new privilege request", () => {
+    it("names it", () => {
+        expect(diffGraphs(v1, v2).capabilities.added).toEqual(["cli:kubectl"]);
+    });
+    it("says what it means, rather than listing a delta", () => {
+        expect(summarise(diffGraphs(v1, v2)).join(" ")).toMatch(/check it against your allowlist/);
+    });
+    it("reports a removed capability without calling it a risk", () => {
+        const diff = diffGraphs(v2, v1);
+        expect(diff.capabilities.removed).toEqual(["cli:kubectl"]);
+        expect(diff.capabilities.added).toEqual([]);
+    });
+    it("calls a version safe only when nothing escalated and nothing was granted", () => {
+        expect(diffGraphs(v1, v2).safe).toBe(false);
+        expect(diffGraphs(v1, v1).safe).toBe(true);
+        expect(diffGraphs(v2, v1).safe).toBe(true);
+    });
+});
+/** "Unchanged regions of the graph do not shift position between the two renderings." */
+describe("one layout, two pictures", () => {
+    it("places every shared node identically in both versions", () => {
+        const shared = layout(unionGraph(v1, v2)).positions;
+        const before = layout(unionGraph(v1, v2)).positions;
+        for (const id of ["s1", "s2"]) {
+            expect(shared[id], id).toEqual(before[id]);
+        }
+    });
+    it("keeps a node's position when a step is inserted after it", () => {
+        const union = layout(unionGraph(v1, v2)).positions;
+        const alone = layout(v1).positions;
+        // s1 is the first step in both, and an insertion later in the procedure must not
+        // move it: a reader comparing two pictures should not have to re-find the top.
+        expect(union["s1"]).toEqual(alone["s1"]);
+    });
+    it("is deterministic, which is what makes the shared layout possible", () => {
+        expect(layout(unionGraph(v1, v2)).positions).toEqual(layout(unionGraph(v1, v2)).positions);
+    });
+    it("contains every node either version has", () => {
+        const union = unionGraph(v1, v2);
+        for (const id of ["s1", "s2", "s3"]) {
+            expect(union.nodes.some((node) => node.id === id), id).toBe(true);
+        }
+    });
+    it("takes the later form of a node that changed, since that is what is being asked about", () => {
+        expect(unionGraph(v1, v2).nodes.find((node) => node.id === "s2").risk).toBe("destructive");
+    });
+});
+describe("what changed structurally", () => {
+    it("marks an added step as added and a removed one as removed", () => {
+        expect(diffGraphs(v1, v2).nodes.find((node) => node.id === "s3").change).toBe("added");
+        expect(diffGraphs(v2, v1).nodes.find((node) => node.id === "s3").change).toBe("removed");
+    });
+    it("names the fields that moved rather than counting them", () => {
+        const s2 = diffGraphs(v1, v2).nodes.find((node) => node.id === "s2");
+        expect(s2.fields).toContain("command");
+        expect(s2.fields).toContain("requires_approval");
+    });
+    it("reports an unchanged step as unchanged", () => {
+        expect(diffGraphs(v1, v2).nodes.find((node) => node.id === "s1").change).toBe("unchanged");
+    });
+    it("diffs the edges an insertion changed", () => {
+        const diff = diffGraphs(v1, v2);
+        expect(diff.edges.some((edge) => edge.from === "s2" && edge.to === "s3" && edge.change === "added")).toBe(true);
+        expect(diff.edges.some((edge) => edge.from === "s2" && edge.to === "__end_success" && edge.change === "removed")).toBe(true);
+    });
+    it("says nothing changed when nothing did", () => {
+        expect(summarise(diffGraphs(v1, v1))).toEqual(["Nothing changed in the graph."]);
+    });
+});
+/** An alignment that guessed silently would draw a correspondence nobody wrote. */
+describe("a step that lost its id", () => {
+    const renamed = toGraph(doc([
+        { id: "s1", kind: "check", title: "Look", tool: "cli:df", command: "df -h", risk: "read-only", next: "cleanup" },
+        { id: "cleanup", kind: "action", title: "Clean up", tool: "cli:rm", command: "rm /tmp/x", risk: "reversible-write", next: "end:success" },
+    ]));
+    it("is matched structurally when the match is unambiguous", () => {
+        const diff = diffGraphs(v1, renamed);
+        const matched = diff.nodes.find((node) => node.id === "cleanup");
+        expect(matched.change).not.toBe("added");
+        expect(matched.matchedBy).toBe("position");
+    });
+    it("says the match was structural, so a reader can disbelieve it", () => {
+        expect(diffGraphs(v1, renamed).nodes.some((node) => node.matchedBy === "position")).toBe(true);
+    });
+    it("refuses to match two candidates that are merely the same kind", () => {
+        const two = toGraph(doc([
+            { id: "a", kind: "action", title: "One", tool: "cli:x", command: "x", risk: "reversible-write", next: "b" },
+            { id: "b", kind: "action", title: "Two", tool: "cli:y", command: "y", risk: "reversible-write", next: "end:success" },
+        ]));
+        const other = toGraph(doc([
+            { id: "c", kind: "action", title: "One", tool: "cli:x", command: "z", risk: "reversible-write", next: "d" },
+            { id: "d", kind: "action", title: "Two", tool: "cli:y", command: "w", risk: "reversible-write", next: "end:success" },
+        ]));
+        const diff = diffGraphs(two, other);
+        expect(diff.nodes.filter((node) => node.matchedBy === "position")).toEqual([]);
+        expect(diff.nodes.filter((node) => node.change === "added").length).toBe(2);
+    });
+});

package/dist/edit.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Editor operations (W-10, §18.3).
+ *
+ * The constructor is a **view over this model**, not a second representation of it. If it
+ * grew its own mutable graph, the editor and the linter would drift, and the editor would
+ * start producing documents the linter rejects for reasons the editor cannot explain.
+ *
+ * So every operation here takes `steps[]` and returns `steps[]`. There is no editor
+ * state, no node objects with identity, nothing to keep in sync — the document is the
+ * state, and the graph is derived from it whenever anything needs to look at shape.
+ *
+ * Two §18.3 rules shape all of this, and both are about refusing to accumulate garbage:
+ *
+ * - **A node cannot exist without a `kind`** (rule 2). There is no placeholder node, so
+ *   there is no moment where a draft contains something nobody has decided about.
+ * - **Deleting a node requires reconnection** (rule 4). A dangling edge does not exist,
+ *   not even in a draft, because a draft that cannot be reasoned about is a draft the
+ *   validation cannot help with.
+ */
+import type { NodeKind, RawStep } from "./model.js";
+export type StepKind = Exclude<NodeKind, "start" | "end">;
+export declare const STEP_KINDS: readonly StepKind[];
+export type EditFailure = {
+    readonly code: "unknown-step";
+    readonly why: string;
+} | {
+    readonly code: "kind-required";
+    readonly why: string;
+} | {
+    readonly code: "reconnect-required";
+    readonly why: string;
+} | {
+    readonly code: "illegal-edge";
+    readonly why: string;
+} | {
+    readonly code: "duplicate-id";
+    readonly why: string;
+};
+export type EditResult = {
+    readonly ok: true;
+    readonly steps: readonly RawStep[];
+    readonly note?: string;
+} | {
+    readonly ok: false;
+    readonly failure: EditFailure;
+};
+/** The next free `sN`, so ids stay short and predictable rather than opaque. */
+export declare function nextId(steps: readonly RawStep[]): string;
+export interface AddStep {
+    /** Required. A node without one cannot exist (§18.3 rule 2). */
+    readonly kind: StepKind;
+    readonly title: string;
+    /** Where it goes. Appended at the end when absent. */
+    readonly after?: string;
+    readonly id?: string;
+}
+/**
+ * Add a step.
+ *
+ * The kind is a parameter rather than something set later, which is the whole of rule 2:
+ * an editor that creates a node and asks afterwards has a state where the node exists and
+ * nobody has decided what it is — and that state ends up in a draft, in an undo stack,
+ * and eventually in a file.
+ *
+ * The new step inherits the `next` of whatever it follows and takes its place, so
+ * inserting into a chain does not leave the chain pointing past it.
+ */
+export declare function addStep(steps: readonly RawStep[], input: AddStep): EditResult;
+export interface DeleteStep {
+    /**
+     * Where the incoming edges go instead. Required whenever anything points at the step:
+     * §18.3 rule 4. `"drop"` removes those references explicitly rather than silently.
+     */
+    readonly reconnectTo?: string | "drop";
+}
+/**
+ * Delete a step, reconnecting what pointed at it.
+ *
+ * Refusing without an instruction is the point. An editor that deletes and leaves the
+ * edges is an editor that produces a document the linter rejects for a reason the person
+ * who deleted the node will not connect to what they did.
+ */
+export declare function deleteStep(steps: readonly RawStep[], id: string, options?: DeleteStep): EditResult;
+/**
+ * The edges an author draws.
+ *
+ * A subset of the model's `EdgeKind`, and deliberately not the same type: the model also
+ * has `approval`, which the derivation adds at every gated arrival and no author ever
+ * draws. Letting an editor offer it would let somebody draw a gate that the derivation
+ * then adds again.
+ */
+export type AuthoredEdge = "next" | "on_fail" | "branch" | "rollback" | "retry";
+/**
+ * Which edges a kind may have.
+ *
+ * Derived from what the kinds mean rather than from what the schema tolerates: a `wait`
+ * has no failure route because waiting does not fail, it times out; an `escalate` has no
+ * outgoing edge at all because it is where a procedure hands off to a person.
+ */
+export declare const LEGAL_EDGES: Readonly<Record<StepKind, readonly AuthoredEdge[]>>;
+export interface Connect {
+    readonly from: string;
+    readonly to: string;
+    readonly kind: AuthoredEdge;
+    /** Required for a branch: an unlabelled branch is a choice nobody can read. */
+    readonly label?: string;
+}
+export declare function connect(steps: readonly RawStep[], edge: Connect): EditResult;
+/**
+ * Undo and redo over whole documents.
+ *
+ * A history of documents rather than of operations, so "undo restores state exactly"
+ * (W-10) is true by construction — including after an automatic insertion, which is the
+ * case an operation-based history gets wrong: the inverse of "add a step" is not
+ * "delete a step" when adding one also inserted an approval gate.
+ */
+export interface History {
+    readonly past: readonly (readonly RawStep[])[];
+    readonly present: readonly RawStep[];
+    readonly future: readonly (readonly RawStep[])[];
+}
+export declare function begin(steps: readonly RawStep[]): History;
+export declare function commit(history: History, steps: readonly RawStep[]): History;
+export declare function undo(history: History): History;
+export declare function redo(history: History): History;
+/**
+ * Changing risk changes the graph (§18.3 rule 3).
+ *
+ * Setting `destructive` or `irreversible` on a step makes invariant 5 apply to it: the
+ * version does not validate until that step is paired with an approval gate or a
+ * rollback. An editor that only reported this would be technically correct and useless —
+ * the author has just told it what they are doing, and the fix is mechanical.
+ *
+ * So the change comes with an offer, and the offer is one action. That is what makes the
+ * safety model feel like help rather than obstruction, which is the difference between a
+ * rule people follow and a rule people work around.
+ */
+export type RiskSuggestion = {
+    readonly kind: "none";
+    readonly why: string;
+} | {
+    readonly kind: "gate" | "rollback";
+    readonly why: string;
+    /** What accepting it does, in the author's words rather than the schema's. */
+    readonly action: string;
+};
+export declare function suggestForRisk(steps: readonly RawStep[], id: string, risk: NonNullable<RawStep["risk"]>): RiskSuggestion;
+/**
+ * Accept the offer, in one action.
+ *
+ * The rollback case inserts the undoing step as well as pointing at it, because "specify
+ * a rollback" with nothing to specify is not one action — it is an offer that hands back
+ * a second task.
+ */
+export declare function acceptRiskSuggestion(steps: readonly RawStep[], id: string, suggestion: RiskSuggestion): EditResult;
+/** Set a risk and, where it changes what the graph needs, say what would fix it. */
+export declare function setRisk(steps: readonly RawStep[], id: string, risk: NonNullable<RawStep["risk"]>): {
+    readonly result: EditResult;
+    readonly suggestion: RiskSuggestion;
+};