From 5ff8da4c6c66344ecaf67ae5d8cb0157a208b616 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 18 Sep 2026 22:33:38 +0000 Subject: [PATCH 01/20] fix: make configured lint findings fail and declare runtime globals Preserve every current rule and option. Add failing-first severity, option-preservation, and source-versus-test environment contracts. This is a partial recovery: npm lint now fails honestly but the existing all-rules backlog is not resolved. No source semantics are changed. Amp-Thread-ID: https://ampcode.com/threads/T-01a0b6a1-ba97-7390-b562-9225304d4bbf Co-authored-by: Amp --- eslint.config.mjs | 25 +++++++++++-- test/lint-contract.test.ts | 76 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 98 insertions(+), 3 deletions(-) create mode 100644 test/lint-contract.test.ts diff --git a/eslint.config.mjs b/eslint.config.mjs index 3a238bfc..d1c9bc97 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -2,10 +2,10 @@ import tsParser from "@typescript-eslint/parser"; import sonarjs from "eslint-plugin-sonarjs"; const sonarRecommended = sonarjs.configs.recommended; -const sonarWarnings = Object.fromEntries( +const sonarErrors = Object.fromEntries( Object.entries(sonarRecommended.rules).map(([ruleName, setting]) => [ ruleName, - Array.isArray(setting) ? ["warn", ...setting.slice(1)] : "warn", + Array.isArray(setting) ? ["error", ...setting.slice(1)] : "error", ]), ); @@ -20,7 +20,26 @@ export default [ ecmaVersion: 2024, parser: tsParser, sourceType: "module", + // Web-platform primitives used by the shared browser/Node implementation. + // Do not grant src/** Node-only or DOM globals (KA-3, FC-3). + globals: { + TextEncoder: "readonly", + structuredClone: "readonly", + }, + }, + rules: sonarErrors, + }, + { + files: ["test/**/*.ts"], + // Vitest runs in bare Node, not a DOM environment. Tests import Vitest APIs. + languageOptions: { + globals: { + Buffer: "readonly", + console: "readonly", + process: "readonly", + TextDecoder: "readonly", + URL: "readonly", + }, }, - rules: sonarWarnings, }, ]; diff --git a/test/lint-contract.test.ts b/test/lint-contract.test.ts new file mode 100644 index 00000000..5cc90241 --- /dev/null +++ b/test/lint-contract.test.ts @@ -0,0 +1,76 @@ +import { spawnSync } from "node:child_process"; +import { readFileSync } from "node:fs"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { describe, expect, it } from "vitest"; + +const root = dirname(dirname(fileURLToPath(import.meta.url))); + +describe("lint enforcement contract", () => { + it("reports a configured finding as an error and exits unsuccessfully", () => { + const manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8")); + expect(manifest.scripts.lint).toBe("eslint ."); + const run = spawnSync(process.execPath, [ + join(root, "node_modules/eslint/bin/eslint.js"), + ".", + "--stdin", "--stdin-filename", "src/lint-contract-probe.ts", "--format", "json", + ], { + cwd: root, + encoding: "utf8", + input: "export const digit = /[0-9]/;\n", + }); + expect(run.error).toBeUndefined(); + expect(run.stderr).toBe(""); + const results = JSON.parse(run.stdout) as { + messages: { ruleId: string; severity: number }[]; + }[]; + expect(results).toHaveLength(1); + expect(results[0]!.messages).toContainEqual(expect.objectContaining({ + ruleId: "sonarjs/concise-regex", + severity: 2, + })); + expect(run.status).toBe(1); + }); + + it.each([ + ["src/lint-contract-probe.ts", ["Buffer", "process", "window"]], + ["test/lint-contract-probe.test.ts", ["window"]], + ])("recognizes only the runtime globals available to %s", (filename, missing) => { + const run = spawnSync(process.execPath, [ + join(root, "node_modules/eslint/bin/eslint.js"), + "--stdin", "--stdin-filename", filename as string, "--format", "json", + ], { + cwd: root, + encoding: "utf8", + input: "export const probe = [TextEncoder, structuredClone, Buffer, process, window];\n", + }); + expect(run.error).toBeUndefined(); + expect(run.stderr).toBe(""); + const results = JSON.parse(run.stdout) as { + messages: { ruleId: string; message: string }[]; + }[]; + expect(results).toHaveLength(1); + const references = results[0]!.messages.filter( + message => message.ruleId === "sonarjs/no-reference-error", + ); + expect(references.map(message => message.message.split('"')[1])).toEqual(missing); + expect(run.status).toBe(1); + }); + + it("preserves rule options while promoting an upstream warning to an error", () => { + // The installed recommendation currently has scalar settings only. Inject + // an option-bearing setting before importing the real config so dropping + // array tails cannot pass unnoticed when the recommendation gains options. + const run = spawnSync(process.execPath, ["--input-type=module", "-e", ` + import sonarjs from "eslint-plugin-sonarjs"; + sonarjs.configs.recommended.rules["sonarjs/cognitive-complexity"] = ["warn", 3]; + const { default: configs } = await import("./eslint.config.mjs"); + const config = configs.find(config => config.rules); + process.stdout.write(JSON.stringify(config.rules["sonarjs/cognitive-complexity"])); + `], { cwd: root, encoding: "utf8" }); + expect(run.error).toBeUndefined(); + expect(run.status).toBe(0); + expect(run.stderr).toBe(""); + expect(JSON.parse(run.stdout)).toEqual(["error", 3]); + }); +}); From db88a38bfa37004b71f1d7dd78790526f82f2337 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 18 Sep 2026 22:40:13 +0000 Subject: [PATCH 02/20] fix: preserve upstream disabled Sonar rules and verify lint policy Amp-Thread-ID: https://ampcode.com/threads/T-01a0b6a1-ba97-7390-b562-9225304d4bbf Co-authored-by: Amp --- eslint.config.mjs | 12 ++++--- test/lint-contract.test.ts | 71 ++++++++++++++++++++++++++++++++++---- 2 files changed, 73 insertions(+), 10 deletions(-) diff --git a/eslint.config.mjs b/eslint.config.mjs index d1c9bc97..e66af7f9 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -2,11 +2,15 @@ import tsParser from "@typescript-eslint/parser"; import sonarjs from "eslint-plugin-sonarjs"; const sonarRecommended = sonarjs.configs.recommended; +// The former unconditional mapping accidentally enabled all 65 rules disabled +// by SonarJS 3.0.7's recommendation. Keep upstream rule selection and options; +// only promote enabled severities so findings cannot produce a successful lint. const sonarErrors = Object.fromEntries( - Object.entries(sonarRecommended.rules).map(([ruleName, setting]) => [ - ruleName, - Array.isArray(setting) ? ["error", ...setting.slice(1)] : "error", - ]), + Object.entries(sonarRecommended.rules).map(([ruleName, setting]) => { + const severity = Array.isArray(setting) ? setting[0] : setting; + if (severity === "off" || severity === 0) return [ruleName, setting]; + return [ruleName, Array.isArray(setting) ? ["error", ...setting.slice(1)] : "error"]; + }), ); export default [ diff --git a/test/lint-contract.test.ts b/test/lint-contract.test.ts index 5cc90241..17b368a5 100644 --- a/test/lint-contract.test.ts +++ b/test/lint-contract.test.ts @@ -7,7 +7,13 @@ import { describe, expect, it } from "vitest"; const root = dirname(dirname(fileURLToPath(import.meta.url))); describe("lint enforcement contract", () => { - it("reports a configured finding as an error and exits unsuccessfully", () => { + it.each([ + ["export const digit = /[0-9]/;", "sonarjs/concise-regex"], + ["export const boxed = new Number(1);", "sonarjs/no-primitive-wrappers"], + ['export const boxed = new String("x");', "sonarjs/no-primitive-wrappers"], + ["export const boxed = new Boolean(false);", "sonarjs/no-primitive-wrappers"], + ['import { runInNewContext } from "node:vm"; export function run(source: string) { return runInNewContext(source); }', "sonarjs/code-eval"], + ])("rejects production finding %s", (input, ruleId) => { const manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8")); expect(manifest.scripts.lint).toBe("eslint ."); const run = spawnSync(process.execPath, [ @@ -17,7 +23,7 @@ describe("lint enforcement contract", () => { ], { cwd: root, encoding: "utf8", - input: "export const digit = /[0-9]/;\n", + input, }); expect(run.error).toBeUndefined(); expect(run.stderr).toBe(""); @@ -26,12 +32,23 @@ describe("lint enforcement contract", () => { }[]; expect(results).toHaveLength(1); expect(results[0]!.messages).toContainEqual(expect.objectContaining({ - ruleId: "sonarjs/concise-regex", + ruleId, severity: 2, })); expect(run.status).toBe(1); }); + it("exits successfully for corrected code", () => { + const run = spawnSync(process.execPath, [ + join(root, "node_modules/eslint/bin/eslint.js"), + ".", "--stdin", "--stdin-filename", "src/lint-contract-probe.ts", "--format", "json", + ], { cwd: root, encoding: "utf8", input: "export const digit = /\\d/;\n" }); + expect(run.status, run.stderr).toBe(0); + expect(JSON.parse(run.stdout)).toEqual([ + expect.objectContaining({ errorCount: 0, warningCount: 0, messages: [] }), + ]); + }); + it.each([ ["src/lint-contract-probe.ts", ["Buffer", "process", "window"]], ["test/lint-contract-probe.test.ts", ["window"]], @@ -39,6 +56,8 @@ describe("lint enforcement contract", () => { const run = spawnSync(process.execPath, [ join(root, "node_modules/eslint/bin/eslint.js"), "--stdin", "--stdin-filename", filename as string, "--format", "json", + // Probe the declared environment independently of recommended rule selection. + "--rule", "sonarjs/no-reference-error:error", ], { cwd: root, encoding: "utf8", @@ -57,13 +76,53 @@ describe("lint enforcement contract", () => { expect(run.status).toBe(1); }); - it("preserves rule options while promoting an upstream warning to an error", () => { + it("retains the actual upstream disabled rules and every enabled rule option", () => { + const run = spawnSync(process.execPath, ["--input-type=module", "-e", ` + import sonarjs from "eslint-plugin-sonarjs"; + const { default: configs } = await import("./eslint.config.mjs"); + process.stdout.write(JSON.stringify({ + upstream: sonarjs.configs.recommended.rules, + configured: configs.find(config => config.rules).rules, + })); + `], { cwd: root, encoding: "utf8" }); + expect(run.status, run.stderr).toBe(0); + const { upstream, configured } = JSON.parse(run.stdout) as { + upstream: Record; + configured: Record; + }; + expect(Object.keys(configured).sort()).toEqual(Object.keys(upstream).sort()); + let disabled = 0; + let enabled = 0; + for (const [name, setting] of Object.entries(upstream)) { + const severity = Array.isArray(setting) ? setting[0] : setting; + if (severity === "off" || severity === 0) { + expect(configured[name], name).toEqual(setting); + disabled++; + } else { + const mapped = configured[name]; + expect(Array.isArray(mapped) ? mapped[0] : mapped, name).toBe("error"); + expect(Array.isArray(mapped) ? mapped.slice(1) : [], name).toEqual( + Array.isArray(setting) ? setting.slice(1) : [], + ); + enabled++; + } + } + expect(disabled).toBeGreaterThan(0); + expect(enabled).toBeGreaterThan(0); + }); + + it.each([ + [["warn", 3], ["error", 3]], + [[1, 4], ["error", 4]], + [["off", 5], ["off", 5]], + [[0, 6], [0, 6]], + ])("preserves options and interprets severity in %j", (setting, expected) => { // The installed recommendation currently has scalar settings only. Inject // an option-bearing setting before importing the real config so dropping // array tails cannot pass unnoticed when the recommendation gains options. const run = spawnSync(process.execPath, ["--input-type=module", "-e", ` import sonarjs from "eslint-plugin-sonarjs"; - sonarjs.configs.recommended.rules["sonarjs/cognitive-complexity"] = ["warn", 3]; + sonarjs.configs.recommended.rules["sonarjs/cognitive-complexity"] = ${JSON.stringify(setting)}; const { default: configs } = await import("./eslint.config.mjs"); const config = configs.find(config => config.rules); process.stdout.write(JSON.stringify(config.rules["sonarjs/cognitive-complexity"])); @@ -71,6 +130,6 @@ describe("lint enforcement contract", () => { expect(run.error).toBeUndefined(); expect(run.status).toBe(0); expect(run.stderr).toBe(""); - expect(JSON.parse(run.stdout)).toEqual(["error", 3]); + expect(JSON.parse(run.stdout)).toEqual(expected); }); }); From 3757ba04ce6b368a2e7a845cb033f789dcfcb4b9 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 18 Sep 2026 22:43:26 +0000 Subject: [PATCH 03/20] test: resolve trusted tools and document intentional lint fixtures Amp-Thread-ID: https://ampcode.com/threads/T-01a0b6a1-ba97-7390-b562-9225304d4bbf Co-authored-by: Amp --- test/applier.test.ts | 2 +- test/check-import-graph.test.ts | 2 +- test/check-profile-claims.test.ts | 2 +- test/encoding-survival.regression.test.ts | 6 ++++++ test/gen-coderabbit-config.test.ts | 4 ++-- test/invariant-ids.test.ts | 3 ++- test/portable-harness.test.ts | 13 ++++++++----- test/process-helpers.ts | 20 ++++++++++++++++++++ test/purity.test.ts | 7 +++++-- test/release-retry.test.ts | 10 ++++++---- test/stateless.test.ts | 2 +- test/upstream-pins.test.ts | 13 +++++++------ 12 files changed, 60 insertions(+), 24 deletions(-) create mode 100644 test/process-helpers.ts diff --git a/test/applier.test.ts b/test/applier.test.ts index ea711e58..45a326b2 100644 --- a/test/applier.test.ts +++ b/test/applier.test.ts @@ -33,7 +33,7 @@ import { type WorkflowNode, } from "../src/index.js"; import { noOpIds, rejectedOutcome } from "./apply-result-helpers.js"; -import { canonicalize, loadCatalog, loadLwwVectors, loadSession, sessionFiles } from "./helpers.js"; +import { loadCatalog, loadLwwVectors, loadSession, sessionFiles } from "./helpers.js"; const catalog = loadCatalog(); const lww = loadLwwVectors(); diff --git a/test/check-import-graph.test.ts b/test/check-import-graph.test.ts index 73de09e5..a9a12dc9 100644 --- a/test/check-import-graph.test.ts +++ b/test/check-import-graph.test.ts @@ -26,7 +26,7 @@ const script = join(repoRoot, "scripts", "check-import-graph.mjs"); function runAgainst(root: string, minModules?: number) { const env: NodeJS.ProcessEnv = { ...process.env, IMPORT_GRAPH_ROOT: root }; if (minModules !== undefined) env.IMPORT_GRAPH_MIN_MODULES = String(minModules); - return spawnSync("node", [script], { encoding: "utf8", env }); + return spawnSync(process.execPath, [script], { encoding: "utf8", env }); } describe("check-import-graph gate", () => { diff --git a/test/check-profile-claims.test.ts b/test/check-profile-claims.test.ts index 54a466bd..ab884054 100644 --- a/test/check-profile-claims.test.ts +++ b/test/check-profile-claims.test.ts @@ -10,7 +10,7 @@ const script = join(repoRoot, "scripts", "check-profile-claims.mjs"); /** Run the gate against an isolated fixture root (its own checks dir + targets). */ function runAgainst(root: string) { - return spawnSync("node", [script], { + return spawnSync(process.execPath, [script], { encoding: "utf8", env: { ...process.env, diff --git a/test/encoding-survival.regression.test.ts b/test/encoding-survival.regression.test.ts index c5c1c1e0..29f6493e 100644 --- a/test/encoding-survival.regression.test.ts +++ b/test/encoding-survival.regression.test.ts @@ -621,8 +621,11 @@ describe("the correction stops at the boundary of the pending decision", () => { ["a Map nested at depth 3", { a: { b: { c: new Map() } } }], ["a Map nested in an array", [new Map()]], ["a Date nested at depth 1", { a: new Date(0) }], + // eslint-disable-next-line sonarjs/no-primitive-wrappers -- Boxed values are the lossy-but-accepted regression inputs, not accidental primitive coercions. ["a boxed Number at depth 0", new Number(1)], + // eslint-disable-next-line sonarjs/no-primitive-wrappers -- Preserve the distinct boxed string encoding-loss case. ["a boxed String at depth 0", new String("ab")], + // eslint-disable-next-line sonarjs/no-primitive-wrappers -- Preserve the distinct boxed boolean encoding-loss case. ["a boxed Boolean at depth 0", new Boolean(true)], ]; @@ -728,8 +731,11 @@ const SHALLOW_SAMPLES: Array<[string, () => unknown]> = [ ["BigInt 2^63", () => 2n ** 63n], ["BigInt 2^70", () => 2n ** 70n], ["BigInt -2^63-1", () => -(2n ** 63n) - 1n], + // eslint-disable-next-line sonarjs/no-primitive-wrappers -- The encoder matrix must distinguish a boxed number from its primitive value. ["boxed Number", () => new Number(1)], + // eslint-disable-next-line sonarjs/no-primitive-wrappers -- The encoder matrix must retain boxed string identity. ["boxed String", () => new String("ab")], + // eslint-disable-next-line sonarjs/no-primitive-wrappers -- The encoder matrix must retain boxed boolean identity. ["boxed Boolean", () => new Boolean(true)], ["class instance", () => new Instance()], ["null-prototype object", () => Object.assign(Object.create(null), { a: 1 })], diff --git a/test/gen-coderabbit-config.test.ts b/test/gen-coderabbit-config.test.ts index f424e839..0577166e 100644 --- a/test/gen-coderabbit-config.test.ts +++ b/test/gen-coderabbit-config.test.ts @@ -9,7 +9,7 @@ const repoRoot = dirname(dirname(fileURLToPath(import.meta.url))); const script = join(repoRoot, "scripts", "gen-coderabbit-config.mjs"); function run(root: string, ...args: string[]) { - return spawnSync("node", [script, ...args], { + return spawnSync(process.execPath, [script, ...args], { encoding: "utf8", env: { ...process.env, CODERABBIT_GEN_ROOT: root }, }); @@ -537,7 +537,7 @@ describe("gen-coderabbit-config", () => { it("the committed .coderabbit.yaml matches the committed profiles", () => { // The gate CI runs, run here too: `npm test` alone catches the drift. - const real = spawnSync("node", [script], { encoding: "utf8" }); + const real = spawnSync(process.execPath, [script], { encoding: "utf8" }); expect(real.stderr).toBe(""); expect(real.status).toBe(0); expect(real.stdout).toMatch(/^coderabbit-config check PASSED /); diff --git a/test/invariant-ids.test.ts b/test/invariant-ids.test.ts index 6c3de5eb..4d7ec665 100644 --- a/test/invariant-ids.test.ts +++ b/test/invariant-ids.test.ts @@ -22,6 +22,7 @@ import { readFileSync } from "node:fs"; import { dirname, extname, join } from "node:path"; import { fileURLToPath } from "node:url"; import { describe, expect, it } from "vitest"; +import { systemExecutable } from "./process-helpers.js"; const root = dirname(dirname(fileURLToPath(import.meta.url))); const REGISTER = "docs/INVARIANTS.md"; @@ -40,7 +41,7 @@ const HEADING = /^### ((?:KA|FC)-\d+)(?![\w-])/gm; 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 }); + const listed = spawnSync(systemExecutable("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") diff --git a/test/portable-harness.test.ts b/test/portable-harness.test.ts index 0281ddd1..f37a4727 100644 --- a/test/portable-harness.test.ts +++ b/test/portable-harness.test.ts @@ -5,6 +5,7 @@ import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; import { runInNewContext } from "node:vm"; import { afterEach, describe, expect, it } from "vitest"; +import { systemExecutable } from "./process-helpers.js"; const repoRoot = dirname(dirname(fileURLToPath(import.meta.url))); const temporary: string[] = []; @@ -134,8 +135,8 @@ describe("portable harness regressions", () => { }, ])("the documented SonarJS command classifies $name", ({ name, eslintStatus, output, expected, selectedFiles = ["fixture.ts"] }) => { const profile = readFileSync(join(repoRoot, ".agents/checks/sonarjs-lint.md"), "utf8"); - const command = [...profile.matchAll(/```bash\n([\s\S]*?)\n\s*```/g)] - .map((match) => match[1]) + const command = profile.split("```bash\n").slice(1) + .map((block) => block.split("```")[0]) .find((block) => block?.includes("npx eslint")); expect(command).toBeDefined(); expect(command).not.toContain("npm i"); @@ -146,7 +147,7 @@ describe("portable harness regressions", () => { writeFileSync(join(ambientBin, "node"), "#!/bin/sh\necho hostile ambient node >&2\nexit 127\n"); chmodSync(join(bin, "npx"), 0o755); chmodSync(join(ambientBin, "node"), 0o755); - const run = spawnSync("bash", ["-c", command!, "sonarjs-lint-test", ...selectedFiles], { + const run = spawnSync(systemExecutable("bash"), ["-c", command!, "sonarjs-lint-test", ...selectedFiles], { encoding: "utf8", cwd: bin, env: { ...process.env, PATH: `${bin}:${ambientBin}:/usr/bin:/bin` }, @@ -200,7 +201,7 @@ describe("portable harness regressions", () => { const stages = join(root, "stages"); mkdirSync(stages); const npmLog = join(root, "npm.log"); - const run = spawnSync("bash", [join(repoRoot, "examples/dochost-poc/run.sh")], { + const run = spawnSync(systemExecutable("bash"), [join(repoRoot, "examples/dochost-poc/run.sh")], { encoding: "utf8", env: { ...process.env, @@ -245,7 +246,7 @@ describe("portable harness regressions", () => { }); try { const started = Date.now(); - const run = spawnSync("bash", [join(repoRoot, "examples/dochost-poc/run.sh")], { + const run = spawnSync(systemExecutable("bash"), [join(repoRoot, "examples/dochost-poc/run.sh")], { encoding: "utf8", timeout: 2_000, env: { ...process.env, PATH: `${bin}:/usr/bin:/bin`, DOCHOST_SRC: sidecar, PORT: port, HARNESS_CURL_COUNT: join(root, "curl-count") }, @@ -266,7 +267,9 @@ describe("portable harness regressions", () => { const nodes = new Map([["1", { id: "1" }]]); const left = { nodes, links: new Map([["7", { id: "7", targetId: "1" }]]) }; const right = { nodes, links: new Map([["7", { id: "7", targetId: "2" }]]) }; + // eslint-disable-next-line sonarjs/code-eval -- Execute the checked-in benchmark assertion itself to kill its equal-count mutant; never caller input. expect(runInNewContext(assertion!, { ra: left, rb: right })).toBe(false); + // eslint-disable-next-line sonarjs/code-eval -- Same checked-in assertion, positive control proving the harness can accept equal readers. expect(runInNewContext(assertion!, { ra: left, rb: left })).toBe(true); }); }); diff --git a/test/process-helpers.ts b/test/process-helpers.ts new file mode 100644 index 00000000..ae23ef3a --- /dev/null +++ b/test/process-helpers.ts @@ -0,0 +1,20 @@ +import { accessSync, constants } from "node:fs"; +import { join } from "node:path"; + +/** + * These integration tests already require POSIX tools (shell scripts, tar). + * Resolve those tools from system directories, never a fixture-controlled PATH. + * A child's PATH remains independently configurable to exercise fake tools. + */ +export function systemExecutable(name: "bash" | "git" | "tar"): string { + for (const directory of ["/usr/bin", "/bin", "/usr/local/bin"]) { + const executable = join(directory, name); + try { + accessSync(executable, constants.X_OK); + return executable; + } catch { + // Try the next system location; absence is an explicit test setup failure. + } + } + throw new Error(`Required POSIX test tool ${name} is not installed in a system directory`); +} diff --git a/test/purity.test.ts b/test/purity.test.ts index 291ea8c9..dda6c05f 100644 --- a/test/purity.test.ts +++ b/test/purity.test.ts @@ -1,7 +1,7 @@ import { spawnSync } from "node:child_process"; import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; -import { dirname, join } from "node:path"; +import { dirname, isAbsolute, join } from "node:path"; import { fileURLToPath, pathToFileURL } from "node:url"; import { describe, expect, it } from "vitest"; @@ -10,7 +10,10 @@ const distEntry = join(root, "dist", "index.js"); describe("purity", () => { it("has exactly yjs as its declared and resolved production dependency root", () => { - const run = spawnSync("npm", ["ls", "--omit=dev", "--json", "--all"], { + const npmCli = process.env.npm_execpath; + expect(npmCli, "Run tests through npm test or npx vitest to supply the npm CLI path").toBeDefined(); + expect(isAbsolute(npmCli!)).toBe(true); + const run = spawnSync(process.execPath, [npmCli!, "ls", "--omit=dev", "--json", "--all"], { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024, diff --git a/test/release-retry.test.ts b/test/release-retry.test.ts index f9616c9d..3deb5d23 100644 --- a/test/release-retry.test.ts +++ b/test/release-retry.test.ts @@ -5,6 +5,7 @@ import { tmpdir } from "node:os"; import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; import { describe, expect, it } from "vitest"; +import { systemExecutable } from "./process-helpers.js"; const root = dirname(dirname(fileURLToPath(import.meta.url))); const script = join(root, "scripts/release-retry.mjs"); @@ -74,7 +75,7 @@ function fixture() { writeFileSync(join(dir, "package.json"), JSON.stringify({ name, version })); writeFileSync(join(dir, "package/package.json"), JSON.stringify({ name, version })); const local = join(dir, "local.tgz"); - const tar = spawnSync("tar", ["-czf", local, "package/package.json"], { cwd: dir }); + const tar = spawnSync(systemExecutable("tar"), ["-czf", local, "package/package.json"], { cwd: dir }); if (tar.status !== 0) throw new Error("could not create real tar fixture"); const digest = createHash("sha512").update(readFileSync(local)).digest(); const integrity = `sha512-${digest.toString("base64")}`; @@ -141,7 +142,8 @@ function absent(f: Fixture) { function existingRelease(f: Fixture) { f.data.releaseStatus = 0; - f.data.release = `HTTP/2.0 200 OK\r\nContent-Type: application/json\r\n\r\n${JSON.stringify({ tag_name: `v${version}`, draft: false })}`; + const body = JSON.stringify({ tag_name: `v${version}`, draft: false }); + f.data.release = `HTTP/2.0 200 OK\r\nContent-Type: application/json\r\n\r\n${body}`; } describe("release retry subprocess orchestration (offline)", () => { @@ -211,7 +213,7 @@ describe("release retry subprocess orchestration (offline)", () => { // identity checks must not accidentally stand in for byte comparison. writeFileSync(join(f.dir, "package/extra.txt"), "different artifact"); f.data.download = join(f.dir, "different.tgz"); - expect(spawnSync("tar", ["-czf", f.data.download, "package"], { cwd: f.dir }).status).toBe(0); + expect(spawnSync(systemExecutable("tar"), ["-czf", f.data.download, "package"], { cwd: f.dir }).status).toBe(0); }], ["download unavailable", (f) => { f.data.downloadStatus = "503"; }], ["different install integrity", (f) => { f.data.lockIntegrity = "sha512-wrong"; }], @@ -268,7 +270,7 @@ describe("release retry subprocess orchestration (offline)", () => { it.each(["name", "version"])("rejects conflicting %s inside the actual local archive", (field) => { const result = run((f) => { writeFileSync(join(f.dir, "package/package.json"), JSON.stringify({ name, version, [field]: "other" })); - expect(spawnSync("tar", ["-czf", f.data.local, "package/package.json"], { cwd: f.dir }).status).toBe(0); + expect(spawnSync(systemExecutable("tar"), ["-czf", f.data.local, "package/package.json"], { cwd: f.dir }).status).toBe(0); const digest = createHash("sha512").update(readFileSync(f.data.local)).digest(); f.data.lockIntegrity = `sha512-${digest.toString("base64")}`; (f.data.metadata as { dist: { integrity: string } }).dist.integrity = f.data.lockIntegrity; diff --git a/test/stateless.test.ts b/test/stateless.test.ts index 29e42fb1..c0485237 100644 --- a/test/stateless.test.ts +++ b/test/stateless.test.ts @@ -4,7 +4,7 @@ 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 type { Op } from "../src/index.js"; import { loadCatalog } from "./helpers.js"; const catalog = loadCatalog(); diff --git a/test/upstream-pins.test.ts b/test/upstream-pins.test.ts index 2c43647e..0860c795 100644 --- a/test/upstream-pins.test.ts +++ b/test/upstream-pins.test.ts @@ -16,6 +16,7 @@ import { tmpdir } from "node:os"; import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; import { describe, expect, it } from "vitest"; +import { systemExecutable } from "./process-helpers.js"; const root = dirname(dirname(fileURLToPath(import.meta.url))); @@ -103,8 +104,8 @@ describe("FC-10 — upstream citations are pinned by SHA, not by branch", () => `esac\n`, ); chmodSync(fakeGh, 0o755); - expect(spawnSync("git", ["init", "--quiet"], { cwd: fixture }).status).toBe(0); - expect(spawnSync("git", ["add", "."], { cwd: fixture }).status).toBe(0); + expect(spawnSync(systemExecutable("git"), ["init", "--quiet"], { cwd: fixture }).status).toBe(0); + expect(spawnSync(systemExecutable("git"), ["add", "."], { cwd: fixture }).status).toBe(0); const run = spawnSync(process.execPath, [join(root, "scripts", "check-pins.mjs"), "--verify-remote"], { encoding: "utf8", @@ -284,8 +285,8 @@ describe("FC-10 — upstream citations are pinned by SHA, not by branch", () => `esac\n`, ); chmodSync(fakeGh, 0o755); - expect(spawnSync("git", ["init", "--quiet"], { cwd: fixture }).status).toBe(0); - expect(spawnSync("git", ["add", "."], { cwd: fixture }).status).toBe(0); + expect(spawnSync(systemExecutable("git"), ["init", "--quiet"], { cwd: fixture }).status).toBe(0); + expect(spawnSync(systemExecutable("git"), ["add", "."], { cwd: fixture }).status).toBe(0); const run = spawnSync(process.execPath, [join(root, "scripts", "check-pins.mjs"), "--verify-remote"], { encoding: "utf8", @@ -339,8 +340,8 @@ describe("FC-10 — upstream citations are pinned by SHA, not by branch", () => 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); + expect(spawnSync(systemExecutable("git"), ["init", "--quiet"], { cwd: fixture }).status).toBe(0); + expect(spawnSync(systemExecutable("git"), ["add", "."], { cwd: fixture }).status).toBe(0); const run = spawnSync(process.execPath, [join(root, "scripts", "check-pins.mjs")], { encoding: "utf8", From 6e6e1a159e119f9068918b261594dd4a4fecd56b Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 18 Sep 2026 22:43:26 +0000 Subject: [PATCH 04/20] test: retain boxed Lamport counter as an explicit invalid fixture Amp-Thread-ID: https://ampcode.com/threads/T-01a0b6a1-ba97-7390-b562-9225304d4bbf Co-authored-by: Amp --- test/clock.test.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/test/clock.test.ts b/test/clock.test.ts index f4d3596d..d558f05a 100644 --- a/test/clock.test.ts +++ b/test/clock.test.ts @@ -9,6 +9,7 @@ describe("creator-owned Lamport counter", () => { it("validates numeric boundaries without coercing unknown inputs", () => { for (const allowZero of [false, true]) { const message = `Lamport counter must be a ${allowZero ? "non-negative" : "positive"} safe integer`; + // eslint-disable-next-line sonarjs/no-primitive-wrappers -- A boxed counter must be rejected without coercion; a primitive would destroy this regression input. for (const value of ["1", 1n, true, null, undefined, Symbol("counter"), {}, new Number(1), -1, 0.5, NaN, Infinity, Number.MAX_SAFE_INTEGER + 1]) { expect(() => validateLamportCounter(value, allowZero)).toThrow(RangeError); expect(() => validateLamportCounter(value, allowZero)).toThrow(new RangeError(message)); From 36ae7a070d23ec0b6b132b74423676ac446e5100 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 18 Sep 2026 22:45:29 +0000 Subject: [PATCH 05/20] refactor: separate payload traversal from budget admission Preserve KA-4 refusal order and cost accounting; add inclusive boundary and repeated-reference budget assertions. No input sandbox claim. Amp-Thread-ID: https://ampcode.com/threads/T-01a0b6a1-ba97-7390-b562-9225304d4bbf Co-authored-by: Amp --- src/limits.ts | 75 ++++++++++++++++++------------------- test/payload-budget.test.ts | 26 +++++++++++++ 2 files changed, 62 insertions(+), 39 deletions(-) create mode 100644 test/payload-budget.test.ts diff --git a/src/limits.ts b/src/limits.ts index c3bdbf7c..6301cadd 100644 --- a/src/limits.ts +++ b/src/limits.ts @@ -58,6 +58,39 @@ type Frame = | { readonly kind: "enter"; readonly value: unknown; readonly depth: number } | { readonly kind: "leave"; readonly container: object }; +/** Charge one value and queue its children in the original traversal order. */ +function queuePayloadChildren(value: unknown, depth: number, onPath: Set, stack: Frame[], cost: number): { cost: number } | { refusal: string } { + if (typeof value === "string") return { cost: cost + value.length }; + if (typeof value !== "object" || value === null) return { cost: cost + 8 }; + // Back-edge: termination handled, refusal deferred to A8 canonicalization. + if (onPath.has(value)) return { cost }; + if (ArrayBuffer.isView(value)) return { cost: cost + value.byteLength }; + if (value instanceof ArrayBuffer) return { cost: cost + value.byteLength }; + if (Array.isArray(value)) { + if (value.length > MAX_COLLECTION_ENTRIES) { + return { refusal: `an array of ${value.length} entries exceeds the ${MAX_COLLECTION_ENTRIES}-entry limit (#14)` }; + } + onPath.add(value); + stack.push({ kind: "leave", container: value }); + for (const item of value) stack.push({ kind: "enter", value: item, depth: depth + 1 }); + return { cost: cost + 4 }; + } + // Any other object is walked as a bag of its own enumerable keys — + // the same shape `structuredClone` and `writeAny` would traverse. + const keys = Object.keys(value); + if (keys.length > MAX_COLLECTION_ENTRIES) { + return { refusal: `an object of ${keys.length} keys exceeds the ${MAX_COLLECTION_ENTRIES}-entry limit (#14)` }; + } + cost += 4; + onPath.add(value); + stack.push({ kind: "leave", container: value }); + for (const key of keys) { + cost += key.length; + stack.push({ kind: "enter", value: (value as Record)[key], depth: depth + 1 }); + } + return { cost }; +} + /** * Why an op exceeds the untrusted-payload budget, or `null` to accept it. * Iterative (no recursion on hostile depth), cycle-tolerant (back-edges are @@ -84,45 +117,9 @@ export function opBoundsRefusal(op: unknown): string | null { } cost += 1; // every visit costs ≥1 → the walk is bounded by MAX_OP_COST - if (typeof value === "string") { - cost += value.length; - } else if (typeof value === "object" && value !== null) { - if (onPath.has(value)) { - // Back-edge: termination handled, refusal deferred to A8 canonicalization. - } else if (ArrayBuffer.isView(value)) { - cost += value.byteLength; - } else if (value instanceof ArrayBuffer) { - cost += value.byteLength; - } else if (Array.isArray(value)) { - if (value.length > MAX_COLLECTION_ENTRIES) { - return `an array of ${value.length} entries exceeds the ${MAX_COLLECTION_ENTRIES}-entry limit (#14)`; - } - cost += 4; - onPath.add(value); - stack.push({ kind: "leave", container: value }); - for (const item of value) stack.push({ kind: "enter", value: item, depth: depth + 1 }); - } else { - // Any other object is walked as a bag of its own enumerable keys — - // the same shape `structuredClone` and `writeAny` would traverse. - const keys = Object.keys(value); - if (keys.length > MAX_COLLECTION_ENTRIES) { - return `an object of ${keys.length} keys exceeds the ${MAX_COLLECTION_ENTRIES}-entry limit (#14)`; - } - cost += 4; - onPath.add(value); - stack.push({ kind: "leave", container: value }); - for (const key of keys) { - cost += key.length; - stack.push({ - kind: "enter", - value: (value as Record)[key], - depth: depth + 1, - }); - } - } - } else { - cost += 8; // number, bigint, boolean, undefined, symbol, function - } + const visit = queuePayloadChildren(value, depth, onPath, stack, cost); + if ("refusal" in visit) return visit.refusal; + cost = visit.cost; if (cost > MAX_OP_COST) { return `payload exceeds the ${MAX_OP_COST}-unit cost budget (#14)`; diff --git a/test/payload-budget.test.ts b/test/payload-budget.test.ts new file mode 100644 index 00000000..30d248ea --- /dev/null +++ b/test/payload-budget.test.ts @@ -0,0 +1,26 @@ +import { describe, expect, it } from "vitest"; +import { MAX_OP_COST, opBoundsRefusal } from "../src/limits.js"; + +describe("payload budget accounting", () => { + it.each([ + [1, (length: number) => "x".repeat(length)], + [7, (length: number) => ({ a: "x".repeat(length) })], + ] as const)("charges %i units of overhead at the inclusive cost boundary", (overhead, payload) => { + expect(opBoundsRefusal(payload(MAX_OP_COST - overhead))).toBeNull(); + expect(opBoundsRefusal(payload(MAX_OP_COST - overhead + 1))).toBe( + `payload exceeds the ${MAX_OP_COST}-unit cost budget (#14)`, + ); + }); + + it("charges repeated shared references independently, not as cycles", () => { + // Array: 1 visit + 4 container. Each object: 1 visit + 4 container + + // 1 key character + 1 string visit. Final empty string: 1 visit. + // Total = 20 + 2 * string length, independently of traversal implementation. + const shared = { a: "x".repeat((MAX_OP_COST - 20) / 2) }; + expect(opBoundsRefusal([shared, shared, ""])).toBeNull(); + shared.a += "x"; + expect(opBoundsRefusal([shared, shared, ""])).toBe( + `payload exceeds the ${MAX_OP_COST}-unit cost budget (#14)`, + ); + }); +}); From 46ba669d6ca3e5e92af7764c10178dcc22bd4785 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 18 Sep 2026 22:45:29 +0000 Subject: [PATCH 06/20] refactor: clarify cycle traversal and identity comparisons Preserve KA-2/KA-4 and FC-2 ordering, exported Actor string semantics, and rejection traversal while removing nested lint findings. Amp-Thread-ID: https://ampcode.com/threads/T-01a0b6a1-ba97-7390-b562-9225304d4bbf Co-authored-by: Amp --- src/doc.ts | 20 +++++++++----------- src/project.ts | 3 ++- src/stamps.ts | 3 ++- src/types.ts | 4 ++-- 4 files changed, 15 insertions(+), 15 deletions(-) diff --git a/src/doc.ts b/src/doc.ts index 6dd7a980..687156f4 100644 --- a/src/doc.ts +++ b/src/doc.ts @@ -521,6 +521,14 @@ export function referenceCyclePath(value: unknown): string | null { Array.isArray(obj) ? { obj, path, keys: [], next: 0, isArray: true } : { obj, path, keys: Object.keys(obj), next: 0, isArray: false }; + const nextChild = (frame: Frame): [unknown, string] => { + const index = frame.next++; + if (frame.isArray) { + return [(frame.obj as unknown[])[index], `${frame.path}[${String(index)}]`]; + } + const key = frame.keys[index]!; + return [(frame.obj as Record)[key], `${frame.path}.${key}`]; + }; const onPath = new Set([value]); const stack: Frame[] = [frameFor(value, "")]; @@ -532,17 +540,7 @@ export function referenceCyclePath(value: unknown): string | null { stack.pop(); continue; } - const index = frame.next++; - let child: unknown; - let childPath: string; - if (frame.isArray) { - child = (frame.obj as unknown[])[index]; - childPath = `${frame.path}[${String(index)}]`; - } else { - const key = frame.keys[index]!; - child = (frame.obj as Record)[key]; - childPath = `${frame.path}.${key}`; - } + const [child, childPath] = nextChild(frame); if (typeof child !== "object" || child === null) continue; if (child instanceof Uint8Array) continue; if (onPath.has(child)) return childPath; diff --git a/src/project.ts b/src/project.ts index cd97cba7..381c6336 100644 --- a/src/project.ts +++ b/src/project.ts @@ -42,7 +42,8 @@ function idCompare(a: unknown, b: unknown): number { if (typeof a === "number" && typeof b === "number") return a - b; const sa = String(a); const sb = String(b); - return sa < sb ? -1 : sa > sb ? 1 : 0; + if (sa < sb) return -1; + return sa > sb ? 1 : 0; } /** Source-output references are link identities, whose canonical order is numeric. */ diff --git a/src/stamps.ts b/src/stamps.ts index c085d2dd..3e20c54d 100644 --- a/src/stamps.ts +++ b/src/stamps.ts @@ -30,7 +30,8 @@ export function codePointCompare(a: string, b: string): -1 | 0 | 1 { } const ra = a.length - i; const rb = b.length - j; - return ra === rb ? 0 : ra < rb ? -1 : 1; + if (ra === rb) return 0; + return ra < rb ? -1 : 1; } function validStampCounter(counter: number): number { diff --git a/src/types.ts b/src/types.ts index 66aa5f57..47a4820a 100644 --- a/src/types.ts +++ b/src/types.ts @@ -123,7 +123,7 @@ export type BatchableOpKind = (typeof BATCHABLE_OPS)[number]; // --------------------------------------------------------------------------- /** Who minted an op — a frozen origin string (vocabulary §7): `agent::`, `human::`, `system:mint`, legacy `cli`. MUST be ASCII (§8.1). */ -export type Actor = string; +export type Actor = OpBase["actor"]; /** * Node / link identity. comfy-cli mints ints (`mint_id()`, `[2^40, 2^53)`), @@ -160,7 +160,7 @@ export type StampKey = [baseVersion: number, actor: Actor, opId: string]; export interface OpBase { /** Unique op identity: uuid4 hex, 32 lowercase `[0-9a-f]` chars (vocabulary §8.2 — LWW-load-bearing, never regenerated). */ op_id: string; - actor: Actor; + actor: string; /** Doc version the op was minted against. */ base_version: number; /** `[base_version, actor]` — see {@link Stamp}. */ From 4b21c5da46f104af094c9b2aa18ca9cbab7c2936 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 18 Sep 2026 22:46:29 +0000 Subject: [PATCH 07/20] refactor: isolate inserted node link remapping Keep KA-4 deterministic ID derivation and slot scrub semantics unchanged. Amp-Thread-ID: https://ampcode.com/threads/T-01a0b6a1-ba97-7390-b562-9225304d4bbf Co-authored-by: Amp --- src/remap.ts | 46 +++++++++++++++++++++++++--------------------- 1 file changed, 25 insertions(+), 21 deletions(-) diff --git a/src/remap.ts b/src/remap.ts index 197025e5..c66664ee 100644 --- a/src/remap.ts +++ b/src/remap.ts @@ -34,6 +34,29 @@ export function linkHasMissingEndpoint(link: unknown, hasNode: (id: unknown) => return endpoints !== undefined && (!hasNode(endpoints[0]) || !hasNode(endpoints[1])); } +function remapInputs(inputs: unknown, linkIds: Map, droppedLinkIds: Set): void { + if (!Array.isArray(inputs)) return; + for (const input of inputs) { + if (typeof input !== "object" || input === null || !("link" in input)) continue; + const record = input as { link?: unknown }; + if (record.link === null || record.link === undefined) continue; + const id = normalizedId(record.link); + if (droppedLinkIds.has(id)) record.link = null; + else if (linkIds.has(id)) record.link = linkIds.get(id); + } +} + +function remapOutputs(outputs: unknown, linkIds: Map, droppedLinkIds: Set): void { + if (!Array.isArray(outputs)) return; + for (const output of outputs) { + if (typeof output !== "object" || output === null || !Array.isArray((output as { links?: unknown }).links)) continue; + const record = output as { links: unknown[] }; + record.links = record.links + .filter((id) => !droppedLinkIds.has(normalizedId(id))) + .map((id) => linkIds.get(normalizedId(id)) ?? id); + } +} + function remapGraph( graph: Record, opId: string, @@ -60,27 +83,8 @@ function remapGraph( for (const node of nodes) { node.id = nodeIds.get(normalizedId(node.id))!; if (definitionIds.has(node.type)) node.type = definitionIds.get(node.type)!; - if (Array.isArray(node.inputs)) { - for (const input of node.inputs) { - if (typeof input === "object" && input !== null && "link" in input) { - const record = input as { link?: unknown }; - if (record.link === null || record.link === undefined) continue; - const id = normalizedId(record.link); - if (droppedLinkIds.has(id)) record.link = null; - else if (linkIds.has(id)) record.link = linkIds.get(id); - } - } - } - if (Array.isArray(node.outputs)) { - for (const output of node.outputs) { - if (typeof output === "object" && output !== null && Array.isArray((output as { links?: unknown }).links)) { - const record = output as { links: unknown[] }; - record.links = record.links - .filter((id) => !droppedLinkIds.has(normalizedId(id))) - .map((id) => linkIds.get(normalizedId(id)) ?? id); - } - } - } + remapInputs(node.inputs, linkIds, droppedLinkIds); + remapOutputs(node.outputs, linkIds, droppedLinkIds); } graph["links"] = links.map((link) => { if (Array.isArray(link)) { From faea724a61ea49827a49ca81ff16622b7a2adcaa Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 18 Sep 2026 22:46:29 +0000 Subject: [PATCH 08/20] refactor: separate definition minting responsibilities Preserve KA-3/KA-4 and FC-3 Yjs layout, validation order, and link identity. Keep imported node/link order and malformed-link fallback keys unchanged. Amp-Thread-ID: https://ampcode.com/threads/T-01a0b6a1-ba97-7390-b562-9225304d4bbf Co-authored-by: Amp --- src/mint.ts | 170 +++++++++++++++++++++++++++++----------------------- 1 file changed, 94 insertions(+), 76 deletions(-) diff --git a/src/mint.ts b/src/mint.ts index f5bb4fba..49366901 100644 --- a/src/mint.ts +++ b/src/mint.ts @@ -116,30 +116,32 @@ export function mint(workflow: WorkflowJSON, catalog: WidgetCatalog, catalogVers else linkState.set(key, cloneForMap(state, `mint: link state ${key}`)); } - const defsIn = workflow["definitions"]; - if (defsIn !== undefined && defsIn !== null) { - if (typeof defsIn !== "object" || Array.isArray(defsIn)) { - throw new TypeError("mint: workflow.definitions must be an object"); - } - const { subgraphs, ...rest } = defsIn as { subgraphs?: unknown; [key: string]: unknown }; - // The fifth ungated passthrough write: `__definitions_extra` reached a - // Y.Map through a bare `structuredClone`. Shallow verdicts are unchanged - // (`rest` is always a plain object), but a cycle inside it would have - // bricked the document exactly as any other passthrough would. - const extra = cloneForMap(rest, "mint: workflow.definitions") as Record; - // Preserve an explicitly-empty subgraphs array through the round trip. - if (Array.isArray(subgraphs) && subgraphs.length === 0) extra["subgraphs"] = []; - meta.set("__definitions_extra", extra); - const defsRoot = definitionsMap(doc); - for (const sg of Array.isArray(subgraphs) ? (subgraphs as SubgraphDef[]) : []) { - if (sg.id === undefined || sg.id === null) throw new TypeError("mint: definition is missing id"); - defsRoot.set(String(sg.id), mintDefinition(sg, catalog)); - } - } + mintWorkflowDefinitions(doc, workflow["definitions"], catalog); }); return doc; } +function mintWorkflowDefinitions(doc: Y.Doc, defsIn: unknown, catalog: WidgetCatalog): void { + if (defsIn === undefined || defsIn === null) return; + if (typeof defsIn !== "object" || Array.isArray(defsIn)) { + throw new TypeError("mint: workflow.definitions must be an object"); + } + const { subgraphs, ...rest } = defsIn as { subgraphs?: unknown; [key: string]: unknown }; + // The fifth ungated passthrough write: `__definitions_extra` reached a + // Y.Map through a bare `structuredClone`. Shallow verdicts are unchanged + // (`rest` is always a plain object), but a cycle inside it would have + // bricked the document exactly as any other passthrough would. + const extra = cloneForMap(rest, "mint: workflow.definitions") as Record; + // Preserve an explicitly-empty subgraphs array through the round trip. + if (Array.isArray(subgraphs) && subgraphs.length === 0) extra["subgraphs"] = []; + metaMap(doc).set("__definitions_extra", extra); + const defsRoot = definitionsMap(doc); + for (const sg of Array.isArray(subgraphs) ? (subgraphs as SubgraphDef[]) : []) { + if (sg.id === undefined || sg.id === null) throw new TypeError("mint: definition is missing id"); + defsRoot.set(String(sg.id), mintDefinition(sg, catalog)); + } +} + function nodeId(value: unknown, context: string): string | number { if (typeof value === "string" && value.length > 0) return value; if (typeof value === "number" && Number.isSafeInteger(value)) return value; @@ -242,6 +244,75 @@ function definitionLinkKey(ln: unknown): string | undefined { return undefined; } +function mintDefinitionNodes(dm: Y.Map, nodes: WorkflowNode[], catalog: WidgetCatalog): void { + const nm = new Y.Map>(); + const order: string[] = []; + for (const node of nodes) { + if (node.id === undefined || node.id === null) throw new TypeError("mint: definition node is missing id"); + const key = String(node.id); + if (order.includes(key)) throw new TypeError(`mint: duplicate definition node id '${key}'`); + order.push(key); + nm.set(key, createNodeMap(node, widgetOrderFor(catalog, node.type))); + } + dm.set("nodes", nm); + dm.set("node_order", order); +} + +function mintDefinitionLinks(dm: Y.Map, links: unknown[]): void { + const lm = new Y.Map(); + const order: string[] = []; + const usedKeys = new Set(); + for (const link of links) { + const key = definitionLinkKey(link); + if (key === undefined) continue; + if (usedKeys.has(key)) throw new TypeError(`mint: duplicate definition link id '${key}'`); + usedKeys.add(key); + } + links.forEach((ln, i) => { + // A definition's interior links are serialized by the frontend as + // OBJECTS (`{id, origin_id, origin_slot, target_id, target_slot, + // type}`), not top-level tuples. Keying every shape by `ln[0]` read + // `undefined` off each object, so every interior link of a real + // template collapsed onto one key and the round trip emitted the last + // one N times (found by the z-image turbo fixture, Amendment A15). + const explicitKey = definitionLinkKey(ln); + let key = explicitKey ?? `#${String(i)}`; + if (explicitKey === undefined) { + const base = key; + let suffix = 1; + while (usedKeys.has(key)) { + key = `${base}~${String(suffix)}`; + suffix += 1; + } + usedKeys.add(key); + } + order.push(key); + lm.set(key, cloneForMap(ln, `mint: definition link ${key}`)); + }); + dm.set("links", lm); + dm.set("link_order", order); +} + +function mintNestedDefinitions(value: object, catalog: WidgetCatalog): Y.Map { + const container = new Y.Map(); + const { subgraphs, ...extra } = value as { subgraphs?: unknown; [key: string]: unknown }; + Object.entries(extra).forEach(([key, entry]) => container.set(key, cloneForMap(entry, `mint: definition.definitions.${key}`))); + if (Array.isArray(subgraphs)) { + const nested = new Y.Map>(); + const order: string[] = []; + for (const child of subgraphs as SubgraphDef[]) { + if (child.id === undefined || child.id === null) throw new TypeError("mint: nested definition is missing id"); + const key = String(child.id); + if (order.includes(key)) throw new TypeError(`mint: duplicate nested definition id '${key}'`); + order.push(key); + nested.set(key, mintDefinition(child, catalog)); + } + container.set("subgraphs", nested); + container.set("subgraph_order", order); + } + return container; +} + export function mintDefinition(sg: SubgraphDef, catalog: WidgetCatalog): Y.Map { for (const key of ["node_order", "link_order", "__definition_digest"]) { if (Object.hasOwn(sg, key)) throw new TypeError(`mint: definition key '${key}' is reserved`); @@ -249,64 +320,11 @@ export function mintDefinition(sg: SubgraphDef, catalog: WidgetCatalog): Y.Map(); for (const [k, v] of Object.entries(sg)) { if (k === "nodes" && Array.isArray(v)) { - const nm = new Y.Map>(); - const order: string[] = []; - for (const n of v as WorkflowNode[]) { - if (n.id === undefined || n.id === null) throw new TypeError("mint: definition node is missing id"); - const key = String(n.id); - if (order.includes(key)) throw new TypeError(`mint: duplicate definition node id '${key}'`); - order.push(key); - nm.set(key, createNodeMap(n, widgetOrderFor(catalog, n.type))); - } - dm.set("nodes", nm); - dm.set("node_order", order); + mintDefinitionNodes(dm, v as WorkflowNode[], catalog); } else if (k === "links" && Array.isArray(v)) { - const lm = new Y.Map(); - const order: string[] = []; - const usedKeys = new Set(); - for (const link of v) { - const key = definitionLinkKey(link); - if (key === undefined) continue; - if (usedKeys.has(key)) throw new TypeError(`mint: duplicate definition link id '${key}'`); - usedKeys.add(key); - } - v.forEach((ln, i) => { - // A definition's interior links are serialized by the frontend as - // OBJECTS (`{id, origin_id, origin_slot, target_id, target_slot, - // type}`), not top-level tuples. Keying every shape by `ln[0]` read - // `undefined` off each object, so every interior link of a real - // template collapsed onto one key and the round trip emitted the last - // one N times (found by the z-image turbo fixture, Amendment A15). - const explicitKey = definitionLinkKey(ln); - let key = explicitKey ?? `#${String(i)}`; - if (explicitKey === undefined) { - const base = key; - for (let suffix = 1; usedKeys.has(key); suffix += 1) key = `${base}~${String(suffix)}`; - usedKeys.add(key); - } - order.push(key); - lm.set(key, cloneForMap(ln, `mint: definition link ${key}`)); - }); - dm.set("links", lm); - dm.set("link_order", order); + mintDefinitionLinks(dm, v); } else if (k === "definitions" && typeof v === "object" && v !== null && !Array.isArray(v)) { - const container = new Y.Map(); - const { subgraphs, ...extra } = v as { subgraphs?: unknown; [key: string]: unknown }; - Object.entries(extra).forEach(([key, value]) => container.set(key, cloneForMap(value, `mint: definition.definitions.${key}`))); - if (Array.isArray(subgraphs)) { - const nested = new Y.Map>(); - const order: string[] = []; - for (const child of subgraphs as SubgraphDef[]) { - if (child.id === undefined || child.id === null) throw new TypeError("mint: nested definition is missing id"); - const key = String(child.id); - if (order.includes(key)) throw new TypeError(`mint: duplicate nested definition id '${key}'`); - order.push(key); - nested.set(key, mintDefinition(child, catalog)); - } - container.set("subgraphs", nested); - container.set("subgraph_order", order); - } - dm.set("definitions", container); + dm.set("definitions", mintNestedDefinitions(v, catalog)); } else { dm.set(k, cloneForMap(v, `mint: definition.${k}`)); } From 883786c8a2c5986a3ea4796b29f64ca73e892b66 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 18 Sep 2026 22:47:06 +0000 Subject: [PATCH 09/20] ci: enforce strict package lint without masking failures Amp-Thread-ID: https://ampcode.com/threads/T-01a0b6a1-ba97-7390-b562-9225304d4bbf Co-authored-by: Amp --- .github/workflows/ci.yml | 3 +++ test/ci-release-contract.test.ts | 16 +++++++++++++++- 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 68d7ea8a..7dbccbec 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -41,6 +41,9 @@ jobs: - name: Type-check gate run: npm run typecheck + - name: Lint gate + run: npm run lint + - name: Purity gate run: npm run check:purity diff --git a/test/ci-release-contract.test.ts b/test/ci-release-contract.test.ts index e087671b..643b2557 100644 --- a/test/ci-release-contract.test.ts +++ b/test/ci-release-contract.test.ts @@ -60,7 +60,8 @@ function requireWorkflow(document: unknown, jobId: string): void { throw new Error("required gates must use the default runner shell"); } const steps = job.steps ?? []; - for (const [name, command] of Object.entries(REQUIRED_STEPS)) { + const requiredSteps = jobId === "ci" ? { ...REQUIRED_STEPS, "Lint gate": "npm run lint" } : REQUIRED_STEPS; + for (const [name, command] of Object.entries(requiredSteps)) { const matches = steps.filter((step) => step.name === name); if (matches.length !== 1 || !unconditionalGate(matches[0]!) || matches[0]!.run?.trim() !== command) { throw new Error(`missing active, failure-propagating ${name}: ${command}`); @@ -149,6 +150,19 @@ describe("standalone package ownership", () => { }); describe("parsed CI and release contracts", () => { + it.each([ + ["missing", (step: Step) => { step.name = "comment-only lint"; }], + ["conditional", (step: Step) => { step.if = "${{ false }}"; }], + ["non-fatal", (step: Step) => { step["continue-on-error"] = true; }], + ["masked exit", (step: Step) => { step.run = "npm run lint || true"; }], + ] as const)("rejects a %s lint gate", (_name, change) => { + const document = loadYaml(".github/workflows/ci.yml") as CiFixture; + const lint = document.jobs.ci.steps.find((step) => step.name === "Lint gate"); + expect(lint).toBeDefined(); + change(lint!); + expect(() => requireWorkflow(document, "ci")).toThrow("missing active, failure-propagating Lint gate"); + }); + it.each([["ci", "ci"], ["release", "publish"]])( "%s runs every required gate and propagates failure", (file, job) => requireWorkflow(loadYaml(`.github/workflows/${file}.yml`), job), From 346be8cf71024d992afb2e1a62995ca96bc6e01f Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 18 Sep 2026 22:51:03 +0000 Subject: [PATCH 10/20] refactor: separate trace validation responsibilities Amp-Thread-ID: https://ampcode.com/threads/T-01a0b6a1-ba97-7390-b562-9225304d4bbf Co-authored-by: Amp --- src/collab-trace.ts | 205 +++++++++++++++++++++++++++----------------- 1 file changed, 127 insertions(+), 78 deletions(-) diff --git a/src/collab-trace.ts b/src/collab-trace.ts index 4589c23a..685aff38 100644 --- a/src/collab-trace.ts +++ b/src/collab-trace.ts @@ -258,27 +258,35 @@ function assertJsonValue(value: unknown, context: string, ancestors = new Set key !== "length" && (typeof key !== "string" || !/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= value.length))) { - invalid(context, "must be canonical JSON data without ignored array properties"); - } - for (let index = 0; index < value.length; index++) { - if (!Object.hasOwn(value, index)) invalid(`${context}[${index}]`, "must be canonical JSON data without sparse entries"); - assertJsonValue(value[index], `${context}[${index}]`, ancestors); - } + assertJsonArray(value, context, ancestors); } else { - const prototype = Object.getPrototypeOf(value); - if (prototype !== Object.prototype && prototype !== null) invalid(context, "must be a canonical JSON object"); - for (const key of Reflect.ownKeys(value)) { - if (typeof key !== "string") invalid(context, "must be canonical JSON data without symbol keys"); - const descriptor = Object.getOwnPropertyDescriptor(value, key)!; - if (!descriptor.enumerable || !("value" in descriptor)) invalid(`${context}.${key}`, "must be canonical JSON data without ignored or computed properties"); - assertJsonValue(descriptor.value, `${context}.${key}`, ancestors); - } + assertJsonObject(value, context, ancestors); } ancestors.delete(value); } +function assertJsonArray(value: unknown[], context: string, ancestors: Set): void { + const ownKeys = Reflect.ownKeys(value); + if (ownKeys.some((key) => key !== "length" && (typeof key !== "string" || !/^(0|[1-9]\d*)$/.test(key) || Number(key) >= value.length))) { + invalid(context, "must be canonical JSON data without ignored array properties"); + } + for (let index = 0; index < value.length; index++) { + if (!Object.hasOwn(value, index)) invalid(`${context}[${index}]`, "must be canonical JSON data without sparse entries"); + assertJsonValue(value[index], `${context}[${index}]`, ancestors); + } +} + +function assertJsonObject(value: object, context: string, ancestors: Set): void { + const prototype = Object.getPrototypeOf(value); + if (prototype !== Object.prototype && prototype !== null) invalid(context, "must be a canonical JSON object"); + for (const key of Reflect.ownKeys(value)) { + if (typeof key !== "string") invalid(context, "must be canonical JSON data without symbol keys"); + const descriptor = Object.getOwnPropertyDescriptor(value, key)!; + if (!descriptor.enumerable || !("value" in descriptor)) invalid(`${context}.${key}`, "must be canonical JSON data without ignored or computed properties"); + assertJsonValue(descriptor.value, `${context}.${key}`, ancestors); + } +} + function assertHash(value: unknown, context: string): TraceHash { const hash = asRecord(value, context); const algorithm = asOneOf(required(hash, "algorithm", context), ["sha256"] as const, `${context}.algorithm`); @@ -352,7 +360,7 @@ function assertOpPayload(value: unknown, context: string) { const stamp = assertStamp(required(payload, "stamp", context), `${context}.stamp`); if (stamp[1] !== actor) invalid(`${context}.stamp`, "does not preserve semantic identity"); - if (op === "insert_workflow") { + function assertWorkflowInsertion(): void { const workflow = asRecord(required(payload, "workflow", context), `${context}.workflow`); asArray(required(workflow, "nodes", `${context}.workflow`), `${context}.workflow.nodes`); if (Object.hasOwn(workflow, "links")) asArray(workflow["links"], `${context}.workflow.links`); @@ -362,7 +370,8 @@ function assertOpPayload(value: unknown, context: string) { asArray(definitions["subgraphs"], `${context}.workflow.definitions.subgraphs`); } } - } else if (op === "add_node") { + } + function assertNodeAddition(): void { const nodeId = asNodeId(required(payload, "node_id", context), `${context}.node_id`); const classType = asString(required(payload, "class_type", context), `${context}.class_type`); assertNumberArray(required(payload, "pos", context), `${context}.pos`); @@ -370,7 +379,8 @@ function assertOpPayload(value: unknown, context: string) { if (String(asNodeId(required(node, "id", `${context}.node`), `${context}.node.id`)) !== String(nodeId)) invalid(`${context}.node.id`, "does not match node_id"); if (asString(required(node, "type", `${context}.node`), `${context}.node.type`) !== classType) invalid(`${context}.node.type`, "does not match class_type"); assertOptionalString(payload, "node_incarnation", context); - } else if (op === "connect") { + } + function assertConnection(): void { asNodeId(required(payload, "link_id", context), `${context}.link_id`); asNodeId(required(payload, "from_node", context), `${context}.from_node`); asInteger(required(payload, "from_slot", context), `${context}.from_slot`); @@ -393,7 +403,15 @@ function assertOpPayload(value: unknown, context: string) { required(inputcount, "value", `${context}.grow.inputcount`); } } - } else if (op === "set_widget") { + } + function assertPromotedWidgetWrite(): void { + const promoted = asRecord(payload["promoted"], `${context}.promoted`); + const valueIndex = asInteger(required(promoted, "value_index", `${context}.promoted`), `${context}.promoted.value_index`); + const hostValues = asArray(required(promoted, "host_widgets_values", `${context}.promoted`), `${context}.promoted.host_widgets_values`); + if (hostValues.length <= valueIndex) invalid(`${context}.promoted.host_widgets_values`, "must cover value_index"); + if (Object.hasOwn(promoted, "instance_path")) assertNodeIdArray(promoted["instance_path"], `${context}.promoted.instance_path`); + } + function assertWidgetWrite(): void { asNodeId(required(payload, "node_id", context), `${context}.node_id`); asString(required(payload, "widget", context), `${context}.widget`); if (required(payload, "value", context) === undefined) invalid(`${context}.value`, "must be JSON-representable"); @@ -409,35 +427,42 @@ function assertOpPayload(value: unknown, context: string) { } else if (payload["inner_widget"] !== undefined && payload["inner_widget"] !== null) { invalid(`${context}.inner_widget`, "requires a non-empty path"); } else if (payload["promoted"] !== undefined && payload["promoted"] !== null) { - const promoted = asRecord(payload["promoted"], `${context}.promoted`); - const valueIndex = asInteger(required(promoted, "value_index", `${context}.promoted`), `${context}.promoted.value_index`); - const hostValues = asArray(required(promoted, "host_widgets_values", `${context}.promoted`), `${context}.promoted.host_widgets_values`); - if (hostValues.length <= valueIndex) invalid(`${context}.promoted.host_widgets_values`, "must cover value_index"); - if (Object.hasOwn(promoted, "instance_path")) assertNodeIdArray(promoted["instance_path"], `${context}.promoted.instance_path`); + assertPromotedWidgetWrite(); } - } else if (op === "disconnect") { - asNodeId(required(payload, "link_id", context), `${context}.link_id`); - asNodeId(required(payload, "to_node", context), `${context}.to_node`); - asInteger(required(payload, "to_slot", context), `${context}.to_slot`); - } else if (op === "delete_node") { - asNodeId(required(payload, "node_id", context), `${context}.node_id`); - assertNodeIdArray(required(payload, "removed_links", context), `${context}.removed_links`); - } else if (op === "clear") { - assertNodeIdArray(required(payload, "removed_nodes", context), `${context}.removed_nodes`); - } else if (op === "define_subgraph") { - asString(required(payload, "subgraph_id", context), `${context}.subgraph_id`); - asRecord(required(payload, "subgraph_definition", context), `${context}.subgraph_definition`); - } else { - // Exhaustiveness guard (issue #21), matching `dispatch` in `applier.ts`: - // `op` is narrowed from `FROZEN_OPS`, so with every kind enumerated above - // it is `never` here. This arm replaced a terminal `else` that validated - // every un-enumerated kind against `clear`'s payload shape — which broke - // silently when `disconnect` joined `FROZEN_OPS` in #139, rejecting real - // disconnect evidence for a missing `removed_nodes` while never checking - // `link_id`, `to_node`, or `to_slot`. Fail-closed reads (KA-11) need the - // next added kind to break compilation here, not to be mis-validated at - // runtime as some other kind. - assertNever(op, `${context}.op`); + } + + switch (op) { + case "insert_workflow": assertWorkflowInsertion(); break; + case "add_node": assertNodeAddition(); break; + case "connect": assertConnection(); break; + case "set_widget": assertWidgetWrite(); break; + case "disconnect": + asNodeId(required(payload, "link_id", context), `${context}.link_id`); + asNodeId(required(payload, "to_node", context), `${context}.to_node`); + asInteger(required(payload, "to_slot", context), `${context}.to_slot`); + break; + case "delete_node": + asNodeId(required(payload, "node_id", context), `${context}.node_id`); + assertNodeIdArray(required(payload, "removed_links", context), `${context}.removed_links`); + break; + case "clear": + assertNodeIdArray(required(payload, "removed_nodes", context), `${context}.removed_nodes`); + break; + case "define_subgraph": + asString(required(payload, "subgraph_id", context), `${context}.subgraph_id`); + asRecord(required(payload, "subgraph_definition", context), `${context}.subgraph_definition`); + break; + default: + // Exhaustiveness guard (issue #21), matching `dispatch` in `applier.ts`: + // `op` is narrowed from `FROZEN_OPS`, so with every kind enumerated above + // it is `never` here. This arm replaced a terminal `else` that validated + // every un-enumerated kind against `clear`'s payload shape — which broke + // silently when `disconnect` joined `FROZEN_OPS` in #139, rejecting real + // disconnect evidence for a missing `removed_nodes` while never checking + // `link_id`, `to_node`, or `to_slot`. Fail-closed reads (KA-11) need the + // next added kind to break compilation here, not to be mis-validated at + // runtime as some other kind. + assertNever(op, `${context}.op`); } return { actor, baseVersion, op, opId, payload, stamp }; @@ -540,18 +565,20 @@ function assertSemanticStep(step: UnknownRecord, context: string): ValidatedSema const decision = assertDecision(required(step, "decision_evidence", context), `${context}.decision_evidence`); const batch = Object.hasOwn(step, "batch") ? assertBatch(step["batch"], `${context}.batch`) : undefined; - if (outcome === "applied") { + function assertAppliedOutcome(): void { if (reasonCode !== outcome) invalid(`${context}.reason_code`, "must match outcome"); if (!processed || !consumed) invalid(`${context}.consumed_op_id`, "must be true for an applied outcome"); if (decision.kind !== "none") invalid(`${context}.decision_evidence`, "must be none for an applied outcome"); - } else if (outcome === "no-op") { + } + function assertNoOpOutcome(): void { if (reasonCode !== outcome) invalid(`${context}.reason_code`, "must match outcome"); if (!processed || !consumed) invalid(`${context}.consumed_op_id`, "must be true for a no-op outcome"); if (decision.kind !== "none" && (decision.kind !== "dedupe" || decision.originalOpId !== opId)) { invalid(`${context}.decision_evidence`, "must be none or identify the deduplicated op_id"); } if (!emptyDiff || !hashesMatch(beforeHash, afterHash)) invalid(`${context}.semantic_diff`, "must be empty for a no-op outcome"); - } else if (outcome === "lww-dropped") { + } + function assertDroppedOutcome(): void { if (reasonCode !== outcome) invalid(`${context}.reason_code`, "must match outcome"); if (!processed || !consumed) invalid(`${context}.consumed_op_id`, "must be true for an LWW-dropped outcome"); if (decision.kind !== "lww-comparison" || decision.losing[0] !== stamp[0] || decision.losing[1] !== stamp[1] || decision.losing[2] !== opId) { @@ -561,7 +588,8 @@ function assertSemanticStep(step: UnknownRecord, context: string): ValidatedSema invalid(`${context}.decision_evidence.winning_stamp`, "must outrank the losing stamp"); } if (!emptyDiff || !hashesMatch(beforeHash, afterHash)) invalid(`${context}.semantic_diff`, "must be empty for an LWW-dropped outcome"); - } else { + } + function assertRejectedOutcome(): void { if (consumed) invalid(`${context}.consumed_op_id`, "must be false for a rejected outcome"); if (decision.kind !== "rejection" || decision.code !== reasonCode) invalid(`${context}.decision_evidence`, "must match the rejection reason_code"); if (!emptyDiff || !hashesMatch(beforeHash, afterHash)) invalid(`${context}.semantic_diff`, "must be empty for a rejected outcome"); @@ -576,6 +604,14 @@ function assertSemanticStep(step: UnknownRecord, context: string): ValidatedSema if (!expectedFailureIndex) invalid(`${context}.decision_evidence.failing_index`, "does not identify the rejected operation"); } + switch (outcome) { + case "applied": assertAppliedOutcome(); break; + case "no-op": assertNoOpOutcome(); break; + case "lww-dropped": assertDroppedOutcome(); break; + case "rejected": assertRejectedOutcome(); break; + default: assertNever(outcome, context); + } + return { afterHash, batchStep: batch === undefined @@ -594,7 +630,17 @@ function assertSemanticStep(step: UnknownRecord, context: string): ValidatedSema }; } -function assertBatchSequences(steps: readonly ValidatedBatchStep[]): void { +function assertAbortedSuffix(members: ValidatedBatchStep[], failure: ValidatedBatchStep): void { + for (const step of members) { + if (step.index < failure.index && step.outcome === "rejected") invalid(`${step.context}.batch`, "contains a rejection before failing_index"); + if (step.index === failure.index && step !== failure) invalid(`${step.context}.batch`, "does not identify the processed rejection"); + if (step.index > failure.index && (step.outcome !== "rejected" || step.processed || step.reasonCode !== "batch_aborted" || step.failingIndex !== failure.index)) { + invalid(`${step.context}.batch`, "must form a contiguous aborted suffix after failing_index"); + } + } +} + +function indexBatchSteps(steps: readonly ValidatedBatchStep[]) { const batches = new Map }>(); for (const step of steps) { const existing = batches.get(step.batchId); @@ -604,7 +650,11 @@ function assertBatchSequences(steps: readonly ValidatedBatchStep[]): void { batch.steps.set(step.index, step); batches.set(step.batchId, batch); } + return batches; +} +function assertBatchSequences(steps: readonly ValidatedBatchStep[]): void { + const batches = indexBatchSteps(steps); for (const [batchId, batch] of batches) { if (batch.steps.size !== batch.size) invalid(`batch '${batchId}'`, `must include all ${batch.size} members under one batch_id`); const ordered = Array.from({ length: batch.size }, (_, index) => batch.steps.get(index)); @@ -620,13 +670,7 @@ function assertBatchSequences(steps: readonly ValidatedBatchStep[]): void { const failures = rejected.filter((step) => step.processed && step.reasonCode !== "batch_aborted"); if (failures.length !== 1) invalid(`batch '${batchId}'`, "must contain exactly one processed rejection"); const failure = failures[0]!; - for (const step of members) { - if (step.index < failure.index && step.outcome === "rejected") invalid(`${step.context}.batch`, "contains a rejection before failing_index"); - if (step.index === failure.index && step !== failure) invalid(`${step.context}.batch`, "does not identify the processed rejection"); - if (step.index > failure.index && (step.outcome !== "rejected" || step.processed || step.reasonCode !== "batch_aborted" || step.failingIndex !== failure.index)) { - invalid(`${step.context}.batch`, "must form a contiguous aborted suffix after failing_index"); - } - } + assertAbortedSuffix(members, failure); } } @@ -650,6 +694,25 @@ function assertLifecycleBase(step: UnknownRecord, context: string, workflowId: s return { afterDoc, afterLineage, afterStateVectorHash, beforeDoc, beforeLineage, beforeStateVectorHash }; } +function assertLifecycleTransition(step: UnknownRecord, context: string, kind: "state-vector-replay" | "doc-reset", lifecycle: ReturnType): void { + if (kind === "state-vector-replay") { + if (!asBoolean(required(step, "same_document", context), `${context}.same_document`) || lifecycle.beforeDoc !== lifecycle.afterDoc || lifecycle.beforeLineage !== lifecycle.afterLineage) { + invalid(context, "violates same-document replay"); + } + asOneOf(required(step, "reason", context), ["seq-gap", "reconnect"] as const, `${context}.reason`); + assertOptionalInteger(step, "requested_from_seq", context); + assertOptionalInteger(step, "resumed_at_seq", context); + } else { + if (asBoolean(required(step, "same_document", context), `${context}.same_document`) || lifecycle.beforeDoc === lifecycle.afterDoc || lifecycle.beforeLineage === lifecycle.afterLineage) { + invalid(context, "does not describe a lineage replacement"); + } + asInteger(required(step, "reset_seq", context), `${context}.reset_seq`); + if (!asBoolean(required(step, "projectors_notified_before_replace", context), `${context}.projectors_notified_before_replace`)) { + invalid(`${context}.projectors_notified_before_replace`, "must be true before document replacement"); + } + } +} + /** Fail closed at the schema-major boundary before a viewer reads a trace. */ export function assertCollabReplayTraceV1(value: unknown): asserts value is CollabReplayTraceV1 { const trace = asRecord(value, "collaboration trace"); @@ -665,7 +728,7 @@ export function assertCollabReplayTraceV1(value: unknown): asserts value is Coll let previousLifecycleAfterStateVectorHash: TraceHash | undefined; let previousSemanticAfterProjectionHash: TraceHash | undefined; - for (const [index, value] of steps.entries()) { + function assertTraceStep(value: unknown, index: number): void { const context = `trace step ${index}`; const step = asRecord(value, context); const stepId = asString(required(step, "step_id", context), `${context}.step_id`); @@ -683,7 +746,7 @@ export function assertCollabReplayTraceV1(value: unknown): asserts value is Coll if (semantic.batchStep !== undefined) batchSteps.push(semantic.batchStep); previousLifecycleAfterStateVectorHash = undefined; previousSemanticAfterProjectionHash = semantic.afterHash; - continue; + return; } previousSemanticAfterProjectionHash = undefined; @@ -693,27 +756,13 @@ export function assertCollabReplayTraceV1(value: unknown): asserts value is Coll if (previousLifecycleAfterStateVectorHash !== undefined && !hashesMatch(previousLifecycleAfterStateVectorHash, lifecycle.beforeStateVectorHash)) { invalid(`${context}.before_state_vector_hash`, "violates state-vector continuity"); } - if (kind === "state-vector-replay") { - if (!asBoolean(required(step, "same_document", context), `${context}.same_document`) || lifecycle.beforeDoc !== lifecycle.afterDoc || lifecycle.beforeLineage !== lifecycle.afterLineage) { - invalid(context, "violates same-document replay"); - } - asOneOf(required(step, "reason", context), ["seq-gap", "reconnect"] as const, `${context}.reason`); - assertOptionalInteger(step, "requested_from_seq", context); - assertOptionalInteger(step, "resumed_at_seq", context); - } else { - if (asBoolean(required(step, "same_document", context), `${context}.same_document`) || lifecycle.beforeDoc === lifecycle.afterDoc || lifecycle.beforeLineage === lifecycle.afterLineage) { - invalid(context, "does not describe a lineage replacement"); - } - asInteger(required(step, "reset_seq", context), `${context}.reset_seq`); - if (!asBoolean(required(step, "projectors_notified_before_replace", context), `${context}.projectors_notified_before_replace`)) { - invalid(`${context}.projectors_notified_before_replace`, "must be true before document replacement"); - } - } + assertLifecycleTransition(step, context, kind, lifecycle); currentLineage = lifecycle.afterLineage; currentDoc = lifecycle.afterDoc; previousLifecycleAfterStateVectorHash = lifecycle.afterStateVectorHash; } + for (const [index, value] of steps.entries()) assertTraceStep(value, index); assertBatchSequences(batchSteps); const assertions = asRecord(required(trace, "assertions", "collaboration trace"), "collaboration trace.assertions"); From f464a1e2e9b7e55005ef110ebbcabad075bbded7 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 18 Sep 2026 22:51:03 +0000 Subject: [PATCH 11/20] refactor: share inert link descriptor record checks Amp-Thread-ID: https://ampcode.com/threads/T-01a0b6a1-ba97-7390-b562-9225304d4bbf Co-authored-by: Amp --- src/read.ts | 27 ++++++++++++--------------- 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/src/read.ts b/src/read.ts index 0e38f868..9e9b3518 100644 --- a/src/read.ts +++ b/src/read.ts @@ -439,6 +439,12 @@ export function readStamps(doc: Y.Doc): Readonly> { return snapshotRoot(doc, ROOT_STAMPS); } +/** Descriptor fields have already been copied into inert snapshot data. */ +function descriptorRecord(value: unknown): Record | undefined { + if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined; + return value as Record; +} + /** Durable imported and operation-owned link descriptors as deep-frozen plain data. */ export function readLinkState(doc: Y.Doc): Readonly> { assertSnapshotReadable(doc, "readLinkState"); @@ -450,19 +456,14 @@ export function readLinkState(doc: Y.Doc): Readonly> { const descriptor = raw as Record; const tuple = descriptor["tuple"]; const destinationValue = descriptor["destination"]; - const destination = typeof destinationValue === "object" && destinationValue !== null && !Array.isArray(destinationValue) - ? destinationValue as Record - : undefined; + const destination = descriptorRecord(destinationValue); const validId = (value: unknown): boolean => (typeof value === "string" && value.length > 0) || (typeof value === "number" && Number.isSafeInteger(value)); const validSlot = (value: unknown): boolean => Number.isSafeInteger(value) && (value as number) >= 0; - const validSlotRecord = destination !== undefined && typeof destination["slot"] === "object" && - destination["slot"] !== null && !Array.isArray(destination["slot"]); - const slotRecord = validSlotRecord ? destination!["slot"] as Record : undefined; + const slotRecord = descriptorRecord(destination?.["slot"]); + const validSlotRecord = slotRecord !== undefined; const authority = descriptor["authority"]; - const operationAuthority = typeof authority === "object" && authority !== null && !Array.isArray(authority) - ? authority as Record - : undefined; + const operationAuthority = descriptorRecord(authority); const operationStamp = operationAuthority?.["stamp"]; // Match validateEnvelope/stampKey, including the empty fallback actor and // non-empty opaque op IDs. Reading must not reject records our writer emits. @@ -472,13 +473,9 @@ export function readLinkState(doc: Y.Doc): Readonly> { typeof operationStamp[1] === "string" && typeof operationStamp[2] === "string" && operationStamp[2].length > 0); const requestValue = destination?.["request"]; - const request = typeof requestValue === "object" && requestValue !== null && !Array.isArray(requestValue) - ? requestValue as Record - : undefined; + const request = descriptorRecord(requestValue); const inputcountValue = request?.["inputcount"]; - const inputcount = typeof inputcountValue === "object" && inputcountValue !== null && !Array.isArray(inputcountValue) - ? inputcountValue as Record - : undefined; + const inputcount = descriptorRecord(inputcountValue); const validRequest = destination?.["kind"] !== "autogrow" || authority === "imported" || (request !== undefined && typeof request["name"] === "string" && typeof request["type"] === "string" && From 622d9bfa1e94c1a24d69eb6b09474ed00dc62f27 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 18 Sep 2026 22:52:02 +0000 Subject: [PATCH 12/20] refactor: separate batch rejection and payload classification Amp-Thread-ID: https://ampcode.com/threads/T-01a0b6a1-ba97-7390-b562-9225304d4bbf Co-authored-by: Amp --- src/applier.ts | 128 +++++++++++++++++++++++++++---------------------- 1 file changed, 72 insertions(+), 56 deletions(-) diff --git a/src/applier.ts b/src/applier.ts index 91c8dd1d..22125b10 100644 --- a/src/applier.ts +++ b/src/applier.ts @@ -185,7 +185,34 @@ export function applyOps(doc: Y.Doc, ops: Op[], catalog?: WidgetCatalog, context return result; } - for (let index = 0; index < ops.length; index++) { + function rejectRemainder(err: unknown, op: Op, index: number): void { + const op_id = opIdentity(op); + const code = err instanceof OpRejectedError ? err.code : "apply_failed"; + const message = err instanceof Error ? err.message : String(err); + outcomes.push({ op_id, outcome: "rejected", reason: { code, message } }); + for (const remainder of ops.slice(index + 1)) { + outcomes.push({ + op_id: opIdentity(remainder), + outcome: "rejected", + reason: { code: "batch_aborted", message: `not processed because op at index ${index} was rejected` }, + }); + } + if (context?.eventSink !== undefined) { + const errorClass = err instanceof Error ? "Error" : "NonError"; + emitCmpEvent(context.eventSink, { + schema_version: CMP_EVENT_SCHEMA_VERSION, + type: err instanceof OpRejectedError ? "op_rejected" : "applier_error", + source: "applyOps", + code, + message, + error_name: err instanceof OpRejectedError ? "OpRejectedError" : errorClass, + op_id, + batch_index: index, + }); + } + } + + function applyOne(index: number): boolean { const op = ops[index]!; try { validateEnvelope(op); @@ -205,7 +232,7 @@ export function applyOps(doc: Y.Doc, ops: Op[], catalog?: WidgetCatalog, context // is a true no-op (byte-identical encodeStateAsUpdate). outcomes.push({ op_id: op.op_id, outcome: "no-op" }); duplicateIds.add(op.op_id); - continue; + return true; } let outcome: Exclude = "applied"; doc.transact(() => { @@ -226,31 +253,14 @@ export function applyOps(doc: Y.Doc, ops: Op[], catalog?: WidgetCatalog, context }); } } catch (err) { - const op_id = opIdentity(op); - const code = err instanceof OpRejectedError ? err.code : "apply_failed"; - const message = err instanceof Error ? err.message : String(err); - outcomes.push({ op_id, outcome: "rejected", reason: { code, message } }); - for (const remainder of ops.slice(index + 1)) { - outcomes.push({ - op_id: opIdentity(remainder), - outcome: "rejected", - reason: { code: "batch_aborted", message: `not processed because op at index ${index} was rejected` }, - }); - } - if (context?.eventSink !== undefined) { - emitCmpEvent(context.eventSink, { - schema_version: CMP_EVENT_SCHEMA_VERSION, - type: err instanceof OpRejectedError ? "op_rejected" : "applier_error", - source: "applyOps", - code, - message, - error_name: err instanceof OpRejectedError ? "OpRejectedError" : err instanceof Error ? "Error" : "NonError", - op_id, - batch_index: index, - }); - } - break; // abort-remainder (vocabulary §4) + rejectRemainder(err, op, index); + return false; } + return true; + } + + for (let index = 0; index < ops.length; index++) { + if (!applyOne(index)) break; // abort-remainder (vocabulary §4) } return makeResult({ outcomes, ops_seen: bookkeeping.size }, ops, duplicateIds); @@ -282,30 +292,14 @@ function opIdentity(op: unknown): string { : ""; } -/** - * Stable, key-order-independent JSON for an op: object keys sorted by code - * point at every depth, array order preserved, whole envelope included. - * - * NOT stored — see {@link opDigest}. Exposed to tests as the definition of - * what the digest is taken over. - */ -function canonicalJson(value: unknown): string { +function rejectBigIntPayload(value: unknown): void { // BigInt classification takes precedence over the generic depth/cost gates. // Keep this walk iterative and bounded so even a hostile envelope cannot // turn the diagnostic into unbounded work. const bigintStack: Array<{ value: unknown; path: string }> = [{ value, path: "$" }]; const bigintVisited = new Set(); let bigintVisits = 0; - while (bigintStack.length > 0 && bigintVisits++ <= MAX_OP_COST) { - const { value, path } = bigintStack.pop()!; - if (typeof value === "bigint") { - throw new OpRejectedError( - "malformed_op", - `op payload at ${path} is a BigInt and cannot be encoded as JSON`, - ); - } - if (typeof value !== "object" || value === null || bigintVisited.has(value)) continue; - bigintVisited.add(value); + function queueChildren(value: object, path: string): void { if (Array.isArray(value)) { const firstIndex = Math.max(0, value.length - (MAX_OP_COST - bigintVisits)); for (let index = value.length - 1; index >= firstIndex; index--) { @@ -324,7 +318,29 @@ function canonicalJson(value: unknown): string { } } } + while (bigintStack.length > 0 && bigintVisits++ <= MAX_OP_COST) { + const { value, path } = bigintStack.pop()!; + if (typeof value === "bigint") { + throw new OpRejectedError( + "malformed_op", + `op payload at ${path} is a BigInt and cannot be encoded as JSON`, + ); + } + if (typeof value !== "object" || value === null || bigintVisited.has(value)) continue; + bigintVisited.add(value); + queueChildren(value, path); + } +} +/** + * Stable, key-order-independent JSON for an op: object keys sorted by code + * point at every depth, array order preserved, whole envelope included. + * + * NOT stored — see {@link opDigest}. Exposed to tests as the definition of + * what the digest is taken over. + */ +function canonicalJson(value: unknown): string { + rejectBigIntPayload(value); // Amendment A11 extends A8's whole-envelope, pre-idempotency gate with a // breadth/size budget. Its iterative depth check keeps A8's // `payload_too_deep` vocabulary while avoiding hostile recursion. @@ -586,12 +602,7 @@ function applyDefineSubgraph( if (existingDigest === digest) return "no-op"; if (digest > existingDigest) { assertDefinitionIdsAvailable(doc, op.subgraph_definition, op.subgraph_id); - let replacement: Y.Map; - try { - replacement = mintDefinition(op.subgraph_definition, catalog); - } catch (error) { - throw new OpRejectedError("malformed_op", `define_subgraph(${op.subgraph_id}): ${error instanceof Error ? error.message : String(error)}`); - } + const replacement = mintSubmittedDefinition(op, catalog); const widgetEdits = definitionWidgetEdits(doc, existing); mset(definitions, op.subgraph_id, replacement); restoreDefinitionWidgetEdits(doc, replacement, widgetEdits); @@ -608,18 +619,21 @@ function applyDefineSubgraph( ); } assertDefinitionIdsAvailable(doc, op.subgraph_definition); - let definition: Y.Map; + const definition = mintSubmittedDefinition(op, catalog); + mset(definitions, op.subgraph_id, definition); + setDefinitionDigest(doc, op.subgraph_id, digest); + return "applied"; +} + +function mintSubmittedDefinition(op: DefineSubgraphOp, catalog: WidgetCatalog): Y.Map { try { - definition = mintDefinition(op.subgraph_definition, catalog); + return mintDefinition(op.subgraph_definition, catalog); } catch (error) { throw new OpRejectedError( "malformed_op", `define_subgraph(${op.subgraph_id}): ${error instanceof Error ? error.message : String(error)}`, ); } - mset(definitions, op.subgraph_id, definition); - setDefinitionDigest(doc, op.subgraph_id, digest); - return "applied"; } function definitionDigest(definition: SubgraphDefinition | Y.Map, catalog: WidgetCatalog): string { @@ -853,7 +867,9 @@ function assertUniqueNormalizedIds( ): void { const ids = new Set(); values.forEach((value, index) => { - const id = Array.isArray(value) ? value[0] : isPlainRecord(value) ? value.id : undefined; + let id: unknown; + if (Array.isArray(value)) id = value[0]; + else if (isPlainRecord(value)) id = value.id; if (id === undefined || id === null) { if (required) throw new OpRejectedError("malformed_op", `${operation}: missing id at ${path}[${index}]`); return; From 911bd0cc84af922969e5609541c48c9e185680da Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 18 Sep 2026 22:52:55 +0000 Subject: [PATCH 13/20] refactor: separate workflow insertion preflight and writes Amp-Thread-ID: https://ampcode.com/threads/T-01a0b6a1-ba97-7390-b562-9225304d4bbf Co-authored-by: Amp --- src/applier.ts | 93 ++++++++++++++++++++++++++++++++------------------ 1 file changed, 60 insertions(+), 33 deletions(-) diff --git a/src/applier.ts b/src/applier.ts index 22125b10..d682a4c0 100644 --- a/src/applier.ts +++ b/src/applier.ts @@ -976,12 +976,12 @@ function validateDefinitionInputs(subgraphs: unknown[], path = "workflow.definit }); } -function applyInsertWorkflow(doc: Y.Doc, op: InsertWorkflowOp, catalog?: WidgetCatalog): SuccessfulOutcome { +function prepareInsertedWorkflow(op: InsertWorkflowOp): Record { const workflow = scrubPrivateKeys(op.workflow) as unknown; if (typeof workflow !== "object" || workflow === null || Array.isArray(workflow)) { throw new OpRejectedError("malformed_op", "insert_workflow: workflow must be an object"); } - let wf = workflow as Record; + const wf = workflow as Record; if (!Array.isArray(wf["nodes"]) || (wf["links"] !== undefined && !Array.isArray(wf["links"]))) { throw new OpRejectedError("malformed_op", "insert_workflow: nodes and links must be arrays"); } @@ -998,7 +998,11 @@ function applyInsertWorkflow(doc: Y.Doc, op: InsertWorkflowOp, catalog?: WidgetC } validateRawGraphIds(wf["nodes"] as unknown[], (wf["links"] as unknown[] | undefined) ?? [], "workflow"); validateDefinitionInputs((subgraphs as unknown[] | undefined) ?? []); - wf = remapInsertedWorkflowIds(wf as unknown as import("./types.js").WorkflowJSON, op.op_id) as unknown as Record; + return remapInsertedWorkflowIds(wf as unknown as import("./types.js").WorkflowJSON, op.op_id) as unknown as Record; +} + +function applyInsertWorkflow(doc: Y.Doc, op: InsertWorkflowOp, catalog?: WidgetCatalog): SuccessfulOutcome { + const wf = prepareInsertedWorkflow(op); const remappedDefinitions = wf["definitions"] as { subgraphs?: unknown[] } | undefined; const remappedSubgraphs = remappedDefinitions?.subgraphs ?? []; @@ -1007,7 +1011,7 @@ function applyInsertWorkflow(doc: Y.Doc, op: InsertWorkflowOp, catalog?: WidgetC const stamps = stampsMap(doc); const stamp = stampKey(op); const seenNodes = new Set(); - for (const candidate of wf["nodes"] as unknown[]) { + function acceptsNode(candidate: unknown): boolean { if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate)) { throw new OpRejectedError("invalid_node_payload", "insert_workflow: every node must be an object"); } @@ -1025,13 +1029,17 @@ function applyInsertWorkflow(doc: Y.Doc, op: InsertWorkflowOp, catalog?: WidgetC if (incumbent === undefined) { throw new OpRejectedError("node_id_collision", `insert_workflow: node id '${key}' collides`); } - if (compareStampKeys(stamp, incumbent) <= 0) return "lww-dropped"; + if (compareStampKeys(stamp, incumbent) <= 0) return false; } seenNodes.add(key); + return true; + } + for (const candidate of wf["nodes"] as unknown[]) { + if (!acceptsNode(candidate)) return "lww-dropped"; } const seenLinks = new Set(); const linkWrites: unknown[][] = []; - for (const candidate of (wf["links"] as unknown[] | undefined) ?? []) { + function acceptsLink(candidate: unknown): boolean { if (!Array.isArray(candidate) || candidate[0] === undefined || candidate[1] === undefined || candidate[3] === undefined) { throw new OpRejectedError("malformed_op", "insert_workflow: every link must be a tuple with an id and two endpoints"); } @@ -1044,13 +1052,17 @@ function applyInsertWorkflow(doc: Y.Doc, op: InsertWorkflowOp, catalog?: WidgetC if (incumbent === undefined) { throw new OpRejectedError("link_id_collision", `insert_workflow: link id '${key}' collides`); } - if (compareStampKeys(stamp, incumbent) <= 0) return "lww-dropped"; + if (compareStampKeys(stamp, incumbent) <= 0) return false; } seenLinks.add(key); if (linkHasMissingEndpoint(candidate, (id) => nodes.has(String(id)) || seenNodes.has(String(id)))) { - continue; + return true; } linkWrites.push(candidate); + return true; + } + for (const candidate of (wf["links"] as unknown[] | undefined) ?? []) { + if (!acceptsLink(candidate)) return "lww-dropped"; } const targetKey = stampTargetKey(op); @@ -1064,7 +1076,7 @@ function applyInsertWorkflow(doc: Y.Doc, op: InsertWorkflowOp, catalog?: WidgetC const defs = definitionsMap(doc); const submittedDefinitionIds = new Set(); const definitionWrites: Array<[string, Y.Map, string]> = []; - for (const candidate of remappedSubgraphs) { + function prepareDefinition(candidate: unknown): void { if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate)) { throw new OpRejectedError("malformed_op", "insert_workflow: every subgraph definition must be an object"); } @@ -1076,9 +1088,10 @@ function applyInsertWorkflow(doc: Y.Doc, op: InsertWorkflowOp, catalog?: WidgetC const digest = definitionDigest(sg as unknown as SubgraphDefinition, cat); definitionWrites.push([id, mintDefinition(sg, cat), digest]); } + for (const candidate of remappedSubgraphs) prepareDefinition(candidate); const nodeWrites: Array<[string, unknown, Y.Map]> = []; - for (const candidate of wf["nodes"] as import("./types.js").WorkflowNode[]) { + function prepareNode(candidate: import("./types.js").WorkflowNode): void { const node = structuredClone(candidate); const wv = node.widgets_values; const entry = catalogEntry(catalog, node.type); @@ -1092,9 +1105,10 @@ function applyInsertWorkflow(doc: Y.Doc, op: InsertWorkflowOp, catalog?: WidgetC throw new OpRejectedError("invalid_node_payload", `insert_workflow(${node.type}): ${err instanceof Error ? err.message : String(err)}`); } } + for (const candidate of wf["nodes"] as import("./types.js").WorkflowNode[]) prepareNode(candidate); const importedLinkStates = new Map>(); - for (const link of linkWrites) { + function prepareLinkState(link: unknown[]): void { const key = String(link[0]); try { importedLinkStates.set(key, importedLinkState(link, wf as unknown as import("./types.js").WorkflowJSON)); @@ -1102,28 +1116,44 @@ function applyInsertWorkflow(doc: Y.Doc, op: InsertWorkflowOp, catalog?: WidgetC throw new OpRejectedError("malformed_op", `insert_workflow: ${err instanceof Error ? err.message : String(err)}`); } } + for (const link of linkWrites) prepareLinkState(link); - for (const [id, definition, digest] of definitionWrites) { - mset(defs, id, definition); - setDefinitionDigest(doc, id, digest); - } - for (const link of linkWrites) { - const key = String((link as unknown[])[0]); - mset(links, key, cloneForMap(link, "insert_workflow: link")); - const state = importedLinkStates.get(key) ?? null; - if (state !== null) mset(linkStateMap(doc), key, cloneForMap(state, `insert_workflow: link state ${key}`)); - mset(stamps, JSON.stringify(["insert_workflow_link", key]), stamp); - } - for (const [key, id, nodeMap] of nodeWrites) { - clearObsoleteWidgetStamps(stamps, key); - mset(nodeMap, NODE_INCARNATION_KEY, `${op.op_id}:${key}`); - mset(nodes, key, nodeMap); - mset(stamps, JSON.stringify(["insert_workflow_node", key]), stamp); - mset(stamps, targetKey, stamp); - reconcileNodeLinkRefs(doc, id, nodeMap); + function commitPreparedWrites(): void { + for (const [id, definition, digest] of definitionWrites) { + mset(defs, id, definition); + setDefinitionDigest(doc, id, digest); + } + for (const link of linkWrites) { + const key = String((link as unknown[])[0]); + mset(links, key, cloneForMap(link, "insert_workflow: link")); + const state = importedLinkStates.get(key) ?? null; + if (state !== null) mset(linkStateMap(doc), key, cloneForMap(state, `insert_workflow: link state ${key}`)); + mset(stamps, JSON.stringify(["insert_workflow_link", key]), stamp); + } + for (const [key, id, nodeMap] of nodeWrites) { + clearObsoleteWidgetStamps(stamps, key); + mset(nodeMap, NODE_INCARNATION_KEY, `${op.op_id}:${key}`); + mset(nodes, key, nodeMap); + mset(stamps, JSON.stringify(["insert_workflow_node", key]), stamp); + mset(stamps, targetKey, stamp); + reconcileNodeLinkRefs(doc, id, nodeMap); + } + if (nodeWrites.length === 0) mset(stamps, targetKey, stamp); } - if (nodeWrites.length === 0) mset(stamps, targetKey, stamp); + commitPreparedWrites(); + updateInsertedWorkflowMeta(doc, wf, nodeWrites, linkWrites); + return nodeWrites.length > 0 || linkWrites.length > 0 || definitionWrites.length > 0 || ((wf["groups"] as unknown[] | undefined)?.length ?? 0) > 0 + ? "applied" + : "no-op"; +} + +function updateInsertedWorkflowMeta( + doc: Y.Doc, + wf: Record, + nodeWrites: Array<[string, unknown, Y.Map]>, + linkWrites: unknown[][], +): void { const meta = metaMap(doc); if (Array.isArray(wf["groups"])) { const currentGroups = Array.isArray(meta.get("groups")) ? meta.get("groups") as unknown[] : []; @@ -1137,9 +1167,6 @@ function applyInsertWorkflow(doc: Y.Doc, op: InsertWorkflowOp, catalog?: WidgetC const currentLink = numericId(meta.get("last_link_id")) ?? 0; const maxLink = Math.max(currentLink, ...linkWrites.map((link) => numericId(link[0]) ?? currentLink)); if (maxLink > currentLink) mset(meta, "last_link_id", maxLink); - return nodeWrites.length > 0 || linkWrites.length > 0 || definitionWrites.length > 0 || ((wf["groups"] as unknown[] | undefined)?.length ?? 0) > 0 - ? "applied" - : "no-op"; } // --------------------------------------------------------------------------- From 8dbcdba6db46e6decf30029120ccd14ab8767ca5 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 18 Sep 2026 22:53:28 +0000 Subject: [PATCH 14/20] refactor: separate widget payload and interior resolution checks Amp-Thread-ID: https://ampcode.com/threads/T-01a0b6a1-ba97-7390-b562-9225304d4bbf Co-authored-by: Amp --- src/applier.ts | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/src/applier.ts b/src/applier.ts index d682a4c0..d9e73c6e 100644 --- a/src/applier.ts +++ b/src/applier.ts @@ -1622,7 +1622,7 @@ function applyPromotedHostWrite( } } -function applySetWidget(doc: Y.Doc, op: SetWidgetOp, catalog?: WidgetCatalog): SuccessfulOutcome { +function validateWidgetOp(op: SetWidgetOp) { const interior: InteriorSetWidgetOp | null = isInteriorWrite(op) ? op : null; if (interior !== null && typeof interior.inner_widget !== "string") { throw new OpRejectedError("malformed_op", "set_widget: interior write without inner_widget"); @@ -1641,7 +1641,11 @@ function applySetWidget(doc: Y.Doc, op: SetWidgetOp, catalog?: WidgetCatalog): S if (promoted !== null && interior !== null) { throw new OpRejectedError("malformed_op", "set_widget: a promoted host write carries no interior path"); } + return { interior, promoted }; +} +function applySetWidget(doc: Y.Doc, op: SetWidgetOp, catalog?: WidgetCatalog): SuccessfulOutcome { + const { interior, promoted } = validateWidgetOp(op); // Interior paths have several legal spellings (definition id and instance // id), but all of them can resolve to the same node. Resolve first // so that node owns one register rather than letting each raw alias claim a @@ -1672,8 +1676,7 @@ function applySetWidget(doc: Y.Doc, op: SetWidgetOp, catalog?: WidgetCatalog): S return applyPromotedHostWrite(doc, op, promoted, stamps, targetKey, key, catalog); } - if (interior !== null) { - const target = interiorResolution!.node; + function applyInteriorWidget(target: Y.Map, interior: InteriorSetWidgetOp): SuccessfulOutcome { if (nodeIncarnation(target) !== (op.node_incarnation ?? LEGACY_NODE_INCARNATION)) return "no-op"; const nodeType = String(target.get("type") ?? ""); const widget = interior.inner_widget; @@ -1706,6 +1709,7 @@ function applySetWidget(doc: Y.Doc, op: SetWidgetOp, catalog?: WidgetCatalog): S return "applied"; } + if (interior !== null) return applyInteriorWidget(interiorResolution!.node, interior); const node = nodesMap(doc).get(String(op.node_id)); if (!node) return "no-op"; // target concurrently deleted → no-op (delete wins) if (nodeIncarnation(node) !== (op.node_incarnation ?? LEGACY_NODE_INCARNATION)) return "no-op"; @@ -1755,16 +1759,14 @@ function resolveInteriorNode( allowRetainedRoute = true, ): InteriorResolution | null { const head = nodesMap(doc).get(path[0]!); - if (!head) { + function resolveMissingHead(): InteriorResolution | null { const directDefinition = resolveDefinition(doc, path[0]!); const retainedDefinitionId = allowRetainedRoute ? stampsMap(doc).get(interiorRouteKey(path[0]!, incarnation)) : undefined; - const definition = directDefinition && String(directDefinition.get("id")) === path[0] - ? directDefinition - : typeof retainedDefinitionId === "string" - ? resolveDefinition(doc, retainedDefinitionId) - : null; + let definition: Y.Map | null = null; + if (directDefinition && String(directDefinition.get("id")) === path[0]) definition = directDefinition; + else if (typeof retainedDefinitionId === "string") definition = resolveDefinition(doc, retainedDefinitionId); if (!definition) return null; const definitionId = String(definition.get("id")); // A retained route represents the deleted routing instance for authority @@ -1790,6 +1792,7 @@ function resolveInteriorNode( if (path.length === 2) return { node: inner, canonicalPath }; return resolveInteriorDescendants(doc, inner, path.slice(2), canonicalPath, catalog); } + if (!head) return resolveMissingHead(); const definition = resolveDefinition(doc, String(head.get("type") ?? "")); const canonicalPath = definition === null ? [path[0]!] From 297e2a5ec2b6a1b7af5ad31ac27591ccdef0a0a4 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 18 Sep 2026 22:54:49 +0000 Subject: [PATCH 15/20] refactor: separate connection scope, claims, and installation Amp-Thread-ID: https://ampcode.com/threads/T-01a0b6a1-ba97-7390-b562-9225304d4bbf Co-authored-by: Amp --- src/applier.ts | 120 ++++++++++++++++++++++++++++--------------------- 1 file changed, 70 insertions(+), 50 deletions(-) diff --git a/src/applier.ts b/src/applier.ts index d9e73c6e..551414ff 100644 --- a/src/applier.ts +++ b/src/applier.ts @@ -1968,15 +1968,7 @@ function requireOpOnlyValid(op: ConnectOp): void { throw new OpRejectedError("malformed_op", "connect: link_type must be a string"); } - if (op.grow?.inputcount != null) { - if (typeof op.grow.inputcount.widget !== "string") { - throw new OpRejectedError("malformed_op", "connect: grow.inputcount needs a widget name"); - } - assertWritableValue(op.grow.inputcount.value, "connect: grow.inputcount"); - } - if (op.grow != null && (typeof op.grow.name !== "string" || typeof op.grow.type !== "string")) { - throw new OpRejectedError("malformed_op", "connect: grow payload needs name and type"); - } + validateGrowPayload(op); // `stampKey` is op-only — `Number(stamp[0])`, `String(stamp[1])`, no document // read — but the concrete branch used to evaluate it BELOW `if (!dst) return`, // so a `base_version` that throws on conversion (a `Symbol`, or an object with @@ -2004,6 +1996,18 @@ function requireOpOnlyValid(op: ConnectOp): void { } } +function validateGrowPayload(op: ConnectOp): void { + if (op.grow?.inputcount != null) { + if (typeof op.grow.inputcount.widget !== "string") { + throw new OpRejectedError("malformed_op", "connect: grow.inputcount needs a widget name"); + } + assertWritableValue(op.grow.inputcount.value, "connect: grow.inputcount"); + } + if (op.grow != null && (typeof op.grow.name !== "string" || typeof op.grow.type !== "string")) { + throw new OpRejectedError("malformed_op", "connect: grow payload needs name and type"); + } +} + interface InteriorConnectScope { nodes: Y.Map>; links: Y.Map; @@ -2047,7 +2051,7 @@ function resolveInteriorConnectScope( path.shift(); } - for (const segment of path) { + function descend(host: Y.Map, segment: string): Y.Map { const ownerType = String(host.get("type") ?? ""); const owner = resolveDefinition(doc, ownerType); if (!owner) { @@ -2066,9 +2070,10 @@ function resolveInteriorConnectScope( `interior node ${segment} not found in subgraph ${ownerId}`, ); } - host = inner; + return inner; } + for (const segment of path) host = descend(host, segment); const hostType = String(host.get("type") ?? ""); const definition = resolveDefinition(doc, hostType); if (!definition) { @@ -2146,9 +2151,24 @@ function applyInteriorConnect(doc: Y.Doc, op: ConnectOp, scope: InteriorConnectS type: op.link_type, }); } - const linkOrder = scope.definition.get("link_order"); + recordInteriorLinkOrder(scope.definition, stamps, linkKey, key); + mset(input, "link", op.link_id); + const output = sourceOutputs.get(op.from_slot) as Y.Map; + let outputLinks = output.get("links"); + if (!(outputLinks instanceof Y.Array)) { + outputLinks = new Y.Array(); + mset(output, "links", outputLinks); + } + if (!(outputLinks as Y.Array).toArray().includes(op.link_id)) { + apush(outputLinks as Y.Array, op.link_id); + } + return "applied"; +} + +function recordInteriorLinkOrder(definition: Y.Map, stamps: Y.Map, linkKey: string, key: StampKey): void { + const linkOrder = definition.get("link_order"); const orderedIds: unknown[] = Array.isArray(linkOrder) ? [...linkOrder] : []; - const definitionId = String(scope.definition.get("id") ?? ""); + const definitionId = String(definition.get("id") ?? ""); const orderStampKey = (candidate: string) => JSON.stringify(["interior_link_order", definitionId, candidate]); const additions: Record = Object.create(null) as Record; @@ -2163,19 +2183,8 @@ function applyInteriorConnect(doc: Y.Doc, op: ConnectOp, scope: InteriorConnectS mset(stamps, orderStampKey(linkKey), key); } if (nextOrder.some((candidate, index) => candidate !== orderedIds[index]) || nextOrder.length !== orderedIds.length) { - mset(scope.definition, "link_order", nextOrder); - } - mset(input, "link", op.link_id); - const output = sourceOutputs.get(op.from_slot) as Y.Map; - let outputLinks = output.get("links"); - if (!(outputLinks instanceof Y.Array)) { - outputLinks = new Y.Array(); - mset(output, "links", outputLinks); - } - if (!(outputLinks as Y.Array).toArray().includes(op.link_id)) { - apush(outputLinks as Y.Array, op.link_id); + mset(definition, "link_order", nextOrder); } - return "applied"; } function applyConnect(doc: Y.Doc, op: ConnectOp, catalog?: WidgetCatalog): SuccessfulOutcome { @@ -2229,29 +2238,35 @@ function applyConnect(doc: Y.Doc, op: ConnectOp, catalog?: WidgetCatalog): Succe const src = nodes.get(String(op.from_node)); const sourceOutputs = src ? requireOutputSlot(src, op) : null; - let toIdx: number; - // Issue #17: this is the discriminant of the `ConnectOp` union. The type now - // says a `grow` op has no numeric `to_slot` and a concrete op has no `grow`; - // this branch is where a wire op that says otherwise is disposed of — and it - // is disposed of exactly as before, `grow` winning and `to_slot` unread. - if (op.grow != null && op.grow.promoted === true) { - if (!claimLinkIdentity(doc, op)) return "lww-dropped"; - // A promoted subgraph input (Amendment A15) is ONE register named by the - // definition, so it is gated and claimed like a concrete input — before the - // source is consulted, for the same reason the concrete branch does it. - const claimed = claimPromotedInput(doc, dst, op); - if (claimed === null) return "lww-dropped"; - toIdx = claimed; - } else if (op.grow != null) { - // Autogrow is NOT a shared register: every grow mints its own slot keyed by - // `grow_id`, so two concurrent grows onto one base both survive and there - // is nothing to gate (vocabulary §1.2 / amendment v1.2's carve-out). - if (!claimLinkIdentity(doc, op)) return "lww-dropped"; - if (!src) return "no-op"; // source concurrently deleted → no-op (delete wins) - toIdx = growInputSlot(doc, dst, op, catalog); - } else { + function claimDestination(dst: Y.Map): number | "lww-dropped" | "no-op" { + // Issue #17: this is the discriminant of the `ConnectOp` union. The type now + // says a `grow` op has no numeric `to_slot` and a concrete op has no `grow`; + // this branch is where a wire op that says otherwise is disposed of — and it + // is disposed of exactly as before, `grow` winning and `to_slot` unread. + if (op.grow != null && op.grow.promoted === true) { + if (!claimLinkIdentity(doc, op)) return "lww-dropped"; + // A promoted subgraph input (Amendment A15) is ONE register named by the + // definition, so it is gated and claimed like a concrete input — before the + // source is consulted, for the same reason the concrete branch does it. + const claimed = claimPromotedInput(doc, dst, op); + if (claimed === null) return "lww-dropped"; + return claimed; + } + if (op.grow != null) { + // Autogrow is NOT a shared register: every grow mints its own slot keyed by + // `grow_id`, so two concurrent grows onto one base both survive and there + // is nothing to gate (vocabulary §1.2 / amendment v1.2's carve-out). + if (!claimLinkIdentity(doc, op)) return "lww-dropped"; + if (!src) return "no-op"; // source concurrently deleted → no-op (delete wins) + return growInputSlot(doc, dst, op, catalog); + } // `to_slot`'s type was settled by `requireOpOnlyValid`. - toIdx = op.to_slot as number; + const toIdx = op.to_slot as number; + if (!claimConcreteInput(dst, toIdx)) return "lww-dropped"; + return toIdx; + } + + function claimConcreteInput(dst: Y.Map, toIdx: number): boolean { const ins = dst.get("inputs"); // STATE-DEPENDENT half only: the op-only domain (integer, non-negative) was // settled by `requireOpOnlyValid` above, before any document read. @@ -2266,7 +2281,7 @@ function applyConnect(doc: Y.Doc, op: ConnectOp, catalog?: WidgetCatalog): Succe throw new OpRejectedError("input_slot_missing", `connect: input slot ${toIdx} is not a slot record`); } - if (!claimLinkIdentity(doc, op)) return "lww-dropped"; + if (!claimLinkIdentity(doc, op)) return false; // ---- The concrete-input LWW register (op-vocabulary-v1.md amendment v1.2) // @@ -2281,7 +2296,7 @@ function applyConnect(doc: Y.Doc, op: ConnectOp, catalog?: WidgetCatalog): Succe const targetKey = stampTargetKey(op); const prior = stamps.get(targetKey) as StampKey | undefined; const key = stampKey(op); - if (prior != null && compareStampKeys(key, prior) <= 0) return "lww-dropped"; + if (prior != null && compareStampKeys(key, prior) <= 0) return false; // Claiming the register is UNCONDITIONAL once the gate passes — the prior // occupant is retired even if this op then turns out to be a delete-wins @@ -2300,13 +2315,18 @@ function applyConnect(doc: Y.Doc, op: ConnectOp, catalog?: WidgetCatalog): Succe mset(stamps, targetKey, key); const prev = slot.get("link"); if (prev != null && prev !== op.link_id) removeLink(doc, prev); + return true; } + const toIdx = claimDestination(dst); + if (typeof toIdx !== "number") return toIdx; // Source concurrently deleted → the winning connect leaves the input EMPTY // (delete wins over the link, not over the register claim). if (!src || !sourceOutputs) return "no-op"; - const outs = sourceOutputs; + return installConnect(doc, op, dst, sourceOutputs, toIdx); +} +function installConnect(doc: Y.Doc, op: ConnectOp, dst: Y.Map, outs: Y.Array, toIdx: number): SuccessfulOutcome { const links = linksMap(doc); const linkKey = String(op.link_id); if (!links.has(linkKey)) { From 40e07380648c36c7f7c640be8536aaa679919dc2 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 18 Sep 2026 22:56:57 +0000 Subject: [PATCH 16/20] refactor: isolate node presence and durable link restoration Amp-Thread-ID: https://ampcode.com/threads/T-01a0b6a1-ba97-7390-b562-9225304d4bbf Co-authored-by: Amp --- src/applier.ts | 70 +++++++++++++++++++++++++++++--------------------- 1 file changed, 41 insertions(+), 29 deletions(-) diff --git a/src/applier.ts b/src/applier.ts index 551414ff..d0f514a0 100644 --- a/src/applier.ts +++ b/src/applier.ts @@ -923,7 +923,7 @@ function validateSerializableValue(value: unknown, path: string): void { function numericId(value: unknown): number | undefined { if (typeof value === "number" && Number.isFinite(value)) return value; - if (typeof value === "string" && /^[0-9]+$/.test(value)) return parseInt(value, 10); + if (typeof value === "string" && /^\d+$/.test(value)) return parseInt(value, 10); return undefined; } @@ -2610,9 +2610,9 @@ function normalizeGrowFamily( const names: string[] = []; for (const { request } of records) { const [requested, widget, isInputcount] = request; - const name = isInputcount - ? nextInputcountName(inputs, requested, occupied) - : nextAutogrowName(inputs, requested, widget ? null : (templates?.[family] ?? null), occupied); + let name: string; + if (isInputcount) name = nextInputcountName(inputs, requested, occupied); + else name = nextAutogrowName(inputs, requested, widget ? null : (templates?.[family] ?? null), occupied); names.push(name); occupied.add(name); } @@ -2732,7 +2732,7 @@ function nextInputcountName( const sep = requested.lastIndexOf("_"); const elem = sep >= 0 ? requested.slice(0, sep) : ""; const nStr = sep >= 0 ? requested.slice(sep + 1) : requested; - let n = /^[0-9]+$/.test(nStr) ? parseInt(nStr, 10) : 1; + let n = /^\d+$/.test(nStr) ? parseInt(nStr, 10) : 1; let name = `${elem}_${n}`; while (taken.has(name)) { n++; @@ -2839,7 +2839,7 @@ function applyDeleteNode(doc: Y.Doc, op: DeleteNodeOp): SuccessfulOutcome { const stamp = stampKey(op); const presenceWon = prior == null || compareStampKeys(stamp, prior) > 0; const nodeWasPresent = nodes.has(key); - if (presenceWon) { + function deletePresence(): void { const node = nodes.get(key); if (node instanceof Y.Map) { const definition = resolveDefinition(doc, String(node.get("type") ?? "")); @@ -2854,12 +2854,12 @@ function applyDeleteNode(doc: Y.Doc, op: DeleteNodeOp): SuccessfulOutcome { mset(stamps, targetKey, stamp); if (nodes.has(key)) mdel(nodes, key); // absent target → no-op-with-cleanup (delete wins) } + if (presenceWon) deletePresence(); const links = linksMap(doc); const removed = new Set(removedLinks); const removedIds = new Set([...removed].map(String)); const toDelete: Array<{ key: string; retire: boolean }> = []; - let retiredStranded = false; links.forEach((ln: unknown, k: string) => { const tuple = ln as unknown[]; if (removed.has(tuple[0])) { @@ -2875,6 +2875,15 @@ function applyDeleteNode(doc: Y.Doc, op: DeleteNodeOp): SuccessfulOutcome { } // An earlier endpoint deletion can already have removed the live tuple. The // explicit target list still retires that stranded intent. + const retiredStranded = retireStrandedLinks(doc, removedIds); + + scrubDanglingLinkRefs(doc); + if (!presenceWon && toDelete.length === 0 && !retiredStranded) return "lww-dropped"; + return nodeWasPresent || toDelete.length > 0 || retiredStranded ? "applied" : "no-op"; +} + +function retireStrandedLinks(doc: Y.Doc, removedIds: Set): boolean { + let retiredStranded = false; for (const [linkKey, raw] of linkStateMap(doc).entries()) { if (typeof raw !== "object" || raw === null) continue; const tuple = (raw as OperationLinkState | ImportedLinkState).tuple; @@ -2883,10 +2892,7 @@ function applyDeleteNode(doc: Y.Doc, op: DeleteNodeOp): SuccessfulOutcome { retiredStranded = true; } } - - scrubDanglingLinkRefs(doc); - if (!presenceWon && toDelete.length === 0 && !retiredStranded) return "lww-dropped"; - return nodeWasPresent || toDelete.length > 0 || retiredStranded ? "applied" : "no-op"; + return retiredStranded; } /** @@ -2911,23 +2917,8 @@ function restoreDurableLinks(doc: Y.Doc, nodeId: unknown): void { const outs = src.get("outputs"); if (!(outs instanceof Y.Array) || !(outs.get(tuple[2]) instanceof Y.Map)) return; - let ins = dst.get("inputs"); - if (!(ins instanceof Y.Array)) { - ins = new Y.Array(); - mset(dst, "inputs", ins); - } - const inputArray = ins as Y.Array; - const destination = state.destination; - if (!destination || typeof destination.to_slot !== "number") return; - while (inputArray.length <= destination.to_slot) { - const slotIndex = inputArray.length; - if (slotIndex !== destination.to_slot) return; - const slot = new Y.Map(); - for (const [key, value] of Object.entries(destination.slot)) slot.set(key, structuredClone(value)); - inputArray.insert(slotIndex, [slot]); - } - const slot = inputArray.get(destination.to_slot); - if (!(slot instanceof Y.Map)) return; + const slot = restoreDestinationInput(dst, state); + if (slot === null) return; const incumbent = slot.get("link"); if (incumbent != null && String(incumbent) !== String(tuple[0])) return; @@ -2946,6 +2937,26 @@ function restoreDurableLinks(doc: Y.Doc, nodeId: unknown): void { }); } +function restoreDestinationInput(dst: Y.Map, state: OperationLinkState): Y.Map | null { + let ins = dst.get("inputs"); + if (!(ins instanceof Y.Array)) { + ins = new Y.Array(); + mset(dst, "inputs", ins); + } + const inputArray = ins as Y.Array; + const destination = state.destination; + if (!destination || typeof destination.to_slot !== "number") return null; + while (inputArray.length <= destination.to_slot) { + const slotIndex = inputArray.length; + if (slotIndex !== destination.to_slot) return null; + const slot = new Y.Map(); + for (const [key, value] of Object.entries(destination.slot)) slot.set(key, structuredClone(value)); + inputArray.insert(slotIndex, [slot]); + } + const slot = inputArray.get(destination.to_slot); + return slot instanceof Y.Map ? slot : null; +} + /** * Rewrite ONE node's slot-level link references from the live `links` map: * `inputs[i].link` is the link whose tuple lands on slot `i`, and @@ -3153,5 +3164,6 @@ function applyClear(doc: Y.Doc, op: Extract): SuccessfulOut mset(meta, "groups", []); applied = true; } - return applied ? "applied" : dropped ? "lww-dropped" : "no-op"; + if (applied) return "applied"; + return dropped ? "lww-dropped" : "no-op"; } From bf523046c6974c5da901745a7e2dc701417ead07 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 18 Sep 2026 22:58:40 +0000 Subject: [PATCH 17/20] test: separate fixture checks and simplify independent comparators Amp-Thread-ID: https://ampcode.com/threads/T-01a0b6a1-ba97-7390-b562-9225304d4bbf Co-authored-by: Amp --- test/collab-trace.test.ts | 26 +++++---- test/connect-lww.test.ts | 6 +- test/convergence.test.ts | 7 ++- test/define-subgraph.test.ts | 5 +- test/dochost-driver.test.ts | 6 +- test/graph-invariant-oracle.ts | 11 ++-- test/helpers.ts | 38 +++++++----- test/insert-workflow.test.ts | 21 +++---- test/nested-encoding-loss.regression.test.ts | 61 ++++++++++---------- test/opid-reuse-order-dependence.test.ts | 2 +- test/register-families.property.test.ts | 9 ++- 11 files changed, 105 insertions(+), 87 deletions(-) diff --git a/test/collab-trace.test.ts b/test/collab-trace.test.ts index 36a4d72a..b4426d05 100644 --- a/test/collab-trace.test.ts +++ b/test/collab-trace.test.ts @@ -20,7 +20,7 @@ import { type SemanticOpTraceStep, type WorkflowJSON, } from "../src/index.js"; -import { loadCatalog } from "./helpers.js"; +import { compareText, loadCatalog } from "./helpers.js"; const catalog = loadCatalog(); const opId = (label: string) => createHash("sha256").update(label).digest("hex").slice(0, 32); @@ -28,7 +28,8 @@ const opId = (label: string) => createHash("sha256").update(label).digest("hex") function canonical(value: unknown): string { if (value === null || typeof value !== "object") return JSON.stringify(value); if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`; - return `{${Object.keys(value as object).sort().map((key) => `${JSON.stringify(key)}:${canonical((value as Record)[key])}`).join(",")}}`; + const entries = Object.keys(value as object).sort().map((key) => `${JSON.stringify(key)}:${canonical((value as Record)[key])}`); + return `{${entries.join(",")}}`; } function hash(value: unknown) { @@ -37,11 +38,11 @@ function hash(value: unknown) { function normalized(doc: Y.Doc): WorkflowJSON { const value = structuredClone(project(doc, catalog)); - value.nodes.sort((a, b) => String(a.id) < String(b.id) ? -1 : String(a.id) > String(b.id) ? 1 : 0); + value.nodes.sort((a, b) => compareText(String(a.id), String(b.id))); value.links.sort((left, right) => { const a = left as unknown[]; const b = right as unknown[]; - return String(a[0]) < String(b[0]) ? -1 : String(a[0]) > String(b[0]) ? 1 : 0; + return compareText(String(a[0]), String(b[0])); }); return value; } @@ -74,13 +75,16 @@ function capture(doc: Y.Doc, op: Op, arrival_index: number, parents: SemanticOpT const targetKey = stampTargetKey(op); const winner = afterStamps[targetKey]; const incoming = stampKey(op); - const evidence = result.outcome === "lww-dropped" && Array.isArray(winner) - ? { kind: "lww-comparison" as const, winning_stamp: winner as [number, string, string], losing_stamp: incoming } - : result.outcome === "no-op" && alreadyApplied - ? { kind: "dedupe" as const, original_op_id: op.op_id } - : result.outcome === "rejected" - ? { kind: "rejection" as const, code: result.reason.code, message: result.reason.message, failing_index: 0 } - : { kind: "none" as const }; + let evidence: SemanticOpTraceStep["decision_evidence"]; + if (result.outcome === "lww-dropped" && Array.isArray(winner)) { + evidence = { kind: "lww-comparison", winning_stamp: winner as [number, string, string], losing_stamp: incoming }; + } else if (result.outcome === "no-op" && alreadyApplied) { + evidence = { kind: "dedupe", original_op_id: op.op_id }; + } else if (result.outcome === "rejected") { + evidence = { kind: "rejection", code: result.reason.code, message: result.reason.message, failing_index: 0 }; + } else { + evidence = { kind: "none" }; + } return { step_id: `s-${arrival_index}`, kind: "semantic-op", diff --git a/test/connect-lww.test.ts b/test/connect-lww.test.ts index 3bc3a55c..f634fea1 100644 --- a/test/connect-lww.test.ts +++ b/test/connect-lww.test.ts @@ -192,7 +192,11 @@ function interleavings(a: T[], b: T[]): T[][] { } function tags(ops: Op[]): string { - return ops.map((o) => o.op_id.replace(/0+$/, "")).join(","); + return ops.map((o) => { + let end = o.op_id.length; + while (end > 0 && o.op_id[end - 1] === "0") end--; + return o.op_id.slice(0, end); + }).join(","); } /** diff --git a/test/convergence.test.ts b/test/convergence.test.ts index 557bda89..e4316d57 100644 --- a/test/convergence.test.ts +++ b/test/convergence.test.ts @@ -121,9 +121,10 @@ describe("two-doc convergence through the single-applier discipline", () => { const windows = reorderableWindows(ops); const reorderable = windows.filter((w) => w.length > 1); const permuted = (variant: "reverse" | "rotate"): Op[] => - windows.flatMap((w) => - w.length === 1 ? w : variant === "reverse" ? [...w].reverse() : [...w.slice(1), w[0]!], - ); + windows.flatMap((w) => { + if (w.length === 1) return w; + return variant === "reverse" ? [...w].reverse() : [...w.slice(1), w[0]!]; + }); it(`${file}: interleaved orders converge to byte-equal projections (${reorderable.length} windows, ${reorderable.reduce((n, w) => n + w.length, 0)} reordered ops)`, () => { expect(reorderable.length, "corpus must actually exercise reordering").toBeGreaterThan(0); diff --git a/test/define-subgraph.test.ts b/test/define-subgraph.test.ts index cc6c2737..c22b8217 100644 --- a/test/define-subgraph.test.ts +++ b/test/define-subgraph.test.ts @@ -14,6 +14,7 @@ import { } from "../src/index.js" import { appliedMap, definitionsMap, metaMap, stampsMap } from "../src/doc.js" import { stampKey } from "../src/stamps.js" +import { compareText } from "./helpers.js" const catalog: WidgetCatalog = { types: { @@ -56,7 +57,7 @@ const rejectionCode = (doc: Y.Doc, op: Op) => const winningReplacement = (incumbent: SubgraphDefinition, replacement: SubgraphDefinition) => { const canonical = (value: unknown): string => JSON.stringify(value, (_key, child: unknown) => child && typeof child === "object" && !Array.isArray(child) - ? Object.fromEntries(Object.entries(child).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) + ? Object.fromEntries(Object.entries(child).sort(([a], [b]) => compareText(a, b))) : child) const digest = (value: unknown) => createHash("sha256").update(canonical(value)).digest("hex") const incumbentDigest = digest(incumbent) @@ -145,7 +146,7 @@ describe("define_subgraph application", () => { expect(applyOps(doc, [op], catalog).outcomes[0]?.outcome).toBe("applied") const expected = createHash("sha256").update(JSON.stringify(definition(), (_key, child: unknown) => child && typeof child === "object" && !Array.isArray(child) - ? Object.fromEntries(Object.entries(child).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) + ? Object.fromEntries(Object.entries(child).sort(([a], [b]) => compareText(a, b))) : child)).digest("hex") expect((metaMap(doc).get("__definition_digests") as Record)[subgraphId]).toBe(expected) }) diff --git a/test/dochost-driver.test.ts b/test/dochost-driver.test.ts index a55ce1bc..cd016068 100644 --- a/test/dochost-driver.test.ts +++ b/test/dochost-driver.test.ts @@ -82,6 +82,11 @@ async function serveFixtureRequest( const apply_result = applyFixtureDrift(mode, state.applyNumber, body, rawResult); const projected = project(doc, body.catalog as WidgetCatalog); const projection = mode === "projection" && state.applyNumber === 1 ? { ...projected, extra: true } : projected; + applyFixtureMutation(mode, state, body, doc); + res.end(JSON.stringify({ apply_result, projection, update_b64: Buffer.from(Y.encodeStateAsUpdate(doc, before)).toString("base64") })); +} + +function applyFixtureMutation(mode: string, state: FixtureState, body: Body, doc: Y.Doc): void { if (mode === "hidden-rejection-mutation" && state.applyNumber === 3) { doc.getMap("meta").set("fixture_hidden_rejection_mutation", true); } @@ -97,7 +102,6 @@ async function serveFixtureRequest( throw new Error(`trailing-operation fixture could not apply operation: ${JSON.stringify(trailingResult)}`); } } - res.end(JSON.stringify({ apply_result, projection, update_b64: Buffer.from(Y.encodeStateAsUpdate(doc, before)).toString("base64") })); } async function run(mode = "match", packageRoot = resolve(".")) { diff --git a/test/graph-invariant-oracle.ts b/test/graph-invariant-oracle.ts index 6c429654..861ee828 100644 --- a/test/graph-invariant-oracle.ts +++ b/test/graph-invariant-oracle.ts @@ -95,11 +95,11 @@ export function checkGraphInvariants(doc: Y.Doc): GraphInvariantViolation[] { // that endpoint, which keeps one missing node from producing duplicate noise. const inputClaims = new Map(); const linkEntries = [...links.entries()].sort(([a], [b]) => compareCodeUnits(a, b)); - for (const [linkMapKey, rawTuple] of linkEntries) { + function checkLink(linkMapKey: string, rawTuple: unknown): void { const path = `links[${JSON.stringify(linkMapKey)}]`; if (!Array.isArray(rawTuple) || rawTuple.length < 5) { violation(violations, "I3", path, "link entry is not a tuple with node endpoints"); - continue; + return; } const tuple = rawTuple as unknown[]; @@ -137,7 +137,7 @@ export function checkGraphInvariants(doc: Y.Doc): GraphInvariantViolation[] { inputClaims.set(claimKey, linkMapKey); } - if (destinationExists) { + function checkDestination(): void { const destination = nodes.get(toNodeKey); const inputs = destination instanceof Y.Map ? destination.get("inputs") : undefined; const toSlot = tuple[4]; @@ -162,7 +162,7 @@ export function checkGraphInvariants(doc: Y.Doc): GraphInvariantViolation[] { } } - if (sourceExists) { + function checkSource(): void { const source = nodes.get(fromNodeKey); const outputs = source instanceof Y.Map ? source.get("outputs") : undefined; const fromSlot = tuple[2]; @@ -180,8 +180,11 @@ export function checkGraphInvariants(doc: Y.Doc): GraphInvariantViolation[] { ); } } + if (destinationExists) checkDestination(); + if (sourceExists) checkSource(); } + for (const [linkMapKey, rawTuple] of linkEntries) checkLink(linkMapKey, rawTuple); return violations.sort((a, b) => { const invariant = INVARIANT_ORDER[a.invariant] - INVARIANT_ORDER[b.invariant]; if (invariant !== 0) return invariant; diff --git a/test/helpers.ts b/test/helpers.ts index 44f7af04..fb1eeb2d 100644 --- a/test/helpers.ts +++ b/test/helpers.ts @@ -57,6 +57,25 @@ export function loadLwwVectors(): LwwVectorsFile { return JSON.parse(readFileSync(join(fixturesDir, "lww-vectors.json"), "utf8")) as LwwVectorsFile; } +export function compareText(a: string, b: string): number { + if (a < b) return -1; + return a > b ? 1 : 0; +} + +const canonicalNodes = (nodes: WorkflowNode[]): WorkflowNode[] => nodes.map((node) => ({ + ...node, + ...(Array.isArray(node.outputs) + ? { + outputs: node.outputs.map((output) => { + if (typeof output !== "object" || output === null || !("links" in output) || !Array.isArray(output.links)) { + return output; + } + return { ...output, links: [...output.links].sort((a, b) => Number(a) - Number(b)) }; + }), + } + : {}), +})); + /** * Schema §7 rule 1: sorted-by-id node/link order is canonical (definitions * sorted by id too, matching comfy-cli `workflow_ops.canonical`). Fixture @@ -65,25 +84,12 @@ export function loadLwwVectors(): LwwVectorsFile { */ export function canonicalize(wf: WorkflowJSON): WorkflowJSON { const byId = (a: { id: unknown }, b: { id: unknown }) => - String(a.id) < String(b.id) ? -1 : String(a.id) > String(b.id) ? 1 : 0; + compareText(String(a.id), String(b.id)); const linkId = (l: unknown) => String((l as unknown[])[0]); - const canonicalNodes = (nodes: WorkflowNode[]): WorkflowNode[] => nodes.map((node) => ({ - ...node, - ...(Array.isArray(node.outputs) - ? { - outputs: node.outputs.map((output) => { - if (typeof output !== "object" || output === null || !("links" in output) || !Array.isArray(output.links)) { - return output; - } - return { ...output, links: [...output.links].sort((a, b) => Number(a) - Number(b)) }; - }), - } - : {}), - })); const out: WorkflowJSON = { ...wf, nodes: canonicalNodes(wf.nodes).sort(byId), - links: [...wf.links].sort((a, b) => (linkId(a) < linkId(b) ? -1 : linkId(a) > linkId(b) ? 1 : 0)), + links: [...wf.links].sort((a, b) => compareText(linkId(a), linkId(b))), }; const defs = out["definitions"] as { subgraphs?: { id?: unknown }[] } | undefined; if (defs && Array.isArray(defs.subgraphs)) { @@ -96,7 +102,7 @@ export function canonicalize(wf: WorkflowJSON): WorkflowJSON { ? { nodes: canonicalNodes((definition as { nodes: WorkflowNode[] }).nodes) } : {}), })) - .sort((a, b) => String(a.id) < String(b.id) ? -1 : String(a.id) > String(b.id) ? 1 : 0), + .sort((a, b) => compareText(String(a.id), String(b.id))), }; } return out; diff --git a/test/insert-workflow.test.ts b/test/insert-workflow.test.ts index 36ecb2bb..cb458d4f 100644 --- a/test/insert-workflow.test.ts +++ b/test/insert-workflow.test.ts @@ -89,6 +89,13 @@ function insertOp(workflow: unknown, overrides: Partial = {}): Op { return { ...env(), op: "insert_workflow", workflow, ...overrides } as unknown as Op; } +function replaySnapshot(seed: Uint8Array, ops: Op[]): WorkflowJSON { + const doc = new Y.Doc(); + Y.applyUpdate(doc, seed); + for (const op of ops) applyOps(doc, [op], catalog); + return project(doc, catalog); +} + const bytes = (doc: Y.Doc): Buffer => Buffer.from(Y.encodeStateAsUpdate(doc)); function ids(wf: WorkflowJSON): unknown[] { @@ -536,12 +543,7 @@ describe("insert_workflow: happy path", () => { it("makes colliding concurrent inserts converge in either legal arrival order", () => { const seed = Y.encodeStateAsUpdate(mint(baseWorkflow(), catalog)); - const run = (ops: Op[]): WorkflowJSON => { - const doc = new Y.Doc(); - Y.applyUpdate(doc, seed); - for (const op of ops) applyOps(doc, [op], catalog); - return project(doc, catalog); - }; + const run = (ops: Op[]) => replaySnapshot(seed, ops); const lower = insertOp( { nodes: [{ id: 100, type: "Src", title: "lower" }, { id: 101, type: "Sink" }], links: [[200, 100, 0, 101, 0, "lower"]] }, { op_id: "a".repeat(32), stamp: [2, "a"] }, @@ -567,12 +569,7 @@ describe("insert_workflow: happy path", () => { const remove = { ...env(), op: "delete_node", node_id: 1, removed_links: [], stamp: [2, "b"], } as unknown as Op; - const run = (ops: Op[]): WorkflowJSON => { - const doc = new Y.Doc(); - Y.applyUpdate(doc, seed); - for (const op of ops) applyOps(doc, [op], catalog); - return project(doc, catalog); - }; + const run = (ops: Op[]) => replaySnapshot(seed, ops); const deleteThenInsert = run([remove, insert]); const insertThenDelete = run([insert, remove]); diff --git a/test/nested-encoding-loss.regression.test.ts b/test/nested-encoding-loss.regression.test.ts index e386cfe6..fe92b669 100644 --- a/test/nested-encoding-loss.regression.test.ts +++ b/test/nested-encoding-loss.regression.test.ts @@ -157,27 +157,30 @@ describe("KA-1: `encodingLosses` agrees with a real encode → decode", () => { const disagreements: string[] = []; let flagged = 0; let clean = 0; + function checkSample(pname: string, place: (v: unknown) => unknown, sname: string, make: () => unknown): void { + let placed: unknown; + try { + // The value AS IT WILL BE STORED, per the detector's contract and + // the storability gate's: cloning is what normalizes a class instance + // or a prototype-less object into a plain, faithfully encodable one. + // A value the clone REFUSES never reaches either question. + placed = structuredClone(place(make())); + } catch { + return; + } + // A value yjs REFUSES is the storability gate's business, not this one. + if (!isStorableMapValue(placed)) return; + const lossy = !identical(placed, roundTrip(placed)); + const reported = encodingLosses(placed).length > 0; + if (reported !== lossy) { + disagreements.push(`${sname} @ ${pname}: round trip lossy=${String(lossy)}, reported=${String(reported)}`); + } + if (lossy) flagged++; + else clean++; + } for (const [pname, place] of PLACEMENTS) { for (const [sname, make] of SAMPLES) { - let placed: unknown; - try { - // The value AS IT WILL BE STORED, per the detector's contract and - // the storability gate's: cloning is what normalizes a class instance - // or a prototype-less object into a plain, faithfully encodable one. - // A value the clone REFUSES never reaches either question. - placed = structuredClone(place(make())); - } catch { - continue; - } - // A value yjs REFUSES is the storability gate's business, not this one. - if (!isStorableMapValue(placed)) continue; - const lossy = !identical(placed, roundTrip(placed)); - const reported = encodingLosses(placed).length > 0; - if (reported !== lossy) { - disagreements.push(`${sname} @ ${pname}: round trip lossy=${String(lossy)}, reported=${String(reported)}`); - } - if (lossy) flagged++; - else clean++; + checkSample(pname, place, sname, make); } } expect(disagreements).toEqual([]); @@ -255,6 +258,10 @@ describe("KA-1: the gap is depth-independent and the same in both containers", ( }); describe("KA-1: two replicas disagree about document contents, end to end", () => { + const readImage = (doc: Y.Doc) => + ((doc.getMap("nodes").get("300") as Y.Map).get("widgets") as Y.Map).get( + "image", + ) as { a: unknown }; it("host → follower (raw update): no error, byte-identical, different contents", () => { const [a, b] = forkedPair(); const result = applyOps( @@ -315,12 +322,8 @@ describe("KA-1: two replicas disagree about document contents, end to end", () = ), ).toBeUndefined(); - const read = (doc: Y.Doc) => - ((doc.getMap("nodes").get("300") as Y.Map).get("widgets") as Y.Map).get( - "image", - ) as { a: unknown }; - expect(read(a).a).toBeInstanceOf(Map); - expect(read(b).a).toEqual({}); + expect(readImage(a).a).toBeInstanceOf(Map); + expect(readImage(b).a).toEqual({}); }); it("a NESTED Date makes the disagreement visible in the PROJECTION, not only in memory", () => { @@ -355,12 +358,8 @@ describe("KA-1: two replicas disagree about document contents, end to end", () = ).toBeUndefined(); const reloaded = new Y.Doc(); Y.applyUpdate(reloaded, Y.encodeStateAsUpdate(a)); - const read = (doc: Y.Doc) => - ((doc.getMap("nodes").get("300") as Y.Map).get("widgets") as Y.Map).get( - "image", - ) as { a: unknown }; - expect(read(a).a).toBeInstanceOf(Map); - expect(read(reloaded).a).not.toBeInstanceOf(Map); + expect(readImage(a).a).toBeInstanceOf(Map); + expect(readImage(reloaded).a).not.toBeInstanceOf(Map); }); }); diff --git a/test/opid-reuse-order-dependence.test.ts b/test/opid-reuse-order-dependence.test.ts index 57a08921..b8d038d9 100644 --- a/test/opid-reuse-order-dependence.test.ts +++ b/test/opid-reuse-order-dependence.test.ts @@ -3,7 +3,7 @@ import { applyOps, mint, project, type SetWidgetOp } from "../src/index.js"; import { loadCatalog, loadLwwVectors } from "./helpers.js"; /** - * Characterizes op_id-reuse order-dependence (todo `OPID-REUSE-ORDER-DEPENDENT`, + * Characterizes op_id-reuse order-dependence (tracking item `OPID-REUSE-ORDER-DEPENDENT`, * follow-up to CMP #33 / `reports/pr-review/gauntlet-75.md`). * * The `op_id_reuse` gate (`src/applier.ts:152-186`) records a payload digest on diff --git a/test/register-families.property.test.ts b/test/register-families.property.test.ts index 819011f3..cd6c5b9e 100644 --- a/test/register-families.property.test.ts +++ b/test/register-families.property.test.ts @@ -171,11 +171,10 @@ function fork(snapshot: Uint8Array): Y.Doc { function applyInterleaved(doc: Y.Doc, ordered: [Op, Op], causal: Op, batch: BatchKind): void { const stream = [ordered[0], causal, ordered[1]]; - const groups = batch === "one" - ? [stream] - : batch === "split-after-first" - ? [stream.slice(0, 1), stream.slice(1)] - : stream.map((op) => [op]); + let groups: Op[][]; + if (batch === "one") groups = [stream]; + else if (batch === "split-after-first") groups = [stream.slice(0, 1), stream.slice(1)]; + else groups = stream.map((op) => [op]); for (const group of groups) { const result = applyOps(doc, group, catalog); expect(result.outcomes.find((outcome) => outcome.outcome === "rejected")).toBeUndefined(); From 42bd586e2bc921017f545d9c9f619b20d1febc52 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 18 Sep 2026 22:58:48 +0000 Subject: [PATCH 18/20] test: clarify clock matrix ordering and divergence classification Amp-Thread-ID: https://ampcode.com/threads/T-01a0b6a1-ba97-7390-b562-9225304d4bbf Co-authored-by: Amp --- test/clock-matrix/clock-matrix.test.ts | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/test/clock-matrix/clock-matrix.test.ts b/test/clock-matrix/clock-matrix.test.ts index da30eb8d..268ce86e 100644 --- a/test/clock-matrix/clock-matrix.test.ts +++ b/test/clock-matrix/clock-matrix.test.ts @@ -121,7 +121,8 @@ function deleteNode(label: string, actor: string, base_version: number, lamport: } function compareStrings(a: string, b: string): number { - return a < b ? -1 : a > b ? 1 : 0; + if (a < b) return -1; + return a > b ? 1 : 0; } function compareBase(a: LogicalOp, b: LogicalOp): number { @@ -205,7 +206,8 @@ function withDivergence(results: Record { const candidate = results[scheme]; const sameOrder = JSON.stringify(candidate.application_order) === JSON.stringify(baseline.application_order); - const divergence_class = candidate.final_state_hash !== baseline.final_state_hash ? "DIVERGENT" : sameOrder ? "identical" : "equivalent-semantics"; + const semanticMatch = sameOrder ? "identical" : "equivalent-semantics"; + const divergence_class = candidate.final_state_hash !== baseline.final_state_hash ? "DIVERGENT" : semanticMatch; return [scheme, { ...candidate, divergence_class }]; })) as Record; } From 57720b6a7bb69ea24adecf2331830da1d50015c3 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 18 Sep 2026 23:01:55 +0000 Subject: [PATCH 19/20] test: separate exhaustive graph and identity case enumeration Amp-Thread-ID: https://ampcode.com/threads/T-01a0b6a1-ba97-7390-b562-9225304d4bbf Co-authored-by: Amp --- ...ect-delete-equivalence.permutation.test.ts | 109 +++++++++++------- .../duplicate-link-id.permutation.test.ts | 40 ++++--- 2 files changed, 90 insertions(+), 59 deletions(-) diff --git a/test/permutation/connect-delete-equivalence.permutation.test.ts b/test/permutation/connect-delete-equivalence.permutation.test.ts index c158cb96..50e9edb7 100644 --- a/test/permutation/connect-delete-equivalence.permutation.test.ts +++ b/test/permutation/connect-delete-equivalence.permutation.test.ts @@ -50,6 +50,13 @@ const EXPECTED_EXECUTIONS = 12_288; type DeleteAxis = "source" | "destination"; type BatchMode = "together" | "split"; +interface GraphCase { + axis: DeleteAxis; + presence: (typeof ENDPOINT_PRESENCE)[number]; + slots: (typeof SLOT_PAIRS)[number]; + incumbent: boolean; +} + interface LogicalState { projection: WorkflowJSON; outcomes: Array<{ opId: string; outcome: string }>; @@ -156,6 +163,29 @@ function comparable(state: LogicalState): unknown { return state.projection; } +function connectOutcome(state: LogicalState, connectId: string): string { + return state.outcomes.find((outcome) => outcome.opId === connectId)?.outcome ?? "batch-aborted"; +} + +function* graphCases(): Generator { + for (const axis of ["source", "destination"] as const) { + for (const presence of ENDPOINT_PRESENCE) { + for (const slots of SLOT_PAIRS) { + for (const incumbent of [false, true] as const) yield { axis, presence, slots, incumbent }; + } + } + } +} + +function* stampCases() { + for (const actorA of ACTORS) { + for (const actorB of ACTORS) { + if (actorA === actorB) continue; + for (const versions of VERSION_PAIRS) yield { actors: [actorA, actorB] as const, versions }; + } + } +} + describe("bounded exhaustive connect x delete equivalence", () => { it("classifies only Amendment A6 state-dependent slot races as divergent", () => { let executions = 0; @@ -165,47 +195,44 @@ describe("bounded exhaustive connect x delete equivalence", () => { let equivalentPairs = 0; const unexpected: string[] = []; - for (const axis of ["source", "destination"] as const) { - for (const presence of ENDPOINT_PRESENCE) { - for (const slots of SLOT_PAIRS) { - for (const incumbent of [false, true] as const) { - for (const actorA of ACTORS) { - for (const actorB of ACTORS) { - if (actorA === actorB) continue; - for (const versions of VERSION_PAIRS) { - const pair = operations(serial, [actorA, actorB], versions, slots, axis); - serial += 2; - for (const mode of ["together", "split"] as const) { - const forward = run(base(presence, incumbent), pair, mode); - const reverse = run(base(presence, incumbent), [pair[1], pair[0]], mode); - executions += 2; - const repro = JSON.stringify({ axis, presence, slots, incumbent, actors: [actorA, actorB], versions, mode }); - const divergent = JSON.stringify(comparable(forward)) !== JSON.stringify(comparable(reverse)); - const connectId = pair[0].op_id; - const connectOutcome = (state: LogicalState): string => - state.outcomes.find((outcome) => outcome.opId === connectId)?.outcome ?? "batch-aborted"; - const forwardConnect = connectOutcome(forward); - const reverseConnect = connectOutcome(reverse); - const bothPresent = presence.source && presence.destination; - const permittedA6Tuple = axis === "source" - ? bothPresent && slots.from === 5 && slots.to === 0 - : mode === "together" && presence.destination && - (slots.to === 5 || bothPresent && slots.from === 5); - const a6 = divergent && permittedA6Tuple && - (forwardConnect === "rejected") !== (reverseConnect === "rejected"); - const permittedAbortTuple = mode === "together" && axis === "source" && - bothPresent && slots.to === 5; - const abortBoundary = divergent && permittedAbortTuple && !a6 && - forwardConnect === "rejected" && reverseConnect === "rejected"; - if (a6) a6DivergentPairs++; - else if (abortBoundary) abortBoundaryPairs++; - else if (divergent) unexpected.push(`${repro} outcomes=${JSON.stringify([forward.outcomes, reverse.outcomes])}`); - else equivalentPairs++; - } - } - } - } - } + function checkArrivalPair( + graph: GraphCase, + pair: readonly [ConnectOp, DeleteNodeOp], + mode: BatchMode, + repro: string, + ): void { + const { axis, presence, slots, incumbent } = graph; + const forward = run(base(presence, incumbent), pair, mode); + const reverse = run(base(presence, incumbent), [pair[1], pair[0]], mode); + executions += 2; + const divergent = JSON.stringify(comparable(forward)) !== JSON.stringify(comparable(reverse)); + const connectId = pair[0].op_id; + const forwardConnect = connectOutcome(forward, connectId); + const reverseConnect = connectOutcome(reverse, connectId); + const bothPresent = presence.source && presence.destination; + const permittedA6Tuple = axis === "source" + ? bothPresent && slots.from === 5 && slots.to === 0 + : mode === "together" && presence.destination && + (slots.to === 5 || bothPresent && slots.from === 5); + const a6 = divergent && permittedA6Tuple && + (forwardConnect === "rejected") !== (reverseConnect === "rejected"); + const permittedAbortTuple = mode === "together" && axis === "source" && + bothPresent && slots.to === 5; + const abortBoundary = divergent && permittedAbortTuple && !a6 && + forwardConnect === "rejected" && reverseConnect === "rejected"; + if (a6) a6DivergentPairs++; + else if (abortBoundary) abortBoundaryPairs++; + else if (divergent) unexpected.push(`${repro} outcomes=${JSON.stringify([forward.outcomes, reverse.outcomes])}`); + else equivalentPairs++; + } + + for (const graph of graphCases()) { + for (const { actors, versions } of stampCases()) { + const pair = operations(serial, actors, versions, graph.slots, graph.axis); + serial += 2; + for (const mode of ["together", "split"] as const) { + const repro = JSON.stringify({ ...graph, actors, versions, mode }); + checkArrivalPair(graph, pair, mode, repro); } } } diff --git a/test/permutation/duplicate-link-id.permutation.test.ts b/test/permutation/duplicate-link-id.permutation.test.ts index b58fa272..9813a9cb 100644 --- a/test/permutation/duplicate-link-id.permutation.test.ts +++ b/test/permutation/duplicate-link-id.permutation.test.ts @@ -139,6 +139,17 @@ function assertCoherentGraph(wf: WorkflowJSON, owner: ConnectOp, repro: string): expect(refs, repro).toEqual(["700", "700"]); } +function* identityCases() { + for (const linkIds of LINK_ID_PAIRS) { + for (const actorA of ACTORS) { + for (const actorB of ACTORS) { + if (actorA === actorB) continue; + for (const versions of VERSION_PAIRS) yield { linkIds, actors: [actorA, actorB] as const, versions }; + } + } + } +} + describe("bounded exhaustive normalized link_id collisions", () => { it("replays every language-neutral parity vector in both arrival orders", () => { let executions = 0; @@ -162,24 +173,17 @@ describe("bounded exhaustive normalized link_id collisions", () => { it("covers every declared permutation with stamped complete-tuple ownership", () => { let executions = 0; let serial = 1; - for (const linkIds of LINK_ID_PAIRS) { - for (const actorA of ACTORS) { - for (const actorB of ACTORS) { - if (actorA === actorB) continue; - for (const versions of VERSION_PAIRS) { - for (const endpoints of ENDPOINT_PAIRS) { - const a = connect(serial++, actorA, versions[0], linkIds[0], endpoints[0]); - const b = connect(serial++, actorB, versions[1], linkIds[1], endpoints[1]); - for (const order of [[a, b], [b, a]] as const) { - for (const batched of [true, false]) { - const repro = JSON.stringify({ linkIds, actors: [actorA, actorB], versions, endpoints, order: order.map((op) => op.op_id), batched }); - const wf = run(order, batched); - expect(String(tuple(wf)[0]), repro).toBe("700"); - assertCoherentGraph(wf, winner(a, b), repro); - executions++; - } - } - } + for (const { linkIds, actors, versions } of identityCases()) { + for (const endpoints of ENDPOINT_PAIRS) { + const a = connect(serial++, actors[0], versions[0], linkIds[0], endpoints[0]); + const b = connect(serial++, actors[1], versions[1], linkIds[1], endpoints[1]); + for (const order of [[a, b], [b, a]] as const) { + for (const batched of [true, false]) { + const repro = JSON.stringify({ linkIds, actors, versions, endpoints, order: order.map((op) => op.op_id), batched }); + const wf = run(order, batched); + expect(String(tuple(wf)[0]), repro).toBe("700"); + assertCoherentGraph(wf, winner(a, b), repro); + executions++; } } } From 554b4c44ba80dbd9a9a485a1f37d5afce06058ed Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 18 Sep 2026 23:01:55 +0000 Subject: [PATCH 20/20] test: separate full-pool generation and batch checks Amp-Thread-ID: https://ampcode.com/threads/T-01a0b6a1-ba97-7390-b562-9225304d4bbf Co-authored-by: Amp --- .../full-op-pool.permutation.test.ts | 141 ++++++++++-------- 1 file changed, 75 insertions(+), 66 deletions(-) diff --git a/test/permutation/full-op-pool.permutation.test.ts b/test/permutation/full-op-pool.permutation.test.ts index ca27e72c..ae16a276 100644 --- a/test/permutation/full-op-pool.permutation.test.ts +++ b/test/permutation/full-op-pool.permutation.test.ts @@ -154,6 +154,51 @@ function makeOp( ): WireOp { const env = envelope(serial, actor, version); const value = side === 0 ? serial : -serial; + function makeConnection(): WireOp { + const common = { + ...env, + op: "connect" as const, + link_id: 100 + side, + from_node: 10, + from_slot: precondition === "from-slot-out-of-range" ? 5 : 0, + to_node: 20, + link_type: "VALUE", + }; + if (precondition === "interior-or-inputcount") { + return { ...common, grow: { name: `value_${side + 1}`, type: "VALUE", inputcount: { widget: "count", value } } }; + } + if (precondition === "promoted-or-autogrow") { + if (side === 0) { + return { ...common, to_node: 57, link_type: "INT", grow: { name: "width", type: "INT", promoted: true } }; + } + return { ...common, grow: { name: `values.value${side}`, type: "VALUE" } }; + } + return { ...common, to_slot: precondition === "to-slot-out-of-range" ? 5 : 0 }; + } + function makeWidgetWrite(): WireOp { + if (precondition === "interior-or-inputcount") { + return { + ...env, + op: "set_widget", + node_id: "57/13", + widget: "missing", + value, + path: ["57", "13"], + inner_widget: "missing", + }; + } + if (precondition === "promoted-or-autogrow") { + return { + ...env, + op: "set_widget", + node_id: 57, + widget: "width", + value, + promoted: { value_index: 0, instance_path: ["57"], host_widgets_values: [value] }, + }; + } + return { ...env, op: "set_widget", node_id: 20, widget: "count", value }; + } switch (kind) { case "add_node": return { @@ -165,27 +210,7 @@ function makeOp( pos: [value, value], node: node(40, "Aux", [], [], [value]), }; - case "connect": { - const common = { - ...env, - op: "connect" as const, - link_id: 100 + side, - from_node: 10, - from_slot: precondition === "from-slot-out-of-range" ? 5 : 0, - to_node: 20, - link_type: "VALUE", - }; - if (precondition === "interior-or-inputcount") { - return { ...common, grow: { name: `value_${side + 1}`, type: "VALUE", inputcount: { widget: "count", value } } }; - } - if (precondition === "promoted-or-autogrow") { - if (side === 0) { - return { ...common, to_node: 57, link_type: "INT", grow: { name: "width", type: "INT", promoted: true } }; - } - return { ...common, grow: { name: `values.value${side}`, type: "VALUE" } }; - } - return { ...common, to_slot: precondition === "to-slot-out-of-range" ? 5 : 0 }; - } + case "connect": return makeConnection(); case "disconnect": return { ...env, @@ -194,29 +219,7 @@ function makeOp( to_node: precondition === "destination-missing" ? 999 : 20, to_slot: precondition === "to-slot-out-of-range" ? 5 : 0, }; - case "set_widget": - if (precondition === "interior-or-inputcount") { - return { - ...env, - op: "set_widget", - node_id: "57/13", - widget: "missing", - value, - path: ["57", "13"], - inner_widget: "missing", - }; - } - if (precondition === "promoted-or-autogrow") { - return { - ...env, - op: "set_widget", - node_id: 57, - widget: "width", - value, - promoted: { value_index: 0, instance_path: ["57"], host_widgets_values: [value] }, - }; - } - return { ...env, op: "set_widget", node_id: 20, widget: "count", value }; + case "set_widget": return makeWidgetWrite(); case "delete_node": return { ...env, op: "delete_node", node_id: side === 0 ? 10 : 20, removed_links: [80, 100, 101] }; case "clear": @@ -250,7 +253,7 @@ function run( const doc = mint(workflow, catalog); const groups = mode === "together" ? [[...ops]] : ops.map((op) => [op]); const outcomes: RunState["outcomes"] = []; - for (const group of groups) { + function applyGroup(group: WireOp[]): void { const before = Y.encodeStateAsUpdate(doc); const result = applyOps(doc, group as Op[], catalog); outcomes.push(...result.outcomes.map((outcome) => ({ @@ -273,6 +276,7 @@ function run( idempotencyVerified.add(op.op); } } + for (const group of groups) applyGroup(group); const appliedIds = new Set(doc.getMap("__applied").keys()); for (const outcome of outcomes) { if (outcome.outcome === "rejected") expect(appliedIds.has(outcome.opId)).toBe(false); @@ -299,12 +303,12 @@ function stable(value: unknown): string { function normalizeR69(workflow: WorkflowJSON): WorkflowJSON { const copy = structuredClone(workflow); - for (const candidate of copy.nodes) { + function normalizeNode(candidate: WorkflowNode): void { for (const output of (candidate.outputs ?? []) as Array<{ links?: unknown[] }>) { if (Array.isArray(output.links)) output.links.sort((a, b) => String(a).localeCompare(String(b))); } const inputs = (candidate.inputs ?? []) as Array<{ link?: unknown; grow_id?: unknown }>; - if (!inputs.some((input) => input.grow_id != null)) continue; + if (!inputs.some((input) => input.grow_id != null)) return; const fixed = inputs.filter((input) => input.grow_id == null); const grown = inputs .filter((input) => input.grow_id != null) @@ -318,6 +322,7 @@ function normalizeR69(workflow: WorkflowJSON): WorkflowJSON { if (link) link[4] = index; } } + for (const candidate of copy.nodes) normalizeNode(candidate); return copy; } @@ -452,6 +457,16 @@ function kindPairs(): Array { return EXHAUSTIVE_KINDS.flatMap((left) => EXHAUSTIVE_KINDS.map((right) => [left, right] as const)); } +function* pairCases() { + for (const kinds of kindPairs()) { + for (const precondition of PRECONDITIONS) { + for (const actors of ACTOR_PAIRS) { + for (const versions of VERSION_PAIRS) yield { kinds, precondition, actors, versions }; + } + } + } +} + describe("full op-pool permutation equivalence", () => { it("covers every declared op-kind pair across representative state, stamp, actor, order, and batch dimensions", () => { let executions = 0; @@ -465,25 +480,19 @@ describe("full op-pool permutation equivalence", () => { let firstR69: string | undefined; let firstRemovedLinkAlias: string | undefined; - for (const kinds of kindPairs()) { - for (const precondition of PRECONDITIONS) { - for (const actors of ACTOR_PAIRS) { - for (const versions of VERSION_PAIRS) { - const pair = kinds.map((kind, side) => makeOp(kind, precondition, side as 0 | 1, serial++, actors[side]!, versions[side]!)); - for (const mode of ["together", "split"] as const) { - const forward = run(base(precondition), pair, mode, idempotencyVerified); - const reverse = run(base(precondition), [pair[1]!, pair[0]!], mode, idempotencyVerified); - executions += 2; - const category = classify(forward, reverse, pair, precondition, mode); - taxonomy[category]++; - if (category === "unexpectedR69" && firstR69 === undefined) { - firstR69 = stable({ kinds, precondition, actors, versions, mode, ops: pair }); - } - if (category === "unexpectedRemovedLinkAlias" && firstRemovedLinkAlias === undefined) { - firstRemovedLinkAlias = stable({ kinds, precondition, actors, versions, mode, ops: pair }); - } - } - } + for (const { kinds, precondition, actors, versions } of pairCases()) { + const pair = kinds.map((kind, side) => makeOp(kind, precondition, side as 0 | 1, serial++, actors[side]!, versions[side]!)); + for (const mode of ["together", "split"] as const) { + const forward = run(base(precondition), pair, mode, idempotencyVerified); + const reverse = run(base(precondition), [pair[1]!, pair[0]!], mode, idempotencyVerified); + executions += 2; + const category = classify(forward, reverse, pair, precondition, mode); + taxonomy[category]++; + if (category === "unexpectedR69" && firstR69 === undefined) { + firstR69 = stable({ kinds, precondition, actors, versions, mode, ops: pair }); + } + if (category === "unexpectedRemovedLinkAlias" && firstRemovedLinkAlias === undefined) { + firstRemovedLinkAlias = stable({ kinds, precondition, actors, versions, mode, ops: pair }); } } }