qinglong/docs/adr/ADR-0304-root-public-export-proof-and-owner-command-ownership.md

ADR-0304：根 Public Export 纯转发证明与 Owner Command 实现归属

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

上下文

schema v4 已冻结 19 个 workspace package 的根文件名、角色和行数，但 public_export 只证明文件被 manifest 指向，没有证明文件本身只是发布边界。复核 @qinglong/cluster-postgres 剩余 10 个根入口/520 审计行后，AST 显示十个文件都只含 TypeScript ExportDeclaration；它们分别是 runtime、admin、Package manager/executor、Worker ingress、Automation 与 AI credential/maintenance 的最小权限公开面，不是隐藏实现。把它们机械移动到 public-api/ 只会改变物理层级，不会改善 ownership。

同一轮全 workspace AST 复核发现两个反例：@qinglong/local-owner-cli/src/index.ts 的 413 行与 @qinglong/local-owner-maintenance/src/command.ts 的 317 行被登记为 public_export，但实际包含 command parsing、 validation、dependency assembly 与 execution。它们没有独立部署、版本、依赖或权限边界，不应拆成新 package；也不应 继续用发布角色隐藏实现。

移动前 GitNexus 将 LocalOwnerCliConfigurationError 与同文件 exactKeys 判为 HIGH，分别为 6 direct/ 10 total/0 process 与 4/9/0；已在编辑前显式告警。Maintenance 配置错误最高为 MEDIUM 5/7/0。两个 runner 均为 LOW 1 direct/3 total/0 process。本批只改变物理路径、相对 import、manifest target 和审计证据，不改变 command schema、validation、error identity、dependency custody、authority、执行顺序或 close 语义。

决策

1. package boundary ledger 升为 schema v5。非浅层 package 的每个 public_export 根文件必须可解析且非空，并且 AST statement 全部是 ExportDeclaration；出现 function、class、variable、expression 或其他实现 statement 时以 PACKAGE_SOURCE_ROOT_PUBLIC_EXPORT_IMPLEMENTATION 失败。
2. local-profile 与 local-adopted-profile 的三组根产品入口继续使用 shallowSourceLayoutKind=public_entrypoints。 它们不是任意豁免：schema v3 已要求 manifest artifact 一一映射、真实 consumer 与递归 production closure 防火墙； 证据消失时必须下沉或合并。
3. @qinglong/cluster-postgres 的十个根 facade 保持原位。它们是 manifest 可证明、AST 纯转发、按 authority 拆分的公开 subpath；不以 root=0 为目标创建 public-api/ 目录或 wrapper。
4. Owner CLI 实现迁至 src/application-command/localOwnerCommand.ts；Maintenance command 实现迁至 src/application-command/localOwnerMaintenanceCommand.ts。CLI binary 和 manifest 直接依赖嵌套产物，不保留旧根 facade。
5. 公开 package specifier、@qinglong/local-owner-maintenance/command subpath、binary 名、exported symbol 与 error class identity 保持不变。测试改从公开 specifier 加载，clean build 必须证明旧 dist/index.*/dist/command.* 不存在。
6. 不新增 workspace package、生产依赖、数据库对象、connection、timer、listener、进程、binary 或部署单元。

被拒绝的方案

• 把 Cluster PostgreSQL facade 全部移到 public-api/：十个文件已是纯转发 least-authority surface；移动不会产生 新 ownership，只会增加 import 与 manifest 噪声。
• 只依赖根行数 hard cap：实现可以在不新增文件的情况下继续藏进既有 public_export，schema v4 无法识别。
• 为两个旧根路径保留 wrapper：物理路径不是公开契约，wrapper 会重新占用根 cap 并允许实现再次回流。
• 把两个 command 各拆成 workspace package：它们分别只服务现有 CLI/maintenance deployable，没有独立 consumer、 dependency closure 或权限域，拆包会增加低配设备的 importer、lockfile 与 SBOM 复杂度。
• 把浅层 Profile 一并强制为纯转发：三组文件是独立 Edge/Standalone 产品组合入口，已有更强的 artifact/closure 证明； 机械下沉不改变交付边界。

接受条件

1. schema v5 正向审计 19/19，无 finding；负向 fixture 能拒绝“以 public export 名义隐藏实现”，已有浅层 Profile 证据继续通过。
2. workspace 保持 19 package/768 source；root 34→32、nested 734→736。Owner CLI 为 48 source、root 2→1、 463→50 行、nested 46→47；Maintenance 为 6 source、root 2→1、367→50 行、nested 4→5。
3. 两个包 check/test、完整 clean 19-package、backend、dependency/boundary 与 Edge/Local/Cluster 制品门通过；十档 artifact 的 bytes/files/modules/RSS 不回退。
4. PostgreSQL HA 物理门通过，且门后 Docker 容器、volume、network 无残留。
5. 强制 GitNexus 不增加产品流程，公开 runner 的直接调用不扩大，detect-changes 保持 low/0 affected process。

接受证据

• package boundary schema v5 为 19 package/768 source、32 root、736 nested，singleSourcePackages=[]；边界 fixture 8/8、dependency fixture 47/47，最终审计 findings=[]。
• Owner CLI 与 Maintenance 的 closure build/typecheck 通过；clean 19-package 从全空 dist 重建并完成测试。Owner CLI 旧 dist/index.*、Maintenance 旧 dist/command.* 均不存在，两个新 application-command JS/declaration 同时存在。
• Worker Runtime 三项本地 TLS/mTLS 测试在受限沙箱内仅因 listen EPERM 127.0.0.1 失败；沙箱外重跑 132/132 通过。 backend 为 1,113 项：1,111 pass/2 条件 skip/0 fail。
• Edge import、Local image、Cluster deployment 与 image release compatible；十档 artifact 全部 compatible 且与前批逐字节 一致。基础 Edge 为 3,635,276 bytes/332 files/48 modules；最大 Standalone Application AI 为 6,123,869 bytes/491 files/104 modules，Owner command 实现未进入路由设备 runtime closure。
• PostgreSQL 18.4 arm64 HA gates.passed=true：remote_apply、timeline 1→2、旧主先 fencing、pg_rewind 后只读同步 rejoin 与两个 fresh control ready 均成立；门后 ql3-ha-* container、volume、network 精确为空。
• 强制 GitNexus 刷新为 43,358 nodes/98,573 edges/1,698 clusters/269 flows。两个 command runner 均为 LOW 1 direct/3 total/0 process；Owner/Maintenance 配置错误分别为 MEDIUM 6/11/0 与 5/8/0，直接调用未扩大， 聚类归位造成 total/risk 标签重算不解释为行为变化。auditPackageBoundaries 为 LOW 2/2/0，auditSourceImports 为 LOW 1/1/0。detect-changes all/compare develop 为 12 files/31 symbols 与 14/34，均 low/0 process。