@abloatai/ablo 0.3.0

package/docs/mcp/cursor.md

@@ -0,0 +1,53 @@
+# Cursor
+
+## Install
+
+Add the Ablo Sync MCP server to Cursor's `mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ablo-sync": {
+      "transport": "http",
+      "url": "https://<your-app>/api/mcp"
+    }
+  }
+}
+```
+
+The file lives at `~/.cursor/mcp.json` on macOS / Linux.
+
+Restart Cursor. The Ablo Sync tools appear under the MCP icon in the agent
+panel.
+
+## With auth
+
+Add a `headers` block:
+
+```json
+{
+  "mcpServers": {
+    "ablo-sync": {
+      "transport": "http",
+      "url": "https://<your-app>/api/mcp",
+      "headers": {
+        "Authorization": "Bearer $ABLO_MCP_TOKEN"
+      }
+    }
+  }
+}
+```
+
+Cursor expands shell-style env vars in this block. Set `ABLO_MCP_TOKEN`
+in your shell config.
+
+## Verify
+
+In Cursor's agent panel, open the MCP tools list. You should see the
+Ablo Sync resource tools and their JSON schemas.
+
+## More
+
+- [MCP overview](/docs/mcp) — how the transport works.
+- [Claude Code setup](/docs/mcp/claude-code) — CLI install.
+- [Windsurf setup](/docs/mcp/windsurf) — same JSON shape.

package/docs/mcp/windsurf.md

@@ -0,0 +1,46 @@
+# Windsurf
+
+## Install
+
+Add the Ablo Sync MCP server to Windsurf's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "ablo-sync": {
+      "transport": "http",
+      "url": "https://<your-app>/api/mcp"
+    }
+  }
+}
+```
+
+The config path differs by platform — Windsurf surfaces it in Settings →
+Cascade → MCP. Restart Windsurf after saving.
+
+## With auth
+
+```json
+{
+  "mcpServers": {
+    "ablo-sync": {
+      "transport": "http",
+      "url": "https://<your-app>/api/mcp",
+      "headers": {
+        "Authorization": "Bearer $ABLO_MCP_TOKEN"
+      }
+    }
+  }
+}
+```
+
+## Verify
+
+Cascade's MCP panel lists every configured server with its tools. You
+should see `ablo-sync` with resource tools enumerated.
+
+## More
+
+- [MCP overview](/docs/mcp) — how the transport works.
+- [Claude Code setup](/docs/mcp/claude-code) — CLI install.
+- [Cursor setup](/docs/mcp/cursor) — same JSON shape.

package/docs/mcp.md

@@ -0,0 +1,59 @@
+# Model Context Protocol
+
+Ablo Sync ships an MCP server at `/api/mcp`. Connect any MCP-compatible AI
+assistant — Claude Code, Cursor, Windsurf — and your sync resources become
+typed, callable tools.
+
+## Install
+
+Pick your client:
+
+- [Claude Code](/docs/mcp/claude-code)
+- [Cursor](/docs/mcp/cursor)
+- [Windsurf](/docs/mcp/windsurf)
+
+## How it works
+
+Each resource you declare becomes one or more MCP tools:
+
+| Resource method | MCP tool name | What it does |
+|---|---|---|
+| `retrieve` | `<resource>.retrieve` | Returns the row + a stamp. |
+| `list` | `<resource>.list` | Cursor-paginated discovery. |
+| `update` | `<resource>.update` | Write, requires the prior stamp. |
+| `intents.create` | `intent.create` | Declare a claim before writing. |
+
+The assistant gets typed JSON schemas, real argument types, and typed
+rejections when it writes stale state. No invention, no hallucinated IDs.
+
+## Auth
+
+The MCP transport requires a capability token. Create one scoped to the
+assistant's session:
+
+```ts
+const capability = await ablo.capabilities.create({
+  participantKind: 'agent',
+  participantId: 'agent:claude-code',
+  // Strings derive from the schema's `identityRoles` templates
+  // (see integration-guide.md §1).
+  syncGroups: ['org:acme'],
+  operations: ['tasks.retrieve', 'tasks.update'],
+  label: 'claude-code dev session',
+  lease: '8h',
+});
+```
+
+Pass `capability.token` into the MCP client's auth header configuration.
+See your client's setup guide for the exact mechanism.
+
+## Limits
+
+The MCP endpoint is rate-limited per token. Read-heavy bursts are fine;
+write-heavy bursts get throttled at the dashboard-configured cap.
+
+## More
+
+The [MCP landing page](/mcp) has the product pitch. The route handler
+itself is at `apps/sync-web/src/app/api/mcp/route.ts` if you want to read
+the implementation.

package/docs/quickstart.md

@@ -0,0 +1,152 @@
+# Quickstart
+
+Declare your state, create one row, and make one confirmed update.
+
+If you already have a backend and database, still start here. The SDK call shape
+is the same; [Integration Guide](./integration-guide.md) explains when to use
+Ablo-managed state versus a Data Source that calls your existing API service.
+
+## 1. Install
+
+```bash
+npm install @ablo/sync-engine
+```
+
+## 2. Set a Sandbox Key
+
+Use an Ablo sandbox key while integrating.
+
+```bash
+export ABLO_API_KEY=sk_test_...
+```
+
+`ABLO_API_KEY` is for trusted server runtimes. Browser apps should use the React
+provider with a scoped capability/session route, not a bundled API key.
+
+## 3. Declare a Schema
+
+```ts
+import Ablo from '@ablo/sync-engine';
+import { defineSchema, model, z } from '@ablo/sync-engine/schema';
+
+const schema = defineSchema({
+  weatherReports: model({
+    location: z.string(),
+    status: z.enum(['pending', 'ready']),
+    forecast: z.string().optional(),
+  }),
+});
+
+export const ablo = Ablo({
+  schema,
+  apiKey: process.env.ABLO_API_KEY,
+});
+```
+
+Pass `schema` for typed model resources. Omit it only for advanced server-side
+resource clients such as custom agents and MCP routes.
+
+## 4. Create and Update
+
+```ts
+await ablo.ready();
+
+const created = await ablo.weatherReports.create({
+  location: 'Stockholm',
+  status: 'pending',
+});
+
+const updated = await ablo.weatherReports.update(created.id, {
+  status: 'ready',
+  forecast: 'Light rain, 13C',
+});
+
+console.log({ id: updated.id, status: updated.status });
+```
+
+Expected output:
+
+```txt
+{ id: '...', status: 'ready' }
+```
+
+## 5. Run the Example
+
+```bash
+cd examples
+ABLO_API_KEY=sk_test_... npx tsx quickstart.ts
+```
+
+## 6. AI Activity on Existing State
+
+Use `edit` when AI or background work will touch an existing row for more than a
+quick write. Other participants can see the activity while your code runs. The
+activity is cleared when `update` finishes; call `release` if the work ends
+without a write.
+
+```ts
+const edit = await ablo.weatherReports.edit('weather_stockholm', {
+  activity: 'checking_weather',
+  field: 'forecast',
+  ttl: '2m',
+});
+
+// Your existing weather tool or agent call. While this runs, other clients see
+// that weather_stockholm is being checked.
+const weather = await weatherAgent.getWeather(edit.current.location, {
+  signal: edit.signal,
+});
+
+await edit.update({
+  status: 'ready',
+  forecast: weather.summary,
+});
+```
+
+Ablo does not fetch the weather. It keeps the activity visible, gives the agent
+call an abort signal if the row changes, and clears the activity when
+`edit.update(...)` finishes.
+
+## 7. Multiplayer and Busy Work
+
+There is no separate multiplayer mode. Use the same schema client for human UI,
+server actions, and agents; Ablo fans out confirmed writes and keeps active
+intents visible on the same resource.
+
+Intents tell you when another human or agent is active on the same target. For
+schema clients, wait on the intent stream and then write through the model.
+
+```ts
+const busy = ablo.intents.list({
+  resource: 'weatherReports',
+  id: 'weather_stockholm',
+});
+
+if (busy.length > 0) {
+  await ablo.intents.waitFor(
+    { resource: 'weatherReports', id: 'weather_stockholm' },
+    { timeout: 30_000 },
+  );
+}
+
+await ablo.weatherReports.update('weather_stockholm', { status: 'ready' });
+```
+
+`ifBusy` controls what happens when another human or agent is already working
+on the same target:
+
+- `return` returns immediately with active intents.
+- `wait` waits for the intent stream to clear.
+- `fail` throws `AbloBusyError` with the active intents attached.
+
+## 8. Next Steps
+
+Keep using the schema client for app and agent writes. Reach for the advanced
+schema-less agent wrapper only when a worker intentionally cannot import the
+app schema.
+
+- [Integration Guide](./integration-guide.md) explains the full app, React, Data Source, multiplayer, and agent path.
+- [Guarantees](./guarantees.md) explains what confirmed writes and stale checks mean.
+- [Client Behavior](./client-behavior.md) covers errors, retries, and public imports.
+- [Connect Your Database](./data-sources.md) covers the optional route for teams keeping rows in their own database.
+- [AI SDK Tool](./examples/ai-sdk-tool.md) shows the same write path inside a tool call.

package/docs/react.md

@@ -0,0 +1,115 @@
+# React
+
+The React bindings for `@ablo/sync-engine`. Use them when you want live
+data on the client without writing fetch + WebSocket plumbing yourself.
+
+For the full app structure, including server loads, existing backends, and
+agents, start with [Integration Guide](/docs/integration-guide).
+
+## Installation
+
+The React bindings ship with the main package — no extra install.
+
+```ts
+import { useAblo } from '@ablo/sync-engine/react';
+```
+
+## useAblo — model resource
+
+```tsx
+'use client';
+
+import { useAblo } from '@ablo/sync-engine/react';
+
+export function TaskView({ task: serverTask }: { task: { id: string; title: string } }) {
+  const task = useAblo((ablo) => ablo.tasks.retrieve(serverTask.id)) ?? serverTask;
+  const intents = useAblo((ablo) =>
+    ablo.intents.list({ resource: 'tasks', id: serverTask.id }),
+  ) ?? [];
+  const busy = intents.length > 0;
+
+  return <article>{task.title}</article>;
+}
+```
+
+The hook:
+
+1. Reads through the same `ablo.<model>` methods as the rest of the SDK.
+2. Tracks the model fields read by the selector and re-renders when confirmed
+   deltas arrive.
+3. Lets Server Component data stay outside the hook: use `?? serverTask` when a
+   parent already loaded the row.
+4. Works for coordination state too, such as `ablo.intents.list(...)`.
+
+Use the zero-argument form only when you need the full client for callbacks,
+effects, or writes:
+
+```tsx
+const abloClient = useAblo();
+```
+
+Prefer selector reads like `useAblo((ablo) => ablo.<model>.retrieve(id))`.
+String model names are kept on older hooks for compatibility, but first examples
+should use the same model-resource shape as the rest of the SDK.
+
+For collections, keep the selector on the model resource too:
+
+```tsx
+const tasks = useAblo((ablo) =>
+  ablo.tasks.list({
+    where: { projectId },
+    filter: (task) => task.status !== 'done',
+    scope: 'live',
+  }),
+);
+```
+
+## Server Load
+
+```tsx
+const [task] = await ablo.tasks.load({ where: { id } });
+```
+
+Use `load` in Server Components when the row may not be in the local pool yet.
+
+## Writes
+
+For Server Actions and route handlers, call the SDK directly:
+
+```ts
+import { ablo } from '@/lib/ablo';
+
+const snap = ablo.snapshot({ tasks: id });
+await ablo.tasks.update(id, patch, {
+  readAt: snap.stamp,
+  onStale: 'reject',
+  wait: 'confirmed',
+});
+```
+
+For client event handlers, get the provider-owned client and call the same
+model resource:
+
+```tsx
+const ablo = useAblo();
+
+async function markDone() {
+  if (!ablo) return;
+  const snap = ablo.snapshot({ tasks: id });
+  await ablo.tasks.update(
+    id,
+    { status: 'done' },
+    { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
+  );
+}
+```
+
+The selector form is for render-time reads. The zero-argument form is for
+imperative work after an event or effect.
+
+See [API reference](/docs/api) for the full options surface.
+
+## Next.js
+
+The Next.js [App Router landing](/nextjs) walks through Server Components
++ Server Actions + `useAblo` together.

package/docs/roadmap.md

@@ -0,0 +1,45 @@
+# Roadmap
+
+What is shipped, what is next, and what we will not build.
+
+## Shipped
+
+- **Resources, intents, commits** — the core API.
+- **Capability tokens** — Biscuit-signed, scoped, attenuable, hot-revocable.
+- **Audit log** — hash-chained per principal, with `delegationChainRoot`.
+- **MCP transport** — HTTP server at `/api/mcp`.
+- **TypeScript SDK** — `@ablo/sync-engine`, with React bindings.
+- **Dashboard** — keys, audit, metrics, allowed origins.
+
+## In flight
+
+- **Real-time presence** — see who else is viewing/editing a resource.
+- **Cross-instance fan-out via Redis** — pub/sub deltas at scale.
+- **Hot capability revocation UI** — in the dashboard, today via API only.
+
+## On deck
+
+- **Schema migrations** — declarative resource schema changes.
+- **Field-level subscriptions** — subscribe to one path, not the whole row.
+- **Bulk import/export** — CSV/JSON round-trip with chain verification.
+
+## Maybe, if demand
+
+- **Python SDK** — when a customer is shipping a Python-only product.
+- **Go SDK** — same.
+- **Multi-region replication** — when latency requirements force it.
+
+## We will not build
+
+- **A general-purpose Postgres wrapper** — Ablo Sync is for state with
+  concurrency semantics, not for storing every table.
+- **Server-side compute** — no triggers, no stored procedures. Compute
+  belongs in your application code.
+- **A document database UI** — your data lives in Ablo Sync; the UI is your
+  product, not ours.
+
+## How priorities shift
+
+We move items between sections based on what customers ask for in
+production. Filing a [feature request](/docs/contact) with a concrete use
+case is more effective than a thread on Twitter.

package/examples/README.md

@@ -0,0 +1,54 @@
+# @ablo/sync-engine Examples
+
+The examples teach the same path as the README and docs: declare a schema,
+create or load typed models, and write through `ablo.<model>`.
+
+```ts
+import Ablo from '@ablo/sync-engine';
+import { defineSchema, model, z } from '@ablo/sync-engine/schema';
+
+const schema = defineSchema({
+  weatherReports: model({
+    location: z.string(),
+    status: z.enum(['pending', 'ready']),
+    forecast: z.string().optional(),
+  }),
+});
+
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+```
+
+Then:
+
+- create with `ablo.weatherReports.create`
+- read with `ablo.weatherReports.load`
+- mark long-running AI work with `ablo.weatherReports.edit`
+- write with `ablo.weatherReports.update`
+- wait for confirmation when the write must be durable before continuing
+
+Use schema-less resources and `commits.create` only for advanced runtimes that
+intentionally cannot import the app schema.
+
+## Running
+
+```bash
+cd packages/sync-engine/examples
+ABLO_API_KEY=sk_test_... npx tsx quickstart.ts
+```
+
+## Data Source (customer-owned database)
+
+`data-source/` is a self-contained, runnable end-to-end demo of the
+HTTP contract Ablo Cloud uses to talk to a customer's database. It
+needs no API key, no cloud connection, and no open ports: the
+orchestrator drives the customer handler in-process so signer and
+verifier exchange real signed bytes without leaving the process.
+
+```bash
+cd packages/sync-engine/examples
+npx tsx data-source/run.ts
+```
+
+See `data-source/README.md` for what each file teaches and the
+production wiring snippets (Next.js, Hono, Cloudflare Workers,
+plain Node).

package/examples/data-source/README.md

@@ -0,0 +1,102 @@
+# Data Source Example
+
+End-to-end demo of the Data Source contract — the path customers take
+when they want Ablo to coordinate writes against rows stored in
+**their** database.
+
+## What's in here
+
+| File                  | Side               | Purpose                                                       |
+| --------------------- | ------------------ | ------------------------------------------------------------- |
+| `schema.ts`           | Shared             | The Zod schema both Ablo and the customer compile against     |
+| `customer-server.ts`  | Customer           | The `dataSource(...)` handler — copy as a skeleton            |
+| `ablo-driver.ts`      | Ablo Cloud         | Signs requests the way Ablo Cloud does in production          |
+| `run.ts`              | Orchestrator       | Drives load -> commit -> list -> events round-trip            |
+
+## Run
+
+```bash
+cd packages/sync-engine/examples
+npx tsx data-source/run.ts
+```
+
+No network port, no env vars, no cloud credentials. The orchestrator
+calls the handler in-process. Signer and verifier still exchange
+signed bytes — flip the secret and you'll see a 401.
+
+## What it proves
+
+1. **Signer/verifier interop.** Ablo Cloud's
+   `signAbloSourceRequest` and the customer's `dataSource(...)`
+   speak the same wire format (Standard Webhooks v1).
+2. **All four request types** — `load`, `list`, `commit`, `events`
+   — share one handler.
+3. **The customer DB stays canonical.** Ablo never sees rows
+   directly; it only sees the response payload from the customer's
+   handler.
+4. **The outbox feed.** Writes that bypass Ablo (cron, dashboards,
+   batch imports) show up on the next `events` poll so Ablo can fan
+   them out to connected clients.
+
+## Production wiring
+
+The customer's handler is a Fetch-API function:
+`(req: Request) => Promise<Response>`. Drop it anywhere that speaks
+that contract.
+
+### Next.js App Router
+
+```ts
+// app/api/ablo/source/route.ts
+export { handleAbloSource as POST } from '@/lib/ablo-source';
+```
+
+### Hono / Cloudflare Workers
+
+```ts
+import { Hono } from 'hono';
+import { handleAbloSource } from './ablo-source';
+
+const app = new Hono();
+app.post('/api/ablo/source', (c) => handleAbloSource(c.req.raw));
+```
+
+### Node `http` server
+
+```ts
+import { createServer } from 'node:http';
+import { handleAbloSource } from './ablo-source';
+
+createServer(async (req, res) => {
+  const body = await new Promise<string>((resolve) => {
+    let chunks = '';
+    req.on('data', (c) => (chunks += c));
+    req.on('end', () => resolve(chunks));
+  });
+  const request = new Request(`http://localhost${req.url}`, {
+    method: req.method,
+    headers: req.headers as Record<string, string>,
+    body,
+  });
+  const response = await handleAbloSource(request);
+  res.writeHead(response.status, Object.fromEntries(response.headers));
+  res.end(await response.text());
+}).listen(3000);
+```
+
+## Migration checklist for an existing backend
+
+Replace the `Map`-based store in `customer-server.ts` with your real
+data layer. The handler shape stays the same:
+
+- `tasks.load({ id })` -> `db.task.findUnique({ where: { id } })`
+- `tasks.list({ query })` -> `db.task.findMany({ take, cursor })`
+- `tasks.commit({ operations, clientTxId })` -> `db.$transaction` that
+  applies each `op` and tags the row with `clientTxId` for idempotent
+  retries
+- `events({ cursor, limit })` -> read from your outbox table, return
+  rows with their `clientTxId` (Ablo dedupes its own commits) and the
+  resume cursor
+
+See `docs/examples/existing-python-backend.md` for the same pattern
+expressed against a Python backend.