experimental-a2 0.1.0 → 0.3.0

package/dist/log-sqlite.js

@@ -1,7 +1,7 @@
 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 { n as pollingStream } from "./log-polling-DZ1MiKLg.js";
 import { mkdirSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { DatabaseSync } from "node:sqlite";

package/dist/recovery-vercel.js

@@ -1,4 +1,4 @@
-import { i as serverInternals, t as DRAIN_TIMINGS } from "./internal-D6wNxTck.js";
+import { a as serverInternals, t as DRAIN_TIMINGS } from "./internal-gCd5qMry.js";
 import { t as retryableLazy } from "./retryable-lazy-DZWmHpii.js";
 import { n as SYSTEM_CLOCK } from "./log-yJbXUf72.js";
 //#region src/recovery-vercel.ts

package/dist/{server-BWffWe5A.js → server-BcLa4RFL.js}

@@ -1,6 +1,6 @@
 import { n as validateSync } from "./validate-XKT4FSNn.js";
 import { n as asLogUnavailable, t as A2Error } from "./errors-BJRMd-h6.js";
-import { i as serverInternals, t as DRAIN_TIMINGS } from "./internal-D6wNxTck.js";
+import { a as serverInternals, t as DRAIN_TIMINGS } from "./internal-gCd5qMry.js";
 import { n as serverInspection } from "./inspection-E7qbD0Xj.js";
 import { t as retryableLazy } from "./retryable-lazy-DZWmHpii.js";
 //#region src/deterministic-id.ts
@@ -142,6 +142,9 @@ function nextClaimWindow() {
 function recoverySlot(dueAt) {
 	return Math.ceil(dueAt / 1e3) * 1e3;
 }
+function currentRecoverySlot(now) {
+	return Math.floor(now / 1e3) * 1e3;
+}
 /**
 * The namespace separator between machine name and session id in
 * storage. Machines sharing one log backend (the dev-default sqlite
@@ -321,13 +324,15 @@ function createServer(options) {
 	* the drain it schedules is created in the append's active context —
 	* with a real tracer, causal work remains connected.
 	*/
-	const appendCore = (sessionId, events, source, onAppended, cause, generatedIds) => telemetry.span("a2.append", {
+	const appendCore = (sessionId, events, source, mode, onAppended, cause, generatedIds) => telemetry.span("a2.append", {
 		"a2.contract": name,
 		"a2.session_id": sessionId,
 		"a2.append.source": source,
+		"a2.append.mode": mode,
 		"a2.append.types": events.map((e) => String(e.type)).join(","),
 		"a2.append.count": events.length
 	}, async (span) => {
+		if (mode === "dispatch" && !recovery) throw new TypeError("append.dispatch requires a configured recovery adapter");
 		assertSessionId(sessionId);
 		const validated = validateEvents(sessionId, events);
 		if (cause) for (const [index, event] of validated.entries()) event.cause = generatedIds?.[index] ? {
@@ -345,9 +350,11 @@ function createServer(options) {
 			throw asLogUnavailable(err);
 		}
 		const appended = rows.map(toPublic);
-		const initialRecoveryAt = shouldHealSession && recovery && source === "external" ? recoverySlot(nextClaimWindow().recoveryAtMs) : void 0;
+		const initialRecoveryAt = shouldHealSession && recovery && source === "external" && mode === "inline" ? recoverySlot(nextClaimWindow().recoveryAtMs) : void 0;
 		const initialArm = initialRecoveryAt !== void 0 ? startRecoveryArm(sessionId, initialRecoveryAt) : null;
-		if (shouldHealSession) onAppended(appended, initialRecoveryAt);
+		const dispatchArm = shouldHealSession && mode === "dispatch" ? startRecoveryArm(sessionId, currentRecoverySlot(Date.now())) : null;
+		if (shouldHealSession && mode === "inline") onAppended(appended, initialRecoveryAt);
+		if (dispatchArm) await dispatchArm;
 		if (initialArm) {
 			let timeout = null;
 			try {
@@ -472,7 +479,7 @@ function createServer(options) {
 					id
 				};
 			}));
-			return appendCore(publicSessionId, withIds, "handler", (_rows, recoveryDueAt) => scheduleDrain(publicSessionId, recoveryDueAt), {
+			return appendCore(publicSessionId, withIds, "handler", "inline", (_rows, recoveryDueAt) => scheduleDrain(publicSessionId, recoveryDueAt), {
 				index: trigger.index,
 				attempt
 			}, generatedIds);
@@ -786,18 +793,21 @@ function createServer(options) {
 			...recoveryArm ? { recoveryArm } : {}
 		};
 	});
+	const appendExternal = async (sessionId, mode, events) => {
+		const pushed = events.filter((event) => Reflect.get(event, "~a2.pushed") === true);
+		if (pushed.length > 0) await options.validatePush?.({
+			sessionId,
+			events: pushed
+		});
+		return appendCore(sessionId, events, "external", mode, (_rows, recoveryDueAt) => scheduleDrain(sessionId, recoveryDueAt));
+	};
 	const self = {
 		contract: serverContract,
 		session(id) {
 			assertSessionId(id);
-			const append = async (...events) => {
-				const pushed = events.filter((event) => Reflect.get(event, "~a2.pushed") === true);
-				if (pushed.length > 0) await options.validatePush?.({
-					sessionId: id,
-					events: pushed
-				});
-				return appendCore(id, events, "external", (_rows, recoveryDueAt) => scheduleDrain(id, recoveryDueAt));
-			};
+			const appendInline = async (...events) => appendExternal(id, "inline", events);
+			const appendDispatch = async (...events) => appendExternal(id, "dispatch", events);
+			const append = Object.assign(appendInline, { dispatch: appendDispatch });
 			return makeSession(id, append);
 		},
 		async drain(sessionId) {

package/dist/server.d.ts

@@ -38,11 +38,15 @@ type LaneContext<D extends EventDefs, K extends keyof D & string = keyof D & str
   };
 };
 type Lane<D extends EventDefs, K extends keyof D & string = keyof D & string> = string | ((context: LaneContext<D, K>) => string);
-type SessionAppend<D extends EventDefs> = {
+type SessionDispatch<D extends EventDefs> = {
   (...events: AppendInput<D>[]): Promise<ContractEvent<D>[]>;
   /** The push-route path: events from `parsePushBody`. */
   (...events: PushedEvent[]): Promise<ContractEvent<D>[]>;
 };
+type SessionAppend<D extends EventDefs> = SessionDispatch<D> & {
+  /** Commit, then hand pending work directly to configured recovery. */
+  dispatch: SessionDispatch<D>;
+};
 type HandlerAppend<D extends EventDefs> = (name: string, ...events: AppendInput<D>[]) => Promise<ContractEvent<D>[]>;
 /** A handle on one instance of the machine. Creating it does no I/O. */
 type Session<D extends EventDefs, Append = SessionAppend<D>> = {
@@ -148,4 +152,4 @@ type ServerOptions<D extends EventDefs> = {
 /** Implement a contract: bind its vocabulary to storage and reactions. */
 declare function createServer<D extends EventDefs>(options: ServerOptions<D>): A2Server<D>;
 //#endregion
-export { type A2Log, type A2LogInspection, A2Recovery, A2Server, AbortSpec, type AppendEvent, type AppendInput, type Clock, type Contract, type ContractEvent, type Event, type EventCause, type EventDefs, type FailAttemptResult, Handler, HandlerAppend, HandlerContext, HandlerEntry, type IdSource, Lane, LaneContext, type LogAppendResult, type LogClaimAvailableResult, type LogStateRead, PushValidationContext, PushedEvent, RecoverableServer, ServerOptions, Session, SessionAppend, type StoredEvent, type StoredSessionPage, type StoredSessionSummary, type StoredSnapshot, createServer };
+export { type A2Log, type A2LogInspection, A2Recovery, A2Server, AbortSpec, type AppendEvent, type AppendInput, type Clock, type Contract, type ContractEvent, type Event, type EventCause, type EventDefs, type FailAttemptResult, Handler, HandlerAppend, HandlerContext, HandlerEntry, type IdSource, Lane, LaneContext, type LogAppendResult, type LogClaimAvailableResult, type LogStateRead, PushValidationContext, PushedEvent, RecoverableServer, ServerOptions, Session, SessionAppend, SessionDispatch, type StoredEvent, type StoredSessionPage, type StoredSessionSummary, type StoredSnapshot, createServer };

package/dist/server.js

@@ -1,2 +1,2 @@
-import { t as createServer } from "./server-BWffWe5A.js";
+import { t as createServer } from "./server-BcLa4RFL.js";
 export { createServer };

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'

package/docs/concepts/01-contracts.mdx

@@ -41,10 +41,9 @@ 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.
 
 :::tip
 Events are facts, so name them in past tense: `created`, `expired`,

package/docs/concepts/03-durability.mdx

@@ -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. Recovery 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.
@@ -170,6 +169,14 @@ 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.
 
+`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
+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
+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
 older pending work. If older handled work is pending, the append still wakes
@@ -231,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
 

package/docs/guides/01-timers.mdx

@@ -1,17 +1,12 @@
 ---
 title: Timers and delays
-description: There is no sleep(). A delayed action is an event, delivered later, by anything that can make an HTTP call.
+description: A delayed action is an event delivered later by anything that can make an HTTP call.
 ---
 
-## There is no `sleep()`
+## Schedule delayed events
 
-Workflow engines let you sleep inside a function, then perform heroics to
-make that survive a serverless platform. A2 doesn't. If something should
-happen in five days, then in five days, something should append an event.
-That's scheduling.
-
-The scheduled thing is data (a session id and an event), not a suspended
-function. No closure has to survive the gap.
+If something should happen in five days, schedule an HTTP call that appends
+the event then. The scheduler stores the session id and event until delivery.
 
 ## Schedule an event
 

package/docs/guides/05-production.mdx

@@ -40,6 +40,19 @@ box; transaction-mode poolers included, which is exactly why polling
 is the default. `pg` is an optional peer dependency; pass
 `connectionString`, or inject your own pool as `client`.
 
+Prefer Redis? `redis({ url })` from `experimental-a2/log-redis` stores each
+session as a Redis Stream and streams push-natively: writes to watched
+sessions publish a disposable wake-up (sessions nobody watches cost no extra
+command), one shared subscriber connection per process serves every connected
+viewer, and a safety re-read covers a lost wake-up within ten seconds.
+Connections scale with your processes, not with your audience.
+`ioredis` is an optional peer dependency; pass `url`, or inject a client.
+Works on single instances and non-cluster providers such as Upstash, where
+durability is on by default. When only a REST API is available,
+`redisHttp({ url, token })` from `experimental-a2/log-redis-http` speaks the
+same storage over `fetch`, holds no connections at all, and polls on the same
+adaptive cadence as Postgres.
+
 This configures storage for A2's session logs. It does not connect A2 to your
 application tables or make them part of the append transaction. See
 [A2 and your database](/guides/application-data) for that boundary.
@@ -115,8 +128,32 @@ so they do not create an independent stream of watchdog callbacks.
 Events appended or returned by handlers ride their current execution window
 and add no recovery operation of their own.
 
-No cron, no sweep, no notification bookkeeping. The queue message is
-the recovery state, and the log is the only thing it consults.
+The queue message carries the recovery state, and recovery consults the log.
+
+### Dispatch in a fresh invocation
+
+Ordinary `append` starts handlers inline and uses recovery as the watchdog.
+Use `append.dispatch` when the current request should only persist the input
+and hand pending work directly to the queue:
+
+```ts app/api/imports/route.ts
+import { ordersServer } from '@/server'
+
+export async function POST(request: Request) {
+  const { orderId, shopId, items } = await request.json()
+  await ordersServer.session(orderId).append.dispatch({
+    id: `created:${orderId}`,
+    type: 'created',
+    payload: { shopId, items },
+  })
+  return Response.json({ accepted: true }, { status: 202 })
+}
+```
+
+The call awaits the immediate queue send and does not start an inline drain.
+If the send fails, the event may already be durable. Its explicit ID makes the
+retry idempotent. An existing drain for the same session can still claim the
+event first; dispatch controls the wakeup path, not worker affinity.
 
 ## 3. When an event dead-letters
 

package/docs/index.mdx

@@ -14,8 +14,8 @@ Handlers react to them, and usually return the next one. The browser follows
 the same log and folds the same state as the server. That's the whole model;
 the rest of this page is it happening.
 
-There is no declared state machine. Events record facts, reducers compute the
-current view, and handlers perform the reactions.
+Events record facts, reducers compute the current view, and handlers perform
+the reactions.
 
 ## Define a contract
 
@@ -39,8 +39,7 @@ export const orders = a2.contract({
 
 ## React to events
 
-Handlers are plain async functions: no determinism rules, no replay, no
-wrappers around side effects. Each one reacts to a fact and usually
+Handlers are plain async functions. Each one reacts to a fact and usually
 returns the next one.
 
 ```ts server/orders.ts
@@ -178,32 +177,6 @@ twenty lines; [Live UI](/guides/react) wires it end to end.
 
 ## FAQ
 
-<details>
-<summary>Why not a workflow engine?</summary>
-
-Workflow engines replay your code from the top on every wake-up. So the
-code has to be deterministic, so every side effect gets wrapped in a step
-function, and `sleep()` becomes something magical instead of something
-you'd never call in a serverless function.
-
-A2's answer is older and simpler: write everything down. Every meaningful
-thing that happens is an event in a log. Handlers are stateless functions
-that react to one event at a time. State isn't stored. It's computed, by
-folding over the log whenever you need it. There's no orchestrator to
-operate.
-
-</details>
-
-<details>
-<summary>Isn't this just event sourcing?</summary>
-
-It's the useful core of it. A log of facts, state as a fold: the idea is
-decades old, and it's a good one. A2 cuts the ceremony that made it a big
-commitment. No command bus, no projection cluster, no upcasting
-framework. A contract, a log, handlers, reducers.
-
-</details>
-
 <details>
 <summary>Can I use A2 without handlers?</summary>
 
@@ -217,12 +190,11 @@ See [Events without handlers](/concepts/handlers#events-without-handlers).
 </details>
 
 <details>
-<summary>How do I wait five days?</summary>
+<summary>How do I schedule an event for later?</summary>
 
-You don't sleep. You schedule an event. Anything that can deliver an
-HTTP call later (QStash, a cron, a payment provider's webhook) hits a
-route that appends. The scheduled thing is data, a session id plus an
-event, not a suspended function. See [Timers](/guides/timers).
+Anything that can deliver an HTTP call later (QStash, a cron, a payment
+provider's webhook) can hit a route that appends. Schedule the session id and
+event as the request payload. See [Timers](/guides/timers).
 
 </details>
 

package/docs/reference/01-api.mdx

@@ -357,6 +357,30 @@ append still starts session healing when older handled work is pending. The
 log reports that session-wide pending state as part of the atomic append, so
 this decision needs no follow-up read.
 
+### `session.append.dispatch(...events)`
+
+```ts
+session.append.dispatch(
+  ...events: Array<{ type: string; payload: unknown; id?: string }>
+): Promise<Event[]>
+```
+
+Commits the same atomic batch, but sends pending work directly to configured
+recovery instead of starting an inline drain. The call awaits acceptance of an
+immediate recovery message. It throws before writing if the server has no
+recovery adapter.
+
+If the queue send fails, the events are already durable. Give them explicit
+IDs and retry the same dispatch safely. A batch that leaves no pending handler
+work does not send a recovery message. Dispatch chooses how this append wakes
+the session; it does not reserve events for one worker. A drain that is already
+active may still claim newly eligible work first.
+
+`dispatch` exists only on a server session's top-level append. Handler-scoped
+`ctx.session.append(name, ...events)` already runs inside an active drain and
+does not expose `dispatch`. Its immediate children and atomically returned
+children become eligible in that drain.
+
 ### `session.history()`
 
 ```ts
@@ -756,6 +780,7 @@ alert on are all mid-span.
 | Attribute             | Span        | When  | Values                                                |
 | --------------------- | ----------- | ----- | ----------------------------------------------------- |
 | `a2.append.source`    | `a2.append` | start | `external` \| `handler`                                |
+| `a2.append.mode`      | `a2.append` | start | `inline` \| `dispatch`                                |
 | `a2.append.types`     | `a2.append` | start | comma-joined event types                              |
 | `a2.append.count`     | `a2.append` | start | batch size                                            |
 | `a2.append.armed`     | `a2.append` | mid   | `false` when the recovery arm failed and this append degraded to append-driven healing |
@@ -835,6 +860,7 @@ dashboard returns 501 for those logs.
 | `experimental-a2/http`            | route-side transport helpers       | none            |
 | `experimental-a2/log-postgres`    | `postgres`: Postgres log backend   | `pg` (or inject a client) |
 | `experimental-a2/log-redis`       | `redis`: Redis Streams log backend, push-native streaming | `ioredis` (or inject a client) |
+| `experimental-a2/log-redis-http`  | `redisHttp`: the same Redis log over provider REST APIs (Upstash) | none |
 | `experimental-a2/log-sqlite`      | SQLite log backend                 | none            |
 | `experimental-a2/log-memory`      | in-memory log backend              | none            |
 | `experimental-a2/recovery-vercel` | `vercelQueues` recovery            | `@vercel/queue` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-a2",
-  "version": "0.1.0",
+  "version": "0.3.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",
@@ -40,6 +40,7 @@
     "./log-sqlite": "./dist/log-sqlite.js",
     "./log-postgres": "./dist/log-postgres.js",
     "./log-redis": "./dist/log-redis.js",
+    "./log-redis-http": "./dist/log-redis-http.js",
     "./recovery-vercel": "./dist/recovery-vercel.js",
     "./cache-indexeddb": "./dist/cache-indexeddb.js",
     "./otel": "./dist/otel.js",