experimental-a2 0.0.0 → 0.2.0

package/dist/server.browser.js

@@ -1,11 +1,11 @@
 //#region src/server.browser.ts
 /**
-* The browser build of a2/server. There isn't one — on purpose.
-* Contracts and reducers (from `a2`) and the session client (from
-* `a2/client` / `a2/react`) are the isomorphic surface; the server is
+* The browser build of experimental-a2/server. There isn't one — on purpose.
+* Contracts and reducers (from `experimental-a2`) and the session client (from
+* `experimental-a2/client` / `experimental-a2/react`) are the isomorphic surface; the server is
 * where handlers and storage live. This module existing in a client
 * bundle means a `'use client'` file (or something it imports)
 * value-imported your server module.
 */
-throw new Error("a2/server is server-only — a client bundle imported it. Import the contract (a2) or the session client (a2/client, a2/react) in browser code instead.");
+throw new Error("experimental-a2/server is server-only — a client bundle imported it. Import the contract (a2) or the session client (experimental-a2/client, experimental-a2/react) in browser code instead.");
 //#endregion

package/dist/server.d.ts

@@ -1,6 +1,6 @@
-import { i as EventDefs, n as Contract, r as ContractEvent, s as Reducer, t as AppendInput } from "./contract-DL8btVd9.js";
-import { a as Event, c as IdSource, d as LogStateRead, f as StoredEvent, h as StoredSnapshot, i as Clock, l as LogClaimResult, m as StoredSessionSummary, n as A2LogInspection, o as EventCause, p as StoredSessionPage, r as AppendEvent, s as FailAttemptResult, t as A2Log, u as LogHandoffResult } from "./log-Dg1I8NRr.js";
-import { i as A2Telemetry } from "./telemetry-C78al20p.js";
+import { a as EventDefs, c as Reducer, n as Contract, r as ContractEvent, t as AppendInput } from "./contract-C_3dIIEU.js";
+import { a as Event, c as IdSource, d as LogStateRead, f as StoredEvent, h as StoredSnapshot, i as Clock, l as LogAppendResult, m as StoredSessionSummary, n as A2LogInspection, o as EventCause, p as StoredSessionPage, r as AppendEvent, s as FailAttemptResult, t as A2Log, u as LogClaimAvailableResult } from "./log-ldf5g8Cx.js";
+import { i as A2Telemetry } from "./telemetry-Cso0qyHQ.js";
 //#region src/server.d.ts
 /**
  * Events that arrived over the wire through `parsePushBody` — already
@@ -15,28 +15,43 @@ type PushedEvent = {
   id?: string;
   readonly "~a2.pushed": true;
 };
+type PushValidationContext = {
+  sessionId: string;
+  events: readonly PushedEvent[];
+};
 /** What every handler receives. */
 type HandlerContext<D extends EventDefs, K extends keyof D & string = keyof D & string> = {
   /** The triggering event. */
   event: ContractEvent<D, K>;
   /** Durable, 1-based dispatch ordinal for this event. */
   attempt: number;
-  /** Append what happens next to this session's log. Atomic per call. */
-  append: (...events: AppendInput<D>[]) => Promise<ContractEvent<D>[]>;
-  /** Every past event in this session, oldest first. Always the raw log. */
-  history: () => Promise<ContractEvent<D>[]>;
+  /** This session, with handler-scoped idempotent append. */
+  session: Session<D, HandlerAppend<D>>;
   /** Fires on `abortOn` events (cancellation slice); dormant otherwise. */
   signal: AbortSignal;
 };
-type Handler<D extends EventDefs, K extends keyof D & string = keyof D & string> = (ctx: HandlerContext<D, K>) => Promise<void>;
-/** A handle on one instance of the machine. Creating it does no I/O. */
-type Session<D extends EventDefs> = {
-  readonly sessionId: string;
-  append: {
-    (...events: AppendInput<D>[]): Promise<ContractEvent<D>[]>;
-    /** The push-route path: events from `parsePushBody`. */
-    (...events: PushedEvent[]): Promise<ContractEvent<D>[]>;
+type Handler<D extends EventDefs, K extends keyof D & string = keyof D & string> = (ctx: HandlerContext<D, K>) => Promise<void | AppendInput<D> | readonly AppendInput<D>[]>;
+type LaneContext<D extends EventDefs, K extends keyof D & string = keyof D & string> = {
+  sessionId: string;
+  event: Pick<ContractEvent<D, K>, "type" | "payload"> & {
+    id?: string;
   };
+};
+type Lane<D extends EventDefs, K extends keyof D & string = keyof D & string> = string | ((context: LaneContext<D, K>) => string);
+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>> = {
+  readonly id: string;
+  append: Append;
   history(): Promise<ContractEvent<D>[]>;
   state<S>(reducer: Reducer<D, S>): Promise<{
     state: S;
@@ -45,7 +60,7 @@ type Session<D extends EventDefs> = {
   /**
    * A live feed of this session's events, starting after `startAt`
    * (exclusive). Server-side only — expose it over SSE with
-   * `sseResponse` from a2/http.
+   * `sseResponse` from experimental-a2/http.
    */
   stream(opts?: {
     startAt?: number;
@@ -68,9 +83,9 @@ type RecoverableServer = {
  * The recovery seam (a2-implementation.md §7, §9). `arm` puts a
  * delayed, coalesced "drain this session" message on durable
  * infrastructure while inline work starts; `handler` returns the route
- * the transport delivers to. Lease holders move the watchdog alongside
+ * the transport delivers to. Claim holders move the watchdog alongside
  * their renewable execution window. Implementations ship as
- * entry points (`a2/recovery-vercel`); core never imports a transport.
+ * entry points (`experimental-a2/recovery-vercel`); core never imports a transport.
  */
 type A2Recovery = {
   arm(opts: {
@@ -86,10 +101,8 @@ type A2Server<D extends EventDefs> = {
   readonly contract: Contract<D>;
   session(id: string): Session<D>;
   /**
-   * Process the session's pending events in order. `settled` means the
-   * drain left nothing actionable: every event processed, or the
-   * session is stalled at a dead-lettered event (which recovery
-   * transports treat as "stop redelivering").
+   * Process every currently eligible event. `settled` means nothing
+   * actionable remains, including work blocked behind a dead letter.
    */
   drain(sessionId: string): Promise<{
     settled: boolean;
@@ -103,9 +116,13 @@ type A2Server<D extends EventDefs> = {
  * without `abortOn` pay nothing. An aborted handler should catch and
  * return normally; throwing means "retry me".
  */
-type AbortSpec<D extends EventDefs, K extends keyof D & string> = Array<keyof D & string> | { [T in keyof D & string]?: true | ((event: ContractEvent<D, T>, trigger: ContractEvent<D, K>) => boolean); };
+type AbortSpec<D extends EventDefs, K extends keyof D & string> = Array<keyof D & string> | { [T in keyof D & string]?: true | ((event: ContractEvent<D, T>, trigger: ContractEvent<D, K>, context: {
+  attempt: number;
+}) => boolean); };
 type HandlerEntry<D extends EventDefs, K extends keyof D & string = keyof D & string> = Handler<D, K> | {
-  abortOn: AbortSpec<D, K>;
+  abortOn?: AbortSpec<D, K>;
+  /** Session-scoped FIFO key, resolved and persisted when the event lands. */
+  lane?: Lane<D, K>;
   handler: Handler<D, K>;
 };
 type ServerOptions<D extends EventDefs> = {
@@ -115,13 +132,15 @@ type ServerOptions<D extends EventDefs> = {
   log?: A2Log;
   /**
    * Queue-backed recovery — e.g. `vercelQueues()` from
-   * `a2/recovery-vercel`. Absent means append-driven healing only: a
+   * `experimental-a2/recovery-vercel`. Absent means append-driven healing only: a
    * working configuration, but a clockless one. Recommended in
    * production.
    */
   recovery?: A2Recovery;
-  /** Optional instrumentation — e.g. `otel()` from `a2/otel`. */
+  /** Optional instrumentation — e.g. `otel()` from `experimental-a2/otel`. */
   telemetry?: A2Telemetry;
+  /** Validate events that came through `parsePushBody` before writing them. */
+  validatePush?: (context: PushValidationContext) => void | PromiseLike<void>;
   /**
    * The reactions, keyed by event type — all present at construction,
    * so a handler can never be silently missing because its module
@@ -133,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, HandlerContext, HandlerEntry, type IdSource, type LogClaimResult, type LogHandoffResult, type LogStateRead, PushedEvent, RecoverableServer, ServerOptions, Session, 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-DYsnKTTy.js";
+import { t as createServer } from "./server-DJgD2YWP.js";
 export { createServer };

package/dist/{telemetry-C78al20p.d.ts → telemetry-Cso0qyHQ.d.ts}

@@ -2,7 +2,7 @@
 /**
  * The A2Telemetry interface — the instrumentation seam. Same philosophy
  * as log backends: the interface lives in core, implementations ship as
- * entry points (`a2/otel` adapts it to OpenTelemetry). Without one,
+ * entry points (`experimental-a2/otel` adapts it to OpenTelemetry). Without one,
  * every operation runs through a no-op wrapper.
  */
 /** Attribute values a2 emits. */

package/dist/{wire-2QpU1EtJ.js → wire-BVsgR8o9.js}

@@ -1,7 +1,7 @@
 import { t as A2Error } from "./errors-BJRMd-h6.js";
 //#region src/wire.ts
 /**
-* The wire format shared by a2/http (server side) and a2/client
+* 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.

package/docs/01-quickstart.mdx

@@ -58,10 +58,10 @@ import { createServer } from 'experimental-a2/server'
 export const ordersServer = createServer({
   contract: orders,
   handlers: {
-    created: async ({ event, append }) => {
+    created: async ({ event }) => {
       // your side effect, e.g. email the shop, idempotent via event.id:
       // await sendEmailToShop(event.payload, { idempotencyKey: event.id })
-      await append({ type: 'shop.notified', payload: {} })
+      return { type: 'shop.notified', payload: {} }
     },
   },
 })
@@ -76,9 +76,9 @@ Two things worth noticing:
 - The side effect takes an idempotency key. Handlers can run more than
   once (that's what at-least-once delivery means), so external calls
   should be safe to repeat. `event.id` is stable across re-runs. Use it.
-- The `append` inside a handler is already deduplicated. If the handler
-  crashes after appending and runs again, the second append is a no-op,
-  [here's how](/concepts/handlers#handlers-can-run-twice).
+- The returned event is committed atomically with successful handler
+  completion. If the handler throws or the process dies first,
+  `shop.notified` does not appear. A handler can return one event or an array.
 
 ## 4. Append the first event
 
@@ -101,7 +101,7 @@ export async function POST(req: Request) {
 ```
 
 A session is one instance of the contract. `ordersServer.session('order-42')`
-is order 42's lifecycle: the unit A2 orders, recovers, folds, and streams.
+is order 42's lifecycle: the unit A2 recovers, folds, and streams.
 Creating the handle does no I/O, and the id is yours to choose.
 
 Try it:
@@ -152,7 +152,7 @@ curl localhost:3000/api/orders/order-42
 `createdAt`.)
 
 That second event is the payoff. You appended one event; the handler
-appended the next; the log shows the whole story, in order. This is what
+returned the next; the log shows the whole story, in order. This is what
 debugging looks like in A2: you read.
 
 ## 6. Fold state out of the log

package/docs/concepts/01-contracts.mdx

@@ -1,6 +1,6 @@
 ---
 title: Contracts and sessions
-description: A contract names one kind of lifecycle. A session is one instance, with its own history, ordering, state, and live stream.
+description: A contract names one kind of lifecycle. A session is one instance, with its own history, state, recovery, and live stream.
 ---
 
 ## Contracts
@@ -36,10 +36,10 @@ throws `INVALID_PAYLOAD` before anything is written, an unknown type
 throws `UNKNOWN_EVENT_TYPE`. What lands in the log is the validated
 output, with defaults applied and transforms run.
 
-The contract is a plain, importable, **isomorphic** value. It carries
-nothing but schemas. 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.
+The contract is a plain, importable, **isomorphic** value. It carries the
+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
@@ -55,7 +55,7 @@ convention, not a namespace.
 
 ## Serving a contract
 
-Handlers and storage bind to the contract with `createServer` from
+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
 (and the one that fails loudly if a browser bundle ever imports it):
 
@@ -68,9 +68,9 @@ export const ordersServer = createServer({
   contract: orders,
   log: postgres({ connectionString: process.env.DATABASE_URL }),
   handlers: {
-    created: async ({ event, append }) => {
+    created: async ({ event }) => {
       // your side effect, then:
-      await append({ type: 'shop.notified', payload: {} })
+      return { type: 'shop.notified', payload: {} }
     },
   },
 })
@@ -101,22 +101,22 @@ const order = ordersServer.session('order-42')
 ```
 
 A session is one instance of the contract: one order, one signup, one
-chat, one approval, one import. It has its own log, its own ordering, its own
-state, and its own live stream. The id is yours: use whatever identifies the
-subject in your system.
+chat, one approval, one import. It has its own ordered log, state, recovery,
+and live stream. The id is yours: use whatever identifies the subject in your
+system.
 
 Creating a session does no I/O. It's a handle; nothing loads until you
 append, read, or stream.
 
-Sessions are also the unit of ordering: events within one session are
-processed serially, in log order. Different sessions never wait for each
-other. More in [Handlers](/concepts/handlers#ordering).
+Handlers are concurrent by default, including within one session. Add a
+[`lane`](/concepts/handlers#lanes) when events share a resource and must run
+one at a time.
 
 ## Pick the boundary
 
 The session is the boundary A2 keeps durable and synchronized. Put events in
-the same session when they must be ordered, folded, recovered, or viewed
-together. Split things that should progress independently.
+the same session when they form one history, fold, recovery unit, or live
+view. Split things that should be read and recovered independently.
 
 A contract is not a database table, and a session is not a table or a general
 query boundary. One contract serves every instance of that lifecycle. An
@@ -130,9 +130,9 @@ usually belong in an application database. See
 
 ## One more option: recovery
 
-Servers accept a `recovery` option, which arms a durable, delayed drain
-for every top-level append, giving crash recovery and handler retries in one
-mechanism. The handler starts without waiting for recovery, and a successful
-initial arm is durable before `append` returns. It changes how fast A2 heals,
-not how it works. Everything in these concept pages holds with or without it.
-Covered in [Going to production](/guides/production).
+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
+before `append` returns. Event types without handlers settle during append and
+create no recovery work when the session has no older backlog. Covered in
+[Going to production](/guides/production).