@runbooks/schema 0.1.0

package/dist/run-report.test.js

@@ -0,0 +1,145 @@
+import { describe, it, expect } from "vitest";
+import { loadRunReportSchema, loadRunReportEnvelopeSchema, validateRunReport, validateRunReportEnvelope, } from "./node.js";
+const report = {
+    report_schema: "runbook-run-report/v1",
+    schema_version: "v1",
+    runbook: "std/k8s-node-not-ready-drain",
+    version: "1.0.0",
+    content_hash: `sha256:${"a".repeat(64)}`,
+    profile: "P1",
+    outcome: "failed",
+    failed_step_id: "s4",
+    failure_class: "permission_denied",
+    executor_kind: "autonomous",
+    runtime_profile: "R2",
+    deviation_count: 2,
+    duration_bucket: "1-5m",
+    env_class: "staging",
+    reported_at: "2026-09-03",
+};
+describe("the normative form validates", () => {
+    it("accepts §14's example", () => {
+        expect(validateRunReport(report).valid).toBe(true);
+    });
+    it("accepts a success with no failure fields", () => {
+        const { failed_step_id: _s, failure_class: _c, ...ok } = report;
+        expect(validateRunReport({ ...ok, outcome: "success" }).valid).toBe(true);
+    });
+    /**
+     * A reporter cannot be required to have run an indexed version, and refusing those
+     * reports would silently exclude exactly the runs worth hearing about.
+     */
+    it("accepts a content hash the catalog has never seen", () => {
+        expect(validateRunReport({ ...report, content_hash: `sha256:${"f".repeat(64)}` }).valid).toBe(true);
+    });
+});
+/**
+ * The exclusions are the point of this schema. The pressure to add "just an error
+ * message field" is constant, and each such field is a secret leak waiting to happen.
+ */
+describe("nothing accepts free text", () => {
+    function walk(schema, path = "$") {
+        const found = [];
+        if (schema.type === "string" || (schema.type === undefined && (schema.pattern || schema.format))) {
+            found.push({ path, node: schema });
+        }
+        for (const [key, child] of Object.entries(schema.properties ?? {})) {
+            found.push(...walk(child, `${path}.${key}`));
+        }
+        for (const [key, child] of Object.entries(schema.$defs ?? {})) {
+            found.push(...walk(child, `${path}.$defs.${key}`));
+        }
+        if (schema.items)
+            found.push(...walk(schema.items, `${path}[]`));
+        return found;
+    }
+    function objects(schema, path = "$") {
+        if (schema === null || typeof schema !== "object")
+            return [];
+        const node = schema;
+        const found = [];
+        if (node["type"] === "object")
+            found.push({ path, node: node });
+        for (const [key, child] of Object.entries(node)) {
+            found.push(...objects(child, `${path}.${key}`));
+        }
+        return found;
+    }
+    it.each([
+        ["run-report.json", loadRunReportSchema()],
+        ["run-report-envelope.json", loadRunReportEnvelopeSchema()],
+    ])("%s constrains every string", (_name, schema) => {
+        for (const { path, node } of walk(schema)) {
+            const constrained = node.enum !== undefined || node.const !== undefined
+                || node.pattern !== undefined || node.format !== undefined;
+            expect(constrained, `${path} is an unconstrained string, which is a free-text field`).toBe(true);
+        }
+    });
+    it.each([
+        ["run-report.json", loadRunReportSchema()],
+        ["run-report-envelope.json", loadRunReportEnvelopeSchema()],
+    ])("%s closes every object", (_name, schema) => {
+        for (const { path, node } of objects(schema)) {
+            expect(node.additionalProperties, `${path} accepts undeclared fields`).toBe(false);
+        }
+    });
+    it("rejects a report carrying an error message", () => {
+        const result = validateRunReport({ ...report, error: "psql: FATAL: password authentication failed for user postgres" });
+        expect(result.valid).toBe(false);
+    });
+    it.each([
+        ["a precise duration", { duration: "3m14s" }],
+        ["a hostname", { host: "db-3.prod.internal" }],
+        ["a sender identity", { reporter: "acme-corp" }],
+        ["a region", { region: "eu-central-1" }],
+    ])("rejects %s", (_case, extra) => {
+        expect(validateRunReport({ ...report, ...extra }).valid).toBe(false);
+    });
+});
+describe("the closed vocabularies stay closed", () => {
+    it.each([
+        ["outcome", "mostly-worked"],
+        ["failure_class", "something_else"],
+        ["executor_kind", "cron"],
+        ["runtime_profile", "R3"],
+        ["duration_bucket", "2m"],
+        ["env_class", "prod-eu"],
+        ["profile", "P2"],
+    ])("rejects an unlisted %s", (field, value) => {
+        expect(validateRunReport({ ...report, [field]: value }).valid).toBe(false);
+    });
+    it("rejects a timestamp where a date belongs", () => {
+        expect(validateRunReport({ ...report, reported_at: "2026-09-03T14:22:07Z" }).valid).toBe(false);
+    });
+    it("requires a failure to name its class", () => {
+        const { failure_class: _c, ...unnamed } = report;
+        expect(validateRunReport(unnamed).valid).toBe(false);
+    });
+    it("refuses a failed step on a successful run", () => {
+        const { failure_class: _c, ...rest } = report;
+        expect(validateRunReport({ ...rest, outcome: "success" }).valid).toBe(false);
+    });
+});
+describe("the CloudEvents envelope", () => {
+    const event = {
+        specversion: "1.0",
+        type: "directory.runbooks.run-report.v1",
+        source: "urn:runbooks:hook",
+        id: "0b7f5f4e-9c2a-4a5b-8f1e-2d3c4b5a6978",
+        datacontenttype: "application/json",
+        data: report,
+    };
+    it("carries a valid report", () => {
+        expect(validateRunReportEnvelope(event).valid).toBe(true);
+    });
+    it("rejects an envelope whose data is not a valid report", () => {
+        expect(validateRunReportEnvelope({ ...event, data: { ...report, error: "boom" } }).valid).toBe(false);
+    });
+    it("keeps the source a kind of producer, not an installation", () => {
+        expect(validateRunReportEnvelope({ ...event, source: "https://runner.acme.internal" }).valid).toBe(false);
+    });
+    /** A precise emission time reintroduces the movement log that bucketing avoided. */
+    it("does not require a time, and refuses an undeclared one", () => {
+        expect(validateRunReportEnvelope({ ...event, time: "2026-09-03T14:22:07Z" }).valid).toBe(false);
+    });
+});

package/dist/served.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The schema of a record **as the catalog serves it** (P-12 audit, §5, §12).
+ *
+ * `p0.json` and `p1.json` describe a record as an author writes it: `trust` is forbidden
+ * there, because trust is computed and never declared, and so is anything else the
+ * catalog assigns. What `/v1/runbooks/{publisher}/{slug}.json` contains is that document
+ * **plus** what the build concluded about it — the id, the hash, the trust level with its
+ * evidence, and any signature verdict.
+ *
+ * Those are two different shapes, and the catalog was publishing the second while
+ * offering only the first as its schema. A third party validating what we serve against
+ * what we publish got "must NOT have additional properties" — which makes "a third party
+ * can check conformance without our code" false at exactly the point where it is being
+ * relied on.
+ *
+ * So this derives the served schema from the authored one rather than restating it: the
+ * fields the catalog assigns are lifted from forbidden to defined, everything else is
+ * whatever the authored schema says, and there is no second copy of the record's shape
+ * to keep in step.
+ */
+export interface SchemaObject {
+    [key: string]: unknown;
+}
+export declare const SERVED_SCHEMA_ID = "https://runbooks.directory/spec/v1/schema/record.json";
+/**
+ * What the catalog adds to a record on the way out, and nothing else may be added.
+ *
+ * Load-bearing rather than descriptive. It used to be neither: the constant said what the
+ * catalog assigns and `servedSchema` listed the same four fields again by hand, so the
+ * sentence "nothing else may be added" was a claim nothing could check and the two copies
+ * were free to drift. The schema below is built from this list, and a test asserts the
+ * served schema defines exactly these fields beyond the authored one.
+ */
+export declare const CATALOG_ASSIGNED: readonly ["trust", "trust_evidence", "signature", "attestations"];
+export type CatalogAssigned = (typeof CATALOG_ASSIGNED)[number];
+export declare function servedSchema(p0: SchemaObject, p1: SchemaObject): SchemaObject;

package/dist/served.js

@@ -0,0 +1,128 @@
+export const SERVED_SCHEMA_ID = "https://runbooks.directory/spec/v1/schema/record.json";
+/**
+ * What the catalog adds to a record on the way out, and nothing else may be added.
+ *
+ * Load-bearing rather than descriptive. It used to be neither: the constant said what the
+ * catalog assigns and `servedSchema` listed the same four fields again by hand, so the
+ * sentence "nothing else may be added" was a claim nothing could check and the two copies
+ * were free to drift. The schema below is built from this list, and a test asserts the
+ * served schema defines exactly these fields beyond the authored one.
+ */
+export const CATALOG_ASSIGNED = ["trust", "trust_evidence", "signature", "attestations"];
+const TRUST_EVIDENCE = {
+    type: "object",
+    required: ["level", "date", "issuer", "self_attested"],
+    additionalProperties: false,
+    description: "Why the level reads as it does (§18.5): a badge without a date and an issuer is a claim nobody can check.",
+    properties: {
+        level: { enum: ["T0", "T1", "T2", "T3", "T4"] },
+        date: { type: "string", format: "date" },
+        issuer: { type: "string" },
+        self_attested: { type: "boolean" },
+        /** Present for the levels that decay. Past it, this record is T2 (§8, P-13). */
+        expires_on: { type: "string", format: "date" },
+        reasons: { type: "array", items: { type: "string" } },
+    },
+};
+/**
+ * The evidence behind the badge (W-18).
+ *
+ * Forbidden in an authored document — "attestations are issued and verified, never
+ * self-declared" — and present on a served one, because that is where they reach a record
+ * from: the catalog, having checked them.
+ */
+const ATTESTATIONS = {
+    type: "array",
+    items: {
+        type: "object",
+        required: ["issuer", "issued_at", "content_hash", "status", "self_attested", "counts"],
+        additionalProperties: false,
+        properties: {
+            issuer: { type: "string" },
+            issued_at: { type: "string", format: "date" },
+            content_hash: { type: "string", pattern: "^sha256:[0-9a-f]{64}$" },
+            status: { enum: ["valid", "invalid", "unverifiable"] },
+            self_attested: { type: "boolean" },
+            /** Whether it contributes to the level today: expiry and issuer standing decide. */
+            counts: { type: "boolean" },
+            why: { type: "string" },
+        },
+    },
+};
+const SIGNATURE = {
+    type: "object",
+    required: ["status", "key_id"],
+    additionalProperties: false,
+    description: "What checking the publisher's signature concluded. `unverifiable` states are published as themselves: a signature nobody could check must not look like one that passed, nor like a record nobody signed.",
+    properties: {
+        status: { enum: ["valid", "invalid", "unknown-key", "revoked"] },
+        key_id: { type: "string" },
+        why: { type: "string" },
+    },
+};
+/**
+ * Derive the served schema from the authored ones.
+ *
+ * `p1.json` composes `p0.json` by `$ref`, and a `$ref` cannot relax an
+ * `additionalProperties: false` in the schema it refers to — so the P0 half is inlined
+ * and patched rather than referenced. That is the only reason this is a transform and not
+ * three lines of `allOf`.
+ */
+/** One fragment per assigned field. Keyed by the list, so a name with no shape fails to compile. */
+const ASSIGNED_SCHEMA = {
+    trust: {
+        enum: ["T0", "T1", "T2", "T3", "T4"],
+        description: "Computed by the catalog at build time from evidence plus a clock, never asserted by the record. Forbidden in an authored document (p0.json); present in every served one.",
+    },
+    trust_evidence: TRUST_EVIDENCE,
+    signature: SIGNATURE,
+    attestations: ATTESTATIONS,
+};
+export function servedSchema(p0, p1) {
+    const authored = structuredClone(p0);
+    const runbook = (authored["properties"]["runbook"] ?? {});
+    const properties = (runbook["properties"] ?? {});
+    // Computed, not declared — on the way in. On the way out they are the point. Added by
+    // walking CATALOG_ASSIGNED, so that list is what decides rather than what comments.
+    for (const field of CATALOG_ASSIGNED)
+        properties[field] = ASSIGNED_SCHEMA[field];
+    const required = new Set([...(runbook["required"] ?? []), "content_hash", "trust"]);
+    const steps = (p1["allOf"] ?? []).find((part) => part["properties"]?.["runbook"]?.["properties"] !== undefined);
+    return {
+        $schema: authored["$schema"],
+        $id: SERVED_SCHEMA_ID,
+        // P1's own definitions travel with the half that uses them: `#/$defs/step` resolves
+        // against the schema it is written in, and inlining the steps block without them
+        // would produce a schema that cannot compile.
+        $defs: p1["$defs"] ?? {},
+        title: "Runbook, as the catalog serves it",
+        description: "A published record: the authored document plus what the build concluded about it. Validate /v1/runbooks/{publisher}/{slug}.json against this; validate a document you are about to submit against p0.json or p1.json, which forbid the fields the catalog assigns.",
+        allOf: [
+            {
+                ...authored,
+                $id: undefined,
+                $schema: undefined,
+                properties: {
+                    ...authored["properties"],
+                    runbook: { ...runbook, properties, required: [...required] },
+                },
+            },
+            // A served P1 record still has to satisfy P1's own additions. A P0 record has no
+            // steps, so this half is applied conditionally rather than required outright.
+            steps
+                ? {
+                    // Typed at every level: ajv runs in strict mode here, which refuses a
+                    // `properties` without a `type` — a good rule, since a schema that forgets it
+                    // silently accepts a string where an object was meant.
+                    if: {
+                        type: "object",
+                        properties: {
+                            runbook: { type: "object", properties: { profile: { const: "P1" } } },
+                        },
+                    },
+                    then: steps,
+                }
+                : {},
+        ],
+    };
+}

package/dist/stats.d.ts

@@ -0,0 +1,17 @@
+/**
+ * One median, because there were two and they disagreed.
+ *
+ * Five places computed `sorted[Math.floor(n / 2)]` — the upper of the two middles for an
+ * even count — and the moderation queue computed the same statistic as
+ * `percentile(ages, 0.5)`, which is `sorted[Math.floor((n - 1) * 0.5)]`, the lower one.
+ * Over thirty records those are index 15 and index 14: two different published numbers for
+ * one word. They agree for every odd count, which is why nothing noticed.
+ *
+ * The convention here is nearest-rank on the upper side: the answer is always a value that
+ * actually occurred rather than the average of two that did not. For a duration in days or
+ * hours that matters — "2.5 days since the trust judgement" is a number no record has, and
+ * a reader who goes looking for it finds nothing.
+ */
+export declare function percentile(sorted: readonly number[], p: number): number | undefined;
+/** The middle value, upper of the two when the count is even. Undefined over nothing. */
+export declare function median(sorted: readonly number[]): number | undefined;

package/dist/stats.js

@@ -0,0 +1,23 @@
+/**
+ * One median, because there were two and they disagreed.
+ *
+ * Five places computed `sorted[Math.floor(n / 2)]` — the upper of the two middles for an
+ * even count — and the moderation queue computed the same statistic as
+ * `percentile(ages, 0.5)`, which is `sorted[Math.floor((n - 1) * 0.5)]`, the lower one.
+ * Over thirty records those are index 15 and index 14: two different published numbers for
+ * one word. They agree for every odd count, which is why nothing noticed.
+ *
+ * The convention here is nearest-rank on the upper side: the answer is always a value that
+ * actually occurred rather than the average of two that did not. For a duration in days or
+ * hours that matters — "2.5 days since the trust judgement" is a number no record has, and
+ * a reader who goes looking for it finds nothing.
+ */
+export function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return undefined;
+    return sorted[Math.min(sorted.length - 1, Math.max(0, Math.floor(sorted.length * p)))];
+}
+/** The middle value, upper of the two when the count is even. Undefined over nothing. */
+export function median(sorted) {
+    return percentile(sorted, 0.5);
+}

package/dist/stats.test.d.ts

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

package/dist/stats.test.js

@@ -0,0 +1,32 @@
+import { describe, it, expect } from "vitest";
+import { median, percentile } from "./stats.js";
+describe("one middle value", () => {
+    it("takes the upper of the two middles when the count is even", () => {
+        // The disagreement this exists to end. The two middles of this list are 20 and 30:
+        // `sorted[Math.floor(n / 2)]` answers 30 and `sorted[Math.floor((n - 1) * 0.5)]`
+        // answers 20, and both were in the repository, under one word.
+        expect(median([10, 20, 30, 40])).toBe(30);
+        expect(median([10, 20, 30, 40])).not.toBe(20);
+    });
+    it("takes the middle when the count is odd", () => {
+        expect(median([1, 2, 3])).toBe(2);
+        expect(median([5])).toBe(5);
+    });
+    it("has no answer over nothing, rather than zero", () => {
+        // Zero is a duration a caller would publish. Undefined is the caller's to turn into
+        // "not measured", which is what /status does with it.
+        expect(median([])).toBeUndefined();
+        expect(percentile([], 0.9)).toBeUndefined();
+    });
+    it("clamps at both ends", () => {
+        expect(percentile([1, 2, 3], 1)).toBe(3);
+        expect(percentile([1, 2, 3], 0)).toBe(1);
+    });
+    it("is the same statistic as the fiftieth percentile", () => {
+        // They were two functions and disagreed. A median that is not p50 is a bug in one of
+        // them, and which one it is cannot be decided by reading either.
+        for (const xs of [[1, 2], [1, 2, 3], [1, 2, 3, 4], [4, 4, 4, 9]]) {
+            expect(median(xs)).toBe(percentile(xs, 0.5));
+        }
+    });
+});

package/dist/validate.d.ts

@@ -0,0 +1,16 @@
+import type { ValidateFunction } from "ajv";
+export interface ValidationError {
+    /** JSON Pointer into the document, precise enough for the constructor to highlight a
+     *  node (tasks/v0/P-02-schema-package.md). */
+    readonly path: string;
+    readonly message: string;
+}
+export interface ValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly ValidationError[];
+}
+/** Compile once per `$id`: ajv registers a schema by its identifier, and a failed
+ *  compile still registers it — so a naive retry reports a duplicate and hides the
+ *  real error. */
+export declare function createValidator(schema: object, refs?: readonly object[]): ValidateFunction;
+export declare function validate(doc: unknown, schema: object, refs?: readonly object[]): ValidationResult;

package/dist/validate.js

@@ -0,0 +1,46 @@
+/**
+ * Schema validation — pure. Takes a schema object; never reads one.
+ *
+ * The split is load-bearing, not stylistic. `packages/supervise` must acquire no
+ * filesystem or network dependency anywhere in its tree (R-01), and `packages/graph`
+ * must run in a browser for the live editor (P-07). Both depend on this package, so a
+ * single `node:fs` import here would break them at a distance. Loading from disk lives
+ * in `./node.js`, which only Node consumers import.
+ *
+ * Stock ajv, no custom keywords: publishing a JSON Schema is pointless if conformance
+ * cannot be checked without our code (RUNBOOK.md G3).
+ */
+import Ajv2020 from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+const ajv = addFormats(new Ajv2020({ allErrors: true, strict: true }));
+const compiled = new Map();
+/** Compile once per `$id`: ajv registers a schema by its identifier, and a failed
+ *  compile still registers it — so a naive retry reports a duplicate and hides the
+ *  real error. */
+export function createValidator(schema, refs = []) {
+    for (const ref of refs) {
+        const refId = ref.$id;
+        if (refId && !ajv.getSchema(refId))
+            ajv.addSchema(ref);
+    }
+    const id = schema.$id;
+    if (!id)
+        return ajv.compile(schema);
+    let check = compiled.get(id);
+    if (!check) {
+        check = ajv.getSchema(id) ?? ajv.compile(schema);
+        compiled.set(id, check);
+    }
+    return check;
+}
+export function validate(doc, schema, refs = []) {
+    const check = createValidator(schema, refs);
+    const valid = check(doc);
+    return {
+        valid,
+        errors: (check.errors ?? []).map((e) => ({
+            path: e.instancePath || "/",
+            message: e.message ?? "invalid",
+        })),
+    };
+}

package/dist/validate.test.d.ts

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

package/dist/validate.test.js

@@ -0,0 +1,61 @@
+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 as validate } from "./node.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("P0 schema", () => {
+    /**
+     * Guards the guard.
+     *
+     * Both suites below are `it.each(load(...))`, and `it.each([])` registers no tests and
+     * reports success. An empty fixture directory would turn "the schema accepts every
+     * valid document and rejects every invalid one" — the claim the whole catalog's
+     * conformance rests on — into two sentences that checked nothing.
+     */
+    it("has fixtures on both sides to check against", () => {
+        expect(load("valid").length).toBeGreaterThan(0);
+        expect(load("invalid").length).toBeGreaterThan(0);
+    });
+    it.each(load("valid"))("accepts $name", ({ doc }) => {
+        const result = validate(doc, "P0");
+        expect(result.errors).toEqual([]);
+        expect(result.valid).toBe(true);
+    });
+    // Each invalid fixture carries __expect naming the rule it must trip, so a fixture
+    // that starts passing for the wrong reason is still a visible failure.
+    it.each(load("invalid"))("rejects $name", ({ doc }) => {
+        expect(doc.__expect, "fixture must state which rule it trips").toBeTypeOf("string");
+        expect(validate(doc, "P0").valid).toBe(false);
+    });
+});
+describe("rules that must not silently regress", () => {
+    const base = JSON.parse(readFileSync(join(FIXTURES, "valid", "minimal.json"), "utf8"));
+    it("refuses a document that asserts its own trust", () => {
+        const doc = { ...base, runbook: { ...base.runbook, trust: "T4" } };
+        expect(validate(doc, "P0").valid).toBe(false);
+    });
+    it("refuses provenance without upstream_state", () => {
+        const doc = {
+            ...base,
+            runbook: {
+                ...base.runbook,
+                source: { url: "https://example.com/r", fetched_at: "2026-09-02" },
+            },
+        };
+        expect(validate(doc, "P0").valid).toBe(false);
+    });
+    // The Q2 decision: our fields live under one namespace key, never flat alongside
+    // Agent Skills fields. A flat document is not a runbook document.
+    it("does not accept our fields at the top level", () => {
+        const { runbook, ...rest } = base;
+        expect(validate({ ...rest, ...runbook }, "P0").valid).toBe(false);
+    });
+});

package/dist/vocabularies.test.d.ts

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

package/dist/vocabularies.test.js

@@ -0,0 +1,77 @@
+/**
+ * The vocabularies the schema declares are one list each (§15, §3).
+ *
+ * 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 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/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@runbooks/schema",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "The published runbook schemas, and a validator that uses stock ajv.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    }
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/runbooks-directory/runbooks.directory"
+  },
+  "engines": {
+    "node": ">=20.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "spec"
+  ],
+  "runbooks": {
+    "schemaVersions": [
+      "v1"
+    ]
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run --passWithNoTests",
+    "lint": "eslint src",
+    "generate": "node dist/generate.cli.js"
+  }
+}