docs: 定义 v0.1 runtime assembly 四要素

2026-05-29 20:52:22 +08:00
parent 052ca938dd
commit 033c537bc8
9 changed files with 250 additions and 1 deletions
@@ -53,6 +53,7 @@ AgentRun 是面向 UniDesk 与 HWLAB 的共享 Agent 执行基础设施。本仓
 - `docs/reference/spec-v01-cicd.md`：v0.1 分支、source worktree、namespace、GitOps、registry、CI/CD 和发布验收规格。
 - `docs/reference/spec-v01-postgres.md`：v0.1 Postgres durable store、schema migration 和 SecretRef 规格。
 - `docs/reference/spec-v01-secret-distribution.md`：v0.1 Code Agent provider credential 和运行时 Secret 分发规格。
+- `docs/reference/spec-v01-runtime-assembly.md`：v0.1 runner/backend 启动前的四要素 RuntimeAssembly 装配模型，覆盖 BackendImageRef、ProfileRef、SessionRef 和 Git-only ResourceBundleRef。
 - `docs/reference/spec-v01-validation.md`：v0.1 两层验证模型，自测试允许 mock，综合联调必须 100% 真实。
 - `docs/reference/spec-v01-agentrun-mgr.md`：v0.1 manager REST API、tenant boundary、runner claim 和 event/status authority。
 - `docs/reference/spec-v01-agentrun-runner.md`：v0.1 短生命周期 runner、claim/poll/report、日志和 failureKind。
@@ -7,6 +7,7 @@
 - 作为 Kubernetes Job 或受控 host process 启动；不作为普通业务客户端直接调用的长驻公共服务。
 - 从 manager register、claim run、续租 lease、poll commands、ack command、append events、patch status。
 - 根据 run 中的 `backendProfile` 和 `executionPolicy.secretScope` 调用 backend adapter。
+- 根据 manager 解析出的 RuntimeAssembly materialize backend image、profile Secret、session 和初始资源；四要素字段权威见 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)，本文只规定 runner 消费边界。
 - 将 backend stdout/stderr、assistant message、tool call、error 和 terminal status 归一化为 manager event。
 - 提供可定位的 job/process identity、logPath、attempt id 和 failureKind。
 - 不直连 Postgres，不扩大 workspace、network、approval 或 secret scope。
@@ -29,6 +30,8 @@ Runner Secret 只能通过 Kubernetes Secret projection、ServiceAccount/RBAC

 Kubernetes Job runner 必须把 credential source 与 runtime home 分开：Secret volume 只读挂在 `/var/run/agentrun/secrets/...`，`/home/agentrun` 由 `emptyDir` 提供可写空间，`CODEX_HOME` 指向当前 run/profile 的 writable runtime home，`AGENTRUN_CODEX_SECRET_HOME` 指向当前 `backendProfile` 对应的只读 projection。runner/backend 在启动 provider 前只复制授权文件，不打印内容。`codex` 与 `deepseek` profile 不得共享同一个可写 runtime home，除非它们运行在不同的 per-run Kubernetes Job 且该目录由 Job 独占 emptyDir 提供。

+RuntimeAssembly P0 中 `SessionRef` 可以显式为 `null`，runner 不得把完整 `CODEX_HOME`、Secret projection 或节点 host path 当作 session store。`ResourceBundleRef` P0 收敛为 Git-only；runner 后续实现资源 materialization 时只能 checkout 到允许 workspace 前缀，并记录 commit/tree 摘要，不能把用户上传文件或 env dump 混入 Git-only bundle。
+
 Kubernetes Job runner 必须设置有限保留时间。`v0.1` 默认 `ttlSecondsAfterFinished=86400`，用于保留最近完成 Job 的调试窗口，同时避免长期堆积 `Completed` runner Job 污染运行面观察。该 TTL 是 Job manifest 的运行面属性，不是 CI/CD 门禁；需要延长保留时间时必须通过受控 Job render/input 显式覆盖，并在 issue 或 PR 中说明原因。

 ## Runner 生命周期
@@ -26,6 +26,8 @@ redact(value) -> redacted value

 Adapter 输入必须来自 manager 保存的 run/command 和 Kubernetes Secret projection；不得从 CLI 参数、临时环境变量或 Git 文件读取 provider credential 明文。`resolveProfile(profile)` 必须返回 profile、backendKind、protocol、transport、command、requiredSecretKeys 和 isolation policy；不得把 unknown profile 静默映射到默认 `codex`。

+Backend adapter 消费 RuntimeAssembly 中的 `BackendImageRef` 和 `ProfileRef` 结果，但不定义四要素字段；四要素权威见 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)。
+
 `v0.1` 的第一真实 adapter 是 Codex stdio adapter。它必须走 Codex CLI app-server JSON-RPC over stdio；adapter 合同把 Codex 的 thread、turn、notification、tool lifecycle 和 stderr/exit 信息归一化为 AgentRun 标准 events。`codex` 与 `deepseek` 只是该 adapter 的 profile/config/SecretRef 选择，不允许复制两套协议实现。

 ## Backend Profile Registry
@@ -117,6 +117,8 @@ Tekton promotion 可以读取 `deploy/deploy.json` 来 render runtime desired st

 ## Artifact 与镜像身份

+镜像身份同时是 RuntimeAssembly 的 `BackendImageRef` 来源；四要素总模型见 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)。本文只定义 image digest、artifact catalog 和 GitOps promotion 边界，不定义 profile、session 或 resource bundle 字段。
+
 - `v0.1` 镜像 tag 使用完整 40 位 source commitId。
 - Runtime manifest 必须使用 digest pin 作为部署身份；G14 本地 registry 对同一 tag 的默认 HEAD 可能返回 Docker schema1 compatibility digest，Tekton 必须用 `Accept: application/vnd.docker.distribution.manifest.v2+json` 采集 containerd 可直接拉取的 schema2 manifest digest，并在写入 catalog 前按 digest HEAD 验证。
 - Catalog 必须记录 lane、source branch、GitOps branch、source commitId、serviceId、image tag、digest、component identity 和 publish/reuse 状态。
@@ -29,6 +29,7 @@
 - `spec-v01-cicd.md`：版本 lane、GitOps、namespace、registry 和发布验收。
 - `spec-v01-postgres.md`：Postgres durable store、schema migration 和 DB SecretRef。
 - `spec-v01-secret-distribution.md`：Code Agent provider credential、Postgres DSN 和运行时 Secret 分发。
+- `spec-v01-runtime-assembly.md`：runner/backend 启动前的四要素 RuntimeAssembly 装配模型；其他 spec 只交叉引用，不重复定义四要素字段。
 - `spec-v01-validation.md`：两层验证模型、自测试和综合联调验收。
 - `spec-v01-agentrun-mgr.md`：manager REST API、tenant boundary、runner claim、event/status authority。
 - `spec-v01-agentrun-runner.md`：短生命周期 runner、claim/poll/report、日志和 failureKind。
@@ -70,7 +71,7 @@
 ## 验收标准

 - `AGENTS.md` 索引本文和其他 `spec-v01-*` 规格。
- `docs/reference/` 中存在 `spec-v01-documentation-governance.md`、`spec-v01-services.md`、`spec-v01-cicd.md`、`spec-v01-postgres.md`、`spec-v01-secret-distribution.md`、`spec-v01-validation.md`、`spec-v01-agentrun-mgr.md`、`spec-v01-agentrun-runner.md`、`spec-v01-backend-adapter.md`、`spec-v01-backend-codex.md`、`spec-v01-cli.md` 和 `spec-v01-scheduler.md`。
+- `docs/reference/` 中存在 `spec-v01-documentation-governance.md`、`spec-v01-services.md`、`spec-v01-cicd.md`、`spec-v01-postgres.md`、`spec-v01-secret-distribution.md`、`spec-v01-runtime-assembly.md`、`spec-v01-validation.md`、`spec-v01-agentrun-mgr.md`、`spec-v01-agentrun-runner.md`、`spec-v01-backend-adapter.md`、`spec-v01-backend-codex.md`、`spec-v01-cli.md` 和 `spec-v01-scheduler.md`。
 - `AGENTS.md` 和 `docs/reference/` 不得把旧 `agentrun_dev`、`agentrun_prod`、`G14:/root/agentrun` 或 `/root/agentrun` 写成当前 source worktree、namespace、发布目标或验收目标；只允许在废弃说明和历史背景中提及。
 - `docs/` 根目录不新增临时 Markdown 报告或 JSON dump。
 - 仓库根目录不存在 `TEST.md`；测试场景维护在对应 `spec-v01-*.md` 的“测试规格”小节。
@@ -0,0 +1,229 @@
+# v0.1 Runtime Assembly 规格
+
+本文定义 AgentRun `v0.1` runner Job 启动前的四要素装配模型。`RuntimeAssembly` 是 manager 侧把 run intent 转换成可执行 runner/backend runtime 的权威视图；它只表达引用、hash、路径、权限、生命周期和脱敏策略，不携带 Secret value 或大文件正文。
+
+## 设计目标
+
+- 把 backend 镜像、provider profile、会话持久化和初始资源注入收敛为四个一等要素。
+- 避免 runner 从隐式环境、host path、默认 home、可变 tag 或用户 payload 猜测运行时输入。
+- 让 CI/CD、Secret、session、workspace 和 resource 注入各自有边界，但统一进入同一个装配计划。
+- 把 identity、network、observability、GC、failureKind、provenance 等横切能力归并为四要素上的 policy、metadata、status 或 lifecycle 子项，不扩成并列的一等对象。
+
+## 四要素模型
+
+`RuntimeAssembly` 的一等要素固定为：
+
+| 要素 | 职责 | v0.1 P0 边界 | 权威/引用 |
+| --- | --- | --- | --- |
+| `BackendImageRef` | 决定用什么 backend runtime image 和 command 能力。 | 使用 CI/CD 产出的 digest-pinned image；当前可复用 agentrun runner image，后续可拆独立 backend image。 | [spec-v01-cicd.md](spec-v01-cicd.md) |
+| `ProfileRef` | 决定 provider/profile 配置和 API KEY SecretRef。 | `codex`、`deepseek` 使用 profile-scoped Kubernetes SecretRef；Secret value 不进 run payload。 | [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md) |
+| `SessionRef` | 决定是否恢复或保存 backend 会话状态。 | P0 可以为 `null`；只定义边界，不把完整 `CODEX_HOME` 持久化。 | 本文 |
+| `ResourceBundleRef` | 决定 backend 启动前 materialize 哪份代码和非敏感 repo 文件。 | P0 收敛为 Git-only，由 Git URL、full commit id 和 checkout policy 决定内容身份。 | 本文 |
+
+`executionPolicy` 和 `observabilityPolicy` 是装配规则，不是新的 runtime material。它们可以约束四要素如何被装配、观察和清理，但不得替代四要素本身。
+
+最小形态：
+
+```json
+{
+  "backendImageRef": {},
+  "profileRef": {},
+  "sessionRef": null,
+  "resourceBundleRef": {},
+  "executionPolicy": {},
+  "observabilityPolicy": {}
+}
+```
+
+## 装配顺序
+
+Manager 创建或触发 runner Job 前必须按固定顺序解析装配计划：
+
+1. 根据 run 的 `backendProfile` 解析 `backendKind` 和 `ProfileRef`。
+2. 根据 `backendKind` 和 lane catalog 解析 `BackendImageRef`，得到 digest-pinned image。
+3. 根据 run/session intent 解析 `SessionRef`；P0 无持久 session 时显式为 `null`。
+4. 根据 run 的 workspace/resource intent 解析 `ResourceBundleRef`；P0 必须是 Git-only。
+5. 合并 `executionPolicy` 与 allowlist，生成 Kubernetes Job 的 env、volume、init/prepare intent 和 resource limit。
+6. 生成可写 runtime home、workspace 和可选 session mount；Secret projection 始终只读。
+7. runner/backend 启动后把 image digest、profile name、SecretRef 名称/key、session id、resource commit/hash 和 redaction 状态写入 event metadata，但不写入 Secret value。
+
+Runner 不得自行选择不同 image、Secret、PVC、host path 或 Git ref；任何缺失或不匹配都应按对应要素失败，而不是 fallback 到默认值。
+
+## BackendImageRef
+
+`BackendImageRef` 表达 backend runtime 能力和镜像身份。P0 允许 manager 和 runner/backend 共用同一镜像；即使共用，也必须在装配计划中把实际 image digest 作为 backend image identity 记录。
+
+建议字段：
+
+```json
+{
+  "backendKind": "codex-app-server-stdio",
+  "image": "127.0.0.1:5000/agentrun/agentrun-mgr@sha256:...",
+  "sourceCommit": "<40-char source commit>",
+  "command": ["bun", "src/runner/main.ts"],
+  "backendCommand": ["codex", "app-server", "--listen", "stdio://"],
+  "resourceProfile": { "cpu": "2", "memory": "4Gi" },
+  "provenance": { "catalog": "deploy/artifact-catalog.v01.json" }
+}
+```
+
+规则：
+
+- image 必须来自 Tekton artifact catalog 或 manager allowlist；客户端 run payload 不得直接提供任意 image。
+- 正式 runtime manifest 必须使用 digest pin，不以 mutable tag 作为执行身份。
+- 镜像只表达 runtime 能力，不包含 API KEY、profile config、session 文件或用户 code。
+- image pull、digest 缺失或 capability 不匹配应归类为 image/infra failure，不得被记录为 provider auth failure。
+
+## ProfileRef
+
+`ProfileRef` 表达 provider/profile 配置和 credential 边界。P0 中 `codex` 与 `deepseek` 都是 `codex-app-server-stdio` backend kind 的 profile/config/SecretRef 选择。
+
+建议字段：
+
+```json
+{
+  "profile": "deepseek",
+  "backendKind": "codex-app-server-stdio",
+  "secretRefs": [
+    { "name": "agentrun-v01-provider-deepseek", "keys": ["auth.json", "config.toml"] }
+  ],
+  "runtimeHome": "/home/agentrun/.codex-deepseek",
+  "redactionPolicy": "provider-credential-v1"
+}
+```
+
+规则：
+
+- API KEY、Codex `auth.json`、Codex `config.toml` 和 provider token 只通过 SecretRef 注入。
+- 非敏感 provider config 可以保存在 profile registry、ConfigMap 或 Postgres capability 中；credential value 不得进入 ConfigMap。
+- Secret projection 是只读 credential source；需要 writable home 的 backend 必须复制到 per-run/profile runtime home。
+- profile 缺失或 SecretRef 不匹配必须 `secret-unavailable`；`deepseek` 不得 fallback 到 `codex`。
+- network、proxy、NO_PROXY、rate limit 和 provider readiness 默认归并到 `ProfileRef` 的 policy/status 子项。
+
+## SessionRef
+
+`SessionRef` 表达可恢复的 backend 会话状态，不等同于 Postgres durable facts。Postgres 保存 run、command、event、terminal status、lease 和 session metadata；backend session 文件应保存到 PVC 或后续对象存储。
+
+P0 允许无持久 session：
+
+```json
+{
+  "sessionRef": null,
+  "persistence": "none"
+}
+```
+
+后续建议字段：
+
+```json
+{
+  "sessionId": "sess_...",
+  "tenantId": "unidesk",
+  "projectId": "pikasTech/unidesk",
+  "backendKind": "codex-app-server-stdio",
+  "backendProfile": "codex",
+  "pvcRef": { "namespace": "agentrun-v01", "name": "agentrun-session-sess-..." },
+  "schemaVersion": "codex-stdio-session-v1",
+  "retentionPolicy": "debug-short"
+}
+```
+
+规则：
+
+- `SessionRef` 不保存 API KEY；每次 run 的 credential 仍从 `ProfileRef` 重新投影。
+- 不直接持久化完整 `CODEX_HOME`，因为该目录可能混合 credential、config、session/cache。
+- session 文件、workspace、profile credential 必须是不同目录或 volume。
+- local-path/RWO PVC 会限制恢复节点；跨节点恢复需要 RWX 存储或对象存储，必须在后续 spec 中明确。
+- session 挂载失败、版本不兼容或 restore 失败应归类为 session failure，不得归为 provider failure。
+
+## ResourceBundleRef
+
+`ResourceBundleRef` 表达 backend 启动前注入哪份代码和非敏感 repo 文件。P0 收敛为 Git-only，不支持上传文件、对象存储 artifact、inline env 或任意 ConfigMap/Secret 文件袋。
+
+P0 字段：
+
+```json
+{
+  "type": "git",
+  "repoUrl": "git@github.com:pikasTech/unidesk.git",
+  "commitId": "<full commit sha>",
+  "subdir": ".",
+  "checkoutPolicy": {
+    "submodules": false,
+    "lfs": false,
+    "sparsePaths": []
+  },
+  "credentialRef": null,
+  "materializedTreeHash": null
+}
+```
+
+规则：
+
+- 内容身份由 `repoUrl + commitId + subdir + sparsePaths` 决定；commit id 必须是不可变 full commit sha。
+- `credentialRef` 只用于拉取私有仓库，不参与内容身份，也不得暴露给 backend。
+- `submodules` 和 `lfs` 默认 false；启用时必须进入验收和凭据边界。
+- checkout 后应记录 `materializedTreeHash` 或等价摘要，确认实际 workspace 与期望 commit/subdir 一致。
+- API KEY、provider token、Codex auth/config 属于 `ProfileRef`，不得放进 Git-only bundle。
+- backend session/cache 属于 `SessionRef`，不得放进 Git-only bundle。
+- 动态用户 env 属于 `executionPolicy` 的 allowlisted overlay，不作为 ResourceBundle 内容身份。
+- 大型外部 artifact、上传文件、对象存储和任意 ConfigMap 文件注入都 deferred；后续必须显式扩展，不得把 P0 Git-only 模型变成万能资源袋。
+
+## 横切能力归并
+
+横切能力必须挂到四要素或 run policy 上：
+
+| 横切能力 | 归并位置 |
+| --- | --- |
+| identity/tenant | run、session、resource 和 profile 的 owner/scope/grant 字段。 |
+| scheduling/resource | `BackendImageRef.resourceProfile` 与 `executionPolicy`。 |
+| network/egress | 主要属于 `ProfileRef`，少量属于 `ResourceBundleRef` fetch policy。 |
+| observability | 四要素 materialization 的 event/status metadata。 |
+| lifecycle/GC | session、resource、run/job 和 image artifact 各自的 retention policy。 |
+| failureKind | 按失败发生在哪个要素归类。 |
+| provenance | image digest、profile config hash、session snapshot version、resource commit/tree hash。 |
+
+## FailureKind 归属
+
+| 失败位置 | 建议 failureKind | 说明 |
+| --- | --- | --- |
+| Backend image pull/capability | `infra-failed` 或后续 `image-unavailable` | 镜像不存在、digest 不可拉取、backendKind 不匹配。 |
+| Profile SecretRef | `secret-unavailable` | Secret 缺失、RBAC 拒绝、缺 `auth.json`/`config.toml`。 |
+| Provider auth/upstream | `provider-auth-failed`、`provider-unavailable` | 已成功 materialize profile，但上游拒绝或不可用。 |
+| Session mount/restore | `infra-failed` 或后续 `session-unavailable` | PVC 不可挂载、schema 不兼容、restore 失败。 |
+| Resource checkout/materialization | `schema-invalid`、`infra-failed` 或后续 `resource-unavailable` | Git URL/commit 非法、checkout 失败、tree hash 不匹配。 |
+
+新增细分 failureKind 前必须同步 manager、runner、backend、CLI、self-test 和 validation spec；P0 可以先用现有 failureKind 并在 event payload 中标明 `assemblyElement`。
+
+## 测试规格
+
+### T1 RuntimeAssembly 字段完整性
+
+阅读本文和 [spec-v01-services.md](spec-v01-services.md)，然后检查 run/runner Job 创建路径是否能明确追溯 `BackendImageRef`、`ProfileRef`、`SessionRef` 和 `ResourceBundleRef`。P0 中尚未实现的 `SessionRef` 和 Git-only `ResourceBundleRef` 必须显式为 `null` 或 deferred 状态，而不是由 runner 隐式猜测。
+
+### T2 BackendImageRef digest 固定
+
+阅读本文和 [spec-v01-cicd.md](spec-v01-cicd.md)，然后检查 Tekton artifact catalog、GitOps runtime manifest 和实际 Deployment/Job image，确认 runner/backend 使用 digest-pinned image，并能追溯 source commit。
+
+### T3 ProfileRef Secret 隔离
+
+阅读本文、[spec-v01-secret-distribution.md](spec-v01-secret-distribution.md) 和 [spec-v01-backend-codex.md](spec-v01-backend-codex.md)，然后分别执行 `backendProfile=codex` 与 `backendProfile=deepseek` 的真实 runner Job。确认当前 run 只挂载匹配 profile 的 SecretRef，runtime home 独立，缺失 profile SecretRef 不 fallback。
+
+### T4 SessionRef 与 credential 分离
+
+阅读本文，然后在引入 session 持久化前确认 P0 runner Job 不把完整 `CODEX_HOME` 持久化到 PVC 或 hostPath。后续实现 session PVC 时，必须证明 session 目录不包含 API KEY、Codex auth/config 或 provider token。
+
+### T5 Git-only ResourceBundle
+
+阅读本文，然后用 Git URL、full commit id 和 subdir 创建资源装配计划。确认 checkout 发生在允许 workspace 前缀内，记录 materialized tree 摘要，且 run payload 不携带文件正文、Secret value 或任意 env dump。
+
+## 规格的实现情况
+
+| 规格项 | 状态 | 说明 |
+| --- | --- | --- |
+| RuntimeAssembly 四要素模型 | 已定义 | 本文作为四要素装配模型权威；其他 spec 只引用，不重复定义。 |
+| `BackendImageRef` | 部分实现 | 当前 runner/backend 复用 agentrun 镜像，CI/CD 已使用 digest-pinned runtime manifest；尚未拆独立 backend image registry。 |
+| `ProfileRef` | 已实现/已通过主闭环 | `codex` 与 `deepseek` profile 已通过 Kubernetes SecretRef、writable runtime home 和真实 Codex stdio turn 验证。 |
+| `SessionRef` | 已定义/P0 未持久化 | 当前 v0.1 只持久化 run facts，不持久化 backend session 文件；后续实现 PVC 或对象存储前必须保持 credential 分离。 |
+| Git-only `ResourceBundleRef` | 已定义/待实现 | P0 规格收敛为 Git-only，尚未进入 runner Job materialization。 |
+| 横切能力归并 | 已定义 | identity、network、observability、GC、failure 和 provenance 归并为四要素 policy/metadata/status/lifecycle 子项。 |
@@ -2,6 +2,8 @@

 本文定义 AgentRun `v0.1` 的 Secret 和 Code Agent provider credential 分发边界。真实 Code Agent backend 需要上游模型凭据；Codex stdio profile 测试凭据以 `~/.codex/auth.json` 与 `~/.codex/config.toml` 形态为输入源，通过 Kubernetes Secret 投影进入 runner/backend Pod。这些值不得进入 Git source、GitOps branch、artifact catalog、event、trace、日志或 CLI 输出。

+在 RuntimeAssembly 中，本文只承担 `ProfileRef` 的 SecretRef、projection、rotation 和 redaction 规则；四要素总模型见 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)。
+
 ## 设计目标

 - API Key、Codex auth/config 等 provider credential 只通过 Kubernetes SecretRef 分发到需要它的 manager、runner 或 backend adapter。
@@ -12,6 +12,7 @@ AgentRun 是面向 UniDesk 与 HWLAB 的共享 Code Agent 执行基础设施。`
 - `agentrun-runner` 是短生命周期 per-run 或 per-attempt 执行者，必须从 manager claim run，并把 event、heartbeat 和 terminal status 写回 manager。
 - Backend adapter 隐藏具体 Agent 工具协议，`v0.1` 使用一个真实 Codex stdio backend kind 形成闭环，并在该 kind 下支持 `codex` 与 `deepseek` profile；其他 backend kind 不进入第一波实现。
 - AgentRun CLI 是受控操作入口，负责创建 run、提交 command、轮询 events、手动启动 runner 和查看 backend capability；CLI 不等待完整模型 turn。
+- RuntimeAssembly 是 runner/backend 启动前的四要素装配模型，负责把 backend image、profile、session 和 Git-only resource bundle 统一成受控 Job 输入；四要素权威规格见 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)。
 - Scheduler 是后续自动派发能力；`v0.1` 可以保留规格和状态字段，但不把自动调度作为第一阶段验收目标。

 ## 语言与协议选型
@@ -76,6 +77,7 @@ Runner inbound API 只允许本地或私有诊断，不作为业务客户端入
 | AgentRun CLI | CLI/Job 工具 | 保留，P0 | JSON 输出、短返回、run/command/event/runner/backend 操作入口。 | `spec-v01-cli.md` |
 | Postgres durable store | 稳定外部服务 | 保留，P0 | 使用 `agentrun-v01-postgres` 保存 runs、commands、events、runners、backends、leases 和 migration ledger；不使用 file/sqlite 作为 v0.1 durable store。 | `spec-v01-postgres.md` |
 | Secret distribution | 系统能力 | 保留，P0 | Provider credential 只通过 Kubernetes SecretRef、ServiceAccount/RBAC 和 runner env/file projection 分发；Codex 测试凭据使用 `~/.codex/auth.json` 与 `~/.codex/config.toml` 生成 Secret projection；source、GitOps、logs 和 events 不保存明文。 | `spec-v01-secret-distribution.md` |
+| RuntimeAssembly | 系统能力 | 保留，P0 规格 | runner/backend 启动前的四要素装配模型：`BackendImageRef`、`ProfileRef`、`SessionRef` 和 Git-only `ResourceBundleRef`；P0 先定义模型，ProfileRef 已实现，SessionRef/ResourceBundleRef 按 deferred 子项推进。 | `spec-v01-runtime-assembly.md` |
 | Tenant policy boundary | Run schema 合同 | 保留，P0 | 作为 `Run` 的必填字段和最小校验存在，不做独立 policy engine；tenant 的业务授权仍由 UniDesk/HWLAB 判定。 | 并入 `spec-v01-agentrun-mgr.md` |
 | Observability | 最小事件/日志合同 | 保留，P1 子项 | 作为 manager/runner 的 event、terminal status、failureKind、logPath 和 redaction 最小合同，不拆独立观测系统。 | 并入 `spec-v01-agentrun-mgr.md`、`spec-v01-agentrun-runner.md` |
 | `agentrun-scheduler` | 长驻调度器 | Deferred | M1-M3 稳定后再实现自动 pending scan、capacity selection 和 runner Job 创建。 | `spec-v01-scheduler.md` |
@@ -173,6 +175,7 @@ Manager 负责校验、保存和返回这些字段；runner 只能消费已保
 | CI/CD lane 规格 | 已定义 | 见 [spec-v01-cicd.md](spec-v01-cicd.md)。 |
 | Postgres durable store 规格 | 已定义 | 见 [spec-v01-postgres.md](spec-v01-postgres.md)。 |
 | Secret 分发规格 | 已定义 | 见 [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md)。 |
+| RuntimeAssembly 规格 | 已定义 | 见 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)。 |
 | 两层验证规格 | 已定义 | 见 [spec-v01-validation.md](spec-v01-validation.md)。 |
 | `agentrun-mgr` 服务规格 | 已定义 | 见 [spec-v01-agentrun-mgr.md](spec-v01-agentrun-mgr.md)。 |
 | `agentrun-runner` 服务规格 | 已定义 | 见 [spec-v01-agentrun-runner.md](spec-v01-agentrun-runner.md)。 |
@@ -57,6 +57,7 @@
 6. manager 可查询 command state、append-only events、terminal_status 和 redacted logPath/job identity。
 7. 重启 `agentrun-mgr` 后，run、command、events 和 terminal_status 仍可从 Postgres 查询。
 8. 日志、event、CLI 输出和 health 中没有 provider credential、DSN password、token 或 URL credential 明文。
+9. 若变更涉及 RuntimeAssembly，必须能追溯 `BackendImageRef`、`ProfileRef`、`SessionRef` 和 `ResourceBundleRef` 的装配状态；P0 未实现的 session/resource 能力必须显式为 `null` 或 deferred，不能由 runner 隐式猜测。

 ### CLI 交互联调标准

@@ -157,6 +158,10 @@ T7 只定义人工验收的检查面和判定口径。若后续为减少人工

 T8 是涉及 backend profile 变更时的综合联调标准；不涉及 backend profile 的普通发布仍至少执行已有真实主闭环。

+### T9 RuntimeAssembly 四要素验收
+
+阅读本文和 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)，然后检查一次真实 runner Job 或 dry-run manifest，确认 backend image 来自 digest-pinned `BackendImageRef`，provider credential 来自匹配 `ProfileRef` SecretRef，`SessionRef` 在 P0 下没有把完整 `CODEX_HOME` 持久化，`ResourceBundleRef` 若出现则必须是 Git-only 的 repo URL、full commit id 和 checkout policy。任何 Secret value、用户文件正文或 env dump 都不得进入 event、trace、log 或 run payload。
+
 ## 规格的实现情况

 | 规格项 | 状态 | 说明 |
@@ -168,4 +173,5 @@ T8 是涉及 backend profile 变更时的综合联调标准；不涉及 backend
 | RESTful API 交互联调标准 | 已定义 | 必须直连真实 manager HTTP JSON API，验证服务合同和 durable facts。 |
 | 真实主闭环 | 已通过 | 当前 v0.1 已通过真实 Tekton/Argo、Postgres、SecretRef、Kubernetes runner Job、Codex stdio turn、RESTful API 和 CLI 主闭环；每次发布仍需按本文手动复验。 |
 | `deepseek` profile 切换验收 | 已通过主闭环 | 自测试和 CLI smoke 已覆盖 profile registry、Secret render、fake stdio turn、无 fallback 和结构化错误；真实 `agentrun-v01` 已按 T8 完成 `codex -> deepseek -> codex` 切换综合联调。后续涉及 backend profile 的发布仍必须按 T8 复验。 |
+| RuntimeAssembly 四要素验收 | 已定义 | T9 定义 backend image、ProfileRef、SessionRef 和 Git-only ResourceBundleRef 的装配验收；P0 当前主要验证 digest image 与 profile SecretRef，session/resource materialization 后续实现时必须补真实联调。 |
 | mock 作为发布证据 | 不采用 | mock 只能证明自测试通过。 |