From 3924eb61967385fdbe65ebfbfca050ea2e8ed0b6 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Fri, 13 Nov 2026 10:33:20 -0700 Subject: [PATCH 01/61] fix(oracle-gaps): retire a batch's copies from Vitest's state A check runs each mutant in a new copy of its test file. Vitest's state kept every file and test task it ever ran (filesMap by path, idMap by task id), so a check held every test of every copy: about 377k test cases on a four-file suite, which exhausted a 2 GB heap. Once a batch's units are plain data, its copies leave the state: their stale idMap entries go first (shape-guarded), then clearFiles replaces each path's file entry. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index a1139a1c..502c17fc 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -1256,10 +1256,33 @@ export default async (env) => { } } finally { for (const copy of copies) globalThis.__oracleGapsCopies.delete(copy) + retireCopies(context, copies) rmSync(capture, { force: true }) } } + /** + * Drops a batch's copies from Vitest's state once their units are plain + * data. Each copy is a new file, and the state keeps every file and test + * task it ever ran: `filesMap` by path and `idMap` by task id, so a check + * holds every test of every copy (about 377k test cases in the four-file + * repro, which runs out of a 2 GB heap). `clearFiles` (Vitest 4.1 and 5.1 + * alike) replaces each path's file entry, but it leaves the copies' test + * tasks in `idMap`, so those go first. The map shapes are guarded: a + * Vitest that changes them throws here rather than leaking quietly. + */ + function retireCopies(context, copies) { + const state = context.state + if (!(state?.filesMap instanceof Map) || !(state?.idMap instanceof Map)) + throw new Error( + `oracle-gaps: this Vitest keeps no filesMap or idMap in its state, so a check cannot retire its copies`, + ) + const gone = new Set(copies) + for (const [id, task] of state.idMap) + if (gone.has(task.file?.filepath ?? task.filepath)) state.idMap.delete(id) + state.clearFiles(context.getRootProject(), copies) + } + async function check(options, store, log = console.error) { const authored = options.mutants ? loadAuthored(options.mutants) : [] seedVariable = `${options.envPrefix}_SEED` From 46dfd3e39ab21d64cfc9b3990b6940ad644204ec Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Fri, 13 Nov 2026 11:31:59 -0700 Subject: [PATCH 02/61] test(oracle-gaps): bounded-retention law after each batch The gap CLI's e2e driver sets ORACLE_GAPS_TEST_RETENTION on each run and records one line per batch: the count of Vitest state entries (filesMap, pathsSet, idMap) and Vite module nodes that still name the batch's retired copies. The law: each count is 0 after retirement. This commit adds the hook and the law, not the fix, so CI records the RED on the parent code. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 32 ++++++++++++++++ .../gap-report-oracle.property.test.mjs | 38 +++++++++++++++++-- 2 files changed, 67 insertions(+), 3 deletions(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index 502c17fc..05839299 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -1281,6 +1281,38 @@ export default async (env) => { for (const [id, task] of state.idMap) if (gone.has(task.file?.filepath ?? task.filepath)) state.idMap.delete(id) state.clearFiles(context.getRootProject(), copies) + retiredEntries(context, copies) + } + + // The test hook (ORACLE_GAPS_TEST_RETENTION, a file path): after a batch's + // copies are retired, one line counts the state entries and module nodes + // that still name a retired copy. The e2e oracle's bounded-retention law + // reads it: each count is 0. + function retiredEntries(context, copies) { + const file = process.env.ORACLE_GAPS_TEST_RETENTION + if (!file) return + const gone = new Set(copies) + const named = (path) => gone.has(path) + const { filesMap, idMap, pathsSet } = context.state + let tasks = 0 + for (const task of idMap.values()) + if (named(task.file?.filepath ?? task.filepath)) tasks += 1 + let nodes = 0 + for (const environment of Object.values( + context.getRootProject().vite?.environments ?? {}, + )) + for (const copy of gone) + nodes += environment.moduleGraph?.fileToModulesMap.get(copy)?.size ?? 0 + appendFileSync( + file, + `${JSON.stringify({ + copies: copies.length, + filesMap: [...filesMap.keys()].filter(named).length, + pathsSet: [...pathsSet].filter(named).length, + idMap: tasks, + moduleNodes: nodes, + })}\n`, + ) } async function check(options, store, log = console.error) { diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 86cc8ccf..5fe7342c 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -647,13 +647,25 @@ function runCli(dir, files, how = {}) { writeFixture(dir, files) const before = new Set(filesUnder(dir)) const { args, out } = cliArgs(dir, files, how) + // The retention hook (ORACLE_GAPS_TEST_RETENTION): one line per batch, + // written beside the run's own temporary files, not in the package. + const hook = join( + mkdtempSync(join(tmpdir(), `gap-retention-`)), + `retention.jsonl`, + ) const child = spawnSync(process.execPath, args, { cwd: repo, encoding: `utf8`, timeout: 300_000, maxBuffer: 64 * 1024 * 1024, - env: cleanEnv(), + env: { ...cleanEnv(), ORACLE_GAPS_TEST_RETENTION: hook }, }) + const retention = existsSync(hook) + ? readFileSync(hook, `utf8`) + .split(`\n`) + .filter(Boolean) + .map((line) => JSON.parse(line)) + : [] const run = readRun( dir, out, @@ -667,7 +679,7 @@ function runCli(dir, files, how = {}) { .split(`\n`) .find((line) => line.startsWith(` replay: `)) ?.slice(` replay: `.length) - return { ...run, strayWrites: strays(dir, before), replay } + return { ...run, strayWrites: strays(dir, before), replay, retention } } /** @@ -1600,10 +1612,11 @@ async function driver(plan, observe) { cli: plan.cliPath === `spaced` ? copy : here, ...configArgs(plan), } - const { replay, ...cli } = runCli(dir, files, how) + const { replay, retention, ...cli } = runCli(dir, files, how) // How many units were computed or reused says how the result was // produced, not what it is, so it is not observed. observe(`cli`, { ...cli, evidence: undefined }) + observe(`retention`, retention) // A failing owner's replay, run as the author would run it (law 3). if (plan.fault === `brokenOwner`) observe(`replay`, { command: replay, ran: replayed(dir, replay) }) @@ -2170,6 +2183,25 @@ function check(plan, observations, expected) { ) const stream = streamBreach(`cli`, cli, expected, plan) if (stream) return stream + // Bounded retention (the register's C entry): once a batch's copies are + // retired, Vitest's filesMap, pathsSet, and idMap and Vite's module graph + // name none of them, so each count the hook reports is 0. + const retention = observations.find( + (o) => o.checkpoint === `retention`, + )?.value + const held = (retention ?? []).find( + (line) => line.filesMap + line.pathsSet + line.idMap + line.moduleNodes > 0, + ) + if (held) + return violation( + `retention`, + `a batch left its retired copies in Vitest or Vite state: ${JSON.stringify(held)}`, + `bounded retention`, + { + actual: held, + expected: { filesMap: 0, pathsSet: 0, idMap: 0, moduleNodes: 0 }, + }, + ) // Through the daemon, each check streams the same kinds of line, and a // completed one ends with its done line (law 15). The state of each step // differs, so its verdict and counts are judged by law 9's comparison. From 84a1085eb1505d4de5b2c62b1804a0798d0057a9 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Fri, 13 Nov 2026 12:04:57 -0700 Subject: [PATCH 03/61] fix(oracle-gaps): retire a copy's Vitest and Vite state, not only its file entry Vitest's clearFiles replaces a copy's file entry, and leaves its path in pathsSet, one placeholder task in idMap, and Vite's module node and transform for the copy. The retention law (bounded retention, after each batch) fails on 46dfd3e in CI: each count is nonzero. retireCopies now removes the copy's filesMap key, pathsSet entry, and idMap tasks. retireModules invalidates each copy's module through Vite's API and removes it from every environment's graph maps. Both guard the shapes they touch and throw if one changes, so a Vitest or Vite that changes them fails loudly rather than leaking. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 115 +++++++++++++++++++------ 1 file changed, 91 insertions(+), 24 deletions(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index 05839299..1a63f923 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -1262,33 +1262,101 @@ export default async (env) => { } /** - * Drops a batch's copies from Vitest's state once their units are plain - * data. Each copy is a new file, and the state keeps every file and test - * task it ever ran: `filesMap` by path and `idMap` by task id, so a check - * holds every test of every copy (about 377k test cases in the four-file - * repro, which runs out of a 2 GB heap). `clearFiles` (Vitest 4.1 and 5.1 - * alike) replaces each path's file entry, but it leaves the copies' test - * tasks in `idMap`, so those go first. The map shapes are guarded: a - * Vitest that changes them throws here rather than leaking quietly. + * Removes a batch's copies from Vitest's state and from Vite's module + * graphs once their units are plain data (the register's C entry: the gap + * CLI keeps no Vitest or Vite state for a mutant copy after the copy's + * results are plain data). Each copy is a new file. Vitest keeps its path + * in `filesMap` and `pathsSet`, and the file and test tasks it ran in + * `idMap`, and Vite keeps a module node, with its transform, per copy. + * Vitest's `clearFiles` replaces the path's file entry only, and leaves + * `pathsSet` and the test tasks, so it is not used: each entry is removed. + * Every map touched is guarded, and a Vitest or Vite whose shape changes + * throws here rather than leaking quietly. During a run, Vitest holds the + * run's copies until it ends, so the in-run peak scales with the batch's + * share of copies, not with the suite. */ function retireCopies(context, copies) { - const state = context.state - if (!(state?.filesMap instanceof Map) || !(state?.idMap instanceof Map)) + const { filesMap, idMap, pathsSet } = context.state ?? {} + if ( + !(filesMap instanceof Map) || + !(idMap instanceof Map) || + !(pathsSet instanceof Set) + ) throw new Error( - `oracle-gaps: this Vitest keeps no filesMap or idMap in its state, so a check cannot retire its copies`, + `oracle-gaps: this Vitest keeps no filesMap, idMap, or pathsSet in its state, so a check cannot retire its copies`, ) const gone = new Set(copies) - for (const [id, task] of state.idMap) - if (gone.has(task.file?.filepath ?? task.filepath)) state.idMap.delete(id) - state.clearFiles(context.getRootProject(), copies) - retiredEntries(context, copies) + for (const [id, task] of idMap) + if (gone.has(task.file?.filepath ?? task.filepath)) idMap.delete(id) + for (const copy of copies) { + filesMap.delete(copy) + pathsSet.delete(copy) + } + const modulesRemoved = retireModules(context.getRootProject().vite, gone) + retiredEntries(context, copies, modulesRemoved) + } + + /** + * Removes the copies' module nodes from every environment's Vite graph. + * Each node is invalidated through Vite's API (which drops its transform), + * then removed from the graph's id, url, etag, and file maps, and from its + * neighbours' import sets. The graph's map shapes are guarded. + */ + function retireModules(server, gone) { + const environments = viteEnvironments(server) + let removed = 0 + for (const environment of environments) { + const graph = environment.moduleGraph + const { + urlToModuleMap, + idToModuleMap, + etagToModuleMap, + fileToModulesMap, + } = graph ?? {} + if ( + !(urlToModuleMap instanceof Map) || + !(idToModuleMap instanceof Map) || + !(etagToModuleMap instanceof Map) || + !(fileToModulesMap instanceof Map) || + typeof graph.invalidateModule !== `function` + ) + throw new Error( + `oracle-gaps: this Vite's module graph has no id, url, etag, or file maps, so a check cannot retire its copies`, + ) + for (const copy of gone) { + for (const mod of fileToModulesMap.get(copy) ?? []) { + removed += 1 + graph.invalidateModule(mod) + for (const imported of mod.importedModules) + imported.importers.delete(mod) + for (const importer of mod.importers) + importer.importedModules.delete(mod) + idToModuleMap.delete(mod.id) + urlToModuleMap.delete(mod.url) + if (mod.etag !== undefined) etagToModuleMap.delete(mod.etag) + } + fileToModulesMap.delete(copy) + } + } + return removed } - // The test hook (ORACLE_GAPS_TEST_RETENTION, a file path): after a batch's - // copies are retired, one line counts the state entries and module nodes - // that still name a retired copy. The e2e oracle's bounded-retention law - // reads it: each count is 0. - function retiredEntries(context, copies) { + // Vite's environments, each with its module graph. A Vite that exposes none + // would make the module step a silent no-op, so it throws here. + function viteEnvironments(server) { + const environments = Object.values(server?.environments ?? {}) + if (environments.length === 0 || environments.some((e) => !e?.moduleGraph)) + throw new Error( + `oracle-gaps: this Vitest exposes no Vite environments with module graphs, so a check cannot retire its copies' module nodes`, + ) + return environments + } + + // The test hook (ORACLE_GAPS_TEST_RETENTION, a file path): after each + // batch's copies are retired, one line counts the state entries and module + // nodes that still name a retired copy. The retention law reads it: each + // count is 0. + function retiredEntries(context, copies, modulesRemoved) { const file = process.env.ORACLE_GAPS_TEST_RETENTION if (!file) return const gone = new Set(copies) @@ -1298,11 +1366,9 @@ export default async (env) => { for (const task of idMap.values()) if (named(task.file?.filepath ?? task.filepath)) tasks += 1 let nodes = 0 - for (const environment of Object.values( - context.getRootProject().vite?.environments ?? {}, - )) + for (const environment of viteEnvironments(context.getRootProject().vite)) for (const copy of gone) - nodes += environment.moduleGraph?.fileToModulesMap.get(copy)?.size ?? 0 + nodes += environment.moduleGraph.fileToModulesMap.get(copy)?.size ?? 0 appendFileSync( file, `${JSON.stringify({ @@ -1311,6 +1377,7 @@ export default async (env) => { pathsSet: [...pathsSet].filter(named).length, idMap: tasks, moduleNodes: nodes, + modulesRemoved, })}\n`, ) } From ce46f4bf078468c58f3a81e029c5969adc0706cb Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Fri, 13 Nov 2026 14:20:59 -0700 Subject: [PATCH 04/61] test(oracle-gaps): the incremental violation names a cold run's error log When the cold run exits 3, its stack is in its error.log. The incremental violation named only the exit code, so a failure printed no stack. It now appends the error log the driver already reads for a run that exits 3. Co-authored-by: Isaac --- .../oracles/oracle-gaps/gap-report-oracle.property.test.mjs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 5fe7342c..6d0c48af 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -2103,7 +2103,7 @@ function incrementalCheck(observations) { ) return violation( `incremental`, - `after ${step}, the daemon's check exited ${daemon.exit} (${daemon.refusal ?? daemon.stderr ?? `no refusal`}) and the cold run exited ${cold.exit} (${cold.refusal ?? `no refusal`})`, + `after ${step}, the daemon's check exited ${daemon.exit} (${daemon.refusal ?? daemon.stderr ?? `no refusal`}) and the cold run exited ${cold.exit} (${cold.refusal ?? `no refusal`})${cold.exit === 3 && cold.stderr ? `; its error log: ${cold.stderr}` : ``}`, `incremental equals cold`, { actual: daemon, expected: cold }, ) From 2de2b9eab86e12ce09d894570ea36e164f1a1e22 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Fri, 13 Nov 2026 14:34:34 -0700 Subject: [PATCH 05/61] test(oracle-gaps): the incremental observation carries a cold run's error log ce46f4b appends cold.stderr to the incremental violation when the cold run exits 3, but the incremental observation's cold run had no stderr, so the message stayed empty. It now carries the run's stderr, with its error.log, when it exits 3, and only then: a completed run's stderr holds timings, which differ between two runs of one history. Co-authored-by: Isaac --- .../oracles/oracle-gaps/gap-report-oracle.property.test.mjs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 6d0c48af..38d9f334 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1330,6 +1330,11 @@ async function incremental(dir, plan, cli, copy, observe, states) { refusal: coldRun.refusal, report: coldRun.report, notes: coldRun.stream.notes, + // An internal error's stack (its error.log, which readRun reads + // for a run that exits 3), for the violation's message. Only + // then: a completed run's stderr holds timings, which differ + // between two runs of one history. + stderr: coldRun.exit === 3 ? coldRun.stderr : undefined, }, daemon: { exit: run.exit, From ca327dca8b7e439d51b96a613fadce189f7fe319 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Fri, 13 Nov 2026 15:57:34 -0700 Subject: [PATCH 06/61] fix(oracle-gaps): a replaced context leaves its maps; a cut-off run is not retired A replaced context stayed reachable through indexOf and contextSpecs, which were never cleared for it, so its Vitest and Vite state stayed too. replace now drops both entries. A run cut off by a hang is not retired: its worker may still send updates, and its context is replaced by the caller. Also: the etag map is cleaned by node identity (Vite keys it by the etag), and the retention observation is the count of batches left with a retired copy's state, which is deterministic, not the per-batch lines. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 13 +++++++-- .../gap-report-oracle.property.test.mjs | 27 ++++++++++--------- 2 files changed, 25 insertions(+), 15 deletions(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index 1a63f923..bf908276 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -1256,7 +1256,10 @@ export default async (env) => { } } finally { for (const copy of copies) globalThis.__oracleGapsCopies.delete(copy) - retireCopies(context, copies) + // A run cut off by a hang is still running: its worker may still send + // updates, so its state is not touched here. Its context is replaced + // by the caller (replace), which closes it and drops its state. + if (result !== undefined) retireCopies(context, copies) rmSync(capture, { force: true }) } } @@ -1333,7 +1336,9 @@ export default async (env) => { importer.importedModules.delete(mod) idToModuleMap.delete(mod.id) urlToModuleMap.delete(mod.url) - if (mod.etag !== undefined) etagToModuleMap.delete(mod.etag) + // Vite keys the etag map by the etag, whose value is the node. + for (const [etag, node] of etagToModuleMap) + if (node === mod) etagToModuleMap.delete(etag) } fileToModulesMap.delete(copy) } @@ -1829,6 +1834,10 @@ export default async (env) => { closeContext(slot.context).catch(() => undefined), sleep(10_000), ]) + // The replaced context leaves every map keyed by it, so it is no longer + // reachable (its Vitest and Vite state with it). + indexOf.delete(slot.context) + contextSpecs.delete(slot.context) slot.context = await warmContext(settings, slot.index) await globSpecs(slot.context) contexts[slot.index] = slot.context diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 38d9f334..e6061d9a 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1621,7 +1621,15 @@ async function driver(plan, observe) { // How many units were computed or reused says how the result was // produced, not what it is, so it is not observed. observe(`cli`, { ...cli, evidence: undefined }) - observe(`retention`, retention) + // Deterministic: how many batches left a retired copy's state behind (0), + // not the per-batch lines, whose batch splits vary with hang cuts. + observe( + `retention`, + retention.filter( + (line) => + line.filesMap + line.pathsSet + line.idMap + line.moduleNodes > 0, + ).length, + ) // A failing owner's replay, run as the author would run it (law 3). if (plan.fault === `brokenOwner`) observe(`replay`, { command: replay, ran: replayed(dir, replay) }) @@ -2191,21 +2199,14 @@ function check(plan, observations, expected) { // Bounded retention (the register's C entry): once a batch's copies are // retired, Vitest's filesMap, pathsSet, and idMap and Vite's module graph // name none of them, so each count the hook reports is 0. - const retention = observations.find( - (o) => o.checkpoint === `retention`, - )?.value - const held = (retention ?? []).find( - (line) => line.filesMap + line.pathsSet + line.idMap + line.moduleNodes > 0, - ) - if (held) + const held = + observations.find((o) => o.checkpoint === `retention`)?.value ?? 0 + if (held > 0) return violation( `retention`, - `a batch left its retired copies in Vitest or Vite state: ${JSON.stringify(held)}`, + `${held} batch(es) left a retired copy's Vitest or Vite state behind`, `bounded retention`, - { - actual: held, - expected: { filesMap: 0, pathsSet: 0, idMap: 0, moduleNodes: 0 }, - }, + { actual: held, expected: 0 }, ) // Through the daemon, each check streams the same kinds of line, and a // completed one ends with its done line (law 15). The state of each step From ce6c93dbe5b93636b8693149af33d7d2a50e98a9 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Fri, 13 Nov 2026 16:03:26 -0700 Subject: [PATCH 07/61] test(oracle-gaps): the retention law compares every structure with its size before the batch The hook now snapshots every structure a copy can leave state in (Vitest's filesMap, pathsSet, idMap, errorsSet, leakSet, and each Vite environment's url, id, etag and file maps and transformed nodes) before a batch, and the law requires each to return to its size after the batch's retirement. The law was tautological before: it counted the same predicate the deletion used. The retention observation is observed from every run kind (cold, daemon, stability, partial), and a run that computed a unit must have written a batch line. A check that ran more than one batch reaches a declared state. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 67 ++++++++++++------- .../gap-report-oracle.property.test.mjs | 60 ++++++++++++++--- 2 files changed, 92 insertions(+), 35 deletions(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index bf908276..f6b43e99 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -1004,6 +1004,9 @@ export default async (env) => { let copyCounter = 0 async function runBatch(context, out, items, seed) { const capture = join(out, `run-${process.pid}-${++runCounter}.jsonl`) + const before = process.env.ORACLE_GAPS_TEST_RETENTION + ? retentionTotals(context) + : undefined // Each copy is named beside its file, so that its imports resolve as the // file's do, and the wrapper's plugin serves its text: nothing is // written there. @@ -1259,7 +1262,10 @@ export default async (env) => { // A run cut off by a hang is still running: its worker may still send // updates, so its state is not touched here. Its context is replaced // by the caller (replace), which closes it and drops its state. - if (result !== undefined) retireCopies(context, copies) + if (result !== undefined) { + retireCopies(context, copies) + retiredEntries(context, before) + } rmSync(capture, { force: true }) } } @@ -1295,8 +1301,7 @@ export default async (env) => { filesMap.delete(copy) pathsSet.delete(copy) } - const modulesRemoved = retireModules(context.getRootProject().vite, gone) - retiredEntries(context, copies, modulesRemoved) + retireModules(context.getRootProject().vite, gone) } /** @@ -1357,33 +1362,43 @@ export default async (env) => { return environments } - // The test hook (ORACLE_GAPS_TEST_RETENTION, a file path): after each - // batch's copies are retired, one line counts the state entries and module - // nodes that still name a retired copy. The retention law reads it: each - // count is 0. - function retiredEntries(context, copies, modulesRemoved) { + // Every structure a copy can leave state in, unfiltered: Vitest's state + // (filesMap, pathsSet, idMap, errorsSet, leakSet) and each Vite environment's + // module graph (its four maps, and the nodes that hold a transform). + function retentionTotals(context) { + const { filesMap, pathsSet, idMap, errorsSet, leakSet } = context.state + const totals = { + filesMap: filesMap.size, + pathsSet: pathsSet.size, + idMap: idMap.size, + errorsSet: errorsSet.size, + leakSet: leakSet.size, + } + for (const [name, environment] of Object.entries( + context.getRootProject().vite?.environments ?? {}, + )) { + const graph = environment.moduleGraph + totals[`${name}.url`] = graph.urlToModuleMap.size + totals[`${name}.id`] = graph.idToModuleMap.size + totals[`${name}.etag`] = graph.etagToModuleMap.size + totals[`${name}.file`] = graph.fileToModulesMap.size + totals[`${name}.transformed`] = [...graph.idToModuleMap.values()].filter( + (node) => node.transformResult != null, + ).length + } + return totals + } + + // The test hook (ORACLE_GAPS_TEST_RETENTION, a file path): after a run + // that settled and its copies are retired, one line holds each structure's + // total before the batch and after its retirement. The bounded-retention + // law reads it: every total returns to its size before the batch. + function retiredEntries(context, before) { const file = process.env.ORACLE_GAPS_TEST_RETENTION if (!file) return - const gone = new Set(copies) - const named = (path) => gone.has(path) - const { filesMap, idMap, pathsSet } = context.state - let tasks = 0 - for (const task of idMap.values()) - if (named(task.file?.filepath ?? task.filepath)) tasks += 1 - let nodes = 0 - for (const environment of viteEnvironments(context.getRootProject().vite)) - for (const copy of gone) - nodes += environment.moduleGraph.fileToModulesMap.get(copy)?.size ?? 0 appendFileSync( file, - `${JSON.stringify({ - copies: copies.length, - filesMap: [...filesMap.keys()].filter(named).length, - pathsSet: [...pathsSet].filter(named).length, - idMap: tasks, - moduleNodes: nodes, - modulesRemoved, - })}\n`, + `${JSON.stringify({ before, after: retentionTotals(context) })}\n`, ) } diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index e6061d9a..e2451d74 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -639,6 +639,16 @@ const configArgs = (plan) => ({ contexts: plan.contexts, }) +// A run that computed a unit ran at least one batch (its evidence counts it), so it +// owes a retention line; a run that computed none (a full reuse, or a refusal) may write none. +const missingLine = (run) => + run.evidence?.computed > 0 && run.retention.length === 0 ? 1 : 0 + +// A batch line (ORACLE_GAPS_TEST_RETENTION) left state behind when a total +// after its retirement differs from its size before the batch. +const leftBehind = (line) => + Object.keys(line.before).some((key) => line.before[key] !== line.after[key]) + /** * Writes the fixture's files and runs the CLI on it. A file of an earlier * state that this state lacks is removed. @@ -1322,7 +1332,16 @@ async function incremental(dir, plan, cli, copy, observe, states) { : await daemonChecks(step, files, how) if (!cold.has(key)) cold.set(key, runCli(dir, files, how)) const coldRun = cold.get(key) - for (const [i, run] of [daemon, ...others].entries()) + for (const [i, run] of [daemon, ...others].entries()) { + observe( + `retention:daemon`, + (run.retention ?? []).filter(leftBehind).length, + ) + observe(`retentionLines:daemon`, missingLine(run)) + observe( + `retention:cold`, + (coldRun.retention ?? []).filter(leftBehind).length, + ) observe(`incremental`, { step: i === 0 ? step : `${step} (a second check at once)`, cold: { @@ -1349,6 +1368,7 @@ async function incremental(dir, plan, cli, copy, observe, states) { stderr: run.stderr?.split(`\n`)[0], }, }) + } if (twice && step === `start`) states.add(`two checks started the daemon at once`) if ( @@ -1623,18 +1643,17 @@ async function driver(plan, observe) { observe(`cli`, { ...cli, evidence: undefined }) // Deterministic: how many batches left a retired copy's state behind (0), // not the per-batch lines, whose batch splits vary with hang cuts. + observe(`retention`, retention.filter(leftBehind).length) observe( - `retention`, - retention.filter( - (line) => - line.filesMap + line.pathsSet + line.idMap + line.moduleNodes > 0, - ).length, + `retentionLines:cold`, + missingLine({ evidence: cli.evidence, retention }), ) // A failing owner's replay, run as the author would run it (law 3). if (plan.fault === `brokenOwner`) observe(`replay`, { command: replay, ran: replayed(dir, replay) }) // Reach comes from what the CLI reported, mapped onto the plan. const states = new Set() + if (retention.length > 1) states.add(`a check that ran more than one batch`) if (cli.exit === 0 && !plan.consoleOutput) states.add(`a completed run whose tests wrote nothing`) // Law 14: a partial run of one owned function's mutants, whose baseline @@ -1651,6 +1670,8 @@ async function driver(plan, observe) { only: ids, outName: `out-only`, }) + observe(`retention:partial`, partial.retention.filter(leftBehind).length) + observe(`retentionLines:partial`, missingLine(partial)) observe(`partial`, { function: chosen.function, source: chosen.source, @@ -2075,7 +2096,13 @@ async function driver(plan, observe) { const moved = { ...files, [SOURCE]: edited(plan) } // The evidence counts are not observed, as for `cli`: they depend on // timing (oracles-followups.md G1). Verdicts and keys are. - observe(`stability`, { ...runCli(dir, moved, how), evidence: undefined }) + const { retention: movedRetention, ...movedRun } = runCli(dir, moved, how) + observe(`stability`, { ...movedRun, evidence: undefined }) + observe(`retention:stability`, movedRetention.filter(leftBehind).length) + observe( + `retentionLines:stability`, + missingLine({ evidence: movedRun.evidence, retention: movedRetention }), + ) states.add(`stability rerun`) } if (plan.steps.length > 0) @@ -2199,8 +2226,23 @@ function check(plan, observations, expected) { // Bounded retention (the register's C entry): once a batch's copies are // retired, Vitest's filesMap, pathsSet, and idMap and Vite's module graph // name none of them, so each count the hook reports is 0. - const held = - observations.find((o) => o.checkpoint === `retention`)?.value ?? 0 + const unlogged = observations + .filter((o) => o.checkpoint.startsWith(`retentionLines`)) + .reduce((sum, o) => sum + o.value, 0) + if (unlogged > 0) + return violation( + `retention`, + `${unlogged} run(s) computed a unit but wrote no batch retention line`, + `bounded retention`, + { actual: unlogged, expected: 0 }, + ) + const held = observations + .filter( + (o) => + o.checkpoint.startsWith(`retention`) && + !o.checkpoint.startsWith(`retentionLines`), + ) + .reduce((sum, o) => sum + o.value, 0) if (held > 0) return violation( `retention`, From 390025ee4c5ac4c5fbaee81685917d2c7958e111 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 07:55:31 -0700 Subject: [PATCH 08/61] test(oracle-gaps): the retention law counts stale replaced contexts; a batch line is owed by mutant results The totals now include the excess of indexOf and contextSpecs over the live contexts, which must be zero before each batch: a context replaced between batches is caught there, not by a single batch's before and after. The missing-line expectation read evidence.computed, which counts single-file runs that write no batch line, so it failed on ce6c93d. A run owes a batch line when a mutant has owner files, since such a mutant's units ran in batches. Without that check, a retirement that never runs writes no line and passes the count law vacuously: the no-retire ablation exited 0. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 4 ++++ .../gap-report-oracle.property.test.mjs | 21 +++++++++++++------ 2 files changed, 19 insertions(+), 6 deletions(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index f6b43e99..99b7751e 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -1368,6 +1368,10 @@ export default async (env) => { function retentionTotals(context) { const { filesMap, pathsSet, idMap, errorsSet, leakSet } = context.state const totals = { + // Maps keyed by a context: each holds one entry per live context. A replaced + // context left in one is stale: the excess over the live contexts. + staleIndexed: indexOf.size - contexts.length, + staleSpecs: contextSpecs.size - contexts.length, filesMap: filesMap.size, pathsSet: pathsSet.size, idMap: idMap.size, diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index e2451d74..aa822b34 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -639,15 +639,24 @@ const configArgs = (plan) => ({ contexts: plan.contexts, }) -// A run that computed a unit ran at least one batch (its evidence counts it), so it -// owes a retention line; a run that computed none (a full reuse, or a refusal) may write none. +// A mutant whose owner files reached it ran their units in batches (runOwners), so a +// run with such a mutant owes at least one batch line. Single-file runs (unmutated and +// selected) write none and are not counted: `evidence.computed` includes them, so it +// does not say whether a batch ran. A refused or fully reused run may write none. const missingLine = (run) => - run.evidence?.computed > 0 && run.retention.length === 0 ? 1 : 0 + run.mutants?.some((m) => m.oracleFiles.length > 0) && + run.retention.length === 0 + ? 1 + : 0 // A batch line (ORACLE_GAPS_TEST_RETENTION) left state behind when a total // after its retirement differs from its size before the batch. const leftBehind = (line) => - Object.keys(line.before).some((key) => line.before[key] !== line.after[key]) + Object.keys(line.before).some( + (key) => + line.before[key] !== line.after[key] || + (key.startsWith(`stale`) && line.before[key] !== 0), + ) /** * Writes the fixture's files and runs the CLI on it. A file of an earlier @@ -1646,7 +1655,7 @@ async function driver(plan, observe) { observe(`retention`, retention.filter(leftBehind).length) observe( `retentionLines:cold`, - missingLine({ evidence: cli.evidence, retention }), + missingLine({ mutants: cli.mutants, retention }), ) // A failing owner's replay, run as the author would run it (law 3). if (plan.fault === `brokenOwner`) @@ -2101,7 +2110,7 @@ async function driver(plan, observe) { observe(`retention:stability`, movedRetention.filter(leftBehind).length) observe( `retentionLines:stability`, - missingLine({ evidence: movedRun.evidence, retention: movedRetention }), + missingLine({ mutants: movedRun.mutants, retention: movedRetention }), ) states.add(`stability rerun`) } From 59363c88788d5ed1087d8cdef83c864d13a5b9eb Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 09:00:50 -0700 Subject: [PATCH 09/61] fix(oracle-gaps): a cold check keeps no unit for reuse The cold check's store kept every computed unit, with its rows, for the whole run: 207 store entries and 103,585 row entries in the ce6c93d heap snapshot. A cold run serves no lookup (evidence.reused is 0 on every klona run), so the store now keeps nothing. The daemon's disk store is unchanged. The retention totals include the store's size, which must match before and after each batch. Paired identity runs (pre-change and this commit, both cut 0) give the same 391 results, and the baseline matches both. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 5 +++++ packages/oracles/oracle-gaps/evidence.mjs | 14 +++++++------- 2 files changed, 12 insertions(+), 7 deletions(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index 3a918a80..8458b218 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -553,6 +553,8 @@ export default async (env) => { return lastServed.get(index) } const indexOf = new Map() + // The units the check's store holds, set by check() (its store's size). + let heldUnits = () => 0 let contexts = [] let contextsKey let contextsConfig @@ -1387,6 +1389,8 @@ export default async (env) => { function retentionTotals(context) { const { filesMap, pathsSet, idMap, errorsSet, leakSet } = context.state const totals = { + // The cold check's store: units it keeps for reuse (none, see evidence.mjs). + store: heldUnits(), // Maps keyed by a context: each holds one entry per live context. A replaced // context left in one is stale: the excess over the live contexts. staleIndexed: indexOf.size - contexts.length, @@ -1426,6 +1430,7 @@ export default async (env) => { } async function check(options, store, log = console.error) { + heldUnits = () => store.size?.() ?? 0 const authored = options.mutants ? loadAuthored(options.mutants) : [] seedVariable = `${options.envPrefix}_SEED` if (options.hangLimit > options.mutantLimit) diff --git a/packages/oracles/oracle-gaps/evidence.mjs b/packages/oracles/oracle-gaps/evidence.mjs index dd018c12..5a2e9581 100644 --- a/packages/oracles/oracle-gaps/evidence.mjs +++ b/packages/oracles/oracle-gaps/evidence.mjs @@ -57,14 +57,14 @@ const withVersion = (row, variant) => ), ].slice(0, VERSIONS) -/** A store that lives for one check. */ +/** + * The store of a cold check. It keeps no unit: a cold run serves no lookup + * (its evidence reports `reused` 0 on every klona run measured), so a unit + * kept for reuse would only be retained, per mutant copy, for the whole run. + * `size` counts what it holds, for the retention law (check.mjs). + */ export function memoryStore() { - const rows = new Map() - return { - get: (id) => rows.get(id), - put: (id, variant) => - rows.set(id, { id, variants: withVersion(rows.get(id), variant) }), - } + return { get: () => undefined, put: () => {}, size: () => 0 } } /** From 969a7a8f61e253aa5859ffa613c0eb03860b4eec Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 09:16:35 -0700 Subject: [PATCH 10/61] test(oracle-gaps): the retention law counts batches exactly; cut batches are logged evidence.batches counts every batch run (cut or not). Each batch writes one retention line, so each run's line count must equal batches: a run with no line for a batch it ran (the no-retire mutant) fails the law. A cut batch writes its before line, so the stale totals of a replaced context are checked there. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 14 +++++-- .../gap-report-oracle.property.test.mjs | 39 +++++++------------ 2 files changed, 26 insertions(+), 27 deletions(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index 8458b218..1cf82276 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -563,6 +563,8 @@ export default async (env) => { let seedVariable = `ORACLE_SEED` const contextSpecs = new Map() let runCounter = 0 + // The current check's evidence, which runBatch counts its batches in (set by check). + let evidenceOf // A context loads the package's own config through its wrapper, so an // error there is the author's: the run refuses, naming the config file @@ -1020,6 +1022,7 @@ export default async (env) => { */ let copyCounter = 0 async function runBatch(context, out, items, seed) { + evidenceOf.batches += 1 const capture = join(out, `run-${process.pid}-${++runCounter}.jsonl`) const before = process.env.ORACLE_GAPS_TEST_RETENTION ? retentionTotals(context) @@ -1286,7 +1289,7 @@ export default async (env) => { if (result !== undefined) { retireCopies(context, copies) retiredEntries(context, before) - } + } else retiredEntries(context, before, true) rmSync(capture, { force: true }) } } @@ -1420,12 +1423,14 @@ export default async (env) => { // that settled and its copies are retired, one line holds each structure's // total before the batch and after its retirement. The bounded-retention // law reads it: every total returns to its size before the batch. - function retiredEntries(context, before) { + function retiredEntries(context, before, cut = false) { const file = process.env.ORACLE_GAPS_TEST_RETENTION if (!file) return + // A cut run is not retired (its context is replaced), so its line has no after: its before still + // names the stale totals the next batch starts from. appendFileSync( file, - `${JSON.stringify({ before, after: retentionTotals(context) })}\n`, + `${JSON.stringify(cut ? { before, cut: true } : { before, after: retentionTotals(context) })}\n`, ) } @@ -1563,7 +1568,10 @@ export default async (env) => { unchanged: 0, // Confirmations that a mutant's budget cut short or left no time. budget: 0, + // Every batch run (runBatch), cut or not: each writes one retention line. + batches: 0, } + evidenceOf = evidence // Each file's imports in its unmutated run. A run that timed out reports // none, so it is stored under these: a mutant changes no import. const fileInputs = new Map() diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index d4dc1d84..11bd4b9d 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -639,23 +639,18 @@ const configArgs = (plan) => ({ contexts: plan.contexts, }) -// A mutant whose owner files reached it ran their units in batches (runOwners), so a -// run with such a mutant owes at least one batch line. Single-file runs (unmutated and -// selected) write none and are not counted: `evidence.computed` includes them, so it -// does not say whether a batch ran. A refused or fully reused run may write none. -const missingLine = (run) => - run.mutants?.some((m) => m.oracleFiles.length > 0) && - run.retention.length === 0 - ? 1 - : 0 +// Exact: a run writes one retention line per batch it ran (evidence.batches, cut batches +// included), so its line count must equal that counter. Zero batches write none. +const unlogged = (run) => + run.retention.length === run.evidence.batches ? 0 : 1 // A batch line (ORACLE_GAPS_TEST_RETENTION) left state behind when a total // after its retirement differs from its size before the batch. const leftBehind = (line) => Object.keys(line.before).some( (key) => - line.before[key] !== line.after[key] || - (key.startsWith(`stale`) && line.before[key] !== 0), + (key.startsWith(`stale`) && line.before[key] !== 0) || + (line.after !== undefined && line.before[key] !== line.after[key]), ) /** @@ -1346,7 +1341,7 @@ async function incremental(dir, plan, cli, copy, observe, states) { `retention:daemon`, (run.retention ?? []).filter(leftBehind).length, ) - observe(`retentionLines:daemon`, missingLine(run)) + observe(`retentionLines:daemon`, unlogged(run)) observe( `retention:cold`, (coldRun.retention ?? []).filter(leftBehind).length, @@ -1655,7 +1650,7 @@ async function driver(plan, observe) { observe(`retention`, retention.filter(leftBehind).length) observe( `retentionLines:cold`, - missingLine({ mutants: cli.mutants, retention }), + unlogged({ retention, evidence: cli.evidence }), ) // A failing owner's replay, run as the author would run it (law 3). if (plan.fault === `brokenOwner`) @@ -1680,7 +1675,7 @@ async function driver(plan, observe) { outName: `out-only`, }) observe(`retention:partial`, partial.retention.filter(leftBehind).length) - observe(`retentionLines:partial`, missingLine(partial)) + observe(`retentionLines:partial`, unlogged(partial)) observe(`partial`, { function: chosen.function, source: chosen.source, @@ -2110,7 +2105,7 @@ async function driver(plan, observe) { observe(`retention:stability`, movedRetention.filter(leftBehind).length) observe( `retentionLines:stability`, - missingLine({ mutants: movedRun.mutants, retention: movedRetention }), + unlogged({ retention: movedRetention, evidence: movedRun.evidence }), ) states.add(`stability rerun`) } @@ -2235,22 +2230,18 @@ function check(plan, observations, expected) { // Bounded retention (the register's C entry): once a batch's copies are // retired, Vitest's filesMap, pathsSet, and idMap and Vite's module graph // name none of them, so each count the hook reports is 0. - const unlogged = observations + const unlogged_ = observations .filter((o) => o.checkpoint.startsWith(`retentionLines`)) .reduce((sum, o) => sum + o.value, 0) - if (unlogged > 0) + if (unlogged_ > 0) return violation( `retention`, - `${unlogged} run(s) computed a unit but wrote no batch retention line`, + `${unlogged_} run(s) wrote a retention line count different from their batches`, `bounded retention`, - { actual: unlogged, expected: 0 }, + { actual: unlogged_, expected: 0 }, ) const held = observations - .filter( - (o) => - o.checkpoint.startsWith(`retention`) && - !o.checkpoint.startsWith(`retentionLines`), - ) + .filter((o) => o.checkpoint.startsWith(`retention`)) .reduce((sum, o) => sum + o.value, 0) if (held > 0) return violation( From 67f057dd95db29ccdd5339cab0c23bfde375015f Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 09:30:56 -0700 Subject: [PATCH 11/61] test(oracle-gaps): the retention law counts copy-owned Vite nodes, not every cached module Vite's graph caches non-copy modules (a source or harness file, on first import), which legitimately grow during a batch; the before-and-after equality was wrong for Vite keys. The law now requires the copies' own module nodes to be zero after each settled batch, and keeps the before-and-after equality for Vitest's state, the store, and the stale context totals. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 18 ++++++++++++++---- .../gap-report-oracle.property.test.mjs | 7 +++++-- 2 files changed, 19 insertions(+), 6 deletions(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index 1cf82276..bdc59849 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -1288,8 +1288,8 @@ export default async (env) => { // by the caller (replace), which closes it and drops its state. if (result !== undefined) { retireCopies(context, copies) - retiredEntries(context, before) - } else retiredEntries(context, before, true) + retiredEntries(context, before, copies) + } else retiredEntries(context, before, copies, true) rmSync(capture, { force: true }) } } @@ -1423,14 +1423,24 @@ export default async (env) => { // that settled and its copies are retired, one line holds each structure's // total before the batch and after its retirement. The bounded-retention // law reads it: every total returns to its size before the batch. - function retiredEntries(context, before, cut = false) { + function retiredEntries(context, before, copies, cut = false) { const file = process.env.ORACLE_GAPS_TEST_RETENTION if (!file) return // A cut run is not retired (its context is replaced), so its line has no after: its before still // names the stale totals the next batch starts from. + // Vite's graph also holds modules that are not copies (a source or harness file is cached on its + // first import, legitimately), so for Vite the law counts the copies' own nodes, which must be 0. + const owned = new Set(copies) + let copyNodes = 0 + for (const environment of Object.values( + context.getRootProject().vite?.environments ?? {}, + )) + for (const copy of owned) + copyNodes += + environment.moduleGraph.fileToModulesMap.get(copy)?.size ?? 0 appendFileSync( file, - `${JSON.stringify(cut ? { before, cut: true } : { before, after: retentionTotals(context) })}\n`, + `${JSON.stringify(cut ? { before, cut: true } : { before, after: retentionTotals(context), copyNodes })}\n`, ) } diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 11bd4b9d..2480a0e0 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -647,10 +647,13 @@ const unlogged = (run) => // A batch line (ORACLE_GAPS_TEST_RETENTION) left state behind when a total // after its retirement differs from its size before the batch. const leftBehind = (line) => + (line.copyNodes ?? 0) !== 0 || Object.keys(line.before).some( (key) => - (key.startsWith(`stale`) && line.before[key] !== 0) || - (line.after !== undefined && line.before[key] !== line.after[key]), + // Vite's keys (`ssr.*`, `client.*`) hold non-copy modules too: only the copies' nodes count there. + !key.includes(`.`) && + ((key.startsWith(`stale`) && line.before[key] !== 0) || + (line.after !== undefined && line.before[key] !== line.after[key])), ) /** From 2ed6f1eca668ae2f7522fe186569685acfab6bfc Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 09:34:03 -0700 Subject: [PATCH 12/61] test(oracle-gaps): the retention law names Vite's totals and bounds non-copy nodes to one per file Vite's totals are named vite.., so the law tells them from Vitest's state by an explicit prefix the hook generates. After each settled batch, the copies' own module nodes must be 0, and each non-copy file (query stripped) has at most one node in each environment's graph: a file cached once per batch under a fresh id fails the law. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 35 ++++++++++++++----- .../gap-report-oracle.property.test.mjs | 6 ++-- 2 files changed, 31 insertions(+), 10 deletions(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index bdc59849..f8d85dd8 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -1408,13 +1408,14 @@ export default async (env) => { context.getRootProject().vite?.environments ?? {}, )) { const graph = environment.moduleGraph - totals[`${name}.url`] = graph.urlToModuleMap.size - totals[`${name}.id`] = graph.idToModuleMap.size - totals[`${name}.etag`] = graph.etagToModuleMap.size - totals[`${name}.file`] = graph.fileToModulesMap.size - totals[`${name}.transformed`] = [...graph.idToModuleMap.values()].filter( - (node) => node.transformResult != null, - ).length + // Vite's keys are named `vite..`, so the law can tell them from Vitest's state. + totals[`vite.${name}.url`] = graph.urlToModuleMap.size + totals[`vite.${name}.id`] = graph.idToModuleMap.size + totals[`vite.${name}.etag`] = graph.etagToModuleMap.size + totals[`vite.${name}.file`] = graph.fileToModulesMap.size + totals[`vite.${name}.transformed`] = [ + ...graph.idToModuleMap.values(), + ].filter((node) => node.transformResult != null).length } return totals } @@ -1423,6 +1424,24 @@ export default async (env) => { // that settled and its copies are retired, one line holds each structure's // total before the batch and after its retirement. The bounded-retention // law reads it: every total returns to its size before the batch. + // Files, without their query, with more than one node in an environment's graph, outside the copies: + // a non-copy file is cached once, so each count must be 0 (the law's bound on originals). + function nonCopyDuplicates(context, owned) { + let dup = 0 + for (const environment of Object.values( + context.getRootProject().vite?.environments ?? {}, + )) { + const perFile = new Map() + for (const node of environment.moduleGraph.idToModuleMap.values()) { + const file = node.id.split(`?`)[0] + if (owned.has(file)) continue + perFile.set(file, (perFile.get(file) ?? 0) + 1) + } + for (const n of perFile.values()) if (n > 1) dup += 1 + } + return dup + } + function retiredEntries(context, before, copies, cut = false) { const file = process.env.ORACLE_GAPS_TEST_RETENTION if (!file) return @@ -1440,7 +1459,7 @@ export default async (env) => { environment.moduleGraph.fileToModulesMap.get(copy)?.size ?? 0 appendFileSync( file, - `${JSON.stringify(cut ? { before, cut: true } : { before, after: retentionTotals(context), copyNodes })}\n`, + `${JSON.stringify(cut ? { before, cut: true } : { before, after: retentionTotals(context), copyNodes, nonCopyDup: nonCopyDuplicates(context, owned) })}\n`, ) } diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 2480a0e0..075ecb9d 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -648,10 +648,12 @@ const unlogged = (run) => // after its retirement differs from its size before the batch. const leftBehind = (line) => (line.copyNodes ?? 0) !== 0 || + (line.nonCopyDup ?? 0) !== 0 || Object.keys(line.before).some( (key) => - // Vite's keys (`ssr.*`, `client.*`) hold non-copy modules too: only the copies' nodes count there. - !key.includes(`.`) && + // Vite's totals are `vite..`: its non-copy modules are cached legitimately + // (checked by the copies' own nodes, copyNodes, and by the bound still to add). + !key.startsWith(`vite.`) && ((key.startsWith(`stale`) && line.before[key] !== 0) || (line.after !== undefined && line.before[key] !== line.after[key])), ) From 2b7efe6262d60eb60c5f1890484dd12ef74ebfc4 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 10:05:42 -0700 Subject: [PATCH 13/61] test(oracle-gaps): the batch-line check defers a run with no report to the completion law; the multi-batch state is declared A run with no report owes no batch line here: the completion law judges it, keyed on the model's prediction (a report unless a refusal is predicted), and fails it with its exit status and stderr. The multi-batch reach state is declared in the property's measured list. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-oracle.property.test.mjs | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 075ecb9d..58989888 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -641,8 +641,13 @@ const configArgs = (plan) => ({ // Exact: a run writes one retention line per batch it ran (evidence.batches, cut batches // included), so its line count must equal that counter. Zero batches write none. +// The batch-line count is owed only with a report: a run with no report is judged by the completion +// law (cli: the model predicts a report unless it predicts a refusal), which fails it there with its +// stderr. This check does not fail a run for lacking a report, so the two laws never both judge it. const unlogged = (run) => - run.retention.length === run.evidence.batches ? 0 : 1 + run.evidence === undefined || run.retention.length === run.evidence.batches + ? 0 + : 1 // A batch line (ORACLE_GAPS_TEST_RETENTION) left state behind when a total // after its retirement differs from its size before the batch. @@ -3435,6 +3440,8 @@ oracleProperty({ ...staticStates, `extra work in a generated function`, `killed by a work bound in a generated function`, + // A check whose runs have more than one batch: the retention law's multi-batch reach. + `a check that ran more than one batch`, ], runs: 2, fixedSeeds: [20261105], From fefc857bdc981624f35c8821f96f3a6f540bd4cb Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 10:10:24 -0700 Subject: [PATCH 14/61] test(oracle-gaps): the batch-line violation names the run that mismatched Co-authored-by: Isaac --- .../oracles/oracle-gaps/gap-report-oracle.property.test.mjs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 58989888..d169f4d3 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -2246,7 +2246,10 @@ function check(plan, observations, expected) { if (unlogged_ > 0) return violation( `retention`, - `${unlogged_} run(s) wrote a retention line count different from their batches`, + `${unlogged_} run(s) wrote a retention line count different from their batches (${observations + .filter((o) => o.checkpoint.startsWith(`retentionLines`) && o.value > 0) + .map((o) => o.checkpoint) + .join(`, `)})`, `bounded retention`, { actual: unlogged_, expected: 0 }, ) From 41d47db58c109275ab582c25aa52955e280b3397 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 10:13:35 -0700 Subject: [PATCH 15/61] test(oracle-gaps): a run's retention lines are its own: one hook file per package, counted as a delta A daemon keeps the environment of the call that started it, so a later daemon check wrote its retention lines to the hook file of the call that started the daemon, and its own (new) hook file was empty: the exact batch-line count failed on a correct run (retentionLines:daemon on the hang history). Counting side: every call for a package writes to one file, and a run's lines are the ones after its start. The production batch-line contract is unchanged. Co-authored-by: Isaac --- .../gap-report-oracle.property.test.mjs | 32 +++++++++++++------ 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index d169f4d3..2b72d87a 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -663,6 +663,23 @@ const leftBehind = (line) => (line.after !== undefined && line.before[key] !== line.after[key])), ) +const hookFiles = new Map() +const hookOf = (dir) => { + if (!hookFiles.has(dir)) + hookFiles.set( + dir, + join(mkdtempSync(join(tmpdir(), `gap-retention-`)), `retention.jsonl`), + ) + return hookFiles.get(dir) +} +const retentionLinesOf = (file) => + existsSync(file) + ? readFileSync(file, `utf8`) + .split(`\n`) + .filter(Boolean) + .map((line) => JSON.parse(line)) + : [] + /** * Writes the fixture's files and runs the CLI on it. A file of an earlier * state that this state lacks is removed. @@ -673,10 +690,10 @@ function runCli(dir, files, how = {}) { const { args, out } = cliArgs(dir, files, how) // The retention hook (ORACLE_GAPS_TEST_RETENTION): one line per batch, // written beside the run's own temporary files, not in the package. - const hook = join( - mkdtempSync(join(tmpdir(), `gap-retention-`)), - `retention.jsonl`, - ) + // One hook file per package: a daemon keeps the environment of the call that started it, so every call + // for this package writes to the same file, and this run's lines are those after its start (the delta). + const hook = hookOf(dir) + const hookBefore = retentionLinesOf(hook) const child = spawnSync(process.execPath, args, { cwd: repo, encoding: `utf8`, @@ -684,12 +701,7 @@ function runCli(dir, files, how = {}) { maxBuffer: 64 * 1024 * 1024, env: { ...cleanEnv(), ORACLE_GAPS_TEST_RETENTION: hook }, }) - const retention = existsSync(hook) - ? readFileSync(hook, `utf8`) - .split(`\n`) - .filter(Boolean) - .map((line) => JSON.parse(line)) - : [] + const retention = retentionLinesOf(hook).slice(hookBefore) const run = readRun( dir, out, From a21287cc569627e126a2aed3654a4d12947af00c Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 10:15:10 -0700 Subject: [PATCH 16/61] test(oracle-gaps): each retention line names its check's output directory; a run keeps its own lines Replaces the delta: a daemon serves many calls and keeps the first caller's environment, so a line is attributed to the check that wrote it (its out directory, the test hook's only addition), and the run keeps the lines that name its own out directory. Two daemon checks at once against one hook file cannot mix. No production outcome changes. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 5 ++++- .../oracles/oracle-gaps/gap-report-oracle.property.test.mjs | 6 +++--- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index f8d85dd8..11662677 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -565,6 +565,8 @@ export default async (env) => { let runCounter = 0 // The current check's evidence, which runBatch counts its batches in (set by check). let evidenceOf + // The output directory of the check being run (the test hook names each line with it). + let hookRun // A context loads the package's own config through its wrapper, so an // error there is the author's: the run refuses, naming the config file @@ -1459,11 +1461,12 @@ export default async (env) => { environment.moduleGraph.fileToModulesMap.get(copy)?.size ?? 0 appendFileSync( file, - `${JSON.stringify(cut ? { before, cut: true } : { before, after: retentionTotals(context), copyNodes, nonCopyDup: nonCopyDuplicates(context, owned) })}\n`, + `${JSON.stringify(cut ? { run: hookRun, before, cut: true } : { run: hookRun, before, after: retentionTotals(context), copyNodes, nonCopyDup: nonCopyDuplicates(context, owned) })}\n`, ) } async function check(options, store, log = console.error) { + hookRun = options.out heldUnits = () => store.size?.() ?? 0 const authored = options.mutants ? loadAuthored(options.mutants) : [] seedVariable = `${options.envPrefix}_SEED` diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 2b72d87a..e21ad49e 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -691,9 +691,8 @@ function runCli(dir, files, how = {}) { // The retention hook (ORACLE_GAPS_TEST_RETENTION): one line per batch, // written beside the run's own temporary files, not in the package. // One hook file per package: a daemon keeps the environment of the call that started it, so every call - // for this package writes to the same file, and this run's lines are those after its start (the delta). + // for this package writes to the same file; each line names its run (below). const hook = hookOf(dir) - const hookBefore = retentionLinesOf(hook) const child = spawnSync(process.execPath, args, { cwd: repo, encoding: `utf8`, @@ -701,7 +700,8 @@ function runCli(dir, files, how = {}) { maxBuffer: 64 * 1024 * 1024, env: { ...cleanEnv(), ORACLE_GAPS_TEST_RETENTION: hook }, }) - const retention = retentionLinesOf(hook).slice(hookBefore) + // Each line names its check's output directory, so this run keeps only its own (a daemon serves many calls). + const retention = retentionLinesOf(hook).filter((line) => line.run === out) const run = readRun( dir, out, From e223349df64b7fe15d852366bde47fe52cc350c2 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 10:17:38 -0700 Subject: [PATCH 17/61] test(oracle-gaps): retention lines carry their batch index; a debug table names each run's batches and lines Diagnostic for the daemon line mismatch (the test hook only; no production outcome changes). Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 2 +- .../oracle-gaps/gap-report-oracle.property.test.mjs | 7 +++++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index 11662677..7acd11e3 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -1461,7 +1461,7 @@ export default async (env) => { environment.moduleGraph.fileToModulesMap.get(copy)?.size ?? 0 appendFileSync( file, - `${JSON.stringify(cut ? { run: hookRun, before, cut: true } : { run: hookRun, before, after: retentionTotals(context), copyNodes, nonCopyDup: nonCopyDuplicates(context, owned) })}\n`, + `${JSON.stringify(cut ? { run: hookRun, batch: evidenceOf.batches, before, cut: true } : { run: hookRun, batch: evidenceOf.batches, before, after: retentionTotals(context), copyNodes, nonCopyDup: nonCopyDuplicates(context, owned) })}\n`, ) } diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index e21ad49e..fae2af8e 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -471,6 +471,7 @@ */ import { spawn, spawnSync } from 'node:child_process' import { + appendFileSync, cpSync, existsSync, mkdirSync, @@ -702,6 +703,12 @@ function runCli(dir, files, how = {}) { }) // Each line names its check's output directory, so this run keeps only its own (a daemon serves many calls). const retention = retentionLinesOf(hook).filter((line) => line.run === out) + // Debug table (ORACLE_GAPS_RETENTION_TABLE): each run's batches against its lines, for the mismatch. + if (process.env.ORACLE_GAPS_RETENTION_TABLE) + appendFileSync( + process.env.ORACLE_GAPS_RETENTION_TABLE, + `${JSON.stringify({ out, batches: JSON.parse(readFileSync(join(out, `results.json`), `utf8`)).evidence?.batches ?? null, lines: retention.map((l) => [l.batch, l.cut === true]) })}\n`, + ) const run = readRun( dir, out, From 30e6caded5feef7f7e269c0c6a185cb2a1d98acc Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 10:20:03 -0700 Subject: [PATCH 18/61] test(oracle-gaps): each CLI call has its own output directory, so its retention lines are its own The table showed the cause: a daemon serves several checks of one test, and two of them shared an out directory, so a run kept lines written by an earlier check (batches 1, lines 4; a run with 0 batches kept 1). Production wrote one line per batch in every run. The counting side is wrong: each call gets its own directory, so the run filter sees only its lines. The debug table is removed (it was for this diagnosis). No production change. Co-authored-by: Isaac --- .../gap-report-oracle.property.test.mjs | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index fae2af8e..a544bfbe 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -471,7 +471,6 @@ */ import { spawn, spawnSync } from 'node:child_process' import { - appendFileSync, cpSync, existsSync, mkdirSync, @@ -665,6 +664,7 @@ const leftBehind = (line) => ) const hookFiles = new Map() +let runSeq = 0 const hookOf = (dir) => { if (!hookFiles.has(dir)) hookFiles.set( @@ -688,7 +688,11 @@ const retentionLinesOf = (file) => function runCli(dir, files, how = {}) { writeFixture(dir, files) const before = new Set(filesUnder(dir)) - const { args, out } = cliArgs(dir, files, how) + const { args, out: outBase } = cliArgs(dir, files, how) + // Each call has its own output directory: its retention lines are then its own, even when a + // daemon serves several checks of one test. + const out = `${outBase}-${++runSeq}` + args[args.indexOf(`--out`) + 1] = out // The retention hook (ORACLE_GAPS_TEST_RETENTION): one line per batch, // written beside the run's own temporary files, not in the package. // One hook file per package: a daemon keeps the environment of the call that started it, so every call @@ -703,12 +707,6 @@ function runCli(dir, files, how = {}) { }) // Each line names its check's output directory, so this run keeps only its own (a daemon serves many calls). const retention = retentionLinesOf(hook).filter((line) => line.run === out) - // Debug table (ORACLE_GAPS_RETENTION_TABLE): each run's batches against its lines, for the mismatch. - if (process.env.ORACLE_GAPS_RETENTION_TABLE) - appendFileSync( - process.env.ORACLE_GAPS_RETENTION_TABLE, - `${JSON.stringify({ out, batches: JSON.parse(readFileSync(join(out, `results.json`), `utf8`)).evidence?.batches ?? null, lines: retention.map((l) => [l.batch, l.cut === true]) })}\n`, - ) const run = readRun( dir, out, From 6b1aa1de0108218e13ec89e925ed0f15bfa3fcfa Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 10:22:29 -0700 Subject: [PATCH 19/61] test(oracle-gaps): the namespace law allows the numbered output directories runCli gives each call Each call's out directory is numbered (out-, out-daemon-, ...), so the outputs of a run are its own. The law's list of own outputs names the fixed ones; the numbered ones match the same pattern the driver creates (OWN_NUMBERED). Without it, a run's out-25 writes read as strays. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-oracle.property.test.mjs | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index a544bfbe..95438928 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -735,7 +735,11 @@ const strays = (dir, before, running = false) => (file) => !before.has(file) && !(running && /^\.oracle-gaps-\d+\//.test(file)) && - !OWN_WRITES.some((home) => file === home || file.startsWith(`${home}/`)), + !OWN_WRITES.some( + (home) => file === home || file.startsWith(`${home}/`), + ) && + // The numbered output directories a run's CLI calls get (runCli): one per call. + !OWN_NUMBERED.test(file), ) /** @@ -948,6 +952,7 @@ function filesUnder(root, within = ``) { // of the repository), so a package, and a workspace dependency in it, keeps // nothing of a run. const OWN_WRITES = [`out`, `out-daemon`, `out-stop`, `out-only`] +const OWN_NUMBERED = /^out(-daemon|-stop|-only)?-\d+(\/|$)/ /** Runs the CLI several times at once on one state of the fixture. */ async function runClisAtOnce(dir, files, hows) { From 11105c5cb08bdb34f8299d3d2da31844c015df96 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 10:24:28 -0700 Subject: [PATCH 20/61] test(oracle-gaps): the namespace law allows exactly the --out a run was given Repair, not widening (P7): the law listed fixed output names (out, out-daemon, out-stop, out-only), and numbered names were a pattern. Now each run's allowed output is the one path the model predicts (its --out, from cliArgs): runCli passes its numbered out, the stop law passes out-stop. A CLI that writes under any other directory, such as out--next, is a stray. The lists are removed. Co-authored-by: Isaac --- .../gap-report-oracle.property.test.mjs | 27 +++++++++++-------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 95438928..12800296 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -720,7 +720,12 @@ function runCli(dir, files, how = {}) { .split(`\n`) .find((line) => line.startsWith(` replay: `)) ?.slice(` replay: `.length) - return { ...run, strayWrites: strays(dir, before), replay, retention } + return { + ...run, + strayWrites: strays(dir, before, relative(dir, out)), + replay, + retention, + } } /** @@ -730,16 +735,13 @@ function runCli(dir, files, how = {}) { * directory, `.oracle-gaps-/` (its capture setup and Vitest configs, * which resolve the package's modules from there), is its own too. */ -const strays = (dir, before, running = false) => +const strays = (dir, before, own, running = false) => filesUnder(dir).filter( (file) => !before.has(file) && !(running && /^\.oracle-gaps-\d+\//.test(file)) && - !OWN_WRITES.some( - (home) => file === home || file.startsWith(`${home}/`), - ) && - // The numbered output directories a run's CLI calls get (runCli): one per call. - !OWN_NUMBERED.test(file), + // The one path a run may write under: the --out the driver gave it (cliArgs names it). + !(file === own || file.startsWith(`${own}/`)), ) /** @@ -837,7 +839,12 @@ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { : warm ? existsSync(join(pids, `warming`)) && !exited : readdirSync(pids).length >= 2 - const strayWhileRunning = strays(dir, before, true) + const strayWhileRunning = strays( + dir, + before, + relative(dir, join(dir, `out-stop`)), + true, + ) if (!abort) child.kill(signal) const ended = await Promise.race([exit, sleep(30_000).then(() => false)]) await sleep(1000) @@ -892,7 +899,7 @@ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { /^\.oracle-gaps-\d+$/.test(name), ), // What else it left in the package. - left: strays(dir, before).filter( + left: strays(dir, before, relative(dir, join(dir, `out-stop`))).filter( (file) => !/^\.oracle-gaps-\d+\//.test(file), ), } @@ -951,8 +958,6 @@ function filesUnder(root, within = ``) { // (maintainer decision, 2026-11-11: the gap check's working files stay out // of the repository), so a package, and a workspace dependency in it, keeps // nothing of a run. -const OWN_WRITES = [`out`, `out-daemon`, `out-stop`, `out-only`] -const OWN_NUMBERED = /^out(-daemon|-stop|-only)?-\d+(\/|$)/ /** Runs the CLI several times at once on one state of the fixture. */ async function runClisAtOnce(dir, files, hows) { From c4e7bc7f57d7678de85efd35a1deff9702b2e84c Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 11:02:38 -0700 Subject: [PATCH 21/61] test(oracle-gaps): the observed text names a run's output directory without its call number The determinism diagnostic found the first differing offset in the cli observation's lead text: one run named /out-9/results.json and the other out-13. The number counts every call in the process (runCli), so it differs between two runs of one history. This was a test-side artifact of the per-call out directories, not a wall-clock cut. The observation now names the directory without the number. No production change. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-oracle.property.test.mjs | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 12800296..b9aa7a48 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1001,6 +1001,11 @@ async function runClisAtOnce(dir, files, hows) { // `.oracle-gaps/session-`, and its copies of test files, // `.oracle-gaps---`, check.mjs), and Vitest names such a file // when it fails to load, so the id is named too. +// A run's output directory carries its call number (runCli: out-), which counts every call in the +// process, so the number differs between two runs of one history. The observation names the directory. +const outNumbers = (text) => + text.replace(/(out(?:-daemon|-stop|-only)?)-\d+(?=[/\s\\"]|$)/g, `$1`) + function namedScratch(text, names) { let named = text const longestFirst = names @@ -1135,9 +1140,10 @@ function readRun(dir, out, status, stderr, cli, stdout) { const blank = printed.indexOf(``) return { lead: (blank < 0 ? printed : printed.slice(0, blank)).map((line) => - namedScratch(line, scratch), + outNumbers(namedScratch(line, scratch)), ), - lastLine: printed.at(-1) && namedScratch(printed.at(-1), scratch), + lastLine: + printed.at(-1) && outNumbers(namedScratch(printed.at(-1), scratch)), // The stdout's own lines of the stream's kinds: the gap lines under // their functions, as the stream prints them (law 15). stdoutGaps: printed.filter((line) => streamedGap.test(line)).length, From 9d3d3d2fa6bb37878fddfe1fac0c4a12a9f9c48d Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 11:05:44 -0700 Subject: [PATCH 22/61] test(oracle-gaps): output directories are numbered within each history, so two runs of one history name the same paths Replaces the name normalisation: it hid a CLI that printed another run's results path. A call's number now counts calls within its history (reset at the start of each driver run), so repeated runs of one history get identical directories and the observation is exact. No production change. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-oracle.property.test.mjs | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index b9aa7a48..c3ce5ccd 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1001,11 +1001,6 @@ async function runClisAtOnce(dir, files, hows) { // `.oracle-gaps/session-`, and its copies of test files, // `.oracle-gaps---`, check.mjs), and Vitest names such a file // when it fails to load, so the id is named too. -// A run's output directory carries its call number (runCli: out-), which counts every call in the -// process, so the number differs between two runs of one history. The observation names the directory. -const outNumbers = (text) => - text.replace(/(out(?:-daemon|-stop|-only)?)-\d+(?=[/\s\\"]|$)/g, `$1`) - function namedScratch(text, names) { let named = text const longestFirst = names @@ -1140,10 +1135,9 @@ function readRun(dir, out, status, stderr, cli, stdout) { const blank = printed.indexOf(``) return { lead: (blank < 0 ? printed : printed.slice(0, blank)).map((line) => - outNumbers(namedScratch(line, scratch)), + namedScratch(line, scratch), ), - lastLine: - printed.at(-1) && outNumbers(namedScratch(printed.at(-1), scratch)), + lastLine: printed.at(-1) && namedScratch(printed.at(-1), scratch), // The stdout's own lines of the stream's kinds: the gap lines under // their functions, as the stream prints them (law 15). stdoutGaps: printed.filter((line) => streamedGap.test(line)).length, @@ -1655,6 +1649,8 @@ async function incremental(dir, plan, cli, copy, observe, states) { } async function driver(plan, observe) { + // Calls are counted within this history, so two runs of one history name the same directories. + runSeq = 0 // A package that resolves no TypeScript, has no config, or has its // config in its parent directory lives outside this repository // (`outsideRepository`); the last in a directory `pkg` of the scratch From 270e6f4a448e3c0cc1973c21fbe2130ee41849e4 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 11:36:00 -0700 Subject: [PATCH 23/61] test(oracle-gaps): at-once runs carry their retention lines; the retention violation names the fields left behind At-once daemon runs (runClisAtOnce) spawned the CLI without the test hook, so the exact line check read an undefined retention. They now set the hook, keep their own lines (out numbered within the history, as runCli's), and are judged by the same law. The retention violation names the leftover fields (copyNodes, nonCopyDup, the stale totals, Vitest's maps) so a CI failure shows which law is hit. The keys are observed as a string and excluded from the count. No production change. Co-authored-by: Isaac --- .../gap-report-oracle.property.test.mjs | 47 +++++++++++++++++-- 1 file changed, 42 insertions(+), 5 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index c3ce5ccd..a4fe96d4 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -651,6 +651,26 @@ const unlogged = (run) => // A batch line (ORACLE_GAPS_TEST_RETENTION) left state behind when a total // after its retirement differs from its size before the batch. +// The keys a settled batch left behind, sorted, for a violation's message. +const leftKeys = (lines) => + [ + ...new Set( + lines.flatMap((line) => [ + ...((line.copyNodes ?? 0) !== 0 ? [`copyNodes`] : []), + ...((line.nonCopyDup ?? 0) !== 0 ? [`nonCopyDup`] : []), + ...Object.keys(line.before ?? {}).filter( + (key) => + !key.startsWith(`vite.`) && + ((key.startsWith(`stale`) && line.before[key] !== 0) || + (line.after !== undefined && + line.before[key] !== line.after[key])), + ), + ]), + ), + ] + .sort() + .join(`, `) + const leftBehind = (line) => (line.copyNodes ?? 0) !== 0 || (line.nonCopyDup ?? 0) !== 0 || @@ -964,10 +984,13 @@ async function runClisAtOnce(dir, files, hows) { writeFixture(dir, files) return Promise.all( hows.map(async (how) => { - const { args, out } = cliArgs(dir, files, how) + const { args, out: outBase } = cliArgs(dir, files, how) + const out = `${outBase}-${++runSeq}` + args[args.indexOf(`--out`) + 1] = out + const hook = hookOf(dir) const child = spawn(process.execPath, args, { cwd: repo, - env: { ...cleanEnv(), ...how.env }, + env: { ...cleanEnv(), ...how.env, ORACLE_GAPS_TEST_RETENTION: hook }, stdio: [`ignore`, `pipe`, `pipe`], }) // Both streams, as runCli reads them: law 15 judges each run's lines, @@ -987,7 +1010,11 @@ async function runClisAtOnce(dir, files, hows) { resolvePromise(code) }) }) - return readRun(dir, out, status, stderr, how.cli ?? here, stdout) + const run = readRun(dir, out, status, stderr, how.cli ?? here, stdout) + return { + ...run, + retention: retentionLinesOf(hook).filter((line) => line.run === out), + } }), ) } @@ -1687,6 +1714,7 @@ async function driver(plan, observe) { // Deterministic: how many batches left a retired copy's state behind (0), // not the per-batch lines, whose batch splits vary with hang cuts. observe(`retention`, retention.filter(leftBehind).length) + observe(`retentionKeys`, leftKeys(retention)) observe( `retentionLines:cold`, unlogged({ retention, evidence: cli.evidence }), @@ -2282,13 +2310,22 @@ function check(plan, observations, expected) { `bounded retention`, { actual: unlogged_, expected: 0 }, ) + const fields = observations + .filter((o) => o.checkpoint.startsWith(`retentionKeys`)) + .map((o) => o.value) + .filter(Boolean) + .join(`, `) const held = observations - .filter((o) => o.checkpoint.startsWith(`retention`)) + .filter( + (o) => + o.checkpoint.startsWith(`retention`) && + !o.checkpoint.startsWith(`retentionKeys`), + ) .reduce((sum, o) => sum + o.value, 0) if (held > 0) return violation( `retention`, - `${held} batch(es) left a retired copy's Vitest or Vite state behind`, + `${held} batch(es) left a retired copy's Vitest or Vite state behind (fields: ${fields || `none named`})`, `bounded retention`, { actual: held, expected: 0 }, ) From 7515fd2b922e30b95fb48c2b14e030f27bd497ac Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 12:44:15 -0700 Subject: [PATCH 24/61] test(oracle-gaps): the retention hook names each non-copy file that has more than one node, and its node ids Diagnostic for the nonCopyDup leftovers in CI (shards 1 and 2). The count is unchanged; the hook line now also carries the duplicated files and their ids, so the cause (a file cached under two id spellings, or per-batch fresh ids) can be read. The test hook only. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index 7acd11e3..46bd31fb 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -1429,7 +1429,7 @@ export default async (env) => { // Files, without their query, with more than one node in an environment's graph, outside the copies: // a non-copy file is cached once, so each count must be 0 (the law's bound on originals). function nonCopyDuplicates(context, owned) { - let dup = 0 + const dup = [] for (const environment of Object.values( context.getRootProject().vite?.environments ?? {}, )) { @@ -1437,9 +1437,13 @@ export default async (env) => { for (const node of environment.moduleGraph.idToModuleMap.values()) { const file = node.id.split(`?`)[0] if (owned.has(file)) continue - perFile.set(file, (perFile.get(file) ?? 0) + 1) + perFile.set(file, [...(perFile.get(file) ?? []), node.id]) } - for (const n of perFile.values()) if (n > 1) dup += 1 + for (const [file, ids] of perFile) + if (ids.length > 1) + dup.push( + `${environment.name ?? `env`} ${file} ${ids.sort().join(` | `)}`, + ) } return dup } @@ -1461,7 +1465,7 @@ export default async (env) => { environment.moduleGraph.fileToModulesMap.get(copy)?.size ?? 0 appendFileSync( file, - `${JSON.stringify(cut ? { run: hookRun, batch: evidenceOf.batches, before, cut: true } : { run: hookRun, batch: evidenceOf.batches, before, after: retentionTotals(context), copyNodes, nonCopyDup: nonCopyDuplicates(context, owned) })}\n`, + `${JSON.stringify(cut ? { run: hookRun, batch: evidenceOf.batches, before, cut: true } : { run: hookRun, batch: evidenceOf.batches, before, after: retentionTotals(context), copyNodes, nonCopyDup: nonCopyDuplicates(context, owned).length, nonCopyIds: nonCopyDuplicates(context, owned) })}\n`, ) } From 8e6801a0f05b7ec24298bed083b1bef0f3195f88 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 12:52:53 -0700 Subject: [PATCH 25/61] test(oracle-gaps): a source file's plain node and its ?raw node are one measured pair, not a leftover The non-copy bound failed on shards 1 and 2 of CI (270e6f4) on exactly this pair: sut.ts (plain) and sut.ts?raw, the source-text import the oracle reads. Measured locally on shard 1's history: the same pair in every batch line (one per file, not per batch). The allowance is that exact pair; any other duplicate is still counted. No production change. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index 46bd31fb..faf26768 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -1439,8 +1439,17 @@ export default async (env) => { if (owned.has(file)) continue perFile.set(file, [...(perFile.get(file) ?? []), node.id]) } + // The one measured allowance: a source file's plain node and its ?raw node (the oracle reads source text + // with ?raw). One pair per file, not per batch (shard 1 on 270e6f4: the same pair in every batch line). for (const [file, ids] of perFile) - if (ids.length > 1) + if ( + ids.length > 1 && + !( + ids.length === 2 && + ids.includes(file) && + ids.includes(`${file}?raw`) + ) + ) dup.push( `${environment.name ?? `env`} ${file} ${ids.sort().join(` | `)}`, ) From 05f00e19da57177016a5cb3b685e5b3d59d36b8f Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 13:20:01 -0700 Subject: [PATCH 26/61] test(oracle-gaps): the daemon, partial, and stability retention sites name their leftover fields CI on 8e6801a: the cold run left nothing named, and the 1, 4, and 12 batches left behind were at the daemon, partial and stability sites, which named no field. Each site now observes its leftover keys, the same as the cold site. Test-side only. Co-authored-by: Isaac --- .../oracles/oracle-gaps/gap-report-oracle.property.test.mjs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index a4fe96d4..f6c249ad 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1406,6 +1406,7 @@ async function incremental(dir, plan, cli, copy, observe, states) { (run.retention ?? []).filter(leftBehind).length, ) observe(`retentionLines:daemon`, unlogged(run)) + observe(`retentionKeys:daemon`, leftKeys(run.retention ?? [])) observe( `retention:cold`, (coldRun.retention ?? []).filter(leftBehind).length, @@ -1743,6 +1744,7 @@ async function driver(plan, observe) { }) observe(`retention:partial`, partial.retention.filter(leftBehind).length) observe(`retentionLines:partial`, unlogged(partial)) + observe(`retentionKeys:partial`, leftKeys(partial.retention ?? [])) observe(`partial`, { function: chosen.function, source: chosen.source, @@ -2174,6 +2176,7 @@ async function driver(plan, observe) { `retentionLines:stability`, unlogged({ retention: movedRetention, evidence: movedRun.evidence }), ) + observe(`retentionKeys:stability`, leftKeys(movedRetention)) states.add(`stability rerun`) } if (plan.steps.length > 0) From 2203587065bc0146e543a849a912fcc77fcada94 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 13:30:23 -0700 Subject: [PATCH 27/61] fix(oracle-gaps): a replaced context leaves the registry and joins it in one synchronous step The registry (indexOf, contextSpecs) and the contexts array changed across awaits in replace: the old context left, the new one registered in warmContext, then specs were read, then the array was assigned. Between those steps the registry and the array disagreed, so a batch that measured the registry (the retention totals) read a negative stale count (-1) during another slot's replacement. The swap is now one synchronous step after all awaits: the replaced context leaves both maps, the new one joins both and the array, and warmContext and specsOf no longer register. Production lookups are per slot (indexOf.get of the slot's current context), so no batch reads another slot's window; the race was in the measurement. Stated as a finding: the -1 measurement was real (the registry was out of step with the array between awaits), and the step is now atomic. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 39 ++++++++++++++++---------- 1 file changed, 24 insertions(+), 15 deletions(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index faf26768..d7b93503 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -738,21 +738,22 @@ export default async (env) => { `Run the gap report on a package whose Vitest config has no test.projects.`, ) } - indexOf.set(context, index) lastServed.delete(index) return context } - async function globSpecs(context) { - // A warm context caches the test files it found; a file added since the - // last check, such as a new oracle file, appears only after the cache is - // cleared. + // A warm context caches the test files it found; a file added since the last check, such as a new oracle + // file, appears only after the cache is cleared. Returns the context's specs (registered by the caller). + async function specsOf(context) { context.clearSpecificationsCache?.() const map = new Map() for (const spec of await context.globTestSpecifications()) { if (isRunnerCopy(spec.moduleId)) continue map.set(spec.moduleId, [...(map.get(spec.moduleId) ?? []), spec]) } - contextSpecs.set(context, map) + return map + } + async function globSpecs(context) { + contextSpecs.set(context, await specsOf(context)) } async function closeContexts() { await Promise.all( @@ -1538,13 +1539,17 @@ export default async (env) => { (contexts.length > 0 && configHash() !== contextsConfig) ) { await closeContexts() - for (let i = 0; i < options.contexts; i += 1) + for (let i = 0; i < options.contexts; i += 1) { contexts.push(await warmContext(settings, i)) + indexOf.set(contexts.at(-1), i) + } contextsKey = JSON.stringify(settings) contextsConfig = configHash() } - while (contexts.length < options.contexts) + while (contexts.length < options.contexts) { contexts.push(await warmContext(settings, contexts.length)) + indexOf.set(contexts.at(-1), contexts.length - 1) + } endPhase(`warm contexts`, { contexts: contexts.length }) // The run names the config its contexts loaded, before any refusal that // the analysis or the baseline makes. @@ -1930,13 +1935,17 @@ export default async (env) => { closeContext(slot.context).catch(() => undefined), sleep(10_000), ]) - // The replaced context leaves every map keyed by it, so it is no longer - // reachable (its Vitest and Vite state with it). - indexOf.delete(slot.context) - contextSpecs.delete(slot.context) - slot.context = await warmContext(settings, slot.index) - await globSpecs(slot.context) - contexts[slot.index] = slot.context + const replaced = slot.context + const next = await warmContext(settings, slot.index) + const specs = await specsOf(next) + // One synchronous step: the replaced context leaves every map keyed by it and the new one joins them, + // with the contexts array, so no reader (and no measurement) sees the registry and the array disagree. + indexOf.delete(replaced) + contextSpecs.delete(replaced) + indexOf.set(next, slot.index) + contextSpecs.set(next, specs) + contexts[slot.index] = next + slot.context = next span(`replace context`, started, { slot: slot.index }) } // `after(index)` is more work for context `index` once its files ran. From 8c48afe2a8c78a49469f689bf63112b6d9301572 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 13:56:10 -0700 Subject: [PATCH 28/61] fix(oracle-gaps): closing the contexts for a config change clears the registry with the array closeContexts emptied the contexts array but left indexOf and contextSpecs keyed by the closed contexts: after a config change in a daemon edit sequence the registry held entries no live context owns (staleIndexed and staleSpecs on CI's shard 3/3). The closed contexts now leave both maps with the array. A production leak, found by the stale totals. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index d7b93503..d5dd3b57 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -764,6 +764,12 @@ export default async (env) => { ]), ), ) + // The closed contexts leave the registry with the array: a context closed for a config change is no longer + // reachable through indexOf or contextSpecs (the daemon's edit sequence left them there before). + for (const context of contexts) { + indexOf.delete(context) + contextSpecs.delete(context) + } contexts = [] lastServed.clear() } From 346c8a806d7412ff1e22ec8c79465a7a0fb27068 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 14:54:24 -0700 Subject: [PATCH 29/61] test(oracle-gaps): the daemon pause watches the state file of its own call The incremental driver waited for out-daemon/state.json before it paused the daemon. 270e6f4 numbers each runClisAtOnce call's output directory (out-daemon-), as runCli already does, so that file never appears and the pause never happens: the daemon held-then-died state is not entered (r61-dm-branch-1 and -2: "did not enter a check whose daemon held it past the CLI's wait, then died"). Main has no numbering there, so its path matched. The driver now names the directory its call was given: runClisAtOnce records each call's output directory before any call starts, and the watch reads that directory's state file. The pause itself is unchanged, and the state is still recorded only when the CLI reports after the daemon died. Production is not changed. The driver's pause assumption was valid on main; this branch's numbering broke it, so the driver is repaired. Co-authored-by: Isaac --- .../gap-report-oracle.property.test.mjs | 33 +++++++++++++------ 1 file changed, 23 insertions(+), 10 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index f6c249ad..b0806f03 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -979,13 +979,18 @@ function filesUnder(root, within = ``) { // of the repository), so a package, and a workspace dependency in it, keeps // nothing of a run. -/** Runs the CLI several times at once on one state of the fixture. */ -async function runClisAtOnce(dir, files, hows) { +/** + * Runs the CLI several times at once on one state of the fixture. `outs` + * receives each call's output directory synchronously, before any call + * starts, so a driver can watch the directory its own call writes. + */ +async function runClisAtOnce(dir, files, hows, outs = []) { writeFixture(dir, files) return Promise.all( hows.map(async (how) => { const { args, out: outBase } = cliArgs(dir, files, how) const out = `${outBase}-${++runSeq}` + outs.push(out) args[args.indexOf(`--out`) + 1] = out const hook = hookOf(dir) const child = spawn(process.execPath, args, { @@ -1564,13 +1569,19 @@ async function incremental(dir, plan, cli, copy, observe, states) { // The time a daemon holds a request is the check's, not time spent // waiting for a daemon, so a CLI that waits 3 s for one still outlasts // a daemon that holds its check for 4 s. - const running = runClisAtOnce(dir, files, [ - { - ...how, - daemon: true, - env: step === `dieMidCheck` ? { ORACLE_GAPS_WAIT_MS: `3000` } : {}, - }, - ]) + const outs = [] + const running = runClisAtOnce( + dir, + files, + [ + { + ...how, + daemon: true, + env: step === `dieMidCheck` ? { ORACLE_GAPS_WAIT_MS: `3000` } : {}, + }, + ], + outs, + ) let paused = false if (step === `resetBeforeRead`) { await new Promise((r) => setTimeout(r, 500)) @@ -1578,7 +1589,9 @@ async function incremental(dir, plan, cli, copy, observe, states) { } else { // Mid-check: the daemon has written this check's state file. A check // that ends first (a refusal runs nothing) leaves its daemon alone. - const started = join(dir, `out-daemon`, `state.json`) + // The call's output directory is numbered (runClisAtOnce), so the + // file is in the directory the call was given, not `out-daemon`. + const started = join(outs[0], `state.json`) let finished = false running.then(() => { finished = true From 79f1dea8e6cb267f85200413d934cf602553528f Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 16:41:39 -0700 Subject: [PATCH 30/61] fix(oracle-gaps): a crashed batch retires and logs; registry checks compare identities; stopped runs judge their batches - runBatch: the race with the watchdog sits inside the try, so a rejected run (a crash, not a cut) still retires its copies and writes its retention line. A cut still writes the cut line. Found in the independent review (M2): the rejection skipped the finally. - The retention hook names identities: staleIndexed counts registry entries that do not name the live context at their own slot; staleSpecs counts entries for no live context; staleOpen counts open (warmed, not closed) contexts beyond the live ones. Found in review (M4, M5). - A stop sets the retention hook, and each stopped run's completed batches are judged by the same leftBehind law (M1). - The retention line drops the unread nonCopyIds field and computes the duplicate list once (M6). The law's authority is the register's C entry on bounded retention (2026-11-13). Test-side hook and driver edits follow P7 (strengthening, no weakening). Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 111 ++++++++++-------- .../gap-report-oracle.property.test.mjs | 34 ++++-- 2 files changed, 89 insertions(+), 56 deletions(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index d5dd3b57..ab255da0 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -593,8 +593,12 @@ export default async (env) => { const limit = process.getMaxListeners() if (limit > 0) process.setMaxListeners(limit + count) } - const closeContext = (context) => - context.close().finally(() => allowListeners(-1)) + // The contexts that are open (warmed and not yet closed): the replaced ones must leave it. + const openContexts = new Set() + const closeContext = (context) => { + openContexts.delete(context) + return context.close().finally(() => allowListeners(-1)) + } // Vite's logger, writing each message as `oracle-gaps: note vite: …`. const viteNote = (message) => { for (const line of String(message) @@ -739,6 +743,7 @@ export default async (env) => { ) } lastServed.delete(index) + openContexts.add(context) return context } // A warm context caches the test files it found; a file added since the last check, such as a new oracle @@ -1150,46 +1155,51 @@ export default async (env) => { } timer = setTimeout(poll, 50) }) - const result = await Promise.race([running, watchdog]) - clearTimeout(timer) - const seconds = (Date.now() - started) / 1000 - // Each copy's rows, and the copies that skipped their tests because an - // earlier copy in the batch killed their mutant. - const skipped = new Set() - // The files of the modules each copy evaluated (its closing row). - const loaded = new Map() - const rowsOf = () => { - const rows = new Map(copies.map((copy) => [copy, []])) - loaded.clear() - if (existsSync(capture)) - for (const line of readFileSync(capture, `utf8`) - .split(`\n`) - .filter(Boolean)) { - const row = JSON.parse(line) - const copy = copies.find( - (c) => - posix(row.key ?? ``).startsWith(`${c} > `) || - posix(row.file ?? ``) === c, - ) - if (copy && row.skipped) skipped.add(copy) - if (copy && row.closed) loaded.set(copy, row.loaded ?? []) - if (copy && row.spin) spun.add(copy) - if (copy && !row.closed && !row.idle && !row.spin && !row.started) - rows.get(copy).push(row) - } - return rows - } - const skippedUnit = (item) => ({ file: item.file, skipped: true }) - // A copy that ran past its call budget, even one whose throw ended the - // loop and let it finish, is a timeout as it stands (a count, not a - // clock: no confirming run). - const spunUnit = (item) => ({ - file: item.file, - timedOut: true, - spin: true, - seconds, - }) + // The race sits inside the try below, so a rejected run (a crash, not a cut) still retires its + // copies and writes its retention line. `raced` tells that apart from a cut, which resolves undefined. + let result + let raced = false try { + result = await Promise.race([running, watchdog]) + raced = true + clearTimeout(timer) + const seconds = (Date.now() - started) / 1000 + // Each copy's rows, and the copies that skipped their tests because an + // earlier copy in the batch killed their mutant. + const skipped = new Set() + // The files of the modules each copy evaluated (its closing row). + const loaded = new Map() + const rowsOf = () => { + const rows = new Map(copies.map((copy) => [copy, []])) + loaded.clear() + if (existsSync(capture)) + for (const line of readFileSync(capture, `utf8`) + .split(`\n`) + .filter(Boolean)) { + const row = JSON.parse(line) + const copy = copies.find( + (c) => + posix(row.key ?? ``).startsWith(`${c} > `) || + posix(row.file ?? ``) === c, + ) + if (copy && row.skipped) skipped.add(copy) + if (copy && row.closed) loaded.set(copy, row.loaded ?? []) + if (copy && row.spin) spun.add(copy) + if (copy && !row.closed && !row.idle && !row.spin && !row.started) + rows.get(copy).push(row) + } + return rows + } + const skippedUnit = (item) => ({ file: item.file, skipped: true }) + // A copy that ran past its call budget, even one whose throw ended the + // loop and let it finish, is a timeout as it stands (a count, not a + // clock: no confirming run). + const spunUnit = (item) => ({ + file: item.file, + timedOut: true, + spin: true, + seconds, + }) if (result === undefined) { // Cancelled without waiting; the caller replaces the context (see // runUnit). @@ -1295,10 +1305,13 @@ export default async (env) => { // A run cut off by a hang is still running: its worker may still send // updates, so its state is not touched here. Its context is replaced // by the caller (replace), which closes it and drops its state. - if (result !== undefined) { + clearTimeout(timer) + if (raced && result === undefined) + retiredEntries(context, before, copies, true) + else { retireCopies(context, copies) retiredEntries(context, before, copies) - } else retiredEntries(context, before, copies, true) + } rmSync(capture, { force: true }) } } @@ -1403,10 +1416,12 @@ export default async (env) => { const totals = { // The cold check's store: units it keeps for reuse (none, see evidence.mjs). store: heldUnits(), - // Maps keyed by a context: each holds one entry per live context. A replaced - // context left in one is stale: the excess over the live contexts. - staleIndexed: indexOf.size - contexts.length, - staleSpecs: contextSpecs.size - contexts.length, + // Identities, not sizes: a registry entry is stale unless it names a live context at its own slot + // (indexOf), or a live context (contextSpecs). Open contexts (not closed) must be the live ones. + staleIndexed: [...indexOf].filter(([c, i]) => contexts[i] !== c).length, + staleSpecs: [...contextSpecs.keys()].filter((c) => !contexts.includes(c)) + .length, + staleOpen: openContexts.size - contexts.length, filesMap: filesMap.size, pathsSet: pathsSet.size, idMap: idMap.size, @@ -1481,7 +1496,7 @@ export default async (env) => { environment.moduleGraph.fileToModulesMap.get(copy)?.size ?? 0 appendFileSync( file, - `${JSON.stringify(cut ? { run: hookRun, batch: evidenceOf.batches, before, cut: true } : { run: hookRun, batch: evidenceOf.batches, before, after: retentionTotals(context), copyNodes, nonCopyDup: nonCopyDuplicates(context, owned).length, nonCopyIds: nonCopyDuplicates(context, owned) })}\n`, + `${JSON.stringify(cut ? { run: hookRun, batch: evidenceOf.batches, before, cut: true } : { run: hookRun, batch: evidenceOf.batches, before, after: retentionTotals(context), copyNodes, nonCopyDup: nonCopyDuplicates(context, owned).length })}\n`, ) } diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index b0806f03..643146fa 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -805,15 +805,21 @@ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { only: ids, pool: abort ? `threads` : pool, }) + // The retention hook is set on every stop, so a stopped run's completed batches are judged too. + const hook = hookOf(dir) const child = spawn(process.execPath, args, { cwd: repo, - env: after - ? { ...cleanEnv(), ORACLE_GAPS_TEST_HOLD_EXIT_MS: `500` } - : warm - ? { ...cleanEnv(), ORACLE_GAPS_TEST_WARM_PROBE: join(pids, `warming`) } - : abort - ? { ...cleanEnv(), GAP_ABORT: `1` } - : { ...cleanEnv(), GAP_STOP_DIR: pids }, + env: { + ...cleanEnv(), + ORACLE_GAPS_TEST_RETENTION: hook, + ...(after + ? { ORACLE_GAPS_TEST_HOLD_EXIT_MS: `500` } + : warm + ? { ORACLE_GAPS_TEST_WARM_PROBE: join(pids, `warming`) } + : abort + ? { GAP_ABORT: `1` } + : { GAP_STOP_DIR: pids }), + }, stdio: [`ignore`, `pipe`, `pipe`], }) let stdout = `` @@ -897,6 +903,10 @@ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { survivors: alive.length, strayWhileRunning, when: when ?? `run`, + // The batches this run completed, each with its retention line (the hook above). + retention: retentionLinesOf(hook).filter( + (line) => line.run === join(dir, `out-stop`), + ), // Whether a refusal's block reached stderr: a stop is never a refusal. refused: stderr.split(`\n`).some((line) => line.startsWith(`refused: `)), exit: exitCode, @@ -1785,7 +1795,15 @@ async function driver(plan, observe) { // of them the previous stopped run had left. if (cli.exit === 0 && stopIds.length > 0) for (const stop of plan.stopRuns) { - const run = await stoppedRun(dir, files, how, stopIds, stop) + const { retention, ...run } = await stoppedRun( + dir, + files, + how, + stopIds, + stop, + ) + observe(`retention:stop`, retention.filter(leftBehind).length) + observe(`retentionKeys:stop`, leftKeys(retention)) const stopped = { ...run, sessions: { From 127a2b7fa7ce4628504ca3c2d3704bae2081a977 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 16:42:36 -0700 Subject: [PATCH 31/61] docs(oracles): the retention test hook is documented in the package README ORACLE_GAPS_TEST_RETENTION is inert unless set, observes only, and its line format is the one the bounded-retention law reads. The register's test-only hooks entry requires it to be documented. #57's test section is not merged yet, so this section stands on its own. Co-authored-by: Isaac --- packages/oracles/README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/packages/oracles/README.md b/packages/oracles/README.md index a2452c5b..91bbd196 100644 --- a/packages/oracles/README.md +++ b/packages/oracles/README.md @@ -14,3 +14,9 @@ Show me what oracle testing with @tanstack/oracles can find in this repository. 3. Read node_modules/@tanstack/oracles/skills/oracles-explore/SKILL.md in full, and follow it. Use wherever a skill asks for the commit to pin. ``` + +## Test hooks + +`ORACLE_GAPS_TEST_RETENTION` (a file path, unset in normal use) makes the gap CLI append one JSON line per mutant batch it runs, cut or not. It only observes: it never changes an outcome. The e2e oracle reads it to check bounded retention. + +Each line has `run` (the run's `--out` path), `batch` (the batch count so far), and `before` (Vitest's and Vite's structure sizes before the batch). A settled batch also has `after` (the sizes after its copies are retired), `copyNodes` (Vite module nodes that still name a copy, must be 0), and `nonCopyDup` (non-copy files with more than one module node in an environment, must be 0 beyond the measured plain-plus-`?raw` pair). A cut batch has `cut: true` and no `after`. The `stale*` fields count registry entries that name no live context, and `staleOpen` counts open contexts beyond the live ones; all must be 0 before a batch. From 65880b6090568dad3b46748fad5aba62ccf3a6fb Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 17:02:40 -0700 Subject: [PATCH 32/61] fix(oracle-gaps): the open-context identity counts a slot being replaced The GREEN run of 79f1dea failed the retention law on staleOpen: a batch on one slot measured the open contexts while another slot's replacement had closed its context and not yet opened the next, so open was one short of the contexts array. That window is legal, so the identity now counts the slots being replaced: open + replacing === contexts.length holds at every batch boundary (a window that the registry swap already covers for indexOf and contextSpecs). Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index ab255da0..1b944865 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -595,6 +595,9 @@ export default async (env) => { } // The contexts that are open (warmed and not yet closed): the replaced ones must leave it. const openContexts = new Set() + // Slots between closing their context and opening the next: their open count is one short, for the + // retention law's identity (open + replacing === contexts.length), which holds at every batch boundary. + let replacing = 0 const closeContext = (context) => { openContexts.delete(context) return context.close().finally(() => allowListeners(-1)) @@ -1421,7 +1424,7 @@ export default async (env) => { staleIndexed: [...indexOf].filter(([c, i]) => contexts[i] !== c).length, staleSpecs: [...contextSpecs.keys()].filter((c) => !contexts.includes(c)) .length, - staleOpen: openContexts.size - contexts.length, + staleOpen: openContexts.size + replacing - contexts.length, filesMap: filesMap.size, pathsSet: pathsSet.size, idMap: idMap.size, @@ -1952,12 +1955,14 @@ export default async (env) => { // it stops the worker. const replace = async (slot) => { const started = Date.now() + replacing += 1 await Promise.race([ closeContext(slot.context).catch(() => undefined), sleep(10_000), ]) const replaced = slot.context const next = await warmContext(settings, slot.index) + replacing -= 1 const specs = await specsOf(next) // One synchronous step: the replaced context leaves every map keyed by it and the new one joins them, // with the contexts array, so no reader (and no measurement) sees the registry and the array disagree. From 1b983e18cdb5b48393ba5c5ae9008e1b793a756b Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 17:55:53 -0700 Subject: [PATCH 33/61] test(oracle-gaps): a batch whose run rejects is a constructed history with its own retention law The crash path (79f1dea) had no reach: no constructed history made a batch's run reject. This adds a test-only fault, ORACLE_GAPS_TEST_REJECT_BATCH= (inert unless set): the n-th batch's run promise rejects, as a crash in Vitest would, so the CLI's rejection path runs (register: test-only hooks). Model (the constructed history's rejectBatch field): the run ends as an internal error, exit 3 with its done error line (ending.mjs, index.mjs). Its batch's copies are retired and its retention line is written with its state after retirement. The retention law is judged before the ending, so a missing line or unretired copies fail on retention, not only on exit. The law 12 limits text names this one constructed fault and nothing wider. Law: the rejected batch's retention line exists and is retired (bounded retention, register C). Authority: ending.mjs (an internal error exits 3 with a done error line), and P10. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 17 ++++-- .../oracle-gaps/gap-report-model-oracle.mjs | 2 + .../gap-report-oracle.property.test.mjs | 57 ++++++++++++++++++- 3 files changed, 70 insertions(+), 6 deletions(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index 1b944865..b7bb4944 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -1096,10 +1096,19 @@ export default async (env) => { writeFileSync(join(out, `state.json`), JSON.stringify(state)) const project = context.getRootProject() const started = Date.now() - const running = context.runTestSpecifications( - copies.map((copy) => project.createSpecification(copy)), - false, - ) + // Test-only fault (ORACLE_GAPS_TEST_REJECT_BATCH=, inert unless set): the n-th batch's run rejects, + // as a crash in Vitest would, so the CLI's rejection path runs (register: test-only hooks). + const running = + process.env.ORACLE_GAPS_TEST_REJECT_BATCH === String(evidenceOf.batches) + ? Promise.reject( + new Error( + `oracle-gaps test fault: batch ${evidenceOf.batches} rejected`, + ), + ) + : context.runTestSpecifications( + copies.map((copy) => project.createSpecification(copy)), + false, + ) // The watchdog: each copy writes a starting row when its setup runs and // a closing row when it finishes, so the copy that is running is the // last that started, or the one after it once that one closed. A copy diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index 6ebe9f35..65e3c811 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -4449,6 +4449,8 @@ function model(plan) { const gaps = entries.map((e) => e.key) return { configLines, + // The batch whose run the model predicts rejects (a constructed fault): the run ends as an internal error. + rejectedBatch: plan.rejectBatch, baseline: baselineOf(plan), blocking: blockingOf(plan).filter((f) => !f.ordinary), replayed: blockingOf(plan).find((f) => f.replayed)?.replayed, diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 643146fa..89ad4345 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -723,7 +723,7 @@ function runCli(dir, files, how = {}) { encoding: `utf8`, timeout: 300_000, maxBuffer: 64 * 1024 * 1024, - env: { ...cleanEnv(), ORACLE_GAPS_TEST_RETENTION: hook }, + env: { ...cleanEnv(), ORACLE_GAPS_TEST_RETENTION: hook, ...how.env }, }) // Each line names its check's output directory, so this run keeps only its own (a daemon serves many calls). const retention = retentionLinesOf(hook).filter((line) => line.run === out) @@ -1730,6 +1730,9 @@ async function driver(plan, observe) { budget: plan.budget, cli: plan.cliPath === `spaced` ? copy : here, ...configArgs(plan), + ...(plan.rejectBatch === undefined + ? {} + : { env: { ORACLE_GAPS_TEST_REJECT_BATCH: String(plan.rejectBatch) } }), } const { replay, retention, ...cli } = runCli(dir, files, how) // How many units were computed or reused says how the result was @@ -1739,6 +1742,19 @@ async function driver(plan, observe) { // not the per-batch lines, whose batch splits vary with hang cuts. observe(`retention`, retention.filter(leftBehind).length) observe(`retentionKeys`, leftKeys(retention)) + // A rejected batch (a constructed fault) owes its own retention line, written after its copies retire. + if (plan.rejectBatch !== undefined) { + observe( + `retentionLines:reject`, + retention.some((line) => line.batch === plan.rejectBatch) ? 0 : 1, + ) + if ( + retention.some( + (line) => line.batch === plan.rejectBatch && line.after !== undefined, + ) + ) + states.add(`a rejected batch retired its copies and logged them`) + } observe( `retentionLines:cold`, unlogged({ retention, evidence: cli.evidence }), @@ -2363,6 +2379,20 @@ function check(plan, observations, expected) { `bounded retention`, { actual: held, expected: 0 }, ) + // A rejected batch (the constructed fault) ends the run as an internal error: exit 3 and its done line + // (ending.mjs). Retention was judged above, so only the ending is judged here, and the run is then done. + if (expected.rejectedBatch !== undefined) { + if ( + cli.exit !== 3 || + !cli.stderr?.includes(`oracle-gaps: done error, log `) + ) + return violation( + `cli`, + `the rejected batch owes exit 3 and an internal error's done line, got exit ${cli.exit}: ${cli.stderr ?? `no stderr`}`, + `internal error`, + ) + return pass + } // Through the daemon, each check streams the same kinds of line, and a // completed one ends with its done line (law 15). The state of each step // differs, so its verdict and counts are judged by law 9's comparison. @@ -3502,6 +3532,7 @@ const separate = [ `an edit that changed the cold result after a hang replaced the only context`, `edit lazy changed the cold result`, `a lazy edit changed the cold result after a batch was cut off`, + `a rejected batch retired its copies and logged them`, ] const witnessed = required.filter((s) => !separate.includes(s)) @@ -3528,7 +3559,7 @@ oracleProperty({ law: { statement: `The gap report enumerates the promised operator mutants, leaves out exactly the probe-only code, discovers every oracle that owns a function's call tree and refuses broken ownership, judges each mutant only by its owners' tests on their registered routes and counts only law verdicts on reproducible routes as kills, which outrank a run that never ends, anchors each mutant by its function and normalized statement, lists every gap and unowned mutant once with consistent counts, keeps keys stable under unrelated edits, reports through one daemon per package what a cold run reports at every state of a sequence of edits, and bounds the runs that confirm a mutant's cut-off copies by one budget per mutant and names each busy mutant in a heartbeat while it runs, leaves nothing in the package and writes nothing where Vitest's include could find it while it runs, leaves no process running once it is stopped, runs the package as Vitest does from any install path and any --source spelling: one instance of each workspace dependency, no refusal over an unbuildable devDependency, child processes for a native addon anywhere in the tree, a capture that a test's builtin spies cannot see, and a refusal of test.projects; leads its report with every test file's baseline, blocks only the mutants a failing oracle file owns and judges the rest, prints every line of its stream with the prefix oracle-gaps: and its kind, one decisive baseline line before any mutant, and a done line last, and every run that does not complete ends, cold or through the daemon, with a refusal that exits 2, prints a refused: block and one fix: directive with no stack trace, and writes the refusal to the run's output directory.`, authority: `The maintainer's decisions in design runs v11, v14, and v19 (2026-11-04 and 2026-11-05), not in this package's records, including that a kill by reach agreement alone is a gap and that an incremental run through the daemon equals a cold one (v19.3); the project's oracle guide on quiet exclusions; the oracle rubric's outcome kinds (ORC-006); the CLI's documented operator list in schemata.mjs; the maintainer's dispositions G1, G2, G4, G5, G6, and G13 of the framework papercut ledger (2026-11-11) and the v20 freeze's namespacing, one-loop, and provisional-report decisions (2026-11-10); the maintainer's request for a greppable stream (2026-11-12, relayed by the coordinator with its decisions of that day: the same prefixes on stdout and stderr, a done line for a stopped run, and no --max-gaps).`, - limits: `Law 12 judges refusals only: no legal history reaches an internal error, so its shape (exit 3, the stack in error.log) is not judged; argument refusals are the static oracle's; the check's rejection of a stack trace, a missing fix, and a wrong exit code is calibrated in the static oracle, through the same refusalBreach, and here only a refused run reported as complete is calibrated, because each calibration here runs real CLI histories. Hangs only as an owner test that awaits a promise that never settles, under a 1 s first budget and a 20 s full limit, and a slow run only as two witnesses whose tests wait where the output changed, 3 s in one that then judges and 10 s in two one-test owners of one that does not; busy loops only on instrumented code (cut by the call budget), no slow runs past the full limit that would end, hangs in ordinary or nondeterministic tests, setup errors other than a throw at module load, loops, multi-line conditions, two functions on one line, or await, new, and void statements; nested functions, object-literal methods, accessors, and class-field arrows only where no test calls them (their ownership is the static oracle's); two source files of one package, with no re-exports, namespace imports, or calls into another package; --only only in a stopped run and a partial run of one function's mutants, and no --sample or --diff-base; the baseline's failures only as one failing owner test that throws an error and a setup file that throws, so a baseline law violation's law and counterexample lines are the classify oracle's; a derived class's file is instrumented and its sites are judged as unowned, but no test imports or constructs the class, so its no-mutant and super-region behavior is the static oracle's (in-process), not this oracle's; package configs only as vite.config or vitest.config with one of the extensions .ts, .mts, .cts, .js, .mjs, and .cjs (not every pair), as config/gap-vitest with the same extension through --config, or none, as an object or a sync or async function, with no plugins of their own and test.projects only as a refusal, and only under the package's own package.json; a top-level await only in an ES module config and require only in a CommonJS one, as Vitest itself loads no other; a --config outside the package is refused by design, through the rule for paths outside the package (args.mjs), and no history generates one; contexts only one, four, or eleven, and process warnings judged only as MaxListenersExceededWarning on the CLI's own stderr (a daemon's process warnings go to its log); a context that fails to open gives back its listener allowance, which no observation shows (a kept allowance only raises the limit, so no warning follows), so that accounting is fixed by inspection; no probe-bound states, so reach agreement's killing of probe mutants is not checked; no gap answers or gate; law 9 judges the witness module's outcome classes along one constructed edit sequence only (a test edit, a helper edit, and a revert), and the budget witness's along one constructed second check with nothing changed, because a generated history with the witness module or the budget witness takes no steps (maintainer decision, 2026-11-11, and the runtime review's P1-a, 2026-11-12; this oracle owns the gap); law 9's edits come only between checks, so a file saved during a check is not generated (the runner invalidates a known input that changed while a run ran and does not store that run, which only inspection fixes; a witness needs a step that edits a file between a unit's start and its end), and a module that a run first loads and that changes during that same run is stored under its later hash; law 9's edits leave out files read through fs, other environment variables, new files that change how an unchanged import resolves, Vite config and installed-package changes, and concurrent checks other than two that start the daemon; cut-off charging judged only under one budget; native addons only as a binding.gyp or a prebuilt .node file, not as optional platform packages; daemon races (two CLIs reading one error file, a CLI hearing closing from the failing daemon it started, a reset connection on macOS) fixed by inspection; the runner's copies of the test files exist only in memory, and its harness and Vitest configs sit in the package's .oracle-gaps-, which the next run removes once a killed run has left it (judged after two stopped runs, not after a SIGKILL); a default --out is judged by the static oracle, and these runs name --out in the package; the namespace is checked after each run and, in a stopped run, while the run runs; a slow kill in a later owner, after earlier owners' confirmations spent the budget, becomes a timeout (owner order; not generated); the Vitest 5 path of the copies' pragma read and of the runner is verified from Vitest 5's source only, since the Vitest 5 CI job runs no gap oracle; a batch whose run reports an error outside any test reruns each copy alone (unitsBatch, runAlone) with its first budget, and a copy cut there is kept as a timeout with no confirmation, a defect older than this oracle's budget work that no history reaches (no history has an error outside any test beside a slow copy), recorded here with that trace for the maintainer; stale-session removal is scoped to this host's session directories (a host file), and is not judged across pid namespaces; the stop law covers SIGTERM and SIGINT sent to the CLI, not a SIGKILL of the CLI (its group then ends at the next check of its parent, by inspection) or a signal sent to the daemon, and its witness is one test that spins synchronously and starts one child process; the mutant budget is witnessed as two slow owners whose confirmations pass the --mutant-limit floor, not through its multiple of the owners' unmutated time, and authored mutants have no confirmations to budget; the witness w_slowpair is a wall-clock window, since the CLI's budget has no controlled clock and a fixture cannot see the time the CLI measures for its file: with one-test owner files p and q of measured unmutated time t each (a file first in its context pays the instrumented transform too), a wait W of 10 s, a 20 s --hang-limit and a 15 s --mutant-limit, it tells a budget from none only while (a) its first attempt is cut, W > 1 s + 3t, (b) its two confirmations do not fit the budget, 2W > max(15 s, 10 x 2t), and (c) each would fit its own full limit, W < 20 s + 3t; (b) is the binding one, so it holds while the two files' time stays under about 2 s together (about 1 s each, some 20 times the authoring machine's idle and 5 to 10 times its loaded measurements), and under one budget a run's overhead must stay under 10 s + 3t; CI runners measure 1.5 to 2.3 times the idle machine; beyond that w_slowpair would read not-judged; a heartbeat is owed only where a slow test waits 3 s against a 2 s interval, twice the first budget, so that no copy cut at its first budget beats, and each beat is observed as its mutant and file, not how long or how often it beat; a config only in the package's parent directory is generated one level up, in a temporary directory with no package.json (so its .js or .ts name is CommonJS), as a plain config, one that throws, one with no default export, or one that defines test.projects; a config two or more levels up, or a parent config beside a package config, is not generated, and the order in one directory follows Vitest's configFiles list by inspection; a package with no config lives in a temporary directory, where no parent has a config; a counterexample shrinks through at most six histories, so it can be larger than the smallest that fails; module-level data only as four \`const\` declarations of the main source (an object literal, an array that holds a function, a boolean, and an object of two methods), read in place, with no data imported from another file, destructured, reassigned, or declared as an enum or a default export; the work law only through shortcut witnesses (an early return before a counting loop with a bound twin of ratio 2, and a push beside one that calls String with a bound twin of ratio 1), the early return in tests that reach the clock by each watched path and in tests that wait a turn, a generated test's bound of 1 derived from its plan (which no generated function's mutant reached in the 36 fixed-seed units), and one warm-cache witness whose selection reproduces observations but not work; work is the capture's count of site evaluations per test, so code with no site (a plain assignment, a for...of pass, a builtin's own work) counts nothing and a test's histories are summed, and a test whose work varies between the unmutated runs while its observations agree is not generated.`, + limits: `Law 12 judges refusals only, and the constructed rejected-batch history (rejectBatch, a test-only fault) only as exit 3 with its internal-error done line, with its retention judged first; no legal history reaches an internal error otherwise, so its shape (the stack in error.log) is not judged; argument refusals are the static oracle's; the check's rejection of a stack trace, a missing fix, and a wrong exit code is calibrated in the static oracle, through the same refusalBreach, and here only a refused run reported as complete is calibrated, because each calibration here runs real CLI histories. Hangs only as an owner test that awaits a promise that never settles, under a 1 s first budget and a 20 s full limit, and a slow run only as two witnesses whose tests wait where the output changed, 3 s in one that then judges and 10 s in two one-test owners of one that does not; busy loops only on instrumented code (cut by the call budget), no slow runs past the full limit that would end, hangs in ordinary or nondeterministic tests, setup errors other than a throw at module load, loops, multi-line conditions, two functions on one line, or await, new, and void statements; nested functions, object-literal methods, accessors, and class-field arrows only where no test calls them (their ownership is the static oracle's); two source files of one package, with no re-exports, namespace imports, or calls into another package; --only only in a stopped run and a partial run of one function's mutants, and no --sample or --diff-base; the baseline's failures only as one failing owner test that throws an error and a setup file that throws, so a baseline law violation's law and counterexample lines are the classify oracle's; a derived class's file is instrumented and its sites are judged as unowned, but no test imports or constructs the class, so its no-mutant and super-region behavior is the static oracle's (in-process), not this oracle's; package configs only as vite.config or vitest.config with one of the extensions .ts, .mts, .cts, .js, .mjs, and .cjs (not every pair), as config/gap-vitest with the same extension through --config, or none, as an object or a sync or async function, with no plugins of their own and test.projects only as a refusal, and only under the package's own package.json; a top-level await only in an ES module config and require only in a CommonJS one, as Vitest itself loads no other; a --config outside the package is refused by design, through the rule for paths outside the package (args.mjs), and no history generates one; contexts only one, four, or eleven, and process warnings judged only as MaxListenersExceededWarning on the CLI's own stderr (a daemon's process warnings go to its log); a context that fails to open gives back its listener allowance, which no observation shows (a kept allowance only raises the limit, so no warning follows), so that accounting is fixed by inspection; no probe-bound states, so reach agreement's killing of probe mutants is not checked; no gap answers or gate; law 9 judges the witness module's outcome classes along one constructed edit sequence only (a test edit, a helper edit, and a revert), and the budget witness's along one constructed second check with nothing changed, because a generated history with the witness module or the budget witness takes no steps (maintainer decision, 2026-11-11, and the runtime review's P1-a, 2026-11-12; this oracle owns the gap); law 9's edits come only between checks, so a file saved during a check is not generated (the runner invalidates a known input that changed while a run ran and does not store that run, which only inspection fixes; a witness needs a step that edits a file between a unit's start and its end), and a module that a run first loads and that changes during that same run is stored under its later hash; law 9's edits leave out files read through fs, other environment variables, new files that change how an unchanged import resolves, Vite config and installed-package changes, and concurrent checks other than two that start the daemon; cut-off charging judged only under one budget; native addons only as a binding.gyp or a prebuilt .node file, not as optional platform packages; daemon races (two CLIs reading one error file, a CLI hearing closing from the failing daemon it started, a reset connection on macOS) fixed by inspection; the runner's copies of the test files exist only in memory, and its harness and Vitest configs sit in the package's .oracle-gaps-, which the next run removes once a killed run has left it (judged after two stopped runs, not after a SIGKILL); a default --out is judged by the static oracle, and these runs name --out in the package; the namespace is checked after each run and, in a stopped run, while the run runs; a slow kill in a later owner, after earlier owners' confirmations spent the budget, becomes a timeout (owner order; not generated); the Vitest 5 path of the copies' pragma read and of the runner is verified from Vitest 5's source only, since the Vitest 5 CI job runs no gap oracle; a batch whose run reports an error outside any test reruns each copy alone (unitsBatch, runAlone) with its first budget, and a copy cut there is kept as a timeout with no confirmation, a defect older than this oracle's budget work that no history reaches (no history has an error outside any test beside a slow copy), recorded here with that trace for the maintainer; stale-session removal is scoped to this host's session directories (a host file), and is not judged across pid namespaces; the stop law covers SIGTERM and SIGINT sent to the CLI, not a SIGKILL of the CLI (its group then ends at the next check of its parent, by inspection) or a signal sent to the daemon, and its witness is one test that spins synchronously and starts one child process; the mutant budget is witnessed as two slow owners whose confirmations pass the --mutant-limit floor, not through its multiple of the owners' unmutated time, and authored mutants have no confirmations to budget; the witness w_slowpair is a wall-clock window, since the CLI's budget has no controlled clock and a fixture cannot see the time the CLI measures for its file: with one-test owner files p and q of measured unmutated time t each (a file first in its context pays the instrumented transform too), a wait W of 10 s, a 20 s --hang-limit and a 15 s --mutant-limit, it tells a budget from none only while (a) its first attempt is cut, W > 1 s + 3t, (b) its two confirmations do not fit the budget, 2W > max(15 s, 10 x 2t), and (c) each would fit its own full limit, W < 20 s + 3t; (b) is the binding one, so it holds while the two files' time stays under about 2 s together (about 1 s each, some 20 times the authoring machine's idle and 5 to 10 times its loaded measurements), and under one budget a run's overhead must stay under 10 s + 3t; CI runners measure 1.5 to 2.3 times the idle machine; beyond that w_slowpair would read not-judged; a heartbeat is owed only where a slow test waits 3 s against a 2 s interval, twice the first budget, so that no copy cut at its first budget beats, and each beat is observed as its mutant and file, not how long or how often it beat; a config only in the package's parent directory is generated one level up, in a temporary directory with no package.json (so its .js or .ts name is CommonJS), as a plain config, one that throws, one with no default export, or one that defines test.projects; a config two or more levels up, or a parent config beside a package config, is not generated, and the order in one directory follows Vitest's configFiles list by inspection; a package with no config lives in a temporary directory, where no parent has a config; a counterexample shrinks through at most six histories, so it can be larger than the smallest that fails; module-level data only as four \`const\` declarations of the main source (an object literal, an array that holds a function, a boolean, and an object of two methods), read in place, with no data imported from another file, destructured, reassigned, or declared as an enum or a default export; the work law only through shortcut witnesses (an early return before a counting loop with a bound twin of ratio 2, and a push beside one that calls String with a bound twin of ratio 1), the early return in tests that reach the clock by each watched path and in tests that wait a turn, a generated test's bound of 1 derived from its plan (which no generated function's mutant reached in the 36 fixed-seed units), and one warm-cache witness whose selection reproduces observations but not work; work is the capture's count of site evaluations per test, so code with no site (a plain assignment, a for...of pass, a builtin's own work) counts nothing and a test's histories are summed, and a test whose work varies between the unmutated runs while its observations agree is not generated.`, }, histories: { // A failing history shrinks through at most six smaller ones. Each runs @@ -4238,6 +4269,28 @@ oracleProperty({ steps: [`lazy`], }), }, + { + // A batch whose run rejects (the test-only fault ORACLE_GAPS_TEST_REJECT_BATCH): the CLI ends with an + // internal error, exit 3 and its done error line (ending.mjs). The batch's copies are retired, and its + // retention line is written with its state after retirement (the bounded retention law). + name: `a batch whose run rejects`, + enters: [`a rejected batch retired its copies and logged them`], + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + wholeFile: `none`, + witness: false, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, + steps: null, + rejectBatch: 1, + }), + }, ]), }, resolve: resolveHistory, From ecbd9a9602d6272746484eef4b3a349b7ab0471c Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 17:58:06 -0700 Subject: [PATCH 34/61] test(oracle-gaps): the rejected-batch state is declared in the required list The constructed history names its state; the state was added to the separate list instead of required, so the framework refused the history as naming undeclared states (its own check, before any run). Co-authored-by: Isaac --- .../oracles/oracle-gaps/gap-report-oracle.property.test.mjs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 89ad4345..7d13452b 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -3487,6 +3487,7 @@ const faults = [ `configSyntax`, `setupThrows`, ...analyzedFaults, + `a rejected batch retired its copies and logged them`, ] const separate = [ `ordinary tests left out by default`, @@ -3532,7 +3533,6 @@ const separate = [ `an edit that changed the cold result after a hang replaced the only context`, `edit lazy changed the cold result`, `a lazy edit changed the cold result after a batch was cut off`, - `a rejected batch retired its copies and logged them`, ] const witnessed = required.filter((s) => !separate.includes(s)) From 4f387314cd120db840034e02a6f75d1a64df9be6 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 17:59:11 -0700 Subject: [PATCH 35/61] test(oracle-gaps): the rejected-batch state is in the required list, not the faults list The previous commit placed the state in the faults array (the nearest list above separate), so the framework generated a declaration-fault variant that named it. It is removed from faults and declared in required. Co-authored-by: Isaac --- .../oracles/oracle-gaps/gap-report-oracle.property.test.mjs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 7d13452b..7341a633 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -3450,6 +3450,7 @@ const required = [ `an edit that changed the cold result after a hang replaced the only context`, `edit lazy changed the cold result`, `a lazy edit changed the cold result after a batch was cut off`, + `a rejected batch retired its copies and logged them`, ] // The faults the CLI analyzes anyway: a package's TypeScript is no input. const analyzedFaults = [`noTypescript`, `apiLessTypescript`] @@ -3487,7 +3488,6 @@ const faults = [ `configSyntax`, `setupThrows`, ...analyzedFaults, - `a rejected batch retired its copies and logged them`, ] const separate = [ `ordinary tests left out by default`, From 668f1659cb9cf83037c65e5d4b25586375e952dd Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 18:00:48 -0700 Subject: [PATCH 36/61] test(oracle-gaps): the rejected-batch history builds from the ordinary history's shape Its build is the ordinary constructed history's (primitive leaves, judging() tests, the same fields), plus rejectBatch: 1, so the framework can take it back for shrinking. The earlier build was refused as not takeable back. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 7341a633..620f5332 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -4287,6 +4287,7 @@ oracleProperty({ authored: null, fault: `none`, stability: `none`, + ordinary: false, steps: null, rejectBatch: 1, }), From 253b861ed589c28a7b9d5ab7b6c3d6044ee83fc9 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 18:02:36 -0700 Subject: [PATCH 37/61] test(oracle-gaps): rejectBatch is a generated field (0: no fault), appended to the history record The constructed rejected-batch history carried a field the generated record did not declare, so the framework refused it as outside the arbitrary's language. rejectBatch is now a generated constant (0 is no fault), appended at the end of the record, so it draws nothing and fixed seeds keep their histories (the generator rule). The driver and the model treat 0 as no fault. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/gap-report-model-oracle.mjs | 5 ++++- .../oracle-gaps/gap-report-oracle.property.test.mjs | 8 ++++---- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index 65e3c811..7b46e291 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -769,6 +769,9 @@ const drawn = fc.record({ }), // Who names the importer's function in an owns entry, if any. importer: fc.constantFrom(`none`, `a`, `b`), + // The batch whose run rejects (a test-only fault, see the constructed history at the end of the + // campaign): 0 is no fault. A constant draws nothing, so fixed seeds keep their histories. + rejectBatch: fc.constant(0), }) // The edit sequence over the witness module, the one list of steps that a @@ -4450,7 +4453,7 @@ function model(plan) { return { configLines, // The batch whose run the model predicts rejects (a constructed fault): the run ends as an internal error. - rejectedBatch: plan.rejectBatch, + rejectedBatch: plan.rejectBatch > 0 ? plan.rejectBatch : undefined, baseline: baselineOf(plan), blocking: blockingOf(plan).filter((f) => !f.ordinary), replayed: blockingOf(plan).find((f) => f.replayed)?.replayed, diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 620f5332..8502c5ad 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1730,9 +1730,9 @@ async function driver(plan, observe) { budget: plan.budget, cli: plan.cliPath === `spaced` ? copy : here, ...configArgs(plan), - ...(plan.rejectBatch === undefined - ? {} - : { env: { ORACLE_GAPS_TEST_REJECT_BATCH: String(plan.rejectBatch) } }), + ...(plan.rejectBatch > 0 + ? { env: { ORACLE_GAPS_TEST_REJECT_BATCH: String(plan.rejectBatch) } } + : {}), } const { replay, retention, ...cli } = runCli(dir, files, how) // How many units were computed or reused says how the result was @@ -1743,7 +1743,7 @@ async function driver(plan, observe) { observe(`retention`, retention.filter(leftBehind).length) observe(`retentionKeys`, leftKeys(retention)) // A rejected batch (a constructed fault) owes its own retention line, written after its copies retire. - if (plan.rejectBatch !== undefined) { + if (plan.rejectBatch > 0) { observe( `retentionLines:reject`, retention.some((line) => line.batch === plan.rejectBatch) ? 0 : 1, From e7883f91643e9354100595aa636ddd2c3b012126 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 18:03:56 -0700 Subject: [PATCH 38/61] test(oracle-gaps): rejectBatch draws 0 or 1, appended last in the draw order A constant of 0 admits only 0, so the constructed rejected-batch history (1) is outside the generated language and the framework refuses it. The field now draws 1 with weight 1 in 200, appended last in the draw order, which is the generator rule for a new history field. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/gap-report-model-oracle.mjs | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index 7b46e291..929e90a1 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -770,8 +770,12 @@ const drawn = fc.record({ // Who names the importer's function in an owns entry, if any. importer: fc.constantFrom(`none`, `a`, `b`), // The batch whose run rejects (a test-only fault, see the constructed history at the end of the - // campaign): 0 is no fault. A constant draws nothing, so fixed seeds keep their histories. - rejectBatch: fc.constant(0), + // campaign): 0 is no fault. Appended last in the draw order (the generator rule), so existing fields + // draw as before. + rejectBatch: fc.oneof( + { weight: 199, arbitrary: fc.constant(0) }, + { weight: 1, arbitrary: fc.constant(1) }, + ), }) // The edit sequence over the witness module, the one list of steps that a From e3dc2b02944854b396be4299793dd1b8d1377529 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 18:07:36 -0700 Subject: [PATCH 39/61] test(oracle-gaps): the resolved plan carries rejectBatch resolveHistory returns the plan from explicit fields, so the rejected-batch fault was dropped and the constructed run never rejected: the history did not enter its state. The plan now carries it. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/gap-report-model-oracle.mjs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index 929e90a1..6c210762 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -2829,6 +2829,8 @@ function resolveHistory(history) { // the test that aborts when the driver asks. aborts: (history.stopRuns ?? []).some((stop) => stop.when === `abort`), ordinary: history.ordinary === true, + // The batch whose run rejects (a test-only fault; 0 is none). + rejectBatch: history.rejectBatch ?? 0, // An `owns` key in an assertion's arguments, in the ordinary file: its // assertion form and whether its list is a literal, or none. matcherOwns: history.matcherOwns ?? `none`, From 43a4c7ca6ba123d8b613e30a80dfe436c4a23f84 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 18:09:04 -0700 Subject: [PATCH 40/61] test(oracle-gaps): the rejected batch's reach state is marked after its states set exists; its stream law is its own ending The reach mark ran before the states set was declared (a ReferenceError). The internal error's lines are not stream lines, so the stream law is skipped for a rejected batch, and its ending (exit 3 and the done error line) is judged after retention. Co-authored-by: Isaac --- .../gap-report-oracle.property.test.mjs | 20 ++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 8502c5ad..eb3ac4e8 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1748,12 +1748,6 @@ async function driver(plan, observe) { `retentionLines:reject`, retention.some((line) => line.batch === plan.rejectBatch) ? 0 : 1, ) - if ( - retention.some( - (line) => line.batch === plan.rejectBatch && line.after !== undefined, - ) - ) - states.add(`a rejected batch retired its copies and logged them`) } observe( `retentionLines:cold`, @@ -1764,6 +1758,13 @@ async function driver(plan, observe) { observe(`replay`, { command: replay, ran: replayed(dir, replay) }) // Reach comes from what the CLI reported, mapped onto the plan. const states = new Set() + if ( + plan.rejectBatch > 0 && + retention.some( + (line) => line.batch === plan.rejectBatch && line.after !== undefined, + ) + ) + states.add(`a rejected batch retired its copies and logged them`) if (retention.length > 1) states.add(`a check that ran more than one batch`) if (cli.exit === 0 && !plan.consoleOutput) states.add(`a completed run whose tests wrote nothing`) @@ -2342,7 +2343,12 @@ function check(plan, observations, expected) { `config`, { actual: cli.configLines, expected: expected.configLines }, ) - const stream = streamBreach(`cli`, cli, expected, plan) + // A rejected batch's run ends with the internal error's lines, which are not stream lines: its ending is + // judged below, after retention (the constructed fault only). + const stream = + expected.rejectedBatch === undefined + ? streamBreach(`cli`, cli, expected, plan) + : undefined if (stream) return stream // Bounded retention (the register's C entry): once a batch's copies are // retired, Vitest's filesMap, pathsSet, and idMap and Vite's module graph From 21cf7014ad12715c7db6fbbb104b275757c111ff Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 18:10:34 -0700 Subject: [PATCH 41/61] test(oracle-gaps): a rejected batch's run observes its exit, last line and the laws before retention The determinism check found the two runs of the rejected-batch history differ at observation 0 (cli), beyond the 2,000-character print (#81). Its stream lines before the batch come in no fixed order, which is not part of the contract. The observation keeps what is judged: the exit, the last line, the config lines, namespace strays and warnings. The ending check reads the last line. Co-authored-by: Isaac --- .../gap-report-oracle.property.test.mjs | 22 +++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index eb3ac4e8..09463815 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1736,8 +1736,22 @@ async function driver(plan, observe) { } const { replay, retention, ...cli } = runCli(dir, files, how) // How many units were computed or reused says how the result was - // produced, not what it is, so it is not observed. - observe(`cli`, { ...cli, evidence: undefined }) + // produced, not what it is, so it is not observed. A rejected batch's run ends in an internal error: + // the baseline lines printed before its batch come in no fixed order, so it observes its exit, its + // last line and the laws that judge the run before retention (the register: the order of streamed + // lines is not part of the contract). + observe( + `cli`, + plan.rejectBatch > 0 + ? { + exit: cli.exit, + lastLine: cli.lastLine, + configLines: cli.configLines, + strayWrites: cli.strayWrites, + warnings: cli.warnings, + } + : { ...cli, evidence: undefined }, + ) // Deterministic: how many batches left a retired copy's state behind (0), // not the per-batch lines, whose batch splits vary with hang cuts. observe(`retention`, retention.filter(leftBehind).length) @@ -2390,11 +2404,11 @@ function check(plan, observations, expected) { if (expected.rejectedBatch !== undefined) { if ( cli.exit !== 3 || - !cli.stderr?.includes(`oracle-gaps: done error, log `) + !cli.lastLine?.startsWith(`oracle-gaps: done error, log `) ) return violation( `cli`, - `the rejected batch owes exit 3 and an internal error's done line, got exit ${cli.exit}: ${cli.stderr ?? `no stderr`}`, + `the rejected batch owes exit 3 and an internal error's done line, got exit ${cli.exit} ending ${JSON.stringify(cli.lastLine)}`, `internal error`, ) return pass From 269f93822685a06c456f1e8c741ef22a7de40b1a Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 18:21:08 -0700 Subject: [PATCH 42/61] test(oracle-gaps): the rejected-batch state is separate, so the all-classes history does not enter it The all-outcome-classes history enters every required state that is not separate. The rejected batch's state needs its own history, so it is listed as separate (it stays required and declared). The fixed-seed shard 2 failed on the all-classes history for this reason. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 09463815..0d19816f 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -3553,6 +3553,7 @@ const separate = [ `an edit that changed the cold result after a hang replaced the only context`, `edit lazy changed the cold result`, `a lazy edit changed the cold result after a batch was cut off`, + `a rejected batch retired its copies and logged them`, ] const witnessed = required.filter((s) => !separate.includes(s)) From a3c3ffeb91d4790717b62a6ad733e938a6b76a49 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 18:25:36 -0700 Subject: [PATCH 43/61] docs(oracles): the rejected-batch test hook is documented in the package README ORACLE_GAPS_TEST_REJECT_BATCH is inert unless set and triggers the real rejection path. The register's test-only hooks entry requires it to be documented with its effect on the ending. Co-authored-by: Isaac --- packages/oracles/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/oracles/README.md b/packages/oracles/README.md index 91bbd196..a5b13b92 100644 --- a/packages/oracles/README.md +++ b/packages/oracles/README.md @@ -20,3 +20,5 @@ Show me what oracle testing with @tanstack/oracles can find in this repository. `ORACLE_GAPS_TEST_RETENTION` (a file path, unset in normal use) makes the gap CLI append one JSON line per mutant batch it runs, cut or not. It only observes: it never changes an outcome. The e2e oracle reads it to check bounded retention. Each line has `run` (the run's `--out` path), `batch` (the batch count so far), and `before` (Vitest's and Vite's structure sizes before the batch). A settled batch also has `after` (the sizes after its copies are retired), `copyNodes` (Vite module nodes that still name a copy, must be 0), and `nonCopyDup` (non-copy files with more than one module node in an environment, must be 0 beyond the measured plain-plus-`?raw` pair). A cut batch has `cut: true` and no `after`. The `stale*` fields count registry entries that name no live context, and `staleOpen` counts open contexts beyond the live ones; all must be 0 before a batch. + +`ORACLE_GAPS_TEST_REJECT_BATCH` (a batch number, unset in normal use) makes the gap CLI's n-th batch run reject, as a crash in Vitest would. It is a test-only fault: it triggers the same rejection path a real crash takes, and nothing else. The run then ends as an internal error: exit 3, the done error line on both streams, and `error.log` in its output directory. The batch's copies are still retired and its retention line is still written. From c0e3b0e381d43770965f82d6f17fb51c2263bf62 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 18:48:17 -0700 Subject: [PATCH 44/61] test(oracle-gaps): the rejected-batch history's three tests are in shard 3 The shard partition check found the fixed-seed, random-seed and determinism tests of the rejected-batch history in no shard (CI's Test job failed on it). They are added to e2e-3, where the fixed-seed history ran green. Co-authored-by: Isaac --- packages/oracles/scripts/e2e-shards.mjs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/packages/oracles/scripts/e2e-shards.mjs b/packages/oracles/scripts/e2e-shards.mjs index 986c4047..11a1c36e 100644 --- a/packages/oracles/scripts/e2e-shards.mjs +++ b/packages/oracles/scripts/e2e-shards.mjs @@ -113,6 +113,9 @@ export const shards = { `fixed seed 20261105: a stale authored mutant and a reformat`, `fixed seed 20261105: an awaiting config in a package with no module type`, `fixed seed 20261105: every outcome class`, + `fixed seed 20261105: a batch whose run rejects`, + `random seed: a batch whose run rejects`, + `determinism: constructed history: a batch whose run rejects`, `random seed: a .ts config in a package with no module type that calls require`, `random seed: a declaration fault: configThrows`, `random seed: a declaration fault: noTypescript`, From d54c43751353515c9653eb9feff5f11ae2e60b33 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 19:13:07 -0700 Subject: [PATCH 45/61] test(oracle-gaps): the rejected-batch history is in Windows fixed-seed shard 1 The PR shard check found the fixed-seed history in no Windows shard (CI's Test job: pr-shards check). It is added to Windows shard 1 beside the other fixed-seed histories. Co-authored-by: Isaac --- packages/oracles/scripts/pr-shards.mjs | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/oracles/scripts/pr-shards.mjs b/packages/oracles/scripts/pr-shards.mjs index 9e162886..b40b1e6f 100644 --- a/packages/oracles/scripts/pr-shards.mjs +++ b/packages/oracles/scripts/pr-shards.mjs @@ -516,6 +516,7 @@ export const partitions = { shards: { 1: anyOf([ 'a .cjs config that calls require', + 'a batch whose run rejects', 'a declaration fault: brokenOwner', 'a declaration fault: missingSource', 'a failing owner under a config that --config names', From 0e580e5c64d6bbaefc5964319d356c9e834d22a5 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 19:21:30 -0700 Subject: [PATCH 46/61] test(oracle-gaps): rejectBatch is a constructed-only field, taken back through an unbuild mapping The generator drew rejectBatch (1 in 200), which the generator rule forbids for a field that changes what a history runs. It is now a constant (fc.constant(0)) in the drawn record, and only the constructed history at the end of the campaign sets it (1). The constructed history gives the framework an unbuild mapping (the optional unbuild on ConstructedHistory, passed to .map as its unmapper), which takes the built history back to a generated one (rejectBatch 0), so fast-check can shrink it. The framework change is additive: a construction without unbuild maps as before. Co-authored-by: Isaac --- .../oracles/oracle-gaps/gap-report-model-oracle.mjs | 10 +++------- .../oracle-gaps/gap-report-oracle.property.test.mjs | 2 ++ packages/oracles/src/oracle-property.ts | 11 ++++++++++- 3 files changed, 15 insertions(+), 8 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index 6c210762..1220c0bc 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -769,13 +769,9 @@ const drawn = fc.record({ }), // Who names the importer's function in an owns entry, if any. importer: fc.constantFrom(`none`, `a`, `b`), - // The batch whose run rejects (a test-only fault, see the constructed history at the end of the - // campaign): 0 is no fault. Appended last in the draw order (the generator rule), so existing fields - // draw as before. - rejectBatch: fc.oneof( - { weight: 199, arbitrary: fc.constant(0) }, - { weight: 1, arbitrary: fc.constant(1) }, - ), + // The batch whose run rejects: a constructed-only field (0 is no fault). Only the constructed history at + // the end of the campaign sets it, through its unbuild mapping (the generator rule). + rejectBatch: fc.constant(0), }) // The edit sequence over the witness module, the one list of steps that a diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 0d19816f..590e9aba 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -4296,6 +4296,8 @@ oracleProperty({ // retention line is written with its state after retirement (the bounded retention law). name: `a batch whose run rejects`, enters: [`a rejected batch retired its copies and logged them`], + // Takes the built history back to a generated one (rejectBatch 0), so that the framework can shrink it. + unbuild: (history) => ({ ...history, rejectBatch: 0 }), build: (generated) => ({ ...generated, functions: [[{ kind: `push`, quote: `'` }]], diff --git a/packages/oracles/src/oracle-property.ts b/packages/oracles/src/oracle-property.ts index 010fb8a8..6c7ea3cd 100644 --- a/packages/oracles/src/oracle-property.ts +++ b/packages/oracles/src/oracle-property.ts @@ -559,6 +559,12 @@ export interface ConstructedHistory { name: string enters: ReadonlyArray build: (generated: THistory) => THistory + /** + * Takes a built history back to a generated one, so fast-check can shrink + * it (its `.map` unmapper). Without it the history is outside the + * arbitrary's language, and the framework refuses it. + */ + unbuild?: (built: THistory) => THistory } /** @@ -2399,7 +2405,10 @@ function generatedTests( : fc.oneof( { arbitrary: source.arbitrary, weight: constructions.length }, ...constructions.map((construction) => ({ - arbitrary: source.arbitrary.map(construction.build), + arbitrary: source.arbitrary.map( + construction.build, + construction.unbuild, + ), weight: 1, })), ) From 954a5f3a3b82baf91676e3677672a31fe7a2b7c4 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 19:22:44 -0700 Subject: [PATCH 47/61] test(oracle-gaps): a constructed history is taken back through its unbuild mapping The registration check tested the built history against the raw generator's language. A constructed fault whose value the generator does not draw (rejectBatch, a constant 0 in the record) is outside that language by design, though its take-back is inside it. The check now tests the history taken back through unbuild when the construction has one; a construction without unbuild is checked as before. Co-authored-by: Isaac --- packages/oracles/src/oracle-property.ts | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/packages/oracles/src/oracle-property.ts b/packages/oracles/src/oracle-property.ts index 6c7ea3cd..24f96349 100644 --- a/packages/oracles/src/oracle-property.ts +++ b/packages/oracles/src/oracle-property.ts @@ -1788,7 +1788,10 @@ function buildConstruction( { cause: error }, ) } - if (!arbitrary.canShrinkWithoutContext(history)) + // The history is taken back through its unbuild mapping (when it has one): a constructed value may + // lie outside the generator's language only where its take-back is inside it. + const takenBack = construction.unbuild?.(history) ?? history + if (!arbitrary.canShrinkWithoutContext(takenBack)) throw untakeable(id, `constructed history "${construction.name}" built`) return history } From cb25107f975a4ad96036740254c038269535c049 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 19:46:58 -0700 Subject: [PATCH 48/61] fix(oracles): the unmapper is passed only when a construction has one (strict types) The build failed (CI's Test jobs): fast-check types the unmapper's argument as unknown and does not accept undefined. The mapping now passes an unmapper only when the construction has unbuild, and adapts it to fast-check's signature. A construction without unbuild maps as before. Co-authored-by: Isaac --- packages/oracles/src/oracle-property.ts | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/packages/oracles/src/oracle-property.ts b/packages/oracles/src/oracle-property.ts index 24f96349..8b36fdf1 100644 --- a/packages/oracles/src/oracle-property.ts +++ b/packages/oracles/src/oracle-property.ts @@ -2407,13 +2407,18 @@ function generatedTests( ? source.arbitrary : fc.oneof( { arbitrary: source.arbitrary, weight: constructions.length }, - ...constructions.map((construction) => ({ - arbitrary: source.arbitrary.map( - construction.build, - construction.unbuild, - ), - weight: 1, - })), + ...constructions.map((construction) => { + const unbuild = construction.unbuild + return { + arbitrary: + unbuild === undefined + ? source.arbitrary.map(construction.build) + : source.arbitrary.map(construction.build, (built: unknown) => + unbuild(built as THistory), + ), + weight: 1, + } + }), ) for (const construction of constructions) { const undeclared = construction.enters.filter( From 025c2feabf4937db4075d8c030b36609c710ea6e Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 21:38:28 -0700 Subject: [PATCH 49/61] test(oracle-gaps): the rejected batch skips main's internal-error and namespace checks; judged after retention Main's #83 check fails any exit 3 at the start of the CLI law, before the rejected-batch branch, so the constructed rejected batch failed on completion. Its internal error also leaves its session, which is the symptom #83 names for the namespace law. For a rejected batch (the constructed fault only), both checks are skipped; its ending (exit 3 and its done error line) and its retention are still judged, with retention first. The Limits name the exemption. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-oracle.property.test.mjs | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 1878dd83..8aea2f8a 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -2576,13 +2576,14 @@ function check(plan, observations, expected) { // An internal error comes first: it also leaves the session directory, so // the namespace law below would name only its symptom (issue #83). The // message carries the run's error.log (readRun). - if (cli.exit === 3) + // A rejected batch (the constructed fault) is judged below, after retention. + if (cli.exit === 3 && expected.rejectedBatch === undefined) return violation( `cli`, `the run ended in an internal error: ${cli.stderr ?? `no stderr`}`, `completion`, ) - if (cli.strayWrites?.length > 0) + if (expected.rejectedBatch === undefined && cli.strayWrites?.length > 0) return violation( `cli`, `the run wrote ${cli.strayWrites.join(`, `)} in the package outside its output directory`, @@ -3920,7 +3921,7 @@ oracleProperty({ law: { statement: `The gap report enumerates the promised operator mutants, leaves out exactly the probe-only code, discovers every oracle that owns a function's call tree and refuses broken ownership, judges each mutant only by its owners' tests on their registered routes and counts only law verdicts on reproducible routes as kills, which outrank a run that never ends, anchors each mutant by its function and normalized statement, lists every gap and unowned mutant once with consistent counts, keeps keys stable under unrelated edits, reports through one daemon per package what a cold run reports at every state of a sequence of edits, and bounds the runs that confirm a mutant's cut-off copies by one budget per mutant and names each busy mutant in a heartbeat while it runs, leaves nothing in the package and writes nothing where Vitest's include could find it while it runs, leaves no process running once it is stopped, runs the package as Vitest does from any install path and any --source spelling: one instance of each workspace dependency, no refusal over an unbuildable devDependency, child processes for a native addon anywhere in the tree, a capture that a test's builtin spies cannot see, and a refusal of test.projects; leads its report with every test file's baseline, blocks only the mutants a failing oracle file owns and judges the rest, prints every line of its stream with the prefix oracle-gaps: and its kind, one decisive baseline line before any mutant, and a done line last, and every run that does not complete ends, cold or through the daemon, with a refusal that exits 2, prints a refused: block and one fix: directive with no stack trace, and writes the refusal to the run's output directory.`, authority: `The maintainer's decisions in design runs v11, v14, and v19 (2026-11-04 and 2026-11-05), not in this package's records, including that a kill by reach agreement alone is a gap and that an incremental run through the daemon equals a cold one (v19.3); the project's oracle guide on quiet exclusions; the oracle rubric's outcome kinds (ORC-006); the CLI's documented operator list in schemata.mjs; the maintainer's dispositions G1, G2, G4, G5, G6, and G13 of the framework papercut ledger (2026-11-11) and the v20 freeze's namespacing, one-loop, and provisional-report decisions (2026-11-10); the maintainer's request for a greppable stream (2026-11-12, relayed by the coordinator with its decisions of that day: the same prefixes on stdout and stderr, a done line for a stopped run, and no --max-gaps).`, - limits: `Law 12 judges refusals only, and the constructed rejected-batch history (rejectBatch, a test-only fault) only as exit 3 with its internal-error done line, with its retention judged first; no legal history reaches an internal error otherwise, so its shape (the stack in error.log) is not judged; argument refusals are the static oracle's; the check's rejection of a stack trace, a missing fix, and a wrong exit code is calibrated in the static oracle, through the same refusalBreach, and here only a refused run reported as complete is calibrated, because each calibration here runs real CLI histories. Hangs only as an owner test that awaits a promise that never settles, under a 1 s first budget and a 20 s full limit, and a slow run only as two witnesses whose tests wait where the output changed, 3 s in one that then judges and 10 s in two one-test owners of one that does not; busy loops only on instrumented code (cut by the call budget), no slow runs past the full limit that would end, hangs in ordinary or nondeterministic tests, setup errors other than a throw at module load, loops, multi-line conditions, two functions on one line, or await, new, and void statements; nested functions, object-literal methods, accessors, and class-field arrows only where no test calls them (their ownership is the static oracle's); two source files of one package, with no re-exports, namespace imports, or calls into another package; --only only in a stopped run and a partial run of one function's mutants, and no --sample or --diff-base; the baseline's failures only as one failing owner test that throws an error and a setup file that throws, so a baseline law violation's law and counterexample lines are the classify oracle's; a derived class's file is instrumented and its sites are judged as unowned, but no test imports or constructs the class, so its no-mutant and super-region behavior is the static oracle's (in-process), not this oracle's; package configs only as vite.config or vitest.config with one of the extensions .ts, .mts, .cts, .js, .mjs, and .cjs (not every pair), as config/gap-vitest with the same extension through --config, or none, as an object or a sync or async function, with no plugins of their own except one enforce: 'pre' transform that appends a comment to each module of the package (prePlugin); a plugin whose output depends on anything but the module's text (a sidecar file it reads) and an environment variable that changes between checks are not generated, since the runner tracks neither yet and the daemon's environment is fixed when it starts (F-A1: the maintainer decided on 2026-11-13 that the daemon tracks both and restarts when they change, in the next pull request); and test.projects only as a refusal, and only under the package's own package.json; a top-level await only in an ES module config and require only in a CommonJS one, as Vitest itself loads no other; a --config outside the package is refused by design, through the rule for paths outside the package (args.mjs), and no history generates one; contexts only one, four, or eleven, and process warnings judged only as MaxListenersExceededWarning on the CLI's own stderr (a daemon's process warnings go to its log); a context that fails to open gives back its listener allowance, which no observation shows (a kept allowance only raises the limit, so no warning follows), so that accounting is fixed by inspection; no probe-bound states, so reach agreement's killing of probe mutants is not checked; no gap answers or gate; law 9 judges the witness module's outcome classes along one constructed edit sequence only (a test edit, a helper edit, and a revert), and the budget witness's along one constructed second check with nothing changed, because a generated history with the witness module or the budget witness takes no steps (maintainer decision, 2026-11-11, and the runtime review's P1-a, 2026-11-12; this oracle owns the gap); law 9's edits come between checks, except one, midrun, which lands during a check through the daemon: a test of file a, whose context has loaded file b's helper, rewrites the helper in the baseline's first run of file a, before file b's runs read it, in one context or several; or a test of file b rewrites its own helper, or the data file that its verdict read through a sync fs read, after file b's judged tests read them, in the run that judges with the old text (review of #55, F1); that check must report, for each mutant, what a cold run of the state before the edit or of the state after it reports, and exit as one of them does (third review of #55, F-C), compared per mutant result rather than per file; when file b's own test lands the edit, b's baseline reads the old text and b's mutant runs read the new one, so b's own mutants in that check are not judged, since their results legitimately mix the two texts (maintainer decision, 2026-11-13), while every other mutant there is judged against both cold runs, with the check's exit code, its mutants' keys, and its stream; the stronger follow-up compares each run's raw outcome with the cold outcome of the state that run read; and the next check, with nothing changed, must equal a cold run of the state after the edit, compared for equality of results only, not for what the daemon reused or computed (the runner's rule: a run whose input changed after the run read it is invalidated and not stored, settleIn); a check through the daemon of a state that nothing changed must compute no run that was not cut off, judged where no test reads the clock (F-A, F-A2), and a test's fs read of a file and the module that the context serves from it are two inputs, each under its own hash (F-A2); an edit during a mutant run is not generated, and a file is edited mid-run only by the run's own tests, not by another process at an arbitrary time; a file that a test reads through fs is edited only as one JSON file that file b's verdict reads by a sync, a promise, or a callback read, or by a sync read after it stats its own directory and tests that it exists (statDir: the directory is an input as a directory, not by its content, and is not itself edited), each read first checking that its fs function keeps its own name and length (the runner stores a run under the files in the package that its copy reads with readFileSync, readFile, existsSync, or statSync, or the fs/promises readFile or stat, each with its hash at the copy's first read; a read outside the package or under node_modules, from a worker thread or a child process that a test starts, or through any other fs API, which includes readdir, opendir, glob, globSync, createReadStream, realpath, lstat, access, open, a read through a file descriptor (read, readSync, readv, fstat, fstatSync, and readFileSync or readFile given a file descriptor), copyFile and copyFileSync, cp and cpSync, openAsBlob, statfs, readlink, the callback stat, exists, watch, watchFile, and the fs/promises access, open, and glob, is no input, and none is generated: the maintainer decided on 2026-11-13 that every fs read except watch and watchFile is an input, which a follow-up of #55 implements, and until then this oracle owns the gap); a run cut off by its clock writes no closing row, so it is stored under its file's known inputs only, while a run that spun ends and keeps the inputs it named (F-D); no history makes a cut run read a file that its file's unmutated run does not read, so this is fixed by inspection; a test that rewrites a file it read with the same text makes the next check compute that run again (1 run in the self-edit histories), since the edit changes the file's modification time: the daemon is conservative there, nothing goes stale, and content keys (D10) remove it, with a selfWrite dimension in that pull request; the mid-run marker sits in the daemon's session directory, .oracle-gaps-, whose location predates #55; the runner's hash memo knows a file by its size and modification time, so an edit that keeps both is not seen, and no history makes one (D10, planned in phase 2, A5); law 9's edits leave out other environment variables, new files that change how an unchanged import resolves, Vite config and installed-package changes, and concurrent checks other than two that start the daemon; cut-off charging judged only under one budget; native addons only as a binding.gyp or a prebuilt .node file, not as optional platform packages; daemon races (two CLIs reading one error file, a CLI hearing closing from the failing daemon it started, a reset connection on macOS) fixed by inspection; the runner's copies of the test files exist only in memory, and its harness and Vitest configs sit in the package's .oracle-gaps-, which the next run removes once a killed run has left it (judged after two stopped runs, not after a SIGKILL); a default --out is judged by the static oracle, and these runs name --out in the package; the namespace is checked after each run and, in a stopped run, while the run runs; a slow kill in a later owner, after earlier owners' confirmations spent the budget, becomes a timeout (owner order; not generated); the Vitest 5 path of the copies' pragma read and of the runner is verified from Vitest 5's source only, since the Vitest 5 CI job runs no gap oracle; a batch whose run reports an error outside any test reruns each copy alone (unitsBatch, runAlone) with its first budget, and a copy cut there is kept as a timeout with no confirmation, a defect older than this oracle's budget work that no history reaches (no history has an error outside any test beside a slow copy), recorded here with that trace for the maintainer; stale-session removal is scoped to this host's session directories (a host file), and is not judged across pid namespaces; the stop law covers SIGTERM and SIGINT sent to the CLI, not a SIGKILL of the CLI (its group then ends at the next check of its parent, by inspection) or a signal sent to the daemon, and its witness is one test that spins synchronously and starts one child process; the mutant budget is witnessed as two slow owners whose confirmations pass the --mutant-limit floor, not through its multiple of the owners' unmutated time, and authored mutants have no confirmations to budget; the witness w_slowpair is a wall-clock window, since the CLI's budget has no controlled clock and a fixture cannot see the time the CLI measures for its file: with one-test owner files p and q of measured unmutated time t each (a file first in its context pays the instrumented transform too), a wait W of 10 s, a 20 s --hang-limit and a 15 s --mutant-limit, it tells a budget from none only while (a) its first attempt is cut, W > 1 s + 3t, (b) its two confirmations do not fit the budget, 2W > max(15 s, 10 x 2t), and (c) each would fit its own full limit, W < 20 s + 3t; (b) is the binding one, so it holds while the two files' time stays under about 2 s together (about 1 s each, some 20 times the authoring machine's idle and 5 to 10 times its loaded measurements), and under one budget a run's overhead must stay under 10 s + 3t; CI runners measure 1.5 to 2.3 times the idle machine; beyond that w_slowpair would read not-judged; a heartbeat is owed only where a slow test waits 3 s against a 2 s interval, twice the first budget, so that no copy cut at its first budget beats, and each beat is observed as its mutant and file, not how long or how often it beat; a config only in the package's parent directory is generated one level up, in a temporary directory with no package.json (so its .js or .ts name is CommonJS), as a plain config, one that throws, one with no default export, or one that defines test.projects; a config two or more levels up, or a parent config beside a package config, is not generated, and the order in one directory follows Vitest's configFiles list by inspection; a package with no config lives in a temporary directory, where no parent has a config; a counterexample shrinks through at most six histories, so it can be larger than the smallest that fails; module-level data only as four \`const\` declarations of the main source (an object literal, an array that holds a function, a boolean, and an object of two methods), read in place, with no data imported from another file, destructured, reassigned, or declared as an enum or a default export; the work law only through shortcut witnesses (an early return before a counting loop with a bound twin of ratio 2, and a push beside one that calls String with a bound twin of ratio 1), the early return in tests that reach the clock by each watched path and in tests that wait a turn, a generated test's bound of 1 derived from its plan (which no generated function's mutant reached in the 36 fixed-seed units), and one warm-cache witness whose selection reproduces observations but not work; work is the capture's count of site evaluations per test, so code with no site (a plain assignment, a for...of pass, a builtin's own work) counts nothing and a test's histories are summed, and a test whose work varies between the unmutated runs while its observations agree is not generated. Open Limits, owned by the in-process runner oracle (L1, state \"torn tail at a cut-off read\"; RED: captureLines without the guard): (a) the batch's cut-off read (runBatch's rowsOf after the cut-off) drops a partial last row, and no witness reaches that drop yet, because a copy held half written across the cut-off did not observe its release in the harness; (b) a short fragment on the strict path, which the no-newline mutant does not reach. The strict read after a finished run (a fragment is an internal error) is witnessed by the no-newline mutant.`, + limits: `Law 12 judges refusals only, and the constructed rejected-batch history (rejectBatch, a test-only fault) only as exit 3 with its internal-error done line, with its retention judged first and its namespace check skipped (the session its internal error leaves is the symptom of #83); no legal history reaches an internal error otherwise, so its shape (the stack in error.log) is not judged; argument refusals are the static oracle's; the check's rejection of a stack trace, a missing fix, and a wrong exit code is calibrated in the static oracle, through the same refusalBreach, and here only a refused run reported as complete is calibrated, because each calibration here runs real CLI histories. Hangs only as an owner test that awaits a promise that never settles, under a 1 s first budget and a 20 s full limit, and a slow run only as two witnesses whose tests wait where the output changed, 3 s in one that then judges and 10 s in two one-test owners of one that does not; busy loops only on instrumented code (cut by the call budget), no slow runs past the full limit that would end, hangs in ordinary or nondeterministic tests, setup errors other than a throw at module load, loops, multi-line conditions, two functions on one line, or await, new, and void statements; nested functions, object-literal methods, accessors, and class-field arrows only where no test calls them (their ownership is the static oracle's); two source files of one package, with no re-exports, namespace imports, or calls into another package; --only only in a stopped run and a partial run of one function's mutants, and no --sample or --diff-base; the baseline's failures only as one failing owner test that throws an error and a setup file that throws, so a baseline law violation's law and counterexample lines are the classify oracle's; a derived class's file is instrumented and its sites are judged as unowned, but no test imports or constructs the class, so its no-mutant and super-region behavior is the static oracle's (in-process), not this oracle's; package configs only as vite.config or vitest.config with one of the extensions .ts, .mts, .cts, .js, .mjs, and .cjs (not every pair), as config/gap-vitest with the same extension through --config, or none, as an object or a sync or async function, with no plugins of their own except one enforce: 'pre' transform that appends a comment to each module of the package (prePlugin); a plugin whose output depends on anything but the module's text (a sidecar file it reads) and an environment variable that changes between checks are not generated, since the runner tracks neither yet and the daemon's environment is fixed when it starts (F-A1: the maintainer decided on 2026-11-13 that the daemon tracks both and restarts when they change, in the next pull request); and test.projects only as a refusal, and only under the package's own package.json; a top-level await only in an ES module config and require only in a CommonJS one, as Vitest itself loads no other; a --config outside the package is refused by design, through the rule for paths outside the package (args.mjs), and no history generates one; contexts only one, four, or eleven, and process warnings judged only as MaxListenersExceededWarning on the CLI's own stderr (a daemon's process warnings go to its log); a context that fails to open gives back its listener allowance, which no observation shows (a kept allowance only raises the limit, so no warning follows), so that accounting is fixed by inspection; no probe-bound states, so reach agreement's killing of probe mutants is not checked; no gap answers or gate; law 9 judges the witness module's outcome classes along one constructed edit sequence only (a test edit, a helper edit, and a revert), and the budget witness's along one constructed second check with nothing changed, because a generated history with the witness module or the budget witness takes no steps (maintainer decision, 2026-11-11, and the runtime review's P1-a, 2026-11-12; this oracle owns the gap); law 9's edits come between checks, except one, midrun, which lands during a check through the daemon: a test of file a, whose context has loaded file b's helper, rewrites the helper in the baseline's first run of file a, before file b's runs read it, in one context or several; or a test of file b rewrites its own helper, or the data file that its verdict read through a sync fs read, after file b's judged tests read them, in the run that judges with the old text (review of #55, F1); that check must report, for each mutant, what a cold run of the state before the edit or of the state after it reports, and exit as one of them does (third review of #55, F-C), compared per mutant result rather than per file; when file b's own test lands the edit, b's baseline reads the old text and b's mutant runs read the new one, so b's own mutants in that check are not judged, since their results legitimately mix the two texts (maintainer decision, 2026-11-13), while every other mutant there is judged against both cold runs, with the check's exit code, its mutants' keys, and its stream; the stronger follow-up compares each run's raw outcome with the cold outcome of the state that run read; and the next check, with nothing changed, must equal a cold run of the state after the edit, compared for equality of results only, not for what the daemon reused or computed (the runner's rule: a run whose input changed after the run read it is invalidated and not stored, settleIn); a check through the daemon of a state that nothing changed must compute no run that was not cut off, judged where no test reads the clock (F-A, F-A2), and a test's fs read of a file and the module that the context serves from it are two inputs, each under its own hash (F-A2); an edit during a mutant run is not generated, and a file is edited mid-run only by the run's own tests, not by another process at an arbitrary time; a file that a test reads through fs is edited only as one JSON file that file b's verdict reads by a sync, a promise, or a callback read, or by a sync read after it stats its own directory and tests that it exists (statDir: the directory is an input as a directory, not by its content, and is not itself edited), each read first checking that its fs function keeps its own name and length (the runner stores a run under the files in the package that its copy reads with readFileSync, readFile, existsSync, or statSync, or the fs/promises readFile or stat, each with its hash at the copy's first read; a read outside the package or under node_modules, from a worker thread or a child process that a test starts, or through any other fs API, which includes readdir, opendir, glob, globSync, createReadStream, realpath, lstat, access, open, a read through a file descriptor (read, readSync, readv, fstat, fstatSync, and readFileSync or readFile given a file descriptor), copyFile and copyFileSync, cp and cpSync, openAsBlob, statfs, readlink, the callback stat, exists, watch, watchFile, and the fs/promises access, open, and glob, is no input, and none is generated: the maintainer decided on 2026-11-13 that every fs read except watch and watchFile is an input, which a follow-up of #55 implements, and until then this oracle owns the gap); a run cut off by its clock writes no closing row, so it is stored under its file's known inputs only, while a run that spun ends and keeps the inputs it named (F-D); no history makes a cut run read a file that its file's unmutated run does not read, so this is fixed by inspection; a test that rewrites a file it read with the same text makes the next check compute that run again (1 run in the self-edit histories), since the edit changes the file's modification time: the daemon is conservative there, nothing goes stale, and content keys (D10) remove it, with a selfWrite dimension in that pull request; the mid-run marker sits in the daemon's session directory, .oracle-gaps-, whose location predates #55; the runner's hash memo knows a file by its size and modification time, so an edit that keeps both is not seen, and no history makes one (D10, planned in phase 2, A5); law 9's edits leave out other environment variables, new files that change how an unchanged import resolves, Vite config and installed-package changes, and concurrent checks other than two that start the daemon; cut-off charging judged only under one budget; native addons only as a binding.gyp or a prebuilt .node file, not as optional platform packages; daemon races (two CLIs reading one error file, a CLI hearing closing from the failing daemon it started, a reset connection on macOS) fixed by inspection; the runner's copies of the test files exist only in memory, and its harness and Vitest configs sit in the package's .oracle-gaps-, which the next run removes once a killed run has left it (judged after two stopped runs, not after a SIGKILL); a default --out is judged by the static oracle, and these runs name --out in the package; the namespace is checked after each run and, in a stopped run, while the run runs; a slow kill in a later owner, after earlier owners' confirmations spent the budget, becomes a timeout (owner order; not generated); the Vitest 5 path of the copies' pragma read and of the runner is verified from Vitest 5's source only, since the Vitest 5 CI job runs no gap oracle; a batch whose run reports an error outside any test reruns each copy alone (unitsBatch, runAlone) with its first budget, and a copy cut there is kept as a timeout with no confirmation, a defect older than this oracle's budget work that no history reaches (no history has an error outside any test beside a slow copy), recorded here with that trace for the maintainer; stale-session removal is scoped to this host's session directories (a host file), and is not judged across pid namespaces; the stop law covers SIGTERM and SIGINT sent to the CLI, not a SIGKILL of the CLI (its group then ends at the next check of its parent, by inspection) or a signal sent to the daemon, and its witness is one test that spins synchronously and starts one child process; the mutant budget is witnessed as two slow owners whose confirmations pass the --mutant-limit floor, not through its multiple of the owners' unmutated time, and authored mutants have no confirmations to budget; the witness w_slowpair is a wall-clock window, since the CLI's budget has no controlled clock and a fixture cannot see the time the CLI measures for its file: with one-test owner files p and q of measured unmutated time t each (a file first in its context pays the instrumented transform too), a wait W of 10 s, a 20 s --hang-limit and a 15 s --mutant-limit, it tells a budget from none only while (a) its first attempt is cut, W > 1 s + 3t, (b) its two confirmations do not fit the budget, 2W > max(15 s, 10 x 2t), and (c) each would fit its own full limit, W < 20 s + 3t; (b) is the binding one, so it holds while the two files' time stays under about 2 s together (about 1 s each, some 20 times the authoring machine's idle and 5 to 10 times its loaded measurements), and under one budget a run's overhead must stay under 10 s + 3t; CI runners measure 1.5 to 2.3 times the idle machine; beyond that w_slowpair would read not-judged; a heartbeat is owed only where a slow test waits 3 s against a 2 s interval, twice the first budget, so that no copy cut at its first budget beats, and each beat is observed as its mutant and file, not how long or how often it beat; a config only in the package's parent directory is generated one level up, in a temporary directory with no package.json (so its .js or .ts name is CommonJS), as a plain config, one that throws, one with no default export, or one that defines test.projects; a config two or more levels up, or a parent config beside a package config, is not generated, and the order in one directory follows Vitest's configFiles list by inspection; a package with no config lives in a temporary directory, where no parent has a config; a counterexample shrinks through at most six histories, so it can be larger than the smallest that fails; module-level data only as four \`const\` declarations of the main source (an object literal, an array that holds a function, a boolean, and an object of two methods), read in place, with no data imported from another file, destructured, reassigned, or declared as an enum or a default export; the work law only through shortcut witnesses (an early return before a counting loop with a bound twin of ratio 2, and a push beside one that calls String with a bound twin of ratio 1), the early return in tests that reach the clock by each watched path and in tests that wait a turn, a generated test's bound of 1 derived from its plan (which no generated function's mutant reached in the 36 fixed-seed units), and one warm-cache witness whose selection reproduces observations but not work; work is the capture's count of site evaluations per test, so code with no site (a plain assignment, a for...of pass, a builtin's own work) counts nothing and a test's histories are summed, and a test whose work varies between the unmutated runs while its observations agree is not generated. Open Limits, owned by the in-process runner oracle (L1, state \"torn tail at a cut-off read\"; RED: captureLines without the guard): (a) the batch's cut-off read (runBatch's rowsOf after the cut-off) drops a partial last row, and no witness reaches that drop yet, because a copy held half written across the cut-off did not observe its release in the harness; (b) a short fragment on the strict path, which the no-newline mutant does not reach. The strict read after a finished run (a fragment is an internal error) is witnessed by the no-newline mutant.`, }, histories: { // A failing history shrinks through at most six smaller ones. Each runs From 83552e73ecdbe7b0825089c4a57d91c1dc0f62d1 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 22:41:35 -0700 Subject: [PATCH 50/61] test(oracle-gaps): rejectBatch is recorded at the end of the generator fingerprint lists The generator canary (gap-report-history-fingerprint) records each field's draws in draw order, and a new field is recorded at the end of both lists. rejectBatch (the constant 0, drawn last) is appended in drawn and histories; every earlier line is unchanged. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/history-fingerprint.json | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/oracles/oracle-gaps/history-fingerprint.json b/packages/oracles/oracle-gaps/history-fingerprint.json index 79e58ac2..aded0740 100644 --- a/packages/oracles/oracle-gaps/history-fingerprint.json +++ b/packages/oracles/oracle-gaps/history-fingerprint.json @@ -52,7 +52,8 @@ ["prePlugin", "7093bcf61828dea9"], ["fsRead", "265eb24ce88fdbe2"], ["laterSteps", "fb28f2575c00f223"], - ["tornRows", "ed6866229ecc4969"] + ["tornRows", "ed6866229ecc4969"], + ["rejectBatch", "e5386ea9402dd268"] ], "histories": [ ["functions", "66c0e9c56951c377"], @@ -107,6 +108,7 @@ ["prePlugin", "7093bcf61828dea9"], ["fsRead", "265eb24ce88fdbe2"], ["laterSteps", "fb28f2575c00f223"], - ["tornRows", "ed6866229ecc4969"] + ["tornRows", "ed6866229ecc4969"], + ["rejectBatch", "e5386ea9402dd268"] ] } From b26d9623be3a5cec88c227ab087f2ab58cba961b Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sun, 15 Nov 2026 00:35:53 -0700 Subject: [PATCH 51/61] test(oracle-gaps): the rejected batch's run is judged by the output namespace law The earlier exemption skipped the namespace law for the constructed rejected batch. Restored: the law judges every write of that run. Whatever an internal error leaves behind is then either removed by the CLI or predicted by the model, decided on the evidence of the run that follows. Co-authored-by: Isaac --- .../oracles/oracle-gaps/gap-report-oracle.property.test.mjs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 8aea2f8a..88e7ea52 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -2583,7 +2583,7 @@ function check(plan, observations, expected) { `the run ended in an internal error: ${cli.stderr ?? `no stderr`}`, `completion`, ) - if (expected.rejectedBatch === undefined && cli.strayWrites?.length > 0) + if (cli.strayWrites?.length > 0) return violation( `cli`, `the run wrote ${cli.strayWrites.join(`, `)} in the package outside its output directory`, @@ -3921,7 +3921,7 @@ oracleProperty({ law: { statement: `The gap report enumerates the promised operator mutants, leaves out exactly the probe-only code, discovers every oracle that owns a function's call tree and refuses broken ownership, judges each mutant only by its owners' tests on their registered routes and counts only law verdicts on reproducible routes as kills, which outrank a run that never ends, anchors each mutant by its function and normalized statement, lists every gap and unowned mutant once with consistent counts, keeps keys stable under unrelated edits, reports through one daemon per package what a cold run reports at every state of a sequence of edits, and bounds the runs that confirm a mutant's cut-off copies by one budget per mutant and names each busy mutant in a heartbeat while it runs, leaves nothing in the package and writes nothing where Vitest's include could find it while it runs, leaves no process running once it is stopped, runs the package as Vitest does from any install path and any --source spelling: one instance of each workspace dependency, no refusal over an unbuildable devDependency, child processes for a native addon anywhere in the tree, a capture that a test's builtin spies cannot see, and a refusal of test.projects; leads its report with every test file's baseline, blocks only the mutants a failing oracle file owns and judges the rest, prints every line of its stream with the prefix oracle-gaps: and its kind, one decisive baseline line before any mutant, and a done line last, and every run that does not complete ends, cold or through the daemon, with a refusal that exits 2, prints a refused: block and one fix: directive with no stack trace, and writes the refusal to the run's output directory.`, authority: `The maintainer's decisions in design runs v11, v14, and v19 (2026-11-04 and 2026-11-05), not in this package's records, including that a kill by reach agreement alone is a gap and that an incremental run through the daemon equals a cold one (v19.3); the project's oracle guide on quiet exclusions; the oracle rubric's outcome kinds (ORC-006); the CLI's documented operator list in schemata.mjs; the maintainer's dispositions G1, G2, G4, G5, G6, and G13 of the framework papercut ledger (2026-11-11) and the v20 freeze's namespacing, one-loop, and provisional-report decisions (2026-11-10); the maintainer's request for a greppable stream (2026-11-12, relayed by the coordinator with its decisions of that day: the same prefixes on stdout and stderr, a done line for a stopped run, and no --max-gaps).`, - limits: `Law 12 judges refusals only, and the constructed rejected-batch history (rejectBatch, a test-only fault) only as exit 3 with its internal-error done line, with its retention judged first and its namespace check skipped (the session its internal error leaves is the symptom of #83); no legal history reaches an internal error otherwise, so its shape (the stack in error.log) is not judged; argument refusals are the static oracle's; the check's rejection of a stack trace, a missing fix, and a wrong exit code is calibrated in the static oracle, through the same refusalBreach, and here only a refused run reported as complete is calibrated, because each calibration here runs real CLI histories. Hangs only as an owner test that awaits a promise that never settles, under a 1 s first budget and a 20 s full limit, and a slow run only as two witnesses whose tests wait where the output changed, 3 s in one that then judges and 10 s in two one-test owners of one that does not; busy loops only on instrumented code (cut by the call budget), no slow runs past the full limit that would end, hangs in ordinary or nondeterministic tests, setup errors other than a throw at module load, loops, multi-line conditions, two functions on one line, or await, new, and void statements; nested functions, object-literal methods, accessors, and class-field arrows only where no test calls them (their ownership is the static oracle's); two source files of one package, with no re-exports, namespace imports, or calls into another package; --only only in a stopped run and a partial run of one function's mutants, and no --sample or --diff-base; the baseline's failures only as one failing owner test that throws an error and a setup file that throws, so a baseline law violation's law and counterexample lines are the classify oracle's; a derived class's file is instrumented and its sites are judged as unowned, but no test imports or constructs the class, so its no-mutant and super-region behavior is the static oracle's (in-process), not this oracle's; package configs only as vite.config or vitest.config with one of the extensions .ts, .mts, .cts, .js, .mjs, and .cjs (not every pair), as config/gap-vitest with the same extension through --config, or none, as an object or a sync or async function, with no plugins of their own except one enforce: 'pre' transform that appends a comment to each module of the package (prePlugin); a plugin whose output depends on anything but the module's text (a sidecar file it reads) and an environment variable that changes between checks are not generated, since the runner tracks neither yet and the daemon's environment is fixed when it starts (F-A1: the maintainer decided on 2026-11-13 that the daemon tracks both and restarts when they change, in the next pull request); and test.projects only as a refusal, and only under the package's own package.json; a top-level await only in an ES module config and require only in a CommonJS one, as Vitest itself loads no other; a --config outside the package is refused by design, through the rule for paths outside the package (args.mjs), and no history generates one; contexts only one, four, or eleven, and process warnings judged only as MaxListenersExceededWarning on the CLI's own stderr (a daemon's process warnings go to its log); a context that fails to open gives back its listener allowance, which no observation shows (a kept allowance only raises the limit, so no warning follows), so that accounting is fixed by inspection; no probe-bound states, so reach agreement's killing of probe mutants is not checked; no gap answers or gate; law 9 judges the witness module's outcome classes along one constructed edit sequence only (a test edit, a helper edit, and a revert), and the budget witness's along one constructed second check with nothing changed, because a generated history with the witness module or the budget witness takes no steps (maintainer decision, 2026-11-11, and the runtime review's P1-a, 2026-11-12; this oracle owns the gap); law 9's edits come between checks, except one, midrun, which lands during a check through the daemon: a test of file a, whose context has loaded file b's helper, rewrites the helper in the baseline's first run of file a, before file b's runs read it, in one context or several; or a test of file b rewrites its own helper, or the data file that its verdict read through a sync fs read, after file b's judged tests read them, in the run that judges with the old text (review of #55, F1); that check must report, for each mutant, what a cold run of the state before the edit or of the state after it reports, and exit as one of them does (third review of #55, F-C), compared per mutant result rather than per file; when file b's own test lands the edit, b's baseline reads the old text and b's mutant runs read the new one, so b's own mutants in that check are not judged, since their results legitimately mix the two texts (maintainer decision, 2026-11-13), while every other mutant there is judged against both cold runs, with the check's exit code, its mutants' keys, and its stream; the stronger follow-up compares each run's raw outcome with the cold outcome of the state that run read; and the next check, with nothing changed, must equal a cold run of the state after the edit, compared for equality of results only, not for what the daemon reused or computed (the runner's rule: a run whose input changed after the run read it is invalidated and not stored, settleIn); a check through the daemon of a state that nothing changed must compute no run that was not cut off, judged where no test reads the clock (F-A, F-A2), and a test's fs read of a file and the module that the context serves from it are two inputs, each under its own hash (F-A2); an edit during a mutant run is not generated, and a file is edited mid-run only by the run's own tests, not by another process at an arbitrary time; a file that a test reads through fs is edited only as one JSON file that file b's verdict reads by a sync, a promise, or a callback read, or by a sync read after it stats its own directory and tests that it exists (statDir: the directory is an input as a directory, not by its content, and is not itself edited), each read first checking that its fs function keeps its own name and length (the runner stores a run under the files in the package that its copy reads with readFileSync, readFile, existsSync, or statSync, or the fs/promises readFile or stat, each with its hash at the copy's first read; a read outside the package or under node_modules, from a worker thread or a child process that a test starts, or through any other fs API, which includes readdir, opendir, glob, globSync, createReadStream, realpath, lstat, access, open, a read through a file descriptor (read, readSync, readv, fstat, fstatSync, and readFileSync or readFile given a file descriptor), copyFile and copyFileSync, cp and cpSync, openAsBlob, statfs, readlink, the callback stat, exists, watch, watchFile, and the fs/promises access, open, and glob, is no input, and none is generated: the maintainer decided on 2026-11-13 that every fs read except watch and watchFile is an input, which a follow-up of #55 implements, and until then this oracle owns the gap); a run cut off by its clock writes no closing row, so it is stored under its file's known inputs only, while a run that spun ends and keeps the inputs it named (F-D); no history makes a cut run read a file that its file's unmutated run does not read, so this is fixed by inspection; a test that rewrites a file it read with the same text makes the next check compute that run again (1 run in the self-edit histories), since the edit changes the file's modification time: the daemon is conservative there, nothing goes stale, and content keys (D10) remove it, with a selfWrite dimension in that pull request; the mid-run marker sits in the daemon's session directory, .oracle-gaps-, whose location predates #55; the runner's hash memo knows a file by its size and modification time, so an edit that keeps both is not seen, and no history makes one (D10, planned in phase 2, A5); law 9's edits leave out other environment variables, new files that change how an unchanged import resolves, Vite config and installed-package changes, and concurrent checks other than two that start the daemon; cut-off charging judged only under one budget; native addons only as a binding.gyp or a prebuilt .node file, not as optional platform packages; daemon races (two CLIs reading one error file, a CLI hearing closing from the failing daemon it started, a reset connection on macOS) fixed by inspection; the runner's copies of the test files exist only in memory, and its harness and Vitest configs sit in the package's .oracle-gaps-, which the next run removes once a killed run has left it (judged after two stopped runs, not after a SIGKILL); a default --out is judged by the static oracle, and these runs name --out in the package; the namespace is checked after each run and, in a stopped run, while the run runs; a slow kill in a later owner, after earlier owners' confirmations spent the budget, becomes a timeout (owner order; not generated); the Vitest 5 path of the copies' pragma read and of the runner is verified from Vitest 5's source only, since the Vitest 5 CI job runs no gap oracle; a batch whose run reports an error outside any test reruns each copy alone (unitsBatch, runAlone) with its first budget, and a copy cut there is kept as a timeout with no confirmation, a defect older than this oracle's budget work that no history reaches (no history has an error outside any test beside a slow copy), recorded here with that trace for the maintainer; stale-session removal is scoped to this host's session directories (a host file), and is not judged across pid namespaces; the stop law covers SIGTERM and SIGINT sent to the CLI, not a SIGKILL of the CLI (its group then ends at the next check of its parent, by inspection) or a signal sent to the daemon, and its witness is one test that spins synchronously and starts one child process; the mutant budget is witnessed as two slow owners whose confirmations pass the --mutant-limit floor, not through its multiple of the owners' unmutated time, and authored mutants have no confirmations to budget; the witness w_slowpair is a wall-clock window, since the CLI's budget has no controlled clock and a fixture cannot see the time the CLI measures for its file: with one-test owner files p and q of measured unmutated time t each (a file first in its context pays the instrumented transform too), a wait W of 10 s, a 20 s --hang-limit and a 15 s --mutant-limit, it tells a budget from none only while (a) its first attempt is cut, W > 1 s + 3t, (b) its two confirmations do not fit the budget, 2W > max(15 s, 10 x 2t), and (c) each would fit its own full limit, W < 20 s + 3t; (b) is the binding one, so it holds while the two files' time stays under about 2 s together (about 1 s each, some 20 times the authoring machine's idle and 5 to 10 times its loaded measurements), and under one budget a run's overhead must stay under 10 s + 3t; CI runners measure 1.5 to 2.3 times the idle machine; beyond that w_slowpair would read not-judged; a heartbeat is owed only where a slow test waits 3 s against a 2 s interval, twice the first budget, so that no copy cut at its first budget beats, and each beat is observed as its mutant and file, not how long or how often it beat; a config only in the package's parent directory is generated one level up, in a temporary directory with no package.json (so its .js or .ts name is CommonJS), as a plain config, one that throws, one with no default export, or one that defines test.projects; a config two or more levels up, or a parent config beside a package config, is not generated, and the order in one directory follows Vitest's configFiles list by inspection; a package with no config lives in a temporary directory, where no parent has a config; a counterexample shrinks through at most six histories, so it can be larger than the smallest that fails; module-level data only as four \`const\` declarations of the main source (an object literal, an array that holds a function, a boolean, and an object of two methods), read in place, with no data imported from another file, destructured, reassigned, or declared as an enum or a default export; the work law only through shortcut witnesses (an early return before a counting loop with a bound twin of ratio 2, and a push beside one that calls String with a bound twin of ratio 1), the early return in tests that reach the clock by each watched path and in tests that wait a turn, a generated test's bound of 1 derived from its plan (which no generated function's mutant reached in the 36 fixed-seed units), and one warm-cache witness whose selection reproduces observations but not work; work is the capture's count of site evaluations per test, so code with no site (a plain assignment, a for...of pass, a builtin's own work) counts nothing and a test's histories are summed, and a test whose work varies between the unmutated runs while its observations agree is not generated. Open Limits, owned by the in-process runner oracle (L1, state \"torn tail at a cut-off read\"; RED: captureLines without the guard): (a) the batch's cut-off read (runBatch's rowsOf after the cut-off) drops a partial last row, and no witness reaches that drop yet, because a copy held half written across the cut-off did not observe its release in the harness; (b) a short fragment on the strict path, which the no-newline mutant does not reach. The strict read after a finished run (a fragment is an internal error) is witnessed by the no-newline mutant.`, + limits: `Law 12 judges refusals only, and the constructed rejected-batch history (rejectBatch, a test-only fault) only as exit 3 with its internal-error done line, with its retention judged first and its output namespace still judged; no legal history reaches an internal error otherwise, so its shape (the stack in error.log) is not judged; argument refusals are the static oracle's; the check's rejection of a stack trace, a missing fix, and a wrong exit code is calibrated in the static oracle, through the same refusalBreach, and here only a refused run reported as complete is calibrated, because each calibration here runs real CLI histories. Hangs only as an owner test that awaits a promise that never settles, under a 1 s first budget and a 20 s full limit, and a slow run only as two witnesses whose tests wait where the output changed, 3 s in one that then judges and 10 s in two one-test owners of one that does not; busy loops only on instrumented code (cut by the call budget), no slow runs past the full limit that would end, hangs in ordinary or nondeterministic tests, setup errors other than a throw at module load, loops, multi-line conditions, two functions on one line, or await, new, and void statements; nested functions, object-literal methods, accessors, and class-field arrows only where no test calls them (their ownership is the static oracle's); two source files of one package, with no re-exports, namespace imports, or calls into another package; --only only in a stopped run and a partial run of one function's mutants, and no --sample or --diff-base; the baseline's failures only as one failing owner test that throws an error and a setup file that throws, so a baseline law violation's law and counterexample lines are the classify oracle's; a derived class's file is instrumented and its sites are judged as unowned, but no test imports or constructs the class, so its no-mutant and super-region behavior is the static oracle's (in-process), not this oracle's; package configs only as vite.config or vitest.config with one of the extensions .ts, .mts, .cts, .js, .mjs, and .cjs (not every pair), as config/gap-vitest with the same extension through --config, or none, as an object or a sync or async function, with no plugins of their own except one enforce: 'pre' transform that appends a comment to each module of the package (prePlugin); a plugin whose output depends on anything but the module's text (a sidecar file it reads) and an environment variable that changes between checks are not generated, since the runner tracks neither yet and the daemon's environment is fixed when it starts (F-A1: the maintainer decided on 2026-11-13 that the daemon tracks both and restarts when they change, in the next pull request); and test.projects only as a refusal, and only under the package's own package.json; a top-level await only in an ES module config and require only in a CommonJS one, as Vitest itself loads no other; a --config outside the package is refused by design, through the rule for paths outside the package (args.mjs), and no history generates one; contexts only one, four, or eleven, and process warnings judged only as MaxListenersExceededWarning on the CLI's own stderr (a daemon's process warnings go to its log); a context that fails to open gives back its listener allowance, which no observation shows (a kept allowance only raises the limit, so no warning follows), so that accounting is fixed by inspection; no probe-bound states, so reach agreement's killing of probe mutants is not checked; no gap answers or gate; law 9 judges the witness module's outcome classes along one constructed edit sequence only (a test edit, a helper edit, and a revert), and the budget witness's along one constructed second check with nothing changed, because a generated history with the witness module or the budget witness takes no steps (maintainer decision, 2026-11-11, and the runtime review's P1-a, 2026-11-12; this oracle owns the gap); law 9's edits come between checks, except one, midrun, which lands during a check through the daemon: a test of file a, whose context has loaded file b's helper, rewrites the helper in the baseline's first run of file a, before file b's runs read it, in one context or several; or a test of file b rewrites its own helper, or the data file that its verdict read through a sync fs read, after file b's judged tests read them, in the run that judges with the old text (review of #55, F1); that check must report, for each mutant, what a cold run of the state before the edit or of the state after it reports, and exit as one of them does (third review of #55, F-C), compared per mutant result rather than per file; when file b's own test lands the edit, b's baseline reads the old text and b's mutant runs read the new one, so b's own mutants in that check are not judged, since their results legitimately mix the two texts (maintainer decision, 2026-11-13), while every other mutant there is judged against both cold runs, with the check's exit code, its mutants' keys, and its stream; the stronger follow-up compares each run's raw outcome with the cold outcome of the state that run read; and the next check, with nothing changed, must equal a cold run of the state after the edit, compared for equality of results only, not for what the daemon reused or computed (the runner's rule: a run whose input changed after the run read it is invalidated and not stored, settleIn); a check through the daemon of a state that nothing changed must compute no run that was not cut off, judged where no test reads the clock (F-A, F-A2), and a test's fs read of a file and the module that the context serves from it are two inputs, each under its own hash (F-A2); an edit during a mutant run is not generated, and a file is edited mid-run only by the run's own tests, not by another process at an arbitrary time; a file that a test reads through fs is edited only as one JSON file that file b's verdict reads by a sync, a promise, or a callback read, or by a sync read after it stats its own directory and tests that it exists (statDir: the directory is an input as a directory, not by its content, and is not itself edited), each read first checking that its fs function keeps its own name and length (the runner stores a run under the files in the package that its copy reads with readFileSync, readFile, existsSync, or statSync, or the fs/promises readFile or stat, each with its hash at the copy's first read; a read outside the package or under node_modules, from a worker thread or a child process that a test starts, or through any other fs API, which includes readdir, opendir, glob, globSync, createReadStream, realpath, lstat, access, open, a read through a file descriptor (read, readSync, readv, fstat, fstatSync, and readFileSync or readFile given a file descriptor), copyFile and copyFileSync, cp and cpSync, openAsBlob, statfs, readlink, the callback stat, exists, watch, watchFile, and the fs/promises access, open, and glob, is no input, and none is generated: the maintainer decided on 2026-11-13 that every fs read except watch and watchFile is an input, which a follow-up of #55 implements, and until then this oracle owns the gap); a run cut off by its clock writes no closing row, so it is stored under its file's known inputs only, while a run that spun ends and keeps the inputs it named (F-D); no history makes a cut run read a file that its file's unmutated run does not read, so this is fixed by inspection; a test that rewrites a file it read with the same text makes the next check compute that run again (1 run in the self-edit histories), since the edit changes the file's modification time: the daemon is conservative there, nothing goes stale, and content keys (D10) remove it, with a selfWrite dimension in that pull request; the mid-run marker sits in the daemon's session directory, .oracle-gaps-, whose location predates #55; the runner's hash memo knows a file by its size and modification time, so an edit that keeps both is not seen, and no history makes one (D10, planned in phase 2, A5); law 9's edits leave out other environment variables, new files that change how an unchanged import resolves, Vite config and installed-package changes, and concurrent checks other than two that start the daemon; cut-off charging judged only under one budget; native addons only as a binding.gyp or a prebuilt .node file, not as optional platform packages; daemon races (two CLIs reading one error file, a CLI hearing closing from the failing daemon it started, a reset connection on macOS) fixed by inspection; the runner's copies of the test files exist only in memory, and its harness and Vitest configs sit in the package's .oracle-gaps-, which the next run removes once a killed run has left it (judged after two stopped runs, not after a SIGKILL); a default --out is judged by the static oracle, and these runs name --out in the package; the namespace is checked after each run and, in a stopped run, while the run runs; a slow kill in a later owner, after earlier owners' confirmations spent the budget, becomes a timeout (owner order; not generated); the Vitest 5 path of the copies' pragma read and of the runner is verified from Vitest 5's source only, since the Vitest 5 CI job runs no gap oracle; a batch whose run reports an error outside any test reruns each copy alone (unitsBatch, runAlone) with its first budget, and a copy cut there is kept as a timeout with no confirmation, a defect older than this oracle's budget work that no history reaches (no history has an error outside any test beside a slow copy), recorded here with that trace for the maintainer; stale-session removal is scoped to this host's session directories (a host file), and is not judged across pid namespaces; the stop law covers SIGTERM and SIGINT sent to the CLI, not a SIGKILL of the CLI (its group then ends at the next check of its parent, by inspection) or a signal sent to the daemon, and its witness is one test that spins synchronously and starts one child process; the mutant budget is witnessed as two slow owners whose confirmations pass the --mutant-limit floor, not through its multiple of the owners' unmutated time, and authored mutants have no confirmations to budget; the witness w_slowpair is a wall-clock window, since the CLI's budget has no controlled clock and a fixture cannot see the time the CLI measures for its file: with one-test owner files p and q of measured unmutated time t each (a file first in its context pays the instrumented transform too), a wait W of 10 s, a 20 s --hang-limit and a 15 s --mutant-limit, it tells a budget from none only while (a) its first attempt is cut, W > 1 s + 3t, (b) its two confirmations do not fit the budget, 2W > max(15 s, 10 x 2t), and (c) each would fit its own full limit, W < 20 s + 3t; (b) is the binding one, so it holds while the two files' time stays under about 2 s together (about 1 s each, some 20 times the authoring machine's idle and 5 to 10 times its loaded measurements), and under one budget a run's overhead must stay under 10 s + 3t; CI runners measure 1.5 to 2.3 times the idle machine; beyond that w_slowpair would read not-judged; a heartbeat is owed only where a slow test waits 3 s against a 2 s interval, twice the first budget, so that no copy cut at its first budget beats, and each beat is observed as its mutant and file, not how long or how often it beat; a config only in the package's parent directory is generated one level up, in a temporary directory with no package.json (so its .js or .ts name is CommonJS), as a plain config, one that throws, one with no default export, or one that defines test.projects; a config two or more levels up, or a parent config beside a package config, is not generated, and the order in one directory follows Vitest's configFiles list by inspection; a package with no config lives in a temporary directory, where no parent has a config; a counterexample shrinks through at most six histories, so it can be larger than the smallest that fails; module-level data only as four \`const\` declarations of the main source (an object literal, an array that holds a function, a boolean, and an object of two methods), read in place, with no data imported from another file, destructured, reassigned, or declared as an enum or a default export; the work law only through shortcut witnesses (an early return before a counting loop with a bound twin of ratio 2, and a push beside one that calls String with a bound twin of ratio 1), the early return in tests that reach the clock by each watched path and in tests that wait a turn, a generated test's bound of 1 derived from its plan (which no generated function's mutant reached in the 36 fixed-seed units), and one warm-cache witness whose selection reproduces observations but not work; work is the capture's count of site evaluations per test, so code with no site (a plain assignment, a for...of pass, a builtin's own work) counts nothing and a test's histories are summed, and a test whose work varies between the unmutated runs while its observations agree is not generated. Open Limits, owned by the in-process runner oracle (L1, state \"torn tail at a cut-off read\"; RED: captureLines without the guard): (a) the batch's cut-off read (runBatch's rowsOf after the cut-off) drops a partial last row, and no witness reaches that drop yet, because a copy held half written across the cut-off did not observe its release in the harness; (b) a short fragment on the strict path, which the no-newline mutant does not reach. The strict read after a finished run (a fragment is an internal error) is witnessed by the no-newline mutant.`, }, histories: { // A failing history shrinks through at most six smaller ones. Each runs From 231a68965ced8b986747ea9ef5b6b244b985382b Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sun, 15 Nov 2026 01:23:11 -0700 Subject: [PATCH 52/61] test(oracle-gaps): the rejected-batch history pins its config, so a random config cannot refuse it before its batch The random-seed run of the constructed history drew a CommonJS package with a .js config, which the CLI refuses before any batch, so no batch ran and no retention line was written (retentionLines:reject). The constructed history now pins its package type and config file (ordinary values, so its take-back stays in the language), and the fixed and determinism units were already unaffected. Co-authored-by: Isaac --- .../oracles/oracle-gaps/gap-report-oracle.property.test.mjs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index d19e1b94..64b7229b 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -5468,6 +5468,10 @@ oracleProperty({ stability: `none`, ordinary: false, steps: null, + packageType: `module`, + configFile: `vitest.config.ts`, + configAwait: false, + configRequire: false, rejectBatch: 1, }), }, From 92d85ae3ffe4c5e365d32da3c003395c0044027d Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sun, 15 Nov 2026 01:24:24 -0700 Subject: [PATCH 53/61] test(oracle-gaps): the rejected-batch history pins its native and config placement A random run drew a native addon and a config in the parent directory, which the CLI refused before its batch (retentionLines:reject again). The history pins both to the values of the daemon history, so no random scenario setting refuses it. Co-authored-by: Isaac --- .../oracles/oracle-gaps/gap-report-oracle.property.test.mjs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 64b7229b..05ce176e 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -5472,6 +5472,8 @@ oracleProperty({ configFile: `vitest.config.ts`, configAwait: false, configRequire: false, + configPlace: `discovered`, + native: `none`, rejectBatch: 1, }), }, From 9ab499e47753c13d5057c43f0377cdc4fc53ed6e Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sun, 15 Nov 2026 07:42:25 -0700 Subject: [PATCH 54/61] test(oracle-gaps): retention lines are attributed to the process that wrote them A line named its run's output directory only, so a daemon the CLI killed mid-check (its batches ran and wrote lines to that directory) was counted against the run that reported, which ran no batch of its own (retentionLines:daemon on the dieMidCheck step, shard 3 of the merged head). The hook line now carries the writing process's pid (observation only). A run's retention is its child's lines; the lines a daemon it killed wrote are judged as that daemon's: each complete and retired (retention:killed). A killed process reports no batch count, so its count is not judged here; the batch it died in writes no line (a Limit). Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 2 +- .../gap-report-oracle.property.test.mjs | 17 +++++++++++++++-- 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index 8f801a30..7e93db9e 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -1590,7 +1590,7 @@ export default async (env) => { environment.moduleGraph.fileToModulesMap.get(copy)?.size ?? 0 appendFileSync( file, - `${JSON.stringify(cut ? { run: hookRun, batch: evidenceOf.batches, before, cut: true } : { run: hookRun, batch: evidenceOf.batches, before, after: retentionTotals(context), copyNodes, nonCopyDup: nonCopyDuplicates(context, owned).length })}\n`, + `${JSON.stringify(cut ? { run: hookRun, pid: process.pid, batch: evidenceOf.batches, before, cut: true } : { run: hookRun, pid: process.pid, batch: evidenceOf.batches, before, after: retentionTotals(context), copyNodes, nonCopyDup: nonCopyDuplicates(context, owned).length })}\n`, ) } diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 05ce176e..36e101a7 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -734,7 +734,10 @@ function runCli(dir, files, how = {}) { env: { ...cleanEnv(), ORACLE_GAPS_TEST_RETENTION: hook, ...how.env }, }) // Each line names its check's output directory, so this run keeps only its own (a daemon serves many calls). - const retention = retentionLinesOf(hook).filter((line) => line.run === out) + // A line names the process that wrote it: this run's own lines are its child's; a daemon it killed writes others. + const retention = retentionLinesOf(hook).filter( + (line) => line.run === out && line.pid === child.pid, + ) const run = readRun( dir, out, @@ -1059,7 +1062,12 @@ async function runClisAtOnce(dir, files, hows, outs = []) { const run = readRun(dir, out, status, stderr, how.cli ?? here, stdout) return { ...run, - retention: retentionLinesOf(hook).filter((line) => line.run === out), + retention: retentionLinesOf(hook).filter( + (line) => line.run === out && line.pid === child.pid, + ), + killedRetention: retentionLinesOf(hook).filter( + (line) => line.run === out && line.pid !== child.pid, + ), } }), ) @@ -1527,6 +1535,11 @@ async function incremental(dir, plan, cli, copy, observe, states) { (run.retention ?? []).filter(leftBehind).length, ) observe(`retentionLines:daemon`, unlogged(run)) + // The batches a daemon ran before it was killed are judged as that daemon's: each complete, retired. + observe( + `retention:killed`, + (run.killedRetention ?? []).filter(leftBehind).length, + ) observe(`retentionKeys:daemon`, leftKeys(run.retention ?? [])) observe( `retention:cold`, From 099bf0a45ec7dbe121e597ec6af06c06f58a43cf Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sun, 15 Nov 2026 08:11:08 -0700 Subject: [PATCH 55/61] test(oracle-gaps): the check writes its pid under the test hook, and retention lines are attributed by it The CLI runs its check in a supervised child, so the pid of the process the driver spawned is not the process that writes the lines (the first attribution failed every cold run). Under ORACLE_GAPS_TEST_RETENTION the check writes its own pid into its output directory (observation only), and the driver attributes a run's lines to that pid. A daemon the CLI killed writes other pids, and its lines are judged as that daemon's (retention:killed). Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 6 ++++++ .../gap-report-oracle.property.test.mjs | 14 ++++++++++---- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index 7e93db9e..6bead92a 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -1596,6 +1596,12 @@ export default async (env) => { async function check(options, store, log = console.error) { hookRun = options.out + // The test hook names the process that runs the check (the CLI's supervised child, or a daemon): its + // retention lines are that process's, and the driver reads this file (observation only). + if (process.env.ORACLE_GAPS_TEST_RETENTION) { + mkdirSync(options.out, { recursive: true }) + writeFileSync(join(options.out, `check.pid`), String(process.pid)) + } heldUnits = () => store.size?.() ?? 0 const authored = options.mutants ? loadAuthored(options.mutants) : [] seedVariable = `${options.envPrefix}_SEED` diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 36e101a7..01e7692a 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -701,6 +701,11 @@ const hookOf = (dir) => { ) return hookFiles.get(dir) } +// The pid of the process that ran a check, which the check writes into its output directory under the hook. +const checkPidOf = (out) => + existsSync(join(out, `check.pid`)) + ? Number(readFileSync(join(out, `check.pid`), `utf8`)) + : undefined const retentionLinesOf = (file) => existsSync(file) ? readFileSync(file, `utf8`) @@ -734,9 +739,10 @@ function runCli(dir, files, how = {}) { env: { ...cleanEnv(), ORACLE_GAPS_TEST_RETENTION: hook, ...how.env }, }) // Each line names its check's output directory, so this run keeps only its own (a daemon serves many calls). - // A line names the process that wrote it: this run's own lines are its child's; a daemon it killed writes others. + // A line names the process that wrote it: this run's own lines are its check's; a daemon it killed writes others. + const checkPid = checkPidOf(out) const retention = retentionLinesOf(hook).filter( - (line) => line.run === out && line.pid === child.pid, + (line) => line.run === out && line.pid === checkPid, ) const run = readRun( dir, @@ -1063,10 +1069,10 @@ async function runClisAtOnce(dir, files, hows, outs = []) { return { ...run, retention: retentionLinesOf(hook).filter( - (line) => line.run === out && line.pid === child.pid, + (line) => line.run === out && line.pid === checkPidOf(out), ), killedRetention: retentionLinesOf(hook).filter( - (line) => line.run === out && line.pid !== child.pid, + (line) => line.run === out && line.pid !== checkPidOf(out), ), } }), From 38fb2d66859f9712b140aa2c6a284bd22c6023ca Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sun, 15 Nov 2026 19:07:06 -0600 Subject: [PATCH 56/61] test(oracle-gaps): rejectBatch is taken back in the model's mapping; the framework's unbuild is reverted The constructed history "a batch whose run rejects" sets the constructed-only field rejectBatch. Main's mechanism for such fields (register: generator rule, extended) takes them back inside the model's histories mapping, as it does for pauseEngages and warmReplaced, so the framework's membership check (F20) is unchanged. This reverts the ConstructedHistory.unbuild addition (954a5f3, cb25107): #61 no longer changes packages/oracles/src. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-model-oracle.mjs | 15 ++++++++--- .../gap-report-oracle.property.test.mjs | 2 -- packages/oracles/src/oracle-property.ts | 27 ++++--------------- 3 files changed, 16 insertions(+), 28 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index 15ef6b4a..920d9209 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -849,7 +849,7 @@ const drawn = fc.record({ // Only the constructed history of a replaced warm daemon sets it. warmReplaced: fc.constant(false), // The batch whose run rejects: a constructed-only field (0 is no fault). Only the constructed history at - // the end of the campaign sets it, through its unbuild mapping (the generator rule). + // the end of the campaign sets it; the take-back below returns it to 0 (the generator rule, extended). rejectBatch: fc.constant(0), }) @@ -904,20 +904,27 @@ const histories = drawn.map( if (!keepsSteps(history)) throw new Error(`a history with the witness module takes no steps`) // Take-back into the drawn language: a disarmed pause (pauseEngages false, - // only the constructed history sets it) comes back as engaged, so the - // arbitrary can shrink it. The disarm is therefore not kept by a shrink. + // only the constructed history sets it) comes back as engaged, and a + // rejected batch (rejectBatch, likewise) as none, so the arbitrary can + // shrink it. Neither is therefore kept by a shrink. const taken = history.tornRows === false ? value : { ...history, tornRows: false } const later = (history.steps ?? []).filter((step) => laterEdits.includes(step), ) if (later.length === 0) - return { ...taken, pauseEngages: true, warmReplaced: false } + return { + ...taken, + pauseEngages: true, + warmReplaced: false, + rejectBatch: 0, + } const earlier = history.steps.filter((step) => !laterEdits.includes(step)) return { ...taken, pauseEngages: true, warmReplaced: false, + rejectBatch: 0, steps: earlier.length > 0 ? earlier : null, laterSteps: later, } diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 01e7692a..251735e8 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -5471,8 +5471,6 @@ oracleProperty({ // retention line is written with its state after retirement (the bounded retention law). name: `a batch whose run rejects`, enters: [`a rejected batch retired its copies and logged them`], - // Takes the built history back to a generated one (rejectBatch 0), so that the framework can shrink it. - unbuild: (history) => ({ ...history, rejectBatch: 0 }), build: (generated) => ({ ...generated, functions: [[{ kind: `push`, quote: `'` }]], diff --git a/packages/oracles/src/oracle-property.ts b/packages/oracles/src/oracle-property.ts index 8b36fdf1..010fb8a8 100644 --- a/packages/oracles/src/oracle-property.ts +++ b/packages/oracles/src/oracle-property.ts @@ -559,12 +559,6 @@ export interface ConstructedHistory { name: string enters: ReadonlyArray build: (generated: THistory) => THistory - /** - * Takes a built history back to a generated one, so fast-check can shrink - * it (its `.map` unmapper). Without it the history is outside the - * arbitrary's language, and the framework refuses it. - */ - unbuild?: (built: THistory) => THistory } /** @@ -1788,10 +1782,7 @@ function buildConstruction( { cause: error }, ) } - // The history is taken back through its unbuild mapping (when it has one): a constructed value may - // lie outside the generator's language only where its take-back is inside it. - const takenBack = construction.unbuild?.(history) ?? history - if (!arbitrary.canShrinkWithoutContext(takenBack)) + if (!arbitrary.canShrinkWithoutContext(history)) throw untakeable(id, `constructed history "${construction.name}" built`) return history } @@ -2407,18 +2398,10 @@ function generatedTests( ? source.arbitrary : fc.oneof( { arbitrary: source.arbitrary, weight: constructions.length }, - ...constructions.map((construction) => { - const unbuild = construction.unbuild - return { - arbitrary: - unbuild === undefined - ? source.arbitrary.map(construction.build) - : source.arbitrary.map(construction.build, (built: unknown) => - unbuild(built as THistory), - ), - weight: 1, - } - }), + ...constructions.map((construction) => ({ + arbitrary: source.arbitrary.map(construction.build), + weight: 1, + })), ) for (const construction of constructions) { const undeclared = construction.enters.filter( From fdb1f5f83ee1c5aacd52f0b6cf03b1b27e3d6a71 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sun, 15 Nov 2026 19:07:29 -0600 Subject: [PATCH 57/61] test(oracle-gaps): the retention law reads real objects, judges every writer, and counts batches by their own index The retention hook moves into retention-hook.mjs, which the CLI loads only when a hook variable is set and which the package does not publish. Its fields observe the real objects (review of #61, F6): staleOpen reads Vitest's own close state of each context that left the live array, and the cold store's law counts the entries given to put that a full collection leaves reachable (held), in place of a size the store reported about itself. The openContexts set, the replacing count, the memoryStore size and evidence.batches, kept only for the hook, are deleted (F10), with the unread retireModules count and the globSpecs wrapper. Each line carries its batch's own index (F11). The law over one call's lines (retentionBreaches) judges every line for the call's --out: a line from a pid other than the check's is allowed only from a daemon the driver killed and saw die, so two processes running one call's check, or a line with no pid, is a breach (F4). A check that reached its report owns indices 0..n-1, each once; a check that ended early, a stopped run and a killed daemon own each index at most once. The warm and mid-run calls are judged too. The rejected-batch fault now rejects after the batch's run completes, so its copies are in Vitest's and Vite's state and their retirement is witnessed (F5). Its run's done line is judged on both streams, and the Limits state the actual check order. The README documents check.pid, pid, held and the new batch index (F3). Co-authored-by: Isaac --- packages/oracles/README.md | 14 +- packages/oracles/oracle-gaps/check.mjs | 188 ++--------- packages/oracles/oracle-gaps/evidence.mjs | 5 +- .../gap-report-oracle.property.test.mjs | 316 +++++++++++------- .../oracles/oracle-gaps/retention-hook.mjs | 201 +++++++++++ packages/oracles/package.json | 1 + 6 files changed, 444 insertions(+), 281 deletions(-) create mode 100644 packages/oracles/oracle-gaps/retention-hook.mjs diff --git a/packages/oracles/README.md b/packages/oracles/README.md index a5b13b92..b3fc2269 100644 --- a/packages/oracles/README.md +++ b/packages/oracles/README.md @@ -17,8 +17,16 @@ Show me what oracle testing with @tanstack/oracles can find in this repository. ## Test hooks -`ORACLE_GAPS_TEST_RETENTION` (a file path, unset in normal use) makes the gap CLI append one JSON line per mutant batch it runs, cut or not. It only observes: it never changes an outcome. The e2e oracle reads it to check bounded retention. +`ORACLE_GAPS_TEST_RETENTION` (a file path, unset in normal use) makes the gap CLI append one JSON line per mutant batch it runs, however the batch ends: settled, cut off, or rejected. It only observes: it never changes an outcome. The e2e oracle reads it to check bounded retention. The hook's code is in `oracle-gaps/retention-hook.mjs`, which the CLI loads only when this variable or `ORACLE_GAPS_TEST_REJECT_BATCH` is set. The published package does not include that file, so the hooks work only from this repository's source. -Each line has `run` (the run's `--out` path), `batch` (the batch count so far), and `before` (Vitest's and Vite's structure sizes before the batch). A settled batch also has `after` (the sizes after its copies are retired), `copyNodes` (Vite module nodes that still name a copy, must be 0), and `nonCopyDup` (non-copy files with more than one module node in an environment, must be 0 beyond the measured plain-plus-`?raw` pair). A cut batch has `cut: true` and no `after`. The `stale*` fields count registry entries that name no live context, and `staleOpen` counts open contexts beyond the live ones; all must be 0 before a batch. +Under the hook, each check also writes `check.pid` (the id of the process that runs the check: the CLI's supervised child, or a daemon) into its `--out` directory, after the CLI creates that directory. Each line has: -`ORACLE_GAPS_TEST_REJECT_BATCH` (a batch number, unset in normal use) makes the gap CLI's n-th batch run reject, as a crash in Vitest would. It is a test-only fault: it triggers the same rejection path a real crash takes, and nothing else. The run then ends as an internal error: exit 3, the done error line on both streams, and `error.log` in its output directory. The batch's copies are still retired and its retention line is still written. +- `run`: the check's `--out` path. +- `pid`: the id of the process that wrote the line. The oracle compares it with `check.pid`. +- `batch`: the batch's own index within its check, from 0, taken when the batch starts. +- `before`: Vitest's and Vite's structure sizes before the batch, and the `stale*` counts. `staleIndexed` and `staleSpecs` count registry entries that name no live context. `staleOpen` counts contexts that left the live array and that Vitest has not started to close (its own close state). All three must be 0. +- `held`: how many of the entries the check gave its store are still reachable after a full garbage collection, which the hook runs before it writes the line. A cold check's store keeps none, so this must be 0 there. A daemon's store keeps its entries by design. +- For a settled or rejected batch: `after` (the sizes after its copies are retired), `copyNodes` (Vite module nodes that still name a copy, must be 0), and `nonCopyDup` (non-copy files with more than one module node in an environment, must be 0 beyond the measured plain-plus-`?raw` pair). +- For a cut batch: `cut: true` and no `after`. Its context is replaced, not retired. + +`ORACLE_GAPS_TEST_REJECT_BATCH` (a batch number from 1, unset in normal use) makes the gap CLI's n-th batch run reject, as a crash in Vitest would. It is a test-only fault: the batch's run completes, so its copies are in Vitest's and Vite's state, and then the run's promise rejects, which takes the same path a real crash takes. The run then ends as an internal error: exit 3, the done error line, and `error.log` in its output directory. The batch's copies are still retired and its retention line is still written. diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index 6bead92a..78aba053 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -602,8 +602,6 @@ export default async (env) => { return lastServed.get(index) } const indexOf = new Map() - // The units the check's store holds, set by check() (its store's size). - let heldUnits = () => 0 let contexts = [] let contextsKey let contextsConfig @@ -612,10 +610,17 @@ export default async (env) => { let seedVariable = `ORACLE_SEED` const contextSpecs = new Map() let runCounter = 0 - // The current check's evidence, which runBatch counts its batches in (set by check). - let evidenceOf - // The output directory of the check being run (the test hook names each line with it). - let hookRun + // The retention test hook (retention-hook.mjs, README "Test hooks"): loaded + // only when one of its variables is set, so a normal run never loads it. + const hook = + process.env.ORACLE_GAPS_TEST_RETENTION || + process.env.ORACLE_GAPS_TEST_REJECT_BATCH + ? (await import(`./retention-hook.mjs`)).retentionHook({ + live: () => contexts, + indexOf, + contextSpecs, + }) + : undefined // A context loads the package's own config through its wrapper, so an // error there is the author's: the run refuses, naming the config file @@ -642,15 +647,8 @@ export default async (env) => { const limit = process.getMaxListeners() if (limit > 0) process.setMaxListeners(limit + count) } - // The contexts that are open (warmed and not yet closed): the replaced ones must leave it. - const openContexts = new Set() - // Slots between closing their context and opening the next: their open count is one short, for the - // retention law's identity (open + replacing === contexts.length), which holds at every batch boundary. - let replacing = 0 - const closeContext = (context) => { - openContexts.delete(context) - return context.close().finally(() => allowListeners(-1)) - } + const closeContext = (context) => + context.close().finally(() => allowListeners(-1)) // Vite's logger, writing each message as `oracle-gaps: note vite: …`. const viteNote = (message) => { for (const line of String(message) @@ -795,7 +793,6 @@ export default async (env) => { ) } lastServed.delete(index) - openContexts.add(context) return context } // A warm context caches the test files it found; a file added since the last check, such as a new oracle @@ -809,9 +806,6 @@ export default async (env) => { } return map } - async function globSpecs(context) { - contextSpecs.set(context, await specsOf(context)) - } async function closeContexts() { await Promise.all( contexts.map((context) => @@ -1102,11 +1096,10 @@ export default async (env) => { let copyCounter = 0 let holdCounter = 0 async function runBatch(context, out, items, seed) { - evidenceOf.batches += 1 const capture = join(out, `run-${process.pid}-${++runCounter}.jsonl`) - const before = process.env.ORACLE_GAPS_TEST_RETENTION - ? retentionTotals(context) - : undefined + // The retention hook's view of this batch: its own index, and the totals + // before it (retention-hook.mjs). + const observed = hook?.begin(context) // Each copy is named beside its file, so that its imports resolve as the // file's do, and the wrapper's plugin serves its text: nothing is // written there. @@ -1171,19 +1164,13 @@ export default async (env) => { writeFileSync(join(out, `state.json`), JSON.stringify(state)) const project = context.getRootProject() const started = Date.now() - // Test-only fault (ORACLE_GAPS_TEST_REJECT_BATCH=, inert unless set): the n-th batch's run rejects, - // as a crash in Vitest would, so the CLI's rejection path runs (register: test-only hooks). - const running = - process.env.ORACLE_GAPS_TEST_REJECT_BATCH === String(evidenceOf.batches) - ? Promise.reject( - new Error( - `oracle-gaps test fault: batch ${evidenceOf.batches} rejected`, - ), - ) - : context.runTestSpecifications( - copies.map((copy) => project.createSpecification(copy)), - false, - ) + const run = context.runTestSpecifications( + copies.map((copy) => project.createSpecification(copy)), + false, + ) + // Test-only fault (ORACLE_GAPS_TEST_REJECT_BATCH=): the n-th batch's + // run rejects once its copies are in Vitest's state, as a crash would. + const running = hook ? hook.fault(observed, run) : run // The watchdog: each copy writes a starting row when its setup runs and // a closing row when it finishes, so the copy that is running is the // last that started, or the one after it once that one closed. A copy @@ -1400,12 +1387,9 @@ export default async (env) => { // updates, so its state is not touched here. Its context is replaced // by the caller (replace), which closes it and drops its state. clearTimeout(timer) - if (raced && result === undefined) - retiredEntries(context, before, copies, true) - else { - retireCopies(context, copies) - retiredEntries(context, before, copies) - } + const cut = raced && result === undefined + if (!cut) retireCopies(context, copies) + await hook?.line(context, observed, copies, cut) rmSync(capture, { force: true }) } } @@ -1452,7 +1436,6 @@ export default async (env) => { */ function retireModules(server, gone) { const environments = viteEnvironments(server) - let removed = 0 for (const environment of environments) { const graph = environment.moduleGraph const { @@ -1473,7 +1456,6 @@ export default async (env) => { ) for (const copy of gone) { for (const mod of fileToModulesMap.get(copy) ?? []) { - removed += 1 graph.invalidateModule(mod) for (const imported of mod.importedModules) imported.importers.delete(mod) @@ -1488,7 +1470,6 @@ export default async (env) => { fileToModulesMap.delete(copy) } } - return removed } // Vite's environments, each with its module graph. A Vite that exposes none @@ -1502,107 +1483,7 @@ export default async (env) => { return environments } - // Every structure a copy can leave state in, unfiltered: Vitest's state - // (filesMap, pathsSet, idMap, errorsSet, leakSet) and each Vite environment's - // module graph (its four maps, and the nodes that hold a transform). - function retentionTotals(context) { - const { filesMap, pathsSet, idMap, errorsSet, leakSet } = context.state - const totals = { - // The cold check's store: units it keeps for reuse (none, see evidence.mjs). - store: heldUnits(), - // Identities, not sizes: a registry entry is stale unless it names a live context at its own slot - // (indexOf), or a live context (contextSpecs). Open contexts (not closed) must be the live ones. - staleIndexed: [...indexOf].filter(([c, i]) => contexts[i] !== c).length, - staleSpecs: [...contextSpecs.keys()].filter((c) => !contexts.includes(c)) - .length, - staleOpen: openContexts.size + replacing - contexts.length, - filesMap: filesMap.size, - pathsSet: pathsSet.size, - idMap: idMap.size, - errorsSet: errorsSet.size, - leakSet: leakSet.size, - } - for (const [name, environment] of Object.entries( - context.getRootProject().vite?.environments ?? {}, - )) { - const graph = environment.moduleGraph - // Vite's keys are named `vite..`, so the law can tell them from Vitest's state. - totals[`vite.${name}.url`] = graph.urlToModuleMap.size - totals[`vite.${name}.id`] = graph.idToModuleMap.size - totals[`vite.${name}.etag`] = graph.etagToModuleMap.size - totals[`vite.${name}.file`] = graph.fileToModulesMap.size - totals[`vite.${name}.transformed`] = [ - ...graph.idToModuleMap.values(), - ].filter((node) => node.transformResult != null).length - } - return totals - } - - // The test hook (ORACLE_GAPS_TEST_RETENTION, a file path): after a run - // that settled and its copies are retired, one line holds each structure's - // total before the batch and after its retirement. The bounded-retention - // law reads it: every total returns to its size before the batch. - // Files, without their query, with more than one node in an environment's graph, outside the copies: - // a non-copy file is cached once, so each count must be 0 (the law's bound on originals). - function nonCopyDuplicates(context, owned) { - const dup = [] - for (const environment of Object.values( - context.getRootProject().vite?.environments ?? {}, - )) { - const perFile = new Map() - for (const node of environment.moduleGraph.idToModuleMap.values()) { - const file = node.id.split(`?`)[0] - if (owned.has(file)) continue - perFile.set(file, [...(perFile.get(file) ?? []), node.id]) - } - // The one measured allowance: a source file's plain node and its ?raw node (the oracle reads source text - // with ?raw). One pair per file, not per batch (shard 1 on 270e6f4: the same pair in every batch line). - for (const [file, ids] of perFile) - if ( - ids.length > 1 && - !( - ids.length === 2 && - ids.includes(file) && - ids.includes(`${file}?raw`) - ) - ) - dup.push( - `${environment.name ?? `env`} ${file} ${ids.sort().join(` | `)}`, - ) - } - return dup - } - - function retiredEntries(context, before, copies, cut = false) { - const file = process.env.ORACLE_GAPS_TEST_RETENTION - if (!file) return - // A cut run is not retired (its context is replaced), so its line has no after: its before still - // names the stale totals the next batch starts from. - // Vite's graph also holds modules that are not copies (a source or harness file is cached on its - // first import, legitimately), so for Vite the law counts the copies' own nodes, which must be 0. - const owned = new Set(copies) - let copyNodes = 0 - for (const environment of Object.values( - context.getRootProject().vite?.environments ?? {}, - )) - for (const copy of owned) - copyNodes += - environment.moduleGraph.fileToModulesMap.get(copy)?.size ?? 0 - appendFileSync( - file, - `${JSON.stringify(cut ? { run: hookRun, pid: process.pid, batch: evidenceOf.batches, before, cut: true } : { run: hookRun, pid: process.pid, batch: evidenceOf.batches, before, after: retentionTotals(context), copyNodes, nonCopyDup: nonCopyDuplicates(context, owned).length })}\n`, - ) - } - async function check(options, store, log = console.error) { - hookRun = options.out - // The test hook names the process that runs the check (the CLI's supervised child, or a daemon): its - // retention lines are that process's, and the driver reads this file (observation only). - if (process.env.ORACLE_GAPS_TEST_RETENTION) { - mkdirSync(options.out, { recursive: true }) - writeFileSync(join(options.out, `check.pid`), String(process.pid)) - } - heldUnits = () => store.size?.() ?? 0 const authored = options.mutants ? loadAuthored(options.mutants) : [] seedVariable = `${options.envPrefix}_SEED` if (options.hangLimit > options.mutantLimit) @@ -1614,6 +1495,7 @@ export default async (env) => { every: Number(process.env.ORACLE_GAPS_HEARTBEAT_MS ?? 30_000), } mkdirSync(options.out, { recursive: true }) + hook?.check(options.out) // An earlier run's internal error; a completed check writes the other // files of an ending over the earlier ones (ending.mjs). rmSync(join(options.out, `error.log`), { force: true }) @@ -1663,6 +1545,7 @@ export default async (env) => { for (let i = 0; i < options.contexts; i += 1) { contexts.push(await warmContext(settings, i)) indexOf.set(contexts.at(-1), i) + hook?.joined(contexts.at(-1)) } contextsKey = JSON.stringify(settings) contextsConfig = configHash() @@ -1670,6 +1553,7 @@ export default async (env) => { while (contexts.length < options.contexts) { contexts.push(await warmContext(settings, contexts.length)) indexOf.set(contexts.at(-1), contexts.length - 1) + hook?.joined(contexts.at(-1)) } endPhase(`warm contexts`, { contexts: contexts.length }) // The run names the config its contexts loaded, before any refusal that @@ -1680,7 +1564,8 @@ export default async (env) => { settings.config ?? `none, Vitest's default discovery`, ), ) - for (const context of contexts) await globSpecs(context) + for (const context of contexts) + contextSpecs.set(context, await specsOf(context)) endPhase(`find test files`) // 1. The static half (analysis.mjs): instrumented sources, mutants, @@ -1739,10 +1624,7 @@ export default async (env) => { unchanged: 0, // Confirmations that a mutant's budget cut short or left no time. budget: 0, - // Every batch run (runBatch), cut or not: each writes one retention line. - batches: 0, } - evidenceOf = evidence // Each file's imports in its unmutated run. A run that timed out reports // none, so it is stored under these: a mutant changes no import. const fileInputs = new Map() @@ -1801,7 +1683,10 @@ export default async (env) => { return stable ? inputs : undefined } const remember = (id, unit, inputs) => { - if (inputs) store.put(id, { inputs, unit }) + if (!inputs) return + const entry = { inputs, unit } + hook?.stored(entry) + store.put(id, entry) } // A batch run in a slot's context, with the inputs to store each item // under: the modules its file's unmutated run read, and those its copy @@ -2072,14 +1957,12 @@ export default async (env) => { // it stops the worker. const replace = async (slot) => { const started = Date.now() - replacing += 1 await Promise.race([ closeContext(slot.context).catch(() => undefined), sleep(10_000), ]) const replaced = slot.context const next = await warmContext(settings, slot.index) - replacing -= 1 const specs = await specsOf(next) // One synchronous step: the replaced context leaves every map keyed by it and the new one joins them, // with the contexts array, so no reader (and no measurement) sees the registry and the array disagree. @@ -2089,6 +1972,7 @@ export default async (env) => { contextSpecs.set(next, specs) contexts[slot.index] = next slot.context = next + hook?.joined(next) span(`replace context`, started, { slot: slot.index }) } // `after(index)` is more work for context `index` once its files ran. diff --git a/packages/oracles/oracle-gaps/evidence.mjs b/packages/oracles/oracle-gaps/evidence.mjs index 5a2e9581..acf46003 100644 --- a/packages/oracles/oracle-gaps/evidence.mjs +++ b/packages/oracles/oracle-gaps/evidence.mjs @@ -61,10 +61,11 @@ const withVersion = (row, variant) => * The store of a cold check. It keeps no unit: a cold run serves no lookup * (its evidence reports `reused` 0 on every klona run measured), so a unit * kept for reuse would only be retained, per mutant copy, for the whole run. - * `size` counts what it holds, for the retention law (check.mjs). + * The retention law observes this through the entries' reachability + * (retention-hook.mjs), not through anything the store reports. */ export function memoryStore() { - return { get: () => undefined, put: () => {}, size: () => 0 } + return { get: () => undefined, put: () => {} } } /** diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 251735e8..a92ce6a6 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -647,50 +647,88 @@ const configArgs = (plan) => ({ contexts: plan.contexts, }) -// Exact: a run writes one retention line per batch it ran (evidence.batches, cut batches -// included), so its line count must equal that counter. Zero batches write none. -// The batch-line count is owed only with a report: a run with no report is judged by the completion -// law (cli: the model predicts a report unless it predicts a refusal), which fails it there with its -// stderr. This check does not fail a run for lacking a report, so the two laws never both judge it. -const unlogged = (run) => - run.evidence === undefined || run.retention.length === run.evidence.batches - ? 0 - : 1 - -// A batch line (ORACLE_GAPS_TEST_RETENTION) left state behind when a total -// after its retirement differs from its size before the batch. -// The keys a settled batch left behind, sorted, for a violation's message. -const leftKeys = (lines) => - [ - ...new Set( - lines.flatMap((line) => [ - ...((line.copyNodes ?? 0) !== 0 ? [`copyNodes`] : []), - ...((line.nonCopyDup ?? 0) !== 0 ? [`nonCopyDup`] : []), - ...Object.keys(line.before ?? {}).filter( - (key) => - !key.startsWith(`vite.`) && - ((key.startsWith(`stale`) && line.before[key] !== 0) || - (line.after !== undefined && - line.before[key] !== line.after[key])), - ), - ]), - ), - ] - .sort() - .join(`, `) - -const leftBehind = (line) => - (line.copyNodes ?? 0) !== 0 || - (line.nonCopyDup ?? 0) !== 0 || - Object.keys(line.before).some( - (key) => - // Vite's totals are `vite..`: its non-copy modules are cached legitimately - // (checked by the copies' own nodes, copyNodes, and by the bound still to add). - !key.startsWith(`vite.`) && - ((key.startsWith(`stale`) && line.before[key] !== 0) || - (line.after !== undefined && line.before[key] !== line.after[key])), +// ### Bounded retention: the law over one call's retention lines +// +// The retention hook (ORACLE_GAPS_TEST_RETENTION, retention-hook.mjs) writes +// one line per batch, however the batch ends (runner law L2): settled, cut +// off, or rejected. Each line names the check's output directory (`run`), the +// process that wrote it (`pid`), and the batch's own index within its check +// (`batch`, from 0, taken when the batch starts). The law over one CLI call's +// lines, independent of every counter the CLI keeps: +// +// - Ownership: a line is the call's own when its pid is the pid the call's +// check wrote (check.pid). The one other pid allowed is a daemon that the +// driver killed during the call and saw die (daemonChecks); its lines judge +// that process's batches up to its death. A line from any other pid, or +// with no pid, is a breach: two processes ran one call's check. +// - One line per batch: a check that ran to its report owns lines whose +// indices are exactly 0..n-1, each once. A check that ended before its +// report (a rejected batch, a stop) or a killed daemon may leave the +// batches it was running unlogged, so there each index appears at most +// once. A rejected batch's own line, with its state after retirement, is +// owed. +// - Retirement: after a settled batch, no Vite node names one of its copies +// (copyNodes), no non-copy file has more than one node beyond the measured +// plain-plus-?raw pair (nonCopyDup), and Vitest's state (filesMap, pathsSet, +// idMap, errorsSet, leakSet) has its size before the batch. Vite's totals +// (`vite.*`) are not compared: Vite caches non-copy modules legitimately +// (register: #61 retention decisions (3)). +// - No stale entry, before any batch: every indexOf entry names a live +// context at its own slot, every contextSpecs key a live context, and no +// context that left the live array is unclosed by Vitest's own state +// (staleIndexed, staleSpecs, staleOpen). +// - A cold check's store keeps nothing (register: #61 retention decisions +// (1)): of the entries the check gave its store, none is reachable after a +// full collection (`held`). A daemon's store keeps its entries by design, +// so `held` is judged on cold calls only. +// +// The breaches are returned as sorted names, so a passing call observes []. +function retentionBreaches( + lines, + { checkPid, killed, complete, cold, rejectBatch = 0 }, +) { + const breaches = new Set() + const own = lines.filter( + (line) => line.pid !== undefined && line.pid === checkPid, + ) + const dead = lines.filter( + (line) => killed !== undefined && line.pid === killed, ) + if (own.length + dead.length < lines.length) breaches.add(`foreignLine`) + const indices = (group) => + group.map((line) => line.batch).sort((a, b) => a - b) + const once = (group) => + indices(group).every( + (index, i, all) => Number.isInteger(index) && index !== all[i - 1], + ) + const exact = (group) => indices(group).every((index, i) => index === i) + if (!(complete ? exact(own) : once(own))) breaches.add(`batchIndex`) + if (!once(dead)) breaches.add(`killedIndex`) + if ( + rejectBatch > 0 && + !own.some( + (line) => line.batch === rejectBatch - 1 && line.after !== undefined, + ) + ) + breaches.add(`rejectLine`) + for (const line of [...own, ...dead]) { + if ((line.copyNodes ?? 0) !== 0) breaches.add(`copyNodes`) + if ((line.nonCopyDup ?? 0) !== 0) breaches.add(`nonCopyDup`) + if (cold && line.held !== 0) breaches.add(`held`) + for (const key of Object.keys(line.before ?? {})) + if ( + !key.startsWith(`vite.`) && + ((key.startsWith(`stale`) && line.before[key] !== 0) || + (line.after !== undefined && line.before[key] !== line.after[key])) + ) + breaches.add(key) + } + return [...breaches].sort() +} +// One hook file per package, in its own temporary directory (removed with the +// package, `dropHook`): a daemon keeps the environment of the call that +// started it, so every call for this package writes to the same file. const hookFiles = new Map() let runSeq = 0 const hookOf = (dir) => { @@ -701,7 +739,12 @@ const hookOf = (dir) => { ) return hookFiles.get(dir) } -// The pid of the process that ran a check, which the check writes into its output directory under the hook. +const dropHook = (dir) => { + const file = hookFiles.get(dir) + hookFiles.delete(dir) + if (file) rmSync(dirname(file), { recursive: true, force: true }) +} +// The pid of the process that ran a check, which the hook writes into the check's output directory. const checkPidOf = (out) => existsSync(join(out, `check.pid`)) ? Number(readFileSync(join(out, `check.pid`), `utf8`)) @@ -738,12 +781,11 @@ function runCli(dir, files, how = {}) { maxBuffer: 64 * 1024 * 1024, env: { ...cleanEnv(), ORACLE_GAPS_TEST_RETENTION: hook, ...how.env }, }) - // Each line names its check's output directory, so this run keeps only its own (a daemon serves many calls). - // A line names the process that wrote it: this run's own lines are its check's; a daemon it killed writes others. + // Each line names its check's output directory, so this call keeps every + // line for its own directory, whichever process wrote it (retentionBreaches + // judges the writer). const checkPid = checkPidOf(out) - const retention = retentionLinesOf(hook).filter( - (line) => line.run === out && line.pid === checkPid, - ) + const retention = retentionLinesOf(hook).filter((line) => line.run === out) const run = readRun( dir, out, @@ -765,6 +807,7 @@ function runCli(dir, files, how = {}) { strayWrites: strays(dir, before, relative(dir, out)), replay, retention, + checkPid, } } @@ -936,6 +979,7 @@ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { retention: retentionLinesOf(hook).filter( (line) => line.run === join(dir, `out-stop`), ), + checkPid: checkPidOf(join(dir, `out-stop`)), // Whether a refusal's block reached stderr: a stop is never a refusal. refused: stderr.split(`\n`).some((line) => line.startsWith(`refused: `)), exit: exitCode, @@ -1068,12 +1112,8 @@ async function runClisAtOnce(dir, files, hows, outs = []) { const run = readRun(dir, out, status, stderr, how.cli ?? here, stdout) return { ...run, - retention: retentionLinesOf(hook).filter( - (line) => line.run === out && line.pid === checkPidOf(out), - ), - killedRetention: retentionLinesOf(hook).filter( - (line) => line.run === out && line.pid !== checkPidOf(out), - ), + retention: retentionLinesOf(hook).filter((line) => line.run === out), + checkPid: checkPidOf(out), } }), ) @@ -1536,20 +1576,24 @@ async function incremental(dir, plan, cli, copy, observe, states) { ? (daemon.evidence?.computed ?? 0) - (daemon.evidence?.cut ?? 0) : undefined for (const [i, run] of [daemon, ...others].entries()) { + // A daemon's call: the daemon the driver killed during it, if any, wrote + // the lines of its own batches (daemonChecks). observe( `retention:daemon`, - (run.retention ?? []).filter(leftBehind).length, - ) - observe(`retentionLines:daemon`, unlogged(run)) - // The batches a daemon ran before it was killed are judged as that daemon's: each complete, retired. - observe( - `retention:killed`, - (run.killedRetention ?? []).filter(leftBehind).length, + retentionBreaches(run.retention, { + checkPid: run.checkPid, + killed: run.killed, + complete: run.reported, + cold: false, + }), ) - observe(`retentionKeys:daemon`, leftKeys(run.retention ?? [])) observe( `retention:cold`, - (coldRun.retention ?? []).filter(leftBehind).length, + retentionBreaches(coldRun.retention, { + checkPid: coldRun.checkPid, + complete: coldRun.reported, + cold: true, + }), ) observe(`incremental`, { step: i === 0 ? step : `${step} (a second check at once)`, @@ -1787,6 +1831,17 @@ async function incremental(dir, plan, cli, copy, observe, states) { path.endsWith(`/midrun.txt`), ) midrunChecks = { during, before: runCli(dir, before, how), landed } + // The check the edit overlapped, through the daemon, and the cold run of + // the state before the edit: each call's lines are judged as any call's. + for (const run of [during, midrunChecks.before]) + observe( + `retention:midrun`, + retentionBreaches(run.retention, { + checkPid: run.checkPid, + complete: run.reported, + cold: run === midrunChecks.before, + }), + ) return [next] } if (step !== `dieMidCheck` && step !== `resetBeforeRead`) @@ -1822,9 +1877,17 @@ async function incremental(dir, plan, cli, copy, observe, states) { // served mark holds (the witness for the warm label). let warm if (!mid) { - await runClisAtOnce(dir, files, [ + const [warmRun] = await runClisAtOnce(dir, files, [ { ...how, daemon: true, outName: `out-warm`, env }, ]) + observe( + `retention:warm`, + retentionBreaches(warmRun.retention, { + checkPid: warmRun.checkPid, + complete: warmRun.reported, + cold: false, + }), + ) warm = pidOf(servedMark) // The warm daemon is stopped before the pause is armed: an armed daemon // holds the stop's own connection unread, so the stop would never end. @@ -1865,6 +1928,8 @@ async function incremental(dir, plan, cli, copy, observe, states) { if (killed) process.kill(pid, `SIGKILL`) const gone = killed ? await waitGone(pid) : false const runs = await running + // The daemon the driver killed, once it is dead: its lines are its own. + if (killed && !isAlive(pid)) runs[0].killed = pid rmSync(marks, { recursive: true, force: true }) // Each label needs its pause's observation: a kill the driver sent and saw // through (gone), and the CLI's report of the check. A label without a pause @@ -2015,7 +2080,7 @@ async function driver(plan, observe) { ? { env: { ORACLE_GAPS_TEST_REJECT_BATCH: String(plan.rejectBatch) } } : {}), } - const { replay, retention, ...cli } = runCli( + const { replay, retention, checkPid, ...cli } = runCli( dir, files, plan.tornRows @@ -2060,26 +2125,25 @@ async function driver(plan, observe) { ? { exit: cli.exit, lastLine: cli.lastLine, + // The done line ends both streams (P10): stderr's last line. + stderrLast: cli.stderr?.trimEnd().split(`\n`).at(-1), configLines: cli.configLines, strayWrites: cli.strayWrites, warnings: cli.warnings, } : { ...cli, evidence: undefined }, ) - // Deterministic: how many batches left a retired copy's state behind (0), - // not the per-batch lines, whose batch splits vary with hang cuts. - observe(`retention`, retention.filter(leftBehind).length) - observe(`retentionKeys`, leftKeys(retention)) - // A rejected batch (a constructed fault) owes its own retention line, written after its copies retire. - if (plan.rejectBatch > 0) { - observe( - `retentionLines:reject`, - retention.some((line) => line.batch === plan.rejectBatch) ? 0 : 1, - ) - } + // Deterministic: the law's breaches (none), not the lines, whose batch + // splits vary with hang cuts. A rejected batch (a constructed fault) ends + // the check before its report, and owes its own line. observe( - `retentionLines:cold`, - unlogged({ retention, evidence: cli.evidence }), + `retention`, + retentionBreaches(retention, { + checkPid, + complete: cli.reported, + cold: true, + rejectBatch: plan.rejectBatch, + }), ) // A failing owner's replay, run as the author would run it (law 3). if (plan.fault === `brokenOwner`) @@ -2089,7 +2153,10 @@ async function driver(plan, observe) { if ( plan.rejectBatch > 0 && retention.some( - (line) => line.batch === plan.rejectBatch && line.after !== undefined, + (line) => + line.pid === checkPid && + line.batch === plan.rejectBatch - 1 && + line.after !== undefined, ) ) states.add(`a rejected batch retired its copies and logged them`) @@ -2112,9 +2179,14 @@ async function driver(plan, observe) { only: ids, outName: `out-only`, }) - observe(`retention:partial`, partial.retention.filter(leftBehind).length) - observe(`retentionLines:partial`, unlogged(partial)) - observe(`retentionKeys:partial`, leftKeys(partial.retention ?? [])) + observe( + `retention:partial`, + retentionBreaches(partial.retention, { + checkPid: partial.checkPid, + complete: partial.reported, + cold: true, + }), + ) observe(`partial`, { function: chosen.function, source: chosen.source, @@ -2142,15 +2214,22 @@ async function driver(plan, observe) { // of them the previous stopped run had left. if (cli.exit === 0 && stopIds.length > 0) for (const stop of plan.stopRuns) { - const { retention, ...run } = await stoppedRun( + const { retention, checkPid, ...run } = await stoppedRun( dir, files, how, stopIds, stop, ) - observe(`retention:stop`, retention.filter(leftBehind).length) - observe(`retentionKeys:stop`, leftKeys(retention)) + // A stopped check ends before its report: each index at most once. + observe( + `retention:stop`, + retentionBreaches(retention, { + checkPid, + complete: false, + cold: true, + }), + ) const stopped = { ...run, sessions: { @@ -2547,14 +2626,20 @@ async function driver(plan, observe) { const moved = { ...files, [SOURCE]: edited(plan) } // The evidence counts are not observed, as for `cli`: they depend on // timing (oracles-followups.md G1). Verdicts and keys are. - const { retention: movedRetention, ...movedRun } = runCli(dir, moved, how) + const { + retention: movedRetention, + checkPid: movedPid, + ...movedRun + } = runCli(dir, moved, how) observe(`stability`, { ...movedRun, evidence: undefined }) - observe(`retention:stability`, movedRetention.filter(leftBehind).length) observe( - `retentionLines:stability`, - unlogged({ retention: movedRetention, evidence: movedRun.evidence }), + `retention:stability`, + retentionBreaches(movedRetention, { + checkPid: movedPid, + complete: movedRun.reported, + cold: true, + }), ) - observe(`retentionKeys:stability`, leftKeys(movedRetention)) states.add(`stability rerun`) } if (plan.steps.length > 0) @@ -2564,6 +2649,7 @@ async function driver(plan, observe) { if (copy) rmSync(copy, { recursive: true, force: true }) removePath(`${dir}.link`) written.delete(dir) + dropHook(dir) try { rmSync(scratch, { recursive: true, force: true }) } catch { @@ -2760,51 +2846,33 @@ function check(plan, observations, expected) { ? streamBreach(`cli`, cli, expected, plan) : undefined if (stream) return stream - // Bounded retention (the register's C entry): once a batch's copies are - // retired, Vitest's filesMap, pathsSet, and idMap and Vite's module graph - // name none of them, so each count the hook reports is 0. - const unlogged_ = observations - .filter((o) => o.checkpoint.startsWith(`retentionLines`)) - .reduce((sum, o) => sum + o.value, 0) - if (unlogged_ > 0) - return violation( - `retention`, - `${unlogged_} run(s) wrote a retention line count different from their batches (${observations - .filter((o) => o.checkpoint.startsWith(`retentionLines`) && o.value > 0) - .map((o) => o.checkpoint) - .join(`, `)})`, - `bounded retention`, - { actual: unlogged_, expected: 0 }, - ) - const fields = observations - .filter((o) => o.checkpoint.startsWith(`retentionKeys`)) - .map((o) => o.value) - .filter(Boolean) - .join(`, `) - const held = observations - .filter( - (o) => - o.checkpoint.startsWith(`retention`) && - !o.checkpoint.startsWith(`retentionKeys`), - ) - .reduce((sum, o) => sum + o.value, 0) - if (held > 0) + // Bounded retention (retentionBreaches): every call's lines are its own + // check's, or a daemon's that the driver killed, one per batch, and each + // settled batch retired its copies, with no stale entry and no unit kept by + // a cold store. + const breached = observations.filter( + (o) => o.checkpoint.startsWith(`retention`) && o.value.length > 0, + ) + if (breached.length > 0) return violation( `retention`, - `${held} batch(es) left a retired copy's Vitest or Vite state behind (fields: ${fields || `none named`})`, + `retention lines break the law: ${breached + .map((o) => `${o.checkpoint} (${o.value.join(`, `)})`) + .join(`; `)}`, `bounded retention`, - { actual: held, expected: 0 }, + { actual: breached.map((o) => [o.checkpoint, o.value]), expected: [] }, ) // A rejected batch (the constructed fault) ends the run as an internal error: exit 3 and its done line // (ending.mjs). Retention was judged above, so only the ending is judged here, and the run is then done. if (expected.rejectedBatch !== undefined) { if ( cli.exit !== 3 || - !cli.lastLine?.startsWith(`oracle-gaps: done error, log `) + !cli.lastLine?.startsWith(`oracle-gaps: done error, log `) || + !cli.stderrLast?.startsWith(`oracle-gaps: done error, log `) ) return violation( `cli`, - `the rejected batch owes exit 3 and an internal error's done line, got exit ${cli.exit} ending ${JSON.stringify(cli.lastLine)}`, + `the rejected batch owes exit 3 and an internal error's done line on both streams, got exit ${cli.exit} ending stdout with ${JSON.stringify(cli.lastLine)} and stderr with ${JSON.stringify(cli.stderrLast)}`, `internal error`, ) return pass @@ -4109,7 +4177,7 @@ oracleProperty({ law: { statement: `The gap report enumerates the promised operator mutants, leaves out exactly the probe-only code, discovers every oracle that owns a function's call tree and refuses broken ownership, judges each mutant only by its owners' tests on their registered routes and counts only law verdicts on reproducible routes as kills, which outrank a run that never ends, anchors each mutant by its function and normalized statement, lists every gap and unowned mutant once with consistent counts, keeps keys stable under unrelated edits, reports through one daemon per package what a cold run reports at every state of a sequence of edits, and bounds the runs that confirm a mutant's cut-off copies by one budget per mutant and names each busy mutant in a heartbeat while it runs, leaves nothing in the package and writes nothing where Vitest's include could find it while it runs, leaves no process running once it is stopped, runs the package as Vitest does from any install path and any --source spelling: one instance of each workspace dependency, no refusal over an unbuildable devDependency, child processes for a native addon anywhere in the tree, a capture that a test's builtin spies cannot see, and a refusal of test.projects; leads its report with every test file's baseline, blocks only the mutants a failing oracle file owns and judges the rest, prints every line of its stream with the prefix oracle-gaps: and its kind, one decisive baseline line before any mutant, and a done line last, and every run that does not complete ends, cold or through the daemon, with a refusal that exits 2, prints a refused: block and one fix: directive with no stack trace, and writes the refusal to the run's output directory.`, authority: `The maintainer's decisions in design runs v11, v14, and v19 (2026-11-04 and 2026-11-05), not in this package's records, including that a kill by reach agreement alone is a gap and that an incremental run through the daemon equals a cold one (v19.3); the project's oracle guide on quiet exclusions; the oracle rubric's outcome kinds (ORC-006); the CLI's documented operator list in schemata.mjs; the maintainer's dispositions G1, G2, G4, G5, G6, and G13 of the framework papercut ledger (2026-11-11) and the v20 freeze's namespacing, one-loop, and provisional-report decisions (2026-11-10); the maintainer's request for a greppable stream (2026-11-12, relayed by the coordinator with its decisions of that day: the same prefixes on stdout and stderr, a done line for a stopped run, and no --max-gaps).`, - limits: `Law 12 judges refusals only, and the constructed rejected-batch history (rejectBatch, a test-only fault) only as exit 3 with its internal-error done line, with its retention judged first and its namespace law still applied; no legal history reaches an internal error otherwise, so its shape (the stack in error.log) is not judged. The run whose process aborts is declared on every platform. Its win32 witness (process.abort through ORACLE_GAPS_TEST_ABORT_AT, under the win32 supervisor) lands in #79; until then the Windows end-to-end job is non-blocking (C entry (c)). On win32 Node cannot deliver SIGTERM (its kill is TerminateProcess, which ends the process with no stopped line), so the stop states that name SIGTERM are required on POSIX only, and a stop there goes through the CLI's test stop hook and is observed as SIGINT; every SIGINT state stays required on win32. Law 12 judges refusals only: no legal history reaches an internal error, so its shape (exit 3, the stack in error.log) is not judged; argument refusals are the static oracle's; the check's rejection of a stack trace, a missing fix, and a wrong exit code is calibrated in the static oracle, through the same refusalBreach, and here only a refused run reported as complete is calibrated, because each calibration here runs real CLI histories. Hangs only as an owner test that awaits a promise that never settles, under a 1 s first budget and a 20 s full limit, and a slow run only as two witnesses whose tests wait where the output changed, 3 s in one that then judges and 10 s in two one-test owners of one that does not; busy loops only on instrumented code (cut by the call budget), no slow runs past the full limit that would end, hangs in ordinary or nondeterministic tests, setup errors other than a throw at module load, loops, multi-line conditions, two functions on one line, or await, new, and void statements; nested functions, object-literal methods, accessors, and class-field arrows only where no test calls them (their ownership is the static oracle's); two source files of one package, with no re-exports, namespace imports, or calls into another package; --only only in a stopped run and a partial run of one function's mutants, and no --sample or --diff-base; the baseline's failures only as one failing owner test that throws an error and a setup file that throws, so a baseline law violation's law and counterexample lines are the classify oracle's; a derived class's file is instrumented and its sites are judged as unowned, but no test imports or constructs the class, so its no-mutant and super-region behavior is the static oracle's (in-process), not this oracle's; package configs only as vite.config or vitest.config with one of the extensions .ts, .mts, .cts, .js, .mjs, and .cjs (not every pair), as config/gap-vitest with the same extension through --config, or none, as an object or a sync or async function, with no plugins of their own except one enforce: 'pre' transform that appends a comment to each module of the package (prePlugin); a plugin whose output depends on anything but the module's text (a sidecar file it reads) and an environment variable that changes between checks are not generated, since the runner tracks neither yet and the daemon's environment is fixed when it starts (F-A1: the maintainer decided on 2026-11-13 that the daemon tracks both and restarts when they change, in the next pull request); and test.projects only as a refusal, and only under the package's own package.json; a top-level await only in an ES module config and require only in a CommonJS one, as Vitest itself loads no other; a --config outside the package is refused by design, through the rule for paths outside the package (args.mjs), and no history generates one; contexts only one, four, or eleven, and process warnings judged only as MaxListenersExceededWarning on the CLI's own stderr (a daemon's process warnings go to its log); a context that fails to open gives back its listener allowance, which no observation shows (a kept allowance only raises the limit, so no warning follows), so that accounting is fixed by inspection; no probe-bound states, so reach agreement's killing of probe mutants is not checked; no gap answers or gate; law 9 judges the witness module's outcome classes along one constructed edit sequence only (a test edit, a helper edit, and a revert), and the budget witness's along one constructed second check with nothing changed, because a generated history with the witness module or the budget witness takes no steps (maintainer decision, 2026-11-11, and the runtime review's P1-a, 2026-11-12; this oracle owns the gap); law 9's edits come between checks, except one, midrun, which lands during a check through the daemon: a test of file a, whose context has loaded file b's helper, rewrites the helper in the baseline's first run of file a, before file b's runs read it, in one context or several; or a test of file b rewrites its own helper, or the data file that its verdict read through a sync fs read, after file b's judged tests read them, in the run that judges with the old text (review of #55, F1); that check must report, for each mutant, what a cold run of the state before the edit or of the state after it reports, and exit as one of them does (third review of #55, F-C), compared per mutant result rather than per file; when file b's own test lands the edit, b's baseline reads the old text and b's mutant runs read the new one, so b's own mutants in that check are not judged, since their results legitimately mix the two texts (maintainer decision, 2026-11-13), while every other mutant there is judged against both cold runs, with the check's exit code, its mutants' keys, and its stream; the stronger follow-up compares each run's raw outcome with the cold outcome of the state that run read; and the next check, with nothing changed, must equal a cold run of the state after the edit, compared for equality of results only, not for what the daemon reused or computed (the runner's rule: a run whose input changed after the run read it is invalidated and not stored, settleIn); a check through the daemon of a state that nothing changed must compute no run that was not cut off, judged where no test reads the clock (F-A, F-A2), and a test's fs read of a file and the module that the context serves from it are two inputs, each under its own hash (F-A2); an edit during a mutant run is not generated, and a file is edited mid-run only by the run's own tests, not by another process at an arbitrary time; a file that a test reads through fs is edited only as one JSON file that file b's verdict reads by a sync, a promise, or a callback read, or by a sync read after it stats its own directory and tests that it exists (statDir: the directory is an input as a directory, not by its content, and is not itself edited), each read first checking that its fs function keeps its own name and length (the runner stores a run under the files in the package that its copy reads with readFileSync, readFile, existsSync, or statSync, or the fs/promises readFile or stat, each with its hash at the copy's first read; a read outside the package or under node_modules, from a worker thread or a child process that a test starts, or through any other fs API, which includes readdir, opendir, glob, globSync, createReadStream, realpath, lstat, access, open, a read through a file descriptor (read, readSync, readv, fstat, fstatSync, and readFileSync or readFile given a file descriptor), copyFile and copyFileSync, cp and cpSync, openAsBlob, statfs, readlink, the callback stat, exists, watch, watchFile, and the fs/promises access, open, and glob, is no input, and none is generated: the maintainer decided on 2026-11-13 that every fs read except watch and watchFile is an input, which a follow-up of #55 implements, and until then this oracle owns the gap); a run cut off by its clock writes no closing row, so it is stored under its file's known inputs only, while a run that spun ends and keeps the inputs it named (F-D); no history makes a cut run read a file that its file's unmutated run does not read, so this is fixed by inspection; a test that rewrites a file it read with the same text makes the next check compute that run again (1 run in the self-edit histories), since the edit changes the file's modification time: the daemon is conservative there, nothing goes stale, and content keys (D10) remove it, with a selfWrite dimension in that pull request; the mid-run marker sits in the daemon's session directory, .oracle-gaps-, whose location predates #55; the runner's hash memo knows a file by its size and modification time, so an edit that keeps both is not seen, and no history makes one (D10, planned in phase 2, A5); law 9's edits leave out other environment variables, new files that change how an unchanged import resolves, Vite config and installed-package changes, and concurrent checks other than two that start the daemon; cut-off charging judged only under one budget; native addons only as a binding.gyp or a prebuilt .node file, not as optional platform packages; daemon races (two CLIs reading one error file, a CLI hearing closing from the failing daemon it started, a reset connection on macOS) fixed by inspection; the runner's copies of the test files exist only in memory, and its harness and Vitest configs sit in the package's .oracle-gaps-, which the next run removes once a killed run has left it (judged after two stopped runs, not after a SIGKILL); a default --out is judged by the static oracle, and these runs name --out in the package; the namespace is checked after each run and, in a stopped run, while the run runs; a slow kill in a later owner, after earlier owners' confirmations spent the budget, becomes a timeout (owner order; not generated); the Vitest 5 path of the copies' pragma read and of the runner is verified from Vitest 5's source only, since the Vitest 5 CI job runs no gap oracle; a batch whose run reports an error outside any test reruns each copy alone (unitsBatch, runAlone) with its first budget, and a copy cut there is kept as a timeout with no confirmation, a defect older than this oracle's budget work that no history reaches (no history has an error outside any test beside a slow copy), recorded here with that trace for the maintainer; stale-session removal is scoped to this host's session directories (a host file), and is not judged across pid namespaces; the stop law covers SIGTERM and SIGINT sent to the CLI, not a SIGKILL of the CLI (its group then ends at the next check of its parent, by inspection) or a signal sent to the daemon, and its witness is one test that spins synchronously and starts one child process; the mutant budget is witnessed as two slow owners whose confirmations pass the --mutant-limit floor, not through its multiple of the owners' unmutated time, and authored mutants have no confirmations to budget; the witness w_slowpair is a wall-clock window, since the CLI's budget has no controlled clock and a fixture cannot see the time the CLI measures for its file: with one-test owner files p and q of measured unmutated time t each (a file first in its context pays the instrumented transform too), a wait W of 10 s, a 20 s --hang-limit and a 15 s --mutant-limit, it tells a budget from none only while (a) its first attempt is cut, W > 1 s + 3t, (b) its two confirmations do not fit the budget, 2W > max(15 s, 10 x 2t), and (c) each would fit its own full limit, W < 20 s + 3t; (b) is the binding one, so it holds while the two files' time stays under about 2 s together (about 1 s each, some 20 times the authoring machine's idle and 5 to 10 times its loaded measurements), and under one budget a run's overhead must stay under 10 s + 3t; CI runners measure 1.5 to 2.3 times the idle machine; beyond that w_slowpair would read not-judged; a heartbeat is owed only where a slow test waits 3 s against a 2 s interval, twice the first budget, so that no copy cut at its first budget beats, and each beat is observed as its mutant and file, not how long or how often it beat; a config only in the package's parent directory is generated one level up, in a temporary directory with no package.json (so its .js or .ts name is CommonJS), as a plain config, one that throws, one with no default export, or one that defines test.projects; a config two or more levels up, or a parent config beside a package config, is not generated, and the order in one directory follows Vitest's configFiles list by inspection; a package with no config lives in a temporary directory, where no parent has a config; a counterexample shrinks through at most six histories, so it can be larger than the smallest that fails; module-level data only as four \`const\` declarations of the main source (an object literal, an array that holds a function, a boolean, and an object of two methods), read in place, with no data imported from another file, destructured, reassigned, or declared as an enum or a default export; the work law only through shortcut witnesses (an early return before a counting loop with a bound twin of ratio 2, and a push beside one that calls String with a bound twin of ratio 1), the early return in tests that reach the clock by each watched path and in tests that wait a turn, a generated test's bound of 1 derived from its plan (which no generated function's mutant reached in the 36 fixed-seed units at main's bases; the disarmed-pause history's base, appended at its index, does reach it, so that history pins its generated inputs to ones that declare no bound, and the model predicts no work verdict for a generated test, a model gap for the maintainer to decide whether to model work counts), and one warm-cache witness whose selection reproduces observations but not work; work is the capture's count of site evaluations per test, so code with no site (a plain assignment, a for...of pass, a builtin's own work) counts nothing and a test's histories are summed, and a test whose work varies between the unmutated runs while its observations agree is not generated. Open Limits, owned by the in-process runner oracle (L1, state \"torn tail at a cut-off read\"; RED: captureLines without the guard): (a) the batch's cut-off read (runBatch's rowsOf after the cut-off) drops a partial last row, and no witness reaches that drop yet, because a copy held half written across the cut-off did not observe its release in the harness; (b) a short fragment on the strict path, which the no-newline mutant does not reach. The strict read after a finished run (a fragment is an internal error) is witnessed by the no-newline mutant. Windows idle gap (recorded, not witnessed): the state \`a hang cut off for idleness\` is required on every platform, and win32 reaches it (run 43683794816, job 132719872988), so it is not platform-scoped. The sampler (capture-setup.mjs) counts a copy idle only after 500 ms with no late tick, no non-quiet handle, utilization at most 5%, and no timer due, so \`every outcome class\` reaches the state only when the sampler sees that window. On win32 the check missed it once (run 43683794816, job 132719872940); the cause is not confirmed (a late tick on a shared runner, or a stdio handle outside \`quiet\` for this file's console output, are the candidates). Its witness, a test-only hold at the hang until the window is seen, is owed, and that is a timing dependency the determinism-under-load rule forbids; the maintainer decides whether it lands before the Windows job becomes blocking.`, + limits: `Law 12 judges refusals. The one internal error a history reaches is the constructed rejected-batch history (rejectBatch, a test-only fault that rejects a batch's run after its copies are in Vitest's and Vite's state). Its run is judged in this order: the output namespace, process warnings, and config lines, as for any run; then bounded retention, which owes the rejected batch's own line with its state after retirement; then exit 3 with an internal error's done line last on both streams. The stream law is not applied to it, and the stack in its error.log is not judged. Bounded retention reads the hook's lines (retention-hook.mjs). Its count of one line per batch (runner law L2) rests on the index the hook takes when a batch starts, so a CLI that skipped a batch's index and its line together, or that omitted only the line of a check's last batch, keeps the indices 0..n-1 and is not seen; a check that ended before its report (the rejected batch, a stopped run) and a daemon the driver killed are judged for at most one line per index, since the batches they were running at their end owe none. A line's process is told by check.pid, which the check writes, and the driver itself knows only the daemon it killed. The cold store's law (held) counts the entries given to the store's put that a full collection leaves reachable, so a store that kept only a part of an entry (its unit without the entry) is not seen; staleOpen reads Vitest's own close state (closingPromise, set when close starts), so a close that starts and never resolves is the runner oracle's (L8); and a context replaced after a check's last batch is observed only by a later check's first batch through the daemon. The run whose process aborts is declared on every platform. Its win32 witness (process.abort through ORACLE_GAPS_TEST_ABORT_AT, under the win32 supervisor) lands in #79; until then the Windows end-to-end job is non-blocking (C entry (c)). On win32 Node cannot deliver SIGTERM (its kill is TerminateProcess, which ends the process with no stopped line), so the stop states that name SIGTERM are required on POSIX only, and a stop there goes through the CLI's test stop hook and is observed as SIGINT; every SIGINT state stays required on win32. Argument refusals are the static oracle's; the check's rejection of a stack trace, a missing fix, and a wrong exit code is calibrated in the static oracle, through the same refusalBreach, and here only a refused run reported as complete is calibrated, because each calibration here runs real CLI histories. Hangs only as an owner test that awaits a promise that never settles, under a 1 s first budget and a 20 s full limit, and a slow run only as two witnesses whose tests wait where the output changed, 3 s in one that then judges and 10 s in two one-test owners of one that does not; busy loops only on instrumented code (cut by the call budget), no slow runs past the full limit that would end, hangs in ordinary or nondeterministic tests, setup errors other than a throw at module load, loops, multi-line conditions, two functions on one line, or await, new, and void statements; nested functions, object-literal methods, accessors, and class-field arrows only where no test calls them (their ownership is the static oracle's); two source files of one package, with no re-exports, namespace imports, or calls into another package; --only only in a stopped run and a partial run of one function's mutants, and no --sample or --diff-base; the baseline's failures only as one failing owner test that throws an error and a setup file that throws, so a baseline law violation's law and counterexample lines are the classify oracle's; a derived class's file is instrumented and its sites are judged as unowned, but no test imports or constructs the class, so its no-mutant and super-region behavior is the static oracle's (in-process), not this oracle's; package configs only as vite.config or vitest.config with one of the extensions .ts, .mts, .cts, .js, .mjs, and .cjs (not every pair), as config/gap-vitest with the same extension through --config, or none, as an object or a sync or async function, with no plugins of their own except one enforce: 'pre' transform that appends a comment to each module of the package (prePlugin); a plugin whose output depends on anything but the module's text (a sidecar file it reads) and an environment variable that changes between checks are not generated, since the runner tracks neither yet and the daemon's environment is fixed when it starts (F-A1: the maintainer decided on 2026-11-13 that the daemon tracks both and restarts when they change, in the next pull request); and test.projects only as a refusal, and only under the package's own package.json; a top-level await only in an ES module config and require only in a CommonJS one, as Vitest itself loads no other; a --config outside the package is refused by design, through the rule for paths outside the package (args.mjs), and no history generates one; contexts only one, four, or eleven, and process warnings judged only as MaxListenersExceededWarning on the CLI's own stderr (a daemon's process warnings go to its log); a context that fails to open gives back its listener allowance, which no observation shows (a kept allowance only raises the limit, so no warning follows), so that accounting is fixed by inspection; no probe-bound states, so reach agreement's killing of probe mutants is not checked; no gap answers or gate; law 9 judges the witness module's outcome classes along one constructed edit sequence only (a test edit, a helper edit, and a revert), and the budget witness's along one constructed second check with nothing changed, because a generated history with the witness module or the budget witness takes no steps (maintainer decision, 2026-11-11, and the runtime review's P1-a, 2026-11-12; this oracle owns the gap); law 9's edits come between checks, except one, midrun, which lands during a check through the daemon: a test of file a, whose context has loaded file b's helper, rewrites the helper in the baseline's first run of file a, before file b's runs read it, in one context or several; or a test of file b rewrites its own helper, or the data file that its verdict read through a sync fs read, after file b's judged tests read them, in the run that judges with the old text (review of #55, F1); that check must report, for each mutant, what a cold run of the state before the edit or of the state after it reports, and exit as one of them does (third review of #55, F-C), compared per mutant result rather than per file; when file b's own test lands the edit, b's baseline reads the old text and b's mutant runs read the new one, so b's own mutants in that check are not judged, since their results legitimately mix the two texts (maintainer decision, 2026-11-13), while every other mutant there is judged against both cold runs, with the check's exit code, its mutants' keys, and its stream; the stronger follow-up compares each run's raw outcome with the cold outcome of the state that run read; and the next check, with nothing changed, must equal a cold run of the state after the edit, compared for equality of results only, not for what the daemon reused or computed (the runner's rule: a run whose input changed after the run read it is invalidated and not stored, settleIn); a check through the daemon of a state that nothing changed must compute no run that was not cut off, judged where no test reads the clock (F-A, F-A2), and a test's fs read of a file and the module that the context serves from it are two inputs, each under its own hash (F-A2); an edit during a mutant run is not generated, and a file is edited mid-run only by the run's own tests, not by another process at an arbitrary time; a file that a test reads through fs is edited only as one JSON file that file b's verdict reads by a sync, a promise, or a callback read, or by a sync read after it stats its own directory and tests that it exists (statDir: the directory is an input as a directory, not by its content, and is not itself edited), each read first checking that its fs function keeps its own name and length (the runner stores a run under the files in the package that its copy reads with readFileSync, readFile, existsSync, or statSync, or the fs/promises readFile or stat, each with its hash at the copy's first read; a read outside the package or under node_modules, from a worker thread or a child process that a test starts, or through any other fs API, which includes readdir, opendir, glob, globSync, createReadStream, realpath, lstat, access, open, a read through a file descriptor (read, readSync, readv, fstat, fstatSync, and readFileSync or readFile given a file descriptor), copyFile and copyFileSync, cp and cpSync, openAsBlob, statfs, readlink, the callback stat, exists, watch, watchFile, and the fs/promises access, open, and glob, is no input, and none is generated: the maintainer decided on 2026-11-13 that every fs read except watch and watchFile is an input, which a follow-up of #55 implements, and until then this oracle owns the gap); a run cut off by its clock writes no closing row, so it is stored under its file's known inputs only, while a run that spun ends and keeps the inputs it named (F-D); no history makes a cut run read a file that its file's unmutated run does not read, so this is fixed by inspection; a test that rewrites a file it read with the same text makes the next check compute that run again (1 run in the self-edit histories), since the edit changes the file's modification time: the daemon is conservative there, nothing goes stale, and content keys (D10) remove it, with a selfWrite dimension in that pull request; the mid-run marker sits in the daemon's session directory, .oracle-gaps-, whose location predates #55; the runner's hash memo knows a file by its size and modification time, so an edit that keeps both is not seen, and no history makes one (D10, planned in phase 2, A5); law 9's edits leave out other environment variables, new files that change how an unchanged import resolves, Vite config and installed-package changes, and concurrent checks other than two that start the daemon; cut-off charging judged only under one budget; native addons only as a binding.gyp or a prebuilt .node file, not as optional platform packages; daemon races (two CLIs reading one error file, a CLI hearing closing from the failing daemon it started, a reset connection on macOS) fixed by inspection; the runner's copies of the test files exist only in memory, and its harness and Vitest configs sit in the package's .oracle-gaps-, which the next run removes once a killed run has left it (judged after two stopped runs, not after a SIGKILL); a default --out is judged by the static oracle, and these runs name --out in the package; the namespace is checked after each run and, in a stopped run, while the run runs; a slow kill in a later owner, after earlier owners' confirmations spent the budget, becomes a timeout (owner order; not generated); the Vitest 5 path of the copies' pragma read and of the runner is verified from Vitest 5's source only, since the Vitest 5 CI job runs no gap oracle; a batch whose run reports an error outside any test reruns each copy alone (unitsBatch, runAlone) with its first budget, and a copy cut there is kept as a timeout with no confirmation, a defect older than this oracle's budget work that no history reaches (no history has an error outside any test beside a slow copy), recorded here with that trace for the maintainer; stale-session removal is scoped to this host's session directories (a host file), and is not judged across pid namespaces; the stop law covers SIGTERM and SIGINT sent to the CLI, not a SIGKILL of the CLI (its group then ends at the next check of its parent, by inspection) or a signal sent to the daemon, and its witness is one test that spins synchronously and starts one child process; the mutant budget is witnessed as two slow owners whose confirmations pass the --mutant-limit floor, not through its multiple of the owners' unmutated time, and authored mutants have no confirmations to budget; the witness w_slowpair is a wall-clock window, since the CLI's budget has no controlled clock and a fixture cannot see the time the CLI measures for its file: with one-test owner files p and q of measured unmutated time t each (a file first in its context pays the instrumented transform too), a wait W of 10 s, a 20 s --hang-limit and a 15 s --mutant-limit, it tells a budget from none only while (a) its first attempt is cut, W > 1 s + 3t, (b) its two confirmations do not fit the budget, 2W > max(15 s, 10 x 2t), and (c) each would fit its own full limit, W < 20 s + 3t; (b) is the binding one, so it holds while the two files' time stays under about 2 s together (about 1 s each, some 20 times the authoring machine's idle and 5 to 10 times its loaded measurements), and under one budget a run's overhead must stay under 10 s + 3t; CI runners measure 1.5 to 2.3 times the idle machine; beyond that w_slowpair would read not-judged; a heartbeat is owed only where a slow test waits 3 s against a 2 s interval, twice the first budget, so that no copy cut at its first budget beats, and each beat is observed as its mutant and file, not how long or how often it beat; a config only in the package's parent directory is generated one level up, in a temporary directory with no package.json (so its .js or .ts name is CommonJS), as a plain config, one that throws, one with no default export, or one that defines test.projects; a config two or more levels up, or a parent config beside a package config, is not generated, and the order in one directory follows Vitest's configFiles list by inspection; a package with no config lives in a temporary directory, where no parent has a config; a counterexample shrinks through at most six histories, so it can be larger than the smallest that fails; module-level data only as four \`const\` declarations of the main source (an object literal, an array that holds a function, a boolean, and an object of two methods), read in place, with no data imported from another file, destructured, reassigned, or declared as an enum or a default export; the work law only through shortcut witnesses (an early return before a counting loop with a bound twin of ratio 2, and a push beside one that calls String with a bound twin of ratio 1), the early return in tests that reach the clock by each watched path and in tests that wait a turn, a generated test's bound of 1 derived from its plan (which no generated function's mutant reached in the 36 fixed-seed units at main's bases; the disarmed-pause history's base, appended at its index, does reach it, so that history pins its generated inputs to ones that declare no bound, and the model predicts no work verdict for a generated test, a model gap for the maintainer to decide whether to model work counts), and one warm-cache witness whose selection reproduces observations but not work; work is the capture's count of site evaluations per test, so code with no site (a plain assignment, a for...of pass, a builtin's own work) counts nothing and a test's histories are summed, and a test whose work varies between the unmutated runs while its observations agree is not generated. Open Limits, owned by the in-process runner oracle (L1, state \"torn tail at a cut-off read\"; RED: captureLines without the guard): (a) the batch's cut-off read (runBatch's rowsOf after the cut-off) drops a partial last row, and no witness reaches that drop yet, because a copy held half written across the cut-off did not observe its release in the harness; (b) a short fragment on the strict path, which the no-newline mutant does not reach. The strict read after a finished run (a fragment is an internal error) is witnessed by the no-newline mutant. Windows idle gap (recorded, not witnessed): the state \`a hang cut off for idleness\` is required on every platform, and win32 reaches it (run 43683794816, job 132719872988), so it is not platform-scoped. The sampler (capture-setup.mjs) counts a copy idle only after 500 ms with no late tick, no non-quiet handle, utilization at most 5%, and no timer due, so \`every outcome class\` reaches the state only when the sampler sees that window. On win32 the check missed it once (run 43683794816, job 132719872940); the cause is not confirmed (a late tick on a shared runner, or a stdio handle outside \`quiet\` for this file's console output, are the candidates). Its witness, a test-only hold at the hang until the window is seen, is owed, and that is a timing dependency the determinism-under-load rule forbids; the maintainer decides whether it lands before the Windows job becomes blocking.`, }, histories: { // A failing history shrinks through at most six smaller ones. Each runs diff --git a/packages/oracles/oracle-gaps/retention-hook.mjs b/packages/oracles/oracle-gaps/retention-hook.mjs new file mode 100644 index 00000000..97b3bccc --- /dev/null +++ b/packages/oracles/oracle-gaps/retention-hook.mjs @@ -0,0 +1,201 @@ +// The retention test hook of the gap CLI (packages/oracles/README.md, "Test +// hooks"). check.mjs imports this module only when ORACLE_GAPS_TEST_RETENTION +// or ORACLE_GAPS_TEST_REJECT_BATCH is set, so a normal run never loads it, and +// the published package does not include it (package.json `files`). +// +// The hook observes; it never changes an outcome (register: test-only hooks). +// The one exception is the rejected-batch fault, which triggers the path a +// crash in Vitest takes. Each field reads the real objects, never bookkeeping +// kept for the hook (review of #61, F6): +// - Vitest's state and Vite's module graphs, by their sizes; +// - the registry (indexOf, contextSpecs), by identity against the live +// contexts; +// - each context that left the live array, by Vitest's own close state; +// - the entries a check gave its store, by whether a full garbage collection +// leaves them reachable. +import { appendFileSync, writeFileSync } from 'node:fs' +import { join } from 'node:path' +import { setFlagsFromString } from 'node:v8' +import { runInNewContext } from 'node:vm' + +/** + * The hook for one session (check.mjs). `session.live()` returns the live + * contexts array, `session.indexOf` and `session.contextSpecs` are the + * registry. + */ +export function retentionHook(session) { + const file = process.env.ORACLE_GAPS_TEST_RETENTION + // The 1-based batch whose run rejects (unset: none). + const rejected = Number(process.env.ORACLE_GAPS_TEST_REJECT_BATCH ?? 0) + // A full collection, without --expose-gc on the command line: the flag is + // set, and `gc` is read from a fresh context, which then exposes it. + setFlagsFromString(`--expose-gc`) + const gc = runInNewContext(`gc`) + // The output directory of the check being run, and the next batch's index + // within that check. A daemon runs one check at a time (its queue). + let run + let next = 0 + // The contexts that joined the live array and have not been seen closed. + const joined = new Set() + // A weak reference to each entry a check gave its store. + let stored = [] + + // A context is closed, or closing, once Vitest's own close has started: + // Vitest sets its closing promise when close() is called. A Vitest whose + // shape has no such field throws here rather than counting it open. + const closing = (context) => { + if (!(`closingPromise` in context)) + throw new Error( + `oracle-gaps: this Vitest has no closingPromise, so the retention hook cannot see whether a context closed`, + ) + return context.closingPromise !== undefined + } + + // Every structure a copy can leave state in, unfiltered: Vitest's state + // (filesMap, pathsSet, idMap, errorsSet, leakSet) and each Vite + // environment's module graph (its four maps, and the nodes that hold a + // transform). The stale fields read the registry and the contexts that left + // the live array. + function totals(context) { + const contexts = session.live() + const { filesMap, pathsSet, idMap, errorsSet, leakSet } = context.state + const totals = { + // A registry entry is stale unless it names a live context at its own + // slot (indexOf), or a live context (contextSpecs). + staleIndexed: [...session.indexOf].filter(([c, i]) => contexts[i] !== c) + .length, + staleSpecs: [...session.contextSpecs.keys()].filter( + (c) => !contexts.includes(c), + ).length, + // A context that left the live array and that Vitest has not started to + // close. + staleOpen: [...joined].filter((c) => !contexts.includes(c) && !closing(c)) + .length, + filesMap: filesMap.size, + pathsSet: pathsSet.size, + idMap: idMap.size, + errorsSet: errorsSet.size, + leakSet: leakSet.size, + } + // A context that left and is closing is done: it is no longer watched. + for (const c of joined) + if (!contexts.includes(c) && closing(c)) joined.delete(c) + for (const [name, environment] of Object.entries( + context.getRootProject().vite?.environments ?? {}, + )) { + const graph = environment.moduleGraph + // Vite's keys are named `vite..`, so the law can tell + // them from Vitest's state. + totals[`vite.${name}.url`] = graph.urlToModuleMap.size + totals[`vite.${name}.id`] = graph.idToModuleMap.size + totals[`vite.${name}.etag`] = graph.etagToModuleMap.size + totals[`vite.${name}.file`] = graph.fileToModulesMap.size + totals[`vite.${name}.transformed`] = [ + ...graph.idToModuleMap.values(), + ].filter((node) => node.transformResult != null).length + } + return totals + } + + // Files, without their query, with more than one node in an environment's + // graph, outside the copies: a non-copy file is cached once, so each count + // must be 0 (the law's bound on originals). The one measured allowance is a + // source file's plain node and its ?raw node (the oracle reads source text + // with ?raw): one pair per file, not per batch. + function nonCopyDuplicates(context, owned) { + const dup = [] + for (const environment of Object.values( + context.getRootProject().vite?.environments ?? {}, + )) { + const perFile = new Map() + for (const node of environment.moduleGraph.idToModuleMap.values()) { + const path = node.id.split(`?`)[0] + if (owned.has(path)) continue + perFile.set(path, [...(perFile.get(path) ?? []), node.id]) + } + for (const [path, ids] of perFile) + if ( + ids.length > 1 && + !( + ids.length === 2 && + ids.includes(path) && + ids.includes(`${path}?raw`) + ) + ) + dup.push(`${environment.name ?? `env`} ${path}`) + } + return dup + } + + // The entries the store was given that a full collection leaves reachable. + // The collection runs after a macrotask turn: a weak reference keeps its + // target alive until the turn that created or read it ends. + async function held() { + await new Promise((resolvePromise) => setImmediate(resolvePromise)) + gc() + stored = stored.filter((ref) => ref.deref() !== undefined) + return stored.length + } + + return { + // A check starts: its batches are counted from 0, and the process that + // runs it is named in its output directory (the driver reads check.pid). + check(out) { + run = out + next = 0 + if (file) writeFileSync(join(out, `check.pid`), String(process.pid)) + }, + // A context joined the live array. + joined(context) { + joined.add(context) + }, + // An entry a check gave its store. + stored(entry) { + stored.push(new WeakRef(entry)) + }, + // A batch starts: its own index, and the totals before it. + begin(context) { + return { index: next++, before: file ? totals(context) : undefined } + }, + // The rejected-batch fault: the batch's run completes, so its copies are + // in Vitest's and Vite's state, and then rejects, as a crash in Vitest + // would. Any other batch's run is returned unchanged. + fault(batch, running) { + return batch.index + 1 === rejected + ? running.then(() => { + throw new Error( + `oracle-gaps test fault: batch ${batch.index + 1} rejected`, + ) + }) + : running + }, + // A batch ended (settled, cut, or rejected): its one line. A cut batch is + // not retired (its context is replaced), so its line has no after. + async line(context, batch, copies, cut) { + if (!file) return + const owned = new Set(copies) + let copyNodes = 0 + for (const environment of Object.values( + context.getRootProject().vite?.environments ?? {}, + )) + for (const copy of owned) + copyNodes += + environment.moduleGraph.fileToModulesMap.get(copy)?.size ?? 0 + const line = { + run, + pid: process.pid, + batch: batch.index, + before: batch.before, + ...(cut + ? { cut: true } + : { + after: totals(context), + copyNodes, + nonCopyDup: nonCopyDuplicates(context, owned).length, + }), + held: await held(), + } + appendFileSync(file, `${JSON.stringify(line)}\n`) + }, + } +} diff --git a/packages/oracles/package.json b/packages/oracles/package.json index 2301c07d..2cabebf4 100644 --- a/packages/oracles/package.json +++ b/packages/oracles/package.json @@ -53,6 +53,7 @@ "oracle-gaps", "!oracle-gaps/**/*.property.test.mjs", "!oracle-gaps/gap-report-model-oracle.mjs", + "!oracle-gaps/retention-hook.mjs", "!oracle-gaps/vitest.config.mjs", "!oracle-gaps/node_modules/**", "!oracle-gaps/.scratch-*", From 34929a9b6973d22c6dabb2a4377eedce0644560c Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sun, 15 Nov 2026 19:40:46 -0600 Subject: [PATCH 58/61] test(oracle-gaps): law 9's first cold run keeps its retention lines and check pid Co-authored-by: Isaac --- .../oracle-gaps/gap-report-oracle.property.test.mjs | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index a92ce6a6..8661f542 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -2643,7 +2643,16 @@ async function driver(plan, observe) { states.add(`stability rerun`) } if (plan.steps.length > 0) - await incremental(dir, plan, cli, copy, observe, states) + // The first cold run keeps its retention lines and check pid: law 9's + // cold result of the first state is this run (incremental). + await incremental( + dir, + plan, + { ...cli, retention, checkPid }, + copy, + observe, + states, + ) for (const state of states) observe(`reach`, state) } finally { if (copy) rmSync(copy, { recursive: true, force: true }) From 85fd038bcbd0cc8a0327cd341496a52a0638b6f0 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sun, 15 Nov 2026 20:14:41 -0600 Subject: [PATCH 59/61] test(oracle-gaps): the killed daemon's retention lines are a declared reach state Co-authored-by: Isaac --- .../oracles/oracle-gaps/gap-report-oracle.property.test.mjs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 8661f542..9bb2f406 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1930,6 +1930,8 @@ async function incremental(dir, plan, cli, copy, observe, states) { const runs = await running // The daemon the driver killed, once it is dead: its lines are its own. if (killed && !isAlive(pid)) runs[0].killed = pid + if (runs[0].retention.some((line) => line.pid === runs[0].killed)) + states.add(`a killed daemon's retention lines were judged as its own`) rmSync(marks, { recursive: true, force: true }) // Each label needs its pause's observation: a kill the driver sent and saw // through (gone), and the CLI's report of the check. A label without a pause @@ -3847,6 +3849,8 @@ const incrementalStates = [ .map((edit) => `edit ${edit} changed the cold result`), `a check whose daemon died during it`, `a check whose daemon held it past the CLI's wait, then died`, + // The retention law's second writer: lines of a daemon the driver killed. + `a killed daemon's retention lines were judged as its own`, `a warm daemon's connection was reset`, `a check whose connection was reset`, `a check after a daemon crash`, From ff5c0218506c7127c6efae0dc7d5c72d61e9d0fc Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sun, 15 Nov 2026 21:33:24 -0600 Subject: [PATCH 60/61] test(oracle-gaps): a stopped run's retention lines are the ones it appended Every stop of a history writes under out-stop, so an earlier stop's lines named the same run and a pid other than this stop's check (found by the shared-index mutant's run of "every outcome class"). Co-authored-by: Isaac --- .../oracle-gaps/gap-report-oracle.property.test.mjs | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 9bb2f406..f12f394f 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -874,7 +874,10 @@ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { pool: abort ? `threads` : pool, }) // The retention hook is set on every stop, so a stopped run's completed batches are judged too. + // Every stop of a history writes under out-stop, so this run's lines are the ones appended after + // the lines already in the file. const hook = hookOf(dir) + const earlierLines = retentionLinesOf(hook).length const base = { ...cleanEnv(), ORACLE_GAPS_TEST_RETENTION: hook } const env = after ? { ...base, ORACLE_GAPS_TEST_HOLD_EXIT_MS: `500` } @@ -976,9 +979,9 @@ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { strayWhileRunning, when: when ?? `run`, // The batches this run completed, each with its retention line (the hook above). - retention: retentionLinesOf(hook).filter( - (line) => line.run === join(dir, `out-stop`), - ), + retention: retentionLinesOf(hook) + .slice(earlierLines) + .filter((line) => line.run === join(dir, `out-stop`)), checkPid: checkPidOf(join(dir, `out-stop`)), // Whether a refusal's block reached stderr: a stop is never a refusal. refused: stderr.split(`\n`).some((line) => line.startsWith(`refused: `)), From 1f67a4b16d11ac41bf59f87204cd143f50da026f Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sun, 15 Nov 2026 23:32:56 -0600 Subject: [PATCH 61/61] fix(oracle-gaps): the retention hook ships, so the CLI cites only files its package ships check.mjs imports retention-hook.mjs when a hook variable is set, and a shipped file may cite only what its package ships (eslint-plugin shipped-citations, maintainer finding F16). The CLI still loads the module only when a hook variable is set. Co-authored-by: Isaac --- packages/oracles/README.md | 2 +- packages/oracles/oracle-gaps/retention-hook.mjs | 7 +++---- packages/oracles/package.json | 1 - 3 files changed, 4 insertions(+), 6 deletions(-) diff --git a/packages/oracles/README.md b/packages/oracles/README.md index b3fc2269..d5fac0f3 100644 --- a/packages/oracles/README.md +++ b/packages/oracles/README.md @@ -17,7 +17,7 @@ Show me what oracle testing with @tanstack/oracles can find in this repository. ## Test hooks -`ORACLE_GAPS_TEST_RETENTION` (a file path, unset in normal use) makes the gap CLI append one JSON line per mutant batch it runs, however the batch ends: settled, cut off, or rejected. It only observes: it never changes an outcome. The e2e oracle reads it to check bounded retention. The hook's code is in `oracle-gaps/retention-hook.mjs`, which the CLI loads only when this variable or `ORACLE_GAPS_TEST_REJECT_BATCH` is set. The published package does not include that file, so the hooks work only from this repository's source. +`ORACLE_GAPS_TEST_RETENTION` (a file path, unset in normal use) makes the gap CLI append one JSON line per mutant batch it runs, however the batch ends: settled, cut off, or rejected. It only observes: it never changes an outcome. The e2e oracle reads it to check bounded retention. The hook's code is in `oracle-gaps/retention-hook.mjs`, which the CLI loads only when this variable or `ORACLE_GAPS_TEST_REJECT_BATCH` is set, so a normal run never loads it. Under the hook, each check also writes `check.pid` (the id of the process that runs the check: the CLI's supervised child, or a daemon) into its `--out` directory, after the CLI creates that directory. Each line has: diff --git a/packages/oracles/oracle-gaps/retention-hook.mjs b/packages/oracles/oracle-gaps/retention-hook.mjs index 97b3bccc..0061e63d 100644 --- a/packages/oracles/oracle-gaps/retention-hook.mjs +++ b/packages/oracles/oracle-gaps/retention-hook.mjs @@ -1,7 +1,6 @@ -// The retention test hook of the gap CLI (packages/oracles/README.md, "Test -// hooks"). check.mjs imports this module only when ORACLE_GAPS_TEST_RETENTION -// or ORACLE_GAPS_TEST_REJECT_BATCH is set, so a normal run never loads it, and -// the published package does not include it (package.json `files`). +// The retention test hook of the gap CLI (the package README, "Test hooks"). +// check.mjs imports this module only when ORACLE_GAPS_TEST_RETENTION or +// ORACLE_GAPS_TEST_REJECT_BATCH is set, so a normal run never loads it. // // The hook observes; it never changes an outcome (register: test-only hooks). // The one exception is the rejected-batch fault, which triggers the path a diff --git a/packages/oracles/package.json b/packages/oracles/package.json index 2cabebf4..2301c07d 100644 --- a/packages/oracles/package.json +++ b/packages/oracles/package.json @@ -53,7 +53,6 @@ "oracle-gaps", "!oracle-gaps/**/*.property.test.mjs", "!oracle-gaps/gap-report-model-oracle.mjs", - "!oracle-gaps/retention-hook.mjs", "!oracle-gaps/vitest.config.mjs", "!oracle-gaps/node_modules/**", "!oracle-gaps/.scratch-*",