experimental-a2 0.16.1 → 0.18.0

package/src/store-sqlite.ts

@@ -15,7 +15,8 @@
 import { mkdirSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
 import { DatabaseSync } from 'node:sqlite'
-import { A2Error } from './errors.ts'
+import { A2Error, supersededAttemptError } from './errors.ts'
+import { CLEAR_EVENT_TYPE, sessionClearedError } from './session-clear.ts'
 import { idempotentReplay } from './idempotent-replay.ts'
 import { decodeReturnedEventIds } from './store-codec.ts'
 import { pollingStream } from './store-polling.ts'
@@ -112,6 +113,11 @@ create table if not exists a2_snapshot_pins (
 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_clears (
+  session_id  text    not null primary key,
+  clear_index integer not null
+) strict;
+
 create table if not exists a2_presence (
   ns          text    not null,
   participant text    not null,
@@ -262,6 +268,7 @@ type PresenceDbRow = {
 
 type StateReadRow = Partial<EventRow> & {
   row_kind: 'snapshot' | 'event'
+  clear_index: number | bigint | null
   head_index: number | bigint | null
   snapshot_index: number | bigint | null
   snapshot_state: string | null
@@ -282,6 +289,8 @@ type ExistingEventRow = EventRow & {
   session_has_pending: number | bigint
 }
 
+const RECLAIM_BATCH = 256
+
 export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
   const path = options.path ?? '.a2/dev.db'
   const clock = options.clock ?? SYSTEM_CLOCK
@@ -314,6 +323,7 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
               when not exists (
                 select 1 from a2_events
                  where session_id = ? and lane = ? and processed_at is null
+                   and idx > ?
               ) then 1
               else 0
             end,
@@ -325,6 +335,7 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
         and idx = (
           select idx from a2_events
            where session_id = ? and lane = ? and processed_at is null
+             and idx > ?
            order by idx limit 1
         )`,
   )
@@ -335,7 +346,7 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
             ) as max,
             exists(
               select 1 from a2_events
-              where session_id = ? and processed_at is null
+              where session_id = ? and processed_at is null and idx > ?
             ) as has_pending`,
   )
   const upsertPresence = db.prepare(
@@ -368,12 +379,80 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
                 select 1 from a2_events pending
                 where pending.session_id = ?
                   and pending.processed_at is null
+                  and pending.idx > ?
               ) as session_has_pending
          from a2_events stored
         where stored.event_id in (${Array.from({ length: count }, () => '?').join(', ')})
         order by stored.idx`,
     )
 
+  const selectClearIndex = db.prepare(
+    'select clear_index from a2_clears where session_id = ?',
+  )
+  const clearIndexOf = (sessionId: string): number =>
+    Number(
+      (
+        selectClearIndex.get(sessionId) as
+          { clear_index: number | bigint } | undefined
+      )?.clear_index ?? 0,
+    )
+  const deleteEventById = db.prepare(
+    'delete from a2_events where session_id = ? and event_id = ?',
+  )
+
+  /**
+   * The rows owning `ids`. This session's rows below its clear marker do
+   * not own their ids: they are deleted here so the ids can be reused.
+   */
+  const liveOwnersOf = (
+    sessionId: string,
+    clearIndex: number,
+    ids: readonly string[],
+  ): ExistingEventRow[] => {
+    if (ids.length === 0) return []
+    const rows = selectByIds(ids.length).all(
+      sessionId,
+      clearIndex,
+      ...ids,
+    ) as unknown as ExistingEventRow[]
+    return rows.filter((row) => {
+      if (row.session_id !== sessionId || Number(row.idx) >= clearIndex)
+        return true
+      deleteEventById.run(sessionId, row.event_id)
+      return false
+    })
+  }
+
+  const selectCauseParent = db.prepare(
+    'select attempt_count, failed_at from a2_events where session_id = ? and idx = ?',
+  )
+  /** The attempt-currency fence shared by handler appends and clears. */
+  const assertCurrentCause = ({
+    sessionId,
+    cause,
+    clearIndex,
+  }: {
+    sessionId: string
+    cause: EventCause
+    clearIndex: number
+  }): void => {
+    if (cause.index <= clearIndex)
+      throw supersededAttemptError(sessionId, cause)
+    const parent = selectCauseParent.get(sessionId, cause.index) as
+      { attempt_count: number | bigint; failed_at: unknown } | undefined
+    if (!parent) {
+      throw new TypeError(
+        `no event at index ${cause.index} in session '${sessionId}'`,
+      )
+    }
+    if (
+      Number(parent.attempt_count) !== cause.attempt ||
+      parent.failed_at !== null
+    ) {
+      throw supersededAttemptError(sessionId, cause)
+    }
+  }
+
   const tx = <T>(fn: () => T): T => {
     db.exec('begin immediate')
     try {
@@ -392,12 +471,13 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
   }
 
   return {
-    async append(sessionId, events) {
+    async append(sessionId, events, appendOptions) {
       if (events.length === 0) {
         return wrap(() => {
           const status = appendStatus.get(
             sessionId,
             sessionId,
+            clearIndexOf(sessionId),
           ) as AppendStatusRow
           return {
             events: [],
@@ -407,6 +487,7 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
       }
       return wrap(() =>
         tx(() => {
+          const clearIndex = clearIndexOf(sessionId)
           const supplied = events.filter((e) => e.id !== undefined)
           const suppliedIds = supplied.map((e) => e.id as string)
           if (new Set(suppliedIds).size !== suppliedIds.length) {
@@ -416,10 +497,7 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
             )
           }
           if (suppliedIds.length > 0) {
-            const existing = selectByIds(suppliedIds.length).all(
-              sessionId,
-              ...suppliedIds,
-            ) as unknown as ExistingEventRow[]
+            const existing = liveOwnersOf(sessionId, clearIndex, suppliedIds)
             if (existing.length > 0) {
               const foreign = existing.find(
                 (row) => row.session_id !== sessionId,
@@ -443,37 +521,25 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
             }
           }
 
+          const originIndex = appendOptions?.originIndex
+          if (originIndex !== undefined && originIndex <= clearIndex) {
+            throw sessionClearedError(
+              `scheduled work from event ${originIndex} was cleared in session '${sessionId}'`,
+            )
+          }
           // 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}'`,
-              )
-            }
+            if (e.cause)
+              assertCurrentCause({ sessionId, cause: e.cause, clearIndex })
           }
 
           const status = appendStatus.get(
             sessionId,
             sessionId,
+            clearIndex,
           ) as AppendStatusRow
           const base = Number(status.max)
           const now = clock.now().getTime()
@@ -492,6 +558,7 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
               e.lane ?? null,
               sessionId,
               e.lane ?? null,
+              clearIndex,
               e.settled ? now : null,
             )
             return {
@@ -530,8 +597,12 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
 
     async read(sessionId, opts) {
       return wrap(() => {
-        const conditions = ['session_id = ?']
-        const params: (string | number)[] = [sessionId]
+        // Reads start at the latest clear marker.
+        const conditions = [
+          'session_id = ?',
+          'idx >= coalesce((select clear_index from a2_clears where session_id = ?), 0)',
+        ]
+        const params: (string | number)[] = [sessionId, sessionId]
         if (opts?.afterIndex !== undefined) {
           conditions.push('idx > ?')
           params.push(opts.afterIndex)
@@ -560,6 +631,7 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
         tx(() => {
           const now = clock.now().getTime()
           const expiresAt = expiresAtMs ?? now + ttlMs
+          const clearIndex = clearIndexOf(sessionId)
           const exclusion =
             excludeIndexes.length === 0
               ? ''
@@ -572,11 +644,17 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
                   and event.processed_at is null
                   and event.failed_at is null
                   and event.lane_ready = 1
+                  and event.idx > ?
                   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<{
+            .all(
+              sessionId,
+              clearIndex,
+              now,
+              ...excludeIndexes,
+            ) as unknown as Array<{
             idx: number | bigint
           }>
           if (eligible.length > 0) {
@@ -599,7 +677,9 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
                 sessionId,
                 row.idx,
               ) as EventRow
-              return toStored(claimed)
+              const stored = toStored(claimed)
+              if (clearIndex > 0) stored.clearIndex = clearIndex
+              return stored
             })
             return { outcome: 'claimed', events }
           }
@@ -612,9 +692,10 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
                   and processed_at is null
                   and failed_at is null
                   and lane_ready = 1
+                  and idx > ?
                   and claim_expires_at > ?`,
             )
-            .get(sessionId, now) as {
+            .get(sessionId, clearIndex, now) as {
             retry_at: number | bigint | null
           }
           return active.retry_at === null
@@ -645,7 +726,12 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
                 and claim_holder = ?
                 and claim_expires_at > ?`,
           )
+          const clearIndex = clearIndexOf(sessionId)
           for (const claim of claims) {
+            if (claim.index <= clearIndex) {
+              superseded.push(claim.index)
+              continue
+            }
             const row = currentAttempt.get(sessionId, claim.index) as
               { attempt_count: number | bigint } | undefined
             if (!row) continue
@@ -674,6 +760,8 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
     async completeAttempt({ sessionId, index, attempt, events }) {
       return wrap(() =>
         tx(() => {
+          const clearIndex = clearIndexOf(sessionId)
+          if (index <= clearIndex) return { outcome: 'superseded' }
           const parent = db
             .prepare('select * from a2_events where session_id = ? and idx = ?')
             .get(sessionId, index) as EventRow | undefined
@@ -713,6 +801,7 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
                 ? []
                 : (selectByIds(ids.length).all(
                     sessionId,
+                    clearIndex,
                     ...ids,
                   ) as unknown as ExistingEventRow[])
             const byId = new Map(existing.map((row) => [row.event_id, row]))
@@ -748,11 +837,7 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
             return { outcome: 'superseded' }
           }
 
-          if (
-            ids.length > 0 &&
-            (selectByIds(ids.length).all(sessionId, ...ids) as unknown[])
-              .length > 0
-          ) {
+          if (liveOwnersOf(sessionId, clearIndex, ids).length > 0) {
             throw new A2Error(
               'PARTIAL_DUPLICATE_BATCH',
               'returned event batch contains an already-appended event id',
@@ -762,6 +847,7 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
           const status = appendStatus.get(
             sessionId,
             sessionId,
+            clearIndex,
           ) as AppendStatusRow
           const now = clock.now().getTime()
           db.prepare(
@@ -788,7 +874,7 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
                 )`,
           ).run(sessionId)
           if (parent.lane !== null) {
-            promoteLaneHead.run(sessionId, sessionId, parent.lane)
+            promoteLaneHead.run(sessionId, sessionId, parent.lane, clearIndex)
           }
           const inserted = events.map((event, offset) => {
             const id = event.id
@@ -806,6 +892,7 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
               event.lane ?? null,
               sessionId,
               event.lane ?? null,
+              clearIndex,
               event.settled ? now : null,
             )
             return toStored(
@@ -824,6 +911,9 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
     async failAttempt({ sessionId, index, attempt, error, maxFailures }) {
       return wrap(() =>
         tx(() => {
+          if (index <= clearIndexOf(sessionId)) {
+            return { outcome: 'superseded', failureCount: 0 }
+          }
           const current = db
             .prepare('select * from a2_events where session_id = ? and idx = ?')
             .get(sessionId, index) as EventRow | undefined
@@ -898,6 +988,66 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
       )
     },
 
+    async deadLetters(sessionId) {
+      return wrap(() => {
+        const rows = db
+          .prepare(
+            `select * from a2_events
+              where session_id = ?
+                and processed_at is null
+                and failed_at is not null
+                and idx > coalesce(
+                  (select clear_index from a2_clears where session_id = ?), 0
+                )
+              order by idx`,
+          )
+          .all(sessionId, sessionId) as unknown as EventRow[]
+        return rows.map(toStored)
+      })
+    },
+
+    async redrive({ sessionId, index, action }) {
+      return wrap(() =>
+        tx(() => {
+          const clearIndex = clearIndexOf(sessionId)
+          const row =
+            index > clearIndex
+              ? (db
+                  .prepare(
+                    'select lane, processed_at, failed_at from a2_events where session_id = ? and idx = ?',
+                  )
+                  .get(sessionId, index) as
+                  | Pick<EventRow, 'lane' | 'processed_at' | 'failed_at'>
+                  | undefined)
+              : undefined
+          const redriven =
+            row !== undefined &&
+            row.processed_at === null &&
+            row.failed_at !== null
+          if (redriven && action === 'skip') {
+            db.prepare(
+              `update a2_events set processed_at = ?, lane_ready = 0
+                where session_id = ? and idx = ?`,
+            ).run(clock.now().getTime(), sessionId, index)
+            if (row.lane !== null) {
+              promoteLaneHead.run(sessionId, sessionId, row.lane, clearIndex)
+            }
+          } else if (redriven) {
+            db.prepare(
+              `update a2_events set failed_at = null, failure_count = 0
+                where session_id = ? and idx = ?`,
+            ).run(sessionId, index)
+          }
+          const status = appendStatus.get(
+            sessionId,
+            sessionId,
+            clearIndex,
+          ) as AppendStatusRow
+          return { redriven, hasPending: Number(status.has_pending) === 1 }
+        }),
+      )
+    },
+
     async readState(sessionId, reducerName, stateOptions) {
       return wrap(() => {
         const throughIndex = stateOptions?.throughIndex ?? null
@@ -905,10 +1055,15 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
           stateOptions?.snapshotThroughIndex ?? throughIndex
         const rows = db
           .prepare(
-            `with head as materialized (
+            `with boundary as materialized (
+             select coalesce(
+               (select clear_index from a2_clears where session_id = ?), 0
+             ) as clear_index
+           ), head as materialized (
              select up_to_index, state, updated_at
                from a2_snapshots
               where session_id = ? and reducer_name = ?
+                and up_to_index >= (select clear_index from boundary)
            ), snapshot as materialized (
              select up_to_index, state from (
                select up_to_index, state from head
@@ -917,10 +1072,12 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
                select up_to_index, state
                  from a2_snapshot_history
                 where session_id = ? and reducer_name = ?
+                  and up_to_index >= (select clear_index from boundary)
                   and (? is null or up_to_index <= ?)
              ) order by up_to_index desc limit 1
              )
              select 0 as row_order, 'snapshot' as row_kind,
+                    (select clear_index from boundary) as clear_index,
                     (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,
@@ -937,16 +1094,21 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
                     null as claim_expires_at
              union all
              select 1 as row_order, 'event' as row_kind,
+                    null as clear_index,
                     (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 event.idx > max(
+                 coalesce((select up_to_index from snapshot), 0),
+                 (select clear_index from boundary) - 1
+               )
                and (? is null or event.idx <= ?)
              order by row_order, idx`,
           )
           .all(
+            sessionId,
             sessionId,
             reducerName,
             snapshotThroughIndex,
@@ -960,7 +1122,9 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
             throughIndex,
           ) as unknown as StateReadRow[]
         const snapshot = rows.find((row) => row.row_kind === 'snapshot')
+        const clearIndex = Number(snapshot?.clear_index ?? 0)
         return {
+          ...(clearIndex > 0 ? { clearIndex } : {}),
           headIndex:
             snapshot?.head_index === null || snapshot?.head_index === undefined
               ? null
@@ -991,7 +1155,7 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
           )
           const unfinished = db.prepare(
             `select 1 from a2_events
-              where session_id = ? and idx = ?
+              where session_id = ? and idx = ? and idx > ?
                 and processed_at is null and failed_at is null`,
           )
           const insertPin = db.prepare(
@@ -1025,9 +1189,12 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
             `delete from a2_snapshot_history
               where session_id = ? and reducer_name = ? and up_to_index = ?`,
           )
+          const clearIndex = clearIndexOf(sessionId)
           for (const write of writes.toSorted((a, b) => a.index - b.index)) {
+            // A fold from before the latest clear describes a lifetime that is gone.
+            if (write.index < clearIndex) continue
             for (const eventIndex of write.pinEventIndexes ?? []) {
-              if (unfinished.get(sessionId, eventIndex)) {
+              if (unfinished.get(sessionId, eventIndex, clearIndex)) {
                 insertPin.run(sessionId, eventIndex, reducerName, write.index)
               }
             }
@@ -1038,6 +1205,7 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
               if (
                 head &&
                 write.index > Number(head.up_to_index) &&
+                Number(head.up_to_index) >= clearIndex &&
                 hasPin.get(sessionId, reducerName, Number(head.up_to_index))
               ) {
                 putHistory.run(
@@ -1126,11 +1294,15 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
     stream(sessionId, opts) {
       const readAfter = (afterIndex: number): StoredEvent[] =>
         wrap(() => {
+          // A cursor below the latest marker resumes at it.
           const rows = db
             .prepare(
-              'select * from a2_events where session_id = ? and idx > ? order by idx',
+              `select * from a2_events
+                where session_id = ? and idx > ?
+                  and idx >= coalesce((select clear_index from a2_clears where session_id = ?), 0)
+                order by idx`,
             )
-            .all(sessionId, afterIndex) as unknown as EventRow[]
+            .all(sessionId, afterIndex, sessionId) as unknown as EventRow[]
           return rows.map(toStored)
         })
       return pollingStream(
@@ -1139,6 +1311,108 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
       )
     },
 
+    async clear({ sessionId, ifLastIndex, cause }) {
+      return wrap(() =>
+        tx(() => {
+          const clearIndex = clearIndexOf(sessionId)
+          if (cause) assertCurrentCause({ sessionId, cause, clearIndex })
+          const head = Number(
+            (
+              appendStatus.get(
+                sessionId,
+                sessionId,
+                clearIndex,
+              ) as AppendStatusRow
+            ).max,
+          )
+          if (ifLastIndex !== undefined && clearIndex === ifLastIndex + 1) {
+            return { cleared: true, index: head, clearIndex }
+          }
+          if (ifLastIndex !== undefined && ifLastIndex !== head) {
+            return { cleared: false, index: head, clearIndex }
+          }
+          if (head === 0 || clearIndex === head) {
+            return { cleared: true, index: head, clearIndex }
+          }
+          const marker = head + 1
+          const now = clock.now().getTime()
+          insertEvent.run(
+            sessionId,
+            marker,
+            CLEAR_EVENT_TYPE,
+            'null',
+            generateId(),
+            now,
+            null,
+            null,
+            null,
+            sessionId,
+            null,
+            clearIndex,
+            now,
+          )
+          db.prepare(
+            `insert into a2_clears (session_id, clear_index) values (?, ?)
+             on conflict (session_id) do update set clear_index = excluded.clear_index`,
+          ).run(sessionId, marker)
+          return { cleared: true, index: marker, clearIndex: marker }
+        }),
+      )
+    },
+
+    async reclaim(sessionId) {
+      return wrap(() =>
+        tx(() => {
+          const clearIndex = clearIndexOf(sessionId)
+          if (clearIndex === 0) return { deleted: 0, done: true }
+          const last = db
+            .prepare(
+              `select max(idx) as last from (
+                 select idx from a2_events
+                  where session_id = ? and idx < ?
+                  order by idx limit ?
+               )`,
+            )
+            .get(sessionId, clearIndex, RECLAIM_BATCH) as {
+            last: number | bigint | null
+          }
+          let deleted = 0
+          if (last.last !== null) {
+            const through = Number(last.last)
+            deleted = Number(
+              db
+                .prepare(
+                  'delete from a2_events where session_id = ? and idx <= ?',
+                )
+                .run(sessionId, through).changes,
+            )
+            db.prepare(
+              'delete from a2_snapshot_pins where session_id = ? and event_index <= ?',
+            ).run(sessionId, through)
+          }
+          const done =
+            db
+              .prepare(
+                'select 1 from a2_events where session_id = ? and idx < ? limit 1',
+              )
+              .get(sessionId, clearIndex) === undefined
+          // Writes serialize with the clear, so none lands below the marker later.
+          if (done) {
+            for (const table of [
+              'a2_snapshot_pins',
+              'a2_snapshot_history',
+              'a2_snapshots',
+            ]) {
+              db.prepare(
+                `delete from ${table} where session_id = ? and up_to_index < ?`,
+              ).run(sessionId, clearIndex)
+            }
+          }
+          return { deleted, done }
+        }),
+      )
+    },
+
     close() {
       db.close()
     },