experimental-a2 0.2.0 → 0.4.0

package/docs/reference/02-errors.mdx

@@ -36,11 +36,15 @@ export async function POST(req: Request) {
 | ------------------------- | ------------------------------------------------------------------ | --------- |
 | `INVALID_PAYLOAD`         | a payload fails its schema; nothing was written, and `details` carries the issues ([Standard Schema](https://standardschema.dev) format) | no        |
 | `UNKNOWN_EVENT_TYPE`      | an event type isn't in the contract's `events` map                  | no        |
+| `UNKNOWN_PRESENCE_FIELD`  | a presence field isn't in the contract's `presence` map             | no        |
+| `PRESENCE_NOT_SUPPORTED`  | the contract declares `presence` but the configured store has no presence capability (thrown at construction; for environment-resolved stores, deferred to the first store use) | no |
 | `PARTIAL_DUPLICATE_BATCH` | a batch mixed already-appended and fresh events                     | no        |
-| `LOG_UNAVAILABLE`         | the log backend failed; nothing was written, original error as `cause` | **yes**   |
-| `LOG_NOT_CONFIGURED`      | production boot with no `log` configured (during `next build` page collection, deferred to first use) | no |
+| `SUPERSEDED_ATTEMPT`      | a handler append from an attempt a recovery claim has replaced; nothing was written, the successor owns the event. Also the abort reason on that handler's `ctx.signal` | no        |
+| `CLAIM_EXPIRED`           | never thrown; only the `ctx.signal` abort reason when the attempt's lease lapsed without renewal (assumed loss, decided locally, not proof) | no        |
+| `STORE_UNAVAILABLE`       | the store backend failed; nothing was written, original error as `cause` | **yes**   |
+| `STORE_NOT_CONFIGURED`    | production boot with no `store` configured (during `next build` page collection, deferred to first use) | no |
 
-Retryability is derivable from the code. `LOG_UNAVAILABLE` is the only one
+Retryability is derivable from the code. `STORE_UNAVAILABLE` is the only one
 worth retrying; the rest are deterministic caller bugs, and retrying them
 is wasted work.
 
@@ -69,9 +73,10 @@ The push route serializes an `A2Error` as:
 ```
 
 with a mapped status: `INVALID_PAYLOAD`, `UNKNOWN_EVENT_TYPE`, and
-`PARTIAL_DUPLICATE_BATCH` are 400; `LOG_UNAVAILABLE` is 503.
+`PARTIAL_DUPLICATE_BATCH` are 400; `SUPERSEDED_ATTEMPT` is 409;
+`STORE_UNAVAILABLE` is 503.
 
 The client's `push` deserializes the body back into an `A2Error`, so client
 and server code branch on identical codes. `push` auto-retries only
-`LOG_UNAVAILABLE`. The serializer pair ships in `experimental-a2/http`, alongside
+`STORE_UNAVAILABLE`. The serializer pair ships in `experimental-a2/http`, alongside
 `parsePushBody` and `sseResponse`.

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "experimental-a2",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Durable sync and reactions for things with a lifecycle: one event log, derived state, and live client per session.",
   "license": "MIT",
   "type": "module",
+  "bin": {
+    "a2": "./dist/cli-bin.js"
+  },
   "sideEffects": false,
   "engines": {
     "node": ">=22.13"
@@ -36,21 +39,29 @@
       "default": "./dist/ai-server.js"
     },
     "./http": "./dist/http.js",
-    "./log-memory": "./dist/log-memory.js",
-    "./log-sqlite": "./dist/log-sqlite.js",
-    "./log-postgres": "./dist/log-postgres.js",
-    "./log-redis": "./dist/log-redis.js",
-    "./recovery-vercel": "./dist/recovery-vercel.js",
+    "./store-memory": "./dist/store-memory.js",
+    "./store-sqlite": "./dist/store-sqlite.js",
+    "./store-postgres": "./dist/store-postgres.js",
+    "./store-redis": "./dist/store-redis.js",
+    "./store-redis-http": "./dist/store-redis-http.js",
+    "./scheduler-qstash": "./dist/scheduler-qstash.js",
+    "./scheduler-vercel": "./dist/scheduler-vercel.js",
     "./cache-indexeddb": "./dist/cache-indexeddb.js",
     "./otel": "./dist/otel.js",
+    "./devtools": "./dist/devtools.js",
     "./devtools/server": {
       "browser": "./dist/devtools-server.browser.js",
       "default": "./dist/devtools-server.js"
     },
+    "./testing": {
+      "browser": "./dist/testing.browser.js",
+      "default": "./dist/testing.js"
+    },
     "./package.json": "./package.json"
   },
   "peerDependencies": {
     "@opentelemetry/api": "^1.9.0",
+    "@upstash/qstash": "^2.11.0",
     "@vercel/queue": "*",
     "ai": "^7.0.0",
     "ioredis": "^5.4.0",
@@ -61,6 +72,9 @@
     "@opentelemetry/api": {
       "optional": true
     },
+    "@upstash/qstash": {
+      "optional": true
+    },
     "@vercel/queue": {
       "optional": true
     },
@@ -79,12 +93,15 @@
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.3.14",
+    "@upstash/qstash": "^2.11.3",
     "ai": "^7.0.58",
     "ioredis": "^5.9.0",
     "@opentelemetry/api": "^1.9.0",
     "@types/pg": "^8.15.0",
+    "@types/ws": "^8.18.1",
     "@vercel/queue": "^0.2.0",
     "pg": "^8.16.0",
+    "ws": "^8.21.3",
     "@testing-library/react": "^16.1.0",
     "@types/react": "^19.0.0",
     "esbuild": "^0.25.0",

package/dist/internal-D6wNxTck.js

@@ -1,36 +0,0 @@
-//#region src/internal.ts
-const serverInternals = /* @__PURE__ */ new WeakMap();
-/**
-* 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 = {
-	claimTtlMs: 5e3,
-	claimHeartbeatMs: 2e3,
-	recoveryGraceMs: 1e3,
-	recoveryArmTimeoutMs: 2e3
-};
-/**
-* Stream liveness knobs — the server-side SSE heartbeat and the
-* client-side stall watchdog. Paired by design: the client declares a
-* connection dead after roughly two missed heartbeats. Mutable only as
-* a white-box test seam; production always uses the defaults.
-*/
-/**
-* Poll cadence for the poll-based log streams (sqlite, postgres) —
-* owned, not configurable: adaptive polling removed the operator's
-* reason to tune it (the floor keeps active streams smooth; the
-* ceiling bounds idle cost). Mutable only as a white-box test seam so
-* suites don't wait out real idle gaps.
-*/
-const POLL_TIMINGS = {
-	activeFloorMs: 25,
-	idleCeilingMs: 250
-};
-const STREAM_TIMINGS = {
-	sseHeartbeatMs: 15e3,
-	stallTimeoutMs: 35e3
-};
-//#endregion
-export { serverInternals as i, POLL_TIMINGS as n, STREAM_TIMINGS as r, DRAIN_TIMINGS as t };

package/dist/log-memory.d.ts

@@ -1,11 +0,0 @@
-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. */
-  clock?: Clock;
-  /** Injectable id source for generated event ids. */
-  ids?: IdSource;
-};
-declare function memory(options?: MemoryLogOptions): A2Log;
-//#endregion
-export { MemoryLogOptions, memory };

package/dist/log-redis.d.ts

@@ -1,31 +0,0 @@
-import { c as IdSource, i as Clock, t as A2Log } from "./log-ldf5g8Cx.js";
-//#region src/log-redis.d.ts
-/**
- * The minimal client this backend needs — `ioredis` matches it
- * structurally. `call` issues any command; `duplicate` opens the
- * dedicated connection each blocking live feed holds.
- */
-type RedisConnection = {
-  call(command: string, ...args: Array<string | number>): Promise<unknown>;
-  duplicate(): RedisConnection;
-  disconnect(): void;
-};
-type RedisLogOptions = {
-  /** Creates an `ioredis` client lazily (optional peer dep `ioredis`). */
-  url?: string | undefined;
-  /** Bring your own client — anything `call`/`duplicate`/`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 RedisLog = A2Log & {
-  /** Disconnect the client and every live stream connection. */
-  close(): Promise<void>;
-};
-declare function redis(options?: RedisLogOptions): RedisLog;
-//#endregion
-export { RedisConnection, RedisLog, RedisLogOptions, redis };

package/dist/recovery-vercel.js

@@ -1,119 +0,0 @@
-import { i as serverInternals, t as DRAIN_TIMINGS } from "./internal-D6wNxTck.js";
-import { t as retryableLazy } from "./retryable-lazy-DZWmHpii.js";
-import { n as SYSTEM_CLOCK } from "./log-yJbXUf72.js";
-//#region src/recovery-vercel.ts
-/**
-* experimental-a2/recovery-vercel — queue-backed recovery over Vercel Queues.
-*
-* `vercelQueues()` returns an `A2Recovery` (a2-implementation.md §9):
-*
-* - `arm` rounds the requested watchdog time up to a one-second slot.
-*   One message per `(contract, session, dueAt)` coalesces appends,
-*   claim renewals and racing callbacks. `DuplicateMessageError` is
-*   success because that due-time slot is already durable.
-* - `handler(...servers)` is the delivery route: look up the server for
-*   the contract named in the message and drain it. Settled drains ack;
-*   contention arms a later watchdog before acking; handler failure keeps
-*   the current message and redelivers with backoff.
-*
-* `@vercel/queue` is an optional peer dependency, imported lazily. The
-* `transport` option is the injection seam — tests run a real little
-* in-memory queue through the same interface.
-*/
-/**
-* The "not settled yet" signal for a stalled handler — an expected state,
-* not a transport failure. The default transport classifies it in
-* `@vercel/queue`'s `retry` option and reschedules the delivery quietly
-* (`{ afterSeconds }` → visibility change → 200 response, no error log)
-* instead of letting it surface as a thrown 500. Busy deliveries use a
-* fresh watchdog instead. Custom transports should treat this class the
-* same way when their protocol has a polite reschedule.
-*/
-var RecoveryUnsettled = class extends Error {};
-/** Vercel Queues rejects shorter visibility changes. */
-const MIN_VISIBILITY_SECONDS = 30;
-/** Redelivery backoff for retry states: base, 2×, 4×… bounded. */
-const unsettledBackoffSeconds = (delaySeconds, deliveryCount) => Math.min(Math.max(delaySeconds * 2 ** Math.max(deliveryCount - 1, 0), MIN_VISIBILITY_SECONDS), 60);
-const vercelQueueTransport = async (delaySeconds) => {
-	const queue = await import("@vercel/queue").catch(() => {
-		throw new Error("experimental-a2/recovery-vercel needs the '@vercel/queue' package (optional peer dependency) — install it, or inject a transport");
-	});
-	return {
-		send: (topic, message, options) => queue.send(topic, message, options),
-		handleCallback: (handler) => queue.handleCallback(handler, {
-			visibilityTimeoutSeconds: MIN_VISIBILITY_SECONDS,
-			retry: (error, metadata) => error instanceof RecoveryUnsettled ? { afterSeconds: unsettledBackoffSeconds(delaySeconds, metadata.deliveryCount) } : void 0
-		}),
-		isDuplicate: (error) => error instanceof queue.DuplicateMessageError
-	};
-};
-function vercelQueues(options = {}) {
-	const topic = options.topic ?? "a2";
-	const delaySeconds = options.delaySeconds ?? 5;
-	const clock = options.clock ?? SYSTEM_CLOCK;
-	const transport = retryableLazy(() => options.transport ? Promise.resolve(options.transport) : vercelQueueTransport(delaySeconds)).get;
-	const sendWatchdog = async (opts) => {
-		const t = await transport();
-		const nowMs = clock.now().getTime();
-		const requestedDueAt = opts.dueAt ?? nowMs + delaySeconds * 1e3;
-		const dueAt = Math.ceil(requestedDueAt / 1e3) * 1e3;
-		const recoveryId = `${opts.contract}:${opts.sessionId}:watchdog:${dueAt}`;
-		try {
-			await t.send(topic, {
-				contract: opts.contract,
-				sessionId: opts.sessionId,
-				dueAt
-			}, {
-				delaySeconds: Math.max(0, Math.ceil((dueAt - nowMs) / 1e3)),
-				idempotencyKey: recoveryId
-			});
-		} catch (err) {
-			if (t.isDuplicate(err)) return;
-			throw err;
-		}
-	};
-	const successorDueAt = (message) => {
-		const minimumDueAt = clock.now().getTime() + DRAIN_TIMINGS.claimTtlMs + DRAIN_TIMINGS.recoveryGraceMs;
-		if (message.dueAt === void 0) return minimumDueAt;
-		const beats = Math.max(1, Math.ceil((minimumDueAt - message.dueAt) / DRAIN_TIMINGS.claimHeartbeatMs));
-		return message.dueAt + beats * DRAIN_TIMINGS.claimHeartbeatMs;
-	};
-	return {
-		async arm({ contract, sessionId, dueAt }) {
-			await sendWatchdog({
-				contract,
-				sessionId,
-				...dueAt !== void 0 ? { dueAt } : {}
-			});
-		},
-		handler(...servers) {
-			const byContract = /* @__PURE__ */ new Map();
-			for (const server of servers) byContract.set(server.contract.name, server);
-			return async (req) => {
-				return (await transport()).handleCallback(async (message) => {
-					const server = byContract.get(message.contract);
-					if (!server) throw new Error(`a2 recovery: no server for contract '${message.contract}' — pass it to recovery.handler(...)`);
-					const internals = serverInternals.get(server);
-					const nextDueAt = successorDueAt(message);
-					const result = internals ? await internals.recoveryDrain(message.sessionId, { recoveryDueAt: nextDueAt }) : {
-						...await server.drain(message.sessionId),
-						outcome: "unknown"
-					};
-					if (result.settled) return;
-					if (result.outcome === "busy") {
-						if (result.recoveryArm) await result.recoveryArm;
-						else await sendWatchdog({
-							contract: message.contract,
-							sessionId: message.sessionId,
-							dueAt: nextDueAt
-						});
-						return;
-					}
-					throw new RecoveryUnsettled(`a2 recovery: session '${message.sessionId}' of '${message.contract}' not settled yet (${result.outcome}) — rescheduled for redelivery`);
-				})(req);
-			};
-		}
-	};
-}
-//#endregion
-export { RecoveryUnsettled, vercelQueues };