experimental-a2 0.8.1 → 0.10.0

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

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.10.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.10.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 }
+}