[rgarcia]

Summary

Adds PostgresStorage to @earendil-works/pi-durable/storage/postgres, a fourth storage backend beside memory, SQLite, and JSONL.

import pg from "pg";
import { PostgresStorage } from "@earendil-works/pi-durable/storage/postgres";

const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
const harness = await Harness.open(await PostgresStorage.open(pool, { session: "support-bot" }), { models, registry }, context);

Design

• No runtime dependency. The storage takes a caller-owned pool through a small structural interface (query, connect, and release/on/off on a client). A pg.Pool satisfies it as is; pg and @types/pg are dev dependencies for tests only.
• Port of SqliteStorage. Same tables, same commit logic, same error messages, Postgres SQL. Records are json (not jsonb) so the stored text round-trips exactly. Indexed strings stay JSON-encoded, as in SQLite, because drivers send UTF-8 and would replace lone surrogates.
• Many Sessions per schema. Every table is keyed by session_id first. The schema defaults to pi_durable, can be overridden with schema, and is created and migrated on first open under a transaction-scoped advisory lock.
• Single owner, enforced. SQLite and JSONL leave this to the caller; a shared database needs it:
  • open() takes a session-level advisory lock on a client it keeps checked out until close(), and rejects if another process holds the Session.
  • open() also writes a fresh owner token. Every commit reads the Session row FOR UPDATE and rejects if the token changed, so a process whose lock connection silently died cannot write after another process takes over.
  • An error on the lock client marks the storage lost; later operations reject.
• document() reads in a REPEATABLE READ READ ONLY transaction so the record and its revisions come from one snapshot. close() waits for admitted operations before releasing the lock. The pool needs at least two connections.

Testing

• test/postgres-storage.test.ts runs the shared storage conformance suite twice (fresh storage, and reopen after every commit) plus ownership and migration tests: Session isolation, second-open rejection, lock-connection loss via pg_terminate_backend, commit fencing after takeover, ID and sequence persistence, concurrent first opens of a fresh schema, and newer-schema rejection. These are skipped unless PI_DURABLE_POSTGRES_URL is set, so CI without Postgres is unaffected.
• Locally against Postgres 17: all 909 durable tests pass with PI_DURABLE_POSTGRES_URL set (908 passed, 1 pre-existing skip).
• Ran examples 13-recovery and 31-reload-and-restart with their SQLite storage swapped for PostgresStorage; output matched SQLite exactly (task resumes from its checkpoint after reopen; reload and restart behave the same).
• npm run build, root tsc --noEmit, biome, and the pre-commit checks pass. The root tsc run also confirms pg.Pool is assignable to the pool interface.
• Not done: no benchmarks against SQLite yet.

[rgarcia]

Superseded by #5, which carries the Postgres storage adapter rebuilt on the grouped-commit contract (and includes #4, which merged into this branch). Retargeted #5 to main.