redweb 0.12.0 → 0.13.0

package/docs/RECOVERY_CODE_ATTRIBUTION.md

@@ -0,0 +1,174 @@
+# Offline client code attribution
+
+The existing private snapshots show a broader set of compiled code attached to
+**preexisting functions and closures**, not an accumulating collection of detached
+optimized versions. This is a narrower, supported conclusion about this diagnostic
+client; it does not establish the entire cause of the original CI recovery failure.
+
+An independent research agent began without inherited conversation or a proposed
+cause. It subsequently encountered earlier investigation notes in the repository
+and disclosed that exposure. Its structural findings were reproduced by the
+tested offline analyzer and submitted to a separate senior critic.
+
+No new measured workload or capture was performed for this milestone. Both inputs
+are the unchanged Windows/Node 22.21.0, V8 12.4.254.21-node.33 snapshots documented
+in [the capture report](RECOVERY_CLIENT_HEAP.md). The original capture command
+failed its detailed-output size limit; its report and failure remain unchanged.
+The new offline result is not a successful replacement recovery run.
+
+## Function identities, not names
+
+| Observed structure | Warm | Final |
+| --- | ---: | ---: |
+| Code objects with deoptimization data | 96 | 261 |
+| Associated SharedFunctionInfo identities | 95 | 260 |
+| Identities with one such Code object | 94 | 259 |
+| Identities with two such Code objects | 1 | 1 |
+| Code objects referenced by an owning closure's current code field | 96 | 261 |
+| Feedback vectors | 487 | 532 |
+
+The final 261 Code objects comprise 57 surviving and 204 added identities; 39 warm
+Code identities disappeared. All 261 have an owning function identity and a
+matching owning closure already present in the warm snapshot. The only two-code
+group contains exactly the same two Code identities in both snapshots, both
+referenced by current closure fields. There were no unresolved, ambiguous or
+conflicting code/feedback associations in this pair.
+
+"Current" means a `closure.code` reference, **not proof that the code remains valid
+or is executing**. V8 permits attached code to be marked for deoptimization; that
+primitive status is not available in these snapshots. See the pinned
+[JSFunction implementation](https://github.com/nodejs/node/blob/v22.21.0/deps/v8/src/objects/js-function.cc).
+This analysis cannot match the exact invalidated versions in the separate earlier
+logging run to these objects.
+
+| Source of added Code objects | Objects | Code plus instruction-stream shallow bytes |
+| --- | ---: | ---: |
+| Node built-ins | 180 | 299,360 |
+| ws | 22 | 57,296 |
+| Realtime test harness | 2 | 8,112 |
+
+These byte totals describe added Code objects plus their attached streams, not
+exclusively newly allocated nodes: one added Node Code references a surviving
+2,752-byte instruction stream. There are 204 added Code objects but 203 added
+instruction-stream identities.
+
+Of 45 added feedback vectors, 44 belong to Node built-ins (9,744 shallow bytes)
+and one to the snapshot observer (184 bytes). Observer allocations are explicitly
+included, not silently attributed to workload code.
+
+The deduplicated union of Code, instruction streams and immediate deoptimization,
+relocation and source-position metadata grows from 201,752 to 861,664 shallow
+bytes (+659,912). Feedback vectors are excluded from this union. These are
+selected graph-node self-sizes, not exclusive retained sizes, all code-related
+memory, or bytes that can be subtracted from the recovery gate. Per-function
+metadata can overlap; adding those rows would double-count shared objects.
+
+## A concrete persistent path
+
+`ws.initAsClient` has the same single closure and SharedFunctionInfo identity in
+both snapshots. Its baseline code remains in `function_data`; one new
+deoptimization-bearing Code occupies the closure's code field at the final
+capture. That new Code and instruction stream occupy 20,056 shallow bytes, with
+15,304 bytes of associated immediate deoptimization data. There is no collection
+of old detached optimized versions for this function in the final snapshot.
+
+The analyzer finds this unique chain in both snapshots, with all eight node
+identities unchanged:
+
+```text
+process
+  -- property/_events --> events object
+  -- property/message --> worker IPC listener
+  -- internal/context --> listener context
+  -- context/WebSocket --> ws WebSocket constructor
+  -- internal/context --> constructor context
+  -- internal/previous --> enclosing context
+  -- context/initAsClient --> initAsClient closure
+```
+
+The listener is sourced from `recovery-split-worker.cjs`; its context also holds
+the harness's `closeClient` and `waitFor`. Two root-reachable module objects export
+the same WebSocket constructor in each snapshot (`ws/index.js` and
+`ws/lib/websocket.js`). This establishes persistent worker/module reachability,
+not a unique owner or a leftover per-connection closure.
+
+The three unchanged objects named `Socket` are also resolved structurally:
+
+| Role | Shallow bytes | Identifying reference |
+| --- | ---: | --- |
+| Cached stderr stream | 320 | `getStderr` context's `stderr` binding |
+| TLS socket prototype | 56 | `TLSSocket.prototype` |
+| JS stream socket prototype | 24 | `JSStreamSocket.prototype` |
+
+Classification requires the appropriate built-in source and edge structure, not
+the displayed size or constructor name alone. All three retain the same identity
+and role; none is identified as a leftover workload connection. Independent
+inspection also found 50 of the 51 unchanged HTTPParser objects reachable through
+the parser FreeList. One remaining parser's semantic role is unresolved despite
+a path through global handles and a native context. The reusable analyzer does
+not classify HTTPParser ownership.
+
+## Method and limits
+
+`CodeAttribution.cjs` composes the existing validated graph reader. It identifies
+SharedFunctionInfo structurally, follows Code/deoptimization-data associations,
+cross-checks closure ownership and requires reciprocal instruction-stream links.
+Identity groups remain separate even when function names coincide.
+
+It does not assume that a snapshot's numerical hidden edge is a V8 field offset.
+The [pinned snapshot generator](https://github.com/nodejs/node/blob/v22.21.0/deps/v8/src/profiler/heap-snapshot-generator.cc)
+compacts hidden visitor indices. The outer function association is the unique
+direct strong structural SFI reference, not nested inlined-function references
+in the [deoptimization data](https://github.com/nodejs/node/blob/v22.21.0/deps/v8/src/objects/deoptimization-data.h).
+Missing, conflicting, ambiguous and unsupported structures remain explicit.
+
+Inputs retain the paired-process identity, exact runtime, phase, size and SHA-256
+checks. Graphs are capped at 250,000 nodes and 1,500,000 edges; metadata association
+work is capped at 2,000,000. Exceeding a bound fails instead of reporting partial
+success. Detailed output contains at most 128 function groups (135 of 263 groups
+are explicitly omitted here); global counts include every group. Output stays
+within 1 MiB, uses narrow fixed source/function labels, and contains no raw object
+IDs, arbitrary values, absolute source paths or code addresses.
+
+To analyze this pinned capture format locally, without starting the workload:
+
+```powershell
+node scripts/diagnostics/HeapCodeComparison.cjs <original-report.json> <private-snapshot-directory> <new-report.json> attribution
+```
+
+Output creation is exclusive; an existing output is not overwritten. Raw
+snapshots remain private and local.
+
+## Evidence and verification
+
+- Implementation: `8a15569` on `codex/agent-ready`.
+- Original report: `coverage/recovery-split-f7owK8/report.json`; SHA-256 `1b894777de9ec50f53faa7e66f144bfe4feb89793ae1bfe068365000833acbe7`.
+- Separate offline attribution: `coverage/recovery-split-f7owK8/code-attribution.json`, 67,985 bytes; SHA-256 `af299ace748edc2c01eb02d18ab93cb256fc28a5883adb853b03e146e2ef3971`.
+- The attribution report embeds original-report and analyzer hashes. Snapshot identities/hashes remain those in the capture report.
+- Native verification: 29 unit and real-process/socket/snapshot tests passed in 8.304 seconds. All six snapshot modules have 100% statements, branches, functions and lines, with unchanged thresholds and no exclusions added. Integration tests use actual native snapshots, CLI processes and network traffic, without mocks.
+- Native coverage: `coverage/code-attribution-native/coverage-final.json`; SHA-256 `fd9c8b997f5d40e7367d79c4ca793435f93e1594a8f4f91f58c3b09af47e535d`.
+- Full regression at implementation `8a15569`: **853 tests in 82 suites passed** in 434.002 seconds, with a normal exit, pretest/generated-documentation checks and all three TypeScript configurations. The subsequently edited evidence prose is checked separately; no runtime or test inputs changed during the suite.
+- Instrumented-library coverage: 100% across 5,445 statements, 4,044 branches, 978 functions and 4,464 lines. The owned-HTTP-shutdown test passed, without resolving its historical timeout.
+- Full-suite JSON: `coverage/code-attribution-full-suite.json`; SHA-256 `7274abbb5915e7865f5e3082afaa32d9a08a624732e24664f916600876c961bc`.
+- After updating the evidence prose and generated catalogue, pretest/type checks and 30 focused documentation/attribution/graph tests in four suites passed (1.241 seconds for tests).
+
+The senior critic approved the scoped analyzer after a reciprocal-stream
+double-counting risk was fixed and regression-tested, then independently reproduced
+the saved attribution and approved this report's interpretation. This is not approval of
+release acceptance or a claim that broader coordinator/worker coverage is 100%.
+
+## Remaining decision boundary
+
+Existing snapshots answer which functions hold this code and disfavor detached
+version accumulation as the explanation for this captured client. They cannot
+answer whether the attached code is marked for invalidation, prove every retained
+byte benign, or reproduce the original Ubuntu/Node 22.23.2 shared-process failure.
+That original fourth-storm 110.218742% result remains above the unchanged 110%
+limit even though the final storm declined. The historical shutdown timeout also
+remains unexplained.
+
+There is no supported Redweb production fix to apply from these findings alone.
+Closing the original failure requires evidence under its comparable environment
+and protocol, not another aggregate snapshot, code-byte subtraction or repeated
+runs selected for a pass. No production runtime, dependency, npm link, workload,
+acceptance limit, publication, deployment or merge changed in this milestone.

package/docs/RECOVERY_CODE_CENSUS.md

@@ -0,0 +1,158 @@
+# Client code-creation census — 2026-08-30
+
+Status: concrete compilation candidates identified; **original recovery failure
+not resolved**. This follows the [JIT control](RECOVERY_RUNTIME_CONTROLS.md).
+
+## Method and boundaries
+
+One predeclared run, executed once after unit/real-network tests and critic review:
+
+```sh
+node scripts/diagnostics/recovery-split.cjs client-code
+```
+
+The server retains normal flags. Only the client adds `--log-code`,
+`--no-log-source-code`, `--no-log-source-position`, `--no-logfile-per-isolate`
+and `--logfile=-` to `--expose-gc`. Inherited Node options/coverage do not enter
+measured workers. No tests ran concurrently with measurement. Runtime is unchanged:
+Windows, Node 22.21.0, V8 12.4.254.21-node.33, ws 8.21.3.
+
+The pinned V8 [flag definitions](https://github.com/nodejs/node/blob/v22.21.0/deps/v8/src/flags/flag-definitions.h)
+show code logging normally enables source logging; the explicit negative flags
+prevent that. V8's [logger implementation](https://github.com/nodejs/node/blob/v22.21.0/deps/v8/src/logging/log.cc)
+records instruction size, code kind, logger-relative microseconds, function name
+and location. Numeric kinds are interpreted using the exact pinned
+[code-kind enum](https://github.com/nodejs/node/blob/v22.21.0/deps/v8/src/objects/code-kind.h).
+Other V8 versions are rejected by the parser, not silently decoded with this enum.
+
+Two tiny diagnostic functions are first invoked **after** the warm and final
+samples. Their native code-creation records bracket the interval in the same V8
+stream; JavaScript stdout markers are not mixed into it. Both are interpreted
+functions, two instruction bytes each. The parser requires exactly one of each,
+in order, and monotonic code-event timestamps. It rejects missing/repeated/reversed
+boundaries, malformed records, unknown kinds, private detail records and oversized
+or incomplete input. The existing coordinator preserves bounded logs and hashes;
+census failure invalidates the result. Summary names/locations are limited to
+known code sources, with other entries explicitly unclassified.
+
+Logging, native markers and their allocations perturb this run. The census window
+is after-warm-sample to after-final-sample, not precisely the two heap-read
+instants. This is not acceptance-equivalent. Creation events/instruction bytes
+are **not retained objects, retained size, total heap size, or a deoptimization
+diagnosis**. Raw local logs still include addresses, paths and code labels; they
+are not published as sanitized reports. No heap snapshots were taken.
+
+## Results
+
+All 7,400 exact reply IDs were acknowledged. Client tracked connections and server
+client/room/session registries were empty at every sample. Both workers exited.
+All source fingerprints remained unchanged through measurement and were rechecked
+afterward. Every raw log's byte length, completeness and SHA-256 was independently
+verified; reparsing its serialized census reproduced the report exactly.
+
+The log has 4,360 code-creation records: 3,502 through the warm boundary,
+**851 between boundaries**, and seven at/after the final boundary. Native boundary
+timestamps are 2,873,133 and 12,657,842 microseconds. Of the interval events, 843
+are TurboFan (1,620,872 instruction bytes) and eight baseline-tier (9,004 bytes).
+These are cumulative creation sizes, not a memory-retention total.
+
+| Source category | Interval creation events | Cumulative instruction bytes |
+| --- | ---: | ---: |
+| Node core | 653 | 1,170,660 |
+| `ws` | 106 | 293,460 |
+| Load-test harness and worker | 41 | 144,184 |
+| Unclassified | 51 | 21,572 |
+
+Largest named TurboFan groups:
+
+| Function | Source | Events | Cumulative instruction bytes |
+| --- | --- | ---: | ---: |
+| `initAsClient` | `ws/lib/websocket.js:667` | 4 | 71,176 |
+| `ClientRequest` | `node:_http_client:190` | 4 | 67,520 |
+| `Socket._writeGeneric` | `node:net:935` | 5 | 29,520 |
+| `onEvent` | `scripts/realtime-harness.js:13` | 5 | 28,004 |
+| `Socket._destroy` | `node:net:808` | 4 | 27,888 |
+| `parserOnHeadersComplete` | `node:_http_common:74` | 4 | 24,208 |
+
+For `initAsClient`, all four events share one SharedFunctionInfo address but have
+four distinct code addresses and instruction sizes of 16,144 / 18,860 / 17,220 /
+18,952 bytes, at 5,508,294 / 7,818,047 / 9,753,664 / 11,684,671 microseconds.
+That is evidence of distinct optimized versions associated with the same function
+in this run, not just four identical records. It does not say why new versions
+were generated, whether earlier versions survived, or which objects retained them.
+
+### Memory observations (not a gate)
+
+| Phase | Server heap bytes | Client heap bytes | Client code-and-metadata bytes |
+| --- | ---: | ---: | ---: |
+| Preconditioning | 10,190,376 | 7,030,952 | 2,860,536 |
+| Warm | 10,190,592 | 7,005,648 | 2,834,870 |
+| Storm 1 | 10,462,648 | 7,242,200 | 2,986,582 |
+| Storm 2 | 10,791,136 | 7,693,424 | 3,283,972 |
+| Storm 3 | 11,087,200 | 7,816,488 | 3,346,328 |
+| Storm 4 | 10,964,832 | 7,853,856 | 3,355,785 |
+| Storm 5 | 9,910,160 | 7,844,472 | 3,330,512 |
+
+Client warm-to-final heap growth is 838,824 bytes; code-and-metadata growth is
+495,642 bytes. Peak/final heap ratios are 112.10748812957773% and
+111.97353906448055%. Client bytecode-and-metadata rises from 756,440 at warm to
+756,544 at storm 1 and stays there; marker overhead is not subtracted. External
+memory (2,331,012) and array buffers (35,458) remain constant after warm-up.
+Server peak/final ratios are 108.79838973044941% and 97.24812846986711%; its
+bytecode-and-metadata again drops late, from 908,728 to 205,328 bytes. None of these
+overlapping statistics is added to/subtracted from heap to manufacture a pass.
+
+## Evidence and verification
+
+- Tooling commit: `200fb30` on `codex/agent-ready`.
+- UTC run: 2026-08-30 19:46:02.966–19:46:15.721.
+- Local directory: `coverage/recovery-split-4EG5qI` (report, samples and four logs).
+- Report SHA-256: `8cc597cf22bdaef4b6af90943b36a4a541e49af03ec8bc43ef76fc95390c8cdb`.
+- Client stdout: 419,734 bytes; SHA-256 `55a02d595bf57b26e39aac6cc609db49a4062df24f2876b5c2fd9766204709c4`.
+- Other three logs: empty, complete, hashes verified.
+- Parser source SHA-256: `759961f48151f8e74cbc6f9490bec640f9e42508023fa5e4082b866eb9c7acec`.
+
+Fifty-nine focused unit/real-child/real-HTTP-WebSocket tests passed. The new parser
+has **100% statements, branches, functions and lines**, in both Jest and native V8
+coverage. The real-network test exercises logging isolation, boundaries, complete
+hashes, source-text exclusion and listener cleanup. On other V8 versions it checks
+explicit parser rejection, while still exercising traffic and capture; it does
+not claim schema support for those versions.
+
+The final-tree combined three diagnostic scripts remain below the unchanged native
+100% gate: **80% statements/lines, 97.02% branches and 93.54% functions**. That
+coverage command exited nonzero despite all 59 behavior tests passing. The worker
+is 100% statements/lines/functions but 98.14% branches (cleanup-barrier timeout
+uncovered); coordinator CLI/orchestration/error paths remain uncovered. These
+numbers supersede the earlier pre-finalization coverage check. No thresholds or
+exclusions changed.
+
+Full-suite verification passed **813 tests / 77 suites** in 411.353 seconds,
+including pretest/generated-documentation checks and all three TypeScript
+configurations. Instrumented-library coverage is 100% for statements, branches,
+functions and lines (5,445 statements, 4,044 branches and 978 functions, none
+uncovered). This excludes the separately measured diagnostic scripts above.
+Result: `coverage/recovery-code-full-suite.json`, SHA-256
+`562e3d65c12ae5073fa51a5f8cedc25a3e0adf705fb91b22235c0e54b7603999`.
+The previous milestone's 777-pass/one-shutdown-timeout result remains recorded;
+the same test passing now does not explain that failure or waive it as harmless.
+
+The senior critic independently verified source/report/log hashes, serialized
+census reproduction, all phase measurements, grouped events and function identity.
+Both the preflight and findings write-up were approved with no outstanding finding.
+After updating the evidence, generated-documentation and TypeScript checks passed
+again, followed by 63 focused documentation/diagnostic tests across four suites.
+
+## Next causal question
+
+The shortlist is now specific: the HTTP/WebSocket handshake and stream lifecycle,
+plus the load-test event helpers. Investigate why these functions acquire multiple
+optimized versions (deoptimization reasons and dependency invalidation), then
+verify surviving code/feedback objects and retaining paths if needed. Do not
+rewrite Redweb or its client based only on these creation counts: this native
+load generator does not import either runtime. No acceptance workload, warm-up,
+memory limit, production source, dependency, frozen helper, npm link, publication,
+deployment or merge changed. Release gates remain open.
+
+Follow-up: [client deoptimization investigation](RECOVERY_DEOPTIMIZATION.md)
+identifies the observed invalidation mechanism without claiming retained-size proof.

package/docs/RECOVERY_COMPARISON.md

@@ -0,0 +1,103 @@
+# Bounded Ubuntu recovery comparison
+
+Status: the declared pair is complete; acceptance decision pending. No retries,
+new tracing, threshold changes or replacement of the original gate followed.
+
+## Exact execution
+
+[Run 33346305798](https://github.com/lakam99/redweb/actions/runs/33346305798)
+executed revision `41915b0c0ef5906eca851aaef64d80b9c198cd08` once on Ubuntu
+24.04.4, image `20260823.283.1`, kernel `6.17.0-1022-azure`, Node 22.23.2,
+V8 `12.4.254.21-node.56`, systemd `255.4-1ubuntu8.17`. The OS/image match the
+historical failing runner; its kernel was not independently recorded. Hardware
+identity or exclusive underlying hardware is not asserted.
+
+The temporary workflow's real service probes returned exactly 0 and 7 with
+confirmed cleanup before either measured command. It then ran, sequentially:
+
+1. `node --expose-gc scripts/verify-recovery.js` — exit 0, 8.002-second service lifetime.
+2. `node scripts/diagnostics/recovery-split.cjs baseline` — exit 0, 8.068-second service lifetime.
+
+Both services became inactive with zero main/control PIDs and removed cgroups.
+Source fingerprints before and after match, including the diagnostic report's
+own fingerprint. All four installed client bundles match published client 0.2.0.
+No diagnostic/workload/coverage overrides entered the measured environments.
+The comparison used systemd descendant containment and a minimal environment,
+unlike the historical direct-shell runner. Those differences are not concealed.
+
+The temporary trigger was removed after collection. Its implementation remains
+auditable in commit `41915b0`; do not restore it merely to obtain another pass.
+
+## Heap results
+
+Bytes measured after each phase's unchanged settling/collection protocol:
+
+| Phase | Original combined process | Split server | Split load generator |
+| --- | ---: | ---: | ---: |
+| Preconditioning | 10,388,616 | 9,991,120 | 6,410,728 |
+| Warm | 10,379,216 | 10,023,960 | 6,360,512 |
+| Storm 1 | 10,823,136 | 10,303,776 | 6,611,032 |
+| Storm 2 | 11,207,736 | 10,627,552 | 7,000,048 |
+| Storm 3 | 11,390,320 | 10,801,856 | 7,119,072 |
+| Storm 4 | 11,330,136 | 10,875,592 | 7,156,480 |
+| Storm 5 | 10,118,552 | 9,654,040 | 7,194,432 |
+
+The original peaked at **109.741622%** of its fixed warm baseline and finished
+at 97.488596%, satisfying its existing 110% bound in this one run. The isolated
+server peaked at **108.495964%** and finished at 96.309642%. The split load
+generator reached **113.110894%**; this is not a claim that every process satisfied
+110%. Systemd's service-accounting numbers are not substituted for Node's heap
+samples or treated as equivalent process-memory measurements.
+
+Both original and split retained empty server client/room/session registries.
+The original waits for a reply per connection but does not assert each reply's
+payload identity. The split verifier additionally checked **7,400 exact replies**:
+client sent, client received and server received agree at every phase, client
+registries are empty, and all recorded worker output is complete and hash-verified.
+Its successful exit proves its stated delivery/cleanup conditions; the heap
+percentages above were independently calculated from the actual samples.
+
+## Contrary CI evidence remains a failure
+
+The ordinary Node 22 job at prior source head `69ea1fb` also ran during this
+collection, on a separate hosted VM. Its 83 suites passed (854 tests, five
+platform-specific skips), but [job 99349863069](https://github.com/lakam99/redweb/actions/runs/33345905870/job/99349863069)
+failed the original recovery gate: warm 10,395,344 bytes, fourth storm 11,540,472
+bytes (**111.015778%**), final 10,069,496 bytes (96.865443%). Final recovery does
+not erase the failed intermediate limit. The measured production runtime and
+original recovery script did not change between those heads.
+
+The same run's Node 20 core job separately failed the trace-mode diagnostic
+integration test with `write EPIPE` during worker startup. Its cause is not yet
+established; it is neither a demonstrated production socket defect nor a passing
+test. Node 24 and lifecycle/browser/package jobs passed. These results must not
+be condensed into a green cross-runtime release claim.
+
+## Decision and preserved evidence
+
+The bounded comparison supports reviewing a server-focused acceptance protocol,
+not automatically adopting one. The proposed next step is a separately reviewed
+server gate with explicit delivery, cleanup, shutdown and fixed memory budgets,
+while retaining the original combined-process result as visible diagnostic
+evidence. Maintainer approval is required before replacing any existing CI gate.
+Until then the current gate and release blockers remain unchanged, and no merge
+or publication is authorized by this report.
+
+The hosted artifact `bounded-recovery-33346305798` is retained for 30 days. A local
+copy remains under `coverage/bounded-recovery-33346305798`; no snapshots were
+collected or uploaded. Key SHA-256 receipts:
+
+- `recovery-comparison/inputs-before.json` (identical to `inputs-after.json`):
+  `26354cecf712c22a66a91e759b45c939a3a27f456ec9f3e72349eb11b3aeecb4`.
+- `recovery-comparison/original.log`:
+  `af8b438e00ef0e901b4dcb598f942e50ce49c9a3fab021b5f82353ee517fc16f`.
+- `recovery-split-8bVO1w/report.json`:
+  `106dee62dbc0dc8667e57bc07dd653034516ba7dd8927c499fedff5cabc6411b`.
+
+The senior critic independently reproduced the ratios, delivery reconciliation,
+sample/log hashes, input identity and recorded cleanup checks without rerunning
+either workload. That is scoped evidence approval, not merge approval.
+
+The original historical failure and deferred research remain described in
+[the follow-up spike](RECOVERY_FOLLOWUP_SPIKE.md). One successful comparison is
+not repeatability evidence and does not explain the underlying V8 cause.

package/docs/RECOVERY_DEOPTIMIZATION.md

@@ -0,0 +1,169 @@
+# Client deoptimization investigation — 2026-08-30
+
+Status: GC-dependent code invalidation identified in the measured client;
+**original recovery acceptance remains open**.
+This continues the [client compilation census](RECOVERY_CODE_CENSUS.md).
+
+## Predeclared method
+
+One measured run, after tests and senior critic preflight:
+
+```sh
+node scripts/diagnostics/recovery-split.cjs client-deopt
+```
+
+This adds only `--log-deopt` to the earlier client-code mode. The worker source,
+seven phases, 7,400 connections, batch size, settling, explicit collections,
+server policies and original recovery limits remain unchanged. Only the client
+is logged; the server retains normal flags. No concurrent tests or coverage
+instrumentation enter measurement. Source-text logging remains disabled.
+
+The pinned [V8 logger](https://github.com/nodejs/node/blob/v22.21.0/deps/v8/src/logging/log.cc)
+distinguishes `dependency-change` from `deopt-eager` and `deopt-lazy`. A dependency
+invalidation record does not prove an active stack bailed out. The logged code
+address is correlated with earlier creations, following native `code-move` events.
+Unknown moves clear stale destination associations; unmatched events stay counted
+as unmatched. Raw deoptimization locations are not published. Reasons outside a
+small known-label allowlist stay counted as unclassified. Native warm/final
+boundaries determine the interval by log order, not by adjacent JavaScript output.
+Zero record counts in earlier `client-code` logs cannot establish absence of
+deoptimization: those runs did not enable `--log-deopt`. This run cannot
+retroactively identify why every compiled version changed in earlier runs.
+
+The [collector implementation](https://github.com/nodejs/node/blob/v22.21.0/deps/v8/src/heap/mark-compact.cc)
+marks code with the reason `weak objects` when an embedded weak object is unmarked,
+then clears embedded objects from that code. A separate
+[dependency mechanism](https://github.com/nodejs/node/blob/v22.21.0/deps/v8/src/objects/dependent-code.cc)
+uses `code dependencies`. Neither reason identifies a particular retained user
+object. The [deoptimizer](https://github.com/nodejs/node/blob/v22.21.0/deps/v8/src/deoptimizer/deoptimizer.cc)
+routes these invalidation records to the native logger. These details apply to
+the pinned Node 22.21.0 / V8 12.4.254.21-node.33 runtime, not every Node release.
+
+The census does not model code deletion, prove simultaneous code survival, or
+calculate retained size. Deoptimization records report instruction-stream object
+size; creation records report instruction size. Those values are intentionally
+not added, equated or subtracted from the heap measurements.
+
+## Results
+
+The single run acknowledged all 7,400 exact reply IDs and left client tracked
+connections and server clients/rooms/sessions empty at every sample. Both workers
+exited. Source fingerprints, output lengths and hashes were independently
+rechecked; reparsing the serialized census exactly reproduced the report.
+
+Within the native after-warm/after-final window (2,950,836–12,789,228 microseconds),
+V8 logged 856 code creations and **703 deoptimization/invalidation records**:
+
+| Record kind | Reason | Records |
+| --- | --- | ---: |
+| Dependency invalidation | `weak objects` | 698 |
+| Eager bailout | `wrong map` | 4 |
+| Eager bailout | `not a Smi` | 1 |
+
+There were 813 such records over the whole log: 109 before the warm boundary,
+703 in the window and one at/after the final boundary. All interval code addresses
+matched known optimized creations, including through 116 logged code moves;
+there were no unmatched moves or unclassified reason labels. Fifty-three interval
+records have unclassified source/function labels: matching a code address is not
+the same as classifying its printable name. No records were dropped to make the
+named-source totals look complete.
+
+### The handshake function's replacement sequence
+
+`ws.initAsClient` has four optimized code creations for one SharedFunctionInfo
+identity. Each specific code address is subsequently invalidated with the reason
+`weak objects`, before the next version is created:
+
+| Version | Created at (V8 microseconds) | Instruction bytes created | Invalidated at | Reason |
+| --- | ---: | ---: | ---: | --- |
+| 1 | 5,581,865 | 16,212 | 6,867,589 | `weak objects` |
+| 2 | 7,886,535 | 15,612 | 8,876,052 | `weak objects` |
+| 3 | 9,846,472 | 14,576 | 10,821,681 | `weak objects` |
+| 4 | 11,807,985 | 15,228 | 12,784,300 | `weak objects` |
+
+Together with the pinned collector code above, this identifies garbage-collector
+dependency invalidation as the mechanism behind these observed optimized-version
+replacements. It is materially more specific than merely noticing code growth.
+It does **not** identify the precise weak referents, prove which collection was
+forced versus natural, prove simultaneous survival of the versions, or establish
+that all heap growth comes from code. No new GC trace or heap snapshot was taken.
+
+### Heap observations, not an acceptance result
+
+| Phase | Server heap bytes | Client heap bytes | Client code-and-metadata bytes |
+| --- | ---: | ---: | ---: |
+| Preconditioning | 10,174,352 | 7,030,968 | 2,860,489 |
+| Warm | 10,193,960 | 7,005,152 | 2,834,367 |
+| Storm 1 | 10,475,080 | 7,241,416 | 2,985,665 |
+| Storm 2 | 10,859,504 | 7,685,000 | 3,276,065 |
+| Storm 3 | 10,854,912 | 7,800,448 | 3,336,345 |
+| Storm 4 | 11,058,200 | 7,840,416 | 3,346,105 |
+| Storm 5 | 9,818,424 | 7,843,832 | 3,330,883 |
+
+Client heap grew 838,680 bytes and code-and-metadata grew 496,516 bytes after
+warm-up. Peak/final client heap was 111.97233122136393% of warm. Client bytecode
+was 756,440 at warm and 756,544 thereafter; external memory (2,331,012 bytes) and
+array buffers (35,458 bytes) stayed constant after warm-up. Server peak/final
+ratios were 108.47796145953093% and 96.31609305902711%. Logging and the existing
+native boundaries perturb execution: these observations do not replace the
+original shared-process acceptance gate. No statistics were subtracted or limits
+changed to produce a pass.
+
+### Retained evidence
+
+- Tooling commit: `8b4694c`, branch `codex/agent-ready`.
+- UTC run: 2026-08-30 20:15:13.595–20:15:26.483, Windows/Node 22.21.0/ws 8.21.3.
+- Local directory: `coverage/recovery-split-xeBAYE` (report, samples and four logs).
+- Report SHA-256: `fdb0626a8fb87425eb0d9384f74066fe3fbbf045c67a4b02a94bc2012262f6e2`.
+- Client stdout: 521,311 bytes; SHA-256 `bbba488633697b70c7ac35e7c0b1821d1008f542af63005710947244f1732bf8`.
+- Other three logs: empty and complete, hashes verified.
+- Code parser SHA-256: `44dae45083bc6a55eed71cb5840dd6ecca4e2c5a2582b0b90bb35e2908af1d5b`.
+- Deoptimization parser SHA-256: `a244196245fb32c3c4ff30a9d70e15fc20b946910e7012334de0d68af99b465b`.
+
+The raw local logs contain addresses, paths and code labels; they are not public
+sanitized artifacts. The version-controlled report contains selected known-code
+labels and numeric evidence instead.
+
+## Verification
+
+Seventy-nine focused tests across five suites passed before measurement, including
+unit tests and real HTTP/WebSocket/process integration. A separate actual-V8
+fixture deterministically produces a field-dependency invalidation and a wrong-map
+eager bailout. Native intrinsics and forced optimization are **test-only**, never
+part of the measured workload. Other runtime versions still exercise real traffic
+and capture, but explicitly reject the unsupported parser schema.
+
+Both parser modules have 100% statement/branch/function/line coverage in Jest and
+native V8 coverage. Combined diagnostic-tool coverage remains below its unchanged
+100% gate on the final tree: 83.01% statements/lines, 97.64% branches and 94.87% functions. All 79
+behavior tests pass, but that aggregate coverage command correctly exits nonzero.
+The old coordinator CLI/error paths and worker cleanup-barrier timeout remain
+uncovered. No exclusions or weakened thresholds were introduced.
+
+Full-suite verification passed **833 tests / 79 suites** in 418.458 seconds,
+including generated-documentation and all three TypeScript pretest configurations.
+Instrumented-library coverage is 100% statements/branches/functions/lines: 5,445
+statements, 4,044 branches and 978 functions, none uncovered. This library
+denominator does not include the diagnostic-tool gaps above. Saved result:
+`coverage/recovery-deopt-full-suite.json`, SHA-256
+`96ab9e8b4ee219b8682e04229e3843edbd3d133ffadfadccd089f1d1f716411b`.
+The earlier shutdown timeout did not recur, but its historical failure remains
+unexplained; this pass is not proof that it was harmless.
+
+The senior critic approved preflight, independently verified every source/output
+hash, census counts and all four code-address sequences, and approved the report's
+wording and inference limits. There were no outstanding findings. No additional
+measured run or acceptance retry was made.
+After the evidence update, generated-documentation and TypeScript checks passed
+again, followed by 83 focused documentation/diagnostic tests across six suites.
+
+## Remaining causal boundary
+
+We now know why the observed handshake versions are replaced. The next distinct
+question is what remains live after those invalidations: surviving code, feedback
+structures and their retaining paths. That requires retention evidence, not more
+counts of creation or invalidation events. Nothing here justifies a speculative
+Redweb/runtime rewrite, suppressing GC, relaxing the recovery budget, or claiming
+that no leak exists. The client load generator does not import Redweb or
+`redweb-client`. Production/library source, dependencies, npm links, frozen
+helpers, publication, deployment and merge state remain unchanged.