experimental-a2 0.20.0 → 0.22.0

package/dist/store-D0MhBvg6.d.ts

@@ -0,0 +1,532 @@
+import { p as PresencePatch } from "./reducer-CYPHsSmd.js";
+//#region src/store.d.ts
+/** A stored event, as the public API exposes it. */
+type Event = {
+  id: string;
+  type: string;
+  payload: unknown;
+  /** Position in the session's event log, from 1. */
+  index: number;
+  sessionId: string;
+  createdAt: Date;
+};
+/** The consumer attempt whose append first persisted a child event. */
+type EventCause = {
+  consumer: string;
+  /** The cursor's lane; null for a concurrent consumer's cursor of one event. */
+  lane: string | null;
+  index: number;
+  attempt: number;
+  /** Size of one named consumer append, used to reject truncated retries. */
+  batchSize?: number;
+};
+/** What the store persists: immutable event history and its causal edge. */
+type StoredEvent = Event & {
+  /** Same-session consumer attempt that appended this event; null means root. */
+  cause: EventCause | null;
+};
+/**
+ * Where a consumer's cursor stands on its head event. A cursor is one record
+ * per (session, consumer, lane): a log cursor for a consumer with one string
+ * lane, a lane cursor per lane for a lane function, and a cursor per event
+ * (lane null) for a concurrent consumer. Its attempt and failure fields
+ * describe the current head and reset when the cursor moves past it.
+ */
+type HeadDispatch = {
+  consumer: string;
+  lane: string | null;
+  /** Adapter clock time recorded by the first durable claim of this head. */
+  firstClaimedAt: Date | null;
+  /** Adapter clock time recorded by the most recent durable claim of this head. */
+  lastClaimedAt: Date | null;
+  /** Durable claims of this head, including claims abandoned by hard kills. */
+  attemptCount: number;
+  /** Current holder; null when the head is not claimed. */
+  claimHolder: string | null;
+  /**
+   * Adapter clock expiry for the current claim, or, with no holder, the end
+   * of a failed attempt's retry hold.
+   */
+  claimExpiresAt: Date | null;
+  /**
+   * Failed attempts on this head: caught 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 failure. */
+  lastFailedAt: Date | null;
+  /** Attempt that produced the most recent caught failure. */
+  lastFailedAttempt: number | null;
+  /** The last failure, stringified. */
+  lastError: string | null;
+  /** Adapter clock time recorded when dead-lettered; null otherwise. */
+  failedAt: Date | null;
+};
+/** Where one cursor stands: its position, its head, and the head's dispatch state. */
+type StoredCursor = HeadDispatch & {
+  /** The last index this cursor finished; a log cursor counts from the latest clear marker. */
+  position: number;
+  /** The event it runs next; null when it has nothing to run. */
+  head: number | null;
+};
+/** A cursor's head event together with its dispatch state. */
+type HeadEvent = StoredEvent & HeadDispatch & {
+  /** Latest clear marker, on claimed heads of a cleared session. */
+  clearIndex?: number;
+};
+/** Names one cursor head: the consumer, its lane, and the head's index. */
+type HeadRef = {
+  consumer: string;
+  lane: string | null;
+  index: number;
+};
+/**
+ * A consumer the caller serves. Work for consumers it does not name is
+ * neither pending nor claimed, so a removed consumer's cursors wait for its
+ * name to return.
+ */
+type StoreConsumer = {
+  name: string;
+  /**
+   * Set for a consumer with one string lane. Its cursor keeps one position
+   * over the log and runs the next event whose type is in `types` (null:
+   * every type). A missing cursor is created by the first append that
+   * carries one of those types: at the start of the log with `backfill`,
+   * otherwise just before that append.
+   */
+  log?: {
+    lane: string;
+    types: readonly string[] | null;
+    backfill: boolean;
+  };
+};
+/**
+ * One live presence value, as `A2Store.presence.read` returns it. The
+ * row is the LWW unit — one participant's one field. `at` is the
+ * sender's stamp, the LWW comparator. `expiresAt` is the storage's
+ * own clock at the applied set plus its `ttlMs` — never derived from
+ * the sender stamp; a row is live strictly before it.
+ */
+type PresenceRow = {
+  participant: string;
+  field: string;
+  value: unknown;
+  seen: number;
+  at: Date;
+  expiresAt: Date;
+};
+/** One consistent cache-plus-tail read for a reducer fold. */
+type StoreStateRead = {
+  /** The current head checkpoint, even when an older historical snapshot is selected. */
+  headIndex: number | null;
+  /** The greatest cached fold at or before the requested snapshot frontier. */
+  snapshot: {
+    index: number;
+    state: unknown;
+  } | null;
+  /** Immutable events strictly after `snapshot.index`, or the full log on a miss. */
+  events: Event[];
+  /** Latest clear marker; omitted when the session was never cleared. */
+  clearIndex?: number;
+};
+type StoreSnapshotWrite = {
+  index: number;
+  state: unknown;
+  /** Unfinished cursor heads that durably retain this exact checkpoint. */
+  pins?: readonly HeadRef[];
+};
+type StoreStateReadRequest = {
+  sessionId: string;
+  throughIndex?: number;
+  snapshotThroughIndex?: number;
+};
+/** The result of atomically claiming every currently eligible head. */
+type StoreClaimAvailableResult = {
+  outcome: "claimed";
+  events: HeadEvent[];
+  /** The session's head when the claim was made: how far behind each event is. */
+  head?: number;
+} | {
+  outcome: "busy";
+  retryAt: Date;
+} | {
+  outcome: "settled";
+};
+/** A completion may lose to a newer claim or an earlier completion. */
+type CompleteAttemptResult = {
+  outcome: "completed";
+  events: StoredEvent[];
+} | {
+  outcome: "superseded";
+};
+/** The result of one claim-renewal heartbeat, both lists in head order. */
+type RenewClaimsResult = {
+  /** Listed claims that remain owned by the holder. */
+  renewed: HeadRef[];
+  /** Listed claims a newer attempt has durably taken, or whose cursor moved on. */
+  superseded: HeadRef[];
+};
+/** The result of atomically recording a caught failure. */
+type FailAttemptResult = {
+  outcome: "failed" | "dead_lettered" | "superseded";
+  failureCount: number;
+};
+/** A consumer an appended event starts work for, with its resolved lane. */
+type EventTarget = {
+  consumer: string;
+  /** The lane a lane function resolved; null runs the event concurrently. */
+  lane: string | null;
+};
+/** Input to `A2Store.append` — already validated by the machine. */
+type AppendEvent = {
+  type: string;
+  payload: unknown;
+  /** Caller-supplied idempotency key; generated when absent. */
+  id?: string;
+  /** Internal causal edge supplied atomically by consumer `session.append`. */
+  cause?: EventCause;
+  /**
+   * Lane-function and concurrent consumers this event starts work for,
+   * resolved before persistence. Log-cursor consumers are matched by type
+   * from `StoreConsumer.log` instead.
+   */
+  targets?: readonly EventTarget[];
+};
+/** A consumer-returned event with the deterministic id retries require. */
+type ReturnedEvent = AppendEvent & {
+  id: string;
+};
+/** The rows written by an append and the session's pending state. */
+type StoreAppendResult = {
+  events: StoredEvent[];
+  /**
+   * Whether a served consumer has a live head in this session: one that is
+   * not dead-lettered. An append whose own batch starts work for a served
+   * consumer may report true without checking that work is runnable.
+   */
+  hasPending: boolean;
+};
+type StoreClearOptions = {
+  sessionId: string;
+  ifLastIndex?: number;
+  /** The clearing consumer's attempt, fenced like a consumer append. */
+  cause?: EventCause;
+};
+type StoreClearResult = {
+  cleared: boolean;
+  /** The head after the operation. */
+  index: number;
+  /** The latest clear marker after the operation, or 0. */
+  clearIndex: number;
+};
+type StoreReclaimResult = {
+  deleted: number;
+  done: boolean;
+};
+type StoreRedriveOptions = {
+  sessionId: string;
+  consumer: string;
+  index: number;
+  /** `retry` clears the dead letter; `skip` moves the cursor past it. */
+  action: "retry" | "skip";
+  consumers?: readonly StoreConsumer[];
+};
+type StoreRedriveResult = {
+  /** Whether the head was dead-lettered and this operation resolved it. */
+  redriven: boolean;
+  /** Whether a served consumer has a live head in this session: one that is not dead-lettered. */
+  hasPending: boolean;
+};
+/**
+ * An injectable clock. Adapters take one so tests can drive claim
+ * expiry, failure timestamps, and (later) stuck-session detection
+ * deterministically — against real storage, no mocking.
+ */
+type Clock = {
+  now(): Date;
+};
+/** An injectable id source for generated event ids. */
+type IdSource = () => string;
+/**
+ * Cursor rules every operation shares:
+ *
+ * - `consumers` names the consumers the caller serves. Omitted, every cursor
+ *   counts and no log cursor is created or advanced by type.
+ * - A cursor's head is the next event it runs: the lowest unfinished event of
+ *   its lane, the event itself for a concurrent cursor, or for a log cursor
+ *   the next event after its position whose type it takes. The clear marker
+ *   is never a head.
+ * - A head is eligible when no live claim or retry hold owns it, it is not
+ *   dead-lettered, and it lies above the latest clear marker.
+ * - Moving a cursor past its head resets the head's attempt and failure
+ *   fields and releases snapshot pins on it.
+ */
+interface A2Store {
+  /**
+   * Accepts a batch; the batch is atomic — one transaction, consecutive
+   * `index`es, all-or-nothing. The idempotency key covers the whole
+   * operation, not each item: if *every* event's `id` already exists in
+   * this session, this is a retry of a committed batch whose ack was
+   * lost — return the existing rows as success. If only *some* ids
+   * exist, the caller mixed an already-sent batch with fresh events —
+   * always a caller bug — so throw `A2Error('PARTIAL_DUPLICATE_BATCH')`.
+   * Ids are unique per session: the same id in another session names a
+   * different event and plays no part in these checks.
+   *
+   * In the same atomic operation, each event's `targets` start cursor work:
+   * a lane target queues the event in that consumer's lane, a null lane
+   * creates a cursor for that event alone. Each log consumer in `consumers`
+   * whose types the batch carries gets its cursor created or, when idle, a
+   * head: the next event after its position that it takes, which may
+   * precede the batch when an appender that doesn't serve it wrote in
+   * between. `hasPending` reflects the whole session for the served consumers,
+   * including older work and idempotent retries.
+   *
+   * An event carrying `cause` is a consumer append, fenced by attempt
+   * currency: accept it only while the cause's cursor still has
+   * `cause.index` as its head, `cause.attempt` is that head's latest
+   * attempt, and the head is not dead-lettered; otherwise throw
+   * `A2Error('SUPERSEDED_ATTEMPT')` and write nothing. The check is part of
+   * this atomic operation and must serialize against a concurrent
+   * `claimAvailable` — an unlocked read of the cursor admits write skew. The
+   * idempotent-replay path runs first, so a batch whose ids all exist
+   * replays regardless of the current attempt.
+   *
+   * Clearing stores (a2-implementation.md §17.2) fence one level earlier:
+   * a `cause` at or below the latest clear marker throws
+   * `SUPERSEDED_ATTEMPT`, an `originIndex` there throws `SESSION_CLEARED`,
+   * and ids whose rows lie below the marker are free to reuse.
+   */
+  append(sessionId: string, events: AppendEvent[], options?: {
+    originIndex?: number;
+    consumers?: readonly StoreConsumer[];
+  }): Promise<StoreAppendResult>;
+  /**
+   * Optional with `reclaim`. Serialized with `append`: checks
+   * `ifLastIndex` against the head and the latest marker, then appends a
+   * clear marker at the next index without touching existing rows.
+   * Afterwards every event at or below the marker is superseded: no head
+   * lies there, and every log cursor's position counts from the marker.
+   */
+  clear?(options: StoreClearOptions): Promise<StoreClearResult>;
+  /**
+   * Deletes one bounded batch of rows below the latest clear marker, with
+   * their cursor records, id records, and cached folds. `done` once nothing
+   * remains below it. Never waits on a lock that other operations hold.
+   */
+  reclaim?(sessionId: string): Promise<StoreReclaimResult>;
+  /**
+   * Optional with `redrive`. The session's dead-lettered heads above the
+   * latest clear marker, in event order, then by consumer name.
+   */
+  deadLetters?(sessionId: string): Promise<HeadEvent[]>;
+  /**
+   * Optional with `deadLetters`. Atomically resolves the consumer's
+   * dead-lettered head at `index` above the latest clear marker; anything
+   * else is untouched and reports `redriven: false`. `retry` clears
+   * `failedAt` and `failureCount`, so the head is claimable again with a
+   * fresh failure budget, keeping its claim history and last failure. `skip`
+   * moves the cursor past the head with no completion. Both serialize with
+   * `claimAvailable` and the consumer-append fence. `hasPending` is read in
+   * the same step.
+   */
+  redrive?(options: StoreRedriveOptions): Promise<StoreRedriveResult>;
+  /**
+   * Brings one log consumer's cursor up to date without an append, for
+   * `session.consume()`. A missing cursor is created: with `backfill`, at
+   * the latest clear marker, taking the first event of its types after it;
+   * otherwise at the head, with nothing to run. When the session has nothing
+   * after its latest clear (or was never written), a missing cursor stays
+   * missing: nothing is written, and the cursor comes back idle at the
+   * marker, so a consume of an unknown session leaves no trace. That is
+   * exact with `backfill`; without it, the consumer starts at the first
+   * consume or serving append that finds events. An
+   * idle cursor takes the next event of its types after its position, so it
+   * finds events appended by deployments that don't serve it. A cursor with
+   * a head, claimed or not, is left as it is. Records the consumer's types,
+   * as an append would, and returns the cursor and the session's head.
+   */
+  wakeLog(options: {
+    sessionId: string;
+    consumer: StoreConsumer & {
+      log: NonNullable<StoreConsumer["log"]>;
+    };
+  }): Promise<{
+    cursor: StoredCursor;
+    head: number;
+  }>;
+  /**
+   * The session's cursors: every log and lane cursor, and every concurrent
+   * cursor that still has a head, by consumer, then lane (concurrent cursors
+   * last, by head). Lane and concurrent cursors whose work lies at or below
+   * the latest clear marker are not listed.
+   */
+  cursors(sessionId: string): Promise<StoredCursor[]>;
+  /** Events for one session, oldest first. Bounds form `(afterIndex, throughIndex]`. */
+  read(sessionId: string, opts?: {
+    afterIndex?: number;
+    throughIndex?: number;
+  }): Promise<StoredEvent[]>;
+  /** Public history without causal edges; core falls back to read when absent. */
+  readHistory?(sessionId: string, opts?: {
+    afterIndex?: number;
+    throughIndex?: number;
+  }): Promise<Event[]>;
+  /**
+   * Atomically claims every eligible head of the served consumers. A live
+   * claim or retry hold produces `busy` only when it is the sole remaining
+   * obstacle to actionable work. Claimed heads are returned in event order,
+   * then by consumer name. Excluded heads stay unclaimed and keep blocking
+   * their lane.
+   */
+  claimAvailable(options: {
+    sessionId: string;
+    holder: string;
+    ttlMs: number;
+    expiresAtMs?: number;
+    exclude?: readonly HeadRef[];
+    consumers?: readonly StoreConsumer[];
+    /**
+     * Taking over a lapsed claim (one whose holder is still recorded, never
+     * completed or failed) adds one to `failureCount`. When that reaches
+     * `maxFailures`, the head 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;
+    /**
+     * Claims only heads at or below this index: a head past it is neither
+     * claimed nor reported `busy`, and stays claimable without it.
+     */
+    through?: number;
+  }): Promise<StoreClaimAvailableResult>;
+  /**
+   * Renews the listed live claims still owned by `holder`. Each listed claim
+   * carries the attempt the holder owns. `renewed` lists the claims that
+   * remain owned after the operation; `superseded` lists the claims whose
+   * head a newer attempt has durably taken, or whose cursor has moved past
+   * it. An expired claim no successor has taken appears in neither list — its
+   * attempt may still complete (`completeAttempt` is the fence), so it is
+   * not reported as lost. Renewal never revives an expired claim.
+   */
+  renewClaims(options: {
+    sessionId: string;
+    holder: string;
+    claims: readonly (HeadRef & {
+      attempt: number;
+    })[];
+    ttlMs: number;
+    expiresAtMs?: number;
+  }): Promise<RenewClaimsResult>;
+  /**
+   * Atomically completes one current attempt: appends its returned events
+   * (with their own targets, waking the served log consumers) and moves the
+   * cursor past its head. Retrying a committed completion with the same
+   * attempt and deterministic child ids returns the existing children. A
+   * stale attempt never appends.
+   */
+  completeAttempt(options: {
+    sessionId: string;
+    consumer: string;
+    lane: string | null;
+    index: number;
+    attempt: number;
+    events: ReturnedEvent[];
+    consumers?: readonly StoreConsumer[];
+  }): Promise<CompleteAttemptResult>;
+  /**
+   * Atomically records a caught failure for one claimed attempt. A stale
+   * attempt cannot poison a finished head or a newer attempt. Accepted
+   * failures record the operation's clock time. A failure that does not
+   * dead-letter releases the claim and, with `retryAfterMs`, keeps the head
+   * unclaimable for that long: its claim expiry is set with no holder, so
+   * `claimAvailable` reports it `busy` until then.
+   */
+  failAttempt(options: {
+    sessionId: string;
+    consumer: string;
+    lane: string | null;
+    index: number;
+    attempt: number;
+    error: string;
+    maxFailures: number;
+    retryAfterMs?: number;
+  }): Promise<FailAttemptResult>;
+  /**
+   * Reads a reducer snapshot and its event tail as one consistent adapter
+   * operation. On a cache miss, `snapshot` is null and `events` is the full
+   * log. The snapshot is untrusted; core may reject it and issue a full
+   * `read()` when its state schema no longer accepts the cached value.
+   * Operational failures propagate without falling back to a full-log read.
+   */
+  readState(sessionId: string, reducerName: string, options?: {
+    throughIndex?: number;
+    snapshotThroughIndex?: number;
+  }): Promise<StoreStateRead>;
+  /**
+   * Optional batched `readState` — one consistent snapshot-plus-tail read
+   * per session id, aligned positionally with the input (duplicates
+   * allowed). Each element has its own frontier; the batch makes no
+   * cross-session consistency claim. Core falls back to parallel
+   * `readState` calls when absent.
+   */
+  readStates?(requests: readonly StoreStateReadRequest[], reducerName: string): Promise<StoreStateRead[]>;
+  /**
+   * Atomically writes disposable reducer checkpoints. The greatest index
+   * advances the head cache. Older checkpoints survive only while at least
+   * one listed cursor head is still unfinished; moving that cursor past it
+   * or dead-lettering it releases the pin and collects unreferenced
+   * historical checkpoints.
+   */
+  putSnapshots(sessionId: string, reducerName: string, snapshots: readonly StoreSnapshotWrite[]): Promise<void>;
+  /**
+   * Optional ephemeral-plane capability (specs/a2-implementation.md
+   * §15.1) — optional like snapshots are. Values arrive already
+   * validated by core; adapters store them opaquely. Presence never
+   * touches the event log: no index, no history row, no recovery arm.
+   */
+  presence?: {
+    /**
+     * Field-wise last-writer-wins merge of one participant's values:
+     * a field whose unexpired entry has a strictly newer `at` (the
+     * sender's stamp) is left untouched. `null` deletes the value but
+     * keeps a tombstone with its `at`, which takes part in the merge
+     * like a value until it expires, so a set older than the delete
+     * still loses when it arrives later. Every applied write, value or
+     * tombstone, refreshes that field's expiry to the storage's own
+     * clock plus `ttlMs` — the sender stamp orders writes but never
+     * anchors their lifetime. `subscribe` delivers applied writes only,
+     * a delete as `null`.
+     */
+    set(ns: string, participant: string, values: Record<string, unknown | null>, meta: {
+      seen: number;
+      at: Date;
+      ttlMs: number;
+    }): Promise<void>;
+    /**
+     * The current map, pruned of rows at or past their `expiresAt`.
+     * Tombstones never appear.
+     */
+    read(ns: string): Promise<PresenceRow[]>;
+    /**
+     * Adapter-managed patch delivery. Without it, live feeds re-read
+     * presence on their poll cadence. HTTP Redis uses adaptive polling
+     * here when its endpoint does not support subscriptions.
+     */
+    subscribe?(ns: string, onPatch: (patch: PresencePatch) => void): () => void;
+  };
+  /**
+   * A live feed of one session's events, starting after `startAfter`
+   * (exclusive). Transport is the backend's choice — in-process pub/sub,
+   * polling, LISTEN/NOTIFY — callers never branch on which. The iterable
+   * ends when the consumer calls `return()` (e.g. a disconnecting SSE
+   * client) and must deliver events appended after subscription.
+   */
+  stream(sessionId: string, opts?: {
+    startAfter?: number;
+  }): AsyncIterable<Event>;
+}
+//#endregion
+export { EventCause as a, PresenceRow as c, StoreStateRead as d, StoredEvent as f, Event as i, StoreAppendResult as l, AppendEvent as n, FailAttemptResult as o, Clock as r, IdSource as s, A2Store as t, StoreClaimAvailableResult as u };
+//# sourceMappingURL=store-D0MhBvg6.d.ts.map

package/dist/store-D0MhBvg6.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-D0MhBvg6.d.ts","names":[],"sources":["../src/store.ts"],"mappings":";;;KAaY;EACV;EACA;EACA;;EAEA;EACA;EACA,WAAW;;;KAID;EACV;;EAEA;EACA;EACA;;EAEA;;;KAIU,cAAc;;EAExB,OAAO;;;;;;;;;KAUG;EACV;EACA;;EAEA,gBAAgB;;EAEhB,eAAe;;EAEf;;EAEA;;;;;EAKA,gBAAgB;;;;;EAKhB;;EAEA,cAAc;;EAEd;;EAEA;;EAEA,UAAU;;;KAIA,eAAe;;EAEzB;;EAEA;;;KAIU,YAAY,cACtB;;EAEE;;;KAIQ;EACV;EACA;EACA;;;;;;;KAQU;EACV;;;;;;;;EAQA;IACE;IACA;IACA;;;;;;;;;;KAWQ;EACV;EACA;EACA;EACA;EACA,IAAI;EACJ,WAAW;;;KAID;;EAEV;;EAEA;IAAY;IAAe;;;EAE3B,QAAQ;;EAER;;KAGU;EACV;EACA;;EAEA,gBAAgB;;KAGN;EACV;EACA;EACA;;;KAIU;EAEN;EACA,QAAQ;;EAER;;EAEA;EAAiB,SAAS;;EAC1B;;;KAGM;EACR;EAAsB,QAAQ;;EAAoB;;;KAG1C;;EAEV,SAAS;;EAET,YAAY;;;KAIF;EACV;EACA;;;KAIU;EACV;;EAEA;;;KAIU;EACV;EACA;;EAEA;;EAEA,QAAQ;;;;;;EAMR,mBAAmB;;;KAIT,gBAAgB;EAAgB;;;KAGhC;EACV,QAAQ;;;;;;EAMR;;KAGU;EACV;EACA;;EAEA,QAAQ;;KAGE;EACV;;EAEA;;EAEA;;KAGU;EAAuB;EAAiB;;KAExC;EACV;EACA;EACA;;EAEA;EACA,qBAAqB;;KAGX;;EAEV;;EAEA;;;;;;;KAQU;EACV,OAAO;;;KAIG;;;;;;;;;;;;;;;UAsBK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoCf,OACE,mBACA,QAAQ,eACR;IACE;IACA,qBAAqB;MAEtB,QAAQ;;;;;;;;EASX,OAAO,SAAS,oBAAoB,QAAQ;;;;;;EAO5C,SAAS,oBAAoB,QAAQ;;;;;EAMrC,aAAa,oBAAoB,QAAQ;;;;;;;;;;;EAYzC,SAAS,SAAS,sBAAsB,QAAQ;;;;;;;;;;;;;;;;EAiBhD,QAAQ;IACN;IACA,UAAU;MAAkB,KAAK,YAAY;;MAC3C;IAAU,QAAQ;IAAc;;;;;;;;EAQpC,QAAQ,oBAAoB,QAAQ;;EAGpC,KACE,mBACA;IAAS;IAAqB;MAC7B,QAAQ;;EAGX,aACE,mBACA;IAAS;IAAqB;MAC7B,QAAQ;;;;;;;;EASX,eAAe;IACb;IACA;IACA;IACA;IACA,mBAAmB;IACnB,qBAAqB;;;;;;;;;IASrB;;;;;IAKA;MACE,QAAQ;;;;;;;;;;EAWZ,YAAY;IACV;IACA;IACA,kBAAkB;MAAY;;IAC9B;IACA;MACE,QAAQ;;;;;;;;EASZ,gBAAgB;IACd;IACA;IACA;IACA;IACA;IACA,QAAQ;IACR,qBAAqB;MACnB,QAAQ;;;;;;;;;EAUZ,YAAY;IACV;IACA;IACA;IACA;IACA;IACA;IACA;IACA;MACE,QAAQ;;;;;;;;EASZ,UACE,mBACA,qBACA;IAAY;IAAuB;MAClC,QAAQ;;;;;;;;EASX,YACE,mBAAmB,yBACnB,sBACC,QAAQ;;;;;;;;EASX,aACE,mBACA,qBACA,oBAAoB,uBACnB;;;;;;;EAQH;;;;;;;;;;;;;IAaE,IACE,YACA,qBACA,QAAQ,gCACR;MAAQ;MAAc,IAAI;MAAM;QAC/B;;;;;IAMH,KAAK,aAAa,QAAQ;;;;;;IAO1B,WAAW,YAAY,UAAU,OAAO;;;;;;;;;EAU1C,OACE,mBACA;IAAS;MACR,cAAc"}

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  /**\n   * Adapter clock expiry for the current dispatch claim, or, with no holder,\n   * the end of a failed attempt's retry hold.\n   */\n  claimExpiresAt: Date | null\n  /**\n   * Failed attempts: caught handler failures, and lapsed claims a later claim\n   * took over. This alone drives dead-lettering.\n   */\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  /** Latest clear marker, on claimed events of a cleared session. */\n  clearIndex?: number\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  /** Latest clear marker; omitted when the session was never cleared. */\n  clearIndex?: number\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\nexport type StoreClearOptions = {\n  sessionId: string\n  ifLastIndex?: number\n  /** The clearing handler's dispatch, fenced like a handler append. */\n  cause?: EventCause\n}\n\nexport type StoreClearResult = {\n  cleared: boolean\n  /** The head after the operation. */\n  index: number\n  /** The latest clear marker after the operation, or 0. */\n  clearIndex: number\n}\n\nexport type StoreReclaimResult = { deleted: number; done: boolean }\n\nexport type StoreRedriveOptions = {\n  sessionId: string\n  index: number\n  /** `retry` clears the dead letter; `skip` settles it without a handler. */\n  action: 'retry' | 'skip'\n}\n\nexport type StoreRedriveResult = {\n  /** Whether the event was dead-lettered and this operation resolved it. */\n  redriven: boolean\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   * Clearing stores (a2-implementation.md §17.2) fence one level earlier:\n   * a `cause` at or below the latest clear marker throws\n   * `SUPERSEDED_ATTEMPT`, an `originIndex` there throws `SESSION_CLEARED`,\n   * and ids whose rows lie below the marker are free to reuse.\n   */\n  append(\n    sessionId: string,\n    events: AppendEvent[],\n    options?: { originIndex?: number },\n  ): Promise<StoreAppendResult>\n\n  /**\n   * Optional with `reclaim`. Serialized with `append`: checks\n   * `ifLastIndex` against the head and the latest marker, then appends a\n   * settled clear marker at the next index without touching existing\n   * rows. Afterwards every event at or below the marker is superseded.\n   */\n  clear?(options: StoreClearOptions): Promise<StoreClearResult>\n\n  /**\n   * Deletes one bounded batch of rows below the latest clear marker, with\n   * their bookkeeping, id records, and cached folds. `done` once nothing\n   * remains below it. Never waits on a lock that other operations hold.\n   */\n  reclaim?(sessionId: string): Promise<StoreReclaimResult>\n\n  /**\n   * Optional with `redrive`. The session's dead-lettered events above the\n   * latest clear marker, oldest first.\n   */\n  deadLetters?(sessionId: string): Promise<StoredEvent[]>\n\n  /**\n   * Optional with `deadLetters`. Atomically resolves one dead-lettered event\n   * above the latest clear marker; any other event is untouched and reports\n   * `redriven: false`. `retry` clears `failedAt` and `failureCount`, so the\n   * event is claimable again with a fresh failure budget, keeping its claim\n   * history and last failure. `skip` records `processedAt` with no\n   * `processedByAttempt` or `returnedEventIds` and exposes the next event in\n   * its lane. Both serialize with `claimAvailable` and the handler-append\n   * parent fence; `skip` also serializes with lane promotion in `append` and\n   * `completeAttempt`. `hasPending` is read in the same step.\n   */\n  redrive?(options: StoreRedriveOptions): Promise<StoreRedriveResult>\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    /**\n     * Taking over a lapsed claim (one whose holder is still recorded, never\n     * completed or failed) adds one to `failureCount`. When that reaches\n     * `maxFailures`, the event dead-letters instead of being claimed: it\n     * comes back in `events` with `failedAt` set and no claim. Its\n     * `attemptCount` still advances, fencing the lapsed attempt, and its\n     * `lastFailedAttempt` is unchanged.\n     */\n    maxFailures?: 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. A failure that does not\n   * dead-letter releases the claim and, with `retryAfterMs`, keeps the event\n   * unclaimable for that long: its claim expiry is set with no holder, so\n   * `claimAvailable` reports it `busy` until then.\n   */\n  failAttempt(options: {\n    sessionId: string\n    index: number\n    attempt: number\n    error: string\n    maxFailures: number\n    retryAfterMs?: 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   * Operational failures propagate without falling back to a full-log read.\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":";AAgNA,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, consumer cursors,\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 consumer attempt whose append first persisted a child event. */\nexport type EventCause = {\n  consumer: string\n  /** The cursor's lane; null for a concurrent consumer's cursor of one event. */\n  lane: string | null\n  index: number\n  attempt: number\n  /** Size of one named consumer append, used to reject truncated retries. */\n  batchSize?: number\n}\n\n/** What the store persists: immutable event history and its causal edge. */\nexport type StoredEvent = Event & {\n  /** Same-session consumer attempt that appended this event; null means root. */\n  cause: EventCause | null\n}\n\n/**\n * Where a consumer's cursor stands on its head event. A cursor is one record\n * per (session, consumer, lane): a log cursor for a consumer with one string\n * lane, a lane cursor per lane for a lane function, and a cursor per event\n * (lane null) for a concurrent consumer. Its attempt and failure fields\n * describe the current head and reset when the cursor moves past it.\n */\nexport type HeadDispatch = {\n  consumer: string\n  lane: string | null\n  /** Adapter clock time recorded by the first durable claim of this head. */\n  firstClaimedAt: Date | null\n  /** Adapter clock time recorded by the most recent durable claim of this head. */\n  lastClaimedAt: Date | null\n  /** Durable claims of this head, including claims abandoned by hard kills. */\n  attemptCount: number\n  /** Current holder; null when the head is not claimed. */\n  claimHolder: string | null\n  /**\n   * Adapter clock expiry for the current claim, or, with no holder, the end\n   * of a failed attempt's retry hold.\n   */\n  claimExpiresAt: Date | null\n  /**\n   * Failed attempts on this head: caught failures, and lapsed claims a later\n   * claim took over. This alone drives dead-lettering.\n   */\n  failureCount: number\n  /** Adapter clock time recorded by the most recent caught failure. */\n  lastFailedAt: Date | null\n  /** Attempt that produced the most recent caught failure. */\n  lastFailedAttempt: number | null\n  /** The last failure, stringified. */\n  lastError: string | null\n  /** Adapter clock time recorded when dead-lettered; null otherwise. */\n  failedAt: Date | null\n}\n\n/** Where one cursor stands: its position, its head, and the head's dispatch state. */\nexport type StoredCursor = HeadDispatch & {\n  /** The last index this cursor finished; a log cursor counts from the latest clear marker. */\n  position: number\n  /** The event it runs next; null when it has nothing to run. */\n  head: number | null\n}\n\n/** A cursor's head event together with its dispatch state. */\nexport type HeadEvent = StoredEvent &\n  HeadDispatch & {\n    /** Latest clear marker, on claimed heads of a cleared session. */\n    clearIndex?: number\n  }\n\n/** Names one cursor head: the consumer, its lane, and the head's index. */\nexport type HeadRef = {\n  consumer: string\n  lane: string | null\n  index: number\n}\n\n/**\n * A consumer the caller serves. Work for consumers it does not name is\n * neither pending nor claimed, so a removed consumer's cursors wait for its\n * name to return.\n */\nexport type StoreConsumer = {\n  name: string\n  /**\n   * Set for a consumer with one string lane. Its cursor keeps one position\n   * over the log and runs the next event whose type is in `types` (null:\n   * every type). A missing cursor is created by the first append that\n   * carries one of those types: at the start of the log with `backfill`,\n   * otherwise just before that append.\n   */\n  log?: {\n    lane: string\n    types: readonly string[] | null\n    backfill: boolean\n  }\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  /** Latest clear marker; omitted when the session was never cleared. */\n  clearIndex?: number\n}\n\nexport type StoreSnapshotWrite = {\n  index: number\n  state: unknown\n  /** Unfinished cursor heads that durably retain this exact checkpoint. */\n  pins?: readonly HeadRef[]\n}\n\nexport type StoreStateReadRequest = {\n  sessionId: string\n  throughIndex?: number\n  snapshotThroughIndex?: number\n}\n\n/** The result of atomically claiming every currently eligible head. */\nexport type StoreClaimAvailableResult =\n  | {\n      outcome: 'claimed'\n      events: HeadEvent[]\n      /** The session's head when the claim was made: how far behind each event is. */\n      head?: number\n    }\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 head order. */\nexport type RenewClaimsResult = {\n  /** Listed claims that remain owned by the holder. */\n  renewed: HeadRef[]\n  /** Listed claims a newer attempt has durably taken, or whose cursor moved on. */\n  superseded: HeadRef[]\n}\n\n/** The result of atomically recording a caught failure. */\nexport type FailAttemptResult = {\n  outcome: 'failed' | 'dead_lettered' | 'superseded'\n  failureCount: number\n}\n\n/** A consumer an appended event starts work for, with its resolved lane. */\nexport type EventTarget = {\n  consumer: string\n  /** The lane a lane function resolved; null runs the event concurrently. */\n  lane: string | null\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 consumer `session.append`. */\n  cause?: EventCause\n  /**\n   * Lane-function and concurrent consumers this event starts work for,\n   * resolved before persistence. Log-cursor consumers are matched by type\n   * from `StoreConsumer.log` instead.\n   */\n  targets?: readonly EventTarget[]\n}\n\n/** A consumer-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  /**\n   * Whether a served consumer has a live head in this session: one that is\n   * not dead-lettered. An append whose own batch starts work for a served\n   * consumer may report true without checking that work is runnable.\n   */\n  hasPending: boolean\n}\n\nexport type StoreClearOptions = {\n  sessionId: string\n  ifLastIndex?: number\n  /** The clearing consumer's attempt, fenced like a consumer append. */\n  cause?: EventCause\n}\n\nexport type StoreClearResult = {\n  cleared: boolean\n  /** The head after the operation. */\n  index: number\n  /** The latest clear marker after the operation, or 0. */\n  clearIndex: number\n}\n\nexport type StoreReclaimResult = { deleted: number; done: boolean }\n\nexport type StoreRedriveOptions = {\n  sessionId: string\n  consumer: string\n  index: number\n  /** `retry` clears the dead letter; `skip` moves the cursor past it. */\n  action: 'retry' | 'skip'\n  consumers?: readonly StoreConsumer[]\n}\n\nexport type StoreRedriveResult = {\n  /** Whether the head was dead-lettered and this operation resolved it. */\n  redriven: boolean\n  /** Whether a served consumer has a live head in this session: one that is not dead-lettered. */\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\n/**\n * Cursor rules every operation shares:\n *\n * - `consumers` names the consumers the caller serves. Omitted, every cursor\n *   counts and no log cursor is created or advanced by type.\n * - A cursor's head is the next event it runs: the lowest unfinished event of\n *   its lane, the event itself for a concurrent cursor, or for a log cursor\n *   the next event after its position whose type it takes. The clear marker\n *   is never a head.\n * - A head is eligible when no live claim or retry hold owns it, it is not\n *   dead-lettered, and it lies above the latest clear marker.\n * - Moving a cursor past its head resets the head's attempt and failure\n *   fields and releases snapshot pins on it.\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   * Ids are unique per session: the same id in another session names a\n   * different event and plays no part in these checks.\n   *\n   * In the same atomic operation, each event's `targets` start cursor work:\n   * a lane target queues the event in that consumer's lane, a null lane\n   * creates a cursor for that event alone. Each log consumer in `consumers`\n   * whose types the batch carries gets its cursor created or, when idle, a\n   * head: the next event after its position that it takes, which may\n   * precede the batch when an appender that doesn't serve it wrote in\n   * between. `hasPending` reflects the whole session for the served consumers,\n   * including older work and idempotent retries.\n   *\n   * An event carrying `cause` is a consumer append, fenced by attempt\n   * currency: accept it only while the cause's cursor still has\n   * `cause.index` as its head, `cause.attempt` is that head's latest\n   * attempt, and the head is not dead-lettered; otherwise throw\n   * `A2Error('SUPERSEDED_ATTEMPT')` and write nothing. The check is part of\n   * this atomic operation and must serialize against a concurrent\n   * `claimAvailable` — an unlocked read of the cursor admits write skew. The\n   * idempotent-replay path runs first, so a batch whose ids all exist\n   * replays regardless of the current attempt.\n   *\n   * Clearing stores (a2-implementation.md §17.2) fence one level earlier:\n   * a `cause` at or below the latest clear marker throws\n   * `SUPERSEDED_ATTEMPT`, an `originIndex` there throws `SESSION_CLEARED`,\n   * and ids whose rows lie below the marker are free to reuse.\n   */\n  append(\n    sessionId: string,\n    events: AppendEvent[],\n    options?: {\n      originIndex?: number\n      consumers?: readonly StoreConsumer[]\n    },\n  ): Promise<StoreAppendResult>\n\n  /**\n   * Optional with `reclaim`. Serialized with `append`: checks\n   * `ifLastIndex` against the head and the latest marker, then appends a\n   * clear marker at the next index without touching existing rows.\n   * Afterwards every event at or below the marker is superseded: no head\n   * lies there, and every log cursor's position counts from the marker.\n   */\n  clear?(options: StoreClearOptions): Promise<StoreClearResult>\n\n  /**\n   * Deletes one bounded batch of rows below the latest clear marker, with\n   * their cursor records, id records, and cached folds. `done` once nothing\n   * remains below it. Never waits on a lock that other operations hold.\n   */\n  reclaim?(sessionId: string): Promise<StoreReclaimResult>\n\n  /**\n   * Optional with `redrive`. The session's dead-lettered heads above the\n   * latest clear marker, in event order, then by consumer name.\n   */\n  deadLetters?(sessionId: string): Promise<HeadEvent[]>\n\n  /**\n   * Optional with `deadLetters`. Atomically resolves the consumer's\n   * dead-lettered head at `index` above the latest clear marker; anything\n   * else is untouched and reports `redriven: false`. `retry` clears\n   * `failedAt` and `failureCount`, so the head is claimable again with a\n   * fresh failure budget, keeping its claim history and last failure. `skip`\n   * moves the cursor past the head with no completion. Both serialize with\n   * `claimAvailable` and the consumer-append fence. `hasPending` is read in\n   * the same step.\n   */\n  redrive?(options: StoreRedriveOptions): Promise<StoreRedriveResult>\n\n  /**\n   * Brings one log consumer's cursor up to date without an append, for\n   * `session.consume()`. A missing cursor is created: with `backfill`, at\n   * the latest clear marker, taking the first event of its types after it;\n   * otherwise at the head, with nothing to run. When the session has nothing\n   * after its latest clear (or was never written), a missing cursor stays\n   * missing: nothing is written, and the cursor comes back idle at the\n   * marker, so a consume of an unknown session leaves no trace. That is\n   * exact with `backfill`; without it, the consumer starts at the first\n   * consume or serving append that finds events. An\n   * idle cursor takes the next event of its types after its position, so it\n   * finds events appended by deployments that don't serve it. A cursor with\n   * a head, claimed or not, is left as it is. Records the consumer's types,\n   * as an append would, and returns the cursor and the session's head.\n   */\n  wakeLog(options: {\n    sessionId: string\n    consumer: StoreConsumer & { log: NonNullable<StoreConsumer['log']> }\n  }): Promise<{ cursor: StoredCursor; head: number }>\n\n  /**\n   * The session's cursors: every log and lane cursor, and every concurrent\n   * cursor that still has a head, by consumer, then lane (concurrent cursors\n   * last, by head). Lane and concurrent cursors whose work lies at or below\n   * the latest clear marker are not listed.\n   */\n  cursors(sessionId: string): Promise<StoredCursor[]>\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 causal edges; 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 head of the served consumers. A live\n   * claim or retry hold produces `busy` only when it is the sole remaining\n   * obstacle to actionable work. Claimed heads are returned in event order,\n   * then by consumer name. Excluded heads stay unclaimed and keep blocking\n   * their lane.\n   */\n  claimAvailable(options: {\n    sessionId: string\n    holder: string\n    ttlMs: number\n    expiresAtMs?: number\n    exclude?: readonly HeadRef[]\n    consumers?: readonly StoreConsumer[]\n    /**\n     * Taking over a lapsed claim (one whose holder is still recorded, never\n     * completed or failed) adds one to `failureCount`. When that reaches\n     * `maxFailures`, the head dead-letters instead of being claimed: it\n     * comes back in `events` with `failedAt` set and no claim. Its\n     * `attemptCount` still advances, fencing the lapsed attempt, and its\n     * `lastFailedAttempt` is unchanged.\n     */\n    maxFailures?: number\n    /**\n     * Claims only heads at or below this index: a head past it is neither\n     * claimed nor reported `busy`, and stays claimable without it.\n     */\n    through?: number\n  }): Promise<StoreClaimAvailableResult>\n\n  /**\n   * Renews the listed live claims still owned by `holder`. Each listed claim\n   * carries the attempt the holder owns. `renewed` lists the claims that\n   * remain owned after the operation; `superseded` lists the claims whose\n   * head a newer attempt has durably taken, or whose cursor has moved past\n   * it. An 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 (HeadRef & { attempt: number })[]\n    ttlMs: number\n    expiresAtMs?: number\n  }): Promise<RenewClaimsResult>\n\n  /**\n   * Atomically completes one current attempt: appends its returned events\n   * (with their own targets, waking the served log consumers) and moves the\n   * cursor past its head. Retrying a committed completion with the same\n   * attempt and deterministic child ids returns the existing children. A\n   * stale attempt never appends.\n   */\n  completeAttempt(options: {\n    sessionId: string\n    consumer: string\n    lane: string | null\n    index: number\n    attempt: number\n    events: ReturnedEvent[]\n    consumers?: readonly StoreConsumer[]\n  }): Promise<CompleteAttemptResult>\n\n  /**\n   * Atomically records a caught failure for one claimed attempt. A stale\n   * attempt cannot poison a finished head or a newer attempt. Accepted\n   * failures record the operation's clock time. A failure that does not\n   * dead-letter releases the claim and, with `retryAfterMs`, keeps the head\n   * unclaimable for that long: its claim expiry is set with no holder, so\n   * `claimAvailable` reports it `busy` until then.\n   */\n  failAttempt(options: {\n    sessionId: string\n    consumer: string\n    lane: string | null\n    index: number\n    attempt: number\n    error: string\n    maxFailures: number\n    retryAfterMs?: 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   * Operational failures propagate without falling back to a full-log read.\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 while at least\n   * one listed cursor head is still unfinished; moving that cursor past it\n   * or dead-lettering it releases the pin and collects unreferenced\n   * 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 unexpired entry has a strictly newer `at` (the\n     * sender's stamp) is left untouched. `null` deletes the value but\n     * keeps a tombstone with its `at`, which takes part in the merge\n     * like a value until it expires, so a set older than the delete\n     * still loses when it arrives later. Every applied write, value or\n     * tombstone, 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. `subscribe` delivers applied writes only,\n     * a delete as `null`.\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    /**\n     * The current map, pruned of rows at or past their `expiresAt`.\n     * Tombstones never appear.\n     */\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":";AAiRA,MAAa,eAAsB,EACjC,2BAAW,IAAI,KAAK,EACtB;AAEA,MAAa,mBAA6B,OAAO,WAAW"}