From 919c9a80fb39c8b0727eb5b14baf25075c0d0cf7 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Thu, 12 Nov 2026 20:17:04 -0700 Subject: [PATCH 01/62] test(oracle-gaps): law 15 owes a stream log that the first line names The maintainer's decision of 2026-11-12: an agent that runs a check in the background learns where to read its stream from the run itself. A run that starts a check names `/stream.log` in its first line on both streams (`oracle-gaps: note log `), and that file holds the stderr's lines, in order, cold, through the daemon, and after a stop or an abort. The driver records each run's first lines and whether its log equals its stderr; two calibrations give a log that misses a line and a naming line after another line. Co-authored-by: Isaac --- .../gap-report-oracle.property.test.mjs | 84 ++++++++++++++++++- packages/oracles/scripts/e2e-shards.mjs | 3 + 2 files changed, 83 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 f3f3a634..13281301 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -330,7 +330,12 @@ * The run's last line is its done line: `completed, gaps[ * (provisional)], report ` on stdout, `refused[, report * ]` after a refusal's block, or `stopped ()` - * after a stop. A check through the daemon streams the same lines. + * after a stop. A check through the daemon streams the same lines. The + * run's first line on both streams names its stream log, `oracle-gaps: + * note log /stream.log`, and that file holds the stderr's lines, in + * order, cold and through the daemon (the maintainer's decision of + * 2026-11-12: an agent that runs a check in the background learns from + * the run itself where to read it). * * Authority: the maintainer's decisions in the gap-check design runs v11, v14, * and v19 (2026-11-04 and 2026-11-05; the design notes are kept by the project @@ -699,7 +704,7 @@ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { writeFixture(dir, files) const before = new Set(filesUnder(dir)) const pids = mkdtempSync(join(realpathSync(tmpdir()), `gap-stop-`)) - const { args } = cliArgs(dir, files, { + const { args, out } = cliArgs(dir, files, { ...how, outName: `out-stop`, contexts: 1, @@ -809,6 +814,16 @@ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { [dir, ``], ]), ), + outDir: namedScratch(out, [ + [how.cli ?? here, ``], + [dir, ``], + ]), + log: streamLogOf(out, stderr, stdout, (text) => + namedScratch(text, [ + [how.cli ?? here, ``], + [dir, ``], + ]), + ), // The session directories in the package once it has ended: a stopped // run leaves its own, and the next run removes it. sessions: readdirSync(dir).filter((name) => @@ -950,6 +965,31 @@ const streamedGap = * or a heartbeat that names a mutant came before the first verdict; * - `last`: the last line, which ends a run that did not complete. */ +/** + * What the run's stream log says (the maintainer's decision of 2026-11-12: + * the CLI writes its stream to `/stream.log`, and its first line on + * both streams names that log), as relations: the first line of each + * stream, with scratch paths named, whether the log exists, and whether its + * lines are the stderr's lines, in order. + */ +function streamLogOf(out, stderr, stdout, name) { + const lines = (text) => `${text ?? ``}`.split(`\n`).filter(Boolean) + let log + try { + log = readFileSync(join(out, `stream.log`), `utf8`) + } catch { + // No log: the run wrote none. + } + return { + stderrFirst: name(lines(stderr)[0] ?? ``), + stdoutFirst: name(lines(stdout)[0] ?? ``), + exists: log !== undefined, + equal: + log !== undefined && + JSON.stringify(lines(log)) === JSON.stringify(lines(stderr)), + } +} + function streamOf(lines, name) { const kinds = new RegExp(`^oracle-gaps: (?:${streamKinds.join(`|`)}) `) const strays = new Set() @@ -1076,6 +1116,10 @@ function readRun(dir, out, status, stderr, cli, stdout) { // The output directory the run was given, as the trace names it: the // final line names its report there. outDir: namedScratch(out, scratch), + // The run's stream log, and the first line that names it. + log: streamLogOf(out, stderr, stdout, (text) => + namedScratch(text, scratch), + ), // Whether the run captured its tests' own console output there. captured: (() => { try { @@ -1297,6 +1341,9 @@ async function incremental(dir, plan, cli, copy, observe, states) { // The stream through the daemon (law 15): both streams' lines. stream: run.stream, stdoutStream: run.stdoutStream, + // Its stream log, and the output directory it names. + log: run.log, + outDir: run.outDir, // The first line of a failure, for the message; readRun has named // the scratch package and CLI copy in it. stderr: run.stderr?.split(`\n`)[0], @@ -2490,6 +2537,19 @@ function endsBreach(run) { [`stderr`, run.stream], [`stdout`, run.stdoutStream], ] + // The run's first line on each stream names its stream log, and the log + // holds the stderr's lines, in order (the maintainer's decision of + // 2026-11-12), for every run that starts a check: each of these does. + const note = `oracle-gaps: note log ${run.outDir}/stream.log` + if (run.log.stderrFirst !== note || run.log.stdoutFirst !== note) + return { + difference: `the run's first lines are ${JSON.stringify([run.log.stderrFirst, run.log.stdoutFirst])}, not ${JSON.stringify(note)} on each stream`, + } + if (!run.log.exists) return { difference: `the run wrote no stream.log` } + if (!run.log.equal) + return { + difference: `the run's stream.log is not its stderr, line for line`, + } for (const [where, stream] of streams) if (stream.strays.length > 0) return { @@ -2954,6 +3014,22 @@ calibrations.push( }, ), }, + { + name: `the stream log misses a line`, + law: `greppable stream`, + corrupt: corruptCli((cli) => ({ + ...cli, + log: { ...cli.log, equal: false }, + })), + }, + { + name: `the line that names the stream log comes after another line`, + law: `greppable stream`, + corrupt: corruptCli((cli) => ({ + ...cli, + log: { ...cli.log, stderrFirst: `oracle-gaps: config vite.config.ts` }, + })), + }, { name: `a stopped run ends without its done line`, law: `greppable stream`, @@ -3246,8 +3322,8 @@ const withDeclaration = (constructed) => oracleProperty({ id: `oracle-gaps.report`, 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).`, + 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, a first line on both streams that names the stream log in the output directory, which holds the stderr's lines in order, 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); the maintainer's decision of 2026-11-12 that the CLI writes its stream to the output directory's stream.log and names it in its first line.`, limits: `Law 12 judges refusals only: no legal history reaches an internal error, so its shape (exit 3, the stack in error.log) is not judged; argument refusals are the static oracle's; the check's rejection of a stack trace, a missing fix, and a wrong exit code is calibrated in the static oracle, through the same refusalBreach, and here only a refused run reported as complete is calibrated, because each calibration here runs real CLI histories. Hangs only as an owner test that awaits a promise that never settles, under a 1 s first budget and a 20 s full limit, and a slow run only as two witnesses whose tests wait where the output changed, 3 s in one that then judges and 10 s in two one-test owners of one that does not; busy loops only on instrumented code (cut by the call budget), no slow runs past the full limit that would end, hangs in ordinary or nondeterministic tests, setup errors other than a throw at module load, loops, multi-line conditions, two functions on one line, or await, new, and void statements; nested functions, object-literal methods, accessors, and class-field arrows only where no test calls them (their ownership is the static oracle's); two source files of one package, with no re-exports, namespace imports, or calls into another package; --only only in a stopped run and a partial run of one function's mutants, and no --sample or --diff-base; the baseline's failures only as one failing owner test that throws an error and a setup file that throws, so a baseline law violation's law and counterexample lines are the classify oracle's; a derived class's file is instrumented and its sites are judged as unowned, but no test imports or constructs the class, so its no-mutant and super-region behavior is the static oracle's (in-process), not this oracle's; package configs only as vite.config or vitest.config with one of the extensions .ts, .mts, .cts, .js, .mjs, and .cjs (not every pair), as config/gap-vitest with the same extension through --config, or none, as an object or a sync or async function, with no plugins of their own and test.projects only as a refusal, and only under the package's own package.json; a top-level await only in an ES module config and require only in a CommonJS one, as Vitest itself loads no other; a --config outside the package is refused by design, through the rule for paths outside the package (args.mjs), and no history generates one; contexts only one, four, or eleven, and process warnings judged only as MaxListenersExceededWarning on the CLI's own stderr (a daemon's process warnings go to its log); a context that fails to open gives back its listener allowance, which no observation shows (a kept allowance only raises the limit, so no warning follows), so that accounting is fixed by inspection; no probe-bound states, so reach agreement's killing of probe mutants is not checked; no gap answers or gate; law 9 judges the witness module's outcome classes along one constructed edit sequence only (a test edit, a helper edit, and a revert), and the budget witness's along one constructed second check with nothing changed, because a generated history with the witness module or the budget witness takes no steps (maintainer decision, 2026-11-11, and the runtime review's P1-a, 2026-11-12; this oracle owns the gap); law 9's edits come only between checks, so a file saved during a check is not generated (the runner invalidates a known input that changed while a run ran and does not store that run, which only inspection fixes; a witness needs a step that edits a file between a unit's start and its end), and a module that a run first loads and that changes during that same run is stored under its later hash; law 9's edits leave out files read through fs, other environment variables, new files that change how an unchanged import resolves, Vite config and installed-package changes, and concurrent checks other than two that start the daemon; cut-off charging judged only under one budget; native addons only as a binding.gyp or a prebuilt .node file, not as optional platform packages; daemon races (two CLIs reading one error file, a CLI hearing closing from the failing daemon it started, a reset connection on macOS) fixed by inspection; the runner's copies of the test files exist only in memory, and its harness and Vitest configs sit in the package's .oracle-gaps-, which the next run removes once a killed run has left it (judged after two stopped runs, not after a SIGKILL); a default --out is judged by the static oracle, and these runs name --out in the package; the namespace is checked after each run and, in a stopped run, while the run runs; a slow kill in a later owner, after earlier owners' confirmations spent the budget, becomes a timeout (owner order; not generated); the Vitest 5 path of the copies' pragma read and of the runner is verified from Vitest 5's source only, since the Vitest 5 CI job runs no gap oracle; a batch whose run reports an error outside any test reruns each copy alone (unitsBatch, runAlone) with its first budget, and a copy cut there is kept as a timeout with no confirmation, a defect older than this oracle's budget work that no history reaches (no history has an error outside any test beside a slow copy), recorded here with that trace for the maintainer; stale-session removal is scoped to this host's session directories (a host file), and is not judged across pid namespaces; the stop law covers SIGTERM and SIGINT sent to the CLI, not a SIGKILL of the CLI (its group then ends at the next check of its parent, by inspection) or a signal sent to the daemon, and its witness is one test that spins synchronously and starts one child process; the mutant budget is witnessed as two slow owners whose confirmations pass the --mutant-limit floor, not through its multiple of the owners' unmutated time, and authored mutants have no confirmations to budget; the witness w_slowpair is a wall-clock window, since the CLI's budget has no controlled clock and a fixture cannot see the time the CLI measures for its file: with one-test owner files p and q of measured unmutated time t each (a file first in its context pays the instrumented transform too), a wait W of 10 s, a 20 s --hang-limit and a 15 s --mutant-limit, it tells a budget from none only while (a) its first attempt is cut, W > 1 s + 3t, (b) its two confirmations do not fit the budget, 2W > max(15 s, 10 x 2t), and (c) each would fit its own full limit, W < 20 s + 3t; (b) is the binding one, so it holds while the two files' time stays under about 2 s together (about 1 s each, some 20 times the authoring machine's idle and 5 to 10 times its loaded measurements), and under one budget a run's overhead must stay under 10 s + 3t; CI runners measure 1.5 to 2.3 times the idle machine; beyond that w_slowpair would read not-judged; a heartbeat is owed only where a slow test waits 3 s against a 2 s interval, twice the first budget, so that no copy cut at its first budget beats, and each beat is observed as its mutant and file, not how long or how often it beat; a config only in the package's parent directory is generated one level up, in a temporary directory with no package.json (so its .js or .ts name is CommonJS), as a plain config, one that throws, one with no default export, or one that defines test.projects; a config two or more levels up, or a parent config beside a package config, is not generated, and the order in one directory follows Vitest's configFiles list by inspection; a package with no config lives in a temporary directory, where no parent has a config; a counterexample shrinks through at most six histories, so it can be larger than the smallest that fails; module-level data only as four \`const\` declarations of the main source (an object literal, an array that holds a function, a boolean, and an object of two methods), read in place, with no data imported from another file, destructured, reassigned, or declared as an enum or a default export.`, }, histories: { diff --git a/packages/oracles/scripts/e2e-shards.mjs b/packages/oracles/scripts/e2e-shards.mjs index 986c4047..9361d239 100644 --- a/packages/oracles/scripts/e2e-shards.mjs +++ b/packages/oracles/scripts/e2e-shards.mjs @@ -167,6 +167,9 @@ export const shards = { // 79 s and 70 s; the daemon-notes one, bound to its history, 2 s (it // took 433 s searching for one). `calibration: a streamed line has no prefix`, + // The stream log's calibrations, not yet measured. + `calibration: the stream log misses a line`, + `calibration: the line that names the stream log comes after another line`, `calibration: a refusal through the daemon drops the cold run's notes`, // Bound to its history (re-review N2), not yet measured. `calibration: a run names a test-output log it never captured`, From 17ea63427021a076d78fcb48d6f0423a750e1c70 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Fri, 13 Nov 2026 07:24:39 -0700 Subject: [PATCH 02/62] test(oracle-gaps): a refusal after a check started names its stream log first The maintainer's decision of 2026-11-12 names the stream log first in every run that starts a check, refusals in it included. The refusal law (#46) owed stdout = the done line alone; it now owes [note log, done line] when the check started, and [done line] for a refusal of the run's arguments, which comes before any check (outsideSource, and the static oracle's argument refusals). Law 15's log checks apply to runs that start a check. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-model-oracle.mjs | 27 ++++++++---- .../gap-report-oracle.property.test.mjs | 41 ++++++++++++------- 2 files changed, 46 insertions(+), 22 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index 1958c9f8..063cd3b8 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -3815,7 +3815,11 @@ function refusal(plan) { if (plan.fault === `badEntry`) return { cause: `${SOURCE}#nope` } if (plan.fault === `missingSource`) return { cause: `src/missing.ts` } if (plan.fault === `nonLiteral`) return { cause: `b.test.ts` } - if (plan.fault === `outsideSource`) return { cause: `outside the package` } + // A `--source` outside the package is an argument the CLI refuses before + // it starts a check (the argument rules that the static oracle judges), + // so its stdout has no line that names a stream log. + if (plan.fault === `outsideSource`) + return { cause: `outside the package`, arguments: true } // The analysis reads the test files that the package's Vitest config // includes (index.mjs, step 2), so a config that does not load is named // before anything the analysis would find. The cause names the config @@ -5174,8 +5178,13 @@ function endingOf(exit, stderr, out, name = (text) => text, stdout = ``) { * The first way a run's ending breaks the refusal law, or undefined. The * cause must name `cause`; with `outKnown`, the run knew its output * directory, so the block names it and the directory holds the refusal. + * `logNote` is the line that names the run's stream log, owed first on + * stdout when the run refused after it started a check, and undefined for + * a refusal of its arguments, before any check (the maintainer's decision + * of 2026-11-12 that every run that starts a check names its stream log + * first). */ -function refusalBreach(ending, { cause, outKnown }) { +function refusalBreach(ending, { cause, outKnown, logNote }) { if (ending.exit !== 2) return `the refusal exited ${ending.exit}, not 2` if (ending.stackFrames) return `the refusal printed a stack trace` if (ending.cause === undefined) @@ -5194,12 +5203,14 @@ function refusalBreach(ending, { cause, outKnown }) { !/^refused(?:, report .+)?$/.test(ending.done) ) return `the refusal's last line is not \`oracle-gaps: done refused\`` - // The done line ends stdout too, as its only line. - if ( - ending.stdout.length !== 1 || - ending.stdout[0] !== `oracle-gaps: done ${ending.done}` - ) - return `the refusal's stdout is ${JSON.stringify(ending.stdout)}, not its done line` + // The done line ends stdout too, as its only line after the line that + // names the stream log, if the run started a check. + const owedStdout = [ + ...(logNote === undefined ? [] : [logNote]), + `oracle-gaps: done ${ending.done}`, + ] + if (JSON.stringify(ending.stdout) !== JSON.stringify(owedStdout)) + return `the refusal's stdout is ${JSON.stringify(ending.stdout)}, not ${JSON.stringify(owedStdout)}` if (!outKnown) return undefined if (!ending.namesOutput) return `the refusal does not name its report in its output directory: done ${ending.done}` 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 13281301..85ed4d33 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -331,11 +331,14 @@ * (provisional)], report ` on stdout, `refused[, report * ]` after a refusal's block, or `stopped ()` * after a stop. A check through the daemon streams the same lines. The - * run's first line on both streams names its stream log, `oracle-gaps: - * note log /stream.log`, and that file holds the stderr's lines, in - * order, cold and through the daemon (the maintainer's decision of - * 2026-11-12: an agent that runs a check in the background learns from - * the run itself where to read it). + * first line, on both streams, of a run that starts a check names its + * stream log, `oracle-gaps: note log /stream.log`, and that file + * holds the stderr's lines, in order, cold and through the daemon (the + * maintainer's decision of 2026-11-12: an agent that runs a check in the + * background learns from the run itself where to read it). A refusal + * after the check started has that line and then its done line on + * stdout; a refusal of the run's arguments comes before any check, and + * its stdout is its done line alone. * * Authority: the maintainer's decisions in the gap-check design runs v11, v14, * and v19 (2026-11-04 and 2026-11-05; the design notes are kept by the project @@ -2061,7 +2064,10 @@ function incrementalCheck(observations) { // A refusal through the daemon ends as a cold refusal does (law 12): // the CLI that asked the daemon writes it to its own output directory. if (cold.refusal !== undefined) { - const breach = refusalBreach(daemon.ending, { outKnown: true }) + const breach = refusalBreach(daemon.ending, { + outKnown: true, + logNote: logNoteOf(daemon), + }) if (breach) return violation( `incremental`, @@ -2198,6 +2204,7 @@ function check(plan, observations, expected) { const breach = refusalBreach(cli.ending, { cause: expected.refused.cause, outKnown: true, + logNote: expected.refused.arguments ? undefined : logNoteOf(cli), }) if (breach) return violation(`cli`, breach, `report-shaped ending`) return incrementalCheck(observations) ?? daemonCheck(observations) ?? pass @@ -2483,7 +2490,7 @@ function check(plan, observations, expected) { function streamBreach(checkpoint, run, expected, plan) { const breach = (difference, extra) => violation(checkpoint, difference, `greppable stream`, extra) - const ends = endsBreach(run) + const ends = endsBreach(run, { checked: !expected.refused?.arguments }) if (ends) return breach(ends.difference, ends.extra) if (run.stream.mutantBeforeVerdict) return breach( @@ -2526,27 +2533,33 @@ function streamBreach(checkpoint, run, expected, plan) { return undefined } +/** The line that names a run's stream log. */ +const logNoteOf = (run) => `oracle-gaps: note log ${run.outDir}/stream.log` + /** * What law 15 judges of every run, on both streams, whatever its outcome: * no stray line, and exactly one done line, which ends each stream, the * same on both, of the kind its exit status says (0 completed, 2 refused, - * 3 error, and a signal's code stopped). Undefined when it holds. + * 3 error, and a signal's code stopped). With `checked`, the run started a + * check, so its first line names its stream log. Undefined when it holds. */ -function endsBreach(run) { +function endsBreach(run, { checked = true } = {}) { const streams = [ [`stderr`, run.stream], [`stdout`, run.stdoutStream], ] // The run's first line on each stream names its stream log, and the log // holds the stderr's lines, in order (the maintainer's decision of - // 2026-11-12), for every run that starts a check: each of these does. - const note = `oracle-gaps: note log ${run.outDir}/stream.log` - if (run.log.stderrFirst !== note || run.log.stdoutFirst !== note) + // 2026-11-12), for every run that starts a check. A refusal of the run's + // arguments comes before any check, and names no log. + const note = logNoteOf(run) + if (checked && (run.log.stderrFirst !== note || run.log.stdoutFirst !== note)) return { difference: `the run's first lines are ${JSON.stringify([run.log.stderrFirst, run.log.stdoutFirst])}, not ${JSON.stringify(note)} on each stream`, } - if (!run.log.exists) return { difference: `the run wrote no stream.log` } - if (!run.log.equal) + if (checked && !run.log.exists) + return { difference: `the run wrote no stream.log` } + if (checked && !run.log.equal) return { difference: `the run's stream.log is not its stderr, line for line`, } From ceeeaf6cbf468ef3840684400aee432d0bd776f4 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Fri, 13 Nov 2026 07:24:39 -0700 Subject: [PATCH 03/62] feat(oracle-gaps): write the stream to /stream.log and name it first A run that starts a check creates `/stream.log`, writes `oracle-gaps: note log ` as its first line on both streams, and writes every stderr line to the log too: the cold check's lines, a daemon reply's stderr, an internal error's or refusal's ending, the completed done line, and the supervisor's own done line for a stopped or crashed run. Co-authored-by: Isaac --- .changeset/gap-cli-stream-log.md | 5 ++ README.md | 4 ++ packages/oracles/oracle-gaps/index.mjs | 64 ++++++++++++++++++-------- 3 files changed, 55 insertions(+), 18 deletions(-) create mode 100644 .changeset/gap-cli-stream-log.md diff --git a/.changeset/gap-cli-stream-log.md b/.changeset/gap-cli-stream-log.md new file mode 100644 index 00000000..cb238549 --- /dev/null +++ b/.changeset/gap-cli-stream-log.md @@ -0,0 +1,5 @@ +--- +'@tanstack/oracles': patch +--- + +The `oracle-gaps` CLI now writes the lines it streams on stderr to `stream.log` in the output directory too, in order, cold and through `--daemon`, and the first line of a check on both streams names that file: `oracle-gaps: note log /stream.log`. An agent that starts a check in the background can read the run's progress and its done line there. diff --git a/README.md b/README.md index 0a5001be..02664e77 100644 --- a/README.md +++ b/README.md @@ -81,6 +81,10 @@ every commit with [pkg.pr.new](https://pkg.pr.new). to the process's stdout and stderr goes to `test-output.log` in the output directory, which a note names; `summary.md` holds the report for reading. A run through the daemon prints the same lines, at the end of its check. + The first line of a check, on both streams, is `oracle-gaps: note log +/stream.log`: the run writes its stderr lines to that file too, in + order, so a check started in the background can be read there while it + runs and after it ends. `--help` is not a check, so its usage text has no prefix. For contributors: two environment variables in the `ORACLE_GAPS_TEST_` diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index d2639fe3..1e873aae 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -122,8 +122,9 @@ // ended 2 s later is killed, and so is any process left in the group when // the run ends. The run kills its group itself if the CLI dies first. import { spawn } from 'node:child_process' -import { realpathSync } from 'node:fs' +import { appendFileSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs' import { constants } from 'node:os' +import { join } from 'node:path' import { pathToFileURL } from 'node:url' import { parseArgs, usage } from './args.mjs' import { codeIdentity, openSession } from './check.mjs' @@ -134,6 +135,19 @@ import { memoryStore } from './evidence.mjs' // How long the group has to end after a stop signal before it is killed. const STOP_GRACE_MS = 2000 +// The stream log (the maintainer's decision of 2026-11-12): a run that +// starts a check writes its stderr to `/stream.log` too, line for +// line, and names that file in its first line on both streams, so an agent +// that runs a check in the background learns from the run where to read +// it. Undefined until the run starts a check. +let streamLog +const logPathOf = (out) => join(out, `stream.log`) +/** Writes `text` to stderr and to the stream log. */ +const writeStream = (text) => { + process.stderr.write(text) + if (streamLog) appendFileSync(streamLog, text) +} + /** Signals every process of group `group`; false when none is left. */ function signalGroup(group, signal) { try { @@ -149,7 +163,9 @@ function signalGroup(group, signal) { * with it: with its exit code, or, once a stop signal has ended its group, * with 128 plus the signal's number. */ -function superviseRun() { +function superviseRun(out) { + // The supervisor's own done line goes to the run's stream log too. + streamLog = logPathOf(out) let child let stopped // How the run ended: its exit code, or the signal that ended it. @@ -192,11 +208,16 @@ function superviseRun() { const line = stopped ? `oracle-gaps: done stopped (${stopped})\n` : `oracle-gaps: done error, the run's process exited with ${how}${outOfMemory ? `: it ran out of memory; give Node more (NODE_OPTIONS=--max-old-space-size=) or run fewer --contexts` : ``}\n` - process.stdout.write(line, () => + process.stdout.write(line, () => { + try { + appendFileSync(streamLog, line) + } catch { + // A run stopped before it wrote its log has none to end. + } process.stderr.write(line, () => process.exit(stopped ? 128 + constants.signals[stopped] : 3), - ), - ) + ) + }) } if (child === undefined || closed) return decide() child.once(`close`, decide) @@ -271,9 +292,9 @@ function watchSupervisor(supervisor) { function asksForCheck(argv) { try { const options = parseArgs(argv) - return !options.help && !options.stop + return options.help || options.stop ? undefined : options } catch { - return false + return undefined } } @@ -281,7 +302,9 @@ function asksForCheck(argv) { async function checkCold(options) { const session = await openSession(options.pkg) try { - return await session.check(options, memoryStore()) + return await session.check(options, memoryStore(), (line) => + writeStream(`${line}\n`), + ) } finally { await session.close() } @@ -294,7 +317,7 @@ async function checkThroughDaemon(options) { process.argv.slice(2), codeIdentity(), ) - if (reply.stderr) process.stderr.write(reply.stderr) + if (reply.stderr) writeStream(reply.stderr) if (reply.failed) throw received(reply.failed) return reply.stdout } @@ -306,13 +329,11 @@ const main = // Windows has no process groups: there the run is the CLI's own process. const supervised = process.platform !== `win32` const supervisor = process.env.ORACLE_GAPS_GROUP -if ( - main && - supervised && - supervisor === undefined && - asksForCheck(process.argv.slice(2)) -) - superviseRun() +const checking = + main && supervised && supervisor === undefined + ? asksForCheck(process.argv.slice(2)) + : undefined +if (checking) superviseRun(checking.out) else if (main) { if (supervisor !== undefined) watchSupervisor(Number(supervisor)) // A test that runs this CLI starts a run of its own, in a group of its own. @@ -356,7 +377,7 @@ else if (main) { if (ended) return const ending = endRun(error, options?.out) holdStops() - process.stderr.write(ending.stderr) + writeStream(ending.stderr) process.stdout.write(`${ending.done}\n`) end(ending.exitCode) } @@ -369,6 +390,13 @@ else if (main) { if (options.help) console.log(usage) else if (options.stop) await stopDaemon(options.pkg) else { + // The first line on both streams names the stream log. + mkdirSync(options.out, { recursive: true }) + streamLog = logPathOf(options.out) + writeFileSync(streamLog, ``) + const note = `oracle-gaps: note log ${streamLog}\n` + process.stdout.write(note) + writeStream(note) const summary = await (options.daemon ? checkThroughDaemon : checkCold)( options, ) @@ -376,7 +404,7 @@ else if (main) { // The summary ends with the done line (report.mjs), which ends stderr // too. console.log(summary) - process.stderr.write(`${summary.split(`\n`).at(-1)}\n`) + writeStream(`${summary.split(`\n`).at(-1)}\n`) } end(0) } catch (error) { From 5a92a3e56effa82e98f0d57415d0a8c2cbefe960 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Fri, 13 Nov 2026 10:23:58 -0700 Subject: [PATCH 04/62] fix(oracle-gaps): own the stream log in the supervisor; refuse a second run on a live --out The supervisor opens /stream.log and writes the note before it spawns the child; it resolves --out once and passes it to the child and to the daemon request; it tees the child's stderr, V8 lines included, to the log. A run whose log cannot be opened is refused before any check (exit 2, one done line), and a second run on a live output directory is refused without writing into it (maintainer decision, 2026-11-13). Oracle: out-mode (explicit or default) and log-blocked and overlap histories, with the law that a completed run's results.json sits beside its stream log and that a refused run writes nothing into a live directory. Stop histories use the stop-only witness. Co-authored-by: Isaac --- .changeset/gap-cli-stream-log.md | 2 +- README.md | 10 +- packages/oracles/oracle-gaps/ending.mjs | 4 +- .../oracle-gaps/gap-report-model-oracle.mjs | 84 +++- .../gap-report-oracle.property.test.mjs | 370 ++++++++++++++++-- ...gap-report-static-oracle.property.test.mjs | 37 +- packages/oracles/oracle-gaps/index.mjs | 129 +++++- packages/oracles/scripts/e2e-shards.mjs | 14 + 8 files changed, 568 insertions(+), 82 deletions(-) diff --git a/.changeset/gap-cli-stream-log.md b/.changeset/gap-cli-stream-log.md index cb238549..1c8c225c 100644 --- a/.changeset/gap-cli-stream-log.md +++ b/.changeset/gap-cli-stream-log.md @@ -2,4 +2,4 @@ '@tanstack/oracles': patch --- -The `oracle-gaps` CLI now writes the lines it streams on stderr to `stream.log` in the output directory too, in order, cold and through `--daemon`, and the first line of a check on both streams names that file: `oracle-gaps: note log /stream.log`. An agent that starts a check in the background can read the run's progress and its done line there. +The `oracle-gaps` CLI now writes the lines it streams on stderr to `stream.log` in the output directory too, in order, cold and through `--daemon`, and the first line of a check on both streams names that file: `oracle-gaps: note log /stream.log`. An agent that starts a cold check in the background can read the run's progress and its done line there while it runs. A check through `--daemon` prints its lines at the end of its check, so its progress is readable there only after it ends. diff --git a/README.md b/README.md index d89f87e9..655a7d96 100644 --- a/README.md +++ b/README.md @@ -119,10 +119,12 @@ every commit with [pkg.pr.new](https://pkg.pr.new). to the process's stdout and stderr goes to `test-output.log` in the output directory, which a note names; `summary.md` holds the report for reading. A run through the daemon prints the same lines, at the end of its check. - The first line of a check, on both streams, is `oracle-gaps: note log -/stream.log`: the run writes its stderr lines to that file too, in - order, so a check started in the background can be read there while it - runs and after it ends. + The first line of a check, on both streams, is + `oracle-gaps: note log /stream.log`: the run writes its stderr lines + to that file too, in order, so a check started in the background can be + read there while it runs and after it ends. A cold run's lines reach the + file as they are printed; a run through `--daemon` prints its lines at the + end of its check, so the file fills then. `--help` is not a check, so its usage text has no prefix. For contributors: two environment variables in the `ORACLE_GAPS_TEST_` diff --git a/packages/oracles/oracle-gaps/ending.mjs b/packages/oracles/oracle-gaps/ending.mjs index f26a94c9..e9153549 100644 --- a/packages/oracles/oracle-gaps/ending.mjs +++ b/packages/oracles/oracle-gaps/ending.mjs @@ -37,8 +37,10 @@ export function endRun(error, out = error?.out) { // The last line says the run refused, and where its report is once the // run knows its output directory (the stream's done line, stream.mjs); // it ends stdout too (index.mjs). + // A reportless refusal (another run uses the directory) writes nothing + // there: the directory's files are the other run's. const done = write( - out, + error.reportless ? undefined : out, results, `Refused: ${message}\n\nFix: ${error.fix}\n`, ) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index 08f0b89d..bcbe550e 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -541,9 +541,12 @@ const drawn = fc.record({ // The budget witness alone (`budget`) costs two 10 s confirmations per // mutant in every CLI run of a history, so generated histories rarely // draw it; its constructed history (the daemon recheck) always does. + // `stop` is the stop witness alone (`w_stop`), which a run that the driver + // stops needs: the capture witness's other outcome classes are not run. witness: fc.oneof( { weight: 30, arbitrary: fc.constantFrom(false, true, `capture`) }, { weight: 1, arbitrary: fc.constant(`budget`) }, + { weight: 1, arbitrary: fc.constant(`stop`) }, ), authored: fc.option( fc.record({ @@ -690,6 +693,39 @@ const drawn = fc.record({ // A second run with `--only`, of one owned function's mutants: its // baseline runs only their owners (law 14). It costs a run of its own. onlyRun: fc.constantFrom(false, false, false, false, false, true), + // Where the run writes: the output directory `--out` names (`explicit`), or + // the one the CLI picks when `--out` is left out (`default`, args.mjs), whose + // stream log, results, and done line must still agree (law 15). + outMode: fc.constantFrom(`explicit`, `explicit`, `explicit`, `default`), + // The run's `/stream.log` is a directory, so the log cannot be written + // (a problem the author can fix: the run refuses before it checks). + logBlocked: fc.constantFrom( + false, + false, + false, + false, + false, + false, + false, + false, + true, + ), + // A second run starts on the first run's output directory while the first + // is live (the coordinator's decision of 2026-11-13 on F4): the second + // refuses, and the first's stream log stays its own. + overlap: fc.constantFrom( + false, + false, + false, + false, + false, + false, + false, + false, + false, + false, + true, + ), // Oracle file a names its own Vitest environment in a pragma // (`// @vitest-environment`), another than the config's, and fails to load // outside it: every copy of it must run in that environment too. @@ -2477,6 +2513,7 @@ function resolveHistory(history) { // so only histories of the `budget` mode carry it. (history.witness === true && w.id !== `w_slowpair`) || (history.witness === `capture` && captureWitness.has(w.id)) || + (history.witness === `stop` && w.id === `w_stop`) || (history.witness === `budget` && w.id === `w_slowpair`), ) .map((w) => ({ @@ -2837,6 +2874,12 @@ function resolveHistory(history) { depSubpath: history.depSubpath === true, unbuiltDep: history.unbuiltDep === true, budget: history.budget ?? `two`, + outMode: history.outMode ?? `explicit`, + // Both name the run's `--out` directory before it starts, so they need + // an explicit one (a default directory is chosen by the CLI). + logBlocked: + history.logBlocked === true && outModeOf(history) === `explicit`, + overlap: history.overlap === true && outModeOf(history) === `explicit`, stopRuns: history.stopRuns ?? [], onlyRun: history.onlyRun === true, pragma: history.pragma === true, @@ -4083,7 +4126,16 @@ function refusal(plan) { if (plan.fault === `brokenVitest`) return { cause: `vitest`, runtime: true } if (plan.fault === `projects`) return { cause: `test.projects`, runtime: true } + // A stream log that cannot be written is refused before the check starts + // (the CLI opens the log before its first line, index.mjs), so its stdout + // owes its done line alone. + if (plan.logBlocked === true) + return { cause: `the stream log`, arguments: true } if (plan.fault === `badEntry`) return { cause: `${SOURCE}#nope` } + // An owns entry that names a missing file (a test file's declaration) is + // found by the analysis, after the check has started, so this refusal + // owes the stream log's note. The argument-stage case, a `--source` that + // is not a file of the package, is the static oracle's `absentSource`. if (plan.fault === `missingSource`) return { cause: `src/missing.ts` } if (plan.fault === `nonLiteral`) return { cause: `b.test.ts` } // A `--source` outside the package is an argument the CLI refuses before @@ -4187,6 +4239,7 @@ const declarationFaults = [ `nonLiteral`, `outsideSource`, ] +const outModeOf = (history) => history.outMode ?? `explicit` const reachesRun = (history) => !declarationFaults.includes(history.fault ?? `none`) @@ -4239,21 +4292,22 @@ function model(plan) { // fault, a Vitest that does not load, a config that does not load, and a // config that defines test.projects, which a loaded context shows. Every // other run names it once, refused or not. - const configLines = [ - `outsideSource`, - `brokenVitest`, - `configThrows`, - `configNoDefault`, - `configNull`, - `configSyntax`, - `projects`, - ].includes(plan.fault) - ? [] - : [ - plan.configPath === undefined - ? `oracle-gaps: config none, Vitest's default discovery` - : `oracle-gaps: config ${plan.configPath}`, - ] + const configLines = + [ + `outsideSource`, + `brokenVitest`, + `configThrows`, + `configNoDefault`, + `configNull`, + `configSyntax`, + `projects`, + ].includes(plan.fault) || plan.logBlocked === true + ? [] + : [ + plan.configPath === undefined + ? `oracle-gaps: config none, Vitest's default discovery` + : `oracle-gaps: config ${plan.configPath}`, + ] if (refused) return { refused, configLines } const sites = sitesOf(plan) const owners = ownersOf(plan) 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 380b12e1..cddd89c9 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -588,14 +588,17 @@ function cliArgs( sources = `${SOURCE},${LIB}`, budget = `two`, outName = daemon ? `out-daemon` : `out`, + // `default` leaves `--out` out, so the CLI picks its own output + // directory (args.mjs): the run's first stdout line names it. + outMode = `explicit`, config, contexts = 4, only, pool, } = {}, ) { - const out = join(dir, outName) - rmSync(out, { recursive: true, force: true }) + const out = outMode === `default` ? undefined : join(dir, outName) + if (out !== undefined) rmSync(out, { recursive: true, force: true }) // The CLI runs from the package directory. A daemon check names its paths // relative to there, as an author types them, and the daemon must read // them as the CLI's caller meant them. @@ -628,9 +631,8 @@ function cliArgs( // one copy: one slow owner's confirmation fits it, two do not (law 4). `--mutant-limit`, String(MUTANT_LIMIT_MS), - `--out`, - path(out), ] + if (out !== undefined) args.push(`--out`, path(out)) if (only !== undefined) args.push(`--only`, only.join(`,`)) if (pool !== undefined) args.push(`--pool`, pool) if (ordinary) args.push(`--ordinary`) @@ -655,6 +657,7 @@ function runCli(dir, files, how = {}) { writeFixture(dir, files) const before = new Set(filesUnder(dir)) const { args, out } = cliArgs(dir, files, how) + if (how.logBlocked) mkdirSync(join(out, `stream.log`), { recursive: true }) const child = spawnSync(process.execPath, args, { cwd: repo, encoding: `utf8`, @@ -727,7 +730,7 @@ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { writeFixture(dir, files) const before = new Set(filesUnder(dir)) const pids = mkdtempSync(join(realpathSync(tmpdir()), `gap-stop-`)) - const { args, out } = cliArgs(dir, files, { + const { args, out: given } = cliArgs(dir, files, { ...how, outName: `out-stop`, contexts: 1, @@ -813,7 +816,18 @@ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { } if (!ended) child.kill(`SIGKILL`) rmSync(pids, { recursive: true, force: true }) - return { + const out = + given ?? + `${stdout}` + .split(`\n`)[0] + .match(/^oracle-gaps: note log (.*)\/stream\.log$/)?.[1] ?? + join(dir, `no-output`) + const scratchNames = [ + [how.cli ?? here, ``], + [dir, ``], + ...(given === undefined ? [[out, ``]] : []), + ] + const result = { signal, pool, spun, @@ -826,26 +840,14 @@ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { exit: exitCode, // Both streams' lines (law 15), with the scratch paths named. stream: streamOf(stderr.split(`\n`), (text) => - namedScratch(text, [ - [how.cli ?? here, ``], - [dir, ``], - ]), + namedScratch(text, scratchNames), ), stdoutStream: streamOf(stdout.split(`\n`), (text) => - namedScratch(text, [ - [how.cli ?? here, ``], - [dir, ``], - ]), + namedScratch(text, scratchNames), ), - outDir: namedScratch(out, [ - [how.cli ?? here, ``], - [dir, ``], - ]), + outDir: namedScratch(out, scratchNames), log: streamLogOf(out, stderr, stdout, (text) => - namedScratch(text, [ - [how.cli ?? here, ``], - [dir, ``], - ]), + namedScratch(text, scratchNames), ), // The session directories in the package once it has ended: a stopped // run leaves its own, and the next run removes it. @@ -857,6 +859,9 @@ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { (file) => !/^\.oracle-gaps-\d+\//.test(file), ), } + // A default output directory is the run's own scratch. + if (given === undefined) rmSync(out, { recursive: true, force: true }) + return result } /** @@ -905,6 +910,83 @@ function filesUnder(root, within = ``) { ) } +const sleep = (ms) => new Promise((r) => setTimeout(r, ms)) + +/** + * Runs the CLI twice on one output directory, the second while the first is + * live (the first has printed its note, so it has its stream log). The first + * run is the history's `cli`, and the second's ending is the `overlap` + * observation (the coordinator's decision of 2026-11-13 on F4: a second run + * refuses, and the first's stream log stays its own). + */ +async function overlappingRuns(dir, files, how) { + writeFixture(dir, files) + const before = new Set(filesUnder(dir)) + const { args, out } = cliArgs(dir, files, how) + const start = () => { + const child = spawn(process.execPath, args, { + cwd: repo, + env: cleanEnv(), + stdio: [`ignore`, `pipe`, `pipe`], + }) + const got = { stdout: ``, stderr: `` } + child.stdout.on(`data`, (chunk) => { + got.stdout += chunk + }) + child.stderr.on(`data`, (chunk) => { + got.stderr += chunk + }) + const status = new Promise((resolvePromise) => { + const timer = setTimeout(() => child.kill(), 300_000) + child.on(`close`, (code) => { + clearTimeout(timer) + resolvePromise(code) + }) + }) + return { got, status } + } + const first = start() + // The first run's note is its first stdout line: its stream log exists. + for ( + let waited = 0; + !first.got.stdout.includes(`oracle-gaps: note log`) && waited < 120_000; + waited += 20 + ) + await sleep(20) + const second = start() + const secondStatus = await second.status + const firstStatus = await first.status + const ended = readRun( + dir, + out, + firstStatus, + first.got.stderr, + how.cli ?? here, + first.got.stdout, + ) + const refused = readRun( + dir, + out, + secondStatus, + second.got.stderr, + how.cli ?? here, + second.got.stdout, + ) + const replay = first.got.stderr + .split(`\n`) + .find((line) => line.startsWith(` replay: `)) + ?.slice(` replay: `.length) + return { + cli: { ...ended, replay, strayWrites: strays(dir, before) }, + overlap: { + exit: refused.exit, + ending: refused.ending, + stream: refused.stream, + stdoutStream: refused.stdoutStream, + }, + } +} + // Where a run may write in the package: only the output directories the // driver names with `--out` (`out`, `out-daemon`, `out-stop`, and // `out-only`). The daemon's state, the workspace dependencies' one-file @@ -996,7 +1078,9 @@ const streamedGap = * lines are the stderr's lines, in order. */ function streamLogOf(out, stderr, stdout, name) { - const lines = (text) => `${text ?? ``}`.split(`\n`).filter(Boolean) + // The lines of a text, its final newline ending the last line. A blank line + // is a line: the log must equal the stderr's lines exactly (F10). + const lines = (text) => `${text ?? ``}`.replace(/\n$/, ``).split(`\n`) let log try { log = readFileSync(join(out, `stream.log`), `utf8`) @@ -1060,11 +1144,40 @@ function streamOf(lines, name) { } function readRun(dir, out, status, stderr, cli, stdout) { + // A run without `--out` writes to the directory its stream log is in, which + // its first stdout line names (law 15); that directory is removed after the + // run is read, as the run's own scratch. + const chosen = + out ?? + `${stdout ?? ``}` + .split(`\n`)[0] + .match(/^oracle-gaps: note log (.*)\/stream\.log$/)?.[1] + try { + return readRunIn( + dir, + chosen ?? join(dir, `no-output`), + status, + stderr, + cli, + stdout, + out === undefined ? chosen : undefined, + ) + } finally { + if (out === undefined && chosen !== undefined) + rmSync(chosen, { recursive: true, force: true }) + } +} + +// `derived` is the output directory the CLI chose (no `--out`), which is named +// `` so that two runs of one history, each with its own directory, record +// the same trace (law 9's determinism). +function readRunIn(dir, out, status, stderr, cli, stdout, derived) { // The output names the CLI directory that ran and the package, as scratch // directories do, before it is cut to its last characters. const scratch = [ [cli, ``], [dir, ``], + ...(derived === undefined ? [] : [[derived, ``]]), ] const named = status === 0 ? undefined : namedScratch(`${stderr}`, scratch) let results @@ -1332,6 +1445,7 @@ async function incremental(dir, plan, cli, copy, observe, states) { const key = fingerprint(files, state, step === `otherInstall`) const how = { seed: state.seed, + outMode: plan.outMode, cli: step === `otherInstall` ? otherCli() : copy, ordinary: plan.ordinary, sources: sourceArgument(plan, `${dir}.link`), @@ -1357,6 +1471,8 @@ async function incremental(dir, plan, cli, copy, observe, states) { : await daemonChecks(step, files, how) if (!cold.has(key)) cold.set(key, runCli(dir, files, how)) const coldRun = cold.get(key) + if (plan.outMode === `default`) + states.add(`a daemon check with the default output directory`) for (const [i, run] of [daemon, ...others].entries()) observe(`incremental`, { step: i === 0 ? step : `${step} (a second check at once)`, @@ -1377,6 +1493,7 @@ async function incremental(dir, plan, cli, copy, observe, states) { // Its stream log, and the output directory it names. log: run.log, outDir: run.outDir, + reported: run.reported, // The first line of a failure, for the message; readRun has named // the scratch package and CLI copy in it. stderr: run.stderr?.split(`\n`)[0], @@ -1647,10 +1764,18 @@ async function driver(plan, observe) { ordinary: plan.ordinary, sources: sourceArgument(plan, `${dir}.link`), budget: plan.budget, + outMode: plan.outMode, + logBlocked: plan.logBlocked, cli: plan.cliPath === `spaced` ? copy : here, ...configArgs(plan), } - const { replay, ...cli } = runCli(dir, files, how) + // Two runs on one output directory: the second's refusal is its own + // observation (overlappingRuns). + const overlapping = plan.overlap + ? await overlappingRuns(dir, files, how) + : undefined + const { replay, ...cli } = overlapping?.cli ?? runCli(dir, files, how) + if (overlapping) observe(`overlap`, overlapping.overlap) // How many units were computed or reused says how the result was // produced, not what it is, so it is not observed. observe(`cli`, { ...cli, evidence: undefined }) @@ -1659,6 +1784,12 @@ async function driver(plan, observe) { observe(`replay`, { command: replay, ran: replayed(dir, replay) }) // Reach comes from what the CLI reported, mapped onto the plan. const states = new Set() + if (plan.outMode === `default`) + states.add(`a run with the default output directory`) + if (plan.logBlocked && cli.exit === 2) + states.add(`a stream log that cannot be written`) + if (overlapping && overlapping.overlap.exit === 2) + states.add(`two runs on one output directory`) if (cli.exit === 0 && !plan.consoleOutput) states.add(`a completed run whose tests wrote nothing`) // Law 14: a partial run of one owned function's mutants, whose baseline @@ -1712,6 +1843,8 @@ async function driver(plan, observe) { }, } observe(`stopped`, stopped) + if (plan.outMode === `default`) + states.add(`a stop with the default output directory`) if (previousSessions.length > 0) states.add(`a run after a stopped one that left its session`) previousSessions = run.sessions @@ -2221,6 +2354,24 @@ function check(plan, observations, expected) { `config`, { actual: cli.configLines, expected: expected.configLines }, ) + // A second run on a live output directory refuses before it writes + // anything (F4, the coordinator's decision of 2026-11-13): the refusal + // names the directory, is one block with its fix, and its stdout is its + // done line alone. The first run's own laws are judged on `cli`. + const overlap = observations.find((o) => o.checkpoint === `overlap`)?.value + if (overlap !== undefined) { + if (overlap.exit !== 2) + return violation( + `overlap`, + `the second run on a live output directory exited ${overlap.exit}, not refusing it`, + `ownership`, + ) + const breach = refusalBreach(overlap.ending, { + cause: `another run is using`, + outKnown: false, + }) + if (breach) return violation(`overlap`, breach, `report-shaped ending`) + } const stream = streamBreach(`cli`, cli, expected, plan) if (stream) return stream // Through the daemon, each check streams the same kinds of line, and a @@ -2290,6 +2441,14 @@ function check(plan, observations, expected) { logNote: expected.refused.arguments ? undefined : logNoteOf(cli), }) if (breach) return violation(`cli`, breach, `report-shaped ending`) + // A refusal of the arguments, or before the check starts, writes no + // stream log (F8, the coordinator's review of #57). + if (expected.refused.arguments && cli.log.exists) + return violation( + `cli`, + `the refusal before the check started wrote a stream log`, + `greppable stream`, + ) return incrementalCheck(observations) ?? daemonCheck(observations) ?? pass } if (cli.exit !== 0 || !cli.reported) @@ -2644,6 +2803,13 @@ function endsBreach(run, { checked = true } = {}) { return { difference: `the run's stream.log is not its stderr, line for line`, } + // A completed run's results.json sits beside its stream log, in the + // directory the log names (law 15's stream log, the maintainer's decision + // of 2026-11-12). + if (checked && run.exit === 0 && run.reported === false) + return { + difference: `the run completed, but its results.json is not beside its stream log`, + } for (const [where, stream] of streams) if (stream.strays.length > 0) return { @@ -3109,20 +3275,31 @@ calibrations.push( ), }, { + // A completed run that starts a check, so its log is judged (law 15). name: `the stream log misses a line`, law: `greppable stream`, - corrupt: corruptCli((cli) => ({ - ...cli, - log: { ...cli.log, equal: false }, - })), + history: { constructed: `two authored mutants` }, + corrupt: corruptCli((cli) => + cli.exit !== 0 + ? undefined + : { ...cli, log: { ...cli.log, equal: false } }, + ), }, { name: `the line that names the stream log comes after another line`, law: `greppable stream`, - corrupt: corruptCli((cli) => ({ - ...cli, - log: { ...cli.log, stderrFirst: `oracle-gaps: config vite.config.ts` }, - })), + history: { constructed: `two authored mutants` }, + corrupt: corruptCli((cli) => + cli.exit !== 0 + ? undefined + : { + ...cli, + log: { + ...cli.log, + stderrFirst: `oracle-gaps: config vite.config.ts`, + }, + }, + ), }, { name: `a stopped run ends without its done line`, @@ -3188,6 +3365,11 @@ const staticStates = [ `owned through bind`, ] const required = [ + `a stream log that cannot be written`, + `two runs on one output directory`, + `a run with the default output directory`, + `a stop with the default output directory`, + `a daemon check with the default output directory`, `killed by a second owner`, `killed`, `random-only kill`, @@ -3488,6 +3670,130 @@ oracleProperty({ consoleOutput: true, }), }, + { + // Without `--out`, the CLI picks the run's output directory + // (args.mjs). A run stopped while its config warms must still leave + // its stream log beside its results, with the done line last on both + // streams (law 15). The stop witness runs alone (witness `stop`), and a history + // with the witness module takes no steps. + name: `a stop with the default output directory`, + enters: [ + `a run with the default output directory`, + `a stop with the default output directory`, + ], + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], + wholeFile: `none`, + witness: `stop`, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, + steps: null, + ordinary: false, + outMode: `default`, + budget: `two`, + stopRuns: [{ signal: `SIGINT`, pool: `threads`, when: `warm` }], + }), + }, + { + // Through the daemon, a check that the CLI parses without `--out` + // would write its results to a directory of its own, apart from the + // stream log the CLI names (law 15). + name: `a daemon check with the default output directory`, + enters: [ + `a run with the default output directory`, + `a daemon check with the default output directory`, + ], + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], + wholeFile: `none`, + witness: false, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, + steps: [`test`], + ordinary: false, + outMode: `default`, + budget: `two`, + }), + }, + { + // A stream log that is a directory cannot be written: the CLI refuses + // before its first line (index.mjs opens the log first), with its + // block, its fix, and its report in the output directory, and its + // stdout is its done line alone (law 12, law 15, and F3 of the + // coordinator's review of #57). No stack trace, and exit 2 or 3. + name: `a stream log that cannot be written`, + enters: [`a stream log that cannot be written`], + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], + wholeFile: `none`, + witness: false, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, + steps: null, + ordinary: false, + budget: `two`, + outMode: `explicit`, + logBlocked: true, + overlap: false, + }), + }, + { + // A second run on the first's output directory while the first is + // live refuses (F4, the coordinator's decision of 2026-11-13): the + // first run's stream log still equals its own stderr, line for line, + // and the refusal reports no directory it does not own. + name: `two runs on one output directory`, + enters: [`two runs on one output directory`], + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], + wholeFile: `none`, + witness: false, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, + steps: null, + ordinary: false, + budget: `two`, + outMode: `explicit`, + logBlocked: false, + overlap: true, + }), + }, { // The budget witness checked through the daemon twice with nothing // changed between: the second check reuses the confirmations the 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 d2ef2d04..07849a8c 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 @@ -89,6 +89,7 @@ * target. An authored mutant's `source` field is used as written. */ import { + existsSync, mkdirSync, mkdtempSync, readFileSync, @@ -371,6 +372,14 @@ const matcherOwns = fc.oneof( ) // Each history of the shared grammar, with its argument fault and its // matcher's `owns`. +// The end-to-end dimensions the static oracle does not draw: `logBlocked` +// (a stream log the run cannot write) and `overlap` (a second run on a live +// output directory). The static run creates no stream log and starts no +// second CLI process, so these are off for it by deliberate scope; the +// end-to-end oracle (gap-report-oracle) owns both (F3 and F4 of the review of +// #57). +const staticResolve = (history) => + resolveHistory({ ...history, logBlocked: false, overlap: false }) const argumentHistories = fc.tuple(histories, badArguments, matcherOwns).map( ([history, bad, matcher]) => ({ ...history, @@ -489,13 +498,19 @@ function argumentsRunOf(dir, plan) { encoding: `utf8`, timeout: 120_000, }) - return endingOf( - run.status, - run.stderr, - out, - (text) => text.replaceAll(dir, ``), - run.stdout, - ) + return { + ...endingOf( + run.status, + run.stderr, + out, + (text) => text.replaceAll(dir, ``), + run.stdout, + ), + // A refusal of the arguments, or before a check starts, writes no stream + // log (F8, the coordinator's review of #57). Judged where the run names + // its output directory; a default one lives in the OS temp directory. + streamLog: out !== undefined && existsSync(join(out, `stream.log`)), + } } // ## The derived class, run @@ -1082,6 +1097,12 @@ function check(plan, observations, expected) { `with ${bad.kind} arguments${bad.daemon ? ` and --daemon` : ``}, ${breach}`, `report-shaped ending`, ) + if (argumentsRun.streamLog) + return violation( + `arguments`, + `with ${bad.kind} arguments${bad.daemon ? ` and --daemon` : ``}, the refusal wrote a stream log`, + `greppable stream`, + ) // An owner that fails, and a config the runner cannot load or honor, are // found only when the runner starts, so the analysis must not refuse for // them: it refuses as it would for the same plan without the fault. @@ -1785,7 +1806,7 @@ oracleProperty({ }, ]), }, - resolve: resolveHistory, + resolve: staticResolve, model, driver, check, diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index 1e873aae..349b96ef 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -122,14 +122,21 @@ // ended 2 s later is killed, and so is any process left in the group when // the run ends. The run kills its group itself if the CLI dies first. import { spawn } from 'node:child_process' -import { appendFileSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs' +import { + appendFileSync, + mkdirSync, + readFileSync, + realpathSync, + rmSync, + writeFileSync, +} from 'node:fs' import { constants } from 'node:os' import { join } from 'node:path' import { pathToFileURL } from 'node:url' import { parseArgs, usage } from './args.mjs' import { codeIdentity, openSession } from './check.mjs' import { received, requestDaemon, stopDaemon } from './daemon.mjs' -import { endRun } from './ending.mjs' +import { endRun, Refusal } from './ending.mjs' import { memoryStore } from './evidence.mjs' // How long the group has to end after a stop signal before it is killed. @@ -139,14 +146,86 @@ const STOP_GRACE_MS = 2000 // starts a check writes its stderr to `/stream.log` too, line for // line, and names that file in its first line on both streams, so an agent // that runs a check in the background learns from the run where to read -// it. Undefined until the run starts a check. +// it. The supervisor opens it before the child starts (startLog), and then +// is the only writer of the child's stderr to it (superviseRun). Undefined +// until the log is open. let streamLog const logPathOf = (out) => join(out, `stream.log`) -/** Writes `text` to stderr and to the stream log. */ +/** Writes `text` to stderr and, once the log is open, to the stream log. */ const writeStream = (text) => { process.stderr.write(text) if (streamLog) appendFileSync(streamLog, text) } +const cannotWrite = (path, error) => + new Refusal( + `the stream log ${path} cannot be written (${error.code ?? error.message})`, + `Remove ${path}, or pass --out a directory whose stream.log can be written.`, + ) +/** Whether process `pid` runs. */ +const alive = (pid) => { + try { + process.kill(pid, 0) + return true + } catch (error) { + return error.code === `EPERM` + } +} +/** + * Claims output directory `out` for this process: a run keeps it while it + * lives, and a second run on it refuses, reportless so that the live run's + * files stay its own (the maintainer's decision of 2026-11-13). A claim by a + * run that has ended is taken over. + */ +function claimOut(out) { + const claim = join(out, `run.pid`) + for (;;) { + try { + writeFileSync(claim, `${process.pid}\n`, { flag: `wx` }) + return + } catch (error) { + if (error.code !== `EEXIST`) throw cannotWrite(claim, error) + } + let holder + try { + holder = Number(readFileSync(claim, `utf8`)) + } catch (error) { + if (error.code !== `ENOENT`) throw cannotWrite(claim, error) + continue + } + if (holder !== process.pid && holder > 0 && alive(holder)) { + const refusal = new Refusal( + `another run is using ${out}`, + `Pass --out a directory no run is using, or wait for the run that uses it to end.`, + ) + refusal.reportless = true + throw refusal + } + rmSync(claim, { force: true }) + } +} +/** + * Opens the run's stream log in `out` and writes its first line, on both + * streams, which names the log. Throws a Refusal when the output directory + * is in use or the log cannot be written; nothing is written then. + */ +function startLog(out) { + const path = logPathOf(out) + try { + mkdirSync(out, { recursive: true }) + } catch (error) { + throw cannotWrite(path, error) + } + claimOut(out) + try { + writeFileSync(path, ``) + } catch (error) { + throw cannotWrite(path, error) + } + streamLog = path + const note = `oracle-gaps: note log ${path}\n` + process.stdout.write(note) + writeStream(note) +} /** Signals every process of group `group`; false when none is left. */ function signalGroup(group, signal) { @@ -164,8 +243,6 @@ function signalGroup(group, signal) { * with 128 plus the signal's number. */ function superviseRun(out) { - // The supervisor's own done line goes to the run's stream log too. - streamLog = logPathOf(out) let child let stopped // How the run ended: its exit code, or the signal that ended it. @@ -209,11 +286,8 @@ function superviseRun(out) { ? `oracle-gaps: done stopped (${stopped})\n` : `oracle-gaps: done error, the run's process exited with ${how}${outOfMemory ? `: it ran out of memory; give Node more (NODE_OPTIONS=--max-old-space-size=) or run fewer --contexts` : ``}\n` process.stdout.write(line, () => { - try { - appendFileSync(streamLog, line) - } catch { - // A run stopped before it wrote its log has none to end. - } + // The log was opened before the run started (startLog). + appendFileSync(streamLog, line) process.stderr.write(line, () => process.exit(stopped ? 128 + constants.signals[stopped] : 3), ) @@ -249,6 +323,10 @@ function superviseRun(out) { [ ...process.execArgv.filter((flag) => !/^--inspect/.test(flag)), ...process.argv.slice(1), + // The out directory, resolved once by this process (asksForCheck): the + // run and a daemon's check write there, not to a directory of their own. + `--out`, + out, ], { detached: true, @@ -259,10 +337,12 @@ function superviseRun(out) { child.on(`message`, (message) => { if (message === `ending`) ending = true }) - // The run's stderr, passed on as it comes, and read for V8's - // out-of-memory message. + // The run's stderr, passed on as it comes, written to the stream log as it + // is (V8's own lines included, which the run does not write itself), and + // read for V8's out-of-memory message. child.stderr.on(`data`, (chunk) => { process.stderr.write(chunk) + appendFileSync(streamLog, chunk) stderrTail = (stderrTail + chunk).slice(-200) if (/heap out of memory/i.test(stderrTail)) outOfMemory = true }) @@ -333,7 +413,18 @@ const checking = main && supervised && supervisor === undefined ? asksForCheck(process.argv.slice(2)) : undefined -if (checking) superviseRun(checking.out) +// A check the supervisor cannot open its log for is run in this process, which +// refuses it the same way (below). +const supervising = (() => { + if (checking === undefined) return false + try { + startLog(checking.out) + return true + } catch { + return false + } +})() +if (supervising) superviseRun(checking.out) else if (main) { if (supervisor !== undefined) watchSupervisor(Number(supervisor)) // A test that runs this CLI starts a run of its own, in a group of its own. @@ -390,13 +481,9 @@ else if (main) { if (options.help) console.log(usage) else if (options.stop) await stopDaemon(options.pkg) else { - // The first line on both streams names the stream log. - mkdirSync(options.out, { recursive: true }) - streamLog = logPathOf(options.out) - writeFileSync(streamLog, ``) - const note = `oracle-gaps: note log ${streamLog}\n` - process.stdout.write(note) - writeStream(note) + // The supervisor opened the log (or, on Windows, there is none and this + // process runs the check); its child writes stderr alone. + if (supervisor === undefined) startLog(options.out) const summary = await (options.daemon ? checkThroughDaemon : checkCold)( options, ) diff --git a/packages/oracles/scripts/e2e-shards.mjs b/packages/oracles/scripts/e2e-shards.mjs index 9361d239..c25528f8 100644 --- a/packages/oracles/scripts/e2e-shards.mjs +++ b/packages/oracles/scripts/e2e-shards.mjs @@ -41,6 +41,10 @@ const suite = `oracle-gaps.report` export const shards = { // 522 s in the measured run, about 221 s idle. 'e2e-1': [ + `fixed seed 20261105: a stop with the default output directory`, + `fixed seed 20261105: a daemon check with the default output directory`, + `fixed seed 20261105: a stream log that cannot be written`, + `fixed seed 20261105: two runs on one output directory`, `fixed seed 20261105: a .cjs config that calls require`, `fixed seed 20261105: a declaration fault: missingSource`, `fixed seed 20261105: a declaration fault: noTypescript`, @@ -106,6 +110,10 @@ export const shards = { ], // 522 s in the measured run, about 221 s idle. 'e2e-3': [ + `random seed: a stop with the default output directory`, + `random seed: a daemon check with the default output directory`, + `random seed: a stream log that cannot be written`, + `random seed: two runs on one output directory`, `fixed seed 20261105: a config fault in a run that owns nothing`, `fixed seed 20261105: a declaration fault: brokenOwner`, `fixed seed 20261105: a declaration fault: configThrows`, @@ -181,6 +189,10 @@ export const shards = { ], // 522 s in the measured run, about 221 s idle. 'e2e-5': [ + `determinism: constructed history: a stop with the default output directory`, + `determinism: constructed history: a daemon check with the default output directory`, + `determinism: constructed history: a stream log that cannot be written`, + `determinism: constructed history: two runs on one output directory`, `fixed seed 20261105: an edit sequence through the daemon`, `fixed seed 20261105: ordinary tests left out by default`, `fixed seed 20261105: two authored mutants`, @@ -267,6 +279,8 @@ function listed() { const run = spawnSync( `pnpm`, [ + // --silent keeps pnpm's workspace banner off stdout, which is JSON. + `--silent`, `exec`, `vitest`, `list`, From fd5655d1c7555b77f0c1e4bd1aa5bc6bd63989ff Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Fri, 13 Nov 2026 10:59:20 -0700 Subject: [PATCH 05/62] wip(oracle-gaps): checkpoint at the pre-restructure CLI with the oracle fixes Oracle changes: out-mode, stop-only and stop-at-spawn dimensions appended to the history grammar (earlier fields unchanged on the sampled histories); the five new states as own-history states; overlap generated only for an explicit out, a live first run, and a fault-free history; the overlap wait ends on the first run's exit; constructed fault histories reset the end-to-end dimensions their generated base may draw. CLI: pre-restructure index.mjs from 5a92a3e. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-model-oracle.mjs | 116 ++++++++++++------ .../gap-report-oracle.property.test.mjs | 97 +++++++++++++-- packages/oracles/scripts/e2e-shards.mjs | 3 + 3 files changed, 167 insertions(+), 49 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index bcbe550e..6c44396b 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -541,12 +541,9 @@ const drawn = fc.record({ // The budget witness alone (`budget`) costs two 10 s confirmations per // mutant in every CLI run of a history, so generated histories rarely // draw it; its constructed history (the daemon recheck) always does. - // `stop` is the stop witness alone (`w_stop`), which a run that the driver - // stops needs: the capture witness's other outcome classes are not run. witness: fc.oneof( { weight: 30, arbitrary: fc.constantFrom(false, true, `capture`) }, { weight: 1, arbitrary: fc.constant(`budget`) }, - { weight: 1, arbitrary: fc.constant(`stop`) }, ), authored: fc.option( fc.record({ @@ -693,39 +690,6 @@ const drawn = fc.record({ // A second run with `--only`, of one owned function's mutants: its // baseline runs only their owners (law 14). It costs a run of its own. onlyRun: fc.constantFrom(false, false, false, false, false, true), - // Where the run writes: the output directory `--out` names (`explicit`), or - // the one the CLI picks when `--out` is left out (`default`, args.mjs), whose - // stream log, results, and done line must still agree (law 15). - outMode: fc.constantFrom(`explicit`, `explicit`, `explicit`, `default`), - // The run's `/stream.log` is a directory, so the log cannot be written - // (a problem the author can fix: the run refuses before it checks). - logBlocked: fc.constantFrom( - false, - false, - false, - false, - false, - false, - false, - false, - true, - ), - // A second run starts on the first run's output directory while the first - // is live (the coordinator's decision of 2026-11-13 on F4): the second - // refuses, and the first's stream log stays its own. - overlap: fc.constantFrom( - false, - false, - false, - false, - false, - false, - false, - false, - false, - false, - true, - ), // Oracle file a names its own Vitest environment in a pragma // (`// @vitest-environment`), another than the config's, and fails to load // outside it: every copy of it must run in that environment too. @@ -805,6 +769,66 @@ const drawn = fc.record({ }), // Who names the importer's function in an owns entry, if any. importer: fc.constantFrom(`none`, `a`, `b`), + // Where the run writes: the output directory `--out` names (`explicit`), or + // the one the CLI picks when `--out` is left out (`default`, args.mjs), whose + // stream log, results, and done line must still agree (law 15). + outMode: fc.constantFrom(`explicit`, `explicit`, `explicit`, `default`), + // The run's `/stream.log` is a directory, so the log cannot be written + // (a problem the author can fix: the run refuses before it checks). + logBlocked: fc.constantFrom( + false, + false, + false, + false, + false, + false, + false, + false, + true, + ), + // A second run starts on the first run's output directory while the first + // is live (the coordinator's decision of 2026-11-13 on F4): the second + // refuses, and the first's stream log stays its own. + overlap: fc.constantFrom( + false, + false, + false, + false, + false, + false, + false, + false, + false, + false, + true, + ), + // The stop witness alone (`w_stop`), which a run the driver stops needs. A + // field of its own, so the witness options above keep their weights. + stopWitness: fc.constantFrom( + false, + false, + false, + false, + false, + false, + false, + false, + true, + ), + // A stop sent as soon as the CLI spawns, before its own run has started (P1: + // the note is written before the child exists, so the stopped line follows + // it). The driver adds this stop to the run's stops. + spawnStop: fc.constantFrom( + false, + false, + false, + false, + false, + false, + false, + false, + true, + ), }) // The edit sequence over the witness module, the one list of steps that a @@ -816,6 +840,10 @@ const drawn = fc.record({ // nothing changed, which reuses the confirmations that the first check ran. const witnessSteps = [`test`, `helper`, `revert`] const budgetSteps = [`recheck`] +// The stop witness alone takes no steps, so it counts only where the history +// has none; a history with steps and the field is a legal history without it. +const stopsOnly = (history) => + history.stopWitness === true && history.steps === null const keepsSteps = (history) => { if (history.witness === false || history.steps === null) return true const kept = history.witness === `budget` ? budgetSteps : witnessSteps @@ -2505,7 +2533,7 @@ function resolveHistory(history) { ...exported, ...importer, ...dotGen, - ...(history.witness + ...(history.witness || stopsOnly(history) ? witness .filter( (w) => @@ -2513,7 +2541,7 @@ function resolveHistory(history) { // so only histories of the `budget` mode carry it. (history.witness === true && w.id !== `w_slowpair`) || (history.witness === `capture` && captureWitness.has(w.id)) || - (history.witness === `stop` && w.id === `w_stop`) || + (stopsOnly(history) && w.id === `w_stop`) || (history.witness === `budget` && w.id === `w_slowpair`), ) .map((w) => ({ @@ -2879,8 +2907,18 @@ function resolveHistory(history) { // an explicit one (a default directory is chosen by the CLI). logBlocked: history.logBlocked === true && outModeOf(history) === `explicit`, - overlap: history.overlap === true && outModeOf(history) === `explicit`, + // A second run needs a live first run, which has its note and stream log. + // A blocked log refuses the first run before it is live, and a refusing + // fault (an argument, declaration, or config fault) ends it before its note + // too, so the overlap is generated only for a run that reaches its check + // (decision of 2026-11-13, review of #57: O1 and O2). + overlap: + history.overlap === true && + outModeOf(history) === `explicit` && + history.logBlocked !== true && + (history.fault ?? `none`) === `none`, stopRuns: history.stopRuns ?? [], + spawnStop: history.spawnStop === true, onlyRun: history.onlyRun === true, pragma: history.pragma === true, cliPath: history.cliPath ?? `plain`, 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 cddd89c9..1cb305bb 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -719,6 +719,9 @@ const strays = (dir, before, running = false) => * one done line and no refusal. */ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { + // `spawn`: the signal comes as the CLI starts, once its own code runs (a + // signal during Node's own start has no handler yet; Limits of #57). + const atSpawn = when === `spawn` const after = when === `after` const warm = when === `warm` // With `abort`, no signal comes: a test of file a aborts the run's @@ -786,11 +789,13 @@ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { if (abort) await Promise.race([exit, sleep(120_000)]) const spun = abort ? exited - : after - ? stdout.includes(`oracle-gaps: done completed`) && !exited - : warm - ? existsSync(join(pids, `warming`)) && !exited - : readdirSync(pids).length >= 2 + : atSpawn + ? !exited + : after + ? stdout.includes(`oracle-gaps: done completed`) && !exited + : warm + ? existsSync(join(pids, `warming`)) && !exited + : readdirSync(pids).length >= 2 const strayWhileRunning = strays(dir, before, true) if (!abort) child.kill(signal) const ended = await Promise.race([exit, sleep(30_000).then(() => false)]) @@ -946,13 +951,25 @@ async function overlappingRuns(dir, files, how) { return { got, status } } const first = start() - // The first run's note is its first stdout line: its stream log exists. + let firstEnded = false + first.status.then(() => { + firstEnded = true + }) + // The first run's note is its first stdout line: its stream log exists. A + // first run that ends first never had a live output directory, so the + // overlap cannot be observed: the driver says so, rather than waiting. for ( let waited = 0; - !first.got.stdout.includes(`oracle-gaps: note log`) && waited < 120_000; + !first.got.stdout.includes(`oracle-gaps: note log`) && + !firstEnded && + waited < 120_000; waited += 20 ) await sleep(20) + if (!first.got.stdout.includes(`oracle-gaps: note log`)) + throw new Error( + `the first run ended before its stream log existed; an overlap needs a live first run`, + ) const second = start() const secondStatus = await second.status const firstStatus = await first.status @@ -1832,7 +1849,12 @@ async function driver(plan, observe) { // session directories the package has once the run ended, and how many // of them the previous stopped run had left. if (cli.exit === 0 && stopIds.length > 0) - for (const stop of plan.stopRuns) { + for (const stop of [ + ...plan.stopRuns, + ...(plan.spawnStop + ? [{ signal: `SIGINT`, pool: `threads`, when: `spawn` }] + : []), + ]) { const run = await stoppedRun(dir, files, how, stopIds, stop) const stopped = { ...run, @@ -1853,6 +1875,10 @@ async function driver(plan, observe) { states.add(`a stop signal after the completed line`) continue } + if (stop.when === `spawn`) { + states.add(`a stop as the CLI starts`) + continue + } if (stop.when === `warm`) { states.add(`a stop signal while the config warms`) continue @@ -2367,7 +2393,7 @@ function check(plan, observations, expected) { `ownership`, ) const breach = refusalBreach(overlap.ending, { - cause: `another run is using`, + cause: `another run (pid `, outKnown: false, }) if (breach) return violation(`overlap`, breach, `report-shaped ending`) @@ -3365,6 +3391,7 @@ const staticStates = [ `owned through bind`, ] const required = [ + `a stop as the CLI starts`, `a stream log that cannot be written`, `two runs on one output directory`, `a run with the default output directory`, @@ -3536,7 +3563,19 @@ const faults = [ `setupThrows`, ...analyzedFaults, ] +// The states that each named constructed history enters, and only that +// history: they are not witnessed by "every outcome class" (a named history +// of its own must enter them, or registration fails). +const ownHistoryStates = [ + `a stop as the CLI starts`, + `a stream log that cannot be written`, + `two runs on one output directory`, + `a run with the default output directory`, + `a stop with the default output directory`, + `a daemon check with the default output directory`, +] const separate = [ + ...ownHistoryStates, `ordinary tests left out by default`, `two authored mutants judged apart`, `a package with a prebuilt addon deep in its tree ran in child processes`, @@ -3595,6 +3634,12 @@ const withDeclaration = (constructed) => build: (generated) => item.build({ ...generated, + // The end-to-end dimensions a generated base may draw: a construction + // that does not name them runs without them (review of #57, apiLess). + logBlocked: false, + overlap: false, + spawnStop: false, + stopWitness: false, declaration: index % 2 === 0 ? `wrapper` : `oracleProperty`, ownerless: false, owners: [`a`, ...generated.owners.slice(1)], @@ -3691,7 +3736,8 @@ oracleProperty({ libraryOwners: [], runes: [], wholeFile: `none`, - witness: `stop`, + witness: false, + stopWitness: true, tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], authored: null, fault: `none`, @@ -3733,6 +3779,37 @@ oracleProperty({ budget: `two`, }), }, + { + // A stop sent as the CLI spawns, before its note's run has started: + // the note is written first, and the stopped line follows it on both + // streams, with one done line (P1 of the review of #57). + name: `a stop as the CLI starts`, + enters: [`a stop as the CLI starts`], + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], + wholeFile: `none`, + witness: false, + stopWitness: true, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, + steps: null, + ordinary: false, + outMode: `explicit`, + logBlocked: false, + overlap: false, + spawnStop: true, + budget: `two`, + }), + }, { // A stream log that is a directory cannot be written: the CLI refuses // before its first line (index.mjs opens the log first), with its diff --git a/packages/oracles/scripts/e2e-shards.mjs b/packages/oracles/scripts/e2e-shards.mjs index c25528f8..cbe86c5d 100644 --- a/packages/oracles/scripts/e2e-shards.mjs +++ b/packages/oracles/scripts/e2e-shards.mjs @@ -78,6 +78,7 @@ export const shards = { ], // 522 s in the measured run, about 221 s idle. 'e2e-2': [ + `fixed seed 20261105: a stop at spawn`, `fixed seed 20261105: a declaration fault: setupThrows`, `fixed seed 20261105: a package with no config`, `fixed seed 20261105: an ambiguous authored mutant`, @@ -110,6 +111,7 @@ export const shards = { ], // 522 s in the measured run, about 221 s idle. 'e2e-3': [ + `determinism: constructed history: a stop at spawn`, `random seed: a stop with the default output directory`, `random seed: a daemon check with the default output directory`, `random seed: a stream log that cannot be written`, @@ -144,6 +146,7 @@ export const shards = { ], // 522 s in the measured run, about 221 s idle. 'e2e-4': [ + `random seed: a stop at spawn`, `fixed seed 20261105: a .ts config in a package with no module type that calls require`, `fixed seed 20261105: a config that --config names`, `fixed seed 20261105: a declaration fault: apiLessTypescript`, From 4d6cc15cdde866e2b6c4ae55d0f92d53eaaf2258 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Fri, 13 Nov 2026 11:13:05 -0700 Subject: [PATCH 06/62] fix(oracle-gaps): claim the output directory atomically and release run.pid on exit A run claims its output directory with run.pid: a temp file that already holds the pid, linked to run.pid (fails if it exists), so two starts cannot both claim. The claim is released on every exit but SIGKILL. A claim whose pid is gone is taken over; a live one refuses the second run and names the pid. Oracle: the spawn-delay law (outcome a or b, judged by the started marker, added with the next commit), the overlap hold guard (a test-only hook), the stop history that waits for the CLI to start, and the appended history fields. Co-authored-by: Isaac --- README.md | 2 +- .../oracle-gaps/gap-report-model-oracle.mjs | 6 ++ .../gap-report-oracle.property.test.mjs | 68 ++++++++++++++--- packages/oracles/oracle-gaps/index.mjs | 74 ++++++++++++------- packages/oracles/scripts/e2e-shards.mjs | 6 +- 5 files changed, 114 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 655a7d96..0d19451c 100644 --- a/README.md +++ b/README.md @@ -129,7 +129,7 @@ every commit with [pkg.pr.new](https://pkg.pr.new). For contributors: two environment variables in the `ORACLE_GAPS_TEST_` namespace are test-only hooks for the CLI's own oracle, not settings for - users. `ORACLE_GAPS_TEST_HOLD_EXIT_MS` holds the run's exit after its done + users. `ORACLE_GAPS_TEST_STARTED` names a file that the CLI writes as its first project statement, before any project module loads, so a test can tell a stop that came before the CLI started from one that came during its loads (test-only, like the hooks below). `ORACLE_GAPS_TEST_HOLD_EXIT_MS` holds the run's exit after its done line, and `ORACLE_GAPS_TEST_WARM_PROBE` makes the first config warm-up wait where a stop signal can reach it. diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index 6c44396b..6aa882e6 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -829,6 +829,10 @@ const drawn = fc.record({ false, true, ), + // The signal of a spawn stop and when it lands, 0 to 150 ms after the CLI + // spawns (the spawn-delay law, review of #57). + spawnSignal: fc.constantFrom(`SIGINT`, `SIGINT`, `SIGTERM`), + spawnDelay: fc.integer({ min: 0, max: 150 }), }) // The edit sequence over the witness module, the one list of steps that a @@ -2919,6 +2923,8 @@ function resolveHistory(history) { (history.fault ?? `none`) === `none`, stopRuns: history.stopRuns ?? [], spawnStop: history.spawnStop === true, + spawnSignal: history.spawnSignal ?? `SIGINT`, + spawnDelay: history.spawnDelay ?? 0, onlyRun: history.onlyRun === true, pragma: history.pragma === true, cliPath: history.cliPath ?? `plain`, 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 1cb305bb..ad17e9ae 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -718,7 +718,13 @@ const strays = (dir, before, running = false) => * Vitest's does; re-review N1). The run then ends stopped, with exactly * one done line and no refusal. */ -async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { +async function stoppedRun( + dir, + files, + how, + ids, + { signal, pool, when, delay = 0 }, +) { // `spawn`: the signal comes as the CLI starts, once its own code runs (a // signal during Node's own start has no handler yet; Limits of #57). const atSpawn = when === `spawn` @@ -740,15 +746,23 @@ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { only: ids, pool: abort ? `threads` : pool, }) + // The started marker: the CLI writes it as its first statement (index.mjs). + const startedPath = join(pids, `started`) const child = spawn(process.execPath, args, { cwd: repo, - env: after - ? { ...cleanEnv(), ORACLE_GAPS_TEST_HOLD_EXIT_MS: `500` } - : warm - ? { ...cleanEnv(), ORACLE_GAPS_TEST_WARM_PROBE: join(pids, `warming`) } - : abort - ? { ...cleanEnv(), GAP_ABORT: `1` } - : { ...cleanEnv(), GAP_STOP_DIR: pids }, + env: { + ...(atSpawn ? { ORACLE_GAPS_TEST_STARTED: startedPath } : {}), + ...(after + ? { ...cleanEnv(), ORACLE_GAPS_TEST_HOLD_EXIT_MS: `500` } + : warm + ? { + ...cleanEnv(), + ORACLE_GAPS_TEST_WARM_PROBE: join(pids, `warming`), + } + : abort + ? { ...cleanEnv(), GAP_ABORT: `1` } + : { ...cleanEnv(), GAP_STOP_DIR: pids }), + }, stdio: [`ignore`, `pipe`, `pipe`], }) let stdout = `` @@ -773,6 +787,7 @@ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { let waited = 0; !exited && !abort && + !atSpawn && (after ? !stdout.includes(`oracle-gaps: done completed`) : warm @@ -797,6 +812,7 @@ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { ? existsSync(join(pids, `warming`)) && !exited : readdirSync(pids).length >= 2 const strayWhileRunning = strays(dir, before, true) + if (atSpawn) await sleep(delay) if (!abort) child.kill(signal) const ended = await Promise.race([exit, sleep(30_000).then(() => false)]) await sleep(1000) @@ -834,6 +850,9 @@ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { ] const result = { signal, + // Whether the CLI wrote its started marker before the signal (outcomes a and b). + started: atSpawn ? existsSync(startedPath) : undefined, + stdoutLength: stdout.length, pool, spun, ended, @@ -928,10 +947,18 @@ async function overlappingRuns(dir, files, how) { writeFixture(dir, files) const before = new Set(filesUnder(dir)) const { args, out } = cliArgs(dir, files, how) - const start = () => { + const start = (holdMs) => { const child = spawn(process.execPath, args, { cwd: repo, - env: cleanEnv(), + // A test-only hold (ORACLE_GAPS_TEST_HOLD_EXIT_MS, index.mjs): the first + // run keeps its output claim until the second has been refused, so the + // overlap does not depend on how fast the first run ends. + env: { + ...cleanEnv(), + ...(holdMs === undefined + ? {} + : { ORACLE_GAPS_TEST_HOLD_EXIT_MS: String(holdMs) }), + }, stdio: [`ignore`, `pipe`, `pipe`], }) const got = { stdout: ``, stderr: `` } @@ -950,7 +977,7 @@ async function overlappingRuns(dir, files, how) { }) return { got, status } } - const first = start() + const first = start(5000) let firstEnded = false first.status.then(() => { firstEnded = true @@ -1852,7 +1879,14 @@ async function driver(plan, observe) { for (const stop of [ ...plan.stopRuns, ...(plan.spawnStop - ? [{ signal: `SIGINT`, pool: `threads`, when: `spawn` }] + ? [ + { + signal: plan.spawnSignal, + pool: `threads`, + when: `spawn`, + delay: plan.spawnDelay, + }, + ] : []), ]) { const run = await stoppedRun(dir, files, how, stopIds, stop) @@ -2756,6 +2790,13 @@ function check(plan, observations, expected) { function streamBreach(checkpoint, run, expected, plan) { const breach = (difference, extra) => violation(checkpoint, difference, `greppable stream`, extra) + // The spawn-delay law (review of #57): a stop before the CLI started (no + // started marker) is outcome (a): no output, no log, the exit by signal. + // Once the marker exists, the outcome is (b) in full. + if (run.started === false) + return run.stdoutLength === 0 && !run.log.exists && run.exit !== 0 + ? undefined + : breach(`a stop before the CLI started left output or a log`) const ends = endsBreach(run, { checked: !expected.refused?.arguments }) if (ends) return breach(ends.difference, ends.extra) if (run.stream.mutantBeforeVerdict) @@ -3807,6 +3848,9 @@ oracleProperty({ logBlocked: false, overlap: false, spawnStop: true, + // Pinned inside the CLI's module-load window (about 20–50 ms after + // spawn, measured): the handlers must already be installed there. + spawnDelay: 30, budget: `two`, }), }, diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index 349b96ef..078c2949 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -124,6 +124,7 @@ import { spawn } from 'node:child_process' import { appendFileSync, + linkSync, mkdirSync, readFileSync, realpathSync, @@ -170,37 +171,58 @@ const alive = (pid) => { return error.code === `EPERM` } } +// The pid this process claimed each output directory with, released when the +// process exits (on every exit but SIGKILL). +const claims = new Set() +process.on(`exit`, () => { + for (const claim of claims) { + try { + if (Number(readFileSync(claim, `utf8`)) === process.pid) + rmSync(claim, { force: true }) + } catch { + // Already gone. + } + } +}) /** - * Claims output directory `out` for this process: a run keeps it while it - * lives, and a second run on it refuses, reportless so that the live run's - * files stay its own (the maintainer's decision of 2026-11-13). A claim by a - * run that has ended is taken over. + * Claims output directory `out` for this process (review of #57, P2 and P3): + * a run keeps it while it lives, and a second run on it refuses without + * writing into it (the maintainer's decision of 2026-11-13). The claim is a + * temp file that already holds the pid, linked to `run.pid`, which fails when + * `run.pid` exists, so the claim is atomic. A claim whose pid no longer runs + * is taken over. */ function claimOut(out) { const claim = join(out, `run.pid`) - for (;;) { - try { - writeFileSync(claim, `${process.pid}\n`, { flag: `wx` }) - return - } catch (error) { - if (error.code !== `EEXIST`) throw cannotWrite(claim, error) - } - let holder - try { - holder = Number(readFileSync(claim, `utf8`)) - } catch (error) { - if (error.code !== `ENOENT`) throw cannotWrite(claim, error) - continue - } - if (holder !== process.pid && holder > 0 && alive(holder)) { - const refusal = new Refusal( - `another run is using ${out}`, - `Pass --out a directory no run is using, or wait for the run that uses it to end.`, - ) - refusal.reportless = true - throw refusal + const temp = `${claim}.${process.pid}.tmp` + try { + mkdirSync(out, { recursive: true }) + writeFileSync(temp, `${process.pid}\n`) + } catch (error) { + throw cannotWrite(claim, error) + } + try { + for (;;) { + try { + linkSync(temp, claim) + claims.add(claim) + return + } catch (error) { + if (error.code !== `EEXIST`) throw cannotWrite(claim, error) + } + const holder = Number(readFileSync(claim, `utf8`)) + if (holder !== process.pid && holder > 0 && alive(holder)) { + const refusal = new Refusal( + `another run (pid ${holder}) is using ${out}`, + `If no run is using it, delete ${claim}; otherwise pass --out a directory no run is using.`, + ) + refusal.reportless = true + throw refusal + } + rmSync(claim, { force: true }) } - rmSync(claim, { force: true }) + } finally { + rmSync(temp, { force: true }) } } /** diff --git a/packages/oracles/scripts/e2e-shards.mjs b/packages/oracles/scripts/e2e-shards.mjs index cbe86c5d..27191c5d 100644 --- a/packages/oracles/scripts/e2e-shards.mjs +++ b/packages/oracles/scripts/e2e-shards.mjs @@ -78,7 +78,7 @@ export const shards = { ], // 522 s in the measured run, about 221 s idle. 'e2e-2': [ - `fixed seed 20261105: a stop at spawn`, + `fixed seed 20261105: a stop as the CLI starts`, `fixed seed 20261105: a declaration fault: setupThrows`, `fixed seed 20261105: a package with no config`, `fixed seed 20261105: an ambiguous authored mutant`, @@ -111,7 +111,7 @@ export const shards = { ], // 522 s in the measured run, about 221 s idle. 'e2e-3': [ - `determinism: constructed history: a stop at spawn`, + `determinism: constructed history: a stop as the CLI starts`, `random seed: a stop with the default output directory`, `random seed: a daemon check with the default output directory`, `random seed: a stream log that cannot be written`, @@ -146,7 +146,7 @@ export const shards = { ], // 522 s in the measured run, about 221 s idle. 'e2e-4': [ - `random seed: a stop at spawn`, + `random seed: a stop as the CLI starts`, `fixed seed 20261105: a .ts config in a package with no module type that calls require`, `fixed seed 20261105: a config that --config names`, `fixed seed 20261105: a declaration fault: apiLessTypescript`, From a2d51b903949fe14ea90f81a34db3bc10bc48419 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Fri, 13 Nov 2026 11:13:07 -0700 Subject: [PATCH 07/62] fix(oracle-gaps): install the stop handlers before any project module loads The CLI's first project statement is now the handler install, so a stop that arrives during the loads is kept and acted on once the note is written. The single run path (P4) is in the same file; the static-import variant with the same handlers passed the default-out units, so the dynamic loads are not the cause of any batch failure (review of #57). A test-only marker, ORACLE_GAPS_TEST_STARTED, is written as the first project statement so the oracle can tell a stop before the CLI started (no output is allowed) from one during its loads (the full output is required). Co-authored-by: Isaac --- packages/oracles/oracle-gaps/index.mjs | 247 +++++++++++++------------ 1 file changed, 127 insertions(+), 120 deletions(-) diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index 078c2949..827c27dc 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -121,6 +121,10 @@ // SIGINT or SIGTERM is sent on to the whole group; a process that has not // ended 2 s later is killed, and so is any process left in the group when // the run ends. The run kills its group itself if the CLI dies first. +// The stop handlers and the claim on the output directory come before the +// CLI's modules load (review of #57, P1): a signal during the loads is kept +// and acted on once the stream log's note is written, so a stop as the CLI starts still +// leaves the note and one done line. Only Node's own start is before them. import { spawn } from 'node:child_process' import { appendFileSync, @@ -134,23 +138,32 @@ import { import { constants } from 'node:os' import { join } from 'node:path' import { pathToFileURL } from 'node:url' -import { parseArgs, usage } from './args.mjs' -import { codeIdentity, openSession } from './check.mjs' -import { received, requestDaemon, stopDaemon } from './daemon.mjs' -import { endRun, Refusal } from './ending.mjs' -import { memoryStore } from './evidence.mjs' + +// A test-only marker (ORACLE_GAPS_TEST_STARTED): the first statement that runs +// project code writes this file, before any project module loads, so a test can +// tell a stop that came before the CLI started from one that came during its loads. +if (process.env.ORACLE_GAPS_TEST_STARTED) + writeFileSync(process.env.ORACLE_GAPS_TEST_STARTED, ``) + +let early +const keepEarly = (signal) => { + early ??= signal +} +process.on(`SIGINT`, keepEarly) +process.on(`SIGTERM`, keepEarly) +const { parseArgs, usage } = await import(`./args.mjs`) +const { endRun, Refusal } = await import(`./ending.mjs`) // How long the group has to end after a stop signal before it is killed. const STOP_GRACE_MS = 2000 // The stream log (the maintainer's decision of 2026-11-12): a run that -// starts a check writes its stderr to `/stream.log` too, line for -// line, and names that file in its first line on both streams, so an agent -// that runs a check in the background learns from the run where to read -// it. The supervisor opens it before the child starts (startLog), and then -// is the only writer of the child's stderr to it (superviseRun). Undefined -// until the log is open. +// starts a check writes its stderr to `/stream.log` too, line for line, +// and names that file in its first line on both streams. The supervisor opens +// it before the child starts (startLog), and is then the only writer of the +// child's stderr to it (superviseRun). Undefined until the log is open. let streamLog +let writingEnding = false const logPathOf = (out) => join(out, `stream.log`) /** Writes `text` to stderr and, once the log is open, to the stream log. */ const writeStream = (text) => { @@ -226,17 +239,12 @@ function claimOut(out) { } } /** - * Opens the run's stream log in `out` and writes its first line, on both - * streams, which names the log. Throws a Refusal when the output directory - * is in use or the log cannot be written; nothing is written then. + * Claims the output directory and writes the run's first line, on both + * streams, which names the log. Throws a Refusal when the directory is in use + * or the log cannot be written; nothing is written then. */ function startLog(out) { const path = logPathOf(out) - try { - mkdirSync(out, { recursive: true }) - } catch (error) { - throw cannotWrite(path, error) - } claimOut(out) try { writeFileSync(path, ``) @@ -249,20 +257,19 @@ function startLog(out) { writeStream(note) } -/** Signals every process of group `group`; false when none is left. */ -function signalGroup(group, signal) { - try { - process.kill(-group, signal) - return true - } catch { - return false - } +/** Flushes both streams, then exits with `code` (after a test's hold). */ +function exitWhenFlushed(code) { + const hold = Number(process.env.ORACLE_GAPS_TEST_HOLD_EXIT_MS ?? 0) + process.stdout.write(``, () => + process.stderr.write(``, () => setTimeout(() => process.exit(code), hold)), + ) } /** - * Runs this CLI again as a child in a process group of its own, and ends - * with it: with its exit code, or, once a stop signal has ended its group, - * with 128 plus the signal's number. + * Runs this CLI again as a child in a process group of its own, and ends with + * it: with its exit code, or, once a stop signal has ended its group, with 128 + * plus the signal's number. The child gets `--out` appended, the directory this + * process resolved (review of #57, F2). */ function superviseRun(out) { let child @@ -270,26 +277,22 @@ function superviseRun(out) { // How the run ended: its exit code, or the signal that ended it. let ended // Whether the run said that it writes its ending (a message it sends - // before it writes): then its done line is the last on each stream, and - // it ends with its own code, whatever stop reaches it. + // before it writes): then its done line is the last on each stream, and it + // ends with its own code, whatever stop reaches it. let ending = false - // Whether the run's stderr, which the CLI passes on, said that V8 ran - // out of memory. + // Whether the run's stderr, which the CLI passes on, said that V8 ran out + // of memory. let outOfMemory = false let stderrTail = `` // Whether the run's streams and channel have closed. let closed = false - // Ends the CLI once the run has ended (or the grace has passed), with - // what is left of the group killed, and once the run's stderr has been - // passed on (at most 2 s more). A run that writes its ending wrote its - // done line, so the CLI ends with its code and writes none. Every other - // end gets one done line from the CLI, on both streams: a run that a stop - // ended stopped (review of #46, F3; re-review N1); a run whose process - // ended on its own, by a signal or a code, with no ending (a V8 - // out-of-memory abort is a SIGABRT) is an error, exit 3, with the remedy - // when it ran out of memory (the coordinator's decision of 2026-11-12 on - // P10). A write to a pipe is asynchronous on macOS, so the process exits - // once it is written. + // Ends the CLI once the run has ended (or the grace has passed), with what + // is left of the group killed. A run that writes its ending wrote its done + // line, so the CLI ends with its code and writes none. Every other end gets + // one done line from the CLI, on both streams: a stop ended the run + // (stopped); a run whose process ended on its own (a signal, a code, a V8 + // out-of-memory abort) is an error, exit 3, with the remedy when it ran out + // of memory. let finishing = false const finish = () => { if (finishing) return @@ -335,18 +338,18 @@ function superviseRun(out) { finish() }, 50) } - // The stop handlers come first, so a signal that comes while the run - // starts is a stop too (re-review N3). + // The stop handlers come first, so a signal that comes while the run starts + // is a stop too. A stop that came during the CLI's loads ends the run before + // it starts: its stopped line follows the note the caller already wrote. process.on(`SIGINT`, stop) process.on(`SIGTERM`, stop) + if (early !== undefined) return stop(early) // An inspector flag would bind the CLI's own port a second time. child = spawn( process.execPath, [ ...process.execArgv.filter((flag) => !/^--inspect/.test(flag)), ...process.argv.slice(1), - // The out directory, resolved once by this process (asksForCheck): the - // run and a daemon's check write there, not to a directory of their own. `--out`, out, ], @@ -359,9 +362,9 @@ function superviseRun(out) { child.on(`message`, (message) => { if (message === `ending`) ending = true }) - // The run's stderr, passed on as it comes, written to the stream log as it - // is (V8's own lines included, which the run does not write itself), and - // read for V8's out-of-memory message. + // The run's stderr, passed on as it comes, written to the stream log as it is + // (V8's own lines included, which the run does not write itself), and read + // for V8's out-of-memory message. child.stderr.on(`data`, (chunk) => { process.stderr.write(chunk) appendFileSync(streamLog, chunk) @@ -377,9 +380,19 @@ function superviseRun(out) { }) } +/** Signals every process of group `group`; false when none is left. */ +function signalGroup(group, signal) { + try { + process.kill(-group, signal) + return true + } catch { + return false + } +} + /** - * The run's side of the group: once the CLI that started it is gone, the - * run kills its group, itself included. + * The run's side of the group: once the CLI that started it is gone, the run + * kills its group, itself included. */ function watchSupervisor(supervisor) { setInterval(() => { @@ -388,8 +401,9 @@ function watchSupervisor(supervisor) { } /** - * Whether arguments `argv` ask for a check, the only run that starts - * processes; a refusal of them is written by the run itself. + * The options of arguments `argv` when they ask for a check, the only run that + * starts processes; undefined for help, a stop, or arguments that refuse (a + * refusal is written by the run itself). */ function asksForCheck(argv) { try { @@ -402,6 +416,8 @@ function asksForCheck(argv) { /** The summary of a check run in this process. */ async function checkCold(options) { + const { openSession } = await import(`./check.mjs`) + const { memoryStore } = await import(`./evidence.mjs`) const session = await openSession(options.pkg) try { return await session.check(options, memoryStore(), (line) => @@ -414,6 +430,8 @@ async function checkCold(options) { /** The summary of a check run by the package's daemon. */ async function checkThroughDaemon(options) { + const { codeIdentity } = await import(`./check.mjs`) + const { received, requestDaemon } = await import(`./daemon.mjs`) const reply = await requestDaemon( options.pkg, process.argv.slice(2), @@ -424,6 +442,23 @@ async function checkThroughDaemon(options) { return reply.stdout } +// The run's ending, once: its refusal or error is written to its output +// directory and stdout and stderr, and the process exits with its code. +let ended = false +const holdStops = () => { + writingEnding = true + process.send?.(`ending`) +} +function endWith(error, out) { + if (ended) return + ended = true + const ending = endRun(error, out) + holdStops() + writeStream(ending.stderr) + process.stdout.write(`${ending.done}\n`) + exitWhenFlushed(ending.exitCode) +} + // A file URL escapes a space, `#`, and the like, so the script's own URL is // compared with the URL of the path it was started as. const main = @@ -431,80 +466,50 @@ const main = // Windows has no process groups: there the run is the CLI's own process. const supervised = process.platform !== `win32` const supervisor = process.env.ORACLE_GAPS_GROUP -const checking = - main && supervised && supervisor === undefined - ? asksForCheck(process.argv.slice(2)) - : undefined -// A check the supervisor cannot open its log for is run in this process, which -// refuses it the same way (below). -const supervising = (() => { - if (checking === undefined) return false - try { - startLog(checking.out) - return true - } catch { - return false + +async function run() { + // The supervisor: it claims the output directory, writes the note, and runs + // the child. A refusal of the claim or the log ends it through endWith (the + // single path for every refusal of a check). + if (supervised && supervisor === undefined) { + const checking = asksForCheck(process.argv.slice(2)) + if (checking !== undefined) { + try { + startLog(checking.out) + } catch (error) { + return endWith(error, checking.out) + } + return superviseRun(checking.out) + } } -})() -if (supervising) superviseRun(checking.out) -else if (main) { if (supervisor !== undefined) watchSupervisor(Number(supervisor)) // A test that runs this CLI starts a run of its own, in a group of its own. delete process.env.ORACLE_GAPS_GROUP - // The run's options, once its arguments parse; a refusal or an error is - // written to their output directory. - let options - let ended = false - // Ends the run once. A write to a pipe is asynchronous on macOS, and - // exiting at once cuts it off at the pipe's buffer, so the process exits - // once both streams have written everything before it. - // A test-only hook for the CLI's own oracle, not for users: - // ORACLE_GAPS_TEST_HOLD_EXIT_MS holds the exit after the done line, so the - // CLI's oracle can send a signal in that window. - const end = (exitCode) => { - if (ended) return - ended = true - const hold = Number(process.env.ORACLE_GAPS_TEST_HOLD_EXIT_MS ?? 0) - process.stdout.write(``, () => - process.stderr.write(``, () => - setTimeout(() => process.exit(exitCode), hold), - ), - ) - } - // A stop ends the run at once, with no line: an error that the stop - // causes (a config load that it cuts off) is no refusal, and the - // supervisor writes the stopped line (re-review N1). Once the run writes - // its ending, it says so to the supervisor, and a stop no longer cuts it - // off: its done line is then the last line of each stream. - let writingEnding = false + // A stop ends the run at once, with no line: an error that the stop causes + // is no refusal, and the supervisor writes the stopped line. Once the run + // writes its ending, a stop no longer cuts it off. const onStop = (signal) => { if (!writingEnding) process.exit(128 + constants.signals[signal]) } process.on(`SIGINT`, onStop) process.on(`SIGTERM`, onStop) - const holdStops = () => { - writingEnding = true - process.send?.(`ending`) - } - const fail = (error) => { - if (ended) return - const ending = endRun(error, options?.out) - holdStops() - writeStream(ending.stderr) - process.stdout.write(`${ending.done}\n`) - end(ending.exitCode) - } - // An error thrown outside the awaited check, by a timer or a promise no - // one awaits, ends the run the same way. - process.on(`uncaughtException`, fail) - process.on(`unhandledRejection`, fail) + // A stop that came before this process could handle it ends it now. + if (early !== undefined) process.exit(128 + constants.signals[early]) + // The run's options, once its arguments parse. + let options + // An error thrown outside the awaited check, by a timer or a promise no one + // awaits, ends the run the same way. + process.on(`uncaughtException`, (error) => endWith(error, options?.out)) + process.on(`unhandledRejection`, (error) => endWith(error, options?.out)) try { options = parseArgs(process.argv.slice(2)) if (options.help) console.log(usage) - else if (options.stop) await stopDaemon(options.pkg) - else { - // The supervisor opened the log (or, on Windows, there is none and this - // process runs the check); its child writes stderr alone. + else if (options.stop) { + const { stopDaemon } = await import(`./daemon.mjs`) + await stopDaemon(options.pkg) + } else { + // Windows has no supervisor: this process opens the log and runs the + // check. A child of a supervisor writes its stderr alone. if (supervisor === undefined) startLog(options.out) const summary = await (options.daemon ? checkThroughDaemon : checkCold)( options, @@ -515,8 +520,10 @@ else if (main) { console.log(summary) writeStream(`${summary.split(`\n`).at(-1)}\n`) } - end(0) + exitWhenFlushed(0) } catch (error) { - fail(error) + endWith(error, options?.out) } } + +if (main) await run() From 2a0fdda73a86a73f49e8d5a7b8fd8e7c99a68c55 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Fri, 13 Nov 2026 19:41:52 -0700 Subject: [PATCH 08/62] test(oracle-gaps): the spawn stop signals once the CLI has started, drawn 0-150 ms otherwise The constructed stop history waits for the started marker (ORACLE_GAPS_TEST_STARTED) and then signals at once, so the signal lands in the CLI's loads on every machine. Generated histories keep the drawn 0-150 ms delay and signal (SIGINT or SIGTERM). Verified: the real CLI passes; the late-handler mutant (handlers after the project loads) is rejected with started-but-no-output. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-model-oracle.mjs | 4 ++++ .../gap-report-oracle.property.test.mjs | 20 ++++++++++++++----- 2 files changed, 19 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 6aa882e6..6b29ac73 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -833,6 +833,9 @@ const drawn = fc.record({ // spawns (the spawn-delay law, review of #57). spawnSignal: fc.constantFrom(`SIGINT`, `SIGINT`, `SIGTERM`), spawnDelay: fc.integer({ min: 0, max: 150 }), + // The spawn stop waits for the CLI's started marker, then signals at once (the + // deterministic witness, event-driven rather than timed). + spawnOnStart: fc.constantFrom(false, false, false, true), }) // The edit sequence over the witness module, the one list of steps that a @@ -2925,6 +2928,7 @@ function resolveHistory(history) { spawnStop: history.spawnStop === true, spawnSignal: history.spawnSignal ?? `SIGINT`, spawnDelay: history.spawnDelay ?? 0, + spawnOnStart: history.spawnOnStart === true, onlyRun: history.onlyRun === true, pragma: history.pragma === true, cliPath: history.cliPath ?? `plain`, 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 ad17e9ae..681948aa 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -723,7 +723,7 @@ async function stoppedRun( files, how, ids, - { signal, pool, when, delay = 0 }, + { signal, pool, when, delay = 0, onStart = false }, ) { // `spawn`: the signal comes as the CLI starts, once its own code runs (a // signal during Node's own start has no handler yet; Limits of #57). @@ -812,7 +812,16 @@ async function stoppedRun( ? existsSync(join(pids, `warming`)) && !exited : readdirSync(pids).length >= 2 const strayWhileRunning = strays(dir, before, true) - if (atSpawn) await sleep(delay) + // A spawn stop signals after its drawn delay, or, when it waits for the + // started marker, at once once the marker exists (event-driven, 30 s cap). + if (atSpawn && onStart) + for ( + let waited = 0; + !existsSync(startedPath) && waited < 30_000; + waited += 1 + ) + await sleep(1) + else if (atSpawn) await sleep(delay) if (!abort) child.kill(signal) const ended = await Promise.race([exit, sleep(30_000).then(() => false)]) await sleep(1000) @@ -1885,6 +1894,7 @@ async function driver(plan, observe) { pool: `threads`, when: `spawn`, delay: plan.spawnDelay, + onStart: plan.spawnOnStart, }, ] : []), @@ -3848,9 +3858,9 @@ oracleProperty({ logBlocked: false, overlap: false, spawnStop: true, - // Pinned inside the CLI's module-load window (about 20–50 ms after - // spawn, measured): the handlers must already be installed there. - spawnDelay: 30, + // The signal waits for the CLI's started marker, so it lands during + // the loads of a CLI that loads before it installs its handlers. + spawnOnStart: true, budget: `two`, }), }, From 76522ffe36efe51470d75fa473283e0e86e4de37 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Fri, 13 Nov 2026 20:04:20 -0700 Subject: [PATCH 09/62] test(oracle-gaps): one decision for whether a refused run owes its note A refusal of the arguments comes before any check, so its output is its done line alone, through the daemon as in a cold run. The cold stream check, the daemon stream check, and the daemon refusal's note now share owesNote(expected), instead of the daemon path applying the note requirement to every refusal. Verified: the outsideSource unit passes on the CLI; the mutant that requires a note for argument refusals fails it. Co-authored-by: Isaac --- .../gap-report-oracle.property.test.mjs | 25 ++++++++++++++----- 1 file changed, 19 insertions(+), 6 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 681948aa..0aa4df70 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -2331,7 +2331,7 @@ async function driver(plan, observe) { * Law 9: each check through the daemon reports what the cold run of the same * state reports. A refused state is compared by the cause it names. */ -function incrementalCheck(observations) { +function incrementalCheck(observations, expected) { for (const { value } of observations.filter( (o) => o.checkpoint === `incremental`, )) { @@ -2352,7 +2352,7 @@ function incrementalCheck(observations) { if (cold.refusal !== undefined) { const breach = refusalBreach(daemon.ending, { outKnown: true, - logNote: logNoteOf(daemon), + logNote: owesNote(expected) ? logNoteOf(daemon) : undefined, }) if (breach) return violation( @@ -2451,7 +2451,7 @@ function check(plan, observations, expected) { (o) => o.checkpoint === `incremental`, )) { const { daemon, cold } = value - const ends = endsBreach(daemon) + const ends = endsBreach(daemon, { checked: owesNote(expected) }) if (ends) return violation( `incremental`, @@ -2519,7 +2519,11 @@ function check(plan, observations, expected) { `the refusal before the check started wrote a stream log`, `greppable stream`, ) - return incrementalCheck(observations) ?? daemonCheck(observations) ?? pass + return ( + incrementalCheck(observations, expected) ?? + daemonCheck(observations) ?? + pass + ) } if (cli.exit !== 0 || !cli.reported) return violation( @@ -2781,7 +2785,11 @@ function check(plan, observations, expected) { { actual: after, expected: before }, ) } - return incrementalCheck(observations) ?? daemonCheck(observations) ?? pass + return ( + incrementalCheck(observations, expected) ?? + daemonCheck(observations) ?? + pass + ) } /** @@ -2797,6 +2805,11 @@ function check(plan, observations, expected) { * (stopped). `run` is a run as readRun records it, observed at * `checkpoint`. */ +// The stage at which a run refuses decides whether it owes its note (law 15, +// review of #57): a refusal of the arguments comes before any check, so its +// output is its done line alone. Both the cold run and a run through the daemon +// are judged by this one decision. +const owesNote = (expected) => !expected.refused?.arguments function streamBreach(checkpoint, run, expected, plan) { const breach = (difference, extra) => violation(checkpoint, difference, `greppable stream`, extra) @@ -2807,7 +2820,7 @@ function streamBreach(checkpoint, run, expected, plan) { return run.stdoutLength === 0 && !run.log.exists && run.exit !== 0 ? undefined : breach(`a stop before the CLI started left output or a log`) - const ends = endsBreach(run, { checked: !expected.refused?.arguments }) + const ends = endsBreach(run, { checked: owesNote(expected) }) if (ends) return breach(ends.difference, ends.extra) if (run.stream.mutantBeforeVerdict) return breach( From a784642c6af2da65cb96ab0fc6c4e18161fff0bc Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Fri, 13 Nov 2026 21:27:14 -0700 Subject: [PATCH 10/62] fix(oracle-gaps): install the stop handlers before the started marker The started marker (ORACLE_GAPS_TEST_STARTED) is written after the stop handlers are installed, so a marker means the CLI can handle a stop. A test-only pause after the marker (ORACLE_GAPS_TEST_PAUSE_AFTER_STARTED, ms) widens the window for the spawn-stop witness: with the marker before the handlers, a stop during the pause ended the CLI with a marker and no output (0 of 20 passes); with the fixed order, 40 of 40 pass. Co-authored-by: Isaac --- .../gap-report-oracle.property.test.mjs | 5 +++++ packages/oracles/oracle-gaps/index.mjs | 18 ++++++++++++------ 2 files changed, 17 insertions(+), 6 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 0aa4df70..70e0b87d 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -752,6 +752,11 @@ async function stoppedRun( cwd: repo, env: { ...(atSpawn ? { ORACLE_GAPS_TEST_STARTED: startedPath } : {}), + // The constructed witness pauses after the marker, so the signal it sends + // on seeing the marker lands inside the pause (review F2). + ...(atSpawn && onStart + ? { ORACLE_GAPS_TEST_PAUSE_AFTER_STARTED: `200` } + : {}), ...(after ? { ...cleanEnv(), ORACLE_GAPS_TEST_HOLD_EXIT_MS: `500` } : warm diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index 827c27dc..962fb9e3 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -139,18 +139,24 @@ import { constants } from 'node:os' import { join } from 'node:path' import { pathToFileURL } from 'node:url' -// A test-only marker (ORACLE_GAPS_TEST_STARTED): the first statement that runs -// project code writes this file, before any project module loads, so a test can -// tell a stop that came before the CLI started from one that came during its loads. -if (process.env.ORACLE_GAPS_TEST_STARTED) - writeFileSync(process.env.ORACLE_GAPS_TEST_STARTED, ``) - let early const keepEarly = (signal) => { early ??= signal } process.on(`SIGINT`, keepEarly) process.on(`SIGTERM`, keepEarly) +// A test-only marker (ORACLE_GAPS_TEST_STARTED): the first statement that runs +// project code writes this file, before any project module loads, so a test can +// tell a stop that came before the CLI started from one that came during its loads. +if (process.env.ORACLE_GAPS_TEST_STARTED) + writeFileSync(process.env.ORACLE_GAPS_TEST_STARTED, ``) +// A test-only pause after the marker (ORACLE_GAPS_TEST_PAUSE_AFTER_STARTED, ms): +// it blocks this thread synchronously, so a stop sent during it lands before the +// handlers below are installed (the widened witness of review F2). Inert unless set. +const pauseMs = Number(process.env.ORACLE_GAPS_TEST_PAUSE_AFTER_STARTED ?? 0) +if (pauseMs > 0) + Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, pauseMs) + const { parseArgs, usage } = await import(`./args.mjs`) const { endRun, Refusal } = await import(`./ending.mjs`) From d338cb16c2b59ebc5089a9e9cbc2dc86bc7b7fe6 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Fri, 13 Nov 2026 22:07:28 -0700 Subject: [PATCH 11/62] fix(oracle-gaps): take over a stale claim under a mutex, and name results.json's state A stale run.pid is taken over only by the racer that creates run.pid.takeover (a directory only one racer can make), and only after it re-reads the stale pid under the mutex. Two concurrent starts against a stale claim now yield exactly one claim (witness: 5 of 5 trials, one claimant each; the mutant without the mutex and the re-read yields two in 5 of 5). A test-only pause (ORACLE_GAPS_TEST_PAUSE_AT, inert unless set) widens the window. The results-beside-log message names the directory and whether results.json is missing, unparseable or read (batch 3, issue #76). Co-authored-by: Isaac --- .../gap-report-oracle.property.test.mjs | 12 +++- packages/oracles/oracle-gaps/index.mjs | 67 ++++++++++++++++++- 2 files changed, 75 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 70e0b87d..1f450287 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1241,10 +1241,16 @@ function readRunIn(dir, out, status, stderr, cli, stdout, derived) { let results let report let summary = `` + // The state of `results.json` in the output directory: missing, unparseable, + // or read (review of #57, batch 3: the message names which). + let reportState = `missing` try { - report = JSON.parse(readFileSync(join(out, `results.json`), `utf8`)) + const text = readFileSync(join(out, `results.json`), `utf8`) + reportState = `unparseable` + report = JSON.parse(text) results = report.results summary = readFileSync(join(out, `summary.md`), `utf8`) + reportState = `read` } catch { // A run that wrote no report is recorded by its exit status and output. } @@ -1348,6 +1354,7 @@ function readRunIn(dir, out, status, stderr, cli, stdout, derived) { ? undefined : `${status === 3 && existsSync(join(out, `error.log`)) ? `error.log: ${namedScratch(readFileSync(join(out, `error.log`), `utf8`), scratch).slice(0, 2000)}\n` : ``}${named.slice(-1500)}`, reported: results !== undefined, + reportState, streamed, // Law 9 compares everything the run reports except how it was // produced: durations, the options it was given (the output directory @@ -1552,6 +1559,7 @@ async function incremental(dir, plan, cli, copy, observe, states) { log: run.log, outDir: run.outDir, reported: run.reported, + reportState: run.reportState, // The first line of a failure, for the message; readRun has named // the scratch package and CLI copy in it. stderr: run.stderr?.split(`\n`)[0], @@ -2903,7 +2911,7 @@ function endsBreach(run, { checked = true } = {}) { // of 2026-11-12). if (checked && run.exit === 0 && run.reported === false) return { - difference: `the run completed, but its results.json is not beside its stream log`, + difference: `the run completed, but ${run.outDir}/results.json is ${run.reportState ?? `missing or unparseable`}, not beside its stream log`, } for (const [where, stream] of streams) if (stream.strays.length > 0) diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index 962fb9e3..c9443035 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -213,6 +213,7 @@ process.on(`exit`, () => { */ function claimOut(out) { const claim = join(out, `run.pid`) + const takeover = `${claim}.takeover` const temp = `${claim}.${process.pid}.tmp` try { mkdirSync(out, { recursive: true }) @@ -229,7 +230,8 @@ function claimOut(out) { } catch (error) { if (error.code !== `EEXIST`) throw cannotWrite(claim, error) } - const holder = Number(readFileSync(claim, `utf8`)) + const holder = readHolder(claim) + if (holder === undefined) continue if (holder !== process.pid && holder > 0 && alive(holder)) { const refusal = new Refusal( `another run (pid ${holder}) is using ${out}`, @@ -238,12 +240,73 @@ function claimOut(out) { refusal.reportless = true throw refusal } - rmSync(claim, { force: true }) + // A stale claim: only the racer that creates the takeover mutex removes it, + // and only if it still names the stale pid it read (review F4). + testPause(`takeover`) + if (!takeMutex(takeover)) { + sleepMs(10) + continue + } + try { + if (readHolder(claim) === holder) rmSync(claim, { force: true }) + } finally { + rmSync(takeover, { recursive: true, force: true }) + } } } finally { rmSync(temp, { force: true }) } } +/** The pid a claim names, or undefined when the claim is gone. */ +function readHolder(claim) { + try { + return Number(readFileSync(claim, `utf8`)) + } catch (error) { + if (error.code === `ENOENT`) return undefined + throw cannotWrite(claim, error) + } +} +/** + * Creates the takeover mutex: a directory only one racer can make. A mutex + * whose pid is gone (a crashed racer) is removed and made again; that rare case + * is in Limits. + */ +function takeMutex(mutex) { + try { + mkdirSync(mutex) + } catch (error) { + if (error.code !== `EEXIST`) throw error + const owner = Number( + (() => { + try { + return readFileSync(join(mutex, `pid`), `utf8`) + } catch { + return `` + } + })(), + ) + if (!(owner > 0 && alive(owner))) { + rmSync(mutex, { recursive: true, force: true }) + return takeMutex(mutex) + } + return false + } + writeFileSync(join(mutex, `pid`), `${process.pid}\n`) + return true +} +/** A test-only pause (ORACLE_GAPS_TEST_PAUSE_AT, inert unless set), see README. */ +function testPause(point) { + if (process.env.ORACLE_GAPS_TEST_PAUSE_AT === point) + Atomics.wait( + new Int32Array(new SharedArrayBuffer(4)), + 0, + 0, + Number(process.env.ORACLE_GAPS_TEST_PAUSE_MS ?? 0), + ) +} +function sleepMs(ms) { + Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms) +} /** * Claims the output directory and writes the run's first line, on both * streams, which names the log. Throws a Refusal when the directory is in use From 6222e257373fcf99abd1d0b2a294c5288f1fd97a Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 02:35:42 -0700 Subject: [PATCH 12/62] ci(oracles): place the new Windows fixed-seed units in shards The fixed-seed units added with the spawn stop, the stream log, and the overlap (five units) were not in any Windows fixed-seed shard, so the pr-shards partition check failed in the Test job. Placed in shards 2 and 3. Co-authored-by: Isaac --- packages/oracles/scripts/pr-shards.mjs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/oracles/scripts/pr-shards.mjs b/packages/oracles/scripts/pr-shards.mjs index 9e162886..bb476807 100644 --- a/packages/oracles/scripts/pr-shards.mjs +++ b/packages/oracles/scripts/pr-shards.mjs @@ -524,6 +524,8 @@ export const partitions = { "test.projects in a parent's config", ]), 2: anyOf([ + 'a stop with the default output directory', + 'a daemon check with the default output directory', 'a .ts config in a package with no module type that calls require', 'a declaration fault: brokenVitest', 'a declaration fault: noTypescript', @@ -533,6 +535,9 @@ export const partitions = { 'two authored mutants', ]), 3: anyOf([ + 'a stop as the CLI starts', + 'a stream log that cannot be written', + 'two runs on one output directory', 'a config fault in a run that owns nothing', 'a declaration fault: configNoDefault', 'a declaration fault: nonLiteral', From 5fa74e07e75260c2467c97b8ff1cdbc0c6cdce04 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 07:57:19 -0700 Subject: [PATCH 13/62] chore(oracle-gaps): drop the unsupervised POSIX seam The unsupervised (win32) path is being replaced by a win32 supervisor (#74), so the seam that forced it on POSIX is removed; its stop witness was not kept. The unsupervised path's stop law (no done line on a stop) is a Limit of this PR. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/index.mjs | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index b6d1a7d5..75828f6d 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -542,11 +542,7 @@ function endWith(error, out) { const main = import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href // Windows has no process groups: there the run is the CLI's own process. -// The test seam ORACLE_GAPS_TEST_UNSUPERVISED forces the unsupervised path on -// POSIX (in-process, as win32 runs it), so its stop law is tested without Windows. -const supervised = - process.platform !== `win32` && - process.env.ORACLE_GAPS_TEST_UNSUPERVISED === undefined +const supervised = process.platform !== `win32` const supervisor = process.env.ORACLE_GAPS_GROUP // Set once the note is written (the unsupervised run has started). From 9560e86eabe95d177c0862ccfe2cb7117335b2cd Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 09:45:15 -0700 Subject: [PATCH 14/62] fix(oracle-gaps): create the takeover mutex with its pid, and never take over an unreadable claim The takeover mutex was made as a directory and its pid written after, so a racer could read it empty, take it for dead, and remove a live mutex. The pid is now written to a temp file and linked into place, so no reader sees an empty mutex. An unreadable or empty mutex or claim counts as live and is never taken over. Witness (two concurrent starts against a stale claim, a test pause between the create and the pid write): the current code gives one claimed and one crashing run in every trial; the fix gives one claimed and one refused in every trial. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/index.mjs | 38 ++++++++++++++------------ 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index 75828f6d..99c34127 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -233,6 +233,11 @@ function claimOut(out) { } const holder = readHolder(claim) if (holder === undefined) continue + // An unreadable claim counts as live: wait for it, never take it over. + if (!(holder > 0)) { + sleepMs(10) + continue + } if (holder !== process.pid && holder > 0 && alive(holder)) { const refusal = new Refusal( `another run (pid ${holder}) is using ${out}`, @@ -268,32 +273,31 @@ function readHolder(claim) { } } /** - * Creates the takeover mutex: a directory only one racer can make. A mutex - * whose pid is gone (a crashed racer) is removed and made again; that rare case - * is in Limits. + * Takes the takeover mutex. The pid is written to a temp file first and linked + * into place, so no reader ever sees an empty mutex (review F4; register: #57 + * claim rules). A mutex whose pid can't be read counts as live and is never + * taken over; only a mutex whose recorded pid is dead is removed, and then made + * again. */ function takeMutex(mutex) { + const temp = `${mutex}.${process.pid}.tmp` + writeFileSync(temp, `${process.pid}\n`) try { - mkdirSync(mutex) + testPause(`mutex-create`) + linkSync(temp, mutex) + return true } catch (error) { if (error.code !== `EEXIST`) throw error - const owner = Number( - (() => { - try { - return readFileSync(join(mutex, `pid`), `utf8`) - } catch { - return `` - } - })(), - ) - if (!(owner > 0 && alive(owner))) { - rmSync(mutex, { recursive: true, force: true }) + const owner = readHolder(mutex) + if (owner === undefined) return false + if (owner > 0 && !alive(owner)) { + rmSync(mutex, { force: true }) return takeMutex(mutex) } return false + } finally { + rmSync(temp, { force: true }) } - writeFileSync(join(mutex, `pid`), `${process.pid}\n`) - return true } /** A test-only pause (ORACLE_GAPS_TEST_PAUSE_AT, inert unless set), see README. */ function testPause(point) { From c8352b8ae30f7c85efaf818c9bd2b8b926fb3b02 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 09:45:18 -0700 Subject: [PATCH 15/62] docs(oracle-gaps): document every test-only ORACLE_GAPS_TEST hook Co-authored-by: Isaac --- README.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 46ac75aa..2881da57 100644 --- a/README.md +++ b/README.md @@ -131,11 +131,16 @@ agent. end of its check, so the file fills then. `--help` is not a check, so its usage text has no prefix. - For contributors: two environment variables in the `ORACLE_GAPS_TEST_` - namespace are test-only hooks for the CLI's own oracle, not settings for - users. `ORACLE_GAPS_TEST_STARTED` names a file that the CLI writes as its first project statement, before any project module loads, so a test can tell a stop that came before the CLI started from one that came during its loads (test-only, like the hooks below). `ORACLE_GAPS_TEST_HOLD_EXIT_MS` holds the run's exit after its done - line, and `ORACLE_GAPS_TEST_WARM_PROBE` makes the first config warm-up - wait where a stop signal can reach it. + For contributors: the `ORACLE_GAPS_TEST_` environment variables are test-only + hooks for the CLI's own oracle, not settings for users. Each is inert unless + set; a hook may pause at one named point and never changes an outcome. + `ORACLE_GAPS_TEST_STARTED` names a file that the CLI writes as its first project statement, before any project module loads, so a test can tell a stop that came before the CLI started from one that came during its loads. + `ORACLE_GAPS_TEST_PAUSE_AFTER_STARTED` (milliseconds) blocks the CLI for that long right after the started file is written, so a stop sent on seeing the file lands inside the pause. + `ORACLE_GAPS_TEST_PAUSE_AT` names one point at which `ORACLE_GAPS_TEST_PAUSE_MS` (milliseconds) blocks the CLI: `takeover` (inside a stale-claim takeover, after the stale pid is read) and `mutex-create` (inside the takeover mutex's creation). + `ORACLE_GAPS_TEST_STOP` names a file whose appearance makes the CLI take a stop as a SIGINT would. + `ORACLE_GAPS_TEST_HOLD_EXIT_MS` holds the run's exit after its done line, + and `ORACLE_GAPS_TEST_WARM_PROBE` makes the first config warm-up wait where a + stop signal can reach it. A few endings print no done line, or one more line: a SIGKILL of the CLI, or a signal that comes while Node is still starting the CLI, before its From 7db86c57b22ca7f4eb1d49aee8dd7b83c5532bab Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 09:55:18 -0700 Subject: [PATCH 16/62] test(oracle-gaps): hold the exit at a named point, and delete the wall-clock hold The overlap and the spawn stop 'after' case kept the first run alive with a wall-clock hold (HOLD_EXIT_MS): under load the first run can end before the second starts, so the overlap outcome depended on timing. The hold is now a named point: after the done line the process keeps its exit (and its output claim) until ORACLE_GAPS_TEST_HOLD_UNTIL names an existing file. The driver releases it once the second run has been refused, or once the 'after' stop has been sent. HOLD_EXIT_MS is deleted. The README documents the new hook. Co-authored-by: Isaac --- README.md | 5 ++-- .../gap-report-oracle.property.test.mjs | 27 ++++++++++++------- packages/oracles/oracle-gaps/index.mjs | 16 +++++++++-- 3 files changed, 35 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 2881da57..de7f4ed9 100644 --- a/README.md +++ b/README.md @@ -138,8 +138,9 @@ agent. `ORACLE_GAPS_TEST_PAUSE_AFTER_STARTED` (milliseconds) blocks the CLI for that long right after the started file is written, so a stop sent on seeing the file lands inside the pause. `ORACLE_GAPS_TEST_PAUSE_AT` names one point at which `ORACLE_GAPS_TEST_PAUSE_MS` (milliseconds) blocks the CLI: `takeover` (inside a stale-claim takeover, after the stale pid is read) and `mutex-create` (inside the takeover mutex's creation). `ORACLE_GAPS_TEST_STOP` names a file whose appearance makes the CLI take a stop as a SIGINT would. - `ORACLE_GAPS_TEST_HOLD_EXIT_MS` holds the run's exit after its done line, - and `ORACLE_GAPS_TEST_WARM_PROBE` makes the first config warm-up wait where a + `ORACLE_GAPS_TEST_HOLD_UNTIL` names a file: after its done line the run keeps + its exit, and its output claim, until the file exists, so a test can send a + stop or start a second run before the run ends. `ORACLE_GAPS_TEST_WARM_PROBE` makes the first config warm-up wait where a stop signal can reach it. A few endings print no done line, or one more line: a SIGKILL of the CLI, 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 7c98382e..8dc3edb2 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -708,7 +708,7 @@ const strays = (dir, before, running = false) => * * With `when` `after`, the run is not stopped while it runs: the witness * does not spin, the run's process holds its exit for 500 ms once it has - * printed its done line (`ORACLE_GAPS_TEST_HOLD_EXIT_MS`, a hook for this + * printed its done line (`ORACLE_GAPS_TEST_HOLD_UNTIL`, a hook for this * driver), and the driver sends the signal once that line is on stdout * (review of #46, F3). The run then ends as it completed, with exactly one * done line. With `warm`, the driver sends the signal while the run warms @@ -758,7 +758,10 @@ async function stoppedRun( ? { ORACLE_GAPS_TEST_PAUSE_AFTER_STARTED: `200` } : {}), ...(after - ? { ...cleanEnv(), ORACLE_GAPS_TEST_HOLD_EXIT_MS: `500` } + ? { + ...cleanEnv(), + ORACLE_GAPS_TEST_HOLD_UNTIL: join(pids, `after-release`), + } : warm ? { ...cleanEnv(), @@ -828,6 +831,8 @@ async function stoppedRun( await sleep(1) else if (atSpawn) await sleep(delay) if (!abort) child.kill(signal) + // The `after` stop is sent while the exit is held; the hold is released now. + if (after) writeFileSync(join(pids, `after-release`), ``) const ended = await Promise.race([exit, sleep(30_000).then(() => false)]) await sleep(1000) const alive = readdirSync(pids) @@ -961,17 +966,17 @@ async function overlappingRuns(dir, files, how) { writeFixture(dir, files) const before = new Set(filesUnder(dir)) const { args, out } = cliArgs(dir, files, how) - const start = (holdMs) => { + const start = (holdUntilFile) => { const child = spawn(process.execPath, args, { cwd: repo, - // A test-only hold (ORACLE_GAPS_TEST_HOLD_EXIT_MS, index.mjs): the first - // run keeps its output claim until the second has been refused, so the - // overlap does not depend on how fast the first run ends. + // The first run holds its exit (and its output claim) until the driver + // releases it after the second run has been refused: the overlap is + // deterministic (ORACLE_GAPS_TEST_HOLD_UNTIL, index.mjs). env: { ...cleanEnv(), - ...(holdMs === undefined + ...(holdUntilFile === undefined ? {} - : { ORACLE_GAPS_TEST_HOLD_EXIT_MS: String(holdMs) }), + : { ORACLE_GAPS_TEST_HOLD_UNTIL: holdUntilFile }), }, stdio: [`ignore`, `pipe`, `pipe`], }) @@ -991,7 +996,10 @@ async function overlappingRuns(dir, files, how) { }) return { got, status } } - const first = start(5000) + // The release file lives outside the package: a stray write there is judged. + const releaseDir = mkdtempSync(join(realpathSync(tmpdir()), `gap-release-`)) + const releaseFile = join(releaseDir, `overlap-release`) + const first = start(releaseFile) let firstEnded = false first.status.then(() => { firstEnded = true @@ -1013,6 +1021,7 @@ async function overlappingRuns(dir, files, how) { ) const second = start() const secondStatus = await second.status + writeFileSync(releaseFile, ``) const firstStatus = await first.status const ended = readRun( dir, diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index 99c34127..f1ee3015 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -332,10 +332,22 @@ function startLog(out) { } /** Flushes both streams, then exits with `code` (after a test's hold). */ +/** + * A test-only hold (ORACLE_GAPS_TEST_HOLD_UNTIL, a path): after its done line the + * process keeps its exit, and its output claim, until the file exists. A test + * releases it once the overlapping run or the stop it sent has been observed, so + * the outcome does not depend on wall-clock timing. Inert unless set. + */ +function holdUntil() { + const file = process.env.ORACLE_GAPS_TEST_HOLD_UNTIL + if (file !== undefined) while (!existsSync(file)) sleepMs(20) +} function exitWhenFlushed(code) { - const hold = Number(process.env.ORACLE_GAPS_TEST_HOLD_EXIT_MS ?? 0) process.stdout.write(``, () => - process.stderr.write(``, () => setTimeout(() => process.exit(code), hold)), + process.stderr.write(``, () => { + holdUntil() + process.exit(code) + }), ) } From e2a74ad61dce6aa22d63ebe5fe9940a0a30645fd Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 13:49:35 -0700 Subject: [PATCH 17/62] test(oracle-gaps): constructed histories for the stale-claim race and dead-pid recovery Two constructed histories gate their reach states: two starts race for a stale claim (exactly one claims, the other refuses), and a stale claim and mutex from a dead pid are taken over (the run claims). The race is paused inside the takeover mutex's creation (ORACLE_GAPS_TEST_PAUSE_AT). Placed in the e2e and Windows shards. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-model-oracle.mjs | 18 +++ .../gap-report-oracle.property.test.mjs | 140 ++++++++++++++++++ packages/oracles/scripts/e2e-shards.mjs | 6 + packages/oracles/scripts/pr-shards.mjs | 2 + 4 files changed, 166 insertions(+) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index 1f835806..c1251418 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -833,6 +833,23 @@ const drawn = fc.record({ // spawns (the spawn-delay law, review of #57). spawnSignal: fc.constantFrom(`SIGINT`, `SIGINT`, `SIGTERM`), spawnDelay: fc.integer({ min: 0, max: 150 }), + // A claim left by a dead pid, then the starts that meet it: two racing starts + // (`race`) or one start that must take over a stale claim and its mutex + // (`recovery`). Constructed histories set it (review of #57, the claim rules). + claimScenario: fc.constantFrom( + false, + false, + false, + false, + false, + false, + false, + false, + false, + false, + `race`, + `recovery`, + ), // The spawn stop waits for the CLI's started marker, then signals at once (the // deterministic witness, event-driven rather than timed). spawnOnStart: fc.constantFrom(false, false, false, true), @@ -2928,6 +2945,7 @@ function resolveHistory(history) { spawnStop: history.spawnStop === true, spawnSignal: history.spawnSignal ?? `SIGINT`, spawnDelay: history.spawnDelay ?? 0, + claimScenario: history.claimScenario ?? false, spawnOnStart: history.spawnOnStart === true, onlyRun: history.onlyRun === true, pragma: history.pragma === true, 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 8dc3edb2..af0b78c4 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -962,6 +962,58 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms)) * observation (the coordinator's decision of 2026-11-13 on F4: a second run * refuses, and the first's stream log stays its own). */ +/** + * Runs a claim scenario (review of #57, the claim rules): a run.pid left by a + * dead pid (and, for `recovery`, a takeover mutex left by a dead pid), then + * the starts that meet it. `race` starts two runs at once, each paused inside + * the takeover mutex's creation (ORACLE_GAPS_TEST_PAUSE_AT), and records each + * run as claimed, refused, or other. + */ +async function claimScenarioRuns(dir, files, how, scenario) { + writeFixture(dir, files) + const { args, out } = cliArgs(dir, files, { ...how, outName: `out-claim` }) + mkdirSync(out, { recursive: true }) + writeFileSync(join(out, `run.pid`), `999999\n`) + if (scenario === `recovery`) + writeFileSync(join(out, `run.pid.takeover`), `999998\n`) + const env = + scenario === `race` + ? { + ...cleanEnv(), + ORACLE_GAPS_TEST_PAUSE_AT: `mutex-create`, + ORACLE_GAPS_TEST_PAUSE_MS: `300`, + } + : cleanEnv() + const runOnce = () => + new Promise((resolvePromise) => { + const child = spawn(process.execPath, args, { + cwd: repo, + env, + stdio: [`ignore`, `pipe`, `pipe`], + }) + let stdout = `` + let stderr = `` + child.stdout.on(`data`, (chunk) => { + stdout += chunk + }) + child.stderr.on(`data`, (chunk) => { + stderr += chunk + }) + child.on(`close`, () => resolvePromise({ stdout, stderr })) + }) + const runs = + scenario === `race` + ? await Promise.all([runOnce(), runOnce()]) + : [await runOnce()] + const outcomeOf = (run) => + run.stdout.includes(`oracle-gaps: note log`) + ? `claimed` + : run.stderr.includes(`another run`) + ? `refused` + : `other` + return { scenario, outcomes: runs.map(outcomeOf).sort() } +} + async function overlappingRuns(dir, files, how) { writeFixture(dir, files) const before = new Set(filesUnder(dir)) @@ -1851,6 +1903,15 @@ async function driver(plan, observe) { : undefined const { replay, ...cli } = overlapping?.cli ?? runCli(dir, files, how) if (overlapping) observe(`overlap`, overlapping.overlap) + if (plan.claimScenario) { + const claim = await claimScenarioRuns(dir, files, how, plan.claimScenario) + observe(`claimScenario`, claim) + states.add( + claim.scenario === `race` + ? `two starts race for a stale claim` + : `a stale claim and mutex from a dead pid are taken over`, + ) + } // How many units were computed or reused says how the result was // produced, not what it is, so it is not observed. observe(`cli`, { ...cli, evidence: undefined }) @@ -2450,6 +2511,19 @@ function check(plan, observations, expected) { // anything (F4, the coordinator's decision of 2026-11-13): the refusal // names the directory, is one block with its fix, and its stdout is its // done line alone. The first run's own laws are judged on `cli`. + const claim = observations.find( + (o) => o.checkpoint === `claimScenario`, + )?.value + if (claim !== undefined) { + const owed = + claim.scenario === `race` ? [`claimed`, `refused`] : [`claimed`] + if (JSON.stringify(claim.outcomes) !== JSON.stringify(owed)) + return violation( + `claimScenario`, + `a ${claim.scenario} gave ${JSON.stringify(claim.outcomes)}, owed ${JSON.stringify(owed)}`, + `ownership`, + ) + } const overlap = observations.find((o) => o.checkpoint === `overlap`)?.value if (overlap !== undefined) { if (overlap.exit !== 2) @@ -3477,6 +3551,8 @@ const staticStates = [ `owned through bind`, ] const required = [ + `two starts race for a stale claim`, + `a stale claim and mutex from a dead pid are taken over`, `a stop as the CLI starts`, `a stream log that cannot be written`, `two runs on one output directory`, @@ -3653,6 +3729,8 @@ const faults = [ // history: they are not witnessed by "every outcome class" (a named history // of its own must enter them, or registration fails). const ownHistoryStates = [ + `two starts race for a stale claim`, + `a stale claim and mutex from a dead pid are taken over`, `a stop as the CLI starts`, `a stream log that cannot be written`, `two runs on one output directory`, @@ -3960,6 +4038,68 @@ oracleProperty({ overlap: true, }), }, + { + // A second run on the first's output directory while the first is + // live refuses (F4, the coordinator's decision of 2026-11-13): the + // first run's stream log still equals its own stderr, line for line, + // and the refusal reports no directory it does not own. + name: `two starts race for a stale claim`, + enters: [`two starts race for a stale claim`], + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], + wholeFile: `none`, + witness: false, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, + steps: null, + ordinary: false, + budget: `two`, + outMode: `explicit`, + logBlocked: false, + overlap: false, + claimScenario: `race`, + }), + }, + { + // A second run on the first's output directory while the first is + // live refuses (F4, the coordinator's decision of 2026-11-13): the + // first run's stream log still equals its own stderr, line for line, + // and the refusal reports no directory it does not own. + name: `a stale claim and mutex from a dead pid are taken over`, + enters: [`a stale claim and mutex from a dead pid are taken over`], + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], + wholeFile: `none`, + witness: false, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, + steps: null, + ordinary: false, + budget: `two`, + outMode: `explicit`, + logBlocked: false, + overlap: false, + claimScenario: `recovery`, + }), + }, { // The budget witness checked through the daemon twice with nothing // changed between: the second check reuses the confirmations the diff --git a/packages/oracles/scripts/e2e-shards.mjs b/packages/oracles/scripts/e2e-shards.mjs index 27191c5d..b6fc53b8 100644 --- a/packages/oracles/scripts/e2e-shards.mjs +++ b/packages/oracles/scripts/e2e-shards.mjs @@ -78,6 +78,8 @@ export const shards = { ], // 522 s in the measured run, about 221 s idle. 'e2e-2': [ + `fixed seed 20261105: two starts race for a stale claim`, + `fixed seed 20261105: a stale claim and mutex from a dead pid are taken over`, `fixed seed 20261105: a stop as the CLI starts`, `fixed seed 20261105: a declaration fault: setupThrows`, `fixed seed 20261105: a package with no config`, @@ -111,6 +113,8 @@ export const shards = { ], // 522 s in the measured run, about 221 s idle. 'e2e-3': [ + `determinism: constructed history: two starts race for a stale claim`, + `determinism: constructed history: a stale claim and mutex from a dead pid are taken over`, `determinism: constructed history: a stop as the CLI starts`, `random seed: a stop with the default output directory`, `random seed: a daemon check with the default output directory`, @@ -146,6 +150,8 @@ export const shards = { ], // 522 s in the measured run, about 221 s idle. 'e2e-4': [ + `random seed: two starts race for a stale claim`, + `random seed: a stale claim and mutex from a dead pid are taken over`, `random seed: a stop as the CLI starts`, `fixed seed 20261105: a .ts config in a package with no module type that calls require`, `fixed seed 20261105: a config that --config names`, diff --git a/packages/oracles/scripts/pr-shards.mjs b/packages/oracles/scripts/pr-shards.mjs index bb476807..9f639f75 100644 --- a/packages/oracles/scripts/pr-shards.mjs +++ b/packages/oracles/scripts/pr-shards.mjs @@ -524,6 +524,8 @@ export const partitions = { "test.projects in a parent's config", ]), 2: anyOf([ + 'two starts race for a stale claim', + 'a stale claim and mutex from a dead pid are taken over', 'a stop with the default output directory', 'a daemon check with the default output directory', 'a .ts config in a package with no module type that calls require', From f3d8d771c715d898a7e59d5291735395643bbbaa Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 13:52:34 -0700 Subject: [PATCH 18/62] test(oracle-gaps): claimScenario last in the draw order; claim states after the declaration claimScenario is appended after spawnOnStart, so the generator draws every earlier field as before (fingerprint canary: 0 of 16,500 pre-existing values differ against 7db86c5 over 300 histories at seed 20261105). The claim scenario's reach states are added after the states set is declared (the first VM run failed with a ReferenceError there). Co-authored-by: Isaac --- .../oracle-gaps/gap-report-model-oracle.mjs | 2 +- .../gap-report-oracle.property.test.mjs | 16 ++++++++-------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index c1251418..c2d7fa96 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -833,6 +833,7 @@ const drawn = fc.record({ // spawns (the spawn-delay law, review of #57). spawnSignal: fc.constantFrom(`SIGINT`, `SIGINT`, `SIGTERM`), spawnDelay: fc.integer({ min: 0, max: 150 }), + spawnOnStart: fc.constantFrom(false, false, false, true), // A claim left by a dead pid, then the starts that meet it: two racing starts // (`race`) or one start that must take over a stale claim and its mutex // (`recovery`). Constructed histories set it (review of #57, the claim rules). @@ -852,7 +853,6 @@ const drawn = fc.record({ ), // The spawn stop waits for the CLI's started marker, then signals at once (the // deterministic witness, event-driven rather than timed). - spawnOnStart: fc.constantFrom(false, false, false, true), }) // The edit sequence over the witness module, the one list of steps that a diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index af0b78c4..8b5d63df 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1903,6 +1903,14 @@ async function driver(plan, observe) { : undefined const { replay, ...cli } = overlapping?.cli ?? runCli(dir, files, how) if (overlapping) observe(`overlap`, overlapping.overlap) + // How many units were computed or reused says how the result was + // produced, not what it is, so it is not observed. + observe(`cli`, { ...cli, evidence: undefined }) + // A failing owner's replay, run as the author would run it (law 3). + if (plan.fault === `brokenOwner`) + observe(`replay`, { command: replay, ran: replayed(dir, replay) }) + // Reach comes from what the CLI reported, mapped onto the plan. + const states = new Set() if (plan.claimScenario) { const claim = await claimScenarioRuns(dir, files, how, plan.claimScenario) observe(`claimScenario`, claim) @@ -1912,14 +1920,6 @@ async function driver(plan, observe) { : `a stale claim and mutex from a dead pid are taken over`, ) } - // How many units were computed or reused says how the result was - // produced, not what it is, so it is not observed. - observe(`cli`, { ...cli, evidence: undefined }) - // A failing owner's replay, run as the author would run it (law 3). - if (plan.fault === `brokenOwner`) - observe(`replay`, { command: replay, ran: replayed(dir, replay) }) - // Reach comes from what the CLI reported, mapped onto the plan. - const states = new Set() if (plan.outMode === `default`) states.add(`a run with the default output directory`) if (plan.logBlocked && cli.exit === 2) From 52c2740328fe0455399b67edfb7ece1224f97d79 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 13:57:15 -0700 Subject: [PATCH 19/62] test(oracle-gaps): sequence the stale-claim race with a held run, not a timed pause ORACLE_GAPS_TEST_PAUSE_MS is removed. A test hook now holds the CLI at one named point (ORACLE_GAPS_TEST_PAUSE_AT): it writes ORACLE_GAPS_TEST_PAUSE_MARKER when it reaches the point, then waits for ORACLE_GAPS_TEST_PAUSE_UNTIL. The race driver holds run A at the takeover mutex's creation, starts run B once A is held, and releases A only after B has claimed; A must refuse. Register: test hooks; no wall-clock ordering. Co-authored-by: Isaac --- README.md | 2 +- .../gap-report-oracle.property.test.mjs | 78 ++++++++++++------- packages/oracles/oracle-gaps/index.mjs | 19 +++-- 3 files changed, 61 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index de7f4ed9..3b371fce 100644 --- a/README.md +++ b/README.md @@ -136,7 +136,7 @@ agent. set; a hook may pause at one named point and never changes an outcome. `ORACLE_GAPS_TEST_STARTED` names a file that the CLI writes as its first project statement, before any project module loads, so a test can tell a stop that came before the CLI started from one that came during its loads. `ORACLE_GAPS_TEST_PAUSE_AFTER_STARTED` (milliseconds) blocks the CLI for that long right after the started file is written, so a stop sent on seeing the file lands inside the pause. - `ORACLE_GAPS_TEST_PAUSE_AT` names one point at which `ORACLE_GAPS_TEST_PAUSE_MS` (milliseconds) blocks the CLI: `takeover` (inside a stale-claim takeover, after the stale pid is read) and `mutex-create` (inside the takeover mutex's creation). + `ORACLE_GAPS_TEST_PAUSE_AT` names one point at which the CLI writes the file `ORACLE_GAPS_TEST_PAUSE_MARKER` (when set) and waits until the file `ORACLE_GAPS_TEST_PAUSE_UNTIL` exists: `takeover` (inside a stale-claim takeover, after the stale pid is read) and `mutex-create` (inside the takeover mutex's creation). `ORACLE_GAPS_TEST_STOP` names a file whose appearance makes the CLI take a stop as a SIGINT would. `ORACLE_GAPS_TEST_HOLD_UNTIL` names a file: after its done line the run keeps its exit, and its output claim, until the file exists, so a test can send a diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 8b5d63df..8350064e 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -976,42 +976,62 @@ async function claimScenarioRuns(dir, files, how, scenario) { writeFileSync(join(out, `run.pid`), `999999\n`) if (scenario === `recovery`) writeFileSync(join(out, `run.pid.takeover`), `999998\n`) - const env = - scenario === `race` - ? { - ...cleanEnv(), - ORACLE_GAPS_TEST_PAUSE_AT: `mutex-create`, - ORACLE_GAPS_TEST_PAUSE_MS: `300`, - } - : cleanEnv() - const runOnce = () => - new Promise((resolvePromise) => { - const child = spawn(process.execPath, args, { - cwd: repo, - env, - stdio: [`ignore`, `pipe`, `pipe`], - }) - let stdout = `` - let stderr = `` - child.stdout.on(`data`, (chunk) => { - stdout += chunk - }) - child.stderr.on(`data`, (chunk) => { - stderr += chunk - }) - child.on(`close`, () => resolvePromise({ stdout, stderr })) + // A run, with its streams collected as they come. + const startRun = (env) => { + const got = { stdout: ``, stderr: `` } + const child = spawn(process.execPath, args, { + cwd: repo, + env, + stdio: [`ignore`, `pipe`, `pipe`], + }) + child.stdout.on(`data`, (chunk) => { + got.stdout += chunk + }) + child.stderr.on(`data`, (chunk) => { + got.stderr += chunk }) - const runs = - scenario === `race` - ? await Promise.all([runOnce(), runOnce()]) - : [await runOnce()] + const done = new Promise((resolvePromise) => { + child.on(`close`, () => resolvePromise(got)) + }) + return { got, done } + } const outcomeOf = (run) => run.stdout.includes(`oracle-gaps: note log`) ? `claimed` : run.stderr.includes(`another run`) ? `refused` : `other` - return { scenario, outcomes: runs.map(outcomeOf).sort() } + if (scenario === `recovery`) { + const run = startRun(cleanEnv()) + return { scenario, outcomes: [outcomeOf(await run.done)] } + } + // race: A is held inside the takeover mutex's creation; B starts once A is + // held and claims; A is released only after B has claimed, so A must refuse. + const marker = join(dir, `a-at-mutex-create`) + const release = join(dir, `release-a`) + const a = startRun({ + ...cleanEnv(), + ORACLE_GAPS_TEST_PAUSE_AT: `mutex-create`, + ORACLE_GAPS_TEST_PAUSE_MARKER: marker, + ORACLE_GAPS_TEST_PAUSE_UNTIL: release, + }) + for (let waited = 0; !existsSync(marker); waited += 1) { + if (waited > 6000) throw new Error(`run A never reached the takeover mutex`) + await sleep(10) + } + const b = startRun(cleanEnv()) + for ( + let waited = 0; + !b.got.stdout.includes(`oracle-gaps: note log`); + waited += 1 + ) { + if (waited > 12000) throw new Error(`run B never claimed the directory`) + await sleep(10) + } + writeFileSync(release, ``) + const runA = await a.done + const runB = await b.done + return { scenario, outcomes: [outcomeOf(runA), outcomeOf(runB)].sort() } } async function overlappingRuns(dir, files, how) { diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index f1ee3015..44af2059 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -299,15 +299,18 @@ function takeMutex(mutex) { rmSync(temp, { force: true }) } } -/** A test-only pause (ORACLE_GAPS_TEST_PAUSE_AT, inert unless set), see README. */ +/** + * A test-only hold at one named point (ORACLE_GAPS_TEST_PAUSE_AT): the process + * writes its marker (ORACLE_GAPS_TEST_PAUSE_MARKER) when it reaches the point, + * then waits until the file ORACLE_GAPS_TEST_PAUSE_UNTIL exists. A test sequences + * other runs against it and releases it. Inert unless set (register: test hooks). + */ function testPause(point) { - if (process.env.ORACLE_GAPS_TEST_PAUSE_AT === point) - Atomics.wait( - new Int32Array(new SharedArrayBuffer(4)), - 0, - 0, - Number(process.env.ORACLE_GAPS_TEST_PAUSE_MS ?? 0), - ) + if (process.env.ORACLE_GAPS_TEST_PAUSE_AT !== point) return + const marker = process.env.ORACLE_GAPS_TEST_PAUSE_MARKER + if (marker !== undefined) writeFileSync(marker, ``) + const until = process.env.ORACLE_GAPS_TEST_PAUSE_UNTIL + if (until !== undefined) while (!existsSync(until)) sleepMs(20) } function sleepMs(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms) From 70e294cd7960ef93379a812819f9044fee76fdfc Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 14:48:05 -0700 Subject: [PATCH 20/62] test(oracle-gaps): generated histories never draw a claim scenario The generator drew claimScenario race or recovery in about 2 of 12 histories, so fixed-seed histories built from generated records ran the claim driver. The driver's out-claim writes, and a generated default output directory, broke the shard units (a TypeError from mkdirSync on an undefined out directory, and the declaration-fault units). The field is now a constant in the drawn record, which draws nothing. The histories take-back reads a constructed claim scenario as that constant, because fast-check refuses any value the arbitrary cannot produce. The claim driver runs only in the two constructed histories. The claim driver's fixture is the one runCli already wrote, and its out-claim directory is an owned write. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-model-oracle.mjs | 41 ++++++++++--------- .../gap-report-oracle.property.test.mjs | 3 +- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index c2d7fa96..3e250115 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -834,23 +834,10 @@ const drawn = fc.record({ spawnSignal: fc.constantFrom(`SIGINT`, `SIGINT`, `SIGTERM`), spawnDelay: fc.integer({ min: 0, max: 150 }), spawnOnStart: fc.constantFrom(false, false, false, true), - // A claim left by a dead pid, then the starts that meet it: two racing starts - // (`race`) or one start that must take over a stale claim and its mutex - // (`recovery`). Constructed histories set it (review of #57, the claim rules). - claimScenario: fc.constantFrom( - false, - false, - false, - false, - false, - false, - false, - false, - false, - false, - `race`, - `recovery`, - ), + // A claim scenario (`race` or `recovery`, review of #57) is constructed only. + // A constant draws nothing, so generated histories never run the claim driver, + // and `histories` below takes a constructed scenario back as this constant. + claimScenario: fc.constant(false), // The spawn stop waits for the CLI's started marker, then signals at once (the // deterministic witness, event-driven rather than timed). }) @@ -892,15 +879,24 @@ const keepsSteps = (history) => { // `budgetSteps` (the review of the gap CLI's runtime fixes, 2026-11-12, // P1-a: the budget witness only in its own histories). The map is its own // inverse on the histories it keeps, so fast-check takes every one of them -// back and shrinks it. +// back and shrinks it. A constructed claim scenario (`claimScenario`) is not a +// value `drawn` can produce, so its take-back reads it as the drawn constant +// `false`. A shrink of a claim counterexample is therefore claim-free: it never +// runs the claim driver, so it cannot reproduce a claim violation, and the +// constructed history stays the counterexample for that law (a stated limit: +// the claim field is not shrunk). const histories = drawn.map( (history) => (keepsSteps(history) ? history : { ...history, steps: null }), (value) => { const history = - /** @type {{ witness: unknown, steps: unknown[] | null }} */ (value) + /** @type {{ witness: unknown, steps: unknown[] | null, claimScenario: unknown }} */ ( + value + ) if (!keepsSteps(history)) throw new Error(`a history with the witness module takes no steps`) - return value + return history.claimScenario === false + ? value + : { ...history, claimScenario: false } }, ) @@ -2945,6 +2941,11 @@ function resolveHistory(history) { spawnStop: history.spawnStop === true, spawnSignal: history.spawnSignal ?? `SIGINT`, spawnDelay: history.spawnDelay ?? 0, + // A claim left by a dead pid, then the starts that meet it: two racing + // starts (`race`) or one start that must take over a stale claim and its + // mutex (`recovery`). Only constructed histories set it, so generated + // histories keep their fixed-seed draws and run no claim driver (P4, the + // coordinator's decision on the claim rules). claimScenario: history.claimScenario ?? false, spawnOnStart: history.spawnOnStart === true, onlyRun: history.onlyRun === true, 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 8350064e..988a6908 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -970,7 +970,6 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms)) * run as claimed, refused, or other. */ async function claimScenarioRuns(dir, files, how, scenario) { - writeFixture(dir, files) const { args, out } = cliArgs(dir, files, { ...how, outName: `out-claim` }) mkdirSync(out, { recursive: true }) writeFileSync(join(out, `run.pid`), `999999\n`) @@ -1133,7 +1132,7 @@ async function overlappingRuns(dir, files, how) { // (maintainer decision, 2026-11-11: the gap check's working files stay out // of the repository), so a package, and a workspace dependency in it, keeps // nothing of a run. -const OWN_WRITES = [`out`, `out-daemon`, `out-stop`, `out-only`] +const OWN_WRITES = [`out`, `out-daemon`, `out-stop`, `out-only`, `out-claim`] /** Runs the CLI several times at once on one state of the fixture. */ async function runClisAtOnce(dir, files, hows) { From 8aa7c10187449971acac6fff42c1099111446f94 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 14:54:04 -0700 Subject: [PATCH 21/62] test(oracle-gaps): a claim race that ends before the mutex is an outcome The race driver waited for run A to reach the takeover mutex and threw when A never did. A CLI that refuses a stale claim before the mutex (the mutant in the claim evidence) then failed with a driver error, not with the law. The driver now records a run that ends first as its outcome, and waits for B's note or B's end, so the race is judged by the claim law: a race gave [refused, refused], owed [claimed, refused]. The correct path is unchanged: A is held at the mutex, B claims, and A is released only while B still holds the directory. Co-authored-by: Isaac --- .../gap-report-oracle.property.test.mjs | 19 +++++++++++++++---- 1 file changed, 15 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 988a6908..a9fe6180 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1006,6 +1006,9 @@ async function claimScenarioRuns(dir, files, how, scenario) { } // race: A is held inside the takeover mutex's creation; B starts once A is // held and claims; A is released only after B has claimed, so A must refuse. + // A run that ends before the mutex (a refusal) is an outcome too: the driver + // records it and does not wait for the pause, so a wrong CLI is judged by the + // law rather than by a driver error. const marker = join(dir, `a-at-mutex-create`) const release = join(dir, `release-a`) const a = startRun({ @@ -1014,17 +1017,25 @@ async function claimScenarioRuns(dir, files, how, scenario) { ORACLE_GAPS_TEST_PAUSE_MARKER: marker, ORACLE_GAPS_TEST_PAUSE_UNTIL: release, }) - for (let waited = 0; !existsSync(marker); waited += 1) { - if (waited > 6000) throw new Error(`run A never reached the takeover mutex`) + let aEnded = false + a.done.then(() => { + aEnded = true + }) + for (let waited = 0; !existsSync(marker) && !aEnded; waited += 1) { + if (waited > 6000) throw new Error(`run A neither paused nor ended`) await sleep(10) } const b = startRun(cleanEnv()) + let bEnded = false + b.done.then(() => { + bEnded = true + }) for ( let waited = 0; - !b.got.stdout.includes(`oracle-gaps: note log`); + !b.got.stdout.includes(`oracle-gaps: note log`) && !bEnded; waited += 1 ) { - if (waited > 12000) throw new Error(`run B never claimed the directory`) + if (waited > 12000) throw new Error(`run B neither claimed nor ended`) await sleep(10) } writeFileSync(release, ``) From 76ce6a7d25e7ce051dd033cffd70e6d8b4893d4f Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 14:56:17 -0700 Subject: [PATCH 22/62] ci(oracles): place the claim histories in fixed-seed shard 1 The two constructed claim histories ran in the rest shard, which took over 9 minutes on the pool. Shard 1 has the lightest measured time, and the two histories add about 22 s to it. The shard partition check still splits every test exactly. Co-authored-by: Isaac --- packages/oracles/scripts/pr-shards.mjs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/packages/oracles/scripts/pr-shards.mjs b/packages/oracles/scripts/pr-shards.mjs index 9f639f75..d1207211 100644 --- a/packages/oracles/scripts/pr-shards.mjs +++ b/packages/oracles/scripts/pr-shards.mjs @@ -295,11 +295,14 @@ export const partitions = { // select exactly these. previously: `fixed seed`, shards: { - // 261 s, 25 s, and a small unit. + // 261 s, 25 s, and a small unit, and the two constructed claim histories + // (about 22 s together, measured on the pool). 1: anyOf([ 'an edit sequence over the witness module', 'a stale authored mutant and a reformat', 'a failing owner under a config that --config names', + 'two starts race for a stale claim', + 'a stale claim and mutex from a dead pid are taken over', ]), // 134 s, 101 s, 27 s, and 15 s. 2: anyOf([ From 5aaa3a1d834c7092b1a48c6346d2c431b13b27dd Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 14:58:11 -0700 Subject: [PATCH 23/62] test(oracle-gaps): append the claim constructions, so existing seeds keep their histories A constructed history samples its generated base with seed + index. The two claim histories sat in the middle of the constructed list, so every later history (the declaration faults among them) sampled a different base than on the green commit, and brokenOwner, outsideSource and setupThrows failed. The claim histories now come last, so each existing history keeps its index and its base. Also gives each claim history its own comment (the copied F4 comment described the overlap). Co-authored-by: Isaac --- .../gap-report-oracle.property.test.mjs | 121 +++++++++--------- 1 file changed, 59 insertions(+), 62 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 a9fe6180..26cc5629 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -4068,68 +4068,6 @@ oracleProperty({ overlap: true, }), }, - { - // A second run on the first's output directory while the first is - // live refuses (F4, the coordinator's decision of 2026-11-13): the - // first run's stream log still equals its own stderr, line for line, - // and the refusal reports no directory it does not own. - name: `two starts race for a stale claim`, - enters: [`two starts race for a stale claim`], - build: (generated) => ({ - ...generated, - functions: [[{ kind: `push`, quote: `'` }]], - containers: [], - overloads: [], - owners: [`a`], - library: [], - libraryOwners: [], - runes: [], - wholeFile: `none`, - witness: false, - tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], - authored: null, - fault: `none`, - stability: `none`, - steps: null, - ordinary: false, - budget: `two`, - outMode: `explicit`, - logBlocked: false, - overlap: false, - claimScenario: `race`, - }), - }, - { - // A second run on the first's output directory while the first is - // live refuses (F4, the coordinator's decision of 2026-11-13): the - // first run's stream log still equals its own stderr, line for line, - // and the refusal reports no directory it does not own. - name: `a stale claim and mutex from a dead pid are taken over`, - enters: [`a stale claim and mutex from a dead pid are taken over`], - build: (generated) => ({ - ...generated, - functions: [[{ kind: `push`, quote: `'` }]], - containers: [], - overloads: [], - owners: [`a`], - library: [], - libraryOwners: [], - runes: [], - wholeFile: `none`, - witness: false, - tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], - authored: null, - fault: `none`, - stability: `none`, - steps: null, - ordinary: false, - budget: `two`, - outMode: `explicit`, - logBlocked: false, - overlap: false, - claimScenario: `recovery`, - }), - }, { // The budget witness checked through the daemon twice with nothing // changed between: the second check reuses the confirmations the @@ -4774,6 +4712,65 @@ oracleProperty({ steps: [`lazy`], }), }, + { + // Two starts meet a stale claim (review of #57, the claim rules): both + // are paused in the takeover mutex, and the race must end claimed and + // refused, one run each. + name: `two starts race for a stale claim`, + enters: [`two starts race for a stale claim`], + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], + wholeFile: `none`, + witness: false, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, + steps: null, + ordinary: false, + budget: `two`, + outMode: `explicit`, + logBlocked: false, + overlap: false, + claimScenario: `race`, + }), + }, + { + // A start meets a claim and a takeover mutex left by dead pids: it takes + // both over and claims the output directory. + name: `a stale claim and mutex from a dead pid are taken over`, + enters: [`a stale claim and mutex from a dead pid are taken over`], + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], + wholeFile: `none`, + witness: false, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, + steps: null, + ordinary: false, + budget: `two`, + outMode: `explicit`, + logBlocked: false, + overlap: false, + claimScenario: `recovery`, + }), + }, ]), }, resolve: resolveHistory, From 2293582d84be9f04794076e1f6ddfe1191e08a2b Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 16:02:44 -0700 Subject: [PATCH 24/62] fix(oracle-gaps): the stream log's note names it in forward slashes on win32 The note line printed join(out, stream.log), which on win32 has backslashes, so the greppable-stream law failed on Windows. The register's Windows-paths entry (2026-11-13) requires forward slashes for report paths. RED: the Windows fixed-seed end-to-end jobs on 5aaa3a1 (CI run 43646266358, jobs 132604647764, 132604647986, 132604647967) failed "the run's first lines are [oracle-gaps: note log \out\stream.log, ...], not ... out/stream.log". The note is posix(path) (paths.mjs), which is the identity on POSIX. The expected note converts backslashes only on win32, as #79 does (678b643, 9626f00). Co-authored-by: Isaac --- .../oracle-gaps/gap-report-oracle.property.test.mjs | 12 ++++++++++-- packages/oracles/oracle-gaps/index.mjs | 5 ++++- 2 files changed, 14 insertions(+), 3 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 26cc5629..2fb3f309 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -2989,8 +2989,16 @@ function streamBreach(checkpoint, run, expected, plan) { return undefined } -/** The line that names a run's stream log. */ -const logNoteOf = (run) => `oracle-gaps: note log ${run.outDir}/stream.log` +/** + * The line that names a run's stream log. On win32 the note names the log in + * forward slashes (the Windows paths rule, register 2026-11-13); POSIX paths + * are used unchanged. + */ +const logNoteOf = (run) => { + const outDir = + process.platform === `win32` ? run.outDir.replaceAll(`\\`, `/`) : run.outDir + return `oracle-gaps: note log ${outDir}/stream.log` +} /** * What law 15 judges of every run, on both streams, whatever its outcome: diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index 44af2059..ecf07418 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -139,6 +139,7 @@ import { import { constants } from 'node:os' import { join } from 'node:path' import { pathToFileURL } from 'node:url' +import { posix } from './paths.mjs' let early const keepEarly = (signal) => { @@ -329,7 +330,9 @@ function startLog(out) { throw cannotWrite(path, error) } streamLog = path - const note = `oracle-gaps: note log ${path}\n` + // The log is named in forward slashes on win32 (the Windows paths rule); POSIX + // paths are unchanged. + const note = `oracle-gaps: note log ${posix(path)}\n` process.stdout.write(note) writeStream(note) } From 24412db3852d9d7cd6c9d1c5294c4521d44a10c3 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 16:41:16 -0700 Subject: [PATCH 25/62] test(oracle-gaps): name the forward-slash spelling of a scratch path on win32 After the note line used forward slashes, the Windows fixed-seed jobs still failed the greppable-stream law: the note named the package as D:/a/.../.scratch-xxx where the driver expected , because the driver named only the native spelling of each scratch path. RED: the Windows fixed-seed end-to-end jobs on 2293582 (CI run 43651225289) fail with "the run's first lines are [oracle-gaps: note log D:/a/oracles/.../.scratch-xxx/out/stream.log, ...], not ... /out/stream.log". On win32 each scratch path is also named in forward slashes; POSIX has one spelling and is unchanged. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-oracle.property.test.mjs | 12 ++++++++---- 1 file changed, 8 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 2fb3f309..08c7745c 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1192,10 +1192,14 @@ function namedScratch(text, names) { const longestFirst = names .filter(([path]) => path !== undefined) .sort(([a], [b]) => b.length - a.length) - for (const [path, name] of longestFirst) - named = named - .replaceAll(pathToFileURL(path).href, name) - .replaceAll(path, name) + for (const [path, name] of longestFirst) { + // On win32 the CLI names a path in forward slashes (the Windows paths + // rule), so the forward-slash spelling is named too; POSIX has one spelling. + const spellings = + process.platform === `win32` ? [path, path.replaceAll(`\\`, `/`)] : [path] + named = named.replaceAll(pathToFileURL(path).href, name) + for (const spelling of spellings) named = named.replaceAll(spelling, name) + } return named .replaceAll(/\.oracle-gaps-\d+/g, `.oracle-gaps-`) .replaceAll(/session-\d+/g, `session-`) From 0738650d623dc4514a1493ba20fa43674cde9cba Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 19:43:25 -0700 Subject: [PATCH 26/62] fix(oracle-gaps): stale claims refuse; no takeover The maintainer's decision, "Stale claims refuse; no takeover": a run.pid that names no running process, or that cannot be read, refuses the second run, like a live claim. Exit 2, one done line, and a fix line that names the claim. Nothing is taken over, so the double claim and the hangs of the takeover mutex are gone by construction. - Removed: the takeover mutex, its waits, the unreadable-claim loop, and the mutex-create pause point. The pause point takeover is gone too; the note point is the one new pause point. - Waits in the CLI are bounded (testPause, holdUntil): a wait past 60 s fails the run loudly. - The stream log's writes go through appendLog, which turns a failure into the refusal cannotWrite. The uncaught-exception handlers are registered before the supervisor runs, so a supervisor error ends the run through endWith. A log that cannot take the done line keeps both streams' done line and the decided exit code. - The supervisor's variable is ORACLE_GAPS_INTERNAL_SUPERVISED. The child kills its group only when it leads that group (checked with ps). - The test stop watcher is one function for both paths; the claim set is one variable. - Claim histories: race (two starts), stale (one start), and empty (one start). Each refusal names its cause and the claim, and leaves run.pid and the directory as they were. Co-authored-by: Isaac --- README.md | 3 +- .../gap-report-oracle.property.test.mjs | 164 +++++++------ packages/oracles/oracle-gaps/index.mjs | 228 +++++++++--------- packages/oracles/scripts/e2e-shards.mjs | 9 +- packages/oracles/scripts/pr-shards.mjs | 6 +- 5 files changed, 218 insertions(+), 192 deletions(-) diff --git a/README.md b/README.md index 3b371fce..135c790b 100644 --- a/README.md +++ b/README.md @@ -136,8 +136,9 @@ agent. set; a hook may pause at one named point and never changes an outcome. `ORACLE_GAPS_TEST_STARTED` names a file that the CLI writes as its first project statement, before any project module loads, so a test can tell a stop that came before the CLI started from one that came during its loads. `ORACLE_GAPS_TEST_PAUSE_AFTER_STARTED` (milliseconds) blocks the CLI for that long right after the started file is written, so a stop sent on seeing the file lands inside the pause. - `ORACLE_GAPS_TEST_PAUSE_AT` names one point at which the CLI writes the file `ORACLE_GAPS_TEST_PAUSE_MARKER` (when set) and waits until the file `ORACLE_GAPS_TEST_PAUSE_UNTIL` exists: `takeover` (inside a stale-claim takeover, after the stale pid is read) and `mutex-create` (inside the takeover mutex's creation). + `ORACLE_GAPS_TEST_PAUSE_AT` names one point at which the CLI writes the file `ORACLE_GAPS_TEST_PAUSE_MARKER` (when set) and waits until the file `ORACLE_GAPS_TEST_PAUSE_UNTIL` exists: `note` (after the note line is written, before the check starts). `ORACLE_GAPS_TEST_STOP` names a file whose appearance makes the CLI take a stop as a SIGINT would. + `ORACLE_GAPS_INTERNAL_SUPERVISED` is set by a supervisor for the child it starts (its own pid). It is internal, not a user setting: the child kills its own process group only when the supervisor that started it has gone and the child leads that group. `ORACLE_GAPS_TEST_HOLD_UNTIL` names a file: after its done line the run keeps its exit, and its output claim, until the file exists, so a test can send a stop or start a second run before the run ends. `ORACLE_GAPS_TEST_WARM_PROBE` makes the first config warm-up wait where a diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 08c7745c..d4e86ad5 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -963,24 +963,24 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms)) * refuses, and the first's stream log stays its own). */ /** - * Runs a claim scenario (review of #57, the claim rules): a run.pid left by a - * dead pid (and, for `recovery`, a takeover mutex left by a dead pid), then - * the starts that meet it. `race` starts two runs at once, each paused inside - * the takeover mutex's creation (ORACLE_GAPS_TEST_PAUSE_AT), and records each - * run as claimed, refused, or other. + * Runs a claim scenario (the maintainer's decision, "Stale claims refuse; no + * takeover"): a run.pid that names a dead pid (`stale`), an empty run.pid + * (`empty`), or two starts at once on a dead pid's claim (`race`). Every start + * refuses and names its cause and its claim, writes no note and no log, and + * leaves run.pid as it was. A start that never ends is killed after 30 s, and + * its outcome is other. */ async function claimScenarioRuns(dir, files, how, scenario) { const { args, out } = cliArgs(dir, files, { ...how, outName: `out-claim` }) mkdirSync(out, { recursive: true }) - writeFileSync(join(out, `run.pid`), `999999\n`) - if (scenario === `recovery`) - writeFileSync(join(out, `run.pid.takeover`), `999998\n`) - // A run, with its streams collected as they come. - const startRun = (env) => { + const claim = join(out, `run.pid`) + const written = scenario === `empty` ? `` : `999999\n` + writeFileSync(claim, written) + const startRun = () => { const got = { stdout: ``, stderr: `` } const child = spawn(process.execPath, args, { cwd: repo, - env, + env: cleanEnv(), stdio: [`ignore`, `pipe`, `pipe`], }) child.stdout.on(`data`, (chunk) => { @@ -989,59 +989,34 @@ async function claimScenarioRuns(dir, files, how, scenario) { child.stderr.on(`data`, (chunk) => { got.stderr += chunk }) - const done = new Promise((resolvePromise) => { - child.on(`close`, () => resolvePromise(got)) + const timer = setTimeout(() => child.kill(`SIGKILL`), 30_000) + return new Promise((resolvePromise) => { + child.on(`close`, (code) => { + clearTimeout(timer) + resolvePromise({ ...got, code }) + }) }) - return { got, done } } - const outcomeOf = (run) => - run.stdout.includes(`oracle-gaps: note log`) - ? `claimed` - : run.stderr.includes(`another run`) - ? `refused` - : `other` - if (scenario === `recovery`) { - const run = startRun(cleanEnv()) - return { scenario, outcomes: [outcomeOf(await run.done)] } - } - // race: A is held inside the takeover mutex's creation; B starts once A is - // held and claims; A is released only after B has claimed, so A must refuse. - // A run that ends before the mutex (a refusal) is an outcome too: the driver - // records it and does not wait for the pause, so a wrong CLI is judged by the - // law rather than by a driver error. - const marker = join(dir, `a-at-mutex-create`) - const release = join(dir, `release-a`) - const a = startRun({ - ...cleanEnv(), - ORACLE_GAPS_TEST_PAUSE_AT: `mutex-create`, - ORACLE_GAPS_TEST_PAUSE_MARKER: marker, - ORACLE_GAPS_TEST_PAUSE_UNTIL: release, - }) - let aEnded = false - a.done.then(() => { - aEnded = true - }) - for (let waited = 0; !existsSync(marker) && !aEnded; waited += 1) { - if (waited > 6000) throw new Error(`run A neither paused nor ended`) - await sleep(10) + const runs = await Promise.all( + scenario === `race` ? [startRun(), startRun()] : [startRun()], + ) + // A refusal's cause and its fix line, as the start printed them. + const outcomeOf = (run) => { + if (run.stdout.includes(`oracle-gaps: note log`)) return `claimed` + const cause = run.stderr.match(/^refused: (.*)$/m)?.[1] + if (cause === undefined || run.code !== 2) return `other` + const fix = run.stderr.match(/^fix: (.*)$/m)?.[1] ?? `` + return `refused (${cause}; fix ${fix.includes(`run.pid`) ? `names the claim` : `does not name the claim`})` } - const b = startRun(cleanEnv()) - let bEnded = false - b.done.then(() => { - bEnded = true - }) - for ( - let waited = 0; - !b.got.stdout.includes(`oracle-gaps: note log`) && !bEnded; - waited += 1 - ) { - if (waited > 12000) throw new Error(`run B neither claimed nor ended`) - await sleep(10) + return { + scenario, + outDir: out, + outcomes: runs.map(outcomeOf).sort(), + // The claim is kept as it was, and nothing else is in the directory: a + // refusal writes no note, no log, and no temp file. + claimKept: readFileSync(claim, `utf8`) === written, + otherFiles: readdirSync(out).filter((name) => name !== `run.pid`), } - writeFileSync(release, ``) - const runA = await a.done - const runB = await b.done - return { scenario, outcomes: [outcomeOf(runA), outcomeOf(runB)].sort() } } async function overlappingRuns(dir, files, how) { @@ -1948,11 +1923,7 @@ async function driver(plan, observe) { if (plan.claimScenario) { const claim = await claimScenarioRuns(dir, files, how, plan.claimScenario) observe(`claimScenario`, claim) - states.add( - claim.scenario === `race` - ? `two starts race for a stale claim` - : `a stale claim and mutex from a dead pid are taken over`, - ) + states.add(claimStateOf[claim.scenario]) } if (plan.outMode === `default`) states.add(`a run with the default output directory`) @@ -2549,14 +2520,26 @@ function check(plan, observations, expected) { (o) => o.checkpoint === `claimScenario`, )?.value if (claim !== undefined) { - const owed = - claim.scenario === `race` ? [`claimed`, `refused`] : [`claimed`] + // A stale claim refuses every start (the maintainer's decision, "Stale claims + // refuse; no takeover"); each refusal names its cause and the claim. + const cause = + claim.scenario === `empty` + ? `run.pid in ${claim.outDir} does not name a pid` + : `run.pid names pid 999999, which is not running` + const refused = `refused (${cause}; fix names the claim)` + const owed = claim.scenario === `race` ? [refused, refused] : [refused] if (JSON.stringify(claim.outcomes) !== JSON.stringify(owed)) return violation( `claimScenario`, `a ${claim.scenario} gave ${JSON.stringify(claim.outcomes)}, owed ${JSON.stringify(owed)}`, `ownership`, ) + if (!claim.claimKept || claim.otherFiles.length > 0) + return violation( + `claimScenario`, + `a ${claim.scenario} wrote beyond its claim attempt: run.pid kept ${claim.claimKept}, other files ${JSON.stringify(claim.otherFiles)}`, + `ownership`, + ) } const overlap = observations.find((o) => o.checkpoint === `overlap`)?.value if (overlap !== undefined) { @@ -3594,7 +3577,8 @@ const staticStates = [ ] const required = [ `two starts race for a stale claim`, - `a stale claim and mutex from a dead pid are taken over`, + `a start refuses a stale claim`, + `a start refuses an empty claim`, `a stop as the CLI starts`, `a stream log that cannot be written`, `two runs on one output directory`, @@ -3772,7 +3756,8 @@ const faults = [ // of its own must enter them, or registration fails). const ownHistoryStates = [ `two starts race for a stale claim`, - `a stale claim and mutex from a dead pid are taken over`, + `a start refuses a stale claim`, + `a start refuses an empty claim`, `a stop as the CLI starts`, `a stream log that cannot be written`, `two runs on one output directory`, @@ -4725,9 +4710,7 @@ oracleProperty({ }), }, { - // Two starts meet a stale claim (review of #57, the claim rules): both - // are paused in the takeover mutex, and the race must end claimed and - // refused, one run each. + // Two starts meet a dead pid's claim (the maintainer's decision, "Stale claims refuse; no takeover"): both refuse, each names the claim, and neither writes past its claim attempt. name: `two starts race for a stale claim`, enters: [`two starts race for a stale claim`], build: (generated) => ({ @@ -4755,10 +4738,37 @@ oracleProperty({ }), }, { - // A start meets a claim and a takeover mutex left by dead pids: it takes - // both over and claims the output directory. - name: `a stale claim and mutex from a dead pid are taken over`, - enters: [`a stale claim and mutex from a dead pid are taken over`], + // One start meets a dead pid's claim: it refuses and names the claim and its fix. + name: `a start refuses a stale claim`, + enters: [`a start refuses a stale claim`], + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], + wholeFile: `none`, + witness: false, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, + steps: null, + ordinary: false, + budget: `two`, + outMode: `explicit`, + logBlocked: false, + overlap: false, + claimScenario: `stale`, + }), + }, + { + // One start meets an empty claim: it refuses, and the claim is never taken over. + name: `a start refuses an empty claim`, + enters: [`a start refuses an empty claim`], build: (generated) => ({ ...generated, functions: [[{ kind: `push`, quote: `'` }]], @@ -4780,7 +4790,7 @@ oracleProperty({ outMode: `explicit`, logBlocked: false, overlap: false, - claimScenario: `recovery`, + claimScenario: `empty`, }), }, ]), diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index ecf07418..1120a162 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -125,7 +125,7 @@ // CLI's modules load (review of #57, P1): a signal during the loads is kept // and acted on once the stream log's note is written, so a stop as the CLI starts still // leaves the note and one done line. Only Node's own start is before them. -import { spawn } from 'node:child_process' +import { execFileSync, spawn } from 'node:child_process' import { appendFileSync, existsSync, @@ -174,9 +174,17 @@ let streamLog let writingEnding = false const logPathOf = (out) => join(out, `stream.log`) /** Writes `text` to stderr and, once the log is open, to the stream log. */ +/** Appends `text` to the stream log at `path`; a failure is the refusal that ends the run. */ +const appendLog = (path, text) => { + try { + appendFileSync(path, text) + } catch (error) { + throw cannotWrite(path, error) + } +} const writeStream = (text) => { process.stderr.write(text) - if (streamLog) appendFileSync(streamLog, text) + if (streamLog) appendLog(streamLog, text) } const cannotWrite = (path, error) => new Refusal( @@ -192,30 +200,28 @@ const alive = (pid) => { return error.code === `EPERM` } } -// The pid this process claimed each output directory with, released when the -// process exits (on every exit but SIGKILL). -const claims = new Set() +// The output directory this process claimed (its run.pid), released when the +// process exits, on every exit but SIGKILL. +let claimed process.on(`exit`, () => { - for (const claim of claims) { - try { - if (Number(readFileSync(claim, `utf8`)) === process.pid) - rmSync(claim, { force: true }) - } catch { - // Already gone. - } + if (claimed === undefined) return + try { + if (Number(readFileSync(claimed, `utf8`)) === process.pid) + rmSync(claimed, { force: true }) + } catch { + // Already gone. } }) /** - * Claims output directory `out` for this process (review of #57, P2 and P3): - * a run keeps it while it lives, and a second run on it refuses without - * writing into it (the maintainer's decision of 2026-11-13). The claim is a - * temp file that already holds the pid, linked to `run.pid`, which fails when - * `run.pid` exists, so the claim is atomic. A claim whose pid no longer runs - * is taken over. + * Claims output directory `out` for this process. The claim is a temp file that + * already holds the pid, linked to `run.pid`, which fails when `run.pid` exists, + * so the claim is atomic. A `run.pid` that names no running process, or that + * cannot be read, refuses as a live one does: nothing is taken over (the + * maintainer's decision, "Stale claims refuse; no takeover"), and the user + * removes the file. */ function claimOut(out) { const claim = join(out, `run.pid`) - const takeover = `${claim}.takeover` const temp = `${claim}.${process.pid}.tmp` try { mkdirSync(out, { recursive: true }) @@ -224,46 +230,35 @@ function claimOut(out) { throw cannotWrite(claim, error) } try { - for (;;) { - try { - linkSync(temp, claim) - claims.add(claim) - return - } catch (error) { - if (error.code !== `EEXIST`) throw cannotWrite(claim, error) - } - const holder = readHolder(claim) - if (holder === undefined) continue - // An unreadable claim counts as live: wait for it, never take it over. - if (!(holder > 0)) { - sleepMs(10) - continue - } - if (holder !== process.pid && holder > 0 && alive(holder)) { - const refusal = new Refusal( - `another run (pid ${holder}) is using ${out}`, - `If no run is using it, delete ${claim}; otherwise pass --out a directory no run is using.`, - ) - refusal.reportless = true - throw refusal - } - // A stale claim: only the racer that creates the takeover mutex removes it, - // and only if it still names the stale pid it read (review F4). - testPause(`takeover`) - if (!takeMutex(takeover)) { - sleepMs(10) - continue - } - try { - if (readHolder(claim) === holder) rmSync(claim, { force: true }) - } finally { - rmSync(takeover, { recursive: true, force: true }) - } - } + linkSync(temp, claim) + claimed = claim + } catch (error) { + if (error.code !== `EEXIST`) throw cannotWrite(claim, error) + throw heldRefusal(out, claim, readHolder(claim)) } finally { rmSync(temp, { force: true }) } } +/** The refusal for a `run.pid` that holds its directory or cannot be read. */ +function heldRefusal(out, claim, holder) { + const refusal = + holder > 0 && alive(holder) + ? new Refusal( + `another run (pid ${holder}) is using ${out}`, + `If no run is using it, delete ${claim}; otherwise pass --out a directory no run is using.`, + ) + : holder > 0 + ? new Refusal( + `run.pid names pid ${holder}, which is not running`, + `if no run uses ${out}, delete ${claim}`, + ) + : new Refusal( + `run.pid in ${out} does not name a pid`, + `if no run uses ${out}, delete ${claim}`, + ) + refusal.reportless = true + return refusal +} /** The pid a claim names, or undefined when the claim is gone. */ function readHolder(claim) { try { @@ -273,33 +268,8 @@ function readHolder(claim) { throw cannotWrite(claim, error) } } -/** - * Takes the takeover mutex. The pid is written to a temp file first and linked - * into place, so no reader ever sees an empty mutex (review F4; register: #57 - * claim rules). A mutex whose pid can't be read counts as live and is never - * taken over; only a mutex whose recorded pid is dead is removed, and then made - * again. - */ -function takeMutex(mutex) { - const temp = `${mutex}.${process.pid}.tmp` - writeFileSync(temp, `${process.pid}\n`) - try { - testPause(`mutex-create`) - linkSync(temp, mutex) - return true - } catch (error) { - if (error.code !== `EEXIST`) throw error - const owner = readHolder(mutex) - if (owner === undefined) return false - if (owner > 0 && !alive(owner)) { - rmSync(mutex, { force: true }) - return takeMutex(mutex) - } - return false - } finally { - rmSync(temp, { force: true }) - } -} +// The longest a test-only wait lasts before it fails the run loudly. +const TEST_WAIT_LIMIT_MS = 60_000 /** * A test-only hold at one named point (ORACLE_GAPS_TEST_PAUSE_AT): the process * writes its marker (ORACLE_GAPS_TEST_PAUSE_MARKER) when it reaches the point, @@ -311,7 +281,17 @@ function testPause(point) { const marker = process.env.ORACLE_GAPS_TEST_PAUSE_MARKER if (marker !== undefined) writeFileSync(marker, ``) const until = process.env.ORACLE_GAPS_TEST_PAUSE_UNTIL - if (until !== undefined) while (!existsSync(until)) sleepMs(20) + if (until !== undefined) waitForFile(until, `the pause at ${point}`) +} +/** Waits for `file` for at most TEST_WAIT_LIMIT_MS, then throws. */ +function waitForFile(file, what) { + for (let waited = 0; !existsSync(file); waited += 20) { + if (waited >= TEST_WAIT_LIMIT_MS) + throw new Error( + `${what} was not released within ${TEST_WAIT_LIMIT_MS} ms`, + ) + sleepMs(20) + } } function sleepMs(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms) @@ -335,6 +315,7 @@ function startLog(out) { const note = `oracle-gaps: note log ${posix(path)}\n` process.stdout.write(note) writeStream(note) + testPause(`note`) } /** Flushes both streams, then exits with `code` (after a test's hold). */ @@ -346,7 +327,7 @@ function startLog(out) { */ function holdUntil() { const file = process.env.ORACLE_GAPS_TEST_HOLD_UNTIL - if (file !== undefined) while (!existsSync(file)) sleepMs(20) + if (file !== undefined) waitForFile(file, `the hold`) } function exitWhenFlushed(code) { process.stdout.write(``, () => @@ -403,8 +384,14 @@ function superviseRun(out) { ? `oracle-gaps: done stopped (${stopped})\n` : `oracle-gaps: done error, the run's process exited with ${how}${outOfMemory ? `: it ran out of memory; give Node more (NODE_OPTIONS=--max-old-space-size=) or run fewer --contexts` : ``}\n` process.stdout.write(line, () => { - // The log was opened before the run started (startLog). - appendFileSync(streamLog, line) + // The log was opened before the run started (startLog). A log that + // cannot take the line does not change the ending: both streams still + // get it, and the code is the decided one. + try { + appendLog(streamLog, line) + } catch { + // The line is still written to stderr below. + } process.stderr.write(line, () => process.exit(stopped ? 128 + constants.signals[stopped] : 3), ) @@ -437,12 +424,7 @@ function superviseRun(out) { process.on(`SIGTERM`, stop) // A test-only stop (ORACLE_GAPS_TEST_STOP, #58): once the named file exists, the // stop is taken as a SIGINT would be. Inert unless set. - if (process.env.ORACLE_GAPS_TEST_STOP !== undefined) { - const file = process.env.ORACLE_GAPS_TEST_STOP - setInterval(() => { - if (existsSync(file)) stop(`SIGINT`) - }, 50).unref() - } + watchTestStop(stop) if (early !== undefined) return stop(early) // An inspector flag would bind the CLI's own port a second time. child = spawn( @@ -456,7 +438,10 @@ function superviseRun(out) { { detached: true, stdio: [`inherit`, `inherit`, `pipe`, `ipc`], - env: { ...process.env, ORACLE_GAPS_GROUP: String(process.pid) }, + env: { + ...process.env, + ORACLE_GAPS_INTERNAL_SUPERVISED: String(process.pid), + }, }, ) child.on(`message`, (message) => { @@ -467,7 +452,7 @@ function superviseRun(out) { // for V8's out-of-memory message. child.stderr.on(`data`, (chunk) => { process.stderr.write(chunk) - appendFileSync(streamLog, chunk) + appendLog(streamLog, chunk) stderrTail = (stderrTail + chunk).slice(-200) if (/heap out of memory/i.test(stderrTail)) outOfMemory = true }) @@ -495,10 +480,36 @@ function signalGroup(group, signal) { * kills its group, itself included. */ function watchSupervisor(supervisor) { + // Only a process that leads its own group kills it: an inherited variable + // (a test's child, say) must not name a group this process does not lead. + if (groupOf(process.pid) !== process.pid) return setInterval(() => { if (process.ppid !== supervisor) process.kill(-process.pid, `SIGKILL`) }, 1000).unref() } +/** The process group of `pid` (POSIX, through ps); undefined when unknown. */ +function groupOf(pid) { + try { + return Number( + execFileSync(`ps`, [`-o`, `pgid=`, `-p`, String(pid)], { + encoding: `utf8`, + }).trim(), + ) + } catch { + return undefined + } +} +/** + * A test-only stop (ORACLE_GAPS_TEST_STOP, #58): once the named file exists, the + * stop is taken as a SIGINT would be. Inert unless set. + */ +function watchTestStop(onStop) { + const file = process.env.ORACLE_GAPS_TEST_STOP + if (file === undefined) return + setInterval(() => { + if (existsSync(file)) onStop(`SIGINT`) + }, 50).unref() +} /** * The options of arguments `argv` when they ask for a check, the only run that @@ -554,7 +565,11 @@ function endWith(error, out) { ended = true const ending = endRun(error, out) holdStops() - writeStream(ending.stderr) + try { + writeStream(ending.stderr) + } catch { + // The log cannot take the ending, which writeStream wrote to stderr first. + } process.stdout.write(`${ending.done}\n`) exitWhenFlushed(ending.exitCode) } @@ -565,7 +580,7 @@ const main = import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href // Windows has no process groups: there the run is the CLI's own process. const supervised = process.platform !== `win32` -const supervisor = process.env.ORACLE_GAPS_GROUP +const supervisor = process.env.ORACLE_GAPS_INTERNAL_SUPERVISED // Set once the note is written (the unsupervised run has started). let runStarted = false @@ -578,12 +593,18 @@ function stopNow(signal) { } async function run() { + // The run's options, once its arguments parse. The handlers come first, so an + // error thrown by the supervisor ends the run through endWith too. + let options + process.on(`uncaughtException`, (error) => endWith(error, options?.out)) + process.on(`unhandledRejection`, (error) => endWith(error, options?.out)) // The supervisor: it claims the output directory, writes the note, and runs // the child. A refusal of the claim or the log ends it through endWith (the // single path for every refusal of a check). if (supervised && supervisor === undefined) { const checking = asksForCheck(process.argv.slice(2)) if (checking !== undefined) { + options = checking try { startLog(checking.out) } catch (error) { @@ -594,7 +615,7 @@ async function run() { } if (supervisor !== undefined) watchSupervisor(Number(supervisor)) // A test that runs this CLI starts a run of its own, in a group of its own. - delete process.env.ORACLE_GAPS_GROUP + delete process.env.ORACLE_GAPS_INTERNAL_SUPERVISED // A stop ends the run at once, with no line: an error that the stop causes // is no refusal, and the supervisor writes the stopped line. Once the run // writes its ending, a stop no longer cuts it off. @@ -609,23 +630,12 @@ async function run() { process.on(`SIGINT`, onStop) process.on(`SIGTERM`, onStop) // A test-only stop for unsupervised runs (ORACLE_GAPS_TEST_STOP, #58). - if (process.env.ORACLE_GAPS_TEST_STOP !== undefined && !supervised) { - const file = process.env.ORACLE_GAPS_TEST_STOP - setInterval(() => { - if (existsSync(file)) onStop(`SIGINT`) - }, 50).unref() - } + if (!supervised) watchTestStop(onStop) // A child of a supervisor that was stopped before its own handlers ran exits // now (the supervisor writes the line). An unsupervised run keeps the stop // and takes it once its note is written, below. if (supervisor !== undefined && early !== undefined) process.exit(128 + constants.signals[early]) - // The run's options, once its arguments parse. - let options - // An error thrown outside the awaited check, by a timer or a promise no one - // awaits, ends the run the same way. - process.on(`uncaughtException`, (error) => endWith(error, options?.out)) - process.on(`unhandledRejection`, (error) => endWith(error, options?.out)) try { options = parseArgs(process.argv.slice(2)) if (options.help) console.log(usage) diff --git a/packages/oracles/scripts/e2e-shards.mjs b/packages/oracles/scripts/e2e-shards.mjs index b6fc53b8..2b7bc339 100644 --- a/packages/oracles/scripts/e2e-shards.mjs +++ b/packages/oracles/scripts/e2e-shards.mjs @@ -79,7 +79,8 @@ export const shards = { // 522 s in the measured run, about 221 s idle. 'e2e-2': [ `fixed seed 20261105: two starts race for a stale claim`, - `fixed seed 20261105: a stale claim and mutex from a dead pid are taken over`, + `fixed seed 20261105: a start refuses a stale claim`, + `fixed seed 20261105: a start refuses an empty claim`, `fixed seed 20261105: a stop as the CLI starts`, `fixed seed 20261105: a declaration fault: setupThrows`, `fixed seed 20261105: a package with no config`, @@ -114,7 +115,8 @@ export const shards = { // 522 s in the measured run, about 221 s idle. 'e2e-3': [ `determinism: constructed history: two starts race for a stale claim`, - `determinism: constructed history: a stale claim and mutex from a dead pid are taken over`, + `determinism: constructed history: a start refuses a stale claim`, + `determinism: constructed history: a start refuses an empty claim`, `determinism: constructed history: a stop as the CLI starts`, `random seed: a stop with the default output directory`, `random seed: a daemon check with the default output directory`, @@ -151,7 +153,8 @@ export const shards = { // 522 s in the measured run, about 221 s idle. 'e2e-4': [ `random seed: two starts race for a stale claim`, - `random seed: a stale claim and mutex from a dead pid are taken over`, + `random seed: a start refuses a stale claim`, + `random seed: a start refuses an empty claim`, `random seed: a stop as the CLI starts`, `fixed seed 20261105: a .ts config in a package with no module type that calls require`, `fixed seed 20261105: a config that --config names`, diff --git a/packages/oracles/scripts/pr-shards.mjs b/packages/oracles/scripts/pr-shards.mjs index d1207211..925b8937 100644 --- a/packages/oracles/scripts/pr-shards.mjs +++ b/packages/oracles/scripts/pr-shards.mjs @@ -302,7 +302,8 @@ export const partitions = { 'a stale authored mutant and a reformat', 'a failing owner under a config that --config names', 'two starts race for a stale claim', - 'a stale claim and mutex from a dead pid are taken over', + 'a start refuses a stale claim', + 'a start refuses an empty claim', ]), // 134 s, 101 s, 27 s, and 15 s. 2: anyOf([ @@ -528,7 +529,8 @@ export const partitions = { ]), 2: anyOf([ 'two starts race for a stale claim', - 'a stale claim and mutex from a dead pid are taken over', + 'a start refuses a stale claim', + 'a start refuses an empty claim', 'a stop with the default output directory', 'a daemon check with the default output directory', 'a .ts config in a package with no module type that calls require', From 71dbed9cac6fb066798c931223bd4817fcd4b8d8 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 19:45:26 -0700 Subject: [PATCH 27/62] test(oracle-gaps): define the claim state map; a claim a start removed is not kept The claim driver referenced claimStateOf, which was not defined, so every claim history threw. And a mutant that takes a claim removes run.pid when it exits, so reading the claim back must tolerate its absence (the law then judges the outcome). The driver also kills any start it spawned when it throws. Co-authored-by: Isaac --- .../gap-report-oracle.property.test.mjs | 25 ++++++++++++++++--- 1 file changed, 21 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 d4e86ad5..29827eed 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -962,6 +962,13 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms)) * observation (the coordinator's decision of 2026-11-13 on F4: a second run * refuses, and the first's stream log stays its own). */ +/** The state each claim scenario enters. */ +const claimStateOf = { + race: `two starts race for a stale claim`, + stale: `a start refuses a stale claim`, + empty: `a start refuses an empty claim`, +} + /** * Runs a claim scenario (the maintainer's decision, "Stale claims refuse; no * takeover"): a run.pid that names a dead pid (`stale`), an empty run.pid @@ -976,6 +983,8 @@ async function claimScenarioRuns(dir, files, how, scenario) { const claim = join(out, `run.pid`) const written = scenario === `empty` ? `` : `999999\n` writeFileSync(claim, written) + // Every start this driver spawns, so a failure here never leaves one running. + const children = [] const startRun = () => { const got = { stdout: ``, stderr: `` } const child = spawn(process.execPath, args, { @@ -983,6 +992,7 @@ async function claimScenarioRuns(dir, files, how, scenario) { env: cleanEnv(), stdio: [`ignore`, `pipe`, `pipe`], }) + children.push(child) child.stdout.on(`data`, (chunk) => { got.stdout += chunk }) @@ -997,9 +1007,16 @@ async function claimScenarioRuns(dir, files, how, scenario) { }) }) } - const runs = await Promise.all( - scenario === `race` ? [startRun(), startRun()] : [startRun()], - ) + let runs + try { + runs = await Promise.all( + scenario === `race` ? [startRun(), startRun()] : [startRun()], + ) + } finally { + for (const child of children) + if (child.exitCode === null && child.signalCode === null) + child.kill(`SIGKILL`) + } // A refusal's cause and its fix line, as the start printed them. const outcomeOf = (run) => { if (run.stdout.includes(`oracle-gaps: note log`)) return `claimed` @@ -1014,7 +1031,7 @@ async function claimScenarioRuns(dir, files, how, scenario) { outcomes: runs.map(outcomeOf).sort(), // The claim is kept as it was, and nothing else is in the directory: a // refusal writes no note, no log, and no temp file. - claimKept: readFileSync(claim, `utf8`) === written, + claimKept: existsSync(claim) && readFileSync(claim, `utf8`) === written, otherFiles: readdirSync(out).filter((name) => name !== `run.pid`), } } From 035dcc55cba4819977d528570b296e45da5aea16 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 20:34:19 -0700 Subject: [PATCH 28/62] test(oracle-gaps): a stream log lost after its note, then stopped or completed F1 (review of #57): a stream log that becomes unwritable after the note crashed the supervisor with a stack, because its stream-log append was unguarded and the uncaught handler was registered after the supervisor returned. - The supervisor records a lost stderr relay once and keeps relaying, so the run's own ending is the only done line on each stream. - New constructed histories: the log is swapped for a directory while the supervisor is paused at the note (ORACLE_GAPS_TEST_PAUSE_AT=note), then the run is stopped or allowed to complete. The law: one done line on each stream, the same on both, the exit code it owes, and no stack. - Stops sent by child.kill on win32 owe no done line (register, "Windows stops", C 2026-11-13); an abort is judged as before. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-model-oracle.mjs | 8 +- .../gap-report-oracle.property.test.mjs | 181 +++++++++++++++++- packages/oracles/oracle-gaps/index.mjs | 11 +- packages/oracles/scripts/e2e-shards.mjs | 6 + packages/oracles/scripts/pr-shards.mjs | 4 + 5 files changed, 204 insertions(+), 6 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index 3e250115..937d3995 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -838,6 +838,9 @@ const drawn = fc.record({ // A constant draws nothing, so generated histories never run the claim driver, // and `histories` below takes a constructed scenario back as this constant. claimScenario: fc.constant(false), + // A stream log that becomes a directory right after the note (review of #57, + // F1): constructed only, and taken back as the constant false below. + logLost: fc.constant(false), // The spawn stop waits for the CLI's started marker, then signals at once (the // deterministic witness, event-driven rather than timed). }) @@ -894,9 +897,9 @@ const histories = drawn.map( ) if (!keepsSteps(history)) throw new Error(`a history with the witness module takes no steps`) - return history.claimScenario === false + return history.claimScenario === false && history.logLost === false ? value - : { ...history, claimScenario: false } + : { ...history, claimScenario: false, logLost: false } }, ) @@ -2947,6 +2950,7 @@ function resolveHistory(history) { // histories keep their fixed-seed draws and run no claim driver (P4, the // coordinator's decision on the claim rules). claimScenario: history.claimScenario ?? false, + logLost: history.logLost ?? false, spawnOnStart: history.spawnOnStart === true, onlyRun: history.onlyRun === true, pragma: history.pragma === true, 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 29827eed..04e3640b 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -481,6 +481,7 @@ import { spawn, spawnSync } from 'node:child_process' import { cpSync, existsSync, + statSync, mkdirSync, mkdtempSync, readdirSync, @@ -962,6 +963,12 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms)) * observation (the coordinator's decision of 2026-11-13 on F4: a second run * refuses, and the first's stream log stays its own). */ +/** The state each unwritable-log ending enters. */ +const lostStateOf = { + stop: `a stream log lost after its note, then stopped`, + complete: `a stream log lost after its note, then completed`, +} + /** The state each claim scenario enters. */ const claimStateOf = { race: `two starts race for a stale claim`, @@ -1036,6 +1043,71 @@ async function claimScenarioRuns(dir, files, how, scenario) { } } +/** + * Runs a check whose stream log becomes a directory right after its note + * (review of #57, F1). The supervisor pauses at the note (ORACLE_GAPS_TEST_PAUSE_AT), + * the driver replaces stream.log with a directory, and the run is then stopped + * (`stop`, through the test stop file) or allowed to complete (`complete`). The + * stop file is written before the release, and the stop watcher starts only + * once the supervisor runs, so the stop is taken by an event, not a timer. + */ +async function unwritableLogRuns(dir, files, how, ending) { + const { args, out } = cliArgs(dir, files, { ...how, outName: `out-lost` }) + const marker = join(dir, `lost-at-note`) + const release = join(dir, `release-lost`) + const stopFile = join(dir, `stop-lost`) + const log = join(out, `stream.log`) + const got = { stdout: ``, stderr: `` } + const child = spawn(process.execPath, args, { + cwd: repo, + env: { + ...cleanEnv(), + ORACLE_GAPS_TEST_PAUSE_AT: `note`, + ORACLE_GAPS_TEST_PAUSE_MARKER: marker, + ORACLE_GAPS_TEST_PAUSE_UNTIL: release, + ORACLE_GAPS_TEST_STOP: stopFile, + }, + stdio: [`ignore`, `pipe`, `pipe`], + }) + child.stdout.on(`data`, (chunk) => { + got.stdout += chunk + }) + child.stderr.on(`data`, (chunk) => { + got.stderr += chunk + }) + const exited = new Promise((resolvePromise) => { + child.on(`close`, (code, signal) => resolvePromise({ code, signal })) + }) + let hasEnded = false + exited.then(() => { + hasEnded = true + }) + const timer = setTimeout(() => child.kill(`SIGKILL`), 60_000) + try { + for (let waited = 0; !existsSync(marker) && !hasEnded; waited += 1) { + if (waited > 6000) throw new Error(`the run never reached its note`) + await sleep(10) + } + if (existsSync(marker)) { + rmSync(log, { force: true }) + mkdirSync(log) + if (ending === `stop`) writeFileSync(stopFile, ``) + writeFileSync(release, ``) + } + const { code, signal } = await exited + return { + ending, + exit: code, + signal, + stdout: got.stdout, + stderr: got.stderr, + logIsDirectory: existsSync(log) && statSync(log).isDirectory(), + } + } finally { + clearTimeout(timer) + } +} + async function overlappingRuns(dir, files, how) { writeFixture(dir, files) const before = new Set(filesUnder(dir)) @@ -1942,6 +2014,13 @@ async function driver(plan, observe) { observe(`claimScenario`, claim) states.add(claimStateOf[claim.scenario]) } + if (plan.logLost) { + observe( + `unwritableLog`, + await unwritableLogRuns(dir, files, how, plan.logLost), + ) + states.add(lostStateOf[plan.logLost]) + } if (plan.outMode === `default`) states.add(`a run with the default output directory`) if (plan.logBlocked && cli.exit === 2) @@ -2558,6 +2637,38 @@ function check(plan, observations, expected) { `ownership`, ) } + const lost = observations.find((o) => o.checkpoint === `unwritableLog`)?.value + if (lost !== undefined) { + // The stream log became a directory after the note. Whatever ends the run, + // each stream ends with one done line, the same on both, the exit code is + // the one that line owes, and no stack trace is printed (review of #57, F1). + const doneOf = (text) => + text.split(`\n`).filter((line) => line.startsWith(`oracle-gaps: done `)) + const owedExit = (line) => + /done stopped \(SIGINT\)/.test(line) + ? 128 + 2 + : /done completed/.test(line) + ? 0 + : /done error/.test(line) + ? 3 + : /done refused/.test(line) + ? 2 + : undefined + const outDone = doneOf(lost.stdout) + const errDone = doneOf(lost.stderr) + const streams = `${lost.stdout}${lost.stderr}` + let difference + if (outDone.length !== 1 || errDone.length !== 1) + difference = `the lost log's run printed ${outDone.length} done lines on stdout and ${errDone.length} on stderr` + else if (outDone[0] !== errDone[0]) + difference = `the done lines differ: ${JSON.stringify(outDone[0])} on stdout, ${JSON.stringify(errDone[0])} on stderr` + else if (lost.exit !== owedExit(errDone[0])) + difference = `the exit code is ${lost.exit}, owed ${owedExit(errDone[0])} for ${JSON.stringify(errDone[0])}` + else if (/^\s+at \S/m.test(streams) || /^\w*Error: /m.test(streams)) + difference = `a stack trace was printed` + if (difference !== undefined) + return violation(`unwritableLog`, difference, `greppable stream`) + } const overlap = observations.find((o) => o.checkpoint === `overlap`)?.value if (overlap !== undefined) { if (overlap.exit !== 2) @@ -2862,8 +2973,12 @@ function check(plan, observations, expected) { { actual: value.survivors, expected: 0 }, ) // A stopped run ends both streams with its stopped line, and one that - // had printed its completed line ends as it completed (law 15). - const ends = value.spun ? endsBreach(value) : undefined + // had printed its completed line ends as it completed (law 15). On win32 + // the driver's stop is child.kill, which is TerminateProcess, so the run is + // killed like SIGKILL and no done line is owed (register, "Windows stops", + // C 2026-11-13). An abort is the run's own end, which is judged as before. + const owesDone = process.platform !== `win32` || value.when === `abort` + const ends = value.spun && owesDone ? endsBreach(value) : undefined if (ends) return violation( `stopped`, @@ -2883,7 +2998,7 @@ function check(plan, observations, expected) { `the run stopped while its config warmed reported a refusal`, `greppable stream`, ) - if (value.spun && !value.stream.last.startsWith(owedEnd)) + if (value.spun && owesDone && !value.stream.last.startsWith(owedEnd)) return violation( `stopped`, `the stopped run's last line is ${JSON.stringify(value.stream.last)}, not ${owedEnd}`, @@ -3596,6 +3711,8 @@ const required = [ `two starts race for a stale claim`, `a start refuses a stale claim`, `a start refuses an empty claim`, + `a stream log lost after its note, then stopped`, + `a stream log lost after its note, then completed`, `a stop as the CLI starts`, `a stream log that cannot be written`, `two runs on one output directory`, @@ -3775,6 +3892,8 @@ const ownHistoryStates = [ `two starts race for a stale claim`, `a start refuses a stale claim`, `a start refuses an empty claim`, + `a stream log lost after its note, then stopped`, + `a stream log lost after its note, then completed`, `a stop as the CLI starts`, `a stream log that cannot be written`, `two runs on one output directory`, @@ -4810,6 +4929,62 @@ oracleProperty({ claimScenario: `empty`, }), }, + { + // The stream log becomes a directory after the note, then the run is stopped: one done line on each stream, the exit code it owes, and no stack. + name: `a stream log lost after its note, then stopped`, + enters: [`a stream log lost after its note, then stopped`], + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], + wholeFile: `none`, + witness: false, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, + steps: null, + ordinary: false, + budget: `two`, + outMode: `explicit`, + logBlocked: false, + overlap: false, + logLost: `stop`, + }), + }, + { + // The stream log becomes a directory after the note, and the run completes: the same law as the stop. + name: `a stream log lost after its note, then completed`, + enters: [`a stream log lost after its note, then completed`], + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], + wholeFile: `none`, + witness: false, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, + steps: null, + ordinary: false, + budget: `two`, + outMode: `explicit`, + logBlocked: false, + overlap: false, + logLost: `complete`, + }), + }, ]), }, resolve: resolveHistory, diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index 1120a162..6279e043 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -357,6 +357,8 @@ function superviseRun(out) { // of memory. let outOfMemory = false let stderrTail = `` + // The first error that the stream log raised after it was open, if any. + let logLost // Whether the run's streams and channel have closed. let closed = false // Ends the CLI once the run has ended (or the grace has passed), with what @@ -452,7 +454,14 @@ function superviseRun(out) { // for V8's out-of-memory message. child.stderr.on(`data`, (chunk) => { process.stderr.write(chunk) - appendLog(streamLog, chunk) + // A log that cannot take the run's stderr is recorded once, and the relay + // goes on: the run's own ending stays the only done line on each stream. + if (logLost === undefined) + try { + appendLog(streamLog, chunk) + } catch (error) { + logLost = error + } stderrTail = (stderrTail + chunk).slice(-200) if (/heap out of memory/i.test(stderrTail)) outOfMemory = true }) diff --git a/packages/oracles/scripts/e2e-shards.mjs b/packages/oracles/scripts/e2e-shards.mjs index 2b7bc339..a273ce6e 100644 --- a/packages/oracles/scripts/e2e-shards.mjs +++ b/packages/oracles/scripts/e2e-shards.mjs @@ -81,6 +81,8 @@ export const shards = { `fixed seed 20261105: two starts race for a stale claim`, `fixed seed 20261105: a start refuses a stale claim`, `fixed seed 20261105: a start refuses an empty claim`, + `fixed seed 20261105: a stream log lost after its note, then stopped`, + `fixed seed 20261105: a stream log lost after its note, then completed`, `fixed seed 20261105: a stop as the CLI starts`, `fixed seed 20261105: a declaration fault: setupThrows`, `fixed seed 20261105: a package with no config`, @@ -117,6 +119,8 @@ export const shards = { `determinism: constructed history: two starts race for a stale claim`, `determinism: constructed history: a start refuses a stale claim`, `determinism: constructed history: a start refuses an empty claim`, + `determinism: constructed history: a stream log lost after its note, then stopped`, + `determinism: constructed history: a stream log lost after its note, then completed`, `determinism: constructed history: a stop as the CLI starts`, `random seed: a stop with the default output directory`, `random seed: a daemon check with the default output directory`, @@ -155,6 +159,8 @@ export const shards = { `random seed: two starts race for a stale claim`, `random seed: a start refuses a stale claim`, `random seed: a start refuses an empty claim`, + `random seed: a stream log lost after its note, then stopped`, + `random seed: a stream log lost after its note, then completed`, `random seed: a stop as the CLI starts`, `fixed seed 20261105: a .ts config in a package with no module type that calls require`, `fixed seed 20261105: a config that --config names`, diff --git a/packages/oracles/scripts/pr-shards.mjs b/packages/oracles/scripts/pr-shards.mjs index 925b8937..5dae4bae 100644 --- a/packages/oracles/scripts/pr-shards.mjs +++ b/packages/oracles/scripts/pr-shards.mjs @@ -304,6 +304,8 @@ export const partitions = { 'two starts race for a stale claim', 'a start refuses a stale claim', 'a start refuses an empty claim', + 'a stream log lost after its note, then stopped', + 'a stream log lost after its note, then completed', ]), // 134 s, 101 s, 27 s, and 15 s. 2: anyOf([ @@ -531,6 +533,8 @@ export const partitions = { 'two starts race for a stale claim', 'a start refuses a stale claim', 'a start refuses an empty claim', + 'a stream log lost after its note, then stopped', + 'a stream log lost after its note, then completed', 'a stop with the default output directory', 'a daemon check with the default output directory', 'a .ts config in a package with no module type that calls require', From 5c0a89588387caf8e7e7e0a1da66e502d2bf4627 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 21:14:44 -0700 Subject: [PATCH 29/62] fix(oracle-gaps): review of the delta: determinism, unreadable claims, loud failures - Determinism: the claim and lost-log observations carry the scratch paths normalized (, ), as the rest of the oracle does. - An unreadable run.pid (a directory, or no permission) refuses with its own cause and fix: "run.pid in can't be read". A claim that vanishes between the link and the read is retried (three attempts at most). - The win32 stop exemption excuses only the done line; the note, the log and the results checks stay. - The ps group check fails the run when ps cannot read the group, so the watchdog is never silently unarmed. - A hold that never releases exits nonzero with an internal-error line. - Removed the dead logLost variable; corrected the stale recovery comments. - New constructed history: a start refuses an unreadable claim (appended). Co-authored-by: Isaac --- .../oracle-gaps/gap-report-model-oracle.mjs | 8 +- .../gap-report-oracle.property.test.mjs | 86 ++++++++++++--- packages/oracles/oracle-gaps/index.mjs | 104 ++++++++++++------ packages/oracles/scripts/e2e-shards.mjs | 3 + packages/oracles/scripts/pr-shards.mjs | 2 + 5 files changed, 154 insertions(+), 49 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index 937d3995..b975f05c 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -834,7 +834,7 @@ const drawn = fc.record({ spawnSignal: fc.constantFrom(`SIGINT`, `SIGINT`, `SIGTERM`), spawnDelay: fc.integer({ min: 0, max: 150 }), spawnOnStart: fc.constantFrom(false, false, false, true), - // A claim scenario (`race` or `recovery`, review of #57) is constructed only. + // A claim scenario (`race`, `stale`, `empty` or `unreadable`, review of #57) is constructed only. // A constant draws nothing, so generated histories never run the claim driver, // and `histories` below takes a constructed scenario back as this constant. claimScenario: fc.constant(false), @@ -2944,9 +2944,9 @@ function resolveHistory(history) { spawnStop: history.spawnStop === true, spawnSignal: history.spawnSignal ?? `SIGINT`, spawnDelay: history.spawnDelay ?? 0, - // A claim left by a dead pid, then the starts that meet it: two racing - // starts (`race`) or one start that must take over a stale claim and its - // mutex (`recovery`). Only constructed histories set it, so generated + // A claim that a start must refuse: two racing starts on a dead pid's claim + // (`race`), one start on it (`stale`), or one on an empty (`empty`) or + // unreadable (`unreadable`) claim. Only constructed histories set it, so generated // histories keep their fixed-seed draws and run no claim driver (P4, the // coordinator's decision on the claim rules). claimScenario: history.claimScenario ?? 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 04e3640b..1403016c 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -974,6 +974,7 @@ const claimStateOf = { race: `two starts race for a stale claim`, stale: `a start refuses a stale claim`, empty: `a start refuses an empty claim`, + unreadable: `a start refuses an unreadable claim`, } /** @@ -988,8 +989,16 @@ async function claimScenarioRuns(dir, files, how, scenario) { const { args, out } = cliArgs(dir, files, { ...how, outName: `out-claim` }) mkdirSync(out, { recursive: true }) const claim = join(out, `run.pid`) - const written = scenario === `empty` ? `` : `999999\n` - writeFileSync(claim, written) + // The claim's text, or none: an unreadable claim is a directory, which no + // read can take. + const written = { + empty: ``, + race: `999999\n`, + stale: `999999\n`, + unreadable: undefined, + }[scenario] + if (written === undefined) mkdirSync(claim) + else writeFileSync(claim, written) // Every start this driver spawns, so a failure here never leaves one running. const children = [] const startRun = () => { @@ -1024,21 +1033,28 @@ async function claimScenarioRuns(dir, files, how, scenario) { if (child.exitCode === null && child.signalCode === null) child.kill(`SIGKILL`) } - // A refusal's cause and its fix line, as the start printed them. + // A refusal's cause and its fix line, as the start printed them. The scratch + // names are normalized, so the observation does not depend on the run's paths. + const names = [ + [out, ``], + [dir, ``], + ] const outcomeOf = (run) => { if (run.stdout.includes(`oracle-gaps: note log`)) return `claimed` const cause = run.stderr.match(/^refused: (.*)$/m)?.[1] if (cause === undefined || run.code !== 2) return `other` const fix = run.stderr.match(/^fix: (.*)$/m)?.[1] ?? `` - return `refused (${cause}; fix ${fix.includes(`run.pid`) ? `names the claim` : `does not name the claim`})` + return `refused (${namedScratch(cause, names)}; fix ${fix.includes(`run.pid`) ? `names the claim` : `does not name the claim`})` } return { scenario, - outDir: out, outcomes: runs.map(outcomeOf).sort(), // The claim is kept as it was, and nothing else is in the directory: a // refusal writes no note, no log, and no temp file. - claimKept: existsSync(claim) && readFileSync(claim, `utf8`) === written, + claimKept: + scenario === `unreadable` + ? existsSync(claim) && statSync(claim).isDirectory() + : existsSync(claim) && readFileSync(claim, `utf8`) === written, otherFiles: readdirSync(out).filter((name) => name !== `run.pid`), } } @@ -1095,12 +1111,16 @@ async function unwritableLogRuns(dir, files, how, ending) { writeFileSync(release, ``) } const { code, signal } = await exited + const names = [ + [out, ``], + [dir, ``], + ] return { ending, exit: code, signal, - stdout: got.stdout, - stderr: got.stderr, + stdout: namedScratch(got.stdout, names), + stderr: namedScratch(got.stderr, names), logIsDirectory: existsSync(log) && statSync(log).isDirectory(), } } finally { @@ -2618,10 +2638,12 @@ function check(plan, observations, expected) { if (claim !== undefined) { // A stale claim refuses every start (the maintainer's decision, "Stale claims // refuse; no takeover"); each refusal names its cause and the claim. - const cause = - claim.scenario === `empty` - ? `run.pid in ${claim.outDir} does not name a pid` - : `run.pid names pid 999999, which is not running` + const cause = { + empty: `run.pid in does not name a pid`, + unreadable: `run.pid in can't be read`, + race: `run.pid names pid 999999, which is not running`, + stale: `run.pid names pid 999999, which is not running`, + }[claim.scenario] const refused = `refused (${cause}; fix names the claim)` const owed = claim.scenario === `race` ? [refused, refused] : [refused] if (JSON.stringify(claim.outcomes) !== JSON.stringify(owed)) @@ -2978,7 +3000,9 @@ function check(plan, observations, expected) { // killed like SIGKILL and no done line is owed (register, "Windows stops", // C 2026-11-13). An abort is the run's own end, which is judged as before. const owesDone = process.platform !== `win32` || value.when === `abort` - const ends = value.spun && owesDone ? endsBreach(value) : undefined + const ends = value.spun + ? endsBreach(value, { doneOwed: owesDone }) + : undefined if (ends) return violation( `stopped`, @@ -3126,7 +3150,7 @@ const logNoteOf = (run) => { * 3 error, and a signal's code stopped). With `checked`, the run started a * check, so its first line names its stream log. Undefined when it holds. */ -function endsBreach(run, { checked = true } = {}) { +function endsBreach(run, { checked = true, doneOwed = true } = {}) { const streams = [ [`stderr`, run.stream], [`stdout`, run.stdoutStream], @@ -3159,6 +3183,9 @@ function endsBreach(run, { checked = true } = {}) { difference: `the run wrote a line on ${where} that is not a line of the stream: ${stream.strays[0]}`, extra: { actual: stream.strays, expected: [] }, } + // A run whose done line is not owed (a stop sent by child.kill on win32) is + // judged on everything above: its note, its log, and its results. + if (!doneOwed) return undefined for (const [where, stream] of streams) if (stream.dones !== 1 || !stream.last.startsWith(`oracle-gaps: done `)) return { @@ -3711,6 +3738,7 @@ const required = [ `two starts race for a stale claim`, `a start refuses a stale claim`, `a start refuses an empty claim`, + `a start refuses an unreadable claim`, `a stream log lost after its note, then stopped`, `a stream log lost after its note, then completed`, `a stop as the CLI starts`, @@ -3892,6 +3920,7 @@ const ownHistoryStates = [ `two starts race for a stale claim`, `a start refuses a stale claim`, `a start refuses an empty claim`, + `a start refuses an unreadable claim`, `a stream log lost after its note, then stopped`, `a stream log lost after its note, then completed`, `a stop as the CLI starts`, @@ -4985,6 +5014,35 @@ oracleProperty({ logLost: `complete`, }), }, + { + // An unreadable claim (a directory where run.pid should be) cannot be read + // at all: its start refuses, and names the claim as unreadable. + name: `a start refuses an unreadable claim`, + enters: [`a start refuses an unreadable claim`], + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], + wholeFile: `none`, + witness: false, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, + steps: null, + ordinary: false, + budget: `two`, + outMode: `explicit`, + logBlocked: false, + overlap: false, + claimScenario: `unreadable`, + }), + }, ]), }, resolve: resolveHistory, diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index 6279e043..cff2fb19 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -230,11 +230,25 @@ function claimOut(out) { throw cannotWrite(claim, error) } try { - linkSync(temp, claim) - claimed = claim - } catch (error) { - if (error.code !== `EEXIST`) throw cannotWrite(claim, error) - throw heldRefusal(out, claim, readHolder(claim)) + // A claim that vanishes between the link and the read was released by a run + // that just ended: the link is tried again, a few times at most. + for (let attempt = 1; ; attempt += 1) { + try { + linkSync(temp, claim) + claimed = claim + return + } catch (error) { + if (error.code !== `EEXIST`) throw cannotWrite(claim, error) + const holder = readHolder(claim) + if (holder === undefined && attempt < 3) continue + if (holder === undefined) + throw new Refusal( + `run.pid in ${out} keeps changing`, + `rerun the check; if no run uses ${out}, delete ${claim}`, + ) + throw heldRefusal(out, claim, holder) + } + } } finally { rmSync(temp, { force: true }) } @@ -242,30 +256,40 @@ function claimOut(out) { /** The refusal for a `run.pid` that holds its directory or cannot be read. */ function heldRefusal(out, claim, holder) { const refusal = - holder > 0 && alive(holder) + holder === UNREADABLE ? new Refusal( - `another run (pid ${holder}) is using ${out}`, - `If no run is using it, delete ${claim}; otherwise pass --out a directory no run is using.`, + `run.pid in ${out} can't be read`, + `if no run uses ${out}, delete ${claim}`, ) - : holder > 0 + : holder > 0 && alive(holder) ? new Refusal( - `run.pid names pid ${holder}, which is not running`, - `if no run uses ${out}, delete ${claim}`, - ) - : new Refusal( - `run.pid in ${out} does not name a pid`, - `if no run uses ${out}, delete ${claim}`, + `another run (pid ${holder}) is using ${out}`, + `If no run is using it, delete ${claim}; otherwise pass --out a directory no run is using.`, ) + : holder > 0 + ? new Refusal( + `run.pid names pid ${holder}, which is not running`, + `if no run uses ${out}, delete ${claim}`, + ) + : new Refusal( + `run.pid in ${out} does not name a pid`, + `if no run uses ${out}, delete ${claim}`, + ) refusal.reportless = true return refusal } -/** The pid a claim names, or undefined when the claim is gone. */ +/** Read a claim that cannot be read (a directory, or no permission). */ +const UNREADABLE = `unreadable` +/** + * The pid a claim names: undefined when the claim is gone, UNREADABLE when it + * cannot be read at all, and NaN or 0 when its text names no pid. + */ function readHolder(claim) { try { return Number(readFileSync(claim, `utf8`)) } catch (error) { if (error.code === `ENOENT`) return undefined - throw cannotWrite(claim, error) + return UNREADABLE } } // The longest a test-only wait lasts before it fails the run loudly. @@ -332,7 +356,16 @@ function holdUntil() { function exitWhenFlushed(code) { process.stdout.write(``, () => process.stderr.write(``, () => { - holdUntil() + try { + holdUntil() + } catch (error) { + // A hold that never releases is a failed test: the run exits nonzero. + process.stderr.write( + `oracle-gaps: internal error, ${error.message}\n`, + () => process.exit(1), + ) + return + } process.exit(code) }), ) @@ -357,8 +390,6 @@ function superviseRun(out) { // of memory. let outOfMemory = false let stderrTail = `` - // The first error that the stream log raised after it was open, if any. - let logLost // Whether the run's streams and channel have closed. let closed = false // Ends the CLI once the run has ended (or the grace has passed), with what @@ -454,14 +485,13 @@ function superviseRun(out) { // for V8's out-of-memory message. child.stderr.on(`data`, (chunk) => { process.stderr.write(chunk) - // A log that cannot take the run's stderr is recorded once, and the relay - // goes on: the run's own ending stays the only done line on each stream. - if (logLost === undefined) - try { - appendLog(streamLog, chunk) - } catch (error) { - logLost = error - } + // A chunk the log cannot take is not written to it, and the relay goes on: the + // run's own ending stays the only done line on each stream. + try { + appendLog(streamLog, chunk) + } catch { + // The stream log cannot be written; stderr above has the chunk. + } stderrTail = (stderrTail + chunk).slice(-200) if (/heap out of memory/i.test(stderrTail)) outOfMemory = true }) @@ -490,8 +520,14 @@ function signalGroup(group, signal) { */ function watchSupervisor(supervisor) { // Only a process that leads its own group kills it: an inherited variable - // (a test's child, say) must not name a group this process does not lead. - if (groupOf(process.pid) !== process.pid) return + // (a test's child, say) must not name a group this process does not lead. A + // group that cannot be read fails the run: the watchdog would not be armed. + const group = groupOf(process.pid) + if (group === undefined) + throw new Error( + `the run cannot read its process group, so it cannot arm its supervisor watchdog`, + ) + if (group !== process.pid) return setInterval(() => { if (process.ppid !== supervisor) process.kill(-process.pid, `SIGKILL`) }, 1000).unref() @@ -622,7 +658,13 @@ async function run() { return superviseRun(checking.out) } } - if (supervisor !== undefined) watchSupervisor(Number(supervisor)) + if (supervisor !== undefined) { + try { + watchSupervisor(Number(supervisor)) + } catch (error) { + return endWith(error, options?.out) + } + } // A test that runs this CLI starts a run of its own, in a group of its own. delete process.env.ORACLE_GAPS_INTERNAL_SUPERVISED // A stop ends the run at once, with no line: an error that the stop causes diff --git a/packages/oracles/scripts/e2e-shards.mjs b/packages/oracles/scripts/e2e-shards.mjs index a273ce6e..913a3c2f 100644 --- a/packages/oracles/scripts/e2e-shards.mjs +++ b/packages/oracles/scripts/e2e-shards.mjs @@ -81,6 +81,7 @@ export const shards = { `fixed seed 20261105: two starts race for a stale claim`, `fixed seed 20261105: a start refuses a stale claim`, `fixed seed 20261105: a start refuses an empty claim`, + `fixed seed 20261105: a start refuses an unreadable claim`, `fixed seed 20261105: a stream log lost after its note, then stopped`, `fixed seed 20261105: a stream log lost after its note, then completed`, `fixed seed 20261105: a stop as the CLI starts`, @@ -119,6 +120,7 @@ export const shards = { `determinism: constructed history: two starts race for a stale claim`, `determinism: constructed history: a start refuses a stale claim`, `determinism: constructed history: a start refuses an empty claim`, + `determinism: constructed history: a start refuses an unreadable claim`, `determinism: constructed history: a stream log lost after its note, then stopped`, `determinism: constructed history: a stream log lost after its note, then completed`, `determinism: constructed history: a stop as the CLI starts`, @@ -159,6 +161,7 @@ export const shards = { `random seed: two starts race for a stale claim`, `random seed: a start refuses a stale claim`, `random seed: a start refuses an empty claim`, + `random seed: a start refuses an unreadable claim`, `random seed: a stream log lost after its note, then stopped`, `random seed: a stream log lost after its note, then completed`, `random seed: a stop as the CLI starts`, diff --git a/packages/oracles/scripts/pr-shards.mjs b/packages/oracles/scripts/pr-shards.mjs index 5dae4bae..8b9dae02 100644 --- a/packages/oracles/scripts/pr-shards.mjs +++ b/packages/oracles/scripts/pr-shards.mjs @@ -304,6 +304,7 @@ export const partitions = { 'two starts race for a stale claim', 'a start refuses a stale claim', 'a start refuses an empty claim', + 'a start refuses an unreadable claim', 'a stream log lost after its note, then stopped', 'a stream log lost after its note, then completed', ]), @@ -533,6 +534,7 @@ export const partitions = { 'two starts race for a stale claim', 'a start refuses a stale claim', 'a start refuses an empty claim', + 'a start refuses an unreadable claim', 'a stream log lost after its note, then stopped', 'a stream log lost after its note, then completed', 'a stop with the default output directory', From 3ecbba8a7a5c338c5536e332a60ef3ec9eb86ba5 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 21:50:55 -0700 Subject: [PATCH 30/62] fix(oracle-gaps): the mid-run check's stream check gets the run's log and results The merge brought main's mid-run observation, which copied only the run's exit, report and streams; the stream check (endsBreach) also reads the run's log, output directory and results, so it threw a TypeError in the fixed-seed shard 3 units through the daemon. Co-authored-by: Isaac --- .../oracles/oracle-gaps/gap-report-oracle.property.test.mjs | 6 ++++++ 1 file changed, 6 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 dd9a4276..27b87842 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1766,6 +1766,12 @@ async function incremental(dir, plan, cli, copy, observe, states) { report: midrunChecks.during.report, stream: midrunChecks.during.stream, stdoutStream: midrunChecks.during.stdoutStream, + // The stream check (endsBreach) judges the log, the output directory + // and the results of the run too. + log: midrunChecks.during.log, + outDir: midrunChecks.during.outDir, + reported: midrunChecks.during.reported, + reportState: midrunChecks.during.reportState, }, before: { exit: midrunChecks.before.exit, From 70928c11f26c015da3b18f964e5f1785dc325f94 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 21:57:49 -0700 Subject: [PATCH 31/62] fix(oracle-gaps): a mid-run run that refuses owes no note, as the cold run does Co-authored-by: Isaac --- .../oracles/oracle-gaps/gap-report-oracle.property.test.mjs | 4 +++- 1 file changed, 3 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 27b87842..d5865e0c 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -2983,7 +2983,9 @@ function check(plan, observations, expected) { ends.extra, ) // The check that a mid-run edit overlapped streams as any check does. - const duringEnds = value.midrun && endsBreach(value.midrun.during) + const duringEnds = + value.midrun && + endsBreach(value.midrun.during, { checked: owesNote(expected) }) if (duringEnds) return violation( `incremental`, From ffe88c715089273993e6c7750f22af0bb9f0bc10 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 22:23:23 -0700 Subject: [PATCH 32/62] fix(oracle-gaps): the overlap observation names the holding pid only as A second run's refusal names the first run's pid, which differs between two runs of the same history, so the determinism unit "two runs on one output directory" failed. The pid's place is observed, not its value. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-oracle.property.test.mjs | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index d5865e0c..7e34ff29 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1135,6 +1135,10 @@ async function unwritableLogRuns(dir, files, how, ending) { } } +/** A copy of `value` in which each refusal's pid is ``: a pid differs between runs. */ +const pidFree = (value) => + JSON.parse(JSON.stringify(value).replaceAll(/pid \d+/g, `pid `)) + async function overlappingRuns(dir, files, how) { writeFixture(dir, files) const before = new Set(filesUnder(dir)) @@ -1220,9 +1224,11 @@ async function overlappingRuns(dir, files, how) { cli: { ...ended, replay, strayWrites: strays(dir, before) }, overlap: { exit: refused.exit, - ending: refused.ending, - stream: refused.stream, - stdoutStream: refused.stdoutStream, + // The first run's pid is its own; the refusal names it, and a pid differs + // between two runs, so only the pid's place is observed. + ending: pidFree(refused.ending), + stream: pidFree(refused.stream), + stdoutStream: pidFree(refused.stdoutStream), }, } } From 9d71756d4eb8cb4bfd4438e0bef5ee8dcdfbfdf6 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 22:40:59 -0700 Subject: [PATCH 33/62] fix(oracle-gaps): a daemon refusal keeps the output directory it names The daemon sent a refusal's message, fix and stack but not the `out` that args.mjs attaches, and the client rebuilt the refusal without it. Its report then had no directory: write() returned false, so the done line lacked its report, and the outsideSource unit failed. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/daemon.mjs | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/packages/oracles/oracle-gaps/daemon.mjs b/packages/oracles/oracle-gaps/daemon.mjs index 6ea0215a..48fcb482 100644 --- a/packages/oracles/oracle-gaps/daemon.mjs +++ b/packages/oracles/oracle-gaps/daemon.mjs @@ -57,16 +57,19 @@ export { socketOf, stateDirOf } from './evidence.mjs' // An error that ended a check, as the daemon sends it, and as the CLI // receives it: a refusal stays a refusal. +// The `out` a refusal names (args.mjs) travels with it, so the client writes the +// refusal's report to the same directory the daemon's run would have. const sent = (error) => ({ message: String(error?.message ?? error), fix: error?.fix, stack: error?.stack, + out: error?.out, }) /** The error that ended a check in the daemon, to end the CLI's run with. */ -export const received = ({ message, fix, stack }) => +export const received = ({ message, fix, stack, out }) => Object.assign( fix === undefined ? new Error(message) : new Refusal(message, fix), - { stack }, + { stack, out }, ) function send(pkg, message) { From f2934fb7318aea0fd6efbf7353d4a882e31ec5f1 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 22:49:33 -0700 Subject: [PATCH 34/62] fix(oracle-gaps): every refusal names its run's output directory, default or not A run with no --out writes to the default directory of its package. A refusal raised while the arguments resolve (an outside source, say) carried no directory, so its report was never written, and law 12 failed (the outsideSource unit). The refusal now carries the directory the run would have used. RED: the outsideSource unit at 9d71756 (pool tags r57m-shard3, r57m-diag-outside). Co-authored-by: Isaac --- packages/oracles/oracle-gaps/args.mjs | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/packages/oracles/oracle-gaps/args.mjs b/packages/oracles/oracle-gaps/args.mjs index d8f7d02f..e48eb3cc 100644 --- a/packages/oracles/oracle-gaps/args.mjs +++ b/packages/oracles/oracle-gaps/args.mjs @@ -85,7 +85,9 @@ export function parseArgs(argv, cwd = process.cwd()) { if (problem) throw new Refusal(...problem) return optionsOf(args, cwd) } catch (error) { - if (error instanceof Refusal && args.out) error.out = resolve(cwd, args.out) + // Every refusal is written to its run's output directory (law 12): the one + // the arguments name, or the default one the run would have used. + if (error instanceof Refusal) error.out = outDirOf(args, cwd) throw error } } @@ -94,6 +96,17 @@ export function parseArgs(argv, cwd = process.cwd()) { * The options of parsed arguments `args`, or the refusal of the first that * breaks the usage text. */ +/** + * The output directory a run with `args` writes to: the `--out` it names, or, + * when it names none, the default directory of its package (optionsOf). A refusal + * that comes before the package is known has none. + */ +function outDirOf(args, cwd) { + if (args.out) return resolve(cwd, args.out) + if (!args.package || !existsSync(resolve(cwd, args.package))) return undefined + const pkg = realPathOf(resolve(cwd, args.package)) + return resolve(cwd, join(stateDirOf(pkg), `out`, runName())) +} function optionsOf(args, cwd) { if (args.help) return { help: true } if (!args.package) From 2724b2d0f7a35c1fcb8d59bf970c70583930ca6c Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 22:57:05 -0700 Subject: [PATCH 35/62] test(oracle-gaps): a default-directory refusal is judged on its shape, not its directory The cold refusal law required the report in the driver's --out, but a run with the default directory has none the driver knows: the CLI chooses it. The law now requires the directory only for an explicit --out. Co-authored-by: Isaac --- .../oracles/oracle-gaps/gap-report-oracle.property.test.mjs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 7e34ff29..59a3fe19 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -3045,9 +3045,12 @@ function check(plan, observations, expected) { // directory the run was given holds it. // Every e2e run names its output directory (`--out`), so even a // refusal of its arguments is written there. + // A run with the default output directory (`--out` left out) lets the CLI + // choose it, so the driver cannot name the directory: the refusal's shape is + // judged, and its directory where the driver knows it. const breach = refusalBreach(cli.ending, { cause: expected.refused.cause, - outKnown: true, + outKnown: plan.outMode === `explicit`, logNote: expected.refused.arguments ? undefined : logNoteOf(cli), }) if (breach) return violation(`cli`, breach, `report-shaped ending`) From 92d7ab0a66f9955a32c1d44c23511d8dd7f2703a Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 22:57:55 -0700 Subject: [PATCH 36/62] test(oracle-gaps): the daemon's refusal is judged on its directory as the cold one is Co-authored-by: Isaac --- .../oracle-gaps/gap-report-oracle.property.test.mjs | 10 ++++++---- 1 file changed, 6 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 59a3fe19..06f7da8b 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -2722,7 +2722,7 @@ async function driver(plan, observe) { * Law 9: each check through the daemon reports what the cold run of the same * state reports. A refused state is compared by the cause it names. */ -function incrementalCheck(observations, expected) { +function incrementalCheck(observations, expected, plan) { for (const { value } of observations.filter( (o) => o.checkpoint === `incremental`, )) { @@ -2811,8 +2811,10 @@ function incrementalCheck(observations, expected) { // A refusal through the daemon ends as a cold refusal does (law 12): // the CLI that asked the daemon writes it to its own output directory. if (cold.refusal !== undefined) { + // As the cold refusal: the driver knows the directory only for an explicit + // --out. const breach = refusalBreach(daemon.ending, { - outKnown: true, + outKnown: plan.outMode === `explicit`, logNote: owesNote(expected) ? logNoteOf(daemon) : undefined, }) if (breach) @@ -3063,7 +3065,7 @@ function check(plan, observations, expected) { `greppable stream`, ) return ( - incrementalCheck(observations, expected) ?? + incrementalCheck(observations, expected, plan) ?? daemonCheck(observations) ?? pass ) @@ -3335,7 +3337,7 @@ function check(plan, observations, expected) { ) } return ( - incrementalCheck(observations, expected) ?? + incrementalCheck(observations, expected, plan) ?? daemonCheck(observations) ?? pass ) From e39f0d2e1f67bc04d88a563cd37608b054f34b81 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 23:15:55 -0700 Subject: [PATCH 37/62] test(oracle-gaps): a default-directory refusal names the directory the default rule predicts The driver no longer skips the refusal's directory check for the default output mode: the report must sit in the default directory's shape, and a logged run's note must name the same directory. The explicit gate is gone. The default directory is normalized in observations, so the random run name does not make two runs differ. RED: the outsideSource unit at 92d7ab0 (the default-mode gate narrowed it). Co-authored-by: Isaac --- .../oracle-gaps/gap-report-model-oracle.mjs | 22 ++++++++++++++++++- .../gap-report-oracle.property.test.mjs | 20 +++++++++++------ 2 files changed, 34 insertions(+), 8 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index 163284c4..82031f7b 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -5861,7 +5861,7 @@ function endingOf(exit, stderr, out, name = (text) => text, stdout = ``) { * of 2026-11-12 that every run that starts a check names its stream log * first). */ -function refusalBreach(ending, { cause, outKnown, logNote }) { +function refusalBreach(ending, { cause, outKnown, defaultOut, logNote }) { if (ending.exit !== 2) return `the refusal exited ${ending.exit}, not 2` if (ending.stackFrames) return `the refusal printed a stack trace` if (ending.cause === undefined) @@ -5889,6 +5889,26 @@ function refusalBreach(ending, { cause, outKnown, logNote }) { if (JSON.stringify(ending.stdout) !== JSON.stringify(owedStdout)) return `the refusal's stdout is ${JSON.stringify(ending.stdout)}, not ${JSON.stringify(owedStdout)}` if (!outKnown) return undefined + if (defaultOut) { + // The CLI chose the directory (args.mjs, the default rule): the report is + // in `/oracle-gaps-/out/`, and a run that logged its + // note names the same directory. The rule's shape is judged here, not the + // directory's name. + const report = /^refused, report (.+)\/summary\.md$/.exec(ending.done)?.[1] + if ( + report === undefined || + !/(^|oracle-gaps-[^/\s]+\/out\/\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z-[0-9a-f]{8})$/.test( + report, + ) + ) + return `the refusal does not name its report in the default output directory: done ${ending.done}` + if ( + logNote !== undefined && + logNote !== `oracle-gaps: note log ${report}/stream.log` + ) + return `the refusal's report is not in the directory its stream log names: ${logNote}` + return undefined + } if (!ending.namesOutput) return `the refusal does not name its report in its output directory: done ${ending.done}` const { written } = ending 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 06f7da8b..f83b8ca5 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1297,7 +1297,13 @@ function namedScratch(text, names) { named = named.replaceAll(pathToFileURL(path).href, name) for (const spelling of spellings) named = named.replaceAll(spelling, name) } + // A run's default output directory is named by the default rule (a random run + // name), so it is normalized the same way. return named + .replaceAll( + /\S*oracle-gaps-[^/\s]+\/out\/\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z-[0-9a-f]{8}/g, + ``, + ) .replaceAll(/\.oracle-gaps-\d+/g, `.oracle-gaps-`) .replaceAll(/session-\d+/g, `session-`) } @@ -2811,10 +2817,10 @@ function incrementalCheck(observations, expected, plan) { // A refusal through the daemon ends as a cold refusal does (law 12): // the CLI that asked the daemon writes it to its own output directory. if (cold.refusal !== undefined) { - // As the cold refusal: the driver knows the directory only for an explicit - // --out. + // As the cold refusal: the default directory is predicted by its rule. const breach = refusalBreach(daemon.ending, { - outKnown: plan.outMode === `explicit`, + outKnown: true, + defaultOut: plan.outMode === `default`, logNote: owesNote(expected) ? logNoteOf(daemon) : undefined, }) if (breach) @@ -3047,12 +3053,12 @@ function check(plan, observations, expected) { // directory the run was given holds it. // Every e2e run names its output directory (`--out`), so even a // refusal of its arguments is written there. - // A run with the default output directory (`--out` left out) lets the CLI - // choose it, so the driver cannot name the directory: the refusal's shape is - // judged, and its directory where the driver knows it. + // A run with the default output directory (`--out` left out) has its + // directory predicted by the default rule, not named by the driver. const breach = refusalBreach(cli.ending, { cause: expected.refused.cause, - outKnown: plan.outMode === `explicit`, + outKnown: true, + defaultOut: plan.outMode === `default`, logNote: expected.refused.arguments ? undefined : logNoteOf(cli), }) if (breach) return violation(`cli`, breach, `report-shaped ending`) From ce6131d03831d2efb67203565a40ff679ab0ec09 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 23:22:25 -0700 Subject: [PATCH 38/62] test(oracle-gaps): a default run's report may be named by the scratch placeholder Co-authored-by: Isaac --- packages/oracles/oracle-gaps/gap-report-model-oracle.mjs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index 82031f7b..4364044e 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -5897,7 +5897,7 @@ function refusalBreach(ending, { cause, outKnown, defaultOut, logNote }) { const report = /^refused, report (.+)\/summary\.md$/.exec(ending.done)?.[1] if ( report === undefined || - !/(^|oracle-gaps-[^/\s]+\/out\/\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z-[0-9a-f]{8})$/.test( + !/(^|^|oracle-gaps-[^/\s]+\/out\/\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z-[0-9a-f]{8})$/.test( report, ) ) From a6e6761ca073ba2d2f3dab570c44c9deb42d8cae Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sat, 14 Nov 2026 23:51:54 -0700 Subject: [PATCH 39/62] test(oracle-gaps): the static oracle normalizes a default output directory's random name A refusal of the arguments now carries the directory its run would have used (args.mjs), so its ending names a random default directory. The static determinism units recorded that name, and two runs differed at the arguments observation (CI, Gap report oracles 2/3). Co-authored-by: Isaac --- .../gap-report-static-oracle.property.test.mjs | 10 +++++++++- 1 file changed, 9 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 082b1763..d6ec4ce3 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 @@ -514,7 +514,15 @@ function argumentsRunOf(dir, plan) { run.status, run.stderr, out, - (text) => text.replaceAll(dir, ``), + // A default output directory's name is random (a run name), so it is + // normalized as the package's directory is. + (text) => + text + .replaceAll(dir, ``) + .replaceAll( + /\S*oracle-gaps-[^/\s]+\/out\/\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z-[0-9a-f]{8}/g, + ``, + ), run.stdout, ), // A refusal of the arguments, or before a check starts, writes no stream From 0ef2144b8408693a1bc36d14f2db351c90603f32 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sun, 15 Nov 2026 00:32:25 -0700 Subject: [PATCH 40/62] fix(oracle-gaps): delta check: claim cause and fix, mid-list inserts, README, stray file - Claim write failures give the claim's own cause and fix (run.pid cannot be written), not the stream log's. - The driver judges a claim refusal's fix line exactly: the claim's directive, if no run uses , delete /run.pid. The reviewer's mutant (f775dff) printed the stream-log fix and now fails. - The eleven #57 constructed histories moved to the end of the list, so main's 26 names are an exact prefix in order: every existing index and seed keeps its history. - README: the diff3 marker and the stale HOLD_EXIT_MS paragraph are removed. - Removed the stray packages/oracles/.dbg4.tmp.mjs; a dangling JSDoc is fixed. Co-authored-by: Isaac --- README.md | 6 - packages/oracles/.dbg4.tmp.mjs | 4 - .../gap-report-oracle.property.test.mjs | 511 +++++++++--------- packages/oracles/oracle-gaps/index.mjs | 13 +- 4 files changed, 266 insertions(+), 268 deletions(-) delete mode 100644 packages/oracles/.dbg4.tmp.mjs diff --git a/README.md b/README.md index 4f64f277..7a64dd71 100644 --- a/README.md +++ b/README.md @@ -143,12 +143,6 @@ agent. its exit, and its output claim, until the file exists, so a test can send a stop or start a second run before the run ends. `ORACLE_GAPS_TEST_WARM_PROBE` makes the first config warm-up wait where a stop signal can reach it. - ||||||| 35422e3 - For contributors: two environment variables in the `ORACLE_GAPS_TEST_` - namespace are test-only hooks for the CLI's own oracle, not settings for - users. `ORACLE_GAPS_TEST_HOLD_EXIT_MS` holds the run's exit after its done - line, and `ORACLE_GAPS_TEST_WARM_PROBE` makes the first config warm-up - wait where a stop signal can reach it. `ORACLE_GAPS_TEST_TORN_ROWS` names a directory where each batch's watchdog counts its polls, and a batch's closing row is held half written until the watchdog has polled twice. The directory holds a `.begun` marker diff --git a/packages/oracles/.dbg4.tmp.mjs b/packages/oracles/.dbg4.tmp.mjs deleted file mode 100644 index 5410ed00..00000000 --- a/packages/oracles/.dbg4.tmp.mjs +++ /dev/null @@ -1,4 +0,0 @@ -import * as fc from 'fast-check' -const { drawn } = await import(process.argv[2]) -const keys = Object.keys(drawn.generator ? {} : {}) -console.log('ok', typeof drawn) 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 f83b8ca5..0c007006 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1050,8 +1050,9 @@ async function claimScenarioRuns(dir, files, how, scenario) { if (run.stdout.includes(`oracle-gaps: note log`)) return `claimed` const cause = run.stderr.match(/^refused: (.*)$/m)?.[1] if (cause === undefined || run.code !== 2) return `other` - const fix = run.stderr.match(/^fix: (.*)$/m)?.[1] ?? `` - return `refused (${namedScratch(cause, names)}; fix ${fix.includes(`run.pid`) ? `names the claim` : `does not name the claim`})` + // The fix line is judged exactly: the claim's directive, named by the run. + const fix = namedScratch(run.stderr.match(/^fix: (.*)$/m)?.[1] ?? ``, names) + return `refused (${namedScratch(cause, names)}; fix ${fix})` } return { scenario, @@ -2918,7 +2919,7 @@ function check(plan, observations, expected) { race: `run.pid names pid 999999, which is not running`, stale: `run.pid names pid 999999, which is not running`, }[claim.scenario] - const refused = `refused (${cause}; fix names the claim)` + const refused = `refused (${cause}; fix if no run uses , delete /run.pid)` const owed = claim.scenario === `race` ? [refused, refused] : [refused] if (JSON.stringify(claim.outcomes) !== JSON.stringify(owed)) return violation( @@ -4440,165 +4441,6 @@ oracleProperty({ consoleOutput: true, }), }, - { - // Without `--out`, the CLI picks the run's output directory - // (args.mjs). A run stopped while its config warms must still leave - // its stream log beside its results, with the done line last on both - // streams (law 15). The stop witness runs alone (witness `stop`), and a history - // with the witness module takes no steps. - name: `a stop with the default output directory`, - enters: [ - `a run with the default output directory`, - `a stop with the default output directory`, - ], - build: (generated) => ({ - ...generated, - functions: [[{ kind: `push`, quote: `'` }]], - containers: [], - overloads: [], - owners: [`a`], - library: [], - libraryOwners: [], - runes: [], - wholeFile: `none`, - witness: false, - stopWitness: true, - tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], - authored: null, - fault: `none`, - stability: `none`, - steps: null, - ordinary: false, - outMode: `default`, - budget: `two`, - stopRuns: [{ signal: `SIGINT`, pool: `threads`, when: `warm` }], - }), - }, - { - // Through the daemon, a check that the CLI parses without `--out` - // would write its results to a directory of its own, apart from the - // stream log the CLI names (law 15). - name: `a daemon check with the default output directory`, - enters: [ - `a run with the default output directory`, - `a daemon check with the default output directory`, - ], - build: (generated) => ({ - ...generated, - functions: [[{ kind: `push`, quote: `'` }]], - containers: [], - overloads: [], - owners: [`a`], - library: [], - libraryOwners: [], - runes: [], - wholeFile: `none`, - witness: false, - tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], - authored: null, - fault: `none`, - stability: `none`, - steps: [`test`], - ordinary: false, - outMode: `default`, - budget: `two`, - }), - }, - { - // A stop sent as the CLI spawns, before its note's run has started: - // the note is written first, and the stopped line follows it on both - // streams, with one done line (P1 of the review of #57). - name: `a stop as the CLI starts`, - enters: [`a stop as the CLI starts`], - build: (generated) => ({ - ...generated, - functions: [[{ kind: `push`, quote: `'` }]], - containers: [], - overloads: [], - owners: [`a`], - library: [], - libraryOwners: [], - runes: [], - wholeFile: `none`, - witness: false, - stopWitness: true, - tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], - authored: null, - fault: `none`, - stability: `none`, - steps: null, - ordinary: false, - outMode: `explicit`, - logBlocked: false, - overlap: false, - spawnStop: true, - // The signal waits for the CLI's started marker, so it lands during - // the loads of a CLI that loads before it installs its handlers. - spawnOnStart: true, - budget: `two`, - }), - }, - { - // A stream log that is a directory cannot be written: the CLI refuses - // before its first line (index.mjs opens the log first), with its - // block, its fix, and its report in the output directory, and its - // stdout is its done line alone (law 12, law 15, and F3 of the - // coordinator's review of #57). No stack trace, and exit 2 or 3. - name: `a stream log that cannot be written`, - enters: [`a stream log that cannot be written`], - build: (generated) => ({ - ...generated, - functions: [[{ kind: `push`, quote: `'` }]], - containers: [], - overloads: [], - owners: [`a`], - library: [], - libraryOwners: [], - runes: [], - wholeFile: `none`, - witness: false, - tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], - authored: null, - fault: `none`, - stability: `none`, - steps: null, - ordinary: false, - budget: `two`, - outMode: `explicit`, - logBlocked: true, - overlap: false, - }), - }, - { - // A second run on the first's output directory while the first is - // live refuses (F4, the coordinator's decision of 2026-11-13): the - // first run's stream log still equals its own stderr, line for line, - // and the refusal reports no directory it does not own. - name: `two runs on one output directory`, - enters: [`two runs on one output directory`], - build: (generated) => ({ - ...generated, - functions: [[{ kind: `push`, quote: `'` }]], - containers: [], - overloads: [], - owners: [`a`], - library: [], - libraryOwners: [], - runes: [], - wholeFile: `none`, - witness: false, - tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], - authored: null, - fault: `none`, - stability: `none`, - steps: null, - ordinary: false, - budget: `two`, - outMode: `explicit`, - logBlocked: false, - overlap: true, - }), - }, { // The budget witness checked through the daemon twice with nothing // changed between: the second check reuses the confirmations the @@ -5705,9 +5547,117 @@ oracleProperty({ }), }, { - // Two starts meet a dead pid's claim (the maintainer's decision, "Stale claims refuse; no takeover"): both refuse, each names the claim, and neither writes past its claim attempt. - name: `two starts race for a stale claim`, - enters: [`two starts race for a stale claim`], + // A batch's watchdog polls the capture while a worker appends its + // closing row. The hook holds each closing row half written until + // the watchdog has polled twice, so a poll reads a partial line by + // construction; the run must still complete and see every closing + // row (issue #83: a poll parsed the partial line and the CLI ended + // in an internal error). + name: `a capture row read while the worker wrote it`, + enters: [`a capture row read while the worker wrote it`], + build: (generated) => ({ + ...generated, + functions: [ + [{ kind: `push`, quote: `'` }], + [{ kind: `push`, quote: `'` }], + ], + containers: [], + overloads: [], + owners: [`a`, `b`], + 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 }, + ], + witness: false, + authored: null, + secondAuthored: false, + fault: `none`, + stability: `none`, + ordinary: false, + native: `none`, + boot: false, + budget: `two`, + cliPath: `plain`, + concurrentStart: false, + contexts: 1, + steps: null, + tornRows: true, + prePlugin: false, + configPlace: `discovered`, + configFile: `vite.config.mjs`, + config: `object`, + }), + }, + { + // The same witness with two concurrent batches (two contexts): a shared + // hold counter would release one batch's hold on the other's polls, so + // each batch must have its own (issue #83, review of #55). + name: `two batches each read a capture row while its worker wrote it`, + enters: [`a capture row read while the worker wrote it`], + build: (generated) => ({ + ...generated, + functions: [ + [{ kind: `if`, op: `>`, k: 4, not: false, quote: `'` }], + [{ kind: `if`, op: `>`, k: 4, not: false, quote: `'` }], + ], + containers: [], + overloads: [], + owners: [`a`, `b`], + 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 }, + ], + witness: false, + authored: null, + secondAuthored: false, + fault: `none`, + stability: `none`, + ordinary: false, + native: `none`, + boot: false, + budget: `two`, + cliPath: `plain`, + concurrentStart: false, + contexts: 4, + steps: null, + tornRows: true, + prePlugin: false, + configPlace: `discovered`, + configFile: `vite.config.mjs`, + config: `object`, + }), + }, + { + // Without `--out`, the CLI picks the run's output directory + // (args.mjs). A run stopped while its config warms must still leave + // its stream log beside its results, with the done line last on both + // streams (law 15). The stop witness runs alone (witness `stop`), and a history + // with the witness module takes no steps. + name: `a stop with the default output directory`, + enters: [ + `a run with the default output directory`, + `a stop with the default output directory`, + ], build: (generated) => ({ ...generated, functions: [[{ kind: `push`, quote: `'` }]], @@ -5719,23 +5669,90 @@ oracleProperty({ runes: [], wholeFile: `none`, witness: false, + stopWitness: true, tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], authored: null, fault: `none`, stability: `none`, steps: null, ordinary: false, + outMode: `default`, budget: `two`, + stopRuns: [{ signal: `SIGINT`, pool: `threads`, when: `warm` }], + }), + }, + { + // Through the daemon, a check that the CLI parses without `--out` + // would write its results to a directory of its own, apart from the + // stream log the CLI names (law 15). + name: `a daemon check with the default output directory`, + enters: [ + `a run with the default output directory`, + `a daemon check with the default output directory`, + ], + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], + wholeFile: `none`, + witness: false, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, + steps: [`test`], + ordinary: false, + outMode: `default`, + budget: `two`, + }), + }, + { + // A stop sent as the CLI spawns, before its note's run has started: + // the note is written first, and the stopped line follows it on both + // streams, with one done line (P1 of the review of #57). + name: `a stop as the CLI starts`, + enters: [`a stop as the CLI starts`], + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], + wholeFile: `none`, + witness: false, + stopWitness: true, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, + steps: null, + ordinary: false, outMode: `explicit`, logBlocked: false, overlap: false, - claimScenario: `race`, + spawnStop: true, + // The signal waits for the CLI's started marker, so it lands during + // the loads of a CLI that loads before it installs its handlers. + spawnOnStart: true, + budget: `two`, }), }, { - // One start meets a dead pid's claim: it refuses and names the claim and its fix. - name: `a start refuses a stale claim`, - enters: [`a start refuses a stale claim`], + // A stream log that is a directory cannot be written: the CLI refuses + // before its first line (index.mjs opens the log first), with its + // block, its fix, and its report in the output directory, and its + // stdout is its done line alone (law 12, law 15, and F3 of the + // coordinator's review of #57). No stack trace, and exit 2 or 3. + name: `a stream log that cannot be written`, + enters: [`a stream log that cannot be written`], build: (generated) => ({ ...generated, functions: [[{ kind: `push`, quote: `'` }]], @@ -5755,15 +5772,17 @@ oracleProperty({ ordinary: false, budget: `two`, outMode: `explicit`, - logBlocked: false, + logBlocked: true, overlap: false, - claimScenario: `stale`, }), }, { - // One start meets an empty claim: it refuses, and the claim is never taken over. - name: `a start refuses an empty claim`, - enters: [`a start refuses an empty claim`], + // A second run on the first's output directory while the first is + // live refuses (F4, the coordinator's decision of 2026-11-13): the + // first run's stream log still equals its own stderr, line for line, + // and the refusal reports no directory it does not own. + name: `two runs on one output directory`, + enters: [`two runs on one output directory`], build: (generated) => ({ ...generated, functions: [[{ kind: `push`, quote: `'` }]], @@ -5784,14 +5803,13 @@ oracleProperty({ budget: `two`, outMode: `explicit`, logBlocked: false, - overlap: false, - claimScenario: `empty`, + overlap: true, }), }, { - // The stream log becomes a directory after the note, then the run is stopped: one done line on each stream, the exit code it owes, and no stack. - name: `a stream log lost after its note, then stopped`, - enters: [`a stream log lost after its note, then stopped`], + // Two starts meet a dead pid's claim (the maintainer's decision, "Stale claims refuse; no takeover"): both refuse, each names the claim, and neither writes past its claim attempt. + name: `two starts race for a stale claim`, + enters: [`two starts race for a stale claim`], build: (generated) => ({ ...generated, functions: [[{ kind: `push`, quote: `'` }]], @@ -5813,13 +5831,13 @@ oracleProperty({ outMode: `explicit`, logBlocked: false, overlap: false, - logLost: `stop`, + claimScenario: `race`, }), }, { - // The stream log becomes a directory after the note, and the run completes: the same law as the stop. - name: `a stream log lost after its note, then completed`, - enters: [`a stream log lost after its note, then completed`], + // One start meets a dead pid's claim: it refuses and names the claim and its fix. + name: `a start refuses a stale claim`, + enters: [`a start refuses a stale claim`], build: (generated) => ({ ...generated, functions: [[{ kind: `push`, quote: `'` }]], @@ -5841,14 +5859,13 @@ oracleProperty({ outMode: `explicit`, logBlocked: false, overlap: false, - logLost: `complete`, + claimScenario: `stale`, }), }, { - // An unreadable claim (a directory where run.pid should be) cannot be read - // at all: its start refuses, and names the claim as unreadable. - name: `a start refuses an unreadable claim`, - enters: [`a start refuses an unreadable claim`], + // One start meets an empty claim: it refuses, and the claim is never taken over. + name: `a start refuses an empty claim`, + enters: [`a start refuses an empty claim`], build: (generated) => ({ ...generated, functions: [[{ kind: `push`, quote: `'` }]], @@ -5870,108 +5887,92 @@ oracleProperty({ outMode: `explicit`, logBlocked: false, overlap: false, - claimScenario: `unreadable`, + claimScenario: `empty`, }), }, { - // A batch's watchdog polls the capture while a worker appends its - // closing row. The hook holds each closing row half written until - // the watchdog has polled twice, so a poll reads a partial line by - // construction; the run must still complete and see every closing - // row (issue #83: a poll parsed the partial line and the CLI ended - // in an internal error). - name: `a capture row read while the worker wrote it`, - enters: [`a capture row read while the worker wrote it`], + // The stream log becomes a directory after the note, then the run is stopped: one done line on each stream, the exit code it owes, and no stack. + name: `a stream log lost after its note, then stopped`, + enters: [`a stream log lost after its note, then stopped`], build: (generated) => ({ ...generated, - functions: [ - [{ kind: `push`, quote: `'` }], - [{ kind: `push`, quote: `'` }], - ], + functions: [[{ kind: `push`, quote: `'` }]], containers: [], overloads: [], - owners: [`a`, `b`], + owners: [`a`], 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 }, - ], witness: false, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], authored: null, - secondAuthored: false, fault: `none`, stability: `none`, + steps: null, ordinary: false, - native: `none`, - boot: false, budget: `two`, - cliPath: `plain`, - concurrentStart: false, - contexts: 1, - steps: null, - tornRows: true, - prePlugin: false, - configPlace: `discovered`, - configFile: `vite.config.mjs`, - config: `object`, + outMode: `explicit`, + logBlocked: false, + overlap: false, + logLost: `stop`, }), }, { - // The same witness with two concurrent batches (two contexts): a shared - // hold counter would release one batch's hold on the other's polls, so - // each batch must have its own (issue #83, review of #55). - name: `two batches each read a capture row while its worker wrote it`, - enters: [`a capture row read while the worker wrote it`], + // The stream log becomes a directory after the note, and the run completes: the same law as the stop. + name: `a stream log lost after its note, then completed`, + enters: [`a stream log lost after its note, then completed`], build: (generated) => ({ ...generated, - functions: [ - [{ kind: `if`, op: `>`, k: 4, not: false, quote: `'` }], - [{ kind: `if`, op: `>`, k: 4, not: false, quote: `'` }], - ], + functions: [[{ kind: `push`, quote: `'` }]], containers: [], overloads: [], - owners: [`a`, `b`], + owners: [`a`], 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 }, - ], witness: false, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], authored: null, - secondAuthored: false, fault: `none`, stability: `none`, + steps: null, ordinary: false, - native: `none`, - boot: false, budget: `two`, - cliPath: `plain`, - concurrentStart: false, - contexts: 4, + outMode: `explicit`, + logBlocked: false, + overlap: false, + logLost: `complete`, + }), + }, + { + // An unreadable claim (a directory where run.pid should be) cannot be read + // at all: its start refuses, and names the claim as unreadable. + name: `a start refuses an unreadable claim`, + enters: [`a start refuses an unreadable claim`], + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], + wholeFile: `none`, + witness: false, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, steps: null, - tornRows: true, - prePlugin: false, - configPlace: `discovered`, - configFile: `vite.config.mjs`, - config: `object`, + ordinary: false, + budget: `two`, + outMode: `explicit`, + logBlocked: false, + overlap: false, + claimScenario: `unreadable`, }), }, ]), diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index cff2fb19..7d6fa4c1 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -173,7 +173,6 @@ const STOP_GRACE_MS = 2000 let streamLog let writingEnding = false const logPathOf = (out) => join(out, `stream.log`) -/** Writes `text` to stderr and, once the log is open, to the stream log. */ /** Appends `text` to the stream log at `path`; a failure is the refusal that ends the run. */ const appendLog = (path, text) => { try { @@ -182,6 +181,7 @@ const appendLog = (path, text) => { throw cannotWrite(path, error) } } +/** Writes `text` to stderr and, once the log is open, to the stream log. */ const writeStream = (text) => { process.stderr.write(text) if (streamLog) appendLog(streamLog, text) @@ -227,7 +227,7 @@ function claimOut(out) { mkdirSync(out, { recursive: true }) writeFileSync(temp, `${process.pid}\n`) } catch (error) { - throw cannotWrite(claim, error) + throw claimCannotWrite(out, claim, error) } try { // A claim that vanishes between the link and the read was released by a run @@ -238,7 +238,7 @@ function claimOut(out) { claimed = claim return } catch (error) { - if (error.code !== `EEXIST`) throw cannotWrite(claim, error) + if (error.code !== `EEXIST`) throw claimCannotWrite(out, claim, error) const holder = readHolder(claim) if (holder === undefined && attempt < 3) continue if (holder === undefined) @@ -253,6 +253,13 @@ function claimOut(out) { rmSync(temp, { force: true }) } } +/** The refusal for a `run.pid` that cannot be written: the claim's own cause. */ +function claimCannotWrite(out, claim, error) { + return new Refusal( + `run.pid in ${out} cannot be written (${error.code ?? error.message})`, + `if no run uses ${out}, delete ${claim}, or pass --out a directory whose run.pid can be written`, + ) +} /** The refusal for a `run.pid` that holds its directory or cannot be read. */ function heldRefusal(out, claim, holder) { const refusal = From d9d34dd0b519b28a6ddc98f1346e1c2bd27db27b Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sun, 15 Nov 2026 01:22:33 -0700 Subject: [PATCH 41/62] test(oracle-gaps): the supervised child exits when its supervisor is killed; a hold the CLI cannot release is marked - The supervisor records its child's pid beside the started marker, and a test that SIGKILLs the supervisor requires the child to be gone within 5 s (the child's watchdog, one tick). POSIX only: win32 has no supervisor until #79 (platform-scoped reach). The supervisor's own claim is left as SIGKILL leaves it, a stale claim, which the next run refuses. - A hold that never releases writes a .unreleased marker beside the hold file; the CLI keeps the exit its done line stated, and the driver throws when the marker exists (a test-only hook: the failure belongs to the test). Co-authored-by: Isaac --- .../oracle-gaps/gap-report-model-oracle.mjs | 15 ++- .../gap-report-oracle.property.test.mjs | 106 ++++++++++++++++++ packages/oracles/oracle-gaps/index.mjs | 28 +++-- packages/oracles/scripts/e2e-shards.mjs | 3 + packages/oracles/scripts/pr-shards.mjs | 2 + 5 files changed, 141 insertions(+), 13 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index 4364044e..83026e30 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -913,6 +913,9 @@ const drawn = fc.record({ // A stream log that becomes a directory right after the note (review of #57, // F1): constructed only, and taken back as the constant false. logLost: fc.constant(false), + // A supervised check whose supervisor is killed (POSIX; review of #57, F7): + // constructed only, and taken back as the constant false. + supervisorDeath: fc.constant(false), }) // The edit sequence over the witness module, the one list of steps that a @@ -973,9 +976,16 @@ const histories = drawn.map( if (!keepsSteps(history)) throw new Error(`a history with the witness module takes no steps`) const reset = - history.claimScenario === false && history.logLost === false + history.claimScenario === false && + history.logLost === false && + history.supervisorDeath === false ? value - : { ...history, claimScenario: false, logLost: false } + : { + ...history, + claimScenario: false, + logLost: false, + supervisorDeath: false, + } const taken = reset.tornRows === false ? reset : { ...reset, tornRows: false } const later = (history.steps ?? []).filter((step) => @@ -3055,6 +3065,7 @@ function resolveHistory(history) { // coordinator's decision on the claim rules). claimScenario: history.claimScenario ?? false, logLost: history.logLost ?? false, + supervisorDeath: history.supervisorDeath ?? false, spawnOnStart: history.spawnOnStart === true, onlyRun: history.onlyRun === true, pragma: history.pragma === true, 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 0c007006..6711fbc2 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -841,8 +841,12 @@ async function stoppedRun( if (!abort) child.kill(signal) // The `after` stop is sent while the exit is held; the hold is released now. if (after) writeFileSync(join(pids, `after-release`), ``) + // The hold beside the release file is marked when the CLI could not release it. + const unreleased = join(pids, `after-release.unreleased`) const ended = await Promise.race([exit, sleep(30_000).then(() => false)]) await sleep(1000) + if (existsSync(unreleased)) + throw new Error(`the stop's hold was never released`) const alive = readdirSync(pids) .filter((name) => /^\d+$/.test(name)) .map(Number) @@ -1140,6 +1144,61 @@ async function unwritableLogRuns(dir, files, how, ending) { const pidFree = (value) => JSON.parse(JSON.stringify(value).replaceAll(/pid \d+/g, `pid `)) +/** + * Runs a supervised check and SIGKILLs its supervisor once the child is running + * (the child's pid is read from the started marker's `.child` file). The child's + * watchdog (index.mjs) ends its group within a tick of losing its supervisor, so + * the child must be gone within 5 s. The supervisor's own claim is left as a + * SIGKILL leaves it: a stale claim, which the next run refuses (the stale-claim + * histories). POSIX only: win32 has no supervisor until #79 (platform-scoped reach). + */ +async function supervisorDeathRuns(dir, files, how) { + const { args } = cliArgs(dir, files, { ...how, outName: `out-death` }) + const started = join(dir, `death-started`) + const supervisor = spawn(process.execPath, args, { + cwd: repo, + env: { ...cleanEnv(), ORACLE_GAPS_TEST_STARTED: started }, + stdio: [`ignore`, `pipe`, `pipe`], + }) + let hasEnded = false + const exited = new Promise((resolvePromise) => { + supervisor.on(`close`, (code, signal) => { + hasEnded = true + resolvePromise({ code, signal }) + }) + }) + const timer = setTimeout(() => supervisor.kill(`SIGKILL`), 60_000) + try { + for ( + let waited = 0; + !existsSync(`${started}.child`) && !hasEnded; + waited += 1 + ) { + if (waited > 3000) + throw new Error(`the supervisor never started its child`) + await sleep(10) + } + if (!existsSync(`${started}.child`)) + return { childGone: true, supervisorSignal: undefined, ended: true } + const childPid = Number(readFileSync(`${started}.child`, `utf8`)) + supervisor.kill(`SIGKILL`) + const { signal } = await exited + let childGone = false + for (let waited = 0; waited < 5000; waited += 50) { + try { + process.kill(childPid, 0) + } catch { + childGone = true + break + } + await sleep(50) + } + return { childGone, supervisorSignal: signal, ended: false } + } finally { + clearTimeout(timer) + } +} + async function overlappingRuns(dir, files, how) { writeFixture(dir, files) const before = new Set(filesUnder(dir)) @@ -1201,6 +1260,9 @@ async function overlappingRuns(dir, files, how) { const secondStatus = await second.status writeFileSync(releaseFile, ``) const firstStatus = await first.status + // A hold the CLI could not release is a driver fault, not an ending. + if (existsSync(`${releaseFile}.unreleased`)) + throw new Error(`the overlap hold was never released`) const ended = readRun( dir, out, @@ -2226,6 +2288,10 @@ async function driver(plan, observe) { observe(`claimScenario`, claim) states.add(claimStateOf[claim.scenario]) } + if (plan.supervisorDeath && process.platform !== `win32`) { + observe(`supervisorDeath`, await supervisorDeathRuns(dir, files, how)) + states.add(`a supervised child exits when its supervisor is killed`) + } if (plan.logLost) { observe( `unwritableLog`, @@ -2934,6 +3000,15 @@ function check(plan, observations, expected) { `ownership`, ) } + const death = observations.find( + (o) => o.checkpoint === `supervisorDeath`, + )?.value + if (death !== undefined && !death.childGone) + return violation( + `supervisorDeath`, + `the supervised child outlived its supervisor, which was killed with SIGKILL`, + `output namespace`, + ) const lost = observations.find((o) => o.checkpoint === `unwritableLog`)?.value if (lost !== undefined) { // The stream log became a directory after the note. Whatever ends the run, @@ -4107,6 +4182,7 @@ const required = [ `a start refuses a stale claim`, `a start refuses an empty claim`, `a start refuses an unreadable claim`, + `a supervised child exits when its supervisor is killed`, `a stream log lost after its note, then stopped`, `a stream log lost after its note, then completed`, `a stop as the CLI starts`, @@ -4290,6 +4366,7 @@ const ownHistoryStates = [ `a start refuses a stale claim`, `a start refuses an empty claim`, `a start refuses an unreadable claim`, + `a supervised child exits when its supervisor is killed`, `a stream log lost after its note, then stopped`, `a stream log lost after its note, then completed`, `a stop as the CLI starts`, @@ -5975,6 +6052,35 @@ oracleProperty({ claimScenario: `unreadable`, }), }, + { + // A supervised check whose supervisor is killed with SIGKILL: its child exits + // within the watchdog's tick, so no run's process outlives its CLI (POSIX). + name: `a supervised child exits when its supervisor is killed`, + enters: [`a supervised child exits when its supervisor is killed`], + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], + wholeFile: `none`, + witness: false, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, + steps: null, + ordinary: false, + budget: `two`, + outMode: `explicit`, + logBlocked: false, + overlap: false, + supervisorDeath: true, + }), + }, ]), }, resolve: resolveHistory, diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index 7d6fa4c1..c5ecfcfa 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -356,23 +356,22 @@ function startLog(out) { * releases it once the overlapping run or the stop it sent has been observed, so * the outcome does not depend on wall-clock timing. Inert unless set. */ +// A hold that never releases is a driver fault. The run keeps the exit code its +// done line already stated: the streams stay as the done line left them, and the +// failure is the driver's, through the `.unreleased` marker beside the hold file. function holdUntil() { const file = process.env.ORACLE_GAPS_TEST_HOLD_UNTIL - if (file !== undefined) waitForFile(file, `the hold`) + if (file === undefined) return + try { + waitForFile(file, `the hold`) + } catch { + writeFileSync(`${file}.unreleased`, ``) + } } function exitWhenFlushed(code) { process.stdout.write(``, () => process.stderr.write(``, () => { - try { - holdUntil() - } catch (error) { - // A hold that never releases is a failed test: the run exits nonzero. - process.stderr.write( - `oracle-gaps: internal error, ${error.message}\n`, - () => process.exit(1), - ) - return - } + holdUntil() process.exit(code) }), ) @@ -484,6 +483,13 @@ function superviseRun(out) { }, }, ) + // A test that kills this supervisor reads the child's pid beside the started + // marker (ORACLE_GAPS_TEST_STARTED), to see the child exit (the watchdog). + if (process.env.ORACLE_GAPS_TEST_STARTED !== undefined) + writeFileSync( + `${process.env.ORACLE_GAPS_TEST_STARTED}.child`, + `${child.pid}\n`, + ) child.on(`message`, (message) => { if (message === `ending`) ending = true }) diff --git a/packages/oracles/scripts/e2e-shards.mjs b/packages/oracles/scripts/e2e-shards.mjs index 8855f846..f67544d6 100644 --- a/packages/oracles/scripts/e2e-shards.mjs +++ b/packages/oracles/scripts/e2e-shards.mjs @@ -119,6 +119,7 @@ export const shards = { `fixed seed 20261105: a start refuses a stale claim`, `fixed seed 20261105: a start refuses an empty claim`, `fixed seed 20261105: a start refuses an unreadable claim`, + `fixed seed 20261105: a supervised child exits when its supervisor is killed`, `fixed seed 20261105: a stream log lost after its note, then stopped`, `fixed seed 20261105: a stream log lost after its note, then completed`, `fixed seed 20261105: a stop as the CLI starts`, @@ -158,6 +159,7 @@ export const shards = { `determinism: constructed history: a start refuses a stale claim`, `determinism: constructed history: a start refuses an empty claim`, `determinism: constructed history: a start refuses an unreadable claim`, + `determinism: constructed history: a supervised child exits when its supervisor is killed`, `determinism: constructed history: a stream log lost after its note, then stopped`, `determinism: constructed history: a stream log lost after its note, then completed`, `determinism: constructed history: a stop as the CLI starts`, @@ -199,6 +201,7 @@ export const shards = { `random seed: a start refuses a stale claim`, `random seed: a start refuses an empty claim`, `random seed: a start refuses an unreadable claim`, + `random seed: a supervised child exits when its supervisor is killed`, `random seed: a stream log lost after its note, then stopped`, `random seed: a stream log lost after its note, then completed`, `random seed: a stop as the CLI starts`, diff --git a/packages/oracles/scripts/pr-shards.mjs b/packages/oracles/scripts/pr-shards.mjs index d947d88b..3de286ba 100644 --- a/packages/oracles/scripts/pr-shards.mjs +++ b/packages/oracles/scripts/pr-shards.mjs @@ -305,6 +305,7 @@ export const partitions = { 'a start refuses a stale claim', 'a start refuses an empty claim', 'a start refuses an unreadable claim', + 'a supervised child exits when its supervisor is killed', 'a stream log lost after its note, then stopped', 'a stream log lost after its note, then completed', ]), @@ -535,6 +536,7 @@ export const partitions = { 'a start refuses a stale claim', 'a start refuses an empty claim', 'a start refuses an unreadable claim', + 'a supervised child exits when its supervisor is killed', 'a stream log lost after its note, then stopped', 'a stream log lost after its note, then completed', 'a stop with the default output directory', From 7772ec3c1a71ad7811263fcd5e6938ff9b52db08 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sun, 15 Nov 2026 01:26:20 -0700 Subject: [PATCH 42/62] test(oracle-gaps): the death witness waits for a silent child, so only the watchdog can end it The supervised child pauses before it writes anything (testPause child), with its watchdog armed. The driver kills the supervisor once the child is paused. A child that writes would die of a broken pipe, which would hide the watchdog. Co-authored-by: Isaac --- .../gap-report-oracle.property.test.mjs | 26 ++++++++++++------- packages/oracles/oracle-gaps/index.mjs | 3 +++ 2 files changed, 20 insertions(+), 9 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 6711fbc2..9073f4d2 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1155,9 +1155,19 @@ const pidFree = (value) => async function supervisorDeathRuns(dir, files, how) { const { args } = cliArgs(dir, files, { ...how, outName: `out-death` }) const started = join(dir, `death-started`) + const paused = join(dir, `child-paused`) + const release = join(dir, `child-release`) const supervisor = spawn(process.execPath, args, { cwd: repo, - env: { ...cleanEnv(), ORACLE_GAPS_TEST_STARTED: started }, + env: { + ...cleanEnv(), + ORACLE_GAPS_TEST_STARTED: started, + // The child pauses silently, before its check, with its watchdog armed; the + // driver releases it last. + ORACLE_GAPS_TEST_PAUSE_AT: `child`, + ORACLE_GAPS_TEST_PAUSE_MARKER: paused, + ORACLE_GAPS_TEST_PAUSE_UNTIL: release, + }, stdio: [`ignore`, `pipe`, `pipe`], }) let hasEnded = false @@ -1169,16 +1179,11 @@ async function supervisorDeathRuns(dir, files, how) { }) const timer = setTimeout(() => supervisor.kill(`SIGKILL`), 60_000) try { - for ( - let waited = 0; - !existsSync(`${started}.child`) && !hasEnded; - waited += 1 - ) { - if (waited > 3000) - throw new Error(`the supervisor never started its child`) + for (let waited = 0; !existsSync(paused) && !hasEnded; waited += 1) { + if (waited > 3000) throw new Error(`the supervised child never paused`) await sleep(10) } - if (!existsSync(`${started}.child`)) + if (!existsSync(paused)) return { childGone: true, supervisorSignal: undefined, ended: true } const childPid = Number(readFileSync(`${started}.child`, `utf8`)) supervisor.kill(`SIGKILL`) @@ -1196,6 +1201,9 @@ async function supervisorDeathRuns(dir, files, how) { return { childGone, supervisorSignal: signal, ended: false } } finally { clearTimeout(timer) + // Released last: a child the watchdog did not end then runs on and ends + // through its own pause, so the run leaves no process behind. + writeFileSync(release, ``) } } diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index c5ecfcfa..04930a0b 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -677,6 +677,9 @@ async function run() { } catch (error) { return endWith(error, options?.out) } + // A supervised child waits here, before it writes anything, so a test can + // kill its supervisor while the child is silent (the watchdog's own case). + testPause(`child`) } // A test that runs this CLI starts a run of its own, in a group of its own. delete process.env.ORACLE_GAPS_INTERNAL_SUPERVISED From 7f935ecbe2efd23fa59ab49c91255f79f9862ac2 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sun, 15 Nov 2026 01:38:22 -0700 Subject: [PATCH 43/62] fix(oracle-gaps): the death witness measures the child, and a held child keeps its watchdog running The driver waited for the supervisor's `close` event, which fires only after the child (which inherits the supervisor's stdout pipe) has ended, so the 5 s check ran after the child's own 60 s hold had ended it. The witness passed without the watchdog. The child's pause was also a synchronous wait, which stopped the watchdog's timer, so the watchdog could never end a held child. The driver now waits for `exit`, checks the recorded child pid within 5 s, and kills that pid when the check fails. A supervisor that ends before its child pauses fails the witness. The child's hold at `child` polls on timers. Co-authored-by: Isaac --- .../gap-report-oracle.property.test.mjs | 27 +++++++++++++----- packages/oracles/oracle-gaps/index.mjs | 28 ++++++++++++++++--- 2 files changed, 44 insertions(+), 11 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 9073f4d2..1df5ed61 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1170,25 +1170,31 @@ async function supervisorDeathRuns(dir, files, how) { }, stdio: [`ignore`, `pipe`, `pipe`], }) + // `exit`, not `close`: the child inherits the supervisor's stdout pipe, so + // `close` waits until the child itself has ended, which would make the 5 s + // check below measure a child that had already gone. let hasEnded = false const exited = new Promise((resolvePromise) => { - supervisor.on(`close`, (code, signal) => { + supervisor.on(`exit`, (code, signal) => { hasEnded = true resolvePromise({ code, signal }) }) }) + let childPid + let childGone = false const timer = setTimeout(() => supervisor.kill(`SIGKILL`), 60_000) try { for (let waited = 0; !existsSync(paused) && !hasEnded; waited += 1) { if (waited > 3000) throw new Error(`the supervised child never paused`) await sleep(10) } + // A supervisor that ended before its child paused proves nothing about the + // watchdog, so the witness fails rather than passing. if (!existsSync(paused)) - return { childGone: true, supervisorSignal: undefined, ended: true } - const childPid = Number(readFileSync(`${started}.child`, `utf8`)) + throw new Error(`the supervisor ended before its child paused`) + childPid = Number(readFileSync(`${started}.child`, `utf8`)) supervisor.kill(`SIGKILL`) const { signal } = await exited - let childGone = false for (let waited = 0; waited < 5000; waited += 50) { try { process.kill(childPid, 0) @@ -1198,11 +1204,18 @@ async function supervisorDeathRuns(dir, files, how) { } await sleep(50) } - return { childGone, supervisorSignal: signal, ended: false } + return { childGone, supervisorSignal: signal } } finally { clearTimeout(timer) - // Released last: a child the watchdog did not end then runs on and ends - // through its own pause, so the run leaves no process behind. + // A child the watchdog did not end is still ours (its pid is recorded), so + // the run leaves no process behind. + if (childPid !== undefined && !childGone) + try { + process.kill(childPid, `SIGKILL`) + } catch { + // It ended on its own in the meantime. + } + // Released last, for the child's own pause. writeFileSync(release, ``) } } diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index 04930a0b..cfc8f8fb 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -308,11 +308,31 @@ const TEST_WAIT_LIMIT_MS = 60_000 * other runs against it and releases it. Inert unless set (register: test hooks). */ function testPause(point) { - if (process.env.ORACLE_GAPS_TEST_PAUSE_AT !== point) return + const until = enterTestPause(point) + if (until !== undefined) waitForFile(until, `the pause at ${point}`) +} +/** + * The same hold for the supervised child, which must keep its event loop + * running: its orphan watchdog is a timer, and a synchronous wait would stop it, + * so the child could never end itself while held. + */ +async function testPauseOnTimers(point) { + const until = enterTestPause(point) + if (until === undefined) return + for (let waited = 0; !existsSync(until); waited += 20) { + if (waited >= TEST_WAIT_LIMIT_MS) + throw new Error( + `the pause at ${point} was not released within ${TEST_WAIT_LIMIT_MS} ms`, + ) + await new Promise((resolve) => setTimeout(resolve, 20)) + } +} +/** Writes the marker of the hold at `point`; returns its release file, when the point is held. */ +function enterTestPause(point) { + if (process.env.ORACLE_GAPS_TEST_PAUSE_AT !== point) return undefined const marker = process.env.ORACLE_GAPS_TEST_PAUSE_MARKER if (marker !== undefined) writeFileSync(marker, ``) - const until = process.env.ORACLE_GAPS_TEST_PAUSE_UNTIL - if (until !== undefined) waitForFile(until, `the pause at ${point}`) + return process.env.ORACLE_GAPS_TEST_PAUSE_UNTIL } /** Waits for `file` for at most TEST_WAIT_LIMIT_MS, then throws. */ function waitForFile(file, what) { @@ -679,7 +699,7 @@ async function run() { } // A supervised child waits here, before it writes anything, so a test can // kill its supervisor while the child is silent (the watchdog's own case). - testPause(`child`) + await testPauseOnTimers(`child`) } // A test that runs this CLI starts a run of its own, in a group of its own. delete process.env.ORACLE_GAPS_INTERNAL_SUPERVISED From 789301c5bcb733bd98c6fda41131a6b33328b6f8 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sun, 15 Nov 2026 01:55:40 -0700 Subject: [PATCH 44/62] docs(oracle-gaps): the supervisor death witness names its platform scope win32 has no supervisor until #79, so the death state is not reached there and the law has no observation to judge. Comment only. Co-authored-by: Isaac --- .../oracles/oracle-gaps/gap-report-oracle.property.test.mjs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index b71693cf..0a631114 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -2439,6 +2439,9 @@ async function driver(plan, observe) { observe(`claimScenario`, claim) states.add(claimStateOf[claim.scenario]) } + // Platform-scoped reach: win32 has no supervisor until #79, so the state is + // not reached there, and the law has no observation to judge. The reason is + // recorded in the PR's Limits. if (plan.supervisorDeath && process.platform !== `win32`) { observe(`supervisorDeath`, await supervisorDeathRuns(dir, files, how)) states.add(`a supervised child exits when its supervisor is killed`) From 8120cb80e54f352990d2bd4797a956ef517658ef Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sun, 15 Nov 2026 07:42:28 -0700 Subject: [PATCH 45/62] fix(oracle-gaps): progress durations are not compared; the supervisor death law is stopping A progress line's wall-clock duration ("in 0.2s") is live progress, not outcome, so the shared stream normalizer names it ``. Every other field stays. The supervisor death violation is tagged with the stopping law, not output namespace. Co-authored-by: Isaac --- .../gap-report-oracle.property.test.mjs | 24 ++++++++++++------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 0a631114..b5fdb2fd 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1406,13 +1406,21 @@ function namedScratch(text, names) { .replaceAll(posix(path), name) // A run's default output directory is named by the default rule (a random run // name), so it is normalized the same way. - return named - .replaceAll( - /\S*oracle-gaps-[^/\s]+\/out\/\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z-[0-9a-f]{8}/g, - ``, - ) - .replaceAll(/\.oracle-gaps-\d+/g, `.oracle-gaps-`) - .replaceAll(/session-\d+/g, `session-`) + return ( + named + .replaceAll( + /\S*oracle-gaps-[^/\s]+\/out\/\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z-[0-9a-f]{8}/g, + ``, + ) + .replaceAll(/\.oracle-gaps-\d+/g, `.oracle-gaps-`) + .replaceAll(/session-\d+/g, `session-`) + // A progress line's wall-clock durations ("in 0.2s") are live progress, not + // outcome: results.json is the stable record (register: heartbeats are + // progress). Every other field of the line stays. + .replaceAll(/oracle-gaps: progress [^\\\n"]*/g, (line) => + line.replaceAll(/\b\d+(?:\.\d+)?s\b/g, ``), + ) + ) } /** What one run of the CLI reported, from its exit status and its files. */ @@ -3161,7 +3169,7 @@ function check(plan, observations, expected) { return violation( `supervisorDeath`, `the supervised child outlived its supervisor, which was killed with SIGKILL`, - `output namespace`, + `stopping`, ) const lost = observations.find((o) => o.checkpoint === `unwritableLog`)?.value if (lost !== undefined) { From 8246f4d3b4f0479507b3f0add1025bfae5d8728d Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sun, 15 Nov 2026 12:59:53 -0700 Subject: [PATCH 46/62] fix(oracle-gaps): claim fix lines print a posix path; the supervisor-death state is platform-scoped Windows CI showed the claim refusals' fix line printed a backslash path (`delete \run.pid`), where the owed line names the claim as `/run.pid`. The fix line now prints the claim in posix form. The supervisor-death state exists only where a supervisor does, so it is required and entered only off win32 (platform-scoped reach, register "Platform-scoped reach (#73)"). On win32 the history runs without the death witness and enters no state; that run is not judged by the death law. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-oracle.property.test.mjs | 13 ++++++++++--- packages/oracles/oracle-gaps/index.mjs | 12 ++++++------ 2 files changed, 16 insertions(+), 9 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 b5fdb2fd..1d188bd1 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -4340,6 +4340,13 @@ const staticStates = [ `a class passed as a value brings its methods`, `owned through bind`, ] +// The supervisor-death state exists only where a supervisor does: win32 has no +// supervisor until #79, so there the state is not required and no history +// enters it (platform-scoped reach, register "Platform-scoped reach (#73)"). +const posixSupervision = + process.platform === `win32` + ? [] + : [`a supervised child exits when its supervisor is killed`] const required = [ // Reached only by the constructed history of the disarmed pause (see there). `a daemon pause that did not engage`, @@ -4349,7 +4356,7 @@ const required = [ `a start refuses a stale claim`, `a start refuses an empty claim`, `a start refuses an unreadable claim`, - `a supervised child exits when its supervisor is killed`, + ...posixSupervision, `a stream log lost after its note, then stopped`, `a stream log lost after its note, then completed`, `a stop as the CLI starts`, @@ -4531,7 +4538,7 @@ const ownHistoryStates = [ `a start refuses a stale claim`, `a start refuses an empty claim`, `a start refuses an unreadable claim`, - `a supervised child exits when its supervisor is killed`, + ...posixSupervision, `a stream log lost after its note, then stopped`, `a stream log lost after its note, then completed`, `a stop as the CLI starts`, @@ -6345,7 +6352,7 @@ oracleProperty({ // A supervised check whose supervisor is killed with SIGKILL: its child exits // within the watchdog's tick, so no run's process outlives its CLI (POSIX). name: `a supervised child exits when its supervisor is killed`, - enters: [`a supervised child exits when its supervisor is killed`], + enters: posixSupervision, build: (generated) => ({ ...generated, functions: [[{ kind: `push`, quote: `'` }]], diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index cfc8f8fb..9fb877f1 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -244,7 +244,7 @@ function claimOut(out) { if (holder === undefined) throw new Refusal( `run.pid in ${out} keeps changing`, - `rerun the check; if no run uses ${out}, delete ${claim}`, + `rerun the check; if no run uses ${out}, delete ${posix(claim)}`, ) throw heldRefusal(out, claim, holder) } @@ -257,7 +257,7 @@ function claimOut(out) { function claimCannotWrite(out, claim, error) { return new Refusal( `run.pid in ${out} cannot be written (${error.code ?? error.message})`, - `if no run uses ${out}, delete ${claim}, or pass --out a directory whose run.pid can be written`, + `if no run uses ${out}, delete ${posix(claim)}, or pass --out a directory whose run.pid can be written`, ) } /** The refusal for a `run.pid` that holds its directory or cannot be read. */ @@ -266,21 +266,21 @@ function heldRefusal(out, claim, holder) { holder === UNREADABLE ? new Refusal( `run.pid in ${out} can't be read`, - `if no run uses ${out}, delete ${claim}`, + `if no run uses ${out}, delete ${posix(claim)}`, ) : holder > 0 && alive(holder) ? new Refusal( `another run (pid ${holder}) is using ${out}`, - `If no run is using it, delete ${claim}; otherwise pass --out a directory no run is using.`, + `If no run is using it, delete ${posix(claim)}; otherwise pass --out a directory no run is using.`, ) : holder > 0 ? new Refusal( `run.pid names pid ${holder}, which is not running`, - `if no run uses ${out}, delete ${claim}`, + `if no run uses ${out}, delete ${posix(claim)}`, ) : new Refusal( `run.pid in ${out} does not name a pid`, - `if no run uses ${out}, delete ${claim}`, + `if no run uses ${out}, delete ${posix(claim)}`, ) refusal.reportless = true return refusal From 658b5f9dde46cd10b64bbcb16895f46064b2fc4d Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sun, 15 Nov 2026 18:38:45 -0600 Subject: [PATCH 47/62] fix(oracle-gaps): a daemon-served check writes to the directory its run named A run without --out names its output directory per call (args.mjs), so the client's stream log and the daemon's results.json were in two different directories. Windows CI showed exit 0 with results.json missing beside the stream log (run 43778158734, job 133009093614: OBSERVER-DIAG names the client's and the daemon's directories, one second and a random suffix apart). The request now carries the directory the run named, unless the arguments already name one. RED: Windows CI at 8120cb8 (run 43725828219), the daemon units on shards 1, 7, 8 and 9, and the diagnostic run 43778158734. GREEN: local POSIX default-output daemon unit (1 passed); Windows CI pending on this head. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/index.mjs | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index 9fb877f1..e5c23fa4 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -621,9 +621,13 @@ async function checkCold(options) { async function checkThroughDaemon(options) { const { codeIdentity } = await import(`./check.mjs`) const { received, requestDaemon } = await import(`./daemon.mjs`) + // A run without `--out` names its directory per call (args.mjs), so the daemon + // would name another one than this run's stream log is in. The request + // carries the directory this run named. + const argv = process.argv.slice(2) const reply = await requestDaemon( options.pkg, - process.argv.slice(2), + argv.includes(`--out`) ? argv : [...argv, `--out`, options.out], codeIdentity(), ) if (reply.stderr) writeStream(reply.stderr) From 1c4dc729b7fb255fd8369078befc8899b688e7d4 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sun, 15 Nov 2026 18:47:49 -0600 Subject: [PATCH 48/62] test(oracle-gaps): the POSIX oracle reaches the daemon request that names no directory On POSIX the supervisor appends `--out` to the child, so every daemon request carries the directory the run named and the default-directory state is never produced there. On win32 there is no supervisor, the request has no `--out`, and the daemon names another directory than the stream log's. A test-only hook (ORACLE_GAPS_TEST_UNSUPERVISED) runs a POSIX check unsupervised, the path win32 takes. The driver sets it on the daemon runs that name no directory. RED: the fix reverted (the request without `--out`) on POSIX fails the default-output daemon unit with results.json missing beside its stream log, the same observation as Windows CI. GREEN: the fixed head passes. Co-authored-by: Isaac --- README.md | 3 +++ .../oracle-gaps/gap-report-oracle.property.test.mjs | 11 ++++++++++- packages/oracles/oracle-gaps/index.mjs | 6 +++++- 3 files changed, 18 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2e3826d7..7d3a6a71 100644 --- a/README.md +++ b/README.md @@ -172,6 +172,9 @@ agent. - `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). + - `ORACLE_GAPS_TEST_UNSUPERVISED` runs a POSIX check unsupervised, the path win32 + takes (no supervisor writes the run's `--out`), so the daemon request of a run + that names no directory is reached on every platform. - `ORACLE_GAPS_INTERNAL_SUPERVISED` is set by a supervisor for the child it starts (its own pid). It is internal, not a user setting: the child kills its own process group only when the supervisor that started it has gone and the 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 1d188bd1..ea6b63de 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -672,7 +672,16 @@ function runCli(dir, files, how = {}) { encoding: `utf8`, timeout: 300_000, maxBuffer: 64 * 1024 * 1024, - env: { ...cleanEnv(), ...how.env }, + // A daemon check that names no directory runs unsupervised, as on win32, so + // the POSIX oracle reaches the state the win32 supervisor never produces: the + // daemon request without `--out` (ORACLE_GAPS_TEST_UNSUPERVISED, index.mjs). + env: { + ...cleanEnv(), + ...how.env, + ...(how.daemon && how.outMode === `default` + ? { ORACLE_GAPS_TEST_UNSUPERVISED: `1` } + : {}), + }, }) const run = readRun( dir, diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index e5c23fa4..51d2c589 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -661,7 +661,11 @@ function endWith(error, out) { const main = import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href // Windows has no process groups: there the run is the CLI's own process. -const supervised = process.platform !== `win32` +// A test-only hook (ORACLE_GAPS_TEST_UNSUPERVISED) runs a POSIX check unsupervised, +// the path win32 takes, so the oracle reaches it on every platform. +const supervised = + process.platform !== `win32` && + process.env.ORACLE_GAPS_TEST_UNSUPERVISED === undefined const supervisor = process.env.ORACLE_GAPS_INTERNAL_SUPERVISED // Set once the note is written (the unsupervised run has started). From c3b6741c702a981626e8d0d30125a8eda4e9cbcd Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sun, 15 Nov 2026 23:02:14 -0600 Subject: [PATCH 49/62] test(oracle-gaps): the eight #57 drawn fields are constructed-only, and the unsupervised hook is a constructed field F2 (generator rule, 2026-11-14): outMode, logBlocked, overlap, stopWitness, spawnStop, spawnSignal, spawnDelay and spawnOnStart were drawn with values that change what a history runs. They are now constants with neutral values, set only by constructed histories, and the take-back maps a constructed value to the neutral one through one table (constructedNeutral). concurrentStart, tornRows, pauseEngages and warmReplaced are main's and are exempt. F1: ORACLE_GAPS_TEST_UNSUPERVISED is set only for a history whose unsupervised field is true. The drawn record holds false. The new constructed history "a daemon check with the default output directory, unsupervised" is appended last. The supervised default-directory history runs sequential checks, so the supervisor-drops-`--out` mutant is killed by it. RED (forwarding reverted, POSIX, the unsupervised unit): "through the daemon at start: the run completed, but /results.json is missing". Mutant (supervisor drops --out for daemon runs without one, the supervised unit): same observation. GREEN: the six default-directory units pass. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-model-oracle.mjs | 122 +++++++----------- .../gap-report-oracle.property.test.mjs | 43 +++++- .../oracle-gaps/history-fingerprint.json | 38 +++--- 3 files changed, 105 insertions(+), 98 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index a88942d8..aabdfba0 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -848,71 +848,27 @@ const drawn = fc.record({ // Whether the warm daemon is replaced after the warm check (review of #73, B2). // Only the constructed history of a replaced warm daemon sets it. warmReplaced: fc.constant(false), - // Where the run writes: the output directory `--out` names (`explicit`), or - // the one the CLI picks when `--out` is left out (`default`, args.mjs), whose - // stream log, results, and done line must still agree (law 15). - outMode: fc.constantFrom(`explicit`, `explicit`, `explicit`, `default`), - // The run's `/stream.log` is a directory, so the log cannot be written - // (a problem the author can fix: the run refuses before it checks). - logBlocked: fc.constantFrom( - false, - false, - false, - false, - false, - false, - false, - false, - true, - ), - // A second run starts on the first run's output directory while the first - // is live (the coordinator's decision of 2026-11-13 on F4): the second - // refuses, and the first's stream log stays its own. - overlap: fc.constantFrom( - false, - false, - false, - false, - false, - false, - false, - false, - false, - false, - true, - ), - // The stop witness alone (`w_stop`), which a run the driver stops needs. A - // field of its own, so the witness options above keep their weights. - stopWitness: fc.constantFrom( - false, - false, - false, - false, - false, - false, - false, - false, - true, - ), - // A stop sent as soon as the CLI spawns, before its own run has started (P1: - // the note is written before the child exists, so the stopped line follows - // it). The driver adds this stop to the run's stops. - spawnStop: fc.constantFrom( - false, - false, - false, - false, - false, - false, - false, - false, - true, - ), - // The signal of a spawn stop and when it lands, 0 to 150 ms after the CLI - // spawns (the spawn-delay law, review of #57). - spawnSignal: fc.constantFrom(`SIGINT`, `SIGINT`, `SIGTERM`), - spawnDelay: fc.integer({ min: 0, max: 150 }), - spawnOnStart: fc.constantFrom(false, false, false, true), + // The fields below that a constructed history sets (outMode, logBlocked, + // overlap, stopWitness, spawnStop, spawnSignal, spawnDelay, spawnOnStart) are + // constructed only: a drawn record holds their neutral value, which draws + // nothing, so generated histories keep the runs they had (the generator rule, + // 2026-11-14). The take-back maps a constructed value to the neutral one + // (constructedNeutral). + // Where the run writes: `--out` names (`explicit`), or the directory the + // CLI picks when `--out` is left out (`default`, args.mjs). + outMode: fc.constant(`explicit`), + // The run's stream log cannot be written (constructed only). + logBlocked: fc.constant(false), + // A second run on the first run's output directory (constructed only). + overlap: fc.constant(false), + // The stop witness alone (`w_stop`), constructed only. + stopWitness: fc.constant(false), + // A stop sent as the CLI spawns, constructed only. + spawnStop: fc.constant(false), + // The signal and delay of a spawn stop, constructed only. + spawnSignal: fc.constant(`SIGINT`), + spawnDelay: fc.constant(0), + spawnOnStart: fc.constant(false), // A claim scenario (`race`, `stale`, `empty` or `unreadable`, review of #57) // is constructed only. A constant draws nothing, so generated histories never // run the claim driver, and `histories` takes a constructed scenario back as @@ -924,6 +880,9 @@ const drawn = fc.record({ // A supervised check whose supervisor is killed (POSIX; review of #57, F7): // constructed only, and taken back as the constant false. supervisorDeath: fc.constant(false), + // A POSIX check run unsupervised, the path win32 takes (the test-only hook + // ORACLE_GAPS_TEST_UNSUPERVISED). Constructed only: a drawn record holds false. + unsupervised: fc.constant(false), }) // The edit sequence over the witness module, the one list of steps that a @@ -974,6 +933,22 @@ const keepsSteps = (history) => { // steps (`laterStepsOf`). Taking a history back returns it unchanged, except a // constructed one whose `steps` hold a later edit, which the steps grammar // cannot draw: its later edits move to `laterSteps`. +// The neutral value of each constructed-only field: a drawn record holds it, and +// the take-back maps a constructed history back to it (the generator rule, 2026-11-14). +const constructedNeutral = { + outMode: `explicit`, + logBlocked: false, + overlap: false, + stopWitness: false, + spawnStop: false, + spawnSignal: `SIGINT`, + spawnDelay: 0, + spawnOnStart: false, + claimScenario: false, + logLost: false, + supervisorDeath: false, + unsupervised: false, +} const histories = drawn.map( (history) => (keepsSteps(history) ? history : { ...history, steps: null }), (value) => { @@ -986,17 +961,11 @@ const histories = drawn.map( // Take-back into the drawn language: a disarmed pause (pauseEngages false, // only the constructed history sets it) comes back as engaged, so the // arbitrary can shrink it. The disarm is therefore not kept by a shrink. - const reset = - history.claimScenario === false && - history.logLost === false && - history.supervisorDeath === false - ? value - : { - ...history, - claimScenario: false, - logLost: false, - supervisorDeath: false, - } + const reset = Object.entries(constructedNeutral).every( + ([field, neutral]) => history[field] === neutral, + ) + ? value + : { ...history, ...constructedNeutral } const taken = reset.tornRows === false ? reset : { ...reset, tornRows: false } const later = (history.steps ?? []).filter((step) => @@ -3082,6 +3051,7 @@ function resolveHistory(history) { claimScenario: history.claimScenario ?? false, logLost: history.logLost ?? false, supervisorDeath: history.supervisorDeath ?? false, + unsupervised: history.unsupervised === true, spawnOnStart: history.spawnOnStart === true, onlyRun: history.onlyRun === true, pragma: history.pragma === true, 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 f3802104..4649b10d 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -682,13 +682,13 @@ function runCli(dir, files, how = {}) { encoding: `utf8`, timeout: 300_000, maxBuffer: 64 * 1024 * 1024, - // A daemon check that names no directory runs unsupervised, as on win32, so - // the POSIX oracle reaches the state the win32 supervisor never produces: the - // daemon request without `--out` (ORACLE_GAPS_TEST_UNSUPERVISED, index.mjs). + // A constructed history that runs unsupervised (`unsupervised`): the path + // win32 takes, so the POSIX oracle reaches the daemon request that names no + // directory (ORACLE_GAPS_TEST_UNSUPERVISED, index.mjs). env: { ...cleanEnv(), ...how.env, - ...(how.daemon && how.outMode === `default` + ...(how.unsupervised === true ? { ORACLE_GAPS_TEST_UNSUPERVISED: `1` } : {}), }, @@ -1907,6 +1907,7 @@ async function incremental(dir, plan, cli, copy, observe, states) { const how = { seed: state.seed, outMode: plan.outMode, + unsupervised: plan.unsupervised, cli: step === `otherInstall` ? otherCli() : copy, ordinary: plan.ordinary, sources: sourceArgument(plan, `${dir}.link`), @@ -2416,6 +2417,7 @@ async function driver(plan, observe) { budget: plan.budget, outMode: plan.outMode, logBlocked: plan.logBlocked, + unsupervised: plan.unsupervised, cli: plan.cliPath === `spaced` ? copy : here, ...configArgs(plan), } @@ -6347,6 +6349,7 @@ oracleProperty({ steps: [`test`], ordinary: false, outMode: `default`, + concurrentStart: false, budget: `two`, }), }, @@ -6643,6 +6646,38 @@ oracleProperty({ supervisorDeath: true, }), }, + { + // The same check, run unsupervised: the path win32 takes, where no + // supervisor writes the run's `--out`. The daemon request names no + // directory, so the CLI and the daemon name two (the fix's RED on POSIX). + name: `a daemon check with the default output directory, unsupervised`, + enters: [ + `a run with the default output directory`, + `a daemon check with the default output directory`, + ], + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], + wholeFile: `none`, + witness: false, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, + steps: [`test`], + ordinary: false, + outMode: `default`, + concurrentStart: false, + unsupervised: true, + budget: `two`, + }), + }, ]), }, resolve: resolveHistory, diff --git a/packages/oracles/oracle-gaps/history-fingerprint.json b/packages/oracles/oracle-gaps/history-fingerprint.json index f58038dd..9a831df4 100644 --- a/packages/oracles/oracle-gaps/history-fingerprint.json +++ b/packages/oracles/oracle-gaps/history-fingerprint.json @@ -55,17 +55,18 @@ ["tornRows", "ed6866229ecc4969"], ["pauseEngages", "c93e2e40cd0c4b9f"], ["warmReplaced", "ed6866229ecc4969"], - ["outMode", "41cdfe2f2bf3d461"], - ["logBlocked", "7e3d565dd085831c"], - ["overlap", "70f12bc4ddb9358a"], - ["stopWitness", "20198d10429c9253"], - ["spawnStop", "88af484a06a50fc2"], - ["spawnSignal", "df5e8e97246a3ecb"], - ["spawnDelay", "3b0468d849c5df4c"], - ["spawnOnStart", "88d5b71848a9c6cd"], + ["outMode", "62a68dc5d76b9e0c"], + ["logBlocked", "ed6866229ecc4969"], + ["overlap", "ed6866229ecc4969"], + ["stopWitness", "ed6866229ecc4969"], + ["spawnStop", "ed6866229ecc4969"], + ["spawnSignal", "b289b0e3d5cb0728"], + ["spawnDelay", "e5386ea9402dd268"], + ["spawnOnStart", "ed6866229ecc4969"], ["claimScenario", "ed6866229ecc4969"], ["logLost", "ed6866229ecc4969"], - ["supervisorDeath", "ed6866229ecc4969"] + ["supervisorDeath", "ed6866229ecc4969"], + ["unsupervised", "ed6866229ecc4969"] ], "histories": [ ["functions", "66c0e9c56951c377"], @@ -123,16 +124,17 @@ ["tornRows", "ed6866229ecc4969"], ["pauseEngages", "c93e2e40cd0c4b9f"], ["warmReplaced", "ed6866229ecc4969"], - ["outMode", "41cdfe2f2bf3d461"], - ["logBlocked", "7e3d565dd085831c"], - ["overlap", "70f12bc4ddb9358a"], - ["stopWitness", "20198d10429c9253"], - ["spawnStop", "88af484a06a50fc2"], - ["spawnSignal", "df5e8e97246a3ecb"], - ["spawnDelay", "3b0468d849c5df4c"], - ["spawnOnStart", "88d5b71848a9c6cd"], + ["outMode", "62a68dc5d76b9e0c"], + ["logBlocked", "ed6866229ecc4969"], + ["overlap", "ed6866229ecc4969"], + ["stopWitness", "ed6866229ecc4969"], + ["spawnStop", "ed6866229ecc4969"], + ["spawnSignal", "b289b0e3d5cb0728"], + ["spawnDelay", "e5386ea9402dd268"], + ["spawnOnStart", "ed6866229ecc4969"], ["claimScenario", "ed6866229ecc4969"], ["logLost", "ed6866229ecc4969"], - ["supervisorDeath", "ed6866229ecc4969"] + ["supervisorDeath", "ed6866229ecc4969"], + ["unsupervised", "ed6866229ecc4969"] ] } From 8c3e1bbd3975427c6496aca345c069f59a87a7ee Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sun, 15 Nov 2026 23:03:49 -0600 Subject: [PATCH 50/62] test(oracle-gaps): place the unsupervised default-directory history in the partitions Co-authored-by: Isaac --- packages/oracles/scripts/e2e-shards.mjs | 3 +++ packages/oracles/scripts/pr-shards.mjs | 1 + 2 files changed, 4 insertions(+) diff --git a/packages/oracles/scripts/e2e-shards.mjs b/packages/oracles/scripts/e2e-shards.mjs index ae561794..64d9b3b7 100644 --- a/packages/oracles/scripts/e2e-shards.mjs +++ b/packages/oracles/scripts/e2e-shards.mjs @@ -43,6 +43,7 @@ export const shards = { 'e2e-1': [ `fixed seed 20261105: a stop with the default output directory`, `fixed seed 20261105: a daemon check with the default output directory`, + `fixed seed 20261105: a daemon check with the default output directory, unsupervised`, `fixed seed 20261105: a stream log that cannot be written`, `fixed seed 20261105: two runs on one output directory`, `fixed seed 20261105: a .cjs config that calls require`, @@ -171,6 +172,7 @@ export const shards = { `determinism: constructed history: a stop as the CLI starts`, `random seed: a stop with the default output directory`, `random seed: a daemon check with the default output directory`, + `random seed: a daemon check with the default output directory, unsupervised`, `random seed: a stream log that cannot be written`, `random seed: two runs on one output directory`, `fixed seed 20261105: a config fault in a run that owns nothing`, @@ -261,6 +263,7 @@ export const shards = { `determinism: constructed history: every outcome class, the warm and abort stops`, `determinism: constructed history: a stop with the default output directory`, `determinism: constructed history: a daemon check with the default output directory`, + `determinism: constructed history: a daemon check with the default output directory, unsupervised`, `determinism: constructed history: a stream log that cannot be written`, `determinism: constructed history: two runs on one output directory`, `fixed seed 20261105: an edit sequence through the daemon`, diff --git a/packages/oracles/scripts/pr-shards.mjs b/packages/oracles/scripts/pr-shards.mjs index 414f33ea..fc7fe03e 100644 --- a/packages/oracles/scripts/pr-shards.mjs +++ b/packages/oracles/scripts/pr-shards.mjs @@ -568,6 +568,7 @@ export const partitions = { 'a declaration fault: badEntry', 'a stop with the default output directory', 'a daemon check with the default output directory', + 'a daemon check with the default output directory, unsupervised', ]), 9: anyOf([ 'a lazy module loaded before a hang in the same batch', From 2a49e79abe7e5612ce36cdbd263e826f55057170 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Sun, 15 Nov 2026 23:19:21 -0600 Subject: [PATCH 51/62] test(oracle-gaps): the cli observation compares gap lines as a sorted set, not in streamed order Determinism flake (pool runs r57c-det-6, job of the unsupervised default-directory history): two runs of one history printed the same 43 gap lines in a different order, so the cli observation's lead differed at its first gap line. The order of streamed gap lines is not part of the contract (C, 2026-11-13; live progress, results.json and the gap-line set are the record). The lead keeps every other line in order, and stdoutGaps, which holds each gap line once, is sorted. 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 4649b10d..b9607646 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1623,16 +1623,19 @@ function readRunIn(dir, out, status, stderr, cli, stdout, derived) { .filter((line, i, all) => all.slice(i).some(Boolean)) const blank = printed.indexOf(``) return { - lead: (blank < 0 ? printed : printed.slice(0, blank)).map((line) => - namedScratch(line, scratch), - ), + // The gap lines are not in the lead: their order is live progress, not outcome + // (C, 2026-11-13), and they are compared as a set in stdoutGaps. + lead: (blank < 0 ? printed : printed.slice(0, blank)) + .filter((line) => !line.startsWith(`oracle-gaps: gap `)) + .map((line) => namedScratch(line, scratch)), lastLine: printed.at(-1) && namedScratch(printed.at(-1), scratch), // The stdout's own lines of the gap kind: the gap lines under their // functions, as the stream prints them (law 15). Every line of the kind // is kept, so a line that does not read as a gap is judged, not lost. stdoutGaps: printed .filter((line) => line.startsWith(`oracle-gaps: gap `)) - .map((line) => namedScratch(line, scratch)), + .map((line) => namedScratch(line, scratch)) + .sort(), stderrGaps: lines .filter((line) => streamedGap.test(line)) .map((line) => namedScratch(line, scratch)), From 31fb85f27f136c4531fad5fb9c0eec0a40af12b6 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Mon, 16 Nov 2026 00:01:55 -0600 Subject: [PATCH 52/62] fix(oracle-gaps): merge-gate fixes: limits, changeset, and nits F3: the declared limits say the supervisor-death state is required only off win32 (win32 has no supervisor until #79; register C entry (e) of #58), and name the scope rather than an OS gap. F4: the declared limits no longer say a default --out is judged only by the static oracle, or that a SIGKILL of the CLI is judged by inspection: a SIGKILL of a supervisor is witnessed on POSIX by its constructed history. F6: the changeset lists the run.pid refusals (live, stale, empty, unreadable) and the default-directory refusal. F7: the daemon request always carries the directory the run named (no `--out=dir` special case); the claim refusals print the claim directory in posix form on win32; the stranded optionsOf JSDoc sits with its function. Co-authored-by: Isaac --- .changeset/gap-cli-stream-log.md | 2 ++ packages/oracles/oracle-gaps/args.mjs | 8 +++---- .../gap-report-oracle.property.test.mjs | 2 +- packages/oracles/oracle-gaps/index.mjs | 23 +++++++++---------- 4 files changed, 18 insertions(+), 17 deletions(-) diff --git a/.changeset/gap-cli-stream-log.md b/.changeset/gap-cli-stream-log.md index 1c8c225c..26f3ab92 100644 --- a/.changeset/gap-cli-stream-log.md +++ b/.changeset/gap-cli-stream-log.md @@ -3,3 +3,5 @@ --- The `oracle-gaps` CLI now writes the lines it streams on stderr to `stream.log` in the output directory too, in order, cold and through `--daemon`, and the first line of a check on both streams names that file: `oracle-gaps: note log /stream.log`. An agent that starts a cold check in the background can read the run's progress and its done line there while it runs. A check through `--daemon` prints its lines at the end of its check, so its progress is readable there only after it ends. + +A run takes its output directory's claim in `run.pid` before it starts, and a second run on a live directory refuses without writing into it. A `run.pid` that names no running process (stale), that is empty, or that cannot be read also refuses the run, and the refusal's fix line tells you to delete `/run.pid` if no run uses that directory. The CLI never takes over another run's claim. A refusal of a run with no `--out` is written to the default output directory the run would have used. diff --git a/packages/oracles/oracle-gaps/args.mjs b/packages/oracles/oracle-gaps/args.mjs index e48eb3cc..010c8c51 100644 --- a/packages/oracles/oracle-gaps/args.mjs +++ b/packages/oracles/oracle-gaps/args.mjs @@ -92,10 +92,6 @@ export function parseArgs(argv, cwd = process.cwd()) { } } -/** - * The options of parsed arguments `args`, or the refusal of the first that - * breaks the usage text. - */ /** * The output directory a run with `args` writes to: the `--out` it names, or, * when it names none, the default directory of its package (optionsOf). A refusal @@ -107,6 +103,10 @@ function outDirOf(args, cwd) { const pkg = realPathOf(resolve(cwd, args.package)) return resolve(cwd, join(stateDirOf(pkg), `out`, runName())) } +/** + * The options of parsed arguments `args`, or the refusal of the first that + * breaks the usage text. + */ function optionsOf(args, cwd) { if (args.help) return { help: true } if (!args.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 2929b73d..57317324 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -5011,7 +5011,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: `The run whose process aborts is declared on every platform. Its win32 witness (process.abort through ORACLE_GAPS_TEST_ABORT_AT, under the win32 supervisor) lands in #79; until then the Windows end-to-end job is non-blocking (C entry (c)). On win32 Node cannot deliver SIGTERM (its kill is TerminateProcess, which ends the process with no stopped line), so the stop states that name SIGTERM are required on POSIX only, and a stop there goes through the CLI's test stop hook and is observed as SIGINT; every SIGINT state stays required on win32. Law 12 judges refusals only: no legal history reaches an internal error, so its shape (exit 3, the stack in error.log) is not judged; argument refusals are the static oracle's; the check's rejection of a stack trace, a missing fix, and a wrong exit code is calibrated in the static oracle, through the same refusalBreach, and here only a refused run reported as complete is calibrated, because each calibration here runs real CLI histories. 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: `The run whose process aborts is declared on every platform. Its win32 witness (process.abort through ORACLE_GAPS_TEST_ABORT_AT, under the win32 supervisor) lands in #79; until then the Windows end-to-end job is non-blocking (C entry (c)). On win32 Node cannot deliver SIGTERM (its kill is TerminateProcess, which ends the process with no stopped line), so the stop states that name SIGTERM are required on POSIX only, and a stop there goes through the CLI's test stop hook and is observed as SIGINT; every SIGINT state stays required on win32. Law 12 judges refusals only: no legal history reaches an internal error, so its shape (exit 3, the stack in error.log) is not judged; argument refusals are the static oracle's; the check's rejection of a stack trace, a missing fix, and a wrong exit code is calibrated in the static oracle, through the same refusalBreach, and here only a refused run reported as complete is calibrated, because each calibration here runs real CLI histories. 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; 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; 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 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 (which no generated function's mutant reached in the 36 fixed-seed units at main's bases; the disarmed-pause history's base, appended at its index, does reach it, so that history pins its generated inputs to ones that declare no bound, and the model predicts no work verdict for a generated test, a model gap for the maintainer to decide whether to model work counts), and one warm-cache witness whose selection reproduces observations but not work; work is the capture's count of site evaluations per test, so code with no site (a plain assignment, a for...of pass, a builtin's own work) counts nothing and a test's histories are summed, and a test whose work varies between the unmutated runs while its observations agree is not generated. Open Limits, owned by the in-process runner oracle (L1, state \"torn tail at a cut-off read\"; RED: captureLines without the guard): (a) the batch's cut-off read (runBatch's rowsOf after the cut-off) drops a partial last row, and no witness reaches that drop yet, because a copy held half written across the cut-off did not observe its release in the harness; (b) a short fragment on the strict path, which the no-newline mutant does not reach. The strict read after a finished run (a fragment is an internal error) is witnessed by the no-newline mutant. Windows idle gap (recorded, not witnessed): the state \`a hang cut off for idleness\` is required on every platform, and win32 reaches it (run 43683794816, job 132719872988), so it is not platform-scoped. The sampler (capture-setup.mjs) counts a copy idle only after 500 ms with no late tick, no non-quiet handle, utilization at most 5%, and no timer due, so \`every outcome class\` reaches the state only when the sampler sees that window. On win32 the check missed it once (run 43683794816, job 132719872940); the cause is not confirmed (a late tick on a shared runner, or a stdio handle outside \`quiet\` for this file's console output, are the candidates). Its witness, a test-only hold at the hang until the window is seen, is owed, and that is a timing dependency the determinism-under-load rule forbids; the maintainer decides whether it lands before the Windows job becomes blocking.`, }, histories: { // A failing history shrinks through at most six smaller ones. Each runs diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index 51d2c589..cd29a91e 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -243,8 +243,8 @@ function claimOut(out) { if (holder === undefined && attempt < 3) continue if (holder === undefined) throw new Refusal( - `run.pid in ${out} keeps changing`, - `rerun the check; if no run uses ${out}, delete ${posix(claim)}`, + `run.pid in ${posix(out)} keeps changing`, + `rerun the check; if no run uses ${posix(out)}, delete ${posix(claim)}`, ) throw heldRefusal(out, claim, holder) } @@ -256,8 +256,8 @@ function claimOut(out) { /** The refusal for a `run.pid` that cannot be written: the claim's own cause. */ function claimCannotWrite(out, claim, error) { return new Refusal( - `run.pid in ${out} cannot be written (${error.code ?? error.message})`, - `if no run uses ${out}, delete ${posix(claim)}, or pass --out a directory whose run.pid can be written`, + `run.pid in ${posix(out)} cannot be written (${error.code ?? error.message})`, + `if no run uses ${posix(out)}, delete ${posix(claim)}, or pass --out a directory whose run.pid can be written`, ) } /** The refusal for a `run.pid` that holds its directory or cannot be read. */ @@ -265,22 +265,22 @@ function heldRefusal(out, claim, holder) { const refusal = holder === UNREADABLE ? new Refusal( - `run.pid in ${out} can't be read`, - `if no run uses ${out}, delete ${posix(claim)}`, + `run.pid in ${posix(out)} can't be read`, + `if no run uses ${posix(out)}, delete ${posix(claim)}`, ) : holder > 0 && alive(holder) ? new Refusal( - `another run (pid ${holder}) is using ${out}`, + `another run (pid ${holder}) is using ${posix(out)}`, `If no run is using it, delete ${posix(claim)}; otherwise pass --out a directory no run is using.`, ) : holder > 0 ? new Refusal( `run.pid names pid ${holder}, which is not running`, - `if no run uses ${out}, delete ${posix(claim)}`, + `if no run uses ${posix(out)}, delete ${posix(claim)}`, ) : new Refusal( - `run.pid in ${out} does not name a pid`, - `if no run uses ${out}, delete ${posix(claim)}`, + `run.pid in ${posix(out)} does not name a pid`, + `if no run uses ${posix(out)}, delete ${posix(claim)}`, ) refusal.reportless = true return refusal @@ -624,10 +624,9 @@ async function checkThroughDaemon(options) { // A run without `--out` names its directory per call (args.mjs), so the daemon // would name another one than this run's stream log is in. The request // carries the directory this run named. - const argv = process.argv.slice(2) const reply = await requestDaemon( options.pkg, - argv.includes(`--out`) ? argv : [...argv, `--out`, options.out], + [...process.argv.slice(2), `--out`, options.out], codeIdentity(), ) if (reply.stderr) writeStream(reply.stderr) From c46660591e7042419ed1ebeb6cdfd65010fed83f Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Mon, 16 Nov 2026 11:03:31 +0000 Subject: [PATCH 53/62] test(oracle-gaps): the stderr gap lines are compared as a sorted set, like stdout's The determinism flake's full difference (pre-merge pool run r57f-det-1, observation cli, first difference at stderrGaps): two runs of one history streamed the same gap lines on stderr in a different order. stderrGaps is the streamed gap lines, which the register counts as live progress (C, 2026-11-13); results.json is the record. The list is now sorted, as stdoutGaps already is, and every line is kept. Co-authored-by: Isaac --- .../oracles/oracle-gaps/gap-report-oracle.property.test.mjs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs index 57317324..2b71e0f2 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -1636,9 +1636,12 @@ function readRunIn(dir, out, status, stderr, cli, stdout, derived) { .filter((line) => line.startsWith(`oracle-gaps: gap `)) .map((line) => namedScratch(line, scratch)) .sort(), + // The streamed gap lines on stderr, as a sorted set: their order is live + // progress, not outcome (C, 2026-11-13), and each line is kept. stderrGaps: lines .filter((line) => streamedGap.test(line)) - .map((line) => namedScratch(line, scratch)), + .map((line) => namedScratch(line, scratch)) + .sort(), baselineFiles: lines.flatMap((line) => { const file = line.match( /^oracle-gaps: baseline (?:pass|fail) (\S+)(?: \(ordinary\))?: /, From c6779eb692804d329bdad5a7763616d873d33225 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Mon, 16 Nov 2026 14:04:05 +0000 Subject: [PATCH 54/62] test(oracle-gaps): draw #57's fields, judge win32 stops, and witness the start holds, ps and a dangling claim The oracle side of the review of #57 under the maintainer's decision "Randomness wins for new fields" (2026-11-16): - outMode, logBlocked, stopWitness, claimScenario, spawnSignal and spawnDelay are drawn. Fields that switch a test-only hook (overlap, spawnStop, spawnOnStart, logLost, supervisorDeath, unsupervised) stay constants that constructed histories set. - A drawn stop no longer takes `after`, which switches ORACLE_GAPS_TEST_HOLD_UNTIL; only a constructed history sets it, and the take-back drops it. - The done line of every win32 stop is judged again: each goes through the test stop hook. A new constructed history stops an unsupervised run, so POSIX reaches stopNow too. - A spawn stop is sent only once the CLI is held at its start, then after its drawn delay: after the started marker until the CLI keeps the stop, or before the CLI's first statement through the driver's own preload (outcome a, now judged on stopped runs). New constructed histories: a stop before the CLI starts and a SIGTERM stop as the CLI starts (POSIX only). "A stop as the CLI starts" is entered only when the CLI kept the stop before its child started. - A drawn and constructed run with no command on its PATH (no ps), and a claim scenario whose run.pid is a dangling link. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-model-oracle.mjs | 146 +++++-- .../gap-report-oracle.property.test.mjs | 409 +++++++++++++++--- .../oracle-gaps/history-fingerprint.json | 34 +- packages/oracles/scripts/e2e-shards.mjs | 15 + packages/oracles/scripts/pr-shards.mjs | 13 +- 5 files changed, 510 insertions(+), 107 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index da890a2d..d839719f 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -702,7 +702,11 @@ const drawn = fc.record({ // warms its config (`warm`, re-review N1). Or no signal: a test // aborts the run's process (`abort`, as a V8 out-of-memory abort // does; the coordinator's decision of 2026-11-12 on P10). - when: fc.constantFrom(`run`, `run`, `after`, `warm`, `abort`), + // `after` switches the test-only hold ORACLE_GAPS_TEST_HOLD_UNTIL, + // so only a constructed history sets it (the maintainer's decision + // "Randomness wins for new fields": a drawn field never switches a + // test-only hook); the take-back drops it (drawnStops). + when: fc.constantFrom(`run`, `run`, `warm`, `abort`), }), { minLength: 1, maxLength: 5 }, ), @@ -860,41 +864,96 @@ 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), - // The fields below that a constructed history sets (outMode, logBlocked, - // overlap, stopWitness, spawnStop, spawnSignal, spawnDelay, spawnOnStart) are - // constructed only: a drawn record holds their neutral value, which draws - // nothing, so generated histories keep the runs they had (the generator rule, - // 2026-11-14). The take-back maps a constructed value to the neutral one + // #57's fields (maintainer decision "Randomness wins for new fields", + // 2026-11-16): a field that changes what a history runs is drawn, and only a + // field that switches a test-only hook stays a constant that constructed + // histories set (overlap, spawnStop, spawnOnStart, logLost, supervisorDeath, + // unsupervised). The take-back maps those back to their neutral values // (constructedNeutral). // Where the run writes: `--out` names (`explicit`), or the directory the - // CLI picks when `--out` is left out (`default`, args.mjs). - outMode: fc.constant(`explicit`), - // The run's stream log cannot be written (constructed only). - logBlocked: fc.constant(false), - // A second run on the first run's output directory (constructed only). + // CLI picks when `--out` is left out (`default`, args.mjs), whose stream + // log, results, and done line must still agree (law 15). + outMode: fc.constantFrom(`explicit`, `explicit`, `explicit`, `default`), + // The run's `/stream.log` is a directory, so the log cannot be written + // (a problem the author can fix: the run refuses before it checks). + logBlocked: fc.constantFrom( + false, + false, + false, + false, + false, + false, + false, + false, + true, + ), + // A second run on the first run's output directory while the first is live + // (ORACLE_GAPS_TEST_HOLD_UNTIL holds the first): constructed only. overlap: fc.constant(false), - // The stop witness alone (`w_stop`), constructed only. - stopWitness: fc.constant(false), - // A stop sent as the CLI spawns, constructed only. + // The stop witness alone (`w_stop`), which a run the driver stops needs. A + // field of its own, so the witness options above keep their weights. + stopWitness: fc.constantFrom( + false, + false, + false, + false, + false, + false, + false, + false, + true, + ), + // A stop sent as the CLI starts (ORACLE_GAPS_TEST_STARTED): constructed only. spawnStop: fc.constant(false), - // The signal and delay of a spawn stop, constructed only. - spawnSignal: fc.constant(`SIGINT`), - spawnDelay: fc.constant(0), + // The signal of a spawn stop, and how long the driver waits, once the CLI is + // held at its start, before it sends it (0 to 300 ms). A held start makes the + // outcome independent of the wait; a hold released by time would end before + // a long wait. + spawnSignal: fc.constantFrom(`SIGINT`, `SIGINT`, `SIGTERM`), + spawnDelay: fc.integer({ min: 0, max: 300 }), + // Where a spawn stop is held: after the CLI's started marker + // (ORACLE_GAPS_TEST_PAUSE_AFTER_STARTED), or, when false, before the CLI's + // first statement (the driver's own preload). Constructed only. spawnOnStart: fc.constant(false), - // A claim scenario (`race`, `stale`, `empty` or `unreadable`, review of #57) - // is constructed only. A constant draws nothing, so generated histories never - // run the claim driver, and `histories` takes a constructed scenario back as - // this constant. - claimScenario: fc.constant(false), - // A stream log that becomes a directory right after the note (review of #57, - // F1): constructed only, and taken back as the constant false. + // A claim that every start must refuse (the maintainer's decision "Stale + // claims refuse; no takeover"): two racing starts on a dead pid's claim + // (`race`), one start on it (`stale`), or one on an empty (`empty`), + // unreadable (`unreadable`), or dangling-link (`dangling`) claim. + claimScenario: fc.constantFrom( + false, + false, + false, + false, + false, + false, + false, + false, + false, + false, + false, + false, + false, + false, + false, + `race`, + `stale`, + `empty`, + `unreadable`, + `dangling`, + ), + // A stream log that becomes a directory right after the note + // (ORACLE_GAPS_TEST_PAUSE_AT=note): constructed only. logLost: fc.constant(false), - // A supervised check whose supervisor is killed (POSIX; review of #57, F7): - // constructed only, and taken back as the constant false. + // A supervised check whose supervisor is killed (ORACLE_GAPS_TEST_PAUSE_AT=child, + // POSIX): constructed only. supervisorDeath: fc.constant(false), // A POSIX check run unsupervised, the path win32 takes (the test-only hook // ORACLE_GAPS_TEST_UNSUPERVISED). Constructed only: a drawn record holds false. unsupervised: fc.constant(false), + // The runs' PATH holds no `ps` (a slim container, or BusyBox's `ps`, which + // has no `-p`): the supervised run needs no external command (POSIX; review + // of #57, A7). + psMissing: fc.constantFrom(false, false, false, false, false, false, true), }) // The edit sequence over the witness module, the one list of steps that a @@ -952,15 +1011,9 @@ const keepsSteps = (history) => { // The neutral value of each constructed-only field: a drawn record holds it, and // the take-back maps a constructed history back to it (the generator rule, 2026-11-14). const constructedNeutral = { - outMode: `explicit`, - logBlocked: false, overlap: false, - stopWitness: false, spawnStop: false, - spawnSignal: `SIGINT`, - spawnDelay: 0, spawnOnStart: false, - claimScenario: false, logLost: false, supervisorDeath: false, unsupervised: false, @@ -968,6 +1021,17 @@ const constructedNeutral = { testRoot: `none`, loadPlugin: false, } +// The stops a drawn record can hold: every stop but a constructed `after` one. +const drawnWhens = [`run`, `warm`, `abort`] +const drawnStops = (history) => + (history.stopRuns ?? []).every((stop) => drawnWhens.includes(stop.when)) + ? history + : { + ...history, + stopRuns: history.stopRuns.filter((stop) => + drawnWhens.includes(stop.when), + ), + } const histories = drawn.map( (history) => (keepsSteps(history) ? history : { ...history, steps: null }), (value) => { @@ -986,7 +1050,9 @@ const histories = drawn.map( ) ? value : { ...history, ...constructedNeutral } - const taken = reset + // A constructed stop after the completed line (`after`) is no drawn stop, + // so it is dropped (drawnStops). + const taken = drawnStops(reset) const later = (history.steps ?? []).filter((step) => laterEdits.includes(step), ) @@ -3075,16 +3141,18 @@ function resolveHistory(history) { spawnStop: history.spawnStop === true, spawnSignal: history.spawnSignal ?? `SIGINT`, spawnDelay: history.spawnDelay ?? 0, - // A claim that a start must refuse: two racing starts on a dead pid's claim - // (`race`), one start on it (`stale`), or one on an empty (`empty`) or - // unreadable (`unreadable`) claim. Only constructed histories set it, so generated - // histories keep their fixed-seed draws and run no claim driver (P4, the - // coordinator's decision on the claim rules). - claimScenario: history.claimScenario ?? false, + // A claim that every start must refuse (`claimScenario` above). The claim + // is read after the arguments, so a run whose arguments refuse + // (`outsideSource`) refuses for them first, and draws no claim. + claimScenario: + (history.fault ?? `none`) === `outsideSource` + ? false + : (history.claimScenario ?? false), logLost: history.logLost ?? false, supervisorDeath: history.supervisorDeath ?? false, unsupervised: history.unsupervised === true, spawnOnStart: history.spawnOnStart === true, + psMissing: history.psMissing === true, onlyRun: history.onlyRun === true, pragma: history.pragma === true, cliPath: history.cliPath ?? `plain`, 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 99168f07..1229ca29 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -496,6 +496,7 @@ import { spawn, spawnSync } from 'node:child_process' import { cpSync, existsSync, + lstatSync, statSync, mkdirSync, mkdtempSync, @@ -591,6 +592,18 @@ const cleanEnv = () => ({ ), ORACLE_GAPS_HEARTBEAT_MS: String(HEARTBEAT_MS), }) +// A PATH that names no command (`psMissing`): a supervised run must need no +// external command, such as `ps`, which a slim container lacks and whose +// BusyBox form has no `-p` (review of #57, A7). The CLI, Vitest's workers and +// the fixture's processes all start through process.execPath, so nothing else +// reads PATH. POSIX only: win32 runs no supervisor (until #79), and its PATH +// also finds the system's libraries. +let emptyPath +const pathEnv = (how) => { + if (how.psMissing !== true || process.platform === `win32`) return {} + emptyPath ??= mkdtempSync(join(realpathSync(tmpdir()), `gap-no-ps-`)) + return { PATH: emptyPath } +} /** * The CLI's arguments for one run of a fixture: cold, or through the daemon @@ -824,6 +837,7 @@ function runCli(dir, files, how = {}) { env: { ...cleanEnv(), ORACLE_GAPS_TEST_RETENTION: hook, + ...pathEnv(how), ...how.env, ...(how.unsupervised === true ? { ORACLE_GAPS_TEST_UNSUPERVISED: `1` } @@ -880,6 +894,28 @@ const strays = (dir, before, own, running = false) => !(own !== undefined && (file === own || file.startsWith(`${own}/`))), ) +/** + * Writes the driver's preload for a stop before the CLI's first statement into + * `dir`, and returns its path: it marks `mark`, then waits (60 s at most, then + * fails loudly) for a release that the driver never writes. + */ +function writePreload(dir, mark) { + const path = join(dir, `hold.cjs`) + writeFileSync( + path, + [ + `const { existsSync, writeFileSync } = require('node:fs')`, + `writeFileSync(${JSON.stringify(mark)}, '')`, + `for (let waited = 0; !existsSync(${JSON.stringify(`${mark}.release`)}); waited += 10) {`, + ` if (waited >= 60000) throw new Error('the hold before the CLI started was not ended by a stop within 60 s')`, + ` Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10)`, + `}`, + ``, + ].join(`\n`), + ) + return path +} + /** * A run that the driver stops by `signal` while the stop witness's test * spins (law 13). The CLI runs only the witness's mutants (`ids`), with @@ -909,8 +945,9 @@ async function stoppedRun( ids, { signal, pool, when, delay = 0, onStart = false }, ) { - // `spawn`: the signal comes as the CLI starts, once its own code runs (a - // signal during Node's own start has no handler yet; Limits of #57). + // `spawn`: the signal comes as the CLI starts, while the CLI is held there: + // after its started marker (`onStart`), or before its first statement (the + // driver's preload, below). const atSpawn = when === `spawn` const after = when === `after` const warm = when === `warm` @@ -942,13 +979,35 @@ async function stoppedRun( // the lines already in the file. const hook = hookOf(dir) const earlierLines = retentionLinesOf(hook).length - const base = { ...cleanEnv(), ORACLE_GAPS_TEST_RETENTION: hook } + const base = { + ...cleanEnv(), + ORACLE_GAPS_TEST_RETENTION: hook, + ...pathEnv(how), + // A constructed history that runs unsupervised (`unsupervised`): the path + // win32 takes, so its stop is the unsupervised run's own stopped line on + // POSIX too (ORACLE_GAPS_TEST_UNSUPERVISED). + ...(how.unsupervised === true + ? { ORACLE_GAPS_TEST_UNSUPERVISED: `1` } + : {}), + } + // The driver's hold before the CLI's first statement (a spawn stop without + // `onStart`, POSIX): a preload writes its marker and waits for a release that + // never comes, so a signal sent once the marker exists lands before any CLI + // code runs, and its default action ends the process (outcome a of the + // spawn-delay law). The preload is the driver's, not the CLI's: it stands for + // a slow start of Node itself. Its wait fails loudly after 60 s. win32 cannot + // deliver a signal, so there the spawn stop is the test stop file alone. + const preStart = atSpawn && !onStart && !win + const heldPath = join(pids, `held`) + const preload = preStart ? writePreload(pids, heldPath) : undefined const env = { ...(atSpawn ? { ORACLE_GAPS_TEST_STARTED: startedPath } : {}), - // The constructed witness pauses after the marker, so the signal it sends - // on seeing the marker lands inside the pause (review F2). + // The constructed witness holds the CLI after its marker until the CLI has + // kept the stop the driver sends on seeing the marker (or, on win32, until + // the test stop file exists), so the stop lands during the CLI's loads, + // whatever the load on the machine (review of #57, A4). ...(atSpawn && onStart - ? { ORACLE_GAPS_TEST_PAUSE_AFTER_STARTED: `200` } + ? { ORACLE_GAPS_TEST_PAUSE_AFTER_STARTED: `1` } : {}), ...(after ? { @@ -962,11 +1021,11 @@ async function stoppedRun( : { ...base, GAP_STOP_DIR: pids }), } if (win) env.ORACLE_GAPS_TEST_STOP = stopFile - const child = spawn(process.execPath, args, { - cwd: repo, - env, - stdio: [`ignore`, `pipe`, `pipe`], - }) + const child = spawn( + process.execPath, + preload === undefined ? args : [`--require`, preload, ...args], + { cwd: repo, env, stdio: [`ignore`, `pipe`, `pipe`] }, + ) let stdout = `` let stderr = `` child.stdout.on(`data`, (chunk) => { @@ -1019,16 +1078,18 @@ async function stoppedRun( given === undefined ? undefined : relative(dir, given), true, ) - // A spawn stop signals after its drawn delay, or, when it waits for the - // started marker, at once once the marker exists (event-driven, 30 s cap). - if (atSpawn && onStart) + // A spawn stop waits for its hold's marker (event-driven, 30 s cap), then + // its drawn delay, and then signals. The hold, not the delay, decides where + // the stop lands: a hold released by time would end before a long delay. + const holdMark = onStart ? startedPath : preStart ? heldPath : undefined + if (atSpawn && holdMark !== undefined) for ( let waited = 0; - !existsSync(startedPath) && waited < 30_000; + !existsSync(holdMark) && !exited && waited < 30_000; waited += 1 ) await sleep(1) - else if (atSpawn) await sleep(delay) + if (atSpawn) await sleep(delay) if (!abort) { if (win) writeFileSync(stopFile, ``) else child.kill(signal) @@ -1061,6 +1122,17 @@ async function stoppedRun( // It ended meanwhile. } if (!ended) child.kill(`SIGKILL`) + // Whether the CLI wrote its started marker before the signal (outcomes a and + // b), whether the driver's hold before it was reached, and whether the + // supervisor had started its run's child (its pid beside the marker): a stop + // the CLI kept during its loads ends it before any child starts. + const startMarks = atSpawn + ? { + started: existsSync(startedPath), + held: preStart ? existsSync(heldPath) : undefined, + childStarted: existsSync(`${startedPath}.child`), + } + : {} rmSync(pids, { recursive: true, force: true }) rmSync(stopFile, { force: true }) const out = given ?? chosenOut(stdout) ?? join(dir, `no-output`) @@ -1072,9 +1144,9 @@ async function stoppedRun( const result = { // The signal the CLI took: the hook's SIGINT on win32. signal: win ? `SIGINT` : signal, - // Whether the CLI wrote its started marker before the signal (outcomes a and b). - started: atSpawn ? existsSync(startedPath) : undefined, + ...startMarks, stdoutLength: stdout.length, + stderrLength: stderr.length, pool, spun, ended, @@ -1191,29 +1263,40 @@ const claimStateOf = { stale: `a start refuses a stale claim`, empty: `a start refuses an empty claim`, unreadable: `a start refuses an unreadable claim`, + dangling: `a start refuses a dangling claim`, } /** * Runs a claim scenario (the maintainer's decision, "Stale claims refuse; no * takeover"): a run.pid that names a dead pid (`stale`), an empty run.pid - * (`empty`), or two starts at once on a dead pid's claim (`race`). Every start - * refuses and names its cause and its claim, writes no note and no log, and - * leaves run.pid as it was. A start that never ends is killed after 30 s, and - * its outcome is other. + * (`empty`), a run.pid that is a directory (`unreadable`) or a link to no file + * (`dangling`, which exists for a link and is missing for a read), or two starts + * at once on a dead pid's claim (`race`). Every start refuses and names its + * cause and its claim, writes no note, no log and no report, and leaves run.pid + * as it was. A start that never ends is killed after 30 s, and its outcome is + * other. The claim lives in a directory that `--out` names: a default output + * directory is new for every run, so no claim can be there before it. */ async function claimScenarioRuns(dir, files, how, scenario) { - const { args, out } = cliArgs(dir, files, { ...how, outName: `out-claim` }) + const { args, out } = cliArgs(dir, files, { + ...how, + outMode: `explicit`, + outName: `out-claim`, + }) mkdirSync(out, { recursive: true }) const claim = join(out, `run.pid`) // The claim's text, or none: an unreadable claim is a directory, which no - // read can take. + // read can take, and a dangling claim is a link to a file that is not there. const written = { empty: ``, race: `999999\n`, stale: `999999\n`, unreadable: undefined, + dangling: undefined, }[scenario] - if (written === undefined) mkdirSync(claim) + const gone = join(out, `gone.pid`) + if (scenario === `dangling`) symlinkSync(gone, claim, `file`) + else if (written === undefined) mkdirSync(claim) else writeFileSync(claim, written) // Every start this driver spawns, so a failure here never leaves one running. const children = [] @@ -1271,7 +1354,10 @@ async function claimScenarioRuns(dir, files, how, scenario) { claimKept: scenario === `unreadable` ? existsSync(claim) && statSync(claim).isDirectory() - : existsSync(claim) && readFileSync(claim, `utf8`) === written, + : scenario === `dangling` + ? lstatSync(claim, { throwIfNoEntry: false })?.isSymbolicLink() === + true && !existsSync(gone) + : existsSync(claim) && readFileSync(claim, `utf8`) === written, otherFiles: readdirSync(out).filter((name) => name !== `run.pid`), } } @@ -1285,7 +1371,12 @@ async function claimScenarioRuns(dir, files, how, scenario) { * once the supervisor runs, so the stop is taken by an event, not a timer. */ async function unwritableLogRuns(dir, files, how, ending) { - const { args, out } = cliArgs(dir, files, { ...how, outName: `out-lost` }) + // The driver swaps the log it names, so the run names its `--out`. + const { args, out } = cliArgs(dir, files, { + ...how, + outMode: `explicit`, + outName: `out-lost`, + }) const marker = join(dir, `lost-at-note`) const release = join(dir, `release-lost`) const stopFile = join(dir, `stop-lost`) @@ -1555,7 +1646,12 @@ async function runClisAtOnce(dir, files, hows, outs = []) { const hook = hookOf(dir) const child = spawn(process.execPath, args, { cwd: repo, - env: { ...cleanEnv(), ...how.env, ORACLE_GAPS_TEST_RETENTION: hook }, + env: { + ...cleanEnv(), + ...pathEnv(how), + ...how.env, + ORACLE_GAPS_TEST_RETENTION: hook, + }, stdio: [`ignore`, `pipe`, `pipe`], }) // Both streams, as runCli reads them: law 15 judges each run's lines, @@ -2098,6 +2194,7 @@ async function incremental(dir, plan, cli, copy, observe, states) { seed: state.seed, outMode: plan.outMode, unsupervised: plan.unsupervised, + psMissing: plan.psMissing, cli: step === `otherInstall` ? otherCli() : copy, ordinary: plan.ordinary, sources: sourceArgument(plan, `${dir}.link`), @@ -2658,6 +2755,7 @@ async function driver(plan, observe) { outMode: plan.outMode, logBlocked: plan.logBlocked, unsupervised: plan.unsupervised, + psMissing: plan.psMissing, cli: plan.cliPath === `spaced` ? copy : here, ...configArgs(plan), ...(plan.rejectBatch > 0 @@ -2774,6 +2872,9 @@ async function driver(plan, observe) { } if (plan.outMode === `default`) states.add(`a run with the default output directory`) + // The cold run is supervised off win32, and its PATH named no command. + if (plan.psMissing && process.platform !== `win32` && cli.exit === 0) + states.add(`a supervised check with no ps on its PATH`) if (plan.logBlocked && cli.exit === 2) states.add(`a stream log that cannot be written`) if (overlapping && overlapping.overlap.exit === 2) @@ -2879,8 +2980,18 @@ async function driver(plan, observe) { states.add(`a stop signal after the completed line`) continue } + // A spawn stop's state is the hold it landed in: before the CLI's + // first statement (the driver's preload), or during the CLI's loads, + // which the CLI kept, so its supervisor started no child (POSIX) and + // the stopped line follows the note. if (stop.when === `spawn`) { - states.add(`a stop as the CLI starts`) + if (run.started === false && run.held === true) + states.add(`a stop before the CLI starts`) + if (run.started === true && run.childStarted === false) { + states.add(`a stop as the CLI starts`) + if (run.signal === `SIGTERM`) + states.add(`a stop by SIGTERM as the CLI starts`) + } continue } if (stop.when === `warm`) { @@ -2892,6 +3003,10 @@ async function driver(plan, observe) { continue } states.add(`a run stopped by ${stopped.signal} while a worker spun`) + // The unsupervised run writes its own stopped line (stopNow): every + // run on win32, and the constructed unsupervised history on POSIX. + if (plan.unsupervised || process.platform === `win32`) + states.add(`an unsupervised run stopped while a worker spun`) states.add( `a stopped run whose workers are ${stop.pool === `forks` ? `child processes` : `threads`}`, ) @@ -3506,6 +3621,8 @@ function check(plan, observations, expected) { const cause = { empty: `run.pid in does not name a pid`, unreadable: `run.pid in can't be read`, + // A link to no file is a claim that no read can take. + dangling: `run.pid in can't be read`, race: `run.pid names pid 999999, which is not running`, stale: `run.pid names pid 999999, which is not running`, }[claim.scenario] @@ -3943,15 +4060,33 @@ function check(plan, observations, expected) { `stopping`, { actual: value.survivors, expected: 0 }, ) + // The spawn-delay law (review of #57; C 2026-11-13 under P10): a stop + // that lands before the CLI's first statement (no started marker) is + // outcome (a): nothing on either stream, no stream log, and an exit by the + // signal. Every other stop is outcome (b), judged below. + if (value.spun && value.started === false) { + if ( + value.stdoutLength === 0 && + value.stderrLength === 0 && + !value.log.exists && + value.exit !== 0 + ) + continue + return violation( + `stopped`, + `a stop before the CLI started left output or a log (${how})`, + `greppable stream`, + ) + } // A stopped run ends both streams with its stopped line, and one that - // had printed its completed line ends as it completed (law 15). On win32 - // the driver's stop is child.kill, which is TerminateProcess, so the run is - // killed like SIGKILL and no done line is owed (register, "Windows stops", - // C 2026-11-13). An abort is the run's own end, which is judged as before. - const owesDone = process.platform !== `win32` || value.when === `abort` - const ends = value.spun - ? endsBreach(value, { doneOwed: owesDone }) - : undefined + // had printed its completed line ends as it completed (law 15), on every + // platform (C 2026-11-13, "Stop window on every platform"). Every stop + // the driver sends on win32 goes through the CLI's test stop hook and is + // taken as a SIGINT, so a done line is owed there too. The one stop that + // owes none is a SIGKILL-equivalent, which no history sends here: a + // win32 child.kill is TerminateProcess (C 2026-11-13, "Windows stops"; + // L1). An abort is the run's own end, which is judged as before. + const ends = value.spun ? endsBreach(value) : undefined if (ends) return violation( `stopped`, @@ -3971,7 +4106,7 @@ function check(plan, observations, expected) { `the run stopped while its config warmed reported a refusal`, `greppable stream`, ) - if (value.spun && owesDone && !value.stream.last.startsWith(owedEnd)) + if (value.spun && !value.stream.last.startsWith(owedEnd)) return violation( `stopped`, `the stopped run's last line is ${JSON.stringify(value.stream.last)}, not ${owedEnd}`, @@ -4031,13 +4166,6 @@ const owesNote = (expected) => !expected.refused?.arguments function streamBreach(checkpoint, run, expected, plan) { const breach = (difference, extra) => violation(checkpoint, difference, `greppable stream`, extra) - // The spawn-delay law (review of #57): a stop before the CLI started (no - // started marker) is outcome (a): no output, no log, the exit by signal. - // Once the marker exists, the outcome is (b) in full. - if (run.started === false) - return run.stdoutLength === 0 && !run.log.exists && run.exit !== 0 - ? undefined - : breach(`a stop before the CLI started left output or a log`) const ends = endsBreach(run, { checked: owesNote(expected) }) if (ends) return breach(ends.difference, ends.extra) if (run.stream.mutantBeforeVerdict) @@ -4202,7 +4330,7 @@ const showsCode = (shown, text) => { * 3 error, and a signal's code stopped). With `checked`, the run started a * check, so its first line names its stream log. Undefined when it holds. */ -function endsBreach(run, { checked = true, doneOwed = true } = {}) { +function endsBreach(run, { checked = true } = {}) { const streams = [ [`stderr`, run.stream], [`stdout`, run.stdoutStream], @@ -4235,9 +4363,6 @@ function endsBreach(run, { checked = true, doneOwed = true } = {}) { difference: `the run wrote a line on ${where} that is not a line of the stream: ${stream.strays[0]}`, extra: { actual: stream.strays, expected: [] }, } - // A run whose done line is not owed (a stop sent by child.kill on win32) is - // judged on everything above: its note, its log, and its results. - if (!doneOwed) return undefined for (const [where, stream] of streams) if (stream.dones !== 1 || !stream.last.startsWith(`oracle-gaps: done `)) return { @@ -5000,6 +5125,21 @@ const posixSupervision = process.platform === `win32` ? [] : [`a supervised child exits when its supervisor is killed`] +// A supervised check with no `ps` on its PATH (review of #57, A7) exists only +// where a supervisor does, for the same reason (#79). +const posixPs = + process.platform === `win32` + ? [] + : [`a supervised check with no ps on its PATH`] +// The spawn stops that need a signal delivered to the CLI's process: SIGTERM, +// and a stop before the CLI's first statement, whose only witness is a signal's +// default action. win32 cannot deliver a signal to a Node process (its kill is +// TerminateProcess, a SIGKILL-equivalent that owes no line, L1), so these +// states are POSIX only (register "Platform-scoped reach (#73)"). +const posixStarts = + process.platform === `win32` + ? [] + : [`a stop before the CLI starts`, `a stop by SIGTERM as the CLI starts`] const required = [ // Reached only by the constructed history of the disarmed pause (see there). `a daemon pause that did not engage`, @@ -5018,6 +5158,10 @@ const required = [ `a run with the default output directory`, `a stop with the default output directory`, `a daemon check with the default output directory`, + `a start refuses a dangling claim`, + `an unsupervised run stopped while a worker spun`, + ...posixStarts, + ...posixPs, `killed by a second owner`, `killed`, `random-only kill`, @@ -5203,6 +5347,10 @@ const ownHistoryStates = [ `a run with the default output directory`, `a stop with the default output directory`, `a daemon check with the default output directory`, + `a start refuses a dangling claim`, + `an unsupervised run stopped while a worker spun`, + ...posixStarts, + ...posixPs, ] const separate = [ ...ownHistoryStates, @@ -5364,6 +5512,8 @@ const withDeclaration = (constructed) => overlap: false, spawnStop: false, stopWitness: false, + claimScenario: false, + psMissing: false, declaration: index % 2 === 0 ? `wrapper` : `oracleProperty`, ownerless: false, owners: [`a`, ...generated.owners.slice(1)], @@ -6919,8 +7069,10 @@ oracleProperty({ logBlocked: false, overlap: false, spawnStop: true, - // The signal waits for the CLI's started marker, so it lands during - // the loads of a CLI that loads before it installs its handlers. + // The CLI is held after its started marker until it has kept the + // signal, so the signal lands during the loads, before the + // supervisor's own handlers, whatever the machine's load. Its signal + // and the driver's wait before it are drawn. spawnOnStart: true, budget: `two`, }), @@ -7216,6 +7368,161 @@ oracleProperty({ budget: `two`, }), }, + { + // A stop that lands before the CLI's first statement (outcome a of the + // spawn-delay law): the driver holds Node's start in a preload of its + // own and signals once the preload has run. No CLI code has run, so + // the run writes nothing at all: no line, no log (C 2026-11-13 under + // P10, flagged for the maintainer). POSIX only (posixStarts): on win32 + // the stop is the test stop file, taken after the note. + name: `a stop before the CLI starts`, + enters: posixStarts.filter( + (state) => state === `a stop before the CLI starts`, + ), + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], + wholeFile: `none`, + witness: false, + stopWitness: true, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, + steps: null, + ordinary: false, + budget: `two`, + outMode: `explicit`, + spawnStop: true, + spawnOnStart: false, + }), + }, + { + // A SIGTERM as the CLI starts, held as "a stop as the CLI starts" is: + // the stopped line names SIGTERM and follows the note (POSIX only, as + // win32 cannot deliver SIGTERM; posixStarts). + name: `a stop by SIGTERM as the CLI starts`, + enters: posixStarts.filter( + (state) => state === `a stop by SIGTERM as the CLI starts`, + ), + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], + wholeFile: `none`, + witness: false, + stopWitness: true, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, + steps: null, + ordinary: false, + budget: `two`, + outMode: `explicit`, + spawnStop: true, + spawnOnStart: true, + spawnSignal: `SIGTERM`, + }), + }, + { + // A run stopped while a worker spins, unsupervised (the test-only hook + // ORACLE_GAPS_TEST_UNSUPERVISED): the path every win32 run takes, where + // the run's own process writes its stopped line (stopNow). On POSIX the + // signal reaches that process itself; on win32 the test stop hook does. + name: `an unsupervised run stopped while a worker spun`, + enters: [`an unsupervised run stopped while a worker spun`], + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], + wholeFile: `none`, + witness: false, + stopWitness: true, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, + steps: null, + ordinary: false, + budget: `two`, + outMode: `explicit`, + unsupervised: true, + stopRuns: [{ signal: `SIGINT`, pool: `threads`, when: `run` }], + }), + }, + { + // A run.pid that is a link to no file: the link exists, so the claim + // cannot be taken, and no read finds a pid in it, so every start + // refuses as for an unreadable claim and writes nothing beside it, + // not even its report (review of #57, A5). + name: `a start refuses a dangling claim`, + enters: [`a start refuses a dangling claim`], + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], + wholeFile: `none`, + witness: false, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, + steps: null, + ordinary: false, + budget: `two`, + outMode: `explicit`, + claimScenario: `dangling`, + }), + }, + { + // A supervised check whose PATH names no command: the supervised run + // must need no `ps`, which a slim container lacks and whose BusyBox + // form has no `-p` (review of #57, A7). POSIX only (posixPs). + name: `a supervised check with no ps on its PATH`, + enters: posixPs, + build: (generated) => ({ + ...generated, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], + wholeFile: `none`, + witness: false, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, + fault: `none`, + stability: `none`, + steps: null, + ordinary: false, + budget: `two`, + psMissing: true, + }), + }, ]), }, resolve: resolveHistory, diff --git a/packages/oracles/oracle-gaps/history-fingerprint.json b/packages/oracles/oracle-gaps/history-fingerprint.json index 7375687d..50fe1386 100644 --- a/packages/oracles/oracle-gaps/history-fingerprint.json +++ b/packages/oracles/oracle-gaps/history-fingerprint.json @@ -32,7 +32,7 @@ ["unbuiltDep", "ece5968476f7042d"], ["boot", "6fc1fdf2bd90d59e"], ["budget", "d8481d5ff2e964b9"], - ["stopRuns", "826d81299eda30ed"], + ["stopRuns", "e7a9ea343f07a902"], ["onlyRun", "439d74b1930e4623"], ["pragma", "731664592bd605c0"], ["cliPath", "cba4d240a707ec0b"], @@ -58,18 +58,19 @@ ["testRoot", "e18db063421a75f1"], ["loadPlugin", "ed6866229ecc4969"], ["rejectBatch", "e5386ea9402dd268"], - ["outMode", "62a68dc5d76b9e0c"], - ["logBlocked", "ed6866229ecc4969"], + ["outMode", "41cdfe2f2bf3d461"], + ["logBlocked", "7e3d565dd085831c"], ["overlap", "ed6866229ecc4969"], - ["stopWitness", "ed6866229ecc4969"], + ["stopWitness", "36747a303377a389"], ["spawnStop", "ed6866229ecc4969"], - ["spawnSignal", "b289b0e3d5cb0728"], - ["spawnDelay", "e5386ea9402dd268"], + ["spawnSignal", "fb32b212e5d379b9"], + ["spawnDelay", "51eee7869e2a0f71"], ["spawnOnStart", "ed6866229ecc4969"], - ["claimScenario", "ed6866229ecc4969"], + ["claimScenario", "9721481ccee3e101"], ["logLost", "ed6866229ecc4969"], ["supervisorDeath", "ed6866229ecc4969"], - ["unsupervised", "ed6866229ecc4969"] + ["unsupervised", "ed6866229ecc4969"], + ["psMissing", "e6ef4bc292a3990d"] ], "histories": [ ["functions", "66c0e9c56951c377"], @@ -104,7 +105,7 @@ ["unbuiltDep", "ece5968476f7042d"], ["boot", "6fc1fdf2bd90d59e"], ["budget", "d8481d5ff2e964b9"], - ["stopRuns", "826d81299eda30ed"], + ["stopRuns", "e7a9ea343f07a902"], ["onlyRun", "439d74b1930e4623"], ["pragma", "731664592bd605c0"], ["cliPath", "cba4d240a707ec0b"], @@ -130,17 +131,18 @@ ["testRoot", "e18db063421a75f1"], ["loadPlugin", "ed6866229ecc4969"], ["rejectBatch", "e5386ea9402dd268"], - ["outMode", "62a68dc5d76b9e0c"], - ["logBlocked", "ed6866229ecc4969"], + ["outMode", "41cdfe2f2bf3d461"], + ["logBlocked", "7e3d565dd085831c"], ["overlap", "ed6866229ecc4969"], - ["stopWitness", "ed6866229ecc4969"], + ["stopWitness", "36747a303377a389"], ["spawnStop", "ed6866229ecc4969"], - ["spawnSignal", "b289b0e3d5cb0728"], - ["spawnDelay", "e5386ea9402dd268"], + ["spawnSignal", "fb32b212e5d379b9"], + ["spawnDelay", "51eee7869e2a0f71"], ["spawnOnStart", "ed6866229ecc4969"], - ["claimScenario", "ed6866229ecc4969"], + ["claimScenario", "9721481ccee3e101"], ["logLost", "ed6866229ecc4969"], ["supervisorDeath", "ed6866229ecc4969"], - ["unsupervised", "ed6866229ecc4969"] + ["unsupervised", "ed6866229ecc4969"], + ["psMissing", "e6ef4bc292a3990d"] ] } diff --git a/packages/oracles/scripts/e2e-shards.mjs b/packages/oracles/scripts/e2e-shards.mjs index a3de069e..bf9ee7f8 100644 --- a/packages/oracles/scripts/e2e-shards.mjs +++ b/packages/oracles/scripts/e2e-shards.mjs @@ -44,6 +44,11 @@ export const shards = { `fixed seed 20261105: a stop with the default output directory`, `fixed seed 20261105: a daemon check with the default output directory`, `fixed seed 20261105: a daemon check with the default output directory, unsupervised`, + `fixed seed 20261105: a stop before the CLI starts`, + `fixed seed 20261105: a stop by SIGTERM as the CLI starts`, + `fixed seed 20261105: an unsupervised run stopped while a worker spun`, + `fixed seed 20261105: a start refuses a dangling claim`, + `fixed seed 20261105: a supervised check with no ps on its PATH`, `fixed seed 20261105: a stream log that cannot be written`, `fixed seed 20261105: two runs on one output directory`, `fixed seed 20261105: a .cjs config that calls require`, @@ -182,6 +187,11 @@ export const shards = { `determinism: constructed history: a start refuses an empty claim`, `determinism: constructed history: a start refuses an unreadable claim`, `determinism: constructed history: a supervised child exits when its supervisor is killed`, + `determinism: constructed history: a stop before the CLI starts`, + `determinism: constructed history: a stop by SIGTERM as the CLI starts`, + `determinism: constructed history: an unsupervised run stopped while a worker spun`, + `determinism: constructed history: a start refuses a dangling claim`, + `determinism: constructed history: a supervised check with no ps on its PATH`, `determinism: constructed history: a stream log lost after its note, then stopped`, `determinism: constructed history: a stream log lost after its note, then completed`, `determinism: constructed history: a stop as the CLI starts`, @@ -228,6 +238,11 @@ export const shards = { `random seed: a start refuses an empty claim`, `random seed: a start refuses an unreadable claim`, `random seed: a supervised child exits when its supervisor is killed`, + `random seed: a stop before the CLI starts`, + `random seed: a stop by SIGTERM as the CLI starts`, + `random seed: an unsupervised run stopped while a worker spun`, + `random seed: a start refuses a dangling claim`, + `random seed: a supervised check with no ps on its PATH`, `random seed: a stream log lost after its note, then stopped`, `random seed: a stream log lost after its note, then completed`, `random seed: a stop as the CLI starts`, diff --git a/packages/oracles/scripts/pr-shards.mjs b/packages/oracles/scripts/pr-shards.mjs index b1d5dc34..fd6f21ce 100644 --- a/packages/oracles/scripts/pr-shards.mjs +++ b/packages/oracles/scripts/pr-shards.mjs @@ -297,11 +297,17 @@ export const partitions = { // select exactly these. previously: `fixed seed`, shards: { - // 261 s, 25 s, and a small unit. + // 261 s, 25 s, and small units: #57's last constructed histories sit + // here, since the rest (shard 3) is near its 10-minute limit. 1: anyOf([ 'an edit sequence over the witness module', 'a stale authored mutant and a reformat', 'a failing owner under a config that --config names', + 'a stop before the CLI starts', + 'a stop by SIGTERM as the CLI starts', + 'an unsupervised run stopped while a worker spun', + 'a start refuses a dangling claim', + 'a supervised check with no ps on its PATH', ]), // Both halves of `every outcome class` (134 s and 155 s on the CI runner), // a second daemon check (101 s), and two small units. The second half @@ -590,6 +596,9 @@ export const partitions = { 'two starts race for a stale claim', 'a start refuses a stale claim', 'a stream log lost after its note, then stopped', + 'a stop before the CLI starts', + 'a stop by SIGTERM as the CLI starts', + 'a start refuses a dangling claim', ]), 10: anyOf([ 'an edit that changed the cold result after a hang replaced the only context', @@ -605,6 +614,8 @@ export const partitions = { 'a reset check after its warm daemon was replaced', 'a stream log lost after its note, then completed', 'a supervised child exits when its supervisor is killed', + 'an unsupervised run stopped while a worker spun', + 'a supervised check with no ps on its PATH', ]), }, }, From c72dd147da77261640838411394bb97606bbc5ad Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Mon, 16 Nov 2026 14:12:24 +0000 Subject: [PATCH 55/62] test(oracle-gaps): the unsupervised witness stops after its note, and a drawn field never switches a hook On POSIX an unsupervised run has no group to end, so a stop while the witness's test spins leaves the test's own child (C 2026-11-13, Windows (e)); the unsupervised witness now stops after its note instead, with its stream log lost, the path every win32 stop takes. The history grammar's canary also checks that no drawn history switches a test-only hook, and that no drawn stop is the stop after the completed line. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-model-oracle.mjs | 17 ++--- .../gap-report-oracle.property.test.mjs | 63 ++++++++++++------- packages/oracles/scripts/e2e-shards.mjs | 6 +- packages/oracles/scripts/pr-shards.mjs | 4 +- .../gap-report-history-fingerprint.test.ts | 31 +++++++++ 5 files changed, 87 insertions(+), 34 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index d839719f..08aed998 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -842,7 +842,7 @@ const drawn = fc.record({ // A batch's closing row written in two halves (issue #83) is constructed // only: the constant draws nothing, so generated histories hold no row, and // `histories` takes a constructed one back as this constant (as - // `claimScenario` does). Its neutral value is recorded by the canary. + // `logLost` does). Its neutral value is recorded by the canary. tornRows: fc.constant(false), // Whether the daemon's pause engages in the daemon steps (dieMidCheck and // resetBeforeRead). Always true in drawn histories, so the seeds' histories are @@ -993,20 +993,21 @@ const keepsSteps = (history) => { // `budgetSteps` (the review of the gap CLI's runtime fixes, 2026-11-12, // P1-a: the budget witness only in its own histories). The map is its own // inverse on the histories it keeps, so fast-check takes every one of them -// back and shrinks it. A constructed claim scenario (`claimScenario`) and a -// constructed stream log loss (`logLost`) are not values `drawn` can produce, so -// their take-back reads them as the drawn constant `false` (a shrink of such a -// counterexample is claim-free and log-intact: the constructed history stays the -// counterexample for its law). A constructed history may also set `tornRows` +// back and shrinks it. A constructed value of a field that switches a +// test-only hook (a stream log loss, `logLost`, for one) is not a value `drawn` +// can produce, so its take-back reads it as the drawn constant (a shrink of +// such a counterexample is log-intact: the constructed history stays the +// counterexample for its law), and so is a constructed stop after the +// completed line (`drawnStops`). A constructed history may also set `tornRows` // (issue #83), which `drawn` cannot produce, so its take-back reads it as the -// drawn constant `false` (as `claimScenario` does): a shrink is torn-row-free. +// drawn constant `false`: a shrink is torn-row-free. // A history is drawn as on main; the plan takes its later edits after its // steps (`laterStepsOf`). Taking a history back returns it unchanged, // except a constructed one whose `steps` hold a later edit, which the // steps grammar cannot draw: its later edits move to `laterSteps`. A // constructed history may also set `tornRows` (issue #83) or `testRoot` // (issue #101), which `drawn` cannot produce, so its take-back reads each as -// its drawn constant (as `claimScenario` does): a shrink is torn-row-free and +// its drawn constant (as `logLost` does): a shrink is torn-row-free and // runs with the package as the config's root. // The neutral value of each constructed-only field: a drawn record holds it, and // the take-back maps a constructed history back to it (the generator rule, 2026-11-14). 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 1229ca29..32f6c0e3 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -373,7 +373,14 @@ * background learns from the run itself where to read it). A refusal * after the check started has that line and then its done line on * stdout; a refusal of the run's arguments comes before any check, and - * its stdout is its done line alone. + * its stdout is its done line alone. A stop owes the same ends on every + * platform (C 2026-11-13, "Stop window on every platform"): its note, and + * then exactly one done line on each stream. Only two stops owe nothing: + * a SIGKILL-equivalent (L1; on win32, child.kill), which no history sends, + * and a stop that lands before the CLI's first statement, which ends the + * process before any line (outcome a of the spawn-delay law, C 2026-11-13 + * under P10, flagged for the maintainer): it must then write nothing at + * all, no line and no stream log. * * Authority: the maintainer's decisions in the gap-check design runs v11, v14, * and v19 (2026-11-04 and 2026-11-05; the design notes are kept by the project @@ -926,17 +933,19 @@ function writePreload(dir, mark) { * only after it closes), sends the signal to the CLI, and waits for the CLI * to end. A second later, each recorded process must have ended. * - * With `when` `after`, the run is not stopped while it runs: the witness - * does not spin, the run's process holds its exit for 500 ms once it has - * printed its done line (`ORACLE_GAPS_TEST_HOLD_UNTIL`, a hook for this - * driver), and the driver sends the signal once that line is on stdout - * (review of #46, F3). The run then ends as it completed, with exactly one + * With `when` `after` (constructed only), the run is not stopped while it + * runs: the witness does not spin, the run's process holds its exit once it + * has printed its done line, until the driver releases it + * (`ORACLE_GAPS_TEST_HOLD_UNTIL`, a hook for this driver), and the driver sends + * the signal once that line is on stdout (review of #46, F3). The run then ends as it completed, with exactly one * done line. With `warm`, the driver sends the signal while the run warms * its config (`ORACLE_GAPS_TEST_WARM_PROBE`, a hook that writes its marker there * and then waits, as a config load does, on a service in the run's group * that the signal ends, with a handler that takes 200 ms to exit, as * Vitest's does; re-review N1). The run then ends stopped, with exactly - * one done line and no refusal. + * one done line and no refusal. With `spawn` (constructed only), the signal + * comes once the CLI is held at its start, `delay` ms after the hold's marker: + * after the started marker when `onStart`, or before the CLI's first statement. */ async function stoppedRun( dir, @@ -1390,6 +1399,11 @@ async function unwritableLogRuns(dir, files, how, ending) { ORACLE_GAPS_TEST_PAUSE_MARKER: marker, ORACLE_GAPS_TEST_PAUSE_UNTIL: release, ORACLE_GAPS_TEST_STOP: stopFile, + // The unsupervised path (ORACLE_GAPS_TEST_UNSUPERVISED), which win32 takes: + // the run's own process writes its stopped line (stopNow). + ...(how.unsupervised === true + ? { ORACLE_GAPS_TEST_UNSUPERVISED: `1` } + : {}), }, stdio: [`ignore`, `pipe`, `pipe`], }) @@ -2869,6 +2883,13 @@ async function driver(plan, observe) { await unwritableLogRuns(dir, files, how, plan.logLost), ) states.add(lostStateOf[plan.logLost]) + // The unsupervised run writes its own stopped line (stopNow): every run + // on win32, and the constructed unsupervised history on POSIX. + if ( + plan.logLost === `stop` && + (plan.unsupervised || process.platform === `win32`) + ) + states.add(`an unsupervised run stopped after its note`) } if (plan.outMode === `default`) states.add(`a run with the default output directory`) @@ -3003,10 +3024,6 @@ async function driver(plan, observe) { continue } states.add(`a run stopped by ${stopped.signal} while a worker spun`) - // The unsupervised run writes its own stopped line (stopNow): every - // run on win32, and the constructed unsupervised history on POSIX. - if (plan.unsupervised || process.platform === `win32`) - states.add(`an unsupervised run stopped while a worker spun`) states.add( `a stopped run whose workers are ${stop.pool === `forks` ? `child processes` : `threads`}`, ) @@ -5159,7 +5176,7 @@ const required = [ `a stop with the default output directory`, `a daemon check with the default output directory`, `a start refuses a dangling claim`, - `an unsupervised run stopped while a worker spun`, + `an unsupervised run stopped after its note`, ...posixStarts, ...posixPs, `killed by a second owner`, @@ -5348,7 +5365,7 @@ const ownHistoryStates = [ `a stop with the default output directory`, `a daemon check with the default output directory`, `a start refuses a dangling claim`, - `an unsupervised run stopped while a worker spun`, + `an unsupervised run stopped after its note`, ...posixStarts, ...posixPs, ] @@ -5525,7 +5542,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; 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; 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 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 (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, 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. 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; 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; 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 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 (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 @@ -7437,12 +7454,17 @@ oracleProperty({ }), }, { - // A run stopped while a worker spins, unsupervised (the test-only hook + // A run stopped after its note, unsupervised (the test-only hook // ORACLE_GAPS_TEST_UNSUPERVISED): the path every win32 run takes, where - // the run's own process writes its stopped line (stopNow). On POSIX the - // signal reaches that process itself; on win32 the test stop hook does. - name: `an unsupervised run stopped while a worker spun`, - enters: [`an unsupervised run stopped while a worker spun`], + // the run's own process writes its stopped line (stopNow). Its stream + // log is lost after the note, as in "a stream log lost after its note, + // then stopped", and its stop is the test stop file, taken once the + // hold at the note is released: one done line on each stream, the same + // on both. The stop lands before the check starts any process, so no + // process can outlive the run (an unsupervised run has no group to end; + // C 2026-11-13, Windows (e)). + name: `a stream log lost after its note, then stopped, unsupervised`, + enters: [`an unsupervised run stopped after its note`], build: (generated) => ({ ...generated, functions: [[{ kind: `push`, quote: `'` }]], @@ -7454,7 +7476,6 @@ oracleProperty({ runes: [], wholeFile: `none`, witness: false, - stopWitness: true, tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], authored: null, fault: `none`, @@ -7463,8 +7484,8 @@ oracleProperty({ ordinary: false, budget: `two`, outMode: `explicit`, + logLost: `stop`, unsupervised: true, - stopRuns: [{ signal: `SIGINT`, pool: `threads`, when: `run` }], }), }, { diff --git a/packages/oracles/scripts/e2e-shards.mjs b/packages/oracles/scripts/e2e-shards.mjs index bf9ee7f8..d6a15eca 100644 --- a/packages/oracles/scripts/e2e-shards.mjs +++ b/packages/oracles/scripts/e2e-shards.mjs @@ -46,7 +46,7 @@ export const shards = { `fixed seed 20261105: a daemon check with the default output directory, unsupervised`, `fixed seed 20261105: a stop before the CLI starts`, `fixed seed 20261105: a stop by SIGTERM as the CLI starts`, - `fixed seed 20261105: an unsupervised run stopped while a worker spun`, + `fixed seed 20261105: a stream log lost after its note, then stopped, unsupervised`, `fixed seed 20261105: a start refuses a dangling claim`, `fixed seed 20261105: a supervised check with no ps on its PATH`, `fixed seed 20261105: a stream log that cannot be written`, @@ -189,7 +189,7 @@ export const shards = { `determinism: constructed history: a supervised child exits when its supervisor is killed`, `determinism: constructed history: a stop before the CLI starts`, `determinism: constructed history: a stop by SIGTERM as the CLI starts`, - `determinism: constructed history: an unsupervised run stopped while a worker spun`, + `determinism: constructed history: a stream log lost after its note, then stopped, unsupervised`, `determinism: constructed history: a start refuses a dangling claim`, `determinism: constructed history: a supervised check with no ps on its PATH`, `determinism: constructed history: a stream log lost after its note, then stopped`, @@ -240,7 +240,7 @@ export const shards = { `random seed: a supervised child exits when its supervisor is killed`, `random seed: a stop before the CLI starts`, `random seed: a stop by SIGTERM as the CLI starts`, - `random seed: an unsupervised run stopped while a worker spun`, + `random seed: a stream log lost after its note, then stopped, unsupervised`, `random seed: a start refuses a dangling claim`, `random seed: a supervised check with no ps on its PATH`, `random seed: a stream log lost after its note, then stopped`, diff --git a/packages/oracles/scripts/pr-shards.mjs b/packages/oracles/scripts/pr-shards.mjs index fd6f21ce..f6781a3f 100644 --- a/packages/oracles/scripts/pr-shards.mjs +++ b/packages/oracles/scripts/pr-shards.mjs @@ -305,7 +305,7 @@ export const partitions = { 'a failing owner under a config that --config names', 'a stop before the CLI starts', 'a stop by SIGTERM as the CLI starts', - 'an unsupervised run stopped while a worker spun', + 'a stream log lost after its note, then stopped, unsupervised', 'a start refuses a dangling claim', 'a supervised check with no ps on its PATH', ]), @@ -614,7 +614,7 @@ export const partitions = { 'a reset check after its warm daemon was replaced', 'a stream log lost after its note, then completed', 'a supervised child exits when its supervisor is killed', - 'an unsupervised run stopped while a worker spun', + 'a stream log lost after its note, then stopped, unsupervised', 'a supervised check with no ps on its PATH', ]), }, diff --git a/packages/oracles/tests/gap-report-history-fingerprint.test.ts b/packages/oracles/tests/gap-report-history-fingerprint.test.ts index e7d22ad1..34d7251b 100644 --- a/packages/oracles/tests/gap-report-history-fingerprint.test.ts +++ b/packages/oracles/tests/gap-report-history-fingerprint.test.ts @@ -59,4 +59,35 @@ describe(`the gap oracle's history grammar`, () => { ) } }) + + // The maintainer's decision "Randomness wins for new fields" (2026-11-16): + // a field that changes what a history runs is drawn, except that a drawn + // field never switches a test-only hook. Each field below switches one + // (named beside it), so every drawn history holds its neutral value, and no + // drawn stop is the stop after the completed line, which holds the run's + // exit (ORACLE_GAPS_TEST_HOLD_UNTIL). The list is written here, not read + // from the model, so a model that starts to draw one of them fails. + test(`draws no value that switches a test-only hook`, () => { + const neutral: Record = { + overlap: false, // ORACLE_GAPS_TEST_HOLD_UNTIL + spawnStop: false, // ORACLE_GAPS_TEST_STARTED + spawnOnStart: false, // ORACLE_GAPS_TEST_PAUSE_AFTER_STARTED + logLost: false, // ORACLE_GAPS_TEST_PAUSE_AT=note + supervisorDeath: false, // ORACLE_GAPS_TEST_PAUSE_AT=child + unsupervised: false, // ORACLE_GAPS_TEST_UNSUPERVISED + tornRows: false, // ORACLE_GAPS_TEST_TORN_ROWS + loadPlugin: false, // LOAD_PLUGIN + rejectBatch: 0, // ORACLE_GAPS_TEST_REJECT_BATCH + } + for (const seed of [FIXED_SEED, 1, 2]) { + const samples = fc.sample(drawn, { seed, numRuns: DRAWS }) as Array< + Record & { stopRuns: Array<{ when: string }> } + > + for (const history of samples) { + for (const [field, value] of Object.entries(neutral)) + expect([field, history[field]]).toEqual([field, value]) + for (const stop of history.stopRuns) expect(stop.when).not.toBe(`after`) + } + } + }) }) From cfcc7fa3a772e346d884d8bcb9869bb6faf73688 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Mon, 16 Nov 2026 14:15:00 +0000 Subject: [PATCH 56/62] test(oracle-gaps): the unsupervised witness is a stop held at the run's note A stream log lost after the note makes the unsupervised run refuse before its stop is taken, so that history never reached stopNow. The witness now holds the run at its note (ORACLE_GAPS_TEST_PAUSE_AT), sends the stop, and releases the hold: a constructed-only stop kind, `note`, which the take-back drops as it drops `after`. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-model-oracle.mjs | 11 +++- .../gap-report-oracle.property.test.mjs | 58 ++++++++++++------- packages/oracles/scripts/e2e-shards.mjs | 6 +- packages/oracles/scripts/pr-shards.mjs | 4 +- 4 files changed, 51 insertions(+), 28 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index 08aed998..cd60cefa 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -491,6 +491,9 @@ const earlierEdits = edits.filter((edit) => !laterEdits.includes(edit)) // 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([]) +// A history's no stop runs, one value for the same reason: a constructed +// history whose stops are all constructed-only is taken back to it. +const NO_STOPS = Object.freeze([]) // The later edits a history takes after its steps: only one without the // witness module that has steps. const laterStepsOf = (history) => @@ -689,7 +692,7 @@ const drawn = fc.record({ // spins (`w_stop`), each in a pool: Vitest's workers as child processes or // as threads. Each costs a run of its own, so few histories have one. stopRuns: fc.oneof( - { weight: 9, arbitrary: fc.constant([]) }, + { weight: 9, arbitrary: fc.constant(NO_STOPS) }, { weight: 1, arbitrary: fc.array( @@ -1029,9 +1032,11 @@ const drawnStops = (history) => ? history : { ...history, - stopRuns: history.stopRuns.filter((stop) => + stopRuns: history.stopRuns.some((stop) => drawnWhens.includes(stop.when), - ), + ) + ? history.stopRuns.filter((stop) => drawnWhens.includes(stop.when)) + : NO_STOPS, } const histories = drawn.map( (history) => (keepsSteps(history) ? history : { ...history, steps: null }), 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 32f6c0e3..3ff3bac2 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -960,6 +960,10 @@ async function stoppedRun( const atSpawn = when === `spawn` const after = when === `after` const warm = when === `warm` + // `note` (constructed only): the run is held right after its note line + // (ORACLE_GAPS_TEST_PAUSE_AT=note), the driver sends the stop, and then + // releases the hold, so the stop is taken before the check starts any process. + const atNote = when === `note` // With `abort`, no signal comes: a test of file a aborts the run's // process (`GAP_ABORT`), in worker threads, so the abort ends the process // that runs the check, as a V8 out-of-memory abort does. The run then @@ -1018,6 +1022,13 @@ async function stoppedRun( ...(atSpawn && onStart ? { ORACLE_GAPS_TEST_PAUSE_AFTER_STARTED: `1` } : {}), + ...(atNote + ? { + ORACLE_GAPS_TEST_PAUSE_AT: `note`, + ORACLE_GAPS_TEST_PAUSE_MARKER: join(pids, `at-note`), + ORACLE_GAPS_TEST_PAUSE_UNTIL: join(pids, `note-release`), + } + : {}), ...(after ? { ...base, @@ -1062,7 +1073,9 @@ async function stoppedRun( ? !stdout.includes(`oracle-gaps: done completed`) : warm ? !existsSync(join(pids, `warming`)) - : readdirSync(pids).length < 2) && + : atNote + ? !existsSync(join(pids, `at-note`)) + : readdirSync(pids).length < 2) && waited < 120_000; waited += 50 ) @@ -1080,7 +1093,9 @@ async function stoppedRun( ? stdout.includes(`oracle-gaps: done completed`) && !exited : warm ? existsSync(join(pids, `warming`)) && !exited - : readdirSync(pids).length >= 2 + : atNote + ? existsSync(join(pids, `at-note`)) && !exited + : readdirSync(pids).length >= 2 const strayWhileRunning = strays( dir, before, @@ -1103,8 +1118,10 @@ async function stoppedRun( if (win) writeFileSync(stopFile, ``) else child.kill(signal) } - // The `after` stop is sent while the exit is held; the hold is released now. + // The `after` stop is sent while the exit is held, and the `note` stop while + // the run is held at its note; each hold is released now. if (after) writeFileSync(join(pids, `after-release`), ``) + if (atNote) writeFileSync(join(pids, `note-release`), ``) // The hold beside the release file is marked when the CLI could not release it. const unreleased = join(pids, `after-release.unreleased`) const ended = await Promise.race([exit, sleep(30_000).then(() => false)]) @@ -2883,13 +2900,6 @@ async function driver(plan, observe) { await unwritableLogRuns(dir, files, how, plan.logLost), ) states.add(lostStateOf[plan.logLost]) - // The unsupervised run writes its own stopped line (stopNow): every run - // on win32, and the constructed unsupervised history on POSIX. - if ( - plan.logLost === `stop` && - (plan.unsupervised || process.platform === `win32`) - ) - states.add(`an unsupervised run stopped after its note`) } if (plan.outMode === `default`) states.add(`a run with the default output directory`) @@ -3019,6 +3029,13 @@ async function driver(plan, observe) { states.add(`a stop signal while the config warms`) continue } + // The unsupervised run writes its own stopped line (stopNow): every + // run on win32, and the constructed unsupervised history on POSIX. + if (stop.when === `note`) { + if (plan.unsupervised || process.platform === `win32`) + states.add(`an unsupervised run stopped after its note`) + continue + } if (stop.when === `abort`) { states.add(`a run whose process aborted`) continue @@ -5542,7 +5559,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, 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. 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; 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; 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 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 (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, 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); 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; 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; 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 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 (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 @@ -7456,14 +7473,14 @@ oracleProperty({ { // A run stopped after its note, unsupervised (the test-only hook // ORACLE_GAPS_TEST_UNSUPERVISED): the path every win32 run takes, where - // the run's own process writes its stopped line (stopNow). Its stream - // log is lost after the note, as in "a stream log lost after its note, - // then stopped", and its stop is the test stop file, taken once the - // hold at the note is released: one done line on each stream, the same - // on both. The stop lands before the check starts any process, so no - // process can outlive the run (an unsupervised run has no group to end; - // C 2026-11-13, Windows (e)). - name: `a stream log lost after its note, then stopped, unsupervised`, + // the run's own process writes its stopped line (stopNow). The run is + // held at its note (ORACLE_GAPS_TEST_PAUSE_AT), the driver sends the + // stop, and releases the hold: the note, then one stopped line on each + // stream. The stop lands before the check starts any process: an + // unsupervised run has no group to end, so a stop while the witness's + // test spins would leave that test's own child on POSIX (C 2026-11-13, + // Windows (e)), where win32 ends it with the run's job object. + name: `an unsupervised run stopped after its note`, enters: [`an unsupervised run stopped after its note`], build: (generated) => ({ ...generated, @@ -7484,8 +7501,9 @@ oracleProperty({ ordinary: false, budget: `two`, outMode: `explicit`, - logLost: `stop`, + stopWitness: true, unsupervised: true, + stopRuns: [{ signal: `SIGINT`, pool: `threads`, when: `note` }], }), }, { diff --git a/packages/oracles/scripts/e2e-shards.mjs b/packages/oracles/scripts/e2e-shards.mjs index d6a15eca..b4ad7158 100644 --- a/packages/oracles/scripts/e2e-shards.mjs +++ b/packages/oracles/scripts/e2e-shards.mjs @@ -46,7 +46,7 @@ export const shards = { `fixed seed 20261105: a daemon check with the default output directory, unsupervised`, `fixed seed 20261105: a stop before the CLI starts`, `fixed seed 20261105: a stop by SIGTERM as the CLI starts`, - `fixed seed 20261105: a stream log lost after its note, then stopped, unsupervised`, + `fixed seed 20261105: an unsupervised run stopped after its note`, `fixed seed 20261105: a start refuses a dangling claim`, `fixed seed 20261105: a supervised check with no ps on its PATH`, `fixed seed 20261105: a stream log that cannot be written`, @@ -189,7 +189,7 @@ export const shards = { `determinism: constructed history: a supervised child exits when its supervisor is killed`, `determinism: constructed history: a stop before the CLI starts`, `determinism: constructed history: a stop by SIGTERM as the CLI starts`, - `determinism: constructed history: a stream log lost after its note, then stopped, unsupervised`, + `determinism: constructed history: an unsupervised run stopped after its note`, `determinism: constructed history: a start refuses a dangling claim`, `determinism: constructed history: a supervised check with no ps on its PATH`, `determinism: constructed history: a stream log lost after its note, then stopped`, @@ -240,7 +240,7 @@ export const shards = { `random seed: a supervised child exits when its supervisor is killed`, `random seed: a stop before the CLI starts`, `random seed: a stop by SIGTERM as the CLI starts`, - `random seed: a stream log lost after its note, then stopped, unsupervised`, + `random seed: an unsupervised run stopped after its note`, `random seed: a start refuses a dangling claim`, `random seed: a supervised check with no ps on its PATH`, `random seed: a stream log lost after its note, then stopped`, diff --git a/packages/oracles/scripts/pr-shards.mjs b/packages/oracles/scripts/pr-shards.mjs index f6781a3f..ea97762b 100644 --- a/packages/oracles/scripts/pr-shards.mjs +++ b/packages/oracles/scripts/pr-shards.mjs @@ -305,7 +305,7 @@ export const partitions = { 'a failing owner under a config that --config names', 'a stop before the CLI starts', 'a stop by SIGTERM as the CLI starts', - 'a stream log lost after its note, then stopped, unsupervised', + 'an unsupervised run stopped after its note', 'a start refuses a dangling claim', 'a supervised check with no ps on its PATH', ]), @@ -614,7 +614,7 @@ export const partitions = { 'a reset check after its warm daemon was replaced', 'a stream log lost after its note, then completed', 'a supervised child exits when its supervisor is killed', - 'a stream log lost after its note, then stopped, unsupervised', + 'an unsupervised run stopped after its note', 'a supervised check with no ps on its PATH', ]), }, From 9c8110dbdde11988c9e401fd409629d412a83797 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Mon, 16 Nov 2026 14:16:04 +0000 Subject: [PATCH 57/62] fix(oracle-gaps): a start hold released by the stop, no ps, and a dangling claim reads as unreadable - The test-only hold after the started marker (ORACLE_GAPS_TEST_PAUSE_AFTER_STARTED) is released by the stop the CLI keeps (or, on win32, by the test stop file), never by time: a 200 ms hold let a late stop land after the supervisor had started its child (register C 2026-11-14, "Determinism under load covers witnesses too"). - The supervised child tells that it leads its own process group by a signal 0 to the group its pid names, not through `ps -o pgid= -p`, which a slim container lacks and BusyBox's ps does not accept: every supervised check exited 3 there. - A run.pid that the claim's link finds and no read does (a link to no file) refuses as an unreadable claim, without writing its report into the directory; the "keeps changing" refusal wrote results.json and summary.md beside another run's claim. Co-authored-by: Isaac --- .changeset/gap-cli-stream-log.md | 2 +- README.md | 8 ++-- packages/oracles/oracle-gaps/index.mjs | 58 ++++++++++++-------------- 3 files changed, 32 insertions(+), 36 deletions(-) diff --git a/.changeset/gap-cli-stream-log.md b/.changeset/gap-cli-stream-log.md index 26f3ab92..d955aff3 100644 --- a/.changeset/gap-cli-stream-log.md +++ b/.changeset/gap-cli-stream-log.md @@ -4,4 +4,4 @@ The `oracle-gaps` CLI now writes the lines it streams on stderr to `stream.log` in the output directory too, in order, cold and through `--daemon`, and the first line of a check on both streams names that file: `oracle-gaps: note log /stream.log`. An agent that starts a cold check in the background can read the run's progress and its done line there while it runs. A check through `--daemon` prints its lines at the end of its check, so its progress is readable there only after it ends. -A run takes its output directory's claim in `run.pid` before it starts, and a second run on a live directory refuses without writing into it. A `run.pid` that names no running process (stale), that is empty, or that cannot be read also refuses the run, and the refusal's fix line tells you to delete `/run.pid` if no run uses that directory. The CLI never takes over another run's claim. A refusal of a run with no `--out` is written to the default output directory the run would have used. +A run takes its output directory's claim in `run.pid` before it starts, and a second run on a live directory refuses without writing into it. A `run.pid` that names no running process (stale), that is empty, or that cannot be read (a directory, or a link to no file) also refuses the run, without writing into the directory, and the refusal's fix line tells you to delete `/run.pid` if no run uses that directory. The CLI never takes over another run's claim. A refusal of a run with no `--out` is written to the default output directory the run would have used. On Linux and macOS the run's supervisor needs no external command: a container without `ps`, or with BusyBox's `ps`, runs the check as any other system does. diff --git a/README.md b/README.md index 7d3a6a71..4bc540f1 100644 --- a/README.md +++ b/README.md @@ -145,9 +145,11 @@ agent. - `ORACLE_GAPS_TEST_STARTED` names a file that the CLI writes as its first project statement, before any project module loads, so a test can tell a stop that came before the CLI started from one that came during its loads. - - `ORACLE_GAPS_TEST_PAUSE_AFTER_STARTED` (milliseconds) blocks the CLI for that - long right after the started file is written, so a stop sent on seeing the - file lands inside the pause. + - `ORACLE_GAPS_TEST_PAUSE_AFTER_STARTED` (any value) holds the CLI right after + the started file is written until the CLI has kept a stop signal (or, with + `ORACLE_GAPS_TEST_STOP`, until that file exists), so a stop sent on seeing + the file lands during the CLI's loads. The stop releases the hold, not a + time; a hold that sees no stop within 60 s fails the run loudly. - `ORACLE_GAPS_TEST_PAUSE_AT` names one point at which the CLI holds: `note` (after the note line is written, before the check starts), and `child` (a supervised child, before it writes anything; it waits on timers, so its diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index cd29a91e..028f8275 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -125,7 +125,7 @@ // CLI's modules load (review of #57, P1): a signal during the loads is kept // and acted on once the stream log's note is written, so a stop as the CLI starts still // leaves the note and one done line. Only Node's own start is before them. -import { execFileSync, spawn } from 'node:child_process' +import { spawn } from 'node:child_process' import { appendFileSync, existsSync, @@ -152,12 +152,24 @@ process.on(`SIGTERM`, keepEarly) // tell a stop that came before the CLI started from one that came during its loads. if (process.env.ORACLE_GAPS_TEST_STARTED) writeFileSync(process.env.ORACLE_GAPS_TEST_STARTED, ``) -// A test-only pause after the marker (ORACLE_GAPS_TEST_PAUSE_AFTER_STARTED, ms): -// it blocks this thread synchronously, so a stop sent during it lands before the -// handlers below are installed (the widened witness of review F2). Inert unless set. -const pauseMs = Number(process.env.ORACLE_GAPS_TEST_PAUSE_AFTER_STARTED ?? 0) -if (pauseMs > 0) - Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, pauseMs) +// A test-only hold after the marker (ORACLE_GAPS_TEST_PAUSE_AFTER_STARTED): the +// CLI waits there until it has kept a stop (keepEarly), or until the test stop +// file exists (win32, ORACLE_GAPS_TEST_STOP), so a stop a test sends on seeing the +// marker lands before the handlers below are installed, whatever the load. The +// stop releases the hold, never the time; a hold with no stop within 60 s fails +// loudly. Inert unless set. +if (process.env.ORACLE_GAPS_TEST_PAUSE_AFTER_STARTED !== undefined) { + const stopFile = process.env.ORACLE_GAPS_TEST_STOP + for ( + let waited = 0; + early === undefined && !(stopFile !== undefined && existsSync(stopFile)); + waited += 10 + ) { + if (waited >= 60_000) + throw new Error(`the hold after the started marker saw no stop in 60 s`) + await new Promise((resolve) => setTimeout(resolve, 10)) + } +} const { parseArgs, usage } = await import(`./args.mjs`) const { endRun, Refusal } = await import(`./ending.mjs`) @@ -241,12 +253,9 @@ function claimOut(out) { if (error.code !== `EEXIST`) throw claimCannotWrite(out, claim, error) const holder = readHolder(claim) if (holder === undefined && attempt < 3) continue - if (holder === undefined) - throw new Refusal( - `run.pid in ${posix(out)} keeps changing`, - `rerun the check; if no run uses ${posix(out)}, delete ${posix(claim)}`, - ) - throw heldRefusal(out, claim, holder) + // A claim that the link finds and no read does (a link to no file, or + // one released and retaken on every try) can't be read. + throw heldRefusal(out, claim, holder ?? UNREADABLE) } } } finally { @@ -554,29 +563,14 @@ function signalGroup(group, signal) { function watchSupervisor(supervisor) { // Only a process that leads its own group kills it: an inherited variable // (a test's child, say) must not name a group this process does not lead. A - // group that cannot be read fails the run: the watchdog would not be armed. - const group = groupOf(process.pid) - if (group === undefined) - throw new Error( - `the run cannot read its process group, so it cannot arm its supervisor watchdog`, - ) - if (group !== process.pid) return + // group whose id is this process's pid exists only while this process leads + // it, so a signal 0 to it tells, with no external command (no `ps`, which a + // slim container lacks; review of #57, A7). + if (!signalGroup(process.pid, 0)) return setInterval(() => { if (process.ppid !== supervisor) process.kill(-process.pid, `SIGKILL`) }, 1000).unref() } -/** The process group of `pid` (POSIX, through ps); undefined when unknown. */ -function groupOf(pid) { - try { - return Number( - execFileSync(`ps`, [`-o`, `pgid=`, `-p`, String(pid)], { - encoding: `utf8`, - }).trim(), - ) - } catch { - return undefined - } -} /** * A test-only stop (ORACLE_GAPS_TEST_STOP, #58): once the named file exists, the * stop is taken as a SIGINT would be. Inert unless set. From d2d723592f74be77eee2650774ddd0795ba0aff3 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Mon, 16 Nov 2026 14:27:05 +0000 Subject: [PATCH 58/62] test(oracle-gaps): a blocked log refuses after the arguments and before the check With logBlocked drawn again, a random seed (-118669542) drew a blocked log beside a declaration fault: the driver claimed "refused ", a state the property does not declare, and the model owed the runtime faults' refusal (brokenVitest, projects) before the log's and the log's before an argument refusal (outsideSource). The CLI refuses its arguments first, then a log it cannot write, then what the check finds (P10 as amended in v21.2: an argument refusal owes the done line alone, and once a check starts its first line is the note). The model's refusal now follows those stages, and the driver claims a fault's refusal only when the run reached its fault. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-model-oracle.mjs | 24 +++++++++++-------- .../gap-report-oracle.property.test.mjs | 12 ++++++---- 2 files changed, 22 insertions(+), 14 deletions(-) diff --git a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs index cd60cefa..d8be42a9 100644 --- a/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs +++ b/packages/oracles/oracle-gaps/gap-report-model-oracle.mjs @@ -4398,17 +4398,26 @@ const ownsNothing = (plan) => const BROKEN_SUITE = `broken (b.*) $x it's` function refusal(plan) { + // The stages of a run decide which refusal comes first (P10 as amended in + // v21.2, R10): the arguments, before any check starts; then the stream log, + // which the run opens before its first line (the maintainer's decision of + // 2026-11-12); then the check itself, whatever it would find. + // A `--source` outside the package is an argument the CLI refuses before + // it starts a check (the argument rules that the static oracle judges), + // so its stdout has no line that names a stream log. + if (plan.fault === `outsideSource`) + return { cause: `outside the package`, arguments: true } + // A stream log that cannot be written is refused before the check starts + // (the CLI opens the log before its first line, index.mjs), so its stdout + // owes its done line alone. + if (plan.logBlocked === true) + return { cause: `the stream log`, arguments: true } // A Vitest that does not load, and a config the runner cannot honor, refuse // the run rather than leave every mutant unreached (maintainer decision, // 2026-11-08). if (plan.fault === `brokenVitest`) return { cause: `vitest`, runtime: true } if (plan.fault === `projects`) return { cause: `test.projects`, runtime: true } - // A stream log that cannot be written is refused before the check starts - // (the CLI opens the log before its first line, index.mjs), so its stdout - // owes its done line alone. - if (plan.logBlocked === true) - return { cause: `the stream log`, arguments: true } if (plan.fault === `badEntry`) return { cause: `${SOURCE}#nope` } // An owns entry that names a missing file (a test file's declaration) is // found by the analysis, after the check has started, so this refusal @@ -4416,11 +4425,6 @@ function refusal(plan) { // is not a file of the package, is the static oracle's `absentSource`. if (plan.fault === `missingSource`) return { cause: `src/missing.ts` } if (plan.fault === `nonLiteral`) return { cause: `b.test.ts` } - // A `--source` outside the package is an argument the CLI refuses before - // it starts a check (the argument rules that the static oracle judges), - // so its stdout has no line that names a stream log. - if (plan.fault === `outsideSource`) - return { cause: `outside the package`, arguments: true } // The analysis reads the test files that the package's Vitest config // includes (index.mjs, step 2), so a config that does not load is named // before anything the analysis would find. The cause names the config 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 3ff3bac2..dd4246ab 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -2906,8 +2906,11 @@ async function driver(plan, observe) { // The cold run is supervised off win32, and its PATH named no command. if (plan.psMissing && process.platform !== `win32` && cli.exit === 0) states.add(`a supervised check with no ps on its PATH`) - if (plan.logBlocked && cli.exit === 2) - states.add(`a stream log that cannot be written`) + // A blocked log refuses the run before its check starts, and only an + // argument refusal comes before it (the model's `refusal`). + const logRefused = + plan.logBlocked && plan.fault !== `outsideSource` && cli.exit === 2 + if (logRefused) states.add(`a stream log that cannot be written`) if (overlapping && overlapping.overlap.exit === 2) states.add(`two runs on one output directory`) if (tornRead && cli.reported) @@ -3046,8 +3049,9 @@ async function driver(plan, observe) { ) } // Each kind of declaration fault is its own state, so each refusal has - // a history that depends on it. - if (plan.fault !== `none` && cli.exit !== 0) + // a history that depends on it. A run its blocked log refused never + // reached its fault. + if (plan.fault !== `none` && cli.exit !== 0 && !logRefused) states.add(`refused ${plan.fault}`) // A failing owner and a throwing setup file block mutants (law 14). if ( From 6c958ed3c111f3e8b907892bc736f7181c3f6395 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Mon, 16 Nov 2026 15:27:26 +0000 Subject: [PATCH 59/62] test(oracle-gaps): split the warm and abort stops of every outcome class into two histories On Windows the one history that held both stops took 557 s, and its job 10m16s, past P12's 10 minutes. Each stop now has its own constructed history over the same base, appended last, and each sits in its own Windows shard (4 and 5). The required states and the union of "every outcome class" are unchanged; the output directory stays drawn. Co-authored-by: Isaac --- .../gap-report-oracle.property.test.mjs | 92 ++++++++++++------- packages/oracles/scripts/e2e-shards.mjs | 9 +- packages/oracles/scripts/pr-shards.mjs | 19 ++-- 3 files changed, 77 insertions(+), 43 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 dd4246ab..3b6074f4 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -6867,39 +6867,6 @@ oracleProperty({ })), }), }, - { - // The second half of `every outcome class` (review of #73, P12): the warm and - // abort stop runs, over a base that enters only their states. Its stops and - // states are the other half of the original's; the union is checked by the - // framework's reach over both halves. - name: `every outcome class, the warm and abort stops`, - enters: stopsSecond, - build: (generated) => ({ - ...generated, - witness: `capture`, - wholeFile: `none`, - fault: `none`, - authored: { stmt: 0, kind: `apply` }, - stability: `insertGuard`, - steps: null, - ordinary: true, - configEnv: false, - native: `none`, - setupGlobal: false, - depSubpath: false, - unbuiltDep: false, - sourceSpelling: `plain`, - cliPath: `plain`, - boot: false, - budget: `two`, - pragma: false, - stopRuns: [ - { signal: `SIGINT`, pool: `threads`, when: `warm` }, - { signal: `SIGINT`, pool: `threads`, when: `abort` }, - ], - consoleOutput: true, - }), - }, { // A warm daemon replaced before the pause (review of #73, B2): the warm // check is served by one daemon, which is then stopped, so the paused @@ -7566,6 +7533,65 @@ oracleProperty({ psMissing: true, }), }, + { + // The second half of `every outcome class` (review of #73, P12) is split + // in two (P12: each Windows job under 9 minutes), each over the same base, + // which enters only its stop's state: the warm stop here, the abort stop + // below. With the first half, the union is checked by the framework's + // reach over every part (stopsSecond). + name: `every outcome class, the warm stop`, + enters: [`a stop signal while the config warms`], + build: (generated) => ({ + ...generated, + witness: `capture`, + wholeFile: `none`, + fault: `none`, + authored: { stmt: 0, kind: `apply` }, + stability: `insertGuard`, + steps: null, + ordinary: true, + configEnv: false, + native: `none`, + setupGlobal: false, + depSubpath: false, + unbuiltDep: false, + sourceSpelling: `plain`, + cliPath: `plain`, + boot: false, + budget: `two`, + pragma: false, + stopRuns: [{ signal: `SIGINT`, pool: `threads`, when: `warm` }], + consoleOutput: true, + }), + }, + { + // The abort stop of the second half of `every outcome class` (see the + // warm stop above): a test of file a aborts the run's process. + name: `every outcome class, the abort stop`, + enters: [`a run whose process aborted`], + build: (generated) => ({ + ...generated, + witness: `capture`, + wholeFile: `none`, + fault: `none`, + authored: { stmt: 0, kind: `apply` }, + stability: `insertGuard`, + steps: null, + ordinary: true, + configEnv: false, + native: `none`, + setupGlobal: false, + depSubpath: false, + unbuiltDep: false, + sourceSpelling: `plain`, + cliPath: `plain`, + boot: false, + budget: `two`, + pragma: false, + stopRuns: [{ signal: `SIGINT`, pool: `threads`, when: `abort` }], + consoleOutput: true, + }), + }, ]), }, resolve: resolveHistory, diff --git a/packages/oracles/scripts/e2e-shards.mjs b/packages/oracles/scripts/e2e-shards.mjs index b4ad7158..40d18e95 100644 --- a/packages/oracles/scripts/e2e-shards.mjs +++ b/packages/oracles/scripts/e2e-shards.mjs @@ -291,9 +291,12 @@ export const shards = { ], // 522 s in the measured run, about 221 s idle. 'e2e-5': [ - `fixed seed 20261105: every outcome class, the warm and abort stops`, - `random seed: every outcome class, the warm and abort stops`, - `determinism: constructed history: every outcome class, the warm and abort stops`, + `fixed seed 20261105: every outcome class, the warm stop`, + `fixed seed 20261105: every outcome class, the abort stop`, + `random seed: every outcome class, the warm stop`, + `random seed: every outcome class, the abort stop`, + `determinism: constructed history: every outcome class, the warm stop`, + `determinism: constructed history: every outcome class, the abort stop`, `determinism: constructed history: a stop with the default output directory`, `determinism: constructed history: a daemon check with the default output directory`, `determinism: constructed history: a daemon check with the default output directory, unsupervised`, diff --git a/packages/oracles/scripts/pr-shards.mjs b/packages/oracles/scripts/pr-shards.mjs index ea97762b..21497ae6 100644 --- a/packages/oracles/scripts/pr-shards.mjs +++ b/packages/oracles/scripts/pr-shards.mjs @@ -309,13 +309,15 @@ export const partitions = { 'a start refuses a dangling claim', 'a supervised check with no ps on its PATH', ]), - // Both halves of `every outcome class` (134 s and 155 s on the CI runner), - // a second daemon check (101 s), and two small units. The second half - // is named here: `every outcome class` alone matches the first half only, - // and the second would fall into the rest (shard 3). + // Every part of `every outcome class` (the first half took 134 s on the CI + // runner, and the warm and abort stops, together 155 s, are now two + // histories), a second daemon check (101 s), and two small units. The + // stop parts are named here: `every outcome class` alone matches the + // first half only, and the others would fall into the rest (shard 3). 2: anyOf([ 'every outcome class', - 'every outcome class, the warm and abort stops', + 'every outcome class, the warm stop', + 'every outcome class, the abort stop', 'a second daemon check of the budget witness', 'a declaration fault: brokenVitest', 'an edit that changed the cold result after a hang replaced the only context', @@ -534,8 +536,11 @@ export const partitions = { 1: anyOf(['an edit sequence over the witness module']), 2: anyOf(['every outcome class']), 3: anyOf(['a declaration fault: noTypescript']), - 4: anyOf(['every outcome class, the warm and abort stops']), - 5: anyOf(['an edit sequence through the daemon']), + 4: anyOf(['every outcome class, the warm stop']), + 5: anyOf([ + 'an edit sequence through the daemon', + 'every outcome class, the abort stop', + ]), 6: anyOf([ 'a batch whose run rejects', 'a second daemon check of the budget witness', From c42eec9862f79c669569bec59900425472e1eb2f Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Mon, 16 Nov 2026 16:28:37 +0000 Subject: [PATCH 60/62] test(oracle-gaps): the warm and abort stop histories run over the stop witness alone Split over the first half's heavy base, each stop history cost that base again: Linux fixed-seed 2/3 took 10m26s, and on Windows the abort stop, which fails there on main's win32 witness (#79), shrank through three heavy histories (592 s, job 12m41s). Each now runs over the stop witness alone, the base of "a stop with the default output directory": the same two states, cheaper histories (R7). Locally each passes in under 15 s, and a mutant of the stopped line and one of the abort's error line are each killed. Co-authored-by: Isaac --- .../gap-report-oracle.property.test.mjs | 65 ++++++++++--------- packages/oracles/scripts/pr-shards.mjs | 4 +- 2 files changed, 35 insertions(+), 34 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 3b6074f4..c330756e 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -7535,33 +7535,35 @@ oracleProperty({ }, { // The second half of `every outcome class` (review of #73, P12) is split - // in two (P12: each Windows job under 9 minutes), each over the same base, - // which enters only its stop's state: the warm stop here, the abort stop - // below. With the first half, the union is checked by the framework's - // reach over every part (stopsSecond). + // in two, each over the stop witness alone (one owned function), so each + // costs a run of that witness and a stop, and a failing stop shrinks + // through cheap histories (P12: each Windows job under 9 minutes). Each + // enters only its stop's state: the warm stop here, the abort stop below. + // The heavy base they shared is the first half's, which enters every + // other state; the union is checked by the framework's reach over every + // part (stopsSecond). Equal reach, cheaper histories (R7). name: `every outcome class, the warm stop`, enters: [`a stop signal while the config warms`], build: (generated) => ({ ...generated, - witness: `capture`, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], wholeFile: `none`, + witness: false, + stopWitness: true, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, fault: `none`, - authored: { stmt: 0, kind: `apply` }, - stability: `insertGuard`, + stability: `none`, steps: null, - ordinary: true, - configEnv: false, - native: `none`, - setupGlobal: false, - depSubpath: false, - unbuiltDep: false, - sourceSpelling: `plain`, - cliPath: `plain`, - boot: false, + ordinary: false, budget: `two`, - pragma: false, stopRuns: [{ signal: `SIGINT`, pool: `threads`, when: `warm` }], - consoleOutput: true, }), }, { @@ -7571,25 +7573,24 @@ oracleProperty({ enters: [`a run whose process aborted`], build: (generated) => ({ ...generated, - witness: `capture`, + functions: [[{ kind: `push`, quote: `'` }]], + containers: [], + overloads: [], + owners: [`a`], + library: [], + libraryOwners: [], + runes: [], wholeFile: `none`, + witness: false, + stopWitness: true, + tests: [{ ...judging(`a`, `fixed seed`, 1), fn: 0 }], + authored: null, fault: `none`, - authored: { stmt: 0, kind: `apply` }, - stability: `insertGuard`, + stability: `none`, steps: null, - ordinary: true, - configEnv: false, - native: `none`, - setupGlobal: false, - depSubpath: false, - unbuiltDep: false, - sourceSpelling: `plain`, - cliPath: `plain`, - boot: false, + ordinary: false, budget: `two`, - pragma: false, stopRuns: [{ signal: `SIGINT`, pool: `threads`, when: `abort` }], - consoleOutput: true, }), }, ]), diff --git a/packages/oracles/scripts/pr-shards.mjs b/packages/oracles/scripts/pr-shards.mjs index 21497ae6..cf5410ae 100644 --- a/packages/oracles/scripts/pr-shards.mjs +++ b/packages/oracles/scripts/pr-shards.mjs @@ -310,8 +310,8 @@ export const partitions = { 'a supervised check with no ps on its PATH', ]), // Every part of `every outcome class` (the first half took 134 s on the CI - // runner, and the warm and abort stops, together 155 s, are now two - // histories), a second daemon check (101 s), and two small units. The + // runner; the warm and abort stops are two small histories over the stop + // witness alone), a second daemon check (101 s), and two small units. The // stop parts are named here: `every outcome class` alone matches the // first half only, and the others would fall into the rest (shard 3). 2: anyOf([ From ffc418c1c699c2ac48af9652f0140eb08cda6f21 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Mon, 16 Nov 2026 18:24:15 +0000 Subject: [PATCH 61/62] test(oracle-gaps): the rejected batch's note names its log on one line After #128 the rejected-batch history's output directory holds a line break, and the stream law judges that run. Its observation now carries the stream log, and the note it owes spells the path as every line of the stream does: a control character as its \uXXXX escape (C 2026-11-16 "The internal-error line"). RED: the note line splits in two. Co-authored-by: Isaac --- .../oracle-gaps/gap-report-oracle.property.test.mjs | 12 +++++++++++- 1 file changed, 11 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 68638d37..50806bb5 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -2954,6 +2954,8 @@ async function driver(plan, observe) { warnings: cli.warnings, stream: cli.stream, stdoutStream: cli.stdoutStream, + // Its stream log (law 15): the note that names it, and its lines. + log: cli.log, outDir: cli.outDir, errorLog: cli.ending?.errorLog, stackFrames: cli.ending?.stackFrames, @@ -4389,9 +4391,17 @@ function streamBreach(checkpoint, run, expected, plan) { * forward slashes (the Windows paths rule, register 2026-11-13); POSIX paths * are used unchanged. */ +// The note names the log as every line of the stream names a path: forward +// slashes on win32, and each control character, a line break included, as its +// `\uXXXX` escape, so the note stays one line (the register's C entry "The +// internal-error line", 2026-11-16). const logNoteOf = (run) => { - const outDir = + const outDir = ( process.platform === `win32` ? run.outDir.replaceAll(`\\`, `/`) : run.outDir + ).replace( + /[\u0000-\u001f\u007f\u2028\u2029]/g, + (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, `0`)}`, + ) return `oracle-gaps: note log ${outDir}/stream.log` } From 07766d3abcea4961b6d85b6a21de93d4c2741970 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Mon, 16 Nov 2026 18:24:35 +0000 Subject: [PATCH 62/62] fix(oracle-gaps): the note line escapes a control character in its log path A --out whose name holds a line break printed the note on two lines, on both streams; every other line of the stream names a path with its control characters escaped (#128). The note now does too. Co-authored-by: Isaac --- packages/oracles/oracle-gaps/index.mjs | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index 028f8275..2fe50edc 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -173,6 +173,8 @@ if (process.env.ORACLE_GAPS_TEST_PAUSE_AFTER_STARTED !== undefined) { const { parseArgs, usage } = await import(`./args.mjs`) const { endRun, Refusal } = await import(`./ending.mjs`) +// ending.mjs loads stream.mjs, so this import costs no load of its own. +const { escapeControls } = await import(`./stream.mjs`) // How long the group has to end after a stop signal before it is killed. const STOP_GRACE_MS = 2000 @@ -372,7 +374,9 @@ function startLog(out) { streamLog = path // The log is named in forward slashes on win32 (the Windows paths rule); POSIX // paths are unchanged. - const note = `oracle-gaps: note log ${posix(path)}\n` + // A line break in the path is written as its escape: the note stays one line + // (the register's C entry "The internal-error line"). + const note = `oracle-gaps: note log ${escapeControls(posix(path))}\n` process.stdout.write(note) writeStream(note) testPause(`note`)