qinglong/docs/adr/ADR-0256-owner-authenticated-local-task-definition-management.md

# ADR-0256：Owner-authenticated Local TaskDefinition Management

- 状态：Accepted
- 日期：2026-08-01
- 关联 RFC：QL-RFC-0001 D-85、D-175、D-207、D-239
- 关联 ADR：ADR-0074、ADR-0085、ADR-0089、ADR-0091、ADR-0092、ADR-0217

## 背景

Fresh Edge/Standalone 已具备版本化 TaskDefinition、内建 `qinglong/command@v1`
语义注册表、原子 execution revision 物化、Owner credential 和 Project Policy，但产品入口
仍只能通过测试或直接 Repository 写入 TaskDefinition。部署者无法用受支持命令完成
create/update/enable/disable/inspect/list，也就无法在 fresh 安装后建立第一个可调度任务。

这个缺口不能靠向常驻 application 暴露写 Repository 解决。路由设备不应因此增加管理
daemon、第二数据库连接、timer 或新的 workspace package；Cluster 也不能复用本机文件
credential 和 SQLite authority 来绕过 PostgreSQL/RBAC/多副本管理边界。

## 决策

1. 在既有 `@qinglong/local-owner-cli` 增加唯一短生命周期 binary `ql3-task`，只接受
   `run --command-file /absolute/private-command.json`。command file 必须位于 deployment
   root 内、由当前 UID 持有、模式 `0600`、不是 symlink；不接受参数拼装的 Task spec。
2. v1 只开放 `task.put|task.inspect|task.list`。`task.put` 以
   `expectedRevision=null` 创建，以当前 revision 更新；`enabled=false|true` 分别表达
   disable/enable 的新 revision，不提供 update-in-place 或 delete。
3. 写入只接受已冻结 registry 中的 Task spec；当前 production registry 仍只有
   `qinglong/command@v1`。CLI 不因为 envelope 支持 `script|workflow|agent|tool` 就猜测其语义。
4. 每次命令建立短生命周期 SQLite connection，使用现有 Owner pepper/credential
   authentication 和 Project Policy。create/update 分别要求 `task.create|task.update`，查询
   要求 `task.read`；principal 必须是 strong User，owner/admin/operator 可写，viewer 只读。
5. 写事务在同一 `BEGIN IMMEDIATE` 内重新验证 credential/Identity/pepper fence、Project
   version/status、RoleBinding version/state，并原子提交 allowed audit、Task head、immutable
   revision、mutation replay 与适用的 local execution revision。任何 fence、semantic、revision
   或 audit replay 冲突整体回滚。
6. `mutationId` 同时是 allowed audit event ID；`requestId`、actor、Policy fence、operation 和
   immutable `occurredAtMs` 都属于 exact replay 语义。调用结果未知时只能原样重放 command
   file。复用 mutation 但改变 Task 或 audit 语义必须失败关闭。
7. inspect/list 使用当前 head、最多 256 条的稳定 `taskId` keyset；每页使用新的
   request/audit identity。输出只包含 Project/task、revision、name、kind/schema、enabled、
   content digest 与时间，不回显 spec/config/command 参数、SecretRef、credential、pepper、
   数据库路径或 command-file 路径。
8. 实现只增加现有 `runtime-core`、`local-sqlite`、`local-admin`、`local-owner-cli` 的显式
   subpath；workspace 保持 19 个 package，不新增第三方或 production dependency、migration、
   daemon、timer、watcher、listener、cache、Pool 或端口。Edge/Standalone 空闲成本为零，只有
   operator 发起命令时产生一个短进程和一个 SQLite connection。
9. `ql3-task` 明确不支持 Cluster。Cluster TaskDefinition 管理必须后续通过 PostgreSQL 管理
   repository、独立 credential/RBAC、强认证 transport、持久审计和多副本 fence 提供；不能
   挂载本机 Owner credential 或把 SQLite command file 当集群管理协议。

## 失败与恢复

- 配置、路径、权限或 Task semantic 失败：修正后创建全新的 command identity；
- 认证、授权或 fence 失败：恢复 credential/RoleBinding 后创建新命令，不复用已改变语义的
  mutation；
- revision conflict：先 inspect 当前 revision，再以新 mutation/时间提交明确更新；
- COMMIT 结果未知：保留原 `0600` command file 并逐字重放；`existing` 表示 durable semantic
  已存在，不重新创建 revision；
- audit 与 Task replay 不一致：停止自动重试并人工检查，禁止直接 SQL 修补或删除历史。

## 被拒绝的替代方案

1. **新建 `task-admin` workspace package**：没有独立部署、依赖或权限域，只会让 19 包拓扑
   再次碎片化，拒绝。
2. **把写入口放进常驻 local application**：扩大空闲 authority 和攻击面，也让路由设备为偶发
   管理持续付费，拒绝。
3. **直接使用 SQLite/Repository 脚本**：绕过 authentication、Policy、audit、semantic registry
   和 revision fence，拒绝。
4. **用 `task.enable|disable` 修改 head bool**：破坏 append-only 历史、pinned Run 解释和 exact
   replay，拒绝；状态变化必须是新 revision。
5. **让 Cluster 复用本机 CLI**：SQLite 单 authority 和本机 credential 不具备 PostgreSQL HA、
   多副本竞争或集群 RBAC 语义，拒绝。

## 验证

- `ql3-task` 真实 SQLite 纵切面覆盖 create、exact replay、disable、inspect、keyset list、
  operator allow、viewer deny、credential/Policy race rollback、Task semantic drift、audit semantic
  drift、私有 command file 与低敏输出；当前 5/5；
- `@qinglong/local-owner-cli` 完整 dependency closure strict TypeScript 通过；
- Owner CLI 83/83、local-admin 81/81、local-sqlite 189/189、backend 956 pass/2 条件
  skip/0 fail；19 个 QL3 package 清理后顺序构建并完成全量测试，所有已执行 suite 零失败；
- dependency boundary 40/40 且 repository audit `findings=[]`，Edge import 与 local image
  静态 inventory audit 均 compatible；GitNexus compare-to-develop 为 LOW、0 条受影响执行流；
- PostgreSQL 18.4 arm64 physical HA 同轮重新通过 `remote_apply`、timeline 1→2、旧主先
  fencing、`pg_rewind` 只读同步重入、两个 fresh control replica 与全部业务 gate，
  `gates.passed=true`；测试容器、网络、卷零残留。此项只证明 Cluster 基线未回归，不把
  本机 `ql3-task` 宣称为 Cluster 产品入口；
- 完整 package/backend/dependency/artifact 回归是合入前门禁。

D-239 验证时曾发现 storage-only 超过 512 files、adopted assembly 漏收 `local-secret`，且
application 为 741 files、约 6.40 MiB、import RSS delta 约 20.2--20.35 MiB，因此本 ADR
当时没有把 Profile gate 标记为通过。后续 ADR-0257/D-240 已通过内部运行制品裁剪、精确 adopted
闭包和 eager import 收口修复该 blocker；十档门现已全部通过。D-239 没有自行放宽预算，完整
application 的 24 MiB import delta 分层也不改变 Edge 96 MiB 总物理进程预算。

## 后续约束

后续 ADR-0258/D-241 已完成 Trigger create/update/enable/disable/inspect/list 和
Task→Trigger→Run 的可操作 fresh 用户闭环，并在 Trigger 写入、scheduler candidate 与最终 Run
commit 三处执行 Task current-head fence。下一步为 Cluster 实现 PostgreSQL/RBAC 对等管理入口。
HTTP/UI 只能调用同一服务语义，不能复制 Task/Trigger semantic、Policy、current-head fence 或
replay 规则。非 command kind 仍须各自完成 semantic、权限、编译与执行评审后才能进入
production registry。