experimental-a2 0.0.0

package/dist/server.browser.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/server.browser.js

@@ -0,0 +1,11 @@
+//#region src/server.browser.ts
+/**
+* The browser build of a2/server. There isn't one — on purpose.
+* Contracts and reducers (from `a2`) and the session client (from
+* `a2/client` / `a2/react`) are the isomorphic surface; the server is
+* where handlers and storage live. This module existing in a client
+* bundle means a `'use client'` file (or something it imports)
+* value-imported your server module.
+*/
+throw new Error("a2/server is server-only — a client bundle imported it. Import the contract (a2) or the session client (a2/client, a2/react) in browser code instead.");
+//#endregion

package/dist/server.d.ts

@@ -0,0 +1,136 @@
+import { i as EventDefs, n as Contract, r as ContractEvent, s as Reducer, t as AppendInput } from "./contract-DL8btVd9.js";
+import { a as Event, c as IdSource, d as LogStateRead, f as StoredEvent, h as StoredSnapshot, i as Clock, l as LogClaimResult, m as StoredSessionSummary, n as A2LogInspection, o as EventCause, p as StoredSessionPage, r as AppendEvent, s as FailAttemptResult, t as A2Log, u as LogHandoffResult } from "./log-Dg1I8NRr.js";
+import { i as A2Telemetry } from "./telemetry-C78al20p.js";
+//#region src/server.d.ts
+/**
+ * Events that arrived over the wire through `parsePushBody` — already
+ * envelope-validated, headed for schema validation inside `append`.
+ * The brand lets the documented push route hand them straight to
+ * `session.append` without weakening typed appends for app code: a
+ * hand-written `{ type: string }` literal still fails to compile.
+ */
+type PushedEvent = {
+  type: string;
+  payload: unknown;
+  id?: string;
+  readonly "~a2.pushed": true;
+};
+/** What every handler receives. */
+type HandlerContext<D extends EventDefs, K extends keyof D & string = keyof D & string> = {
+  /** The triggering event. */
+  event: ContractEvent<D, K>;
+  /** Durable, 1-based dispatch ordinal for this event. */
+  attempt: number;
+  /** Append what happens next to this session's log. Atomic per call. */
+  append: (...events: AppendInput<D>[]) => Promise<ContractEvent<D>[]>;
+  /** Every past event in this session, oldest first. Always the raw log. */
+  history: () => Promise<ContractEvent<D>[]>;
+  /** Fires on `abortOn` events (cancellation slice); dormant otherwise. */
+  signal: AbortSignal;
+};
+type Handler<D extends EventDefs, K extends keyof D & string = keyof D & string> = (ctx: HandlerContext<D, K>) => Promise<void>;
+/** A handle on one instance of the machine. Creating it does no I/O. */
+type Session<D extends EventDefs> = {
+  readonly sessionId: string;
+  append: {
+    (...events: AppendInput<D>[]): Promise<ContractEvent<D>[]>;
+    /** The push-route path: events from `parsePushBody`. */
+    (...events: PushedEvent[]): Promise<ContractEvent<D>[]>;
+  };
+  history(): Promise<ContractEvent<D>[]>;
+  state<S>(reducer: Reducer<D, S>): Promise<{
+    state: S;
+    index: number;
+  }>;
+  /**
+   * A live feed of this session's events, starting after `startAt`
+   * (exclusive). Server-side only — expose it over SSE with
+   * `sseResponse` from a2/http.
+   */
+  stream(opts?: {
+    startAt?: number;
+  }): AsyncIterable<ContractEvent<D>>;
+};
+/**
+ * What recovery needs from a server — structural, so servers of any
+ * contract mix in one `handler(...)` call. Deliberately tiny: recovery
+ * consults the log through `drain` and nothing else.
+ */
+type RecoverableServer = {
+  readonly contract: {
+    readonly name: string;
+  };
+  drain(sessionId: string): Promise<{
+    settled: boolean;
+  }>;
+};
+/**
+ * The recovery seam (a2-implementation.md §7, §9). `arm` puts a
+ * delayed, coalesced "drain this session" message on durable
+ * infrastructure while inline work starts; `handler` returns the route
+ * the transport delivers to. Lease holders move the watchdog alongside
+ * their renewable execution window. Implementations ship as
+ * entry points (`a2/recovery-vercel`); core never imports a transport.
+ */
+type A2Recovery = {
+  arm(opts: {
+    contract: string;
+    sessionId: string;
+    /** Earliest useful delivery as epoch milliseconds. */
+    dueAt?: number;
+  }): Promise<void>;
+  handler(...servers: RecoverableServer[]): (req: Request) => Promise<Response>;
+};
+type A2Server<D extends EventDefs> = {
+  /** The contract this server implements. */
+  readonly contract: Contract<D>;
+  session(id: string): Session<D>;
+  /**
+   * Process the session's pending events in order. `settled` means the
+   * drain left nothing actionable: every event processed, or the
+   * session is stalled at a dead-lettered event (which recovery
+   * transports treat as "stop redelivering").
+   */
+  drain(sessionId: string): Promise<{
+    settled: boolean;
+  }>;
+};
+/**
+ * Which events fire `ctx.signal` while a handler runs — the preemption
+ * channel for user cancellation. The array form matches by type; the
+ * object form takes per-type predicates for targeted cancellation
+ * (`(event, trigger) => event.payload.of === trigger.id`). Handlers
+ * without `abortOn` pay nothing. An aborted handler should catch and
+ * return normally; throwing means "retry me".
+ */
+type AbortSpec<D extends EventDefs, K extends keyof D & string> = Array<keyof D & string> | { [T in keyof D & string]?: true | ((event: ContractEvent<D, T>, trigger: ContractEvent<D, K>) => boolean); };
+type HandlerEntry<D extends EventDefs, K extends keyof D & string = keyof D & string> = Handler<D, K> | {
+  abortOn: AbortSpec<D, K>;
+  handler: Handler<D, K>;
+};
+type ServerOptions<D extends EventDefs> = {
+  /** The contract this server implements (see `a2.contract`). */
+  contract: Contract<D>;
+  /** Where events live. Defaults: sqlite in dev, memory in tests, required in prod. */
+  log?: A2Log;
+  /**
+   * Queue-backed recovery — e.g. `vercelQueues()` from
+   * `a2/recovery-vercel`. Absent means append-driven healing only: a
+   * working configuration, but a clockless one. Recommended in
+   * production.
+   */
+  recovery?: A2Recovery;
+  /** Optional instrumentation — e.g. `otel()` from `a2/otel`. */
+  telemetry?: A2Telemetry;
+  /**
+   * The reactions, keyed by event type — all present at construction,
+   * so a handler can never be silently missing because its module
+   * wasn't imported. Compose across files by spreading objects (note:
+   * a duplicate key under spread silently last-wins).
+   */
+  handlers?: { [K in keyof D & string]?: HandlerEntry<D, K>; };
+};
+/** Implement a contract: bind its vocabulary to storage and reactions. */
+declare function createServer<D extends EventDefs>(options: ServerOptions<D>): A2Server<D>;
+//#endregion
+export { type A2Log, type A2LogInspection, A2Recovery, A2Server, AbortSpec, type AppendEvent, type AppendInput, type Clock, type Contract, type ContractEvent, type Event, type EventCause, type EventDefs, type FailAttemptResult, Handler, HandlerContext, HandlerEntry, type IdSource, type LogClaimResult, type LogHandoffResult, type LogStateRead, PushedEvent, RecoverableServer, ServerOptions, Session, type StoredEvent, type StoredSessionPage, type StoredSessionSummary, type StoredSnapshot, createServer };

package/dist/server.js

@@ -0,0 +1,2 @@
+import { t as createServer } from "./server-DYsnKTTy.js";
+export { createServer };

package/dist/telemetry-C78al20p.d.ts

@@ -0,0 +1,32 @@
+//#region src/telemetry.d.ts
+/**
+ * The A2Telemetry interface — the instrumentation seam. Same philosophy
+ * as log backends: the interface lives in core, implementations ship as
+ * entry points (`a2/otel` adapts it to OpenTelemetry). Without one,
+ * every operation runs through a no-op wrapper.
+ */
+/** Attribute values a2 emits. */
+type A2AttributeValue = string | number | boolean;
+/** The spans a2 emits today. The catalogue grows with the surface. */
+type A2SpanName = "a2.append" | "a2.drain" | "a2.event" | "a2.state";
+type A2SpanHandle = {
+  /** Attach or update an attribute mid-span (e.g. the outcome). */
+  setAttribute(key: string, value: A2AttributeValue): void;
+  /**
+   * Mark the span failed without a2's control flow throwing — used for
+   * handler failures, which a2 swallows by design (they go into the
+   * retry machinery, not up the stack) but telemetry must still see.
+   */
+  recordError(error: unknown): void;
+};
+type A2Telemetry = {
+  /**
+   * Wrap one unit of a2 work. Implementations should time it, record a
+   * thrown error as a failure, propagate context so nested spans tree
+   * up, and always return `fn`'s result (or rethrow its error) —
+   * telemetry observes, it never alters behavior.
+   */
+  span<T>(name: A2SpanName, attributes: Record<string, A2AttributeValue>, fn: (span: A2SpanHandle) => Promise<T>): Promise<T>;
+};
+//#endregion
+export { A2Telemetry as i, A2SpanHandle as n, A2SpanName as r, A2AttributeValue as t };

package/dist/validate-XKT4FSNn.js

@@ -0,0 +1,28 @@
+//#region src/validate.ts
+/**
+* Run a Standard Schema validator, requiring a synchronous result.
+* Validators must be synchronous (specs/a2-api.md §1) — an async one is
+* a definition bug, rejected at definition time where possible and here
+* as a backstop. `what` names the schema in error messages, e.g.
+* "event 'created'" or "the stateSchema".
+*/
+function validateSync(schema, value, what) {
+	const result = schema["~standard"].validate(value);
+	if (result instanceof Promise) throw new TypeError(`the schema for ${what} is asynchronous — a2 schemas must validate synchronously`);
+	return result;
+}
+/**
+* Probe a schema to reject always-async validators early. The probe
+* value is deliberately garbage — we only care whether the result is a
+* Promise, not whether it passes.
+*/
+function assertSyncSchema(schema, what) {
+	const probe = Symbol("a2.schema-probe");
+	const result = schema["~standard"].validate(probe);
+	if (result instanceof Promise) {
+		result.catch(() => {});
+		throw new TypeError(`the schema for ${what} is asynchronous — a2 schemas must validate synchronously`);
+	}
+}
+//#endregion
+export { validateSync as n, assertSyncSchema as t };

package/dist/wire-2QpU1EtJ.js

@@ -0,0 +1,62 @@
+import { t as A2Error } from "./errors-BJRMd-h6.js";
+//#region src/wire.ts
+/**
+* The wire format shared by a2/http (server side) and a2/client
+* (browser side): events as JSON with ISO timestamps, and the A2Error
+* envelope. Internal module — both entry points re-export what's
+* public.
+*/
+function eventToWire(event) {
+	return {
+		id: event.id,
+		type: event.type,
+		payload: event.payload,
+		index: event.index,
+		sessionId: event.sessionId,
+		createdAt: event.createdAt.toISOString()
+	};
+}
+function eventFromWire(wire) {
+	return {
+		id: wire.id,
+		type: wire.type,
+		payload: wire.payload,
+		index: wire.index,
+		sessionId: wire.sessionId,
+		createdAt: new Date(wire.createdAt)
+	};
+}
+function isWireEvent(value) {
+	if (value === null || typeof value !== "object") return false;
+	const v = value;
+	return typeof v["id"] === "string" && typeof v["type"] === "string" && typeof v["index"] === "number" && typeof v["sessionId"] === "string" && typeof v["createdAt"] === "string";
+}
+const ERROR_STATUS = {
+	INVALID_PAYLOAD: 400,
+	UNKNOWN_EVENT_TYPE: 400,
+	PARTIAL_DUPLICATE_BATCH: 400,
+	LOG_UNAVAILABLE: 503,
+	LOG_NOT_CONFIGURED: 500
+};
+function errorStatus(code) {
+	return ERROR_STATUS[code];
+}
+function errorToWire(error) {
+	const body = { error: {
+		code: error.code,
+		message: error.message
+	} };
+	if (error.details !== void 0) body.error.details = error.details;
+	return body;
+}
+/** Rebuild an A2Error from a wire body; null if the body isn't one. */
+function errorFromWire(body) {
+	if (body === null || typeof body !== "object") return null;
+	const err = body.error;
+	if (err === null || typeof err !== "object") return null;
+	const { code, message, details } = err;
+	if (typeof code !== "string" || !(code in ERROR_STATUS)) return null;
+	return new A2Error(code, String(message ?? code), { details });
+}
+//#endregion
+export { eventToWire as a, eventFromWire as i, errorStatus as n, isWireEvent as o, errorToWire as r, errorFromWire as t };

package/docs/01-quickstart.mdx

@@ -0,0 +1,214 @@
+---
+title: Quickstart
+description: Define one lifecycle, implement its reactions, and make your first durable append in about 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.
+
+## 1. Install
+
+```package-install
+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 entire upfront declaration. No state list, no transition
+table.
+
+```ts server/orders.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({}),
+  },
+})
+```
+
+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 log.
+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):
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+
+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: {} })
+    },
+  },
+})
+```
+
+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:
+
+- 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 `append` inside a handler is already deduplicated. If the handler
+  crashes after appending and runs again, the second append is a no-op,
+  [here's how](/concepts/handlers#handlers-can-run-twice).
+
+## 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'
+
+export async function POST(req: Request) {
+  const { orderId, shopId, items } = await req.json()
+
+  await ordersServer.session(orderId).append({
+    type: 'created',
+    payload: { shopId, items },
+  })
+
+  return Response.json({ ok: true })
+}
+```
+
+A session is one instance of the contract. `ordersServer.session('order-42')`
+is order 42's lifecycle: the unit A2 orders, recovers, folds, and streams.
+Creating the handle does no I/O, and the id is yours to choose.
+
+Try it:
+
+```bash
+curl -X POST localhost:3000/api/orders \
+  -H 'content-type: application/json' \
+  -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.
+
+When the append returns, the event is durably in the log and A2 has started the
+`created` handler inline. In production, queue-backed recovery wakes pending
+work after a failure or process death. See [Durability](/concepts/durability)
+for the exact contract.
+
+## 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'
+
+export async function GET(
+  _req: Request,
+  { params }: { params: Promise<{ orderId: string }> },
+) {
+  const { orderId } = await params
+  const events = await ordersServer.session(orderId).history()
+  return Response.json(events)
+}
+```
+
+```bash
+curl localhost:3000/api/orders/order-42
+```
+
+```json
+[
+  { "index": 1, "type": "created", "payload": { "shopId": "shop-7", "items": ["flat white"] } },
+  { "index": 2, "type": "shop.notified", "payload": {} }
+]
+```
+
+(Trimmed for brevity; each event also carries `id`, `sessionId`, and
+`createdAt`.)
+
+That second event is the payoff. You appended one event; the handler
+appended the next; the log shows the whole story, in order. This is what
+debugging looks like in A2: you read.
+
+## 6. Fold state out of the log
+
+Raw session history is truth, but UIs usually want a view. Define a reducer
+once:
+
+```ts reducer.ts
+import { orders } from '@/server/orders'
+
+export const ordersReducer = orders
+  .reducer({ 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:
+
+```ts
+// anywhere on the server:
+import { ordersServer } from '@/server/orders'
+import { ordersReducer } from '@/reducer'
+
+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).
+
+## 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.
+
+<CardGroup cols={2}>
+  <Card title="Handlers" href="/concepts/handlers" icon="file">
+    The context object, chaining, ordering, and re-runs.
+  </Card>
+  <Card title="Going to production" href="/guides/production" icon="rocket">
+    Postgres, queue-backed recovery, and dead-letter resolution.
+  </Card>
+</CardGroup>

package/docs/concepts/01-contracts.mdx

@@ -0,0 +1,138 @@
+---
+title: Contracts and sessions
+description: A contract names one kind of lifecycle. A session is one instance, with its own history, ordering, state, and live stream.
+---
+
+## Contracts
+
+A2 has two nouns. A **contract** defines what can happen in one kind of
+lifecycle. A **session** is one instance of it.
+
+```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({}),
+    'shop.started': z.object({}),
+    'driver.notified': z.object({ driverId: z.string() }),
+    expired: z.object({}),
+  },
+})
+```
+
+The name identifies the contract everywhere: in storage, in queue
+messages, in logs. It's what keeps an app with several contracts
+unambiguous.
+
+`events` is the contract's full vocabulary. Each key is an event name;
+each value is a schema for its payload. Zod in these docs, but any
+[Standard Schema](https://standardschema.dev) library works: Valibot,
+ArkType, your own. Every append is validated against it: a bad payload
+throws `INVALID_PAYLOAD` before anything is written, an unknown type
+throws `UNKNOWN_EVENT_TYPE`. What lands in the log is the validated
+output, with defaults applied and transforms run.
+
+The contract is a plain, importable, **isomorphic** value. It carries
+nothing but schemas. The server implements it, [reducers](/concepts/state)
+derive from it, and the browser types its pushes off it. One artifact,
+shared by every side of the wire.
+
+And that's the entire declaration. No states, no transition table. What
+happens on each event is defined where the contract is served; what
+things look like right now is defined by [reducers](/concepts/state). The
+contract just names the vocabulary.
+
+:::tip
+Events are facts, so name them in past tense: `created`, `expired`,
+`shop.notified`. If a name reads like a command (`notifyShop`), it's
+describing what a handler should do, not what happened. Dots are a naming
+convention, not a namespace.
+:::
+
+## Serving a contract
+
+Handlers and storage bind to the contract with `createServer` from
+`experimental-a2/server`, the entry point that is allowed to touch a log backend
+(and the one that fails loudly if a browser bundle ever imports it):
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { postgres } from 'experimental-a2/log-postgres'
+import { orders } from '@/contracts'
+
+export const ordersServer = createServer({
+  contract: orders,
+  log: postgres({ connectionString: process.env.DATABASE_URL }),
+  handlers: {
+    created: async ({ event, append }) => {
+      // your side effect, then:
+      await append({ type: 'shop.notified', payload: {} })
+    },
+  },
+})
+```
+
+Handlers are one table of reactions, declared at construction, so a
+handler can never be silently missing because the module that would
+have registered it wasn't imported. Compose across files by spreading
+objects into `handlers`.
+
+| Entry point       | Backend   | Use it for                                |
+| ----------------- | --------- | ----------------------------------------- |
+| `experimental-a2/log-postgres` | Postgres  | Production                                 |
+| `experimental-a2/log-sqlite`   | SQLite    | Development: the default, at `.a2/dev.db`  |
+| `experimental-a2/log-memory`   | In-memory | Tests: the default when `NODE_ENV=test`    |
+
+When you omit `log`, development gets SQLite (state survives `next dev`
+restarts) and tests get memory. Production gets an error: the server
+throws `LOG_NOT_CONFIGURED` at startup rather than guess where your
+events should live. A failed boot beats events written to a filesystem
+that evaporates.
+
+## Sessions
+
+```ts
+// anywhere on the server: a route, a handler, a script
+const order = ordersServer.session('order-42')
+```
+
+A session is one instance of the contract: one order, one signup, one
+chat, one approval, one import. It has its own log, its own ordering, its own
+state, and its own live stream. The id is yours: use whatever identifies the
+subject in your system.
+
+Creating a session does no I/O. It's a handle; nothing loads until you
+append, read, or stream.
+
+Sessions are also the unit of ordering: events within one session are
+processed serially, in log order. Different sessions never wait for each
+other. More in [Handlers](/concepts/handlers#ordering).
+
+## Pick the boundary
+
+The session is the boundary A2 keeps durable and synchronized. Put events in
+the same session when they must be ordered, folded, recovered, or viewed
+together. Split things that should progress independently.
+
+A contract is not a database table, and a session is not a table or a general
+query boundary. One contract serves every instance of that lifecycle. An
+`orders` contract may serve millions of order sessions through the same server
+and handler table.
+
+This boundary works well when someone opens a thing by id and watches it
+progress. Collections, joins, search, and constraints across many records
+usually belong in an application database. See
+[A2 and your database](/guides/application-data).
+
+## One more option: recovery
+
+Servers accept a `recovery` option, which arms a durable, delayed drain
+for every top-level append, giving crash recovery and handler retries in one
+mechanism. The handler starts without waiting for recovery, and a successful
+initial arm is durable before `append` returns. It changes how fast A2 heals,
+not how it works. Everything in these concept pages holds with or without it.
+Covered in [Going to production](/guides/production).