docs: 简化 v0.1 runtime assembly 四要素

docs/reference/spec-v01-runtime-assembly.md

@@ -1,229 +1,123 @@
-# v0.1 Runtime Assembly 规格
+# v0.1 Runtime Assembly 最简规格
 
-本文定义 AgentRun `v0.1` runner Job 启动前的四要素装配模型。`RuntimeAssembly` 是 manager 侧把 run intent 转换成可执行 runner/backend runtime 的权威视图；它只表达引用、hash、路径、权限、生命周期和脱敏策略，不携带 Secret value 或大文件正文。
+本文定义 AgentRun `v0.1` runner/backend 启动前的最简四要素装配模型。`RuntimeAssembly` 只回答一个问题：一次 run 到底用哪份 backend 镜像、哪个 profile、哪份 session、哪份代码。其他能力只作为四要素的 policy 或 metadata，不扩展成新的运行时要素。
 
-## 设计目标
+## 最简四要素
 
-- 把 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 子项，不扩成并列的一等对象。
+`v0.1` 只保留四个一等要素：
 
-## 四要素模型
-
-`RuntimeAssembly` 的一等要素固定为：
-
-| 要素 | 职责 | v0.1 P0 边界 | 权威/引用 |
+| 要素 | 最小字段 | v0.1 含义 | 不包含 |
 | --- | --- | --- | --- |
-| `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 决定内容身份。 | 本文 |
+| `BackendImageRef` | `image` | digest-pinned backend/runner 镜像。 | API KEY、profile config、用户代码、session 文件。 |
+| `ProfileRef` | `profile`、`secretRef` | provider profile 和 API KEY/配置 SecretRef。 | backend 镜像、session、repo 文件。 |
+| `SessionRef` | `sessionId` 或 `null` | backend 会话文件持久化引用；P0 可以为 `null`。 | API KEY、完整 `CODEX_HOME`、Git workspace。 |
+| `ResourceBundleRef` | `repoUrl`、`commitId` | 初始代码/文件输入；P0 固定 Git-only。 | 上传文件、对象存储 artifact、inline env、Secret value。 |
 
-`executionPolicy` 和 `observabilityPolicy` 是装配规则，不是新的 runtime material。它们可以约束四要素如何被装配、观察和清理，但不得替代四要素本身。
-
-最小形态：
+P0 最小 JSON 形态：
 
 ```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": []
+  "backendImageRef": {
+    "image": "127.0.0.1:5000/agentrun/agentrun-mgr@sha256:..."
   },
-  "credentialRef": null,
-  "materializedTreeHash": null
+  "profileRef": {
+    "profile": "codex",
+    "secretRef": { "name": "agentrun-v01-provider-codex", "keys": ["auth.json", "config.toml"] }
+  },
+  "sessionRef": null,
+  "resourceBundleRef": {
+    "repoUrl": "git@github.com:pikasTech/unidesk.git",
+    "commitId": "<full commit sha>"
+  }
 }
 ```
 
-规则：
+`executionPolicy`、`observabilityPolicy`、tenant identity、network、GC、failureKind、provenance 和 resource limit 都不是新的要素；它们分别挂在四要素或 run policy 上。
 
-- 内容身份由 `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 模型变成万能资源袋。
+## 四要素边界
 
-## 横切能力归并
+### BackendImageRef
 
-横切能力必须挂到四要素或 run policy 上：
+- `image` 必须是 digest-pinned image。
+- image 来源必须是 CI/CD artifact catalog、GitOps manifest 或 manager allowlist；客户端不能在 run payload 中传任意镜像。
+- v0.1 可以继续使用现有 agentrun runner 镜像，不要求立即拆独立 backend image。
+- 验收时只需要能追溯实际 Deployment/Job image digest 和 source commit。
 
-| 横切能力 | 归并位置 |
-| --- | --- |
-| 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。 |
+### ProfileRef
 
-## FailureKind 归属
+- `profile` 在 v0.1 只允许 `codex` 或 `deepseek`。
+- `secretRef` 只保存 Secret 名称和 key，不保存值。
+- 当前 profile 只能读取当前 profile 的 SecretRef；缺失必须 `secret-unavailable`，不能 fallback 到另一个 profile。
+- profile Secret 只读投影，backend 需要可写目录时复制到 per-run/profile runtime home。
 
-| 失败位置 | 建议 failureKind | 说明 |
+### SessionRef
+
+- P0 允许 `sessionRef=null`，表示不持久化 backend session 文件。
+- 一旦启用 session，必须只保存 backend session/cache，不保存 API KEY、`auth.json`、`config.toml` 或完整 `CODEX_HOME`。
+- session 文件目录必须和 profile credential、Git workspace 分开。
+- v0.1 先定义边界，不要求实现 PVC/session restore。
+
+### ResourceBundleRef
+
+- P0 固定 Git-only，由 `repoUrl + full commitId` 决定内容身份。
+- `commitId` 必须是不可变 full commit sha，不能是 branch、tag 或 `HEAD`。
+- 可选扩展只允许 `subdir`、`sparsePaths`、`submodules=false`、`lfs=false`、`credentialRef`；默认不启用。
+- `credentialRef` 只用于拉取私有 Git repo，不等同于 backend API KEY。
+- 不支持上传文件、对象存储 artifact、任意 ConfigMap 文件袋或 inline env；后续需要时另写版本规格。
+
+## 最简装配顺序
+
+1. Manager 根据 run 解析四要素引用。
+2. Manager 或 runner Job render 只使用解析后的 image、SecretRef、sessionRef 和 Git commit。
+3. Runner materialize profile Secret 到 writable runtime home。
+4. Runner materialize Git-only resource bundle 到 workspace；P0 未实现时必须显式记录为 deferred 或 null，不能猜测 host path。
+5. Runner 启动 backend，并在 event 中记录 image digest、profile、SecretRef 名称/key、sessionRef、repoUrl/commitId 的脱敏摘要。
+
+任何一个要素缺失或不合法，都必须按该要素失败；不得静默 fallback。
+
+## v0.1 验收标准
+
+### A1 BackendImageRef 验收
+
+- 实际 manager Deployment 和 runner Job 使用 digest-pinned image。
+- event、CLI 或诊断输出能看到 image digest 或可追溯到 GitOps/catalog。
+- run payload 不能传任意 image 字符串。
+
+### A2 ProfileRef 验收
+
+- `codex` run 只挂载 `agentrun-v01-provider-codex`。
+- `deepseek` run 只挂载 `agentrun-v01-provider-deepseek`。
+- `codex -> deepseek -> codex` 切换后，`CODEX_HOME`、SecretRef、backend_status 不互相污染。
+- 删除或缺失 `deepseek` SecretRef 时必须 `secret-unavailable`，不能 fallback 到 `codex`。
+- 所有输出不得包含 Secret value、`auth.json` 或 `config.toml` 明文。
+
+### A3 SessionRef 验收
+
+- P0 若未启用 session，run/manifest 必须显式表现为 `sessionRef=null` 或 equivalent deferred 状态。
+- runner Job 不得把完整 `CODEX_HOME`、Secret projection 或 host path 当成 session store。
+- 后续启用 session 前，必须补充真实验收：session 目录不包含 API KEY 或 profile credential。
+
+### A4 ResourceBundleRef 验收
+
+- P0 ResourceBundle 只能是 Git-only：`repoUrl + full commitId`。
+- `commitId` 不是 branch/tag/HEAD。
+- checkout 只能进入允许 workspace 前缀，不能覆盖 `/app`、Secret projection、profile runtime home 或 session 目录。
+- run payload 不携带文件正文、env dump、Secret value 或大型 artifact。
+
+### A5 综合验收
+
+一次真实 runner Job 或 dry-run manifest 必须能同时回答：
+
+1. 用哪一个 image digest。
+2. 用哪一个 profile 和 SecretRef。
+3. 是否使用 session；若不用，必须明确为 `null`/deferred。
+4. 使用哪一个 Git repo 和 full commit；若 P0 尚未 materialize，必须明确为 deferred，不能隐式使用 host path。
+
+## 实现状态
+
+| 要素 | v0.1 状态 | 说明 |
 | --- | --- | --- |
-| 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 子项。 |
+| `BackendImageRef` | 部分实现 | CI/CD 已使用 digest-pinned runtime image；当前 runner/backend 仍复用 agentrun 镜像。 |
+| `ProfileRef` | 已实现/已通过主闭环 | `codex` 与 `deepseek` 已通过 SecretRef、writable runtime home 和真实 stdio turn 验证。 |
+| `SessionRef` | 规格已定义/P0 未实现 | 当前只持久化 run facts，不持久化 backend session 文件。 |
+| `ResourceBundleRef` | 规格已定义/P0 Git-only/待实现 | 已明确最简 Git-only 模型，runner materialization 后续实现。 |

docs/reference/spec-v01-validation.md

@@ -160,7 +160,7 @@ T8 是涉及 backend profile 变更时的综合联调标准；不涉及 backend
 
 ### 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。
+阅读本文和 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)，然后检查一次真实 runner Job 或 dry-run manifest，确认四个问题都有明确答案：用哪一个 digest-pinned image、用哪一个 profile/SecretRef、是否使用 session、使用哪一个 Git repo/full commit。P0 未启用 session 或 Git-only resource materialization 时，必须明确为 `null` 或 deferred，不能由 runner 隐式使用 host path。任何 Secret value、用户文件正文、env dump、branch/tag/HEAD 形式的 resource commit 都不能作为通过证据。
 
 ## 规格的实现情况
 
@@ -173,5 +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 后续实现时必须补真实联调。 |
+| RuntimeAssembly 四要素验收 | 已定义 | T9 收敛为四个最简问题：image digest、profile/SecretRef、session null/deferred、Git-only repo/full commit；session/resource materialization 后续实现时必须补真实联调。 |
 | mock 作为发布证据 | 不采用 | mock 只能证明自测试通过。 |