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、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 定义的 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，然后在 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，然后创建 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；readiness 必须显示 migration ready。
manager Postgres adapter	已实现/已通过主闭环	agentrun-mgr 通过 DATABASE_URL 启用 Postgres adapter，持久化 runs、commands、events、runners、backends 和 leases；缺少 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。