experimental-a2 0.17.0 → 0.18.1

package/src/store-sqlite.ts

@@ -470,6 +470,22 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
     }
   }
 
+  /** A dead-lettered event's snapshot pins, and history no pin keeps. */
+  const releasePins = (sessionId: string, index: number): void => {
+    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 {
     async append(sessionId, events, appendOptions) {
       if (events.length === 0) {
@@ -626,6 +642,7 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
       ttlMs,
       expiresAtMs,
       excludeIndexes = [],
+      maxFailures,
     }) {
       return wrap(() =>
         tx(() => {
@@ -638,7 +655,7 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
               : `and event.idx not in (${excludeIndexes.map(() => '?').join(', ')})`
           const eligible = db
             .prepare(
-              `select event.idx
+              `select event.idx, event.claim_holder, event.failure_count
                  from a2_events event
                 where event.session_id = ?
                   and event.processed_at is null
@@ -656,11 +673,15 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
               ...excludeIndexes,
             ) as unknown as Array<{
             idx: number | bigint
+            claim_holder: string | null
+            failure_count: number | bigint
           }>
           if (eligible.length > 0) {
             const update = db.prepare(
               `update a2_events set
                  attempt_count = attempt_count + 1,
+                 failure_count = failure_count
+                   + case when claim_holder is null then 0 else 1 end,
                  first_claimed_at = coalesce(first_claimed_at, ?),
                  last_claimed_at = ?,
                  claim_holder = ?,
@@ -668,15 +689,30 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
                where session_id = ? and idx = ?
                returning *`,
             )
+            // Advancing the attempt fences the lapsed one; nothing runs.
+            const deadLetter = () =>
+              db.prepare(
+                `update a2_events set
+                   attempt_count = attempt_count + 1,
+                   failure_count = failure_count + 1,
+                   failed_at = ?,
+                   claim_holder = null,
+                   claim_expires_at = null
+                 where session_id = ? and idx = ?
+                 returning *`,
+              )
             const events = eligible.map((row) => {
-              const claimed = update.get(
-                now,
-                now,
-                holder,
-                expiresAt,
-                sessionId,
-                row.idx,
+              // A lapsed claim's takeover that spends the last failed attempt.
+              const exhausted =
+                row.claim_holder !== null &&
+                maxFailures !== undefined &&
+                Number(row.failure_count) + 1 >= maxFailures
+              const claimed = (
+                exhausted
+                  ? deadLetter().get(now, sessionId, row.idx)
+                  : update.get(now, now, holder, expiresAt, sessionId, row.idx)
               ) as EventRow
+              if (exhausted) releasePins(sessionId, Number(row.idx))
               const stored = toStored(claimed)
               if (clearIndex > 0) stored.clearIndex = clearIndex
               return stored
@@ -687,15 +723,16 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
           const active = db
             .prepare(
               `select min(claim_expires_at) as retry_at
-                 from a2_events
+                 from a2_events event
                 where session_id = ?
                   and processed_at is null
                   and failed_at is null
                   and lane_ready = 1
                   and idx > ?
-                  and claim_expires_at > ?`,
+                  and claim_expires_at > ?
+                  ${exclusion}`,
             )
-            .get(sessionId, clearIndex, now) as {
+            .get(sessionId, clearIndex, now, ...excludeIndexes) as {
             retry_at: number | bigint | null
           }
           return active.retry_at === null
@@ -908,7 +945,14 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
       )
     },
 
-    async failAttempt({ sessionId, index, attempt, error, maxFailures }) {
+    async failAttempt({
+      sessionId,
+      index,
+      attempt,
+      error,
+      maxFailures,
+      retryAfterMs,
+    }) {
       return wrap(() =>
         tx(() => {
           if (index <= clearIndexOf(sessionId)) {
@@ -954,7 +998,7 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
                last_failed_attempt = ?,
                failed_at = ?,
                claim_holder = null,
-               claim_expires_at = null
+               claim_expires_at = ?
              where session_id = ? and idx = ?`,
           ).run(
             nextFailureCount,
@@ -962,24 +1006,13 @@ export function sqlite(options: SqliteStoreOptions = {}): SqliteStore {
             now,
             attempt,
             deadLettered ? now : null,
+            deadLettered || retryAfterMs === undefined
+              ? null
+              : now + retryAfterMs,
             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)
-          }
+          if (deadLettered) releasePins(sessionId, index)
           return {
             outcome: deadLettered ? 'dead_lettered' : 'failed',
             failureCount: nextFailureCount,
@@ -988,6 +1021,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

@@ -53,9 +53,15 @@ export type StoredEvent = Event & {
   attemptCount: number
   /** Current dispatch holder; null when the event is not claimed. */
   claimHolder: string | null
-  /** Adapter clock expiry for the current dispatch claim. */
+  /**
+   * Adapter clock expiry for the current dispatch claim, or, with no holder,
+   * the end of a failed attempt's retry hold.
+   */
   claimExpiresAt: Date | null
-  /** Caught handler failures. This alone drives dead-lettering. */
+  /**
+   * Failed attempts: caught handler failures, and lapsed claims a later claim
+   * took over. This alone drives dead-lettering.
+   */
   failureCount: number
   /** Adapter clock time recorded by the most recent caught handler failure. */
   lastFailedAt: Date | null
@@ -174,6 +180,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 +261,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,
@@ -266,6 +305,15 @@ export interface A2Store {
     ttlMs: number
     expiresAtMs?: number
     excludeIndexes?: readonly number[]
+    /**
+     * Taking over a lapsed claim (one whose holder is still recorded, never
+     * completed or failed) adds one to `failureCount`. When that reaches
+     * `maxFailures`, the event dead-letters instead of being claimed: it
+     * comes back in `events` with `failedAt` set and no claim. Its
+     * `attemptCount` still advances, fencing the lapsed attempt, and its
+     * `lastFailedAttempt` is unchanged.
+     */
+    maxFailures?: number
   }): Promise<StoreClaimAvailableResult>
 
   /**
@@ -300,7 +348,10 @@ export interface A2Store {
   /**
    * Atomically records a caught failure for one claimed attempt. A stale
    * attempt cannot poison a processed event or a newer dispatch. Accepted
-   * failures record the operation's clock time.
+   * failures record the operation's clock time. A failure that does not
+   * dead-letter releases the claim and, with `retryAfterMs`, keeps the event
+   * unclaimable for that long: its claim expiry is set with no holder, so
+   * `claimAvailable` reports it `busy` until then.
    */
   failAttempt(options: {
     sessionId: string
@@ -308,6 +359,7 @@ export interface A2Store {
     attempt: number
     error: string
     maxFailures: number
+    retryAfterMs?: number
   }): Promise<FailAttemptResult>
 
   /**

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":";;;;;;;;;;;;KA2CY;EACV,KAAK;EACL,GAAG,kBAAkB,WAAW;EAChC,GAAG,gBAAgB;EACnB,GAAG,gBAAgB,WAAW;EAC9B,MAAM,eAAe;;;EAGrB;;;;KCjBG,mBAAmB,UAAU,oBACzB,wBAAwB;KAE5B,wBAAwB,UAAU,gBAAgB,YAClD,WAAW,2BAA0B;KAG9B,YAAY,UAAU,YAAY;WACnC,MAAM,mBAAmB;WACzB;WACA;;KAGC,eAAe,UAAU,eAAe;WACzC;WACA,QAAQ,wBAAwB;WAChC;WACA;;KAGC,YACV,UAAU,YAAY,WACtB,UAAU,eAAe;WAGZ;WACA;WACA;WACA;WACA;;WAGA;WACA;WACA;WACA;WACA;;WAGA;WACA;WACA,iBAAiB,YAAY;WAC7B,WAAW,eAAe;WAC1B;;KAGH,oBACV,SAAS,QAAQ,sBACd,WAAW,QAAQ;KAEZ,mBACV,UAAU,YAAY,WACtB,UAAU,eAAe;EAEzB,aAAa,WAAW,YAAY,GAAG,iBAAiB;EACxD,mBAAmB;;EAEnB;;;;;KC1FU;EACV;EACA;EACA;;;KAIU;EACV;EACA;EACA;EACA;;EAEA;;;KAIU;EACV;EACA;;EAEA;EACA;EACA;;EAEA;EACA,iBAAiB;;EAEjB;;;KAIU;EACV;EACA;;EAEA;EACA;EACA;;EAEA;;EAEA;;;KAIU,gBACV,qBAAqB,sBAAsB;;;KCqBxC,YAAY,uBAAuB,YAEpC;EAAY,oBAAoB;IAC9B;;KAiCM,eACV,UAAU,WACV,gBAAgB,mBAAmB,YACnC,UAAU,eAAe,sBACzB;;EAGA,OAAO,cAAc,GAAG;;EAExB;;EAEA,SAAS,QAAQ,GAAG,cAAc,IAAI,GAAG;;EAEzC,QAAQ;;KAGE,QACV,UAAU,WACV,gBAAgB,mBAAmB,YACnC,UAAU,eAAe,sBACzB,cAEA,KAAK,eAAe,GAAG,GAAG,GAAG,OAC1B,eAAe,YAAY,cAAc,YAAY;KAE9C,YACV,UAAU,WACV,gBAAgB,mBAAmB;EAEnC;EACA,OAAO,KAAK,cAAc,GAAG;IAA4B;;;KAG/C,KACV,UAAU,WACV,gBAAgB,mBAAmB,yBACtB,SAAS,YAAY,GAAG;KAE3B,gBAAgB,UAAU,iBACjC,QAAQ,YAAY,SACpB,QAAQ,cAAc;KAEf,cAAc,UAAU,aAAa,gBAAgB;;EAE/D,UAAU,gBAAgB;;KAGhB,cAAc,UAAU,cAClC,iBACG,QAAQ,YAAY,SACpB,QAAQ,cAAc;KAEf;KAEA;EACR,OAAO;EAAe;;EAAiB,IAAI;EAAM;;KAEzC,gBAAgB,UAAU;GAElC,cACA,QAAQ,mBACL,QAAQ,YAAY,OACtB;;;;;;EAMH,MACE,cACA,SAAS;IAAmB;MAC3B;;KAGO;EACV;;KAGU;;EAEV;;KAGU;EAAuB;EAAkB;;;;;;;;;KASzC,gBAAgB,UAAU,WAAW,UAAU;;;;;;EAMzD,OAAO;IACL;IACA;MACE,cACF,cAAc,KAAK,iBAAiB,cAAc,KAAK,iBAAiB;;;;;;;EAQ1E,YAAY;IACV;IACA,QAAQ,cAAc;IACtB;IACA;MACE;;EAEJ,YAAY,QAAQ,YAAY;;;KAItB,QACV,UAAU,WACV,SAAS,cAAc,IACvB,UAAU,eAAe,sBACzB,aACE,aAAa,GAAG,gBAAgB,GAAG;WAC5B;EACT,QAAQ;EACR,UAAU,gBAAgB;;;;;EAK1B,MAAM,UAAU,sBAAsB,QAAQ;EAC9C,QAAQ;IAAY;IAAc;MAAiB,QAAQ,cAAc;EACzE;KACG,GACC,SAAS,QAAQ,GAAG,GAAG,uBACvB,UAAU,eACT;MAAU,OAAO;MAAG;MAAe;;QAClC;QAEI;MAAU,OAAO;MAAG;MAAe;;;;;;;;EAM7C,OAAO;IACL;MACE,cAAc,cAAc,KAAK;;;;;;;KAQ3B;WACD;aAAqB;;EAC9B,MAAM,oBAAoB;IAAU;;;;;;;;;;;;KAY1B;EACV,SAAS,MAAM,gBAAgB;EAC/B,WAAW,SAAS,qBAAqB,KAAK,YAAY,QAAQ;;KAGxD,SACV,UAAU,WACV,UAAU,eAAe,sBACzB,UAAU,kBAAkB,GAAG,iBAC7B,kBAAkB,GAAG;;WAGd,UAAU,SAAS,GAAG,GAAG;WACzB;KACN,SAAS,UAAU,QAAQ;KAC3B,SAAS,SAAS,SAAS,mBAAmB,GAAG,KAAK,QAAQ;;EAEjE,QAAQ,aAAa,QAAQ,GAAG,cAAc,IAAI,GAAG,YAAY;;;;;EAKjE,MAAM,oBAAoB;IAAU;;;;;;;;iBAiBhB,uBACpB,QAAQ,iBACR,MAAM,sBACL;;;;;;;;iBAgCmB,sBACpB,QAAQ,iBACR,MAAM,qBACL;;;;;;;;;KAiCS,UAAU,UAAU,WAAW,gBAAgB,cACvD,YAAY,iBAET,WAAW,uBAGN,OAAO,cAAc,GAAG,IACxB,SAAS,cAAc,GAAG,IAC1B;EAAW;;KAIX,aACV,UAAU,WACV,gBAAgB,mBAAmB,YACnC,UAAU,eAAe,sBACzB,aAEE,QAAQ,GAAG,GAAG,GAAG;EAEf,UAAU,UAAU,GAAG;;EAEvB,OAAO,KAAK,GAAG;EACf,SAAS,QAAQ,GAAG,GAAG,GAAG;;KAG3B,mBAAmB,eAAe;iBAEvB,QACd,UAAU;EAAoB,SAAS;GACvC,OAAO,IAAI,UAAU;EAAoB,SAAS;IAAM;KAO9C,cACV,UAAU,WACV,UAAU,eAAe,sBACzB,UAAU,kBAAkB,GAAG,iBAC7B,kBAAkB,GAAG;;EAGvB,UAAU,SAAS,GAAG,GAAG;;EAEzB,QAAQ;;;;;;;EAOR,YAAY;;EAEZ,YAAY;;;;;;EAMZ;IAAa;;;;;;;;EAOb,cAAc,WAAW,cAAc,aAAa,GAAG,GAAG,GAAG,YAAY;;;iBAkN3D,aACd,UAAU,WACV,UAAU,eAAe,sBACzB,UAAU,kBAAkB,GAAG,iBAC7B,kBAAkB,GAAG,gBACvB,SAAS,cAAc,GAAG,GAAG,KAAK,SAAS,GAAG,GAAG"}