salvage: uncommitted work from /home/jwoltje/distrobox-homes/mosaic-dev/src/stack-p3-t5 (disk cleanup #824, 2026-11-06)
This commit is contained in:
1 parent
517e1adad3
commit
748eee24ba
2 files changed
+2178
-182
No files matched your search
+1735
-122
File diff suppressed because it is too large.
Load diff
@@ -442,7 +442,7 @@ its stated reason is the same defect class as the span gap that created this ite
|
||||
|
||||
### RED phase result
|
||||
|
||||
Focused matrix, gateway package: **83 failing / 17 passing (100 cases, 6 files)**, and the terminal
|
||||
Focused matrix, gateway package: **83 failing / 40 passing (123 cases, 6 files)**, and the terminal
|
||||
summary carries **no `Errors` row at all**. Typecheck, lint and Prettier clean. Every failure is an
|
||||
assertion that names what it wanted — the matrix output was scanned specifically for `TypeError`,
|
||||
`ReferenceError`, missing-export and module-resolution text, not merely counted. Most of those
|
||||
@@ -632,10 +632,21 @@ What follows is stated plainly because the temptation to round it off is exactly
|
||||
this item documents: **exact script equality plus `exec` is not process-tree cleanup.** It prohibits
|
||||
_injected_ shell content, which is worth having on its own terms. But the launcher the contract
|
||||
_permits_ is multi-process, so a timed-out route can still leave a live process inside a sandbox
|
||||
being torn down. The fixture's timeout control asserts what it actually measures — a single-process
|
||||
`exec node -e` sleeper is killed and writes nothing — and it is named for that property alone. No
|
||||
assertion in this file establishes descendant containment, and the control is not offered as
|
||||
evidence of it.
|
||||
being torn down.
|
||||
|
||||
**Historical, and superseded — recorded because the sequence is the point.** At the time this
|
||||
paragraph was first written, the fixture's timeout control asserted only what it actually measured:
|
||||
a single-process `exec node -e` sleeper was killed and wrote nothing, and the control was named for
|
||||
that property alone. No assertion in the file established descendant containment, and the control
|
||||
was explicitly not offered as evidence of it. **Current disposition:** that gap is closed. The
|
||||
control now runs the real TSX **CLI/launcher** — `tsx --eval`, which loads the same loader and
|
||||
esbuild children as the route without executing the absent packaged `dev:local` route — and
|
||||
containment is asserted rather than assumed. An earlier revision of this sentence, and the control's
|
||||
own name, said "the real TSX route"; the invocation says `--eval`, so the name claimed a subject the
|
||||
call does not exercise and both have been corrected. See
|
||||
_Timeout containment_ below for the mechanism, the ruling that governs it, and the residuals it does
|
||||
not close. The earlier wording is kept because a document that silently overwrites the state it was
|
||||
wrong about teaches nothing about how the error was found.
|
||||
|
||||
One further measurement decides what any containment design may look like, so it is recorded here
|
||||
rather than left for whoever writes that design to rediscover: every process in the TSX tree runs in
|
||||
@@ -644,10 +655,19 @@ the test runner's `pgid` and `sid`, because a spawn inherits both by default. Th
|
||||
sharp — the obvious repair, signalling the negative process-group id, would signal the test runner
|
||||
itself. Group containment is therefore not a matter of sending a different signal to the tree as it
|
||||
exists; it requires the child to be given a group of its own at spawn time before any group-directed
|
||||
signal is safe to send. Which design does that, and whether the resulting emptiness proof is
|
||||
reuse-safe to the reviewer's standard, is under adjudication and deliberately not settled by the
|
||||
author. This section will record the ruling and the residual — including the one no group-based
|
||||
design can close, a descendant that calls `setsid()` for itself and leaves the group.
|
||||
signal is safe to send.
|
||||
|
||||
Which design does that, and whether the resulting emptiness proof is reuse-safe, **was under
|
||||
architecture adjudication and is now settled** — the author did not settle it, which was the point
|
||||
of routing it. The ruling is Design A with the gate set `G1, G2, G3-S (+ subordinate floor), G4, G5,
|
||||
G6, G7, G8`, behind an independent verification gate. Its two most consequential parts are that a
|
||||
negative kill is issued **only immediately after an enumeration that just proved at least one fully
|
||||
identity-verified live member** (G7), and that unproven emptiness **retains** the sandbox rather than
|
||||
removing it (G8). A subsequent ruling on the same gate settled what counts as proof: **ESRCH from
|
||||
`kill(-pgid, 0)`**, not a zero-member scan, with enumeration retained for identity rather than for
|
||||
existence. The mechanism, the accepted residual and its quantitative bound are recorded under
|
||||
_Timeout containment_ below, including the one no group-based design closes: a descendant that calls
|
||||
`setsid()` for itself leaves the group and the session.
|
||||
|
||||
**There is exactly one place in the file where a child process is created**, and that is the
|
||||
mechanism, not tidiness. A control that made its own spawn would leave the route's spawn free to be
|
||||
@@ -712,28 +732,47 @@ the callback happened to throw first. How a proof reads is not a property of the
|
||||
mechanism this whole item rests on is the last place to accept new surface for it.
|
||||
|
||||
A structural assertion guards the shape the argument depends on: the spec asserts against its own
|
||||
source that `node:child_process` is imported exactly once as the named form `{ spawnSync }`, that
|
||||
the `spawnSync` identifier occurs exactly twice (its import and its one call), and that
|
||||
`...process.env` occurs nowhere. That is aimed at the one revert behavioral assertions cannot see,
|
||||
since a behavioral case only ever observes the spawn it makes itself. It is a source-text
|
||||
source that `node:child_process` is named exactly twice, once as the value import `{ spawnSync }`
|
||||
and once as the type import `{ SpawnSyncOptionsWithStringEncoding }`, and matches both import lines
|
||||
literally rather than counting them; that the `spawnSync` identifier occurs exactly three times —
|
||||
its import, one occurrence in the comment above the options object, and its single call site; and
|
||||
that `...process.env` occurs nowhere. That is aimed at the one revert behavioral assertions cannot
|
||||
see, since a behavioral case only ever observes the spawn it makes itself. It is a source-text
|
||||
heuristic and is documented as one: a child created through an indirection it does not name would
|
||||
not redden it. It is stated here as a guard, not as a proof.
|
||||
|
||||
`fixture control: the spawn site delivers exactly the allowlist to a real child` is the only case
|
||||
in the package-route arm that runs a child at RED head, and it measures the environment **from
|
||||
inside the child** rather than from the object handed to `spawnSync`. It spawns twice through that
|
||||
one site: directly, where the observed key set must equal the allowlist exactly and the child's
|
||||
`HOME` must be neither the real home nor an ancestor of it; and through the trusted shell, which is
|
||||
the route's own shape, where every allowlisted name must be present, must still carry the value the
|
||||
builder constructed for that spawn's own sandbox, and every added name must be one of the shell's
|
||||
bookkeeping names. Presence alone was not enough: a shell-mediated child that changed `HOME`,
|
||||
`PATH` or an XDG root would keep every name and stay green. Beyond the key set, it enumerates the
|
||||
directories on the child's observed `PATH` and asserts the reachable executable names **equal** the
|
||||
allowlist, asserts the seven known agent-runtime names are absent, and asserts each symlink resolves
|
||||
to its exact expected binary. It is green by construction and is a **harness control, not
|
||||
coverage** — it asserts nothing about the code under test. Its purpose is to redden if the fixture
|
||||
is widened back toward the ambient environment, including by a new executable appearing on `PATH`
|
||||
that nobody thought to name.
|
||||
`fixture control: the spawn site delivers exactly the allowlist to a real child` measures the
|
||||
environment **from inside the child** rather than from the object handed to `spawnSync`. It spawns
|
||||
twice through that one site: directly, where the observed key set must equal the allowlist exactly
|
||||
and the child's `HOME` must be neither the real home nor an ancestor of it; and through the trusted
|
||||
shell, which is the route's own shape, where every allowlisted name must be present, must still
|
||||
carry the value the builder constructed for that spawn's own sandbox, and every added name must be
|
||||
one of the shell's bookkeeping names. Presence alone was not enough: a shell-mediated child that
|
||||
changed `HOME`, `PATH` or an XDG root would keep every name and stay green. Beyond the key set, it
|
||||
enumerates the directories on the child's observed `PATH` and asserts the reachable executable names
|
||||
**equal** the allowlist, asserts the seven known agent-runtime names are absent, and asserts each
|
||||
symlink resolves to its exact expected binary. It is green by construction and is a **harness
|
||||
control, not coverage** — it asserts nothing about the code under test. Its purpose is to redden if
|
||||
the fixture is widened back toward the ambient environment, including by a new executable appearing
|
||||
on `PATH` that nobody thought to name.
|
||||
|
||||
An earlier version of that paragraph opened by calling this the only case in the package-route arm
|
||||
that runs a child at RED head. It is not, and the uniqueness was doing no work in the argument, so
|
||||
it has been dropped rather than rescoped: the timeout containment control runs a real child at RED
|
||||
head too, and a third environment measurement has since been added beside this one.
|
||||
|
||||
That third measurement is `fixture control: the TSX launcher delivers exactly the allowlist to its
|
||||
loader process`, and it exists because the two arms above prove the _fixture's_ hermeticity through
|
||||
`node` and through the trusted shell, while the route's actual launcher is TSX — a loader that
|
||||
registers module hooks and therefore has both reason and opportunity to add environment of its own.
|
||||
Measured through the real TSX CLI, through the same one spawn site and the same two-command `PATH`,
|
||||
the loader's child receives exactly the ten allowlisted names, each carrying the builder's own value
|
||||
for that run's sandbox, with no added name and **no `NODE_*` variable of any kind** — no
|
||||
`NODE_PATH`, no `NODE_OPTIONS`, no loader control. TSX writes one deprecation warning to stderr and
|
||||
nothing else. That is the result the measurement was built to be able to contradict; it came back
|
||||
clean, which is a finding and not a reassurance, and the case is retained so that a future TSX which
|
||||
does inject a loader control reddens rather than passes silently. Like its siblings it is a harness
|
||||
control and asserts nothing about the code under test.
|
||||
|
||||
`does not leak the parent ambient environment into the child` is the route-arm half, and it is
|
||||
**pending execution until GREEN**. At RED head there is no `dev:local` script, so the manifest
|
||||
@@ -798,40 +837,115 @@ The second is green today and must stay green; it replaced a case that awaited
|
||||
`onModuleInit().catch(() => undefined)` and asserted only an absence, which a total failure
|
||||
satisfied.
|
||||
|
||||
The seventeen passing cases are itemized rather than counted as coverage, because a green that
|
||||
cannot fail for its stated reason is the same defect class as the span gap that created this item:
|
||||
The forty passing cases are itemized rather than counted as coverage, because a green that cannot
|
||||
fail for its stated reason is the same defect class as the span gap that created this item. They
|
||||
divide into two populations that must never be summed as though they measured the same thing:
|
||||
sixteen that make a claim about the code under test, and twenty-four that make a claim about
|
||||
this spec's own harness. The sixteen:
|
||||
|
||||
| Passing case | Why it is green |
|
||||
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| env: config read on import, no policy | legacy regression guard — expected green |
|
||||
| env: planted dotenv loads, no policy | legacy regression guard — expected green |
|
||||
| main: anchored config reaches `detectAndAssertTier` | current-contract regression guard; its import-time-exit premise is superseded and must migrate at GREEN |
|
||||
| local-dev: production `dev` script untouched | regression guard — expected green |
|
||||
| local-dev: no static import of `main.js` | structural, three forms (binding, side-effect, `require`); must stay green |
|
||||
| local-dev: importing starts nothing | structural; green today only because nothing invokes `runLocalDev` |
|
||||
| policy: refuses to serve when unestablished | scaffolding implements this correctly already |
|
||||
| policy: no fallback read when unestablished | scaffolding implements this correctly already |
|
||||
| inventory: retains no raw DSN text | **vacuous today** — the stub returns an empty inventory |
|
||||
| inventory: retains no planted canary | **vacuous today** — same empty inventory |
|
||||
| inventory: writes no planted canary to the console | **vacuous today** — the stub reads no source, so it can log none |
|
||||
| policy: children beneath the state root | **vacuous today** — the stub concatenates the declared root |
|
||||
| policy: unaffected by post-establish input mutation | **vacuous today** — the stub captured strings, it did not clone |
|
||||
| policy: frozen policy survives a source file gaining a DSN | **vacuous today** — the stub re-serves the same object it built |
|
||||
| policy: frozen policy survives the environment gaining a DSN | **vacuous today** — same |
|
||||
| database: sterile local lifecycle migrates, no Postgres seam | positive anchor — green today, must stay green; the one case that fails if GREEN makes "safe" mean "inert" |
|
||||
| local-dev: fixture control — spawn site delivers the allowlist | harness control, not coverage — green by construction; the only case that runs a child at RED head, and the guard on the instrument the other three depend on |
|
||||
| Passing case | Why it is green |
|
||||
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
|
||||
| env: config read on import, no policy | legacy regression guard — expected green |
|
||||
| env: planted dotenv loads, no policy | legacy regression guard — expected green |
|
||||
| main: anchored config reaches `detectAndAssertTier` | current-contract regression guard; its import-time-exit premise is superseded and must migrate at GREEN |
|
||||
| local-dev: production `dev` script untouched | regression guard — expected green |
|
||||
| local-dev: no static import of `main.js` | structural, three forms (binding, side-effect, `require`); must stay green |
|
||||
| local-dev: importing starts nothing | structural; green today only because nothing invokes `runLocalDev` |
|
||||
| policy: refuses to serve when unestablished | scaffolding implements this correctly already |
|
||||
| policy: no fallback read when unestablished | scaffolding implements this correctly already |
|
||||
| inventory: retains no raw DSN text | **vacuous today** — the stub returns an empty inventory |
|
||||
| inventory: retains no planted canary | **vacuous today** — same empty inventory |
|
||||
| inventory: writes no planted canary to the console | **vacuous today** — the stub reads no source, so it can log none |
|
||||
| policy: children beneath the state root | **vacuous today** — the stub concatenates the declared root |
|
||||
| policy: unaffected by post-establish input mutation | **vacuous today** — the stub captured strings, it did not clone |
|
||||
| policy: frozen policy survives a source file gaining a DSN | **vacuous today** — the stub re-serves the same object it built |
|
||||
| policy: frozen policy survives the environment gaining a DSN | **vacuous today** — same |
|
||||
| database: sterile local lifecycle migrates, no Postgres seam | positive anchor — green today, must stay green; the one case that fails if GREEN makes "safe" mean "inert" |
|
||||
|
||||
Seven greens are vacuous until the implementation exists, up from three, because an earlier pass
|
||||
added retention and post-freeze-mutation cases that a stub satisfies trivially. They are evidence
|
||||
of nothing today and are re-checked at GREEN. The count rising is the honest outcome of asserting
|
||||
more about a module that does not exist yet — it is recorded here so it cannot later be read as
|
||||
coverage. Of the ten non-vacuous greens, one is the harness control above — it asserts
|
||||
nothing about the code under test and is never counted as coverage — seven are guards that must
|
||||
stay green (two legacy continuity, the untouched `dev` script, the structural no-static-import,
|
||||
the two unestablished-policy refusals, and the database positive anchor) and two are green for a
|
||||
weaker reason than they read: `local-dev` "starts nothing on import" is green only because nothing yet invokes
|
||||
`runLocalDev`, and the `main.ts` anchoring case guards a current contract whose import-time-exit
|
||||
premise `-02a` inverts, so it must be migrated at GREEN rather than deleted.
|
||||
The other twenty-four greens are **harness self-verification, not coverage of `-02a` at all**.
|
||||
They assert that this file's own containment machinery, identity guards and channel accounting
|
||||
behave as specified — code that lives inside the spec file. Every one of them would still be green
|
||||
if `local-dev.ts` were never written, because none of them touch it:
|
||||
|
||||
| Passing control | What it establishes |
|
||||
| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| ten identity guards (`refuses undefined` … `refuses the verifier process group`) | a negative kill is refused before it is issued, for every unsafe child-identity shape |
|
||||
| nine containment negative controls | G7 and G8 hold: enumeration precedes every signal, an empty group is never signaled, ESRCH forces re-enumeration, a non-ESRCH errno becomes a typed failure, identity pairs update across rounds, the bound failure is typed, and an unproven sandbox is retained with its absolute path named |
|
||||
| two G8 wiring controls | the `'unproven'` flag arrives set from `makeChildSandbox`, and the flip to `'proven-empty'` still follows the proof in source order |
|
||||
| fixture control: the TSX launcher delivers the allowlist | the launcher passes exactly the allowlist, with both output channels consumed byte-for-byte rather than merely matched |
|
||||
| fixture control: timeout SIGKILLs TSX and proves its process group empty | the unmocked group-kill route contains a loader child that outlives SIGKILL to its TSX parent |
|
||||
|
||||
| fixture control: the spawn site delivers the allowlist | green by construction; the guard on the instrument the environment cases depend on. An earlier revision listed this row in the subject table above, while its own cell there called it "harness control, not coverage" — it was counted on the side it explicitly disclaimed |
|
||||
|
||||
Counting those twenty-four as coverage would be precisely the error this section exists to
|
||||
prevent. The passing total grew from seventeen to forty while the module under test was still
|
||||
unimplemented, and every added green is a statement about the instrument rather than about the
|
||||
subject. The failing total did not move — 83 before and after — which is the measurement that says
|
||||
no case changed sides while the instrument was being hardened.
|
||||
|
||||
Two corrections to the paragraph above, both of which were wrong in an earlier revision in the
|
||||
same direction — toward reading better than the evidence supports.
|
||||
|
||||
The first is the split itself. It read seventeen subject to twenty-three harness; it is sixteen to
|
||||
twenty-four. The `local-dev` spawn-site fixture control was tabled among the subject cases while
|
||||
its own cell described it as "harness control, not coverage", so the document contradicted itself
|
||||
within one row and the contradiction inflated the side that flatters the work.
|
||||
|
||||
The second is the word "absent". `apps/gateway/src/local-dev.ts` is not absent and has not been
|
||||
since the RED commit that introduced this spec — it is a tracked forty-three-line stub whose own
|
||||
header says it "establishes nothing correctly and performs no dynamic import". What is absent is
|
||||
the implementation, not the module. The distinction is load-bearing rather than pedantic: an
|
||||
absent module makes a case fail, while a stub can make one pass for a reason that has nothing to
|
||||
do with the contract, which is exactly the vacuous-green population this section itemizes. The
|
||||
rest of the section had it right — every vacuous row already explains itself by what "the stub"
|
||||
does — so the defect was confined to the summary sentence, which is the sentence most likely to be
|
||||
quoted on its own.
|
||||
|
||||
**Every pass/fail total in this section — forty passing, 83 failing — is the measurement taken
|
||||
before the K1/K2/K3/K6 amendment, and has not been retaken.** The amendment added twenty controls
|
||||
to `local-dev.spec.ts`, all of them harness self-verification, which moved the file to sixteen
|
||||
subject claims and forty-four harness controls across sixty runtime cases (fifty-one literal
|
||||
declarations, one of which is an `it.each` expanding to ten). Those sixty are declared counts,
|
||||
obtained by reading the file; they are not results. Whether the twenty new controls pass is a
|
||||
question for the independent gate, and stating a passing total here on the strength of having
|
||||
written the cases would be the same overclaim the section exists to prevent. The subject count did
|
||||
not move, which is the property worth checking: an amendment that hardened the instrument added no
|
||||
claim about the subject.
|
||||
|
||||
**The r3 amendment adds three further controls, and the same property holds.** The file is now
|
||||
**sixteen subject claims and forty-seven harness controls across sixty-three runtime cases**
|
||||
(fifty-four literal declarations, the same single `it.each` expanding to ten). The three additions
|
||||
are `classifies a safe zero/zero process identity as present`, `keeps zero/zero nonmembers out of a
|
||||
complete positive-group enumeration`, and `uses only the validated child pid for every negative
|
||||
group argument` — a parse class, an enumeration outcome, and a signal-argument boundary, all three
|
||||
claims about this spec's own instrument rather than about the code under test.
|
||||
|
||||
The derivation is stated because the number is the kind of thing that gets carried forward rather
|
||||
than recomputed. The r2 bytes were reconstructed from the published r2 patch, the reconstruction
|
||||
was confirmed against that patch's own recorded digest, and the two declaration lists were compared
|
||||
by name: three present now, none removed. That is why the harness figure is forty-seven rather than
|
||||
forty-four held over, and why the subject figure is asserted as unmoved rather than assumed to be.
|
||||
These remain declared counts obtained by reading the file. **No runtime case in this file has been
|
||||
executed by its author, at r2 or at r3.**
|
||||
|
||||
One coincidence is worth disarming explicitly, because it invites a false inference. An independent
|
||||
run reported sixteen failing and forty-four passing cases, and this document declares sixteen
|
||||
subject and forty-four harness. The numbers coincide on different axes and neither corroborates the
|
||||
other; the reported failures were thirteen subject and three harness. Reading agreement into the
|
||||
pair would be reading a coincidence as a measurement. The r3 counts break the coincidence, which is
|
||||
convenient rather than meaningful.
|
||||
|
||||
Seven of those sixteen greens are vacuous until the implementation exists, up from three,
|
||||
because an earlier pass added retention and post-freeze-mutation cases that a stub satisfies
|
||||
trivially. They are evidence of nothing today and are re-checked at GREEN. The count rising is the
|
||||
honest outcome of asserting more about a module that is not implemented yet — it is recorded here
|
||||
so it cannot later be read as coverage. Of the nine non-vacuous greens, seven are guards
|
||||
that must stay green (two legacy continuity, the untouched `dev` script, the structural
|
||||
no-static-import, the two unestablished-policy refusals, and the database positive anchor) and two
|
||||
are green for a weaker reason than they read: `local-dev` "starts nothing on import" is green only
|
||||
because nothing yet invokes `runLocalDev`, and the `main.ts` anchoring case guards a current
|
||||
contract whose import-time-exit premise `-02a` inverts, so it must be migrated at GREEN rather than
|
||||
deleted.
|
||||
|
||||
**Classification is a type obligation, not only a wording one.** Two inventory cases demanded the
|
||||
raw source values `'standalone'` and `'postgres'`, which the value-free classification unions
|
||||
@@ -842,6 +956,275 @@ clean", collapsing the exact distinction the refusal path is built on. The invar
|
||||
`present === false` if and only if `readability === 'absent'` is asserted directly, per state and
|
||||
across all seven rows at once.
|
||||
|
||||
### Timeout containment: what the fixture kills, and what it does not
|
||||
|
||||
Node's `spawnSync` timeout kills exactly one process — the direct child. That is the whole of what
|
||||
the built-in does, and for a single-process child it is sufficient. The required `dev:local` route
|
||||
is not a single process. TSX spawns an esbuild service child and a `node --require .../preflight.cjs
|
||||
--import .../loader.mjs --eval <script>` child, and the second is where the route's own code runs.
|
||||
|
||||
Measured six times out of six under the fixture's exact spawn shape, that loader/eval child
|
||||
**survives** the SIGKILL sent to its TSX parent, is reparented, and completes its work afterward —
|
||||
writing into a sandbox directory the fixture is concurrently removing. The exact `dev:local` script
|
||||
contract prevents _injected_ shell content; it does not close this, because the launcher the
|
||||
contract _permits_ is the one that leaks.
|
||||
|
||||
The remediation is a bounded containment step that runs synchronously after `spawnSync` returns:
|
||||
the child is spawned `detached`, giving it its own process group and its own session; the group is
|
||||
enumerated from `/proc`, signalled by negative PGID, and re-enumerated until proven empty or a
|
||||
bound is reached. Two rules govern it, and both are mechanism rather than description.
|
||||
|
||||
**Kill eligibility (G7): a negative signal may issue only immediately after an enumeration that
|
||||
found at least one fully identity-verified live member** — `(pid, starttime)` recorded, and
|
||||
`pgid === childPid` and `sid === childPid` both satisfied. An enumeration returning zero members
|
||||
goes straight to emptiness confirmation and signals nothing. The rule it replaces is the ordinary
|
||||
one — signal, then check — and the difference is that a negative PGID is not a request addressed to
|
||||
a process the caller has verified exists. Never kill on suspicion.
|
||||
|
||||
**Teardown gate (G8): emptiness must be proven before the sandbox is removed, and unproven
|
||||
emptiness retains it.** Proof is **ESRCH from `kill(-pgid, 0)`**, taken at the initial observation
|
||||
and again after every signal round, and nothing weaker. A zero-member `/proc` enumeration is not
|
||||
proof: the scan is a directory snapshot stitched to per-entry reads, and a fork handoff can straddle
|
||||
it. Measured on this host class — a group whose leader has exited **and been reaped**, with only a
|
||||
later-created grandchild alive in it, reports EXISTS to the kernel while a scan can list no member
|
||||
at all. Enumeration is kept and is not the existence oracle: enumeration answers _who_ is present
|
||||
and whether their identity is anomalous, the kernel call answers _whether anyone is_. Success from
|
||||
the probe means the group exists; **EPERM means it exists and cannot be signalled**; any other errno
|
||||
means unknown. Both are typed refusals that retain the sandbox, because a `catch` that reports
|
||||
emptiness when the answer was unreadable is this item's own defect reintroduced one layer down. An
|
||||
identity anomaly, a non-ESRCH signal errno, an unreadable member identity, or an exhausted round
|
||||
bound each leave the sandbox on disk, name its absolute path in the typed failure, and fail the test
|
||||
loudly. Deleting under a possibly-live survivor would discard both the marker the control depends on
|
||||
and the forensic evidence, and would remove the working directory out from under a process that is
|
||||
still running — provoking exactly the less-contained behaviour the step exists to prevent. A typed,
|
||||
loud failure is the outcome whenever the group will not empty; a silent pass is not reachable.
|
||||
|
||||
**An earlier probe of mine reported the opposite result, and it was wrong.** It enumerated
|
||||
survivors by PPID against the killed parent's pid and found none, which I read as a clean tree.
|
||||
SIGKILLing a parent _reparents_ its children, so the survivors had moved out of the filter's reach;
|
||||
the sweep returned empty because it could no longer see them. Re-probed by matching on sandbox path
|
||||
instead of parentage, the result reversed completely. Parent-scoped observation is not admissible
|
||||
evidence of tree death, and this is the same defect class as a review bounded by directories it
|
||||
never listed.
|
||||
|
||||
#### The containment argument is session identity, not timing
|
||||
|
||||
`detached: true` performs `setsid()`, so the child leads a new session whose id equals its own pid.
|
||||
Every enumerated group member must therefore satisfy both `pgid === childPid` and `sid === childPid`;
|
||||
a member matching the group but not the session is a group/session anomaly and is refused with its
|
||||
own typed failure, **without a kill**. Measured 4/4 on the real TSX route under this exact spawn
|
||||
shape: every group member carried `sid === childPid`, and the verifier was never in the group.
|
||||
|
||||
This bound is structural rather than temporal. Membership in the child's group is reachable only by
|
||||
being the child, by inheriting across `fork`, or by a `setpgid` that Linux refuses across session
|
||||
boundaries with `EPERM` — so no process existing before the spawn can join, **regardless of when it
|
||||
started**. A start-time comparison was the earlier candidate for this job and is strictly weaker: it
|
||||
reasons about when a process began rather than about what it can be a member of.
|
||||
|
||||
A subordinate `SPAWN_BOUNDARY_FLOOR` — the verifier's own start time from `/proc/self/stat` field 22,
|
||||
read once — is retained as a cheap gross-anomaly backstop beneath that guard, not as the containment
|
||||
argument. Its gap between the floor and the actual spawn instant is a **detection window, not a
|
||||
process-age residual**: a process starting inside it is not detectable by the floor, and is not left
|
||||
uncontained either, because session identity excludes it structurally. A tighter per-spawn floor —
|
||||
the maximum start time across `/proc` sampled immediately before each spawn — is available in ticks
|
||||
with no clock conversion and no external executable; it was considered and withdrawn, because it
|
||||
tightens a guard that is not load-bearing at the cost of a full `/proc` sweep before every one of
|
||||
the fixture's spawns.
|
||||
|
||||
Guarding the guard: the pid about to be signalled is validated as a **positive safe integer** before
|
||||
any negative kill, not merely as finite. `-0 === 0`, `process.kill` coerces it, and `kill(0, sig)`
|
||||
signals the caller's own process group — so a finiteness check would have admitted the one value
|
||||
that turns the self-protection guard into the accident it exists to prevent. The same requirement is
|
||||
applied to the parsed verifier PGID before it is compared or used in any signal path.
|
||||
|
||||
#### What this does not contain — stated, not implied away
|
||||
|
||||
- **A descendant that calls `setsid()` for itself leaves the group and the session, and is
|
||||
unreachable by any group kill.** No design considered here closes that. "Process-group
|
||||
containment" is not totality, and the point of writing this paragraph is that closing a
|
||||
containment overclaim by writing a new one would repeat the exact defect this item exists to
|
||||
record.
|
||||
- **No start-time test can distinguish a recycled group's new members from legitimate
|
||||
descendants.** Both postdate the spawn. What bounds that case is the identity-checked enumeration
|
||||
loop, which matches `(pid, starttime)` pairs across kill rounds so that a pid acquired by a
|
||||
different process between rounds is not counted as a survivor — and, above it, the session check,
|
||||
which turns a group recycled into a _different_ session from a mis-kill into a detected refusal.
|
||||
- **Identity checking does not close pid reuse, and the source must not claim it does — this is an
|
||||
accepted operational risk, not a solved problem.** A recycled pid equal to `childPid` whose new
|
||||
owner itself calls `setsid()` presents `pid === pgid === sid === childPid` and is indistinguishable
|
||||
from the real child by identity fields. The check is not atomic with the signal that follows it, so
|
||||
such an impostor arising between them would be **mis-killed**, not merely mis-observed. G7 pins
|
||||
that window to a single enumeration→signal gap by permitting a kill only immediately after an
|
||||
enumeration that just proved at least one fully identity-verified live member, and by issuing **no
|
||||
kill at all** when an enumeration finds zero members — never killing on suspicion of members, only
|
||||
what was just proven present. Post-signal `(pid, starttime)` pair comparison is **detection and
|
||||
reclassification, not a failure path.** A member whose pair no longer matches is classified as
|
||||
newly observed rather than as a surviving one; it stays a verified live member, having passed the
|
||||
same group and session identity checks, and becomes one of the recorded pairs the next eligibility
|
||||
decision is made against. No typed failure fires on a changed pair. An earlier revision of this
|
||||
paragraph said one did, which was a claim about a mechanism the source does not contain. What the
|
||||
comparison actually buys is that a pid acquired by a different process between rounds is never
|
||||
counted as evidence that the original member survived. It does not buy prevention, and detection
|
||||
after the fact is not prevention.
|
||||
|
||||
The bound on the accepted risk, stated so a reader can judge it rather than take it on trust:
|
||||
within that sub-millisecond gap the impostor requires **all** of (a) every just-verified member
|
||||
exiting; (b) the freed number being reallocated, which requires the kernel's cyclic allocator to
|
||||
traverse the remaining pid space — `pid_max` is 4,194,304 on this host class, so even at an absurd
|
||||
10⁶ forks per second a wraparound takes seconds against a sub-millisecond window, a margin of at
|
||||
least 10³; (c) the process landing on exactly `childPid` and calling `setsid()`; and (d) same-uid
|
||||
signalability, which also bounds any blast radius to the invoking user's own processes.
|
||||
Requirement (a) additionally rests on the pgid-pins-pid-number mechanism described in the next
|
||||
bullet, and is kept as stated mechanism rather than host measurement; (b) through (d) carry the
|
||||
bound on their own. This arithmetic bounds **likelihood, in the mis-signal direction only** — how
|
||||
improbable it is that an impostor occupies the number a signal round is about to use. It is not
|
||||
an input to the emptiness proof, which is closed structurally by what ESRCH means and does not
|
||||
depend on any of these numbers; see the signal-zero-candidate bullet below.
|
||||
|
||||
- **An unreaped zombie leader makes the kernel report the group as existing.** `kill(-pgid, 0)`
|
||||
succeeds while a leader has exited and has not yet been waited on, so the ESRCH answer G8 now
|
||||
requires as proof is unavailable for as long as the zombie persists. This is bounded and fails in
|
||||
the safe direction: the sandbox is retained, the round bound is exhausted, and the failure is typed
|
||||
and loud, so the outcome is a refusal to claim emptiness rather than a false claim of it. It is
|
||||
stated rather than engineered around, because the only two ways to remove it are to reap on the
|
||||
containment path — which would mean the verifier taking ownership of a process it did not spawn —
|
||||
or to read a non-ESRCH answer as emptiness, which is the exact defect the gate exists to remove.
|
||||
|
||||
- **The signal-zero candidate is not proven to still name the original child's group.** `spawnSync`
|
||||
returns after the leader exits, and pid reuse in the enumeration-to-signal gap is already accepted
|
||||
above; nothing in the source proves the number passed to `kill(-pgid, 0)` still names the group it
|
||||
named at spawn. What makes this survivable is **structural, and it is not the `pid_max` margin**.
|
||||
ESRCH is returned only when no process is in the group. Any surviving original member is in that
|
||||
group by definition. The kernel therefore cannot answer ESRCH while a member exists, so a false
|
||||
_empty_ is not reachable through reuse at all — a reused group number can only answer EXISTS, and
|
||||
only when the original group is genuinely gone. A wrong candidate can withhold the proof and
|
||||
retain the sandbox; it cannot manufacture one. The proof's failure mode is closed; its
|
||||
availability is not guaranteed, and the design does not claim it is.
|
||||
|
||||
**The arithmetic above carries no weight in this argument, and must not be cited as though it
|
||||
did.** The `pid_max` margin says reuse is unlikely. It says nothing about why reuse is harmless
|
||||
to the proof, which is a consequence of what ESRCH means rather than of how rarely a number comes
|
||||
back around. An earlier revision of this bullet rested the case on the margin, which put a number
|
||||
in the place where the semantics already did the work — the same substitution as counting a
|
||||
harness control as coverage, and it would have degraded silently on any host with a smaller
|
||||
`pid_max` rather than failing.
|
||||
|
||||
**This closes the emptiness proof and nothing else — and "closed" is the right word only here.**
|
||||
The same reuse remains live in the other direction, where it is not benign: a group number that
|
||||
has been reallocated by the time a `SIGKILL` round issues names a stranger's process group, and
|
||||
that kill lands on a third party rather than failing a test. Withholding a proof retains a sandbox
|
||||
and fails loudly; a wrong group kill cannot be walked back.
|
||||
|
||||
That direction is **narrowed and detected, not closed.** Every signal is issued immediately after
|
||||
an enumeration whose members passed group, session and anomaly verification — round 0 from the
|
||||
pre-loop enumeration, each later round from the fresh one taken at the end of its predecessor — so
|
||||
the exposure is reduced to a single enumeration→signal gap per round instead of spanning the
|
||||
loop, and a pid acquired by a different process between rounds is never counted as a surviving
|
||||
member. What that does not do is make the gap atomic. An exact identity impostor arising inside
|
||||
it — a recycled pid equal to `childPid` whose new owner calls `setsid()`, presenting
|
||||
`pid === pgid === sid === childPid` — is indistinguishable from the real child by every field the
|
||||
check reads, and would be mis-killed. That is the accepted operational residual recorded three
|
||||
bullets above, and per-round re-verification does not remove it.
|
||||
|
||||
An earlier revision of this paragraph said the mis-signal risk was "closed by a different
|
||||
mechanism entirely". That was an overclaim, and it contradicted this document's own bullet
|
||||
stating that identity checking does not close pid reuse and that the source must not claim it
|
||||
does. Two adjacent statements in one record, one saying the risk is accepted and one saying it is
|
||||
closed, is worse than either alone: a reader quoting the closure sentence would carry away the
|
||||
opposite of the design's actual position. Only false emptiness is closed, and only structurally,
|
||||
by what ESRCH means. The two mechanisms must be kept apart wherever either is quoted — the
|
||||
structural ESRCH argument protects the proof, per-round re-verification narrows and detects
|
||||
mis-signal, and neither substitutes for the other or for the admitted residual.
|
||||
|
||||
- **Enumeration is coupled to the readability of the whole `/proc` table, not only to the target
|
||||
group, and that coupling is deliberate.** A single genuinely unreadable or unparseable record
|
||||
belonging to an entirely unrelated process makes the whole scan return typed unknown rather than
|
||||
`complete`. This looks disproportionate and is kept anyway: the scan's question is "is any member
|
||||
of this group present", and a record that cannot be read cannot be excluded from membership, so
|
||||
the honest answer is that membership is undetermined. Treating an unreadable stranger as a
|
||||
nonmember would silently convert an unanswered question into a negative answer, which is the
|
||||
precise shape of the defect this whole item exists to remove. The cost is availability — an
|
||||
unrelated permission or grammar surprise anywhere in `/proc` withholds the proof and retains the
|
||||
sandbox — and the design accepts that cost rather than narrowing the scan to records it already
|
||||
believes are irrelevant.
|
||||
|
||||
Two classes are explicitly **not** instances of this coupling, because both are understood rather
|
||||
than merely unread. A kernel thread's `pgid=0, sid=0` record is a valid, completely parsed record
|
||||
that is a nonmember of every strictly positive target group; it is recognized, not tolerated. A
|
||||
process that disappears mid-scan (`ENOENT` from the open, `ESRCH` from a read after a successful
|
||||
open) is benign absence, since a task that is gone is not a member either. Neither withholds
|
||||
`complete`. What withholds it is a record that is present and unreadable, or readable and not
|
||||
understood — and the distinction between "known to be irrelevant" and "not known" is the entire
|
||||
content of this bullet. An earlier revision failed exactly here in the opposite direction: it
|
||||
classified kernel threads as unparseable, which made `complete` unreachable on every Linux host
|
||||
and meant the containment success path could never run at all.
|
||||
|
||||
- **Two mechanisms would close it outright, and both are out of reach here — one on reachability,
|
||||
one on structure.** Recorded as named escalation paths so that a future reader inherits the
|
||||
analysis instead of repeating it. `pidfd_send_signal(fd, SIGKILL, PIDFD_SIGNAL_PROCESS_GROUP)` on
|
||||
kernels ≥ 6.9 signals the group of a pidfd-pinned process and closes the race outright; it is
|
||||
present in this host's headers and is rejected because Node exposes no pidfd bindings, so reaching
|
||||
it needs either a native addon or an external helper executable — both refused classes for this
|
||||
item, and a rejection on **reachability, not absence**. A cgroup v2 kill boundary is rejected on
|
||||
**structure rather than environment**, which is the sharper reason and not the one first proposed:
|
||||
delegation is real on this host class and `cgroup.kill` needs no new executable, but under this
|
||||
design no fixture code runs while `spawnSync` blocks, so the child is already dead when control
|
||||
returns and there is nothing left to migrate. Migration while the child lives would require the
|
||||
asynchronous design, and even there writing a pid into `cgroup.procs` moves only that pid, so
|
||||
anything forked before migration escapes the boundary; the race-free form is
|
||||
`clone3(CLONE_INTO_CGROUP)`, unreachable from Node builtins. The distinction is worth stating in
|
||||
its own words, because the author's first framing was the weaker one: the question was never
|
||||
whether the tool is available, it is whether there is a **moment to use it**. Delegation being real
|
||||
on this host class is recorded deliberately, so that a future reader who checks the environment,
|
||||
finds the mechanism present, and concludes the rejection is stale, reads this sentence instead.
|
||||
"Unavailable in this environment" and "inapplicable to this design" send that reader down
|
||||
different paths, and this one is the second.
|
||||
- **One supporting mechanism is unverified.** The soundness of a freshly created group at spawn
|
||||
time rests on the kernel not allocating a PID number while it persists as a live process's PGID
|
||||
or SID (struct-pid refcounting). That is stated here as mechanism, not as measurement: forcing
|
||||
PID-space wraparound to observe it is not a bounded experiment, and it was not run. Nothing in
|
||||
the design depends on it.
|
||||
- **The esbuild observation is bounded to the runs performed.** In these runs the esbuild service
|
||||
child did not survive the parent kill and its count did not accumulate. That is not a claim it
|
||||
can never survive, and nothing in the design assumes it exits on its own.
|
||||
- **The installed type declarations do not describe the runtime.** `detached` is declared on
|
||||
`SpawnOptions` and not on `SpawnSyncOptions`, while Node honours it on `spawnSync` regardless —
|
||||
measured on this host as `pid == pgid == sid`. The gap is reconciled explicitly and visibly at the
|
||||
call site, because the earlier reconciliation was an annotated local variable that suppressed
|
||||
excess-property checking silently: the call read as type-checked when it was not, and the file's
|
||||
own review measure is a count of type escapes, which such a construct does not appear in. A
|
||||
construct that defeats the metric is worse than the escape it avoids.
|
||||
|
||||
#### The same errno name means different things at different layers
|
||||
|
||||
Two syscalls in this design return overlapping errno names while answering different questions. The
|
||||
names are not interchangeable, and collapsing them is a live failure mode rather than a theoretical
|
||||
one — it has already happened once, in a ruling.
|
||||
|
||||
| Operation | Benign absence | Exists | Unknown / refusal |
|
||||
| ----------------------- | ----------------- | -------------------------------------------- | -------------------------------------- |
|
||||
| read `/proc/<pid>/stat` | `ENOENT`, `ESRCH` | n/a — a successful parse is presence | every other errno, every parse failure |
|
||||
| `kill(-pgid, 0)` | `ESRCH` **only** | success = signalable; `EPERM` = unsignalable | `ENOENT` and every other errno |
|
||||
|
||||
The asymmetry is the point. At the stat layer both names mean the task is gone: `ENOENT` is what an
|
||||
open returns for a task already reaped, and `ESRCH` is what a **read** returns when the task is
|
||||
reaped after the open succeeded but before the read — `readFileSync` performs both operations in
|
||||
one call, so a single call can surface either. At the kill layer `ESRCH` carries the entire
|
||||
emptiness proof and `ENOENT` is not an expected answer at all, so treating it as absence would be
|
||||
inventing a proof from an unexplained result.
|
||||
|
||||
The earlier ruling on this point required `ENOENT` alone as benign stat absence and classified stat
|
||||
`ESRCH` as unknown. It was **superseded by its own author** after a deterministic measurement of the
|
||||
open/read race — open an fd on `/proc/<pid>/stat`, kill and reap the task, then read the already-open
|
||||
fd, which yields `ESRCH` where a fresh open yields `ENOENT`. The candidate was already correct at
|
||||
that layer and was returned unchanged with the contradiction flagged rather than silently normalized
|
||||
to match the ruling. That refusal is what surfaced the error. Had the code been aligned to the
|
||||
ruling instead, the `ENOENT`-only rule would have shipped and left an intermittent version of the
|
||||
kernel-thread poisoning behind it: in a scan of roughly a thousand pids, a process exiting mid-scan
|
||||
is the ordinary case rather than the edge, so the bug would have passed most runs and failed
|
||||
occasionally — the harder kind to find, and the kind that erodes trust in the suite rather than in
|
||||
the defect.
|
||||
|
||||
### Scope discipline
|
||||
|
||||
`-02a` neither breaks production-like entrypoints nor authorizes their local use. They resolve
|
||||
|
||||
Reference in new issue
Block a user