@runbooks/schema 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,22 @@
+# `@runbooks/schema`
+
+The published runbook schemas, the content hash, capability parsing, and a validator that
+uses stock ajv with no custom keywords.
+
+**Tasks:** [S-01](../../tasks/v0/S-01-frontmatter-and-p0-schema.md),
+[S-02](../../tasks/v0/S-02-p1-step-schema.md),
+[P-14](../../tasks/v2/P-14-converter-package.md) (published) ·
+**Normative:** RUNBOOK.md §5, §9
+
+Stock ajv is the point: a published JSON Schema that only validates with our extensions is
+not a published schema. A third party checks conformance with any draft-2020-12 validator,
+and this package is a convenience rather than a requirement.
+
+The schemas travel with the package — `spec/v1/schema/*.json`, bundled at pack time from
+the one place they are authored. A validator installed without the documents it validates
+against is a function that throws on first use.
+
+`schema/record.json` is the shape of a record **as the catalog serves it**: the authored
+document plus what the build concluded. Validate what you fetch against that one; validate
+what you are about to submit against `p0.json` or `p1.json`, which forbid the fields the
+catalog assigns.

package/dist/agent-skills.test.d.ts

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

package/dist/agent-skills.test.js

@@ -0,0 +1,71 @@
+import { describe, it, expect } from "vitest";
+import { validateProfile } from "./node.js";
+/**
+ * S-01, acceptance criterion 1: a SKILL.md from a public Agent Skills catalog validates
+ * as P0 after adding only provenance fields, with no restructuring of its existing keys.
+ *
+ * This is the criterion the Q2 decision could most easily have broken. Namespacing our
+ * fields under `runbook` is only safe if the top level stays genuinely theirs — every
+ * key an Agent Skills document already carries, including ones neither specification
+ * has defined yet, must survive untouched.
+ */
+// Shaped like a real published skill: required keys plus extras we do not control.
+const publishedSkill = {
+    name: "kafka-consumer-group-stuck-restart",
+    description: "Restart a consumer group that has stopped advancing its offsets.",
+    version: "2.1.0",
+    license: "Apache-2.0",
+    author: "acme platform team",
+    metadata: { category: "ops" },
+    "allowed-tools": ["Bash"],
+};
+const provenance = {
+    runbook: {
+        schema_version: "v1",
+        profile: "P0",
+        domain: "data-pipelines",
+        targets: ["kafka"],
+        trigger: "alert",
+        execution: "human-with-agent",
+        risk: "reversible-write",
+        capabilities: ["cli:kafka-consumer-groups"],
+        publisher: "github:acme",
+        lang: "en",
+        license: "Apache-2.0",
+        source: {
+            url: "https://github.com/acme/skills/blob/HEAD/kafka.md",
+            fetched_at: "2026-09-02",
+            upstream_state: "current",
+        },
+    },
+};
+describe("Agent Skills superset (S-01 acceptance 1)", () => {
+    it("accepts a published skill once provenance is added", () => {
+        const result = validateProfile({ ...publishedSkill, ...provenance }, "P0");
+        expect(result.errors).toEqual([]);
+    });
+    it("leaves every original key untouched", () => {
+        const doc = { ...publishedSkill, ...provenance };
+        for (const [key, value] of Object.entries(publishedSkill)) {
+            expect(doc[key]).toEqual(value);
+        }
+    });
+    // The collision Q2 was decided to avoid. `license` at the top level is theirs and
+    // means whatever they say; `runbook.license` is ours and is the SPDX identifier the
+    // catalog filters on. Both coexist, which is the entire argument for one namespace
+    // key over flat fields.
+    it("lets an upstream key coexist with our field of the same name", () => {
+        const doc = {
+            ...publishedSkill,
+            license: "see LICENSE.txt",
+            ...provenance,
+        };
+        expect(validateProfile(doc, "P0").valid).toBe(true);
+        expect(doc.license).toBe("see LICENSE.txt");
+        expect(doc.runbook.license).toBe("Apache-2.0");
+    });
+    // Without provenance it is a skill, not a catalog record (RUNBOOK.md 10).
+    it("rejects the same skill with no provenance", () => {
+        expect(validateProfile(publishedSkill, "P0").valid).toBe(false);
+    });
+});

package/dist/capabilities.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Capability grammar, and extraction of the capabilities a shell command actually needs.
+ *
+ * This lives here, beside the grammar, because two consumers must agree on it exactly:
+ * the linter's capability/command consistency gate (P-06) and the supervisor's
+ * enforcement (R-02). A second parser would mean a document that passes T2 fails at run
+ * time — the catalog would be certifying something the runtime then refuses, which is
+ * worse than certifying nothing.
+ *
+ * Pure: no I/O, so the supervisor's tree stays auditable.
+ */
+export type CapabilityKind = "mcp" | "cli" | "iam";
+export interface Capability {
+    readonly kind: CapabilityKind;
+    readonly urn: string;
+    /** The server, binary or service the capability names. */
+    readonly name: string;
+}
+export declare function parseCapability(urn: string): Capability | undefined;
+export interface Extraction {
+    /** Capabilities the command demonstrably needs. */
+    readonly capabilities: readonly string[];
+    /**
+     * True when the command could not be parsed with confidence.
+     *
+     * A distinct outcome from "needs nothing", and deliberately so: a gate that treats
+     * "I could not tell" as "consistent" is decoration. R-02 blocks and reports; P-06
+     * warns that the step is unanalyzable.
+     */
+    readonly unanalyzable: boolean;
+    readonly reason?: string;
+}
+/**
+ * The capabilities a command needs, seen through the common wrappers.
+ *
+ * Conservative by design: an unrecognized shape is reported, never silently passed. A
+ * step whose command cannot be analysed is a step nobody has checked, and saying so is
+ * more useful than a clean result that means nothing.
+ */
+export declare function capabilitiesInCommand(command: string): Extraction;

package/dist/capabilities.js

@@ -0,0 +1,211 @@
+/**
+ * Capability grammar, and extraction of the capabilities a shell command actually needs.
+ *
+ * This lives here, beside the grammar, because two consumers must agree on it exactly:
+ * the linter's capability/command consistency gate (P-06) and the supervisor's
+ * enforcement (R-02). A second parser would mean a document that passes T2 fails at run
+ * time — the catalog would be certifying something the runtime then refuses, which is
+ * worse than certifying nothing.
+ *
+ * Pure: no I/O, so the supervisor's tree stays auditable.
+ */
+const CAPABILITY = /^(?:(mcp):([a-z0-9][a-z0-9-]*)|(cli):([a-z0-9][a-z0-9._-]*)|(iam):([a-z0-9-]+):([A-Za-z0-9*]+))$/;
+export function parseCapability(urn) {
+    const m = CAPABILITY.exec(urn);
+    if (!m)
+        return undefined;
+    if (m[1])
+        return { kind: "mcp", urn, name: m[2] };
+    if (m[3])
+        return { kind: "cli", urn, name: m[4] };
+    return { kind: "iam", urn, name: m[6] };
+}
+/** Wrappers that run another command rather than being the command. */
+const PASSTHROUGH = new Set(["sudo", "doas", "command", "nohup", "time", "nice", "ionice"]);
+/**
+ * Flags that consume the next token. Without this, `sudo -u postgres psql` attributes
+ * the command to `postgres` — the flag's argument — rather than to psql. Getting this
+ * wrong is not a cosmetic miss: it silently authorizes the wrong capability.
+ */
+const FLAGS_WITH_VALUE = {
+    sudo: new Set(["-u", "--user", "-g", "--group", "-p", "--prompt", "-h", "--host", "-C", "-r", "-t"]),
+    doas: new Set(["-u", "-C"]),
+    nice: new Set(["-n", "--adjustment"]),
+    ionice: new Set(["-c", "-n", "-p"]),
+};
+function skipFlags(tokens, from, wrapper) {
+    const takesValue = FLAGS_WITH_VALUE[wrapper] ?? new Set();
+    let i = from;
+    while (i < tokens.length && tokens[i].startsWith("-")) {
+        const flag = tokens[i];
+        i++;
+        // `--user=postgres` carries its value; `--user postgres` does not.
+        if (takesValue.has(flag) && !flag.includes("=") && i < tokens.length)
+            i++;
+    }
+    return i;
+}
+const DASH_C = new Set(["sh", "bash", "zsh", "dash", "ksh"]);
+const TAKES_COMMAND_ARG = new Set(["xargs", "watch", "timeout"]);
+/** Shell metacharacters we cannot reason about without a real parser. */
+const OPAQUE = /[`$(){}<>]/;
+/**
+ * The command with quoted content removed, so opacity is judged on shell syntax rather
+ * than on data.
+ *
+ * `psql -c "select f('x')"` is perfectly analysable — the parentheses are SQL, not a
+ * subshell — and flagging it would make the gate noise that gets ignored. Single quotes
+ * are literal, so their content goes entirely. Inside double quotes a shell still
+ * expands `$` and backticks, so those survive and everything else does not.
+ */
+function shellView(command) {
+    // `{{inputs.x}}` is our syntax, not the shell's, and by the time a command runs the
+    // supervisor has bound it to a literal (§13.2). Reading our own placeholders as shell
+    // grouping would make every parameterised command unanalysable.
+    command = command.replace(/\{\{[^}]*\}\}/g, "VALUE");
+    let out = "";
+    let quote;
+    for (const ch of command) {
+        if (!quote) {
+            if (ch === '"' || ch === "'") {
+                quote = ch;
+                continue;
+            }
+            out += ch;
+            continue;
+        }
+        if (ch === quote) {
+            quote = undefined;
+            continue;
+        }
+        // Inside double quotes only expansion is still shell; inside single quotes nothing is.
+        if (quote === '"' && (ch === "$" || ch === "`"))
+            out += ch;
+    }
+    return out;
+}
+function stripQuotes(token) {
+    const first = token[0];
+    if ((first === '"' || first === "'") && token.endsWith(first) && token.length > 1) {
+        return token.slice(1, -1);
+    }
+    return token;
+}
+function tokenize(command) {
+    // Deliberately simple: quotes and whitespace only. Anything richer is reported as
+    // unanalyzable rather than guessed at.
+    const out = [];
+    let current = "";
+    let quote;
+    for (const ch of command) {
+        if (quote) {
+            if (ch === quote)
+                quote = undefined;
+            else
+                current += ch;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            if (current)
+                out.push(current);
+            current = "";
+            continue;
+        }
+        current += ch;
+    }
+    if (current)
+        out.push(current);
+    return out;
+}
+/**
+ * The capabilities a command needs, seen through the common wrappers.
+ *
+ * Conservative by design: an unrecognized shape is reported, never silently passed. A
+ * step whose command cannot be analysed is a step nobody has checked, and saying so is
+ * more useful than a clean result that means nothing.
+ */
+export function capabilitiesInCommand(command) {
+    const trimmed = command.trim();
+    if (!trimmed)
+        return { capabilities: [], unanalyzable: false };
+    if (OPAQUE.test(shellView(trimmed))) {
+        return {
+            capabilities: [],
+            unanalyzable: true,
+            reason: "The command uses substitution or grouping, so what it invokes cannot be determined statically. Split it into steps, or name the tool explicitly.",
+        };
+    }
+    const segments = trimmed.split(/\s*(?:\|\||&&|[|;])\s*/).filter(Boolean);
+    const found = new Set();
+    let unanalyzable = false;
+    let reason;
+    for (const segment of segments) {
+        const tokens = tokenize(segment);
+        let i = 0;
+        // env-style leading assignments belong to the command, not to a binary.
+        while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i]))
+            i++;
+        if (tokens[i] === "env") {
+            i++;
+            while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i]))
+                i++;
+        }
+        while (i < tokens.length && PASSTHROUGH.has(tokens[i])) {
+            const wrapper = tokens[i];
+            i = skipFlags(tokens, i + 1, wrapper);
+        }
+        const head = tokens[i];
+        if (!head)
+            continue;
+        if (DASH_C.has(head)) {
+            const flag = tokens.indexOf("-c", i);
+            const inner = flag >= 0 ? tokens.slice(flag + 1).join(" ") : undefined;
+            if (!inner) {
+                unanalyzable = true;
+                reason = `A ${head} invocation with no -c argument reads a script this cannot see.`;
+                continue;
+            }
+            const nested = capabilitiesInCommand(stripQuotes(inner));
+            for (const c of nested.capabilities)
+                found.add(c);
+            if (nested.unanalyzable) {
+                unanalyzable = true;
+                reason = nested.reason;
+            }
+            continue;
+        }
+        if (TAKES_COMMAND_ARG.has(head)) {
+            let j = skipFlags(tokens, i + 1, head);
+            // `timeout 30s cmd` — skip a bare duration argument too.
+            if (head === "timeout" && j < tokens.length && /^\d+[smhd]?$/.test(tokens[j]))
+                j++;
+            const inner = tokens.slice(j).join(" ");
+            if (!inner)
+                continue;
+            const nested = capabilitiesInCommand(inner);
+            for (const c of nested.capabilities)
+                found.add(c);
+            if (nested.unanalyzable) {
+                unanalyzable = true;
+                reason = nested.reason;
+            }
+            continue;
+        }
+        const binary = head.split("/").pop();
+        if (!/^[a-z0-9][a-z0-9._-]*$/i.test(binary)) {
+            unanalyzable = true;
+            reason = `"${head}" does not look like a command this can attribute to a capability.`;
+            continue;
+        }
+        found.add(`cli:${binary.toLowerCase()}`);
+    }
+    return {
+        capabilities: [...found],
+        unanalyzable,
+        ...(reason ? { reason } : {}),
+    };
+}

package/dist/capabilities.test.d.ts

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

package/dist/capabilities.test.js

@@ -0,0 +1,119 @@
+import { describe, it, expect } from "vitest";
+import { parseCapability, capabilitiesInCommand } from "./capabilities.js";
+describe("capability grammar", () => {
+    it.each([
+        ["mcp:postgres", "mcp", "postgres"],
+        ["cli:kubectl", "cli", "kubectl"],
+        ["cli:kafka-consumer-groups", "cli", "kafka-consumer-groups"],
+        ["iam:s3:PutObject", "iam", "s3"],
+    ])("parses %s", (urn, kind, name) => {
+        expect(parseCapability(urn)).toMatchObject({ kind, name });
+    });
+    it.each(["postgres", "mcp:", "http:example.com", "MCP:Postgres"])("rejects %s", (urn) => expect(parseCapability(urn)).toBeUndefined());
+});
+/**
+ * R-02 requires this extraction to be the same code the linter uses. These cases are
+ * therefore the shared contract: if the two ever disagree about what a command needs, a
+ * document can pass T2 and be refused at run time, which is worse than certifying
+ * nothing.
+ */
+describe("what a command actually invokes", () => {
+    const needs = (cmd) => [...capabilitiesInCommand(cmd).capabilities].sort();
+    it("finds the plain binary", () => {
+        expect(needs("kubectl get pods")).toEqual(["cli:kubectl"]);
+    });
+    it("looks through sudo and env assignments", () => {
+        expect(needs("sudo -u postgres psql -c 'select 1'")).toEqual(["cli:psql"]);
+        expect(needs("PGPASSWORD=x psql -l")).toEqual(["cli:psql"]);
+        expect(needs("env FOO=1 kubectl get pods")).toEqual(["cli:kubectl"]);
+    });
+    it("looks inside sh -c", () => {
+        expect(needs("sh -c 'kubectl delete pod x'")).toEqual(["cli:kubectl"]);
+    });
+    it("finds every stage of a pipeline", () => {
+        expect(needs("kubectl get pods | grep Running")).toEqual(["cli:grep", "cli:kubectl"]);
+    });
+    it("follows && and ; as separate commands", () => {
+        expect(needs("kubectl drain node && psql -c 'x'")).toEqual(["cli:kubectl", "cli:psql"]);
+    });
+    it("looks past xargs and timeout", () => {
+        expect(needs("xargs -n1 kubectl delete pod")).toEqual(["cli:kubectl"]);
+        expect(needs("timeout 30s kubectl get pods")).toEqual(["cli:kubectl"]);
+    });
+    it("takes the binary out of a path", () => {
+        expect(needs("/usr/local/bin/kubectl get pods")).toEqual(["cli:kubectl"]);
+    });
+    // The conservative fallback. "I could not tell" must never look like "needs nothing":
+    // a step nobody could analyse is a step nobody has checked.
+    describe("unanalyzable rather than silently clean", () => {
+        it.each([
+            "kubectl delete pod $(kubectl get pods -o name)",
+            "eval `cat script.sh`",
+            "for p in a b; do kubectl delete pod $p; done",
+        ])("reports %s", (cmd) => {
+            const result = capabilitiesInCommand(cmd);
+            expect(result.unanalyzable).toBe(true);
+            expect(result.reason).toBeTypeOf("string");
+        });
+        it("is a different outcome from needing nothing", () => {
+            const empty = capabilitiesInCommand("");
+            expect(empty.unanalyzable).toBe(false);
+            expect(empty.capabilities).toEqual([]);
+        });
+    });
+});
+describe("flags that consume their next token", () => {
+    const needs = (cmd) => [...capabilitiesInCommand(cmd).capabilities].sort();
+    // Attributing a command to a flag's argument does not merely miss the real binary,
+    // it authorizes the wrong capability.
+    it.each([
+        ["sudo -u postgres psql -c 'select 1'", ["cli:psql"]],
+        ["sudo --user=postgres psql -l", ["cli:psql"]],
+        ["sudo -g ops -u deploy kubectl get pods", ["cli:kubectl"]],
+        ["nice -n 10 kubectl get pods", ["cli:kubectl"]],
+    ])("%s needs %j", (cmd, expected) => {
+        expect(needs(cmd)).toEqual(expected);
+    });
+});
+describe("quoted content is data, not shell syntax", () => {
+    const needs = (cmd) => [...capabilitiesInCommand(cmd).capabilities].sort();
+    // Flagging every SQL call as unanalysable would make the gate noise, and a noisy gate
+    // is one people learn to ignore.
+    it("reads a command whose argument contains parentheses", () => {
+        const command = `psql -tAc "select pg_drop_replication_slot('wal_keeper')"`;
+        expect(capabilitiesInCommand(command).unanalyzable).toBe(false);
+        expect(needs(command)).toEqual(["cli:psql"]);
+    });
+    it("reads a single-quoted argument containing anything at all", () => {
+        expect(needs(`psql -c 'select $(1); {x}'`)).toEqual(["cli:psql"]);
+    });
+    // A shell still expands these inside double quotes, so they remain opaque.
+    it("still refuses a substitution inside double quotes", () => {
+        expect(capabilitiesInCommand(`sh -c "kubectl delete pod $(id -u)"`).unanalyzable).toBe(true);
+        expect(capabilitiesInCommand('echo "`whoami`"').unanalyzable).toBe(true);
+    });
+    it("still refuses a substitution outside quotes", () => {
+        expect(capabilitiesInCommand("kubectl delete pod $(kubectl get pods -o name)").unanalyzable)
+            .toBe(true);
+    });
+});
+describe("an interpolation is a value, not shell syntax", () => {
+    const needs = (cmd) => [...capabilitiesInCommand(cmd).capabilities].sort();
+    // Reading our own placeholders as shell grouping would make every parameterised
+    // command unanalysable, which is most of the useful ones.
+    it("reads a command with a placeholder argument", () => {
+        expect(capabilitiesInCommand("df -h {{inputs.mount}}").unanalyzable).toBe(false);
+        expect(needs("df -h {{inputs.mount}}")).toEqual(["cli:df"]);
+    });
+    it("reads a placeholder inside a quoted argument", () => {
+        expect(needs(`psql -tAc "select active where name='{{inputs.slot}}'"`)).toEqual(["cli:psql"]);
+    });
+    // A placeholder may be an argument but not the command itself: if the binary is
+    // supplied at run time there is nothing to check against the manifest, and saying so
+    // is better than attributing the step to whatever the value happened to be.
+    it("refuses a command whose head is a placeholder", () => {
+        const result = capabilitiesInCommand("{{inputs.binary}} --flag");
+        expect(result.unanalyzable).toBe(true);
+        expect(result.capabilities).toEqual([]);
+    });
+});

package/dist/content-classes.test.d.ts

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

package/dist/content-classes.test.js

@@ -0,0 +1,77 @@
+/**
+ * The four content classes are one list (§15).
+ *
+ * They were written out three times: here as prose in the schema, in `@runbooks/lint` as a
+ * type beside a table of what each class means, and in `@runbooks/moderation` as a type
+ * beside a table of what the queue does about it. Three copies is two chances to disagree,
+ * and they had already taken one — the linter said a `curated` record does not auto-publish
+ * while the policy said silence may publish it, and nothing read the linter's copy, so the
+ * wrong one was also the invisible one.
+ *
+ * The names now live in this package with `Risk` and `StepKind`. What holds them to the
+ * schema itself is this file: an enum in `record.json` that gains a fifth value, or loses
+ * one, fails here rather than in whichever consumer meets the value first.
+ */
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONTENT_CLASSES, UPSTREAM_STATES } from "./index.js";
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+function enumIn(file, field = "content_class") {
+    const schema = JSON.parse(readFileSync(join(ROOT, "spec", "v1", "schema", file), "utf8"));
+    const found = [];
+    const walk = (node) => {
+        if (Array.isArray(node))
+            return node.forEach(walk);
+        if (typeof node !== "object" || node === null)
+            return;
+        for (const [key, value] of Object.entries(node)) {
+            if (key === field && typeof value === "object" && value !== null) {
+                const candidate = value.enum;
+                if (Array.isArray(candidate))
+                    found.push(...candidate);
+            }
+            walk(value);
+        }
+    };
+    walk(schema);
+    return found;
+}
+describe("the content class vocabulary", () => {
+    it.each(["record.json", "p0.json"])("matches the enum in %s", (file) => {
+        const declared = enumIn(file);
+        expect(declared.length, `${file} declares no content_class enum`).toBeGreaterThan(0);
+        expect([...declared].sort()).toEqual([...CONTENT_CLASSES].sort());
+    });
+    it("is in the order §15 lists them, least claimed first", () => {
+        expect(CONTENT_CLASSES).toEqual(["ingested", "adapted", "submitted", "curated"]);
+    });
+    /** The type is the list, so a class cannot be added to one and not the other. */
+    it("has a type that admits exactly these", () => {
+        const every = {
+            ingested: true,
+            adapted: true,
+            submitted: true,
+            curated: true,
+        };
+        expect(Object.keys(every).sort()).toEqual([...CONTENT_CLASSES].sort());
+    });
+});
+/**
+ * The same, for the state of the source a record came from.
+ *
+ * Written out three times — the reindexer that sets it, the resolver that warns on it, the
+ * page that shows it — and shared by none of them.
+ */
+describe("the upstream state vocabulary", () => {
+    it.each(["record.json", "p0.json"])("matches the enum in %s", (file) => {
+        const declared = enumIn(file, "upstream_state");
+        expect(declared.length, `${file} declares no upstream_state enum`).toBeGreaterThan(0);
+        expect([...declared].sort()).toEqual([...UPSTREAM_STATES].sort());
+    });
+    it("has a type that admits exactly these", () => {
+        const every = { current: true, changed: true, gone: true };
+        expect(Object.keys(every).sort()).toEqual([...UPSTREAM_STATES].sort());
+    });
+});

package/dist/generate.cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/generate.cli.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { writeFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { generateTypes } from "./generate.js";
+import { loadSchema, specSchemaDir } from "./node.js";
+import { servedSchema } from "./served.js";
+const source = generateTypes([
+    { name: "RunbookP0", schema: loadSchema("P0") },
+]);
+// Written to src/, not beside the compiled file: the generated types are source, and
+// checking them in is what lets CI notice when the schema moved and they did not.
+const out = join(dirname(fileURLToPath(import.meta.url)), "..", "src", "generated.ts");
+await writeFile(out, source, "utf8");
+process.stdout.write(`wrote ${out}\n`);
+/**
+ * The served-record schema, derived rather than written.
+ *
+ * The catalog publishes what a record must look like on the way in and serves something
+ * with the build's conclusions added. Both are legitimate; publishing only the first,
+ * while `/v1/runbooks/*.json` is the second, made "check conformance without our code"
+ * fail for anyone who tried it.
+ */
+const served = servedSchema(loadSchema("P0"), loadSchema("P1"));
+const servedOut = join(specSchemaDir(), "record.json");
+await writeFile(servedOut, `${JSON.stringify(served, null, 2)}\n`, "utf8");
+process.stdout.write(`wrote ${servedOut}\n`);

package/dist/generate.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Type generation from the published schemas.
+ *
+ * The failure this prevents: a hand-written interface drifting from the schema we
+ * publish, so the site renders a field the specification does not define — or stops
+ * rendering one it does. Types are generated, and a schema change without regeneration
+ * fails CI.
+ *
+ * Deliberately narrow rather than a general JSON Schema compiler. It understands exactly
+ * the constructs our schemas use and **throws on anything else**, so adding an
+ * unsupported construct breaks generation loudly instead of quietly producing a type
+ * that is wrong in a way nobody notices. A general library gets this backwards: it
+ * guesses, and a guess about a contract is worse than a failure to compile one.
+ */
+export interface JsonSchema {
+    $schema?: string;
+    $id?: string;
+    $defs?: Record<string, JsonSchema>;
+    $ref?: string;
+    title?: string;
+    description?: string;
+    type?: string;
+    enum?: unknown[];
+    const?: unknown;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    additionalProperties?: boolean | JsonSchema;
+    items?: JsonSchema;
+    allOf?: JsonSchema[];
+    anyOf?: JsonSchema[];
+    oneOf?: JsonSchema[];
+    not?: JsonSchema;
+    if?: JsonSchema;
+    then?: JsonSchema;
+    pattern?: string;
+    format?: string;
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    minItems?: number;
+    maxItems?: number;
+    minProperties?: number;
+    uniqueItems?: boolean;
+    default?: unknown;
+}
+export declare class UnsupportedConstruct extends Error {
+    constructor(construct: string, path: string);
+}
+export declare const GENERATED_BANNER = "/* eslint-disable */\n/**\n * GENERATED \u2014 do not edit.\n *\n * Run `pnpm --filter @runbooks/schema generate` after changing spec/v1/schema/*.json.\n * A schema change without regeneration fails CI: a hand-written type that has drifted\n * from the published schema is worse than no type, because it makes the drift invisible.\n */\n";
+export declare function generateTypes(schemas: {
+    name: string;
+    schema: JsonSchema;
+}[]): string;