dsh-vision-router 2.3.0 → 3.0.1

package/README.md

@@ -42,9 +42,15 @@
 > **Data leaves your machine by default.** When a cloud vision model is used, Vision Router sends the image (or a derived crop), the vision prompt and related request metadata to that provider. A fresh install has an anonymous OVHcloud vision fallback enabled, so "free" and "no key" do **not** mean offline. Do not use the cloud chain for confidential, regulated or classified material. See [Data flow and strict local-only use](#data-flow-and-strict-local-only-use).
 
 > [!WARNING]
-> 📌 **Announcement (v2.3.0)**
+> 📌 **Announcement (v3.0.1)**
 >
-> **v2.3.0:** Architecture hardening and compatibility convergence. The supported DSH 0.1.x window now starts at `0.1.5-rc.1`, while the 0.2.x train starts at verified `0.2.0-rc.2`; composition, Session repair, Settings/browser ownership and Desktop lifecycle contracts are hardened, and only proven-unreachable pre-floor shims are retired. [What’s new →](docs/releases/v2.3.0.md)
+> **v3.0.1: five corrective fixes on the 3.0 line.** The Vision Router settings surface
+> reads and writes real values on the Desktop shell, the model picker no longer groups the
+> same model twice, and every provider leg that can reach a remote provider — background
+> profiling, the local vision stabilizer, the settings "test connection" probe and the
+> LM Studio native transport — now follows the same `proxy` / `proxyHosts` decision as
+> foreground vision turns. Supported Hosts are unchanged: DSH 0.1.x from `0.1.5-rc.1`,
+> DSH 0.2.x from verified `0.2.0-rc.2`. [What’s new →](docs/releases/v3.0.1.md)
 
 <p align="center">
   <img src="assets/vision-demo.gif" width="640" alt="Demo: paste an image, the agent locates the send button with vision_ground / vision_crop / vision_pixel_diff and answers with coordinates" />
@@ -151,6 +157,15 @@ For normal npm/npx installs, installation is a single command:
 npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router
 ```
 
+> [!IMPORTANT]
+> **Which profile?** Install into an **existing profile that already serves the Web UI**:
+>
+> - Web DSH: `--profile web` (default data directory `~/.dsh`);
+> - the official DeepSeek Harness desktop app: `--profile desktop` (same `~/.dsh` data directory; reload the plugin or restart the app afterwards);
+> - Oh-DSH Desktop: its data directory is `~/.ohdsh`, see [Oh-DSH Desktop](#oh-dsh-desktop) below.
+>
+> `dsh plugin add` only adds the plugin to the profile you name. A **brand-new** profile contains just `@deepseek-ai/dsh-base`, and `dsh web` never binds a port in that state (no Web surface). Install into an existing profile, or give the new profile a Web surface first.
+
 > [!WARNING]
 > If this profile already loads community plugins manually through `cordis.patch.yml`, do **not** mix that legacy setup with `dsh plugin add` / `dsh plugin list`: current DSH CLI behavior can also append bundle-patch dependencies to `dsh.profile.bundles`, causing those plugins to register twice. Migrate the existing manual plugin rows to bundle-managed loading first, or keep using the manual installation path. See [deepseek-harness discussion #2889](https://github.com/deepseek-ai/deepseek-harness/discussions/2889).
 
@@ -436,7 +451,7 @@ ollama pull qwen2.5vl
 ## Requirements
 
 - DeepSeek Harness Web profile. Normal installs can use `npx @deepseek-ai/dsh ...`; source checkouts use `pnpm dsh ...`. A bare `dsh ...` command only works when the CLI is already on your shell `PATH`.
-- **DSH Host support policy:** DVR 2.3.x supports DSH 0.1.x continuously from `0.1.5-rc.1` (current stable evidence: `0.1.5-rc.3`) and supports the 0.2.x train from verified `0.2.0-rc.2`. Exact `0.2.0-rc.2` is also the ordinary 2.3 development Host. Pre-0.1.5 Hosts are unsupported, and DVR no longer publishes the older jagged 0.1.x exception list. Runtime behavior remains capability-based. See [DSH Host support window](docs/architecture/dsh-support-window.md).
+- **DSH Host support policy:** DVR 3.0.x supports DSH 0.1.x continuously from `0.1.5-rc.1` (current stable evidence: `0.1.5-rc.3`) and supports the 0.2.x train from verified `0.2.0-rc.2`. Exact `0.2.0-rc.2` is also the ordinary 3.0 development Host. Pre-0.1.5 Hosts are unsupported, and DVR no longer publishes the older jagged 0.1.x exception list. Runtime behavior remains capability-based. See [DSH Host support window](docs/architecture/dsh-support-window.md).
 - Node ≥ 22 (host side).
 - No API key for the default free chain; a credential reference (`apiKeyEnv`) only for paid `httpProviders`.
 - Chrome / Chromium / Edge is needed only for `vision_html_screenshot`; every other tool works without a browser.

package/README.zh.md

@@ -42,9 +42,13 @@
 > **默认配置会让数据出网。** 使用云端视觉模型时，Vision Router 会将图片（或由它裁剪出的局部）、识图提示词及相关请求元数据发送给对应供应商。新安装默认开启 OVHcloud 匿名视觉兜底，因此“免费”和“免 Key”不等于离线。涉密、涉案、内部或其他受限材料请勿使用云端链路。详见[数据流向与严格纯本地配置](#数据流向与严格纯本地配置)。
 
 > [!WARNING]
-> 📌 **公告（v2.3.0）**
+> 📌 **公告（v3.0.1）**
 >
-> **v2.3.0：架构加固与兼容收敛。DSH 0.1.x 正式支持线提高到 `0.1.5-rc.1` 起，0.2.x 从已验证的 `0.2.0-rc.2` 起；composition、Session repair、Settings/浏览器 ownership 与 Desktop lifecycle 均完成加固，只退休已证明在新支持窗口不可达的旧 shim。** [查看完整更新 →](docs/releases/v2.3.0.md)
+> **v3.0.1：3.0 线上的五处修正。** Desktop 壳上的 Vision Router 设置面能读取并写入真实值，
+> 模型选择器不再把同一模型重复分组；所有可能触达远程 provider 的腿 —— 后台基准分析、本地视觉
+> 稳定器、设置里的「测试连接」探针、LM Studio native 传输 —— 现在都与前台视觉轮次遵守同一套
+> `proxy` / `proxyHosts` 判定。支持的 Host 不变：DSH 0.1.x 自 `0.1.5-rc.1` 起，DSH 0.2.x 自
+> 已验证的 `0.2.0-rc.2` 起。 [查看完整更新 →](docs/releases/v3.0.1.md)
 
 <p align="center">
   <img src="assets/vision-demo.gif" width="640" alt="演示：粘贴图片，Agent 用 vision_ground / vision_crop / vision_pixel_diff 定位发送按钮并给出坐标" />
@@ -149,6 +153,15 @@ Vision Router 在默认配置下不是完全离线工具。具体边界取决于
 npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router
 ```
 
+> [!IMPORTANT]
+> **装到哪个 profile？** 请装进**已经存在、并且自带 Web 界面**的 profile：
+>
+> - 网页版 DSH：`--profile web`（默认数据目录 `~/.dsh`）；
+> - 官方 DeepSeek Harness 桌面应用：`--profile desktop`（同一个 `~/.dsh` 数据目录，装完在应用里重新加载插件或重启一次应用）；
+> - Oh-DSH Desktop：数据目录是 `~/.ohdsh`，见下方 [Oh-DSH Desktop](#oh-dsh-desktop)。
+>
+> `dsh plugin add` 只是把插件加进**指定** profile。**全新创建**的 profile 只含 `@deepseek-ai/dsh-base`，此时 `dsh web` 不会绑定端口（没有 Web 面）。请装进已有的 profile，或先让新 profile 具备 Web 面。
+
 > [!WARNING]
 > 如果这个 profile 里已经有通过 `cordis.patch.yml` **手动挂载**的社区插件，不要再把这种旧式加载方式与 `dsh plugin add` / `dsh plugin list` 混用：当前 DSH CLI 可能同时把带 bundle patch 的依赖追加到 `dsh.profile.bundles`，导致这些插件被重复注册。请先把原有手动插件迁移到 bundle 管理方式，或继续沿用手动安装路径。详见 [deepseek-harness Discussion #2889](https://github.com/deepseek-ai/deepseek-harness/discussions/2889)。
 
@@ -434,7 +447,7 @@ ollama pull qwen2.5vl
 ## 环境要求
 
 - DeepSeek Harness 的 Web profile。普通安装可用 `npx @deepseek-ai/dsh ...`；从源码仓库运行时用 `pnpm dsh ...`。只有 CLI 已经进入系统 `PATH` 时才能直接写 `dsh ...`。
-- **DSH Host 支持策略：** DVR 2.3.x 从 `0.1.5-rc.1` 起连续支持 DSH 0.1.x（当前稳定证据为 `0.1.5-rc.3`），并从已验证的 `0.2.0-rc.2` 起支持 0.2.x；精确 `0.2.0-rc.2` 同时作为 2.3 默认开发 Host。低于 0.1.5 的 Host 不再支持，也不再维护旧的 0.1.x 锯齿式例外列表。运行时仍按能力判断，而不是按版本字符串分支。详见 [DSH Host 支持窗口](docs/architecture/dsh-support-window.md)。
+- **DSH Host 支持策略：** DVR 3.0.x 从 `0.1.5-rc.1` 起连续支持 DSH 0.1.x（当前稳定证据为 `0.1.5-rc.3`），并从已验证的 `0.2.0-rc.2` 起支持 0.2.x；精确 `0.2.0-rc.2` 同时作为 3.0 默认开发 Host。低于 0.1.5 的 Host 不再支持，也不再维护旧的 0.1.x 锯齿式例外列表。运行时仍按能力判断，而不是按版本字符串分支。详见 [DSH Host 支持窗口](docs/architecture/dsh-support-window.md)。
 - Node ≥ 22（宿主侧）。
 - 默认免费链路无需 API Key；付费 `httpProviders` 只需一个凭据引用（`apiKeyEnv`）。
 - 只有 `vision_html_screenshot` 需要 Chrome / Chromium / Edge；其余工具无浏览器也能用。

package/docs/architecture/3.0-architecture-plan.md

@@ -0,0 +1,252 @@
+# DVR 3.0 architecture plan
+
+Status: **complete through R10 post-main correctness closure**
+
+Baseline:
+
+- DVR `main@c61802dfc591410ba328b7f4c8f983b0e3d5f447`
+- DSH `deepseek-ai/deepseek-harness@639ed015397290b3745d163aafe02ffee4aa3f84` (`0.2.0-rc.2`)
+- 3.0 development branch: `3.0`
+- R9 architecture checkpoint: `1e331b1b8f8ea74a5cd38a1347f4e0bd13ef9ef9`
+- R9 architecture audit: `docs/architecture/3.0-r9-final-audit.md`
+- R10 post-main correctness implementation: `b38d427d54024f739dabbb3dacf389dc719a960f`
+- R10 closure: `docs/architecture/3.0-r10-final-correctness-closure.md`
+
+3.0 is **typed architecture consolidation**, not a repository-wide TypeScript rewrite.
+The success criterion is that changes to DSH contracts, lifecycle ownership, Settings,
+Session, provider contracts, and public package boundaries fail loudly at the nearest
+compiler/runtime/package gate. The percentage of files ending in `.ts` is not a goal.
+
+## Invariants inherited from 2.3
+
+3.0 must preserve the semantic owners established by 2.3:
+
+| Responsibility | Owner |
+| --- | --- |
+| routing/background authority | `lib/vision-routing-authority.js` |
+| routing evidence | `lib/vision-routing-evidence.js` |
+| planning/scoring | `lib/vision-capability-router.js` |
+| execution order | `lib/vision-execution-order.js` |
+| Session visual state/index | Session runtime/state/index owners |
+| managed artifacts | `lib/vision-artifact-store.js` |
+| DVR-owned provider HTTP | explicit `VisionProviderTransport` instance |
+| Host/product projection | server presentation boundaries |
+| browser rendering | client/presentation layer |
+
+High fan-out in `runtime-composition` is expected for a composition root and is not
+by itself an extraction target. Core extraction requires a stable semantic owner, not
+a line-count or import-count justification.
+
+## Required architecture direction
+
+```text
+DSH public contracts
+        |
+        v
+narrow Host boundaries
+        |
+        v
+DVR domain types
+        |
+        v
+Authority -> Evidence -> Planner -> Execution
+        |                       |
+        +------ composition ----+
+                  |
+                  v
+             mature core
+```
+
+Host types and DVR domain types must not become one giant interface graph.
+
+## Source/build target
+
+The target package model is:
+
+```text
+canonical source                    generated package artifact
+src/**/*.ts / transitional .js  -> lib/**/*.js
+client typed/transitional source -> lib/client.js
+                                  -> lib/types/**/*.d.ts
+```
+
+The preferred artifact directory remains `lib`; introducing `dist` has no identified
+architectural benefit. Ordinary generated Host JavaScript should not become a second
+checked-in source of truth.
+
+Host code remains unbundled ESM. Browser code is a separate build/type world.
+
+## Type ownership
+
+Use DSH package-exported public contracts wherever DSH owns the concept. DVR owns only
+DVR semantics such as routing decisions, capability evidence, image ownership, Session
+vision state, provider configuration, diagnostics, and resource ownership.
+
+Do not create a generic `DvrContext`, Host facade, service locator, DI container,
+global registry, or callback bag to make TypeScript conversion easier.
+
+## Runtime validation
+
+TypeScript never replaces validation at Settings/JSON, RPC, provider/network,
+filesystem, persisted state, environment, browser/Node, or user-input boundaries.
+
+Preferred rule:
+
+```text
+unknown -> boundary parser/official codec -> typed value -> domain
+```
+
+Schemastery remains the owner for plugin Config/Settings schema. Zod or another runtime
+validator is justified only for complex untrusted external shapes; browser code should
+not gain a heavyweight validator merely for type symmetry.
+
+## Host / Client programs
+
+Host and browser Client must be type-checked as separate programs. DSH itself separates
+the two because both sides augment Cordis Context under different runtime contracts.
+
+Host compilation should follow real Node ESM resolution rather than copying DSH's
+monorepo-only build choices mechanically. Current target for the Host compiler is
+NodeNext/NodeNext with explicit ESM extension discipline.
+
+## Browser constraint
+
+The existing `262144` byte single-file review bound for `lib/client.js` is frozen.
+3.0 must not raise it to make TypeScript fit. Client migration is an independent Go/No-Go
+workstream and may remain partly JavaScript if typed generation would weaken
+determinism, debugging, loader transparency, or the size gate.
+
+## Compatibility
+
+Runtime Host compatibility and durable user-data compatibility are independent.
+
+3.0 may raise the Host floor only after a dedicated evidence gate proves that the
+removed Host generations account for real compatibility complexity. A higher Host floor
+does not authorize deleting readers/migrations for persisted Settings, profile data,
+Session/replay data, attachment identity, or historical image ownership.
+
+No speculative DSH 0.3 implementation is part of this plan.
+
+## Production dependency policy
+
+Production runtime code may depend on documented/package-exported DSH faces. It must
+not import `@deepseek-ai/*/src/*` or DeepSeek Harness monorepo filesystem internals.
+
+Exact-source compatibility surveillance under `scripts/` and tests is a separate
+category: it may inspect upstream implementation source to detect Host drift or a shim's
+removal condition, but that source dependency must not enter runtime code, public
+declarations, or the npm runtime graph.
+
+## Public API direction
+
+R7 replaced the former transitive mature-Core export graph with an explicit package-root
+runtime/type surface. New Core exports no longer become package API automatically.
+
+`./client` remains a DSH loader entry and is not treated as an ordinary consumer
+library API.
+
+## Roadmap
+
+Final status:
+
+| Phase | Result |
+| --- | --- |
+| R0 | complete |
+| R1 | complete |
+| R2 | complete |
+| R3 | complete |
+| R4 | complete |
+| R5 | complete — production Browser TypeScript switch No-Go |
+| R6 | complete |
+| R7 | complete |
+| R8 | complete |
+| R9 | complete |
+| R10 | complete — post-main final correctness closure |
+
+R9 records the typed-architecture audit at its historical checkpoint. The post-main
+correctness findings and repairs are recorded separately in
+`docs/architecture/3.0-r10-final-correctness-closure.md`.
+
+### R0 - Baseline and contract ledger
+
+- freeze package/export/browser/support facts;
+- record DSH public type authorities;
+- classify current package-root exposure;
+- gate production private DSH source imports;
+- record compatibility candidates without deleting them.
+
+### R1 - Source/artifact boundary
+
+- establish `src` as canonical source and `lib` as generated output;
+- preserve behavior/module ownership during relocation;
+- add clean/reproducible artifact checks;
+- do not combine source moves with semantic refactors.
+
+### R2 - Type infrastructure and Host boundaries
+
+- separate Host and Client TypeScript programs;
+- add strict compiler policy;
+- type Settings, Session, LLM/provider, attachment, RemoteResult, and composition inputs
+  against DSH public contracts;
+- allow a controlled JS bridge during migration.
+
+### R3 - DVR domain types
+
+Type only stable DVR-owned semantics. Do not create interfaces without a named owner and
+a concrete coupling/risk they reduce.
+
+### R4 - Composition and mature Core
+
+Migrate composition/lifecycle before low-value algorithmic code. Mature Core conversion
+is incremental and must not trigger decomposition solely for file size.
+
+### R5 - Browser Client
+
+Run an independent typed-source/build experiment. Switch production ownership only when
+the output is deterministic, understandable, uses only supported runtime externals,
+passes real browser/Desktop tests, and stays at or below 256 KiB.
+
+### R6 - Compatibility retirement / Host floor
+
+Re-run every shim's documented removal condition. Host-floor changes are evidence-based
+and do not retire durable-data compatibility.
+
+### R7 - Public API
+
+Classify root exports as plugin contract, supported API, compatibility API, accidental
+internal, or test-only. Publish only deliberate types/runtime faces.
+
+### R8 - CI/release
+
+Add typecheck, lint, clean build, generated sync, reproducibility, packed declaration
+smoke, and source-to-artifact evidence without weakening the existing pack-once,
+tarball-identity, trusted-publishing, and provenance model.
+
+### R9 - Final audit
+
+Re-run ownership, lifecycle, dependency-cycle, browser, compatibility, package,
+Node 22/24, supported DSH, Desktop, adversarial, property, resource, and release audits.
+
+### R10 - Final correctness closure
+
+- review post-main implementation rather than treating R9 green evidence as transitive;
+- repair provider transport capture, dynamic Host validation and optional Cordis seams;
+- complete Session Vision sidecar/user-authority lifecycle ownership;
+- align package-root runtime and declaration contracts;
+- migrate CI trigger ownership from generated artifacts to canonical source;
+- verify the exact package candidate before tag creation while preserving pack-once.
+
+## Explicit non-goals
+
+- 100% TypeScript conversion;
+- Big Bang rewrite;
+- generic DI/service locator;
+- global current owner or registry;
+- `Object.create(core)` facade;
+- Config/Settings impersonation;
+- Core decomposition by LOC;
+- composition splitting by fan-out;
+- routing/Session/provider rewrites unrelated to a proven 3.0 seam;
+- browser size-limit increase;
+- importing DSH private implementation to obtain richer types;
+- deleting runtime validation because code is typed.

package/docs/architecture/3.0-r0-contract-ledger.md

@@ -0,0 +1,137 @@
+# DVR 3.0 R0 contract ledger
+
+Status: **R0 baseline**
+
+Audit baseline:
+
+- DVR source baseline: `main@c61802dfc591410ba328b7f4c8f983b0e3d5f447`
+- 3.0 planning commit: `9fe18fb0abe8732ee2848140e10113dfada92623`
+- DSH source baseline: `deepseek-ai/deepseek-harness@639ed015397290b3745d163aafe02ffee4aa3f84`
+- DSH package line at audit: `0.2.0-rc.2`
+
+R0 records facts and installs non-behavioral architecture gates. It does not move source,
+change Host support, delete compatibility, or alter plugin runtime behavior.
+
+## Package and runtime baseline
+
+| Contract | R0 value |
+| --- | --- |
+| package | `dsh-vision-router@2.3.0` |
+| module kind | ESM |
+| Node | `^22.19.0 || >=24.0.0` |
+| package root | `lib/public-entry.js` |
+| DSH browser entry | `lib/client.js` |
+| CLI | `lib/doctor-cli-p0.js` |
+| browser hard bound | `262144` bytes |
+| browser R0 size | `261672` bytes |
+| browser headroom | `472` bytes |
+| production ESM cycles at 2.3 close | 0 |
+
+The 256 KiB browser review bound is a retained constraint, not a migration target to relax.
+
+## Current root export topology
+
+The current root is intentionally **not** curated during R0:
+
+```text
+package "."
+  -> lib/public-entry.js
+     -> export * from ../entry.js
+        -> export * from ./index.js
+           -> export * from ./lib/vision-resilience.js
+```
+
+Static export inventory at the R0 baseline:
+
+- `index.js`: 101 direct named exports;
+- `lib/vision-resilience.js`: 13 named exports re-exported by `index.js`;
+- `entry.js`: 10 direct named exports plus the Core star export;
+- estimated distinct package-root named surface after shadowing/deduplication: **122 names**.
+
+This is an **inventory**, not an assertion that all 122 names are supported public API.
+R7 must classify every root export as one of:
+
+- `PLUGIN_CONTRACT`;
+- `PUBLIC_SUPPORTED`;
+- `PUBLIC_COMPAT`;
+- `INTERNAL_ACCIDENTAL`;
+- `TEST_ONLY`.
+
+R0 must not reduce this surface before that classification because doing so would mix API
+breakage with source/build migration.
+
+## DSH type authority ledger
+
+Production TypeScript must prefer package-exported DSH contracts where DSH owns the
+concept.
+
+| Concept | Current DSH authority |
+| --- | --- |
+| `RemoteResult` / remote failures | `@deepseek-ai/dsh-typert-protocol` |
+| Session client/controller faces | `@deepseek-ai/dsh-api-session-controller/client` |
+| Session/model-selection value contracts | `@deepseek-ai/dsh-api-session-controller/types` |
+| LLM/provider/message vocabulary | `@deepseek-ai/dsh-llm/types` |
+| attachment vocabulary | `@deepseek-ai/dsh-attachment` / exported types face |
+| Settings transport/view vocabulary | `@deepseek-ai/dsh-settings/types` |
+| generated client remote assembly | `@deepseek-ai/dsh-api-remotes/client` |
+| browser slots | `@deepseek-ai/dsh-client-ui-slots` |
+| ModelDirectory controller/state | `@deepseek-ai/dsh-client-ui-model-selection/client` |
+
+`ModelDirectory` and `ModelDirectoryState` are package-exported browser contracts, but
+remain model-selection UI/controller types. They are not DVR routing-domain types.
+
+## Production private-source policy
+
+R0 installs a hard architectural rule:
+
+> Production runtime code must not import or reference DSH package `src/*` entry points
+> or `deepseek-harness/packages/*/src/*` monorepo implementation paths.
+
+This applies to production entry points and `lib/**/*.js` now, and later to generated
+runtime output from `src`.
+
+The rule deliberately does **not** ban scripts/tests that inspect exact upstream source.
+Files such as `scripts/dsh017-source-contract.mjs` are upstream compatibility
+surveillance; they are allowed to inspect DSH implementation source because they do not
+enter the npm production runtime graph.
+
+## Compatibility baseline
+
+2.3 closes with runtime Host support spanning the 0.1.5 train and exact 0.2.0-rc.2
+evidence. 3.0 does not change that in R0.
+
+Runtime Host compatibility and durable-data compatibility remain independent. A later
+Host-floor raise cannot by itself remove replay, Settings/profile, Session, attachment,
+route-identity, or historical image-ownership readers.
+
+## R0 compatibility candidate: dsh-client-runtime
+
+Current DVR still names `@deepseek-ai/dsh-client-runtime` in two places:
+
+1. `package.json#dsh.client.inject`;
+2. `lib/doctor-runtime.js#HOST_PACKAGES`.
+
+At the audited DSH `0.2.0-rc.2` source baseline, repository search finds historical
+references but no current package implementation that establishes this as a current
+browser runtime package. DVR also has no identified `ctx.runtime` consumption.
+
+Classification: **candidate stale Host/browser edge, not yet deletion-authorized**.
+
+Removal requires real package/Host/browser evidence and must update both the manifest
+and Doctor assumption together. R0 records the candidate; R6 owns the decision.
+
+## R0 exit criteria
+
+R0 is complete when:
+
+- the 3.0 architecture plan exists in-repo;
+- this contract ledger exists;
+- the existing package/browser/support baselines remain unchanged;
+- CI runs on the 3.0 development branch;
+- production private DSH source references are forbidden by an executable architecture
+  test;
+- no runtime behavior, support floor, compatibility shim, release metadata, tag, npm
+  package, or GitHub Release is changed.
+
+The next phase is R1: establish a source/artifact boundary without mixing that move with
+semantic refactors.

package/docs/architecture/3.0-r1-source-artifact-boundary.md

@@ -0,0 +1,98 @@
+# DVR 3.0 R1 source/artifact boundary
+
+Status: **complete**
+
+R1 was intentionally split so source relocation and artifact removal were not performed
+in one unreviewable change.
+
+## Final source/artifact model
+
+The canonical editable runtime tree is `src/`, preserving the established 2.3 package
+artifact topology:
+
+```text
+src/entry.js / transitional .ts       -> entry.js
+src/index.js / transitional .ts       -> index.js
+src/lib/**/*.js / src/lib/**/*.ts     -> lib/**/*.js
+```
+
+`entry.js`, `index.js`, and `lib/**` are generated package artifacts and are no longer
+tracked by Git.
+
+The move did not authorize import rewrites, Core decomposition, public API contraction,
+or runtime ownership changes. Source relocation and TypeScript migration remain separate
+review dimensions.
+
+## Build ownership
+
+`scripts/build-source-artifacts.mjs` is the only writer for the package runtime tree.
+
+A normal `pnpm build`:
+
+1. removes any stale root `entry.js`, `index.js`, and `lib/**`;
+2. copies transitional canonical JavaScript from `src/` byte-for-byte;
+3. compiles canonical TypeScript in an isolated temporary output directory;
+4. copies compiled JavaScript into the established package artifact paths.
+
+This clean-before-build rule prevents deleted or renamed source modules from surviving as
+stale files that could later enter `pnpm pack`.
+
+`pnpm build:check` builds into a temporary directory and compares generated output with
+the current package tree without mutating it.
+
+`pnpm build:reproducible` performs two clean builds into independent temporary
+directories and compares relative paths, byte sizes, and SHA-256 hashes.
+
+## Install and package lifecycle
+
+Repository installs run `prepare -> pnpm build`, so workflows and direct test commands
+that historically consumed `lib/**` receive current artifacts from canonical source.
+
+The one security workflow that intentionally installs with `--ignore-scripts`
+(`adversarial-fuzz`) has an explicit build step.
+
+`prepack -> pnpm build` is an independent package safety gate. Packaging therefore does
+not rely on generated files being present in the checkout or left over from tests.
+
+Generated runtime paths are ignored by Git:
+
+- `/entry.js`;
+- `/index.js`;
+- `/lib/`.
+
+The npm `files` allowlist continues to name those artifact paths because they are package
+outputs, not repository source.
+
+## Workflow trigger migration
+
+Specialized workflows whose path filters referenced the old root `index.js`,
+`entry.js`, or `lib/**` now also follow `src/**`. This prevents removal of tracked
+artifacts from silently disabling architecture, Host, browser, resource, compatibility,
+or fuzz gates.
+
+## Browser client
+
+The browser client remains a separate workstream. Canonical browser source currently
+lives under `src/lib/client.js`; its deterministic embedded maintenance-actions sync is
+performed on canonical source before package artifacts are rebuilt.
+
+The existing 262144-byte hard review bound is unchanged.
+
+## R1 verification
+
+R1b was verified from a checkout with **zero tracked generated runtime artifacts**:
+
+- frozen install succeeded;
+- prepare rebuilt the runtime tree;
+- clean build succeeded;
+- generated artifact verification succeeded;
+- two-build reproducibility succeeded;
+- Host and Client typecheck succeeded;
+- full Node 22 and Node 24 test suites succeeded;
+- Linux and macOS native Host/sharp smoke succeeded;
+- Windows runtime regression succeeded;
+- Windows `pnpm pack` succeeded with generated artifacts ignored by Git;
+- the packed tarball installed into a DSH-like Host with the shared-sharp invariant intact.
+
+R1 is closed. Further source migration is R2/R3/R4 work and must preserve this build
+contract.