dsh-vision-router 2.3.0 → 3.0.0

package/docs/architecture/3.0-r9-final-audit.md

@@ -0,0 +1,370 @@
+# DVR 3.0 R9 — Final architecture audit
+
+Status: **complete**
+
+Implementation checkpoint audited:
+
+- branch: `3.0`
+- runtime/source HEAD: `1e331b1b8f8ea74a5cd38a1347f4e0bd13ef9ef9`
+- package version at audit: `2.3.0`
+- 3.0 PR: none
+- 3.0 release/tag: none
+
+R9 is the final architecture audit for the 3.0 typed-architecture consolidation. It
+re-runs the ownership, lifecycle, dependency-cycle, browser, compatibility, package,
+Node 22/24, supported-DSH, Desktop, adversarial, property, resource and release gates
+defined by the 3.0 plan.
+
+The result is a closure, not a repository-wide TypeScript conversion.
+
+## Final architecture shape
+
+3.0 ends with the same core principle with which it started:
+
+```text
+DSH public contracts
+        |
+        v
+narrow runtime-validated Host boundaries
+        |
+        v
+typed DVR semantic owners
+        |
+        v
+Authority -> Evidence -> Planner -> Execution
+        |                       |
+        +------ composition ----+
+                    |
+                    v
+               mature Core
+```
+
+TypeScript was used where it reduces concrete ownership, lifecycle or contract drift
+risk. Mature algorithmic JavaScript and the browser client remain JavaScript where a
+language conversion would add build/declaration complexity without moving an
+architectural boundary.
+
+## Final source/package checkpoint
+
+At the audited implementation HEAD:
+
+```text
+canonical runtime TS owners       38
+canonical public declarations      1
+canonical package artifacts      182
+tracked generated artifacts        0
+
+browser client bytes          261672
+browser hard gate             262144
+browser headroom                 472
+
+package-root runtime exports       12
+runtime-composition.js lines      483
+```
+
+The final source-to-artifact evidence digest is:
+
+```text
+1949633432f7e284eec19fab4bd4e75a303e33bfe60f375ddf958c3a2343d48a
+```
+
+The validation checkout was clean.
+
+## R9 findings and repairs
+
+R9 was not a ceremonial re-run. It found several integration defects that ordinary
+unit/CI coverage did not expose and repaired them before closure.
+
+### 1. Frozen Host Dispatcher Proxy invariant
+
+The typed provider transport correctly moved DVR toward the public Undici Dispatcher
+contract, but the per-hop wrapper originally used the borrowed Host dispatcher itself as
+a JavaScript Proxy target.
+
+A Host dispatcher may expose `dispatch` as a frozen/non-configurable own property. A
+Proxy `get` trap that substitutes another dispatch function then violates ECMAScript
+Proxy invariants and throws before network dispatch.
+
+R9 changed the wrapper to use a neutral shell with the same prototype while forwarding
+all non-dispatch reads/method calls to the borrowed fallback dispatcher.
+
+Result:
+
+- DVR still does not own or close the borrowed fallback;
+- full Dispatcher method/event surface remains available;
+- prototype/instance-style compatibility is preserved;
+- the wrapper can safely override only the dispatch routing seam.
+
+The transport regression suite passes after the repair.
+
+### 2. Cross-repository Host workflows still assumed tracked artifacts
+
+R1 removed `entry.js`, `index.js` and `lib/**` from Git. Several real-Host and exact
+source workflows still checked DVR out under `dvr/` and immediately handed that checkout
+to DSH as if generated package artifacts were tracked.
+
+This caused exact-source failures such as:
+
+```text
+Cannot find .../dvr/lib/dsh-contract-compat.js
+```
+
+and real Host/browser failures where the package topology was incomplete.
+
+R9 updated every current cross-repository DVR checkout workflow to materialize the
+package explicitly:
+
+```text
+pnpm install --frozen-lockfile --ignore-scripts
+pnpm build
+pnpm build:check
+```
+
+before DSH consumes the package.
+
+A permanent architecture gate now requires one explicit materialization step per current
+`path: dvr` checkout job.
+
+### 3. Peer-admission gate had a stale hard-coded DSH peer list
+
+The Host admission evaluator assumed DVR declared only two DSH peers. 3.0 legitimately
+uses the public `@deepseek-ai/dsh-storage-domain` type contract for the optional durable
+Session policy sidecar, so the hard-coded peer list drifted from the package manifest.
+
+R9 changed admission verification to derive the complete DSH peer set from
+`package.json` rather than silently maintaining a second list.
+
+This does not broaden admission. The same compatibility expression is still evaluated for
+every declared DSH peer.
+
+### 4. Optional Cordis capabilities were read as direct service properties
+
+Real DSH Host/Desktop runs exposed an important Cordis lifecycle rule that ordinary object
+fixtures did not model: directly reading an undeclared optional service property can turn
+capability detection into a hard pending dependency.
+
+R9 repaired three seams:
+
+- Session projection lookup now uses `Context#get('sessionProjections')`;
+- optional storage-domain lookup now uses `Context#get('storageDomain')`;
+- Agent delegation binding now enters through
+  `ctx.inject(['agents'], agentsCtx => ...)`.
+
+Regression fixtures now deliberately throw on direct optional service-property reads so a
+future refactor cannot accidentally recreate the hard dependency.
+
+This preserves the intended ownership model:
+
+```text
+optional capability
+  -> capability-safe Host lookup / explicit lifecycle child
+  -> narrow DVR boundary
+```
+
+instead of:
+
+```text
+optional capability
+  -> implicit Cordis dependency
+  -> plugin remains pending
+```
+
+## Local final-audit matrix
+
+All final local evidence below was re-run at
+`1e331b1b8f8ea74a5cd38a1347f4e0bd13ef9ef9`.
+
+### Build / source ownership
+
+```text
+build                         success
+build:check                   182/182 artifacts in sync
+source ownership lint         success
+source -> artifact evidence   success
+Host typecheck                success
+Client typecheck              success
+```
+
+### Full runtime suite
+
+```text
+main suite     1588 tests / 1587 pass / 0 fail / 1 skip
+backend suite     9 tests /    9 pass / 0 fail
+```
+
+### Architecture / composition / transport
+
+```text
+87 / 87 pass
+```
+
+Coverage includes ownership closure, dependency-cycle audit, composition, Session runtime
+parity, execution-order wiring, Core surface projection and provider transport.
+
+### Browser
+
+```text
+166 / 166 pass
+```
+
+The 256 KiB single-file gate remains unchanged.
+
+### Compatibility
+
+```text
+118 / 118 pass
+```
+
+### Resource / lifecycle
+
+```text
+35 / 35 pass
+```
+
+### Property fuzz
+
+```text
+5 / 5 pass
+```
+
+### Adversarial fuzz
+
+```text
+500 cases passed
+seed = 1592639710
+```
+
+## Main CI
+
+Current implementation HEAD CI:
+
+```text
+run 36863198103
+HEAD 1e331b1b8f8ea74a5cd38a1347f4e0bd13ef9ef9
+conclusion: success
+```
+
+This includes the 3.0 packed-public-API gate together with Node 22/24 and native package
+coverage.
+
+## Supported DSH exact-source matrix
+
+Final R9 run:
+
+```text
+DSH exact source contract
+run 36864403940
+HEAD 1e331b1b8f8ea74a5cd38a1347f4e0bd13ef9ef9
+conclusion: success
+```
+
+The matrix covers the admitted 0.1.5/0.1.7 source trains across Ubuntu, macOS and Windows.
+
+The public Host floor therefore remains evidence-backed; R9 found no reason to raise it.
+
+## DSH 0.1.7 real Host/Desktop
+
+Final R9 run:
+
+```text
+DSH 0.1.7 real Host smoke
+run 36864412738
+HEAD 1e331b1b8f8ea74a5cd38a1347f4e0bd13ef9ef9
+conclusion: success
+```
+
+Passed:
+
+- real Host + Chromium;
+- macOS real Desktop renderer;
+- Windows Desktop Host / Node 22.19.0;
+- Windows Desktop Host / Node 24.21.0.
+
+## DSH 0.2.0-rc.2 real Host/Desktop
+
+Final R9 run:
+
+```text
+DSH 0.2.0-rc.2 validation
+run 36864396216
+HEAD 1e331b1b8f8ea74a5cd38a1347f4e0bd13ef9ef9
+conclusion: success
+```
+
+Passed:
+
+- real Host + Chromium;
+- Windows Desktop Host / Node 22.19.0;
+- Windows Desktop Host / Node 24.21.0;
+- exact source / Ubuntu;
+- exact source / Windows;
+- exact source / macOS including real Desktop lifecycle.
+
+## Negative architecture audit
+
+R9 explicitly rechecked the 3.0 non-goals.
+
+Production source contains no introduced:
+
+- `DvrContext`;
+- giant `HostFacade`;
+- generic service locator / DI container;
+- global current owner / registry;
+- `Object.create(core)` facade;
+- private DSH `/src/` production import;
+- `@ts-ignore` or `@ts-nocheck` suppression.
+
+`runtime-composition.js` remains a composition root rather than becoming a second Core.
+
+R9 did not:
+
+- convert mature Core merely for TypeScript percentage;
+- raise the browser size gate;
+- introduce a browser bundler/minifier as an architecture fix;
+- delete runtime validation;
+- collapse Host and Client compiler worlds;
+- narrow historical durable-data compatibility;
+- raise the DSH Host floor without evidence.
+
+## Roadmap result
+
+```text
+R0  baseline / contract ledger               complete
+R1  source / artifact boundary               complete
+R2  type infrastructure / Host boundaries    complete
+R3  DVR domain types                         complete
+R4  composition / mature Core                complete
+R5  Browser Client                           complete / production TS switch No-Go
+R6  compatibility retirement / Host floor    complete
+R7  public API                               complete
+R8  CI / release                             complete
+R9  final architecture audit                 complete
+```
+
+The R4 result does not mean every mature-Core file became TypeScript. It means the
+high-value composition/lifecycle seams were consolidated without creating the forbidden
+declaration/facade graph; low-value algorithmic conversion was intentionally left out.
+
+## Final 3.0 architecture verdict
+
+The architecture work described by the 3.0 plan is complete.
+
+3.0 now has:
+
+- one canonical source tree;
+- explicit generated package artifacts;
+- strict, separate Host and Client compiler worlds;
+- typed high-value lifecycle/domain owners;
+- runtime validation at dynamic boundaries;
+- explicit provider/resource/Session ownership;
+- an intentionally narrow package-root runtime/type API;
+- evidence-based compatibility retention/retirement;
+- a deliberate Browser TypeScript No-Go rather than a weakened size/build contract;
+- release and packed-package gates aligned with canonical source ownership;
+- real Host/Desktop evidence across the supported DSH window.
+
+The next work should therefore be release preparation or bug-driven follow-up, not another
+architecture migration pass.
+
+No PR, merge to `main`, 3.0 version bump, tag or formal 3.0 release is performed by
+this R9 closure.

package/docs/architecture/dsh-support-window.md

@@ -1,6 +1,6 @@
 # DSH Host support window
 
-Status: normative for the current DVR 2.x compatibility program.
+Status: normative for the current DVR 3.x compatibility program.
 
 ## Public support policy
 
@@ -9,7 +9,8 @@ The public support policy contains only released Host semantics. Preview/canary
 | DVR train | Minimum Supported Host | Current Stable Host | Ordinary development Host |
 |---|---|---|---|
 | `2.2.x` | `0.1.0-rc.8` | `0.1.5-rc.3` | historical 2.2 development baseline |
-| `2.3.x` | **DSH `0.1.5` train** | `0.1.5-rc.3` | **exact `0.2.0-rc.2`** |
+| `2.3.x` | **DSH `0.1.5` train** | `0.1.5-rc.3` | historical 2.3 baseline |
+| `3.0.x` | **DSH `0.1.5` train** | `0.1.5-rc.3` | **exact `0.2.0-rc.2`** |
 
 DVR `2.2.x` keeps `0.1.0-rc.8` as its historical public floor.
 
@@ -54,9 +55,10 @@ DVR 2.0.x minimum: DSH 0.1.0-rc.6
 DVR 2.1.x minimum: DSH 0.1.0-rc.8
 DVR 2.2.x minimum: DSH 0.1.0-rc.8
 DVR 2.3.x minimum: DSH 0.1.5 train (earliest admitted release: 0.1.5-rc.1)
+DVR 3.0.x minimum: DSH 0.1.5 train (unchanged from 2.3.x; earliest admitted release: 0.1.5-rc.1)
 ```
 
-Users on DSH trains older than `0.1.5` must upgrade DSH before upgrading to DVR 2.3.x.
+Users on DSH trains older than `0.1.5` must upgrade DSH before upgrading to DVR 2.3.x or 3.0.x.
 
 The 2.3 floor increase authorizes a fresh deletion audit for Host-version compatibility whose only purpose was keeping pre-`0.1.5` Hosts running. It does **not** authorize deleting compatibility for durable data merely because the Host that originally produced that data is no longer supported. Session logs, replay envelopes, persisted settings and other long-lived inputs require separate reachability evidence on supported Hosts.
 

package/docs/releases/v3.0.0.md

@@ -0,0 +1,85 @@
+# v3.0.0
+
+DSH Vision Router 3.0.0 is the ownership release. Vision authority now belongs to a
+durable, explicitly owned Session policy instead of ambient session state; the
+package root is a deliberate, typed public API instead of a monolithic
+implementation file; and the runtime installation is grouped into explicit
+composition phases with an explicitly passed provider transport. It also closes the
+R10 correctness work, the R11 adversarial final audit, and hardens the release
+pipeline itself.
+
+## Highlights
+
+- **Session Vision policy has a durable owner.** A scoped policy store, backed by
+  the Host storage domain, owns Vision authority per Session: it hydrates before a
+  child session publishes, carries into direct Vision checks, and binds delegation
+  to the Host Agent lifecycle instead of re-deriving authority from ambient state. A
+  scoped volatile backend keeps hosts without durable storage working.
+- **Deliberate package root.** The monolithic `index.js` entry is replaced by a
+  curated public entry with its own declaration file, and `exports["."]` now carries
+  `types`. The packed public-API contract executes that entry, checks its lifecycle
+  preconditions and arity, and type-checks a consumer sample against the shipped
+  declarations.
+- **Explicit composition and transport ownership.** Runtime installation is grouped
+  into explicit phases; router-owned provider HTTP receives its
+  `VisionProviderTransport` explicitly, and Core no longer installs a process-wide
+  proxy fetch. Provider probes — live model discovery and the settings connection
+  check — run inside the same configured-pair proxy scope as vision turns, taking the
+  transport the proxy boundary owns rather than reading the process global at call
+  time.
+- **R11 adversarial final audit.** Twenty findings closed, each recorded together
+  with the artifact that guards it, plus the mechanical gates that keep the defect
+  classes from returning: source-ownership lint rules, the bundle-patch activation
+  shim contract, the offline release state machine, and boundary tests against a real
+  Host.
+- **Release-pipeline integrity.** The release state machine is refusal-first and
+  draft-safe; registry identity and package content are compared before and after
+  publishing; the README announcement bars and the release notes are hard gates; the
+  pnpm-free Windows runtime smoke now receives built artifacts instead of installing
+  a package manager.
+
+## Breaking change: a new required peer
+
+3.0.0 adds one required peer dependency:
+
+- `@deepseek-ai/dsh-storage-domain` `>=0.1.5-rc.1 <0.2.0-0 || >=0.2.0-rc.2 <0.3.0-0`
+
+It backs the durable Session Vision policy layer. A Host that cannot provide the
+storage domain cannot persist the policy and therefore must be upgraded first.
+Existing Vision Router settings, profiles and historical Session data keep working:
+the policy store is additive and hydrates from the Session when no durable entry
+exists yet.
+
+## Host support window
+
+Unchanged from 2.3.x:
+
+- DSH 0.1.x: `>=0.1.5-rc.1 <0.2.0-0`
+- DSH 0.2.x: `>=0.2.0-rc.2 <0.3.0-0`
+- ordinary development Host: exact `0.2.0-rc.2`
+
+## Validation
+
+- the full gate battery on the exact release commit: install, build, build:check,
+  source-ownership lint, source→artifact evidence, reproducible clean build,
+  typecheck, the test suite, client-source synchronization, the Host support-window
+  contract, and the packed public-API contract;
+- the real-Host compatibility matrix, adversarial compatibility/fuzz gates and the
+  resource-stress gates;
+- consumer verification of the installed package on both targets (a `dsh web`
+  profile installed from the repository, and a real Desktop shell): a real image turn
+  reaches the provider with the image and the configured credential attached, live
+  model discovery reports the live models, and the Vision Router settings surface
+  renders.
+
+The audit and its evidence index are recorded in
+`docs/architecture/3.0-r11-adversarial-review.md`.
+
+## Upgrade
+
+Users on 2.3.0 with a supported Host can upgrade in place; Vision Router settings and
+existing Session data are read as before, and the durable policy store starts empty
+and hydrates from the Session. On a Host that predates the storage domain, upgrade
+DSH first. Remote Settings keeps its existing product contract: its confirmation is
+an acknowledgement, not an authorization credential, and mutation stays bounded by
+the explicit allow-list and local-only fields.

package/entry.js

@@ -14,7 +14,7 @@ export { SETTINGS_CONTRACT_REVISION }
 
 export const Config = composePublicVisionConfig(core.Config)
 
-export * from './index.js'
+export { inject, name } from './index.js'
 export { sessionSurfaceReplacementIntent } from './lib/session-surface-compat.js'
 export {
   ensureVisionAttachmentAdmissionPolicy,