experimental-a2 0.17.0 → 0.18.0

package/src/store-redis-core.ts

@@ -123,6 +123,23 @@ const READ_CONCURRENCY = 16
 
 const META_CHUNK_SIZE = 1000
 
+/** The metadata columns of a full stored row. */
+const STORED_EVENT_META_SUFFIXES = [
+  'p',
+  'pa',
+  'ri',
+  'ch',
+  'ce',
+  'f',
+  'fc',
+  'lc',
+  'lf',
+  'lfa',
+  'd',
+  'a',
+  'e',
+] as const
+
 /**
  * Upstash bills every call a script makes, so scripts read the counter and
  * split with one MGET, read metadata with one HMGET per hash (`read_fields`),
@@ -278,6 +295,33 @@ local function flush_queue()
 end
 `
 
+/**
+ * Settles one unfinished event for scripts that include ENQUEUE_LUA: it
+ * leaves the pending and ready sets, and a lane head hands its lane to the
+ * next unfinished event. A dead-lettered successor stays out of the ready set.
+ */
+const SETTLE_LUA = `
+local function settle(field, lane, next_field)
+  redis.call('ZREM', PENDING, field)
+  redis.call('ZREM', READY, field)
+  if lane == '' then return end
+  local head_key = lane_field(lane, 'head')
+  if redis.call('HGET', META, head_key) ~= field then return end
+  while next_field do
+    local row = read_fields({ next_field }, { 'p', 'f', 'next' })[next_field]
+    if not row[1] then
+      redis.call('HSET', META, head_key, next_field)
+      if not row[2] then
+        redis.call('ZADD', READY, tonumber(next_field), next_field)
+      end
+      return
+    end
+    next_field = row[3]
+  end
+  clear_lane(lane)
+end
+`
+
 /**
  * Event-id ownership for scripts that add events. Each script reads the
  * counter, split, clear boundary, and per-id keys with one MGET and applies
@@ -611,25 +655,7 @@ ${ENQUEUE_LUA}
 ${ID_OWNERS_LUA}
 ${RELEASE_PINS_LUA}
 ${WAKE_LUA}
-local function settle(field, lane, next_field)
-  redis.call('ZREM', PENDING, field)
-  redis.call('ZREM', READY, field)
-  if lane == '' then return end
-  local head_key = lane_field(lane, 'head')
-  if redis.call('HGET', META, head_key) ~= field then return end
-  while next_field do
-    local row = read_fields({ next_field }, { 'p', 'f', 'next' })[next_field]
-    if not row[1] then
-      redis.call('HSET', META, head_key, next_field)
-      if not row[2] then
-        redis.call('ZADD', READY, tonumber(next_field), next_field)
-      end
-      return
-    end
-    next_field = row[3]
-  end
-  clear_lane(lane)
-end
+${SETTLE_LUA}
 local parent = ARGV[3]
 local attempt = tonumber(ARGV[4])
 local n = tonumber(ARGV[5])
@@ -715,6 +741,78 @@ if n > 0 then wake(ARGV[6 + n * 5], tostring(total + n), ARGV[2]) end
 return { 'ok', tostring(total + 1) }
 `
 
+/**
+ * KEYS: counter, meta, pending, ready, metadata split.
+ * ARGV: idx, action ('retry' | 'skip'), nowMs.
+ * Returns [redriven, hasPending]. Acts only on an unfinished, dead-lettered
+ * event above the clear boundary. A retry keeps the event pending and makes
+ * it ready again when it is unlaned or its lane's head.
+ */
+const REDRIVE_LUA = `
+local COUNTER, META, SPLIT, PENDING, READY = KEYS[1], KEYS[2], KEYS[5], KEYS[3], KEYS[4]
+${META_LUA}
+${ENQUEUE_LUA}
+${SETTLE_LUA}
+local function result(redriven)
+  return { redriven, redis.call('ZCARD', PENDING) > 0 and '1' or '0' }
+end
+local counts = redis.call('MGET', COUNTER, SPLIT, CLEAR)
+local total = tonumber(counts[1] or '0')
+use_split(counts[2], counts[1], counts[3])
+local idx = tonumber(ARGV[1])
+if idx <= boundary or idx > total then return result('0') end
+local field = tostring(idx)
+local row = read_fields({ field }, { 'p', 'f', 'l', 'next' })[field]
+if row[1] or not row[2] then return result('0') end
+local meta_key = mkey(field)
+local lane = row[3] or ''
+if ARGV[2] == 'skip' then
+  put(meta_key, field .. ':p', ARGV[3])
+  settle(field, lane, row[4])
+  flush_queue()
+  flush()
+else
+  redis.call('HDEL', meta_key, field .. ':f', field .. ':a')
+  if lane == '' or redis.call('HGET', META, lane_field(lane, 'head')) == field then
+    redis.call('ZADD', READY, idx, field)
+  end
+end
+return result('1')
+`
+
+/**
+ * KEYS: store, counter, meta, pending, metadata split.
+ * Returns the dead-lettered events above the clear boundary, oldest first,
+ * as pairs of a stream entry and its STORED_EVENT_META_SUFFIXES columns.
+ * Every unfinished event is in the pending set, so the scan is bounded by
+ * unfinished work, not history; only dead letters read their full columns.
+ */
+const DEAD_LETTERS_LUA = `
+local COUNTER, META, SPLIT = KEYS[2], KEYS[3], KEYS[5]
+${META_LUA}
+local counts = redis.call('MGET', COUNTER, SPLIT, CLEAR)
+use_split(counts[2], counts[1], counts[3])
+local candidates = {}
+for _, field in ipairs(redis.call('ZRANGE', KEYS[4], 0, -1)) do
+  if tonumber(field) > boundary then candidates[#candidates + 1] = field end
+end
+local status = read_fields(candidates, { 'p', 'f' })
+local dead = {}
+for _, field in ipairs(candidates) do
+  if status[field][2] and not status[field][1] then dead[#dead + 1] = field end
+end
+local rows = read_fields(dead, { ${STORED_EVENT_META_SUFFIXES.map((suffix) => `'${suffix}'`).join(', ')} })
+local result = {}
+for _, field in ipairs(dead) do
+  local entries = redis.call('XRANGE', KEYS[1], field .. '-0', field .. '-0')
+  if #entries > 0 then
+    result[#result + 1] = entries[1]
+    result[#result + 1] = rows[field]
+  end
+end
+return result
+`
+
 /**
  * KEYS: head, history, event counter, event meta, pin counts, metadata split.
  * ARGV: nowMs, event pin key prefix, write count, then per write:
@@ -1117,22 +1215,6 @@ const fieldMap = (fields: string[]): Record<string, string> => {
   return map
 }
 
-const STORED_EVENT_META_SUFFIXES = [
-  'p',
-  'pa',
-  'ri',
-  'ch',
-  'ce',
-  'f',
-  'fc',
-  'lc',
-  'lf',
-  'lfa',
-  'd',
-  'a',
-  'e',
-] as const
-
 const entryIndex = (entryId: string): number =>
   Number(entryId.slice(0, entryId.indexOf('-')))
 
@@ -1240,6 +1322,46 @@ const toCause = (raw: string | undefined): EventCause | null => {
   }
 }
 
+type MetaSuffix = (typeof STORED_EVENT_META_SUFFIXES)[number]
+
+/** A stream entry joined with its metadata columns; absent columns are unset. */
+const toStoredEvent = (
+  sessionId: string,
+  entry: StreamEntry,
+  column: (suffix: MetaSuffix) => string | undefined,
+): StoredEvent => {
+  const fields = fieldMap(entry[1])
+  const date = (suffix: MetaSuffix): Date | null => {
+    const value = column(suffix)
+    return value === undefined ? null : new Date(Number(value))
+  }
+  const count = (suffix: MetaSuffix): number | null => {
+    const value = column(suffix)
+    return value === undefined ? null : Number(value)
+  }
+  const returnedEventIds = column('ri')
+  return Object.assign(toEvent(sessionId, entry), {
+    cause: toCause(fields['cause']),
+    lane: fields['lane'] === '' ? null : fields['lane']!,
+    processedAt: date('p'),
+    processedByAttempt: count('pa'),
+    returnedEventIds:
+      returnedEventIds === undefined
+        ? null
+        : decodeReturnedEventIds(returnedEventIds),
+    firstClaimedAt: date('fc'),
+    lastClaimedAt: date('lc'),
+    attemptCount: count('d') ?? 0,
+    claimHolder: column('ch') ?? null,
+    claimExpiresAt: date('ce'),
+    failureCount: count('a') ?? 0,
+    lastFailedAt: date('lf'),
+    lastFailedAttempt: count('lfa'),
+    lastError: column('e') ?? null,
+    failedAt: date('f'),
+  })
+}
+
 const toClaimAvailableResult = (
   sessionId: string,
   reply: unknown[],
@@ -1471,50 +1593,12 @@ export function createRedisStoreCore(
       }
     }
     return entries.map((entry) => {
-      const event = toEvent(sessionId, entry)
-      const idx = event.index
-      const fields = fieldMap(entry[1])
-      const processedAt = meta[`${idx}:p`]
-      const processedByAttempt = meta[`${idx}:pa`]
-      const returnedEventIds = meta[`${idx}:ri`]
-      const claimHolder = meta[`${idx}:ch`]
-      const claimExpiresAt = meta[`${idx}:ce`]
-      const failedAt = meta[`${idx}:f`]
-      const firstClaimedAt = meta[`${idx}:fc`]
-      const lastClaimedAt = meta[`${idx}:lc`]
-      const lastFailedAt = meta[`${idx}:lf`]
-      const lastFailedAttempt = meta[`${idx}:lfa`]
-      return Object.assign(event, {
-        cause: toCause(fields['cause']),
-        lane: fields['lane'] === '' ? null : fields['lane']!,
-        processedAt:
-          processedAt === undefined ? null : new Date(Number(processedAt)),
-        processedByAttempt:
-          processedByAttempt === undefined ? null : Number(processedByAttempt),
-        returnedEventIds:
-          returnedEventIds === undefined
-            ? null
-            : decodeReturnedEventIds(returnedEventIds),
-        firstClaimedAt:
-          firstClaimedAt === undefined
-            ? null
-            : new Date(Number(firstClaimedAt)),
-        lastClaimedAt:
-          lastClaimedAt === undefined ? null : new Date(Number(lastClaimedAt)),
-        attemptCount: Number(meta[`${idx}:d`] ?? 0),
-        claimHolder: claimHolder ?? null,
-        claimExpiresAt:
-          claimExpiresAt === undefined
-            ? null
-            : new Date(Number(claimExpiresAt)),
-        failureCount: Number(meta[`${idx}:a`] ?? 0),
-        lastFailedAt:
-          lastFailedAt === undefined ? null : new Date(Number(lastFailedAt)),
-        lastFailedAttempt:
-          lastFailedAttempt === undefined ? null : Number(lastFailedAttempt),
-        lastError: meta[`${idx}:e`] ?? null,
-        failedAt: failedAt === undefined ? null : new Date(Number(failedAt)),
-      })
+      const idx = entryIndex(entry[0])
+      return toStoredEvent(
+        sessionId,
+        entry,
+        (suffix) => meta[`${idx}:${suffix}`],
+      )
     })
   }
 
@@ -2039,6 +2123,53 @@ export function createRedisStoreCore(
       })
     },
 
+    async deadLetters(sessionId) {
+      return wrap(async () => {
+        const reply = (await evalScript(
+          DEAD_LETTERS_LUA,
+          [
+            storeKey(sessionId),
+            countKey(sessionId),
+            metaKey(sessionId),
+            pendingKey(sessionId),
+            metaSplitKey(sessionId),
+          ],
+          [],
+        )) as unknown[]
+        const events: StoredEvent[] = []
+        for (let i = 0; i + 1 < reply.length; i += 2) {
+          const columns = reply[i + 1] as Array<string | null>
+          events.push(
+            toStoredEvent(
+              sessionId,
+              reply[i] as StreamEntry,
+              (suffix) =>
+                columns[STORED_EVENT_META_SUFFIXES.indexOf(suffix)] ??
+                undefined,
+            ),
+          )
+        }
+        return events
+      })
+    },
+
+    async redrive({ sessionId, index, action }) {
+      return wrap(async () => {
+        const [redriven, hasPending] = (await evalScript(
+          REDRIVE_LUA,
+          [
+            countKey(sessionId),
+            metaKey(sessionId),
+            pendingKey(sessionId),
+            readyKey(sessionId),
+            metaSplitKey(sessionId),
+          ],
+          [index, action, clock.now().getTime()],
+        )) as [string, string]
+        return { redriven: redriven === '1', hasPending: hasPending === '1' }
+      })
+    },
+
     async readState(sessionId, reducerName, stateOptions) {
       return wrap(() =>
         retryAfterGap(async () => {

package/src/store-redis-notify.ts

@@ -292,6 +292,8 @@ export function createRedisNotifyStore(options: {
     putSnapshots: core.putSnapshots,
     clear: core.clear!,
     reclaim: core.reclaim!,
+    deadLetters: core.deadLetters!,
+    redrive: core.redrive!,
 
     presence: {
       async set(ns, participant, values, meta) {

package/src/store-sqlite.ts

@@ -988,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

package/src/store.ts

@@ -174,6 +174,20 @@ export type StoreClearResult = {
 
 export type StoreReclaimResult = { deleted: number; done: boolean }
 
+export type StoreRedriveOptions = {
+  sessionId: string
+  index: number
+  /** `retry` clears the dead letter; `skip` settles it without a handler. */
+  action: 'retry' | 'skip'
+}
+
+export type StoreRedriveResult = {
+  /** Whether the event was dead-lettered and this operation resolved it. */
+  redriven: boolean
+  /** Whether the session contains an event without a completion marker. */
+  hasPending: boolean
+}
+
 /**
  * An injectable clock. Adapters take one so tests can drive claim
  * expiry, failure timestamps, and (later) stuck-session detection
@@ -241,6 +255,25 @@ export interface A2Store {
    */
   reclaim?(sessionId: string): Promise<StoreReclaimResult>
 
+  /**
+   * Optional with `redrive`. The session's dead-lettered events above the
+   * latest clear marker, oldest first.
+   */
+  deadLetters?(sessionId: string): Promise<StoredEvent[]>
+
+  /**
+   * Optional with `deadLetters`. Atomically resolves one dead-lettered event
+   * above the latest clear marker; any other event is untouched and reports
+   * `redriven: false`. `retry` clears `failedAt` and `failureCount`, so the
+   * event is claimable again with a fresh failure budget, keeping its claim
+   * history and last failure. `skip` records `processedAt` with no
+   * `processedByAttempt` or `returnedEventIds` and exposes the next event in
+   * its lane. Both serialize with `claimAvailable` and the handler-append
+   * parent fence; `skip` also serializes with lane promotion in `append` and
+   * `completeAttempt`. `hasPending` is read in the same step.
+   */
+  redrive?(options: StoreRedriveOptions): Promise<StoreRedriveResult>
+
   /** Events for one session, oldest first. Bounds form `(afterIndex, throughIndex]`. */
   read(
     sessionId: string,

package/src/telemetry.ts

@@ -17,6 +17,7 @@ export type A2SpanName =
   | 'a2.commit'
   | 'a2.state'
   | 'a2.snapshot'
+  | 'a2.redrive'
   | 'a2.ai.control'
   | 'a2.ai.ack'
   | 'a2.ai.generate'

package/dist/internal-CbVvEwad.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"internal-CbVvEwad.js","names":[],"sources":["../src/internal.ts"],"sourcesContent":["/**\n * Private seams shared by a2 entry points and a2's own tests. Not exported\n * from the package. Nothing here is public API.\n */\n\nimport type { ScheduledEvent } from './scheduler-task.ts'\nimport type { DrainableServer } from './server.ts'\nimport type { Event } from './store.ts'\n\nexport type DrainOutcome = 'busy' | 'stalled' | 'settled'\n\n/**\n * A null-prototype record for maps keyed by caller-controlled strings\n * (participant ids, presence field names). On a normal object,\n * assigning to '__proto__' rewrites the prototype instead of creating\n * an own property — the prototype-pollution class. Null-prototype\n * objects still satisfy Record types and JSON.stringify cleanly.\n */\nexport function nullProtoRecord<T extends object>(): T {\n  return Object.create(null) as T\n}\n\n/**\n * ECMA-262's maximum Date value (±8.64e15 ms). A presence stamp past\n * it becomes an Invalid Date whose toISOString throws — one hostile\n * stamp would poison every subscriber's snapshot frame — so both\n * seams bound `at` to the representable range.\n */\nexport const MAX_DATE_MS = 8_640_000_000_000_000\n\n/**\n * Participant ids that collide with Object.prototype plumbing.\n * Null-prototype construction already defuses them, but they are\n * rejected at both seams (`parsePushBody`, `setPresence`) so a hostile\n * id never propagates into userland maps either.\n */\nexport const RESERVED_PARTICIPANT_IDS: ReadonlySet<string> = new Set([\n  '__proto__',\n  'constructor',\n  'prototype',\n])\n\nexport type DrainResult = {\n  settled: boolean\n  outcome: DrainOutcome\n  /** Existing successor arm a scheduler callback may join before acking. */\n  schedulerArm?: Promise<void>\n}\n\nexport type ServerInternals = {\n  /**\n   * Await every in-flight background drain this machine has scheduled,\n   * including ones scheduled while waiting. Lets tests flush the\n   * fire-and-forget inline path deterministically — no sleeps.\n   */\n  settle(): Promise<void>\n  /** The public `server.drain()` result deliberately remains `{ settled }`. */\n  schedulerDrain(\n    sessionId: string,\n    opts?: { watchdogDueAt?: number },\n  ): Promise<DrainResult>\n  /** Deliver a scheduler-owned delayed append through the normal root path. */\n  schedulerAppend(\n    sessionId: string,\n    events: readonly ScheduledEvent[],\n    originIndex?: number,\n  ): Promise<void>\n  /** Deliver a scheduler-owned conditional clear, deletion included. */\n  schedulerClear(sessionId: string, ifLastIndex: number): Promise<void>\n  /** `session.history` with clear markers kept; reads start at the latest one. */\n  historyWithMarkers(sessionId: string, gte: number): Promise<Event[]>\n}\n\nexport const serverInternals: WeakMap<object, ServerInternals> = new WeakMap()\n\nconst objectLike = (value: unknown): value is object =>\n  (typeof value === 'object' && value !== null) || typeof value === 'function'\n\n/** The ambient value delivered to `handlerContext` during a tool execution. */\nexport type AmbientToolScope = {\n  /** Executing server identity; a test scope from `runWithHandlerContext` has none. */\n  contract?: { readonly name: string }\n  context: unknown\n}\n\n/**\n * Structural AsyncLocalStorage surface for the ambient tool scope. The\n * instance is created by the server-only AI entry point (the only place\n * `node:async_hooks` may be imported) and shared through a global\n * symbol slot, so `handlerContext` in the isomorphic AI entry point and\n * independently bundled A2 copies all read the same scope.\n */\nexport type AmbientToolScopeStorage = {\n  getStore(): AmbientToolScope | undefined\n  run<R>(store: AmbientToolScope, callback: () => R): R\n}\n\nconst TOOL_SCOPE_STORAGE = Symbol.for('experimental-a2.ai.tool-scope')\n\nexport function ambientToolScopeStorage(): AmbientToolScopeStorage | undefined {\n  const value = Reflect.get(globalThis, TOOL_SCOPE_STORAGE)\n  if (\n    !objectLike(value) ||\n    typeof Reflect.get(value, 'getStore') !== 'function' ||\n    typeof Reflect.get(value, 'run') !== 'function'\n  ) {\n    return undefined\n  }\n  return value as AmbientToolScopeStorage\n}\n\nexport function installAmbientToolScopeStorage(\n  create: () => AmbientToolScopeStorage,\n): AmbientToolScopeStorage {\n  const existing = ambientToolScopeStorage()\n  if (existing !== undefined) return existing\n  const storage = create()\n  Reflect.set(globalThis, TOOL_SCOPE_STORAGE, storage)\n  return storage\n}\n\nexport type SchedulerSendFailureDisposition = 'retryable' | 'terminal'\n\ntype SchedulerSendFailureMarker = {\n  readonly version: 1\n  readonly pending: SchedulerSendFailureDisposition[]\n  readonly active: SchedulerSendFailureDisposition[]\n}\n\nconst SCHEDULER_SEND_FAILURE = Symbol.for(\n  'experimental-a2.scheduler.send-failure',\n)\n\nconst schedulerSendFailureMarker = (\n  value: unknown,\n): SchedulerSendFailureMarker | undefined => {\n  if (!objectLike(value)) return undefined\n  const marker = Reflect.get(value, SCHEDULER_SEND_FAILURE)\n  if (\n    !objectLike(marker) ||\n    Reflect.get(marker, 'version') !== 1 ||\n    !Array.isArray(Reflect.get(marker, 'pending')) ||\n    !Array.isArray(Reflect.get(marker, 'active'))\n  ) {\n    return undefined\n  }\n  return marker as SchedulerSendFailureMarker\n}\n\nconst schedulerFailureObject = (error: unknown): object => {\n  if (\n    objectLike(error) &&\n    (schedulerSendFailureMarker(error) !== undefined ||\n      Object.isExtensible(error))\n  ) {\n    return error\n  }\n  return new Error(String(error), { cause: error })\n}\n\nconst schedulerSendFailureState = (\n  error: object,\n): SchedulerSendFailureMarker => {\n  const existing = schedulerSendFailureMarker(error)\n  if (existing !== undefined) return existing\n  const marker: SchedulerSendFailureMarker = {\n    version: 1,\n    pending: [],\n    active: [],\n  }\n  Object.defineProperty(error, SCHEDULER_SEND_FAILURE, {\n    value: marker,\n    enumerable: false,\n    configurable: true,\n    writable: false,\n  })\n  return marker\n}\n\nconst clearSchedulerSendFailureState = (\n  error: object,\n  marker: SchedulerSendFailureMarker,\n): void => {\n  if (marker.pending.length === 0 && marker.active.length === 0) {\n    Reflect.deleteProperty(error, SCHEDULER_SEND_FAILURE)\n  }\n}\n\n/**\n * Classify an adapter error before throwing it. Unclassified adapter failures\n * are retryable because the caller cannot know whether a remote send landed.\n */\nexport function classifySchedulerSendFailure(\n  error: unknown,\n  disposition: SchedulerSendFailureDisposition,\n): unknown {\n  const classified = schedulerFailureObject(error)\n  schedulerSendFailureState(classified).pending.push(disposition)\n  return classified\n}\n\n/** Consume a pending adapter classification and count this rejected send. */\nexport function markSchedulerSendFailure(error: unknown): unknown {\n  const marked = schedulerFailureObject(error)\n  const marker = schedulerSendFailureState(marked)\n  marker.active.push(marker.pending.pop() ?? 'retryable')\n  return marked\n}\n\nexport function consumeSchedulerSendFailure(\n  error: unknown,\n): SchedulerSendFailureDisposition | undefined {\n  if (!objectLike(error)) return undefined\n  const marker = schedulerSendFailureMarker(error)\n  const disposition = marker?.active.pop()\n  if (marker !== undefined) clearSchedulerSendFailureState(error, marker)\n  return disposition\n}\n\nconst isDrainableServer = (value: unknown): value is DrainableServer => {\n  if (value === null || typeof value !== 'object') return false\n  const contract = Reflect.get(value, 'contract')\n  return (\n    contract !== null &&\n    typeof contract === 'object' &&\n    typeof Reflect.get(contract, 'name') === 'string' &&\n    typeof Reflect.get(value, 'drain') === 'function'\n  )\n}\n\n/**\n * Validate the server list captured by a scheduler route at construction time.\n * The seam stays structural so custom scheduler integrations can supply their\n * own drainable targets.\n */\nexport function assertSchedulerTargets(\n  servers: readonly unknown[],\n): asserts servers is readonly DrainableServer[] {\n  const contracts = new Set<string>()\n  for (const target of servers) {\n    if (!isDrainableServer(target)) {\n      throw new TypeError('a2 scheduler: expected a server from createServer()')\n    }\n    const name = target.contract.name\n    if (contracts.has(name)) {\n      throw new TypeError(\n        `a2 scheduler: duplicate server contract '${name}' in one handler`,\n      )\n    }\n    contracts.add(name)\n  }\n}\n\n/**\n * Drain timing knobs. Mutable only as a white-box test seam. Claim\n * heartbeats run on real timers, so tests shrink these to keep suites\n * fast. Production always uses the defaults.\n */\nexport const DRAIN_TIMINGS: {\n  /** How long a claim lives without renewal. */\n  claimTtlMs: number\n  /** Heartbeat cadence while a handler is running. */\n  claimHeartbeatMs: number\n  /** Base delay before retrying a failed renewal while the lease lives. */\n  renewRetryMs: number\n  /** Delay between a claim's expiry and its scheduler watchdog. */\n  watchdogGraceMs: number\n  /** Maximum time a top-level append waits for its initial scheduler arm. */\n  schedulerArmTimeoutMs: number\n} = {\n  claimTtlMs: 5_000,\n  claimHeartbeatMs: 2_000,\n  renewRetryMs: 400,\n  watchdogGraceMs: 1_000,\n  schedulerArmTimeoutMs: 2_000,\n}\n\n/**\n * Stream liveness knobs — the server-side SSE heartbeat and the\n * client-side stall watchdog. Paired by design: the client declares a\n * connection dead after roughly two missed heartbeats. Mutable only as\n * a white-box test seam; production always uses the defaults.\n */\n/**\n * Poll cadence for the poll-based store streams (sqlite, postgres) —\n * owned, not configurable: adaptive polling removed the operator's\n * reason to tune it (the floor keeps active streams smooth; the\n * ceiling bounds idle cost). Mutable only as a white-box test seam so\n * suites don't wait out real idle gaps.\n */\nexport const POLL_TIMINGS: {\n  /** Gap between polls while a session is producing events. */\n  activeFloorMs: number\n  /** The idle ceiling — the longest gap between polls. */\n  idleCeilingMs: number\n} = {\n  activeFloorMs: 25,\n  idleCeilingMs: 2_000,\n}\n\n/**\n * Safety-read cadence for the notify-driven redis live stream. A\n * parked feed re-reads the store at this interval even without a\n * pub/sub wake-up, so a lost notification (subscriber reconnect gap,\n * dropped PUBLISH) costs latency, never an event. Mutable only as a\n * white-box test seam.\n */\nexport const NOTIFY_TIMINGS: {\n  safetyReadMs: number\n} = {\n  safetyReadMs: 10_000,\n}\n\n/**\n * Bounds for each server instance's in-memory reducer-state cache. Sizes are\n * encoded JSON lengths, re-measured every `measureEvery` folded events, so\n * the byte budget is approximate. Mutable only as a white-box test seam.\n */\nexport const STATE_CACHE: {\n  maxEntries: number\n  maxBytes: number\n  /** Events a cached state may advance before it writes a snapshot. */\n  snapshotEvery: number\n  /** Events a warm read may fold; longer tails read the stored snapshot. */\n  maxTail: number\n  /** Events folded between re-measuring a cached state's encoded size. */\n  measureEvery: number\n} = {\n  maxEntries: 1_000,\n  maxBytes: 32 * 1024 * 1024,\n  snapshotEvery: 128,\n  maxTail: 255,\n  measureEvery: 16,\n}\n\n/**\n * Warm state-read tails for stores that can serve one in a single request:\n * events from `fromIndex` (inclusive) through `throughIndex` or the newest\n * event, or null when that needs more than one request. Like every store\n * read, a tail starts no lower than the latest clear marker. Keyed by the exact\n * store object, so a wrapper built by spreading or proxying a store reads\n * through its own `readHistory` instead.\n */\nexport const stateTailReaders: WeakMap<\n  object,\n  (\n    sessionId: string,\n    fromIndex: number,\n    throughIndex?: number,\n  ) => Promise<Event[] | null>\n> = new WeakMap()\n\nexport const STREAM_TIMINGS: {\n  /** Cadence of `: ping` comment frames from `sseResponse`. */\n  sseHeartbeatMs: number\n  /** How far ahead of an invocation deadline an SSE response closes. */\n  sseDeadlineGraceMs: number\n  /** Client: silence longer than this means the connection is dead. */\n  stallTimeoutMs: number\n  /** Client reconnect backoff: first retry delay, doubling per attempt. */\n  reconnectBaseMs: number\n  /** Client reconnect backoff ceiling. */\n  reconnectMaxMs: number\n} = {\n  sseHeartbeatMs: 15_000,\n  sseDeadlineGraceMs: 1_000,\n  stallTimeoutMs: 35_000,\n  reconnectBaseMs: 500,\n  reconnectMaxMs: 5_000,\n}\n\n/**\n * WebSocket down-pump backpressure — `sessionsSocket` parks its pull\n * loop while the socket reports more buffered bytes than the\n * high-water mark and re-checks on the poll cadence, so a slow reader\n * applies backpressure to the store subscription instead of buffering\n * without bound in the socket. Acks and heartbeats stay exempt: they\n * are small and correctness-relevant. Mutable only as a white-box test\n * seam.\n */\nexport const SOCKET_TIMINGS: {\n  highWaterMarkBytes: number\n  resumePollMs: number\n  /** Up-lane bound: concurrent push/presence handlers per socket. POST\n   * gets per-request platform limits for free; the socket must bring\n   * its own. Over the cap, pushes are answered with a retryable error\n   * ack and presence frames are shed (that plane repaints). */\n  maxInFlightMessages: number\n  /** Hard ceiling on `bufferedAmount`: past it the peer is a\n   * non-reader (acks and pings are park-exempt, so only a peer that\n   * never reads can reach it) and the socket closes 1008. */\n  disconnectWaterMarkBytes: number\n} = {\n  highWaterMarkBytes: 1_048_576,\n  resumePollMs: 25,\n  maxInFlightMessages: 32,\n  disconnectWaterMarkBytes: 8_388_608,\n}\n\n/**\n * Client presence send cadence — a leading send immediately, then at\n * most one merged send per interval (~15Hz). Owned, not configurable\n * (decision #36's rule): coupling the cadence to the POST ack tied\n * remote cursor smoothness to RTT, and the ack serves no correctness\n * purpose on a fire-and-forget LWW plane. Mutable only as a white-box\n * test seam.\n */\nexport const PRESENCE_TIMINGS: {\n  sendIntervalMs: number\n} = {\n  sendIntervalMs: 66,\n}\n"],"mappings":"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"}

package/dist/server-CGM8WzRG.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"server-CGM8WzRG.d.ts","names":[],"sources":["../src/session-socket.ts","../src/server-fetch.ts","../src/scheduler-task.ts","../src/server.ts"],"mappings":"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"}