experimental-a2 0.20.0 → 0.21.1

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/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,5 +1,5 @@
 /**
- * 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
@@ -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

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}`,
     )
-  }
 }

package/src/push-envelope.ts

@@ -77,6 +77,13 @@ export function parsePresenceSibling(
   return out
 }
 
+/** The longest event id a push may carry: ids are indexed, and Postgres's index rows have a limit. */
+const MAX_PUSHED_ID = 256
+
+/** A UUIDv5, the shape of the ids A2 derives (deterministic-id.ts). */
+const DERIVED_ID =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
 /** The events half of the envelope, shared by the POST body and socket
  * `push` frames so INVALID_PAYLOAD shapes have one implementation. */
 export function parsePushEvents(events: unknown): ParsedPushEvent[] {
@@ -94,6 +101,19 @@ export function parsePushEvents(events: unknown): ParsedPushEvent[] {
     if (id !== undefined && typeof id !== 'string') {
       throw invalid(`events[${i}].id must be a string when present`)
     }
+    if (id !== undefined && (id.length === 0 || id.length > MAX_PUSHED_ID)) {
+      throw invalid(
+        `events[${i}].id must be 1-${MAX_PUSHED_ID} characters when present`,
+      )
+    }
+    // A2 derives the ids of what consumers append, return, and schedule as
+    // UUIDv5s, from inputs a caller can know: one pushed first would take its
+    // place. Callers' own ids are v4 (crypto.randomUUID) or v8 (idempotentId).
+    if (id !== undefined && DERIVED_ID.test(id)) {
+      throw invalid(
+        `events[${i}].id is shaped like the ids A2 derives for consumers (a UUIDv5); use crypto.randomUUID() or idempotentId()`,
+      )
+    }
     const out: { type: string; payload: unknown; id?: string } = {
       type,
       payload,

package/src/runtime-consumer.ts

@@ -0,0 +1,10 @@
+/**
+ * `consumer()` for A2's own runtimes (actors, the AI runtime): their names
+ * sit under the reserved `a2.` prefix, and their child ids leave the name
+ * out, as the handler tables they replaced had. Not a public entry point.
+ */
+import { runtimeConsumerFactory } from './internal.ts'
+import type { consumer } from './server.ts'
+
+export const runtimeConsumer = ((options: never) =>
+  runtimeConsumerFactory.define!(options)) as typeof consumer

package/src/scheduler-task.ts

@@ -5,7 +5,7 @@ export type ScheduledEvent = {
   payload: unknown
 }
 
-/** A durable wake-up for pending handler work. */
+/** A durable wake-up for pending consumer work. */
 export type SchedulerDrainTask = {
   version: 1
   kind: 'drain'
@@ -26,7 +26,7 @@ export type SchedulerAppendTask = {
   /** Earliest useful delivery as epoch milliseconds. */
   dueAt: number
   events: readonly ScheduledEvent[]
-  /** The scheduling handler's event; delivery skips once it is cleared. */
+  /** The scheduling consumer's event; delivery skips once it is cleared. */
   originIndex?: number
 }
 

package/src/scheduler-vercel.ts

@@ -14,7 +14,7 @@
  *   the configured deployment scope for sending and receiving.
  * - `handler(...servers)` is the delivery route: look up the server for
  *   the contract named in the message and drain it. Settled drains ack;
- *   contention, handler failure, and a drain that throws after arming its
+ *   contention, consumer failure, and a drain that throws after arming its
  *   successor all ack once a later watchdog is durable.
  *
  * `@vercel/queue` is an optional peer dependency, imported lazily. The

package/src/server.browser.ts

@@ -2,7 +2,7 @@
  * The browser build of experimental-a2/server. There isn't one — on purpose.
  * Contracts and reducers (from `experimental-a2`) and the session client (from
  * `experimental-a2/client` / `experimental-a2/react`) are the isomorphic surface; the server is
- * where handlers and storage live. This module existing in a client
+ * where consumers and storage live. This module existing in a client
  * bundle means a `'use client'` file (or something it imports)
  * value-imported your server module.
  */