@kronos-ts/postgres 0.1.0

package/README.md

@@ -0,0 +1,176 @@
+# @kronos-ts/postgres
+
+First-party Postgres extension for Kronos. Provides DCB-compliant event storage and snapshots via the framework's `eventStore` + `snapshotStore` slots.
+
+## Install
+
+```bash
+bun add @kronos-ts/postgres
+# Choose one driver:
+bun add pg                 # for pgAdapter (Node + Bun)
+bun add postgres           # for postgresAdapter (porsager — Node + Bun)
+# bunSqlAdapter has no external dep (uses Bun.sql built-in, requires Bun >= 1.2)
+```
+
+Requires Postgres 14+ (for `xid8` and `pg_snapshot_xmin`).
+
+## Usage
+
+```typescript
+import { kronos } from "@kronos-ts/app"
+import { postgres } from "@kronos-ts/postgres"
+import { pgAdapter } from "@kronos-ts/postgres/adapters/pg"
+
+const app = await kronos()
+  .use(postgres({
+    adapter: pgAdapter({ connectionString: "postgresql://user:pass@host/db" }),
+    // Default: auto-create schema on connect. Set false to manage migrations yourself.
+    bootstrap: true,
+  }))
+  .start()
+```
+
+### Accessing slots
+
+In normal usage you don't touch the `eventStore` directly — command handlers, `load()`, and tracking processors handle it. If you need the raw store (e.g. for tests, scripts, or low-level access), capture it via a probe decorator before `start()` — `RunningApp` doesn't expose it on its public surface:
+
+```typescript
+import type { App } from "@kronos-ts/app"
+import type { EventStore } from "@kronos-ts/eventsourcing"
+import { EventCriteria } from "@kronos-ts/messaging"
+import { tag } from "@kronos-ts/common"
+
+let eventStore: EventStore | undefined
+const capture = (a: App) => {
+  a.decorate("eventStore", (inner) => { eventStore = inner; return inner })
+}
+
+const app = await kronos()
+  .use(capture)
+  .use(postgres({ adapter: pgAdapter({ connectionString }) }))
+  .start()
+
+// 1. Source events for a state (criteria + optional start position).
+//    Returns the matched events plus a consistency marker.
+const criteria = EventCriteria.havingTags(tag("order", "123"))
+const { events: sourced, marker } = await eventStore!.source({ criteria })
+
+// 2. Append with a DCB precondition. The marker locks in the prefix you read
+//    from source() — if anything matching `criteria` was appended in the
+//    meantime, AppendConditionError is thrown.
+const newMarker = await eventStore!.append(newEvents, { criteria, marker })
+
+// 3. Tail events. open() returns a pull-based MessageStream<SequencedEvent>,
+//    not an AsyncIterable. Pull with next() and register a callback for
+//    wake-ups when more events arrive.
+const stream = eventStore!.open({ position: 0n, criteria })
+stream.setCallback(() => {
+  while (stream.hasNextAvailable()) {
+    const seq = stream.next()
+    if (!seq) break
+    // seq.event is the EventMessage; seq.sequence is the bigint position.
+  }
+})
+// remember to stream.close() when you're done
+```
+
+## Adapters
+
+Three reference adapters ship with the package:
+
+| Adapter | Runtime | Driver | LISTEN support |
+|---------|---------|--------|----------------|
+| `pgAdapter` | Node, Bun | `pg` (node-postgres) 8.20+ | native |
+| `postgresAdapter` | Node, Bun | `postgres` (porsager) 3.4+ | native |
+| `bunSqlAdapter` | Bun 1.2+ | built-in `Bun.sql` | native (1.2+) or polling shim |
+
+You can also implement your own — `PostgresAdapter` from `@kronos-ts/postgres` is the contract.
+
+### pgAdapter
+
+```typescript
+import { pgAdapter } from "@kronos-ts/postgres/adapters/pg"
+
+const adapter = pgAdapter({
+  connectionString: "postgresql://user:pass@host/db",
+  poolConfig: { max: 10 }, // optional pg.Pool overrides
+})
+```
+
+### postgresAdapter
+
+```typescript
+import { postgresAdapter } from "@kronos-ts/postgres/adapters/postgres"
+
+const adapter = postgresAdapter({
+  connectionString: "postgresql://user:pass@host/db",
+  clientOptions: { idle_timeout: 20 }, // optional porsager/postgres options
+})
+```
+
+### bunSqlAdapter
+
+```typescript
+import { bunSqlAdapter } from "@kronos-ts/postgres/adapters/bun-sql"
+
+// Bun runtime only — throws at connect() if run under Node
+const adapter = bunSqlAdapter({
+  connectionString: "postgresql://user:pass@host/db",
+})
+```
+
+## DCB Semantics
+
+The engine implements [Dynamic Consistency Boundaries](https://dcb.events):
+- **Atomic multi-tag conflict check** on append with advisory-lock serialization
+- **Criteria-based sourcing** with `@>` (contains-all) tag semantics
+- **Gap-free tailing** using `xid8` + `pg_snapshot_xmin(pg_current_snapshot())`
+
+Concurrent writers on **disjoint tags** run in parallel (advisory-lock taxonomy permits this). Concurrent writers on the **same tag** serialise — exactly one commits; the other receives `AppendConditionError`.
+
+### Gap-free streaming
+
+The `open()` streaming method uses a two-phase cursor to prevent the concurrent-commit gap bug:
+
+- **Initial fetch:** `WHERE sequence_position > $cursor AND transaction_id < pg_snapshot_xmin(pg_current_snapshot())`
+- **Subsequent fetches:** `WHERE (transaction_id, sequence_position) > ($xid, $pos) AND transaction_id < pg_snapshot_xmin(pg_current_snapshot())`
+
+The `pg_snapshot_xmin` watermark hides events from in-flight transactions, preventing the cursor from advancing past events that haven't committed yet. When a slow transaction finally commits, its events become visible in the correct xid8 order — no gaps, no re-ordering.
+
+## Schema
+
+`bootstrap: true` (default) auto-creates these tables on connect:
+- `kronos_events` — append-only event log with `xid8` watermark, BIGSERIAL position, JSONB payload, GIN index on tags
+- `kronos_snapshots` — composite-PK `(state_name, state_id)` with BYTEA payload
+
+Custom table names: `postgres({ adapter, tableNames: { events: "my_events", snapshots: "my_snaps" } })`.
+
+## SQLSTATE
+
+DCB violations raise SQLSTATE `KR001`. The adapter catches this and throws `AppendConditionError`. To detect violations from your own code:
+
+```typescript
+import { AppendConditionError } from "@kronos-ts/postgres"
+
+try {
+  await eventStore.append(events, condition)
+} catch (e) {
+  if (e instanceof AppendConditionError) {
+    // Re-source the state to get a fresh marker, then retry.
+  }
+}
+```
+
+If you're working directly against the driver (bypassing the adapter), `isDcbViolation(err)` from `@kronos-ts/postgres` inspects a raw pg / postgres.js / Bun.sql error's `.code` field for the KR001 SQLSTATE.
+
+## FAQ
+
+**Q: Can I run my own migrations?** Yes — set `bootstrap: false` and apply equivalent DDL via your own migration tooling. The reference DDL lives in `packages/extensions/postgres/src/schema.ts` (`buildEventsTableDDL`, `buildEventsIndexesDDL`, `buildSnapshotsTableDDL`).
+
+**Q: PgBouncer compatibility?** Yes — the adapter uses xact-scoped advisory locks (never session-scoped), so transaction-pooling mode is safe.
+
+**Q: Older Postgres support?** No. `xid8` requires PG14+. PG14 has been GA since 2021 and is universally supported across managed services.
+
+**Q: Is Bun.sql LISTEN available in all Bun versions?** `Bun.SQL` was introduced in Bun 1.2. The `bunSqlAdapter` feature-detects native LISTEN; if unavailable (older Bun), it falls back to a 250ms polling shim. For production streaming workloads, use Bun 1.2+ or switch to `pgAdapter` / `postgresAdapter` which always have native LISTEN.
+
+**Q: TokenStore?** Out of scope for this package. Compose with `@kronos-ts/drizzle` / `@kronos-ts/knex` / etc. for token-store needs.

package/dist/adapter.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Driver-agnostic adapter contract for @kronos-ts/postgres.
+ *
+ * Per D-12.05 the package itself has zero direct dependency on any specific
+ * Postgres client library. Engine code (Plan 04) talks to this interface;
+ * adapter implementations (pg, postgres.js, Bun.sql) live under
+ * `./adapters/*` and are imported via package sub-path exports (D-12.08).
+ *
+ * Capability coverage per D-12.07:
+ *   - query execution (parameterised)         -> query / queryOne
+ *   - transactions with isolation level       -> transaction(isolationLevel, fn)
+ *   - LISTEN-style subscription               -> listen(channel, onNotification)
+ *   - lifecycle                               -> connect / disconnect
+ *
+ * Error contract per D-12.12: SQLSTATE on thrown errors as `.code` (string).
+ * Adapter implementations MUST NOT swallow / rewrap SQLSTATE-bearing errors
+ * — the engine relies on `isDcbViolation(err)` reading `err.code === "KR001"`.
+ */
+/**
+ * Postgres isolation levels the engine actually emits. SQL string values are
+ * the verbatim Postgres syntax used after `SET TRANSACTION ISOLATION LEVEL`,
+ * so adapters can interpolate directly without a lookup table.
+ */
+export declare const IsolationLevel: {
+    readonly READ_COMMITTED: "READ COMMITTED";
+    readonly REPEATABLE_READ: "REPEATABLE READ";
+    readonly SERIALIZABLE: "SERIALIZABLE";
+};
+export type IsolationLevel = (typeof IsolationLevel)[keyof typeof IsolationLevel];
+/** Plain row shape returned by query/queryOne. Adapter implementations cast
+ *  driver-specific row objects to this. */
+export type QueryRow = Record<string, unknown>;
+/**
+ * Active in-transaction handle. Pinned to a single underlying connection so
+ * statements never interleave with sibling pool traffic. Intentionally NO
+ * nested-transaction method — Plan 04's engine does not need it and savepoints
+ * would invite confusion about which level a SQLSTATE error propagates from.
+ */
+export interface PostgresAdapterTransaction {
+    query<R extends QueryRow = QueryRow>(sql: string, params?: unknown[]): Promise<R[]>;
+}
+/** Handle to a live LISTEN subscription. unlisten() unregisters + releases
+ *  the dedicated connection (if any). */
+export interface ListenSubscription {
+    unlisten(): Promise<void>;
+}
+/**
+ * The single interface the engine layer (Plan 04+) consumes. All concurrency
+ * (pool sizing, idle eviction, reconnect) lives below this seam — the engine
+ * code MUST NOT know about pools.
+ */
+export interface PostgresAdapter {
+    /**
+     * Run a parameterised SQL statement on a pool-borrowed connection.
+     * Returns rows; empty array if none. Thrown errors carry SQLSTATE on
+     * `.code` unchanged so `isDcbViolation(err)` works at any call site.
+     */
+    query<R extends QueryRow = QueryRow>(sql: string, params?: unknown[]): Promise<R[]>;
+    /**
+     * Convenience for single-row queries. Returns `null` if zero rows.
+     * Throws if more than one row is returned (caller bug — use query()).
+     */
+    queryOne<R extends QueryRow = QueryRow>(sql: string, params?: unknown[]): Promise<R | null>;
+    /**
+     * Open a transaction at the given isolation level, run `fn` against a
+     * pinned-connection handle, and COMMIT on resolution or ROLLBACK on
+     * rejection. If `fn` throws, the original error is re-thrown after
+     * ROLLBACK; rollback failures do NOT mask the original.
+     *
+     * The framework's AppendTransaction has a synchronous `rollback(): void`
+     * (see packages/eventsourcing/src/event-storage-engine.ts) — the
+     * implementation translates that into a fire-and-forget reject inside
+     * this method's promise, NOT an awaited rollback round-trip.
+     */
+    transaction<T>(isolationLevel: IsolationLevel, fn: (tx: PostgresAdapterTransaction) => Promise<T>): Promise<T>;
+    /**
+     * Subscribe to `LISTEN <channel>` on a dedicated long-lived connection.
+     * Adapter implementations that lack a real LISTEN channel (e.g. Bun.sql
+     * pre-1.x) MAY implement a polling shim — the subscription handle is the
+     * same regardless. Plan 05's streaming open() uses this to wake up
+     * tailers immediately instead of waiting for a poll tick.
+     */
+    listen(channel: string, onNotification: (payload: string | undefined) => void): Promise<ListenSubscription>;
+    /** Initialise pool / verify reachability. Idempotent. */
+    connect(): Promise<void>;
+    /** Drain pool, close LISTEN connections, release sockets. Idempotent. */
+    disconnect(): Promise<void>;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;CAIjB,CAAA;AACV,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAA;AAEjF;2CAC2C;AAC3C,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAE9C;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,KAAK,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAA;CACpF;AAED;yCACyC;AACzC,MAAM,WAAW,kBAAkB;IACjC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,KAAK,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAA;IAEnF;;;OAGG;IACH,QAAQ,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IAE3F;;;;;;;;;;OAUG;IACH,WAAW,CAAC,CAAC,EACX,cAAc,EAAE,cAAc,EAC9B,EAAE,EAAE,CAAC,EAAE,EAAE,0BAA0B,KAAK,OAAO,CAAC,CAAC,CAAC,GACjD,OAAO,CAAC,CAAC,CAAC,CAAA;IAEb;;;;;;OAMG;IACH,MAAM,CACJ,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,GACpD,OAAO,CAAC,kBAAkB,CAAC,CAAA;IAE9B,yDAAyD;IACzD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAExB,yEAAyE;IACzE,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC5B"}

package/dist/adapter.js

@@ -0,0 +1,29 @@
+/**
+ * Driver-agnostic adapter contract for @kronos-ts/postgres.
+ *
+ * Per D-12.05 the package itself has zero direct dependency on any specific
+ * Postgres client library. Engine code (Plan 04) talks to this interface;
+ * adapter implementations (pg, postgres.js, Bun.sql) live under
+ * `./adapters/*` and are imported via package sub-path exports (D-12.08).
+ *
+ * Capability coverage per D-12.07:
+ *   - query execution (parameterised)         -> query / queryOne
+ *   - transactions with isolation level       -> transaction(isolationLevel, fn)
+ *   - LISTEN-style subscription               -> listen(channel, onNotification)
+ *   - lifecycle                               -> connect / disconnect
+ *
+ * Error contract per D-12.12: SQLSTATE on thrown errors as `.code` (string).
+ * Adapter implementations MUST NOT swallow / rewrap SQLSTATE-bearing errors
+ * — the engine relies on `isDcbViolation(err)` reading `err.code === "KR001"`.
+ */
+/**
+ * Postgres isolation levels the engine actually emits. SQL string values are
+ * the verbatim Postgres syntax used after `SET TRANSACTION ISOLATION LEVEL`,
+ * so adapters can interpolate directly without a lookup table.
+ */
+export const IsolationLevel = {
+    READ_COMMITTED: "READ COMMITTED",
+    REPEATABLE_READ: "REPEATABLE READ",
+    SERIALIZABLE: "SERIALIZABLE",
+};
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,cAAc,EAAE,gBAAgB;IAChC,eAAe,EAAE,iBAAiB;IAClC,YAAY,EAAE,cAAc;CACpB,CAAA"}

package/dist/adapters/bun-sql.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Bun.sql adapter for @kronos-ts/postgres.
+ *
+ * Import via the sub-path (Bun runtime only):
+ *   import { bunSqlAdapter } from "@kronos-ts/postgres/adapters/bun-sql"
+ *
+ * Requires Bun >= 1.2 for Bun.SQL (sql.transaction()). LISTEN support is
+ * feature-detected; if Bun.SQL lacks native LISTEN on the running version,
+ * the adapter falls back to a 250ms polling shim — slower wake-up but
+ * correct semantics.
+ *
+ * This file uses `globalThis as { Bun?: ... }` access to avoid a hard
+ * compile-time reference to Bun's global, so the package can ship under
+ * Node (where this file would never be imported) without TypeScript
+ * compilation errors. Users importing the sub-path under Node will get
+ * a clear runtime error from the connect() call.
+ */
+import type { PostgresAdapter } from "../adapter.js";
+export interface BunSqlAdapterConfig {
+    readonly connectionString: string;
+}
+export declare function bunSqlAdapter(config: BunSqlAdapterConfig): PostgresAdapter;
+//# sourceMappingURL=bun-sql.d.ts.map

package/dist/adapters/bun-sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bun-sql.d.ts","sourceRoot":"","sources":["../../src/adapters/bun-sql.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EACV,eAAe,EAIhB,MAAM,eAAe,CAAA;AAGtB,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;CAClC;AA6ED,wBAAgB,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,eAAe,CA0H1E"}

package/dist/adapters/bun-sql.js

@@ -0,0 +1,175 @@
+/**
+ * Bun.sql adapter for @kronos-ts/postgres.
+ *
+ * Import via the sub-path (Bun runtime only):
+ *   import { bunSqlAdapter } from "@kronos-ts/postgres/adapters/bun-sql"
+ *
+ * Requires Bun >= 1.2 for Bun.SQL (sql.transaction()). LISTEN support is
+ * feature-detected; if Bun.SQL lacks native LISTEN on the running version,
+ * the adapter falls back to a 250ms polling shim — slower wake-up but
+ * correct semantics.
+ *
+ * This file uses `globalThis as { Bun?: ... }` access to avoid a hard
+ * compile-time reference to Bun's global, so the package can ship under
+ * Node (where this file would never be imported) without TypeScript
+ * compilation errors. Users importing the sub-path under Node will get
+ * a clear runtime error from the connect() call.
+ */
+import { IsolationLevel } from "../adapter.js";
+/**
+ * Bun.SQL surfaces SQLSTATE in `err.errno` (not `err.code`). The adapter
+ * contract (D-12.12) requires SQLSTATE on `.code` so that `isDcbViolation(err)`
+ * works uniformly across all adapters.
+ *
+ * This helper normalises Bun.SQL errors: if `err.code === "ERR_POSTGRES_SERVER_ERROR"`
+ * and `err.errno` is a non-empty string, we copy `errno` to `code` before
+ * re-throwing, giving callers the SQLSTATE they expect on `.code`.
+ */
+/**
+ * Bun.SQL's `.unsafe(text, params)` does not auto-encode JS arrays as Postgres
+ * array literals — single-element arrays get unwrapped to their scalar value
+ * and bound as TEXT, which fails when the column is TEXT[]. We pre-encode any
+ * plain Array param to the canonical `{"v1","v2"}` literal so it round-trips
+ * to TEXT[] / array operators (`@>`, `ANY`) correctly.
+ *
+ * Uint8Array / Buffer are not plain arrays (Array.isArray returns false), so
+ * BYTEA params remain untouched.
+ */
+function encodeArrayParam(arr) {
+    const escaped = arr.map((v) => {
+        if (v === null || v === undefined)
+            return "NULL";
+        const s = String(v);
+        return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+    });
+    return `{${escaped.join(",")}}`;
+}
+function normalizeParams(params) {
+    if (!params)
+        return [];
+    return params.map((p) => (Array.isArray(p) ? encodeArrayParam(p) : p));
+}
+function normalizeBunSqlError(err) {
+    if (typeof err === "object" &&
+        err !== null &&
+        err.code === "ERR_POSTGRES_SERVER_ERROR" &&
+        typeof err.errno === "string" &&
+        err.errno.length > 0) {
+        ;
+        err.code = err.errno;
+    }
+    throw err;
+}
+function getBunSql() {
+    const g = globalThis;
+    if (!g.Bun?.SQL) {
+        throw new Error("bunSqlAdapter requires the Bun runtime with built-in Bun.SQL (>= 1.2). " +
+            "Detected non-Bun runtime — use pgAdapter or postgresAdapter instead.");
+    }
+    return g.Bun.SQL;
+}
+export function bunSqlAdapter(config) {
+    let sql;
+    let disconnected = false;
+    function getInstance() {
+        if (!sql) {
+            const SQL = getBunSql();
+            sql = new SQL({ url: config.connectionString });
+        }
+        return sql;
+    }
+    return {
+        async connect() {
+            const inst = getInstance();
+            const rows = await inst.unsafe("SELECT 1 AS ok").catch(normalizeBunSqlError);
+            if (rows[0]?.ok !== 1) {
+                throw new Error("bunSqlAdapter.connect: unexpected health-check response");
+            }
+        },
+        async disconnect() {
+            if (disconnected)
+                return;
+            disconnected = true;
+            if (sql) {
+                // Bun.SQL exposes both close() and end() — try end() first (graceful
+                // drain), fall back to close() if end is unavailable.
+                try {
+                    if (typeof sql.end === "function") {
+                        await sql.end();
+                    }
+                    else {
+                        await sql.close();
+                    }
+                }
+                catch {
+                    /* ignore disconnect errors */
+                }
+                sql = undefined;
+            }
+        },
+        async query(text, params) {
+            const inst = getInstance();
+            return inst.unsafe(text, normalizeParams(params)).catch(normalizeBunSqlError);
+        },
+        async queryOne(text, params) {
+            const rows = await this.query(text, params);
+            if (rows.length === 0)
+                return null;
+            if (rows.length > 1) {
+                throw new Error(`bunSqlAdapter.queryOne: more than one row returned (got ${rows.length}). Use query() for multi-row results.`);
+            }
+            return rows[0] ?? null;
+        },
+        async transaction(isolationLevel, fn) {
+            const inst = getInstance();
+            // Bun.SQL.begin(isolation, fn) starts a transaction at the given isolation
+            // level. The callback receives a scoped sql instance pinned to the
+            // underlying connection. SQLSTATE errors from within the transaction are
+            // normalized (errno -> code) via normalizeBunSqlError before propagating.
+            return inst.begin(`ISOLATION LEVEL ${isolationLevel}`, async (txSql) => {
+                const tx = {
+                    async query(text, params) {
+                        return txSql.unsafe(text, normalizeParams(params)).catch(normalizeBunSqlError);
+                    },
+                };
+                return fn(tx);
+            }).catch(normalizeBunSqlError);
+        },
+        async listen(channel, onNotification) {
+            if (!/^[A-Za-z0-9_]+$/.test(channel)) {
+                throw new Error(`bunSqlAdapter.listen: channel name must match /^[A-Za-z0-9_]+$/, got: ${channel}`);
+            }
+            const inst = getInstance();
+            // Feature-detect native LISTEN
+            if (typeof inst.listen === "function") {
+                const sub = await inst.listen(channel, (p) => onNotification(p || undefined));
+                return {
+                    async unlisten() {
+                        await sub.unlisten();
+                    },
+                };
+            }
+            // Polling fallback for Bun versions without native LISTEN.
+            // The fallback fires the callback on every tick with undefined payload,
+            // which causes the streaming engine to re-poll. This is coarse but
+            // semantically correct — the caller (open() in postgres-event-store.ts)
+            // already falls back to 250ms polling as a safety net, so this shim
+            // merely triggers additional pump cycles.
+            let stopped = false;
+            const tick = setInterval(() => {
+                if (stopped) {
+                    clearInterval(tick);
+                    return;
+                }
+                onNotification(undefined);
+            }, 250);
+            return {
+                async unlisten() {
+                    stopped = true;
+                    clearInterval(tick);
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=bun-sql.js.map

package/dist/adapters/bun-sql.js.map

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

package/dist/adapters/pg.d.ts

@@ -0,0 +1,24 @@
+/**
+ * pg (node-postgres 8.20+) reference adapter for @kronos-ts/postgres.
+ *
+ * Import via the sub-path:
+ *   import { pgAdapter } from "@kronos-ts/postgres/adapters/pg"
+ *
+ * Implements every PostgresAdapter method per the contract in
+ * ../adapter.ts. Pool sizing follows pg defaults; override via the
+ * `poolConfig` field if needed.
+ *
+ * LISTEN uses a dedicated long-lived PoolClient pinned outside the pool
+ * (never released) so notification delivery is not racing pool eviction.
+ * That client is closed by `disconnect()`.
+ */
+import { type PoolConfig } from "pg";
+import type { PostgresAdapter } from "../adapter.js";
+export interface PgAdapterConfig {
+    /** Standard libpq URI: postgresql://user:pass@host:port/db */
+    readonly connectionString: string;
+    /** Optional pg.Pool config overrides (max connections, idleTimeoutMillis, etc.). */
+    readonly poolConfig?: Omit<PoolConfig, "connectionString">;
+}
+export declare function pgAdapter(config: PgAdapterConfig): PostgresAdapter;
+//# sourceMappingURL=pg.d.ts.map

package/dist/adapters/pg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg.d.ts","sourceRoot":"","sources":["../../src/adapters/pg.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAyB,KAAK,UAAU,EAAE,MAAM,IAAI,CAAA;AAC3D,OAAO,KAAK,EACV,eAAe,EAIhB,MAAM,eAAe,CAAA;AAGtB,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,oFAAoF;IACpF,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,kBAAkB,CAAC,CAAA;CAC3D;AAOD,wBAAgB,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAwJlE"}