experimental-a2 0.0.0

package/docs/guides/07-devtools.mdx

@@ -0,0 +1,101 @@
+---
+title: Devtools
+description: Mount one read-only handler to inspect sessions, event lifecycles, failures, and snapshots from the durable log.
+---
+
+## Mount the dashboard
+
+The devtools application is one HTTP handler. Give it every A2 server you want
+to inspect, then mount it on a route that matches the root and its child paths.
+In Next.js, an optional catch-all route does both:
+
+```ts app/api/a2/devtools/[[...path]]/route.ts
+import { createDevtools } from 'experimental-a2/devtools/server'
+import { billingServer, ordersServer } from '@/server'
+
+const devtools = createDevtools({
+  servers: [ordersServer, billingServer],
+  authorize: async (_request) => {
+    // Return true after your auth or any other checks.
+    return process.env.NODE_ENV !== 'production'
+  },
+})
+
+export const GET = devtools.handler()
+```
+
+Open `/api/a2/devtools`. There is no client factory, provider, React component,
+or separate datastore. The handler serves the browser application itself and
+reads the same log as the servers.
+
+The initial HTML contains the first page of the selected contract's sessions
+and the selected session's durable detail. The browser starts from that
+bootstrap data without a loading screen or an initial API request waterfall,
+then takes over navigation and live updates.
+
+The selected contract and session stay in the URL. Refreshing preserves the
+view, links open the same session, and browser back and forward navigation work.
+
+Omit `authorize` for the same development-only behavior shown above. An
+unguarded handler returns 404 in production. In a deployed dashboard, provide
+your application's access check. Returning `false` hides the route with a 404;
+returning a `Response` supports a redirect or authentication challenge.
+
+## Causal forest
+
+Every stored `cause` connects a child to the event index and handler attempt
+whose `ctx.append` first persisted it. The dashboard builds that forest
+directly from the session log. It does not need a trace table or another write
+on the append path.
+
+A null cause appears as **origin unknown**. New top-level appends write null,
+but events written before causal metadata also read as null. The dashboard does
+not guess which one it is. If a cause points outside the visible log, the row
+keeps the stored edge and marks its parent unavailable.
+
+## What the timeline means
+
+Each row is one durable event. Its bar begins at `createdAt`, when the event
+entered the log, and ends at `processedAt` or `failedAt`. A pending event stays
+open. Markers show the operation boundaries A2 stores:
+
+- first and latest dispatch from `firstClaimedAt` and `lastClaimedAt`
+- latest caught failure from `lastFailedAt` and `lastFailedAttempt`
+- completion from `processedAt` and `processedByAttempt`
+- dead-lettering from `failedAt`
+
+`attemptCount` counts every durable dispatch claim. `failureCount` counts only
+caught handler failures. A hard crash can increase the first without
+increasing the second. The dashboard calls that difference a dispatch without
+an outcome because it may be active work, a hard crash, or a superseded
+attempt. It does not claim to know which one occurred.
+
+Migrated events can have an `attemptCount` without a `firstClaimedAt`. The
+dashboard shows the first dispatch time as unknown instead of moving it to
+`createdAt` or `lastClaimedAt`.
+
+The bar is event lifetime, not handler execution time. A2 stores lifecycle
+summaries, not one span row for every attempt. Time spent waiting, running a
+handler, coordinating a lease, or waiting for recovery remains one honest
+interval.
+
+Snapshots appear as their reducer name, event frontier, and last update time.
+The dashboard does not send cached snapshot state to the browser.
+
+## Live updates
+
+The selected session opens an SSE connection to the same handler. The stream
+sends invalidations, not a second copy of state. On each invalidation the
+browser reads the durable session again. A disconnected browser can miss every
+frame and still become correct immediately after reconnecting.
+
+While work is pending, the handler checks processing metadata quickly. It
+backs off after the session settles and emits heartbeats for intermediaries.
+Only sessions someone is viewing have a live inspection loop.
+
+## Custom logs
+
+The memory, SQLite, Postgres, and Redis adapters provide the optional read-only
+inspection interface. A custom `A2Log` can implement `inspect.listSessions`
+and `inspect.listSnapshots` to appear in the dashboard. Logs without inspection
+continue to work normally; their devtools endpoint returns 501.

package/docs/guides/08-application-data.mdx

@@ -0,0 +1,114 @@
+---
+title: A2 and your database
+description: Use A2 for things with a lifecycle. Keep collections, relationships, and queries in your application database.
+---
+
+## Start with ownership
+
+A2 does not replace your application database. It synchronizes one known
+session at a time: its events, its derived state, and optimistic writes from
+the browser. It does not synchronize tables or database queries.
+
+Use your database for the records and relationships that the rest of the
+application queries.
+
+Decide which system owns each fact:
+
+- If A2 owns it, append an event and derive the session's state with a reducer.
+- If your database owns it, write it with the database's normal transaction.
+
+Do not make both paths authoritative for the same fact.
+
+## What belongs in A2
+
+A2 fits something with a lifecycle: an order moving through fulfillment, an
+agent producing a response, an approval waiting for a decision, or an import
+that can fail and resume.
+
+A **contract** names the events in one kind of lifecycle. A **session** is one
+instance of it:
+
+```text
+orders / order-42
+orders / order-43
+agents / run-abc
+```
+
+The session is the boundary A2 orders, recovers, folds, and streams. Put events
+in the same session when they must be ordered or viewed together. Split work
+that should progress independently.
+
+A contract is not a table. A session is not a table either. One contract
+usually serves many sessions, and one session may describe changes that touch
+several records elsewhere in an application.
+
+## What belongs in the database
+
+Use your application database for collections and relationships: accounts,
+projects, issue lists, labels, permissions, search, joins, pagination, and
+reporting. Use its transactions for constraints that must hold across several
+rows before a request returns.
+
+The Postgres adapter in `experimental-a2/log-postgres` stores A2's own logs. It does not
+watch your application tables, turn their changes into events, or combine an
+A2 append with your SQL transaction. The A2 log and your tables may share one
+Postgres database, but they remain separate data models and transaction
+boundaries.
+
+## An issue tracker
+
+An issue tracker is mostly a collection and query product. Postgres should
+usually own its core data:
+
+| Part | Owner |
+| --- | --- |
+| issues, projects, labels, comments | Postgres |
+| permissions, board filters, search | Postgres |
+| an AI investigation attached to an issue | one A2 session |
+| an import or automation run | one A2 session |
+
+The A2 session can store the investigation's messages, progress, tool calls,
+approval, and result. It refers to the issue id, but it does not become a
+second owner of the issue.
+
+An individual issue also has a lifecycle, so A2 can own it when the issue's
+ordered history and live state are the center of the product. That choice has
+a cost: boards and search span many sessions and need another query model. If
+those collection views are the center of the product, let the database lead.
+
+Do not put an entire workspace in one session just to make cross-issue queries
+possible. Every event in one session is ordered together, and every client of
+that session follows the same growing log.
+
+## Database writes from handlers
+
+Handlers may call your database like any other side effect. They are
+at-least-once, so make the write idempotent with `event.id`. The event is
+durable before the handler runs, and the SQL write may happen later or be
+retried.
+
+That is a good fit for a reaction to a lifecycle event. It is not one atomic
+write across A2 and your tables. If a relational change must commit before the
+request succeeds, make that change through the database's write path.
+
+## Cross-session indexes
+
+Sometimes an A2-owned lifecycle needs a small database index, such as a list of
+active imports. A handler can maintain that index. Treat it as an advanced
+integration:
+
+- it is eventually consistent with the session logs;
+- writes must be idempotent;
+- A2 orders events within one session, not across sessions;
+- A2 does not expose one API that scans and replays every session to rebuild
+  the index.
+
+Back up and migrate that index like application data. If search, joins, and
+cross-session reporting are central rather than incidental, the database
+should probably own that domain.
+
+## The short version
+
+Use A2 when people open something by id and watch it progress. Use your
+database when people list, filter, join, and edit many records. In an
+application that needs both, split ownership along that line.

package/docs/index.mdx

@@ -0,0 +1,282 @@
+---
+title: Introduction
+description: A2 is durable sync and reactions for things with a lifecycle. Append events, run handlers, and keep one live view from server to browser.
+---
+
+```bash
+pnpm add experimental-a2
+```
+
+A2 is durable sync and reactions for things with a lifecycle.
+
+An order, agent run, approval, or import gets a session. You append events.
+Handlers react to them, and usually append the next one. The browser follows
+the same log and folds the same state as the server. That's the whole model;
+the rest of this page is it happening.
+
+There is no declared state machine. Events record facts, reducers compute the
+current view, and handlers perform the reactions.
+
+## Define a contract
+
+Events are the vocabulary. A contract names them once, as a plain
+importable value. The server implements it, and the browser types itself
+off it later.
+
+```ts contracts.ts
+import { z } from 'zod'
+import * as a2 from 'experimental-a2'
+
+export const orders = a2.contract({
+  name: 'orders',
+  events: {
+    created: z.object({ items: z.array(z.string()) }),
+    'shop.notified': z.object({}),
+    cancelled: z.object({}),
+  },
+})
+```
+
+## React to events
+
+Handlers are plain async functions: no determinism rules, no replay, no
+wrappers around side effects. Each one reacts to a fact and usually
+appends 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; event.id makes a stable idempotency key:
+      // await notifyShop(event.payload, { idempotencyKey: event.id })
+      await append({ type: 'shop.notified', payload: {} })
+    },
+  },
+})
+```
+
+## Open a session
+
+A session is one instance of the contract, with its own log and its own
+ordering. It is the thing A2 keeps durable and live. The id is yours:
+
+- `session('order-8194')`: an order moving through fulfillment
+- `session('chat-a8c1')`: an agent chat streaming its reply
+- `session('cart-julian')`: a shopping cart
+- `session('doc-roadmap')`: a document with three people typing in it
+
+Anything whose story spans more than one request. Put events in the same
+session when they must be ordered or viewed together. Any server code can open
+one and append: a route handler, a webhook, a cron job.
+
+```ts app/api/orders/route.ts
+import { ordersServer } from '@/server/orders'
+
+export async function POST(req: Request) {
+  const body = await req.json()
+  await ordersServer.session(body.orderId).append({
+    type: 'created',
+    payload: { items: body.items },
+  })
+  return Response.json({ ok: true })
+}
+```
+
+That append is durable. The event hits the log before anything else happens,
+then A2 starts its handler inline. In production, queue-backed recovery wakes
+pending work after a crash or timeout.
+
+## State is a fold
+
+There is no separate state record for the session to keep in sync. Fold its log
+through a reducer, a pure function derived from the contract. It imports
+nothing server-only, which is about to matter.
+
+```ts reducer.ts
+import { orders } from '@/contracts'
+
+export const orderStatus = orders
+  .reducer({ name: 'order-status', initialState: { status: 'new' } })
+  .fold((state, event) => {
+    switch (event.type) {
+      case 'created':
+        return { status: 'created' }
+      case 'shop.notified':
+        return { status: 'notified' }
+      case 'cancelled':
+        return { status: 'cancelled' }
+      default:
+        return state
+    }
+  })
+```
+
+```ts
+// anywhere on the server:
+import { ordersServer } from '@/server/orders'
+import { orderStatus } from '@/reducer'
+
+const { state } = await ordersServer.session(orderId).state(orderStatus)
+// state → { status: 'notified' }
+```
+
+## The browser joins the session
+
+The reducer is isomorphic, so the browser runs the same fold the server
+does. A session streams to the client live and takes optimistic writes,
+all typed by the one contract:
+
+```ts app/orders/[orderId]/session.ts
+'use client'
+import { createReact } from 'experimental-a2/react'
+import { orderStatus } from '@/reducer'
+
+export const { SessionProvider, useSession } = createReact({
+  reducer: orderStatus,
+})
+```
+
+```tsx app/orders/[orderId]/order-client.tsx
+'use client'
+import { useSession } from './session'
+
+export function OrderStatus() {
+  const { state, connection, push } = useSession()
+  return (
+    <div>
+      {state.status}
+      {connection.status === 'live' ? ' · live' : ''}
+      <button onClick={() => void push({ type: 'cancelled', payload: {} })}>
+        Cancel order
+      </button>
+    </div>
+  )
+}
+```
+
+`push` applies instantly, validates against the contract before anything
+leaves the browser, and rolls back if the server says no. Mounting
+`SessionProvider` and the small stream route it talks to takes about
+twenty lines; [Live UI](/guides/react) wires it end to end.
+
+## The properties
+
+- **Handlers are plain async functions.** If it runs on your laptop, it
+  runs in production.
+- **History is real.** [`history()`](/concepts/state) returns what
+  actually happened, in order. Debugging is reading, not reconstructing.
+- **Nothing inside a session is sacred except its log.** Snapshots, leases, queue
+  messages: all disposable caches. Delete them and A2 rebuilds
+  everything from the log.
+
+## FAQ
+
+<details>
+<summary>Why not a workflow engine?</summary>
+
+Workflow engines replay your code from the top on every wake-up. So the
+code has to be deterministic, so every side effect gets wrapped in a step
+function, and `sleep()` becomes something magical instead of something
+you'd never call in a serverless function.
+
+A2's answer is older and simpler: write everything down. Every meaningful
+thing that happens is an event in a log. Handlers are stateless functions
+that react to one event at a time. State isn't stored. It's computed, by
+folding over the log whenever you need it. There's no orchestrator to
+operate.
+
+</details>
+
+<details>
+<summary>Isn't this just event sourcing?</summary>
+
+It's the useful core of it. A log of facts, state as a fold: the idea is
+decades old, and it's a good one. A2 cuts the ceremony that made it a big
+commitment. No command bus, no projection cluster, no upcasting
+framework. A contract, a log, handlers, reducers.
+
+</details>
+
+<details>
+<summary>How do I wait five days?</summary>
+
+You don't sleep. You schedule an event. Anything that can deliver an
+HTTP call later (QStash, a cron, a payment provider's webhook) hits a
+route that appends. The scheduled thing is data, a session id plus an
+event, not a suspended function. See [Timers](/guides/timers).
+
+</details>
+
+<details>
+<summary>How do I cancel work that's already running?</summary>
+
+Cancellation is an event too: same route, same auth, same log. Handlers
+opt in with `abortOn` and receive a live `AbortSignal`; reducers cut the
+derived view exactly. See [Cancellation](/guides/cancellation).
+
+</details>
+
+<details>
+<summary>What happens when a handler keeps failing?</summary>
+
+It retries with backoff, then dead-letters after ten caught failures, and the
+session stalls at that event, visibly, instead of silently skipping it.
+[Durability](/concepts/durability) has the exact guarantees and the
+recovery story behind them.
+
+</details>
+
+<details>
+<summary>What does production need?</summary>
+
+Two decisions: a log backend (Postgres or Redis) and queue-backed
+recovery. Development needs neither. SQLite appears under `.a2/` and
+state survives restarts. See [Going to production](/guides/production).
+
+</details>
+
+<details>
+<summary>What does A2 sync?</summary>
+
+One session whose id the application already knows. The browser follows its
+events, folds them into live state, and can push changes optimistically. A2
+does not replicate database tables or subscribe to queries across sessions.
+
+</details>
+
+<details>
+<summary>Where does my application database fit?</summary>
+
+A2 does not replace it. Use A2 for things with a lifecycle. Keep collections,
+relationships, constraints, search, and reporting in your application
+database. Split ownership instead of writing the same fact through both paths.
+See [A2 and your database](/guides/application-data).
+
+</details>
+
+## Where to next
+
+<CardGroup cols={2}>
+  <Card title="Quickstart" href="/quickstart" icon="rocket">
+    A contract, a handler, and a durable append in five minutes.
+  </Card>
+  <Card title="Contracts and sessions" href="/concepts/contracts" icon="folder">
+    The two nouns you'll use everywhere.
+  </Card>
+  <Card title="Durability" href="/concepts/durability" icon="wrench">
+    What A2 guarantees, and exactly how.
+  </Card>
+  <Card title="Live UI with React" href="/guides/react" icon="lightbulb">
+    Stream a session to the browser with optimistic writes.
+  </Card>
+  <Card title="Durable AI agents" href="/guides/ai-agents" icon="bot">
+    Run AI SDK agents with durable messages, progress, tools, and approvals.
+  </Card>
+  <Card title="A2 and your database" href="/guides/application-data" icon="database">
+    Decide what belongs in a session and what belongs in ordinary tables.
+  </Card>
+</CardGroup>