@kyneta/postgres-store 1.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Duane Johnson
+
+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,99 @@
+# @kyneta/postgres-store
+
+Postgres storage backend for `@kyneta/exchange` — async-native, JSONB meta, BYTEA blobs.
+
+## Installation
+
+```sh
+pnpm add @kyneta/postgres-store pg
+```
+
+Peer dependencies: `@kyneta/exchange`, `@kyneta/schema`, `@kyneta/sql-store-core`, `pg`.
+
+## Usage
+
+### Recommended: `createPostgresStore` factory
+
+```ts
+import { Pool } from "pg"
+import { Exchange } from "@kyneta/exchange"
+import { createPostgresStore } from "@kyneta/postgres-store"
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL })
+const store = await createPostgresStore(pool)
+
+const exchange = new Exchange({
+  stores: [store],
+  // ...
+})
+
+// On shutdown:
+// await exchange.shutdown()
+// await pool.end()
+```
+
+The factory queries `information_schema.columns` to validate that the canonical schema exists with compatible column types, then returns a ready Store. If validation fails, a curated error tells you which column is missing or has the wrong type.
+
+### Sync constructor (advanced)
+
+For callers that validate the schema separately at process start:
+
+```ts
+import { PostgresStore } from "@kyneta/postgres-store"
+
+const store = new PostgresStore(pool)
+```
+
+## Schema
+
+Run [`schema.sql`](./schema.sql) once before constructing the store, or include the canonical DDL as a step in your migration pipeline. The store does not auto-DDL — Postgres convention is migrations-as-deployment-step.
+
+```sql
+CREATE TABLE IF NOT EXISTS kyneta_meta (
+  doc_id TEXT  PRIMARY KEY,
+  data   JSONB NOT NULL
+);
+CREATE TABLE IF NOT EXISTS kyneta_records (
+  doc_id  TEXT    NOT NULL,
+  seq     INTEGER NOT NULL,
+  kind    TEXT    NOT NULL,
+  payload TEXT,
+  blob    BYTEA,
+  PRIMARY KEY (doc_id, seq)
+);
+```
+
+JSONB on `meta.data` enables operator queryability for admin tooling (`data->>'syncProtocol'`, `data->>'replicaType'`). Round-trip through `loadAll` is structurally portable with `@kyneta/sqlite-store` (both consume `toRow`/`fromRow` from `@kyneta/sql-store-core`); JSONB normalizes whitespace and key order, so a byte-level dump comparison would diverge.
+
+## Options
+
+### `tables`
+
+```ts
+const store = await createPostgresStore(pool, {
+  tables: { meta: "app_meta", records: "app_records" },
+})
+```
+
+Default: `{ meta: "kyneta_meta", records: "kyneta_records" }`. Use to run multiple isolated Exchange instances against the same database — each owns one `tables` pair.
+
+`listDocIds(prefix)` uses a range scan (`doc_id >= prefix AND doc_id < successor(prefix)`), not `LIKE`. Doc IDs containing `%` and `_` are matched literally.
+
+## Lifecycle
+
+The caller owns the connection lifecycle:
+
+- `Pool`: passed in by the caller. The Store calls `pool.connect()`/`release()` per transaction. The caller calls `pool.end()` on shutdown.
+- `Client`: passed in by the caller; transactions run against the same connection. The caller calls `client.end()` on shutdown.
+
+`PostgresStore.close()` is a no-op.
+
+### Runtime schema drift
+
+Schema validation runs once at `createPostgresStore` time. If a DBA alters the schema while the Exchange is running, the change is **not** detected — re-run `createPostgresStore` after migrations (which means restarting the Exchange). Build a `revalidate()` API only if your operational pattern actually requires it.
+
+## See also
+
+- [`@kyneta/sql-store-core`](../sql-core/) — pure helpers shared with `sqlite-store` and `prisma-store`.
+- [`@kyneta/sqlite-store`](../sqlite/) — universal SQLite backend.
+- [`@kyneta/prisma-store`](../prisma/) — backend that takes a caller-supplied `PrismaClient`.

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import { DocId, Store, StoreMeta, StoreRecord } from "@kyneta/exchange";
+import { TableNames } from "@kyneta/sql-store-core";
+import { Client, Pool } from "pg";
+
+//#region src/index.d.ts
+interface PostgresStoreOptions {
+  /**
+   * Override the default table names (`kyneta_meta` and `kyneta_records`).
+   *
+   * Use when running multiple isolated Exchange instances against the
+   * same database — each instance owns one `tables` pair.
+   */
+  tables?: Partial<TableNames>;
+}
+type PgConnection = Client | Pool;
+/**
+ * Caller owns the connection lifecycle — `close()` is a no-op,
+ * `pool.end()` is the caller's responsibility. Prefer
+ * `createPostgresStore` over the bare constructor: it validates the
+ * schema at construction time so misconfiguration fails loudly with a
+ * curated error rather than per-method `column does not exist` later.
+ */
+declare class PostgresStore implements Store {
+  #private;
+  constructor(client: PgConnection, options?: PostgresStoreOptions);
+  append(docId: DocId, record: StoreRecord): Promise<void>;
+  loadAll(docId: DocId): AsyncIterable<StoreRecord>;
+  replace(docId: DocId, records: StoreRecord[]): Promise<void>;
+  delete(docId: DocId): Promise<void>;
+  currentMeta(docId: DocId): Promise<StoreMeta | null>;
+  listDocIds(prefix?: string): AsyncIterable<DocId>;
+  close(): Promise<void>;
+}
+/**
+ * Validation runs once at factory time, not on every method call. A
+ * schema change applied while the Exchange is running won't be
+ * detected — restart after migrations. Polling or a `revalidate()`
+ * API would be over-engineering for a failure mode that fails loudly
+ * on the next write anyway.
+ */
+declare function createPostgresStore(client: PgConnection, options?: PostgresStoreOptions): Promise<Store>;
+//#endregion
+export { PostgresStore, PostgresStoreOptions, createPostgresStore };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;UAgCiB,oBAAA;;AAAjB;;;;;EAOE,MAAA,GAAS,OAAA,CAAQ,UAAA;AAAA;AAAA,KAGd,YAAA,GAAe,MAAA,GAAS,IAAA;;AAF5B;;;;;AAuBD;cAAa,aAAA,YAAyB,KAAA;EAAA;cAKxB,MAAA,EAAQ,YAAA,EAAc,OAAA,GAAS,oBAAA;EA0DrC,MAAA,CAAO,KAAA,EAAO,KAAA,EAAO,MAAA,EAAQ,WAAA,GAAc,OAAA;EA+B1C,OAAA,CAAQ,KAAA,EAAO,KAAA,GAAQ,aAAA,CAAc,WAAA;EAWtC,OAAA,CAAQ,KAAA,EAAO,KAAA,EAAO,OAAA,EAAS,WAAA,KAAgB,OAAA;EAiC/C,MAAA,CAAO,KAAA,EAAO,KAAA,GAAQ,OAAA;EAYtB,WAAA,CAAY,KAAA,EAAO,KAAA,GAAQ,OAAA,CAAQ,SAAA;EAQlC,UAAA,CAAW,MAAA,YAAkB,aAAA,CAAc,KAAA;EA0B5C,KAAA,CAAA,GAAS,OAAA;AAAA;;;;;;;;iBAsCK,mBAAA,CACpB,MAAA,EAAQ,YAAA,EACR,OAAA,GAAS,oBAAA,GACR,OAAA,CAAQ,KAAA"}

package/dist/index.js

@@ -0,0 +1,203 @@
+import { SeqNoTracker } from "@kyneta/exchange";
+import { fromRow, planAppend, planReplace, resolveTables } from "@kyneta/sql-store-core";
+//#region src/index.ts
+/**
+* Caller owns the connection lifecycle — `close()` is a no-op,
+* `pool.end()` is the caller's responsibility. Prefer
+* `createPostgresStore` over the bare constructor: it validates the
+* schema at construction time so misconfiguration fails loudly with a
+* curated error rather than per-method `column does not exist` later.
+*/
+var PostgresStore = class {
+	#client;
+	#seqNos = new SeqNoTracker();
+	#tables;
+	constructor(client, options = {}) {
+		this.#client = client;
+		this.#tables = resolveTables(options);
+	}
+	/**
+	* For `Pool`: check out a `PoolClient` so BEGIN..COMMIT all run on
+	* the same physical connection (Postgres transactions are
+	* connection-scoped; checking back out for COMMIT would target a
+	* different connection). For `Client`: run inline.
+	*
+	* Re-throws on rollback so callers can put post-commit work
+	* lexically after the awaited call — a rejection skips the next
+	* statement, mirroring sync `transaction()` + throw.
+	*/
+	async #withTransaction(fn) {
+		if (typeof this.#client.connect === "function") {
+			const poolClient = await this.#client.connect();
+			try {
+				await poolClient.query("BEGIN");
+				try {
+					const result = await fn(poolClient);
+					await poolClient.query("COMMIT");
+					return result;
+				} catch (e) {
+					await poolClient.query("ROLLBACK");
+					throw e;
+				}
+			} finally {
+				poolClient.release();
+			}
+		}
+		const client = this.#client;
+		await client.query("BEGIN");
+		try {
+			const result = await fn(client);
+			await client.query("COMMIT");
+			return result;
+		} catch (e) {
+			await client.query("ROLLBACK");
+			throw e;
+		}
+	}
+	get #q() {
+		return this.#client;
+	}
+	async append(docId, record) {
+		const plan = planAppend(docId, record, await this.currentMeta(docId), await this.#seqNos.next(docId, async () => {
+			return (await this.#q.query(`SELECT MAX(seq)::int AS max_seq FROM ${this.#tables.records} WHERE doc_id = $1`, [docId])).rows[0]?.max_seq ?? null;
+		}));
+		await this.#withTransaction(async (q) => {
+			if (plan.upsertMeta !== null) await q.query(`INSERT INTO ${this.#tables.meta} (doc_id, data)
+           VALUES ($1, $2::jsonb)
+           ON CONFLICT (doc_id) DO UPDATE SET data = EXCLUDED.data`, [docId, plan.upsertMeta.data]);
+			const { row } = plan.insertRecord;
+			await q.query(`INSERT INTO ${this.#tables.records}
+         (doc_id, seq, kind, payload, blob)
+         VALUES ($1, $2, $3, $4, $5)`, [
+				docId,
+				plan.insertRecord.seq,
+				row.kind,
+				row.payload,
+				row.blob
+			]);
+		});
+	}
+	async *loadAll(docId) {
+		const result = await this.#q.query(`SELECT kind, payload, blob FROM ${this.#tables.records}
+       WHERE doc_id = $1 ORDER BY seq`, [docId]);
+		for (const row of result.rows) yield fromRow(row);
+	}
+	async replace(docId, records) {
+		const plan = planReplace(records, await this.currentMeta(docId));
+		await this.#withTransaction(async (q) => {
+			await q.query(`DELETE FROM ${this.#tables.records} WHERE doc_id = $1`, [docId]);
+			for (const { seq, row } of plan.records) await q.query(`INSERT INTO ${this.#tables.records}
+           (doc_id, seq, kind, payload, blob)
+           VALUES ($1, $2, $3, $4, $5)`, [
+				docId,
+				seq,
+				row.kind,
+				row.payload,
+				row.blob
+			]);
+			await q.query(`INSERT INTO ${this.#tables.meta} (doc_id, data)
+         VALUES ($1, $2::jsonb)
+         ON CONFLICT (doc_id) DO UPDATE SET data = EXCLUDED.data`, [docId, plan.upsertMeta.data]);
+		});
+		this.#seqNos.reset(docId, records.length - 1);
+	}
+	async delete(docId) {
+		await this.#withTransaction(async (q) => {
+			await q.query(`DELETE FROM ${this.#tables.records} WHERE doc_id = $1`, [docId]);
+			await q.query(`DELETE FROM ${this.#tables.meta} WHERE doc_id = $1`, [docId]);
+		});
+		this.#seqNos.remove(docId);
+	}
+	async currentMeta(docId) {
+		return (await this.#q.query(`SELECT data FROM ${this.#tables.meta} WHERE doc_id = $1`, [docId])).rows[0]?.data ?? null;
+	}
+	async *listDocIds(prefix) {
+		if (prefix === void 0) {
+			const result = await this.#q.query(`SELECT doc_id FROM ${this.#tables.meta}`);
+			for (const row of result.rows) yield row.doc_id;
+			return;
+		}
+		const upper = prefixUpperBound(prefix);
+		const result = upper === null ? await this.#q.query(`SELECT doc_id FROM ${this.#tables.meta} WHERE doc_id >= $1`, [prefix]) : await this.#q.query(`SELECT doc_id FROM ${this.#tables.meta}
+             WHERE doc_id >= $1 AND doc_id < $2`, [prefix, upper]);
+		for (const row of result.rows) yield row.doc_id;
+	}
+	async close() {}
+};
+/**
+* Returns null when no successor exists (e.g. all code units at U+10FFFF),
+* letting the caller fall back to an unbounded `>= prefix` scan.
+*/
+function prefixUpperBound(prefix) {
+	if (prefix.length === 0) return null;
+	const codes = Array.from(prefix);
+	for (let i = codes.length - 1; i >= 0; i--) {
+		const code = codes[i].codePointAt(0);
+		if (code < 1114111) {
+			const next = String.fromCodePoint(code + 1);
+			return codes.slice(0, i).join("") + next;
+		}
+	}
+	return null;
+}
+/**
+* Validation runs once at factory time, not on every method call. A
+* schema change applied while the Exchange is running won't be
+* detected — restart after migrations. Polling or a `revalidate()`
+* API would be over-engineering for a failure mode that fails loudly
+* on the next write anyway.
+*/
+async function createPostgresStore(client, options = {}) {
+	await validateSchema(client, resolveTables(options));
+	return new PostgresStore(client, options);
+}
+const EXPECTED_COLUMNS = {
+	meta: [{
+		name: "doc_id",
+		types: ["text"]
+	}, {
+		name: "data",
+		types: ["jsonb"]
+	}],
+	records: [
+		{
+			name: "doc_id",
+			types: ["text"]
+		},
+		{
+			name: "seq",
+			types: ["integer"]
+		},
+		{
+			name: "kind",
+			types: ["text"]
+		},
+		{
+			name: "payload",
+			types: ["text"]
+		},
+		{
+			name: "blob",
+			types: ["bytea"]
+		}
+	]
+};
+async function validateSchema(q, tables) {
+	for (const [role, expected] of [["meta", EXPECTED_COLUMNS.meta], ["records", EXPECTED_COLUMNS.records]]) {
+		const tableName = tables[role];
+		const result = await q.query(`SELECT column_name, data_type, is_nullable
+       FROM information_schema.columns
+       WHERE table_name = $1`, [tableName]);
+		if (result.rows.length === 0) throw new Error(`@kyneta/postgres-store: table "${tableName}" not found. Run schema.sql or include the canonical DDL in your migrations.`);
+		const columnsByName = new Map(result.rows.map((r) => [r.column_name, r]));
+		for (const col of expected) {
+			const found = columnsByName.get(col.name);
+			if (found === void 0) throw new Error(`@kyneta/postgres-store: table "${tableName}" missing column "${col.name}". See schema.sql for the canonical definition.`);
+			if (!col.types.includes(found.data_type)) throw new Error(`@kyneta/postgres-store: table "${tableName}" column "${col.name}" has type "${found.data_type}", expected one of [${col.types.join(", ")}].`);
+		}
+	}
+}
+//#endregion
+export { PostgresStore, createPostgresStore };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["#client","#seqNos","#tables","#withTransaction","#q"],"sources":["../src/index.ts"],"sourcesContent":["// Postgres Store backend.\n//\n// Why JSONB on meta, not TEXT: operators occasionally need to filter\n// metas by `syncProtocol` or `replicaType` during incident\n// investigations, and JSONB makes `data->>'syncProtocol'` trivial.\n// Cost: JSONB normalizes whitespace and key order at insert time, so\n// `meta.data` bytes don't match SQLite's TEXT-stored meta — but\n// round-trip through `loadAll` still yields a structurally equal\n// `StoreRecord`, which is what cross-backend portability actually\n// requires.\n\nimport {\n  type DocId,\n  SeqNoTracker,\n  type Store,\n  type StoreMeta,\n  type StoreRecord,\n} from \"@kyneta/exchange\"\nimport {\n  fromRow,\n  planAppend,\n  planReplace,\n  type RowShape,\n  resolveTables,\n  type TableNames,\n} from \"@kyneta/sql-store-core\"\nimport type { Client, Pool, PoolClient } from \"pg\"\n\n// ---------------------------------------------------------------------------\n// Options\n// ---------------------------------------------------------------------------\n\nexport interface PostgresStoreOptions {\n  /**\n   * Override the default table names (`kyneta_meta` and `kyneta_records`).\n   *\n   * Use when running multiple isolated Exchange instances against the\n   * same database — each instance owns one `tables` pair.\n   */\n  tables?: Partial<TableNames>\n}\n\ntype PgConnection = Client | Pool\n\n/**\n * Narrow structural type for the methods we actually call. Keeps the\n * package independent of `pg`'s top-level type changes across versions.\n */\ninterface PgQuerier {\n  query<R = unknown>(text: string, values?: unknown[]): Promise<{ rows: R[] }>\n}\n\n// ---------------------------------------------------------------------------\n// PostgresStore\n// ---------------------------------------------------------------------------\n\n/**\n * Caller owns the connection lifecycle — `close()` is a no-op,\n * `pool.end()` is the caller's responsibility. Prefer\n * `createPostgresStore` over the bare constructor: it validates the\n * schema at construction time so misconfiguration fails loudly with a\n * curated error rather than per-method `column does not exist` later.\n */\nexport class PostgresStore implements Store {\n  readonly #client: PgConnection\n  readonly #seqNos = new SeqNoTracker()\n  readonly #tables: TableNames\n\n  constructor(client: PgConnection, options: PostgresStoreOptions = {}) {\n    this.#client = client\n    this.#tables = resolveTables(options)\n  }\n\n  /**\n   * For `Pool`: check out a `PoolClient` so BEGIN..COMMIT all run on\n   * the same physical connection (Postgres transactions are\n   * connection-scoped; checking back out for COMMIT would target a\n   * different connection). For `Client`: run inline.\n   *\n   * Re-throws on rollback so callers can put post-commit work\n   * lexically after the awaited call — a rejection skips the next\n   * statement, mirroring sync `transaction()` + throw.\n   */\n  async #withTransaction<R>(\n    fn: (querier: PgQuerier) => Promise<R>,\n  ): Promise<R> {\n    const isPool = typeof (this.#client as Pool).connect === \"function\"\n    if (isPool) {\n      const poolClient: PoolClient = await (this.#client as Pool).connect()\n      try {\n        await poolClient.query(\"BEGIN\")\n        try {\n          const result = await fn(poolClient as unknown as PgQuerier)\n          await poolClient.query(\"COMMIT\")\n          return result\n        } catch (e) {\n          await poolClient.query(\"ROLLBACK\")\n          throw e\n        }\n      } finally {\n        poolClient.release()\n      }\n    }\n    const client = this.#client as Client\n    await client.query(\"BEGIN\")\n    try {\n      const result = await fn(client as unknown as PgQuerier)\n      await client.query(\"COMMIT\")\n      return result\n    } catch (e) {\n      await client.query(\"ROLLBACK\")\n      throw e\n    }\n  }\n\n  // Non-transactional reads (currentMeta, loadAll, listDocIds, the\n  // cold-start MAX(seq)) don't need a held connection — issuing them\n  // against the pool/client directly avoids unnecessary checkouts.\n  get #q(): PgQuerier {\n    return this.#client as unknown as PgQuerier\n  }\n\n  // -------------------------------------------------------------------------\n  // Store interface\n  // -------------------------------------------------------------------------\n\n  async append(docId: DocId, record: StoreRecord): Promise<void> {\n    const existingMeta = await this.currentMeta(docId)\n    const seq = await this.#seqNos.next(docId, async () => {\n      const result = await this.#q.query<{ max_seq: number | null }>(\n        `SELECT MAX(seq)::int AS max_seq FROM ${this.#tables.records} WHERE doc_id = $1`,\n        [docId],\n      )\n      return result.rows[0]?.max_seq ?? null\n    })\n\n    const plan = planAppend(docId, record, existingMeta, seq)\n\n    await this.#withTransaction(async q => {\n      if (plan.upsertMeta !== null) {\n        await q.query(\n          `INSERT INTO ${this.#tables.meta} (doc_id, data)\n           VALUES ($1, $2::jsonb)\n           ON CONFLICT (doc_id) DO UPDATE SET data = EXCLUDED.data`,\n          [docId, plan.upsertMeta.data],\n        )\n      }\n      const { row } = plan.insertRecord\n      await q.query(\n        `INSERT INTO ${this.#tables.records}\n         (doc_id, seq, kind, payload, blob)\n         VALUES ($1, $2, $3, $4, $5)`,\n        [docId, plan.insertRecord.seq, row.kind, row.payload, row.blob],\n      )\n    })\n  }\n\n  async *loadAll(docId: DocId): AsyncIterable<StoreRecord> {\n    const result = await this.#q.query<RowShape>(\n      `SELECT kind, payload, blob FROM ${this.#tables.records}\n       WHERE doc_id = $1 ORDER BY seq`,\n      [docId],\n    )\n    for (const row of result.rows) {\n      yield fromRow(row)\n    }\n  }\n\n  async replace(docId: DocId, records: StoreRecord[]): Promise<void> {\n    const existingMeta = await this.currentMeta(docId)\n    const plan = planReplace(records, existingMeta)\n\n    await this.#withTransaction(async q => {\n      await q.query(`DELETE FROM ${this.#tables.records} WHERE doc_id = $1`, [\n        docId,\n      ])\n\n      for (const { seq, row } of plan.records) {\n        await q.query(\n          `INSERT INTO ${this.#tables.records}\n           (doc_id, seq, kind, payload, blob)\n           VALUES ($1, $2, $3, $4, $5)`,\n          [docId, seq, row.kind, row.payload, row.blob],\n        )\n      }\n\n      await q.query(\n        `INSERT INTO ${this.#tables.meta} (doc_id, data)\n         VALUES ($1, $2::jsonb)\n         ON CONFLICT (doc_id) DO UPDATE SET data = EXCLUDED.data`,\n        [docId, plan.upsertMeta.data],\n      )\n    })\n\n    // Must run after commit. If `#withTransaction` rejects, the throw\n    // propagates past this line; the cache stays unmutated. Inside the\n    // callback would corrupt it on rollback — the next append would\n    // collide with restored rows on (doc_id, seq).\n    this.#seqNos.reset(docId, records.length - 1)\n  }\n\n  async delete(docId: DocId): Promise<void> {\n    await this.#withTransaction(async q => {\n      await q.query(`DELETE FROM ${this.#tables.records} WHERE doc_id = $1`, [\n        docId,\n      ])\n      await q.query(`DELETE FROM ${this.#tables.meta} WHERE doc_id = $1`, [\n        docId,\n      ])\n    })\n    this.#seqNos.remove(docId)\n  }\n\n  async currentMeta(docId: DocId): Promise<StoreMeta | null> {\n    const result = await this.#q.query<{ data: StoreMeta }>(\n      `SELECT data FROM ${this.#tables.meta} WHERE doc_id = $1`,\n      [docId],\n    )\n    return result.rows[0]?.data ?? null\n  }\n\n  async *listDocIds(prefix?: string): AsyncIterable<DocId> {\n    if (prefix === undefined) {\n      const result = await this.#q.query<{ doc_id: string }>(\n        `SELECT doc_id FROM ${this.#tables.meta}`,\n      )\n      for (const row of result.rows) yield row.doc_id\n      return\n    }\n\n    // Range scan instead of LIKE — `%` and `_` in doc IDs are literal,\n    // not wildcards.\n    const upper = prefixUpperBound(prefix)\n    const result =\n      upper === null\n        ? await this.#q.query<{ doc_id: string }>(\n            `SELECT doc_id FROM ${this.#tables.meta} WHERE doc_id >= $1`,\n            [prefix],\n          )\n        : await this.#q.query<{ doc_id: string }>(\n            `SELECT doc_id FROM ${this.#tables.meta}\n             WHERE doc_id >= $1 AND doc_id < $2`,\n            [prefix, upper],\n          )\n    for (const row of result.rows) yield row.doc_id\n  }\n\n  async close(): Promise<void> {\n    // Caller calls `pool.end()` / `client.end()`.\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Range-scan helper\n// ---------------------------------------------------------------------------\n\n/**\n * Returns null when no successor exists (e.g. all code units at U+10FFFF),\n * letting the caller fall back to an unbounded `>= prefix` scan.\n */\nfunction prefixUpperBound(prefix: string): string | null {\n  if (prefix.length === 0) return null\n  const codes = Array.from(prefix)\n  for (let i = codes.length - 1; i >= 0; i--) {\n    const ch = codes[i] as string\n    const code = ch.codePointAt(0) as number\n    if (code < 0x10ffff) {\n      const next = String.fromCodePoint(code + 1)\n      return codes.slice(0, i).join(\"\") + next\n    }\n  }\n  return null\n}\n\n// ---------------------------------------------------------------------------\n// Factory: createPostgresStore (recommended entry point)\n// ---------------------------------------------------------------------------\n\n/**\n * Validation runs once at factory time, not on every method call. A\n * schema change applied while the Exchange is running won't be\n * detected — restart after migrations. Polling or a `revalidate()`\n * API would be over-engineering for a failure mode that fails loudly\n * on the next write anyway.\n */\nexport async function createPostgresStore(\n  client: PgConnection,\n  options: PostgresStoreOptions = {},\n): Promise<Store> {\n  const tables = resolveTables(options)\n  await validateSchema(client as unknown as PgQuerier, tables)\n  return new PostgresStore(client, options)\n}\n\ninterface ColumnInfo {\n  column_name: string\n  data_type: string\n  is_nullable: string\n}\n\nconst EXPECTED_COLUMNS = {\n  meta: [\n    { name: \"doc_id\", types: [\"text\"] },\n    { name: \"data\", types: [\"jsonb\"] },\n  ],\n  records: [\n    { name: \"doc_id\", types: [\"text\"] },\n    { name: \"seq\", types: [\"integer\"] },\n    { name: \"kind\", types: [\"text\"] },\n    { name: \"payload\", types: [\"text\"] },\n    { name: \"blob\", types: [\"bytea\"] },\n  ],\n} as const\n\nasync function validateSchema(q: PgQuerier, tables: TableNames): Promise<void> {\n  for (const [role, expected] of [\n    [\"meta\", EXPECTED_COLUMNS.meta] as const,\n    [\"records\", EXPECTED_COLUMNS.records] as const,\n  ]) {\n    const tableName = tables[role]\n    const result = await q.query<ColumnInfo>(\n      `SELECT column_name, data_type, is_nullable\n       FROM information_schema.columns\n       WHERE table_name = $1`,\n      [tableName],\n    )\n    if (result.rows.length === 0) {\n      throw new Error(\n        `@kyneta/postgres-store: table \"${tableName}\" not found. ` +\n          `Run schema.sql or include the canonical DDL in your migrations.`,\n      )\n    }\n    const columnsByName = new Map(result.rows.map(r => [r.column_name, r]))\n    for (const col of expected) {\n      const found = columnsByName.get(col.name)\n      if (found === undefined) {\n        throw new Error(\n          `@kyneta/postgres-store: table \"${tableName}\" missing column ` +\n            `\"${col.name}\". See schema.sql for the canonical definition.`,\n        )\n      }\n      if (!(col.types as readonly string[]).includes(found.data_type)) {\n        throw new Error(\n          `@kyneta/postgres-store: table \"${tableName}\" column ` +\n            `\"${col.name}\" has type \"${found.data_type}\", ` +\n            `expected one of [${col.types.join(\", \")}].`,\n        )\n      }\n    }\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@kyneta/postgres-store",
+  "version": "1.5.0",
+  "description": "Postgres storage backend for @kyneta/exchange",
+  "author": "Duane Johnson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/halecraft/kyneta",
+    "directory": "packages/exchange/stores/postgres"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "schema.sql"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./src": "./src/index.ts",
+    "./src/*": "./src/*",
+    "./schema.sql": "./schema.sql"
+  },
+  "peerDependencies": {
+    "@kyneta/exchange": "^1.5.0",
+    "@kyneta/schema": "^1.5.0",
+    "@kyneta/sql-store-core": "^1.5.0",
+    "pg": "^8.11.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "@types/pg": "^8.11.0",
+    "pg": "^8.13.0",
+    "tsdown": "^0.21.9",
+    "typescript": "^5.9.2",
+    "vitest": "^4.0.17",
+    "@kyneta/exchange": "^1.5.0",
+    "@kyneta/sql-store-core": "^1.5.0",
+    "@kyneta/schema": "^1.5.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "verify logic",
+    "verify": "verify"
+  }
+}

package/schema.sql

@@ -0,0 +1,23 @@
+-- @kyneta/postgres-store — canonical schema.
+--
+-- Run this once before constructing a `PostgresStore`, or include it
+-- as a migration step in your application's migration pipeline. The
+-- `createPostgresStore` factory validates that these tables exist with
+-- the expected columns; it does not auto-DDL.
+--
+-- Default table names. To use different names, override via the
+-- `tables` option and replace the names below to match.
+
+CREATE TABLE IF NOT EXISTS kyneta_meta (
+  doc_id TEXT  PRIMARY KEY,
+  data   JSONB NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS kyneta_records (
+  doc_id  TEXT    NOT NULL,
+  seq     INTEGER NOT NULL,
+  kind    TEXT    NOT NULL,
+  payload TEXT,
+  blob    BYTEA,
+  PRIMARY KEY (doc_id, seq)
+);

package/src/__tests__/postgres-store.test.ts

@@ -0,0 +1,243 @@
+// postgres-store — conformance + Postgres-specific tests.
+//
+// Gated by the `KYNETA_PG_URL` env var. When unset, the entire suite
+// is skipped (the package still builds and typechecks). Set
+// `KYNETA_PG_URL=postgres://localhost:5432/kyneta_test` (or similar)
+// to run.
+
+import { describeStore, makeMetaRecord } from "@kyneta/exchange/testing"
+import { Pool } from "pg"
+import { afterAll, beforeAll, describe, expect, it } from "vitest"
+import { createPostgresStore, PostgresStore } from "../index.js"
+
+const PG_URL = process.env.KYNETA_PG_URL
+const ENABLED = PG_URL !== undefined && PG_URL.length > 0
+
+const pool: Pool | null = ENABLED
+  ? new Pool({ connectionString: PG_URL })
+  : null
+
+// Per-test schema namespace via per-test table names. Truncate between
+// tests via DELETE on the canonical tables for the conformance run.
+const SCHEMA_TABLES = {
+  meta: "kyneta_meta",
+  records: "kyneta_records",
+} as const
+
+const SCHEMA_DDL = `
+  CREATE TABLE IF NOT EXISTS ${SCHEMA_TABLES.meta} (
+    doc_id TEXT  PRIMARY KEY,
+    data   JSONB NOT NULL
+  );
+  CREATE TABLE IF NOT EXISTS ${SCHEMA_TABLES.records} (
+    doc_id  TEXT    NOT NULL,
+    seq     INTEGER NOT NULL,
+    kind    TEXT    NOT NULL,
+    payload TEXT,
+    blob    BYTEA,
+    PRIMARY KEY (doc_id, seq)
+  );
+`
+
+if (ENABLED && pool !== null) {
+  beforeAll(async () => {
+    await pool.query(SCHEMA_DDL)
+  })
+
+  afterAll(async () => {
+    await pool.end()
+  })
+}
+
+const describeIfEnabled = ENABLED ? describe : describe.skip
+
+describeIfEnabled("PostgresStore", () => {
+  if (!ENABLED || pool === null) return
+
+  // -------------------------------------------------------------------------
+  // Conformance suite — uses canonical tables + per-test truncation
+  // -------------------------------------------------------------------------
+
+  describeStore(
+    "PostgresStore",
+    async () => {
+      // Truncate before each test for a clean slate.
+      await pool.query(
+        `TRUNCATE ${SCHEMA_TABLES.records}, ${SCHEMA_TABLES.meta}`,
+      )
+      return new PostgresStore(pool)
+    },
+    {
+      cleanup: async () => {
+        await pool.query(
+          `TRUNCATE ${SCHEMA_TABLES.records}, ${SCHEMA_TABLES.meta}`,
+        )
+      },
+      faultFactory: async () => {
+        await pool.query(
+          `TRUNCATE ${SCHEMA_TABLES.records}, ${SCHEMA_TABLES.meta}`,
+        )
+        // Wrap a single connection (not the pool) so we can intercept
+        // its `query` method to inject failures. The faulty store uses
+        // a Client-shaped wrapper; the fresh store uses a fresh client
+        // checked out from the pool.
+        const client = await pool.connect()
+        // Forward all queries except after arming, when the Nth post-arm
+        // call throws. Schema DDL ran in beforeAll, so we don't need to
+        // protect those calls.
+        let armed: number | null = null
+        let count = 0
+        const realQuery = client.query.bind(client) as (
+          ...args: unknown[]
+        ) => Promise<unknown>
+        const wrappedClient = {
+          query: ((...args: unknown[]) => {
+            if (armed !== null) {
+              count += 1
+              if (count === armed) {
+                return Promise.reject(
+                  new Error(`fault-injected: query call #${count}`),
+                )
+              }
+            }
+            return realQuery(...args)
+          }) as typeof client.query,
+          // Pretend to be a Client (no .connect method).
+        } as unknown as ConstructorParameters<typeof PostgresStore>[0]
+
+        const store = new PostgresStore(wrappedClient)
+
+        return {
+          store,
+          injectFault: n => {
+            armed = n
+            count = 0
+          },
+          freshStore: async () => new PostgresStore(pool),
+          cleanup: async () => {
+            client.release()
+          },
+        }
+      },
+      isolationFactory: async () => {
+        // Two distinct table-name pairs sharing the same Pool.
+        const tablesA = { meta: "iso_a_meta", records: "iso_a_records" }
+        const tablesB = { meta: "iso_b_meta", records: "iso_b_records" }
+        await pool.query(`
+          CREATE TABLE IF NOT EXISTS ${tablesA.meta} (
+            doc_id TEXT PRIMARY KEY, data JSONB NOT NULL
+          );
+          CREATE TABLE IF NOT EXISTS ${tablesA.records} (
+            doc_id TEXT, seq INTEGER, kind TEXT, payload TEXT, blob BYTEA,
+            PRIMARY KEY (doc_id, seq)
+          );
+          CREATE TABLE IF NOT EXISTS ${tablesB.meta} (
+            doc_id TEXT PRIMARY KEY, data JSONB NOT NULL
+          );
+          CREATE TABLE IF NOT EXISTS ${tablesB.records} (
+            doc_id TEXT, seq INTEGER, kind TEXT, payload TEXT, blob BYTEA,
+            PRIMARY KEY (doc_id, seq)
+          );
+          TRUNCATE ${tablesA.records}, ${tablesA.meta},
+                   ${tablesB.records}, ${tablesB.meta};
+        `)
+        return {
+          storeA: new PostgresStore(pool, { tables: tablesA }),
+          storeB: new PostgresStore(pool, { tables: tablesB }),
+          cleanup: async () => {
+            await pool.query(`
+              DROP TABLE IF EXISTS ${tablesA.records};
+              DROP TABLE IF EXISTS ${tablesA.meta};
+              DROP TABLE IF EXISTS ${tablesB.records};
+              DROP TABLE IF EXISTS ${tablesB.meta};
+            `)
+          },
+        }
+      },
+    },
+  )
+
+  // -------------------------------------------------------------------------
+  // Postgres-specific: createPostgresStore validation
+  // -------------------------------------------------------------------------
+
+  describe("createPostgresStore — schema validation", () => {
+    it("rejects when meta table is missing", async () => {
+      await expect(
+        createPostgresStore(pool, {
+          tables: { meta: "nonexistent_meta", records: "kyneta_records" },
+        }),
+      ).rejects.toThrow(/nonexistent_meta/)
+    })
+
+    it("rejects when records table is missing", async () => {
+      await expect(
+        createPostgresStore(pool, {
+          tables: { meta: "kyneta_meta", records: "nonexistent_records" },
+        }),
+      ).rejects.toThrow(/nonexistent_records/)
+    })
+
+    it("returns a ready Store when schema is valid", async () => {
+      const store = await createPostgresStore(pool)
+      expect(store).toBeDefined()
+      await store.close()
+    })
+
+    it("rejects when a column has the wrong type", async () => {
+      const tables = {
+        meta: "wrongtype_meta",
+        records: "wrongtype_records",
+      }
+      await pool.query(`
+        DROP TABLE IF EXISTS ${tables.records};
+        DROP TABLE IF EXISTS ${tables.meta};
+        CREATE TABLE ${tables.meta} (
+          doc_id TEXT PRIMARY KEY, data TEXT NOT NULL
+        );
+        CREATE TABLE ${tables.records} (
+          doc_id TEXT, seq INTEGER, kind TEXT, payload TEXT, blob BYTEA,
+          PRIMARY KEY (doc_id, seq)
+        );
+      `)
+      try {
+        await expect(createPostgresStore(pool, { tables })).rejects.toThrow(
+          /data.*type "text"/,
+        )
+      } finally {
+        await pool.query(`
+          DROP TABLE IF EXISTS ${tables.records};
+          DROP TABLE IF EXISTS ${tables.meta};
+        `)
+      }
+    })
+  })
+
+  // -------------------------------------------------------------------------
+  // Postgres-specific: range-scan correctness
+  // -------------------------------------------------------------------------
+
+  describe("listDocIds — range scan vs LIKE-pattern hazards", () => {
+    it("prefix containing % and _ matches literally, not as wildcards", async () => {
+      await pool.query(
+        `TRUNCATE ${SCHEMA_TABLES.records}, ${SCHEMA_TABLES.meta}`,
+      )
+      const store = new PostgresStore(pool)
+
+      await store.append("100%_done", makeMetaRecord())
+      await store.append("100_other", makeMetaRecord())
+      await store.append("100xyz", makeMetaRecord())
+      await store.append("other", makeMetaRecord())
+
+      // "100%" must match only "100%_done" — NOT "100_other" / "100xyz"
+      const matched: string[] = []
+      for await (const id of store.listDocIds("100%")) matched.push(id)
+      expect(matched).toEqual(["100%_done"])
+
+      // "100_" must match only "100_other"
+      const matched2: string[] = []
+      for await (const id of store.listDocIds("100_")) matched2.push(id)
+      expect(matched2).toEqual(["100_other"])
+    })
+  })
+})

package/src/index.ts

@@ -0,0 +1,351 @@
+// Postgres Store backend.
+//
+// Why JSONB on meta, not TEXT: operators occasionally need to filter
+// metas by `syncProtocol` or `replicaType` during incident
+// investigations, and JSONB makes `data->>'syncProtocol'` trivial.
+// Cost: JSONB normalizes whitespace and key order at insert time, so
+// `meta.data` bytes don't match SQLite's TEXT-stored meta — but
+// round-trip through `loadAll` still yields a structurally equal
+// `StoreRecord`, which is what cross-backend portability actually
+// requires.
+
+import {
+  type DocId,
+  SeqNoTracker,
+  type Store,
+  type StoreMeta,
+  type StoreRecord,
+} from "@kyneta/exchange"
+import {
+  fromRow,
+  planAppend,
+  planReplace,
+  type RowShape,
+  resolveTables,
+  type TableNames,
+} from "@kyneta/sql-store-core"
+import type { Client, Pool, PoolClient } from "pg"
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+export interface PostgresStoreOptions {
+  /**
+   * Override the default table names (`kyneta_meta` and `kyneta_records`).
+   *
+   * Use when running multiple isolated Exchange instances against the
+   * same database — each instance owns one `tables` pair.
+   */
+  tables?: Partial<TableNames>
+}
+
+type PgConnection = Client | Pool
+
+/**
+ * Narrow structural type for the methods we actually call. Keeps the
+ * package independent of `pg`'s top-level type changes across versions.
+ */
+interface PgQuerier {
+  query<R = unknown>(text: string, values?: unknown[]): Promise<{ rows: R[] }>
+}
+
+// ---------------------------------------------------------------------------
+// PostgresStore
+// ---------------------------------------------------------------------------
+
+/**
+ * Caller owns the connection lifecycle — `close()` is a no-op,
+ * `pool.end()` is the caller's responsibility. Prefer
+ * `createPostgresStore` over the bare constructor: it validates the
+ * schema at construction time so misconfiguration fails loudly with a
+ * curated error rather than per-method `column does not exist` later.
+ */
+export class PostgresStore implements Store {
+  readonly #client: PgConnection
+  readonly #seqNos = new SeqNoTracker()
+  readonly #tables: TableNames
+
+  constructor(client: PgConnection, options: PostgresStoreOptions = {}) {
+    this.#client = client
+    this.#tables = resolveTables(options)
+  }
+
+  /**
+   * For `Pool`: check out a `PoolClient` so BEGIN..COMMIT all run on
+   * the same physical connection (Postgres transactions are
+   * connection-scoped; checking back out for COMMIT would target a
+   * different connection). For `Client`: run inline.
+   *
+   * Re-throws on rollback so callers can put post-commit work
+   * lexically after the awaited call — a rejection skips the next
+   * statement, mirroring sync `transaction()` + throw.
+   */
+  async #withTransaction<R>(
+    fn: (querier: PgQuerier) => Promise<R>,
+  ): Promise<R> {
+    const isPool = typeof (this.#client as Pool).connect === "function"
+    if (isPool) {
+      const poolClient: PoolClient = await (this.#client as Pool).connect()
+      try {
+        await poolClient.query("BEGIN")
+        try {
+          const result = await fn(poolClient as unknown as PgQuerier)
+          await poolClient.query("COMMIT")
+          return result
+        } catch (e) {
+          await poolClient.query("ROLLBACK")
+          throw e
+        }
+      } finally {
+        poolClient.release()
+      }
+    }
+    const client = this.#client as Client
+    await client.query("BEGIN")
+    try {
+      const result = await fn(client as unknown as PgQuerier)
+      await client.query("COMMIT")
+      return result
+    } catch (e) {
+      await client.query("ROLLBACK")
+      throw e
+    }
+  }
+
+  // Non-transactional reads (currentMeta, loadAll, listDocIds, the
+  // cold-start MAX(seq)) don't need a held connection — issuing them
+  // against the pool/client directly avoids unnecessary checkouts.
+  get #q(): PgQuerier {
+    return this.#client as unknown as PgQuerier
+  }
+
+  // -------------------------------------------------------------------------
+  // Store interface
+  // -------------------------------------------------------------------------
+
+  async append(docId: DocId, record: StoreRecord): Promise<void> {
+    const existingMeta = await this.currentMeta(docId)
+    const seq = await this.#seqNos.next(docId, async () => {
+      const result = await this.#q.query<{ max_seq: number | null }>(
+        `SELECT MAX(seq)::int AS max_seq FROM ${this.#tables.records} WHERE doc_id = $1`,
+        [docId],
+      )
+      return result.rows[0]?.max_seq ?? null
+    })
+
+    const plan = planAppend(docId, record, existingMeta, seq)
+
+    await this.#withTransaction(async q => {
+      if (plan.upsertMeta !== null) {
+        await q.query(
+          `INSERT INTO ${this.#tables.meta} (doc_id, data)
+           VALUES ($1, $2::jsonb)
+           ON CONFLICT (doc_id) DO UPDATE SET data = EXCLUDED.data`,
+          [docId, plan.upsertMeta.data],
+        )
+      }
+      const { row } = plan.insertRecord
+      await q.query(
+        `INSERT INTO ${this.#tables.records}
+         (doc_id, seq, kind, payload, blob)
+         VALUES ($1, $2, $3, $4, $5)`,
+        [docId, plan.insertRecord.seq, row.kind, row.payload, row.blob],
+      )
+    })
+  }
+
+  async *loadAll(docId: DocId): AsyncIterable<StoreRecord> {
+    const result = await this.#q.query<RowShape>(
+      `SELECT kind, payload, blob FROM ${this.#tables.records}
+       WHERE doc_id = $1 ORDER BY seq`,
+      [docId],
+    )
+    for (const row of result.rows) {
+      yield fromRow(row)
+    }
+  }
+
+  async replace(docId: DocId, records: StoreRecord[]): Promise<void> {
+    const existingMeta = await this.currentMeta(docId)
+    const plan = planReplace(records, existingMeta)
+
+    await this.#withTransaction(async q => {
+      await q.query(`DELETE FROM ${this.#tables.records} WHERE doc_id = $1`, [
+        docId,
+      ])
+
+      for (const { seq, row } of plan.records) {
+        await q.query(
+          `INSERT INTO ${this.#tables.records}
+           (doc_id, seq, kind, payload, blob)
+           VALUES ($1, $2, $3, $4, $5)`,
+          [docId, seq, row.kind, row.payload, row.blob],
+        )
+      }
+
+      await q.query(
+        `INSERT INTO ${this.#tables.meta} (doc_id, data)
+         VALUES ($1, $2::jsonb)
+         ON CONFLICT (doc_id) DO UPDATE SET data = EXCLUDED.data`,
+        [docId, plan.upsertMeta.data],
+      )
+    })
+
+    // Must run after commit. If `#withTransaction` rejects, the throw
+    // propagates past this line; the cache stays unmutated. Inside the
+    // callback would corrupt it on rollback — the next append would
+    // collide with restored rows on (doc_id, seq).
+    this.#seqNos.reset(docId, records.length - 1)
+  }
+
+  async delete(docId: DocId): Promise<void> {
+    await this.#withTransaction(async q => {
+      await q.query(`DELETE FROM ${this.#tables.records} WHERE doc_id = $1`, [
+        docId,
+      ])
+      await q.query(`DELETE FROM ${this.#tables.meta} WHERE doc_id = $1`, [
+        docId,
+      ])
+    })
+    this.#seqNos.remove(docId)
+  }
+
+  async currentMeta(docId: DocId): Promise<StoreMeta | null> {
+    const result = await this.#q.query<{ data: StoreMeta }>(
+      `SELECT data FROM ${this.#tables.meta} WHERE doc_id = $1`,
+      [docId],
+    )
+    return result.rows[0]?.data ?? null
+  }
+
+  async *listDocIds(prefix?: string): AsyncIterable<DocId> {
+    if (prefix === undefined) {
+      const result = await this.#q.query<{ doc_id: string }>(
+        `SELECT doc_id FROM ${this.#tables.meta}`,
+      )
+      for (const row of result.rows) yield row.doc_id
+      return
+    }
+
+    // Range scan instead of LIKE — `%` and `_` in doc IDs are literal,
+    // not wildcards.
+    const upper = prefixUpperBound(prefix)
+    const result =
+      upper === null
+        ? await this.#q.query<{ doc_id: string }>(
+            `SELECT doc_id FROM ${this.#tables.meta} WHERE doc_id >= $1`,
+            [prefix],
+          )
+        : await this.#q.query<{ doc_id: string }>(
+            `SELECT doc_id FROM ${this.#tables.meta}
+             WHERE doc_id >= $1 AND doc_id < $2`,
+            [prefix, upper],
+          )
+    for (const row of result.rows) yield row.doc_id
+  }
+
+  async close(): Promise<void> {
+    // Caller calls `pool.end()` / `client.end()`.
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Range-scan helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns null when no successor exists (e.g. all code units at U+10FFFF),
+ * letting the caller fall back to an unbounded `>= prefix` scan.
+ */
+function prefixUpperBound(prefix: string): string | null {
+  if (prefix.length === 0) return null
+  const codes = Array.from(prefix)
+  for (let i = codes.length - 1; i >= 0; i--) {
+    const ch = codes[i] as string
+    const code = ch.codePointAt(0) as number
+    if (code < 0x10ffff) {
+      const next = String.fromCodePoint(code + 1)
+      return codes.slice(0, i).join("") + next
+    }
+  }
+  return null
+}
+
+// ---------------------------------------------------------------------------
+// Factory: createPostgresStore (recommended entry point)
+// ---------------------------------------------------------------------------
+
+/**
+ * Validation runs once at factory time, not on every method call. A
+ * schema change applied while the Exchange is running won't be
+ * detected — restart after migrations. Polling or a `revalidate()`
+ * API would be over-engineering for a failure mode that fails loudly
+ * on the next write anyway.
+ */
+export async function createPostgresStore(
+  client: PgConnection,
+  options: PostgresStoreOptions = {},
+): Promise<Store> {
+  const tables = resolveTables(options)
+  await validateSchema(client as unknown as PgQuerier, tables)
+  return new PostgresStore(client, options)
+}
+
+interface ColumnInfo {
+  column_name: string
+  data_type: string
+  is_nullable: string
+}
+
+const EXPECTED_COLUMNS = {
+  meta: [
+    { name: "doc_id", types: ["text"] },
+    { name: "data", types: ["jsonb"] },
+  ],
+  records: [
+    { name: "doc_id", types: ["text"] },
+    { name: "seq", types: ["integer"] },
+    { name: "kind", types: ["text"] },
+    { name: "payload", types: ["text"] },
+    { name: "blob", types: ["bytea"] },
+  ],
+} as const
+
+async function validateSchema(q: PgQuerier, tables: TableNames): Promise<void> {
+  for (const [role, expected] of [
+    ["meta", EXPECTED_COLUMNS.meta] as const,
+    ["records", EXPECTED_COLUMNS.records] as const,
+  ]) {
+    const tableName = tables[role]
+    const result = await q.query<ColumnInfo>(
+      `SELECT column_name, data_type, is_nullable
+       FROM information_schema.columns
+       WHERE table_name = $1`,
+      [tableName],
+    )
+    if (result.rows.length === 0) {
+      throw new Error(
+        `@kyneta/postgres-store: table "${tableName}" not found. ` +
+          `Run schema.sql or include the canonical DDL in your migrations.`,
+      )
+    }
+    const columnsByName = new Map(result.rows.map(r => [r.column_name, r]))
+    for (const col of expected) {
+      const found = columnsByName.get(col.name)
+      if (found === undefined) {
+        throw new Error(
+          `@kyneta/postgres-store: table "${tableName}" missing column ` +
+            `"${col.name}". See schema.sql for the canonical definition.`,
+        )
+      }
+      if (!(col.types as readonly string[]).includes(found.data_type)) {
+        throw new Error(
+          `@kyneta/postgres-store: table "${tableName}" column ` +
+            `"${col.name}" has type "${found.data_type}", ` +
+            `expected one of [${col.types.join(", ")}].`,
+        )
+      }
+    }
+  }
+}