experimental-a2 0.20.0 → 0.22.0

package/src/ai.ts

@@ -94,7 +94,7 @@ import {
   type ProgressBatches,
   type StoredProgressPayload,
 } from './ai-progress-batches.ts'
-import type { HandlerContext } from './server.ts'
+import type { ConsumerContext } from './server.ts'
 import type { StandardSchemaV1 } from './standard-schema.ts'
 import { assertSyncSchema, validateSync } from './validate.ts'
 
@@ -462,8 +462,8 @@ export type AgentContract<
 export type AgentToolEventDefs = EventDefs &
   Pick<AIEventDefs, 'ai.tool.execution.requested'>
 
-/** The durable handler context supplied when A2 executes a local AI tool. */
-export type AgentToolContext<D extends AgentToolEventDefs> = HandlerContext<
+/** The durable consumer context supplied when A2 executes a local AI tool. */
+export type AgentToolContext<D extends AgentToolEventDefs> = ConsumerContext<
   D,
   'ai.tool.execution.requested'
 >
@@ -2526,20 +2526,20 @@ export const inputs: AIInputs = {
 }
 
 /**
- * Read the durable handler context ambient to the current AI tool
+ * Read the durable consumer context ambient to the current AI tool
  * execution. A2 runs each local tool's `execute` inside this scope, so
  * plain AI SDK `tool()` definitions reach their `event`, `attempt`,
  * `session`, and `signal` without an A2-specific wrapper. Pass the
  * agent's contract to type application events; it is verified against
  * the executing agent.
  */
-export function handlerContext<D extends AgentToolEventDefs = AIEventDefs>(
+export function consumerContext<D extends AgentToolEventDefs = AIEventDefs>(
   contract?: Contract<D>,
 ): AgentToolContext<D> {
   const scope = ambientToolScopeStorage()?.getStore()
   if (scope === undefined) {
     throw new TypeError(
-      "handlerContext() requires an ambient A2 tool execution: call it inside a local tool's execute, or wrap direct tool tests with runWithHandlerContext",
+      "consumerContext() requires an ambient A2 tool execution: call it inside a local tool's execute, or wrap direct tool tests with runWithConsumerContext",
     )
   }
   if (
@@ -2548,7 +2548,7 @@ export function handlerContext<D extends AgentToolEventDefs = AIEventDefs>(
     scope.contract.name !== contract.name
   ) {
     throw new TypeError(
-      `handlerContext('${contract.name}') was called during a tool execution for agent '${scope.contract.name}'`,
+      `consumerContext('${contract.name}') was called during a tool execution for agent '${scope.contract.name}'`,
     )
   }
   return scope.context as AgentToolContext<D>

package/src/client.ts

@@ -38,6 +38,7 @@ import type {
   PresencePatch,
   WithPresence,
 } from './contract.ts'
+import { presenceTombstones } from './presence-tombstones.ts'
 import { foldEvent, type Reducer, type StateSnapshot } from './reducer.ts'
 import { isSessionCleared } from './session-clear.ts'
 import { validateSync } from './validate.ts'
@@ -1560,6 +1561,8 @@ export function createClient<
     // Participant and field keys arrive off the wire, so the map and
     // every entry are built null-prototype — see `nullProtoRecord`.
     let presenceState: PresenceMap = nullProtoRecord()
+    /** Stamps of applied foreign nulls — kept out of `presenceState`. */
+    const presenceDeletes = presenceTombstones()
     let presenceLastSentAt = 0
     /** The last LWW stamp issued — see `nextPresenceAt`. */
     let presenceLastAt = 0
@@ -1763,14 +1766,19 @@ export function createClient<
       for (const [field, value] of Object.entries(patch.values)) {
         if (value === undefined) continue
         const existing = entry[field]
-        // Field-wise LWW: an older stamp loses, a tie goes to the wire.
+        const write = { participant: patch.participant, field, at: patch.at }
+        // Field-wise LWW against the live value or its deletion: an older
+        // stamp loses, a tie goes to the wire.
         if (existing && existing.at.getTime() > patch.at.getTime()) continue
+        if (presenceDeletes.outranks(write)) continue
         if (value === null) {
+          presenceDeletes.keep(write)
           if (existing) {
             delete entry[field]
             changed = true
           }
         } else {
+          presenceDeletes.drop(write)
           entry[field] = { value, seen: patch.seen, at: patch.at }
           changed = true
         }
@@ -1787,7 +1795,16 @@ export function createClient<
       const next: PresenceMap = nullProtoRecord()
       for (const [id, fields] of Object.entries(incoming)) {
         if (id === participant) continue
-        next[id] = fields
+        const entry: PresenceMap[string] = nullProtoRecord()
+        for (const [field, stamp] of Object.entries(fields)) {
+          if (stamp === undefined) continue
+          const write = { participant: id, field, at: stamp.at }
+          // A row older than the field's deletion must not resurrect it.
+          if (presenceDeletes.outranks(write)) continue
+          presenceDeletes.drop(write)
+          entry[field] = stamp
+        }
+        if (Object.keys(entry).length > 0) next[id] = entry
       }
       // Foreign entries replaced wholesale; the own echo survives.
       const own =

package/src/contract.ts

@@ -123,7 +123,7 @@ export type Contract<
   readonly events: Readonly<D>
   /** The presence vocabulary — empty unless declared. */
   readonly presence: Readonly<P>
-  /** Preserve literal types for a handler-returned event batch. */
+  /** Preserve literal types for a consumer-returned event batch. */
   readonly batch: EventBatchFactory<D>
   readonly reducer: R
 }

package/src/deterministic-id.ts

@@ -1,9 +1,9 @@
 /**
- * Deterministic default ids for handler `session.append` calls. A handler
+ * Deterministic default ids for consumer `session.append` calls. A consumer
  * re-run after a crash calls `session.append` again; giving
  * each call a deterministic id — derived from the triggering event's id
  * and the caller's stable name — makes the re-run a no-op via the store's
- * unique index on event ids.
+ * per-session unique index on event ids.
  *
  * The id is a UUIDv5-shaped SHA-1 over
  * `(namespace, triggerEventId, name, itemOrdinal)`, computed with
@@ -32,20 +32,38 @@ async function deterministicId(parts: Array<string | number>): Promise<string> {
   return deterministicIdFromInput(parts.join('\u0000'))
 }
 
+/**
+ * `consumer` keys the id on the consumer that appends, so two consumers of
+ * one event never collide. A2's own consumers pass none: their types are
+ * disjoint, so the event alone keys them.
+ */
 export async function deterministicEventId(
   triggerEventId: string,
   name: string,
   itemOrdinal: number,
+  consumer?: string,
 ): Promise<string> {
   if (name.length === 0) throw new TypeError('append name must not be empty')
-  return deterministicId([APPEND_NAMESPACE, triggerEventId, name, itemOrdinal])
+  return deterministicId([
+    APPEND_NAMESPACE,
+    triggerEventId,
+    name,
+    itemOrdinal,
+    ...(consumer === undefined ? [] : [consumer]),
+  ])
 }
 
 export async function deterministicReturnedEventId(
   triggerEventId: string,
   itemOrdinal: number,
+  consumer?: string,
 ): Promise<string> {
-  return deterministicId([RETURN_NAMESPACE, triggerEventId, itemOrdinal])
+  return deterministicId([
+    RETURN_NAMESPACE,
+    triggerEventId,
+    itemOrdinal,
+    ...(consumer === undefined ? [] : [consumer]),
+  ])
 }
 
 /**
@@ -60,6 +78,7 @@ export async function deterministicScheduleId(
   triggerEventId: string | null,
   name: string,
   clearIndex = 0,
+  consumer?: string,
 ): Promise<string> {
   return deterministicIdFromInput(
     JSON.stringify([
@@ -69,6 +88,7 @@ export async function deterministicScheduleId(
       triggerEventId,
       name,
       ...(clearIndex > 0 ? [clearIndex] : []),
+      ...(consumer === undefined ? [] : [{ consumer }]),
     ]),
   )
 }
@@ -80,6 +100,7 @@ export async function deterministicScheduleClearId({
   clearIndex,
   name,
   ifLastIndex,
+  consumer,
 }: {
   contract: string
   sessionId: string
@@ -87,6 +108,7 @@ export async function deterministicScheduleClearId({
   clearIndex: number
   name: string
   ifLastIndex: number
+  consumer?: string
 }): Promise<string> {
   return deterministicIdFromInput(
     JSON.stringify([
@@ -97,6 +119,7 @@ export async function deterministicScheduleClearId({
       clearIndex,
       name,
       ifLastIndex,
+      ...(consumer === undefined ? [] : [{ consumer }]),
     ]),
   )
 }

package/src/errors.ts

@@ -3,13 +3,14 @@ export type A2ServerErrorCode =
   | 'FORBIDDEN' // external ingress was denied by server.fetch authorization
   | 'UNKNOWN_EVENT_TYPE' // event type not in the machine's `events` map
   | 'PARTIAL_DUPLICATE_BATCH' // batch mixed already-appended and fresh events
-  | 'SUPERSEDED_ATTEMPT' // handler append from an attempt a recovery claim or a clear replaced
+  | 'SUPERSEDED_ATTEMPT' // consumer append from an attempt a recovery claim or a clear replaced
   | 'SESSION_CLEARED' // a read or call reached across the session's latest clear
   | 'CLAIM_EXPIRED' // ctx.signal abort reason: the attempt's lease lapsed without renewal
   | 'STORE_UNAVAILABLE' // store backend failure — retryable, nothing was written
   | 'STORE_NOT_CONFIGURED' // no `store` in production, a missing peer dependency, or Postgres lacks A2's tables
   | 'UNKNOWN_PRESENCE_FIELD' // presence field not in the contract's `presence` map
   | 'PRESENCE_NOT_SUPPORTED' // contract declares presence but the store lacks the capability
+  | 'CONSUMER_DEAD_LETTERED' // session.consume reached a head that dead-lettered for that consumer
 
 export type A2ErrorCode =
   A2ServerErrorCode | 'TIMEOUT' | 'HTTP_ERROR' | 'CONNECTION_FAILED' | 'UNKNOWN'
@@ -34,14 +35,16 @@ export class A2Error extends Error {
   }
 }
 
-/** A handler write whose attempt no longer owns its triggering event. */
+/** A consumer write whose attempt no longer owns its triggering event. */
 export function supersededAttemptError(
   sessionId: string,
-  cause: { index: number; attempt: number },
+  cause: { consumer?: string; index: number; attempt: number },
 ): A2Error {
+  const of =
+    cause.consumer === undefined ? '' : ` for consumer '${cause.consumer}'`
   return new A2Error(
     'SUPERSEDED_ATTEMPT',
-    `attempt ${cause.attempt} no longer owns event ${cause.index} in session '${sessionId}'`,
+    `attempt ${cause.attempt} no longer owns event ${cause.index}${of} in session '${sessionId}'`,
   )
 }
 
@@ -58,7 +61,7 @@ export function asStoreUnavailable(err: unknown): A2Error {
 }
 
 /**
- * Throw from a handler to reject retrying: the failure is adjudicated
+ * Throw from a consumer to reject retrying: the failure is adjudicated
  * terminal immediately (dead-lettered on the first throw) instead of
  * consuming the ten-failure retry budget. For deterministic failures —
  * a guard that will refuse identically on every attempt — retrying is

package/src/idempotent-replay.ts

@@ -37,7 +37,6 @@ export const idempotentReplay = (
         stored === undefined ||
         stored.index !== firstIndex + index ||
         stored.type !== event.type ||
-        stored.lane !== (event.lane ?? null) ||
         stored.cause?.batchSize !== event.cause?.batchSize ||
         canonicalJson(stored.payload) !== canonicalJson(event.payload)
       )

package/src/index.ts

@@ -3,7 +3,7 @@
  *
  * This entry point is isomorphic by construction: the contract (the
  * vocabulary everything shares), reducers derived from it, and the
- * error type. Implementing a contract — storage, handlers, sessions —
+ * error type. Implementing a contract — storage, consumers, sessions —
  * lives in experimental-a2/server, which never enters a browser bundle.
  */
 

package/src/internal.ts

@@ -75,7 +75,17 @@ export type ServerInternals = {
 export const serverInternals: WeakMap<object, ServerInternals> = new WeakMap()
 
 /**
- * Handler contexts whose previous attempt ended in a failure the handler
+ * Consumers A2's own runtimes define: named under `a2.`, with child ids that
+ * leave the name out, since their types are disjoint. Defined through
+ * `runtimeConsumer` (runtime-consumer.ts), which the server module installs.
+ */
+export const runtimeConsumers: WeakSet<object> = new WeakSet()
+
+export const runtimeConsumerFactory: { define?: (options: never) => unknown } =
+  {}
+
+/**
+ * Consumer contexts whose previous attempt ended in a failure the consumer
  * threw, as opposed to a claim that lapsed (a crash, a timeout, a frozen
  * process). Only the attempt's own outcome is known, not how far it got.
  */
@@ -84,9 +94,9 @@ export const failedPreviousAttempt: WeakSet<object> = new WeakSet()
 const objectLike = (value: unknown): value is object =>
   (typeof value === 'object' && value !== null) || typeof value === 'function'
 
-/** The ambient value delivered to `handlerContext` during a tool execution. */
+/** The ambient value delivered to `consumerContext` during a tool execution. */
 export type AmbientToolScope = {
-  /** Executing server identity; a test scope from `runWithHandlerContext` has none. */
+  /** Executing server identity; a test scope from `runWithConsumerContext` has none. */
   contract?: { readonly name: string }
   context: unknown
 }
@@ -95,7 +105,7 @@ export type AmbientToolScope = {
  * Structural AsyncLocalStorage surface for the ambient tool scope. The
  * instance is created by the server-only AI entry point (the only place
  * `node:async_hooks` may be imported) and shared through a global
- * symbol slot, so `handlerContext` in the isomorphic AI entry point and
+ * symbol slot, so `consumerContext` in the isomorphic AI entry point and
  * independently bundled A2 copies all read the same scope.
  */
 export type AmbientToolScopeStorage = {
@@ -267,7 +277,7 @@ export function assertSchedulerTargets(
 export const DRAIN_TIMINGS: {
   /** How long a claim lives without renewal. */
   claimTtlMs: number
-  /** Heartbeat cadence while a handler is running. */
+  /** Heartbeat cadence while a consumer is running. */
   claimHeartbeatMs: number
   /** Base delay before retrying a failed renewal while the lease lives. */
   renewRetryMs: number
@@ -289,6 +299,21 @@ export const DRAIN_TIMINGS: {
   failureRetryMaxMs: 30_000,
 }
 
+/**
+ * How many kernels a harness keeps, per agent, for the next step of a session
+ * in its process. Mutable only as a white-box test seam; production always
+ * uses the default.
+ */
+export const HARNESS_PARKING: { maxKernels: number } = { maxKernels: 32 }
+
+/**
+ * Per server: called when a drain of a session ends with nothing left to run
+ * for it in this process, so the layer above can let go of what it kept for
+ * that session's next step.
+ */
+export const drainSettledHooks: WeakMap<object, (sessionId: string) => void> =
+  new WeakMap()
+
 /**
  * Stream liveness knobs — the server-side SSE heartbeat and the
  * client-side stall watchdog. Paired by design: the client declares a
@@ -313,16 +338,22 @@ export const POLL_TIMINGS: {
 }
 
 /**
- * Safety-read cadence for the notify-driven redis live stream. A
- * parked feed re-reads the store at this interval even without a
- * pub/sub wake-up, so a lost notification (subscriber reconnect gap,
- * dropped PUBLISH) costs latency, never an event. Mutable only as a
- * white-box test seam.
+ * Timings for the notify-driven redis live stream. A parked feed re-reads
+ * the store every `safetyReadMs` even without a pub/sub wake-up, so a lost
+ * notification (subscriber reconnect gap, dropped PUBLISH) costs latency,
+ * never an event. Writers publish after their scripts, so wake-ups from
+ * concurrent writers can arrive out of order: a feed holds a gap for
+ * `reorderMs` before catching up with a read, and a write waits at most
+ * `publishMs` for its PUBLISH. Mutable only as a white-box test seam.
  */
 export const NOTIFY_TIMINGS: {
   safetyReadMs: number
+  reorderMs: number
+  publishMs: number
 } = {
   safetyReadMs: 10_000,
+  reorderMs: 50,
+  publishMs: 1_000,
 }
 
 /**
@@ -412,15 +443,25 @@ export const SOCKET_TIMINGS: {
 }
 
 /**
- * Client presence send cadence — a leading send immediately, then at
- * most one merged send per interval (~15Hz). Owned, not configurable
- * (decision #36's rule): coupling the cadence to the POST ack tied
- * remote cursor smoothness to RTT, and the ack serves no correctness
- * purpose on a fire-and-forget LWW plane. Mutable only as a white-box
- * test seam.
+ * Presence timings. Owned, not configurable (decision #36's rule).
+ * Mutable only as a white-box test seam.
  */
 export const PRESENCE_TIMINGS: {
+  /**
+   * Client send cadence — a leading send immediately, then at most one
+   * merged send per interval (~15Hz). Coupling the cadence to the POST
+   * ack tied remote cursor smoothness to RTT, and the ack serves no
+   * correctness purpose on a fire-and-forget LWW plane.
+   */
   sendIntervalMs: number
+  /**
+   * How long, in local receipt time, a presence applier keeps a deleted
+   * field's stamp so an older set delivered after the delete still
+   * loses. Reorders span milliseconds; the bound keeps a long-lived
+   * client with churning participants from accumulating tombstones.
+   */
+  tombstoneMs: number
 } = {
   sendIntervalMs: 66,
+  tombstoneMs: 60_000,
 }

package/src/otel.ts

@@ -4,7 +4,7 @@
  * Peer-depends on `@opentelemetry/api` (optional). Spans nest through
  * the active context, so with a context manager registered (any real
  * OTel setup, e.g. `@vercel/otel`) the happy path lands in one trace:
- * request → a2.append → a2.drain → a2.event → the handler's own spans.
+ * request → a2.append → a2.drain → a2.event → the consumer's own spans.
  */
 
 import {

package/src/postgres-schema.ts

@@ -1,80 +1,121 @@
 /**
  * The Postgres schema contract. A2 never runs DDL in a Postgres database:
- * `sql/postgres/schema.sql` (and `notifications.sql` for
- * `listenConnectionString`) create the tables, and a store checks the
- * recorded version before its first query.
+ * `sql/postgres/schema.sql`, or the tables in `drizzle-schema.ts` next to it,
+ * create
+ * the tables, and `notifications.sql` the triggers `listenConnectionString`
+ * needs. A store checks nothing up front. A query that finds a table or column
+ * missing fails anyway, so the store only turns that failure into one that
+ * says what to apply. Missing triggers fail no query, so a listening store
+ * looks for them when its listener starts.
  */
 
 import { A2Error } from './errors.ts'
-import type { PostgresClient } from './store-postgres.ts'
-
-/** The `a2_schema` version this release needs; `schema.sql` records it. */
-export const POSTGRES_SCHEMA_VERSION = 1
+import type { PostgresClient, PostgresConnection } from './store-postgres.ts'
 
 const PACKAGE = 'node_modules/experimental-a2'
 
-const apply = (file: string): string =>
-  `apply ${PACKAGE}/sql/postgres/${file} to this database`
-
 const SEE_DOCS = `See ${PACKAGE}/docs/stores/04-postgres.mdx.`
 
-const VERSION = 'select version from a2_schema'
-const VERSION_AND_TRIGGERS = `select version, (select count(*) from pg_trigger
-   where (tgname = 'a2_notify_events' and tgrelid = to_regclass('a2_events'))
-      or (tgname = 'a2_notify_presence' and tgrelid = to_regclass('a2_presence')))
-  as notify_triggers from a2_schema`
+/** Postgres error codes a store that hasn't been set up raises. */
+const UNDEFINED_TABLE = '42P01'
+const UNDEFINED_COLUMN = '42703'
+const UNDEFINED_FUNCTION = '42883'
+/** `a2_batch` refuses to run outside read committed. */
+const BATCH_ISOLATION = 'A2002'
+const INSUFFICIENT_PRIVILEGE = '42501'
+/** NUL, which Postgres can't store: in jsonb (`\u0000`), or in text. */
+const UNTRANSLATABLE_CHARACTER = '22P05'
+const CHARACTER_NOT_IN_REPERTOIRE = '22021'
 
-/** Explains a failed version read, or returns undefined when the schema is not the cause. */
-const diagnose = async (
-  client: PostgresClient,
-): Promise<A2Error | undefined> => {
-  const [found] = (
-    await client.query(`select
-      to_regclass('a2_schema') is not null as marked,
-      to_regclass('a2_events') is not null as installed,
-      has_table_privilege(to_regclass('a2_schema'), 'select') as readable`)
-  ).rows
-  if (!found) return undefined
-  if (!found['marked'])
+/** The Postgres error in `error`'s cause chain, for clients that wrap theirs. */
+const postgresError = (
+  error: unknown,
+): { code: string; message: string } | undefined => {
+  for (let current = error, depth = 0; depth < 5; depth += 1) {
+    if (typeof current !== 'object' || current === null) return undefined
+    const { code, message, cause } = current as {
+      code?: unknown
+      message?: unknown
+      cause?: unknown
+    }
+    if (typeof code === 'string' && /^[0-9A-Z]{5}$/.test(code))
+      return { code, message: typeof message === 'string' ? message : code }
+    current = cause
+  }
+  return undefined
+}
+
+/** Explains a query that failed because A2's tables aren't set up, or on a NUL, or returns `error`. */
+export const explainPostgresError = (error: unknown): unknown => {
+  const found = postgresError(error)
+  if (
+    found?.code === UNDEFINED_TABLE ||
+    found?.code === UNDEFINED_COLUMN ||
+    found?.code === UNDEFINED_FUNCTION
+  )
     return new A2Error(
       'STORE_NOT_CONFIGURED',
-      found['installed']
-        ? `This Postgres database has A2's tables but no a2_schema version. That is expected once after upgrading from a release that created its tables at runtime, and your events are untouched. A2 doesn't create or change tables at runtime: ${apply('schema.sql')}. ${SEE_DOCS}`
-        : `A2's tables aren't in this Postgres database, and A2 doesn't create tables at runtime: ${apply('schema.sql')}. ${SEE_DOCS}`,
+      `${found.message}: A2's tables or its function are missing, or from an earlier release, and A2 doesn't create or change them at runtime. Apply ${PACKAGE}/sql/postgres/schema.sql to this database, or migrate it to the tables in drizzle-schema.ts next to it, with schema.sql's a2_batch function. ${SEE_DOCS}`,
+      { cause: error },
     )
-  if (found['readable'] === false)
+  if (found?.code === INSUFFICIENT_PRIVILEGE)
     return new A2Error(
       'STORE_NOT_CONFIGURED',
-      `The role this store connects as can't read a2_schema. Apply schema.sql as that role, or grant it select on a2_schema and select, insert, update, and delete on A2's other tables. ${SEE_DOCS}`,
+      `${found.message}: the role this store connects as needs select, insert, update, and delete on A2's tables, and execute on a2_batch. Create them as that role, or grant it those privileges. ${SEE_DOCS}`,
+      { cause: error },
     )
-  return undefined
-}
-
-/** Reads the schema version (and, with a listener, the triggers) in one query that takes no lock a writer holds. */
-export const checkPostgresSchema = async ({
-  client,
-  listen,
-}: {
-  client: PostgresClient
-  listen: boolean
-}): Promise<void> => {
-  let row: Record<string, unknown> | undefined
-  try {
-    row = (await client.query(listen ? VERSION_AND_TRIGGERS : VERSION)).rows[0]
-  } catch (err) {
-    throw (await diagnose(client).catch(() => undefined)) ?? err
-  }
-  const version = Number(row?.['version'] ?? 0)
-  if (version < POSTGRES_SCHEMA_VERSION) {
-    throw new A2Error(
+  // Nothing was written: the payload is the problem, so retrying can't help.
+  if (
+    found?.code === UNTRANSLATABLE_CHARACTER ||
+    found?.code === CHARACTER_NOT_IN_REPERTOIRE
+  )
+    return new A2Error(
+      'INVALID_PAYLOAD',
+      `${found.message}: Postgres can't store a NUL character (\\u0000) in text or jsonb, so nothing was written. Remove it before appending.`,
+      { cause: error },
+    )
+  if (found?.code === BATCH_ISOLATION)
+    return new A2Error(
       'STORE_NOT_CONFIGURED',
-      `This Postgres database has A2 schema version ${version}, and this release of experimental-a2 needs version ${POSTGRES_SCHEMA_VERSION}: ${apply('schema.sql')}. ${SEE_DOCS}`,
+      `${found.message}: A2 reads what it locks in read committed, Postgres's default, and its connections here default to a stricter level. Set default_transaction_isolation to 'read committed' for the role or database this store connects to. ${SEE_DOCS}`,
+      { cause: error },
     )
-  }
-  if (listen && Number(row?.['notify_triggers']) < 2) {
+  return error
+}
+
+const explained = <T>(promise: Promise<T>): Promise<T> =>
+  promise.catch((error: unknown) => {
+    throw explainPostgresError(error)
+  })
+
+/** `client`, with every query's setup failures explained. */
+export const explainingPostgresClient = (
+  client: PostgresClient,
+): PostgresClient => ({
+  query: (text, values) => explained(client.query(text, values)),
+  ...(client.connect && {
+    connect: async (): Promise<PostgresConnection> => {
+      const connection = await client.connect!()
+      return {
+        query: (text, values) => explained(connection.query(text, values)),
+        release: () => connection.release(),
+      }
+    },
+  }),
+  ...(client.end && { end: () => client.end!() }),
+})
+
+/** Fails when the triggers `listenConnectionString` listens to are missing. */
+export const checkPostgresTriggers = async (
+  client: PostgresClient,
+): Promise<void> => {
+  const { rows } =
+    await client.query(`select count(*) as triggers from pg_trigger
+   where (tgname = 'a2_notify_events' and tgrelid = to_regclass('a2_events'))
+      or (tgname = 'a2_notify_presence' and tgrelid = to_regclass('a2_presence'))`)
+  if (Number(rows[0]?.['triggers']) < 2)
     throw new A2Error(
       'STORE_NOT_CONFIGURED',
-      `listenConnectionString needs A2's notification triggers, which aren't in this Postgres database. After schema.sql, ${apply('notifications.sql')}. ${SEE_DOCS}`,
+      `listenConnectionString needs A2's notification triggers, which aren't in this Postgres database. After schema.sql, apply ${PACKAGE}/sql/postgres/notifications.sql to this database. ${SEE_DOCS}`,
     )
-  }
 }