@haikit/postgres 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hai contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# @haikit/postgres
+
+A durable `StoreAdapter` for haikit. Swap it in for `memoryStore()` before you
+ship: a parked `elicit` turn is durable state, and a conversation that loses it
+can never be sent again.
+
+```ts
+import pg from "pg";
+import { createHai } from "@haikit/server";
+import { pgStore, migrate } from "@haikit/postgres";
+
+const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
+await migrate(pool);
+
+const hai = createHai({ store: pgStore(pool), model, tools, surfaces, system });
+```
+
+## Bring your own driver
+
+`pgStore` takes anything with `query(text, params) → Promise<{ rows }>`. A
+`pg.Pool`, a `pg.Client` and PGlite all fit as they are, so this package depends
+on `@haikit/core` and nothing else — pooling, TLS and connection lifecycle stay
+yours.
+
+## Why it is safe to run on several instances
+
+- **One statement per operation.** Every fenced write checks the turn's lease
+  token inside the same `UPDATE` or `INSERT … SELECT` that performs it. There is
+  no read-then-write anywhere, so there is nothing to race and no transaction to
+  forget.
+- **The database's clock.** Lease expiry is computed with `now()`, never
+  `Date.now()`, so clock skew between app servers cannot hand one conversation
+  to two of them.
+- **Write-once payloads.** Everything about a surface that changes over a
+  conversation lives on the fenced conversation row, so no payload write can
+  disagree with the history that references it.
+
+The test suite runs twenty real connections at one released lease and requires
+exactly one to win.
+
+## Schema
+
+Two tables, `haikit_conversations` and `haikit_payloads`. `migrate()` creates
+them if they do not exist; if you use your own migration tool, the statements
+are exported as `schema`.
+
+Handles are numbered per conversation, so every conversation's digests start at
+`ui_01`.
+
+## Cleaning up
+
+A turn that is overtaken mid-flight can leave payload rows that the surviving
+history never references. They are inert — an interaction on one is refused —
+but they are still rows:
+
+```ts
+import { sweepOrphans } from "@haikit/postgres";
+
+await sweepOrphans(pool, { olderThanMs: 24 * 60 * 60 * 1000 });
+```
+
+Keep `olderThanMs` above your lease TTL. Conversations with a turn in flight are
+skipped regardless. Deleting whole conversations is retention policy, not
+garbage collection, and is left to you.

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @haikit/postgres — a durable StoreAdapter.
+ *
+ * Every method is a single SQL statement, and every fenced write checks the
+ * lease token *inside* that statement. That is the whole trick: the contract in
+ * `@haikit/core` requires the check and the write to be atomic, and a
+ * conditional UPDATE is atomic without a transaction. There is no
+ * read-then-write anywhere in this file, and none should be added.
+ *
+ * Time comes from the database (`now()`), never from `Date.now()`, so lease
+ * expiry cannot be skewed by clocks on different app servers.
+ */
+import { type StoreAdapter } from "@haikit/core";
+/**
+ * Anything that runs a parameterised statement and returns rows. A `pg.Pool`,
+ * a `pg.Client` and PGlite all satisfy this as they are — the driver is yours,
+ * and so are pooling and connection lifecycle.
+ *
+ * Only `rows` is required. Every fenced statement here uses `RETURNING` and
+ * checks the rows it got back rather than a driver's affected-row count,
+ * because drivers disagree on what that field is called.
+ */
+export interface Queryable {
+    query(text: string, params?: unknown[]): Promise<{
+        rows: any[];
+    }>;
+}
+export interface PgStoreOptions {
+    /**
+     * Turn lease TTL. A process that dies mid-turn strands its conversation for
+     * this long; too short and a slow turn is overtaken while still running —
+     * which is safe (its writes are fenced out) but wasteful.
+     */
+    leaseMs?: number;
+}
+/**
+ * The schema, one statement per entry. `migrate()` runs these; export them to
+ * your own migration tool instead if you have one.
+ */
+export declare const schema: readonly string[];
+/** Create the tables if they do not exist. Idempotent. */
+export declare function migrate(db: Queryable): Promise<void>;
+export declare function pgStore(db: Queryable, options?: PgStoreOptions): StoreAdapter;
+export interface SweepOptions {
+    /**
+     * Only sweep rows at least this old. Keep it above your lease TTL: a turn
+     * inserts its payloads before it saves the history that references them, so
+     * a young row can look orphaned while its turn is still running.
+     */
+    olderThanMs: number;
+}
+/**
+ * Delete orphaned payloads: rows written by a turn that was then overtaken, so
+ * the surviving history never recorded their handles. They are inert — an
+ * interaction on one is refused — but they are still rows.
+ *
+ * Conversations with a live lease are skipped regardless of age, so an
+ * in-flight turn's not-yet-recorded payloads are never touched. Deleting
+ * conversations themselves is retention policy, not garbage collection, and is
+ * left to you.
+ */
+export declare function sweepOrphans(db: Queryable, options: SweepOptions): Promise<{
+    deleted: number;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAEtB;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,GAAG,EAAE,CAAA;KAAE,CAAC,CAAC;CACnE;AAED,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID;;;GAGG;AACH,eAAO,MAAM,MAAM,EAAE,SAAS,MAAM,EA0BnC,CAAC;AAEF,0DAA0D;AAC1D,wBAAsB,OAAO,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAI1D;AAqCD,wBAAgB,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,GAAE,cAAmB,GAAG,YAAY,CAkIjF;AAED,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAYrG"}

package/dist/index.js

@@ -0,0 +1,212 @@
+/**
+ * @haikit/postgres — a durable StoreAdapter.
+ *
+ * Every method is a single SQL statement, and every fenced write checks the
+ * lease token *inside* that statement. That is the whole trick: the contract in
+ * `@haikit/core` requires the check and the write to be atomic, and a
+ * conditional UPDATE is atomic without a transaction. There is no
+ * read-then-write anywhere in this file, and none should be added.
+ *
+ * Time comes from the database (`now()`), never from `Date.now()`, so lease
+ * expiry cannot be skewed by clocks on different app servers.
+ */
+import { ConversationBusy, StaleLease, } from "@haikit/core";
+const LEASE_MS = 120_000;
+/**
+ * The schema, one statement per entry. `migrate()` runs these; export them to
+ * your own migration tool instead if you have one.
+ */
+export const schema = [
+    `CREATE TABLE IF NOT EXISTS haikit_conversations (
+     id           text PRIMARY KEY,
+     status       text NOT NULL,
+     messages     jsonb NOT NULL DEFAULT '[]',
+     handles      jsonb NOT NULL DEFAULT '[]',
+     frozen       jsonb NOT NULL DEFAULT '[]',
+     pending      jsonb,
+     lease_until  timestamptz,
+     lease_token  text,
+     handle_seq   integer NOT NULL DEFAULT 0,
+     updated_at   timestamptz NOT NULL DEFAULT now()
+   )`,
+    // Write-once. Nothing about a payload changes after insert — everything that
+    // does lives on the fenced conversation row (see Conversation.frozen).
+    `CREATE TABLE IF NOT EXISTS haikit_payloads (
+     conversation_id text NOT NULL REFERENCES haikit_conversations(id) ON DELETE CASCADE,
+     handle          text NOT NULL,
+     component       text NOT NULL,
+     version         integer NOT NULL,
+     props           jsonb NOT NULL,
+     mode            text NOT NULL,
+     created_at      timestamptz NOT NULL DEFAULT now(),
+     PRIMARY KEY (conversation_id, handle)
+   )`,
+    `CREATE INDEX IF NOT EXISTS haikit_payloads_created_at ON haikit_payloads (created_at)`,
+];
+/** Create the tables if they do not exist. Idempotent. */
+export async function migrate(db) {
+    // One statement per call: some drivers (PGlite among them) reject several
+    // statements in a single parameterised query.
+    for (const statement of schema)
+        await db.query(statement);
+}
+const CONVERSATION_COLUMNS = `
+  id, status, messages, handles, frozen, pending, lease_token,
+  (extract(epoch FROM lease_until) * 1000)::float8 AS lease_until_ms`;
+const PAYLOAD_COLUMNS = `
+  handle, conversation_id, component, version, props, mode,
+  (extract(epoch FROM created_at) * 1000)::float8 AS created_at_ms`;
+/** Most drivers parse jsonb into values; a few hand back text. Accept both. */
+const json = (value) => (typeof value === "string" ? JSON.parse(value) : value);
+const toConversation = (row) => ({
+    id: row.id,
+    status: row.status,
+    messages: json(row.messages),
+    handles: json(row.handles),
+    frozen: json(row.frozen),
+    pending: row.pending == null ? null : json(row.pending),
+    leaseUntil: row.lease_until_ms == null ? null : Number(row.lease_until_ms),
+    leaseToken: row.lease_token,
+});
+const toPayload = (row) => ({
+    handle: row.handle,
+    conversationId: row.conversation_id,
+    component: row.component,
+    version: Number(row.version),
+    props: json(row.props),
+    mode: row.mode,
+    createdAt: Number(row.created_at_ms),
+});
+const newToken = () => globalThis.crypto.randomUUID();
+const newId = () => `conv_${globalThis.crypto.randomUUID().replaceAll("-", "")}`;
+export function pgStore(db, options = {}) {
+    const leaseMs = options.leaseMs ?? LEASE_MS;
+    /** A fenced write matched nothing. Say which of the two reasons applies. */
+    async function stale(conversationId) {
+        const { rows } = await db.query(`SELECT 1 FROM haikit_conversations WHERE id = $1`, [conversationId]);
+        throw rows.length
+            ? new StaleLease(conversationId)
+            : new StaleLease(conversationId, "does not exist — no lease was ever issued for it");
+    }
+    return {
+        async loadConversation(id) {
+            if (id) {
+                // Acquisition in one statement: the expiry check and the new token are
+                // the same UPDATE, so two instances cannot both see "expired" and both
+                // acquire. The row lock serialises them; the loser re-evaluates the
+                // WHERE clause against the winner's committed lease and matches nothing.
+                const { rows } = await db.query(`UPDATE haikit_conversations
+              SET lease_until = now() + $2::float8 * interval '1 millisecond',
+                  lease_token = $3
+            WHERE id = $1 AND (lease_until IS NULL OR lease_until <= now())
+            RETURNING ${CONVERSATION_COLUMNS}`, [id, leaseMs, newToken()]);
+                if (rows[0])
+                    return toConversation(rows[0]);
+                // Nothing matched: either someone holds the lease, or there is no such
+                // conversation. This second read only picks the error — it decides
+                // nothing about who holds the lease.
+                const exists = await db.query(`SELECT 1 FROM haikit_conversations WHERE id = $1`, [id]);
+                if (exists.rows.length)
+                    throw new ConversationBusy(id);
+                // An unknown id starts a fresh conversation, as memoryStore does.
+            }
+            const { rows } = await db.query(`INSERT INTO haikit_conversations (id, status, lease_until, lease_token)
+         VALUES ($1, 'idle', now() + $2::float8 * interval '1 millisecond', $3)
+         RETURNING ${CONVERSATION_COLUMNS}`, [newId(), leaseMs, newToken()]);
+            return toConversation(rows[0]);
+        },
+        async saveConversation(conversation) {
+            // Compare-and-set on the token. A null token or an unknown id matches no
+            // row (NULL = x is never true), which is exactly the contract: saving is
+            // not an upsert, and a superseded holder cannot overwrite the winner.
+            const { rows } = await db.query(`UPDATE haikit_conversations
+            SET status      = $3,
+                messages    = $4::jsonb,
+                handles     = $5::jsonb,
+                frozen      = $6::jsonb,
+                pending     = $7::jsonb,
+                lease_until = to_timestamp($8::float8 / 1000),
+                updated_at  = now()
+          WHERE id = $1 AND lease_token = $2
+          RETURNING id`, [
+                conversation.id,
+                conversation.leaseToken,
+                conversation.status,
+                JSON.stringify(conversation.messages),
+                JSON.stringify(conversation.handles),
+                JSON.stringify(conversation.frozen),
+                // SQL NULL, not the JSON value null — keep "no pending turn" queryable
+                conversation.pending == null ? null : JSON.stringify(conversation.pending),
+                conversation.leaseUntil,
+            ]);
+            if (!rows.length)
+                await stale(conversation.id);
+        },
+        async putPayload(record, leaseToken) {
+            // Fence, number and insert in one statement. The CTE's UPDATE both checks
+            // the token and takes the next handle number under the row lock, so
+            // concurrent renders in one conversation never share a handle. If the
+            // token does not match, `owner` is empty and nothing is inserted.
+            const { rows } = await db.query(`WITH owner AS (
+           UPDATE haikit_conversations
+              SET handle_seq = handle_seq + 1
+            WHERE id = $1::text AND lease_token = $2
+            RETURNING handle_seq
+         )
+         INSERT INTO haikit_payloads (conversation_id, handle, component, version, props, mode)
+         SELECT $1::text,
+                -- ui_01 … ui_09, ui_10 … ui_99, ui_100: pad, never truncate
+                'ui_' || CASE WHEN handle_seq < 10 THEN '0' ELSE '' END || handle_seq,
+                $3::text, $4::integer, $5::jsonb, $6::text
+           FROM owner
+         RETURNING handle`, [
+                record.conversationId,
+                leaseToken,
+                record.component,
+                record.version,
+                JSON.stringify(record.props),
+                record.mode,
+            ]);
+            if (!rows.length)
+                await stale(record.conversationId);
+            return rows[0].handle;
+        },
+        /** Scoped: a handle is only meaningful inside its own conversation. */
+        async getPayload(handle, conversationId) {
+            const { rows } = await db.query(`SELECT ${PAYLOAD_COLUMNS} FROM haikit_payloads WHERE conversation_id = $1 AND handle = $2`, [conversationId, handle]);
+            return rows[0] ? toPayload(rows[0]) : null;
+        },
+        async getPayloads(handles, conversationId) {
+            if (!handles.length)
+                return [];
+            // The list travels as jsonb rather than a native array parameter, which
+            // not every driver encodes the same way.
+            const { rows } = await db.query(`SELECT ${PAYLOAD_COLUMNS} FROM haikit_payloads
+          WHERE conversation_id = $1
+            AND handle IN (SELECT jsonb_array_elements_text($2::jsonb))`, [conversationId, JSON.stringify(handles)]);
+            const order = new Map(handles.map((h, i) => [h, i]));
+            return rows.map(toPayload).sort((a, b) => order.get(a.handle) - order.get(b.handle));
+        },
+    };
+}
+/**
+ * Delete orphaned payloads: rows written by a turn that was then overtaken, so
+ * the surviving history never recorded their handles. They are inert — an
+ * interaction on one is refused — but they are still rows.
+ *
+ * Conversations with a live lease are skipped regardless of age, so an
+ * in-flight turn's not-yet-recorded payloads are never touched. Deleting
+ * conversations themselves is retention policy, not garbage collection, and is
+ * left to you.
+ */
+export async function sweepOrphans(db, options) {
+    const { rows } = await db.query(`DELETE FROM haikit_payloads p
+      USING haikit_conversations c
+      WHERE p.conversation_id = c.id
+        AND p.created_at < now() - $1::float8 * interval '1 millisecond'
+        AND (c.lease_until IS NULL OR c.lease_until <= now())
+        AND NOT (c.handles @> jsonb_build_array(p.handle))
+      RETURNING p.handle`, [options.olderThanMs]);
+    return { deleted: rows.length };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@haikit/postgres",
+  "version": "0.3.0",
+  "description": "Postgres store adapter for haikit: durable conversations, fenced turn leases, write-once payloads. Bring your own driver.",
+  "keywords": [
+    "haikit",
+    "postgres",
+    "postgresql",
+    "llm",
+    "agent",
+    "agentic-ui",
+    "store",
+    "durable"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "prepack": "npm --prefix ../.. run build"
+  },
+  "dependencies": {
+    "@haikit/core": "0.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/wfoxd/haikit/tree/main/packages/postgres#readme",
+  "bugs": {
+    "url": "https://github.com/wfoxd/haikit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wfoxd/haikit.git",
+    "directory": "packages/postgres"
+  }
+}

package/src/index.ts

@@ -0,0 +1,283 @@
+/**
+ * @haikit/postgres — a durable StoreAdapter.
+ *
+ * Every method is a single SQL statement, and every fenced write checks the
+ * lease token *inside* that statement. That is the whole trick: the contract in
+ * `@haikit/core` requires the check and the write to be atomic, and a
+ * conditional UPDATE is atomic without a transaction. There is no
+ * read-then-write anywhere in this file, and none should be added.
+ *
+ * Time comes from the database (`now()`), never from `Date.now()`, so lease
+ * expiry cannot be skewed by clocks on different app servers.
+ */
+
+import {
+  ConversationBusy,
+  StaleLease,
+  type Conversation,
+  type PayloadRecord,
+  type StoreAdapter,
+} from "@haikit/core";
+
+/**
+ * Anything that runs a parameterised statement and returns rows. A `pg.Pool`,
+ * a `pg.Client` and PGlite all satisfy this as they are — the driver is yours,
+ * and so are pooling and connection lifecycle.
+ *
+ * Only `rows` is required. Every fenced statement here uses `RETURNING` and
+ * checks the rows it got back rather than a driver's affected-row count,
+ * because drivers disagree on what that field is called.
+ */
+export interface Queryable {
+  query(text: string, params?: unknown[]): Promise<{ rows: any[] }>;
+}
+
+export interface PgStoreOptions {
+  /**
+   * Turn lease TTL. A process that dies mid-turn strands its conversation for
+   * this long; too short and a slow turn is overtaken while still running —
+   * which is safe (its writes are fenced out) but wasteful.
+   */
+  leaseMs?: number;
+}
+
+const LEASE_MS = 120_000;
+
+/**
+ * The schema, one statement per entry. `migrate()` runs these; export them to
+ * your own migration tool instead if you have one.
+ */
+export const schema: readonly string[] = [
+  `CREATE TABLE IF NOT EXISTS haikit_conversations (
+     id           text PRIMARY KEY,
+     status       text NOT NULL,
+     messages     jsonb NOT NULL DEFAULT '[]',
+     handles      jsonb NOT NULL DEFAULT '[]',
+     frozen       jsonb NOT NULL DEFAULT '[]',
+     pending      jsonb,
+     lease_until  timestamptz,
+     lease_token  text,
+     handle_seq   integer NOT NULL DEFAULT 0,
+     updated_at   timestamptz NOT NULL DEFAULT now()
+   )`,
+  // Write-once. Nothing about a payload changes after insert — everything that
+  // does lives on the fenced conversation row (see Conversation.frozen).
+  `CREATE TABLE IF NOT EXISTS haikit_payloads (
+     conversation_id text NOT NULL REFERENCES haikit_conversations(id) ON DELETE CASCADE,
+     handle          text NOT NULL,
+     component       text NOT NULL,
+     version         integer NOT NULL,
+     props           jsonb NOT NULL,
+     mode            text NOT NULL,
+     created_at      timestamptz NOT NULL DEFAULT now(),
+     PRIMARY KEY (conversation_id, handle)
+   )`,
+  `CREATE INDEX IF NOT EXISTS haikit_payloads_created_at ON haikit_payloads (created_at)`,
+];
+
+/** Create the tables if they do not exist. Idempotent. */
+export async function migrate(db: Queryable): Promise<void> {
+  // One statement per call: some drivers (PGlite among them) reject several
+  // statements in a single parameterised query.
+  for (const statement of schema) await db.query(statement);
+}
+
+const CONVERSATION_COLUMNS = `
+  id, status, messages, handles, frozen, pending, lease_token,
+  (extract(epoch FROM lease_until) * 1000)::float8 AS lease_until_ms`;
+
+const PAYLOAD_COLUMNS = `
+  handle, conversation_id, component, version, props, mode,
+  (extract(epoch FROM created_at) * 1000)::float8 AS created_at_ms`;
+
+/** Most drivers parse jsonb into values; a few hand back text. Accept both. */
+const json = (value: unknown) => (typeof value === "string" ? JSON.parse(value) : value);
+
+const toConversation = (row: any): Conversation => ({
+  id: row.id,
+  status: row.status,
+  messages: json(row.messages),
+  handles: json(row.handles),
+  frozen: json(row.frozen),
+  pending: row.pending == null ? null : json(row.pending),
+  leaseUntil: row.lease_until_ms == null ? null : Number(row.lease_until_ms),
+  leaseToken: row.lease_token,
+});
+
+const toPayload = (row: any): PayloadRecord => ({
+  handle: row.handle,
+  conversationId: row.conversation_id,
+  component: row.component,
+  version: Number(row.version),
+  props: json(row.props),
+  mode: row.mode,
+  createdAt: Number(row.created_at_ms),
+});
+
+const newToken = () => globalThis.crypto.randomUUID();
+const newId = () => `conv_${globalThis.crypto.randomUUID().replaceAll("-", "")}`;
+
+export function pgStore(db: Queryable, options: PgStoreOptions = {}): StoreAdapter {
+  const leaseMs = options.leaseMs ?? LEASE_MS;
+
+  /** A fenced write matched nothing. Say which of the two reasons applies. */
+  async function stale(conversationId: string): Promise<never> {
+    const { rows } = await db.query(`SELECT 1 FROM haikit_conversations WHERE id = $1`, [conversationId]);
+    throw rows.length
+      ? new StaleLease(conversationId)
+      : new StaleLease(conversationId, "does not exist — no lease was ever issued for it");
+  }
+
+  return {
+    async loadConversation(id) {
+      if (id) {
+        // Acquisition in one statement: the expiry check and the new token are
+        // the same UPDATE, so two instances cannot both see "expired" and both
+        // acquire. The row lock serialises them; the loser re-evaluates the
+        // WHERE clause against the winner's committed lease and matches nothing.
+        const { rows } = await db.query(
+          `UPDATE haikit_conversations
+              SET lease_until = now() + $2::float8 * interval '1 millisecond',
+                  lease_token = $3
+            WHERE id = $1 AND (lease_until IS NULL OR lease_until <= now())
+            RETURNING ${CONVERSATION_COLUMNS}`,
+          [id, leaseMs, newToken()],
+        );
+        if (rows[0]) return toConversation(rows[0]);
+
+        // Nothing matched: either someone holds the lease, or there is no such
+        // conversation. This second read only picks the error — it decides
+        // nothing about who holds the lease.
+        const exists = await db.query(`SELECT 1 FROM haikit_conversations WHERE id = $1`, [id]);
+        if (exists.rows.length) throw new ConversationBusy(id);
+        // An unknown id starts a fresh conversation, as memoryStore does.
+      }
+
+      const { rows } = await db.query(
+        `INSERT INTO haikit_conversations (id, status, lease_until, lease_token)
+         VALUES ($1, 'idle', now() + $2::float8 * interval '1 millisecond', $3)
+         RETURNING ${CONVERSATION_COLUMNS}`,
+        [newId(), leaseMs, newToken()],
+      );
+      return toConversation(rows[0]);
+    },
+
+    async saveConversation(conversation) {
+      // Compare-and-set on the token. A null token or an unknown id matches no
+      // row (NULL = x is never true), which is exactly the contract: saving is
+      // not an upsert, and a superseded holder cannot overwrite the winner.
+      const { rows } = await db.query(
+        `UPDATE haikit_conversations
+            SET status      = $3,
+                messages    = $4::jsonb,
+                handles     = $5::jsonb,
+                frozen      = $6::jsonb,
+                pending     = $7::jsonb,
+                lease_until = to_timestamp($8::float8 / 1000),
+                updated_at  = now()
+          WHERE id = $1 AND lease_token = $2
+          RETURNING id`,
+        [
+          conversation.id,
+          conversation.leaseToken,
+          conversation.status,
+          JSON.stringify(conversation.messages),
+          JSON.stringify(conversation.handles),
+          JSON.stringify(conversation.frozen),
+          // SQL NULL, not the JSON value null — keep "no pending turn" queryable
+          conversation.pending == null ? null : JSON.stringify(conversation.pending),
+          conversation.leaseUntil,
+        ],
+      );
+      if (!rows.length) await stale(conversation.id);
+    },
+
+    async putPayload(record, leaseToken) {
+      // Fence, number and insert in one statement. The CTE's UPDATE both checks
+      // the token and takes the next handle number under the row lock, so
+      // concurrent renders in one conversation never share a handle. If the
+      // token does not match, `owner` is empty and nothing is inserted.
+      const { rows } = await db.query(
+        `WITH owner AS (
+           UPDATE haikit_conversations
+              SET handle_seq = handle_seq + 1
+            WHERE id = $1::text AND lease_token = $2
+            RETURNING handle_seq
+         )
+         INSERT INTO haikit_payloads (conversation_id, handle, component, version, props, mode)
+         SELECT $1::text,
+                -- ui_01 … ui_09, ui_10 … ui_99, ui_100: pad, never truncate
+                'ui_' || CASE WHEN handle_seq < 10 THEN '0' ELSE '' END || handle_seq,
+                $3::text, $4::integer, $5::jsonb, $6::text
+           FROM owner
+         RETURNING handle`,
+        [
+          record.conversationId,
+          leaseToken,
+          record.component,
+          record.version,
+          JSON.stringify(record.props),
+          record.mode,
+        ],
+      );
+      if (!rows.length) await stale(record.conversationId);
+      return rows[0].handle;
+    },
+
+    /** Scoped: a handle is only meaningful inside its own conversation. */
+    async getPayload(handle, conversationId) {
+      const { rows } = await db.query(
+        `SELECT ${PAYLOAD_COLUMNS} FROM haikit_payloads WHERE conversation_id = $1 AND handle = $2`,
+        [conversationId, handle],
+      );
+      return rows[0] ? toPayload(rows[0]) : null;
+    },
+
+    async getPayloads(handles, conversationId) {
+      if (!handles.length) return [];
+      // The list travels as jsonb rather than a native array parameter, which
+      // not every driver encodes the same way.
+      const { rows } = await db.query(
+        `SELECT ${PAYLOAD_COLUMNS} FROM haikit_payloads
+          WHERE conversation_id = $1
+            AND handle IN (SELECT jsonb_array_elements_text($2::jsonb))`,
+        [conversationId, JSON.stringify(handles)],
+      );
+      const order = new Map(handles.map((h, i) => [h, i] as const));
+      return rows.map(toPayload).sort((a, b) => order.get(a.handle)! - order.get(b.handle)!);
+    },
+  };
+}
+
+export interface SweepOptions {
+  /**
+   * Only sweep rows at least this old. Keep it above your lease TTL: a turn
+   * inserts its payloads before it saves the history that references them, so
+   * a young row can look orphaned while its turn is still running.
+   */
+  olderThanMs: number;
+}
+
+/**
+ * Delete orphaned payloads: rows written by a turn that was then overtaken, so
+ * the surviving history never recorded their handles. They are inert — an
+ * interaction on one is refused — but they are still rows.
+ *
+ * Conversations with a live lease are skipped regardless of age, so an
+ * in-flight turn's not-yet-recorded payloads are never touched. Deleting
+ * conversations themselves is retention policy, not garbage collection, and is
+ * left to you.
+ */
+export async function sweepOrphans(db: Queryable, options: SweepOptions): Promise<{ deleted: number }> {
+  const { rows } = await db.query(
+    `DELETE FROM haikit_payloads p
+      USING haikit_conversations c
+      WHERE p.conversation_id = c.id
+        AND p.created_at < now() - $1::float8 * interval '1 millisecond'
+        AND (c.lease_until IS NULL OR c.lease_until <= now())
+        AND NOT (c.handles @> jsonb_build_array(p.handle))
+      RETURNING p.handle`,
+    [options.olderThanMs],
+  );
+  return { deleted: rows.length };
+}