experimental-a2 0.20.0 → 0.22.0

package/examples/playground/app/orders/server.ts

@@ -1,6 +1,6 @@
 import 'server-only'
 import { vercelQueues } from 'experimental-a2/scheduler-vercel'
-import { createServer } from 'experimental-a2/server'
+import { consumer, createServer } from 'experimental-a2/server'
 import { store } from '@/lib/store'
 import { orders } from './model'
 
@@ -14,37 +14,56 @@ export const ordersScheduler =
     ? vercelQueues({ topic: 'a2-orders' })
     : undefined
 
+const notifyShop = consumer({
+  contract: orders,
+  name: 'notify-shop',
+  types: ['created'],
+}).run(async ({ session }) => {
+  await wait(800)
+  await session.append('notify-shop', {
+    type: 'shop.notified',
+    payload: {},
+  })
+})
+
+const notifyDriver = consumer({
+  contract: orders,
+  name: 'notify-driver',
+  types: ['shop.started'],
+}).run(async ({ session }) => {
+  await wait(1200)
+  const driverId = drivers[Math.floor(Math.random() * drivers.length)]!
+  await session.append('notify-driver', {
+    type: 'driver.notified',
+    payload: { driverId },
+  })
+})
+
+const pickUp = consumer({
+  contract: orders,
+  name: 'pick-up',
+  types: ['driver.notified'],
+}).run(async ({ session }) => {
+  await wait(3000)
+  const etaMinutes = 3 + Math.floor(Math.random() * 5)
+  await session.append('courier-picked-up', {
+    type: 'courier.picked_up',
+    payload: { etaMinutes },
+  })
+})
+
+const deliver = consumer({
+  contract: orders,
+  name: 'deliver',
+  types: ['courier.picked_up'],
+}).run(async ({ session }) => {
+  await wait(3500)
+  await session.append('delivered', { type: 'delivered', payload: {} })
+})
+
 export const ordersServer = createServer({
   ...(store ? { store } : {}),
   ...(ordersScheduler ? { scheduler: ordersScheduler } : {}),
   contract: orders,
-  handlers: {
-    created: async ({ session }) => {
-      await wait(800)
-      await session.append('notify-shop', {
-        type: 'shop.notified',
-        payload: {},
-      })
-    },
-    'shop.started': async ({ session }) => {
-      await wait(1200)
-      const driverId = drivers[Math.floor(Math.random() * drivers.length)]!
-      await session.append('notify-driver', {
-        type: 'driver.notified',
-        payload: { driverId },
-      })
-    },
-    'driver.notified': async ({ session }) => {
-      await wait(3000)
-      const etaMinutes = 3 + Math.floor(Math.random() * 5)
-      await session.append('courier-picked-up', {
-        type: 'courier.picked_up',
-        payload: { etaMinutes },
-      })
-    },
-    'courier.picked_up': async ({ session }) => {
-      await wait(3500)
-      await session.append('delivered', { type: 'delivered', payload: {} })
-    },
-  },
+  consumers: [notifyShop, notifyDriver, pickUp, deliver],
 })

package/examples/playground/app/recovery/[recoveryId]/recovery-client.tsx

@@ -45,7 +45,7 @@ export function RecoveryClient({
   return (
     <article>
       <header className="session-header">
-        <h1>Cross-invocation handler chain</h1>
+        <h1>Cross-invocation step chain</h1>
         <ConnectionPill connection={connection} />
         <span
           className={`badge${completed ? ' done' : running ? ' waiting' : ''}`}
@@ -59,14 +59,14 @@ export function RecoveryClient({
       </header>
 
       <p className="lede">
-        Four handlers fit individually, but their 32-second chain does not fit
-        in one 20-second function. Every invocation has the same limit.
+        Four steps fit individually, but their 32-second chain does not fit in
+        one 20-second function. Every invocation has the same limit.
       </p>
 
       <dl className="facts">
         <dt>Function limit</dt>
         <dd>{FUNCTION_LIMIT_SECONDS} seconds</dd>
-        <dt>Each handler</dt>
+        <dt>Each step</dt>
         <dd>{STEP_SECONDS} seconds</dd>
         <dt>Whole chain</dt>
         <dd>
@@ -94,15 +94,14 @@ export function RecoveryClient({
           <h2>The chain is crossing function invocations</h2>
           <p>
             Each step waits eight seconds before appending its completion fact.
-            A2 does not predict whether the next handler fits. The first
-            invocation completes two handlers, starts the third, and is stopped
-            by Vercel at 20 seconds. That event stays pending. Its claim
-            watchdog acquires the expired claim and retries the same event in a
-            fresh function.
+            A2 does not predict whether the next step fits. The first invocation
+            completes two steps, starts the third, and is stopped by Vercel at
+            20 seconds. That event stays pending. Its claim watchdog acquires
+            the expired claim and retries the same event in a fresh function.
           </p>
           <p className="hint">
             Keep this page open. Claim heartbeats keep scheduling watchdogs
-            while a handler is alive. The known function deadline caps the last
+            while a step is running. The known function deadline caps the last
             claim window, so the scheduler arrives just after Vercel stops the
             worker. Reloading can also trigger A2&apos;s separate
             interaction-healing path.
@@ -112,8 +111,8 @@ export function RecoveryClient({
 
       {completed ? (
         <p className="proof">
-          All {state.completedSteps} bounded handlers finished. The scheduler
-          added no event of its own; it only continued draining the pending
+          All {state.completedSteps} bounded steps finished. The scheduler added
+          no event of its own; it only continued draining the pending
           application events.
         </p>
       ) : null}
@@ -127,12 +126,12 @@ export function RecoveryClient({
             state.completedSteps < STEP_COUNT ? (
               <>
                 Waiting for step {state.completedSteps + 1} of {STEP_COUNT}. The
-                event log stays quiet while its {STEP_SECONDS}-second handler
-                runs; the next row is the handler&apos;s real completion fact.
+                event log stays quiet while its {STEP_SECONDS}-second step runs;
+                the next row is the step&apos;s real completion fact.
               </>
             ) : (
               <>
-                All four handlers finished. Waiting for the final{' '}
+                All four steps finished. Waiting for the final{' '}
                 <code>pipeline.completed</code> fact from the active drain.
               </>
             )

package/examples/playground/app/recovery/page.tsx

@@ -6,10 +6,10 @@ export default function RecoveryPage(): ReactNode {
     <article>
       <h1>Recovery lab</h1>
       <p className="lede">
-        Run four 8-second handlers in a chain. Each fits inside a 20-second
-        Vercel function, but all 32 seconds cannot. Watch Vercel stop one
-        mid-handler, then let A2 retry that pending event in a fresh invocation
-        with the same limit.
+        Run four 8-second steps in a chain. Each fits inside a 20-second Vercel
+        function, but all 32 seconds cannot. Watch Vercel stop one mid-step,
+        then let A2 retry that pending event in a fresh invocation with the same
+        limit.
       </p>
       <NewRecoverySession />
       <p className="hint">

package/examples/playground/app/recovery/server.ts

@@ -1,6 +1,6 @@
 import 'server-only'
 import { vercelQueues } from 'experimental-a2/scheduler-vercel'
-import { createServer } from 'experimental-a2/server'
+import { consumer, createServer } from 'experimental-a2/server'
 import { store } from '@/lib/store'
 import { recovery } from './model'
 
@@ -15,39 +15,30 @@ export const recoveryScheduler =
     ? vercelQueues({ topic: 'a2-recovery' })
     : undefined
 
+/** Each step waits its 8 seconds, then returns the next one, in one lane. */
+const runPipeline = consumer({
+  contract: recovery,
+  name: 'run-pipeline',
+  types: ['pipeline.started', 'step.completed'],
+  lane: 'pipeline',
+}).run(async ({ event }) => {
+  const step = event.type === 'step.completed' ? event.payload.step : 0
+  if (step === stepCount) {
+    return {
+      type: 'pipeline.completed',
+      payload: { stepCount },
+    }
+  }
+  await wait(stepDurationSeconds * 1_000)
+  return {
+    type: 'step.completed',
+    payload: { step: step + 1, durationSeconds: stepDurationSeconds },
+  }
+})
+
 export const recoveryServer = createServer({
   ...(store ? { store } : {}),
   ...(recoveryScheduler ? { scheduler: recoveryScheduler } : {}),
   contract: recovery,
-  handlers: {
-    'pipeline.started': {
-      lane: 'pipeline',
-      handler: async () => {
-        await wait(stepDurationSeconds * 1_000)
-        return {
-          type: 'step.completed',
-          payload: { step: 1, durationSeconds: stepDurationSeconds },
-        }
-      },
-    },
-    'step.completed': {
-      lane: 'pipeline',
-      handler: async ({ event }) => {
-        if (event.payload.step === stepCount) {
-          return {
-            type: 'pipeline.completed',
-            payload: { stepCount },
-          }
-        }
-        await wait(stepDurationSeconds * 1_000)
-        return {
-          type: 'step.completed',
-          payload: {
-            step: event.payload.step + 1,
-            durationSeconds: stepDurationSeconds,
-          },
-        }
-      },
-    },
-  },
+  consumers: [runPipeline],
 })

package/examples/playground/drizzle.config.ts

@@ -0,0 +1,14 @@
+// The Postgres at DATABASE_URL: a2slack's tables, and A2's (db/a2.ts, a copy
+// of experimental-a2's drizzle-schema.ts). tablesFilter keeps push and
+// studio to these, since other apps share the database.
+import { defineConfig } from 'drizzle-kit'
+
+export default defineConfig({
+  dialect: 'postgresql',
+  schema: './app/a2slack/db/schema.ts',
+  out: './app/a2slack/db/migrations',
+  casing: 'snake_case',
+  dbCredentials: { url: process.env.DATABASE_URL ?? '' },
+  tablesFilter: ['a2slack_*', 'a2_*'],
+  migrations: { table: 'a2slack_migrations', schema: 'public' },
+})

package/examples/playground/lib/store.ts

@@ -9,7 +9,7 @@ const postgresUrl = process.env.DATABASE_URL?.replace(
 )
 
 export const store: RedisStore | PostgresStore | undefined = redisUrl
-  ? redis({ url: redisUrl })
+  ? redis({ url: redisUrl, keyPrefix: 'a2-playground-tagged' })
   : postgresUrl
     ? postgres({ connectionString: postgresUrl })
     : undefined

package/examples/playground/next.config.ts

@@ -12,7 +12,12 @@ const nextConfig: NextConfig = {
   // Turbopack panic on its WebAssembly), so it finds photon through this
   // app: package.json depends on photon at the version Pi pins, and the two
   // move together.
-  serverExternalPackages: ['libfx', '@silvia-odwyer/photon-node'],
+  serverExternalPackages: [
+    'libfx',
+    '@silvia-odwyer/photon-node',
+    // a2slack's development database, PGlite, loads its WebAssembly by path.
+    '@electric-sql/pglite',
+  ],
   turbopack: {
     // WebAssembly Pi's code reaches that the bundler cannot trace.
     resolveAlias: {

package/examples/playground/package.json

@@ -11,18 +11,26 @@
   "scripts": {
     "dev": "next dev",
     "build": "next build",
+    "vercel-build": "node scripts/migrate.mjs && turbo run build",
     "test": "vitest run",
+    "drills": "vitest run --config vitest.drills.config.ts",
     "typecheck": "tsc --noEmit",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "node scripts/migrate.mjs",
     "a0:template": "node --env-file-if-exists=.env.local scripts/a0-template.ts"
   },
   "dependencies": {
     "@ai-sdk/otel": "1.0.58",
+    "@base-ui/react": "^1.7.0",
     "@codemirror/state": "^6.7.1",
     "@codemirror/view": "^6.43.8",
+    "@electric-sql/pglite": "^0.3.14",
     "@earendil-works/pi-ai": "1.0.3",
     "@earendil-works/pi-coding-agent": "1.0.2",
     "@opentelemetry/api": "^1.9.0",
+    "@paper-design/shaders-react": "^0.0.80",
     "@silvia-odwyer/photon-node": "0.3.4",
+    "@upstash/redis": "^1.39.0",
     "@vercel/blob": "^2.8.0",
     "@vercel/functions": "^3.9.3",
     "@vercel/otel": "^2.1.0",
@@ -30,7 +38,8 @@
     "@vercel/sandbox": "^3.0.0",
     "ai": "^7.0.58",
     "codemirror": "^6.0.2",
-    "experimental-a2": "0.20.0",
+    "drizzle-orm": "^0.45.3",
+    "experimental-a2": "0.22.0",
     "geist": "^1.7.2",
     "ioredis": "^5.9.0",
     "libfx": "0.0.12",
@@ -52,9 +61,11 @@
     "@testing-library/react": "^16.1.0",
     "jsdom": "^26.0.0",
     "@types/node": "^24.0.0",
+    "@types/pg": "^8.15.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@types/ws": "^8.18.1",
+    "drizzle-kit": "^0.31.11",
     "typescript": "^7.0.2",
     "undici": "^8.10.2",
     "vitest": "^4.1.10"

package/examples/playground/scripts/migrate.mjs

@@ -0,0 +1,31 @@
+/**
+ * Applies app/a2slack/db/migrations to the Postgres at DATABASE_URL_UNPOOLED
+ * (the Neon integration's direct connection) or DATABASE_URL. drizzle-kit
+ * migrate does the same, but hides the database's error when one fails.
+ *
+ *   DATABASE_URL=postgres://… pnpm --filter playground db:migrate
+ */
+import { drizzle } from 'drizzle-orm/node-postgres'
+import { migrate } from 'drizzle-orm/node-postgres/migrator'
+
+const url = process.env.DATABASE_URL_UNPOOLED || process.env.DATABASE_URL
+if (!url) {
+  console.error('error: set DATABASE_URL to the Postgres to migrate')
+  process.exit(1)
+}
+
+const db = drizzle({ connection: url })
+try {
+  await migrate(db, {
+    migrationsFolder: new URL('../app/a2slack/db/migrations', import.meta.url)
+      .pathname,
+    migrationsTable: 'a2slack_migrations',
+    migrationsSchema: 'public',
+  })
+  console.log('migrations applied')
+} catch (error) {
+  console.error('error: migrations failed, and none were applied:', error)
+  process.exitCode = 1
+} finally {
+  await db.$client.end()
+}

package/examples/playground/vercel.json

@@ -71,6 +71,15 @@
           "retryAfterSeconds": 30
         }
       ]
+    },
+    "app/a2slack/scheduler/route.ts": {
+      "experimentalTriggers": [
+        {
+          "type": "queue/v2beta",
+          "topic": "a2-a2slack",
+          "retryAfterSeconds": 30
+        }
+      ]
     }
   }
 }

package/examples/playground/vitest.drills.config.ts

@@ -0,0 +1,32 @@
+// The a2slack drills (app/a2slack/drills): load, rebuild, and failure runs
+// against a throwaway Redis and Postgres they start themselves. Not part of
+// `pnpm test`; run them with `pnpm drills`.
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  resolve: {
+    tsconfigPaths: true,
+    alias: {
+      'server-only': fileURLToPath(
+        new URL('./test/server-only.ts', import.meta.url),
+      ),
+    },
+  },
+  test: {
+    include: ['app/a2slack/drills/*.drill.ts'],
+    fileParallelism: false,
+    testTimeout: 15 * 60_000,
+    hookTimeout: 120_000,
+    env: {
+      VERCEL: '',
+      A2_QUEUES: '',
+      AI_GATEWAY_API_KEY: '',
+      VERCEL_OIDC_TOKEN: '',
+      KV_REST_API_URL: '',
+      KV_REST_API_TOKEN: '',
+      REDIS_KV_REST_API_URL: '',
+      REDIS_KV_REST_API_TOKEN: '',
+    },
+  },
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-a2",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Syncs your immutable event log, from server to browser: one contract, handlers, derived state, and a live client per session.",
   "license": "MIT",
   "type": "module",
@@ -113,6 +113,9 @@
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.3.14",
+    "experimental-a2-0-20": "npm:experimental-a2@0.20.0",
+    "drizzle-kit": "^0.31.11",
+    "drizzle-orm": "^0.45.3",
     "@upstash/qstash": "^2.11.3",
     "ai": "^7.0.58",
     "ioredis": "^5.9.0",
@@ -146,7 +149,7 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.reference.json",
     "test": "vitest run",
     "test:watch": "vitest"
   }

package/sql/postgres/drizzle-schema.ts

@@ -0,0 +1,209 @@
+/**
+ * An example: A2's tables for experimental-a2/store-postgres as Drizzle
+ * definitions, the same tables schema.sql next to this file creates. It isn't
+ * an API, and nothing imports it. Use it however fits your setup, for example
+ * as a copy next to your own schema, so your migrations create A2's tables
+ * with yours. Adapt it to your Drizzle version, your ORM, and how you lay out
+ * your schema.
+ *
+ * Whatever creates them, A2 relies on the table and column names, the column
+ * types, the primary keys, and the unique index on a2_events (session_id,
+ * event_id). The other indexes keep its queries fast. Every name is spelled
+ * out, so Drizzle's `casing` setting changes none of them.
+ *
+ * A2's tables change only when a release's changelog says so; compare your
+ * copy with that release's file. Drizzle can't declare functions or
+ * triggers: add schema.sql's `a2_batch` function, which A2 runs its writes
+ * through, as a custom migration (`drizzle-kit generate --custom`), and the
+ * triggers `listenConnectionString` needs are in notifications.sql.
+ */
+import { sql } from 'drizzle-orm'
+import {
+  bigint,
+  boolean,
+  index,
+  integer,
+  jsonb,
+  pgTable,
+  primaryKey,
+  text,
+  uniqueIndex,
+} from 'drizzle-orm/pg-core'
+
+const int8 = (name: string) => bigint(name, { mode: 'number' })
+
+export const a2Events = pgTable(
+  'a2_events',
+  {
+    sessionId: text('session_id').notNull(),
+    idx: int8('idx').notNull(),
+    eventType: text('event_type').notNull(),
+    payload: jsonb('payload').notNull(),
+    eventId: text('event_id').notNull(),
+    createdAt: int8('created_at').notNull(),
+    cause: jsonb('cause'),
+  },
+  (table) => [
+    primaryKey({
+      name: 'a2_events_pkey',
+      columns: [table.sessionId, table.idx],
+    }),
+    uniqueIndex('a2_events_session_event_id').on(
+      table.sessionId,
+      table.eventId,
+    ),
+    index('a2_events_types').on(table.sessionId, table.eventType, table.idx),
+  ],
+)
+
+/**
+ * One row per run of a cursor: an event cursor's one event, a lane's run of
+ * queued events, or a log cursor's position.
+ */
+export const a2Cursors = pgTable(
+  'a2_cursors',
+  {
+    sessionId: text('session_id').notNull(),
+    consumer: text('consumer').notNull(),
+    cursorKey: text('cursor_key').notNull(),
+    epoch: int8('epoch').notNull(),
+    lane: text('lane'),
+    kind: text('kind').notNull(),
+    position: int8('position').notNull(),
+    head: int8('head'),
+    types: jsonb('types'),
+    attemptCount: integer('attempt_count').notNull().default(0),
+    firstClaimedAt: int8('first_claimed_at'),
+    lastClaimedAt: int8('last_claimed_at'),
+    claimHolder: text('claim_holder'),
+    claimExpiresAt: int8('claim_expires_at'),
+    failureCount: integer('failure_count').notNull().default(0),
+    lastFailedAt: int8('last_failed_at'),
+    lastFailedAttempt: integer('last_failed_attempt'),
+    lastError: text('last_error'),
+    failedAt: int8('failed_at'),
+    completedIdx: int8('completed_idx'),
+    completedAttempt: integer('completed_attempt'),
+    returnedEventIds: jsonb('returned_event_ids'),
+  },
+  (table) => [
+    primaryKey({
+      name: 'a2_cursors_pkey',
+      columns: [table.sessionId, table.cursorKey, table.consumer, table.epoch],
+    }),
+    index('a2_cursors_heads')
+      .on(table.sessionId, table.head)
+      .where(sql`head is not null`),
+    index('a2_cursors_lanes')
+      .on(table.sessionId)
+      .where(sql`kind = 'lane'`),
+  ],
+)
+
+/** A lane cursor's queue: the events appended for the lane, in log order. */
+export const a2LaneEvents = pgTable(
+  'a2_lane_events',
+  {
+    sessionId: text('session_id').notNull(),
+    consumer: text('consumer').notNull(),
+    lane: text('lane').notNull(),
+    idx: int8('idx').notNull(),
+    done: boolean('done').notNull().default(false),
+    completedAttempt: integer('completed_attempt'),
+    returnedEventIds: jsonb('returned_event_ids'),
+  },
+  (table) => [
+    primaryKey({
+      name: 'a2_lane_events_pkey',
+      columns: [table.sessionId, table.consumer, table.lane, table.idx],
+    }),
+  ],
+)
+
+export const a2Snapshots = pgTable(
+  'a2_snapshots',
+  {
+    sessionId: text('session_id').notNull(),
+    reducerName: text('reducer_name').notNull(),
+    upToIndex: int8('up_to_index').notNull(),
+    state: jsonb('state').notNull(),
+    updatedAt: int8('updated_at').notNull(),
+  },
+  (table) => [
+    primaryKey({
+      name: 'a2_snapshots_pkey',
+      columns: [table.sessionId, table.reducerName],
+    }),
+  ],
+)
+
+export const a2SnapshotHistory = pgTable(
+  'a2_snapshot_history',
+  {
+    sessionId: text('session_id').notNull(),
+    reducerName: text('reducer_name').notNull(),
+    upToIndex: int8('up_to_index').notNull(),
+    state: jsonb('state').notNull(),
+    updatedAt: int8('updated_at').notNull(),
+  },
+  (table) => [
+    primaryKey({
+      name: 'a2_snapshot_history_pkey',
+      columns: [table.sessionId, table.reducerName, table.upToIndex],
+    }),
+  ],
+)
+
+export const a2SnapshotPins = pgTable(
+  'a2_snapshot_pins',
+  {
+    sessionId: text('session_id').notNull(),
+    eventIndex: int8('event_index').notNull(),
+    consumer: text('consumer').notNull(),
+    cursorKey: text('cursor_key').notNull(),
+    reducerName: text('reducer_name').notNull(),
+    upToIndex: int8('up_to_index').notNull(),
+  },
+  (table) => [
+    primaryKey({
+      name: 'a2_snapshot_pins_pkey',
+      columns: [
+        table.sessionId,
+        table.eventIndex,
+        table.consumer,
+        table.cursorKey,
+        table.reducerName,
+        table.upToIndex,
+      ],
+    }),
+    index('a2_snapshot_pins_checkpoint').on(
+      table.sessionId,
+      table.reducerName,
+      table.upToIndex,
+    ),
+  ],
+)
+
+export const a2Clears = pgTable('a2_clears', {
+  sessionId: text('session_id').primaryKey(),
+  clearIndex: int8('clear_index').notNull(),
+})
+
+export const a2Presence = pgTable(
+  'a2_presence',
+  {
+    ns: text('ns').notNull(),
+    participant: text('participant').notNull(),
+    field: text('field').notNull(),
+    value: jsonb('value').notNull(),
+    seen: int8('seen').notNull(),
+    at: int8('at').notNull(),
+    expiresAt: int8('expires_at').notNull(),
+  },
+  (table) => [
+    primaryKey({
+      name: 'a2_presence_pkey',
+      columns: [table.ns, table.participant, table.field],
+    }),
+  ],
+)