experimental-a2 0.8.1 → 0.9.0

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)
+  })
+})

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/package.json

@@ -22,7 +22,7 @@
     "@vercel/sandbox": "^3.0.0",
     "ai": "^7.0.58",
     "codemirror": "^6.0.2",
-    "experimental-a2": "0.8.1",
+    "experimental-a2": "0.9.0",
     "ioredis": "^5.9.0",
     "next": "^16.3.0",
     "pg": "^8.16.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-a2",
-  "version": "0.8.1",
+  "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",
@@ -39,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,
+  }
+}