experimental-a2 0.12.0 → 0.14.0

package/dist/store-N8PXxDAS.js.map

@@ -1 +1 @@
-{"version":3,"file":"store-N8PXxDAS.js","names":[],"sources":["../src/store.ts"],"sourcesContent":["/**\n * The A2Store interface — the storage contract every store backend\n * implements. See specs/a2-implementation.md §2–3.\n *\n * This is the whole storage contract: append, read, dispatch claims,\n * failure markers, snapshots, and the live stream. The scheduler\n * needs nothing extra — the armed queue message is its own state, and\n * the store is the only thing it consults.\n */\n\nimport type { PresencePatch } from './contract.ts'\n\n/** A stored event, as the public API exposes it. */\nexport type Event = {\n  id: string\n  type: string\n  payload: unknown\n  /** Position in the session's event log, from 1. */\n  index: number\n  sessionId: string\n  createdAt: Date\n}\n\n/** The handler dispatch whose append first persisted a child event. */\nexport type EventCause = {\n  index: number\n  attempt: number\n  /** Size of one named handler append, used to reject truncated retries. */\n  batchSize?: number\n}\n\n/**\n * What the store persists: immutable event history, including its causal edge,\n * plus derived dispatch and failure bookkeeping. The bookkeeping is disposable;\n * the event and its cause are not.\n */\nexport type StoredEvent = Event & {\n  /** Same-session handler dispatch that appended this event; null means root. */\n  cause: EventCause | null\n  /** Session-scoped serial execution key resolved when the event is appended. */\n  lane: string | null\n  /** Adapter clock time recorded by append settlement, completion, or manual skip; null while pending. */\n  processedAt: Date | null\n  /** Dispatch attempt that completed this event; null without dispatch or while pending. */\n  processedByAttempt: number | null\n  /** Exact ordered child ids atomically returned by the completing attempt. */\n  returnedEventIds: string[] | null\n  /** Adapter clock time recorded by the first durable dispatch claim. */\n  firstClaimedAt: Date | null\n  /** Adapter clock time recorded by the most recent durable dispatch claim. */\n  lastClaimedAt: Date | null\n  /** Durable dispatch claims, including claims abandoned by hard kills. */\n  attemptCount: number\n  /** Current dispatch holder; null when the event is not claimed. */\n  claimHolder: string | null\n  /** Adapter clock expiry for the current dispatch claim. */\n  claimExpiresAt: Date | null\n  /** Caught handler failures. This alone drives dead-lettering. */\n  failureCount: number\n  /** Adapter clock time recorded by the most recent caught handler failure. */\n  lastFailedAt: Date | null\n  /** Dispatch attempt that produced the most recent caught handler failure. */\n  lastFailedAttempt: number | null\n  /** The last handler failure, stringified. */\n  lastError: string | null\n  /** Adapter clock time recorded when dead-lettered; null otherwise. */\n  failedAt: Date | null\n}\n\n/**\n * One live presence value, as `A2Store.presence.read` returns it. The\n * row is the LWW unit — one participant's one field. `at` is the\n * sender's stamp, the LWW comparator. `expiresAt` is the storage's\n * own clock at the applied set plus its `ttlMs` — never derived from\n * the sender stamp; a row is live strictly before it.\n */\nexport type PresenceRow = {\n  participant: string\n  field: string\n  value: unknown\n  seen: number\n  at: Date\n  expiresAt: Date\n}\n\n/** One consistent cache-plus-tail read for a reducer fold. */\nexport type StoreStateRead = {\n  /** The current head checkpoint, even when an older historical snapshot is selected. */\n  headIndex: number | null\n  /** The greatest cached fold at or before the requested snapshot frontier. */\n  snapshot: { index: number; state: unknown } | null\n  /** Immutable events strictly after `snapshot.index`, or the full log on a miss. */\n  events: Event[]\n}\n\nexport type StoreSnapshotWrite = {\n  index: number\n  state: unknown\n  /** Unfinished trigger events that durably retain this exact checkpoint. */\n  pinEventIndexes?: readonly number[]\n}\n\nexport type StoreStateReadRequest = {\n  sessionId: string\n  throughIndex?: number\n  snapshotThroughIndex?: number\n}\n/** The result of atomically claiming every currently eligible event. */\nexport type StoreClaimAvailableResult =\n  | { outcome: 'claimed'; events: StoredEvent[] }\n  | { outcome: 'busy'; retryAt: Date }\n  | { outcome: 'settled' }\n\n/** A completion may lose to a newer claim or an earlier completion. */\nexport type CompleteAttemptResult =\n  { outcome: 'completed'; events: StoredEvent[] } | { outcome: 'superseded' }\n\n/** The result of one claim-renewal heartbeat, both lists in append order. */\nexport type RenewClaimsResult = {\n  /** Listed claims that remain owned by the holder. */\n  renewed: number[]\n  /** Listed claims whose event a newer attempt has durably taken. */\n  superseded: number[]\n}\n\n/** The result of atomically recording a caught handler failure. */\nexport type FailAttemptResult = {\n  outcome: 'failed' | 'dead_lettered' | 'superseded'\n  failureCount: number\n}\n\n/** Input to `A2Store.append` — already validated by the machine. */\nexport type AppendEvent = {\n  type: string\n  payload: unknown\n  /** Caller-supplied idempotency key; generated when absent. */\n  id?: string\n  /** Internal causal edge supplied atomically by handler `session.append`. */\n  cause?: EventCause\n  /** Session-scoped serial execution key resolved before persistence. */\n  lane?: string\n  /** Internal hint: settle this event in the append transaction; no handler is registered. */\n  settled?: true\n}\n\n/** A handler-returned event with the deterministic id retries require. */\nexport type ReturnedEvent = AppendEvent & { id: string }\n\n/** The rows written by an append and the session's pending state. */\nexport type StoreAppendResult = {\n  events: StoredEvent[]\n  /** Whether the session contains an event without a completion marker. */\n  hasPending: boolean\n}\n\n/**\n * An injectable clock. Adapters take one so tests can drive claim\n * expiry, failure timestamps, and (later) stuck-session detection\n * deterministically — against real storage, no mocking.\n */\nexport type Clock = {\n  now(): Date\n}\n\n/** An injectable id source for generated event ids. */\nexport type IdSource = () => string\n\nexport const SYSTEM_CLOCK: Clock = {\n  now: () => new Date(),\n}\n\nexport const RANDOM_IDS: IdSource = () => crypto.randomUUID()\n\nexport interface A2Store {\n  /**\n   * Accepts a batch; the batch is atomic — one transaction, consecutive\n   * `index`es, all-or-nothing. The idempotency key covers the whole\n   * operation, not each item: if *every* event's `id` already exists in\n   * this session, this is a retry of a committed batch whose ack was\n   * lost — return the existing rows as success. If only *some* ids\n   * exist, the caller mixed an already-sent batch with fresh events —\n   * always a caller bug — so throw `A2Error('PARTIAL_DUPLICATE_BATCH')`.\n   * Events carrying `settled: true` get `processedAt` in this same atomic\n   * operation, with no dispatch claim or `processedByAttempt`. The result's\n   * `hasPending` reflects the whole session in the same atomic operation,\n   * including older events and idempotent retries.\n   *\n   * An event carrying `cause` is a handler append, fenced by attempt\n   * currency: accept it only while `cause.attempt` is still the parent\n   * event's latest attempt and the parent is not dead-lettered; otherwise\n   * throw `A2Error('SUPERSEDED_ATTEMPT')` and write nothing. The check is\n   * part of this atomic operation and must serialize against a concurrent\n   * `claimAvailable` — an unlocked read of the parent admits write skew.\n   * The idempotent-replay path runs first, so a batch whose ids all exist\n   * replays regardless of the current attempt.\n   */\n  append(sessionId: string, events: AppendEvent[]): Promise<StoreAppendResult>\n\n  /** Events for one session, oldest first. Bounds form `(afterIndex, throughIndex]`. */\n  read(\n    sessionId: string,\n    opts?: { afterIndex?: number; throughIndex?: number },\n  ): Promise<StoredEvent[]>\n\n  /**\n   * Atomically claims every eligible pending event. Unlaned events are all\n   * independently eligible. Within a lane, only the lowest-index unfinished\n   * event is eligible. A live claim produces `busy` only when it is the sole\n   * remaining obstacle to actionable work. Claimed events are returned in event-log\n   * order. Excluded rows remain lane barriers.\n   */\n  claimAvailable(options: {\n    sessionId: string\n    holder: string\n    ttlMs: number\n    expiresAtMs?: number\n    excludeIndexes?: readonly number[]\n  }): Promise<StoreClaimAvailableResult>\n\n  /**\n   * Renews the listed live claims still owned by `holder`. Each listed claim\n   * carries the attempt ordinal the holder owns. `renewed` lists the claims\n   * that remain owned after the operation; `superseded` lists the claims\n   * whose event's `attemptCount` has durably passed the listed attempt. An\n   * expired claim no successor has taken appears in neither list — its\n   * attempt may still complete (`completeAttempt` is the fence), so it is\n   * not reported as lost. Renewal never revives an expired claim.\n   */\n  renewClaims(options: {\n    sessionId: string\n    holder: string\n    claims: readonly { index: number; attempt: number }[]\n    ttlMs: number\n    expiresAtMs?: number\n  }): Promise<RenewClaimsResult>\n\n  /**\n   * Atomically completes one current attempt and appends its returned events.\n   * Retrying a committed completion with the same attempt and deterministic\n   * child ids returns the existing children. A stale attempt never appends.\n   */\n  completeAttempt(options: {\n    sessionId: string\n    index: number\n    attempt: number\n    events: ReturnedEvent[]\n  }): Promise<CompleteAttemptResult>\n\n  /**\n   * Atomically records a caught failure for one claimed attempt. A stale\n   * attempt cannot poison a processed event or a newer dispatch. Accepted\n   * failures record the operation's clock time.\n   */\n  failAttempt(options: {\n    sessionId: string\n    index: number\n    attempt: number\n    error: string\n    maxFailures: number\n  }): Promise<FailAttemptResult>\n\n  /**\n   * Reads a reducer snapshot and its event tail as one consistent adapter\n   * operation. On a cache miss, `snapshot` is null and `events` is the full\n   * log. The snapshot is untrusted; core may reject it and issue a full\n   * `read()` when its state schema no longer accepts the cached value.\n   */\n  readState(\n    sessionId: string,\n    reducerName: string,\n    options?: { throughIndex?: number; snapshotThroughIndex?: number },\n  ): Promise<StoreStateRead>\n\n  /**\n   * Optional batched `readState` — one consistent snapshot-plus-tail read\n   * per session id, aligned positionally with the input (duplicates\n   * allowed). Each element has its own frontier; the batch makes no\n   * cross-session consistency claim. Core falls back to parallel\n   * `readState` calls when absent.\n   */\n  readStates?(\n    requests: readonly StoreStateReadRequest[],\n    reducerName: string,\n  ): Promise<StoreStateRead[]>\n\n  /**\n   * Atomically writes disposable reducer checkpoints. The greatest index\n   * advances the head cache. Older checkpoints survive only when at least one\n   * listed trigger event is still unfinished; completion and dead-lettering\n   * release that event's pins and collect unreferenced historical checkpoints.\n   */\n  putSnapshots(\n    sessionId: string,\n    reducerName: string,\n    snapshots: readonly StoreSnapshotWrite[],\n  ): Promise<void>\n\n  /**\n   * Optional ephemeral-plane capability (specs/a2-implementation.md\n   * §15.1) — optional like snapshots are. Values arrive already\n   * validated by core; adapters store them opaquely. Presence never\n   * touches the event log: no index, no history row, no recovery arm.\n   */\n  presence?: {\n    /**\n     * Field-wise last-writer-wins merge of one participant's values:\n     * a field whose existing row has a strictly newer `at` (the\n     * sender's stamp) is left untouched; `null` deletes the row. Every\n     * applied write refreshes that field's expiry to the storage's own\n     * clock plus `ttlMs` — the sender stamp orders writes but never\n     * anchors their lifetime.\n     */\n    set(\n      ns: string,\n      participant: string,\n      values: Record<string, unknown | null>,\n      meta: { seen: number; at: Date; ttlMs: number },\n    ): Promise<void>\n\n    /** The current map, pruned of rows at or past their `expiresAt`. */\n    read(ns: string): Promise<PresenceRow[]>\n\n    /**\n     * Adapter-managed patch delivery. Without it, live feeds re-read\n     * presence on their poll cadence. HTTP Redis uses adaptive polling\n     * here when its endpoint does not support subscriptions.\n     */\n    subscribe?(ns: string, onPatch: (patch: PresencePatch) => void): () => void\n  }\n\n  /**\n   * A live feed of one session's events, starting after `startAfter`\n   * (exclusive). Transport is the backend's choice — in-process pub/sub,\n   * polling, LISTEN/NOTIFY — callers never branch on which. The iterable\n   * ends when the consumer calls `return()` (e.g. a disconnecting SSE\n   * client) and must deliver events appended after subscription.\n   */\n  stream(\n    sessionId: string,\n    opts?: { startAfter?: number },\n  ): AsyncIterable<Event>\n}\n"],"mappings":";AAuKA,MAAa,eAAsB,EACjC,2BAAW,IAAI,KAAK,EACtB;AAEA,MAAa,mBAA6B,OAAO,WAAW"}
+{"version":3,"file":"store-N8PXxDAS.js","names":[],"sources":["../src/store.ts"],"sourcesContent":["/**\n * The A2Store interface — the storage contract every store backend\n * implements. See specs/a2-implementation.md §2–3.\n *\n * This is the whole storage contract: append, read, dispatch claims,\n * failure markers, snapshots, and the live stream. The scheduler\n * needs nothing extra — the armed queue message is its own state, and\n * the store is the only thing it consults.\n */\n\nimport type { PresencePatch } from './contract.ts'\n\n/** A stored event, as the public API exposes it. */\nexport type Event = {\n  id: string\n  type: string\n  payload: unknown\n  /** Position in the session's event log, from 1. */\n  index: number\n  sessionId: string\n  createdAt: Date\n}\n\n/** The handler dispatch whose append first persisted a child event. */\nexport type EventCause = {\n  index: number\n  attempt: number\n  /** Size of one named handler append, used to reject truncated retries. */\n  batchSize?: number\n}\n\n/**\n * What the store persists: immutable event history, including its causal edge,\n * plus derived dispatch and failure bookkeeping. The bookkeeping is disposable;\n * the event and its cause are not.\n */\nexport type StoredEvent = Event & {\n  /** Same-session handler dispatch that appended this event; null means root. */\n  cause: EventCause | null\n  /** Session-scoped serial execution key resolved when the event is appended. */\n  lane: string | null\n  /** Adapter clock time recorded by append settlement, completion, or manual skip; null while pending. */\n  processedAt: Date | null\n  /** Dispatch attempt that completed this event; null without dispatch or while pending. */\n  processedByAttempt: number | null\n  /** Exact ordered child ids atomically returned by the completing attempt. */\n  returnedEventIds: string[] | null\n  /** Adapter clock time recorded by the first durable dispatch claim. */\n  firstClaimedAt: Date | null\n  /** Adapter clock time recorded by the most recent durable dispatch claim. */\n  lastClaimedAt: Date | null\n  /** Durable dispatch claims, including claims abandoned by hard kills. */\n  attemptCount: number\n  /** Current dispatch holder; null when the event is not claimed. */\n  claimHolder: string | null\n  /** Adapter clock expiry for the current dispatch claim. */\n  claimExpiresAt: Date | null\n  /** Caught handler failures. This alone drives dead-lettering. */\n  failureCount: number\n  /** Adapter clock time recorded by the most recent caught handler failure. */\n  lastFailedAt: Date | null\n  /** Dispatch attempt that produced the most recent caught handler failure. */\n  lastFailedAttempt: number | null\n  /** The last handler failure, stringified. */\n  lastError: string | null\n  /** Adapter clock time recorded when dead-lettered; null otherwise. */\n  failedAt: Date | null\n}\n\n/**\n * One live presence value, as `A2Store.presence.read` returns it. The\n * row is the LWW unit — one participant's one field. `at` is the\n * sender's stamp, the LWW comparator. `expiresAt` is the storage's\n * own clock at the applied set plus its `ttlMs` — never derived from\n * the sender stamp; a row is live strictly before it.\n */\nexport type PresenceRow = {\n  participant: string\n  field: string\n  value: unknown\n  seen: number\n  at: Date\n  expiresAt: Date\n}\n\n/** One consistent cache-plus-tail read for a reducer fold. */\nexport type StoreStateRead = {\n  /** The current head checkpoint, even when an older historical snapshot is selected. */\n  headIndex: number | null\n  /** The greatest cached fold at or before the requested snapshot frontier. */\n  snapshot: { index: number; state: unknown } | null\n  /** Immutable events strictly after `snapshot.index`, or the full log on a miss. */\n  events: Event[]\n}\n\nexport type StoreSnapshotWrite = {\n  index: number\n  state: unknown\n  /** Unfinished trigger events that durably retain this exact checkpoint. */\n  pinEventIndexes?: readonly number[]\n}\n\nexport type StoreStateReadRequest = {\n  sessionId: string\n  throughIndex?: number\n  snapshotThroughIndex?: number\n}\n/** The result of atomically claiming every currently eligible event. */\nexport type StoreClaimAvailableResult =\n  | { outcome: 'claimed'; events: StoredEvent[] }\n  | { outcome: 'busy'; retryAt: Date }\n  | { outcome: 'settled' }\n\n/** A completion may lose to a newer claim or an earlier completion. */\nexport type CompleteAttemptResult =\n  { outcome: 'completed'; events: StoredEvent[] } | { outcome: 'superseded' }\n\n/** The result of one claim-renewal heartbeat, both lists in append order. */\nexport type RenewClaimsResult = {\n  /** Listed claims that remain owned by the holder. */\n  renewed: number[]\n  /** Listed claims whose event a newer attempt has durably taken. */\n  superseded: number[]\n}\n\n/** The result of atomically recording a caught handler failure. */\nexport type FailAttemptResult = {\n  outcome: 'failed' | 'dead_lettered' | 'superseded'\n  failureCount: number\n}\n\n/** Input to `A2Store.append` — already validated by the machine. */\nexport type AppendEvent = {\n  type: string\n  payload: unknown\n  /** Caller-supplied idempotency key; generated when absent. */\n  id?: string\n  /** Internal causal edge supplied atomically by handler `session.append`. */\n  cause?: EventCause\n  /** Session-scoped serial execution key resolved before persistence. */\n  lane?: string\n  /** Internal hint: settle this event in the append transaction; no handler is registered. */\n  settled?: true\n}\n\n/** A handler-returned event with the deterministic id retries require. */\nexport type ReturnedEvent = AppendEvent & { id: string }\n\n/** The rows written by an append and the session's pending state. */\nexport type StoreAppendResult = {\n  events: StoredEvent[]\n  /** Whether the session contains an event without a completion marker. */\n  hasPending: boolean\n}\n\n/**\n * An injectable clock. Adapters take one so tests can drive claim\n * expiry, failure timestamps, and (later) stuck-session detection\n * deterministically — against real storage, no mocking.\n */\nexport type Clock = {\n  now(): Date\n}\n\n/** An injectable id source for generated event ids. */\nexport type IdSource = () => string\n\nexport const SYSTEM_CLOCK: Clock = {\n  now: () => new Date(),\n}\n\nexport const RANDOM_IDS: IdSource = () => crypto.randomUUID()\n\nexport interface A2Store {\n  /**\n   * Accepts a batch; the batch is atomic — one transaction, consecutive\n   * `index`es, all-or-nothing. The idempotency key covers the whole\n   * operation, not each item: if *every* event's `id` already exists in\n   * this session, this is a retry of a committed batch whose ack was\n   * lost — return the existing rows as success. If only *some* ids\n   * exist, the caller mixed an already-sent batch with fresh events —\n   * always a caller bug — so throw `A2Error('PARTIAL_DUPLICATE_BATCH')`.\n   * Events carrying `settled: true` get `processedAt` in this same atomic\n   * operation, with no dispatch claim or `processedByAttempt`. The result's\n   * `hasPending` reflects the whole session in the same atomic operation,\n   * including older events and idempotent retries.\n   *\n   * An event carrying `cause` is a handler append, fenced by attempt\n   * currency: accept it only while `cause.attempt` is still the parent\n   * event's latest attempt and the parent is not dead-lettered; otherwise\n   * throw `A2Error('SUPERSEDED_ATTEMPT')` and write nothing. The check is\n   * part of this atomic operation and must serialize against a concurrent\n   * `claimAvailable` — an unlocked read of the parent admits write skew.\n   * The idempotent-replay path runs first, so a batch whose ids all exist\n   * replays regardless of the current attempt.\n   */\n  append(sessionId: string, events: AppendEvent[]): Promise<StoreAppendResult>\n\n  /** Events for one session, oldest first. Bounds form `(afterIndex, throughIndex]`. */\n  read(\n    sessionId: string,\n    opts?: { afterIndex?: number; throughIndex?: number },\n  ): Promise<StoredEvent[]>\n\n  /** Public history without dispatch metadata; core falls back to read when absent. */\n  readHistory?(\n    sessionId: string,\n    opts?: { afterIndex?: number; throughIndex?: number },\n  ): Promise<Event[]>\n\n  /**\n   * Atomically claims every eligible pending event. Unlaned events are all\n   * independently eligible. Within a lane, only the lowest-index unfinished\n   * event is eligible. A live claim produces `busy` only when it is the sole\n   * remaining obstacle to actionable work. Claimed events are returned in event-log\n   * order. Excluded rows remain lane barriers.\n   */\n  claimAvailable(options: {\n    sessionId: string\n    holder: string\n    ttlMs: number\n    expiresAtMs?: number\n    excludeIndexes?: readonly number[]\n  }): Promise<StoreClaimAvailableResult>\n\n  /**\n   * Renews the listed live claims still owned by `holder`. Each listed claim\n   * carries the attempt ordinal the holder owns. `renewed` lists the claims\n   * that remain owned after the operation; `superseded` lists the claims\n   * whose event's `attemptCount` has durably passed the listed attempt. An\n   * expired claim no successor has taken appears in neither list — its\n   * attempt may still complete (`completeAttempt` is the fence), so it is\n   * not reported as lost. Renewal never revives an expired claim.\n   */\n  renewClaims(options: {\n    sessionId: string\n    holder: string\n    claims: readonly { index: number; attempt: number }[]\n    ttlMs: number\n    expiresAtMs?: number\n  }): Promise<RenewClaimsResult>\n\n  /**\n   * Atomically completes one current attempt and appends its returned events.\n   * Retrying a committed completion with the same attempt and deterministic\n   * child ids returns the existing children. A stale attempt never appends.\n   */\n  completeAttempt(options: {\n    sessionId: string\n    index: number\n    attempt: number\n    events: ReturnedEvent[]\n  }): Promise<CompleteAttemptResult>\n\n  /**\n   * Atomically records a caught failure for one claimed attempt. A stale\n   * attempt cannot poison a processed event or a newer dispatch. Accepted\n   * failures record the operation's clock time.\n   */\n  failAttempt(options: {\n    sessionId: string\n    index: number\n    attempt: number\n    error: string\n    maxFailures: number\n  }): Promise<FailAttemptResult>\n\n  /**\n   * Reads a reducer snapshot and its event tail as one consistent adapter\n   * operation. On a cache miss, `snapshot` is null and `events` is the full\n   * log. The snapshot is untrusted; core may reject it and issue a full\n   * `read()` when its state schema no longer accepts the cached value.\n   */\n  readState(\n    sessionId: string,\n    reducerName: string,\n    options?: { throughIndex?: number; snapshotThroughIndex?: number },\n  ): Promise<StoreStateRead>\n\n  /**\n   * Optional batched `readState` — one consistent snapshot-plus-tail read\n   * per session id, aligned positionally with the input (duplicates\n   * allowed). Each element has its own frontier; the batch makes no\n   * cross-session consistency claim. Core falls back to parallel\n   * `readState` calls when absent.\n   */\n  readStates?(\n    requests: readonly StoreStateReadRequest[],\n    reducerName: string,\n  ): Promise<StoreStateRead[]>\n\n  /**\n   * Atomically writes disposable reducer checkpoints. The greatest index\n   * advances the head cache. Older checkpoints survive only when at least one\n   * listed trigger event is still unfinished; completion and dead-lettering\n   * release that event's pins and collect unreferenced historical checkpoints.\n   */\n  putSnapshots(\n    sessionId: string,\n    reducerName: string,\n    snapshots: readonly StoreSnapshotWrite[],\n  ): Promise<void>\n\n  /**\n   * Optional ephemeral-plane capability (specs/a2-implementation.md\n   * §15.1) — optional like snapshots are. Values arrive already\n   * validated by core; adapters store them opaquely. Presence never\n   * touches the event log: no index, no history row, no recovery arm.\n   */\n  presence?: {\n    /**\n     * Field-wise last-writer-wins merge of one participant's values:\n     * a field whose existing row has a strictly newer `at` (the\n     * sender's stamp) is left untouched; `null` deletes the row. Every\n     * applied write refreshes that field's expiry to the storage's own\n     * clock plus `ttlMs` — the sender stamp orders writes but never\n     * anchors their lifetime.\n     */\n    set(\n      ns: string,\n      participant: string,\n      values: Record<string, unknown | null>,\n      meta: { seen: number; at: Date; ttlMs: number },\n    ): Promise<void>\n\n    /** The current map, pruned of rows at or past their `expiresAt`. */\n    read(ns: string): Promise<PresenceRow[]>\n\n    /**\n     * Adapter-managed patch delivery. Without it, live feeds re-read\n     * presence on their poll cadence. HTTP Redis uses adaptive polling\n     * here when its endpoint does not support subscriptions.\n     */\n    subscribe?(ns: string, onPatch: (patch: PresencePatch) => void): () => void\n  }\n\n  /**\n   * A live feed of one session's events, starting after `startAfter`\n   * (exclusive). Transport is the backend's choice — in-process pub/sub,\n   * polling, LISTEN/NOTIFY — callers never branch on which. The iterable\n   * ends when the consumer calls `return()` (e.g. a disconnecting SSE\n   * client) and must deliver events appended after subscription.\n   */\n  stream(\n    sessionId: string,\n    opts?: { startAfter?: number },\n  ): AsyncIterable<Event>\n}\n"],"mappings":";AAuKA,MAAa,eAAsB,EACjC,2BAAW,IAAI,KAAK,EACtB;AAEA,MAAa,mBAA6B,OAAO,WAAW"}

package/dist/store-memory.d.ts

@@ -1,4 +1,4 @@
-import { r as Clock, s as IdSource, t as A2Store } from "./store-DtDOWLSn.js";
+import { r as Clock, s as IdSource, t as A2Store } from "./store-D_yhNdPz.js";
 //#region src/store-memory.d.ts
 type MemoryStoreOptions = {
   /** Injectable clock — every stored timestamp comes from here. */

package/dist/store-postgres.d.ts

@@ -1,4 +1,4 @@
-import { r as Clock, s as IdSource, t as A2Store } from "./store-DtDOWLSn.js";
+import { r as Clock, s as IdSource, t as A2Store } from "./store-D_yhNdPz.js";
 //#region src/store-postgres.d.ts
 /** The result shape this backend reads: just rows. */
 type PostgresQueryResult = {

package/dist/store-postgres.js

@@ -986,6 +986,25 @@ function postgres(options = {}) {
 				return rows.map(toStored);
 			});
 		},
+		async readHistory(sessionId, opts) {
+			return wrap(async () => {
+				if (opts?.throughIndex !== void 0 && opts.throughIndex <= (opts.afterIndex ?? 0)) return [];
+				const c = await client();
+				const conditions = ["session_id = $1"];
+				const params = [sessionId];
+				if (opts?.afterIndex !== void 0) {
+					params.push(opts.afterIndex);
+					conditions.push(`idx > $${params.length}`);
+				}
+				if (opts?.throughIndex !== void 0) {
+					params.push(opts.throughIndex);
+					conditions.push(`idx <= $${params.length}`);
+				}
+				const { rows } = await c.query(`select session_id, idx, event_id, event_type, payload, created_at
+             from a2_events where ${conditions.join(" and ")} order by idx`, params);
+				return rows.map(toEvent);
+			});
+		},
 		async claimAvailable({ sessionId, holder, ttlMs, expiresAtMs, excludeIndexes = [] }) {
 			return wrap(() => withTx(async (query) => {
 				const now = clock.now().getTime();