From bd0da97d5a3c6baac126e09522259577a7794ab5 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 12:41:20 +0000 Subject: [PATCH 01/19] test: reproduce admission, pin and cache invariants --- test/helpers/effects.ts | 56 +++++++++++++++++++ test/invariants/i2-no-loss.test.ts | 22 ++++++++ test/invariants/i5-admission-parity.test.ts | 34 +++++++++++ .../invariants/i7-effects-containment.test.ts | 20 +++++++ 4 files changed, 132 insertions(+) create mode 100644 test/helpers/effects.ts create mode 100644 test/invariants/i2-no-loss.test.ts create mode 100644 test/invariants/i5-admission-parity.test.ts create mode 100644 test/invariants/i7-effects-containment.test.ts diff --git a/test/helpers/effects.ts b/test/helpers/effects.ts new file mode 100644 index 00000000..131764b4 --- /dev/null +++ b/test/helpers/effects.ts @@ -0,0 +1,56 @@ +import { lstat, readdir, readFile, readlink } from "node:fs/promises"; +import { join } from "node:path"; +import { execFileSync } from "node:child_process"; + +export interface EffectSnapshot { + tree: Record; + claims: Record; + git?: { index: string; refs: string; head: string }; +} +export interface EffectPolicy { + // Exact relative paths only, each with a fixture-specific reason. No globs or prefixes. + exclude?: Record; + manifests?: string[]; + git?: boolean; +} + +export async function snapshot(root: string, policy: EffectPolicy = {}): Promise { + for (const [path, reason] of Object.entries(policy.exclude ?? {})) { + if (!reason.trim() || path.startsWith("/") || path.split("/").some(p => p === ".." || p === "." || !p) + || /[*?\[\]]/.test(path)) throw new Error("Exclusions require an exact relative path and reason"); + } + const result: EffectSnapshot = { tree: {}, claims: {} }; + async function visit(relative: string): Promise { + const path = join(root, relative); + const stat = await lstat(path); + if (stat.isDirectory()) { + if (relative) result.tree[relative] = { kind: "directory", mode: stat.mode & 0o7777 }; + for (const name of (await readdir(path)).sort()) await visit(relative ? `${relative}/${name}` : name); + } else if (!Object.hasOwn(policy.exclude ?? {}, relative)) { + result.tree[relative] = stat.isSymbolicLink() + ? { kind: "symlink", mode: stat.mode & 0o7777, target: await readlink(path) } + : { kind: "file", mode: stat.mode & 0o7777, bytes: (await readFile(path)).toString("base64") }; + } else if ((policy.manifests ?? []).includes(relative)) { + throw new Error("Manifest claims cannot be excluded"); + } + } + await visit(""); + for (const path of policy.manifests ?? []) result.claims[path] = JSON.parse(await readFile(join(root, path), "utf8")); + if (policy.git) { + const git = (...args: string[]) => execFileSync("git", ["-C", root, ...args], { encoding: "utf8" }); + result.git = { index: git("ls-files", "--stage", "-z"), refs: git("show-ref", "--head"), head: git("symbolic-ref", "-q", "HEAD") }; + } + return result; +} + +export function diffEffects(before: EffectSnapshot, after: EffectSnapshot): string[] { + const changes: string[] = []; + for (const section of ["tree", "claims", "git"] as const) { + const left = before[section] ?? {}; + const right = after[section] ?? {}; + for (const key of [...new Set([...Object.keys(left), ...Object.keys(right)])].sort()) { + if (JSON.stringify(left[key as keyof typeof left]) !== JSON.stringify(right[key as keyof typeof right])) changes.push(`${section}:${key}`); + } + } + return changes; +} diff --git a/test/invariants/i2-no-loss.test.ts b/test/invariants/i2-no-loss.test.ts new file mode 100644 index 00000000..918772aa --- /dev/null +++ b/test/invariants/i2-no-loss.test.ts @@ -0,0 +1,22 @@ +import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { expect, it } from "vitest"; +import { GitSourceDriver } from "../../src/source/git.js"; +import { diffEffects, snapshot } from "../helpers/effects.js"; + +it("read_missing_git_preserves_cache", async () => { + const root = await mkdtemp(join(tmpdir(), "invariant-i2-")); + try { + const driver = new GitSourceDriver(); + // Local nonexistent source: clone must fail without network access. + const resolved = await driver.resolve(`git+file://${join(root, "missing.git")}`, { cacheRoot: join(root, "cache") }); + await mkdir(resolved.resolvedPath, { recursive: true }); + await writeFile(join(resolved.resolvedPath, "sentinel"), "preserve me"); + const before = await snapshot(root); + const failure = await driver.fetch(resolved).then(() => undefined, error => error); + expect(failure).toBeInstanceOf(Error); + // Expected: a read refuses an incomplete checkout without deleting existing bytes. + expect(diffEffects(before, await snapshot(root))).toEqual([]); + } finally { await rm(root, { recursive: true, force: true }); } +}); diff --git a/test/invariants/i5-admission-parity.test.ts b/test/invariants/i5-admission-parity.test.ts new file mode 100644 index 00000000..78bad990 --- /dev/null +++ b/test/invariants/i5-admission-parity.test.ts @@ -0,0 +1,34 @@ +import { mkdtemp, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { expect, it } from "vitest"; +import { createCombinedInstallPlan, applyCombinedInstallPlan, readInstallManifest, type DesiredArtifact } from "../../src/install/index.js"; +import { targetMappingSchema, type AdapterConfig } from "../../src/model/adapter.js"; +import { hashPath } from "../../src/utils/fs.js"; +import { diffEffects, snapshot } from "../helpers/effects.js"; + +it("stale_merge_metadata_rejected_in_all_paths", async () => { + const root = await mkdtemp(join(tmpdir(), "invariant-i5-")); + try { + const sourcePath = join(root, "source.json"); + await writeFile(sourcePath, JSON.stringify({ managed: { value: "current" } })); + const adapter: AdapterConfig = { name: "synthetic", targets: { settings: { + local: targetMappingSchema.parse({ enabled: true, dest: "config.json", merge: "json-deep" }), + } } }; + const artifact: DesiredArtifact = { type: "settings", name: "synthetic", sourcePath, stagedPath: sourcePath, + relativePath: "source.json", kind: "file", hash: await hashPath(sourcePath), channel: "managed" }; + await applyCombinedInstallPlan(await createCombinedInstallPlan([artifact], adapter, root)); + const manifest = (await readInstallManifest(root, adapter.name))!; + manifest.entries[0]!.mergeRemoval = { managed: { value: "stale" } }; + // Source hash is unchanged; user-owned fields must survive both admission paths. + await writeFile(join(root, "config.json"), JSON.stringify({ managed: { value: "current" }, user: { keep: true } })); + const before = await snapshot(root); + const preview = await createCombinedInstallPlan([artifact], adapter, root, manifest); + expect(diffEffects(before, await snapshot(root))).toEqual([]); + const failure = await applyCombinedInstallPlan(preview).then(() => undefined, error => error); + expect(failure).toBeInstanceOf(Error); + expect(String(failure)).toMatch(/managed|contribution|merge/i); + // Expected: preview blocks the same stale contribution that apply rejects. + expect(preview.hasBlockingChanges).toBe(true); + } finally { await rm(root, { recursive: true, force: true }); } +}); diff --git a/test/invariants/i7-effects-containment.test.ts b/test/invariants/i7-effects-containment.test.ts new file mode 100644 index 00000000..927827f4 --- /dev/null +++ b/test/invariants/i7-effects-containment.test.ts @@ -0,0 +1,20 @@ +import { mkdtemp, rm } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { expect, it } from "vitest"; +import { refuseNewPinCollisions } from "../../src/lifecycle/pin-preflight.js"; +import { diffEffects, snapshot } from "../helpers/effects.js"; + +it("pin_provenance_and_feature_floor_enforced", async () => { + const root = await mkdtemp(join(tmpdir(), "invariant-i7-")); + try { + const before = await snapshot(root); + const warnings: string[] = []; + const failure = await refuseNewPinCollisions(root, { + packages: [{ name: "synthetic-pin", source: join(root, "unresolvable"), mode: "pinned" }], + }, message => warnings.push(message)).then(() => undefined, error => error); + expect(diffEffects(before, await snapshot(root))).toEqual([]); + // Expected: an unresolved approved pin refuses; warning and success are insufficient. + expect({ refused: failure instanceof Error, warnings }).toMatchObject({ refused: true }); + } finally { await rm(root, { recursive: true, force: true }); } +}); From 156ee7e3a7f685ac6fa906ffc88d45fb0f7d635f Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 12:42:14 +0000 Subject: [PATCH 02/19] test: use supported local git source syntax --- test/invariants/i2-no-loss.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/invariants/i2-no-loss.test.ts b/test/invariants/i2-no-loss.test.ts index 918772aa..2b295b41 100644 --- a/test/invariants/i2-no-loss.test.ts +++ b/test/invariants/i2-no-loss.test.ts @@ -10,7 +10,7 @@ it("read_missing_git_preserves_cache", async () => { try { const driver = new GitSourceDriver(); // Local nonexistent source: clone must fail without network access. - const resolved = await driver.resolve(`git+file://${join(root, "missing.git")}`, { cacheRoot: join(root, "cache") }); + const resolved = await driver.resolve(`git:file://${join(root, "missing.git")}`, { cacheRoot: join(root, "cache") }); await mkdir(resolved.resolvedPath, { recursive: true }); await writeFile(join(resolved.resolvedPath, "sentinel"), "preserve me"); const before = await snapshot(root); From 38ccbc060164d72b1eaf51cd914ac8eee7de6b5f Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 12:43:13 +0000 Subject: [PATCH 03/19] test: complete invariant fixture inputs --- test/invariants/i5-admission-parity.test.ts | 2 +- test/invariants/i7-effects-containment.test.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/test/invariants/i5-admission-parity.test.ts b/test/invariants/i5-admission-parity.test.ts index 78bad990..48011504 100644 --- a/test/invariants/i5-admission-parity.test.ts +++ b/test/invariants/i5-admission-parity.test.ts @@ -16,7 +16,7 @@ it("stale_merge_metadata_rejected_in_all_paths", async () => { local: targetMappingSchema.parse({ enabled: true, dest: "config.json", merge: "json-deep" }), } } }; const artifact: DesiredArtifact = { type: "settings", name: "synthetic", sourcePath, stagedPath: sourcePath, - relativePath: "source.json", kind: "file", hash: await hashPath(sourcePath), channel: "managed" }; + relativePath: "source.json", kind: "file", hash: await hashPath(sourcePath), channel: "managed", meta: {} }; await applyCombinedInstallPlan(await createCombinedInstallPlan([artifact], adapter, root)); const manifest = (await readInstallManifest(root, adapter.name))!; manifest.entries[0]!.mergeRemoval = { managed: { value: "stale" } }; diff --git a/test/invariants/i7-effects-containment.test.ts b/test/invariants/i7-effects-containment.test.ts index 927827f4..142d7d02 100644 --- a/test/invariants/i7-effects-containment.test.ts +++ b/test/invariants/i7-effects-containment.test.ts @@ -11,7 +11,7 @@ it("pin_provenance_and_feature_floor_enforced", async () => { const before = await snapshot(root); const warnings: string[] = []; const failure = await refuseNewPinCollisions(root, { - packages: [{ name: "synthetic-pin", source: join(root, "unresolvable"), mode: "pinned" }], + schemaVersion: 1, packages: [{ name: "synthetic-pin", source: join(root, "unresolvable"), mode: "pinned" }], }, message => warnings.push(message)).then(() => undefined, error => error); expect(diffEffects(before, await snapshot(root))).toEqual([]); // Expected: an unresolved approved pin refuses; warning and success are insufficient. From cca0024d3f2caacf7169436c2d0ec4a52887ca74 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 12:44:41 +0000 Subject: [PATCH 04/19] test: inventory Commander commands and reconcile runner test identities --- scripts/test-command-map.json | 23 ++++ scripts/test-command-matrix.mjs | 130 ++++++++++++++++++++ scripts/test-command-reporter.mjs | 28 +++++ test/invariants/i5-admission-parity.test.ts | 2 +- 4 files changed, 182 insertions(+), 1 deletion(-) create mode 100644 scripts/test-command-map.json create mode 100644 scripts/test-command-matrix.mjs create mode 100644 scripts/test-command-reporter.mjs diff --git a/scripts/test-command-map.json b/scripts/test-command-map.json new file mode 100644 index 00000000..8e093074 --- /dev/null +++ b/scripts/test-command-map.json @@ -0,0 +1,23 @@ +{ + "schemaVersion": 1, + "links": [ + { + "file": "test/cli-verb-redesign.test.ts", + "name": "CLI verb redesign > previews and applies Git cache pruning", + "commands": ["cache prune"], + "evidence": "Runs cache prune in preview and apply modes and checks retained cache entries." + }, + { + "file": "test/cli-verb-redesign.test.ts", + "name": "CLI verb redesign > drafts a registry publish submission from a GitHub URL without writing workspace state", + "commands": ["registry publish"], + "evidence": "Invokes registry publish and checks its draft and workspace effects." + }, + { + "file": "test/cli-verb-redesign.test.ts", + "name": "CLI verb redesign > doctor suggests the Copilot user companion skill install without writing files", + "commands": ["doctor"], + "evidence": "Invokes doctor and checks the suggested install and unchanged tree." + } + ] +} diff --git a/scripts/test-command-matrix.mjs b/scripts/test-command-matrix.mjs new file mode 100644 index 00000000..2bdd99e9 --- /dev/null +++ b/scripts/test-command-matrix.mjs @@ -0,0 +1,130 @@ +import { createHash } from "node:crypto"; +import { readFile, writeFile, mkdtemp, rm, readdir } from "node:fs/promises"; +import { join, relative, resolve } from "node:path"; +import { tmpdir } from "node:os"; +import { pathToFileURL } from "node:url"; +import { spawnSync, execFileSync } from "node:child_process"; +import { createRequire } from "node:module"; +import { build } from "esbuild"; + +const root = process.cwd(); +const require = createRequire(import.meta.url); +const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0; +const hash = bytes => createHash("sha256").update(bytes).digest("hex"); +const read = path => readFile(join(root, path), "utf8"); + +export function counts(tests) { + const pass = tests.filter(t => t.status === "passed").length; + const fail = tests.filter(t => t.status === "failed").length; + return { registered: tests.length, executed: pass + fail, pass, fail, + skipped: tests.filter(t => t.status === "skipped").length, + pending: tests.filter(t => t.status === "pending").length }; +} + +export function reconcile(commands, registered, results, links) { + const byId = new Map(registered.map(t => [t.id, t])); + const resultIds = new Set(results.map(t => t.id)); + if (byId.size !== registered.length || resultIds.size !== results.length + || byId.size !== resultIds.size || [...byId.keys()].some(id => !resultIds.has(id))) { + throw new Error("Registered and executed runner IDs do not reconcile"); + } + const attributed = new Map(commands.map(command => [command, new Set()])); + const assigned = new Set(); + const selectors = new Set(); + for (const link of links) { + const key = `${link.file}::${link.name}`; + if (selectors.has(key) || !link.evidence?.trim() || !link.commands.length) throw new Error(`Invalid mapping: ${key}`); + selectors.add(key); + const matches = registered.filter(t => t.file === link.file && t.name === link.name); + if (matches.length !== 1) throw new Error(`Mapping must match exactly one registered test: ${key} (${matches.length})`); + for (const command of link.commands) { + if (!attributed.has(command)) throw new Error(`Unknown parser command: ${command}`); + attributed.get(command).add(matches[0].id); + assigned.add(matches[0].id); + } + } + const rows = commands.map(command => { + const tests = results.filter(t => attributed.get(command).has(t.id)).sort((a,b) => compare(a.id,b.id)); + return { command, ...counts(tests), tests }; + }); + return { rows, uniqueAttributed: assigned.size, + unattributed: results.filter(t => !assigned.has(t.id)).sort((a,b) => compare(a.id,b.id)) }; +} + +async function parserCommands(scratch) { + const source = await read("src/cli/index.ts"); + const marker = "try {\n await main();"; + if (source.split(marker).length !== 2) throw new Error("CLI entry boundary changed; inspect inventory loader"); + // Load the actual Commander tree, replacing only the executable entrypoint. + const code = `${source.slice(0, source.indexOf(marker))}\nexport { program };\n`; + const output = join(scratch, "parser.mjs"); + await build({ stdin: { contents: code, resolveDir: join(root,"src/cli"), sourcefile: "index.ts", loader: "ts" }, + bundle: true, packages: "external", platform: "node", format: "esm", outfile: output, write: true }); + const { program } = await import(pathToFileURL(output)); + const commands = [program.name()]; + function visit(parent, prefix) { + for (const command of parent.commands) { + const path = [...prefix, command.name()]; + commands.push(path.join(" ")); + visit(command, path); + } + } + visit(program, []); + if (new Set(commands).size !== commands.length) throw new Error("Duplicate parser command path"); + return commands.sort(compare); +} + +async function sourceReceipt() { + // Hash exact source/test/script/config bytes; no absolute paths, timestamps or self-referential output. + const files = []; + async function visit(dir) { + for (const entry of (await readdir(join(root,dir), { withFileTypes: true })).sort((a,b) => compare(a.name,b.name))) { + const path = `${dir}/${entry.name}`; + if (entry.isDirectory()) await visit(path); + else if (entry.isFile() && !path.includes("/.command-matrix-")) files.push([path, hash(await readFile(join(root,path)))]); + } + } + for (const dir of ["src", "test", "scripts"]) await visit(dir); + for (const path of ["package.json", "pnpm-lock.yaml", "vitest.config.ts", "tsconfig.json"]) files.push([path,hash(await read(path))]); + return { inputDigest: hash(JSON.stringify(files.sort((a,b) => compare(a[0],b[0])))), + parserSha256: hash(await read("src/cli/index.ts")), + vitest: require("vitest/package.json").version, + node: process.versions.node }; +} + +async function main() { + // Inside the repository so external imports resolve the installed dependencies. + const scratch = await mkdtemp(join(root, "scripts/.command-matrix-")); + const reportRoot = await mkdtemp(join(tmpdir(), "command-matrix-")); + try { + const commands = await parserCommands(scratch); + const report = join(reportRoot,"runner.json"); + const json = join(reportRoot,"vitest.json"); + const runner = spawnSync(process.execPath, [require.resolve("vitest/vitest.mjs"), "run", + "--maxWorkers=2", "--reporter=json", "--reporter=./scripts/test-command-reporter.mjs", `--outputFile=${json}`], { + cwd: root, env: { ...process.env, COMMAND_MATRIX_REPORT: report }, encoding: "utf8", maxBuffer: 40 * 1024 * 1024, + }); + if (runner.error) throw runner.error; + const observed = JSON.parse(await readFile(report,"utf8")); + const official = JSON.parse(await readFile(json,"utf8")); + const officialTests = official.testResults.flatMap(file => file.assertionResults); + if (officialTests.length !== observed.tests.length) throw new Error("JSON reporter test count mismatch"); + const mapping = JSON.parse(await read("scripts/test-command-map.json")); + if (mapping.schemaVersion !== 1) throw new Error("Unsupported mapping schema"); + const matrix = reconcile(commands, observed.registered, observed.tests, mapping.links); + const output = { schemaVersion: 1, receipt: await sourceReceipt(), + commandCount: commands.length, zeroTestCommands: matrix.rows.filter(row => !row.registered).map(row => row.command), + totals: counts(observed.tests), uniqueAttributed: matrix.uniqueAttributed, + runnerExitCode: runner.status, moduleErrors: observed.moduleErrors, unhandledErrors: observed.unhandledErrors, + commands: matrix.rows, unattributed: matrix.unattributed }; + const destination = resolve(process.argv[2] ?? "docs/test-command-matrix.json"); + await writeFile(destination, `${JSON.stringify(output,null,2)}\n`); + console.log(JSON.stringify({ commandCount: output.commandCount, zeroTestCommands: output.zeroTestCommands.length, + ...output.totals, uniqueAttributed: output.uniqueAttributed, output: relative(root,destination) })); + if (runner.status !== 0 || observed.moduleErrors.length || observed.unhandledErrors) process.exitCode = 1; + } finally { + await rm(scratch, { recursive: true, force: true }); + await rm(reportRoot, { recursive: true, force: true }); + } +} +if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) await main(); diff --git a/scripts/test-command-reporter.mjs b/scripts/test-command-reporter.mjs new file mode 100644 index 00000000..632e4ffd --- /dev/null +++ b/scripts/test-command-reporter.mjs @@ -0,0 +1,28 @@ +import { writeFileSync } from "node:fs"; + +// Uses runner-owned IDs, including parameter expansion, rather than source-text guesses. +export default class CommandMatrixReporter { + registered = new Map(); + onTestModuleCollected(module) { + for (const test of module.children.allTests()) { + if (this.registered.has(test.id)) throw new Error(`Duplicate runner test ID: ${test.id}`); + this.registered.set(test.id, { + id: test.id, file: module.relativeModuleId, name: test.fullName, + expectedFailure: test.options.fails === true, + }); + } + } + onTestRunEnd(modules, errors, reason) { + const tests = []; + for (const module of modules) for (const test of module.children.allTests()) { + const registered = this.registered.get(test.id); + if (!registered) throw new Error(`Unregistered runner test: ${test.id}`); + tests.push({ ...registered, status: test.result().state }); + } + writeFileSync(process.env.COMMAND_MATRIX_REPORT, JSON.stringify({ + registered: [...this.registered.values()], tests, reason, + moduleErrors: modules.filter(module => !module.ok()).map(module => module.relativeModuleId), + unhandledErrors: errors.length, + })); + } +} diff --git a/test/invariants/i5-admission-parity.test.ts b/test/invariants/i5-admission-parity.test.ts index 48011504..55c6c235 100644 --- a/test/invariants/i5-admission-parity.test.ts +++ b/test/invariants/i5-admission-parity.test.ts @@ -16,7 +16,7 @@ it("stale_merge_metadata_rejected_in_all_paths", async () => { local: targetMappingSchema.parse({ enabled: true, dest: "config.json", merge: "json-deep" }), } } }; const artifact: DesiredArtifact = { type: "settings", name: "synthetic", sourcePath, stagedPath: sourcePath, - relativePath: "source.json", kind: "file", hash: await hashPath(sourcePath), channel: "managed", meta: {} }; + relativePath: "source.json", kind: "file", hash: await hashPath(sourcePath), channel: "managed", meta: { dependencyRole: "root" } }; await applyCombinedInstallPlan(await createCombinedInstallPlan([artifact], adapter, root)); const manifest = (await readInstallManifest(root, adapter.name))!; manifest.entries[0]!.mergeRemoval = { managed: { value: "stale" } }; From 50f452001c2e3e5f9f6125e25ef4f7388a87888d Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 12:46:14 +0000 Subject: [PATCH 05/19] test: verify effect snapshots and command attribution accounting --- docs/testing-invariants.md | 21 +++++++++++++ scripts/test-command-matrix.mjs | 14 +++------ test/command-matrix.test.ts | 17 ++++++++++ test/effects-harness.test.ts | 35 +++++++++++++++++++++ test/invariants/i5-admission-parity.test.ts | 2 +- 5 files changed, 78 insertions(+), 11 deletions(-) create mode 100644 docs/testing-invariants.md create mode 100644 test/command-matrix.test.ts create mode 100644 test/effects-harness.test.ts diff --git a/docs/testing-invariants.md b/docs/testing-invariants.md new file mode 100644 index 00000000..464ac1df --- /dev/null +++ b/docs/testing-invariants.md @@ -0,0 +1,21 @@ +# Invariant baseline and command attribution + +Run `node scripts/test-command-matrix.mjs [output.json]` from the repository root after installing dependencies. The script runs the entire Vitest suite; failures remain in the output and yield a nonzero exit. It loads the actual Commander tree with only its executable entrypoint removed, including root, groups and hidden commands. No command handler runs during inventory. + +`scripts/test-command-map.json` is deliberately conservative: every link names exactly one runner-registered file/full-name pair and documents why that test covers the command. Imports and shared files do not imply command coverage. Add audited links as coverage is established; an unattributed test is not evidence of absent behavior. Unknown commands, missing or ambiguous cases, duplicate IDs and registration/result mismatches refuse generation. Parameterized cases remain individual runner IDs. Per-command counts overlap; only the union of IDs is a suite total. IDs are Vitest IDs, stable for the same runner/project/module/test order. The separate JSON reporter reconciles the overall count. + +The report records input-byte and parser hashes, runner and Node versions. It excludes timing, absolute paths and stack traces. Unattributed tests are explicitly listed to reconcile the full runner inventory. `it.fails` outcomes count as runner passes and carry `expectedFailure: true`; this is not proof that the invariant holds. Skipped and pending outcomes are separate from executed cases. Generated reports are observations of one environment and are not committed as a portable status baseline. + +## Effects harness + +`test/helpers/effects.ts` records file bytes in base64, permission bits, directories and symlink targets without following links. Explicit manifest paths record complete parsed claims as well as original bytes. With `git: true`, the snapshot also records the staged index, refs and symbolic HEAD; the filesystem tree includes raw Git metadata. Locks under the fixture root are included. No timestamps are recorded. There are no default path exclusions. A caller may exclude only an exact file or symlink path with a nonempty reason; directories are always traversed and manifest claims cannot be excluded. Compare snapshots with `diffEffects`; unknown changed paths remain visible. This is an isolated filesystem observer, not a syscall/network/process tracer. + +## Expected failures + +The invariant tests use synthetic fixtures and no live targets. Each assertion is first reproduced as an ordinary failing test, then marked `it.fails`. A product fix must remove that marker in the same change: an unexpected pass fails CI. Do not replace the marker with skip or todo. + +| Invariant | Case | Observed defect | +| --- | --- | --- | +| I2 | `read_missing_git_preserves_cache` | Fetch removes an existing incomplete cache directory and its sentinel before a failing local clone. | +| I5 | `stale_merge_metadata_rejected_in_all_paths` | Preview accepts unchanged source with stale contribution metadata while apply rejects the contribution. | +| I7 | `pin_provenance_and_feature_floor_enforced` | Unresolvable local pin emits a warning and returns successfully. This case covers unreachable pins only. | diff --git a/scripts/test-command-matrix.mjs b/scripts/test-command-matrix.mjs index 2bdd99e9..afcb39ed 100644 --- a/scripts/test-command-matrix.mjs +++ b/scripts/test-command-matrix.mjs @@ -76,16 +76,10 @@ async function parserCommands(scratch) { async function sourceReceipt() { // Hash exact source/test/script/config bytes; no absolute paths, timestamps or self-referential output. - const files = []; - async function visit(dir) { - for (const entry of (await readdir(join(root,dir), { withFileTypes: true })).sort((a,b) => compare(a.name,b.name))) { - const path = `${dir}/${entry.name}`; - if (entry.isDirectory()) await visit(path); - else if (entry.isFile() && !path.includes("/.command-matrix-")) files.push([path, hash(await readFile(join(root,path)))]); - } - } - for (const dir of ["src", "test", "scripts"]) await visit(dir); - for (const path of ["package.json", "pnpm-lock.yaml", "vitest.config.ts", "tsconfig.json"]) files.push([path,hash(await read(path))]); + const tracked = execFileSync("git", ["ls-files", "-z"], { cwd: root, encoding: "utf8" }).split("\0").filter(Boolean); + const paths = tracked.filter(path => /^(src|test|scripts)\//.test(path) + || ["package.json", "pnpm-lock.yaml", "vitest.config.ts", "tsconfig.json"].includes(path)); + const files = await Promise.all(paths.sort(compare).map(async path => [path, hash(await readFile(join(root,path)))])); return { inputDigest: hash(JSON.stringify(files.sort((a,b) => compare(a[0],b[0])))), parserSha256: hash(await read("src/cli/index.ts")), vitest: require("vitest/package.json").version, diff --git a/test/command-matrix.test.ts b/test/command-matrix.test.ts new file mode 100644 index 00000000..99b9d9b8 --- /dev/null +++ b/test/command-matrix.test.ts @@ -0,0 +1,17 @@ +import { expect, it } from "vitest"; +// @ts-expect-error The CLI support script is native ESM JavaScript. +import { reconcile, counts } from "../scripts/test-command-matrix.mjs"; + +it("reconciles shared command attribution without double-counting unique runner IDs", () => { + const registered = [{ id: "a", file: "case.ts", name: "parameter 1" }, { id: "b", file: "case.ts", name: "parameter 2" }]; + const results = registered.map(test => ({ ...test, status: "passed" })); + const matrix = reconcile(["one", "two", "zero"], registered, results, + [{ file: "case.ts", name: "parameter 1", commands: ["one", "two"], evidence: "shared fixture" }]); + expect(matrix.uniqueAttributed).toBe(1); + expect(matrix.rows.map((row: { registered: number }) => row.registered)).toEqual([1,1,0]); + expect(matrix.unattributed.map((test: { id: string }) => test.id)).toEqual(["b"]); + expect(() => reconcile(["one"], registered, [results[0]], [])).toThrow(/reconcile/); + expect(() => reconcile(["one"], registered, results, [{ file: "case.ts", name: "missing", commands: ["one"], evidence: "fixture" }])).toThrow(/exactly one/); + expect(() => reconcile(["one"], registered, results, [{ file: "case.ts", name: "parameter 1", commands: ["unknown"], evidence: "fixture" }])).toThrow(/Unknown/); + expect(counts([{ status: "passed" }, { status: "failed" }, { status: "skipped" }, { status: "pending" }])).toEqual({ registered: 4, executed: 2, pass: 1, fail: 1, skipped: 1, pending: 1 }); +}); diff --git a/test/effects-harness.test.ts b/test/effects-harness.test.ts new file mode 100644 index 00000000..d8f8582a --- /dev/null +++ b/test/effects-harness.test.ts @@ -0,0 +1,35 @@ +import { execFileSync } from "node:child_process"; +import { chmod, mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { expect, it } from "vitest"; +import { diffEffects, snapshot } from "./helpers/effects.js"; + +it("detects bytes, modes, symlinks, claims, index and refs without following links", async () => { + const root = await mkdtemp(join(tmpdir(), "effects-harness-")); + try { + const git = (...args: string[]) => execFileSync("git", ["-C", root, ...args]); + git("init", "-b", "main"); + git("config", "user.name", "Synthetic"); + git("config", "user.email", "synthetic@example.invalid"); + await writeFile(join(root, "file"), Buffer.from([0,255,1])); + await writeFile(join(root, "manifest.json"), JSON.stringify({ entries: [{ owner: "alpha" }] })); + await symlink("file", join(root,"link")); + git("add", "file"); git("commit", "-m", "fixture"); + const policy = { manifests: ["manifest.json"], git: true }; + const before = await snapshot(root, policy); + expect(diffEffects(before, await snapshot(root,policy))).toEqual([]); + await writeFile(join(root,"file"), Buffer.from([0,255,2])); + await chmod(join(root,"file"), 0o755); + await rm(join(root,"link")); await symlink("missing",join(root,"link")); + await writeFile(join(root,"manifest.json"), JSON.stringify({ entries: [{ owner: "beta" }] })); + git("add", "file"); git("branch", "other"); + const changes = diffEffects(before, await snapshot(root,policy)); + expect(changes).toEqual(expect.arrayContaining(["tree:file", "tree:link", "claims:manifest.json", "git:index", "git:refs"])); + await expect(snapshot(root, { exclude: { "**": "invalid" } })).rejects.toThrow(/exact/); + await expect(snapshot(root, { exclude: { "file": "" } })).rejects.toThrow(/reason/); + const excluded = { exclude: { "file": "This fixture explicitly ignores the mutable file payload." } }; + expect((await snapshot(root,excluded)).tree.file).toBeUndefined(); + await expect(snapshot(root, { manifests: ["manifest.json"], exclude: { "manifest.json": "invalid claim exclusion" } })).rejects.toThrow(/claims/); + } finally { await rm(root, { recursive: true, force: true }); } +}); diff --git a/test/invariants/i5-admission-parity.test.ts b/test/invariants/i5-admission-parity.test.ts index 55c6c235..51762835 100644 --- a/test/invariants/i5-admission-parity.test.ts +++ b/test/invariants/i5-admission-parity.test.ts @@ -16,7 +16,7 @@ it("stale_merge_metadata_rejected_in_all_paths", async () => { local: targetMappingSchema.parse({ enabled: true, dest: "config.json", merge: "json-deep" }), } } }; const artifact: DesiredArtifact = { type: "settings", name: "synthetic", sourcePath, stagedPath: sourcePath, - relativePath: "source.json", kind: "file", hash: await hashPath(sourcePath), channel: "managed", meta: { dependencyRole: "root" } }; + relativePath: "source.json", kind: "file", hash: await hashPath(sourcePath), channel: "managed", meta: { dependencyRole: "root", owners: ["synthetic"], logicalSelector: "settings/synthetic" } }; await applyCombinedInstallPlan(await createCombinedInstallPlan([artifact], adapter, root)); const manifest = (await readInstallManifest(root, adapter.name))!; manifest.entries[0]!.mergeRemoval = { managed: { value: "stale" } }; From 6eb5abc1d95f70a56091ed55bc20699836b2b86b Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 12:47:24 +0000 Subject: [PATCH 06/19] test: retain verified invariant failures and publish CI command matrix --- .github/workflows/ci.yml | 9 ++++++++- scripts/test-command-matrix.mjs | 4 +++- test/invariants/i2-no-loss.test.ts | 2 +- test/invariants/i5-admission-parity.test.ts | 2 +- test/invariants/i7-effects-containment.test.ts | 2 +- 5 files changed, 14 insertions(+), 5 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a40ca332..703d09ee 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -70,4 +70,11 @@ jobs: - name: Test env: SYNCWHEEL_SOURCE_ROOT: ${{ github.workspace }}/syncwheel - run: pnpm test + run: node scripts/test-command-matrix.mjs "${{ runner.temp }}/test-command-matrix.json" + + - name: Upload command test matrix + if: always() + uses: actions/upload-artifact@v4 + with: + name: test-command-matrix + path: ${{ runner.temp }}/test-command-matrix.json diff --git a/scripts/test-command-matrix.mjs b/scripts/test-command-matrix.mjs index afcb39ed..a31569b8 100644 --- a/scripts/test-command-matrix.mjs +++ b/scripts/test-command-matrix.mjs @@ -5,10 +5,12 @@ import { tmpdir } from "node:os"; import { pathToFileURL } from "node:url"; import { spawnSync, execFileSync } from "node:child_process"; import { createRequire } from "node:module"; -import { build } from "esbuild"; + const root = process.cwd(); const require = createRequire(import.meta.url); +// Use the bundler shipped with the pinned, direct tsup development dependency. +const { build } = createRequire(require.resolve("tsup/package.json"))("esbuild"); const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0; const hash = bytes => createHash("sha256").update(bytes).digest("hex"); const read = path => readFile(join(root, path), "utf8"); diff --git a/test/invariants/i2-no-loss.test.ts b/test/invariants/i2-no-loss.test.ts index 2b295b41..7f579679 100644 --- a/test/invariants/i2-no-loss.test.ts +++ b/test/invariants/i2-no-loss.test.ts @@ -5,7 +5,7 @@ import { expect, it } from "vitest"; import { GitSourceDriver } from "../../src/source/git.js"; import { diffEffects, snapshot } from "../helpers/effects.js"; -it("read_missing_git_preserves_cache", async () => { +it.fails("read_missing_git_preserves_cache", async () => { const root = await mkdtemp(join(tmpdir(), "invariant-i2-")); try { const driver = new GitSourceDriver(); diff --git a/test/invariants/i5-admission-parity.test.ts b/test/invariants/i5-admission-parity.test.ts index 51762835..37c38922 100644 --- a/test/invariants/i5-admission-parity.test.ts +++ b/test/invariants/i5-admission-parity.test.ts @@ -7,7 +7,7 @@ import { targetMappingSchema, type AdapterConfig } from "../../src/model/adapter import { hashPath } from "../../src/utils/fs.js"; import { diffEffects, snapshot } from "../helpers/effects.js"; -it("stale_merge_metadata_rejected_in_all_paths", async () => { +it.fails("stale_merge_metadata_rejected_in_all_paths", async () => { const root = await mkdtemp(join(tmpdir(), "invariant-i5-")); try { const sourcePath = join(root, "source.json"); diff --git a/test/invariants/i7-effects-containment.test.ts b/test/invariants/i7-effects-containment.test.ts index 142d7d02..7a9919fb 100644 --- a/test/invariants/i7-effects-containment.test.ts +++ b/test/invariants/i7-effects-containment.test.ts @@ -5,7 +5,7 @@ import { expect, it } from "vitest"; import { refuseNewPinCollisions } from "../../src/lifecycle/pin-preflight.js"; import { diffEffects, snapshot } from "../helpers/effects.js"; -it("pin_provenance_and_feature_floor_enforced", async () => { +it.fails("pin_provenance_and_feature_floor_enforced", async () => { const root = await mkdtemp(join(tmpdir(), "invariant-i7-")); try { const before = await snapshot(root); From f31d029a681ebad165e18a092550ce107e1bf1a1 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 12:49:05 +0000 Subject: [PATCH 07/19] test: resolve runner executable through its exported package metadata --- scripts/test-command-matrix.mjs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/test-command-matrix.mjs b/scripts/test-command-matrix.mjs index a31569b8..1e173d27 100644 --- a/scripts/test-command-matrix.mjs +++ b/scripts/test-command-matrix.mjs @@ -1,6 +1,6 @@ import { createHash } from "node:crypto"; import { readFile, writeFile, mkdtemp, rm, readdir } from "node:fs/promises"; -import { join, relative, resolve } from "node:path"; +import { dirname, join, relative, resolve } from "node:path"; import { tmpdir } from "node:os"; import { pathToFileURL } from "node:url"; import { spawnSync, execFileSync } from "node:child_process"; @@ -96,7 +96,7 @@ async function main() { const commands = await parserCommands(scratch); const report = join(reportRoot,"runner.json"); const json = join(reportRoot,"vitest.json"); - const runner = spawnSync(process.execPath, [require.resolve("vitest/vitest.mjs"), "run", + const runner = spawnSync(process.execPath, [join(dirname(require.resolve("vitest/package.json")), "vitest.mjs"), "run", "--maxWorkers=2", "--reporter=json", "--reporter=./scripts/test-command-reporter.mjs", `--outputFile=${json}`], { cwd: root, env: { ...process.env, COMMAND_MATRIX_REPORT: report }, encoding: "utf8", maxBuffer: 40 * 1024 * 1024, }); From e7ddfecc1319cb1151d9d4d510e16244775cec7c Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 12:50:25 +0000 Subject: [PATCH 08/19] test: require stale admission refusal before additional effects --- test/invariants/i5-admission-parity.test.ts | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/test/invariants/i5-admission-parity.test.ts b/test/invariants/i5-admission-parity.test.ts index 37c38922..b3f446b7 100644 --- a/test/invariants/i5-admission-parity.test.ts +++ b/test/invariants/i5-admission-parity.test.ts @@ -27,8 +27,11 @@ it.fails("stale_merge_metadata_rejected_in_all_paths", async () => { expect(diffEffects(before, await snapshot(root))).toEqual([]); const failure = await applyCombinedInstallPlan(preview).then(() => undefined, error => error); expect(failure).toBeInstanceOf(Error); - expect(String(failure)).toMatch(/managed|contribution|merge/i); // Expected: preview blocks the same stale contribution that apply rejects. expect(preview.hasBlockingChanges).toBe(true); + expect(preview.operations).toEqual(expect.arrayContaining([expect.objectContaining({ + action: "conflict", blockedReason: expect.stringMatching(/contribution|merge/i), + })])); + expect(diffEffects(before, await snapshot(root))).toEqual([]); } finally { await rm(root, { recursive: true, force: true }); } }); From adb319dfea54504e1281396e57eaeb3e3b239a55 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 12:51:49 +0000 Subject: [PATCH 09/19] test: include root permissions and raw Git index in effect snapshots --- docs/testing-invariants.md | 2 +- test/helpers/effects.ts | 10 ++++++---- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/testing-invariants.md b/docs/testing-invariants.md index 464ac1df..553e67e2 100644 --- a/docs/testing-invariants.md +++ b/docs/testing-invariants.md @@ -8,7 +8,7 @@ The report records input-byte and parser hashes, runner and Node versions. It ex ## Effects harness -`test/helpers/effects.ts` records file bytes in base64, permission bits, directories and symlink targets without following links. Explicit manifest paths record complete parsed claims as well as original bytes. With `git: true`, the snapshot also records the staged index, refs and symbolic HEAD; the filesystem tree includes raw Git metadata. Locks under the fixture root are included. No timestamps are recorded. There are no default path exclusions. A caller may exclude only an exact file or symlink path with a nonempty reason; directories are always traversed and manifest claims cannot be excluded. Compare snapshots with `diffEffects`; unknown changed paths remain visible. This is an isolated filesystem observer, not a syscall/network/process tracer. +`test/helpers/effects.ts` records file bytes in base64, permission bits, directories and symlink targets without following links. Explicit manifest paths record complete parsed claims as well as original bytes. With `git: true`, the snapshot also records the staged index (semantic entries and raw bytes), refs and symbolic HEAD; the filesystem tree includes raw Git metadata. Locks under the fixture root are included. Filesystem atime, mtime, ctime and birthtime are not recorded; all listed content and permission fields are compared exactly. There are no default path exclusions. A caller may exclude only an exact file or symlink path with a nonempty reason; directories are always traversed and manifest claims cannot be excluded. Compare snapshots with `diffEffects`; unknown changed paths remain visible. This is an isolated filesystem observer, not a syscall/network/process tracer. ## Expected failures diff --git a/test/helpers/effects.ts b/test/helpers/effects.ts index 131764b4..2140d645 100644 --- a/test/helpers/effects.ts +++ b/test/helpers/effects.ts @@ -1,11 +1,11 @@ import { lstat, readdir, readFile, readlink } from "node:fs/promises"; -import { join } from "node:path"; +import { isAbsolute, join, resolve } from "node:path"; import { execFileSync } from "node:child_process"; export interface EffectSnapshot { tree: Record; claims: Record; - git?: { index: string; refs: string; head: string }; + git?: { index: string; refs: string; head: string; indexBytes: string }; } export interface EffectPolicy { // Exact relative paths only, each with a fixture-specific reason. No globs or prefixes. @@ -24,7 +24,7 @@ export async function snapshot(root: string, policy: EffectPolicy = {}): Promise const path = join(root, relative); const stat = await lstat(path); if (stat.isDirectory()) { - if (relative) result.tree[relative] = { kind: "directory", mode: stat.mode & 0o7777 }; + result.tree[relative || "."] = { kind: "directory", mode: stat.mode & 0o7777 }; for (const name of (await readdir(path)).sort()) await visit(relative ? `${relative}/${name}` : name); } else if (!Object.hasOwn(policy.exclude ?? {}, relative)) { result.tree[relative] = stat.isSymbolicLink() @@ -38,7 +38,9 @@ export async function snapshot(root: string, policy: EffectPolicy = {}): Promise for (const path of policy.manifests ?? []) result.claims[path] = JSON.parse(await readFile(join(root, path), "utf8")); if (policy.git) { const git = (...args: string[]) => execFileSync("git", ["-C", root, ...args], { encoding: "utf8" }); - result.git = { index: git("ls-files", "--stage", "-z"), refs: git("show-ref", "--head"), head: git("symbolic-ref", "-q", "HEAD") }; + const indexPath = git("rev-parse", "--git-path", "index").trim(); + const indexBytes = (await readFile(isAbsolute(indexPath) ? indexPath : resolve(root,indexPath))).toString("base64"); + result.git = { indexBytes, index: git("ls-files", "--stage", "-z"), refs: git("show-ref", "--head"), head: git("symbolic-ref", "-q", "HEAD") }; } return result; } From 3429cb12619b775caf10aa61f044f561e79ce5db Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 12:53:02 +0000 Subject: [PATCH 10/19] test: run the declared package test command for matrix observations --- scripts/test-command-matrix.mjs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/test-command-matrix.mjs b/scripts/test-command-matrix.mjs index 1e173d27..573da2e4 100644 --- a/scripts/test-command-matrix.mjs +++ b/scripts/test-command-matrix.mjs @@ -1,6 +1,6 @@ import { createHash } from "node:crypto"; import { readFile, writeFile, mkdtemp, rm, readdir } from "node:fs/promises"; -import { dirname, join, relative, resolve } from "node:path"; +import { join, relative, resolve } from "node:path"; import { tmpdir } from "node:os"; import { pathToFileURL } from "node:url"; import { spawnSync, execFileSync } from "node:child_process"; @@ -96,7 +96,7 @@ async function main() { const commands = await parserCommands(scratch); const report = join(reportRoot,"runner.json"); const json = join(reportRoot,"vitest.json"); - const runner = spawnSync(process.execPath, [join(dirname(require.resolve("vitest/package.json")), "vitest.mjs"), "run", + const runner = spawnSync("pnpm", ["test", "--maxWorkers=2", "--reporter=json", "--reporter=./scripts/test-command-reporter.mjs", `--outputFile=${json}`], { cwd: root, env: { ...process.env, COMMAND_MATRIX_REPORT: report }, encoding: "utf8", maxBuffer: 40 * 1024 * 1024, }); From 71101a9b4f92ffad1ee817fe50842506dba202e1 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 13:10:52 +0000 Subject: [PATCH 11/19] test: correct invariant scope and expose matrix runner failures --- docs/testing-invariants.md | 11 ++--- scripts/test-command-matrix.mjs | 37 ++++++++++------ test/command-matrix.test.ts | 43 ++++++++++++++++++- test/invariants/i2-no-loss.test.ts | 24 ++++++++--- test/invariants/i5-admission-parity.test.ts | 30 +++++++++---- .../invariants/i7-effects-containment.test.ts | 20 --------- 6 files changed, 112 insertions(+), 53 deletions(-) delete mode 100644 test/invariants/i7-effects-containment.test.ts diff --git a/docs/testing-invariants.md b/docs/testing-invariants.md index 553e67e2..e8b109dd 100644 --- a/docs/testing-invariants.md +++ b/docs/testing-invariants.md @@ -1,10 +1,10 @@ # Invariant baseline and command attribution -Run `node scripts/test-command-matrix.mjs [output.json]` from the repository root after installing dependencies. The script runs the entire Vitest suite; failures remain in the output and yield a nonzero exit. It loads the actual Commander tree with only its executable entrypoint removed, including root, groups and hidden commands. No command handler runs during inventory. +Run `node scripts/test-command-matrix.mjs [output.json]` from the repository root after installing dependencies. Without an output argument, the report is saved under the operating system temporary directory. Parser scratch files also live there. The script runs the entire Vitest suite with the default reporter streamed to stdout/stderr; failures remain in the output and yield a nonzero exit. It loads the actual Commander tree with only its executable entrypoint removed, including root, groups and hidden commands. No command handler runs during inventory. -`scripts/test-command-map.json` is deliberately conservative: every link names exactly one runner-registered file/full-name pair and documents why that test covers the command. Imports and shared files do not imply command coverage. Add audited links as coverage is established; an unattributed test is not evidence of absent behavior. Unknown commands, missing or ambiguous cases, duplicate IDs and registration/result mismatches refuse generation. Parameterized cases remain individual runner IDs. Per-command counts overlap; only the union of IDs is a suite total. IDs are Vitest IDs, stable for the same runner/project/module/test order. The separate JSON reporter reconciles the overall count. +`scripts/test-command-map.json` currently links only three commands and is deliberately conservative: every link names exactly one runner-registered file/full-name pair and documents why that test covers the command. Imports and shared files do not imply command coverage. Add audited links as coverage is established; an unattributed test is not evidence of absent behavior. Unknown commands, missing or ambiguous cases, duplicate IDs and registration/result mismatches refuse generation. Parameterized cases remain individual runner IDs. Per-command counts overlap; only the union of IDs is a suite total. IDs are Vitest IDs, stable for the same runner/project/module/test order. The separate JSON reporter reconciles the overall count. -The report records input-byte and parser hashes, runner and Node versions. It excludes timing, absolute paths and stack traces. Unattributed tests are explicitly listed to reconcile the full runner inventory. `it.fails` outcomes count as runner passes and carry `expectedFailure: true`; this is not proof that the invariant holds. Skipped and pending outcomes are separate from executed cases. Generated reports are observations of one environment and are not committed as a portable status baseline. +The report records input-byte and parser hashes, runner and Node versions. It excludes timing, absolute paths and stack traces. `unattributedCommands` lists commands with no declared test links; this is not a claim that their behavior is untested. Unattributed tests are explicitly listed to reconcile the full runner inventory. `it.fails` outcomes count as runner passes and carry `expectedFailure: true`; this is not proof that the invariant holds. Skipped and pending outcomes are separate from executed cases. Generated reports are observations of one environment and are not committed as a portable status baseline. ## Effects harness @@ -12,10 +12,11 @@ The report records input-byte and parser hashes, runner and Node versions. It ex ## Expected failures -The invariant tests use synthetic fixtures and no live targets. Each assertion is first reproduced as an ordinary failing test, then marked `it.fails`. A product fix must remove that marker in the same change: an unexpected pass fails CI. Do not replace the marker with skip or todo. +The invariant tests use synthetic fixtures and no live targets. Each expected-failure test has an adjacent ordinary test that checks the exact current defect, so a broken setup cannot masquerade as an expected failure. A product fix must remove that marker in the same change: an unexpected pass fails CI. Do not replace the marker with skip or todo. | Invariant | Case | Observed defect | | --- | --- | --- | | I2 | `read_missing_git_preserves_cache` | Fetch removes an existing incomplete cache directory and its sentinel before a failing local clone. | | I5 | `stale_merge_metadata_rejected_in_all_paths` | Preview accepts unchanged source with stale contribution metadata while apply rejects the contribution. | -| I7 | `pin_provenance_and_feature_floor_enforced` | Unresolvable local pin emits a warning and returns successfully. This case covers unreachable pins only. | + +An unreachable source during pin preflight produces a warning by design, not a defect: it does not prove a new artifact collision. The existing pin-preflight tests retain that intended behavior. diff --git a/scripts/test-command-matrix.mjs b/scripts/test-command-matrix.mjs index 573da2e4..16f21e11 100644 --- a/scripts/test-command-matrix.mjs +++ b/scripts/test-command-matrix.mjs @@ -1,5 +1,5 @@ import { createHash } from "node:crypto"; -import { readFile, writeFile, mkdtemp, rm, readdir } from "node:fs/promises"; +import { readFile, writeFile, mkdtemp, rm } from "node:fs/promises"; import { join, relative, resolve } from "node:path"; import { tmpdir } from "node:os"; import { pathToFileURL } from "node:url"; @@ -35,7 +35,7 @@ export function reconcile(commands, registered, results, links) { const selectors = new Set(); for (const link of links) { const key = `${link.file}::${link.name}`; - if (selectors.has(key) || !link.evidence?.trim() || !link.commands.length) throw new Error(`Invalid mapping: ${key}`); + if (selectors.has(key) || !link.evidence?.trim() || !Array.isArray(link.commands) || !link.commands.length) throw new Error(`Invalid mapping: ${key}`); selectors.add(key); const matches = registered.filter(t => t.file === link.file && t.name === link.name); if (matches.length !== 1) throw new Error(`Mapping must match exactly one registered test: ${key} (${matches.length})`); @@ -53,7 +53,7 @@ export function reconcile(commands, registered, results, links) { unattributed: results.filter(t => !assigned.has(t.id)).sort((a,b) => compare(a.id,b.id)) }; } -async function parserCommands(scratch) { +export async function parserCommands(scratch) { const source = await read("src/cli/index.ts"); const marker = "try {\n await main();"; if (source.split(marker).length !== 2) throw new Error("CLI entry boundary changed; inspect inventory loader"); @@ -61,7 +61,11 @@ async function parserCommands(scratch) { const code = `${source.slice(0, source.indexOf(marker))}\nexport { program };\n`; const output = join(scratch, "parser.mjs"); await build({ stdin: { contents: code, resolveDir: join(root,"src/cli"), sourcefile: "index.ts", loader: "ts" }, - bundle: true, packages: "external", platform: "node", format: "esm", outfile: output, write: true }); + bundle: true, plugins: [{ name: "resolve-temporary-parser-imports", setup(context) { + context.onResolve({ filter: /^[^./]/ }, args => ({ + path: args.path.startsWith("node:") ? args.path : import.meta.resolve(args.path), external: true, + })); + } }], platform: "node", format: "esm", outfile: output, write: true }); const { program } = await import(pathToFileURL(output)); const commands = [program.name()]; function visit(parent, prefix) { @@ -88,18 +92,25 @@ async function sourceReceipt() { node: process.versions.node }; } +export function runTests(report, json) { + return spawnSync("pnpm", ["test", "--maxWorkers=2", "--reporter=default", "--reporter=json", + "--reporter=./scripts/test-command-reporter.mjs", `--outputFile=${json}`], { + cwd: root, env: { ...process.env, COMMAND_MATRIX_REPORT: report }, stdio: "inherit", + }); +} + +export async function matrixDestination(path) { + return path ? resolve(path) : join(await mkdtemp(join(tmpdir(), "command-matrix-output-")), "matrix.json"); +} + async function main() { - // Inside the repository so external imports resolve the installed dependencies. - const scratch = await mkdtemp(join(root, "scripts/.command-matrix-")); + const scratch = await mkdtemp(join(tmpdir(), "command-matrix-parser-")); const reportRoot = await mkdtemp(join(tmpdir(), "command-matrix-")); try { const commands = await parserCommands(scratch); const report = join(reportRoot,"runner.json"); const json = join(reportRoot,"vitest.json"); - const runner = spawnSync("pnpm", ["test", - "--maxWorkers=2", "--reporter=json", "--reporter=./scripts/test-command-reporter.mjs", `--outputFile=${json}`], { - cwd: root, env: { ...process.env, COMMAND_MATRIX_REPORT: report }, encoding: "utf8", maxBuffer: 40 * 1024 * 1024, - }); + const runner = runTests(report, json); if (runner.error) throw runner.error; const observed = JSON.parse(await readFile(report,"utf8")); const official = JSON.parse(await readFile(json,"utf8")); @@ -109,13 +120,13 @@ async function main() { if (mapping.schemaVersion !== 1) throw new Error("Unsupported mapping schema"); const matrix = reconcile(commands, observed.registered, observed.tests, mapping.links); const output = { schemaVersion: 1, receipt: await sourceReceipt(), - commandCount: commands.length, zeroTestCommands: matrix.rows.filter(row => !row.registered).map(row => row.command), + commandCount: commands.length, unattributedCommands: matrix.rows.filter(row => !row.registered).map(row => row.command), totals: counts(observed.tests), uniqueAttributed: matrix.uniqueAttributed, runnerExitCode: runner.status, moduleErrors: observed.moduleErrors, unhandledErrors: observed.unhandledErrors, commands: matrix.rows, unattributed: matrix.unattributed }; - const destination = resolve(process.argv[2] ?? "docs/test-command-matrix.json"); + const destination = await matrixDestination(process.argv[2]); await writeFile(destination, `${JSON.stringify(output,null,2)}\n`); - console.log(JSON.stringify({ commandCount: output.commandCount, zeroTestCommands: output.zeroTestCommands.length, + console.log(JSON.stringify({ commandCount: output.commandCount, unattributedCommands: output.unattributedCommands.length, ...output.totals, uniqueAttributed: output.uniqueAttributed, output: relative(root,destination) })); if (runner.status !== 0 || observed.moduleErrors.length || observed.unhandledErrors) process.exitCode = 1; } finally { diff --git a/test/command-matrix.test.ts b/test/command-matrix.test.ts index 99b9d9b8..8f96d2aa 100644 --- a/test/command-matrix.test.ts +++ b/test/command-matrix.test.ts @@ -1,6 +1,14 @@ -import { expect, it } from "vitest"; +import { mkdtemp, rm } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { dirname, join, relative } from "node:path"; +import { spawnSync } from "node:child_process"; +import { expect, it, vi } from "vitest"; // @ts-expect-error The CLI support script is native ESM JavaScript. -import { reconcile, counts } from "../scripts/test-command-matrix.mjs"; +import { reconcile, counts, runTests, matrixDestination, parserCommands } from "../scripts/test-command-matrix.mjs"; + +vi.mock("node:child_process", async importOriginal => ({ + ...await importOriginal(), spawnSync: vi.fn(), +})); it("reconciles shared command attribution without double-counting unique runner IDs", () => { const registered = [{ id: "a", file: "case.ts", name: "parameter 1" }, { id: "b", file: "case.ts", name: "parameter 2" }]; @@ -15,3 +23,34 @@ it("reconciles shared command attribution without double-counting unique runner expect(() => reconcile(["one"], registered, results, [{ file: "case.ts", name: "parameter 1", commands: ["unknown"], evidence: "fixture" }])).toThrow(/Unknown/); expect(counts([{ status: "passed" }, { status: "failed" }, { status: "skipped" }, { status: "pending" }])).toEqual({ registered: 4, executed: 2, pass: 1, fail: 1, skipped: 1, pending: 1 }); }); + +it("rejects mappings without a commands array with an explicit validation error", () => { + const registered = [{ id: "a", file: "case.ts", name: "case" }]; + for (const commands of [undefined, null, "one", []]) { + expect(() => reconcile(["one"], registered, registered, + [{ file: "case.ts", name: "case", evidence: "fixture", commands }])).toThrow(/Invalid mapping/); + } +}); + +it("streams default reporter output and runner errors to CI", () => { + runTests("runner.json", "vitest.json"); + expect(vi.mocked(spawnSync)).toHaveBeenCalledWith("pnpm", expect.arrayContaining(["test", "--reporter=default"]), + expect.objectContaining({ stdio: "inherit" })); +}); + +it("keeps the default report outside the checkout in a temporary directory", async () => { + const output = await matrixDestination(); + try { + expect(relative(tmpdir(), output)).toMatch(/^command-matrix-output-[^/]+\/matrix\.json$/); + expect(await matrixDestination("custom.json")).toBe(join(process.cwd(), "custom.json")); + } finally { await rm(dirname(output), { recursive: true, force: true }); } +}); + +it("loads the Commander tree from a scratch directory outside the checkout", async () => { + const scratch = await mkdtemp(join(tmpdir(), "command-matrix-parser-test-")); + try { + const commands = await parserCommands(scratch); + expect(commands).toEqual(expect.arrayContaining(["agentwheel", "cache prune", "registry publish", "doctor"])); + expect(new Set(commands).size).toBe(commands.length); + } finally { await rm(scratch, { recursive: true, force: true }); } +}); diff --git a/test/invariants/i2-no-loss.test.ts b/test/invariants/i2-no-loss.test.ts index 7f579679..c0c822a9 100644 --- a/test/invariants/i2-no-loss.test.ts +++ b/test/invariants/i2-no-loss.test.ts @@ -1,11 +1,11 @@ import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; -import { join } from "node:path"; +import { join, relative } from "node:path"; import { expect, it } from "vitest"; import { GitSourceDriver } from "../../src/source/git.js"; import { diffEffects, snapshot } from "../helpers/effects.js"; -it.fails("read_missing_git_preserves_cache", async () => { +async function observeIncompleteCacheRead() { const root = await mkdtemp(join(tmpdir(), "invariant-i2-")); try { const driver = new GitSourceDriver(); @@ -15,8 +15,22 @@ it.fails("read_missing_git_preserves_cache", async () => { await writeFile(join(resolved.resolvedPath, "sentinel"), "preserve me"); const before = await snapshot(root); const failure = await driver.fetch(resolved).then(() => undefined, error => error); - expect(failure).toBeInstanceOf(Error); - // Expected: a read refuses an incomplete checkout without deleting existing bytes. - expect(diffEffects(before, await snapshot(root))).toEqual([]); + const cachePath = relative(root, resolved.resolvedPath); + return { failure, effects: diffEffects(before, await snapshot(root)), + removedPaths: [`tree:${cachePath}`, `tree:${cachePath}/sentinel`] }; + } finally { await rm(root, { recursive: true, force: true }); } +} + +// Expected: a read refuses an incomplete checkout without deleting existing bytes. +it.fails("read_missing_git_preserves_cache", async () => { + const observed = await observeIncompleteCacheRead(); + expect(observed.failure).toBeInstanceOf(Error); + expect(observed.effects).toEqual([]); +}); + +it("read_missing_git_preserves_cache_current_defect_deletes_only_sentinel_tree", async () => { + const observed = await observeIncompleteCacheRead(); + expect(observed.failure).toBeInstanceOf(Error); + expect(observed.effects).toEqual(observed.removedPaths); }); diff --git a/test/invariants/i5-admission-parity.test.ts b/test/invariants/i5-admission-parity.test.ts index b3f446b7..f94853b8 100644 --- a/test/invariants/i5-admission-parity.test.ts +++ b/test/invariants/i5-admission-parity.test.ts @@ -7,7 +7,7 @@ import { targetMappingSchema, type AdapterConfig } from "../../src/model/adapter import { hashPath } from "../../src/utils/fs.js"; import { diffEffects, snapshot } from "../helpers/effects.js"; -it.fails("stale_merge_metadata_rejected_in_all_paths", async () => { +async function observeStaleMergeAdmission() { const root = await mkdtemp(join(tmpdir(), "invariant-i5-")); try { const sourcePath = join(root, "source.json"); @@ -26,12 +26,26 @@ it.fails("stale_merge_metadata_rejected_in_all_paths", async () => { const preview = await createCombinedInstallPlan([artifact], adapter, root, manifest); expect(diffEffects(before, await snapshot(root))).toEqual([]); const failure = await applyCombinedInstallPlan(preview).then(() => undefined, error => error); - expect(failure).toBeInstanceOf(Error); - // Expected: preview blocks the same stale contribution that apply rejects. - expect(preview.hasBlockingChanges).toBe(true); - expect(preview.operations).toEqual(expect.arrayContaining([expect.objectContaining({ - action: "conflict", blockedReason: expect.stringMatching(/contribution|merge/i), - })])); - expect(diffEffects(before, await snapshot(root))).toEqual([]); + return { preview, failure, effects: diffEffects(before, await snapshot(root)) }; } finally { await rm(root, { recursive: true, force: true }); } +} + +// Expected: preview blocks the same stale contribution that apply rejects. +it.fails("stale_merge_metadata_rejected_in_all_paths", async () => { + const { preview, failure, effects } = await observeStaleMergeAdmission(); + expect(failure).toBeInstanceOf(Error); + expect(preview.hasBlockingChanges).toBe(true); + expect(preview.operations).toEqual(expect.arrayContaining([expect.objectContaining({ + action: "conflict", blockedReason: expect.stringMatching(/contribution|merge/i), + })])); + expect(effects).toEqual([]); +}); + +it("stale_merge_metadata_rejected_in_all_paths_current_defect_skips_preview_but_apply_refuses", async () => { + const { preview, failure } = await observeStaleMergeAdmission(); + expect(preview.hasBlockingChanges).toBe(false); + expect(preview.operations).toMatchObject([{ action: "skip" }]); + expect(preview.operations).toHaveLength(1); + expect(failure).toBeInstanceOf(Error); + expect(String(failure)).toMatch(/exact merge contribution/); }); diff --git a/test/invariants/i7-effects-containment.test.ts b/test/invariants/i7-effects-containment.test.ts deleted file mode 100644 index 7a9919fb..00000000 --- a/test/invariants/i7-effects-containment.test.ts +++ /dev/null @@ -1,20 +0,0 @@ -import { mkdtemp, rm } from "node:fs/promises"; -import { tmpdir } from "node:os"; -import { join } from "node:path"; -import { expect, it } from "vitest"; -import { refuseNewPinCollisions } from "../../src/lifecycle/pin-preflight.js"; -import { diffEffects, snapshot } from "../helpers/effects.js"; - -it.fails("pin_provenance_and_feature_floor_enforced", async () => { - const root = await mkdtemp(join(tmpdir(), "invariant-i7-")); - try { - const before = await snapshot(root); - const warnings: string[] = []; - const failure = await refuseNewPinCollisions(root, { - schemaVersion: 1, packages: [{ name: "synthetic-pin", source: join(root, "unresolvable"), mode: "pinned" }], - }, message => warnings.push(message)).then(() => undefined, error => error); - expect(diffEffects(before, await snapshot(root))).toEqual([]); - // Expected: an unresolved approved pin refuses; warning and success are insufficient. - expect({ refused: failure instanceof Error, warnings }).toMatchObject({ refused: true }); - } finally { await rm(root, { recursive: true, force: true }); } -}); From 3f8bf8e4b0aee8b42ab0881917000fc1001c53d9 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:00:53 +0000 Subject: [PATCH 12/19] test: reproduce persistent effects around synthetic status reads --- test/helpers/read-effects-preload.cjs | 22 ++++++++ test/helpers/read-effects.ts | 52 +++++++++++++++++++ .../invariants/i7-effects-containment.test.ts | 23 ++++++++ 3 files changed, 97 insertions(+) create mode 100644 test/helpers/read-effects-preload.cjs create mode 100644 test/helpers/read-effects.ts create mode 100644 test/invariants/i7-effects-containment.test.ts diff --git a/test/helpers/read-effects-preload.cjs b/test/helpers/read-effects-preload.cjs new file mode 100644 index 00000000..54cdf641 --- /dev/null +++ b/test/helpers/read-effects-preload.cjs @@ -0,0 +1,22 @@ +// Fixture-only observer. Evidence is the single explicitly excluded trace file. +const fs = require("node:fs"); +const child = require("node:child_process"); +const util = require("node:util"); +const { syncBuiltinESMExports } = require("node:module"); +function record(kind, name, args) { + fs.appendFileSync(process.env.SYNTHETIC_EFFECT_TRACE, JSON.stringify({ kind, name, args }) + "\n"); +} +for (const name of ["execFile", "execFileSync", "spawn", "spawnSync", "exec", "execSync"]) { + const original = child[name]; + const wrapped = function(...args) { record("process", name, args.slice(0,2)); return original.apply(this,args); }; + if (original[util.promisify.custom]) wrapped[util.promisify.custom] = function(...args) { + record("process", name, args.slice(0,2)); return original[util.promisify.custom].apply(this,args); + }; + child[name] = wrapped; +} +for (const [moduleName, names] of [["node:http", ["request", "get"]], ["node:https", ["request", "get"]], ["node:net", ["connect", "createConnection"]]]) { + const module = require(moduleName); + for (const name of names) module[name] = function() { record("network", `${moduleName}.${name}`, []); throw new Error("Synthetic fixture forbids network"); }; +} +globalThis.fetch = async function() { record("network", "fetch", []); throw new Error("Synthetic fixture forbids network"); }; +syncBuiltinESMExports(); diff --git a/test/helpers/read-effects.ts b/test/helpers/read-effects.ts new file mode 100644 index 00000000..34ee913b --- /dev/null +++ b/test/helpers/read-effects.ts @@ -0,0 +1,52 @@ +import { execFileSync, spawnSync } from "node:child_process"; +import { mkdir, mkdtemp, readFile, rm, utimes, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { GitSourceDriver } from "../../src/source/git.js"; +import { releaseGitSnapshotLease } from "../../src/source/cache.js"; +import { diffEffects, snapshot } from "./effects.js"; + +export async function readFixture(warm: boolean) { + const root = await mkdtemp(join(tmpdir(), "synthetic-read-")); + const home = join(root,"home"); const workspace = join(root,"workspace"); + const temp = join(root,"temp"); const source = join(root,"source"); + const cacheRoot = join(workspace,".agentwheel/cache"); + for (const path of [home, workspace, temp, join(source,"skills/synthetic"), join(workspace,".agentwheel")]) await mkdir(path, { recursive: true }); + const git = (dir: string, ...args: string[]) => execFileSync("git", ["-C",dir,...args], { encoding: "utf8", env: { ...process.env, GIT_CONFIG_GLOBAL: "/dev/null" } }); + for (const dir of [workspace, source]) { + git(dir,"init","-b","main"); git(dir,"config","user.name","Synthetic"); git(dir,"config","user.email","synthetic@example.invalid"); + } + await writeFile(join(workspace,"sentinel"),"user bytes"); git(workspace,"add","sentinel"); git(workspace,"commit","-m","fixture"); + await writeFile(join(source,"skills/synthetic/SKILL.md"), "---\nname: synthetic\ndescription: Synthetic skill.\n---\n# Synthetic\n"); + await writeFile(join(source,"openpack.json"), JSON.stringify({ schemaVersion: 2, name: "fixture/synthetic", version: "1.0.0", provides: [{ type: "skills", path: "skills" }] })); + git(source,"add","openpack.json","skills"); git(source,"commit","-m","fixture"); + const sourceUrl = `git:${source}#main`; + await writeFile(join(workspace,".agentwheel/config.json"), JSON.stringify({ schemaVersion: 1, bootstrapSkills: false, + packages: [{ name: "synthetic", source: sourceUrl, driver: "git", mode: "pinned", requestedRef: "main", adapter: "codex", installationType: "local" }], registry: {}, profiles: {}, agents: {} })); + const driver = new GitSourceDriver(); + const resolved = await driver.resolve(sourceUrl,{ cacheRoot }); + if (warm) { + const fetched = await driver.fetch(resolved); await releaseGitSnapshotLease(fetched.cacheLeasePath); + for (const prefix of ["111111111111","222222222222","333333333333","444444444444"]) { + const path = `${resolved.resolvedPath}-${prefix}`; + await mkdir(path); await writeFile(join(path,"sentinel"),"retained cache evidence"); await utimes(path,1,1); + } + } + const trace = join(root,"trace.jsonl"); await writeFile(trace,""); + const policy = { exclude: { "trace.jsonl": "Only the fixture observer evidence is excluded; command state is compared exactly." } }; + return { + root, workspace, home, temp, cacheRoot, resolved, + async probe(extra: string[] = [], entry = join(process.cwd(),"dist/index.js")) { + const before = await snapshot(root,policy); + const result = spawnSync(process.execPath, [entry,"status","--local","--adapter","codex","--target-root",workspace,"--json",...extra], { + cwd: workspace, encoding: "utf8", timeout: 30_000, + env: { ...process.env, HOME: home, XDG_CONFIG_HOME: join(home,".config"), XDG_CACHE_HOME: join(home,".cache"), TMPDIR: temp, + AGENTWHEEL_NO_UPDATE_CHECK: "1", GIT_CONFIG_GLOBAL: "/dev/null", + NODE_OPTIONS: `--require=${resolve("test/helpers/read-effects-preload.cjs")}`, SYNTHETIC_EFFECT_TRACE: trace }, + }); + const calls = (await readFile(trace,"utf8")).trim().split("\n").filter(Boolean).map(line => JSON.parse(line) as { kind: string; name: string; args: unknown[] }); + return { result, calls, changes: diffEffects(before,await snapshot(root,policy)) }; + }, + dispose: () => rm(root,{ recursive: true, force: true }), + }; +} diff --git a/test/invariants/i7-effects-containment.test.ts b/test/invariants/i7-effects-containment.test.ts new file mode 100644 index 00000000..2d60b729 --- /dev/null +++ b/test/invariants/i7-effects-containment.test.ts @@ -0,0 +1,23 @@ +import { expect, it } from "vitest"; +import { readFixture } from "../helpers/read-effects.js"; + +it.each([false,true])("read_effects_match_explicit_policy_status_warm_%s", async warm => { + const fixture = await readFixture(warm); + try { + const observed = await fixture.probe(); + expect(observed.result.error).toBeUndefined(); + expect(JSON.parse(observed.result.stdout).command).toBe("status"); + expect(observed.calls.filter(call => call.kind === "network")).toEqual([]); + expect(observed.calls.filter(call => /\b(fetch|clone|ls-remote)\b/.test(JSON.stringify(call.args)))).toEqual([]); + expect(observed.changes).toEqual([]); + } finally { await fixture.dispose(); } +}, 30_000); + +it("read_never_evicts_snapshot", async () => { + const fixture = await readFixture(true); + try { + const observed = await fixture.probe(["--offline"]); + expect(JSON.parse(observed.result.stdout).command).toBe("status"); + expect(observed.changes).toEqual([]); + } finally { await fixture.dispose(); } +}, 30_000); From c290660627fbcdaa3681362108fa3b6bea80f44a Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:02:14 +0000 Subject: [PATCH 13/19] test: use an unambiguous synthetic workspace selector --- test/helpers/read-effects.ts | 2 +- test/invariants/i7-effects-containment.test.ts | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/test/helpers/read-effects.ts b/test/helpers/read-effects.ts index 34ee913b..a2b23d37 100644 --- a/test/helpers/read-effects.ts +++ b/test/helpers/read-effects.ts @@ -38,7 +38,7 @@ export async function readFixture(warm: boolean) { root, workspace, home, temp, cacheRoot, resolved, async probe(extra: string[] = [], entry = join(process.cwd(),"dist/index.js")) { const before = await snapshot(root,policy); - const result = spawnSync(process.execPath, [entry,"status","--local","--adapter","codex","--target-root",workspace,"--json",...extra], { + const result = spawnSync(process.execPath, [entry,"status","--installation-type","local","--adapter","codex","--target-root",workspace,"--json",...extra], { cwd: workspace, encoding: "utf8", timeout: 30_000, env: { ...process.env, HOME: home, XDG_CONFIG_HOME: join(home,".config"), XDG_CACHE_HOME: join(home,".cache"), TMPDIR: temp, AGENTWHEEL_NO_UPDATE_CHECK: "1", GIT_CONFIG_GLOBAL: "/dev/null", diff --git a/test/invariants/i7-effects-containment.test.ts b/test/invariants/i7-effects-containment.test.ts index 2d60b729..9780f791 100644 --- a/test/invariants/i7-effects-containment.test.ts +++ b/test/invariants/i7-effects-containment.test.ts @@ -6,6 +6,7 @@ it.each([false,true])("read_effects_match_explicit_policy_status_warm_%s", async try { const observed = await fixture.probe(); expect(observed.result.error).toBeUndefined(); + expect(observed.result.stdout, observed.result.stderr).not.toBe(""); expect(JSON.parse(observed.result.stdout).command).toBe("status"); expect(observed.calls.filter(call => call.kind === "network")).toEqual([]); expect(observed.calls.filter(call => /\b(fetch|clone|ls-remote)\b/.test(JSON.stringify(call.args)))).toEqual([]); @@ -17,6 +18,7 @@ it("read_never_evicts_snapshot", async () => { const fixture = await readFixture(true); try { const observed = await fixture.probe(["--offline"]); + expect(observed.result.stdout, observed.result.stderr).not.toBe(""); expect(JSON.parse(observed.result.stdout).command).toBe("status"); expect(observed.changes).toEqual([]); } finally { await fixture.dispose(); } From cc2ec0c810d6672421c415c6f81ca819cb9a605f Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:11:45 +0000 Subject: [PATCH 14/19] test: expose cache deletion and lease effects before the read policy fix --- .../invariants/i7-effects-containment.test.ts | 20 ++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/test/invariants/i7-effects-containment.test.ts b/test/invariants/i7-effects-containment.test.ts index 9780f791..966eec97 100644 --- a/test/invariants/i7-effects-containment.test.ts +++ b/test/invariants/i7-effects-containment.test.ts @@ -1,3 +1,5 @@ +import { rm, writeFile } from "node:fs/promises"; +import { join } from "node:path"; import { expect, it } from "vitest"; import { readFixture } from "../helpers/read-effects.js"; @@ -9,8 +11,8 @@ it.each([false,true])("read_effects_match_explicit_policy_status_warm_%s", async expect(observed.result.stdout, observed.result.stderr).not.toBe(""); expect(JSON.parse(observed.result.stdout).command).toBe("status"); expect(observed.calls.filter(call => call.kind === "network")).toEqual([]); - expect(observed.calls.filter(call => /\b(fetch|clone|ls-remote)\b/.test(JSON.stringify(call.args)))).toEqual([]); - expect(observed.changes).toEqual([]); + expect.soft(observed.calls.filter(call => /\b(fetch|clone|ls-remote)\b/.test(JSON.stringify(call.args)))).toEqual([]); + expect.soft(observed.changes).toEqual([]); } finally { await fixture.dispose(); } }, 30_000); @@ -20,6 +22,18 @@ it("read_never_evicts_snapshot", async () => { const observed = await fixture.probe(["--offline"]); expect(observed.result.stdout, observed.result.stderr).not.toBe(""); expect(JSON.parse(observed.result.stdout).command).toBe("status"); - expect(observed.changes).toEqual([]); + expect.soft(observed.changes).toEqual([]); + } finally { await fixture.dispose(); } +}, 30_000); + +it("read_missing_git_preserves_cache_status", async () => { + const fixture = await readFixture(true); + try { + await rm(join(fixture.resolved.resolvedPath,".git"), { recursive: true }); + await writeFile(join(fixture.resolved.resolvedPath,"sentinel"),"preserve incomplete checkout"); + const observed = await fixture.probe(); + expect(observed.result.stdout, observed.result.stderr).not.toBe(""); + expect(JSON.parse(observed.result.stdout).command).toBe("status"); + expect.soft(observed.changes).toEqual([]); } finally { await fixture.dispose(); } }, 30_000); From 92e8cf0829245d890a28bd76a914866811762670 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:17:09 +0000 Subject: [PATCH 15/19] fix: observe status caches without implicit refresh or builds --- docs/read-effects.md | 17 ++++++ scripts/agentwheel-local.mjs | 23 ++++++++ src/adapters/resolve.ts | 2 + src/cli/index.ts | 5 +- src/cli/update-check.ts | 2 + src/effects/read-policy.ts | 23 ++++++++ src/profile/members.ts | 5 +- src/registry/client.ts | 7 ++- src/resolve/graph.ts | 4 ++ src/source/cache.ts | 4 ++ src/source/git.ts | 28 +++++++++- src/status/repository.ts | 2 +- src/transport/index.ts | 2 + src/version/policy.ts | 5 +- test/helpers/read-effects.ts | 4 +- test/invariants/i2-no-loss.test.ts | 7 +-- .../invariants/i7-effects-containment.test.ts | 52 ++++++++++++++++++- test/read-effect-policy.test.ts | 50 ++++++++++++++++++ 18 files changed, 225 insertions(+), 17 deletions(-) create mode 100644 docs/read-effects.md create mode 100644 scripts/agentwheel-local.mjs create mode 100644 src/effects/read-policy.ts create mode 100644 test/read-effect-policy.test.ts diff --git a/docs/read-effects.md b/docs/read-effects.md new file mode 100644 index 00000000..94194628 --- /dev/null +++ b/docs/read-effects.md @@ -0,0 +1,17 @@ +# Status observation and explicit refresh + +`status` now observes local state and existing caches by default, regardless of cache TTL. `status --refresh` explicitly permits cache population, source fetches, snapshot maintenance, version discovery and composite member refresh. `--offline` wins over `--refresh`. Missing or stale evidence remains visible in the status protocol instead of causing an implicit refresh. Useful cached Git snapshots and local sources still support pending-work inspection; an absent cached snapshot returns a named refresh requirement. + +The AsyncLocalStorage scope in `src/effects/read-policy.ts` centralizes this distinction across graph sources, registry/version indexes, member reports, and cache writers. Observation never creates cache leases or maintenance locks and does not prune snapshots. Incomplete checkout directories are preserved even during refresh: repair is a separate explicit operation. Git status disables optional index locks. The optional update notifier does not fetch or persist on status reads. + +Observation supports built-in local targets and cached composite reports. Unqualified programmatic adapters, source drivers other than local/Git, and direct remote transports refuse before execution; explicit refresh retains their existing admission and execution paths. This deliberately avoids promising zero effects for arbitrary executable code. Other CLI read/preview verbs have not yet been qualified by this batch. + +Diagnostics consumers of the versioned `status --json` protocol inherit this policy. Tests exercise a synthetic child-process consumer, not a private fleet configuration. No fleet diagnostics source is changed by this PR. + +`scripts/agentwheel-local.mjs` is the generic source-owned local launcher. It requires a prebuilt, current `dist/index.js`, or refuses with an explicit build instruction. It never runs a package manager, acquires a build lock, or builds implicitly, for any verb. `AGENTWHEEL_REPO_DIR` selects a checkout; the default is the repository containing the launcher. This PR does not replace any installed wrapper or retarget a runtime launcher. + +## Evidence and limits + +The B0a effects helper is reused from PR #201; this PR is based on that branch. Before the product changes, synthetic status fixtures reproduced clone/fetch/tag queries, persistent cache leases and version-index writes, and removal of a sentinel from an incomplete checkout. A separately isolated legacy-launcher probe reproduced one implicit build on a status invocation with a dummy builder. That launcher was unversioned: the replacement above establishes a source-owned implementation without copying host-specific defaults into public source. + +The fixture snapshots synthetic HOME, workspace, cache, Git metadata and temp before/after each invocation. A child preload records process calls and rejects Node network APIs; only its exact evidence file is excluded from tree comparison. Tests cover cold/warm/offline/refused reads, a diagnostics protocol consumer, wrapper admission, and explicitly bounded refresh writes. External Git network access is checked through command arguments; this is an application-boundary trace, not a kernel syscall sandbox. Concurrent refresh/prune versus a lease-free observer remains a separate cache-lifecycle qualification concern: observation may report missing evidence but cannot repair or delete it. diff --git a/scripts/agentwheel-local.mjs b/scripts/agentwheel-local.mjs new file mode 100644 index 00000000..be416ef3 --- /dev/null +++ b/scripts/agentwheel-local.mjs @@ -0,0 +1,23 @@ +#!/usr/bin/env node +import { readdirSync, statSync } from "node:fs"; +import { dirname, join, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; +import { spawnSync } from "node:child_process"; + +const root = resolve(process.env.AGENTWHEEL_REPO_DIR ?? join(dirname(fileURLToPath(import.meta.url)), "..")); +const entry = join(root,"dist/index.js"); +function newest(path) { + let stat; + try { stat = statSync(path); } catch { return 0; } + return stat.isDirectory() ? Math.max(stat.mtimeMs,...readdirSync(path).map(name => newest(join(path,name)))) : stat.mtimeMs; +} +let built = 0; +try { built = statSync(entry).mtimeMs; } catch { /* Missing builds are refused below. */ } +if (!built || ["src","package.json","pnpm-lock.yaml","tsconfig.json","tsup.config.ts"].some(path => newest(join(root,path)) > built)) { + console.error("agentwheel: built CLI is missing or stale. Build explicitly with pnpm build in the selected checkout; this wrapper never builds implicitly."); + process.exitCode = 127; +} else { + const result = spawnSync(process.execPath,[entry,...process.argv.slice(2)],{ stdio: "inherit" }); + if (result.error) console.error(result.error.message); + process.exitCode = result.status ?? 1; +} diff --git a/src/adapters/resolve.ts b/src/adapters/resolve.ts index 8ea3a963..0352a97c 100644 --- a/src/adapters/resolve.ts +++ b/src/adapters/resolve.ts @@ -1,3 +1,4 @@ +import { isObservation } from "../effects/read-policy.js"; import { resolve } from "node:path"; import type { AdapterConfig } from "../model/adapter.js"; import { loadAdapterConfig } from "../model/adapter.js"; @@ -15,6 +16,7 @@ export interface ResolveAdapterOptions { export async function resolveAdapter(options: ResolveAdapterOptions): Promise { if (options.adapterModule) { + if (isObservation()) throw new Error("Observation refuses unqualified adapter code; use --refresh explicitly."); const modulePath = resolve(options.baseDir ?? process.cwd(), options.adapterModule); const adapter = await loadProgrammaticAdapter(modulePath, { allowCode: options.allowAdapterCode === true }); options.warn?.(`WARNING: loaded local adapter code ${adapter.programmatic?.modulePath} (${adapter.programmatic?.hash})`); diff --git a/src/cli/index.ts b/src/cli/index.ts index 7acac5bf..5ebcbba1 100644 --- a/src/cli/index.ts +++ b/src/cli/index.ts @@ -1,3 +1,4 @@ +import { withReadEffects } from "../effects/read-policy.js"; import { createHash } from "node:crypto"; import { existsSync } from "node:fs"; import { mkdir, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises"; @@ -1677,7 +1678,7 @@ program .option("--offline", "use cached version and member status even when stale", false) .option("--refresh", "refresh package and member status regardless of TTL", false) .option("--recover-legacy-state", "inspect stable state while preserving invalid historical state", false) - .action(async (options) => { + .action(async (options) => withReadEffects(options, async () => { const normalizedOptions = normalizeRuntimeScopeOptions(options); const composite = await resolveSelectedCompositeProfile(normalizedOptions); if (composite) { @@ -1699,7 +1700,7 @@ program for (const target of targets) { await printStatus(target, normalizedOptions); } - }); + })); const journalCommand = program .command("journal") diff --git a/src/cli/update-check.ts b/src/cli/update-check.ts index 3f5fad49..6edbdb0e 100644 --- a/src/cli/update-check.ts +++ b/src/cli/update-check.ts @@ -1,3 +1,4 @@ +import { isObservationInvocation } from "../effects/read-policy.js"; import { mkdir, readFile, writeFile } from "node:fs/promises"; import { homedir } from "node:os"; import { dirname, join } from "node:path"; @@ -52,6 +53,7 @@ export async function maybeCheckForUpdate(options: UpdateCheckOptions): Promise< } function isDisabled(options: UpdateCheckOptions): boolean { + if (isObservationInvocation(options.argv ?? process.argv)) return true; const env = options.env ?? process.env; if (env.AGENTWHEEL_NO_UPDATE_CHECK === "1" || env.AGENTWHEEL_NO_UPDATE_CHECK === "true") return true; if (env.CI) return true; diff --git a/src/effects/read-policy.ts b/src/effects/read-policy.ts new file mode 100644 index 00000000..f1c69f36 --- /dev/null +++ b/src/effects/read-policy.ts @@ -0,0 +1,23 @@ +import { AsyncLocalStorage } from "node:async_hooks"; + +export type ReadEffectPolicy = "observe" | "refresh"; +const contexts = new AsyncLocalStorage(); + +export function readEffectPolicy(options: { refresh?: boolean; offline?: boolean }): ReadEffectPolicy { + return options.refresh === true && options.offline !== true ? "refresh" : "observe"; +} + +export function withReadEffects(options: { refresh?: boolean; offline?: boolean }, action: () => T): T { + return contexts.run(readEffectPolicy(options), action); +} + +export function isObservation(): boolean { return contexts.getStore() === "observe"; } + +export function requireRefreshEffect(effect: string): void { + if (isObservation()) throw new Error(`Observation refuses ${effect}. Use an explicit --refresh to update caches.`); +} + +// Conservative early suppression of the optional update notifier. Actual admission is scoped by the parsed action. +export function isObservationInvocation(argv: string[]): boolean { + return argv.includes("status") && readEffectPolicy({ refresh: argv.includes("--refresh"), offline: argv.includes("--offline") }) === "observe"; +} diff --git a/src/profile/members.ts b/src/profile/members.ts index 23b9044d..d6518a97 100644 --- a/src/profile/members.ts +++ b/src/profile/members.ts @@ -1,3 +1,4 @@ +import { isObservation } from "../effects/read-policy.js"; import { execFile } from "node:child_process"; import { readFile } from "node:fs/promises"; import { join, resolve } from "node:path"; @@ -57,9 +58,9 @@ async function collectMember( const ageMs = cached ? Date.now() - new Date(cached.checkedAt).getTime() : Number.POSITIVE_INFINITY; const fresh = ageMs <= ttlSeconds * 1000; - if (options.offline || (cached && fresh && !options.refresh)) { + if (isObservation() || options.offline || (cached && fresh && !options.refresh)) { if (!cached) { - return memberFailure(member, "STALE", "No cached member status is available offline."); + return memberFailure(member, "STALE", "No cached member status is available; use --refresh explicitly."); } return memberFromReport(member, cached.report, { checkedAt: cached.checkedAt, diff --git a/src/registry/client.ts b/src/registry/client.ts index cccf3bf6..873e6c2a 100644 --- a/src/registry/client.ts +++ b/src/registry/client.ts @@ -1,3 +1,4 @@ +import { isObservation } from "../effects/read-policy.js"; import { readFile, rm, stat } from "node:fs/promises"; import { homedir } from "node:os"; import { dirname, join, resolve } from "node:path"; @@ -43,14 +44,16 @@ export class RegistryClient { } async getIndex(options: { refresh?: boolean } = {}): Promise { + const offline = this.options.offline || isObservation(); + const refresh = options.refresh && !isObservation(); const sources = await this.getSources(); const ttlMs = await this.getTtlMs(); const cached = await this.readCache(); - if (!options.refresh && cached && sameSources(cached.sources, sources) && (this.options.offline || !this.isExpired(cached, ttlMs))) { + if (!refresh && cached && sameSources(cached.sources, sources) && (offline || !this.isExpired(cached, ttlMs))) { this.warnCompatibility(cached.entries); return { entries: cached.entries, sources: cached.sources, fetchedAt: cached.fetchedAt, fromCache: true }; } - if (this.options.offline) { + if (offline) { const reason = cached ? "registry sources changed" : "registry cache is missing"; const label = this.options.offlineLabel ?? "Offline"; const hint = this.options.offlineHint ?? `Run without ${label === "Offline" ? "--offline" : "--frozen-lock"} first.`; diff --git a/src/resolve/graph.ts b/src/resolve/graph.ts index bbfc7e4b..d44172f7 100644 --- a/src/resolve/graph.ts +++ b/src/resolve/graph.ts @@ -1,3 +1,4 @@ +import { isObservation } from "../effects/read-policy.js"; import { createHash } from "node:crypto"; import { readdir, readFile, stat } from "node:fs/promises"; import { basename, extname, join } from "node:path"; @@ -1005,6 +1006,9 @@ async function fetchPackage( if (existing) return existing; const promise = (async () => { + if (isObservation() && !["local", "git"].includes(normalized.driver)) { + throw new Error(`Observation cannot qualify source driver '${normalized.driver}'; use --refresh explicitly.`); + } const driver = getSourceDriver(normalized.driver); const resolved = await driver.resolve(normalized.source, { cacheRoot: options.cacheRoot ?? join(options.workspaceRoot, ".agentwheel", "cache"), diff --git a/src/source/cache.ts b/src/source/cache.ts index cf51ce95..b8124ff8 100644 --- a/src/source/cache.ts +++ b/src/source/cache.ts @@ -1,3 +1,4 @@ +import { requireRefreshEffect } from "../effects/read-policy.js"; import { randomUUID } from "node:crypto"; import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises"; import { dirname, join } from "node:path"; @@ -30,6 +31,7 @@ interface SnapshotEntry { * The mutable checkout itself is never removed. */ export async function pruneGitCache(cacheRoot: string, options: GitCachePruneOptions = {}): Promise { + requireRefreshEffect("cache pruning"); if (!(await pathExists(cacheRoot))) return { removedPaths: [], retainedPaths: [] }; if (options.maintenanceLockHeld) return pruneGitCacheUnlocked(cacheRoot, options); return withGitCacheMaintenanceLock( @@ -44,6 +46,7 @@ export async function withGitCacheMaintenanceLock( timeoutMs: number, fn: () => Promise, ): Promise { + requireRefreshEffect("persistent cache maintenance locks"); const lockPath = join(cacheRoot, ".maintenance.lock"); await mkdir(cacheRoot, { recursive: true }); const started = Date.now(); @@ -73,6 +76,7 @@ export async function withGitCacheMaintenanceLock( } export async function createGitSnapshotLease(snapshotPath: string): Promise { + requireRefreshEffect("persistent snapshot leases"); const leasePath = `${snapshotPath}${leaseMarker}${process.pid}-${randomUUID()}`; await writeFile(leasePath, JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }), { encoding: "utf8", diff --git a/src/source/git.ts b/src/source/git.ts index fdfe3011..2514130c 100644 --- a/src/source/git.ts +++ b/src/source/git.ts @@ -1,3 +1,4 @@ +import { isObservation } from "../effects/read-policy.js"; import { execFile } from "node:child_process"; import { mkdir, rename, rm, stat } from "node:fs/promises"; import { homedir } from "node:os"; @@ -43,6 +44,10 @@ export class GitSourceDriver implements SourceDriver { } async fetch(resolved: ResolvedSource): Promise { + if (isObservation()) return this.observe(resolved); + if (await pathExists(resolved.resolvedPath) && !(await pathExists(join(resolved.resolvedPath, ".git")))) { + throw new Error("Incomplete cached checkout preserved; explicit cache repair is required before refresh."); + } return withFilesystemLock(`${resolved.resolvedPath}.lock`, resolved.cacheLockTimeoutMs ?? 30_000, async () => { const parsed = parseGitSource(resolved.source); const cacheRoot = dirname(resolved.resolvedPath); @@ -53,7 +58,9 @@ export class GitSourceDriver implements SourceDriver { if (resolved.frozenLock) { throw new Error(`Frozen lock requires cached git checkout at ${resolved.resolvedPath}`); } - await rm(resolved.resolvedPath, { recursive: true, force: true }); + if (await pathExists(resolved.resolvedPath)) { + throw new Error("Incomplete cached checkout preserved; explicit cache repair is required before refresh."); + } await git([...(await gitAuthArguments(parsed.url)), "clone", "--no-checkout", parsed.url, resolved.resolvedPath]); await assertOwnedByCurrentUser(resolved.resolvedPath); } else if (!resolved.frozenLock) { @@ -103,6 +110,23 @@ export class GitSourceDriver implements SourceDriver { }, "git cache"); } + private async observe(resolved: ResolvedSource): Promise { + if (!(await pathExists(join(resolved.resolvedPath, ".git")))) { + throw new Error("Observation requires a complete cached Git checkout; existing bytes were preserved. Use --refresh for an absent cache, or explicitly repair an incomplete checkout."); + } + const parsed = parseGitSource(resolved.source); + const commit = await resolveCommit(resolved.resolvedPath, resolved.requestedRef ?? parsed.ref ?? "HEAD"); + const snapshot = join(dirname(resolved.resolvedPath), `${basename(resolved.resolvedPath)}-${commit.slice(0,12)}`); + const packageRoot = parsed.subpath ? join(snapshot, parsed.subpath) : snapshot; + if (!(await isDirectory(packageRoot))) { + throw new Error("Observation requires an existing cached Git snapshot; use --refresh to materialize it."); + } + const manifest = await readPackageManifest(packageRoot); + return { ...resolved, resolvedPath: packageRoot, resolvedCommit: commit, + packageName: manifest?.name, packageVersion: manifest?.version, + sourceHash: await hashPath(packageRoot), cacheLeasePath: undefined }; + } + async list(resolved: ResolvedSource) { return this.local.list({ ...resolved, driver: "local" }); } @@ -139,7 +163,7 @@ function cachePathFor(url: string, cacheRoot?: string): string { } async function git(args: string[], env?: NodeJS.ProcessEnv) { - return execFileAsync("git", args, { env, maxBuffer: 1024 * 1024 * 10 }); + return execFileAsync("git", args, { env: isObservation() ? { ...process.env, ...env, GIT_OPTIONAL_LOCKS: "0" } : env, maxBuffer: 1024 * 1024 * 10 }); } async function resolveCommit(checkoutPath: string, ref: string): Promise { diff --git a/src/status/repository.ts b/src/status/repository.ts index 32373506..3492a606 100644 --- a/src/status/repository.ts +++ b/src/status/repository.ts @@ -19,7 +19,7 @@ export async function collectRepositoryStatus(workspaceRoot: string): Promise JSON.parse(line) as { kind: string; name: string; args: unknown[] }); return { result, calls, changes: diffEffects(before,await snapshot(root,policy)) }; diff --git a/test/invariants/i2-no-loss.test.ts b/test/invariants/i2-no-loss.test.ts index c0c822a9..577ec2d4 100644 --- a/test/invariants/i2-no-loss.test.ts +++ b/test/invariants/i2-no-loss.test.ts @@ -23,14 +23,15 @@ async function observeIncompleteCacheRead() { } // Expected: a read refuses an incomplete checkout without deleting existing bytes. -it.fails("read_missing_git_preserves_cache", async () => { +it("read_missing_git_preserves_cache", async () => { const observed = await observeIncompleteCacheRead(); expect(observed.failure).toBeInstanceOf(Error); expect(observed.effects).toEqual([]); }); -it("read_missing_git_preserves_cache_current_defect_deletes_only_sentinel_tree", async () => { +it("read_missing_git_preserves_cache_requires_explicit_repair", async () => { const observed = await observeIncompleteCacheRead(); expect(observed.failure).toBeInstanceOf(Error); - expect(observed.effects).toEqual(observed.removedPaths); + expect(String(observed.failure)).toMatch(/Incomplete cached checkout preserved/); + expect(observed.effects).toEqual([]); }); diff --git a/test/invariants/i7-effects-containment.test.ts b/test/invariants/i7-effects-containment.test.ts index 966eec97..3149ee11 100644 --- a/test/invariants/i7-effects-containment.test.ts +++ b/test/invariants/i7-effects-containment.test.ts @@ -1,5 +1,5 @@ import { rm, writeFile } from "node:fs/promises"; -import { join } from "node:path"; +import { join, resolve } from "node:path"; import { expect, it } from "vitest"; import { readFixture } from "../helpers/read-effects.js"; @@ -37,3 +37,53 @@ it("read_missing_git_preserves_cache_status", async () => { expect.soft(observed.changes).toEqual([]); } finally { await fixture.dispose(); } }, 30_000); + +it("read_effects_match_explicit_policy_diagnostics_consumer", async () => { + const fixture = await readFixture(true); + try { + const consumer = join(fixture.root,"diagnostics.mjs"); + await writeFile(consumer, `import { spawnSync } from "node:child_process"; +const result = spawnSync(process.execPath, [process.env.SYNTHETIC_CLI,...process.argv.slice(2)], {stdio:"inherit"}); +process.exitCode = result.status ?? 1;`); + const observed = await fixture.probe([],consumer,{ SYNTHETIC_CLI: resolve("dist/index.js") }); + expect(observed.result.stdout,observed.result.stderr).not.toBe(""); + expect(JSON.parse(observed.result.stdout).command).toBe("status"); + expect(observed.calls.filter(call => call.kind === "network")).toEqual([]); + expect(observed.changes).toEqual([]); + } finally { await fixture.dispose(); } +}, 30_000); + +it("unqualified_cli_does_not_build_on_read", async () => { + const fixture = await readFixture(false); + try { + const observed = await fixture.probe([],resolve("scripts/agentwheel-local.mjs"),{ AGENTWHEEL_REPO_DIR: fixture.root }); + expect(observed.result.status).toBe(127); + expect(observed.result.stderr).toMatch(/Build explicitly.*never builds implicitly/); + expect(observed.calls).toEqual([]); + expect(observed.changes).toEqual([]); + } finally { await fixture.dispose(); } +}, 30_000); + +it("read_effects_match_explicit_policy_local_wrapper", async () => { + const fixture = await readFixture(true); + try { + const observed = await fixture.probe([],resolve("scripts/agentwheel-local.mjs"),{ AGENTWHEEL_REPO_DIR: process.cwd() }); + expect(observed.result.stdout,observed.result.stderr).not.toBe(""); + expect(JSON.parse(observed.result.stdout).command).toBe("status"); + expect(observed.calls.filter(call => call.kind === "network")).toEqual([]); + expect(observed.calls.filter(call => /\b(pnpm|flock|clone|fetch|ls-remote)\b/.test(JSON.stringify(call.args)))).toEqual([]); + expect(observed.changes).toEqual([]); + } finally { await fixture.dispose(); } +}, 30_000); + +it("read_effects_match_explicit_policy_explicit_refresh", async () => { + const fixture = await readFixture(false); + try { + const observed = await fixture.probe(["--refresh"]); + expect(observed.result.stdout,observed.result.stderr).not.toBe(""); + expect(JSON.parse(observed.result.stdout).command).toBe("status"); + expect(observed.changes.length).toBeGreaterThan(0); + expect(observed.changes.every(path => path.startsWith("tree:workspace/.agentwheel/cache"))).toBe(true); + expect(observed.calls.filter(call => call.kind === "network")).toEqual([]); + } finally { await fixture.dispose(); } +}, 30_000); diff --git a/test/read-effect-policy.test.ts b/test/read-effect-policy.test.ts new file mode 100644 index 00000000..8e20f6aa --- /dev/null +++ b/test/read-effect-policy.test.ts @@ -0,0 +1,50 @@ +import { mkdtemp, rm } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { expect, it } from "vitest"; +import { withReadEffects, isObservation, readEffectPolicy } from "../src/effects/read-policy.js"; +import { createGitSnapshotLease, pruneGitCache } from "../src/source/cache.js"; +import { maybeCheckForUpdate } from "../src/cli/update-check.js"; +import { collectCompositeMembers } from "../src/profile/members.js"; +import { diffEffects, snapshot } from "./helpers/effects.js"; + +it("preserves context across asynchronous work and restores the caller scope", async () => { + expect(isObservation()).toBe(false); + await withReadEffects({}, async () => { + await Promise.resolve(); expect(isObservation()).toBe(true); + await withReadEffects({refresh:true}, async () => { expect(isObservation()).toBe(false); }); + expect(isObservation()).toBe(true); + }); + expect(isObservation()).toBe(false); + expect(readEffectPolicy({refresh:true,offline:true})).toBe("observe"); +}); + +it("refuses persistent lease and prune helpers before touching an observation tree", async () => { + const root = await mkdtemp(join(tmpdir(),"synthetic-policy-")); + try { + const before = await snapshot(root); + await withReadEffects({}, async () => { + await expect(createGitSnapshotLease(join(root,"snapshot"))).rejects.toThrow(/Observation refuses/); + await expect(pruneGitCache(root)).rejects.toThrow(/Observation refuses/); + }); + expect(diffEffects(before,await snapshot(root))).toEqual([]); + } finally { await rm(root,{recursive:true,force:true}); } +}); + +it("does not fetch or write update notices on an interactive status read", async () => { + let calls=0; + await maybeCheckForUpdate({currentVersion:"1.0.0",argv:["node","cli","status"],env:{},isTTY:true, + fetchImpl: async () => {calls++; throw new Error("unexpected network");}}); + expect(calls).toBe(0); +}); + +it("does not invoke or cache an uncached composite member during observation", async () => { + const root = await mkdtemp(join(tmpdir(),"synthetic-members-")); + try { + const before = await snapshot(root); + const members = await withReadEffects({}, () => collectCompositeMembers({cliVersion:"1.0.0",workspaceRoot:root, + profileName:"synthetic",profileTtlSeconds:1,members:[{id:"leaf",workspace:root,profile:"synthetic",transport:"local"}]})); + expect(members[0]?.error).toMatch(/No cached member status/); + expect(diffEffects(before,await snapshot(root))).toEqual([]); + } finally {await rm(root,{recursive:true,force:true});} +}); From bb1015ebcff3d29f60f0418d2e2cfc87858537f8 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:21:19 +0000 Subject: [PATCH 16/19] test: qualify offline usefulness, retained snapshots and adapter refusal --- docs/testing-invariants.md | 6 +++--- .../invariants/i7-effects-containment.test.ts | 21 +++++++++++++++++-- test/read-effect-policy.test.ts | 16 +++++++++++++- 3 files changed, 37 insertions(+), 6 deletions(-) diff --git a/docs/testing-invariants.md b/docs/testing-invariants.md index e8b109dd..b89031b3 100644 --- a/docs/testing-invariants.md +++ b/docs/testing-invariants.md @@ -10,13 +10,13 @@ The report records input-byte and parser hashes, runner and Node versions. It ex `test/helpers/effects.ts` records file bytes in base64, permission bits, directories and symlink targets without following links. Explicit manifest paths record complete parsed claims as well as original bytes. With `git: true`, the snapshot also records the staged index (semantic entries and raw bytes), refs and symbolic HEAD; the filesystem tree includes raw Git metadata. Locks under the fixture root are included. Filesystem atime, mtime, ctime and birthtime are not recorded; all listed content and permission fields are compared exactly. There are no default path exclusions. A caller may exclude only an exact file or symlink path with a nonempty reason; directories are always traversed and manifest claims cannot be excluded. Compare snapshots with `diffEffects`; unknown changed paths remain visible. This is an isolated filesystem observer, not a syscall/network/process tracer. -## Expected failures +## Invariant cases -The invariant tests use synthetic fixtures and no live targets. Each expected-failure test has an adjacent ordinary test that checks the exact current defect, so a broken setup cannot masquerade as an expected failure. A product fix must remove that marker in the same change: an unexpected pass fails CI. Do not replace the marker with skip or todo. +The invariant tests use synthetic fixtures and no live targets. I2 now uses ordinary regression tests; I5 remains an expected failure. Each expected-failure test has an adjacent ordinary test that checks the exact current defect, so a broken setup cannot masquerade as an expected failure. A product fix must remove that marker in the same change: an unexpected pass fails CI. Do not replace the marker with skip or todo. | Invariant | Case | Observed defect | | --- | --- | --- | -| I2 | `read_missing_git_preserves_cache` | Fetch removes an existing incomplete cache directory and its sentinel before a failing local clone. | +| I2 | `read_missing_git_preserves_cache` | Fixed: an incomplete cache checkout is preserved and refuses implicit repair. | | I5 | `stale_merge_metadata_rejected_in_all_paths` | Preview accepts unchanged source with stale contribution metadata while apply rejects the contribution. | An unreachable source during pin preflight produces a warning by design, not a defect: it does not prove a new artifact collision. The existing pin-preflight tests retain that intended behavior. diff --git a/test/invariants/i7-effects-containment.test.ts b/test/invariants/i7-effects-containment.test.ts index 3149ee11..ed2708f6 100644 --- a/test/invariants/i7-effects-containment.test.ts +++ b/test/invariants/i7-effects-containment.test.ts @@ -1,4 +1,4 @@ -import { rm, writeFile } from "node:fs/promises"; +import { mkdir, rm, utimes, writeFile } from "node:fs/promises"; import { join, resolve } from "node:path"; import { expect, it } from "vitest"; import { readFixture } from "../helpers/read-effects.js"; @@ -9,7 +9,9 @@ it.each([false,true])("read_effects_match_explicit_policy_status_warm_%s", async const observed = await fixture.probe(); expect(observed.result.error).toBeUndefined(); expect(observed.result.stdout, observed.result.stderr).not.toBe(""); - expect(JSON.parse(observed.result.stdout).command).toBe("status"); + const report = JSON.parse(observed.result.stdout); + expect(report.command).toBe("status"); + if (warm) expect(report.targets[0].pendingCount).toBeGreaterThan(0); expect(observed.calls.filter(call => call.kind === "network")).toEqual([]); expect.soft(observed.calls.filter(call => /\b(fetch|clone|ls-remote)\b/.test(JSON.stringify(call.args)))).toEqual([]); expect.soft(observed.changes).toEqual([]); @@ -87,3 +89,18 @@ it("read_effects_match_explicit_policy_explicit_refresh", async () => { expect(observed.calls.filter(call => call.kind === "network")).toEqual([]); } finally { await fixture.dispose(); } }, 30_000); + +it("read_never_evicts_snapshot_warm_cache", async () => { + const fixture = await readFixture(true); + try { + await mkdir(join(fixture.cacheRoot,"synthetic-checkout/.git"),{recursive:true}); + for (const suffix of ["aaaaaaaaaaaa","bbbbbbbbbbbb","cccccccccccc","dddddddddddd"]) { + const dir = join(fixture.cacheRoot,`synthetic-checkout-${suffix}`); + await mkdir(dir); await writeFile(join(dir,"sentinel"),"recovery evidence"); + } + const observed = await fixture.probe([],process.env.SYNTHETIC_READ_CLI); + expect(observed.result.stdout, observed.result.stderr).not.toBe(""); + expect(JSON.parse(observed.result.stdout).command).toBe("status"); + expect(observed.changes).toEqual([]); + } finally {await fixture.dispose();} +},30_000); diff --git a/test/read-effect-policy.test.ts b/test/read-effect-policy.test.ts index 8e20f6aa..06c9119a 100644 --- a/test/read-effect-policy.test.ts +++ b/test/read-effect-policy.test.ts @@ -1,4 +1,4 @@ -import { mkdtemp, rm } from "node:fs/promises"; +import { mkdtemp, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { expect, it } from "vitest"; @@ -6,6 +6,7 @@ import { withReadEffects, isObservation, readEffectPolicy } from "../src/effects import { createGitSnapshotLease, pruneGitCache } from "../src/source/cache.js"; import { maybeCheckForUpdate } from "../src/cli/update-check.js"; import { collectCompositeMembers } from "../src/profile/members.js"; +import { resolveAdapter } from "../src/adapters/resolve.js"; import { diffEffects, snapshot } from "./helpers/effects.js"; it("preserves context across asynchronous work and restores the caller scope", async () => { @@ -48,3 +49,16 @@ it("does not invoke or cache an uncached composite member during observation", a expect(diffEffects(before,await snapshot(root))).toEqual([]); } finally {await rm(root,{recursive:true,force:true});} }); + +it("refuses unknown adapter effects before evaluating the module", async () => { + const root = await mkdtemp(join(tmpdir(),"synthetic-adapter-")); + try { + const module = join(root,"adapter.mjs"); + await writeFile(module, `import {writeFileSync} from "node:fs";writeFileSync(${JSON.stringify(join(root,"side-effect"))},"unexpected");export default {};`); + const before = await snapshot(root); + await withReadEffects({},async () => { + await expect(resolveAdapter({adapterModule:module,allowAdapterCode:true})).rejects.toThrow(/Observation refuses unqualified adapter/); + }); + expect(diffEffects(before,await snapshot(root))).toEqual([]); + } finally {await rm(root,{recursive:true,force:true});} +}); From a7edab138632dc4f600cb2732e75a8e2bc07836e Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:23:32 +0000 Subject: [PATCH 17/19] test: trigger snapshot pruning with a newer synthetic source revision --- docs/read-effects.md | 2 +- test/invariants/i7-effects-containment.test.ts | 6 ++++++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/read-effects.md b/docs/read-effects.md index 94194628..adf3eb80 100644 --- a/docs/read-effects.md +++ b/docs/read-effects.md @@ -12,6 +12,6 @@ Diagnostics consumers of the versioned `status --json` protocol inherit this pol ## Evidence and limits -The B0a effects helper is reused from PR #201; this PR is based on that branch. Before the product changes, synthetic status fixtures reproduced clone/fetch/tag queries, persistent cache leases and version-index writes, and removal of a sentinel from an incomplete checkout. A separately isolated legacy-launcher probe reproduced one implicit build on a status invocation with a dummy builder. That launcher was unversioned: the replacement above establishes a source-owned implementation without copying host-specific defaults into public source. +The B0a effects helper is reused from PR #201; this PR is based on that branch. Before the product changes, synthetic status fixtures reproduced clone/fetch/tag queries, persistent cache leases and version-index writes, global pruning when a newer source commit creates a snapshot, and removal of a sentinel from an incomplete checkout. A separately isolated legacy-launcher probe reproduced one implicit build on a status invocation with a dummy builder. That launcher was unversioned: the replacement above establishes a source-owned implementation without copying host-specific defaults into public source. The fixture snapshots synthetic HOME, workspace, cache, Git metadata and temp before/after each invocation. A child preload records process calls and rejects Node network APIs; only its exact evidence file is excluded from tree comparison. Tests cover cold/warm/offline/refused reads, a diagnostics protocol consumer, wrapper admission, and explicitly bounded refresh writes. External Git network access is checked through command arguments; this is an application-boundary trace, not a kernel syscall sandbox. Concurrent refresh/prune versus a lease-free observer remains a separate cache-lifecycle qualification concern: observation may report missing evidence but cannot repair or delete it. diff --git a/test/invariants/i7-effects-containment.test.ts b/test/invariants/i7-effects-containment.test.ts index ed2708f6..1fedca0a 100644 --- a/test/invariants/i7-effects-containment.test.ts +++ b/test/invariants/i7-effects-containment.test.ts @@ -1,3 +1,4 @@ +import { execFileSync } from "node:child_process"; import { mkdir, rm, utimes, writeFile } from "node:fs/promises"; import { join, resolve } from "node:path"; import { expect, it } from "vitest"; @@ -98,6 +99,11 @@ it("read_never_evicts_snapshot_warm_cache", async () => { const dir = join(fixture.cacheRoot,`synthetic-checkout-${suffix}`); await mkdir(dir); await writeFile(join(dir,"sentinel"),"recovery evidence"); } + // A newer source commit makes the old reader materialize a snapshot and run global pruning. + const source = join(fixture.root,"source"); + await writeFile(join(source,"revision"),"new revision"); + execFileSync("git",["-C",source,"add","revision"]); + execFileSync("git",["-C",source,"commit","-m","synthetic revision"]); const observed = await fixture.probe([],process.env.SYNTHETIC_READ_CLI); expect(observed.result.stdout, observed.result.stderr).not.toBe(""); expect(JSON.parse(observed.result.stdout).command).toBe("status"); From 6389ee810ba114ffe3102c5dbd8ef8a716e2e326 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:37:21 +0000 Subject: [PATCH 18/19] test: preserve legacy status reporting with uncached version metadata --- test/cli-verb-redesign.test.ts | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/test/cli-verb-redesign.test.ts b/test/cli-verb-redesign.test.ts index 68fb7fa2..13d161ce 100644 --- a/test/cli-verb-redesign.test.ts +++ b/test/cli-verb-redesign.test.ts @@ -1,3 +1,4 @@ +import { diffEffects, snapshot } from "./helpers/effects.js"; import { execFile } from "node:child_process"; import { chmod, mkdtemp, mkdir, readFile, readdir, rm, stat, utimes, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; @@ -946,11 +947,18 @@ describe("CLI verb redesign", () => { it("reports correlated released state before target identity migration", async () => { const state = await releasedTargetStateFixture(); - - const status = JSON.parse((await runCli([ + const before = await snapshot(state.workspace); + const result = await runCli([ "status", "--adapter", "codex", "--installation-type", "local", "--target-root", state.workspace, "--json", - ])).stdout); + ]).catch((error: { code: number; stdout: string; stderr: string }) => { + // Observation reports unavailable version metadata without populating a cache. + expect(error.code, error.stdout + error.stderr).toBe(1); + return error; + }); + const status = JSON.parse(result.stdout); + expect(status.targets[0].packages[0].error).toMatch(/No cached version index.*--refresh/); + expect(diffEffects(before, await snapshot(state.workspace))).toEqual([]); expect(status.targets[0]).toMatchObject({ manifestEntryCount: 1, From 667d6d23ca50ab3d9b842ff622811603944ad627 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:54:10 +0000 Subject: [PATCH 19/19] fix: clarify cache freshness and incomplete checkout recovery --- docs/read-effects.md | 12 ++++++++- src/adapters/resolve.ts | 2 +- src/cli/index.ts | 2 +- src/cli/update-check.ts | 2 +- src/profile/members.ts | 2 +- src/registry/client.ts | 2 +- src/resolve/graph.ts | 2 +- src/source/cache.ts | 2 +- src/source/git.ts | 26 +++++++++++++++----- src/version/policy.ts | 2 +- test/invariants/i2-no-loss.test.ts | 39 +++++++++++++++++++++++++++--- test/read-effect-policy.test.ts | 8 +++++- 12 files changed, 81 insertions(+), 20 deletions(-) diff --git a/docs/read-effects.md b/docs/read-effects.md index adf3eb80..81c954e7 100644 --- a/docs/read-effects.md +++ b/docs/read-effects.md @@ -2,7 +2,17 @@ `status` now observes local state and existing caches by default, regardless of cache TTL. `status --refresh` explicitly permits cache population, source fetches, snapshot maintenance, version discovery and composite member refresh. `--offline` wins over `--refresh`. Missing or stale evidence remains visible in the status protocol instead of causing an implicit refresh. Useful cached Git snapshots and local sources still support pending-work inspection; an absent cached snapshot returns a named refresh requirement. -The AsyncLocalStorage scope in `src/effects/read-policy.ts` centralizes this distinction across graph sources, registry/version indexes, member reports, and cache writers. Observation never creates cache leases or maintenance locks and does not prune snapshots. Incomplete checkout directories are preserved even during refresh: repair is a separate explicit operation. Git status disables optional index locks. The optional update notifier does not fetch or persist on status reads. +## Consumer behavior change and cache refresh responsibility + +Previously, a status read could refresh expired member and package-version caches automatically. It no longer does. The default `fleet-diagnostics` wrapper forwards an observation to `status`; after the member or version TTL expires it therefore shows stale evidence (`STALE`, or a degraded status derived from stale package metadata) until an explicit refresh succeeds. Repeated diagnostics reads do not make those caches fresh. Missing caches stay missing and are reported as unavailable. + +The operator or caller requesting fresh evidence now owns the refresh: run `agentwheel status` with the **same workspace/fleet and profile selectors** plus `--refresh`, or explicitly opt into the diagnostics caller's existing `--refresh` option. The refresh path updates the member-report and version-index caches; subsequent default reads consume those caches without extending their freshness. No background refresher, timer, or new automated refresh owner is added here. Any change to fleet-control consumers or their refresh schedule is a separate maintainer decision and follow-up; this PR does not change fleet-control. + +For example, `agentwheel status --fleet example-fleet --profile example-profile --refresh --json` refreshes that selected scope. `--offline` must be omitted when refreshing. Existing mutating commands retain their own cache behavior; this change concerns the read route. + +## Effect policy + +The AsyncLocalStorage scope in `src/effects/read-policy.ts` centralizes this distinction across graph sources, registry/version indexes, member reports, and cache writers. Observation never creates cache leases or maintenance locks and does not prune snapshots. Incomplete checkout directories are preserved even during refresh: repair is a separate explicit operation. The error identifies the exact checkout directory to move into a new backup location outside its cache directory. Confirm the original checkout path is absent, then rerun the same scoped command with `--refresh` to clone it again. Do not overwrite existing backups. No repair command or automatic move/removal is provided. Git status disables optional index locks. The optional update notifier does not fetch or persist on status reads. Observation supports built-in local targets and cached composite reports. Unqualified programmatic adapters, source drivers other than local/Git, and direct remote transports refuse before execution; explicit refresh retains their existing admission and execution paths. This deliberately avoids promising zero effects for arbitrary executable code. Other CLI read/preview verbs have not yet been qualified by this batch. diff --git a/src/adapters/resolve.ts b/src/adapters/resolve.ts index 0352a97c..b696dc9e 100644 --- a/src/adapters/resolve.ts +++ b/src/adapters/resolve.ts @@ -1,5 +1,5 @@ -import { isObservation } from "../effects/read-policy.js"; import { resolve } from "node:path"; +import { isObservation } from "../effects/read-policy.js"; import type { AdapterConfig } from "../model/adapter.js"; import { loadAdapterConfig } from "../model/adapter.js"; import { getAdapter } from "./index.js"; diff --git a/src/cli/index.ts b/src/cli/index.ts index 5ebcbba1..8d597f02 100644 --- a/src/cli/index.ts +++ b/src/cli/index.ts @@ -1,4 +1,3 @@ -import { withReadEffects } from "../effects/read-policy.js"; import { createHash } from "node:crypto"; import { existsSync } from "node:fs"; import { mkdir, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises"; @@ -6,6 +5,7 @@ import { homedir, tmpdir } from "node:os"; import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path"; import { fileURLToPath } from "node:url"; import { Command } from "commander"; +import { withReadEffects } from "../effects/read-policy.js"; import { resolveAdapter } from "../adapters/resolve.js"; import { installRootForAdapterInstallationType, diff --git a/src/cli/update-check.ts b/src/cli/update-check.ts index 6edbdb0e..bb202b04 100644 --- a/src/cli/update-check.ts +++ b/src/cli/update-check.ts @@ -1,7 +1,7 @@ -import { isObservationInvocation } from "../effects/read-policy.js"; import { mkdir, readFile, writeFile } from "node:fs/promises"; import { homedir } from "node:os"; import { dirname, join } from "node:path"; +import { isObservationInvocation } from "../effects/read-policy.js"; const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; const DEFAULT_TIMEOUT_MS = 300; diff --git a/src/profile/members.ts b/src/profile/members.ts index d6518a97..7d94442f 100644 --- a/src/profile/members.ts +++ b/src/profile/members.ts @@ -1,9 +1,9 @@ -import { isObservation } from "../effects/read-policy.js"; import { execFile } from "node:child_process"; import { readFile } from "node:fs/promises"; import { join, resolve } from "node:path"; import { promisify } from "node:util"; import { z } from "zod"; +import { isObservation } from "../effects/read-policy.js"; import type { WorkspaceProfileMember } from "../model/workspace.js"; import { statusReportSchema, diff --git a/src/registry/client.ts b/src/registry/client.ts index 873e6c2a..d75241a3 100644 --- a/src/registry/client.ts +++ b/src/registry/client.ts @@ -1,8 +1,8 @@ -import { isObservation } from "../effects/read-policy.js"; import { readFile, rm, stat } from "node:fs/promises"; import { homedir } from "node:os"; import { dirname, join, resolve } from "node:path"; import { fileURLToPath } from "node:url"; +import { isObservation } from "../effects/read-policy.js"; import { registryCacheSchema, registryIndexSchema, type RegistryCache, type RegistryEntry } from "../model/registry.js"; import { normalizeArtifactSelectors } from "../model/selection.js"; import { readMergedWorkspaceConfig } from "../model/workspace.js"; diff --git a/src/resolve/graph.ts b/src/resolve/graph.ts index d44172f7..d5f5ae1f 100644 --- a/src/resolve/graph.ts +++ b/src/resolve/graph.ts @@ -1,7 +1,7 @@ -import { isObservation } from "../effects/read-policy.js"; import { createHash } from "node:crypto"; import { readdir, readFile, stat } from "node:fs/promises"; import { basename, extname, join } from "node:path"; +import { isObservation } from "../effects/read-policy.js"; import { extractOpenPackIncludeSelectors, parseOpenPackIncludeSelector } from "../compose/markdown.js"; import type { Artifact, PackageItemRequire, PackageItemSuggest } from "../model/artifact.js"; import { artifactTypeSchema } from "../model/artifact.js"; diff --git a/src/source/cache.ts b/src/source/cache.ts index b8124ff8..96a8760d 100644 --- a/src/source/cache.ts +++ b/src/source/cache.ts @@ -1,7 +1,7 @@ -import { requireRefreshEffect } from "../effects/read-policy.js"; import { randomUUID } from "node:crypto"; import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises"; import { dirname, join } from "node:path"; +import { requireRefreshEffect } from "../effects/read-policy.js"; import { isIgnoredGeneratedEntry, pathExists } from "../utils/fs.js"; const snapshotNamePattern = /^(.*)-([0-9a-f]{12})$/i; diff --git a/src/source/git.ts b/src/source/git.ts index 2514130c..ee047775 100644 --- a/src/source/git.ts +++ b/src/source/git.ts @@ -1,9 +1,9 @@ -import { isObservation } from "../effects/read-policy.js"; import { execFile } from "node:child_process"; import { mkdir, rename, rm, stat } from "node:fs/promises"; import { homedir } from "node:os"; import { basename, dirname, join, resolve, sep } from "node:path"; import { promisify } from "node:util"; +import { isObservation } from "../effects/read-policy.js"; import { readPackageManifest } from "../model/package.js"; import { hashPath, @@ -46,7 +46,7 @@ export class GitSourceDriver implements SourceDriver { async fetch(resolved: ResolvedSource): Promise { if (isObservation()) return this.observe(resolved); if (await pathExists(resolved.resolvedPath) && !(await pathExists(join(resolved.resolvedPath, ".git")))) { - throw new Error("Incomplete cached checkout preserved; explicit cache repair is required before refresh."); + throw incompleteCheckoutError(resolved.resolvedPath); } return withFilesystemLock(`${resolved.resolvedPath}.lock`, resolved.cacheLockTimeoutMs ?? 30_000, async () => { const parsed = parseGitSource(resolved.source); @@ -59,7 +59,7 @@ export class GitSourceDriver implements SourceDriver { throw new Error(`Frozen lock requires cached git checkout at ${resolved.resolvedPath}`); } if (await pathExists(resolved.resolvedPath)) { - throw new Error("Incomplete cached checkout preserved; explicit cache repair is required before refresh."); + throw incompleteCheckoutError(resolved.resolvedPath); } await git([...(await gitAuthArguments(parsed.url)), "clone", "--no-checkout", parsed.url, resolved.resolvedPath]); await assertOwnedByCurrentUser(resolved.resolvedPath); @@ -112,11 +112,12 @@ export class GitSourceDriver implements SourceDriver { private async observe(resolved: ResolvedSource): Promise { if (!(await pathExists(join(resolved.resolvedPath, ".git")))) { - throw new Error("Observation requires a complete cached Git checkout; existing bytes were preserved. Use --refresh for an absent cache, or explicitly repair an incomplete checkout."); + if (await pathExists(resolved.resolvedPath)) throw incompleteCheckoutError(resolved.resolvedPath); + throw new Error(`Observation requires a cached Git checkout at ${JSON.stringify(resolved.resolvedPath)}; rerun the same scoped command with --refresh to create an absent cache.`); } const parsed = parseGitSource(resolved.source); const commit = await resolveCommit(resolved.resolvedPath, resolved.requestedRef ?? parsed.ref ?? "HEAD"); - const snapshot = join(dirname(resolved.resolvedPath), `${basename(resolved.resolvedPath)}-${commit.slice(0,12)}`); + const snapshot = snapshotPathFor(resolved.resolvedPath, commit); const packageRoot = parsed.subpath ? join(snapshot, parsed.subpath) : snapshot; if (!(await isDirectory(packageRoot))) { throw new Error("Observation requires an existing cached Git snapshot; use --refresh to materialize it."); @@ -184,8 +185,21 @@ async function resolveCommit(checkoutPath: string, ref: string): Promise throw lastError; } +function incompleteCheckoutError(checkoutPath: string): Error { + return new Error( + `Incomplete cached checkout preserved at ${JSON.stringify(checkoutPath)}. ` + + `Manual repair: move this exact directory to a new backup location outside the cache directory ${JSON.stringify(dirname(checkoutPath))}; do not overwrite an existing backup. ` + + "Confirm the original directory is absent, then rerun the same scoped command with --refresh to clone it again. " + + "Agentwheel does not move or remove the directory automatically.", + ); +} + +function snapshotPathFor(checkoutPath: string, commit: string): string { + return join(dirname(checkoutPath), `${basename(checkoutPath)}-${commit.slice(0, 12)}`); +} + async function snapshotCommit(checkoutPath: string, commit: string): Promise<{ path: string; created: boolean }> { - const snapshotPath = join(dirname(checkoutPath), `${basename(checkoutPath)}-${commit.slice(0, 12)}`); + const snapshotPath = snapshotPathFor(checkoutPath, commit); if (await pathExists(snapshotPath)) return { path: snapshotPath, created: false }; const tempPath = join(dirname(checkoutPath), `${basename(snapshotPath)}.tmp-${process.pid}-${Date.now()}`); const tempIndexPath = `${tempPath}.index`; diff --git a/src/version/policy.ts b/src/version/policy.ts index 5fc71079..70cb99f1 100644 --- a/src/version/policy.ts +++ b/src/version/policy.ts @@ -1,10 +1,10 @@ -import { isObservation } from "../effects/read-policy.js"; import { execFile } from "node:child_process"; import { readFile } from "node:fs/promises"; import { join, resolve } from "node:path"; import { promisify } from "node:util"; import { parse as parseJsonc } from "jsonc-parser"; import { z } from "zod"; +import { isObservation } from "../effects/read-policy.js"; import type { WorkspacePackage } from "../model/workspace.js"; import { readPackageManifest } from "../model/package.js"; import { compareSemverStrings, parseSemver, satisfiesVersionRange } from "../resolve/semver.js"; diff --git a/test/invariants/i2-no-loss.test.ts b/test/invariants/i2-no-loss.test.ts index 577ec2d4..7074a935 100644 --- a/test/invariants/i2-no-loss.test.ts +++ b/test/invariants/i2-no-loss.test.ts @@ -1,11 +1,15 @@ -import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; +import { mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join, relative } from "node:path"; import { expect, it } from "vitest"; +import { withReadEffects } from "../../src/effects/read-policy.js"; import { GitSourceDriver } from "../../src/source/git.js"; +import { releaseGitSnapshotLease } from "../../src/source/cache.js"; +import { pathExists } from "../../src/utils/fs.js"; +import { readFixture } from "../helpers/read-effects.js"; import { diffEffects, snapshot } from "../helpers/effects.js"; -async function observeIncompleteCacheRead() { +async function observeIncompleteCacheRead(observe = false) { const root = await mkdtemp(join(tmpdir(), "invariant-i2-")); try { const driver = new GitSourceDriver(); @@ -14,9 +18,9 @@ async function observeIncompleteCacheRead() { await mkdir(resolved.resolvedPath, { recursive: true }); await writeFile(join(resolved.resolvedPath, "sentinel"), "preserve me"); const before = await snapshot(root); - const failure = await driver.fetch(resolved).then(() => undefined, error => error); + const failure = await withReadEffects({ refresh: !observe }, () => driver.fetch(resolved)).then(() => undefined, error => error); const cachePath = relative(root, resolved.resolvedPath); - return { failure, effects: diffEffects(before, await snapshot(root)), + return { failure, checkoutPath: resolved.resolvedPath, effects: diffEffects(before, await snapshot(root)), removedPaths: [`tree:${cachePath}`, `tree:${cachePath}/sentinel`] }; } finally { await rm(root, { recursive: true, force: true }); } @@ -35,3 +39,30 @@ it("read_missing_git_preserves_cache_requires_explicit_repair", async () => { expect(String(observed.failure)).toMatch(/Incomplete cached checkout preserved/); expect(observed.effects).toEqual([]); }); + +it.each([false, true])("incomplete_cache_error_names_manual_move_observe_%s", async observe => { + const observed = await observeIncompleteCacheRead(observe); + expect(observed.failure).toBeInstanceOf(Error); + const message = String(observed.failure); + expect(message).toContain(JSON.stringify(observed.checkoutPath)); + expect(message).toMatch(/Manual repair: move this exact directory.*backup location outside the cache directory/); + expect(message).toMatch(/Confirm the original directory is absent, then rerun the same scoped command with --refresh/); + expect(observed.effects).toEqual([]); +}); + +it("manual_backup_allows_refresh_without_losing_incomplete_checkout_evidence", async () => { + const fixture = await readFixture(true); + try { + await rm(join(fixture.resolved.resolvedPath, ".git"), { recursive: true }); + await writeFile(join(fixture.resolved.resolvedPath, "sentinel"), "preserved evidence"); + const driver = new GitSourceDriver(); + await expect(withReadEffects({refresh:true}, () => driver.fetch(fixture.resolved))).rejects.toThrow(JSON.stringify(fixture.resolved.resolvedPath)); + const backup = join(fixture.root, "checkout-backup"); + // This is the explicit operator step, outside the cache, against a new destination. + await rename(fixture.resolved.resolvedPath, backup); + const refreshed = await withReadEffects({refresh:true}, () => driver.fetch(fixture.resolved)); + await releaseGitSnapshotLease(refreshed.cacheLeasePath); + expect(await readFile(join(backup, "sentinel"), "utf8")).toBe("preserved evidence"); + expect(await pathExists(join(fixture.resolved.resolvedPath, ".git"))).toBe(true); + } finally { await fixture.dispose(); } +}); diff --git a/test/read-effect-policy.test.ts b/test/read-effect-policy.test.ts index 06c9119a..bd63b371 100644 --- a/test/read-effect-policy.test.ts +++ b/test/read-effect-policy.test.ts @@ -2,7 +2,7 @@ import { mkdtemp, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { expect, it } from "vitest"; -import { withReadEffects, isObservation, readEffectPolicy } from "../src/effects/read-policy.js"; +import { withReadEffects, isObservation, readEffectPolicy, isObservationInvocation } from "../src/effects/read-policy.js"; import { createGitSnapshotLease, pruneGitCache } from "../src/source/cache.js"; import { maybeCheckForUpdate } from "../src/cli/update-check.js"; import { collectCompositeMembers } from "../src/profile/members.js"; @@ -62,3 +62,9 @@ it("refuses unknown adapter effects before evaluating the module", async () => { expect(diffEffects(before,await snapshot(root))).toEqual([]); } finally {await rm(root,{recursive:true,force:true});} }); + +it("conservatively suppresses the notifier when status is an argument value", () => { + expect(isObservationInvocation(["node", "cli", "add", "status"])).toBe(true); + expect(isObservationInvocation(["node", "cli", "status", "--refresh"])).toBe(false); + expect(isObservationInvocation(["node", "cli", "status", "--refresh", "--offline"])).toBe(true); +});