redweb 0.12.0 → 0.13.0

package/docs/PACKAGED_EXAMPLE_VERIFICATION.md

@@ -0,0 +1,126 @@
+# Packaged-example verification
+
+The installed-example probe now bounds listening, upgrade and action waits,
+owns its socket immediately, and attempts socket closure and application shutdown
+independently. Malformed responses, premature closes, send errors and timeouts
+fail the action with their cause preserved. All action listeners and its timer
+are removed on settlement. Success is printed only after confirmed cleanup.
+The counter's development-route 404 body is consumed as well.
+
+This changes verification tooling, not Redweb's public API or application runtime.
+The original acceptance assertions remain: a production-only counter without
+TypeScript or Zod; chat after explicit application Zod installation; actual chat
+join, sanitized inspection, development revision/JS/CSS resources; exact emitted
+client bytes; and generated page/component/socket-route compilation and tests.
+
+## Isolation and ownership
+
+The verifier copies the existing realtime harness, error normalizer and frozen
+network helper unchanged, alongside the guarded action helper, into a child
+support directory. Its WebSocket dependency is resolved from the installed
+Redweb package and linked only after checking its real path stays inside this
+consumer. The probe additionally checks transport identity. No repository
+dependency is substituted into the package, and the support directory is not
+an ancestor of the probe: it cannot satisfy the probe's absent-TypeScript/Zod
+checks. Each install refreshes the owned transport link; a replaced regular
+file is rejected, not deleted. Client identity is checked before and after
+the complete consumer flow.
+
+Commands reject truncated output. Each probe has a 90-second parent deadline;
+other install/compiler/generated-test commands retain 120 seconds. The existing
+workspace owner supervises processes and removes only its disposable consumer.
+
+## Evidence
+
+`npm run verify:package:examples:coverage` passed **40 tests / five suites** in
+25.259 seconds on Windows / Node 22.21.0. The three-script original-source scope
+is 100%: 178 statements, 44 branches, 20 functions and 150 lines.
+
+Explicit unit fault boundaries cover action protocol/timing, coordinator cleanup,
+preflight and installed dependency resolution/link tampering. The copied entrypoint
+is evaluated unchanged with original-source Istanbul instrumentation. Its private
+VM map joins the report only when that file is explicitly selected by the maintained
+coverage command; it does not enlarge the ordinary library denominator.
+
+No-mock integration uses actual WebSocket peers for success, unrelated frames,
+malformed data, incorrect results, close and silent timeout. A separate installed
+consumer packs the current source, runs real npm installs, HTTP/WebSockets and
+development resources, then compiles and executes all three generated additions.
+The first local installation timed out after certificate-chain verification failed;
+it cleaned up and was not counted as passing. Using Node's supported
+`--use-system-ca` option succeeded without disabling TLS verification.
+
+The senior critic identified two test defects: cleanup could skip server closure,
+and VM coverage could pollute the library denominator. Both were corrected before
+the maintained successful run. CI retains the scoped report for 30 days and
+allows 30 minutes for all bounded install/verification phases.
+
+Source SHA-256 identities:
+
+- `scripts/lib/example-dependency-probe.cjs`: `3a2b575129544e5497f44fd5e0f0ab574bc4da13ed560219b0f8f1d830b49547`
+- `scripts/lib/performProbeAction.js`: `21dbbe345657b528b62464bb6e4ffef0f4ac8fe7be46a0fa3e7805c5ee67fd98`
+- `scripts/lib/verify-example-dependencies.js`: `fd99d93475fcfbf228564b49bf8fd771e76f9f71bc0faa2f26d2b19d8c6fbbab`
+
+Report `coverage/example-dependency-tools/coverage-final.json` SHA-256:
+`51729c6f8604ad0a0b1f4e5c3d71688b75f833d3cb6b78155c7dc769cdc14c17`.
+
+This is not whole-repository 100%, a new one-hour soak, a benchmark waiver or a
+release approval. The full package/regression/hosted outcomes are recorded
+separately as they complete. No publication, deployment or merge is implied.
+
+The full `verify:live-html:package` gate also passed: isolated registry client
+0.2.0, actual counter/chat/reconnect/disconnect browser acceptance, all-four 100%
+emitted runtime and refresh browser coverage, every packaged starter, compiled
+documentation/action/room examples, generated additions and static/JSX export.
+The checked archive SHA-256 was
+`739567465bb18a3bf3df9771c84b57f56f503769527ed9c90d96c59a76cd97c1`;
+its retained browser report is
+`coverage/packed-browser/f91d60fd-dffd-4c6e-806f-c8615ecc687c/`.
+That archive preceded this explanatory document; it is runtime/tool behavior
+evidence, not a byte identity claim about a later documentation-bearing tarball.
+
+## Complete increment checkpoint
+
+The complete local regression of the source set committed in `449a369` and
+`551a905` passed **1,292 tests / 126 suites** in 690.807 seconds, with two
+POSIX-only skips. Generated documentation, example/protocol snapshots and all
+three TypeScript configurations passed. The ordinary coverage map contains
+exactly the unchanged 91 library files: 5,449 statements, 4,046 branches,
+978 functions and 4,468 lines, all 100%. Private probe instrumentation did not
+enter that denominator.
+
+Full map `coverage/coverage-final.json` SHA-256:
+`c21b602f7d66b6105fa53a7ba0a5eb879d4b75e7ee560c8869beebdbee20f051`.
+Inventory `coverage/example-dependency-full-results.json` SHA-256:
+`8e2612d78a30ee3ce3bf28201e222bbfff9da21d599c1bff2556a904fa304a24`.
+
+Sequential clean checks after regression passed on Windows / Node 22.21.0:
+
+- Default socket load: 32 clients, 3,200 messages, 6,486.03 messages/second,
+  p99 7.2315 ms, slow consumer contained.
+- Memory: 500 connections, three trials, 1,881.744 bytes of measured framework
+  metadata per connection against the unchanged 2,048-byte limit.
+- HTML load: 200 expired renders, 110 live clients, 7,501,568-byte heap delta.
+- JSX: 10,000 component rows, 52.5 ms, 0.6 MiB retained.
+- Server-focused recovery: `server-steady-v1`, all 7,400 replies exact,
+  all server phases passing (highest 108.4196% of warm). The retained client
+  diagnostic exceeded 110% in later phases; this is not a client-memory fix.
+- Thirty-second / 16-client soak: 4,368 sent, 4,363 received, five missing,
+  99.88553114% delivery, seven samples, all eight trends passing, final registries
+  zero, final heap 99.909556% of warm, handles 1→2. Not lossless or an hour soak.
+- Production dependency audit: zero reported vulnerabilities, with certificate
+  validation retained through the Windows trusted certificate store.
+
+Recovery report `coverage/server-recovery-package-final-20260831/report.json`
+SHA-256: `071e98324524586cd8c8c50b35b68d5623f2f179e1e436076da62d7031055465`.
+Soak report `coverage/soak-package-final-20260831.json` SHA-256:
+`4bd8bd5e95054da8c27f1236ca42335663fde6e303c3a850db3e4a684079b371`.
+
+The senior critic approved all 18 actual changed remote blobs at `551a905`, with
+no remaining scoped finding. Both [PR CI](https://github.com/lakam99/redweb/actions/runs/33373452034)
+and [push CI](https://github.com/lakam99/redweb/actions/runs/33373448945) passed
+every Node 18/20/22/24 and lifecycle/package/browser job at that head. These are
+implementation-head outcomes, not claims about a later evidence-only commit.
+The npm links and frozen files remain unchanged. The historical room-phase
+failure, unresolved throughput benchmark, remaining private-tool coverage and
+publication/site alignment remain separately recorded release work.

package/docs/POLISH_RELEASE_CHECKPOINT.md

@@ -0,0 +1,91 @@
+# Release-polish checkpoint
+
+This document preserves the historical `3166468` checkpoint, including its failed
+CI result. It is not the current release decision: the server-focused recovery
+gate was subsequently adopted, while the original measurement remains a visible
+non-blocking diagnostic. See [the reviewed recovery policy](SERVER_RECOVERY_CANDIDATE.md)
+and [the current acceptance checklist](AGENT_READY_ACCEPTANCE.md) for later work
+and remaining gates. The historical failure below is not relabelled as resolved.
+
+These are verified checkpoints, not release approval. Redweb's runtime at
+`3166468` was tested with published `redweb-client@0.2.0` on Windows,
+Node 22.21.0 and Chrome 152.0.7977.64. Later candidate-verifier development changes
+private tooling only; it is not claimed covered by these earlier checks.
+
+## Current package and resources
+
+The full clean registry package gate passed: actual counter/chat/dashboard browser
+acceptance, reconnect/disconnect, six starters, executable recipes and source-free
+consumers. It used no client override or consumer link. All 192 original package
+files, 23 harness files and four explicitly external development tools passed
+identity checks.
+
+- Redweb archive SHA-256:
+  `f9bb0230becb7d1ab29e36a24ab9c35362d70e790bff3a9f3b064f9cb9b49439`.
+- Report: `coverage/packed-browser/a03b7840-905c-4718-8f52-701d5fbd955c/report.json`.
+- Report SHA-256:
+  `8c4c051b034998a9ad537c1240600e9b434402a296fd7cdabc69244071a9b0e4`.
+- Frontend run `b71d6f8a-fc4a-4b7f-b61d-207274883b12`: all-four 100% over
+  426 statements, 262 branches, 64 functions and 351 lines.
+- Refresh run `ac9073e4-c2a2-4baa-b6f1-4552a38c526f`: all-four 100% over
+  82 statements, 44 branches, 12 functions and 71 lines; actual bfcache restoration.
+
+After package and site tests terminated, the unchanged resource gates ran
+sequentially without inherited workload or instrumentation overrides:
+
+| Gate | Observed result |
+| --- | --- |
+| Socket load | 32 clients, 3,200 messages; 6,686.50 messages/s, p99 7.233 ms; slow consumer contained |
+| Metadata overhead | Three 500-client trials; 1,880.752 bytes/connection against 2,048 limit |
+| Live HTML load | 200 expired renders, 110 clients; 8,080,280-byte heap delta |
+| JSX rendering | 10,000 component rows in 49.2 ms; 1.3 MiB retained |
+| Production audit | Zero reported vulnerabilities; TLS verification retained |
+
+## Full 60-minute soak
+
+One default run began at 2026-08-31T01:41:14Z. Its original owned terminal session
+completed with exit 0; the resulting file was independently checked against all
+delivery, registry, trend, heap and handle predicates. No competing local
+load/browser/test run was started during the measurement. Runtime source and the
+soak script were unchanged; candidate tooling edits do not enter the soak process.
+
+- 3,600 seconds, 64 clients, 720 samples.
+- 2,104,941 messages sent; 2,104,808 received: **99.9936815% delivery** against
+  the existing 99% requirement. This is not lossless delivery: 133 replies were
+  not received during rotating-connection traffic.
+- Warm heap 11,378,888 bytes; peak 11,918,736; final 11,296,552:
+  **99.276414%** of warm, below 110%.
+- All final client/room/session/in-flight registries empty. All eight resource
+  trend predicates passed. Handles moved from one to two, within the allowed one.
+- Result: `coverage/polish-soak-3166468-20260831.json`, SHA-256
+  `f402a73e26f207fb5e55b53365912169350bba2fad0bb33d4856719db6df49c3`.
+- Script SHA-256:
+  `ce30f8abcda0e018b8c586bd53dba775aebdaaaaf5275aa8bdf2b2f8d9b1d22b`.
+
+## Historical CI failure at `3166468`
+
+At the same `3166468` revision, the
+[push run](https://github.com/lakam99/redweb/actions/runs/33347952379) passed
+all jobs. The [PR run](https://github.com/lakam99/redweb/actions/runs/33347954450)
+passed Node 18/20/24 and lifecycle checks but failed Node 22 recovery. Its unit and
+integration suites passed first: 83 suites, 858 passing tests and five existing
+platform skips, with all-four 100% instrumented-library coverage.
+
+PR storm 3 peaked at **110.111615%**, above the unchanged 110% limit; final heap
+was 98.786034% with empty registries. The push Node 22 peak was 109.607980%.
+Neither final cleanup, the green push run nor the long-soak pass waives this
+failure. No selective rerun occurred. The senior critic independently verified
+the CI and package evidence.
+
+The local documentation site imports the same canonical source at commit
+`6b528f1`: 98 pages, 154 assets, real HTTP/link/download and filesystem-rollback
+checks, six documentation tests with 100% line/branch/function coverage across
+its seven declared modules. Catalogue SHA-256:
+`8b4d805a7f845af30175423eebc4da610e579b9a51a74ccd8e6f56a5e0d4fa73`.
+This is not whole-site coverage or a hosting deployment.
+
+At this checkpoint, the maintainer had authorized development/review of a
+server-focused candidate, not yet its adoption. Its protocol and results required
+separate assessment.
+Redweb publication, released-site alignment, final requirement audit and merge
+remain pending. The original gate and failed results remain intact.

package/docs/PROCESS_CLEANUP_OBSERVATION.md

@@ -0,0 +1,61 @@
+# Starter cleanup: unresolved CI observation
+
+The [Node 20 push job for 08348fb](https://github.com/lakam99/redweb/actions/runs/33403291226/job/99524600675)
+failed the immediate descendant-disappearance assertion in
+`tests/integration/starter-verifier.integration.test.js`: signal zero did not
+throw. Ubuntu 24.04.4 / Node 20.20.2 / npm 10.8.2 reported 1,530 passed,
+one failed and six skipped tests. Its other three matrix jobs passed; the
+separate PR workflow passed completely. Neither result waives this failure.
+
+Independent inspection found that the frozen process-tree helper signals the
+Linux group but awaits only the direct child's exit. The workspace owner also
+waits for that child's close; the descendant has ignored stdio, so this does not
+establish descendant disappearance. Signal zero checks PID existence, and a
+terminated but unreaped process can still exist. That makes an exit/reaping race
+plausible, not proven for this run. A surviving process or reused PID remains
+possible. See the primary [kill semantics](https://man7.org/linux/man-pages/man2/kill.2.html)
+and [wait/reaping semantics](https://man7.org/linux/man-pages/man2/wait.2.html).
+
+The old log lacks process state and start identity. Its fallback sends another
+signal before waiting, so successful fallback is not proof that original cleanup
+alone succeeded. The test now also requires the captured command error to be
+the actual timeout, not merely contain the fixture's output marker.
+
+The diagnostic-enabled ordinary Node 20 CI execution retains the existing immediate assertion,
+two-second command limit and five-second fallback limit. The fixture records
+initial process identities. If an assertion fails, it samples descendant and
+group-leader identity **before the fallback signal**, appends the command
+error/cause and observations to the thrown error, and preserves them if fallback
+also fails. No additional acceptance wait or successful-run retry is added.
+
+A separate Linux-only negative control deliberately puts its owned descendant
+in a different process group. It requires the unchanged immediate assertion to
+fail, verifies that the diagnostic identifies the live escaped process and its
+unchanged start identity, then confirms that the existing fallback terminated it.
+This is not a reproduction of the original failure or permission to accept escape.
+It must fail specifically at the immediate disappearance assertion and must not
+return an aggregate fallback failure. Independent review caught that accepting
+any error would have allowed a failed fallback to masquerade as a passed control.
+Observation-read errors are recorded separately from the original command error;
+a real malformed-file test verifies that they cannot replace the timeout evidence.
+
+The helper retains only PID, state, parent/group/session IDs, process start ticks,
+platform and observation time. It excludes command names, arguments and
+environment. Start ticks remain text, avoiding integer precision loss. Field
+positions follow [proc_pid_stat](https://man7.org/linux/man-pages/man5/proc_pid_stat.5.html).
+Unsupported platforms and failed reads are explicit. A post-assertion snapshot
+is not the process state at the exact failing instant; a later `ENOENT` or a
+passing run is inconclusive. Direct-root exit/signal timestamps are still absent.
+
+Local Windows tests exercise parsing and the real npm descendant workflow, but
+cannot reproduce Linux reaping or validate the native `/proc` branch. The local
+Docker Linux engine was unavailable; it was not started or reconfigured.
+The final Windows run passed 21 tests with the one Linux-only negative control
+skipped (7.439 seconds). Both [PR](https://github.com/lakam99/redweb/actions/runs/33406107275)
+and [push](https://github.com/lakam99/redweb/actions/runs/33406101028) workflows
+for `4fe0145` subsequently passed all jobs. The actual Node 20.20.2 push job
+passed 1,573 tests with seven platform skips in 823.853 seconds, including the
+Linux escaped-child negative control and malformed-observation regression.
+This validates the diagnostic on Linux, not the cause of the original failure.
+Frozen helpers/evaluation evidence, runtime code and acceptance thresholds remain
+unchanged. No cause or fix for the original CI failure is claimed yet.

package/docs/PROCESS_REAPING_VERIFICATION.md

@@ -0,0 +1,30 @@
+# Descendant-reaping test synchronization
+
+PR CI at `d24d734`, [run 33353677136, Node 22 job
+99371666483](https://github.com/lakam99/redweb/actions/runs/33353677136/job/99371666483),
+failed one test: the descendant PID was still addressable immediately after a
+timed-out build returned. The job passed 915 tests, skipped five platform-specific
+cases and failed one; library coverage remained all-four 100%. Its recovery step
+was correctly skipped, not counted as passed. Other matrix and lifecycle jobs passed.
+
+The frozen process helper sends a process-group kill on POSIX and awaits the root
+process exit. That event does not notify the test that every descendant has been
+reaped. Linux's [kill(2)](https://man7.org/linux/man-pages/man2/kill.2.html) and
+[wait(2)](https://man7.org/linux/man-pages/man2/waitpid.2.html) documentation explain
+that an exited process can retain a visible PID until reaping. The failed log
+does not establish whether that PID was running, dying, a zombie, or reused; the
+historical failure is not relabelled as proven harmless.
+
+The three descendant checks now reuse the existing bounded condition observer.
+They require actual `ESRCH` within five seconds, preserve the final strict
+process-existence assertion, and reject every other error. The observer neither
+sends a signal nor treats zombies as absent. A new real-process negative control
+proves a live survivor times out and remains alive until the test's separate
+owner explicitly stops it. Original build/cleanup deadlines and frozen helpers
+are unchanged; outer test deadlines now cover the sum of the existing phases
+plus the bounded observation.
+
+All eight actual-process tests passed locally on Windows/Node 22.21.0 in 4.84
+seconds. Linux verification follows through ordinary CI, not selective retries.
+The senior critic approved the synchronization contract and negative control;
+this is a test correction, not a server recovery-policy or runtime change.

package/docs/PRODUCTION_READINESS.md

@@ -20,6 +20,13 @@ WebSocket provides an ordered byte stream while a connection remains healthy. Re
 ## Roadmap gates
 
 1. **Bounded transport:** pre-upgrade admission, origin policy, rate limits, slow-consumer enforcement, bounded ordered processing, payload limits, and route-level heartbeat.
+
+Heartbeat expiry is deferred to the event-loop check phase before terminating a
+peer, allowing already-dispatched pong handling to win after a server stall; an
+actually silent peer is terminated by the deferred check.
+`timeoutMs` is therefore a liveness threshold subject to event-loop scheduling,
+not a hard wall-clock resource limit. The deferral owns at most one pending check
+per expired connection; bound connections and queues independently.
 2. **Multiplayer grouping:** route-scoped rooms, atomic membership cleanup, bounded session resumption, fixed-step services, and vendor-neutral metrics.
 3. **Horizontal composition:** draining/readiness, adapter lifecycle, loop prevention, bounded validation, placement hooks, and documented partition behavior.
 4. **Protocol and clients:** version negotiation, stable envelopes and error codes, generated client-facing types, binary replication hooks, and operational examples.
@@ -35,11 +42,13 @@ WebSocket provides an ordered byte stream while a connection remains healthy. Re
 - Broadcast serializes once and remains O(n) in selected recipients.
 - Slow clients cannot grow framework-owned memory without bound.
 - A 60-minute soak shows no monotonic growth in timers, listeners, rooms, sessions, or queues.
-- Reconnect storms return retained heap to within 10% of the warmed baseline after expiry and forced collection.
+- The blocking `server-steady-v1` reconnect gate requires every storm to retain at most 110% of the same warmed **server** heap after expiry and forced collection. Exact delivery, empty measured registries, unchanged inputs, complete logs and normal worker cleanup are mandatory. Client heap is reported separately; the original shared-process diagnostic remains visible and non-blocking, without relabelling its failures.
 - Readiness becomes false before draining and shutdown completes within its documented bound.
 
 The independent senior-review gate rejects releases that weaken any invariant, hide ambiguous delivery semantics, add mandatory brokers or identity libraries, or substitute coverage percentages for race, load, soak, and failure evidence.
 
+See [operations verification](MULTIPLAYER_OPERATIONS.md#verification) for the current commands and the distinction between server acceptance and the original diagnostic. These are required gates, not a statement that the current development candidate has passed them; consult the [release checklist](AGENT_READY_ACCEPTANCE.md) for outstanding failures.
+
 ## Horizontal composition contract
 
 - Placement runs before upgrade within the admission timeout. Redirects must use `wss`, contain no credentials or fragment, and may be restricted with `allowedPlacementOrigins`. Plain `ws` placement requires the explicit `allowInsecurePlacement` escape hatch for private development networks.
@@ -65,4 +74,4 @@ The independent senior-review gate rejects releases that weaken any invariant, h
 - Timed-out admission hooks that ignore cancellation retain their reservation until they actually settle, preventing repeated timeout waves from accumulating unbounded application work.
 - Fixed-step services clamp retained lag with `maxRetainedLagMs`; dropped time is observable rather than replayed forever.
 - Session count, ID length, and lifetime are bounded by Redweb. Session `data` is application-owned, so applications must validate and cap its shape and byte size before storing it.
-- Fully enabled idle routes have a 2 KiB framework-metadata budget per connection. Disabled features retain the legacy path and are compared against 0.8 by the performance gate.
+- Fully enabled idle routes have a 2 KiB framework-metadata budget per connection. Disabled features retain the legacy path; the performance gate compares against an explicitly prepared, identified release baseline. Historical 0.8 evidence does not establish performance against a newer baseline.

package/docs/RECOVERY_CLIENT_HEAP.md

@@ -0,0 +1,201 @@
+# Client heap survival investigation — 2026-08-30
+
+Status: surviving code-related structures identified in the instrumented client;
+the original recovery acceptance gate remains open. This follows the
+[deoptimization investigation](RECOVERY_DEOPTIMIZATION.md).
+
+## Predeclared method
+
+One measured run after tests and senior critic preflight:
+
+```sh
+node scripts/diagnostics/recovery-split.cjs client-heap
+```
+
+The existing seven-phase, 7,400-connection split workload is unchanged. Both workers
+retain normal `--expose-gc` flags; no compilation/deoptimization logger or coverage
+is enabled. Only the native `ws` client captures snapshots, through separate RPCs
+after its warm and storm-5 samples have returned. Server and client measurements
+precede capture; the later workload therefore observes the warm snapshot's effects.
+The client still does not import Redweb or redweb-client. No concurrent tests run
+during measurement, and no rerun is selected because its memory result is greener.
+
+[Node's pinned V8 API](https://nodejs.org/download/release/v22.21.0/docs/api/v8.html)
+warns that snapshot generation blocks execution and may need roughly twice the
+heap's memory. Its format is undocumented and version-specific. The analyzer is
+pinned to Node 22.21.0 / V8 12.4.254.21-node.33. Snapshot capture initiates collection;
+[Chrome's snapshot documentation](https://developer.chrome.com/docs/devtools/memory-problems/heap-snapshots)
+distinguishes comparison, containment, shallow sizes and retained sizes. Our
+comparison reports shallow bytes and graph paths, **not** dominators or retained size.
+
+## Capture and analysis safeguards
+
+- Raw snapshots stay in a newly created local temporary directory, outside the
+  repository. They may contain secrets; do not upload or commit them. Unix permissions
+  are restricted to the owner; Windows uses the current user's inherited temporary
+  directory ACL (the Unix mode is not an independent Windows privacy guarantee).
+- Files are opened exclusively before capture and limited to 64 MiB of saved data.
+  Partial/failed captures invalidate the run and cannot be reused. This limit does
+  not bound native generation memory or its pause; the coordinator has a 60-second
+  capture deadline and owns child termination/cleanup.
+- Both captures must have the same worker-generated UUID/PID identity, runtime,
+  ordered phases and verified SHA-256/file lengths. Snapshots are parsed offline,
+  after the workers exit, not inside the measured client.
+- The existing validated graph parser is shared with the earlier marker-based
+  analyzer. Parsing is capped at 250,000 nodes and 1,500,000 edges per snapshot.
+- A single breadth-first search starts at the validated synthetic root, excluding
+  weak and shortcut edges. Paths use only fixed category labels and edge kinds;
+  arbitrary function/property names, node IDs, addresses and contents are withheld.
+  Paths over 32 edges are explicitly truncated; unreachable nodes remain counted.
+  These are shortest paths in the filtered snapshot graph, not unique ownership
+  proofs or a complete interpretation of ephemeron/engine retention semantics.
+- Added, removed and surviving IDs are separated. Survivor bytes/counts before and
+  after are both included, so size/category changes reconcile with gross deltas.
+  The final public comparison is bounded to 1 MiB; errors are redacted. Complete
+  category/cohort/path-status totals are retained; at most 128 detailed path groups
+  are shown, prioritizing added objects then descending shallow bytes. Omitted
+  group counts are explicit. These examples are not representative statistics.
+
+This run can show which code-related objects survive in a snapshot-instrumented
+client. It cannot identify the earlier run's exact surviving compiled versions,
+equate instruction sizes with snapshot self sizes, or explain every byte of the
+original shared-process recovery failure. No code amount is subtracted from heap
+usage to manufacture acceptance.
+
+## Verification before measurement
+
+Sixteen focused unit and real snapshot/process/network tests pass. Native V8
+coverage is 100% statements, branches, functions and lines across all five snapshot
+capture/parser/analysis modules. Real integration tests use no mocks, check exact
+request/reply IDs, exercise two captures in one worker, verify reusable listener
+ports, reject altered identities/versions/lengths/hashes, enforce the capture size
+limit, and preserve an existing file on overwrite attempts. Synthetic graph tests
+cover cycles, weak/shortcut-only reachability, truncated paths and survivor changes.
+The preexisting broader coordinator coverage gaps are not claimed closed by this
+focused result.
+
+## Original run and offline repair
+
+Exactly one workload was run, at tooling commit `4d036b4`, from
+20:37:09.177Z to 20:37:23.539Z. It reached the post-worker-cleanup comparison stage
+after all 7,400 exact acknowledgements and empty client/server registries at every
+sample. All four output logs were complete and empty. Source hashes were checked.
+
+The run nevertheless **exited 1**: the initial detailed comparison was 1,391,590
+bytes, exceeding the 1 MiB output cap. Its original report remains unchanged with
+`deliveryAndCleanupPassed: false`. This is a failed diagnostic, not a release pass.
+
+The correction at `bd68503` bounds detailed examples while preserving complete
+numeric totals. Its new 3,000-path fixture checks omission accounting and output
+size; a real CLI test checks provenance, redacted errors and overwrite refusal.
+The same existing snapshots were reanalyzed offline, without another workload or
+snapshot capture. Native coverage after the correction passed 17 tests and all-four
+100% across the five snapshot modules. The senior critic independently reproduced
+the reanalysis and verified hashes, reconciliation, omission counts and path totals.
+
+Reproduction uses a new output file; it never overwrites the original report:
+
+```sh
+node scripts/diagnostics/HeapCodeComparison.cjs <original-report.json> <private-snapshot-directory> <new-summary.json>
+```
+
+## What survived
+
+The snapshots contain 77,725 then 80,910 nodes: 4,771 added IDs, 1,586 removed IDs,
+and 76,139 surviving IDs. Net snapshot shallow bytes increased by 937,387. The
+complete V8 `code` category increased by 801,792 shallow bytes; it includes several
+different kinds of internal data, not just executable instructions.
+
+| Code-related category | Net shallow bytes |
+| --- | ---: |
+| Remaining unclassified code nodes | +543,408 |
+| Deoptimization data | +113,880 |
+| Relocation information | +91,608 |
+| Bytecode arrays | +19,064 |
+| Generic code objects | +14,520 |
+| Feedback vectors | +9,928 |
+| Constant pools | +7,440 |
+| Feedback cells | +2,184 |
+| Uncompiled data, combined | −240 |
+
+These labels follow fixed tags in the pinned
+[V8 snapshot generator](https://github.com/nodejs/node/blob/v22.21.0/deps/v8/src/profiler/heap-snapshot-generator.cc).
+Unrecognized names remain unclassified. The other major net category was hidden
+runtime data (+122,672 shallow bytes). These are distinct snapshot categories;
+they must not be added to overlapping `getHeapCodeStatistics()` measurements.
+
+There were no WebSocket, Sender, Receiver or Timeout instances in either snapshot.
+All three Socket instances and all 51 HTTPParser instances survived unchanged,
+with no additions. That narrows the evidence away from accumulating connection
+instances in this client; it does not establish that every retained object is benign.
+
+All 33,449 final code nodes are included in path totals: 33,441 have a path from the
+root in the filtered graph; eight surviving nodes (512 shallow bytes) do not.
+No path was depth-truncated. The 2,802 grouped paths yield 128 detailed examples
+and 2,674 explicitly omitted groups. Some examples run through global handles,
+closures and code objects; others include a Socket. A shortest path is neither a
+unique owner nor evidence that such a Socket is a leftover workload connection.
+
+## Observer effects and remaining causal question
+
+| Phase | Server heap bytes | Client heap bytes |
+| --- | ---: | ---: |
+| Preconditioning | 10,176,480 | 6,596,520 |
+| Warm, before first capture | 10,195,968 | 6,567,568 |
+| Storm 1 | 10,480,392 | 7,498,024 |
+| Storm 2 | 10,873,856 | 7,831,056 |
+| Storm 3 | 10,965,904 | 8,014,120 |
+| Storm 4 | 11,055,136 | 8,040,528 |
+| Storm 5, before final capture | 9,925,432 | 8,054,112 |
+
+Client heap growth was 1,486,544 bytes (122.63% of warm), while code/metadata
+statistics grew by 534,410 bytes. Bytecode/metadata statistics changed from
+758,616 to 666,216 after the warm snapshot. These readings are before capture,
+whereas the snapshot inventories are collected during capture, with extra GC and
+diagnostic machinery. The unequal deltas must not be treated as a missing-byte
+equation or used to claim the original unsnapshotted growth is fully explained.
+
+The next useful step requires **no new workload**: attribute the largest added
+code/deoptimization groups to known Node, ws and harness functions through narrowly
+allowlisted structural relationships in these snapshots. Distinguish module/cache
+roots and standard-stream sockets from workload connections. This milestone does
+not identify the exact earlier invalidated versions, prove exclusive retention,
+explain all hidden data, or resolve the original recovery failure or historical
+shutdown timeout. No speculative production optimization or acceptance change was made.
+
+Follow-through: [offline function and root attribution](RECOVERY_CODE_ATTRIBUTION.md)
+now records that analysis of the same snapshots, including persistent function
+identities and all three standard-stream/prototype Socket roles. The original
+capture and verification evidence below remains unchanged.
+
+## Evidence identity
+
+- Original local run: `coverage/recovery-split-f7owK8`.
+- Original report SHA-256: `1b894777de9ec50f53faa7e66f144bfe4feb89793ae1bfe068365000833acbe7`.
+- Warm snapshot: 7,512,482 bytes; SHA-256 `339a0fe74d9bb942c64a5514975b2918376004436125ca8af169ccdc86dfdaa3`.
+- Final snapshot: 7,796,848 bytes; SHA-256 `7e494dbe82222c4045d673d5bd1cf79a953708025219ebb632fcaf0fdb59576d`.
+- Separate offline report: `heap-reanalysis.json`, 88,196 bytes; SHA-256 `f3904afc8ee5786fec862737404f69ba1076cd46c8f828a5d530781c7dc64aa9`.
+- Offline analyzer SHA-256: `afa8981ec976a6a9405207f4297257c518483941c919b2d3f0ffd868b3155392`.
+
+The offline report includes the original report hash, unchanged failure status and
+all analyzer input hashes. Raw snapshots remain private and local; no publication,
+deployment, dependency change, npm-link change or merge occurred.
+
+## Final verification
+
+At implementation commit `bd68503`, the full suite passed **841 tests in 81 suites**
+in 435.006 seconds, including the owned-HTTP-shutdown test. Pretest documentation,
+generated examples/protocol types and all three TypeScript configurations passed.
+The historical shutdown timeout is still unexplained, not waived by this pass.
+
+Instrumented-library coverage remains all-four 100%: 5,445 statements, 4,044 branches
+and 978 functions, none uncovered. The separate untransformed native snapshot-tool
+run passed 17 tests with all-four 100% across `ClientHeapCapture`, `HeapSnapshotGraph`,
+`HeapCodeComparison`, `recovery-heap-graph` and `recovery-heap-summary`, including the
+offline CLI. Broader split-coordinator/worker coverage gaps remain outside that
+five-module claim. No threshold was lowered or uncovered code excluded to obtain it.
+
+- Full-suite JSON: `coverage/client-heap-full-suite.json`; SHA-256
+  `bb49cab38666d8d60c879aa970fcf44df494d7d900d5152548266662eea5d1cc`.
+- Native snapshot-tool coverage JSON: `coverage/client-heap-native/coverage-final.json`;
+  SHA-256 `f90cdb7ce7e02d611f8c88d1fc3e224803f3dc57c51bba184969be880136a886`.