experimental-a2 0.6.0 → 0.8.0

package/dist/{server-DpvjhdoE.d.ts → server-DjPhHnbI.d.ts}

@@ -1,6 +1,63 @@
 import { a as EventDefs, c as PresencePatch, d as WithPresence, l as PresenceSnapshot, n as Contract, o as PresenceDefs, p as Reducer, r as ContractEvent, s as PresenceMap, t as AppendInput } from "./contract-jIfaR085.js";
-import { t as A2Store } from "./store-DysUkTH3.js";
+import { t as A2Store } from "./store-RJO35BMj.js";
 import { i as A2Telemetry } from "./telemetry-CpeclqB2.js";
+//#region src/session-socket.d.ts
+/**
+ * The structural socket `sessionsSocket` speaks against — satisfied
+ * by `ws` and by `@vercel/functions`' upgraded socket alike, so the
+ * platform upgrade API stays out of the library. `message` data
+ * arrives as whatever the platform delivers (string, Buffer,
+ * ArrayBuffer, or fragments); the handler normalizes defensively.
+ */
+type A2Socket = {
+  send(data: string): void;
+  on(event: "message", listener: (data: unknown) => void): void;
+  on(event: "close", listener: () => void): void;
+  on(event: "error", listener: (error: unknown) => void): void;
+  close(code?: number, reason?: string): void;
+  /** Bytes queued but not yet transmitted — when exposed, the down
+   * pump uses it for backpressure (`SOCKET_TIMINGS`). */
+  bufferedAmount?: number;
+};
+//#endregion
+//#region src/server-fetch.d.ts
+type SuggestedEventType<D extends EventDefs> = (keyof D & string) | (string & Record<never, never>);
+type SuggestedPresenceValues<P extends PresenceDefs> = Readonly<{ [F in keyof P & string]?: unknown; } & Record<string, unknown>>;
+type A2PushEvent<D extends EventDefs = EventDefs> = {
+  readonly type: SuggestedEventType<D>;
+  readonly payload: unknown;
+  readonly id?: string;
+};
+type A2PushPresence<P extends PresenceDefs = PresenceDefs> = {
+  readonly participant: string;
+  readonly values: SuggestedPresenceValues<P>;
+  readonly seen?: number;
+  readonly at?: number;
+};
+type A2Operation<D extends EventDefs = EventDefs, P extends PresenceDefs = Record<never, never>> = {
+  readonly type: "stream";
+  readonly sessionId: string;
+  readonly startAfter: number;
+  readonly transport: "http" | "websocket";
+} | {
+  readonly type: "history";
+  readonly sessionId: string;
+  readonly gte: number;
+  readonly lte: number;
+  readonly transport: "http";
+} | {
+  readonly type: "push";
+  readonly sessionId: string;
+  readonly events: readonly A2PushEvent<D>[];
+  readonly presence?: A2PushPresence<P>;
+  readonly transport: "http" | "websocket";
+};
+type UpgradeWebSocket = (attach: (socket: A2Socket) => void) => Response | Promise<Response>;
+type ServerFetchOptions<D extends EventDefs = EventDefs, P extends PresenceDefs = Record<never, never>> = {
+  authorize?: (operation: A2Operation<D, P>) => boolean | Promise<boolean>;
+  upgradeWebSocket?: UpgradeWebSocket;
+};
+//#endregion
 //#region src/scheduler-task.d.ts
 /** One event carried by a delayed append task. */
 type ScheduledEvent = {
@@ -33,42 +90,6 @@ type SchedulerAppendTask = {
 type SchedulerTask = SchedulerDrainTask | SchedulerAppendTask;
 //#endregion
 //#region src/server.d.ts
-/**
- * Events that arrived over the wire through `parsePushBody` — already
- * envelope-validated, headed for schema validation inside `append`.
- * The brand lets the documented push route hand them straight to
- * `session.append` without weakening typed appends for app code: a
- * hand-written `{ type: string }` literal still fails to compile.
- */
-type PushedEvent = {
-  type: string;
-  payload: unknown;
-  id?: string;
-  readonly "~a2.pushed": true;
-};
-/**
- * A presence patch that arrived over the wire through `parsePushBody`
- * — same provenance brand as `PushedEvent`, so the documented route
- * hands it whole to `session.setPresence` while a hand-written
- * untyped patch still fails to compile. Field validation happens
- * inside `setPresence`.
- */
-type PushedPresence = {
-  participant: string;
-  values: Record<string, unknown>;
-  seen?: number;
-  /** The sender's LWW stamp in epoch ms; receipt time when absent. */
-  at?: number;
-  readonly "~a2.pushed": true;
-};
-type PushValidationContext = {
-  sessionId: string;
-  events: readonly PushedEvent[];
-  /** The whole pushed patch — present exactly on the presence-plane
-   * invocation, so the callback authorizes the participant id and can
-   * apply size or cardinality policy. */
-  presence?: PushedPresence;
-};
 /** What every handler receives. */
 type HandlerContext<D extends EventDefs, K extends keyof D & string = keyof D & string, P extends PresenceDefs = Record<never, never>> = {
   /** The triggering event. */
@@ -88,11 +109,7 @@ type LaneContext<D extends EventDefs, K extends keyof D & string = keyof D & str
   };
 };
 type Lane<D extends EventDefs, K extends keyof D & string = keyof D & string> = string | ((context: LaneContext<D, K>) => string);
-type SessionDispatch<D extends EventDefs> = {
-  (...events: AppendInput<D>[]): Promise<ContractEvent<D>[]>;
-  /** The push-route path: events from `parsePushBody`. */
-  (...events: PushedEvent[]): Promise<ContractEvent<D>[]>;
-};
+type SessionDispatch<D extends EventDefs> = (...events: AppendInput<D>[]) => Promise<ContractEvent<D>[]>;
 type SessionAppend<D extends EventDefs> = SessionDispatch<D> & {
   /** Commit, then hand pending work directly to configured scheduler. */
   dispatch: SessionDispatch<D>;
@@ -107,6 +124,9 @@ type ScheduleTiming = {
   delay?: never;
 };
 type SessionSchedule<D extends EventDefs> = (name: string, timing: ScheduleTiming, ...events: AppendInput<D>[]) => Promise<void>;
+type StateOptions = {
+  through?: number | "latest";
+};
 /**
  * The presence members of a session — intersected in via
  * `WithPresence`, so they exist exactly when the contract declares
@@ -135,7 +155,7 @@ type SessionPresence<D extends EventDefs, P extends PresenceDefs> = {
     values: PresencePatch<P>["values"];
     seen?: number;
     at?: number;
-  } | PushedPresence): Promise<void>;
+  }): Promise<void>;
   /** The current map, expired values pruned — a point-in-time read. */
   presence(): Promise<PresenceMap<P>>;
 };
@@ -148,14 +168,13 @@ type Session<D extends EventDefs, Append = SessionAppend<D>, P extends PresenceD
     gte?: number;
     lte?: number;
   }): Promise<ContractEvent<D>[]>;
-  state<S>(reducer: Reducer<D, S>): Promise<{
+  state<S>(reducer: Reducer<D, S>, options?: StateOptions): Promise<{
     state: S;
     index: number;
   }>;
   /**
    * A live feed of this session's events, starting after `startAfter`
-   * (exclusive). Server-side only — `handle` from experimental-a2/http
-   * exposes it over SSE as the route's stream lane.
+   * (exclusive). Server-side only. `server.fetch` exposes it over SSE.
    */
   stream(opts?: {
     startAfter?: number;
@@ -190,6 +209,10 @@ type A2Scheduler = {
 type A2Server<D extends EventDefs, P extends PresenceDefs = Record<never, never>> = {
   /** The contract this server implements. */
   readonly contract: Contract<D, P>;
+  readonly fetch: {
+    (request: Request): Promise<Response>;
+    (request: Request, options: ServerFetchOptions<D, P>): Promise<Response>;
+  };
   session(id: string): Session<D, SessionAppend<D>, P>;
   /**
    * Process every currently eligible event. `settled` means nothing
@@ -236,8 +259,6 @@ type ServerOptions<D extends EventDefs, P extends PresenceDefs = Record<never, n
   scheduler?: A2Scheduler;
   /** Optional instrumentation — e.g. `otel()` from `experimental-a2/otel`. */
   telemetry?: A2Telemetry;
-  /** Validate events that came through `parsePushBody` before writing them. */
-  validatePush?: (context: PushValidationContext) => void | PromiseLike<void>;
   /**
    * Presence-plane policy — valid only when the contract declares
    * presence fields (TypeError at construction otherwise). `ttlMs` is
@@ -257,5 +278,5 @@ type ServerOptions<D extends EventDefs, P extends PresenceDefs = Record<never, n
 /** Implement a contract: bind its vocabulary to storage and reactions. */
 declare function createServer<D extends EventDefs, P extends PresenceDefs = Record<never, never>>(options: ServerOptions<D, P>): A2Server<D, P>;
 //#endregion
-export { deliverSchedulerAppend as C, SchedulerTask as D, SchedulerDrainTask as E, createServer as S, SchedulerAppendTask as T, Session as _, Handler as a, SessionPresence as b, HandlerEntry as c, PushValidationContext as d, PushedEvent as f, ServerOptions as g, ScheduleTiming as h, DrainableServer as i, Lane as l, ScheduleDelay as m, A2Server as n, HandlerAppend as o, PushedPresence as p, AbortSpec as r, HandlerContext as s, A2Scheduler as t, LaneContext as u, SessionAppend as v, ScheduledEvent as w, SessionSchedule as x, SessionDispatch as y };
-//# sourceMappingURL=server-DpvjhdoE.d.ts.map
+export { UpgradeWebSocket as A, SchedulerAppendTask as C, A2PushEvent as D, A2Operation as E, A2PushPresence as O, ScheduledEvent as S, SchedulerTask as T, SessionPresence as _, Handler as a, createServer as b, HandlerEntry as c, ScheduleDelay as d, ScheduleTiming as f, SessionDispatch as g, SessionAppend as h, DrainableServer as i, A2Socket as j, ServerFetchOptions as k, Lane as l, Session as m, A2Server as n, HandlerAppend as o, ServerOptions as p, AbortSpec as r, HandlerContext as s, A2Scheduler as t, LaneContext as u, SessionSchedule as v, SchedulerDrainTask as w, deliverSchedulerAppend as x, StateOptions as y };
+//# sourceMappingURL=server-DjPhHnbI.d.ts.map

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

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

package/dist/server.d.ts

@@ -1,4 +1,4 @@
 import { a as EventDefs, c as PresencePatch, l as PresenceSnapshot, n as Contract, o as PresenceDefs, r as ContractEvent, s as PresenceMap, t as AppendInput } from "./contract-jIfaR085.js";
-import { a as Event, c as IdSource, d as StoreClaimAvailableResult, f as StoreStateRead, g as StoredSnapshot, h as StoredSessionSummary, i as Clock, l as PresenceRow, m as StoredSessionPage, n as A2StoreInspection, o as EventCause, p as StoredEvent, r as AppendEvent, s as FailAttemptResult, t as A2Store, u as StoreAppendResult } from "./store-DysUkTH3.js";
-import { C as deliverSchedulerAppend, D as SchedulerTask, E as SchedulerDrainTask, S as createServer, T as SchedulerAppendTask, _ as Session, a as Handler, b as SessionPresence, c as HandlerEntry, d as PushValidationContext, f as PushedEvent, g as ServerOptions, h as ScheduleTiming, i as DrainableServer, l as Lane, m as ScheduleDelay, n as A2Server, o as HandlerAppend, p as PushedPresence, r as AbortSpec, s as HandlerContext, t as A2Scheduler, u as LaneContext, v as SessionAppend, w as ScheduledEvent, x as SessionSchedule, y as SessionDispatch } from "./server-DpvjhdoE.js";
-export { A2Scheduler, A2Server, type A2Store, type A2StoreInspection, AbortSpec, type AppendEvent, type AppendInput, type Clock, type Contract, type ContractEvent, DrainableServer, type Event, type EventCause, type EventDefs, type FailAttemptResult, Handler, HandlerAppend, HandlerContext, HandlerEntry, type IdSource, Lane, LaneContext, type PresenceDefs, type PresenceMap, type PresencePatch, type PresenceRow, type PresenceSnapshot, PushValidationContext, PushedEvent, PushedPresence, ScheduleDelay, ScheduleTiming, type ScheduledEvent, type SchedulerAppendTask, type SchedulerDrainTask, type SchedulerTask, ServerOptions, Session, SessionAppend, SessionDispatch, SessionPresence, SessionSchedule, type StoreAppendResult, type StoreClaimAvailableResult, type StoreStateRead, type StoredEvent, type StoredSessionPage, type StoredSessionSummary, type StoredSnapshot, createServer, deliverSchedulerAppend };
+import { a as EventCause, c as PresenceRow, d as StoreStateRead, f as StoredEvent, i as Event, l as StoreAppendResult, n as AppendEvent, o as FailAttemptResult, r as Clock, s as IdSource, t as A2Store, u as StoreClaimAvailableResult } from "./store-RJO35BMj.js";
+import { A as UpgradeWebSocket, C as SchedulerAppendTask, D as A2PushEvent, E as A2Operation, O as A2PushPresence, S as ScheduledEvent, T as SchedulerTask, _ as SessionPresence, a as Handler, b as createServer, c as HandlerEntry, d as ScheduleDelay, f as ScheduleTiming, g as SessionDispatch, h as SessionAppend, i as DrainableServer, j as A2Socket, k as ServerFetchOptions, l as Lane, m as Session, n as A2Server, o as HandlerAppend, p as ServerOptions, r as AbortSpec, s as HandlerContext, t as A2Scheduler, u as LaneContext, v as SessionSchedule, w as SchedulerDrainTask, x as deliverSchedulerAppend, y as StateOptions } from "./server-DjPhHnbI.js";
+export { type A2Operation, type A2PushEvent, type A2PushPresence, A2Scheduler, A2Server, type A2Socket, type A2Store, AbortSpec, type AppendEvent, type AppendInput, type Clock, type Contract, type ContractEvent, DrainableServer, type Event, type EventCause, type EventDefs, type FailAttemptResult, Handler, HandlerAppend, HandlerContext, HandlerEntry, type IdSource, Lane, LaneContext, type PresenceDefs, type PresenceMap, type PresencePatch, type PresenceRow, type PresenceSnapshot, ScheduleDelay, ScheduleTiming, type ScheduledEvent, type SchedulerAppendTask, type SchedulerDrainTask, type SchedulerTask, type ServerFetchOptions, ServerOptions, Session, SessionAppend, SessionDispatch, SessionPresence, SessionSchedule, StateOptions, type StoreAppendResult, type StoreClaimAvailableResult, type StoreStateRead, type StoredEvent, type UpgradeWebSocket, createServer, deliverSchedulerAppend };

package/dist/server.js

@@ -1,2 +1,2 @@
-import { n as deliverSchedulerAppend, t as createServer } from "./server-Duw6MVlB.js";
+import { n as deliverSchedulerAppend, t as createServer } from "./server-B2XNevQA.js";
 export { createServer, deliverSchedulerAppend };

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/** Durable, read-only session metadata for administrative inspection. */\nexport type StoredSessionSummary = {\n  sessionId: string\n  eventCount: number\n  pendingCount: number\n  failedCount: number\n  /** Durable dispatch claims across every event in the session. */\n  attemptCount: number\n  /** Caught handler failures across every event in the session. */\n  failureCount: number\n  firstEventAt: Date\n  updatedAt: Date\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/** Metadata for the latest cached fold of one reducer. */\nexport type StoredSnapshot = {\n  reducerName: string\n  index: number\n  updatedAt: Date\n}\n\n/** One consistent cache-plus-tail read for a reducer fold. */\nexport type StoreStateRead = {\n  /** The latest cached fold for this reducer, if one exists. */\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 StoredSessionPage = {\n  sessions: StoredSessionSummary[]\n  /** Opaque backend cursor; null means there is no next page. */\n  cursor: string | null\n}\n\nexport type StoredEventPage = {\n  events: StoredEvent[]\n  /** Fixed inclusive log frontier shared by every page in one inspection. */\n  throughIndex: number\n}\n\n/**\n * Optional read-only administration implemented by A2's shipped stores.\n * It is separate from the correctness contract so custom stores do not\n * need to expose storage-wide discovery merely to process events.\n */\nexport type A2StoreInspection = {\n  listSessions(options: {\n    /** Storage namespace prefix, including the contract separator. */\n    prefix: string\n    cursor?: string\n    limit: number\n  }): Promise<StoredSessionPage>\n  /**\n   * A bounded event page for read-only administration. The first page captures\n   * `throughIndex`; callers pass it back so concurrent appends cannot extend a\n   * walk indefinitely. Optional for custom stores; A2 falls back to `read()`.\n   */\n  readEvents?(\n    sessionId: string,\n    options: { afterIndex: number; throughIndex?: number; limit: number },\n  ): Promise<StoredEventPage>\n  listSnapshots(sessionId: string): Promise<StoredSnapshot[]>\n}\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(sessionId: string, reducerName: string): 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    sessionIds: string[],\n    reducerName: string,\n  ): Promise<StoreStateRead[]>\n\n  /**\n   * Writes a disposable reducer cache. Guard this operation so a slower\n   * concurrent writer can never clobber a further-along snapshot\n   * (`where up_to_index < excluded.up_to_index`).\n   */\n  putSnapshot(\n    sessionId: string,\n    reducerName: string,\n    index: number,\n    state: unknown,\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     * Push-tier patch delivery; present only on backends with a real\n     * broadcast primitive. Without it the backend is the degraded\n     * tier: live feeds surface presence by re-reading on their\n     * existing poll cadence.\n     */\n    subscribe?(ns: string, onPatch: (patch: PresencePatch) => void): () => void\n  }\n\n  /** Read-only operational data used by `experimental-a2/devtools/server`. */\n  inspect?: A2StoreInspection\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":";AAkNA,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  /**\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     * Push-tier patch delivery; present only on backends with a real\n     * broadcast primitive. Without it the backend is the degraded\n     * tier: live feeds surface presence by re-reading on their\n     * existing poll cadence.\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-DysUkTH3.d.ts → store-RJO35BMj.d.ts}

@@ -54,19 +54,6 @@ type StoredEvent = Event & {
   /** Adapter clock time recorded when dead-lettered; null otherwise. */
   failedAt: Date | null;
 };
-/** Durable, read-only session metadata for administrative inspection. */
-type StoredSessionSummary = {
-  sessionId: string;
-  eventCount: number;
-  pendingCount: number;
-  failedCount: number;
-  /** Durable dispatch claims across every event in the session. */
-  attemptCount: number;
-  /** Caught handler failures across every event in the session. */
-  failureCount: number;
-  firstEventAt: Date;
-  updatedAt: Date;
-};
 /**
  * One live presence value, as `A2Store.presence.read` returns it. The
  * row is the LWW unit — one participant's one field. `at` is the
@@ -82,15 +69,11 @@ type PresenceRow = {
   at: Date;
   expiresAt: Date;
 };
-/** Metadata for the latest cached fold of one reducer. */
-type StoredSnapshot = {
-  reducerName: string;
-  index: number;
-  updatedAt: Date;
-};
 /** One consistent cache-plus-tail read for a reducer fold. */
 type StoreStateRead = {
-  /** The latest cached fold for this reducer, if one exists. */
+  /** 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;
@@ -98,39 +81,16 @@ type StoreStateRead = {
   /** Immutable events strictly after `snapshot.index`, or the full log on a miss. */
   events: Event[];
 };
-type StoredSessionPage = {
-  sessions: StoredSessionSummary[];
-  /** Opaque backend cursor; null means there is no next page. */
-  cursor: string | null;
-};
-type StoredEventPage = {
-  events: StoredEvent[];
-  /** Fixed inclusive log frontier shared by every page in one inspection. */
-  throughIndex: number;
+type StoreSnapshotWrite = {
+  index: number;
+  state: unknown;
+  /** Unfinished trigger events that durably retain this exact checkpoint. */
+  pinEventIndexes?: readonly number[];
 };
-/**
- * Optional read-only administration implemented by A2's shipped stores.
- * It is separate from the correctness contract so custom stores do not
- * need to expose storage-wide discovery merely to process events.
- */
-type A2StoreInspection = {
-  listSessions(options: {
-    /** Storage namespace prefix, including the contract separator. */
-    prefix: string;
-    cursor?: string;
-    limit: number;
-  }): Promise<StoredSessionPage>;
-  /**
-   * A bounded event page for read-only administration. The first page captures
-   * `throughIndex`; callers pass it back so concurrent appends cannot extend a
-   * walk indefinitely. Optional for custom stores; A2 falls back to `read()`.
-   */
-  readEvents?(sessionId: string, options: {
-    afterIndex: number;
-    throughIndex?: number;
-    limit: number;
-  }): Promise<StoredEventPage>;
-  listSnapshots(sessionId: string): Promise<StoredSnapshot[]>;
+type StoreStateReadRequest = {
+  sessionId: string;
+  throughIndex?: number;
+  snapshotThroughIndex?: number;
 };
 /** The result of atomically claiming every currently eligible event. */
 type StoreClaimAvailableResult = {
@@ -285,7 +245,10 @@ interface A2Store {
    * log. The snapshot is untrusted; core may reject it and issue a full
    * `read()` when its state schema no longer accepts the cached value.
    */
-  readState(sessionId: string, reducerName: string): Promise<StoreStateRead>;
+  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
@@ -293,13 +256,14 @@ interface A2Store {
    * cross-session consistency claim. Core falls back to parallel
    * `readState` calls when absent.
    */
-  readStates?(sessionIds: string[], reducerName: string): Promise<StoreStateRead[]>;
+  readStates?(requests: readonly StoreStateReadRequest[], reducerName: string): Promise<StoreStateRead[]>;
   /**
-   * Writes a disposable reducer cache. Guard this operation so a slower
-   * concurrent writer can never clobber a further-along snapshot
-   * (`where up_to_index < excluded.up_to_index`).
+   * Atomically writes disposable reducer checkpoints. The greatest index
+   * advances the head cache. Older checkpoints survive only when at least one
+   * listed trigger event is still unfinished; completion and dead-lettering
+   * release that event's pins and collect unreferenced historical checkpoints.
    */
-  putSnapshot(sessionId: string, reducerName: string, index: number, state: unknown): Promise<void>;
+  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
@@ -330,8 +294,6 @@ interface A2Store {
      */
     subscribe?(ns: string, onPatch: (patch: PresencePatch) => void): () => void;
   };
-  /** Read-only operational data used by `experimental-a2/devtools/server`. */
-  inspect?: A2StoreInspection;
   /**
    * A live feed of one session's events, starting after `startAfter`
    * (exclusive). Transport is the backend's choice — in-process pub/sub,
@@ -344,5 +306,5 @@ interface A2Store {
   }): AsyncIterable<Event>;
 }
 //#endregion
-export { Event as a, IdSource as c, StoreClaimAvailableResult as d, StoreStateRead as f, StoredSnapshot as g, StoredSessionSummary as h, Clock as i, PresenceRow as l, StoredSessionPage as m, A2StoreInspection as n, EventCause as o, StoredEvent as p, AppendEvent as r, FailAttemptResult as s, A2Store as t, StoreAppendResult as u };
-//# sourceMappingURL=store-DysUkTH3.d.ts.map
+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-RJO35BMj.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store-RJO35BMj.d.ts","names":[],"sources":["../src/store.ts"],"mappings":";;;KAaY;EACV;EACA;EACA;;EAEA;EACA;EACA,WAAW;;;KAID;EACV;EACA;;EAEA;;;;;;;KAQU,cAAc;;EAExB,OAAO;;EAEP;;EAEA,aAAa;;EAEb;;EAEA;;EAEA,gBAAgB;;EAEhB,eAAe;;EAEf;;EAEA;;EAEA,gBAAgB;;EAEhB;;EAEA,cAAc;;EAEd;;EAEA;;EAEA,UAAU;;;;;;;;;KAUA;EACV;EACA;EACA;EACA;EACA,IAAI;EACJ,WAAW;;;KAID;;EAEV;;EAEA;IAAY;IAAe;;;EAE3B,QAAQ;;KAGE;EACV;EACA;;EAEA;;KAGU;EACV;EACA;EACA;;;KAGU;EACN;EAAoB,QAAQ;;EAC5B;EAAiB,SAAS;;EAC1B;;;KAGM;EACR;EAAsB,QAAQ;;EAAoB;;;KAG1C;;EAEV;;EAEA;;;KAIU;EACV;EACA;;;KAIU;EACV;EACA;;EAEA;;EAEA,QAAQ;;EAER;;EAEA;;;KAIU,gBAAgB;EAAgB;;;KAGhC;EACV,QAAQ;;EAER;;;;;;;KAQU;EACV,OAAO;;;KAIG;UAQK;;;;;;;;;;;;;;;;;;;;;;;EAuBf,OAAO,mBAAmB,QAAQ,gBAAgB,QAAQ;;EAG1D,KACE,mBACA;IAAS;IAAqB;MAC7B,QAAQ;;;;;;;;EASX,eAAe;IACb;IACA;IACA;IACA;IACA;MACE,QAAQ;;;;;;;;;;EAWZ,YAAY;IACV;IACA;IACA;MAAmB;MAAe;;IAClC;IACA;MACE,QAAQ;;;;;;EAOZ,gBAAgB;IACd;IACA;IACA;IACA,QAAQ;MACN,QAAQ;;;;;;EAOZ,YAAY;IACV;IACA;IACA;IACA;IACA;MACE,QAAQ;;;;;;;EAQZ,UACE,mBACA,qBACA;IAAY;IAAuB;MAClC,QAAQ;;;;;;;;EASX,YACE,mBAAmB,yBACnB,sBACC,QAAQ;;;;;;;EAQX,aACE,mBACA,qBACA,oBAAoB,uBACnB;;;;;;;EAQH;;;;;;;;;IASE,IACE,YACA,qBACA,QAAQ,gCACR;MAAQ;MAAc,IAAI;MAAM;QAC/B;;IAGH,KAAK,aAAa,QAAQ;;;;;;;IAQ1B,WAAW,YAAY,UAAU,OAAO;;;;;;;;;EAU1C,OACE,mBACA;IAAS;MACR,cAAc"}

package/dist/store-memory.d.ts

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

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

@@ -1 +1 @@
-{"version":3,"file":"store-memory.d.ts","names":[],"sources":["../src/store-memory.ts"],"mappings":";;KA2BY;;EAEV,QAAQ;;EAER,MAAM;;iBAyEQ,OAAO,UAAS,qBAA0B"}
+{"version":3,"file":"store-memory.d.ts","names":[],"sources":["../src/store-memory.ts"],"mappings":";;KA0BY;;EAEV,QAAQ;;EAER,MAAM;;iBA+EQ,OAAO,UAAS,qBAA0B"}