Skip to content

fix(oracle-gaps): retire a batch's copies from Vitest's state - #61

Merged
KyleAMathews merged 66 commits into
mainfrom
fix/gap-cli-retention
Nov 16, 2026
Merged

KyleAMathews merged 66 commits into
mainfrom
fix/gap-cli-retention

Conversation

@KyleAMathews

@KyleAMathews KyleAMathews commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

The gap CLI kept Vitest and Vite state for every mutant copy after its batch had finished. Each copy is a new file. Vitest kept its path in filesMap and pathsSet, and its file and test tasks in idMap. Vite kept a module node and a transform for each copy. On the klona four-file suite (295 mutants, 2 contexts), the child ran out of a 2 GB heap before the check ended.

This PR removes a batch's copies from Vitest's and Vite's state once the batch ends, however it ends. It keeps the context registry (indexOf, contextSpecs) in step with the live contexts. A cold check's store keeps no unit.

The retention law reads the hook's lines from ORACLE_GAPS_TEST_RETENTION. After the merge-gate review, the hook moved into oracle-gaps/retention-hook.mjs. The CLI loads that module only when a hook variable is set. The module ships with the package, because a shipped file may cite only files its package ships (eslint-plugin shipped-citations, maintainer finding F16). Each field now observes the real objects:

  • the cold store, by whether a full collection leaves the entries it was given reachable;
  • open contexts, by Vitest's own close state.

The law judges every line written for a call's --out, whichever process wrote it. It counts batches by each batch's own index.

#61 no longer changes packages/oracles/src: git diff origin/main...HEAD -- packages/oracles/src is empty.

Law and authority

  • Bounded retention (e2e oracle, checkpoint retention, retentionBreaches). After each settled or rejected batch:

    • no Vite node names one of its copies (copyNodes);
    • no non-copy file has more than one node beyond the measured plain-plus-?raw pair (nonCopyDup);
    • Vitest's filesMap, pathsSet, idMap, errorsSet and leakSet have their sizes from before the batch.

    Before each batch:

    • every indexOf entry names a live context at its own slot, and every contextSpecs key names a live context;
    • every context that left the live array has started to close, by Vitest's own closingPromise (staleIndexed, staleSpecs, staleOpen).

    Authority: register C "fix(oracle-gaps): retire a batch's copies from Vitest's state #61 retention decisions" (retained Vitest and Vite state is removed after a batch).

  • Cold store (register C "fix(oracle-gaps): retire a batch's copies from Vitest's state #61 retention decisions" (1)): a cold check gives its store entries, and a full collection leaves none of them reachable (held). A daemon's store keeps its entries by design, so held is judged on cold calls only.

  • One line per batch (register C "Runner laws" L2: exactly one line per batch, however the batch ends).

    • Each line carries its batch's own index within its check, taken when the batch starts.
    • A check that reached its report owns indices 0..n-1, each once.
    • Some calls may leave the batches they were running at their end with no line: a check that ended before its report (the rejected batch, a stopped run) and a daemon the driver killed. For these, each index appears at most once.
    • The rejected batch's own line, with its state after retirement, is owed.
  • Line ownership (coordinator ruling of 2026-11-15 on fix(oracle-gaps): retire a batch's copies from Vitest's state #61: lines are counted per writing pid):

    • A line is the call's own when its pid equals the check.pid that the call's check wrote.
    • The only other pid allowed is a daemon that the driver killed during the call (daemonChecks) and that is dead when the line is judged.
    • Any other pid, or no pid, is a breach (foreignLine): two processes ran one call's check.
  • Non-copy bound (register C "fix(oracle-gaps): retire a batch's copies from Vitest's state #61 retention decisions" (2) and (3)): this is unchanged.

  • Rejected batch, check order (register C "E2E completion first" and P10):

    1. The output namespace, process warnings and config lines are judged first, as for any run.
    2. Bounded retention is judged next.
    3. Then exit 3 and an internal error's done line, last on both stdout and stderr.

    The stream law is not applied to this run.

Decisions

  • P9 (oracle-first): each oracle change has a RED, run as a hostile mutant on the parent's oracle or on this head. See below.
  • P7 (no weakening): no comparison is relaxed.
    • held replaces the store's own size, which read 0 for main's store.
    • staleOpen reads Vitest's own state, not a set kept for the hook.
    • Lines from other pids are judged, not dropped.
    • The index law replaces a comparison with the CLI's own counter.
    • The rejected batch's done line is now also judged on stderr.
  • F1: no framework change. rejectBatch is taken back inside the model's histories mapping, as main does for pauseEngages and warmReplaced (register: "Generator rule, extended"). The ConstructedHistory.unbuild addition (954a5f3, cb25107) is reverted.
  • Test-only hooks (register): ORACLE_GAPS_TEST_RETENTION and ORACLE_GAPS_TEST_REJECT_BATCH are inert unless set, and the README's test section documents them, including check.pid, pid, batch, held and the full collection.
    • The retention hook only observes. It runs gc() (exposed through v8.setFlagsFromString and vm) after a setImmediate turn before it writes each line.
    • The reject fault triggers the rejection path a real crash takes: the batch's run completes, so its copies are in Vitest's and Vite's state, and then its promise rejects.
  • Generator rule: the constructed histories keep main's 30, in main's order, and a batch whose run rejects is appended as the last one. rejectBatch is fc.constant(0) in the drawn record, last in the draw order, and recorded in history-fingerprint.json.
  • F10, user-visible output: evidence.batches is deleted, so results.json is unchanged from main. The unread removed count, the globSpecs wrapper, the openContexts set, the replacing count and memoryStore().size are also deleted.

Evidence

Head: 1f67a4b. It merges main at 9aed105 (#115, #103): #103's five new constructed histories come first, after main's earlier ones, and a batch whose run rejects is the last. rejectBatch follows testRoot and loadPlugin in the drawn record and in the fingerprint. Runs on the Arclet pool are tagged r61-g-*-1f6 (and r61-f-*-7d0 at the previous head), with logs in /tmp/arca-results/. Local runs used /tmp/e2e-lock.sh, with logs in /tmp/fix61-logs/. Each mutant is a scratch branch scratch/fix61-<name>-g (local, not pushed). Each one is the same mutant commit, cherry-picked onto every head that was tested.

  • Law: as stated above.

  • Reach: these are the fixed-seed shards at 7d0eccb (r61-f-g1/g2/g3-7d0; shard 3 at 1f67a4b passes 50 tests with the same states), summed over shards:

    State Reached
    "a rejected batch retired its copies and logged them" 1 (shard 3)
    "a killed daemon's retention lines were judged as its own" (new, required through incrementalStates) 1 (shard 3)
    "a check whose daemon held it past the CLI's wait, then died" 1
    "a check that ran more than one batch" 19 (2 + 4 + 13)
  • RED and mutants: each row runs the new oracle against a hostile change. Where the old oracle (head 099bf0a) was blind, the "Old oracle" column says so.

    Finding Mutant (site) Old oracle at 099bf0a New oracle at 1f67a4b
    F5 skip retireCopies on rejection (if (raced && !cut)) o-rejretire (local): passes, so the old fault was vacuous r61-g-m-rejretire-1f6: killed, retention (copyNodes, filesMap, idMap, pathsSet)
    F5 the race outside the try (79f1dea reverted) (RED of 79f1dea, earlier) r61-g-m-raceout-1f6: killed, retention (rejectLine)
    F6 store main's memoryStore (rows Map, no size) o-mainstore (local, 3 histories): passes r61-g-m-mainstore-1f6: 3 failed, retention (held), retention:partial (held)
    F6 open closeContext never closes (Promise.resolve) o-neverclose (local, the same history, the set deleted but never closed): passes r61-g-m-neverclose-1f6: killed, staleOpen at retention, retention:daemon and retention:cold
    F4 a line without pid killed by the count, by reasoning (not run) r61-g-m-nopid-1f6: 3 failed, foreignLine
    F4 two processes run one call's check (the daemon checks, and the CLI also runs checkCold into the same --out, and then reports the daemon's summary) o-twoproc2 (local): fails only on reach (the cold re-run overwrites results.json's reuse counts); retention does not see it r61-g-m-twoproc2-1f6: killed, retention:daemon (foreignLine)
    F11 the line names the shared counter at write time (head's form) not seen by the count r61-g-m-sharedidx-1f6: 2 failed, retention (batchIndex), retention:daemon (batchIndex)
    F9 no-retire (retireCopies never runs) r61-g-m-noretire-1f6: 3 failed, copyNodes, filesMap, idMap, pathsSet
    F9 leak (the replaced context kept, not closed) r61-g-m-leak-1f6: killed, staleOpen
    F9 indexOf kept on replace r61-g-m-indexof-1f6: killed, staleIndexed
    F1 rejectBatch: 0 removed from the take-back (scratch 67d8091) the load fails: "constructed history "a batch whose run rejects" built a history the arbitrary cannot take back"

    The histories for these runs:

    • the rejected batch: fixed seed 20261105: a batch whose run rejects;
    • store, nopid and noretire: a package with no config, a load failure beside a hang and two authored mutants;
    • never-close and leak: an edit that changed the cold result after a hang replaced the only context;
    • indexOf: a lazy module loaded before a hang in the same batch;
    • two processes: an edit sequence through the daemon;
    • shared index: two authored mutants and an edit sequence through the daemon.

    Command: pnpm exec vitest --run --config oracle-gaps/vitest.config.mjs gap-report-oracle -t "<history>$".

  • GREEN at 1f67a4b:

    • r61-g-g1-1f6: 3 passed;
    • r61-g-g2-1f6: 5 passed;
    • r61-g-g3-1f6: 50 passed;
    • r61-g-rejdet-1f6: random seed and determinism of the rejected batch pass, and random seed: an edit sequence through the daemon passes. determinism: constructed history: an edit sequence through the daemon failed: see "Determinism of the daemon history" below.
    • CI run 43811995544: every blocking job passed. See "CI" below.

    Command: pnpm exec vitest --run --config oracle-gaps/vitest.config.mjs gap-report-oracle -t "$(node scripts/pr-shards.mjs pattern oracle-gaps-fixed-seed N)".

  • The finding the mutants found in the driver: the shared-index mutant's run of "every outcome class" also reported retention:stop (foreignLine) on a GREEN code path. Every stop of a history writes under out-stop, so the lines of an earlier stop were read as this stop's. The driver now takes only the lines that a stopped run appended (ff5c021).

Klona memory

This is unchanged since 65880b6, and it was not re-measured. The retirement and store code is the same, and the hook changes do not run without the variable. Command: NODE_OPTIONS=--max-old-space-size=<MB> /usr/bin/time -l node <CLI>/index.mjs --package /tmp/oom/klona --source src/index.js,src/lite.js,src/full.js,src/json.js --seed 20261112 --contexts 2 --mutants /tmp/oom/mutants --out <dir>. Logs are in /tmp/r61-klona/.

Commit Heap Exit Peak RSS
head 65880b6 1024 MB 0 1,919,205,376 B
head 65880b6 2048 MB 0 2,202,779,648 B
main 35422e3 1024 MB 3 (out of memory) 1,972,060,160 B
main 35422e3 2048 MB 3 (out of memory) 3,374,268,416 B

Weight

Method: each file is minified with esbuild 0.28.2 and then compressed with gzip -9, from git archive. "Published" means the oracle-gaps files that package.json files ships.

Scope main 9aed105 old head 099bf0a (on main 4d3c8a9: 117,518 / 47,419) head 1f67a4b
Published oracle-gaps, minified / gzip 117,490 / 47,430 (15 files) 121,086 / 48,614 (15 files) 121,869 / 49,323 (16 files)
check.mjs, minified / gzip 35,277 / 14,121 38,922 / 15,319 37,208 / 14,812
retention-hook.mjs (loaded only under a hook variable) none none 2,508 / 1,221
  • Against main, head adds +4,379 B minified and +1,893 B gzip. Of that, the hook module accounts for 2,508 / 1,221, and the CLI never loads it without a hook variable. The code a normal run loads adds +1,871 / +672.
  • Against the old head's own base, the old head added +3,568 / +1,195. Head's normal-run code is 1,697 / 523 below that.
  • The total published bytes are 783 / 709 above the old head, because the hook module has to ship (F16) and as a module of its own it costs more. Inlining it in check.mjs would remove the module overhead, but the hook code would then sit in the normal run path, against the F10 ruling.
  • The growth in the normal path is the retirement itself: retireCopies, retireModules, viteEnvironments and their shape guards, the registry swap, and the race in the try.
  • No byte reaches a user's production bundle (register C "Zero shipped bytes").

CI

Run 43811995544 at 1f67a4b. Every blocking job passed, and every one finished under 10 minutes. The longest were:

  • Gap e2e fixed seed 2/3: 7m32s;
  • Gap e2e fixed seed 3/3: 7m00s;
  • Windows e2e 1/10: 6m04s;
  • Framework self-oracle 8/8: 5m48s.

The run at 7d0eccb (43805253378) failed Test eslint-plugin-oracles and Windows unit suites on shipped-citations. At that head check.mjs cited retention-hook.mjs, which the package did not ship. 1f67a4b fixes this by shipping the file.

Windows (non-blocking, #73)

From run 43811995544 at 1f67a4b:

  • 4/10 (9m13s): the stopped run's last line is done completed, not the SIGABRT ending. This is the same as main (fix(oracle-gaps): supervise the check on win32; log each CLI run in the e2e driver #79).
  • 2/10 (11m33s, over the 10-minute budget): this failed every outcome class on key stability: w_fastturn:if-false was killed in the first run and not-observed in the stability rerun. The time includes shrinking the failing history.
  • 3/10: passed this time.

At 099bf0a (run 43729584796), 3/10 failed with "161 gap lines for 160 gaps". I compared the 161 streamed lines with the model's 160 gaps for the failing history (replayed with ORACLE_PATH=0:0). The extra line is gap not-observed L113 sut.ts:M95 x > 2 → false ``. That is the same w_fastturn:if-false mutant. The model predicts it killed, by the work law in a test that waits a turn.

The same comparison on #87's failing job (#73 at 104376d, before any #61 code) finds the same extra mutant (L121 sut.ts:M112). The classification comes from the copy's capture rows, its work count and their time-dependency marks, and #61 does not change how those rows are read. Retirement runs after the units are plain data, and it removes only the copies' own nodes and entries. By that inspection, both 2/10 and 3/10 are #87's mutant, which is nondeterministic on win32, and not #61's.

Determinism of the daemon history

determinism: constructed history: an edit sequence through the daemon differs at the start step. In one run of the two, the second of the two checks started at once has the note test output line, and in the other run it does not. Main has the same difference (register "Main's determinism failures", #82). It failed 1 of 5 times at 9aed105 (r61-det-main-1…5; main's observation 1). On #61 heads it failed:

  • 2 of 3 at 099bf0a;
  • 1 of 3 at 7d0eccb;
  • 3 of 4 runs with logs at 1f67a4b (observation 4, the same text); one more run was counted without a kept log.

A lookup diagnostic (scratch a901573, r61-diagdet-1…3, where 1 of 3 failed) shows the cause. Whichever of the two concurrent calls the daemon serves first computes every unit, and the other reuses all of them. So the observation depends on which CLI process reaches the daemon first, which is a wall-clock race between processes in the driver (register "Determinism under load covers witnesses"). The rate on #61 heads is higher in these small samples. I did not find a #61 change that decides the order.

Limits

This pull request and its description were written by Isaac.

A check runs each mutant in a new copy of its test file. Vitest's state kept
every file and test task it ever ran (filesMap by path, idMap by task id), so
a check held every test of every copy: about 377k test cases on a four-file
suite, which exhausted a 2 GB heap. Once a batch's units are plain data, its
copies leave the state: their stale idMap entries go first (shape-guarded),
then clearFiles replaces each path's file entry.

Co-authored-by: Isaac <no-reply@databricks.com>
@coderabbitai

coderabbitai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@changeset-bot

changeset-bot Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 1f67a4b

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@pkg-pr-new

pkg-pr-new Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

npm i https://pkg.pr.new/TanStack/oracles/@tanstack/eslint-plugin-oracles@61
npm i https://pkg.pr.new/TanStack/oracles/@tanstack/oracles@61

commit: 1f67a4b

@KyleAMathews
KyleAMathews marked this pull request as ready for review November 13, 2026 18:11
@KyleAMathews
KyleAMathews marked this pull request as draft November 13, 2026 18:21
KyleAMathews and others added 4 commits November 13, 2026 11:31
The gap CLI's e2e driver sets ORACLE_GAPS_TEST_RETENTION on each run and
records one line per batch: the count of Vitest state entries (filesMap,
pathsSet, idMap) and Vite module nodes that still name the batch's retired
copies. The law: each count is 0 after retirement. This commit adds the hook
and the law, not the fix, so CI records the RED on the parent code.

Co-authored-by: Isaac <no-reply@databricks.com>
… file entry

Vitest's clearFiles replaces a copy's file entry, and leaves its path in
pathsSet, one placeholder task in idMap, and Vite's module node and transform
for the copy. The retention law (bounded retention, after each batch) fails on
46dfd3e in CI: each count is nonzero.

retireCopies now removes the copy's filesMap key, pathsSet entry, and idMap
tasks. retireModules invalidates each copy's module through Vite's API and
removes it from every environment's graph maps. Both guard the shapes they
touch and throw if one changes, so a Vitest or Vite that changes them fails
loudly rather than leaking.

Co-authored-by: Isaac <no-reply@databricks.com>
… log

When the cold run exits 3, its stack is in its error.log. The incremental
violation named only the exit code, so a failure printed no stack. It now
appends the error log the driver already reads for a run that exits 3.

Co-authored-by: Isaac <no-reply@databricks.com>
…rror log

ce46f4b appends cold.stderr to the incremental violation when the cold
run exits 3, but the incremental observation's cold run had no stderr,
so the message stayed empty. It now carries the run's stderr, with its
error.log, when it exits 3, and only then: a completed run's stderr holds
timings, which differ between two runs of one history.

Co-authored-by: Isaac <no-reply@databricks.com>
…s not retired

A replaced context stayed reachable through indexOf and contextSpecs, which
were never cleared for it, so its Vitest and Vite state stayed too. replace now
drops both entries. A run cut off by a hang is not retired: its worker may still
send updates, and its context is replaced by the caller.

Also: the etag map is cleaned by node identity (Vite keys it by the etag), and
the retention observation is the count of batches left with a retired copy's
state, which is deterministic, not the per-batch lines.

Co-authored-by: Isaac <no-reply@databricks.com>
@KyleAMathews
KyleAMathews marked this pull request as draft November 13, 2026 22:58
KyleAMathews and others added 8 commits November 13, 2026 16:03
…s size before the batch

The hook now snapshots every structure a copy can leave state in (Vitest's
filesMap, pathsSet, idMap, errorsSet, leakSet, and each Vite environment's
url, id, etag and file maps and transformed nodes) before a batch, and the law
requires each to return to its size after the batch's retirement. The law was
tautological before: it counted the same predicate the deletion used.

The retention observation is observed from every run kind (cold, daemon,
stability, partial), and a run that computed a unit must have written a batch
line. A check that ran more than one batch reaches a declared state.

Co-authored-by: Isaac <no-reply@databricks.com>
…a batch line is owed by mutant results

The totals now include the excess of indexOf and contextSpecs over the live
contexts, which must be zero before each batch: a context replaced between
batches is caught there, not by a single batch's before and after.

The missing-line expectation read evidence.computed, which counts single-file
runs that write no batch line, so it failed on ce6c93d. A run owes a batch
line when a mutant has owner files, since such a mutant's units ran in batches.
Without that check, a retirement that never runs writes no line and passes the
count law vacuously: the no-retire ablation exited 0.

Co-authored-by: Isaac <no-reply@databricks.com>
Co-authored-by: Isaac <no-reply@databricks.com>
The cold check's store kept every computed unit, with its rows, for the whole
run: 207 store entries and 103,585 row entries in the ce6c93d heap snapshot.
A cold run serves no lookup (evidence.reused is 0 on every klona run), so the
store now keeps nothing. The daemon's disk store is unchanged.

The retention totals include the store's size, which must match before and
after each batch. Paired identity runs (pre-change and this commit, both
cut 0) give the same 391 results, and the baseline matches both.

Co-authored-by: Isaac <no-reply@databricks.com>
…hes are logged

evidence.batches counts every batch run (cut or not). Each batch writes one
retention line, so each run's line count must equal batches: a run with no line
for a batch it ran (the no-retire mutant) fails the law. A cut batch writes its
before line, so the stale totals of a replaced context are checked there.

Co-authored-by: Isaac <no-reply@databricks.com>
…t every cached module

Vite's graph caches non-copy modules (a source or harness file, on first import),
which legitimately grow during a batch; the before-and-after equality was wrong
for Vite keys. The law now requires the copies' own module nodes to be zero
after each settled batch, and keeps the before-and-after equality for Vitest's
state, the store, and the stale context totals.

Co-authored-by: Isaac <no-reply@databricks.com>
…on-copy nodes to one per file

Vite's totals are named vite.<environment>.<map>, so the law tells them from
Vitest's state by an explicit prefix the hook generates. After each settled
batch, the copies' own module nodes must be 0, and each non-copy file (query
stripped) has at most one node in each environment's graph: a file cached once
per batch under a fresh id fails the law.

Co-authored-by: Isaac <no-reply@databricks.com>
…o the completion law; the multi-batch state is declared

A run with no report owes no batch line here: the completion law judges it, keyed on the
model's prediction (a report unless a refusal is predicted), and fails it with its exit
status and stderr. The multi-batch reach state is declared in the property's measured list.

Co-authored-by: Isaac <no-reply@databricks.com>
KyleAMathews and others added 7 commits November 14, 2026 10:10
…ched

Co-authored-by: Isaac <no-reply@databricks.com>
… per package, counted as a delta

A daemon keeps the environment of the call that started it, so a later daemon
check wrote its retention lines to the hook file of the call that started the
daemon, and its own (new) hook file was empty: the exact batch-line count
failed on a correct run (retentionLines:daemon on the hang history). Counting
side: every call for a package writes to one file, and a run's lines are the
ones after its start. The production batch-line contract is unchanged.

Co-authored-by: Isaac <no-reply@databricks.com>
…tory; a run keeps its own lines

Replaces the delta: a daemon serves many calls and keeps the first caller's environment,
so a line is attributed to the check that wrote it (its out directory, the test hook's
only addition), and the run keeps the lines that name its own out directory. Two daemon
checks at once against one hook file cannot mix. No production outcome changes.

Co-authored-by: Isaac <no-reply@databricks.com>
…able names each run's batches and lines

Diagnostic for the daemon line mismatch (the test hook only; no production outcome changes).

Co-authored-by: Isaac <no-reply@databricks.com>
… retention lines are its own

The table showed the cause: a daemon serves several checks of one test, and two of them shared an
out directory, so a run kept lines written by an earlier check (batches 1, lines 4; a run with 0 batches
kept 1). Production wrote one line per batch in every run. The counting side is wrong: each call gets
its own directory, so the run filter sees only its lines. The debug table is removed (it was for this
diagnosis). No production change.

Co-authored-by: Isaac <no-reply@databricks.com>
…tories runCli gives each call

Each call's out directory is numbered (out-<n>, out-daemon-<n>, ...), so the outputs of a run are
its own. The law's list of own outputs names the fixed ones; the numbered ones match the same pattern
the driver creates (OWN_NUMBERED). Without it, a run's out-25 writes read as strays.

Co-authored-by: Isaac <no-reply@databricks.com>
…as given

Repair, not widening (P7): the law listed fixed output names (out, out-daemon, out-stop, out-only), and
numbered names were a pattern. Now each run's allowed output is the one path the model predicts (its
--out, from cliArgs): runCli passes its numbered out, the stop law passes out-stop. A CLI that writes
under any other directory, such as out-<n>-next, is a stray. The lists are removed.

Co-authored-by: Isaac <no-reply@databricks.com>
KyleAMathews and others added 15 commits November 14, 2026 22:41
…r fingerprint lists

The generator canary (gap-report-history-fingerprint) records each field's draws in draw order, and a
new field is recorded at the end of both lists. rejectBatch (the constant 0, drawn last) is appended in
drawn and histories; every earlier line is unchanged.

Co-authored-by: Isaac <no-reply@databricks.com>
…amespace law

The earlier exemption skipped the namespace law for the constructed rejected batch. Restored: the law judges
every write of that run. Whatever an internal error leaves behind is then either removed by the CLI or
predicted by the model, decided on the evidence of the run that follows.

Co-authored-by: Isaac <no-reply@databricks.com>
# Conflicts:
#	packages/oracles/oracle-gaps/gap-report-model-oracle.mjs
#	packages/oracles/oracle-gaps/gap-report-oracle.property.test.mjs
#	packages/oracles/oracle-gaps/history-fingerprint.json
#	packages/oracles/scripts/pr-shards.mjs
…andom config cannot refuse it before its batch

The random-seed run of the constructed history drew a CommonJS package with a .js config, which the CLI refuses
before any batch, so no batch ran and no retention line was written (retentionLines:reject). The constructed
history now pins its package type and config file (ordinary values, so its take-back stays in the language),
and the fixed and determinism units were already unaffected.

Co-authored-by: Isaac <no-reply@databricks.com>
…fig placement

A random run drew a native addon and a config in the parent directory, which the CLI refused before its batch
(retentionLines:reject again). The history pins both to the values of the daemon history, so no random
scenario setting refuses it.

Co-authored-by: Isaac <no-reply@databricks.com>
… wrote them

A line named its run's output directory only, so a daemon the CLI killed mid-check (its batches ran and wrote
lines to that directory) was counted against the run that reported, which ran no batch of its own
(retentionLines:daemon on the dieMidCheck step, shard 3 of the merged head). The hook line now carries the
writing process's pid (observation only). A run's retention is its child's lines; the lines a daemon it
killed wrote are judged as that daemon's: each complete and retired (retention:killed). A killed process
reports no batch count, so its count is not judged here; the batch it died in writes no line (a Limit).

Co-authored-by: Isaac <no-reply@databricks.com>
…retention lines are attributed by it

The CLI runs its check in a supervised child, so the pid of the process the driver spawned is not the process
that writes the lines (the first attribution failed every cold run). Under ORACLE_GAPS_TEST_RETENTION the check
writes its own pid into its output directory (observation only), and the driver attributes a run's lines to
that pid. A daemon the CLI killed writes other pids, and its lines are judged as that daemon's (retention:killed).

Co-authored-by: Isaac <no-reply@databricks.com>
…the framework's unbuild is reverted

The constructed history "a batch whose run rejects" sets the constructed-only
field rejectBatch. Main's mechanism for such fields (register: generator rule,
extended) takes them back inside the model's histories mapping, as it does for
pauseEngages and warmReplaced, so the framework's membership check (F20) is
unchanged. This reverts the ConstructedHistory.unbuild addition (954a5f3,
cb25107): #61 no longer changes packages/oracles/src.

Co-authored-by: Isaac <no-reply@databricks.com>
… writer, and counts batches by their own index

The retention hook moves into retention-hook.mjs, which the CLI loads only
when a hook variable is set and which the package does not publish. Its
fields observe the real objects (review of #61, F6): staleOpen reads Vitest's
own close state of each context that left the live array, and the cold
store's law counts the entries given to put that a full collection leaves
reachable (held), in place of a size the store reported about itself. The
openContexts set, the replacing count, the memoryStore size and
evidence.batches, kept only for the hook, are deleted (F10), with the unread
retireModules count and the globSpecs wrapper.

Each line carries its batch's own index (F11). The law over one call's lines
(retentionBreaches) judges every line for the call's --out: a line from a pid
other than the check's is allowed only from a daemon the driver killed and
saw die, so two processes running one call's check, or a line with no pid,
is a breach (F4). A check that reached its report owns indices 0..n-1, each
once; a check that ended early, a stopped run and a killed daemon own each
index at most once. The warm and mid-run calls are judged too.

The rejected-batch fault now rejects after the batch's run completes, so its
copies are in Vitest's and Vite's state and their retirement is witnessed
(F5). Its run's done line is judged on both streams, and the Limits state the
actual check order. The README documents check.pid, pid, held and the new
batch index (F3).

Co-authored-by: Isaac <no-reply@databricks.com>
…nd check pid

Co-authored-by: Isaac <no-reply@databricks.com>
… reach state

Co-authored-by: Isaac <no-reply@databricks.com>
…pended

Every stop of a history writes under out-stop, so an earlier stop's lines
named the same run and a pid other than this stop's check (found by the
shared-index mutant's run of "every outcome class").

Co-authored-by: Isaac <no-reply@databricks.com>
Co-authored-by: Isaac <no-reply@databricks.com>
main's constructed histories and its testRoot and loadPlugin fields come
first; #61's rejected-batch history and its rejectBatch field follow them.

Co-authored-by: Isaac <no-reply@databricks.com>
…es its package ships

check.mjs imports retention-hook.mjs when a hook variable is set, and a
shipped file may cite only what its package ships (eslint-plugin
shipped-citations, maintainer finding F16). The CLI still loads the module
only when a hook variable is set.

Co-authored-by: Isaac <no-reply@databricks.com>
@KyleAMathews
KyleAMathews marked this pull request as ready for review November 16, 2026 13:34
@KyleAMathews
KyleAMathews merged commit fac63df into main Nov 16, 2026
47 of 49 checks passed
@KyleAMathews
KyleAMathews deleted the fix/gap-cli-retention branch November 16, 2026 13:34
KyleAMathews added a commit that referenced this pull request Nov 16, 2026
Main's constructed history from #61 ("a batch whose run rejects") comes
first; this branch's history stays appended after it. The Limits take
main's text with this branch's work-bound sentence.

Co-authored-by: Isaac <no-reply@databricks.com>
KyleAMathews added a commit that referenced this pull request Nov 16, 2026
#61's per-call output directories and retention hook meet #57's default
output directory: a run without --out keeps no suffix, and its check pid
and retention lines are read from the directory its note line names,
before the run's scratch directory is removed. main's constructed
history (a batch whose run rejects) and its rejectBatch field come first;
#57's follow.

Co-authored-by: Isaac <no-reply@databricks.com>
KyleAMathews added a commit that referenced this pull request Nov 16, 2026
#61's constructed history ("a batch whose run rejects") comes before #99's,
and its field rejectBatch before #99's hangMs; rejectBatch switches a
test-only hook, so it stays a constant. Its env rides on the history's shared
run options with #99's hooks. In runBatch, #61's try/finally (retire the
batch's copies, write the retention line) wraps #99's cut handling: the spin
rows, the built-in verdicts of cut copies, and the backstop's cause. The
context replacement keeps #99's bounded close (closeWithin) with #61's
registry swap. The fingerprint lists are recorded anew (M "Randomness wins").

Co-authored-by: Isaac <no-reply@databricks.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant