experimental-a2 0.8.0 → 0.9.0

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/app/vault/[vaultId]/route.ts

@@ -0,0 +1,19 @@
+/**
+ * The vault's ingress — the actor mirror of `server.fetch`: your route
+ * authenticates and picks the instance, `handle.fetch` serves the rest
+ * (GET → the state-plane SSE, POST → the call lane).
+ */
+import { vault } from '../server'
+
+async function respond(
+  request: Request,
+  context: { params: Promise<{ vaultId: string }> },
+): Promise<Response> {
+  const { vaultId } = await context.params
+  // here's where you'd authenticate; per-operation policy goes in
+  // fetch's { authorize } option
+  return vault.actor(vaultId).fetch(request)
+}
+
+export const GET = respond
+export const POST = respond

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

@@ -0,0 +1,12 @@
+import type { ReactNode } from 'react'
+import { vault } from './server'
+import { VaultClient } from './vault-client'
+
+export const dynamic = 'force-dynamic'
+
+const VAULT_ID = 'shared'
+
+export default async function VaultPage(): Promise<ReactNode> {
+  const initial = await vault.actor(VAULT_ID).state()
+  return <VaultClient vaultId={VAULT_ID} initial={initial} />
+}

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

@@ -0,0 +1,9 @@
+import 'server-only'
+import { store } from '@/lib/store'
+import { createVault } from './vault'
+
+export type { VaultState } from './vault'
+
+export const vault: ReturnType<typeof createVault> = createVault(
+  store ? { store } : {},
+)

package/examples/playground/app/vault/vault-client.tsx

@@ -0,0 +1,124 @@
+'use client'
+import type { ReactNode } from 'react'
+import { useEffect, useState } from 'react'
+import { ActorRefusedError } from 'experimental-a2/actor/client'
+import { useActor } from 'experimental-a2/actor/react'
+import type { ActorSnapshot } from 'experimental-a2/actor/react'
+import type { vault, VaultState } from '@/app/vault/server'
+import { ActivityFeed } from '@/app/components/activity-feed'
+import { ConnectionPill } from '@/app/components/connection-pill'
+
+const ACTIVITY_LIMIT = 50
+
+export function VaultClient({
+  vaultId,
+  initial,
+}: {
+  vaultId: string
+  initial: ActorSnapshot<VaultState>
+}): ReactNode {
+  const [participant] = useState(
+    () => `guest-${Math.random().toString(36).slice(2, 8)}`,
+  )
+  const { state, call, events, index, connection, presence, setPresence } =
+    useActor<typeof vault>({
+      api: `/vault/${vaultId}`,
+      id: vaultId,
+      initial,
+      participant,
+    })
+  const [answer, setAnswer] = useState<string | null>(null)
+
+  useEffect(() => {
+    setPresence({ viewing: true })
+  }, [setPresence])
+  const here = Object.keys(presence).length
+
+  const run = async (invoke: () => Promise<unknown>): Promise<void> => {
+    try {
+      await invoke()
+      setAnswer(null)
+    } catch (err) {
+      setAnswer(
+        err instanceof ActorRefusedError
+          ? err.message
+          : err instanceof Error
+            ? err.message
+            : String(err),
+      )
+    }
+  }
+
+  // deployed state may predate the `pending` field
+  const pending = Object.entries(state.pending ?? {})
+  const visibleEvents = events.slice(-ACTIVITY_LIMIT)
+
+  return (
+    <article>
+      <header className="session-header">
+        <h1>Vault</h1>
+        <ConnectionPill connection={connection} />
+        <span className="badge live">shared</span>
+        {here > 1 ? <span className="badge">{here} viewing</span> : null}
+      </header>
+      <p className="lede">
+        One durable actor per vault id — serial brain, concurrent muscle. A
+        withdrawal is a saga: the action <em>reserves</em> instantly (balance
+        drops, a pending transfer appears), a <em>task</em> runs the slow
+        2-second transfer off the lane, and its result comes back as a message
+        that <em>settles</em> or <em>refunds</em>. The lane is never blocked:
+        keep depositing while transfers are in flight.
+      </p>
+
+      <section className="counter-panel" aria-label="Vault controls">
+        <output className="counter-value" aria-live="polite">
+          ${state.balance}
+        </output>
+        <div className="counter-actions">
+          <button
+            type="button"
+            onClick={() => void run(() => call.deposit({ amount: 25 }))}
+          >
+            Deposit $25
+          </button>
+          <button
+            type="button"
+            className="secondary"
+            onClick={() => void run(() => call.withdraw({ amount: 60 }))}
+          >
+            Withdraw $60
+          </button>
+          <button
+            type="button"
+            className="secondary"
+            onClick={() => void run(() => call.withdraw({ amount: 19 }))}
+          >
+            Withdraw $19 (bounces)
+          </button>
+        </div>
+        <p className="hint" aria-live="polite">
+          {pending.length > 0
+            ? `${pending.length} transfer${pending.length === 1 ? '' : 's'} in flight: ${pending
+                .map(([, amount]) => `$${amount}`)
+                .join(', ')}`
+            : `${state.deposits} deposits, ${state.withdrawals} settled withdrawals`}
+        </p>
+      </section>
+
+      {answer ? <p className="error">refused: {answer}</p> : null}
+      <p className="hint">
+        Watch the state plane below narrate the saga: <code>withdraw</code> (the
+        reserve commits with the transfer trigger, atomically), then two seconds
+        later <code>settle</code> — or <code>refund</code> for amounts ending in
+        9, the demo bank&apos;s bounce policy. Withdrawing more than the balance
+        is refused instantly by the guard; the reserve means in-flight transfers
+        can never oversell the balance, from any number of tabs.
+      </p>
+
+      <ActivityFeed events={visibleEvents} index={index} />
+      {events.length > ACTIVITY_LIMIT ? (
+        <p className="hint">Showing the latest {ACTIVITY_LIMIT} events.</p>
+      ) : null}
+    </article>
+  )
+}

package/examples/playground/app/vault/vault.test.ts

@@ -0,0 +1,147 @@
+/**
+ * The vault saga, tested against a real (memory) store — the whole
+ * durable pipeline runs: appends, lanes, claims, atomic commits,
+ * concurrent tasks. Nothing is mocked; the store and the fake bank's
+ * latency are injected through the factory, and every test gets an
+ * isolated vault.
+ */
+import { describe, expect, it } from 'vitest'
+import { ActorRefusedError } from 'experimental-a2/actor/client'
+import { memory } from 'experimental-a2/store-memory'
+import { createVault } from './vault'
+
+const makeVault = (transferMs = 25) =>
+  createVault({ store: memory(), transferMs })
+
+describe('vault saga', () => {
+  it('reserve → transfer → settle: the happy path', async () => {
+    const vault = makeVault().actor('acct')
+    await vault.call.deposit({ amount: 100 })
+
+    // the withdraw answers at reserve time: balance already down,
+    // the transfer visible as pending
+    const reserved = await vault.call.withdraw({ amount: 60 })
+    expect(reserved.state.balance).toBe(40)
+    expect(Object.values(reserved.state.pending)).toEqual([60])
+    expect(reserved.state.withdrawals).toBe(0)
+
+    // the settle arrives as a message once the transfer completes
+    await expect
+      .poll(async () => (await vault.state()).state, { timeout: 5_000 })
+      .toEqual({ balance: 40, deposits: 1, withdrawals: 1, pending: {} })
+  })
+
+  it('reserve → transfer bounces → refund: the compensation path', async () => {
+    const vault = makeVault().actor('acct')
+    await vault.call.deposit({ amount: 100 })
+
+    const reserved = await vault.call.withdraw({ amount: 19 }) // ends in 9: bounces
+    expect(reserved.state.balance).toBe(81)
+
+    await expect
+      .poll(async () => (await vault.state()).state, { timeout: 5_000 })
+      .toEqual({ balance: 100, deposits: 1, withdrawals: 0, pending: {} })
+  })
+
+  it('the reserve prevents overselling while a transfer is in flight', async () => {
+    // a slow bank, so the second withdraw races the in-flight transfer
+    const vault = makeVault(500).actor('acct')
+    await vault.call.deposit({ amount: 100 })
+
+    await vault.call.withdraw({ amount: 60 })
+    // the transfer has not settled — but the money is already reserved
+    await expect(vault.call.withdraw({ amount: 60 })).rejects.toThrow(
+      'insufficient funds: the balance is 40',
+    )
+  })
+
+  it('the lane stays free while transfers are in flight', async () => {
+    const vault = makeVault(500).actor('acct')
+    await vault.call.deposit({ amount: 100 })
+    await vault.call.withdraw({ amount: 60 })
+
+    // the deposit answers immediately, while pending proves the
+    // transfer is still running — the task holds no lane
+    const during = await vault.call.deposit({ amount: 5 })
+    expect(during.state.balance).toBe(45)
+    expect(Object.keys(during.state.pending)).toHaveLength(1)
+  })
+
+  it('interleavings reorder but never corrupt: the mixed scenario', async () => {
+    const vault = makeVault().actor('acct')
+    await vault.call.deposit({ amount: 100 })
+    await vault.call.withdraw({ amount: 19 }) // will bounce → refund
+    await vault.call.deposit({ amount: 25 })
+    await vault.call.withdraw({ amount: 60 }) // will settle
+
+    // whatever order the two transfers resolve in, the final state is
+    // the same — every decision ran serialized against fresh state
+    await expect
+      .poll(async () => (await vault.state()).state, { timeout: 5_000 })
+      .toEqual({
+        balance: 65, // 100 − 19 + 25 − 60 + 19 (refund)
+        deposits: 2,
+        withdrawals: 1,
+        pending: {},
+      })
+  })
+
+  it('finalizers are idempotent: a manual refund wins, the late settle no-ops', async () => {
+    const vault = makeVault(300).actor('acct')
+    await vault.call.deposit({ amount: 100 })
+
+    const reserved = await vault.call.withdraw({ amount: 60 })
+    const ref = Object.keys(reserved.state.pending)[0]!
+
+    // support intervenes before the bank answers
+    const refunded = await vault.call.refund({ ref })
+    expect(refunded.state.balance).toBe(100)
+    expect(refunded.state.pending).toEqual({})
+
+    // the transfer later settles into a void: pending[ref] is gone, so
+    // the settle no-ops — no double-credit, no phantom withdrawal
+    await new Promise((resolve) => setTimeout(resolve, 600))
+    const { state } = await vault.state()
+    expect(state).toEqual({
+      balance: 100,
+      deposits: 1,
+      withdrawals: 0,
+      pending: {},
+    })
+  })
+
+  it('state predating the pending field is defaulted in code (deploy drift)', async () => {
+    const vault = makeVault().actor('legacy')
+    // seed a commit written by an older deployment: no `pending` field
+    await vault.session.append({
+      type: 'a2.actor.state',
+      payload: {
+        state: { balance: 100, deposits: 1, withdrawals: 0 },
+        event: 'legacy',
+        message: 'legacy-1',
+      },
+    })
+    // new code reads the old shape and defaults the new field
+    const reserved = await vault.call.withdraw({ amount: 60 })
+    expect(reserved.state.balance).toBe(40)
+    expect(Object.keys(reserved.state.pending)).toHaveLength(1)
+    await expect
+      .poll(async () => (await vault.state()).state.pending, {
+        timeout: 5_000,
+      })
+      .toEqual({})
+  })
+
+  it('guards refuse garbage with an answer, not a retry', async () => {
+    const vault = makeVault().actor('acct')
+    await expect(vault.call.withdraw({ amount: -5 })).rejects.toThrowError(
+      ActorRefusedError,
+    )
+    await expect(vault.call.withdraw({ amount: -5 })).rejects.toThrow(
+      'amount must be between 1 and 1,000,000',
+    )
+    // the refusals are history, not corruption
+    const { state } = await vault.state()
+    expect(state.balance).toBe(0)
+  })
+})