docs: plan worker control plane session runtime

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

@@ -0,0 +1,310 @@
+# Worker 控制面会话与运行态接收设计
+
+## 1. 目标
+
+实现 `WorkerControlPlane` 的第一个端到端交付单元，使 Controller 能通过 gRPC：
+
+1. 注册 Gateway Worker 并签发可过期、可替换的 Session。
+2. 校验 Worker 对已发布 Snapshot 的正向或负向 ACK。
+3. 接收完整稀疏 Runtime 报告，并把空报告作为心跳。
+4. 在多个 Controller 副本之间通过 Redis 共享 Session、Snapshot 元数据和报告
+   序号栅栏。
+
+本次实现 `RegisterWorker`、`AcknowledgeSnapshot` 和 `ReportRuntime` 三个 RPC。
+`WatchSnapshots` 与 `ReportOutcomes` 保留已发布的 protobuf 契约，但明确返回
+`Unimplemented`，后续交付单元再实现 Snapshot payload/stream、Gateway 客户端和
+Outcome 去重。
+
+## 2. 当前基础与约束
+
+仓库已经具备以下基础：
+
+- `controlplane.proto` 已定义 Worker 注册、Snapshot、ACK、Outcome 和 Runtime。
+- `workerruntime` 已定义 Session、完整稀疏报告和内存参考实现。
+- `redisactivity` 已原子维护 Worker Session、报告序号、报告 TTL 和 ownership
+  fence。
+- Gateway Snapshot Store 已能生成与当前本地快照一致的 Runtime 报告。
+- Kubernetes 清单已预留 Controller `8443` 控制面端口。
+
+现有 `SessionWriter.ReplaceSession` 只能保存已经 ACK 的 Session，不能表达注册后、
+首次 ACK 前的状态；现有 `ErrStaleReport` 同时表示报告序号落后和 Snapshot 不匹配，
+不足以给 Worker 返回准确恢复指令。本次必须修正这两个领域边界，而不是只在 gRPC
+Handler 中增加特殊分支。
+
+必须保持以下不变量：
+
+- Gateway 请求热路径不访问 Redis、PostgreSQL 或 gRPC。
+- Session、Snapshot 元数据和 Runtime 只进入 Redis 或节点内存，不进入 PostgreSQL。
+- Worker 自报的 Session、版本、epoch 和 checksum 不能直接成为权威状态。
+- Session ID、证书身份、Proxy 地址和 Client 信息不得成为 Prometheus 标签。
+
+## 3. 组件边界
+
+### 3.1 生成契约
+
+从 `api/proto/controlplane/v1/controlplane.proto` 生成并提交：
+
+- `gen/controlplane/v1/controlplane.pb.go`
+- `gen/controlplane/v1/controlplane_grpc.pb.go`
+
+`go.mod` 直接固定 `google.golang.org/grpc` 与 `google.golang.org/protobuf`，并用 Go
+tool 依赖固定 `protoc-gen-go` 和 `protoc-gen-go-grpc`。生成脚本必须可重复执行，CI
+验证 descriptor 编译和已提交生成文件没有漂移。
+
+### 3.2 公共应用服务
+
+新增 `internal/controller/worker`，向传输层公开以下应用接口：
+
+```go
+type Service interface {
+	Register(context.Context, RegisterCommand) (Registration, error)
+	Acknowledge(context.Context, SnapshotAcknowledgement) error
+	ReportRuntime(context.Context, workerruntime.Report) (RuntimeDecision, error)
+}
+```
+
+命令和结果不引用 protobuf 类型。gRPC DTO 映射、状态码映射和证书身份校验留在
+传输适配层，领域服务可以在不启动网络的情况下测试。
+
+服务依赖以下公共端口：
+
+```go
+type ControlStore interface {
+	CurrentOwnershipEpoch(context.Context) (uint64, error)
+	OpenSession(context.Context, workerruntime.Session, time.Duration) error
+	RecordIssuedSnapshot(context.Context, workerruntime.SnapshotReference, time.Duration) error
+	AcknowledgeSnapshot(context.Context, workerruntime.SnapshotAcknowledgement, time.Duration) error
+	ReplaceRuntime(context.Context, workerruntime.Report, time.Duration) error
+}
+```
+
+`RecordIssuedSnapshot` 本轮用于契约和集成测试，并作为下一轮 Snapshot Publisher 的
+稳定接入点。Controller 启动不会伪造已发布 Snapshot。
+
+### 3.3 Redis 权威存储
+
+`redisactivity.Adapter` 实现同一 `ControlStore`。新增的 Session 与 Snapshot 元数据
+继续使用 `{activity}` hash tag，与当前 ownership 和 runtime key 位于同一 Redis
+Cluster slot。
+
+每个 Worker 只保留当前已发布 SnapshotReference：
+
+- `worker_id`
+- `version`
+- `ownership_epoch`
+- `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 有以下状态：
+
+```text
+[不存在/过期]
+      |
+      | RegisterWorker
+      v
+[已注册，ACK=0]
+      |
+      | 有效正向 ACK
+      v
+[已 ACK，可接收 Runtime]
+      |
+      | 空或非空 Runtime
+      +--------------------> [续期]
+      |
+      | 对新 Snapshot 的负向 ACK
+      v
+[保留旧 ACK，Runtime 已禁用]
+      |
+      | 后续有效正向 ACK
+      +--------------------> [已 ACK，可接收 Runtime]
+      |
+      | 新 instance 注册 / TTL 过期
+      v
+[失效]
+```
+
+规则如下：
+
+1. 每次成功注册都生成新的 128-bit 加密随机 Session ID。
+2. 同一 `worker_id` 再注册会替换旧 Session，并删除旧 Runtime 报告。
+3. 注册后的 `acked_snapshot_version`、`acked_ownership_epoch` 和
+   `acked_checksum` 均为零值，`runtime_enabled=false`。
+4. Runtime 只有在 Session 已完成正向 ACK 后才可接受。
+5. 空 Runtime 报告表示完整稀疏计数全部为零，同时承担心跳并续期 Session。
+6. Session 到期后，旧实例的 ACK 和 Runtime 均失败；使用该报告计算容量时保持
+   fail-closed。
+
+`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；禁止空键和首尾空白。`labels` 在 protobuf 契约中是 map，重复 wire key
+在进入 Service 前已按 protobuf map 语义归一化为最后一值；Service 只验证
+解码后的唯一键集。
+
+## 5. RPC 行为
+
+### 5.1 RegisterWorker
+
+处理顺序：
+
+1. 校验消息大小、协议版本、标识与标签边界。
+2. 校验 mTLS Worker 身份与请求中的 `worker_id` 一致。
+3. 从 Redis 读取或原子初始化全局 ownership epoch，最小值为 `1`。
+4. 生成新 Session ID，并以未 ACK 状态替换当前 Worker Session。
+5. 返回 Session、ownership epoch、heartbeat interval 和 max stale age。
+
+同一实例重复注册也签发新 Session，保证网络重试不会让两个并行连接共享写权限。
+
+### 5.2 AcknowledgeSnapshot
+
+ACK 操作在 Redis Lua 的一个原子边界内完成：
+
+1. Session 必须存在、未过期，并匹配 worker/session。
+2. 先按 tuple 与 Session 已 ACK 上界比较，再与当前已发布
+   SnapshotReference 比较。落后 tuple 是 stale ACK；超前 tuple 或同 tuple
+   不同 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，设置 `runtime_enabled=false`，也不持久化自由文本错误；
+   下一轮 Snapshot Stream 据此继续发送完整 Snapshot。只有后续正向 ACK
+   才把 `runtime_enabled` 重新设为 true，因此负向 ACK 后延迟到达的旧 Runtime
+   不能重建已清除的报告与 sequence fence。
+5. 旧版本、错误 checksum、超前版本或被替换 Session 均不修改状态。
+
+`error_code` 只接受有界枚举风格字符串；`error_message` 只做长度校验，不写日志或
+持久化，避免敏感信息进入控制面状态。
+
+### 5.3 ReportRuntime
+
+处理顺序：
+
+1. 校验 Session、报告序号、时间戳、计数非负、Proxy ID 唯一和批次上限。
+2. Session 必须 `runtime_enabled=true`，且 Snapshot version 与 ownership epoch 必须
+   精确等于 Session 已 ACK 上界。
+3. 相同 sequence 和相同规范化内容是幂等重放，但仍必须续期 Session
+   与报告 TTL；较小 sequence 拒绝；相同 sequence 不同内容判定冲突。
+4. 成功报告完整替换该 Worker 的稀疏 Runtime，并续期 Session 与报告 TTL。
+5. 返回 Controller 当前 ownership epoch；本轮 `revoke_proxy_ids` 为空。
+
+需要把错误语义拆开：
+
+- `ErrSnapshotMismatch`：报告与 ACK 上界不一致，gRPC 返回成功响应且
+  `require_full_snapshot=true`，不写入报告。
+- `ErrStaleReport`：sequence 倒退，映射 `Aborted`。
+- `ErrConflictingReport`：相同 sequence 内容不同，映射 `AlreadyExists`。
+- `ErrStaleSession`：Session 被替换或过期，映射 `FailedPrecondition`。
+- Redis 或内部依赖错误映射 `Unavailable`，不得泄露后端错误文本。
+
+## 6. gRPC Listener 与安全
+
+配置新增独立的 `controlPlane`：
+
+```yaml
+controlPlane:
+  enabled: false
+  listen: 127.0.0.1:8443
+  protocolVersion: 1
+  heartbeatInterval: 10s
+  sessionTTL: 35s
+  maxStaleAge: 30s
+  maxMessageBytes: 4194304
+  maxRuntimeCounters: 100000
+  tls:
+    mode: disabled
+```
+
+验证规则：
+
+- 启用时必须有合法监听地址、正数限制和 `sessionTTL >= 3 * heartbeatInterval`。
+- `maxStaleAge` 不小于 heartbeat interval。
+- `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：
+
+```text
+spiffe://TRUST_DOMAIN/ENVIRONMENT/worker/WORKER_ID
+```
+
+请求中的 `worker_id` 必须与证书 URI SAN 完全一致。Session ID 不作为 TLS 身份，
+也不写日志。gRPC Server 配置接收/发送消息上限、并发 Stream 上限和 keepalive
+enforcement；停机先停止接收新 RPC，再有界 `GracefulStop`，超时后 `Stop`。
+
+Controller bootstrap 只在 `controlPlane.enabled=true` 时构造并启动 gRPC Server，
+并将其加入现有 lifecycle Group。控制面启用时 Redis 是必需依赖；其就绪状态纳入
+Controller readiness。默认配置保持关闭，避免当前部署清单把未配置证书的 `8443`
+错误暴露为可运行能力。
+
+## 7. 错误与资源边界
+
+- 单消息最大值默认 4 MiB，Runtime counter 默认最多 100,000 条。
+- Proxy ID 使用与 Worker ID 相同的字符集和 128 字节上限。
+- Snapshot checksum 必须是原始 SHA-256 的 32 字节值，不接受十六进制文本或其他
+  长度。
+- ACK `error_code` 为空或匹配 `[A-Z][A-Z0-9_]{0,63}`；`error_message` 最长
+  512 字节，只做校验和丢弃。
+- Counter 规范化排序后计算摘要，禁止重复 Proxy ID。
+- Redis 脚本只处理有界数组，不执行全库扫描。
+- 所有 gRPC 错误返回稳定 code 和低敏感度 message，不返回 Redis key、Session ID、
+  Proxy 地址、证书内容或内部堆栈。
+- 不增加无界 goroutine、无界 channel 或每请求日志。
+
+## 8. 测试策略
+
+测试只通过已批准的公共 seam：
+
+1. **`worker.Service` 单元测试**：注册替换、协议不兼容、负向 ACK、ACK 幂等/倒退/
+   checksum 错误、Runtime 心跳、Snapshot mismatch 恢复指令和存储失败。
+2. **`workerruntime.ControlStore` 公共契约**：内存参考实现与 Redis Adapter 运行同一
+   契约，覆盖 Session TTL、ACK 原子性、报告序号和跨实例 fence。
+3. **gRPC bufconn 测试**：使用生成 Client 调用三个 RPC，验证 DTO、状态码、批次
+   限制以及两个未实现 RPC。
+4. **TLS 测试**：运行时生成测试 CA/Server/Worker 证书，验证正确 SPIFFE 身份、
+   worker_id 不匹配、缺失客户端证书和回环明文规则。
+5. **Controller bootstrap 测试**：临时回环端口启动、Readiness、联动关闭和 Redis
+   不可用失败路径。
+6. **Redis 8.2 集成测试**：通过现有 `test-redis.ps1` 验证多 Controller 共享状态、
+   旧 Session 隔离、TTL 过期和 ACK/Runtime 原子失败不留部分写入。
+
+每个测试命令最长 60 秒。实现采用纵向 TDD：先写一个公共行为测试并确认失败，
+再实现最小生产代码使其通过，然后进入下一行为。
+
+## 9. 验收标准
+
+1. 三个 RPC 可由生成的 gRPC Client 真实调用，并通过 Redis 共享状态。
+2. 注册后未 ACK 的 Session 不能写 Runtime；有效 ACK 后空报告可续期。
+3. 新实例注册后，旧实例的 ACK 与 Runtime 都被拒绝。
+4. Snapshot 元数据与 Session ACK 在 Redis 原子校验，不信任 Worker 自报。
+5. Runtime 序号倒退、冲突、Snapshot mismatch 和存储故障具有不同恢复语义。
+6. 非回环明文监听配置被拒绝，mTLS Worker 身份与请求 ID 绑定。
+7. `WatchSnapshots`、`ReportOutcomes` 明确返回 `Unimplemented`，文档不把本交付单元
+   描述为完整 Worker 控制面。
+8. `go test ./...`、`go vet ./...`、`go build ./...`、protobuf 生成漂移检查和 Redis
+   fixture 全部通过。
+9. Gateway 包及请求热路径不新增 Redis、PostgreSQL 或 gRPC Client 依赖。
+
+## 10. 非目标
+
+- 不实现 Snapshot payload 构建、Delta、WatchSnapshots Stream 或 Gateway 客户端。
+- 不实现 Outcome 批次去重、健康 reducer 或 CheckerControlPlane。
+- 不实现 Worker 维度 revoke/drain 索引；本轮 `revoke_proxy_ids` 保持为空。
+- 不把 Session、ACK、Runtime 或 Snapshot 元数据写入 PostgreSQL。
+- 不宣称 Gateway 进程、完整多副本控制面或 100,000 QPS 已完成。