docs: specify postgres and secret distribution

AGENTS.md

@@ -44,5 +44,7 @@ AgentRun 是面向 UniDesk 与 HWLAB 的共享 Agent 执行基础设施。本仓
 - `docs/reference/spec-v01-documentation-governance.md`：v0.1 文档治理、唯一入口、spec 权威和过程材料承载规则。
 - `docs/reference/spec-v01-services.md`：v0.1 服务总览、保留对象、deferred 对象和单服务规格索引。
 - `docs/reference/spec-v01-cicd.md`：v0.1 分支、workspace、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 API Key 和运行时 Secret 分发规格。
 - `docs/reference/architecture.md`：AgentRun 产品边界、服务架构、MVP 阶段、RESTful API 模型和数据模型。
 - `docs/reference/cli.md`：按 `cli-spec` 固化的 CLI 与服务 API 约束。

docs/reference/architecture.md

@@ -190,8 +190,9 @@ Event 是 append-only，并按 seq 分页：
 
 ## 数据模型方向
 
-第一版实现可以使用紧凑 schema，但不应把所有事实都隐藏在一个 JSON blob 中。稳定方向是：
+`v0.1` 使用 Postgres 作为唯一 durable store；file、sqlite、JSONL 或 Pod 本地目录只能用于临时测试或日志，不作为运行面事实来源。第一版实现可以使用紧凑 schema，但不应把所有事实都隐藏在一个 JSON blob 中。稳定方向是：
 
+- `agentrun_schema_migrations`：migration id、checksum 和 applied timestamp；
 - `agentrun_runs`：run identity、tenant/project/workspace/backend policy、status 和 timestamps；
 - `agentrun_commands`：command type、idempotency key、payload hash、state 和 ack timestamps；
 - `agentrun_events`：按 run 和 seq 索引的 append-only event records；
@@ -199,6 +200,8 @@ Event 是 append-only，并按 seq 分页：
 - `agentrun_backends`：backend profile、capabilities、capacity 和 health；
 - `agentrun_leases`：当前 ownership 和 expiry。
 
+Postgres DSN、provider API Key 和未来 tenant credential 的分发边界见 [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md)；source、GitOps、event、trace、日志和 CLI 输出都不得保存 Secret 明文。
+
 ## 部署方向
 
 AgentRun 从 `v0.1` 开始按版本 lane 滚动，废弃 `dev/prod` 管理口径。`v0.1` 的固定 source workspace 是 `G14:/root/agentrun-v01`，固定 source branch 是 `v0.1`，固定运行目标是 G14 原生 k3s namespace `agentrun-v01`。后续 `v0.2`、`v0.3` 必须拥有自己的 branch、workspace、namespace、GitOps branch、runtime path 和发布验收。

docs/reference/spec-v01-cicd.md

@@ -76,6 +76,7 @@
 - service id、组件类型和是否参与 `v0.1` runtime。
 - replica、resource request/limit、health path、ports、env key、ConfigMap/SecretRef 名称和 key。
 - runtime namespace、ServiceAccount、RBAC intent、PVC intent、NetworkPolicy intent。
+- Postgres 和 Code Agent provider 的 SecretRef 名称、key 名称与 mount/env intent；Secret 值不在 source 或 GitOps 中出现。
 - public/ingress intent 的声明占位；`v0.1` 默认不要求公网入口。
 
 禁止写入 `deploy/deploy.json` 的内容：
@@ -114,6 +115,7 @@ Tekton promotion 可以读取 `deploy/deploy.json` 来 render runtime desired st
 - `argocd/agentrun-v01` AppProject destination 只能包含 `agentrun-v01`。
 - `argocd/agentrun-g14-v01` source 必须指向 `v0.1-gitops:deploy/gitops/g14/runtime-v01`，destination 必须是 `agentrun-v01`。
 - `v0.1` Secret、ServiceAccount、RBAC、PVC、ConfigMap 和 runtime config 必须独立命名或 namespace scope；文档、issue、trace 和 report 只记录 SecretRef 名称与 key，不记录值。
+- `agentrun-mgr` 和 runner Job 只能通过 `spec-v01-secret-distribution.md` 定义的 SecretRef 注入 Postgres DSN 和 Code Agent API Key，不得从 `deploy/deploy.json`、artifact catalog 或 generated manifest 中读取明文。
 - `agentrun_dev` 和 `agentrun_prod` 不得作为 `v0.1` namespace、Argo destination、Pipeline target 或验收目标。
 
 ## 手动和热修边界

docs/reference/spec-v01-documentation-governance.md

@@ -27,6 +27,8 @@
 - `spec-v01-documentation-governance.md`：文档治理和旧口径迁移。
 - `spec-v01-services.md`：服务总览、保留和 deferred 对象。
 - `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 API Key、Postgres DSN 和运行时 Secret 分发。
 - 未来新增单服务规格必须使用 `spec-v01-<service-or-capability>.md`，例如 `spec-v01-agentrun-mgr.md`、`spec-v01-agentrun-runner.md`。
 - `v0.2` 或更高版本的规格不得写入 `spec-v01-*`；只能在对应版本 lane 中创建自己的 `spec-v02-*`、`spec-v03-*`。
 - 每个可实现规格应包含“测试规格”小节；测试编号写在对应 spec 内，不创建或恢复根目录 `TEST.md`。
@@ -48,11 +50,13 @@
 - Runtime namespace：`agentrun-v01`。
 - 发布和验收规格：[spec-v01-cicd.md](spec-v01-cicd.md)。
 - 服务总览规格：[spec-v01-services.md](spec-v01-services.md)。
+- Postgres durable store 规格：[spec-v01-postgres.md](spec-v01-postgres.md)。
+- Secret/API Key 分发规格：[spec-v01-secret-distribution.md](spec-v01-secret-distribution.md)。
 
 ## 验收标准
 
 - `AGENTS.md` 索引本文和其他 `spec-v01-*` 规格。
-- `docs/reference/` 中存在 `spec-v01-documentation-governance.md`、`spec-v01-services.md` 和 `spec-v01-cicd.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`。
 - `AGENTS.md` 和 `docs/reference/` 不得把旧 `agentrun_dev`、`agentrun_prod`、`G14:/root/agentrun` 或 `/root/agentrun` 写成当前工作区、namespace、发布目标或验收目标；只允许在废弃说明和历史背景中提及。
 - `docs/` 根目录不新增临时 Markdown 报告或 JSON dump。
 - 仓库根目录不存在 `TEST.md`；测试场景维护在对应 `spec-v01-*.md` 的“测试规格”小节。

docs/reference/spec-v01-postgres.md

@@ -0,0 +1,79 @@
+# v0.1 Postgres Durable Store 规格
+
+本文定义 AgentRun `v0.1` 的持久化存储规格。`v0.1` 使用 Postgres 作为唯一 durable store；file、sqlite、JSONL 或 Pod 本地目录只能用于临时测试或日志，不作为运行面事实来源。
+
+## 在系统中的职责划分
+
+- 保存 `agentrun-mgr` 的 durable facts：runs、commands、events、runners、backends、leases 和 migration ledger。
+- 为 runner claim、command ack、event append、heartbeat 和 terminal status 提供事务边界。
+- 与 `agentrun-v01` namespace 绑定；不复用未来 `v0.2`、`v0.3` 或旧 dev/prod 数据库。
+- 不向公网开放，不允许普通 runner 直连写入不属于自己的 run facts。
+
+## 固定命名
+
+| 对象 | v0.1 规格 |
+| --- | --- |
+| Runtime namespace | `agentrun-v01` |
+| StatefulSet | `agentrun-v01-postgres` |
+| Service | `agentrun-v01-postgres` |
+| Database | `agentrun_v01` |
+| Runtime user | `agentrun_v01` |
+| Data PVC | `agentrun-v01-postgres-data` |
+| Postgres Secret | `agentrun-v01-postgres` |
+| Manager DB Secret | `agentrun-v01-mgr-db` |
+| Manager env key | `DATABASE_URL` |
+
+Secret 名称和 key 可以在实现时按 Kubernetes 命名限制微调，但必须保持 lane 独立，并在 `deploy/deploy.json` 中只记录 SecretRef 名称和 key，不记录值。
+
+## 数据模型方向
+
+`v0.1` 稳定表方向：
+
+- `agentrun_schema_migrations`：migration id、checksum、appliedAt。
+- `agentrun_runs`：run identity、tenant/project/workspace/backend policy、status 和 timestamps。
+- `agentrun_commands`：command type、idempotency key、payload hash、state 和 ack timestamps。
+- `agentrun_events`：按 run 和 seq 索引的 append-only event records。
+- `agentrun_runners`：registered runner identity、placement、heartbeat 和 capability snapshot。
+- `agentrun_backends`：backend profile、capabilities、capacity 和 health。
+- `agentrun_leases`：run ownership、expiry 和 stale recovery marker。
+
+第一版实现可以把 backend-specific payload 存在 JSONB 字段中，但 run、command、event、runner、backend 和 lease 的主键、状态、时间戳和索引字段必须是一等列，不能把所有事实塞进一个不可查询 JSON blob。
+
+## 访问边界
+
+- `agentrun-mgr` 是数据库写入 authority；业务客户端通过 manager REST API 访问 durable facts。
+- runner 不直接读取或写入 Postgres，除非后续 spec 明确引入受限 DB role；`v0.1` 默认 runner 通过 manager API claim/report。
+- CLI 不直接连 Postgres；CLI 调用 manager REST API。
+- Postgres DSN 只通过 [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md) 定义的 Kubernetes SecretRef 注入 `agentrun-mgr`。
+- 日志、event、CLI 输出和 health 只能展示数据库 readiness、schema version、SecretRef 名称或 redacted DSN，不得打印 DSN 明文。
+
+## Migration 规则
+
+- migration 必须由 source branch 的人写 migration 文件或等价 migration module 定义。
+- CI 可以校验 migration 顺序、checksum 和向前兼容，但不得把 live DB dump 写回 source。
+- 启动时 `agentrun-mgr` 可以执行幂等 migration 或在 migration 缺失时 fail fast；不得静默以空 schema 继续服务。
+- schema migration 记录必须写入 `agentrun_schema_migrations`。
+
+## 测试规格
+
+### T1 Postgres readiness
+
+阅读本文和 [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md)，然后在 `agentrun-v01` namespace 中检查 StatefulSet、Service、PVC 和 SecretRef 名称存在；不得输出 Secret 值。
+
+### T2 Manager DB health
+
+阅读本文，然后访问 `agentrun-mgr` health/readiness，确认返回 Postgres reachable、schema migration ready、database adapter 为 Postgres，并且 DSN 被 redacted。
+
+### T3 Durable facts round-trip
+
+阅读本文和 [spec-v01-services.md](spec-v01-services.md)，然后创建 run、command、event 和 terminal status，重启 `agentrun-mgr` 后确认 facts 仍可通过 manager API 查询。
+
+## 规格的实现情况
+
+| 规格项 | 状态 | 说明 |
+| --- | --- | --- |
+| Postgres durable store 规格 | 已定义 | 本文为 v0.1 存储权威。 |
+| StatefulSet/Service/PVC | 未实现 | 需要后续 GitOps lane 初始化。 |
+| migration ledger | 未实现 | 需要后续代码和 schema migration。 |
+| manager Postgres adapter | 未实现 | 需要后续 `agentrun-mgr` 实现。 |
+| file/sqlite durable store | 不采用 | 只可用于临时本地测试，不作为 v0.1 runtime truth。 |

docs/reference/spec-v01-secret-distribution.md

@@ -0,0 +1,112 @@
+# v0.1 Secret 与 API Key 分发规格
+
+本文定义 AgentRun `v0.1` 的 Secret 和 Code Agent API Key 分发边界。Code Agent 一定需要上游模型 API Key，但这些值不得进入 Git source、GitOps branch、artifact catalog、event、trace、日志或 CLI 输出。
+
+## 设计目标
+
+- API Key 只通过 Kubernetes SecretRef 分发到需要它的 manager、runner 或 backend adapter。
+- `deploy/deploy.json` 只记录 SecretRef 名称、key 名称、mount/env intent 和 secret scope，不记录 Secret 值。
+- `v0.1-gitops` 的 rendered manifests 只能引用 Secret 名称和 key，不包含 Secret data。
+- `agentrun-mgr` 保存 run 的 `executionPolicy.secretScope`，但保存的是 credential source reference，不是 credential value。
+- runner 和 backend adapter 只能消费 manager 已授权的 secret scope，不能枚举 namespace 内所有 Secret。
+
+## Secret 分类
+
+| Secret 类别 | 用途 | 默认消费者 | v0.1 规则 |
+| --- | --- | --- | --- |
+| Postgres DSN | manager 连接 durable store | `agentrun-mgr` | 只通过 `agentrun-v01-mgr-db/DATABASE_URL` 注入。 |
+| Codex/OpenAI-compatible API Key | 真实 Code Agent backend 调上游模型 | runner 或 backend adapter | 只通过 provider profile SecretRef 注入，不写入 run payload。 |
+| Git SSH deploy key | Tekton checkout source/GitOps promotion，Argo 读取 GitOps branch | Tekton、Argo CD | 只存在于 `agentrun-ci` 或 `argocd` Secret；不进入 runtime Pod。 |
+| Registry credential | push/pull private registry | Tekton、runtime imagePullSecret | 只作为 ServiceAccount/imagePullSecret 引用。 |
+| Future tenant credential | tenant 专属工具或外部服务 | runner/backend adapter | 必须先定义 SecretRef 和 secret scope，再允许 run 引用。 |
+
+## 固定命名建议
+
+| 对象 | v0.1 建议 |
+| --- | --- |
+| Manager DB Secret | `agentrun-v01-mgr-db` key `DATABASE_URL` |
+| Provider Secret | `agentrun-v01-provider-codex` key `API_KEY` |
+| Provider config Secret | `agentrun-v01-provider-codex` key `BASE_URL` 或 ConfigMap 中非敏感 base URL |
+| Tekton Git SSH Secret | `agentrun-ci/agentrun-git-ssh` |
+| Argo Git SSH Secret | `argocd/agentrun-git-ssh` |
+| Runtime ServiceAccount | `agentrun-v01-mgr`、`agentrun-v01-runner` |
+
+命名可以在实现时因集群约束调整，但必须满足 lane 独立、用途单一、最小 RBAC 和不跨 `v0.1`/`v0.2` 复用的原则。
+
+## Run secretScope 合同
+
+Run 的 `executionPolicy.secretScope` 只能包含引用，不包含值。示例形态：
+
+```json
+{
+  "providerCredentials": [
+    {
+      "profile": "codex",
+      "secretRef": {
+        "namespace": "agentrun-v01",
+        "name": "agentrun-v01-provider-codex",
+        "key": "API_KEY"
+      }
+    }
+  ],
+  "allowCredentialEcho": false
+}
+```
+
+规则：
+
+- `allowCredentialEcho` 必须固定为 `false`。
+- `secretRef.namespace` 默认只能是 run 所在 lane namespace 或明确批准的 platform namespace。
+- manager 可以保存 `secretRef`，但不得读取 Secret 值后存库。
+- runner/backend adapter 获得 Secret 的方式必须来自 Kubernetes env/file projection 或受限 Secret API 读取；不得通过 run payload、event、CLI 参数或日志传递。
+- SecretRef 不存在或 RBAC 不允许时，run 必须失败为结构化 `failureKind=secret-unavailable` 或等价错误，不得降级成无凭证重试风暴。
+
+## 分发路径
+
+`v0.1` 默认路径：
+
+```text
+deploy/deploy.json
+  -> declares SecretRef names and mount/env intent only
+Tekton promotion
+  -> renders SecretRef references into v0.1-gitops manifests
+Argo CD
+  -> syncs workload references to agentrun-v01
+Kubernetes Secret
+  -> created out-of-band by operator or approved secret-management flow
+runner/backend Pod
+  -> receives API Key via env/file projection
+```
+
+Secret 创建和轮换不由 source branch 自动生成；source branch 只声明需要哪个 SecretRef。后续如果接入 External Secrets、Vault、SealedSecrets 或 SOPS，必须新增或更新本 spec，明确 controller、source of truth、rotation 和 redaction 规则。
+
+## 日志与事件 Redaction
+
+- event、trace、日志、CLI 输出、health 和 diagnostics 不得打印 Secret 值。
+- `Authorization`、`api_key`、`token`、`password`、URL credential、DSN password 必须 redacted。
+- 可以打印 SecretRef 名称、key 名称、credential source、是否存在、是否被挂载、是否通过 readiness 检查。
+- provider auth 失败只能报告 failure kind、HTTP status 分类和 request id；不得打印请求 header 或 body 中的凭据。
+
+## 测试规格
+
+### T1 SecretRef render
+
+阅读本文和 [spec-v01-cicd.md](spec-v01-cicd.md)，然后检查 `deploy/deploy.json` 只包含 SecretRef 名称/key 和 mount/env intent；rendered GitOps manifest 也只包含 SecretRef，不包含 Secret data。
+
+### T2 Runner credential projection
+
+阅读本文，然后启动一个最小 backend runner dry-run，确认 Pod env/file projection 能看到 provider credential，但 event、日志和 CLI 输出只显示 redacted credential source。
+
+### T3 Missing secret failure
+
+阅读本文，然后用一个不存在的 provider SecretRef 创建 run，确认 run 失败为结构化 `secret-unavailable`，不会打印 Secret 值，也不会无限重试。
+
+## 规格的实现情况
+
+| 规格项 | 状态 | 说明 |
+| --- | --- | --- |
+| Secret 分发规格 | 已定义 | 本文为 v0.1 API Key 分发权威。 |
+| Kubernetes SecretRef 注入 | 未实现 | 需要后续 GitOps/runtime 实现。 |
+| provider API Key projection | 未实现 | 需要后续 runner/backend adapter 实现。 |
+| redaction 最小规则 | 已定义 | 需要后续代码实现和测试。 |
+| 外部 secret manager | 未采用 | 如需 Vault/ExternalSecrets/SOPS，后续单独更新规格。 |

docs/reference/spec-v01-services.md

@@ -40,7 +40,8 @@ Runner inbound API 只允许本地或私有诊断，不作为业务客户端入
 | Backend adapter | 执行适配层 | 保留，P0 | 统一 backend capability、event normalization、error mapping 和 credential boundary。 | `spec-v01-backend-adapter.md` |
 | First real backend | 具体 Agent backend | 保留，P0 | `v0.1` 必须至少证明一个真实 Agent backend；默认候选是 Codex。 | `spec-v01-backend-codex.md` |
 | AgentRun CLI | CLI/Job 工具 | 保留，P0 | JSON 输出、短返回、run/command/event/runner/backend 操作入口。 | `spec-v01-cli.md` |
-| Durable store | 数据存储 | 保留，P0 | 保存 runs、commands、events、runners、backends、leases；具体存储可从 file/sqlite/Postgres 起步，但必须有迁移边界。 | `spec-v01-state-store.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 | API Key 只通过 Kubernetes SecretRef、ServiceAccount/RBAC 和 runner env/file projection 分发；source、GitOps、logs 和 events 不保存明文。 | `spec-v01-secret-distribution.md` |
 | Tenant policy boundary | Run schema 合同 | 保留，P0 | 作为 `Run` 的必填字段和最小校验存在，不做独立 policy engine；tenant 的业务授权仍由 UniDesk/HWLAB 判定。 | 并入 `spec-v01-agentrun-mgr.md` |
 | Observability | 最小事件/日志合同 | 保留，P0 子项 | 作为 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` |
@@ -91,7 +92,7 @@ Run create 的最小字段合同：
 | `executionPolicy` | 必填或由 manager 显式写入默认值，至少包含 sandbox、approval、timeout、network 和 secret scope。 |
 | `traceSink` | 字段必须存在；可以为 `null` 或显式 sink，表示标准事件是否需要镜像给 tenant。 |
 
-Manager 负责校验、保存和返回这些字段；runner 只能消费已保存的 run policy，不能自行扩大 workspace、network 或 secret scope。HWLAB live device mutation、UniDesk production deploy、GitHub issue/PR 写入等业务授权仍由 tenant 自己的入口判定，AgentRun 不把这些业务规则内建成通用门禁。
+Manager 负责校验、保存和返回这些字段；runner 只能消费已保存的 run policy，不能自行扩大 workspace、network 或 secret scope。`executionPolicy.secretScope` 只能引用 [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md) 定义的 SecretRef 或 credential source，不能携带 API Key 明文。HWLAB live device mutation、UniDesk production deploy、GitHub issue/PR 写入等业务授权仍由 tenant 自己的入口判定，AgentRun 不把这些业务规则内建成通用门禁。
 
 ## 最小 Observability 合同
 
@@ -136,6 +137,8 @@ Manager 负责校验、保存和返回这些字段；runner 只能消费已保
 | `v0.1` 服务总体规格 | 已定义 | 本文定义服务总览和取舍表。 |
 | 文档治理规格 | 已定义 | 见 [spec-v01-documentation-governance.md](spec-v01-documentation-governance.md)。 |
 | 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)。 |
 | `agentrun-mgr` 实现 | 未实现 | 需后续单服务 spec 和代码实现。 |
 | `agentrun-runner` 实现 | 未实现 | 需后续单服务 spec 和代码实现。 |
 | 第一真实 backend | 未实现 | 默认候选 Codex，需后续 backend spec。 |