@runbooks/graph 0.1.0

package/dist/paths.test.js

@@ -0,0 +1,255 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { toGraph, START } from "./model.js";
+import { reachableFrom, unreachable, allPathsTo, successPaths } from "./paths.js";
+import { checkGraph } from "./invariants.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: "Which?", branches: { a: "s2", b: "s3", default: "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 retrying = toGraph(doc([
+    { id: "s1", kind: "check", title: "Settled", tool: "cli:test", expect: "settled", assert: { exit_code: 0 }, on_fail: "s2", next: "end:success" },
+    { id: "s2", kind: "wait", title: "Wait", duration: "5s", retry: { max: 2, target: "s1" }, next: "end:failed" },
+]));
+describe("what a graph can reach", () => {
+    it("reaches every node of a linear procedure from the start", () => {
+        expect(reachableFrom(linear)).toContain("s1");
+        expect(reachableFrom(linear)).toContain("s2");
+        expect(reachableFrom(linear)).toContain("s9");
+    });
+    it("reports nothing unreachable in a valid graph", () => {
+        expect(unreachable(linear)).toEqual([]);
+        expect(unreachable(branching)).toEqual([]);
+    });
+    it("names an orphan, which is what invariant 1 blocks on", () => {
+        const orphaned = toGraph(doc([
+            { id: "s1", kind: "action", title: "Only", tool: "cli:a", next: "end:success" },
+            { id: "s7", kind: "action", title: "Nobody points here", tool: "cli:b", next: "end:success" },
+        ]));
+        // s7 is reached by the fall-through the derivation adds, so orphan it explicitly.
+        const graph = { ...orphaned, edges: orphaned.edges.filter((e) => e.to !== "s7") };
+        expect(unreachable(graph)).toContain("s7");
+        expect(checkGraph(graph).some((f) => f.code === "graph/unreachable")).toBe(true);
+    });
+    it("starts from the start node by default", () => {
+        expect(reachableFrom(linear)[0]).toBe(START);
+    });
+});
+describe("every path to an ending", () => {
+    it("enumerates both branches of a decision", () => {
+        const paths = allPathsTo(branching);
+        expect(paths.length).toBeGreaterThanOrEqual(2);
+        expect(paths.some((path) => path.includes("s2"))).toBe(true);
+        expect(paths.some((path) => path.includes("s3"))).toBe(true);
+    });
+    it("ends every path at a terminal", () => {
+        for (const path of allPathsTo(branching)) {
+            expect(path.at(-1)).toMatch(/^__end_/);
+        }
+    });
+    /**
+     * A bounded retry means a node genuinely appears twice on a real run. A walk that
+     * refused to revisit anything would be simulating a different procedure.
+     */
+    it("lets a retried step appear twice", () => {
+        const paths = allPathsTo(retrying);
+        expect(paths.some((path) => path.filter((id) => id === "s1").length > 1)).toBe(true);
+    });
+    it("bounds the revisiting, so a cycle cannot run forever", () => {
+        for (const path of allPathsTo(retrying)) {
+            for (const id of new Set(path)) {
+                expect(path.filter((step) => step === id).length).toBeLessThanOrEqual(2);
+            }
+        }
+    });
+    it("takes a visit budget from the caller", () => {
+        const once = allPathsTo(retrying, START, { maxVisits: 1 });
+        for (const path of once) {
+            expect(path.filter((id) => id === "s1").length).toBe(1);
+        }
+    });
+    it("stops at a ceiling rather than hanging a caller on a wide graph", () => {
+        expect(allPathsTo(branching, START, { limit: 1 })).toHaveLength(1);
+    });
+    it("returns a path that ran out of edges, rather than nothing", () => {
+        const dangling = toGraph(doc([{ id: "s1", kind: "action", title: "Ends nowhere", tool: "cli:a" }]));
+        const stripped = { ...dangling, edges: dangling.edges.filter((e) => e.from !== "s1") };
+        expect(allPathsTo(stripped).some((path) => path.at(-1) === "s1")).toBe(true);
+    });
+});
+describe("the paths where nothing goes wrong", () => {
+    it("follows forward edges only", () => {
+        for (const path of successPaths(linear)) {
+            expect(path).not.toContain("s9");
+        }
+    });
+    it("keeps both sides of a decision, since choosing is not failing", () => {
+        const paths = successPaths(branching);
+        expect(paths.some((p) => p.includes("s2"))).toBe(true);
+        expect(paths.some((p) => p.includes("s3"))).toBe(true);
+    });
+    it("is deterministic, so a silhouette is stable across builds", () => {
+        expect(successPaths(branching)).toEqual(successPaths(branching));
+    });
+});
+/** §6 lists four warnings. Three are here; the fourth is the linter's. */
+describe("the warnings that lower trust without blocking", () => {
+    it("names an action with no tool", () => {
+        const graph = toGraph(doc([{ id: "s1", kind: "action", title: "Do the thing", next: "end:success" }]));
+        const found = checkGraph(graph).find((f) => f.code === "graph/step-without-tool");
+        expect(found?.at).toBe("s1");
+        expect(found?.severity).toBe("warning");
+    });
+    /**
+     * The consequences it names are a machine's, so it stops where the machine does.
+     *
+     * It fired on every action and check of all three `human-only` records — twenty steps
+     * doing exactly what they declared — and told each one that a supervisor had nothing to
+     * scope, on a procedure that declares no agent may run it. A warning that cannot be acted
+     * on is how a reader learns to skip the gate.
+     */
+    it("says nothing on a record no agent may run", () => {
+        const graph = toGraph(doc([{ id: "s1", kind: "action", title: "Do the thing", next: "end:success" }]));
+        expect(checkGraph(graph, { execution: "human-only" }).some((f) => f.code === "graph/step-without-tool")).toBe(false);
+    });
+    it.each(["human-with-agent", "agent-autonomous"])("still names it under %s", (execution) => {
+        const graph = toGraph(doc([{ id: "s1", kind: "action", title: "Do the thing", next: "end:success" }]));
+        expect(checkGraph(graph, { execution }).find((f) => f.code === "graph/step-without-tool")?.at).toBe("s1");
+    });
+    /** And the other §6 warnings are not suppressed with it. */
+    it("keeps the warnings that are not about a tool on a human-only record", () => {
+        const graph = toGraph(doc([
+            { id: "s1", kind: "decision", title: "Which way?", question: "Which?", branches: { a: "s2", default: "s2" } },
+            { id: "s2", kind: "check", title: "Look", next: "end:success" },
+        ]));
+        const codes = checkGraph(graph, { execution: "human-only" }).map((f) => f.code);
+        expect(codes.some((code) => code !== "graph/step-without-tool")).toBe(true);
+    });
+    it("says nothing about a wait or a decision, which have nothing to invoke", () => {
+        const graph = toGraph(doc([
+            { id: "s1", kind: "wait", title: "Wait", duration: "5s", next: "end:success" },
+        ]));
+        expect(checkGraph(graph).some((f) => f.code === "graph/step-without-tool")).toBe(false);
+    });
+    it("names a branch leading to a check with no expectation", () => {
+        const graph = toGraph(doc([
+            { id: "s1", kind: "decision", title: "Which", question: "Which?", branches: { a: "s2", default: "s2" } },
+            { id: "s2", kind: "check", title: "Did it work", tool: "cli:test", on_fail: "end:failed", next: "end:success" },
+        ]));
+        const found = checkGraph(graph).find((f) => f.code === "graph/branch-check-without-expect");
+        expect(found?.at).toBe("s2");
+        expect(found?.message).toMatch(/cannot tell whether it worked/);
+    });
+    it("says nothing when the check does state an expectation", () => {
+        const graph = toGraph(doc([
+            { id: "s1", kind: "decision", title: "Which", question: "Which?", branches: { a: "s2", default: "s2" } },
+            { id: "s2", kind: "check", title: "Did it work", tool: "cli:test", expect: "the marker is gone", on_fail: "end:failed", next: "end:success" },
+        ]));
+        expect(checkGraph(graph).some((f) => f.code === "graph/branch-check-without-expect")).toBe(false);
+    });
+    it("leaves the unused-capability warning to the linter, which can see capabilities", () => {
+        const source = new URL("./invariants.ts", import.meta.url);
+        expect(source.pathname.endsWith("invariants.ts")).toBe(true);
+        // The reason is written where somebody would look for the missing check.
+        expect(checkGraph(linear).some((f) => f.code === "capabilities/redundant")).toBe(false);
+    });
+});
+/**
+ * P-07's third criterion: the package runs in the browser for the live editor and in CI
+ * for the linter, so it may depend on neither React, the DOM, nor Node. Checked through
+ * the import graph rather than by reading, because the rule erodes through a transitive
+ * import nobody looked at — which is how `packages/supervise` is checked for the same
+ * kind of promise.
+ */
+describe("the model runs anywhere", () => {
+    const FORBIDDEN = /from\s+"(react|react-dom|node:[a-z/]+|fs|path|os|crypto)"/g;
+    /**
+     * Follows relative imports and steps into a workspace package's entry point, because
+     * the rule is about what ends up in the bundle rather than about this directory.
+     */
+    function reachable(entry) {
+        const seen = new Map();
+        const queue = [entry];
+        while (queue.length > 0) {
+            const file = queue.pop();
+            if (seen.has(file) || !existsSync(file))
+                continue;
+            const source = readFileSync(file, "utf8");
+            seen.set(file, [...source.matchAll(FORBIDDEN)].map((m) => m[1]));
+            for (const [, spec] of source.matchAll(/from\s+"(\.[^"]+)"/g)) {
+                queue.push(join(dirname(file), spec.replace(/\.js$/, ".ts")));
+            }
+            for (const [, pkg] of source.matchAll(/from\s+"@runbooks\/([a-z-]+)"/g)) {
+                queue.push(join(here, "..", "..", pkg, "src", "index.ts"));
+            }
+        }
+        return seen;
+    }
+    const here = dirname(fileURLToPath(import.meta.url));
+    const modules = reachable(join(here, "index.ts"));
+    it("reaches more than its own entry point", () => {
+        expect(modules.size).toBeGreaterThan(3);
+    });
+    it("imports no React, no DOM and nothing Node-specific", () => {
+        const offenders = [...modules]
+            .filter(([, forbidden]) => forbidden.length > 0)
+            .map(([file, forbidden]) => `${file.slice(here.length + 1)} imports ${forbidden.join(", ")}`);
+        expect(offenders, "the editor runs this in a browser and the linter runs it in CI: one import breaks one of them").toEqual([]);
+    });
+    /**
+     * Only workspace packages, and each of those is checked for the same property by its
+     * own tests. A third-party dependency is where React or a Node built-in arrives
+     * without anybody choosing it.
+     */
+    it("depends on nothing outside the workspace", () => {
+        const manifest = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
+        for (const [name, range] of Object.entries(manifest.dependencies ?? {})) {
+            expect(name, `${name} is not a workspace package`).toMatch(/^@runbooks\//);
+            // `workspace:^0.1.0` on a package that is published (P-14): the protocol is still
+            // the workspace's, and pack resolves it to the version a consumer installs. What
+            // this test is about is that nothing here comes from outside the workspace.
+            expect(range, `${name} is not resolved from the workspace`).toMatch(/^workspace:/);
+        }
+    });
+});
+/**
+ * Found in audit: reachability was implemented twice — once here and once inside
+ * invariant 1 — and the file claimed consumers were built on it while having none. Two
+ * sweeps that agree today are one sweep and one bug waiting for somebody to change what
+ * counts as an edge.
+ */
+describe("reachability has one implementation", () => {
+    const src = dirname(fileURLToPath(import.meta.url));
+    it("is what invariant 1 uses", () => {
+        const source = readFileSync(join(src, "invariants.ts"), "utf8");
+        expect(source).toContain("reachableFrom(g, starts[0]!.id)");
+        // And no second sweep beside it.
+        expect(source).not.toMatch(/const queue = \[starts/);
+    });
+    it("agrees with what the invariant reports, by construction rather than by luck", () => {
+        const orphaned = toGraph(doc([
+            { id: "s1", kind: "action", title: "Only", tool: "cli:a", next: "end:success" },
+            { id: "s7", kind: "action", title: "Orphan", tool: "cli:b", next: "end:success" },
+        ]));
+        const graph = { ...orphaned, edges: orphaned.edges.filter((e) => e.to !== "s7") };
+        const fromPaths = unreachable(graph);
+        const fromInvariant = checkGraph(graph)
+            .filter((f) => f.code === "graph/unreachable")
+            .map((f) => f.at);
+        expect(fromPaths.sort()).toEqual(fromInvariant.sort());
+    });
+    it("says which consumers do not exist yet, rather than implying they do", () => {
+        const source = readFileSync(join(src, "paths.ts"), "utf8");
+        expect(source).toMatch(/The other consumers do not exist yet/);
+        expect(source.replace(/\s*\*\s*/g, " ")).toMatch(/exactly one caller and says so/);
+    });
+});

package/dist/relations.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Relations between runbooks (S-13, §22).
+ *
+ * v3's premise is that procedures compose: the graph stops being intra-runbook and becomes
+ * a graph of runbooks. Four kinds, and each asserts something different enough that the
+ * validation rules differ too.
+ *
+ * A relation is **authored**, unlike an attestation: only the author can say how their
+ * procedure stands to another. What they cannot do is make the claim resolve — a reference
+ * to a record this catalog does not hold is a broken record, not a pending one.
+ */
+import { type UpstreamState } from "@runbooks/schema";
+export declare const RELATION_KINDS: readonly ["requires", "rollback_of", "escalates_to", "part_of"];
+export type RelationKind = (typeof RELATION_KINDS)[number];
+export interface Relation {
+    readonly kind: RelationKind;
+    /** `publisher/slug`, optionally `@semver`. */
+    readonly ref: string;
+    readonly why?: string;
+    /**
+     * `part_of` only: the step of the parent this record expands (§18.6, W-21).
+     *
+     * Without it a decomposition is a claim of membership with no place in the parent's
+     * procedure, and a reader cannot tell which of twelve steps this is the detail of.
+     */
+    readonly step?: string;
+}
+export interface Reference {
+    readonly publisher: string;
+    readonly slug: string;
+    readonly semver?: string;
+}
+export declare function parseRef(ref: string): Reference | undefined;
+/**
+ * Which kinds must pin a version, and which must not.
+ *
+ * `requires` and `rollback_of` assert what *another record does* — it prepares this, it is
+ * undone by this — and that is only true of a version. An unpinned claim about behaviour
+ * follows the other author's next edit, which is exactly the update drift this catalog
+ * exists to expose rather than to inherit.
+ *
+ * `part_of` and `escalates_to` are structural: this belongs to that, failures go there.
+ * Pinning those freezes an arrangement in place, so that a playbook keeps pointing at
+ * last year's version of its own step, and the composition rots while every reference
+ * still resolves.
+ */
+export declare const MUST_PIN: Readonly<Record<RelationKind, boolean>>;
+/**
+ * Which kinds may cross a publisher boundary.
+ *
+ * All but `part_of`. Declaring yourself part of somebody else's procedure is a claim about
+ * *their* composition, made without them: the containing record decides what it contains.
+ * The rest are claims about your own record's relationship to theirs, which is yours to
+ * make — and to be wrong about in public.
+ */
+export declare const MAY_CROSS_PUBLISHER: Readonly<Record<RelationKind, boolean>>;
+export interface RelationProblem {
+    /** Which relation, so a finding points at the edge rather than at the document. */
+    readonly index: number;
+    readonly code: "relations/unparseable" | "relations/dangling" | "relations/must-pin" | "relations/must-not-pin" | "relations/cross-publisher" | "relations/self" | "relations/cycle";
+    readonly relation: Relation;
+    readonly message: string;
+}
+export interface Known {
+    /** `publisher/slug` of every record the catalog holds. */
+    readonly refs: ReadonlySet<string>;
+    /** Versions per `publisher/slug`, for checking a pin resolves. */
+    readonly versions: Readonly<Record<string, readonly string[]>>;
+    /** Step ids per record, so a `part_of` naming a step can be checked against it (W-21). */
+    readonly steps?: Readonly<Record<string, readonly string[]>>;
+}
+/**
+ * Check one record's relations.
+ *
+ * Every problem here is a blocking one. A relation that does not resolve is not a
+ * best-effort link: it is the record asserting a composition that cannot be assembled, and
+ * a reader following it arrives nowhere.
+ */
+export declare function checkRelations(self: {
+    readonly publisher: string;
+    readonly slug: string;
+    readonly relations?: readonly Relation[];
+}, known: Known): RelationProblem[];
+/**
+ * Cycles, across records.
+ *
+ * All four kinds must be acyclic, for reasons that differ by kind and agree in outcome. A
+ * `requires` cycle is a dependency nobody can satisfy first. A `part_of` cycle is a
+ * containment that contains itself. An `escalates_to` cycle is the failure mode it exists
+ * to prevent: a handoff loop where an incident circulates and nobody owns it. A
+ * `rollback_of` cycle says each of two procedures undoes the other, which is not a thing.
+ */
+export declare function relationCycles(records: readonly {
+    readonly ref: string;
+    readonly relations?: readonly Relation[];
+}[], kind: RelationKind): string[][];
+/**
+ * The trust of a composition: the weakest member's, and never better.
+ *
+ * Stated rather than left to intuition, because intuition here is optimistic. A playbook
+ * of a T4 and a T1 is a procedure that will run the T1 — the level of the thing you
+ * assembled cannot exceed the level of the part you did not check, and averaging would let
+ * one good member launder four bad ones.
+ */
+declare const TRUST_ORDER: readonly ["T0", "T1", "T2", "T3", "T4"];
+export type CompositionTrust = (typeof TRUST_ORDER)[number];
+export declare function compositionTrust(levels: readonly CompositionTrust[]): CompositionTrust;
+/**
+ * What a relation to a record whose upstream is gone means.
+ *
+ * Not a broken reference: the record is still here, still published, still what it was.
+ * What has gone is the source it was indexed from, and that is a fact about *its*
+ * provenance which the composition inherits rather than a fault in the relation. It is
+ * surfaced, and the composition's trust already reflects it — that member's own level fell
+ * when its upstream did.
+ */
+export declare function inheritsUpstream(state: string | undefined): UpstreamState | "unknown";
+export {};

package/dist/relations.js

@@ -0,0 +1,213 @@
+/**
+ * Relations between runbooks (S-13, §22).
+ *
+ * v3's premise is that procedures compose: the graph stops being intra-runbook and becomes
+ * a graph of runbooks. Four kinds, and each asserts something different enough that the
+ * validation rules differ too.
+ *
+ * A relation is **authored**, unlike an attestation: only the author can say how their
+ * procedure stands to another. What they cannot do is make the claim resolve — a reference
+ * to a record this catalog does not hold is a broken record, not a pending one.
+ */
+import { UPSTREAM_STATES } from "@runbooks/schema";
+export const RELATION_KINDS = ["requires", "rollback_of", "escalates_to", "part_of"];
+export function parseRef(ref) {
+    const match = /^([a-z0-9][a-z0-9-]*)\/([a-z0-9][a-z0-9-]*)(?:@(\d+\.\d+\.\d+))?$/.exec(ref);
+    if (!match)
+        return undefined;
+    return { publisher: match[1], slug: match[2], ...(match[3] ? { semver: match[3] } : {}) };
+}
+/**
+ * Which kinds must pin a version, and which must not.
+ *
+ * `requires` and `rollback_of` assert what *another record does* — it prepares this, it is
+ * undone by this — and that is only true of a version. An unpinned claim about behaviour
+ * follows the other author's next edit, which is exactly the update drift this catalog
+ * exists to expose rather than to inherit.
+ *
+ * `part_of` and `escalates_to` are structural: this belongs to that, failures go there.
+ * Pinning those freezes an arrangement in place, so that a playbook keeps pointing at
+ * last year's version of its own step, and the composition rots while every reference
+ * still resolves.
+ */
+export const MUST_PIN = {
+    requires: true,
+    rollback_of: true,
+    escalates_to: false,
+    part_of: false,
+};
+/**
+ * Which kinds may cross a publisher boundary.
+ *
+ * All but `part_of`. Declaring yourself part of somebody else's procedure is a claim about
+ * *their* composition, made without them: the containing record decides what it contains.
+ * The rest are claims about your own record's relationship to theirs, which is yours to
+ * make — and to be wrong about in public.
+ */
+export const MAY_CROSS_PUBLISHER = {
+    requires: true,
+    rollback_of: true,
+    escalates_to: true,
+    part_of: false,
+};
+/**
+ * Check one record's relations.
+ *
+ * Every problem here is a blocking one. A relation that does not resolve is not a
+ * best-effort link: it is the record asserting a composition that cannot be assembled, and
+ * a reader following it arrives nowhere.
+ */
+export function checkRelations(self, known) {
+    const problems = [];
+    (self.relations ?? []).forEach((relation, index) => {
+        const parsed = parseRef(relation.ref);
+        if (!parsed) {
+            problems.push({
+                index,
+                code: "relations/unparseable",
+                relation,
+                message: `${relation.ref} is not publisher/slug or publisher/slug@semver.`,
+            });
+            return;
+        }
+        const target = `${parsed.publisher}/${parsed.slug}`;
+        if (target === `${self.publisher}/${self.slug}`) {
+            problems.push({
+                index,
+                code: "relations/self",
+                relation,
+                message: `A record cannot ${relation.kind} itself. Whatever this was meant to say, it says nothing.`,
+            });
+            return;
+        }
+        if (MUST_PIN[relation.kind] && !parsed.semver) {
+            problems.push({
+                index,
+                code: "relations/must-pin",
+                relation,
+                message: `\`${relation.kind}\` asserts what ${target} does, which is only true of a version. Pin it: ${target}@<semver>.`,
+            });
+        }
+        if (!MUST_PIN[relation.kind] && parsed.semver) {
+            problems.push({
+                index,
+                code: "relations/must-not-pin",
+                relation,
+                message: `\`${relation.kind}\` is structural, and pinning it freezes the arrangement: the composition would keep pointing at ${parsed.semver} while ${target} moves on. Drop the version.`,
+            });
+        }
+        if (!MAY_CROSS_PUBLISHER[relation.kind] && parsed.publisher !== self.publisher) {
+            problems.push({
+                index,
+                code: "relations/cross-publisher",
+                relation,
+                message: `\`part_of\` is a claim about ${parsed.publisher}'s composition, and only they can make it. A record does not join somebody else's playbook by declaring that it has.`,
+            });
+        }
+        if (!known.refs.has(target)) {
+            problems.push({
+                index,
+                code: "relations/dangling",
+                relation,
+                message: `${target} is not a record this catalog holds. A relation to nothing is a composition that cannot be assembled, and a reader following it arrives nowhere.`,
+            });
+            return;
+        }
+        /**
+         * A `part_of` naming a step the parent does not have (W-21).
+         *
+         * Checked here because only the catalog can: the child cannot see the parent's steps,
+         * and an unchecked `step` would send a reader looking for the detail of a step that
+         * is not in the procedure.
+         */
+        if (relation.kind === "part_of" && relation.step && known.steps) {
+            const steps = known.steps[target];
+            if (steps && !steps.includes(relation.step)) {
+                problems.push({
+                    index,
+                    code: "relations/dangling",
+                    relation,
+                    message: `${target} has no step \`${relation.step}\`. A decomposition names the step it expands, and this one names something that is not in the parent: ${steps.join(", ") || "it has no steps"}.`,
+                });
+            }
+        }
+        if (parsed.semver && !(known.versions[target] ?? []).includes(parsed.semver)) {
+            problems.push({
+                index,
+                code: "relations/dangling",
+                relation,
+                message: `${target} exists and has no version ${parsed.semver}. Pin one it has: ${(known.versions[target] ?? []).join(", ") || "none published"}.`,
+            });
+        }
+    });
+    return problems;
+}
+/**
+ * Cycles, across records.
+ *
+ * All four kinds must be acyclic, for reasons that differ by kind and agree in outcome. A
+ * `requires` cycle is a dependency nobody can satisfy first. A `part_of` cycle is a
+ * containment that contains itself. An `escalates_to` cycle is the failure mode it exists
+ * to prevent: a handoff loop where an incident circulates and nobody owns it. A
+ * `rollback_of` cycle says each of two procedures undoes the other, which is not a thing.
+ */
+export function relationCycles(records, kind) {
+    const edges = new Map();
+    for (const record of records) {
+        const targets = (record.relations ?? [])
+            .filter((relation) => relation.kind === kind)
+            .map((relation) => parseRef(relation.ref))
+            .filter((parsed) => parsed !== undefined)
+            .map((parsed) => `${parsed.publisher}/${parsed.slug}`);
+        if (targets.length > 0)
+            edges.set(record.ref, targets);
+    }
+    const cycles = [];
+    const seen = new Set();
+    const walk = (node, path) => {
+        const at = path.indexOf(node);
+        if (at !== -1) {
+            cycles.push([...path.slice(at), node]);
+            return;
+        }
+        if (seen.has(node))
+            return;
+        seen.add(node);
+        for (const next of edges.get(node) ?? [])
+            walk(next, [...path, node]);
+    };
+    for (const record of records)
+        walk(record.ref, []);
+    return cycles;
+}
+/**
+ * The trust of a composition: the weakest member's, and never better.
+ *
+ * Stated rather than left to intuition, because intuition here is optimistic. A playbook
+ * of a T4 and a T1 is a procedure that will run the T1 — the level of the thing you
+ * assembled cannot exceed the level of the part you did not check, and averaging would let
+ * one good member launder four bad ones.
+ */
+const TRUST_ORDER = ["T0", "T1", "T2", "T3", "T4"];
+export function compositionTrust(levels) {
+    if (levels.length === 0)
+        return "T0";
+    return levels.reduce((weakest, level) => TRUST_ORDER.indexOf(level) < TRUST_ORDER.indexOf(weakest) ? level : weakest);
+}
+/**
+ * What a relation to a record whose upstream is gone means.
+ *
+ * Not a broken reference: the record is still here, still published, still what it was.
+ * What has gone is the source it was indexed from, and that is a fact about *its*
+ * provenance which the composition inherits rather than a fault in the relation. It is
+ * surfaced, and the composition's trust already reflects it — that member's own level fell
+ * when its upstream did.
+ */
+export function inheritsUpstream(state) {
+    // Membership, from the list that defines it. Spelled out, this says "these three are the
+    // states" a second time, and a fourth state would be read here as `unknown` — which is a
+    // composition quietly told the source is unknowable rather than that it moved.
+    return UPSTREAM_STATES.includes(state ?? "")
+        ? state
+        : "unknown";
+}

package/dist/relations.test.d.ts

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