experimental-a2 0.16.1 → 0.17.0

package/src/server.ts

@@ -1,3 +1,4 @@
+import { decodeState, encodeState } from './reducer-runtime.ts'
 // oxlint-disable no-await-in-loop -- scheduler advances after durable outcomes
 /**
  * experimental-a2/server — where a contract is implemented. `createServer({
@@ -25,27 +26,52 @@ import {
   POLL_TIMINGS,
   MAX_DATE_MS,
   RESERVED_PARTICIPANT_IDS,
+  STATE_CACHE,
   markSchedulerSendFailure,
+  stateTailReaders,
   nullProtoRecord,
   serverInternals,
   type DrainOutcome,
   type DrainResult,
 } from './internal.ts'
+import {
+  isSessionCleared,
+  sessionClearedError,
+  type SessionCleared,
+} from './session-clear.ts'
+import { boundedCache } from './bounded-cache.ts'
 import { defaultSleep, type Sleeper } from './store-polling.ts'
 import { createStreamActivity, streamActivities } from './stream-activity.ts'
+import {
+  bufferedEvents,
+  isSerializedEvent,
+  takeBuffered,
+} from './stream-buffer.ts'
 import type {
   A2Store,
   AppendEvent,
   Event,
   EventCause,
   StoreClaimAvailableResult,
+  StoreClearResult,
+  StoreReclaimResult,
   StoreSnapshotWrite,
   StoreStateRead,
   PresenceRow,
   ReturnedEvent,
   StoredEvent,
 } from './store.ts'
-import type { Reducer } from './reducer.ts'
+import {
+  cloneInitial,
+  foldEvent,
+  type Reducer,
+  type RegisteredReducer,
+} from './reducer.ts'
+type PublicState<R> = undefined extends R
+  ? never
+  : R extends { initialState: infer S }
+    ? S
+    : never
 import {
   createServerFetch,
   type A2Operation,
@@ -59,6 +85,7 @@ import {
   deterministicEventId,
   deterministicReturnedEventId,
   deterministicScheduledEventId,
+  deterministicScheduleClearId,
   deterministicScheduleId,
 } from './deterministic-id.ts'
 import { invocationDeadlineMs, platformWaitUntil } from './platform.ts'
@@ -66,6 +93,7 @@ import { retryableLazy } from './retryable-lazy.ts'
 import type {
   ScheduledEvent,
   SchedulerAppendTask,
+  SchedulerClearTask,
   SchedulerTask,
 } from './scheduler-task.ts'
 import {
@@ -79,13 +107,14 @@ export type HandlerContext<
   D extends EventDefs,
   K extends keyof D & string = keyof D & string,
   P extends PresenceDefs = Record<never, never>,
+  S = 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>
+  session: Session<D, HandlerAppend<D>, P, S>
   /** Fires on `abortOn` events (cancellation slice); dormant otherwise. */
   signal: AbortSignal
 }
@@ -94,8 +123,9 @@ export type Handler<
   D extends EventDefs,
   K extends keyof D & string = keyof D & string,
   P extends PresenceDefs = Record<never, never>,
+  S = never,
 > = (
-  ctx: HandlerContext<D, K, P>,
+  ctx: HandlerContext<D, K, P, S>,
 ) => Promise<void | AppendInput<D> | readonly AppendInput<D>[]>
 
 export type LaneContext<
@@ -130,16 +160,34 @@ 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>
+export type SessionSchedule<D extends EventDefs> = {
+  (
+    name: string,
+    timing: ScheduleTiming,
+    ...events: AppendInput<D>[]
+  ): Promise<void>
+  /**
+   * Publish a durable conditional clear. Delivery clears only while
+   * `ifLastIndex` is still the head, and finishes deleting before it
+   * acknowledges.
+   */
+  clear(
+    name: string,
+    options: ScheduleTiming & { ifLastIndex: number },
+  ): Promise<void>
+}
 
 export type StateOptions = {
   through?: number | 'latest'
 }
 
+export type SessionClearOptions = {
+  /** Clear only while this is the head; a mismatch changes nothing. */
+  ifLastIndex?: number
+}
+
+export type SessionClearResult = { cleared: boolean; index: number }
+
 /**
  * The presence members of a session — intersected in via
  * `WithPresence`, so they exist exactly when the contract declares
@@ -156,7 +204,9 @@ export type SessionPresence<D extends EventDefs, P extends PresenceDefs> = {
   stream(opts: {
     startAfter?: number
     presence: true
-  }): AsyncIterable<ContractEvent<D> | PresencePatch<P> | PresenceSnapshot<P>>
+  }): AsyncIterable<
+    ContractEvent<D> | SessionCleared | 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`
@@ -178,20 +228,33 @@ export type Session<
   D extends EventDefs,
   Append = SessionAppend<D>,
   P extends PresenceDefs = Record<never, never>,
+  S = never,
 > = WithPresence<P, SessionPresence<D, P>> & {
   readonly id: string
   append: Append
   schedule: SessionSchedule<D>
+  /**
+   * End the current lifetime: atomically append a clear marker, then
+   * delete the history below it. Indexes never restart.
+   */
+  clear(options?: SessionClearOptions): Promise<SessionClearResult>
   history(options?: { gte?: number; lte?: number }): Promise<ContractEvent<D>[]>
-  state<S, V = S>(
-    reducer: Reducer<D, S, Record<never, never>, V>,
-    options?: StateOptions,
-  ): Promise<{ state: S; index: number }>
+  state: {
+    <T>(
+      reducer: Reducer<D, T, Record<never, never>>,
+      options?: StateOptions,
+    ): Promise<{ state: T; index: number; clearIndex?: number }>
+  } & ([S] extends [never]
+    ? unknown
+    : { (): Promise<{ state: S; index: number; clearIndex?: number }> })
   /**
    * A live feed of this session's events, starting after `startAfter`
    * (exclusive). Server-side only. `server.fetch` exposes it over SSE.
+   * A clear arrives as a `SessionCleared` marker.
    */
-  stream(opts?: { startAfter?: number }): AsyncIterable<ContractEvent<D>>
+  stream(opts?: {
+    startAfter?: number
+  }): AsyncIterable<ContractEvent<D> | SessionCleared>
 }
 
 /**
@@ -221,14 +284,16 @@ export type A2Scheduler = {
 export type A2Server<
   D extends EventDefs,
   P extends PresenceDefs = Record<never, never>,
+  R extends RegisteredReducer<D, P> | undefined =
+    RegisteredReducer<D, P> | undefined,
 > = {
   /** The contract this server implements. */
-  readonly contract: Contract<D, P>
+  readonly contract: Contract<D, P, R>
   readonly fetch: {
     (request: Request): Promise<Response>
     (request: Request, options: ServerFetchOptions<D, P>): Promise<Response>
   }
-  session(id: string): Session<D, SessionAppend<D>, P>
+  session(id: string): Session<D, SessionAppend<D>, P, PublicState<R>>
   /**
    * Process every currently eligible event. `settled` means nothing
    * actionable remains, including work blocked behind a dead letter.
@@ -259,13 +324,58 @@ export async function deliverSchedulerAppend(
       `a2 scheduler: append task for contract '${task.contract}' cannot be delivered to '${server.contract.name}'`,
     )
   }
+  const { originIndex } = task
+  // A malformed origin would read as cleared and drop the events silently.
+  if (
+    originIndex !== undefined &&
+    (!Number.isSafeInteger(originIndex) || originIndex < 1)
+  ) {
+    throw new TypeError(
+      'a2 scheduler: append task originIndex must be a positive safe integer',
+    )
+  }
   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)
+  await internals.schedulerAppend(task.sessionId, task.events, originIndex)
+}
+
+/**
+ * Deliver one authenticated scheduler clear: a conditional
+ * `clear({ ifLastIndex })` that resolves after its deletion finishes, so a
+ * provider retry resumes an interrupted deletion. Custom scheduler adapters
+ * call this after validating their transport envelope; application code uses
+ * `session.schedule.clear`.
+ */
+export async function deliverSchedulerClear(
+  server: DrainableServer,
+  task: SchedulerClearTask,
+): Promise<void> {
+  if (server.contract.name !== task.contract) {
+    throw new TypeError(
+      `a2 scheduler: clear task for contract '${task.contract}' cannot be delivered to '${server.contract.name}'`,
+    )
+  }
+  // Without its condition a clear task would erase the whole session.
+  if (
+    task.kind !== 'clear' ||
+    !Number.isSafeInteger(task.ifLastIndex) ||
+    task.ifLastIndex < 0
+  ) {
+    throw new TypeError(
+      'a2 scheduler: a clear task needs kind "clear" and a non-negative safe integer ifLastIndex',
+    )
+  }
+  const internals = serverInternals.get(server)
+  if (!internals) {
+    throw new TypeError(
+      `a2 scheduler: server for contract '${task.contract}' cannot receive scheduled clears`,
+    )
+  }
+  await internals.schedulerClear(task.sessionId, task.ifLastIndex)
 }
 
 /**
@@ -292,13 +402,14 @@ export type HandlerEntry<
   D extends EventDefs,
   K extends keyof D & string = keyof D & string,
   P extends PresenceDefs = Record<never, never>,
+  S = never,
 > =
-  | Handler<D, K, P>
+  | Handler<D, K, P, S>
   | {
       abortOn?: AbortSpec<D, K>
       /** Session-scoped FIFO key, resolved and persisted when the event lands. */
       lane?: Lane<D, K>
-      handler: Handler<D, K, P>
+      handler: Handler<D, K, P, S>
     }
 
 type HandlerFunction = (ctx: never) => Promise<unknown>
@@ -315,9 +426,11 @@ export function handler(
 export type ServerOptions<
   D extends EventDefs,
   P extends PresenceDefs = Record<never, never>,
+  R extends RegisteredReducer<D, P> | undefined =
+    RegisteredReducer<D, P> | undefined,
 > = {
   /** The contract this server implements (see `a2.contract`). */
-  contract: Contract<D, P>
+  contract: Contract<D, P, R>
   /** Where events live. Defaults: sqlite in dev, memory in tests, required in prod. */
   store?: A2Store
   /**
@@ -341,11 +454,31 @@ export type ServerOptions<
    * 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> }
+  handlers?: { [K in keyof D & string]?: HandlerEntry<D, K, P, PublicState<R>> }
 }
 
 const MAX_FAILURES = 10
 
+/** Abort a lost attempt's handler and release its drain slot. */
+function endSuperseded(
+  entry: {
+    supersede: AbortController
+    fence: (outcome: {
+      status: 'superseded'
+      opensLane: false
+      appendsEvents: false
+    }) => void
+  },
+  message: string,
+): void {
+  entry.supersede.abort(new A2Error('SUPERSEDED_ATTEMPT', message))
+  entry.fence({ status: 'superseded', opensLane: false, appendsEvents: false })
+}
+
+/** Pause between clear-deletion batches that found only locked rows. */
+const RECLAIM_STALL_MS = 20
+const RECLAIM_STALL_LIMIT = 50
+
 /** Default: how long a presence value survives without a refreshing set. */
 const PRESENCE_TTL_MS = 60_000
 
@@ -511,11 +644,32 @@ function foldPresenceRows(
   return map
 }
 
+type SnapshotWrites = Map<
+  number,
+  { state: unknown; pinEventIndexes: Set<number> }
+>
+
+const addSnapshotWrite = (
+  writes: SnapshotWrites,
+  index: number,
+  state: unknown,
+  pinEventIndex?: number,
+): void => {
+  let write = writes.get(index)
+  if (!write) {
+    write = { state: cloneInitial(state), pinEventIndexes: new Set() }
+    writes.set(index, write)
+  }
+  if (pinEventIndex !== undefined) write.pinEventIndexes.add(pinEventIndex)
+}
+
 /** 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> {
+  R extends RegisteredReducer<D, P> | undefined =
+    RegisteredReducer<D, P> | undefined,
+>(options: ServerOptions<D, P, R>): A2Server<D, P, R> {
   const serverContract = options?.contract
   if (
     serverContract === null ||
@@ -855,6 +1009,7 @@ export function createServer<
     cause?: EventCause,
     generatedIds?: readonly boolean[],
     requireDurableInitialArm = false,
+    originIndex?: number,
   ): Promise<ContractEvent<D>[]> =>
     telemetry.span(
       'a2.append',
@@ -885,9 +1040,20 @@ export function createServer<
         let rows: StoredEvent[]
         let shouldHealSession: boolean
         try {
-          const result = await store.append(nsId(sessionId), validated)
+          const result = await store.append(
+            nsId(sessionId),
+            validated,
+            originIndex === undefined ? undefined : { originIndex },
+          )
           rows = result.events
-          shouldHealSession = result.hasPending
+          // A handler appending only settled events adds no work, and the
+          // drain holding its trigger is already running.
+          shouldHealSession =
+            result.hasPending &&
+            !(
+              source === 'handler' &&
+              validated.every((event) => event.settled === true)
+            )
         } catch (err) {
           throw asStoreUnavailable(err)
         }
@@ -1005,12 +1171,18 @@ export function createServer<
     }
   }
 
+  type StateResult = { state: unknown; index: number; clearIndex?: number }
+
   type PendingStateRead = {
     sessionId: string
     throughIndex?: number
+    /** The id of the event at `throughIndex`, when the reader knows it. */
+    throughEventId?: string
     pinEventIndex?: number
+    /** A handler read: rejected once this trigger index has been cleared. */
+    triggerIndex?: number
     span: A2SpanHandle
-    resolve: (result: { state: unknown; index: number }) => void
+    resolve: (result: StateResult) => void
     reject: (reason: unknown) => void
   }
 
@@ -1045,6 +1217,331 @@ export function createServer<
     return plans
   }
 
+  const persistSnapshots = ({
+    store,
+    reducer,
+    sessionId,
+    snapshots,
+  }: {
+    store: A2Store
+    reducer: Reducer<D, unknown>
+    sessionId: string
+    snapshots: StoreSnapshotWrite[]
+  }): void => {
+    const persistence = Promise.resolve()
+      .then(() =>
+        telemetry.span(
+          'a2.snapshot',
+          {
+            'a2.contract': name,
+            'a2.session_id': sessionId,
+            'a2.snapshot.reducer': reducer.name,
+            'a2.snapshot.index': snapshots.at(-1)!.index,
+            'a2.snapshot.count': snapshots.length,
+          },
+          async (span) => {
+            try {
+              await store.putSnapshots(nsId(sessionId), reducer.name, snapshots)
+            } catch (error) {
+              try {
+                span.recordError(error)
+              } catch (telemetryError) {
+                // oxlint-disable-next-line preserve-caught-error -- AggregateError preserves both failures.
+                throw new AggregateError(
+                  [error, telemetryError],
+                  'Snapshot write and error reporting failed',
+                  { cause: telemetryError },
+                )
+              }
+            }
+          },
+        ),
+      )
+      .catch((error: unknown) => {
+        // oxlint-disable-next-line no-console -- telemetry failure must not hide failed background work.
+        console.error(
+          '[a2] error in a2.snapshot telemetry',
+          {
+            sessionId,
+            reducer: reducer.name,
+            index: snapshots.at(-1)!.index,
+          },
+          error,
+        )
+      })
+    track(persistence)
+    platformWaitUntil(persistence)
+  }
+
+  // ── in-memory reducer state ──────────────────────────────────────
+  /**
+   * The latest folded state per (session, reducer) this process has seen,
+   * with the index and id of the last event it reflects. An entry serves
+   * only the reducer object that folded it, so a same-named reducer with
+   * different logic reads the store. Cached states are never handed out;
+   * readers get clones.
+   */
+  type CachedState = {
+    reducer: Reducer<D, unknown>
+    index: number
+    lastId: string
+    state: unknown
+    bytes: number
+    /** Events folded since `bytes` was last measured. */
+    unmeasured: number
+    persistedIndex: number
+    /** The latest clear marker at or below `index`, or zero. */
+    clearIndex: number
+  }
+  const stateCache = boundedCache<string, CachedState>(STATE_CACHE)
+  const cacheState = (key: string, next: CachedState): void => {
+    const current = stateCache.get(key)
+    if (
+      current?.reducer === next.reducer &&
+      (current.index > next.index ||
+        (current.index === next.index &&
+          current.persistedIndex >= next.persistedIndex))
+    )
+      return
+    stateCache.set(key, next, next.bytes)
+  }
+
+  const writeSnapshots = ({
+    store,
+    reducer,
+    sessionId,
+    writes,
+  }: {
+    store: A2Store
+    reducer: Reducer<D, unknown>
+    sessionId: string
+    writes: SnapshotWrites
+  }): StoreSnapshotWrite[] => {
+    const snapshots = [...writes]
+      .toSorted(([a], [b]) => a - b)
+      .map(([index, write]) => {
+        const snapshot: StoreSnapshotWrite = {
+          index,
+          state: encodeState({ reducer, state: write.state }),
+        }
+        if (write.pinEventIndexes.size > 0) {
+          snapshot.pinEventIndexes = [...write.pinEventIndexes]
+        }
+        return snapshot
+      })
+    if (snapshots.length > 0) {
+      persistSnapshots({ store, reducer, sessionId, snapshots })
+    }
+    return snapshots
+  }
+
+  /**
+   * Folds `rows` from `position` in bound order, resolving each entry with a
+   * clone once the rows through its bound are folded. `visit` sees each
+   * entry's state before later rows are folded into it.
+   */
+  const foldEntries = ({
+    reducer,
+    entries,
+    rows,
+    position,
+    state,
+    index,
+    clearIndex,
+    snapshot,
+    visit,
+  }: {
+    reducer: Reducer<D, unknown>
+    entries: PendingStateRead[]
+    rows: Event[]
+    position: number
+    state: unknown
+    index: number
+    /** The latest clear marker the rows reflect, or zero. */
+    clearIndex: number
+    snapshot: string
+    visit: (
+      entry: PendingStateRead,
+      state: unknown,
+      index: number,
+      folded: number,
+    ) => void
+  }): { state: unknown; index: number; position: number } => {
+    const start = position
+    const ordered = entries.toSorted(
+      (a, b) =>
+        (a.throughIndex ?? Number.POSITIVE_INFINITY) -
+        (b.throughIndex ?? Number.POSITIVE_INFINITY),
+    )
+    for (const entry of ordered) {
+      const target = entry.throughIndex ?? Number.POSITIVE_INFINITY
+      while (position < rows.length && rows[position]!.index <= target) {
+        const row = rows[position]!
+        state = foldEvent(reducer, state, toPublic(row))
+        index = row.index
+        position += 1
+      }
+      if (
+        (entry.triggerIndex !== undefined &&
+          entry.triggerIndex <= clearIndex) ||
+        (entry.throughIndex !== undefined &&
+          entry.throughIndex > 0 &&
+          entry.throughIndex < clearIndex)
+      ) {
+        entry.reject(
+          sessionClearedError(
+            `session '${entry.sessionId}' was cleared at index ${clearIndex}`,
+          ),
+        )
+        continue
+      }
+      entry.span.setAttribute('a2.state.snapshot', snapshot)
+      entry.span.setAttribute('a2.state.folded', position - start)
+      entry.span.setAttribute('a2.state.index', index)
+      visit(entry, state, index, position - start)
+      // A result below the marker (the explicit seed) predates this lifetime.
+      entry.resolve({
+        state: cloneInitial(state),
+        index,
+        ...(clearIndex > 0 && index >= clearIndex ? { clearIndex } : {}),
+      })
+    }
+    return { state, index, position }
+  }
+
+  /**
+   * Events from `fromIndex` (inclusive) through `throughIndex` or the newest
+   * event, or null when the tail is too long to be worth folding in memory.
+   */
+  const readCachedTail = async (
+    store: A2Store,
+    sessionId: string,
+    fromIndex: number,
+    throughIndex?: number,
+  ): Promise<Event[] | null> => {
+    const readTail = stateTailReaders.get(store)
+    if (readTail) {
+      try {
+        return await readTail(nsId(sessionId), fromIndex, throughIndex)
+      } catch (err) {
+        throw asStoreUnavailable(err)
+      }
+    }
+    const limit = fromIndex + STATE_CACHE.maxTail
+    const capped = throughIndex === undefined || throughIndex > limit
+    const rows = await readHistory(sessionId, {
+      gte: fromIndex,
+      lte: capped ? limit : throughIndex,
+    })
+    return capped && rows.at(-1)?.index === limit ? null : rows
+  }
+
+  /**
+   * Serves a plan from the cached state when every read is at or past the
+   * cached index. A read bounded at the cached index by an event whose id
+   * matches the cached one (a handler's own trigger) needs no store request;
+   * any other read fetches the tail from the cached event onward and checks
+   * that event's id. Returns false when the store must answer instead.
+   */
+  const foldCachedPlan = async (
+    store: A2Store,
+    reducer: Reducer<D, unknown>,
+    plan: StateReadPlan,
+  ): Promise<boolean> => {
+    const key = stateCacheKey(plan.sessionId, reducer.name)
+    const cached = stateCache.get(key)
+    if (cached?.reducer !== reducer) return false
+    if (
+      plan.entries.some(
+        (entry) =>
+          entry.throughIndex !== undefined && entry.throughIndex < cached.index,
+      )
+    )
+      return false
+    let rows: Event[] = []
+    if (
+      plan.entries.some(
+        (entry) =>
+          entry.throughIndex !== cached.index ||
+          entry.throughEventId !== cached.lastId,
+      )
+    ) {
+      const tail = await readCachedTail(
+        store,
+        plan.sessionId,
+        cached.index,
+        plan.throughIndex,
+      )
+      if (!tail) return false
+      // A clear after the cached event, or a rewritten log, needs the store:
+      // it applies the boundary and its fences.
+      if (
+        tail[0]?.index !== cached.index ||
+        tail[0].id !== cached.lastId ||
+        tail.some((row, position) => position > 0 && isSessionCleared(row))
+      ) {
+        stateCache.delete(key)
+        return false
+      }
+      rows = tail
+    }
+    const writes: SnapshotWrites = new Map()
+    const folded = foldEntries({
+      reducer,
+      entries: plan.entries,
+      rows,
+      position: 1,
+      state: rows.length > 1 ? cloneInitial(cached.state) : cached.state,
+      index: cached.index,
+      clearIndex: cached.clearIndex,
+      snapshot: 'memory',
+      visit: (entry, state, index) => {
+        if (entry.pinEventIndex !== undefined) {
+          addSnapshotWrite(writes, index, state, entry.pinEventIndex)
+        }
+      },
+    })
+    const added = Math.max(0, folded.position - 1)
+    const rewritesHead =
+      folded.index - cached.persistedIndex >= STATE_CACHE.snapshotEvery
+    if (rewritesHead && !writes.has(folded.index)) {
+      writes.set(folded.index, {
+        state: folded.state,
+        pinEventIndexes: new Set(),
+      })
+    }
+    const snapshots = writeSnapshots({
+      store,
+      reducer,
+      sessionId: plan.sessionId,
+      writes,
+    })
+    const measure =
+      rewritesHead || cached.unmeasured + added >= STATE_CACHE.measureEvery
+    let grown = 0
+    if (!measure) {
+      for (let position = 1; position < folded.position; position += 1) {
+        grown += JSON.stringify(rows[position]!.payload)?.length ?? 0
+      }
+    }
+    cacheState(key, {
+      reducer,
+      index: folded.index,
+      lastId: added > 0 ? rows[folded.position - 1]!.id : cached.lastId,
+      state: folded.state,
+      bytes: measure
+        ? measuredBytes(reducer, folded.state, folded.index, snapshots)
+        : cached.bytes + grown,
+      unmeasured: measure ? 0 : cached.unmeasured + added,
+      persistedIndex: Math.max(
+        cached.persistedIndex,
+        snapshots.at(-1)?.index ?? 0,
+      ),
+      clearIndex: cached.clearIndex,
+    })
+    return true
+  }
+
   // The cache is untrusted: schema rejection refolds from the raw store.
   const foldStatePlan = async (
     store: A2Store,
@@ -1057,11 +1554,18 @@ export function createServer<
     let snapshotOutcome = 'miss'
     const snap = stateRead.snapshot
     let rows = stateRead.events
+    let clearIndex = stateRead.clearIndex ?? 0
     if (snap) {
-      if (reducer.stateSchema) {
+      let decoded: unknown
+      try {
+        decoded = decodeState({ reducer, state: snap.state })
+      } catch {
+        snapshotOutcome = 'rejected'
+      }
+      if (snapshotOutcome !== 'rejected' && reducer.stateSchema) {
         const result = validateSync(
           reducer.stateSchema,
-          snap.state,
+          decoded,
           'the stateSchema',
         )
         if (result.issues) {
@@ -1071,8 +1575,8 @@ export function createServer<
           index = snap.index
           snapshotOutcome = 'hit'
         }
-      } else {
-        state = snap.state
+      } else if (snapshotOutcome !== 'rejected') {
+        state = decoded
         index = snap.index
         snapshotOutcome = 'hit'
       }
@@ -1088,116 +1592,52 @@ export function createServer<
       } catch (err) {
         throw asStoreUnavailable(err)
       }
+      // Reads start at the latest marker, so a clear since readState leads.
+      if (rows[0] && isSessionCleared(rows[0]))
+        clearIndex = Math.max(clearIndex, rows[0].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 writes: SnapshotWrites = new Map()
+    const folded = foldEntries({
+      reducer,
+      entries: plan.entries,
+      rows,
+      position: 0,
+      state,
+      index,
+      clearIndex,
+      snapshot: snapshotOutcome,
+      visit: (entry, entryState, entryIndex, count) => {
+        if (entryIndex === 0) return
+        if (count === 0 && entry.pinEventIndex === undefined) return
         const advancesHead =
-          stateRead.headIndex === null || index > stateRead.headIndex
+          stateRead.headIndex === null || entryIndex > 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(() =>
-          telemetry.span(
-            'a2.snapshot',
-            {
-              'a2.contract': name,
-              'a2.session_id': plan.sessionId,
-              'a2.snapshot.reducer': reducer.name,
-              'a2.snapshot.index': snapshots.at(-1)!.index,
-              'a2.snapshot.count': snapshots.length,
-            },
-            async (span) => {
-              try {
-                await store.putSnapshots(
-                  nsId(plan.sessionId),
-                  reducer.name,
-                  snapshots,
-                )
-              } catch (error) {
-                try {
-                  span.recordError(error)
-                } catch (telemetryError) {
-                  // oxlint-disable-next-line preserve-caught-error -- AggregateError preserves both failures.
-                  throw new AggregateError(
-                    [error, telemetryError],
-                    'Snapshot write and error reporting failed',
-                    { cause: telemetryError },
-                  )
-                }
-              }
-            },
-          ),
-        )
-        .catch((error: unknown) => {
-          // oxlint-disable-next-line no-console -- telemetry failure must not hide failed background work.
-          console.error(
-            '[a2] error in a2.snapshot telemetry',
-            {
-              sessionId: plan.sessionId,
-              reducer: reducer.name,
-              index: snapshots.at(-1)!.index,
-            },
-            error,
-          )
-        })
-      track(persistence)
-      platformWaitUntil(persistence)
+          snapshotOutcome === 'rejected' && entryIndex === stateRead.headIndex
+        if (!advancesHead && !repairsHead && entry.pinEventIndex === undefined)
+          return
+        addSnapshotWrite(writes, entryIndex, entryState, entry.pinEventIndex)
+      },
+    })
+    const snapshots = writeSnapshots({
+      store,
+      reducer,
+      sessionId: plan.sessionId,
+      writes,
+    })
+    if (folded.position > 0 && STATE_CACHE.maxEntries > 0) {
+      cacheState(stateCacheKey(plan.sessionId, reducer.name), {
+        reducer,
+        index: folded.index,
+        lastId: rows[folded.position - 1]!.id,
+        state: folded.state,
+        bytes: measuredBytes(reducer, folded.state, folded.index, snapshots),
+        unmeasured: 0,
+        persistedIndex: Math.min(
+          Math.max(stateRead.headIndex ?? 0, ...writes.keys()),
+          folded.index,
+        ),
+        clearIndex,
+      })
     }
   }
 
@@ -1212,7 +1652,17 @@ export function createServer<
     reducer: Reducer<D, unknown>,
     batch: PendingStateRead[],
   ): Promise<void> => {
-    const plans = planStateReads(batch)
+    const plans: StateReadPlan[] = []
+    await Promise.all(
+      planStateReads(batch).map(async (plan) => {
+        try {
+          if (!(await foldCachedPlan(store, reducer, plan))) plans.push(plan)
+        } catch (error) {
+          for (const entry of plan.entries) entry.reject(error)
+        }
+      }),
+    )
+    if (plans.length === 0) return
     let reads: (StoreStateRead | Promise<StoreStateRead>)[]
     try {
       reads = store.readStates
@@ -1243,7 +1693,8 @@ export function createServer<
         )
     } catch (error) {
       const failure = asStoreUnavailable(error)
-      for (const entry of batch) entry.reject(failure)
+      for (const plan of plans)
+        for (const entry of plan.entries) entry.reject(failure)
       return
     }
     await Promise.all(
@@ -1257,14 +1708,20 @@ export function createServer<
     )
   }
 
+  type StateReadBounds = {
+    throughIndex?: number
+    throughEventId?: string
+    pinEventIndex?: number
+    triggerIndex?: number
+  }
+
   const enqueueStateRead = (
     store: A2Store,
     sessionId: string,
     reducer: Reducer<D, unknown>,
-    throughIndex?: number,
-    pinEventIndex?: number,
-    span?: A2SpanHandle,
-  ): Promise<{ state: unknown; index: number }> =>
+    bounds: StateReadBounds,
+    span: A2SpanHandle,
+  ): Promise<StateResult> =>
     new Promise((resolve, reject) => {
       const reducerName = reducer.name
       let batch = pendingStateReads.get(reducerName)
@@ -1286,22 +1743,14 @@ export function createServer<
         })
         batch = opened
       }
-      batch.push({
-        sessionId,
-        ...(throughIndex === undefined ? {} : { throughIndex }),
-        ...(pinEventIndex === undefined ? {} : { pinEventIndex }),
-        span: span!,
-        resolve,
-        reject,
-      })
+      batch.push({ sessionId, ...bounds, span, resolve, reject })
     })
 
-  const readState = async <S, V>(
+  const readState = async <S>(
     sessionId: string,
-    reducer: Reducer<D, S, Record<never, never>, V>,
-    throughIndex?: number,
-    pinEventIndex?: number,
-  ): Promise<{ state: S; index: number }> => {
+    reducer: Reducer<D, S, Record<never, never>>,
+    bounds: StateReadBounds,
+  ): Promise<{ state: S; index: number; clearIndex?: number }> => {
     const store = await resolveStore()
     return telemetry.span(
       'a2.state',
@@ -1315,20 +1764,27 @@ export function createServer<
           store,
           sessionId,
           reducer as Reducer<D, unknown>,
-          throughIndex,
-          pinEventIndex,
+          bounds,
           span,
-        ) as Promise<{ state: S; index: number }>,
+        ) as Promise<{ state: S; index: number; clearIndex?: number }>,
     )
   }
 
   const makeSchedule = (
     sessionId: string,
-    trigger: Pick<StoredEvent, 'id' | 'createdAt'> | null,
+    trigger: Pick<
+      StoredEvent,
+      'id' | 'createdAt' | 'index' | 'clearIndex'
+    > | null,
   ): SessionSchedule<D> => {
     const triggerEventId = trigger?.id ?? null
     const triggerCreatedAt = trigger?.createdAt.getTime()
-    return async (scheduleName, timing, ...events) => {
+    const clearIndex = trigger?.clearIndex ?? 0
+    const schedule = async (
+      scheduleName: string,
+      timing: ScheduleTiming,
+      ...events: AppendInput<D>[]
+    ): Promise<void> => {
       if (!scheduler) {
         throw new TypeError(
           'session.schedule requires a configured scheduler adapter',
@@ -1357,6 +1813,7 @@ export function createServer<
         sessionId,
         triggerEventId,
         scheduleName,
+        clearIndex,
       )
       const scheduledEvents: ScheduledEvent[] = await Promise.all(
         validated.map(async (event, item) => ({
@@ -1384,11 +1841,60 @@ export function createServer<
           sessionId,
           dueAt,
           events: scheduledEvents,
+          ...(trigger ? { originIndex: trigger.index } : {}),
         })
       } catch (error) {
         throw markSchedulerSendFailure(error)
       }
     }
+    const clear = async (
+      scheduleName: string,
+      clearOptions: ScheduleTiming & { ifLastIndex: number },
+    ): Promise<void> => {
+      if (!scheduler) {
+        throw new TypeError(
+          'session.schedule.clear requires a configured scheduler adapter',
+        )
+      }
+      assertScheduleName(scheduleName)
+      if (clearOptions === null || typeof clearOptions !== 'object') {
+        throw new TypeError('schedule.clear requires an ifLastIndex')
+      }
+      const { ifLastIndex, ...timing } = clearOptions
+      assertClearIndex(ifLastIndex)
+      const dueAt = scheduleDueAt(
+        timing as ScheduleTiming,
+        triggerCreatedAt ?? Date.now(),
+      )
+      const store = await resolveStore()
+      if (!store.clear || !store.reclaim) {
+        throw new TypeError(
+          'session.schedule.clear requires a store that supports clearing',
+        )
+      }
+      const id = await deterministicScheduleClearId({
+        contract: name,
+        sessionId,
+        triggerEventId,
+        clearIndex,
+        name: scheduleName,
+        ifLastIndex,
+      })
+      try {
+        await scheduler.schedule({
+          version: 1,
+          kind: 'clear',
+          id,
+          contract: name,
+          sessionId,
+          dueAt,
+          ifLastIndex,
+        })
+      } catch (error) {
+        throw markSchedulerSendFailure(error)
+      }
+    }
+    return Object.assign(schedule, { clear })
   }
 
   const toSessionEvent = (id: string, event: Event): ContractEvent<D> =>
@@ -1455,6 +1961,14 @@ export function createServer<
           },
         }
         streamActivities.set(stream, activity)
+        bufferedEvents.set(stream, () => {
+          const event = closed || !inner ? undefined : takeBuffered(inner)
+          if (!event) return undefined
+          if (!isSerializedEvent(event)) return toSessionEvent(id, event)
+          // Taken rows belong to this stream alone.
+          event.sessionId = id
+          return event
+        })
         return stream
       },
     }
@@ -1582,6 +2096,8 @@ export function createServer<
     const ns = nsId(id)
     let closed = false
     let events: AsyncIterator<Event> | undefined
+    // An event read the merge loop started and has not yet yielded.
+    let pendingEvent: Promise<IteratorResult<Event>> | null = null
     let unsubscribe: (() => void) | undefined
     let sleeper: Sleeper | null = null
     let wakeQueue: (() => void) | null = null
@@ -1763,7 +2279,6 @@ export function createServer<
         }
         return null
       }
-      let pendingEvent: Promise<IteratorResult<Event>> | null = null
       try {
         // Subscribe before the snapshot read: a patch landing between
         // the two is painted twice, never lost — repaints are idempotent.
@@ -1873,36 +2388,149 @@ export function createServer<
           },
         }
         streamActivities.set(stream, activity)
+        bufferedEvents.set(stream, () => {
+          // A held event may follow only events already yielded; while a
+          // read is outstanding, its event must go first.
+          if (closed || !events || pendingEvent) return undefined
+          const event = takeBuffered(events)
+          if (!event) return undefined
+          if (!isSerializedEvent(event)) return toSessionEvent(id, event)
+          // Taken rows belong to this stream alone.
+          event.sessionId = id
+          return event
+        })
         return stream
       },
     }
   }
 
+  // ── clearing (a2-implementation.md §17) ──────────────────────────
+
+  const reclaimAll = async (store: A2Store, ns: string): Promise<void> => {
+    for (let stalls = 0; ;) {
+      let batch: StoreReclaimResult
+      try {
+        // oxlint-disable-next-line no-await-in-loop -- bounded batches, oldest first
+        batch = await store.reclaim!(ns)
+      } catch (err) {
+        throw asStoreUnavailable(err)
+      }
+      if (batch.done) return
+      if (batch.deleted > 0) {
+        stalls = 0
+        continue
+      }
+      // Only rows other work holds locked remain; they free up shortly.
+      stalls += 1
+      if (stalls === RECLAIM_STALL_LIMIT) {
+        throw new A2Error(
+          'STORE_UNAVAILABLE',
+          `deleting the cleared history of session '${stripNs(ns)}' made no progress`,
+        )
+      }
+      // oxlint-disable-next-line no-await-in-loop -- paced retry
+      await defaultSleep(RECLAIM_STALL_MS).promise
+    }
+  }
+
+  /** The handler attempt a `ctx.session.clear()` belongs to. */
+  type ClearingAttempt = {
+    cause: EventCause
+    end: () => void
+    signal: AbortSignal
+  }
+
+  const clearSession = async (
+    sessionId: string,
+    clearOptions: SessionClearOptions | undefined,
+    attempt: ClearingAttempt | undefined,
+  ): Promise<SessionClearResult> => {
+    const ifLastIndex = clearOptions?.ifLastIndex
+    if (ifLastIndex !== undefined) assertClearIndex(ifLastIndex)
+    const store = await resolveStore()
+    if (!store.clear || !store.reclaim) {
+      throw new TypeError(
+        'session.clear requires a store that supports clearing',
+      )
+    }
+    const ns = nsId(sessionId)
+    let result: StoreClearResult
+    try {
+      result = await store.clear({
+        sessionId: ns,
+        ...(ifLastIndex === undefined ? {} : { ifLastIndex }),
+        ...(attempt ? { cause: attempt.cause } : {}),
+      })
+    } catch (err) {
+      throw asStoreUnavailable(err)
+    }
+    if (result.cleared) {
+      // This instance's own reads after the clear, including the clearing
+      // handler's, go to the store and see the boundary.
+      const cachePrefix = stateCacheKey(sessionId, '')
+      stateCache.deleteWhere((key) => key.startsWith(cachePrefix))
+    }
+    const deletion = reclaimAll(store, ns)
+    if (attempt) {
+      if (attempt.cause.index <= result.clearIndex) attempt.end()
+      // Ending the attempt releases its drain slot; the deletion must still
+      // outlive the drain.
+      const kept = deletion.catch(() => undefined)
+      track(kept)
+      platformWaitUntil(kept)
+    }
+    await deletion
+    return { cleared: result.cleared, index: result.index }
+  }
+
   const makeSession = <Append>(
     id: string,
     append: Append,
-    trigger: Pick<StoredEvent, 'id' | 'createdAt' | 'index'> | null,
+    trigger: Pick<
+      StoredEvent,
+      'id' | 'createdAt' | 'index' | 'clearIndex'
+    > | null,
+    attempt?: ClearingAttempt,
   ): Session<D, Append, P> =>
     ({
       id,
       append,
       schedule: makeSchedule(id, trigger),
+      clear: (clearOptions?: SessionClearOptions) =>
+        clearSession(id, clearOptions, attempt),
       history: async (bounds?: { gte?: number; lte?: number }) =>
-        (await readHistory(id, bounds)).map(toPublic),
-      state: <S, V>(
-        reducer: Reducer<D, S, Record<never, never>, V>,
+        (await readHistory(id, bounds))
+          .filter((row) => !isSessionCleared(row))
+          .map(toPublic),
+      state: <S>(
+        reducer: Reducer<
+          D,
+          S,
+          Record<never, never>
+        > = serverContract.reducer as unknown as Reducer<
+          D,
+          S,
+          Record<never, never>
+        >,
         stateOptions?: StateOptions,
       ) => {
+        if (!reducer)
+          throw new A2Error('INVALID_PAYLOAD', 'contract has no public reducer')
         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,
-        )
+        const bounds: StateReadBounds = {}
+        if (through !== undefined && through !== 'latest') {
+          bounds.throughIndex = through
+          if (trigger) bounds.pinEventIndex = trigger.index
+          // Only a live attempt may be answered from memory with no store
+          // request; a superseded one (including by a clear) reads the store.
+          if (through === trigger?.index && !attempt?.signal.aborted)
+            bounds.throughEventId = trigger.id
+        }
+        if (trigger) bounds.triggerIndex = trigger.index
+        return readState(id, reducer, bounds)
       },
       stream: (opts?: { startAfter?: number; presence?: boolean }) => {
         const startAfter = opts?.startAfter ?? 0
@@ -1932,6 +2560,7 @@ export function createServer<
     trigger: StoredEvent,
     attempt: number,
     signal: AbortSignal,
+    endAttempt: () => void,
   ): HandlerContext<D> => {
     const publicSessionId = stripNs(trigger.sessionId)
     const append: HandlerAppend<D> = async (appendName, ...events) => {
@@ -1961,7 +2590,11 @@ export function createServer<
       // 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),
+      session: makeSession(publicSessionId, append, trigger, {
+        cause: { index: trigger.index, attempt },
+        end: endAttempt,
+        signal,
+      }),
       signal,
     }
   }
@@ -2267,17 +2900,10 @@ export function createServer<
                   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}'`,
-                    ),
+                  endSuperseded(
+                    entry,
+                    `a newer attempt owns event ${index} in session '${sessionId}'`,
                   )
-                  entry.fence({
-                    status: 'superseded',
-                    opensLane: false,
-                    appendsEvents: false,
-                  })
                 }
                 if (window.deadlineCapped) stopRenewing = true
                 scheduleLapse()
@@ -2299,6 +2925,7 @@ export function createServer<
         const runEvent = async (
           event: StoredEvent,
           supersedeSignal: AbortSignal,
+          endAttempt: () => void,
         ): Promise<EventOutcome> => {
           const registration = handlers.get(event.type)
           return telemetry.span(
@@ -2338,7 +2965,7 @@ export function createServer<
                   ])
                 }
                 const operation = registration?.handler(
-                  makeCtx(event, event.attemptCount, handlerSignal),
+                  makeCtx(event, event.attemptCount, handlerSignal, endAttempt),
                 )
                 const result = operation
                   ? await (subscription
@@ -2369,17 +2996,31 @@ export function createServer<
                 // 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),
-                  // A NonRetriableError is terminal on its first throw:
-                  // deterministic failures should not burn the retry
-                  // budget before dead-lettering.
-                  maxFailures:
-                    err instanceof NonRetriableError ? 1 : MAX_FAILURES,
-                })
+                const failure = await telemetry.span(
+                  'a2.commit',
+                  {
+                    'a2.contract': name,
+                    'a2.session_id': sessionId,
+                    'a2.commit.operation': 'fail',
+                    'a2.commit.index': event.index,
+                    'a2.commit.attempt': event.attemptCount,
+                  },
+                  async (commitSpan) => {
+                    const result = await store.failAttempt({
+                      sessionId: ns,
+                      index: event.index,
+                      attempt: event.attemptCount,
+                      error: describeError(err),
+                      // A NonRetriableError is terminal on its first throw:
+                      // deterministic failures should not burn the retry
+                      // budget before dead-lettering.
+                      maxFailures:
+                        err instanceof NonRetriableError ? 1 : MAX_FAILURES,
+                    })
+                    commitSpan.setAttribute('a2.commit.outcome', result.outcome)
+                    return result
+                  },
+                )
                 eventSpan.setAttribute('a2.event.outcome', failure.outcome)
                 return {
                   status: failure.outcome,
@@ -2390,12 +3031,26 @@ export function createServer<
                 await subscription?.close()
               }
               await renewal
-              const completion = await store.completeAttempt({
-                sessionId: ns,
-                index: event.index,
-                attempt: event.attemptCount,
-                events: returned,
-              })
+              const completion = await telemetry.span(
+                'a2.commit',
+                {
+                  'a2.contract': name,
+                  'a2.session_id': sessionId,
+                  'a2.commit.operation': 'complete',
+                  'a2.commit.index': event.index,
+                  'a2.commit.attempt': event.attemptCount,
+                },
+                async (commitSpan) => {
+                  const result = await store.completeAttempt({
+                    sessionId: ns,
+                    index: event.index,
+                    attempt: event.attemptCount,
+                    events: returned,
+                  })
+                  commitSpan.setAttribute('a2.commit.outcome', result.outcome)
+                  return result
+                },
+              )
               eventSpan.setAttribute(
                 'a2.event.outcome',
                 completion.outcome === 'completed'
@@ -2430,29 +3085,28 @@ export function createServer<
           // 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}'`,
-              ),
+            endSuperseded(
+              previous,
+              `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
           })
+          // A handler's own committed clear supersedes it immediately.
+          const endAttempt = (): void =>
+            endSuperseded(
+              { supersede, fence },
+              `event ${event.index} in session '${sessionId}' was cleared`,
+            )
           // 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),
+            runEvent(event, supersede.signal, endAttempt),
             fenced,
           ]).then((eventOutcome) => {
             // Identity-guarded: a fenced predecessor's continuation must
@@ -2493,17 +3147,29 @@ export function createServer<
             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] }),
-              })
+              claim = await telemetry.span(
+                'a2.claim',
+                { 'a2.contract': name, 'a2.session_id': sessionId },
+                async (claimSpan) => {
+                  const result = await store.claimAvailable({
+                    sessionId: ns,
+                    holder,
+                    ttlMs: window.ttlMs,
+                    ...(window.deadlineCapped
+                      ? { expiresAtMs: window.expiresAtMs }
+                      : {}),
+                    ...(excluded.size === 0
+                      ? {}
+                      : { excludeIndexes: [...excluded] }),
+                  })
+                  claimSpan.setAttribute('a2.claim.outcome', result.outcome)
+                  claimSpan.setAttribute(
+                    'a2.claim.count',
+                    result.outcome === 'claimed' ? result.events.length : 0,
+                  )
+                  return result
+                },
+              )
               if (claim.outcome === 'claimed') {
                 requestWatchdog(window.watchdogAtMs)
                 if (window.deadlineCapped) stopRenewing = true
@@ -2595,6 +3261,7 @@ export function createServer<
     mode: 'inline' | 'dispatch',
     events: AppendInput<D>[],
     requireDurableInitialArm = false,
+    originIndex?: number,
   ): Promise<ContractEvent<D>[]> => {
     return appendCore(
       sessionId,
@@ -2605,6 +3272,7 @@ export function createServer<
       undefined,
       undefined,
       requireDurableInitialArm,
+      originIndex,
     )
   }
 
@@ -2620,11 +3288,29 @@ export function createServer<
     return makeSession(id, append, null)
   }
 
-  const fetch = createServerFetch({ contract: serverContract, session })
-  const self: A2Server<D, P> = {
+  const historyPage = async (
+    sessionId: string,
+    bounds: { gte: number; lte: number },
+  ): Promise<{ events: ContractEvent<D>[]; clearIndex?: number }> => {
+    assertSessionId(sessionId)
+    const rows = await readHistory(sessionId, bounds)
+    // Reads start at the latest marker, so it can only lead the page.
+    const marker = rows[0] && isSessionCleared(rows[0]) ? rows[0] : undefined
+    return {
+      events: (marker ? rows.slice(1) : rows).map(toPublic),
+      ...(marker ? { clearIndex: marker.index } : {}),
+    }
+  }
+
+  const fetch = createServerFetch({
     contract: serverContract,
-    fetch,
     session,
+    historyPage,
+  })
+  const self: A2Server<D, P, R> = {
+    contract: serverContract,
+    fetch,
+    session: session as A2Server<D, P, R>['session'],
 
     async drain(sessionId) {
       assertSessionId(sessionId)
@@ -2643,14 +3329,38 @@ export function createServer<
       assertSessionId(sessionId)
       return drainSession(sessionId, opts?.watchdogDueAt)
     },
-    schedulerAppend: async (sessionId, events) => {
+    schedulerAppend: async (sessionId, events, originIndex) => {
       if (!scheduler) {
         throw new TypeError(
           'scheduled append delivery requires a configured scheduler adapter',
         )
       }
       assertSessionId(sessionId)
-      await appendExternal(sessionId, 'inline', [...events], true)
+      try {
+        await appendExternal(
+          sessionId,
+          'inline',
+          [...events],
+          true,
+          originIndex,
+        )
+      } catch (error) {
+        // The scheduling handler's lifetime was cleared: an acknowledged no-op.
+        if (
+          originIndex !== undefined &&
+          error instanceof A2Error &&
+          error.code === 'SESSION_CLEARED'
+        )
+          return
+        throw error
+      }
+    },
+    historyWithMarkers: async (sessionId, gte) =>
+      (await readHistory(sessionId, { gte })).map(toPublic),
+    schedulerClear: async (sessionId, ifLastIndex) => {
+      assertSessionId(sessionId)
+      assertClearIndex(ifLastIndex)
+      await clearSession(sessionId, { ifLastIndex }, undefined)
     },
   })
   return self
@@ -2683,6 +3393,12 @@ function assertStateIndex(value: number): void {
   }
 }
 
+function assertClearIndex(value: number): void {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new TypeError('ifLastIndex 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')
@@ -2827,16 +3543,19 @@ function isJsonValue(value: unknown, ancestors: WeakSet<object>): boolean {
   }
 }
 
-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
-  }
-}
+const measuredBytes = (
+  reducer: object,
+  state: unknown,
+  index: number,
+  snapshots: StoreSnapshotWrite[],
+): number =>
+  JSON.stringify(
+    snapshots.find((snapshot) => snapshot.index === index)?.state ??
+      encodeState({ reducer, state }),
+  )?.length ?? 0
+
+const stateCacheKey = (sessionId: string, reducerName: string): string =>
+  `${sessionId}\u0000${reducerName}`
 
 // Server-side types users need when passing custom stores or building
 // transports — re-exported so experimental-a2/server is self-sufficient.
@@ -2857,6 +3576,7 @@ export type {
 export type {
   ScheduledEvent,
   SchedulerAppendTask,
+  SchedulerClearTask,
   SchedulerDrainTask,
   SchedulerTask,
 } from './scheduler-task.ts'