experimental-a2 0.16.1 → 0.18.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "experimental-a2",
-  "version": "0.16.1",
-  "description": "Durable sync and reactions for things with a lifecycle: one event log, derived state, and live client per session.",
+  "version": "0.18.0",
+  "description": "Syncs your immutable event log, from server to browser: one contract, handlers, derived state, and a live client per session.",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -39,6 +39,16 @@
       "browser": "./dist/ai-server.browser.js",
       "default": "./dist/ai-server.js"
     },
+    "./ai/fx": {
+      "browser": "./dist/ai-fx.browser.js",
+      "default": "./dist/ai-fx.js"
+    },
+    "./ai/pi": {
+      "browser": "./dist/ai-pi.browser.js",
+      "default": "./dist/ai-pi.js"
+    },
+    "./ai/client": "./dist/ai-client.js",
+    "./ai/react": "./dist/ai-react.js",
     "./actor": {
       "browser": "./dist/actor.browser.js",
       "default": "./dist/actor.js"
@@ -59,9 +69,12 @@
   "peerDependencies": {
     "@opentelemetry/api": "^1.9.0",
     "@upstash/qstash": "^2.11.0",
+    "@earendil-works/pi-ai": "^1.0.2",
+    "@earendil-works/pi-coding-agent": "^1.0.2",
     "@vercel/queue": "*",
     "ai": "^7.0.0",
     "ioredis": "^5.4.0",
+    "libfx": "^0.0.12",
     "pg": "^8.11.0",
     "react": "^19.0.0"
   },
@@ -78,9 +91,18 @@
     "ai": {
       "optional": true
     },
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
     "ioredis": {
       "optional": true
     },
+    "libfx": {
+      "optional": true
+    },
     "pg": {
       "optional": true
     },
@@ -113,7 +135,11 @@
     "tsdown": "^0.22.14",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10",
-    "zod": "^4.4.3"
+    "zod": "^4.4.3",
+    "libfx": "0.0.12",
+    "@earendil-works/pi-ai": "1.0.3",
+    "@earendil-works/pi-coding-agent": "1.0.2",
+    "@vercel/sandbox": "^3.0.0"
   },
   "scripts": {
     "build": "tsdown",

package/src/actor-client.ts

@@ -6,7 +6,8 @@
  * `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
+ * `ActorRefusedError`), a 410 for a call cleared before its answer
+ * (an `ActorRequestError` whose `cause` is the `A2Error`), 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.
  *
@@ -19,6 +20,7 @@
 
 import { ActorRefusedError } from './actor-shared.ts'
 import type { ActorCallOptions, ActorCallResult } from './actor.ts'
+import { A2Error } from './errors.ts'
 
 export { ActorRefusedError }
 
@@ -58,7 +60,7 @@ export type ActorClientCall<
   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 }>
+    ? (...args: P) => Promise<ActorCallResult<View>>
     : never
 }
 
@@ -111,7 +113,12 @@ const callOverWire = async (
       typeof body['error'] === 'string'
         ? body['error']
         : `actor call failed (${response.status})`
-    throw new ActorRequestError(message, { status: response.status })
+    throw new ActorRequestError(message, {
+      status: response.status,
+      ...(response.status === 410 && body['code'] === 'SESSION_CLEARED'
+        ? { cause: new A2Error('SESSION_CLEARED', message) }
+        : {}),
+    })
   }
   return snapshotBody(body, response.status)
 }
@@ -150,10 +157,15 @@ const snapshotBody = (
   body: Record<string, unknown>,
   status: number,
 ): ActorCallResult<unknown> => {
+  const clearIndex = body['clearIndex']
   if (
     !('state' in body) ||
     !Number.isSafeInteger(body['index']) ||
-    (body['index'] as number) < 0
+    (body['index'] as number) < 0 ||
+    (clearIndex !== undefined &&
+      (!Number.isSafeInteger(clearIndex) ||
+        (clearIndex as number) < 1 ||
+        (clearIndex as number) > (body['index'] as number)))
   ) {
     throw new ActorRequestError('actor request returned an invalid snapshot', {
       status,

package/src/actor-react.ts

@@ -37,14 +37,22 @@ import {
   type AnyActorDefinition,
 } from './actor-client.ts'
 import { createClient } from './client.ts'
+import { foldsClearMarkers } from './reducer.ts'
+import { isSessionCleared } from './session-clear.ts'
 import type { A2Client, Connection } from './client.ts'
 import type { ContractEvent, EventDefs, PresenceDefs } from './contract.ts'
+import { internalContract as contract } from './contract.ts'
 import type { Reducer } from './reducer.ts'
 import { useSession } from './react.ts'
 import { useMemo } from 'react'
 
 /** The server-to-client handoff: `await def.actor(id).state()`. */
-export type ActorSnapshot<S> = { state: S; index: number }
+export type ActorSnapshot<S> = {
+  state: S
+  index: number
+  /** The latest clear marker, once the actor has been cleared. */
+  clearIndex?: number
+}
 
 export type UseActorOptions<View> = {
   /** The route whose handler delegates to `handle.fetch` for this instance. */
@@ -104,14 +112,23 @@ const followerReducer: Reducer<EventDefs, unknown, PresenceDefs> = {
   // 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
+  // A clear marker from the actor route carries the actor's initial state.
+  fold: foldsClearMarkers((state: unknown, event: ContractEvent<EventDefs>) =>
+    event.type === ACTOR_STATE_EVENT || isSessionCleared(event)
+      ? (event.payload as { state?: unknown } | null)?.state
       : state,
+  ),
   initialState: undefined,
   stateSchema: undefined,
 }
 
+const followerContract = contract({
+  name: 'a2.actor.follower',
+  events: followerReducer.events,
+  presence: followerReducer.presence,
+  reducer: followerReducer,
+})
+
 const clients = new Map<string, A2Client<EventDefs, unknown, PresenceDefs>>()
 
 /** Use one actor instance: live state plus typed calls. No provider. */
@@ -121,11 +138,11 @@ export function useActor<D extends AnyActorDefinition, View = ActorStateOf<D>>(
   const { api } = options
   let client = clients.get(api)
   if (!client) {
-    client = createClient({ reducer: followerReducer, api })
+    client = createClient({ contract: followerContract, api })
     clients.set(api, client)
   }
   const session = useSession(client, options.id, {
-    hydrate: options.initial,
+    initial: options.initial,
     ...(options.participant === undefined
       ? {}
       : { participant: options.participant }),
@@ -134,11 +151,8 @@ export function useActor<D extends AnyActorDefinition, View = ActorStateOf<D>>(
     () =>
       createActorClient<D, View>({
         api,
-        onSnapshot: ({ state, index }) => {
-          client.session(options.id, {
-            initialState: state,
-            initialIndex: index,
-          })
+        onSnapshot: ({ state, index, clearIndex }) => {
+          client.session(options.id, { initial: { state, index, clearIndex } })
         },
       }),
     [api, client, options.id],

package/src/actor-shared.ts

@@ -1,3 +1,4 @@
+import { reducer } from './reducer.ts'
 /**
  * Internal shared vocabulary of the actor module — the reserved event
  * envelopes, the protocol and context types, the state fold. Not an
@@ -10,7 +11,7 @@
  * events committed atomically with each handler's completion.
  */
 
-import { contract as createContract } from './contract.ts'
+import { internalContract as createContract } from './contract.ts'
 import type { Reducer } from './reducer.ts'
 import type { ScheduleTiming } from './server.ts'
 import type { StandardSchemaV1 } from './standard-schema.ts'
@@ -169,6 +170,8 @@ export type ActorStatePayload<S> = {
   event: string
   /** The message (invocation event) id this state answers. */
   message: string
+  /** The session's latest clear marker when this state was read. */
+  clearIndex?: number
 }
 
 export type ActorFailedPayload = {
@@ -293,11 +296,21 @@ export function actorStateSchema<S>(): StandardSchemaV1<ActorStatePayload<S>> {
     if (!isJsonTree(state)) {
       return issue('the actor state must be a plain JSON tree')
     }
+    const clearIndex = value['clearIndex']
+    if (
+      clearIndex !== undefined &&
+      (!Number.isSafeInteger(clearIndex) || (clearIndex as number) < 1)
+    ) {
+      return issue('the actor clearIndex must be a positive safe integer')
+    }
     return {
       value: {
         state: state as S,
         event: value['event'],
         message: value['message'],
+        ...(clearIndex === undefined
+          ? {}
+          : { clearIndex: clearIndex as number }),
       },
     }
   })
@@ -348,9 +361,11 @@ export function actorReducer<S>(
   const events: ActorClientEventDefs<S> = {
     [ACTOR_STATE_EVENT]: actorStateSchema(),
   }
-  return createContract({ name: options.name, events })
-    .reducer({ name: ACTOR_REDUCER_NAME, initialState: options.state })
-    .fold((state, event) =>
-      event.type === ACTOR_STATE_EVENT ? event.payload.state : state,
-    )
+  return reducer({
+    contract: createContract({ name: options.name, events }),
+    name: ACTOR_REDUCER_NAME,
+    initialState: options.state,
+  }).fold((state, event) =>
+    event.type === ACTOR_STATE_EVENT ? event.payload.state : state,
+  )
 }

package/src/actor.ts

@@ -71,14 +71,17 @@ import type {
 } from './actor-shared.ts'
 import { parsePresenceSibling } from './push-envelope.ts'
 import type { ParsedPushPresence } from './push-envelope.ts'
-import { contract as createContract } from './contract.ts'
+import { internalContract as createContract } from './contract.ts'
 import type { PresencePatch, PresenceSnapshot } from './contract.ts'
 import type { Contract, EventDefs } from './contract.ts'
 import type { Reducer } from './reducer.ts'
 import { A2Error, NonRetriableError } from './errors.ts'
+import { serverInternals } from './internal.ts'
 import { createServer } from './server.ts'
 import { setServerFetchHooks } from './server-fetch.ts'
 import { sseResponse } from './sse.ts'
+import { isSessionCleared, sessionClearedError } from './session-clear.ts'
+import type { SessionCleared } from './session-clear.ts'
 import type { A2Scheduler, A2Server, HandlerEntry, Session } from './server.ts'
 import type { A2Store } from './store.ts'
 import type { StandardSchemaV1 } from './standard-schema.ts'
@@ -224,6 +227,11 @@ export type ActorCallResult<S> = {
   state: S
   /** Log index of the state commit that answered this message. */
   index: number
+  /**
+   * The clear marker this state's lifetime began at, once the actor has been
+   * cleared. For a call answer it is the lifetime the handler read.
+   */
+  clearIndex?: number
 }
 
 type CallMethod<
@@ -257,8 +265,10 @@ export type ActorHandle<D extends ActorProtocol> = {
   readonly id: string
   /**
    * Send the event and await its answer: the state after the handler
-   * ran, or a rejection with `ActorRefusedError`. Serial events only —
-   * concurrent handlers produce no answer to await; `send` them.
+   * ran, or a rejection with `ActorRefusedError`. A clear before the call
+   * receives its answer rejects with `A2Error('SESSION_CLEARED')`. Serial
+   * events only — concurrent handlers produce no answer to await; `send`
+   * them.
    */
   readonly call: { readonly [K in keyof D['events']]: CallMethod<D, K> }
   /** Cast: validate, append the event durably, return without waiting. */
@@ -268,9 +278,10 @@ export type ActorHandle<D extends ActorProtocol> = {
   /**
    * The managed door — the actor mirror of `server.fetch`, bound to
    * this instance. GET streams the state plane (`a2.actor.state`
-   * commits only, `?index` resume, heartbeat, deadline rotation);
-   * POST is the call lane `createActorClient` speaks (`{ event,
-   * input, messageId? }` → the answer, 409 for a refusal). Your route
+   * commits and clear resets, `?index` resume, heartbeat, deadline
+   * rotation); POST is the call lane `createActorClient` speaks
+   * (`{ event, input, messageId? }` → the answer, 409 for a refusal,
+   * 410 for a call cleared before its answer). Your route
    * authenticates and picks the instance; `authorize` sees every
    * operation. Custom endpoints are route code around this call.
    */
@@ -294,7 +305,7 @@ export type ActorDefinition<D extends ActorProtocol> = {
   readonly contract: Contract<EventDefs>
   /** The underlying A2 server — `server.fetch` mounts the full session wire. */
   readonly server: A2Server<EventDefs>
-  /** The state fold — same identity as the client's follower fold. */
+  /** The state fold over commits; a clear resets it to the initial state. */
   readonly reducer: Reducer<ActorClientEventDefs<D['state']>, D['state']>
   actor(id: string): ActorHandle<D>
 }
@@ -516,7 +527,7 @@ export function actor<D extends ActorProtocol>(
         // an event-relative read would miss them and lose updates.
         // 'latest' is deterministic here because the lane makes this
         // attempt the only possible writer while it runs.
-        const { state } = await ctx.session.state(serverReducer, {
+        const { state, clearIndex } = await ctx.session.state(serverReducer, {
           through: 'latest',
         })
         const draft = structuredClone(state)
@@ -565,6 +576,7 @@ export function actor<D extends ActorProtocol>(
           state: draft,
           event: eventName,
           message: ctx.event.id,
+          ...(clearIndex === undefined ? {} : { clearIndex }),
         }
         return [...sends, { type: ACTOR_STATE_EVENT, payload }]
       },
@@ -600,6 +612,8 @@ export function actor<D extends ActorProtocol>(
     },
   })
 
+  const internals = serverInternals.get(server)!
+
   const makeHandle = (id: string): ActorHandle<D> => {
     const session = server.session(id)
 
@@ -634,12 +648,26 @@ export function actor<D extends ActorProtocol>(
         // Drain participates in processing (usually answering inline in
         // this invocation); claims arbitrate if another process runs.
         await server.drain(id)
-        const tail = await session.history({ gte: cursor })
+        const tail = await internals.historyWithMarkers(id, cursor)
         for (const event of tail) {
+          // Reads start at the latest marker, so a clear after the message
+          // arrives before any answer from the next lifetime, including one
+          // from a message that reuses this id.
+          if (isSessionCleared(event)) {
+            throw sessionClearedError(
+              `actor '${name}': '${eventName}' (message ${message.id}) was cleared before the call received its answer`,
+            )
+          }
           if (event.type === ACTOR_STATE_EVENT) {
             const payload = event.payload as ActorStatePayload<D['state']>
             if (payload.message === message.id) {
-              return { state: payload.state, index: event.index }
+              return {
+                state: payload.state,
+                index: event.index,
+                ...(payload.clearIndex === undefined
+                  ? {}
+                  : { clearIndex: payload.clearIndex }),
+              }
             }
           }
           if (event.type === ACTOR_FAILED_EVENT) {
@@ -661,10 +689,19 @@ export function actor<D extends ActorProtocol>(
     }
 
     const readState = async (): Promise<ActorCallResult<D['state']>> => {
-      const { state, index } = await session.state(serverReducer)
-      return { state, index }
+      const { state, index, clearIndex } = await session.state(serverReducer)
+      return clearIndex === undefined
+        ? { state, index }
+        : { state, index, clearIndex }
     }
 
+    /** A snapshot or call answer through the route's view. */
+    const projected = (
+      result: ActorCallResult<D['state']>,
+      view: ((state: D['state']) => unknown) | undefined,
+    ): ActorCallResult<unknown> =>
+      view ? { ...result, state: applyView(view, result.state) } : result
+
     const applyView = (
       view: (state: D['state']) => unknown,
       state: D['state'],
@@ -689,6 +726,7 @@ export function actor<D extends ActorProtocol>(
       // advance the resume frontier.
       const source: AsyncIterable<
         | Awaited<ReturnType<typeof session.history>>[number]
+        | SessionCleared
         | PresencePatch
         | PresenceSnapshot
       > = presenceEnabled
@@ -707,6 +745,16 @@ export function actor<D extends ActorProtocol>(
           continue
         }
         const event = item
+        if (isSessionCleared(event)) {
+          // The follower has no seed of its own: the marker carries the
+          // actor's initial state, projected like any commit.
+          const initial = structuredClone(options.state)
+          yield {
+            ...event,
+            payload: { state: view ? applyView(view, initial) : initial },
+          }
+          continue
+        }
         // The state plane only: subscribers see what the actor is,
         // never other callers' inputs. Refusals answer only their
         // caller (the POST 409); the full mailbox stays server-side.
@@ -724,10 +772,11 @@ export function actor<D extends ActorProtocol>(
     }
 
     // The managed door — the actor mirror of `server.fetch`: GET is
-    // the state-plane SSE (`a2.actor.state` commits only, `?index`
-    // resume), POST is the call lane (`{ event, input, messageId? }`
-    // → the answer, 409 for a refusal). Authentication happens in the
-    // surrounding route; per-operation policy in `authorize`.
+    // the state-plane SSE (`a2.actor.state` commits and clear resets,
+    // `?index` resume), POST is the call lane (`{ event, input,
+    // messageId? }` → the answer, 409 for a refusal, 410 for a cleared
+    // call). Authentication happens in the surrounding route;
+    // per-operation policy in `authorize`.
     const handleFetch = async (
       request: Request,
       fetchOptions?: ActorFetchOptions<D>,
@@ -739,15 +788,11 @@ export function actor<D extends ActorProtocol>(
         const url = new URL(request.url)
         if (url.searchParams.has('snapshot')) {
           if (!(await authorized({ type: 'state', id }))) return forbidden()
-          const result = await readState()
           return Response.json(
+            projected(await readState(), fetchOptions?.view),
             {
-              state: fetchOptions?.view
-                ? applyView(fetchOptions.view, result.state)
-                : result.state,
-              index: result.index,
+              headers: { 'cache-control': 'private, no-store' },
             },
-            { headers: { 'cache-control': 'private, no-store' } },
           )
         }
         const raw = Number(url.searchParams.get('index'))
@@ -858,15 +903,9 @@ export function actor<D extends ActorProtocol>(
           input,
           messageId === undefined ? undefined : { id: messageId },
         )
-        return Response.json(
-          fetchOptions?.view
-            ? {
-                state: applyView(fetchOptions.view, result.state),
-                index: result.index,
-              }
-            : result,
-          { headers: { 'cache-control': 'private, no-store' } },
-        )
+        return Response.json(projected(result, fetchOptions?.view), {
+          headers: { 'cache-control': 'private, no-store' },
+        })
       } catch (error) {
         if (error instanceof ActorRefusedError) {
           return Response.json(
@@ -878,6 +917,12 @@ export function actor<D extends ActorProtocol>(
             { status: 409 },
           )
         }
+        if (error instanceof A2Error && error.code === 'SESSION_CLEARED') {
+          return Response.json(
+            { code: error.code, error: error.message },
+            { status: 410 },
+          )
+        }
         if (
           error instanceof A2Error &&
           (error.code === 'INVALID_PAYLOAD' ||