@rotorsoft/act-pg 0.20.1 → 0.20.2

package/dist/index.js

@@ -0,0 +1,846 @@
+// src/postgres-store.ts
+import { randomUUID } from "crypto";
+import {
+  ConcurrencyError,
+  log,
+  SNAP_EVENT,
+  TOMBSTONE_EVENT
+} from "@rotorsoft/act";
+import pg from "pg";
+
+// src/utils.ts
+var ISO_8601 = /^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])T([01][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9])(\.\d+)?(Z|[+-][0-2][0-9]:[0-5][0-9])?$/;
+var dateReviver = (_key, value) => {
+  if (typeof value === "string" && ISO_8601.test(value)) {
+    return new Date(value);
+  }
+  return value;
+};
+
+// src/postgres-store.ts
+var logger = log();
+var { Pool, types } = pg;
+types.setTypeParser(
+  types.builtins.JSONB,
+  (val) => JSON.parse(val, dateReviver)
+);
+var SAFE_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+var PG_UNIQUE_VIOLATION = "23505";
+var NOTIFY_CHANNEL_PREFIX = "act_commit";
+function notifyChannel(schema, table) {
+  return `${NOTIFY_CHANNEL_PREFIX}_${schema}_${table}`;
+}
+function assertSafeIdentifier(value, label) {
+  if (!SAFE_IDENTIFIER.test(value))
+    throw new Error(`Unsafe SQL identifier for ${label}: "${value}"`);
+}
+var DEFAULT_CONFIG = {
+  host: "localhost",
+  port: 5432,
+  database: "postgres",
+  user: "postgres",
+  password: "postgres",
+  schema: "public",
+  table: "events",
+  notify: false
+};
+var PostgresStore = class {
+  _pool;
+  config;
+  _fqt;
+  _fqs;
+  /**
+   * Per-instance writer identifier embedded in every NOTIFY payload. The
+   * `notify()` LISTEN handler skips payloads where `by === this._by`,
+   * giving the `"notified"` lifecycle event a clean cross-process
+   * semantic — local commits never echo back through this channel.
+   */
+  _by = randomUUID();
+  /**
+   * Effective NOTIFY channel for this store. Computed from `(schema,
+   * table)` at construction so multiple stores in the same database
+   * stay isolated.
+   */
+  _channel;
+  /** Active LISTEN client (one per `notify()` subscription). */
+  _listenClient;
+  /**
+   * Notification listener attached to the active LISTEN client. Tracked
+   * separately so the re-subscribe / dispose paths can detach it before
+   * destroying the client — without this, a pool that reused the
+   * connection would re-fire the stale handler.
+   */
+  _listenHandler;
+  /**
+   * Cross-process commit subscription. **Present only when
+   * `config.notify === true`** — the orchestrator's auto-wire path
+   * checks `if (store.notify)`, so omitting the method keeps
+   * single-instance deployments free of any LISTEN/NOTIFY overhead
+   * (no dedicated client, no per-commit `pg_notify`).
+   *
+   * @see {@link Config.notify} for the rationale and the multi-process
+   *   contract.
+   */
+  notify;
+  /**
+   * Create a new PostgresStore instance.
+   * @param config Partial configuration (host, port, user, password, schema, table, etc.)
+   */
+  constructor(config = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    assertSafeIdentifier(this.config.schema, "schema");
+    assertSafeIdentifier(this.config.table, "table");
+    const { schema: _, table: __, ...poolConfig } = this.config;
+    this._pool = new Pool(poolConfig);
+    this._fqt = `"${this.config.schema}"."${this.config.table}"`;
+    this._fqs = `"${this.config.schema}"."${this.config.table}_streams"`;
+    this._channel = notifyChannel(this.config.schema, this.config.table);
+    if (this.config.notify) {
+      this.notify = this._subscribeNotifications.bind(this);
+    }
+  }
+  /**
+   * Dispose of the store and close all database connections.
+   * Releases any active LISTEN client first so the pool can drain cleanly.
+   * @returns Promise that resolves when all connections are closed
+   */
+  async dispose() {
+    await this._teardownListen();
+    await this._pool.end();
+  }
+  /**
+   * Tear down the active LISTEN subscription if any: detach the
+   * notification listener, run UNLISTEN, and destroy the dedicated
+   * client (do not return it to the pool — its listener is removed but
+   * destroying belt-and-braces guards against any future change in
+   * pg-pool semantics that could re-issue a half-clean client).
+   */
+  async _teardownListen() {
+    if (!this._listenClient) return;
+    this._listenClient.removeListener("notification", this._listenHandler);
+    this._listenHandler = void 0;
+    try {
+      await this._listenClient.query(`UNLISTEN ${this._channel}`);
+    } catch {
+    }
+    this._listenClient.release(true);
+    this._listenClient = void 0;
+  }
+  /**
+   * Seed the database with required tables, indexes, and schema for event storage.
+   * @returns Promise that resolves when seeding is complete
+   * @throws Error if seeding fails
+   */
+  async seed() {
+    const client = await this._pool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query(
+        `CREATE SCHEMA IF NOT EXISTS "${this.config.schema}";`
+      );
+      await client.query(
+        `CREATE TABLE IF NOT EXISTS ${this._fqt} (
+          id serial PRIMARY KEY,
+          name varchar(100) COLLATE pg_catalog."default" NOT NULL,
+          data jsonb,
+          stream varchar(100) COLLATE pg_catalog."default" NOT NULL,
+          version int NOT NULL,
+          created timestamptz NOT NULL DEFAULT now(),
+          meta jsonb
+        ) TABLESPACE pg_default;`
+      );
+      await client.query(
+        `CREATE UNIQUE INDEX IF NOT EXISTS "${this.config.table}_stream_ix" 
+        ON ${this._fqt} (stream COLLATE pg_catalog."default", version);`
+      );
+      await client.query(
+        `CREATE INDEX IF NOT EXISTS "${this.config.table}_name_ix" 
+        ON ${this._fqt} (name COLLATE pg_catalog."default");`
+      );
+      await client.query(
+        `CREATE INDEX IF NOT EXISTS "${this.config.table}_created_id_ix" 
+        ON ${this._fqt} (created, id);`
+      );
+      await client.query(
+        `CREATE INDEX IF NOT EXISTS "${this.config.table}_correlation_ix" 
+        ON ${this._fqt} ((meta ->> 'correlation') COLLATE pg_catalog."default");`
+      );
+      await client.query(
+        `CREATE TABLE IF NOT EXISTS ${this._fqs} (
+          stream varchar(100) COLLATE pg_catalog."default" PRIMARY KEY,
+          source varchar(100) COLLATE pg_catalog."default",
+          at int NOT NULL DEFAULT -1,
+          retry smallint NOT NULL DEFAULT 0,
+          blocked boolean NOT NULL DEFAULT false,
+          error text,
+          leased_by text,
+          leased_until timestamptz,
+          priority int NOT NULL DEFAULT 0
+        ) TABLESPACE pg_default;`
+      );
+      await client.query(
+        `ALTER TABLE ${this._fqs}
+         ADD COLUMN IF NOT EXISTS priority int NOT NULL DEFAULT 0;`
+      );
+      await client.query(
+        `DROP INDEX IF EXISTS "${this.config.schema}"."${this.config.table}_streams_fetch_ix"`
+      );
+      await client.query(
+        `CREATE INDEX IF NOT EXISTS "${this.config.table}_streams_claim_ix"
+        ON ${this._fqs} (blocked, priority DESC, at);`
+      );
+      await client.query("COMMIT");
+      logger.info(
+        `Seeded schema "${this.config.schema}" with table "${this.config.table}"`
+      );
+    } catch (error) {
+      await client.query("ROLLBACK");
+      logger.error(error);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+  /**
+   * Drop all tables and schema created by the store (for testing or cleanup).
+   * @returns Promise that resolves when the schema is dropped
+   */
+  async drop() {
+    await this._pool.query(
+      `
+      DO $$
+      BEGIN
+        IF EXISTS (SELECT 1 FROM information_schema.schemata
+          WHERE schema_name = '${this.config.schema}'
+        ) THEN
+          EXECUTE 'DROP TABLE IF EXISTS ${this._fqt}';
+          EXECUTE 'DROP TABLE IF EXISTS ${this._fqs}';
+          IF '${this.config.schema}' <> 'public' THEN
+            EXECUTE 'DROP SCHEMA "${this.config.schema}" CASCADE';
+          END IF;
+        END IF;
+      END
+      $$;
+    `
+    );
+  }
+  /**
+   * Query events from the store, optionally filtered by stream, event name, time, etc.
+   *
+   * @param callback Function called for each event found
+   * @param query (Optional) Query filter (stream, names, before, after, etc.)
+   * @returns The number of events found
+   *
+   * @example
+   * await store.query((event) => console.log(event), { stream: "A" });
+   */
+  async query(callback, query) {
+    const {
+      stream,
+      names,
+      before,
+      after,
+      limit,
+      created_before,
+      created_after,
+      backward,
+      correlation,
+      with_snaps = false
+    } = query || {};
+    let sql = `SELECT * FROM ${this._fqt}`;
+    const conditions = [];
+    const values = [];
+    if (query) {
+      if (typeof after !== "undefined") {
+        values.push(after);
+        conditions.push(`id>$${values.length}`);
+      } else {
+        conditions.push("id>-1");
+      }
+      if (stream) {
+        values.push(stream);
+        conditions.push(
+          query.stream_exact ? `stream = $${values.length}` : `stream ~ $${values.length}`
+        );
+      }
+      if (names?.length) {
+        values.push(names);
+        conditions.push(`name = ANY($${values.length})`);
+      }
+      if (before) {
+        values.push(before);
+        conditions.push(`id<$${values.length}`);
+      }
+      if (created_after) {
+        values.push(created_after.toISOString());
+        conditions.push(`created>$${values.length}`);
+      }
+      if (created_before) {
+        values.push(created_before.toISOString());
+        conditions.push(`created<$${values.length}`);
+      }
+      if (correlation) {
+        values.push(correlation);
+        conditions.push(`meta->>'correlation'=$${values.length}`);
+      }
+      if (!with_snaps) {
+        conditions.push(`name <> '${SNAP_EVENT}'`);
+      }
+    }
+    if (conditions.length) {
+      sql += " WHERE " + conditions.join(" AND ");
+    }
+    sql += ` ORDER BY id ${backward ? "DESC" : "ASC"}`;
+    if (limit) {
+      values.push(limit);
+      sql += ` LIMIT $${values.length}`;
+    }
+    const result = await this._pool.query(sql, values);
+    for (const row of result.rows) callback(row);
+    return result.rowCount ?? 0;
+  }
+  /**
+   * Commit new events to the store for a given stream, with concurrency control.
+   *
+   * @param stream The stream name
+   * @param msgs Array of messages (event name and data)
+   * @param meta Event metadata (correlation, causation, etc.)
+   * @param expectedVersion (Optional) Expected stream version for concurrency control
+   * @returns Array of committed events
+   * @throws ConcurrencyError if the expected version does not match
+   */
+  async commit(stream, msgs, meta, expectedVersion) {
+    if (msgs.length === 0) return [];
+    const client = await this._pool.connect();
+    let version = -1;
+    try {
+      await client.query("BEGIN");
+      const last = await client.query(
+        `SELECT version
+        FROM ${this._fqt}
+        WHERE stream=$1 ORDER BY version DESC LIMIT 1`,
+        [stream]
+      );
+      version = last.rowCount ? last.rows[0].version : -1;
+      if (typeof expectedVersion === "number" && version !== expectedVersion)
+        throw new ConcurrencyError(
+          stream,
+          version,
+          msgs,
+          expectedVersion
+        );
+      const committed = [];
+      for (const { name, data } of msgs) {
+        version++;
+        const sql = `
+          INSERT INTO ${this._fqt}(name, data, stream, version, meta)
+          VALUES($1, $2, $3, $4, $5) RETURNING *`;
+        const vals = [name, data, stream, version, meta];
+        try {
+          const { rows } = await client.query(sql, vals);
+          committed.push(rows.at(0));
+        } catch (error) {
+          if (error?.code === PG_UNIQUE_VIOLATION) {
+            throw new ConcurrencyError(
+              stream,
+              version - 1,
+              msgs,
+              expectedVersion ?? -1
+            );
+          }
+          throw error;
+        }
+      }
+      if (this.config.notify) {
+        const payload = JSON.stringify({
+          stream,
+          events: committed.map((c) => ({ id: c.id, name: c.name })),
+          by: this._by
+        });
+        await client.query(`SELECT pg_notify($1, $2)`, [
+          this._channel,
+          payload
+        ]);
+      }
+      await client.query("COMMIT");
+      return committed;
+    } catch (error) {
+      await client.query("ROLLBACK").catch(() => {
+      });
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+  /**
+   * Atomically discovers and leases streams for reaction processing.
+   *
+   * Uses `FOR UPDATE SKIP LOCKED` to implement zero-contention competing consumers:
+   * - Workers never block each other — locked rows are silently skipped
+   * - Discovery and locking happen in a single atomic transaction
+   * - No wasted polls — every returned stream is exclusively owned
+   *
+   * @param lagging - Max streams from lagging frontier (ascending watermark)
+   * @param leading - Max streams from leading frontier (descending watermark)
+   * @param by - Lease holder identifier (UUID)
+   * @param millis - Lease duration in milliseconds
+   * @returns Leased streams with metadata
+   */
+  async claim(lagging, leading, by, millis) {
+    const client = await this._pool.connect();
+    try {
+      await client.query("BEGIN");
+      const { rows } = await client.query(
+        `
+        WITH
+        available AS (
+          SELECT stream, source, at, priority
+          FROM ${this._fqs} s
+          WHERE blocked = false
+            AND (leased_by IS NULL OR leased_until <= NOW())
+            AND (s.at < 0 OR EXISTS (
+              SELECT 1 FROM ${this._fqt} e
+              WHERE e.id > s.at
+                AND e.name <> '${SNAP_EVENT}'
+                AND (s.source IS NULL OR e.stream = COALESCE(s.source, s.stream))
+              LIMIT 1
+            ))
+          FOR UPDATE SKIP LOCKED
+        ),
+        -- Priority lanes (ACT-102): higher priority first, then
+        -- lagging-watermark order. With everyone at priority=0 the
+        -- ORDER BY collapses to plain at ASC so existing workloads
+        -- see no behavior change.
+        lag AS (
+          SELECT stream, source, at, TRUE AS lagging
+          FROM available
+          ORDER BY priority DESC, at ASC
+          LIMIT $1
+        ),
+        lead AS (
+          SELECT stream, source, at, FALSE AS lagging
+          FROM available
+          ORDER BY at DESC
+          LIMIT $2
+        ),
+        combined AS (
+          SELECT DISTINCT ON (stream) stream, source, at, lagging
+          FROM (SELECT * FROM lag UNION ALL SELECT * FROM lead) t
+          ORDER BY stream, at
+        )
+        UPDATE ${this._fqs} s
+        SET
+          leased_by = $3,
+          leased_until = NOW() + ($4::integer || ' milliseconds')::interval,
+          retry = s.retry + 1
+        FROM combined c
+        WHERE s.stream = c.stream
+        RETURNING s.stream, s.source, s.at, s.retry, c.lagging
+        `,
+        [lagging, leading, by, millis]
+      );
+      await client.query("COMMIT");
+      return rows.map(({ stream, source, at, retry, lagging: lagging2 }) => ({
+        stream,
+        source: source ?? void 0,
+        at,
+        by,
+        retry,
+        lagging: lagging2
+      }));
+    } catch (error) {
+      await client.query("ROLLBACK").catch(() => {
+      });
+      logger.error(error);
+      return [];
+    } finally {
+      client.release();
+    }
+  }
+  /**
+   * Registers streams for event processing.
+   * Upserts stream entries so they become visible to claim().
+   * Also returns the current max watermark across all subscriptions.
+   * @param streams - Streams to register with optional source.
+   * @returns subscribed count and current max watermark.
+   */
+  async subscribe(streams) {
+    const client = await this._pool.connect();
+    try {
+      await client.query("BEGIN");
+      let subscribed = 0;
+      if (streams.length) {
+        const { rowCount: inserted } = await client.query(
+          `
+          INSERT INTO ${this._fqs} (stream, source, priority)
+          SELECT s->>'stream',
+                 s->>'source',
+                 COALESCE((s->>'priority')::int, 0)
+          FROM jsonb_array_elements($1::jsonb) AS s
+          ON CONFLICT (stream) DO NOTHING
+          `,
+          [JSON.stringify(streams)]
+        );
+        subscribed = inserted ?? 0;
+        await client.query(
+          `
+          UPDATE ${this._fqs} t
+          SET priority = COALESCE((s->>'priority')::int, 0)
+          FROM jsonb_array_elements($1::jsonb) AS s
+          WHERE t.stream = s->>'stream'
+            AND COALESCE((s->>'priority')::int, 0) > t.priority
+          `,
+          [JSON.stringify(streams)]
+        );
+      }
+      const { rows } = await client.query(
+        `SELECT COALESCE(MAX(at), -1) AS max FROM ${this._fqs}`
+      );
+      await client.query("COMMIT");
+      return { subscribed, watermark: rows[0]?.max ?? -1 };
+    } catch (error) {
+      await client.query("ROLLBACK").catch(() => {
+      });
+      logger.error(error);
+      return { subscribed: 0, watermark: -1 };
+    } finally {
+      client.release();
+    }
+  }
+  /**
+   * Acknowledge and release leases after processing, updating stream positions.
+   *
+   * @param leases - Leases to acknowledge, including last processed watermark and lease holder.
+   * @returns Acked leases.
+   */
+  async ack(leases) {
+    const client = await this._pool.connect();
+    try {
+      await client.query("BEGIN");
+      const { rows } = await client.query(
+        `
+      WITH input AS (
+        SELECT * FROM jsonb_to_recordset($1::jsonb)
+        AS x(stream text, by text, at int, lagging boolean)
+      )
+      UPDATE ${this._fqs} AS s
+      SET
+        at = i.at,
+        retry = -1,
+        leased_by = NULL,
+        leased_until = NULL
+      FROM input i
+      WHERE s.stream = i.stream AND s.leased_by = i.by
+      RETURNING s.stream, s.source, s.at, i.by, s.retry, i.lagging
+      `,
+        [JSON.stringify(leases)]
+      );
+      await client.query("COMMIT");
+      return rows.map((row) => ({
+        stream: row.stream,
+        source: row.source ?? void 0,
+        at: row.at,
+        by: row.by,
+        retry: row.retry,
+        lagging: row.lagging
+      }));
+    } catch (error) {
+      await client.query("ROLLBACK").catch(() => {
+      });
+      logger.error(error);
+      return [];
+    } finally {
+      client.release();
+    }
+  }
+  /**
+   * Block a stream for processing after failing to process and reaching max retries with blocking enabled.
+   * @param leases - Leases to block, including lease holder and last error message.
+   * @returns Blocked leases.
+   */
+  async block(leases) {
+    const client = await this._pool.connect();
+    try {
+      await client.query("BEGIN");
+      const { rows } = await client.query(
+        `
+      WITH input AS (
+        SELECT * FROM jsonb_to_recordset($1::jsonb)
+        AS x(stream text, by text, error text, lagging boolean)
+      )
+      UPDATE ${this._fqs} AS s
+      SET blocked = true, error = i.error
+      FROM input i
+      WHERE s.stream = i.stream AND s.leased_by = i.by AND s.blocked = false
+      RETURNING s.stream, s.source, s.at, i.by, s.retry, s.error, i.lagging
+      `,
+        [JSON.stringify(leases)]
+      );
+      await client.query("COMMIT");
+      return rows.map((row) => ({
+        stream: row.stream,
+        source: row.source ?? void 0,
+        at: row.at,
+        by: row.by,
+        retry: row.retry,
+        lagging: row.lagging,
+        error: row.error
+      }));
+    } catch (error) {
+      await client.query("ROLLBACK").catch(() => {
+      });
+      logger.error(error);
+      return [];
+    } finally {
+      client.release();
+    }
+  }
+  /**
+   * Reset watermarks for the given streams to -1, clearing retry, blocked,
+   * error, and lease state so they can be replayed from the beginning.
+   * @param streams - Stream names to reset.
+   * @returns Count of streams that were actually reset.
+   */
+  async reset(streams) {
+    if (!streams.length) return 0;
+    const { rowCount } = await this._pool.query(
+      `UPDATE ${this._fqs}
+       SET at = -1, retry = 0, blocked = false, error = NULL,
+           leased_by = NULL, leased_until = NULL
+       WHERE stream = ANY($1)`,
+      [streams]
+    );
+    return rowCount ?? 0;
+  }
+  /**
+   * Bulk-update priority of streams matching `filter` (ACT-102).
+   *
+   * Filter semantics mirror {@link query_streams}: regex on `stream` /
+   * `source` by default, exact match with the `_exact` flags,
+   * `blocked` restricts to blocked or unblocked rows. Empty filter
+   * (`{}`) updates every registered stream.
+   *
+   * Unlike {@link subscribe} (which keeps `max()` of registered
+   * priorities), this sets the priority outright — operator override
+   * for the build-time scheduling policy.
+   *
+   * @returns Count of streams whose priority changed.
+   */
+  async prioritize(filter, priority) {
+    const conditions = ["priority <> $1"];
+    const values = [priority];
+    if (filter.stream !== void 0) {
+      values.push(filter.stream);
+      conditions.push(
+        filter.stream_exact ? `stream = $${values.length}` : `stream ~ $${values.length}`
+      );
+    }
+    if (filter.source !== void 0) {
+      conditions.push(`source IS NOT NULL`);
+      values.push(filter.source);
+      conditions.push(
+        filter.source_exact ? `source = $${values.length}` : `source ~ $${values.length}`
+      );
+    }
+    if (filter.blocked !== void 0) {
+      values.push(filter.blocked);
+      conditions.push(`blocked = $${values.length}`);
+    }
+    const sql = `UPDATE ${this._fqs} SET priority = $1 WHERE ${conditions.join(" AND ")}`;
+    const { rowCount } = await this._pool.query(sql, values);
+    return rowCount ?? 0;
+  }
+  /**
+   * Streams subscription positions to a callback, ordered by stream name,
+   * along with the highest event id in the store.
+   *
+   * Filters (`stream`, `source`, `blocked`, `after`, `limit`) are applied
+   * server-side. `stream`/`source` are regex by default (`~`), or exact
+   * with `*_exact: true` — same convention as {@link Store.query}.
+   *
+   * @returns `maxEventId` and the `count` of positions emitted.
+   */
+  async query_streams(callback, query) {
+    const limit = query?.limit ?? 100;
+    const conditions = [];
+    const values = [];
+    if (query?.stream !== void 0) {
+      values.push(query.stream);
+      conditions.push(
+        query.stream_exact ? `stream = $${values.length}` : `stream ~ $${values.length}`
+      );
+    }
+    if (query?.source !== void 0) {
+      conditions.push(`source IS NOT NULL`);
+      values.push(query.source);
+      conditions.push(
+        query.source_exact ? `source = $${values.length}` : `source ~ $${values.length}`
+      );
+    }
+    if (query?.blocked !== void 0) {
+      values.push(query.blocked);
+      conditions.push(`blocked = $${values.length}`);
+    }
+    if (query?.after !== void 0) {
+      values.push(query.after);
+      conditions.push(`stream > $${values.length}`);
+    }
+    let sql = `SELECT stream, source, at, retry, blocked, error, leased_by, leased_until, priority FROM ${this._fqs}`;
+    if (conditions.length) sql += " WHERE " + conditions.join(" AND ");
+    values.push(limit);
+    sql += ` ORDER BY stream LIMIT $${values.length}`;
+    const client = await this._pool.connect();
+    try {
+      const [streamsResult, maxResult] = await Promise.all([
+        client.query(sql, values),
+        client.query(
+          `SELECT COALESCE(MAX(id), -1) AS m FROM ${this._fqt}`
+        )
+      ]);
+      let count = 0;
+      for (const row of streamsResult.rows) {
+        callback({
+          stream: row.stream,
+          source: row.source ?? void 0,
+          at: row.at,
+          retry: row.retry,
+          blocked: row.blocked,
+          error: row.error ?? "",
+          priority: row.priority,
+          leased_by: row.leased_by ?? void 0,
+          leased_until: row.leased_until ?? void 0
+        });
+        count++;
+      }
+      return { maxEventId: Number(maxResult.rows[0].m), count };
+    } finally {
+      client.release();
+    }
+  }
+  /**
+   * Implementation of the optional `Store.notify` hook. Bound onto
+   * `this.notify` in the constructor when `config.notify === true`,
+   * left detached otherwise — see {@link Config.notify}.
+   *
+   * Checks out a dedicated long-lived client from the pool, runs
+   * `LISTEN act_commit_<schema>_<table>`, and parses each incoming
+   * notification payload. The handler is invoked exactly once per
+   * **remote** commit — payloads originating from this same store
+   * instance (matched by the per-instance `_by` UUID) are silently
+   * skipped, giving callers a clean cross-process semantic.
+   *
+   * Multiple subscriptions on the same store instance are not supported —
+   * this method releases any prior LISTEN client before opening a new one.
+   * The returned disposer cleanly UNLISTENs and releases the dedicated
+   * client; pool disposal also tears the subscription down as a safety
+   * net.
+   *
+   * @param handler Called for each cross-process commit notification.
+   * @returns Disposer that releases the LISTEN client.
+   */
+  async _subscribeNotifications(handler) {
+    await this._teardownListen();
+    const client = await this._pool.connect();
+    const onNotification = (msg) => {
+      if (msg.channel !== this._channel) return;
+      if (!msg.payload) return;
+      let parsed;
+      try {
+        parsed = JSON.parse(msg.payload);
+      } catch (err) {
+        logger.error(
+          { err, payload: msg.payload },
+          "act_commit: malformed payload, skipping"
+        );
+        return;
+      }
+      if (parsed.by === this._by) return;
+      if (typeof parsed.stream !== "string" || !Array.isArray(parsed.events)) {
+        logger.error(
+          { payload: msg.payload },
+          "act_commit: payload missing required fields, skipping"
+        );
+        return;
+      }
+      const events = [];
+      for (const raw of parsed.events) {
+        if (raw && typeof raw === "object" && typeof raw.id === "number" && typeof raw.name === "string") {
+          events.push({
+            id: raw.id,
+            name: raw.name
+          });
+        }
+      }
+      if (events.length === 0) return;
+      try {
+        handler({ stream: parsed.stream, events });
+      } catch (err) {
+        logger.error(err, "act_commit: handler threw, listener preserved");
+      }
+    };
+    client.on("notification", onNotification);
+    try {
+      await client.query(`LISTEN ${this._channel}`);
+    } catch (err) {
+      client.removeListener("notification", onNotification);
+      client.release(true);
+      throw err;
+    }
+    this._listenClient = client;
+    this._listenHandler = onNotification;
+    return async () => {
+      if (this._listenClient !== client) return;
+      await this._teardownListen();
+    };
+  }
+  /**
+   * Atomically truncates streams and seeds each with a snapshot or tombstone.
+   * @param targets - Streams to truncate with optional snapshot state and meta.
+   * @returns Map keyed by stream name, each entry with `deleted` count and `committed` event.
+   */
+  async truncate(targets) {
+    if (!targets.length) return /* @__PURE__ */ new Map();
+    const streams = targets.map((t) => t.stream);
+    const client = await this._pool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query(`DELETE FROM ${this._fqs} WHERE stream = ANY($1)`, [
+        streams
+      ]);
+      const result = /* @__PURE__ */ new Map();
+      for (const { stream, snapshot, meta } of targets) {
+        const { rowCount } = await client.query(
+          `DELETE FROM ${this._fqt} WHERE stream = $1`,
+          [stream]
+        );
+        const name = snapshot !== void 0 ? SNAP_EVENT : TOMBSTONE_EVENT;
+        const { rows } = await client.query(
+          `INSERT INTO ${this._fqt}(name, data, stream, version, created, meta)
+           VALUES($1, $2, $3, 0, now(), $4) RETURNING *`,
+          [
+            name,
+            snapshot ?? {},
+            stream,
+            meta ?? { correlation: "", causation: {} }
+          ]
+        );
+        result.set(stream, {
+          deleted: rowCount ?? 0,
+          committed: rows[0]
+        });
+      }
+      await client.query("COMMIT");
+      return result;
+    } catch (error) {
+      await client.query("ROLLBACK").catch(() => {
+      });
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+};
+export {
+  PostgresStore
+};
+//# sourceMappingURL=index.js.map