qinglong/docs/adr/ADR-0176-explicit-local-ai-feature-activation-and-deactivation.md

# ADR-0176：显式 Local AI Feature 启用与非破坏性停用

- 状态：Accepted
- 日期：2026-07-27
- 关联：RFC D-40、D-73、D-84、D-87、D-156、D-165、D-166；ADR-0087、ADR-0167、ADR-0175

## 背景

ADR-0175 要求 Model Price Catalog CLI 不得自动执行 AI DDL，但部署者当时没有受审的
产品启用入口，只能由测试或部署代码直接调用 `migrateLocalModelInvocationFeature()`。
这会产生三个问题：

1. “schema 已存在”和“部署者已明确启用”是同一个隐式状态，无法安全停用；
2. 迁移版本、备份确认、稳定 User、强认证和当前 Owner 没有绑定到耐久启用事实；
3. 只在 CLI 外层检查启用状态，无法阻止停用提交后的并发 invocation admission。

本机 feature migration 还可能跨多个 SQLite 事务。进程在某一步迁移后退出时，不能假装
整次启用原子完成；重试必须从受审 history/checksum 恢复，并且只有最后的 activation
transition 提交后，业务写入口才可到达。

## 决策

### 1. 复用现有包和短生命周期 authority

在现有 `@qinglong/local-owner-cli` 增加：

- 显式子路径 `@qinglong/local-owner-cli/ai-feature-command`；
- 二进制 `ql3-ai-feature`；
- `ai-feature.inspect|activate|deactivate` 三种 operation。

不新增 workspace package、第三方依赖、daemon、listener、timer、watcher 或缓存。CLI
仍只接受私有 exact-shape command file，完成后关闭唯一 SQLite authority。默认
edge/standalone runtime、通用 local-admin 和 Cluster image 不导入该入口。

现有 SQLite facade 的实现原本以 Plugin Package 命名，却已被多个本机管理域复用。
本 ADR 在同一个 `@qinglong/local-sqlite` 包内增加中性的
`/authenticated-management` 子路径，并保留 `/package-management` 兼容入口；不为
一个类型别名拆新包。

### 2. 9007 只属于本机 AI feature stream

本机 AI migration stream 在既有 9001–9006 后追加：

```text
9007-ai-feature-activation
```

9007 创建两张本机控制表：

- `ModelInvocationFeatureTransitions`：append-only generation、active/inactive、
  mutation/request、migration plan、data-safety、User/authentication 和 digest；
- `ModelInvocationFeatureHead`：只指向一个已存在的不可变 transition。

PostgreSQL Cluster 仍保持 pg-9001–pg-9006、11 张业务表和既有 ACL，不能把本机
Owner ceremony 复制成 Cluster authority。9007 checksum 为
`2454987c61a48dc5286a883d755c709000e6fd630025373cb276723001bdcc6c`；
包含 9001–9007 的 migration plan digest 为
`529cd8d3bce9ef124dd609044c4f704ea313926c9c8fc422c23871e110fed538`。

### 3. inspect、activate 与 migration plan fence

`inspect` 只有在 local-console 强认证和当前 `default` Project Owner 复验后，才返回：

- `absent | partial_or_drifted | ready` 三态 schema 摘要；
- 当前 active/inactive generation 的低敏摘要；
- 当前二进制的 migration plan digest。

`activate` command 必须回传 inspect 得到的 exact plan digest 和 CAS generation/state。
代码版本、迁移顺序或任一 checksum 改变都会形成新 plan digest，旧 command 不得执行
新 DDL。

首次启用必须选择一种 data-safety 证据：

- `fresh_database`：只允许没有 AI durable data 的 feature；不带备份 digest；
- `backup_verified`：带 64 位十六进制 backup evidence digest。

CLI 在 DDL 前和 transition 前均复验 credential、pepper、User 和 Owner。9001–9007
逐步使用既有 migration history/checksum 收敛；崩溃后可能留下 reviewed partial
schema，但不会留下 active head。重试完成全部 migration 并再次通过强认证后，才在
一个 `BEGIN IMMEDIATE` 中写 transition/head。相同 mutation 的响应丢失重试优先返回
首次 durable transition，即使启用后已经产生业务数据也不得重新执行“空库”裁决。

### 4. 停用不删除数据，并形成 admission fence

`deactivate` 只追加下一代 `inactive` transition 并更新 head：

- 不执行 `DROP`、`DELETE`、清表、回滚 migration 或修改历史；
- data-safety 必须固定为 `preserve_existing`；
- 有未完成 ModelInvocation 时拒绝停用；
- credential/User/pepper/Owner 与未完成调用检查在 transition 的同一
  `BEGIN IMMEDIATE` 中再次执行。

本地 invocation 的 `admit`、`admitWithQuota`、`admitWithPricing` 在各自
`BEGIN IMMEDIATE` 内、写任何新 start 前读取 active head。价格目录 mutation 也在其
事务 hook 内复验 active。由此：

- admission 先提交时，停用随后看到未完成调用并拒绝；
- 停用先提交时，后续 admission/价格 mutation 看到 inactive 并拒绝；
- 已经存在的 admission replay 和 completion/recovery 仍可完成，不因停用破坏耐久
  收敛。

这是一条数据库串行化写围栏，不依赖进程内布尔值、文件锁或 watcher。

### 5. 鉴权、审计和输出

三种 operation 都要求稳定 User、`local_console` assurance、credential-version pepper
provenance 和当前平台 Owner。命令不得提供 principal、authentication ID、assurance、
Owner、Policy 或数据库时间。

成功由 append-only transition/head 证明；失败写现有低敏 SecurityAudit，固定原因包括：

- `credential_rejected` / `credential_fence_rejected`；
- `platform_owner_required`；
- `data_safety_rejected`；
- `in_flight_invocation`；
- `transition_conflict` / `transition_unavailable`；
- `migration_unavailable`。

输出不包含 credential、secret、principal、subject ID、authentication ID、备份路径或
DDL 细节。

## 拒绝方案

1. **新增 `ql3-ai-feature-cli` package**：没有新的部署边界，只会制造小包，拒绝。
2. **让 `ql3-model-price` 顺便迁移**：把日常业务管理升级为 DDL authority，拒绝。
3. **以 schema presence 代表 enabled**：无法表达显式停用和 operator intent，拒绝。
4. **停用时 DROP AI 表**：破坏账本、重放、恢复和备份语义，拒绝。
5. **只在启动配置读取一个布尔值**：无法和 durable admission transaction 串行化，
   拒绝。
6. **只在停用前事务外检查未完成调用**：检查后仍可并发创建 start，拒绝。
7. **把 9007 同步加入 PostgreSQL**：本机 Owner ceremony 不具备 Cluster TLS、平台
   Policy、耐久 quota 和职责分离 authority，拒绝。

## 当前证据

- AI suite 96 项：94 pass、2 条真实 PostgreSQL 条件 skip；覆盖 9007 schema/history、
  append-only transition/head、CAS/plan/identity drift、事务 hook/replay、inactive
  admission fence 和既有 crash matrix；
- local-owner-cli 22/22，覆盖真实 `ql3-ai-feature` binary、inspect/activate/replay/
  deactivate、无敏感输出、widened body、plan drift、pre-migrated backup evidence、
  credential revoke、in-flight deactivation rejection 和 inactive price gate；
- local-sqlite 127/127；22-importer dependency audit `findings=[]`，AI 21 个、Owner
  CLI 10 个源码文件；edge 121-module import gate 无 AI 越界；
- clean build 后 workspace 仍为 22 个 QL3 package，没有新增生产依赖或常驻资源；
  base edge/standalone 均为 478 files，AI opt-in 制品均为 522 files，disabled loader
  的 storage/provider/management authority load 保持为 0；
- 2026-07-27 重新执行 PostgreSQL 18.4 arm64 physical HA 门，timeline 1→2、
  old-primary fence、双 control replica 重建、`pg_rewind` 只读 sync rejoin 与总
  `gates.passed=true`。AI 专项在 promotion 前后均精确保持 pg-9001–pg-9006、
  11 张表和同一最小权限矩阵；本机 9007 未进入 PostgreSQL history，因而该证据不
  冒充 Cluster activation ceremony。

## 后续门禁

1. 产品启动 composition、active-head dynamic import、restart/drain/operator UX 已由
   ADR-0177 完成；真实产品 executable 仍需选择该显式入口；
2. 私有命令模板、备份/恢复演练和真实低配 Linux 设备断电/ENOSPC 证据；
3. activation transition 与 Model Price mutation 专属 SQLite
   COMMIT-response-loss/SIGKILL 矩阵；
4. Cluster TLS identity、平台 Policy/quota、双人 activation 和独立 transport；
5. 只有 Cluster 入口变更 PostgreSQL schema/ACL 后才重跑对应三角色与 physical HA 门。