pikasTech-agentrun/docs/reference/spec-v01-postgres.md

# 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、runner_jobs、sessions、backends、leases、Queue facts 和 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_runner_jobs`：手动 runner Job 的 idempotency key、payload hash、attempt/job identity 和创建响应。
- `agentrun_sessions`：SessionRef 到 backend thread/cache identity、execution projection、active run/command、terminal/unread 水位的映射，不保存 credential 文件或 Secret 值。
- `agentrun_session_read_cursors`：按 reader 记录 Session 已读 version，用于 CLI 默认只看 running/unread。
- `agentrun_queue_tasks`：AgentRun Queue task identity、queue/lane、tenant/project、priority、state、backendProfile、workspace/resource 引用、可选 `sessionRef` 和 version；携带 `sessionRef` 的 task dispatch 后必须把 `sessionPath` 写回 Queue 记录。
- `agentrun_queue_attempts`：task attempt identity、runId、commandId、runnerJobId、sessionId、state、failureKind、retry index 和 timestamps。
- `agentrun_task_summaries` / `agentrun_attempt_summaries`：Queue 列表、详情和 commander 使用的轻量摘要；不能从 Core trace 反推 overview。
- `agentrun_queue_stats`：按 queue/lane/state/backendProfile 聚合的统计水位。
- `agentrun_queue_read_cursors`：按 user/agent/client 记录 Queue 已读水位。
- `agentrun_queue_judge_runs`：judge 请求、结果、failureKind、重试建议和 attempt 关联。
- `agentrun_task_references`：任务的显式 issue/PR/repo/commit/doc 引用，不保存 UniDesk 隐式环境提示。
- `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 和 Queue 的主键、状态、时间戳和索引字段必须是一等列，不能把所有事实塞进一个不可查询 JSON blob。Queue 首版不得新增 OA/Event/integrations/notification 这类外部动作表；如后续需要 connector/sink，必须另立规格。

## 访问边界

- `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 | 已实现/已通过主闭环 | `agentrun-v01-postgres` StatefulSet、Service 和 PVC 已由 GitOps runtime 提供，作为 `agentrun-v01` durable store。 |
| migration ledger | 已实现/已通过主闭环 | `agentrun-mgr` 启动 Postgres adapter 时幂等创建 `agentrun_schema_migrations` 并记录 migration id/checksum；当前最新 migration 为 `006_v01_session_control`，用于在不改写既有 migration checksum 的前提下新增 session projection/read cursor；readiness 必须显示 migration ready。 |
| manager Postgres adapter | 已实现/已通过主闭环 | `agentrun-mgr` 通过 `DATABASE_URL` 启用 Postgres adapter，持久化 runs、commands、events、runners、runner_jobs、sessions、session read cursors、backends、leases、Queue task 和 read cursor；缺少 `DATABASE_URL` 时 live runtime fail fast，memory 只允许显式 self-test/dev。 |
| health/readiness store 状态 | 已实现 | health/readiness 返回 adapter、reachable、migrationReady、migrationId、failureKind 和 redacted Secret 状态，不输出 DSN 明文。 |
| file/sqlite durable store | 不采用 | 只可用于临时本地测试，不作为 v0.1 runtime truth。 |