experimental-a2 0.3.0 → 0.4.0

package/dist/{log-redis.js → store-redis.js}

@@ -1,32 +1,10 @@
-import { t as A2Error } from "./errors-BJRMd-h6.js";
-import { n as NOTIFY_TIMINGS } from "./internal-gCd5qMry.js";
+import { t as A2Error } from "./errors-BQuJpe82.js";
+import { r as NOTIFY_TIMINGS } from "./internal-aEotMzu_.js";
+import { t as defaultSleep } from "./store-polling-DgrrAE3d.js";
 import { t as retryableLazy } from "./retryable-lazy-DZWmHpii.js";
-import { n as SYSTEM_CLOCK, t as RANDOM_IDS } from "./log-yJbXUf72.js";
-import { t as defaultSleep } from "./log-polling-DZ1MiKLg.js";
-import { t as createRedisLogCore } from "./log-redis-core-CyJ5L8yR.js";
-//#region src/log-redis.ts
-/**
-* experimental-a2/log-redis — the Redis-protocol log backend, on Redis
-* Streams. The storage semantics live in log-redis-core.ts (shared
-* with experimental-a2/log-redis-http); this module owns the connection and
-* the live feed.
-*
-* `stream()` is notify-driven: writes to watched sessions fire a
-* disposable PUBLISH wake-up (feeds hold a TTL'd presence marker the
-* write script checks, so unwatched sessions cost no wake-up), one
-* shared subscriber connection per backend serves every local feed,
-* and each wake triggers an `XRANGE` catch-up read. The notification
-* only decides when to read, never what — a lost one is healed by a
-* safety re-read (NOTIFY_TIMINGS), so delivery never depends on
-* pub/sub. Connections scale with processes (one command client plus
-* one subscriber), not with concurrent viewers.
-*
-* Works with any Redis-protocol server on a single instance or a
-* non-cluster provider (Upstash — durable by default — Redis, Valkey).
-* Cluster mode is out: the atomic scripts span keys. `ioredis` is an
-* optional peer dependency; pass `url`, or inject any client exposing
-* `call`/`duplicate`/`on`/`disconnect`.
-*/
+import { n as SYSTEM_CLOCK, t as RANDOM_IDS } from "./store-N8PXxDAS.js";
+import { t as createRedisStoreCore } from "./store-redis-core-DWqx3F47.js";
+//#region src/store-redis.ts
 function redis(options = {}) {
 	const clock = options.clock ?? SYSTEM_CLOCK;
 	const ids = options.ids ?? RANDOM_IDS;
@@ -35,12 +13,13 @@ function redis(options = {}) {
 	const connection = retryableLazy(async () => {
 		if (options.client) return options.client;
 		return new (await (import("ioredis").catch(() => {
-			throw new A2Error("LOG_NOT_CONFIGURED", "experimental-a2/log-redis with a url needs the 'ioredis' package (optional peer dependency) — install it, or inject a client");
+			throw new A2Error("STORE_NOT_CONFIGURED", "experimental-a2/store-redis with a url needs the 'ioredis' package (optional peer dependency) — install it, or inject a client");
 		}))).default(options.url);
 	});
 	const client = connection.get;
 	const notifyChannel = (sessionId) => `${prefix}:${sessionId}:notify`;
-	const core = createRedisLogCore({
+	const presenceChannel = (ns) => `${prefix}:${ns}:presence`;
+	const core = createRedisStoreCore({
 		call: async (command, ...args) => {
 			return (await client()).call(command, ...args);
 		},
@@ -66,18 +45,63 @@ function redis(options = {}) {
 	* clock's every-stored-timestamp pledge is untouched.
 	*/
 	const watchedRefreshedAt = /* @__PURE__ */ new Map();
+	/**
+	* `:presence` channel → live listeners. Same-instance patches are
+	* delivered here synchronously by `presence.set`, so subscribe/set
+	* ordering never depends on the SUBSCRIBE command settling; the
+	* channel carries only other instances' patches, with own echoes
+	* skipped by `src`.
+	*/
+	const presenceListeners = /* @__PURE__ */ new Map();
+	const instanceId = crypto.randomUUID();
+	const deliverRemotePresence = (listeners, message) => {
+		let parsed;
+		try {
+			parsed = JSON.parse(message);
+		} catch {
+			return;
+		}
+		if (parsed.src === instanceId) return;
+		const patch = {
+			participant: parsed.participant,
+			values: parsed.values,
+			seen: parsed.seen,
+			at: new Date(parsed.at)
+		};
+		for (const listener of listeners) listener(patch);
+	};
 	const getSubscriber = () => {
 		subscriber ??= (async () => {
 			const conn = (await client()).duplicate();
-			conn.on("message", (channel) => {
+			conn.on("message", (channel, message) => {
 				const set = wakers.get(channel);
-				if (!set) return;
-				for (const wake of set) wake();
+				if (set) for (const wake of set) wake();
+				const listeners = presenceListeners.get(channel);
+				if (listeners) deliverRemotePresence(listeners, message);
 			});
 			return conn;
 		})();
 		return subscriber;
 	};
+	/**
+	* The subscriber, gated on connection readiness — for channel
+	* commands only (`close` uses the ungated promise, so it can never
+	* hang on an unreachable server). SUBSCRIBE carries redis's
+	* ok-loading flag, so ioredis writes it mid-handshake, ahead of the
+	* ready check's INFO — which then finds the connection already in
+	* subscriber mode and fails the check (a spurious error event plus
+	* a reconnect). ECHO has no such flag: it resolves only once the
+	* connection is ready, so every channel command chained behind it
+	* lands after the check.
+	*/
+	let subscriberGate = null;
+	const gatedSubscriber = () => {
+		subscriberGate ??= getSubscriber().then(async (conn) => {
+			await conn.call("echo", "ready");
+			return conn;
+		});
+		return subscriberGate;
+	};
 	const acquireChannel = async (channel) => {
 		const existing = subscriptions.get(channel);
 		if (existing) {
@@ -92,7 +116,7 @@ function redis(options = {}) {
 		}
 		const lease = {
 			refs: 1,
-			ready: getSubscriber().then((conn) => conn.call("subscribe", channel))
+			ready: gatedSubscriber().then((conn) => conn.call("subscribe", channel))
 		};
 		subscriptions.set(channel, lease);
 		try {
@@ -109,7 +133,7 @@ function redis(options = {}) {
 		if (lease.refs > 0) return;
 		subscriptions.delete(channel);
 		watchedRefreshedAt.delete(channel);
-		getSubscriber().then((conn) => conn.call("unsubscribe", channel)).catch(() => {});
+		gatedSubscriber().then((conn) => conn.call("unsubscribe", channel)).catch(() => {});
 	};
 	const armWaker = (channel) => {
 		let wake;
@@ -141,11 +165,47 @@ function redis(options = {}) {
 		readState: core.readState,
 		putSnapshot: core.putSnapshot,
 		inspect: core.inspect,
+		presence: {
+			async set(ns, participant, values, meta) {
+				const patch = await core.presence.set(ns, participant, values, meta);
+				if (!patch) return;
+				const channel = presenceChannel(ns);
+				const listeners = presenceListeners.get(channel);
+				if (listeners) for (const listener of listeners) listener(patch);
+				const message = JSON.stringify({
+					src: instanceId,
+					participant: patch.participant,
+					values: patch.values,
+					seen: patch.seen,
+					at: patch.at.getTime()
+				});
+				await client().then((c) => c.call("publish", channel, message)).catch(() => {});
+			},
+			read: core.presence.read,
+			subscribe(ns, onPatch) {
+				const channel = presenceChannel(ns);
+				let listeners = presenceListeners.get(channel);
+				if (!listeners) {
+					listeners = /* @__PURE__ */ new Set();
+					presenceListeners.set(channel, listeners);
+				}
+				listeners.add(onPatch);
+				acquireChannel(channel).catch(() => {});
+				let stopped = false;
+				return () => {
+					if (stopped) return;
+					stopped = true;
+					listeners.delete(onPatch);
+					if (listeners.size === 0) presenceListeners.delete(channel);
+					releaseChannel(channel);
+				};
+			}
+		},
 		stream(sessionId, opts) {
-			const startAt = opts?.startAt ?? 0;
+			const startAfter = opts?.startAfter ?? 0;
 			const channel = notifyChannel(sessionId);
 			return { [Symbol.asyncIterator]() {
-				let last = startAt;
+				let last = startAfter;
 				let buffer = [];
 				let closed = false;
 				let subscribed = false;
@@ -176,7 +236,7 @@ function redis(options = {}) {
 							}
 							if (severed) {
 								release();
-								throw new A2Error("LOG_UNAVAILABLE", "the log was closed");
+								throw new A2Error("STORE_UNAVAILABLE", "the store was closed");
 							}
 							const waker = armWaker(channel);
 							interrupt = waker.wake;
@@ -204,7 +264,7 @@ function redis(options = {}) {
 									done: true
 								};
 								if (err instanceof A2Error) throw err;
-								throw new A2Error("LOG_UNAVAILABLE", "redis log operation failed", { cause: err });
+								throw new A2Error("STORE_UNAVAILABLE", "redis store operation failed", { cause: err });
 							} finally {
 								waker.disarm();
 								interrupt = null;

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

@@ -1,6 +1,6 @@
-import { c as IdSource, i as Clock, t as A2Log } from "./log-ldf5g8Cx.js";
-//#region src/log-sqlite.d.ts
-type SqliteLogOptions = {
+import { c as IdSource, i as Clock, t as A2Store } from "./store-C3sNAaBT.js";
+//#region src/store-sqlite.d.ts
+type SqliteStoreOptions = {
   /** Database file path. Defaults to `.a2/dev.db`; `:memory:` works. */
   path?: string;
   /** Injectable clock — every stored timestamp comes from here. */
@@ -8,10 +8,10 @@ type SqliteLogOptions = {
   /** Injectable id source for generated event ids. */
   ids?: IdSource;
 };
-type SqliteLog = A2Log & {
+type SqliteStore = A2Store & {
   /** Close the underlying database handle. */
   close(): void;
 };
-declare function sqlite(options?: SqliteLogOptions): SqliteLog;
+declare function sqlite(options?: SqliteStoreOptions): SqliteStore;
 //#endregion
-export { SqliteLog, SqliteLogOptions, sqlite };
+export { SqliteStore, SqliteStoreOptions, sqlite };

package/dist/{log-sqlite.js → store-sqlite.js}

@@ -1,16 +1,17 @@
-import { t as A2Error } from "./errors-BJRMd-h6.js";
-import { t as idempotentReplay } from "./idempotent-replay-BMyHrP0L.js";
-import { n as SYSTEM_CLOCK, t as RANDOM_IDS } from "./log-yJbXUf72.js";
-import { n as pollingStream } from "./log-polling-DZ1MiKLg.js";
+import { t as A2Error } from "./errors-BQuJpe82.js";
+import { n as pollingStream } from "./store-polling-DgrrAE3d.js";
+import { t as idempotentReplay } from "./idempotent-replay-DuqEkYA7.js";
+import { n as SYSTEM_CLOCK, t as RANDOM_IDS } from "./store-N8PXxDAS.js";
+import { t as decodeReturnedEventIds } from "./store-codec-DTG0Ftek.js";
 import { mkdirSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { DatabaseSync } from "node:sqlite";
-//#region src/log-sqlite.ts
+//#region src/store-sqlite.ts
 /**
-* experimental-a2/log-sqlite — sqlite log backend (the dev default, `.a2/dev.db`).
+* experimental-a2/store-sqlite — sqlite store backend (the dev default, `.a2/dev.db`).
 *
 * Built on `node:sqlite` (Node ≥ 22.13) so it ships with zero
-* dependencies. Implements the A2Log interface; the conformance suite
+* dependencies. Implements the A2Store interface; the conformance suite
 * in test/conformance is the executable contract.
 *
 * The spec's `index` column is stored as `idx` (a2-implementation.md
@@ -66,6 +67,17 @@ create table if not exists a2_snapshots (
   updated_at   integer not null,
   primary key (session_id, reducer_name)
 ) strict;
+
+create table if not exists a2_presence (
+  ns          text    not null,
+  participant text    not null,
+  field       text    not null,
+  value       text    not null,
+  seen        integer not null,
+  at          integer not null,
+  expires_at  integer not null,
+  primary key (ns, participant, field)
+) strict;
 `;
 /**
 * Switching journal modes takes an exclusive lock, and — unlike normal
@@ -88,7 +100,7 @@ const wrap = (fn) => {
 		return fn();
 	} catch (err) {
 		if (err instanceof A2Error || err instanceof TypeError) throw err;
-		throw new A2Error("LOG_UNAVAILABLE", "sqlite log operation failed", { cause: err });
+		throw new A2Error("STORE_UNAVAILABLE", "sqlite store operation failed", { cause: err });
 	}
 };
 const toDate = (ms) => ms === null ? null : new Date(Number(ms));
@@ -114,7 +126,7 @@ const toStored = (row) => ({
 	lane: row.lane,
 	processedAt: toDate(row.processed_at),
 	processedByAttempt: row.processed_by_attempt === null ? null : Number(row.processed_by_attempt),
-	returnedEventIds: row.returned_event_ids === null ? null : JSON.parse(row.returned_event_ids),
+	returnedEventIds: row.returned_event_ids === null ? null : decodeReturnedEventIds(row.returned_event_ids),
 	firstClaimedAt: toDate(row.first_claimed_at),
 	lastClaimedAt: toDate(row.last_claimed_at),
 	attemptCount: Number(row.attempt_count),
@@ -175,6 +187,21 @@ function sqlite(options = {}) {
               select 1 from a2_events
               where session_id = ? and processed_at is null
             ) as has_pending`);
+	const upsertPresence = db.prepare(`insert into a2_presence (ns, participant, field, value, seen, at, expires_at)
+     values (?, ?, ?, ?, ?, ?, ?)
+     on conflict (ns, participant, field) do update set
+       value = excluded.value,
+       seen = excluded.seen,
+       at = excluded.at,
+       expires_at = excluded.expires_at
+     where a2_presence.at <= excluded.at`);
+	const deletePresence = db.prepare(`delete from a2_presence
+      where ns = ? and participant = ? and field = ? and at <= ?`);
+	const sweepPresence = db.prepare("delete from a2_presence where ns = ? and expires_at <= ?");
+	const selectPresence = db.prepare(`select participant, field, value, seen, at, expires_at
+       from a2_presence
+      where ns = ? and expires_at > ?
+      order by participant, field`);
 	const selectByIds = (count) => db.prepare(`select stored.*,
               exists(
                 select 1 from a2_events pending
@@ -221,6 +248,12 @@ function sqlite(options = {}) {
 						throw new A2Error("PARTIAL_DUPLICATE_BATCH", `batch mixes ${existing.length} already-appended and ${events.length - existing.length} fresh events`);
 					}
 				}
+				for (const e of events) {
+					if (!e.cause) continue;
+					const parent = db.prepare("select attempt_count, failed_at from a2_events where session_id = ? and idx = ?").get(sessionId, e.cause.index);
+					if (!parent) throw new TypeError(`no event at index ${e.cause.index} in session '${sessionId}'`);
+					if (Number(parent.attempt_count) !== e.cause.attempt || parent.failed_at !== null) throw new A2Error("SUPERSEDED_ATTEMPT", `attempt ${e.cause.attempt} no longer owns event ${e.cause.index} in session '${sessionId}'`);
+				}
 				const status = appendStatus.get(sessionId, sessionId);
 				const base = Number(status.max);
 				const now = clock.now().getTime();
@@ -265,6 +298,10 @@ function sqlite(options = {}) {
 					conditions.push("idx > ?");
 					params.push(opts.afterIndex);
 				}
+				if (opts?.throughIndex !== void 0) {
+					conditions.push("idx <= ?");
+					params.push(opts.throughIndex);
+				}
 				return db.prepare(`select * from a2_events where ${conditions.join(" and ")} order by idx`).all(...params).map(toStored);
 			});
 		},
@@ -312,20 +349,39 @@ function sqlite(options = {}) {
 				};
 			}));
 		},
-		async renewClaims({ sessionId, holder, indexes, ttlMs, expiresAtMs }) {
-			if (indexes.length === 0) return [];
+		async renewClaims({ sessionId, holder, claims, ttlMs, expiresAtMs }) {
+			if (claims.length === 0) return {
+				renewed: [],
+				superseded: []
+			};
 			return wrap(() => tx(() => {
 				const now = clock.now().getTime();
 				const expiresAt = expiresAtMs ?? now + ttlMs;
-				const placeholders = indexes.map(() => "?").join(", ");
-				return db.prepare(`update a2_events set claim_expires_at = ?
-                where session_id = ?
-                  and idx in (${placeholders})
-                  and processed_at is null
-                  and failed_at is null
-                  and claim_holder = ?
-                  and claim_expires_at > ?
-                returning idx`).all(expiresAt, sessionId, ...indexes, holder, now).map((row) => Number(row.idx)).toSorted((a, b) => a - b);
+				const renewed = [];
+				const superseded = [];
+				const currentAttempt = db.prepare("select attempt_count from a2_events where session_id = ? and idx = ?");
+				const extend = db.prepare(`update a2_events set claim_expires_at = ?
+              where session_id = ?
+                and idx = ?
+                and attempt_count = ?
+                and processed_at is null
+                and failed_at is null
+                and claim_holder = ?
+                and claim_expires_at > ?`);
+				for (const claim of claims) {
+					const row = currentAttempt.get(sessionId, claim.index);
+					if (!row) continue;
+					if (Number(row.attempt_count) > claim.attempt) {
+						superseded.push(claim.index);
+						continue;
+					}
+					const updated = extend.run(expiresAt, sessionId, claim.index, claim.attempt, holder, now);
+					if (Number(updated.changes) === 1) renewed.push(claim.index);
+				}
+				return {
+					renewed: renewed.toSorted((a, b) => a - b),
+					superseded: superseded.toSorted((a, b) => a - b)
+				};
 			}));
 		},
 		async completeAttempt({ sessionId, index, attempt, events }) {
@@ -336,7 +392,7 @@ function sqlite(options = {}) {
 				if (new Set(ids).size !== ids.length) throw new A2Error("PARTIAL_DUPLICATE_BATCH", "returned event batch contains the same event id more than once");
 				if (parent.processed_at !== null) {
 					if (Number(parent.processed_by_attempt) !== attempt) return { outcome: "superseded" };
-					const returnedIds = parent.returned_event_ids === null ? null : JSON.parse(parent.returned_event_ids);
+					const returnedIds = parent.returned_event_ids === null ? null : decodeReturnedEventIds(parent.returned_event_ids);
 					if (returnedIds === null || returnedIds.length !== ids.length || returnedIds.some((id, offset) => id !== ids[offset])) throw new A2Error("PARTIAL_DUPLICATE_BATCH", "completed attempt does not match the returned event batch");
 					const existing = ids.length === 0 ? [] : selectByIds(ids.length).all(sessionId, ...ids);
 					const byId = new Map(existing.map((row) => [row.event_id, row]));
@@ -465,6 +521,32 @@ function sqlite(options = {}) {
            where excluded.up_to_index > a2_snapshots.up_to_index`).run(sessionId, reducerName, index, JSON.stringify(state) ?? "null", clock.now().getTime());
 			});
 		},
+		presence: {
+			async set(ns, participant, values, meta) {
+				const entries = Object.entries(values);
+				if (entries.length === 0) return;
+				wrap(() => tx(() => {
+					const atMs = meta.at.getTime();
+					const expiresAtMs = clock.now().getTime() + meta.ttlMs;
+					for (const [field, value] of entries) if (value === null) deletePresence.run(ns, participant, field, atMs);
+					else upsertPresence.run(ns, participant, field, JSON.stringify(value) ?? "null", meta.seen, atMs, expiresAtMs);
+				}));
+			},
+			async read(ns) {
+				return wrap(() => {
+					const now = clock.now().getTime();
+					sweepPresence.run(ns, now);
+					return selectPresence.all(ns, now).map((row) => ({
+						participant: row.participant,
+						field: row.field,
+						value: JSON.parse(row.value),
+						seen: Number(row.seen),
+						at: new Date(Number(row.at)),
+						expiresAt: new Date(Number(row.expires_at))
+					}));
+				});
+			}
+		},
 		inspect: {
 			async listSessions(inspectionOptions) {
 				return wrap(() => {
@@ -513,6 +595,18 @@ function sqlite(options = {}) {
 					};
 				});
 			},
+			async readEvents(sessionId, pageOptions) {
+				return wrap(() => {
+					const currentFrontier = Number(db.prepare("select coalesce(max(idx), 0) as frontier from a2_events where session_id = ?").get(sessionId).frontier);
+					const throughIndex = Math.min(pageOptions.throughIndex ?? currentFrontier, currentFrontier);
+					return {
+						events: db.prepare(`select * from a2_events
+                where session_id = ? and idx > ? and idx <= ?
+                order by idx limit ?`).all(sessionId, pageOptions.afterIndex, throughIndex, pageOptions.limit).map(toStored),
+						throughIndex
+					};
+				});
+			},
 			async listSnapshots(sessionId) {
 				return wrap(() => {
 					return db.prepare(`select reducer_name, up_to_index, updated_at
@@ -528,7 +622,7 @@ function sqlite(options = {}) {
 			const readAfter = (afterIndex) => wrap(() => {
 				return db.prepare("select * from a2_events where session_id = ? and idx > ? order by idx").all(sessionId, afterIndex).map(toStored);
 			});
-			return pollingStream(readAfter, opts?.startAt !== void 0 ? { startAt: opts.startAt } : {});
+			return pollingStream(readAfter, opts?.startAfter !== void 0 ? { startAfter: opts.startAfter } : {});
 		},
 		close() {
 			db.close();

package/dist/{telemetry-Cso0qyHQ.d.ts → telemetry-BjYHTfh2.d.ts}

@@ -1,7 +1,7 @@
 //#region src/telemetry.d.ts
 /**
  * The A2Telemetry interface — the instrumentation seam. Same philosophy
- * as log backends: the interface lives in core, implementations ship as
+ * as store backends: the interface lives in core, implementations ship as
  * entry points (`experimental-a2/otel` adapts it to OpenTelemetry). Without one,
  * every operation runs through a no-op wrapper.
  */

package/dist/testing.browser.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/testing.browser.js

@@ -0,0 +1,4 @@
+//#region src/testing.browser.ts
+/** experimental-a2/testing loads local capture files and is Node-only. */
+throw new Error("experimental-a2/testing is Node-only. Load captures in a local test or script.");
+//#endregion

package/dist/testing.d.ts

@@ -0,0 +1,31 @@
+import { a as EventDefs, n as Contract, p as Reducer, r as ContractEvent } from "./contract-jIfaR085.js";
+import { c as DevtoolsCapture, l as DevtoolsCaptureEvent } from "./devtools-J_jZ2vQf.js";
+//#region src/testing.d.ts
+type CaptureSource = string | URL;
+type LoadedCapture<D extends EventDefs> = {
+  /** The verified capture, including its footer and operational records. */
+  readonly capture: DevtoolsCapture;
+  /** The contract used to validate and type the captured event history. */
+  readonly contract: Contract<D>;
+  /** Contract-typed public events with `createdAt` revived to `Date`. */
+  readonly events: readonly ContractEvent<D>[];
+  /** Unmodified wire events, including dispatch and failure metadata. */
+  readonly rawEvents: readonly DevtoolsCaptureEvent[];
+};
+type ReplayCaptureOptions = {
+  /** Fold events through this log index, inclusive. Zero means no events. */
+  throughIndex?: number;
+};
+type CaptureReplay<S> = {
+  readonly state: S;
+  /** The last event index actually folded, or zero for the initial state. */
+  readonly index: number;
+};
+/** Validate an already-parsed capture against an application's contract. */
+declare function prepareCapture<D extends EventDefs>(capture: DevtoolsCapture, contract: Contract<D>): Promise<LoadedCapture<D>>;
+/** Load, integrity-check, and contract-type a `.a2log` file or URL. */
+declare function loadCapture<D extends EventDefs>(source: CaptureSource, contract: Contract<D>): Promise<LoadedCapture<D>>;
+/** Purely fold captured events through a reducer, optionally to a cutpoint. */
+declare function replayCapture<D extends EventDefs, S>(loaded: LoadedCapture<D>, reducer: Reducer<D, S>, options?: ReplayCaptureOptions): CaptureReplay<S>;
+//#endregion
+export { CaptureReplay, CaptureSource, LoadedCapture, ReplayCaptureOptions, loadCapture, prepareCapture, replayCapture };

package/dist/testing.js

@@ -0,0 +1,101 @@
+import { n as validateSync } from "./validate-XKT4FSNn.js";
+import { l as parseDevtoolsCapture, u as verifyDevtoolsCapture } from "./devtools-kJJaORn-.js";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+//#region src/testing.ts
+/**
+* Offline helpers for loading a captured A2 session and replaying its events
+* through the application's current reducers. This module never constructs a
+* server or dispatches handlers.
+*/
+const captureError = (message) => /* @__PURE__ */ new TypeError(`invalid A2 capture: ${message}`);
+const typedEvents = (capture, contract) => {
+	const events = [];
+	for (const event of capture.events) {
+		const schema = Object.hasOwn(contract.events, event.type) ? contract.events[event.type] : void 0;
+		if (schema === void 0) throw captureError(`contract '${contract.name}' has no event type '${event.type}' at index ${event.index}`);
+		const result = validateSync(schema, structuredClone(event.payload), `captured event '${event.type}'`);
+		if (result.issues !== void 0) throw captureError(`event #${event.index} '${event.type}' has an invalid payload: ${result.issues.map((issue) => issue.message).join("; ")}`);
+		events.push({
+			id: event.id,
+			type: event.type,
+			payload: result.value,
+			index: event.index,
+			sessionId: event.sessionId,
+			createdAt: new Date(event.createdAt)
+		});
+	}
+	return events;
+};
+/** Validate an already-parsed capture against an application's contract. */
+async function prepareCapture(capture, contract) {
+	await verifyDevtoolsCapture(capture);
+	if (capture.contract !== contract.name) throw captureError(`expected contract '${contract.name}', received '${capture.contract}'`);
+	return {
+		capture,
+		contract,
+		events: typedEvents(capture, contract),
+		rawEvents: capture.events
+	};
+}
+const displayUrl = (url) => {
+	if (url.protocol === "data:") return "data: URL";
+	const safe = new URL(url);
+	safe.username = "";
+	safe.password = "";
+	safe.search = "";
+	safe.hash = "";
+	return safe.href;
+};
+const fetchCapture = async (url) => {
+	const location = displayUrl(url);
+	let response;
+	try {
+		response = await fetch(url);
+	} catch {
+		throw new Error(`failed to load A2 capture from '${location}'`);
+	}
+	if (!response.ok) throw new Error(`failed to load A2 capture from '${location}': ${response.status} ${response.statusText}`);
+	return new Uint8Array(await response.arrayBuffer());
+};
+const readCapture = async (source) => {
+	if (source instanceof URL) return source.protocol === "file:" ? readFile(fileURLToPath(source)) : fetchCapture(source);
+	if (/^[a-z]:[\\/]/i.test(source)) return readFile(source);
+	let url;
+	try {
+		url = new URL(source);
+	} catch {
+		return readFile(source);
+	}
+	return readCapture(url);
+};
+/** Load, integrity-check, and contract-type a `.a2log` file or URL. */
+async function loadCapture(source, contract) {
+	const encoded = await readCapture(source);
+	return prepareCapture(parseDevtoolsCapture(encoded), contract);
+}
+const cloneInitial = (initialState) => {
+	try {
+		return structuredClone(initialState);
+	} catch {
+		return initialState;
+	}
+};
+/** Purely fold captured events through a reducer, optionally to a cutpoint. */
+function replayCapture(loaded, reducer, options = {}) {
+	const { throughIndex } = options;
+	if (throughIndex !== void 0 && (!Number.isInteger(throughIndex) || throughIndex < 0)) throw new TypeError("throughIndex must be a non-negative integer");
+	let state = cloneInitial(reducer.initialState);
+	let index = 0;
+	for (const event of loaded.events) {
+		if (throughIndex !== void 0 && event.index > throughIndex) break;
+		state = reducer.fold(state, event);
+		index = event.index;
+	}
+	return {
+		state,
+		index
+	};
+}
+//#endregion
+export { loadCapture, prepareCapture, replayCapture };