experimental-a2 0.19.0 → 0.21.1

package/src/ai-harness.ts

@@ -14,6 +14,7 @@ import type {
   ReasoningLevel,
   ToolResultPayload,
 } from './ai.ts'
+import { createHash } from 'node:crypto'
 import { STEERED_REASON } from './ai-control.ts'
 import { boundedCache, type BoundedCache } from './bounded-cache.ts'
 import type { ContractEvent, EventDefs } from './contract.ts'
@@ -322,6 +323,7 @@ export type HarnessInput = { text: string; files: FileUIPart[] }
 
 /** One harness turn to rebuild: its prompt, completed generations, and end. */
 export type HarnessTurn = {
+  /** With any steering that entered before the turn's first completed generation. */
   prompt: HarnessInput
   generations: RecordedGeneration[]
   /** Steering that entered after the generation at that index. */
@@ -440,8 +442,15 @@ export function harnessTurns(
       files: response.prompt.flatMap((prompt) => prompt.files),
     }
     let turn = turns.at(-1)
-    if (steered && turn !== undefined) {
-      const at = Math.max(0, turn.generations.length - 1)
+    if (steered && turn?.generations.length === 0) {
+      // Nothing answered the prompt yet, so the steering joins it, as messages
+      // queued before a response join its prompt.
+      turn.prompt = {
+        text: `${turn.prompt.text}\n\n${input.text}`,
+        files: [...turn.prompt.files, ...input.files],
+      }
+    } else if (steered && turn !== undefined) {
+      const at = turn.generations.length - 1
       turn.steers.set(at, [...(turn.steers.get(at) ?? []), input])
     } else {
       turn = { prompt: input, generations: [], steers: new Map(), end: 'live' }
@@ -598,6 +607,23 @@ export function gatewayCredential(harness: string): GatewayCredential {
   throw new Error(`${harness}() needs AI_GATEWAY_API_KEY or VERCEL_OIDC_TOKEN`)
 }
 
+/**
+ * The `x-session-affinity` an agent session's Gateway calls carry: stable for
+ * the session, so supporting providers can reuse their cache, and free of its
+ * raw ID.
+ */
+export function gatewaySessionAffinity({
+  agentName,
+  sessionId,
+}: {
+  agentName: string
+  sessionId: string
+}): string {
+  return createHash('sha256')
+    .update(JSON.stringify([agentName, sessionId]))
+    .digest('hex')
+}
+
 // Where Vercel Functions keep the current request, as @vercel/oidc reads it.
 const REQUEST_CONTEXT = Symbol.for('@vercel/request-context')
 

package/src/ai-pi.ts

@@ -436,7 +436,7 @@ async function runStep(
     const result = results.get(toolCallId)
     if (result !== undefined) return answeredTool(result, shape)
     if (state.plan.end === 'live' && state.liveStep) {
-      // Pi now waits on tools that A2's tool handlers run.
+      // Pi now waits on tools that A2's tool consumer run.
       endStep(state)
       return pending(signal)
     }
@@ -962,7 +962,7 @@ function builtinDefinition(
 
 /**
  * The tools Pi's session declares: Pi's own, and the agent's. Their results
- * come from A2's log; A2's tool handlers ran them.
+ * come from A2's log; A2's tool consumer ran them.
  */
 async function sessionTools(
   modules: PiModules,

package/src/ai-server.ts

@@ -1,10 +1,10 @@
 /**
  * experimental-a2/ai/server — `agent()`: the experimental-a2/ai protocol,
- * its model and tool handlers, and A2's store, scheduler, and telemetry,
+ * its model and tool consumers, and A2's store, scheduler, and telemetry,
  * assembled as one ordinary A2 server.
  */
 
-export { agent, runWithHandlerContext } from './ai-agent.ts'
+export { agent, runWithConsumerContext } from './ai-agent.ts'
 export type {
   AISDKHarness,
   Agent,

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' // production boot with no `store` passed
+  | '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

@@ -7,7 +7,8 @@ import type { ScheduledEvent } from './scheduler-task.ts'
 import type { DrainableServer } from './server.ts'
 import type { Event } from './store.ts'
 
-export type DrainOutcome = 'busy' | 'stalled' | 'settled'
+/** `failed`: a scheduler drain threw after arming its successor. */
+export type DrainOutcome = 'busy' | 'stalled' | 'settled' | 'failed'
 
 /**
  * A null-prototype record for maps keyed by caller-controlled strings
@@ -74,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.
  */
@@ -83,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
 }
@@ -94,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 = {
@@ -266,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-notifications.ts

@@ -220,25 +220,3 @@ export function postgresNotifications(
   }
   return manager
 }
-
-export const POSTGRES_NOTIFICATIONS_SQL = `
-create or replace function a2_notify_events() returns trigger language plpgsql as $$
-begin
-  perform pg_notify('a2_events_' || md5(new.session_id), '');
-  return null;
-end $$;
-create or replace function a2_notify_presence() returns trigger language plpgsql as $$
-begin
-  perform pg_notify('a2_presence_' || md5(case when TG_OP = 'DELETE' then old.ns else new.ns end),
-    coalesce(current_setting('a2.presence_source', true), ''));
-  return null;
-end $$;
-do $$ begin
-  if not exists (select 1 from pg_trigger where tgname = 'a2_notify_events' and tgrelid = 'a2_events'::regclass) then
-    create trigger a2_notify_events after insert on a2_events for each row execute function a2_notify_events();
-  end if;
-  if not exists (select 1 from pg_trigger where tgname = 'a2_notify_presence' and tgrelid = 'a2_presence'::regclass) then
-    create trigger a2_notify_presence after insert or update or delete on a2_presence for each row execute function a2_notify_presence();
-  end if;
-end $$;
-`

package/src/postgres-resources.ts

@@ -15,10 +15,7 @@ export type PostgresQueries = {
   client: PostgresClient
   raw: PostgresClient
   exclusive<T>(fn: () => Promise<T>): Promise<T>
-  initialize(options: {
-    schema: string
-    run: () => Promise<void>
-  }): Promise<void>
+  initialize(options: { key: string; run: () => Promise<void> }): Promise<void>
   close(): Promise<void>
 }
 
@@ -128,7 +125,7 @@ export function postgresConnectionKey({
 
 const queries = (raw: PostgresClient): PostgresQueries => {
   let pending: Promise<unknown> = Promise.resolve()
-  const schemas = new Map<string, Promise<void>>()
+  const initialized = new Map<string, Promise<void>>()
   const exclusive = <T>(fn: () => Promise<T>): Promise<T> => {
     const result = pending.then(fn)
     pending = result.catch(() => {})
@@ -140,13 +137,13 @@ const queries = (raw: PostgresClient): PostgresQueries => {
       ? raw
       : { query: (text, values) => exclusive(() => raw.query(text, values)) },
     exclusive,
-    initialize({ schema, run }) {
-      const existing = schemas.get(schema)
+    initialize({ key, run }) {
+      const existing = initialized.get(key)
       if (existing) return existing
       const attempt = run()
-      schemas.set(schema, attempt)
+      initialized.set(key, attempt)
       void attempt.catch(() => {
-        if (schemas.get(schema) === attempt) schemas.delete(schema)
+        if (initialized.get(key) === attempt) initialized.delete(key)
       })
       return attempt
     },

package/src/postgres-schema.ts

@@ -0,0 +1,121 @@
+/**
+ * The Postgres schema contract. A2 never runs DDL in a Postgres database:
+ * `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, PostgresConnection } from './store-postgres.ts'
+
+const PACKAGE = 'node_modules/experimental-a2'
+
+const SEE_DOCS = `See ${PACKAGE}/docs/stores/04-postgres.mdx.`
+
+/** 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'
+
+/** 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.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?.code === INSUFFICIENT_PRIVILEGE)
+    return new A2Error(
+      'STORE_NOT_CONFIGURED',
+      `${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 },
+    )
+  // 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',
+      `${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 },
+    )
+  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 ${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-qstash.ts

@@ -497,8 +497,11 @@ const readBoundedBody = async (
   return new TextDecoder().decode(bytes)
 }
 
-const storeUnavailable = (error: unknown): error is A2Error =>
-  error instanceof A2Error && error.code === 'STORE_UNAVAILABLE'
+// A store that isn't set up yet (Postgres before schema.sql, a missing driver)
+// is fixed without changing the task, so its work waits like any outage.
+const storeOutage = (error: unknown): error is A2Error =>
+  error instanceof A2Error &&
+  (error.code === 'STORE_UNAVAILABLE' || error.code === 'STORE_NOT_CONFIGURED')
 
 const response = {
   ok: (): Response => new Response('ok'),
@@ -888,7 +891,7 @@ export function qstash(options: QStashSchedulerOptions = {}): A2Scheduler {
               await deliverSchedulerAppend(server, task)
             else await deliverSchedulerClear(server, task)
           } catch (error) {
-            if (!storeUnavailable(error)) throw error
+            if (!storeOutage(error)) throw error
             await sendStoreOutageSuccessor(task, outage)
           }
           return response.ok()
@@ -906,13 +909,17 @@ export function qstash(options: QStashSchedulerOptions = {}): A2Scheduler {
                 outcome: 'unknown' as const,
               }
         } catch (error) {
-          if (!storeUnavailable(error)) throw error
+          if (!storeOutage(error)) throw error
           await sendStoreOutageSuccessor(task, outage)
           return response.ok()
         }
         if (result.settled) return response.ok()
 
-        if (result.outcome === 'busy' || result.outcome === 'stalled') {
+        if (
+          result.outcome === 'busy' ||
+          result.outcome === 'stalled' ||
+          result.outcome === 'failed'
+        ) {
           if (result.schedulerArm) await result.schedulerArm
           else {
             await sendTask({