qinglong/docs/adr/ADR-0212-owner-fenced-local-project-lifecycle.md

ADR-0212：Owner 围栏化 Local Project 生命周期

• 状态：Accepted
• 日期：2026-07-29
• 关联 RFC：QL-RFC-0001 D-05、D-27、D-37、D-65、D-72、D-73、D-175、 D-198、D-201、D-202
• 关联 ADR：ADR-0028、ADR-0074、ADR-0086、ADR-0185、ADR-0207、 ADR-0208、ADR-0211

背景

ADR-0208 让既有 Project 的 RoleBinding 有了强认证产品入口，但 Project 本身仍只能 通过迁移、测试 fixture 或直接 SQL 建立。部署者无法用受支持方式：

• 创建第二个业务 Project；
• 原子建立首个可接管 Owner；
• 暂停一个 Project 的全部业务授权；
• 在保留历史、RoleBinding 和资源的前提下恢复 Project。

Project lifecycle 是实例级管理动作，不应由任意 secondary Project Owner 执行。 如果创建 Project 与创建首 Owner 分成两个事务，进程在中间崩溃会留下无人可管理的 active Project。若直接覆盖 Project 行，又会失去响应丢失重放和审计事实。

决策

1. 扩展既有 ql3-policy，不新增 workspace package

继续使用以下既有边界：

• @qinglong/runtime-core/local-project-policy-administration：命令、结果和错误契约；
• @qinglong/local-sqlite/project-policy-administration：最终事务 authority；
• @qinglong/local-admin/project-policy-administration：强认证 Owner 服务；
• @qinglong/local-owner-cli/project-policy-command：私有 command file 与低敏输出；
• ql3-policy：一次命令、一次进程的产品 binary。

新增三个 operation：

• policy.project.create；
• policy.project.archive；
• policy.project.restore。

workspace 仍为 22 个 package。该领域与 RoleBinding 共享认证、Policy、SQLite authority、CLI 和部署消费者，不满足 ADR-0185 的新交付/进程/依赖隔离条件；把它 拆成单文件 package 只会增加 importer、lockfile 和供应链维护成本。

2. 只有实例 authority Project 的当前强认证 Owner 可以变更生命周期

command 同时携带 authorityProjectId 和目标 projectId。服务层先要求调用者在 authority Project 上通过 Owner-only project.manage。SQLite 在 BEGIN IMMEDIATE 取得写锁后再次复验：

1. authenticated credential、Identity、有效期、pepper binding/catalog/material；
2. ADR-0211 的实例 authority anchor；
3. authority Project active/version；
4. actor 最新 RoleBinding version/state/owner role。

secondary Project Owner 即使能通过自己 Project 的 policy，也会在最终 authority anchor 检查失败关闭。直接调用 repository 不能绕过。

3. Project create 与首 Owner、审计、mutation ledger 原子提交

policy.project.create 要求：

• expectedCurrentVersion = 0；
• 唯一且规范的 Project ID、name、slug；
• UUIDv4 mutation 和独立 failure-audit UUID；
• Profile 容量仍有余量。

同一事务插入：

1. version 1、active 的 Project；
2. actor 自身 version 1、active/owner 的 RoleBinding；
3. allowed security audit；
4. immutable Project administration mutation。

任一步失败全部回滚。成功输出只含 Project ID、name、slug、status、version 和 inserted|existing。

4. archive/restore 是版本化状态转换，不删除历史

• archive：active@N → archived@(N+1)；
• restore：archived@N → active@(N+1)；
• 两者都使用 expected-version CAS；
• authority Project 禁止 archive；
• archived Project 由现有 Project Policy 默认拒绝业务权限；
• RoleBinding、Task、Run、Secret、Package 和审计历史不删除；
• restore 后沿用既有 RoleBinding，重新进入正常 Policy 判定。

本切片不提供 hard delete。需要资源清理时必须另建引用感知、可恢复的 retention 协议，不能把 archive 冒充删除。

5. mutation ledger 提供精确响应丢失重放

SQLite v37 新增 QingLong3ProjectAdministrationMutations，冻结 operation、 authority Project、目标 Project 快照、前后版本、actor、首 Owner version、audit 和 时间。相同 mutation 且语义完全一致返回 existing；相同 mutation 用于不同操作、 Project、metadata、版本、actor 或 audit 时返回 mutation conflict。

Project 当前行是可变 head；mutation ledger 是不可变历史，两者不能合并成同一事实。

6. Profile 容量是硬上限

• Edge：最多 16 个 Project；
• Standalone：最多 128 个 Project。

容量在最终写事务内计数，达到上限时不写 Project、Owner、allowed audit 或 mutation。 archive 不释放名额，因为对象和引用仍然存在。容量仅影响人工管理命令，不增加 daemon、timer、watcher、listener、缓存或空闲写入。

不采用方案

为 Project lifecycle 新建 package

拒绝。它与 RoleBinding 共用同一产品、authority 和交付闭包，没有独立消费者或进程 权限，违反 ADR-0185 的 package budget。

允许任意 Project Owner 创建其他 Project

拒绝。Project-scoped RBAC 不能隐式授予实例拓扑 authority，否则 secondary Owner 可无限扩展实例作用域。

先创建 Project，再单独授予 Owner

拒绝。崩溃窗口会留下 active 但无人可管理的 Project。

archive 时删除 RoleBinding 或业务数据

拒绝。删除会破坏审计、历史 Run 可解释性和可恢复性，也无法安全判断所有引用。

只更新 Project 当前行，不保存 mutation ledger

拒绝。COMMIT response loss 后无法区分未执行、已执行和被其他命令覆盖。

影响

正向影响：

• 本机部署首次具备受支持的多 Project 创建、暂停和恢复路径；
• 创建后立即存在可登录、可交接的 Owner；
• archived Project 自动复用既有默认拒绝 Policy；
• secondary Project Owner 与 direct repository caller 均不能扩大实例拓扑；
• Edge/Standalone 资源上限明确，空闲成本为零；
• workspace 保持 22 包，没有新增第三方依赖。

代价与限制：

• Local SQLite contract 从 v36 提升到 v37，镜像和 rollout 写契约必须同步升级；
• Project list/inspect 由 ADR-0213 补齐；当前仍没有 rename、authority transfer 或 hard-delete 产品命令；
• authority Project 无法 archive；恢复该根对象需要未来独立 break-glass ceremony；
• Cluster 仍使用 PostgreSQL/RBAC 管理面，不能复用本机 command file。

验证

• GitNexus 对共享 SQLite readiness 入口评估为 CRITICAL：15 个直接调用者、35 个上游 符号；v37 必须跑迁移、冷启动、rollout 和既有安全回归；
• ql3-policy 真实 SQLite/CLI 10/10：
  • create/exact replay；
  • 首 Owner、audit、mutation 原子事实；
  • archive 后业务 policy 拒绝、restore 后恢复；
  • mutation drift、ID/slug 冲突；
  • authority Project archive 拒绝；
  • secondary Project Owner 越权拒绝；
  • Edge 第 17 个 Project 在零部分写入下拒绝；
  • 既有 RoleBinding、防锁死和 credential fence 回归；
• SQLite database 13/13、rollout safety 7/7、Identity/Credential 聚焦 4/4；
• local-admin 与 local-owner-cli strict TypeScript 通过；
• Local image/OCI labels、CI image contract 和 deployment evidence 必须固定为 v37；
• 完整 workspace、制品/RSS 和 PostgreSQL HA 门在锁定依赖恢复后重跑。