docs: plan worker control plane session runtime

docs/superpowers/specs/2026-07-31-worker-controlplane-session-runtime-design.md

@@ -95,9 +95,15 @@ Cluster slot。
 - `checksum`
 - `expires_at`
 
+引用按 `(ownership_epoch, version)` 严格单调前进。相同 tuple 只允许使用
+相同 checksum 幂等续期；同 tuple 更换 checksum 或倒退 tuple 均原子失败。
 发布新引用会覆盖旧引用。旧版本 ACK 必须失败，Worker 后续通过完整 Snapshot 重同步。
 Snapshot payload 不在本轮写入 Redis；下一轮会评估 payload 存储和流式分发方式。
 
+全局 ownership epoch 是 namespace 内的持久单调标量，不跟随 ownership TTL
+过期。既有 namespace 在首次控制面读取或下次 Assign/Renew 时移除该 key
+的历史 TTL，避免 epoch 回退产生 ABA。
+
 ## 4. Session 状态机
 
 Session 有以下状态：
@@ -116,6 +122,13 @@ Session 有以下状态：
       | 空或非空 Runtime
       +--------------------> [续期]
       |
+      | 对新 Snapshot 的负向 ACK
+      v
+[保留旧 ACK，Runtime 已禁用]
+      |
+      | 后续有效正向 ACK
+      +--------------------> [已 ACK，可接收 Runtime]
+      |
       | 新 instance 注册 / TTL 过期
       v
 [失效]
@@ -125,7 +138,8 @@ Session 有以下状态：
 
 1. 每次成功注册都生成新的 128-bit 加密随机 Session ID。
 2. 同一 `worker_id` 再注册会替换旧 Session，并删除旧 Runtime 报告。
-3. 注册后的 `acked_snapshot_version` 和 `acked_ownership_epoch` 均为零。
+3. 注册后的 `acked_snapshot_version`、`acked_ownership_epoch` 和
+   `acked_checksum` 均为零值，`runtime_enabled=false`。
 4. Runtime 只有在 Session 已完成正向 ACK 后才可接受。
 5. 空 Runtime 报告表示完整稀疏计数全部为零，同时承担心跳并续期 Session。
 6. Session 到期后，旧实例的 ACK 和 Runtime 均失败；使用该报告计算容量时保持
@@ -134,7 +148,9 @@ Session 有以下状态：
 `supported_protocol_version` 本轮只接受 `1`。`worker_id` 与 `instance_id` 使用
 `[A-Za-z0-9][A-Za-z0-9._-]{0,127}`；`zone` 为空或使用同一字符集且最长 128 字节。
 标签最多 32 个，键最长 64 字节、值最长 256 字节，规范化后的键值总长度最多
-4 KiB；禁止重复键、空键和首尾空白。
+4 KiB；禁止空键和首尾空白。`labels` 在 protobuf 契约中是 map，重复 wire key
+在进入 Service 前已按 protobuf map 语义归一化为最后一值；Service 只验证
+解码后的唯一键集。
 
 ## 5. RPC 行为
 
@@ -155,12 +171,19 @@ Session 有以下状态：
 ACK 操作在 Redis Lua 的一个原子边界内完成：
 
 1. Session 必须存在、未过期，并匹配 worker/session。
-2. version、ownership epoch 和 checksum 必须匹配当前已发布 SnapshotReference。
+2. 先按 tuple 与 Session 已 ACK 上界比较，再与当前已发布
-3. `applied=true` 时，ACK 只能严格前进或完全相同地幂等重放；成功后续期 Session
+   SnapshotReference 比较。落后 tuple 是 stale ACK；超前 tuple 或同 tuple
-   并清除旧 Runtime。
+   不同 checksum 是 Snapshot mismatch。
+3. `applied=true` 时，ACK 只能严格前进或完全相同地幂等重放。严格前进
+   时清除旧 Runtime、保存新上界并设置 `runtime_enabled=true`；相同 ACK
+   且 Runtime 已开启时只续期 Session，不清除 Runtime 或 sequence/digest fence。
+   若相同 ACK 上界因先前负向 ACK 处于禁用状态，则清理残留 Runtime
+   并重新开启。
 4. `applied=false` 是已接受的负向 ACK：续期当前 Session，但不推进 ACK 上界、
-   不保留旧 Runtime，也不持久化自由文本错误；下一轮 Snapshot Stream 据此继续
+   不保留旧 Runtime，设置 `runtime_enabled=false`，也不持久化自由文本错误；
-   发送完整 Snapshot。
+   下一轮 Snapshot Stream 据此继续发送完整 Snapshot。只有后续正向 ACK
+   才把 `runtime_enabled` 重新设为 true，因此负向 ACK 后延迟到达的旧 Runtime
+   不能重建已清除的报告与 sequence fence。
 5. 旧版本、错误 checksum、超前版本或被替换 Session 均不修改状态。
 
 `error_code` 只接受有界枚举风格字符串；`error_message` 只做长度校验，不写日志或
@@ -171,9 +194,10 @@ ACK 操作在 Redis Lua 的一个原子边界内完成：
 处理顺序：
 
 1. 校验 Session、报告序号、时间戳、计数非负、Proxy ID 唯一和批次上限。
-2. Snapshot version 与 ownership epoch 必须精确等于 Session 已 ACK 上界。
+2. Session 必须 `runtime_enabled=true`，且 Snapshot version 与 ownership epoch 必须
-3. 相同 sequence 和相同规范化内容是幂等重放；较小 sequence 拒绝；相同 sequence
+   精确等于 Session 已 ACK 上界。
-   不同内容判定冲突。
+3. 相同 sequence 和相同规范化内容是幂等重放，但仍必须续期 Session
+   与报告 TTL；较小 sequence 拒绝；相同 sequence 不同内容判定冲突。
 4. 成功报告完整替换该 Worker 的稀疏 Runtime，并续期 Session 与报告 TTL。
 5. 返回 Controller 当前 ownership epoch；本轮 `revoke_proxy_ids` 为空。
 
@@ -211,6 +235,8 @@ controlPlane:
 - `tls.mode` 只允许 `disabled` 或 `mtls`。
 - `disabled` 只允许回环地址；非回环监听必须使用 `mtls`。
 - `mtls` 必须提供 server cert、server key、client CA、trust domain 和 environment。
+- trust domain 必须是无 port 的小写 DNS 名，environment 必须是单个有界 URI
+  path segment。
 
 mTLS Worker 身份使用 URI SAN：