@runbooks/graph 0.1.0

package/dist/edit.js

@@ -0,0 +1,299 @@
+import { isDangerous, plural } from "@runbooks/schema";
+export const STEP_KINDS = ["check", "action", "decision", "wait", "escalate"];
+/** The next free `sN`, so ids stay short and predictable rather than opaque. */
+export function nextId(steps) {
+    let n = steps.length + 1;
+    const taken = new Set(steps.map((step) => step.id));
+    while (taken.has(`s${n}`))
+        n += 1;
+    return `s${n}`;
+}
+/**
+ * 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 function addStep(steps, input) {
+    if (!STEP_KINDS.includes(input.kind)) {
+        return {
+            ok: false,
+            failure: {
+                code: "kind-required",
+                why: `A step needs one of ${STEP_KINDS.join(", ")}. There is no placeholder node: a node nobody has decided about ends up in a draft and then in a file.`,
+            },
+        };
+    }
+    const id = input.id ?? nextId(steps);
+    if (steps.some((step) => step.id === id)) {
+        return { ok: false, failure: { code: "duplicate-id", why: `${id} is already a step.` } };
+    }
+    const created = { id, kind: input.kind, title: input.title };
+    if (!input.after)
+        return { ok: true, steps: [...steps, created] };
+    const index = steps.findIndex((step) => step.id === input.after);
+    if (index < 0) {
+        return { ok: false, failure: { code: "unknown-step", why: `${input.after} is not a step.` } };
+    }
+    const previous = steps[index];
+    const inherited = previous.next;
+    return {
+        ok: true,
+        steps: [
+            ...steps.slice(0, index),
+            { ...previous, next: id },
+            ...(inherited ? [{ ...created, next: inherited }] : [created]),
+            ...steps.slice(index + 1),
+        ],
+    };
+}
+function referencesTo(steps, id) {
+    return steps
+        .filter((step) => step.next === id ||
+        step.on_fail === id ||
+        step.on_fail === `escalate:${id}` ||
+        step.rollback_ref === id ||
+        step.retry?.target === id ||
+        Object.values(step.branches ?? {}).includes(id))
+        .map((step) => step.id);
+}
+/** Re-point every reference to `from` at `to`, or remove it when `to` is undefined. */
+function repoint(step, from, to) {
+    const swap = (value) => {
+        if (value === undefined)
+            return undefined;
+        if (value === from)
+            return to;
+        if (value === `escalate:${from}`)
+            return to ? `escalate:${to}` : undefined;
+        return value;
+    };
+    const branches = step.branches
+        ? Object.fromEntries(Object.entries(step.branches)
+            .map(([label, target]) => [label, target === from ? to : target])
+            .filter((entry) => entry[1] !== undefined))
+        : undefined;
+    const next = { ...step };
+    const setOrDelete = (key, value) => {
+        if (value === undefined)
+            delete next[key];
+        else
+            next[key] = value;
+    };
+    setOrDelete("next", swap(step.next));
+    setOrDelete("on_fail", swap(step.on_fail));
+    setOrDelete("rollback_ref", swap(step.rollback_ref));
+    if (step.retry?.target === from) {
+        if (to)
+            next.retry = { ...step.retry, target: to };
+        else
+            delete next.retry;
+    }
+    if (branches)
+        next.branches = branches;
+    return next;
+}
+/**
+ * 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 function deleteStep(steps, id, options = {}) {
+    if (!steps.some((step) => step.id === id)) {
+        return { ok: false, failure: { code: "unknown-step", why: `${id} is not a step.` } };
+    }
+    const pointing = referencesTo(steps, id);
+    if (pointing.length > 0 && options.reconnectTo === undefined) {
+        return {
+            ok: false,
+            failure: {
+                code: "reconnect-required",
+                why: `${pointing.join(", ")} point at ${id}. Say where those edges go — another step, or "drop" — because a dangling edge does not exist here even in a draft.`,
+            },
+        };
+    }
+    if (options.reconnectTo &&
+        options.reconnectTo !== "drop" &&
+        !steps.some((step) => step.id === options.reconnectTo)) {
+        return {
+            ok: false,
+            failure: { code: "unknown-step", why: `${options.reconnectTo} is not a step to reconnect to.` },
+        };
+    }
+    const to = options.reconnectTo === "drop" || options.reconnectTo === undefined ? undefined : options.reconnectTo;
+    return {
+        ok: true,
+        steps: steps.filter((step) => step.id !== id).map((step) => repoint(step, id, to)),
+        ...(pointing.length > 0
+            ? {
+                note: to
+                    ? `${plural(pointing.length, "edge")} now point at ${to}.`
+                    : `${plural(pointing.length, "edge")} were removed with it.`,
+            }
+            : {}),
+    };
+}
+/**
+ * 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 const LEGAL_EDGES = {
+    check: ["next", "on_fail"],
+    action: ["next", "on_fail", "rollback"],
+    decision: ["branch"],
+    wait: ["next", "retry"],
+    escalate: [],
+};
+export function connect(steps, edge) {
+    const from = steps.find((step) => step.id === edge.from);
+    const to = steps.find((step) => step.id === edge.to);
+    if (!from)
+        return { ok: false, failure: { code: "unknown-step", why: `${edge.from} is not a step.` } };
+    if (!to && !edge.to.startsWith("end:")) {
+        return { ok: false, failure: { code: "unknown-step", why: `${edge.to} is not a step.` } };
+    }
+    const allowed = LEGAL_EDGES[from.kind];
+    if (!allowed.includes(edge.kind)) {
+        return {
+            ok: false,
+            failure: {
+                code: "illegal-edge",
+                why: `A ${from.kind} has no ${edge.kind} edge. It may have: ${allowed.join(", ") || "none — this is where a procedure hands off to a person"}.`,
+            },
+        };
+    }
+    if (edge.kind === "branch" && !edge.label) {
+        return {
+            ok: false,
+            failure: {
+                code: "illegal-edge",
+                why: "A branch needs a label. An unlabelled branch is a choice nobody reading the graph can make.",
+            },
+        };
+    }
+    const updated = { ...from };
+    if (edge.kind === "next")
+        updated.next = edge.to;
+    if (edge.kind === "on_fail")
+        updated.on_fail = edge.to;
+    if (edge.kind === "rollback")
+        updated.rollback_ref = edge.to;
+    if (edge.kind === "retry")
+        updated.retry = { ...(from.retry ?? {}), max: from.retry?.max ?? 3, target: edge.to };
+    if (edge.kind === "branch")
+        updated.branches = { ...(from.branches ?? {}), [edge.label]: edge.to };
+    return { ok: true, steps: steps.map((step) => (step.id === from.id ? updated : step)) };
+}
+export function begin(steps) {
+    return { past: [], present: steps, future: [] };
+}
+export function commit(history, steps) {
+    return { past: [...history.past, history.present], present: steps, future: [] };
+}
+export function undo(history) {
+    const previous = history.past.at(-1);
+    if (!previous)
+        return history;
+    return {
+        past: history.past.slice(0, -1),
+        present: previous,
+        future: [history.present, ...history.future],
+    };
+}
+export function redo(history) {
+    const [next, ...rest] = history.future;
+    if (!next)
+        return history;
+    return { past: [...history.past, history.present], present: next, future: rest };
+}
+export function suggestForRisk(steps, id, risk) {
+    const step = steps.find((candidate) => candidate.id === id);
+    if (!step)
+        return { kind: "none", why: `${id} is not a step.` };
+    if (!isDangerous(risk)) {
+        return { kind: "none", why: `${risk} needs no pairing: invariant 5 applies to destructive and irreversible work.` };
+    }
+    if (step.requires_approval || step.rollback_ref) {
+        return { kind: "none", why: `${id} is already paired with ${step.requires_approval ? "an approval gate" : "a rollback"}.` };
+    }
+    /**
+     * A gate for irreversible work, a rollback offered first for destructive.
+     *
+     * Undoing is better than asking where undoing is possible: a rollback restores the
+     * system, an approval only moves the decision to a person who may also be wrong at
+     * 3am. Where nothing can restore it — which is what irreversible means — a person is
+     * the only thing left.
+     */
+    if (risk === "irreversible") {
+        return {
+            kind: "gate",
+            why: `${id} is irreversible, so invariant 5 requires a pairing and a rollback cannot be one: nothing restores what cannot be undone.`,
+            action: "Add an approval gate before this step",
+        };
+    }
+    return {
+        kind: "rollback",
+        why: `${id} is destructive, so invariant 5 requires either a step that undoes it or a human decision before it.`,
+        action: "Add a step that undoes this one, and point at it",
+    };
+}
+/**
+ * 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 function acceptRiskSuggestion(steps, id, suggestion) {
+    const step = steps.find((candidate) => candidate.id === id);
+    if (!step)
+        return { ok: false, failure: { code: "unknown-step", why: `${id} is not a step.` } };
+    if (suggestion.kind === "none") {
+        return { ok: false, failure: { code: "illegal-edge", why: suggestion.why } };
+    }
+    if (suggestion.kind === "gate") {
+        return {
+            ok: true,
+            steps: steps.map((candidate) => candidate.id === id ? { ...candidate, requires_approval: true } : candidate),
+            note: `${id} now halts for a human decision before it runs.`,
+        };
+    }
+    const undoId = nextId(steps);
+    const undo = {
+        id: undoId,
+        kind: "action",
+        title: `Undo ${step.title.toLowerCase()}`,
+        risk: "reversible-write",
+        next: "end:aborted",
+    };
+    return {
+        ok: true,
+        steps: [
+            ...steps.map((candidate) => candidate.id === id ? { ...candidate, rollback_ref: undoId } : candidate),
+            undo,
+        ],
+        note: `${undoId} was added as the step that undoes ${id}. It needs a command before it is worth anything — a rollback nobody wrote is a rollback nobody can run.`,
+    };
+}
+/** Set a risk and, where it changes what the graph needs, say what would fix it. */
+export function setRisk(steps, id, risk) {
+    const step = steps.find((candidate) => candidate.id === id);
+    if (!step) {
+        return {
+            result: { ok: false, failure: { code: "unknown-step", why: `${id} is not a step.` } },
+            suggestion: { kind: "none", why: `${id} is not a step.` },
+        };
+    }
+    const updated = steps.map((candidate) => (candidate.id === id ? { ...candidate, risk } : candidate));
+    return { result: { ok: true, steps: updated }, suggestion: suggestForRisk(updated, id, risk) };
+}

package/dist/edit.test.d.ts

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

package/dist/edit.test.js

@@ -0,0 +1,231 @@
+import { describe, it, expect } from "vitest";
+import { toGraph } from "./model.js";
+import { addStep, deleteStep, connect, nextId, begin, commit, undo, redo, STEP_KINDS, LEGAL_EDGES, } from "./edit.js";
+const ok = (result) => {
+    if (!result.ok)
+        throw new Error(`expected success: ${result.failure.why}`);
+    return result.steps;
+};
+const base = [
+    { id: "s1", kind: "check", title: "Look", tool: "cli:df", expect: "there", on_fail: "s3", next: "s2" },
+    { id: "s2", kind: "action", title: "Fix", tool: "cli:rm", next: "end:success" },
+    { id: "s3", kind: "escalate", title: "Escalate", to: "team:x" },
+];
+/** §18.3 rule 2: a node cannot exist without a kind. There is no placeholder. */
+describe("a step is created with its kind or not at all", () => {
+    it("takes the kind as a parameter rather than setting it later", () => {
+        const steps = ok(addStep(base, { kind: "wait", title: "Wait for it" }));
+        expect(steps.at(-1).kind).toBe("wait");
+    });
+    it("refuses a kind that is not one of the five", () => {
+        const result = addStep(base, { kind: "placeholder", title: "Later" });
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.failure.why).toMatch(/There is no placeholder node/);
+    });
+    it("offers exactly the five kinds §5 defines", () => {
+        expect([...STEP_KINDS]).toEqual(["check", "action", "decision", "wait", "escalate"]);
+    });
+    it("gives a new step an unused id", () => {
+        expect(nextId(base)).toBe("s4");
+        expect(nextId([...base, { id: "s4", kind: "wait", title: "W" }])).toBe("s5");
+    });
+    it("inserts into a chain without leaving it pointing past the new step", () => {
+        const steps = ok(addStep(base, { kind: "check", title: "Confirm", after: "s1" }));
+        const first = steps.find((s) => s.id === "s1");
+        const inserted = steps.find((s) => s.id === first.next);
+        expect(inserted.title).toBe("Confirm");
+        expect(inserted.next).toBe("s2");
+    });
+});
+/** §18.3 rule 4: deletion requires reconnection. A dangling edge does not exist. */
+describe("deleting a step says where its edges go", () => {
+    it("refuses while something points at it", () => {
+        const result = deleteStep(base, "s2");
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.failure.code).toBe("reconnect-required");
+            expect(result.failure.why).toMatch(/does not exist here even in a draft/);
+        }
+    });
+    it("re-points the incoming edges when told where", () => {
+        const steps = ok(deleteStep(base, "s2", { reconnectTo: "s3" }));
+        expect(steps.find((s) => s.id === "s1").next).toBe("s3");
+        expect(steps.some((s) => s.id === "s2")).toBe(false);
+    });
+    it("removes them when told to drop them, rather than silently", () => {
+        const steps = ok(deleteStep(base, "s2", { reconnectTo: "drop" }));
+        expect(steps.find((s) => s.id === "s1").next).toBeUndefined();
+    });
+    it("re-points an escalate: reference, keeping the prefix the author wrote", () => {
+        const prefixed = base.map((step) => step.id === "s1" ? { ...step, on_fail: "escalate:s3" } : step);
+        const steps = ok(deleteStep(prefixed, "s3", { reconnectTo: "s2" }));
+        expect(steps.find((s) => s.id === "s1").on_fail).toBe("escalate:s2");
+    });
+    it("leaves a plain reference plain", () => {
+        const steps = ok(deleteStep(base, "s3", { reconnectTo: "s2" }));
+        expect(steps.find((s) => s.id === "s1").on_fail).toBe("s2");
+    });
+    it("deletes a step nothing points at without asking", () => {
+        const orphan = [...base, { id: "s9", kind: "wait", title: "Alone" }];
+        expect(ok(deleteStep(orphan, "s9")).some((s) => s.id === "s9")).toBe(false);
+    });
+    it("refuses to reconnect to a step that does not exist", () => {
+        expect(deleteStep(base, "s2", { reconnectTo: "s99" }).ok).toBe(false);
+    });
+});
+/** Only legal edge types between legal node types (§6, §18.3). */
+describe("edges are constrained by what the kinds mean", () => {
+    it.each([
+        ["check", "next", true],
+        ["check", "on_fail", true],
+        ["check", "rollback", false],
+        ["action", "rollback", true],
+        ["decision", "branch", true],
+        ["decision", "next", false],
+        ["wait", "retry", true],
+        ["escalate", "next", false],
+    ])("a %s may have a %s edge: %s", (kind, edge, allowed) => {
+        expect(LEGAL_EDGES[kind].includes(edge)).toBe(allowed);
+    });
+    it("says what an escalate is instead of listing nothing", () => {
+        const escalate = base.find((s) => s.id === "s3");
+        const result = connect(base, { from: escalate.id, to: "s1", kind: "next" });
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.failure.why).toMatch(/hands off to a person/);
+    });
+    it("refuses an unlabelled branch", () => {
+        const withDecision = ok(addStep(base, { kind: "decision", title: "Which way", id: "s4" }));
+        const result = connect(withDecision, { from: "s4", to: "s2", kind: "branch" });
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.failure.why).toMatch(/choice nobody reading the graph can make/);
+    });
+    it("accepts a labelled one", () => {
+        const withDecision = ok(addStep(base, { kind: "decision", title: "Which way", id: "s4" }));
+        const steps = ok(connect(withDecision, { from: "s4", to: "s2", kind: "branch", label: "yes" }));
+        expect(steps.find((s) => s.id === "s4").branches).toEqual({ yes: "s2" });
+    });
+    it("connects to a terminal without requiring it to be a step", () => {
+        expect(connect(base, { from: "s2", to: "end:failed", kind: "next" }).ok).toBe(true);
+    });
+    /** The editor may not draw an approval edge: the derivation adds those at every gate. */
+    it("offers no approval edge, since the derivation adds them", () => {
+        for (const kind of STEP_KINDS) {
+            expect(LEGAL_EDGES[kind]).not.toContain("approval");
+        }
+    });
+});
+/**
+ * W-10's first criterion, property-tested rather than clicked through: no sequence of
+ * operations reaches a dangling edge or a kindless node.
+ */
+describe("no sequence of operations reaches a broken draft", () => {
+    function randomSequence(seed) {
+        // A small deterministic PRNG, so a failure is reproducible from its seed.
+        let state = seed;
+        const random = () => ((state = (state * 1103515245 + 12345) % 2147483648) / 2147483648);
+        const pick = (items) => items[Math.floor(random() * items.length)];
+        let steps = [...base];
+        for (let i = 0; i < 40; i++) {
+            const roll = random();
+            if (roll < 0.4) {
+                const result = addStep(steps, {
+                    kind: pick(STEP_KINDS),
+                    title: `Step ${i}`,
+                    ...(steps.length > 0 && random() < 0.5 ? { after: pick(steps).id } : {}),
+                });
+                if (result.ok)
+                    steps = result.steps;
+            }
+            else if (roll < 0.7 && steps.length > 1) {
+                const victim = pick(steps);
+                const survivor = steps.find((s) => s.id !== victim.id);
+                const result = deleteStep(steps, victim.id, {
+                    reconnectTo: random() < 0.5 ? survivor.id : "drop",
+                });
+                if (result.ok)
+                    steps = result.steps;
+            }
+            else if (steps.length > 1) {
+                const from = pick(steps);
+                const to = pick(steps);
+                const result = connect(steps, {
+                    from: from.id,
+                    to: to.id,
+                    kind: pick(LEGAL_EDGES[from.kind].length > 0 ? LEGAL_EDGES[from.kind] : ["next"]),
+                    label: "branch-label",
+                });
+                if (result.ok)
+                    steps = result.steps;
+            }
+        }
+        return steps;
+    }
+    it.each([1, 7, 42, 1337, 90210, 5150, 271828, 31415])("seed %i leaves no broken step", (seed) => {
+        const steps = randomSequence(seed);
+        const ids = new Set(steps.map((step) => step.id));
+        for (const step of steps) {
+            expect(step.kind, `${step.id} has no kind`).toBeDefined();
+            expect(STEP_KINDS).toContain(step.kind);
+            expect(step.title.length).toBeGreaterThan(0);
+            const targets = [
+                step.next,
+                step.on_fail?.replace(/^escalate:/, ""),
+                step.rollback_ref,
+                step.retry?.target,
+                ...Object.values(step.branches ?? {}),
+            ].filter((target) => typeof target === "string");
+            for (const target of targets) {
+                if (target.startsWith("end:"))
+                    continue;
+                expect(ids.has(target), `${step.id} points at ${target}, which is not a step`).toBe(true);
+            }
+        }
+    });
+    it.each([3, 99, 2024])("seed %i still derives a graph", (seed) => {
+        const steps = randomSequence(seed);
+        expect(() => toGraph({ runbook: { steps } })).not.toThrow();
+    });
+});
+/**
+ * "Undo restores state exactly, including after an automatic insertion." A history of
+ * documents rather than of operations, because the inverse of "add a step" is not
+ * "delete a step" when adding one also inserted a gate.
+ */
+describe("undo and redo", () => {
+    it("restores the previous document exactly", () => {
+        const history = commit(begin(base), ok(addStep(base, { kind: "wait", title: "Wait" })));
+        expect(undo(history).present).toEqual(base);
+    });
+    it("restores it exactly after an insertion that changed two steps", () => {
+        const inserted = ok(addStep(base, { kind: "check", title: "Confirm", after: "s1" }));
+        expect(inserted.find((s) => s.id === "s1").next).not.toBe("s2");
+        expect(undo(commit(begin(base), inserted)).present).toEqual(base);
+    });
+    it("redoes what it undid", () => {
+        const changed = ok(addStep(base, { kind: "wait", title: "Wait" }));
+        const history = commit(begin(base), changed);
+        expect(redo(undo(history)).present).toEqual(changed);
+    });
+    it("does nothing at the ends rather than throwing", () => {
+        expect(undo(begin(base)).present).toEqual(base);
+        expect(redo(begin(base)).present).toEqual(base);
+    });
+    it("drops the redo stack once something new is done, as every editor does", () => {
+        const first = commit(begin(base), ok(addStep(base, { kind: "wait", title: "One" })));
+        const undone = undo(first);
+        const other = commit(undone, ok(addStep(base, { kind: "wait", title: "Two" })));
+        expect(other.future).toEqual([]);
+    });
+    it("survives a long session, holding each state rather than replaying operations", () => {
+        let history = begin(base);
+        for (let i = 0; i < 20; i++) {
+            history = commit(history, ok(addStep(history.present, { kind: "wait", title: `W${i}` })));
+        }
+        for (let i = 0; i < 20; i++)
+            history = undo(history);
+        expect(history.present).toEqual(base);
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Graph model, invariants, layout.
+ * Implementation: tasks/v0/P-07-graph-model-package.md, P-08-graph-layout.md
+ *
+ * No dependency on React, the DOM, or Node: this runs in the browser for the live
+ * editor and in the gate runner for linting.
+ */
+export * from "./model.js";
+export * from "./invariants.js";
+export * from "./layout.js";
+export * from "./paths.js";
+export * from "./edit.js";
+export * from "./simulate.js";
+export * from "./diff.js";
+export * from "./relations.js";
+export * from "./subgraph.js";

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * Graph model, invariants, layout.
+ * Implementation: tasks/v0/P-07-graph-model-package.md, P-08-graph-layout.md
+ *
+ * No dependency on React, the DOM, or Node: this runs in the browser for the live
+ * editor and in the gate runner for linting.
+ */
+export * from "./model.js";
+export * from "./invariants.js";
+export * from "./layout.js";
+export * from "./paths.js";
+export * from "./edit.js";
+export * from "./simulate.js";
+export * from "./diff.js";
+export * from "./relations.js";
+export * from "./subgraph.js";

package/dist/invariants.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The seven blocking invariants of RUNBOOK.md 6, plus the four warnings.
+ *
+ * These are the structural half of T1/T2 (section 8): the same rules the linter runs in
+ * CI, the editor runs on every idle keystroke, and the renderer assumes hold. Each
+ * returns the node or edge it failed on, so an error can highlight what is wrong rather
+ * than describing it.
+ *
+ * Messages follow section 18.7: name the location, name the fix, never "something went
+ * wrong". Every code resolves to a spec anchor (`/spec/v1/graph-model`), which is what
+ * lets an error message be short without being unhelpful.
+ */
+import type { Graph } from "./model.js";
+export type Severity = "error" | "warning";
+export interface GraphFinding {
+    readonly code: string;
+    readonly severity: Severity;
+    readonly message: string;
+    /** Node id, or `from->to` for an edge. */
+    readonly at: string;
+}
+/**
+ * What the document says about itself that a graph alone cannot: how it is meant to be run.
+ *
+ * The graph is the same shape whoever executes it. Some warnings are not — see the tool
+ * warning in `warnings` — so the caller passes what it knows rather than the check
+ * guessing, and a caller with only a graph gets the graph-only answers.
+ */
+export interface GraphContext {
+    readonly execution?: string;
+}
+export declare function checkGraph(g: Graph, context?: GraphContext): GraphFinding[];
+export declare function graphErrors(g: Graph, context?: GraphContext): GraphFinding[];