dsh-vision-router 2.2.7 → 2.3.0

package/docs/architecture/2.3.0-reopened-plan.md

@@ -0,0 +1,720 @@
+# DVR 2.3.0 reopened execution plan
+
+Status: **completed through release preparation / publication and main integration pending explicit user decision**.
+
+Branch: `2.3.0`.
+
+Reopen baseline:
+
+- 2.3 branch: `5ef41f2` (`chore(architecture): record remote settings contract and Desktop lineage`)
+- current main: `6ebc30b` (`v2.2.8`)
+- original 2.3 branch point: `74e3f019` (`v2.2.7`)
+
+The earlier version of `2.3.0-final-audit.md` was a **first-pass audit snapshot**. The later review reopened 2.3 after finding a Session correctness hole, unresolved findings and substantial `main`/Desktop evolution.
+
+That reopened work is now complete through R5 and release preparation. The current `2.3.0-final-audit.md` is the authoritative final architecture decision; only explicit main integration and publication remain pending.
+
+## 1. What 2.3.0 is now trying to achieve
+
+2.3.0 is not a large feature release and is not a rewrite of the Vision Router architecture.
+
+Its final architecture objective is:
+
+> **make the current single-owner design safe under composition, current DSH Desktop/Host behavior, long-session edge cases, and future extraction — then remove only the mature-Core/browser glue whose replacement boundary is clearly better than the current one.**
+
+The order matters. Correctness and integration come before further extraction.
+
+The remaining phase has five priorities, in this order:
+
+1. **Integrate the current v2.2.8 / Desktop / DSH 0.2-rc.2 mainline into the 2.3 branch.**
+2. **Close confirmed correctness and lifecycle gaps**, especially Session event-feed overflow and asynchronous Core bootstrap settlement.
+3. **Bring 2.3 compatibility evidence and developer baselines up to the current support reality.**
+4. **Continue mature-Core and browser extraction only at stable ownership seams with measurable structural benefit.**
+5. **Re-run an adversarial final audit on the integrated branch before release/version work begins.**
+
+## 2. Historical accounting: what belongs to which development line
+
+A 2.3 task being "complete" means the final 2.3 branch satisfies its exit contract. It does **not** mean every prerequisite was first authored on the 2.3 branch.
+
+### 2.1 Inherited before the 2.3 branch was cut
+
+The `v2.2.7@74e3f01` branch point already contained substantial Host/Desktop hardening, including:
+
+- official Desktop-origin recognition (`58d2f21`);
+- DSH 0.1.7 Settings/Session/Web lifecycle compatibility;
+- Host-first proxy convergence and scoped proxy ownership;
+- Web capability/authentication boundaries;
+- Session event-feed repair introduced around #527/#533;
+- the original descriptor-safe fetch lifecycle for proxy + pi-ai wrappers (#522);
+- resource-governor, fuzz, property and architecture-closure infrastructure.
+
+These are inherited foundations, not new 2.3 accomplishments.
+
+### 2.2 First-pass 2.3 work that remains valid
+
+The first 2.3 pass added or completed:
+
+- runtime-i18n migration onto the descriptor-safe fetch wrapper lifecycle;
+- full i18n + wire + proxy composition coverage;
+- five explicit runtime composition phases;
+- a branch-local aggregated 2.3 critical architecture gate;
+- removal of the `VisionProviderTransport` process-global/current registry in favor of explicit transport plumbing;
+- compatibility inventory reclassification;
+- explicit public Config composition;
+- extraction of maintenance routes and the desktop screenshot implementation from the mature Core;
+- source ownership for browser maintenance actions with deterministic `client.js` embedding;
+- the explicit Remote Settings product contract: risk confirmation is reminder/acknowledgement only, not authentication.
+
+These changes stay unless the integrated v2.2.8 branch proves a concrete regression.
+
+### 2.3 Mainline work after the branch cut that 2.3 must inherit
+
+`main` continued independently after the 2.3 branch was cut. Current v2.2.8 includes, among other changes:
+
+- shared Desktop/Web client-script carrier ownership (`b1bd5ec` lineage);
+- stale Vision tool-mask release and HMR cleanup (`2c4c57d` lineage);
+- DSH `0.2.0-rc.2` exact compatibility evidence;
+- authenticated Desktop renderer/Host validation and multi-plugin isolation coverage;
+- related Settings/client carrier changes.
+
+A no-commit integration audit of `2.3.0 + origin/main(v2.2.8)` produced **no textual conflicts** and passed the focused integration set **121/121** plus the full suite **1552 tests / 1551 pass / 1 skip / 0 fail**.
+
+That is strong evidence that the lines can converge cleanly, but it is not a substitute for actually merging/reconciling main into the 2.3 branch and rerunning the complete 2.3 gates there.
+
+### 2.4 Historical experimental `composition-hardening-stage1` branch
+
+`feat/composition-hardening-stage1@bfea108` is a historical experiment, not an integration target.
+
+It attempted several ideas later implemented differently in 2.3, including transport-registry removal and a `core-runtime-facade`. Its focused audit currently produces **44 pass / 2 fail** against the architecture contracts because its entry/composition changes were not fully reconciled with the existing P3 closure tests.
+
+The `core-runtime-facade` approach is intentionally **not** adopted by 2.3. It uses `Object.create(core)` to produce a Core-like object with injected runtime behavior. Although convenient, this changes object identity/own-property semantics and adds another implicit facade layer. The explicit transport dependency used by current 2.3 is more verbose but keeps ownership and call-site dependencies visible.
+
+Do not cherry-pick `bfea108` wholesale.
+
+## 3. Reopened finding ledger
+
+This ledger is the checklist that the final 2.3 audit must reconcile. Completing a batch does not implicitly close unrelated findings.
+
+| Finding | State at reopen | 2.3 disposition |
+| --- | --- | --- |
+| runtime-i18n direct `globalThis.fetch` accessor recursion | closed | first-pass 2.3 fix + full wrapper matrix remain required |
+| proxy/pi-ai fetch wrapper composition | closed | inherited #522 lifecycle + expanded 2.3 matrix |
+| `VisionProviderTransport` process-global/current registry | closed | explicit transport plumbing; must not regress |
+| runtime composition ordering hidden in one flat installer chain | closed for 2.3 | five phases + async Core settlement contract; must not regress |
+| Session event-feed pending overflow silently loses repair | **closed** | `669e445` bounded exact-event recovery; gate `36589418063` |
+| Promise-returning Core apply ends schema bootstrap too early | **closed** | `8fee12e` settles bootstrap after async Core apply |
+| v2.2.8/Desktop/rc.2 mainline absent from branch | **closed** | `d7b7415` integrated v2.2.8 mainline |
+| 2.3 aggregate gate behind current rc.2/Desktop evidence | **closed** | reusable rc.2/Desktop evidence in aggregate gate; run `36592304318` |
+| public Host floor still carries 0.1.0-era compatibility | **closed** | R2.2 publishes continuous `0.1.5+` support and removes pre-floor required Host fixtures |
+| default dev DSH dependencies older than active development target | **closed** | root dev dependencies and lockfile pin exact `0.2.0-rc.2` |
+| compatibility inventory evaluated on old branch/support baseline | **closed** | R2.3 retired pre-floor Android/provider/alias paths and finalized retained-seam evidence; aggregate run `36660877636` |
+| `index.js` mature Core still owns non-algorithm product/Web glue | **closed for 2.3 R3 scope** | diagnostics Web ownership extracted; provider-call binding explicitly rejected because it would add an interface without reducing dependency fan-out |
+| `core-primitives.js` large/shared | retained debt | do not split without a stable data-plane owner |
+| current-product browser logic still lives in raw embedded preludes | partial | R4 source modularization over shared carrier |
+| multiple independent browser delivery mechanisms | improved on main | inherit shared `client-script-carrier` in R0; forbid new direct owners |
+| aggregate architecture gate not a protected-main required status | deferred | decide at final integration, not mid-branch |
+| Remote Settings confirmation is not authentication | product decision | **no fix**; reminder-only behavior is intentional |
+| DSH Web activation overlays remain | external Host gap | retain while exact source contract is `shim-required` |
+| Host-first proxy ownership | closed/inherited | preserve; no global dispatcher re-ownership |
+| Web capability boundary/auth inheritance | closed/inherited | preserve; continue closed-world route classification |
+
+The final audit may add findings, but it may not remove an open row merely because the related code was reorganized. A row closes only when its stated exit evidence exists.
+
+## 4. Frozen product and architecture decisions
+
+These decisions remain fixed for the rest of 2.3.0.
+
+### 4.1 Remote Settings is reminder-only
+
+Remote Settings keeps the current product behavior:
+
+- the browser may show a risk confirmation;
+- `acceptedRisk` records acknowledgement of the warning flow;
+- it is **not** a credential, authentication proof, administrator authorization, local-presence proof, challenge response or one-time secret;
+- no 2.3 task adds a hidden second server-side confirmation gate;
+- the actual capability boundary remains the remote mutable-field allow-list plus local-only fields.
+
+The code now carries this product contract explicitly. Do not reinterpret historical `authorize*` RPC/function names as security-auth semantics.
+
+### 4.2 Existing semantic owners stay authoritative
+
+2.3 must not create a second owner for:
+
+| Responsibility | Owner |
+| --- | --- |
+| routing/background authority | `vision-routing-authority.js` |
+| routing evidence | `vision-routing-evidence.js` |
+| planning/scoring | `vision-capability-router.js` |
+| execution order | `vision-execution-order.js` |
+| Session visual state/index | `session-vision-runtime.js` + state/index |
+| managed artifacts | `vision-artifact-store.js` |
+| Router-owned provider HTTP | `vision-provider-transport.js` |
+| Host/product presentation state | server-side presentation/product boundaries |
+| browser rendering | client/presentation layer |
+
+No generic dependency-injection container, current-owner locator or Core-like service facade is introduced to reduce parameter plumbing.
+
+### 4.3 Host-first network behavior remains authoritative
+
+A blank DVR proxy continues to inherit Host/Undici network policy. Explicit `proxy` / `proxyHosts` remain supported Advanced product overrides. 2.3 does not re-own global network dispatch.
+
+### 4.4 Compatibility retirement remains evidence-driven
+
+No shim is removed merely because it is old or aesthetically awkward. The removal condition must be satisfied on the current integrated support matrix, including durable historical/session inputs where applicable.
+
+The DSH Web activation overlays remain while exact supported/rc source contracts classify them as `shim-required`.
+
+### 4.5 DVR 2.3 resets the supported Host floor and the default development Host
+
+This is a deliberate 2.3 minor-release policy change, not an incidental consequence of dependency cleanup.
+
+For DVR `2.3.0`:
+
+- **Minimum supported DSH Host:** `0.1.5` train (earliest admitted release `0.1.5-rc.1`).
+- **Default development Host:** exact `0.2.0-rc.2`.
+- **Unsupported by DVR 2.3:** all DSH Host trains older than `0.1.5`, including the entire `0.1.0-rc.6/rc.7/rc.8` line and the intermediate 0.1.x pre-stable trains previously admitted for older DVR releases.
+- The default development version is pinned exactly; it must not float through a caret range to a different rc without an explicit evidence update.
+- Runtime compatibility remains capability-based. Raising the support floor does not authorize widespread version-string branching.
+
+The policy distinction is intentional:
+
+```text
+public compatibility floor: DSH 0.1.5 train
+ordinary 2.3 development:    0.2.0-rc.2 exact
+older Host archaeology:      not part of the 2.3 supported Host matrix
+```
+
+Dropping an old Host does **not** automatically permit deleting compatibility code that protects durable data produced by older versions. Session logs, replay envelopes, persisted settings and other long-lived inputs are audited by data format/capability, not by the current Host version alone.
+
+The 2.3 release notes, README/Doctor support messaging, peer admission and CI must all converge on this boundary before release.
+
+## 5. Phase R0 — integrate current main before further architecture work
+
+Status: **completed** on `2.3.0`.
+
+Evidence:
+
+- `d7b7415` merged current `origin/main` / v2.2.8 into `2.3.0` with no textual conflicts;
+- `279a3b0` added a manual trigger to the existing rc.2 validation workflow so the exact mainline fixture could be reused on the branch without opening a PR;
+- local integrated branch: `client:check` green, focused Desktop/Session/composition set **121/121**, full suite **1552 tests / 1551 pass / 1 skip / 0 fail**, `pnpm pack` green;
+- `2.3 Critical Architecture Gate` run `36586576101`: success on Node 22, Node 24 and current stable Host;
+- `DSH 0.2.0-rc.2 validation` run `36586632659`: success across Windows/macOS/Linux exact-source evidence, real Host + Chromium, Windows Desktop Host Node 22/24, Node 24 multi-plugin adversary and real macOS/Windows Desktop renderer lifecycle.
+
+R0 is closed. R1 correctness work is now permitted.
+
+### R0.1 Merge/reconcile `origin/main` v2.2.8 into `2.3.0`
+
+Bring the 22 main-only commits into the 2.3 branch before making further 2.3 architecture changes.
+
+Required retained mainline behavior includes:
+
+- shared `client-script-carrier` ownership;
+- Desktop structured carrier + Web HTML carrier coexistence;
+- stale tool-mask/HMR cleanup;
+- DSH 0.2.0-rc.2 evidence and fixtures;
+- Desktop authenticated runtime coverage;
+- current support-window documentation.
+
+Do not resolve apparent overlap by deleting 2.3's explicit source modules or transport plumbing unless a failing contract proves the 2.3 implementation is wrong.
+
+### R0.2 Integration gate
+
+After the merge, run at minimum:
+
+- `pnpm client:check`;
+- full default tests on Node 22 + 24;
+- client-script-carrier and Settings/Desktop tests;
+- Session event-feed tests;
+- fetch wrapper composition tests;
+- architecture closure tests;
+- current stable Host fixture;
+- DSH 0.2.0-rc.2 exact/desktop validation;
+- package smoke.
+
+**Exit condition:** the real `2.3.0` branch, not a temporary merge worktree, contains current main and is green before R1 begins.
+
+## 6. Phase R1 — correctness hardening
+
+Correctness fixes take priority over additional extraction.
+
+### R1.1 Repair Session event-feed overflow without returning to full-history cloning
+
+Status: **completed** by `669e445` (`fix(session): recover bounded event-feed overflow`).
+
+Evidence: the original 257-event reproducer now repairs **257/257** with one exact recovery read; normal 256-event feed uses zero recovery reads; 400-event overflow recovers in capped 32-read batches; transient/unsupported readers retain dirty retry state; Session-focused suite **92/92**; full suite **1560 tests / 1559 pass / 1 skip / 0 fail**; remote gate `36589418063` success. Recovery stores only bounded seq ranges and uses `readSessionEvent()` — it does not return to whole-history cloning.
+
+#### Confirmed defect
+
+`session-vision-index.js` bounds each pending surface-repair map at 256 entries. When a 257th pending repair arrives, the oldest entry is currently deleted permanently.
+
+A current-code reproducer with 257 pending guard-stop events yields:
+
+```text
+events:          257
+repaired:        256
+oldestRepaired:  false
+```
+
+The warning is emitted, but no recovery path restores the dropped repair. This trades bounded memory for silent durable-surface correctness loss.
+
+#### Required design
+
+Do **not** fix this by returning to repeated whole-session clones/snapshots; #527/#533 existed specifically to remove that failure mode.
+
+Preferred recovery model:
+
+```text
+steady state
+  session/event -> bounded pending repair map -> next pre-step repair
+
+on overflow
+  keep bounded fast-path map
+  + mark this Session repair feed as dirty
+  + remember the earliest/affected dropped repair range
+
+next prepareDecision
+  inspect current surface nodes
+  recover missing repair events through Host-owned bounded SessionQuery.readEvent()
+  in bounded batches
+  apply only repairs that are still on the current surface
+  keep dirty state until the affected current surface has been completely reconciled
+  then return to event-feed steady state
+```
+
+The current `createSessionEventReader()` already uses `sessionQuery.readEvent({sessionId, seq})` and does not materialize the entire Session log. Prefer that exact-event capability for overflow healing. A whole-log `readSessionLog()` must not become the normal overflow repair path merely because it is convenient.
+
+If exact-event recovery is unavailable on a compatibility Host, fail visibly and retain dirty/retry state rather than silently clearing the lost-repair condition.
+
+#### Required tests
+
+Cover:
+
+- 257 pending guard repairs: all still-current repairs eventually complete;
+- 257 pending tool-result repairs;
+- dropped events removed from `surface.nodes` are not resurrected;
+- recovery proceeds in bounded batches rather than unbounded allocations/reads;
+- a transient `readEvent()` failure retries later;
+- unsupported exact-event capability never silently marks the dirty repair complete;
+- normal <=256 event-feed steady state performs zero extra SessionQuery reads;
+- replacement events never re-enqueue themselves.
+
+**Exit condition:** bounded memory no longer implies silent loss of a repair still present on the current Session surface.
+
+### R1.2 Make Core schema-bootstrap completion follow the actual Core apply lifetime
+
+Status: **completed** by `8fee12e` (`fix(runtime): settle Core bootstrap after async apply`).
+
+The synchronous Core path remains synchronous, Promise-returning Core apply now keeps the schema-bootstrap window open until settlement, failure closes it exactly once, and post-Core installation follows the same settlement boundary.
+
+#### Original latent gap
+
+`runtime-composition.js` currently accepts a Promise-like return from `core.apply()`, but calls:
+
+```text
+coreVisionSurfaceRuntime.finishSchemaBootstrap()
+```
+
+immediately after invoking `core.apply()`, before a returned Promise settles.
+
+Today the mature Core applies synchronously, so this is not a current production crash. However the composition contract is internally inconsistent: it claims async compatibility while ending the schema-bootstrap window synchronously.
+
+#### Required design
+
+Create one explicit Core-apply settlement path:
+
+- synchronous return: finalize bootstrap exactly where it finalizes today;
+- synchronous throw: close the bootstrap lifecycle and log/rethrow as today;
+- Promise resolve: finalize bootstrap only after Core registration has completed;
+- Promise reject: close the bootstrap lifecycle once, preserve the original rejection and bounded logging;
+- post-Core installers that semantically require completed Core registration must run from the same settlement boundary.
+
+Do not make all composition async solely to solve this. Preserve synchronous return behavior for the current Core.
+
+#### Required tests
+
+Use a stub Core for:
+
+- synchronous success;
+- synchronous throw;
+- delayed Promise success with schema reads before/after settlement;
+- delayed Promise rejection;
+- exactly-once `finishSchemaBootstrap()`;
+- wrapper/maintenance installation ordering relative to settlement.
+
+**Exit condition:** the lifecycle behavior matches the return type the composition already claims to support.
+
+## 7. Phase R2 — support, compatibility and CI convergence
+
+### R2.1 Advance the 2.3 gate to current Host evidence
+
+Status: **completed**.
+
+The aggregate gate now reuses the current rc.2/Desktop workflow rather than copying its fixture. Reusable-workflow concurrency was isolated so the called workflow cannot contend with its caller. Aggregate run `36592304318` completed successfully across Node 22/24, stable Host `0.1.5-rc.3`, rc.2 exact-source on Ubuntu/macOS/Windows, real Host + Chromium, Windows Desktop Node 22/24, macOS Desktop lifecycle and the final `critical-gate`.
+
+The first-pass 2.3 gate only embedded current stable `0.1.5-rc.3`; the completed R2.1 gate also reflects the admitted DSH `0.2.0-rc.2` evidence now present on main.
+
+The final 2.3 aggregate gate should cover:
+
+- Node 22 and Node 24 full regression;
+- current stable `0.1.5-rc.3` exact Host contract;
+- exact DSH `0.2.0-rc.2` contract/browser/Desktop evidence;
+- shared client carrier ownership;
+- fetch composition;
+- Session overflow recovery;
+- architecture closure;
+- security/property fuzz contracts;
+- package/public-entry smoke.
+
+Prefer reusing current mainline workflows/scripts rather than duplicating rc.2 fixture construction inside the 2.3 gate.
+
+### R2.2 Raise the 2.3 Host floor and pin ordinary development to the latest verified Host
+
+Status: **completed**.
+
+Evidence:
+
+- peer admission is train-shaped: `>=0.1.5-rc.1 <0.2.0-0 || >=0.2.0-rc.2 <0.3.0-0`;
+- minimum `0.1.5-rc.1` and current `0.1.5-rc.3` isolated Host contracts are green;
+- ordinary development dependencies and the pnpm lockfile pin exact `0.2.0-rc.2`;
+- minimum-Host Settings persistence runs in its own self-contained fixture rather than borrowing root dependencies;
+- README/Doctor/support-window contracts publish the 0.1.5 train rather than the old jagged 0.1.x list.
+
+Policy is now frozen by §4.5.
+
+R2.2 must change the repository so that:
+
+- public DVR 2.3 Host support starts at the **DSH `0.1.5` train** (earliest admitted release `0.1.5-rc.1`);
+- normal root development dependencies use **exact `0.2.0-rc.2`**;
+- peer admission and public support messaging no longer advertise DSH trains below `0.1.5` for DVR 2.3;
+- the `0.1.0-rc.6/rc.7/rc.8` Host matrix and other pre-`0.1.5` Host compatibility jobs are removed from the 2.3 required compatibility program rather than being preserved as release gates;
+- tests whose only purpose is proving a pre-floor Host implementation may be deleted with their fixture;
+- tests that exercise **durable historical data semantics** must be retained or rewritten against supported Hosts even if the Host that originally produced the data is no longer supported;
+- the exact rc.2 development pin is reproducible and changes only through an explicit Host-evidence update.
+
+The resulting development/support model is:
+
+```text
+minimum supported Host       DSH 0.1.5 train
+ordinary development Host    0.2.0-rc.2 exact
+current forward evidence     0.2.0-rc.2
+pre-0.1.5 Host compatibility unsupported in DVR 2.3
+```
+
+This is an intentional support-floor increase in a minor release. It **does** change the public 2.3 support contract; it must not be disguised as a devDependency-only cleanup.
+
+Required verification:
+
+- a clean `pnpm install --frozen-lockfile && pnpm test` uses the exact rc.2 development dependencies;
+- minimum `0.1.5-rc.1` and current stable `0.1.5-rc.3` Host evidence stay green;
+- exact `0.2.0-rc.2` Host/Desktop evidence stays green;
+- peer-dependency tests assert the new 2.3 floor rather than the old rc.8 floor;
+- Doctor/README/support-window tests report the new minimum;
+- no default or required CI job claims pre-`0.1.5` Hosts are supported.
+
+**Exit condition:** the package, lockfile, CI and support messaging all agree that DVR 2.3 supports the DSH `0.1.5` train plus explicitly verified later trains and develops against exact `0.2.0-rc.2`.
+
+### R2.3 Re-run compatibility retirement against the new `0.1.5` train floor
+
+Status: **completed**.
+
+Completed retirements:
+
+- pre-floor Android/no-batch attachment fallback;
+- legacy DeepSeek provider reconstruction/keep-alive takeover;
+- rc.7-labelled public aliases in favor of capability-named APIs;
+- pre-floor `0.1.5-alpha.2` removed from the normative exact-source support matrix (historical browser surveillance may remain explicitly non-support).
+
+R2.3 is now a real retirement pass, not only a reclassification exercise.
+
+After R2.2 raises the public minimum, rerun every `retain-host-gap` / `product-compat` seam and separate three questions:
+
+1. **Host-version compatibility:** is the seam needed by the supported `0.1.5` train or an explicitly admitted later train?
+2. **Current product compatibility:** is the seam still part of an intentional DVR product contract such as explicit proxy overrides?
+3. **Durable-data compatibility:** can persisted Session/settings/replay data created by older DVR/Host combinations still reach this path on a supported Host?
+
+A seam that exists **only** to keep a pre-`0.1.5` Host running becomes a deletion candidate. It does not need to be preserved as a historical Host fixture.
+
+Do not assume the first-pass 6 + 5 classification remains correct merely because the source files survived the merge.
+
+For every retained seam record:
+
+- minimum `0.1.5-rc.1` and current stable `0.1.5-rc.3` evidence;
+- exact `0.2.0-rc.2` evidence;
+- whether Desktop structured carrier changes the seam;
+- whether rc.2 now owns the capability upstream;
+- durable historical-data constraints independent of Host version;
+- next concrete removal trigger.
+
+For every deleted seam record the proof that no supported Host/current durable-data path still reaches it.
+
+Only then may the compatibility inventory be called final for 2.3.
+
+R2.3 is closed by current-branch evidence:
+
+- exact supported 0.1.x source matrix: run `36659179011` — success;
+- minimum/current Host contract after the retirement pass: run `36660877445` — success;
+- final aggregate architecture/compat gate: run `36660877636` — success across Node 22/24, current `0.1.5-rc.3`, exact `0.2.0-rc.2` source on Ubuntu/macOS/Windows, real Host + Chromium, Windows Desktop Node 22/24, macOS Desktop renderer lifecycle, and final `critical-gate`.
+
+No remaining retained seam is justified only by a pre-`0.1.5` Host. Remaining compatibility debt is current-Host, durable-data, product, or platform compatibility and therefore moves forward explicitly rather than being deleted for version-age alone.
+
+### R2.4 Promote the aggregate gate only after the branch is stable
+
+Final repository-governance inspection does **not** confirm the older assumption that `main` requires `test (22)`, `test (24)` and `current-contract`. The readable active repository ruleset is **Main PR safety**: it requires PR-based integration and resolved review threads, but currently exposes no required status-check rule. The branch-protection endpoint itself is not readable through the GitHub App because it lacks repository-administration permission.
+
+The 2.3 aggregate gate is therefore branch-local evidence, not a GitHub-enforced `main` required check. DVR 2.3 does not mutate repository governance from the development branch.
+
+At explicit integration time, decide separately whether the aggregate architecture/compat gate should become a required `main` status and whether it replaces or supplements other checks. This is a repository-governance action, not something to fake through workflow naming alone.
+
+## 8. Phase R3 — mature-Core extraction, second pass
+
+Status: **completed**.
+
+Evidence:
+
+- `7015c2e` extracted `/_dsh/vision-router/test-connection` and `/_dsh/vision-router/model-capabilities` into `lib/vision-diagnostics-routes.js`, so Core no longer owns those WebServer route registrations;
+- `4317d5f` preserved partial-LLM diagnostics semantics after extraction;
+- exact supported-source contract run `36661996135`: success;
+- current-head DSH Contract run `36662031316`: success;
+- aggregate `2.3 Critical Architecture Gate` run `36662031617`: success across Node 22/24, current stable Host, exact rc.2 source on Ubuntu/macOS/Windows, real Host + Chromium, Windows Desktop Node 22/24, macOS Desktop renderer lifecycle and final `critical-gate`;
+- the secondary provider-call binding candidate was explicitly rejected after dependency review: `index.js` has only three one-line transport-binding closures (four OpenAI call sites, one local call site and one Anthropic call site), while `core-primitives.js` still has twelve real `providerTransport` data-plane references. Moving the three wrappers to a new module would not reduce primitive dependencies or Core fan-out, and would add a new interface solely to hide explicit plumbing.
+
+The first pass proved that extraction is useful when the seam already has a stable owner (`maintenance-routes`, `desktop-screenshot-tool`, `public-config`). The second pass must use stricter acceptance criteria.
+
+### R3.1 Extraction acceptance rule
+
+A candidate moves out of `index.js` only when all are true:
+
+1. it represents one coherent responsibility, not an arbitrary group of lines;
+2. the resulting module has a narrower dependency set than the code had implicitly inside Core;
+3. no module-global/current owner is introduced;
+4. no Core-like facade or generic service locator is introduced;
+5. the move can be behavior-preserving in its own commit;
+6. the extracted contract can be tested directly without reconstructing most of Core;
+7. composition/Core fan-out or product/lifecycle glue is measurably reduced.
+
+If the extracted function needs a large bag of unrelated callbacks just to compile, the seam is not mature enough and remains in Core.
+
+### R3.2 Primary candidate: diagnostics/product Web ownership still inside Core
+
+Status: **completed** by `7015c2e` (`refactor(core): extract vision diagnostics routes`), with `4317d5f` preserving partial-LLM diagnostics behavior.
+
+`index.js` previously directly owned Web registrations for:
+
+- `/_dsh/vision-router/test-connection`;
+- `/_dsh/vision-router/model-capabilities`.
+
+These are product diagnostics/settings support, not visual inference algorithms.
+
+2.3 should attempt to move them behind a narrow diagnostics owner **only if** the service boundary can be expressed cleanly, for example as explicit candidate/catalog/capability probes rather than passing most of Core into a route module.
+
+Success means Core no longer owns WebServer registration for these endpoints.
+
+That condition is now satisfied by `lib/vision-diagnostics-routes.js`. The extracted module receives three coherent diagnostics faces — connection candidates/probes, capability snapshot, and Host ownership state — rather than a Core facade.
+
+Abort the extraction if the route module requires a broad Core facade or a dependency bag that simply reproduces `index.js` coupling elsewhere.
+
+### R3.3 Secondary candidate: provider-call transport binding
+
+Status: **rejected for 2.3 after dependency review**.
+
+Core currently creates local helper closures to attach the explicit `providerTransport` to OpenAI/local/Anthropic calls.
+
+A small typed/narrow provider-call binding module may be worthwhile if it:
+
+- accepts only the explicit transport + concrete call functions;
+- returns only the three transport-bound call operations;
+- does not pretend to be Core;
+- removes repeated transport option plumbing across Core/primitives;
+- preserves direct helper callers without an implicit current transport.
+
+This is explicitly different from the rejected historical `core-runtime-facade` approach.
+
+If the module does not reduce dependency repetition in practice, leave the explicit call-site plumbing as-is.
+
+That is the current result. The proposed module would only relocate three one-line closures. The underlying primitives still need explicit transport data for local/OpenAI/Anthropic and request paths, so the extraction would not eliminate or narrow those dependencies. Explicit plumbing therefore remains preferable to a cosmetic binding layer.
+
+### R3.4 Do not make `core-primitives.js` line count a release criterion
+
+`core-primitives.js` is still large, but 2.3 should not split it solely because it is ~3k lines.
+
+A primitive group moves only when a clear data-plane owner emerges. OCR/image preprocessing/resource-governor code should remain together with its current owner until a move reduces coupling rather than adding interfaces.
+
+**R3 exit condition:** met. Diagnostics/product Web ownership was cleanly extracted and the secondary transport-binding candidate was rejected with dependency evidence. The goal remains architectural clarity, not an arbitrary LOC target.
+
+## 9. Phase R4 — browser/source modularization on top of the shared carrier
+
+Status: **completed**.
+
+Evidence:
+
+- `28cc21f` moved remote Settings risk/reminder behavior into `lib/remote-settings-risk-client-boundary.js`, so queue/Web and queue-to-live lifecycle paths consume one current-product semantic owner instead of maintaining duplicate authorization/reminder code;
+- `3adc254` moved the local `allowRemoteSettings` browser normalization/write behavior into the capability owner in `lib/local-remote-settings-permission.js`, leaving the loader lifecycle bridge to compose owners rather than copy product semantics;
+- `1debee0` renamed the retained loader bridge to `lib/settings-client-loader-lifecycle.js` and capability-named APIs. The historical in-page `data-vision-router-settings-rc8-lifecycle` marker and `__visionRouterSettingsRc8Lifecycle` sentinel are deliberately retained only for mixed-generation/HMR idempotency;
+- DSH Contract run `36672168661`: success;
+- exact supported-source run `36672168695`: success;
+- aggregate `2.3 Critical Architecture Gate` run `36672168927`: success across Node 22/24, current stable Host, exact rc.2 source on Ubuntu/macOS/Windows, real Host + Chromium, Windows Desktop Node 22/24, macOS Desktop renderer lifecycle and final `critical-gate`;
+- the standalone remote-risk `tapIndex()` path is intentionally retained as the queue-stage/served-Web compatibility fallback. Moving that fallback onto the structured Desktop carrier as well was rejected because the queue-to-live lifecycle carrier already covers Desktop/live attachment; duplicating the fallback there would add a second wrapper execution surface without adding product capability.
+
+Main's shared `client-script-carrier` changes the correct direction for browser cleanup.
+
+### R4.1 One delivery mechanism, multiple source owners
+
+Current-product browser code should increasingly follow:
+
+```text
+real source module
+  -> deterministic generated/embedded script
+  -> shared client-script-carrier
+  -> Desktop structured row and/or Web HTML carrier
+```
+
+Do not add new independent `tapIndex()` owners when the shared carrier can carry the same code.
+
+### R4.2 Move current-product logic before legacy compatibility shims
+
+Prioritize source modularization for browser code that represents current product behavior, such as:
+
+- current settings/product actions;
+- current diagnostics/capability presentation;
+- current routing/settings presentation;
+- current model visibility/product presentation.
+
+Legacy Host lifecycle shims may remain `String.raw` while the Host gaps they bridge still exist.
+
+The target is **not** “zero `String.raw` in 2.3”. The target is that new/current product logic has a real source owner and compatibility injection code is visibly separated from it.
+
+### R4.3 Preserve deterministic bundle checks
+
+Any embedded current-product source must have a generation/synchronization check analogous to `client-maintenance-actions.js` so the shipping `client.js` cannot silently diverge from its source owner.
+
+**R4 exit condition:** met. Current remote-risk and local-permission behavior now have real source owners, while the retained loader/fallback shims contain lifecycle/delivery compatibility rather than duplicate product policy. Browser delivery continues to use the shared mainline carrier where it is the correct execution surface; the queue/Web fallback remains separate only where combining it would create duplicate execution.
+
+## 10. Phase R5 — final adversarial audit and release handoff
+
+Status: **completed**.
+
+### Final finding ledger
+
+| Severity | Unresolved |
+| --- | ---: |
+| High | 0 |
+| Medium | 0 |
+
+Closed during R5:
+
+- the frozen Session/Core wiring contract still pointed at the pre-R3 diagnostics owner; `fd97e5e` now forbids Core from regaining that response ownership and verifies the extracted diagnostics module performs the live official-route check;
+- `079781c` pruned retired/unused mature-Core import fan-out found by the final static review;
+- the production ESM cycle audit was made durable in `scripts/esm-cycle-audit.mjs` plus the default test manifest.
+
+### Final evidence
+
+- R5 deep audit run `36673859366`: success;
+  - Architecture Closure Node 22: 132/132;
+  - Architecture Closure Node 24: 132/132;
+  - 166 production ESM modules / 347 static relative edges / 0 cycles;
+  - deterministic and rotating property/adversarial fuzz passed;
+  - quality 12/12;
+  - 100MP stress passed on Ubuntu/macOS/Windows, maximum observed RSS delta 92.5 MiB;
+  - client source sync and package smoke passed.
+- minimum/current Host run `36673859352`: success for `0.1.5-rc.1` and `0.1.5-rc.3`;
+- supported 0.1.x exact-source run `36672168695`: success for `0.1.5-rc.1`, `0.1.5-rc.3` and `0.1.7-rc.2` on Ubuntu/macOS/Windows;
+- aggregate run `36673859774`: success across Node 22/24 full regressions, current Host, exact rc.2 source on three OSes, real Host + Chromium, Windows Desktop Node 22/24, macOS Desktop renderer and final `critical-gate`;
+- immediately before final housekeeping, `main@65415159` is the merge base and `2.3.0` is behind by 0 commits.
+
+### Quantitative closure snapshot
+
+| File | Lines | UTF-8 bytes | Direct local import fan-out |
+| --- | ---: | ---: | ---: |
+| `index.js` | 4,787 | 223,815 | 28 |
+| `lib/core-primitives.js` | 2,935 | 120,717 | 11 |
+| `lib/runtime-composition.js` | 468 | 20,774 | 44 |
+| `lib/client.js` | 4,961 | 261,672 | 0 ESM imports |
+
+The client bundle has 472 bytes of headroom under the existing 262,144-byte single-file review bound. This is recorded as Low retained maintenance debt rather than “solved” by weakening the guard.
+
+The full final audit is `2.3.0-final-audit.md`. It distinguishes inherited hardening, parallel main/Desktop integration, 2.3-authored work and retained debt.
+
+### Release preparation after architecture closure
+
+Status: **preparation completed; integration/publication pending explicit user decision**.
+
+Completed after the green final audit:
+
+- package version `2.3.0`;
+- bilingual changelog and curated release notes;
+- README release/support messaging;
+- release-ready support-policy/Doctor alignment;
+- release workflow fail-closed checks for generated client synchronization and Host support policy;
+- repository-governance review: no branch/ruleset mutation from `2.3.0`.
+
+Still intentionally not performed:
+
+- PR/main integration;
+- `v2.3.0` tag creation;
+- npm publication;
+- GitHub Release/provenance publication.
+
+The release workflow requires the release SHA to be on `main` and manual dispatch requires the exact current `origin/main` HEAD. A tag is therefore a publication action and must not be created merely as branch housekeeping.
+
+No PR is opened merely because this plan exists.
+
+## 11. Revised batch order
+
+| Batch | Work | Nature | Gate before next batch |
+| --- | --- | --- | --- |
+| R0 | merge current `main` / v2.2.8 into `2.3.0` | integration | full + Desktop/rc.2 green |
+| R1.1 | Session feed overflow dirty/recovery path | correctness fix | 257+ regressions + normal feed unchanged |
+| R1.2 | async Core apply/bootstrap settlement | lifecycle correctness | sync + async settlement tests |
+| R2.1 | update 2.3 gate to stable + rc.2/Desktop | CI/support | aggregate gate green |
+| R2.2 | raise minimum Host to the `0.1.5` train + pin dev Host to exact rc.2 | support/developer contract | package/CI/docs agree; stable + rc.2 green |
+| R2.3 | retire pre-floor Host compatibility and re-audit remaining seams | compat deletion/evidence | inventory complete; durable-data paths proven |
+| R3 | second mature-Core extraction pass | behavior-preserving refactor | targeted + full tests |
+| R4 | second browser source modularization pass | behavior-preserving refactor | shared carrier + sync checks green |
+| R5 | final adversarial audit | audit/docs | no unresolved High/Medium blocker |
+| Release | version/changelog/tag/integration | release | separate user decision |
+
+Each behavior fix/refactor gets its own commit. Do not combine Session recovery, mainline integration and Core extraction into one diff.
+
+## 12. What is explicitly not a 2.3 requirement
+
+2.3 does **not** require:
+
+- changing Remote Settings into authenticated authorization;
+- preserving DVR 2.3 Host compatibility with DSH trains older than `0.1.5`;
+- deleting `proxy` / `proxyHosts`;
+- deleting Web activation overlays while current exact Host evidence still requires them;
+- replacing the routing/evidence/planning/execution architecture;
+- splitting all of `core-primitives.js`;
+- eliminating every browser `String.raw` compatibility prelude;
+- physically splitting DSH's single delivered `client.js` bundle if the Host contract still consumes one bundle;
+- adopting the historical `core-runtime-facade` experiment;
+- adding feature work such as PDF/video/CAD/GUI agents.
+
+## 13. Final success definition
+
+2.3.0 is ready to close only when all of the following are true:
+
+1. the branch contains the then-current v2.2.8/main Desktop and rc.2 compatibility line;
+2. Session overflow cannot silently lose a still-current surface repair;
+3. Core schema bootstrap ends according to the actual Core apply settlement contract;
+4. fetch composition remains fully descriptor-safe across i18n/wire/proxy/Host accessors;
+5. no process-global/current provider transport locator returns;
+6. the public 2.3 Host floor is the DSH `0.1.5` train, ordinary development is pinned to exact `0.2.0-rc.2`, and package/lockfile/README/Doctor/CI agree;
+7. the aggregate branch gate covers the new minimum stable Host plus admitted rc/Desktop evidence;
+8. pre-floor Host-only compatibility is retired, while any retained seam has current-Host or durable-data evidence;
+9. the R3/R4 extraction candidates are either cleanly extracted or explicitly rejected with dependency evidence; no extraction is forced merely to reduce LOC;
+10. final full/fuzz/stress/quality/package validation is green;
+11. the final audit has no unresolved High or Medium architecture/correctness blocker;
+12. release/version work has not been conflated with architecture refactoring.
+
+The intended end state is not “many more files”. It is:
+
+```text
+2.2.8 + first-pass 2.3
+  -> integrated current Desktop/Host line
+  -> no known Session/composition correctness hole
+  -> current support evidence and developer baseline
+  -> fewer mature-Core/browser product-glue responsibilities
+  -> explicit remaining compatibility debt
+  -> one trustworthy final gate/audit
+```