experimental-a2 0.8.0 → 0.9.0

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

@@ -0,0 +1,119 @@
+/**
+ * The vault actor — a durable mailbox with memory, and muscle.
+ *
+ * Defined over a protocol: state and events, as types. Handlers are
+ * serial by default (the brain: hold the lane, decide against fresh
+ * state, one atomic commit); `{ concurrent: true }` opts a handler out
+ * of the lane (the muscle: slow I/O in parallel, results sent home as
+ * events). A withdrawal is the classic saga — reserve (serial) →
+ * transfer (concurrent) → settle or refund (serial) — each step one
+ * atomic commit, every crash landing between named states. The reserve
+ * and its transfer trigger commit together: `ctx.send` is buffered
+ * into the same atomic operation as the state change, so the saga can
+ * never half-start.
+ *
+ * A factory, deliberately: the store and the transfer latency are
+ * injected, so tests build isolated vaults on a memory store with a
+ * fast clock (vault.test.ts) while server.ts builds the real one.
+ */
+import { NonRetriableError } from 'experimental-a2'
+import { actor, concurrent } from 'experimental-a2/actor'
+import type { A2Store } from 'experimental-a2/server'
+
+interface Vault {
+  state: {
+    balance: number
+    deposits: number
+    withdrawals: number
+    /** In-flight transfers: ref → reserved amount. */
+    pending: Record<string, number>
+  }
+  events: {
+    deposit: { amount: number }
+    withdraw: { amount: number }
+    settle: { ref: string }
+    refund: { ref: string }
+    transfer: { ref: string; amount: number }
+  }
+  /** Ephemeral audience state — never in the log, invisible to handlers. */
+  presence: { viewing: boolean }
+}
+
+/** For client props — type-only imports of this module are erased. */
+export type VaultState = Vault['state']
+
+// Types are compile-time claims — the route is public, so wire input
+// gets a first-line runtime guard (bring zod and `.parse` if you
+// prefer schemas; it's userland either way).
+function guardAmount(input: { amount: number }): number {
+  const amount = input?.amount
+  if (typeof amount !== 'number' || !Number.isInteger(amount)) {
+    throw new NonRetriableError('amount must be an integer')
+  }
+  if (amount <= 0 || amount > 1_000_000) {
+    throw new NonRetriableError('amount must be between 1 and 1,000,000')
+  }
+  return amount
+}
+
+export function createVault(options?: {
+  store?: A2Store
+  /** The fake bank's latency — tests inject a fast one. */
+  transferMs?: number
+}) {
+  const transferMs = options?.transferMs ?? 2_000
+  const store = options?.store
+  return actor<Vault>({
+    name: 'vault',
+    state: { balance: 0, deposits: 0, withdrawals: 0, pending: {} },
+    presence: true,
+
+    handlers: {
+      deposit: (ctx, input) => {
+        const amount = guardAmount(input)
+        ctx.state.balance += amount
+        ctx.state.deposits += 1
+      },
+
+      withdraw: (ctx, input) => {
+        ctx.state.pending ??= {}
+        const amount = guardAmount(input)
+        if (ctx.state.balance < amount) {
+          throw new NonRetriableError(
+            `insufficient funds: the balance is ${ctx.state.balance}`,
+          )
+        }
+        ctx.state.balance -= amount
+        ctx.state.pending[ctx.id] = amount
+        ctx.send.transfer({ ref: ctx.id, amount })
+      },
+
+      settle: (ctx, input) => {
+        ctx.state.pending ??= {}
+        if (ctx.state.pending[input.ref] === undefined) return
+        delete ctx.state.pending[input.ref]
+        ctx.state.withdrawals += 1
+      },
+
+      refund: (ctx, input) => {
+        ctx.state.pending ??= {}
+        const amount = ctx.state.pending[input.ref]
+        if (amount === undefined) return
+        delete ctx.state.pending[input.ref]
+        ctx.state.balance += amount
+      },
+
+      transfer: concurrent(async (ctx, input) => {
+        await new Promise((resolve) => setTimeout(resolve, transferMs))
+        // demo bank policy: amounts ending in 9 bounce → compensation
+        if (input.amount % 10 === 9) {
+          ctx.send.refund({ ref: input.ref })
+          return
+        }
+        ctx.send.settle({ ref: input.ref })
+      }),
+    },
+
+    ...(store ? { store } : {}),
+  })
+}

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.9.0",
+    "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.9.0",
   "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",
@@ -36,6 +39,12 @@
       "browser": "./dist/ai-server.browser.js",
       "default": "./dist/ai-server.js"
     },
+    "./actor": {
+      "browser": "./dist/actor.browser.js",
+      "default": "./dist/actor.js"
+    },
+    "./actor/client": "./dist/actor-client.js",
+    "./actor/react": "./dist/actor-react.js",
     "./store-memory": "./dist/store-memory.js",
     "./store-sqlite": "./dist/store-sqlite.js",
     "./store-postgres": "./dist/store-postgres.js",

package/src/actor-client.ts

@@ -0,0 +1,132 @@
+/**
+ * experimental-a2/actor/client — typed calls to an actor over HTTP.
+ * Framework-agnostic: no React, no framework machinery; works in any
+ * browser code and server-to-server.
+ *
+ * `client.call` mirrors the server handle's `call` record over the
+ * call lane `handle.fetch` serves — POST `{ event, input, messageId? }`
+ * → the answer (post-state), a 409 refusal (revived as
+ * `ActorRefusedError`), or a 400. Both ends of that wire are library
+ * code: the types here are backed by `handle.fetch`, not by a
+ * hand-written convention.
+ *
+ * ```ts
+ * import type { vault } from '@/app/vault/server' // type-only, erased
+ * const client = createActorClient<typeof vault>({ api: `/vault/${id}` })
+ * await client.call.withdraw({ amount: 60 }) // ActorRefusedError on refusal
+ * ```
+ */
+
+import { ActorRefusedError } from './actor-shared.ts'
+import type { ActorCallOptions, ActorCallResult } from './actor.ts'
+
+export { ActorRefusedError }
+
+/** The loose shape of an `actor()` definition — carried type-only. */
+export type AnyActorDefinition = {
+  actor(id: string): {
+    state(): Promise<{ state: unknown; index: number }>
+    call: object
+  }
+}
+
+type HandleOf<D extends AnyActorDefinition> = ReturnType<D['actor']>
+
+export type ActorStateOf<D extends AnyActorDefinition> = Awaited<
+  ReturnType<HandleOf<D>['state']>
+>['state']
+
+/**
+ * The server handle's `call` record mirrored to the client, with
+ * answers carrying `View` — the projected shape when the route mounts
+ * `fetch(req, { view })`, the full state otherwise (the default).
+ */
+export type ActorClientCall<
+  D extends AnyActorDefinition,
+  View = ActorStateOf<D>,
+> = {
+  readonly [K in keyof HandleOf<D>['call']]: HandleOf<D>['call'][K] extends (
+    ...args: infer P
+  ) => Promise<{ state: unknown; index: number }>
+    ? (...args: P) => Promise<{ state: View; index: number }>
+    : never
+}
+
+export type ActorClient<
+  D extends AnyActorDefinition,
+  View = ActorStateOf<D>,
+> = {
+  /** Typed calls over POST — the response is the answer. */
+  readonly call: ActorClientCall<D, View>
+}
+
+export type CreateActorClientOptions = {
+  /** The route whose handler delegates to `handle.fetch` for this instance. */
+  api: string
+  /** Injectable transport (tests, custom auth headers). */
+  fetch?: typeof globalThis.fetch
+}
+
+const CALL_TIMEOUT_MS = 30_000
+
+const callOverWire = async (
+  fetchImpl: typeof globalThis.fetch,
+  api: string,
+  event: string,
+  input: unknown,
+  options?: ActorCallOptions,
+): Promise<ActorCallResult<unknown>> => {
+  const response = await fetchImpl(api, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      event,
+      ...(input === undefined ? {} : { input }),
+      ...(options?.id === undefined ? {} : { messageId: options.id }),
+    }),
+    signal: AbortSignal.timeout(options?.timeoutMs ?? CALL_TIMEOUT_MS),
+  })
+  const body = (await response.json().catch(() => ({}))) as Record<
+    string,
+    unknown
+  >
+  if (response.status === 409 && typeof body['error'] === 'string') {
+    throw new ActorRefusedError(
+      typeof body['event'] === 'string' ? body['event'] : event,
+      typeof body['messageId'] === 'string' ? body['messageId'] : '',
+      body['error'],
+    )
+  }
+  if (!response.ok) {
+    const message =
+      typeof body['error'] === 'string'
+        ? body['error']
+        : `actor call failed (${response.status})`
+    throw new Error(message)
+  }
+  return body as ActorCallResult<unknown>
+}
+
+/**
+ * A typed call surface for one actor instance's route. When the route
+ * mounts a `view`, pass its shape as the second type argument so call
+ * answers carry the projected state:
+ * `createActorClient<typeof vault, PublicVault>({ api })`.
+ */
+export function createActorClient<
+  D extends AnyActorDefinition,
+  View = ActorStateOf<D>,
+>(options: CreateActorClientOptions): ActorClient<D, View> {
+  const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis)
+  const call = new Proxy(
+    {},
+    {
+      get: (_target, event) =>
+        typeof event === 'string'
+          ? (input?: unknown, callOptions?: ActorCallOptions) =>
+              callOverWire(fetchImpl, options.api, event, input, callOptions)
+          : undefined,
+    },
+  ) as ActorClientCall<D, View>
+  return { call }
+}

package/src/actor-react.ts

@@ -0,0 +1,143 @@
+'use client'
+/**
+ * experimental-a2/actor/react — use an actor from React: live state
+ * plus typed calls, one hook. A thin wrapper: the state pump follows
+ * the SSE that `handle.fetch` serves (frontier resume, reconnection,
+ * heartbeat watchdog — both ends library code), and `call` is
+ * `createActorClient`'s typed surface (the framework-agnostic
+ * primitive for everything that isn't React).
+ *
+ * ```tsx
+ * // server component
+ * const initial = await vault.actor(id).state()
+ * // client component — typed by the server module, erased at build
+ * const { state, call, connection } = useActor<typeof vault>({
+ *   api: `/vault/${id}`, // your route: auth, then handle.fetch
+ *   id,
+ *   initial,
+ * })
+ * await call.withdraw({ amount: 60 }) // ActorRefusedError on refusal
+ * ```
+ *
+ * The fold is library code (last write wins over state commits), so no
+ * reducers, schemas, or contracts appear in browser code. Live, not
+ * optimistic: handlers are server code deciding against serialized
+ * fresh state, so a local guess would be wrong exactly when the actor
+ * matters. On a view-projected mount, pass the projected shape as the
+ * second type argument — `useActor<typeof vault, PublicVault>` — and
+ * `initial`, `state`, and call answers all carry it.
+ */
+
+import { ACTOR_STATE_EVENT, openPresenceDefs } from './actor-shared.ts'
+import type { ActorPresenceMap, ActorPresenceValues } from './actor-shared.ts'
+import {
+  createActorClient,
+  type ActorClientCall,
+  type ActorStateOf,
+  type AnyActorDefinition,
+} from './actor-client.ts'
+import { createClient } from './client.ts'
+import type { A2Client, Connection } from './client.ts'
+import type { ContractEvent, EventDefs, PresenceDefs } from './contract.ts'
+import type { Reducer } from './reducer.ts'
+import { useSession } from './react.ts'
+
+/** The server-to-client handoff: `await def.actor(id).state()`. */
+export type ActorSnapshot<S> = { state: S; index: number }
+
+export type UseActorOptions<View> = {
+  /** The route whose handler delegates to `handle.fetch` for this instance. */
+  api: string
+  /** The instance id. */
+  id: string
+  /** The server-rendered fold — the stream resumes after `index`. */
+  initial: ActorSnapshot<View>
+  /** This client's presence identity — required to call `setPresence`. */
+  participant?: string
+}
+
+/** The definition's presence vocabulary, `never` when undeclared. */
+type PresenceOf<D extends AnyActorDefinition> = D extends {
+  protocol?: infer P
+}
+  ? NonNullable<P> extends { presence: infer Values extends object }
+    ? Values
+    : never
+  : never
+
+export type UseActorResult<D extends AnyActorDefinition, View> = {
+  /** The actor's state, live: every commit streams in and replaces it. */
+  state: View
+  /** The stream frontier. */
+  index: number
+  connection: Connection
+  /** Typed calls over POST — the response is the answer. */
+  call: ActorClientCall<D, View>
+  /** The state-commit feed this browser has observed. */
+  events: ContractEvent<EventDefs>[]
+  /**
+   * The replicated presence map: participant → field → latest value.
+   * Peer-authored — render values like user input. Empty (and
+   * `setPresence` untyped-callable-with-nothing) when the protocol
+   * declares no presence.
+   */
+  presence: ActorPresenceMap<PresenceOf<D>>
+  /**
+   * Announce this client's presence fields (throttled, resent on
+   * reconnect; `null` clears a field). Requires `participant`.
+   */
+  setPresence: (values: ActorPresenceValues<PresenceOf<D>>) => void
+}
+
+/**
+ * The follower fold, untyped on purpose: the state type comes from the
+ * caller's `initial` handoff, and the fold never inspects state.
+ * `initialState` is never rendered — `initial` is required, so every
+ * session hydrates before it connects.
+ */
+const followerReducer: Reducer<EventDefs, unknown, PresenceDefs> = {
+  name: 'a2.actor.follower.v1',
+  events: {},
+  // The open vocabulary ('*' catch-all): the browser cannot know a
+  // server-defined field list, so the server stays the authority and
+  // the protocol types honest callers at compile time.
+  presence: openPresenceDefs,
+  fold: (state, event) =>
+    event.type === ACTOR_STATE_EVENT
+      ? (event.payload as { state: unknown }).state
+      : state,
+  initialState: undefined,
+  stateSchema: undefined,
+}
+
+const clients = new Map<string, A2Client<EventDefs, unknown, PresenceDefs>>()
+
+/** Use one actor instance: live state plus typed calls. No provider. */
+export function useActor<D extends AnyActorDefinition, View = ActorStateOf<D>>(
+  options: UseActorOptions<View>,
+): UseActorResult<D, View> {
+  const { api } = options
+  let client = clients.get(api)
+  if (!client) {
+    client = createClient({ reducer: followerReducer, api })
+    clients.set(api, client)
+  }
+  const session = useSession(client, options.id, {
+    hydrate: options.initial,
+    ...(options.participant === undefined
+      ? {}
+      : { participant: options.participant }),
+  })
+  const { call } = createActorClient<D, View>({ api })
+  return {
+    state: session.state as View,
+    index: session.index,
+    connection: session.connection,
+    call,
+    events: session.events,
+    presence: session.presence as ActorPresenceMap<PresenceOf<D>>,
+    setPresence: session.setPresence as (
+      values: ActorPresenceValues<PresenceOf<D>>,
+    ) => void,
+  }
+}