experimental-a2 0.2.0 → 0.4.0

package/dist/store-redis-http.d.ts

@@ -0,0 +1,21 @@
+import { c as IdSource, i as Clock, t as A2Store } from "./store-C3sNAaBT.js";
+//#region src/store-redis-http.d.ts
+type RedisHttpStoreOptions = {
+  /** REST endpoint, e.g. `process.env.UPSTASH_REDIS_REST_URL`. */
+  url: string;
+  /** Bearer token, e.g. `process.env.UPSTASH_REDIS_REST_TOKEN`. */
+  token: string;
+  /** Key prefix — isolates multiple apps on one Redis. Default `'a2'`. */
+  keyPrefix?: string;
+  /** Injectable clock — every stored timestamp comes from here. */
+  clock?: Clock;
+  /** Injectable id source for generated event ids. */
+  ids?: IdSource;
+};
+type RedisHttpStore = A2Store & {
+  /** Nothing to disconnect; present so callers can treat stores uniformly. */
+  close(): Promise<void>;
+};
+declare function redisHttp(options: RedisHttpStoreOptions): RedisHttpStore;
+//#endregion
+export { RedisHttpStore, RedisHttpStoreOptions, redisHttp };

package/dist/store-redis-http.js

@@ -0,0 +1,70 @@
+import { t as A2Error } from "./errors-BQuJpe82.js";
+import { n as pollingStream } from "./store-polling-DgrrAE3d.js";
+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-http.ts
+/**
+* experimental-a2/store-redis-http — the same Redis Streams store over a
+* provider REST API (Upstash-shaped: POST one command as a JSON array,
+* receive `{ result }` or `{ error }`). The storage semantics live in
+* store-redis-core.ts, shared with experimental-a2/store-redis.
+*
+* Fully connectionless: every command is one `fetch`, so it works
+* where a Redis-protocol connection cannot exist or cannot be spared.
+* Without a connection there is no push and no pub/sub, so `stream()`
+* is the shared activity-adaptive poll loop (25ms while events flow,
+* backing off to a 250ms idle ceiling), and presence is the degraded
+* tier: `set`/`read` from the shared core, no `subscribe`. No peer
+* dependencies.
+*/
+function redisHttp(options) {
+	if (!options.url || !options.token) throw new TypeError("redisHttp() needs a url and a token");
+	const { url, token } = options;
+	const call = async (command, ...args) => {
+		let response;
+		try {
+			response = await fetch(url, {
+				method: "POST",
+				headers: {
+					authorization: `Bearer ${token}`,
+					"content-type": "application/json"
+				},
+				body: JSON.stringify([command, ...args.map(String)])
+			});
+		} catch (err) {
+			throw new A2Error("STORE_UNAVAILABLE", "redis rest request failed", { cause: err });
+		}
+		const body = await response.json().catch(() => null);
+		if (body === null || !response.ok || body.error !== void 0) throw new A2Error("STORE_UNAVAILABLE", `redis rest command failed: ${body?.error ?? `status ${response.status}`}`);
+		return body.result;
+	};
+	const core = createRedisStoreCore({
+		call,
+		clock: options.clock ?? SYSTEM_CLOCK,
+		ids: options.ids ?? RANDOM_IDS,
+		keyPrefix: options.keyPrefix ?? "a2"
+	});
+	return {
+		append: core.append,
+		read: core.read,
+		claimAvailable: core.claimAvailable,
+		renewClaims: core.renewClaims,
+		completeAttempt: core.completeAttempt,
+		failAttempt: core.failAttempt,
+		readState: core.readState,
+		putSnapshot: core.putSnapshot,
+		presence: {
+			async set(ns, participant, values, meta) {
+				await core.presence.set(ns, participant, values, meta);
+			},
+			read: core.presence.read
+		},
+		inspect: core.inspect,
+		stream(sessionId, opts) {
+			return pollingStream((afterIndex) => core.readRange(sessionId, afterIndex), opts?.startAfter !== void 0 ? { startAfter: opts.startAfter } : {});
+		},
+		async close() {}
+	};
+}
+//#endregion
+export { redisHttp };

package/dist/store-redis.d.ts

@@ -0,0 +1,37 @@
+import { c as IdSource, i as Clock, t as A2Store } from "./store-C3sNAaBT.js";
+//#region src/store-redis.d.ts
+/**
+ * The minimal client this backend needs — `ioredis` matches it
+ * structurally. `call` issues any command; `duplicate` opens the one
+ * shared subscriber connection; `on` delivers its pub/sub messages.
+ *
+ * The client must restore its subscriptions after a reconnect
+ * (`ioredis` does). One that doesn't stays correct — the safety
+ * re-read delivers everything — but every live feed silently degrades
+ * to safety-read latency from that point on.
+ */
+type RedisConnection = {
+  call(command: string, ...args: Array<string | number>): Promise<unknown>;
+  duplicate(): RedisConnection;
+  on(event: "message", listener: (channel: string, message: string) => void): unknown;
+  disconnect(): void;
+};
+type RedisStoreOptions = {
+  /** Creates an `ioredis` client lazily (optional peer dep `ioredis`). */
+  url?: string | undefined;
+  /** Bring your own client — anything `call`/`duplicate`/`on`/`disconnect`. */
+  client?: RedisConnection;
+  /** Key prefix — isolates multiple apps on one Redis. Default `'a2'`. */
+  keyPrefix?: string;
+  /** Injectable clock — every stored timestamp comes from here. */
+  clock?: Clock;
+  /** Injectable id source for generated event ids. */
+  ids?: IdSource;
+};
+type RedisStore = A2Store & {
+  /** Disconnect the command client and the shared subscriber. */
+  close(): Promise<void>;
+};
+declare function redis(options?: RedisStoreOptions): RedisStore;
+//#endregion
+export { RedisConnection, RedisStore, RedisStoreOptions, redis };

package/dist/store-redis.js

@@ -0,0 +1,298 @@
+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 "./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;
+	const prefix = options.keyPrefix ?? "a2";
+	if (!options.client && !options.url) throw new TypeError("redis() needs a url or an injected client");
+	const connection = retryableLazy(async () => {
+		if (options.client) return options.client;
+		return new (await (import("ioredis").catch(() => {
+			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 presenceChannel = (ns) => `${prefix}:${ns}:presence`;
+	const core = createRedisStoreCore({
+		call: async (command, ...args) => {
+			return (await client()).call(command, ...args);
+		},
+		clock,
+		ids,
+		keyPrefix: prefix,
+		notify: (sessionId, count) => {
+			client().then((c) => c.call("publish", notifyChannel(sessionId), count)).catch(() => {});
+		}
+	});
+	let severed = false;
+	let subscriber = null;
+	/** channel → parked-feed wake-ups, armed before each catch-up read. */
+	const wakers = /* @__PURE__ */ new Map();
+	/** channel → refcounted subscription held for each live iterator. */
+	const subscriptions = /* @__PURE__ */ new Map();
+	/**
+	* channel → last presence-marker refresh, throttling the SET.
+	* Deliberately real time (`Date.now()`), not the injected clock:
+	* the marker's PX expiry runs on server real time, and the throttle
+	* must tick with the TTL it refreshes or time-traveling tests would
+	* desync the two. Process-local and never stored, so the injected
+	* 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, message) => {
+				const set = wakers.get(channel);
+				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) {
+			existing.refs += 1;
+			try {
+				await existing.ready;
+			} catch (err) {
+				existing.refs -= 1;
+				throw err;
+			}
+			return;
+		}
+		const lease = {
+			refs: 1,
+			ready: gatedSubscriber().then((conn) => conn.call("subscribe", channel))
+		};
+		subscriptions.set(channel, lease);
+		try {
+			await lease.ready;
+		} catch (err) {
+			if (subscriptions.get(channel) === lease) subscriptions.delete(channel);
+			throw err;
+		}
+	};
+	const releaseChannel = (channel) => {
+		const lease = subscriptions.get(channel);
+		if (!lease) return;
+		lease.refs -= 1;
+		if (lease.refs > 0) return;
+		subscriptions.delete(channel);
+		watchedRefreshedAt.delete(channel);
+		gatedSubscriber().then((conn) => conn.call("unsubscribe", channel)).catch(() => {});
+	};
+	const armWaker = (channel) => {
+		let wake;
+		const wakeup = new Promise((resolve) => {
+			wake = resolve;
+		});
+		let set = wakers.get(channel);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			wakers.set(channel, set);
+		}
+		set.add(wake);
+		return {
+			wakeup,
+			wake,
+			disarm: () => {
+				set.delete(wake);
+				if (set.size === 0) wakers.delete(channel);
+			}
+		};
+	};
+	return {
+		append: core.append,
+		read: core.read,
+		claimAvailable: core.claimAvailable,
+		renewClaims: core.renewClaims,
+		completeAttempt: core.completeAttempt,
+		failAttempt: core.failAttempt,
+		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 startAfter = opts?.startAfter ?? 0;
+			const channel = notifyChannel(sessionId);
+			return { [Symbol.asyncIterator]() {
+				let last = startAfter;
+				let buffer = [];
+				let closed = false;
+				let subscribed = false;
+				let pending = null;
+				let interrupt = null;
+				const release = () => {
+					if (!subscribed) return;
+					subscribed = false;
+					releaseChannel(channel);
+				};
+				return {
+					async next() {
+						for (;;) {
+							if (closed) {
+								release();
+								return {
+									value: void 0,
+									done: true
+								};
+							}
+							const row = buffer.shift();
+							if (row) {
+								last = row.index;
+								return {
+									value: row,
+									done: false
+								};
+							}
+							if (severed) {
+								release();
+								throw new A2Error("STORE_UNAVAILABLE", "the store was closed");
+							}
+							const waker = armWaker(channel);
+							interrupt = waker.wake;
+							try {
+								if (!subscribed) {
+									await acquireChannel(channel);
+									subscribed = true;
+								}
+								const markedAt = watchedRefreshedAt.get(channel) ?? 0;
+								if (Date.now() - markedAt >= NOTIFY_TIMINGS.safetyReadMs) {
+									watchedRefreshedAt.set(channel, Date.now());
+									await core.markWatched(sessionId, NOTIFY_TIMINGS.safetyReadMs * 3);
+								}
+								buffer = await core.readEvents(sessionId, last);
+								if (buffer.length === 0 && !closed && !severed) {
+									pending = defaultSleep(NOTIFY_TIMINGS.safetyReadMs);
+									await Promise.race([waker.wakeup, pending.promise]);
+									pending.cancel();
+									pending = null;
+								}
+							} catch (err) {
+								release();
+								if (closed) return {
+									value: void 0,
+									done: true
+								};
+								if (err instanceof A2Error) throw err;
+								throw new A2Error("STORE_UNAVAILABLE", "redis store operation failed", { cause: err });
+							} finally {
+								waker.disarm();
+								interrupt = null;
+							}
+						}
+					},
+					async return() {
+						closed = true;
+						pending?.cancel();
+						interrupt?.();
+						release();
+						return {
+							value: void 0,
+							done: true
+						};
+					}
+				};
+			} };
+		},
+		async close() {
+			severed = true;
+			for (const set of wakers.values()) for (const wake of set) wake();
+			if (subscriber) (await subscriber.catch(() => null))?.disconnect();
+			const current = connection.peek();
+			if (!current) return;
+			(await current.catch(() => null))?.disconnect();
+		}
+	};
+}
+//#endregion
+export { redis };

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 { t as pollingStream } from "./log-polling-6COoN60V.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.
  */