experimental-a2 0.16.1 → 0.18.0

package/src/contract.ts

@@ -1,15 +1,9 @@
-/**
- * The contract — a2's primary noun. A named event vocabulary, shared by
- * everything: the server implements it (experimental-a2/server's `createServer`),
- * reducers derive from it (`contract.reducer`), the browser types its
- * pushes off it. Isomorphic by construction: this module imports
- * nothing but schema plumbing.
- *
- * The contract says what can be *said*; the server says how it's
- * *reacted to*; a reducer says how it's *seen*.
- */
-
-import { makeReducerBuilder, type ReducerBuilder } from './reducer.ts'
+import {
+  makeReducerBuilder,
+  type Reducer,
+  type RegisteredReducer,
+} from './reducer.ts'
+import { RESERVED_EVENT_PREFIX } from './session-clear.ts'
 import type { StandardSchemaV1 } from './standard-schema.ts'
 import { assertSyncSchema } from './validate.ts'
 
@@ -121,6 +115,7 @@ export type ReducerOptions<Seed, S> = {
 export type Contract<
   D extends EventDefs = EventDefs,
   P extends PresenceDefs = Record<never, never>,
+  R = RegisteredReducer<D, P> | undefined,
 > = {
   /** Identity — prefixes storage keys and queue messages. */
   readonly name: string
@@ -130,19 +125,7 @@ export type Contract<
   readonly presence: Readonly<P>
   /** Preserve literal types for a handler-returned event batch. */
   readonly batch: EventBatchFactory<D>
-  /**
-   * Derive a view from this contract. The reducer's `name` is its
-   * identity and snapshot cache key: rename it when the fold's logic
-   * changes. Two steps by design: this call fixes the state and event
-   * types, so `.fold()` receives fully concrete types — literal unions
-   * in your state survive, with zero annotations. (A single call can't
-   * do this: TypeScript never contextually types the returns of a
-   * context-sensitive argument against generics inferred in the same
-   * call.)
-   */
-  reducer<Seed, S = Seed>(
-    options: ReducerOptions<Seed, S>,
-  ): ReducerBuilder<D, S, P>
+  readonly reducer: R
 }
 
 /**
@@ -150,21 +133,77 @@ export type Contract<
  * must be synchronous — async ones are rejected here, at definition
  * time. The result is a plain, importable, isomorphic value.
  */
-export function contract<
-  D extends EventDefs,
-  P extends PresenceDefs = Record<never, never>,
->(options: {
-  /** Identity — prefixes storage keys and queue messages. */
+type ContractOptions<D extends EventDefs, P extends PresenceDefs> = {
   name: string
-  /** The vocabulary: event name → payload schema (Standard Schema). */
   events: D
-  /**
-   * Optional second vocabulary: presence field → value schema.
-   * Per-participant ephemeral state, replicated last-writer-wins and
-   * never stored in the log — reducers cannot see it.
-   */
   presence?: P
-}): Contract<D, P> {
+}
+
+export function contract<
+  D extends EventDefs,
+  P extends PresenceDefs = Record<never, never>,
+  Schema extends StandardSchemaV1 = StandardSchemaV1,
+>(
+  options: ContractOptions<D, P> & {
+    reducer: {
+      name: string
+      initialState: StandardSchemaV1.InferInput<NoInfer<Schema>>
+      stateSchema: Schema
+      fold: (
+        state: StandardSchemaV1.InferOutput<Schema>,
+        event: ContractEvent<NoInfer<D>>,
+      ) => StandardSchemaV1.InferOutput<Schema>
+    }
+  },
+): Contract<D, P, Reducer<D, StandardSchemaV1.InferOutput<Schema>, P>>
+export function contract<
+  D extends EventDefs,
+  P extends PresenceDefs = Record<never, never>,
+  S = unknown,
+>(
+  options: ContractOptions<D, P> & {
+    reducer: {
+      name: string
+      initialState: S
+      fold: (state: NoInfer<S>, event: ContractEvent<NoInfer<D>>) => NoInfer<S>
+    }
+  },
+): Contract<D, P, Reducer<D, S, P>>
+export function contract<
+  D extends EventDefs,
+  P extends PresenceDefs = Record<never, never>,
+  R extends RegisteredReducer<D, P> = RegisteredReducer<D, P>,
+>(options: ContractOptions<D, P> & { reducer: R }): Contract<D, P, R>
+export function contract<
+  D extends EventDefs,
+  P extends PresenceDefs = Record<never, never>,
+>(
+  options: ContractOptions<D, P> & { reducer?: undefined },
+): Contract<D, P, undefined>
+export function contract(options: AnyContractOptions): unknown {
+  for (const type of Object.keys(options.events ?? {})) {
+    if (type.startsWith(RESERVED_EVENT_PREFIX)) {
+      throw new TypeError(
+        `contract '${String(options.name)}': event types starting with '${RESERVED_EVENT_PREFIX}' are reserved`,
+      )
+    }
+  }
+  return defineContract(options)
+}
+
+/** A2's own contracts, which may declare reserved `a2.` event types. */
+export const internalContract: typeof contract =
+  defineContract as typeof contract
+
+type AnyContractOptions = ContractOptions<EventDefs, PresenceDefs> & {
+  reducer?:
+    | (ReducerOptions<unknown, unknown> & {
+        fold: (state: never, event: never) => unknown
+      })
+    | undefined
+}
+
+function defineContract(options: AnyContractOptions): unknown {
   const { name } = options
   if (typeof name !== 'string' || name.length === 0) {
     throw new TypeError('contract name must be a non-empty string')
@@ -183,7 +222,7 @@ export function contract<
   }
   const events = Object.freeze({ ...defs })
 
-  const presenceDefs = options.presence ?? ({} as P)
+  const presenceDefs = options.presence ?? {}
   for (const [field, schema] of Object.entries(presenceDefs)) {
     if (typeof schema?.['~standard']?.validate !== 'function') {
       throw new TypeError(
@@ -198,9 +237,20 @@ export function contract<
     name,
     events,
     presence,
-    batch: (...items) => items,
-    reducer(reducerOptions) {
-      return makeReducerBuilder(events, presence, reducerOptions)
-    },
+    batch: <const E extends readonly AppendInput<EventDefs>[]>(
+      ...items: E
+    ): E => items,
+    reducer:
+      options.reducer === undefined
+        ? undefined
+        : {
+            ...options.reducer,
+            ...makeReducerBuilder(events, presence, options.reducer).fold(
+              options.reducer.fold as (
+                state: unknown,
+                event: ContractEvent<EventDefs>,
+              ) => unknown,
+            ),
+          },
   }
 }

package/src/deterministic-id.ts

@@ -14,6 +14,7 @@ const APPEND_NAMESPACE = 'a2:handler-append:v2'
 const RETURN_NAMESPACE = 'a2:handler-return:v1'
 const SCHEDULE_NAMESPACE = 'a2:schedule:v1'
 const SCHEDULED_EVENT_NAMESPACE = 'a2:scheduled-event:v1'
+const SCHEDULE_CLEAR_NAMESPACE = 'a2:schedule-clear:v1'
 
 async function deterministicIdFromInput(input: string): Promise<string> {
   const digest = await crypto.subtle.digest(
@@ -47,11 +48,18 @@ export async function deterministicReturnedEventId(
   return deterministicId([RETURN_NAMESPACE, triggerEventId, itemOrdinal])
 }
 
+/**
+ * The id of a scheduled append. `clearIndex` is the lifetime the trigger was
+ * claimed in; it joins the input only when positive, so a trigger id reused
+ * after a clear schedules a distinct task while sessions never cleared keep
+ * the ids they always had.
+ */
 export async function deterministicScheduleId(
   contract: string,
   sessionId: string,
   triggerEventId: string | null,
   name: string,
+  clearIndex = 0,
 ): Promise<string> {
   return deterministicIdFromInput(
     JSON.stringify([
@@ -60,6 +68,35 @@ export async function deterministicScheduleId(
       sessionId,
       triggerEventId,
       name,
+      ...(clearIndex > 0 ? [clearIndex] : []),
+    ]),
+  )
+}
+
+export async function deterministicScheduleClearId({
+  contract,
+  sessionId,
+  triggerEventId,
+  clearIndex,
+  name,
+  ifLastIndex,
+}: {
+  contract: string
+  sessionId: string
+  triggerEventId: string | null
+  clearIndex: number
+  name: string
+  ifLastIndex: number
+}): Promise<string> {
+  return deterministicIdFromInput(
+    JSON.stringify([
+      SCHEDULE_CLEAR_NAMESPACE,
+      contract,
+      sessionId,
+      triggerEventId,
+      clearIndex,
+      name,
+      ifLastIndex,
     ]),
   )
 }

package/src/equal-json.ts

@@ -0,0 +1,32 @@
+export const sameValue = (left: unknown, right: unknown): boolean => {
+  if (Object.is(left, right)) return true
+  if (
+    typeof left !== 'object' ||
+    left === null ||
+    typeof right !== 'object' ||
+    right === null
+  )
+    return false
+  const prototype = Object.getPrototypeOf(left)
+  if (
+    prototype !== Object.getPrototypeOf(right) ||
+    (prototype !== Object.prototype &&
+      prototype !== Array.prototype &&
+      prototype !== null)
+  )
+    return false
+  if (
+    Array.isArray(left) &&
+    (!Array.isArray(right) || left.length !== right.length)
+  )
+    return false
+  const keys = Reflect.ownKeys(left)
+  return (
+    keys.length === Reflect.ownKeys(right).length &&
+    keys.every(
+      (key) =>
+        Object.hasOwn(right, key) &&
+        sameValue(Reflect.get(left, key), Reflect.get(right, key)),
+    )
+  )
+}

package/src/errors.ts

@@ -3,7 +3,8 @@ export type A2ServerErrorCode =
   | 'FORBIDDEN' // external ingress was denied by server.fetch authorization
   | 'UNKNOWN_EVENT_TYPE' // event type not in the machine's `events` map
   | 'PARTIAL_DUPLICATE_BATCH' // batch mixed already-appended and fresh events
-  | 'SUPERSEDED_ATTEMPT' // handler append from an attempt a recovery claim replaced
+  | 'SUPERSEDED_ATTEMPT' // handler append from an attempt a recovery claim or a clear replaced
+  | 'SESSION_CLEARED' // a read or call reached across the session's latest clear
   | 'CLAIM_EXPIRED' // ctx.signal abort reason: the attempt's lease lapsed without renewal
   | 'STORE_UNAVAILABLE' // store backend failure — retryable, nothing was written
   | 'STORE_NOT_CONFIGURED' // production boot with no `store` passed
@@ -33,6 +34,17 @@ export class A2Error extends Error {
   }
 }
 
+/** A handler write whose attempt no longer owns its triggering event. */
+export function supersededAttemptError(
+  sessionId: string,
+  cause: { index: number; attempt: number },
+): A2Error {
+  return new A2Error(
+    'SUPERSEDED_ATTEMPT',
+    `attempt ${cause.attempt} no longer owns event ${cause.index} in session '${sessionId}'`,
+  )
+}
+
 /**
  * Wrap an arbitrary thrown value as STORE_UNAVAILABLE, preserving the
  * original as `cause`. A2Errors pass through untouched — they already

package/src/index.ts

@@ -22,9 +22,11 @@ export type {
   ReducerOptions,
 } from './contract.ts'
 
-export type { Reducer, ReducerBuilder } from './reducer.ts'
+export { reducer } from './reducer.ts'
+export type { Reducer, ReducerBuilder, StateSnapshot } from './reducer.ts'
 
 export { A2Error, NonRetriableError } from './errors.ts'
+export type { SessionCleared } from './session-clear.ts'
 export type { A2ErrorCode, A2ServerErrorCode } from './errors.ts'
 
 export type {
@@ -36,3 +38,5 @@ export type {
 
 export type { Event } from './store.ts'
 export type { StandardSchemaV1 } from './standard-schema.ts'
+
+export type { InitialSnapshot } from './initial-snapshot.ts'

package/src/initial-snapshot.ts

@@ -0,0 +1,39 @@
+import type { StateSnapshot } from './reducer.ts'
+
+export type InitialSnapshot<S> =
+  | StateSnapshot<S>
+  | null
+  | undefined
+  | Promise<StateSnapshot<S> | null | undefined>
+
+export function isInitialPromise<S>(
+  initial: InitialSnapshot<S>,
+): initial is Promise<StateSnapshot<S> | null | undefined> {
+  return (
+    initial !== null &&
+    typeof initial === 'object' &&
+    'then' in initial &&
+    typeof initial.then === 'function'
+  )
+}
+
+export function observeInitial<S>(options: {
+  promise: Promise<StateSnapshot<S> | null | undefined>
+  settled(
+    result: { value: StateSnapshot<S> | null | undefined } | { error: unknown },
+  ): void
+}): () => void {
+  let listener: typeof options.settled | undefined = options.settled
+  const deliver = (result: Parameters<typeof options.settled>[0]): void => {
+    const current = listener
+    listener = undefined
+    current?.(result)
+  }
+  void Promise.resolve(options.promise).then(
+    (value) => deliver({ value }),
+    (error: unknown) => deliver({ error }),
+  )
+  return () => {
+    listener = undefined
+  }
+}

package/src/internal.ts

@@ -5,6 +5,7 @@
 
 import type { ScheduledEvent } from './scheduler-task.ts'
 import type { DrainableServer } from './server.ts'
+import type { Event } from './store.ts'
 
 export type DrainOutcome = 'busy' | 'stalled' | 'settled'
 
@@ -62,11 +63,23 @@ export type ServerInternals = {
   schedulerAppend(
     sessionId: string,
     events: readonly ScheduledEvent[],
+    originIndex?: number,
   ): Promise<void>
+  /** Deliver a scheduler-owned conditional clear, deletion included. */
+  schedulerClear(sessionId: string, ifLastIndex: number): Promise<void>
+  /** `session.history` with clear markers kept; reads start at the latest one. */
+  historyWithMarkers(sessionId: string, gte: number): Promise<Event[]>
 }
 
 export const serverInternals: WeakMap<object, ServerInternals> = new WeakMap()
 
+/**
+ * Handler contexts whose previous attempt ended in a failure the handler
+ * threw, as opposed to a claim that lapsed (a crash, a timeout, a frozen
+ * process). Only the attempt's own outcome is known, not how far it got.
+ */
+export const failedPreviousAttempt: WeakSet<object> = new WeakSet()
+
 const objectLike = (value: unknown): value is object =>
   (typeof value === 'object' && value !== null) || typeof value === 'function'
 
@@ -305,6 +318,45 @@ export const NOTIFY_TIMINGS: {
   safetyReadMs: 10_000,
 }
 
+/**
+ * Bounds for each server instance's in-memory reducer-state cache. Sizes are
+ * encoded JSON lengths, re-measured every `measureEvery` folded events, so
+ * the byte budget is approximate. Mutable only as a white-box test seam.
+ */
+export const STATE_CACHE: {
+  maxEntries: number
+  maxBytes: number
+  /** Events a cached state may advance before it writes a snapshot. */
+  snapshotEvery: number
+  /** Events a warm read may fold; longer tails read the stored snapshot. */
+  maxTail: number
+  /** Events folded between re-measuring a cached state's encoded size. */
+  measureEvery: number
+} = {
+  maxEntries: 1_000,
+  maxBytes: 32 * 1024 * 1024,
+  snapshotEvery: 128,
+  maxTail: 255,
+  measureEvery: 16,
+}
+
+/**
+ * Warm state-read tails for stores that can serve one in a single request:
+ * events from `fromIndex` (inclusive) through `throughIndex` or the newest
+ * event, or null when that needs more than one request. Like every store
+ * read, a tail starts no lower than the latest clear marker. Keyed by the exact
+ * store object, so a wrapper built by spreading or proxying a store reads
+ * through its own `readHistory` instead.
+ */
+export const stateTailReaders: WeakMap<
+  object,
+  (
+    sessionId: string,
+    fromIndex: number,
+    throughIndex?: number,
+  ) => Promise<Event[] | null>
+> = new WeakMap()
+
 export const STREAM_TIMINGS: {
   /** Cadence of `: ping` comment frames from `sseResponse`. */
   sseHeartbeatMs: number

package/src/libfx.d.ts

@@ -0,0 +1,34 @@
+// The subset of libfx's agent API that experimental-a2/ai/fx uses; libfx
+// ships no type declarations.
+declare module 'libfx' {
+  export type FxHostTool = {
+    name: string
+    description: string
+    inputSchema: object
+    execute(input: unknown, context: { signal: AbortSignal }): unknown
+  }
+
+  export type FxTurn = AsyncIterable<{ type: string }> & {
+    result: Promise<{ stopReason: string }>
+    steer(input: string): Promise<void>
+    cancel(): void
+  }
+
+  export type FxAgent = {
+    prompt(input: string, options?: { signal?: AbortSignal }): FxTurn
+    checkpoint(): Promise<Uint8Array>
+    close(): Promise<void>
+  }
+
+  export function createFxAgent(options: {
+    apiKey: string
+    model?: string | { id: string; effort?: string; fast?: boolean }
+    instructions?: string | string[]
+    tools?: FxHostTool[]
+    checkpoint?: Uint8Array
+    fetch?: (
+      input: string | URL | Request,
+      init?: RequestInit,
+    ) => Promise<Response>
+  }): Promise<FxAgent>
+}

package/src/postgres-notification-scope.ts

@@ -65,12 +65,15 @@ export function postgresNotificationScope(
         [Symbol.asyncIterator]() {
           let stopped = false
           let after = startAfter
-          let buffer: Event[] = []
+          let buffer: Array<Event | undefined> = []
+          let position = 0
           let version = 0
           let waiting: Sleeper | undefined
           let lease: ReturnType<PostgresNotifications['watch']> | undefined
           const stop = (): void => {
             stopped = true
+            buffer = []
+            position = 0
             waiting?.cancel()
             lease?.stop()
             state.stops.delete(stop)
@@ -92,16 +95,24 @@ export function postgresNotificationScope(
                 for (;;) {
                   if (stopped || state.closed)
                     return { done: true, value: undefined }
-                  const row = buffer.shift()
+                  const row = buffer[position]
                   if (row) {
                     after = row.index
+                    buffer[position] = undefined
+                    position += 1
+                    if (position === buffer.length) {
+                      buffer = []
+                      position = 0
+                    }
                     return { done: false, value: row }
                   }
                   const before = version
                   // oxlint-disable-next-line no-await-in-loop -- cursor catch-up
-                  buffer = await read(after)
+                  const rows = await read(after)
                   if (stopped || state.closed)
                     return { done: true, value: undefined }
+                  buffer = rows
+                  position = 0
                   if (buffer.length || before !== version) continue
                   waiting = defaultSleep(NOTIFY_TIMINGS.safetyReadMs)
                   // oxlint-disable-next-line no-await-in-loop -- wait for a hint or the safety read