test(infra): attribute and gate the ECONNREFUSED network-escape class repo-wide

[yinlianghui]

Fixes#6640

Verified on 1836f41f8. Three files: vitest.setup.network-escape-guard.ts (new), scripts/__tests__/network-escape-ledger.test.ts (new, the shrink-only pin), and one import line in vitest.setup.base.ts.

Attribution first, per the triage ruling

A sweep of every project — dom (all 8 shards), dom-heavy, unit, apps/console, each VERDICT command-exit 0 from the shared verify lock — attributes the class to 21 test files across 9 packages: app-shell (8), plugin-detail (4), plugin-kanban (3), and one each in plugin-view, plugin-calendar, plugin-grid, plugin-gantt, plugin-charts, examples/schema-catalog. They reach /api/v1/security/explain, /api/v1/meta/_drafts, /api/v1/meta/object, /api/v1/meta/object/task, /api/v1/ai/conversations and /api/v1/automation/_status. The full table with per-file rows is on the card.

This selects possibility 1, and falsifies possibility 2. Not one of the 21 is a file the four closed siblings fixed. Checked by symptom rather than by issue number: all eight landed doubles are still on main and still working (stubGlobal + unstubAllGlobals present, none appears in the sweep) — DatasetReportRenderer (#5225), DetailView + DetailView.invalidation (#3339), ObjectChart.compareTo (#4106), FlowCanvas + the metadata-admin inspectors (#4688), plus the DatasetWidget / DashboardGridLayout.datasetPath / calendar propsContract siblings. No fix was reverted, so the closed cards are not lying about main and no annotation is owed them.

The sharpest illustration of what is actually broken sits in one directory: #4688 stubbed ActionDefaultInspector, ConditionBuilder, HookDefaultInspector, PageBlockInspector and ViewVariantInspector, while FlowNodeInspector.specKeys and .inactiveRetained — same directory, same mechanism — were simply not in its enumeration. Each fix closed the files someone had listed by hand, and the list is hand-made. That is why a fifth per-package fix is the wrong shape.

Mechanism

happy-dom's default document URL is http://localhost:3000; nothing in this repo configures it. So a DOM-env test rendering a component that reaches one of the roughly 18 apiFetch ?? fetch / globalThis.fetch fallbacks in product code resolves a relative /api/v1/... against a real TCP socket.

Two findings that shaped the instrument

1. The stacks are unattributable, and that — not the noise — is the defect. They arrive as

Error: connect ECONNREFUSED 127.0.0.1:3000
at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1637:16)

with no stderr | FILE > TESTNAME header and no user stack frame, because it is an unhandled socket error raised below the layer Vitest captures per test. Vitest cannot tie it to a file. That is why the class survived four fixes: the output never said who was left.

2. A throwing fetch would never fire. Every escaping call site is const doFetch = apiFetch ?? fetch inside try { ... } catch { } — best-effort by construction, which is exactly why the suite is green while escaping. A rejection raised from inside fetch lands in that same catch and is swallowed, leaving the test green and the guard silent. So the escape is recorded at the call and asserted in afterEach, where no product catch can reach it. Measured: the ablation below fails only because of this choice.

What it does and does not do

It silences nothing — the real request still goes out and the real ECONNREFUSED still prints, because those stacks are the evidence that a test reached for a socket. Beside each one the guard now writes an attributed line naming the owning file, so a bare stack in a truncated log is no longer an unowned red. It skips and quarantines nothing: every test still runs and asserts exactly what it asserted before. KNOWN_ESCAPES is the 21 measured files and may only shrink — a new escape in any other file is red on its first run, which is the structural close of the class.

Written straight to process stderr rather than through console: under happy-dom globalThis.console is the window's virtual console and never reaches the terminal (measured — the line vanished entirely), and process stderr is also the only stream that puts the attribution beside the stack it explains.

Verification

Ablation, on the committed tree: delete one entry from KNOWN_ESCAPES, confirm the mutation landed by blob hash, run, restore, confirm the restored blob is byte-identical to the HEAD blob with git diff HEAD empty. Mutated: Test Files 1 failed, the guard naming file, test and URL.

Green with the guard: the 21 known files (690 tests, 135 attributed lines, 0 guard failures) · unit (808 files, 12572 passed, 9 pre-existing skips) · dom-heavy (34 files, 332 tests) · dom shard 5/16 (89 files, 1516 tests) · dom shard 3/8, the escape-heaviest (179 files, 2275 tests).

type-check:vitest-setup earned its keep twice. It ships no @types/node by design, so the first draft's node:fs / node:path / process / import.meta.dirname uses were five real errors; the guard now declares the one structural type it needs. And re-running the suite after that rewrite caught the second defect: Vite statically rewrites the new URL('.', import.meta.url) pattern at transform time, so the value reaching the run was /@fs/... rather than a real path — every path relative-isation missed and all 21 known escapes failed at once. Derived by string surgery on import.meta.url instead.

Patch round (review follow-up)

The ledger's docstring said it "may only shrink" and nothing made that true — an author meeting the guard's red could go green by adding a line, which is precisely how a burn-down ledger decays into the permanent quarantine it is not supposed to be. KNOWN_ESCAPES is now exported (that export is its only behaviour change) and pinned by scripts/__tests__/network-escape-ledger.test.ts, which reconciles the live set against a pinned literal of the 21 measured paths in both directions:

• a name in the ledger but not the pin ⇒ the ledger grew. Red.
• a name in the pin but not the ledger ⇒ a fix landed and the pin is stale. Red until the pin is updated too, so shrinking is a deliberate two-line change rather than a silent one.

Plus an anchored non-vacuity floor, because both reconciles pass vacuously on two empty collections: the pin must be non-empty, the imported set must be non-empty, and every pinned path must still resolve on disk (so a rename cannot leave the two sides agreeing about files that no longer exist).

Proved by ablation on disk, each leg confirmed by blob hash and restored to a byte-identical blob with git diff HEAD empty:

• add a bogus name to KNOWN_ESCAPES ⇒ Tests 1 failed | 2 passed, "The network-escape ledger GREW, and it may only shrink."
• delete a real name without touching the pin ⇒ Tests 1 failed | 2 passed, "A pinned escape is gone from KNOWN_ESCAPES — which is good news, banked wrong."

Gates on 1836f41f8, each quoting its own verdict line: type-check:vitest-setup exit 0 · type-check:scripts exit 0 (the new import edge from scripts/__tests__ to the root setup file is clean) · check:control-bytes "OK (scanned 5998 tracked text file(s); skipped 85 binary)" · eslint on both changed files exit 0, 0 errors · network-escape-ledger.test.ts + vitest-invocation-guard.test.ts "Test Files 2 passed (2) / Tests 33 passed (33)" · the 21 known files again "Test Files 21 passed (21) / Tests 690 passed (690)", 135 attributed lines, 0 guard failures · check-changeset-presence "No source or published contract of a released package changed in this range, so no changeset is owed."

Declared narrowing

The remaining dom shards were swept for attribution but not re-run against the final commit; CI runs the full farm regardless. Two runs were cut by the container's 10-minute foreground cap and recorded NOT MEASURED, then re-run split rather than quoted.

Follow-up, deliberately not in this PR

The 21 known escapes are recorded, not excused. Each is fixed by serving its probe from a double — see packages/plugin-report/src/__tests__/DatasetReportRenderer.test.tsx for the shape — and deleting its line from KNOWN_ESCAPESand from the pin. That is per-file work across 9 packages and belongs in its own cards, not riding on the instrument that found them.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BGMDbrVa8JjZcCQ7DWYH1b

[yinlianghui]

Fixes#6640

Verified on 1836f41f8. Three files: vitest.setup.network-escape-guard.ts (new), scripts/__tests__/network-escape-ledger.test.ts (new, the shrink-only pin), and one import line in vitest.setup.base.ts.

Attribution first, per the triage ruling

A sweep of every project — dom (all 8 shards), dom-heavy, unit, apps/console, each VERDICT command-exit 0 from the shared verify lock — attributes the class to 21 test files across 9 packages: app-shell (8), plugin-detail (4), plugin-kanban (3), and one each in plugin-view, plugin-calendar, plugin-grid, plugin-gantt, plugin-charts, examples/schema-catalog. They reach /api/v1/security/explain, /api/v1/meta/_drafts, /api/v1/meta/object, /api/v1/meta/object/task, /api/v1/ai/conversations and /api/v1/automation/_status. The full table with per-file rows is on the card.

This selects possibility 1, and falsifies possibility 2. Not one of the 21 is a file the four closed siblings fixed. Checked by symptom rather than by issue number: all eight landed doubles are still on main and still working (stubGlobal + unstubAllGlobals present, none appears in the sweep) — DatasetReportRenderer (#5225), DetailView + DetailView.invalidation (#3339), ObjectChart.compareTo (#4106), FlowCanvas + the metadata-admin inspectors (#4688), plus the DatasetWidget / DashboardGridLayout.datasetPath / calendar propsContract siblings. No fix was reverted, so the closed cards are not lying about main and no annotation is owed them.

The sharpest illustration of what is actually broken sits in one directory: #4688 stubbed ActionDefaultInspector, ConditionBuilder, HookDefaultInspector, PageBlockInspector and ViewVariantInspector, while FlowNodeInspector.specKeys and .inactiveRetained — same directory, same mechanism — were simply not in its enumeration. Each fix closed the files someone had listed by hand, and the list is hand-made. That is why a fifth per-package fix is the wrong shape.

Mechanism

happy-dom's default document URL is http://localhost:3000; nothing in this repo configures it. So a DOM-env test rendering a component that reaches one of the roughly 18 apiFetch ?? fetch / globalThis.fetch fallbacks in product code resolves a relative /api/v1/... against a real TCP socket.

Two findings that shaped the instrument

1. The stacks are unattributable, and that — not the noise — is the defect. They arrive as

Error: connect ECONNREFUSED 127.0.0.1:3000
at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1637:16)

with no stderr | FILE > TESTNAME header and no user stack frame, because it is an unhandled socket error raised below the layer Vitest captures per test. Vitest cannot tie it to a file. That is why the class survived four fixes: the output never said who was left.

2. A throwing fetch would never fire. Every escaping call site is const doFetch = apiFetch ?? fetch inside try { ... } catch { } — best-effort by construction, which is exactly why the suite is green while escaping. A rejection raised from inside fetch lands in that same catch and is swallowed, leaving the test green and the guard silent. So the escape is recorded at the call and asserted in afterEach, where no product catch can reach it. Measured: the ablation below fails only because of this choice.

What it does and does not do

It silences nothing — the real request still goes out and the real ECONNREFUSED still prints, because those stacks are the evidence that a test reached for a socket. Beside each one the guard now writes an attributed line naming the owning file, so a bare stack in a truncated log is no longer an unowned red. It skips and quarantines nothing: every test still runs and asserts exactly what it asserted before. KNOWN_ESCAPES is the 21 measured files and may only shrink — a new escape in any other file is red on its first run, which is the structural close of the class.

Written straight to process stderr rather than through console: under happy-dom globalThis.console is the window's virtual console and never reaches the terminal (measured — the line vanished entirely), and process stderr is also the only stream that puts the attribution beside the stack it explains.

Verification

Ablation, on the committed tree: delete one entry from KNOWN_ESCAPES, confirm the mutation landed by blob hash, run, restore, confirm the restored blob is byte-identical to the HEAD blob with git diff HEAD empty. Mutated: Test Files 1 failed, the guard naming file, test and URL.

Green with the guard: the 21 known files (690 tests, 135 attributed lines, 0 guard failures) · unit (808 files, 12572 passed, 9 pre-existing skips) · dom-heavy (34 files, 332 tests) · dom shard 5/16 (89 files, 1516 tests) · dom shard 3/8, the escape-heaviest (179 files, 2275 tests).

type-check:vitest-setup earned its keep twice. It ships no @types/node by design, so the first draft's node:fs / node:path / process / import.meta.dirname uses were five real errors; the guard now declares the one structural type it needs. And re-running the suite after that rewrite caught the second defect: Vite statically rewrites the new URL('.', import.meta.url) pattern at transform time, so the value reaching the run was /@fs/... rather than a real path — every path relative-isation missed and all 21 known escapes failed at once. Derived by string surgery on import.meta.url instead.

Patch round (review follow-up)

The ledger's docstring said it "may only shrink" and nothing made that true — an author meeting the guard's red could go green by adding a line, which is precisely how a burn-down ledger decays into the permanent quarantine it is not supposed to be. KNOWN_ESCAPES is now exported (that export is its only behaviour change) and pinned by scripts/__tests__/network-escape-ledger.test.ts, which reconciles the live set against a pinned literal of the 21 measured paths in both directions:

• a name in the ledger but not the pin ⇒ the ledger grew. Red.
• a name in the pin but not the ledger ⇒ a fix landed and the pin is stale. Red until the pin is updated too, so shrinking is a deliberate two-line change rather than a silent one.

Plus an anchored non-vacuity floor, because both reconciles pass vacuously on two empty collections: the pin must be non-empty, the imported set must be non-empty, and every pinned path must still resolve on disk (so a rename cannot leave the two sides agreeing about files that no longer exist).

Proved by ablation on disk, each leg confirmed by blob hash and restored to a byte-identical blob with git diff HEAD empty:

• add a bogus name to KNOWN_ESCAPES ⇒ Tests 1 failed | 2 passed, "The network-escape ledger GREW, and it may only shrink."
• delete a real name without touching the pin ⇒ Tests 1 failed | 2 passed, "A pinned escape is gone from KNOWN_ESCAPES — which is good news, banked wrong."

Gates on 1836f41f8, each quoting its own verdict line: type-check:vitest-setup exit 0 · type-check:scripts exit 0 (the new import edge from scripts/__tests__ to the root setup file is clean) · check:control-bytes "OK (scanned 5998 tracked text file(s); skipped 85 binary)" · eslint on both changed files exit 0, 0 errors · network-escape-ledger.test.ts + vitest-invocation-guard.test.ts "Test Files 2 passed (2) / Tests 33 passed (33)" · the 21 known files again "Test Files 21 passed (21) / Tests 690 passed (690)", 135 attributed lines, 0 guard failures · check-changeset-presence "No source or published contract of a released package changed in this range, so no changeset is owed."

Declared narrowing

The remaining dom shards were swept for attribution but not re-run against the final commit; CI runs the full farm regardless. Two runs were cut by the container's 10-minute foreground cap and recorded NOT MEASURED, then re-run split rather than quoted.

Follow-up, deliberately not in this PR

The 21 known escapes are recorded, not excused. Each is fixed by serving its probe from a double — see packages/plugin-report/src/__tests__/DatasetReportRenderer.test.tsx for the shape — and deleting its line from KNOWN_ESCAPESand from the pin. That is per-file work across 9 packages and belongs in its own cards, not riding on the instrument that found them.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BGMDbrVa8JjZcCQ7DWYH1b

[yinlianghui]

Fixes#6640

Verified on 1836f41f8. Three files: vitest.setup.network-escape-guard.ts (new), scripts/__tests__/network-escape-ledger.test.ts (new, the shrink-only pin), and one import line in vitest.setup.base.ts.

Attribution first, per the triage ruling

A sweep of every project — dom (all 8 shards), dom-heavy, unit, apps/console, each VERDICT command-exit 0 from the shared verify lock — attributes the class to 21 test files across 9 packages: app-shell (8), plugin-detail (4), plugin-kanban (3), and one each in plugin-view, plugin-calendar, plugin-grid, plugin-gantt, plugin-charts, examples/schema-catalog. They reach /api/v1/security/explain, /api/v1/meta/_drafts, /api/v1/meta/object, /api/v1/meta/object/task, /api/v1/ai/conversations and /api/v1/automation/_status. The full table with per-file rows is on the card.

This selects possibility 1, and falsifies possibility 2. Not one of the 21 is a file the four closed siblings fixed. Checked by symptom rather than by issue number: all eight landed doubles are still on main and still working (stubGlobal + unstubAllGlobals present, none appears in the sweep) — DatasetReportRenderer (#5225), DetailView + DetailView.invalidation (#3339), ObjectChart.compareTo (#4106), FlowCanvas + the metadata-admin inspectors (#4688), plus the DatasetWidget / DashboardGridLayout.datasetPath / calendar propsContract siblings. No fix was reverted, so the closed cards are not lying about main and no annotation is owed them.

The sharpest illustration of what is actually broken sits in one directory: #4688 stubbed ActionDefaultInspector, ConditionBuilder, HookDefaultInspector, PageBlockInspector and ViewVariantInspector, while FlowNodeInspector.specKeys and .inactiveRetained — same directory, same mechanism — were simply not in its enumeration. Each fix closed the files someone had listed by hand, and the list is hand-made. That is why a fifth per-package fix is the wrong shape.

Mechanism

happy-dom's default document URL is http://localhost:3000; nothing in this repo configures it. So a DOM-env test rendering a component that reaches one of the roughly 18 apiFetch ?? fetch / globalThis.fetch fallbacks in product code resolves a relative /api/v1/... against a real TCP socket.

Two findings that shaped the instrument

1. The stacks are unattributable, and that — not the noise — is the defect. They arrive as

Error: connect ECONNREFUSED 127.0.0.1:3000
at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1637:16)

with no stderr | FILE > TESTNAME header and no user stack frame, because it is an unhandled socket error raised below the layer Vitest captures per test. Vitest cannot tie it to a file. That is why the class survived four fixes: the output never said who was left.

2. A throwing fetch would never fire. Every escaping call site is const doFetch = apiFetch ?? fetch inside try { ... } catch { } — best-effort by construction, which is exactly why the suite is green while escaping. A rejection raised from inside fetch lands in that same catch and is swallowed, leaving the test green and the guard silent. So the escape is recorded at the call and asserted in afterEach, where no product catch can reach it. Measured: the ablation below fails only because of this choice.

What it does and does not do

It silences nothing — the real request still goes out and the real ECONNREFUSED still prints, because those stacks are the evidence that a test reached for a socket. Beside each one the guard now writes an attributed line naming the owning file, so a bare stack in a truncated log is no longer an unowned red. It skips and quarantines nothing: every test still runs and asserts exactly what it asserted before. KNOWN_ESCAPES is the 21 measured files and may only shrink — a new escape in any other file is red on its first run, which is the structural close of the class.

Written straight to process stderr rather than through console: under happy-dom globalThis.console is the window's virtual console and never reaches the terminal (measured — the line vanished entirely), and process stderr is also the only stream that puts the attribution beside the stack it explains.

Verification

Ablation, on the committed tree: delete one entry from KNOWN_ESCAPES, confirm the mutation landed by blob hash, run, restore, confirm the restored blob is byte-identical to the HEAD blob with git diff HEAD empty. Mutated: Test Files 1 failed, the guard naming file, test and URL.

Green with the guard: the 21 known files (690 tests, 135 attributed lines, 0 guard failures) · unit (808 files, 12572 passed, 9 pre-existing skips) · dom-heavy (34 files, 332 tests) · dom shard 5/16 (89 files, 1516 tests) · dom shard 3/8, the escape-heaviest (179 files, 2275 tests).

type-check:vitest-setup earned its keep twice. It ships no @types/node by design, so the first draft's node:fs / node:path / process / import.meta.dirname uses were five real errors; the guard now declares the one structural type it needs. And re-running the suite after that rewrite caught the second defect: Vite statically rewrites the new URL('.', import.meta.url) pattern at transform time, so the value reaching the run was /@fs/... rather than a real path — every path relative-isation missed and all 21 known escapes failed at once. Derived by string surgery on import.meta.url instead.

Patch round (review follow-up)

The ledger's docstring said it "may only shrink" and nothing made that true — an author meeting the guard's red could go green by adding a line, which is precisely how a burn-down ledger decays into the permanent quarantine it is not supposed to be. KNOWN_ESCAPES is now exported (that export is its only behaviour change) and pinned by scripts/__tests__/network-escape-ledger.test.ts, which reconciles the live set against a pinned literal of the 21 measured paths in both directions:

• a name in the ledger but not the pin ⇒ the ledger grew. Red.
• a name in the pin but not the ledger ⇒ a fix landed and the pin is stale. Red until the pin is updated too, so shrinking is a deliberate two-line change rather than a silent one.

Plus an anchored non-vacuity floor, because both reconciles pass vacuously on two empty collections: the pin must be non-empty, the imported set must be non-empty, and every pinned path must still resolve on disk (so a rename cannot leave the two sides agreeing about files that no longer exist).

Proved by ablation on disk, each leg confirmed by blob hash and restored to a byte-identical blob with git diff HEAD empty:

• add a bogus name to KNOWN_ESCAPES ⇒ Tests 1 failed | 2 passed, "The network-escape ledger GREW, and it may only shrink."
• delete a real name without touching the pin ⇒ Tests 1 failed | 2 passed, "A pinned escape is gone from KNOWN_ESCAPES — which is good news, banked wrong."

Gates on 1836f41f8, each quoting its own verdict line: type-check:vitest-setup exit 0 · type-check:scripts exit 0 (the new import edge from scripts/__tests__ to the root setup file is clean) · check:control-bytes "OK (scanned 5998 tracked text file(s); skipped 85 binary)" · eslint on both changed files exit 0, 0 errors · network-escape-ledger.test.ts + vitest-invocation-guard.test.ts "Test Files 2 passed (2) / Tests 33 passed (33)" · the 21 known files again "Test Files 21 passed (21) / Tests 690 passed (690)", 135 attributed lines, 0 guard failures · check-changeset-presence "No source or published contract of a released package changed in this range, so no changeset is owed."

Declared narrowing

The remaining dom shards were swept for attribution but not re-run against the final commit; CI runs the full farm regardless. Two runs were cut by the container's 10-minute foreground cap and recorded NOT MEASURED, then re-run split rather than quoted.

Follow-up, deliberately not in this PR

The 21 known escapes are recorded, not excused. Each is fixed by serving its probe from a double — see packages/plugin-report/src/__tests__/DatasetReportRenderer.test.tsx for the shape — and deleting its line from KNOWN_ESCAPESand from the pin. That is per-file work across 9 packages and belongs in its own cards, not riding on the instrument that found them.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BGMDbrVa8JjZcCQ7DWYH1b

[yinlianghui]

Fixes#6640

Verified on 1836f41f8. Three files: vitest.setup.network-escape-guard.ts (new), scripts/__tests__/network-escape-ledger.test.ts (new, the shrink-only pin), and one import line in vitest.setup.base.ts.

Attribution first, per the triage ruling

A sweep of every project — dom (all 8 shards), dom-heavy, unit, apps/console, each VERDICT command-exit 0 from the shared verify lock — attributes the class to 21 test files across 9 packages: app-shell (8), plugin-detail (4), plugin-kanban (3), and one each in plugin-view, plugin-calendar, plugin-grid, plugin-gantt, plugin-charts, examples/schema-catalog. They reach /api/v1/security/explain, /api/v1/meta/_drafts, /api/v1/meta/object, /api/v1/meta/object/task, /api/v1/ai/conversations and /api/v1/automation/_status. The full table with per-file rows is on the card.

This selects possibility 1, and falsifies possibility 2. Not one of the 21 is a file the four closed siblings fixed. Checked by symptom rather than by issue number: all eight landed doubles are still on main and still working (stubGlobal + unstubAllGlobals present, none appears in the sweep) — DatasetReportRenderer (#5225), DetailView + DetailView.invalidation (#3339), ObjectChart.compareTo (#4106), FlowCanvas + the metadata-admin inspectors (#4688), plus the DatasetWidget / DashboardGridLayout.datasetPath / calendar propsContract siblings. No fix was reverted, so the closed cards are not lying about main and no annotation is owed them.

The sharpest illustration of what is actually broken sits in one directory: #4688 stubbed ActionDefaultInspector, ConditionBuilder, HookDefaultInspector, PageBlockInspector and ViewVariantInspector, while FlowNodeInspector.specKeys and .inactiveRetained — same directory, same mechanism — were simply not in its enumeration. Each fix closed the files someone had listed by hand, and the list is hand-made. That is why a fifth per-package fix is the wrong shape.

Mechanism

happy-dom's default document URL is http://localhost:3000; nothing in this repo configures it. So a DOM-env test rendering a component that reaches one of the roughly 18 apiFetch ?? fetch / globalThis.fetch fallbacks in product code resolves a relative /api/v1/... against a real TCP socket.

Two findings that shaped the instrument

1. The stacks are unattributable, and that — not the noise — is the defect. They arrive as

Error: connect ECONNREFUSED 127.0.0.1:3000
at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1637:16)

with no stderr | FILE > TESTNAME header and no user stack frame, because it is an unhandled socket error raised below the layer Vitest captures per test. Vitest cannot tie it to a file. That is why the class survived four fixes: the output never said who was left.

2. A throwing fetch would never fire. Every escaping call site is const doFetch = apiFetch ?? fetch inside try { ... } catch { } — best-effort by construction, which is exactly why the suite is green while escaping. A rejection raised from inside fetch lands in that same catch and is swallowed, leaving the test green and the guard silent. So the escape is recorded at the call and asserted in afterEach, where no product catch can reach it. Measured: the ablation below fails only because of this choice.

What it does and does not do

It silences nothing — the real request still goes out and the real ECONNREFUSED still prints, because those stacks are the evidence that a test reached for a socket. Beside each one the guard now writes an attributed line naming the owning file, so a bare stack in a truncated log is no longer an unowned red. It skips and quarantines nothing: every test still runs and asserts exactly what it asserted before. KNOWN_ESCAPES is the 21 measured files and may only shrink — a new escape in any other file is red on its first run, which is the structural close of the class.

Written straight to process stderr rather than through console: under happy-dom globalThis.console is the window's virtual console and never reaches the terminal (measured — the line vanished entirely), and process stderr is also the only stream that puts the attribution beside the stack it explains.

Verification

Ablation, on the committed tree: delete one entry from KNOWN_ESCAPES, confirm the mutation landed by blob hash, run, restore, confirm the restored blob is byte-identical to the HEAD blob with git diff HEAD empty. Mutated: Test Files 1 failed, the guard naming file, test and URL.

Green with the guard: the 21 known files (690 tests, 135 attributed lines, 0 guard failures) · unit (808 files, 12572 passed, 9 pre-existing skips) · dom-heavy (34 files, 332 tests) · dom shard 5/16 (89 files, 1516 tests) · dom shard 3/8, the escape-heaviest (179 files, 2275 tests).

type-check:vitest-setup earned its keep twice. It ships no @types/node by design, so the first draft's node:fs / node:path / process / import.meta.dirname uses were five real errors; the guard now declares the one structural type it needs. And re-running the suite after that rewrite caught the second defect: Vite statically rewrites the new URL('.', import.meta.url) pattern at transform time, so the value reaching the run was /@fs/... rather than a real path — every path relative-isation missed and all 21 known escapes failed at once. Derived by string surgery on import.meta.url instead.

Patch round (review follow-up)

The ledger's docstring said it "may only shrink" and nothing made that true — an author meeting the guard's red could go green by adding a line, which is precisely how a burn-down ledger decays into the permanent quarantine it is not supposed to be. KNOWN_ESCAPES is now exported (that export is its only behaviour change) and pinned by scripts/__tests__/network-escape-ledger.test.ts, which reconciles the live set against a pinned literal of the 21 measured paths in both directions:

• a name in the ledger but not the pin ⇒ the ledger grew. Red.
• a name in the pin but not the ledger ⇒ a fix landed and the pin is stale. Red until the pin is updated too, so shrinking is a deliberate two-line change rather than a silent one.

Plus an anchored non-vacuity floor, because both reconciles pass vacuously on two empty collections: the pin must be non-empty, the imported set must be non-empty, and every pinned path must still resolve on disk (so a rename cannot leave the two sides agreeing about files that no longer exist).

Proved by ablation on disk, each leg confirmed by blob hash and restored to a byte-identical blob with git diff HEAD empty:

• add a bogus name to KNOWN_ESCAPES ⇒ Tests 1 failed | 2 passed, "The network-escape ledger GREW, and it may only shrink."
• delete a real name without touching the pin ⇒ Tests 1 failed | 2 passed, "A pinned escape is gone from KNOWN_ESCAPES — which is good news, banked wrong."

Gates on 1836f41f8, each quoting its own verdict line: type-check:vitest-setup exit 0 · type-check:scripts exit 0 (the new import edge from scripts/__tests__ to the root setup file is clean) · check:control-bytes "OK (scanned 5998 tracked text file(s); skipped 85 binary)" · eslint on both changed files exit 0, 0 errors · network-escape-ledger.test.ts + vitest-invocation-guard.test.ts "Test Files 2 passed (2) / Tests 33 passed (33)" · the 21 known files again "Test Files 21 passed (21) / Tests 690 passed (690)", 135 attributed lines, 0 guard failures · check-changeset-presence "No source or published contract of a released package changed in this range, so no changeset is owed."

Declared narrowing

The remaining dom shards were swept for attribution but not re-run against the final commit; CI runs the full farm regardless. Two runs were cut by the container's 10-minute foreground cap and recorded NOT MEASURED, then re-run split rather than quoted.

Follow-up, deliberately not in this PR

The 21 known escapes are recorded, not excused. Each is fixed by serving its probe from a double — see packages/plugin-report/src/__tests__/DatasetReportRenderer.test.tsx for the shape — and deleting its line from KNOWN_ESCAPESand from the pin. That is per-file work across 9 packages and belongs in its own cards, not riding on the instrument that found them.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BGMDbrVa8JjZcCQ7DWYH1b

[yinlianghui]

Fixes#6640

Verified on 1836f41f8. Three files: vitest.setup.network-escape-guard.ts (new), scripts/__tests__/network-escape-ledger.test.ts (new, the shrink-only pin), and one import line in vitest.setup.base.ts.

Attribution first, per the triage ruling

A sweep of every project — dom (all 8 shards), dom-heavy, unit, apps/console, each VERDICT command-exit 0 from the shared verify lock — attributes the class to 21 test files across 9 packages: app-shell (8), plugin-detail (4), plugin-kanban (3), and one each in plugin-view, plugin-calendar, plugin-grid, plugin-gantt, plugin-charts, examples/schema-catalog. They reach /api/v1/security/explain, /api/v1/meta/_drafts, /api/v1/meta/object, /api/v1/meta/object/task, /api/v1/ai/conversations and /api/v1/automation/_status. The full table with per-file rows is on the card.

This selects possibility 1, and falsifies possibility 2. Not one of the 21 is a file the four closed siblings fixed. Checked by symptom rather than by issue number: all eight landed doubles are still on main and still working (stubGlobal + unstubAllGlobals present, none appears in the sweep) — DatasetReportRenderer (#5225), DetailView + DetailView.invalidation (#3339), ObjectChart.compareTo (#4106), FlowCanvas + the metadata-admin inspectors (#4688), plus the DatasetWidget / DashboardGridLayout.datasetPath / calendar propsContract siblings. No fix was reverted, so the closed cards are not lying about main and no annotation is owed them.

The sharpest illustration of what is actually broken sits in one directory: #4688 stubbed ActionDefaultInspector, ConditionBuilder, HookDefaultInspector, PageBlockInspector and ViewVariantInspector, while FlowNodeInspector.specKeys and .inactiveRetained — same directory, same mechanism — were simply not in its enumeration. Each fix closed the files someone had listed by hand, and the list is hand-made. That is why a fifth per-package fix is the wrong shape.

Mechanism

happy-dom's default document URL is http://localhost:3000; nothing in this repo configures it. So a DOM-env test rendering a component that reaches one of the roughly 18 apiFetch ?? fetch / globalThis.fetch fallbacks in product code resolves a relative /api/v1/... against a real TCP socket.

Two findings that shaped the instrument

1. The stacks are unattributable, and that — not the noise — is the defect. They arrive as

Error: connect ECONNREFUSED 127.0.0.1:3000
at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1637:16)

with no stderr | FILE > TESTNAME header and no user stack frame, because it is an unhandled socket error raised below the layer Vitest captures per test. Vitest cannot tie it to a file. That is why the class survived four fixes: the output never said who was left.

2. A throwing fetch would never fire. Every escaping call site is const doFetch = apiFetch ?? fetch inside try { ... } catch { } — best-effort by construction, which is exactly why the suite is green while escaping. A rejection raised from inside fetch lands in that same catch and is swallowed, leaving the test green and the guard silent. So the escape is recorded at the call and asserted in afterEach, where no product catch can reach it. Measured: the ablation below fails only because of this choice.

What it does and does not do

It silences nothing — the real request still goes out and the real ECONNREFUSED still prints, because those stacks are the evidence that a test reached for a socket. Beside each one the guard now writes an attributed line naming the owning file, so a bare stack in a truncated log is no longer an unowned red. It skips and quarantines nothing: every test still runs and asserts exactly what it asserted before. KNOWN_ESCAPES is the 21 measured files and may only shrink — a new escape in any other file is red on its first run, which is the structural close of the class.

Written straight to process stderr rather than through console: under happy-dom globalThis.console is the window's virtual console and never reaches the terminal (measured — the line vanished entirely), and process stderr is also the only stream that puts the attribution beside the stack it explains.

Verification

Ablation, on the committed tree: delete one entry from KNOWN_ESCAPES, confirm the mutation landed by blob hash, run, restore, confirm the restored blob is byte-identical to the HEAD blob with git diff HEAD empty. Mutated: Test Files 1 failed, the guard naming file, test and URL.

Green with the guard: the 21 known files (690 tests, 135 attributed lines, 0 guard failures) · unit (808 files, 12572 passed, 9 pre-existing skips) · dom-heavy (34 files, 332 tests) · dom shard 5/16 (89 files, 1516 tests) · dom shard 3/8, the escape-heaviest (179 files, 2275 tests).

type-check:vitest-setup earned its keep twice. It ships no @types/node by design, so the first draft's node:fs / node:path / process / import.meta.dirname uses were five real errors; the guard now declares the one structural type it needs. And re-running the suite after that rewrite caught the second defect: Vite statically rewrites the new URL('.', import.meta.url) pattern at transform time, so the value reaching the run was /@fs/... rather than a real path — every path relative-isation missed and all 21 known escapes failed at once. Derived by string surgery on import.meta.url instead.

Patch round (review follow-up)

The ledger's docstring said it "may only shrink" and nothing made that true — an author meeting the guard's red could go green by adding a line, which is precisely how a burn-down ledger decays into the permanent quarantine it is not supposed to be. KNOWN_ESCAPES is now exported (that export is its only behaviour change) and pinned by scripts/__tests__/network-escape-ledger.test.ts, which reconciles the live set against a pinned literal of the 21 measured paths in both directions:

• a name in the ledger but not the pin ⇒ the ledger grew. Red.
• a name in the pin but not the ledger ⇒ a fix landed and the pin is stale. Red until the pin is updated too, so shrinking is a deliberate two-line change rather than a silent one.

Plus an anchored non-vacuity floor, because both reconciles pass vacuously on two empty collections: the pin must be non-empty, the imported set must be non-empty, and every pinned path must still resolve on disk (so a rename cannot leave the two sides agreeing about files that no longer exist).

Proved by ablation on disk, each leg confirmed by blob hash and restored to a byte-identical blob with git diff HEAD empty:

• add a bogus name to KNOWN_ESCAPES ⇒ Tests 1 failed | 2 passed, "The network-escape ledger GREW, and it may only shrink."
• delete a real name without touching the pin ⇒ Tests 1 failed | 2 passed, "A pinned escape is gone from KNOWN_ESCAPES — which is good news, banked wrong."

Gates on 1836f41f8, each quoting its own verdict line: type-check:vitest-setup exit 0 · type-check:scripts exit 0 (the new import edge from scripts/__tests__ to the root setup file is clean) · check:control-bytes "OK (scanned 5998 tracked text file(s); skipped 85 binary)" · eslint on both changed files exit 0, 0 errors · network-escape-ledger.test.ts + vitest-invocation-guard.test.ts "Test Files 2 passed (2) / Tests 33 passed (33)" · the 21 known files again "Test Files 21 passed (21) / Tests 690 passed (690)", 135 attributed lines, 0 guard failures · check-changeset-presence "No source or published contract of a released package changed in this range, so no changeset is owed."

Declared narrowing

The remaining dom shards were swept for attribution but not re-run against the final commit; CI runs the full farm regardless. Two runs were cut by the container's 10-minute foreground cap and recorded NOT MEASURED, then re-run split rather than quoted.

Follow-up, deliberately not in this PR

The 21 known escapes are recorded, not excused. Each is fixed by serving its probe from a double — see packages/plugin-report/src/__tests__/DatasetReportRenderer.test.tsx for the shape — and deleting its line from KNOWN_ESCAPESand from the pin. That is per-file work across 9 packages and belongs in its own cards, not riding on the instrument that found them.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BGMDbrVa8JjZcCQ7DWYH1b

[yinlianghui]

Fixes#6640

Verified on 1836f41f8. Three files: vitest.setup.network-escape-guard.ts (new), scripts/__tests__/network-escape-ledger.test.ts (new, the shrink-only pin), and one import line in vitest.setup.base.ts.

Attribution first, per the triage ruling

A sweep of every project — dom (all 8 shards), dom-heavy, unit, apps/console, each VERDICT command-exit 0 from the shared verify lock — attributes the class to 21 test files across 9 packages: app-shell (8), plugin-detail (4), plugin-kanban (3), and one each in plugin-view, plugin-calendar, plugin-grid, plugin-gantt, plugin-charts, examples/schema-catalog. They reach /api/v1/security/explain, /api/v1/meta/_drafts, /api/v1/meta/object, /api/v1/meta/object/task, /api/v1/ai/conversations and /api/v1/automation/_status. The full table with per-file rows is on the card.

This selects possibility 1, and falsifies possibility 2. Not one of the 21 is a file the four closed siblings fixed. Checked by symptom rather than by issue number: all eight landed doubles are still on main and still working (stubGlobal + unstubAllGlobals present, none appears in the sweep) — DatasetReportRenderer (#5225), DetailView + DetailView.invalidation (#3339), ObjectChart.compareTo (#4106), FlowCanvas + the metadata-admin inspectors (#4688), plus the DatasetWidget / DashboardGridLayout.datasetPath / calendar propsContract siblings. No fix was reverted, so the closed cards are not lying about main and no annotation is owed them.

The sharpest illustration of what is actually broken sits in one directory: #4688 stubbed ActionDefaultInspector, ConditionBuilder, HookDefaultInspector, PageBlockInspector and ViewVariantInspector, while FlowNodeInspector.specKeys and .inactiveRetained — same directory, same mechanism — were simply not in its enumeration. Each fix closed the files someone had listed by hand, and the list is hand-made. That is why a fifth per-package fix is the wrong shape.

Mechanism

happy-dom's default document URL is http://localhost:3000; nothing in this repo configures it. So a DOM-env test rendering a component that reaches one of the roughly 18 apiFetch ?? fetch / globalThis.fetch fallbacks in product code resolves a relative /api/v1/... against a real TCP socket.

Two findings that shaped the instrument

1. The stacks are unattributable, and that — not the noise — is the defect. They arrive as

Error: connect ECONNREFUSED 127.0.0.1:3000
at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1637:16)

with no stderr | FILE > TESTNAME header and no user stack frame, because it is an unhandled socket error raised below the layer Vitest captures per test. Vitest cannot tie it to a file. That is why the class survived four fixes: the output never said who was left.

2. A throwing fetch would never fire. Every escaping call site is const doFetch = apiFetch ?? fetch inside try { ... } catch { } — best-effort by construction, which is exactly why the suite is green while escaping. A rejection raised from inside fetch lands in that same catch and is swallowed, leaving the test green and the guard silent. So the escape is recorded at the call and asserted in afterEach, where no product catch can reach it. Measured: the ablation below fails only because of this choice.

What it does and does not do

It silences nothing — the real request still goes out and the real ECONNREFUSED still prints, because those stacks are the evidence that a test reached for a socket. Beside each one the guard now writes an attributed line naming the owning file, so a bare stack in a truncated log is no longer an unowned red. It skips and quarantines nothing: every test still runs and asserts exactly what it asserted before. KNOWN_ESCAPES is the 21 measured files and may only shrink — a new escape in any other file is red on its first run, which is the structural close of the class.

Written straight to process stderr rather than through console: under happy-dom globalThis.console is the window's virtual console and never reaches the terminal (measured — the line vanished entirely), and process stderr is also the only stream that puts the attribution beside the stack it explains.

Verification

Ablation, on the committed tree: delete one entry from KNOWN_ESCAPES, confirm the mutation landed by blob hash, run, restore, confirm the restored blob is byte-identical to the HEAD blob with git diff HEAD empty. Mutated: Test Files 1 failed, the guard naming file, test and URL.

Green with the guard: the 21 known files (690 tests, 135 attributed lines, 0 guard failures) · unit (808 files, 12572 passed, 9 pre-existing skips) · dom-heavy (34 files, 332 tests) · dom shard 5/16 (89 files, 1516 tests) · dom shard 3/8, the escape-heaviest (179 files, 2275 tests).

type-check:vitest-setup earned its keep twice. It ships no @types/node by design, so the first draft's node:fs / node:path / process / import.meta.dirname uses were five real errors; the guard now declares the one structural type it needs. And re-running the suite after that rewrite caught the second defect: Vite statically rewrites the new URL('.', import.meta.url) pattern at transform time, so the value reaching the run was /@fs/... rather than a real path — every path relative-isation missed and all 21 known escapes failed at once. Derived by string surgery on import.meta.url instead.

Patch round (review follow-up)

The ledger's docstring said it "may only shrink" and nothing made that true — an author meeting the guard's red could go green by adding a line, which is precisely how a burn-down ledger decays into the permanent quarantine it is not supposed to be. KNOWN_ESCAPES is now exported (that export is its only behaviour change) and pinned by scripts/__tests__/network-escape-ledger.test.ts, which reconciles the live set against a pinned literal of the 21 measured paths in both directions:

• a name in the ledger but not the pin ⇒ the ledger grew. Red.
• a name in the pin but not the ledger ⇒ a fix landed and the pin is stale. Red until the pin is updated too, so shrinking is a deliberate two-line change rather than a silent one.

Plus an anchored non-vacuity floor, because both reconciles pass vacuously on two empty collections: the pin must be non-empty, the imported set must be non-empty, and every pinned path must still resolve on disk (so a rename cannot leave the two sides agreeing about files that no longer exist).

Proved by ablation on disk, each leg confirmed by blob hash and restored to a byte-identical blob with git diff HEAD empty:

• add a bogus name to KNOWN_ESCAPES ⇒ Tests 1 failed | 2 passed, "The network-escape ledger GREW, and it may only shrink."
• delete a real name without touching the pin ⇒ Tests 1 failed | 2 passed, "A pinned escape is gone from KNOWN_ESCAPES — which is good news, banked wrong."

Gates on 1836f41f8, each quoting its own verdict line: type-check:vitest-setup exit 0 · type-check:scripts exit 0 (the new import edge from scripts/__tests__ to the root setup file is clean) · check:control-bytes "OK (scanned 5998 tracked text file(s); skipped 85 binary)" · eslint on both changed files exit 0, 0 errors · network-escape-ledger.test.ts + vitest-invocation-guard.test.ts "Test Files 2 passed (2) / Tests 33 passed (33)" · the 21 known files again "Test Files 21 passed (21) / Tests 690 passed (690)", 135 attributed lines, 0 guard failures · check-changeset-presence "No source or published contract of a released package changed in this range, so no changeset is owed."

Declared narrowing

The remaining dom shards were swept for attribution but not re-run against the final commit; CI runs the full farm regardless. Two runs were cut by the container's 10-minute foreground cap and recorded NOT MEASURED, then re-run split rather than quoted.

Follow-up, deliberately not in this PR

The 21 known escapes are recorded, not excused. Each is fixed by serving its probe from a double — see packages/plugin-report/src/__tests__/DatasetReportRenderer.test.tsx for the shape — and deleting its line from KNOWN_ESCAPESand from the pin. That is per-file work across 9 packages and belongs in its own cards, not riding on the instrument that found them.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BGMDbrVa8JjZcCQ7DWYH1b

[yinlianghui]

Fixes#6640

Verified on 1836f41f8. Three files: vitest.setup.network-escape-guard.ts (new), scripts/__tests__/network-escape-ledger.test.ts (new, the shrink-only pin), and one import line in vitest.setup.base.ts.

Attribution first, per the triage ruling

A sweep of every project — dom (all 8 shards), dom-heavy, unit, apps/console, each VERDICT command-exit 0 from the shared verify lock — attributes the class to 21 test files across 9 packages: app-shell (8), plugin-detail (4), plugin-kanban (3), and one each in plugin-view, plugin-calendar, plugin-grid, plugin-gantt, plugin-charts, examples/schema-catalog. They reach /api/v1/security/explain, /api/v1/meta/_drafts, /api/v1/meta/object, /api/v1/meta/object/task, /api/v1/ai/conversations and /api/v1/automation/_status. The full table with per-file rows is on the card.

This selects possibility 1, and falsifies possibility 2. Not one of the 21 is a file the four closed siblings fixed. Checked by symptom rather than by issue number: all eight landed doubles are still on main and still working (stubGlobal + unstubAllGlobals present, none appears in the sweep) — DatasetReportRenderer (#5225), DetailView + DetailView.invalidation (#3339), ObjectChart.compareTo (#4106), FlowCanvas + the metadata-admin inspectors (#4688), plus the DatasetWidget / DashboardGridLayout.datasetPath / calendar propsContract siblings. No fix was reverted, so the closed cards are not lying about main and no annotation is owed them.

The sharpest illustration of what is actually broken sits in one directory: #4688 stubbed ActionDefaultInspector, ConditionBuilder, HookDefaultInspector, PageBlockInspector and ViewVariantInspector, while FlowNodeInspector.specKeys and .inactiveRetained — same directory, same mechanism — were simply not in its enumeration. Each fix closed the files someone had listed by hand, and the list is hand-made. That is why a fifth per-package fix is the wrong shape.

Mechanism

happy-dom's default document URL is http://localhost:3000; nothing in this repo configures it. So a DOM-env test rendering a component that reaches one of the roughly 18 apiFetch ?? fetch / globalThis.fetch fallbacks in product code resolves a relative /api/v1/... against a real TCP socket.

Two findings that shaped the instrument

1. The stacks are unattributable, and that — not the noise — is the defect. They arrive as

Error: connect ECONNREFUSED 127.0.0.1:3000
at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1637:16)

with no stderr | FILE > TESTNAME header and no user stack frame, because it is an unhandled socket error raised below the layer Vitest captures per test. Vitest cannot tie it to a file. That is why the class survived four fixes: the output never said who was left.

2. A throwing fetch would never fire. Every escaping call site is const doFetch = apiFetch ?? fetch inside try { ... } catch { } — best-effort by construction, which is exactly why the suite is green while escaping. A rejection raised from inside fetch lands in that same catch and is swallowed, leaving the test green and the guard silent. So the escape is recorded at the call and asserted in afterEach, where no product catch can reach it. Measured: the ablation below fails only because of this choice.

What it does and does not do

It silences nothing — the real request still goes out and the real ECONNREFUSED still prints, because those stacks are the evidence that a test reached for a socket. Beside each one the guard now writes an attributed line naming the owning file, so a bare stack in a truncated log is no longer an unowned red. It skips and quarantines nothing: every test still runs and asserts exactly what it asserted before. KNOWN_ESCAPES is the 21 measured files and may only shrink — a new escape in any other file is red on its first run, which is the structural close of the class.

Written straight to process stderr rather than through console: under happy-dom globalThis.console is the window's virtual console and never reaches the terminal (measured — the line vanished entirely), and process stderr is also the only stream that puts the attribution beside the stack it explains.

Verification

Ablation, on the committed tree: delete one entry from KNOWN_ESCAPES, confirm the mutation landed by blob hash, run, restore, confirm the restored blob is byte-identical to the HEAD blob with git diff HEAD empty. Mutated: Test Files 1 failed, the guard naming file, test and URL.

Green with the guard: the 21 known files (690 tests, 135 attributed lines, 0 guard failures) · unit (808 files, 12572 passed, 9 pre-existing skips) · dom-heavy (34 files, 332 tests) · dom shard 5/16 (89 files, 1516 tests) · dom shard 3/8, the escape-heaviest (179 files, 2275 tests).

type-check:vitest-setup earned its keep twice. It ships no @types/node by design, so the first draft's node:fs / node:path / process / import.meta.dirname uses were five real errors; the guard now declares the one structural type it needs. And re-running the suite after that rewrite caught the second defect: Vite statically rewrites the new URL('.', import.meta.url) pattern at transform time, so the value reaching the run was /@fs/... rather than a real path — every path relative-isation missed and all 21 known escapes failed at once. Derived by string surgery on import.meta.url instead.

Patch round (review follow-up)

The ledger's docstring said it "may only shrink" and nothing made that true — an author meeting the guard's red could go green by adding a line, which is precisely how a burn-down ledger decays into the permanent quarantine it is not supposed to be. KNOWN_ESCAPES is now exported (that export is its only behaviour change) and pinned by scripts/__tests__/network-escape-ledger.test.ts, which reconciles the live set against a pinned literal of the 21 measured paths in both directions:

• a name in the ledger but not the pin ⇒ the ledger grew. Red.
• a name in the pin but not the ledger ⇒ a fix landed and the pin is stale. Red until the pin is updated too, so shrinking is a deliberate two-line change rather than a silent one.

Plus an anchored non-vacuity floor, because both reconciles pass vacuously on two empty collections: the pin must be non-empty, the imported set must be non-empty, and every pinned path must still resolve on disk (so a rename cannot leave the two sides agreeing about files that no longer exist).

Proved by ablation on disk, each leg confirmed by blob hash and restored to a byte-identical blob with git diff HEAD empty:

• add a bogus name to KNOWN_ESCAPES ⇒ Tests 1 failed | 2 passed, "The network-escape ledger GREW, and it may only shrink."
• delete a real name without touching the pin ⇒ Tests 1 failed | 2 passed, "A pinned escape is gone from KNOWN_ESCAPES — which is good news, banked wrong."

Gates on 1836f41f8, each quoting its own verdict line: type-check:vitest-setup exit 0 · type-check:scripts exit 0 (the new import edge from scripts/__tests__ to the root setup file is clean) · check:control-bytes "OK (scanned 5998 tracked text file(s); skipped 85 binary)" · eslint on both changed files exit 0, 0 errors · network-escape-ledger.test.ts + vitest-invocation-guard.test.ts "Test Files 2 passed (2) / Tests 33 passed (33)" · the 21 known files again "Test Files 21 passed (21) / Tests 690 passed (690)", 135 attributed lines, 0 guard failures · check-changeset-presence "No source or published contract of a released package changed in this range, so no changeset is owed."

Declared narrowing

The remaining dom shards were swept for attribution but not re-run against the final commit; CI runs the full farm regardless. Two runs were cut by the container's 10-minute foreground cap and recorded NOT MEASURED, then re-run split rather than quoted.

Follow-up, deliberately not in this PR

The 21 known escapes are recorded, not excused. Each is fixed by serving its probe from a double — see packages/plugin-report/src/__tests__/DatasetReportRenderer.test.tsx for the shape — and deleting its line from KNOWN_ESCAPESand from the pin. That is per-file work across 9 packages and belongs in its own cards, not riding on the instrument that found them.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BGMDbrVa8JjZcCQ7DWYH1b

[yinlianghui]

Fixes#6640

Verified on 1836f41f8. Three files: vitest.setup.network-escape-guard.ts (new), scripts/__tests__/network-escape-ledger.test.ts (new, the shrink-only pin), and one import line in vitest.setup.base.ts.

Attribution first, per the triage ruling

A sweep of every project — dom (all 8 shards), dom-heavy, unit, apps/console, each VERDICT command-exit 0 from the shared verify lock — attributes the class to 21 test files across 9 packages: app-shell (8), plugin-detail (4), plugin-kanban (3), and one each in plugin-view, plugin-calendar, plugin-grid, plugin-gantt, plugin-charts, examples/schema-catalog. They reach /api/v1/security/explain, /api/v1/meta/_drafts, /api/v1/meta/object, /api/v1/meta/object/task, /api/v1/ai/conversations and /api/v1/automation/_status. The full table with per-file rows is on the card.

This selects possibility 1, and falsifies possibility 2. Not one of the 21 is a file the four closed siblings fixed. Checked by symptom rather than by issue number: all eight landed doubles are still on main and still working (stubGlobal + unstubAllGlobals present, none appears in the sweep) — DatasetReportRenderer (#5225), DetailView + DetailView.invalidation (#3339), ObjectChart.compareTo (#4106), FlowCanvas + the metadata-admin inspectors (#4688), plus the DatasetWidget / DashboardGridLayout.datasetPath / calendar propsContract siblings. No fix was reverted, so the closed cards are not lying about main and no annotation is owed them.

The sharpest illustration of what is actually broken sits in one directory: #4688 stubbed ActionDefaultInspector, ConditionBuilder, HookDefaultInspector, PageBlockInspector and ViewVariantInspector, while FlowNodeInspector.specKeys and .inactiveRetained — same directory, same mechanism — were simply not in its enumeration. Each fix closed the files someone had listed by hand, and the list is hand-made. That is why a fifth per-package fix is the wrong shape.

Mechanism

happy-dom's default document URL is http://localhost:3000; nothing in this repo configures it. So a DOM-env test rendering a component that reaches one of the roughly 18 apiFetch ?? fetch / globalThis.fetch fallbacks in product code resolves a relative /api/v1/... against a real TCP socket.

Two findings that shaped the instrument

1. The stacks are unattributable, and that — not the noise — is the defect. They arrive as

Error: connect ECONNREFUSED 127.0.0.1:3000
at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1637:16)

with no stderr | FILE > TESTNAME header and no user stack frame, because it is an unhandled socket error raised below the layer Vitest captures per test. Vitest cannot tie it to a file. That is why the class survived four fixes: the output never said who was left.

2. A throwing fetch would never fire. Every escaping call site is const doFetch = apiFetch ?? fetch inside try { ... } catch { } — best-effort by construction, which is exactly why the suite is green while escaping. A rejection raised from inside fetch lands in that same catch and is swallowed, leaving the test green and the guard silent. So the escape is recorded at the call and asserted in afterEach, where no product catch can reach it. Measured: the ablation below fails only because of this choice.

What it does and does not do

It silences nothing — the real request still goes out and the real ECONNREFUSED still prints, because those stacks are the evidence that a test reached for a socket. Beside each one the guard now writes an attributed line naming the owning file, so a bare stack in a truncated log is no longer an unowned red. It skips and quarantines nothing: every test still runs and asserts exactly what it asserted before. KNOWN_ESCAPES is the 21 measured files and may only shrink — a new escape in any other file is red on its first run, which is the structural close of the class.

Written straight to process stderr rather than through console: under happy-dom globalThis.console is the window's virtual console and never reaches the terminal (measured — the line vanished entirely), and process stderr is also the only stream that puts the attribution beside the stack it explains.

Verification

Ablation, on the committed tree: delete one entry from KNOWN_ESCAPES, confirm the mutation landed by blob hash, run, restore, confirm the restored blob is byte-identical to the HEAD blob with git diff HEAD empty. Mutated: Test Files 1 failed, the guard naming file, test and URL.

Green with the guard: the 21 known files (690 tests, 135 attributed lines, 0 guard failures) · unit (808 files, 12572 passed, 9 pre-existing skips) · dom-heavy (34 files, 332 tests) · dom shard 5/16 (89 files, 1516 tests) · dom shard 3/8, the escape-heaviest (179 files, 2275 tests).

type-check:vitest-setup earned its keep twice. It ships no @types/node by design, so the first draft's node:fs / node:path / process / import.meta.dirname uses were five real errors; the guard now declares the one structural type it needs. And re-running the suite after that rewrite caught the second defect: Vite statically rewrites the new URL('.', import.meta.url) pattern at transform time, so the value reaching the run was /@fs/... rather than a real path — every path relative-isation missed and all 21 known escapes failed at once. Derived by string surgery on import.meta.url instead.

Patch round (review follow-up)

The ledger's docstring said it "may only shrink" and nothing made that true — an author meeting the guard's red could go green by adding a line, which is precisely how a burn-down ledger decays into the permanent quarantine it is not supposed to be. KNOWN_ESCAPES is now exported (that export is its only behaviour change) and pinned by scripts/__tests__/network-escape-ledger.test.ts, which reconciles the live set against a pinned literal of the 21 measured paths in both directions:

• a name in the ledger but not the pin ⇒ the ledger grew. Red.
• a name in the pin but not the ledger ⇒ a fix landed and the pin is stale. Red until the pin is updated too, so shrinking is a deliberate two-line change rather than a silent one.

Plus an anchored non-vacuity floor, because both reconciles pass vacuously on two empty collections: the pin must be non-empty, the imported set must be non-empty, and every pinned path must still resolve on disk (so a rename cannot leave the two sides agreeing about files that no longer exist).

Proved by ablation on disk, each leg confirmed by blob hash and restored to a byte-identical blob with git diff HEAD empty:

• add a bogus name to KNOWN_ESCAPES ⇒ Tests 1 failed | 2 passed, "The network-escape ledger GREW, and it may only shrink."
• delete a real name without touching the pin ⇒ Tests 1 failed | 2 passed, "A pinned escape is gone from KNOWN_ESCAPES — which is good news, banked wrong."

Gates on 1836f41f8, each quoting its own verdict line: type-check:vitest-setup exit 0 · type-check:scripts exit 0 (the new import edge from scripts/__tests__ to the root setup file is clean) · check:control-bytes "OK (scanned 5998 tracked text file(s); skipped 85 binary)" · eslint on both changed files exit 0, 0 errors · network-escape-ledger.test.ts + vitest-invocation-guard.test.ts "Test Files 2 passed (2) / Tests 33 passed (33)" · the 21 known files again "Test Files 21 passed (21) / Tests 690 passed (690)", 135 attributed lines, 0 guard failures · check-changeset-presence "No source or published contract of a released package changed in this range, so no changeset is owed."

Declared narrowing

The remaining dom shards were swept for attribution but not re-run against the final commit; CI runs the full farm regardless. Two runs were cut by the container's 10-minute foreground cap and recorded NOT MEASURED, then re-run split rather than quoted.

Follow-up, deliberately not in this PR

The 21 known escapes are recorded, not excused. Each is fixed by serving its probe from a double — see packages/plugin-report/src/__tests__/DatasetReportRenderer.test.tsx for the shape — and deleting its line from KNOWN_ESCAPESand from the pin. That is per-file work across 9 packages and belongs in its own cards, not riding on the instrument that found them.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BGMDbrVa8JjZcCQ7DWYH1b