experimental-a2 0.0.0 → 0.2.0

package/dist/devtools-server.browser.js

@@ -1,4 +1,4 @@
 //#region src/devtools-server.browser.ts
-/** a2/devtools/server owns log access and is server-only. */
-throw new Error("a2/devtools/server is server-only — mount its handler in a server route and open that URL in the browser.");
+/** experimental-a2/devtools/server owns log access and is server-only. */
+throw new Error("experimental-a2/devtools/server is server-only — mount its handler in a server route and open that URL in the browser.");
 //#endregion

package/dist/devtools-server.js

@@ -819,7 +819,7 @@ if (bootstrap) {
 //#endregion
 //#region src/devtools-server.ts
 /**
-* a2/devtools/server — a read-only dashboard over A2's durable data.
+* experimental-a2/devtools/server — a read-only dashboard over A2's durable data.
 * One Request handler serves the application, its private browser bundle,
 * JSON inspection endpoints, and live SSE invalidations.
 */

package/dist/http.d.ts

@@ -1,4 +1,4 @@
-import { a as Event } from "./log-Dg1I8NRr.js";
+import { a as Event } from "./log-ldf5g8Cx.js";
 import { PushedEvent } from "./server.js";
 import { t as A2Error } from "./errors-xL_JTXsY.js";
 //#region src/http.d.ts

package/dist/http.js

@@ -1,9 +1,9 @@
 import { t as A2Error } from "./errors-BJRMd-h6.js";
-import { r as STREAM_TIMINGS } from "./internal-Dm8Ejnud.js";
-import { a as eventToWire, n as errorStatus, r as errorToWire, t as errorFromWire } from "./wire-2QpU1EtJ.js";
+import { r as STREAM_TIMINGS } from "./internal-D6wNxTck.js";
+import { a as eventToWire, n as errorStatus, r as errorToWire, t as errorFromWire } from "./wire-BVsgR8o9.js";
 //#region src/http.ts
 /**
-* a2/http — route-side transport helpers (specs/a2-api.md §9–10).
+* experimental-a2/http — route-side transport helpers (specs/a2-api.md §9–10).
 *
 * `sseResponse` pipes a `session.stream()` iterable into a server-sent
 * events Response; `parsePushBody` validates the push envelope;
@@ -39,6 +39,7 @@ async function parsePushBody(req) {
 				payload
 			};
 			if (id !== void 0) out.id = id;
+			Object.defineProperty(out, "~a2.pushed", { value: true });
 			return out;
 		})
 	};

package/dist/idempotent-replay-BMyHrP0L.js

@@ -0,0 +1,19 @@
+import { t as A2Error } from "./errors-BJRMd-h6.js";
+//#region src/idempotent-replay.ts
+const canonicalJson = (value) => JSON.stringify(value, (_key, candidate) => {
+	if (candidate === null || typeof candidate !== "object" || Array.isArray(candidate)) return candidate;
+	return Object.fromEntries(Object.entries(candidate).toSorted(([left], [right]) => left.localeCompare(right)));
+}) ?? "null";
+const idempotentReplay = (events, existing) => {
+	const byId = new Map(existing.map((event) => [event.id, event]));
+	const ordered = events.map((event) => event.id === void 0 ? void 0 : byId.get(event.id));
+	const firstIndex = ordered[0]?.index;
+	const batchSize = events[0]?.cause?.batchSize;
+	if (firstIndex === void 0 || batchSize !== void 0 && batchSize !== events.length || ordered.some((stored, index) => {
+		const event = events[index];
+		return stored === void 0 || stored.index !== firstIndex + index || stored.type !== event.type || stored.lane !== (event.lane ?? null) || stored.cause?.batchSize !== event.cause?.batchSize || canonicalJson(stored.payload) !== canonicalJson(event.payload);
+	})) throw new A2Error("PARTIAL_DUPLICATE_BATCH", "already-appended events do not match the retried batch");
+	return ordered;
+};
+//#endregion
+export { idempotentReplay as t };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a as ReducerOptions, c as ReducerBuilder, i as EventDefs, l as StandardSchemaV1, n as Contract, o as contract, r as ContractEvent, s as Reducer, t as AppendInput } from "./contract-DL8btVd9.js";
-import { a as Event } from "./log-Dg1I8NRr.js";
-import { i as A2Telemetry, n as A2SpanHandle, r as A2SpanName, t as A2AttributeValue } from "./telemetry-C78al20p.js";
+import { a as EventDefs, c as Reducer, i as EventBatchFactory, l as ReducerBuilder, n as Contract, o as ReducerOptions, r as ContractEvent, s as contract, t as AppendInput, u as StandardSchemaV1 } from "./contract-C_3dIIEU.js";
+import { a as Event } from "./log-ldf5g8Cx.js";
+import { i as A2Telemetry, n as A2SpanHandle, r as A2SpanName, t as A2AttributeValue } from "./telemetry-Cso0qyHQ.js";
 import { n as A2ErrorCode, t as A2Error } from "./errors-xL_JTXsY.js";
-export { type A2AttributeValue, A2Error, type A2ErrorCode, type A2SpanHandle, type A2SpanName, type A2Telemetry, type AppendInput, type Contract, type ContractEvent, type Event, type EventDefs, type Reducer, type ReducerBuilder, type ReducerOptions, type StandardSchemaV1, contract };
+export { type A2AttributeValue, A2Error, type A2ErrorCode, type A2SpanHandle, type A2SpanName, type A2Telemetry, type AppendInput, type Contract, type ContractEvent, type Event, type EventBatchFactory, type EventDefs, type Reducer, type ReducerBuilder, type ReducerOptions, type StandardSchemaV1, contract };

package/dist/index.js

@@ -1,3 +1,3 @@
-import { t as contract } from "./contract-B0kAXoaL.js";
+import { t as contract } from "./contract-CG_adnu_.js";
 import { t as A2Error } from "./errors-BJRMd-h6.js";
 export { A2Error, contract };

package/dist/{internal-Dm8Ejnud.js → internal-D6wNxTck.js}

@@ -1,13 +1,13 @@
 //#region src/internal.ts
 const serverInternals = /* @__PURE__ */ new WeakMap();
 /**
-* Drain timing knobs. Mutable only as a white-box test seam — lease
+* Drain timing knobs. Mutable only as a white-box test seam. Claim
 * heartbeats run on real timers, so tests shrink these to keep suites
 * fast. Production always uses the defaults.
 */
 const DRAIN_TIMINGS = {
-	leaseTtlMs: 5e3,
-	leaseHeartbeatMs: 2e3,
+	claimTtlMs: 5e3,
+	claimHeartbeatMs: 2e3,
 	recoveryGraceMs: 1e3,
 	recoveryArmTimeoutMs: 2e3
 };

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

@@ -3,8 +3,8 @@
  * 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, the drain markers,
- * the failure markers, leases, snapshots, and the live stream. Recovery
+ * 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.
  */
@@ -22,25 +22,35 @@ type Event = {
 type EventCause = {
   index: number;
   attempt: number;
+  /** Size of one named handler append, used to reject truncated retries. */
+  batchSize?: number;
 };
 /**
  * What the log stores: immutable event history, including its causal edge,
- * plus derived drain and failure bookkeeping. The bookkeeping is disposable;
+ * plus derived dispatch and failure bookkeeping. The bookkeeping is disposable;
  * the event and its cause are not.
  */
 type StoredEvent = Event & {
-  /** Same-session handler dispatch that appended this event; null means root or legacy unknown. */
+  /** Same-session handler dispatch that appended this event; null means root. */
   cause: EventCause | null;
-  /** Adapter clock time recorded by completion or manual skip; null while pending. */
+  /** Session-scoped serial execution key resolved when the event is appended. */
+  lane: string | null;
+  /** Adapter clock time recorded by append settlement, completion, or manual skip; null while pending. */
   processedAt: Date | null;
-  /** Dispatch attempt that completed this event; null for pending or administrative completion. */
+  /** Dispatch attempt that completed this event; null without dispatch or while pending. */
   processedByAttempt: number | null;
+  /** Exact ordered child ids atomically returned by the completing attempt. */
+  returnedEventIds: string[] | null;
   /** Adapter clock time recorded by the first durable dispatch claim. */
   firstClaimedAt: Date | null;
   /** Adapter clock time recorded by the most recent durable dispatch claim. */
   lastClaimedAt: Date | null;
   /** Durable dispatch claims, including claims abandoned by hard kills. */
   attemptCount: number;
+  /** Current dispatch holder; null when the event is not claimed. */
+  claimHolder: string | null;
+  /** Adapter clock expiry for the current dispatch claim. */
+  claimExpiresAt: Date | null;
   /** Caught handler failures. This alone drives dead-lettering. */
   failureCount: number;
   /** Adapter clock time recorded by the most recent caught handler failure. */
@@ -89,7 +99,7 @@ type StoredSessionPage = {
 /**
  * Optional read-only administration implemented by A2's shipped logs.
  * It is separate from the correctness contract so custom logs do not
- * need to expose storage-wide discovery merely to store and drain events.
+ * need to expose storage-wide discovery merely to process events.
  */
 type A2LogInspection = {
   listSessions(options: {
@@ -100,17 +110,21 @@ type A2LogInspection = {
   }): Promise<StoredSessionPage>;
   listSnapshots(sessionId: string): Promise<StoredSnapshot[]>;
 };
-/** The result of atomically claiming the next event in a drain. */
-type LogClaimResult = {
+/** The result of atomically claiming every currently eligible event. */
+type LogClaimAvailableResult = {
   outcome: "claimed";
-  event: StoredEvent;
+  events: StoredEvent[];
 } | {
   outcome: "busy";
+  retryAt: Date;
 } | {
   outcome: "settled";
 };
 /** A completion may lose to a newer claim or an earlier completion. */
-type LogHandoffResult = LogClaimResult | {
+type CompleteAttemptResult = {
+  outcome: "completed";
+  events: StoredEvent[];
+} | {
   outcome: "superseded";
 };
 /** The result of atomically recording a caught handler failure. */
@@ -124,11 +138,25 @@ type AppendEvent = {
   payload: unknown;
   /** Caller-supplied idempotency key; generated when absent. */
   id?: string;
-  /** Internal causal edge supplied atomically by `ctx.append`. */
+  /** Internal causal edge supplied atomically by handler `session.append`. */
   cause?: EventCause;
+  /** Session-scoped serial execution key resolved before persistence. */
+  lane?: string;
+  /** 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. */
+type ReturnedEvent = AppendEvent & {
+  id: string;
+};
+/** The rows written by an append and the session's pending state. */
+type LogAppendResult = {
+  events: StoredEvent[];
+  /** Whether the session contains an event without a completion marker. */
+  hasPending: boolean;
 };
 /**
- * An injectable clock. Adapters take one so tests can drive lease
+ * 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.
  */
@@ -146,43 +174,53 @@ interface A2Log {
    * 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')`.
+   * Events carrying `settled: true` get `processedAt` in this same atomic
+   * 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.
    */
-  append(sessionId: string, events: AppendEvent[]): Promise<StoredEvent[]>;
+  append(sessionId: string, events: AppendEvent[]): Promise<LogAppendResult>;
   /** Events for one session, oldest first. */
   read(sessionId: string, opts?: {
     afterIndex?: number;
-    unprocessedOnly?: boolean;
   }): Promise<StoredEvent[]>;
   /**
-   * Atomically selects the first pending event, checks its scope, acquires the
-   * session lease, increments its durable dispatch count, and records the
-   * operation's clock time. A claimed event's `attemptCount` is the 1-based
-   * attempt passed to its handler.
+   * 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
+   * order. Excluded rows remain lane barriers.
    */
-  claimNext(options: {
+  claimAvailable(options: {
     sessionId: string;
     holder: string;
     ttlMs: number;
     expiresAtMs?: number;
-    /** Inclusive causal-tree frontier. Omit for a full-session drain. */
-    maxIndex?: number;
-  }): Promise<LogClaimResult>;
+    excludeIndexes?: readonly number[];
+  }): Promise<LogClaimAvailableResult>;
   /**
-   * Atomically marks one event processed only if its attempt is still current
-   * and it has no completion marker. While this holder still owns a live lease,
-   * claims the next pending event. Completion and any claimed successor record
-   * the same adapter clock value.
+   * 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.
    */
-  completeAndClaimNext(options: {
+  renewClaims(options: {
     sessionId: string;
     holder: string;
-    completedIndex: number;
+    indexes: number[];
+    ttlMs: number;
+    expiresAtMs?: number;
+  }): Promise<number[]>;
+  /**
+   * Atomically completes one current attempt and appends its returned events.
+   * 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;
+    index: number;
     attempt: number;
-    /** Inclusive causal-tree frontier. Omit for a full-session drain. */
-    maxIndex?: number;
-  }): Promise<LogHandoffResult>;
-  /** The drain-completion marker and drain idempotency check. */
-  markProcessed(sessionId: string, index: number): Promise<void>;
+    events: ReturnedEvent[];
+  }): Promise<CompleteAttemptResult>;
   /**
    * Atomically records a caught failure for one claimed attempt. A stale
    * attempt cannot poison a processed event or a newer dispatch. Accepted
@@ -195,8 +233,6 @@ interface A2Log {
     error: string;
     maxFailures: number;
   }): Promise<FailAttemptResult>;
-  /** Dead-letters the event. */
-  markFailed(sessionId: string, index: number): Promise<void>;
   /**
    * 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
@@ -210,26 +246,8 @@ interface A2Log {
    * (`where up_to_index < excluded.up_to_index`).
    */
   putSnapshot(sessionId: string, reducerName: string, index: number, state: unknown): Promise<void>;
-  /** Read-only operational data used by `a2/devtools/server`. */
+  /** Read-only operational data used by `experimental-a2/devtools/server`. */
   inspect?: A2LogInspection;
-  /**
-   * One lease per session — serializes processing order for a session,
-   * not individual events. TTL-bounded, never held indefinitely.
-   * Re-acquiring with the same holder renews the TTL.
-   */
-  lease: {
-    acquire(options: {
-      sessionId: string;
-      holder: string;
-      ttlMs: number;
-      /** Optional absolute expiry used for platform-deadline lease windows. */
-      expiresAtMs?: number;
-    }): Promise<boolean>;
-    release(options: {
-      sessionId: string;
-      holder: string;
-    }): Promise<void>;
-  };
   /**
    * A live feed of one session's events, starting after `startAt`
    * (exclusive). Transport is the backend's choice — in-process pub/sub,
@@ -242,4 +260,4 @@ interface A2Log {
   }): AsyncIterable<Event>;
 }
 //#endregion
-export { Event as a, IdSource as c, LogStateRead as d, StoredEvent as f, StoredSnapshot as h, Clock as i, LogClaimResult as l, StoredSessionSummary as m, A2LogInspection as n, EventCause as o, StoredSessionPage as p, AppendEvent as r, FailAttemptResult as s, A2Log as t, LogHandoffResult as u };
+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 };

package/dist/log-memory.d.ts

@@ -1,4 +1,4 @@
-import { c as IdSource, i as Clock, t as A2Log } from "./log-Dg1I8NRr.js";
+import { c as IdSource, i as Clock, t as A2Log } from "./log-ldf5g8Cx.js";
 //#region src/log-memory.d.ts
 type MemoryLogOptions = {
   /** Injectable clock — every stored timestamp comes from here. */