experimental-a2 0.4.0 → 0.5.0

package/src/server.ts

@@ -0,0 +1,2700 @@
+// oxlint-disable no-await-in-loop -- scheduler advances after durable outcomes
+/**
+ * experimental-a2/server — where a contract is implemented. `createServer({
+ * contract, store, handlers, ... })` binds the vocabulary to storage and
+ * reactions; sessions, drains, claims, and scheduler all live here.
+ * Server-only by construction: this entry point is the only one that
+ * can reach a store backend, and its exports map fails loudly in browser
+ * bundles.
+ */
+
+import type {
+  AppendInput,
+  Contract,
+  ContractEvent,
+  EventDefs,
+  PresenceDefs,
+  PresenceMap,
+  PresencePatch,
+  PresenceSnapshot,
+  WithPresence,
+} from './contract.ts'
+import { A2Error, asStoreUnavailable } from './errors.ts'
+import {
+  DRAIN_TIMINGS,
+  POLL_TIMINGS,
+  MAX_DATE_MS,
+  RESERVED_PARTICIPANT_IDS,
+  markSchedulerSendFailure,
+  nullProtoRecord,
+  serverInternals,
+  serverSchedulerBindings,
+  type DrainOutcome,
+  type DrainResult,
+} from './internal.ts'
+import { InspectionUnsupportedError, serverInspection } from './inspection.ts'
+import { defaultSleep } from './store-polling.ts'
+import type {
+  A2Store,
+  AppendEvent,
+  Event,
+  EventCause,
+  StoreClaimAvailableResult,
+  StoreStateRead,
+  PresenceRow,
+  ReturnedEvent,
+  StoredEvent,
+} from './store.ts'
+import type { Reducer } from './reducer.ts'
+import { validateSync } from './validate.ts'
+import {
+  deterministicEventId,
+  deterministicReturnedEventId,
+  deterministicScheduledEventId,
+  deterministicScheduleId,
+} from './deterministic-id.ts'
+import { invocationDeadlineMs, platformWaitUntil } from './platform.ts'
+import { retryableLazy } from './retryable-lazy.ts'
+import type {
+  ScheduledEvent,
+  SchedulerAppendTask,
+  SchedulerTask,
+} from './scheduler-task.ts'
+import {
+  NOOP_TELEMETRY,
+  type A2SpanHandle,
+  type A2Telemetry,
+} from './telemetry.ts'
+
+/**
+ * Events that arrived over the wire through `parsePushBody` — already
+ * envelope-validated, headed for schema validation inside `append`.
+ * The brand lets the documented push route hand them straight to
+ * `session.append` without weakening typed appends for app code: a
+ * hand-written `{ type: string }` literal still fails to compile.
+ */
+export type PushedEvent = {
+  type: string
+  payload: unknown
+  id?: string
+  readonly '~a2.pushed': true
+}
+
+/**
+ * A presence patch that arrived over the wire through `parsePushBody`
+ * — same provenance brand as `PushedEvent`, so the documented route
+ * hands it whole to `session.setPresence` while a hand-written
+ * untyped patch still fails to compile. Field validation happens
+ * inside `setPresence`.
+ */
+export type PushedPresence = {
+  participant: string
+  values: Record<string, unknown>
+  seen?: number
+  /** The sender's LWW stamp in epoch ms; receipt time when absent. */
+  at?: number
+  readonly '~a2.pushed': true
+}
+
+export type PushValidationContext = {
+  sessionId: string
+  events: readonly PushedEvent[]
+  /** The whole pushed patch — present exactly on the presence-plane
+   * invocation, so the callback authorizes the participant id and can
+   * apply size or cardinality policy. */
+  presence?: PushedPresence
+}
+
+/** What every handler receives. */
+export type HandlerContext<
+  D extends EventDefs,
+  K extends keyof D & string = keyof D & string,
+  P extends PresenceDefs = Record<never, never>,
+> = {
+  /** The triggering event. */
+  event: ContractEvent<D, K>
+  /** Durable, 1-based dispatch ordinal for this event. */
+  attempt: number
+  /** This session, with handler-scoped idempotent append. */
+  session: Session<D, HandlerAppend<D>, P>
+  /** Fires on `abortOn` events (cancellation slice); dormant otherwise. */
+  signal: AbortSignal
+}
+
+export type Handler<
+  D extends EventDefs,
+  K extends keyof D & string = keyof D & string,
+  P extends PresenceDefs = Record<never, never>,
+> = (
+  ctx: HandlerContext<D, K, P>,
+) => Promise<void | AppendInput<D> | readonly AppendInput<D>[]>
+
+export type LaneContext<
+  D extends EventDefs,
+  K extends keyof D & string = keyof D & string,
+> = {
+  sessionId: string
+  event: Pick<ContractEvent<D, K>, 'type' | 'payload'> & { id?: string }
+}
+
+export type Lane<
+  D extends EventDefs,
+  K extends keyof D & string = keyof D & string,
+> = string | ((context: LaneContext<D, K>) => string)
+
+export type SessionDispatch<D extends EventDefs> = {
+  (...events: AppendInput<D>[]): Promise<ContractEvent<D>[]>
+  /** The push-route path: events from `parsePushBody`. */
+  (...events: PushedEvent[]): Promise<ContractEvent<D>[]>
+}
+
+export type SessionAppend<D extends EventDefs> = SessionDispatch<D> & {
+  /** Commit, then hand pending work directly to configured scheduler. */
+  dispatch: SessionDispatch<D>
+}
+
+export type HandlerAppend<D extends EventDefs> = (
+  name: string,
+  ...events: AppendInput<D>[]
+) => Promise<ContractEvent<D>[]>
+
+export type ScheduleDelay = `${number}${'ms' | 's' | 'm' | 'h' | 'd'}`
+
+export type ScheduleTiming =
+  { delay: ScheduleDelay; at?: never } | { at: Date; delay?: never }
+
+export type SessionSchedule<D extends EventDefs> = (
+  name: string,
+  timing: ScheduleTiming,
+  ...events: AppendInput<D>[]
+) => Promise<void>
+
+/**
+ * The presence members of a session — intersected in via
+ * `WithPresence`, so they exist exactly when the contract declares
+ * presence fields. Intersected before the base members so the widened
+ * `stream` overload is tried first: the literal `presence: true`
+ * selects it, everything else falls through to the events-only base.
+ */
+export type SessionPresence<D extends EventDefs, P extends PresenceDefs> = {
+  /**
+   * The two-plane feed: one snapshot of the current pruned map first
+   * (per-field stamps exact), then presence patches interleaved with
+   * events.
+   */
+  stream(opts: {
+    startAfter?: number
+    presence: true
+  }): AsyncIterable<ContractEvent<D> | PresencePatch<P> | PresenceSnapshot<P>>
+  /**
+   * Validate against the contract's presence schemas, then broadcast.
+   * Never an append: no log row, no dispatch, no scheduler arm. `at`
+   * is the sender's LWW stamp in epoch ms; omitted, receipt time
+   * stands in (single writer, so receipt order is sender order).
+   */
+  setPresence(
+    patch:
+      | {
+          participant: string
+          values: PresencePatch<P>['values']
+          seen?: number
+          at?: number
+        }
+      | PushedPresence,
+  ): Promise<void>
+  /** The current map, expired values pruned — a point-in-time read. */
+  presence(): Promise<PresenceMap<P>>
+}
+
+/** A handle on one instance of the machine. Creating it does no I/O. */
+export type Session<
+  D extends EventDefs,
+  Append = SessionAppend<D>,
+  P extends PresenceDefs = Record<never, never>,
+> = WithPresence<P, SessionPresence<D, P>> & {
+  readonly id: string
+  append: Append
+  schedule: SessionSchedule<D>
+  history(options?: { gte?: number; lte?: number }): Promise<ContractEvent<D>[]>
+  state<S>(reducer: Reducer<D, S>): Promise<{ state: S; index: number }>
+  /**
+   * A live feed of this session's events, starting after `startAfter`
+   * (exclusive). Server-side only — `handle` from experimental-a2/http
+   * exposes it over SSE as the route's stream lane.
+   */
+  stream(opts?: { startAfter?: number }): AsyncIterable<ContractEvent<D>>
+}
+
+/**
+ * The public server shape scheduler handlers accept. It stays structural so
+ * servers of any contract mix in one route; A2's private server internals add
+ * delayed-append delivery without exposing an untyped append method here.
+ */
+export type DrainableServer = {
+  readonly contract: { readonly name: string }
+  drain(sessionId: string): Promise<{ settled: boolean }>
+}
+
+/**
+ * The scheduler seam (a2-implementation.md §7, §9). `schedule` puts a
+ * versioned drain or delayed append task on durable infrastructure;
+ * `handler` returns the route the transport delivers to. Claim holders
+ * move the watchdog alongside their renewable execution window.
+ * Implementations ship as
+ * entry points (`experimental-a2/scheduler-vercel`); core never imports a
+ * transport.
+ */
+export type A2Scheduler = {
+  schedule(task: SchedulerTask): Promise<void>
+  handler(...servers: DrainableServer[]): (req: Request) => Promise<Response>
+}
+
+export type A2Server<
+  D extends EventDefs,
+  P extends PresenceDefs = Record<never, never>,
+> = {
+  /** The contract this server implements. */
+  readonly contract: Contract<D, P>
+  session(id: string): Session<D, SessionAppend<D>, P>
+  /**
+   * Process every currently eligible event. `settled` means nothing
+   * actionable remains, including work blocked behind a dead letter.
+   */
+  drain(sessionId: string): Promise<{ settled: boolean }>
+}
+
+/**
+ * Deliver one authenticated scheduler append through an A2 server's ordinary
+ * top-level append path. Custom scheduler adapters call this after validating
+ * their transport envelope; application code normally uses `session.schedule`.
+ */
+export async function deliverSchedulerAppend(
+  server: DrainableServer,
+  task: SchedulerAppendTask,
+): Promise<void> {
+  if (server.contract.name !== task.contract) {
+    throw new TypeError(
+      `a2 scheduler: append task for contract '${task.contract}' cannot be delivered to '${server.contract.name}'`,
+    )
+  }
+  const internals = serverInternals.get(server)
+  if (!internals) {
+    throw new TypeError(
+      `a2 scheduler: server for contract '${task.contract}' cannot receive scheduled appends`,
+    )
+  }
+  await internals.schedulerAppend(task.sessionId, task.events)
+}
+
+/**
+ * Which events fire `ctx.signal` while a handler runs — the preemption
+ * channel for user cancellation. The array form matches by type; the
+ * object form takes per-type predicates for targeted cancellation
+ * (`(event, trigger) => event.payload.of === trigger.id`). Handlers
+ * without `abortOn` pay nothing. An aborted handler should catch and
+ * return normally; throwing means "retry me".
+ */
+export type AbortSpec<D extends EventDefs, K extends keyof D & string> =
+  | Array<keyof D & string>
+  | {
+      [T in keyof D & string]?:
+        | true
+        | ((
+            event: ContractEvent<D, T>,
+            trigger: ContractEvent<D, K>,
+            context: { attempt: number },
+          ) => boolean)
+    }
+
+export type HandlerEntry<
+  D extends EventDefs,
+  K extends keyof D & string = keyof D & string,
+  P extends PresenceDefs = Record<never, never>,
+> =
+  | Handler<D, K, P>
+  | {
+      abortOn?: AbortSpec<D, K>
+      /** Session-scoped FIFO key, resolved and persisted when the event lands. */
+      lane?: Lane<D, K>
+      handler: Handler<D, K, P>
+    }
+
+export type ServerOptions<
+  D extends EventDefs,
+  P extends PresenceDefs = Record<never, never>,
+> = {
+  /** The contract this server implements (see `a2.contract`). */
+  contract: Contract<D, P>
+  /** Where events live. Defaults: sqlite in dev, memory in tests, required in prod. */
+  store?: A2Store
+  /**
+   * Queue-backed scheduler — e.g. `vercelQueues()` from
+   * `experimental-a2/scheduler-vercel`. Absent means append-driven healing only: a
+   * working configuration, but a clockless one. Recommended in
+   * production.
+   */
+  scheduler?: A2Scheduler
+  /** Optional instrumentation — e.g. `otel()` from `experimental-a2/otel`. */
+  telemetry?: A2Telemetry
+  /** Validate events that came through `parsePushBody` before writing them. */
+  validatePush?: (context: PushValidationContext) => void | PromiseLike<void>
+  /**
+   * Presence-plane policy — valid only when the contract declares
+   * presence fields (TypeError at construction otherwise). `ttlMs` is
+   * how long a value survives without a refreshing set; default 60s.
+   */
+  presence?: { ttlMs?: number }
+  /**
+   * The reactions, keyed by event type — all present at construction,
+   * so a handler can never be silently missing because its module
+   * wasn't imported. Compose across files by spreading objects (note:
+   * a duplicate key under spread silently last-wins).
+   */
+  handlers?: { [K in keyof D & string]?: HandlerEntry<D, K, P> }
+}
+
+const MAX_FAILURES = 10
+
+/** Default: how long a presence value survives without a refreshing set. */
+const PRESENCE_TTL_MS = 60_000
+
+type ClaimWindow = {
+  ttlMs: number
+  expiresAtMs: number
+  watchdogAtMs: number
+  deadlineCapped: boolean
+}
+
+type DrainSignal = {
+  version: number
+  closed: boolean
+  notify(): void
+  wait(version: number): { promise: Promise<void>; cancel(): void }
+}
+
+type AbortSubscription = {
+  controller: AbortController
+  triggerIndex: number
+  types: Set<string>
+  matches(event: Event): boolean
+}
+
+type AbortHub = {
+  subscriptions: Set<AbortSubscription>
+  seen: Map<number, Event>
+  startAfter: number
+  ready: Promise<void>
+  watch: Promise<void> | null
+  error: unknown
+  iterator: AsyncIterator<Event> | null
+  stopped: boolean
+}
+
+function createDrainSignal(): DrainSignal {
+  const listeners = new Set<() => void>()
+  return {
+    version: 0,
+    closed: false,
+    notify() {
+      this.version += 1
+      for (const listener of listeners) listener()
+      listeners.clear()
+    },
+    wait(version) {
+      if (this.version !== version) {
+        return { promise: Promise.resolve(), cancel: () => {} }
+      }
+      let resolve!: () => void
+      const promise = new Promise<void>((done) => {
+        resolve = done
+      })
+      listeners.add(resolve)
+      return { promise, cancel: () => listeners.delete(resolve) }
+    },
+  }
+}
+
+function dispatchAbortEvent(hub: AbortHub, event: Event): void {
+  let relevant = false
+  for (const subscription of hub.subscriptions) {
+    if (!subscription.types.has(event.type)) continue
+    relevant = true
+    if (subscription.matches(event)) subscription.controller.abort()
+  }
+  if (relevant) hub.seen.set(event.index, event)
+}
+
+function pruneAbortHub(hub: AbortHub): void {
+  let minimum = Infinity
+  const types = new Set<string>()
+  for (const subscription of hub.subscriptions) {
+    minimum = Math.min(minimum, subscription.triggerIndex)
+    for (const type of subscription.types) types.add(type)
+  }
+  for (const [index, event] of hub.seen) {
+    if (index <= minimum || !types.has(event.type)) hub.seen.delete(index)
+  }
+}
+
+/**
+ * Deadlines tighten the claim/watchdog window; they never decide whether a
+ * handler starts. A platform timeout therefore follows the same path as any
+ * other process death: the in-flight event remains pending and is retried.
+ */
+function nextClaimWindow(): ClaimWindow {
+  const nowMs = Date.now()
+  const deadlineMs = invocationDeadlineMs()
+  const deadlineTtlMs =
+    deadlineMs === null ? DRAIN_TIMINGS.claimTtlMs : deadlineMs - nowMs
+  const deadlineCapped =
+    deadlineMs !== null && deadlineTtlMs <= DRAIN_TIMINGS.claimTtlMs
+  const ttlMs = Math.max(1, Math.min(DRAIN_TIMINGS.claimTtlMs, deadlineTtlMs))
+  const expiresAtMs = nowMs + ttlMs
+  return {
+    ttlMs,
+    expiresAtMs,
+    watchdogAtMs: expiresAtMs + DRAIN_TIMINGS.watchdogGraceMs,
+    deadlineCapped,
+  }
+}
+
+function schedulerSlot(dueAt: number): number {
+  return Math.ceil(dueAt / 1_000) * 1_000
+}
+
+function currentSchedulerSlot(now: number): number {
+  return Math.floor(now / 1_000) * 1_000
+}
+
+/**
+ * The namespace separator between machine name and session id in
+ * storage. Machines sharing one store backend (the dev-default sqlite
+ * file, a shared Postgres) must not collide on session ids; the machine
+ * name is what makes multi-machine apps unambiguous (a2-api.md §1), so
+ * it prefixes every storage key.
+ */
+const NS = '\u001f'
+
+const devDefaultStore = retryableLazy(() =>
+  import('./store-sqlite.ts').then((m) => m.sqlite()),
+)
+
+function environment(): 'development' | 'test' | 'production' {
+  const env =
+    typeof process === 'undefined' ? undefined : process.env?.['NODE_ENV']
+  if (env === 'test') return 'test'
+  if (env === 'production') return 'production'
+  return 'development'
+}
+
+function describeError(err: unknown): string {
+  if (err instanceof Error) return err.stack ?? `${err.name}: ${err.message}`
+  return String(err)
+}
+
+/**
+ * Comparison key for a presence value in the degraded-tier diff — an
+ * LWW tie can replace a value without moving its `seen`/`at` stamp.
+ */
+function fingerprint(value: unknown): string {
+  return JSON.stringify(value) ?? ''
+}
+
+function foldPresenceRows(
+  rows: PresenceRow[],
+): Record<string, Record<string, { value: unknown; seen: number; at: Date }>> {
+  // Null-prototype at both levels: participants and fields are caller
+  // strings, and a '__proto__' key on a normal object rewrites its
+  // prototype instead of setting an own property.
+  const map =
+    nullProtoRecord<
+      Record<string, Record<string, { value: unknown; seen: number; at: Date }>>
+    >()
+  for (const row of rows) {
+    ;(map[row.participant] ??= nullProtoRecord())[row.field] = {
+      value: row.value,
+      seen: row.seen,
+      at: row.at,
+    }
+  }
+  return map
+}
+
+/** Implement a contract: bind its vocabulary to storage and reactions. */
+export function createServer<
+  D extends EventDefs,
+  P extends PresenceDefs = Record<never, never>,
+>(options: ServerOptions<D, P>): A2Server<D, P> {
+  const serverContract = options?.contract
+  if (
+    serverContract === null ||
+    typeof serverContract !== 'object' ||
+    typeof serverContract.name !== 'string' ||
+    serverContract.events === null
+  ) {
+    throw new TypeError(
+      'createServer expects options with a contract (see a2.contract)',
+    )
+  }
+  const name = serverContract.name
+  const defs = serverContract.events
+  const presenceDefs: Readonly<PresenceDefs> = serverContract.presence
+  const declaresPresence = Object.keys(presenceDefs).length > 0
+  const presenceNotSupported = (): A2Error =>
+    new A2Error(
+      'PRESENCE_NOT_SUPPORTED',
+      `the contract '${name}' declares presence but the store backend for its server has no presence capability (A2Store.presence)`,
+    )
+
+  if (options.presence !== undefined) {
+    // An option for a plane the contract doesn't declare is a mistake
+    // worth failing loud at construction.
+    if (!declaresPresence) {
+      throw new TypeError(
+        `the presence option requires a contract that declares presence fields — '${name}' has none`,
+      )
+    }
+    const { ttlMs } = options.presence
+    if (ttlMs !== undefined && (!Number.isInteger(ttlMs) || ttlMs <= 0)) {
+      throw new TypeError(
+        'presence.ttlMs must be a positive integer of milliseconds',
+      )
+    }
+  }
+  const presenceTtlMs = options.presence?.ttlMs ?? PRESENCE_TTL_MS
+
+  // Resolve where events live. Explicit store wins; otherwise the
+  // environment decides — and production refuses to guess
+  // (a2-implementation.md §8): a failed boot beats events written to an
+  // ephemeral filesystem.
+  let makeStore: () => Promise<A2Store>
+  if (options.store) {
+    const explicit = options.store
+    // Fail at boot, not first use (a2-api.md §12).
+    if (declaresPresence && !explicit.presence) throw presenceNotSupported()
+    makeStore = () => Promise.resolve(explicit)
+  } else {
+    const env = environment()
+    if (env === 'production') {
+      const error = (): A2Error =>
+        new A2Error(
+          'STORE_NOT_CONFIGURED',
+          `the server for '${name}' has no store configured and NODE_ENV is 'production' — pass an explicit store backend (e.g. postgres from 'experimental-a2/store-postgres')`,
+        )
+      // `next build` evaluates route modules with NODE_ENV=production
+      // to collect page data — in a CI without the runtime env vars, a
+      // construction-time throw fails the build for nothing (the store is
+      // never used during collection). During that phase only, defer
+      // the failure to first use; a real production boot still fails at
+      // construction, before any event can land somewhere ephemeral.
+      if (process.env['NEXT_PHASE'] !== 'phase-production-build') {
+        throw error()
+      }
+      makeStore = () => Promise.reject(error())
+    } else {
+      makeStore =
+        env === 'test'
+          ? () => import('./store-memory.ts').then((m) => m.memory())
+          : devDefaultStore.get
+    }
+  }
+
+  // Environment-resolved stores arrive lazily; assert the capability the
+  // moment one resolves — the closest available moment to construction.
+  if (declaresPresence && !options.store) {
+    const inner = makeStore
+    makeStore = async () => {
+      const store = await inner()
+      if (!store.presence) throw presenceNotSupported()
+      return store
+    }
+  }
+
+  const resolveStore = retryableLazy(makeStore).get
+
+  const telemetry = options.telemetry ?? NOOP_TELEMETRY
+  const scheduler = options.scheduler
+
+  type AbortMatcher = Map<
+    string,
+    | true
+    | ((
+        event: ContractEvent<D>,
+        trigger: ContractEvent<D>,
+        context: { attempt: number },
+      ) => boolean)
+  >
+  const handlers = new Map<
+    string,
+    { handler: Handler<D>; abortOn: AbortMatcher | null; lane: Lane<D> | null }
+  >()
+  for (const [type, entry] of Object.entries(options.handlers ?? {})) {
+    if (entry === undefined) continue
+    if (!Object.hasOwn(defs, type)) {
+      throw new TypeError(
+        `contract '${name}' has no event type '${type}' — cannot register a handler for it`,
+      )
+    }
+    const handler = typeof entry === 'function' ? entry : entry?.handler
+    if (typeof handler !== 'function') {
+      throw new TypeError(`handler for '${type}' must be a function`)
+    }
+    let abortOn: AbortMatcher | null = null
+    const spec = typeof entry === 'function' ? undefined : entry.abortOn
+    if (spec !== undefined) {
+      abortOn = new Map()
+      const pairs = Array.isArray(spec)
+        ? spec.map((abortType) => [abortType, true as const] as const)
+        : (Object.entries(spec) as Array<
+            [
+              string,
+              (
+                | true
+                | ((
+                    e: never,
+                    t: never,
+                    context: { attempt: number },
+                  ) => boolean)
+              ),
+            ]
+          >)
+      for (const [abortType, matcher] of pairs) {
+        if (matcher === undefined) continue
+        if (!Object.hasOwn(defs, abortType)) {
+          throw new TypeError(
+            `contract '${name}' has no event type '${String(abortType)}' — cannot abort on it`,
+          )
+        }
+        abortOn.set(String(abortType), matcher as never)
+      }
+      if (abortOn.size === 0) abortOn = null
+    }
+    const lane = typeof entry === 'function' ? null : (entry.lane ?? null)
+    if (
+      lane !== null &&
+      typeof lane !== 'function' &&
+      (typeof lane !== 'string' || lane.length === 0)
+    ) {
+      throw new TypeError(
+        `lane for '${type}' must be a non-empty string or a function`,
+      )
+    }
+    handlers.set(type, {
+      handler: handler as Handler<D>,
+      abortOn,
+      lane: lane as Lane<D> | null,
+    })
+  }
+
+  const prefix = `${name}${NS}`
+  const nsId = (sessionId: string): string => `${prefix}${sessionId}`
+  const stripNs = (stored: string): string => stored.slice(prefix.length)
+
+  const toPublic = (row: Event): ContractEvent<D> =>
+    ({
+      id: row.id,
+      type: row.type,
+      payload: row.payload,
+      index: row.index,
+      sessionId: stripNs(row.sessionId),
+      createdAt: row.createdAt,
+    }) as ContractEvent<D>
+
+  // ── background work tracking ─────────────────────────────────────
+  // Every fire-and-forget operation is tracked so (a) platforms with
+  // waitUntil keep the invocation alive and (b) tests can flush
+  // deterministically via serverInternals.
+  const inFlight = new Set<Promise<unknown>>()
+  const track = (p: Promise<unknown>): void => {
+    inFlight.add(p)
+    const drop = (): void => {
+      inFlight.delete(p)
+    }
+    p.then(drop, drop)
+  }
+
+  type SchedulerArmSlot = {
+    promise: Promise<void>
+    forget: ReturnType<typeof setTimeout>
+  }
+  const schedulerArmSlots = new Map<string, SchedulerArmSlot>()
+
+  /**
+   * Start an optional scheduler arm without putting it on the execution path.
+   * The returned raw promise lets the initial append report failure; the
+   * tracked copy is always rejection-safe for heartbeat callers.
+   */
+  const startSchedulerArm = (
+    sessionId: string,
+    dueAt: number,
+  ): Promise<void> | null => {
+    if (!scheduler) return null
+    const slottedDueAt = schedulerSlot(dueAt)
+    const slotKey = JSON.stringify([sessionId, slottedDueAt])
+    const existing = schedulerArmSlots.get(slotKey)
+    if (existing) return existing.promise
+    // Normalize even a custom adapter's synchronous throw into a rejected
+    // promise. Optional scheduler must never stop inline claiming.
+    const raw = Promise.resolve().then(() =>
+      scheduler.schedule({
+        version: 1,
+        kind: 'drain',
+        contract: name,
+        sessionId,
+        dueAt: slottedDueAt,
+      }),
+    )
+    const forget = setTimeout(
+      () => {
+        if (schedulerArmSlots.get(slotKey)?.promise === raw) {
+          schedulerArmSlots.delete(slotKey)
+        }
+      },
+      Math.max(0, slottedDueAt - Date.now()) + 1_000,
+    )
+    ;(forget as { unref?: () => void }).unref?.()
+    schedulerArmSlots.set(slotKey, { promise: raw, forget })
+    void raw.then(undefined, () => {
+      const current = schedulerArmSlots.get(slotKey)
+      if (current?.promise !== raw) return
+      clearTimeout(current.forget)
+      schedulerArmSlots.delete(slotKey)
+    })
+    const safe = raw.catch(() => {})
+    track(safe)
+    platformWaitUntil(safe)
+    return raw
+  }
+
+  const scheduledDrains = new Map<
+    string,
+    { signal: DrainSignal; promise: Promise<void> }
+  >()
+
+  const scheduleDrain = (sessionId: string, watchdogDueAt?: number): void => {
+    const existing = scheduledDrains.get(sessionId)
+    if (existing && !existing.signal.closed) {
+      existing.signal.notify()
+      return
+    }
+    if (existing) scheduledDrains.delete(sessionId)
+    const signal = createDrainSignal()
+    const p = new Promise<void>((resolve) => {
+      queueMicrotask(() => {
+        void drainSession(sessionId, watchdogDueAt, signal)
+          .then(() => resolve())
+          .catch(() => resolve())
+      })
+    }).finally(() => {
+      if (scheduledDrains.get(sessionId)?.promise === p) {
+        scheduledDrains.delete(sessionId)
+      }
+    })
+    scheduledDrains.set(sessionId, { signal, promise: p })
+    track(p)
+    platformWaitUntil(p)
+  }
+
+  // ── append ───────────────────────────────────────────────────────
+
+  const validateEvents = (
+    sessionId: string,
+    events: AppendInput<D>[],
+    resolveDispatchMetadata = true,
+  ): AppendEvent[] => {
+    if (events.length === 0) {
+      throw new TypeError('append requires at least one event')
+    }
+    return events.map((e) => {
+      const schema = Object.hasOwn(defs, e.type) ? defs[e.type] : undefined
+      if (!schema) {
+        throw new A2Error(
+          'UNKNOWN_EVENT_TYPE',
+          `contract '${name}' has no event type '${String(e.type)}'`,
+        )
+      }
+      const result = validateSync(schema, e.payload, `event '${e.type}'`)
+      if (result.issues) {
+        throw new A2Error(
+          'INVALID_PAYLOAD',
+          `invalid payload for event '${e.type}' on machine '${name}'`,
+          { details: result.issues },
+        )
+      }
+      const validated: AppendEvent = { type: e.type, payload: result.value }
+      if (e.id !== undefined) validated.id = e.id
+      if (!resolveDispatchMetadata) return validated
+      const registration = handlers.get(e.type)
+      if (!registration) {
+        validated.settled = true
+      } else if (registration.lane !== null) {
+        const lane =
+          typeof registration.lane === 'function'
+            ? registration.lane({
+                sessionId,
+                event: {
+                  type: e.type,
+                  payload: structuredClone(result.value),
+                  ...(e.id === undefined ? {} : { id: e.id }),
+                } as never,
+              })
+            : registration.lane
+        if (typeof lane !== 'string' || lane.length === 0) {
+          throw new TypeError(
+            `lane for '${e.type}' must resolve to a non-empty string`,
+          )
+        }
+        validated.lane = lane
+      }
+      return validated
+    })
+  }
+
+  /**
+   * Validate + write. `onAppended` runs inside the telemetry span, so
+   * the drain it schedules is created in the append's active context —
+   * with a real tracer, causal work remains connected.
+   */
+  const appendCore = (
+    sessionId: string,
+    events: AppendInput<D>[],
+    source: 'external' | 'handler',
+    mode: 'inline' | 'dispatch',
+    onAppended: (rows: ContractEvent<D>[], watchdogDueAt?: number) => void,
+    cause?: EventCause,
+    generatedIds?: readonly boolean[],
+    requireDurableInitialArm = false,
+  ): Promise<ContractEvent<D>[]> =>
+    telemetry.span(
+      'a2.append',
+      {
+        'a2.contract': name,
+        'a2.session_id': sessionId,
+        'a2.append.source': source,
+        'a2.append.mode': mode,
+        'a2.append.types': events.map((e) => String(e.type)).join(','),
+        'a2.append.count': events.length,
+      },
+      async (span) => {
+        if (mode === 'dispatch' && !scheduler) {
+          throw new TypeError(
+            'append.dispatch requires a configured scheduler adapter',
+          )
+        }
+        assertSessionId(sessionId)
+        const validated = validateEvents(sessionId, events)
+        if (cause) {
+          for (const [index, event] of validated.entries()) {
+            event.cause = generatedIds?.[index]
+              ? { ...cause, batchSize: events.length }
+              : cause
+          }
+        }
+        const store = await resolveStore()
+        let rows: StoredEvent[]
+        let shouldHealSession: boolean
+        try {
+          const result = await store.append(nsId(sessionId), validated)
+          rows = result.events
+          shouldHealSession = result.hasPending
+        } catch (err) {
+          throw asStoreUnavailable(err)
+        }
+        const appended = rows.map(toPublic)
+
+        const initialWatchdogAt =
+          shouldHealSession &&
+          scheduler &&
+          source === 'external' &&
+          mode === 'inline'
+            ? schedulerSlot(nextClaimWindow().watchdogAtMs)
+            : undefined
+        const initialArm =
+          initialWatchdogAt !== undefined
+            ? startSchedulerArm(sessionId, initialWatchdogAt)
+            : null
+        const dispatchArm =
+          shouldHealSession && mode === 'dispatch'
+            ? startSchedulerArm(sessionId, currentSchedulerSlot(Date.now()))
+            : null
+        if (shouldHealSession && mode === 'inline') {
+          onAppended(appended, initialWatchdogAt)
+        }
+        if (dispatchArm) {
+          await dispatchArm
+        }
+        if (initialArm) {
+          let timeout: ReturnType<typeof setTimeout> | null = null
+          try {
+            await Promise.race([
+              initialArm,
+              new Promise<never>((_, reject) => {
+                timeout = setTimeout(() => {
+                  reject(
+                    new Error(
+                      `a2 scheduler arm timed out after ${DRAIN_TIMINGS.schedulerArmTimeoutMs}ms`,
+                    ),
+                  )
+                }, DRAIN_TIMINGS.schedulerArmTimeoutMs)
+              }),
+            ])
+          } catch (err) {
+            span.setAttribute('a2.append.armed', false)
+            span.recordError(err)
+            if (requireDurableInitialArm) throw err
+          } finally {
+            if (timeout) clearTimeout(timeout)
+          }
+        }
+        return appended
+      },
+    )
+
+  const readHistory = async (
+    sessionId: string,
+    bounds?: { gte?: number; lte?: number },
+  ): Promise<StoredEvent[]> => {
+    const gte = bounds?.gte
+    const lte = bounds?.lte
+    assertHistoryIndex('gte', gte)
+    assertHistoryIndex('lte', lte)
+    if (gte !== undefined && lte !== undefined && gte > lte) {
+      throw new RangeError(
+        'history.gte must be less than or equal to history.lte',
+      )
+    }
+    if (lte === 0) return []
+
+    const store = await resolveStore()
+    try {
+      const readOptions =
+        gte === undefined && lte === undefined
+          ? undefined
+          : {
+              ...(gte === undefined
+                ? {}
+                : { afterIndex: Math.max(0, gte - 1) }),
+              ...(lte === undefined ? {} : { throughIndex: lte }),
+            }
+      const rows = await store.read(nsId(sessionId), readOptions)
+      return rows.filter(
+        (row) =>
+          (gte === undefined || row.index >= gte) &&
+          (lte === undefined || row.index <= lte),
+      )
+    } catch (err) {
+      throw asStoreUnavailable(err)
+    }
+  }
+
+  // Snapshot plus tail is one adapter operation. A cache-path failure is
+  // not load-bearing: fall back to the raw store, which still reports a
+  // real storage failure.
+  const readCachedState = async (
+    store: A2Store,
+    sessionId: string,
+    reducerName: string,
+  ): Promise<StoreStateRead> => {
+    try {
+      return await store.readState(nsId(sessionId), reducerName)
+    } catch {
+      try {
+        return { snapshot: null, events: await store.read(nsId(sessionId)) }
+      } catch (err) {
+        throw asStoreUnavailable(err)
+      }
+    }
+  }
+
+  // The cache is untrusted: schema rejection refolds from the raw store.
+  const foldStateRead = async <S>(
+    store: A2Store,
+    sessionId: string,
+    reducer: Reducer<D, S>,
+    stateRead: StoreStateRead,
+    span: A2SpanHandle,
+  ): Promise<{ state: S; index: number; folded: number }> => {
+    let state = cloneInitial(reducer.initialState)
+    let index = 0
+    let snapshotOutcome = 'miss'
+    const snap = stateRead.snapshot
+    let rows = stateRead.events
+    if (snap) {
+      if (reducer.stateSchema) {
+        const result = validateSync(
+          reducer.stateSchema,
+          snap.state,
+          'the stateSchema',
+        )
+        if (result.issues) {
+          snapshotOutcome = 'rejected'
+        } else {
+          state = result.value as S
+          index = snap.index
+          snapshotOutcome = 'hit'
+        }
+      } else {
+        state = snap.state as S
+        index = snap.index
+        snapshotOutcome = 'hit'
+      }
+    }
+    span.setAttribute('a2.state.snapshot', snapshotOutcome)
+
+    if (snapshotOutcome === 'rejected') {
+      try {
+        rows = await store.read(nsId(sessionId))
+      } catch (err) {
+        throw asStoreUnavailable(err)
+      }
+    }
+    for (const row of rows) {
+      state = reducer.fold(state, toPublic(row) as never)
+      index = row.index
+    }
+    span.setAttribute('a2.state.folded', rows.length)
+    span.setAttribute('a2.state.index', index)
+    return { state, index, folded: rows.length }
+  }
+
+  // ── same-tick state-read coalescing ──────────────────────────────
+  // Concurrent state() calls for one reducer name coalesce into a
+  // single store.readStates() round trip when the adapter has one.
+  // Unlike DataLoader there is deliberately NO result cache: a batch
+  // exists only between enqueue and flush, and nothing is shared after
+  // distribution — every state() call still observes a fresh frontier.
+  type PendingStateRead = {
+    sessionId: string
+    resolve: (read: StoreStateRead | Promise<StoreStateRead>) => void
+  }
+  const pendingStateReads = new Map<string, PendingStateRead[]>()
+
+  // The flush microtask voids this promise, so the function must be
+  // total: never reject, never leave an entry unresolved — even for a
+  // synchronously throwing adapter or a read structuredClone rejects.
+  const flushStateReads = async (
+    store: A2Store,
+    reducerName: string,
+    batch: PendingStateRead[],
+  ): Promise<void> => {
+    let reads: StoreStateRead[] | null
+    try {
+      reads = store.readStates
+        ? await store.readStates(
+            batch.map((entry) => nsId(entry.sessionId)),
+            reducerName,
+          )
+        : null
+    } catch {
+      reads = null
+    }
+    // A failed or misaligned batch is an ill-behaved cache path, never a
+    // batch-shaped error: each caller falls back to its own per-call read
+    // (promise adoption carries a real storage failure to that caller).
+    if (!reads || reads.length !== batch.length) {
+      for (const entry of batch) {
+        entry.resolve(readCachedState(store, entry.sessionId, reducerName))
+      }
+      return
+    }
+    // Duplicate ids share one store read; their folds must not share
+    // payload objects, exactly as two separate state() calls would not.
+    const seen = new Set<string>()
+    for (const [position, entry] of batch.entries()) {
+      const shared = seen.has(entry.sessionId)
+      seen.add(entry.sessionId)
+      try {
+        const read = reads[position]!
+        entry.resolve(shared ? structuredClone(read) : read)
+      } catch {
+        entry.resolve(readCachedState(store, entry.sessionId, reducerName))
+      }
+    }
+  }
+
+  const enqueueStateRead = (
+    store: A2Store,
+    sessionId: string,
+    reducerName: string,
+  ): Promise<StoreStateRead> =>
+    new Promise((resolve) => {
+      let batch = pendingStateReads.get(reducerName)
+      if (!batch) {
+        const opened: PendingStateRead[] = []
+        pendingStateReads.set(reducerName, opened)
+        // One microtask is the whole batching window — deliberately NOT
+        // DataLoader's post-promise-job nextTick, which would defer
+        // handler-internal reads past the entire microtask cascade and
+        // reorder drain interleaving (and has no edge-runtime primitive).
+        // It still coalesces reliably: siblings of one Promise.all
+        // traverse identical awaits (store resolution, span wrapper), so
+        // their enqueues sit at consecutive queue positions — cold or
+        // warm — and this flush, queued by the first of them, runs after
+        // the last. A deeper-staggered caller just opens the next batch.
+        queueMicrotask(() => {
+          pendingStateReads.delete(reducerName)
+          void flushStateReads(store, reducerName, opened)
+        })
+        batch = opened
+      }
+      batch.push({ sessionId, resolve })
+    })
+
+  const readState = async <S>(
+    sessionId: string,
+    reducer: Reducer<D, S>,
+  ): Promise<{ state: S; index: number }> => {
+    const store = await resolveStore()
+    return telemetry.span(
+      'a2.state',
+      {
+        'a2.contract': name,
+        'a2.session_id': sessionId,
+        'a2.state.reducer': reducer.name,
+      },
+      async (span) => {
+        const stateRead = store.readStates
+          ? await enqueueStateRead(store, sessionId, reducer.name)
+          : await readCachedState(store, sessionId, reducer.name)
+        const { state, index, folded } = await foldStateRead(
+          store,
+          sessionId,
+          reducer,
+          stateRead,
+          span,
+        )
+        // Write-back is a disposable cache. Copy before returning so caller
+        // mutations cannot race the background persistence.
+        if (folded > 0) {
+          const snapshotState = cloneInitial(state)
+          const write = Promise.resolve()
+            .then(() =>
+              store.putSnapshot(
+                nsId(sessionId),
+                reducer.name,
+                index,
+                snapshotState,
+              ),
+            )
+            .catch(() => {})
+          track(write)
+          platformWaitUntil(write)
+        }
+        return { state, index }
+      },
+    )
+  }
+
+  const makeSchedule = (
+    sessionId: string,
+    trigger: Pick<StoredEvent, 'id' | 'createdAt'> | null,
+  ): SessionSchedule<D> => {
+    const triggerEventId = trigger?.id ?? null
+    const triggerCreatedAt = trigger?.createdAt.getTime()
+    return async (scheduleName, timing, ...events) => {
+      if (!scheduler) {
+        throw new TypeError(
+          'session.schedule requires a configured scheduler adapter',
+        )
+      }
+      assertScheduleName(scheduleName)
+      if (events.length === 0) {
+        throw new TypeError('schedule requires at least one event')
+      }
+      const dueAt = scheduleDueAt(timing, triggerCreatedAt ?? Date.now())
+      const payloads = events.map((event) =>
+        cloneScheduledPayload(event.payload),
+      )
+      const snapshottedEvents = events.map((event, index) => ({
+        type: event.type,
+        payload: payloads[index],
+        ...(event.id === undefined ? {} : { id: event.id }),
+      })) as AppendInput<D>[]
+      const validated = validateEvents(
+        sessionId,
+        structuredClone(snapshottedEvents),
+        false,
+      )
+      const scheduleId = await deterministicScheduleId(
+        name,
+        sessionId,
+        triggerEventId,
+        scheduleName,
+      )
+      const scheduledEvents: ScheduledEvent[] = await Promise.all(
+        validated.map(async (event, item) => ({
+          id:
+            event.id ?? (await deterministicScheduledEventId(scheduleId, item)),
+          type: event.type,
+          payload: payloads[item],
+        })),
+      )
+      if (
+        new Set(scheduledEvents.map((event) => event.id)).size !==
+        scheduledEvents.length
+      ) {
+        throw new A2Error(
+          'PARTIAL_DUPLICATE_BATCH',
+          'scheduled batch contains the same event id more than once',
+        )
+      }
+      try {
+        await scheduler.schedule({
+          version: 1,
+          kind: 'append',
+          id: scheduleId,
+          contract: name,
+          sessionId,
+          dueAt,
+          events: scheduledEvents,
+        })
+      } catch (error) {
+        throw markSchedulerSendFailure(error)
+      }
+    }
+  }
+
+  const toSessionEvent = (id: string, event: Event): ContractEvent<D> =>
+    ({
+      id: event.id,
+      type: event.type,
+      payload: event.payload,
+      index: event.index,
+      sessionId: id,
+      createdAt: event.createdAt,
+    }) as ContractEvent<D>
+
+  const streamEvents = (
+    id: string,
+    startAfter: number,
+  ): AsyncIterable<ContractEvent<D>> => {
+    const store = resolveStore()
+    const outer = async function* (): AsyncGenerator<ContractEvent<D>> {
+      const inner = (await store).stream(nsId(id), { startAfter })
+      for await (const event of inner) yield toSessionEvent(id, event)
+    }
+    return outer()
+  }
+
+  // ── presence ──────────────────────────────────────────────
+
+  const requirePresence = (
+    store: A2Store,
+  ): NonNullable<A2Store['presence']> => {
+    if (!store.presence) throw presenceNotSupported()
+    return store.presence
+  }
+
+  const setPresence = async (
+    sessionId: string,
+    patch: {
+      participant: string
+      values: Record<string, unknown>
+      seen?: number
+      at?: number
+    },
+    fallbackSeen: number,
+  ): Promise<void> => {
+    // The push-route provenance seam, mirroring appendExternal: a
+    // branded patch came from the wire, so `validatePush` runs before
+    // field validation and the broadcast — with `events: []`, the
+    // documented presence-only shape.
+    if (Reflect.get(patch, '~a2.pushed') === true) {
+      // Frozen before the callback: this is the authorization seam,
+      // and an authorization hook must not be able to rewrite
+      // authorship or values on its way through (assignment throws
+      // under strict mode, failing the push loudly).
+      Object.freeze(patch.values)
+      await options.validatePush?.({
+        sessionId,
+        events: [],
+        presence: Object.freeze(patch as PushedPresence),
+      })
+    }
+    if (
+      typeof patch.participant !== 'string' ||
+      patch.participant.length === 0
+    ) {
+      throw new TypeError('presence participant must be a non-empty string')
+    }
+    if (RESERVED_PARTICIPANT_IDS.has(patch.participant)) {
+      throw new TypeError(
+        `presence participant must not be '${patch.participant}'`,
+      )
+    }
+    if (
+      patch.at !== undefined &&
+      (typeof patch.at !== 'number' ||
+        !Number.isFinite(patch.at) ||
+        patch.at < 0 ||
+        patch.at > MAX_DATE_MS)
+    ) {
+      throw new TypeError(
+        'presence at must be non-negative epoch milliseconds within the Date range',
+      )
+    }
+    // Validate the whole patch before the adapter sees any of it — a
+    // bad field means nothing is broadcast.
+    const validated: Record<string, unknown> = nullProtoRecord()
+    for (const [field, value] of Object.entries(patch.values)) {
+      if (value === undefined) continue
+      const schema = Object.hasOwn(presenceDefs, field)
+        ? presenceDefs[field]
+        : undefined
+      if (!schema) {
+        throw new A2Error(
+          'UNKNOWN_PRESENCE_FIELD',
+          `contract '${name}' has no presence field '${field}'`,
+        )
+      }
+      if (value === null) {
+        validated[field] = null
+        continue
+      }
+      const result = validateSync(schema, value, `presence field '${field}'`)
+      if (result.issues) {
+        throw new A2Error(
+          'INVALID_PAYLOAD',
+          `invalid value for presence field '${field}' on machine '${name}'`,
+          { details: result.issues },
+        )
+      }
+      validated[field] = result.value
+    }
+    const store = await resolveStore()
+    try {
+      await requirePresence(store).set(
+        nsId(sessionId),
+        patch.participant,
+        validated,
+        {
+          seen: patch.seen ?? fallbackSeen,
+          // The sender's stamp is the LWW order; receipt time is the
+          // fallback for stampless callers (handlers, old wire
+          // clients), where receipt order is sender order — single
+          // writer. Storage anchors expiry on its own clock either way.
+          at: new Date(patch.at ?? Date.now()),
+          ttlMs: presenceTtlMs,
+        },
+      )
+    } catch (err) {
+      throw asStoreUnavailable(err)
+    }
+  }
+
+  const readPresenceMap = async (
+    sessionId: string,
+  ): Promise<PresenceMap<P>> => {
+    const store = await resolveStore()
+    let rows: PresenceRow[]
+    try {
+      rows = await requirePresence(store).read(nsId(sessionId))
+    } catch (err) {
+      throw asStoreUnavailable(err)
+    }
+    return foldPresenceRows(rows) as PresenceMap<P>
+  }
+
+  /**
+   * The two-plane feed. Patches ride `subscribe` when the adapter has
+   * the push tier; without it the map is re-read and diffed whenever
+   * the event feed wakes, and at the poll idle ceiling while it is
+   * silent — degraded means later, not lost while watched.
+   */
+  const streamWithPresence = (
+    id: string,
+    startAfter: number,
+  ): AsyncIterable<ContractEvent<D> | PresencePatch | PresenceSnapshot> => {
+    const ns = nsId(id)
+    const outer = async function* (): AsyncGenerator<
+      ContractEvent<D> | PresencePatch | PresenceSnapshot
+    > {
+      const store = await resolveStore()
+      const api = requirePresence(store)
+
+      const readRows = async (): Promise<PresenceRow[]> => {
+        try {
+          return await api.read(ns)
+        } catch (err) {
+          throw asStoreUnavailable(err)
+        }
+      }
+
+      // What this feed has already painted, per (participant, field) —
+      // the comparison state for re-read diffs.
+      const painted = new Map<
+        string,
+        Map<string, { seen: number; atMs: number; value: string }>
+      >()
+
+      // One patch per (participant, field), never merged — a merged
+      // stamp would let a stale field inherit a fresher sibling's
+      // `seen` and survive the documented frontier reconciliation.
+      const diffRows = (rows: PresenceRow[]): PresencePatch[] => {
+        const patches: PresencePatch[] = []
+        const live = new Map<string, Set<string>>()
+        for (const row of rows) {
+          let liveFields = live.get(row.participant)
+          if (!liveFields) {
+            liveFields = new Set()
+            live.set(row.participant, liveFields)
+          }
+          liveFields.add(row.field)
+          const stamp = {
+            seen: row.seen,
+            atMs: row.at.getTime(),
+            value: fingerprint(row.value),
+          }
+          const prior = painted.get(row.participant)?.get(row.field)
+          if (
+            prior &&
+            prior.seen === stamp.seen &&
+            prior.atMs === stamp.atMs &&
+            prior.value === stamp.value
+          ) {
+            continue
+          }
+          let paintedFields = painted.get(row.participant)
+          if (!paintedFields) {
+            paintedFields = new Map()
+            painted.set(row.participant, paintedFields)
+          }
+          paintedFields.set(row.field, stamp)
+          patches.push({
+            participant: row.participant,
+            values: { [row.field]: row.value },
+            seen: row.seen,
+            at: row.at,
+          })
+        }
+        for (const [participant, fields] of painted) {
+          for (const [field, prior] of fields) {
+            if (live.get(participant)?.has(field)) continue
+            fields.delete(field)
+            patches.push({
+              participant,
+              values: { [field]: null },
+              // A cleared field has no surviving row; its last painted
+              // `seen` and the observation time are the honest stamps.
+              seen: prior.seen,
+              at: new Date(),
+            })
+          }
+          if (fields.size === 0) painted.delete(participant)
+        }
+        return patches
+      }
+
+      const paint = (patch: PresencePatch): void => {
+        let fields = painted.get(patch.participant)
+        for (const [field, value] of Object.entries(patch.values)) {
+          if (value === null || value === undefined) {
+            fields?.delete(field)
+            continue
+          }
+          if (!fields) {
+            fields = new Map()
+            painted.set(patch.participant, fields)
+          }
+          fields.set(field, {
+            seen: patch.seen,
+            atMs: patch.at.getTime(),
+            value: fingerprint(value),
+          })
+        }
+        if (fields?.size === 0) painted.delete(patch.participant)
+      }
+
+      // Arrivals coalesce per (participant, field): latest value wins,
+      // each field keeps its own seen/at stamps (never merged — a stale
+      // field must not inherit a fresher sibling's `seen`), one patch
+      // per (participant, field) on drain. A stalled consumer therefore
+      // holds at most the live presence cardinality, never the arrival
+      // history.
+      const queue = new Map<
+        string,
+        Map<string, { value: unknown; seen: number; at: Date }>
+      >()
+      let wakeQueue: (() => void) | null = null
+      const enqueue = (patch: PresencePatch): void => {
+        for (const [field, value] of Object.entries(patch.values)) {
+          if (value === undefined) continue
+          let fields = queue.get(patch.participant)
+          if (!fields) {
+            fields = new Map()
+            queue.set(patch.participant, fields)
+          }
+          // Per-field LWW in the queue itself: pub/sub delivery order
+          // is not apply order (two instances' PUBLISHes race), and an
+          // unconditional overwrite would let an older patch swallow a
+          // newer queued value that then never reaches the subscriber.
+          // Ties go to the incoming patch, like every other comparator.
+          const queued = fields.get(field)
+          if (queued && queued.at.getTime() > patch.at.getTime()) continue
+          fields.set(field, { value, seen: patch.seen, at: patch.at })
+        }
+        wakeQueue?.()
+      }
+      const dequeue = (): PresencePatch | null => {
+        for (const [participant, fields] of queue) {
+          for (const [field, stamp] of fields) {
+            fields.delete(field)
+            if (fields.size === 0) queue.delete(participant)
+            return {
+              participant,
+              values: { [field]: stamp.value },
+              seen: stamp.seen,
+              at: stamp.at,
+            }
+          }
+          queue.delete(participant)
+        }
+        return null
+      }
+      // Subscribe before the snapshot read: a patch landing between
+      // the two is painted twice, never lost — repaints are idempotent.
+      const unsubscribe = api.subscribe?.(ns, enqueue)
+
+      const events = store.stream(ns, { startAfter })[Symbol.asyncIterator]()
+      let pendingEvent: Promise<IteratorResult<Event>> | null = null
+      try {
+        // Exactly one snapshot before any live item: the pruned map,
+        // per-field stamps exact — a reconnecting client replaces its
+        // foreign entries wholesale from it.
+        const snapshotRows = await readRows()
+        for (const row of snapshotRows) {
+          let fields = painted.get(row.participant)
+          if (!fields) {
+            fields = new Map()
+            painted.set(row.participant, fields)
+          }
+          fields.set(row.field, {
+            seen: row.seen,
+            atMs: row.at.getTime(),
+            value: fingerprint(row.value),
+          })
+        }
+        yield { snapshot: foldPresenceRows(snapshotRows) }
+
+        for (;;) {
+          for (;;) {
+            const patch = dequeue()
+            if (!patch) break
+            paint(patch)
+            yield patch
+          }
+          pendingEvent ??= events.next()
+          let woke: 'event' | 'patch' | 'tick'
+          if (unsubscribe) {
+            const arrival = new Promise<void>((resolve) => {
+              wakeQueue = resolve
+            })
+            woke = await Promise.race([
+              pendingEvent.then(() => 'event' as const),
+              arrival.then(() => 'patch' as const),
+            ])
+            wakeQueue = null
+            if (woke === 'patch') continue
+          } else {
+            const sleeper = defaultSleep(POLL_TIMINGS.idleCeilingMs)
+            woke = await Promise.race([
+              pendingEvent.then(() => 'event' as const),
+              sleeper.promise.then(() => 'tick' as const),
+            ])
+            sleeper.cancel()
+          }
+          if (woke === 'event') {
+            const result = await pendingEvent
+            pendingEvent = null
+            if (result.done) return
+            yield toSessionEvent(id, result.value)
+          }
+          if (!unsubscribe) {
+            for (const patch of diffRows(await readRows())) yield patch
+          }
+        }
+      } finally {
+        wakeQueue = null
+        unsubscribe?.()
+        // The consumer may close while an event read is in flight; its
+        // settlement is no longer anyone's business.
+        pendingEvent?.catch(() => {})
+        await events.return?.()
+      }
+    }
+    return outer()
+  }
+
+  const makeSession = <Append>(
+    id: string,
+    append: Append,
+    trigger: Pick<StoredEvent, 'id' | 'createdAt' | 'index'> | null,
+  ): Session<D, Append, P> =>
+    ({
+      id,
+      append,
+      schedule: makeSchedule(id, trigger),
+      history: async (bounds?: { gte?: number; lte?: number }) =>
+        (await readHistory(id, bounds)).map(toPublic),
+      state: <S>(reducer: Reducer<D, S>) => readState(id, reducer),
+      stream: (opts?: { startAfter?: number; presence?: boolean }) => {
+        const startAfter = opts?.startAfter ?? 0
+        assertStreamIndex(startAfter)
+        return opts?.presence === true
+          ? streamWithPresence(id, startAfter)
+          : streamEvents(id, startAfter)
+      },
+      // Only on presence-declaring contracts — the type surface promises
+      // no runtime-inert members (a2-api.md §12).
+      ...(declaresPresence
+        ? {
+            setPresence: (patch: {
+              participant: string
+              values: Record<string, unknown>
+              seen?: number
+              at?: number
+            }) => setPresence(id, patch, trigger?.index ?? 0),
+            presence: () => readPresenceMap(id),
+          }
+        : {}),
+    }) as Session<D, Append, P>
+
+  // ── drain ────────────────────────────────────────────────────────
+
+  const makeCtx = (
+    trigger: StoredEvent,
+    attempt: number,
+    signal: AbortSignal,
+  ): HandlerContext<D> => {
+    const publicSessionId = stripNs(trigger.sessionId)
+    const append: HandlerAppend<D> = async (appendName, ...events) => {
+      assertAppendName(appendName)
+      const generatedIds = events.map((event) => event.id === undefined)
+      const withIds = await Promise.all(
+        // oxlint-disable-next-line no-map-spread
+        events.map(async (event, item) => {
+          if (event.id !== undefined) return event
+          const id = await deterministicEventId(trigger.id, appendName, item)
+          return { ...event, id }
+        }),
+      )
+      return appendCore(
+        publicSessionId,
+        withIds,
+        'handler',
+        'inline',
+        (_rows, watchdogDueAt) => scheduleDrain(publicSessionId, watchdogDueAt),
+        { index: trigger.index, attempt },
+        generatedIds,
+      )
+    }
+    return {
+      event: toPublic(trigger),
+      attempt,
+      // The handler-scoped `setPresence` stamps `seen` with the
+      // triggering event's index by default — the frontier the handler
+      // provably reflects.
+      session: makeSession(publicSessionId, append, trigger),
+      signal,
+    }
+  }
+
+  const abortHubs = new Map<string, AbortHub>()
+
+  const createAbortHub = (
+    store: A2Store,
+    ns: string,
+    startAfter: number,
+  ): AbortHub => {
+    const hub: AbortHub = {
+      subscriptions: new Set(),
+      seen: new Map(),
+      startAfter,
+      ready: Promise.resolve(),
+      watch: null,
+      error: null,
+      iterator: null,
+      stopped: false,
+    }
+    hub.ready = (async () => {
+      const existing = await store.read(ns, { afterIndex: startAfter })
+      for (const event of existing) dispatchAbortEvent(hub, event)
+      const tail = existing.at(-1)?.index ?? startAfter
+      const feed = store.stream(ns, { startAfter: tail })
+      const iterator = feed[Symbol.asyncIterator]()
+      hub.iterator = iterator
+      hub.watch = (async () => {
+        for (;;) {
+          const { value, done } = await iterator.next()
+          if (done || value === undefined || hub.stopped) return
+          dispatchAbortEvent(hub, value)
+        }
+      })().catch((error: unknown) => {
+        hub.error = error
+      })
+    })().catch((error: unknown) => {
+      hub.error = error
+      if (abortHubs.get(ns) === hub) abortHubs.delete(ns)
+      throw error
+    })
+    abortHubs.set(ns, hub)
+    return hub
+  }
+
+  const subscribeAbort = async (
+    store: A2Store,
+    ns: string,
+    trigger: StoredEvent,
+    abortOn: AbortMatcher,
+    attempt: number,
+  ): Promise<{
+    signal: AbortSignal
+    monitor<T>(operation: Promise<T>): Promise<T>
+    close(): Promise<void>
+  }> => {
+    let hub = abortHubs.get(ns)
+    if (!hub) hub = createAbortHub(store, ns, trigger.index)
+    const activeTypes = new Set<string>()
+    for (const active of hub.subscriptions) {
+      for (const type of active.types) activeTypes.add(type)
+    }
+    const publicTrigger = toPublic(trigger)
+    const subscription: AbortSubscription = {
+      controller: new AbortController(),
+      triggerIndex: trigger.index,
+      types: new Set(abortOn.keys()),
+      matches: (event) => {
+        if (event.index <= trigger.index) return false
+        const matcher = abortOn.get(event.type)
+        if (matcher === undefined) return false
+        return matcher === true
+          ? true
+          : matcher(toPublic(event as StoredEvent), publicTrigger, { attempt })
+      },
+    }
+    hub.subscriptions.add(subscription)
+    const needsCatchup =
+      trigger.index < hub.startAfter ||
+      [...subscription.types].some((type) => !activeTypes.has(type))
+    if (needsCatchup) {
+      const earlier = await store.read(ns, { afterIndex: trigger.index })
+      hub.startAfter = Math.min(hub.startAfter, trigger.index)
+      for (const event of earlier) dispatchAbortEvent(hub, event)
+    }
+    for (const event of hub.seen.values()) {
+      if (subscription.matches(event)) subscription.controller.abort()
+    }
+    await hub.ready
+    if (hub.error !== null) throw hub.error
+    return {
+      signal: subscription.controller.signal,
+      monitor: async <T>(operation: Promise<T>): Promise<T> => {
+        const outcome = await Promise.race([
+          operation.then(
+            (value) => ({ type: 'completed' as const, value }),
+            (error: unknown) => ({ type: 'handler-failed' as const, error }),
+          ),
+          hub.watch!.then(() =>
+            hub.error === null
+              ? { type: 'monitor-closed' as const }
+              : { type: 'monitor-failed' as const, error: hub.error },
+          ),
+        ])
+        if (outcome.type === 'completed') return outcome.value
+        if (outcome.type === 'handler-failed') throw outcome.error
+        if (outcome.type === 'monitor-failed') {
+          for (const active of hub.subscriptions) {
+            active.controller.abort(outcome.error)
+          }
+          await operation.catch(() => {})
+          throw outcome.error
+        }
+        await operation.catch(() => {})
+        throw new Error('abort monitor closed while handlers were active')
+      },
+      close: async () => {
+        hub.subscriptions.delete(subscription)
+        if (hub.subscriptions.size > 0) {
+          pruneAbortHub(hub)
+          return
+        }
+        hub.stopped = true
+        abortHubs.delete(ns)
+        await hub.ready
+        await hub.iterator?.return?.()
+        await hub.watch
+      },
+    }
+  }
+
+  const returnedEvents = async (
+    sessionId: string,
+    trigger: StoredEvent,
+    result: void | AppendInput<D> | readonly AppendInput<D>[],
+  ): Promise<ReturnedEvent[]> => {
+    if (result === undefined) return []
+    const events = Array.isArray(result) ? [...result] : [result]
+    if (events.length === 0) return []
+    const withIds = await Promise.all(
+      // oxlint-disable-next-line oxc/no-map-spread -- handler results remain caller-owned
+      events.map(async (event, item) => {
+        const withId = { ...event }
+        withId.id =
+          event.id ?? (await deterministicReturnedEventId(trigger.id, item))
+        return withId
+      }),
+    )
+    return validateEvents(sessionId, withIds).map((event) =>
+      Object.assign(event, {
+        id: event.id!,
+        cause: {
+          index: trigger.index,
+          attempt: trigger.attemptCount,
+        },
+      }),
+    )
+  }
+
+  type EventStatus =
+    'processed' | 'failed' | 'dead_lettered' | 'superseded' | 'surrendered'
+
+  type EventOutcome = {
+    status: EventStatus
+    opensLane: boolean
+    appendsEvents: boolean
+  }
+
+  const drainSession = (
+    sessionId: string,
+    watchdogDueAt?: number,
+    signal?: DrainSignal,
+  ): Promise<DrainResult> =>
+    telemetry.span(
+      'a2.drain',
+      { 'a2.contract': name, 'a2.session_id': sessionId },
+      async (span) => {
+        const store = await resolveStore()
+        const ns = nsId(sessionId)
+        const holder = crypto.randomUUID()
+        type ActiveEvent = {
+          attempt: number
+          execution: Promise<EventOutcome>
+          supersede: AbortController
+          /** Resolves the tracked execution early once supersession is durable. */
+          fence: (outcome: EventOutcome) => void
+          /** Local lease estimate: request time + ttl — at or before the store's. */
+          expiresAtMs: number
+          lapsed: boolean
+        }
+        const active = new Map<number, ActiveEvent>()
+        const excluded = new Set<number>()
+        let processed = 0
+        let sawFailure = false
+        let schedulerArm: Promise<void> | undefined
+        let heartbeat: ReturnType<typeof setInterval> | null = null
+        let lapseTimer: ReturnType<typeof setTimeout> | null = null
+        let retryTimer: ReturnType<typeof setTimeout> | null = null
+        let renewal: Promise<void> | null = null
+        let stopRenewing = false
+
+        // Self-fencing at local lease lapse: the drain wrote every expiry it
+        // holds (request time + ttl, at or before the store's own stamp), so
+        // it can conclude "assume a successor" with zero I/O — including
+        // while the store is unreachable or in the first tick after a stall.
+        const lapseDue = (): void => {
+          lapseTimer = null
+          const nowMs = Date.now()
+          for (const [index, entry] of active) {
+            if (entry.lapsed || entry.expiresAtMs > nowMs) continue
+            entry.lapsed = true
+            entry.supersede.abort(
+              new A2Error(
+                'CLAIM_EXPIRED',
+                `the claim on event ${index} in session '${sessionId}' lapsed without renewal`,
+              ),
+            )
+          }
+          scheduleLapse()
+        }
+        const scheduleLapse = (): void => {
+          if (lapseTimer) {
+            clearTimeout(lapseTimer)
+            lapseTimer = null
+          }
+          let next = Number.POSITIVE_INFINITY
+          for (const entry of active.values()) {
+            if (!entry.lapsed) next = Math.min(next, entry.expiresAtMs)
+          }
+          if (next === Number.POSITIVE_INFINITY) return
+          lapseTimer = setTimeout(lapseDue, Math.max(0, next - Date.now()))
+          ;(lapseTimer as { unref?: () => void }).unref?.()
+        }
+
+        // A missed beat spends lease slack; the next scheduled beat may be
+        // provably too late. Retry promptly (jittered against fleet-wide
+        // synchronization on a struggling store) while a lease can still be
+        // saved — the lapse ends the retries naturally.
+        const scheduleRenewRetry = (): void => {
+          if (stopRenewing || retryTimer) return
+          const nowMs = Date.now()
+          const saveable = [...active.values()].some(
+            (entry) => !entry.lapsed && entry.expiresAtMs > nowMs,
+          )
+          if (!saveable) return
+          const delay = DRAIN_TIMINGS.renewRetryMs * (0.5 + Math.random() * 0.5)
+          retryTimer = setTimeout(() => {
+            retryTimer = null
+            void renew()
+          }, delay)
+          ;(retryTimer as { unref?: () => void }).unref?.()
+        }
+
+        const alignWatchdogAt = (minimumDueAt: number): number => {
+          if (watchdogDueAt === undefined) return minimumDueAt
+          const beats = Math.max(
+            0,
+            Math.ceil(
+              (minimumDueAt - watchdogDueAt) / DRAIN_TIMINGS.claimHeartbeatMs,
+            ),
+          )
+          return watchdogDueAt + beats * DRAIN_TIMINGS.claimHeartbeatMs
+        }
+
+        const requestWatchdog = (dueAt: number): void => {
+          const arm = startSchedulerArm(sessionId, alignWatchdogAt(dueAt))
+          if (arm) schedulerArm = arm
+        }
+
+        const renew = (): Promise<void> => {
+          if (stopRenewing || renewal || active.size === 0) {
+            return renewal ?? Promise.resolve()
+          }
+          const window = nextClaimWindow()
+          requestWatchdog(window.watchdogAtMs)
+          const claims = [...active.entries()].map(([index, entry]) => ({
+            index,
+            attempt: entry.attempt,
+          }))
+          const operation = store
+            .renewClaims({
+              sessionId: ns,
+              holder,
+              claims,
+              ttlMs: window.ttlMs,
+              ...(window.deadlineCapped
+                ? { expiresAtMs: window.expiresAtMs }
+                : {}),
+            })
+            .then(
+              (result) => {
+                for (const index of result.renewed) {
+                  const entry = active.get(index)
+                  if (entry && !entry.lapsed) {
+                    entry.expiresAtMs = window.expiresAtMs
+                  }
+                }
+                for (const index of result.superseded) {
+                  const entry = active.get(index)
+                  if (!entry) continue
+                  // Idempotent: the local lapse normally aborted this signal
+                  // already — this is the proof, whose job is the release.
+                  entry.supersede.abort(
+                    new A2Error(
+                      'SUPERSEDED_ATTEMPT',
+                      `a newer attempt owns event ${index} in session '${sessionId}'`,
+                    ),
+                  )
+                  entry.fence({
+                    status: 'superseded',
+                    opensLane: false,
+                    appendsEvents: false,
+                  })
+                }
+                if (window.deadlineCapped) stopRenewing = true
+                scheduleLapse()
+                return undefined
+              },
+              () => {
+                scheduleRenewRetry()
+                return undefined
+              },
+            )
+          let tracked!: Promise<void>
+          tracked = operation.finally(() => {
+            if (renewal === tracked) renewal = null
+          })
+          renewal = tracked
+          return tracked
+        }
+
+        const runEvent = async (
+          event: StoredEvent,
+          supersedeSignal: AbortSignal,
+        ): Promise<EventOutcome> => {
+          const registration = handlers.get(event.type)
+          return telemetry.span(
+            'a2.event',
+            {
+              'a2.contract': name,
+              'a2.session_id': sessionId,
+              'a2.event.type': event.type,
+              'a2.event.index': event.index,
+              'a2.event.id': event.id,
+              'a2.event.attempt': event.attemptCount,
+              'a2.event.handled': registration !== undefined,
+              ...(event.lane === null ? {} : { 'a2.event.lane': event.lane }),
+            },
+            async (eventSpan) => {
+              let subscription:
+                | {
+                    signal: AbortSignal
+                    monitor<T>(operation: Promise<T>): Promise<T>
+                    close(): Promise<void>
+                  }
+                | undefined
+              let handlerSignal = supersedeSignal
+              let returned: ReturnedEvent[]
+              try {
+                if (registration?.abortOn) {
+                  subscription = await subscribeAbort(
+                    store,
+                    ns,
+                    event,
+                    registration.abortOn,
+                    event.attemptCount,
+                  )
+                  handlerSignal = AbortSignal.any([
+                    supersedeSignal,
+                    subscription.signal,
+                  ])
+                }
+                const operation = registration?.handler(
+                  makeCtx(event, event.attemptCount, handlerSignal),
+                )
+                const result = operation
+                  ? await (subscription
+                      ? subscription.monitor(operation)
+                      : operation)
+                  : undefined
+                if (subscription) {
+                  await subscription.close()
+                  subscription = undefined
+                }
+                returned = await returnedEvents(sessionId, event, result)
+              } catch (err) {
+                if (supersedeSignal.aborted && err === supersedeSignal.reason) {
+                  // The handler surrendered to its own abort — identity, not
+                  // code, so it cannot arrive from another context. A lapse
+                  // is not a handler failure: no completion, no failure
+                  // budget spent; the claim simply expires and recovery
+                  // retries.
+                  eventSpan.setAttribute('a2.event.outcome', 'surrendered')
+                  return {
+                    status: 'surrendered',
+                    opensLane: false,
+                    appendsEvents: false,
+                  }
+                }
+                // Everything else — including a store fence rejection — is
+                // adjudicated by failAttempt, which is itself fenced: a
+                // genuinely superseded attempt gets 'superseded' back with
+                // no mutation. One adjudicator, not two.
+                eventSpan.recordError(err)
+                const failure = await store.failAttempt({
+                  sessionId: ns,
+                  index: event.index,
+                  attempt: event.attemptCount,
+                  error: describeError(err),
+                  maxFailures: MAX_FAILURES,
+                })
+                eventSpan.setAttribute('a2.event.outcome', failure.outcome)
+                return {
+                  status: failure.outcome,
+                  opensLane: false,
+                  appendsEvents: false,
+                }
+              } finally {
+                await subscription?.close()
+              }
+              await renewal
+              const completion = await store.completeAttempt({
+                sessionId: ns,
+                index: event.index,
+                attempt: event.attemptCount,
+                events: returned,
+              })
+              eventSpan.setAttribute(
+                'a2.event.outcome',
+                completion.outcome === 'completed'
+                  ? 'processed'
+                  : completion.outcome,
+              )
+              if (completion.outcome === 'superseded') {
+                return {
+                  status: 'superseded',
+                  opensLane: false,
+                  appendsEvents: false,
+                }
+              }
+              if (handlerSignal.aborted) {
+                eventSpan.setAttribute('a2.event.aborted', true)
+              }
+              return {
+                status: 'processed',
+                opensLane: event.lane !== null,
+                appendsEvents: returned.length > 0,
+              }
+            },
+          )
+        }
+
+        let claimAgain = false
+
+        const start = (event: StoredEvent, expiresAtMs: number): void => {
+          // Re-claiming an index this drain still tracks is durable proof
+          // that the old attempt lost: our own new claim advanced the
+          // ordinal. Fence the old entry before it can be confused with
+          // the new one.
+          const previous = active.get(event.index)
+          if (previous) {
+            previous.supersede.abort(
+              new A2Error(
+                'SUPERSEDED_ATTEMPT',
+                `a newer attempt owns event ${event.index} in session '${sessionId}'`,
+              ),
+            )
+            previous.fence({
+              status: 'superseded',
+              opensLane: false,
+              appendsEvents: false,
+            })
+          }
+          const supersede = new AbortController()
+          let fence!: (outcome: EventOutcome) => void
+          const fenced = new Promise<EventOutcome>((resolve) => {
+            fence = resolve
+          })
+          // The race lets a durable supersession release this slot while the
+          // zombie handler keeps running — its completion and failure are
+          // fenced by the store, so nothing it does from here is counted.
+          let entry!: ActiveEvent
+          const execution = Promise.race([
+            runEvent(event, supersede.signal),
+            fenced,
+          ]).then((eventOutcome) => {
+            // Identity-guarded: a fenced predecessor's continuation must
+            // not delete the entry of the attempt that replaced it.
+            if (active.get(event.index) === entry) active.delete(event.index)
+            if (eventOutcome.status === 'processed') processed += 1
+            if (eventOutcome.status === 'failed') {
+              excluded.add(event.index)
+              sawFailure = true
+            }
+            claimAgain ||= eventOutcome.opensLane || eventOutcome.appendsEvents
+            return eventOutcome
+          })
+          entry = {
+            attempt: event.attemptCount,
+            execution,
+            supersede,
+            fence,
+            expiresAtMs,
+            lapsed: false,
+          }
+          active.set(event.index, entry)
+          scheduleLapse()
+          if (!heartbeat && !stopRenewing) {
+            heartbeat = setInterval(
+              () => void renew(),
+              DRAIN_TIMINGS.claimHeartbeatMs,
+            )
+            ;(heartbeat as { unref?: () => void }).unref?.()
+          }
+        }
+
+        let outcome: DrainOutcome = 'settled'
+        let shouldClaim = true
+        try {
+          for (;;) {
+            const signalVersion = signal?.version ?? 0
+            let claim: StoreClaimAvailableResult | undefined
+            if (shouldClaim) {
+              const window = nextClaimWindow()
+              claim = await store.claimAvailable({
+                sessionId: ns,
+                holder,
+                ttlMs: window.ttlMs,
+                ...(window.deadlineCapped
+                  ? { expiresAtMs: window.expiresAtMs }
+                  : {}),
+                ...(excluded.size === 0
+                  ? {}
+                  : { excludeIndexes: [...excluded] }),
+              })
+              if (claim.outcome === 'claimed') {
+                requestWatchdog(window.watchdogAtMs)
+                if (window.deadlineCapped) stopRenewing = true
+                for (const event of claim.events) {
+                  start(event, window.expiresAtMs)
+                }
+                shouldClaim = false
+              }
+            }
+            if (active.size > 0) {
+              const wake = signal?.wait(signalVersion)
+              await Promise.race([
+                ...[...active.values()].map((entry) => entry.execution),
+                ...(wake ? [wake.promise] : []),
+              ])
+              wake?.cancel()
+              shouldClaim =
+                claimAgain ||
+                active.size === 0 ||
+                (signal !== undefined && signal.version !== signalVersion)
+              claimAgain = false
+              continue
+            }
+            if (!shouldClaim) {
+              shouldClaim = true
+              continue
+            }
+            if (claim === undefined) continue
+            if (signal && signal.version !== signalVersion) continue
+            if (claim.outcome === 'busy') {
+              requestWatchdog(
+                claim.retryAt.getTime() + DRAIN_TIMINGS.watchdogGraceMs,
+              )
+              outcome = 'busy'
+            } else if (sawFailure) {
+              outcome = 'stalled'
+            }
+            if (signal) signal.closed = true
+            break
+          }
+        } finally {
+          if (signal) signal.closed = true
+          stopRenewing = true
+          if (heartbeat) clearInterval(heartbeat)
+          if (retryTimer) clearTimeout(retryTimer)
+          await renewal
+          await Promise.allSettled(
+            [...active.values()].map((entry) => entry.execution),
+          )
+          if (lapseTimer) clearTimeout(lapseTimer)
+        }
+        span.setAttribute('a2.drain.processed', processed)
+        span.setAttribute('a2.drain.outcome', outcome)
+        return {
+          settled: outcome === 'settled',
+          outcome,
+          processed,
+          ...(schedulerArm ? { schedulerArm } : {}),
+        }
+      },
+    )
+
+  // ── public surface ───────────────────────────────────────────────
+
+  const appendExternal = async (
+    sessionId: string,
+    mode: 'inline' | 'dispatch',
+    events: Array<AppendInput<D> | PushedEvent>,
+    requireDurableInitialArm = false,
+  ): Promise<ContractEvent<D>[]> => {
+    const pushed = events.filter(
+      (event): event is PushedEvent =>
+        Reflect.get(event, '~a2.pushed') === true,
+    )
+    if (pushed.length > 0) {
+      await options.validatePush?.({ sessionId, events: pushed })
+    }
+    return appendCore(
+      sessionId,
+      events as AppendInput<D>[],
+      'external',
+      mode,
+      (_rows, watchdogDueAt) => scheduleDrain(sessionId, watchdogDueAt),
+      undefined,
+      undefined,
+      requireDurableInitialArm,
+    )
+  }
+
+  const self: A2Server<D, P> = {
+    contract: serverContract,
+    session(id) {
+      assertSessionId(id)
+      const appendInline = async (
+        ...events: Array<AppendInput<D> | PushedEvent>
+      ) => appendExternal(id, 'inline', events)
+      const appendDispatch = async (
+        ...events: Array<AppendInput<D> | PushedEvent>
+      ) => appendExternal(id, 'dispatch', events)
+      const append = Object.assign(appendInline, {
+        dispatch: appendDispatch,
+      }) as SessionAppend<D>
+      return makeSession(id, append, null)
+    },
+
+    async drain(sessionId) {
+      assertSessionId(sessionId)
+      const { settled } = await drainSession(sessionId)
+      return { settled }
+    },
+  }
+
+  serverInternals.set(self, {
+    settle: async () => {
+      while (inFlight.size > 0) {
+        await Promise.allSettled(inFlight)
+      }
+    },
+    schedulerDrain: (sessionId, opts) => {
+      assertSessionId(sessionId)
+      return drainSession(sessionId, opts?.watchdogDueAt)
+    },
+    schedulerAppend: async (sessionId, events) => {
+      if (!scheduler) {
+        throw new TypeError(
+          'scheduled append delivery requires a configured scheduler adapter',
+        )
+      }
+      assertSessionId(sessionId)
+      await appendExternal(sessionId, 'inline', [...events], true)
+    },
+  })
+  serverSchedulerBindings.set(self, { scheduler })
+
+  serverInspection.set(self, {
+    async listSessions(inspectionOptions) {
+      const store = await resolveStore()
+      if (!store.inspect) {
+        throw new InspectionUnsupportedError(
+          'this store backend does not support inspection',
+        )
+      }
+      const page = await store.inspect.listSessions({
+        prefix: `${name}${NS}`,
+        limit: inspectionOptions.limit,
+        ...(inspectionOptions.cursor !== undefined
+          ? { cursor: inspectionOptions.cursor }
+          : {}),
+      })
+      return {
+        cursor: page.cursor,
+        // oxlint-disable-next-line oxc/no-map-spread -- inspection results remain adapter-owned
+        sessions: page.sessions.map((session) => {
+          const publicSession = { ...session }
+          publicSession.sessionId = stripNs(session.sessionId)
+          return publicSession
+        }),
+      }
+    },
+    async readSessionPage(sessionId, inspectionOptions) {
+      assertSessionId(sessionId)
+      if (
+        !Number.isSafeInteger(inspectionOptions.afterIndex) ||
+        inspectionOptions.afterIndex < 0 ||
+        !Number.isSafeInteger(inspectionOptions.limit) ||
+        inspectionOptions.limit < 1 ||
+        (inspectionOptions.throughIndex !== undefined &&
+          (!Number.isSafeInteger(inspectionOptions.throughIndex) ||
+            inspectionOptions.throughIndex < 0))
+      ) {
+        throw new TypeError('invalid inspection event page bounds')
+      }
+      const store = await resolveStore()
+      if (!store.inspect) {
+        throw new InspectionUnsupportedError(
+          'this store backend does not support inspection',
+        )
+      }
+      const ns = nsId(sessionId)
+      const snapshots =
+        inspectionOptions.afterIndex === 0
+          ? await store.inspect.listSnapshots(ns)
+          : []
+      const page = store.inspect.readEvents
+        ? await store.inspect.readEvents(ns, inspectionOptions)
+        : await (async () => {
+            const all = await store.read(ns)
+            const currentFrontier = all.at(-1)?.index ?? 0
+            const throughIndex = Math.min(
+              inspectionOptions.throughIndex ?? currentFrontier,
+              currentFrontier,
+            )
+            return {
+              events: all
+                .filter(
+                  (event) =>
+                    event.index > inspectionOptions.afterIndex &&
+                    event.index <= throughIndex,
+                )
+                .slice(0, inspectionOptions.limit),
+              throughIndex,
+            }
+          })()
+      const { events, throughIndex } = page
+      if (
+        !Number.isSafeInteger(throughIndex) ||
+        throughIndex < 0 ||
+        events.length > inspectionOptions.limit ||
+        (inspectionOptions.throughIndex !== undefined &&
+          inspectionOptions.afterIndex > 0 &&
+          throughIndex !== inspectionOptions.throughIndex)
+      ) {
+        throw new A2Error(
+          'STORE_UNAVAILABLE',
+          `inspection event page for session '${sessionId}' has invalid bounds`,
+        )
+      }
+      for (let position = 0; position < events.length; position += 1) {
+        if (
+          events[position]!.index !==
+            inspectionOptions.afterIndex + position + 1 ||
+          events[position]!.index > throughIndex
+        ) {
+          throw new A2Error(
+            'STORE_UNAVAILABLE',
+            `inspection event page for session '${sessionId}' is not contiguous`,
+          )
+        }
+      }
+      if (inspectionOptions.afterIndex < throughIndex && events.length === 0) {
+        throw new A2Error(
+          'STORE_UNAVAILABLE',
+          `inspection event page for session '${sessionId}' ended before index ${throughIndex}`,
+        )
+      }
+      const lastIndex = events.at(-1)?.index ?? inspectionOptions.afterIndex
+      return {
+        // oxlint-disable-next-line oxc/no-map-spread -- inspection results remain adapter-owned
+        events: events.map((event) => {
+          const publicEvent = { ...event }
+          publicEvent.sessionId = sessionId
+          return publicEvent
+        }),
+        snapshots: snapshots.filter(
+          (snapshot) => snapshot.index <= throughIndex,
+        ),
+        throughIndex,
+        nextIndex: lastIndex < throughIndex ? lastIndex : null,
+      }
+    },
+  })
+
+  return self
+}
+
+function assertSessionId(id: string): void {
+  if (typeof id !== 'string' || id.length === 0) {
+    throw new TypeError('session id must be a non-empty string')
+  }
+  if (id.includes(NS)) {
+    throw new TypeError('session id contains a reserved control character')
+  }
+}
+
+function assertHistoryIndex(name: 'gte' | 'lte', value?: number): void {
+  if (value !== undefined && (!Number.isSafeInteger(value) || value < 0)) {
+    throw new TypeError(`history.${name} must be a non-negative safe integer`)
+  }
+}
+
+function assertStreamIndex(value: number): void {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new TypeError('stream.startAfter must be a non-negative safe integer')
+  }
+}
+
+function assertAppendName(name: string): void {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new TypeError('handler append name must be a non-empty string')
+  }
+}
+
+function assertScheduleName(name: string): void {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new TypeError('schedule name must be a non-empty string')
+  }
+}
+
+const SCHEDULE_DELAY = /^(?:0|[1-9]\d*)(?:\.\d+)?(ms|s|m|h|d)$/
+const SCHEDULE_DELAY_MULTIPLIER: Record<'ms' | 's' | 'm' | 'h' | 'd', number> =
+  {
+    ms: 1,
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+  }
+
+function scheduleDueAt(timing: ScheduleTiming, baseTime: number): number {
+  if (timing === null || typeof timing !== 'object' || Array.isArray(timing)) {
+    throw new TypeError(
+      "schedule timing must contain exactly one of 'delay' or 'at'",
+    )
+  }
+  const record = timing as Record<string, unknown>
+  const hasDelay = Object.hasOwn(record, 'delay')
+  const hasAt = Object.hasOwn(record, 'at')
+  if (hasDelay === hasAt) {
+    throw new TypeError(
+      "schedule timing must contain exactly one of 'delay' or 'at'",
+    )
+  }
+
+  let dueAt: number
+  if (hasAt) {
+    const at = record['at']
+    if (!(at instanceof Date) || !Number.isFinite(at.getTime())) {
+      throw new TypeError('schedule at must be a valid Date')
+    }
+    dueAt = at.getTime()
+  } else {
+    const delay = record['delay']
+    if (typeof delay !== 'string') {
+      throw new TypeError(
+        "schedule delay must use ms, s, m, h, or d (for example '30s')",
+      )
+    }
+    const match = SCHEDULE_DELAY.exec(delay)
+    const amount = match ? Number(delay.slice(0, -match[1]!.length)) : NaN
+    if (!match || !Number.isFinite(amount) || amount <= 0) {
+      throw new TypeError(
+        "schedule delay must be positive and use ms, s, m, h, or d (for example '30s')",
+      )
+    }
+    dueAt =
+      baseTime +
+      amount *
+        SCHEDULE_DELAY_MULTIPLIER[
+          match[1] as keyof typeof SCHEDULE_DELAY_MULTIPLIER
+        ]
+  }
+  if (!Number.isFinite(dueAt)) {
+    throw new TypeError('schedule due time must be a finite epoch time')
+  }
+  return dueAt
+}
+
+function assertScheduledPayload(payload: unknown): void {
+  try {
+    if (isJsonValue(payload, new WeakSet())) return
+  } catch {
+    // Proxies and hostile accessors are not stable transport values either.
+  }
+  throw new TypeError(
+    'session.schedule event payload must be JSON-serializable',
+  )
+}
+
+function cloneScheduledPayload(payload: unknown): unknown {
+  assertScheduledPayload(payload)
+  try {
+    const cloned = structuredClone(payload)
+    const encoded = JSON.stringify(cloned)
+    if (encoded === undefined) throw new TypeError()
+    return JSON.parse(encoded) as unknown
+  } catch {
+    throw new TypeError(
+      'session.schedule event payload must be JSON-serializable',
+    )
+  }
+}
+
+function isJsonValue(value: unknown, ancestors: WeakSet<object>): boolean {
+  if (value === null) return true
+  if (typeof value === 'string' || typeof value === 'boolean') return true
+  if (typeof value === 'number') {
+    return Number.isFinite(value) && !Object.is(value, -0)
+  }
+  if (typeof value !== 'object') return false
+  if (ancestors.has(value)) return false
+  ancestors.add(value)
+  try {
+    if (Array.isArray(value)) {
+      const keys = Reflect.ownKeys(value)
+      if (keys.length !== value.length + 1 || !keys.includes('length')) {
+        return false
+      }
+      for (let index = 0; index < value.length; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index))
+        if (
+          !descriptor ||
+          !descriptor.enumerable ||
+          !('value' in descriptor) ||
+          !isJsonValue(descriptor.value, ancestors)
+        ) {
+          return false
+        }
+      }
+      return true
+    }
+    const prototype = Object.getPrototypeOf(value)
+    if (prototype !== Object.prototype) return false
+    for (const key of Reflect.ownKeys(value)) {
+      if (typeof key !== 'string') return false
+      const descriptor = Object.getOwnPropertyDescriptor(value, key)
+      if (
+        !descriptor ||
+        !descriptor.enumerable ||
+        !('value' in descriptor) ||
+        !isJsonValue(descriptor.value, ancestors)
+      ) {
+        return false
+      }
+    }
+    return true
+  } finally {
+    ancestors.delete(value)
+  }
+}
+
+function cloneInitial<S>(initial: S): S {
+  // Defensive: a reducer that mutates state in place must not corrupt
+  // the shared initialState across folds. Fall back to the original for
+  // non-cloneable values (functions, class instances).
+  try {
+    return structuredClone(initial)
+  } catch {
+    return initial
+  }
+}
+
+// Server-side types users need when passing custom stores or building
+// transports — re-exported so experimental-a2/server is self-sufficient.
+export type {
+  A2Store,
+  A2StoreInspection,
+  AppendEvent,
+  Clock,
+  Event,
+  EventCause,
+  FailAttemptResult,
+  IdSource,
+  StoreAppendResult,
+  StoreClaimAvailableResult,
+  StoreStateRead,
+  PresenceRow,
+  StoredEvent,
+  StoredSessionPage,
+  StoredSessionSummary,
+  StoredSnapshot,
+} from './store.ts'
+export type {
+  ScheduledEvent,
+  SchedulerAppendTask,
+  SchedulerDrainTask,
+  SchedulerTask,
+} from './scheduler-task.ts'
+export type {
+  AppendInput,
+  Contract,
+  ContractEvent,
+  EventDefs,
+  PresenceDefs,
+  PresenceMap,
+  PresencePatch,
+  PresenceSnapshot,
+} from './contract.ts'