@runbooks/schema 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Conformance profiles, generated types, and content_hash.
+ * Implementation: tasks/v0/P-02-schema-package.md
+ */
+export declare const SCHEMA_VERSION: "v1";
+export { validate, createValidator } from "./validate.js";
+export * from "./served.js";
+export { checkInterpolations } from "./interpolation.js";
+export type { ValidationResult, ValidationError } from "./validate.js";
+export type Profile = "P0" | "P1" | "P2";
+export type RuntimeProfile = "R0" | "R1" | "R2";
+export type Risk = "read-only" | "reversible-write" | "destructive" | "irreversible";
+export type StepKind = "check" | "action" | "decision" | "wait" | "escalate";
+/**
+ * How a record got here (§15) — the four classes, in the order §15 lists them.
+ *
+ * Here rather than in a package that acts on them, for the reason `Risk` and `StepKind`
+ * are here: it is a vocabulary the schema defines and several packages read. It had been
+ * written out twice, in `@runbooks/lint` and `@runbooks/moderation`, and each grew its own
+ * table of what the classes mean. `vocabularies.test.ts` holds this list to the
+ * schema's own enum, so the two cannot drift apart silently either.
+ */
+export declare const CONTENT_CLASSES: readonly ["ingested", "adapted", "submitted", "curated"];
+export type ContentClass = (typeof CONTENT_CLASSES)[number];
+/**
+ * What the source a record came from says today (§3, §10).
+ *
+ * Another vocabulary the schema declares and several packages read, and another one that
+ * had been written out separately in each of them — once in the reindexer, once in the
+ * CLI's resolver, once in the site's record page. Three copies of a three-value union is
+ * how a fourth state ends up meaning one thing to the program that writes it and nothing
+ * at all to the two that read it.
+ */
+export declare const UPSTREAM_STATES: readonly ["current", "changed", "gone"];
+export type UpstreamState = (typeof UPSTREAM_STATES)[number];
+/** Risk levels ordered least to most dangerous. Order is load-bearing: a risk ceiling
+ *  is a comparison, and getting the order wrong permits what it means to forbid. */
+export declare const RISK_ORDER: readonly Risk[];
+/**
+ * A count and the noun that goes with it, chosen in code.
+ *
+ * "3 step(s)" is a programmer counting rather than a sentence. It was fixed on the catalog
+ * pages, then in the client components, and stayed on the third surface: the terminal, and
+ * the review sheet an operator opens in a browser. One home, so the fourth surface does not
+ * get its own version. An irregular noun gives its plural as the third argument.
+ */
+export declare function plural(count: number, singular: string, many?: string): string;
+export declare function riskAtMost(actual: Risk, ceiling: Risk): boolean;
+/** The two risk levels the spec treats as dangerous work. This is the line every
+ *  consequence is drawn from, so it is drawn once: RUNBOOK.md 12 forces
+ *  `requires_approval: true` on them regardless of what the source document says,
+ *  invariant 5 requires each one to be paired with a gate or a rollback, and the
+ *  catalog marks them wherever a reader can see a step without reading it. */
+export declare function isDangerous(risk: Risk): boolean;
+export * from "./capabilities.js";
+export * from "./stats.js";
+export * from "./hash.js";
+export type { RunbookP0 } from "./generated.js";

package/dist/index.js

@@ -0,0 +1,61 @@
+/**
+ * Conformance profiles, generated types, and content_hash.
+ * Implementation: tasks/v0/P-02-schema-package.md
+ */
+export const SCHEMA_VERSION = "v1";
+export { validate, createValidator } from "./validate.js";
+export * from "./served.js";
+export { checkInterpolations } from "./interpolation.js";
+/**
+ * How a record got here (§15) — the four classes, in the order §15 lists them.
+ *
+ * Here rather than in a package that acts on them, for the reason `Risk` and `StepKind`
+ * are here: it is a vocabulary the schema defines and several packages read. It had been
+ * written out twice, in `@runbooks/lint` and `@runbooks/moderation`, and each grew its own
+ * table of what the classes mean. `vocabularies.test.ts` holds this list to the
+ * schema's own enum, so the two cannot drift apart silently either.
+ */
+export const CONTENT_CLASSES = ["ingested", "adapted", "submitted", "curated"];
+/**
+ * What the source a record came from says today (§3, §10).
+ *
+ * Another vocabulary the schema declares and several packages read, and another one that
+ * had been written out separately in each of them — once in the reindexer, once in the
+ * CLI's resolver, once in the site's record page. Three copies of a three-value union is
+ * how a fourth state ends up meaning one thing to the program that writes it and nothing
+ * at all to the two that read it.
+ */
+export const UPSTREAM_STATES = ["current", "changed", "gone"];
+/** Risk levels ordered least to most dangerous. Order is load-bearing: a risk ceiling
+ *  is a comparison, and getting the order wrong permits what it means to forbid. */
+export const RISK_ORDER = [
+    "read-only",
+    "reversible-write",
+    "destructive",
+    "irreversible",
+];
+/**
+ * A count and the noun that goes with it, chosen in code.
+ *
+ * "3 step(s)" is a programmer counting rather than a sentence. It was fixed on the catalog
+ * pages, then in the client components, and stayed on the third surface: the terminal, and
+ * the review sheet an operator opens in a browser. One home, so the fourth surface does not
+ * get its own version. An irregular noun gives its plural as the third argument.
+ */
+export function plural(count, singular, many = `${singular}s`) {
+    return `${count} ${count === 1 ? singular : many}`;
+}
+export function riskAtMost(actual, ceiling) {
+    return RISK_ORDER.indexOf(actual) <= RISK_ORDER.indexOf(ceiling);
+}
+/** The two risk levels the spec treats as dangerous work. This is the line every
+ *  consequence is drawn from, so it is drawn once: RUNBOOK.md 12 forces
+ *  `requires_approval: true` on them regardless of what the source document says,
+ *  invariant 5 requires each one to be paired with a gate or a rollback, and the
+ *  catalog marks them wherever a reader can see a step without reading it. */
+export function isDangerous(risk) {
+    return risk === "destructive" || risk === "irreversible";
+}
+export * from "./capabilities.js";
+export * from "./stats.js";
+export * from "./hash.js";

package/dist/index.test.d.ts

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

package/dist/index.test.js

@@ -0,0 +1,236 @@
+import { describe, it, expect } from "vitest";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { RISK_ORDER, riskAtMost, isDangerous, plural } from "./index.js";
+function repoRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 8; i += 1) {
+        if (existsSync(join(dir, "pnpm-workspace.yaml")))
+            return dir;
+        dir = resolve(dir, "..");
+    }
+    throw new Error("repo root not found");
+}
+/**
+ * Every source in the workspace, walked once.
+ *
+ * Two sweeps below read the same tree for two different one-home rules, and a third will
+ * come. Reading it twice is how the second one quietly stops covering what the first does.
+ */
+const roots = ["packages", "apps"].map((dir) => join(repoRoot(), dir));
+const sources = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+        return ["node_modules", "dist", ".next", ".next-serve"].includes(entry.name)
+            ? []
+            : sources(full);
+    }
+    /*
+     * `.tsx` too, which for a long time it was not.
+     *
+     * Every sweep below walked `.ts` and stopped, so the forty-one files that are the
+     * pages and the client components — the surface a reader actually meets — were outside
+     * all of them. The plural rule was being broken in six of them while the sweep that
+     * guards it reported the tree clean.
+     */
+    const source = entry.name.endsWith(".ts") || entry.name.endsWith(".tsx");
+    return source && !entry.name.includes(".test.") ? [full] : [];
+});
+const allSources = roots.flatMap(sources);
+/** Every source but the one that defines the plural rule, which may quote what it forbids. */
+const written = allSources.filter((file) => !file.endsWith(join("schema", "src", "index.ts")));
+describe("risk ordering", () => {
+    it("is ordered least to most dangerous", () => {
+        expect(RISK_ORDER).toEqual([
+            "read-only",
+            "reversible-write",
+            "destructive",
+            "irreversible",
+        ]);
+    });
+    // The order is load-bearing: a risk ceiling is a comparison, and an inverted order
+    // permits exactly what it is meant to forbid.
+    it("lets a ceiling forbid everything above it", () => {
+        expect(riskAtMost("read-only", "reversible-write")).toBe(true);
+        expect(riskAtMost("destructive", "reversible-write")).toBe(false);
+        expect(riskAtMost("irreversible", "destructive")).toBe(false);
+    });
+    // RUNBOOK.md 12: forced on output regardless of what the source document says.
+    it("forces approval for destructive and irreversible only", () => {
+        expect(isDangerous("destructive")).toBe(true);
+        expect(isDangerous("irreversible")).toBe(true);
+        expect(isDangerous("reversible-write")).toBe(false);
+    });
+});
+/**
+ * The parenthetical plural, at its last surface (audit).
+ *
+ * "2 procedure(s)" was fixed on the catalog pages, then "step(s)" three times in the client
+ * components, and both sweeps read what those surfaces emit — the built HTML and the
+ * component sources. Twenty-four more were in the terminal, in the review sheet an operator
+ * opens in a browser, and in supervisor and linter messages, because no sweep read the
+ * sources that write them.
+ *
+ * `plural` is the one home. This is the sweep that keeps a fourth surface from inventing a
+ * fourth version of it: no source writes a count in parentheses, and the file that defines
+ * the rule may quote the shape it forbids.
+ */
+describe("nothing counts in parentheses", () => {
+    const files = written;
+    it("finds the sources by reading the tree, not a list kept here", () => {
+        expect(files.length).toBeGreaterThan(50);
+    });
+    it.each(files.map((file) => [file.slice(repoRoot().length + 1), file]))("%s writes its plurals out", (name, file) => {
+        const at = readFileSync(file, "utf8")
+            .split("\n")
+            .findIndex((line) => /[A-Za-z]\(s\)/.test(line));
+        expect(at, `${name}:${at + 1} counts in parentheses; use plural()`).toBe(-1);
+    });
+    /**
+     * And does not build one out of a ternary, which is the other way to write it by hand.
+     *
+     * This sweep forbade the string `(s)` — the spelling that was in front of whoever wrote
+     * it. Eight plurals were being assembled a different way in the meantime, six of them on
+     * pages: `${n} step${n === 1 ? "" : "s"}`, and once `capabilit${n === 1 ? "y" : "ies"}`.
+     * Every one of them is `plural()` with more characters and one more place to get an
+     * irregular noun wrong.
+     */
+    /**
+     * A ternary is a hand-made plural when its two branches are one noun and its plural —
+     * and only then.
+     *
+     * The first attempt matched any two quoted branches where one ended in `s`, and reported
+     * `? "was" : "were"` and `? "pass" : "allow"`: a verb agreeing with its subject, and an
+     * enum. Neither is `plural()`'s to fix, and a sweep that cries about them is one somebody
+     * turns off. So the two branches are compared as words: singular and singular + s, or
+     * -y and -ies, or the bare suffix.
+     */
+    const isPlural = (one, other) => other === `${one}s` ||
+        other === `${one}es` ||
+        (one.endsWith("y") && other === `${one.slice(0, -1)}ies`) ||
+        (one === "" && (other === "s" || other === "es"));
+    it.each(files.map((file) => [file.slice(repoRoot().length + 1), file]))("%s does not assemble a plural out of a ternary", (name, file) => {
+        const at = readFileSync(file, "utf8")
+            .split("\n")
+            .findIndex((line) => [...line.matchAll(/\?\s*"([a-z]*)"\s*:\s*"([a-z]*)"/g)].some((match) => isPlural(match[1], match[2]) || isPlural(match[2], match[1])));
+        expect(at, `${name}:${at + 1} builds a plural by hand; use plural()`).toBe(-1);
+    });
+});
+/**
+ * `median` is the one home too, and this is the sweep that keeps a seventh site from
+ * inventing a seventh version of it.
+ *
+ * There were six: two in the status page's metrics, two in the adaptation numbers, one in
+ * the takedown log and one inside the moderation queue's own `percentile`. Five picked the
+ * upper of the two middles and the sixth the lower, so `p50` and "median age" were one
+ * word for two different numbers — over an even count, which is why every test of each one
+ * passed.
+ *
+ * It reuses the walker above rather than carrying its own: a sweep against duplication
+ * that duplicates the sweep is an argument against itself.
+ */
+describe("nothing computes a middle by hand", () => {
+    const middles = allSources.filter((file) => !file.endsWith(join("schema", "src", "stats.ts")));
+    it.each(middles.map((file) => [file.slice(repoRoot().length + 1), file]))("%s asks for the middle rather than working one out", (name, file) => {
+        /*
+         * Halving a length, in any spelling.
+         *
+         * This matched `[Math.floor(x.length / 2)]` — square brackets and all — which is one
+         * of at least four ways to take a middle. `xs.at(Math.floor(xs.length / 2))`,
+         * `xs[(xs.length / 2) | 0]` and `xs.slice(Math.floor(xs.length / 2))[0]` all went
+         * straight past it; measured, by writing each into a source and watching the sweep
+         * stay green. What they have in common is not the brackets, it is dividing a length
+         * by two, so that is what is forbidden — along with `(n - 1) * p`, which is the
+         * percentile spelling the moderation queue used before there was one home for it.
+         *
+         * `stats.ts` is excluded because it is the home. Nothing else in the tree divides a
+         * length by two for any reason, so this costs no false positives; a geometric
+         * midpoint divides a width or a count, not the length of a list.
+         */
+        const at = readFileSync(file, "utf8")
+            .split("\n")
+            .map((line) => line.replace(/\/\/.*$/, ""))
+            .findIndex((line) => /\.length\s*(?:\/\s*2\b|\*\s*0\.5)|\(\s*\w+\.length\s*-\s*1\s*\)\s*\*/.test(line));
+        expect(at, `${name}:${at + 1} works out a middle by hand; use median() or percentile()`).toBe(-1);
+    });
+});
+/**
+ * A third rule with one home, guarded from the same walk.
+ *
+ * `isUntrusted` decides whether a step body is data or instructions (§12), and it lived
+ * twice: `packages/lint` derives it from the ladder, `apps/web` enumerated it as T0 or T1.
+ * They agreed over the five levels that exist and would have parted over a sixth — with
+ * the enumerated one calling an unknown low level trusted, which is the wrong direction
+ * for this particular question. The web copy was called by nothing but its own test.
+ *
+ * It lives beside the other two sweeps because they share the walk, not because the rule
+ * belongs to this package: the file that owns it is `packages/lint/src/trust.ts`.
+ */
+/**
+ * The schema version is written once, and `SCHEMA_VERSION` is where.
+ *
+ * The constant is the first line of this package and nothing used it. Six places in
+ * shipped code wrote `"v1"` into a document by hand — the build twice, the ingest
+ * pipeline, the supervisor's report, and both of the web app's exporters — so the version
+ * this catalog serves was a string repeated in six files and a constant nobody read.
+ *
+ * Only value positions. A type annotation has to be the literal (`readonly
+ * schema_version: "v1";`), and a semicolon is what tells them apart — checked against the
+ * tree before this was written, where it separated the two type positions from the
+ * sixteen value ones without a single wrong call.
+ *
+ * Fixtures are not swept. A test that builds a document with the version spelled out is
+ * saying what that document is, and pinning it to the constant would make the fixture
+ * follow the code it is meant to hold still.
+ */
+describe("the schema version has one home", () => {
+    const shipped = written.filter((file) => !file.includes(".test."));
+    it.each(shipped.map((file) => [file.slice(repoRoot().length + 1), file]))("%s asks for the version rather than spelling it", (name, file) => {
+        const at = readFileSync(file, "utf8")
+            .split("\n")
+            .map((line) => line.replace(/\/\/.*$/, ""))
+            .findIndex((line) => /schema_version:\s*"v\d+"\s*[,}]/.test(line));
+        expect(at, `${name}:${at + 1} writes the schema version out; use SCHEMA_VERSION`).toBe(-1);
+    });
+});
+describe("nothing decides trust for itself", () => {
+    const owner = join("lint", "src", "trust.ts");
+    const others = allSources.filter((file) => !file.endsWith(owner));
+    /** Comments say what the rule is; only code decides it. */
+    const code = (file) => readFileSync(file, "utf8")
+        .replace(/\/\*[\s\S]*?\*\//g, "")
+        .split("\n")
+        .map((line) => line.replace(/\/\/.*$/, ""));
+    it.each(others.map((file) => [file.slice(repoRoot().length + 1), file]))("%s does not define its own isUntrusted", (name, file) => {
+        const at = code(file).findIndex((line) => /(function|const)\s+isUntrusted\b/.test(line));
+        expect(at, `${name}:${at + 1} defines isUntrusted; import it from @runbooks/lint`).toBe(-1);
+    });
+    /**
+     * And does not spell the same rule out inline, which is where the first version of this
+     * sweep could not see it.
+     *
+     * That one forbade a function called `isUntrusted` and found one copy. Two more were
+     * sitting in plain sight as `!== "T0" && !== "T1"` — the listing filter that decides
+     * which records a reader sees, and the "At T2 or above" number on `/status` — because a
+     * check written against a name cannot see the rule written without one. A guard narrower
+     * than the rule it guards is the shape this repository keeps finding, and it found it
+     * here in its own guard.
+     */
+    it.each(others.map((file) => [file.slice(repoRoot().length + 1), file]))("%s asks the ladder rather than naming a level", (name, file) => {
+        const at = code(file).findIndex((line) => /[=!]==\s*"T[0-4]"/.test(line));
+        expect(at, `${name}:${at + 1} compares a trust level by name; ask isUntrusted or atLeast`).toBe(-1);
+    });
+});
+describe("a count and its noun", () => {
+    it("says one thing in the singular", () => {
+        expect(plural(1, "step")).toBe("1 step");
+    });
+    it("says none and many in the plural", () => {
+        expect(plural(0, "step")).toBe("0 steps");
+        expect(plural(3, "step")).toBe("3 steps");
+    });
+    it("takes an irregular plural when the noun has one", () => {
+        expect(plural(2, "entry", "entries")).toBe("2 entries");
+    });
+});

package/dist/interpolation.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Interpolation checking — semantic, not structural, so JSON Schema cannot express it:
+ * it compares strings inside `command` against the keys of `runbook.inputs`.
+ *
+ * Why it blocks rather than warns: a command interpolating an undeclared input produces
+ * an empty string at run time, and an empty string is how a scoped operation silently
+ * becomes an unscoped one. `--group ""` is not a narrower command than `--group prod`;
+ * it is a different one (RUNBOOK.md 5, 13.2).
+ */
+import type { ValidationError } from "./validate.js";
+export declare function checkInterpolations(doc: unknown): ValidationError[];

package/dist/interpolation.js

@@ -0,0 +1,34 @@
+const PLACEHOLDER = /\{\{\s*inputs\.([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/g;
+const ANY_PLACEHOLDER = /\{\{\s*([^}]+?)\s*\}\}/g;
+export function checkInterpolations(doc) {
+    const d = doc;
+    const declared = new Set(Object.keys(d.runbook?.inputs ?? {}));
+    const steps = d.runbook?.steps ?? [];
+    const errors = [];
+    steps.forEach((step, i) => {
+        if (typeof step?.command !== "string")
+            return;
+        const at = `/runbook/steps/${i}/command`;
+        for (const [, name] of step.command.matchAll(PLACEHOLDER)) {
+            if (name && !declared.has(name)) {
+                errors.push({
+                    path: at,
+                    message: `step ${step.id ?? i} interpolates {{inputs.${name}}}, which is not declared ` +
+                        `in runbook.inputs. Declare it, or remove the reference.`,
+                });
+            }
+        }
+        // Anything else in braces is not an input reference, and a supervisor has nothing
+        // to bind it to. Naming the expression is more useful than "invalid template".
+        for (const [, expr] of step.command.matchAll(ANY_PLACEHOLDER)) {
+            if (expr && !/^inputs\.[a-zA-Z_][a-zA-Z0-9_]*$/.test(expr.trim())) {
+                errors.push({
+                    path: at,
+                    message: `step ${step.id ?? i} interpolates {{${expr}}}; only {{inputs.<name>}} is ` +
+                        `defined. Nothing else has a value at run time.`,
+                });
+            }
+        }
+    });
+    return errors;
+}

package/dist/node.d.ts

@@ -0,0 +1,41 @@
+import type { ValidationResult } from "./validate.js";
+import type { Profile } from "./index.js";
+export type PublishedProfile = Extract<Profile, "P0" | "P1">;
+export declare function specSchemaDir(): string;
+export declare function loadSchema(profile: PublishedProfile): object;
+/**
+ * The attestation schema (S-05).
+ *
+ * Published and, until R-09, validated by nothing: the format existed and no code checked
+ * a statement against it before signing one. A signature over an unchecked document is a
+ * key behind a field nobody reviewed.
+ */
+export declare function loadAttestationSchema(): object;
+export declare function validateAttestation(statement: unknown): ValidationResult;
+/** The run report schema, and the CloudEvents envelope that carries one (S-06, §14). */
+export declare function loadRunReportSchema(): object;
+export declare function loadRunReportEnvelopeSchema(): object;
+/**
+ * Validate a report, or the envelope carrying one.
+ *
+ * Nothing in a report is checked semantically the way a runbook is: the whole design is
+ * that the schema is the check. A report that validates carries no free text, because
+ * there is nowhere in the schema for free text to go.
+ */
+export declare function validateRunReport(report: unknown): ValidationResult;
+export declare function validateRunReportEnvelope(event: unknown): ValidationResult;
+/**
+ * Schema validation plus the semantic checks that JSON Schema cannot express. Both are
+ * reported together because a caller does not care which layer rejected a document -
+ * it cares what to fix.
+ */
+export declare function validateProfile(doc: unknown, profile: PublishedProfile): ValidationResult;
+/**
+ * Which profile a document satisfies, highest first.
+ *
+ * A document is P1 when it validates as P1, P0 when it only validates as P0, and
+ * undefined when it is neither. Reported rather than assumed: a record claiming
+ * `profile: P1` with no steps is a claim, and the profile facet has to be the checked
+ * fact rather than the claim (§5).
+ */
+export declare function detectProfile(doc: unknown): PublishedProfile | undefined;

package/dist/node.js

@@ -0,0 +1,111 @@
+/**
+ * Node-only entry point: loading schemas from disk.
+ *
+ * Deliberately separate from `./validate.js`. Everything that touches the filesystem
+ * lives here so that packages depending on the pure half — supervise, graph — stay free
+ * of I/O and can be checked for it mechanically.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { validate } from "./validate.js";
+import { checkInterpolations } from "./interpolation.js";
+export function specSchemaDir() {
+    return specDir();
+}
+/**
+ * Where the schemas are, in both worlds this package lives in.
+ *
+ * Installed from a tarball there is one copy: the one `prepack` bundled, beside `dist`.
+ * In this repository there are two — that copy and the authored originals in `spec/v1` —
+ * and reading the bundled one here would be reading a snapshot of the schemas instead of
+ * the schemas. It happened the first time the copy existed: the generator regenerated
+ * `record.json` from a stale `p0.json` and wrote it into the package rather than the spec.
+ *
+ * So the repository wins where there is a repository, identified the way every other
+ * loader here identifies it, and the bundled copy is the fallback that makes the published
+ * package work at all.
+ */
+function specDir() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 8; i++) {
+        if (existsSync(join(dir, "pnpm-workspace.yaml"))) {
+            const authored = join(dir, "spec", "v1", "schema");
+            if (existsSync(authored))
+                return authored;
+        }
+        dir = resolve(dir, "..");
+    }
+    dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 8; i++) {
+        const candidate = join(dir, "spec", "v1", "schema");
+        if (existsSync(candidate))
+            return candidate;
+        dir = resolve(dir, "..");
+    }
+    throw new Error("spec/v1/schema not found above " + import.meta.url);
+}
+export function loadSchema(profile) {
+    return JSON.parse(readFileSync(join(specDir(), `${profile.toLowerCase()}.json`), "utf8"));
+}
+/**
+ * The attestation schema (S-05).
+ *
+ * Published and, until R-09, validated by nothing: the format existed and no code checked
+ * a statement against it before signing one. A signature over an unchecked document is a
+ * key behind a field nobody reviewed.
+ */
+export function loadAttestationSchema() {
+    return JSON.parse(readFileSync(join(specDir(), "attestation.json"), "utf8"));
+}
+export function validateAttestation(statement) {
+    return validate(statement, loadAttestationSchema());
+}
+/** The run report schema, and the CloudEvents envelope that carries one (S-06, §14). */
+export function loadRunReportSchema() {
+    return JSON.parse(readFileSync(join(specDir(), "run-report.json"), "utf8"));
+}
+export function loadRunReportEnvelopeSchema() {
+    return JSON.parse(readFileSync(join(specDir(), "run-report-envelope.json"), "utf8"));
+}
+/**
+ * Validate a report, or the envelope carrying one.
+ *
+ * Nothing in a report is checked semantically the way a runbook is: the whole design is
+ * that the schema is the check. A report that validates carries no free text, because
+ * there is nowhere in the schema for free text to go.
+ */
+export function validateRunReport(report) {
+    return validate(report, loadRunReportSchema());
+}
+export function validateRunReportEnvelope(event) {
+    return validate(event, loadRunReportEnvelopeSchema(), [loadRunReportSchema()]);
+}
+/**
+ * Schema validation plus the semantic checks that JSON Schema cannot express. Both are
+ * reported together because a caller does not care which layer rejected a document -
+ * it cares what to fix.
+ */
+export function validateProfile(doc, profile) {
+    // P1 refers to P0 by absolute $id, so P0 must be registered before P1 compiles.
+    const refs = profile === "P1" ? [loadSchema("P0")] : [];
+    const structural = validate(doc, loadSchema(profile), refs);
+    const semantic = profile === "P1" ? checkInterpolations(doc) : [];
+    const errors = [...structural.errors, ...semantic];
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Which profile a document satisfies, highest first.
+ *
+ * A document is P1 when it validates as P1, P0 when it only validates as P0, and
+ * undefined when it is neither. Reported rather than assumed: a record claiming
+ * `profile: P1` with no steps is a claim, and the profile facet has to be the checked
+ * fact rather than the claim (§5).
+ */
+export function detectProfile(doc) {
+    if (validateProfile(doc, "P1").valid)
+        return "P1";
+    if (validateProfile(doc, "P0").valid)
+        return "P0";
+    return undefined;
+}

package/dist/p1.test.d.ts

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

package/dist/p1.test.js

@@ -0,0 +1,87 @@
+import { describe, it, expect } from "vitest";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { validateProfile } from "./node.js";
+import { checkInterpolations } from "./interpolation.js";
+const FIXTURES = resolve(dirname(fileURLToPath(import.meta.url)), "..", "fixtures");
+function load(kind) {
+    const dir = join(FIXTURES, kind);
+    return readdirSync(dir).map((name) => ({
+        name,
+        doc: JSON.parse(readFileSync(join(dir, name), "utf8")),
+    }));
+}
+describe("P1 schema", () => {
+    it.each(load("p1-valid"))("accepts $name", ({ doc }) => {
+        const result = validateProfile(doc, "P1");
+        expect(result.errors).toEqual([]);
+        expect(result.valid).toBe(true);
+    });
+    it.each(load("p1-invalid"))("rejects $name", ({ doc }) => {
+        expect(doc.__expect, "fixture must state which rule it trips").toBeTypeOf("string");
+        expect(validateProfile(doc, "P1").valid).toBe(false);
+    });
+    // A P1 document is a P0 document with more in it. If that stopped being true, every
+    // facet, hub and search filter would need a second code path.
+    it.each(load("p1-valid"))("$name is also valid P0", ({ doc }) => {
+        expect(validateProfile(doc, "P0").valid).toBe(true);
+    });
+});
+describe("invariant 5 is structural, not advisory", () => {
+    const base = JSON.parse(readFileSync(join(FIXTURES, "p1-valid", "destructive-with-rollback.json"), "utf8"));
+    function withStep(step) {
+        return { ...base, runbook: { ...base.runbook, steps: [base.runbook.steps[0], step] } };
+    }
+    it("accepts a destructive action gated by approval", () => {
+        const doc = withStep({
+            id: "s2", kind: "action", title: "Drop the replication slot",
+            risk: "destructive", requires_approval: true,
+        });
+        expect(validateProfile(doc, "P1").valid).toBe(true);
+    });
+    it("accepts a destructive action paired with a rollback", () => {
+        const doc = withStep({
+            id: "s2", kind: "action", title: "Drop the replication slot",
+            risk: "destructive", rollback_ref: "s1",
+        });
+        expect(validateProfile(doc, "P1").valid).toBe(true);
+    });
+    // requires_approval: false on a destructive step is the case someone will eventually
+    // try. It must not satisfy the pairing rule.
+    it("refuses a destructive action that opts out of approval", () => {
+        const doc = withStep({
+            id: "s2", kind: "action", title: "Drop the replication slot",
+            risk: "destructive", requires_approval: false,
+        });
+        expect(validateProfile(doc, "P1").valid).toBe(false);
+    });
+    it("leaves reversible actions unpaired", () => {
+        const doc = withStep({
+            id: "s2", kind: "action", title: "Restart the consumer group",
+            risk: "reversible-write",
+        });
+        expect(validateProfile(doc, "P1").valid).toBe(true);
+    });
+});
+describe("interpolation", () => {
+    const doc = (inputs, command) => ({
+        runbook: { inputs, steps: [{ id: "s1", command }] },
+    });
+    it("accepts a declared input", () => {
+        expect(checkInterpolations(doc({ group: { type: "string" } }, "x --g {{inputs.group}}"))).toEqual([]);
+    });
+    it("names the undeclared input and what to do", () => {
+        const errors = checkInterpolations(doc({}, "x --g {{inputs.group}}"));
+        expect(errors).toHaveLength(1);
+        expect(errors[0].message).toContain("inputs.group");
+        expect(errors[0].message).toContain("Declare it");
+    });
+    it("rejects anything that is not an input reference", () => {
+        const errors = checkInterpolations(doc({}, "x --g {{env.GROUP}}"));
+        expect(errors.some((e) => e.message.includes("env.GROUP"))).toBe(true);
+    });
+    it("tolerates a step with no command", () => {
+        expect(checkInterpolations({ runbook: { steps: [{ id: "s1" }] } })).toEqual([]);
+    });
+});

package/dist/run-report.test.d.ts

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