experimental-a2 0.0.0 → 0.1.0

package/docs/concepts/03-durability.mdx

@@ -9,47 +9,44 @@ description: Appends are effectively-once, handlers are at-least-once, and retri
   `append` returns, the event is in the log.
 - **Handlers are at-least-once.** They may run again after a crash, so
   [side effects use idempotency keys](/concepts/handlers#handlers-can-run-twice).
-- **Order holds per session.** Events are processed in log order. A2 never
-  dispatches past a pending event.
+- **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 correctness model
 
-The log says what needs work. The lease says who may work now. The processed
-marker says what finished. The watchdog says when to look again.
+The log says what needs work. A per-event claim says who may work now. The
+processed marker says what finished. The watchdog says when to look again.
 
 ```text
-+-----------------+
-| Wakeups         |
-|                 |
-| append          |
-| watchdog        |
-| state / stream  |
-+--------+--------+
++------------------+
+| Wakeups          |
+| append, watchdog |
++--------+---------+
          |
          v
-+-----------------+
-| drain(session)  |
-+--------+--------+
++------------------+
+| drain(session)   |
++--------+---------+
          |
          v
-+-----------------+
-| claimNext       |
-+--------+--------+
++------------------+
+| claimAvailable   |
++--------+---------+
          |
-    +----+----+
-    |         |
-    v         v
-+----------+  +-----------------+
-| return   |  | run handler     |
-| busy or  |  | claimed event   |
-| settled  |  +-----------------+
-+----------+
+    +----+----------------+
+    |                     |
+    v                     v
++-------------+   +-------------------+
+| busy or     |   | run every claimed |
+| settled     |   | event concurrently|
++-------------+   +-------------------+
 ```
 
 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.
-Append follows its causal tree; recovery and explicit `server.drain()` inspect
-the full session. Reads never dispatch handlers.
+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.
@@ -59,72 +56,149 @@ Your log contains only application facts.
 ## One event, many attempts
 
 An event is pending until it has a processed marker. Attempt tracking is part
-of the operations that already claim and advance that event:
+of the operations that already claim and complete that event:
 
 ```text
 +----------------------------+  one backend operation
-| claimNext                  |
-| head + lease + attempt     |
+| claimAvailable             |
+| eligible events + attempts |
 +-------------+--------------+
               |
-              v
-+----------------------------+
-| handler 1                  |
-+-------------+--------------+
-              |
-              v
-+----------------------------+  one backend operation
-| completeAndClaimNext       |
-| complete 1 + claim 2       |
-+-------------+--------------+
-              |
-              v
-+----------------------------+
-| handler 2                  |
-+----------------------------+
+       +------+------+
+       |             |
+       v             v
++-------------+ +-------------+
+| handler A   | | handler B   |
++------+------+ +------+------+
+       |               |
+       v               v
++-------------+ +-------------+  one operation per event
+| complete A  | | complete B  |
++-------------+ +-------------+
 ```
 
 `ctx.attempt` is the durable, 1-based claim ordinal. A kill after the claim can
 consume an ordinal before user code sees it, but adds no caught failure. A
 retry gets the same event id, index, type, and payload with a larger attempt.
 
-Use `event.id` to deduplicate external effects. `ctx.append` derives stable
-child ids when call order is stable. Otherwise, pass
-[explicit child ids](/concepts/handlers#handlers-can-run-twice).
+Use `event.id` to deduplicate external effects. `ctx.session.append` derives
+stable child ids from its handler-local name. See
+[Handlers can run twice](/concepts/handlers#handlers-can-run-twice).
+
+Each claim stores its holder and expiry on the event. Claiming an expired event
+increments its attempt before a new handler starts. Completion and failure are
+fenced by that ordinal, so an older attempt cannot overwrite a newer one.
+
+## Immediate and dependent events
+
+Handlers have two ways to publish more events:
+
+- `ctx.session.append(name, ...events)` commits immediately. Its events may run
+  before the current handler finishes. The stable name makes the append
+  idempotent across retries.
+- `return event` or `return [eventA, eventB]` publishes only when the handler
+  succeeds. A2 completes the parent and appends the whole returned batch in
+  one transaction.
+
+```ts server/pipeline.ts
+import { z } from 'zod'
+import * as a2 from 'experimental-a2'
+import { createServer } from 'experimental-a2/server'
+
+const pipeline = a2.contract({
+  name: 'pipeline',
+  events: {
+    'build.requested': z.object({ buildId: z.string() }),
+    'build.completed': z.object({ buildId: z.string() }),
+    'deploy.requested': z.object({ buildId: z.string() }),
+  },
+})
+
+export const pipelineServer = createServer({
+  contract: pipeline,
+  handlers: {
+    'build.requested': async ({ event }) => {
+      // your side effect, idempotent via event.id:
+      // await build(event.payload, { idempotencyKey: event.id })
+      return [
+        { type: 'build.completed', payload: { buildId: event.payload.buildId } },
+        { type: 'deploy.requested', payload: { buildId: event.payload.buildId } },
+      ]
+    },
+  },
+})
+```
+
+If the handler throws, neither returned event exists. If the completion
+transaction commits but its acknowledgment is lost, A2 retries with the same
+ordered child ids and returns the already-committed rows. A partial or changed
+batch is rejected.
+
+This transaction covers only A2's log. An HTTP call, database write, Bash
+command, or other external effect cannot join it. If an effect succeeds and
+the process dies before completion commits, the handler runs it again. Use
+`event.id` as an idempotency key or add fencing in the external system.
+
+## Lanes
+
+A lane is a session-scoped serial group. A2 resolves the lane when it appends
+the event and stores the value beside it.
+
+- Events without a lane are independently eligible.
+- Only the lowest-index unfinished event in a lane is eligible.
+- Different lanes run concurrently.
+- A failure blocks later events in that lane, not the whole session.
+
+Persisting the value matters for recovery. A deployment that changes a lane
+resolver affects new events, not pending ones already in the log.
+
+A lane controls A2 dispatch, not the outside world. A worker can perform an
+external effect and disappear before recording completion. Its successor then
+retries the same event. External idempotency is still required.
+
+A2 claims every currently eligible event. It does not add a global concurrency
+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
 
-A top-level append commits first, then 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.append` rides the
-active drain and adds no arm.
+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.
+
+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
+the session-wide healing path.
 
 ## Causal trees are durable
 
-Every event written by `ctx.append` stores one atomic `cause` with the
-triggering event's index and current dispatch ordinal. Top-level appends store
-null. In newly written data that is a root, but durable readers also use null
-for legacy events whose origin is unknown. Several appends from one handler are
-siblings. Nested handler appends create further levels. If a handler retries
-after writing a child, idempotency preserves that child's original cause.
+Every event written by `ctx.session.append` or returned by a handler stores one
+atomic `cause` with the triggering event's index and current dispatch ordinal.
+Top-level appends store null. Several children from one handler are siblings.
+Nested handler output creates further levels. If a handler retries after
+writing a child, idempotency preserves that child's original cause.
 
 The edge is part of the existing append batch and survives process restarts.
-The stored event also carries `firstClaimedAt`, `lastClaimedAt`,
-`lastFailedAt`, `lastFailedAttempt`, `processedAt`, and `processedByAttempt`.
-These timestamps are adapter clock values captured for atomic log operations,
-not exact database commit times. `processedAt` is write-once, so a stale worker
-cannot rewrite a newer completion. The durable log can therefore rebuild a
-causal forest and show useful lifecycle boundaries. `attemptCount` summarizes
-intermediate claims instead of storing one row per attempt.
+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
+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.
 
-## Lease and watchdog timing
+## Claim and watchdog timing
 
-A heartbeat renews the session lease and arms a watchdog after each lease
-window. For illustration, use a five-second lease, two-second heartbeat, and
-one-second grace:
+A heartbeat renews every live claim owned by the drain and arms a watchdog
+after each claim window. For illustration, use a five-second claim, two-second
+heartbeat, and one-second grace:
 
-| Time | Live worker | Lease | Watchdog |
+| Time | Live worker | Event claim | Watchdog |
 | ---: | --- | --- | --- |
 | t0 | Claim attempt 1 | Through t5 | Arm t6 |
 | t2 | Heartbeat | Through t7 | Arm t8 |
@@ -135,15 +209,17 @@ one-second grace:
 | t9 | | Expires | t10 remains scheduled |
 | t10 | Claim attempt 2 | New window | Deliver t10: wins |
 
-Lease renewal and queue sends do not block each other. A busy watchdog ensures
-a later watchdog before acknowledging; if that send fails, it does not
-acknowledge. If a deadline is available, A2 caps the current lease window at
-it. The deadline never gates handler dispatch.
+Claim renewal and queue sends do not block each other. An expired claim cannot
+be renewed. It becomes eligible for a new claim, which increments the attempt
+and fences the previous worker. A busy watchdog ensures a later watchdog
+before acknowledging; if that send fails, it does not acknowledge. If a
+deadline is available, A2 caps the current claim window at it. The deadline
+never gates handler dispatch.
 
 ## A chain that crosses the function timeout
 
-Four eight-second handlers do not fit together in a 20-second invocation, but
-each fits in a fresh one:
+Four eight-second handlers returned one after another do not fit together in a
+20-second invocation, but each fits in a fresh one:
 
 | Time | Work | Durable state |
 | ---: | --- | --- |
@@ -161,55 +237,57 @@ 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.
 
-## Crash after a child append
+## Crash around a returned batch
 
 ```text
-+------------------------+
-| Invocation A           |
-| event 2, attempt 1     |
-| append child event 3   |
-+-----------+------------+
-            |
-            v
-+------------------------+
-| Durable log            |
-| event 2: pending       |
-| event 3: pending       |
-+-----------+------------+
-            |
-        SIGKILL, then lease expiry
-            |
-            v
-+------------------------+
-| Invocation B           |
-| event 2, attempt 2     |
-| append reuses event 3  |
-+-----------+------------+
-            |
-            v
-   complete 2, drain 3
++-------------------------+
+| Invocation A            |
+| event 2, attempt 1      |
+| handler returns event 3 |
++------------+------------+
+             |
+        completeAttempt
+             |
+       +-----+------+
+       |            |
+       v            v
+   transaction   SIGKILL before
+   commits       transaction
+       |            |
+       v            v
+  event 2 done   event 2 pending
+  event 3 exists event 3 absent
 ```
 
-The deterministic child id makes the retry reuse event 3. External effects
-use event 2's id as their idempotency key.
+If the commit acknowledgment is lost, a retry with the exact returned ids gets
+event 3 back without duplicating it. If the transaction did not commit, event
+2 retries and produces the same deterministic returned id. External effects
+still use event 2's id as their idempotency key.
+
+With `ctx.session.append`, the child commits before its parent finishes. It
+remains in the log if the parent crashes and can run concurrently unless both
+events use the same lane.
 
 ## Why this stays correct
 
 | Property | Durable rule |
 | --- | --- |
 | Commit | Store the event before any wakeup. |
-| Order | Claim only the lowest pending index. |
-| Ownership | Only a live lease holder can claim the next event. |
-| Handoff | Complete the current event and claim the next atomically. |
+| Concurrency | Claim every eligible unlaned event and one unfinished head per lane. |
+| Ownership | Store an expiring claim on each event. |
+| Completion | Complete the parent and append its returned batch atomically. |
+| Fencing | Only the current attempt can complete or record a failure. |
 | Retry | Without a processed marker, the same event remains pending. |
-| Identity | Event and derived child ids stay stable across retries. |
+| Identity | Event, immediate child, and returned child ids stay stable across retries. |
 | Liveness | A watchdog, later append, or explicit drain re-enters `drain(session)`. |
 
 ## When a handler keeps failing
 
-A caught failure increments `failureCount`; a stale failure changes nothing.
-Ten caught failures dead-letter the event and stall that session. Hard kills
-do not consume this budget. Resolution is manual: fix and retry, or skip.
+A caught failure increments `failureCount`, clears that event's claim, and
+leaves other eligible events running. A stale failure changes nothing. Ten
+caught failures dead-letter the event. Later events in its lane remain blocked;
+unlaned events and other lanes continue. Hard kills do not consume this budget.
+Resolution is manual: fix and retry, or skip.
 
 ## Limits
 
@@ -218,7 +296,8 @@ do not consume this budget. Resolution is manual: fix and retry, or skip.
 | 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 or lease backend unavailable | Safe progress stops until it returns. |
+| Log 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
 

package/docs/concepts/04-state.mdx

@@ -67,6 +67,25 @@ const { state, index } = await ordersServer
   .state(ordersReducer)
 ```
 
+Handlers receive the same session interface for their triggering session:
+
+```ts server.ts
+import { createServer } from 'experimental-a2/server'
+import { orders } from './contracts'
+import { ordersReducer } from './reducer'
+
+export const ordersServer = createServer({
+  contract: orders,
+  handlers: {
+    created: async ({ session }) => {
+      const { state, index } = await session.state(ordersReducer)
+      void state
+      void index
+    },
+  },
+})
+```
+
 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
@@ -83,7 +102,14 @@ 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.
+pending work to finish. Inside a handler, the returned index includes the
+triggering event and may include later events that 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.
+For joins, use a monotone readiness check (once ready, always ready) and give
+the output event a stable explicit `id`. Repeated attempts then converge on the
+same append.
 
 `stateSchema` declares the state's shape once. Without it, the state type
 is inferred from `initialState`, fine while every fold arm returns the

package/docs/guides/01-timers.mdx

@@ -25,14 +25,14 @@ import { orders } from '@/contracts'
 export const ordersServer = createServer({
   contract: orders,
   handlers: {
-    created: async ({ event }) => {
+    created: async ({ session }) => {
       // schedule with anything that can deliver an HTTP call later:
       // QStash, cron, a provider webhook:
       //
       // await scheduleHttpCall({
       //   delay: '5d',
       //   url: '/api/append',
-      //   body: { sessionId: event.sessionId, type: 'expired', payload: {} },
+      //   body: { sessionId: session.id, type: 'expired', payload: {} },
       // })
     },
   },
@@ -70,8 +70,8 @@ import { orders } from '@/contracts'
 export const ordersServer = createServer({
   contract: orders,
   handlers: {
-    expired: async ({ history }) => {
-      const events = await history()
+    expired: async ({ session }) => {
+      const events = await session.history()
       if (events.some((e) => e.type === 'shop.started')) return // stale, ignore
       // ...actually expire the order
     },

package/docs/guides/02-cancellation.mdx

@@ -65,10 +65,38 @@ generate: {
 The pushing side already knows the id it's cancelling; it's in the
 `events` feed the hook exposes.
 
-Because sessions process serially, the `cancelled` event's own handler runs
-*after* the interrupted one settles. That makes it the natural place for
-cleanup. The signal is the preemption channel; the event is the durable
-record.
+Handlers are concurrent by default. A `cancelled` handler may therefore run
+while the interrupted handler is still unwinding. The signal is the
+preemption channel; the event is the durable record.
+
+When cleanup must wait for the interrupted handler, put both event types in
+one lane. The event fires the signal as soon as it is appended, but its own
+handler waits for earlier work in that lane:
+
+```ts server/chat-with-cleanup.ts
+import { createServer } from 'experimental-a2/server'
+import { chat } from '@/contracts'
+
+export const chatServer = createServer({
+  contract: chat,
+  handlers: {
+    generate: {
+      lane: 'generation',
+      abortOn: ['cancelled'],
+      handler: async (ctx) => {
+        // your abortable work; hand it ctx.signal:
+        // await streamText({ signal: ctx.signal, ... })
+      },
+    },
+    cancelled: {
+      lane: 'generation',
+      handler: async () => {
+        // your cleanup, after generate has returned
+      },
+    },
+  },
+})
+```
 
 ## The view cuts
 

package/docs/guides/05-production.mdx

@@ -1,13 +1,13 @@
 ---
 title: Going to production
-description: Point the log at Postgres, add queue-backed recovery, and know what to do when an event dead-letters.
+description: Point the log at durable storage, add recovery for handler work, and know what to do when an event dead-letters.
 ---
 
 ## Two pieces
 
 Development needs zero setup: SQLite appears under `.a2/`, and tests run
-in memory. Production needs two deliberate pieces. Neither changes your
-handlers.
+in memory. Every production server needs a durable log. Servers with handlers
+also need recovery. Neither choice changes your event contract.
 
 ## 1. Choose a log
 
@@ -30,7 +30,8 @@ export const ordersServer = createServer({
 ```
 
 The Postgres backend uses real transactions; appends serialize per
-session on an advisory lock, and the live stream polls the log with an
+session on an advisory lock, while handler claims remain concurrent. The live
+stream polls the log with an
 activity-adaptive cadence: 25ms while a session is producing events
 (a token stream reads smoothly, not in clumps), backing off to 250ms
 when it goes quiet (a LISTEN/NOTIFY upgrade could still land without
@@ -43,7 +44,7 @@ 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.
 
-## 2. Add recovery
+## 2. Add recovery for handlers
 
 Recovery is what puts a clock on healing. `experimental-a2/recovery-vercel` rides
 Vercel Queues (`@vercel/queue` is a peer
@@ -94,33 +95,35 @@ export const POST = recovery.handler(ordersServer, billingServer)
 The trigger makes the route private. Only queue infrastructure can invoke
 it, so it needs no auth of its own.
 
-One route, one job. Every top-level append starts a delayed, coalesced
-"drain this session" arm alongside its inline handler. The handler does not
-wait for the queue, while `append` joins the initial arm for up to two seconds
-before it returns. An unresponsive queue therefore cannot hold the append open
-indefinitely. Every lease renewal arms another watchdog for just after that
-lease window. A live holder keeps moving the watchdog forward. A killed holder
-stops heartbeating, its lease expires, and the next watchdog retries the
-pending event. When Vercel exposes the function deadline, A2 caps the final
-lease window there so timeout recovery starts promptly. A failing handler
-keeps the current message and redelivers with backoff until the session
-settles.
-
-Due times are rounded to one-second slots. Top-level arms, lease renewals, and
+One route, one job. A top-level append that leaves or finds pending handler
+work starts a delayed, coalesced "drain this session" arm alongside its inline
+handler. The handler does not wait for the queue, while `append` joins the
+initial arm for up to two seconds before it returns. An unresponsive queue
+therefore cannot hold the append open indefinitely. Claim renewals arm another
+watchdog for just after the current window. Live handlers keep moving their
+per-event claims and the watchdog forward. A killed holder stops heartbeating,
+its claims expire, and the next watchdog retries those pending events. When
+Vercel exposes the
+function deadline, A2 caps the final claim window there so timeout recovery
+starts promptly. A failing handler keeps the current message and redelivers
+with backoff. Work outside its lane continues.
+
+Due times are rounded to one-second slots. Top-level arms, claim renewals, and
 racing deliveries targeting the same slot deduplicate into one queue message.
 Busy deliveries continue the current message's heartbeat-aligned slot series,
 so they do not create an independent stream of watchdog callbacks.
-Events appended by handlers ride their current execution window and add no
-recovery operation of their own.
+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.
 
 ## 3. When an event dead-letters
 
-After ten caught handler failures, A2 stops retrying an event and the session
-stalls at it; [Durability](/concepts/durability#when-a-handler-keeps-failing)
-explains why stalling is the honest choice. Resolution is manual, and has
+After ten caught handler failures, A2 stops retrying an event. It blocks later
+events in the same lane; unlaned events and other lanes continue.
+[Durability](/concepts/durability#when-a-handler-keeps-failing) explains this
+boundary. Resolution is manual, and has
 exactly two shapes:
 
 - **Fix and retry.** Deploy the handler fix, clear the event's failure
@@ -155,14 +158,20 @@ path lands in a single trace: the request → `a2.append` → the inline
 make: the whole causal chain, visually. Handler failures mark their `a2.event`
 span with the exception, each dispatch reports `ctx.attempt` as
 `a2.event.attempt`, and `a2.event.outcome = dead_lettered` is the attribute to
-alert on when a session [stalls for manual
+alert on when an event [needs manual
 resolution](#3-when-an-event-dead-letters). See the
 [API reference](/reference/api#a2otel) for the span catalogue.
 
 ## Running without a queue
 
-Skip `recovery`, and the only wakeups are a top-level append or explicit
-`server.drain()`. Reads never wake the session.
+If none of a contract's event types have handlers, skip `recovery`. Those
+events settle in their append transaction, so they create no drains, claims,
+queue messages, or recovery callbacks. The server is a durable event log for
+history, reducers, and live sync. That is a complete production configuration,
+not degraded recovery, because there is no reaction to recover.
+
+With handlers, skipping `recovery` means the only wakeups are a top-level
+append or explicit `server.drain()`. Reads never wake the session.
 
 That's a real configuration, not a broken one. Fine for internal tools
 and low-stakes apps where "heals on the next write" is acceptable. But
@@ -174,6 +183,6 @@ For production, configure recovery.
 | Piece               | Done when                                                            |
 | ------------------- | -------------------------------------------------------------------- |
 | Log                 | `log: postgres(...)` on every server                                  |
-| Recovery            | one shared `vercelQueues()`, route mounted, trigger in `vercel.json`  |
+| Recovery            | for servers with handlers: one shared `vercelQueues()`, route, and trigger |
 | Idempotent handlers | external side effects take `event.id` as an idempotency key           |
 | Client split        | contracts/reducers isomorphic; only `experimental-a2/server` touches backends      |