dsh-vision-router 2.3.0 → 3.0.1

package/docs/architecture/3.0-r5-browser-typescript-gate.md

@@ -0,0 +1,105 @@
+# DVR 3.0 R5 Browser TypeScript gate
+
+> Status: **No-Go for monolithic Browser TypeScript migration**
+>
+> Audited branch: `3.0`
+>
+> Evidence checkpoint: `20723c368433fcc628a09fe168ca4a9d221e55e1`
+
+## Decision
+
+DVR 3.0 does **not** migrate `src/lib/client.js` wholesale to TypeScript at this stage.
+
+This is not a rejection of TypeScript in Browser code. It is a boundary decision: the current Browser delivery topology does not provide enough architectural leverage to justify converting the monolith, and forcing the conversion would create new DTO/facade/type-maintenance debt without improving a stable ownership seam.
+
+## Current bundle constraint
+
+The canonical Browser source and delivered artifact are currently identical in size:
+
+- `src/lib/client.js`: **261,672 bytes**
+- `lib/client.js`: **261,672 bytes**
+- existing single-file review bound: **262,144 bytes**
+- remaining headroom: **472 bytes**
+
+The existing `tests/index-modularization.test.js` gate continues to enforce the 256 KiB bound. R5 does not raise, weaken, or bypass it.
+
+`pnpm client:check` is green at this checkpoint.
+
+## Strict TypeScript characterization
+
+A temporary, non-committed Client compiler spike added the existing `src/lib/client.js` to the current Client program with:
+
+- `allowJs: true`
+- `checkJs: true`
+- inherited `strict: true`
+- inherited `noUncheckedIndexedAccess`
+- inherited `exactOptionalPropertyTypes`
+- Client DOM libs
+- `types: []`
+
+The existing monolith produced **478 TypeScript diagnostics**.
+
+Largest classes:
+
+| Code | Count | Meaning |
+| --- | ---: | --- |
+| TS7006 | 258 | implicit-any parameters |
+| TS2339 | 105 | dynamic/undeclared object properties |
+| TS7005 | 60 | implicitly-any variables |
+| TS7034 | 18 | variables whose array/object type cannot be inferred safely |
+| TS7053 | 13 | dynamic indexed access |
+| TS2367 | 13 | comparisons whose inferred domains do not overlap |
+
+The first errors also expose real dynamic Browser/Host seams:
+
+- `window.__ModuleLoader__`;
+- injected `require()` values;
+- React loaded through the Host module carrier;
+- historical client attachment compatibility;
+- mutable capability/state bags assembled at runtime.
+
+Treating those surfaces as statically trustworthy would require either broad `any`, duplicated Host DTOs, or a large Browser facade. None reduces current ownership risk.
+
+## Why this is a No-Go
+
+A direct `.js -> .ts` conversion would currently optimize for file extension rather than architecture.
+
+It would tend to require one or more of the following, all rejected for 3.0:
+
+- a large DVR Browser/Host facade;
+- copied Host client DTOs;
+- broad `any` or assertion-heavy adapters;
+- a new bundler/transpilation layer solely to preserve the existing single-file delivery shape;
+- generated TypeScript source embedded back into `client.js`;
+- raising the 256 KiB review bound;
+- minification as an architectural escape hatch.
+
+The current Client compiler world therefore remains intentionally separate and narrow. Host TypeScript migration must not leak Node ambient types into it.
+
+## Existing source ownership remains valid
+
+Browser behavior is already partially source-owned outside the monolith where a stable owner exists. For example, maintenance actions are authored in `client-maintenance-actions.js` and deterministically embedded into `client.js`; `pnpm client:check` verifies synchronization.
+
+That pattern should not be mechanically converted to TypeScript either. In particular, a function serialized with `Function#toString()` cannot safely carry TypeScript-only syntax into the delivered browser source.
+
+## Re-open conditions
+
+R5 Browser TypeScript should be reconsidered only when at least one of these becomes true:
+
+1. a substantial Browser responsibility gains an independent stable owner that can be typed without copying the monolith's dynamic Host surface;
+2. DSH exposes a public typed Client module/context contract that removes the need for DVR-owned facades;
+3. the Browser delivery topology gains an official build/bundle seam where TypeScript can compile without changing runtime ownership or weakening the size gate;
+4. source extraction creates enough review headroom that a typed owner can be introduced without hiding growth through minification;
+5. a concrete Browser bug class is shown to be prevented by a narrow type boundary.
+
+## Invariants retained
+
+- no increase to the 262,144-byte client bound;
+- no Node globals in the Client TypeScript program;
+- no production dependency on DSH private `src/*` paths;
+- no broad Host facade;
+- no repository-wide Browser TypeScript rewrite;
+- no minification-based architecture fix;
+- runtime validation remains authoritative for dynamic Host/client data.
+
+R5 therefore closes as **No-Go for monolithic migration, open for future owner-by-owner typed extraction when a real seam appears**.

package/docs/architecture/3.0-r6-compat-retirement.md

@@ -0,0 +1,203 @@
+# DVR 3.0 R6 — Compatibility retirement / Host-floor re-audit
+
+Status: **complete — one stale package edge retired; Host floor unchanged**
+
+Baseline:
+
+- DVR branch: `3.0`
+- DSH exact source: `deepseek-ai/deepseek-harness@639ed015397290b3745d163aafe02ffee4aa3f84`
+- DSH version: `0.2.0-rc.2`
+- public DVR Host window remains:
+  - `>=0.1.5-rc.1 <0.2.0-0`
+  - or `>=0.2.0-rc.2 <0.3.0-0`
+
+R6 re-runs compatibility removal conditions. It does **not** treat age, a TypeScript
+migration, or the current development pin as evidence that a compatibility owner is dead.
+
+Durable user-data compatibility remains independent of the runtime Host floor.
+
+## Result
+
+R6 found one real stale package-graph edge:
+
+```text
+@deepseek-ai/dsh-client-runtime
+```
+
+It was retired from both:
+
+- `package.json#dsh.client.inject`;
+- Doctor's Host-package diagnostic inventory.
+
+No documented runtime compatibility seam met its removal condition, and the public Host
+floor is not raised.
+
+## Retired: stale dsh-client-runtime client injection
+
+### Evidence
+
+The exact DSH `0.2.0-rc.2` client architecture has no
+`@deepseek-ai/dsh-client-runtime` package.
+
+Repository review also found no DVR production consumer of a `ctx.runtime` or equivalent
+client-runtime service. The only remaining DVR references before retirement were:
+
+1. `package.json#dsh.client.inject`;
+2. Doctor's diagnostic package list.
+
+This matters because current DSH does not define `dsh.client.inject` as an optional
+capability hint. Its client-module contract describes inject entries as package dependency
+edges: injected package factories must arrive before the consuming row materializes, and
+Cordis uses the same edges for entry composition.
+
+A package name that no longer exists therefore has no supported ownership role as a
+compatibility placeholder.
+
+### Retirement
+
+R6 removes the stale row rather than replacing it with another guessed package.
+
+The retained client inject list continues to use only the existing DVR-declared package
+edges; no unrelated browser dependency is changed.
+
+Doctor also stops reporting `@deepseek-ai/dsh-client-runtime` as a Host package. Keeping
+the diagnostic after removing the graph edge would have produced false missing-package
+evidence.
+
+A regression gate in `tests/manifest-dependencies.test.js` now forbids the package name
+from returning to either surface.
+
+### Validation
+
+After retirement:
+
+- canonical build succeeded;
+- generated-artifact reproducibility succeeded;
+- Host TypeScript program succeeded;
+- Client TypeScript program succeeded;
+- manifest, Doctor, browser-client and DSH-compatibility targeted tests passed
+  `193/193`.
+
+## Host floor: KEEP
+
+R6 does not raise the minimum Host from `0.1.5-rc.1`.
+
+A Host-floor increase requires evidence that dropping the admitted Host generation removes
+real compatibility complexity without conflating runtime compatibility with persisted data.
+That condition is not met.
+
+Several retained seams remain reachable for current product/platform reasons even if older
+Hosts were removed, while other seams still span genuine lifecycle differences inside the
+declared support window.
+
+Raising the floor would therefore reduce support without producing the architectural
+simplification required by the 3.0 plan.
+
+## Retained: DSH Web modules -> webServer overlay
+
+Verdict: **KEEP — shim-required**
+
+Exact `0.2.0-rc.2` source still declares:
+
+```yaml
+- id: modules
+  name: '@deepseek-ai/dsh-client-modules'
+```
+
+with no activation `inject` field.
+
+The existing retirement classifier therefore remains in `shim-required`, not
+`retire-ready`.
+
+DVR must keep the overlay until an admitted Host's official modules row owns
+`webServer` itself.
+
+## Retained: DSH Web connection -> webServer overlay
+
+Verdict: **KEEP — shim-required**
+
+Exact `0.2.0-rc.2` source still declares:
+
+```yaml
+- id: connection
+  name: '@deepseek-ai/dsh-client-connection'
+  inject: [webRuntime]
+```
+
+The official row still does not own `webServer`.
+
+The existing classifier correctly remains `shim-required`. If upstream later adds
+`webServer`, the surveillance gate is already designed to change to
+`retire-ready` and force an explicit DVR retirement before that Host train is admitted.
+
+## Retained: pi-ai / OpenCode Go session-affinity projection
+
+Verdict: **KEEP — Host gap remains**
+
+Exact DSH `0.2.0-rc.2` `PiAiAdapter` propagates the Harness session identity into
+pi-ai:
+
+```text
+GenerateOptions.sessionId
+  -> streamSimple(..., { sessionId: String(options.sessionId) })
+```
+
+but the current DSH source contains no `x-opencode-session` carrier.
+
+That is precisely the documented removal condition for DVR's scoped OpenCode Go wire
+projection: generic `sessionId` propagation is not equivalent to the endpoint-required
+header.
+
+The DVR rule remains narrowly scoped to an active Vision Router affinity scope and the
+official `https://opencode.ai/zen/go...` endpoint. It must not be retired until the
+native header is emitted on every supported path.
+
+## Retained compatibility inventory
+
+The remaining normative seams in `compat-inventory.md` continue to satisfy at least one
+current removal blocker.
+
+### Host-gap owners
+
+- `dsh-contract-compat` — Settings lifecycle still spans admitted Host generations;
+  durable historical attachment-policy overlays are a separate data-compatibility reason.
+- `adapter-update-coalescer` — DVR still owns duck-typed adapters whose Host base
+  contracts and synchronous topology updates require normalization/coalescing.
+- `pi-ai-bridge-wire-compat` — native OpenCode affinity remains absent as proved above;
+  legacy direct bridge removal is independently gated.
+- `settings-client-loader-lifecycle` — the supported browser module lifecycle still
+  requires post-create reattachment across the declared Host window.
+- `legacy-global-proxy-boundary` — explicit DVR proxy override for Host-owned visual
+  adapters remains a supported product capability with no scoped Host dispatcher seam.
+- `legacy-core-vision-policy-bridge` — the Host still lacks the two exact pre-step
+  capabilities recorded by the inventory; the 3.0 typed Core-surface work did not create
+  an upstream substitute.
+
+### Product / durable-data / platform owners
+
+These are not Host-floor retirement candidates:
+
+- `replay-envelope-v2-compat` — durable replay data;
+- `http-compat` — evidenced provider wire behavior;
+- `tesseract-exec-compat` — Node/process and Windows DPI behavior;
+- `abort-signal-compat` — partial runtime-realm capability compatibility.
+
+Deleting any of these merely because the current Host pin is `0.2.0-rc.2` would mix
+independent compatibility domains.
+
+## R6 exit state
+
+```text
+Host floor                     unchanged
+durable-data compatibility     unchanged
+stale client-runtime inject    retired
+stale Doctor package row       retired
+modules -> webServer overlay   keep / shim-required
+connection -> webServer        keep / shim-required
+OpenCode session projection    keep / Host gap
+other normative compat         keep
+```
+
+R6 is therefore a real retirement pass, not a blanket deletion pass: it removes the one
+edge whose ownership and supplier both disappeared while preserving every seam whose
+documented removal condition is still false.

package/docs/architecture/3.0-r7-public-api.md

@@ -0,0 +1,151 @@
+# DVR 3.0 R7 — Public API closure
+
+Status: **complete**
+
+R7 replaces the package root's accidental mature-Core export graph with one explicit
+plugin/compatibility contract and publishes a matching declaration surface.
+
+## Before R7
+
+The package root was:
+
+```text
+lib/public-entry.js
+  -> export * from ../entry.js
+entry.js
+  -> export * from ./index.js
+index.js
+  -> mature Core + algorithm/helper exports
+```
+
+A runtime import of the built package exposed **122 names**. Most were implementation
+details such as OCR helpers, pixel-diff utilities, cache primitives, HTTP/provider helpers,
+SVG rendering helpers and routing internals.
+
+Those names were public only because of transitive `export *`; they had no package-root
+ownership contract.
+
+Repository reachability review found no production or test consumer importing those Core
+helpers through `dsh-vision-router` or through `entry.js`. Existing direct entry
+consumers use the public Config/revision contract, while Core tests import `index.js`
+or the owning module explicitly.
+
+## Deliberate runtime surface
+
+R7 removes `export * from './index.js'` from `entry.js`.
+
+The package root now exposes exactly:
+
+```text
+Config
+SETTINGS_CONTRACT_REVISION
+apply
+name
+inject
+
+sessionSurfaceReplacementIntent
+
+ensureVisionAttachmentAdmissionPolicy
+hasBatchAttachmentContract
+hostOwnsOfficialDeepSeekProvider
+installHostSettingsCompatibility
+installVisionAttachmentAdmissionPolicy
+protectHostProviderOwnership
+```
+
+Classification:
+
+- **plugin contract**
+  - `name`
+  - `inject`
+  - `Config`
+  - `apply`
+- **supported DVR contract**
+  - `SETTINGS_CONTRACT_REVISION`
+- **compatibility API**
+  - `sessionSurfaceReplacementIntent`
+  - the six explicit DSH compatibility helpers above
+- **accidental internal**
+  - every former transitive mature-Core/helper export
+- **test-only**
+  - none are published through the package root
+
+The mature Core remains importable inside the repository from its owning source/artifact;
+R7 does not delete or rename its internal exports.
+
+## Type surface
+
+R7 adds one hand-owned declaration:
+
+```text
+src/lib/public-entry.d.ts
+  -> build
+lib/public-entry.d.ts
+```
+
+It intentionally declares only the runtime faces above.
+
+Dynamic Host values remain `unknown` at the package boundary instead of inventing a DVR
+copy of the DSH Context graph. The Session replacement variants and the narrow
+compatibility result/options that DVR actually owns are declared explicitly.
+
+No internal typed owner is re-exported merely because it exists.
+
+## Package resolution
+
+The package follows the current DSH publication shape:
+
+```json
+{
+  "main": "lib/public-entry.js",
+  "types": "lib/public-entry.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/public-entry.d.ts",
+      "default": "./lib/public-entry.js"
+    }
+  }
+}
+```
+
+The existing `main` remains for runtime compatibility.
+
+`./client` stays a DSH loader entry and is deliberately **not** promoted to an ordinary
+typed consumer-library API.
+
+## Source/artifact ownership
+
+The R1 builder now understands canonical `.d.ts` source files:
+
+- `.js` canonical source is copied as runtime JavaScript;
+- `.ts` canonical source is compiled to JavaScript;
+- `.d.ts` canonical source is copied as a declaration artifact.
+
+Generated declarations remain outside Git source-of-truth just like generated runtime JS.
+
+## Permanent gates
+
+`tests/architecture-contract-baseline.test.js` now locks:
+
+1. root `main`, `types` and conditional `exports["."]`;
+2. absence of `export * from './index.js'` in the entry boundary;
+3. the exact twelve runtime export names;
+4. a deliberate declaration for every runtime export;
+5. no relative internal-module re-export from the root declaration;
+6. no DSH private `/src/` dependency in the public declaration.
+
+This means a new Core export cannot silently become package API again.
+
+## Validation
+
+At R7 closure:
+
+- canonical build: success;
+- generated-artifact check: **182 artifacts in sync**;
+- Host TypeScript program: success;
+- Client TypeScript program: success;
+- built root runtime export count: **12**;
+- public API / Config / DSH compatibility targeted tests: **66/66**.
+
+R7 therefore closes both halves of the package boundary: runtime names and TypeScript
+names are deliberate, narrow and independently owned.

package/docs/architecture/3.0-r8-ci-release.md

@@ -0,0 +1,248 @@
+# DVR 3.0 R8 — CI / release closure
+
+Status: **complete**
+
+R8 aligns the 3.0 canonical-source build with CI, packing and the existing trusted
+release model. It does not replace the 2.3 pack-once / tarball-identity / OIDC /
+provenance design; it closes the new source/type/declaration gaps around that design.
+
+## Release blocker found during R8
+
+R1 intentionally removed generated runtime artifacts from Git:
+
+```text
+src/**
+  -> build
+entry.js
+index.js
+lib/**
+```
+
+and added:
+
+```text
+prepare = pnpm build
+prepack = pnpm build
+```
+
+The pre-3.0 release workflow still had two incompatible assumptions:
+
+1. release verification rejected `prepare` and `prepack` as forbidden lifecycle
+   scripts;
+2. the publish phase set `NPM_CONFIG_IGNORE_SCRIPTS=true`, checked out a clean tree,
+   did not install/build package artifacts, then executed `npm pack`.
+
+Because generated JavaScript is no longer tracked, that publish path could have packed a
+tarball without the canonical runtime artifacts.
+
+R8 fixes the release path instead of weakening R1.
+
+## Canonical source ownership lint
+
+R8 adds:
+
+```text
+pnpm lint
+  -> scripts/lint-source-ownership.mjs
+```
+
+The gate verifies:
+
+- every canonical non-declaration `.ts` owner is present in `tsconfig.build.json`;
+- every canonical Host `.ts` owner is present in `tsconfig.host.json`;
+- stale TypeScript build includes fail closed;
+- two canonical source files cannot claim the same package artifact;
+- production source cannot contain `@ts-ignore` or `@ts-nocheck`;
+- production source cannot import DSH private `/src/` entry points;
+- `entry.js`, `index.js` and `lib/**` cannot return to Git source-of-truth.
+
+At closure the gate reports:
+
+```text
+38 typed runtime owners
+182 canonical package artifacts
+```
+
+## Source-to-artifact evidence
+
+R8 adds:
+
+```text
+pnpm source:artifact:check
+  -> scripts/verify-source-artifact-map.mjs
+```
+
+It proves one package artifact for every canonical JS/TS/declaration source and rejects:
+
+- missing generated artifacts;
+- orphan generated artifacts;
+- canonical ownership collisions;
+- copied JS/declaration byte drift.
+
+For compiled TypeScript it records the canonical-source and emitted-artifact hashes rather
+than pretending compilation is byte identity.
+
+R8 closure evidence:
+
+```json
+{
+  "canonicalSources": 182,
+  "typedSources": 38,
+  "declarationSources": 1,
+  "packageArtifacts": 182,
+  "mappingSha256": "8799b5363d809834b834676418583eb73aa969ab0d2f6808ed527120579f656a"
+}
+```
+
+## Packed public API smoke
+
+R8 adds:
+
+```text
+scripts/verify-packed-public-api.mjs <existing-package.tgz>
+```
+
+The script never repacks. It validates the exact candidate supplied by its caller:
+
+- package `main`, `types`, root conditional exports and `./client`;
+- required runtime/declaration artifacts;
+- canonical `src/` is not shipped;
+- exact twelve R7 runtime exports;
+- a strict NodeNext TypeScript consumer resolves the packed declaration;
+- an accidental mature-Core helper such as `createCache` is not package-root API.
+
+This gives declarations a packed-package contract rather than validating only the
+repository checkout.
+
+## CI
+
+The Node 22 CI path now runs:
+
+```text
+frozen install
+build
+build:check
+build:reproducible
+Host + Client typecheck
+source ownership lint
+source-to-artifact evidence
+client generated-source check
+full runtime suite
+```
+
+A separate `packed public API` job:
+
+1. performs the canonical build;
+2. packs one candidate;
+3. runs the packed runtime/declaration smoke against that tarball.
+
+Node 24 continues to run the full runtime suite, while Linux/macOS/Windows native Host
+jobs retain their sharp/package installation checks.
+
+At the final R8/R9 checkpoint, CI run `36855737017` for
+`046fd10bc1e6eae9bb72bdf68f0a5e0580ae1efd` completed successfully across:
+
+- packed public API;
+- Node 22;
+- Node 24;
+- Linux Host/sharp;
+- macOS Host/sharp;
+- Windows Host/sharp.
+
+## Release verification phase
+
+Release verification now explicitly validates the 3.0 source contract:
+
+```text
+install locked dependencies
+build
+build:check
+lint
+source:artifact:check
+build:reproducible
+typecheck
+full tests
+client:check
+Host support-window contract
+```
+
+The lifecycle security check permits only the two required build hooks and pins their
+contents exactly:
+
+```text
+prepare = pnpm build
+prepack = pnpm build
+```
+
+Install/publish lifecycle hooks with unrelated execution authority remain forbidden.
+
+## Trusted publish phase
+
+The publish phase deliberately keeps:
+
+```text
+NPM_CONFIG_IGNORE_SCRIPTS=true
+```
+
+It now performs:
+
+```text
+pnpm install --frozen-lockfile --ignore-scripts
+pnpm build
+pnpm build:check
+pnpm lint
+pnpm source:artifact:check
+npm pack --json        # exactly once
+verify-packed-public-api <that exact tarball>
+registry identity / publish / provenance
+```
+
+So a release no longer depends on npm lifecycle scripts to materialize package code.
+
+The pre-existing supply-chain design is unchanged after the tarball is created:
+
+- one exact tarball is hashed;
+- the same tarball is probed/published;
+- trusted OIDC publishing remains enabled;
+- registry SHA identity is verified;
+- SLSA/GitHub provenance binds the exact tarball;
+- GitHub Release rehydrates and verifies the same npm artifact.
+
+## Clean publish simulation
+
+R8 reproduced the trusted-publish shape from a clean checkout:
+
+1. `pnpm install --frozen-lockfile --ignore-scripts`;
+2. asserted `entry.js`, `index.js` and `lib/` were still absent;
+3. explicit canonical build;
+4. build/source ownership verification;
+5. one `npm pack`;
+6. packed runtime/declaration smoke.
+
+Result:
+
+```text
+PUBLISH_SIM_OK:dsh-vision-router-2.3.0.tgz
+```
+
+The package version remains 2.3.0 because R8 is architecture/release-path validation,
+not the 3.0 release/version-bump phase.
+
+## R8 exit state
+
+```text
+canonical source                  src/**
+generated repository artifacts    untracked
+typed runtime owners              38
+public declaration owners          1
+source/package artifacts          182 -> 182
+Host + Client typecheck           gated
+clean reproducibility             gated
+packed declarations               gated
+browser generated sync            gated
+pack-once                         preserved
+trusted publishing                preserved
+tarball identity                  preserved
+provenance                         preserved
+formal release                    not performed
+```