experimental-a2 0.0.0 → 0.2.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,157 @@ 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.
+
+`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
+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 +217,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 +245,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 +304,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