dsh-vision-router 2.2.7 → 2.3.0

package/docs/architecture/2.3.0-final-audit.md

@@ -0,0 +1,279 @@
+# DVR 2.3.0 final architecture audit
+
+> **R5 final decision.** This document replaces the earlier first-pass snapshot that was later superseded by `2.3.0-reopened-plan.md`.
+
+Audited production baseline: `079781cf175308d3f46925c413c1891894d3dec0` — `refactor(core): prune retired import fan-out`.
+
+R5 evidence head: `3bd943915a7fa3ff9bd440b89f9be60318b7614e`. The R5 evidence commits align architecture tests and the temporary deep-audit runner around the audited production baseline.
+
+Post-R5 release-preparation code baseline: `5af60011819a05f9ad7c068e1d798c435e4125b0` — `ci(release): fail closed on generated client and Host policy`. The architecture phase itself remained closed after this point, but the later pre-release bug audit found concrete lifecycle/transport correctness defects that were fixed without changing the established semantic-owner model.
+
+Final pre-release closure was integrated by PR #607/#609 for Session v4 producer-owned message sources and PR #611 for provider-transport propagation, cancellation ownership, Remote Settings RPC isolation, and latest-selection recovery. PR #611 final head `b8bbd8de7658423019dc83090e7c6a15a5b651d4` merged into the final production-code baseline `0c3c08078fd4c744f97560dc4fb6fea7935698f1`.
+
+The release-document reconciliation that follows this code baseline is documentation-only. The eventual `v2.3.0` tag must point to the exact current `main` after that reconciliation; this audit intentionally does not hardcode a self-referential post-documentation merge SHA. There is still **no `v2.3.0` tag, npm 2.3.0 publication, or GitHub Release** at this point.
+
+## 1. Exit decision and finding ledger
+
+| Severity | Unresolved findings |
+| --- | ---: |
+| High | 0 |
+| Medium | 0 |
+
+The reopened 2.3 architecture phase is therefore **complete**.
+
+This is not a claim of complete modularization. It means the R0-R5 architecture findings have been reconciled without creating a second semantic owner, the supported Host window is evidenced, retained compatibility has explicit removal conditions, and the final adversarial/resource/browser/pack gates are green.
+
+Two R5 audit findings were closed during the audit itself:
+
+1. the frozen Architecture Closure matrix still asserted that DeepSeek ownership diagnostics lived in `index.js`, although R3 had intentionally extracted that responsibility to `lib/vision-diagnostics-routes.js`; `fd97e5e` corrected the contract so Core is forbidden from regaining that Web response ownership while the diagnostics owner must continue the live route-availability check;
+2. repository import review found retired/unused mature-Core import fan-out; `079781c` removed those edges without moving runtime authority or behavior.
+
+Post-R5 release-readiness review also closed two non-architecture consistency findings:
+
+1. `cea9ca4` aligned Doctor's human-readable `0.2.0-rc.2` evidence with the actual peer-admitted 0.2.x support boundary, and `75c4973` aligned the previously dormant support-window contract; the contract is now part of the branch-local Node 22/24 critical gate;
+2. `5af6001` made the release workflow independently fail closed on deterministic browser-source synchronization and the Host support-window contract before any tag/npm/GitHub write phase.
+
+A small client-bundle review-margin issue remains **Low retained debt**, not a release-blocking architecture finding: `lib/client.js` is 261,672 bytes against the existing 262,144-byte single-file review bound, leaving 472 bytes. The bound is intentionally not weakened. Future browser growth should prefer further source-owner extraction instead of raising the limit or hiding growth through fragile late minification.
+
+## 2. What 2.3 inherited versus what 2.3 changed
+
+### Inherited hardening
+
+The branch began from the v2.2.7 line with substantial Desktop/Host work already present, including official Desktop origin handling, Settings/Session/Web lifecycle compatibility, Host-first proxy behavior, and earlier Session/fetch repairs.
+
+Those inherited changes are prerequisites, not 2.3-authored accomplishments.
+
+### Parallel main/Desktop work integrated into 2.3
+
+R0 first merged the v2.2.8 mainline. Later, before R4 browser work, the then-current main `65415159` was reconciled with a true dual-parent merge:
+
+- `0f642b92` — `merge: reconcile latest main before R4`.
+
+That integration brought the newer Desktop Settings launcher/onboarding lifecycle into the same ancestry before further browser modularization.
+
+### New 2.3 architecture work
+
+Major 2.3-owned changes include:
+
+- descriptor-safe runtime-i18n fetch wrapping and the complete fetch-composition matrix;
+- explicit five-phase runtime composition;
+- explicit `VisionProviderTransport` plumbing with the process-global registry removed;
+- continuous DSH support policy from the 0.1.5 train plus exact rc.2 development Host pinning;
+- retirement of pre-floor Android/no-batch attachment fallback, legacy DeepSeek provider reconstruction, and rc.7 public archaeology aliases;
+- bounded Session event-feed overflow recovery;
+- async Core bootstrap settlement correctness;
+- public Config, maintenance Web routes and Desktop screenshot-tool extraction;
+- diagnostics Web ownership extraction to `lib/vision-diagnostics-routes.js`;
+- source-owned browser maintenance actions with deterministic generated-bundle checking;
+- source-owned remote Settings risk/reminder behavior and local permission behavior;
+- capability-named Settings loader lifecycle ownership;
+- DSH `ModelDirectory.select()` `RemoteResult` semantics honored by the Vision toggle;
+- durable production ESM-cycle audit.
+
+## 3. Semantic ownership after R5
+
+The established owners remain unchanged:
+
+| 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 | explicit Session runtime/state/index |
+| managed artifacts | `vision-artifact-store.js` |
+| Router-owned provider HTTP | explicit `vision-provider-transport.js` instance |
+| product/Host presentation | server product/presentation boundaries |
+| browser rendering | client/presentation layer |
+
+Final closure tests continue to forbid hidden module-global `current*` semantic owners, unregistered module-level `installed[]` registries and Core-like runtime facades.
+
+The R3 secondary “provider-call transport binding” extraction was deliberately rejected: moving three one-line closures would add an interface without reducing the real transport dependency of the primitives/data plane.
+
+## 4. Composition and mature-Core snapshot
+
+Current production metrics:
+
+| 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 |
+| `entry.js` | 33 | 1,218 | 3 |
+
+`runtime-composition.js` remains the highest-fan-out module because it is the construction root. Its five explicit phases make lifecycle ordering inspectable; fan-out there is not treated as a reason to invent another container/facade.
+
+`index.js` and `core-primitives.js` remain large. R3 intentionally stopped extraction when the next candidate would only move callbacks/dependencies without creating a stable owner.
+
+## 5. Browser/source modularization verdict
+
+R4 moved current Settings product semantics out of compatibility preludes:
+
+- `remote-settings-risk-client-boundary.js` is the single owner for the remote risk/reminder behavior;
+- `local-remote-settings-permission.js` owns the local permission normalization/write behavior;
+- `settings-client-loader-lifecycle.js` owns only the supported Host queue-to-live reattachment lifecycle.
+
+The old rc.8-labelled source/API name is gone. The historical in-page marker/sentinel remains only for mixed-generation/HMR idempotency.
+
+The standalone remote-risk Web `tapIndex()` fallback is intentionally retained. Moving it onto the shared Desktop structured carrier was reviewed and rejected because Desktop/live attachment is already handled by the loader lifecycle; installing the fallback there would create duplicate wrapper execution, not improve ownership.
+
+Likewise, `settings-factory-lifecycle.js` and `settings-client-loader-lifecycle.js` remain separate because they re-arm different responsibilities. Combining them would couple unrelated lifecycle concerns.
+
+## 6. Compatibility retirement verdict
+
+Canonical inventory at R5:
+
+| State | Count |
+| --- | ---: |
+| `retain-host-gap` | 6 |
+| `product-compat` | 4 |
+| `retire-ready` | 0 |
+| `historical-only` | 0 |
+
+Retained Host-gap seams:
+
+- `dsh-contract-compat.js`;
+- `adapter-update-coalescer.js`;
+- `pi-ai-bridge-wire-compat.js`;
+- `settings-client-loader-lifecycle.js`;
+- `legacy-global-proxy-boundary.js`;
+- `legacy-core-vision-policy-bridge.js`.
+
+Retained product/platform/durable-data seams:
+
+- `replay-envelope-v2-compat.js`;
+- `http-compat.js`;
+- `tesseract-exec-compat.js`;
+- `abort-signal-compat.js`.
+
+No remaining seam satisfies its recorded deletion protocol. In particular, durable replay/profile compatibility is not retired merely because the Host support floor moved forward.
+
+The DSH Web activation overlays remain externally blocked on upstream ownership and continue to be classified through exact-source contracts.
+
+Remote Settings remains the frozen product contract: the confirmation is **reminder/acknowledgement only**. `acceptedRisk: true` is not authentication, authorization proof, local-presence proof, a challenge response or a credential.
+
+## 7. Final Host and runtime evidence
+
+### Current/minimum Host
+
+DSH Contract run `36673859352`: **success**.
+
+It validates both:
+
+- minimum supported `0.1.5-rc.1`, including minimum Settings persistence;
+- current stable evidence `0.1.5-rc.3`.
+
+### Exact supported 0.1.x source matrix
+
+Run `36672168695`: **success** across all nine jobs:
+
+- `0.1.5-rc.1` on Ubuntu/macOS/Windows;
+- `0.1.5-rc.3` on Ubuntu/macOS/Windows;
+- `0.1.7-rc.2` on Ubuntu/macOS/Windows.
+
+This run is after the R4 Settings/browser lifecycle changes.
+
+### Node 22 / Node 24 and rc.2 Desktop/Host
+
+Aggregate run `36673859774`: **success**.
+
+On the audited evidence head it covers:
+
+- Node 22 full regression: **1,556 tests / 1,550 pass / 6 skip / 0 fail**;
+- Node 24 full regression: **1,556 tests / 1,550 pass / 6 skip / 0 fail**;
+- current Host contract;
+- exact `0.2.0-rc.2` source on Ubuntu/macOS/Windows;
+- real Host + Chromium;
+- Windows Desktop on Node 22 and Node 24;
+- real macOS Desktop renderer lifecycle;
+- final aggregate `critical-gate`.
+
+Package smoke succeeds. Post-R5 release preparation sets the package identity to `2.3.0`; publication remains separate. Release-ready validation on `5af6001` is aggregate run `36683695105` — **success** across Node 22/24, current Host, rc.2 source/browser/Desktop and final `critical-gate`. The supported 0.1.x exact-source matrix after the support-policy wording fix is run `36682332455` — **success** on `cea9ca4`; the following `75c4973` commit changes only the contract wording itself.
+
+### Final pre-release candidate after #606 / #611
+
+The final integrated candidate was exercised again after the release-blocker audit:
+
+- CI run `36807044745`: Node 22 and Node 24 each **1,569 tests / 1,563 pass / 6 skip / 0 fail**, plus **10/10** backend-runtime-policy tests;
+- Architecture Closure run `36807044583`: **131/131** on Node 22 and **131/131** on Node 24;
+- DSH `0.1.7-rc.2` real Host run `36807044648`: Chromium, Windows Desktop Node 22/24, and macOS Desktop renderer all pass; the first macOS attempt hit an Electron runner startup timeout and the isolated rerun passed, matching a successful local run against the same upstream `477b4f4` source;
+- DSH `0.2.0-rc.2` validation run `36807044773`: exact source Windows/Linux/macOS, real Host + Chromium, Windows Desktop Node 22/24, official peer admission, Host proxy authority, and real macOS Desktop renderer all pass;
+- production ESM graph at release prep: **166 modules / 354 static relative edges / 0 cycles**;
+- exact upstream v4 row-admission assertions cover every DVR-owned durable v4 message source.
+
+These post-R5 fixes close concrete lifecycle and transport regressions while preserving the R5 semantic ownership decisions.
+
+## 8. R5 adversarial, quality and resource evidence
+
+Temporary R5 deep-audit run `36673859366`: **success**.
+
+Architecture Closure:
+
+- Node 22: **132 / 132**;
+- Node 24: **132 / 132**.
+
+Static dependency audit:
+
+- **166** production ESM modules;
+- **347** static relative dependency edges;
+- **0** cycles.
+
+Fuzz evidence:
+
+- deterministic property fuzz: 1,000 cases, seed `1592639710`;
+- deterministic adversarial fuzz: 500 cases, seed `1592639710`;
+- rotating property fuzz: 3,000 cases, seed `2314120998`;
+- rotating adversarial fuzz: 1,500 cases, seed `2314120998`;
+- all passed.
+
+Quality baseline:
+
+- **12 / 12**.
+
+100MP compressed-image resource stress, with a 256 MiB peak-delta gate:
+
+- Linux peak delta: **61.0 MiB** maximum;
+- macOS peak delta: **72.1 MiB** maximum;
+- Windows peak delta: **92.5 MiB** maximum;
+- every concurrency record ended with `activeBytes=0`, `activeCount=0`, `queued=0`.
+
+The one-shot R5 workflow existed only to make this evidence reproducible and is removed after recording these results. The durable ESM-cycle test remains in the default test manifest.
+
+## 9. Retained debt
+
+R5 closes with explicit debt, not a purity claim:
+
+1. **Mature Core remains large.** Further extraction should wait for a stable owner seam rather than chase LOC.
+2. **Composition remains high fan-out.** This is acceptable for a construction root but new installers should continue to be challenged.
+3. **The delivered browser bundle remains monolithic and near its review bound.** It has only 472 bytes of headroom under the 256 KiB single-file review limit. Do not raise the bound casually; continue source extraction before adding substantial product logic.
+4. **Ten compatibility seams remain intentionally supported.** None currently meets its removal condition.
+5. **DSH Web activation overlays remain upstream-blocked.** Exact-source watchers must continue to detect when the upstream gap actually closes.
+
+None of these retained items is an unresolved High or Medium 2.3 architecture finding.
+
+## 10. Release handoff
+
+Architecture closure, code integration, and publication remain separate phases. **The 2.3.0 code candidate is integrated into `main`; publication is still intentionally not performed.**
+
+Completed before publication:
+
+- package version -> `2.3.0`;
+- #606 Session v4 producer-source fix and exact upstream admission hardening merged;
+- #611 final lifecycle/transport/Settings/toggle closure merged as `0c3c080`;
+- bilingual CHANGELOG and curated `docs/releases/v2.3.0.md` reconciled to the final candidate;
+- README release/support messaging is already present;
+- Doctor/support-window wording remains aligned with the peer-admitted `0.2.0-rc.2` boundary;
+- release verification runs both `pnpm client:check` and `tests/dsh-support-window.test.js` before any write-token phase;
+- Node 22/24, 0.1.7 real Host, rc.2 exact-source/Desktop, Architecture Closure, P1/P2/P3, dependency/fuzz/resource and source-sync gates are green.
+
+Repository-governance review found one active ruleset, **Main PR safety**, requiring PR-based integration/thread resolution but exposing no required status-check rule. No ruleset or branch-protection mutation is part of the 2.3 release preparation.
+
+Once this release-document reconciliation is present on `main`, only explicit publication authorization remains:
+
+- create `v2.3.0` at the then-current exact `main` SHA;
+- publish npm/GitHub Release/provenance through `.github/workflows/release.yml`.
+
+The release workflow is fail-closed: manual dispatch requires the exact current `origin/main` SHA, materializes the immutable tag only after verification, packs once, verifies npm registry identity by tarball hash, publishes through trusted OIDC, and emits provenance/attestation. Creating `v2.3.0` is therefore a real publication action, not housekeeping.
+
+At this handoff npm latest is still `2.2.8`; npm has no `2.3.0`, the remote repository has no `v2.3.0` tag, and there is no GitHub Release for 2.3.0.