Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

test(parse-pool): the regression test for the counter fix, plus ten rounds of doc corrections (#657)

Joseph Mikhail6f72257bb115
diff --git a/core-ingestion/src/index.ts b/core-ingestion/src/index.ts
index 742973b8..1a701a05 100644
--- a/core-ingestion/src/index.ts
+++ b/core-ingestion/src/index.ts
@@ -16,21 +16,30 @@ import Parser from 'tree-sitter';
// tree-sitter-powershell required type=module -> 1 (*)
// @tree-sitter-grammars/tree-sitter-lua optional type=module -> 1
// tree-sitter-css optional type=module -> 1
-// the other 11 required grammars required type=commonjs -> 0
-// the other 11 optional grammars optional type=commonjs -> 0
+// every remaining required grammar required type=commonjs -> 0
+// every remaining optional grammar optional type=commonjs -> 0
// tree-sitter-sas optional type=module -> 0
// (full-filename main + "exports")
//
-// (*) INFERRED, not measured. `tree-sitter-powershell` is not installed in
-// every checkout -- it is absent from this one -- so its row comes from the
-// import comment below rather than from running Node against the package. CI
-// proves the subpath `bindings/node/index.js` resolves; it does not prove the
-// bare specifier would warn. Re-measure before relying on it. Marked because
-// an unverifiable row in this table is what went stale in #595 and cost
-// Ix#650 sixteen review rounds.
+// (*) INFERRED, not measured: nobody has run Node against the BARE specifier
+// `tree-sitter-powershell` and watched for the warning. Its row comes from the
+// import comment below, which describes the package's shape. That is the
+// durable reason, and it does not expire when the package is installed -- CI
+// installs it and proves the subpath `bindings/node/index.js` resolves, which
+// is a different thing from proving the bare specifier warns. (It was also
+// missing from the working copy this was written in, which is how the gap was
+// noticed, but do not read the marker as being about that: a clean `npm ci`
+// has it, since it is a plain `dependencies` entry in `package-lock.json`.)
+// Re-measure before relying on it, and do not clear the marker just because
+// the package is present. An unverifiable row in this table is what went
+// stale in #595 and cost Ix#650 sixteen review rounds.
//
-// The two 11s are a coincidence, not a copy-paste: 13 required grammars minus
-// c-sharp and powershell, and 14 optional minus lua, css and sas.
+// The rows above are deliberately not counted. What decides a warning is the
+// per-package shape, which is what this table is for; the required/optional
+// totals are arithmetic over `package.json` and belong to
+// `docs/parse-pool-teardown.md`. Restating them here is how the previous
+// version went stale -- #595 added a required grammar and the count under it
+// silently stopped being true.
//
// So the rule is `"type": "module"` + a directory `"main"` + no `"exports"`,
// which today means c-sharp (static, below) plus powershell, css and lua
@@ -67,7 +76,10 @@ import C from 'tree-sitter-c';
// @ts-ignore
import CPP from 'tree-sitter-cpp';
// tree-sitter-c-sharp is `"type": "module"` with a directory `"main"` and no
-// `"exports"` — the one required grammar that actually triggers DEP0151.
+// `"exports"`, so it needs the explicit file path. NOT the only required
+// grammar in that shape — tree-sitter-powershell is too, further down; the
+// table at the top of this file lists them. Saying "the only one" here is what
+// went stale when #595 added powershell.
// @ts-ignore
import CSharp from 'tree-sitter-c-sharp/bindings/node/index.js';
// @ts-ignore
diff --git a/docs/parse-pool-teardown.md b/docs/parse-pool-teardown.md
index f8666ff9..a75f33c3 100644
--- a/docs/parse-pool-teardown.md
+++ b/docs/parse-pool-teardown.md
@@ -16,16 +16,32 @@ landed BEFORE the test file the real-ingest arm drives:
|---|---|---|
| `084f472` | #570 | last build with the `terminate()` teardown |
| `20e1dae` | #598 | the fix -- teardown becomes `__shutdown` + `unref()` |
-| `b9b84ef` | #597 | adds `ingest-files.test.ts` |
+| `b9b84ef` | #597 | adds `ingest-files.test.ts` AND the loader's vm fallback |
So:
-- The **minimal harness** arm runs at `084f472`.
+- The **minimal harness** arm runs at `084f472` -- but the harness itself is
+ not in the repo, at that commit or any other, and it produced the 6.3% that
+ is the numerator of the ratios that compare it to real ingests -- 28× and
+ 3.86×, though not the 7× idle-vs-loaded further down, which is real against
+ real. So by this section's own standard it
+ is not reproducible either: the build is named, the program is not.
- The **real-ingest** arm needs both, and no commit has both -- checked every
- commit on `main`. It was measured on a hand-assembled tree: `b9b84ef`'s
- `ingest-files.test.ts` over `084f472`'s `parse-pool.ts`. An earlier revision
- of this file said "check out `084f472`", which gives "no such file". Say the
- recipe or the arm is not reproducible.
+ commit on `main`. It was measured on a hand-assembled tree: `084f472`, plus
+ TWO files from `b9b84ef` --
+
+ ix-cli/src/cli/__tests__/ingest-files.test.ts the harness itself
+ ix-cli/src/cli/commands/ingestion-loader.ts or it cannot run at all
+
+ The loader is not optional. `loadIngestionModules` reaches the built
+ `core-ingestion` through `new Function("return import(specifier)")`, and
+ inside vitest's vm context that throws `A dynamic import callback was not
+ specified`. `b9b84ef` added the fallback for exactly that; `084f472` has the
+ indirection and no fallback, so the ONE-file recipe an earlier revision of
+ this section gave -- the test file alone -- throws on the first `run()` and
+ measures zero ingests, not twelve. That is what the second file above
+ fixes. Before that it said "check out `084f472`", which gives "no such
+ file". Say the whole recipe or the arm is not reproducible.
- The **vitest** check needs the CURRENT tree, not either of those: its
"36 of 38" is today's count.
@@ -80,7 +96,17 @@ demonstration of agreement.
**Real ingests** — `ingest-files.test.ts` under vitest. That file drives a
FIXED number of ingests per process, not an average: **12** at `b9b84ef`, the
version measured (14 today). The per-teardown rate is `1-(1-p)^12` solved
-against the process counts:
+against the process counts.
+
+The exponent is TEARDOWNS, and 12 is the ingest count, so that step rests on a
+premise worth writing down: `ingestFiles` creates its pool lazily, through
+`ensureParsePool()`, so an ingest that parses no file tears nothing down. Every
+ingest in that file parses at least one — the `fixture(N)` calls are all
+N > 0, with `force: true` — so ingests and teardowns coincide there. Add an
+empty-repo or unsupported-extension case and they stop coinciding, and
+updating this
+exponent to the new ingest count would understate the rate with nothing red.
+That is the same unrecorded-derivation failure that made 9.5 unfalsifiable.
| configuration | result | per POOL teardown |
|---|---|---|
@@ -125,9 +151,15 @@ writing down.
The minimal harness overstates real exposure by **28×** on the only
load-matched comparison available (idle vs idle). Against the loaded real rate
-it is 3.9×, but that mixes conditions — the harness was never run loaded, and
-load raises the rate — so treat 3.9× as a lower bound on what is unexplained,
-not the residue after subtracting load.
+it is **3.86×** (6.3267 / 1.6397; the printed 6.3 / 1.64 gives 3.84, which is
+why this one is written to two decimals rather than rounded into an
+ambiguity). An earlier revision labelled 6.327 / 1.640 as "the unrounded MLE
+over the unrounded loaded rate" -- both are themselves rounded, and a reader
+following this file's own convention would recompute from the real values and
+think one of the two paragraphs wrong. That comparison mixes
+conditions — the harness was never run loaded, and load raises the rate — so
+treat it as a lower bound on what is unexplained, not the residue after
+subtracting load.
**Parses per worker is not controlled.** `ingestFiles` parses a `.ts` file
twice (index prescan, then streaming loop, both on the same pool), so file
@@ -200,7 +232,13 @@ falsification it does not support.
The 6.3% is per POOL teardown, and a pool disposes 21 isolates. Treating
those disposals as independent gives `1-(1-h)^21 = 0.063`, i.e. **h = 0.31%**
-— a factor of 20.5, and for a pool of 21 that is the only shape the answer can
+— a factor of **20.4** (6.3267 / 0.3107; the printed figures give 20.3). The
+fifth digit on the MLE is why h shows 0.3107 and not 0.3108: recomputing from
+a 4-digit 6.327 gives the latter. It changes nothing above -- 6.3267/0.3108 is
+20.36 and still rounds to 20.4 -- but this is the paragraph about a
+mis-rounded conversion factor, so the operand that actually reproduces the
+printed one is the one to give. And
+for a pool of 21 that is the only shape the answer can
take: at small h the pool rate is about 21h, so the ratio can approach 21 and
never exceed it. Any conversion factor larger than the pool size is arithmetic
that went wrong, which is how a bad conversion factor quoted here in an
@@ -221,8 +259,16 @@ either way, which is why it is stated rather than hedged away: redo it with
the real-ingest IDLE hazard instead — 0.225% per pool over 21 isolates is
h = 1.07e-4, and 36 terminated isolates over 10 runs gives **0.96** — against
0.33, both unremarkable. Nothing here rests on the exact h. (An earlier
-revision said 0.95; the stated inputs give 0.962, and every other figure in
-this file reproduces to the digit.)
+revision said 0.95. That was not an arithmetic slip -- 0.95 is what the
+withdrawn 0.28% idle rate gives (0.953, which the file rounded to 0.95) -- it
+moved because the rate
+under it did.) Do not read that as "and
+everything else is exact" — an earlier revision of this parenthetical said so
+and was wrong in the same breath: the conversion factor earlier in this same
+section read 20.5 where its own inputs give 20.4. Ratios here are quoted from
+unrounded
+inputs, so recomputing from the ROUNDED figures printed beside them can differ
+in the last digit; where that changes the rounding, the operands are given.
How many addon-loaded isolates a run terminates is not a guess: `isolate`
defaults to `true`, `core-ingestion` ships no vitest config to change it, and
diff --git a/ix-cli/src/cli/__tests__/parse-pool.test.ts b/ix-cli/src/cli/__tests__/parse-pool.test.ts
index 53ed48fa..37fafdb2 100644
--- a/ix-cli/src/cli/__tests__/parse-pool.test.ts
+++ b/ix-cli/src/cli/__tests__/parse-pool.test.ts
@@ -114,12 +114,19 @@ describe("ParsePool", () => {
} catch (err) {
// EEXIST is the expected answer: another thread holds the claim.
// Anything else means THIS thread failed to claim for an unrelated
- // reason, and if it was the first thread the next one claims
- // successfully and the run looks entirely normal -- one arming, one
- // respawn, green. A previous revision rethrew here and claimed that
- // surfaced the problem; it does not, it just moves which thread
- // faults. So record it instead, and let the test assert the absence
- // of this file. Best-effort: if this write fails too there is
+ // reason, and the two cases differ:
+ //
+ // the FIRST thread fails -- at concurrency 1 it is the only worker,
+ // so isFaulter stays false, nothing ever throws, nothing dies
+ // and nothing respawns. The run is NOT green; it fails in
+ // waitUntil, which reads this file to say so.
+ // a REPLACEMENT fails -- the fault already happened, so the test
+ // reaches its assertions, and the .failed check below is what
+ // catches it.
+ //
+ // Recorded rather than rethrown for both. A previous revision rethrew
+ // and claimed that surfaced the problem; it does not -- it only moves
+ // which thread faults. Best-effort: if this write fails too there is
// nothing left to say with.
if (err.code !== 'EEXIST') {
try {
@@ -228,9 +235,16 @@ describe("ParsePool", () => {
// delivered before the two parses below went out. The test then failed on
// `b2.ts` coming back null, which looks exactly like the bug it guards.
//
- // `workerDeaths()` is the pool's own signal that `onError` ran to
- // completion, so this waits on the state the test actually depends on and
- // is done as soon as it holds.
+ // `workerDeaths()` is the pool's own signal that `onError` has REACTED to
+ // a death -- it advances before `spawnWorker()` and `drain()`, so it means
+ // begun, not finished. That is enough here, and not because of the poll
+ // interval: `waitUntil` evaluates its condition once SYNCHRONOUSLY before
+ // any timer, so a 5ms tick guarantees nothing. What guarantees it is that
+ // this test body is async and so cannot be running inside `onError` --
+ // the handler has always returned before any line here executes. The
+ // distinction matters to anyone copying the `workerDeaths() > before`
+ // pattern into a synchronous callback, which the accessor's own doc
+ // warns against.
// `> 0` is only correct because this is the FIRST death of the run. The
// counter is monotonic and never resets, so a second wait written this
// way returns immediately -- a silent no-op, which is the same class of
@@ -311,12 +325,41 @@ describe("ParsePool", () => {
// A worker that dies deterministically on construction burns through the
// cap. Draining only the queue that existed at that instant left every
// LATER parse waiting on a `drain()` that is a no-op with no idle workers.
- const pool = new ParsePool(worker("dead", BORN_DEAD), 1);
+ // Named, because the death count below is derived from it as well as from
+ // the cap -- see there.
+ const concurrency = 1;
+ const pool = new ParsePool(worker("dead", BORN_DEAD), concurrency);
pool.init();
- // Enough calls to outlast the cap, then more after it.
+ // Enough calls to outlast the cap, DERIVED from it. A hard-coded depth
+ // makes the derivation below one-directional: lowering `MAX_RESPAWNS`
+ // still works, but raising it past that depth means the queue drains
+ // before the pool reaches the latch, and the death assertion then fails
+ // with a message accusing the counter -- which is the exact failure the
+ // derivation exists to prevent. `MAX_RESPAWNS` is documented as tunable,
+ // so that is a reachable edit, not a hypothetical one.
+ const postLatch = 3; // the parses issued below, after the pool is dead
+ // Headroom, so the queue is still non-empty when `dead` latches. Unrelated
+ // to `postLatch` above; they are equal by coincidence, and unifying them
+ // would invent a coupling that does not exist.
+ //
+ // This is the constant that makes this test exercise the branch it is
+ // named for, and it is worth knowing that no other assertion here
+ // protects it: both of the ones below hold at `headroom = 0` too, because
+ // then every queued task is consumed by a death and none is stranded.
+ // Mutation-checked -- deleting the strand-and-resolve body from the cap
+ // branch in `parse-pool.ts` SURVIVES at 0 and is killed at 3, where the
+ // three stranded parses never settle and this hangs to the timeout. So
+ // trimming it silently turns a queue-stranding test into one that only
+ // covers in-flight losses.
+ const headroom = 3;
+ const queued = ParsePool.MAX_RESPAWNS + concurrency + headroom;
+ expect(
+ headroom,
+ "headroom is this test's coverage of the stranded-queue path, not slack",
+ ).toBeGreaterThan(0);
const first = await Promise.all(
- Array.from({ length: 20 }, (_, i) => pool.parse(`f${i}.ts`, "x")),
+ Array.from({ length: queued }, (_, i) => pool.parse(`f${i}.ts`, "x")),
);
expect(first.every((r) => r === null)).toBe(true);
@@ -326,8 +369,51 @@ describe("ParsePool", () => {
Promise.all([pool.parse("l1.ts", "x"), pool.parse("l2.ts", "x")]),
).resolves.toEqual([null, null]);
- // And every one of them is counted, so the stitch gate sees the loss.
- expect(pool.crashedTasks()).toBeGreaterThanOrEqual(23);
+ // And every one of them is counted, so the stitch gate sees the loss: the
+ // whole queued batch plus every parse issued after the latch. EXACT, not
+ // a floor -- this was the last loose assertion in a test tightened
+ // everywhere else, and a floor cannot see an over-count. A regression
+ // that counted the stranded queue twice (the `else if` branch's
+ // `crashed += stranded` plus `parse()`'s own `if (this.dead)`) raises the
+ // number and slides under a `>=`.
+ expect(pool.crashedTasks()).toBe(queued + postLatch);
+
+ // The death that hits the cap still counts. This is the only place that
+ // pins it: every other use of `workerDeaths()` watches the FIRST death of
+ // a healthy pool, where a counter incremented inside the respawn branch
+ // and one incremented outside it both read 1, so neither placement is
+ // distinguishable there. Here they are not equal -- `MAX_RESPAWNS` is 16,
+ // so the pool takes `MAX_RESPAWNS + concurrency` deaths: every worker it
+ // ever starts dies, and it starts `concurrency` up front plus one per
+ // respawn until the budget is gone. The last `concurrency` of them fall
+ // outside the branch -- one only when the pool is size 1, which is what
+ // it is here. Derived from BOTH constants, because at concurrency N the
+ // initial N-1 extra workers also die before `workers.length === 0` can
+ // latch `dead` -- so a bare `MAX_RESPAWNS + 1` silently means "and the
+ // pool is size 1", and raising the size here would fail this assertion
+ // with a message accusing the death counter.
+ //
+ // Asserted EXACTLY, and DERIVED from the constant rather than restated.
+ // A loose `>` form pins the placement only by accident of the cap's
+ // value: an increment moved back inside the branch yields exactly
+ // `MAX_RESPAWNS`, so `> MAX_RESPAWNS` happens to catch it, but any
+ // "more than roughly the cap" shape stops discriminating the moment
+ // someone reaches for a rounder number. And a hard-coded 17 fails a cap
+ // change with a message about the counter, where the tempting repair is
+ // to loosen the assertion into one that no longer catches the bug.
+ // `MAX_RESPAWNS` is public for exactly this, the way
+ // `SHUTDOWN_GRACE_MS` already is for the teardown-bound test below.
+ //
+ // Without this the increment can be tidied back into the branch with the
+ // suite green, and the `const before = ...` / `> before` wait that
+ // `workerDeaths()`'s own doc prescribes then hangs forever past the cap.
+ expect(
+ pool.workerDeaths(),
+ "expected MAX_RESPAWNS + concurrency deaths: every worker the pool " +
+ "starts dies. The shortfall is the deaths PAST the cap -- the ones " +
+ "that exhaust the budget are still counted either way, so a count of " +
+ "exactly MAX_RESPAWNS means the post-cap deaths stopped being counted",
+ ).toBe(ParsePool.MAX_RESPAWNS + concurrency);
await pool.destroy();
});
diff --git a/ix-cli/src/cli/commands/parse-pool.ts b/ix-cli/src/cli/commands/parse-pool.ts
index 8676be5b..9881cb2c 100644
--- a/ix-cli/src/cli/commands/parse-pool.ts
+++ b/ix-cli/src/cli/commands/parse-pool.ts
@@ -195,8 +195,8 @@ export class ParsePool {
* dispatched, and long before `index.ts`'s own body or its top-level
* `await`s run. Note which end that pins: the addon-free window CLOSES when
* those static imports evaluate, not when evaluation finishes. A worker
- * suspended at one of those awaits already holds all twelve, and is not
- * safe to terminate.
+ * suspended at one of those awaits already holds every one of them, and is
+ * not safe to terminate.
*
* Not every grammar: most go through null-returning helpers and can be
* absent, but the core and the statically imported ones are always there,
@@ -447,8 +447,12 @@ export class ParsePool {
* Worker deaths this run has reacted to. Monotonic.
*
* Deaths, not replacements: past `MAX_RESPAWNS` the pool stops replacing but
- * still reacts -- splicing `idle`, latching `dead`, draining the queue -- and
- * a caller watching for "did the pool notice a worker die" needs those too.
+ * still reacts -- it has spliced `workers` before the branch is reached, and
+ * `idle` too if the worker was idle (one that died mid-task lives in
+ * `active`, so there is nothing to take out of the free list -- which is the
+ * case the cap test exercises) -- and a caller watching for "did the pool notice a worker die"
+ * needs those too. (What the branch itself does past the cap depends on
+ * whether any worker survives; `onError` spells that out.)
* An earlier revision counted replacements and sat inside the cap branch,
* which silently stopped advancing at exactly the point a caller most wants
* to know.
@@ -462,9 +466,19 @@ export class ParsePool {
*
* This one is a LEVEL. `onError` increments it in the same synchronous
* handler that does the splicing, so once it has advanced the pool has
- * finished reacting to that death -- including one that faulted with no task
- * in flight, which `crashedTasks()` deliberately does not count because no
- * file was lost. That combination is otherwise unobservable from outside,
+ * BEGUN reacting to that death -- and, since the handler runs to completion
+ * before any asynchronous observer gets the loop back, has finished by the
+ * time anyone polling can read it. The distinction matters only to a future
+ * caller reading this from inside a synchronous path. The increment now runs
+ * before everything the handler does afterwards: on the capped path before
+ * `dead` is latched and before the queue is stranded and resolved, and on
+ * the healthy path before `spawnWorker()` and `drain()`. So such a caller
+ * could see it advanced with `idle` still empty, no replacement yet, and
+ * the queue not yet moving.
+ *
+ * What it observes that nothing else does is a death with no task in
+ * flight, which `crashedTasks()` deliberately does not count because no
+ * file was lost. That combination is otherwise invisible from outside,
* which is what this exists for.
*
* Test observability, and only that today -- nothing in `ingest.ts` reads
@@ -478,6 +492,20 @@ export class ParsePool {
* test observing that first death. Anything later wants
* `const before = pool.workerDeaths()` and then `> before`, or it is a
* poll that returns immediately and waits for nothing.
+ *
+ * Two things stop it moving, and a `> before` wait across either never
+ * completes -- the same hang this counter was moved out of the cap branch
+ * to avoid, one step further along:
+ *
+ * teardown `onError` returns at its `destroyed` guard, so no death is
+ * counted once `destroy()` has begun.
+ * the latch past `MAX_RESPAWNS` with no worker left, `dead` is set and
+ * nothing is ever spawned again, so no further death can
+ * occur. This one bites while the process is still running
+ * normally, which makes it the easier of the two to miss.
+ *
+ * The teardown caveat is on the private `respawns` field too, which a
+ * caller reading this accessor would not see.
*/
workerDeaths(): number {
return this.deaths;
@@ -508,7 +536,10 @@ export class ParsePool {
* `MAX_RESPAWNS` -- so 0 means the full budget is available and 16 means it
* is exhausted, which is the opposite of how "budget" usually reads.
* `onResult` clears it on any success, so it is not a tally either: read
- * `deaths` for "how many workers died this run?".
+ * `deaths` for "how many deaths did the pool REACT to?" -- which is not the
+ * same as "how many workers died": `onError` returns early once `destroy()`
+ * has begun, so the ordinary end-of-run exit of every surviving worker is
+ * uncounted, and a clean run ends at 0.
*/
private respawns = 0;
@@ -523,8 +554,16 @@ export class ParsePool {
*/
private dead = false;
- /** Generous enough for real flakiness, small enough to stop a spawn loop. */
- private static readonly MAX_RESPAWNS = 16;
+ /**
+ * Generous enough for real flakiness, small enough to stop a spawn loop.
+ *
+ * Public for the same reason `SHUTDOWN_GRACE_MS` is: the test that pins the
+ * capped death derives its expectation from this rather than restating it.
+ * A hard-coded 17 there fails on a cap change with a message about the
+ * counter, and the tempting repair is to loosen the assertion into
+ * something that no longer catches the bug.
+ */
+ static readonly MAX_RESPAWNS = 16;
private onError(w: Worker, _err: Error): void {
// Not during shutdown. `destroy()` ends every worker on purpose, and
@@ -571,12 +610,37 @@ export class ParsePool {
const idleIdx = this.idle.indexOf(w);
if (idleIdx !== -1) this.idle.splice(idleIdx, 1);
- // Before the cap branch, because a capped death still reacts fully --
- // it splices `idle`, latches `dead` and drains the queue -- and a signal
- // that means "the pool has finished reacting" has to advance for those
- // too. Inside the branch it counted replacements instead, so past the cap
- // it stopped moving and the `> before` wait below would hang on exactly
- // the deaths a caller most wants to observe.
+ // Before the cap branch, because a death past the cap still reacts -- it
+ // has already spliced `workers` above, and `idle` too if it was idle (a
+ // worker that died mid-task is in `active`, so there is nothing to splice
+ // from the free list) -- and a signal meaning
+ // "the pool reacted to a death" has to advance for those too. Inside the
+ // branch it counted replacements instead, so past the cap it stopped
+ // moving, and the baseline wait described on `workerDeaths()` (~140 lines
+ // above) would hang on exactly the deaths a caller most wants to see.
+ //
+ // What the cap branch itself does -- the `if/else if` immediately below --
+ // depends on whether any worker is left. (Past the cap, that is. While the
+ // budget lasts the pool simply respawns and never latches `dead`.) With
+ // none, the `else if` latches `dead`, strands the queue and resolves it
+ // as crashed, then returns -- so that path never reaches `drain()`. With
+ // others still alive, NEITHER branch body runs and control falls straight
+ // through to `drain()`. `ingest.ts` builds the pool with
+ // `Math.max(1, os.cpus().length - 1)` and `respawns` is a pool-wide budget
+ // that any success resets, so on an ordinary machine the fall-through is
+ // the usual case -- do not read the cap as implying the pool is finished.
+ //
+ // The floor in that expression is there because 1 is reachable, and at
+ // concurrency 1 this inverts: the first death PAST the cap is also the last
+ // worker, so `workers.length === 0` always holds and the pool always
+ // latches `dead`. (Not the death that exhausts the budget -- that one
+ // still takes the respawn branch and spawns a replacement. The two are
+ // one apart, and this file is where that distinction has to stay
+ // straight.) Above concurrency 1 it does not invert. Which case a given machine falls
+ // into depends on its core count, and this comment deliberately does not
+ // say -- an earlier revision guessed at CI's and contradicted the machine
+ // sizes in `docs/parse-pool-teardown.md`, which is the file that owns
+ // them.
this.deaths++;
if (this.respawns < ParsePool.MAX_RESPAWNS) {