experimental-a2 0.3.0 → 0.4.0

package/dist/wire-DCUZBUlT.js

@@ -0,0 +1,222 @@
+import { t as A2Error } from "./errors-BQuJpe82.js";
+import { g as nullProtoRecord } from "./internal-aEotMzu_.js";
+//#region src/wire.ts
+/**
+* The wire format shared by experimental-a2/http (server side) and experimental-a2/client
+* (browser side): events as JSON with ISO timestamps, and the A2Error
+* envelope. Internal module — both entry points re-export what's
+* public.
+*/
+function eventToWire(event) {
+	return {
+		id: event.id,
+		type: event.type,
+		payload: event.payload,
+		index: event.index,
+		sessionId: event.sessionId,
+		createdAt: event.createdAt.toISOString()
+	};
+}
+function eventFromWire(wire) {
+	return {
+		id: wire.id,
+		type: wire.type,
+		payload: wire.payload,
+		index: wire.index,
+		sessionId: wire.sessionId,
+		createdAt: new Date(wire.createdAt)
+	};
+}
+function isWireEvent(value) {
+	if (value === null || typeof value !== "object") return false;
+	const v = value;
+	return typeof v["id"] === "string" && typeof v["type"] === "string" && typeof v["index"] === "number" && typeof v["sessionId"] === "string" && typeof v["createdAt"] === "string";
+}
+function presencePatchToWire(patch) {
+	return {
+		participant: patch.participant,
+		values: patch.values,
+		seen: patch.seen,
+		at: patch.at.toISOString()
+	};
+}
+function presencePatchFromWire(wire) {
+	return {
+		participant: wire.participant,
+		values: wire.values,
+		seen: wire.seen,
+		at: new Date(wire.at)
+	};
+}
+function presenceSnapshotToWire(snapshot) {
+	const wire = nullProtoRecord();
+	for (const [participant, fields] of Object.entries(snapshot.snapshot)) {
+		const wireFields = nullProtoRecord();
+		for (const [field, entry] of Object.entries(fields)) {
+			if (entry === void 0) continue;
+			wireFields[field] = {
+				value: entry.value,
+				seen: entry.seen,
+				at: entry.at.toISOString()
+			};
+		}
+		wire[participant] = wireFields;
+	}
+	return { snapshot: wire };
+}
+function presenceSnapshotFromWire(wire) {
+	const map = nullProtoRecord();
+	for (const [participant, fields] of Object.entries(wire.snapshot)) {
+		const revived = nullProtoRecord();
+		for (const [field, entry] of Object.entries(fields)) revived[field] = {
+			value: entry.value,
+			seen: entry.seen,
+			at: new Date(entry.at)
+		};
+		map[participant] = revived;
+	}
+	return { snapshot: map };
+}
+function isWirePresencePatch(value) {
+	if (value === null || typeof value !== "object") return false;
+	const v = value;
+	return typeof v["participant"] === "string" && v["values"] !== null && typeof v["values"] === "object" && !Array.isArray(v["values"]) && typeof v["seen"] === "number" && typeof v["at"] === "string";
+}
+function isWirePresenceSnapshot(value) {
+	if (value === null || typeof value !== "object") return false;
+	const v = value;
+	return v["snapshot"] !== null && typeof v["snapshot"] === "object" && !Array.isArray(v["snapshot"]);
+}
+const ERROR_STATUS = {
+	INVALID_PAYLOAD: 400,
+	UNKNOWN_EVENT_TYPE: 400,
+	PARTIAL_DUPLICATE_BATCH: 400,
+	SUPERSEDED_ATTEMPT: 409,
+	CLAIM_EXPIRED: 409,
+	STORE_UNAVAILABLE: 503,
+	STORE_NOT_CONFIGURED: 500,
+	UNKNOWN_PRESENCE_FIELD: 400,
+	PRESENCE_NOT_SUPPORTED: 500
+};
+function errorStatus(code) {
+	return ERROR_STATUS[code];
+}
+function errorToWire(error) {
+	const body = { error: {
+		code: error.code,
+		message: error.message
+	} };
+	if (error.details !== void 0) body.error.details = error.details;
+	return body;
+}
+/** Rebuild an A2Error from a wire body; null if the body isn't one. */
+function errorFromWire(body) {
+	if (body === null || typeof body !== "object") return null;
+	const err = body.error;
+	if (err === null || typeof err !== "object") return null;
+	const { code, message, details } = err;
+	if (typeof code !== "string" || !Object.hasOwn(ERROR_STATUS, code)) return null;
+	return new A2Error(code, String(message ?? code), { details });
+}
+const SOCKET_PING_FRAME = JSON.stringify({ kind: "ping" });
+/** One stream item as a socket frame — `sseResponse`'s framing over
+* the same codecs, with `kind` instead of an SSE event name. */
+function socketFrameFor(item) {
+	if ("snapshot" in item) return JSON.stringify({
+		kind: "presence-snapshot",
+		...presenceSnapshotToWire(item)
+	});
+	if ("participant" in item) return JSON.stringify({
+		kind: "presence",
+		...presencePatchToWire(item)
+	});
+	return JSON.stringify({
+		kind: "event",
+		...eventToWire(item)
+	});
+}
+function socketAckFor(req, events) {
+	return JSON.stringify({
+		kind: "ack",
+		req,
+		events: events.map(eventToWire)
+	});
+}
+function socketErrorAckFor(req, error) {
+	return JSON.stringify({
+		kind: "ack",
+		req,
+		...errorToWire(error)
+	});
+}
+function parseSocketFrame(data) {
+	let parsed;
+	try {
+		parsed = JSON.parse(data);
+	} catch {
+		return null;
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+	const frame = parsed;
+	switch (frame["kind"]) {
+		case "ping": return { kind: "ping" };
+		case "event": {
+			if (!isWireEvent(parsed)) return null;
+			const { id, type, payload, index, sessionId, createdAt } = parsed;
+			return {
+				kind: "event",
+				event: {
+					id,
+					type,
+					payload,
+					index,
+					sessionId,
+					createdAt
+				}
+			};
+		}
+		case "presence": {
+			if (!isWirePresencePatch(parsed)) return null;
+			const { participant, values, seen, at } = parsed;
+			return {
+				kind: "presence",
+				patch: {
+					participant,
+					values,
+					seen,
+					at
+				}
+			};
+		}
+		case "presence-snapshot":
+			if (!isWirePresenceSnapshot(parsed)) return null;
+			return {
+				kind: "presence-snapshot",
+				snapshot: { snapshot: parsed.snapshot }
+			};
+		case "ack": {
+			const req = frame["req"];
+			if (typeof req !== "number") return null;
+			const events = frame["events"];
+			if (Array.isArray(events) && events.every(isWireEvent)) return {
+				kind: "ack",
+				req,
+				events
+			};
+			const error = errorFromWire(parsed);
+			if (error) return {
+				kind: "ack",
+				req,
+				error
+			};
+			return {
+				kind: "ack",
+				req,
+				error: new A2Error("STORE_UNAVAILABLE", "unintelligible ack")
+			};
+		}
+		default: return null;
+	}
+}
+//#endregion
+export { socketFrameFor as _, eventFromWire as a, isWirePresencePatch as c, presencePatchFromWire as d, presencePatchToWire as f, socketErrorAckFor as g, socketAckFor as h, errorToWire as i, isWirePresenceSnapshot as l, presenceSnapshotToWire as m, errorFromWire as n, eventToWire as o, presenceSnapshotFromWire as p, errorStatus as r, isWireEvent as s, SOCKET_PING_FRAME as t, parseSocketFrame as u };

package/docs/01-quickstart.mdx

@@ -40,7 +40,7 @@ implements it below, the reducer derives from it in step 6, and when a
 browser enters the picture it types the client too.
 
 There's no database setup in development: A2 stores events in SQLite at
-`.a2/dev.db`, so state survives restarts. Tests get an in-memory log.
+`.a2/dev.db`, so state survives restarts. Tests get an in-memory store.
 Production wants an explicit backend; see
 [Going to production](/guides/production).
 
@@ -115,7 +115,7 @@ The payload is validated against the schema before anything is written;
 send garbage and you get `INVALID_PAYLOAD` back, with the issues.
 
 When the append returns, the event is durably in the log and A2 has started the
-`created` handler inline. In production, queue-backed recovery wakes pending
+`created` handler inline. In production, a queue-backed scheduler wakes pending
 work after a failure or process death. See [Durability](/concepts/durability)
 for the exact contract.
 
@@ -208,6 +208,6 @@ infrastructure.
     The context object, chaining, ordering, and re-runs.
   </Card>
   <Card title="Going to production" href="/guides/production" icon="rocket">
-    Postgres, queue-backed recovery, and dead-letter resolution.
+    Postgres, a queue-backed scheduler, and dead-letter resolution.
   </Card>
 </CardGroup>

package/docs/concepts/01-contracts.mdx

@@ -45,6 +45,11 @@ The contract names the complete vocabulary. What happens on each event is
 defined where the contract is served. [Reducers](/concepts/state) define what
 things look like right now.
 
+A contract can also declare `presence`, a second vocabulary for ephemeral
+participant state (cursors, typing, live progress) that is replicated but
+never stored in the log. Events are facts; presence is the moment. See
+[Presence](/guides/presence).
+
 :::tip
 Events are facts, so name them in past tense: `created`, `expired`,
 `shop.notified`. If a name reads like a command (`notifyShop`), it's
@@ -55,17 +60,17 @@ convention, not a namespace.
 ## Serving a contract
 
 Storage and optional handlers bind to the contract with `createServer` from
-`experimental-a2/server`, the entry point that is allowed to touch a log backend
+`experimental-a2/server`, the entry point that is allowed to touch a store backend
 (and the one that fails loudly if a browser bundle ever imports it):
 
 ```ts server/orders.ts
 import { createServer } from 'experimental-a2/server'
-import { postgres } from 'experimental-a2/log-postgres'
+import { postgres } from 'experimental-a2/store-postgres'
 import { orders } from '@/contracts'
 
 export const ordersServer = createServer({
   contract: orders,
-  log: postgres({ connectionString: process.env.DATABASE_URL }),
+  store: postgres({ connectionString: process.env.DATABASE_URL }),
   handlers: {
     created: async ({ event }) => {
       // your side effect, then:
@@ -82,13 +87,13 @@ objects into `handlers`.
 
 | Entry point       | Backend   | Use it for                                |
 | ----------------- | --------- | ----------------------------------------- |
-| `experimental-a2/log-postgres` | Postgres  | Production                                 |
-| `experimental-a2/log-sqlite`   | SQLite    | Development: the default, at `.a2/dev.db`  |
-| `experimental-a2/log-memory`   | In-memory | Tests: the default when `NODE_ENV=test`    |
+| `experimental-a2/store-postgres` | Postgres  | Production                                 |
+| `experimental-a2/store-sqlite`   | SQLite    | Development: the default, at `.a2/dev.db`  |
+| `experimental-a2/store-memory`   | In-memory | Tests: the default when `NODE_ENV=test`    |
 
-When you omit `log`, development gets SQLite (state survives `next dev`
+When you omit `store`, development gets SQLite (state survives `next dev`
 restarts) and tests get memory. Production gets an error: the server
-throws `LOG_NOT_CONFIGURED` at startup rather than guess where your
+throws `STORE_NOT_CONFIGURED` at startup rather than guess where your
 events should live. A failed boot beats events written to a filesystem
 that evaporates.
 
@@ -127,11 +132,11 @@ progress. Collections, joins, search, and constraints across many records
 usually belong in an application database. See
 [A2 and your database](/guides/application-data).
 
-## One more option: recovery
+## One more option: a scheduler
 
-Servers accept a `recovery` option. When a top-level append leaves or finds
-pending handler work, recovery arms a durable, delayed drain. The handler
-starts without waiting for recovery, and a successful initial arm is durable
+Servers accept a `scheduler` option. When a top-level append leaves or finds
+pending handler work, the scheduler arms a durable, delayed drain. The handler
+starts without waiting for the scheduler, and a successful initial arm is durable
 before `append` returns. Event types without handlers settle during append and
-create no recovery work when the session has no older backlog. Covered in
+create no scheduler work when the session has no older backlog. Covered in
 [Going to production](/guides/production).

package/docs/concepts/02-handlers.mdx

@@ -32,16 +32,16 @@ module that registered it was never imported.
 Handlers are optional per event type. An event without one still gets its full
 place in the log. You can read it with `history()`, fold it into state, and
 stream it to a live client. A2 settles it in the append transaction, with no
-dispatch claim or recovery message.
+dispatch claim or scheduler message.
 
-```ts server/order-log.ts
+```ts server/order-history.ts
 import { createServer } from 'experimental-a2/server'
-import { postgres } from 'experimental-a2/log-postgres'
+import { postgres } from 'experimental-a2/store-postgres'
 import { orders } from '@/contracts'
 
-export const orderLog = createServer({
+export const orderHistory = createServer({
   contract: orders,
-  log: postgres({ connectionString: process.env.DATABASE_URL }),
+  store: postgres({ connectionString: process.env.DATABASE_URL }),
 })
 ```
 
@@ -58,7 +58,7 @@ Every handler receives one argument:
 | `ctx.event`   | The triggering event: `{ id, type, payload, index, sessionId, createdAt }`. |
 | `ctx.attempt` | The durable 1-based dispatch claim for this event. |
 | `ctx.session` | This session's handle: `id`, `append`, `history`, `state`, and `stream`. |
-| `ctx.signal`  | An `AbortSignal`, active only with `abortOn`. See [Cancellation](/guides/cancellation). |
+| `ctx.signal`  | An `AbortSignal`. Fires when the attempt's lease lapses (`CLAIM_EXPIRED`), when a recovered run provably supersedes it (`SUPERSEDED_ATTEMPT`), and on matching `abortOn` events. See [Cancellation](/guides/cancellation). |
 
 `ctx.attempt` starts at `1` and increments on every durable claim. It may skip
 when a process dies between the claim and handler entry.
@@ -239,7 +239,7 @@ export const drivers = createServer({
 })
 ```
 
-The resolved lane is stored with the event when it is appended. Recovery uses
+The resolved lane is stored with the event when it is appended. The scheduler uses
 that stored value, so a deployment cannot reinterpret pending work. Lane keys
 are scoped to one session. They are not distributed locks across sessions.
 

package/docs/concepts/03-durability.mdx

@@ -5,13 +5,13 @@ description: Appends are effectively-once, handlers are at-least-once, and retri
 
 ## The contract
 
-- **Appends are effectively-once.** Event ids deduplicate writes. When
-  `append` returns, the event is in the log.
+- **Appends are effectively-once.** Event ids deduplicate writes. A batch commits
+  before its handlers start; they may start before `append` resolves.
 - **Handlers are at-least-once.** They may run again after a crash, so
   [side effects use idempotency keys](/concepts/handlers#handlers-can-run-twice).
-- **The log stays ordered.** Every session has one immutable event order.
-- **Handlers are concurrent by default.** Independent events can run at the
-  same time. Events in the same lane run one at a time in log order.
+- **The log stays ordered.** Every session has one immutable append order.
+- **Handlers are concurrent by default.** Log order does not serialize them.
+  Only events in the same lane run one at a time in log order.
 
 ## The correctness model
 
@@ -44,7 +44,7 @@ processed marker says what finished. The watchdog says when to look again.
 ```
 
 A queue message identifies a session. Every wakeup runs the same drain, and
-the log decides what remains. Recovery and explicit `server.drain()` inspect
+the log decides what remains. The scheduler and explicit `server.drain()` inspect
 the full session. Reads never dispatch handlers.
 
 :::note[Recovery is not an event]
@@ -160,25 +160,25 @@ limit or priority queue. Use lanes for ordered mutual exclusion. Put capacity
 limits near the constrained resource, such as an API client, connection pool,
 or execution runtime.
 
-## Append and recovery
+## Append and scheduling
 
-A top-level append commits first. When pending handler work remains, it starts
-the inline drain and optional watchdog arm in parallel. The drain never waits
-for the queue. Append joins the arm for at most two seconds; on failure, its
-telemetry span records `a2.append.armed = false`, but committed work continues.
-`ctx.session.append` rides the active session drain and adds no arm. Returned
-events enter the log as part of completion, then become eligible immediately.
+A top-level append commits first. Only then does A2 start the inline drain and
+optional watchdog arm in parallel. A handler may start before `append` returns;
+the call joins the arm for at most two seconds, not the handler. The drain never
+waits for the queue. Arm failure records `a2.append.armed = false`, while
+`ctx.session.append` rides the active drain and adds no arm. Returned events
+enter the log with completion, then become eligible immediately.
 
 `session.append.dispatch(...events)` chooses the other execution path. It
 commits first, skips the current invocation's inline drain, and awaits an
-immediate recovery send. It requires configured recovery. Queue delivery then
+immediate scheduler send. It requires a configured scheduler. Queue delivery then
 claims the same durable events through the normal drain path. If the send
 fails, retry with the same explicit event IDs; the append itself may already
-have committed. The recovery message is a wakeup, not worker affinity. An
+have committed. The scheduler message is a wakeup, not worker affinity. An
 already-active drain may claim the new work first.
 
 An event type without a handler settles in the append transaction with no
-dispatch attempt. It starts no drain or recovery arm when the session has no
+dispatch attempt. It starts no drain or scheduler arm when the session has no
 older pending work. If older handled work is pending, the append still wakes
 the session-wide healing path.
 
@@ -194,7 +194,7 @@ The edge is part of the existing append batch and survives process restarts.
 The stored event also carries `lane`, `firstClaimedAt`, `lastClaimedAt`,
 `claimHolder`, `claimExpiresAt`, `lastFailedAt`, `lastFailedAttempt`,
 `processedAt`, `processedByAttempt`, and `returnedEventIds`. Timestamps are
-adapter clock values captured for atomic log operations, not exact database
+adapter clock values captured for atomic store operations, not exact database
 commit times. A stale worker cannot rewrite a newer completion. The durable
 log can rebuild a causal forest and useful lifecycle boundaries without one
 row per attempt.
@@ -299,9 +299,9 @@ Resolution is manual: fix and retry, or skip.
 | Situation | Result |
 | --- | --- |
 | Process dies before the first arm is durable | Retry with the same ids, append again later, or call `drain()`. |
-| No recovery configured | A later top-level append or explicit `drain()` wakes the session. Reads never do. |
-| Recovery dies after claiming but before arming | Its unacknowledged queue delivery is the slower fallback. |
-| Log backend unavailable | Safe progress stops until it returns. |
+| No scheduler configured | A later top-level append or explicit `drain()` wakes the session. Reads never do. |
+| Scheduler invocation dies after claiming but before arming | Its unacknowledged queue delivery is the slower fallback. |
+| Store backend unavailable | Safe progress stops until it returns. |
 | External effect succeeds before A2 completion | The handler may repeat it. Use idempotency or external fencing. |
 
 ## What append never throws for
@@ -311,4 +311,4 @@ identical batch retry returns rows with the same ids. A mixed batch throws
 [`PARTIAL_DUPLICATE_BATCH`](/reference/errors).
 
 For the queue route and deployment configuration, see
-[Going to production](/guides/production#2-add-recovery).
+[Going to production](/guides/production#2-add-a-scheduler-for-handlers).

package/docs/concepts/04-state.mdx

@@ -13,7 +13,8 @@ const events = await ordersServer.session(orderId).history()
 Everything that happened in this session, oldest first. Always the raw log,
 never a summary, never a snapshot. This is the session's audit trail and
 debugging story, and it is also fine to use inside handlers for questions like
-"did the shop already start?"
+"did the shop already start?" Pass inclusive `gte` or `lte` indexes to read a
+bounded slice.
 
 ## Reducers
 
@@ -86,24 +87,20 @@ export const ordersServer = createServer({
 })
 ```
 
-A reducer is a name (its identity, more on that below) plus the values that
-anchor it: `initialState` (the seed), an optional `stateSchema`, and the
-pure `fold`, `(state, event) => state`. It's derived *from* the
-contract, so the events type themselves; the two-step shape is
-deliberate: the first call fixes the state and event types, and
-`.fold()` receives fully concrete ones. No type arguments, no
-annotations, and literal unions (like the `z.enum` status above) survive
-the fold intact. `state()` folds the session's events through it and
-returns the result, along with `index`: the log position the state
-reflects. The browser uses that index to resume a live stream exactly
-where server-rendered state left off. See [Live UI](/guides/react).
-
-The snapshot and its remaining event tail come back in one consistent log
-operation. A missing snapshot reads the full log. A snapshot rejected by
-`stateSchema`, or a failed cache read, falls back to the full log and rebuilds
-from truth. `state()` is observational: it never runs handlers or waits for
-pending work to finish. Inside a handler, the returned index includes the
-triggering event and may include later events that committed before the read.
+A reducer is a name (its identity, more on that below), `initialState`, an
+optional `stateSchema`, and the pure `fold`, `(state, event) => state`. It is
+derived from the contract, so the events type themselves; the two-step shape
+fixes the state and event types before `.fold()` receives them. No type
+arguments or annotations are needed, and literal unions survive the fold.
+`state()` returns the result with `index`, the last log position included. The
+fold includes every event through that index and none after it. The browser
+resumes its live stream from that boundary. See [Live UI](/guides/react).
+
+The snapshot and its remaining event tail come back in one consistent store
+operation. A missing, invalid, or unreadable snapshot rebuilds from the full log.
+`state()` is observational: it never runs handlers or waits for pending work.
+Its index marks committed history, not handler completion. Inside a handler it
+includes the trigger and may include later events committed before the read.
 
 The read and a following `ctx.session.append(name, ...events)` are separate
 operations. Concurrent appends and retries can move the frontier between them.
@@ -121,7 +118,7 @@ cache](/guides/local-first): a cached fold that fails the schema is
 discarded and refolded, catching shape drift a stale `name` can't.
 
 Note what these modules import: schemas and `experimental-a2`. Never `experimental-a2/server`,
-never a log backend. Contract and reducer are isomorphic by
+never a store backend. Contract and reducer are isomorphic by
 construction; the browser runs the same reducer. More on the split in
 [Live UI](/guides/react#keep-the-backend-out-of-the-bundle). (In a
 server-only app you can keep the contract next to `createServer`
@@ -129,7 +126,7 @@ instead of in its own file.)
 
 ## Snapshots are a cache
 
-Folding a long session on every read would get slow, so the log backend
+Folding a long session on every read would get slow, so the store backend
 caches folded state as a snapshot. You never interact with it, except for
 one string.