qinglong/docs/adr/ADR-0258-owner-authenticated-local-trigger-management-and-current-task-fence.md

# ADR-0258：Owner-authenticated Local Trigger Management 与 Current Task Fence

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

## 背景

ADR-0256 已让 fresh Edge/Standalone 能通过受支持入口创建 TaskDefinition，但部署者仍不能
创建、更新、停用、启用或查询 Trigger，Fresh Setup 因此停在 Task 而不能完成
Task→Trigger→Run。既有 scheduler 还只检查 Trigger current head；Task 更新或停用后，固定到
旧 Task revision 的已启用 Trigger 仍可能继续产生 Run。这会绕过部署者对 Task current head
作出的撤权决定。

该缺口不能通过新增常驻管理服务、每 Trigger timer 或新 workspace package 解决。路由设备的
空闲资源边界必须不变；Cluster 也不能复用本机 SQLite、Owner credential file 或 command file
来绕过 PostgreSQL/RBAC 与多副本围栏。

## 决策

1. 在既有 `@qinglong/local-owner-cli` 增加短生命周期 binary `ql3-trigger`，只接受
   `run --command-file /absolute/private-command.json`。command file 必须位于 deployment root
   内、由当前 UID 持有、模式 `0600` 且不是 symlink。
2. v1 只开放 `trigger.put|trigger.inspect|trigger.list`。`trigger.put` 以
   `expectedRevision=null` 创建，以 current revision 更新；enable/disable 都追加 immutable
   Trigger revision，不提供原地修改或 delete。production registry 只接受
   `qinglong/cron@v1`。
3. 创建或更新必须绑定 exact `taskId`、`taskRevision` 与 `taskContentDigest`。启用的 Trigger
   只能绑定同 Project 下当前、内容摘要一致且 enabled 的 Task head。Task 更新、停用或重新启用
   后，旧 Trigger 失败关闭，必须由部署者显式提交新 Trigger revision 完成 repin。
4. 为避免撤权死锁，`enabled=false` 的新 Trigger revision 可以继续绑定历史 Task revision；
   因此 Task 已变化或停用后，operator 仍能明确停用 stale Trigger。再次启用时必须 repin 当前
   Task head。
5. scheduler 在两个位置复验 Task current fence：候选发现必须联结 current Task head；最终
   创建 Run 的事务必须再次验证 Task current revision、content digest 和 enabled。扫描后发生
   Task race 时不得创建 Run，不能只依赖 Trigger 写入时的检查。
6. 每次命令建立短生命周期 SQLite connection，复用 Owner pepper/credential authentication
   与 Project Policy。put 要求 `task.update`，inspect/list 要求 `task.read`；principal 必须是
   strong User。沿用 Task 权限是因为 Trigger 直接改变该 Task 的调度能力，v1 不另造含义重叠的
   permission。
7. 写事务在同一 `BEGIN IMMEDIATE` 内重新验证 credential/Identity/pepper、Project 与
   RoleBinding fence，并原子提交 allowed `trigger.create|trigger.update` audit、Trigger head、
   immutable revision、mutation replay 和本机 schedule reset。任何认证、Policy、Task、revision、
   audit 或 replay 漂移都整体回滚。
8. `mutationId` 同时是 allowed audit event ID；request、actor、Policy fence、完整 Trigger
   mutation 与 immutable `occurredAtMs` 都属于 exact replay。结果未知时只能原样重放同一个
   command file。
9. inspect/list 只返回低敏 current-head 摘要：Project/Trigger、revision、Task binding、schema、
   enabled、content digest 与时间；不回显 cron expression、timezone、misfire policy、credential、
   pepper、数据库路径或 command-file 路径。list 使用最多 256 条的稳定 `triggerId` keyset。
10. 实现只增加既有 `runtime-core`、`local-sqlite`、`local-admin`、`local-owner-cli` 的 source
    module 与 subpath。workspace 保持 19 个 package，不新增 production dependency、migration、
    daemon、timer、watcher、listener、cache、Pool、连接或端口。只有 operator 执行命令时产生
    一个短进程和一个 SQLite connection。
11. `ql3-trigger` 只支持 Edge/Standalone。Cluster 必须使用后续 PostgreSQL 管理 repository、
    集群 credential/RBAC、强认证 transport、durable audit 与多副本 fence；不得把本机文件挂进
    Pod 伪装集群管理入口。

## 失败与恢复

- Task 已更新或停用：scheduler 自动停止 admission；先 inspect Task current head，再明确停用
  stale Trigger，或以新 mutation 将 Trigger repin 到已启用的 current Task；
- revision conflict：inspect Trigger current revision 后人工确认，再生成新 command identity；
- 认证、授权、Task fence、semantic 或 audit conflict：失败关闭，不创建半个 revision 或 Run；
- COMMIT 结果未知：逐字重放原 `0600` command file；`existing` 表示相同 durable semantic 已提交；
- 禁止直接修改 Trigger、schedule 或 audit 表来“恢复”，历史 revision 必须保留解释既有 Run。

## 被拒绝的替代方案

1. **新增 `trigger-admin` package**：没有独立交付、依赖或权限域，会重现单文件/小包碎片化，拒绝。
2. **让旧 Trigger 永久执行 pinned Task**：Task current head 的停用/替换将不能撤销后续 admission，
   拒绝；历史 pin 只用于解释已创建 Run。
3. **只在 Trigger 写入时检查 Task**：扫描与 commit 之间仍有竞态，拒绝；最终 Run admission 必须
   重验 current Task fence。
4. **Task 变化时自动改写 Trigger pin**：会在没有 operator intent、audit 和 replay identity 时改变
   执行语义，拒绝；恢复必须显式 repin。
5. **禁止 stale Trigger 的任何更新**：Task 先变化后将无法停用旧 Trigger，形成撤权死锁，拒绝；
   只允许追加 disabled revision，重新启用仍须 current pin。
6. **每 Trigger 建 timer 或管理 daemon**：扩大路由设备空闲 RSS、唤醒与连接数，拒绝；复用唯一
   application scheduler cadence。

## 验证

- `ql3-trigger` 真实 SQLite 纵切面 5/5：create、exact replay、disable、inspect/list、operator
  allow、viewer deny、credential/Policy race、Task fence、audit drift、私有 command file 与低敏输出；
- SQLite Trigger/schedule 定向 7/7：Task 更新或停用后候选为空，扫描后 stale commit 不生成 Run，
  stale Trigger 可停用，Task 重新启用并显式 repin 后才恢复候选；
- fresh 产品链 1/1：`ql3-task` 创建 Task、`ql3-trigger` 创建 cron Trigger、production
  `LocalSchedulerCoordinator` 生成唯一 queued Run；Task 停用后不再产生第二个 Run；
- 19 个 QL3 package 清理、顺序构建与完整测试零失败；Owner CLI 88/88，backend 958 pass/
  2 条件 skip/0 fail；Trigger 精确依赖边界加入后定向审计 41/41，全仓 19-importer audit
  `findings=[]/compatible=true`，Edge import 和 local image inventory 均 compatible；
- 十档 exact offline artifact 全绿：storage 322 files/3,491,202--3,491,250 bytes，adopted
  361/4,064,367--4,064,451，application 415/4,548,022--4,548,166，AI-only
  345/4,082,310--4,082,370，application+AI 438/5,139,202--5,139,358；最大 import RSS delta
  20,480,000 bytes，全部低于既有分层门；
- PostgreSQL 18.4 arm64 physical HA 重新完成 `remote_apply`、timeline 1→2、旧主先 fencing、
  `pg_rewind` 只读同步重入、两个 fresh control replicas、scheduler exactly-once 与全部业务门，
  `gates.passed=true`；测试容器、网络和卷零残留。它只证明 Cluster 基线未回归，不把本机
  `ql3-trigger` 宣称为 Cluster 管理入口；
- 实现没有新增 workspace package、第三方依赖、migration 或常驻资源；GitNexus 刷新后为
  37,577 nodes/85,540 edges/280 flows，相对 `develop` 与整个工作树的 change detection 均为
  LOW、0 affected process。

## 后续约束

- 下一步为 Cluster 提供 PostgreSQL/RBAC 对等的 Task/Trigger 管理 transport，不能共享本机
  credential 或 SQLite authority；
- HTTP/UI 只能调用同一 administration service 语义，不能复制 Policy、Task current fence、
  audit 或 replay 逻辑；
- 新 Trigger schema 必须先完成 semantic registry、资源预算、安全与执行语义评审；
- 每次修改 Task/Trigger/scheduler admission 都必须覆盖“候选后 race、最终 commit 失败关闭”。