实现 client-go Pod backend

docs/design-principles.md

@@ -21,18 +21,20 @@ runs-on: [self-hosted, vm]
 
 ## 一个 job，一个环境
 
-Controller 根据 Gitea `workflow_job` webhook 创建执行环境。每个 Pod 或 VM 注册一个
-ephemeral runner，只执行一个 job；任务结束后注销 runner，并删除计算环境及其全部
-本地状态。
+Controller 通过 Gitea RunnerService 原子领取具体 task，再把版本化 assignment 交给
+一个一次性 Pod 或 VM。executor 直接执行已经领取的 task，不再注册临时 runner 去
+二次竞争任务；任务结束并回报 Gitea 后删除计算环境及其全部本地状态。
 
 `job_id` 仅用于消息去重、状态追踪、实例关联和失败清理，不进入 workload 身份，也
 不参与资源授权。
 
-Gitea 不保证由某次 `queued` webhook 创建的 runner 一定领取该 webhook 对应的 job。
-因此创建环境时只赋予无业务权限的启动身份。runner 实际领取任务后，controller 根据
-`in_progress` webhook 返回的 `runner_name` 和真实 job 名称绑定业务身份；环境中的
-job-start hook 必须等目标 SVID 可用后才放行 workflow 的第一步。不能依据 queued
-事件提前赋予任务权限。
+assignment ID 只用于消息去重、状态追踪、实例关联和失败清理，不进入 workload 身份，
+也不参与资源授权。worker 通过 assignment ID 从 Kubernetes labels 或 OpenSandbox
+metadata 恢复 executor；JetStream 不保存 executor 生命周期状态。
+
+Pod executor 创建后，controller 使用实际 Pod UID 创建幂等 `ClusterStaticEntry`，将
+SPIFFE ID绑定到该 Pod 的 workload selector。executor 必须等目标 SVID 可用后才执行
+workflow 的第一步。
 
 ## 环境只提供运行边界
 
@@ -54,15 +56,15 @@ kind 等工具由 pipeline 按需安装和启动，而不是由 controller 预
 SPIFFE ID 由具有业务意义且稳定的 workflow 上下文派生：
 
 ```text
-spiffe://ddupan.top/ci/<owner>/<repository>/<job-name>
+spiffe://ddupan.top/ci/<owner>/<repository>/<job-key>
 ```
 
 同一种任务在不同运行中使用相同的逻辑 SPIFFE ID；每次运行取得独立、短期的 SVID。
 Pod 与 VM 是可替换的执行实现，因此默认不写入 SPIFFE ID。
 
-job 名称必须经过确定性的路径规范化。规范化结果必须保留仓库边界，并在发生冲突时
-拒绝创建环境，不能静默地让两个任务共享身份。同一仓库内需要不同权限的任务应使用
-不同的 job 名称；workflow 文件只是编排载体，不进入权限身份。
+job key 必须满足 `[A-Za-z_][A-Za-z0-9_-]*`，展示名称 `name` 不参与身份计算。同一
+仓库内需要不同权限的任务应使用不同的 job key；workflow 文件只是编排载体，不进入
+权限身份。
 
 ## Self-service 与授权边界
 
@@ -86,3 +88,10 @@ OpenBao 或其他资源的特殊权限。资源所有者在资源端按照有意
 
 仓库中的 `jwt-broker` 是早期方案的实验实现，在 Pod/VM 动态执行环境完成迁移后不应
 部署。
+
+## 实现依赖原则
+
+基础设施协议优先使用上游维护的成熟客户端，不在 controller 内重复实现认证、连接、
+资源编码或错误语义。Kubernetes 使用 `client-go`，NATS JetStream 使用 `nats.go`，
+Gitea RunnerService 使用 `actionslib`；自定义代码只保留领域模型、reconcile 规则及
+上游客户端未覆盖的最小适配层。