From b0c6074b43bab60bf5c6b526b692b0e1d572d9e7 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Mon, 16 Nov 2026 14:10:32 +0000 Subject: [PATCH 01/34] test(oracle-gaps): every read is a daemon input, oracle first Law 9 (incremental equals cold, v21.1 I8) now draws a gate input that file b's verdict reads, and an edit that flips only that input between daemon checks (maintainer decision, 2026-11-16, "Every read is a daemon input"): a file in the package, outside it, or under node_modules, the variable GAP_INPUT_GATE, or a file the config's own plugin reads when the config resolves or in each transform. A gate file's edit may keep its size and modification time (keepStamp, D10). The fields are appended last and drawn ("Randomness wins"); one constructed history per kind is appended at the end of the list, and the fixed-seed CI job gets a fourth shard for them. Co-authored-by: Isaac --- .github/workflows/pr.yml | 6 +- .../oracle-gaps/gap-report-model-oracle.mjs | 207 +++++++++++++++++- .../gap-report-oracle.property.test.mjs | 152 ++++++++++++- ...gap-report-static-oracle.property.test.mjs | 3 + .../oracle-gaps/history-fingerprint.json | 10 +- packages/oracles/scripts/pr-shards.mjs | 20 ++ 6 files changed, 376 insertions(+), 22 deletions(-) diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml index edf59139..cd5b6e2c 100644 --- a/.github/workflows/pr.yml +++ b/.github/workflows/pr.yml @@ -106,12 +106,12 @@ jobs: env: SHARD: ${{ matrix.shard }} test-oracle-gaps-end-to-end: - name: Gap report end-to-end oracle (fixed seed, ${{ matrix.shard }}/3) + name: Gap report end-to-end oracle (fixed seed, ${{ matrix.shard }}/4) runs-on: ubuntu-latest strategy: fail-fast: false matrix: - shard: [1, 2, 3] + shard: [1, 2, 3, 4] steps: - name: Checkout uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 @@ -119,7 +119,7 @@ jobs: persist-credentials: false - name: Setup Tools uses: tanstack/config/.github/setup@e4b48f16568324f76f467aa4c2aac2f05db632c3 - # The end-to-end oracle's fixed-seed units, in three shards. Its random + # The end-to-end oracle's fixed-seed units, in four shards. Its random # units, calibrations, and determinism units run locally. - run: pnpm exec vitest --run --config oracle-gaps/vitest.config.mjs gap-report-oracle -t "$(node scripts/pr-shards.mjs pattern oracle-gaps-fixed-seed "$SHARD")" working-directory: packages/oracles diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index 6dbe5bd5..b1dd9770 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -13,6 +13,7 @@ import { rmSync, symlinkSync, unlinkSync, + utimesSync, writeFileSync, } from 'node:fs' import { createRequire } from 'node:module' @@ -488,6 +489,11 @@ const edits = [ // `laterSteps` (the generator rule: new draws go last). const laterEdits = [`fsData`, `midrun`] const earlierEdits = edits.filter((edit) => !laterEdits.includes(edit)) +// The edit of the gate input that file b's verdict reads (`inputRead`), +// which flips it between `open` and `shut`. It is drawn in its own field +// (`inputSteps`), after `laterSteps`, so the fields before it draw as they +// did (the generator rule: new draws go last). +const inputEdits = [`inputGate`] // A history's no later edits, one value, so `histories` can take it back // (fc.constant takes back only its own reference). const NO_LATER_STEPS = Object.freeze([]) @@ -497,6 +503,12 @@ const laterStepsOf = (history) => history.witness === false && history.steps != null ? (history.laterSteps ?? []) : [] +// The input edits a history takes after its later edits, by the same rule. +const NO_INPUT_STEPS = Object.freeze([]) +const inputStepsOf = (history) => + history.witness === false && history.steps != null + ? (history.inputSteps ?? []) + : [] // The steps that act on the daemon and change no file. const daemonEvents = new Set([ `restart`, @@ -860,6 +872,46 @@ const drawn = fc.record({ // 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; the take-back below returns it to 0 (the generator rule, extended). rejectBatch: fc.constant(0), + // Every read is a daemon input (maintainer decision, 2026-11-16, "All of + // them"): a file a test reads through fs on any path, node_modules + // included; an environment variable a test reads; and what the config's + // own plugin reads. File b's verdicts also wait on one such gate input, + // which the `inputGate` edit flips between `open` and `shut` (law 9). The + // gate is a JSON file that the test reads with a sync read: in the + // package's tests (`inside`), beside the package and outside it + // (`outside`), or in a package under its node_modules (`module`); or the + // variable GAP_INPUT_GATE (`env`); or a file the config's own plugin + // reads, once when the config resolves (`pluginConfig`) or each time it + // transforms a test file (`pluginTransform`), and writes into the test's + // text. These fields change what a history runs, so they are drawn + // (maintainer decision, 2026-11-16, "Randomness wins"), and last. + inputRead: fc.constantFrom( + `none`, + `none`, + `none`, + `inside`, + `outside`, + `module`, + `env`, + `pluginConfig`, + `pluginTransform`, + ), + // Each write of a gate file keeps its size (`open` and `shut` have one + // length) and gets back one fixed modification time, as `cp -p`, `rsync + // -t`, or `touch -r` leave a file: a cache keyed by size and time cannot + // tell the two texts apart (D10; the TLA model's weakened-stamp run). + keepStamp: fc.constantFrom(false, false, false, true), + // The input edits, which follow a history's steps and later edits. + inputSteps: fc.oneof( + { weight: 3, arbitrary: fc.constant(NO_INPUT_STEPS) }, + { + weight: 1, + arbitrary: fc.array(fc.constantFrom(...inputEdits), { + minLength: 1, + maxLength: 2, + }), + }, + ), }) // The edit sequence over the witness module, the one list of steps that a @@ -926,21 +978,28 @@ const histories = drawn.map( const later = (history.steps ?? []).filter((step) => laterEdits.includes(step), ) - if (later.length === 0) + // An input edit in `steps` moves to `inputSteps` in the same way. + const inputs = (history.steps ?? []).filter((step) => + inputEdits.includes(step), + ) + if (later.length === 0 && inputs.length === 0) return { ...taken, pauseEngages: true, warmReplaced: false, rejectBatch: 0, } - const earlier = history.steps.filter((step) => !laterEdits.includes(step)) + const earlier = history.steps.filter( + (step) => !laterEdits.includes(step) && !inputEdits.includes(step), + ) return { ...taken, pauseEngages: true, warmReplaced: false, rejectBatch: 0, steps: earlier.length > 0 ? earlier : null, - laterSteps: later, + ...(later.length > 0 ? { laterSteps: later } : {}), + ...(inputs.length > 0 ? { inputSteps: inputs } : {}), } }, ) @@ -2944,11 +3003,25 @@ function resolveHistory(history) { template: history.template, fault: history.fault, stability: history.stability, - steps: [...(history.steps ?? []), ...laterStepsOf(history)], + steps: [ + ...(history.steps ?? []), + ...laterStepsOf(history), + ...inputStepsOf(history), + ], pauseEngages: history.pauseEngages !== false, warmReplaced: history.warmReplaced === true, lazyGate: history.lazyGate === true, fsRead: history.fsRead ?? `none`, + // The gate input that file b's verdicts also wait on (`inputRead`), and + // whether each write of a gate file keeps its size and modification time + // (`keepStamp`). + // A plugin's gate needs a config to hold the plugin: with none, file b + // reads no gate. + inputRead: + pluginGated(history) && configOf(history).configPath === undefined + ? `none` + : (history.inputRead ?? `none`), + keepStamp: history.keepStamp === true, // Whether a step edits file b's helper during a check (`midrun`): then // file a loads the helper and holds the test that edits it. midrun: [...(history.steps ?? []), ...laterStepsOf(history)].includes( @@ -4695,6 +4768,77 @@ const dataReads = { ], } +// The gate input of file b's verdicts (`inputRead`): the variable that +// `env` reads, and the file each other kind reads. A gate file holds +// `open` or `shut`, two words of one length, so an edit keeps its size. +const INPUT_GATE_VAR = `GAP_INPUT_GATE` +const gateText = (open) => + `${JSON.stringify({ gate: open ? `open` : `shut` })}\n` +// The modification time, in seconds, that every write of a gate file gets +// back under `keepStamp`. +const GATE_STAMP = 1_700_000_000 +// A fixture path under the directory beside the package (`outsideOf`), +// which is outside it; writeFixture places it there. +const BESIDE = `/` +/** The directory beside the package `dir` that holds its outside files. */ +const outsideOf = (dir) => `${dir}.outside` +const gateFiles = { + inside: `tests/gate.json`, + outside: `${BESIDE}gate.json`, + module: `node_modules/gap-gate/gate.json`, + pluginConfig: `tests/plugin-gate.json`, + pluginTransform: `tests/plugin-gate.json`, +} +/** Whether the gate input is one that the config's own plugin reads. */ +const pluginGated = (history) => + history.inputRead === `pluginConfig` || + history.inputRead === `pluginTransform` +// Whether a test's verdict waits on the gate input. +const inputGated = (plan, file, t) => + plan.inputRead !== `none` && + file === `b` && + t.judges && + t.judgeBy === `verdict` +// How file b reads its gate input, by each kind (`inputRead`). The outside +// file lies in the directory beside the package, named by the package's +// own directory with `.outside` after it. The plugin kinds read the text +// that the config's plugin wrote in place of `__GAP_INPUT_GATE__`. +const readGateFile = (path) => + `const readInput = async () => ({ open: JSON.parse(readGate(${path}, 'utf8')).gate === 'open' })` +const inputReads = { + inside: [ + `import { readFileSync as readGate } from 'node:fs'`, + readGateFile(`new URL('./gate.json', import.meta.url)`), + ], + outside: [ + `import { readFileSync as readGate } from 'node:fs'`, + `import { fileURLToPath as gatePackage } from 'node:url'`, + readGateFile( + `gatePackage(new URL('..', import.meta.url)).replace(/[\\\\/]+$/, '') + '.outside/gate.json'`, + ), + ], + module: [ + `import { readFileSync as readGate } from 'node:fs'`, + readGateFile( + `new URL('../node_modules/gap-gate/gate.json', import.meta.url)`, + ), + ], + env: [ + `const readInput = async () => ({ open: process.env.${INPUT_GATE_VAR} !== 'shut' })`, + ], + pluginConfig: [ + `const readInput = async () => ({ open: __GAP_INPUT_GATE__ === 'open' })`, + ], + pluginTransform: [ + `const readInput = async () => ({ open: __GAP_INPUT_GATE__ === 'open' })`, + ], +} +/** The variables a check of `state` runs with: the gate's, under `env`. */ +const inputEnv = (plan, state) => + plan.inputRead === `env` + ? { [INPUT_GATE_VAR]: state.inputOpen ? `open` : `shut` } + : {} + function oracleTestFile(plan, file) { const sites = sitesOf(plan) const entries = [ @@ -4792,6 +4936,9 @@ function oracleTestFile(plan, file) { `import * as sut from '../src/sut'`, ...(file === `b` ? [`import { strict } from './strict'`] : []), ...(file === `b` && plan.fsRead !== `none` ? dataReads[plan.fsRead] : []), + ...(file === `b` && plan.inputRead !== `none` + ? inputReads[plan.inputRead] + : []), ...stubs, // State that tests of this file share (the `w_shared` witness). `const shared = { value: 0 }`, @@ -4950,7 +5097,7 @@ function oracleTestFile(plan, file) { // A lazy gate is imported only where the output differs, so // the unmutated run never loads it. It is open before any // edit, so the model need not read it. - ` if (${when} && JSON.stringify(${out}) !== ${JSON.stringify(expected)}${lazyGated(plan, file, t) ? ` && (await import('./lazy')).open` : ``}${fsGated(plan, file, t) ? ` && (await readData()).open` : ``}) {`, + ` if (${when} && JSON.stringify(${out}) !== ${JSON.stringify(expected)}${lazyGated(plan, file, t) ? ` && (await import('./lazy')).open` : ``}${fsGated(plan, file, t) ? ` && (await readData()).open` : ``}${inputGated(plan, file, t) ? ` && (await readInput()).open` : ``}) {`, ` g.__oracleVerdict?.({ property: 'fixture-${file}', law: '${t.law}', checkpoint: 'trace' })`, ` throw new Error('violation')`, ` }`, @@ -4968,7 +5115,7 @@ function oracleTestFile(plan, file) { : []), t.asProp ? ` fcTest.prop([fcv.integer({ min: 0, max: 10 })], { numRuns: 20, seed: 1 })('${testName(t, index)}', async (n) => {` - : ` test('${testName(t, index)}', ${(t.hangs && !t.flaky) || t.slow || t.ioWait || t.timed || lazyGated(plan, file, t) || fsGated(plan, file, t) ? `async ` : ``}() => {`, + : ` test('${testName(t, index)}', ${(t.hangs && !t.flaky) || t.slow || t.ioWait || t.timed || lazyGated(plan, file, t) || fsGated(plan, file, t) || inputGated(plan, file, t) ? `async ` : ``}() => {`, ...partsOf(t).flatMap(campaign), ` })`, `})`, @@ -5192,6 +5339,8 @@ const initialState = (plan) => ({ lazyOpen: true, // What `tests/data.json` holds: whether file b's data gate is open. dataOpen: true, + // Whether file b's gate input reads `open` (`inputRead`). + inputOpen: true, // How many mid-run edits have landed (`midrun`). midruns: 0, seed: 1, @@ -5222,6 +5371,16 @@ const PRE_PLUGIN = `{ name: 'gap-pre-rewrite', enforce: 'pre', transform(code, i // memory, so only the runner's own \`load\` can answer for it (review of #103). const LOAD_PLUGIN = `{ name: 'gap-own-load', load(id) { const path = id.split('?')[0]; return path.endsWith('.test.ts') ? readFileSync(path, 'utf8') : undefined } }` +// The config's own plugin that reads the gate file (`inputRead` +// `pluginConfig` or `pluginTransform`) and writes its word in place of +// `__GAP_INPUT_GATE__` in each test file it transforms. It finds the file +// under the root Vite resolved, so it reads the package's file wherever the +// config lies. `pluginConfig` reads it once, when the config resolves; +// `pluginTransform` reads it in each transform. +const GATE_READ = `JSON.parse(readGate(root + '/tests/plugin-gate.json', 'utf8')).gate` +const gatePlugin = (plan) => + `(() => { let root; let gate; return { name: 'gap-input-gate', configResolved(resolved) { root = resolved.root${plan.inputRead === `pluginConfig` ? `; gate = ${GATE_READ}` : ``} }, transform(code, id) { return id.split('?')[0].endsWith('.test.ts') ? code.replaceAll('__GAP_INPUT_GATE__', JSON.stringify(${plan.inputRead === `pluginConfig` ? `gate` : GATE_READ})) : undefined } } })()` + /** * The text of the package's config, in its syntax (`configOf`), with the * fault, the top-level await, or the `require` calls the plan holds. `test` @@ -5232,6 +5391,7 @@ function configText(plan, test) { const plugins = [ ...(plan.prePlugin ? [PRE_PLUGIN] : []), ...(plan.loadPlugin ? [LOAD_PLUGIN] : []), + ...(pluginGated(plan) ? [gatePlugin(plan)] : []), ] const config = `defineConfig(${ { object: ``, function: `() => (`, async: `async () => (`, promise: `` }[ @@ -5260,6 +5420,13 @@ function configText(plan, test) { : [`import { fileURLToPath } from 'node:url'`]), // Only an ES module config has the load plugin (its constructed history). ...(plan.loadPlugin ? [`import { readFileSync } from 'node:fs'`] : []), + ...(pluginGated(plan) + ? [ + commonjs + ? `const { readFileSync: readGate } = require('node:fs')` + : `import { readFileSync as readGate } from 'node:fs'`, + ] + : []), ...(plan.fault === `configThrows` ? [`throw new Error('the fixture config broke')`] : []), @@ -5467,6 +5634,15 @@ function fixtureFiles(plan, state = initialState(plan)) { ...(plan.fsRead !== `none` ? { 'tests/data.json': `${JSON.stringify({ open: state.dataOpen })}\n` } : {}), + // The gate file, which under `keepStamp` gets back one modification + // time each time it is written. + ...(gateFiles[plan.inputRead] === undefined + ? {} + : { + [gateFiles[plan.inputRead]]: plan.keepStamp + ? { text: gateText(state.inputOpen), mtime: GATE_STAMP } + : gateText(state.inputOpen), + }), // A workspace dependency with module state, linked through node_modules. 'deps/state-dep/package.json': manifest({ name: `state-dep`, @@ -5661,6 +5837,11 @@ function removePath(path) { // The paths each fixture directory holds, so a state that lacks a file of // the state before it removes that file. const written = new Map() +// Where a fixture path lies: in the package, or beside it (`BESIDE`). +const placeOf = (dir, path) => + path.startsWith(BESIDE) + ? join(outsideOf(dir), path.slice(BESIDE.length)) + : join(dir, path) function writeFixture(dir, files) { for (const sub of [ `src`, @@ -5674,14 +5855,17 @@ function writeFixture(dir, files) { if (!existsSync(join(dir, `node_modules/state-dep`))) symlinkSync(`../deps/state-dep`, join(dir, `node_modules/state-dep`), `dir`) for (const path of written.get(dir) ?? []) - if (!(path in files)) removePath(join(dir, path)) - for (const [path, text] of Object.entries(files)) { - const at = join(dir, path) + if (!(path in files)) removePath(placeOf(dir, path)) + for (const [path, value] of Object.entries(files)) { + const at = placeOf(dir, path) mkdirSync(dirname(at), { recursive: true }) + // A file may name the modification time it gets back (`keepStamp`). + const text = typeof value?.text === `string` ? value.text : value // An unchanged file keeps its modification time, as in a real package. if (typeof text === `string`) { if (!existsSync(at) || readFileSync(at, `utf8`) !== text) writeFileSync(at, text) + if (value.mtime !== undefined) utimesSync(at, value.mtime, value.mtime) } else if (linkTarget(at) !== text.link) { // A link that a later state points elsewhere is replaced. removePath(at) @@ -5758,6 +5942,7 @@ function applyEdit(state, edit) { : { ...state, strict: !state.strict, midruns: state.midruns + 1 } if (edit === `lazy`) return { ...state, lazyOpen: !state.lazyOpen } if (edit === `fsData`) return { ...state, dataOpen: !state.dataOpen } + if (edit === `inputGate`) return { ...state, inputOpen: !state.inputOpen } if (edit === `seed`) return { ...state, seed: state.seed === 1 ? 2 : 1 } if (edit === `config`) return { ...state, altConfig: !state.altConfig } // A seed no other step uses, so the check has fresh work to be killed in. @@ -5978,6 +6163,10 @@ function readSummary(summary) { export { drawn, NO_LATER_STEPS, + NO_INPUT_STEPS, + inputEdits, + inputEnv, + outsideOf, MIDRUN_EDITORS, captureWitness, outsideRepository, 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 fa15adc6..5259ce95 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -431,8 +431,12 @@ * the check it overlaps must report, for each mutant, what a cold run of * the state before or after the edit reports, and the runner must store no * run under a text it did not read (see the limits). An edit can change a - * file that a test reads through `fs` (`fsData`). Law 9's edits do not - * include an environment variable other than the seed, a new file that changes how an + * file that a test reads through `fs` (`fsData`), and the gate input that + * file b's verdict reads (`inputGate`): a file in the package, outside it, + * or under node_modules, the variable GAP_INPUT_GATE, or a file the config's + * own plugin reads, since every read is a daemon input (maintainer decision, + * 2026-11-16). Law 9's edits do not include another environment variable + * than the seed and the gate's, a new file that changes how an * unchanged import resolves, a change to the Vite config or the installed * packages, or checks at once other than the two that start the daemon. * The harness keeps every global a copy defines configurable, by wrapping @@ -550,6 +554,9 @@ import { HEARTBEAT_MS, FULL_LIMIT_MS, NO_LATER_STEPS, + NO_INPUT_STEPS, + inputEnv, + outsideOf, } from './gap-report-model-oracle.mjs' const here = dirname(fileURLToPath(import.meta.url)) @@ -1562,6 +1569,8 @@ async function incremental(dir, plan, cli, copy, observe, states) { ...configArgs(plan), // After the `config` edit, `--config` names the second config. ...(state.altConfig ? { config: altConfigPath(plan) } : {}), + // The gate variable of this state, when file b's verdicts read one. + env: inputEnv(plan, state), } // The first check may be two at once, which must reach one daemon, and // so are the two after a crash. @@ -1765,6 +1774,17 @@ async function incremental(dir, plan, cli, copy, observe, states) { states.add( `an edit to data read through ${plan.fsRead} changed the cold result`, ) + // An edit of only the gate input that file b's verdicts read, by each + // kind, and one that kept the gate file's size and modification time. + if (step === `inputGate`) { + states.add( + `an edit to the ${plan.inputRead} gate input changed the cold result`, + ) + if (plan.keepStamp && plan.inputRead !== `env`) + states.add( + `an edit that kept a file's size and modification time changed the cold result`, + ) + } // The daemon's previous check cut a run off, so the only context, which // ran every file, was replaced. Whether the replacement read the edited // file again is not observed; the constructed history's order makes it @@ -1896,7 +1916,12 @@ async function incremental(dir, plan, cli, copy, observe, states) { let warm if (!mid) { const [warmRun] = await runClisAtOnce(dir, files, [ - { ...how, daemon: true, outName: `out-warm`, env }, + { + ...how, + daemon: true, + outName: `out-warm`, + env: { ...how.env, ...env }, + }, ]) observe( `retention:warm`, @@ -1913,7 +1938,9 @@ async function incremental(dir, plan, cli, copy, observe, states) { writeFileSync(armMark, ``) } let finished = false - const running = runClisAtOnce(dir, files, [{ ...how, daemon: true, env }]) + const running = runClisAtOnce(dir, files, [ + { ...how, daemon: true, env: { ...how.env, ...env } }, + ]) running.then(() => { finished = true }) @@ -2101,9 +2128,12 @@ async function driver(plan, observe) { budget: plan.budget, cli: plan.cliPath === `spaced` ? copy : here, ...configArgs(plan), - ...(plan.rejectBatch > 0 - ? { env: { ORACLE_GAPS_TEST_REJECT_BATCH: String(plan.rejectBatch) } } - : {}), + env: { + ...inputEnv(plan, initialState(plan)), + ...(plan.rejectBatch > 0 + ? { ORACLE_GAPS_TEST_REJECT_BATCH: String(plan.rejectBatch) } + : {}), + }, } const { replay, retention, checkPid, ...cli } = runCli( dir, @@ -2686,6 +2716,7 @@ async function driver(plan, observe) { } finally { if (copy) rmSync(copy, { recursive: true, force: true }) removePath(`${dir}.link`) + rmSync(outsideOf(dir), { recursive: true, force: true }) written.delete(dir) dropHook(dir) try { @@ -4144,6 +4175,15 @@ const incrementalStates = [ `two checks started the daemon at once`, `the daemon ran from a path with a space and #`, ] +// The kinds of gate input that file b's verdicts may read (`inputRead`). +const inputKinds = [ + `inside`, + `outside`, + `module`, + `env`, + `pluginConfig`, + `pluginTransform`, +] // Law 9's states that a constructed history of their own reaches, not the // edit sequence: the mid-run edit, and an edit to data a test reads through // fs, by each read. @@ -4161,6 +4201,14 @@ const ownedIncrementalStates = [ `an edit to data read through promise changed the cold result`, `an edit to data read through callback changed the cold result`, `an edit to data read through statDir changed the cold result`, + // Every read is a daemon input (maintainer decision, 2026-11-16): an edit + // of only the gate input that file b's verdicts read, by each kind, and an + // edit that kept the gate file's size and modification time (D10). + ...inputKinds.map( + (kind) => `an edit to the ${kind} gate input changed the cold result`, + ), + `edit inputGate changed the cold result`, + `an edit that kept a file's size and modification time changed the cold result`, ] // The static states (probe structure and ownership through the reference // tree) are gap-report-static-oracle's: it reaches each in every campaign, @@ -4524,7 +4572,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. 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. Law 15's stdout gap lines are judged against each completed run's own results.json, by id: the cold run, and each check through the daemon (every step's check and the check that a mid-run edit overlaps); a stopped run and a refusal list no gaps and are not judged so. A line's change is read loosely: its code on one line, whole or cut after a kept part and ended with \`...\`; where the printer cuts (60 code points, kept 57) is the classify oracle's law 8 (\`shortened\`), in-process. A line with any text after its change does not read and fails loudly: the \` (cause: )\` suffix that #99 adds to timeout lines is not read yet, so whichever of #99 and #115 lands second extends readGapLine. 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) and, in one constructed history, a plugin whose load reads each test file with a sync read (loadPlugin); 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 config's test.root only in four shapes, each in one constructed history of an ES module config that Vitest discovers, with one owner and one context, where the test files' globs and the setup file are relative to the root (issue #101): the directory that holds the tests, the directory above the package, a directory of the package that holds no test file, and the package's tests as a symbolic link to the directory that holds them (required on every platform, since Windows creates the link as the driver's other links); not under --config, a CommonJS config, test.projects, several contexts with different roots, or a root that is the filesystem's root; the runner serves each copy of a test file by its absolute path, through its pre plugin's load (which answers before the config's own plugins) and through its read of the copy's path for Vitest's pragma read (serveCopies), and histories run copies only in Vite's server environments (node and the pragma's ssr environment): jsdom and happy-dom, Vite's client environment, are not generated (the #103 merge-gate review ran jsdom by hand under all five root shapes, and the copies loaded in each); 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. Law 15's stdout gap lines are judged against each completed run's own results.json, by id: the cold run, and each check through the daemon (every step's check and the check that a mid-run edit overlaps); a stopped run and a refusal list no gaps and are not judged so. A line's change is read loosely: its code on one line, whole or cut after a kept part and ended with \`...\`; where the printer cuts (60 code points, kept 57) is the classify oracle's law 8 (\`shortened\`), in-process. A line with any text after its change does not read and fails loudly: the \` (cause: )\` suffix that #99 adds to timeout lines is not read yet, so whichever of #99 and #115 lands second extends readGapLine. 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) and, in one constructed history, a plugin whose load reads each test file with a sync read (loadPlugin); and the gate plugin (inputRead pluginConfig or pluginTransform), which reads a sidecar file of the package once when the config resolves or in each transform of a test file, and writes its word into the test's text (maintainer decision, 2026-11-16, "Every read is a daemon input": every plugin input is a daemon input); a plugin that reads an environment variable, enumerates the environment, or reads through another fs API than the six below is not generated; and test.projects only as a refusal, and only under the package's own package.json; a config's test.root only in four shapes, each in one constructed history of an ES module config that Vitest discovers, with one owner and one context, where the test files' globs and the setup file are relative to the root (issue #101): the directory that holds the tests, the directory above the package, a directory of the package that holds no test file, and the package's tests as a symbolic link to the directory that holds them (required on every platform, since Windows creates the link as the driver's other links); not under --config, a CommonJS config, test.projects, several contexts with different roots, or a root that is the filesystem's root; the runner serves each copy of a test file by its absolute path, through its pre plugin's load (which answers before the config's own plugins) and through its read of the copy's path for Vitest's pragma read (serveCopies), and histories run copies only in Vite's server environments (node and the pragma's ssr environment): jsdom and happy-dom, Vite's client environment, are not generated (the #103 merge-gate review ran jsdom by hand under all five root shapes, and the copies loaded in each); 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; every read is a daemon input (maintainer decision, 2026-11-16, "All of them"), on any path and under node_modules too, with no package-boundary exception: the gate input (inputRead) is a JSON file that file b's verdict reads with a sync read in the package's tests, beside the package and outside it, or in a package under its node_modules, or the variable GAP_INPUT_GATE, or the gate plugin's sidecar file, and the inputGate edit flips only that input, drawn (maintainer decision, 2026-11-16, "Randomness wins") and in one constructed history per kind; a read from a worker thread or a child process that a test starts, an enumeration of the environment by a test (it is an input as the set of names, and not generated), or a read 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; a gate file's edits may keep its size and get back one fixed modification time (keepStamp), as cp -p, rsync -t, or touch -r leave a file, in generated histories and in two constructed ones (the package's file and the plugin's sidecar), so a reuse decided by a file's size and modification time across checks is seen (D10); an edit that keeps both during a check is not generated; law 9's edits leave out environment variables other than the seed and the gate's, 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 @@ -5975,6 +6023,94 @@ oracleProperty({ rejectBatch: 1, }), }, + // Every read is a daemon input (maintainer decision, 2026-11-16, "All + // of them"). File b's verdict also waits on one gate input, and the + // one edit flips only that input from `open` to `shut`: the cold run + // then reports b's mutant as a survivor, and the daemon must not + // reuse a kill that read the open gate (law 9). One history per kind + // of input, appended last, so the histories before them keep their + // seeds' samples. + ...[ + // A file in the package that the test reads, written back with its + // size and modification time, as `cp -p` leaves it: the daemon must + // see the new text all the same (D10). + [ + `an edit to a file in the package that keeps its size and modification time`, + `inside`, + true, + ], + [ + `an edit to a file outside the package that a test reads`, + `outside`, + false, + ], + [ + `an edit to a file under node_modules that a test reads`, + `module`, + false, + ], + [`an edit to an environment variable that a test reads`, `env`, false], + [ + `an edit to a file the config's plugin reads when the config resolves`, + `pluginConfig`, + false, + ], + // Written back with its size and modification time, too. + [ + `an edit to a file the config's plugin reads when it transforms a test`, + `pluginTransform`, + true, + ], + ].map(([name, inputRead, keepStamp]) => ({ + name, + enters: [ + `edit inputGate changed the cold result`, + `an edit to the ${inputRead} gate input changed the cold result`, + ...(keepStamp + ? [ + `an edit that kept a file's size and modification time changed the cold result`, + ] + : []), + ], + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`b`], + library: [], + libraryOwners: [], + runes: [], + derived: null, + dotGen: false, + dataOwners: [], + exportOwners: [], + importer: `none`, + wholeFile: `none`, + template: false, + tests: [{ ...judging(`b`, `fixed seed`, 1), fn: 0 }], + witness: false, + authored: null, + secondAuthored: false, + fault: `none`, + stability: `none`, + ordinary: false, + native: `none`, + boot: false, + cliPath: `plain`, + concurrentStart: false, + lazyGate: false, + fsRead: `none`, + prePlugin: false, + // A config the plugin can sit in, which Vitest discovers. + configPlace: `discovered`, + inputRead, + keepStamp, + laterSteps: NO_LATER_STEPS, + inputSteps: NO_INPUT_STEPS, + steps: [`inputGate`], + }), + })), ]), }, resolve: resolveHistory, diff --git a/packages/oracles/oracle-gaps/gap-report-static-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-static-oracle.property.test.mjs index 5ccab440..7abbca35 100644 --- a/packages/oracles/oracle-gaps/gap-report-static-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-static-oracle.property.test.mjs @@ -129,6 +129,7 @@ import { refusalBreach, resolveHistory, removePath, + outsideOf, sourceArgument, caseless, writeFixture, @@ -251,6 +252,7 @@ function defaultOutputsOf(dir, sources) { same: [outs[0] === outs[1], outs[0] === outs[2], outs[1] === outs[2]], } } finally { + rmSync(outsideOf(other), { recursive: true, force: true }) rmSync(other, { recursive: true, force: true }) } } @@ -977,6 +979,7 @@ async function driver(plan, observe) { } finally { written.delete(dir) removePath(`${dir}.link`) + rmSync(outsideOf(dir), { recursive: true, force: true }) rmSync(scratch, { recursive: true, force: true }) } } diff --git a/packages/oracles/oracle-gaps/history-fingerprint.json b/packages/oracles/oracle-gaps/history-fingerprint.json index 20fef659..1dca6243 100644 --- a/packages/oracles/oracle-gaps/history-fingerprint.json +++ b/packages/oracles/oracle-gaps/history-fingerprint.json @@ -57,7 +57,10 @@ ["warmReplaced", "ed6866229ecc4969"], ["testRoot", "e18db063421a75f1"], ["loadPlugin", "ed6866229ecc4969"], - ["rejectBatch", "e5386ea9402dd268"] + ["rejectBatch", "e5386ea9402dd268"], + ["inputRead", "a90da00463cd4e9a"], + ["keepStamp", "45ab5c81233b3182"], + ["inputSteps", "655fde9118d2e219"] ], "histories": [ ["functions", "66c0e9c56951c377"], @@ -117,6 +120,9 @@ ["warmReplaced", "ed6866229ecc4969"], ["testRoot", "e18db063421a75f1"], ["loadPlugin", "ed6866229ecc4969"], - ["rejectBatch", "e5386ea9402dd268"] + ["rejectBatch", "e5386ea9402dd268"], + ["inputRead", "a90da00463cd4e9a"], + ["keepStamp", "45ab5c81233b3182"], + ["inputSteps", "655fde9118d2e219"] ] } diff --git a/packages/oracles/scripts/pr-shards.mjs b/packages/oracles/scripts/pr-shards.mjs index 52670611..13c9dc9a 100644 --- a/packages/oracles/scripts/pr-shards.mjs +++ b/packages/oracles/scripts/pr-shards.mjs @@ -26,6 +26,16 @@ import { tmpdir } from 'node:os' import { dirname, join } from 'node:path' import { fileURLToPath } from 'node:url' +// The constructed histories of the edits of each kind of daemon input +// (gap-report-oracle.property.test.mjs). +const daemonInputUnits = [ + 'an edit to a file in the package that keeps its size and modification time', + 'an edit to a file outside the package that a test reads', + 'an edit to a file under node_modules that a test reads', + 'an edit to an environment variable that a test reads', + "an edit to a file the config's plugin reads when the config resolves", + "an edit to a file the config's plugin reads when it transforms a test", +] const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, `\\$&`) const anyOf = (names) => `(?:${names.map(escape).join(`|`)})` const rest = Symbol(`rest`) @@ -318,6 +328,10 @@ export const partitions = { // through the daemon (94 s), brokenOwner (83 s), generated (23 s), the // lazy module (12 s), and small units. 3: rest, + // The edits of a daemon input that every read makes one (maintainer + // decision, 2026-11-16, "Every read is a daemon input"), one unit per + // kind of input. + 4: anyOf(daemonInputUnits), }, }, 'oracle-gaps-static-windows': { @@ -543,6 +557,8 @@ export const partitions = { 'a config whose test root holds no test file', 'a config whose test root is a symbolic link', 'a config whose plugin loads test files with a sync read', + daemonInputUnits[0], + daemonInputUnits[1], ]), 7: anyOf([ 'a daemon pause that cannot engage', @@ -567,6 +583,8 @@ export const partitions = { 'an awaiting config in a package with no module type', 'a declaration fault: configNoDefault', 'a declaration fault: badEntry', + daemonInputUnits[2], + daemonInputUnits[3], ]), 9: anyOf([ 'a lazy module loaded before a hang in the same batch', @@ -579,6 +597,8 @@ export const partitions = { 'a .ts config in a package with no module type that calls require', 'ordinary tests left out by default', 'a declaration fault: configNull', + daemonInputUnits[4], + daemonInputUnits[5], ]), 10: anyOf([ 'an edit that changed the cold result after a hang replaced the only context', From 66d4cdc9ae6f8a2dd08d591a8574813e86c90962 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Mon, 16 Nov 2026 14:17:29 +0000 Subject: [PATCH 02/34] test(oracle-gaps): a cold run is cached by the variables its state sets too The gate variable of an env history changes no file, so the cold result of its edited state was read from the cache of its first state. 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 5259ce95..ace4f7f9 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1496,8 +1496,15 @@ async function incremental(dir, plan, cli, copy, observe, states) { if (!reportText.includes(RUN_LINE)) throw new Error(`the cli edit no longer finds the summary's run line`) const cold = new Map() + // A state is its files, its seed, its CLI, and the variables it sets. const fingerprint = (files, state, other = false) => - JSON.stringify([files, state.seed, state.cliEdited, other]) + JSON.stringify([ + files, + state.seed, + state.cliEdited, + other, + inputEnv(plan, state), + ]) cold.set(fingerprint(fixtureFiles(plan), initialState(plan)), cli) // A cold result without the run identity, which every edit changes, so // that two states compare by what they report. From c192abef739e82c2c8800c68c87854208ab8d038 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Mon, 16 Nov 2026 14:19:42 +0000 Subject: [PATCH 03/34] fix(oracle-gaps): every read is a daemon input For incremental equals cold (v21.2 I8, R46, G42), a unit's inputs now cover every read (maintainer decision, 2026-11-16, "All of them"): - a test's fs read on any path, node_modules included (the package boundary filter is gone); - a test's environment variable read, by value (env:), or the set of names when it lists them (env:*); - what Vitest, the config, and the config's own plugins read in the CLI's process while Vitest loads, while a context warms, and in each plugin hook (session inputs, added to every unit that settles after the read). The worker and the session share one recorder (inputs.mjs). The daemon runs a check only in the environment of the CLI that asks, and restarts when a session file input changed (G34, R46). The hash memo lives for one check, so an edit between checks that keeps size and mtime is seen (D10, D54: the TLA weakened-stamp mechanism). Co-authored-by: Isaac --- .changeset/gap-cli-daemon-every-read.md | 9 ++ README.md | 70 +++++----- .../oracles/oracle-gaps/capture-setup.mjs | 106 ++++---------- packages/oracles/oracle-gaps/check.mjs | 125 +++++++++++++++-- packages/oracles/oracle-gaps/daemon.mjs | 28 +++- packages/oracles/oracle-gaps/inputs.mjs | 129 ++++++++++++++++++ 6 files changed, 334 insertions(+), 133 deletions(-) create mode 100644 .changeset/gap-cli-daemon-every-read.md create mode 100644 packages/oracles/oracle-gaps/inputs.mjs diff --git a/.changeset/gap-cli-daemon-every-read.md b/.changeset/gap-cli-daemon-every-read.md new file mode 100644 index 00000000..c38c4416 --- /dev/null +++ b/.changeset/gap-cli-daemon-every-read.md @@ -0,0 +1,9 @@ +--- +'@tanstack/oracles': patch +--- + +A check through `--daemon` now treats every read as an input of the runs that made it, so after any of these changes it reports what a cold run reports. Before, the daemon reused a run that read the old input. The new inputs are a file that a test reads through `fs` outside the package or under `node_modules`; an environment variable that a test reads (or the set of variable names, when a test lists them); and a file or variable that Vitest, the Vite config, or one of the config's own plugins reads while it loads or in one of its hooks, such as a sidecar file that a plugin writes into the code it transforms. + +The daemon now runs each check in the environment of the CLI that asked for it. A check from another environment, or after a file that the config or a plugin read has changed, starts a new daemon, which still reuses every stored run whose inputs are unchanged. + +Each check now hashes every file input from its content, so an edit that keeps a file's size and modification time, as `cp -p`, `rsync -t`, or `touch -r` leave it, is no longer missed. diff --git a/README.md b/README.md index 94e550b6..a4c8072f 100644 --- a/README.md +++ b/README.md @@ -185,40 +185,42 @@ exited with ` and exits 3; after an out-of-memory crash it with `oracle-gaps --stop-daemon --package `. On Windows, which has no process groups, the run is not supervised. - A check through the daemon reuses a run while its inputs are unchanged: - the modules the run loaded, and the files in the package that its tests - read through `fs` (`readFileSync`, `readFile`, `existsSync`, `statSync`, - and `fs/promises` `readFile` and `stat`), each by the content that the - run read. A run that an edit overlapped, because a file changed after the - run read it, is not reused. A directory that a test stats or tests for is - an input as a directory, not by its content. - - Two kinds of input are not tracked yet. A Vite plugin whose output depends - on anything but a module's text, such as a sidecar file that it reads, can - make the daemon serve a run that read the plugin's old output. And the - daemon's environment is fixed when it starts, so an environment variable - that a later check sets does not reach the daemon's runs. After such a - change, run the check cold (without `--daemon`), or stop the daemon with - `oracle-gaps --stop-daemon --package `. The maintainer decided on - 2026-11-13 that the daemon tracks both and restarts when they change; a - later release does that. - - These reads are no input, so an edit to the file alone does not rerun the - tests that read it: a read outside the package or under `node_modules`; a - read from a worker thread or child process that the test starts; and a - read through any `fs` or `fs/promises` function other than the six above, - or through one of those six given a file descriptor. That catch-all - includes, for example, `readdir`, `opendir`, `glob`, `globSync`, - `createReadStream`, `realpath`, `lstat`, `access`, `open`, `read`, - `readSync`, `readv`, `fstat`, `fstatSync`, `copyFile`, `copyFileSync`, `cp`, - `cpSync`, `openAsBlob`, `statfs`, `readlink`, the callback `stat`, - `exists`, `watch`, and `watchFile`, and the `fs/promises` `readdir`, - `opendir`, `glob`, `lstat`, `realpath`, `readlink`, `access`, `open`, - `copyFile`, `cp`, `statfs`, and `watch`. Run the check cold (without - `--daemon`) after an edit to a file read that way. A later release records - all of them except `watch` and `watchFile`, which wait for future changes - and stay no input (maintainer decision, 2026-11-13, with `watchFile` in the - family of `watch`). + A check through the daemon reuses a run while its inputs are unchanged. + Every read is an input (maintainer decision, 2026-11-16): the modules the + run loaded; the files its tests read through `fs` on any path, inside the + package or outside it, `node_modules` included (`readFileSync`, + `readFile`, `existsSync`, `statSync`, and `fs/promises` `readFile` and + `stat`), each by the content that the run read; the environment variables + its tests read, by value, or all of them when a test lists them; and what + Vitest, the Vite config, and the config's own plugins read in the CLI's + process while it loads them and in each plugin hook. Each check hashes + every file input from its content, so an edit that keeps a file's size and + modification time (`cp -p`, `rsync -t`, `touch -r`) is seen. A run that an + edit overlapped, because a file changed after the run read it, is not + reused. A directory that a test stats or tests for is an input as a + directory, not by its content. + + The daemon runs every check in the environment that the CLI asking for it + has. A check from another environment, or after a file that Vitest, the + config, or a plugin read has changed, stops the daemon and starts a new + one, which reads them again; the runs it stored are still reused where + their inputs are unchanged. + + These reads are no input yet, so an edit to the file alone does not rerun + the tests that read it: a read from a worker thread or child process that + the test starts; and a read through any `fs` or `fs/promises` function + other than the six above, or through one of those six given a file + descriptor. That catch-all includes, for example, `readdir`, `opendir`, + `glob`, `globSync`, `createReadStream`, `realpath`, `lstat`, `access`, + `open`, `read`, `readSync`, `readv`, `fstat`, `fstatSync`, `copyFile`, + `copyFileSync`, `cp`, `cpSync`, `openAsBlob`, `statfs`, `readlink`, the + callback `stat`, `exists`, `watch`, and `watchFile`, and the `fs/promises` + `readdir`, `opendir`, `glob`, `lstat`, `realpath`, `readlink`, `access`, + `open`, `copyFile`, `cp`, `statfs`, and `watch`. Run the check cold + (without `--daemon`) after an edit to a file read that way. A later + release records all of them except `watch` and `watchFile`, which wait for + future changes and stay no input (maintainer decision, 2026-11-13, with + `watchFile` in the family of `watch`). - `packages/eslint-plugin-oracles` (`@tanstack/eslint-plugin-oracles`): the `oracle/*` lint rules. The rules recognize the framework by its package diff --git a/packages/oracles/oracle-gaps/capture-setup.mjs b/packages/oracles/oracle-gaps/capture-setup.mjs index cf56db29..67efd8f5 100644 --- a/packages/oracles/oracle-gaps/capture-setup.mjs +++ b/packages/oracles/oracle-gaps/capture-setup.mjs @@ -24,12 +24,12 @@ // In a mutant run, fast-check stops a property at its first failure instead // of shrinking it: a kill needs one failing history, not the smallest one. import { createHash } from 'node:crypto' -import fs, { appendFileSync, readFileSync } from 'node:fs' +import { appendFileSync, readFileSync } from 'node:fs' import { createRequire, syncBuiltinESMExports } from 'node:module' -import { dirname, isAbsolute, join, resolve as resolvePath } from 'node:path' -import { fileURLToPath } from 'node:url' +import { dirname, isAbsolute, join } from 'node:path' import { afterAll, beforeEach, chai, expect, inject, vi } from 'vitest' -import { posix, writeWhole } from './paths.mjs' +import { fileHash, keepProperties, watchReads } from './inputs.mjs' +import { writeWhole } from './paths.mjs' const run = inject(`oracleGaps`) ?? @@ -68,14 +68,7 @@ const realUse = real.use // A wrapper keeps every own property of the function it wraps, such as // `util.promisify.custom`, so `util.promisify(setTimeout)` still resolves -// with its value under the capture (law 3: a test that passes alone passes -// under the CLI). -function keepProperties(from, to) { - for (const key of Reflect.ownKeys(from)) - if (key !== `prototype`) - Object.defineProperty(to, key, Object.getOwnPropertyDescriptor(from, key)) - return to -} +// with its value under the capture (inputs.mjs, keepProperties). // The timers that code in this worker has pending, counted where they are // made, each with when it is next due: Node's resource list does not @@ -274,70 +267,23 @@ function appendClosingRow(row) { writeWhole(`${hold}.${marker}`, ``) appendFileSync(state.capture, row.slice(half)) } -// The files this copy reads through fs inside the package: by a sync, a -// promise, or a callback read, or a check of whether a file exists or what -// it is. The daemon stores the run under them as it does the modules the -// copy evaluated (the closing row's `loaded`), so an edit of only such a -// file runs it again, as a cold run sees the edit (law 9). Reads under -// node_modules and of the runner's own files are left out. Each path keeps -// its hash from the copy's first read of it, taken as the runner hashes an -// input (check.mjs, fileHashes), so the run is stored under the text it -// read and not under an edit that lands later in the run (review of #55, -// F1). +// What this copy reads: each file through fs, on any path, node_modules +// included, by a sync, a promise, or a callback read, or a check of whether +// a file exists or what it is; and each environment variable, or the set of +// names when the copy lists them (inputs.mjs). Every read is a daemon input +// (maintainer decision, 2026-11-16): the daemon stores the run under them as +// it does the modules the copy evaluated (the closing row's `loaded`), so an +// edit of only such an input runs it again, as a cold run sees the edit +// (law 9). A file keeps its hash from the copy's first read of it, so the +// run is stored under the text it read and not under an edit that lands +// later in the run (review of #55, F1). A variable's hash is the runner's, +// from the environment it gives the check (check.mjs, servedHash). globalThis.__oracleGapsReads = new Map() -if (!globalThis.__oracleGapsReading) { - globalThis.__oracleGapsReading = true - // A read's key follows the gap CLI's path rule (paths.mjs, copied beside - // this file with it). The file system gets the native path. - const root = `${posix(process.cwd()).replace(/\/+$/, ``)}/` - const { readFileSync: readNow, statSync: statNow } = fs - const hashNow = (path) => { - try { - return statNow(path).isFile() - ? createHash(`sha1`).update(readNow(path)).digest(`hex`) - : `not a file` - } catch { - return `missing` - } - } - const record = (target) => { - let path - try { - if (target instanceof URL) path = fileURLToPath(target) - else if (typeof target === `string`) path = resolvePath(target) - else if (Buffer.isBuffer(target)) path = resolvePath(target.toString()) - } catch { - return - } - if (path === undefined) return - const key = posix(path) - const reads = globalThis.__oracleGapsReads - if ( - key.startsWith(root) && - !key.includes(`/node_modules/`) && - !key.includes(`/.oracle-gaps`) && - !reads.has(key) - ) - reads.set(key, hashNow(path)) - } - // A wrapper keeps the function's own properties (its name and length, - // which code that dispatches on arity reads), so a test that passes alone - // passes under the capture (law 3; review of #55). - for (const [owner, names] of [ - [fs, [`readFileSync`, `readFile`, `existsSync`, `statSync`]], - [fs.promises, [`readFile`, `stat`]], - ]) - for (const name of names) { - const original = owner[name] - owner[name] = keepProperties(original, function (target, ...rest) { - record(target) - return original.call(this, target, ...rest) - }) - } - // An ES module's `import { readFileSync } from 'node:fs'` (and from - // 'node:fs/promises') reads these from now on. - syncBuiltinESMExports() -} +watchReads((key) => { + const reads = globalThis.__oracleGapsReads + if (!reads.has(key)) + reads.set(key, key.startsWith(`fs:`) ? fileHash(key.slice(3)) : null) +}) // A test's own writes to the process's stdout and stderr (a debugging // `process.stdout.write`) go to the run's test-output.log, beside its // capture, not to the CLI's streams, whose every line is a line of the @@ -1120,13 +1066,9 @@ afterAll(() => { // The hash of each file the copy read, from its first read, under its own // key (`fs:`): a test's read of a file is another input than the // module that its context serves from that file, which can differ from - // the file's text (fourth review of #55, F-A2). - const readAt = Object.fromEntries( - [...globalThis.__oracleGapsReads].map(([path, hash]) => [ - `fs:${path}`, - hash, - ]), - ) + // the file's text (fourth review of #55, F-A2). A variable it read has no + // hash here (`env:`, null). + const readAt = Object.fromEntries(globalThis.__oracleGapsReads) appendClosingRow( `${JSON.stringify({ file: thisFile, closed: true, loaded, readAt, ...(skippedCopy ? { skipped: true } : {}) })}\n`, ) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index 6f1be393..ad1f0040 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -9,16 +9,21 @@ // units, the ownership, and the options. A cold run computes every unit. The // daemon keeps each unit in its evidence store with the hash of every module // the run imported, as Vitest reports them, and of what was served for each -// instrumented or patched source; a stored unit is reused only while every -// one of those hashes is unchanged. So a check through the daemon reports -// what a cold run reports (the CLI oracle's law 9). Not covered: a file a -// test reads through `fs`, an environment variable other than the seed, and -// a new file that changes how an unchanged import resolves. +// instrumented or patched source, and of every other read the run made: a +// file its tests read through `fs` on any path, a variable they read, and +// what the config and its plugins read in this process (inputs.mjs; every +// read is a daemon input, maintainer decision, 2026-11-16). A stored unit is +// reused only while every one of those hashes is unchanged. So a check +// through the daemon reports what a cold run reports (the CLI oracle's law +// 9). Not covered: a read through another fs API than those inputs.mjs +// watches, one from a worker thread or a child process that a test starts, +// and a new file that changes how an unchanged import resolves. // // A unit's identity also carries the global inputs: this CLI's own files, // the harness, the Vite config and the files it loads, the package's // manifest and the lockfile, the Node version, and the options that change a // run (the seed, the test timeout, and bail). +import { AsyncLocalStorage } from 'node:async_hooks' import { spawn, spawnSync } from 'node:child_process' import { createHash } from 'node:crypto' import { @@ -73,6 +78,7 @@ import { specifierOf, } from './paths.mjs' import { stateDirOf } from './evidence.mjs' +import { envHash, fileHash, watchReads } from './inputs.mjs' import { baselineOf, blockedOr, @@ -161,6 +167,7 @@ const ownFiles = [ `stream.mjs`, `authored.mjs`, `capture-setup.mjs`, + `inputs.mjs`, `paths.mjs`, `evidence.mjs`, `daemon.mjs`, @@ -214,10 +221,52 @@ class KeepOrder { } } -/** Hashes of files by content, memoized by size and modification time. */ +/** + * The config's own plugins, with each hook run under `reading` (openSession), + * so what a hook reads is a session input. A `load` or `transform` hook + * names the module it serves. A plugin is wrapped once; a hook is a function + * or an object with a `handler`, as Vite takes it. + */ +const hooked = new WeakSet() +function pluginHooks(option, reading) { + if (Array.isArray(option)) + return option.map((plugin) => pluginHooks(plugin, reading)) + if (typeof option?.then === `function`) + return option.then((plugin) => pluginHooks(plugin, reading)) + if (option === null || typeof option !== `object` || hooked.has(option)) + return option + hooked.add(option) + for (const [name, hook] of Object.entries(option)) { + const handler = typeof hook === `function` ? hook : hook?.handler + if (typeof handler !== `function`) continue + const at = { load: 0, transform: 1 }[name] + const watched = function (...args) { + const id = at === undefined ? undefined : args[at] + return reading.run( + { + module: + typeof id === `string` + ? `fs:${posix(id.split(`?`)[0])}` + : undefined, + }, + () => handler.apply(this, args), + ) + } + option[name] = + typeof hook === `function` ? watched : { ...hook, handler: watched } + } + return option +} + +/** + * Hashes of files by content, memoized by size and modification time for + * one check (`forget`, which each check calls first): an edit between two + * checks that keeps a file's size and modification time, as `cp -p` leaves + * it, is still seen (D10; the TLA model's weakened-stamp run). + */ function fileHashes() { const memo = new Map() - return (path) => { + const hashOf = (path) => { let stat try { stat = statSync(path) @@ -240,6 +289,8 @@ function fileHashes() { memo.set(path, { stamp, hash }) return hash } + hashOf.forget = () => memo.clear() + return hashOf } /** The lockfile that pins the package's dependencies, if any. */ @@ -438,11 +489,31 @@ export async function openSession(pkg) { `the TypeScript this CLI depends on (${ts.version}) has no compiler API`, `Reinstall @tanstack/oracles, which depends on TypeScript 5.`, ) + // What Vitest, the config, and the config's own plugins read in this + // process (`reading`: while Vitest loads, while each context warms, and in + // each hook of the config's plugins, pluginHooks). Every plugin input is a + // daemon input (maintainer decision, 2026-11-16, "All of them"): each is + // an input of every unit that settles after it was read, with its hash + // from that read (settleIn), and a daemon whose session input changed is + // replaced (inputsChanged, daemon.mjs), since a plugin or a module may + // keep what it read. A load or transform hook's read of the module it + // serves is that module's own text, which is the module's input already. + const sessionReads = new Map() + const reading = new AsyncLocalStorage() + watchReads((key) => { + const hook = reading.getStore() + if (hook === undefined || key === hook.module || sessionReads.has(key)) + return + sessionReads.set(key, key.startsWith(`fs:`) ? fileHash(key.slice(3)) : null) + }) + globalThis.__oracleGapsPluginHooks = (plugins) => + pluginHooks(plugins, reading) const requireTarget = createRequire(join(pkg, `package.json`)) let createVitest try { - ;({ createVitest } = await import( - pathToFileURL(requireTarget.resolve(`vitest/node`)).href + ;({ createVitest } = await reading.run( + {}, + () => import(pathToFileURL(requireTarget.resolve(`vitest/node`)).href), )) } catch (error) { throw new Refusal( @@ -480,7 +551,9 @@ export async function openSession(pkg) { writeFileSync(join(home, `host`), hostname()) const harness = join(home, `capture-setup.mjs`) copyFileSync(join(here, `capture-setup.mjs`), harness) - // The harness imports the path rule beside it (capture-setup.mjs). + // The harness imports the input rule and the path rule beside it + // (capture-setup.mjs). + copyFileSync(join(here, `inputs.mjs`), join(home, `inputs.mjs`)) copyFileSync(join(here, `paths.mjs`), join(home, `paths.mjs`)) // One wrapper config per context, over the package's own config (a path // relative to the package, or undefined for none). Each serves its own @@ -520,6 +593,8 @@ export default async (env) => { const loaded = typeof base === 'function' ? await base(env) : await base if (loaded === null || typeof loaded !== 'object') throw new Error(${JSON.stringify(`${config ?? `the config`}: config must export or return an object.`)}) + // The config's own plugins, whose hooks' reads are inputs (check.mjs, pluginHooks). + if (loaded.plugins !== undefined) loaded.plugins = globalThis.__oracleGapsPluginHooks(loaded.plugins) const merged = mergeConfig(loaded, { plugins: [{ name: 'oracle-gaps-schemata', @@ -585,6 +660,8 @@ export default async (env) => { // module by the text that its context serves. const servedHash = (path, index) => { if (path.startsWith(`fs:`)) return hashOf(path.slice(3)) + // A variable by its value in the environment this check runs under. + if (path.startsWith(`env:`)) return envHash(path.slice(4)) const text = globalThis.__oracleGapsServe[index]?.get(path) ?? globalThis.__oracleGapsSchemata.get(path) @@ -721,7 +798,12 @@ export default async (env) => { await new Promise((resolve) => service.on(`exit`, resolve)) throw new Error(`The service was stopped`) } - async function warmContext(settings, index) { + // A context warms under `reading` (see sessionReads): what its config, + // Vite, and Vitest read while it warms is a session input. + function warmContext(settings, index) { + return reading.run({}, () => warmIn(settings, index)) + } + async function warmIn(settings, index) { await fromConfig(index, settings.config, warmProbe()) writeWrapper(index, settings.config) // A context that fails to open gives its listener allowance back: one @@ -1486,6 +1568,8 @@ export default async (env) => { } async function check(options, store, log = console.error) { + // Each check hashes every input from its text (fileHashes). + hashOf.forget() const authored = options.mutants ? loadAuthored(options.mutants) : [] seedVariable = `${options.envPrefix}_SEED` if (options.hangLimit > options.mutantLimit) @@ -1663,11 +1747,15 @@ export default async (env) => { // its context's transform of it, or else its hash at the start, or now. // A path that changed while the run ran is invalidated, and the run is // not stored (undefined); nor is a run with no known input. - function settleIn(context, started, paths, readAt = {}) { + function settleIn(context, started, runPaths, runReadAt = {}) { const index = indexOf.get(context) const served = servedBy(index) const loads = globalThis.__oracleGapsLoads[index] - let stable = paths.length > 0 + let stable = runPaths.length > 0 + // The session's inputs so far, each with its hash from its read: a + // run may have read through any of them (see sessionReads). + const paths = [...new Set([...runPaths, ...sessionReads.keys()])] + const readAt = { ...Object.fromEntries(sessionReads), ...runReadAt } const inputs = paths.map((path) => { const now = servedHash(path, index) const hash = @@ -2625,7 +2713,16 @@ export default async (env) => { rmSync(home, { recursive: true, force: true }) } - return { check, close } + /** + * Whether a file the session read (sessionReads) holds other text now: a + * daemon then serves no more checks, since a plugin or a module may keep + * what it read (daemon.mjs). + */ + const inputsChanged = () => + [...sessionReads].some( + ([key, hash]) => key.startsWith(`fs:`) && fileHash(key.slice(3)) !== hash, + ) + return { check, close, inputsChanged } } /** diff --git a/packages/oracles/oracle-gaps/daemon.mjs b/packages/oracles/oracle-gaps/daemon.mjs index 71837dba..3bcfdda7 100644 --- a/packages/oracles/oracle-gaps/daemon.mjs +++ b/packages/oracles/oracle-gaps/daemon.mjs @@ -182,7 +182,13 @@ export async function requestDaemon(pkg, argv, code) { let reply const sent = Date.now() try { - reply = await send(pkg, { argv, cwd: process.cwd(), code }) + // The CLI's environment, which the daemon must run the check under. + reply = await send(pkg, { + argv, + cwd: process.cwd(), + code, + env: process.env, + }) held += Date.now() - sent } catch (error) { if (!absent(error)) throw error @@ -311,7 +317,13 @@ async function takeLock(lock, socket) { } } +// An environment as one value: its names and values, in name order. +const envKey = (env) => JSON.stringify(Object.entries(env ?? {}).sort()) + async function serve(pkg) { + // The environment this daemon runs its checks under, which the CLI that + // started it gave it, taken before the session sets anything in it. + const ownEnv = envKey(process.env) mkdirSync(stateDirOf(pkg), { recursive: true }) const lock = join(stateDirOf(pkg), `daemon.lock`) const socket = socketOf(pkg) @@ -396,8 +408,18 @@ async function serve(pkg) { // A daemon whose code changed, or that a CLI of other code asks (a // second install), declines this check and closes after the // requests already queued, each of which hears `closing`; the CLI - // then starts a daemon of its own code. - if (codeIdentity() !== code || message.code !== code) { + // then starts a daemon of its own code. So does a daemon asked from + // another environment than its own, or whose session read a file + // that changed since (check.mjs, inputsChanged): every read is a + // daemon input (maintainer decision, 2026-11-16), and a module or a + // plugin may keep what it read, so the CLI starts a daemon in its own + // environment, which reads them again. + if ( + codeIdentity() !== code || + message.code !== code || + envKey(message.env) !== ownEnv || + session.inputsChanged() + ) { closing = true queue = queue.then(() => shutdown(connection, { restart: true })) return diff --git a/packages/oracles/oracle-gaps/inputs.mjs b/packages/oracles/oracle-gaps/inputs.mjs new file mode 100644 index 00000000..e23c68c1 --- /dev/null +++ b/packages/oracles/oracle-gaps/inputs.mjs @@ -0,0 +1,129 @@ +// What a run reads, as the daemon keys it. Every read is a daemon input +// (maintainer decision, 2026-11-16, "All of them"): a file read through fs +// on any path, node_modules included, an environment variable, and what +// the config's own plugins read. So when one changes between two checks, +// the next check through the daemon reports what a cold run reports (the +// CLI oracle's law 9). +// +// An input's key is `fs:` for a file, hashed by its text (or as +// `not a file`, or `missing`), `env:` for a variable, hashed by its +// value, or `env:*` for the set of names, which code reads when it lists +// the environment. The harness (capture-setup.mjs) watches a test's reads in +// its worker, and the session (check.mjs) watches what the config and its +// plugins read in the CLI's process. Both files are copied beside the +// harness with this one. +import { createHash } from 'node:crypto' +import fs from 'node:fs' +import { syncBuiltinESMExports } from 'node:module' +import { resolve } from 'node:path' +import { fileURLToPath } from 'node:url' +import { posix } from './paths.mjs' + +// The calls that read a file, and those that test whether it exists and +// what it is. Each is taken once per process, before a wrapper replaces it, +// so hashing a file is not itself a read. +const reads = [ + [fs, [`readFileSync`, `readFile`, `existsSync`, `statSync`]], + [fs.promises, [`readFile`, `stat`]], +] +const original = (globalThis.__oracleGapsOriginalFs ??= { + readFileSync: fs.readFileSync, + statSync: fs.statSync, +}) +const sha1 = (data) => createHash(`sha1`).update(data).digest(`hex`) + +/** + * A file's input hash now, never from a cache: the hash of its text, or + * `not a file` (a test can stat a directory, whose input is that a + * directory is there), or `missing`. + */ +export function fileHash(path) { + try { + return original.statSync(path).isFile() + ? sha1(original.readFileSync(path)) + : `not a file` + } catch { + return `missing` + } +} + +/** A variable's input hash under `env`, or for `*`, that of its names. */ +export const envHash = (name, env = process.env) => + sha1( + name === `*` + ? Object.keys(env).sort().join(`\0`) + : `${env[name] === undefined ? `unset` : `=${env[name]}`}`, + ) + +// The runner's own files: a session directory (`.oracle-gaps-/`, which +// holds this file) and the copies of test files +// (`.oracle-gaps---`). A user's path that only contains +// `.oracle-gaps` is an input like any other. +const isRunnerFile = (path) => /\/\.oracle-gaps-\d+[-/]/.test(path) + +/** + * A wrapper keeps every own property of the function it wraps (its name + * and length, which code that dispatches on arity reads, or + * `util.promisify.custom`), so a test that passes alone passes under the + * capture (law 3; review of #55). + */ +export function keepProperties(from, to) { + for (const key of Reflect.ownKeys(from)) + if (key !== `prototype`) + Object.defineProperty(to, key, Object.getOwnPropertyDescriptor(from, key)) + return to +} + +/** + * Watches this process's reads from now on: each read calls `record(key)` + * with the input's key, the `record` of the latest call. The wrappers are + * installed once per process. A file's path is the path rule's (paths.mjs), + * and the runner's own files are left out. An ES module's + * `import { readFileSync } from 'node:fs'` reads the wrappers too. + */ +export function watchReads(record) { + globalThis.__oracleGapsRecord = record + if (globalThis.__oracleGapsWatching) return + globalThis.__oracleGapsWatching = true + record = (key) => globalThis.__oracleGapsRecord(key) + const watched = (target) => { + let path + try { + if (target instanceof URL) path = fileURLToPath(target) + else if (typeof target === `string`) path = resolve(target) + else if (Buffer.isBuffer(target)) path = resolve(target.toString()) + } catch { + return + } + if (path !== undefined && !isRunnerFile(posix(path))) + record(`fs:${posix(path)}`) + } + for (const [owner, names] of reads) + for (const name of names) { + const read = owner[name] + owner[name] = keepProperties(read, function (target, ...rest) { + watched(target) + return read.call(this, target, ...rest) + }) + } + syncBuiltinESMExports() + // A variable read by name, a test of whether it is set, and a listing of + // the names, which reads the set of names. + process.env = new Proxy(process.env, { + get(env, name) { + if (typeof name === `string`) record(`env:${name}`) + return Reflect.get(env, name) + }, + has(env, name) { + if (typeof name === `string`) record(`env:${name}`) + return Reflect.has(env, name) + }, + ownKeys(env) { + record(`env:*`) + return Reflect.ownKeys(env) + }, + // A write goes to the environment itself, which keeps its own rules + // (a value is a string). + set: (env, name, value) => Reflect.set(env, name, value), + }) +} From 965182cfaf2060a694bac608f5b1b0a8fe38b316 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Mon, 16 Nov 2026 14:27:55 +0000 Subject: [PATCH 04/34] fix(oracle-gaps): a file a reader wrote before it read it is no input Vite bundles the config into a temporary file and imports it, and a test may read back a temporary file it wrote: such a file holds the reader's own output, so it is no input. A write is known by the path it names and by its directory's real path, which an import by real URL names. The contexts also run without Vitest's results cache, which the runner's own order makes useless and which every run rewrites. The session's warm-time reads (Vitest, Vite, and the config while Vitest loads and a context warms, some hundred files and variables) are global inputs, in the unit identity, so a unit stores only what the config's own plugin hooks read. Co-authored-by: Isaac --- .../oracles/oracle-gaps/capture-setup.mjs | 9 ++- packages/oracles/oracle-gaps/check.mjs | 57 ++++++++++++------- packages/oracles/oracle-gaps/inputs.mjs | 53 ++++++++++++----- 3 files changed, 80 insertions(+), 39 deletions(-) diff --git a/packages/oracles/oracle-gaps/capture-setup.mjs b/packages/oracles/oracle-gaps/capture-setup.mjs index 67efd8f5..0dde87c0 100644 --- a/packages/oracles/oracle-gaps/capture-setup.mjs +++ b/packages/oracles/oracle-gaps/capture-setup.mjs @@ -277,11 +277,14 @@ function appendClosingRow(row) { // (law 9). A file keeps its hash from the copy's first read of it, so the // run is stored under the text it read and not under an edit that lands // later in the run (review of #55, F1). A variable's hash is the runner's, -// from the environment it gives the check (check.mjs, servedHash). +// from the environment it gives the check (check.mjs, servedHash). A file +// the copy wrote before it read it is its own output, no input. globalThis.__oracleGapsReads = new Map() -watchReads((key) => { +const wrote = new Set() +watchReads((key, write) => { const reads = globalThis.__oracleGapsReads - if (!reads.has(key)) + if (write) wrote.add(key) + else if (!reads.has(key) && !wrote.has(key)) reads.set(key, key.startsWith(`fs:`) ? fileHash(key.slice(3)) : null) }) // A test's own writes to the process's stdout and stderr (a debugging diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index ad1f0040..79f143f8 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -244,6 +244,7 @@ function pluginHooks(option, reading) { const id = at === undefined ? undefined : args[at] return reading.run( { + hook: true, module: typeof id === `string` ? `fs:${posix(id.split(`?`)[0])}` @@ -490,21 +491,29 @@ export async function openSession(pkg) { `Reinstall @tanstack/oracles, which depends on TypeScript 5.`, ) // What Vitest, the config, and the config's own plugins read in this - // process (`reading`: while Vitest loads, while each context warms, and in - // each hook of the config's plugins, pluginHooks). Every plugin input is a - // daemon input (maintainer decision, 2026-11-16, "All of them"): each is - // an input of every unit that settles after it was read, with its hash - // from that read (settleIn), and a daemon whose session input changed is - // replaced (inputsChanged, daemon.mjs), since a plugin or a module may - // keep what it read. A load or transform hook's read of the module it - // serves is that module's own text, which is the module's input already. - const sessionReads = new Map() + // process (`reading`): every plugin input is a daemon input (maintainer + // decision, 2026-11-16, "All of them"). What Vitest and Vite read while + // Vitest loads and while a context warms (`warmReads`, some hundred files + // and variables) is a global input of every unit (globalKey). What a hook + // of the config's own plugins reads (`hookReads`, pluginHooks), at any + // time, is an input of every unit that settles after it, with its hash + // from that read (settleIn). A daemon whose session read a file that has + // changed since is replaced (inputsChanged, daemon.mjs), since a plugin or + // a module may keep what it read. A load or transform hook's read of the + // module it serves is that module's own text, the module's input already. + // A file that the session wrote there before it read it, such as the + // config Vite bundles into a temporary file, is the session's own output. + const warmReads = new Map() + const hookReads = new Map() + const wrote = new Set() const reading = new AsyncLocalStorage() - watchReads((key) => { - const hook = reading.getStore() - if (hook === undefined || key === hook.module || sessionReads.has(key)) - return - sessionReads.set(key, key.startsWith(`fs:`) ? fileHash(key.slice(3)) : null) + watchReads((key, write) => { + const at = reading.getStore() + const reads = at?.hook ? hookReads : warmReads + if (at === undefined || key === at.module || reads.has(key)) return + if (write) wrote.add(key) + else if (!wrote.has(key)) + reads.set(key, key.startsWith(`fs:`) ? fileHash(key.slice(3)) : null) }) globalThis.__oracleGapsPluginHooks = (plugins) => pluginHooks(plugins, reading) @@ -798,8 +807,8 @@ export default async (env) => { await new Promise((resolve) => service.on(`exit`, resolve)) throw new Error(`The service was stopped`) } - // A context warms under `reading` (see sessionReads): what its config, - // Vite, and Vitest read while it warms is a session input. + // A context warms under `reading` (see warmReads): what its config, Vite, + // and Vitest read while it warms is a global input. function warmContext(settings, index) { return reading.run({}, () => warmIn(settings, index)) } @@ -828,6 +837,10 @@ export default async (env) => { teardownTimeout: settings.testTimeout, typecheck: { enabled: false }, coverage: { enabled: false }, + // The runner orders the files itself (KeepOrder), so Vitest's + // results cache, which it reads when a context warms and writes + // after each run, would only be an input that every run changes. + cache: false, // Vitest 5 caches transformed modules on disk by default, keyed by // the file, not by what this runner's plugin serves for it, so a // patched or instrumented source could come back as an earlier text. @@ -1752,10 +1765,10 @@ export default async (env) => { const served = servedBy(index) const loads = globalThis.__oracleGapsLoads[index] let stable = runPaths.length > 0 - // The session's inputs so far, each with its hash from its read: a - // run may have read through any of them (see sessionReads). - const paths = [...new Set([...runPaths, ...sessionReads.keys()])] - const readAt = { ...Object.fromEntries(sessionReads), ...runReadAt } + // What the config's plugins have read so far, each with its hash from + // its read: the run may have read through any of it (see hookReads). + const paths = [...new Set([...runPaths, ...hookReads.keys()])] + const readAt = { ...Object.fromEntries(hookReads), ...runReadAt } const inputs = paths.map((path) => { const now = servedHash(path, index) const hash = @@ -2714,12 +2727,12 @@ export default async (env) => { } /** - * Whether a file the session read (sessionReads) holds other text now: a + * Whether a file the session read (warmReads, hookReads) holds other text now: a * daemon then serves no more checks, since a plugin or a module may keep * what it read (daemon.mjs). */ const inputsChanged = () => - [...sessionReads].some( + [...warmReads, ...hookReads].some( ([key, hash]) => key.startsWith(`fs:`) && fileHash(key.slice(3)) !== hash, ) return { check, close, inputsChanged } diff --git a/packages/oracles/oracle-gaps/inputs.mjs b/packages/oracles/oracle-gaps/inputs.mjs index e23c68c1..23055280 100644 --- a/packages/oracles/oracle-gaps/inputs.mjs +++ b/packages/oracles/oracle-gaps/inputs.mjs @@ -15,7 +15,7 @@ import { createHash } from 'node:crypto' import fs from 'node:fs' import { syncBuiltinESMExports } from 'node:module' -import { resolve } from 'node:path' +import { basename, dirname, join, resolve } from 'node:path' import { fileURLToPath } from 'node:url' import { posix } from './paths.mjs' @@ -26,9 +26,18 @@ const reads = [ [fs, [`readFileSync`, `readFile`, `existsSync`, `statSync`]], [fs.promises, [`readFile`, `stat`]], ] +// The calls that write a file's text. A file that a reader wrote before it +// reads it holds the reader's own output, which follows from the reader's +// other inputs, so that read is no input: a test's temporary file, or the +// config that Vite bundles into a temporary file and then imports. +const writes = [ + [fs, [`writeFileSync`, `writeFile`, `appendFileSync`, `appendFile`]], + [fs.promises, [`writeFile`, `appendFile`]], +] const original = (globalThis.__oracleGapsOriginalFs ??= { readFileSync: fs.readFileSync, statSync: fs.statSync, + realpathSync: fs.realpathSync.native, }) const sha1 = (data) => createHash(`sha1`).update(data).digest(`hex`) @@ -76,7 +85,8 @@ export function keepProperties(from, to) { /** * Watches this process's reads from now on: each read calls `record(key)` - * with the input's key, the `record` of the latest call. The wrappers are + * with the input's key, and each write of a file `record(key, true)`, the + * `record` of the latest call. The wrappers are * installed once per process. A file's path is the path rule's (paths.mjs), * and the runner's own files are left out. An ES module's * `import { readFileSync } from 'node:fs'` reads the wrappers too. @@ -85,8 +95,8 @@ export function watchReads(record) { globalThis.__oracleGapsRecord = record if (globalThis.__oracleGapsWatching) return globalThis.__oracleGapsWatching = true - record = (key) => globalThis.__oracleGapsRecord(key) - const watched = (target) => { + record = (key, write) => globalThis.__oracleGapsRecord(key, write) + const watched = (target, write) => { let path try { if (target instanceof URL) path = fileURLToPath(target) @@ -95,17 +105,32 @@ export function watchReads(record) { } catch { return } - if (path !== undefined && !isRunnerFile(posix(path))) - record(`fs:${posix(path)}`) + if (path === undefined || isRunnerFile(posix(path))) return + record(`fs:${posix(path)}`, write) + // A written file is also known by its directory's real path, which a + // later read through a link, or an import by its real URL, names. + if (write) + try { + record( + `fs:${posix(join(original.realpathSync(dirname(path)), basename(path)))}`, + write, + ) + } catch { + // No directory to write in: the write fails as it would. + } } - for (const [owner, names] of reads) - for (const name of names) { - const read = owner[name] - owner[name] = keepProperties(read, function (target, ...rest) { - watched(target) - return read.call(this, target, ...rest) - }) - } + for (const [calls, write] of [ + [reads, false], + [writes, true], + ]) + for (const [owner, names] of calls) + for (const name of names) { + const call = owner[name] + owner[name] = keepProperties(call, function (target, ...rest) { + watched(target, write) + return call.call(this, target, ...rest) + }) + } syncBuiltinESMExports() // A variable read by name, a test of whether it is set, and a listing of // the names, which reads the set of names. From 44f6c6d29eec9e5e9a7addc00fe6452497a7c3cf Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Mon, 16 Nov 2026 14:28:09 +0000 Subject: [PATCH 05/34] fix(oracle-gaps): the unit identity carries the session's warm-time reads Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index 79f143f8..924dacad 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -1701,6 +1701,9 @@ export default async (env) => { ] .sort() .map((file) => [file, hashOf(file)]), + // What Vitest, Vite, and the config read while Vitest loaded and the + // contexts warmed (warmReads), each by its value now. + [...warmReads.keys()].sort().map((key) => [key, servedHash(key)]), process.version, options.seed ?? null, settings, From 89424e406976ffa0c689c707c2bb9b693c0f726d Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Mon, 16 Nov 2026 14:29:41 +0000 Subject: [PATCH 06/34] test(oracle-gaps): each input edit is followed by an unchanged check A daemon that never reuses a run equals a cold run trivially. After the input edit, a second check through the daemon with nothing changed must compute nothing (law unchanged reuse), so that build fails the oracle. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-oracle.property.test.mjs | 11 +++++++---- 1 file changed, 7 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 ace4f7f9..f8d47450 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -6034,9 +6034,11 @@ oracleProperty({ // of them"). File b's verdict also waits on one gate input, and the // one edit flips only that input from `open` to `shut`: the cold run // then reports b's mutant as a survivor, and the daemon must not - // reuse a kill that read the open gate (law 9). One history per kind - // of input, appended last, so the histories before them keep their - // seeds' samples. + // reuse a kill that read the open gate (law 9). A second check with + // nothing changed then computes nothing (the `unchanged reuse` law), so + // a daemon that never reuses, which equals a cold run trivially, fails + // too. One history per kind of input, appended last, so the histories + // before them keep their seeds' samples. ...[ // A file in the package that the test reads, written back with its // size and modification time, as `cp -p` leaves it: the daemon must @@ -6073,6 +6075,7 @@ oracleProperty({ enters: [ `edit inputGate changed the cold result`, `an edit to the ${inputRead} gate input changed the cold result`, + `an unchanged check through the daemon computed nothing`, ...(keepStamp ? [ `an edit that kept a file's size and modification time changed the cold result`, @@ -6115,7 +6118,7 @@ oracleProperty({ keepStamp, laterSteps: NO_LATER_STEPS, inputSteps: NO_INPUT_STEPS, - steps: [`inputGate`], + steps: [`inputGate`, `recheck`], }), })), ]), From 64a85617d8aeaeae2ab3eaaf403a73936081653b Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Mon, 16 Nov 2026 15:11:44 +0000 Subject: [PATCH 07/34] fix(oracle-gaps): a variable the CLI set, and a read after its warm, stay out of the global inputs The CLI sets ORACLE_GAPS_STATE to each check's output, so a warm-time read of it changed every unit's identity between checks. A variable the reader set before it read it is its own output, as a file it wrote is. And work that a warm leaves behind can read after the warm ended (Vite read the workspace's package.json during a run): such a read is an input of the units that settle after it, not a global one, so the unit identity stays that of the warm. Found by the oracle's unchanged check after each input edit: every check through the daemon computed every run. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 21 +++++++++++++++++---- packages/oracles/oracle-gaps/inputs.mjs | 10 +++++++--- 2 files changed, 24 insertions(+), 7 deletions(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index 924dacad..cc65ebd5 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -503,25 +503,38 @@ export async function openSession(pkg) { // module it serves is that module's own text, the module's input already. // A file that the session wrote there before it read it, such as the // config Vite bundles into a temporary file, is the session's own output. + // So is a variable that the CLI set (ORACLE_GAPS_STATE, which names each + // check's output). A read that comes after its warm ended, from work the + // warm left behind, is a hook's read, so the global inputs stay those of + // the warm itself. const warmReads = new Map() const hookReads = new Map() const wrote = new Set() const reading = new AsyncLocalStorage() watchReads((key, write) => { const at = reading.getStore() - const reads = at?.hook ? hookReads : warmReads + if (write && key.startsWith(`env:`)) wrote.add(key) + const reads = at?.hook || at?.done ? hookReads : warmReads if (at === undefined || key === at.module || reads.has(key)) return if (write) wrote.add(key) else if (!wrote.has(key)) reads.set(key, key.startsWith(`fs:`) ? fileHash(key.slice(3)) : null) }) + // Runs `work` as a warm under `reading`. + const warming = async (work) => { + const at = {} + try { + return await reading.run(at, work) + } finally { + at.done = true + } + } globalThis.__oracleGapsPluginHooks = (plugins) => pluginHooks(plugins, reading) const requireTarget = createRequire(join(pkg, `package.json`)) let createVitest try { - ;({ createVitest } = await reading.run( - {}, + ;({ createVitest } = await warming( () => import(pathToFileURL(requireTarget.resolve(`vitest/node`)).href), )) } catch (error) { @@ -810,7 +823,7 @@ export default async (env) => { // A context warms under `reading` (see warmReads): what its config, Vite, // and Vitest read while it warms is a global input. function warmContext(settings, index) { - return reading.run({}, () => warmIn(settings, index)) + return warming(() => warmIn(settings, index)) } async function warmIn(settings, index) { await fromConfig(index, settings.config, warmProbe()) diff --git a/packages/oracles/oracle-gaps/inputs.mjs b/packages/oracles/oracle-gaps/inputs.mjs index 23055280..bd3f8f03 100644 --- a/packages/oracles/oracle-gaps/inputs.mjs +++ b/packages/oracles/oracle-gaps/inputs.mjs @@ -85,7 +85,8 @@ export function keepProperties(from, to) { /** * Watches this process's reads from now on: each read calls `record(key)` - * with the input's key, and each write of a file `record(key, true)`, the + * with the input's key, and each write of a file or a variable + * `record(key, true)`, the * `record` of the latest call. The wrappers are * installed once per process. A file's path is the path rule's (paths.mjs), * and the runner's own files are left out. An ES module's @@ -148,7 +149,10 @@ export function watchReads(record) { return Reflect.ownKeys(env) }, // A write goes to the environment itself, which keeps its own rules - // (a value is a string). - set: (env, name, value) => Reflect.set(env, name, value), + // (a value is a string). A variable the reader set is its own output. + set(env, name, value) { + if (typeof name === `string`) record(`env:${name}`, true) + return Reflect.set(env, name, value) + }, }) } From 38dd019cf420a560a3fd021db5b5535e5b92191d Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Mon, 16 Nov 2026 15:18:07 +0000 Subject: [PATCH 08/34] test(oracle-gaps): the gate plugin finds its file from the config's own location A config's test root moves Vite's root (the constructed test-root histories), so a path from the resolved root named a file in src/. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-model-oracle.mjs | 36 ++++++++++++------- 1 file changed, 24 insertions(+), 12 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index b1dd9770..60ce4ba8 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -17,7 +17,7 @@ import { writeFileSync, } from 'node:fs' import { createRequire } from 'node:module' -import { dirname, join } from 'node:path' +import { dirname, join, posix as posixPath } from 'node:path' import { fileURLToPath } from 'node:url' import fc from 'fast-check' @@ -5374,19 +5374,26 @@ const LOAD_PLUGIN = `{ name: 'gap-own-load', load(id) { const path = id.split('? // The config's own plugin that reads the gate file (`inputRead` // `pluginConfig` or `pluginTransform`) and writes its word in place of // `__GAP_INPUT_GATE__` in each test file it transforms. It finds the file -// under the root Vite resolved, so it reads the package's file wherever the -// config lies. `pluginConfig` reads it once, when the config resolves; -// `pluginTransform` reads it in each transform. -const GATE_READ = `JSON.parse(readGate(root + '/tests/plugin-gate.json', 'utf8')).gate` +// from the config's own location (`gatePath`), not from a root, which a +// config's test root moves. `pluginConfig` reads it once, when the config +// resolves; `pluginTransform` reads it in each transform. +const GATE_READ = `JSON.parse(readGate(gatePath, 'utf8')).gate` const gatePlugin = (plan) => - `(() => { let root; let gate; return { name: 'gap-input-gate', configResolved(resolved) { root = resolved.root${plan.inputRead === `pluginConfig` ? `; gate = ${GATE_READ}` : ``} }, transform(code, id) { return id.split('?')[0].endsWith('.test.ts') ? code.replaceAll('__GAP_INPUT_GATE__', JSON.stringify(${plan.inputRead === `pluginConfig` ? `gate` : GATE_READ})) : undefined } } })()` + `(() => { let gate; return { name: 'gap-input-gate', configResolved() { ${plan.inputRead === `pluginConfig` ? `gate = ${GATE_READ}` : ``} }, transform(code, id) { return id.split('?')[0].endsWith('.test.ts') ? code.replaceAll('__GAP_INPUT_GATE__', JSON.stringify(${plan.inputRead === `pluginConfig` ? `gate` : GATE_READ})) : undefined } } })()` +// The gate file's path from a config at `configPath` (in the package, or in +// its parent, where the package is the directory `pkg`). +const gateFromConfig = (configPath) => + posixPath.relative( + posixPath.dirname(posixPath.join(`/pkg`, configPath)), + `/pkg/tests/plugin-gate.json`, + ) /** * The text of the package's config, in its syntax (`configOf`), with the * fault, the top-level await, or the `require` calls the plan holds. `test` * is the config's `test` object. */ -function configText(plan, test) { +function configText(plan, test, configPath = plan.configPath) { const commonjs = plan.configSyntax === `cjs` const plugins = [ ...(plan.prePlugin ? [PRE_PLUGIN] : []), @@ -5421,11 +5428,15 @@ function configText(plan, test) { // Only an ES module config has the load plugin (its constructed history). ...(plan.loadPlugin ? [`import { readFileSync } from 'node:fs'`] : []), ...(pluginGated(plan) - ? [ - commonjs - ? `const { readFileSync: readGate } = require('node:fs')` - : `import { readFileSync as readGate } from 'node:fs'`, - ] + ? commonjs + ? [ + `const { readFileSync: readGate } = require('node:fs')`, + `const gatePath = require('node:path').join(__dirname, '${gateFromConfig(configPath)}')`, + ] + : [ + `import { readFileSync as readGate } from 'node:fs'`, + `const gatePath = new URL('${gateFromConfig(configPath)}', import.meta.url)`, + ] : []), ...(plan.fault === `configThrows` ? [`throw new Error('the fixture config broke')`] @@ -5611,6 +5622,7 @@ function fixtureFiles(plan, state = initialState(plan)) { [altConfigPath(plan)]: configText( plan, test.replace(`'tests/**/*.test.ts'`, `'tests/a.test.ts'`), + altConfigPath(plan), ), } : {}), From 0cffc447e0b3497e1244a1b2c7c45ae0144a29ca Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Mon, 16 Nov 2026 15:47:49 +0000 Subject: [PATCH 09/34] fix(oracle-gaps): the global inputs are the first check's warm reads A context that replaces one cut off by a hang warms again, and what it read that the first warm did not changed every later unit's identity, so a revert to a state the daemon had seen ran everything again (the witness edit sequence lost the state "a revert of a file edit reran nothing"). Such a read is now an input of the units that settle after it. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index cc65ebd5..f440ff79 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -506,7 +506,10 @@ export async function openSession(pkg) { // So is a variable that the CLI set (ORACLE_GAPS_STATE, which names each // check's output). A read that comes after its warm ended, from work the // warm left behind, is a hook's read, so the global inputs stay those of - // the warm itself. + // the warm itself. So is what a later warm reads that the first did not + // (a context that replaces one cut off by a hang): the global inputs are + // those of the session's first check (`warmed`), and stay one set. + let warmed = false const warmReads = new Map() const hookReads = new Map() const wrote = new Set() @@ -514,8 +517,14 @@ export async function openSession(pkg) { watchReads((key, write) => { const at = reading.getStore() if (write && key.startsWith(`env:`)) wrote.add(key) - const reads = at?.hook || at?.done ? hookReads : warmReads - if (at === undefined || key === at.module || reads.has(key)) return + const reads = at?.hook || at?.done || warmed ? hookReads : warmReads + if ( + at === undefined || + key === at.module || + reads.has(key) || + warmReads.has(key) + ) + return if (write) wrote.add(key) else if (!wrote.has(key)) reads.set(key, key.startsWith(`fs:`) ? fileHash(key.slice(3)) : null) @@ -1725,6 +1734,7 @@ export default async (env) => { options.mutantLimit, ]), ) + warmed = true // How the evidence was produced: units reused and computed, runs cut off // at their time limit or for idleness (of them, `idle`), items rerun // after a cut-off batch, and mutants that changed no value and so needed From 5cc1f2be890d9d037b042e73bba6fcf2cf99e012 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Mon, 16 Nov 2026 16:02:55 +0000 Subject: [PATCH 10/34] fix(oracle-gaps): a variable the CLI set is no input of a run either A copy that read ORACLE_GAPS_STATE (the harness's fallback) was stored under the check's own output path, so a revert to a state the daemon had seen ran it again. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index f440ff79..5c946296 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -1793,7 +1793,11 @@ export default async (env) => { let stable = runPaths.length > 0 // What the config's plugins have read so far, each with its hash from // its read: the run may have read through any of it (see hookReads). - const paths = [...new Set([...runPaths, ...hookReads.keys()])] + // A variable that the CLI set (`wrote`) is its own output, which a + // copy may read too (the harness's fallback read of ORACLE_GAPS_STATE). + const paths = [...new Set([...runPaths, ...hookReads.keys()])].filter( + (path) => !wrote.has(path), + ) const readAt = { ...Object.fromEntries(hookReads), ...runReadAt } const inputs = paths.map((path) => { const now = servedHash(path, index) From 156a5c0b68e18326e4f407818b90afd1755d76e5 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Mon, 16 Nov 2026 16:03:51 +0000 Subject: [PATCH 11/34] fix(oracle-gaps): drop the frozen global input set The witness edit sequence's lost revert state came from ORACLE_GAPS_STATE as a run input (fixed in the previous commit), not from a replacement warm's reads, so the freeze added code that no history needs. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 16 +++------------- 1 file changed, 3 insertions(+), 13 deletions(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index 5c946296..1d39944a 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -506,10 +506,7 @@ export async function openSession(pkg) { // So is a variable that the CLI set (ORACLE_GAPS_STATE, which names each // check's output). A read that comes after its warm ended, from work the // warm left behind, is a hook's read, so the global inputs stay those of - // the warm itself. So is what a later warm reads that the first did not - // (a context that replaces one cut off by a hang): the global inputs are - // those of the session's first check (`warmed`), and stay one set. - let warmed = false + // the warm itself. const warmReads = new Map() const hookReads = new Map() const wrote = new Set() @@ -517,14 +514,8 @@ export async function openSession(pkg) { watchReads((key, write) => { const at = reading.getStore() if (write && key.startsWith(`env:`)) wrote.add(key) - const reads = at?.hook || at?.done || warmed ? hookReads : warmReads - if ( - at === undefined || - key === at.module || - reads.has(key) || - warmReads.has(key) - ) - return + const reads = at?.hook || at?.done ? hookReads : warmReads + if (at === undefined || key === at.module || reads.has(key)) return if (write) wrote.add(key) else if (!wrote.has(key)) reads.set(key, key.startsWith(`fs:`) ? fileHash(key.slice(3)) : null) @@ -1734,7 +1725,6 @@ export default async (env) => { options.mutantLimit, ]), ) - warmed = true // How the evidence was produced: units reused and computed, runs cut off // at their time limit or for idleness (of them, `idle`), items rerun // after a cut-off batch, and mutants that changed no value and so needed From c19bc40cb8107ccc5225995d0f3c3f0d1bd1727b Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Mon, 16 Nov 2026 16:06:15 +0000 Subject: [PATCH 12/34] test(oracle-gaps): place the daemon-input units in the e2e shard partition Co-authored-by: Isaac --- packages/oracles/scripts/e2e-shards.mjs | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/packages/oracles/scripts/e2e-shards.mjs b/packages/oracles/scripts/e2e-shards.mjs index 50b8a6b9..1dd43aa1 100644 --- a/packages/oracles/scripts/e2e-shards.mjs +++ b/packages/oracles/scripts/e2e-shards.mjs @@ -104,6 +104,26 @@ export const shards = { `fixed seed 20261105: an edit to data a test reads through fs (statDir)`, `random seed: an edit to data a test reads through fs (statDir)`, `determinism: constructed history: an edit to data a test reads through fs (statDir)`, + // The daemon-input histories (law 9, every read is a daemon input): about + // 25 s each on the Arca pool, fixed seed. + `fixed seed 20261105: an edit to a file in the package that keeps its size and modification time`, + `random seed: an edit to a file in the package that keeps its size and modification time`, + `determinism: constructed history: an edit to a file in the package that keeps its size and modification time`, + `fixed seed 20261105: an edit to a file outside the package that a test reads`, + `random seed: an edit to a file outside the package that a test reads`, + `determinism: constructed history: an edit to a file outside the package that a test reads`, + `fixed seed 20261105: an edit to a file under node_modules that a test reads`, + `random seed: an edit to a file under node_modules that a test reads`, + `determinism: constructed history: an edit to a file under node_modules that a test reads`, + `fixed seed 20261105: an edit to an environment variable that a test reads`, + `random seed: an edit to an environment variable that a test reads`, + `determinism: constructed history: an edit to an environment variable that a test reads`, + `fixed seed 20261105: an edit to a file the config's plugin reads when the config resolves`, + `random seed: an edit to a file the config's plugin reads when the config resolves`, + `determinism: constructed history: an edit to a file the config's plugin reads when the config resolves`, + `fixed seed 20261105: an edit to a file the config's plugin reads when it transforms a test`, + `random seed: an edit to a file the config's plugin reads when it transforms a test`, + `determinism: constructed history: an edit to a file the config's plugin reads when it transforms a test`, // Added with the CLI's parent-config discovery (not yet measured). `fixed seed 20261105: a package whose parent directory has its config`, `random seed: test.projects in a parent's config`, From 2f2769fe54e0acc416cae23fe17914abb8b5f3f8 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Tue, 17 Nov 2026 11:34:48 +0000 Subject: [PATCH 13/34] test(oracle-gaps): a directory listing a test reads is a daemon input, oracle first Two more gate kinds (G42's listing family): file b reads its gate as the one file name in tests/gate-dir, by readdirSync (listing) or opendirSync (opendir); the edit renames that file, so no file's text changes. One constructed history each, appended last. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-model-oracle.mjs | 23 +++++++++++++++++-- .../gap-report-oracle.property.test.mjs | 16 ++++++++++++- .../oracle-gaps/history-fingerprint.json | 4 ++-- packages/oracles/scripts/e2e-shards.mjs | 6 +++++ packages/oracles/scripts/pr-shards.mjs | 4 ++++ 5 files changed, 48 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 6196ed39..19c1e7da 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -883,8 +883,12 @@ const drawn = fc.record({ // variable GAP_INPUT_GATE (`env`); or a file the config's own plugin // reads, once when the config resolves (`pluginConfig`) or each time it // transforms a test file (`pluginTransform`), and writes into the test's - // text. These fields change what a history runs, so they are drawn - // (maintainer decision, 2026-11-16, "Randomness wins"), and last. + // text; or the listing of a directory of the package's tests, which holds + // one empty file named `open` or `shut`, read by `readdirSync` + // (`listing`) or by `opendirSync` (`opendir`): the edit renames that file, + // so no file's text changes. These fields change what a history runs, so + // they are drawn (maintainer decision, 2026-11-16, "Randomness wins"), and + // last. inputRead: fc.constantFrom( `none`, `none`, @@ -895,6 +899,8 @@ const drawn = fc.record({ `env`, `pluginConfig`, `pluginTransform`, + `listing`, + `opendir`, ), // Each write of a gate file keeps its size (`open` and `shut` have one // length) and gets back one fixed modification time, as `cp -p`, `rsync @@ -4840,6 +4846,14 @@ const inputReads = { pluginTransform: [ `const readInput = async () => ({ open: __GAP_INPUT_GATE__ === 'open' })`, ], + listing: [ + `import { readdirSync as listGate } from 'node:fs'`, + `const readInput = async () => ({ open: listGate(new URL('./gate-dir/', import.meta.url)).includes('open') })`, + ], + opendir: [ + `import { opendirSync as openGate } from 'node:fs'`, + `const readInput = async () => { const dir = openGate(new URL('./gate-dir/', import.meta.url)); const names: Array = []; for (let entry = dir.readSync(); entry; entry = dir.readSync()) names.push(entry.name); dir.closeSync(); return { open: names.includes('open') } }`, + ], } /** The variables a check of `state` runs with: the gate's, under `env`. */ const inputEnv = (plan, state) => @@ -5656,6 +5670,11 @@ function fixtureFiles(plan, state = initialState(plan)) { : {}), // The gate file, which under `keepStamp` gets back one modification // time each time it is written. + // The gate directory of a listing, which holds one empty file, named + // by the gate's word. + ...(plan.inputRead === `listing` || plan.inputRead === `opendir` + ? { [`tests/gate-dir/${state.inputOpen ? `open` : `shut`}`]: `` } + : {}), ...(gateFiles[plan.inputRead] === undefined ? {} : { 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 85b7ea04..33ebf2bd 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1876,7 +1876,11 @@ async function incremental(dir, plan, cli, copy, observe, states) { states.add( `an edit to the ${plan.inputRead} gate input changed the cold result`, ) - if (plan.keepStamp && plan.inputRead !== `env`) + // Only a gate file keeps its stamp; a listing's edit renames a file. + if ( + plan.keepStamp && + ![`env`, `listing`, `opendir`].includes(plan.inputRead) + ) states.add( `an edit that kept a file's size and modification time changed the cold result`, ) @@ -4427,6 +4431,8 @@ const inputKinds = [ `env`, `pluginConfig`, `pluginTransform`, + `listing`, + `opendir`, ] // Law 9's states that a constructed history of their own reaches, not the // edit sequence: the mid-run edit, and an edit to data a test reads through @@ -6330,6 +6336,14 @@ oracleProperty({ `pluginTransform`, true, ], + // A directory's listing, by readdirSync and by opendirSync: the edit + // renames the one file in it. + [`an edit to a directory listing that a test reads`, `listing`, false], + [ + `an edit to a directory a test reads through opendir`, + `opendir`, + false, + ], ].map(([name, inputRead, keepStamp]) => ({ name, enters: [ diff --git a/packages/oracles/oracle-gaps/history-fingerprint.json b/packages/oracles/oracle-gaps/history-fingerprint.json index 1dca6243..47f848b4 100644 --- a/packages/oracles/oracle-gaps/history-fingerprint.json +++ b/packages/oracles/oracle-gaps/history-fingerprint.json @@ -58,7 +58,7 @@ ["testRoot", "e18db063421a75f1"], ["loadPlugin", "ed6866229ecc4969"], ["rejectBatch", "e5386ea9402dd268"], - ["inputRead", "a90da00463cd4e9a"], + ["inputRead", "767787b6ef3d2628"], ["keepStamp", "45ab5c81233b3182"], ["inputSteps", "655fde9118d2e219"] ], @@ -121,7 +121,7 @@ ["testRoot", "e18db063421a75f1"], ["loadPlugin", "ed6866229ecc4969"], ["rejectBatch", "e5386ea9402dd268"], - ["inputRead", "a90da00463cd4e9a"], + ["inputRead", "767787b6ef3d2628"], ["keepStamp", "45ab5c81233b3182"], ["inputSteps", "655fde9118d2e219"] ] diff --git a/packages/oracles/scripts/e2e-shards.mjs b/packages/oracles/scripts/e2e-shards.mjs index a4718c35..54fe2da4 100644 --- a/packages/oracles/scripts/e2e-shards.mjs +++ b/packages/oracles/scripts/e2e-shards.mjs @@ -124,6 +124,12 @@ export const shards = { `fixed seed 20261105: an edit to a file the config's plugin reads when it transforms a test`, `random seed: an edit to a file the config's plugin reads when it transforms a test`, `determinism: constructed history: an edit to a file the config's plugin reads when it transforms a test`, + `fixed seed 20261105: an edit to a directory listing that a test reads`, + `random seed: an edit to a directory listing that a test reads`, + `determinism: constructed history: an edit to a directory listing that a test reads`, + `fixed seed 20261105: an edit to a directory a test reads through opendir`, + `random seed: an edit to a directory a test reads through opendir`, + `determinism: constructed history: an edit to a directory a test reads through opendir`, // Added with the CLI's parent-config discovery (not yet measured). `fixed seed 20261105: a package whose parent directory has its config`, `random seed: test.projects in a parent's config`, diff --git a/packages/oracles/scripts/pr-shards.mjs b/packages/oracles/scripts/pr-shards.mjs index 89007eca..88d0e0f6 100644 --- a/packages/oracles/scripts/pr-shards.mjs +++ b/packages/oracles/scripts/pr-shards.mjs @@ -35,6 +35,8 @@ const daemonInputUnits = [ 'an edit to an environment variable that a test reads', "an edit to a file the config's plugin reads when the config resolves", "an edit to a file the config's plugin reads when it transforms a test", + 'an edit to a directory listing that a test reads', + 'an edit to a directory a test reads through opendir', ] const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, `\\$&`) const anyOf = (names) => `(?:${names.map(escape).join(`|`)})` @@ -599,6 +601,8 @@ export const partitions = { 'a declaration fault: configNull', daemonInputUnits[4], daemonInputUnits[5], + daemonInputUnits[6], + daemonInputUnits[7], ]), 10: anyOf([ 'an edit that changed the cold result after a hang replaced the only context', From a5afad40a37ec5cd6f2158ccd1d02a0e00c87385 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Tue, 17 Nov 2026 11:35:56 +0000 Subject: [PATCH 14/34] fix(oracle-gaps): a directory listing a test reads is a daemon input readdir, readdirSync, opendir and opendirSync, and the fs/promises readdir and opendir, are inputs keyed by the listing they name (dir:, or dirs: for a recursive one), hashed by each entry's name and kind (G42's listing family). Vitest's own listing to find test files while a context warms is no input: each check finds its test files again. Co-authored-by: Isaac --- .../oracles/oracle-gaps/capture-setup.mjs | 4 +- packages/oracles/oracle-gaps/check.mjs | 15 +++-- packages/oracles/oracle-gaps/inputs.mjs | 59 +++++++++++++++---- 3 files changed, 62 insertions(+), 16 deletions(-) diff --git a/packages/oracles/oracle-gaps/capture-setup.mjs b/packages/oracles/oracle-gaps/capture-setup.mjs index c31dd561..64151551 100644 --- a/packages/oracles/oracle-gaps/capture-setup.mjs +++ b/packages/oracles/oracle-gaps/capture-setup.mjs @@ -28,7 +28,7 @@ import { appendFileSync, readFileSync } from 'node:fs' import { createRequire, syncBuiltinESMExports } from 'node:module' import { dirname, isAbsolute, join } from 'node:path' import { afterAll, beforeEach, chai, expect, inject, vi } from 'vitest' -import { fileHash, keepProperties, watchReads } from './inputs.mjs' +import { inputHash, keepProperties, watchReads } from './inputs.mjs' import { writeWhole } from './paths.mjs' const run = @@ -285,7 +285,7 @@ watchReads((key, write) => { const reads = globalThis.__oracleGapsReads if (write) wrote.add(key) else if (!reads.has(key) && !wrote.has(key)) - reads.set(key, key.startsWith(`fs:`) ? fileHash(key.slice(3)) : null) + reads.set(key, key.startsWith(`env:`) ? null : inputHash(key)) }) // A test's own writes to the process's stdout and stderr (a debugging // `process.stdout.write`) go to the run's test-output.log, beside its diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index 8757bb23..acb9e51d 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -79,7 +79,7 @@ import { specifierOf, } from './paths.mjs' import { stateDirOf } from './evidence.mjs' -import { envHash, fileHash, watchReads } from './inputs.mjs' +import { envHash, inputHash, watchReads } from './inputs.mjs' import { baselineOf, blockedOr, @@ -517,9 +517,13 @@ export async function openSession(pkg) { if (write && key.startsWith(`env:`)) wrote.add(key) const reads = at?.hook || at?.done ? hookReads : warmReads if (at === undefined || key === at.module || reads.has(key)) return + // Vitest lists the package's directories to find its test files, which + // each check does again (specsOf), so a warm's listing is no input; a + // plugin hook's listing is. + if (reads === warmReads && /^dirs?:/.test(key)) return if (write) wrote.add(key) else if (!wrote.has(key)) - reads.set(key, key.startsWith(`fs:`) ? fileHash(key.slice(3)) : null) + reads.set(key, key.startsWith(`env:`) ? null : inputHash(key)) }) // Runs `work` as a warm under `reading`. const warming = async (work) => { @@ -683,8 +687,11 @@ export default async (env) => { // module by the text that its context serves. const servedHash = (path, index) => { if (path.startsWith(`fs:`)) return hashOf(path.slice(3)) - // A variable by its value in the environment this check runs under. + // A variable by its value in the environment this check runs under, and + // a directory by its listing now. if (path.startsWith(`env:`)) return envHash(path.slice(4)) + if (path.startsWith(`dir:`) || path.startsWith(`dirs:`)) + return inputHash(path) const text = globalThis.__oracleGapsServe[index]?.get(path) ?? globalThis.__oracleGapsSchemata.get(path) @@ -2766,7 +2773,7 @@ export default async (env) => { */ const inputsChanged = () => [...warmReads, ...hookReads].some( - ([key, hash]) => key.startsWith(`fs:`) && fileHash(key.slice(3)) !== hash, + ([key, hash]) => !key.startsWith(`env:`) && inputHash(key) !== hash, ) return { check, close, inputsChanged } } diff --git a/packages/oracles/oracle-gaps/inputs.mjs b/packages/oracles/oracle-gaps/inputs.mjs index bd3f8f03..517c7b02 100644 --- a/packages/oracles/oracle-gaps/inputs.mjs +++ b/packages/oracles/oracle-gaps/inputs.mjs @@ -6,9 +6,10 @@ // CLI oracle's law 9). // // An input's key is `fs:` for a file, hashed by its text (or as -// `not a file`, or `missing`), `env:` for a variable, hashed by its -// value, or `env:*` for the set of names, which code reads when it lists -// the environment. The harness (capture-setup.mjs) watches a test's reads in +// `not a file`, or `missing`), `dir:` for a directory's listing, +// hashed by its entries' names and kinds, or `dirs:` for a recursive +// one, `env:` for a variable, hashed by its value, or `env:*` for the +// set of names, which code reads when it lists the environment. The harness (capture-setup.mjs) watches a test's reads in // its worker, and the session (check.mjs) watches what the config and its // plugins read in the CLI's process. Both files are copied beside the // harness with this one. @@ -26,6 +27,11 @@ const reads = [ [fs, [`readFileSync`, `readFile`, `existsSync`, `statSync`]], [fs.promises, [`readFile`, `stat`]], ] +// The calls that list a directory. +const listings = [ + [fs, [`readdirSync`, `readdir`, `opendirSync`, `opendir`]], + [fs.promises, [`readdir`, `opendir`]], +] // The calls that write a file's text. A file that a reader wrote before it // reads it holds the reader's own output, which follows from the reader's // other inputs, so that read is no input: a test's temporary file, or the @@ -37,6 +43,7 @@ const writes = [ const original = (globalThis.__oracleGapsOriginalFs ??= { readFileSync: fs.readFileSync, statSync: fs.statSync, + readdirSync: fs.readdirSync, realpathSync: fs.realpathSync.native, }) const sha1 = (data) => createHash(`sha1`).update(data).digest(`hex`) @@ -56,6 +63,35 @@ export function fileHash(path) { } } +/** + * A directory's input hash now: that of its entries' names and kinds, every + * level's for a recursive listing, or `not a directory`, or `missing`. + */ +function listingHash(path, recursive) { + try { + return sha1( + original + .readdirSync(path, { withFileTypes: true, recursive }) + .map( + (entry) => + `${posix(entry.parentPath ?? path)}/${entry.name}\0${entry.isDirectory() ? `d` : entry.isSymbolicLink() ? `l` : `f`}`, + ) + .sort() + .join(`\0`), + ) + } catch (error) { + return error?.code === `ENOTDIR` ? `not a directory` : `missing` + } +} + +/** A file's or a directory's input hash now, by its key. */ +export const inputHash = (key) => + key.startsWith(`fs:`) + ? fileHash(key.slice(3)) + : key.startsWith(`dirs:`) + ? listingHash(key.slice(5), true) + : listingHash(key.slice(4), false) + /** A variable's input hash under `env`, or for `*`, that of its names. */ export const envHash = (name, env = process.env) => sha1( @@ -97,17 +133,19 @@ export function watchReads(record) { if (globalThis.__oracleGapsWatching) return globalThis.__oracleGapsWatching = true record = (key, write) => globalThis.__oracleGapsRecord(key, write) - const watched = (target, write) => { + const watched = (target, kind, options) => { + const write = kind === `write` let path try { - if (target instanceof URL) path = fileURLToPath(target) + if (target instanceof URL) path = resolve(fileURLToPath(target)) else if (typeof target === `string`) path = resolve(target) else if (Buffer.isBuffer(target)) path = resolve(target.toString()) } catch { return } if (path === undefined || isRunnerFile(posix(path))) return - record(`fs:${posix(path)}`, write) + const prefix = kind !== `list` ? `fs` : options?.recursive ? `dirs` : `dir` + record(`${prefix}:${posix(path)}`, write) // A written file is also known by its directory's real path, which a // later read through a link, or an import by its real URL, names. if (write) @@ -120,15 +158,16 @@ export function watchReads(record) { // No directory to write in: the write fails as it would. } } - for (const [calls, write] of [ - [reads, false], - [writes, true], + for (const [calls, kind] of [ + [reads, `read`], + [listings, `list`], + [writes, `write`], ]) for (const [owner, names] of calls) for (const name of names) { const call = owner[name] owner[name] = keepProperties(call, function (target, ...rest) { - watched(target, write) + watched(target, kind, rest[0]) return call.call(this, target, ...rest) }) } From 164831b76d05860df1e836ffa5dc4ba317064b34 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Tue, 17 Nov 2026 12:02:17 +0000 Subject: [PATCH 15/34] test(oracle-gaps): a file a test reads through a stream is a daemon input, oracle first One more gate kind (stream): file b reads tests/gate.json through createReadStream, and its edit keeps the file's size and mtime. One constructed history, appended last (#140). Co-authored-by: Isaac --- packages/oracles/oracle-gaps/gap-report-model-oracle.mjs | 9 ++++++++- .../oracle-gaps/gap-report-oracle.property.test.mjs | 4 ++++ packages/oracles/oracle-gaps/history-fingerprint.json | 4 ++-- packages/oracles/scripts/e2e-shards.mjs | 3 +++ packages/oracles/scripts/pr-shards.mjs | 2 ++ 5 files changed, 19 insertions(+), 3 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index 0bb480d8..d1312ffa 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -983,7 +983,8 @@ const drawn = fc.record({ // text; or the listing of a directory of the package's tests, which holds // one empty file named `open` or `shut`, read by `readdirSync` // (`listing`) or by `opendirSync` (`opendir`): the edit renames that file, - // so no file's text changes. These fields change what a history runs, so + // so no file's text changes; or the package's gate file read through a + // stream (`stream`, createReadStream). These fields change what a history runs, so // they are drawn (maintainer decision, 2026-11-16, "Randomness wins"), and // last. inputRead: fc.constantFrom( @@ -998,6 +999,7 @@ const drawn = fc.record({ `pluginTransform`, `listing`, `opendir`, + `stream`, ), // Each write of a gate file keeps its size (`open` and `shut` have one // length) and gets back one fixed modification time, as `cp -p`, `rsync @@ -4984,6 +4986,7 @@ const BESIDE = `/` const outsideOf = (dir) => `${dir}.outside` const gateFiles = { inside: `tests/gate.json`, + stream: `tests/gate.json`, outside: `${BESIDE}gate.json`, module: `node_modules/gap-gate/gate.json`, pluginConfig: `tests/plugin-gate.json`, @@ -5032,6 +5035,10 @@ const inputReads = { pluginTransform: [ `const readInput = async () => ({ open: __GAP_INPUT_GATE__ === 'open' })`, ], + stream: [ + `import { createReadStream as streamGate } from 'node:fs'`, + `const readInput = async () => { const chunks: Array = []; for await (const chunk of streamGate(new URL('./gate.json', import.meta.url))) chunks.push(chunk as Buffer); return { open: JSON.parse(Buffer.concat(chunks).toString('utf8')).gate === 'open' } }`, + ], listing: [ `import { readdirSync as listGate } from 'node:fs'`, `const readInput = async () => ({ open: listGate(new URL('./gate-dir/', import.meta.url)).includes('open') })`, 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 e1a3d994..579414d9 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -5415,6 +5415,7 @@ const inputKinds = [ `pluginTransform`, `listing`, `opendir`, + `stream`, ] // Law 9's states that a constructed history of their own reaches, not the // edit sequence: the mid-run edit, and an edit to data a test reads through @@ -7975,6 +7976,9 @@ oracleProperty({ `opendir`, false, ], + // The package's gate file read through a stream, written back with + // its size and modification time. + [`an edit to a file a test reads through a stream`, `stream`, true], ].map(([name, inputRead, keepStamp]) => ({ name, enters: [ diff --git a/packages/oracles/oracle-gaps/history-fingerprint.json b/packages/oracles/oracle-gaps/history-fingerprint.json index 4e83d699..5dc606c4 100644 --- a/packages/oracles/oracle-gaps/history-fingerprint.json +++ b/packages/oracles/oracle-gaps/history-fingerprint.json @@ -71,7 +71,7 @@ ["supervisorDeath", "ed6866229ecc4969"], ["unsupervised", "ed6866229ecc4969"], ["psMissing", "e6ef4bc292a3990d"], - ["inputRead", "3c41fc8568963e89"], + ["inputRead", "992c868c7f5164a0"], ["keepStamp", "06892edd24057352"], ["inputSteps", "a7805625269c7a5f"] ], @@ -147,7 +147,7 @@ ["supervisorDeath", "ed6866229ecc4969"], ["unsupervised", "ed6866229ecc4969"], ["psMissing", "e6ef4bc292a3990d"], - ["inputRead", "3c41fc8568963e89"], + ["inputRead", "992c868c7f5164a0"], ["keepStamp", "06892edd24057352"], ["inputSteps", "a7805625269c7a5f"] ] diff --git a/packages/oracles/scripts/e2e-shards.mjs b/packages/oracles/scripts/e2e-shards.mjs index cea11351..36d40d75 100644 --- a/packages/oracles/scripts/e2e-shards.mjs +++ b/packages/oracles/scripts/e2e-shards.mjs @@ -140,6 +140,9 @@ export const shards = { `fixed seed 20261105: an edit to a directory a test reads through opendir`, `random seed: an edit to a directory a test reads through opendir`, `determinism: constructed history: an edit to a directory a test reads through opendir`, + `fixed seed 20261105: an edit to a file a test reads through a stream`, + `random seed: an edit to a file a test reads through a stream`, + `determinism: constructed history: an edit to a file a test reads through a stream`, // Added with the CLI's parent-config discovery (not yet measured). `fixed seed 20261105: a package whose parent directory has its config`, `random seed: test.projects in a parent's config`, diff --git a/packages/oracles/scripts/pr-shards.mjs b/packages/oracles/scripts/pr-shards.mjs index 247ba14e..dc58812f 100644 --- a/packages/oracles/scripts/pr-shards.mjs +++ b/packages/oracles/scripts/pr-shards.mjs @@ -37,6 +37,7 @@ const daemonInputUnits = [ "an edit to a file the config's plugin reads when it transforms a test", 'an edit to a directory listing that a test reads', 'an edit to a directory a test reads through opendir', + 'an edit to a file a test reads through a stream', ] const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, `\\$&`) const anyOf = (names) => `(?:${names.map(escape).join(`|`)})` @@ -628,6 +629,7 @@ export const partitions = { daemonInputUnits[5], daemonInputUnits[6], daemonInputUnits[7], + daemonInputUnits[8], ]), 10: anyOf([ 'an edit that changed the cold result after a hang replaced the only context', From e4fa41e118045b4c600e9b39b29d90c5e8b12e39 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Tue, 17 Nov 2026 12:29:32 +0000 Subject: [PATCH 16/34] fix(oracle-gaps): a file a test reads through a stream is a daemon input createReadStream is one of the reads, keyed by the whole file (#140). The README and the oracle's limits name the families still open: fd reads (#141), link targets and the stat family (#142), and worker threads and child processes (#143). Fixes #140 Co-authored-by: Isaac --- .changeset/gap-cli-daemon-every-read.md | 2 +- README.md | 22 +++++++++---------- .../gap-report-oracle.property.test.mjs | 2 +- packages/oracles/oracle-gaps/inputs.mjs | 12 ++++++---- 4 files changed, 21 insertions(+), 17 deletions(-) diff --git a/.changeset/gap-cli-daemon-every-read.md b/.changeset/gap-cli-daemon-every-read.md index c38c4416..40d04a43 100644 --- a/.changeset/gap-cli-daemon-every-read.md +++ b/.changeset/gap-cli-daemon-every-read.md @@ -2,7 +2,7 @@ '@tanstack/oracles': patch --- -A check through `--daemon` now treats every read as an input of the runs that made it, so after any of these changes it reports what a cold run reports. Before, the daemon reused a run that read the old input. The new inputs are a file that a test reads through `fs` outside the package or under `node_modules`; an environment variable that a test reads (or the set of variable names, when a test lists them); and a file or variable that Vitest, the Vite config, or one of the config's own plugins reads while it loads or in one of its hooks, such as a sidecar file that a plugin writes into the code it transforms. +A check through `--daemon` now treats every read as an input of the runs that made it, so after any of these changes it reports what a cold run reports. Before, the daemon reused a run that read the old input. The new inputs are a file that a test reads through `fs` outside the package or under `node_modules`, or through `createReadStream`; a directory that a test lists (`readdir`, `opendir`, and their sync and `fs/promises` forms), by its entries; an environment variable that a test reads (or the set of variable names, when a test lists them); and a file or variable that Vitest, the Vite config, or one of the config's own plugins reads while it loads or in one of its hooks, such as a sidecar file that a plugin writes into the code it transforms. The daemon now runs each check in the environment of the CLI that asked for it. A check from another environment, or after a file that the config or a plugin read has changed, starts a new daemon, which still reuses every stored run whose inputs are unchanged. diff --git a/README.md b/README.md index ade8882f..ec00b4b4 100644 --- a/README.md +++ b/README.md @@ -227,8 +227,11 @@ exited with ` and exits 3; after an out-of-memory crash Every read is an input (maintainer decision, 2026-11-16): the modules the run loaded; the files its tests read through `fs` on any path, inside the package or outside it, `node_modules` included (`readFileSync`, - `readFile`, `existsSync`, `statSync`, and `fs/promises` `readFile` and - `stat`), each by the content that the run read; the environment variables + `readFile`, `createReadStream`, `existsSync`, `statSync`, and + `fs/promises` `readFile` and `stat`), each by the content that the run + read; the directories its tests list (`readdir`, `readdirSync`, `opendir`, + `opendirSync`, and `fs/promises` `readdir` and `opendir`), each by its + entries' names and kinds; the environment variables its tests read, by value, or all of them when a test lists them; and what Vitest, the Vite config, and the config's own plugins read in the CLI's process while it loads them and in each plugin hook. Each check hashes @@ -246,15 +249,12 @@ exited with ` and exits 3; after an out-of-memory crash These reads are no input yet, so an edit to the file alone does not rerun the tests that read it: a read from a worker thread or child process that - the test starts; and a read through any `fs` or `fs/promises` function - other than the six above, or through one of those six given a file - descriptor. That catch-all includes, for example, `readdir`, `opendir`, - `glob`, `globSync`, `createReadStream`, `realpath`, `lstat`, `access`, - `open`, `read`, `readSync`, `readv`, `fstat`, `fstatSync`, `copyFile`, - `copyFileSync`, `cp`, `cpSync`, `openAsBlob`, `statfs`, `readlink`, the - callback `stat`, `exists`, `watch`, and `watchFile`, and the `fs/promises` - `readdir`, `opendir`, `glob`, `lstat`, `realpath`, `readlink`, `access`, - `open`, `copyFile`, `cp`, `statfs`, and `watch`. Run the check cold + the test starts (#143); a read through a file descriptor, after `open`, + `openSync`, or the `fs/promises` `open` (#141); a link's target, or the + rest of the stat family, `lstat`, `readlink`, `realpath`, `access`, the + callback `stat`, and `exists` (#142); and `glob`, `globSync`, `copyFile`, + `copyFileSync`, `cp`, `cpSync`, `openAsBlob`, `statfs`, and the + `fs/promises` `glob`, `copyFile`, `cp`, and `statfs`. Run the check cold (without `--daemon`) after an edit to a file read that way. A later release records all of them except `watch` and `watchFile`, which wait for future changes and stay no input (maintainer decision, 2026-11-13, with 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 579414d9..6dc6c326 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -5885,7 +5885,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. 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 the stream law (law 15) on both streams, as for any run, so its error line and its done line carry the prefix, and no other line does not, which the state \`a run ended in an internal error\` declares; then exit 3 with an internal error's done line last on both streams, no stack frame on stderr, and an error.log in its output directory. What the error.log's stack says is not judged. An internal error that no fault constructs is a completion failure, reported before the stream law; an internal error through the daemon is reached by no history, and its ending is the same function's (endRun), by inspection. The internal error's lines follow the register's C entry "The internal-error line" (2026-11-16): the general law (endsBreach) owes every run that ends through endRun one error line on stderr naming the done line's log, the output directory's error.log, and none on stdout, and owes the supervisor's own exit 3 none. The message's escape is witnessed by the fault's message, which holds a line break and a forged done line after it; the log path's escape only on POSIX, where the rejected batch's output directory holds a line break (a name on win32 cannot). Paths in a completed run's lines (the results note, the done line's report, the test-output note) are escaped the same way, by inspection: no completed history names such a directory. P10's exempt lines (v21.2 P10 and I3) are read by their own shapes (exemptBlocks), never by indentation alone: a baseline failure's indented details, a refusal's block, Node's warning with its \`--trace-warnings\` frames and its hint, V8's fatal block, esbuild's message block, and Vite's own \`[vite]\` line. The V8, traced-warning, and esbuild blocks are calibrated beside our own line with no prefix (the stream calibrations put them before the rejected-batch run's done line, and the law must name our line alone); no generated history prints any of them or a Vite line, and a shape of those tools that exemptBlocks does not name is read as a stray. The stdout summary's exemption is unused and not exercised: the CLI prefixes every summary line (its summary, legend, and function kinds). \`--help\` prints its usage text with no prefix and no done line, exempt by the register's M entry "\`--help\` is exempt" (2026-11-16), and the static oracle's Help law owes exactly that text; \`--stop-daemon\` prints nothing and exits 0, read the same way as a command outside the run protocol (C, pending ratification), and this oracle runs it without observing its streams. A syntax error in a module that the config imports lets the esbuild that Vite bundles configs with print its block before the refusal (trace, Vite 7.3.7, esbuild 0.28.2: \`✘ [ERROR] Unexpected end of file\`, an empty line, \` helper.ts:2:0:\`, the code frame, then the refused block): its lines are exempt by the register's M entry "Other tools' output is exempt" (2026-11-16), the refusal and the done line around them keep the prefix, and no history generates it. 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, which owes its done line as any stop does (no history sends a win32 child.kill, the SIGKILL-equivalent that owes none); every SIGINT state stays required on win32. A stop as the CLI starts lands only in one of two holds: the driver's own preload before the CLI's first statement (outcome a, nothing written; POSIX only, since its witness is a signal's default action), or the CLI's hold after its started marker, which the stop the CLI keeps releases (outcome b, judged only when the supervisor started no child); a stop during Node's own start between the two is not generated, since its outcome follows timing. The drawn spawn delay is a wait inside a hold, so it cannot move a stop out of it. Stop runs that land while the config warms (ORACLE_GAPS_TEST_WARM_PROBE) are still drawn, and on win32 every drawn stop goes through ORACLE_GAPS_TEST_STOP: each is a test-only hook that a drawn field switches, main's pattern, which the review of #57 (A3) brought to the maintainer; only the stop after the completed line (ORACLE_GAPS_TEST_HOLD_UNTIL) was made constructed-only. A missing \`ps\` is generated only as a PATH that names no command, on POSIX, where the run is supervised. The unsupervised path (stopNow, every win32 stop) is reached on POSIX by one constructed history whose stop is held at the run's note, before the check starts a process: an unsupervised POSIX run has no group to end, so a stop while the witness's test spins leaves that test's own child (measured; C 2026-11-13, Windows (e)), which win32 ends with the job object libuv puts its children in. 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. Law 15's stdout gap lines are judged against each completed run's own results.json, by id: the cold run, and each check through the daemon (every step's check and the check that a mid-run edit overlaps); a stopped run and a refusal list no gaps and are not judged so. A line's change is read loosely: its code on one line, whole or cut after a kept part and ended with \`...\`; where the printer cuts (60 code points, kept 57) is the classify oracle's law 8 (\`shortened\`), in-process. A line with any text after its change does not read and fails loudly: the \` (cause: )\` suffix that #99 adds to timeout lines is not read yet, so whichever of #99 and #115 lands second extends readGapLine. 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) and, in one constructed history, a plugin whose load reads each test file with a sync read (loadPlugin); and the gate plugin (inputRead pluginConfig or pluginTransform), which reads a sidecar file of the package once when the config resolves or in each transform of a test file, and writes its word into the test's text (maintainer decision, 2026-11-16, "Every read is a daemon input": every plugin input is a daemon input); a plugin that reads an environment variable, enumerates the environment, or reads through another fs API than the six below is not generated; and test.projects only as a refusal, and only under the package's own package.json; the supervisor-death state is required and entered only off win32: win32 has no supervisor until #79, so there the state is not reached and its history is not judged (platform-scoped reach; the win32 run is unsupervised, which register C entry (e) of #58 records as not guaranteeing that no process outlives the CLI); a config's test.root only in four shapes, each in one constructed history of an ES module config that Vitest discovers, with one owner and one context, where the test files' globs and the setup file are relative to the root (issue #101): the directory that holds the tests, the directory above the package, a directory of the package that holds no test file, and the package's tests as a symbolic link to the directory that holds them (required on every platform, since Windows creates the link as the driver's other links); not under --config, a CommonJS config, test.projects, several contexts with different roots, or a root that is the filesystem's root; the runner serves each copy of a test file by its absolute path, through its pre plugin's load (which answers before the config's own plugins) and through its read of the copy's path for Vitest's pragma read (serveCopies), and histories run copies only in Vite's server environments (node and the pragma's ssr environment): jsdom and happy-dom, Vite's client environment, are not generated (the #103 merge-gate review ran jsdom by hand under all five root shapes, and the copies loaded in each); 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; every read is a daemon input (maintainer decision, 2026-11-16, "All of them"), on any path and under node_modules too, with no package-boundary exception: the gate input (inputRead) is a JSON file that file b's verdict reads with a sync read in the package's tests, beside the package and outside it, or in a package under its node_modules, or the variable GAP_INPUT_GATE, or the gate plugin's sidecar file, and the inputGate edit flips only that input, drawn (maintainer decision, 2026-11-16, "Randomness wins") and in one constructed history per kind; a read from a worker thread or a child process that a test starts, an enumeration of the environment by a test (it is an input as the set of names, and not generated), or a read 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; a gate file's edits may keep its size and get back one fixed modification time (keepStamp), as cp -p, rsync -t, or touch -r leave a file, in generated histories and in two constructed ones (the package's file and the plugin's sidecar), so a reuse decided by a file's size and modification time across checks is seen (D10); an edit that keeps both during a check is not generated; law 9's edits leave out environment variables other than the seed and the gate's, 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 here too: the default-directory histories (a stop, a daemon check, and the unsupervised daemon check) run without --out, and their directory is named in the trace; 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; a SIGKILL of a supervisor is witnessed on POSIX by the constructed history "a supervised child exits when its supervisor is killed" (its child exits within the watchdog tick), and a signal sent to the daemon is not witnessed here, 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; probe code is never work (maintainer decision, 2026-11-16), so the model and the capture count no probe-only site, and only a constructed history (a probe branch under a generated test's work bound) reaches a probe branch beside a bound: the fixed seeds' generated histories reach neither that state nor \`killed by a work bound in a generated function\`, which stays measured; work counts are observed only through a bound's ratio and a rise, never as numbers (v21.2 O1), so a counter that skips every site on a probe's line, which drops only the condition sites of an elseIf that run once on both sides, survives (mutant M6, equivalent under these observations), while one that skips every site of a function that holds probe code is killed (M7), 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 the stream law (law 15) on both streams, as for any run, so its error line and its done line carry the prefix, and no other line does not, which the state \`a run ended in an internal error\` declares; then exit 3 with an internal error's done line last on both streams, no stack frame on stderr, and an error.log in its output directory. What the error.log's stack says is not judged. An internal error that no fault constructs is a completion failure, reported before the stream law; an internal error through the daemon is reached by no history, and its ending is the same function's (endRun), by inspection. The internal error's lines follow the register's C entry "The internal-error line" (2026-11-16): the general law (endsBreach) owes every run that ends through endRun one error line on stderr naming the done line's log, the output directory's error.log, and none on stdout, and owes the supervisor's own exit 3 none. The message's escape is witnessed by the fault's message, which holds a line break and a forged done line after it; the log path's escape only on POSIX, where the rejected batch's output directory holds a line break (a name on win32 cannot). Paths in a completed run's lines (the results note, the done line's report, the test-output note) are escaped the same way, by inspection: no completed history names such a directory. P10's exempt lines (v21.2 P10 and I3) are read by their own shapes (exemptBlocks), never by indentation alone: a baseline failure's indented details, a refusal's block, Node's warning with its \`--trace-warnings\` frames and its hint, V8's fatal block, esbuild's message block, and Vite's own \`[vite]\` line. The V8, traced-warning, and esbuild blocks are calibrated beside our own line with no prefix (the stream calibrations put them before the rejected-batch run's done line, and the law must name our line alone); no generated history prints any of them or a Vite line, and a shape of those tools that exemptBlocks does not name is read as a stray. The stdout summary's exemption is unused and not exercised: the CLI prefixes every summary line (its summary, legend, and function kinds). \`--help\` prints its usage text with no prefix and no done line, exempt by the register's M entry "\`--help\` is exempt" (2026-11-16), and the static oracle's Help law owes exactly that text; \`--stop-daemon\` prints nothing and exits 0, read the same way as a command outside the run protocol (C, pending ratification), and this oracle runs it without observing its streams. A syntax error in a module that the config imports lets the esbuild that Vite bundles configs with print its block before the refusal (trace, Vite 7.3.7, esbuild 0.28.2: \`✘ [ERROR] Unexpected end of file\`, an empty line, \` helper.ts:2:0:\`, the code frame, then the refused block): its lines are exempt by the register's M entry "Other tools' output is exempt" (2026-11-16), the refusal and the done line around them keep the prefix, and no history generates it. 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, which owes its done line as any stop does (no history sends a win32 child.kill, the SIGKILL-equivalent that owes none); every SIGINT state stays required on win32. A stop as the CLI starts lands only in one of two holds: the driver's own preload before the CLI's first statement (outcome a, nothing written; POSIX only, since its witness is a signal's default action), or the CLI's hold after its started marker, which the stop the CLI keeps releases (outcome b, judged only when the supervisor started no child); a stop during Node's own start between the two is not generated, since its outcome follows timing. The drawn spawn delay is a wait inside a hold, so it cannot move a stop out of it. Stop runs that land while the config warms (ORACLE_GAPS_TEST_WARM_PROBE) are still drawn, and on win32 every drawn stop goes through ORACLE_GAPS_TEST_STOP: each is a test-only hook that a drawn field switches, main's pattern, which the review of #57 (A3) brought to the maintainer; only the stop after the completed line (ORACLE_GAPS_TEST_HOLD_UNTIL) was made constructed-only. A missing \`ps\` is generated only as a PATH that names no command, on POSIX, where the run is supervised. The unsupervised path (stopNow, every win32 stop) is reached on POSIX by one constructed history whose stop is held at the run's note, before the check starts a process: an unsupervised POSIX run has no group to end, so a stop while the witness's test spins leaves that test's own child (measured; C 2026-11-13, Windows (e)), which win32 ends with the job object libuv puts its children in. 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. Law 15's stdout gap lines are judged against each completed run's own results.json, by id: the cold run, and each check through the daemon (every step's check and the check that a mid-run edit overlaps); a stopped run and a refusal list no gaps and are not judged so. A line's change is read loosely: its code on one line, whole or cut after a kept part and ended with \`...\`; where the printer cuts (60 code points, kept 57) is the classify oracle's law 8 (\`shortened\`), in-process. A line with any text after its change does not read and fails loudly: the \` (cause: )\` suffix that #99 adds to timeout lines is not read yet, so whichever of #99 and #115 lands second extends readGapLine. 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) and, in one constructed history, a plugin whose load reads each test file with a sync read (loadPlugin); and the gate plugin (inputRead pluginConfig or pluginTransform), which reads a sidecar file of the package once when the config resolves or in each transform of a test file, and writes its word into the test's text (maintainer decision, 2026-11-16, "Every read is a daemon input": every plugin input is a daemon input); a plugin that reads an environment variable, enumerates the environment, or reads through another fs API than the six below is not generated; and test.projects only as a refusal, and only under the package's own package.json; the supervisor-death state is required and entered only off win32: win32 has no supervisor until #79, so there the state is not reached and its history is not judged (platform-scoped reach; the win32 run is unsupervised, which register C entry (e) of #58 records as not guaranteeing that no process outlives the CLI); a config's test.root only in four shapes, each in one constructed history of an ES module config that Vitest discovers, with one owner and one context, where the test files' globs and the setup file are relative to the root (issue #101): the directory that holds the tests, the directory above the package, a directory of the package that holds no test file, and the package's tests as a symbolic link to the directory that holds them (required on every platform, since Windows creates the link as the driver's other links); not under --config, a CommonJS config, test.projects, several contexts with different roots, or a root that is the filesystem's root; the runner serves each copy of a test file by its absolute path, through its pre plugin's load (which answers before the config's own plugins) and through its read of the copy's path for Vitest's pragma read (serveCopies), and histories run copies only in Vite's server environments (node and the pragma's ssr environment): jsdom and happy-dom, Vite's client environment, are not generated (the #103 merge-gate review ran jsdom by hand under all five root shapes, and the copies loaded in each); 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; every read is a daemon input (maintainer decision, 2026-11-16, "All of them"), on any path and under node_modules too, with no package-boundary exception: the gate input (inputRead) is a JSON file that file b's verdict reads with a sync read in the package's tests, beside the package and outside it, or in a package under its node_modules, or the variable GAP_INPUT_GATE, or the gate plugin's sidecar file, and the inputGate edit flips only that input, drawn (maintainer decision, 2026-11-16, "Randomness wins") and in one constructed history per kind; a read from a worker thread or a child process that a test starts, an enumeration of the environment by a test (it is an input as the set of names, and not generated), or a read through any other fs API than the six, createReadStream (the gate kind stream), and the listings of readdir and opendir (the gate kinds listing and opendir), which includes glob, globSync, 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 (issues #141 fd reads, #142 link targets and the stat family, #143 worker threads and child processes): 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; a gate file's edits may keep its size and get back one fixed modification time (keepStamp), as cp -p, rsync -t, or touch -r leave a file, in generated histories and in two constructed ones (the package's file and the plugin's sidecar), so a reuse decided by a file's size and modification time across checks is seen (D10); an edit that keeps both during a check is not generated; law 9's edits leave out environment variables other than the seed and the gate's, 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 here too: the default-directory histories (a stop, a daemon check, and the unsupervised daemon check) run without --out, and their directory is named in the trace; 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; a SIGKILL of a supervisor is witnessed on POSIX by the constructed history "a supervised child exits when its supervisor is killed" (its child exits within the watchdog tick), and a signal sent to the daemon is not witnessed here, 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; probe code is never work (maintainer decision, 2026-11-16), so the model and the capture count no probe-only site, and only a constructed history (a probe branch under a generated test's work bound) reaches a probe branch beside a bound: the fixed seeds' generated histories reach neither that state nor \`killed by a work bound in a generated function\`, which stays measured; work counts are observed only through a bound's ratio and a rise, never as numbers (v21.2 O1), so a counter that skips every site on a probe's line, which drops only the condition sites of an elseIf that run once on both sides, survives (mutant M6, equivalent under these observations), while one that skips every site of a function that holds probe code is killed (M7), 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/inputs.mjs b/packages/oracles/oracle-gaps/inputs.mjs index 517c7b02..a871b99a 100644 --- a/packages/oracles/oracle-gaps/inputs.mjs +++ b/packages/oracles/oracle-gaps/inputs.mjs @@ -20,11 +20,15 @@ import { basename, dirname, join, resolve } from 'node:path' import { fileURLToPath } from 'node:url' import { posix } from './paths.mjs' -// The calls that read a file, and those that test whether it exists and -// what it is. Each is taken once per process, before a wrapper replaces it, -// so hashing a file is not itself a read. +// The calls that read a file (a stream's too, by the whole file), and those +// that test whether it exists and what it is. Each is taken once per +// process, before a wrapper replaces it, so hashing a file is not itself a +// read. const reads = [ - [fs, [`readFileSync`, `readFile`, `existsSync`, `statSync`]], + [ + fs, + [`readFileSync`, `readFile`, `createReadStream`, `existsSync`, `statSync`], + ], [fs.promises, [`readFile`, `stat`]], ] // The calls that list a directory. From b1d0bbabc58e8f11940570841c6a78d68e878f7b Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Tue, 17 Nov 2026 16:48:15 +0000 Subject: [PATCH 17/34] test(oracle-gaps): Vite's own plugin inputs, config-time listings, and hand-edited plugin output, oracle first Three more gate kinds from the review of #133: - tsconfig: the package's tsconfig.json, which Vite's esbuild plugin reads when it transforms a test (useDefineForClassFields decides whether a declared class field is an own property; F1); - configListing: a listing the config makes when it loads, given to the tests through define (F2); - pluginWrite: a file the config's plugin writes in configResolved, then edited by hand; a cold run's plugin writes it again (F3). One constructed history each, appended last. All three fail incremental equals cold on the current head. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-model-oracle.mjs | 85 ++++++++++++++++--- .../gap-report-oracle.property.test.mjs | 48 ++++++++++- .../oracle-gaps/history-fingerprint.json | 4 +- packages/oracles/scripts/e2e-shards.mjs | 9 ++ packages/oracles/scripts/pr-shards.mjs | 6 ++ 5 files changed, 134 insertions(+), 18 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index b0eca6b0..af3ae62e 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -991,7 +991,14 @@ const drawn = fc.record({ // one empty file named `open` or `shut`, read by `readdirSync` // (`listing`) or by `opendirSync` (`opendir`): the edit renames that file, // so no file's text changes; or the package's gate file read through a - // stream (`stream`, createReadStream). These fields change what a history runs, so + // stream (`stream`, createReadStream); or an input of Vite's own plugins, + // the package's tsconfig.json, whose useDefineForClassFields decides + // whether a declared class field is an own property (`tsconfig`); or a + // listing that the config makes when it loads and gives to the tests + // through `define` (`configListing`); or a file that the config's plugin + // writes when the config resolves, which the edit then changes by hand + // (`pluginWrite`: a cold run's plugin writes it again, so the cold result + // does not change, and the daemon must not read the hand edit). These fields change what a history runs, so // they are drawn (maintainer decision, 2026-11-16, "Randomness wins"), and // last. inputRead: fc.constantFrom( @@ -1007,6 +1014,9 @@ const drawn = fc.record({ `listing`, `opendir`, `stream`, + `tsconfig`, + `configListing`, + `pluginWrite`, ), // Each write of a gate file keeps its size (`open` and `shut` have one // length) and gets back one fixed modification time, as `cp -p`, `rsync @@ -3171,7 +3181,7 @@ function resolveHistory(history) { // A plugin's gate needs a config to hold the plugin: with none, file b // reads no gate. inputRead: - pluginGated(history) && configOf(history).configPath === undefined + configGated(history) && configOf(history).configPath === undefined ? `none` : (history.inputRead ?? `none`), keepStamp: history.keepStamp === true, @@ -5006,6 +5016,11 @@ const gateFiles = { const pluginGated = (history) => history.inputRead === `pluginConfig` || history.inputRead === `pluginTransform` +/** Whether the gate lives in the config (a plugin, or the config's own listing). */ +const configGated = (history) => + pluginGated(history) || + history.inputRead === `configListing` || + history.inputRead === `pluginWrite` // Whether a test's verdict waits on the gate input. const inputGated = (plan, file, t) => plan.inputRead !== `none` && @@ -5045,6 +5060,18 @@ const inputReads = { pluginTransform: [ `const readInput = async () => ({ open: __GAP_INPUT_GATE__ === 'open' })`, ], + tsconfig: [ + `class GateBase {}`, + `class GateField extends GateBase { field!: number }`, + `const readInput = async () => ({ open: Object.hasOwn(new GateField(), 'field') })`, + ], + configListing: [ + `const readInput = async () => ({ open: __GAP_INPUT_GATE__ === 'open' })`, + ], + pluginWrite: [ + `import { readFileSync as readGate } from 'node:fs'`, + readGateFile(`new URL('./gen.json', import.meta.url)`), + ], stream: [ `import { createReadStream as streamGate } from 'node:fs'`, `const readInput = async () => { const chunks: Array = []; for await (const chunk of streamGate(new URL('./gate.json', import.meta.url))) chunks.push(chunk as Buffer); return { open: JSON.parse(Buffer.concat(chunks).toString('utf8')).gate === 'open' } }`, @@ -5604,14 +5631,21 @@ const LOAD_PLUGIN = `{ name: 'gap-own-load', load(id) { const path = id.split('? // resolves; `pluginTransform` reads it in each transform. const GATE_READ = `JSON.parse(readGate(gatePath, 'utf8')).gate` const gatePlugin = (plan) => - `(() => { let gate; return { name: 'gap-input-gate', configResolved() { ${plan.inputRead === `pluginConfig` ? `gate = ${GATE_READ}` : ``} }, transform(code, id) { return id.split('?')[0].endsWith('.test.ts') ? code.replaceAll('__GAP_INPUT_GATE__', JSON.stringify(${plan.inputRead === `pluginConfig` ? `gate` : GATE_READ})) : undefined } } })()` + plan.inputRead === `pluginWrite` + ? `{ name: 'gap-input-gate', configResolved() { writeGate(gatePath, '{"gate":"open"}\\n') } }` + : `(() => { let gate; return { name: 'gap-input-gate', configResolved() { ${plan.inputRead === `pluginConfig` ? `gate = ${GATE_READ}` : ``} }, transform(code, id) { return id.split('?')[0].endsWith('.test.ts') ? code.replaceAll('__GAP_INPUT_GATE__', JSON.stringify(${plan.inputRead === `pluginConfig` ? `gate` : GATE_READ})) : undefined } } })()` // The gate file's path from a config at `configPath` (in the package, or in // its parent, where the package is the directory `pkg`). -const gateFromConfig = (configPath) => +const gateFromConfig = (configPath, target = `tests/plugin-gate.json`) => posixPath.relative( posixPath.dirname(posixPath.join(`/pkg`, configPath)), - `/pkg/tests/plugin-gate.json`, + `/pkg/${target}`, ) +// The file or directory the config reads or writes, by gate kind. +const configTargets = { + configListing: `tests/gate-dir`, + pluginWrite: `tests/gen.json`, +} /** * The text of the package's config, in its syntax (`configOf`), with the @@ -5623,8 +5657,15 @@ function configText(plan, test, configPath = plan.configPath) { const plugins = [ ...(plan.prePlugin ? [PRE_PLUGIN] : []), ...(plan.loadPlugin ? [LOAD_PLUGIN] : []), - ...(pluginGated(plan) ? [gatePlugin(plan)] : []), + ...(pluginGated(plan) || plan.inputRead === `pluginWrite` + ? [gatePlugin(plan)] + : []), ] + // The config's listing of the gate directory, given to the tests. + const define = + plan.inputRead === `configListing` + ? `, define: { __GAP_INPUT_GATE__: JSON.stringify(listGate(gatePath).includes('open') ? 'open' : 'shut') }` + : `` const config = `defineConfig(${ { object: ``, function: `() => (`, async: `async () => (`, promise: `` }[ plan.config @@ -5633,7 +5674,7 @@ function configText(plan, test, configPath = plan.configPath) { plan.fault === `projects` ? `{ projects: [{ test: { name: 'unit', ...${test} } }] }` : test - }${plugins.length > 0 ? `, plugins: [${plugins.join(`, `)}]` : ``} }${plan.config === `object` || plan.config === `promise` ? `` : `)`})` + }${plugins.length > 0 ? `, plugins: [${plugins.join(`, `)}]` : ``}${define} }${plan.config === `object` || plan.config === `promise` ? `` : `)`})` // A promise of the config, a null default, or a config cut off mid-object. const body = plan.fault === `configNull` @@ -5652,15 +5693,15 @@ function configText(plan, test, configPath = plan.configPath) { : [`import { fileURLToPath } from 'node:url'`]), // Only an ES module config has the load plugin (its constructed history). ...(plan.loadPlugin ? [`import { readFileSync } from 'node:fs'`] : []), - ...(pluginGated(plan) + ...(configGated(plan) ? commonjs ? [ - `const { readFileSync: readGate } = require('node:fs')`, - `const gatePath = require('node:path').join(__dirname, '${gateFromConfig(configPath)}')`, + `const { readFileSync: readGate, readdirSync: listGate, writeFileSync: writeGate } = require('node:fs')`, + `const gatePath = require('node:path').join(__dirname, '${gateFromConfig(configPath, configTargets[plan.inputRead])}')`, ] : [ - `import { readFileSync as readGate } from 'node:fs'`, - `const gatePath = new URL('${gateFromConfig(configPath)}', import.meta.url)`, + `import { readFileSync as readGate, readdirSync as listGate, writeFileSync as writeGate } from 'node:fs'`, + `const gatePath = new URL('${gateFromConfig(configPath, configTargets[plan.inputRead])}', import.meta.url)`, ] : []), ...(plan.fault === `configThrows` @@ -5875,9 +5916,19 @@ function fixtureFiles(plan, state = initialState(plan)) { // time each time it is written. // The gate directory of a listing, which holds one empty file, named // by the gate's word. - ...(plan.inputRead === `listing` || plan.inputRead === `opendir` + ...([`listing`, `opendir`, `configListing`].includes(plan.inputRead) ? { [`tests/gate-dir/${state.inputOpen ? `open` : `shut`}`]: `` } : {}), + // The package's tsconfig.json, read by Vite's own esbuild plugin. + ...(plan.inputRead === `tsconfig` + ? { + 'tsconfig.json': `${JSON.stringify({ compilerOptions: { target: `ES2022`, useDefineForClassFields: state.inputOpen } })}\n`, + } + : {}), + // The file the config's plugin writes, as a hand edit leaves it. + ...(plan.inputRead === `pluginWrite` + ? { 'tests/gen.json': gateText(state.inputOpen) } + : {}), ...(gateFiles[plan.inputRead] === undefined ? {} : { @@ -6007,6 +6058,14 @@ function fixtureFiles(plan, state = initialState(plan)) { } for (const file of oracleFilesOf(plan)) files[`tests/${file}.test.ts`] = oracleTestFile(plan, file) + // The hand edit of the file the plugin writes also changes file b's own + // text, so the daemon runs b again and reads the edited file. + if ( + plan.inputRead === `pluginWrite` && + files[`tests/b.test.ts`] !== undefined + ) + files[`tests/b.test.ts`] += + `// the plugin's file was edited to ${state.inputOpen ? `open` : `shut`}\n` // Each mid-run edit changes file a's own text too (a count of them), so // the daemon runs file a's tests again in the check the edit lands in, // instead of reusing their evidence: the marker sits in the daemon's 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 742f038b..9bc9cae1 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -2669,6 +2669,17 @@ async function incremental(dir, plan, cli, copy, observe, states) { // The other install's summary reads otherwise by construction, so its // check is no edit, and the next edit is compared with the state before. if (step === `otherInstall`) return + // A hand edit of a file the config's plugin writes leaves the cold result + // as it was (the cold run's plugin writes the file again); the check + // through the daemon is judged against it all the same. + if ( + step === `inputGate` && + plan.inputRead === `pluginWrite` && + daemon.reported + ) + states.add( + `a hand edit of a file the config's plugin writes was checked through the daemon`, + ) // An edit that changes the cold result is one a stale cache could miss. if (step !== `start` && result(previous) !== result(coldRun)) { states.add(`edit ${step} changed the cold result`) @@ -2686,7 +2697,9 @@ async function incremental(dir, plan, cli, copy, observe, states) { // Only a gate file keeps its stamp; a listing's edit renames a file. if ( plan.keepStamp && - ![`env`, `listing`, `opendir`].includes(plan.inputRead) + ![`env`, `listing`, `opendir`, `tsconfig`, `configListing`].includes( + plan.inputRead, + ) ) states.add( `an edit that kept a file's size and modification time changed the cold result`, @@ -5575,6 +5588,8 @@ const inputKinds = [ `listing`, `opendir`, `stream`, + `tsconfig`, + `configListing`, ] // Law 9's states that a constructed history of their own reaches, not the // edit sequence: the mid-run edit, and an edit to data a test reads through @@ -5599,6 +5614,7 @@ const ownedIncrementalStates = [ ...inputKinds.map( (kind) => `an edit to the ${kind} gate input changed the cold result`, ), + `a hand edit of a file the config's plugin writes was checked through the daemon`, `edit inputGate changed the cold result`, `an edit that kept a file's size and modification time changed the cold result`, ] @@ -8141,11 +8157,37 @@ oracleProperty({ // The package's gate file read through a stream, written back with // its size and modification time. [`an edit to a file a test reads through a stream`, `stream`, true], + // An input of Vite's own esbuild plugin (review of #133, F1). + [ + `an edit to the tsconfig that Vite's own plugin reads`, + `tsconfig`, + false, + ], + // A listing that the config makes when it loads (review of #133, F2). + [ + `an edit to a directory the config lists when it loads`, + `configListing`, + false, + ], + // A hand edit of a file that the config's plugin writes (review of + // #133, F3): the cold run's plugin writes it again, so the cold + // result does not change. + [ + `a hand edit of a file the config's plugin writes`, + `pluginWrite`, + false, + ], ].map(([name, inputRead, keepStamp]) => ({ name, enters: [ - `edit inputGate changed the cold result`, - `an edit to the ${inputRead} gate input changed the cold result`, + ...(inputRead === `pluginWrite` + ? [ + `a hand edit of a file the config's plugin writes was checked through the daemon`, + ] + : [ + `edit inputGate changed the cold result`, + `an edit to the ${inputRead} gate input changed the cold result`, + ]), `an unchanged check through the daemon computed nothing`, ...(keepStamp ? [ diff --git a/packages/oracles/oracle-gaps/history-fingerprint.json b/packages/oracles/oracle-gaps/history-fingerprint.json index 87ba90ca..5469e557 100644 --- a/packages/oracles/oracle-gaps/history-fingerprint.json +++ b/packages/oracles/oracle-gaps/history-fingerprint.json @@ -72,7 +72,7 @@ ["unsupervised", "ed6866229ecc4969"], ["psMissing", "e6ef4bc292a3990d"], ["holdOverlap", "ed6866229ecc4969"], - ["inputRead", "992c868c7f5164a0"], + ["inputRead", "c2c447f51d3e29ba"], ["keepStamp", "06892edd24057352"], ["inputSteps", "a7805625269c7a5f"] ], @@ -149,7 +149,7 @@ ["unsupervised", "ed6866229ecc4969"], ["psMissing", "e6ef4bc292a3990d"], ["holdOverlap", "ed6866229ecc4969"], - ["inputRead", "992c868c7f5164a0"], + ["inputRead", "c2c447f51d3e29ba"], ["keepStamp", "06892edd24057352"], ["inputSteps", "a7805625269c7a5f"] ] diff --git a/packages/oracles/scripts/e2e-shards.mjs b/packages/oracles/scripts/e2e-shards.mjs index ee43f6e7..449c6a15 100644 --- a/packages/oracles/scripts/e2e-shards.mjs +++ b/packages/oracles/scripts/e2e-shards.mjs @@ -143,6 +143,15 @@ export const shards = { `fixed seed 20261105: an edit to a file a test reads through a stream`, `random seed: an edit to a file a test reads through a stream`, `determinism: constructed history: an edit to a file a test reads through a stream`, + "fixed seed 20261105: an edit to the tsconfig that Vite's own plugin reads", + "random seed: an edit to the tsconfig that Vite's own plugin reads", + "determinism: constructed history: an edit to the tsconfig that Vite's own plugin reads", + 'fixed seed 20261105: an edit to a directory the config lists when it loads', + 'random seed: an edit to a directory the config lists when it loads', + 'determinism: constructed history: an edit to a directory the config lists when it loads', + "fixed seed 20261105: a hand edit of a file the config's plugin writes", + "random seed: a hand edit of a file the config's plugin writes", + "determinism: constructed history: a hand edit of a file the config's plugin writes", // Added with the CLI's parent-config discovery (not yet measured). `fixed seed 20261105: a package whose parent directory has its config`, `random seed: test.projects in a parent's config`, diff --git a/packages/oracles/scripts/pr-shards.mjs b/packages/oracles/scripts/pr-shards.mjs index dc58812f..aca5218d 100644 --- a/packages/oracles/scripts/pr-shards.mjs +++ b/packages/oracles/scripts/pr-shards.mjs @@ -38,6 +38,9 @@ const daemonInputUnits = [ 'an edit to a directory listing that a test reads', 'an edit to a directory a test reads through opendir', 'an edit to a file a test reads through a stream', + "an edit to the tsconfig that Vite's own plugin reads", + 'an edit to a directory the config lists when it loads', + "a hand edit of a file the config's plugin writes", ] const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, `\\$&`) const anyOf = (names) => `(?:${names.map(escape).join(`|`)})` @@ -576,6 +579,7 @@ export const partitions = { 'a start refuses an empty claim', daemonInputUnits[0], daemonInputUnits[1], + daemonInputUnits[9], ]), 7: anyOf([ 'a daemon pause that cannot engage', @@ -607,6 +611,8 @@ export const partitions = { 'a daemon check with the default output directory, unsupervised', daemonInputUnits[2], daemonInputUnits[3], + daemonInputUnits[10], + daemonInputUnits[11], ]), 9: anyOf([ 'a lazy module loaded before a hang in the same batch', From 38e2269415dae324c5c23447505935c0b12df6c3 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Tue, 17 Nov 2026 16:50:29 +0000 Subject: [PATCH 18/34] fix(oracle-gaps): every plugin's hook reads, config-time listings, and per-check own writes From the review of #133: - F1: the runner's plugin wraps every resolved plugin's hooks in configResolved, Vite's and Vitest's own included, so what Vite's esbuild plugin reads (tsconfig.json) is an input. This replaces wrapping the config's own plugins in the wrapper config. - F2: a listing made while a context warms is an input again (no exclusion), so a config that lists a directory into define is seen. - F3: the session's own writes are per check (maintainer decision, 2026-11-17, "Own writes aren't inputs": the same process, earlier in the check). A file the session wrote is known by its text at the end of each check, and a hand edit of it replaces the daemon. A copy's read of a file the session wrote is an input; only the CLI's own variables stay out of a run's inputs. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 75 ++++++++++++++++---------- 1 file changed, 47 insertions(+), 28 deletions(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index 67a8ec23..dfc6ab72 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -223,20 +223,23 @@ class KeepOrder { } /** - * The config's own plugins, with each hook run under `reading` (openSession), - * so what a hook reads is a session input. A `load` or `transform` hook - * names the module it serves. A plugin is wrapped once; a hook is a function - * or an object with a `handler`, as Vite takes it. + * Every plugin of a resolved config, Vite's and Vitest's own as well as the + * config's, with each hook run under `reading` (openSession), so what a hook + * reads is a session input: the tsconfig.json that Vite's esbuild plugin + * reads is an input as a sidecar of the config's own plugin is (review of + * #133, F1). A `load` or `transform` hook names the module it serves. The + * runner's own plugin is left as it is. A plugin is wrapped once; a hook is + * a function or an object with a `handler`, as Vite takes it. */ const hooked = new WeakSet() -function pluginHooks(option, reading) { - if (Array.isArray(option)) - return option.map((plugin) => pluginHooks(plugin, reading)) - if (typeof option?.then === `function`) - return option.then((plugin) => pluginHooks(plugin, reading)) - if (option === null || typeof option !== `object` || hooked.has(option)) - return option - hooked.add(option) +function pluginHooks(plugins, reading) { + for (const option of plugins) { + if (option.name === `oracle-gaps-schemata` || hooked.has(option)) continue + hooked.add(option) + hookPlugin(option, reading) + } +} +function hookPlugin(option, reading) { for (const [name, hook] of Object.entries(option)) { const handler = typeof hook === `function` ? hook : hook?.handler if (typeof handler !== `function`) continue @@ -257,7 +260,6 @@ function pluginHooks(option, reading) { option[name] = typeof hook === `function` ? watched : { ...hook, handler: watched } } - return option } /** @@ -502,25 +504,27 @@ export async function openSession(pkg) { // changed since is replaced (inputsChanged, daemon.mjs), since a plugin or // a module may keep what it read. A load or transform hook's read of the // module it serves is that module's own text, the module's input already. - // A file that the session wrote there before it read it, such as the - // config Vite bundles into a temporary file, is the session's own output. - // So is a variable that the CLI set (ORACLE_GAPS_STATE, which names each - // check's output). A read that comes after its warm ended, from work the + // A file that the session wrote earlier in the check before it read it, + // such as the config Vite bundles into a temporary file, is the session's + // own output (maintainer decision, 2026-11-17, "Own writes aren't + // inputs": the same process, earlier in the check). Each check starts + // with no write (`wrote`), and a file the session wrote must still hold + // what it wrote at the next check (`written`, inputsChanged), since a + // hand edit of it is no write of the session. So is a variable that the + // CLI set (ORACLE_GAPS_STATE, which names each check's output), which a + // copy may read too. A read that comes after its warm ended, from work the // warm left behind, is a hook's read, so the global inputs stay those of // the warm itself. const warmReads = new Map() const hookReads = new Map() const wrote = new Set() + const written = new Map() const reading = new AsyncLocalStorage() watchReads((key, write) => { const at = reading.getStore() if (write && key.startsWith(`env:`)) wrote.add(key) const reads = at?.hook || at?.done ? hookReads : warmReads if (at === undefined || key === at.module || reads.has(key)) return - // Vitest lists the package's directories to find its test files, which - // each check does again (specsOf), so a warm's listing is no input; a - // plugin hook's listing is. - if (reads === warmReads && /^dirs?:/.test(key)) return if (write) wrote.add(key) else if (!wrote.has(key)) reads.set(key, key.startsWith(`env:`) ? null : inputHash(key)) @@ -620,12 +624,15 @@ export default async (env) => { const loaded = typeof base === 'function' ? await base(env) : await base if (loaded === null || typeof loaded !== 'object') throw new Error(${JSON.stringify(`${config ?? `the config`}: config must export or return an object.`)}) - // The config's own plugins, whose hooks' reads are inputs (check.mjs, pluginHooks). - if (loaded.plugins !== undefined) loaded.plugins = globalThis.__oracleGapsPluginHooks(loaded.plugins) const merged = mergeConfig(loaded, { plugins: [{ name: 'oracle-gaps-schemata', enforce: 'pre', + // Every resolved plugin's hooks read their inputs under the runner's + // watch (check.mjs, pluginHooks). + configResolved(resolved) { + globalThis.__oracleGapsPluginHooks(resolved.plugins) + }, // A workspace dependency loads from its one-file bundle // (workspaceBundles). A copy of a test file is not resolved here, so // Vite keeps the absolute path that Vitest imports it by, and \`load\` @@ -1607,9 +1614,20 @@ export default async (env) => { return environments } - async function check(options, store, log = console.error) { - // Each check hashes every input from its text (fileHashes). + // A check, after which each file the session wrote is known by its text. + async function check(...args) { + try { + return await checkIn(...args) + } finally { + for (const key of wrote) + if (key.startsWith(`fs:`)) written.set(key, inputHash(key)) + } + } + async function checkIn(options, store, log = console.error) { + // Each check hashes every input from its text (fileHashes), and starts + // with no write of its own. hashOf.forget() + wrote.clear() const authored = options.mutants ? loadAuthored(options.mutants) : [] seedVariable = `${options.envPrefix}_SEED` if (options.hangLimit > options.mutantLimit) @@ -1806,7 +1824,7 @@ export default async (env) => { // A variable that the CLI set (`wrote`) is its own output, which a // copy may read too (the harness's fallback read of ORACLE_GAPS_STATE). const paths = [...new Set([...runPaths, ...hookReads.keys()])].filter( - (path) => !wrote.has(path), + (path) => !(path.startsWith(`env:`) && wrote.has(path)), ) const readAt = { ...Object.fromEntries(hookReads), ...runReadAt } const inputs = paths.map((path) => { @@ -2777,12 +2795,13 @@ export default async (env) => { } /** - * Whether a file the session read (warmReads, hookReads) holds other text now: a + * Whether a file the session read (warmReads, hookReads) or wrote + * (written) holds other text now: a * daemon then serves no more checks, since a plugin or a module may keep * what it read (daemon.mjs). */ const inputsChanged = () => - [...warmReads, ...hookReads].some( + [...warmReads, ...hookReads, ...written].some( ([key, hash]) => !key.startsWith(`env:`) && inputHash(key) !== hash, ) return { check, close, inputsChanged } From dcd5bab5d6ea947358f6a48ba184dad259455a10 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Tue, 17 Nov 2026 16:53:10 +0000 Subject: [PATCH 19/34] test(oracle-gaps): the static calibrations name their histories; a 240 s backstop Each static calibration binds the constructed history it corrupts instead of searching the campaign for one (a refusal's corruption needs a refused run, which the search reached only after a dozen histories, and the draws that the appended fields shift made it longer): the 14 calibrations run in 30 s locally. The static property's timeout is a 240 s wall-clock backstop, about twice the generated units' measured CI cost (review of #133, F6; #144). Co-authored-by: Isaac --- ...gap-report-static-oracle.property.test.mjs | 26 ++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/packages/oracles/oracle-gaps/gap-report-static-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-static-oracle.property.test.mjs index 720a8abf..a85c031d 100644 --- a/packages/oracles/oracle-gaps/gap-report-static-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-static-oracle.property.test.mjs @@ -1275,29 +1275,41 @@ const corruptArguments = (change) => (trace) => { const value = { ...trace[index].value, ...change(trace[index].value) } return trace.map((o, i) => (i === index ? { ...o, value } : o)) } +// Each calibration names the history it corrupts (the framework's history +// binding), so it runs that one history instead of searching the campaign's +// histories for one its corruption applies to: a refusal's corruption needs a +// refused run, which the search found only after a dozen other histories, +// and the draws that #133's appended fields shift made that search longer +// (review of #133, F6). The bound histories reach what each corruption needs: +// a refusal, Svelte runes, owned mutants, a stability rerun, a derived class. const calibrations = [ { name: `a refusal prints a stack trace, as a crash does`, + history: { constructed: `bad arguments: noPackage` }, law: `report-shaped ending`, corrupt: corruptArguments(() => ({ stackFrames: true })), }, { name: `a refusal exits 1, as a crash does`, + history: { constructed: `bad arguments: noPackage` }, law: `report-shaped ending`, corrupt: corruptArguments(() => ({ exit: 1 })), }, { name: `a refusal gives no fix`, + history: { constructed: `bad arguments: noPackage` }, law: `report-shaped ending`, corrupt: corruptArguments(() => ({ fix: undefined, cause: undefined })), }, { name: `a refusal ends without its done line`, + history: { constructed: `bad arguments: noPackage` }, law: `report-shaped ending`, corrupt: corruptArguments(() => ({ done: undefined })), }, { name: `a refusal's fix offers a way around it`, + history: { constructed: `bad arguments: noPackage` }, law: `report-shaped ending`, corrupt: corruptArguments((v) => ({ fix: `${v.fix} Or mark the mutant equivalent.`, @@ -1305,11 +1317,13 @@ const calibrations = [ }, { name: `a refusal names another cause`, + history: { constructed: `bad arguments: noPackage` }, law: `report-shaped ending`, corrupt: corruptArguments(() => ({ cause: `something went wrong` })), }, { name: `a rune is moved from its place`, + history: { constructed: `every static state` }, law: `rune placement`, corrupt: corrupt(`static`, (v) => { if (!v.runes?.includes(`= $`)) return false @@ -1318,11 +1332,13 @@ const calibrations = [ }, { name: `a mutant is dropped`, + history: { constructed: `every static state` }, law: `enumeration`, corrupt: corrupt(`static`, (v) => void v.mutants.shift()), }, { name: `production code is marked as probe code`, + history: { constructed: `every static state` }, law: `probe-only code`, corrupt: corrupt(`static`, (v) => { const m = v.mutants.find((x) => !x.probe) @@ -1332,6 +1348,7 @@ const calibrations = [ }, { name: `an owned mutant is reported unowned`, + history: { constructed: `every static state` }, law: `ownership`, corrupt: corrupt(`static`, (v) => { const m = v.mutants.find((x) => !x.probe && x.owned) @@ -1341,6 +1358,7 @@ const calibrations = [ }, { name: `a derived class's super call is made conditional`, + history: { constructed: `a plain-parameter derived class` }, law: `super unconditional`, corrupt: corrupt(`derived`, (v) => { const run = v.mutants[0]?.runs[0] @@ -1352,6 +1370,7 @@ const calibrations = [ }, { name: `the instrumented derived class differs with no mutant active`, + history: { constructed: `a plain-parameter derived class` }, law: `no-mutant behavior`, corrupt: corrupt(`derived`, (v) => { v.instrumented[0] = { error: `Must call super constructor` } @@ -1359,6 +1378,7 @@ const calibrations = [ }, { name: `a key drops its statement`, + history: { constructed: `every static state` }, law: `keys`, corrupt: corrupt(`static`, (v) => { v.mutants[0].key = v.mutants[0].key.slice( @@ -1369,6 +1389,7 @@ const calibrations = [ }, { name: `an edit moves a key`, + history: { constructed: `every static state` }, law: `key stability`, corrupt: (trace) => { const before = trace.find((o) => o.checkpoint === `static`)?.value @@ -1847,5 +1868,8 @@ oracleProperty({ driver, check, calibrations, - timeout: 120_000, + // A loud wall-clock backstop, not a budget (M-6): about twice the + // generated units' measured cost on CI (85 to 121 s), so a unit is never + // cut off by load before its verdict (review of #133, F6; #144). + timeout: 240_000, }) From a26081a6f44fd5c86d10bb5dd7601988686e9b76 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Tue, 17 Nov 2026 16:55:08 +0000 Subject: [PATCH 20/34] docs(oracle-gaps): every plugin's reads, a full recompute on any env change, and the open families The README and the changeset say that every plugin's hook reads are inputs, that any environment difference recomputes every unit (Vitest and Vite read every variable while a context warms; review of #133, F8), and name the issue for each family still open (#141-#143, #152-#154). "every outcome class" takes no gate input: its states are not the daemon-input histories', and it is the campaign's costliest history. Co-authored-by: Isaac --- .changeset/gap-cli-daemon-every-read.md | 4 +- README.md | 37 ++++++++++++------- .../gap-report-oracle.property.test.mjs | 8 +++- 3 files changed, 32 insertions(+), 17 deletions(-) diff --git a/.changeset/gap-cli-daemon-every-read.md b/.changeset/gap-cli-daemon-every-read.md index 40d04a43..2e8394f4 100644 --- a/.changeset/gap-cli-daemon-every-read.md +++ b/.changeset/gap-cli-daemon-every-read.md @@ -2,8 +2,8 @@ '@tanstack/oracles': patch --- -A check through `--daemon` now treats every read as an input of the runs that made it, so after any of these changes it reports what a cold run reports. Before, the daemon reused a run that read the old input. The new inputs are a file that a test reads through `fs` outside the package or under `node_modules`, or through `createReadStream`; a directory that a test lists (`readdir`, `opendir`, and their sync and `fs/promises` forms), by its entries; an environment variable that a test reads (or the set of variable names, when a test lists them); and a file or variable that Vitest, the Vite config, or one of the config's own plugins reads while it loads or in one of its hooks, such as a sidecar file that a plugin writes into the code it transforms. +A check through `--daemon` now treats every read as an input of the runs that made it, so after any of these changes it reports what a cold run reports. Before, the daemon reused a run that read the old input. The new inputs are a file that a test reads through `fs` outside the package or under `node_modules`, or through `createReadStream`; a directory that a test lists (`readdir`, `opendir`, and their sync and `fs/promises` forms), by its entries; an environment variable that a test reads (or the set of variable names, when a test lists them); and a file or variable that Vitest, Vite, or the config reads in the CLI's process, while it loads or in a hook of any plugin, Vite's own included, such as the `tsconfig.json` that Vite's esbuild plugin reads or a sidecar file that a plugin writes into the code it transforms. -The daemon now runs each check in the environment of the CLI that asked for it. A check from another environment, or after a file that the config or a plugin read has changed, starts a new daemon, which still reuses every stored run whose inputs are unchanged. +The daemon now runs each check in the environment of the CLI that asked for it. A check from another environment, or after a file that Vitest, the config, or a plugin read or wrote has changed, starts a new daemon. Because Vitest and Vite read every environment variable while they start, any change to the environment runs every unit again, as a cold run does. Each check now hashes every file input from its content, so an edit that keeps a file's size and modification time, as `cp -p`, `rsync -t`, or `touch -r` leave it, is no longer missed. diff --git a/README.md b/README.md index ec00b4b4..889123aa 100644 --- a/README.md +++ b/README.md @@ -231,10 +231,14 @@ exited with ` and exits 3; after an out-of-memory crash `fs/promises` `readFile` and `stat`), each by the content that the run read; the directories its tests list (`readdir`, `readdirSync`, `opendir`, `opendirSync`, and `fs/promises` `readdir` and `opendir`), each by its - entries' names and kinds; the environment variables - its tests read, by value, or all of them when a test lists them; and what - Vitest, the Vite config, and the config's own plugins read in the CLI's - process while it loads them and in each plugin hook. Each check hashes + entries' names and kinds; the environment variables its tests read, by + value, or all of them when a test lists them; and what Vitest, Vite, and + the config read in the CLI's process, while Vitest loads and the contexts + warm, and in each hook of every plugin, Vite's own (such as the + `tsconfig.json` that its esbuild plugin reads) and the config's alike. A + file that a reader wrote earlier in the check, before it read it, is its + own output and no input (maintainer decision, 2026-11-17); a file the + session wrote that is edited by hand afterwards is seen. Each check hashes every file input from its content, so an edit that keeps a file's size and modification time (`cp -p`, `rsync -t`, `touch -r`) is seen. A run that an edit overlapped, because a file changed after the run read it, is not @@ -242,23 +246,28 @@ exited with ` and exits 3; after an out-of-memory crash directory, not by its content. The daemon runs every check in the environment that the CLI asking for it - has. A check from another environment, or after a file that Vitest, the - config, or a plugin read has changed, stops the daemon and starts a new - one, which reads them again; the runs it stored are still reused where - their inputs are unchanged. + has. While a context warms, Vitest and Vite read every environment + variable by value, so a check from an environment that differs in any + variable, even one no test reads (`OLDPWD`, `SHLVL`, a terminal's session + id), starts a new daemon and runs every unit again, as a cold run does. + So does a check after a file that Vitest, the config, or a plugin read or + wrote has changed. These reads are no input yet, so an edit to the file alone does not rerun the tests that read it: a read from a worker thread or child process that the test starts (#143); a read through a file descriptor, after `open`, `openSync`, or the `fs/promises` `open` (#141); a link's target, or the rest of the stat family, `lstat`, `readlink`, `realpath`, `access`, the - callback `stat`, and `exists` (#142); and `glob`, `globSync`, `copyFile`, + callback `stat`, and `exists` (#142); `glob`, `globSync`, `copyFile`, `copyFileSync`, `cp`, `cpSync`, `openAsBlob`, `statfs`, and the - `fs/promises` `glob`, `copyFile`, `cp`, and `statfs`. Run the check cold - (without `--daemon`) after an edit to a file read that way. A later - release records all of them except `watch` and `watchFile`, which wait for - future changes and stay no input (maintainer decision, 2026-11-13, with - `watchFile` in the family of `watch`). + `fs/promises` `glob`, `copyFile`, `cp`, and `statfs` (#152); the + module-level reads of a test file whose tests are all skipped (#153); and + the earlier content of a file that a test appends to, partly writes, or + fails to write, then reads (#154). Run the check cold (without `--daemon`) + after an edit to a file read that way. A later release records all of + them except `watch` and `watchFile`, which wait for future changes and + stay no input (maintainer decision, 2026-11-13, with `watchFile` in the + family of `watch`). - `packages/eslint-plugin-oracles` (`@tanstack/eslint-plugin-oracles`): the `oracle/*` lint rules. The rules recognize the framework by its package 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 9bc9cae1..ee26858d 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -6060,7 +6060,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. 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 the stream law (law 15) on both streams, as for any run, so its error line and its done line carry the prefix, and no other line does not, which the state \`a run ended in an internal error\` declares; then exit 3 with an internal error's done line last on both streams, no stack frame on stderr, and an error.log in its output directory. What the error.log's stack says is not judged. An internal error that no fault constructs is a completion failure, reported before the stream law; an internal error through the daemon is reached by no history, and its ending is the same function's (endRun), by inspection. The internal error's lines follow the register's C entry "The internal-error line" (2026-11-16): the general law (endsBreach) owes every run that ends through endRun one error line on stderr naming the done line's log, the output directory's error.log, and none on stdout, and owes the supervisor's own exit 3 none. The message's escape is witnessed by the fault's message, which holds a line break and a forged done line after it; the log path's escape only on POSIX, where the rejected batch's output directory holds a line break (a name on win32 cannot). Paths in a completed run's lines (the results note, the done line's report, the test-output note) are escaped the same way, by inspection: no completed history names such a directory. P10's exempt lines (v21.2 P10 and I3) are read by their own shapes (exemptBlocks), never by indentation alone: a baseline failure's indented details, a refusal's block, Node's warning with its \`--trace-warnings\` frames and its hint, V8's fatal block, esbuild's message block, and Vite's own \`[vite]\` line. The V8, traced-warning, and esbuild blocks are calibrated beside our own line with no prefix (the stream calibrations put them before the rejected-batch run's done line, and the law must name our line alone); no generated history prints any of them or a Vite line, and a shape of those tools that exemptBlocks does not name is read as a stray. The stdout summary's exemption is unused and not exercised: the CLI prefixes every summary line (its summary, legend, and function kinds). \`--help\` prints its usage text with no prefix and no done line, exempt by the register's M entry "\`--help\` is exempt" (2026-11-16), and the static oracle's Help law owes exactly that text; \`--stop-daemon\` prints nothing and exits 0, read the same way as a command outside the run protocol (C, pending ratification), and this oracle runs it without observing its streams. A syntax error in a module that the config imports lets the esbuild that Vite bundles configs with print its block before the refusal (trace, Vite 7.3.7, esbuild 0.28.2: \`✘ [ERROR] Unexpected end of file\`, an empty line, \` helper.ts:2:0:\`, the code frame, then the refused block): its lines are exempt by the register's M entry "Other tools' output is exempt" (2026-11-16), the refusal and the done line around them keep the prefix, and no history generates it. 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, which owes its done line as any stop does (no history sends a win32 child.kill, the SIGKILL-equivalent that owes none); every SIGINT state stays required on win32. A stop as the CLI starts lands only in one of two holds: the driver's own preload before the CLI's first statement (outcome a, nothing written; POSIX only, since its witness is a signal's default action), or the CLI's hold after its started marker, which the stop the CLI keeps releases (outcome b, judged only when the supervisor started no child); a stop during Node's own start between the two is not generated, since its outcome follows timing. The drawn spawn delay is a wait inside a hold, so it cannot move a stop out of it. Stop runs that land while the config warms (ORACLE_GAPS_TEST_WARM_PROBE) are still drawn, and on win32 every drawn stop goes through ORACLE_GAPS_TEST_STOP: each is a test-only hook that a drawn field switches, main's pattern, which the review of #57 (A3) brought to the maintainer; only the stop after the completed line (ORACLE_GAPS_TEST_HOLD_UNTIL) was made constructed-only. A missing \`ps\` is generated only as a PATH that names no command, on POSIX, where the run is supervised. The unsupervised path (stopNow, every win32 stop) is reached on POSIX by one constructed history whose stop is held at the run's note, before the check starts a process: an unsupervised POSIX run has no group to end, so a stop while the witness's test spins leaves that test's own child (measured; C 2026-11-13, Windows (e)), which win32 ends with the job object libuv puts its children in. 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. Law 15's stdout gap lines are judged against each completed run's own results.json, by id: the cold run, and each check through the daemon (every step's check and the check that a mid-run edit overlaps); a stopped run and a refusal list no gaps and are not judged so. A line's change is read loosely: its code on one line, whole or cut after a kept part and ended with \`...\`; where the printer cuts (60 code points, kept 57) is the classify oracle's law 8 (\`shortened\`), in-process. A line with any text after its change does not read and fails loudly: the \` (cause: )\` suffix that #99 adds to timeout lines is not read yet, so whichever of #99 and #115 lands second extends readGapLine. 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) and, in one constructed history, a plugin whose load reads each test file with a sync read (loadPlugin); and the gate plugin (inputRead pluginConfig or pluginTransform), which reads a sidecar file of the package once when the config resolves or in each transform of a test file, and writes its word into the test's text (maintainer decision, 2026-11-16, "Every read is a daemon input": every plugin input is a daemon input); a plugin that reads an environment variable, enumerates the environment, or reads through another fs API than the six below is not generated; and test.projects only as a refusal, and only under the package's own package.json; the supervisor-death state is required and entered only off win32: win32 has no supervisor until #79, so there the state is not reached and its history is not judged (platform-scoped reach; the win32 run is unsupervised, which register C entry (e) of #58 records as not guaranteeing that no process outlives the CLI); a config's test.root only in four shapes, each in one constructed history of an ES module config that Vitest discovers, with one owner and one context, where the test files' globs and the setup file are relative to the root (issue #101): the directory that holds the tests, the directory above the package, a directory of the package that holds no test file, and the package's tests as a symbolic link to the directory that holds them (required on every platform, since Windows creates the link as the driver's other links); not under --config, a CommonJS config, test.projects, several contexts with different roots, or a root that is the filesystem's root; the runner serves each copy of a test file by its absolute path, through its pre plugin's load (which answers before the config's own plugins) and through its read of the copy's path for Vitest's pragma read (serveCopies), and histories run copies only in Vite's server environments (node and the pragma's ssr environment): jsdom and happy-dom, Vite's client environment, are not generated (the #103 merge-gate review ran jsdom by hand under all five root shapes, and the copies loaded in each); 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; every read is a daemon input (maintainer decision, 2026-11-16, "All of them"), on any path and under node_modules too, with no package-boundary exception: the gate input (inputRead) is a JSON file that file b's verdict reads with a sync read in the package's tests, beside the package and outside it, or in a package under its node_modules, or the variable GAP_INPUT_GATE, or the gate plugin's sidecar file, and the inputGate edit flips only that input, drawn (maintainer decision, 2026-11-16, "Randomness wins") and in one constructed history per kind; a read from a worker thread or a child process that a test starts, an enumeration of the environment by a test (it is an input as the set of names, and not generated), or a read through any other fs API than the six, createReadStream (the gate kind stream), and the listings of readdir and opendir (the gate kinds listing and opendir), which includes glob, globSync, 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 (issues #141 fd reads, #142 link targets and the stat family, #143 worker threads and child processes): 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; a gate file's edits may keep its size and get back one fixed modification time (keepStamp), as cp -p, rsync -t, or touch -r leave a file, in generated histories and in two constructed ones (the package's file and the plugin's sidecar), so a reuse decided by a file's size and modification time across checks is seen (D10); an edit that keeps both during a check is not generated; law 9's edits leave out environment variables other than the seed and the gate's, 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 here too: the default-directory histories (a stop, a daemon check, and the unsupervised daemon check) run without --out, and their directory is named in the trace; 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; a SIGKILL of a supervisor is witnessed on POSIX by the constructed history "a supervised child exits when its supervisor is killed" (its child exits within the watchdog tick), and a signal sent to the daemon is not witnessed here, 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; probe code is never work (maintainer decision, 2026-11-16), so the model and the capture count no probe-only site, and only a constructed history (a probe branch under a generated test's work bound) reaches a probe branch beside a bound: the fixed seeds' generated histories reach neither that state nor \`killed by a work bound in a generated function\`, which stays measured; work counts are observed only through a bound's ratio and a rise, never as numbers (v21.2 O1), so a counter that skips every site on a probe's line, which drops only the condition sites of an elseIf that run once on both sides, survives (mutant M6, equivalent under these observations), while one that skips every site of a function that holds probe code is killed (M7), 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 the stream law (law 15) on both streams, as for any run, so its error line and its done line carry the prefix, and no other line does not, which the state \`a run ended in an internal error\` declares; then exit 3 with an internal error's done line last on both streams, no stack frame on stderr, and an error.log in its output directory. What the error.log's stack says is not judged. An internal error that no fault constructs is a completion failure, reported before the stream law; an internal error through the daemon is reached by no history, and its ending is the same function's (endRun), by inspection. The internal error's lines follow the register's C entry "The internal-error line" (2026-11-16): the general law (endsBreach) owes every run that ends through endRun one error line on stderr naming the done line's log, the output directory's error.log, and none on stdout, and owes the supervisor's own exit 3 none. The message's escape is witnessed by the fault's message, which holds a line break and a forged done line after it; the log path's escape only on POSIX, where the rejected batch's output directory holds a line break (a name on win32 cannot). Paths in a completed run's lines (the results note, the done line's report, the test-output note) are escaped the same way, by inspection: no completed history names such a directory. P10's exempt lines (v21.2 P10 and I3) are read by their own shapes (exemptBlocks), never by indentation alone: a baseline failure's indented details, a refusal's block, Node's warning with its \`--trace-warnings\` frames and its hint, V8's fatal block, esbuild's message block, and Vite's own \`[vite]\` line. The V8, traced-warning, and esbuild blocks are calibrated beside our own line with no prefix (the stream calibrations put them before the rejected-batch run's done line, and the law must name our line alone); no generated history prints any of them or a Vite line, and a shape of those tools that exemptBlocks does not name is read as a stray. The stdout summary's exemption is unused and not exercised: the CLI prefixes every summary line (its summary, legend, and function kinds). \`--help\` prints its usage text with no prefix and no done line, exempt by the register's M entry "\`--help\` is exempt" (2026-11-16), and the static oracle's Help law owes exactly that text; \`--stop-daemon\` prints nothing and exits 0, read the same way as a command outside the run protocol (C, pending ratification), and this oracle runs it without observing its streams. A syntax error in a module that the config imports lets the esbuild that Vite bundles configs with print its block before the refusal (trace, Vite 7.3.7, esbuild 0.28.2: \`✘ [ERROR] Unexpected end of file\`, an empty line, \` helper.ts:2:0:\`, the code frame, then the refused block): its lines are exempt by the register's M entry "Other tools' output is exempt" (2026-11-16), the refusal and the done line around them keep the prefix, and no history generates it. 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, which owes its done line as any stop does (no history sends a win32 child.kill, the SIGKILL-equivalent that owes none); every SIGINT state stays required on win32. A stop as the CLI starts lands only in one of two holds: the driver's own preload before the CLI's first statement (outcome a, nothing written; POSIX only, since its witness is a signal's default action), or the CLI's hold after its started marker, which the stop the CLI keeps releases (outcome b, judged only when the supervisor started no child); a stop during Node's own start between the two is not generated, since its outcome follows timing. The drawn spawn delay is a wait inside a hold, so it cannot move a stop out of it. Stop runs that land while the config warms (ORACLE_GAPS_TEST_WARM_PROBE) are still drawn, and on win32 every drawn stop goes through ORACLE_GAPS_TEST_STOP: each is a test-only hook that a drawn field switches, main's pattern, which the review of #57 (A3) brought to the maintainer; only the stop after the completed line (ORACLE_GAPS_TEST_HOLD_UNTIL) was made constructed-only. A missing \`ps\` is generated only as a PATH that names no command, on POSIX, where the run is supervised. The unsupervised path (stopNow, every win32 stop) is reached on POSIX by one constructed history whose stop is held at the run's note, before the check starts a process: an unsupervised POSIX run has no group to end, so a stop while the witness's test spins leaves that test's own child (measured; C 2026-11-13, Windows (e)), which win32 ends with the job object libuv puts its children in. 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. Law 15's stdout gap lines are judged against each completed run's own results.json, by id: the cold run, and each check through the daemon (every step's check and the check that a mid-run edit overlaps); a stopped run and a refusal list no gaps and are not judged so. A line's change is read loosely: its code on one line, whole or cut after a kept part and ended with \`...\`; where the printer cuts (60 code points, kept 57) is the classify oracle's law 8 (\`shortened\`), in-process. A line with any text after its change does not read and fails loudly: the \` (cause: )\` suffix that #99 adds to timeout lines is not read yet, so whichever of #99 and #115 lands second extends readGapLine. 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) and, in one constructed history, a plugin whose load reads each test file with a sync read (loadPlugin); and the gate plugin (inputRead pluginConfig or pluginTransform), which reads a sidecar file of the package once when the config resolves or in each transform of a test file, and writes its word into the test's text (maintainer decision, 2026-11-16, "Every read is a daemon input": every plugin input is a daemon input); a plugin that reads an environment variable, enumerates the environment, or reads through another fs API than the six below is not generated; and test.projects only as a refusal, and only under the package's own package.json; the supervisor-death state is required and entered only off win32: win32 has no supervisor until #79, so there the state is not reached and its history is not judged (platform-scoped reach; the win32 run is unsupervised, which register C entry (e) of #58 records as not guaranteeing that no process outlives the CLI); a config's test.root only in four shapes, each in one constructed history of an ES module config that Vitest discovers, with one owner and one context, where the test files' globs and the setup file are relative to the root (issue #101): the directory that holds the tests, the directory above the package, a directory of the package that holds no test file, and the package's tests as a symbolic link to the directory that holds them (required on every platform, since Windows creates the link as the driver's other links); not under --config, a CommonJS config, test.projects, several contexts with different roots, or a root that is the filesystem's root; the runner serves each copy of a test file by its absolute path, through its pre plugin's load (which answers before the config's own plugins) and through its read of the copy's path for Vitest's pragma read (serveCopies), and histories run copies only in Vite's server environments (node and the pragma's ssr environment): jsdom and happy-dom, Vite's client environment, are not generated (the #103 merge-gate review ran jsdom by hand under all five root shapes, and the copies loaded in each); 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; every read is a daemon input (maintainer decision, 2026-11-16, "All of them"), on any path and under node_modules too, with no package-boundary exception: the gate input (inputRead) is a JSON file that file b's verdict reads with a sync read in the package's tests, beside the package and outside it, or in a package under its node_modules, or the variable GAP_INPUT_GATE, or the gate plugin's sidecar file, or a directory's listing (readdir, opendir), or a stream of the gate file, or the package's tsconfig.json, which Vite's own esbuild plugin reads (tsconfig: useDefineForClassFields decides whether a declared class field is an own property), or a listing the config makes when it loads and gives the tests through define (configListing), or a file the config's plugin writes when the config resolves and the edit changes by hand (pluginWrite: the cold result does not change, since a cold run's plugin writes it again, and the history enters its own state), and the inputGate edit flips only that input, drawn (maintainer decision, 2026-11-16, "Randomness wins") and in one constructed history per kind; a read from a worker thread or a child process that a test starts, an enumeration of the environment by a test (it is an input as the set of names, and not generated), or a read through any other fs API than the six, createReadStream (the gate kind stream), and the listings of readdir and opendir (the gate kinds listing and opendir), which includes glob, globSync, 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 (issues #141 fd reads, #142 link targets and the stat family, #143 worker threads and child processes, #152 glob, copyFile, cp, openAsBlob and statfs, #153 the module-level reads of a file whose tests all skip, #154 appends, partial and failed writes, and the runner-file rule): 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; a gate file's edits may keep its size and get back one fixed modification time (keepStamp), as cp -p, rsync -t, or touch -r leave a file, in generated histories and in two constructed ones (the package's file and the plugin's sidecar), so a reuse decided by a file's size and modification time across checks is seen (D10); an edit that keeps both during a check is not generated; law 9's edits leave out environment variables other than the seed and the gate's, 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 here too: the default-directory histories (a stop, a daemon check, and the unsupervised daemon check) run without --out, and their directory is named in the trace; 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; a SIGKILL of a supervisor is witnessed on POSIX by the constructed history "a supervised child exits when its supervisor is killed" (its child exits within the watchdog tick), and a signal sent to the daemon is not witnessed here, 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; probe code is never work (maintainer decision, 2026-11-16), so the model and the capture count no probe-only site, and only a constructed history (a probe branch under a generated test's work bound) reaches a probe branch beside a bound: the fixed seeds' generated histories reach neither that state nor \`killed by a work bound in a generated function\`, which stays measured; work counts are observed only through a bound's ratio and a rise, never as numbers (v21.2 O1), so a counter that skips every site on a probe's line, which drops only the condition sites of an elseIf that run once on both sides, survives (mutant M6, equivalent under these observations), while one that skips every site of a function that holds probe code is killed (M7), 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 @@ -6094,6 +6094,12 @@ oracleProperty({ witness: `capture`, wholeFile: `none`, fault: `none`, + // No gate input: its states are the daemon-input histories', and the + // witness module's own runs are the costliest of the campaign (the + // Windows job of this one history; review of #133, F6). + inputRead: `none`, + keepStamp: false, + inputSteps: NO_INPUT_STEPS, authored: { stmt: 0, kind: `apply` }, stability: `insertGuard`, steps: null, From 35a5ac1a43364c12b1ee0d535f23dd27df65976e Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Tue, 17 Nov 2026 23:27:13 +0000 Subject: [PATCH 21/34] fix(oracle-gaps): a stat is an input by existence and kind, not by text existsSync, statSync and the fs/promises stat key the path as stat:, hashed by whether it exists and what it is (G42's stat family). Once every plugin's hooks are watched, Vite's resolution stats each module it imports, and keying that by the module's text made every edit restart the daemon and run every unit again (the mid-run edits never landed in the daemon that the check started in, and the edit sequence reused nothing). Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 3 +- packages/oracles/oracle-gaps/inputs.mjs | 53 ++++++++++++++++++------- 2 files changed, 40 insertions(+), 16 deletions(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index dfc6ab72..34976730 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -697,8 +697,7 @@ export default async (env) => { // A variable by its value in the environment this check runs under, and // a directory by its listing now. if (path.startsWith(`env:`)) return envHash(path.slice(4)) - if (path.startsWith(`dir:`) || path.startsWith(`dirs:`)) - return inputHash(path) + if (/^(dir|dirs|stat):/.test(path)) return inputHash(path) const text = globalThis.__oracleGapsServe[index]?.get(path) ?? globalThis.__oracleGapsSchemata.get(path) diff --git a/packages/oracles/oracle-gaps/inputs.mjs b/packages/oracles/oracle-gaps/inputs.mjs index a871b99a..71f828b4 100644 --- a/packages/oracles/oracle-gaps/inputs.mjs +++ b/packages/oracles/oracle-gaps/inputs.mjs @@ -8,7 +8,8 @@ // An input's key is `fs:` for a file, hashed by its text (or as // `not a file`, or `missing`), `dir:` for a directory's listing, // hashed by its entries' names and kinds, or `dirs:` for a recursive -// one, `env:` for a variable, hashed by its value, or `env:*` for the +// one, `stat:` for a test of whether a path exists and what it is, +// hashed by that, `env:` for a variable, hashed by its value, or `env:*` for the // set of names, which code reads when it lists the environment. The harness (capture-setup.mjs) watches a test's reads in // its worker, and the session (check.mjs) watches what the config and its // plugins read in the CLI's process. Both files are copied beside the @@ -20,16 +21,20 @@ import { basename, dirname, join, resolve } from 'node:path' import { fileURLToPath } from 'node:url' import { posix } from './paths.mjs' -// The calls that read a file (a stream's too, by the whole file), and those -// that test whether it exists and what it is. Each is taken once per -// process, before a wrapper replaces it, so hashing a file is not itself a -// read. +// The calls that read a file (a stream's too, by the whole file). Each is +// taken once per process, before a wrapper replaces it, so hashing a file is +// not itself a read. const reads = [ - [ - fs, - [`readFileSync`, `readFile`, `createReadStream`, `existsSync`, `statSync`], - ], - [fs.promises, [`readFile`, `stat`]], + [fs, [`readFileSync`, `readFile`, `createReadStream`]], + [fs.promises, [`readFile`]], +] +// The calls that test whether a file exists and what it is: an input by its +// existence and kind (G42's stat family), not by its text, so that Vite's +// resolution, which stats each module it imports, does not make every +// module's text an input of every run. +const stats = [ + [fs, [`existsSync`, `statSync`]], + [fs.promises, [`stat`]], ] // The calls that list a directory. const listings = [ @@ -92,9 +97,21 @@ function listingHash(path, recursive) { export const inputHash = (key) => key.startsWith(`fs:`) ? fileHash(key.slice(3)) - : key.startsWith(`dirs:`) - ? listingHash(key.slice(5), true) - : listingHash(key.slice(4), false) + : key.startsWith(`stat:`) + ? kindOf(key.slice(5)) + : key.startsWith(`dirs:`) + ? listingHash(key.slice(5), true) + : listingHash(key.slice(4), false) + +/** A path's existence and kind now. */ +function kindOf(path) { + try { + const stat = original.statSync(path) + return stat.isFile() ? `file` : stat.isDirectory() ? `directory` : `other` + } catch { + return `missing` + } +} /** A variable's input hash under `env`, or for `*`, that of its names. */ export const envHash = (name, env = process.env) => @@ -148,7 +165,14 @@ export function watchReads(record) { return } if (path === undefined || isRunnerFile(posix(path))) return - const prefix = kind !== `list` ? `fs` : options?.recursive ? `dirs` : `dir` + const prefix = + kind === `stat` + ? `stat` + : kind !== `list` + ? `fs` + : options?.recursive + ? `dirs` + : `dir` record(`${prefix}:${posix(path)}`, write) // A written file is also known by its directory's real path, which a // later read through a link, or an import by its real URL, names. @@ -164,6 +188,7 @@ export function watchReads(record) { } for (const [calls, kind] of [ [reads, `read`], + [stats, `stat`], [listings, `list`], [writes, `write`], ]) From 6f6a7affd1ec7690fe022eda2d5f32cc1ffeac98 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Wed, 18 Nov 2026 05:04:10 +0000 Subject: [PATCH 22/34] fix(oracle-gaps): hook reads live once in a session log; discovery and the runner's entries leave listings On TanStack DB's subset-dedupe suite every unit carried 2,400 to 3,000 hook-read keys, and a listing of the package root among them changed at each check, so an unchanged recheck through the daemon ran all 557 units. - A session's hook reads are kept once, in order, in the store (hook-log:); a unit names the prefix that came before it settled (hooks::), an input while every read in it still holds. - A listing leaves out the runner's own entries (its session directory). - Vitest's discovery of test files, which each check does again outside any warm (specsOf), lists the package's directories: its listings are no global input, so the --out directories that runs create beside the tests do not change every unit's identity. Brought to the maintainer as a register entry. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 69 +++++++++++++++++++++++-- packages/oracles/oracle-gaps/inputs.mjs | 12 ++++- 2 files changed, 75 insertions(+), 6 deletions(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index bc0a1f8c..98a21fe7 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -519,6 +519,15 @@ export async function openSession(pkg, pause = async () => {}) { // the warm itself. const warmReads = new Map() const hookReads = new Map() + // The hook reads in the order they came (`hookLog`), kept once in the + // store per session (`hook-log:`): a unit names the part of the log + // that came before it settled (`hooks::`), which is an input while + // every read in that part holds its hash, so no unit carries the reads + // themselves (about 3,000 on TanStack DB's suite; review of #133). + const hookLogId = sha1(`${process.pid}:${Date.now()}:${Math.random()}`) + const hookLog = [] + // Per check: how far each session's log still holds (logHolds). + const holds = new Map() const wrote = new Set() const written = new Map() const reading = new AsyncLocalStorage() @@ -526,10 +535,18 @@ export async function openSession(pkg, pause = async () => {}) { const at = reading.getStore() if (write && key.startsWith(`env:`)) wrote.add(key) const reads = at?.hook || at?.done ? hookReads : warmReads - if (at === undefined || key === at.module || reads.has(key)) return + if (at === undefined || at.discovery || key === at.module || reads.has(key)) + return if (write) wrote.add(key) - else if (!wrote.has(key)) - reads.set(key, key.startsWith(`env:`) ? null : inputHash(key)) + else if (!wrote.has(key)) { + const hash = key.startsWith(`env:`) + ? reads === hookReads + ? envHash(key.slice(4)) + : null + : inputHash(key) + reads.set(key, hash) + if (reads === hookReads) hookLog.push([key, hash]) + } }) // Runs `work` as a warm under `reading`. const warming = async (work) => { @@ -699,12 +716,34 @@ export default async (env) => { // A variable by its value in the environment this check runs under, and // a directory by its listing now. if (path.startsWith(`env:`)) return envHash(path.slice(4)) + if (path.startsWith(`hooks:`)) { + const [, id, n] = path.split(`:`) + return logHolds(id, Number(n)) >= Number(n) ? `held` : `changed` + } if (/^(dir|dirs|stat):/.test(path)) return inputHash(path) const text = globalThis.__oracleGapsServe[index]?.get(path) ?? globalThis.__oracleGapsSchemata.get(path) return text === undefined ? hashOf(path) : sha1(text) } + // How much of a session's hook log, from its start, still holds its + // hashes in this check: a unit that names `hooks::` is unchanged + // while the first n reads hold. Another session's log is read from the + // store; the current one's grows while the check runs, so the count + // extends as later units ask. + let currentStore + const logHolds = (id, n) => { + const log = + id === hookLogId + ? hookLog + : (currentStore?.get(`hook-log:${id}`)?.variants[0]?.inputs ?? []) + const held = holds.get(id) ?? { count: 0, broken: false } + holds.set(id, held) + while (!held.broken && held.count < Math.min(n, log.length)) + if (servedHash(log[held.count][0]) === log[held.count][1]) held.count += 1 + else held.broken = true + return held.count + } // A context transformed a module (its wrapper's transform hook): the hash // of what it then serves. globalThis.__oracleGapsTransformed = (index, path) => @@ -901,6 +940,17 @@ export default async (env) => { throw error }), ) + // Vitest's discovery of the test files lists the package's directories. + // Each check discovers them again, outside any warm (specsOf), so what a + // listing found is never stale: those listings are no global input. The + // `--out` directories that runs create beside the tests would otherwise + // change every unit's identity at every check. + for (const project of context.projects ?? []) { + const globFiles = project.globFiles + if (typeof globFiles === `function`) + project.globFiles = (...args) => + reading.run({ discovery: true }, () => globFiles.apply(project, args)) + } // Vitest 3 calls this step `init`; Vitest 4 renamed it `standalone`. await fromConfig( index, @@ -1644,6 +1694,12 @@ export default async (env) => { } finally { for (const key of wrote) if (key.startsWith(`fs:`)) written.set(key, inputHash(key)) + // The session's hook log, for units that later sessions look up. + if (hookLog.length > 0) + args[1]?.put(`hook-log:${hookLogId}`, { + inputs: [...hookLog], + unit: null, + }) } } async function checkIn( @@ -1665,6 +1721,8 @@ export default async (env) => { // with no write of its own. hashOf.forget() wrote.clear() + holds.clear() + currentStore = store const authored = options.mutants ? loadAuthored(options.mutants) : [] seedVariable = `${options.envPrefix}_SEED` if (options.hangLimit > options.mutantLimit) @@ -1865,10 +1923,11 @@ export default async (env) => { // its read: the run may have read through any of it (see hookReads). // A variable that the CLI set (`wrote`) is its own output, which a // copy may read too (the harness's fallback read of ORACLE_GAPS_STATE). - const paths = [...new Set([...runPaths, ...hookReads.keys()])].filter( + const hooks = `hooks:${hookLogId}:${hookLog.length}` + const paths = [...new Set([...runPaths, hooks])].filter( (path) => !(path.startsWith(`env:`) && wrote.has(path)), ) - const readAt = { ...Object.fromEntries(hookReads), ...runReadAt } + const readAt = { [hooks]: `held`, ...runReadAt } const inputs = paths.map((path) => { const now = servedHash(path, index) const hash = diff --git a/packages/oracles/oracle-gaps/inputs.mjs b/packages/oracles/oracle-gaps/inputs.mjs index 71f828b4..42f06b5b 100644 --- a/packages/oracles/oracle-gaps/inputs.mjs +++ b/packages/oracles/oracle-gaps/inputs.mjs @@ -81,6 +81,11 @@ function listingHash(path, recursive) { return sha1( original .readdirSync(path, { withFileTypes: true, recursive }) + // The runner's own entries (its session directory) are no input. + .filter( + (entry) => + !isRunnerFile(`${posix(entry.parentPath ?? path)}/${entry.name}/`), + ) .map( (entry) => `${posix(entry.parentPath ?? path)}/${entry.name}\0${entry.isDirectory() ? `d` : entry.isSymbolicLink() ? `l` : `f`}`, @@ -114,7 +119,10 @@ function kindOf(path) { } /** A variable's input hash under `env`, or for `*`, that of its names. */ -export const envHash = (name, env = process.env) => +export const envHash = ( + name, + env = globalThis.__oracleGapsEnv ?? process.env, +) => sha1( name === `*` ? Object.keys(env).sort().join(`\0`) @@ -203,6 +211,8 @@ export function watchReads(record) { syncBuiltinESMExports() // A variable read by name, a test of whether it is set, and a listing of // the names, which reads the set of names. + // The environment itself, which hashing reads without being watched. + globalThis.__oracleGapsEnv = process.env process.env = new Proxy(process.env, { get(env, name) { if (typeof name === `string`) record(`env:${name}`) From a3737b8501d3c1a2f87a2e475c6eef53ac1666d7 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Thu, 19 Nov 2026 07:23:10 -0800 Subject: [PATCH 23/34] test(oracle-gaps): a daemon store longer than the string limit, oracle first (#179) V8 makes no string longer than about 512 MB, and the daemon writes and reads its evidence store as one string, so on TanStack DB's subset-dedupe suite every check after the 6th ends in "Invalid string length". A test-only knob (ORACLE_GAPS_TEST_STRING_LIMIT, inert unless set) lowers the limit where the store makes or reads a string, as V8's throws. The constructed history `storeLimit` runs a store of about 78,000 characters under a 32,768 limit (no row is longer than about 9,000): a first check, an unchanged recheck, and a restart that reads the store back. RED here: after start, the daemon's check exited 3 (error.log: RangeError: Invalid string length) and the cold run exited 0. Co-authored-by: Isaac --- README.md | 4 + packages/oracles/oracle-gaps/evidence.mjs | 19 ++++- .../oracle-gaps/gap-report-model-oracle.mjs | 11 +++ .../gap-report-oracle.property.test.mjs | 76 +++++++++++++++++++ .../oracle-gaps/history-fingerprint.json | 6 +- packages/oracles/scripts/e2e-shards.mjs | 3 + packages/oracles/scripts/pr-shards.mjs | 3 + 7 files changed, 118 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index a3961953..24c2de97 100644 --- a/README.md +++ b/README.md @@ -184,6 +184,10 @@ agent. for a daemon to start or to close, and for a daemon that holds its check to send anything; a test shortens it to outlast a paused daemon. It is a test-only knob, not a setting for users. + - `ORACLE_GAPS_TEST_STRING_LIMIT` (characters) makes the daemon's evidence + store throw where it makes or reads a string longer than this, as V8 does + past its own limit (about 512 MB), so a test meets that limit with a small + store. It is a test-only knob, not a setting for users. - `ORACLE_GAPS_TEST_SERVED_MARK` names a file the daemon writes its pid to after it answers a check, so a test can tell which daemon served an earlier check (the warm daemon that a later check's pause must match). diff --git a/packages/oracles/oracle-gaps/evidence.mjs b/packages/oracles/oracle-gaps/evidence.mjs index acf46003..dd0f01ee 100644 --- a/packages/oracles/oracle-gaps/evidence.mjs +++ b/packages/oracles/oracle-gaps/evidence.mjs @@ -68,6 +68,18 @@ export function memoryStore() { return { get: () => undefined, put: () => {} } } +// The longest string V8 makes (about 512 MB on 64-bit), which a test lowers +// (ORACLE_GAPS_TEST_STRING_LIMIT, a test-only knob) so that a small store +// meets the limit that a suite's store meets: past it, V8 throws a +// RangeError where the store makes or reads a string. +const STRING_LIMIT = Number(process.env.ORACLE_GAPS_TEST_STRING_LIMIT) || 0 +/** `text`, a string the store made or read, past the test limit a throw. */ +function storeString(text) { + if (STRING_LIMIT > 0 && text.length > STRING_LIMIT) + throw new RangeError(`Invalid string length`) + return text +} + /** * A store in `/evidence.json`. It reads the file once, when it opens. * `put` changes the rows in memory, and `flush` writes every row to a @@ -80,7 +92,10 @@ export async function diskStore(dir) { const file = join(dir, `evidence.json`) const rows = new Map( existsSync(file) - ? JSON.parse(readFileSync(file, `utf8`)).map((row) => [row.id, row]) + ? JSON.parse(storeString(readFileSync(file, `utf8`))).map((row) => [ + row.id, + row, + ]) : [], ) let dirty = false @@ -95,7 +110,7 @@ export async function diskStore(dir) { // The OS may have cleaned the temp directory that holds the store. mkdirSync(dir, { recursive: true }) const temporary = `${file}.${process.pid}.tmp` - writeFileSync(temporary, JSON.stringify([...rows.values()])) + writeFileSync(temporary, storeString(JSON.stringify([...rows.values()]))) renameSync(temporary, file) dirty = false }, diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index 9227f687..5e93431a 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -1172,6 +1172,15 @@ const drawn = fc.record({ }), }, ), + // Whether a daemon's checks run under a small test-only string limit + // (ORACLE_GAPS_TEST_STRING_LIMIT): V8 makes no string longer than about + // 512 MB, and a suite's store can pass that (#179), so a store that the + // daemon writes and reads as one string fails every check past it. The + // limit is longer than any one stored row of this history and shorter than + // the store. It switches a test-only knob, so only the constructed history + // "a daemon store longer than the string limit, reloaded after a restart" + // sets it. + storeLimit: fc.constant(false), }) // The edit sequence over the witness module, the one list of steps that a @@ -1245,6 +1254,7 @@ const constructedNeutral = { slowStart: false, holdOverlap: false, shortWait: false, + storeLimit: false, } // A drawn history never switches a test-only hook either (randomness wins, // 2026-11-16; v21.2 I16). Two steps arm a daemon pause: `dieMidCheck` holds @@ -3509,6 +3519,7 @@ function resolveHistory(history) { spinThrows: history.spinThrows === true, slowStart: history.slowStart ?? false, shortWait: history.shortWait === true, + storeLimit: history.storeLimit === true, // The gate input that file b's verdicts also wait on (`inputRead`), and // whether each write of a gate file keeps its size and modification time // (`keepStamp`). 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 6a9c483e..75ef7c3c 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -624,6 +624,12 @@ import { outsideOf, } from './gap-report-model-oracle.mjs' +// The test string limit of the `storeLimit` history, in characters: longer +// than any one row that history's store holds, and shorter than the store +// (#179). Measured on macOS: the store is about 78,000 characters, and its +// longest row about 9,000. +const STORE_STRING_LIMIT = 32_768 + const here = dirname(fileURLToPath(import.meta.url)) const repo = resolve(here, `..`) @@ -2594,6 +2600,10 @@ async function incremental(dir, plan, cli, copy, observe, states) { ...(plan.shortWait && step !== `start` ? { ORACLE_GAPS_TEST_WAIT_MS: `3000` } : {}), + // The daemon's store under the test string limit (`storeLimit`). + ...(plan.storeLimit + ? { ORACLE_GAPS_TEST_STRING_LIMIT: `${STORE_STRING_LIMIT}` } + : {}), }, } // The first check may be two at once, which must reach one daemon, and @@ -2818,6 +2828,10 @@ async function incremental(dir, plan, cli, copy, observe, states) { states.add(`incremental check reused some evidence and recomputed some`) if (step === `restart` && reused > 0) states.add(`evidence reused after a daemon restart`) + // A daemon restarted under the test string limit read back a store + // longer than the limit, and reused what it held (#179). + if (plan.storeLimit && step === `restart` && reused > 0) + states.add(`a daemon reloaded a store longer than the string limit`) if (unchangedComputed === 0 && reused > 0) { states.add(`an unchanged check through the daemon computed nothing`) if (plan.prePlugin) @@ -6545,6 +6559,7 @@ const required = [ `a check through the daemon worked past its CLI's bound`, `a slow daemon start was served by the daemon`, `a check abandoned while a context warmed in place of a cut one wrote nothing more`, + `a daemon reloaded a store longer than the string limit`, ] // The faults the CLI analyzes anyway: a package's TypeScript is no input. const analyzedFaults = [`noTypescript`, `apiLessTypescript`] @@ -9624,6 +9639,67 @@ oracleProperty({ steps: [`inputGate`, `recheck`], }), })), + { + // A store longer than the longest string V8 makes (#179), under a + // test-only limit (`storeLimit`) that is longer than any one stored + // row of this history and shorter than the store: the daemon writes + // the store after its first check, reuses it unchanged on the + // recheck, and a new daemon after the restart reads it back and + // reuses it. A store made or read as one string ends each of those + // checks in an internal error, which the cold run does not have. + name: `a daemon store longer than the string limit, reloaded after a restart`, + enters: [ + `a daemon reloaded a store longer than the string limit`, + `evidence reused after a daemon restart`, + `an unchanged check through the daemon computed nothing`, + ], + build: (generated) => ({ + ...generated, + functions: [ + [{ kind: `push`, quote: `'` }], + [{ kind: `push`, quote: `'` }], + [{ kind: `push`, quote: `'` }], + ], + containers: [], + overloads: [], + owners: [`a`, `b`, `both`], + library: [], + libraryOwners: [], + runes: [], + derived: null, + dotGen: false, + dataOwners: [], + exportOwners: [], + importer: `none`, + wholeFile: `none`, + template: false, + tests: [ + { ...judging(`a`, `fixed seed`, 1), fn: 0 }, + { ...judging(`b`, `fixed seed`, 1), fn: 1 }, + { ...judging(`a`, `fixed seed`, 1), fn: 2 }, + { ...judging(`b`, `fixed seed`, 1), fn: 2 }, + ], + witness: false, + authored: null, + secondAuthored: false, + fault: `none`, + stability: `none`, + ordinary: false, + native: `none`, + boot: false, + cliPath: `plain`, + concurrentStart: false, + lazyGate: false, + fsRead: `none`, + prePlugin: false, + inputRead: `none`, + keepStamp: false, + laterSteps: NO_LATER_STEPS, + inputSteps: NO_INPUT_STEPS, + steps: [`recheck`, `restart`], + storeLimit: true, + }), + }, ]), }, resolve: resolveHistory, diff --git a/packages/oracles/oracle-gaps/history-fingerprint.json b/packages/oracles/oracle-gaps/history-fingerprint.json index 82e70e6b..c920feb3 100644 --- a/packages/oracles/oracle-gaps/history-fingerprint.json +++ b/packages/oracles/oracle-gaps/history-fingerprint.json @@ -83,7 +83,8 @@ ["optionalChains", "92f0ef0b4dde6c60"], ["inputRead", "5684eb5ba5dfefcd"], ["keepStamp", "56ab48b583bcfac8"], - ["inputSteps", "d0b00193871ff120"] + ["inputSteps", "d0b00193871ff120"], + ["storeLimit", "ed6866229ecc4969"] ], "histories": [ ["functions", "66c0e9c56951c377"], @@ -169,6 +170,7 @@ ["optionalChains", "92f0ef0b4dde6c60"], ["inputRead", "5684eb5ba5dfefcd"], ["keepStamp", "56ab48b583bcfac8"], - ["inputSteps", "d0b00193871ff120"] + ["inputSteps", "d0b00193871ff120"], + ["storeLimit", "ed6866229ecc4969"] ] } diff --git a/packages/oracles/scripts/e2e-shards.mjs b/packages/oracles/scripts/e2e-shards.mjs index 05330860..fad422a0 100644 --- a/packages/oracles/scripts/e2e-shards.mjs +++ b/packages/oracles/scripts/e2e-shards.mjs @@ -156,6 +156,9 @@ export const shards = { "fixed seed 20261105: a hand edit of a file the config's plugin writes", "random seed: a hand edit of a file the config's plugin writes", "determinism: constructed history: a hand edit of a file the config's plugin writes", + 'fixed seed 20261105: a daemon store longer than the string limit, reloaded after a restart', + 'random seed: a daemon store longer than the string limit, reloaded after a restart', + 'determinism: constructed history: a daemon store longer than the string limit, reloaded after a restart', // Added with the CLI's parent-config discovery (not yet measured). `fixed seed 20261105: a package whose parent directory has its config`, `random seed: test.projects in a parent's config`, diff --git a/packages/oracles/scripts/pr-shards.mjs b/packages/oracles/scripts/pr-shards.mjs index ec1041cc..258d9879 100644 --- a/packages/oracles/scripts/pr-shards.mjs +++ b/packages/oracles/scripts/pr-shards.mjs @@ -42,6 +42,8 @@ const daemonInputUnits = [ "an edit to the tsconfig that Vite's own plugin reads", 'an edit to a directory the config lists when it loads', "a hand edit of a file the config's plugin writes", + // The evidence store under a test string limit (#179). + 'a daemon store longer than the string limit, reloaded after a restart', ] const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, `\\$&`) const anyOf = (names) => `(?:${names.map(escape).join(`|`)})` @@ -885,6 +887,7 @@ export const partitions = { daemonInputUnits[0], daemonInputUnits[1], daemonInputUnits[9], + daemonInputUnits[12], ]), 7: anyOf([ 'a daemon pause that cannot engage', From 6b2a085333e63e7e47e5e7438fdd52d425d9fc4e Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Thu, 19 Nov 2026 07:27:34 -0800 Subject: [PATCH 24/34] fix(oracle-gaps): the evidence store is written and read one row per line (#179) The store is now evidence.jsonl, one JSON row per line. A flush writes each row to the temporary file in turn, and opening reads the file as bytes and parses each line alone, so no string holds the whole store and a suite's store can pass V8's string limit. The driver's view of the stored inputs reads the new file. An earlier evidence.json is not read: the first daemon after the change starts cold. GREEN: "a daemon store longer than the string limit, reloaded after a restart" passes. Mutants: a flush that joins the rows into one string fails after start; an open that reads the file as one string fails after restart. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/evidence.mjs | 52 +++++++++++++------ .../gap-report-oracle.property.test.mjs | 13 +++-- 2 files changed, 46 insertions(+), 19 deletions(-) diff --git a/packages/oracles/oracle-gaps/evidence.mjs b/packages/oracles/oracle-gaps/evidence.mjs index dd0f01ee..89c4ae19 100644 --- a/packages/oracles/oracle-gaps/evidence.mjs +++ b/packages/oracles/oracle-gaps/evidence.mjs @@ -1,17 +1,19 @@ // The evidence store: units of evidence by identity (check.mjs). // // A cold run keeps its units in memory and drops them. The daemon keeps them -// in a JSON file on disk, so a daemon that restarts reuses what an earlier one +// in a file of JSON rows on disk, so a daemon that restarts reuses what an earlier one // ran. The store is a cache over the evidence a check reports, never the // record: a stored unit is used only while every input it recorded is // unchanged. import { + closeSync, existsSync, mkdirSync, + openSync, readFileSync, renameSync, rmSync, - writeFileSync, + writeSync, } from 'node:fs' import { createHash } from 'node:crypto' import { tmpdir } from 'node:os' @@ -81,22 +83,36 @@ function storeString(text) { } /** - * A store in `/evidence.json`. It reads the file once, when it opens. - * `put` changes the rows in memory, and `flush` writes every row to a - * temporary file and renames it over the store, so a crash during a write - * leaves the previous version whole. The daemon flushes after each check and - * on close. + * The rows of the store file `file`, one JSON row per line. The file is read + * as bytes and each line parsed alone, so no string holds the whole store, + * which can pass V8's string limit on a large suite (#179). JSON escapes + * every line break inside a row. + */ +function readRows(file) { + const bytes = readFileSync(file) + const rows = [] + for (let start = 0; start < bytes.length;) { + const end = bytes.indexOf(0x0a, start) + const stop = end === -1 ? bytes.length : end + if (stop > start) + rows.push(JSON.parse(storeString(bytes.toString(`utf8`, start, stop)))) + start = stop + 1 + } + return rows +} + +/** + * A store in `/evidence.jsonl`, one row per line. It reads the file + * once, when it opens. `put` changes the rows in memory, and `flush` writes + * each row to a temporary file and renames it over the store, so a crash + * during a write leaves the previous version whole. The daemon flushes after + * each check and on close. */ export async function diskStore(dir) { mkdirSync(dir, { recursive: true }) - const file = join(dir, `evidence.json`) + const file = join(dir, `evidence.jsonl`) const rows = new Map( - existsSync(file) - ? JSON.parse(storeString(readFileSync(file, `utf8`))).map((row) => [ - row.id, - row, - ]) - : [], + existsSync(file) ? readRows(file).map((row) => [row.id, row]) : [], ) let dirty = false return { @@ -110,7 +126,13 @@ export async function diskStore(dir) { // The OS may have cleaned the temp directory that holds the store. mkdirSync(dir, { recursive: true }) const temporary = `${file}.${process.pid}.tmp` - writeFileSync(temporary, storeString(JSON.stringify([...rows.values()]))) + const fd = openSync(temporary, `w`) + try { + for (const row of rows.values()) + writeSync(fd, `${storeString(JSON.stringify(row))}\n`) + } finally { + closeSync(fd) + } renameSync(temporary, file) dirty = false }, 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 75ef7c3c..080bc407 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -2474,11 +2474,16 @@ const waitGone = async (pid) => { * evidence store (evidence.mjs), or none when it has stored nothing. */ function storedInputs(dir) { - const file = join(stateDirOf(realpathSync(dir)), `evidence.json`) + const file = join(stateDirOf(realpathSync(dir)), `evidence.jsonl`) if (!existsSync(file)) return [] - return JSON.parse(readFileSync(file, `utf8`)).flatMap((row) => - row.variants.flatMap((variant) => variant.inputs.map(([path]) => path)), - ) + return readFileSync(file, `utf8`) + .split(`\n`) + .filter((line) => line !== ``) + .flatMap((line) => + JSON.parse(line).variants.flatMap((variant) => + variant.inputs.map(([path]) => path), + ), + ) } function daemonsOf(dir) { From 3b69867ae97b410f78fda1c64ac30d2c64b02948 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Thu, 19 Nov 2026 07:30:30 -0800 Subject: [PATCH 25/34] test(oracle-gaps): a file a test's child process wrote is no input, oracle first Under "Own writes aren't inputs" (M 2026-11-17) and "Optimize #133 before merging" (M 2026-11-19), a file that a test's own process tree wrote earlier in the check is the tree's output. The drawn field `childWrite` (appended last, 1 in 8) makes file b, as it loads, read a file that a node grandchild of its test wrote in a new temporary directory, then remove the directory. One constructed history, appended last, rechecks such a state through the daemon: `unchanged reuse` owes no computed run. TanStack DB's error-docs and oracle-replay tests read what their children write this way. RED here: the check through the daemon at recheck, of a state that nothing changed, computed 2 runs that were not cut off, owed none. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-model-oracle.mjs | 37 +++++++++++ .../gap-report-oracle.property.test.mjs | 61 +++++++++++++++++++ .../oracle-gaps/history-fingerprint.json | 6 +- packages/oracles/scripts/e2e-shards.mjs | 3 + packages/oracles/scripts/pr-shards.mjs | 3 + 5 files changed, 108 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 5e93431a..310afe5e 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -1181,6 +1181,26 @@ const drawn = fc.record({ // "a daemon store longer than the string limit, reloaded after a restart" // sets it. storeLimit: fc.constant(false), + // Whether file b, as it loads, reads a file that its test's own child + // process wrote: a node child starts a node grandchild, which writes the + // file in a new temporary directory and prints the directory, and file b + // reads the file and removes the directory. A file that the test's own + // process tree wrote earlier in the check is its own output, no input + // (maintainer decisions "Own writes aren't inputs", 2026-11-17, and + // "Optimize #133 before merging", 2026-11-19), so an unchanged recheck + // through the daemon reuses file b's runs although the directory differs + // in every run. It changes what a history runs, so it is drawn (randomness + // wins, 2026-11-16), and last. + childWrite: fc.constantFrom( + false, + false, + false, + false, + false, + false, + false, + true, + ), }) // The edit sequence over the witness module, the one list of steps that a @@ -3520,6 +3540,7 @@ function resolveHistory(history) { slowStart: history.slowStart ?? false, shortWait: history.shortWait === true, storeLimit: history.storeLimit === true, + childWrite: history.childWrite === true, // The gate input that file b's verdicts also wait on (`inputRead`), and // whether each write of a gate file keeps its size and modification time // (`keepStamp`). @@ -5462,6 +5483,21 @@ const inputReads = { `const readInput = async () => { const dir = openGate(new URL('./gate-dir/', import.meta.url)); const names: Array = []; for (let entry = dir.readSync(); entry; entry = dir.readSync()) names.push(entry.name); dir.closeSync(); return { open: names.includes('open') } }`, ], } +// File b's read of a file that its test's child process tree wrote +// (`childWrite`): the grandchild writes `child.txt` in a new directory under +// the OS temporary directory and prints the directory, which the child +// passes on; file b checks the text and removes the directory. +const CHILD_WRITE = `const fs = require('node:fs'), os = require('node:os'), path = require('node:path'); const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gap-child-')); fs.writeFileSync(path.join(dir, 'child.txt'), 'written'); process.stdout.write(dir)` +const CHILD_START = `process.stdout.write(require('node:child_process').execFileSync(process.execPath, ['-e', ${JSON.stringify(CHILD_WRITE)}], { encoding: 'utf8' }))` +const childWriteRead = [ + `import { execFileSync as runChild } from 'node:child_process'`, + `import { readFileSync as readChild, rmSync as removeChild } from 'node:fs'`, + `import { join as joinChild } from 'node:path'`, + `const childDir = runChild(process.execPath, ['-e', ${JSON.stringify(CHILD_START)}], { encoding: 'utf8' })`, + `const childText = readChild(joinChild(childDir, 'child.txt'), 'utf8')`, + `removeChild(childDir, { recursive: true, force: true })`, + `if (childText !== 'written') throw new Error('the child process wrote another text')`, +] /** The variables a check of `state` runs with: the gate's, under `env`. */ const inputEnv = (plan, state) => plan.inputRead === `env` @@ -5573,6 +5609,7 @@ function oracleTestFile(plan, file) { ...(file === `b` && plan.inputRead !== `none` ? inputReads[plan.inputRead] : []), + ...(file === `b` && plan.childWrite ? childWriteRead : []), ...stubs, // State that tests of this file share (the `w_shared` witness). `const shared = { value: 0 }`, 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 080bc407..fce67f36 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -2850,6 +2850,13 @@ async function incremental(dir, plan, cli, copy, observe, states) { states.add( `an unchanged check through the daemon computed nothing while a test read a source through fs`, ) + // File b read a file that its test's child process tree wrote, in a + // new temporary directory each run: the file is the tree's own output, + // so the unchanged recheck reused b's runs (`childWrite`). + if (plan.childWrite) + states.add( + `an unchanged check through the daemon computed nothing while a test read what its child process wrote`, + ) } // A daemon check after an edit that computed fewer runs cut off by their // call budget than the cold run of the same state reused such a run, so @@ -6565,6 +6572,7 @@ const required = [ `a slow daemon start was served by the daemon`, `a check abandoned while a context warmed in place of a cut one wrote nothing more`, `a daemon reloaded a store longer than the string limit`, + `an unchanged check through the daemon computed nothing while a test read what its child process wrote`, ] // The faults the CLI analyzes anyway: a package's TypeScript is no input. const analyzedFaults = [`noTypescript`, `apiLessTypescript`] @@ -7100,6 +7108,8 @@ oracleProperty({ inputRead: `none`, keepStamp: false, inputSteps: NO_INPUT_STEPS, + storeLimit: false, + childWrite: false, stopRuns: NO_STOPS, laterSteps: NO_LATER_STEPS, }, @@ -9705,6 +9715,57 @@ oracleProperty({ storeLimit: true, }), }, + { + // A file that the test's own child process tree wrote earlier in the + // check is no input of the test (maintainer decisions "Own writes + // aren't inputs", 2026-11-17, and "Optimize #133 before merging", + // 2026-11-19): file b reads, as it loads, a file that a node + // grandchild of its test wrote in a new temporary directory, so the + // unchanged recheck through the daemon must reuse b's runs although + // the file's path differs in every run (`unchanged reuse`). + name: `a test that reads a file its child process wrote, rechecked through the daemon`, + enters: [ + `an unchanged check through the daemon computed nothing`, + `an unchanged check through the daemon computed nothing while a test read what its child process wrote`, + ], + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`b`], + library: [], + libraryOwners: [], + runes: [], + derived: null, + dotGen: false, + dataOwners: [], + exportOwners: [], + importer: `none`, + wholeFile: `none`, + template: false, + tests: [{ ...judging(`b`, `fixed seed`, 1), fn: 0 }], + witness: false, + authored: null, + secondAuthored: false, + fault: `none`, + stability: `none`, + ordinary: false, + native: `none`, + boot: false, + cliPath: `plain`, + concurrentStart: false, + lazyGate: false, + fsRead: `none`, + prePlugin: false, + inputRead: `none`, + keepStamp: false, + laterSteps: NO_LATER_STEPS, + inputSteps: NO_INPUT_STEPS, + steps: [`recheck`], + childWrite: true, + }), + }, ]), }, resolve: resolveHistory, diff --git a/packages/oracles/oracle-gaps/history-fingerprint.json b/packages/oracles/oracle-gaps/history-fingerprint.json index c920feb3..09db4fde 100644 --- a/packages/oracles/oracle-gaps/history-fingerprint.json +++ b/packages/oracles/oracle-gaps/history-fingerprint.json @@ -84,7 +84,8 @@ ["inputRead", "5684eb5ba5dfefcd"], ["keepStamp", "56ab48b583bcfac8"], ["inputSteps", "d0b00193871ff120"], - ["storeLimit", "ed6866229ecc4969"] + ["storeLimit", "ed6866229ecc4969"], + ["childWrite", "b5de417f8ab99e7a"] ], "histories": [ ["functions", "66c0e9c56951c377"], @@ -171,6 +172,7 @@ ["inputRead", "5684eb5ba5dfefcd"], ["keepStamp", "56ab48b583bcfac8"], ["inputSteps", "d0b00193871ff120"], - ["storeLimit", "ed6866229ecc4969"] + ["storeLimit", "ed6866229ecc4969"], + ["childWrite", "b5de417f8ab99e7a"] ] } diff --git a/packages/oracles/scripts/e2e-shards.mjs b/packages/oracles/scripts/e2e-shards.mjs index fad422a0..13e415db 100644 --- a/packages/oracles/scripts/e2e-shards.mjs +++ b/packages/oracles/scripts/e2e-shards.mjs @@ -159,6 +159,9 @@ export const shards = { 'fixed seed 20261105: a daemon store longer than the string limit, reloaded after a restart', 'random seed: a daemon store longer than the string limit, reloaded after a restart', 'determinism: constructed history: a daemon store longer than the string limit, reloaded after a restart', + 'fixed seed 20261105: a test that reads a file its child process wrote, rechecked through the daemon', + 'random seed: a test that reads a file its child process wrote, rechecked through the daemon', + 'determinism: constructed history: a test that reads a file its child process wrote, rechecked through the daemon', // Added with the CLI's parent-config discovery (not yet measured). `fixed seed 20261105: a package whose parent directory has its config`, `random seed: test.projects in a parent's config`, diff --git a/packages/oracles/scripts/pr-shards.mjs b/packages/oracles/scripts/pr-shards.mjs index 258d9879..8ba40dad 100644 --- a/packages/oracles/scripts/pr-shards.mjs +++ b/packages/oracles/scripts/pr-shards.mjs @@ -44,6 +44,8 @@ const daemonInputUnits = [ "a hand edit of a file the config's plugin writes", // The evidence store under a test string limit (#179). 'a daemon store longer than the string limit, reloaded after a restart', + // A file the test's child process wrote (own writes of the process tree). + 'a test that reads a file its child process wrote, rechecked through the daemon', ] const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, `\\$&`) const anyOf = (names) => `(?:${names.map(escape).join(`|`)})` @@ -888,6 +890,7 @@ export const partitions = { daemonInputUnits[1], daemonInputUnits[9], daemonInputUnits[12], + daemonInputUnits[13], ]), 7: anyOf([ 'a daemon pause that cannot engage', From f4df874326008138e9483d1878ba9a994e2cc850 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Thu, 19 Nov 2026 07:31:25 -0800 Subject: [PATCH 26/34] test(oracle-gaps): the child-written file is also tested for existence before it is read A stat of a file that the test's process tree wrote is a read of that file too (G42's stat family), so it is no input either. RED still: the unchanged recheck computes file b's runs. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/gap-report-model-oracle.mjs | 7 +++++-- 1 file changed, 5 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 310afe5e..2e235318 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -5486,14 +5486,17 @@ const inputReads = { // File b's read of a file that its test's child process tree wrote // (`childWrite`): the grandchild writes `child.txt` in a new directory under // the OS temporary directory and prints the directory, which the child -// passes on; file b checks the text and removes the directory. +// passes on; file b tests that the file exists, which is a read of it by +// existence and kind (G42's stat family), checks its text, and removes the +// directory. const CHILD_WRITE = `const fs = require('node:fs'), os = require('node:os'), path = require('node:path'); const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gap-child-')); fs.writeFileSync(path.join(dir, 'child.txt'), 'written'); process.stdout.write(dir)` const CHILD_START = `process.stdout.write(require('node:child_process').execFileSync(process.execPath, ['-e', ${JSON.stringify(CHILD_WRITE)}], { encoding: 'utf8' }))` const childWriteRead = [ `import { execFileSync as runChild } from 'node:child_process'`, - `import { readFileSync as readChild, rmSync as removeChild } from 'node:fs'`, + `import { existsSync as childExists, readFileSync as readChild, rmSync as removeChild } from 'node:fs'`, `import { join as joinChild } from 'node:path'`, `const childDir = runChild(process.execPath, ['-e', ${JSON.stringify(CHILD_START)}], { encoding: 'utf8' })`, + `if (!childExists(joinChild(childDir, 'child.txt'))) throw new Error('the child process wrote no file')`, `const childText = readChild(joinChild(childDir, 'child.txt'), 'utf8')`, `removeChild(childDir, { recursive: true, force: true })`, `if (childText !== 'written') throw new Error('the child process wrote another text')`, From 38b67370d9b36c85d48b0162bdd3bc7a9e3c29eb Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Thu, 19 Nov 2026 07:50:17 -0800 Subject: [PATCH 27/34] test(oracle-gaps): the store-limit and child-write states belong to their own histories "every outcome class" enters every required state that no history owns alone; the two new states have their own constructed histories, so they join `separate`. 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 fce67f36..e5b6e50f 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -6694,6 +6694,10 @@ const separate = [ `a check through the daemon worked past its CLI's bound`, `a slow daemon start was served by the daemon`, `a check abandoned while a context warmed in place of a cut one wrote nothing more`, + // Each has its own constructed history (#179; own writes of the test's + // process tree). + `a daemon reloaded a store longer than the string limit`, + `an unchanged check through the daemon computed nothing while a test read what its child process wrote`, ] // A stop by SIGTERM exists only where Node can deliver it: on win32 kill is // TerminateProcess, so there the stop law is judged by SIGINT (the test stop From f754fbd4f732ef7357434c962141703d93691314 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Thu, 19 Nov 2026 07:52:02 -0800 Subject: [PATCH 28/34] fix(oracle-gaps): a file a test's child processes wrote is the test's own output Every Node process that a test starts preloads child-writes.mjs through NODE_OPTIONS, which its own children inherit, and appends the key of each file it writes to the copy's log in the session directory. The harness reads that log before it records a read, so a file that the test's process tree wrote earlier in the check is no input, whether the test reads its text or tests whether it exists (a stat of an own-written file is a read of it too). This closes #143's write side. GREEN: "a test that reads a file its child process wrote, rechecked through the daemon" passes. Mutants: a child that logs no write, and an own-output test that ignores stats, each fail the unchanged recheck (computed 2 runs, owed none). Co-authored-by: Isaac --- .changeset/gap-cli-daemon-every-read.md | 2 + README.md | 9 ++++- .../oracles/oracle-gaps/capture-setup.mjs | 38 ++++++++++++++++++- packages/oracles/oracle-gaps/check.mjs | 5 ++- packages/oracles/oracle-gaps/child-writes.mjs | 19 ++++++++++ 5 files changed, 68 insertions(+), 5 deletions(-) create mode 100644 packages/oracles/oracle-gaps/child-writes.mjs diff --git a/.changeset/gap-cli-daemon-every-read.md b/.changeset/gap-cli-daemon-every-read.md index 2e8394f4..09a8ade2 100644 --- a/.changeset/gap-cli-daemon-every-read.md +++ b/.changeset/gap-cli-daemon-every-read.md @@ -7,3 +7,5 @@ A check through `--daemon` now treats every read as an input of the runs that ma The daemon now runs each check in the environment of the CLI that asked for it. A check from another environment, or after a file that Vitest, the config, or a plugin read or wrote has changed, starts a new daemon. Because Vitest and Vite read every environment variable while they start, any change to the environment runs every unit again, as a cold run does. Each check now hashes every file input from its content, so an edit that keeps a file's size and modification time, as `cp -p`, `rsync -t`, or `touch -r` leave it, is no longer missed. + +A file that a test, or a Node process it started at any depth, wrote before the test read it is the test's own output and no input, so a test whose child writes a temporary file is reused on an unchanged check. The daemon's evidence store is now written and read one row per line, so a large suite's store no longer fails every check with "Invalid string length". diff --git a/README.md b/README.md index 24c2de97..bbde7f3d 100644 --- a/README.md +++ b/README.md @@ -251,8 +251,13 @@ runs cold` and runs the check in its own process, which reports what the the config read in the CLI's process, while Vitest loads and the contexts warm, and in each hook of every plugin, Vite's own (such as the `tsconfig.json` that its esbuild plugin reads) and the config's alike. A - file that a reader wrote earlier in the check, before it read it, is its - own output and no input (maintainer decision, 2026-11-17); a file the + file that a reader wrote earlier in the check, before it read it or tested + whether it exists, is its own output and no input (maintainer decision, + 2026-11-17). For a test, that includes a file that a Node process it + started wrote, at any depth: each such process preloads the runner's + write log through `NODE_OPTIONS` (maintainer decision, 2026-11-19). A + child started with an environment that drops `NODE_OPTIONS`, or a writer + that is not Node, is not seen, so its file stays an input. A file the session wrote that is edited by hand afterwards is seen. Each check hashes every file input from its content, so an edit that keeps a file's size and modification time (`cp -p`, `rsync -t`, `touch -r`) is seen. A run that an diff --git a/packages/oracles/oracle-gaps/capture-setup.mjs b/packages/oracles/oracle-gaps/capture-setup.mjs index 341db51b..f023f6bf 100644 --- a/packages/oracles/oracle-gaps/capture-setup.mjs +++ b/packages/oracles/oracle-gaps/capture-setup.mjs @@ -27,6 +27,8 @@ import { createHash } from 'node:crypto' import { appendFileSync, readFileSync } from 'node:fs' import { createRequire, syncBuiltinESMExports } from 'node:module' import { dirname, isAbsolute, join } from 'node:path' +import { fileURLToPath } from 'node:url' +import { threadId } from 'node:worker_threads' import { afterAll, beforeEach, chai, expect, inject, vi } from 'vitest' import { inputHash, keepProperties, watchReads } from './inputs.mjs' import { writeWhole } from './paths.mjs' @@ -278,15 +280,47 @@ function appendClosingRow(row) { // run is stored under the text it read and not under an edit that lands // later in the run (review of #55, F1). A variable's hash is the runner's, // from the environment it gives the check (check.mjs, servedHash). A file -// the copy wrote before it read it is its own output, no input. +// that the copy, or a process it started at any depth, wrote before the copy +// read it is its own output, no input, whether the copy reads its text or +// tests whether it exists (`stat:`). globalThis.__oracleGapsReads = new Map() const wrote = new Set() +// The child processes' writes: every Node process a test starts preloads +// child-writes.mjs, which each of its own children inherits through +// NODE_OPTIONS, and appends the key of each file it writes to this copy's +// log, in the session directory beside this file. +const childLog = join( + dirname(fileURLToPath(import.meta.url)), + `child-writes-${process.pid}-${threadId}-${(globalThis.__oracleGapsCopies = (globalThis.__oracleGapsCopies ?? 0) + 1)}.log`, +) +let childRead = 0 +/** Whether the copy or a process it started wrote the file `key` names. */ +function ownOutput(key) { + const file = key.replace(/^stat:/, `fs:`) + if (wrote.has(file)) return true + let text + try { + text = globalThis.__oracleGapsOriginalFs.readFileSync(childLog, `utf8`) + } catch { + return false + } + for (const line of text.slice(childRead).split(`\n`)) + if (line !== ``) wrote.add(line) + childRead = text.length + return wrote.has(file) +} watchReads((key, write) => { const reads = globalThis.__oracleGapsReads if (write) wrote.add(key) - else if (!reads.has(key) && !wrote.has(key)) + else if (!reads.has(key) && !wrote.has(key) && !ownOutput(key)) reads.set(key, key.startsWith(`env:`) ? null : inputHash(key)) }) +if (!globalThis.__oracleGapsChildren) { + globalThis.__oracleGapsChildren = true + process.env.NODE_OPTIONS = + `${process.env.NODE_OPTIONS ?? ``} --import=${new URL(`./child-writes.mjs`, import.meta.url).href}`.trim() +} +process.env.ORACLE_GAPS_CHILD_WRITES = childLog // A test's own writes to the process's stdout and stderr (a debugging // `process.stdout.write`) go to the run's test-output.log, beside its // capture, not to the CLI's streams, whose every line is a line of the diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index c56b8260..6f925fa7 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -161,6 +161,7 @@ const ownFiles = [ `authored.mjs`, `capture-setup.mjs`, `inputs.mjs`, + `child-writes.mjs`, `paths.mjs`, `evidence.mjs`, `daemon.mjs`, @@ -596,9 +597,11 @@ export async function openSession(pkg, pause = async () => {}) { writeFileSync(join(home, `host`), hostname()) const harness = join(home, `capture-setup.mjs`) copyFileSync(join(here, `capture-setup.mjs`), harness) - // The harness imports the input rule and the path rule beside it + // The harness imports the input rule and the path rule beside it, and + // preloads the child-write log into the processes a test starts // (capture-setup.mjs). copyFileSync(join(here, `inputs.mjs`), join(home, `inputs.mjs`)) + copyFileSync(join(here, `child-writes.mjs`), join(home, `child-writes.mjs`)) copyFileSync(join(here, `paths.mjs`), join(home, `paths.mjs`)) // One wrapper config per context, over the package's own config (a path // relative to the package, or undefined for none). Each serves its own diff --git a/packages/oracles/oracle-gaps/child-writes.mjs b/packages/oracles/oracle-gaps/child-writes.mjs new file mode 100644 index 00000000..7a2fce60 --- /dev/null +++ b/packages/oracles/oracle-gaps/child-writes.mjs @@ -0,0 +1,19 @@ +// What a test's own child processes write, at any depth. The harness +// (capture-setup.mjs) preloads this file into every Node process that a test +// starts (`--import` in NODE_OPTIONS, which each child passes on to its own +// children) and names a log per copy (ORACLE_GAPS_CHILD_WRITES). Each file +// that such a process writes goes into the log as its input key, before the +// write, so the copy knows that a later read of it reads its own process +// tree's output, which is no input (maintainer decisions "Own writes aren't +// inputs", 2026-11-17, and "Optimize #133 before merging", 2026-11-19). +// The log is written through a file descriptor, which no wrapper watches. +import { openSync, writeSync } from 'node:fs' +import { watchReads } from './inputs.mjs' + +const log = process.env.ORACLE_GAPS_CHILD_WRITES +if (log) { + const fd = openSync(log, `a`) + watchReads((key, write) => { + if (write && key.startsWith(`fs:`)) writeSync(fd, `${key}\n`) + }) +} From ab06f52443f6a6561d3c006bb20edfca666ca2fb Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Thu, 19 Nov 2026 07:57:47 -0800 Subject: [PATCH 29/34] perf(oracle-gaps): inputs that many units read alike are stored once per set A unit's variables and files under node_modules move into one stored set per distinct list (`shared:`, a store row), which the unit names in place of them; the set holds while each of its inputs holds, judged once per check and context. A unit keeps only its own inputs (M "Optimize #133 before merging", 2026-11-19). No reuse rule changes: a set is changed as soon as one of its inputs is. The 14 daemon-input units pass. Mutant: a set that always holds fails "an edit to a file under node_modules that a test reads" (the env kind restarts the daemon, so it does not see the set). Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 39 +++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index 6f925fa7..e20916bb 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -718,12 +718,33 @@ export default async (env) => { const [, id, n] = path.split(`:`) return logHolds(id, Number(n)) >= Number(n) ? `held` : `changed` } + if (path.startsWith(`shared:`)) return sharedHolds(path, index) if (/^(dir|dirs|stat):/.test(path)) return inputHash(path) const text = globalThis.__oracleGapsServe[index]?.get(path) ?? globalThis.__oracleGapsSchemata.get(path) return text === undefined ? hashOf(path) : sha1(text) } + // The inputs that many units read alike, a variable or a file under + // node_modules, are stored once per distinct set (`shared:`, a row + // of the store) and named by each unit that read them (sharedInputs), so + // a unit keeps only the inputs that are its own (review of #133, M + // "Optimize #133 before merging"). A set holds while each of its inputs + // holds its hash, judged once per check and context. + const shared = new Map() + const sharedHolds = (path, index) => { + const key = `${path}:${index}` + if (!shared.has(key)) { + const inputs = currentStore?.get(path)?.variants[0]?.inputs + shared.set( + key, + inputs?.every(([input, hash]) => servedHash(input, index) === hash) + ? `held` + : `changed`, + ) + } + return shared.get(key) + } // How much of a session's hook log, from its start, still holds its // hashes in this check: a unit that names `hooks::` is unchanged // while the first n reads hold. Another session's log is read from the @@ -1720,6 +1741,7 @@ export default async (env) => { hashOf.forget() wrote.clear() holds.clear() + shared.clear() currentStore = store const authored = options.mutants ? loadAuthored(options.mutants) : [] seedVariable = `${options.envPrefix}_SEED` @@ -1944,10 +1966,25 @@ export default async (env) => { } const remember = (id, unit, inputs) => { if (!inputs) return - const entry = { inputs, unit } + const entry = { inputs: sharedInputs(inputs), unit } hook?.stored(entry) store.put(id, entry) } + // A unit's inputs with those that many units read alike (see + // sharedHolds) moved into one stored set, which the unit names. + const sharedInputs = (inputs) => { + const common = [] + const own = [] + for (const input of inputs) + (input[0].startsWith(`env:`) || input[0].includes(`/node_modules/`) + ? common + : own + ).push(input) + if (common.length < 2) return inputs + const path = `shared:${sha1(JSON.stringify(common))}` + if (!store.get(path)) store.put(path, { inputs: common, unit: null }) + return [...own, [path, `held`]] + } // 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 // loaded beyond them, as a mutated branch can import a module. From a2ecb43fc90c65622494ba9f86970ebe45034b11 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Thu, 19 Nov 2026 09:18:08 -0800 Subject: [PATCH 30/34] test(oracle-gaps): a child-writing test in a client-transform environment, oracle first On TanStack DB (jsdom) every test that starts a Node child failed under the CLI: Vite's client transform rewrites the harness's `new URL('./child-writes.mjs', import.meta.url)` to a URL of the dev server, and the child's `--import=http://localhost:3000/...` fails (ERR_UNSUPPORTED_ESM_URL_SCHEME). The grammar ran every file in the config's node environment. The drawn field `childEnvironment` (appended last) puts file b, when it reads what its child wrote and reads no gate input or data, in a custom environment with `viteEnvironment: 'client'`; the constructed child-write history takes it. RED here: the stream's decisive baseline lines are ["oracle-gaps: baseline 1 of 2 oracle files failed (provisional)"], owed ["oracle-gaps: baseline all 2 oracle files pass"]. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-model-oracle.mjs | 37 +++++++++++++++++++ .../gap-report-oracle.property.test.mjs | 4 ++ .../oracle-gaps/history-fingerprint.json | 6 ++- 3 files changed, 45 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 2e235318..0138832e 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -1201,6 +1201,16 @@ const drawn = fc.record({ false, true, ), + // The Vite environment that file b runs in when it reads what its child + // process wrote (`childWrite`): the config's (`node`), or one that + // transforms its modules for the client (`client`), as a jsdom + // environment does. The client transform rewrites `new URL(, + // import.meta.url)` to a URL of the dev server, in the harness that runs in + // the file's environment too, so the harness's own path to the child + // preload must not take that form (TanStack DB's jsdom suite). Only file b + // takes it, and only where it reads no gate input or data, whose paths + // take that form in the file's own text. + childEnvironment: fc.constantFrom(`node`, `node`, `node`, `client`), }) // The edit sequence over the witness module, the one list of steps that a @@ -3541,6 +3551,12 @@ function resolveHistory(history) { shortWait: history.shortWait === true, storeLimit: history.storeLimit === true, childWrite: history.childWrite === true, + childEnvironment: + history.childWrite === true && + (history.inputRead ?? `none`) === `none` && + (history.fsRead ?? `none`) === `none` + ? (history.childEnvironment ?? `node`) + : `node`, // The gate input that file b's verdicts also wait on (`inputRead`), and // whether each write of a gate file keeps its size and modification time // (`keepStamp`). @@ -5556,6 +5572,9 @@ function oracleTestFile(plan, file) { const out = [ // A per-file environment, which Vitest reads from the file's text. ...(plan.pragma && file === `a` ? [`// @vitest-environment marked`] : []), + ...(plan.childEnvironment === `client` && file === `b` + ? [`// @vitest-environment client-marked`] + : []), `import { ${plan.tests.some((t) => t.file === file && t.cleanupThrows) ? `afterEach, ` : ``}describe, expect, test${plan.tests.some((t) => t.file === file && (t.spies || t.timed === `spiedclock`)) ? `, vi` : ``} } from 'vitest'`, ...(plan.tests.some((t) => t.file === file && t.shrinks) ? [`import fc from 'fast-check'`] @@ -6492,6 +6511,24 @@ function fixtureFiles(plan, state = initialState(plan)) { ].join(`\n`), } : {}), + // The client-transform environment that file b names when it reads what + // its child process wrote (`childEnvironment`). + ...(plan.childEnvironment === `client` + ? { + [`${testRoot.environments ?? `node_modules`}/vitest-environment-client-marked/package.json`]: `${JSON.stringify({ name: `vitest-environment-client-marked`, type: `module`, exports: `./index.js` })}\n`, + [`${testRoot.environments ?? `node_modules`}/vitest-environment-client-marked/index.js`]: + [ + `export default {`, + ` name: 'client-marked',`, + ` viteEnvironment: 'client',`, + ` setup() {`, + ` return { teardown() {} }`, + ` },`, + `}`, + ``, + ].join(`\n`), + } + : {}), // A copy that a check which died left behind (the runner names its // copies `.oracle-gaps---`). It is no test file: a check // that took it for one would refuse the run. 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 e5b6e50f..edaed1bc 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -7114,6 +7114,7 @@ oracleProperty({ inputSteps: NO_INPUT_STEPS, storeLimit: false, childWrite: false, + childEnvironment: `node`, stopRuns: NO_STOPS, laterSteps: NO_LATER_STEPS, }, @@ -9768,6 +9769,9 @@ oracleProperty({ inputSteps: NO_INPUT_STEPS, steps: [`recheck`], childWrite: true, + // In an environment that transforms file b for the client, as a + // jsdom environment does (`childEnvironment`). + childEnvironment: `client`, }), }, ]), diff --git a/packages/oracles/oracle-gaps/history-fingerprint.json b/packages/oracles/oracle-gaps/history-fingerprint.json index 09db4fde..323cf38b 100644 --- a/packages/oracles/oracle-gaps/history-fingerprint.json +++ b/packages/oracles/oracle-gaps/history-fingerprint.json @@ -85,7 +85,8 @@ ["keepStamp", "56ab48b583bcfac8"], ["inputSteps", "d0b00193871ff120"], ["storeLimit", "ed6866229ecc4969"], - ["childWrite", "b5de417f8ab99e7a"] + ["childWrite", "b5de417f8ab99e7a"], + ["childEnvironment", "6f44f756ac5ac6ef"] ], "histories": [ ["functions", "66c0e9c56951c377"], @@ -173,6 +174,7 @@ ["keepStamp", "56ab48b583bcfac8"], ["inputSteps", "d0b00193871ff120"], ["storeLimit", "ed6866229ecc4969"], - ["childWrite", "b5de417f8ab99e7a"] + ["childWrite", "b5de417f8ab99e7a"], + ["childEnvironment", "6f44f756ac5ac6ef"] ] } From aae16d2813413c1f5560a44ae52622754ccbd11a Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Thu, 19 Nov 2026 09:27:34 -0800 Subject: [PATCH 31/34] fix(oracle-gaps): the child preload is named by a file URL built from the harness's path The harness built the preload's URL as `new URL('./child-writes.mjs', import.meta.url)`, which Vite's client transform rewrites to a dev-server URL. It now joins the preload to the session directory taken from `fileURLToPath(import.meta.url)` and names it with `pathToFileURL`. GREEN: the child-write history in the client environment passes. Mutant: the parent commit's `new URL` form, RED above. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/capture-setup.mjs | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/packages/oracles/oracle-gaps/capture-setup.mjs b/packages/oracles/oracle-gaps/capture-setup.mjs index f023f6bf..a1aa9c72 100644 --- a/packages/oracles/oracle-gaps/capture-setup.mjs +++ b/packages/oracles/oracle-gaps/capture-setup.mjs @@ -27,7 +27,7 @@ import { createHash } from 'node:crypto' import { appendFileSync, readFileSync } from 'node:fs' import { createRequire, syncBuiltinESMExports } from 'node:module' import { dirname, isAbsolute, join } from 'node:path' -import { fileURLToPath } from 'node:url' +import { fileURLToPath, pathToFileURL } from 'node:url' import { threadId } from 'node:worker_threads' import { afterAll, beforeEach, chai, expect, inject, vi } from 'vitest' import { inputHash, keepProperties, watchReads } from './inputs.mjs' @@ -289,8 +289,12 @@ const wrote = new Set() // child-writes.mjs, which each of its own children inherits through // NODE_OPTIONS, and appends the key of each file it writes to this copy's // log, in the session directory beside this file. +// The session directory, from this file's path. Not `new URL(, +// import.meta.url)`: a client-transform environment (jsdom) rewrites that +// form to a URL of Vite's dev server. +const home = dirname(fileURLToPath(import.meta.url)) const childLog = join( - dirname(fileURLToPath(import.meta.url)), + home, `child-writes-${process.pid}-${threadId}-${(globalThis.__oracleGapsCopies = (globalThis.__oracleGapsCopies ?? 0) + 1)}.log`, ) let childRead = 0 @@ -318,7 +322,7 @@ watchReads((key, write) => { if (!globalThis.__oracleGapsChildren) { globalThis.__oracleGapsChildren = true process.env.NODE_OPTIONS = - `${process.env.NODE_OPTIONS ?? ``} --import=${new URL(`./child-writes.mjs`, import.meta.url).href}`.trim() + `${process.env.NODE_OPTIONS ?? ``} --import=${pathToFileURL(join(home, `child-writes.mjs`)).href}`.trim() } process.env.ORACLE_GAPS_CHILD_WRITES = childLog // A test's own writes to the process's stdout and stderr (a debugging From a367794b5420c47143e98f8344e6e47699b7d1ad Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Thu, 19 Nov 2026 11:11:47 -0800 Subject: [PATCH 32/34] perf(oracle-gaps): a shared input set is keyed in one order The copies of a test file read the same modules and variables in different orders, so on TanStack DB's suite 559 units named 466 sets of about 458 inputs each, and the store grew to 576 MB against main's 444 MB. Sorting the set before it is keyed gives the copies of a file one set. The 14 daemon-input units pass. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index e20916bb..3bcf57bf 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -1981,6 +1981,9 @@ export default async (env) => { : own ).push(input) if (common.length < 2) return inputs + // In one order, so the copies of a file, which read the same modules + // in different orders, name one set. + common.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)) const path = `shared:${sha1(JSON.stringify(common))}` if (!store.get(path)) store.put(path, { inputs: common, unit: null }) return [...own, [path, `held`]] From 021cc06004f4cf0e5be502aed0000c22e4aa7013 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Thu, 19 Nov 2026 12:53:26 -0800 Subject: [PATCH 33/34] perf(oracle-gaps): a stored unit leaves out the hashes of what its copy read `readAt` (about 460 keys a unit on TanStack DB) is used only when a run settles, and the variant's inputs already hold those hashes, so the store drops it. Fixed-seed daemon histories (edit sequence, fs data, outside file, store limit, child write) pass. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index 3bcf57bf..2616b117 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -1964,7 +1964,9 @@ export default async (env) => { }) return stable ? inputs : undefined } - const remember = (id, unit, inputs) => { + // A unit is stored without the hashes of what its copy read (`readAt`), + // which only its settling used: the stored inputs hold them. + const remember = (id, { readAt, ...unit }, inputs) => { if (!inputs) return const entry = { inputs: sharedInputs(inputs), unit } hook?.stored(entry) From 6bc03d4b81cb3be13d9aafa2ff67156602964076 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Thu, 19 Nov 2026 15:15:03 -0800 Subject: [PATCH 34/34] perf(oracle-gaps): the session's hook log is stored again only when it grows Each check put the session's hook log into the store, which marked the store dirty, so the daemon wrote the whole store (about 490 MB on TanStack DB's suite) after every check, an unchanged one too. The log is now put only when it has grown since its last put. The 14 daemon-input units pass. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/check.mjs | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/packages/oracles/oracle-gaps/check.mjs b/packages/oracles/oracle-gaps/check.mjs index 2616b117..d317a24d 100644 --- a/packages/oracles/oracle-gaps/check.mjs +++ b/packages/oracles/oracle-gaps/check.mjs @@ -519,6 +519,8 @@ export async function openSession(pkg, pause = async () => {}) { // themselves (about 3,000 on TanStack DB's suite; review of #133). const hookLogId = sha1(`${process.pid}:${Date.now()}:${Math.random()}`) const hookLog = [] + // How much of the hook log the store holds (see check). + let hookLogStored = 0 // Per check: how far each session's log still holds (logHolds). const holds = new Map() const wrote = new Set() @@ -1713,12 +1715,15 @@ export default async (env) => { } finally { for (const key of wrote) if (key.startsWith(`fs:`)) written.set(key, inputHash(key)) - // The session's hook log, for units that later sessions look up. - if (hookLog.length > 0) + // The session's hook log, for units that later sessions look up, once + // it has grown: a put marks the store to be written again, whole. + if (hookLog.length > hookLogStored) { args[1]?.put(`hook-log:${hookLogId}`, { inputs: [...hookLog], unit: null, }) + hookLogStored = hookLog.length + } } } async function checkIn(