import { spawnSync } from "node:child_process"; import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import path from "node:path"; import { pathToFileURL } from "node:url"; import { describe, expect, it } from "vitest"; import { diffRegistrySnapshots, registrySnapshotDigest, validateBreakingEvidence, verifyRegistryBaselineApproval, } from "../../scripts/lib/registry-compatibility.ts"; type RegistryDefinition = Readonly<{ registryId: string; owner: string; requiredFields: string[]; fieldTypes: Record; path: string; exportName: string; rowsPath?: string; rowKeyFields?: string[]; uniqueFields?: string[]; uniqueFieldSets?: string[][]; snapshotProjection?: { singletonRowKey: string; canonicalArrayKeyFields: Record; }; consumers?: Array<{ path: string; token: string }>; breakingFields?: string[]; }>; describe("registry governance manifest", () => { it("declares eleven typed, single-owner executable registries", async () => { const governance = JSON.parse( await readFile("config/contracts/registry-governance.json", "utf8"), ); const registries = governance.registries as RegistryDefinition[]; expect(governance.registries).toHaveLength(11); expect(new Set(registries.map((entry) => entry.registryId)).size).toBe( 11, ); expect(registries.every((entry) => entry.owner)).toBe(true); expect( registries.every( (entry) => Array.isArray(entry.requiredFields) && entry.requiredFields.length > 0 && entry.fieldTypes && Object.keys(entry.fieldTypes).length > 0, ), ).toBe(true); }); it("governs the installed invalidation graph and wire versions at their real exports", async () => { const governance = JSON.parse( await readFile("config/contracts/registry-governance.json", "utf8"), ) as { registries: RegistryDefinition[] }; const byId = new Map( governance.registries.map((registry) => [registry.registryId, registry]), ); expect(byId.get("FE-REG-QUERY-INVALIDATION")).toMatchObject({ path: "src/features/installed-feature-contracts.ts", exportName: "INVALIDATION_REGISTRY", rowsPath: "edges", rowKeyFields: [ "topicId", "namespace.namespaceId", "namespace.namespaceVersion", ], uniqueFieldSets: [ [ "topicId", "namespace.namespaceId", "namespace.namespaceVersion", ], ], snapshotProjection: { singletonRowKey: "invalidation-graph", canonicalArrayKeyFields: { topics: ["$value"], namespaces: ["namespaceId", "namespaceVersion"], edges: [ "topicId", "namespace.namespaceId", "namespace.namespaceVersion", ], }, }, consumers: [ { path: "src/bootstrap/runtime-adapters.ts", token: "indexInvalidationRegistry(INVALIDATION_REGISTRY)", }, ], breakingFields: ["topics", "namespaces", "edges"], }); expect(byId.get("FE-REG-QUERY-INVALIDATION-TOPIC-VERSION")).toMatchObject({ path: "src/features/installed-feature-contracts.ts", exportName: "INVALIDATION_TOPIC_VERSIONS", rowKeyFields: ["topicId"], uniqueFields: ["topicId"], consumers: [ { path: "src/bootstrap/runtime-adapters.ts", token: "indexInvalidationTopicVersions(", }, ], breakingFields: ["topicId", "topicVersion"], }); }); it("projects graph and array exports into deterministic governed rows", async () => { const directory = await mkdtemp( path.join(tmpdir(), "registry-governance-projection-"), ); const artifact = path.join(directory, "registries.json"); try { const result = spawnSync( process.execPath, [ "scripts/check-registries.ts", "--governance", "tests/fixtures/registry/invalidation/governance.json", "--artifact", artifact, "--no-baseline", ], { encoding: "utf8" }, ); expect(result.status, result.stderr).toBe(0); const report = JSON.parse(await readFile(artifact, "utf8")) as { registries: Array<{ registryId: string; rows: Record>; }>; }; expect( report.registries.find( (registry) => registry.registryId === "FIXTURE-INVALIDATION-EDGES", )?.rows, ).toEqual({ "invalidation-graph": { topics: ["orders", "qinv.fixture.changed"], namespaces: [ { namespaceId: "orders", namespaceVersion: 1 }, { namespaceId: "qinv.fixture.changed", namespaceVersion: 1 }, ], edges: [ { topicId: "orders", namespace: { namespaceId: "qinv.fixture.changed", namespaceVersion: 1, }, }, { topicId: "qinv.fixture.changed", namespace: { namespaceId: "orders", namespaceVersion: 1 }, }, ], }, }); expect( report.registries.find( (registry) => registry.registryId === "FIXTURE-INVALIDATION-VERSIONS", )?.rows, ).toHaveProperty('["qinv.fixture.changed"]'); } finally { await rm(directory, { recursive: true, force: true }); } }); it("requires explicit evidence for post-baseline graph and version drift", async () => { const directory = await mkdtemp( path.join(tmpdir(), "registry-governance-tamper-"), ); const artifact = path.join(directory, "registries.json"); try { const result = spawnSync( process.execPath, [ "scripts/check-registries.ts", "--governance", "tests/fixtures/registry/invalidation/governance.json", "--artifact", artifact, "--no-baseline", ], { encoding: "utf8" }, ); expect(result.status, result.stderr).toBe(0); const report = JSON.parse(await readFile(artifact, "utf8")) as { registries: Array<{ registryId: string; contract: Record; rows: Record>; }>; }; const baseline = { schemaVersion: 2, registries: report.registries }; expect( baseline.registries.find( (registry) => registry.registryId === "FIXTURE-INVALIDATION-EDGES", )?.rows["invalidation-graph"], ).toBeDefined(); const tamperCases = [ { name: "topic", registryId: "FIXTURE-INVALIDATION-EDGES", field: "topics", apply(snapshot: typeof baseline) { const graph = snapshot.registries.find( (registry) => registry.registryId === this.registryId, )?.rows["invalidation-graph"]; (graph?.topics as string[])[0] = "tampered-topic"; }, }, { name: "namespace", registryId: "FIXTURE-INVALIDATION-EDGES", field: "namespaces", apply(snapshot: typeof baseline) { const graph = snapshot.registries.find( (registry) => registry.registryId === this.registryId, )?.rows["invalidation-graph"]; const namespaces = graph?.namespaces as Array<{ namespaceId: string; }>; namespaces[0]!.namespaceId = "tampered-namespace"; }, }, { name: "edge", registryId: "FIXTURE-INVALIDATION-EDGES", field: "edges", apply(snapshot: typeof baseline) { const graph = snapshot.registries.find( (registry) => registry.registryId === this.registryId, )?.rows["invalidation-graph"]; const edges = graph?.edges as Array<{ topicId: string }>; edges[0]!.topicId = "tampered-edge"; }, }, { name: "version", registryId: "FIXTURE-INVALIDATION-VERSIONS", field: "topicVersion", apply(snapshot: typeof baseline) { const versions = snapshot.registries.find( (registry) => registry.registryId === this.registryId, )?.rows; const firstVersion = versions?.[Object.keys(versions)[0] ?? ""]; if (!firstVersion) throw new Error("version fixture row missing"); firstVersion.topicVersion = 2; }, }, ]; for (const tamperCase of tamperCases) { const current = structuredClone(baseline); tamperCase.apply(current); const diff = diffRegistrySnapshots(baseline, current); expect(diff.impact, tamperCase.name).toBe("breaking"); expect( diff.changes.some((change) => change.kind === "registry-added"), tamperCase.name, ).toBe(false); const breakingChanges = diff.changes.filter( (change) => change.impact === "breaking", ); expect(breakingChanges, tamperCase.name).toEqual( expect.arrayContaining([ expect.objectContaining({ registryId: tamperCase.registryId, field: tamperCase.field, }), ]), ); expect( validateBreakingEvidence(diff, { changes: [] }).passed, tamperCase.name, ).toBe(false); expect( validateBreakingEvidence(diff, { changes: breakingChanges.map((change) => ({ changeId: change.changeId, after: change.after, versionBump: "2", migration: `migrate ${tamperCase.name}`, compatibilityWindow: "one release", rollback: `restore ${tamperCase.name} baseline`, owner: "fixture-owner", })), }).passed, tamperCase.name, ).toBe(true); } } finally { await rm(directory, { recursive: true, force: true }); } }); it("pins the full invalidation graph and versions in the approved repository baseline", async () => { const baseline = JSON.parse( await readFile("config/contracts/registry-baseline.json", "utf8"), ) as { schemaVersion: number; registries: Array<{ registryId: string; rows: Record>; }>; }; const approval = JSON.parse( await readFile( "config/contracts/registry-baseline.approval.json", "utf8", ), ) as Record; expect(verifyRegistryBaselineApproval(baseline, approval).passed).toBe(true); expect(baseline.registries).toHaveLength(11); const graph = baseline.registries.find( (registry) => registry.registryId === "FE-REG-QUERY-INVALIDATION", ); const versions = baseline.registries.find( (registry) => registry.registryId === "FE-REG-QUERY-INVALIDATION-TOPIC-VERSION", ); expect(graph?.rows["invalidation-graph"]).toMatchObject({ topics: expect.any(Array), namespaces: expect.any(Array), edges: expect.any(Array), }); expect(versions?.rows).toBeDefined(); // Who approved and why, not this template's wording: a project that // re-baselines with update:registry-baseline writes its own (D-13). expect(approval).toMatchObject({ owner: expect.stringMatching(/\S/u), reason: expect.stringMatching(/\S/u), }); }); // The baseline diff compares contracts and rows, not `source`, so a moved // registry (15-01 moved FE-REG-API and FE-REG-SCHEMA) left the approved // baseline naming a file that no longer holds it. Re-approve after a move. it("names each registry's governed source in the approved baseline", async () => { const governance = JSON.parse( await readFile("config/contracts/registry-governance.json", "utf8"), ) as { registries: Array<{ registryId: string; path: string }> }; const baseline = JSON.parse( await readFile("config/contracts/registry-baseline.json", "utf8"), ) as { registries: Array<{ registryId: string; source: string }> }; const sources = new Map( baseline.registries.map(({ registryId, source }) => [registryId, source]), ); expect( governance.registries .filter(({ registryId, path: source }) => sources.get(registryId) !== source) .map(({ registryId }) => registryId), "run update:registry-baseline after moving a registry", ).toEqual([]); }); // 0929/07-01 (3). Re-approval makes the current snapshot the baseline, so it // explains every change the evidence described. Git history keeps the rows. it("deletes the evidence rows the new baseline explains when it re-approves", async () => { const directory = await mkdtemp( path.join(tmpdir(), "registry-baseline-update-"), ); const evidencePath = path.join( directory, "config/contracts/registry-change-evidence.json", ); try { await mkdir(path.dirname(evidencePath), { recursive: true }); await writeFile( path.join(directory, "snapshot.json"), JSON.stringify({ registries: [] }), ); await writeFile( evidencePath, JSON.stringify({ schemaVersion: 1, changes: [ { changeId: "FE-REG-TEST:A:*:removed", versionBump: "2", migration: "none", compatibilityWindow: "none", rollback: "restore A", owner: "fixture-owner", }, ], }), ); const result = spawnSync( process.execPath, [path.resolve("scripts/update-registry-baseline.ts"), "snapshot.json"], { cwd: directory, encoding: "utf8", env: { ...process.env, REGISTRY_BASELINE_OWNER: "fixture-owner", REGISTRY_BASELINE_REASON: "fixture re-approval", }, }, ); expect(result.status, result.stderr).toBe(0); expect(JSON.parse(await readFile(evidencePath, "utf8"))).toEqual({ schemaVersion: 1, changes: [], }); expect(result.stdout).toContain("FE-REG-TEST:A:*:removed"); } finally { await rm(directory, { recursive: true, force: true }); } }); it("rejects duplicate composite invalidation edges after projection", async () => { const directory = await mkdtemp( path.join(tmpdir(), "registry-governance-duplicate-"), ); const artifact = path.join(directory, "registries.json"); try { const result = spawnSync( process.execPath, [ "scripts/check-registries.ts", "--governance", "tests/fixtures/registry/invalidation/duplicate-governance.json", "--artifact", artifact, "--no-baseline", ], { encoding: "utf8" }, ); expect(result.status).toBe(1); const report = JSON.parse(await readFile(artifact, "utf8")) as { failures: string[]; }; expect(report.failures).toEqual([ expect.stringContaining( "duplicates topicId+namespace.namespaceId+namespace.namespaceVersion", ), ]); } finally { await rm(directory, { recursive: true, force: true }); } }); // 0929/07-03. loadingSurface is a name, checked for its form, not a list. it("rejects a route loading surface that is not a kebab-case name", async () => { const directory = await mkdtemp( path.join(tmpdir(), "registry-governance-routes-"), ); const artifact = path.join(directory, "registries.json"); try { spawnSync( process.execPath, [ "scripts/check-registries.ts", "--governance", "tests/fixtures/registry/routes/governance.json", "--artifact", artifact, ], { encoding: "utf8" }, ); const { failures } = JSON.parse(await readFile(artifact, "utf8")) as { failures: string[]; }; expect( failures.filter((failure) => failure.includes(".loadingSurface ")), ).toEqual([ "ROUTES.FIRST.loadingSurface value Unknown loading does not match ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$", ]); } finally { await rm(directory, { recursive: true, force: true }); } }); it("names the load error of a registry source that exists but fails to import", async () => { const directory = await mkdtemp(path.join(tmpdir(), "registry-source-error-")); try { await mkdir(path.join(directory, "src"), { recursive: true }); await writeFile( path.join(directory, "src/broken.ts"), 'import { missingExport } from "./absent.ts";\nexport const ROWS = [missingExport];\n', ); await writeFile(path.join(directory, "src/absent.ts"), "export const other = 1;\n"); await writeFile( path.join(directory, "governance.json"), JSON.stringify({ schemaVersion: 1, sourceDirectories: [], registries: [ { registryId: "FIXTURE-BROKEN", path: "src/broken.ts", exportName: "ROWS", owner: "fixture", requiredFields: ["id"], uniqueFields: ["id"], }, ], compatibilityImpact: { allowed: ["none", "additive", "behavior-change", "breaking"], current: "none", }, }), ); const result = spawnSync( process.execPath, [ path.resolve("scripts/check-registries.ts"), "--governance", "governance.json", "--no-baseline", "--artifact", "out.json", ], { cwd: directory, encoding: "utf8" }, ); expect(result.status).toBe(1); expect(`${result.stdout}${result.stderr}`).toContain( "missing registry source src/broken.ts: The requested module './absent.ts' does not provide an export named 'missingExport'", ); } finally { await rm(directory, { recursive: true, force: true }); } }); // 1103/14-06. A contract contribution that fails to compose throws while // the registry source loads. The gate names the cause the error carries in // `reason` and does not also report the unloaded registries as deleted // (`removed` evidence) or as unknown reference targets. it("names a load error's reason and reports no cascade for the registries it did not load", async () => { const directory = await mkdtemp(path.join(tmpdir(), "registry-source-reason-")); const run = (extra: readonly string[]) => spawnSync( process.execPath, [ path.resolve("scripts/check-registries.ts"), "--governance", "governance.json", "--artifact", "out.json", ...extra, ], { cwd: directory, encoding: "utf8" }, ); try { await mkdir(path.join(directory, "src"), { recursive: true }); await writeFile( path.join(directory, "src/composed.ts"), 'export const ROWS = { A: { id: "A" } };\n', ); await writeFile( path.join(directory, "src/routes.ts"), 'export const ROUTES = { R: { id: "R", target: "A" } };\n', ); await writeFile( path.join(directory, "governance.json"), JSON.stringify({ schemaVersion: 1, sourceDirectories: [], registries: [ { registryId: "FIXTURE-COMPOSED", path: "src/composed.ts", exportName: "ROWS", owner: "fixture", keyField: "id", requiredFields: ["id"], fieldTypes: { id: "string" }, }, { registryId: "FIXTURE-ROUTES", path: "src/routes.ts", exportName: "ROUTES", owner: "fixture", keyField: "id", requiredFields: ["id", "target"], fieldTypes: { id: "string", target: "string" }, references: [ { field: "target", registryId: "FIXTURE-COMPOSED", targetField: "id", }, ], }, ], }), ); const healthy = run(["--no-baseline"]); expect(healthy.status, healthy.stderr).toBe(0); const report = JSON.parse( await readFile(path.join(directory, "out.json"), "utf8"), ) as { registries: unknown[] }; const baseline = { schemaVersion: 2, registries: report.registries }; await writeFile(path.join(directory, "baseline.json"), JSON.stringify(baseline)); await writeFile( path.join(directory, "approval.json"), JSON.stringify({ schemaVersion: 1, snapshotDigest: registrySnapshotDigest(baseline), owner: "fixture", reason: "fixture", approvedAt: "2026-11-04T00:00:00.000Z", }), ); await writeFile( path.join(directory, "evidence.json"), JSON.stringify({ schemaVersion: 1, changes: [] }), ); const withBaseline = [ "--baseline", "baseline.json", "--approval", "approval.json", "--compatibility-evidence", "evidence.json", ]; expect(run(withBaseline).status).toBe(0); await writeFile( path.join(directory, "src/composed.ts"), 'throw Object.assign(new Error("Installed contract contribution is not composable"), { reason: "notice-feature/NOTICE_LIST_ITEMS: unknown authProfileId NOTICE_NOPE" });\n', ); const broken = run(withBaseline); const output = `${broken.stdout}${broken.stderr}`; expect(broken.status).toBe(1); expect(output.trim().split("\n")).toEqual([ "Registry governance failed:", "missing registry source src/composed.ts: Installed contract contribution is not composable (reason: notice-feature/NOTICE_LIST_ITEMS: unknown authProfileId NOTICE_NOPE)", ]); } finally { await rm(directory, { recursive: true, force: true }); } }); // 1105/09-03. The real composition error already ends its message with the // reason (1103/09-07). The gate prints that cause once, not again in // `(reason: ...)`. it("names a ContractContributionError's reason once", async () => { const directory = await mkdtemp(path.join(tmpdir(), "registry-source-real-error-")); const errorModule = pathToFileURL( path.resolve("src/contracts/external-contract-runtime.ts"), ).href; try { await mkdir(path.join(directory, "src"), { recursive: true }); await writeFile( path.join(directory, "src/composed.ts"), [ `import { ContractContributionError } from ${JSON.stringify(errorModule)};`, 'throw new ContractContributionError("notice-feature/NOTICE_LIST_ITEMS: unknown authProfileId NOTICE_NOPE");', "", ].join("\n"), ); await writeFile( path.join(directory, "governance.json"), JSON.stringify({ schemaVersion: 1, sourceDirectories: [], registries: [ { registryId: "FIXTURE-COMPOSED", path: "src/composed.ts", exportName: "ROWS", owner: "fixture", keyField: "id", requiredFields: ["id"], fieldTypes: { id: "string" }, }, ], }), ); const result = spawnSync( process.execPath, [ path.resolve("scripts/check-registries.ts"), "--governance", "governance.json", "--artifact", "out.json", "--no-baseline", ], { cwd: directory, encoding: "utf8" }, ); const output = `${result.stdout}${result.stderr}`; expect(result.status).toBe(1); expect(output).toContain( "missing registry source src/composed.ts: Installed contract contribution is not composable: notice-feature/NOTICE_LIST_ITEMS: unknown authProfileId NOTICE_NOPE\n", ); expect(output.split("unknown authProfileId NOTICE_NOPE")).toHaveLength(2); expect(output).not.toContain("(reason:"); } finally { await rm(directory, { recursive: true, force: true }); } }); });