@runbooks/schema 0.1.0

package/dist/generate.js

@@ -0,0 +1,133 @@
+/**
+ * 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 class UnsupportedConstruct extends Error {
+    constructor(construct, path) {
+        super(`The generator does not understand "${construct}" at ${path}. Teach it that construct rather than hand-writing the type: a hand-written type is exactly the drift this exists to prevent.`);
+        this.name = "UnsupportedConstruct";
+    }
+}
+/** Keywords that constrain values without changing their TypeScript type. */
+const IGNORED = new Set([
+    "$schema", "$id", "title", "description", "pattern", "format", "minLength",
+    "maxLength", "minimum", "maximum", "minItems", "maxItems", "minProperties",
+    "uniqueItems", "default", "required", "if", "then", "allOf", "examples",
+]);
+function literal(value) {
+    return typeof value === "string" ? JSON.stringify(value) : String(value);
+}
+function isForbidden(schema) {
+    // `{ not: {} }` matches nothing, which is how a forbidden property is written.
+    return schema.not !== undefined && Object.keys(schema.not).length === 0;
+}
+function typeOf(schema, path, indent) {
+    for (const key of Object.keys(schema)) {
+        if (IGNORED.has(key))
+            continue;
+        if (!["type", "enum", "const", "properties", "additionalProperties", "items", "not", "anyOf", "oneOf", "$defs", "$ref"].includes(key)) {
+            throw new UnsupportedConstruct(key, path);
+        }
+    }
+    if (schema.$ref) {
+        // Our only refs are same-document `#/$defs/...`, which the caller inlines.
+        throw new UnsupportedConstruct("$ref", path);
+    }
+    if (schema.const !== undefined)
+        return literal(schema.const);
+    if (schema.enum)
+        return schema.enum.map(literal).join(" | ");
+    if (schema.anyOf || schema.oneOf) {
+        return (schema.anyOf ?? schema.oneOf)
+            .map((s, i) => typeOf(s, `${path}/${i}`, indent))
+            .join(" | ");
+    }
+    switch (schema.type) {
+        case "string": return "string";
+        case "number":
+        case "integer": return "number";
+        case "boolean": return "boolean";
+        case "array": return `${typeOf(schema.items ?? {}, `${path}/items`, indent)}[]`;
+        case "object": return objectType(schema, path, indent);
+        case undefined: return "unknown";
+        default: throw new UnsupportedConstruct(`type: ${schema.type}`, path);
+    }
+}
+function objectType(schema, path, indent) {
+    const inner = `${indent}  `;
+    const required = new Set(schema.required ?? []);
+    const lines = [];
+    for (const [name, property] of Object.entries(schema.properties ?? {})) {
+        if (isForbidden(property)) {
+            lines.push(`${inner}/** Forbidden by the schema. ${property.description ?? ""} */`);
+            lines.push(`${inner}${key(name)}?: never;`);
+            continue;
+        }
+        if (property.description) {
+            lines.push(`${inner}/** ${property.description.replace(/\s+/g, " ")} */`);
+        }
+        const optional = required.has(name) ? "" : "?";
+        lines.push(`${inner}${key(name)}${optional}: ${typeOf(property, `${path}/${name}`, inner)};`);
+    }
+    if (schema.additionalProperties !== false) {
+        const value = typeof schema.additionalProperties === "object"
+            ? typeOf(schema.additionalProperties, `${path}/additionalProperties`, inner)
+            : "unknown";
+        lines.push(`${inner}[key: string]: ${value} | undefined;`);
+    }
+    return lines.length === 0 ? "Record<string, never>" : `{\n${lines.join("\n")}\n${indent}}`;
+}
+function key(name) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+/** Inline same-document `$defs` refs, which is the only form our schemas use. */
+function inline(schema, defs) {
+    if (Array.isArray(schema))
+        return schema;
+    if (!schema || typeof schema !== "object")
+        return schema;
+    if (schema.$ref?.startsWith("#/$defs/")) {
+        const name = schema.$ref.slice("#/$defs/".length);
+        const target = defs[name];
+        if (!target)
+            throw new UnsupportedConstruct(`$ref to missing ${name}`, "#");
+        return inline(target, defs);
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(schema)) {
+        out[k] = Array.isArray(v)
+            ? v.map((x) => inline(x, defs))
+            : v && typeof v === "object"
+                ? inline(v, defs)
+                : v;
+    }
+    return out;
+}
+export const GENERATED_BANNER = `/* eslint-disable */
+/**
+ * GENERATED — do not edit.
+ *
+ * Run \`pnpm --filter @runbooks/schema generate\` after changing spec/v1/schema/*.json.
+ * A schema change without regeneration fails CI: a hand-written type that has drifted
+ * from the published schema is worse than no type, because it makes the drift invisible.
+ */
+`;
+export function generateTypes(schemas) {
+    const parts = schemas.map(({ name, schema }) => {
+        const resolved = inline(schema, schema.$defs ?? {});
+        const { $defs: _defs, ...withoutDefs } = resolved;
+        const body = typeOf(withoutDefs, `#${name}`, "");
+        return `export interface ${name} ${body}\n`;
+    });
+    return `${GENERATED_BANNER}\n${parts.join("\n")}`;
+}

package/dist/generate.test.d.ts

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

package/dist/generate.test.js

@@ -0,0 +1,85 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { generateTypes, UnsupportedConstruct } from "./generate.js";
+import { loadSchema, detectProfile } from "./node.js";
+const HERE = dirname(fileURLToPath(import.meta.url));
+/**
+ * P-02's acceptance, and the whole reason the generator exists: a schema change without
+ * regeneration fails CI. A hand-written type that has drifted from the published schema
+ * is worse than no type, because it makes the drift invisible.
+ */
+describe("types cannot drift from the schema", () => {
+    it("the checked-in types are what the current schema generates", () => {
+        const generated = generateTypes([
+            { name: "RunbookP0", schema: loadSchema("P0") },
+        ]);
+        const committed = readFileSync(join(HERE, "generated.ts"), "utf8");
+        expect(generated, "spec/v1/schema changed without regenerating: run pnpm --filter @runbooks/schema generate").toBe(committed);
+    });
+    it("carries the schema's own descriptions into the types", () => {
+        const committed = readFileSync(join(HERE, "generated.ts"), "utf8");
+        expect(committed).toContain("A privilege request, not a description");
+        expect(committed).toContain("GENERATED");
+    });
+    it("marks a forbidden property as never rather than omitting it", () => {
+        const committed = readFileSync(join(HERE, "generated.ts"), "utf8");
+        // A record may not assert its own trust (§8). Typing it `never` says so at the call
+        // site; omitting it would just make the field unknown.
+        expect(committed).toMatch(/trust\?: never/);
+    });
+});
+/**
+ * A general compiler guesses at a construct it does not know. A guess about a contract
+ * is worse than a failure to compile one, so this generator throws instead.
+ */
+describe("an unsupported construct fails loudly", () => {
+    it("throws rather than guessing", () => {
+        expect(() => generateTypes([{ name: "X", schema: { type: "object", propertyNames: { pattern: "^a" } } }])).toThrow(UnsupportedConstruct);
+    });
+    it("names the construct and says to teach the generator", () => {
+        try {
+            generateTypes([{ name: "X", schema: { type: "object", patternProperties: {} } }]);
+            expect.unreachable();
+        }
+        catch (error) {
+            expect(error.message).toContain("patternProperties");
+            expect(error.message).toMatch(/Teach it that construct/);
+        }
+    });
+});
+describe("profile detection reports the checked fact, not the claim", () => {
+    const base = {
+        name: "example-procedure",
+        description: "A procedure used to check profile detection.",
+        runbook: {
+            schema_version: "v1", profile: "P0", domain: "databases", targets: ["postgres"],
+            trigger: "alert", execution: "human-only", risk: "read-only", capabilities: [],
+            publisher: "std", lang: "en", license: "MIT",
+            source: { url: "https://example.com/r", fetched_at: "2026-09-03", upstream_state: "current" },
+        },
+    };
+    it("detects P0 for a prose record", () => {
+        expect(detectProfile(base)).toBe("P0");
+    });
+    it("detects P1 once there are steps", () => {
+        const p1 = {
+            ...base,
+            runbook: {
+                ...base.runbook,
+                profile: "P1",
+                steps: [{ id: "s1", kind: "action", title: "Do the thing", risk: "read-only", next: "end:success" }],
+            },
+        };
+        expect(detectProfile(p1)).toBe("P1");
+    });
+    // The facet has to be the checked fact: a record claiming P1 with no steps is a claim.
+    it("returns P0 for a record that claims P1 without steps", () => {
+        const claiming = { ...base, runbook: { ...base.runbook, profile: "P1" } };
+        expect(detectProfile(claiming)).toBe("P0");
+    });
+    it("returns undefined for something that is neither", () => {
+        expect(detectProfile({ name: "x" })).toBeUndefined();
+    });
+});

package/dist/generated.d.ts

@@ -0,0 +1,101 @@
+/**
+ * GENERATED — do not edit.
+ *
+ * Run `pnpm --filter @runbooks/schema generate` after changing spec/v1/schema/*.json.
+ * A schema change without regeneration fails CI: a hand-written type that has drifted
+ * from the published schema is worse than no type, because it makes the drift invisible.
+ */
+export interface RunbookP0 {
+    /** Agent Skills field. ASCII slug, never reused (§9). */
+    name: string;
+    /** Agent Skills field. What the procedure does and when to reach for it. */
+    description: string;
+    runbook: {
+        schema_version: "v1";
+        /** ULID assigned by the catalog. Immutable, survives renames (§9). Absent in an authored document. */
+        id?: string;
+        /** The version this snapshot is. Assigned by the catalog alongside `id` and `content_hash`; absent in an authored document, present in everything the catalog serves. */
+        semver?: string;
+        /** What this version is (RUNBOOK.md 9). Agent pins point at it and attestations bind to it. Computed over the document with this field and x-layout excluded, so it cannot be part of what it hashes. */
+        content_hash?: string;
+        profile: "P0" | "P1" | "P2";
+        /** Lowest client runtime profile permitted to follow this runbook (§13.3). A client refuses a document whose minimum exceeds what it enforces. */
+        min_runtime_profile?: "R0" | "R1" | "R2";
+        /** Closed list, changed only by RFC (§4). Navigation and URLs, not classification. */
+        domain: "incident-response" | "data-pipelines" | "llm-ops" | "agent-workflows" | "cloud-infra" | "databases" | "ci-cd" | "security";
+        targets: string[];
+        trigger: "alert" | "symptom" | "scheduled" | "manual" | "agent-invoked";
+        execution: "human-only" | "human-with-agent" | "agent-autonomous";
+        risk: "read-only" | "reversible-write" | "destructive" | "irreversible";
+        blast_radius?: "resource" | "service" | "cluster" | "tenant" | "global";
+        duration?: "<5m" | "5-30m" | ">30m";
+        /** A privilege request, not a description (§2). A client MUST check it against its own allowlist before execution (§12). */
+        capabilities: string[];
+        /** Version ranges per target, e.g. {"postgres": ">=14 <17"}. */
+        applies_to?: {
+            [key: string]: string | undefined;
+        };
+        /** Namespace (§7). Claimed, not granted, except `std` which is ours. */
+        publisher: string;
+        lang: string;
+        title_en?: string;
+        summary_en?: string;
+        translation_of?: string;
+        /** The catalog record this was adapted from, when the original is itself in the catalog. Attribution for an adaptation is its source (RUNBOOK.md 10.2), which every record carries; this is the edge that lets a reader see both and keeps deduplication from counting one procedure twice. Requiring it of an adaptation whose original is not in the catalog would be requiring a link to nothing. */
+        derived_from?: string;
+        /** How this record got here (RUNBOOK.md 15). `adapted` means the procedure derives from somebody else's document under a licence that allows it, whether a machine segmented it or a person rewrote it by hand. It is the one class with a rule of its own: it does not publish without a human confirming the step segmentation and the risk labelling, because an unreviewed machine adaptation is what that rule is guarding against. Its attribution is `source`, which is mandatory for every record. */
+        content_class?: "ingested" | "adapted" | "submitted" | "curated";
+        /** SPDX identifier. Mandatory: an undetectable licence means the record is not ingested at all (§10.2). */
+        license: string;
+        /** The pressure valve for anything that is not a facet: uncontrolled, unguaranteed, not filterable (§4). */
+        keywords?: string[];
+        /** Declared parameters. Interpolation may reference only these, and a missing required input aborts a run rather than interpolating empty (§5). */
+        inputs?: {
+            [key: string]: {
+                type: "string" | "number" | "boolean";
+                required?: boolean;
+                default?: unknown;
+                description?: string;
+                /** The value is a credential and is redacted wherever the run is shown to a human - an approval request above all (RUNBOOK.md 13, NG3). An approval channel is somewhere a secret should never arrive. */
+                secret?: boolean;
+            } | undefined;
+        };
+        /** Permitted but unconstrained at P0, which is prose. P1 requires it and constrains every item (spec/v1/schema/p1.json). It is declared here so that each profile is a strict superset of the one below: a P1 document must also be a valid P0 document, or every facet, hub and search filter would need a second code path. */
+        steps?: unknown[];
+        /** Provenance. A record without it does not validate (§10). */
+        source: {
+            url: string;
+            commit?: string;
+            fetched_at: string;
+            upstream_state: "current" | "changed" | "gone";
+            /** The hash of the upstream document as it was when this record was made. What a reindex compares against: without it, 'has upstream changed' can only be answered by re-deriving the record, and a derivation that differs for our own reasons would read as the source having moved. Never part of content_hash — noticing that a source moved is not a new version of this record. */
+            upstream_hash?: string;
+            /** When the upstream was last looked at, which is not when the record was made. A marker with no date is a claim about the present made at an unknown time. */
+            checked_at?: string;
+        };
+        /** Forbidden by the schema. Forbidden. Trust is computed from evidence plus a clock and is never asserted by a record (RUNBOOK.md 8). A document that declares its own trust is invalid, not merely ignored. */
+        trust?: never;
+        /** Forbidden by the schema. Forbidden. Attestations are issued and verified, never self-declared (RUNBOOK.md 8). They reach a record through the catalog, not through its frontmatter. */
+        attestations?: never;
+        /** Forbidden by the schema. Forbidden. There is no self-certification of any kind. See RUNBOOK.md 19 on why there is no score. */
+        profile_verified?: never;
+        /** Edges to other records (§22). A relation is authored: unlike an attestation, it is the author saying how this procedure stands to another, and only they can say it. Every reference must resolve to a record this catalog holds, or the record does not publish. */
+        relations?: {
+            /** requires: this cannot run until that one has. rollback_of: this undoes that one. escalates_to: when this hands off, it hands off to that one. part_of: this is a step of that larger procedure (§18.6's decomposition). */
+            kind: "requires" | "rollback_of" | "escalates_to" | "part_of";
+            /** publisher/slug, optionally pinned with @semver. `requires` and `rollback_of` must pin, because they assert what another record does and that is only true of a version. `part_of` and `escalates_to` must not, because they are structural and a pinned structure rots. */
+            ref: string;
+            /** One sentence for a reader. Optional, and the only free text in a relation. */
+            why?: string;
+            /** `part_of` only: the step of the parent this record expands (§18.6). Without it a decomposition is a claim of membership with no place in the parent's procedure, and a reader cannot tell which of twelve steps this is the detail of. */
+            step?: string;
+        }[];
+        /** Forbidden by the schema. Forbidden. The evidence for a trust level is what the catalog concluded while computing it (RUNBOOK.md 8, 18.5), so it arrives with the level and never from the document. Submit the record; the level and its evidence are added on the way out, and both are in schema/record.json. */
+        trust_evidence?: never;
+        /** Forbidden by the schema. Forbidden. A signature field in a served record is what checking the publisher's key concluded (RUNBOOK.md 8), not a claim the document makes about itself: a record that carried its own verdict would be asserting the one thing verification exists to decide. Sign the record with the publishing key instead. */
+        signature?: never;
+    };
+    /** The markdown body of the SKILL.md this record came from, carried so it participates in content_hash. Changing the prose of a procedure is a change to the procedure. */
+    body?: string;
+    [key: string]: unknown | undefined;
+}

package/dist/generated.js

@@ -0,0 +1,9 @@
+/* eslint-disable */
+/**
+ * GENERATED — do not edit.
+ *
+ * Run `pnpm --filter @runbooks/schema generate` after changing spec/v1/schema/*.json.
+ * A schema change without regeneration fails CI: a hand-written type that has drifted
+ * from the published schema is worse than no type, because it makes the drift invisible.
+ */
+export {};

package/dist/generated.ts

@@ -0,0 +1,82 @@
+/* eslint-disable */
+/**
+ * GENERATED — do not edit.
+ *
+ * Run `pnpm --filter @runbooks/schema generate` after changing spec/v1/schema/*.json.
+ * A schema change without regeneration fails CI: a hand-written type that has drifted
+ * from the published schema is worse than no type, because it makes the drift invisible.
+ */
+
+export interface RunbookP0 {
+  /** Agent Skills field. ASCII slug, never reused (§9). */
+  name: string;
+  /** Agent Skills field. What the procedure does and when to reach for it. */
+  description: string;
+  runbook: {
+    schema_version: "v1";
+    /** ULID assigned by the catalog. Immutable, survives renames (§9). Absent in an authored document. */
+    id?: string;
+    /** The version this snapshot is. Assigned by the catalog alongside `id` and `content_hash`; absent in an authored document, present in everything the catalog serves. */
+    semver?: string;
+    /** What this version is (RUNBOOK.md 9). Agent pins point at it and attestations bind to it. Computed over the document with this field and x-layout excluded, so it cannot be part of what it hashes. */
+    content_hash?: string;
+    profile: "P0" | "P1" | "P2";
+    /** Lowest client runtime profile permitted to follow this runbook (§13.3). A client refuses a document whose minimum exceeds what it enforces. */
+    min_runtime_profile?: "R0" | "R1" | "R2";
+    /** Closed list, changed only by RFC (§4). Navigation and URLs, not classification. */
+    domain: "incident-response" | "data-pipelines" | "llm-ops" | "agent-workflows" | "cloud-infra" | "databases" | "ci-cd" | "security";
+    targets: string[];
+    trigger: "alert" | "symptom" | "scheduled" | "manual" | "agent-invoked";
+    execution: "human-only" | "human-with-agent" | "agent-autonomous";
+    risk: "read-only" | "reversible-write" | "destructive" | "irreversible";
+    blast_radius?: "resource" | "service" | "cluster" | "tenant" | "global";
+    duration?: "<5m" | "5-30m" | ">30m";
+    /** A privilege request, not a description (§2). A client MUST check it against its own allowlist before execution (§12). */
+    capabilities: string[];
+    /** Version ranges per target, e.g. {"postgres": ">=14 <17"}. */
+    applies_to?: {
+      [key: string]: string | undefined;
+    };
+    /** Namespace (§7). Claimed, not granted, except `std` which is ours. */
+    publisher: string;
+    lang: string;
+    title_en?: string;
+    summary_en?: string;
+    translation_of?: string;
+    /** Set on an adaptation, pointing at the record it was lifted from (§10.2). Does not create a new Topic and does not dedup separately. */
+    derived_from?: string;
+    /** SPDX identifier. Mandatory: an undetectable licence means the record is not ingested at all (§10.2). */
+    license: string;
+    /** The pressure valve for anything that is not a facet: uncontrolled, unguaranteed, not filterable (§4). */
+    keywords?: string[];
+    /** Declared parameters. Interpolation may reference only these, and a missing required input aborts a run rather than interpolating empty (§5). */
+    inputs?: {
+      [key: string]: {
+        type: "string" | "number" | "boolean";
+        required?: boolean;
+        default?: unknown;
+        description?: string;
+        /** The value is a credential and is redacted wherever the run is shown to a human - an approval request above all (RUNBOOK.md 13, NG3). An approval channel is somewhere a secret should never arrive. */
+        secret?: boolean;
+      } | undefined;
+    };
+    /** Permitted but unconstrained at P0, which is prose. P1 requires it and constrains every item (spec/v1/schema/p1.json). It is declared here so that each profile is a strict superset of the one below: a P1 document must also be a valid P0 document, or every facet, hub and search filter would need a second code path. */
+    steps?: unknown[];
+    /** Provenance. A record without it does not validate (§10). */
+    source: {
+      url: string;
+      commit?: string;
+      fetched_at: string;
+      upstream_state: "current" | "changed" | "gone";
+    };
+    /** Forbidden by the schema. Forbidden. Trust is computed from evidence plus a clock and is never asserted by a record (RUNBOOK.md 8). A document that declares its own trust is invalid, not merely ignored. */
+    trust?: never;
+    /** Forbidden by the schema. Forbidden. Attestations are issued and verified, never self-declared (RUNBOOK.md 8). They reach a record through the catalog, not through its frontmatter. */
+    attestations?: never;
+    /** Forbidden by the schema. Forbidden. There is no self-certification of any kind. See RUNBOOK.md 19 on why there is no score. */
+    profile_verified?: never;
+  };
+  /** The markdown body of the SKILL.md this record came from, carried so it participates in content_hash. Changing the prose of a procedure is a change to the procedure. */
+  body?: string;
+  [key: string]: unknown | undefined;
+}

package/dist/hash.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `content_hash`: what a version *is*.
+ *
+ * Agent pins point at it, attestations bind to it, and the resolver refuses a document
+ * whose bytes do not match it. So the computation has to be reproducible by anyone,
+ * which means canonicalization is specified rather than incidental.
+ *
+ * Web Crypto, not `node:crypto`: this package is a dependency of the supervisor core and
+ * of the graph package, which runs in a browser for the live editor. A Node-only import
+ * here would break both at a distance.
+ */
+/**
+ * Key order, once, for every canonicalization this product has.
+ *
+ * By code point — which is what `jq -cS` emits, what Python's `sort_keys` and Go's
+ * `encoding/json` do, and what `spec/v1/signing.md` prints as the recipe a publisher signs
+ * with **without our code**. JavaScript's `<` compares UTF-16 code units instead, and the
+ * two disagree the moment a key above U+FFFF meets one in U+E000..U+FFFF: by code unit the
+ * astral key comes first, by code point it comes last. A publisher following the printed
+ * recipe would then produce bytes this product refuses to verify, which is the single
+ * failure a canonicalization exists to prevent.
+ *
+ * No key in this catalog is outside ASCII, so this reorders nothing that has been
+ * published. It is the rule that was wrong, and a rule about signatures is not worth
+ * leaving wrong until a document arrives that shows it.
+ */
+export declare function byCodePoint(a: string, b: string): number;
+/**
+ * Deterministic serialization: object keys sorted, excluded keys dropped at every depth,
+ * array order preserved because order is meaning in `steps[]`.
+ */
+export declare function canonicalize(value: unknown): string;
+/** The document as it is hashed: catalog-assigned fields removed at every depth. */
+export declare function hashableDocument(document: unknown): unknown;
+export declare function contentHash(document: unknown): Promise<string>;
+export declare function matchesHash(document: unknown, expected: string): Promise<boolean>;

package/dist/hash.js

@@ -0,0 +1,102 @@
+/**
+ * `content_hash`: what a version *is*.
+ *
+ * Agent pins point at it, attestations bind to it, and the resolver refuses a document
+ * whose bytes do not match it. So the computation has to be reproducible by anyone,
+ * which means canonicalization is specified rather than incidental.
+ *
+ * Web Crypto, not `node:crypto`: this package is a dependency of the supervisor core and
+ * of the graph package, which runs in a browser for the live editor. A Node-only import
+ * here would break both at a distance.
+ */
+/**
+ * Excluded from the hash.
+ *
+ * `x-layout` is presentation rather than content (RUNBOOK.md 6): re-laying-out a graph is
+ * not a new version.
+ *
+ * The rest are assigned by the catalog rather than written by an author. `content_hash`
+ * cannot be part of what it hashes, and `trust` decays with the calendar — a hash that
+ * moved when a badge expired would make every pinned reference break on a quiet Tuesday.
+ *
+ * The upstream markers are the same kind of thing as trust: an observation the catalog
+ * made about the world, not content an author wrote. §3 is explicit that a moved
+ * upstream does not invalidate the indexed version — the record remains and the marker
+ * changes — and a marker inside the hash would make noticing that a source moved into a
+ * new version of our record, breaking every pin that referred to it.
+ *
+ * This set is shared by whatever computes a hash and whatever verifies one. They cannot
+ * be allowed to disagree: when they did, the catalog published records that failed their
+ * own verification.
+ */
+const EXCLUDED = new Set([
+    "x-layout",
+    "content_hash",
+    "trust",
+    "trust_evidence",
+    "upstream_state",
+    "upstream_hash",
+    "checked_at",
+    /**
+     * The catalog's own identifier (§9). Assigned by us, not written by an author, and
+     * stable across renames — so it cannot be part of what identifies the content, and a
+     * record that gained one would otherwise stop hashing to its own published hash. This
+     * is the fourth field to arrive here for the same reason, which is why the reason is
+     * stated once at the top rather than four times.
+     */
+    "id",
+]);
+/**
+ * Key order, once, for every canonicalization this product has.
+ *
+ * By code point — which is what `jq -cS` emits, what Python's `sort_keys` and Go's
+ * `encoding/json` do, and what `spec/v1/signing.md` prints as the recipe a publisher signs
+ * with **without our code**. JavaScript's `<` compares UTF-16 code units instead, and the
+ * two disagree the moment a key above U+FFFF meets one in U+E000..U+FFFF: by code unit the
+ * astral key comes first, by code point it comes last. A publisher following the printed
+ * recipe would then produce bytes this product refuses to verify, which is the single
+ * failure a canonicalization exists to prevent.
+ *
+ * No key in this catalog is outside ASCII, so this reorders nothing that has been
+ * published. It is the rule that was wrong, and a rule about signatures is not worth
+ * leaving wrong until a document arrives that shows it.
+ */
+export function byCodePoint(a, b) {
+    const left = [...a];
+    const right = [...b];
+    for (let i = 0; i < left.length && i < right.length; i += 1) {
+        const difference = left[i].codePointAt(0) - right[i].codePointAt(0);
+        if (difference !== 0)
+            return difference;
+    }
+    return left.length - right.length;
+}
+/**
+ * Deterministic serialization: object keys sorted, excluded keys dropped at every depth,
+ * array order preserved because order is meaning in `steps[]`.
+ */
+export function canonicalize(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(canonicalize).join(",")}]`;
+    const entries = Object.entries(value)
+        .filter(([k, v]) => !EXCLUDED.has(k) && v !== undefined)
+        .sort(([a], [b]) => byCodePoint(a, b));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalize(v)}`).join(",")}}`;
+}
+function hex(buffer) {
+    return [...new Uint8Array(buffer)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** The document as it is hashed: catalog-assigned fields removed at every depth. */
+export function hashableDocument(document) {
+    return JSON.parse(canonicalize(document));
+}
+export async function contentHash(document) {
+    const bytes = new TextEncoder().encode(canonicalize(document));
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    return `sha256:${hex(digest)}`;
+}
+export async function matchesHash(document, expected) {
+    return (await contentHash(document)) === expected;
+}

package/dist/hash.test.d.ts

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

package/dist/hash.test.js

@@ -0,0 +1,54 @@
+import { describe, it, expect } from "vitest";
+import { canonicalize, contentHash, matchesHash } from "./hash.js";
+describe("canonicalization", () => {
+    it("does not depend on key order", () => {
+        expect(canonicalize({ b: 1, a: 2 })).toBe(canonicalize({ a: 2, b: 1 }));
+    });
+    // Order is meaning in steps[]: reordering a procedure is a different procedure.
+    it("preserves array order", () => {
+        expect(canonicalize([1, 2])).not.toBe(canonicalize([2, 1]));
+    });
+    it("sorts at every depth", () => {
+        expect(canonicalize({ x: { b: 1, a: 2 } })).toBe(canonicalize({ x: { a: 2, b: 1 } }));
+    });
+    // Presentation is not content: re-laying-out a graph must not create a new version.
+    it("ignores x-layout wherever it appears", () => {
+        const plain = { runbook: { steps: [{ id: "s1" }] } };
+        const laid = { runbook: { steps: [{ id: "s1", "x-layout": { x: 10, y: 20 } }] } };
+        expect(canonicalize(laid)).toBe(canonicalize(plain));
+    });
+});
+describe("content hash", () => {
+    it("is stable across runs and key order", async () => {
+        const a = await contentHash({ name: "x", runbook: { profile: "P0" } });
+        const b = await contentHash({ runbook: { profile: "P0" }, name: "x" });
+        expect(a).toBe(b);
+        expect(a).toMatch(/^sha256:[0-9a-f]{64}$/);
+    });
+    it("changes when content changes", async () => {
+        expect(await contentHash({ a: 1 })).not.toBe(await contentHash({ a: 2 }));
+    });
+    it("does not change when only layout moves", async () => {
+        const doc = { runbook: { steps: [{ id: "s1" }] } };
+        const moved = { runbook: { steps: [{ id: "s1", "x-layout": { x: 1, y: 2 } }] } };
+        expect(await matchesHash(moved, await contentHash(doc))).toBe(true);
+    });
+});
+/**
+ * The fourth field to be excluded for the same reason, and the second time a
+ * catalog-assigned field was added after hashing and broke a record's ability to verify
+ * itself. Assigned by us is not content.
+ */
+describe("a catalog-assigned identifier is not content", () => {
+    it("ignores id wherever it appears", async () => {
+        const bare = { runbook: { semver: "1.0.0" } };
+        const identified = { runbook: { semver: "1.0.0", id: `rb_${"0".repeat(26)}` } };
+        expect(await contentHash(identified)).toBe(await contentHash(bare));
+    });
+    it("keeps a served record hashing to what it declares", async () => {
+        const served = { name: "x", runbook: { semver: "1.0.0", id: `rb_${"0".repeat(26)}`, trust: "T2" } };
+        const declared = await contentHash(served);
+        expect(await contentHash({ ...served, runbook: { ...served.runbook, content_hash: declared } }))
+            .toBe(declared);
+    });
+});