experimental-a2 0.5.1 → 0.7.0

package/src/ai-server.ts

@@ -57,11 +57,14 @@ import {
   createServer,
   type A2Server,
   type HandlerContext,
-  type PushValidationContext,
   type ServerOptions,
 } from './server.ts'
+import {
+  setServerFetchHooks,
+  type ServerIngressContext,
+} from './server-fetch.ts'
 
-export function validateAgentPush(context: PushValidationContext): void {
+function validateAgentIngress(context: ServerIngressContext): void {
   const rejected = context.events.find((event) => {
     if (event.type !== 'ai.message.created') {
       return !(
@@ -203,7 +206,7 @@ export type CreateAgentServerOptions<
   D extends AIEventDefs<M> & EventDefs,
   T extends ToolSet = ToolSet,
 > = CreateHandlersOptions<M, D, T> &
-  Omit<ServerOptions<D>, 'contract' | 'handlers' | 'validatePush'> & {
+  Omit<ServerOptions<D>, 'contract' | 'handlers'> & {
     handlers?: ServerOptions<D>['handlers']
   }
 
@@ -1708,12 +1711,13 @@ export function createAgentServer<
     ...(compaction === undefined ? {} : { compaction }),
     ...(progress === undefined ? {} : { progress }),
   })
-  return createServer({
+  const server = createServer({
     ...serverOptions,
     contract: definition.contract,
     handlers: { ...builtIns, ...handlers },
-    validatePush: validateAgentPush,
   })
+  setServerFetchHooks(server, { validateIngress: validateAgentIngress })
+  return server
 }
 
 export type { Instructions, LanguageModel, ToolSet }

package/src/client.ts

@@ -177,13 +177,19 @@ export type SessionClient<
    * this throws a TypeError there.
    */
   loadHistory(options?: LoadHistoryOptions): Promise<ContractEvent<D>[]>
-  /** Open the live stream (idempotent while open). Reconnects with
-   * backoff and resumes from the frontier until `close()`. */
-  connect(): void
   /**
-   * Stop the live stream. Not terminal: `connect()` starts it again
-   * from the current frontier — which is what makes the React
-   * StrictMode mount dance (setup → cleanup → setup) work.
+   * Take a lease on the live stream and return its release. Leases
+   * refcount per handle — the first connects, releasing the last
+   * closes — so independent consumers of one identity-mapped handle
+   * (two hooks, a hook plus vanilla code) never fight over the
+   * stream. Releasing twice is a no-op. While any lease is held the
+   * stream reconnects with backoff and resumes from the frontier.
+   */
+  connect(): () => void
+  /**
+   * The hard stop: drops every outstanding lease and closes the
+   * stream now. Not terminal — a later `connect()` starts fresh from
+   * the current frontier.
    */
   close(): void
 }
@@ -193,11 +199,8 @@ export type SessionOptions<D extends EventDefs, S> = {
   initialIndex?: number
   /** Server-rendered history through `initialIndex`. Seeds the event feed. */
   initialEvents?: ContractEvent<D>[]
-  /**
-   * This client's presence identity — required to call `setPresence`.
-   * Caller-supplied (a user id, a tab nonce, a guest name): A2 does
-   * not invent an identity story. Bound once per session handle.
-   */
+  /** Overrides the client's `participant` for this session handle.
+   * Bound once per handle. */
   participant?: string
 }
 
@@ -263,6 +266,14 @@ export type CreateClientOptions<
   /** How long an idle session keeps its in-memory identity, in
    * milliseconds. Defaults to five minutes; `Infinity` disables GC. */
   gcTime?: number
+  /**
+   * This client's presence identity — required to call `setPresence`.
+   * Caller-supplied (a user id, a tab nonce, a guest name): A2 does
+   * not invent an identity story; the app states it once here. The
+   * default for every session handle this client creates;
+   * `session(id, { participant })` overrides it per handle.
+   */
+  participant?: string
 }
 
 const PUSH_ATTEMPTS = 3
@@ -797,7 +808,7 @@ const wsTransport = (
         settleChannel(
           channel,
           new Error(
-            'subscribe not confirmed: is the ws route serving the multiplexed socket (handle with options.upgrade)?',
+            'subscribe not confirmed: is the ws route calling server.fetch with upgradeWebSocket?',
           ),
         )
       }, STREAM_TIMINGS.stallTimeoutMs)
@@ -1022,7 +1033,7 @@ export function createClient<
     // stream; the own entry is the local echo — server copies of self
     // are ignored (the echo is at least as new, and comparing it to
     // server stamps would put two clocks in one order).
-    let participant = sessionOptions?.participant
+    let participant = sessionOptions?.participant ?? options.participant
     // Participant and field keys arrive off the wire, so the map and
     // every entry are built null-prototype — see `nullProtoRecord`.
     let presenceState: PresenceMap = nullProtoRecord()
@@ -1292,7 +1303,7 @@ export function createClient<
     const setPresence = (values: PresencePatch<P>['values']): void => {
       if (participant === undefined) {
         throw new TypeError(
-          'setPresence requires a participant — pass one in the session options (the SessionProvider participant prop)',
+          'setPresence requires a participant — pass one to createClient({ participant }) or in the session options (the SessionProvider/useSession participant prop)',
         )
       }
       const validated: Record<string, unknown> = nullProtoRecord()
@@ -1551,7 +1562,7 @@ export function createClient<
       const readHistory = transport.history
       if (readHistory === undefined) {
         throw new TypeError(
-          'loadHistory requires an http api — the ws transport has no history lane; serve the session over handle() and pass its route url as the string or { type: "http" } api',
+          'loadHistory requires an http api — the ws transport has no history lane; serve the session with server.fetch and pass its route url as the string or { type: "http" } api',
         )
       }
       const before = loadOptions?.before
@@ -1600,11 +1611,34 @@ export function createClient<
 
     // ── the live stream ──────────────────────────────────────────
     // A run-generation model instead of a terminal `closed` flag:
-    // close() bumps the generation (the running loop notices and
+    // stopping bumps the generation (the running loop notices and
     // exits), connect() starts a fresh one. Reentrant by design.
+    // Consumers hold leases: connect() counts one and returns its
+    // release, the last release stops the stream, and close() is the
+    // hard stop — it drops every lease and stops now (bumping
+    // `leaseEpoch` makes the outstanding releases inert).
     let generation = 0
     let active = false
     let abort: AbortController | null = null
+    let leases = 0
+    let leaseEpoch = 0
+
+    const stopStream = (): void => {
+      touch(sessionId)
+      if (!active) return
+      active = false
+      generation += 1 // the running loop notices and exits
+      abort?.abort()
+      abort = null
+      // A pending trailing send dies with the stream — losing one is
+      // fine by definition; sets made while closed accumulate in
+      // `presenceResend` and repaint after the next connect.
+      clearTimeout(presenceTimer)
+      presenceTimer = undefined
+      presenceBuffer = null
+      status = 'closed'
+      notify()
+    }
 
     const runStream = async (run: number): Promise<void> => {
       let backoff = STREAM_TIMINGS.reconnectBaseMs
@@ -1727,27 +1761,29 @@ export function createClient<
       loadHistory,
       connect() {
         touch(sessionId)
-        if (active) return
-        active = true
-        status = 'connecting'
-        notify()
-        void runStream(generation)
+        leases += 1
+        const epoch = leaseEpoch
+        if (!active) {
+          active = true
+          status = 'connecting'
+          notify()
+          void runStream(generation)
+        }
+        let released = false
+        return () => {
+          // Idempotent, and inert after a hard close() — a stale
+          // release must not touch leases taken since.
+          if (released || leaseEpoch !== epoch) return
+          released = true
+          touch(sessionId)
+          leases -= 1
+          if (leases === 0) stopStream()
+        }
       },
       close() {
-        touch(sessionId)
-        if (!active) return
-        active = false
-        generation += 1 // the running loop notices and exits
-        abort?.abort()
-        abort = null
-        // A pending trailing send dies with the stream — losing one is
-        // fine by definition; sets made while closed accumulate in
-        // `presenceResend` and repaint after the next connect.
-        clearTimeout(presenceTimer)
-        presenceTimer = undefined
-        presenceBuffer = null
-        status = 'closed'
-        notify()
+        leases = 0
+        leaseEpoch += 1
+        stopStream()
       },
       hydrate(next) {
         touch(sessionId)

package/src/errors.ts

@@ -8,6 +8,7 @@
 
 export type A2ErrorCode =
   | 'INVALID_PAYLOAD' // schema validation failed — thrown before anything is written
+  | 'FORBIDDEN' // external ingress was denied by server.fetch authorization
   | 'UNKNOWN_EVENT_TYPE' // event type not in the machine's `events` map
   | 'PARTIAL_DUPLICATE_BATCH' // batch mixed already-appended and fresh events
   | 'SUPERSEDED_ATTEMPT' // handler append from an attempt a recovery claim replaced

package/src/internal.ts

@@ -4,7 +4,7 @@
  */
 
 import type { ScheduledEvent } from './scheduler-task.ts'
-import type { A2Scheduler, DrainableServer } from './server.ts'
+import type { DrainableServer } from './server.ts'
 
 export type DrainOutcome = 'busy' | 'stalled' | 'settled'
 
@@ -67,14 +67,6 @@ export type ServerInternals = {
 
 export const serverInternals: WeakMap<object, ServerInternals> = new WeakMap()
 
-type ServerSchedulerBinding = {
-  scheduler: A2Scheduler | undefined
-}
-
-/** Scheduler configuration captured only for servers made by `createServer`. */
-export const serverSchedulerBindings: WeakMap<object, ServerSchedulerBinding> =
-  new WeakMap()
-
 const objectLike = (value: unknown): value is object =>
   (typeof value === 'object' && value !== null) || typeof value === 'function'
 
@@ -232,13 +224,11 @@ const isDrainableServer = (value: unknown): value is DrainableServer => {
 
 /**
  * Validate the server list captured by a scheduler route at construction time.
- * Built-in adapters keep their low-level target seam structural for custom
- * integrations. The application-facing `schedulerHandler` uses strict mode
- * so only servers made by this A2 copy reach a configured adapter.
+ * The seam stays structural so custom scheduler integrations can supply their
+ * own drainable targets.
  */
 export function assertSchedulerTargets(
   servers: readonly unknown[],
-  options: { allowStructural: boolean },
 ): asserts servers is readonly DrainableServer[] {
   const contracts = new Set<string>()
   for (const target of servers) {
@@ -252,56 +242,7 @@ export function assertSchedulerTargets(
       )
     }
     contracts.add(name)
-
-    const binding = serverSchedulerBindings.get(target)
-    if (!binding) {
-      if (!options.allowStructural) {
-        throw new TypeError(
-          `a2 scheduler: server for contract '${name}' was not created by createServer()`,
-        )
-      }
-      continue
-    }
-  }
-}
-
-/** Require every real server to share one exact configured scheduler. */
-export function assertServerSchedulerBindings(
-  scheduler: A2Scheduler,
-  servers: readonly DrainableServer[],
-): void {
-  for (const server of servers) {
-    const binding = serverSchedulerBindings.get(server)
-    if (!binding?.scheduler) {
-      throw new TypeError(
-        `a2 scheduler: server for contract '${server.contract.name}' has no scheduler configured`,
-      )
-    }
-    if (binding.scheduler !== scheduler) {
-      throw new TypeError(
-        `a2 scheduler: server for contract '${server.contract.name}' is configured with a different scheduler instance`,
-      )
-    }
-  }
-}
-
-/** Resolve the scheduler privately bound to a real A2 server. */
-export function schedulerForServer(server: unknown): A2Scheduler {
-  if (!isDrainableServer(server)) {
-    throw new TypeError('a2 scheduler: expected a server from createServer()')
-  }
-  const binding = serverSchedulerBindings.get(server)
-  if (!binding) {
-    throw new TypeError(
-      `a2 scheduler: server for contract '${server.contract.name}' was not created by createServer()`,
-    )
-  }
-  if (!binding.scheduler) {
-    throw new TypeError(
-      `a2 scheduler: server for contract '${server.contract.name}' has no scheduler configured`,
-    )
   }
-  return binding.scheduler
 }
 
 /**

package/src/push-envelope.ts

@@ -1,14 +1,25 @@
 /**
- * The push envelope's trust boundary — parsing and provenance-branding
- * for `{ sessionId, events, presence? }`, shared verbatim by the HTTP
+ * The push envelope's trust boundary for `{ sessionId, events, presence? }`,
+ * shared verbatim by the HTTP
  * POST lane and the socket's push/presence frames so INVALID_PAYLOAD
- * shapes are one implementation. Internal module — `handle` (and the
- * socket handler) compose it; it is not part of the public surface.
+ * shapes are one implementation. Internal module, not public API.
  */
 
 import { A2Error } from './errors.ts'
 import { MAX_DATE_MS, RESERVED_PARTICIPANT_IDS } from './internal.ts'
-import type { PushedEvent, PushedPresence } from './server.ts'
+
+export type ParsedPushEvent = {
+  type: string
+  payload: unknown
+  id?: string
+}
+
+export type ParsedPushPresence = {
+  participant: string
+  values: Record<string, unknown>
+  seen?: number
+  at?: number
+}
 
 export const invalidPushBody = (message: string): A2Error =>
   new A2Error('INVALID_PAYLOAD', `malformed push body: ${message}`)
@@ -17,18 +28,13 @@ const invalid = invalidPushBody
 
 export type PushBody = {
   sessionId: string
-  /** Branded: `session.append` accepts these directly (the push route
-   * path); schema validation still happens inside `append`. Empty only
-   * for a presence-only push. */
-  events: PushedEvent[]
-  /** Branded like `events`: `session.setPresence` accepts it whole;
-   * field validation still happens inside `setPresence`. */
-  presence?: PushedPresence
+  events: ParsedPushEvent[]
+  presence?: ParsedPushPresence
 }
 
 export function parsePresenceSibling(
   value: unknown,
-): PushedPresence | undefined {
+): ParsedPushPresence | undefined {
   if (value === undefined) return undefined
   if (value === null || typeof value !== 'object' || Array.isArray(value)) {
     throw invalid('presence must be an object when present')
@@ -68,14 +74,12 @@ export function parsePresenceSibling(
   } = { participant, values: values as Record<string, unknown> }
   if (seen !== undefined) out.seen = seen
   if (at !== undefined) out.at = at
-  Object.defineProperty(out, '~a2.pushed', { value: true })
-  return out as PushedPresence
+  return out
 }
 
-/** The events half of the envelope — shared verbatim by the POST body
- * and the socket's `push` frames, so the provenance brand and the
- * INVALID_PAYLOAD shapes are one implementation. */
-export function parsePushEvents(events: unknown): PushedEvent[] {
+/** The events half of the envelope, shared by the POST body and socket
+ * `push` frames so INVALID_PAYLOAD shapes have one implementation. */
+export function parsePushEvents(events: unknown): ParsedPushEvent[] {
   if (!Array.isArray(events) || events.length === 0) {
     throw invalid('events must be a non-empty array')
   }
@@ -95,8 +99,7 @@ export function parsePushEvents(events: unknown): PushedEvent[] {
       payload,
     }
     if (id !== undefined) out.id = id
-    Object.defineProperty(out, '~a2.pushed', { value: true })
-    return out as PushedEvent
+    return out
   })
 }
 

package/src/react.ts

@@ -10,6 +10,12 @@
  * renders resolve the same live session. Everything is typed by the
  * reducer value — no type arguments, and nothing here ever touches the
  * machine module.
+ *
+ * The standalone `useSession(client, sessionId, options?)` is the
+ * provider-less primitive for client-first apps: identity-mapped
+ * handles, one leased stream per session, and an app-owned hydration
+ * input — the hook holds the stream until the app hands it a
+ * `{ state, index }` fold.
  */
 
 import {
@@ -44,6 +50,30 @@ import type {
 } from './contract.ts'
 import type { Reducer } from './reducer.ts'
 
+export type UseSessionOptions<S> = {
+  /** Overrides the client's `participant` for this session — for apps
+   * whose identity is only known at mount time. Bound once per
+   * session handle. */
+  participant?: string
+  /**
+   * The server fold this session mounts from: the `{ state, index }`
+   * pair `session.state(reducer)` returns, fetched by the app through
+   * its own route. Atomic on purpose — the fold and its frontier
+   * travel together or not at all. While `undefined` (the app's fetch
+   * has not landed), the hook holds the stream; when the value
+   * arrives, the session hydrates through the ordinary re-hydration
+   * seam and the stream connects at that frontier. To fold from the log's start
+   * deliberately, hand the fold's true starting point:
+   * `{ state: reducer.initialState, index: 0 }` — state at index 0 is
+   * the reducer's seed by definition, so the explicit replay needs no
+   * special vocabulary. There is no pending/ready echo on the result:
+   * whether the fold has been handed over is this option — the
+   * caller's own input — so the data layer's loading state IS the
+   * pending state.
+   */
+  hydrate?: { state: S; index: number } | undefined
+}
+
 export type SessionProviderProps<D extends EventDefs, S> = {
   /** Which session to subscribe to. */
   sessionId: string
@@ -55,11 +85,8 @@ export type SessionProviderProps<D extends EventDefs, S> = {
   initialIndex: number
   /** Server-rendered event history through `initialIndex`. */
   initialEvents?: ContractEvent<D>[]
-  /**
-   * This client's presence identity — required to call `setPresence`.
-   * Caller-supplied (a user id, a tab nonce, a guest name): A2 does
-   * not invent an identity story.
-   */
+  /** Overrides the client's `participant` for this session — for apps
+   * whose identity is only known at mount time. */
   participant?: string
   children?: ReactNode
 }
@@ -156,7 +183,6 @@ export function createReact<
   options: { client: A2Client<D, S, P> } | { reducer: Reducer<D, S, P> },
 ): BoundA2React<D, S, P> | A2React<D, S, P> {
   const Context = createContext<SessionClient<D, S, P> | null>(null)
-  const providerMounts = new WeakMap<SessionClient<D, S, P> & object, number>()
   const resolveSession: (
     sessionId: string,
     api: string | undefined,
@@ -232,53 +258,101 @@ export function createReact<
         ),
       [sessionId, api, initialState, initialIndex, initialEvents, participant],
     )
-    useEffect(() => {
-      const mounts = providerMounts.get(client) ?? 0
-      providerMounts.set(client, mounts + 1)
-      if (mounts === 0) client.connect()
-      return () => {
-        const remaining = (providerMounts.get(client) ?? 1) - 1
-        if (remaining === 0) {
-          providerMounts.delete(client)
-          client.close()
-        } else {
-          providerMounts.set(client, remaining)
-        }
-      }
-    }, [client])
+    useSessionLifecycle(client, true)
     return createElement(Context.Provider, { value: client }, props.children)
   }
 
-  function useSession(): UseSessionResult<D, S, P> {
+  function useBoundSession(): UseSessionResult<D, S, P> {
     const client = useContext(Context)
     if (!client) {
       throw new Error(
         'useSession must be rendered inside its matching SessionProvider',
       )
     }
-    const snapshot: SessionSnapshot<D, S, P> = useSyncExternalStore(
-      client.subscribe,
-      client.getSnapshot,
-      client.getSnapshot,
-    )
-    return useMemo(() => {
-      // Runtime mirror of the WithPresence surface: the client attaches
-      // setPresence (and the snapshot carries presence) exactly when the
-      // reducer declares presence fields — no runtime-inert members.
-      const { setPresence } = client as Partial<SessionClientPresence<P>>
-      const { presence } = snapshot as Partial<{ presence: PresenceMap<P> }>
-      return {
-        state: snapshot.state,
-        events: snapshot.events,
-        index: snapshot.index,
-        connection: snapshot.connection,
-        push: client.push,
-        loadHistory: client.loadHistory,
-        history: snapshot.history,
-        ...(setPresence && presence ? { presence, setPresence } : {}),
-      } as UseSessionResult<D, S, P>
-    }, [snapshot, client])
+    return useSessionResult(client)
   }
 
-  return { SessionProvider, useSession }
+  return { SessionProvider, useSession: useBoundSession }
+}
+
+// ── the shared session lifecycle ───────────────────────────────
+
+/**
+ * Hold a stream lease while mounted and `live` — the client refcounts
+ * leases per handle, so however many providers and hooks mount one
+ * session, the first connects and the last release closes
+ * (StrictMode-safe: the lease is retaken on remount). A standalone
+ * hook without a `hydrate` value passes `live: false` and holds the
+ * stream — connecting an unhydrated session would replay the whole
+ * log, and the library never picks the expensive path silently.
+ */
+function useSessionLifecycle<D extends EventDefs, S, P extends PresenceDefs>(
+  session: SessionClient<D, S, P>,
+  live: boolean,
+): void {
+  useEffect(() => {
+    if (!live) return
+    return session.connect()
+  }, [session, live])
+}
+
+function useSessionResult<D extends EventDefs, S, P extends PresenceDefs>(
+  session: SessionClient<D, S, P>,
+): UseSessionResult<D, S, P> {
+  const snapshot: SessionSnapshot<D, S, P> = useSyncExternalStore(
+    session.subscribe,
+    session.getSnapshot,
+    session.getSnapshot,
+  )
+  return useMemo(() => {
+    // Runtime mirror of the WithPresence surface: the client attaches
+    // setPresence (and the snapshot carries presence) exactly when the
+    // reducer declares presence fields — no runtime-inert members.
+    const { setPresence } = session as Partial<SessionClientPresence<P>>
+    const { presence } = snapshot as Partial<{ presence: PresenceMap<P> }>
+    return {
+      state: snapshot.state,
+      events: snapshot.events,
+      index: snapshot.index,
+      connection: snapshot.connection,
+      push: session.push,
+      loadHistory: session.loadHistory,
+      history: snapshot.history,
+      ...(setPresence && presence ? { presence, setPresence } : {}),
+    } as UseSessionResult<D, S, P>
+  }, [snapshot, session])
+}
+
+/**
+ * The standalone, provider-less hook — for apps whose components reach
+ * sessions ad hoc (a sidebar of channel sessions, a user session read
+ * from a menu). Takes the shared client and a session id; the handle
+ * is identity-mapped, so every hook and provider mounting the same
+ * session shares one runtime and one leased stream. Hydration is
+ * app-owned: pass `hydrate` when your fetch lands; until then the
+ * stream is held, and your data layer's loading state is the pending
+ * state.
+ */
+export function useSession<
+  D extends EventDefs,
+  S,
+  P extends PresenceDefs = Record<never, never>,
+>(
+  client: A2Client<D, S, P>,
+  sessionId: string,
+  options?: UseSessionOptions<S>,
+): UseSessionResult<D, S, P> {
+  const { participant, hydrate } = options ?? {}
+  const session = useMemo(
+    () =>
+      client.session(sessionId, {
+        ...(hydrate === undefined
+          ? {}
+          : { initialState: hydrate.state, initialIndex: hydrate.index }),
+        ...(participant === undefined ? {} : { participant }),
+      }),
+    [client, sessionId, hydrate, participant],
+  )
+  useSessionLifecycle(session, hydrate !== undefined)
+  return useSessionResult(session)
 }

package/src/scheduler-qstash.ts

@@ -94,7 +94,7 @@ export type QStashTransport = {
 }
 
 export type QStashSchedulerOptions = {
-  /** Exact URL mounted with `schedulerHandler(...)`. Inferred in local dev and on Vercel. */
+  /** Exact URL mounted with `scheduler.handler(...)`. Inferred in local dev and on Vercel. */
   url?: string
   /** QStash API token. Default: `QSTASH_TOKEN`. */
   token?: string
@@ -819,7 +819,7 @@ export function qstash(options: QStashSchedulerOptions = {}): A2Scheduler {
     },
 
     handler(...servers: DrainableServer[]) {
-      assertSchedulerTargets(servers, { allowStructural: true })
+      assertSchedulerTargets(servers)
       const byContract = new Map<string, DrainableServer>()
       for (const server of servers) {
         byContract.set(server.contract.name, server)
@@ -851,7 +851,7 @@ export function qstash(options: QStashSchedulerOptions = {}): A2Scheduler {
         const server = byContract.get(task.contract)
         if (!server) {
           throw new Error(
-            `a2 scheduler: no server for contract '${task.contract}' — pass it to schedulerHandler(...)`,
+            `a2 scheduler: no server for contract '${task.contract}' — pass it to scheduler.handler(...)`,
           )
         }
         const internals = serverInternals.get(server)

package/src/scheduler-vercel.ts

@@ -368,7 +368,7 @@ export function vercelQueues(options: VercelQueuesOptions = {}): A2Scheduler {
     },
 
     handler(...servers: DrainableServer[]) {
-      assertSchedulerTargets(servers, { allowStructural: true })
+      assertSchedulerTargets(servers)
       const byContract = new Map<string, DrainableServer>()
       for (const server of servers) {
         byContract.set(server.contract.name, server)
@@ -386,7 +386,7 @@ export function vercelQueues(options: VercelQueuesOptions = {}): A2Scheduler {
             // wiring bug — throw so it redelivers and stays visible in
             // queue observability instead of vanishing on an ack.
             throw new Error(
-              `a2 scheduler: no server for contract '${task.contract}' — pass it to schedulerHandler(...)`,
+              `a2 scheduler: no server for contract '${task.contract}' — pass it to scheduler.handler(...)`,
             )
           }
           const internals = serverInternals.get(server)