experimental-a2 0.17.0 → 0.18.1

package/docs/01-quickstart.mdx

@@ -1,13 +1,12 @@
 ---
 title: Quickstart
-description: Define one lifecycle, implement its reactions, and make your first durable append in about five minutes.
+description: Define a contract, react to its events, and make your first durable append in five minutes.
 ---
 
 ## What you'll build
 
-The smallest useful lifecycle: an order that notifies a shop when it arrives.
-One contract, one session, one handler, two routes, and at the end a log you
-can read back.
+An order that notifies a shop when it arrives: one contract, one handler, two
+routes, and a log you can read back.
 
 ## 1. Install
 
@@ -17,10 +16,7 @@ npm i experimental-a2 zod
 
 ## 2. Define a contract
 
-A contract is a name plus the events it understands: each key an event
-name, each value a schema. Zod here, though any
-[Standard Schema](https://standardschema.dev) validator works, and
-that's the contract's complete declaration.
+A contract is a name plus the events it understands, each with a schema:
 
 ```ts server/orders.ts
 import { z } from 'zod'
@@ -35,21 +31,10 @@ export const orders = a2.contract({
 })
 ```
 
-The contract is a plain, importable, isomorphic value. The server
-implements it below, the reducer derives from it in step 6, and when a
-browser enters the picture it types the client too.
-
-There's no database setup in development: A2 stores events in SQLite at
-`.a2/dev.db`, so state survives restarts. Tests get an in-memory store.
-Production wants an explicit backend; see
-[Going to production](/guides/production).
-
 ## 3. Implement it
 
-Handlers run where the contract is served. `createServer` binds the
-vocabulary to storage and reactions; each handler gets the triggering
-event and can append what happens next. Same file, below the contract
-(they can split later, when a browser needs the contract alone):
+`createServer` binds the contract to storage and handlers. Same file, below
+the contract:
 
 ```ts server/orders.ts
 import { createServer } from 'experimental-a2/server'
@@ -66,24 +51,19 @@ export const ordersServer = createServer({
 })
 ```
 
-All handlers are declared at construction: one table of reactions, so a
-handler can never be silently missing because the module that registered
-it wasn't imported.
-
-Two things worth noticing:
+- Handlers can run more than once (at-least-once delivery), so make external
+  calls safe to repeat. `event.id` is stable across re-runs: use it as the
+  idempotency key.
+- The returned event commits atomically with handler success. If the handler
+  throws or the process dies first, `shop.notified` doesn't appear. Return one
+  event or an array.
 
-- The side effect takes an idempotency key. Handlers can run more than
-  once (that's what at-least-once delivery means), so external calls
-  should be safe to repeat. `event.id` is stable across re-runs. Use it.
-- The returned event is committed atomically with successful handler
-  completion. If the handler throws or the process dies first,
-  `shop.notified` does not appear. A handler can return one event or an array.
+Development needs no database setup: events go to SQLite at `.a2/dev.db` and
+survive restarts. Tests get an in-memory store. Production needs an explicit
+store; see [Production](/server/production).
 
 ## 4. Append the first event
 
-`append` is the entire public surface for moving a session forward. Call it
-from a route:
-
 ```ts app/api/orders/route.ts
 import { ordersServer } from '@/server/orders'
 
@@ -99,11 +79,8 @@ export async function POST(req: Request) {
 }
 ```
 
-A session is one instance of the contract. `ordersServer.session('order-42')`
-is order 42's lifecycle: the unit A2 recovers, folds, and streams.
-Creating the handle does no I/O, and the id is yours to choose.
-
-Try it:
+`session(orderId)` is one [session](/contract/sessions), one instance of the
+contract. The id is yours, and creating the handle does no I/O.
 
 ```bash
 curl -X POST localhost:3000/api/orders \
@@ -111,18 +88,15 @@ curl -X POST localhost:3000/api/orders \
   -d '{ "orderId": "order-42", "shopId": "shop-7", "items": ["flat white"] }'
 ```
 
-The payload is validated against the schema before anything is written;
-send garbage and you get `INVALID_PAYLOAD` back, with the issues.
+The payload is validated before anything is written; a bad one fails with
+`INVALID_PAYLOAD` and the issues.
 
-When the append returns, the event is durably in the log and A2 has started the
+When `append` returns, the event is durably in the log and A2 has started the
 `created` handler inline. In production, a queue-backed scheduler wakes pending
-work after a failure or process death. See [Durability](/concepts/durability)
-for the exact contract.
+work after a failure or process death. See [Guarantees](/server/guarantees).
 
 ## 5. Read the log back
 
-Add a route that returns the session's history:
-
 ```ts app/api/orders/[orderId]/route.ts
 import { ordersServer } from '@/server/orders'
 
@@ -147,41 +121,35 @@ curl localhost:3000/api/orders/order-42
 ]
 ```
 
-(Trimmed for brevity; each event also carries `id`, `sessionId`, and
-`createdAt`.)
-
-That second event is the payoff. You appended one event; the handler
-returned the next; the log shows the whole story, in order. This is what
-debugging looks like in A2: you read.
+Each event also carries `id`, `sessionId`, and `createdAt` (trimmed here). You
+appended one event and the handler returned the second. Debugging in A2 is
+reading the log.
 
 ## 6. Fold state out of the log
 
-Raw session history is truth, but UIs usually want a view. Define a reducer
-once:
+UIs usually want a view, not raw history. Define a reducer once:
 
 ```ts reducer.ts
 import { reducer } from 'experimental-a2'
 import { orders } from '@/server/orders'
 
-export const ordersReducer = reducer({ contract: orders, name: 'order-status', initialState: { status: 'new' }  })
-  .fold((state, event) => {
-    switch (event.type) {
-      case 'created':
-        return { ...state, status: 'created' }
-      case 'shop.notified':
-        return { ...state, status: 'notified' }
-      default:
-        return state
-    }
-  })
+export const ordersReducer = reducer({
+  contract: orders,
+  name: 'order-status',
+  initialState: { status: 'new' },
+}).fold((state, event) => {
+  switch (event.type) {
+    case 'created':
+      return { ...state, status: 'created' }
+    case 'shop.notified':
+      return { ...state, status: 'notified' }
+    default:
+      return state
+  }
+})
 ```
 
-A reducer is *derived from* the contract, in two steps by design: the
-first call fixes the state and event types, so `.fold()` receives fully
-concrete ones. No type arguments, no annotations, and literal unions in
-your state survive the fold.
-
-And fold anywhere you need the current picture:
+Then fold wherever you need the current picture:
 
 ```ts
 // anywhere on the server:
@@ -192,22 +160,20 @@ const { state } = await ordersServer.session('order-42').state(ordersReducer)
 // state → { status: 'notified' }
 ```
 
-The session's state is not a second record to update. It is a fold over the
-log. More in [Reading state](/concepts/state).
+State isn't a second record to update. It's a fold over the log; see
+[State](/contract/state).
 
 ## That's it
 
-You have a durable lifecycle, implemented: a validated write path, a handler,
-a log you can read, and a view folded from it.
-Everything else in these docs is the same two moves, append an event and
-react to it, applied to timers, cancellation, live UIs, and production
-infrastructure.
+You have a validated write path, a handler, a log you can read, and a view
+folded from it. The rest of these docs apply the same two moves, append an
+event and react to it, to timers, cancellation, live UIs, and production.
 
 <CardGroup cols={2}>
-  <Card title="Handlers" href="/concepts/handlers" icon="file">
-    The context object, chaining, ordering, and re-runs.
+  <Card title="Handlers" href="/server/handlers" icon="file">
+    Context, chaining, and re-runs.
   </Card>
-  <Card title="Going to production" href="/guides/production" icon="rocket">
-    Postgres, a queue-backed scheduler, and dead-letter resolution.
+  <Card title="Production" href="/server/production" icon="rocket">
+    A store, a scheduler, dead letters.
   </Card>
 </CardGroup>

package/docs/{guides/07-examples.mdx → 02-examples.mdx}

@@ -1,19 +1,10 @@
 ---
 title: Complete examples
-description: Read or copy the complete Next.js playground that ships inside the experimental-a2 package.
+description: Every experimental-a2 install includes a complete Next.js playground to copy, run, and read.
 ---
 
 ## Shipped with the package
 
-Every `experimental-a2` installation includes a complete Next.js playground at
-`node_modules/experimental-a2/examples/playground`.
-
-The playground is not a collection of isolated snippets. Each feature owns its
-contract, reducer, server, route handlers, client session, and scheduler when it
-needs one. It uses only public package entry points.
-
-Copy it into a new directory to run or modify it:
-
 ```sh
 cp -R node_modules/experimental-a2/examples/playground ./a2-playground
 cd a2-playground
@@ -21,12 +12,13 @@ pnpm install
 pnpm dev
 ```
 
-The copied `package.json` is standalone. Its A2 dependency is pinned to the
-version that supplied the example.
+The playground lives at `node_modules/experimental-a2/examples/playground`.
+Each feature owns its contract, reducer, server, route handlers, client
+session, and scheduler when it needs one, using only public entry points.
 
-The snapshot also includes an `AGENTS.md` file. Coding agents that support
-repository instructions discover the example's structure as soon as they work
-inside the copied directory.
+The copy is standalone: its `package.json` pins A2 to the version that
+shipped it, and its `AGENTS.md` describes the structure to coding agents that
+work inside the directory.
 
 ## Find the right example
 
@@ -49,8 +41,6 @@ When A2 is installed locally, read these package directories in this order:
 3. `node_modules/experimental-a2/src` only when implementation details are
    relevant.
 
-Do not infer application patterns from `dist`. The playground is the reference
-for how the public pieces fit together in a real Next.js application.
-
-The npm snapshot is generated from `apps/playground` in the A2 repository when
-the package is published, so the runnable app remains the canonical source.
+Don't infer application patterns from `dist`. The playground, generated from
+`apps/playground` in the A2 repository at publish time, is the reference for
+how the public pieces fit together.

package/docs/actors/01-introduction.mdx

@@ -1,28 +1,22 @@
 ---
 title: Introduction
-description: "A durable object built on the log: one named instance, typed state, and handlers that process one message at a time."
+description: "Typed state behind a mailbox. Each instance processes one message at a time, and each handler ends in one atomic commit."
 ---
 
 ## The model
 
-An actor is state behind a mailbox. You address an instance by id, send
-it typed events, and its handlers process them one at a time: read
-state, decide, mutate, return. Each handler ends in one atomic commit.
-Between messages the instance is rows in your store, not a process:
-nothing to keep alive, no locks to take, no lost updates to debug.
+An actor is state behind a mailbox: you send an instance typed events,
+and its handlers process them one at a time. Between messages an
+instance is rows in your store, not a process. Every instance is an
+ordinary A2 session, so durability, retries, history, and devtools hold
+for actors too.
 
-Every instance is an ordinary A2 session underneath, so everything the
-log gives a session (durability, retries, history, devtools) holds for
-actors too. The module is three entry points: `experimental-a2/actor`
-on the server, `experimental-a2/actor/client` anywhere, and
+Entry points: `experimental-a2/actor` on the server,
+`experimental-a2/actor/client` anywhere, and
 `experimental-a2/actor/react` for the hook.
 
 ## Define one
 
-A protocol declares the state shape and the events with their inputs.
-Types, not schemas: handlers are trusted server code, and the compiler
-holds them to the protocol. Pass it explicitly.
-
 ```ts vault.ts
 import { NonRetriableError } from 'experimental-a2'
 import { actor } from 'experimental-a2/actor'
@@ -52,28 +46,22 @@ export const vault = actor<Vault>({
 })
 ```
 
-The `handlers` record must cover every declared event: a missing
-handler, an extra one, or a wrong input shape fails to compile. Inputs
-arrive typed; `ctx.state` is a mutable draft of the instance's state,
-committed atomically when the handler returns. `name` is identity (it
-prefixes storage keys), and `state` seeds new instances.
+Pass the protocol explicitly as the type argument. It declares types,
+not schemas: handlers are trusted server code, and a missing handler,
+an extra one, or a wrong input shape fails to compile. `ctx.state` is a
+mutable draft, committed atomically when the handler returns. `name` is
+identity (it prefixes storage keys), and `state` seeds new instances.
 
-Types are compile-time claims. When an event can arrive from the wire,
-guard its input in the handler's first lines and throw
-`NonRetriableError` on bad shapes (bring a schema library and `.parse`
-if you prefer; it is userland either way).
+When an event can arrive from the wire, guard its input in the
+handler's first lines and throw `NonRetriableError` on bad shapes.
 
-`actor` also accepts the `store`, `scheduler`, and `telemetry` options
-`createServer` takes. Without a store it uses the same development
-default; see [Going to production](/guides/production). A protocol can
-declare one more vocabulary, `presence`, for live audience state; see
-[Presence](/actors/routes#presence).
+`actor` also accepts `createServer`'s `store`, `scheduler`, and
+`telemetry` options, with the same development default store; see
+[Production](/server/production). A protocol can also declare
+[`presence`](/actors/routes#presence).
 
 ## Call it
 
-`call` sends the event and awaits its answer: the state after the
-handler ran, and the log index of that commit.
-
 ```ts
 // anywhere on the server:
 import { vault } from '@/vault'
@@ -84,18 +72,14 @@ const { state, index } = await savings.call.deposit({ amount: 100 })
 // state reflects this deposit, and every message before it
 ```
 
-`vault.actor(id)` is a handle, not a resource; nothing exists until the
-first message. Concurrent calls from any number of serverless
+`call` awaits the answer: the state after the handler ran and the log
+index of that commit. `vault.actor(id)` is a handle; nothing exists
+until the first message. Concurrent calls from any number of
 invocations serialize on the instance's lane, and each answer reflects
-its own message. That serialization is the feature:
-[Concurrency](/actors/concurrency) is the full story.
+its own message; see [Concurrency](/actors/concurrency).
 
 ### Refusals
 
-A handler says no by throwing `NonRetriableError`. That refusal is an
-answer, not a failure: nothing commits, nothing retries, and the caller
-gets the message.
-
 ```ts
 // anywhere on the server:
 import { ActorRefusedError } from 'experimental-a2/actor'
@@ -110,28 +94,23 @@ try {
 }
 ```
 
-Three kinds of failure, three behaviors:
+Throwing `NonRetriableError` refuses the message. A refusal is an
+answer, and it is all or nothing: no state change, no buffered sends,
+no retry. The message settles, and the caller receives
+`ActorRefusedError`.
 
-- **`NonRetriableError`** is a refusal, and a refusal is all or
-  nothing: no state change, no buffered sends. The message is settled,
-  and the caller receives `ActorRefusedError`.
-- **Any other throw** is an infrastructure failure. A2 retries the
-  message with the usual budget and backoff; the instance's lane waits,
-  which is deliberate (correctness over liveness). See
+- **Any other throw** retries the message with the usual budget and
+  backoff while the instance's lane waits; see
   [Errors](/reference/errors).
 - **A crash** re-runs the handler from the pre-message state. `ctx.id`
   is the message id, stable across re-runs: use it as the idempotency
   key for external I/O.
-
-A call cleared by `handle.session.clear()` before it receives its answer
-rejects with an `A2Error` whose code is `SESSION_CLEARED`. The handler may
-already have run. Over HTTP it's a `410`; see [Routes](/actors/routes).
+- **A clear** by `handle.session.clear()` before the answer rejects the
+  call with an `A2Error` whose code is `SESSION_CLEARED`. The handler
+  may already have run. Over HTTP it's a `410`.
 
 ## Send, don't wait
 
-`send` validates, appends the event durably, and returns without
-waiting for the handler.
-
 ```ts
 // anywhere on the server:
 import { vault } from '@/vault'
@@ -140,9 +119,9 @@ const { id } = await vault.actor('savings').send.deposit({ amount: 25 })
 // durably queued; the handler runs on the instance's lane
 ```
 
-Same mailbox, same ordering; the only difference is that nobody waits
-for the answer. Pass `{ id }` in the options to make a retried send
-idempotent.
+`send` validates and appends the event durably without waiting for the
+handler: same mailbox, same ordering. Pass `{ id }` in the options to
+make a retried send idempotent.
 
 ## Read without queueing
 
@@ -153,41 +132,24 @@ import { vault } from '@/vault'
 const { state } = await vault.actor('savings').state()
 ```
 
-A snapshot read. It never queues behind pending messages, and a new
+A snapshot read: it never queues behind pending messages, and a new
 instance reads as its seed state.
 
 ## State is remembered, not recomputed
 
-Every commit appends a state event to the instance's log, and reads
-fold those by last write wins. History is never reinterpreted: you can
-rewrite a handler freely without changing what any past commit means.
-(This is the opposite trade from [reducers](/concepts/state), which
-recompute views from events; actor state is the recorded decision
-itself.)
-
-Because state lives in the log, it holds to the same floor as any
-payload: plain JSON trees. A `Date`, a `Map`, or `NaN` fails the commit
-loudly instead of being silently coerced.
+Every commit appends a state event, and reads fold them by last write
+wins. Unlike [reducers](/contract/state), nothing is recomputed, so
+rewriting a handler never changes what a past commit means. State must
+be plain JSON: a `Date`, a `Map`, or `NaN` fails the commit loudly.
 
-Two consequences worth designing for:
-
-- **Old instances meet new code.** After a deploy, state written by the
-  previous version flows into the new handlers. Default new fields
-  defensively (`ctx.state.pending ??= {}` as a first line) instead of
-  assuming the latest shape.
-- **The seed applies to new instances only.** Changing `state` in the
-  definition does not migrate existing instances; they keep their
-  remembered state.
+- **Old instances meet new code.** After a deploy, default new fields
+  defensively (`ctx.state.pending ??= {}` as a first line).
+- **The seed applies to new instances only.** Changing `state` does not
+  migrate existing instances.
 
 ## The log is still there
 
-An actor is a layer over an ordinary A2 session, not a wall around
-one. `handle.session` is that session (history, streams, scheduling),
-the definition
-exposes its assembled `contract`, `server`, and `reducer`, and the full
-mailbox is visible in devtools. Event names starting with `a2.` are
-reserved for the actor's own bookkeeping.
-
-Next: [Concurrency](/actors/concurrency) for the execution
-model, [Deadlines and timers](/actors/timers) for scheduled events, and
-[Routes, clients, and React](/actors/routes) for the wire.
+`handle.session` is the instance's underlying session (history,
+streams, scheduling). The definition exposes its assembled `contract`,
+`server`, and `reducer`, and devtools show the full mailbox. Event
+names starting with `a2.` are reserved for the actor's own bookkeeping.

package/docs/actors/02-concurrency.mdx

@@ -1,50 +1,35 @@
 ---
 title: Concurrency
-description: "Each instance processes one message at a time. Slow work goes in concurrent handlers: they run in parallel and report back by sending events."
+description: "Each instance processes one message at a time. Slow work goes in concurrent handlers, which run in parallel and report back by sending events."
 ---
 
 ## One message at a time
 
-Every message an instance receives runs on its
-[lane](/concepts/handlers#lanes): a serial queue, one handler at a
-time, in arrival order. This is what makes handlers easy to trust. A
-handler always sees the state every previous message produced, its
-checks cannot be raced by another message, and its changes commit
-before the next message runs.
+Every message runs on the instance's [lane](/server/handlers#lanes):
+one handler at a time, in arrival order. A handler sees the state every
+previous message produced, no other message can race its checks, and
+its changes commit before the next message runs.
 
-The lane is per instance. A thousand vaults process in parallel; each
-vault processes in order. If a single instance receives more traffic
-than one queue can absorb, split the identity and give the work more
-instances (per user, per order, per document) instead of trying to
-make one instance concurrent.
-
-## The problem with slow work
-
-A serial handler holds the lane while it runs. If `withdraw` awaits a
-two-second bank API, every deposit waits behind it. The instance stays
-correct, but it stops responding.
-
-The fix is not to weaken the lane. It is to split the work: serial
-handlers make the decisions, concurrent handlers do the slow parts,
-and the results come back as events.
+Lanes are per instance: a thousand vaults process in parallel, each in
+order. If one instance gets more traffic than one queue can absorb,
+split the identity (per user, per order, per document) instead of
+making one instance concurrent.
 
 ## Concurrent handlers
 
-Wrap a handler in `concurrent(...)` and it leaves the lane: it runs in
-parallel with serial handlers and with other concurrent handlers. Two
-things change inside it:
+A serial handler holds the lane while it runs: if `withdraw` awaits a
+two-second bank API, every deposit waits behind it. Keep decisions
+serial and move the slow part into a handler wrapped in
+`concurrent(...)`. It leaves the lane and runs in parallel with serial
+handlers and other concurrent ones. Inside it:
 
-- There is no `ctx.state` draft to mutate. Reading state becomes a
-  function call, `ctx.state()`, and the snapshot it returns can go
-  stale while the handler keeps running.
-- State changes happen by sending events. Their serial handlers run on
-  the lane and decide against current state.
+- `ctx.state()` returns a snapshot, which can go stale while the
+  handler runs. There is no draft to mutate.
+- State changes happen by sending events, whose serial handlers decide
+  against current state.
 
 ## Reserve, transfer, settle
 
-A withdrawal that talks to a slow bank, without ever blocking the
-vault: reserve the money, run the transfer, then settle or refund.
-
 ```ts vault.ts
 import { NonRetriableError } from 'experimental-a2'
 import { actor, concurrent } from 'experimental-a2/actor'
@@ -109,46 +94,34 @@ export const vault = actor<Vault>({
 })
 ```
 
-Step by step:
-
-1. **`withdraw` reserves.** It runs on the lane, so the balance check
-   cannot be raced by another withdrawal. The balance drops, `pending`
-   records the reserved amount, and the `transfer` event commits
-   atomically with both. The withdrawal cannot half-start.
-2. **`transfer` does the slow part.** It runs off the lane, so
-   deposits keep flowing meanwhile. It finishes by sending an event:
-   `settle` on success, `refund` when the bank says no. It never
-   changes state itself, and it reports failure by sending, not by
-   throwing.
-3. **`settle` and `refund` finish the job.** Both check `pending[ref]`
-   first and return when the entry is gone, so a duplicate or late
-   message does nothing. The refund amount comes from state, not from
-   recomputing it.
-
-A crash at any step re-runs that one message from the state it started
-with. Wherever the process dies, the vault lands in a named state:
-reserved, settled, or refunded. Money is never half-transferred.
+1. **`withdraw` reserves** on the lane, so no other withdrawal can race
+   the balance check. The balance drop, the `pending` entry, and the
+   `transfer` event commit atomically: the withdrawal cannot
+   half-start.
+2. **`transfer` does the slow part** off the lane, so deposits keep
+   flowing. It never changes state, and it reports failure by sending
+   `refund`, not by throwing.
+3. **`settle` and `refund` finish.** Both return when `pending[ref]` is
+   gone, so a duplicate or late message does nothing. The refund amount
+   comes from state.
+
+A crash re-runs only that message from the state it started with, so
+the vault always lands reserved, settled, or refunded.
 
 ## Buffered sends
 
-`ctx.send` does not append immediately. Everything a handler sends is
-buffered and commits when the handler completes: for a serial handler,
-in the same commit as its state change; for a concurrent handler, when
-it finishes. A refusal discards the buffer along with the state
-changes, so a refused message leaves no trace. Re-runs produce the
-same message ids, so a retried handler does not append its sends
-twice.
+`ctx.send` buffers. A serial handler's sends commit with its state
+change; a concurrent handler's commit when it finishes. A refusal
+discards the buffer with the state changes, so a refused message leaves
+no trace. Re-runs produce the same message ids, so a retried handler
+never appends its sends twice. `ctx.schedule` is
+[not buffered](/actors/timers#scheduling-is-immediate).
 
 ## When handlers fail
 
-- A **serial** handler that throws `NonRetriableError` refuses the
-  message: nothing commits, and the caller gets the answer (see
-  [Introduction](/actors/introduction#refusals)).
-- A **serial** handler that throws anything else is retried on the
-  lane, and the instance waits. This is deliberate: state never
-  advances past a failure.
-- A **concurrent** handler that throws is retried off the lane;
-  nothing else waits for it.
-- `call` works on serial events only. A concurrent handler produces no
-  answer to wait for, so calling one is rejected: `send` those events
-  instead.
+A concurrent handler that throws retries off the lane, and nothing
+waits for it. Serial handlers fail as described in
+[Refusals](/actors/introduction#refusals).
+
+`call` works on serial events only. A concurrent handler produces no
+answer, so calling one is rejected: `send` those events instead.