@kronos-ts/postgres 0.1.0

package/dist/errors.js

@@ -0,0 +1,41 @@
+/**
+ * SQLSTATE used by the schema-bootstrap stored procedure when a DCB
+ * append condition is violated. Per D-12.12: dedicated SQLSTATE via
+ * `RAISE ... USING ERRCODE`, never error-text parsing.
+ *
+ * `KR001` lives in the Postgres user-defined SQLSTATE range (KX–ZZ).
+ * It is intentionally distinct from:
+ *   - `P0001` — generic RAISE (would over-match any unhandled plpgsql exception)
+ *   - `23505` — unique_violation (used by primary key conflicts)
+ * Adapter layers translate `err.code === KR001` into AppendConditionError.
+ */
+export const KRONOS_DCB_VIOLATION_SQLSTATE = "KR001";
+/**
+ * Thrown when an append condition is violated — optimistic concurrency
+ * failure. Structurally mirrors `@kronos-ts/eventsourcing`'s
+ * AppendConditionError so callers that catch either get equivalent
+ * behaviour, but we ship our own class so that the SQLSTATE-catch
+ * boundary lives inside this package's import graph.
+ */
+export class AppendConditionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AppendConditionError";
+    }
+    static fromConflictCount(count, afterPosition) {
+        return new AppendConditionError(`Append condition violated: ${count} conflicting event(s) ` +
+            `found after position ${afterPosition}`);
+    }
+}
+/**
+ * Adapter-agnostic check: pg and postgres.js both surface SQLSTATE on
+ * thrown errors as `.code` (string). Bun.sql follows the same convention.
+ * This helper keeps the SQLSTATE constant centralised.
+ */
+export function isDcbViolation(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        "code" in err &&
+        err.code === KRONOS_DCB_VIOLATION_SQLSTATE);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,OAAO,CAAA;AAEpD;;;;;;GAMG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAA;IACpC,CAAC;IAED,MAAM,CAAC,iBAAiB,CAAC,KAAa,EAAE,aAAqB;QAC3D,OAAO,IAAI,oBAAoB,CAC7B,8BAA8B,KAAK,wBAAwB;YACzD,wBAAwB,aAAa,EAAE,CAC1C,CAAA;IACH,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY;IACzC,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,MAAM,IAAI,GAAG;QACZ,GAAyB,CAAC,IAAI,KAAK,6BAA6B,CAClE,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { AppendConditionError, KRONOS_DCB_VIOLATION_SQLSTATE, isDcbViolation, } from "./errors.js";
+export { IsolationLevel, type PostgresAdapter, type PostgresAdapterTransaction, type ListenSubscription, type QueryRow, } from "./adapter.js";
+export { createPostgresEventStore, type PostgresEventStoreConfig, type Serializer, type TagResolver, } from "./postgres-event-store.js";
+export { createPostgresSnapshotStore, type PostgresSnapshotStoreConfig, } from "./postgres-snapshot-store.js";
+export { postgres, type PostgresConfig } from "./postgres.js";
+export { bootstrapSchema, buildEventsTableDDL, buildEventsIndexesDDL, buildSnapshotsTableDDL, DEFAULT_TABLE_NAMES, type TableNames, } from "./schema.js";
+//# 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":"AAWA,OAAO,EACL,oBAAoB,EACpB,6BAA6B,EAC7B,cAAc,GACf,MAAM,aAAa,CAAA;AAKpB,OAAO,EACL,cAAc,EACd,KAAK,eAAe,EACpB,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,EACvB,KAAK,QAAQ,GACd,MAAM,cAAc,CAAA;AAGrB,OAAO,EACL,wBAAwB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,2BAA2B,CAAA;AAGlC,OAAO,EACL,2BAA2B,EAC3B,KAAK,2BAA2B,GACjC,MAAM,8BAA8B,CAAA;AAGrC,OAAO,EAAE,QAAQ,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAA;AAK7D,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,KAAK,UAAU,GAChB,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,26 @@
+// Public entry point for @kronos-ts/postgres.
+//
+// Wave-1 only exports the error surface; subsequent waves layer in:
+//   Plan 04 — postgres() extension factory + PostgresConfig (./postgres.js),
+//             createPostgresEventStore (./postgres-event-store.js)
+//   Plan 05 — createPostgresSnapshotStore (./postgres-snapshot-store.js)
+//
+// Adapter implementations are NOT exported from this barrel — users import
+// them via the sub-path exports declared in package.json:
+//   import { pgAdapter } from "@kronos-ts/postgres/adapters/pg"
+export { AppendConditionError, KRONOS_DCB_VIOLATION_SQLSTATE, isDcbViolation, } from "./errors.js";
+// Adapter contract types (re-export so users can write
+// `function myFn(adapter: PostgresAdapter)` against the package root).
+// Adapter implementations stay sub-path-only.
+export { IsolationLevel, } from "./adapter.js";
+// Engine factory (Plan 04 + extended in Plan 05)
+export { createPostgresEventStore, } from "./postgres-event-store.js";
+// Snapshot store factory (Plan 05)
+export { createPostgresSnapshotStore, } from "./postgres-snapshot-store.js";
+// Extension factory (Plan 05)
+export { postgres } from "./postgres.js";
+// Schema bootstrap + DDL builders — exposed for users who want to run their
+// own migrations (set `postgres({ bootstrap: false })`) or drive the store
+// directly without going through the extension factory.
+export { bootstrapSchema, buildEventsTableDDL, buildEventsIndexesDDL, buildSnapshotsTableDDL, DEFAULT_TABLE_NAMES, } from "./schema.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,EAAE;AACF,oEAAoE;AACpE,6EAA6E;AAC7E,mEAAmE;AACnE,yEAAyE;AACzE,EAAE;AACF,2EAA2E;AAC3E,0DAA0D;AAC1D,gEAAgE;AAEhE,OAAO,EACL,oBAAoB,EACpB,6BAA6B,EAC7B,cAAc,GACf,MAAM,aAAa,CAAA;AAEpB,uDAAuD;AACvD,uEAAuE;AACvE,8CAA8C;AAC9C,OAAO,EACL,cAAc,GAKf,MAAM,cAAc,CAAA;AAErB,iDAAiD;AACjD,OAAO,EACL,wBAAwB,GAIzB,MAAM,2BAA2B,CAAA;AAElC,mCAAmC;AACnC,OAAO,EACL,2BAA2B,GAE5B,MAAM,8BAA8B,CAAA;AAErC,8BAA8B;AAC9B,OAAO,EAAE,QAAQ,EAAuB,MAAM,eAAe,CAAA;AAE7D,4EAA4E;AAC5E,2EAA2E;AAC3E,wDAAwD;AACxD,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,GAEpB,MAAM,aAAa,CAAA"}

package/dist/postgres-event-store.d.ts

@@ -0,0 +1,52 @@
+/**
+ * createPostgresEventStore — full EventStorageEngine + EventBus implementation.
+ *
+ * Plan 12-04 delivered: source, appendEvents, append.
+ * Plan 12-05 adds: open (gap-free tailing via xid8 + pg_snapshot_xmin),
+ *   getHeadPosition, firstToken, latestToken, publish, subscribe.
+ *
+ * Append path:
+ *   1. open transaction at READ COMMITTED
+ *   2. acquireWriteLocks for the criteria tags (not event types) so that
+ *      two writers on the SAME criteria tag serialize, while disjoint-tag
+ *      writers run in parallel
+ *   3. Conflict check: SELECT count(*) WHERE sequence_position > marker AND criteria
+ *   4. If conflict count > 0 → throw AppendConditionError (code KR001)
+ *   5. INSERT events returning sequence_position for the ConsistencyMarker
+ *   6. commit() → COMMIT; afterCommit() → marker; rollback() → fire-and-forget
+ *      ROLLBACK (synchronous void per the framework contract)
+ *
+ * Streaming path (open):
+ *   - Watermark query: (transaction_id, sequence_position) > ($xid, $pos)
+ *     AND transaction_id < pg_snapshot_xmin(pg_current_snapshot())
+ *   - Wake-up via LISTEN/NOTIFY on `kronos_events_${tables.events}` channel
+ *   - Fallback to 250ms polling if LISTEN is not supported
+ *
+ * Note on the stored procedure (buildAppendStoredProcedureDDL): The SP is
+ * registered in schema.ts and available on the DB, but this plan uses
+ * direct parameterised SQL for the conflict check + INSERT rather than
+ * calling the SP. The SP's dynamic-SQL approach has complex $N-rebinding
+ * requirements (criteria_params JSONB → USING binding) that are cleaner to
+ * handle in TypeScript. Plan 06's review may revisit whether the SP
+ * provides a meaningful benefit.
+ */
+import type { EventStore } from "@kronos-ts/eventsourcing";
+import type { EventMessage } from "@kronos-ts/messaging";
+import type { Serializer } from "@kronos-ts/common";
+export type { Serializer } from "@kronos-ts/common";
+import type { PostgresAdapter } from "./adapter.js";
+import { type TableNames } from "./schema.js";
+export interface TagResolver {
+    resolve(event: EventMessage): ReadonlyArray<{
+        key: string;
+        value: string;
+    }>;
+}
+export interface PostgresEventStoreConfig {
+    readonly adapter: PostgresAdapter;
+    readonly serializer: Serializer;
+    readonly tagResolver: TagResolver;
+    readonly tableNames?: TableNames;
+}
+export declare function createPostgresEventStore(config: PostgresEventStoreConfig): EventStore;
+//# sourceMappingURL=postgres-event-store.d.ts.map

package/dist/postgres-event-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-event-store.d.ts","sourceRoot":"","sources":["../src/postgres-event-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAGV,UAAU,EACX,MAAM,0BAA0B,CAAA;AAMjC,OAAO,KAAK,EACV,YAAY,EAMb,MAAM,sBAAsB,CAAA;AAG7B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,KAAK,EAAE,eAAe,EAA8B,MAAM,cAAc,CAAA;AAK/E,OAAO,EAAE,KAAK,UAAU,EAAuB,MAAM,aAAa,CAAA;AAIlE,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,aAAa,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC5E;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IACjC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;IAC/B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAA;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;CACjC;AAED,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,wBAAwB,GAC/B,UAAU,CA+dZ"}

package/dist/postgres-event-store.js

@@ -0,0 +1,496 @@
+/**
+ * createPostgresEventStore — full EventStorageEngine + EventBus implementation.
+ *
+ * Plan 12-04 delivered: source, appendEvents, append.
+ * Plan 12-05 adds: open (gap-free tailing via xid8 + pg_snapshot_xmin),
+ *   getHeadPosition, firstToken, latestToken, publish, subscribe.
+ *
+ * Append path:
+ *   1. open transaction at READ COMMITTED
+ *   2. acquireWriteLocks for the criteria tags (not event types) so that
+ *      two writers on the SAME criteria tag serialize, while disjoint-tag
+ *      writers run in parallel
+ *   3. Conflict check: SELECT count(*) WHERE sequence_position > marker AND criteria
+ *   4. If conflict count > 0 → throw AppendConditionError (code KR001)
+ *   5. INSERT events returning sequence_position for the ConsistencyMarker
+ *   6. commit() → COMMIT; afterCommit() → marker; rollback() → fire-and-forget
+ *      ROLLBACK (synchronous void per the framework contract)
+ *
+ * Streaming path (open):
+ *   - Watermark query: (transaction_id, sequence_position) > ($xid, $pos)
+ *     AND transaction_id < pg_snapshot_xmin(pg_current_snapshot())
+ *   - Wake-up via LISTEN/NOTIFY on `kronos_events_${tables.events}` channel
+ *   - Fallback to 250ms polling if LISTEN is not supported
+ *
+ * Note on the stored procedure (buildAppendStoredProcedureDDL): The SP is
+ * registered in schema.ts and available on the DB, but this plan uses
+ * direct parameterised SQL for the conflict check + INSERT rather than
+ * calling the SP. The SP's dynamic-SQL approach has complex $N-rebinding
+ * requirements (criteria_params JSONB → USING binding) that are cleaner to
+ * handle in TypeScript. Plan 06's review may revisit whether the SP
+ * provides a meaningful benefit.
+ */
+import { markerAt } from "@kronos-ts/eventsourcing";
+import { createMessageStream, globalSequenceToken, FIRST_TOKEN } from "@kronos-ts/messaging";
+import { qualifiedNameToString, qualifiedNameFromString } from "@kronos-ts/common";
+import { IsolationLevel } from "./adapter.js";
+import { acquireWriteLocks } from "./advisory-locks.js";
+import { buildCriteriaWhere, encodeTag } from "./criteria-sql.js";
+import { AppendConditionError, isDcbViolation, KRONOS_DCB_VIOLATION_SQLSTATE } from "./errors.js";
+import { DEFAULT_TABLE_NAMES } from "./schema.js";
+export function createPostgresEventStore(config) {
+    const { adapter, tagResolver } = config;
+    const tables = config.tableNames ?? DEFAULT_TABLE_NAMES;
+    // Push-based subscriber registry (EventBus.subscribe contract)
+    const eventSubscribers = new Set();
+    // LISTEN/NOTIFY channel name for wake-up of tailing streams (D-12.14)
+    const notifyChannel = `kronos_events_${tables.events}`;
+    function eventTypeOf(e) {
+        return qualifiedNameToString(e.name);
+    }
+    /**
+     * Extract lock targets from the criteria — the writer locks on what it is
+     * READING (the criteria tags), not just what it is writing. This ensures
+     * two writers on the same criteria tag serialize (one blocks until the
+     * other commits), while writers on disjoint criteria tags run in parallel.
+     *
+     * For `any-tag` or empty criteria, returns an empty array so only the
+     * global-intent S-lock is acquired (acquireWriteLocks handles the empty case).
+     */
+    function lockTargetsForCondition(condition) {
+        if (!condition)
+            return [];
+        return extractCriteriaTags(condition.criteria).map((tag) => ({ type: "", tag }));
+    }
+    function extractCriteriaTags(criteria) {
+        switch (criteria.kind) {
+            case "tags":
+                return criteria.tags.map((t) => encodeTag(t.key, t.value));
+            case "any-tag":
+                // any-tag covers all tags — use global-intent only (empty list)
+                return [];
+            case "type-restricted":
+                return extractCriteriaTags(criteria.inner);
+            case "either":
+                return criteria.criteria.flatMap((c) => extractCriteriaTags(c));
+        }
+    }
+    function encodedTagsOf(e) {
+        return tagResolver.resolve(e).map((t) => encodeTag(t.key, t.value));
+    }
+    /**
+     * Check for DCB conflict and INSERT events, within the caller's transaction.
+     * Returns the (position, xid) of the last inserted row.
+     *
+     * Uses parameterised SQL (no dynamic SQL), so each query is prepared once
+     * and has no $N rebinding complexity.
+     */
+    async function checkAndInsert(tx, events, condition) {
+        // --- Conflict check ---
+        if (condition) {
+            const markerPos = condition.marker.position;
+            const built = buildCriteriaWhere(condition.criteria, 2); // $1 = markerPos
+            const sql = `SELECT count(*)::bigint AS cnt FROM ${tables.events}
+                   WHERE sequence_position > $1 AND (${built.where})`;
+            const rows = await tx.query(sql, [markerPos, ...built.params]);
+            const cnt = BigInt(rows[0]?.cnt ?? 0);
+            if (cnt > 0n) {
+                // Throw with the KR001 code so isDcbViolation() can identify it
+                const err = new AppendConditionError(`Append condition violated: ${cnt} conflicting event(s) after position ${markerPos}`);
+                err.code = KRONOS_DCB_VIOLATION_SQLSTATE;
+                throw err;
+            }
+        }
+        // --- Insert events ---
+        let lastPosition = -1n;
+        let lastXid = "";
+        for (const e of events) {
+            const encodedTags = encodedTagsOf(e);
+            const type = eventTypeOf(e);
+            const payload = e.payload ?? {};
+            const metadata = e.metadata ?? {};
+            const rows = await tx.query(`INSERT INTO ${tables.events} (event_id, type, tags, payload, metadata)
+         VALUES ($1, $2, $3, $4, $5)
+         RETURNING sequence_position, transaction_id`, [
+                e.identifier,
+                type,
+                encodedTags,
+                JSON.stringify(payload),
+                JSON.stringify(metadata),
+            ]);
+            const row = rows[0];
+            if (!row)
+                throw new Error("INSERT returned no rows");
+            lastPosition = BigInt(row.sequence_position);
+            lastXid = row.transaction_id;
+        }
+        if (lastPosition < 0n) {
+            throw new Error("no events were inserted");
+        }
+        return { position: lastPosition, xid: lastXid };
+    }
+    return {
+        async source(condition) {
+            const start = condition.start ?? 0n;
+            const built = buildCriteriaWhere(condition.criteria, 2); // $1 = start
+            const sql = `
+        SELECT sequence_position, type, tags, payload, metadata
+        FROM ${tables.events}
+        WHERE sequence_position >= $1 AND (${built.where})
+        ORDER BY sequence_position ASC
+      `;
+            const rows = await adapter.query(sql, [start, ...built.params]);
+            const events = rows.map((r) => decodeEvent(r));
+            const headRow = await adapter.queryOne(`SELECT MAX(sequence_position)::text AS head FROM ${tables.events}`);
+            const head = headRow?.head ? BigInt(headRow.head) : -1n;
+            const lastPos = rows.length > 0 ? BigInt(rows[rows.length - 1].sequence_position) : -1n;
+            const marker = rows.length > 0 ? markerAt(lastPos) : markerAt(head);
+            return { events, marker };
+        },
+        async appendEvents(events, condition) {
+            // Two-phase: open tx, acquire locks, run conflict check + INSERT, hold
+            // tx open until commit(). We bridge adapter.transaction() (which owns
+            // the full lifecycle) with a deferred that the AppendTransaction controls.
+            const targets = lockTargetsForCondition(condition);
+            let resolveOuter;
+            let rejectOuter;
+            const outer = new Promise((res, rej) => {
+                resolveOuter = res;
+                rejectOuter = rej;
+            });
+            let txReady;
+            const txStaged = new Promise((res) => {
+                txReady = res;
+            });
+            let resolveTxControl;
+            const txControl = new Promise((res) => {
+                resolveTxControl = res;
+            });
+            // Kick off the transaction in the background.
+            const txPromise = adapter
+                .transaction(IsolationLevel.READ_COMMITTED, async (tx) => {
+                await acquireWriteLocks(tx, targets);
+                let captured;
+                try {
+                    captured = await checkAndInsert(tx, events, condition);
+                }
+                catch (err) {
+                    if (isDcbViolation(err)) {
+                        // Already an AppendConditionError with KR001 code
+                        throw err;
+                    }
+                    if (err.code === "23505") {
+                        throw AppendConditionError.fromConflictCount(0, condition?.marker.position ?? -1n);
+                    }
+                    throw err;
+                }
+                txReady();
+                const cmd = await txControl;
+                if (cmd === "rollback") {
+                    throw new Error("__kronos_rollback__");
+                }
+                return captured;
+            })
+                .then((v) => resolveOuter(v), (e) => {
+                if (e instanceof Error && e.message === "__kronos_rollback__") {
+                    rejectOuter(new Error("rolled back"));
+                }
+                else {
+                    rejectOuter(e);
+                }
+            });
+            void txPromise;
+            // Wait until the SP has executed so that errors (DCB violation) surface
+            // BEFORE the AppendTransaction handle is returned.
+            await Promise.race([
+                txStaged,
+                outer.catch(() => {
+                    return;
+                }),
+            ]);
+            // Surface any already-rejected error immediately.
+            let alreadyFailed = false;
+            outer.catch(() => {
+                alreadyFailed = true;
+            });
+            await Promise.resolve();
+            if (alreadyFailed) {
+                await outer;
+            }
+            let committed = false;
+            const transaction = {
+                async commit() {
+                    committed = true;
+                    resolveTxControl("commit");
+                    await outer;
+                    // Wake up tailing streams + notify push-based subscribers after commit
+                    await adapter.query(`NOTIFY ${notifyChannel}`);
+                    for (const sub of eventSubscribers) {
+                        try {
+                            await sub(events);
+                        }
+                        catch { /* ignore subscriber errors */ }
+                    }
+                },
+                async afterCommit() {
+                    const result = await outer;
+                    return markerAt(result.position);
+                },
+                rollback() {
+                    if (committed)
+                        return;
+                    resolveTxControl("rollback");
+                    outer.catch(() => {
+                        /* swallow — rollback path is expected to reject outer */
+                    });
+                },
+            };
+            return transaction;
+        },
+        async append(events, condition) {
+            // Convenience: appendEvents + commit + afterCommit in one shot.
+            const targets = lockTargetsForCondition(condition);
+            let marker;
+            try {
+                marker = await adapter.transaction(IsolationLevel.READ_COMMITTED, async (tx) => {
+                    await acquireWriteLocks(tx, targets);
+                    const captured = await checkAndInsert(tx, events, condition);
+                    return markerAt(captured.position);
+                });
+            }
+            catch (err) {
+                if (isDcbViolation(err)) {
+                    // Re-throw AppendConditionError directly (already has correct type)
+                    throw err;
+                }
+                if (err.code === "23505") {
+                    throw AppendConditionError.fromConflictCount(0, condition?.marker.position ?? -1n);
+                }
+                throw err;
+            }
+            // Wake up tailing streams + notify push-based subscribers
+            await adapter.query(`NOTIFY ${notifyChannel}`);
+            for (const sub of eventSubscribers) {
+                try {
+                    await sub(events);
+                }
+                catch { /* ignore subscriber errors */ }
+            }
+            return marker;
+        },
+        async getHeadPosition() {
+            const row = await adapter.queryOne(`SELECT COALESCE(MAX(sequence_position), 0)::text AS head FROM ${tables.events}`);
+            return row?.head ? BigInt(row.head) : 0n;
+        },
+        async firstToken() {
+            return FIRST_TOKEN;
+        },
+        async latestToken() {
+            const row = await adapter.queryOne(`SELECT COALESCE(MAX(sequence_position), 0)::text AS head FROM ${tables.events}`);
+            const head = row?.head ? BigInt(row.head) : 0n;
+            return globalSequenceToken(head);
+        },
+        async publish(events) {
+            // publish = append without condition; also notifies subscribers + streams
+            const targets = [];
+            let marker;
+            try {
+                marker = await adapter.transaction(IsolationLevel.READ_COMMITTED, async (tx) => {
+                    await acquireWriteLocks(tx, targets);
+                    const captured = await checkAndInsert(tx, events, undefined);
+                    return markerAt(captured.position);
+                });
+            }
+            catch (err) {
+                if (err.code === "23505") {
+                    throw AppendConditionError.fromConflictCount(0, -1n);
+                }
+                throw err;
+            }
+            void marker;
+            await adapter.query(`NOTIFY ${notifyChannel}`);
+            for (const sub of eventSubscribers) {
+                try {
+                    await sub(events);
+                }
+                catch { /* ignore subscriber errors */ }
+            }
+        },
+        subscribe(handler) {
+            eventSubscribers.add(handler);
+            return () => {
+                eventSubscribers.delete(handler);
+            };
+        },
+        open(condition) {
+            let cursorPosition = condition.position;
+            // The (xid8, position) tuple bookmark. We start with xid8 = '0' which is
+            // less than any real xid8 — so the (xid8, position) > ($1, $2) predicate
+            // collapses to effectively position > $2 on first read.
+            let cursorXid = "0";
+            const criteria = condition.criteria;
+            let closed = false;
+            let onAvailable = null;
+            const buffer = [];
+            let polling = false;
+            let listenSub;
+            async function fetchBatch(limit = 100) {
+                if (closed)
+                    return;
+                // When we have a real xid cursor, use the (xid8, position) tuple comparison
+                // for gap-free ordering. On initial fetch (cursorXid = "0") we don't yet
+                // have a real xid, so fall back to a plain sequence_position > $cursor filter —
+                // the pg_snapshot_xmin watermark still applies to exclude in-flight transactions.
+                let sql;
+                let queryParams;
+                if (cursorXid === "0") {
+                    // Initial fetch: simple position filter — all committed events after cursorPosition.
+                    // $1 = position, criteria starts at $2
+                    const builtInitial = criteria
+                        ? buildCriteriaWhere(criteria, 2)
+                        : { where: "true", params: [], nextParamIndex: 2 };
+                    const limitParam = builtInitial.nextParamIndex;
+                    sql = `
+            SELECT sequence_position::text AS sequence_position,
+                   transaction_id::text AS transaction_id,
+                   type, tags, payload, metadata
+            FROM ${tables.events}
+            WHERE sequence_position > $1::bigint
+              AND transaction_id < pg_snapshot_xmin(pg_current_snapshot())
+              AND (${builtInitial.where})
+            ORDER BY transaction_id ASC, sequence_position ASC
+            LIMIT $${limitParam}
+          `;
+                    queryParams = [String(cursorPosition), ...builtInitial.params, limit];
+                }
+                else {
+                    // Subsequent fetch: (xid8, position) tuple comparison for gap-free ordering.
+                    // $1 = xid, $2 = position, criteria starts at $3
+                    const builtTuple = criteria
+                        ? buildCriteriaWhere(criteria, 3)
+                        : { where: "true", params: [], nextParamIndex: 3 };
+                    const limitParam = builtTuple.nextParamIndex;
+                    sql = `
+            SELECT sequence_position::text AS sequence_position,
+                   transaction_id::text AS transaction_id,
+                   type, tags, payload, metadata
+            FROM ${tables.events}
+            WHERE (transaction_id, sequence_position) > ($1::xid8, $2::bigint)
+              AND transaction_id < pg_snapshot_xmin(pg_current_snapshot())
+              AND (${builtTuple.where})
+            ORDER BY transaction_id ASC, sequence_position ASC
+            LIMIT $${limitParam}
+          `;
+                    queryParams = [cursorXid, String(cursorPosition), ...builtTuple.params, limit];
+                }
+                const rows = await adapter.query(sql, queryParams);
+                for (const r of rows) {
+                    const event = decodeEvent(r);
+                    const seq = BigInt(r.sequence_position);
+                    buffer.push({ sequence: seq, event });
+                    cursorXid = r.transaction_id;
+                    cursorPosition = seq;
+                }
+            }
+            async function pump() {
+                if (polling || closed)
+                    return;
+                polling = true;
+                try {
+                    await fetchBatch();
+                    if (buffer.length > 0 && onAvailable)
+                        onAvailable();
+                }
+                finally {
+                    polling = false;
+                }
+            }
+            // Start polling immediately so we don't miss events that were committed
+            // before the LISTEN subscription is established. The poll interval is
+            // replaced by NOTIFY-driven pumps once LISTEN is up.
+            let pollInterval = setInterval(() => {
+                if (closed) {
+                    clearInterval(pollInterval);
+                    pollInterval = undefined;
+                    return;
+                }
+                void pump();
+            }, 250);
+            // Wake-up via LISTEN/NOTIFY — supplements polling with instant delivery
+            void adapter
+                .listen(notifyChannel, () => {
+                void pump();
+            })
+                .then((sub) => {
+                listenSub = sub;
+                // Keep polling as a safety net even with LISTEN active.
+                // The 250ms interval is cheap (no-op when no new events).
+            })
+                .catch(() => {
+                // LISTEN not supported — polling fallback already running above
+            });
+            // Also run an immediate fetch to pick up any pre-existing events
+            void pump();
+            return createMessageStream({
+                next() {
+                    return buffer.shift();
+                },
+                peek() {
+                    return buffer[0];
+                },
+                hasNextAvailable() {
+                    return buffer.length > 0;
+                },
+                setCallback(cb) {
+                    onAvailable = cb;
+                },
+                isCompleted() {
+                    return closed;
+                },
+                error() {
+                    return undefined;
+                },
+                close() {
+                    closed = true;
+                    onAvailable = null;
+                    if (pollInterval) {
+                        clearInterval(pollInterval);
+                        pollInterval = undefined;
+                    }
+                    if (listenSub)
+                        void listenSub.unlisten();
+                },
+            });
+        },
+    };
+}
+function decodeEvent(row) {
+    const qn = qualifiedNameFromString(row.type);
+    const tags = row.tags.map((t) => {
+        const sep = t.indexOf("");
+        return sep >= 0
+            ? { key: t.slice(0, sep), value: t.slice(sep + 1) }
+            : { key: t, value: "" };
+    });
+    return {
+        name: qn,
+        tags,
+        payload: decodeJsonb(row.payload),
+        metadata: decodeJsonb(row.metadata),
+    };
+}
+// Adapter-agnostic JSONB decoding: pgAdapter/postgresAdapter return parsed
+// objects, but bunSqlAdapter (Bun.SQL) returns JSONB as a raw string. Normalise
+// here so callers always see a JS object.
+function decodeJsonb(v) {
+    if (typeof v === "string") {
+        try {
+            return JSON.parse(v);
+        }
+        catch {
+            return v;
+        }
+    }
+    return v;
+}
+//# sourceMappingURL=postgres-event-store.js.map