redweb 0.12.0 → 0.13.0

package/docs/SOCKET_CONTRACTS.md

@@ -0,0 +1,39 @@
+# Shared socket contracts
+
+Status: unreleased on `codex/agent-ready`; not part of npm 0.12.0.
+
+A contract declares message payloads once. The same schema supplies runtime validation and inferred TypeScript types for senders and handlers. The URL still selects the route (`/match`), and the envelope's `type` selects an individual handler (`join`, `move`, `resume`). No socket decorators or second action dispatcher are required.
+
+Start with `npx redweb init my-match --template socket` after installing a release containing this feature. During development, use the checked-out CLI or packed artifact instead of the published 0.12.0 command. The complete maintained example lives in [the socket recipe](../recipes/socket/README.md): [contract](../recipes/socket/contract.ts), [handlers](../recipes/socket/handlers.ts), [server](../recipes/socket/app.tsx), and [real-network tests](../recipes/socket/app.test.cjs).
+
+Session ownership is separate from room fan-out. For authenticated group delivery,
+see [room authorization](ROOM_AUTHORIZATION.md) and the complete
+[shared page/private-room example](snippets/room-access.tsx).
+
+## One schema, two sides
+
+Import `defineSocketContract` from `redweb/contract` for a shared module, or from `redweb` in server-only code. The standalone entry does not import the HTTP server or Node socket listener. Browser consumers need a bundler capable of consuming the CommonJS package; this is not a native browser script URL or a React integration.
+
+`defineSocketContract(version, schemas, options?)` accepts an object mapping message names to [Standard Schema v1](https://standardschema.dev/) validators. Zod is used by the starter, but is not a Redweb runtime dependency. Use your existing compatible schema library. The version must match the negotiated protocol version, and `error` is reserved for protocol errors. Contracts support 1–256 types, names up to 256 characters, and versions up to 64 characters.
+
+- `contract.handler(type, callback)` returns a `BaseHandler` subclass accepted by `SocketRoute.handlers`. The callback receives `(socket, payload, message)` after validation. Payload and message types are inferred from the schema output. Register one handler per inbound type; declaring an outbound type does not expose a handler for it.
+- `contract.protocol` supplies the immutable `{ versions: [version] }` route configuration. The route requires negotiation: a browser URL can use `?redwebVersion=1`. Contract handlers refuse a socket negotiated to a different version.
+- `contract.client(socket)` wraps an existing browser or Node WebSocket-like object with `send(data)`. It neither opens the connection nor reconnects it. Wait for the socket to open before sending.
+- `client.send(type, payload, metadata?)` validates and sends a JSON envelope. `client.envelope(...)` validates and returns the envelope without sending it. Senders use schema **input** types; receivers get schema **output** types. Metadata supports the existing `requestId` and `sequence` fields.
+- `client.parse(frame)` decodes and validates a response. It accepts text, byte arrays, ArrayBuffers, or a message event containing them. The result is a type-discriminated message union or protocol error. Catch parse failures in asynchronous message listeners.
+- `contract.send(serverSocket, type, payload, metadata?)` validates server output and uses the existing `sendEvent` transport path, preserving backpressure behavior. Its boolean result means the transport accepted the send, not that a peer received or acknowledged it.
+- `contract.parse(type, unknownPayload)` runs validation directly without sending. It returns inferred output; this method alone does not JSON-serialize its argument.
+
+## Validation and wire behavior
+
+Socket payloads use JSON. Declare ISO strings rather than `Date` objects on the wire, and encode bigint values as strings. Top-level `undefined`, bigint, and cyclic values cannot be sent. JSON conversion occurs before sender validation, so the validator sees the representation that a receiver will actually get.
+
+Sender validation uses an isolated copy. The transmitted payload remains the original JSON input snapshot even if a validator mutates its argument. Receiver validation produces transformed output for the application. Validators execute on both sending and receiving sides; use deterministic validators and avoid side effects such as writing to a database inside a transform.
+
+Validation accepts asynchronous validators and awaits thenable outputs within the same error boundary/deadline. The default `validationTimeoutMs` is 5,000; configure a positive integer no greater than 2,147,483,647. Overdue validation is rejected, including synchronous work that finishes after its deadline. **This does not preempt synchronous JavaScript or cancel a validator's external work.** Validators are trusted application code, not a CPU sandbox. Keep expensive work out of validation and enforce transport payload/queue/rate limits separately.
+
+Invalid inbound payloads never reach the handler callback. The peer receives sanitized `INVALID_PAYLOAD` and closes with code 1008. Validator diagnostics are not exposed because they may contain private data. Unknown inbound handler types retain `UNKNOWN_HANDLER`; incompatible versions are rejected during negotiation. Ordinary uncontracted routes keep their existing behavior.
+
+Invalid output from `contract.send()` rejects locally. If that rejection escapes a handler, it is an application failure (`HANDLER_FAILED`, close 1011), not a client policy violation. Handle intentional application rejections explicitly if you want a recoverable protocol response; schema validation does not replace authentication, authorization, or game rules.
+
+The match recipe uses private, in-memory bearer sessions solely to demonstrate join/move/resume. Read its security, restart, expiry, and scaling boundaries before adapting it.

package/docs/SPLIT_RECOVERY_COVERAGE.md

@@ -0,0 +1,83 @@
+# Authored split-recovery coverage
+
+The maintained `npm run verify:recovery:coverage` gate now includes both original
+split-runner source files, not just the server policy and command wrapper.
+All 161 tests across ten suites passed in 32.290 seconds on Windows Node 22.21.0.
+
+| Authored file | Statements | Branch outcomes | Functions | Lines |
+| --- | ---: | ---: | ---: | ---: |
+| `diagnostics/recovery-split.cjs` | 224 | 96 | 44 | 184 |
+| `diagnostics/recovery-split-worker.cjs` | 101 | 49 | 17 | 84 |
+| `lib/ServerRecoveryCandidate.js` | 68 | 13 | 15 | 61 |
+| `lib/ServerRecoveryPolicy.js` | 60 | 10 | 8 | 55 |
+| `verify-server-recovery.js` | 4 | 2 | 2 | 4 |
+| Total, all 100% | 457 | 170 | 86 | 388 |
+
+Paths in this table are relative to `scripts/`. Report:
+`coverage/server-recovery-acceptance/coverage-final.json`, SHA-256
+`7ed28a1a33d1fdfcb3e7724aabee7a669f0ffca706806e45c5680a2bb9b4fdb4`.
+CI retains this directory after success or failure. No coverage threshold,
+ignored source, workload, sampling or acceptance limit changes.
+
+## What these tests establish
+
+The existing real worker/IPC/socket integration suite runs once.
+It is complemented by explicit process, transport, clock, GC and report-failure
+unit boundaries. Synthetic byte counts are not memory evidence. The VM executes
+the original file at its original filename, validates unchanged source bytes,
+and verifies statement/function/branch maps against both its instrumenter and
+any existing Jest map before merging into the explicitly selected tool scope.
+All 61 functions in the two authored runner files are represented; historical
+converted maps with smaller function denominators are not used as proof.
+
+Tests cover exact batch ordering and delivery reconciliation, request failures,
+deadline/listener cleanup, partial acquisition, late socket acquisition,
+independent worker/output cleanup, snapshot privacy and identity, input changes,
+and combined primary/report/finalization errors. The ten existing worker-error
+units reuse the same boundary helper instead of duplicating VM setup. The
+critic strengthened the finalization error-order oracle and late-acquisition
+cleanup assertions before final verification.
+
+An intermediate 68-test selection passed behavior but failed coverage at
+99.38% statements / 99.31% branches / 100% functions / 99.25% lines. It lacked
+the existing native output-limit path and the instrumented existing worker
+error cases; including those original tests closes the gaps without adding
+another default 7,400-message measurement. The partial report hash is
+`b9ab23a8de56675a48478e4515d98119fe9475d62b5968a7df3e014658145575`.
+
+Snapshot branches in this gate use explicit VM unit boundaries. Actual private
+snapshot capture belongs to separate existing client-heap/recovery-verifier
+integration and full-regression evidence, not this 161-test selection.
+
+The separate uninstrumented server acceptance recorded in
+[failure handling](SPLIT_RECOVERY_ERROR_HANDLING.md) remains the relevant clean
+memory measurement. Completing source coverage does not resolve historical
+throughput, cleanup or original shared-process diagnostic failures.
+
+## Full regression and contrary hosted evidence
+
+The full Windows suite at unchanged commit `df58f94` completed: 1,943 passed,
+five skipped, 175 suites, 1,501.012 seconds. It predates the new boundary tests
+and soak retention changes. Scoped `NODE_OPTIONS=--use-system-ca` enabled the
+system certificate store for npm consumers; TLS verification stayed enabled.
+Library coverage is 5,449 statements / 4,046 branch outcomes / 978 functions /
+4,468 lines, all 100%, not whole-repository coverage.
+
+- Full JSON: `coverage/release-df58f94-tests.json`, SHA-256 `49392363f314cb95e37b0b3adf42ff611af5937d6b8e6a2b8de7a4a4e3c03582`.
+- Map: `coverage/release-df58f94/coverage-final.json`, SHA-256 `9961a216b47d33803286fab9bffe81d7400c0a8f61478459bd437b7b45cbfb82`.
+- Both `019b010` hosted runs passed: PR 33431726293 and push 33431722990.
+- `df58f94` push 33432417846 passed, but PR 33432429300 failed its Node 24 soak delivery assertion. That failure is not superseded by the Windows or push pass; see [soak observation](SOAK_ROTATION_OBSERVATION.md).
+
+No new hour soak, publication, deployment, merge or release approval is claimed.
+
+### Subsequent Linux artifact verification
+
+At `2e6afe9`, PR run 33436490115 completed both the authored recovery coverage
+step and its artifact upload successfully. The downloaded map at
+`coverage/ci-recovery-2e6afe9/coverage-final.json` has SHA-256
+`2647d1734b36ff0384f3d8ee292747a851b946db53d296f17ab9d3a32242d54a`.
+Its exact five-file inventory and serialized statement/function/branch source
+locations match the current authored files. All 457/170/86/388 counters remain
+100%. This is the Linux lifecycle job's Node 22 scope; the full workflow was
+still running when this artifact was inspected. A completed coverage step does
+not certify the unfinished workflow or supersede earlier delivery failures.

package/docs/SPLIT_RECOVERY_ERROR_HANDLING.md

@@ -0,0 +1,67 @@
+# Split recovery: failure-channel corrections
+
+The shared diagnostic/server-acceptance runner now preserves three concrete
+failure boundaries without changing its workload, thresholds or sampling:
+
+- Synchronous native IPC serialization errors use the existing request cleanup
+  closure, removing listeners and cancelling the request deadline immediately.
+- Falsy/non-Error failures are normalized through the existing shared
+  `verificationError` helper before failure tracking and report aggregation.
+  Original Error identity is retained; other values remain available as causes.
+- Worker error replies remain failures for non-Error rejections and Errors with
+  missing/empty stacks. A fixed fallback prevents an empty error field from
+  being interpreted as successful IPC. Private snapshot replies retain their
+  fixed redaction message.
+
+The newly imported helper is included in the measurement fingerprint. No frozen
+evaluation code, process helper, network helper, acceptance limits, socket
+library API or application workload changed.
+
+## Regressions before and after correction
+
+Two real-process tests initially failed in 1.360s. Circular request data left
+one extra listener on each of `message`, `exit` and `error`. An output callback
+throwing `0` rejected with that primitive instead of retaining a persistent
+failure. These checks use actual workers/IPC/output and no mocked transport or
+process APIs; deliberate callbacks supply the failing application boundary.
+
+The separate process/clock/GC unit boundary initially had seven failures and one
+pass in 0.441s: null/undefined crashed error reporting, while other primitives
+and an object produced an undefined error field. Snapshot refusal was already
+correct. The critic then identified two genuine-Error cases (absent/empty stack),
+which failed before the fallback was added (eight passed, two failed, 0.475s).
+Those VM units are not native memory or IPC evidence.
+
+The final selection passed 47 tests in 12.243s across existing split-runner
+unit/native integration tests and the two new error test files. It includes five
+actual early worker-registration failures and verifies normal Error type,
+message/cause, recorded worker exit and both closed pipes. Those assertions
+explicitly reject an unrelated cleanup AggregateError. Existing checks exercise
+actual rooms/sessions, bad replies, unreachable peers, output draining, trace/code
+modes, deadlines, forced cleanup and listener reuse.
+
+The established server policy/coordinator/CLI coverage scope also passed all
+76 tests in 26.638s at all-four 100% before the final missing-stack fallback;
+that fallback is covered by the subsequent 47-test selection. This scope does
+**not** include the full authored coordinator/worker files. The subsequent
+161-test maintained gate closes those source-matched maps at all-four 100%;
+see [authored coverage](SPLIT_RECOVERY_COVERAGE.md) for the exact scope and limits.
+
+## Fresh uninstrumented server acceptance
+
+One final normal `verify:recovery:server` run used the corrected runner/worker:
+
+- All 7,400 exact replies reconciled between server and client.
+- Empty measured registries, identical initial/final input fingerprints, complete
+  logs, and normal zero-status worker exits with both pipes closed; no forced
+  cleanup was required.
+- Server storm peak: 108.18707393318519% of warm heap; final: 97.15476818198938%.
+- Client peak: 112.98160068884602%, retained as a diagnostic, not subject to the
+  server's 110% budget.
+
+Report: `coverage/server-recovery-ipc-fix-20260831/report.json`, SHA-256
+`a8458d98eb90e17d3ee19006938a4efb51e67090b78ebccefd3ce2f13a3cdd48`.
+This is one Windows/Node 22.21.0 result, not cross-platform release acceptance
+or a resolution of the original shared-process failure. Historical throughput,
+cleanup and soak limitations remain unchanged. No publication, deployment or
+merge is claimed.

package/docs/STARTER_COORDINATOR_VERIFICATION.md

@@ -0,0 +1,112 @@
+# Starter coordinator verification
+
+Both starter coverage coordinators now have a maintained direct coverage gate:
+`npm run verify:starter-coordinators:coverage`. This is a private-tool scope, not
+a change to the shipped runtime or a whole-repository coverage claim.
+
+## Corrections
+
+The V8 measurement previously fingerprinted inputs only after testing. It now
+records the generated source/test/configuration inventory before execution and
+requires identical bytes afterward. A real copied-repository regression changes
+a source comment during the generated test command: compilation and all 14 real
+tests pass, but the coordinator rejects the changed input and retains raw output.
+The authored-source coordinator already enforced this correspondence; the same
+native regression now exercises it directly.
+
+Both runners previously wrote their success summary before updating the latest
+index. An index-write failure could therefore leave a successful summary behind
+while the command failed. Shared `finishVerificationSummary` records failure and
+attempts one best-effort rewrite. Recording failures always remain command
+failures, including when the corrective write succeeds. Primary and secondary
+errors remain available; retained-workspace metadata survives repeated aggregation.
+This is not atomic storage: an unwritable filesystem can still leave partial or
+stale artifacts, so a summary alone never overrides a failed command outcome.
+
+Both runners defensively reject an empty template inventory, and measurement also
+rejects an empty source inventory. These are explicit boundary tests, not a claim
+that the current six-template inventory was empty in ordinary execution.
+
+## Tests and ownership
+
+On Windows / Node 22.21.0, 56 tests in three suites pass in 22.027 seconds:
+
+- 47 explicit unit fault cases instrument the exact coordinator source in a VM.
+  Compiler, process, filesystem and collector boundaries are injected here; these
+  cases are not described as mock-free integration.
+- Seven native managed-child/filesystem cases obstruct report paths and exercise
+  actual successful, failed, recoverable-write and persistent-write outcomes.
+- Two native copied-repository cases use the real initializer, compiler, generated
+  HTTP/WebSocket tests and coverage tools to reject source mutation after testing.
+
+The native repository fixture awaits the real private `main` entrypoint, avoiding
+an outer process timeout that could orphan independently owned descendants. Each
+inner command retains its existing deadline. Cleanup uncertainty preserves the
+outer fixture before assertions; normal confirmed cleanup removes owned projects.
+The fixture selects TAP output explicitly and restores the prior environment.
+The ordinary CLI entrypoints remain separately exercised by full starter runs.
+
+CI retains reports for 30 days and gives the scoped tests 90 minutes and the two
+full starter commands 65 minutes. These conservative outer limits cover existing
+failure/cleanup budgets; they do not increase inner command deadlines. Normal
+execution is substantially shorter. No success is inferred from timeout expiry.
+
+## Exact coverage identity
+
+All four metrics are 100% over exactly three files: 180 statements, 34 branches,
+25 functions and 148 lines. The VM maps join coverage only when this private scope
+is explicitly selected; they do not enlarge the normal 91-file library scope.
+
+| File | SHA-256 |
+| --- | --- |
+| `scripts/measure-starter-coverage.js` | `76d475e1f9fa2d3adbdcadd6947d3ed2179646bc0122dad2054a868923d4be3c` |
+| `scripts/verify-starter-source-coverage.js` | `833c7511b3799ac4e9513db5a45584fd3095ad2c1409653e90bc1ed8368d6457` |
+| `scripts/lib/finishVerificationSummary.js` | `ffd7bfa685e5d260ffa176377e1de6adb835244134f0cda290214961f9423b80` |
+
+Report `coverage/starter-coordinators/coverage-final.json` SHA-256:
+`1d5453ad7a2e9ba3450df49aa4fdf4ad65998b72b693eb25b9bda1dfd5a90415`.
+
+The senior critic approved the final source and checked these identities. The
+preceding 1,322-test regression does not include these 56 cases or the ten later
+report-retention cases. Both hosted workflows for `7a25d48` and `1eddee0` passed;
+those earlier results are not assigned to this new source.
+
+## Full starter workflows
+
+Both actual CLI entrypoints completed against the final source above. Measurement
+ran all six applications and 104 tests, retaining `measured` status. Its separate
+V8 function gaps remain realtime 58.33%, chat 59.09% and dashboard 88.70%; the other
+three applications have all-four 100% in that map.
+`coverage/starters/271e9e10-5069-4983-b60f-612d660b04c9/summary.json` SHA-256:
+`0b6507753dc1d49a6c1e99bd59df6cf3000767f3317620307abc351260692159`.
+
+The authored-source gate passed all six applications, 104 tests in each plain and
+instrumented mode, no failures or skips, and all 96 process reports retained.
+All-four 100% covers the unchanged 600 statements, 299 branches, 160 functions and
+472 lines. Raw report/log hashes were checked against each summary entry. This
+uses actual HTTP/WebSockets, files and SQLite, including the one-minute rate
+window in each dashboard mode. The unchanged collector's five tests also pass.
+`coverage/starter-source/900bf78d-3e77-40b4-b645-c6599a7b1728/summary.json` SHA-256:
+`8679e03a06e441403f08bbfca069c3e82b56ec2bfdd9a23f427885b0e820f050`.
+
+Full pretest/generated/type checks pass. The complete root regression selected
+for this increment then passed 1,388 tests across 132 suites in 724.472 seconds,
+with two POSIX-only skips on Windows. Exactly 91 library files retain all-four
+100%: 5,449 statements, 4,046 branches, 978 functions and 4,468 lines. The private
+VM maps did not enlarge that denominator. The subsequent lifecycle-coordinator
+tests were added after selection and are not included in this inventory.
+
+Full report `coverage/coverage-final.json` SHA-256:
+`f9a99527a5d288640750ddab72858dc571e524864d5ed2a4012e34c6ee0df44b`.
+Inventory `coverage/starter-coordinators-full-results.json` SHA-256:
+`a17c022d9c38738bdcbe736496015781abb02a903548e1a52ef27012a1cd7348`.
+
+The critic approved all 13 actual remote changed blobs at `377f029`, including
+the retained full-starter artifacts. Both hosted workflows then passed completely:
+PR `33380771673` and push `33380765217`. Later evidence/implementation heads retain
+their own separate hosted outcomes.
+
+No compiler/runtime behavior, coverage thresholds, frozen evaluation files,
+publication, deployment or performance acceptance changed. V8 compiler-generated
+function gaps remain diagnostic; authored-source coverage is the separate gate.
+The unresolved throughput result in `BENCHMARK_VERIFICATION.md` remains open.

package/docs/STARTER_LIFECYCLE_VERIFICATION.md

@@ -0,0 +1,75 @@
+# Lifecycle coverage must measure actual code
+
+The lifecycle gate previously trusted c8's exit code. A real command with all four
+100% thresholds and an empty source match exits successfully with `{}` coverage:
+c8 compares a nonnumeric empty-map percentage against the thresholds.
+
+The current generated lifecycle application exposed a concrete false-green too:
+all 13 source-free tests passed, c8 exited zero, but its report was empty. The
+generated JavaScript has an external map pointing to TypeScript removed by the
+deployment check. The converter cannot read that original source; c8 catches the
+conversion error and omits the module. This is a verification defect, not a
+demonstrated runtime lifecycle failure. The failed evidence remains under
+`coverage/starter-lifecycle/abb4623b-ed07-47cd-8f02-8a463bd7b788/`.
+
+## Correction and scope
+
+`verify-starter-lifecycle.js` now requires exactly the expected deployed
+`dist/run-app.js` module, nonempty statement/branch/function/line inventories and
+100% in each metric. Empty, wrong-module, extra-module and incomplete maps fail.
+The existing source-free application checks run first, unchanged.
+
+This gate deliberately measures emitted JavaScript, not authored TypeScript.
+Inside its disposable application only, it removes the asserted trailing
+`sourceMappingURL` comment. Every preceding executable byte remains unchanged;
+the original JavaScript, original map and measured JavaScript are retained.
+The measured file must remain byte-identical after testing. Merely moving the map
+was tested and was insufficient: the converter also follows the unchanged comment
+and fails when the map is missing. That failed attempt remains under
+`coverage/starter-lifecycle/15a3915d-8803-46b2-8714-ec07bde0782a/`.
+
+Each run retains raw JSON and successful test output in a unique directory before
+temporary cleanup. It reuses the shared report/workspace owners; no new process
+manager was added. Success output follows confirmed cleanup. Invalid reports or
+recording/cleanup failures remain failures. The separate original-TypeScript
+starter gate is unchanged and is not replaced by this emitted-code measurement.
+
+## Verification
+
+On Windows / Node 22.21.0, `npm run verify:starters:lifecycle:coverage` passes
+26 tests across two suites in 16.827 seconds. Twenty-four explicitly labelled
+unit faults cover orchestration, malformed/empty/incomplete inventories, import
+and CLI entry, LF/CRLF metadata removal, changed executable bytes and cleanup.
+Two no-API-mock integration tests reproduce the actual c8 empty-map success and
+run the complete generated, compiled, source-free lifecycle workflow.
+
+The exact coordinator scope is all-four 100%: 42 statements, six branches,
+four functions and 39 lines. VM maps are merged only into this explicitly selected
+scope, not the normal library denominator. Source SHA-256:
+`0fd8c761f536b818eafcc07a521639216770dc4b8d87a8670cc79cfdbeba3e32`.
+Report `coverage/starter-lifecycle-coordinator/coverage-final.json` SHA-256:
+`adcfe7be6387d8d980262f78a551c07858449b93f8ef62e45b30adfbc6fa12c2`.
+
+The ordinary `npm run verify:starters:lifecycle` CLI also passes after those tests.
+Its 13 real lifecycle cases pass with no skips or failures; the report contains
+exactly one emitted module, 57 statements/lines, 20 branches and four functions,
+all covered. Existing tests use real child processes, HTTP/TCP/WebSockets and
+timers. On Windows, signal events are explicitly emitted by the fixture; Linux
+uses actual OS signals. This local result is not a new Linux execution claim.
+
+Final CLI artifacts: `coverage/starter-lifecycle/d23cbdd7-93d3-4639-bb11-d79721fa4fb0/`.
+
+| Artifact | SHA-256 |
+| --- | --- |
+| `coverage-final.json` | `e87cb491536901d88530db1ee9140c813b6e416ec60d5b26c8170e7ac1fa63d8` |
+| `deployed-run-app.js` | `680c7c29aee7628f578c95df0d58ce7fa34252d9e13660194c5d1ed055bf9c3c` |
+| `deployed-run-app.js.map` | `f42265ab86fcacf880083e9ada2b414fcac70c3bba05753f575a154b359d88ca` |
+| `measured-run-app.js` | `3b06e16afa137a5b55b0d6a2ce95abc4f638e5dead30b1ae0260825ea2ca8f45` |
+| `test-output.txt` | `df897133496bad53d81c4f1e44e09876321584b9eac3749dc70feda1da94ca2e` |
+
+CI allows eight minutes for the scoped tests and five for the ordinary CLI,
+covering existing inner command/cleanup budgets, and retains evidence for 30 days.
+The critic approved the source and verified the metadata-only transformation.
+The previous 1,388-test/132-suite regression does not include these 26 later cases.
+No runtime/compiler changes, threshold relaxation, benchmark waiver, npm
+publication, deployment or new hour-soak result is claimed.

package/docs/STARTER_REPORT_RETENTION.md

@@ -0,0 +1,73 @@
+# Retaining failed starter coverage evidence
+
+The starter coverage measurement and authored-source gate previously copied raw
+reports only after child commands and parsing/collection succeeded. If a child
+wrote coverage and then failed, or its output was malformed, workspace cleanup
+could remove the only raw report. Successful authored runs also discarded the
+individual process maps after combining them. This was an evidence-loss defect,
+not a demonstrated false-green coverage result.
+
+Both runners now create retained application directories before execution and
+reuse `reportCommand` to preserve available raw bytes before parsing or collection.
+The authored gate retains individual maps in `process-reports/`; both runners
+save successful command logs immediately. Missing reports still fail validation,
+and failed commands remain failures even when a report was written.
+
+The shared helper handles a file or directory. A directory destination is first
+reserved with an exclusive creation, preventing `cpSync` from silently merging
+new files into an older report. Primary and copy failures remain visible together.
+Copying is not atomic: partial bytes can survive a failed copy, are not certified
+complete, and cannot be reused as a fresh destination.
+
+## Tests and scope
+
+`npm run verify:reports:coverage` passes 15 tests across two suites in 1.064 seconds
+on Windows / Node 22.21.0. Five explicit fault units complement ten actual managed
+child-process/filesystem cases. They check successful/failed exits, absent reports,
+nested raw directories, malformed bytes retained after parsing failure, exclusive
+destinations and combined failures. The mid-copy unit writes one actual file before
+injecting a copy failure, then proves a second attempt cannot merge into it.
+
+The exact `scripts/lib/reportCommand.js` scope is all-four 100%: 16 statements,
+eight branches, one function and 14 lines. CI allows seven minutes for the summed
+350-second outer failure budgets and retains the coverage report for 30 days.
+This does not claim direct 100% coverage of either entire starter coordinator.
+
+Source SHA-256:
+`65ef5c11a4855b16b3d3277d5a541e88a0edeba96fd12e24efebae30c6ff029c`.
+Report `coverage/command-report/coverage-final.json` SHA-256:
+`1bcc4a8daa5da4f51e2567bfe007f4a1533150067292b315f261d31500dc787a`.
+
+The new directory-retention regression failed in both real child exit modes before
+the helper gained directory support. Both pass after the correction.
+
+## Actual starter runs
+
+The measurement runner completed all six applications, retaining its diagnostic
+status `measured`, not a passing all-code gate. Compiler-generated function gaps
+remain visible: realtime 58.33%, chat 59.09%, dashboard 88.70%; the other three
+applications have all-four 100% in that separate V8 map.
+`coverage/starters/e7da2be3-5366-4a21-8641-2420e7fca1ca/summary.json` SHA-256:
+`ad7b088829ce1e88bfd68194d13900f548d6c42b08a082de9bdd28a9e806ac51`.
+
+The authored-source gate then passed all six applications, 104 real tests in each
+plain/instrumented mode, no failures or skips. Its unchanged authored denominator
+is all-four 100%: 600 statements, 299 branches, 160 functions and 472 lines.
+All 96 individual process maps are retained, matching the per-application reported
+counts (14/15/14/14/24/15 for realtime/chat/site/socket/dashboard/http-ws).
+`coverage/starter-source/ad9c5821-7437-4988-9c62-520d8ccb1a79/summary.json` SHA-256:
+`971d8cd416080019a48bc901a24a19096ee86162aecd93fb61189b1e4043a702`.
+These runs use actual generated applications, HTTP/WebSockets, files and SQLite,
+including the dashboard's real one-minute rate window in each mode.
+
+The unchanged application collector's five tests also pass at all-four 100%.
+Compatibility with the existing client-report path passes 31 selected checks
+across four suites in 4.546 seconds, with all-four 100% for `ClientSourceCoverage`
+and the retention helper. This is not a rerun or resolution of the separate
+standalone client V8 diagnostic.
+
+The critic approved the implementation and partial-copy/exclusive-root tests.
+The preceding 1,322-test full checkpoint in `ACTION_INPUT_VERIFICATION.md` does not
+include the ten added cases in this follow-up. No coverage thresholds,
+compiler/runtime behavior, frozen evaluation files, publication status or
+performance acceptance were changed.

package/docs/VERIFICATION_EVIDENCE.md

@@ -1,5 +1,7 @@
 # 0.9.0 verification evidence
 
+This is historical evidence for the 0.9.0 candidate, not certification of a newer release. Current commands, measurement scopes and unresolved gates are recorded in [operations](MULTIPLAYER_OPERATIONS.md#verification) and the [development release checklist](AGENT_READY_ACCEPTANCE.md).
+
 Release-candidate measurements were taken on Windows x64, Node 22.21.0, and an AMD Ryzen 7 7800X3D. Performance numbers are machine-specific; the scripts and thresholds are the durable contract.
 
 ## Automated correctness