experimental-a2 0.2.0 → 0.4.0

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 };

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

@@ -20,8 +20,7 @@ npm i experimental-a2 zod
 A contract is a name plus the events it understands: each key an event
 name, each value a schema. Zod here, though any
 [Standard Schema](https://standardschema.dev) validator works, and
-that's the entire upfront declaration. No state list, no transition
-table.
+that's the contract's complete declaration.
 
 ```ts server/orders.ts
 import { z } from 'zod'
@@ -41,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).
 
@@ -116,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.
 
@@ -209,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

@@ -41,10 +41,14 @@ schemas and their type helpers. The server implements it,
 [reducers](/concepts/state) derive from it, and the browser types its pushes
 off it. One artifact, shared by every side of the wire.
 
-And that's the entire declaration. No states, no transition table. What
-happens on each event is defined where the contract is served; what
-things look like right now is defined by [reducers](/concepts/state). The
-contract just names the vocabulary.
+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`,
@@ -56,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:
@@ -83,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.
 
@@ -128,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
 
@@ -43,10 +43,9 @@ processed marker says what finished. The watchdog says when to look again.
 +-------------+   +-------------------+
 ```
 
-A queue message names a session. It carries no event index or continuation
-state. Every wakeup runs the same drain, and the log decides what remains.
-Recovery and explicit `server.drain()` inspect the full session. Reads never
-dispatch handlers.
+A queue message identifies a session. Every wakeup runs the same drain, and
+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]
 A2 does not append `recovered` or `continued`. Recovery retries the same event.
@@ -161,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.
 
@@ -195,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.
@@ -239,11 +238,9 @@ Four eight-second handlers returned one after another do not fit together in a
 | t29 | Handler 3 finishes; handler 4 starts | Events 1 through 3 processed |
 | t37 | Handler 4 finishes | Session settled |
 
-The retry restarts handler 3; it does not resume its old call.
-
-One handler that always exceeds a fresh invocation cannot finish this way. A2
-cannot checkpoint arbitrary async code. Split the work into smaller events or
-increase the function duration.
+The retry starts handler 3 again from its entry point. Keep each handler within
+a fresh invocation. Split longer work into smaller events or increase the
+function duration.
 
 ## Crash around a returned batch
 
@@ -302,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
@@ -314,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).