experimental-a2 0.6.0 → 0.8.0

package/src/server.ts

@@ -28,11 +28,9 @@ import {
   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,
@@ -40,12 +38,21 @@ import type {
   Event,
   EventCause,
   StoreClaimAvailableResult,
+  StoreSnapshotWrite,
   StoreStateRead,
   PresenceRow,
   ReturnedEvent,
   StoredEvent,
 } from './store.ts'
 import type { Reducer } from './reducer.ts'
+import {
+  createServerFetch,
+  type A2Operation,
+  type A2PushEvent,
+  type A2PushPresence,
+  type ServerFetchOptions,
+  type UpgradeWebSocket,
+} from './server-fetch.ts'
 import { validateSync } from './validate.ts'
 import {
   deterministicEventId,
@@ -66,45 +73,6 @@ import {
   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,
@@ -142,11 +110,9 @@ export type Lane<
   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 SessionDispatch<D extends EventDefs> = (
+  ...events: AppendInput<D>[]
+) => Promise<ContractEvent<D>[]>
 
 export type SessionAppend<D extends EventDefs> = SessionDispatch<D> & {
   /** Commit, then hand pending work directly to configured scheduler. */
@@ -169,6 +135,10 @@ export type SessionSchedule<D extends EventDefs> = (
   ...events: AppendInput<D>[]
 ) => Promise<void>
 
+export type StateOptions = {
+  through?: number | 'latest'
+}
+
 /**
  * The presence members of a session — intersected in via
  * `WithPresence`, so they exist exactly when the contract declares
@@ -192,16 +162,12 @@ export type SessionPresence<D extends EventDefs, P extends PresenceDefs> = {
    * 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>
+  setPresence(patch: {
+    participant: string
+    values: PresencePatch<P>['values']
+    seen?: number
+    at?: number
+  }): Promise<void>
   /** The current map, expired values pruned — a point-in-time read. */
   presence(): Promise<PresenceMap<P>>
 }
@@ -216,11 +182,13 @@ export type Session<
   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 }>
+  state<S>(
+    reducer: Reducer<D, S>,
+    options?: StateOptions,
+  ): 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.
+   * (exclusive). Server-side only. `server.fetch` exposes it over SSE.
    */
   stream(opts?: { startAfter?: number }): AsyncIterable<ContractEvent<D>>
 }
@@ -255,6 +223,10 @@ export type A2Server<
 > = {
   /** The contract this server implements. */
   readonly contract: Contract<D, P>
+  readonly fetch: {
+    (request: Request): Promise<Response>
+    (request: Request, options: ServerFetchOptions<D, P>): Promise<Response>
+  }
   session(id: string): Session<D, SessionAppend<D>, P>
   /**
    * Process every currently eligible event. `settled` means nothing
@@ -263,6 +235,15 @@ export type A2Server<
   drain(sessionId: string): Promise<{ settled: boolean }>
 }
 
+export type {
+  A2Operation,
+  A2PushEvent,
+  A2PushPresence,
+  ServerFetchOptions,
+  UpgradeWebSocket,
+}
+export type { A2Socket } from './session-socket.ts'
+
 /**
  * Deliver one authenticated scheduler append through an A2 server's ordinary
  * top-level append path. Custom scheduler adapters call this after validating
@@ -336,8 +317,6 @@ export type ServerOptions<
   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
@@ -994,26 +973,85 @@ export function createServer<
     store: A2Store,
     sessionId: string,
     reducerName: string,
+    throughIndex?: number,
+    snapshotThroughIndex?: number,
   ): Promise<StoreStateRead> => {
     try {
-      return await store.readState(nsId(sessionId), reducerName)
+      return await store.readState(
+        nsId(sessionId),
+        reducerName,
+        throughIndex === undefined && snapshotThroughIndex === undefined
+          ? undefined
+          : {
+              ...(throughIndex === undefined ? {} : { throughIndex }),
+              ...(snapshotThroughIndex === undefined
+                ? {}
+                : { snapshotThroughIndex }),
+            },
+      )
     } catch {
       try {
-        return { snapshot: null, events: await store.read(nsId(sessionId)) }
+        return {
+          headIndex: null,
+          snapshot: null,
+          events: await store.read(
+            nsId(sessionId),
+            throughIndex === undefined ? undefined : { throughIndex },
+          ),
+        }
       } catch (err) {
         throw asStoreUnavailable(err)
       }
     }
   }
 
+  type PendingStateRead = {
+    sessionId: string
+    throughIndex?: number
+    pinEventIndex?: number
+    span: A2SpanHandle
+    resolve: (result: { state: unknown; index: number }) => void
+    reject: (reason: unknown) => void
+  }
+
+  type StateReadPlan = {
+    sessionId: string
+    entries: PendingStateRead[]
+    throughIndex?: number
+    snapshotThroughIndex?: number
+  }
+
+  const planStateReads = (batch: PendingStateRead[]): StateReadPlan[] => {
+    const bySession = new Map<string, PendingStateRead[]>()
+    for (const entry of batch) {
+      const entries = bySession.get(entry.sessionId)
+      if (entries) entries.push(entry)
+      else bySession.set(entry.sessionId, [entry])
+    }
+    const plans: StateReadPlan[] = []
+    for (const [sessionId, entries] of bySession) {
+      const boundaries = entries.flatMap((entry) =>
+        entry.throughIndex === undefined ? [] : [entry.throughIndex],
+      )
+      const plan: StateReadPlan = { sessionId, entries }
+      if (boundaries.length === entries.length) {
+        plan.throughIndex = Math.max(...boundaries)
+      }
+      if (boundaries.length > 0) {
+        plan.snapshotThroughIndex = Math.min(...boundaries)
+      }
+      plans.push(plan)
+    }
+    return plans
+  }
+
   // The cache is untrusted: schema rejection refolds from the raw store.
-  const foldStateRead = async <S>(
+  const foldStatePlan = async (
     store: A2Store,
-    sessionId: string,
-    reducer: Reducer<D, S>,
+    reducer: Reducer<D, unknown>,
+    plan: StateReadPlan,
     stateRead: StoreStateRead,
-    span: A2SpanHandle,
-  ): Promise<{ state: S; index: number; folded: number }> => {
+  ): Promise<void> => {
     let state = cloneInitial(reducer.initialState)
     let index = 0
     let snapshotOutcome = 'miss'
@@ -1029,44 +1067,101 @@ export function createServer<
         if (result.issues) {
           snapshotOutcome = 'rejected'
         } else {
-          state = result.value as S
+          state = result.value
           index = snap.index
           snapshotOutcome = 'hit'
         }
       } else {
-        state = snap.state as S
+        state = snap.state
         index = snap.index
         snapshotOutcome = 'hit'
       }
     }
-    span.setAttribute('a2.state.snapshot', snapshotOutcome)
-
     if (snapshotOutcome === 'rejected') {
       try {
-        rows = await store.read(nsId(sessionId))
+        rows = await store.read(
+          nsId(plan.sessionId),
+          plan.throughIndex === undefined
+            ? undefined
+            : { throughIndex: plan.throughIndex },
+        )
       } catch (err) {
         throw asStoreUnavailable(err)
       }
     }
-    for (const row of rows) {
-      state = reducer.fold(state, toPublic(row) as never)
-      index = row.index
+    const ordered = plan.entries.toSorted(
+      (a, b) =>
+        (a.throughIndex ?? Number.POSITIVE_INFINITY) -
+        (b.throughIndex ?? Number.POSITIVE_INFINITY),
+    )
+    const writes = new Map<
+      number,
+      { state: unknown; pinEventIndexes: Set<number> }
+    >()
+    let rowPosition = 0
+    for (const entry of ordered) {
+      const target = entry.throughIndex ?? Number.POSITIVE_INFINITY
+      while (rowPosition < rows.length && rows[rowPosition]!.index <= target) {
+        const row = rows[rowPosition]!
+        state = reducer.fold(state, toPublic(row) as never)
+        index = row.index
+        rowPosition += 1
+      }
+      const resultState = cloneInitial(state)
+      const folded = rowPosition
+      entry.span.setAttribute('a2.state.snapshot', snapshotOutcome)
+      entry.span.setAttribute('a2.state.folded', folded)
+      entry.span.setAttribute('a2.state.index', index)
+      if (index > 0 && (folded > 0 || entry.pinEventIndex !== undefined)) {
+        const advancesHead =
+          stateRead.headIndex === null || index > stateRead.headIndex
+        const repairsHead =
+          snapshotOutcome === 'rejected' && index === stateRead.headIndex
+        if (
+          !advancesHead &&
+          !repairsHead &&
+          entry.pinEventIndex === undefined
+        ) {
+          entry.resolve({ state: resultState, index })
+          continue
+        }
+        let write = writes.get(index)
+        if (!write) {
+          write = {
+            state: cloneInitial(resultState),
+            pinEventIndexes: new Set(),
+          }
+          writes.set(index, write)
+        }
+        if (entry.pinEventIndex !== undefined) {
+          write.pinEventIndexes.add(entry.pinEventIndex)
+        }
+      }
+      entry.resolve({ state: resultState, index })
+    }
+    if (writes.size > 0) {
+      const snapshots: StoreSnapshotWrite[] = []
+      for (const [snapshotIndex, write] of writes) {
+        const snapshot: StoreSnapshotWrite = {
+          index: snapshotIndex,
+          state: write.state,
+        }
+        if (write.pinEventIndexes.size > 0) {
+          snapshot.pinEventIndexes = [...write.pinEventIndexes]
+        }
+        snapshots.push(snapshot)
+      }
+      const persistence = Promise.resolve()
+        .then(() =>
+          store.putSnapshots(nsId(plan.sessionId), reducer.name, snapshots),
+        )
+        .catch(() => {})
+      track(persistence)
+      platformWaitUntil(persistence)
     }
-    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
@@ -1074,40 +1169,62 @@ export function createServer<
   // synchronously throwing adapter or a read structuredClone rejects.
   const flushStateReads = async (
     store: A2Store,
-    reducerName: string,
+    reducer: Reducer<D, unknown>,
     batch: PendingStateRead[],
   ): Promise<void> => {
+    const plans = planStateReads(batch)
     let reads: StoreStateRead[] | null
     try {
       reads = store.readStates
         ? await store.readStates(
-            batch.map((entry) => nsId(entry.sessionId)),
-            reducerName,
+            plans.map((plan) => ({
+              sessionId: nsId(plan.sessionId),
+              ...(plan.throughIndex === undefined
+                ? {}
+                : { throughIndex: plan.throughIndex }),
+              ...(plan.snapshotThroughIndex === undefined
+                ? {}
+                : { snapshotThroughIndex: plan.snapshotThroughIndex }),
+            })),
+            reducer.name,
+          )
+        : await Promise.all(
+            plans.map((plan) =>
+              readCachedState(
+                store,
+                plan.sessionId,
+                reducer.name,
+                plan.throughIndex,
+                plan.snapshotThroughIndex,
+              ),
+            ),
           )
-        : 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))
+    if (!reads || reads.length !== plans.length) {
+      try {
+        reads = await Promise.all(
+          plans.map((plan) =>
+            readCachedState(
+              store,
+              plan.sessionId,
+              reducer.name,
+              plan.throughIndex,
+              plan.snapshotThroughIndex,
+            ),
+          ),
+        )
+      } catch (err) {
+        for (const entry of batch) entry.reject(err)
+        return
       }
-      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)
+    for (const [position, plan] of plans.entries()) {
       try {
-        const read = reads[position]!
-        entry.resolve(shared ? structuredClone(read) : read)
-      } catch {
-        entry.resolve(readCachedState(store, entry.sessionId, reducerName))
+        await foldStatePlan(store, reducer, plan, reads[position]!)
+      } catch (err) {
+        for (const entry of plan.entries) entry.reject(err)
       }
     }
   }
@@ -1115,9 +1232,13 @@ export function createServer<
   const enqueueStateRead = (
     store: A2Store,
     sessionId: string,
-    reducerName: string,
-  ): Promise<StoreStateRead> =>
-    new Promise((resolve) => {
+    reducer: Reducer<D, unknown>,
+    throughIndex?: number,
+    pinEventIndex?: number,
+    span?: A2SpanHandle,
+  ): Promise<{ state: unknown; index: number }> =>
+    new Promise((resolve, reject) => {
+      const reducerName = reducer.name
       let batch = pendingStateReads.get(reducerName)
       if (!batch) {
         const opened: PendingStateRead[] = []
@@ -1133,16 +1254,25 @@ export function createServer<
         // the last. A deeper-staggered caller just opens the next batch.
         queueMicrotask(() => {
           pendingStateReads.delete(reducerName)
-          void flushStateReads(store, reducerName, opened)
+          void flushStateReads(store, reducer, opened)
         })
         batch = opened
       }
-      batch.push({ sessionId, resolve })
+      batch.push({
+        sessionId,
+        ...(throughIndex === undefined ? {} : { throughIndex }),
+        ...(pinEventIndex === undefined ? {} : { pinEventIndex }),
+        span: span!,
+        resolve,
+        reject,
+      })
     })
 
   const readState = async <S>(
     sessionId: string,
     reducer: Reducer<D, S>,
+    throughIndex?: number,
+    pinEventIndex?: number,
   ): Promise<{ state: S; index: number }> => {
     const store = await resolveStore()
     return telemetry.span(
@@ -1152,36 +1282,15 @@ export function createServer<
         '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(
+      (span) =>
+        enqueueStateRead(
           store,
           sessionId,
-          reducer,
-          stateRead,
+          reducer as Reducer<D, unknown>,
+          throughIndex,
+          pinEventIndex,
           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 }
-      },
+        ) as Promise<{ state: S; index: number }>,
     )
   }
 
@@ -1205,11 +1314,11 @@ export function createServer<
       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 snapshottedEvents = events.map((event, index) =>
+        event.id === undefined
+          ? { type: event.type, payload: payloads[index] }
+          : { type: event.type, payload: payloads[index], id: event.id },
+      ) as AppendInput<D>[]
       const validated = validateEvents(
         sessionId,
         structuredClone(snapshottedEvents),
@@ -1295,22 +1404,6 @@ export function createServer<
     },
     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
@@ -1636,7 +1729,18 @@ export function createServer<
       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),
+      state: <S>(reducer: Reducer<D, S>, stateOptions?: StateOptions) => {
+        const through = stateOptions?.through ?? trigger?.index
+        if (through !== undefined && through !== 'latest') {
+          assertStateIndex(through)
+        }
+        return readState(
+          id,
+          reducer,
+          through === 'latest' ? undefined : through,
+          trigger && through !== 'latest' ? trigger.index : undefined,
+        )
+      },
       stream: (opts?: { startAfter?: number; presence?: boolean }) => {
         const startAfter = opts?.startAfter ?? 0
         assertStreamIndex(startAfter)
@@ -2240,16 +2344,38 @@ export function createServer<
                 shouldClaim = false
               }
             }
+            if (
+              claim?.outcome === 'claimed' &&
+              [...active.values()].some((entry) => entry.lapsed)
+            ) {
+              shouldClaim = true
+              continue
+            }
             if (active.size > 0) {
               const wake = signal?.wait(signalVersion)
-              await Promise.race([
-                ...[...active.values()].map((entry) => entry.execution),
-                ...(wake ? [wake.promise] : []),
+              const hasLapsed = [...active.values()].some(
+                (entry) => entry.lapsed,
+              )
+              const retry =
+                claim?.outcome === 'busy' && hasLapsed
+                  ? defaultSleep(
+                      Math.max(0, claim.retryAt.getTime() - Date.now()),
+                    )
+                  : undefined
+              const retryDue = await Promise.race([
+                ...[...active.values()].map((entry) =>
+                  entry.execution.then(() => false),
+                ),
+                ...(wake ? [wake.promise.then(() => false)] : []),
+                ...(retry ? [retry.promise.then(() => true)] : []),
               ])
               wake?.cancel()
+              retry?.cancel()
               shouldClaim =
+                retryDue ||
                 claimAgain ||
                 active.size === 0 ||
+                hasLapsed ||
                 (signal !== undefined && signal.version !== signalVersion)
               claimAgain = false
               continue
@@ -2298,19 +2424,12 @@ export function createServer<
   const appendExternal = async (
     sessionId: string,
     mode: 'inline' | 'dispatch',
-    events: Array<AppendInput<D> | PushedEvent>,
+    events: AppendInput<D>[],
     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>[],
+      events,
       'external',
       mode,
       (_rows, watchdogDueAt) => scheduleDrain(sessionId, watchdogDueAt),
@@ -2320,21 +2439,23 @@ export function createServer<
     )
   }
 
+  const session = (id: string): Session<D, SessionAppend<D>, P> => {
+    assertSessionId(id)
+    const appendInline = async (...events: AppendInput<D>[]) =>
+      appendExternal(id, 'inline', events)
+    const appendDispatch = async (...events: AppendInput<D>[]) =>
+      appendExternal(id, 'dispatch', events)
+    const append = Object.assign(appendInline, {
+      dispatch: appendDispatch,
+    }) as SessionAppend<D>
+    return makeSession(id, append, null)
+  }
+
+  const fetch = createServerFetch({ contract: serverContract, session })
   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)
-    },
+    fetch,
+    session,
 
     async drain(sessionId) {
       assertSessionId(sessionId)
@@ -2363,126 +2484,6 @@ export function createServer<
       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
 }
 
@@ -2507,6 +2508,12 @@ function assertStreamIndex(value: number): void {
   }
 }
 
+function assertStateIndex(value: number): void {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new TypeError('state.through 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')
@@ -2666,7 +2673,6 @@ function cloneInitial<S>(initial: S): S {
 // transports — re-exported so experimental-a2/server is self-sufficient.
 export type {
   A2Store,
-  A2StoreInspection,
   AppendEvent,
   Clock,
   Event,
@@ -2678,9 +2684,6 @@ export type {
   StoreStateRead,
   PresenceRow,
   StoredEvent,
-  StoredSessionPage,
-  StoredSessionSummary,
-  StoredSnapshot,
 } from './store.ts'
 export type {
   ScheduledEvent,