experimental-a2 0.17.0 → 0.18.1

package/docs/concepts/02-handlers.mdx

@@ -1,284 +0,0 @@
----
-title: Handlers
-description: Concurrent reactions with atomic returned events and explicit serial lanes.
----
-
-```ts server/orders.ts
-import { createServer } from 'experimental-a2/server'
-import { orders } from '@/contracts'
-
-export const ordersServer = createServer({
-  contract: orders,
-  handlers: {
-    created: async ({ event }) => {
-      // your side effect, e.g. email the shop, idempotent via event.id:
-      // await sendEmailToShop(event.payload, { idempotencyKey: event.id })
-      return { type: 'shop.notified', payload: {} }
-    },
-  },
-})
-```
-
-A handler runs when its event lands. It is a plain async function: call a
-database, hit an API, stream a model response. A2 durably claims the event,
-renews that claim while the function runs, and retries after a crash.
-
-Handlers live in the server's construction, not on sessions. One complete
-table serves every session. A handler cannot be silently missing because the
-module that registered it was never imported.
-
-## Events without handlers
-
-Handlers are optional per event type. An event without one still gets its full
-place in the log. You can read it with `history()`, fold it into state, and
-stream it to a live client. A2 settles it in the append transaction, with no
-dispatch claim or scheduler message.
-
-```ts server/order-history.ts
-import { createServer } from 'experimental-a2/server'
-import { postgres } from 'experimental-a2/store-postgres'
-import { orders } from '@/contracts'
-
-export const orderHistory = createServer({
-  contract: orders,
-  store: postgres({ connectionString: process.env.DATABASE_URL }),
-})
-```
-
-A contract can mix handled and unhandled event types. Adding a handler later
-does not replay events that were already settled. Model replay as a new event
-or run an explicit migration when that is the behavior you want.
-
-## The context
-
-Every handler receives one argument:
-
-| Property      | What it is |
-| ------------- | ---------- |
-| `ctx.event`   | The triggering event: `{ id, type, payload, index, sessionId, createdAt }`. |
-| `ctx.attempt` | The durable 1-based dispatch claim for this event. |
-| `ctx.session` | This session's handle: `id`, `append`, `history`, `state`, and `stream`. |
-| `ctx.signal`  | An `AbortSignal`. Fires when the attempt's lease lapses (`CLAIM_EXPIRED`), when a recovered run provably supersedes it (`SUPERSEDED_ATTEMPT`), and on matching `abortOn` events. See [Cancellation](/guides/cancellation). |
-
-`ctx.attempt` starts at `1` and increments on every durable claim. It may skip
-when a process dies between the claim and handler entry.
-
-`ctx.session.id` is the same value as `ctx.event.sessionId`. Use
-`ctx.session.history()` when a handler needs raw facts. Use
-[`state()`](/concepts/state) for a cached computed view of a long session.
-The handler-scoped state read folds through `ctx.event.index` by default, so
-later concurrent appends do not change what that event sees. Use
-`ctx.session.state(reducer, { through: 'latest' })` when the handler
-intentionally joins against the current committed frontier.
-
-## Return what happens after success
-
-Return an event when it depends on successful handler completion:
-
-```ts server/return-one.ts
-import { createServer } from 'experimental-a2/server'
-import { orders } from '@/contracts'
-
-export const assignments = createServer({
-  contract: orders,
-  handlers: {
-    'shop.started': async () => {
-      return { type: 'driver.notified', payload: { driverId: 'driver-7' } }
-    },
-  },
-})
-```
-
-A handler can return one event or an array:
-
-```ts server/return-many.ts
-import { createServer } from 'experimental-a2/server'
-import { orders } from '@/contracts'
-
-export const fanout = createServer({
-  contract: orders,
-  handlers: {
-    'shop.started': async () => {
-      return orders.batch(
-        { type: 'shop.notified', payload: {} },
-        { type: 'driver.notified', payload: { driverId: 'driver-7' } },
-      )
-    },
-  },
-})
-```
-
-`contract.batch(...)` keeps each event's literal type when an async handler
-returns different event types. It is a type helper; validation still happens
-when A2 commits the returned events.
-
-A2 marks the triggering event processed and appends the returned batch in one
-atomic storage operation. The batch is all-or-nothing and occupies consecutive
-log positions. If the handler throws or the process dies first, none of the
-returned events exist.
-
-Returned events receive deterministic ids. If A2 commits the operation but
-loses its acknowledgement, the retry recognizes the exact returned batch and
-does not duplicate it.
-
-## Append what should happen now
-
-`ctx.session.append()` has different timing. It commits immediately, so the appended
-event can start while its parent handler is still running:
-
-```ts server/append-now.ts
-import { createServer } from 'experimental-a2/server'
-import { orders } from '@/contracts'
-
-export const immediate = createServer({
-  contract: orders,
-  handlers: {
-    created: async ({ session }) => {
-      await session.append('notify-shop', {
-        type: 'shop.notified',
-        payload: {},
-      })
-
-      // The shop.notified handler may already be running here.
-      // await continueCurrentWork()
-    },
-    'shop.notified': async () => {},
-  },
-})
-```
-
-Use it for streaming progress, independent fan-out, or any fact that remains
-true even if the current handler later fails. A multi-event
-`ctx.session.append()` is atomic per call.
-
-The first argument names this immediate append within the triggering event.
-It is the handler-local idempotency key for events whose `id` is omitted. Keep
-it stable across retries:
-
-```ts
-// inside a handler:
-await session.append(
-  'publish-build',
-  { type: 'artifact.created', payload: artifact },
-  { type: 'build.completed', payload: result },
-)
-```
-
-A2 combines the triggering event id, this name, and each unnamed event's
-position to derive deterministic child ids. Parallel branches can finish in
-any order without changing their identities. Reusing a name with the same
-generated-id batch returns the existing events. Changing that batch conflicts
-with the rows already stored under those ids. An explicit event `id` wins over
-the generated id, which is useful when different triggering events must
-converge on one fact. Top-level `server.session(id).append(...events)` takes no
-name because it is not scoped to a handler.
-
-The distinction is small and important:
-
-| Syntax | The event becomes durable |
-| ------ | ------------------------- |
-| `return event` | Atomically when the handler completes successfully |
-| `return [a, b]` | Both atomically when the handler completes successfully |
-| `await session.append(name, event)` | Immediately, before the handler completes |
-
-## Concurrent by default
-
-Every eligible event has its own durable claim. Independent handlers in the
-same session start without waiting for earlier handlers:
-
-```ts
-// anywhere on the server:
-await ordersServer.session('order-42').append(
-  { type: 'created', payload: { shopId: 'shop-7', items: [] } },
-  { type: 'shop.started', payload: {} },
-)
-```
-
-The log order remains stable, but handler start and completion order do not.
-A failure retries that event without holding up unlaned events or other lanes.
-
-## Lanes
-
-Use a lane when events share a resource and must not overlap:
-
-```ts server/serial-orders.ts
-import { createServer } from 'experimental-a2/server'
-import { orders } from '@/contracts'
-
-export const serialOrders = createServer({
-  contract: orders,
-  handlers: {
-    created: {
-      lane: 'order-work',
-      handler: async () => {},
-    },
-    'shop.started': {
-      lane: 'order-work',
-      handler: async () => {},
-    },
-  },
-})
-```
-
-Within one session, events with the same lane run one at a time in log order.
-Different lanes and unlaned events remain concurrent. A constant lane like
-`'order-work'` recreates a serial queue for the event types that use it.
-
-A lane can also be derived from the validated event:
-
-```ts server/drivers.ts
-import { createServer } from 'experimental-a2/server'
-import { orders } from '@/contracts'
-
-export const drivers = createServer({
-  contract: orders,
-  handlers: {
-    'driver.notified': {
-      lane: ({ event }) => `driver:${event.payload.driverId}`,
-      handler: async ({ event }) => {
-        // your work for this driver, using event.payload.driverId
-      },
-    },
-  },
-})
-```
-
-The resolved lane is stored with the event when it is appended. The scheduler uses
-that stored value, so a deployment cannot reinterpret pending work. Lane keys
-are scoped to one session. They are not distributed locks across sessions.
-
-If a lane's first unfinished event fails, later events in that lane wait.
-Other lanes continue. After ten caught failures the event dead-letters and
-keeps blocking its lane until manual resolution.
-
-## Handlers can run twice
-
-Handlers are at-least-once. A crash after your side effect but before A2
-commits completion means the handler can run again.
-
-1. **External side effects take an idempotency key.** `event.id` is stable
-   across attempts. Pass it to anything that should not happen twice.
-
-2. **Immediate handler appends are deduplicated.**
-   `ctx.session.append(name, ...events)` derives ids from the triggering event,
-   the stable handler-local name, and each event's position. A retry gets the
-   existing rows back. A changed generated-id batch conflicts with those
-   existing rows.
-
-3. **Returned events commit with completion.** They either all exist with the
-   processed marker or none exist.
-
-A handler should give every independent immediate append a stable name. The
-name removes any dependence on the order in which concurrent branches call
-`append`. Use explicit event ids when several different triggering events must
-converge on one shared fact.
-
-## When handlers throw
-
-Throwing means "retry me." A2 records the failure and retries with backoff.
-The failed event blocks only its lane. After ten caught failures it
-dead-letters for [manual resolution](/concepts/durability#when-a-handler-keeps-failing).
-
-An interrupted handler should catch and return normally. Throwing is the
-wrong response to someone pressing stop. See
-[Cancellation](/guides/cancellation).

package/docs/concepts/03-durability.mdx

@@ -1,314 +0,0 @@
----
-title: Durability
-description: Appends are effectively-once, handlers are at-least-once, and retries preserve event identity across crashes.
----
-
-## The contract
-
-- **Appends are effectively-once.** Event ids deduplicate writes. A batch commits
-  before its handlers start; they may start before `append` resolves.
-- **Handlers are at-least-once.** They may run again after a crash, so
-  [side effects use idempotency keys](/concepts/handlers#handlers-can-run-twice).
-- **The log stays ordered.** Every session has one immutable append order.
-- **Handlers are concurrent by default.** Log order does not serialize them.
-  Only events in the same lane run one at a time in log order.
-
-## The correctness model
-
-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 |
-+--------+---------+
-         |
-         v
-+------------------+
-| drain(session)   |
-+--------+---------+
-         |
-         v
-+------------------+
-| claimAvailable   |
-+--------+---------+
-         |
-    +----+----------------+
-    |                     |
-    v                     v
-+-------------+   +-------------------+
-| busy or     |   | run every claimed |
-| settled     |   | event concurrently|
-+-------------+   +-------------------+
-```
-
-A queue message identifies a session. Every wakeup runs the same drain, and
-the log decides what remains. The scheduler 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.
-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 complete that event:
-
-```text
-+----------------------------+  one backend operation
-| claimAvailable             |
-| eligible events + attempts |
-+-------------+--------------+
-              |
-       +------+------+
-       |             |
-       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.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 scheduling
-
-A top-level append commits first. Only then does A2 start the inline drain and
-optional watchdog arm in parallel. A handler may start before `append` returns;
-the call joins the arm for at most two seconds, not the handler. The drain never
-waits for the queue. Arm failure records `a2.append.armed = false`, while
-`ctx.session.append` rides the active drain and adds no arm. Returned events
-enter the log with 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 scheduler send. It requires a configured scheduler. 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 scheduler 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 scheduler 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.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 `lane`, `firstClaimedAt`, `lastClaimedAt`,
-`claimHolder`, `claimExpiresAt`, `lastFailedAt`, `lastFailedAttempt`,
-`processedAt`, `processedByAttempt`, and `returnedEventIds`. Timestamps are
-adapter clock values captured for atomic store 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.
-
-## Claim and watchdog timing
-
-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 | Event claim | Watchdog |
-| ---: | --- | --- | --- |
-| t0 | Claim attempt 1 | Through t5 | Arm t6 |
-| t2 | Heartbeat | Through t7 | Arm t8 |
-| t4 | Heartbeat | Through t9 | Arm t10 |
-| t6 | Handler runs | Through t9 | Deliver t6: `busy`; ensure a later slot |
-| t7 | Process dies | Abandoned | No more arms |
-| t8 | | Through t9 | Deliver t8: `busy`; ensure a later slot |
-| t9 | | Expires | t10 remains scheduled |
-| t10 | Claim attempt 2 | New window | Deliver t10: wins |
-
-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 returned one after another do not fit together in a
-20-second invocation, but each fits in a fresh one:
-
-| Time | Work | Durable state |
-| ---: | --- | --- |
-| t0 | Handler 1 starts | Attempt 1 |
-| t8 | Handler 1 finishes; handler 2 starts | Event 1 processed |
-| t16 | Handler 2 finishes; handler 3 starts | Events 1 and 2 processed |
-| t20 | Function is killed | Event 3 pending; `failureCount = 0` |
-| t21 | Handler 3 starts again | Same event, attempt 2 |
-| t29 | Handler 3 finishes; handler 4 starts | Events 1 through 3 processed |
-| t37 | Handler 4 finishes | Session settled |
-
-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
-
-```text
-+-------------------------+
-| 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
-```
-
-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. |
-| 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, 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`, 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
-
-| Situation | Result |
-| --- | --- |
-| Process dies before the first arm is durable | Retry with the same ids, append again later, or call `drain()`. |
-| No scheduler configured | A later top-level append or explicit `drain()` wakes the session. Reads never do. |
-| Scheduler invocation dies after claiming but before arming | Its unacknowledged queue delivery is the slower fallback. |
-| Store 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
-
-Append success means the event is durable, not that all handlers finished. An
-identical batch retry returns rows with the same ids. A mixed batch throws
-[`PARTIAL_DUPLICATE_BATCH`](/reference/errors).
-
-For the queue route and deployment configuration, see
-[Going to production](/guides/production#2-add-a-scheduler-for-handlers).