Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
72 commits
Select commit Hold shift + click to select a range
919c9a8
test(oracle-gaps): law 15 owes a stream log that the first line names
KyleAMathews Nov 13, 2026
17ea634
test(oracle-gaps): a refusal after a check started names its stream l…
KyleAMathews Nov 13, 2026
ceeeaf6
feat(oracle-gaps): write the stream to <out>/stream.log and name it f…
KyleAMathews Nov 13, 2026
23b47d5
Merge origin/main (#48, #54) into feat/gap-cli-stream-log
KyleAMathews Nov 13, 2026
5a92a3e
fix(oracle-gaps): own the stream log in the supervisor; refuse a seco…
KyleAMathews Nov 13, 2026
fd5655d
wip(oracle-gaps): checkpoint at the pre-restructure CLI with the orac…
KyleAMathews Nov 13, 2026
4d6cc15
fix(oracle-gaps): claim the output directory atomically and release r…
KyleAMathews Nov 13, 2026
a2d51b9
fix(oracle-gaps): install the stop handlers before any project module…
KyleAMathews Nov 13, 2026
2a0fdda
test(oracle-gaps): the spawn stop signals once the CLI has started, d…
KyleAMathews Nov 14, 2026
f5b7db8
Merge remote-tracking branch 'origin/main' into feat/gap-cli-stream-log
KyleAMathews Nov 14, 2026
76522ff
test(oracle-gaps): one decision for whether a refused run owes its note
KyleAMathews Nov 14, 2026
a784642
fix(oracle-gaps): install the stop handlers before the started marker
KyleAMathews Nov 14, 2026
d338cb1
fix(oracle-gaps): take over a stale claim under a mutex, and name res…
KyleAMathews Nov 14, 2026
cb6caf7
Merge remote-tracking branch 'origin/main' into feat/gap-cli-stream-log
KyleAMathews Nov 14, 2026
6222e25
ci(oracles): place the new Windows fixed-seed units in shards
KyleAMathews Nov 14, 2026
5fa74e0
chore(oracle-gaps): drop the unsupervised POSIX seam
KyleAMathews Nov 14, 2026
9560e86
fix(oracle-gaps): create the takeover mutex with its pid, and never t…
KyleAMathews Nov 14, 2026
c8352b8
docs(oracle-gaps): document every test-only ORACLE_GAPS_TEST hook
KyleAMathews Nov 14, 2026
7db86c5
test(oracle-gaps): hold the exit at a named point, and delete the wal…
KyleAMathews Nov 14, 2026
e2a74ad
test(oracle-gaps): constructed histories for the stale-claim race and…
KyleAMathews Nov 14, 2026
f3d8d77
test(oracle-gaps): claimScenario last in the draw order; claim states…
KyleAMathews Nov 14, 2026
52c2740
test(oracle-gaps): sequence the stale-claim race with a held run, not…
KyleAMathews Nov 14, 2026
70e294c
test(oracle-gaps): generated histories never draw a claim scenario
KyleAMathews Nov 14, 2026
8aa7c10
test(oracle-gaps): a claim race that ends before the mutex is an outcome
KyleAMathews Nov 14, 2026
76ce6a7
ci(oracles): place the claim histories in fixed-seed shard 1
KyleAMathews Nov 14, 2026
5aaa3a1
test(oracle-gaps): append the claim constructions, so existing seeds …
KyleAMathews Nov 14, 2026
2293582
fix(oracle-gaps): the stream log's note names it in forward slashes o…
KyleAMathews Nov 14, 2026
24412db
test(oracle-gaps): name the forward-slash spelling of a scratch path …
KyleAMathews Nov 14, 2026
0738650
fix(oracle-gaps): stale claims refuse; no takeover
KyleAMathews Nov 15, 2026
71dbed9
test(oracle-gaps): define the claim state map; a claim a start remove…
KyleAMathews Nov 15, 2026
035dcc5
test(oracle-gaps): a stream log lost after its note, then stopped or …
KyleAMathews Nov 15, 2026
5c0a895
fix(oracle-gaps): review of the delta: determinism, unreadable claims…
KyleAMathews Nov 15, 2026
ea9895a
Merge origin/main into feat/gap-cli-stream-log
KyleAMathews Nov 15, 2026
3ecbba8
fix(oracle-gaps): the mid-run check's stream check gets the run's log…
KyleAMathews Nov 15, 2026
70928c1
fix(oracle-gaps): a mid-run run that refuses owes no note, as the col…
KyleAMathews Nov 15, 2026
ffe88c7
fix(oracle-gaps): the overlap observation names the holding pid only …
KyleAMathews Nov 15, 2026
9d71756
fix(oracle-gaps): a daemon refusal keeps the output directory it names
KyleAMathews Nov 15, 2026
f2934fb
fix(oracle-gaps): every refusal names its run's output directory, def…
KyleAMathews Nov 15, 2026
2724b2d
test(oracle-gaps): a default-directory refusal is judged on its shape…
KyleAMathews Nov 15, 2026
92d7ab0
test(oracle-gaps): the daemon's refusal is judged on its directory as…
KyleAMathews Nov 15, 2026
e39f0d2
test(oracle-gaps): a default-directory refusal names the directory th…
KyleAMathews Nov 15, 2026
ce6131d
test(oracle-gaps): a default run's report may be named by the scratch…
KyleAMathews Nov 15, 2026
a6e6761
test(oracle-gaps): the static oracle normalizes a default output dire…
KyleAMathews Nov 15, 2026
0ef2144
fix(oracle-gaps): delta check: claim cause and fix, mid-list inserts,…
KyleAMathews Nov 15, 2026
d9d34dd
test(oracle-gaps): the supervised child exits when its supervisor is …
KyleAMathews Nov 15, 2026
7772ec3
test(oracle-gaps): the death witness waits for a silent child, so onl…
KyleAMathews Nov 15, 2026
7f935ec
fix(oracle-gaps): the death witness measures the child, and a held ch…
KyleAMathews Nov 15, 2026
dc3b2b1
Merge origin/main into feat/gap-cli-stream-log
KyleAMathews Nov 15, 2026
789301c
docs(oracle-gaps): the supervisor death witness names its platform scope
KyleAMathews Nov 15, 2026
8120cb8
fix(oracle-gaps): progress durations are not compared; the supervisor…
KyleAMathews Nov 15, 2026
8246f4d
fix(oracle-gaps): claim fix lines print a posix path; the supervisor-…
KyleAMathews Nov 15, 2026
658b5f9
fix(oracle-gaps): a daemon-served check writes to the directory its r…
KyleAMathews Nov 16, 2026
1c4dc72
test(oracle-gaps): the POSIX oracle reaches the daemon request that n…
KyleAMathews Nov 16, 2026
f91c7dc
Merge origin/main (#115) into feat/gap-cli-stream-log
KyleAMathews Nov 16, 2026
c3b6741
test(oracle-gaps): the eight #57 drawn fields are constructed-only, a…
KyleAMathews Nov 16, 2026
8c3e1bb
test(oracle-gaps): place the unsupervised default-directory history i…
KyleAMathews Nov 16, 2026
2a49e79
test(oracle-gaps): the cli observation compares gap lines as a sorted…
KyleAMathews Nov 16, 2026
067da4c
Merge origin/main (#103) into feat/gap-cli-stream-log
KyleAMathews Nov 16, 2026
31fb85f
fix(oracle-gaps): merge-gate fixes: limits, changeset, and nits
KyleAMathews Nov 16, 2026
c466605
test(oracle-gaps): the stderr gap lines are compared as a sorted set,…
KyleAMathews Nov 16, 2026
fd6ef6a
Merge origin/main (#61) into feat/gap-cli-stream-log
KyleAMathews Nov 16, 2026
c6779eb
test(oracle-gaps): draw #57's fields, judge win32 stops, and witness …
KyleAMathews Nov 16, 2026
c72dd14
test(oracle-gaps): the unsupervised witness stops after its note, and…
KyleAMathews Nov 16, 2026
cfcc7fa
test(oracle-gaps): the unsupervised witness is a stop held at the run…
KyleAMathews Nov 16, 2026
9c8110d
fix(oracle-gaps): a start hold released by the stop, no ps, and a dan…
KyleAMathews Nov 16, 2026
d2d7235
test(oracle-gaps): a blocked log refuses after the arguments and befo…
KyleAMathews Nov 16, 2026
6c958ed
test(oracle-gaps): split the warm and abort stops of every outcome cl…
KyleAMathews Nov 16, 2026
c42eec9
test(oracle-gaps): the warm and abort stop histories run over the sto…
KyleAMathews Nov 16, 2026
61915af
Merge origin/main (#121) into feat/gap-cli-stream-log
KyleAMathews Nov 16, 2026
6ea6f82
Merge origin/main (#128) into feat/gap-cli-stream-log
KyleAMathews Nov 16, 2026
ffc418c
test(oracle-gaps): the rejected batch's note names its log on one line
KyleAMathews Nov 16, 2026
07766d3
fix(oracle-gaps): the note line escapes a control character in its lo…
KyleAMathews Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changeset/gap-cli-stream-log.md
Original file line number Diff line number Diff line change
@@ -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 <out>/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 `<out>/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.
47 changes: 38 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <out>/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 `<file>.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
Expand All @@ -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
Expand Down
15 changes: 14 additions & 1 deletion packages/oracles/oracle-gaps/args.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
7 changes: 5 additions & 2 deletions packages/oracles/oracle-gaps/daemon.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion packages/oracles/oracle-gaps/ending.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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`,
)
Expand Down
Loading
Loading