experimental-a2 0.8.0 → 0.9.0

package/src/actor.ts

@@ -0,0 +1,914 @@
+/**
+ * experimental-a2/actor — durable actors over the log. Server-only
+ * (handlers are server code); the browser condition resolves to a
+ * throwing stub, and the browser surfaces are experimental-a2/actor/client
+ * and experimental-a2/actor/react.
+ *
+ * An actor is defined over a protocol — its state shape and event
+ * vocabulary, as types — and one complete `handlers` bag:
+ *
+ * ```ts
+ * interface Counter {
+ *   state: { count: number }
+ *   events: { increment: object; add: { by: number } }
+ * }
+ * const counter = actor<Counter>({
+ *   name: 'counter',
+ *   state: { count: 0 },
+ *   handlers: {
+ *     increment: (ctx) => {
+ *       ctx.state.count++
+ *     },
+ *     add: (ctx, input) => {
+ *       ctx.state.count += input.by
+ *     },
+ *   },
+ * })
+ * ```
+ *
+ * Handlers are serial by default: one at a time per instance (a lane —
+ * the state's write lock), `ctx.state` a mutable draft committed
+ * atomically with completion. A handler holding slow I/O opts out of
+ * the lane with `{ concurrent: true, handle }`: it runs in parallel,
+ * reads state as a snapshot, and mutates by sending events whose
+ * serial handlers decide against fresh state. `ctx.send.eventName(...)`
+ * is typed by the protocol and buffered — committed atomically with
+ * the handler's completion, so a reserve and its trigger can never
+ * half-happen.
+ *
+ * A thrown `NonRetriableError` is an answer (settled, delivered to a
+ * waiting caller); any other error retries like every A2 handler
+ * failure; a crash re-runs against the same pre-state. Everything
+ * compiles to contract + reducer + laned handlers + returned events —
+ * no new store operations, no new wire.
+ */
+
+// oxlint-disable no-await-in-loop -- a call awaits its answer: drain, read
+// the tail, repeat until the message settles. Sequential by nature.
+
+import {
+  ACTOR_FAILED_EVENT,
+  ACTOR_LANE,
+  ACTOR_STATE_EVENT,
+  ActorRefusedError,
+  actorFailedSchema,
+  actorReducer,
+  actorStateSchema,
+  isJsonTree,
+  openPresenceDefs,
+} from './actor-shared.ts'
+import type {
+  ActorClientEventDefs,
+  ActorConcurrentContext,
+  ActorContext,
+  ActorFailedPayload,
+  ActorPresenceOf,
+  ActorProtocol,
+  ActorScheduleOptions,
+  ActorScheduleSend,
+  ActorSend,
+  ActorStatePayload,
+} 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 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 { createServer } from './server.ts'
+import { setServerFetchHooks } from './server-fetch.ts'
+import { sseResponse } from './sse.ts'
+import type { A2Scheduler, A2Server, HandlerEntry, Session } from './server.ts'
+import type { A2Store } from './store.ts'
+import type { StandardSchemaV1 } from './standard-schema.ts'
+import type { A2Telemetry } from './telemetry.ts'
+
+export type {
+  ActorConcurrentContext,
+  ActorContext,
+  ActorPresenceMap,
+  ActorPresenceOf,
+  ActorPresenceValues,
+  ActorProtocol,
+  ActorScheduleOptions,
+  ActorScheduleSend,
+  ActorSend,
+} from './actor-shared.ts'
+export { ActorRefusedError } from './actor-shared.ts'
+
+/**
+ * One event's handler: ordinary server code. Serial by default — read
+ * `ctx.state`, perform I/O, mutate `ctx.state`, one atomic commit at
+ * return. `{ concurrent: true, handle }` opts the handler out of the
+ * lane for slow I/O: state becomes a snapshot read and mutations
+ * happen by sending events. The input is typed by the protocol; the
+ * wire hands handlers parsed JSON, so a wire-exposed event guards its
+ * input in its first line (`schema.parse(input)` if you like schemas —
+ * userland either way).
+ */
+export type ActorHandler<D extends ActorProtocol, K extends keyof D['events']> =
+  | ((ctx: ActorContext<D>, input: D['events'][K]) => void | Promise<void>)
+  | {
+      concurrent: true
+      handle: (
+        ctx: ActorConcurrentContext<D>,
+        input: D['events'][K],
+      ) => void | Promise<void>
+    }
+
+/**
+ * Mark a handler concurrent — off the lane, in parallel with the lane
+ * and with other concurrent handlers, `ctx.state()` a snapshot read.
+ * Sugar for the structural `{ concurrent: true, handle }` form:
+ *
+ * ```ts
+ * handlers: {
+ *   transfer: concurrent(async (ctx, input) => {
+ *     await bank.transfer(input, { idempotencyKey: input.ref })
+ *     ctx.send.settle({ ref: input.ref })
+ *   }),
+ * }
+ * ```
+ */
+export function concurrent<Ctx, I>(
+  handle: (ctx: Ctx, input: I) => void | Promise<void>,
+): { concurrent: true; handle: (ctx: Ctx, input: I) => void | Promise<void> } {
+  return { concurrent: true, handle }
+}
+
+export type ActorOptions<D extends ActorProtocol> = {
+  /** Identity — prefixes storage keys; one contract per actor definition. */
+  name: string
+  /** The initial state — checked against the protocol, a plain JSON tree. */
+  state: D['state']
+  /**
+   * One handler per declared event — completeness and payload shapes
+   * are compile-checked against the protocol.
+   */
+  handlers: { [K in keyof D['events']]: ActorHandler<D, K> }
+  store?: A2Store
+  scheduler?: A2Scheduler
+  telemetry?: A2Telemetry
+} & ([ActorPresenceOf<D>] extends [never]
+  ? { presence?: never }
+  : {
+      /**
+       * The wire bit for the protocol's `presence` vocabulary — types
+       * erase, so the runtime needs one value to arm the presence
+       * lanes (frames on GET, envelopes on POST). Required exactly
+       * when the protocol declares `presence`; the vocabulary itself
+       * is typed there. Values are validated to the JSON floor and
+       * pass through `authorize` as `{ type: 'presence' }` operations;
+       * meaning stays with your renderers — treat values as user
+       * input.
+       */
+      presence: true
+    })
+
+/**
+ * One HTTP operation `handle.fetch` is about to serve — the actor
+ * mirror of core's `A2Operation`. `authorize` sees it before any
+ * write or subscription; returning `false` answers 403.
+ */
+export type ActorOperation =
+  | {
+      readonly type: 'stream'
+      readonly id: string
+      readonly startAfter: number
+    }
+  | {
+      readonly type: 'call'
+      readonly id: string
+      readonly event: string
+      readonly input: unknown
+      readonly messageId?: string
+    }
+  | {
+      readonly type: 'presence'
+      readonly id: string
+      readonly participant: string
+      readonly values: Readonly<Record<string, unknown>>
+    }
+
+export type ActorFetchOptions<D extends ActorProtocol> = {
+  /** Per-operation policy — authentication happened in your route. */
+  authorize?: (operation: ActorOperation) => boolean | Promise<boolean>
+  /**
+   * Request-time projection: what this mount's audience sees. Applied
+   * to every state frame on the stream AND to call answers (the two
+   * untrusted lanes must agree, or the call lane leaks what the
+   * stream hides). The definition stays audience-agnostic — different
+   * routes project the same actor differently, and per-viewer views
+   * are just closures over the route's auth. Output is held to the
+   * JSON-tree floor like everything else. Transport-agnostic: applied
+   * at frame emission, so any wire the door speaks emits projected
+   * frames. Absent, the full state ships (the trusted default).
+   */
+  view?: (state: D['state']) => unknown
+}
+
+export type ActorSendOptions = {
+  /** Explicit message id — makes retries of this send idempotent. */
+  id?: string
+}
+
+export type ActorCallOptions = ActorSendOptions & {
+  /** How long to await the answer before rejecting the wait (default 30s). */
+  timeoutMs?: number
+}
+
+export type ActorCallResult<S> = {
+  /** The actor's state after this message was processed. */
+  state: S
+  /** Log index of the state commit that answered this message. */
+  index: number
+}
+
+type CallMethod<
+  D extends ActorProtocol,
+  K extends keyof D['events'],
+> = {} extends D['events'][K]
+  ? (
+      input?: D['events'][K],
+      options?: ActorCallOptions,
+    ) => Promise<ActorCallResult<D['state']>>
+  : (
+      input: D['events'][K],
+      options?: ActorCallOptions,
+    ) => Promise<ActorCallResult<D['state']>>
+
+type SendMethod<
+  D extends ActorProtocol,
+  K extends keyof D['events'],
+> = {} extends D['events'][K]
+  ? (
+      input?: D['events'][K],
+      options?: ActorSendOptions,
+    ) => Promise<{ id: string; index: number }>
+  : (
+      input: D['events'][K],
+      options?: ActorSendOptions,
+    ) => Promise<{ id: string; index: number }>
+
+/** One instance: typed calls and sends, reads, the managed door, the escape hatch. */
+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.
+   */
+  readonly call: { readonly [K in keyof D['events']]: CallMethod<D, K> }
+  /** Cast: validate, append the event durably, return without waiting. */
+  readonly send: { readonly [K in keyof D['events']]: SendMethod<D, K> }
+  /** Snapshot read — never queues behind pending messages. */
+  readonly state: () => Promise<ActorCallResult<D['state']>>
+  /**
+   * 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
+   * authenticates and picks the instance; `authorize` sees every
+   * operation. Custom endpoints are route code around this call.
+   */
+  readonly fetch: (
+    request: Request,
+    options?: ActorFetchOptions<D>,
+  ) => Promise<Response>
+  /** Escape hatch: the raw A2 session (history, stream, schedule). */
+  readonly session: Session<EventDefs>
+}
+
+export type ActorDefinition<D extends ActorProtocol> = {
+  readonly name: string
+  /**
+   * Type-only carrier of the protocol, so clients deriving from
+   * `typeof def` can see the vocabularies (`experimental-a2/actor/react`
+   * types `presence` from it). Never a runtime value.
+   */
+  readonly protocol?: D
+  /** The assembled contract — declared events plus the reserved a2.actor.* pair. */
+  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. */
+  readonly reducer: Reducer<ActorClientEventDefs<D['state']>, D['state']>
+  actor(id: string): ActorHandle<D>
+}
+
+// Object-mechanics names, not surface names: events live in their own
+// bags, so nothing else is reserved.
+const UNSAFE_EVENT_NAMES = new Set(['__proto__', 'constructor', 'prototype'])
+
+const forbidden = (): Response =>
+  Response.json({ error: 'the operation is not authorized' }, { status: 403 })
+
+const CALL_TIMEOUT_MS = 30_000
+const CALL_POLL_MS = 25
+
+/** Declared events accept any JSON tree; `undefined` normalizes to `{}`. */
+const jsonInputSchema: StandardSchemaV1<unknown> = {
+  '~standard': {
+    version: 1,
+    vendor: 'a2',
+    validate(value) {
+      if (value === undefined || value === null) return { value: {} }
+      if (!isJsonTree(value)) {
+        return {
+          issues: [{ message: 'event input must be a plain JSON tree' }],
+        }
+      }
+      return { value }
+    },
+  },
+}
+
+const describeError = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error)
+
+const sleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms))
+
+type NormalizedHandler<D extends ActorProtocol> =
+  | {
+      kind: 'serial'
+      handle: (ctx: ActorContext<D>, input: unknown) => void | Promise<void>
+    }
+  | {
+      kind: 'concurrent'
+      handle: (
+        ctx: ActorConcurrentContext<D>,
+        input: unknown,
+      ) => void | Promise<void>
+    }
+
+/**
+ * Define and serve an actor over its protocol: a named, durable
+ * instance-per-id with serialized state handlers, concurrent I/O
+ * handlers, and typed self-sends.
+ */
+export function actor<D extends ActorProtocol>(
+  options: ActorOptions<D>,
+): ActorDefinition<D> {
+  const { name } = options
+
+  const handlersByEvent = new Map<string, NormalizedHandler<D>>()
+  const events: Record<string, StandardSchemaV1> = {
+    [ACTOR_STATE_EVENT]: actorStateSchema(),
+    [ACTOR_FAILED_EVENT]: actorFailedSchema,
+  }
+  for (const [eventName, def] of Object.entries(
+    options.handlers as Record<string, ActorHandler<D, keyof D['events']>>,
+  )) {
+    if (UNSAFE_EVENT_NAMES.has(eventName)) {
+      throw new TypeError(
+        `actor '${name}': '${eventName}' collides with object plumbing and cannot name an event`,
+      )
+    }
+    if (eventName.startsWith('a2.')) {
+      throw new TypeError(
+        `actor '${name}': event names starting with 'a2.' are reserved`,
+      )
+    }
+    handlersByEvent.set(
+      eventName,
+      typeof def === 'function'
+        ? {
+            kind: 'serial',
+            handle: def as (
+              ctx: ActorContext<D>,
+              input: unknown,
+            ) => void | Promise<void>,
+          }
+        : {
+            kind: 'concurrent',
+            handle: def.handle as (
+              ctx: ActorConcurrentContext<D>,
+              input: unknown,
+            ) => void | Promise<void>,
+          },
+    )
+    events[eventName] = jsonInputSchema
+  }
+
+  const reducer = actorReducer({ name, state: options.state })
+  // The server's contract carries every event type; the reducer only
+  // folds state commits. Same fold, same identity — the widening is a
+  // typing formality.
+  const serverReducer = reducer as unknown as Reducer<EventDefs, D['state']>
+
+  // The typed durable-timer surface: immediate handoff to the
+  // configured scheduler through the handler session, so timer
+  // identity is scoped to the triggering message and re-runs address
+  // the same timer (core §6). Not buffered — see ActorScheduleSend.
+  const makeSchedule = (
+    schedule: (
+      name: string,
+      timing: { delay?: string; at?: Date },
+      event: { type: string; payload: unknown },
+    ) => Promise<void>,
+  ): ActorScheduleSend<D['events']> => {
+    const surface: Record<string, unknown> = {}
+    for (const eventName of handlersByEvent.keys()) {
+      Object.defineProperty(surface, eventName, {
+        value: (input: unknown, scheduleOptions: ActorScheduleOptions) => {
+          const { name: taskName, ...timing } = scheduleOptions
+          return schedule(taskName ?? eventName, timing, {
+            type: eventName,
+            payload: input ?? {},
+          })
+        },
+        enumerable: true,
+        configurable: true,
+        writable: false,
+      })
+    }
+    return surface as ActorScheduleSend<D['events']>
+  }
+
+  // The typed self-send surface: per-invocation buffers behind one
+  // shared method record shape. defineProperty so event names like
+  // 'constructor'-adjacent identifiers can never touch prototypes.
+  const makeSend = (
+    buffer: { type: string; payload: unknown }[],
+  ): ActorSend<D['events']> => {
+    const send: Record<string, unknown> = {}
+    for (const eventName of handlersByEvent.keys()) {
+      Object.defineProperty(send, eventName, {
+        value: (input?: unknown) => {
+          buffer.push({ type: eventName, payload: input ?? {} })
+        },
+        enumerable: true,
+        configurable: true,
+        writable: false,
+      })
+    }
+    return send as ActorSend<D['events']>
+  }
+
+  const handlers: Record<string, HandlerEntry<EventDefs>> = {}
+  for (const [eventName, def] of handlersByEvent) {
+    if (def.kind === 'concurrent') {
+      // No lane: concurrent handlers run in parallel — with the lane
+      // and with each other. They cannot write state (no draft to
+      // commit), so no serialization is needed for correctness; slow
+      // I/O lives here without blocking the actor.
+      handlers[eventName] = async (ctx) => {
+        const sends: { type: string; payload: unknown }[] = []
+        try {
+          await def.handle(
+            {
+              id: ctx.event.id,
+              attempt: ctx.attempt,
+              signal: ctx.signal,
+              send: makeSend(sends),
+              schedule: makeSchedule((taskName, timing, event) =>
+                ctx.session.schedule(
+                  taskName,
+                  timing as Parameters<typeof ctx.session.schedule>[1],
+                  event,
+                ),
+              ),
+              state: async () => {
+                const { state, index } = await ctx.session.state(
+                  serverReducer,
+                  { through: 'latest' },
+                )
+                return { state, index }
+              },
+            },
+            ctx.event.payload,
+          )
+        } catch (error) {
+          if (!(error instanceof NonRetriableError)) throw error
+          // A terminal failure is recorded for audit; nothing awaits a
+          // concurrent handler, so the marker is history, not an
+          // answer. Buffered sends are discarded — refusals are total,
+          // so compensate by completing (send then return), never by
+          // throwing.
+          const payload: ActorFailedPayload = {
+            message: ctx.event.id,
+            event: eventName,
+            error: describeError(error),
+          }
+          return { type: ACTOR_FAILED_EVENT, payload }
+        }
+        // Sends commit atomically with settlement; re-runs converge on
+        // the same deterministic message ids.
+        return sends
+      }
+      continue
+    }
+    handlers[eventName] = {
+      // One lane for every serial handler of one instance: the next
+      // message starts only after the previous one completed, and
+      // completion commits the state event atomically —
+      // read-modify-write on `ctx.state` is safe by exclusion, not by
+      // liveness.
+      lane: ACTOR_LANE,
+      handler: async (ctx) => {
+        // Explicitly 'latest', not the event-relative default: prior
+        // lane messages commit *after* this message was appended, so
+        // their state commits carry higher indexes than the trigger —
+        // 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, {
+          through: 'latest',
+        })
+        const draft = structuredClone(state)
+        const sends: { type: string; payload: unknown }[] = []
+        try {
+          await def.handle(
+            {
+              state: draft,
+              id: ctx.event.id,
+              attempt: ctx.attempt,
+              signal: ctx.signal,
+              send: makeSend(sends),
+              schedule: makeSchedule((taskName, timing, event) =>
+                ctx.session.schedule(
+                  taskName,
+                  timing as Parameters<typeof ctx.session.schedule>[1],
+                  event,
+                ),
+              ),
+            },
+            ctx.event.payload,
+          )
+        } catch (error) {
+          // A NonRetriableError is an answer: settle the message,
+          // record the refusal, deliver it to the waiting caller —
+          // no retry, no failure budget spent (buffered sends are
+          // discarded with the draft: refusals are total). Every
+          // other throw is an ordinary A2 handler failure: rethrown
+          // into core's retry machinery (backoff, ten-failure
+          // budget, dead letter) — including surrendered lease
+          // aborts, which core recognizes by identity.
+          if (!(error instanceof NonRetriableError)) throw error
+          const payload: ActorFailedPayload = {
+            message: ctx.event.id,
+            event: eventName,
+            error: describeError(error),
+          }
+          return { type: ACTOR_FAILED_EVENT, payload }
+        }
+        // One returned batch: buffered sends plus the state commit —
+        // committed atomically with completion, so a reserve and its
+        // trigger can never half-happen. The state event stays the
+        // outcome marker a waiting call resolves on. (Unconditional
+        // for now; a dirty check is a compatible later optimization.)
+        const payload: ActorStatePayload<D['state']> = {
+          state: draft,
+          event: eventName,
+          message: ctx.event.id,
+        }
+        return [...sends, { type: ACTOR_STATE_EVENT, payload }]
+      },
+    }
+  }
+
+  const presenceEnabled = (options as { presence?: unknown }).presence === true
+  // The '*' catch-all arms an open server-side vocabulary: the
+  // protocol types field names at compile time, the floor validates
+  // every value, and `authorize` sees every set. See openPresenceDefs.
+  const contract = presenceEnabled
+    ? createContract({ name, events, presence: openPresenceDefs })
+    : createContract({ name, events })
+  const server = createServer({
+    contract,
+    handlers,
+    ...(options.store ? { store: options.store } : {}),
+    ...(options.scheduler ? { scheduler: options.scheduler } : {}),
+    ...(options.telemetry ? { telemetry: options.telemetry } : {}),
+  })
+  // Single-writer discipline on the underlying session wire too: if an
+  // application mounts `def.server.fetch`, browsers may push declared
+  // events, never authored state or failure records.
+  setServerFetchHooks(server, {
+    validateIngress: ({ events: pushed }) => {
+      for (const event of pushed) {
+        if (event.type.startsWith('a2.actor.')) {
+          throw new TypeError(
+            `'${event.type}' is reserved — only a handler's completion can author it`,
+          )
+        }
+      }
+    },
+  })
+
+  const makeHandle = (id: string): ActorHandle<D> => {
+    const session = server.session(id)
+
+    const sendEvent = async (
+      eventName: string,
+      input: unknown,
+      sendOptions?: ActorSendOptions,
+    ): Promise<{ id: string; index: number }> => {
+      const [message] = await session.append({
+        type: eventName,
+        payload: input ?? {},
+        ...(sendOptions?.id ? { id: sendOptions.id } : {}),
+      })
+      if (!message) throw new Error('append returned no event')
+      return { id: message.id, index: message.index }
+    }
+
+    const callEvent = async (
+      eventName: string,
+      input: unknown,
+      callOptions?: ActorCallOptions,
+    ): Promise<ActorCallResult<D['state']>> => {
+      if (handlersByEvent.get(eventName)?.kind === 'concurrent') {
+        throw new TypeError(
+          `actor '${name}': '${eventName}' is concurrent — it produces no answer to await; send it instead`,
+        )
+      }
+      const message = await sendEvent(eventName, input, callOptions)
+      const deadline = Date.now() + (callOptions?.timeoutMs ?? CALL_TIMEOUT_MS)
+      let cursor = message.index + 1
+      for (;;) {
+        // 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 })
+        for (const event of tail) {
+          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 }
+            }
+          }
+          if (event.type === ACTOR_FAILED_EVENT) {
+            const payload = event.payload as ActorFailedPayload
+            if (payload.message === message.id) {
+              throw new ActorRefusedError(eventName, message.id, payload.error)
+            }
+          }
+        }
+        const last = tail[tail.length - 1]
+        if (last) cursor = last.index + 1
+        if (Date.now() >= deadline) {
+          throw new Error(
+            `actor '${name}': timed out waiting for '${eventName}' (message ${message.id})`,
+          )
+        }
+        await sleep(CALL_POLL_MS)
+      }
+    }
+
+    const readState = async (): Promise<ActorCallResult<D['state']>> => {
+      const { state, index } = await session.state(serverReducer)
+      return { state, index }
+    }
+
+    const applyView = (
+      view: (state: D['state']) => unknown,
+      state: D['state'],
+    ): unknown => {
+      const viewed = view(state)
+      if (!isJsonTree(viewed)) {
+        throw new TypeError(
+          `actor '${name}': the view returned a value that is not a plain JSON tree`,
+        )
+      }
+      return viewed
+    }
+
+    const streamStates = async function* (
+      startAfter: number,
+      view?: (state: D['state']) => unknown,
+    ) {
+      // With presence armed, the session interleaves presence items
+      // (snapshot, then patches) between log events. They are
+      // ephemeral audience data, not actor state: they pass through
+      // untouched — views project state, never peers — and they never
+      // advance the resume frontier.
+      const source: AsyncIterable<
+        | Awaited<ReturnType<typeof session.history>>[number]
+        | PresencePatch
+        | PresenceSnapshot
+      > = presenceEnabled
+        ? (
+            session as unknown as {
+              stream(options: {
+                startAfter: number
+                presence: true
+              }): AsyncIterable<PresencePatch | PresenceSnapshot>
+            }
+          ).stream({ startAfter, presence: true })
+        : session.stream({ startAfter })
+      for await (const item of source) {
+        if (!('type' in item)) {
+          yield item
+          continue
+        }
+        const event = item
+        // 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.
+        if (event.type !== ACTOR_STATE_EVENT) continue
+        if (!view) {
+          yield event
+          continue
+        }
+        const payload = event.payload as ActorStatePayload<D['state']>
+        yield {
+          ...event,
+          payload: { ...payload, state: applyView(view, payload.state) },
+        }
+      }
+    }
+
+    // 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`.
+    const handleFetch = async (
+      request: Request,
+      fetchOptions?: ActorFetchOptions<D>,
+    ): Promise<Response> => {
+      const authorized = async (operation: ActorOperation): Promise<boolean> =>
+        (await fetchOptions?.authorize?.(Object.freeze(operation))) !== false
+
+      if (request.method === 'GET') {
+        const url = new URL(request.url)
+        const raw = Number(url.searchParams.get('index'))
+        const startAfter = Number.isSafeInteger(raw) && raw >= 0 ? raw : 0
+        if (!(await authorized({ type: 'stream', id, startAfter }))) {
+          return forbidden()
+        }
+        return sseResponse(streamStates(startAfter, fetchOptions?.view))
+      }
+      if (request.method !== 'POST') {
+        return new Response(null, {
+          status: 405,
+          headers: { allow: 'GET, POST' },
+        })
+      }
+      let body: unknown
+      try {
+        body = await request.json()
+      } catch {
+        return Response.json({ error: 'invalid JSON body' }, { status: 400 })
+      }
+      const record =
+        typeof body === 'object' && body !== null
+          ? (body as Record<string, unknown>)
+          : {}
+      if ('presence' in record) {
+        // A presence envelope — what the follower client's
+        // `setPresence` posts. Events never ride this lane: writes to
+        // the actor are calls.
+        if (!presenceEnabled) {
+          return Response.json(
+            { error: `actor '${name}' declares no presence` },
+            { status: 400 },
+          )
+        }
+        const pushedEvents = record['events']
+        if (
+          pushedEvents !== undefined &&
+          (!Array.isArray(pushedEvents) || pushedEvents.length > 0)
+        ) {
+          return Response.json(
+            { error: 'the actor wire takes calls, not event pushes' },
+            { status: 400 },
+          )
+        }
+        let patch: ParsedPushPresence
+        try {
+          const parsed = parsePresenceSibling(record['presence'])
+          if (!parsed) throw new TypeError('presence must be an object')
+          patch = parsed
+        } catch (error) {
+          return Response.json({ error: describeError(error) }, { status: 400 })
+        }
+        if (
+          !(await authorized({
+            type: 'presence',
+            id,
+            participant: patch.participant,
+            values: patch.values,
+          }))
+        ) {
+          return forbidden()
+        }
+        try {
+          await (
+            session as unknown as {
+              setPresence(patch: ParsedPushPresence): Promise<void>
+            }
+          ).setPresence(patch)
+        } catch (error) {
+          if (
+            error instanceof A2Error &&
+            (error.code === 'INVALID_PAYLOAD' ||
+              error.code === 'UNKNOWN_PRESENCE_FIELD')
+          ) {
+            return Response.json({ error: error.message }, { status: 400 })
+          }
+          throw error
+        }
+        return Response.json([])
+      }
+      const eventName = record['event']
+      if (
+        typeof eventName !== 'string' ||
+        handlersByEvent.get(eventName)?.kind !== 'serial'
+      ) {
+        return Response.json({ error: 'unknown event' }, { status: 400 })
+      }
+      const messageId = record['messageId']
+      if (messageId !== undefined && typeof messageId !== 'string') {
+        return Response.json({ error: 'invalid messageId' }, { status: 400 })
+      }
+      const input = record['input']
+      if (
+        !(await authorized({
+          type: 'call',
+          id,
+          event: eventName,
+          input,
+          ...(messageId === undefined ? {} : { messageId }),
+        }))
+      ) {
+        return forbidden()
+      }
+      try {
+        const result = await callEvent(
+          eventName,
+          input,
+          messageId === undefined ? undefined : { id: messageId },
+        )
+        return Response.json(
+          fetchOptions?.view
+            ? {
+                state: applyView(fetchOptions.view, result.state),
+                index: result.index,
+              }
+            : result,
+        )
+      } catch (error) {
+        if (error instanceof ActorRefusedError) {
+          return Response.json(
+            {
+              error: error.message,
+              event: error.event,
+              messageId: error.messageId,
+            },
+            { status: 409 },
+          )
+        }
+        if (
+          error instanceof A2Error &&
+          (error.code === 'INVALID_PAYLOAD' ||
+            error.code === 'UNKNOWN_EVENT_TYPE')
+        ) {
+          return Response.json({ error: error.message }, { status: 400 })
+        }
+        throw error
+      }
+    }
+
+    const call: Record<string, unknown> = {}
+    const send: Record<string, unknown> = {}
+    for (const eventName of handlersByEvent.keys()) {
+      Object.defineProperty(call, eventName, {
+        value: (input?: unknown, callOptions?: ActorCallOptions) =>
+          callEvent(eventName, input, callOptions),
+        enumerable: true,
+        configurable: true,
+        writable: false,
+      })
+      Object.defineProperty(send, eventName, {
+        value: (input?: unknown, sendOptions?: ActorSendOptions) =>
+          sendEvent(eventName, input, sendOptions),
+        enumerable: true,
+        configurable: true,
+        writable: false,
+      })
+    }
+
+    const handle: ActorHandle<D> = {
+      id,
+      session,
+      call: call as ActorHandle<D>['call'],
+      send: send as ActorHandle<D>['send'],
+      state: readState,
+      fetch: handleFetch,
+    }
+    return handle
+  }
+
+  return {
+    name,
+    contract,
+    server,
+    reducer,
+    actor: makeHandle,
+  }
+}