experimental-a2 0.4.0 → 0.5.1

package/src/store.ts

@@ -0,0 +1,385 @@
+/**
+ * The A2Store interface — the storage contract every store backend
+ * implements. See specs/a2-implementation.md §2–3.
+ *
+ * This is the whole storage contract: append, read, dispatch claims,
+ * failure markers, snapshots, and the live stream. The scheduler
+ * needs nothing extra — the armed queue message is its own state, and
+ * the store is the only thing it consults.
+ */
+
+import type { PresencePatch } from './contract.ts'
+
+/** A stored event, as the public API exposes it. */
+export type Event = {
+  id: string
+  type: string
+  payload: unknown
+  /** Position in the session's event log, from 1. */
+  index: number
+  sessionId: string
+  createdAt: Date
+}
+
+/** The handler dispatch whose append first persisted a child event. */
+export type EventCause = {
+  index: number
+  attempt: number
+  /** Size of one named handler append, used to reject truncated retries. */
+  batchSize?: number
+}
+
+/**
+ * What the store persists: immutable event history, including its causal edge,
+ * plus derived dispatch and failure bookkeeping. The bookkeeping is disposable;
+ * the event and its cause are not.
+ */
+export type StoredEvent = Event & {
+  /** Same-session handler dispatch that appended this event; null means root. */
+  cause: EventCause | null
+  /** Session-scoped serial execution key resolved when the event is appended. */
+  lane: string | null
+  /** Adapter clock time recorded by append settlement, completion, or manual skip; null while pending. */
+  processedAt: Date | null
+  /** Dispatch attempt that completed this event; null without dispatch or while pending. */
+  processedByAttempt: number | null
+  /** Exact ordered child ids atomically returned by the completing attempt. */
+  returnedEventIds: string[] | null
+  /** Adapter clock time recorded by the first durable dispatch claim. */
+  firstClaimedAt: Date | null
+  /** Adapter clock time recorded by the most recent durable dispatch claim. */
+  lastClaimedAt: Date | null
+  /** Durable dispatch claims, including claims abandoned by hard kills. */
+  attemptCount: number
+  /** Current dispatch holder; null when the event is not claimed. */
+  claimHolder: string | null
+  /** Adapter clock expiry for the current dispatch claim. */
+  claimExpiresAt: Date | null
+  /** Caught handler failures. This alone drives dead-lettering. */
+  failureCount: number
+  /** Adapter clock time recorded by the most recent caught handler failure. */
+  lastFailedAt: Date | null
+  /** Dispatch attempt that produced the most recent caught handler failure. */
+  lastFailedAttempt: number | null
+  /** The last handler failure, stringified. */
+  lastError: string | null
+  /** Adapter clock time recorded when dead-lettered; null otherwise. */
+  failedAt: Date | null
+}
+
+/** Durable, read-only session metadata for administrative inspection. */
+export type StoredSessionSummary = {
+  sessionId: string
+  eventCount: number
+  pendingCount: number
+  failedCount: number
+  /** Durable dispatch claims across every event in the session. */
+  attemptCount: number
+  /** Caught handler failures across every event in the session. */
+  failureCount: number
+  firstEventAt: Date
+  updatedAt: Date
+}
+
+/**
+ * One live presence value, as `A2Store.presence.read` returns it. The
+ * row is the LWW unit — one participant's one field. `at` is the
+ * sender's stamp, the LWW comparator. `expiresAt` is the storage's
+ * own clock at the applied set plus its `ttlMs` — never derived from
+ * the sender stamp; a row is live strictly before it.
+ */
+export type PresenceRow = {
+  participant: string
+  field: string
+  value: unknown
+  seen: number
+  at: Date
+  expiresAt: Date
+}
+
+/** Metadata for the latest cached fold of one reducer. */
+export type StoredSnapshot = {
+  reducerName: string
+  index: number
+  updatedAt: Date
+}
+
+/** One consistent cache-plus-tail read for a reducer fold. */
+export type StoreStateRead = {
+  /** The latest cached fold for this reducer, if one exists. */
+  snapshot: { index: number; state: unknown } | null
+  /** Immutable events strictly after `snapshot.index`, or the full log on a miss. */
+  events: Event[]
+}
+
+export type StoredSessionPage = {
+  sessions: StoredSessionSummary[]
+  /** Opaque backend cursor; null means there is no next page. */
+  cursor: string | null
+}
+
+export type StoredEventPage = {
+  events: StoredEvent[]
+  /** Fixed inclusive log frontier shared by every page in one inspection. */
+  throughIndex: number
+}
+
+/**
+ * Optional read-only administration implemented by A2's shipped stores.
+ * It is separate from the correctness contract so custom stores do not
+ * need to expose storage-wide discovery merely to process events.
+ */
+export type A2StoreInspection = {
+  listSessions(options: {
+    /** Storage namespace prefix, including the contract separator. */
+    prefix: string
+    cursor?: string
+    limit: number
+  }): Promise<StoredSessionPage>
+  /**
+   * A bounded event page for read-only administration. The first page captures
+   * `throughIndex`; callers pass it back so concurrent appends cannot extend a
+   * walk indefinitely. Optional for custom stores; A2 falls back to `read()`.
+   */
+  readEvents?(
+    sessionId: string,
+    options: { afterIndex: number; throughIndex?: number; limit: number },
+  ): Promise<StoredEventPage>
+  listSnapshots(sessionId: string): Promise<StoredSnapshot[]>
+}
+
+/** The result of atomically claiming every currently eligible event. */
+export type StoreClaimAvailableResult =
+  | { outcome: 'claimed'; events: StoredEvent[] }
+  | { outcome: 'busy'; retryAt: Date }
+  | { outcome: 'settled' }
+
+/** A completion may lose to a newer claim or an earlier completion. */
+export type CompleteAttemptResult =
+  { outcome: 'completed'; events: StoredEvent[] } | { outcome: 'superseded' }
+
+/** The result of one claim-renewal heartbeat, both lists in append order. */
+export type RenewClaimsResult = {
+  /** Listed claims that remain owned by the holder. */
+  renewed: number[]
+  /** Listed claims whose event a newer attempt has durably taken. */
+  superseded: number[]
+}
+
+/** The result of atomically recording a caught handler failure. */
+export type FailAttemptResult = {
+  outcome: 'failed' | 'dead_lettered' | 'superseded'
+  failureCount: number
+}
+
+/** Input to `A2Store.append` — already validated by the machine. */
+export type AppendEvent = {
+  type: string
+  payload: unknown
+  /** Caller-supplied idempotency key; generated when absent. */
+  id?: string
+  /** Internal causal edge supplied atomically by handler `session.append`. */
+  cause?: EventCause
+  /** Session-scoped serial execution key resolved before persistence. */
+  lane?: string
+  /** Internal hint: settle this event in the append transaction; no handler is registered. */
+  settled?: true
+}
+
+/** A handler-returned event with the deterministic id retries require. */
+export type ReturnedEvent = AppendEvent & { id: string }
+
+/** The rows written by an append and the session's pending state. */
+export type StoreAppendResult = {
+  events: StoredEvent[]
+  /** Whether the session contains an event without a completion marker. */
+  hasPending: boolean
+}
+
+/**
+ * An injectable clock. Adapters take one so tests can drive claim
+ * expiry, failure timestamps, and (later) stuck-session detection
+ * deterministically — against real storage, no mocking.
+ */
+export type Clock = {
+  now(): Date
+}
+
+/** An injectable id source for generated event ids. */
+export type IdSource = () => string
+
+export const SYSTEM_CLOCK: Clock = {
+  now: () => new Date(),
+}
+
+export const RANDOM_IDS: IdSource = () => crypto.randomUUID()
+
+export interface A2Store {
+  /**
+   * Accepts a batch; the batch is atomic — one transaction, consecutive
+   * `index`es, all-or-nothing. The idempotency key covers the whole
+   * operation, not each item: if *every* event's `id` already exists in
+   * this session, this is a retry of a committed batch whose ack was
+   * lost — return the existing rows as success. If only *some* ids
+   * exist, the caller mixed an already-sent batch with fresh events —
+   * always a caller bug — so throw `A2Error('PARTIAL_DUPLICATE_BATCH')`.
+   * Events carrying `settled: true` get `processedAt` in this same atomic
+   * operation, with no dispatch claim or `processedByAttempt`. The result's
+   * `hasPending` reflects the whole session in the same atomic operation,
+   * including older events and idempotent retries.
+   *
+   * An event carrying `cause` is a handler append, fenced by attempt
+   * currency: accept it only while `cause.attempt` is still the parent
+   * event's latest attempt and the parent is not dead-lettered; otherwise
+   * throw `A2Error('SUPERSEDED_ATTEMPT')` and write nothing. The check is
+   * part of this atomic operation and must serialize against a concurrent
+   * `claimAvailable` — an unlocked read of the parent admits write skew.
+   * The idempotent-replay path runs first, so a batch whose ids all exist
+   * replays regardless of the current attempt.
+   */
+  append(sessionId: string, events: AppendEvent[]): Promise<StoreAppendResult>
+
+  /** Events for one session, oldest first. Bounds form `(afterIndex, throughIndex]`. */
+  read(
+    sessionId: string,
+    opts?: { afterIndex?: number; throughIndex?: number },
+  ): Promise<StoredEvent[]>
+
+  /**
+   * Atomically claims every eligible pending event. Unlaned events are all
+   * independently eligible. Within a lane, only the lowest-index unfinished
+   * event is eligible. A live claim produces `busy` only when it is the sole
+   * remaining obstacle to actionable work. Claimed events are returned in event-log
+   * order. Excluded rows remain lane barriers.
+   */
+  claimAvailable(options: {
+    sessionId: string
+    holder: string
+    ttlMs: number
+    expiresAtMs?: number
+    excludeIndexes?: readonly number[]
+  }): Promise<StoreClaimAvailableResult>
+
+  /**
+   * Renews the listed live claims still owned by `holder`. Each listed claim
+   * carries the attempt ordinal the holder owns. `renewed` lists the claims
+   * that remain owned after the operation; `superseded` lists the claims
+   * whose event's `attemptCount` has durably passed the listed attempt. An
+   * expired claim no successor has taken appears in neither list — its
+   * attempt may still complete (`completeAttempt` is the fence), so it is
+   * not reported as lost. Renewal never revives an expired claim.
+   */
+  renewClaims(options: {
+    sessionId: string
+    holder: string
+    claims: readonly { index: number; attempt: number }[]
+    ttlMs: number
+    expiresAtMs?: number
+  }): Promise<RenewClaimsResult>
+
+  /**
+   * Atomically completes one current attempt and appends its returned events.
+   * Retrying a committed completion with the same attempt and deterministic
+   * child ids returns the existing children. A stale attempt never appends.
+   */
+  completeAttempt(options: {
+    sessionId: string
+    index: number
+    attempt: number
+    events: ReturnedEvent[]
+  }): Promise<CompleteAttemptResult>
+
+  /**
+   * Atomically records a caught failure for one claimed attempt. A stale
+   * attempt cannot poison a processed event or a newer dispatch. Accepted
+   * failures record the operation's clock time.
+   */
+  failAttempt(options: {
+    sessionId: string
+    index: number
+    attempt: number
+    error: string
+    maxFailures: number
+  }): Promise<FailAttemptResult>
+
+  /**
+   * Reads a reducer snapshot and its event tail as one consistent adapter
+   * operation. On a cache miss, `snapshot` is null and `events` is the full
+   * log. The snapshot is untrusted; core may reject it and issue a full
+   * `read()` when its state schema no longer accepts the cached value.
+   */
+  readState(sessionId: string, reducerName: string): Promise<StoreStateRead>
+
+  /**
+   * Optional batched `readState` — one consistent snapshot-plus-tail read
+   * per session id, aligned positionally with the input (duplicates
+   * allowed). Each element has its own frontier; the batch makes no
+   * cross-session consistency claim. Core falls back to parallel
+   * `readState` calls when absent.
+   */
+  readStates?(
+    sessionIds: string[],
+    reducerName: string,
+  ): Promise<StoreStateRead[]>
+
+  /**
+   * Writes a disposable reducer cache. Guard this operation so a slower
+   * concurrent writer can never clobber a further-along snapshot
+   * (`where up_to_index < excluded.up_to_index`).
+   */
+  putSnapshot(
+    sessionId: string,
+    reducerName: string,
+    index: number,
+    state: unknown,
+  ): Promise<void>
+
+  /**
+   * Optional ephemeral-plane capability (specs/a2-implementation.md
+   * §15.1) — optional like snapshots are. Values arrive already
+   * validated by core; adapters store them opaquely. Presence never
+   * touches the event log: no index, no history row, no recovery arm.
+   */
+  presence?: {
+    /**
+     * Field-wise last-writer-wins merge of one participant's values:
+     * a field whose existing row has a strictly newer `at` (the
+     * sender's stamp) is left untouched; `null` deletes the row. Every
+     * applied write refreshes that field's expiry to the storage's own
+     * clock plus `ttlMs` — the sender stamp orders writes but never
+     * anchors their lifetime.
+     */
+    set(
+      ns: string,
+      participant: string,
+      values: Record<string, unknown | null>,
+      meta: { seen: number; at: Date; ttlMs: number },
+    ): Promise<void>
+
+    /** The current map, pruned of rows at or past their `expiresAt`. */
+    read(ns: string): Promise<PresenceRow[]>
+
+    /**
+     * Push-tier patch delivery; present only on backends with a real
+     * broadcast primitive. Without it the backend is the degraded
+     * tier: live feeds surface presence by re-reading on their
+     * existing poll cadence.
+     */
+    subscribe?(ns: string, onPatch: (patch: PresencePatch) => void): () => void
+  }
+
+  /** Read-only operational data used by `experimental-a2/devtools/server`. */
+  inspect?: A2StoreInspection
+
+  /**
+   * A live feed of one session's events, starting after `startAfter`
+   * (exclusive). Transport is the backend's choice — in-process pub/sub,
+   * polling, LISTEN/NOTIFY — callers never branch on which. The iterable
+   * ends when the consumer calls `return()` (e.g. a disconnecting SSE
+   * client) and must deliver events appended after subscription.
+   */
+  stream(
+    sessionId: string,
+    opts?: { startAfter?: number },
+  ): AsyncIterable<Event>
+}

package/src/telemetry.ts

@@ -0,0 +1,54 @@
+/**
+ * The A2Telemetry interface — the instrumentation seam. Same philosophy
+ * as store backends: the interface lives in core, implementations ship as
+ * entry points (`experimental-a2/otel` adapts it to OpenTelemetry). Without
+ * one, spans are free and swallowed errors print to the console.
+ */
+
+/** Attribute values a2 emits. */
+export type A2AttributeValue = string | number | boolean
+
+/** The spans a2 emits today. The catalogue grows with the surface. */
+export type A2SpanName = 'a2.append' | 'a2.drain' | 'a2.event' | 'a2.state'
+
+export type A2SpanHandle = {
+  /** Attach or update an attribute mid-span (e.g. the outcome). */
+  setAttribute(key: string, value: A2AttributeValue): void
+  /**
+   * Mark the span failed without a2's control flow throwing — used for
+   * handler failures, which a2 swallows by design (they go into the
+   * retry machinery, not up the stack) but telemetry must still see.
+   */
+  recordError(error: unknown): void
+}
+
+export type A2Telemetry = {
+  /**
+   * Wrap one unit of a2 work. Implementations should time it, record a
+   * thrown error as a failure, propagate context so nested spans tree
+   * up, and always return `fn`'s result (or rethrow its error) —
+   * telemetry observes, it never alters behavior.
+   */
+  span<T>(
+    name: A2SpanName,
+    attributes: Record<string, A2AttributeValue>,
+    fn: (span: A2SpanHandle) => Promise<T>,
+  ): Promise<T>
+}
+
+/**
+ * The default when no telemetry is configured. Spans cost nothing, but
+ * `recordError` prints: it only ever receives errors a2 swallows by
+ * design, so without a configured sink the console is the one place
+ * they can surface. Passing `telemetry` replaces this sink wholesale.
+ */
+export const CONSOLE_TELEMETRY: A2Telemetry = {
+  span: (name, attributes, fn) =>
+    fn({
+      setAttribute: () => {},
+      recordError: (error) => {
+        // oxlint-disable-next-line no-console -- the whole point: swallowed errors must surface without configuration
+        console.error(`[a2] error in ${name}`, attributes, error)
+      },
+    }),
+}

package/src/testing.browser.ts

@@ -0,0 +1,5 @@
+/** experimental-a2/testing loads local capture files and is Node-only. */
+throw new Error(
+  'experimental-a2/testing is Node-only. Load captures in a local test or script.',
+)
+export {}

package/src/testing.ts

@@ -0,0 +1,185 @@
+/**
+ * Offline helpers for loading a captured A2 session and replaying its events
+ * through the application's current reducers. This module never constructs a
+ * server or dispatches handlers.
+ */
+
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import type { Contract, ContractEvent, EventDefs } from './contract.ts'
+import {
+  parseDevtoolsCapture,
+  verifyDevtoolsCapture,
+  type DevtoolsCapture,
+  type DevtoolsCaptureEvent,
+} from './devtools.ts'
+import type { Reducer } from './reducer.ts'
+import { validateSync } from './validate.ts'
+
+export type CaptureSource = string | URL
+
+export type LoadedCapture<D extends EventDefs> = {
+  /** The verified capture, including its footer and operational records. */
+  readonly capture: DevtoolsCapture
+  /** The contract used to validate and type the captured event history. */
+  readonly contract: Contract<D>
+  /** Contract-typed public events with `createdAt` revived to `Date`. */
+  readonly events: readonly ContractEvent<D>[]
+  /** Unmodified wire events, including dispatch and failure metadata. */
+  readonly rawEvents: readonly DevtoolsCaptureEvent[]
+}
+
+export type ReplayCaptureOptions = {
+  /** Fold events through this log index, inclusive. Zero means no events. */
+  throughIndex?: number
+}
+
+export type CaptureReplay<S> = {
+  readonly state: S
+  /** The last event index actually folded, or zero for the initial state. */
+  readonly index: number
+}
+
+const captureError = (message: string): TypeError =>
+  new TypeError(`invalid A2 capture: ${message}`)
+
+const typedEvents = <D extends EventDefs>(
+  capture: DevtoolsCapture,
+  contract: Contract<D>,
+): ContractEvent<D>[] => {
+  const events: ContractEvent<D>[] = []
+  for (const event of capture.events) {
+    const schema = Object.hasOwn(contract.events, event.type)
+      ? contract.events[event.type]
+      : undefined
+    if (schema === undefined) {
+      throw captureError(
+        `contract '${contract.name}' has no event type '${event.type}' at index ${event.index}`,
+      )
+    }
+    const result = validateSync(
+      schema,
+      structuredClone(event.payload),
+      `captured event '${event.type}'`,
+    )
+    if (result.issues !== undefined) {
+      throw captureError(
+        `event #${event.index} '${event.type}' has an invalid payload: ${result.issues
+          .map((issue) => issue.message)
+          .join('; ')}`,
+      )
+    }
+    events.push({
+      id: event.id,
+      type: event.type,
+      payload: result.value,
+      index: event.index,
+      sessionId: event.sessionId,
+      createdAt: new Date(event.createdAt),
+    } as ContractEvent<D>)
+  }
+  return events
+}
+
+/** Validate an already-parsed capture against an application's contract. */
+export async function prepareCapture<D extends EventDefs>(
+  capture: DevtoolsCapture,
+  contract: Contract<D>,
+): Promise<LoadedCapture<D>> {
+  await verifyDevtoolsCapture(capture)
+  if (capture.contract !== contract.name) {
+    throw captureError(
+      `expected contract '${contract.name}', received '${capture.contract}'`,
+    )
+  }
+  return {
+    capture,
+    contract,
+    events: typedEvents(capture, contract),
+    rawEvents: capture.events,
+  }
+}
+
+const displayUrl = (url: URL): string => {
+  if (url.protocol === 'data:') return 'data: URL'
+  const safe = new URL(url)
+  safe.username = ''
+  safe.password = ''
+  safe.search = ''
+  safe.hash = ''
+  return safe.href
+}
+
+const fetchCapture = async (url: URL): Promise<Uint8Array> => {
+  const location = displayUrl(url)
+  let response: Response
+  try {
+    response = await fetch(url)
+  } catch {
+    throw new Error(`failed to load A2 capture from '${location}'`)
+  }
+  if (!response.ok) {
+    throw new Error(
+      `failed to load A2 capture from '${location}': ${response.status} ${response.statusText}`,
+    )
+  }
+  return new Uint8Array(await response.arrayBuffer())
+}
+
+const readCapture = async (source: CaptureSource): Promise<Uint8Array> => {
+  if (source instanceof URL) {
+    return source.protocol === 'file:'
+      ? readFile(fileURLToPath(source))
+      : fetchCapture(source)
+  }
+  if (/^[a-z]:[\\/]/i.test(source)) return readFile(source)
+  let url: URL | undefined
+  try {
+    url = new URL(source)
+  } catch {
+    return readFile(source)
+  }
+  return readCapture(url)
+}
+
+/** Load, integrity-check, and contract-type a `.a2log` file or URL. */
+export async function loadCapture<D extends EventDefs>(
+  source: CaptureSource,
+  contract: Contract<D>,
+): Promise<LoadedCapture<D>> {
+  const encoded = await readCapture(source)
+  const capture = parseDevtoolsCapture(encoded)
+  return prepareCapture(capture, contract)
+}
+
+const cloneInitial = <S>(initialState: S): S => {
+  try {
+    return structuredClone(initialState)
+  } catch {
+    return initialState
+  }
+}
+
+/** Purely fold captured events through a reducer, optionally to a cutpoint. */
+export function replayCapture<D extends EventDefs, S>(
+  loaded: LoadedCapture<D>,
+  reducer: Reducer<D, S>,
+  options: ReplayCaptureOptions = {},
+): CaptureReplay<S> {
+  const { throughIndex } = options
+  if (
+    throughIndex !== undefined &&
+    (!Number.isInteger(throughIndex) || throughIndex < 0)
+  ) {
+    throw new TypeError('throughIndex must be a non-negative integer')
+  }
+
+  let state = cloneInitial(reducer.initialState)
+  let index = 0
+  for (const event of loaded.events) {
+    if (throughIndex !== undefined && event.index > throughIndex) break
+    state = reducer.fold(state, event)
+    index = event.index
+  }
+  return { state, index }
+}

package/src/validate.ts

@@ -0,0 +1,39 @@
+import type { StandardSchemaV1 } from './standard-schema.ts'
+
+/**
+ * Run a Standard Schema validator, requiring a synchronous result.
+ * Validators must be synchronous (specs/a2-api.md §1) — an async one is
+ * a definition bug, rejected at definition time where possible and here
+ * as a backstop. `what` names the schema in error messages, e.g.
+ * "event 'created'" or "the stateSchema".
+ */
+export function validateSync<Input, Output>(
+  schema: StandardSchemaV1<Input, Output>,
+  value: unknown,
+  what: string,
+): StandardSchemaV1.Result<Output> {
+  const result = schema['~standard'].validate(value)
+  if (result instanceof Promise) {
+    throw new TypeError(
+      `the schema for ${what} is asynchronous — a2 schemas must validate synchronously`,
+    )
+  }
+  return result
+}
+
+/**
+ * Probe a schema to reject always-async validators early. The probe
+ * value is deliberately garbage — we only care whether the result is a
+ * Promise, not whether it passes.
+ */
+export function assertSyncSchema(schema: StandardSchemaV1, what: string): void {
+  const probe = Symbol('a2.schema-probe')
+  const result = schema['~standard'].validate(probe)
+  if (result instanceof Promise) {
+    // Swallow the eventual rejection — the probe input was garbage.
+    result.catch(() => {})
+    throw new TypeError(
+      `the schema for ${what} is asynchronous — a2 schemas must validate synchronously`,
+    )
+  }
+}