Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/INVARIANTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion docs/decisions/ADR-021-doc-derived-lamport-clock-store.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion scripts/check-pins.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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");

Expand Down
2 changes: 1 addition & 1 deletion scripts/check-purity.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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 = [
Expand Down
2 changes: 1 addition & 1 deletion scripts/check-stateless.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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"))
Expand Down
118 changes: 118 additions & 0 deletions test/invariant-ids.test.ts
Original file line number Diff line number Diff line change
@@ -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<string> {
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 including the register. */
function citationsByFile(): Map<string, string[]> {
const found = new Map<string, string[]>();
for (const file of trackedTextFiles()) {
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 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", () => {
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]);
});
});
22 changes: 21 additions & 1 deletion test/purity.test.ts
Original file line number Diff line number Diff line change
@@ -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";
Expand Down Expand Up @@ -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<string, unknown>)["window"]).toBe("undefined");
expect(typeof (globalThis as Record<string, unknown>)["document"]).toBe("undefined");
Expand Down
36 changes: 36 additions & 0 deletions test/stateless.test.ts
Original file line number Diff line number Diff line change
@@ -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),
Expand All @@ -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<string, unknown>();\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);
Expand Down
48 changes: 47 additions & 1 deletion test/upstream-pins.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down Expand Up @@ -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
Expand Down