docs(boot): describe the interception layer in the generation note and README

The generation note and the app-boot README no longer claim that runtime lookup hides the shared position or recognizes profile projections: generation entries occupy their package names at $DSH_HOME/profiles/node_modules and every other name sees that directory as an ordinary ancestor. Pairing records re-recorded.
This commit is contained in:
imccyu committed 2026-09-19 14:39:44 +08:00
1 parent 81b6934804
commit 0e2097ac18
6 files changed
+8 -8

No files matched your search

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md
2026-09-09-profile-resolution-generations.md: 55b1e1cf9cba349bb7259c90893c778fac131d81
2026-09-09-profile-resolution-generations.zh.md: cba5ebf7b50e720d10c4f1c095a9544a20434ba7
2026-09-09-profile-resolution-generations.md: b6dc5f0441239c75f3e1ee8677ec5b3f8e3cf659
2026-09-09-profile-resolution-generations.zh.md: fb465351f8b5507ee8381e2e2b35e58eb5977405
@@ -104,7 +104,7 @@ Replacing, upgrading, or removing an already loaded package requires process res
### Filesystem and runtime carriers
The resolver does not create, update, or remove fallback symlinks and proxy packages. Runtime lookup skips the shared fallback position under `$DSH_HOME/profiles/node_modules` and ignores profile-owned projections into `.dsh-module-fallback`. Those projections are also excluded from profile-local package metadata and bundle dependency discovery; ordinary pnpm-installed packages retain native precedence. Writable profile state and package-manager transactions remain outside the resolver.
The resolver does not create, update, or remove fallback symlinks and proxy packages. Generation entries occupy their package names at `$DSH_HOME/profiles/node_modules`; every other name sees that directory as an ordinary ancestor, and symlinks anywhere in the profile tree are ordinary filesystem content without dedicated recognition. Profile-local package metadata and bundle dependency discovery follow the same Node lookup; ordinary pnpm-installed packages retain native precedence. The [lookup-order Note](2026-09-19-profile-resolution-lookup-order.md) records the complete order. Writable profile state and package-manager transactions remain outside the resolver.
Runtime resolution requires a supported Node Internal loader interface. The Electron Host runs through the Electron executable with `ELECTRON_RUN_AS_NODE=1`; packaged builds read the dsh tree from ASAR and map executable ASAR entries to electron-builder's unpacked tree. Pkg and Electron use the same runtime-generation mechanism as ordinary Node launches.
@@ -104,7 +104,7 @@ resolution generation 列出可用 fallback 包;Loader entries 组成活动插
### 文件系统与运行时载体
解析器不创建、更新或删除 fallback 软链接与代理包。运行时查找跳过 `$DSH_HOME/profiles/node_modules` 下的共享 fallback 位置,并忽略指向 `.dsh-module-fallback` 的 profile 自有投影。profile 本地包元数据与 bundle 依赖展开也排除这些投影;正常由 pnpm 安装的包保留原生优先级。可写 profile 状态和包管理器事务不属于解析器。
解析器不创建、更新或删除 fallback 软链接与代理包。generation 条目占据 `$DSH_HOME/profiles/node_modules` 上各自的包名位置;其余包名把该目录当作普通祖先,profile 树内任何位置的软链接都是普通文件系统内容,没有专门识别。profile 本地包元数据与 bundle 依赖展开遵循同一套 Node 查找;正常由 pnpm 安装的包保留原生优先级。完整顺序见[查找顺序 Note](2026-09-19-profile-resolution-lookup-order.zh.md)。可写 profile 状态和包管理器事务不属于解析器。
运行时解析要求受支持的 Node Internal loader 接口。Electron Host 通过设置 `ELECTRON_RUN_AS_NODE=1` 的 Electron 可执行文件运行;打包构建从 ASAR 读取 dsh 依赖树,并把 ASAR 中的可执行条目映射到 electron-builder 的 unpacked 目录。pkg 与 Electron 使用和普通 Node 启动相同的 runtime generation 机制。
+2 -2
View File
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write packages/boot/app-boot/README.md
README.md: b61331924b561eab54a6478ab403fa088775e8fc
README.zh.md: 1055b003d6f318c2a39d358634f5b9afeb4b496e
README.md: 867f88c1e957e738c911672aaf879d07a0e4066d
README.zh.md: 195187d4e5c901279840e56878ac27629ce00f8b
+1 -1
View File
@@ -113,7 +113,7 @@ This section explains how the outcomes above are realized and points at the code
- **Process-local module resolution.** Runtime resolution installs one generation on Node's internal ESM and CommonJS resolvers before profile rows mount. Node still owns exports, conditions, subpaths, module caches, and error codes; routed ESM failures report the original importer instead of the internal lookup anchor. `ctx.pluginPackages` exposes package metadata from the same generation without recording Entry imports; an installed generation is authoritative even for a miss, while low-level embedders that install the service without one retain native lookup.
- **Two Loader builtins.** `mountRootInclude` registers `cordis:include` and `cordis:group` as Loader builtins: a group row gives one `isolate` realm to a provider and its consumers together, and an agent preset outside this workspace cannot resolve `@deepseek-ai/cordis-plugin-group` by name. Both load through the ambient module pipeline rather than the included tree's own specifier resolution.
- **Consumer-owned strictness.** Ordinary Loader groups keep successful siblings. App-boot applies the global required-entry policy after initial settlement; agent presets and dynamic multi-entry compositions own and dispose their separate generation when they require all-or-nothing setup. App-boot reads failed fibers to report their recorded errors and coalesces duplicate Loader rejection notifications through one process checkpoint.
- **One fallback generation.** The installation-first and ordered-bundle breadth-first traversal produces the runtime table. Runtime resolution creates no links and ignores stale projections at their former lookup positions. External bare targets selected by package `imports` use the same package order, while Node retains mapping, conditions, and exact target resolution. A complete successor may add package names atomically, while changing or removing an existing mapping requires restart.
- **One fallback generation.** The installation-first and ordered-bundle breadth-first traversal produces the runtime table. Runtime resolution creates no links; generation entries occupy their package names at `$DSH_HOME/profiles/node_modules`, and every other name sees that directory as an ordinary ancestor. External bare targets selected by package `imports` use the same package order, while Node retains mapping, conditions, and exact target resolution. A complete successor may add package names atomically, while changing or removing an existing mapping requires restart.
- **Application-owned profiles.** Application-owned profiles use the same runtime generation. Resolution does not modify their `node_modules`; pnpm owns installed packages.
- **Owned Workers.** Worker build banners import `@deepseek-ai/dsh-app-boot/worker/profile-resolution-bootstrap` before bundled business code. Each Worker installs the structured-cloned generation in its own isolate. The bootstrap bundle has no static package imports. Source Worker entries retain their self-contained dependency closure, and third-party Workers receive no injection.
- **Update completion.** App boot observes restart failures through the `internal/update` waterfall. Live patch reloads wait for the tree's fibers before auditing activation; `Fiber.update()` and `Entry.update()` alone do not establish restart success.
+1 -1
View File
@@ -113,7 +113,7 @@ Loader 结算后,app-boot 在仅 optional 条目未激活时输出警告。如
- **进程内模块解析。** runtime 解析会在挂载 profile 条目前,将一份 generation 安装到 Node 的 ESM 与 CommonJS 内部 resolver。exports、conditions、subpath、模块缓存和错误码仍由 Node 负责;路由后的 ESM 失败会报告原始 importer,而不是内部查找锚点。`ctx.pluginPackages` 从同一 generation 提供 package metadata,不记录 Entry import;安装 generation 后,即使查询未命中也以 generation 为准,仅安装服务而未提供 generation 的底层嵌入方仍使用 Node 原生查找。
- **两个 Loader builtin。** `mountRootInclude` 把 `cordis:include` 与 `cordis:group` 注册为 Loader builtin:group 行能把一个提供方与它的消费方放进同一个 `isolate` realm,而位于本工作区之外的 agent preset 无法按名称解析 `@deepseek-ai/cordis-plugin-group`。两者都通过宿主的模块管线加载,而非被包含树自身的说明符解析。
- **由 consumer 持有严格语义。** 普通 Loader group 保留成功 sibling。App-boot 在首次结算后应用全局 required-entry policy;agent preset 与动态多 entry 组合在需要 all-or-nothing setup 时,持有并拆卸各自的独立 generation。App-boot 读取 failed fiber 来报告已记录的错误,并在一个进程检查点内合并 Loader 重复的 rejection 通知。
- **唯一 fallback generation。** 安装优先、有序 bundle 逐根 breadth-first 遍历生成运行时表。runtime 解析不创建链接,并在旧链接原来的查找位置忽略陈旧投影。package `imports` 选中的外部 bare target 使用相同的选包顺序,映射、conditions 和精确 target 解析仍由 Node 负责。完整后继 generation 可以原子增加 package name,修改或删除既有映射则要求重启。
- **唯一 fallback generation。** 安装优先、有序 bundle 逐根 breadth-first 遍历生成运行时表。runtime 解析不创建链接;generation 条目占据 `$DSH_HOME/profiles/node_modules` 上各自的包名位置,其余包名把该目录当作普通祖先。package `imports` 选中的外部 bare target 使用相同的选包顺序,映射、conditions 和精确 target 解析仍由 Node 负责。完整后继 generation 可以原子增加 package name,修改或删除既有映射则要求重启。
- **应用自有 profile。** 应用自有 profile 使用相同的 runtime generation。解析过程不修改其 `node_modules`;已安装包由 pnpm 管理。
- **自有 Worker。** Worker 构建 banner 会在业务 bundle 前导入 `@deepseek-ai/dsh-app-boot/worker/profile-resolution-bootstrap`。每个 Worker 在自己的 isolate 中安装结构化克隆的 generation。bootstrap bundle 不静态导入任何包。源码 Worker 入口保留自包含依赖,第三方 Worker 不接受注入。
- **更新完成。** App boot 通过 `internal/update` waterfall 观察重启失败。实时 patch 重载在检查激活状态前等待配置树中的 fiber;单独调用 `Fiber.update()` 或 `Entry.update()` 不能确定重启成功。