experimental-a2 0.23.0 → 0.24.0

package/examples/playground/app/a2slack/db/migrations/meta/_journal.json

@@ -36,6 +36,13 @@
       "when": 1792693132589,
       "tag": "0004_a2_session_event_ids",
       "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1792761727680,
+      "tag": "0005_a2slack_feed_v2",
+      "breakpoints": true
     }
   ]
-}
+}

package/examples/playground/app/a2slack/db/queries.ts

@@ -38,7 +38,7 @@ import {
 } from './schema'
 
 /** The feed consumer's name, which its position is recorded under. */
-export const FEED = 'a2slack-feed'
+export const FEED = 'a2slack-feed-v2'
 
 export const PAGE_SIZE = 50
 

package/examples/playground/app/a2slack/drills/a2slack.drill.ts

@@ -340,7 +340,7 @@ async function loadRun(store: A2Store, label: string) {
       payload: { id: channel, by: pick(USERS) },
     })
   await until(
-    () => idle(store, ['welcome', 'a2slack-feed', 'a2slack-notify']),
+    () => idle(store, ['welcome', a2slack.queries.FEED, 'a2slack-notify']),
     {
       timeoutMs: 60_000,
     },
@@ -350,7 +350,7 @@ async function loadRun(store: A2Store, label: string) {
 
   const posted = await post(to, MESSAGES, CONCURRENCY)
   const catchUpMs = await until(
-    () => idle(store, ['welcome', 'a2slack-feed', 'a2slack-notify']),
+    () => idle(store, ['welcome', a2slack.queries.FEED, 'a2slack-notify']),
     { timeoutMs: 10 * 60_000, everyMs: 100 },
   )
   const log = await logCounts(to[0]!)
@@ -361,7 +361,7 @@ async function loadRun(store: A2Store, label: string) {
   await followers.close()
   const tables = await tableCounts()
   const db = await a2slack.database()
-  const feedPosition = await a2slack.queries.position(db, 'a2slack-feed')
+  const feedPosition = await a2slack.queries.position(db, a2slack.queries.FEED)
 
   const [root] = await rows<{ id: string }>(
     "select id from a2slack_messages where thread_id is null and channel = 'room-1' order by log_index desc limit 1",
@@ -449,23 +449,23 @@ it('rebuild: a renamed feed fills empty tables from the whole log', async () =>
   const db = await a2slack.database()
   await db.execute(
     sql.raw(
-      "truncate a2slack_channels, a2slack_messages, a2slack_notifications, a2slack_reactions, a2slack_reads; delete from a2slack_positions where consumer = 'a2slack-feed'",
+      `truncate a2slack_channels, a2slack_messages, a2slack_notifications, a2slack_reactions, a2slack_reads; delete from a2slack_positions where consumer = '${a2slack.queries.FEED}'`,
     ),
   )
   const { telemetry, runs } = recorder()
-  const feedV2 = a2slack
+  const feedRebuild = a2slack
     .consumer({
       contract: a2slack.model.workspace,
-      name: 'a2slack-feed-v2',
-      lane: 'feed-v2',
+      name: 'a2slack-feed-rebuild',
+      lane: 'feed-rebuild',
       backfill: true,
     })
     .run(async ({ event }) => {
       await a2slack.feedEvent(await a2slack.database(), event)
     })
-  const [server] = servers(redisStore, [feedV2], telemetry, 1)
+  const [server] = servers(redisStore, [feedRebuild], telemetry, 1)
   const t0 = performance.now()
-  const consumed = await session(server!).consume(feedV2)
+  const consumed = await session(server!).consume(feedRebuild)
   const ms = performance.now() - t0
   const after = await tableCounts()
   const result = {
@@ -524,9 +524,12 @@ it('poison: one bad event dead-letters its consumer alone, and redrive resumes i
   await post(to, 50, 5)
 
   const t0 = performance.now()
-  await until(() => idle(redisStore, ['a2slack-feed', 'a2slack-notify']), {
-    timeoutMs: 60_000,
-  })
+  await until(
+    () => idle(redisStore, [a2slack.queries.FEED, 'a2slack-notify']),
+    {
+      timeoutMs: 60_000,
+    },
+  )
   const othersCaughtUpMs = performance.now() - t0
   const stuck = (await redisStore.cursors('a2slack\u001fworkspace')).find(
     (cursor) => cursor.consumer === 'drill-seen',
@@ -625,14 +628,14 @@ it('outage: Postgres goes away mid-load, and every event still lands once', asyn
   })
   await outage
   await until(
-    () => idle(redisStore, ['welcome', 'a2slack-feed', 'a2slack-notify']),
+    () => idle(redisStore, ['welcome', a2slack.queries.FEED, 'a2slack-notify']),
     { timeoutMs: 5 * 60_000, everyMs: 200 },
   )
   const idleAt = performance.now()
   const log = await logCounts(to[0]!)
   const tables = await tableCounts()
   const db = await a2slack.database()
-  const feedPosition = await a2slack.queries.position(db, 'a2slack-feed')
+  const feedPosition = await a2slack.queries.position(db, a2slack.queries.FEED)
   const deadLetters = await session(to[0]!).deadLetters()
   const result = {
     appended: 3_000,

package/examples/playground/app/a2slack/search-index.ts

@@ -12,7 +12,7 @@ import { Redis, s } from '@upstash/redis'
 import { searchFeed } from './db/queries'
 import type { SearchResult } from './model'
 
-const NAME = 'a2slack-messages-v1'
+const NAME = 'a2slack-messages-v2'
 const PREFIX = `${NAME}:message:`
 
 const schema = s.object({

package/examples/playground/app/a2slack/server.ts

@@ -4,8 +4,8 @@
  * either writes somewhere else or returns events into the log:
  *
  * - `welcome` posts a new channel's opening message.
- * - `a2slack-feed` keeps the tables every page reads (db/schema.ts).
- * - `a2slack-search-v1` keeps the search index in Upstash Redis Search,
+ * - `a2slack-feed-v2` keeps the tables every page reads (db/schema.ts).
+ * - `a2slack-search-v2` keeps the search index in Upstash Redis Search,
  *   where it's configured (search-index.ts).
  * - `a2slack-notify` works out who should hear about each message, and
  *   returns a notification addressed to each of them.

package/examples/playground/lib/store.ts

@@ -8,6 +8,8 @@ const postgresUrl = process.env.DATABASE_URL?.replace(
   'sslmode=verify-full',
 )
 
+// A new keyPrefix starts every log over: a2slack's feed (consumers/feed.ts)
+// has to start over with it, under a new name and with its tables cleared.
 export const store: RedisStore | PostgresStore | undefined = redisUrl
   ? redis({ url: redisUrl, keyPrefix: 'a2-playground-tagged' })
   : postgresUrl

package/examples/playground/package.json

@@ -39,7 +39,7 @@
     "ai": "^7.0.58",
     "codemirror": "^6.0.2",
     "drizzle-orm": "^0.45.3",
-    "experimental-a2": "0.23.0",
+    "experimental-a2": "0.24.0",
     "geist": "^1.7.2",
     "ioredis": "^5.9.0",
     "libfx": "0.0.12",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-a2",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Syncs your immutable event log, from server to browser: one contract, handlers, derived state, and a live client per session.",
   "license": "MIT",
   "type": "module",

package/src/errors.ts

@@ -5,6 +5,7 @@ export type A2ServerErrorCode =
   | 'PARTIAL_DUPLICATE_BATCH' // batch mixed already-appended and fresh events
   | 'SUPERSEDED_ATTEMPT' // consumer append from an attempt a recovery claim or a clear replaced
   | 'SESSION_CLEARED' // a read or call reached across the session's latest clear
+  | 'LAST_INDEX_MISMATCH' // a conditional append's ifLastIndex was not the head — nothing was written
   | 'CLAIM_EXPIRED' // ctx.signal abort reason: the attempt's lease lapsed without renewal
   | 'STORE_UNAVAILABLE' // store backend failure — retryable, nothing was written
   | 'STORE_NOT_CONFIGURED' // no `store` in production, a missing peer dependency, or Postgres lacks A2's tables
@@ -48,6 +49,44 @@ export function supersededAttemptError(
   )
 }
 
+/** A conditional append whose `ifLastIndex` is not the session's head. */
+export function lastIndexMismatchError(
+  sessionId: string,
+  ifLastIndex: number,
+  head: number,
+): A2Error {
+  return new A2Error(
+    'LAST_INDEX_MISMATCH',
+    `session '${sessionId}' is at index ${head}, not ${ifLastIndex}`,
+    { details: { index: head } },
+  )
+}
+
+/** A conditional append's condition and the head its store found. */
+export type ConditionalHead = {
+  sessionId: string
+  ifLastIndex: number
+  head: number
+}
+
+/**
+ * A batch whose ids conflict with committed events. In a conditional append
+ * whose head moved, the condition failed first, as when another writer's
+ * batch took those ids, so the conflict reports the head instead.
+ */
+export function duplicateBatchError(
+  message: string,
+  conditional: ConditionalHead | undefined,
+): A2Error {
+  return conditional && conditional.head !== conditional.ifLastIndex
+    ? lastIndexMismatchError(
+        conditional.sessionId,
+        conditional.ifLastIndex,
+        conditional.head,
+      )
+    : new A2Error('PARTIAL_DUPLICATE_BATCH', message)
+}
+
 /**
  * Wrap an arbitrary thrown value as STORE_UNAVAILABLE, preserving the
  * original as `cause`. A2Errors pass through untouched — they already

package/src/idempotent-replay.ts

@@ -1,4 +1,4 @@
-import { A2Error } from './errors.ts'
+import { duplicateBatchError, type ConditionalHead } from './errors.ts'
 import type { AppendEvent, StoredEvent } from './store.ts'
 
 const canonicalJson = (value: unknown): string =>
@@ -20,6 +20,7 @@ const canonicalJson = (value: unknown): string =>
 export const idempotentReplay = (
   events: readonly AppendEvent[],
   existing: readonly StoredEvent[],
+  conditional?: ConditionalHead,
 ): StoredEvent[] => {
   const byId = new Map(existing.map((event) => [event.id, event]))
   const ordered = events.map((event) =>
@@ -42,9 +43,9 @@ export const idempotentReplay = (
       )
     })
   ) {
-    throw new A2Error(
-      'PARTIAL_DUPLICATE_BATCH',
+    throw duplicateBatchError(
       'already-appended events do not match the retried batch',
+      conditional,
     )
   }
 

package/src/server.ts

@@ -155,6 +155,15 @@ export type SessionDispatch<D extends EventDefs> = (
 export type SessionAppend<D extends EventDefs> = SessionDispatch<D> & {
   /** Commit, then hand pending work directly to configured scheduler. */
   dispatch: SessionDispatch<D>
+  /**
+   * Append only while `index` is the session's head, checked in the same
+   * atomic step as the write. Otherwise nothing is written and it throws
+   * `LAST_INDEX_MISMATCH`, with the head as `details.index`.
+   */
+  ifLastIndex(
+    index: number,
+    ...events: AppendInput<D>[]
+  ): Promise<ContractEvent<D>[]>
 }
 
 export type ConsumerAppend<D extends EventDefs> = (
@@ -1395,6 +1404,9 @@ export function createServer<
     })
   }
 
+  /** What the store checks before it writes, inside the append's atomic step. */
+  type AppendCondition = { originIndex?: number; ifLastIndex?: number }
+
   /**
    * Validate + write. `onAppended` runs inside the telemetry span, so
    * the drain it schedules is created in the append's active context —
@@ -1409,7 +1421,7 @@ export function createServer<
     cause?: EventCause,
     generatedIds?: readonly boolean[],
     requireDurableInitialArm = false,
-    originIndex?: number,
+    condition: AppendCondition = {},
   ): Promise<ContractEvent<D>[]> =>
     telemetry.span(
       'a2.append',
@@ -1442,7 +1454,7 @@ export function createServer<
         try {
           const result = await store.append(nsId(sessionId), validated, {
             consumers: storeConsumers,
-            ...(originIndex === undefined ? {} : { originIndex }),
+            ...condition,
           })
           rows = result.events
           // A consumer appending events no consumer takes adds no work, and
@@ -2243,7 +2255,7 @@ export function createServer<
         throw new TypeError('schedule.clear requires an ifLastIndex')
       }
       const { ifLastIndex, ...timing } = clearOptions
-      assertClearIndex(ifLastIndex)
+      assertIfLastIndex(ifLastIndex)
       const dueAt = scheduleDueAt(
         timing as ScheduleTiming,
         triggerCreatedAt ?? Date.now(),
@@ -2848,7 +2860,7 @@ export function createServer<
     attempt: ClearingAttempt | undefined,
   ): Promise<SessionClearResult> => {
     const ifLastIndex = clearOptions?.ifLastIndex
-    if (ifLastIndex !== undefined) assertClearIndex(ifLastIndex)
+    if (ifLastIndex !== undefined) assertIfLastIndex(ifLastIndex)
     const store = await resolveStore()
     if (!store.clear || !store.reclaim) {
       throw new TypeError(
@@ -4077,7 +4089,7 @@ export function createServer<
     mode: 'inline' | 'dispatch',
     events: AppendInput<D>[],
     requireDurableInitialArm = false,
-    originIndex?: number,
+    condition: AppendCondition = {},
   ): Promise<ContractEvent<D>[]> => {
     return appendCore(
       sessionId,
@@ -4088,7 +4100,7 @@ export function createServer<
       undefined,
       undefined,
       requireDurableInitialArm,
-      originIndex,
+      condition,
     )
   }
 
@@ -4100,8 +4112,19 @@ export function createServer<
       appendExternal(id, 'inline', events)
     const appendDispatch = async (...events: AppendInput<D>[]) =>
       appendExternal(id, 'dispatch', events)
+    const appendIfLastIndex = async (
+      index: number,
+      ...events: AppendInput<D>[]
+    ) => {
+      assertIfLastIndex(index)
+      if (events.length === 0) {
+        throw new TypeError('append.ifLastIndex requires at least one event')
+      }
+      return appendExternal(id, 'inline', events, false, { ifLastIndex: index })
+    }
     const append = Object.assign(appendInline, {
       dispatch: appendDispatch,
+      ifLastIndex: appendIfLastIndex,
     }) as SessionAppend<D>
     return Object.assign(makeSession(id, append, null), {
       deadLetters: () => listDeadLetters(id),
@@ -4169,7 +4192,7 @@ export function createServer<
           'inline',
           [...events],
           true,
-          originIndex,
+          originIndex === undefined ? {} : { originIndex },
         )
       } catch (error) {
         // The scheduling consumer's lifetime was cleared: an acknowledged no-op.
@@ -4186,7 +4209,7 @@ export function createServer<
       (await readHistory(sessionId, { gte })).map(toPublic),
     schedulerClear: async (sessionId, ifLastIndex) => {
       assertSessionId(sessionId)
-      assertClearIndex(ifLastIndex)
+      assertIfLastIndex(ifLastIndex)
       await clearSession(sessionId, { ifLastIndex }, undefined)
     },
   })
@@ -4232,7 +4255,7 @@ function assertRedriveIndex(value: number): void {
   }
 }
 
-function assertClearIndex(value: number): void {
+function assertIfLastIndex(value: number): void {
   if (!Number.isSafeInteger(value) || value < 0) {
     throw new TypeError('ifLastIndex must be a non-negative safe integer')
   }

package/src/store-memory.ts

@@ -7,7 +7,12 @@
  */
 
 import type { PresencePatch } from './contract.ts'
-import { A2Error, supersededAttemptError } from './errors.ts'
+import {
+  A2Error,
+  duplicateBatchError,
+  lastIndexMismatchError,
+  supersededAttemptError,
+} from './errors.ts'
 import { idempotentReplay } from './idempotent-replay.ts'
 import { nullProtoRecord } from './internal.ts'
 import { CLEAR_EVENT_TYPE, sessionClearedError } from './session-clear.ts'
@@ -664,6 +669,12 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
         return { events: [], hasPending: hasPending(sessionId, consumers) }
       }
 
+      const ifLastIndex = appendOptions?.ifLastIndex
+      const conditional =
+        ifLastIndex === undefined
+          ? undefined
+          : { sessionId, ifLastIndex, head: headOf(sessions.get(sessionId)) }
+
       // Batch-scoped idempotency (a2-implementation.md §3): all ids
       // already present → lost-ack retry, return the original rows;
       // some present → the caller mixed sent and fresh events.
@@ -671,13 +682,17 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       if (existing.length > 0) {
         if (existing.length === events.length) {
           return {
-            events: idempotentReplay(events, existing.map(toStored)),
+            events: idempotentReplay(
+              events,
+              existing.map(toStored),
+              conditional,
+            ),
             hasPending: hasPending(sessionId, consumers),
           }
         }
-        throw new A2Error(
-          'PARTIAL_DUPLICATE_BATCH',
+        throw duplicateBatchError(
           `batch mixes ${existing.length} already-appended and ${events.length - existing.length} fresh events`,
+          conditional,
         )
       }
 
@@ -692,6 +707,13 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       for (const event of events) {
         if (event.cause) assertCurrentCause(sessionId, event.cause)
       }
+      if (conditional && conditional.head !== conditional.ifLastIndex) {
+        throw lastIndexMismatchError(
+          sessionId,
+          conditional.ifLastIndex,
+          conditional.head,
+        )
+      }
 
       const inserted = insert(sessionId, events, clock.now(), consumers)
       notifyStreams(sessionId, inserted)

package/src/store-postgres.ts

@@ -29,7 +29,12 @@
  * for the session lock holds, or one a clear left behind.
  */
 
-import { A2Error, supersededAttemptError } from './errors.ts'
+import {
+  A2Error,
+  duplicateBatchError,
+  lastIndexMismatchError,
+  supersededAttemptError,
+} from './errors.ts'
 import { idempotentReplay } from './idempotent-replay.ts'
 import { CLEAR_EVENT_TYPE, sessionClearedError } from './session-clear.ts'
 import {
@@ -574,7 +579,8 @@ const INSERTED_AFTER = `(
  * every event's id belongs to this session already, the batch is a retry: it
  * stops with the committed rows. Some owned aborts, as does scheduled work
  * from at or below the clear marker (`origin`). Rows below the marker own no
- * id.
+ * id. Both id outcomes carry the head, which a conditional append's conflict
+ * reports when it moved.
  */
 const APPEND_CHECKS = `
   with boundary as materialized (
@@ -592,12 +598,12 @@ const APPEND_CHECKS = `
   )
   select case
     when (select count(*) from owned) = ${param.bigint('count')} then
-      jsonb_build_object('stop', 'replay',
+      jsonb_build_object('stop', 'replay', 'head', boundary.base,
         'has_pending', boundary.has_pending,
         'events', (select jsonb_agg(to_jsonb(owned) order by owned.idx)
                      from owned))
     when exists (select 1 from owned) then
-      jsonb_build_object('abort', 'mixed', 'owned',
+      jsonb_build_object('abort', 'mixed', 'head', boundary.base, 'owned',
         (select count(*) from owned))
     when ${param.bigint('origin')} <= boundary.clear_index then
       jsonb_build_object('abort', 'cleared')
@@ -630,6 +636,16 @@ const FENCE = `
     from cause where cause.ord not in (select ord from held)
    order by cause.ord limit 1`
 
+/**
+ * A conditional append's head check, under the session lock and after the
+ * fences: it aborts with the head unless the head is `ifLastIndex`.
+ */
+const IF_LAST_INDEX = `
+  select jsonb_build_object('abort', 'moved', 'index', head.idx)
+    from (select coalesce(max(idx), 0) as idx from a2_events
+           where session_id = ${SESSION}) head
+   where head.idx <> ${param.bigint('ifLastIndex')}`
+
 /**
  * Frees the `ids` this session's rows below its clear marker hold, so the
  * batch can take them. It never waits on a row: a reclaim deleting one may
@@ -1811,6 +1827,11 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
         ]
         const work = enqueue(events, consumers)
         const originIndex = appendOptions?.originIndex
+        const ifLastIndex = appendOptions?.ifLastIndex
+        const conditionalAt = (head: unknown) =>
+          ifLastIndex === undefined
+            ? undefined
+            : { sessionId, ifLastIndex, head: asNumber(head) }
         // One round trip, holding the session lock only while the server
         // runs it: index assignment must not race across writers.
         const results = await run({
@@ -1819,6 +1840,7 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
             LOCK_SESSION,
             APPEND_CHECKS,
             causes.length > 0 && FENCE,
+            ifLastIndex !== undefined && IF_LAST_INDEX,
             suppliedIds.length > 0 && REUSE_IDS,
             INSERT_EVENTS,
             ...work.statements,
@@ -1829,6 +1851,7 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
             ids: suppliedIds,
             count: events.length,
             origin: originIndex ?? null,
+            ifLastIndex: ifLastIndex ?? null,
             // Attempt-currency fence: a fresh consumer append commits only
             // while its causal attempt still owns the cursor's head
             // (store.ts `append`).
@@ -1846,9 +1869,9 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
             switch (reason['abort']) {
               case 'mixed': {
                 const owned = asNumber(reason['owned'])
-                return new A2Error(
-                  'PARTIAL_DUPLICATE_BATCH',
+                return duplicateBatchError(
                   `batch mixes ${owned} already-appended and ${events.length - owned} fresh events`,
+                  conditionalAt(reason['head']),
                 )
               }
               case 'cleared':
@@ -1860,6 +1883,12 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
                   sessionId,
                   causes[asNumber(reason['ord']) - 1]!,
                 )
+              case 'moved':
+                return lastIndexMismatchError(
+                  sessionId,
+                  ifLastIndex!,
+                  asNumber(reason['index']),
+                )
               case 'held':
                 return new A2Error(
                   'STORE_UNAVAILABLE',
@@ -1881,6 +1910,7 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
             events: idempotentReplay(
               events,
               (checked['events'] as Row[]).map(toStored),
+              conditionalAt(checked['head']),
             ),
             hasPending: checked['has_pending'] === true,
           }