From c8ad53ec05aeb6cdf12aae01751e8325e4e64eba Mon Sep 17 00:00:00 2001 From: bymyself Date: Thu, 17 Sep 2026 00:11:30 -0700 Subject: [PATCH 1/3] test: recover standalone governance gates and invariant register --- docs/INVARIANTS.md | 5 + ...ADR-021-doc-derived-lamport-clock-store.md | 3 +- scripts/check-pins.mjs | 2 +- scripts/check-purity.mjs | 2 +- scripts/check-stateless.mjs | 2 +- test/invariant-ids.test.ts | 118 ++++++++++++++++++ test/purity.test.ts | 22 +++- test/stateless.test.ts | 36 ++++++ test/upstream-pins.test.ts | 48 ++++++- 9 files changed, 232 insertions(+), 6 deletions(-) create mode 100644 test/invariant-ids.test.ts diff --git a/docs/INVARIANTS.md b/docs/INVARIANTS.md index 567337d0..ee221807 100644 --- a/docs/INVARIANTS.md +++ b/docs/INVARIANTS.md @@ -81,6 +81,11 @@ Two corrections recorded by MUT-GLOB-KA4-1, both measured on this tree rather th **Why:** Replay semantics must not drift with a moving vocabulary. **Enforced by:** `test/roundtrip.test.ts`, `test/catalog-sha-binding-integration.test.ts`, [`catalog-pinning`](../.agents/checks/catalog-pinning.md), [ADR-003](decisions/ADR-003-catalog-sha-at-mint.md), and — for the *citations* rather than `meta.catalog_version` itself — `scripts/check-pins.mjs` (`npm run check:pins`) with `docs/upstream-pins.json` and `test/upstream-pins.test.ts`. `test/doc-mint-mutation-survivors.test.ts` additionally pins that an imported workflow cannot forge `catalog_version`/`schema_version` or any `__`-prefixed meta key, and that an unpinned mint records an EMPTY catalog version rather than a plausible-looking default (FC-10). The rule's second clause is narrower than it looks: **`meta.catalog_version` is still UNGUARDED at the write sites — see roadmap.** Neither `mint()` nor `initDoc()` rejects a branch-shaped catalog version; only the citations are linted. +### KA-13 — The package owns no state outside the caller's document +**Rule:** The package holds no caller-independent durable state: no module-level `let`/`var`, no module-level mutable collection, and no UI/reactivity/framework import. Every document is caller-owned and injected, so behavior must not depend on process lifetime or module-registry identity. There is exactly one documented exception — the `Y.Doc`-keyed `documentTransactionTails` weak registry of [ADR-021](decisions/ADR-021-doc-derived-lamport-clock-store.md) amendment CLK-2 — which is named in the gate's allowlist, keyed by caller-owned document identity, and creates no durable or cross-document state. +**Why:** One implementation must run identically in a browser bundle, at a peer or edge, and in a bare Node doc-host serving many documents from one process, so restart and reconnect reseed from committed document state rather than package-owned persistence and two documents in one process cannot leak into each other. **This is not an alias of KA-3, and the overlap is the reason it reads like one:** KA-3 constrains the *dependency surface* (portability), KA-13 constrains *state ownership*. They coincide only on the framework-import ban, which is why `scripts/check-stateless.mjs` cites both and why the framework rules in the strict config are labelled `KA-3/KA-13`. +**Enforced by:** `scripts/check-stateless.mjs` (`npm run check:stateless`), which lints every `src/**/*.ts` file against the `statelessRules` set in [`eslint.strict.config.js`](../.agents/checks/eslint.strict.config.js) under `CMP_STATELESS_ONLY=1` and then runs the colocated `test/stateless.test.ts` probe — no state shared between documents in one module instance, identical public behavior from fresh module registries, and a fresh Node process. The gate exits 2 (INCONCLUSIVE, never a pass) when a precondition or the per-file lint floor is missing, and it is merge-blocking in fact rather than by convention: [`.github/workflows/ci.yml`](../.github/workflows/ci.yml) runs it on every push and pull request. `test/invariant-ids.test.ts` holds this register itself — every `KA-*`/`FC-*` id cited anywhere in the package must resolve to a heading in this file, which is the guard that was missing while this entry was ([comfy-multi-player #152](https://github.com/Comfy-Org/comfy-multi-player/issues/152)). + ### KA-11 amendment — DQ-11 incarnation namespace (schema v2) **Rule:** A node lifetime has a durable `__incarnation` token. Imported nodes use `"0"`; a modern winning `add_node` carries its immutable `op_id` as the token diff --git a/docs/decisions/ADR-021-doc-derived-lamport-clock-store.md b/docs/decisions/ADR-021-doc-derived-lamport-clock-store.md index 3a50a132..cf7354d2 100644 --- a/docs/decisions/ADR-021-doc-derived-lamport-clock-store.md +++ b/docs/decisions/ADR-021-doc-derived-lamport-clock-store.md @@ -68,7 +68,8 @@ no caller-independent merge or durable state (KA-13). - **DQ-11:** the decision to namespace node-scoped stamps by incarnation. - **Vector clock:** a test reference mapping each actor to its observed counter, able to distinguish ordered pairs from true concurrency. -- **KA-13:** the package statelessness invariant guarded by `check:stateless`. +- **KA-13:** the package statelessness invariant guarded by `check:stateless`, registered in + [`docs/INVARIANTS.md`](../INVARIANTS.md). ## Amendment: CLK-1 transaction serialization and commit diff --git a/scripts/check-pins.mjs b/scripts/check-pins.mjs index 02343f2b..5c698099 100644 --- a/scripts/check-pins.mjs +++ b/scripts/check-pins.mjs @@ -54,7 +54,7 @@ import { existsSync, readFileSync } from "node:fs"; import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; -const root = dirname(dirname(fileURLToPath(import.meta.url))); +const root = process.env.PINS_ROOT ?? dirname(dirname(fileURLToPath(import.meta.url))); const registryPath = join(root, "docs", "upstream-pins.json"); const verifyRemote = process.argv.includes("--verify-remote"); diff --git a/scripts/check-purity.mjs b/scripts/check-purity.mjs index 0a260bce..c684e928 100644 --- a/scripts/check-purity.mjs +++ b/scripts/check-purity.mjs @@ -23,7 +23,7 @@ import { existsSync, readFileSync } from "node:fs"; import { dirname, join } from "node:path"; import { fileURLToPath, pathToFileURL } from "node:url"; -const root = dirname(dirname(fileURLToPath(import.meta.url))); +const root = process.env.PURITY_ROOT ?? dirname(dirname(fileURLToPath(import.meta.url))); /** Banned dependency names. Exact-match strings or RegExp tested on the name. */ const BANNED = [ diff --git a/scripts/check-stateless.mjs b/scripts/check-stateless.mjs index 2561792a..b43d4fb0 100644 --- a/scripts/check-stateless.mjs +++ b/scripts/check-stateless.mjs @@ -13,7 +13,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs"; import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; -const root = dirname(dirname(fileURLToPath(import.meta.url))); +const root = process.env.STATELESS_ROOT ?? dirname(dirname(fileURLToPath(import.meta.url))); const config = join(root, ".agents/checks/eslint.strict.config.js"); const sourceFiles = readdirSync(join(root, "src"), { recursive: true }) .filter((file) => typeof file === "string" && file.endsWith(".ts")) diff --git a/test/invariant-ids.test.ts b/test/invariant-ids.test.ts new file mode 100644 index 00000000..3140db9d --- /dev/null +++ b/test/invariant-ids.test.ts @@ -0,0 +1,118 @@ +/** + * Every `KA-*` / `FC-*` id cited in this repository resolves to a heading in + * `docs/INVARIANTS.md`. + * + * `docs/INVARIANTS.md` calls itself "the machine-addressable review log", and + * `AGENTS.md` requires every semantics-touching change to cite the affected ids + * in its PR description — but nothing checked that a cited id exists. `KA-13` + * was cited by the stateless gate, the strict ESLint config, `ADR-021` and + * `test/stateless.test.ts` while the register stopped at `KA-12`, so the label + * was unresolvable for every reader who followed it (#152). + * + * This is a register-integrity check, not a coverage check: it says nothing + * about whether an id is *guarded*, only that it is *defined*. `UNGUARDED` + * markers stay the register's own business. + * + * Deliberately offline and repository-local — it reads the working tree through + * `git ls-files` so a new citation in a new file is covered without anyone + * remembering to extend a list. + */ +import { spawnSync } from "node:child_process"; +import { readFileSync } from "node:fs"; +import { dirname, extname, join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { describe, expect, it } from "vitest"; + +const root = dirname(dirname(fileURLToPath(import.meta.url))); +const REGISTER = "docs/INVARIANTS.md"; + +/** `KA-0` / `FC-0` is the placeholder row in the `EXCEPTIONS.md` table template. */ +const PLACEHOLDER = /^(KA|FC)-0$/; + +// `\b` is the wrong right-hand delimiter here: a digit followed by `-` IS a word +// boundary, so `/KA-\d+\b/` reads `KA-13-SOMETHING` as a citation of `KA-13`. +// That is exactly the mis-registration this suite exists to catch, so both ends +// require a non-id character. +const CITATION = /\b(KA|FC)-\d+(?![\w-])/g; +const HEADING = /^### ((?:KA|FC)-\d+)(?![\w-])/gm; + +/** Text formats where a citation is meant to be read and followed. */ +const TEXT_EXTENSIONS = new Set([".ts", ".js", ".mjs", ".cjs", ".md", ".json", ".yaml", ".yml"]); + +function trackedTextFiles(): string[] { + const listed = spawnSync("git", ["ls-files", "-z"], { cwd: root, encoding: "utf8", maxBuffer: 32 * 1024 * 1024 }); + if (listed.status !== 0) throw new Error(`git ls-files failed: ${listed.stderr || listed.error?.message}`); + return listed.stdout + .split("\0") + .filter(Boolean) + .filter((file) => TEXT_EXTENSIONS.has(extname(file))); +} + +/** Group 1 is mandatory in `HEADING`, but `noUncheckedIndexedAccess` cannot see that. */ +function captured(match: RegExpExecArray, group: number): string { + const value = match[group]; + if (value === undefined) throw new Error(`regex group ${group} did not capture in: ${match[0]}`); + return value; +} + +function definedIds(): Set { + const register = readFileSync(join(root, REGISTER), "utf8"); + return new Set(Array.from(register.matchAll(HEADING), (match) => captured(match, 1))); +} + +/** file → sorted ids cited in it, for every tracked text file outside the register. */ +function citationsByFile(): Map { + const found = new Map(); + for (const file of trackedTextFiles()) { + if (file === REGISTER) continue; + const cited = new Set( + Array.from(readFileSync(join(root, file), "utf8").matchAll(CITATION), (match) => captured(match, 0)).filter( + (id) => !PLACEHOLDER.test(id), + ), + ); + if (cited.size > 0) found.set(file, [...cited].sort()); + } + return found; +} + +describe("invariant register integrity (KA-*/FC-* ids resolve)", () => { + const defined = definedIds(); + const cited = citationsByFile(); + + it("finds the register and a non-trivial number of ids in it", () => { + // A heading regex that silently stopped matching would read the register as + // EMPTY, which turns the resolution case below into a wall of false + // failures rather than a silent pass — but pin the floor anyway, because a + // register read as empty is never a legitimate state. + expect(defined.size).toBeGreaterThanOrEqual(22); + expect(defined.has("KA-1")).toBe(true); + expect(defined.has("FC-10")).toBe(true); + }); + + it("scans a non-trivial number of citing files", () => { + expect(cited.size).toBeGreaterThanOrEqual(20); + }); + + it("resolves every cited id to a heading in docs/INVARIANTS.md", () => { + const unresolved = [...cited] + .flatMap(([file, ids]) => ids.filter((id) => !defined.has(id)).map((id) => `${file}: ${id}`)) + .sort(); + expect(unresolved).toEqual([]); + }); + + it("keeps KA-13 registered, the citation this guard was written for", () => { + expect(defined.has("KA-13")).toBe(true); + expect(cited.get("test/stateless.test.ts")).toContain("KA-13"); + expect(cited.get("scripts/check-stateless.mjs")).toContain("KA-13"); + expect(cited.get(".agents/checks/eslint.strict.config.js")).toContain("KA-13"); + expect(cited.get("docs/decisions/ADR-021-doc-derived-lamport-clock-store.md")).toContain("KA-13"); + }); + + it("would catch an unregistered id (the #152 shape), rather than only the fixed instance", () => { + // Assembled from parts on purpose: a literal sentinel in this file's own + // source would be scanned as a real citation and fail the case above. + const unregistered = ["KA", "999"].join("-"); + expect(defined.has(unregistered)).toBe(false); + expect(Array.from(`cites ${unregistered} here`.matchAll(CITATION), (match) => match[0])).toEqual([unregistered]); + }); +}); diff --git a/test/purity.test.ts b/test/purity.test.ts index eef7ef9b..dbbc7951 100644 --- a/test/purity.test.ts +++ b/test/purity.test.ts @@ -1,5 +1,6 @@ import { spawnSync } from "node:child_process"; -import { existsSync, readFileSync } from "node:fs"; +import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; import { dirname, join } from "node:path"; import { fileURLToPath, pathToFileURL } from "node:url"; import { describe, expect, it } from "vitest"; @@ -40,6 +41,25 @@ describe("purity", () => { expect(Object.keys(packageJson.dependencies ?? {}).sort()).toEqual(["yjs"]); }); + it("makes the production gate fail on a planted framework dependency", () => { + const fixture = mkdtempSync(join(tmpdir(), "purity-")); + try { + writeFileSync( + join(fixture, "package.json"), + JSON.stringify({ dependencies: { react: "^19.0.0", yjs: "^13.6.27" } }), + ); + const run = spawnSync(process.execPath, [join(root, "scripts", "check-purity.mjs")], { + encoding: "utf8", + env: { ...process.env, PURITY_ROOT: fixture }, + }); + expect(run.status).toBe(1); + expect(run.stderr).toContain("runtime dependencies must be exactly {yjs}"); + expect(run.stderr).toContain("{react, yjs}"); + } finally { + rmSync(fixture, { recursive: true, force: true }); + } + }); + it("test environment itself is bare node (no DOM globals)", () => { expect(typeof (globalThis as Record)["window"]).toBe("undefined"); expect(typeof (globalThis as Record)["document"]).toBe("undefined"); diff --git a/test/stateless.test.ts b/test/stateless.test.ts index 321455c3..eabcc5da 100644 --- a/test/stateless.test.ts +++ b/test/stateless.test.ts @@ -1,10 +1,14 @@ import { spawnSync } from "node:child_process"; +import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; import { describe, expect, it, vi } from "vitest"; import { applyOps, mint, project, type Op } from "../src/index.js"; import { loadCatalog } from "./helpers.js"; const catalog = loadCatalog(); +const repoRoot = dirname(dirname(fileURLToPath(import.meta.url))); const add: Op = { op: "add_node", op_id: "1".repeat(32), @@ -23,6 +27,38 @@ async function freshApi() { } describe("KA-13: cmp is stateless modulo caller-owned documents", () => { + it.each([ + ["module-level mutable state", "const cache = new Map();\nvoid cache;\n", "no module-level mutable collection"], + ["a module-level let", "let current = 0;\ncurrent += 1;\n", "no module-level let/var"], + ["a UI import", 'import { ref } from "vue";\nvoid ref;\n', "cmp is DOM/framework-free and stateless"], + ])("makes the production gate fail on planted %s", (_name, source, expected) => { + const root = mkdtempSync(join(tmpdir(), "stateless-")); + try { + mkdirSync(join(root, ".agents", "checks"), { recursive: true }); + mkdirSync(join(root, "src")); + mkdirSync(join(root, "node_modules")); + symlinkSync( + join(repoRoot, ".agents", "checks", "eslint.strict.config.js"), + join(root, ".agents", "checks", "eslint.strict.config.js"), + ); + for (const dependency of [".bin", "@typescript-eslint", "eslint", "eslint-plugin-sonarjs"]) { + symlinkSync(join(repoRoot, "node_modules", dependency), join(root, "node_modules", dependency), "dir"); + } + writeFileSync(join(root, "package.json"), JSON.stringify({ name: "stateless-fixture" })); + writeFileSync(join(root, "src", "leak.ts"), source); + + const run = spawnSync(process.execPath, [join(repoRoot, "scripts", "check-stateless.mjs")], { + encoding: "utf8", + env: { ...process.env, STATELESS_ROOT: root }, + }); + expect(run.status).toBe(1); + expect(run.stderr).toContain(expected); + expect(run.stderr).toContain("src/leak.ts"); + } finally { + rmSync(root, { recursive: true, force: true }); + } + }); + it("does not share document state between calls in one module instance", async () => { const api = await freshApi(); const untouched = api.mint({ nodes: [], links: [] }, catalog); diff --git a/test/upstream-pins.test.ts b/test/upstream-pins.test.ts index 8f2c37bf..810255aa 100644 --- a/test/upstream-pins.test.ts +++ b/test/upstream-pins.test.ts @@ -10,7 +10,9 @@ * resolves upstream is a network question, and a test that silently degrades to * "assume fine" when the network is absent is worse than no test. */ -import { readFileSync } from "node:fs"; +import { spawnSync } from "node:child_process"; +import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; import { describe, expect, it } from "vitest"; @@ -59,6 +61,50 @@ const REQUIRED_SITES = ["src/index.ts", "src/types.ts", "docs/multiplayer-schema const VOCABULARY_PIN = "7e732242d971daf0d2d30f22f997abfacd78986e"; describe("FC-10 — upstream citations are pinned by SHA, not by branch", () => { + it("makes the production gate fail on a planted moving upstream citation", () => { + const fixture = mkdtempSync(join(tmpdir(), "pins-")); + try { + mkdirSync(join(fixture, "docs")); + const commit = "a".repeat(40); + const citedBy = ["citation-1.md", "citation-2.md", "citation-3.md", "citation-4.md"]; + writeFileSync( + join(fixture, "docs", "upstream-pins.json"), + JSON.stringify({ + pins: { + vocabulary: { + commit, + repo: "https://github.com/example/op-vocabulary", + path: "README.md", + established_by: "resolved from an immutable upstream revision with audit evidence", + sections_cited: ["Vocabulary"], + cited_by: citedBy, + }, + }, + }), + ); + for (const site of citedBy) writeFileSync(join(fixture, site), `Pinned at ${commit}.\n`); + writeFileSync( + join(fixture, citedBy[0]!), + `comfy-cli op-vocabulary citation (branch \`moving/main\`) at ${commit}.\n`, + ); + for (let index = 0; index < 20; index += 1) { + writeFileSync(join(fixture, `tracked-${index}.md`), `fixture ${index}\n`); + } + expect(spawnSync("git", ["init", "--quiet"], { cwd: fixture }).status).toBe(0); + expect(spawnSync("git", ["add", "."], { cwd: fixture }).status).toBe(0); + + const run = spawnSync(process.execPath, [join(root, "scripts", "check-pins.mjs")], { + encoding: "utf8", + env: { ...process.env, PINS_ROOT: fixture }, + }); + expect(run.status).toBe(1); + expect(run.stderr).toContain("upstream citation uses a moving reference"); + expect(run.stderr).toContain("citation-1.md:1"); + } finally { + rmSync(fixture, { recursive: true, force: true }); + } + }); + it("registers at least the vocabulary, its v1.2 amendment, and the minting module", () => { // "At least", as the title says. This asserted exact set equality, which // made it a change detector: registering a NEW cross-repo pin — the thing From 6f75eb1c88d78823108be33ed85da7737fa88499 Mon Sep 17 00:00:00 2001 From: bymyself Date: Thu, 17 Sep 2026 08:32:17 -0700 Subject: [PATCH 2/3] test: validate invariant register self-citations --- test/invariant-ids.test.ts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/test/invariant-ids.test.ts b/test/invariant-ids.test.ts index 3140db9d..e427a593 100644 --- a/test/invariant-ids.test.ts +++ b/test/invariant-ids.test.ts @@ -60,11 +60,10 @@ function definedIds(): Set { return new Set(Array.from(register.matchAll(HEADING), (match) => captured(match, 1))); } -/** file → sorted ids cited in it, for every tracked text file outside the register. */ +/** file → sorted ids cited in it, for every tracked text file including the register. */ function citationsByFile(): Map { const found = new Map(); for (const file of trackedTextFiles()) { - if (file === REGISTER) continue; const cited = new Set( Array.from(readFileSync(join(root, file), "utf8").matchAll(CITATION), (match) => captured(match, 0)).filter( (id) => !PLACEHOLDER.test(id), From e4212f728635f87e608eb0251db92b488dddfe9a Mon Sep 17 00:00:00 2001 From: bymyself Date: Thu, 17 Sep 2026 08:40:33 -0700 Subject: [PATCH 3/3] test: pin invariant register inclusion in citation scan --- test/invariant-ids.test.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/test/invariant-ids.test.ts b/test/invariant-ids.test.ts index e427a593..6c3de5eb 100644 --- a/test/invariant-ids.test.ts +++ b/test/invariant-ids.test.ts @@ -88,8 +88,9 @@ describe("invariant register integrity (KA-*/FC-* ids resolve)", () => { expect(defined.has("FC-10")).toBe(true); }); - it("scans a non-trivial number of citing files", () => { + it("scans a non-trivial number of citing files including the register", () => { expect(cited.size).toBeGreaterThanOrEqual(20); + expect(cited.get(REGISTER)).toContain("KA-3"); }); it("resolves every cited id to a heading in docs/INVARIANTS.md", () => {