experimental-a2 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.0
+
+### Minor Changes
+
+- 056cf86: Add `session.append.dispatch(...events)` to persist events and hand pending
+  handler work directly to configured recovery instead of starting it inline.
+
 ## 0.1.0
 
 ### Minor Changes

package/dist/ai-server.js

@@ -1,5 +1,5 @@
 import { t as A2Error } from "./errors-BJRMd-h6.js";
-import { t as createServer } from "./server-BWffWe5A.js";
+import { t as createServer } from "./server-DJgD2YWP.js";
 import { convertToModelMessages, stepCountIs, streamText, toUIMessageStream } from "ai";
 //#region src/ai-sdk-step.ts
 const CONTROLLED_SETTINGS = [

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

@@ -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-DJgD2YWP.js";
 export { createServer };

package/docs/concepts/03-durability.mdx

@@ -170,6 +170,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

package/docs/guides/05-production.mdx

@@ -118,6 +118,31 @@ 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.
 
+### 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
 
 After ten caught handler failures, A2 stops retrying an event. It blocks later

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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-a2",
-  "version": "0.1.0",
+  "version": "0.2.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",