experimental-a2 0.3.0 → 0.5.0

package/src/store-sqlite.ts

@@ -0,0 +1,1108 @@
+/**
+ * experimental-a2/store-sqlite — sqlite store backend (the dev default, `.a2/dev.db`).
+ *
+ * Built on `node:sqlite` (Node ≥ 22.13) so it ships with zero
+ * dependencies. Implements the A2Store interface; the conformance suite
+ * in test/conformance is the executable contract.
+ *
+ * The spec's `index` column is stored as `idx` (a2-implementation.md
+ * §11 — `index` collides with a reserved word) and mapped back at the
+ * API boundary. Timestamps are epoch milliseconds written from the
+ * injected clock — never SQL `now()` — so tests can time-travel against
+ * real storage.
+ */
+
+import { mkdirSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+import { A2Error } from './errors.ts'
+import { idempotentReplay } from './idempotent-replay.ts'
+import { decodeReturnedEventIds } from './store-codec.ts'
+import { pollingStream } from './store-polling.ts'
+import {
+  RANDOM_IDS,
+  SYSTEM_CLOCK,
+  type A2Store,
+  type Clock,
+  type Event,
+  type EventCause,
+  type IdSource,
+  type StoredEvent,
+} from './store.ts'
+
+export type SqliteStoreOptions = {
+  /** Database file path. Defaults to `.a2/dev.db`; `:memory:` works. */
+  path?: string
+  /** Injectable clock — every stored timestamp comes from here. */
+  clock?: Clock
+  /** Injectable id source for generated event ids. */
+  ids?: IdSource
+}
+
+export type SqliteStore = A2Store & {
+  /** Close the underlying database handle. */
+  close(): void
+}
+
+const SCHEMA = `
+create table if not exists a2_events (
+  session_id   text    not null,
+  idx          integer not null,
+  event_type   text    not null,
+  payload      text    not null,
+  event_id     text    not null,
+  created_at   integer not null,
+  cause        text,
+  lane         text,
+  lane_ready   integer not null default 0,
+  processed_at integer,
+  processed_by_attempt integer,
+  returned_event_ids text,
+  first_claimed_at integer,
+  last_claimed_at integer,
+  attempt_count integer not null default 0,
+  failure_count integer not null default 0,
+  last_failed_at integer,
+  last_failed_attempt integer,
+  last_error   text,
+  failed_at    integer,
+  claim_holder text,
+  claim_expires_at integer,
+  primary key (session_id, idx)
+) strict;
+
+create unique index if not exists a2_events_event_id on a2_events (event_id);
+create index if not exists a2_events_unprocessed
+  on a2_events (session_id, idx) where processed_at is null;
+create index if not exists a2_events_lane_pending
+  on a2_events (session_id, lane, idx) where processed_at is null;
+create index if not exists a2_events_dispatch_ready
+  on a2_events (session_id, idx)
+  where lane_ready = 1 and processed_at is null and failed_at is null;
+create index if not exists a2_events_claim_expiry
+  on a2_events (session_id, claim_expires_at)
+  where lane_ready = 1 and processed_at is null and failed_at is null;
+
+create table if not exists a2_snapshots (
+  session_id   text    not null,
+  reducer_name text    not null,
+  up_to_index  integer not null,
+  state        text    not null,
+  updated_at   integer not null,
+  primary key (session_id, reducer_name)
+) strict;
+
+create table if not exists a2_presence (
+  ns          text    not null,
+  participant text    not null,
+  field       text    not null,
+  value       text    not null,
+  seen        integer not null,
+  at          integer not null,
+  expires_at  integer not null,
+  primary key (ns, participant, field)
+) strict;
+`
+
+/**
+ * Switching journal modes takes an exclusive lock, and — unlike normal
+ * statements — the switch can return SQLITE_BUSY without consulting the
+ * busy handler while several connections race it (instances cold-booting
+ * against one file). Bounded synchronous retry; the window is boot-only
+ * and tiny. Found by the multi-process torture test.
+ */
+const setWalJournalMode = (db: DatabaseSync): void => {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      db.exec('pragma journal_mode = wal')
+      return
+    } catch (err) {
+      const busy = (err as { errcode?: number }).errcode === 5
+      if (!busy || attempt >= 100) throw err
+      // Synchronous 5ms sleep — sqlite() is a sync constructor.
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5)
+    }
+  }
+}
+
+const wrap = <T>(fn: () => T): T => {
+  try {
+    return fn()
+  } catch (err) {
+    if (err instanceof A2Error || err instanceof TypeError) throw err
+    throw new A2Error('STORE_UNAVAILABLE', 'sqlite store operation failed', {
+      cause: err,
+    })
+  }
+}
+
+const toDate = (ms: number | bigint | null): Date | null =>
+  ms === null ? null : new Date(Number(ms))
+
+const toCause = (json: string | null): EventCause | null => {
+  if (json === null) return null
+  const value = JSON.parse(json) as {
+    index?: unknown
+    attempt?: unknown
+    batchSize?: unknown
+  }
+  if (
+    !Number.isInteger(value.index) ||
+    Number(value.index) < 1 ||
+    !Number.isInteger(value.attempt) ||
+    Number(value.attempt) < 1
+  ) {
+    throw new TypeError('stored event has an invalid cause')
+  }
+  if (
+    value.batchSize !== undefined &&
+    (!Number.isInteger(value.batchSize) || Number(value.batchSize) < 1)
+  ) {
+    throw new TypeError('stored event has an invalid cause')
+  }
+  return {
+    index: Number(value.index),
+    attempt: Number(value.attempt),
+    ...(value.batchSize === undefined
+      ? {}
+      : { batchSize: Number(value.batchSize) }),
+  }
+}
+
+const toStored = (row: EventRow): StoredEvent => ({
+  id: row.event_id,
+  type: row.event_type,
+  payload: JSON.parse(row.payload),
+  index: Number(row.idx),
+  sessionId: row.session_id,
+  createdAt: new Date(Number(row.created_at)),
+  cause: toCause(row.cause),
+  lane: row.lane,
+  processedAt: toDate(row.processed_at),
+  processedByAttempt:
+    row.processed_by_attempt === null ? null : Number(row.processed_by_attempt),
+  returnedEventIds:
+    row.returned_event_ids === null
+      ? null
+      : decodeReturnedEventIds(row.returned_event_ids),
+  firstClaimedAt: toDate(row.first_claimed_at),
+  lastClaimedAt: toDate(row.last_claimed_at),
+  attemptCount: Number(row.attempt_count),
+  failureCount: Number(row.failure_count),
+  lastFailedAt: toDate(row.last_failed_at),
+  lastFailedAttempt:
+    row.last_failed_attempt === null ? null : Number(row.last_failed_attempt),
+  lastError: row.last_error,
+  failedAt: toDate(row.failed_at),
+  claimHolder: row.claim_holder,
+  claimExpiresAt: toDate(row.claim_expires_at),
+})
+
+const toEvent = (row: EventRow): Event => ({
+  id: row.event_id,
+  type: row.event_type,
+  payload: JSON.parse(row.payload),
+  index: Number(row.idx),
+  sessionId: row.session_id,
+  createdAt: new Date(Number(row.created_at)),
+})
+
+type EventRow = {
+  session_id: string
+  idx: number | bigint
+  event_type: string
+  payload: string
+  event_id: string
+  created_at: number | bigint
+  cause: string | null
+  lane: string | null
+  processed_at: number | bigint | null
+  processed_by_attempt: number | bigint | null
+  returned_event_ids: string | null
+  first_claimed_at: number | bigint | null
+  last_claimed_at: number | bigint | null
+  attempt_count: number | bigint
+  failure_count: number | bigint
+  last_failed_at: number | bigint | null
+  last_failed_attempt: number | bigint | null
+  last_error: string | null
+  failed_at: number | bigint | null
+  claim_holder: string | null
+  claim_expires_at: number | bigint | null
+}
+
+type SessionSummaryRow = {
+  session_id: string
+  event_count: number | bigint
+  pending_count: number | bigint
+  failed_count: number | bigint
+  attempt_count: number | bigint
+  failure_count: number | bigint
+  first_event_at: number | bigint
+  updated_at: number | bigint
+}
+
+type SnapshotRow = {
+  reducer_name: string
+  up_to_index: number | bigint
+  updated_at: number | bigint
+}
+
+type PresenceDbRow = {
+  participant: string
+  field: string
+  value: string
+  seen: number | bigint
+  at: number | bigint
+  expires_at: number | bigint
+}
+
+type StateReadRow = Partial<EventRow> & {
+  row_kind: 'snapshot' | 'event'
+  snapshot_index: number | bigint | null
+  snapshot_state: string | null
+}
+
+type AppendStatusRow = {
+  max: number | bigint
+  has_pending: number | bigint
+}
+
+type ExistingEventRow = EventRow & {
+  session_has_pending: number | bigint
+}
+
+export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
+  const path = options.path ?? '.a2/dev.db'
+  const clock = options.clock ?? SYSTEM_CLOCK
+  const generateId = options.ids ?? RANDOM_IDS
+
+  if (path !== ':memory:') {
+    // The dev-default backend only ever runs outside production, but
+    // bundlers can't know that: without the ignore, Turbopack sees a
+    // dynamic fs path and traces the entire project into the output.
+    mkdirSync(dirname(resolve(/* turbopackIgnore: true */ path)), {
+      recursive: true,
+    })
+  }
+  const db = new DatabaseSync(path)
+  // busy_timeout before anything that takes locks: concurrent
+  // cold-opens (several instances booting at once) race the WAL switch
+  // and schema creation.
+  db.exec('pragma busy_timeout = 5000')
+  setWalJournalMode(db)
+  db.exec('pragma synchronous = normal')
+  db.exec(SCHEMA)
+
+  const insertEvent = db.prepare(
+    `insert into a2_events
+       (session_id, idx, event_type, payload, event_id, created_at,
+        cause, lane, lane_ready, processed_at)
+     select ?, ?, ?, ?, ?, ?, ?, ?,
+            case
+              when ? is null then 1
+              when not exists (
+                select 1 from a2_events
+                 where session_id = ? and lane = ? and processed_at is null
+              ) then 1
+              else 0
+            end,
+            ?`,
+  )
+  const promoteLaneHead = db.prepare(
+    `update a2_events set lane_ready = 1
+      where session_id = ?
+        and idx = (
+          select idx from a2_events
+           where session_id = ? and lane = ? and processed_at is null
+           order by idx limit 1
+        )`,
+  )
+  const appendStatus = db.prepare(
+    `select coalesce(
+              (select max(idx) from a2_events where session_id = ?),
+              0
+            ) as max,
+            exists(
+              select 1 from a2_events
+              where session_id = ? and processed_at is null
+            ) as has_pending`,
+  )
+  const upsertPresence = db.prepare(
+    `insert into a2_presence (ns, participant, field, value, seen, at, expires_at)
+     values (?, ?, ?, ?, ?, ?, ?)
+     on conflict (ns, participant, field) do update set
+       value = excluded.value,
+       seen = excluded.seen,
+       at = excluded.at,
+       expires_at = excluded.expires_at
+     where a2_presence.at <= excluded.at`,
+  )
+  const deletePresence = db.prepare(
+    `delete from a2_presence
+      where ns = ? and participant = ? and field = ? and at <= ?`,
+  )
+  const sweepPresence = db.prepare(
+    'delete from a2_presence where ns = ? and expires_at <= ?',
+  )
+  const selectPresence = db.prepare(
+    `select participant, field, value, seen, at, expires_at
+       from a2_presence
+      where ns = ? and expires_at > ?
+      order by participant, field`,
+  )
+  const selectByIds = (count: number) =>
+    db.prepare(
+      `select stored.*,
+              exists(
+                select 1 from a2_events pending
+                where pending.session_id = ?
+                  and pending.processed_at is null
+              ) as session_has_pending
+         from a2_events stored
+        where stored.event_id in (${Array.from({ length: count }, () => '?').join(', ')})
+        order by stored.idx`,
+    )
+
+  const tx = <T>(fn: () => T): T => {
+    db.exec('begin immediate')
+    try {
+      const result = fn()
+      db.exec('commit')
+      return result
+    } catch (err) {
+      try {
+        db.exec('rollback')
+      } catch {
+        // Rollback can fail if the transaction never started; the
+        // original error is what matters.
+      }
+      throw err
+    }
+  }
+
+  return {
+    async append(sessionId, events) {
+      if (events.length === 0) {
+        return wrap(() => {
+          const status = appendStatus.get(
+            sessionId,
+            sessionId,
+          ) as AppendStatusRow
+          return {
+            events: [],
+            hasPending: Number(status.has_pending) === 1,
+          }
+        })
+      }
+      return wrap(() =>
+        tx(() => {
+          const supplied = events.filter((e) => e.id !== undefined)
+          const suppliedIds = supplied.map((e) => e.id as string)
+          if (new Set(suppliedIds).size !== suppliedIds.length) {
+            throw new A2Error(
+              'PARTIAL_DUPLICATE_BATCH',
+              'batch contains the same event id more than once',
+            )
+          }
+          if (suppliedIds.length > 0) {
+            const existing = selectByIds(suppliedIds.length).all(
+              sessionId,
+              ...suppliedIds,
+            ) as unknown as ExistingEventRow[]
+            if (existing.length > 0) {
+              const foreign = existing.find(
+                (row) => row.session_id !== sessionId,
+              )
+              if (foreign) {
+                throw new A2Error(
+                  'PARTIAL_DUPLICATE_BATCH',
+                  `event id '${foreign.event_id}' already exists in another session`,
+                )
+              }
+              if (existing.length === events.length) {
+                return {
+                  events: idempotentReplay(events, existing.map(toStored)),
+                  hasPending: Number(existing[0]!.session_has_pending) === 1,
+                }
+              }
+              throw new A2Error(
+                'PARTIAL_DUPLICATE_BATCH',
+                `batch mixes ${existing.length} already-appended and ${events.length - existing.length} fresh events`,
+              )
+            }
+          }
+
+          // Attempt-currency fence: a fresh handler append commits only
+          // while its causal attempt is still the parent's latest
+          // (store.ts `append`). `begin immediate` serializes this read
+          // against a concurrent claim.
+          for (const e of events) {
+            if (!e.cause) continue
+            const parent = db
+              .prepare(
+                'select attempt_count, failed_at from a2_events where session_id = ? and idx = ?',
+              )
+              .get(sessionId, e.cause.index) as
+              { attempt_count: number | bigint; failed_at: unknown } | undefined
+            if (!parent) {
+              throw new TypeError(
+                `no event at index ${e.cause.index} in session '${sessionId}'`,
+              )
+            }
+            if (
+              Number(parent.attempt_count) !== e.cause.attempt ||
+              parent.failed_at !== null
+            ) {
+              throw new A2Error(
+                'SUPERSEDED_ATTEMPT',
+                `attempt ${e.cause.attempt} no longer owns event ${e.cause.index} in session '${sessionId}'`,
+              )
+            }
+          }
+
+          const status = appendStatus.get(
+            sessionId,
+            sessionId,
+          ) as AppendStatusRow
+          const base = Number(status.max)
+          const now = clock.now().getTime()
+          const inserted: StoredEvent[] = events.map((e, i) => {
+            const id = e.id ?? generateId()
+            const index = base + 1 + i
+            insertEvent.run(
+              sessionId,
+              index,
+              e.type,
+              JSON.stringify(e.payload) ?? 'null',
+              id,
+              now,
+              e.cause ? JSON.stringify(e.cause) : null,
+              e.lane ?? null,
+              e.lane ?? null,
+              sessionId,
+              e.lane ?? null,
+              e.settled ? now : null,
+            )
+            return {
+              id,
+              type: e.type,
+              payload: structuredClone(e.payload),
+              index,
+              sessionId,
+              createdAt: new Date(now),
+              cause: e.cause ? { ...e.cause } : null,
+              lane: e.lane ?? null,
+              processedAt: e.settled ? new Date(now) : null,
+              processedByAttempt: null,
+              returnedEventIds: null,
+              firstClaimedAt: null,
+              lastClaimedAt: null,
+              attemptCount: 0,
+              failureCount: 0,
+              lastFailedAt: null,
+              lastFailedAttempt: null,
+              lastError: null,
+              failedAt: null,
+              claimHolder: null,
+              claimExpiresAt: null,
+            }
+          })
+          return {
+            events: inserted,
+            hasPending:
+              Number(status.has_pending) === 1 ||
+              events.some((event) => event.settled !== true),
+          }
+        }),
+      )
+    },
+
+    async read(sessionId, opts) {
+      return wrap(() => {
+        const conditions = ['session_id = ?']
+        const params: (string | number)[] = [sessionId]
+        if (opts?.afterIndex !== undefined) {
+          conditions.push('idx > ?')
+          params.push(opts.afterIndex)
+        }
+        if (opts?.throughIndex !== undefined) {
+          conditions.push('idx <= ?')
+          params.push(opts.throughIndex)
+        }
+        const rows = db
+          .prepare(
+            `select * from a2_events where ${conditions.join(' and ')} order by idx`,
+          )
+          .all(...params) as unknown as EventRow[]
+        return rows.map(toStored)
+      })
+    },
+
+    async claimAvailable({
+      sessionId,
+      holder,
+      ttlMs,
+      expiresAtMs,
+      excludeIndexes = [],
+    }) {
+      return wrap(() =>
+        tx(() => {
+          const now = clock.now().getTime()
+          const expiresAt = expiresAtMs ?? now + ttlMs
+          const exclusion =
+            excludeIndexes.length === 0
+              ? ''
+              : `and event.idx not in (${excludeIndexes.map(() => '?').join(', ')})`
+          const eligible = db
+            .prepare(
+              `select event.idx
+                 from a2_events event
+                where event.session_id = ?
+                  and event.processed_at is null
+                  and event.failed_at is null
+                  and event.lane_ready = 1
+                  and (event.claim_expires_at is null or event.claim_expires_at <= ?)
+                  ${exclusion}
+                order by event.idx`,
+            )
+            .all(sessionId, now, ...excludeIndexes) as unknown as Array<{
+            idx: number | bigint
+          }>
+          if (eligible.length > 0) {
+            const update = db.prepare(
+              `update a2_events set
+                 attempt_count = attempt_count + 1,
+                 first_claimed_at = coalesce(first_claimed_at, ?),
+                 last_claimed_at = ?,
+                 claim_holder = ?,
+                 claim_expires_at = ?
+               where session_id = ? and idx = ?
+               returning *`,
+            )
+            const events = eligible.map((row) => {
+              const claimed = update.get(
+                now,
+                now,
+                holder,
+                expiresAt,
+                sessionId,
+                row.idx,
+              ) as EventRow
+              return toStored(claimed)
+            })
+            return { outcome: 'claimed', events }
+          }
+
+          const active = db
+            .prepare(
+              `select min(claim_expires_at) as retry_at
+                 from a2_events
+                where session_id = ?
+                  and processed_at is null
+                  and failed_at is null
+                  and lane_ready = 1
+                  and claim_expires_at > ?`,
+            )
+            .get(sessionId, now) as {
+            retry_at: number | bigint | null
+          }
+          return active.retry_at === null
+            ? { outcome: 'settled' }
+            : { outcome: 'busy', retryAt: new Date(Number(active.retry_at)) }
+        }),
+      )
+    },
+
+    async renewClaims({ sessionId, holder, claims, ttlMs, expiresAtMs }) {
+      if (claims.length === 0) return { renewed: [], superseded: [] }
+      return wrap(() =>
+        tx(() => {
+          const now = clock.now().getTime()
+          const expiresAt = expiresAtMs ?? now + ttlMs
+          const renewed: number[] = []
+          const superseded: number[] = []
+          const currentAttempt = db.prepare(
+            'select attempt_count from a2_events where session_id = ? and idx = ?',
+          )
+          const extend = db.prepare(
+            `update a2_events set claim_expires_at = ?
+              where session_id = ?
+                and idx = ?
+                and attempt_count = ?
+                and processed_at is null
+                and failed_at is null
+                and claim_holder = ?
+                and claim_expires_at > ?`,
+          )
+          for (const claim of claims) {
+            const row = currentAttempt.get(sessionId, claim.index) as
+              { attempt_count: number | bigint } | undefined
+            if (!row) continue
+            if (Number(row.attempt_count) > claim.attempt) {
+              superseded.push(claim.index)
+              continue
+            }
+            const updated = extend.run(
+              expiresAt,
+              sessionId,
+              claim.index,
+              claim.attempt,
+              holder,
+              now,
+            )
+            if (Number(updated.changes) === 1) renewed.push(claim.index)
+          }
+          return {
+            renewed: renewed.toSorted((a, b) => a - b),
+            superseded: superseded.toSorted((a, b) => a - b),
+          }
+        }),
+      )
+    },
+
+    async completeAttempt({ sessionId, index, attempt, events }) {
+      return wrap(() =>
+        tx(() => {
+          const parent = db
+            .prepare('select * from a2_events where session_id = ? and idx = ?')
+            .get(sessionId, index) as EventRow | undefined
+          if (!parent) {
+            throw new TypeError(
+              `no event at index ${index} in session '${sessionId}'`,
+            )
+          }
+          const ids = events.map((event) => event.id)
+          if (new Set(ids).size !== ids.length) {
+            throw new A2Error(
+              'PARTIAL_DUPLICATE_BATCH',
+              'returned event batch contains the same event id more than once',
+            )
+          }
+
+          if (parent.processed_at !== null) {
+            if (Number(parent.processed_by_attempt) !== attempt) {
+              return { outcome: 'superseded' }
+            }
+            const returnedIds =
+              parent.returned_event_ids === null
+                ? null
+                : decodeReturnedEventIds(parent.returned_event_ids)
+            if (
+              returnedIds === null ||
+              returnedIds.length !== ids.length ||
+              returnedIds.some((id, offset) => id !== ids[offset])
+            ) {
+              throw new A2Error(
+                'PARTIAL_DUPLICATE_BATCH',
+                'completed attempt does not match the returned event batch',
+              )
+            }
+            const existing =
+              ids.length === 0
+                ? []
+                : (selectByIds(ids.length).all(
+                    sessionId,
+                    ...ids,
+                  ) as unknown as ExistingEventRow[])
+            const byId = new Map(existing.map((row) => [row.event_id, row]))
+            const ordered = ids.map((id) => byId.get(id))
+            if (
+              ordered.some(
+                (row) =>
+                  !row ||
+                  row.session_id !== sessionId ||
+                  row.cause === null ||
+                  toCause(row.cause)?.index !== index ||
+                  toCause(row.cause)?.attempt !== attempt,
+              )
+            ) {
+              throw new A2Error(
+                'PARTIAL_DUPLICATE_BATCH',
+                'returned event retry does not match the committed batch',
+              )
+            }
+            return {
+              outcome: 'completed',
+              events: idempotentReplay(
+                events,
+                (ordered as ExistingEventRow[]).map(toStored),
+              ),
+            }
+          }
+          if (
+            Number(parent.attempt_count) !== attempt ||
+            parent.claim_holder === null ||
+            parent.failed_at !== null
+          ) {
+            return { outcome: 'superseded' }
+          }
+
+          if (
+            ids.length > 0 &&
+            (selectByIds(ids.length).all(sessionId, ...ids) as unknown[])
+              .length > 0
+          ) {
+            throw new A2Error(
+              'PARTIAL_DUPLICATE_BATCH',
+              'returned event batch contains an already-appended event id',
+            )
+          }
+
+          const status = appendStatus.get(
+            sessionId,
+            sessionId,
+          ) as AppendStatusRow
+          const now = clock.now().getTime()
+          db.prepare(
+            `update a2_events set
+               processed_at = ?,
+               processed_by_attempt = ?,
+               returned_event_ids = ?,
+               lane_ready = 0,
+               claim_holder = null,
+               claim_expires_at = null
+             where session_id = ? and idx = ?`,
+          ).run(now, attempt, JSON.stringify(ids), sessionId, index)
+          if (parent.lane !== null) {
+            promoteLaneHead.run(sessionId, sessionId, parent.lane)
+          }
+          const inserted = events.map((event, offset) => {
+            const id = event.id
+            const childIndex = Number(status.max) + offset + 1
+            const cause = { index, attempt }
+            insertEvent.run(
+              sessionId,
+              childIndex,
+              event.type,
+              JSON.stringify(event.payload) ?? 'null',
+              id,
+              now,
+              JSON.stringify(cause),
+              event.lane ?? null,
+              event.lane ?? null,
+              sessionId,
+              event.lane ?? null,
+              event.settled ? now : null,
+            )
+            return toStored(
+              db
+                .prepare(
+                  'select * from a2_events where session_id = ? and idx = ?',
+                )
+                .get(sessionId, childIndex) as EventRow,
+            )
+          })
+          return { outcome: 'completed', events: inserted }
+        }),
+      )
+    },
+
+    async failAttempt({ sessionId, index, attempt, error, maxFailures }) {
+      return wrap(() =>
+        tx(() => {
+          const current = db
+            .prepare('select * from a2_events where session_id = ? and idx = ?')
+            .get(sessionId, index) as EventRow | undefined
+          if (!current) {
+            throw new TypeError(
+              `no event at index ${index} in session '${sessionId}'`,
+            )
+          }
+          const failureCount = Number(current.failure_count)
+          if (
+            current.processed_at !== null ||
+            Number(current.attempt_count) !== attempt
+          ) {
+            return { outcome: 'superseded', failureCount }
+          }
+          if (current.failed_at !== null) {
+            return { outcome: 'dead_lettered', failureCount }
+          }
+          if (
+            current.claim_holder === null &&
+            current.last_failed_attempt !== null &&
+            Number(current.last_failed_attempt) === attempt
+          ) {
+            return { outcome: 'failed', failureCount }
+          }
+          if (current.claim_holder === null) {
+            return { outcome: 'superseded', failureCount }
+          }
+
+          const now = clock.now().getTime()
+          const nextFailureCount = failureCount + 1
+          const deadLettered = nextFailureCount >= maxFailures
+          db.prepare(
+            `update a2_events set
+               failure_count = ?,
+               last_error = ?,
+               last_failed_at = ?,
+               last_failed_attempt = ?,
+               failed_at = ?,
+               claim_holder = null,
+               claim_expires_at = null
+             where session_id = ? and idx = ?`,
+          ).run(
+            nextFailureCount,
+            error,
+            now,
+            attempt,
+            deadLettered ? now : null,
+            sessionId,
+            index,
+          )
+          return {
+            outcome: deadLettered ? 'dead_lettered' : 'failed',
+            failureCount: nextFailureCount,
+          }
+        }),
+      )
+    },
+
+    async readState(sessionId, reducerName) {
+      return wrap(() => {
+        const rows = db
+          .prepare(
+            `with snapshot as materialized (
+             select up_to_index, state
+               from a2_snapshots
+               where session_id = ? and reducer_name = ?
+             )
+             select 0 as row_order, 'snapshot' as row_kind,
+                    snapshot.up_to_index as snapshot_index,
+                    snapshot.state as snapshot_state,
+                    null as session_id, null as idx, null as event_type,
+                    null as payload, null as event_id, null as created_at,
+                    null as cause, null as lane, null as lane_ready,
+                    null as processed_at,
+                    null as processed_by_attempt, null as returned_event_ids,
+                    null as first_claimed_at,
+                    null as last_claimed_at, null as attempt_count,
+                    null as failure_count, null as last_failed_at,
+                    null as last_failed_attempt, null as last_error,
+                    null as failed_at, null as claim_holder,
+                    null as claim_expires_at
+             from snapshot
+             union all
+             select 1 as row_order, 'event' as row_kind,
+                    null as snapshot_index, null as snapshot_state,
+                    event.*
+             from a2_events as event
+             where event.session_id = ?
+               and event.idx > coalesce((select up_to_index from snapshot), 0)
+             order by row_order, idx`,
+          )
+          .all(sessionId, reducerName, sessionId) as unknown as StateReadRow[]
+        const snapshot = rows.find((row) => row.row_kind === 'snapshot')
+        return {
+          snapshot: snapshot
+            ? {
+                index: Number(snapshot.snapshot_index),
+                state: JSON.parse(snapshot.snapshot_state!),
+              }
+            : null,
+          events: rows
+            .filter(
+              (row): row is StateReadRow & EventRow => row.row_kind === 'event',
+            )
+            .map(toEvent),
+        }
+      })
+    },
+
+    async putSnapshot(sessionId, reducerName, index, state) {
+      wrap(() => {
+        // Guarded upsert: a slower concurrent writer must never clobber
+        // a further-along snapshot (spec §3).
+        db.prepare(
+          `insert into a2_snapshots (session_id, reducer_name, up_to_index, state, updated_at)
+           values (?, ?, ?, ?, ?)
+           on conflict (session_id, reducer_name) do update set
+             up_to_index = excluded.up_to_index,
+             state = excluded.state,
+             updated_at = excluded.updated_at
+           where excluded.up_to_index > a2_snapshots.up_to_index`,
+        ).run(
+          sessionId,
+          reducerName,
+          index,
+          JSON.stringify(state) ?? 'null',
+          clock.now().getTime(),
+        )
+      })
+    },
+
+    presence: {
+      async set(ns, participant, values, meta) {
+        const entries = Object.entries(values)
+        if (entries.length === 0) return
+        wrap(() =>
+          tx(() => {
+            const atMs = meta.at.getTime()
+            // Expiry anchors on the storage clock — the sender's `at`
+            // orders writes but never anchors their lifetime.
+            const expiresAtMs = clock.now().getTime() + meta.ttlMs
+            for (const [field, value] of entries) {
+              // Field-wise LWW: a stored row with a strictly newer `at`
+              // survives; ties go to the incoming write (memory parity).
+              if (value === null) {
+                deletePresence.run(ns, participant, field, atMs)
+              } else {
+                upsertPresence.run(
+                  ns,
+                  participant,
+                  field,
+                  JSON.stringify(value) ?? 'null',
+                  meta.seen,
+                  atMs,
+                  expiresAtMs,
+                )
+              }
+            }
+          }),
+        )
+      },
+
+      async read(ns) {
+        return wrap(() => {
+          const now = clock.now().getTime()
+          // The sweep is opportunistic cleanup; the select's filter
+          // alone keeps expired rows out of this result.
+          sweepPresence.run(ns, now)
+          const rows = selectPresence.all(ns, now) as unknown as PresenceDbRow[]
+          return rows.map((row) => ({
+            participant: row.participant,
+            field: row.field,
+            value: JSON.parse(row.value) as unknown,
+            seen: Number(row.seen),
+            at: new Date(Number(row.at)),
+            expiresAt: new Date(Number(row.expires_at)),
+          }))
+        })
+      },
+    },
+
+    inspect: {
+      async listSessions(inspectionOptions) {
+        return wrap(() => {
+          const conditions = ['substr(session_id, 1, ?) = ?']
+          const params: (string | number)[] = [
+            inspectionOptions.prefix.length,
+            inspectionOptions.prefix,
+          ]
+          if (inspectionOptions.cursor !== undefined) {
+            conditions.push('session_id > ?')
+            params.push(inspectionOptions.cursor)
+          }
+          params.push(inspectionOptions.limit + 1)
+          const rows = db
+            .prepare(
+              `select
+                 session_id,
+                 count(*) as event_count,
+                 sum(case when processed_at is null and failed_at is null then 1 else 0 end) as pending_count,
+                 sum(case when failed_at is not null then 1 else 0 end) as failed_count,
+                 sum(attempt_count) as attempt_count,
+                 sum(failure_count) as failure_count,
+                 min(created_at) as first_event_at,
+                 max(max(
+                   created_at,
+                   coalesce(first_claimed_at, 0),
+                   coalesce(last_claimed_at, 0),
+                   coalesce(last_failed_at, 0),
+                   coalesce(processed_at, 0),
+                   coalesce(failed_at, 0)
+                 )) as updated_at
+               from a2_events
+               where ${conditions.join(' and ')}
+               group by session_id
+               order by session_id
+               limit ?`,
+            )
+            .all(...params) as unknown as SessionSummaryRow[]
+          const hasMore = rows.length > inspectionOptions.limit
+          const visible = rows.slice(0, inspectionOptions.limit)
+          return {
+            sessions: visible.map((row) => ({
+              sessionId: row.session_id,
+              eventCount: Number(row.event_count),
+              pendingCount: Number(row.pending_count),
+              failedCount: Number(row.failed_count),
+              attemptCount: Number(row.attempt_count),
+              failureCount: Number(row.failure_count),
+              firstEventAt: new Date(Number(row.first_event_at)),
+              updatedAt: new Date(Number(row.updated_at)),
+            })),
+            cursor: hasMore ? (visible.at(-1)?.session_id ?? null) : null,
+          }
+        })
+      },
+      async readEvents(sessionId, pageOptions) {
+        return wrap(() => {
+          const currentFrontier = Number(
+            (
+              db
+                .prepare(
+                  'select coalesce(max(idx), 0) as frontier from a2_events where session_id = ?',
+                )
+                .get(sessionId) as { frontier: number }
+            ).frontier,
+          )
+          const throughIndex = Math.min(
+            pageOptions.throughIndex ?? currentFrontier,
+            currentFrontier,
+          )
+          const rows = db
+            .prepare(
+              `select * from a2_events
+                where session_id = ? and idx > ? and idx <= ?
+                order by idx limit ?`,
+            )
+            .all(
+              sessionId,
+              pageOptions.afterIndex,
+              throughIndex,
+              pageOptions.limit,
+            ) as unknown as EventRow[]
+          return { events: rows.map(toStored), throughIndex }
+        })
+      },
+      async listSnapshots(sessionId) {
+        return wrap(() => {
+          const rows = db
+            .prepare(
+              `select reducer_name, up_to_index, updated_at
+               from a2_snapshots where session_id = ? order by reducer_name`,
+            )
+            .all(sessionId) as unknown as SnapshotRow[]
+          return rows.map((row) => ({
+            reducerName: row.reducer_name,
+            index: Number(row.up_to_index),
+            updatedAt: new Date(Number(row.updated_at)),
+          }))
+        })
+      },
+    },
+
+    stream(sessionId, opts) {
+      const readAfter = (afterIndex: number): StoredEvent[] =>
+        wrap(() => {
+          const rows = db
+            .prepare(
+              'select * from a2_events where session_id = ? and idx > ? order by idx',
+            )
+            .all(sessionId, afterIndex) as unknown as EventRow[]
+          return rows.map(toStored)
+        })
+      return pollingStream(
+        readAfter,
+        opts?.startAfter !== undefined ? { startAfter: opts.startAfter } : {},
+      )
+    },
+
+    close() {
+      db.close()
+    },
+  }
+}