experimental-a2 0.3.0 → 0.5.0

package/dist/server.d.ts

@@ -1,155 +1,4 @@
-import { a as EventDefs, c as Reducer, n as Contract, r as ContractEvent, t as AppendInput } from "./contract-C_3dIIEU.js";
-import { a as Event, c as IdSource, d as LogStateRead, f as StoredEvent, h as StoredSnapshot, i as Clock, l as LogAppendResult, m as StoredSessionSummary, n as A2LogInspection, o as EventCause, p as StoredSessionPage, r as AppendEvent, s as FailAttemptResult, t as A2Log, u as LogClaimAvailableResult } from "./log-ldf5g8Cx.js";
-import { i as A2Telemetry } from "./telemetry-Cso0qyHQ.js";
-//#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;
-};
-type PushValidationContext = {
-  sessionId: string;
-  events: readonly PushedEvent[];
-};
-/** What every handler receives. */
-type HandlerContext<D extends EventDefs, K extends keyof D & string = keyof D & string> = {
-  /** The triggering event. */
-  event: ContractEvent<D, K>;
-  /** Durable, 1-based dispatch ordinal for this event. */
-  attempt: number;
-  /** This session, with handler-scoped idempotent append. */
-  session: Session<D, HandlerAppend<D>>;
-  /** Fires on `abortOn` events (cancellation slice); dormant otherwise. */
-  signal: AbortSignal;
-};
-type Handler<D extends EventDefs, K extends keyof D & string = keyof D & string> = (ctx: HandlerContext<D, K>) => Promise<void | AppendInput<D> | readonly AppendInput<D>[]>;
-type LaneContext<D extends EventDefs, K extends keyof D & string = keyof D & string> = {
-  sessionId: string;
-  event: Pick<ContractEvent<D, K>, "type" | "payload"> & {
-    id?: string;
-  };
-};
-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 SessionAppend<D extends EventDefs> = SessionDispatch<D> & {
-  /** Commit, then hand pending work directly to configured recovery. */
-  dispatch: SessionDispatch<D>;
-};
-type HandlerAppend<D extends EventDefs> = (name: string, ...events: AppendInput<D>[]) => Promise<ContractEvent<D>[]>;
-/** A handle on one instance of the machine. Creating it does no I/O. */
-type Session<D extends EventDefs, Append = SessionAppend<D>> = {
-  readonly id: string;
-  append: Append;
-  history(): Promise<ContractEvent<D>[]>;
-  state<S>(reducer: Reducer<D, S>): Promise<{
-    state: S;
-    index: number;
-  }>;
-  /**
-   * A live feed of this session's events, starting after `startAt`
-   * (exclusive). Server-side only — expose it over SSE with
-   * `sseResponse` from experimental-a2/http.
-   */
-  stream(opts?: {
-    startAt?: number;
-  }): AsyncIterable<ContractEvent<D>>;
-};
-/**
- * What recovery needs from a server — structural, so servers of any
- * contract mix in one `handler(...)` call. Deliberately tiny: recovery
- * consults the log through `drain` and nothing else.
- */
-type RecoverableServer = {
-  readonly contract: {
-    readonly name: string;
-  };
-  drain(sessionId: string): Promise<{
-    settled: boolean;
-  }>;
-};
-/**
- * The recovery seam (a2-implementation.md §7, §9). `arm` puts a
- * delayed, coalesced "drain this session" message on durable
- * infrastructure while inline work starts; `handler` returns the route
- * the transport delivers to. Claim holders move the watchdog alongside
- * their renewable execution window. Implementations ship as
- * entry points (`experimental-a2/recovery-vercel`); core never imports a transport.
- */
-type A2Recovery = {
-  arm(opts: {
-    contract: string;
-    sessionId: string;
-    /** Earliest useful delivery as epoch milliseconds. */
-    dueAt?: number;
-  }): Promise<void>;
-  handler(...servers: RecoverableServer[]): (req: Request) => Promise<Response>;
-};
-type A2Server<D extends EventDefs> = {
-  /** The contract this server implements. */
-  readonly contract: Contract<D>;
-  session(id: string): Session<D>;
-  /**
-   * Process every currently eligible event. `settled` means nothing
-   * actionable remains, including work blocked behind a dead letter.
-   */
-  drain(sessionId: string): Promise<{
-    settled: boolean;
-  }>;
-};
-/**
- * Which events fire `ctx.signal` while a handler runs — the preemption
- * channel for user cancellation. The array form matches by type; the
- * object form takes per-type predicates for targeted cancellation
- * (`(event, trigger) => event.payload.of === trigger.id`). Handlers
- * without `abortOn` pay nothing. An aborted handler should catch and
- * return normally; throwing means "retry me".
- */
-type AbortSpec<D extends EventDefs, K extends keyof D & string> = Array<keyof D & string> | { [T in keyof D & string]?: true | ((event: ContractEvent<D, T>, trigger: ContractEvent<D, K>, context: {
-  attempt: number;
-}) => boolean); };
-type HandlerEntry<D extends EventDefs, K extends keyof D & string = keyof D & string> = Handler<D, K> | {
-  abortOn?: AbortSpec<D, K>;
-  /** Session-scoped FIFO key, resolved and persisted when the event lands. */
-  lane?: Lane<D, K>;
-  handler: Handler<D, K>;
-};
-type ServerOptions<D extends EventDefs> = {
-  /** The contract this server implements (see `a2.contract`). */
-  contract: Contract<D>;
-  /** Where events live. Defaults: sqlite in dev, memory in tests, required in prod. */
-  log?: A2Log;
-  /**
-   * Queue-backed recovery — e.g. `vercelQueues()` from
-   * `experimental-a2/recovery-vercel`. Absent means append-driven healing only: a
-   * working configuration, but a clockless one. Recommended in
-   * production.
-   */
-  recovery?: A2Recovery;
-  /** 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>;
-  /**
-   * The reactions, keyed by event type — all present at construction,
-   * so a handler can never be silently missing because its module
-   * wasn't imported. Compose across files by spreading objects (note:
-   * a duplicate key under spread silently last-wins).
-   */
-  handlers?: { [K in keyof D & string]?: HandlerEntry<D, K>; };
-};
-/** Implement a contract: bind its vocabulary to storage and reactions. */
-declare function createServer<D extends EventDefs>(options: ServerOptions<D>): A2Server<D>;
-//#endregion
-export { type A2Log, type A2LogInspection, A2Recovery, A2Server, AbortSpec, type AppendEvent, type AppendInput, type Clock, type Contract, type ContractEvent, type Event, type EventCause, type EventDefs, type FailAttemptResult, Handler, HandlerAppend, HandlerContext, HandlerEntry, type IdSource, Lane, LaneContext, type LogAppendResult, type LogClaimAvailableResult, type LogStateRead, PushValidationContext, PushedEvent, RecoverableServer, ServerOptions, Session, SessionAppend, SessionDispatch, type StoredEvent, type StoredSessionPage, type StoredSessionSummary, type StoredSnapshot, createServer };
+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-DUF9pjsx.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 };

package/dist/server.js

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

package/dist/{log-ldf5g8Cx.d.ts → store-DysUkTH3.d.ts}

@@ -1,19 +1,11 @@
-//#region src/log.d.ts
-/**
- * The A2Log interface — the storage contract every log backend
- * implements. See specs/a2-implementation.md §2–3.
- *
- * This is the whole storage contract: append, read, dispatch claims,
- * failure markers, snapshots, and the live stream. Recovery
- * needs nothing extra — the armed queue message is its own state, and
- * the log is the only thing it consults.
- */
+import { c as PresencePatch } from "./contract-jIfaR085.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 log, from 1. */
+  /** Position in the session's event log, from 1. */
   index: number;
   sessionId: string;
   createdAt: Date;
@@ -26,7 +18,7 @@ type EventCause = {
   batchSize?: number;
 };
 /**
- * What the log stores: immutable event history, including its causal edge,
+ * What the store persists: immutable event history, including its causal edge,
  * plus derived dispatch and failure bookkeeping. The bookkeeping is disposable;
  * the event and its cause are not.
  */
@@ -75,6 +67,21 @@ type StoredSessionSummary = {
   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
+ * 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;
+};
 /** Metadata for the latest cached fold of one reducer. */
 type StoredSnapshot = {
   reducerName: string;
@@ -82,7 +89,7 @@ type StoredSnapshot = {
   updatedAt: Date;
 };
 /** One consistent cache-plus-tail read for a reducer fold. */
-type LogStateRead = {
+type StoreStateRead = {
   /** The latest cached fold for this reducer, if one exists. */
   snapshot: {
     index: number;
@@ -96,22 +103,37 @@ type StoredSessionPage = {
   /** 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;
+};
 /**
- * Optional read-only administration implemented by A2's shipped logs.
- * It is separate from the correctness contract so custom logs do not
+ * 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 A2LogInspection = {
+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[]>;
 };
 /** The result of atomically claiming every currently eligible event. */
-type LogClaimAvailableResult = {
+type StoreClaimAvailableResult = {
   outcome: "claimed";
   events: StoredEvent[];
 } | {
@@ -127,12 +149,19 @@ type CompleteAttemptResult = {
 } | {
   outcome: "superseded";
 };
+/** The result of one claim-renewal heartbeat, both lists in append order. */
+type RenewClaimsResult = {
+  /** Listed claims that remain owned by the holder. */
+  renewed: number[];
+  /** Listed claims whose event a newer attempt has durably taken. */
+  superseded: number[];
+};
 /** The result of atomically recording a caught handler failure. */
 type FailAttemptResult = {
   outcome: "failed" | "dead_lettered" | "superseded";
   failureCount: number;
 };
-/** Input to `A2Log.append` — already validated by the machine. */
+/** Input to `A2Store.append` — already validated by the machine. */
 type AppendEvent = {
   type: string;
   payload: unknown;
@@ -145,12 +174,12 @@ type AppendEvent = {
   /** Internal hint: settle this event in the append transaction; no handler is registered. */
   settled?: true;
 };
-/** A handler-returned event with the deterministic id recovery requires. */
+/** A handler-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 LogAppendResult = {
+type StoreAppendResult = {
   events: StoredEvent[];
   /** Whether the session contains an event without a completion marker. */
   hasPending: boolean;
@@ -165,7 +194,7 @@ type Clock = {
 };
 /** An injectable id source for generated event ids. */
 type IdSource = () => string;
-interface A2Log {
+interface A2Store {
   /**
    * Accepts a batch; the batch is atomic — one transaction, consecutive
    * `index`es, all-or-nothing. The idempotency key covers the whole
@@ -178,17 +207,27 @@ interface A2Log {
    * operation, with no dispatch claim or `processedByAttempt`. The result's
    * `hasPending` reflects the whole session in the same atomic operation,
    * including older events and idempotent retries.
+   *
+   * An event carrying `cause` is a handler append, fenced by attempt
+   * currency: accept it only while `cause.attempt` is still the parent
+   * event's latest attempt and the parent 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 parent admits write skew.
+   * The idempotent-replay path runs first, so a batch whose ids all exist
+   * replays regardless of the current attempt.
    */
-  append(sessionId: string, events: AppendEvent[]): Promise<LogAppendResult>;
-  /** Events for one session, oldest first. */
+  append(sessionId: string, events: AppendEvent[]): Promise<StoreAppendResult>;
+  /** Events for one session, oldest first. Bounds form `(afterIndex, throughIndex]`. */
   read(sessionId: string, opts?: {
     afterIndex?: number;
+    throughIndex?: number;
   }): Promise<StoredEvent[]>;
   /**
    * Atomically claims every eligible pending event. Unlaned events are all
    * independently eligible. Within a lane, only the lowest-index unfinished
    * event is eligible. A live claim produces `busy` only when it is the sole
-   * remaining obstacle to actionable work. Claimed events are returned in log
+   * remaining obstacle to actionable work. Claimed events are returned in event-log
    * order. Excluded rows remain lane barriers.
    */
   claimAvailable(options: {
@@ -197,19 +236,26 @@ interface A2Log {
     ttlMs: number;
     expiresAtMs?: number;
     excludeIndexes?: readonly number[];
-  }): Promise<LogClaimAvailableResult>;
+  }): Promise<StoreClaimAvailableResult>;
   /**
-   * Renews the listed live claims still owned by `holder`. Missing, expired,
-   * completed, failed, or superseded claims are omitted from the result. The
-   * renewed indexes are returned in log order.
+   * Renews the listed live claims still owned by `holder`. Each listed claim
+   * carries the attempt ordinal the holder owns. `renewed` lists the claims
+   * that remain owned after the operation; `superseded` lists the claims
+   * whose event's `attemptCount` has durably passed the listed attempt. 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;
-    indexes: number[];
+    claims: readonly {
+      index: number;
+      attempt: number;
+    }[];
     ttlMs: number;
     expiresAtMs?: number;
-  }): Promise<number[]>;
+  }): Promise<RenewClaimsResult>;
   /**
    * Atomically completes one current attempt and appends its returned events.
    * Retrying a committed completion with the same attempt and deterministic
@@ -239,25 +285,64 @@ interface A2Log {
    * 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<LogStateRead>;
+  readState(sessionId: string, reducerName: string): 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?(sessionIds: string[], 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`).
    */
   putSnapshot(sessionId: string, reducerName: string, index: number, state: unknown): 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 existing row has a strictly newer `at` (the
+     * sender's stamp) is left untouched; `null` deletes the row. Every
+     * applied write refreshes that field's expiry to the storage's own
+     * clock plus `ttlMs` — the sender stamp orders writes but never
+     * anchors their lifetime.
+     */
+    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`. */
+    read(ns: string): Promise<PresenceRow[]>;
+    /**
+     * Push-tier patch delivery; present only on backends with a real
+     * broadcast primitive. Without it the backend is the degraded
+     * tier: live feeds surface presence by re-reading on their
+     * existing poll cadence.
+     */
+    subscribe?(ns: string, onPatch: (patch: PresencePatch) => void): () => void;
+  };
   /** Read-only operational data used by `experimental-a2/devtools/server`. */
-  inspect?: A2LogInspection;
+  inspect?: A2StoreInspection;
   /**
-   * A live feed of one session's events, starting after `startAt`
+   * 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?: {
-    startAt?: number;
+    startAfter?: number;
   }): AsyncIterable<Event>;
 }
 //#endregion
-export { Event as a, IdSource as c, LogStateRead as d, StoredEvent as f, StoredSnapshot as h, Clock as i, LogAppendResult as l, StoredSessionSummary as m, A2LogInspection as n, EventCause as o, StoredSessionPage as p, AppendEvent as r, FailAttemptResult as s, A2Log as t, LogClaimAvailableResult as u };
+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

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

@@ -0,0 +1 @@
+{"version":3,"file":"store-DysUkTH3.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;;;KAIA;EACV;EACA;EACA;EACA;;EAEA;;EAEA;EACA,cAAc;EACd,WAAW;;;;;;;;;KAUD;EACV;EACA;EACA;EACA;EACA,IAAI;EACJ,WAAW;;;KAID;EACV;EACA;EACA,WAAW;;;KAID;;EAEV;IAAY;IAAe;;;EAE3B,QAAQ;;KAGE;EACV,UAAU;;EAEV;;KAGU;EACV,QAAQ;;EAER;;;;;;;KAQU;EACV,aAAa;;IAEX;IACA;IACA;MACE,QAAQ;;;;;;EAMZ,YACE,mBACA;IAAW;IAAoB;IAAuB;MACrD,QAAQ;EACX,cAAc,oBAAoB,QAAQ;;;KAIhC;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,UAAU,mBAAmB,sBAAsB,QAAQ;;;;;;;;EAS3D,YACE,sBACA,sBACC,QAAQ;;;;;;EAOX,YACE,mBACA,qBACA,eACA,iBACC;;;;;;;EAQH;;;;;;;;;IASE,IACE,YACA,qBACA,QAAQ,gCACR;MAAQ;MAAc,IAAI;MAAM;QAC/B;;IAGH,KAAK,aAAa,QAAQ;;;;;;;IAQ1B,WAAW,YAAY,UAAU,OAAO;;;EAI1C,UAAU;;;;;;;;EASV,OACE,mBACA;IAAS;MACR,cAAc"}

package/dist/{log-yJbXUf72.js → store-N8PXxDAS.js}

@@ -1,5 +1,7 @@
-//#region src/log.ts
+//#region src/store.ts
 const SYSTEM_CLOCK = { now: () => /* @__PURE__ */ new Date() };
 const RANDOM_IDS = () => crypto.randomUUID();
 //#endregion
 export { SYSTEM_CLOCK as n, RANDOM_IDS as t };
+
+//# sourceMappingURL=store-N8PXxDAS.js.map

package/dist/store-N8PXxDAS.js.map

@@ -0,0 +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"}

package/dist/store-codec-DTG0Ftek.js

@@ -0,0 +1,10 @@
+//#region src/store-codec.ts
+const decodeReturnedEventIds = (value) => {
+	const decoded = typeof value === "string" ? JSON.parse(value) : value;
+	if (!Array.isArray(decoded) || decoded.some((eventId) => typeof eventId !== "string")) throw new TypeError("stored event has invalid returned event ids");
+	return decoded;
+};
+//#endregion
+export { decodeReturnedEventIds as t };
+
+//# sourceMappingURL=store-codec-DTG0Ftek.js.map

package/dist/store-codec-DTG0Ftek.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-codec-DTG0Ftek.js","names":[],"sources":["../src/store-codec.ts"],"sourcesContent":["export const decodeReturnedEventIds = (value: unknown): string[] => {\n  const decoded: unknown = typeof value === 'string' ? JSON.parse(value) : value\n  if (\n    !Array.isArray(decoded) ||\n    decoded.some((eventId) => typeof eventId !== 'string')\n  ) {\n    throw new TypeError('stored event has invalid returned event ids')\n  }\n  return decoded\n}\n"],"mappings":";AAAA,MAAa,0BAA0B,UAA6B;CAClE,MAAM,UAAmB,OAAO,UAAU,WAAW,KAAK,MAAM,KAAK,IAAI;CACzE,IACE,CAAC,MAAM,QAAQ,OAAO,KACtB,QAAQ,MAAM,YAAY,OAAO,YAAY,QAAQ,GAErD,MAAM,IAAI,UAAU,6CAA6C;CAEnE,OAAO;AACT"}

package/dist/store-memory.d.ts

@@ -0,0 +1,12 @@
+import { c as IdSource, i as Clock, t as A2Store } from "./store-DysUkTH3.js";
+//#region src/store-memory.d.ts
+type MemoryStoreOptions = {
+  /** Injectable clock — every stored timestamp comes from here. */
+  clock?: Clock;
+  /** Injectable id source for generated event ids. */
+  ids?: IdSource;
+};
+declare function memory(options?: MemoryStoreOptions): A2Store;
+//#endregion
+export { MemoryStoreOptions, memory };
+//# sourceMappingURL=store-memory.d.ts.map

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

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