qinglong/docs/adr/ADR-0297-ai-root-implementation-domain-ownership.md

# ADR-0297：AI 根实现的领域归属与公开 Subpath 稳定性

- 状态：Accepted
- 日期：2026-08-09
- 关联：D-05、D-06、D-17、D-85、D-87、D-213、D-257、ADR-0040、ADR-0042、ADR-0087、ADR-0276、ADR-0296

## 上下文

ADR-0296 建立根 source 行数棘轮后，`@qinglong/ai` 成为最大根实现债务：4 个根文件共 6,187 个审计行。其中 `index.ts`
只有 16 个审计行并只做公开聚合；`modelInvocationMigration.ts`、`profileComposition.ts` 与
`localModelInvocationFeatureActivation.ts` 分别承载 4,644、872、652 个可见代码行，实际职责已经稳定为 Migration、
Profile Composition 和 Feature Activation。三者继续放在 package root 会把领域实现伪装成入口，也会使 schema v4 的
`rootSourceLineHardCap=6187` 失去治理价值。

这三个领域没有新的部署、权限、依赖或版本生命周期，拆成 workspace package 会扩大路由设备的 importer/SBOM/构建拓扑。
现有公开消费者已经通过 `@qinglong/ai/profile`、`@qinglong/ai/model-invocation-migration` 和
`@qinglong/ai/local-feature-activation` 使用能力，物理输出路径不是公共契约。

强制 GitNexus 在移动前显示：`LocalModelInvocationFeatureActivationRepository` 为 CRITICAL（9 direct/27 total/4
process），`assertLocalModelInvocationFeatureActive` 为 HIGH（6/11/3 process），`assertLocalModelInvocationFeatureReady`
为 HIGH（2/6/1 process）；Migration 文件整体为 MEDIUM（9 direct/19 total/0 process），Profile 文件和两个 bootstrap
入口均为 LOW。高风险来自既有本机 AI admission/completion 与 application bootstrap，不是本批新增流程。

## 决策

1. 将三个根实现原样归入同 package 的 owning domain：
   - `src/migration/modelInvocationMigration.ts`
   - `src/profile/profileComposition.ts`
   - `src/feature-activation/localModelInvocationFeatureActivation.ts`
2. 根目录只保留聚合公开导出的 `index.ts`，不增加兼容 facade 或 wrapper。package ledger 将 AI 的
   `rootSourceFileHardCap` 从 4 降为 1、`rootSourceLineHardCap` 从 6,187 降为 16；两个值以后只能继续下降或经独立 ADR 复审。
3. `package.json#exports` 只更新内部 `dist` target，三个公开 package subpath、根 export symbol、错误 class identity、
   migration ID/checksum/顺序与运行行为保持不变。
4. AI package tests 和 fixtures 改为通过 package self-reference 的公开 subpath 加载，禁止继续依赖旧的根 `dist/*.js` 私有路径。
   仓库根 live-contract/benchmark 脚本不是 workspace importer，继续显式加载受审嵌套 `dist` 路径，避免虚构 root dependency。
5. 不新增 package、生产依赖、migration、数据库对象、connection、timer、watcher、listener、进程或部署单元。

## 被拒绝的方案

- **保留三个根 facade**：根文件数和行数看似下降，但会制造无独立语义的 wrapper，继续让内部代码依赖虚假入口。
- **拆成三个 workspace package**：没有独立制品或权限边界，只会增加低配设备安装、lock importer、SBOM 和发布成本。
- **同时拆分 4,644 行 Migration 语义**：目录归位可以证明零行为变化；在同批重排 SQL step 会扩大 HIGH/CRITICAL 风险面。
- **继续让测试 require 私有 dist 路径**：会把旧编译布局误当公共 API，使后续内部重构不可验证。
- **只提高 6,187 行 hard cap**：冻结坏结构不等于治理；已有稳定领域边界时应降低棘轮。

## 接受条件

1. AI 保持 62 个 source，root 只有 1 个 `index.ts`/16 审计行，nested 58→61；workspace package/source 总数不变。
2. 三个公开 subpath 与根导出保持，AI package 及全部生产 consumer 通过 clean build/test。
3. migration 定义、Feature Activation repository、Profile disabled/active/drain 行为均由原测试覆盖；旧私有根 dist 引用清零。
4. 完整 packages/backend、四项架构审计和十档 artifact/RSS compatible；基础 Edge 不安装 AI。
5. GitNexus 保持既有 269 条流程，detect_changes 不出现新增受影响产品流程。

## 接受证据

- package boundary schema v4 报告 AI 为 62 source、1 root/16 root lines/61 nested，workspace 仍为 19 package、768 source、
  45 root、723 nested，`singleSourcePackages=[]`；7 项 boundary fixture 全部通过。
- AI 212 项为 209 pass/3 条 PostgreSQL 条件 skip；完整 19-package clean build/test 通过；backend 1,112 项为
  1,110 pass/2 skip/0 fail。cluster dependency、package boundary、Edge import、local image 四项审计均 compatible。
- 十档 artifact/RSS 全部 compatible。基础 Edge 保持 3,635,004 bytes/332 files/48 loaded modules；AI-only Edge 为
  5,022,545/396/49；最大 Standalone Application AI 为 6,123,597/491/104，低于 6 MiB/768 files 门。
- 强制 GitNexus 为 43,284 nodes/98,496 edges/1,695 clusters/269 flows。移动后 CRITICAL/HIGH 符号的 direct/total/process
  计数与移动前一致；`bootstrapModelGatewayProfile` 仍为 LOW（1 direct/1 total/0 process）。`detect_changes` all/compare
  `develop` 仍为 12 files/31 symbols 与 14/34，均 low/0 affected process。
- 本批没有修改 SQL、migration checksum、生产 dependency 或 Cluster 状态，不重复制造无关 PostgreSQL HA 物理证据；
  相关根 live-contract 路径契约 8/8 通过。