experimental-a2 0.6.0 → 0.8.0

package/src/store-redis-http.ts

@@ -95,14 +95,13 @@ export function redisHttp(options: RedisHttpStoreOptions): RedisHttpStore {
     completeAttempt: core.completeAttempt,
     failAttempt: core.failAttempt,
     readState: core.readState,
-    putSnapshot: core.putSnapshot,
+    putSnapshots: core.putSnapshots,
     presence: {
       async set(ns, participant, values, meta) {
         await core.presence.set(ns, participant, values, meta)
       },
       read: core.presence.read,
     },
-    inspect: core.inspect,
 
     stream(sessionId, opts) {
       return pollingStream(

package/src/store-redis.ts

@@ -291,8 +291,7 @@ export function redis(options: RedisStoreOptions = {}): RedisStore {
     completeAttempt: core.completeAttempt,
     failAttempt: core.failAttempt,
     readState: core.readState,
-    putSnapshot: core.putSnapshot,
-    inspect: core.inspect,
+    putSnapshots: core.putSnapshots,
 
     presence: {
       async set(ns, participant, values, meta) {

package/src/store-sqlite.ts

@@ -92,6 +92,26 @@ create table if not exists a2_snapshots (
   primary key (session_id, reducer_name)
 ) strict;
 
+create table if not exists a2_snapshot_history (
+  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, up_to_index)
+) strict;
+
+create table if not exists a2_snapshot_pins (
+  session_id   text    not null,
+  event_index  integer not null,
+  reducer_name text    not null,
+  up_to_index  integer not null,
+  primary key (session_id, event_index, reducer_name, up_to_index)
+) strict;
+
+create index if not exists a2_snapshot_pins_checkpoint
+  on a2_snapshot_pins (session_id, reducer_name, up_to_index);
+
 create table if not exists a2_presence (
   ns          text    not null,
   participant text    not null,
@@ -231,23 +251,6 @@ type EventRow = {
   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
@@ -259,10 +262,17 @@ type PresenceDbRow = {
 
 type StateReadRow = Partial<EventRow> & {
   row_kind: 'snapshot' | 'event'
+  head_index: number | bigint | null
   snapshot_index: number | bigint | null
   snapshot_state: string | null
 }
 
+type SnapshotHeadRow = {
+  up_to_index: number | bigint
+  state: string
+  updated_at: number | bigint
+}
+
 type AppendStatusRow = {
   max: number | bigint
   has_pending: number | bigint
@@ -764,6 +774,19 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
                claim_expires_at = null
              where session_id = ? and idx = ?`,
           ).run(now, attempt, JSON.stringify(ids), sessionId, index)
+          db.prepare(
+            'delete from a2_snapshot_pins where session_id = ? and event_index = ?',
+          ).run(sessionId, index)
+          db.prepare(
+            `delete from a2_snapshot_history
+              where session_id = ?
+                and not exists (
+                  select 1 from a2_snapshot_pins pin
+                   where pin.session_id = a2_snapshot_history.session_id
+                     and pin.reducer_name = a2_snapshot_history.reducer_name
+                     and pin.up_to_index = a2_snapshot_history.up_to_index
+                )`,
+          ).run(sessionId)
           if (parent.lane !== null) {
             promoteLaneHead.run(sessionId, sessionId, parent.lane)
           }
@@ -852,6 +875,21 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
             sessionId,
             index,
           )
+          if (deadLettered) {
+            db.prepare(
+              'delete from a2_snapshot_pins where session_id = ? and event_index = ?',
+            ).run(sessionId, index)
+            db.prepare(
+              `delete from a2_snapshot_history
+                where session_id = ?
+                  and not exists (
+                    select 1 from a2_snapshot_pins pin
+                     where pin.session_id = a2_snapshot_history.session_id
+                       and pin.reducer_name = a2_snapshot_history.reducer_name
+                       and pin.up_to_index = a2_snapshot_history.up_to_index
+                  )`,
+            ).run(sessionId)
+          }
           return {
             outcome: deadLettered ? 'dead_lettered' : 'failed',
             failureCount: nextFailureCount,
@@ -860,18 +898,32 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
       )
     },
 
-    async readState(sessionId, reducerName) {
+    async readState(sessionId, reducerName, stateOptions) {
       return wrap(() => {
+        const throughIndex = stateOptions?.throughIndex ?? null
+        const snapshotThroughIndex =
+          stateOptions?.snapshotThroughIndex ?? throughIndex
         const rows = db
           .prepare(
-            `with snapshot as materialized (
-             select up_to_index, state
+            `with head as materialized (
+             select up_to_index, state, updated_at
                from a2_snapshots
-               where session_id = ? and reducer_name = ?
+              where session_id = ? and reducer_name = ?
+           ), snapshot as materialized (
+             select up_to_index, state from (
+               select up_to_index, state from head
+                where (? is null or up_to_index <= ?)
+               union all
+               select up_to_index, state
+                 from a2_snapshot_history
+                where session_id = ? and reducer_name = ?
+                  and (? is null or up_to_index <= ?)
+             ) order by up_to_index desc limit 1
              )
              select 0 as row_order, 'snapshot' as row_kind,
-                    snapshot.up_to_index as snapshot_index,
-                    snapshot.state as snapshot_state,
+                    (select up_to_index from head) as head_index,
+                    (select up_to_index from snapshot) as snapshot_index,
+                    (select state from snapshot) 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,
@@ -883,25 +935,44 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
                     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,
+                    (select up_to_index from head) as head_index,
                     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)
+               and (? is null or event.idx <= ?)
              order by row_order, idx`,
           )
-          .all(sessionId, reducerName, sessionId) as unknown as StateReadRow[]
+          .all(
+            sessionId,
+            reducerName,
+            snapshotThroughIndex,
+            snapshotThroughIndex,
+            sessionId,
+            reducerName,
+            snapshotThroughIndex,
+            snapshotThroughIndex,
+            sessionId,
+            throughIndex,
+            throughIndex,
+          ) 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,
+          headIndex:
+            snapshot?.head_index === null || snapshot?.head_index === undefined
+              ? null
+              : Number(snapshot.head_index),
+          snapshot:
+            snapshot?.snapshot_index !== null &&
+            snapshot?.snapshot_index !== undefined
+              ? {
+                  index: Number(snapshot.snapshot_index),
+                  state: JSON.parse(snapshot.snapshot_state!),
+                }
+              : null,
           events: rows
             .filter(
               (row): row is StateReadRow & EventRow => row.row_kind === 'event',
@@ -911,26 +982,95 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
       })
     },
 
-    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(),
-        )
-      })
+    async putSnapshots(sessionId, reducerName, writes) {
+      await wrap(() =>
+        tx(() => {
+          const selectHead = db.prepare(
+            `select up_to_index, state, updated_at from a2_snapshots
+              where session_id = ? and reducer_name = ?`,
+          )
+          const unfinished = db.prepare(
+            `select 1 from a2_events
+              where session_id = ? and idx = ?
+                and processed_at is null and failed_at is null`,
+          )
+          const insertPin = db.prepare(
+            `insert or ignore into a2_snapshot_pins
+               (session_id, event_index, reducer_name, up_to_index)
+             values (?, ?, ?, ?)`,
+          )
+          const hasPin = db.prepare(
+            `select 1 from a2_snapshot_pins
+              where session_id = ? and reducer_name = ? and up_to_index = ?
+              limit 1`,
+          )
+          const putHistory = db.prepare(
+            `insert into a2_snapshot_history
+               (session_id, reducer_name, up_to_index, state, updated_at)
+             values (?, ?, ?, ?, ?)
+             on conflict (session_id, reducer_name, up_to_index) do update set
+               state = excluded.state, updated_at = excluded.updated_at`,
+          )
+          const putHead = 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`,
+          )
+          const deleteHistory = db.prepare(
+            `delete from a2_snapshot_history
+              where session_id = ? and reducer_name = ? and up_to_index = ?`,
+          )
+          for (const write of writes.toSorted((a, b) => a.index - b.index)) {
+            for (const eventIndex of write.pinEventIndexes ?? []) {
+              if (unfinished.get(sessionId, eventIndex)) {
+                insertPin.run(sessionId, eventIndex, reducerName, write.index)
+              }
+            }
+            const head = selectHead.get(sessionId, reducerName) as
+              SnapshotHeadRow | undefined
+            const now = clock.now().getTime()
+            if (!head || write.index >= Number(head.up_to_index)) {
+              if (
+                head &&
+                write.index > Number(head.up_to_index) &&
+                hasPin.get(sessionId, reducerName, Number(head.up_to_index))
+              ) {
+                putHistory.run(
+                  sessionId,
+                  reducerName,
+                  Number(head.up_to_index),
+                  head.state,
+                  Number(head.updated_at),
+                )
+              }
+              putHead.run(
+                sessionId,
+                reducerName,
+                write.index,
+                JSON.stringify(write.state) ?? 'null',
+                now,
+              )
+              deleteHistory.run(sessionId, reducerName, write.index)
+            } else if (
+              write.index < Number(head.up_to_index) &&
+              hasPin.get(sessionId, reducerName, write.index)
+            ) {
+              putHistory.run(
+                sessionId,
+                reducerName,
+                write.index,
+                JSON.stringify(write.state) ?? 'null',
+                now,
+              )
+            }
+          }
+        }),
+      )
     },
 
     presence: {
@@ -983,108 +1123,6 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
       },
     },
 
-    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(() => {

package/src/store.ts

@@ -67,20 +67,6 @@ export type StoredEvent = Event & {
   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
@@ -97,57 +83,28 @@ export type PresenceRow = {
   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. */
+  /** The current head checkpoint, even when an older historical snapshot is selected. */
+  headIndex: number | null
+  /** The greatest cached fold at or before the requested snapshot frontier. */
   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
+export type StoreSnapshotWrite = {
+  index: number
+  state: unknown
+  /** Unfinished trigger events that durably retain this exact checkpoint. */
+  pinEventIndexes?: readonly 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[]>
+export type StoreStateReadRequest = {
+  sessionId: string
+  throughIndex?: number
+  snapshotThroughIndex?: number
 }
-
 /** The result of atomically claiming every currently eligible event. */
 export type StoreClaimAvailableResult =
   | { outcome: 'claimed'; events: StoredEvent[] }
@@ -308,7 +265,11 @@ export interface A2Store {
    * 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>
+  readState(
+    sessionId: string,
+    reducerName: string,
+    options?: { throughIndex?: number; snapshotThroughIndex?: number },
+  ): Promise<StoreStateRead>
 
   /**
    * Optional batched `readState` — one consistent snapshot-plus-tail read
@@ -318,20 +279,20 @@ export interface A2Store {
    * `readState` calls when absent.
    */
   readStates?(
-    sessionIds: string[],
+    requests: readonly StoreStateReadRequest[],
     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`).
+   * Atomically writes disposable reducer checkpoints. The greatest index
+   * advances the head cache. Older checkpoints survive only when at least one
+   * listed trigger event is still unfinished; completion and dead-lettering
+   * release that event's pins and collect unreferenced historical checkpoints.
    */
-  putSnapshot(
+  putSnapshots(
     sessionId: string,
     reducerName: string,
-    index: number,
-    state: unknown,
+    snapshots: readonly StoreSnapshotWrite[],
   ): Promise<void>
 
   /**
@@ -368,9 +329,6 @@ export interface A2Store {
     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,

package/src/wire.ts

@@ -1,5 +1,5 @@
 /**
- * The wire format shared by experimental-a2/http (server side) and experimental-a2/client
+ * The wire format shared by server.fetch and experimental-a2/client
  * (browser side): events as JSON with ISO timestamps, and the A2Error
  * envelope. Internal module — both entry points re-export what's
  * public.
@@ -176,6 +176,7 @@ export type WireError = {
 
 const ERROR_STATUS: Record<A2ErrorCode, number> = {
   INVALID_PAYLOAD: 400,
+  FORBIDDEN: 403,
   UNKNOWN_EVENT_TYPE: 400,
   PARTIAL_DUPLICATE_BATCH: 400,
   SUPERSEDED_ATTEMPT: 409,