experimental-a2 0.0.0

package/docs/concepts/02-handlers.mdx

@@ -0,0 +1,146 @@
+---
+title: Handlers
+description: Stateless async functions that react to one event, and usually append the next one.
+---
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { orders } from '@/contracts'
+
+export const ordersServer = createServer({
+  contract: orders,
+  handlers: {
+    created: async ({ event, append }) => {
+      // 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: {} })
+    },
+  },
+})
+```
+
+That's a handler: it runs when its event lands, does its work, and appends
+what happens next. Handlers live in the server's construction, not on
+sessions. One table of reactions serves every session: `order-1`,
+`order-2`, all of them. Because the table is complete at construction, a
+handler can never be silently missing just because the module that
+defined it wasn't imported.
+
+They're also plain async functions. No determinism requirements, no replay,
+no wrappers around side effects. Call your database, hit an API, use
+`Math.random()`, stream a model response for a minute. A2 heartbeats the
+session's lease while your handler runs, so a slow handler never loses its
+exclusivity to a concurrent retry. The one thing you don't do in a handler
+is wait for the future. For that, [append an event later](/guides/timers).
+
+## 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.append(...e)`   | Append what happens next to this session's log. Typed against the contract's schemas.          |
+| `ctx.history()`      | Every past event in this session, oldest first. Always the raw log.                            |
+| `ctx.signal`         | An `AbortSignal`, active only with `abortOn`. 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.
+
+Use `history()` when a handler needs more than the triggering event: "has
+this order already been notified twice?". For a cheap computed view of a
+long session, use a [reducer](/concepts/state) instead.
+
+## Chaining
+
+The core pattern: handlers append the event that should happen next.
+
+```ts
+// server/orders.ts, the next link in the chain:
+import { createServer } from 'experimental-a2/server'
+import { orders } from '@/contracts'
+
+export const ordersServer = createServer({
+  contract: orders,
+  handlers: {
+    'shop.started': async ({ append }) => {
+      // const driverId = await acquireDriver(), however your app finds one
+      const driverId = 'driver-7'
+      await append({ type: 'driver.notified', payload: { driverId } })
+    },
+  },
+})
+```
+
+This is how a lifecycle moves in A2. It is not a workflow definition, but a
+chain of facts, each one triggering the next reaction. Afterward, the full
+story of the order is sitting in its log, readable top to bottom.
+
+`append` takes one or more events. A multi-event append is atomic:
+all-or-nothing, consecutive log positions, one transaction.
+
+## Ordering
+
+Within a session, handlers run serially, in log order. The handler for
+event 5 doesn't start until events 1 through 4 have finished, even when
+retries and queue deliveries arrive shuffled. Across sessions there's no
+coordination; two orders never wait on each other.
+
+Chained handlers run inline for as long as the current invocation lives. A2
+does not predict whether the next handler fits in the remaining function
+time. If the platform stops the invocation, completed events stay processed
+and the event that was still running stays pending. Recovery retries that same
+event under a fresh lease.
+
+Each individual handler must still fit inside a fresh invocation. A2 can
+recover a chain whose total duration crosses the function limit, but it cannot
+split one handler while it is running. If a handler always exceeds the
+platform's function duration, every recovery attempt reaches the same limit.
+Break that work into a chain of smaller events, or give the function enough
+time for one handler to finish.
+
+If a handler fails, the session stalls at that event. Later events keep
+accumulating in the log (appends never fail because a handler is failing),
+but their handlers wait. Skipping ahead would let a handler observe a
+history whose earlier handlers never ran; stalling is the honest behavior.
+The retry story is in [Durability](/concepts/durability).
+
+## Handlers can run twice
+
+Handlers are at-least-once. A crash after your side effect but before A2
+marks the event processed means the handler runs again. Two rules make this
+a non-issue:
+
+1. **External side effects take an idempotency key.** `event.id` is stable
+   across re-runs. Pass it to your email provider, your payment API,
+   anything that shouldn't happen twice.
+
+2. **`ctx.append` is deduplicated for you.** Each append call inside a
+   handler gets a deterministic id derived from the triggering event and the
+   call's position. A re-run produces the same ids, hits the log's unique
+   index, and gets the existing rows back. The straight-line case needs no
+   thought.
+
+:::note
+How? Without an explicit `id`, `ctx.append` derives one deterministically:
+a hash of the triggering event's id plus the call's position ("the second
+append this handler made"). A re-run reproduces the same ids, hits the
+log's unique index, and gets the original rows back. It's the same
+[idempotency machinery](/concepts/durability#what-append-never-throws-for)
+that dedupes every append. No special case, no checkpoint state.
+:::
+
+One caveat on rule 2: a handler that appends in a data-dependent order
+(looping over results from an external API, say) should pass explicit `id`s,
+because "the same call position" isn't stable when the loop changes.
+
+## When handlers throw
+
+Throwing means "retry me". A2 records the failure and retries with backoff
+until the handler succeeds, or, after ten caught failures, dead-letters the event
+and stalls the session for [manual resolution](/concepts/durability#when-a-handler-keeps-failing).
+
+The flip side: a handler interrupted by a user (via `ctx.signal`) should
+catch and return normally. "Retry me" is exactly the wrong response to
+someone pressing stop. See [Cancellation](/guides/cancellation).

package/docs/concepts/03-durability.mdx

@@ -0,0 +1,230 @@
+---
+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. When
+  `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 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.
+
+```text
++-----------------+
+| Wakeups         |
+|                 |
+| append          |
+| watchdog        |
+| state / stream  |
++--------+--------+
+         |
+         v
++-----------------+
+| drain(session)  |
++--------+--------+
+         |
+         v
++-----------------+
+| claimNext       |
++--------+--------+
+         |
+    +----+----+
+    |         |
+    v         v
++----------+  +-----------------+
+| return   |  | run handler     |
+| busy or  |  | claimed event   |
+| settled  |  +-----------------+
++----------+
+```
+
+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.
+
+:::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 advance that event:
+
+```text
++----------------------------+  one backend operation
+| claimNext                  |
+| head + lease + attempt     |
++-------------+--------------+
+              |
+              v
++----------------------------+
+| handler 1                  |
++-------------+--------------+
+              |
+              v
++----------------------------+  one backend operation
+| completeAndClaimNext       |
+| complete 1 + claim 2       |
++-------------+--------------+
+              |
+              v
++----------------------------+
+| handler 2                  |
++----------------------------+
+```
+
+`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).
+
+## 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.
+
+## 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.
+
+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.
+
+## Lease 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:
+
+| Time | Live worker | Lease | 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 |
+
+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.
+
+## 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:
+
+| 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 restarts handler 3; it does not resume its old call.
+
+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
+
+```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
+```
+
+The deterministic child id makes the retry reuse event 3. External effects
+use event 2's id as their idempotency key.
+
+## 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. |
+| Retry | Without a processed marker, the same event remains pending. |
+| Identity | Event and derived 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.
+
+## Limits
+
+| Situation | Result |
+| --- | --- |
+| 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. |
+
+## 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-recovery).

package/docs/concepts/04-state.mdx

@@ -0,0 +1,133 @@
+---
+title: Reading state
+description: "A session's state is a fold over its log: raw history when you want facts, a reducer when you want the current view."
+---
+
+## History
+
+```ts
+// anywhere on the server:
+const events = await ordersServer.session(orderId).history()
+```
+
+Everything that happened in this session, oldest first. Always the raw log,
+never a summary, never a snapshot. This is the session's audit trail and
+debugging story, and it is also fine to use inside handlers for questions like
+"did the shop already start?"
+
+## Reducers
+
+For a computed view, derive a reducer from the contract and fold:
+
+```ts contracts.ts
+import { z } from 'zod'
+import * as a2 from 'experimental-a2'
+
+export const orders = a2.contract({
+  name: 'orders',
+  events: {
+    created: z.object({ shopId: z.string(), items: z.array(z.string()) }),
+    'shop.notified': z.object({}),
+    expired: z.object({}),
+  },
+})
+```
+
+```ts reducer.ts
+import { z } from 'zod'
+import { orders } from './contracts'
+
+export const ordersReducer = orders
+  .reducer({
+    name: 'order-status',
+    initialState: { status: 'new' },
+    stateSchema: z.object({
+      status: z.enum(['new', 'created', 'notified', 'expired']),
+      shopId: z.string().optional(),
+    }),
+  })
+  .fold((state, event) => {
+    switch (event.type) {
+      case 'created':
+        return { status: 'created', shopId: event.payload.shopId }
+      case 'shop.notified':
+        return { ...state, status: 'notified' }
+      case 'expired':
+        return { ...state, status: 'expired' }
+      default:
+        return state
+    }
+  })
+```
+
+```ts
+// anywhere on the server, e.g. a server component before first paint:
+const { state, index } = await ordersServer
+  .session(orderId)
+  .state(ordersReducer)
+```
+
+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
+contract, so the events type themselves; the two-step shape is
+deliberate: the first call fixes the state and event types, and
+`.fold()` receives fully concrete ones. No type arguments, no
+annotations, and literal unions (like the `z.enum` status above) survive
+the fold intact. `state()` folds the session's events through it and
+returns the result, along with `index`: the log position the state
+reflects. The browser uses that index to resume a live stream exactly
+where server-rendered state left off. See [Live UI](/guides/react).
+
+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.
+
+`stateSchema` declares the state's shape once. Without it, the state type
+is inferred from `initialState`, fine while every fold arm returns the
+same shape. With it, the schema is the type (and the seed may lean on its
+defaults), `initialState` is validated at definition, and anywhere A2
+rehydrates folded state instead of refolding raw events, [server
+snapshots](#snapshots-are-a-cache), the [browser
+cache](/guides/local-first): a cached fold that fails the schema is
+discarded and refolded, catching shape drift a stale `name` can't.
+
+Note what these modules import: schemas and `experimental-a2`. Never `experimental-a2/server`,
+never a log backend. Contract and reducer are isomorphic by
+construction; the browser runs the same reducer. More on the split in
+[Live UI](/guides/react#keep-the-backend-out-of-the-bundle). (In a
+server-only app you can keep the contract next to `createServer`
+instead of in its own file.)
+
+## Snapshots are a cache
+
+Folding a long session on every read would get slow, so the log backend
+caches folded state as a snapshot. You never interact with it, except for
+one string.
+
+Snapshots are keyed by the reducer's `name`, which makes the name do two
+jobs. It's the identity: two different reducers over the same session
+never fight over a cache entry, because they have different names. And
+it's the invalidation knob. Changed the fold's logic? Change the name (a
+`-v2` suffix works). Snapshots stored under the old name are simply
+ignored; the next read refolds from raw events and caches under the new
+name. That's the entire cache invalidation story: one string.
+
+Snapshot write-back runs in platform `waitUntil` after the state is ready. It
+never delays the read, and a failed or interrupted cache write changes no
+application behavior. The next read folds the missing tail again.
+
+Deleting every snapshot is always safe. The log rebuilds them.
+
+## Events don't change meaning
+
+The log is append-only, and events are immutable in meaning: `created`
+means forever what it meant when it was written. When a payload needs a new
+shape, add a new event type (`created.v2`) rather than redefining the old
+one.
+
+This is why reducers accumulate switch cases over time, and why they never
+migrate anything: old sessions keep their old events, new sessions write
+new ones, and the same fold handles both.

package/docs/guides/01-timers.mdx

@@ -0,0 +1,85 @@
+---
+title: Timers and delays
+description: There is no sleep(). A delayed action is an event, delivered later, by anything that can make an HTTP call.
+---
+
+## There is no `sleep()`
+
+Workflow engines let you sleep inside a function, then perform heroics to
+make that survive a serverless platform. A2 doesn't. If something should
+happen in five days, then in five days, something should append an event.
+That's scheduling.
+
+The scheduled thing is data (a session id and an event), not a suspended
+function. No closure has to survive the gap.
+
+## Schedule an event
+
+Use any scheduler that can deliver an HTTP call later: QStash, a cron, your
+payment provider's webhook. It hits a route; the route appends.
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { orders } from '@/contracts'
+
+export const ordersServer = createServer({
+  contract: orders,
+  handlers: {
+    created: async ({ event }) => {
+      // 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: {} },
+      // })
+    },
+  },
+})
+```
+
+```ts app/api/append/route.ts
+import { ordersServer } from '@/server/orders'
+
+export async function POST(req: Request) {
+  const { sessionId, type, payload } = await req.json()
+  await ordersServer.session(sessionId).append({ type, payload })
+  return Response.json({ ok: true })
+}
+```
+
+:::warning
+Auth this route like any other. Anything that can call it can move your
+sessions forward.
+:::
+
+## Stale timers
+
+The order shipped on day two. The expiry still fires on day five. Now what?
+
+You could hunt down the scheduled call and cancel it. The simpler default,
+and the recommended one, is to let the timer fire and have the handler
+check whether it still applies. Guard on read:
+
+```ts
+// server/orders.ts, the expiry handler, guarding on read:
+import { createServer } from 'experimental-a2/server'
+import { orders } from '@/contracts'
+
+export const ordersServer = createServer({
+  contract: orders,
+  handlers: {
+    expired: async ({ history }) => {
+      const events = await history()
+      if (events.some((e) => e.type === 'shop.started')) return // stale, ignore
+      // ...actually expire the order
+    },
+  },
+})
+```
+
+This works because history is truth. The timer doesn't need to know what
+happened after it was scheduled; the handler can just look. The stale
+`expired` event still lands in the log, and that's fine: it's a fact ("the
+timer fired"), and the handler decided it was moot.