experimental-a2 0.8.0 → 0.8.1

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

@@ -0,0 +1,144 @@
+'use client'
+import type { ReactNode } from 'react'
+import { useState } from 'react'
+import { ActivityFeed } from '@/app/components/activity-feed'
+import { ConnectionPill } from '@/app/components/connection-pill'
+import { useSession } from './session'
+
+const FUNCTION_LIMIT_SECONDS = 20
+const STEP_SECONDS = 8
+const STEP_COUNT = 4
+
+export function RecoveryClient({
+  sessionId,
+  onVercel,
+}: {
+  sessionId: string
+  onVercel: boolean
+}): ReactNode {
+  const { state, events, index, connection } = useSession()
+  const [error, setError] = useState<string | null>(null)
+  const [starting, setStarting] = useState(false)
+
+  const run = async (): Promise<void> => {
+    setError(null)
+    setStarting(true)
+    try {
+      const response = await fetch('/recovery/start', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ sessionId }),
+      })
+      if (!response.ok) {
+        throw new Error(`recovery trigger returned ${response.status}`)
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err))
+    } finally {
+      setStarting(false)
+    }
+  }
+
+  const running = state.phase === 'running'
+  const completed = state.phase === 'completed'
+
+  return (
+    <article>
+      <header className="session-header">
+        <h1>Cross-invocation handler chain</h1>
+        <ConnectionPill connection={connection} />
+        <span
+          className={`badge${completed ? ' done' : running ? ' waiting' : ''}`}
+        >
+          {completed
+            ? 'completed'
+            : running
+              ? `${state.completedSteps}/${state.stepCount ?? STEP_COUNT} steps`
+              : 'ready'}
+        </span>
+      </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.
+      </p>
+
+      <dl className="facts">
+        <dt>Function limit</dt>
+        <dd>{FUNCTION_LIMIT_SECONDS} seconds</dd>
+        <dt>Each handler</dt>
+        <dd>{STEP_SECONDS} seconds</dd>
+        <dt>Whole chain</dt>
+        <dd>
+          {STEP_COUNT} × {STEP_SECONDS} = {STEP_COUNT * STEP_SECONDS} seconds
+        </dd>
+        <dt>Queue consumer limit</dt>
+        <dd>{FUNCTION_LIMIT_SECONDS} seconds</dd>
+      </dl>
+
+      <button
+        disabled={state.phase !== 'idle' || starting || !onVercel}
+        onClick={() => void run()}
+      >
+        {starting ? 'Committing…' : 'Start four-step chain'}
+      </button>
+      {!onVercel ? (
+        <p className="hint">
+          Deploy this playground to Vercel to supply a real invocation deadline
+          and queue redelivery. <code>next dev</code> has neither boundary.
+        </p>
+      ) : null}
+
+      {running ? (
+        <section className="timeout-callout">
+          <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.
+          </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
+            claim window, so the scheduler arrives just after Vercel stops the
+            worker. Reloading can also trigger A2&apos;s separate
+            interaction-healing path.
+          </p>
+        </section>
+      ) : null}
+
+      {completed ? (
+        <p className="proof">
+          All {state.completedSteps} bounded handlers finished. The scheduler
+          added no event of its own; it only continued draining the pending
+          application events.
+        </p>
+      ) : null}
+      {error ? <p className="error">{error}</p> : null}
+
+      <ActivityFeed
+        events={events}
+        index={index}
+        status={
+          running ? (
+            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.
+              </>
+            ) : (
+              <>
+                All four handlers finished. Waiting for the final{' '}
+                <code>pipeline.completed</code> fact from the active drain.
+              </>
+            )
+          ) : undefined
+        }
+      />
+    </article>
+  )
+}

package/examples/playground/app/recovery/[recoveryId]/session.ts

@@ -0,0 +1,7 @@
+'use client'
+import { createReact } from 'experimental-a2/react'
+import { recoveryReducer } from '../model'
+
+export const { SessionProvider, useSession } = createReact({
+  reducer: recoveryReducer,
+})

package/examples/playground/app/recovery/events/route.ts

@@ -0,0 +1,3 @@
+import { recoveryServer } from '../server'
+
+export const GET = recoveryServer.fetch

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

@@ -0,0 +1,55 @@
+import * as a2 from 'experimental-a2'
+import { z } from 'zod'
+
+export const recovery = a2.contract({
+  name: 'recovery',
+  events: {
+    'pipeline.started': z.object({
+      stepCount: z.literal(4),
+      stepDurationSeconds: z.literal(8),
+    }),
+    'step.completed': z.object({
+      step: z.number().int().min(1).max(4),
+      durationSeconds: z.literal(8),
+    }),
+    'pipeline.completed': z.object({ stepCount: z.literal(4) }),
+  },
+})
+
+const recoveryState = z.object({
+  phase: z.enum(['idle', 'running', 'completed']),
+  stepCount: z.number().int().positive().nullable(),
+  stepDurationSeconds: z.number().int().positive().nullable(),
+  completedSteps: z.number().int().nonnegative(),
+})
+
+export type RecoveryState = z.output<typeof recoveryState>
+
+export const recoveryReducer = recovery
+  .reducer({
+    name: 'recovery',
+    initialState: {
+      phase: 'idle',
+      stepCount: null,
+      stepDurationSeconds: null,
+      completedSteps: 0,
+    },
+    stateSchema: recoveryState,
+  })
+  .fold((state, event) => {
+    switch (event.type) {
+      case 'pipeline.started':
+        return {
+          ...state,
+          phase: 'running',
+          stepCount: event.payload.stepCount,
+          stepDurationSeconds: event.payload.stepDurationSeconds,
+        }
+      case 'step.completed':
+        return { ...state, completedSteps: event.payload.step }
+      case 'pipeline.completed':
+        return { ...state, phase: 'completed' }
+      default:
+        return state
+    }
+  })

package/examples/playground/app/recovery/new-recovery-session.tsx

@@ -0,0 +1,20 @@
+'use client'
+import type { ReactNode } from 'react'
+import { useRouter } from 'next/navigation'
+
+const newSessionId = (): string =>
+  `recovery-${Math.random().toString(36).slice(2, 8)}`
+
+export function NewRecoverySession(): ReactNode {
+  const router = useRouter()
+
+  return (
+    <button
+      onClick={() =>
+        router.push(`/recovery/${encodeURIComponent(newSessionId())}`)
+      }
+    >
+      Start a recovery run
+    </button>
+  )
+}

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

@@ -0,0 +1,22 @@
+import type { ReactNode } from 'react'
+import { NewRecoverySession } from './new-recovery-session'
+
+export default function RecoveryPage(): ReactNode {
+  return (
+    <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.
+      </p>
+      <NewRecoverySession />
+      <p className="hint">
+        Each run gets a fresh session. This is enabled only on Vercel, where the
+        platform can supply the deadline and deliver the armed queue message.
+        The event log contains pipeline facts only.
+      </p>
+    </article>
+  )
+}

package/examples/playground/app/recovery/scheduler/route.ts

@@ -0,0 +1,7 @@
+import { recoveryScheduler, recoveryServer } from '../server'
+
+export const maxDuration = 20
+
+export const POST =
+  recoveryScheduler?.handler(recoveryServer) ??
+  (() => new Response('recovery scheduler is not configured', { status: 503 }))

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

@@ -0,0 +1,53 @@
+import 'server-only'
+import { vercelQueues } from 'experimental-a2/scheduler-vercel'
+import { createServer } from 'experimental-a2/server'
+import { store } from '@/lib/store'
+import { recovery } from './model'
+
+const stepCount = 4 as const
+const stepDurationSeconds = 8 as const
+
+const wait = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms))
+
+export const recoveryScheduler =
+  process.env.VERCEL || process.env.A2_QUEUES
+    ? vercelQueues({ topic: 'a2-recovery' })
+    : undefined
+
+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,
+          },
+        }
+      },
+    },
+  },
+})

package/examples/playground/app/recovery/start/route.ts

@@ -0,0 +1,41 @@
+import { A2Error } from 'experimental-a2'
+import { recoveryServer } from '../server'
+
+const errorResponse = (error: unknown): Response => {
+  if (error instanceof A2Error) {
+    return Response.json(
+      { error: { code: error.code, message: error.message } },
+      { status: error.code === 'STORE_UNAVAILABLE' ? 503 : 400 },
+    )
+  }
+  return Response.json(
+    { error: { message: 'internal error' } },
+    { status: 500 },
+  )
+}
+
+export const maxDuration = 20
+
+export async function POST(request: Request): Promise<Response> {
+  try {
+    const body: unknown = await request.json()
+    const sessionId =
+      typeof body === 'object' && body !== null && 'sessionId' in body
+        ? Reflect.get(body, 'sessionId')
+        : undefined
+    if (typeof sessionId !== 'string' || sessionId.length === 0) {
+      throw new A2Error(
+        'INVALID_PAYLOAD',
+        'sessionId must be a non-empty string',
+      )
+    }
+    const result = await recoveryServer.session(sessionId).append({
+      id: `${sessionId}:pipeline`,
+      type: 'pipeline.started',
+      payload: { stepCount: 4, stepDurationSeconds: 8 },
+    })
+    return Response.json(result)
+  } catch (error) {
+    return errorResponse(error)
+  }
+}

package/examples/playground/css.d.ts

@@ -0,0 +1,4 @@
+// Next's shipped types only declare '*.module.css'; plain global
+// stylesheets need this for `tsc --noEmit` to accept the side-effect
+// import in app/layout.tsx.
+declare module '*.css'

package/examples/playground/lib/store.ts

@@ -0,0 +1,15 @@
+import 'server-only'
+import { postgres, type PostgresStore } from 'experimental-a2/store-postgres'
+import { redis, type RedisStore } from 'experimental-a2/store-redis'
+
+const redisUrl = process.env.REDIS_URL
+const postgresUrl = process.env.DATABASE_URL?.replace(
+  /sslmode=(require|prefer|verify-ca)/,
+  'sslmode=verify-full',
+)
+
+export const store: RedisStore | PostgresStore | undefined = redisUrl
+  ? redis({ url: redisUrl })
+  : postgresUrl
+    ? postgres({ connectionString: postgresUrl })
+    : undefined

package/examples/playground/next-env.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/examples/playground/next.config.ts

@@ -0,0 +1,10 @@
+// No workarounds needed: experimental-a2/server is a separate server-only entry
+// point, so client bundles never reach a store backend; the sqlite dev
+// default carries its own turbopackIgnore annotation in a2's dist, so
+// output tracing stays scoped without externalizing anything; and
+// Next 16 transpiles this file with the TS7 (tsgo) compiler.
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {}
+
+export default nextConfig

package/examples/playground/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "a2-playground",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Complete Next.js examples for experimental-a2.",
+  "type": "module",
+  "packageManager": "pnpm@11.20.0",
+  "engines": {
+    "node": ">=22.18"
+  },
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@codemirror/state": "^6.7.1",
+    "@codemirror/view": "^6.43.8",
+    "@vercel/functions": "^3.9.3",
+    "@vercel/queue": "^0.2.0",
+    "@vercel/sandbox": "^3.0.0",
+    "ai": "^7.0.58",
+    "codemirror": "^6.0.2",
+    "experimental-a2": "0.8.1",
+    "ioredis": "^5.9.0",
+    "next": "^16.3.0",
+    "pg": "^8.16.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "server-only": "^0.0.1",
+    "ws": "^8.21.3",
+    "y-codemirror.next": "^0.3.5",
+    "y-protocols": "^1.0.7",
+    "yjs": "^13.6.32",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@types/ws": "^8.18.1",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  }
+}

package/examples/playground/tsconfig.json

@@ -0,0 +1,37 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noFallthroughCasesInSwitch": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowJs": true,
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": ["node_modules"]
+}

package/examples/playground/vercel.json

@@ -0,0 +1,40 @@
+{
+  "functions": {
+    "app/orders/scheduler/route.ts": {
+      "experimentalTriggers": [
+        {
+          "type": "queue/v2beta",
+          "topic": "a2-orders",
+          "retryAfterSeconds": 30
+        }
+      ]
+    },
+    "app/chat/scheduler/route.ts": {
+      "experimentalTriggers": [
+        {
+          "type": "queue/v2beta",
+          "topic": "a2-chat",
+          "retryAfterSeconds": 30
+        }
+      ]
+    },
+    "app/agent/scheduler/route.ts": {
+      "experimentalTriggers": [
+        {
+          "type": "queue/v2beta",
+          "topic": "a2-agent",
+          "retryAfterSeconds": 30
+        }
+      ]
+    },
+    "app/recovery/scheduler/route.ts": {
+      "experimentalTriggers": [
+        {
+          "type": "queue/v2beta",
+          "topic": "a2-recovery",
+          "retryAfterSeconds": 30
+        }
+      ]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-a2",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Durable sync and reactions for things with a lifecycle: one event log, derived state, and live client per session.",
   "license": "MIT",
   "type": "module",
@@ -20,8 +20,11 @@
   "files": [
     "dist",
     "docs",
+    "examples",
     "src",
-    "CHANGELOG.md"
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "README.md"
   ],
   "exports": {
     ".": "./dist/index.js",