dsh-vision-router 2.2.8 → 3.0.0

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

@@ -0,0 +1,410 @@
+# DVR 2.3.0 architecture execution plan
+
+Baseline: `origin/main@74e3f0194f8ba733f2e64f6080f68c5c9dca9167` (`v2.2.7`).
+
+Branch: `2.3.0`.
+
+Implementation status: **first-pass plan completed, overall 2.3.0 reopened**. This document is retained as the historical plan for the first architecture pass. A later adversarial review found additional correctness/integration work; the active execution authority is `2.3.0-reopened-plan.md`.
+
+This document defines the implementation order for the 2.3.0 architecture phase. All work described here is developed on the single `2.3.0` branch first. No pull request is opened while the phase is being assembled and validated.
+
+2.3.0 is not another architecture rewrite. The 2.x single-owner model remains authoritative. The goal is to harden composition, retire compatibility seams whose removal conditions are now satisfied, and extract stable responsibilities from the mature Core without creating new semantic owners.
+
+## 1. Phase goals
+
+2.3.0 has three ordered goals:
+
+1. **Composition hardening** — make cross-boundary behavior explicit, lifecycle-safe and testable as a composition, not merely as isolated modules.
+2. **Compatibility retirement** — remove transitional registries/shims only when their documented removal conditions are actually satisfied; keep real Host-gap compatibility intact.
+3. **Mature-Core extraction** — move stable responsibilities out of the mature monolith into explicit owners while preserving behavior and authority direction.
+
+The order is intentional. Extraction must not begin by moving unstable composition behavior into new modules, and compatibility code must not be deleted before the replacement seam has been proven in production paths.
+
+## 2. Frozen product and architecture decisions
+
+The following decisions are fixed for 2.3.0 unless explicitly revisited before implementation.
+
+### 2.1 Remote Settings behavior is reminder-only
+
+Remote Settings keeps its current product model:
+
+- a remote client may be shown a risk reminder before enabling remote settings;
+- the reminder is a user-facing warning, not an authentication or authorization proof;
+- the server does **not** add a second confirmation validator, challenge, identity check, one-time secret, or local-machine approval requirement;
+- the existing remote field allow-list and local-only field boundaries remain the actual capability restriction;
+- `acceptedRisk` remains a product-flow acknowledgement, not a security credential.
+
+Therefore 2.3.0 must **not** treat the reminder-only design as a security defect and must not silently strengthen it into a server-side validation gate.
+
+### 2.2 Existing single-owner architecture remains normative
+
+2.3.0 preserves the current ownership direction:
+
+| 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 | `session-vision-runtime.js` / state + index |
+| Managed artifacts | `vision-artifact-store.js` |
+| Router-owned provider HTTP | `vision-provider-transport.js` |
+| Host product/presentation decisions | `vision-product-presentation.js` |
+| Browser rendering | browser/client presentation layer |
+
+No 2.3.0 task may introduce a second owner for one of these responsibilities.
+
+### 2.3 Host-first remains the transport rule
+
+With no explicit DVR proxy override, Host network policy remains authoritative. 2.3.0 may make transport ownership more explicit, but must not replace blank-proxy Host behavior with a DVR-owned dispatcher or native-fetch snapshot.
+
+### 2.4 Compatibility retirement is evidence-driven
+
+A compatibility seam is removed only when its existing inventory removal condition is satisfied by code and tests. A seam that still closes a real DSH Host gap is retained even if its implementation is aesthetically undesirable.
+
+In particular, the `modules -> webServer` and `connection -> webServer` compatibility overlays are retained while exact supported/preview DSH source contracts still classify them as `shim-required`.
+
+## 3. Workstream A — composition hardening
+
+Composition hardening is the first implementation batch because the current main risk is interaction between individually-correct boundaries.
+
+### A1. Converge every DVR `fetch` wrapper on one lifecycle primitive
+
+**Problem**
+
+`runtime-i18n-boundary.js` still assigns `globalThis.fetch` directly while the proxy and pi-ai compatibility boundaries use `captureFetchDelegate()` + `installFetchWrapper()`. With a Host accessor-owned fetch pipeline, direct assignment can invoke the foreign setter and create a recursive cycle.
+
+**Implementation**
+
+- Replace direct i18n fetch assignment/restoration with the shared descriptor-safe fetch lifecycle.
+- Preserve live Host accessor recomposition rather than freezing one compiled getter result.
+- Preserve out-of-order disposal and later Host replacement behavior.
+- Do not broaden the i18n boundary's network scope; only its installation lifecycle changes.
+
+**Required composition matrix**
+
+Test both load orders and disposal orders for:
+
+- Host accessor + i18n;
+- Host accessor + wire compatibility;
+- Host accessor + proxy compatibility;
+- Host accessor + i18n + wire;
+- Host accessor + i18n + proxy;
+- Host accessor + i18n + wire + proxy;
+- live Host middleware replacement/removal;
+- later Host `fetch` replacement;
+- blank DVR proxy Host-first behavior;
+- scoped proxy/wire behavior remaining visual-call-only.
+
+**Exit condition**
+
+No production DVR boundary assigns `globalThis.fetch` through a foreign accessor setter.
+
+### A2. Promote composition tests from feature-local to cross-boundary contracts
+
+Create a small set of composition contract tests that assert invariants across installers rather than re-testing individual implementations.
+
+Target invariants:
+
+- no wrapper recaptures itself through a Host setter;
+- no disposal restores a stale DVR layer over a later Host replacement;
+- no compatibility boundary expands its authority when another wrapper is present;
+- ordinary Host traffic remains untouched by visual-only scopes;
+- all lifecycle cleanup is order-independent where the public lifecycle permits non-LIFO cleanup.
+
+The tests should depend on public/narrow seams, not private implementation ordering where possible.
+
+### A3. Restructure `runtime-composition.js` into explicit phases
+
+Do not convert the runtime into a service locator. Keep dependency construction explicit, but group the current high-fan-out installer sequence into named phases.
+
+Target shape:
+
+```text
+applyVisionRuntimeComposition
+  -> installHostAndSecurityBoundaries
+  -> createRuntimeOwners
+  -> installExecutionAndRouting
+  -> applyMatureCoreBridge
+  -> installPresentationAndWeb
+```
+
+Each phase receives and returns a narrow composition object containing only dependencies required by later phases.
+
+**Rules**
+
+- installation order remains behaviorally identical in the first refactor;
+- no product behavior changes in the same commit as the phase extraction;
+- Core receives the same context identity/compat boundaries as before;
+- phase functions do not become new semantic authorities.
+
+**Exit condition**
+
+The top-level composition file reads as lifecycle orchestration rather than a flat installer chain, and cross-phase dependencies are visible in function signatures.
+
+### A4. Create one 2.3 critical architecture gate
+
+Do not make all existing workflows required. Instead define one aggregated 2.3 architecture/compat gate that runs the minimum high-value contracts needed before branch integration:
+
+- Node 22 + 24 core test suite;
+- fetch composition matrix;
+- architecture closure contracts;
+- current supported Host contract;
+- security/property boundary tests;
+- package/entry smoke relevant to the modified phase.
+
+This gate is added and exercised on the `2.3.0` branch. Whether it becomes a protected-branch required check for `main` is a separate integration decision after the branch is complete.
+
+## 4. Workstream B — compatibility retirement
+
+Compatibility retirement starts only after Workstream A is green, so removal work is protected by stronger composition tests.
+
+### B1. Remove the VisionProviderTransport process/profile registry
+
+**Current transitional seam**
+
+`vision-provider-transport.js` retains module-level `installed[]`; `http-compat.js` and `catalog-corrections.js` read `currentVisionProviderTransport()`.
+
+**Target**
+
+Make transport dependency explicit in all production compatibility callers.
+
+Expected direction:
+
+```text
+runtime owner
+  -> explicit VisionProviderTransport
+     -> OpenAI compatibility caller
+     -> Anthropic/catalog correction caller
+```
+
+**Implementation constraints**
+
+- keep direct/unit call compatibility only where it is part of the public/testable function contract;
+- do not replace the registry with another module-global current owner;
+- preserve proxy admission, redirect-hop selection, credential resolution, bounded body reads, cancellation and dispatcher lifecycle;
+- delete `installVisionProviderTransport()` / `currentVisionProviderTransport()` only after repository-wide production reads reach zero.
+
+**Exit condition**
+
+No production module-global transport locator remains.
+
+### B2. Reclassify the compatibility inventory
+
+For every retained compatibility seam, assign one 2.3 state:
+
+- `retain-host-gap` — exact current Host evidence still requires it;
+- `retire-ready` — replacement seam exists and all production callers have migrated;
+- `product-compat` — intentionally retained product compatibility, not blocked on Host evolution;
+- `historical-only` — no production use remains and it can be deleted.
+
+Update `docs/architecture/compat-inventory.md` only after code evidence exists. Documentation must describe the actual state, not the desired state.
+
+### B3. Retain DSH Web activation overlays until upstream ownership lands
+
+The `modules` and `connection` WebServer overlays stay in 2.3.0 while the exact supported/preview upstream rows remain `shim-required`.
+
+The source-contract watcher remains responsible for producing `retire-ready` when upstream starts owning the dependency.
+
+2.3.0 must not remove these overlays simply as part of a generic compatibility cleanup.
+
+### B4. Review legacy global proxy compatibility without changing proxy product policy
+
+`proxy` / `proxyHosts` remain supported advanced overrides.
+
+The work in 2.3.0 is limited to:
+
+- verifying the remaining unscoped whole-turn fallback is still reachable only through the documented legacy configuration;
+- ensuring it does not expand during composition changes;
+- removing it only if its existing product/support-window retirement condition is independently satisfied.
+
+Do not deprecate explicit DVR proxy support as part of 2.3.0 architecture cleanup.
+
+## 5. Workstream C — mature-Core extraction
+
+Core extraction begins after A is stable and B1 has removed the most important process-level locator. The objective is not to minimize file size; it is to move stable responsibilities to explicit owners.
+
+### C1. Extract public configuration construction
+
+Replace the current two-stage Config/default construction with an explicit public configuration factory or schema composition seam.
+
+Target distinction:
+
+```text
+Core schema / legacy implementation defaults
+          +
+2.3 public product defaults and settings additions
+          -> public Config
+```
+
+**Constraints**
+
+- no user-visible default changes in the extraction commit;
+- entry-point exports stay compatible;
+- Settings registration receives the same final schema/defaults;
+- historical profile migration remains unchanged.
+
+### C2. Extract Core-owned browser/maintenance route registration
+
+Move stable route registration currently buried in `index.js` into a narrow installer owned by the runtime/web composition layer, starting with routes that are not intrinsic to image algorithms, for example:
+
+- update check;
+- self update;
+- model-capability metadata;
+- other product/maintenance endpoints whose authority already lives outside the Core algorithm.
+
+All extracted routes must continue to pass through the existing Web capability/authentication boundary.
+
+**Goal**
+
+`index.js` should increasingly describe visual Core behavior rather than product Web administration.
+
+### C3. Extract stable local image-processing/tool groups by ownership
+
+Candidates are extracted only when they have a clear cohesive owner and can be moved without recreating hidden shared state.
+
+Preferred extraction units:
+
+- image preprocessing / downscale and bounded resource helpers;
+- OCR execution group;
+- visual artifact-producing tool group;
+- screenshot/capture implementation behind the existing screenshot runtime boundary.
+
+Do not split a function merely to reduce LOC. A move is accepted only if the resulting module has a stable input/output contract and a narrower dependency set than the Core monolith.
+
+### C4. Reduce `client.js` by moving current-product modules first
+
+The browser cleanup follows the same rule: current product logic moves to real modules; old Host compatibility shims may remain injected/prelude code.
+
+First candidates:
+
+- settings product sections already backed by server-owned state;
+- update/log/diagnostics actions;
+- capability/runtime presentation components with stable contracts.
+
+Do not rewrite the entire client or remove legacy loader shims in one batch.
+
+### C5. Keep Core extraction behavior-preserving
+
+Every extraction commit must satisfy:
+
+- no new Settings proxy/impersonation;
+- no new module-global runtime owner;
+- no second routing/session/artifact/transport authority;
+- no change to native multimodal non-intervention;
+- no expansion of browser authority;
+- no support-window increase or decrease unless separately documented.
+
+## 6. Implementation sequence on branch `2.3.0`
+
+The branch is implemented in this order:
+
+| Batch | Scope | Must be behavior-changing? | Dependency |
+| --- | --- | --- | --- |
+| 0 | Planning document + baseline evidence | No | none |
+| 1 | A1 fetch lifecycle convergence | Yes, bug fix only | Batch 0 |
+| 2 | A2 composition contract matrix | No product change | Batch 1 |
+| 3 | A3 composition phase refactor | No | Batch 2 |
+| 4 | A4 2.3 critical architecture gate | No | Batch 3 |
+| 5 | B1 explicit provider transport plumbing + registry deletion | Internal only | Batch 4 |
+| 6 | B2/B3/B4 compat inventory reconciliation | Only if retirement evidence exists | Batch 5 |
+| 7 | C1 public Config construction extraction | No | Batch 6 |
+| 8 | C2 product/Web route extraction from mature Core | No | Batch 7 |
+| 9 | C3 local image/tool extraction | No | Batch 8 |
+| 10 | C4 browser current-product modularization | No intended product change | Batch 9 |
+| 11 | Final 2.3 adversarial architecture audit | No | Batch 10 |
+
+A later batch may be dropped if its preconditions are not met. In particular, compatibility deletion is never forced merely because it appears in this plan.
+
+## 7. Commit discipline
+
+All work remains on `2.3.0` during the phase.
+
+Recommended commit boundaries:
+
+1. `docs(architecture): define 2.3.0 execution plan`
+2. `fix(fetch): converge runtime i18n on safe wrapper lifecycle`
+3. `test(composition): cover complete DVR fetch wrapper matrix`
+4. `refactor(runtime): group composition into explicit phases`
+5. `ci(architecture): add 2.3 critical composition gate`
+6. `refactor(transport): pass provider transport explicitly`
+7. `refactor(compat): retire satisfied compatibility seams`
+8. `refactor(config): make public config construction explicit`
+9. `refactor(core): extract product web routes`
+10. subsequent Core/client extraction commits, one responsibility at a time
+11. `docs(architecture): record 2.3.0 final audit and remaining compat`
+
+Do not combine a compatibility deletion with an unrelated Core extraction. Regressions must be attributable to one ownership change.
+
+## 8. Validation policy
+
+### Per-batch minimum
+
+Each batch runs its directly affected tests plus:
+
+- Node-supported unit tests for the changed boundary;
+- architecture closure tests if owner/dependency direction changes;
+- Host contract tests if DSH seams change;
+- package smoke if public entry/config/export behavior changes.
+
+### Milestone validation
+
+After A, B and C respectively, run the branch-wide validation set:
+
+```text
+pnpm test
+pnpm test:compat
+pnpm test:security
+pnpm test:property-fuzz
+pnpm test:stress
+pnpm test:quality
+package/pack smoke
+```
+
+Where a script name differs from the current package scripts, the equivalent existing workflow/test set is used rather than adding duplicate commands just for naming consistency.
+
+### Final branch exit criteria
+
+2.3.0 is ready for integration discussion only when:
+
+1. all branch changes are on `2.3.0` and the working tree is clean;
+2. the i18n/accessor fetch recursion reproducer is permanently covered and green;
+3. composition contracts cover all production fetch-wrapper combinations;
+4. the provider transport registry is gone, or documented with concrete evidence explaining why B1 could not complete;
+5. every deleted compatibility seam satisfies its inventory removal condition;
+6. all retained Host-gap seams remain feature-detected and tested;
+7. Core extraction introduced no new semantic owner/global current locator;
+8. current stable Host and admitted preview Host contracts remain green;
+9. Node 22/24 and required platform tests remain green;
+10. final architecture audit explicitly lists retained debt rather than declaring blanket purity.
+
+## 9. Explicit non-goals for 2.3.0
+
+2.3.0 does not include:
+
+- changing Remote Settings from reminder-only to server-side confirmation/authentication;
+- redesigning capability scoring or routing policy;
+- changing native multimodal ownership;
+- deleting DSH compatibility overlays that still classify as `shim-required`;
+- deprecating DVR `proxy` / `proxyHosts`;
+- adding PDF/video/CAD/GUI-agent product features;
+- rewriting all of `index.js` or `client.js`;
+- introducing a general dependency-injection container/service locator;
+- raising the public DSH minimum solely to simplify DVR internals.
+
+## 10. Architectural success definition
+
+2.3.0 succeeds if the runtime becomes easier to reason about **without changing who owns decisions**:
+
+```text
+2.2.x
+  correct owners + many compatibility/composition seams
+
+2.3.0
+  same correct owners
+  + composition behavior explicitly contracted
+  + fewer process/global compatibility locators
+  + mature Core containing less product/lifecycle glue
+```
+
+The release should end with less hidden coupling, not merely more files.