运维 PostgreSQL 持久化 Provider。

显式迁移，然后连接

迁移凭据与运行时凭据必须分离。迁移是部署动作，不是每次应用启动时隐式发生的副作用。

use stateknot_store_postgres::{PostgresStore, PostgresStoreOptions};

let options = PostgresStoreOptions::default();
PostgresStore::migrate_database(&migration_url, options.clone()).await?;
let store = PostgresStore::connect(&runtime_url, options).await?;
store.health_check().await?;

Schema 缺失、版本过新或过旧、迁移不完整、Checksum 不一致都会导致启动拒绝。不能捕获该错误后继续运行部分兼容的数据库。

使用统一、已校验的启动配置

PostgresStoreConfig 提供封闭的环境变量契约和生产安全的 Builder。生产环境默认保持 TLS 完整验证并禁止隐式迁移；启用生产自动迁移时， 必须提供独立的 STATEKNOT_MIGRATION_DATABASE_URL。错误和 Debug 输出都会对连接 URL 脱敏。

use stateknot_store_postgres::{PostgresStore, PostgresStoreConfig};

let config = PostgresStoreConfig::from_env()?;
let store = PostgresStore::connect_config(config).await?;

DATABASE_URL 为必填项；STATEKNOT_AUTO_MIGRATE 与 STATEKNOT_DEV_MODE 是可选的封闭布尔值。生产迁移使用独立权限 URL。仅在可信本地数据库上，STATEKNOT_DEV_MODE=true 才会启用迁移、 关闭 TLS 并把连接池限制为四个连接；等价的显式入口是 PostgresStore::connect_development(...)。

安全且有界的默认值

传输

默认验证 TLS 证书链与主机名，URL Query 无法静默削弱该策略。

连接池

1–16 个连接、5 秒获取超时、10 分钟 Idle Retirement 与 30 分钟最大连接寿命。

事务

5 秒 Lock Timeout 与 15 秒 Statement Timeout；无效或无界的时序关系会在连接阶段 Fail Closed。

所有权

Run Lease 为 30 秒，最大续租 Horizon 为 5 分钟；Outbox Network Attempt 使用固定、不可续租的 1 分钟 Lease。

把 Graph Version 当作不可变 Release

Migration 13 增加 Tenant-scoped Compiled Graph Registry。Key 由精确 Graph Owner、Name 与 Version 组成；Canonical Bytes 和 Definition Digest 不能在该 Key 下变化。Run 依赖其 Reference 前必须先注册 Graph。

let outcome = store
    .register_graph_definition(tenant_id, compiled_graph)
    .await?;

相同重试会收敛到原注册；同一版本下的不同 Bytes 会返回冲突。每次 Load 都会重新编译并验证 Canonical Bytes、冗余 Key Column、Digest 与 Tenant Binding；Claimed Recovery 会在精确 Live Fence 下隔离缺失或损坏的 Pinned Evidence。

禁止暴露只初始化一半的 Agent Run

Migration 15 增加不可变 agent_admissions。DurableAgentAdmission 在一个 Transaction 内提交已认证 Intent、数据库时间、Active Lifecycle、 Sequence-one Event、Superstep-zero Checkpoint、Graph Anchor 与 Scheduler Projection。精确 Retry 会恢复并重校验原 Commit；Changed Intent 会产生 Conflict。

Scheduler-ready Index 现在要求 Checkpoint，因此低层未初始化 Row 无法被 Claim。可信 Ingress、Idempotency、Rollout 与敏感数据要求见持久化准入指南。

Migration 16 增加 Tenant-scoped 持久化 Submission Key。Key Mapping 与 Admission 同时 Commit，不保存 Raw Key；相同 Logical Retry 可以使用新的 Candidate ID，Changed Content 或同 Run 的第二个 Key 会被拒绝。详见Run/Result 指南。

不要随意削弱 TLS

生产环境应使用 VerifyFull。RequireEncryption 只加密但不认证 Server，属于明确降级；Disabled 仅适用于可信本地 Socket 或隔离测试网络。

把 Artifact 注册为不可变 Evidence

Migration 18 增加 Tenant-qualified artifacts 与 artifact_parents。每条记录会绑定 Canonical Reference Bytes/Digest、Content Length/Digest、 Origin Run/Event、Same-tenant Lineage、Idempotency Key 与私有、Provider-neutral Locator。Exact Retry 会收敛；Changed Metadata 会产生 Conflict，每次 Load 都会重新校验完整 Projection。

Object I/O 位于 Registry Transaction 之外。Artifact 持久化指南定义私有 Conditional Publication、Authorization-before-lookup、完整 Integrity Verification、Egress Policy 与 Cleanup 责任。

绑定已知 Model Failure，但不削弱 Barrier

Migration 19 允许 Pending Node Result 绑定状态为 committed 或 failed 的精确 Terminal Model Revision。Composite Foreign Key 仍固定 Tenant、Run、Invocation、Revision、Digest、Status 与 Journal Anchor； Prepared/Executing Revision 仍不可绑定，并继续阻塞 Checkpoint 推进。

Provider-native Graph 只把它用于确定性、有界 Output Repair：Response Phase 的 response.malformed Failure 必须携带精确 Usage，才能成为已消费 Evidence。PostgreSQL 16/17 Matrix 会验证已填充 v18→v19 Upgrade、Legacy Constraint 拒绝、Failed-binding Reload 与 Successor Barrier Commit。

分离数据库角色

Migration Role 需要创建所属 Schema 与迁移表的权限。Runtime Role 只需要文档声明的表与 Projection 操作权限；不应获得 DDL，也不应获得修改或删除不可变 Journal、Checkpoint、Invocation Revision、Attempt、Result、Graph Definition 或 Consumption History 的权限。

精确 Grant Surface 维护在仓库的Provider 运维文档中。请按实际部署版本审核，不要复制旧文章中的 Grant。

验证范围与当前限制

CI 会分别在 PostgreSQL 16 与 17 上执行强制的 Provider、Runtime 与 Artifact-store 集成测试，覆盖迁移、Lost ACK、Fencing、损坏拒绝、并发、Rollback Injection、Outbox Recovery、Durable Wait、Quarantine、不可变 Graph Registration/Recovery、Ready-node Planning 与延迟重试调度、Lifecycle Commit、可恢复 Model/Tool 执行、Fairness Reservation / Retention、原子 Agent Admission、Canonical Parallel Sibling Commit、有序 Read-only Tool Wave 与 Write Barrier、持久化 Ingress-key/Run-result 校验和加权 Cross-tenant Agent Loop 执行。Model Binding Evidence 还覆盖已填充的 Migration 18→19、 Committed-only Constraint 拒绝、精确 Failed-revision Recovery 与 Successor Barrier Release。Artifact Evidence 还覆盖已填充的 Migration 17→18、Schema Refusal、不可变 Registration、私有 Object Publication、 Authorization-first Lookup、Multipart Ingestion 与完整 Digest 校验。

独立的 pg_dump/pg_restore 演练验证已消费子 Join 的完整快照与图恢复执行；另有物理 pg_basebackup 加 WAL 归档演练，在命名恢复点恢复同一路径并排除之后的写入。两者都不等于完整灾备或同步备库故障切换验收。

正式生产发布仍需要角色隔离、通用 Retention/GC、参考规模的故障切换与恢复演练、Stale-race 验证、Role-separated Service Deployment 与 Live-workload Qualification。