diff --git a/.changeset/gap-cli-stream-log.md b/.changeset/gap-cli-stream-log.md new file mode 100644 index 00000000..d955aff3 --- /dev/null +++ b/.changeset/gap-cli-stream-log.md @@ -0,0 +1,7 @@ +--- +'@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 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 (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 192c7c9c..92277cc7 100644 --- a/README.md +++ b/README.md @@ -131,25 +131,47 @@ agent. 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. 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 and no done line. `--stop-daemon` prints nothing. 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, and none changes an outcome by itself. - - `ORACLE_GAPS_TEST_HOLD_EXIT_MS` holds the run's exit after its done line. + - `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. A hold the CLI cannot + release is marked by a `.unreleased` file. - `ORACLE_GAPS_TEST_WARM_PROBE` makes the first config warm-up wait where a stop signal can reach it. - `ORACLE_GAPS_TEST_STOP` names a file whose appearance makes the CLI take a stop as a SIGINT would (the win32 stop, which has no signal to deliver). - - `ORACLE_GAPS_TEST_PAUSE_AT` names one point at which the CLI blocks, with - `ORACLE_GAPS_TEST_PAUSE_MARK` naming a file the blocked process writes its - pid to: `daemon-reply` holds a daemon's reply after the check, and - `daemon-read` holds its first connection unread, once `ORACLE_GAPS_TEST_PAUSE_ARM` - names an existing file. The test kills the process by that pid, so no signal - is needed to pause on win32. Both marks are written whole (a temp file, then - a rename), and the test parses the pid as a positive integer before it sends - any signal. + - `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` (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 + orphan watchdog keeps running). A hold at `note` blocks synchronously. At + either point the CLI writes the file `ORACLE_GAPS_TEST_PAUSE_MARKER` (when + set) and waits until the file `ORACLE_GAPS_TEST_PAUSE_UNTIL` exists. + - `ORACLE_GAPS_TEST_PAUSE_MARK` and `ORACLE_GAPS_TEST_PAUSE_ARM` (daemon points): + `ORACLE_GAPS_TEST_PAUSE_AT` also names `daemon-reply` (holds a daemon's reply + after the check) and `daemon-read` (holds its first connection unread, once + `ORACLE_GAPS_TEST_PAUSE_ARM` names an existing file). The blocked process + writes its pid to `ORACLE_GAPS_TEST_PAUSE_MARK`, whole (a temp file, then a + rename), and the test parses the pid as a positive integer before it sends + any signal, so no signal is needed to pause on win32. - `ORACLE_GAPS_TEST_WAIT_MARK` names a file a request writes when its reply has not come `ORACLE_GAPS_TEST_WAIT_MS` after it was sent. A request has no timeout of its own: this timer starts with the request, and is cleared when @@ -161,6 +183,13 @@ 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 + child leads that group. - `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 per batch and diff --git a/packages/oracles/oracle-gaps/args.mjs b/packages/oracles/oracle-gaps/args.mjs index d8f7d02f..010c8c51 100644 --- a/packages/oracles/oracle-gaps/args.mjs +++ b/packages/oracles/oracle-gaps/args.mjs @@ -85,11 +85,24 @@ 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 } } +/** + * 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())) +} /** * The options of parsed arguments `args`, or the refusal of the first that * breaks the usage text. diff --git a/packages/oracles/oracle-gaps/daemon.mjs b/packages/oracles/oracle-gaps/daemon.mjs index 71837dba..44bcdca2 100644 --- a/packages/oracles/oracle-gaps/daemon.mjs +++ b/packages/oracles/oracle-gaps/daemon.mjs @@ -58,16 +58,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 }, ) // A test mark is written whole or not at all: its file exists only once it diff --git a/packages/oracles/oracle-gaps/ending.mjs b/packages/oracles/oracle-gaps/ending.mjs index f49adfdc..e5b3c680 100644 --- a/packages/oracles/oracle-gaps/ending.mjs +++ b/packages/oracles/oracle-gaps/ending.mjs @@ -46,8 +46,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 8837915b..6bda9f32 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( @@ -702,7 +705,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 }, ), @@ -838,7 +845,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 @@ -860,6 +867,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), + // #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), 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`), 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 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 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 (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 @@ -871,6 +968,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 @@ -895,20 +996,53 @@ 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 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`: 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). +const constructedNeutral = { + overlap: false, + spawnStop: false, + spawnOnStart: false, + logLost: false, + supervisorDeath: false, + unsupervised: false, + tornRows: false, + 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.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 }), (value) => { const history = - /** @type {{ witness: unknown, steps: unknown[] | null, tornRows: unknown, testRoot: unknown }} */ ( + /** @type {{ witness: unknown, steps: unknown[] | null, tornRows: unknown, testRoot: unknown, loadPlugin: unknown, claimScenario: unknown, logLost: unknown }} */ ( value ) if (!keepsSteps(history)) @@ -917,12 +1051,14 @@ const histories = drawn.map( // only the constructed history sets it) comes back as engaged, and a // rejected batch (rejectBatch, likewise) as none, so the arbitrary can // shrink it. Neither is therefore kept by a shrink. - const taken = - history.tornRows === false && - history.testRoot === `none` && - history.loadPlugin === false - ? value - : { ...history, tornRows: false, testRoot: `none`, loadPlugin: false } + const reset = Object.entries(constructedNeutral).every( + ([field, neutral]) => history[field] === neutral, + ) + ? value + : { ...history, ...constructedNeutral } + // 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), ) @@ -2598,7 +2734,7 @@ function resolveHistory(history) { ...exported, ...importer, ...dotGen, - ...(history.witness + ...(history.witness || stopsOnly(history) ? witness .filter( (w) => @@ -2606,6 +2742,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)) || + (stopsOnly(history) && w.id === `w_stop`) || (history.witness === `budget` && w.id === `w_slowpair`), ) .map((w) => ({ @@ -2991,7 +3128,37 @@ 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`, + // 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, + spawnSignal: history.spawnSignal ?? `SIGINT`, + spawnDelay: history.spawnDelay ?? 0, + // 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`, @@ -4233,6 +4400,20 @@ 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). @@ -4240,9 +4421,12 @@ function refusal(plan) { if (plan.fault === `projects`) return { cause: `test.projects`, runtime: 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` } - if (plan.fault === `outsideSource`) return { cause: `outside the package` } // 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 @@ -4341,6 +4525,7 @@ const declarationFaults = [ `nonLiteral`, `outsideSource`, ] +const outModeOf = (history) => history.outMode ?? `explicit` const reachesRun = (history) => !declarationFaults.includes(history.fault ?? `none`) @@ -4399,21 +4584,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) @@ -5877,8 +6063,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, 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) @@ -5897,13 +6088,35 @@ 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 (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 9f0e38dd..50806bb5 100644 --- a/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs +++ b/packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs @@ -380,7 +380,22 @@ * are the stdout summary (unused: the CLI prefixes it), refusal blocks, * indented baseline lines under a prefixed head line, `--help`'s usage * text, and the lines and blocks that Node, V8, esbuild, and Vite print; - * each is told by its own shape, and no other line is exempt. A check through the daemon streams the same lines. + * each is told by its own shape, and no other line is exempt. A check through the daemon streams the same lines. The + * 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. 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 @@ -503,6 +518,8 @@ import { spawn, spawnSync } from 'node:child_process' import { cpSync, existsSync, + lstatSync, + statSync, mkdirSync, mkdtempSync, readdirSync, @@ -597,6 +614,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 @@ -613,14 +642,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. @@ -653,9 +685,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`) @@ -781,6 +812,22 @@ const retentionLinesOf = (file) => .filter(Boolean) .map((line) => JSON.parse(line)) : [] +// The lines of the check that wrote to `out`. A default output directory is +// known only from the run's note line, which spells it in forward slashes on +// win32 (the Windows paths rule), so both spellings are compared that way. +const linesOfRun = (lines, out) => + lines.filter( + (line) => + out !== undefined && + typeof line.run === `string` && + posix(line.run) === posix(out), + ) +// The output directory a run without `--out` chose: its note line names the +// stream log there (law 15). +const chosenOut = (stdout) => + `${stdout ?? ``}` + .split(`\n`)[0] + .match(/^oracle-gaps: note log (.*)\/stream\.log$/)?.[1] /** * Writes the fixture's files and runs the CLI on it. A file of an earlier @@ -804,10 +851,15 @@ function runCli(dir, files, how = {}) { const before = new Set(filesUnder(dir)) const { args, out: outBase } = cliArgs(dir, files, how) // Each call has its own output directory: its retention lines are then its own, even when a - // daemon serves several checks of one test. `outBreak` puts a line break in its name, where the + // daemon serves several checks of one test. A run with the default output directory names + // no --out (the CLI picks a fresh one). `outBreak` puts a line break in its name, where the // platform allows one, so that a line that names the directory must escape it. - const out = `${outBase}-${++runSeq}${how.outBreak ? `\nbreak` : ``}` - args[args.indexOf(`--out`) + 1] = out + const out = + outBase === undefined + ? undefined + : `${outBase}-${++runSeq}${how.outBreak ? `\nbreak` : ``}` + if (out !== undefined) args[args.indexOf(`--out`) + 1] = out + if (how.logBlocked) mkdirSync(join(out, `stream.log`), { recursive: true }) // The retention hook (ORACLE_GAPS_TEST_RETENTION): one line per batch, // written beside the run's own temporary files, not in the package. // One hook file per package: a daemon keeps the environment of the call that started it, so every call @@ -818,13 +870,27 @@ function runCli(dir, files, how = {}) { encoding: `utf8`, timeout: 300_000, maxBuffer: 64 * 1024 * 1024, - env: { ...cleanEnv(), ORACLE_GAPS_TEST_RETENTION: hook, ...how.env }, + // 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(), + ORACLE_GAPS_TEST_RETENTION: hook, + ...pathEnv(how), + ...how.env, + ...(how.unsupervised === true + ? { ORACLE_GAPS_TEST_UNSUPERVISED: `1` } + : {}), + }, }) // Each line names its check's output directory, so this call keeps every // line for its own directory, whichever process wrote it (retentionBreaches // judges the writer). - const checkPid = checkPidOf(out) - const retention = retentionLinesOf(hook).filter((line) => line.run === out) + // A default output directory is removed once the run is read, so its + // check's pid and lines are read first. + const ranIn = out ?? chosenOut(child.stdout) + const checkPid = ranIn === undefined ? undefined : checkPidOf(ranIn) + const retention = linesOfRun(retentionLinesOf(hook), ranIn) const run = readRun( dir, out, @@ -843,7 +909,7 @@ function runCli(dir, files, how = {}) { ?.slice(label.length) return { ...run, - strayWrites: strays(dir, before, relative(dir, out)), + strayWrites: strays(dir, before, out && relative(dir, out)), replay, retention, checkPid, @@ -863,8 +929,31 @@ const strays = (dir, before, own, running = false) => !before.has(file) && !(running && /^\.oracle-gaps-\d+\//.test(file)) && // The one path a run may write under: the --out the driver gave it (cliArgs names it). - !(file === own || file.startsWith(`${own}/`)), + // A run with the default output directory may write nothing in the package. + !(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 @@ -876,21 +965,37 @@ const strays = (dir, before, own, running = false) => * 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_EXIT_MS`, 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, files, how, ids, { signal, pool, when }) { +async function stoppedRun( + dir, + files, + how, + ids, + { signal, pool, when, delay = 0, onStart = false }, +) { + // `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` + // `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 @@ -905,32 +1010,74 @@ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { // names, as a SIGINT), so the run is observed as SIGINT (see below). const win = process.platform === `win32` const stopFile = `${pids}-stop` - const { args } = cliArgs(dir, files, { + const { args, out: given } = cliArgs(dir, files, { ...how, outName: `out-stop`, contexts: 1, only: ids, pool: abort ? `threads` : pool, }) + // The started marker: the CLI writes it as its first statement (index.mjs). + const startedPath = join(pids, `started`) // The retention hook is set on every stop, so a stopped run's completed batches are judged too. // Every stop of a history writes under out-stop, so this run's lines are the ones appended after // the lines already in the file. const hook = hookOf(dir) const earlierLines = retentionLinesOf(hook).length - const base = { ...cleanEnv(), ORACLE_GAPS_TEST_RETENTION: hook } - const env = after - ? { ...base, ORACLE_GAPS_TEST_HOLD_EXIT_MS: `500` } - : warm - ? { ...base, ORACLE_GAPS_TEST_WARM_PROBE: join(pids, `warming`) } - : abort - ? { ...base, GAP_ABORT: `1` } - : { ...base, GAP_STOP_DIR: pids } + 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 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: `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, + ORACLE_GAPS_TEST_HOLD_UNTIL: join(pids, `after-release`), + } + : warm + ? { ...base, ORACLE_GAPS_TEST_WARM_PROBE: join(pids, `warming`) } + : abort + ? { ...base, GAP_ABORT: `1` } + : { ...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) => { @@ -953,11 +1100,14 @@ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { let waited = 0; !exited && !abort && + !atSpawn && (after ? !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 ) @@ -969,23 +1119,47 @@ 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 + : atNote + ? existsSync(join(pids, `at-note`)) && !exited + : readdirSync(pids).length >= 2 const strayWhileRunning = strays( dir, before, - relative(dir, join(dir, `out-stop`)), + given === undefined ? undefined : relative(dir, given), true, ) + // 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(holdMark) && !exited && waited < 30_000; + waited += 1 + ) + await sleep(1) + if (atSpawn) await sleep(delay) if (!abort) { if (win) writeFileSync(stopFile, ``) else child.kill(signal) } + // 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)]) 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) @@ -1006,11 +1180,31 @@ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { // 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 }) - return { + const out = given ?? chosenOut(stdout) ?? join(dir, `no-output`) + const scratchNames = [ + [how.cli ?? here, ``], + [dir, ``], + ...(given === undefined ? [[out, ``]] : []), + ] + const result = { // The signal the CLI took: the hook's SIGINT on win32. signal: win ? `SIGINT` : signal, + ...startMarks, + stdoutLength: stdout.length, + stderrLength: stderr.length, pool, spun, ended, @@ -1018,25 +1212,21 @@ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { strayWhileRunning, when: when ?? `run`, // The batches this run completed, each with its retention line (the hook above). - retention: retentionLinesOf(hook) - .slice(earlierLines) - .filter((line) => line.run === join(dir, `out-stop`)), - checkPid: checkPidOf(join(dir, `out-stop`)), + retention: linesOfRun(retentionLinesOf(hook).slice(earlierLines), out), + checkPid: checkPidOf(out), // Whether a refusal's block reached stderr: a stop is never a refusal. refused: stderr.split(`\n`).some((line) => line.startsWith(`refused: `)), 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, scratchNames), + log: streamLogOf(out, stderr, stdout, (text) => + 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. @@ -1044,10 +1234,13 @@ async function stoppedRun(dir, files, how, ids, { signal, pool, when }) { /^\.oracle-gaps-\d+$/.test(name), ), // What else it left in the package. - left: strays(dir, before, relative(dir, join(dir, `out-stop`))).filter( + left: strays(dir, before, given && relative(dir, given)).filter( (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 } /** @@ -1107,6 +1300,391 @@ 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). + */ +/** 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`, + 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`), 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, + 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, 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] + 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 = [] + const startRun = () => { + const got = { stdout: ``, stderr: `` } + const child = spawn(process.execPath, args, { + cwd: repo, + env: cleanEnv(), + stdio: [`ignore`, `pipe`, `pipe`], + }) + children.push(child) + child.stdout.on(`data`, (chunk) => { + got.stdout += chunk + }) + child.stderr.on(`data`, (chunk) => { + got.stderr += chunk + }) + const timer = setTimeout(() => child.kill(`SIGKILL`), 30_000) + return new Promise((resolvePromise) => { + child.on(`close`, (code) => { + clearTimeout(timer) + resolvePromise({ ...got, code }) + }) + }) + } + 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. 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` + // 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, + 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: + scenario === `unreadable` + ? existsSync(claim) && statSync(claim).isDirectory() + : scenario === `dangling` + ? lstatSync(claim, { throwIfNoEntry: false })?.isSymbolicLink() === + true && !existsSync(gone) + : existsSync(claim) && readFileSync(claim, `utf8`) === written, + otherFiles: readdirSync(out).filter((name) => name !== `run.pid`), + } +} + +/** + * 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) { + // 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`) + 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, + // 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`], + }) + 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 + const names = [ + [out, ``], + [dir, ``], + ] + return { + ending, + exit: code, + signal, + stdout: namedScratch(got.stdout, names), + stderr: namedScratch(got.stderr, names), + logIsDirectory: existsSync(log) && statSync(log).isDirectory(), + } + } finally { + clearTimeout(timer) + } +} + +/** 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 `)) + +/** + * 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 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, + // 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`], + }) + // `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(`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)) + throw new Error(`the supervisor ended before its child paused`) + childPid = Number(readFileSync(`${started}.child`, `utf8`)) + supervisor.kill(`SIGKILL`) + const { signal } = await exited + for (let waited = 0; waited < 5000; waited += 50) { + try { + process.kill(childPid, 0) + } catch { + childGone = true + break + } + await sleep(50) + } + return { childGone, supervisorSignal: signal } + } finally { + clearTimeout(timer) + // 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, ``) + } +} + +async function overlappingRuns(dir, files, how) { + writeFixture(dir, files) + const before = new Set(filesUnder(dir)) + const { args, out } = cliArgs(dir, files, how) + // Both runs carry the retention hook; only the first one runs a check. + const hook = hookOf(dir) + const start = (holdUntilFile) => { + const child = spawn(process.execPath, args, { + cwd: repo, + // 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(), + ORACLE_GAPS_TEST_RETENTION: hook, + ...(holdUntilFile === undefined + ? {} + : { ORACLE_GAPS_TEST_HOLD_UNTIL: holdUntilFile }), + }, + 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 } + } + // 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 + }) + // 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`) && + !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 + 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, + 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, relative(dir, out)), + retention: linesOfRun(retentionLinesOf(hook), out), + checkPid: checkPidOf(out), + }, + overlap: { + exit: refused.exit, + // 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), + }, + } +} + // 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 @@ -1125,13 +1703,18 @@ async function runClisAtOnce(dir, files, hows, outs = []) { return Promise.all( hows.map(async (how) => { const { args, out: outBase } = cliArgs(dir, files, how) - const out = `${outBase}-${++runSeq}` + const out = outBase === undefined ? undefined : `${outBase}-${++runSeq}` outs.push(out) - args[args.indexOf(`--out`) + 1] = out + if (out !== undefined) args[args.indexOf(`--out`) + 1] = out 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, @@ -1151,12 +1734,13 @@ async function runClisAtOnce(dir, files, hows, outs = []) { resolvePromise(code) }) }) + // A default output directory is removed once the run is read, so its + // check's pid and lines are read first. + const ranIn = out ?? chosenOut(stdout) + const retention = linesOfRun(retentionLinesOf(hook), ranIn) + const checkPid = ranIn === undefined ? undefined : checkPidOf(ranIn) const run = readRun(dir, out, status, stderr, how.cli ?? here, stdout) - return { - ...run, - retention: retentionLinesOf(hook).filter((line) => line.run === out), - checkPid: checkPidOf(out), - } + return { ...run, retention, checkPid } }), ) } @@ -1182,9 +1766,23 @@ function namedScratch(text, names) { .replaceAll(pathToFileURL(path).href, name) .replaceAll(path, name) .replaceAll(posix(path), name) - return named - .replaceAll(/\.oracle-gaps-\d+/g, `.oracle-gaps-`) - .replaceAll(/session-\d+/g, `session-`) + // 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-`) + // 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. */ @@ -1249,6 +1847,33 @@ const exemptBlocks = [ * - `errors`: how many internal error lines (`oracle-gaps: error `) it has, * and `errorLogs`, the log each of them names (`its stack is in `). */ +/** + * 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) { + // 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`) + } 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() @@ -1312,20 +1937,55 @@ 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 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. } @@ -1366,19 +2026,25 @@ function readRun(dir, out, status, stderr, cli, stdout) { .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(), + // 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\))?: /, @@ -1402,6 +2068,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 { @@ -1431,6 +2101,7 @@ function readRun(dir, out, status, stderr, cli, stdout) { ? 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 @@ -1644,6 +2315,9 @@ async function incremental(dir, plan, cli, copy, observe, states) { const key = fingerprint(files, state, step === `otherInstall`) const how = { 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`), @@ -1669,6 +2343,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`) // A check through the daemon of a state that nothing changed reuses // every run that the store keeps (the README's reuse contract: a run is // reused while its inputs are unchanged), so where no test reads the @@ -1710,6 +2386,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, stdoutGaps: [...midrunChecks.during.stdoutGaps].sort(), }, before: { @@ -1746,6 +2428,11 @@ async function incremental(dir, plan, cli, copy, observe, states) { // part of the contract), judged against its own results.json. stream: run.stream, stdoutStream: run.stdoutStream, + // Its stream log, and the output directory it names. + log: run.log, + outDir: run.outDir, + reported: run.reported, + reportState: run.reportState, stdoutGaps: [...run.stdoutGaps].sort(), // The first line of a failure, for the message; readRun has named // the scratch package and CLI copy in it. @@ -2188,6 +2875,10 @@ async function driver(plan, observe) { ordinary: plan.ordinary, sources: sourceArgument(plan, `${dir}.link`), budget: plan.budget, + outMode: plan.outMode, + logBlocked: plan.logBlocked, + unsupervised: plan.unsupervised, + psMissing: plan.psMissing, cli: plan.cliPath === `spaced` ? copy : here, ...configArgs(plan), // A rejected batch ends through the internal error's ending, the one ending a history reaches that @@ -2202,16 +2893,24 @@ async function driver(plan, observe) { : {}), foreign: plan.foreign, } - const { replay, retention, checkPid, ...cli } = runCli( - dir, - files, - plan.tornRows - ? { - ...how, - env: { ...how.env, ORACLE_GAPS_TEST_TORN_ROWS: tornPolls }, - } - : how, - ) + // Two runs on one output directory: the second's refusal is its own + // observation (overlappingRuns). A torn-row check runs with its env. + const overlapping = plan.overlap + ? await overlappingRuns(dir, files, how) + : undefined + const { replay, retention, checkPid, ...cli } = + overlapping?.cli ?? + runCli( + dir, + files, + plan.tornRows + ? { + ...how, + env: { ...how.env, ORACLE_GAPS_TEST_TORN_ROWS: tornPolls }, + } + : how, + ) + if (overlapping) observe(`overlap`, overlapping.overlap) // The watchdog read a closing row while the worker wrote it: a hold // marks `reached` once two polls came after its first half. A hold that // waited 60 s with no poll marks `unreached`, and the witness fails @@ -2255,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, @@ -2293,6 +2994,37 @@ async function driver(plan, observe) { if (cli.exit === 3 && cli.ending?.errorLog) states.add(`a run ended in an internal error`) if (retention.length > 1) states.add(`a check that ran more than one batch`) + if (plan.claimScenario) { + const claim = await claimScenarioRuns(dir, files, how, plan.claimScenario) + 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`) + } + 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`) + // 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`) + // 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) states.add(`a capture row read while the worker wrote it`) if (cli.exit === 0 && !plan.consoleOutput) @@ -2345,7 +3077,20 @@ 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: plan.spawnSignal, + pool: `threads`, + when: `spawn`, + delay: plan.spawnDelay, + onStart: plan.spawnOnStart, + }, + ] + : []), + ]) { const { retention, checkPid, ...run } = await stoppedRun( dir, files, @@ -2371,6 +3116,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 @@ -2379,10 +3126,31 @@ 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`) { + 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`) { 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 @@ -2393,8 +3161,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 ( @@ -2839,7 +3608,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, plan) { for (const { value } of observations.filter( (o) => o.checkpoint === `incremental`, )) { @@ -2928,7 +3697,12 @@ 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 }) + // As the cold refusal: the default directory is predicted by its rule. + const breach = refusalBreach(daemon.ending, { + outKnown: true, + defaultOut: plan.outMode === `default`, + logNote: owesNote(expected) ? logNoteOf(daemon) : undefined, + }) if (breach) return violation( `incremental`, @@ -3009,6 +3783,94 @@ 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 claim = observations.find( + (o) => o.checkpoint === `claimScenario`, + )?.value + 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 = { + 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] + 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( + `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 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`, + `stopping`, + ) + 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) + 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 (pid `, + outKnown: false, + }) + if (breach) return violation(`overlap`, breach, `report-shaped ending`) + } // Law 15 holds for every run, an internal error's included: its error line and its done line are lines of // the stream (v21.2 P10, I3, I7, R10). The rest of a rejected batch's ending is judged below, after // retention. @@ -3060,7 +3922,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`, @@ -3069,7 +3931,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`, @@ -3141,12 +4005,28 @@ 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) has its + // directory predicted by the default rule, not named by the driver. const breach = refusalBreach(cli.ending, { cause: expected.refused.cause, outKnown: true, + defaultOut: plan.outMode === `default`, + logNote: expected.refused.arguments ? undefined : logNoteOf(cli), }) if (breach) return violation(`cli`, breach, `report-shaped ending`) - return incrementalCheck(observations) ?? daemonCheck(observations) ?? pass + // 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, expected, plan) ?? + daemonCheck(observations) ?? + pass + ) } if (cli.exit !== 0 || !cli.reported) return violation( @@ -3361,8 +4241,32 @@ 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). + // 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( @@ -3415,7 +4319,11 @@ function check(plan, observations, expected) { { actual: after, expected: before }, ) } - return incrementalCheck(observations) ?? daemonCheck(observations) ?? pass + return ( + incrementalCheck(observations, expected, plan) ?? + daemonCheck(observations) ?? + pass + ) } /** @@ -3431,10 +4339,15 @@ 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) - const ends = endsBreach(run) + const ends = endsBreach(run, { checked: owesNote(expected) }) if (ends) return breach(ends.difference, ends.extra) if (run.stream.mutantBeforeVerdict) return breach( @@ -3473,6 +4386,25 @@ function streamBreach(checkpoint, run, expected, plan) { return undefined } +/** + * 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. + */ +// 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 = ( + 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` +} + /** * Law 15's gap lines on stdout, judged against the run's own results.json: * each gap it reports has exactly one gap line, which names its id, and @@ -3596,7 +4528,8 @@ const lineSpelling = (path) => * 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). And law 12's one diagnostic per + * 3 error, and a signal's code stopped). With `checked`, the run started a + * check, so its first line names its stream log. And law 12's one diagnostic per * failure (v21.2 P10 and R10; the register's C entry "The internal-error * line", 2026-11-16): an internal error that ends through its own ending, * whose done line names its log (`done error, log `), wrote exactly one @@ -3605,11 +4538,33 @@ const lineSpelling = (path) => * supervisor's own exit 3 included (`done error, the run's process exited * …`), wrote none. 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. 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 (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`, + } + // 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 ${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) return { @@ -4265,6 +5220,33 @@ 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`, + 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`, + 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`, law: `greppable stream`, @@ -4424,6 +5406,28 @@ 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`] +// 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`, @@ -4431,6 +5435,23 @@ const required = [ `a probe branch's work under a generated test's bound judged nothing`, // Reached only by the constructed history of a replaced warm daemon (see there). `a warm daemon was replaced before the pause`, + `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`, + ...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`, + `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`, + `a start refuses a dangling claim`, + `an unsupervised run stopped after its note`, + ...posixStarts, + ...posixPs, `killed by a second owner`, `killed`, `random-only kill`, @@ -4600,7 +5621,30 @@ 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 = [ + `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`, + ...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`, + `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`, + `a start refuses a dangling claim`, + `an unsupervised run stopped after its note`, + ...posixStarts, + ...posixPs, +] 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`, @@ -4760,6 +5804,14 @@ 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, + claimScenario: false, + psMissing: false, declaration: index % 2 === 0 ? `wrapper` : `oracleProperty`, ownerless: false, owners: [`a`, ...generated.owners.slice(1)], @@ -4771,7 +5823,7 @@ oracleProperty({ law: { statement: `The gap report enumerates the promised operator mutants, leaves out exactly the probe-only code, discovers every oracle that owns a function's call tree and refuses broken ownership, judges each mutant only by its owners' tests on their registered routes and counts only law verdicts on reproducible routes as kills, which outrank a run that never ends, anchors each mutant by its function and normalized statement, lists every gap and unowned mutant once with consistent counts, keeps keys stable under unrelated edits, reports through one daemon per package what a cold run reports at every state of a sequence of edits, and bounds the runs that confirm a mutant's cut-off copies by one budget per mutant and names each busy mutant in a heartbeat while it runs, leaves nothing in the package and writes nothing where Vitest's include could find it while it runs, leaves no process running once it is stopped, runs the package as Vitest does from any install path and any --source spelling: one instance of each workspace dependency, no refusal over an unbuildable devDependency, child processes for a native addon anywhere in the tree, a capture that a test's builtin spies cannot see, and a refusal of test.projects; leads its report with every test file's baseline, blocks only the mutants a failing oracle file owns and judges the rest, prints every line of its stream with the prefix oracle-gaps: and its kind, one decisive baseline line before any mutant, and a done line last, and every run that does not complete ends, cold or through the daemon, with a refusal that exits 2, prints a refused: block and one fix: directive with no stack trace, and writes the refusal to the run's output directory.`, authority: `The maintainer's decisions in design runs v11, v14, and v19 (2026-11-04 and 2026-11-05), not in this package's records, including that a kill by reach agreement alone is a gap and that an incremental run through the daemon equals a cold one (v19.3); the project's oracle guide on quiet exclusions; the oracle rubric's outcome kinds (ORC-006); the CLI's documented operator list in schemata.mjs; the maintainer's dispositions G1, G2, G4, G5, G6, and G13 of the framework papercut ledger (2026-11-11) and the v20 freeze's namespacing, one-loop, and provisional-report decisions (2026-11-10); the maintainer's request for a greppable stream (2026-11-12, relayed by the coordinator with its decisions of that day: the same prefixes on stdout and stderr, a done line for a stopped run, and no --max-gaps).`, - limits: `Law 12 judges refusals. The one internal error a history reaches is the constructed rejected-batch history (rejectBatch, a test-only fault that rejects a batch's run after its copies are in Vitest's and Vite's state). Its run is judged in this order: the output namespace, process warnings, and config lines, as for any run; then bounded retention, which owes the rejected batch's own line with its state after retirement; then the stream law (law 15) on both streams, as for any run, so its error line and its done line carry the prefix, and no other line does not, which the state \`a run ended in an internal error\` declares; then exit 3 with an internal error's done line last on both streams, no stack frame on stderr, and an error.log in its output directory. What the error.log's stack says is not judged. An internal error that no fault constructs is a completion failure, reported before the stream law; an internal error through the daemon is reached by no history, and its ending is the same function's (endRun), by inspection. The internal error's lines follow the register's C entry "The internal-error line" (2026-11-16): the general law (endsBreach) owes every run that ends through endRun one error line on stderr naming the done line's log, the output directory's error.log, and none on stdout, and owes the supervisor's own exit 3 none. The message's escape is witnessed by the fault's message, which holds a line break and a forged done line after it; the log path's escape only on POSIX, where the rejected batch's output directory holds a line break (a name on win32 cannot). Paths in a completed run's lines (the results note, the done line's report, the test-output note) are escaped the same way, by inspection: no completed history names such a directory. P10's exempt lines (v21.2 P10 and I3) are read by their own shapes (exemptBlocks), never by indentation alone: a baseline failure's indented details, a refusal's block, Node's warning with its \`--trace-warnings\` frames and its hint, V8's fatal block, esbuild's message block, and Vite's own \`[vite]\` line. The V8, traced-warning, and esbuild blocks are calibrated beside our own line with no prefix (the stream calibrations put them before the rejected-batch run's done line, and the law must name our line alone); no generated history prints any of them or a Vite line, and a shape of those tools that exemptBlocks does not name is read as a stray. The stdout summary's exemption is unused and not exercised: the CLI prefixes every summary line (its summary, legend, and function kinds). \`--help\` prints its usage text with no prefix and no done line, exempt by the register's M entry "\`--help\` is exempt" (2026-11-16), and the static oracle's Help law owes exactly that text; \`--stop-daemon\` prints nothing and exits 0, read the same way as a command outside the run protocol (C, pending ratification), and this oracle runs it without observing its streams. A syntax error in a module that the config imports lets the esbuild that Vite bundles configs with print its block before the refusal (trace, Vite 7.3.7, esbuild 0.28.2: \`✘ [ERROR] Unexpected end of file\`, an empty line, \` helper.ts:2:0:\`, the code frame, then the refused block): its lines are exempt by the register's M entry "Other tools' output is exempt" (2026-11-16), the refusal and the done line around them keep the prefix, and no history generates it. Bounded retention reads the hook's lines (retention-hook.mjs). Its count of one line per batch (runner law L2) rests on the index the hook takes when a batch starts, so a CLI that skipped a batch's index and its line together, or that omitted only the line of a check's last batch, keeps the indices 0..n-1 and is not seen; a check that ended before its report (the rejected batch, a stopped run) and a daemon the driver killed are judged for at most one line per index, since the batches they were running at their end owe none. A line's process is told by check.pid, which the check writes, and the driver itself knows only the daemon it killed. The cold store's law (held) counts the entries given to the store's put that a full collection leaves reachable, so a store that kept only a part of an entry (its unit without the entry) is not seen; staleOpen reads Vitest's own close state (closingPromise, set when close starts), so a close that starts and never resolves is the runner oracle's (L8); and a context replaced after a check's last batch is observed only by a later check's first batch through the daemon. The run whose process aborts is declared on every platform. Its win32 witness (process.abort through ORACLE_GAPS_TEST_ABORT_AT, under the win32 supervisor) lands in #79; until then the Windows end-to-end job is non-blocking (C entry (c)). On win32 Node cannot deliver SIGTERM (its kill is TerminateProcess, which ends the process with no stopped line), so the stop states that name SIGTERM are required on POSIX only, and a stop there goes through the CLI's test stop hook and is observed as SIGINT; every SIGINT state stays required on win32. Argument refusals are the static oracle's; the check's rejection of a stack trace, a missing fix, and a wrong exit code is calibrated in the static oracle, through the same refusalBreach, and here only a refused run reported as complete is calibrated, because each calibration here runs real CLI histories. Law 15's stdout gap lines are judged against each completed run's own results.json, by id: the cold run, and each check through the daemon (every step's check and the check that a mid-run edit overlaps); a stopped run and a refusal list no gaps and are not judged so. A line's change is read loosely: its code on one line, whole or cut after a kept part and ended with \`...\`; where the printer cuts (60 code points, kept 57) is the classify oracle's law 8 (\`shortened\`), in-process. A line with any text after its change does not read and fails loudly: the \` (cause: )\` suffix that #99 adds to timeout lines is not read yet, so whichever of #99 and #115 lands second extends readGapLine. Hangs only as an owner test that awaits a promise that never settles, under a 1 s first budget and a 20 s full limit, and a slow run only as two witnesses whose tests wait where the output changed, 3 s in one that then judges and 10 s in two one-test owners of one that does not; busy loops only on instrumented code (cut by the call budget), no slow runs past the full limit that would end, hangs in ordinary or nondeterministic tests, setup errors other than a throw at module load, loops, multi-line conditions, two functions on one line, or await, new, and void statements; nested functions, object-literal methods, accessors, and class-field arrows only where no test calls them (their ownership is the static oracle's); two source files of one package, with no re-exports, namespace imports, or calls into another package; --only only in a stopped run and a partial run of one function's mutants, and no --sample or --diff-base; the baseline's failures only as one failing owner test that throws an error and a setup file that throws, so a baseline law violation's law and counterexample lines are the classify oracle's; a derived class's file is instrumented and its sites are judged as unowned, but no test imports or constructs the class, so its no-mutant and super-region behavior is the static oracle's (in-process), not this oracle's; package configs only as vite.config or vitest.config with one of the extensions .ts, .mts, .cts, .js, .mjs, and .cjs (not every pair), as config/gap-vitest with the same extension through --config, or none, as an object or a sync or async function, with no plugins of their own except one enforce: 'pre' transform that appends a comment to each module of the package (prePlugin) and, in one constructed history, a plugin whose load reads each test file with a sync read (loadPlugin); a plugin whose output depends on anything but the module's text (a sidecar file it reads) and an environment variable that changes between checks are not generated, since the runner tracks neither yet and the daemon's environment is fixed when it starts (F-A1: the maintainer decided on 2026-11-13 that the daemon tracks both and restarts when they change, in the next pull request); and test.projects only as a refusal, and only under the package's own package.json; a config's test.root only in four shapes, each in one constructed history of an ES module config that Vitest discovers, with one owner and one context, where the test files' globs and the setup file are relative to the root (issue #101): the directory that holds the tests, the directory above the package, a directory of the package that holds no test file, and the package's tests as a symbolic link to the directory that holds them (required on every platform, since Windows creates the link as the driver's other links); not under --config, a CommonJS config, test.projects, several contexts with different roots, or a root that is the filesystem's root; the runner serves each copy of a test file by its absolute path, through its pre plugin's load (which answers before the config's own plugins) and through its read of the copy's path for Vitest's pragma read (serveCopies), and histories run copies only in Vite's server environments (node and the pragma's ssr environment): jsdom and happy-dom, Vite's client environment, are not generated (the #103 merge-gate review ran jsdom by hand under all five root shapes, and the copies loaded in each); a top-level await only in an ES module config and require only in a CommonJS one, as Vitest itself loads no other; a --config outside the package is refused by design, through the rule for paths outside the package (args.mjs), and no history generates one; contexts only one, four, or eleven, and process warnings judged only as MaxListenersExceededWarning on the CLI's own stderr (a daemon's process warnings go to its log); a context that fails to open gives back its listener allowance, which no observation shows (a kept allowance only raises the limit, so no warning follows), so that accounting is fixed by inspection; no probe-bound states, so reach agreement's killing of probe mutants is not checked; no gap answers or gate; law 9 judges the witness module's outcome classes along one constructed edit sequence only (a test edit, a helper edit, and a revert), and the budget witness's along one constructed second check with nothing changed, because a generated history with the witness module or the budget witness takes no steps (maintainer decision, 2026-11-11, and the runtime review's P1-a, 2026-11-12; this oracle owns the gap); law 9's edits come between checks, except one, midrun, which lands during a check through the daemon: a test of file a, whose context has loaded file b's helper, rewrites the helper in the baseline's first run of file a, before file b's runs read it, in one context or several; or a test of file b rewrites its own helper, or the data file that its verdict read through a sync fs read, after file b's judged tests read them, in the run that judges with the old text (review of #55, F1); that check must report, for each mutant, what a cold run of the state before the edit or of the state after it reports, and exit as one of them does (third review of #55, F-C), compared per mutant result rather than per file; when file b's own test lands the edit, b's baseline reads the old text and b's mutant runs read the new one, so b's own mutants in that check are not judged, since their results legitimately mix the two texts (maintainer decision, 2026-11-13), while every other mutant there is judged against both cold runs, with the check's exit code, its mutants' keys, and its stream; the stronger follow-up compares each run's raw outcome with the cold outcome of the state that run read; and the next check, with nothing changed, must equal a cold run of the state after the edit, compared for equality of results only, not for what the daemon reused or computed (the runner's rule: a run whose input changed after the run read it is invalidated and not stored, settleIn); a check through the daemon of a state that nothing changed must compute no run that was not cut off, judged where no test reads the clock (F-A, F-A2), and a test's fs read of a file and the module that the context serves from it are two inputs, each under its own hash (F-A2); an edit during a mutant run is not generated, and a file is edited mid-run only by the run's own tests, not by another process at an arbitrary time; a file that a test reads through fs is edited only as one JSON file that file b's verdict reads by a sync, a promise, or a callback read, or by a sync read after it stats its own directory and tests that it exists (statDir: the directory is an input as a directory, not by its content, and is not itself edited), each read first checking that its fs function keeps its own name and length (the runner stores a run under the files in the package that its copy reads with readFileSync, readFile, existsSync, or statSync, or the fs/promises readFile or stat, each with its hash at the copy's first read; a read outside the package or under node_modules, from a worker thread or a child process that a test starts, or through any other fs API, which includes readdir, opendir, glob, globSync, createReadStream, realpath, lstat, access, open, a read through a file descriptor (read, readSync, readv, fstat, fstatSync, and readFileSync or readFile given a file descriptor), copyFile and copyFileSync, cp and cpSync, openAsBlob, statfs, readlink, the callback stat, exists, watch, watchFile, and the fs/promises access, open, and glob, is no input, and none is generated: the maintainer decided on 2026-11-13 that every fs read except watch and watchFile is an input, which a follow-up of #55 implements, and until then this oracle owns the gap); a run cut off by its clock writes no closing row, so it is stored under its file's known inputs only, while a run that spun ends and keeps the inputs it named (F-D); no history makes a cut run read a file that its file's unmutated run does not read, so this is fixed by inspection; a test that rewrites a file it read with the same text makes the next check compute that run again (1 run in the self-edit histories), since the edit changes the file's modification time: the daemon is conservative there, nothing goes stale, and content keys (D10) remove it, with a selfWrite dimension in that pull request; the mid-run marker sits in the daemon's session directory, .oracle-gaps-, whose location predates #55; the runner's hash memo knows a file by its size and modification time, so an edit that keeps both is not seen, and no history makes one (D10, planned in phase 2, A5); law 9's edits leave out other environment variables, new files that change how an unchanged import resolves, Vite config and installed-package changes, and concurrent checks other than two that start the daemon; cut-off charging judged only under one budget; native addons only as a binding.gyp or a prebuilt .node file, not as optional platform packages; daemon races (two CLIs reading one error file, a CLI hearing closing from the failing daemon it started, a reset connection on macOS) fixed by inspection; the runner's copies of the test files exist only in memory, and its harness and Vitest configs sit in the package's .oracle-gaps-, which the next run removes once a killed run has left it (judged after two stopped runs, not after a SIGKILL); a default --out is judged by the static oracle, and these runs name --out in the package; the namespace is checked after each run and, in a stopped run, while the run runs; a slow kill in a later owner, after earlier owners' confirmations spent the budget, becomes a timeout (owner order; not generated); the Vitest 5 path of the copies' pragma read and of the runner is verified from Vitest 5's source only, since the Vitest 5 CI job runs no gap oracle; a batch whose run reports an error outside any test reruns each copy alone (unitsBatch, runAlone) with its first budget, and a copy cut there is kept as a timeout with no confirmation, a defect older than this oracle's budget work that no history reaches (no history has an error outside any test beside a slow copy), recorded here with that trace for the maintainer; stale-session removal is scoped to this host's session directories (a host file), and is not judged across pid namespaces; the stop law covers SIGTERM and SIGINT sent to the CLI, not a SIGKILL of the CLI (its group then ends at the next check of its parent, by inspection) or a signal sent to the daemon, and its witness is one test that spins synchronously and starts one child process; the mutant budget is witnessed as two slow owners whose confirmations pass the --mutant-limit floor, not through its multiple of the owners' unmutated time, and authored mutants have no confirmations to budget; the witness w_slowpair is a wall-clock window, since the CLI's budget has no controlled clock and a fixture cannot see the time the CLI measures for its file: with one-test owner files p and q of measured unmutated time t each (a file first in its context pays the instrumented transform too), a wait W of 10 s, a 20 s --hang-limit and a 15 s --mutant-limit, it tells a budget from none only while (a) its first attempt is cut, W > 1 s + 3t, (b) its two confirmations do not fit the budget, 2W > max(15 s, 10 x 2t), and (c) each would fit its own full limit, W < 20 s + 3t; (b) is the binding one, so it holds while the two files' time stays under about 2 s together (about 1 s each, some 20 times the authoring machine's idle and 5 to 10 times its loaded measurements), and under one budget a run's overhead must stay under 10 s + 3t; CI runners measure 1.5 to 2.3 times the idle machine; beyond that w_slowpair would read not-judged; a heartbeat is owed only where a slow test waits 3 s against a 2 s interval, twice the first budget, so that no copy cut at its first budget beats, and each beat is observed as its mutant and file, not how long or how often it beat; a config only in the package's parent directory is generated one level up, in a temporary directory with no package.json (so its .js or .ts name is CommonJS), as a plain config, one that throws, one with no default export, or one that defines test.projects; a config two or more levels up, or a parent config beside a package config, is not generated, and the order in one directory follows Vitest's configFiles list by inspection; a package with no config lives in a temporary directory, where no parent has a config; a counterexample shrinks through at most six histories, so it can be larger than the smallest that fails; module-level data only as four \`const\` declarations of the main source (an object literal, an array that holds a function, a boolean, and an object of two methods), read in place, with no data imported from another file, destructured, reassigned, or declared as an enum or a default export; the work law only through shortcut witnesses (an early return before a counting loop with a bound twin of ratio 2, and a push beside one that calls String with a bound twin of ratio 1), the early return in tests that reach the clock by each watched path and in tests that wait a turn, a generated test's bound of 1 derived from its plan; probe code is never work (maintainer decision, 2026-11-16), so the model and the capture count no probe-only site, and only a constructed history (a probe branch under a generated test's work bound) reaches a probe branch beside a bound: the fixed seeds' generated histories reach neither that state nor \`killed by a work bound in a generated function\`, which stays measured; work counts are observed only through a bound's ratio and a rise, never as numbers (v21.2 O1), so a counter that skips every site on a probe's line, which drops only the condition sites of an elseIf that run once on both sides, survives (mutant M6, equivalent under these observations), while one that skips every site of a function that holds probe code is killed (M7), and one warm-cache witness whose selection reproduces observations but not work; work is the capture's count of site evaluations per test, so code with no site (a plain assignment, a for...of pass, a builtin's own work) counts nothing and a test's histories are summed, and a test whose work varies between the unmutated runs while its observations agree is not generated. Open Limits, owned by the in-process runner oracle (L1, state \"torn tail at a cut-off read\"; RED: captureLines without the guard): (a) the batch's cut-off read (runBatch's rowsOf after the cut-off) drops a partial last row, and no witness reaches that drop yet, because a copy held half written across the cut-off did not observe its release in the harness; (b) a short fragment on the strict path, which the no-newline mutant does not reach. The strict read after a finished run (a fragment is an internal error) is witnessed by the no-newline mutant. Windows idle gap (recorded, not witnessed): the state \`a hang cut off for idleness\` is required on every platform, and win32 reaches it (run 43683794816, job 132719872988), so it is not platform-scoped. The sampler (capture-setup.mjs) counts a copy idle only after 500 ms with no late tick, no non-quiet handle, utilization at most 5%, and no timer due, so \`every outcome class\` reaches the state only when the sampler sees that window. On win32 the check missed it once (run 43683794816, job 132719872940); the cause is not confirmed (a late tick on a shared runner, or a stdio handle outside \`quiet\` for this file's console output, are the candidates). Its witness, a test-only hold at the hang until the window is seen, is owed, and that is a timing dependency the determinism-under-load rule forbids; the maintainer decides whether it lands before the Windows job becomes blocking.`, + limits: `Law 12 judges refusals. The one internal error a history reaches is the constructed rejected-batch history (rejectBatch, a test-only fault that rejects a batch's run after its copies are in Vitest's and Vite's state). Its run is judged in this order: the output namespace, process warnings, and config lines, as for any run; then bounded retention, which owes the rejected batch's own line with its state after retirement; then the stream law (law 15) on both streams, as for any run, so its error line and its done line carry the prefix, and no other line does not, which the state \`a run ended in an internal error\` declares; then exit 3 with an internal error's done line last on both streams, no stack frame on stderr, and an error.log in its output directory. What the error.log's stack says is not judged. An internal error that no fault constructs is a completion failure, reported before the stream law; an internal error through the daemon is reached by no history, and its ending is the same function's (endRun), by inspection. The internal error's lines follow the register's C entry "The internal-error line" (2026-11-16): the general law (endsBreach) owes every run that ends through endRun one error line on stderr naming the done line's log, the output directory's error.log, and none on stdout, and owes the supervisor's own exit 3 none. The message's escape is witnessed by the fault's message, which holds a line break and a forged done line after it; the log path's escape only on POSIX, where the rejected batch's output directory holds a line break (a name on win32 cannot). Paths in a completed run's lines (the results note, the done line's report, the test-output note) are escaped the same way, by inspection: no completed history names such a directory. P10's exempt lines (v21.2 P10 and I3) are read by their own shapes (exemptBlocks), never by indentation alone: a baseline failure's indented details, a refusal's block, Node's warning with its \`--trace-warnings\` frames and its hint, V8's fatal block, esbuild's message block, and Vite's own \`[vite]\` line. The V8, traced-warning, and esbuild blocks are calibrated beside our own line with no prefix (the stream calibrations put them before the rejected-batch run's done line, and the law must name our line alone); no generated history prints any of them or a Vite line, and a shape of those tools that exemptBlocks does not name is read as a stray. The stdout summary's exemption is unused and not exercised: the CLI prefixes every summary line (its summary, legend, and function kinds). \`--help\` prints its usage text with no prefix and no done line, exempt by the register's M entry "\`--help\` is exempt" (2026-11-16), and the static oracle's Help law owes exactly that text; \`--stop-daemon\` prints nothing and exits 0, read the same way as a command outside the run protocol (C, pending ratification), and this oracle runs it without observing its streams. A syntax error in a module that the config imports lets the esbuild that Vite bundles configs with print its block before the refusal (trace, Vite 7.3.7, esbuild 0.28.2: \`✘ [ERROR] Unexpected end of file\`, an empty line, \` helper.ts:2:0:\`, the code frame, then the refused block): its lines are exempt by the register's M entry "Other tools' output is exempt" (2026-11-16), the refusal and the done line around them keep the prefix, and no history generates it. Bounded retention reads the hook's lines (retention-hook.mjs). Its count of one line per batch (runner law L2) rests on the index the hook takes when a batch starts, so a CLI that skipped a batch's index and its line together, or that omitted only the line of a check's last batch, keeps the indices 0..n-1 and is not seen; a check that ended before its report (the rejected batch, a stopped run) and a daemon the driver killed are judged for at most one line per index, since the batches they were running at their end owe none. A line's process is told by check.pid, which the check writes, and the driver itself knows only the daemon it killed. The cold store's law (held) counts the entries given to the store's put that a full collection leaves reachable, so a store that kept only a part of an entry (its unit without the entry) is not seen; staleOpen reads Vitest's own close state (closingPromise, set when close starts), so a close that starts and never resolves is the runner oracle's (L8); and a context replaced after a check's last batch is observed only by a later check's first batch through the daemon. The run whose process aborts is declared on every platform. Its win32 witness (process.abort through ORACLE_GAPS_TEST_ABORT_AT, under the win32 supervisor) lands in #79; until then the Windows end-to-end job is non-blocking (C entry (c)). On win32 Node cannot deliver SIGTERM (its kill is TerminateProcess, which ends the process with no stopped line), so the stop states that name SIGTERM are required on POSIX only, and a stop there goes through the CLI's test stop hook and is observed as SIGINT, which owes its done line as any stop does (no history sends a win32 child.kill, the SIGKILL-equivalent that owes none); every SIGINT state stays required on win32. A stop as the CLI starts lands only in one of two holds: the driver's own preload before the CLI's first statement (outcome a, nothing written; POSIX only, since its witness is a signal's default action), or the CLI's hold after its started marker, which the stop the CLI keeps releases (outcome b, judged only when the supervisor started no child); a stop during Node's own start between the two is not generated, since its outcome follows timing. The drawn spawn delay is a wait inside a hold, so it cannot move a stop out of it. Stop runs that land while the config warms (ORACLE_GAPS_TEST_WARM_PROBE) are still drawn, and on win32 every drawn stop goes through ORACLE_GAPS_TEST_STOP: each is a test-only hook that a drawn field switches, main's pattern, which the review of #57 (A3) brought to the maintainer; only the stop after the completed line (ORACLE_GAPS_TEST_HOLD_UNTIL) was made constructed-only. A missing \`ps\` is generated only as a PATH that names no command, on POSIX, where the run is supervised. The unsupervised path (stopNow, every win32 stop) is reached on POSIX by one constructed history whose stop is held at the run's note, before the check starts a process: an unsupervised POSIX run has no group to end, so a stop while the witness's test spins leaves that test's own child (measured; C 2026-11-13, Windows (e)), which win32 ends with the job object libuv puts its children in. Argument refusals are the static oracle's; the check's rejection of a stack trace, a missing fix, and a wrong exit code is calibrated in the static oracle, through the same refusalBreach, and here only a refused run reported as complete is calibrated, because each calibration here runs real CLI histories. Law 15's stdout gap lines are judged against each completed run's own results.json, by id: the cold run, and each check through the daemon (every step's check and the check that a mid-run edit overlaps); a stopped run and a refusal list no gaps and are not judged so. A line's change is read loosely: its code on one line, whole or cut after a kept part and ended with \`...\`; where the printer cuts (60 code points, kept 57) is the classify oracle's law 8 (\`shortened\`), in-process. A line with any text after its change does not read and fails loudly: the \` (cause: )\` suffix that #99 adds to timeout lines is not read yet, so whichever of #99 and #115 lands second extends readGapLine. Hangs only as an owner test that awaits a promise that never settles, under a 1 s first budget and a 20 s full limit, and a slow run only as two witnesses whose tests wait where the output changed, 3 s in one that then judges and 10 s in two one-test owners of one that does not; busy loops only on instrumented code (cut by the call budget), no slow runs past the full limit that would end, hangs in ordinary or nondeterministic tests, setup errors other than a throw at module load, loops, multi-line conditions, two functions on one line, or await, new, and void statements; nested functions, object-literal methods, accessors, and class-field arrows only where no test calls them (their ownership is the static oracle's); two source files of one package, with no re-exports, namespace imports, or calls into another package; --only only in a stopped run and a partial run of one function's mutants, and no --sample or --diff-base; the baseline's failures only as one failing owner test that throws an error and a setup file that throws, so a baseline law violation's law and counterexample lines are the classify oracle's; a derived class's file is instrumented and its sites are judged as unowned, but no test imports or constructs the class, so its no-mutant and super-region behavior is the static oracle's (in-process), not this oracle's; package configs only as vite.config or vitest.config with one of the extensions .ts, .mts, .cts, .js, .mjs, and .cjs (not every pair), as config/gap-vitest with the same extension through --config, or none, as an object or a sync or async function, with no plugins of their own except one enforce: 'pre' transform that appends a comment to each module of the package (prePlugin) and, in one constructed history, a plugin whose load reads each test file with a sync read (loadPlugin); 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; probe code is never work (maintainer decision, 2026-11-16), so the model and the capture count no probe-only site, and only a constructed history (a probe branch under a generated test's work bound) reaches a probe branch beside a bound: the fixed seeds' generated histories reach neither that state nor \`killed by a work bound in a generated function\`, which stays measured; work counts are observed only through a bound's ratio and a rise, never as numbers (v21.2 O1), so a counter that skips every site on a probe's line, which drops only the condition sites of an elseIf that run once on both sides, survives (mutant M6, equivalent under these observations), while one that skips every site of a function that holds probe code is killed (M7), and one warm-cache witness whose selection reproduces observations but not work; work is the capture's count of site evaluations per test, so code with no site (a plain assignment, a for...of pass, a builtin's own work) counts nothing and a test's histories are summed, and a test whose work varies between the unmutated runs while its observations agree is not generated. Open Limits, owned by the in-process runner oracle (L1, state \"torn tail at a cut-off read\"; RED: captureLines without the guard): (a) the batch's cut-off read (runBatch's rowsOf after the cut-off) drops a partial last row, and no witness reaches that drop yet, because a copy held half written across the cut-off did not observe its release in the harness; (b) a short fragment on the strict path, which the no-newline mutant does not reach. The strict read after a finished run (a fragment is an internal error) is witnessed by the no-newline mutant. Windows idle gap (recorded, not witnessed): the state \`a hang cut off for idleness\` is required on every platform, and win32 reaches it (run 43683794816, job 132719872988), so it is not platform-scoped. The sampler (capture-setup.mjs) counts a copy idle only after 500 ms with no late tick, no non-quiet handle, utilization at most 5%, and no timer due, so \`every outcome class\` reaches the state only when the sampler sees that window. On win32 the check missed it once (run 43683794816, job 132719872940); the cause is not confirmed (a late tick on a shared runner, or a stdio handle outside \`quiet\` for this file's console output, are the candidates). Its witness, a test-only hold at the hang until the window is seen, is owed, and that is a timing dependency the determinism-under-load rule forbids; the maintainer decides whether it lands before the Windows job becomes blocking.`, }, histories: { // A failing history shrinks through at most six smaller ones. Each runs @@ -6062,39 +7114,6 @@ oracleProperty({ // (v21.2 R53, M-23), so the bound sees only production sites. }), }, - { - // 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 @@ -6235,6 +7254,618 @@ oracleProperty({ ], }), }, + { + // 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`, + concurrentStart: false, + 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 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`, + }), + }, + { + // 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, + }), + }, + { + // 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: `'` }]], + 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`, + }), + }, + { + // 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: `'` }]], + 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: `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`, + }), + }, + { + // 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`, + }), + }, + { + // 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: posixSupervision, + 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, + }), + }, + { + // 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`, + }), + }, + { + // 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 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). 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, + 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`, + stopWitness: true, + unsupervised: true, + stopRuns: [{ signal: `SIGINT`, pool: `threads`, when: `note` }], + }), + }, + { + // 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, + }), + }, + { + // The second half of `every outcome class` (review of #73, P12) is split + // 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, + 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`, + stopRuns: [{ signal: `SIGINT`, pool: `threads`, when: `warm` }], + }), + }, + { + // 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, + 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`, + stopRuns: [{ signal: `SIGINT`, pool: `threads`, when: `abort` }], + }), + }, ]), }, resolve: resolveHistory, diff --git a/packages/oracles/oracle-gaps/gap-report-static-oracle.property.test.mjs b/packages/oracles/oracle-gaps/gap-report-static-oracle.property.test.mjs index e8d30d9f..9ab93db6 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 @@ -92,6 +92,7 @@ * target. An authored mutant's `source` field is used as written. */ import { + existsSync, mkdirSync, mkdtempSync, readFileSync, @@ -380,6 +381,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, @@ -505,16 +514,30 @@ function argumentsRunOf(dir, plan) { encoding: `utf8`, timeout: 120_000, }) - return endingOf( - run.status, - run.stderr, - out, - // The CLI names its paths in forward slashes (the Windows paths rule), so - // the package is named in both spellings. - (text) => - text.replaceAll(posix(dir), ``).replaceAll(dir, ``), - run.stdout, - ) + return { + ...endingOf( + run.status, + run.stderr, + out, + // The CLI names its paths in forward slashes (the Windows paths rule), so + // the package is named in both spellings. A default output directory's + // name is random (a run name), so it is normalized as the package's + // directory is. + (text) => + text + .replaceAll(posix(dir), ``) + .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 + // 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 @@ -1107,6 +1130,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. @@ -1810,7 +1839,7 @@ oracleProperty({ }, ]), }, - resolve: resolveHistory, + resolve: staticResolve, model, driver, check, diff --git a/packages/oracles/oracle-gaps/history-fingerprint.json b/packages/oracles/oracle-gaps/history-fingerprint.json index 20fef659..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"], @@ -57,7 +57,20 @@ ["warmReplaced", "ed6866229ecc4969"], ["testRoot", "e18db063421a75f1"], ["loadPlugin", "ed6866229ecc4969"], - ["rejectBatch", "e5386ea9402dd268"] + ["rejectBatch", "e5386ea9402dd268"], + ["outMode", "41cdfe2f2bf3d461"], + ["logBlocked", "7e3d565dd085831c"], + ["overlap", "ed6866229ecc4969"], + ["stopWitness", "36747a303377a389"], + ["spawnStop", "ed6866229ecc4969"], + ["spawnSignal", "fb32b212e5d379b9"], + ["spawnDelay", "51eee7869e2a0f71"], + ["spawnOnStart", "ed6866229ecc4969"], + ["claimScenario", "9721481ccee3e101"], + ["logLost", "ed6866229ecc4969"], + ["supervisorDeath", "ed6866229ecc4969"], + ["unsupervised", "ed6866229ecc4969"], + ["psMissing", "e6ef4bc292a3990d"] ], "histories": [ ["functions", "66c0e9c56951c377"], @@ -92,7 +105,7 @@ ["unbuiltDep", "ece5968476f7042d"], ["boot", "6fc1fdf2bd90d59e"], ["budget", "d8481d5ff2e964b9"], - ["stopRuns", "826d81299eda30ed"], + ["stopRuns", "e7a9ea343f07a902"], ["onlyRun", "439d74b1930e4623"], ["pragma", "731664592bd605c0"], ["cliPath", "cba4d240a707ec0b"], @@ -117,6 +130,19 @@ ["warmReplaced", "ed6866229ecc4969"], ["testRoot", "e18db063421a75f1"], ["loadPlugin", "ed6866229ecc4969"], - ["rejectBatch", "e5386ea9402dd268"] + ["rejectBatch", "e5386ea9402dd268"], + ["outMode", "41cdfe2f2bf3d461"], + ["logBlocked", "7e3d565dd085831c"], + ["overlap", "ed6866229ecc4969"], + ["stopWitness", "36747a303377a389"], + ["spawnStop", "ed6866229ecc4969"], + ["spawnSignal", "fb32b212e5d379b9"], + ["spawnDelay", "51eee7869e2a0f71"], + ["spawnOnStart", "ed6866229ecc4969"], + ["claimScenario", "9721481ccee3e101"], + ["logLost", "ed6866229ecc4969"], + ["supervisorDeath", "ed6866229ecc4969"], + ["unsupervised", "ed6866229ecc4969"], + ["psMissing", "e6ef4bc292a3990d"] ] } diff --git a/packages/oracles/oracle-gaps/index.mjs b/packages/oracles/oracle-gaps/index.mjs index 4321082e..2fe50edc 100755 --- a/packages/oracles/oracle-gaps/index.mjs +++ b/packages/oracles/oracle-gaps/index.mjs @@ -121,60 +121,323 @@ // 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 { existsSync, realpathSync } from 'node:fs' +import { + appendFileSync, + existsSync, + linkSync, + 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 { memoryStore } from './evidence.mjs' +import { posix } from './paths.mjs' + +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 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`) +// 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 -/** Signals every process of group `group`; false when none is left. */ -function signalGroup(group, signal) { +// 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. 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`) +/** Appends `text` to the stream log at `path`; a failure is the refusal that ends the run. */ +const appendLog = (path, text) => { try { - process.kill(-group, signal) + appendFileSync(path, text) + } catch (error) { + 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) +} +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` + } +} +// The output directory this process claimed (its run.pid), released when the +// process exits, on every exit but SIGKILL. +let claimed +process.on(`exit`, () => { + if (claimed === undefined) return + try { + if (Number(readFileSync(claimed, `utf8`)) === process.pid) + rmSync(claimed, { force: true }) } catch { - return false + // Already gone. + } +}) +/** + * 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 temp = `${claim}.${process.pid}.tmp` + try { + mkdirSync(out, { recursive: true }) + writeFileSync(temp, `${process.pid}\n`) + } catch (error) { + throw claimCannotWrite(out, claim, error) + } + try { + // 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 claimCannotWrite(out, claim, error) + const holder = readHolder(claim) + if (holder === undefined && attempt < 3) continue + // 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 { + 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 ${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. */ +function heldRefusal(out, claim, holder) { + const refusal = + holder === UNREADABLE + ? new Refusal( + `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 ${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 ${posix(out)}, delete ${posix(claim)}`, + ) + : new Refusal( + `run.pid in ${posix(out)} does not name a pid`, + `if no run uses ${posix(out)}, delete ${posix(claim)}`, + ) + refusal.reportless = true + return refusal +} +/** 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 + return UNREADABLE + } +} +// 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, + * 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) { + 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, ``) + return process.env.ORACLE_GAPS_TEST_PAUSE_UNTIL +} +/** 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) +} +/** + * 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) + claimOut(out) + try { + writeFileSync(path, ``) + } catch (error) { + throw cannotWrite(path, error) + } + streamLog = path + // The log is named in forward slashes on win32 (the Windows paths rule); POSIX + // paths are unchanged. + // 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`) +} + +/** 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. + */ +// 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) return + try { + waitForFile(file, `the hold`) + } catch { + writeFileSync(`${file}.unreleased`, ``) } } +function exitWhenFlushed(code) { + process.stdout.write(``, () => + process.stderr.write(``, () => { + holdUntil() + process.exit(code) + }), + ) +} /** - * 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() { +function superviseRun(out) { let child let stopped // 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 @@ -192,11 +455,19 @@ 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, () => { + // 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), - ), - ) + ) + }) } if (child === undefined || closed) return decide() child.once(`close`, decide) @@ -218,39 +489,55 @@ function superviseRun() { 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) - // The test-only stop hook (ORACLE_GAPS_TEST_STOP, review F(f)): in a - // supervised run it goes through this supervisor's stop, which forwards to - // the child and writes the stopped line, as a SIGINT does. - if (process.env.ORACLE_GAPS_TEST_STOP !== undefined) { - const file = process.env.ORACLE_GAPS_TEST_STOP - setInterval(() => { - if (existsSync(file)) stop(`SIGINT`) - }, 50).unref() - } + // 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. + watchTestStop(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), + `--out`, + 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), + }, }, ) + // 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 }) - // 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) + // 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 }) @@ -263,34 +550,66 @@ function superviseRun() { }) } +/** 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) { + // 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 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() } +/** + * 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() +} /** - * 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 { const options = parseArgs(argv) - return !options.help && !options.stop + return options.help || options.stop ? undefined : options } catch { - return false + return undefined } } /** 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()) + return await session.check(options, memoryStore(), (line) => + writeStream(`${line}\n`), + ) } finally { await session.close() } @@ -298,110 +617,129 @@ 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`) + // 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 reply = await requestDaemon( options.pkg, - process.argv.slice(2), + [...process.argv.slice(2), `--out`, options.out], 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 } +// 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() + 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) +} + // 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 = 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 -if ( - main && - supervised && - supervisor === undefined && - asksForCheck(process.argv.slice(2)) -) - superviseRun() -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. +// 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). +let runStarted = false +/** Ends an unsupervised run with its stopped line on both streams (#58). */ +function stopNow(signal) { + const line = `oracle-gaps: done stopped (${signal})\n` + process.stdout.write(line) + writeStream(line) + exitWhenFlushed(128 + constants.signals[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 - 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), - ), - ) + 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) { + return endWith(error, checking.out) + } + return superviseRun(checking.out) + } + } + if (supervisor !== undefined) { + try { + watchSupervisor(Number(supervisor)) + } 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). + await testPauseOnTimers(`child`) } - // 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 run that has started owes its stop one stopped line on each stream - // (#57, all-or-nothing). A supervised run's supervisor writes it; an - // unsupervised run (win32, no process groups) writes it here. A stop before - // the run starts prints nothing, as the law allows. - let runStarted = false + // 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 + // is no refusal, and the supervisor writes the stopped line. Once the run + // writes its ending, a stop no longer cuts it off. + // The all-or-nothing stop law (#57 and #58): a stop after the note writes one + // done stopped line on each stream; a supervised child's stop is the + // supervisor's line; a stop before the note waits for it (the early stop). const onStop = (signal) => { if (writingEnding) return - const code = 128 + constants.signals[signal] - if (!runStarted || supervised) return process.exit(code) - const line = `oracle-gaps: done stopped (${signal})\n` - process.stdout.write(line, () => - process.stderr.write(line, () => process.exit(code)), - ) + if (!supervised) return runStarted && stopNow(signal) + process.exit(128 + constants.signals[signal]) } process.on(`SIGINT`, onStop) process.on(`SIGTERM`, onStop) - // A test-only hook for the CLI's own oracle, not for users (as - // ORACLE_GAPS_TEST_HOLD_EXIT_MS): when the file ORACLE_GAPS_TEST_STOP names - // appears, the CLI takes the same stop as a SIGINT. CI's Windows witness uses - // it, since a non-console parent cannot deliver Ctrl+C there. - // Unsupervised runs only (win32, no supervisor); a supervised child's stop - // is the supervisor's. - 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() - } - const holdStops = () => { - writingEnding = true - process.send?.(`ending`) - } - const fail = (error) => { - if (ended) return - const ending = endRun(error, options?.out) - holdStops() - process.stderr.write(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 test-only stop for unsupervised runs (ORACLE_GAPS_TEST_STOP, #58). + 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]) try { options = parseArgs(process.argv.slice(2)) if (options.help) console.log(usage) - else if (options.stop) await stopDaemon(options.pkg) - else { + 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) runStarted = true + if (early !== undefined) return stopNow(early) const summary = await (options.daemon ? checkThroughDaemon : checkCold)( options, ) @@ -409,10 +747,12 @@ 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) + exitWhenFlushed(0) } catch (error) { - fail(error) + endWith(error, options?.out) } } + +if (main) await run() diff --git a/packages/oracles/scripts/e2e-shards.mjs b/packages/oracles/scripts/e2e-shards.mjs index 30f2d967..e7b367e4 100644 --- a/packages/oracles/scripts/e2e-shards.mjs +++ b/packages/oracles/scripts/e2e-shards.mjs @@ -41,6 +41,16 @@ 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 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 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`, + `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`, @@ -111,6 +121,14 @@ 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 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`, `fixed seed 20261105: a declaration fault: setupThrows`, `fixed seed 20261105: a package with no config`, `fixed seed 20261105: an ambiguous authored mutant`, @@ -164,6 +182,24 @@ export const shards = { `fixed seed 20261105: a config whose plugin loads test files with a sync read`, `random seed: a config whose plugin loads test files with a sync read`, `determinism: constructed history: a config whose plugin loads test files with a sync read`, + `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 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 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`, + `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`, + `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`, `fixed seed 20261105: a declaration fault: brokenOwner`, `fixed seed 20261105: a declaration fault: configThrows`, @@ -202,6 +238,19 @@ 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 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 stop before the CLI starts`, + `random seed: a stop by SIGTERM as the CLI starts`, + `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`, + `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`, `fixed seed 20261105: a declaration fault: apiLessTypescript`, @@ -233,6 +282,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`, @@ -249,9 +301,17 @@ export const shards = { `fixed seed 20261105: a probe branch under a generated test's work bound`, `random seed: a probe branch under a generated test's work bound`, `determinism: constructed history: a probe branch under a generated test's work bound`, - `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`, + `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`, @@ -348,6 +408,8 @@ function listed() { const run = spawnSync( `pnpm`, [ + // --silent keeps pnpm's workspace banner off stdout, which is JSON. + `--silent`, `exec`, `vitest`, `list`, diff --git a/packages/oracles/scripts/pr-shards.mjs b/packages/oracles/scripts/pr-shards.mjs index a2b88dcb..ca8b9b4f 100644 --- a/packages/oracles/scripts/pr-shards.mjs +++ b/packages/oracles/scripts/pr-shards.mjs @@ -297,19 +297,27 @@ 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 after its note', + '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; 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([ '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', @@ -528,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', @@ -543,6 +554,9 @@ export const partitions = { 'a config whose test root holds no test file', 'a config whose test root is a symbolic link', 'a config whose plugin loads test files with a sync read', + 'two runs on one output directory', + 'a stream log that cannot be written', + 'a start refuses an empty claim', ]), 7: anyOf([ 'a daemon pause that cannot engage', @@ -555,6 +569,8 @@ export const partitions = { 'a package whose parent directory has its config', 'a declaration fault: configSyntax', 'a declaration fault: nonLiteral', + 'a stop as the CLI starts', + 'a start refuses an unreadable claim', ]), 8: anyOf([ 'a declaration fault: brokenVitest', @@ -567,6 +583,9 @@ export const partitions = { 'an awaiting config in a package with no module type', 'a declaration fault: configNoDefault', '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', @@ -579,6 +598,12 @@ export const partitions = { 'a .ts config in a package with no module type that calls require', 'ordinary tests left out by default', 'a declaration fault: configNull', + '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', @@ -593,6 +618,10 @@ export const partitions = { 'a declaration fault: configThrows', 'a reset check after its warm daemon was replaced', "a probe branch under a generated test's work bound", + 'a stream log lost after its note, then completed', + 'a supervised child exits when its supervisor is killed', + 'an unsupervised run stopped after its note', + '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`) + } + } + }) })