qinglong/docs/adr/ADR-0296-root-entrypoint-line-ratchet-and-local-admin-domain-entry.md

ADR-0296：根入口行数棘轮与 Local Admin 领域入口

• 状态：Accepted
• 日期：2026-08-09
• 关联：D-05、D-06、D-17、D-85、D-87、D-213、D-257、ADR-0064、ADR-0069、ADR-0087、ADR-0267、ADR-0276、ADR-0295

上下文

ADR-0295 已能拒绝没有 artifact/closure 证明的浅层 package，但现有 package boundary ledger 只限制根 source 文件数量和角色。 一个标记为 public_export 的根文件仍可继续承载大量实现而不触发门禁。@qinglong/local-admin/src/index.ts 就是实际反例：它有 1,940 行，完整实现 Legacy SQLite inspection、review、stage、verify、activation 和 source write fence；与同 package 已有的 src/legacy-adoption/ 领域模块并列，却被 package root 名称掩盖为入口。

机械增加两行 index.ts facade 虽能把实现移入目录，却会新增一个无独立语义的微型 wrapper，重现本轮刚拒绝的文件碎片化。 package manifest 本身已经能够把 . 直接映射到嵌套领域输出，不需要源码 wrapper。

强制 GitNexus 中 LocalSqliteAdoptionError 为 CRITICAL（35 direct/40 total/0 process），inspectLegacySqlitePath 为 MEDIUM （8 direct/13 total/0 process），其余公开 adoption/activation entry 多为 LOW；高风险来自共享错误契约和同文件内部调用， 不是产品流程扩张。package boundary sourceMetrics/auditPackageBoundaries 均为 LOW，各 1 direct/0 process。

决策

1. 将原 local-admin/src/index.ts 的 Legacy Adoption 实现原样移至 src/legacy-adoption/localSqliteAdoption.ts，与 decision、publisher、keyring 等同领域模块共置。
2. 删除源码 index.ts wrapper。package manifest 的 main、types 与 exports["."] 直接指向领域输出；公开 package specifier @qinglong/local-admin、全部导出名称、类型、错误 class identity 和运行行为保持不变。
3. runtime.ts 与 legacyCrontabDecisionIssuer.ts 直接依赖领域模块，不再通过 package root 形成内部反向依赖。
4. package boundary ledger 升级为 schema v4。每个 workspace package 必须声明不可增长的 rootSourceLineHardCap；审计从实际 根 TypeScript source 计算总行数，缺失、负值或超限均失败。文件数量和行数是两个独立棘轮。
5. 为当前 19 个 package 建立真实基线。Local Admin 从 2 个根文件/1,949 行收敛为 1 个根文件/9 行，nested 24→25，source 总数仍为 26；workspace package/source 总数、生产依赖和公开 export 集合不变。
6. 高基线只表示“禁止继续恶化”，不表示架构债务已经合理。后续优先复审 AI migration/profile、Local SQLite adoption/runtime、 Cluster Control root 和 Worker production assembly，并在每次下沉后只能降低对应 hard cap。
7. 不新增 package、wrapper、第三方依赖、数据库对象、connection、timer、watcher、listener、进程或部署单元。

被拒绝的方案

• 保留两行 package-root facade：新增没有独立职责的 source/compiled wrapper，违背减少微型文件的目标。
• 只移动文件、不增加行数门禁：同类 god module 可以在任一 public_export 根文件重新出现。
• 一次拆分 1,940 行内部状态机：本批目标是修正 ownership；同时重写高风险 adoption/activation 事务会把可验证的移动变成语义重构。
• 新增 local-adoption workspace package：没有新的依赖、权限、部署或版本生命周期，只会扩大 importer 拓扑。
• 统一设置很小的全局阈值：会把 migration、binary assembly 与固定 Profile composition 混为同一种入口；逐 package 棘轮更适合 按风险持续下降，同时不允许任何现状反弹。

接受条件

1. Local Admin root source 只有 runtime.ts，9 行；Legacy Adoption 实现位于领域目录，source 总数仍为 26。
2. root package specifier 与 runtime/decision-issuer subpath 的导出和错误 class identity 保持；83 项 Local Admin 测试通过。
3. schema v4 fixture 必须拒绝在不增加根文件的情况下向入口塞入实现；当前 19-package boundary 为 compatible。
4. 完整 19-package、backend、依赖/Edge/local-image 审计与十档 artifact/RSS 门通过；基础 Edge 不安装 Local Admin。
5. GitNexus/detect_changes 不出现新产品流程或生产依赖变化。

接受证据

• @qinglong/local-admin 保持 26 个 source；root 仅 runtime.ts 1 个/9 行，nested 为 25。package root 的 main/types/exports["."] 直接映射 dist/legacy-adoption/localSqliteAdoption.*，不存在两行 wrapper。
• Local Admin 83/83、完整 19-package build/test、backend 1,112（1,110 pass/2 skip）通过；schema v4 的 7 项 boundary fixture 覆盖“根文件数不变但行数增长”并全部通过。cluster dependency、package boundary、Edge import、local image 四项审计 均为 compatible，workspace 仍为 19 package/768 source/48 root/720 nested，singleSourcePackages=[]。
• 十档 Profile artifact/RSS 全部 compatible。基础 Edge 为 3,635,004 bytes/332 files/48 loaded modules，不含 Local Admin； 最大 Standalone Application AI 为 6,122,822 bytes/491 files/104 loaded modules，仍低于 6 MiB/768 files 门限。
• 强制 GitNexus 为 43,284 nodes/98,493 edges/1,698 clusters/269 flows。移动后的 LocalSqliteAdoptionError 仍为 CRITICAL（35 direct/40 total），inspectLegacySqlitePath 为 MEDIUM（8/13），但两者均为 0 affected process； sourceMetrics/auditPackageBoundaries 为 LOW，分别 1 direct/2 total 与 1/1。detect_changes all/compare develop 为 12 files/31 symbols 与 14/34，均 low/0 process。
• 本批没有修改 production dependency、migration、数据库/Cluster 状态或运行资源，因此不重复制造无关 PostgreSQL HA 物理故障证据；此前门禁结论不被本批扩大或替代。