dsh-vision-router 2.0.0 → 2.1.0

package/docs/architecture/dsh-compatibility-matrix.md

@@ -0,0 +1,57 @@
+# DSH compatibility matrix
+
+This document is the P0 compatibility baseline for dsh-vision-router 2.x.
+
+The matrix is capability-based. Runtime code must feature-detect the seam it needs; it must not branch on a DSH version string merely to select a behavior. Version labels below name the CI fixtures that prove each capability.
+
+## Gating fixtures
+
+| CI fixture | DSH package line | Role |
+| --- | --- | --- |
+| `minimum-contract` | `0.1.0-rc.6` | Minimum supported Host contract. Must remain green. |
+| `legacy-contract` | `0.1.0-rc.8` | Legacy contract carrying batch attachments and dimension policy. |
+| `current-contract` | `0.1.1-rc.2` | Current contract baseline for 2.x convergence. Must be green before P1. |
+| `latest-dsh` | resolved dynamically from npm | Scheduled canary only. Never a normal PR required check. |
+
+Node 22 and Node 24 remain the general required runtime matrix. The Host contract jobs are additive; they do not replace the normal test matrix.
+
+## Capability matrix
+
+`yes` means the fixture has a direct positive test or feature probe. `no` means a direct negative probe exists. `compat` means the fixture proves Vision Router can safely carry the newer input/config through that Host, but does **not** claim the Host owns that capability. `probe` means the capability is intentionally not inferred from the version label and is verified at runtime/contract-test time.
+
+| Capability | minimum-contract rc.6 | legacy-contract rc.8 | current-contract rc.2 | Evidence / detection |
+| --- | --- | --- | --- | --- |
+| Batch attachment save | no | yes | yes | `hasBatchAttachmentContract()` checks the released `attachments.saveImages` prototype; `tests/rc6-rc7-compat.test.js`; contract CI. |
+| Max image dimension policy | compat | yes | yes | All fixtures parse the complete attachment-local row; rc.8/current positively retain the field and the established admission tests exercise the 10000/10001 boundary. Older Schemastery passthrough is not treated as ownership evidence. |
+| Adapter registration | yes | yes | yes | released `ctx.llm.registerAdapter` surface plus adapter contract tests. |
+| Atomic registration replace | probe | probe | yes | current-contract exercises the real registration handle's `replace()` and disposer; Doctor reports `unknown` if a live Host cannot prove replacement without mutating topology. |
+| Settings live namespace | yes | yes | yes | `settings.register()` + live `scope.get()/watch()` compatibility tests; current-contract mounts the real SettingsProvider contract through a minimal storage subclass. |
+| Tool registration / execution | probe | probe | yes | current-contract mounts the released `@deepseek-ai/dsh-tools` runtime, registers a typed tool, executes it, and disposes it; Vision Router tool-runtime boundary tests remain additive. |
+| `prepareCall` | no | no | yes | `tests/adapter-prepare-call-compat.test.js`; current-contract exercises the installed LLM runtime's `prepareCall()`. |
+| Native image coexistence | yes | yes | yes | `tests/native-image-coexistence.test.js`, `tests/issue-289-native-nonintervention.test.js`, cold-resume workflow. |
+| Jobs service | probe | probe | probe | read-only Doctor capability probe only; P2 must run a separate feasibility spike before any scheduler migration. |
+| Client surface replacement | probe | probe | probe | no version inference; keep `unknown` until a safe readable Host seam is available. |
+| Settings web exposure | probe | probe | probe | presentation capability; never inferred from the settings persistence service. |
+| Effect/dispose cleanup | yes | yes | yes | compatibility lifecycle tests plus current-contract adapter/tool/watch disposer checks; plugin registrations remain Cordis-effect owned. |
+| Public entry boot | yes | yes | yes | packed plugin public entry import in each Host contract fixture. |
+| Packaged tarball install | yes | yes | yes | each Host contract fixture packs the plugin then installs the tarball into an isolated Host package. |
+
+## Compatibility inventory and exit criteria
+
+Every compatibility seam must answer the same six questions: **Reason**, **Host gap**, **First needed for**, **Feature detection**, **Removal condition**, and **Tests**. Source modules carry the detailed annotation; this table is the architectural index.
+
+| Seam | Reason / Host gap | Feature detection | Removal condition | Primary tests |
+| --- | --- | --- | --- | --- |
+| `lib/dsh-contract-compat.js` | Keep rc.6 single-attachment behavior, rc.8 attachment overlay repair, and settings/provider ownership semantics across the support window. | attachment/settings/LLM methods, never a version string. | Supported Host window provides the needed public seams natively and minimum supported DSH advances beyond the gap. | `rc6-rc7-compat`, `rc6-real-settings-persistence`, `attachment-admission-policy`, contract CI. |
+| `lib/adapter-update-coalescer.js` | Older Vision Router adapters are duck-typed while DSH 0.1.1 dispatches through `prepareCall`; synchronous topology events can re-enter reconciliation. | adapter has `prepareCall`; event behavior is bounded by the coalescer. | All supported adapters implement the Host contract directly and no supported Host needs the reconciliation guard. | `adapter-prepare-call-compat`, adapter/runtime regression tests. |
+| `lib/android-attachment-compat.js` | Termux/Android file persistence can fail at the permission boundary on the minimum Host contract. | actual Android/Termux environment plus permission-boundary failure and absence of batch attachment ownership. | Minimum supported Host owns a working Android attachment store for this path. | `android-attachment-compat`, resource tests. |
+| `lib/replay-envelope-v2-compat.js` | Durable replay producer identity moved into the v2 replay envelope. | exact `response.kind === 'pi-ai' && response.version === 2` producer proof. | Support window no longer contains histories/runtime needing the old source normalization. | `replay-delegation`, replay/session tests. |
+| `lib/pi-ai-bridge-wire-compat.js` | The legacy direct image bridge predates pi-ai declared wire compatibility. | exact non-streaming image bridge fingerprint and resolved pi-ai route/model facts. | Direct bridge is removed or every supported Host executes the request through the native pi-ai wire contract. | `pi-ai-bridge-wire-compat`, native process-restart contract. |
+| `lib/settings-client-rc8-lifecycle.js` | Browser-side settings lifecycle differs across supported Host generations. | browser/runtime surface behavior, not DSH version parsing. | Support window exposes one stable settings client lifecycle. | settings IA/lifecycle regression tests. |
+
+## Rules
+
+1. A new version-specific branch requires evidence that no stable capability probe exists.
+2. A compatibility layer may narrow behavior to preserve an existing product contract; it may not expand routing authority.
+3. `latest-dsh` can reveal upstream drift, but a canary failure must not silently redefine the supported contract.
+4. P1 may begin only when all three gating fixtures and the existing cold-resume/resource baselines are green.

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

@@ -0,0 +1,50 @@
+# DSH Host support window
+
+Status: normative for the DVR 2.x compatibility program.
+
+## Current DVR 2.1.x window
+
+| Role | DSH train | Meaning |
+|---|---|---|
+| Minimum Supported Host | `0.1.0-rc.8` | Oldest Host generation that DVR 2.1.x publicly supports. |
+| Previous Supported Train | `0.1.1-rc.1` | Previous released Host train kept in the compatibility matrix. |
+| Current Supported Train | `0.1.1-rc.2` | Current released train used by the required current-contract gate. |
+| Canary only | `0.1.2-alpha.4` | Latest upstream prerelease evidence at v2.1.0 release preparation time. It is not a released support-floor claim and does not authorize compat deletion by itself. |
+
+DVR `2.1.x` therefore supports DSH `0.1.0-rc.8` and newer released trains covered by the published matrix. Runtime branching remains capability-based rather than version-string-driven.
+
+## Floor transition from DVR 2.0.x
+
+DVR 2.0.x was released with DSH `0.1.0-rc.6` as its minimum Host. The 2.1.0 boundary was announced in advance and raises the public minimum to DSH `0.1.0-rc.8`.
+
+```text
+DVR 2.0.x minimum: DSH 0.1.0-rc.6
+DVR 2.1.x minimum: DSH 0.1.0-rc.8
+```
+
+Users still on rc.6/rc.7 should upgrade DSH before upgrading to DVR 2.1.x.
+
+This support-floor transition does **not** require deleting every rc.6-era compatibility seam in the same release. Compatibility code is retired only after a separate proof shows it is unreachable or unnecessary on every supported Host and durable-history path.
+
+No later support-floor increase is currently announced.
+
+## Support-window change protocol
+
+A Host support-floor change is valid only when all of the following are true:
+
+1. the change is announced in a DVR minor or major release, never only in a patch release;
+2. README / support documentation and release notes state the old and new floors;
+3. Doctor reports the effective support window and gives a capability-based upgrade result for Hosts below the active floor;
+4. required CI has stable minimum, previous, current, and canary evidence for the declared window;
+5. compatibility seams are removed only after the new minimum Host proves the replacement capability;
+6. removal PRs keep restart, settings, native-image coexistence, tool execution, Node 22/24 and supported-platform regressions green.
+
+## Capability-first rule
+
+Version labels describe the public support window; runtime branching still uses capabilities.
+
+DVR must not turn this table into widespread version-string conditionals. Runtime compatibility continues to feature-detect the concrete Host seam it needs. If a capability cannot be proven safely, the compatibility path fails open or reports an explicit unsupported/unknown state according to that seam's contract.
+
+## Compatibility-retirement rule
+
+The 2.1.x floor makes rc.6-only compatibility candidates eligible for a fresh deletion audit, but does not automatically authorize deletion. Durable session formats, replay envelopes, adapter wire shapes, and other historical inputs may outlive the Host version that originally produced them.

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

@@ -0,0 +1,148 @@
+# 2.x Architecture Closure — final adversarial audit
+
+Audit baseline: `main@1c11c1c3c7046268ae1c7b8f2287b023aeb1eb26` (after C3-B / PR #339).
+
+This document records the final adversarial architecture review. It is not a feature roadmap and does not claim that PDF, video, CAD or GUI-agent support exists. The final `CLOSED` declaration is allowed only after the accompanying final Closure gate is merged and the resulting `main` gates are green.
+
+## Severity result
+
+| Severity | Structural blockers |
+| --- | ---: |
+| High | 0 |
+| Medium | 0 |
+
+No remaining finding establishes a second semantic owner for Authority, routing, Session recovery/surface repair, Artifact storage, Router-owned provider HTTP, Host product decisions, or browser presentation.
+
+## Single-owner result
+
+| Semantic responsibility | Current owner | Permanent evidence |
+| --- | --- | --- |
+| User routing/background authority | `lib/vision-routing-authority.js` | P1 routing parity + Architecture Closure |
+| Capability evidence collection | `lib/vision-routing-evidence.js` | routing evidence/runtime parity |
+| Capability planning/scoring | `lib/vision-capability-router.js` | P1 routing parity |
+| Scoped execution order | `lib/vision-execution-order.js` | execution-order wiring/parity |
+| Session indexing, durable recovery and surface repair | `lib/session-vision-index.js` | `session-runtime-core-wiring.test.js` |
+| Session bounded state | `lib/session-vision-state.js` | Session runtime/state integration gates |
+| Managed artifact publication/lifetime | `lib/vision-artifact-store.js` | artifact boundary/store gates |
+| Router-owned provider HTTP | `lib/vision-provider-transport.js` | P2 provider-transport gates |
+| Host product/presentation decisions | `lib/vision-product-presentation.js` | presentation convergence/switch gates |
+| Browser rendering | Web benchmark client/panel | browser second-owner algorithms are forbidden by `presentation-switch.test.js` |
+
+## Duplicate-owner adversarial checks
+
+### Session
+
+- Production creates one explicit `SessionVisionRuntime` and supplies the same index owner to the Session boundary and Core.
+- `currentSessionVisionStateStore`, module-global `currentStore`, lookup monkey-patching and the old Core scan/recovery/surface-repair algorithms are forbidden by the Closure suite.
+- Repository search at the audit baseline finds `currentSessionVisionStateStore` only inside the test that forbids its return.
+
+Result: **PASS**.
+
+### Core policy / Settings impersonation
+
+`legacy-core-vision-policy-bridge.js` retains only two real pre-step compatibility behaviors. The Closure suite forbids projected Settings/config/scope/child views and forbids interception of `ctx.get('settings')` or injected Settings children.
+
+Result: **PASS**.
+
+### Browser product ownership
+
+The browser consumes Host candidate `presentation` state. The final switch gate forbids browser implementations of background eligibility, deferred/excluded interpretation, measured-text-only inference and the retired runtime-status fetch/switch shim.
+
+Result: **PASS**.
+
+### Capability shadow
+
+`lib/vision-capability-shadow.js` and its historical test path are deleted. A recursive gate forbids imports of the retired shadow surface from production, tests or scripts.
+
+Result: **PASS**.
+
+## Compatibility result
+
+The normative compatibility inventory now requires every retained seam to document:
+
+- reason;
+- Host/internal gap;
+- feature/capability detection;
+- removal condition;
+- tests.
+
+The inventory-completeness gate covers 11 retained seams.
+
+Two notable retained items are intentionally **not blockers**:
+
+1. `legacy-core-vision-policy-bridge.js` remains for the two supported pre-step behaviors described above.
+2. `vision-provider-transport.js` retains one scoped process/profile registry because mature OpenAI-compat and Anthropic catalog-correction callers still read `currentVisionProviderTransport()`. Its install/release lifecycle and deletion trigger are explicit.
+
+A repository-wide audit of the exact `const installed = []` pattern found only the inventoried VisionProviderTransport registry. The retired Session current-owner locator is absent from production.
+
+Result: **PASS / justified compatibility only**.
+
+## Future-modality tabletop
+
+The Closure architecture is tested against hypothetical future additions:
+
+- PDF;
+- video;
+- CAD screenshot;
+- GUI agent;
+- `1+X` structured-first / free-follow-up vision.
+
+These are architecture scenarios, not implemented features.
+
+An acceptable future change may add:
+
+- capability vocabulary;
+- evidence/intent mapping;
+- an operation/tool or model path;
+- presentation state when needed.
+
+The tabletop fails if the feature proposal requires a new semantic infrastructure owner such as:
+
+- Settings proxy/impersonation;
+- new context wrapper carrying internal policy semantics;
+- new module-global runtime registry;
+- new Session cache/owner;
+- new Host patch or lifecycle exception used to bypass existing owners.
+
+`tests/final-architecture-closure.test.js` also binds the tabletop to the real current owner modules and recursively checks production for hidden module-global `current*` owners and unregistered `installed[]` registries.
+
+Result at audit design time: **PASS, pending final PR/main execution**.
+
+## Long-term anti-regression gate
+
+Architecture Closure permanently carries these constituent gates:
+
+- external/cross-boundary contract baseline;
+- compatibility inventory completeness;
+- Settings impersonation closure;
+- Host-presentation/browser switch closure;
+- capability-shadow retirement;
+- Session runtime/Core single-owner wiring;
+- final owner/tabletop/runtime-locator closure gate.
+
+This deliberately protects ownership/dependency direction rather than trying to make every occurrence of words such as `legacy`, `Proxy` or `current` illegal.
+
+## Regression evidence on the C3-B merged baseline
+
+Exact baseline: `1c11c1c3c7046268ae1c7b8f2287b023aeb1eb26`.
+
+- Architecture Closure: run `33258346425`, Node 22/24 success.
+- P3 Compatibility Convergence: run `33258346400`, Node 22/24 success.
+- DSH Contract: run `33258346423`, minimum/legacy/current success.
+- P1 Routing Parity: run `33258346406`, Node 22/24 success.
+- P2 Data Boundary: run `33258346424`, all Node 22/24 boundary jobs success.
+- Native multimodal cold resume: run `33258346404`, rc.7/rc.8 on Node 22/24 success.
+- CI: run `33258346403`, Node 22/24, rc.6/rc.7/rc.8 and Ubuntu/macOS/Windows success.
+- CodeQL: run `33258346338`, Actions and JavaScript/TypeScript analyses success.
+
+## Final decision rule
+
+At this baseline the adversarial audit has **zero High/Medium structural blockers**. Architecture convergence must not be declared closed merely from this document or from a green PR.
+
+Closure becomes final only when:
+
+1. the future-modality/runtime-locator gate in this final PR passes;
+2. the final PR is merged normally;
+3. the resulting `main` SHA passes the required and Architecture Closure gates (plus the normal regression/security matrix triggered by the change).
+
+After those conditions are met, stop architecture convergence rather than continuing purity refactors. Future PDF/video/1+X work belongs to product PRs that must respect these owner boundaries.

package/docs/architecture/p2-jobs-feasibility.md

@@ -0,0 +1,94 @@
+# P2-F — `ctx.jobs` Feasibility Spike
+
+Status: **NO-GO: retain current scheduler**
+
+Reviewed against:
+
+- DeepSeek Harness `main` at `cd5ef8148158c3a752a658978873241fdf8e2bbc` (`dsh@0.1.2-alpha.1` release merge, 2026-08-27).
+- Official Jobs subsystem contract: `docs/subsystems/jobs.md` at the same commit.
+- Vision Router `createBackgroundCapabilityProfiler()` and its current regression suites.
+
+This is a feasibility result, not a rejection of `ctx.jobs` as a Host feature. Jobs is the correct generic long-running-work registry when its ownership model matches the producer. The question here is narrower: **would replacing Vision Router's background capability scheduler with `ctx.jobs` reduce custom lifecycle code without weakening routing authority, priority, or restart semantics?** The answer is no on the current Host contract.
+
+## Host contract observed
+
+The current DSH Jobs contract provides:
+
+- atomic registration and lifecycle state;
+- optional exact `Agent` ownership with session-fenced access;
+- unowned jobs when no owner is supplied;
+- cancellation, bounded wait, output/status reads and completion listeners;
+- owner disposal and service disposal cancellation/await semantics;
+- an attached-controller admission fence: `start()` refuses work when no attached job controller serves the selected owner;
+- one registry across process compositions, with visibility/delivery determined by the registering context and owner.
+
+It does **not** define a producer-independent priority scheduler. In particular, the Jobs contract has no native concept of:
+
+```text
+foreground visual work
+  > manual capability benchmark
+  > unattended background benchmark
+```
+
+Nor does it know Vision Router's live measurement authority, endpoint identity/fingerprint, local-free eligibility, topology revision, or publish fence.
+
+## Ten required checks
+
+| # | Requirement | Current scheduler | `ctx.jobs` as replacement | Result |
+|---|---|---|---|---|
+| 1 | profile-wide job ownership | Profiler is installed once on the plugin composition/capability store and is not session-owned. | An **unowned** Job can be profile/process-visible, but an owned Job is tied to an exact Agent and requires a serving controller. Choosing unowned preserves profile scope but gains no useful owner lifecycle over the current profiler. | **No migration benefit** |
+| 2 | Web settings page close must not stop work | Background profiler lives in the plugin fiber; the Web route is only a status/control projection. Closing the page does not own the profiler. | Possible only if the Job registration/controller is kept outside the page/client scope. This adds composition/controller placement constraints rather than removing them. | **Current is simpler** |
+| 3 | plugin dispose immediately terminates work | `installBackgroundCapabilityProfiling()` registers an effect disposer that unregisters listeners and calls `profiler.stop()`, which aborts current work. | Jobs service/owner disposal can cancel and await compliant producers. | **Jobs capable, no decisive gain** |
+| 4 | `all → off` immediately aborts | Policy polling and `settingsChanged()` revoke authorization and abort the active controller; yielded work does not receive provider backoff. | Jobs can carry a `cancel()` hook, but it does not observe Vision Router settings or infer authority revoke. We would retain the same settings watcher/policy logic to call it. | **No lifecycle reduction** |
+| 5 | `all → local-free` narrows correctly | `workStillAuthorized()` re-evaluates live authority and candidate eligibility; paid work aborts while eligible local work may continue. | Jobs has no backend/authority semantics. The same Vision Router eligibility code must remain outside the registry. | **No lifecycle reduction** |
+| 6 | manual Benchmark preempts background | `manualStart()` increments a lease, aborts current background work, and blocks new background ticks until all manual work releases. | Jobs has no cross-kind priority/preemption contract. We would have to rebuild the same arbitration above Jobs. | **FAIL as replacement** |
+| 7 | foreground visual work has highest priority | `foregroundStart()` immediately aborts background work and resets the idle window; foreground tool wrappers bracket activity. | Jobs has no producer-independent priority/preemption contract. | **FAIL as replacement** |
+| 8 | headless behavior | Scheduler depends on settings/core/store/timers, not on a browser page or Agent owner. | An unowned Job can be headless, but an owned Job adds owner/controller admission requirements. Using unowned Jobs again removes the principal ownership benefit. | **Current is simpler / fewer assumptions** |
+| 9 | process restart semantics | Work itself is intentionally not resumed. On restart the scheduler reconstructs from persisted measured evidence, image verdicts and bounded background-stop records, then chooses fresh work. | Current JobRegistry is a process-local lifecycle registry; the documented contract does not provide durable replay/resume of producer work. We would still need Vision Router's persisted evidence/stop semantics. | **No migration benefit** |
+| 10 | background stop/evidence publish fencing | Before `store.put`, `assertBackgroundPublishable()` rechecks live authority, current candidate existence, benchmarkability, endpoint fingerprint and current background eligibility. Persistent stops are separately bounded and credential-aware. | Jobs settlement records generic lifecycle state; it does not validate model identity, fingerprint, routing authority, or evidence publication. The full fence must remain. | **FAIL as simplification** |
+
+## GO criteria evaluation
+
+The implementation plan allows migration only if Jobs satisfies all of these architecture outcomes.
+
+| GO criterion | Evaluation |
+|---|---|
+| Reduce custom lifecycle code | **FAIL.** Priority, settings/topology invalidation, eligibility and publish fencing all remain; Jobs adds registration/controller placement. |
+| Do not weaken authority revoke | Achievable only by retaining the current revoke logic around Jobs; therefore no simplification. |
+| Preserve priority | **FAIL natively.** Current DSH Jobs has no foreground/manual/background priority contract. |
+| Preserve Web-close continuation | Achievable only with careful unowned/profile-scoped registration, which adds scope assumptions. |
+| Do not add session-owner assumptions | **FAIL for owned Jobs;** unowned Jobs avoid the assumption but also discard the ownership benefit. |
+
+## Decision
+
+```text
+NO-GO: retain current scheduler
+```
+
+This is a successful P2-F outcome under the implementation plan.
+
+The current `createBackgroundCapabilityProfiler()` remains production authority for unattended benchmark scheduling. `ctx.jobs` should be reconsidered only if a future Host contract adds a generic priority/resource scheduler or a profile-scoped owner/controller seam that demonstrably eliminates Vision Router's custom arbitration rather than wrapping it.
+
+## Evidence / regression coverage
+
+Current repository tests already exercise the semantics that a migration would have to preserve:
+
+- `tests/vision-background-benchmark.test.js`
+  - foreground abort/preemption;
+  - manual benchmark lease/preemption;
+  - `all → off` revoke;
+  - `all → local-free` narrowing;
+  - topology-change abort;
+  - local-free eligibility.
+- `tests/vision-background-lifecycle.test.js`
+  - bounded persistent-stop lifetime;
+  - credential-rotation release;
+  - failure-lifetime separation.
+- `lib/vision-background-benchmark.js`
+  - plugin effect disposal;
+  - headless timer ownership;
+  - pre-publish live authority / candidate / fingerprint fence.
+
+Official DSH reference used for the spike:
+
+- `https://github.com/deepseek-ai/deepseek-harness/blob/cd5ef8148158c3a752a658978873241fdf8e2bbc/docs/subsystems/jobs.md`

package/docs/architecture/p3-compat-retirement.md

@@ -0,0 +1,46 @@
+# P3-B compatibility retirement audit
+
+Decision date: 2026-08-28
+
+Current DVR train: `2.0.x`
+
+Current minimum supported Host: DSH `0.1.0-rc.6`
+
+## Result
+
+**NO COMPAT DELETION IS CURRENTLY AUTHORIZED.**
+
+P3-B is intentionally a retirement audit, not a quota to delete files. Under the current 2.0.x support window, every Host-generation compatibility seam that materially exists for rc.6/rc.8 users still has a reachable support case.
+
+## Seam review
+
+| Seam | Why it still exists in 2.0.x | Earliest retirement trigger |
+|---|---|---|
+| attachment contract / Android attachment fallback | rc.6 remains the minimum and does not provide the later batch-attachment contract used by the modern path | after the released minimum Host no longer needs the single-attachment/permission fallback and the replacement is proven on the new minimum |
+| Host settings compatibility | rc.6 remains supported; live settings/client behavior differs across the support window | after the new minimum exposes the stable settings seam used by DVR without compatibility wrapping |
+| rc.8 browser/client lifecycle compatibility | rc.8 is still inside the declared support window and remains the Previous Supported Train | only after rc.8 itself leaves the support window or the same path becomes unreachable by capability proof |
+| replay envelope v2 compatibility | old durable histories remain valid inputs even when the live Host is newer | only when the supported history/runtime window no longer needs producer rebinding or Host provides an equivalent native replay identity seam |
+| adapter prepareCall/coalescing compatibility | the support matrix still spans Host generations with different adapter-registration/update behavior | only when the minimum Host and every DVR-owned adapter satisfy one stable registration/update contract |
+| pi-ai bridge wire compatibility | legacy direct-bridge traffic remains a supported route shape | only after the direct bridge is retired or all supported Hosts execute that path through an equivalent native wire seam |
+| process-global proxy compatibility | P2-E already reduced this to Host-owned/raw-fetch compatibility only; the minimum Host still lacks a provider-scoped/shared proxy seam | when the minimum supported Host provides a provider-scoped/shared HTTP proxy seam |
+
+## First planned deletion window
+
+The announced DVR 2.1.0 floor is DSH `0.1.0-rc.8`. That boundary makes **rc.6-only** compatibility candidates eligible for a fresh deletion audit, but it does not automatically delete them.
+
+Each deletion still requires proof on:
+
+- minimum Host;
+- current Host;
+- process restart / cold resume;
+- settings read/write behavior;
+- native multimodal coexistence;
+- tool registration and execution;
+- Node 22 and Node 24;
+- Ubuntu, macOS and Windows where the seam affects runtime/platform behavior.
+
+## P3-B verdict
+
+`PASS — no expired seam under the current 2.0.x support window.`
+
+Deleting a still-supported rc.6 seam merely to make the compatibility inventory smaller would violate the P3 plan and the published 2.0.x compatibility contract.

package/docs/architecture/p3-host-native-seams.md

@@ -0,0 +1,43 @@
+# P3-D Host-native seam migration evaluation
+
+Decision date: 2026-08-28
+
+Support window: DVR `2.0.x` / minimum DSH `0.1.0-rc.6` / previous `0.1.0-rc.8` / current `0.1.1-rc.2`.
+
+P3-D permits a migration only when all four conditions are true:
+
+```text
+official API stable
++ minimum Host supports it
++ parity proved
++ replacement is simpler
+```
+
+Current result: **NO NEW HOST-NATIVE MIGRATION IS AUTHORIZED IN DVR 2.0.x.**
+
+| Candidate | Current evidence | Decision |
+|---|---|---|
+| settings exposure | Newer Hosts expose stronger live settings seams, but rc.6 remains the minimum and existing compatibility is still required for the supported window | NO-GO in 2.0.x |
+| provider transport / proxy | P2-D moved Router-owned HTTP to `VisionProviderTransport`; P2-E reduced the global patch to Host-owned/raw-fetch compatibility. The minimum Host still has no proven provider-scoped/shared proxy seam | KEEP P2 boundary; no native migration |
+| `ctx.jobs` | P2-F's ten-point spike found that Jobs does not replace DVR's priority, authority-revoke, topology-abort and evidence-publication fencing without retaining the custom scheduler | NO-GO; retain current scheduler |
+| adapter registration replacement | Current Host generations expose better replacement behavior, but a read-only capability probe cannot prove a stable returned handle across the full minimum/previous/current window | NO-GO until minimum Host contract and parity tests prove one handle contract |
+| scoped tool execution hooks | Current DSH has richer tool pipeline seams, but the rc.6 support floor and existing mature wrapper behavior mean a migration would be a split-path compatibility rewrite rather than simplification | NO-GO in 2.0.x |
+
+## Important distinction
+
+P3-D is not a requirement to consume every API present on upstream `main`. A seam visible only on a development/canary Host does not satisfy the support-window rule.
+
+Likewise, a native seam that still requires DVR to keep the old implementation for the minimum Host fails the "replacement is simpler" criterion unless the split itself has a concrete product or reliability benefit.
+
+## Revisit trigger
+
+Re-run this matrix when one of these occurs:
+
+1. DVR 2.1.0 actually raises the minimum Host to rc.8;
+2. a released DSH train exposes a provider-scoped/shared proxy contract;
+3. adapter replacement or tool-execution hooks become stable on the declared minimum Host;
+4. upstream Jobs semantics materially change enough to satisfy the P2-F go criteria.
+
+## P3-D verdict
+
+`PASS — evaluated; no migration currently meets the plan's four mandatory conditions.`

package/docs/architecture/p3-native-recovery-evaluation.md

@@ -0,0 +1,65 @@
+# P3-E native request recovery vs Vision Chain
+
+Decision date: 2026-08-28
+
+Upstream evidence baseline: DeepSeek Harness `main@cd5ef8148158c3a752a658978873241fdf8e2bbc` (`dsh@0.1.2-alpha.1` release merge) plus the released support window used by DVR 2.0.x.
+
+## Question
+
+Can DSH-native `agent/request`, `agent/request-error`, `llm/stream` and Host retry semantics replace DVR's mature synthetic `vision-chain` without losing behavior?
+
+## Result
+
+**KEEP `vision-chain`.**
+
+The upstream retry executor is intentionally an agent-loop request-recovery mechanism. It handles a failed model request at the open-step `agent/request-error` boundary and re-runs that step under the selected provider's retry policy. Its own package contract states that it does **not** wrap the streaming call itself and that direct `ctx.llm.stream()` consumers remain single-attempt.
+
+That is useful Host behavior, but it is not the same execution problem as DVR's visual backend chain.
+
+## Required semantic comparison
+
+| Required DVR behavior | Native recovery fit | Finding |
+|---|---|---|
+| cross-provider fallback | insufficient | Host retry is provider-policy request recovery; DVR must deliberately move across visual backends/providers |
+| shared total deadline | insufficient as replacement | DVR owns one visual-task deadline across multiple backend attempts; independent Host retries can add latency/budget unless separately fenced |
+| fair per-backend budget | insufficient | DVR reserves bounded attempt budgets so one backend cannot consume the whole visual task |
+| circuit breaker | not replacement-equivalent | DVR breaker is backend/deployment-aware and integrated with fallback selection |
+| exact route identity | partial | Host retry preserves/reconstructs a request identity, but DVR also needs exact candidate/deployment identity while changing backends |
+| no retry amplification | risk | stacking provider retry with DVR fallback can multiply attempts unless one layer is explicitly disabled/fenced |
+| cancellation | supported by Host retry, already supported by DVR | not a simplification by itself |
+| v1/legacy Host | insufficient | DVR 2.0.x still supports rc.6; current upstream recovery semantics cannot become the sole path |
+
+## Why a split modern path is not adopted
+
+A modern-Host-only native recovery branch would still need DVR's own:
+
+- cross-provider candidate loop;
+- shared total deadline;
+- per-attempt budget;
+- breaker/failure classification;
+- exact deployment identity;
+- cancellation fencing;
+- legacy/minimum-Host path.
+
+That creates two recovery authorities without deleting the hard part of the current executor. It therefore fails the P3 migration rule that a Host-native replacement must be semantically equivalent **and simpler**.
+
+## Interaction with Host retry
+
+DVR should continue to treat Host retry as an outer/adjacent Host concern and keep its own visual chain from accidentally amplifying retries. Future work may consume a more explicit Host recovery decision seam if DSH exposes one that can coordinate provider changes and total budgets, but this evaluation does not authorize such a rewrite.
+
+## Revisit trigger
+
+Re-run the spike only if released DSH adds a recovery contract that can explicitly express or delegate:
+
+- provider replacement;
+- one shared request-family deadline;
+- bounded attempt accounting;
+- cancellation/disposal quiescence;
+- durable identity across changed providers;
+- retry/fallback composition without amplification;
+
+and that contract exists on the declared minimum supported Host.
+
+## P3-E verdict
+
+`PASS — KEEP vision-chain; native request recovery is not a simpler semantic replacement.`

package/docs/architecture/runtime-boundaries.md

@@ -0,0 +1,124 @@
+# Runtime boundaries
+
+This document freezes the ownership boundaries that must remain true during the dsh-vision-router 2.x convergence work. P0 does not redesign routing behavior; it makes the existing product contract explicit so later refactors cannot accidentally move authority or lifecycle ownership.
+
+## Dependency direction
+
+The intended runtime direction is:
+
+```text
+Authority -> Evidence -> Planner -> Execution
+                    \-> Presentation (read-only projection)
+Session / Storage / Compat are supporting boundaries, not alternate policy owners.
+```
+
+Execution may consume a plan and live authority. It must not synthesize broader authority than the plan was allowed to use. Presentation may render state. It must not re-derive routing eligibility independently.
+
+## Authority
+
+**Owns:** authorization to perform behavior with user/resource/security consequences.
+
+Examples:
+- whether Auto routing is currently authorized;
+- whether background capability measurement is allowed;
+- whether paid background work is allowed;
+- whether remote settings mutation is allowed.
+
+Rules:
+- absence of authority is denial, not an invitation to infer intent;
+- authority is checked at the point where work begins and, for revocable operations, again before publication/continuation;
+- evidence, planner scores, cached state, UI state, or compatibility shims may never grant authority.
+
+## Evidence
+
+**Owns:** observed model/provider capability facts and their scope, freshness and persistence policy.
+
+Rules:
+- evidence says what has been observed, not what the user authorized;
+- durable capability evidence is kept separate from process-local runtime performance;
+- negative evidence and uncertainty must remain distinguishable;
+- evidence collection may not mutate settings or route order merely to make planning easier.
+
+## Planner
+
+**Owns:** pure selection/ranking from authorized candidates plus evidence and preference inputs.
+
+Rules:
+- no provider network I/O;
+- no persistence writes;
+- no settings mutation;
+- no Host service registration;
+- no authority expansion;
+- output is data describing an execution choice/order, not a disguised settings object.
+
+The existing `vision-capability-router.js` is the productized planner. P1 converges how its output reaches execution; P0 does not create a second planner.
+
+## Execution
+
+**Owns:** performing the selected visual work under deadlines, fallback, breaker, cancellation and provider/runtime contracts.
+
+Rules:
+- consumes authorized candidates/plan; cannot add a provider that was not already eligible;
+- cannot reinterpret planner output as permission;
+- preserves native multimodal non-intervention when the Host/model owns image input;
+- cancellation and authority revocation must not publish stale work;
+- compatibility adaptation stays narrow to the Host seam actually missing.
+
+## Session
+
+**Owns:** durable conversation/session facts that need to survive process restart, plus explicitly bounded process-local projections used to execute the current session safely.
+
+Rules:
+- durable Host/session facts and process-local caches are different lifetimes;
+- a process-local store is not a second source of truth for durable conversation identity;
+- restart/resume correctness is part of the product contract;
+- do not replace `SessionVisionStateStore` in P0/P1 merely for architectural symmetry.
+
+## Storage
+
+**Owns:** attachment/artifact placement, retention and deletion safety.
+
+Two classes must remain distinct:
+- **Host-owned attachments:** durable identities/content governed by the DSH attachment service;
+- **Vision Router derived artifacts:** temporary or managed outputs created by plugin operations.
+
+Rules:
+- never delete unknown/user-owned entries;
+- no P0 artifact layout migration;
+- storage cleanup may use only plugin-owned namespaces/provenance;
+- `.run-meta.json` is not introduced as part of P0.
+
+## Compat
+
+**Owns:** the smallest translation necessary when a supported Host contract lacks a seam required by the product contract.
+
+Rules:
+- capability detection first; version-persona branching last resort;
+- every major shim records Reason, Host gap, First needed for, Feature detection, Removal condition and Tests;
+- compat may preserve existing semantics but must not invent new routing authority;
+- a shim is removed only after the supported Host window and tests prove the native seam covers it.
+
+See `dsh-compatibility-matrix.md` for the inventory and exit criteria.
+
+## Presentation
+
+**Owns:** user-visible projection and interaction surfaces.
+
+Rules:
+- UI does not own route eligibility, authority, breaker state, credential validity or evidence validity;
+- presentation consumes structured product/runtime state instead of recreating routing rules in browser code;
+- P0 does not split the Web UI; it only freezes this ownership rule for later P3 work.
+
+## P0 invariants
+
+The following are deliberate stop conditions for any P0 change:
+
+- Auto or Ordered routing behavior changes;
+- authority becomes broader than before;
+- native multimodal requests are newly intercepted;
+- session restart/resume semantics change;
+- artifact layout or cleanup scope changes;
+- background scheduler is migrated to `ctx.jobs`;
+- `vision-capability-shadow.js` execution flow is split or rewritten.
+
+P0 is complete when the Host contract gates, compatibility inventory, Doctor capability snapshot, runtime-boundary documentation and logical test groups are all present while the existing behavior remains unchanged.