experimental-a2 0.3.0 → 0.5.0

package/src/store-postgres.ts

@@ -0,0 +1,1212 @@
+/**
+ * experimental-a2/store-postgres — postgres store backend (the production path).
+ *
+ * Implements the A2Store interface over any client that speaks the tiny
+ * `PostgresClient` shape below — a `pg` Pool matches it structurally
+ * (and is what `connectionString` creates, lazily; `pg` is an optional
+ * peer dependency). The conformance suite in test/conformance is the
+ * executable contract, run against PGlite (real Postgres, in-process)
+ * and against a real server when `TEST_DATABASE_URL` is set.
+ *
+ * Semantics mirror the sqlite backend: `index` is stored as `idx`,
+ * timestamps are epoch milliseconds written from the injected clock —
+ * never SQL `now()` — and `stream()` is a poll loop. (A LISTEN/NOTIFY
+ * upgrade can land later without any API change; callers never branch
+ * on the transport.) Appends serialize per session via
+ * `pg_advisory_xact_lock`, so concurrent writers can't race the index
+ * assignment.
+ */
+
+import { A2Error } from './errors.ts'
+import { idempotentReplay } from './idempotent-replay.ts'
+import { decodeReturnedEventIds } from './store-codec.ts'
+import { pollingStream } from './store-polling.ts'
+import { retryableLazy } from './retryable-lazy.ts'
+import {
+  RANDOM_IDS,
+  SYSTEM_CLOCK,
+  type A2Store,
+  type Clock,
+  type Event,
+  type EventCause,
+  type IdSource,
+  type StoredEvent,
+  type StoreStateRead,
+} from './store.ts'
+
+/** The result shape this backend reads: just rows. */
+export type PostgresQueryResult = { rows: Record<string, unknown>[] }
+
+/** One checked-out connection — what transactions run on. */
+export type PostgresConnection = {
+  query(text: string, values?: unknown[]): Promise<PostgresQueryResult>
+  release(): void
+}
+
+/**
+ * The minimal client this backend needs. `pg.Pool` matches it
+ * structurally; so does PGlite (which has no `connect` — transactions
+ * then serialize on an internal mutex, fine for a single-connection
+ * client).
+ */
+export type PostgresClient = {
+  query(text: string, values?: unknown[]): Promise<PostgresQueryResult>
+  connect?(): Promise<PostgresConnection>
+  end?(): Promise<void>
+}
+
+export type PostgresStoreOptions = {
+  /** Creates a `pg` Pool lazily (requires the optional peer dep `pg`). */
+  connectionString?: string | undefined
+  /** Bring your own client — a `pg` Pool, PGlite, a pooler wrapper. */
+  client?: PostgresClient
+  /** Injectable clock — every stored timestamp comes from here. */
+  clock?: Clock
+  /** Injectable id source for generated event ids. */
+  ids?: IdSource
+}
+
+export type PostgresStore = A2Store & {
+  /** End the underlying pool/client (when this backend created it, or
+   * the injected client has `end`). */
+  close(): Promise<void>
+}
+
+const SCHEMA = `
+create table if not exists a2_events (
+  session_id   text    not null,
+  idx          bigint  not null,
+  event_type   text    not null,
+  payload      jsonb   not null,
+  event_id     text    not null,
+  created_at   bigint  not null,
+  cause        jsonb,
+  lane         text,
+  lane_ready   boolean not null default false,
+  processed_at bigint,
+  processed_by_attempt integer,
+  returned_event_ids jsonb,
+  first_claimed_at bigint,
+  last_claimed_at bigint,
+  attempt_count integer not null default 0,
+  failure_count integer not null default 0,
+  last_failed_at bigint,
+  last_failed_attempt integer,
+  last_error   text,
+  failed_at    bigint,
+  claim_holder text,
+  claim_expires_at bigint,
+  primary key (session_id, idx)
+);
+
+create unique index if not exists a2_events_event_id on a2_events (event_id);
+create index if not exists a2_events_unprocessed
+  on a2_events (session_id, idx) where processed_at is null;
+create index if not exists a2_events_lane_pending
+  on a2_events (session_id, lane, idx) where processed_at is null;
+create index if not exists a2_events_dispatch_ready
+  on a2_events (session_id, idx)
+  where lane_ready and processed_at is null and failed_at is null;
+create index if not exists a2_events_claim_expiry
+  on a2_events (session_id, claim_expires_at)
+  where lane_ready and processed_at is null and failed_at is null;
+
+create table if not exists a2_snapshots (
+  session_id   text   not null,
+  reducer_name text   not null,
+  up_to_index  bigint not null,
+  state        jsonb  not null,
+  updated_at   bigint not null,
+  primary key (session_id, reducer_name)
+);
+
+create table if not exists a2_presence (
+  ns          text   not null,
+  participant text   not null,
+  field       text   not null,
+  value       jsonb  not null,
+  seen        bigint not null,
+  at          bigint not null,
+  expires_at  bigint not null,
+  primary key (ns, participant, field)
+);
+`
+
+const asNumber = (value: unknown): number => Number(value) // bigint columns arrive as strings
+
+const toDate = (ms: unknown): Date | null =>
+  ms === null || ms === undefined ? null : new Date(asNumber(ms))
+
+const toCause = (raw: unknown): EventCause | null => {
+  if (raw === null || raw === undefined) return null
+  const value = (typeof raw === 'string' ? JSON.parse(raw) : raw) as {
+    index?: unknown
+    attempt?: unknown
+    batchSize?: unknown
+  }
+  if (
+    !Number.isInteger(value.index) ||
+    Number(value.index) < 1 ||
+    !Number.isInteger(value.attempt) ||
+    Number(value.attempt) < 1
+  ) {
+    throw new TypeError('stored event has an invalid cause')
+  }
+  if (
+    value.batchSize !== undefined &&
+    (!Number.isInteger(value.batchSize) || Number(value.batchSize) < 1)
+  ) {
+    throw new TypeError('stored event has an invalid cause')
+  }
+  return {
+    index: Number(value.index),
+    attempt: Number(value.attempt),
+    ...(value.batchSize === undefined
+      ? {}
+      : { batchSize: Number(value.batchSize) }),
+  }
+}
+
+const toStored = (row: Record<string, unknown>): StoredEvent => ({
+  id: row['event_id'] as string,
+  type: row['event_type'] as string,
+  payload: row['payload'],
+  index: asNumber(row['idx']),
+  sessionId: row['session_id'] as string,
+  createdAt: new Date(asNumber(row['created_at'])),
+  cause: toCause(row['cause']),
+  lane: (row['lane'] as string | null) ?? null,
+  processedAt: toDate(row['processed_at']),
+  processedByAttempt:
+    row['processed_by_attempt'] === null ||
+    row['processed_by_attempt'] === undefined
+      ? null
+      : asNumber(row['processed_by_attempt']),
+  returnedEventIds:
+    row['returned_event_ids'] === null ||
+    row['returned_event_ids'] === undefined
+      ? null
+      : decodeReturnedEventIds(row['returned_event_ids']),
+  firstClaimedAt: toDate(row['first_claimed_at']),
+  lastClaimedAt: toDate(row['last_claimed_at']),
+  attemptCount: asNumber(row['attempt_count']),
+  failureCount: asNumber(row['failure_count']),
+  lastFailedAt: toDate(row['last_failed_at']),
+  lastFailedAttempt:
+    row['last_failed_attempt'] === null ||
+    row['last_failed_attempt'] === undefined
+      ? null
+      : asNumber(row['last_failed_attempt']),
+  lastError: (row['last_error'] as string | null) ?? null,
+  failedAt: toDate(row['failed_at']),
+  claimHolder: (row['claim_holder'] as string | null) ?? null,
+  claimExpiresAt: toDate(row['claim_expires_at']),
+})
+
+const toEvent = (row: Record<string, unknown>): Event => ({
+  id: row['event_id'] as string,
+  type: row['event_type'] as string,
+  payload: row['payload'],
+  index: asNumber(row['idx']),
+  sessionId: row['session_id'] as string,
+  createdAt: new Date(asNumber(row['created_at'])),
+})
+
+const wrap = async <T>(fn: () => Promise<T>): Promise<T> => {
+  try {
+    return await fn()
+  } catch (err) {
+    if (err instanceof A2Error || err instanceof TypeError) throw err
+    throw new A2Error('STORE_UNAVAILABLE', 'postgres store operation failed', {
+      cause: err,
+    })
+  }
+}
+
+const jsonb = (value: unknown): string => JSON.stringify(value) ?? 'null'
+
+const initializeSchema = async (client: PostgresClient): Promise<void> => {
+  if (!client.connect) {
+    await client.query(SCHEMA)
+    return
+  }
+
+  const conn = await client.connect()
+  try {
+    await conn.query('begin')
+    // `if not exists` does not serialize concurrent catalog writes. Every
+    // serverless isolate takes the same transaction-scoped lock before DDL.
+    await conn.query(
+      "select pg_advisory_xact_lock(hashtext('a2:postgres:schema'))",
+    )
+    await conn.query(SCHEMA)
+    await conn.query('commit')
+  } catch (err) {
+    await conn.query('rollback').catch(() => {})
+    throw err
+  } finally {
+    conn.release()
+  }
+}
+
+export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
+  const clock = options.clock ?? SYSTEM_CLOCK
+  const generateId = options.ids ?? RANDOM_IDS
+
+  if (!options.client && !options.connectionString) {
+    throw new TypeError(
+      'postgres() needs a connectionString or an injected client',
+    )
+  }
+
+  // Lazy init: the first operation creates the client (dynamic import
+  // of the optional peer dep `pg`) and the schema. Constructing the
+  // backend does no I/O — same contract as every other adapter.
+  const connection = retryableLazy(async () => {
+    let owned: PostgresClient | null = null
+    try {
+      let c = options.client
+      if (!c) {
+        const pg = await import('pg').catch(() => {
+          throw new A2Error(
+            'STORE_NOT_CONFIGURED',
+            "experimental-a2/store-postgres with a connectionString needs the 'pg' package (optional peer dependency) — install it, or inject a client",
+          )
+        })
+        c = new pg.default.Pool({
+          connectionString: options.connectionString,
+        }) as unknown as PostgresClient
+        owned = c
+      }
+      await initializeSchema(c)
+      return c
+    } catch (err) {
+      if (owned?.end) await owned.end().catch(() => {})
+      throw err
+    }
+  })
+  const client = connection.get
+
+  // Transactions run on one connection. Pools check one out; a
+  // single-connection client (PGlite) serializes on this mutex instead.
+  let mutex: Promise<unknown> = Promise.resolve()
+  const withTx = async <T>(
+    fn: (query: PostgresConnection['query']) => Promise<T>,
+  ): Promise<T> => {
+    const c = await client()
+    if (c.connect) {
+      const conn = await c.connect()
+      try {
+        await conn.query('begin')
+        const result = await fn((text, values) => conn.query(text, values))
+        await conn.query('commit')
+        return result
+      } catch (err) {
+        await conn.query('rollback').catch(() => {})
+        throw err
+      } finally {
+        conn.release()
+      }
+    }
+    const run = mutex.then(async () => {
+      await c.query('begin')
+      try {
+        const result = await fn((text, values) => c.query(text, values))
+        await c.query('commit')
+        return result
+      } catch (err) {
+        await c.query('rollback').catch(() => {})
+        throw err
+      }
+    })
+    mutex = run.catch(() => {})
+    return run
+  }
+
+  return {
+    async append(sessionId, events) {
+      if (events.length === 0) {
+        return wrap(async () => {
+          const c = await client()
+          const { rows } = await c.query(
+            `select exists(
+               select 1 from a2_events
+               where session_id = $1 and processed_at is null
+             ) as has_pending`,
+            [sessionId],
+          )
+          return {
+            events: [],
+            hasPending: rows[0]?.['has_pending'] === true,
+          }
+        })
+      }
+      return wrap(() =>
+        withTx(async (query) => {
+          // Serialize appends per session — index assignment must not
+          // race across writers. Transaction-scoped, self-releasing.
+          await query('select pg_advisory_xact_lock(hashtext($1))', [sessionId])
+
+          const supplied = events.filter((e) => e.id !== undefined)
+          const suppliedIds = supplied.map((e) => e.id as string)
+          if (new Set(suppliedIds).size !== suppliedIds.length) {
+            throw new A2Error(
+              'PARTIAL_DUPLICATE_BATCH',
+              'batch contains the same event id more than once',
+            )
+          }
+          if (suppliedIds.length > 0) {
+            const { rows: existing } = await query(
+              `select stored.*,
+                      exists(
+                        select 1 from a2_events pending
+                        where pending.session_id = $2
+                          and pending.processed_at is null
+                      ) as session_has_pending
+                 from a2_events stored
+                where stored.event_id = any($1)
+                order by stored.idx`,
+              [suppliedIds, sessionId],
+            )
+            if (existing.length > 0) {
+              const foreign = existing.find(
+                (row) => row['session_id'] !== sessionId,
+              )
+              if (foreign) {
+                throw new A2Error(
+                  'PARTIAL_DUPLICATE_BATCH',
+                  `event id '${String(foreign['event_id'])}' already exists in another session`,
+                )
+              }
+              if (existing.length === events.length) {
+                return {
+                  events: idempotentReplay(events, existing.map(toStored)),
+                  hasPending: existing[0]?.['session_has_pending'] === true,
+                }
+              }
+              throw new A2Error(
+                'PARTIAL_DUPLICATE_BATCH',
+                `batch mixes ${existing.length} already-appended and ${events.length - existing.length} fresh events`,
+              )
+            }
+          }
+
+          // Attempt-currency fence: a fresh handler append commits only
+          // while its causal attempt is still the parent's latest
+          // (store.ts `append`). `for update` serializes this read against
+          // a concurrent `claimAvailable` — an unlocked read admits write
+          // skew.
+          const causeIndexes = [
+            ...new Set(
+              events
+                .filter((e) => e.cause !== undefined)
+                .map((e) => e.cause!.index),
+            ),
+          ]
+          if (causeIndexes.length > 0) {
+            const { rows: parents } = await query(
+              `select idx, attempt_count, failed_at from a2_events
+                where session_id = $1 and idx = any($2::bigint[])
+                for update`,
+              [sessionId, causeIndexes],
+            )
+            const byIndex = new Map(
+              parents.map((row) => [asNumber(row['idx']), row]),
+            )
+            for (const e of events) {
+              if (!e.cause) continue
+              const parent = byIndex.get(e.cause.index)
+              if (!parent) {
+                throw new TypeError(
+                  `no event at index ${e.cause.index} in session '${sessionId}'`,
+                )
+              }
+              if (
+                asNumber(parent['attempt_count']) !== e.cause.attempt ||
+                parent['failed_at'] !== null
+              ) {
+                throw new A2Error(
+                  'SUPERSEDED_ATTEMPT',
+                  `attempt ${e.cause.attempt} no longer owns event ${e.cause.index} in session '${sessionId}'`,
+                )
+              }
+            }
+          }
+
+          const { rows: maxRows } = await query(
+            `select coalesce(max(idx), 0) as max,
+                    exists(
+                      select 1 from a2_events pending
+                      where pending.session_id = $1
+                        and pending.processed_at is null
+                    ) as session_has_pending
+               from a2_events
+              where session_id = $1`,
+            [sessionId],
+          )
+          const base = asNumber(maxRows[0]?.['max'])
+          const now = clock.now().getTime()
+          const inserted: StoredEvent[] = []
+          for (let i = 0; i < events.length; i += 1) {
+            const e = events[i]!
+            const id = e.id ?? generateId()
+            const index = base + 1 + i
+            // oxlint-disable-next-line no-await-in-loop -- one tx, ordered inserts
+            await query(
+              `insert into a2_events
+                 (session_id, idx, event_type, payload, event_id, created_at,
+                  cause, lane, lane_ready, processed_at)
+               values (
+                 $1, $2, $3, $4::jsonb, $5, $6, $7::jsonb, $8,
+                 $8::text is null or not exists (
+                   select 1 from a2_events
+                    where session_id = $1 and lane = $8 and processed_at is null
+                 ),
+                 $9
+               )`,
+              [
+                sessionId,
+                index,
+                e.type,
+                jsonb(e.payload),
+                id,
+                now,
+                e.cause ? jsonb(e.cause) : null,
+                e.lane ?? null,
+                e.settled ? now : null,
+              ],
+            )
+            inserted.push({
+              id,
+              type: e.type,
+              payload: structuredClone(e.payload),
+              index,
+              sessionId,
+              createdAt: new Date(now),
+              cause: e.cause ? { ...e.cause } : null,
+              lane: e.lane ?? null,
+              processedAt: e.settled ? new Date(now) : null,
+              processedByAttempt: null,
+              returnedEventIds: null,
+              firstClaimedAt: null,
+              lastClaimedAt: null,
+              attemptCount: 0,
+              failureCount: 0,
+              lastFailedAt: null,
+              lastFailedAttempt: null,
+              lastError: null,
+              failedAt: null,
+              claimHolder: null,
+              claimExpiresAt: null,
+            })
+          }
+          return {
+            events: inserted,
+            hasPending:
+              maxRows[0]?.['session_has_pending'] === true ||
+              events.some((event) => event.settled !== true),
+          }
+        }),
+      )
+    },
+
+    async read(sessionId, opts) {
+      return wrap(async () => {
+        const c = await client()
+        const conditions = ['session_id = $1']
+        const params: unknown[] = [sessionId]
+        if (opts?.afterIndex !== undefined) {
+          params.push(opts.afterIndex)
+          conditions.push(`idx > $${params.length}`)
+        }
+        if (opts?.throughIndex !== undefined) {
+          params.push(opts.throughIndex)
+          conditions.push(`idx <= $${params.length}`)
+        }
+        const { rows } = await c.query(
+          `select * from a2_events where ${conditions.join(' and ')} order by idx`,
+          params,
+        )
+        return rows.map(toStored)
+      })
+    },
+
+    async claimAvailable({
+      sessionId,
+      holder,
+      ttlMs,
+      expiresAtMs,
+      excludeIndexes = [],
+    }) {
+      return wrap(() =>
+        withTx(async (query) => {
+          const now = clock.now().getTime()
+          const expiresAt = expiresAtMs ?? now + ttlMs
+          const { rows } = await query(
+            `with eligible as materialized (
+               select event.idx
+                 from a2_events event
+                where event.session_id = $1
+                  and event.processed_at is null
+                  and event.failed_at is null
+                  and event.lane_ready
+                  and (event.claim_expires_at is null or event.claim_expires_at <= $2)
+                  and not (event.idx = any($5::bigint[]))
+                for update of event
+             )
+             update a2_events claimed set
+               attempt_count = claimed.attempt_count + 1,
+               first_claimed_at = coalesce(claimed.first_claimed_at, $2),
+               last_claimed_at = $2,
+               claim_holder = $3,
+               claim_expires_at = $4
+             from eligible
+             where claimed.session_id = $1 and claimed.idx = eligible.idx
+             returning claimed.*`,
+            [sessionId, now, holder, expiresAt, [...excludeIndexes]],
+          )
+          if (rows.length > 0) {
+            const events = rows
+              .map(toStored)
+              .toSorted((a, b) => a.index - b.index)
+            return { outcome: 'claimed', events }
+          }
+          const { rows: activeRows } = await query(
+            `select min(claim_expires_at) as retry_at
+               from a2_events
+              where session_id = $1
+                and processed_at is null
+                and failed_at is null
+                and lane_ready
+                and claim_expires_at > $2`,
+            [sessionId, now],
+          )
+          const retryAt = activeRows[0]?.['retry_at']
+          return retryAt === null || retryAt === undefined
+            ? { outcome: 'settled' }
+            : { outcome: 'busy', retryAt: new Date(asNumber(retryAt)) }
+        }),
+      )
+    },
+
+    async renewClaims({ sessionId, holder, claims, ttlMs, expiresAtMs }) {
+      if (claims.length === 0) return { renewed: [], superseded: [] }
+      return wrap(async () => {
+        const c = await client()
+        const now = clock.now().getTime()
+        const expiresAt = expiresAtMs ?? now + ttlMs
+        const indexes = claims.map((claim) => claim.index)
+        const attempts = new Map(
+          claims.map((claim) => [claim.index, claim.attempt]),
+        )
+        const { rows } = await c.query(
+          `with listed as (
+             select idx, attempt
+               from unnest($3::bigint[], $6::int[]) as listed(idx, attempt)
+           ),
+           renewed as (
+             update a2_events event set claim_expires_at = $1
+               from listed
+              where event.session_id = $2
+                and event.idx = listed.idx
+                and event.attempt_count = listed.attempt
+                and event.processed_at is null
+                and event.failed_at is null
+                and event.claim_holder = $4
+                and event.claim_expires_at > $5
+              returning event.idx
+           )
+           select event.idx, event.attempt_count,
+                  exists(select 1 from renewed where renewed.idx = event.idx)
+                    as renewed
+             from a2_events event
+            where event.session_id = $2 and event.idx = any($3::bigint[])`,
+          [
+            expiresAt,
+            sessionId,
+            indexes,
+            holder,
+            now,
+            claims.map((claim) => claim.attempt),
+          ],
+        )
+        const renewed: number[] = []
+        const superseded: number[] = []
+        for (const row of rows) {
+          const index = asNumber(row['idx'])
+          if (row['renewed'] === true) renewed.push(index)
+          else if (
+            asNumber(row['attempt_count']) > (attempts.get(index) ?? 0)
+          ) {
+            superseded.push(index)
+          }
+        }
+        return {
+          renewed: renewed.toSorted((a, b) => a - b),
+          superseded: superseded.toSorted((a, b) => a - b),
+        }
+      })
+    },
+
+    async completeAttempt({ sessionId, index, attempt, events }) {
+      return wrap(() =>
+        withTx(async (query) => {
+          const { rows: parentRows } = await query(
+            `select * from a2_events
+              where session_id = $1 and idx = $2
+              for update`,
+            [sessionId, index],
+          )
+          const parent = parentRows[0]
+          if (!parent) {
+            throw new TypeError(
+              `no event at index ${index} in session '${sessionId}'`,
+            )
+          }
+          const ids = events.map((event) => event.id)
+          if (new Set(ids).size !== ids.length) {
+            throw new A2Error(
+              'PARTIAL_DUPLICATE_BATCH',
+              'returned event batch contains the same event id more than once',
+            )
+          }
+          if (parent['processed_at'] !== null) {
+            if (asNumber(parent['processed_by_attempt']) !== attempt) {
+              return { outcome: 'superseded' }
+            }
+            const returnedIds =
+              parent['returned_event_ids'] === null ||
+              parent['returned_event_ids'] === undefined
+                ? null
+                : decodeReturnedEventIds(parent['returned_event_ids'])
+            if (
+              returnedIds === null ||
+              returnedIds.length !== ids.length ||
+              returnedIds.some((id, offset) => id !== ids[offset])
+            ) {
+              throw new A2Error(
+                'PARTIAL_DUPLICATE_BATCH',
+                'completed attempt does not match the returned event batch',
+              )
+            }
+            if (events.length === 0) {
+              return { outcome: 'completed', events: [] }
+            }
+            const { rows: existing } = await query(
+              `select * from a2_events
+                where event_id = any($1::text[])`,
+              [ids],
+            )
+            const byId = new Map(
+              existing.map((row) => [row['event_id'] as string, row]),
+            )
+            const ordered = ids.map((id) => byId.get(id))
+            if (
+              ordered.some((row) => {
+                const cause = row ? toCause(row['cause']) : null
+                return (
+                  !row ||
+                  row['session_id'] !== sessionId ||
+                  cause?.index !== index ||
+                  cause.attempt !== attempt
+                )
+              })
+            ) {
+              throw new A2Error(
+                'PARTIAL_DUPLICATE_BATCH',
+                'returned event retry does not match the committed batch',
+              )
+            }
+            return {
+              outcome: 'completed',
+              events: idempotentReplay(
+                events,
+                (ordered as Record<string, unknown>[]).map(toStored),
+              ),
+            }
+          }
+          if (
+            asNumber(parent['attempt_count']) !== attempt ||
+            parent['claim_holder'] === null ||
+            parent['claim_holder'] === undefined ||
+            parent['failed_at'] !== null
+          ) {
+            return { outcome: 'superseded' }
+          }
+
+          await query('select pg_advisory_xact_lock(hashtext($1))', [sessionId])
+          if (ids.length > 0) {
+            const { rows: existing } = await query(
+              'select event_id from a2_events where event_id = any($1::text[])',
+              [ids],
+            )
+            if (existing.length > 0) {
+              throw new A2Error(
+                'PARTIAL_DUPLICATE_BATCH',
+                'returned event batch contains an already-appended event id',
+              )
+            }
+          }
+
+          const { rows: maxRows } = await query(
+            'select coalesce(max(idx), 0) as max from a2_events where session_id = $1',
+            [sessionId],
+          )
+          const base = asNumber(maxRows[0]?.['max'])
+          const now = clock.now().getTime()
+          const inserted: StoredEvent[] = []
+          for (let offset = 0; offset < events.length; offset += 1) {
+            const event = events[offset]!
+            const childIndex = base + offset + 1
+            // oxlint-disable-next-line no-await-in-loop -- one tx, ordered inserts
+            const { rows } = await query(
+              `insert into a2_events
+                 (session_id, idx, event_type, payload, event_id, created_at,
+                  cause, lane, lane_ready, processed_at)
+               values (
+                 $1, $2, $3, $4::jsonb, $5, $6, $7::jsonb, $8,
+                 $8::text is null or not exists (
+                   select 1 from a2_events
+                    where session_id = $1 and lane = $8 and processed_at is null
+                 ),
+                 $9
+               )
+               returning *`,
+              [
+                sessionId,
+                childIndex,
+                event.type,
+                jsonb(event.payload),
+                event.id,
+                now,
+                jsonb({ index, attempt }),
+                event.lane ?? null,
+                event.settled ? now : null,
+              ],
+            )
+            inserted.push(toStored(rows[0]!))
+          }
+          await query(
+            `update a2_events set
+               processed_at = $1,
+               processed_by_attempt = $2,
+               returned_event_ids = $5::jsonb,
+               lane_ready = false,
+               claim_holder = null,
+               claim_expires_at = null
+             where session_id = $3 and idx = $4`,
+            [now, attempt, sessionId, index, jsonb(ids)],
+          )
+          const parentLane = (parent['lane'] as string | null) ?? null
+          if (parentLane !== null) {
+            await query(
+              `update a2_events set lane_ready = true
+                where session_id = $1
+                  and idx = (
+                    select idx from a2_events
+                     where session_id = $1 and lane = $2 and processed_at is null
+                     order by idx limit 1
+                  )`,
+              [sessionId, parentLane],
+            )
+          }
+          return { outcome: 'completed', events: inserted }
+        }),
+      )
+    },
+
+    async failAttempt({ sessionId, index, attempt, error, maxFailures }) {
+      return wrap(async () => {
+        const c = await client()
+        const { rows } = await c.query(
+          `with current as materialized (
+             select e.* from a2_events e
+             where e.session_id = $1 and e.idx = $2
+             for update of e
+           ), updated as (
+             update a2_events e set
+               failure_count = e.failure_count + 1,
+               last_error = $4,
+               last_failed_at = $6,
+               last_failed_attempt = $3,
+               failed_at = case
+                 when e.failure_count + 1 >= $5 then $6
+                 else e.failed_at
+               end,
+               claim_holder = null,
+               claim_expires_at = null
+             from current
+             where e.session_id = $1
+               and e.idx = $2
+               and current.processed_at is null
+               and current.failed_at is null
+               and current.attempt_count = $3
+               and current.claim_holder is not null
+             returning e.failure_count, e.failed_at
+           )
+           select case
+             when not exists (select 1 from current) then 'missing'
+             when exists (
+               select 1 from updated where failed_at is not null
+             ) then 'dead_lettered'
+             when exists (select 1 from updated) then 'failed'
+             when exists (
+               select 1 from current
+               where processed_at is not null or attempt_count <> $3
+             ) then 'superseded'
+             when exists (
+               select 1 from current where failed_at is not null
+             ) then 'dead_lettered'
+             when exists (
+               select 1 from current
+                where claim_holder is null and last_failed_attempt = $3
+             ) then 'failed'
+             else 'superseded'
+           end as outcome,
+           coalesce(
+             (select failure_count from updated),
+             (select failure_count from current)
+           ) as failure_count`,
+          [
+            sessionId,
+            index,
+            attempt,
+            error,
+            maxFailures,
+            clock.now().getTime(),
+          ],
+        )
+        const row = rows[0]
+        if (!row || row['outcome'] === 'missing') {
+          throw new TypeError(
+            `no event at index ${index} in session '${sessionId}'`,
+          )
+        }
+        return {
+          outcome: row['outcome'] as 'failed' | 'dead_lettered' | 'superseded',
+          failureCount: asNumber(row['failure_count']),
+        }
+      })
+    },
+
+    async readState(sessionId, reducerName) {
+      return wrap(async () => {
+        const c = await client()
+        const { rows } = await c.query(
+          `with snapshot as materialized (
+             select up_to_index, state
+             from a2_snapshots
+             where session_id = $1 and reducer_name = $2
+           )
+           select 0 as row_order, 'snapshot' as row_kind,
+                  snapshot.up_to_index as snapshot_index,
+                  snapshot.state as snapshot_state,
+                  null::text as session_id, null::bigint as idx,
+                  null::text as event_type, null::jsonb as payload,
+                  null::text as event_id, null::bigint as created_at
+           from snapshot
+           union all
+           select 1 as row_order, 'event' as row_kind,
+                  null::bigint as snapshot_index,
+                  null::jsonb as snapshot_state,
+                  event.session_id, event.idx, event.event_type,
+                  event.payload, event.event_id, event.created_at
+           from a2_events event
+           where event.session_id = $1
+             and event.idx > coalesce((select up_to_index from snapshot), 0)
+           order by row_order, idx`,
+          [sessionId, reducerName],
+        )
+        const snapshot = rows.find((row) => row['row_kind'] === 'snapshot')
+        return {
+          snapshot: snapshot
+            ? {
+                index: asNumber(snapshot['snapshot_index']),
+                state: snapshot['snapshot_state'],
+              }
+            : null,
+          events: rows
+            .filter((row) => row['row_kind'] === 'event')
+            .map(toEvent),
+        }
+      })
+    },
+
+    async readStates(sessionIds, reducerName) {
+      if (sessionIds.length === 0) return []
+      return wrap(async () => {
+        const c = await client()
+        // One statement, one MVCC snapshot — each session's tail is
+        // bounded by the same snapshot row the read returns.
+        const { rows } = await c.query(
+          `with snapshot as materialized (
+             select session_id, up_to_index, state
+             from a2_snapshots
+             where session_id = any($1::text[]) and reducer_name = $2
+           )
+           select 0 as row_order, 'snapshot' as row_kind,
+                  snapshot.session_id,
+                  snapshot.up_to_index as snapshot_index,
+                  snapshot.state as snapshot_state,
+                  null::bigint as idx, null::text as event_type,
+                  null::jsonb as payload, null::text as event_id,
+                  null::bigint as created_at
+           from snapshot
+           union all
+           select 1 as row_order, 'event' as row_kind,
+                  event.session_id,
+                  null::bigint as snapshot_index,
+                  null::jsonb as snapshot_state,
+                  event.idx, event.event_type, event.payload,
+                  event.event_id, event.created_at
+           from a2_events event
+           left join snapshot on snapshot.session_id = event.session_id
+           where event.session_id = any($1::text[])
+             and event.idx > coalesce(snapshot.up_to_index, 0)
+           order by row_order, session_id, idx`,
+          [sessionIds, reducerName],
+        )
+        const bySession = new Map<string, StoreStateRead>()
+        const readOf = (sessionId: string): StoreStateRead => {
+          let read = bySession.get(sessionId)
+          if (!read) {
+            read = { snapshot: null, events: [] }
+            bySession.set(sessionId, read)
+          }
+          return read
+        }
+        for (const row of rows) {
+          const read = readOf(row['session_id'] as string)
+          if (row['row_kind'] === 'snapshot') {
+            read.snapshot = {
+              index: asNumber(row['snapshot_index']),
+              state: row['snapshot_state'],
+            }
+          } else {
+            read.events.push(toEvent(row))
+          }
+        }
+        return sessionIds.map(
+          (sessionId) =>
+            bySession.get(sessionId) ?? { snapshot: null, events: [] },
+        )
+      })
+    },
+
+    async putSnapshot(sessionId, reducerName, index, state) {
+      await wrap(async () => {
+        const c = await client()
+        // Guarded upsert: a slower concurrent writer must never clobber
+        // a further-along snapshot (spec §3).
+        await c.query(
+          `insert into a2_snapshots (session_id, reducer_name, up_to_index, state, updated_at)
+           values ($1, $2, $3, $4::jsonb, $5)
+           on conflict (session_id, reducer_name) do update set
+             up_to_index = excluded.up_to_index,
+             state = excluded.state,
+             updated_at = excluded.updated_at
+           where excluded.up_to_index > a2_snapshots.up_to_index`,
+          [sessionId, reducerName, index, jsonb(state), clock.now().getTime()],
+        )
+      })
+    },
+
+    presence: {
+      async set(ns, participant, values, meta) {
+        const entries = Object.entries(values)
+        if (entries.length === 0) return
+        await wrap(async () => {
+          const c = await client()
+          const atMs = meta.at.getTime()
+          // Expiry anchors on the storage clock — the sender's `at`
+          // orders writes but never anchors their lifetime.
+          const expiresAtMs = clock.now().getTime() + meta.ttlMs
+          for (const [field, value] of entries) {
+            // Field-wise LWW: a stored row with a strictly newer `at`
+            // survives; ties go to the incoming write (memory parity).
+            // oxlint-disable-next-line no-await-in-loop -- independent per-field registers
+            await (value === null
+              ? c.query(
+                  `delete from a2_presence
+                    where ns = $1 and participant = $2 and field = $3
+                      and at <= $4`,
+                  [ns, participant, field, atMs],
+                )
+              : c.query(
+                  `insert into a2_presence
+                     (ns, participant, field, value, seen, at, expires_at)
+                   values ($1, $2, $3, $4::jsonb, $5, $6, $7)
+                   on conflict (ns, participant, field) do update set
+                     value = excluded.value,
+                     seen = excluded.seen,
+                     at = excluded.at,
+                     expires_at = excluded.expires_at
+                   where a2_presence.at <= excluded.at`,
+                  [
+                    ns,
+                    participant,
+                    field,
+                    jsonb(value),
+                    meta.seen,
+                    atMs,
+                    expiresAtMs,
+                  ],
+                ))
+          }
+        })
+      },
+
+      async read(ns) {
+        return wrap(async () => {
+          const c = await client()
+          const now = clock.now().getTime()
+          // Sweep and read share one statement (one snapshot): the
+          // delete is opportunistic cleanup; the filter alone keeps
+          // expired rows out of this result.
+          const { rows } = await c.query(
+            `with swept as (
+               delete from a2_presence
+                where ns = $1 and expires_at <= $2
+             )
+             select participant, field, value, seen, at, expires_at
+               from a2_presence
+              where ns = $1 and expires_at > $2
+              order by participant, field`,
+            [ns, now],
+          )
+          return rows.map((row) => ({
+            participant: row['participant'] as string,
+            field: row['field'] as string,
+            value: row['value'],
+            seen: asNumber(row['seen']),
+            at: new Date(asNumber(row['at'])),
+            expiresAt: new Date(asNumber(row['expires_at'])),
+          }))
+        })
+      },
+    },
+
+    inspect: {
+      async listSessions(inspectionOptions) {
+        return wrap(async () => {
+          const c = await client()
+          const conditions = ['left(session_id, length($1)) = $1']
+          const params: unknown[] = [inspectionOptions.prefix]
+          if (inspectionOptions.cursor !== undefined) {
+            params.push(inspectionOptions.cursor)
+            conditions.push(`session_id > $${params.length}`)
+          }
+          params.push(inspectionOptions.limit + 1)
+          const { rows } = await c.query(
+            `select
+               session_id,
+               count(*) as event_count,
+               count(*) filter (where processed_at is null and failed_at is null) as pending_count,
+               count(*) filter (where failed_at is not null) as failed_count,
+               sum(attempt_count) as attempt_count,
+               sum(failure_count) as failure_count,
+               min(created_at) as first_event_at,
+               max(greatest(
+                 created_at,
+                 coalesce(first_claimed_at, 0),
+                 coalesce(last_claimed_at, 0),
+                 coalesce(last_failed_at, 0),
+                 coalesce(processed_at, 0),
+                 coalesce(failed_at, 0)
+               )) as updated_at
+             from a2_events
+             where ${conditions.join(' and ')}
+             group by session_id
+             order by session_id
+             limit $${params.length}`,
+            params,
+          )
+          const hasMore = rows.length > inspectionOptions.limit
+          const visible = rows.slice(0, inspectionOptions.limit)
+          return {
+            sessions: visible.map((row) => ({
+              sessionId: row['session_id'] as string,
+              eventCount: asNumber(row['event_count']),
+              pendingCount: asNumber(row['pending_count']),
+              failedCount: asNumber(row['failed_count']),
+              attemptCount: asNumber(row['attempt_count']),
+              failureCount: asNumber(row['failure_count']),
+              firstEventAt: new Date(asNumber(row['first_event_at'])),
+              updatedAt: new Date(asNumber(row['updated_at'])),
+            })),
+            cursor: hasMore
+              ? ((visible.at(-1)?.['session_id'] as string | undefined) ?? null)
+              : null,
+          }
+        })
+      },
+      async readEvents(sessionId, pageOptions) {
+        return wrap(async () => {
+          const c = await client()
+          const currentFrontier = asNumber(
+            (
+              await c.query(
+                'select coalesce(max(idx), 0) as frontier from a2_events where session_id = $1',
+                [sessionId],
+              )
+            ).rows[0]?.['frontier'] ?? 0,
+          )
+          const throughIndex = Math.min(
+            pageOptions.throughIndex ?? currentFrontier,
+            currentFrontier,
+          )
+          const { rows } = await c.query(
+            `select * from a2_events
+              where session_id = $1 and idx > $2 and idx <= $3
+              order by idx limit $4`,
+            [
+              sessionId,
+              pageOptions.afterIndex,
+              throughIndex,
+              pageOptions.limit,
+            ],
+          )
+          return { events: rows.map(toStored), throughIndex }
+        })
+      },
+      async listSnapshots(sessionId) {
+        return wrap(async () => {
+          const c = await client()
+          const { rows } = await c.query(
+            `select reducer_name, up_to_index, updated_at
+             from a2_snapshots where session_id = $1 order by reducer_name`,
+            [sessionId],
+          )
+          return rows.map((row) => ({
+            reducerName: row['reducer_name'] as string,
+            index: asNumber(row['up_to_index']),
+            updatedAt: new Date(asNumber(row['updated_at'])),
+          }))
+        })
+      },
+    },
+
+    stream(sessionId, opts) {
+      const readAfter = (afterIndex: number): Promise<StoredEvent[]> =>
+        wrap(async () => {
+          const c = await client()
+          const { rows } = await c.query(
+            'select * from a2_events where session_id = $1 and idx > $2 order by idx',
+            [sessionId, afterIndex],
+          )
+          return rows.map(toStored)
+        })
+      return pollingStream(
+        readAfter,
+        opts?.startAfter !== undefined ? { startAfter: opts.startAfter } : {},
+      )
+    },
+
+    async close() {
+      const current = connection.peek()
+      if (!current) return
+      const c = await current
+      await c.end?.()
+    },
+  }
+}