@reventlessdev/reventless-postgres 3.0.0-alpha.1

package/lib/bs/src/PgDriver.resi

@@ -0,0 +1,68 @@
+// Sealed wrapper around node-postgres (`pg`).
+//
+// Unlike SqliteDriver (node:sqlite, synchronous), every operation here is
+// asynchronous — there is no synchronous Postgres client in Node. Storage
+// makers stay synchronous (they only close over a `pool`); the async cost lands
+// where the adapter operations already are (`append`/`read` return promises).
+// Schema setup (`PgSchema.ensureSchema`) is therefore a distinct async step run
+// once before any maker, not an inline `ensureSchema` inside the maker.
+//
+// The interface is kept tight so a different driver could be dropped in later
+// without callers changing.
+
+type pool
+type client
+
+// TLS options. Required for RDS/managed Postgres (PG15+ defaults to
+// `rds.force_ssl=1`). `rejectUnauthorized: false` encrypts without CA
+// verification.
+type sslConfig = {rejectUnauthorized: bool}
+
+// Invoked by pg per physical connection, so a rotated secret is picked up on the
+// next new connection without rebuilding the pool.
+type passwordProvider = unit => promise<string>
+
+type poolConfig = {
+  // Supply either a full `connectionString` (local/dev) or the discrete fields
+  // (AWS adapter — password comes from a Secrets Manager provider that can't be
+  // baked into a static string).
+  connectionString?: string,
+  host?: string,
+  port?: int,
+  database?: string,
+  user?: string,
+  password?: passwordProvider,
+  ssl?: sslConfig,
+  // Upper bound on pooled connections. Defaults to pg's own default (10).
+  max?: int,
+}
+
+let makePool: poolConfig => pool
+let endPool: pool => promise<unit>
+
+// Parameterised query (extended protocol — exactly one statement). Returns the
+// result rows. Postgres returns `bigint`/`xid8` as strings, `jsonb` already
+// parsed, and `text[]` as a JS array — all directly usable as `JSON.t`.
+let query: (pool, string, array<JSON.t>) => promise<array<dict<JSON.t>>>
+
+// Parameterised query returning the first row, or None.
+let queryOne: (pool, string, array<JSON.t>) => promise<option<dict<JSON.t>>>
+
+// Simple-protocol statement with no parameters — allows multi-statement DDL and
+// dollar-quoted function bodies. Used by PgSchema.
+let exec: (pool, string) => promise<unit>
+
+// Run `fn` inside BEGIN/COMMIT on a single checked-out connection. Rolls back on
+// any rejected promise or thrown exception, then always releases the connection.
+// Transaction-scoped advisory locks require this single-connection guarantee.
+let transaction: (pool, client => promise<'a>) => promise<'a>
+
+// Same as `query`, but on an explicit transaction connection.
+let queryOn: (client, string, array<JSON.t>) => promise<array<dict<JSON.t>>>
+let execOn: (client, string) => promise<unit>
+
+// Open a dedicated long-lived connection issuing `LISTEN <channel>`, invoking
+// `onNotify` with each notification payload. The returned client is caller-owned
+// (call `unlisten` to `UNLISTEN` + release). Used by the change feed (Phase D).
+let listen: (pool, ~channel: string, ~onNotify: string => unit) => promise<client>
+let unlisten: (client, ~channel: string) => promise<unit>

package/lib/bs/src/PgSchema.res

@@ -0,0 +1,256 @@
+// Idempotent schema + migration runner for the Postgres backend.
+//
+// `ensureSchema(pool)` is callable from any deploy-time context or standalone.
+// The package depends on no IaC/provider SDK; a platform that embeds this
+// storage is responsible for emitting the deploy-time resource that runs it.
+//
+// It creates:
+//   event_log / snapshot      — classic OCC log (Phase A)
+//   dcb_event                 — DCB log; positions are a global IDENTITY sequence,
+//                               rows stamped with the committing xid8 (Phase B)
+//   dcb_scope                 — companion table for the #RowLocks strategy (B4)
+//   dcb_subscription          — change-feed checkpoints (Phase D)
+//   dcb_condition_where(...)  — compiles a DcbTag.query jsonb AST → SQL WHERE
+//   dcb_append(...)           — the concurrency-critical append (B1): scoped
+//                               advisory locks + exact check + insert + NOTIFY,
+//                               one round trip, transaction-scoped.
+
+// Table / index DDL. Every statement is individually idempotent so ensureSchema
+// is safe to run on every startup and concurrently across processes.
+let tableStatements = [
+  // --- Classic event log (Phase A) ---
+  "CREATE TABLE IF NOT EXISTS event_log (
+     log_name      text   NOT NULL,
+     aggregate_id  text   NOT NULL,
+     seq_nr        bigint NOT NULL,
+     payload       jsonb  NOT NULL,
+     msg_id        text,
+     global_seq    bigint GENERATED ALWAYS AS IDENTITY,
+     PRIMARY KEY (log_name, aggregate_id, seq_nr)
+   )",
+  "CREATE TABLE IF NOT EXISTS snapshot (
+     log_name      text   NOT NULL,
+     aggregate_id  text   NOT NULL,
+     seq_nr        bigint NOT NULL,
+     state         jsonb  NOT NULL,
+     schema_hash   text   NOT NULL,
+     PRIMARY KEY (log_name, aggregate_id)
+   )",
+  // --- DCB event log (Phase B) ---
+  "CREATE TABLE IF NOT EXISTS dcb_event (
+     log_name        text        NOT NULL,
+     position        bigint      GENERATED ALWAYS AS IDENTITY,
+     transaction_id  xid8        NOT NULL DEFAULT pg_current_xact_id(),
+     event_type      text        NOT NULL,
+     tags            text[]      NOT NULL DEFAULT '{}',
+     data            jsonb       NOT NULL,
+     meta            jsonb       NOT NULL,
+     recorded_at     timestamptz NOT NULL DEFAULT now(),
+     PRIMARY KEY (log_name, position)
+   )",
+  "CREATE INDEX IF NOT EXISTS dcb_event_tags_gin ON dcb_event USING gin (tags)",
+  "CREATE INDEX IF NOT EXISTS dcb_event_type_pos ON dcb_event (log_name, event_type, position)",
+  "CREATE INDEX IF NOT EXISTS dcb_event_tx_pos   ON dcb_event (log_name, transaction_id, position)",
+  // --- Row-lock companion (B4) ---
+  "CREATE TABLE IF NOT EXISTS dcb_scope (
+     log_name    text   NOT NULL,
+     scope_hash  bigint NOT NULL,
+     PRIMARY KEY (log_name, scope_hash)
+   )",
+  // --- Change-feed checkpoints (Phase D) ---
+  "CREATE TABLE IF NOT EXISTS dcb_subscription (
+     subscriber    text   PRIMARY KEY,
+     last_tx       xid8   NOT NULL DEFAULT '0'::xid8,
+     last_position bigint NOT NULL DEFAULT 0
+   )",
+]
+
+// Compiles a DcbTag.query jsonb AST to a SQL WHERE fragment against `dcb_event`.
+// The AST is `[ {eventTypes: [text]|null, tags: [text]|null}, ... ]` — an OR of
+// clauses; within a clause the tags array is `@>`-contained and event types are
+// an IN list. All embedded values pass through quote_literal (the values are
+// framework-controlled tag/event strings, but escaping is non-negotiable for
+// EXECUTE'd SQL). Tags are encoded 'key=value' to match the dcb_event.tags column.
+//
+// `after` is the two-column cursor decoded to (p_after_tx, p_after_pos); the
+// generated fragment is the exact `(transaction_id, position) > (tx, pos)`
+// comparison reads use, so read → decide → conditional-append is exact.
+let dcbConditionWhereFn = "
+CREATE OR REPLACE FUNCTION dcb_after_frag(p_tx xid8, p_pos bigint) RETURNS text
+LANGUAGE sql IMMUTABLE AS $af$
+  SELECT CASE WHEN p_tx IS NULL THEN NULL ELSE
+    '(transaction_id > ' || quote_literal(p_tx::text) || '::xid8 OR (transaction_id = '
+    || quote_literal(p_tx::text) || '::xid8 AND position > ' || p_pos::text || '))'
+  END;
+$af$;
+
+CREATE OR REPLACE FUNCTION dcb_condition_where(
+  p_log_name text,
+  p_query    jsonb,
+  p_after_tx  xid8,
+  p_after_pos bigint
+) RETURNS text
+LANGUAGE plpgsql IMMUTABLE AS $fn$
+DECLARE
+  v_clauses text[] := '{}';
+  v_parts   text[];
+  v_types   text;
+  v_tags    text;
+  v_after   text := dcb_after_frag(p_after_tx, p_after_pos);
+  qi        jsonb;
+BEGIN
+  IF p_query IS NULL OR jsonb_array_length(p_query) = 0 THEN
+    v_types := 'log_name = ' || quote_literal(p_log_name);
+    IF v_after IS NOT NULL THEN
+      v_types := v_types || ' AND ' || v_after;
+    END IF;
+    RETURN v_types;
+  END IF;
+
+  FOR qi IN SELECT * FROM jsonb_array_elements(p_query) LOOP
+    v_parts := ARRAY['log_name = ' || quote_literal(p_log_name)];
+    IF v_after IS NOT NULL THEN
+      v_parts := array_append(v_parts, v_after);
+    END IF;
+
+    IF jsonb_typeof(qi->'eventTypes') = 'array'
+       AND jsonb_array_length(qi->'eventTypes') > 0 THEN
+      SELECT string_agg(quote_literal(t), ',')
+        INTO v_types
+        FROM jsonb_array_elements_text(qi->'eventTypes') t;
+      v_parts := array_append(v_parts, 'event_type IN (' || v_types || ')');
+    END IF;
+
+    IF jsonb_typeof(qi->'tags') = 'array'
+       AND jsonb_array_length(qi->'tags') > 0 THEN
+      SELECT string_agg(quote_literal(t), ',')
+        INTO v_tags
+        FROM jsonb_array_elements_text(qi->'tags') t;
+      v_parts := array_append(v_parts, 'tags @> ARRAY[' || v_tags || ']::text[]');
+    END IF;
+
+    v_clauses := array_append(v_clauses, '(' || array_to_string(v_parts, ' AND ') || ')');
+  END LOOP;
+
+  RETURN array_to_string(v_clauses, ' OR ');
+END;
+$fn$;
+"
+
+// The append. Called as `SELECT dcb_append($1,$2::jsonb,$3::jsonb,$4)` — a single
+// simple statement, so the implicit transaction holds every advisory lock until
+// the insert commits. Returns the encoded cursor `<xid8>:<position>` (both
+// zero-padded to 20 digits so string order == numeric order) of the last event.
+//
+// Lock scope (advisory strategy): a deterministic hashtextextended() of every
+// tag carried by the written events OR referenced in the condition query,
+// namespaced per log_name, acquired in sorted order (deadlock-free). Lock scope
+// controls only *what serializes*; the check itself is exact, so a coarse scope
+// (hash collision) can only delay an append, never wrongly reject it.
+let dcbAppendFn = "
+CREATE OR REPLACE FUNCTION dcb_append(
+  p_log_name      text,
+  p_events        jsonb,
+  p_condition     jsonb DEFAULT NULL,
+  p_lock_strategy text  DEFAULT 'advisory'
+) RETURNS text
+LANGUAGE plpgsql AS $fn$
+DECLARE
+  v_lock_keys bigint[];
+  v_after_raw text;
+  v_after_tx  xid8;
+  v_after_pos bigint;
+  v_where     text;
+  v_conflict  boolean;
+  v_last_pos  bigint;
+  v_key       bigint;
+BEGIN
+  -- 1. Lock keys: every tag in written events UNION every tag in the condition.
+  SELECT array_agg(DISTINCT k ORDER BY k) INTO v_lock_keys
+  FROM (
+    SELECT hashtextextended(p_log_name || '=' || tag, 0) AS k
+      FROM jsonb_array_elements(p_events) ev,
+           jsonb_array_elements_text(ev->'tags') tag
+    UNION
+    SELECT hashtextextended(p_log_name || '=' || tag, 0) AS k
+      FROM jsonb_array_elements(COALESCE(p_condition->'query', '[]'::jsonb)) qi,
+           jsonb_array_elements_text(COALESCE(qi->'tags', '[]'::jsonb)) tag
+  ) s;
+
+  -- 2. Acquire in sorted order.
+  IF v_lock_keys IS NOT NULL THEN
+    IF p_lock_strategy = 'rows' THEN
+      INSERT INTO dcb_scope(log_name, scope_hash)
+        SELECT p_log_name, k FROM unnest(v_lock_keys) k
+        ON CONFLICT DO NOTHING;
+      PERFORM 1 FROM dcb_scope
+        WHERE log_name = p_log_name AND scope_hash = ANY(v_lock_keys)
+        ORDER BY scope_hash
+        FOR UPDATE;
+    ELSE
+      FOREACH v_key IN ARRAY v_lock_keys LOOP
+        PERFORM pg_advisory_xact_lock(v_key);
+      END LOOP;
+    END IF;
+  END IF;
+
+  -- 3. Exact condition check under the held locks (READ COMMITTED is race-free
+  --    here: a conflicting concurrent writer is either committed+visible or
+  --    blocked on our lock).
+  IF p_condition IS NOT NULL THEN
+    v_after_raw := NULLIF(p_condition->>'after', '');
+    IF v_after_raw IS NOT NULL THEN
+      -- Cursor is '<xid8>:<position>', each zero-padded to 20 digits. Strip the
+      -- padding before casting (bigint tolerates leading zeros; be explicit for
+      -- xid8, guarding the all-zeros case).
+      v_after_tx  := COALESCE(NULLIF(ltrim(split_part(v_after_raw, ':', 1), '0'), ''), '0')::xid8;
+      v_after_pos := split_part(v_after_raw, ':', 2)::bigint;
+    END IF;
+    v_where := dcb_condition_where(p_log_name, p_condition->'query', v_after_tx, v_after_pos);
+    EXECUTE 'SELECT EXISTS (SELECT 1 FROM dcb_event WHERE ' || v_where || ')'
+      INTO v_conflict;
+    IF v_conflict THEN
+      RAISE EXCEPTION 'dcb_conflict' USING ERRCODE = 'P0001';
+    END IF;
+  END IF;
+
+  -- 4. Insert every event in array order; positions come from the IDENTITY seq.
+  WITH ins AS (
+    INSERT INTO dcb_event(log_name, event_type, tags, data, meta)
+    SELECT p_log_name,
+           ev->>'event_type',
+           ARRAY(SELECT jsonb_array_elements_text(ev->'tags')),
+           ev->'data',
+           ev->'meta'
+      FROM jsonb_array_elements(p_events) WITH ORDINALITY AS t(ev, ord)
+     ORDER BY ord
+    RETURNING position
+  )
+  SELECT max(position) INTO v_last_pos FROM ins;
+
+  -- 5. Wake the change feed (Phase D). No-op if nobody is LISTENing.
+  PERFORM pg_notify('dcb_' || p_log_name, v_last_pos::text);
+
+  RETURN lpad(pg_current_xact_id()::text, 20, '0') || ':' || lpad(v_last_pos::text, 20, '0');
+END;
+$fn$;
+"
+
+let functionStatements = [dcbConditionWhereFn, dcbAppendFn]
+
+let ensureSchema = async (pool: PgDriver.pool): unit => {
+  for i in 0 to tableStatements->Array.length - 1 {
+    await pool->PgDriver.exec(tableStatements->Array.getUnsafe(i))
+  }
+  for i in 0 to functionStatements->Array.length - 1 {
+    await pool->PgDriver.exec(functionStatements->Array.getUnsafe(i))
+  }
+}
+
+// resetOnStart support: TRUNCATE (never DROP) so the schema/functions survive.
+// Mirrors the reventless-local contract that reset wipes data, not structure.
+let truncateAll = async (pool: PgDriver.pool): unit => {
+  await pool->PgDriver.exec(
+    "TRUNCATE event_log, snapshot, dcb_event, dcb_scope, dcb_subscription RESTART IDENTITY",
+  )
+}

package/lib/bs/src/PgSchema.res.mjs

@@ -0,0 +1,46 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as PgDriver$ReventlessPostgres from "./PgDriver.res.mjs";
+
+let tableStatements = [
+  "CREATE TABLE IF NOT EXISTS event_log (\n     log_name      text   NOT NULL,\n     aggregate_id  text   NOT NULL,\n     seq_nr        bigint NOT NULL,\n     payload       jsonb  NOT NULL,\n     msg_id        text,\n     global_seq    bigint GENERATED ALWAYS AS IDENTITY,\n     PRIMARY KEY (log_name, aggregate_id, seq_nr)\n   )",
+  "CREATE TABLE IF NOT EXISTS snapshot (\n     log_name      text   NOT NULL,\n     aggregate_id  text   NOT NULL,\n     seq_nr        bigint NOT NULL,\n     state         jsonb  NOT NULL,\n     schema_hash   text   NOT NULL,\n     PRIMARY KEY (log_name, aggregate_id)\n   )",
+  "CREATE TABLE IF NOT EXISTS dcb_event (\n     log_name        text        NOT NULL,\n     position        bigint      GENERATED ALWAYS AS IDENTITY,\n     transaction_id  xid8        NOT NULL DEFAULT pg_current_xact_id(),\n     event_type      text        NOT NULL,\n     tags            text[]      NOT NULL DEFAULT '{}',\n     data            jsonb       NOT NULL,\n     meta            jsonb       NOT NULL,\n     recorded_at     timestamptz NOT NULL DEFAULT now(),\n     PRIMARY KEY (log_name, position)\n   )",
+  "CREATE INDEX IF NOT EXISTS dcb_event_tags_gin ON dcb_event USING gin (tags)",
+  "CREATE INDEX IF NOT EXISTS dcb_event_type_pos ON dcb_event (log_name, event_type, position)",
+  "CREATE INDEX IF NOT EXISTS dcb_event_tx_pos   ON dcb_event (log_name, transaction_id, position)",
+  "CREATE TABLE IF NOT EXISTS dcb_scope (\n     log_name    text   NOT NULL,\n     scope_hash  bigint NOT NULL,\n     PRIMARY KEY (log_name, scope_hash)\n   )",
+  "CREATE TABLE IF NOT EXISTS dcb_subscription (\n     subscriber    text   PRIMARY KEY,\n     last_tx       xid8   NOT NULL DEFAULT '0'::xid8,\n     last_position bigint NOT NULL DEFAULT 0\n   )"
+];
+
+let dcbConditionWhereFn = "\nCREATE OR REPLACE FUNCTION dcb_after_frag(p_tx xid8, p_pos bigint) RETURNS text\nLANGUAGE sql IMMUTABLE AS $af$\n  SELECT CASE WHEN p_tx IS NULL THEN NULL ELSE\n    '(transaction_id > ' || quote_literal(p_tx::text) || '::xid8 OR (transaction_id = '\n    || quote_literal(p_tx::text) || '::xid8 AND position > ' || p_pos::text || '))'\n  END;\n$af$;\n\nCREATE OR REPLACE FUNCTION dcb_condition_where(\n  p_log_name text,\n  p_query    jsonb,\n  p_after_tx  xid8,\n  p_after_pos bigint\n) RETURNS text\nLANGUAGE plpgsql IMMUTABLE AS $fn$\nDECLARE\n  v_clauses text[] := '{}';\n  v_parts   text[];\n  v_types   text;\n  v_tags    text;\n  v_after   text := dcb_after_frag(p_after_tx, p_after_pos);\n  qi        jsonb;\nBEGIN\n  IF p_query IS NULL OR jsonb_array_length(p_query) = 0 THEN\n    v_types := 'log_name = ' || quote_literal(p_log_name);\n    IF v_after IS NOT NULL THEN\n      v_types := v_types || ' AND ' || v_after;\n    END IF;\n    RETURN v_types;\n  END IF;\n\n  FOR qi IN SELECT * FROM jsonb_array_elements(p_query) LOOP\n    v_parts := ARRAY['log_name = ' || quote_literal(p_log_name)];\n    IF v_after IS NOT NULL THEN\n      v_parts := array_append(v_parts, v_after);\n    END IF;\n\n    IF jsonb_typeof(qi->'eventTypes') = 'array'\n       AND jsonb_array_length(qi->'eventTypes') > 0 THEN\n      SELECT string_agg(quote_literal(t), ',')\n        INTO v_types\n        FROM jsonb_array_elements_text(qi->'eventTypes') t;\n      v_parts := array_append(v_parts, 'event_type IN (' || v_types || ')');\n    END IF;\n\n    IF jsonb_typeof(qi->'tags') = 'array'\n       AND jsonb_array_length(qi->'tags') > 0 THEN\n      SELECT string_agg(quote_literal(t), ',')\n        INTO v_tags\n        FROM jsonb_array_elements_text(qi->'tags') t;\n      v_parts := array_append(v_parts, 'tags @> ARRAY[' || v_tags || ']::text[]');\n    END IF;\n\n    v_clauses := array_append(v_clauses, '(' || array_to_string(v_parts, ' AND ') || ')');\n  END LOOP;\n\n  RETURN array_to_string(v_clauses, ' OR ');\nEND;\n$fn$;\n";
+
+let dcbAppendFn = "\nCREATE OR REPLACE FUNCTION dcb_append(\n  p_log_name      text,\n  p_events        jsonb,\n  p_condition     jsonb DEFAULT NULL,\n  p_lock_strategy text  DEFAULT 'advisory'\n) RETURNS text\nLANGUAGE plpgsql AS $fn$\nDECLARE\n  v_lock_keys bigint[];\n  v_after_raw text;\n  v_after_tx  xid8;\n  v_after_pos bigint;\n  v_where     text;\n  v_conflict  boolean;\n  v_last_pos  bigint;\n  v_key       bigint;\nBEGIN\n  -- 1. Lock keys: every tag in written events UNION every tag in the condition.\n  SELECT array_agg(DISTINCT k ORDER BY k) INTO v_lock_keys\n  FROM (\n    SELECT hashtextextended(p_log_name || '=' || tag, 0) AS k\n      FROM jsonb_array_elements(p_events) ev,\n           jsonb_array_elements_text(ev->'tags') tag\n    UNION\n    SELECT hashtextextended(p_log_name || '=' || tag, 0) AS k\n      FROM jsonb_array_elements(COALESCE(p_condition->'query', '[]'::jsonb)) qi,\n           jsonb_array_elements_text(COALESCE(qi->'tags', '[]'::jsonb)) tag\n  ) s;\n\n  -- 2. Acquire in sorted order.\n  IF v_lock_keys IS NOT NULL THEN\n    IF p_lock_strategy = 'rows' THEN\n      INSERT INTO dcb_scope(log_name, scope_hash)\n        SELECT p_log_name, k FROM unnest(v_lock_keys) k\n        ON CONFLICT DO NOTHING;\n      PERFORM 1 FROM dcb_scope\n        WHERE log_name = p_log_name AND scope_hash = ANY(v_lock_keys)\n        ORDER BY scope_hash\n        FOR UPDATE;\n    ELSE\n      FOREACH v_key IN ARRAY v_lock_keys LOOP\n        PERFORM pg_advisory_xact_lock(v_key);\n      END LOOP;\n    END IF;\n  END IF;\n\n  -- 3. Exact condition check under the held locks (READ COMMITTED is race-free\n  --    here: a conflicting concurrent writer is either committed+visible or\n  --    blocked on our lock).\n  IF p_condition IS NOT NULL THEN\n    v_after_raw := NULLIF(p_condition->>'after', '');\n    IF v_after_raw IS NOT NULL THEN\n      -- Cursor is '<xid8>:<position>', each zero-padded to 20 digits. Strip the\n      -- padding before casting (bigint tolerates leading zeros; be explicit for\n      -- xid8, guarding the all-zeros case).\n      v_after_tx  := COALESCE(NULLIF(ltrim(split_part(v_after_raw, ':', 1), '0'), ''), '0')::xid8;\n      v_after_pos := split_part(v_after_raw, ':', 2)::bigint;\n    END IF;\n    v_where := dcb_condition_where(p_log_name, p_condition->'query', v_after_tx, v_after_pos);\n    EXECUTE 'SELECT EXISTS (SELECT 1 FROM dcb_event WHERE ' || v_where || ')'\n      INTO v_conflict;\n    IF v_conflict THEN\n      RAISE EXCEPTION 'dcb_conflict' USING ERRCODE = 'P0001';\n    END IF;\n  END IF;\n\n  -- 4. Insert every event in array order; positions come from the IDENTITY seq.\n  WITH ins AS (\n    INSERT INTO dcb_event(log_name, event_type, tags, data, meta)\n    SELECT p_log_name,\n           ev->>'event_type',\n           ARRAY(SELECT jsonb_array_elements_text(ev->'tags')),\n           ev->'data',\n           ev->'meta'\n      FROM jsonb_array_elements(p_events) WITH ORDINALITY AS t(ev, ord)\n     ORDER BY ord\n    RETURNING position\n  )\n  SELECT max(position) INTO v_last_pos FROM ins;\n\n  -- 5. Wake the change feed (Phase D). No-op if nobody is LISTENing.\n  PERFORM pg_notify('dcb_' || p_log_name, v_last_pos::text);\n\n  RETURN lpad(pg_current_xact_id()::text, 20, '0') || ':' || lpad(v_last_pos::text, 20, '0');\nEND;\n$fn$;\n";
+
+let functionStatements = [
+  dcbConditionWhereFn,
+  dcbAppendFn
+];
+
+async function ensureSchema(pool) {
+  for (let i = 0, i_finish = tableStatements.length; i < i_finish; ++i) {
+    await PgDriver$ReventlessPostgres.exec(pool, tableStatements[i]);
+  }
+  for (let i$1 = 0, i_finish$1 = functionStatements.length; i$1 < i_finish$1; ++i$1) {
+    await PgDriver$ReventlessPostgres.exec(pool, functionStatements[i$1]);
+  }
+}
+
+async function truncateAll(pool) {
+  return await PgDriver$ReventlessPostgres.exec(pool, "TRUNCATE event_log, snapshot, dcb_event, dcb_scope, dcb_subscription RESTART IDENTITY");
+}
+
+export {
+  tableStatements,
+  dcbConditionWhereFn,
+  dcbAppendFn,
+  functionStatements,
+  ensureSchema,
+  truncateAll,
+}
+/* PgDriver-ReventlessPostgres Not a pure module */

package/lib/bs/src/QueryDbStorage_Postgres.res

@@ -0,0 +1,244 @@
+// Postgres-backed QueryDb storage — JSONB document tables, one per read model.
+//
+// Implements the clean QueryDb_Adapter.storageMaker (the shape
+// QueryDbStorage_DynamoDb implements): no in-process bus. The reventless-local
+// bridge that publishes state-changes to live GraphQL subscriptions wraps this
+// at integration time (Phase E), the way QueryDbStorage_Sqlite wraps its data
+// access today.
+//
+// Table `qdb_<name>`: partition_key text, sub_key text, item jsonb, expires_at
+// double precision (unix epoch seconds; null = never), PRIMARY KEY
+// (partition_key, sub_key). `item jsonb` returns already parsed. TTL is lazy —
+// every read carries `(expires_at IS NULL OR expires_at > epoch_now)`.
+//
+// GSI: each declared indexConfig becomes an expression index on `item->>'field'`
+// (composite keys concatenated with the configured separator). projectionType is
+// irrelevant in a relational store (every column is on the same row).
+
+open ReventlessCore
+open Reventless.ReadModel
+
+let tableName = (name: string): string => "qdb_" ++ name->String.replaceAll("-", "_")
+
+// Collapse anything outside [A-Za-z0-9_] to _ — predictable, injection-safe idents.
+let sanitizeIdent = (s: string): string =>
+  s->String.replaceRegExp(%re("/[^A-Za-z0-9_]/g"), "_")
+
+let notExpiredClause = "(expires_at IS NULL OR expires_at > extract(epoch from now()))"
+
+// JSONB text extraction for a single top-level field.
+let jsonField = (field: string): string =>
+  `(item->>'${field->String.replaceAll("'", "''")}')`
+
+let compositeExpr = (fields: array<string>, sep: string): string => {
+  let escapedSep = sep->String.replaceAll("'", "''")
+  fields->Array.map(jsonField)->Array.join(` || '${escapedSep}' || `)
+}
+
+let indexExpressions = (idx: indexConfig): (string, option<string>) => {
+  let pkExpr = switch idx.pkFields {
+  | Some(fields) if fields->Array.length > 0 => compositeExpr(fields, idx.pkSep->Option.getOr("/"))
+  | _ =>
+    switch idx.idField {
+    | Some(field) => jsonField(field)
+    | None => jsonField(idx.index)
+    }
+  }
+  let skExpr = switch idx.skFields {
+  | Some(fields) if fields->Array.length > 0 =>
+    Some(compositeExpr(fields, idx.skSep->Option.getOr("/")))
+  | _ =>
+    switch idx.subIdField {
+    | Some(field) => Some(jsonField(field))
+    | None => None
+    }
+  }
+  (pkExpr, skExpr)
+}
+
+let ensureTable = async (~pool, ~table) => {
+  await pool->PgDriver.exec(
+    `CREATE TABLE IF NOT EXISTS ${table} (partition_key text NOT NULL, sub_key text NOT NULL DEFAULT '', item jsonb NOT NULL, expires_at double precision, PRIMARY KEY (partition_key, sub_key))`,
+  )
+}
+
+let ensureIndexes = async (~pool, ~table, ~indexes: array<indexConfig>) => {
+  for i in 0 to indexes->Array.length - 1 {
+    let idx = indexes->Array.getUnsafe(i)
+    let (pkExpr, skExprOpt) = indexExpressions(idx)
+    let indexName = `idx_${table}_${sanitizeIdent(idx.index)}`
+    let cols = switch skExprOpt {
+    | Some(skExpr) => `${pkExpr}, ${skExpr}`
+    | None => pkExpr
+    }
+    await pool->PgDriver.exec(`CREATE INDEX IF NOT EXISTS ${indexName} ON ${table} (${cols})`)
+  }
+}
+
+let decodeItem = (row: dict<JSON.t>): JSON.t =>
+  row->Dict.get("item")->Option.getOr(JSON.Encode.null)
+
+let computeSubKey = (item: JSON.t, subIdField: option<string>): string =>
+  switch subIdField {
+  | None => ""
+  | Some(field) =>
+    switch item->JSON.Decode.object->Option.flatMap(o => o->Dict.get(field)) {
+    | Some(JSON.String(s)) => s
+    | _ => ""
+    }
+  }
+
+let withId = (item: JSON.t, partitionKey: string): JSON.t =>
+  switch item->JSON.Decode.object {
+  | Some(obj) if obj->Dict.get("id")->Option.isNone =>
+    let copy = Dict.copy(obj)
+    copy->Dict.set("id", JSON.Encode.string(partitionKey))
+    JSON.Encode.object(copy)
+  | _ => item
+  }
+
+let makeStorage = (
+  ~pool: PgDriver.pool,
+  ~name: string,
+  ~indexes: array<indexConfig>,
+  ~subIdField: option<string>,
+): QueryDb_Adapter.storage => {
+  let table = tableName(name)
+  // Schema setup is async but makeStorage is synchronous; gate every operation on
+  // this promise so the first access waits for table + index creation exactly
+  // once (subsequent awaits resolve immediately).
+  let ready = {
+    open Promise
+    ensureTable(~pool, ~table)->then(() => ensureIndexes(~pool, ~table, ~indexes))
+  }
+
+  let rowsFor = async (id: string): array<JSON.t> => {
+    await ready
+    (await pool->PgDriver.query(
+      `SELECT item FROM ${table} WHERE partition_key = $1 AND ${notExpiredClause} ORDER BY sub_key ASC`,
+      [JSON.Encode.string(id)],
+    ))->Array.map(decodeItem)
+  }
+
+  let saveOne = async (id: string, state: JSON.t, ttl: option<int>) => {
+    await ready
+    let subKey = computeSubKey(state, subIdField)
+    let expiresAt = switch ttl {
+    | Some(t) => JSON.Encode.int(t)
+    | None => JSON.Encode.null
+    }
+    let _ = await pool->PgDriver.query(
+      `INSERT INTO ${table}(partition_key, sub_key, item, expires_at)
+       VALUES ($1, $2, $3::jsonb, $4)
+       ON CONFLICT (partition_key, sub_key)
+       DO UPDATE SET item = EXCLUDED.item, expires_at = EXCLUDED.expires_at`,
+      [
+        JSON.Encode.string(id),
+        JSON.Encode.string(subKey),
+        JSON.Encode.string(JSON.stringify(state)),
+        expiresAt,
+      ],
+    )
+  }
+
+  let load: QueryDb.load<string, JSON.t> = async id => Ok(await rowsFor(id))
+
+  let loadStream: QueryDb.loadStream<string, JSON.t> =
+    id =>
+      Effect.promise(() => rowsFor(id))
+      ->Stream.fromEffect
+      ->Stream.flatMap(arr => Stream.fromIterable(arr))
+
+  let save: QueryDb.save<string, JSON.t> = async (id, state, _saveMode, ttl) => {
+    await saveOne(id, state, ttl)
+    Ok()
+  }
+
+  let saveBatch: QueryDb.saveBatch<string, JSON.t> = async batch => {
+    // pg has no synchronous multi-statement transaction helper here; the upserts
+    // are independent (distinct keys) so a sequential apply is equivalent.
+    for i in 0 to batch->Array.length - 1 {
+      let (id, state, ttl) = batch->Array.getUnsafe(i)
+      await saveOne(id, state, ttl)
+    }
+    Ok()
+  }
+
+  // Mirror DynamoDB's `ADD #field :inc`: read the counter on the partition item
+  // (counters are single-state, sub_key=""), add inc, upsert, return NEW total.
+  let count: QueryDb.count<string> = async (id, fieldName, inc) => {
+    await ready
+    let existing = (await rowsFor(id))->Array.get(0)->Option.flatMap(JSON.Decode.object)
+    let current =
+      existing
+      ->Option.flatMap(o => o->Dict.get(fieldName))
+      ->Option.flatMap(JSON.Decode.float)
+      ->Option.mapOr(0, Float.toInt)
+    let next = current + inc
+    let obj = switch existing {
+    | Some(o) => Dict.copy(o)
+    | None => Dict.make()
+    }
+    obj->Dict.set("id", JSON.Encode.string(id))
+    obj->Dict.set(fieldName, JSON.Encode.int(next))
+    await saveOne(id, JSON.Encode.object(obj), None)
+    Ok(next)
+  }
+
+  let delete: QueryDb.delete<string> = async (id, subIdOpt) => {
+    await ready
+    let _ = switch subIdOpt {
+    | None =>
+      await pool->PgDriver.query(
+        `DELETE FROM ${table} WHERE partition_key = $1`,
+        [JSON.Encode.string(id)],
+      )
+    | Some((_, subValue)) =>
+      await pool->PgDriver.query(
+        `DELETE FROM ${table} WHERE partition_key = $1 AND sub_key = $2`,
+        [JSON.Encode.string(id), JSON.Encode.string(subValue)],
+      )
+    }
+    Ok()
+  }
+
+  let deleteBatch: QueryDb.deleteBatch<string> = async ids => {
+    for i in 0 to ids->Array.length - 1 {
+      let (id, subIdOpt) = ids->Array.getUnsafe(i)
+      let _ = await delete(id, subIdOpt)
+    }
+    Ok()
+  }
+
+  let ops: QueryDb_Adapter.operations = {
+    load,
+    loadStream,
+    save,
+    saveBatch,
+    count,
+    delete,
+    deleteBatch,
+  }
+
+  {
+    QueryDb_Adapter.resources: [],
+    dataSourceName: ""->Pulumi.Output.make,
+    operations: Pulumi.Output.make(ops),
+  }
+}
+
+// Standalone/deploy storage: inject the pool via a provider module.
+module Make = (P: {let pool: PgDriver.pool}) => {
+  type api = unit
+  type role = unit
+
+  let make: QueryDb_Adapter.storageMaker<unit, unit> = (
+    ~name,
+    ~indexes,
+    ~subIdField=?,
+    ~ttl as _=?,
+    ~api as _,
+    ~apiRole as _,
+    ~opts as _,
+  ) => makeStorage(~pool=P.pool, ~name, ~indexes, ~subIdField)
+}