dsh-vision-router 2.3.0 → 3.0.0

package/docs/architecture/3.0-r10-final-correctness-closure.md

@@ -0,0 +1,207 @@
+# DVR 3.0 R10 — Final Correctness Closure
+
+Status: **complete — integrated into `3.0` through PR #621**
+
+Implementation checkpoint:
+
+- implementation branch: `r10-final-correctness-closure`
+- original review base: `3.0@cc6bdd8d24bc186e13ae5bfa73502a30196aa16b`
+- implementation HEAD: `b38d427d54024f739dabbb3dacf389dc719a960f`
+- reconciled R10 head: `9c77880c69e3a85ff07666a83c9006d82cc48cba`
+- integration PR: `#621`
+- integrated `3.0` merge commit: `3e63545804617a3ffcd354cca05db9e6ff6918a5`
+- DSH authority: `deepseek-ai/deepseek-harness@639ed015397290b3745d163aafe02ffee4aa3f84` (`0.2.0-rc.2`)
+- package version: `2.3.0`
+- version bump / tag / npm publish: **not part of R10**
+
+R10 is a post-R9 correctness closure. It does not reopen the 3.0 architecture program,
+and it does not broaden the TypeScript migration. It reviews the implementation after
+current `main` was absorbed into `3.0`, then repairs concrete runtime, lifecycle,
+source-ownership, public-contract, and release-order defects found by code review.
+
+## Closure decisions
+
+### 1. Provider transport restores module-time Host fetch ownership
+
+The TypeScript migration had changed the module-time `globalThis.fetch.bind(globalThis)`
+snapshot into a wrapper that re-read `globalThis.fetch` on every request. That made the
+Router-owned direct-provider transport re-enter process-wide fetch wrappers installed
+later by Core/compat layers.
+
+R10 restores a real module-time bound fetch snapshot. The transport may still observe the
+live Undici global dispatcher as designed; it no longer observes later replacement of the
+`globalThis.fetch` function itself.
+
+### 2. Dynamic Host tool definitions keep runtime validation
+
+`vision-attachment-handle-runtime` again treats tool definitions as runtime Host input.
+Nullish or malformed registrations are passed through for Host-owned validation instead
+of throwing inside DVR merely because a TypeScript generic describes the expected shape.
+
+This preserves the 3.0 rule that static typing never replaces validation at dynamic Host
+boundaries.
+
+### 3. Optional Cordis capabilities use non-owning lookup semantics
+
+R10 removes remaining direct optional-service property fallbacks for:
+
+- `sessionQuery`;
+- `sessionProjections`;
+- `systemPrompt`;
+- `attachments`.
+
+These paths now use `Context#get` capability probes. Required services continue to be
+owned through the existing `inject`/composition seams. This prevents optional detection
+from accidentally becoming a Cordis pending dependency.
+
+### 4. Session Vision sidecar owns its complete async lifecycle
+
+The Session Vision policy domain now binds its consumer effect before asynchronous
+`storageDomain.open()` begins. Unload/HMR can therefore await and close an eventual late
+handle instead of leaving a same-name domain open in the longer-lived facility.
+
+The store also:
+
+- retires an old domain before opening against a replacement facility;
+- closes stale/late opens exactly once;
+- degrades to volatile authority after a storage failure without losing the current
+  in-process Session decision;
+- evicts durable hot-cache rows at Agent disposal while keeping durable Session truth for
+  future cold resume.
+
+Persistent policy retention remains Session-scoped by design; R10 does not add an
+arbitrary TTL that would break cold-resume semantics.
+
+### 5. User Session authority is connected to the official durable selection fact
+
+DSH rc.2 records explicit Session model changes as the durable `model/selection` event.
+R10 consumes that committed event and materializes DVR `source: 'user'` Session Vision
+policy from the exact selected route.
+
+This completes the authority model that already allowed user policy to outrank an
+inherited delegation snapshot. Delegation still creates a child-local snapshot and later
+parent changes do not retroactively mutate that child; a later explicit selection in the
+child Session can now override the inherited snapshot through a real production path.
+
+### 6. Package-root declarations match the package-root runtime
+
+`public-entry.d.ts` no longer exposes the internal third `runtime` argument of
+`src/entry.js` through package-root `apply()`. The package wrapper owns provider transport
+creation, so consumer injection of that internal seam is not public API.
+
+`installHostSettingsCompatibility` now declares and enforces both `namespace` and `Config`
+as required. The declaration source is included in the Host TypeScript program, and the
+packed consumer contract contains negative type assertions for both invalid calls.
+
+### 7. Provider transport teardown is an awaited Cordis disposer
+
+The public entry returns the transport-disposal Promise from its effect disposer instead
+of discarding it. HMR/plugin unload therefore waits for Router-owned dispatcher leases and
+ProxyAgent cleanup. The synchronous apply-failure path starts the same idempotent cleanup
+and absorbs cleanup rejection while rethrowing the original apply failure.
+
+### 8. CI triggers now follow canonical source ownership
+
+After R1, `src/**` is canonical and root `entry.js` / `index.js` / `lib/**` are generated
+package artifacts. R10 migrates workflow path filters and the CI impact classifier to the
+canonical source paths, including the real `.ts` extension for migrated owners.
+
+A repository contract now rejects workflow trigger ownership by generated package paths
+and verifies every literal canonical `src/**` trigger resolves to a real source file.
+
+### 9. Release correctness preserves both pre-tag verification and pack-once
+
+The release workflow no longer creates a new immutable tag before the exact package
+candidate is packed and inspected.
+
+The release sequence is now:
+
+```text
+verify exact main source
+  -> build / type / test / source-artifact gates
+  -> pin npm client
+  -> npm pack exactly once
+  -> verify packed public API
+  -> probe existing npm version against tarball SHA-1
+  -> persist exact tarball as same-run artifact
+  -> create/verify immutable tag
+  -> rehydrate the same tarball
+  -> verify SHA-1 + SHA-256 handoff
+  -> publish that exact tarball with trusted OIDC
+  -> registry identity wait + attestation + GitHub Release
+```
+
+This closes the tag-before-pack failure window without weakening the pre-existing
+pack-once / exact-tarball / provenance model.
+
+## Negative review
+
+R10 deliberately did **not**:
+
+- rewrite `src/index.js` or the mature Core; it remains byte-identical to current
+  `origin/main:index.js` at the implementation checkpoint;
+- introduce a generic `DvrContext`, Host facade, DI/service locator, global runtime owner,
+  or second source tree;
+- raise the browser `262144` byte gate; `src/lib/client.js` remains `261672` bytes;
+- convert the production browser client merely to increase TypeScript percentage;
+- add DSH private `/src/*` runtime imports;
+- change the advertised Host support window;
+- bump the package to `3.0.0`, create a tag, or publish a release.
+
+## Explicitly retained findings
+
+The following findings were intentionally kept outside R10 and remain visible for future
+work rather than being hidden by the closure:
+
+1. `runtime-composition.js` is still a JavaScript composition root. Its phase objects are
+   not compiler-enforced contracts. R10 does not convert it merely to satisfy a language
+   metric.
+2. `tsconfig.client.json` protects the browser-only compiler world, but production
+   `src/lib/client.js` is not under strict TypeScript/checkJs coverage. The R5 production
+   Browser TypeScript switch remains No-Go under the frozen size/build constraints.
+3. R9 remains historical evidence for `1e331b1`; R10 is the post-main correctness
+   checkpoint and does not rewrite R9 as though it had audited this later code.
+
+## Local implementation evidence
+
+At `b38d427d54024f739dabbb3dacf389dc719a960f` plus the documentation-only closure that
+follows it:
+
+```text
+canonical source files            182
+canonical runtime TS owners        38
+canonical public declarations       1
+canonical package artifacts       182
+browser client bytes           261672
+browser hard gate              262144
+```
+
+Source-to-artifact evidence digest:
+
+```text
+2a9f8d2c2ed1f60506871a0237383fd8e31304296360c1193009cfbf300a8821
+```
+
+Local post-fix validation completed with:
+
+- generated artifacts: `182/182` in sync;
+- Host + Client typecheck: pass;
+- source ownership lint: pass;
+- no remaining audited direct optional-service property reads;
+- main regression: `1605 tests / 1604 pass / 0 fail / 1 skip`;
+- backend runtime policy: `10/10` pass;
+- reproducible build: `182` artifacts verified;
+- targeted R10 transport/release/trigger regressions: pass;
+- workflow YAML parse: pass;
+- canonical workflow literal trigger audit: `0` invalid paths.
+
+These gates verify the repaired implementation; they are evidence after the code review,
+not a substitute for the code review that produced R10.
+
+## Exit decision
+
+R10 closes the concrete correctness defects found after R9 and after current `main` was
+absorbed into `3.0`. PR #621 has been reviewed for mergeability and integrated into `3.0`. The integrated
+branch is `0` commits behind current `main`; GitHub-side Host/Desktop/package evidence
+can now run against the integrated R10 head as part of the later 3.0 release-candidate
+phase. No further architecture migration pass is justified by R10 itself.