@abloatai/ablo 0.3.0

package/docs/integration-guide.md

@@ -0,0 +1,493 @@
+# Integration Guide
+
+Use this guide when you are adding Ablo to a real product, not a demo.
+
+## Why Ablo, before the API
+
+Ablo is a sync engine designed from the ground up for **humans and AI
+agents editing the same state at the same time**. That premise drives
+every design choice in this guide; if you only need server-to-server
+data syncing without agents in the loop, the trade-offs land elsewhere
+(Replicache, ElectricSQL, PowerSync are good answers for human-only
+real-time apps; Zero is a good answer for query-shaped sync).
+
+The shape of the SDK reflects three commitments:
+
+- **One model API for every actor.** `ablo.<model>.update(...)` is what
+  React components, server actions, background workers, and AI agents
+  all call. No separate "agent SDK," no parallel mutation path. The
+  attribution comes from the credential, not the call site.
+- **Server owns the scope convention; client picks a subset by id.** The
+  `org:` / `user:` / `team:` (or your own `region:` / `customer:`)
+  prefixes live in the schema's `identityRoles` once, never typed by
+  consumer code. Same boundary Liveblocks (`prepareSession`), PowerSync
+  (named streams), and Zero (synced queries) settled on after the same
+  realization: clients that compose scope strings drift; servers that
+  derive scope from authed identity don't.
+- **Capabilities, not API keys, are how agents authenticate.** Static
+  API keys protect server-to-server humans. Agents get per-run,
+  per-scope, leased credentials with per-request signature verification
+  and instant revocation. The 2025-2026 AI-agent auth consensus
+  (OAuth 2.1 / MCP, AWS STS, Vault leases, Auth0 Token Vault) converged
+  on this shape. Capabilities are Ablo's instance.
+
+If you have already built a sync layer or an agent runtime, you know
+what each of those costs. This guide assumes you want them solved once,
+together, behind one client.
+
+## The integration in one diagram
+
+The normal integration is one client:
+
+```ts
+import Ablo from '@ablo/sync-engine';
+import { defineSchema, model, z } from '@ablo/sync-engine/schema';
+```
+
+Declare the models Ablo coordinates, then read and write through
+`ablo.<model>`. React, server actions, backend workers, and agents should all use
+that same model path.
+
+```txt
+schema -> ablo.<model>.load(...) -> ablo.<model>.update(...)
+```
+
+Capabilities, tasks, commits, and receipts exist under the hood. Most apps do
+not create them by hand.
+
+## Pick The Backing Mode
+
+Every schema model has a backing store. The SDK call shape stays the same.
+
+| Mode | Rows live in | Use when |
+|---|---|---|
+| Ablo-managed | Ablo | New collaborative or agent-written state can live in Ablo. |
+| Data Source | Your app database | You already have tables, service logic, and API endpoints that remain canonical. |
+| Schema-less resource API | Custom runtime | A server worker, MCP route, or migration script intentionally cannot import the app schema. |
+
+Do not pass a database URL to `Ablo(...)`. Application and agent code use
+`ABLO_API_KEY`. If your database stays canonical, add a Data Source URL in Ablo
+and keep the database credentials inside your app.
+
+## Test With Sandboxes
+
+Use the public `/sandbox` page to understand the state flow. It is a visual,
+deterministic demo; it does not call your API key or mutate hosted Ablo data.
+It is also built for coding agents: copy the sandbox prompt into Claude Code or
+Codex and ask it to wire one real resource through the schema model API.
+
+Use the authenticated org dashboard sandbox for real integration work. The
+default sandbox is the equivalent of Stripe test mode:
+
+- it is scoped to the organization,
+- it has an isolated sync group prefix,
+- it mints `sk_test_*` keys,
+- it can be reset without touching live state,
+- additional sandboxes can start blank or from copied live configuration.
+
+Live keys and sandbox keys are separate. Use `sk_test_*` while wiring your app,
+agents, and Data Source endpoint; move to `sk_live_*` only when the same schema
+and write path are ready for production.
+
+When handing this to a coding agent, give it a concrete target:
+
+```txt
+Add Ablo Sync to this app for one resource that humans and agents both edit.
+Use the org sandbox sk_test_* key. Declare schema, add the Ablo client, replace
+one write with ablo.<model>.update(..., { readAt, onStale: 'reject',
+wait: 'confirmed' }), and add a smoke test for two concurrent writers.
+```
+
+## 1. Declare A Schema
+
+Start with fields and relations. Keep load strategies, indexing hints, and
+read-only/mutable shortcuts out of the first version unless you already need
+offline-heavy local cache behavior.
+
+```ts
+// src/ablo.schema.ts
+import { defineSchema, model, z } from '@ablo/sync-engine/schema';
+
+export const schema = defineSchema(
+  {
+    tasks: model({
+      id: z.string(),
+      projectId: z.string(),
+      title: z.string(),
+      status: z.enum(['todo', 'doing', 'done']),
+      assigneeId: z.string().nullable(),
+      updatedAt: z.string(),
+    }),
+  },
+  {
+    // Identity-anchored sync-group roles. The server walks these to
+    // build each participant's allowed subscription set from the
+    // resolved identity context. Templates and extractors are fully
+    // consumer-controlled — no hardcoded `org:` / `user:` convention
+    // anywhere in the engine. Omit `identityRoles` entirely if your
+    // schema doesn't need identity-derived scoping.
+    identityRoles: [
+      {
+        kind: 'tenant',
+        template: 'org:{id}',
+        extract: (i) => (i.organizationId ? [String(i.organizationId)] : []),
+      },
+      {
+        kind: 'participant',
+        template: 'user:{id}',
+        extract: (i) => (i.userId ? [String(i.userId)] : []),
+      },
+    ],
+  },
+);
+```
+
+### Declaring scope on a model
+
+Per-row tenancy and per-entity sync-group anchors live on the
+`defineModel` (or `model(...)`) options. The two halves compose: the
+identity roles above produce a participant's *allowed* set; the
+per-model options below define how rows are filtered server-side and
+which sync-group label each row fans out on.
+
+```ts
+model(
+  { /* fields */ },
+  /* relations */ {},
+  {
+    // Rows carry organization_id and bootstrap filters on it.
+    orgScoped: true,
+
+    // Per-entity sync-group anchor. Lets a capability narrow into
+    // one row's scope via `syncGroupFormat.replace('{id}', rowId)`.
+    syncGroupFormat: 'matter:{id}',
+  },
+)
+```
+
+For rows that don't carry `organization_id` themselves but inherit
+tenancy via a foreign key, use `scopedVia` instead of `orgScoped:
+false` — the latter exposes the entire table cross-tenant. See
+`packages/sync-engine/src/schema/model.ts` for the full option set.
+
+## 2. Create The Client
+
+Trusted runtimes can use `ABLO_API_KEY`.
+
+```ts
+// src/ablo.ts
+import Ablo from '@ablo/sync-engine';
+import { schema } from './ablo.schema';
+
+export const ablo = Ablo({
+  schema,
+  apiKey: process.env.ABLO_API_KEY,
+});
+```
+
+Browser apps should use the React provider or a scoped session/capability, not a
+server API key in the bundle.
+
+```tsx
+// app/providers.tsx
+'use client';
+
+import { AbloProvider } from '@ablo/sync-engine/react';
+import { schema } from '@/ablo.schema';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <AbloProvider schema={schema}>{children}</AbloProvider>;
+}
+```
+
+### Why two credential shapes
+
+`ABLO_API_KEY` is your long-lived account credential. Treat it like a
+Stripe secret key: it stays on trusted servers, never reaches a browser
+bundle, and signs server-to-server requests. It is the right credential
+for trusted runtimes (Next.js server actions, background workers,
+migration scripts) where the code reading it is yours.
+
+A browser or an agent runtime is not that environment. The React
+provider and the `agent.run(...)` wrapper both exchange your api key for
+a **capability** — a short-lived, narrowly-scoped bearer token. The
+browser holds the cap; the api key never leaves the server. The
+exchange is the bridge between two credential shapes:
+
+```
+                     trusted runtime              browser / agent
+ABLO_API_KEY ─exchange─►  Capability token ────► narrow scope, leased
+(long-lived,             (short-lived,
+ broad scope,             per-actor scope,
+ server only)             revocable)
+```
+
+This is the same shape as Stripe's
+ephemeral keys (Issuing Elements expires in 15 minutes) and AWS STS
+AssumeRole (returns time-bounded creds with the minimal needed scope).
+You never *type* a capability into your app; the SDK mints one when it
+needs one and refreshes before expiry. See
+[Capabilities](./capabilities.md) for the design rationale and the
+manual create/revoke surface that custom runtimes use.
+
+## 3. Read State
+
+Use `load` when the row may not already be local.
+
+```ts
+await ablo.ready();
+
+const [task] = await ablo.tasks.load({ where: { id: 'task_123' } });
+if (!task) throw new Error('task not found');
+```
+
+Use `retrieve`, `list`, and `count` for synchronous local reads after data has
+loaded.
+
+```ts
+const task = ablo.tasks.retrieve('task_123');
+const activeTasks = ablo.tasks.list({
+  where: { projectId: 'proj_123' },
+  filter: (task) => task.status !== 'done',
+  orderBy: { updatedAt: 'desc' },
+  limit: 50,
+});
+```
+
+In React, selector `useAblo` is the public read API:
+
+```tsx
+'use client';
+
+import { useAblo } from '@ablo/sync-engine/react';
+
+export function TaskRow({ task: serverTask }: { task: Task }) {
+  const task = useAblo((ablo) => ablo.tasks.retrieve(serverTask.id)) ?? serverTask;
+  const intents = useAblo((ablo) =>
+    ablo.intents.list({ resource: 'tasks', id: serverTask.id }),
+  ) ?? [];
+
+  return (
+    <button disabled={intents.length > 0 || task.status === 'done'}>
+      {task.title}
+    </button>
+  );
+}
+```
+
+Use zero-argument `useAblo()` only in callbacks and effects:
+
+```tsx
+const ablo = useAblo();
+```
+
+## 4. Write State
+
+For simple writes:
+
+```ts
+await ablo.tasks.update(
+  'task_123',
+  { status: 'done' },
+  { wait: 'confirmed' },
+);
+```
+
+For writes based on state the user or agent already read, snapshot first and
+reject stale updates:
+
+```ts
+const snap = ablo.snapshot({ tasks: 'task_123' });
+
+await ablo.tasks.update(
+  'task_123',
+  { status: 'done' },
+  {
+    readAt: snap.stamp,
+    onStale: 'reject',
+    wait: 'confirmed',
+  },
+);
+```
+
+`wait: 'confirmed'` resolves after the server accepts the write. Rejections roll
+back optimistic local state and throw a typed `AbloError`.
+
+## 5. Multiplayer Is Automatic
+
+There is no separate multiplayer setup.
+
+If humans, server actions, and agents use the same schema model resource, they
+share the same stream:
+
+```txt
+human UI -> ablo.tasks.update(...)
+agent    -> ablo.tasks.update(...)
+server   -> ablo.tasks.update(...)
+```
+
+Ablo coordinates those writes, fans out confirmed deltas, exposes active intents,
+and lets callers reject stale writes with `readAt`.
+
+Direct writes to your own database bypass that stream until your app reports the
+change through Data Source events.
+
+## 6. Existing API Backend
+
+This is the path for a product where buttons already call Python, Rails, Go, or
+Node endpoints.
+
+Keep your backend and database canonical. Add Ablo as the shared write path for
+the records that need multiplayer now and agent-safe writes later.
+
+```txt
+Button
+  -> ablo.tasks.update(...)
+  -> Ablo
+  -> signed Data Source request
+  -> existing backend service
+  -> app database
+  -> Ablo realtime fanout
+```
+
+The migration can be gradual:
+
+1. Declare schema for one resource, such as `tasks`.
+2. Keep existing server loads for first paint.
+3. Add `useAblo((ablo) => ablo.tasks.retrieve(id)) ?? serverTask` for live rows.
+4. Add one Data Source endpoint that calls the existing service layer.
+5. Move one mutation button from `fetch('/api/tasks/...')` to `ablo.tasks.update(...)`.
+6. Add an outbox/events path for writes that still happen outside Ablo.
+7. Let agents use the same `ablo.tasks.load(...)` and `ablo.tasks.update(...)`.
+
+For the full Python shape, see
+[Existing Python Backend](./examples/existing-python-backend.md).
+
+## 7. Data Source Endpoint
+
+Use a Data Source when your app database remains the source of truth.
+
+```ts
+// app/api/ablo/source/route.ts
+import { dataSource } from '@ablo/sync-engine';
+import { schema } from '@/ablo.schema';
+import { db } from '@/db';
+
+export const POST = dataSource({
+  schema,
+  signingSecret: process.env.ABLO_DATA_SOURCE_SIGNING_SECRET,
+
+  authorize() {
+    return { db };
+  },
+
+  async commit({ operations, clientTxId, context }) {
+    const rows = await context.auth.db.transaction(async (tx) => {
+      await tx.idempotency.upsert({ key: clientTxId });
+      return applyOperations(tx, operations);
+    });
+
+    return { rows };
+  },
+
+  tasks: {
+    async load({ id, context }) {
+      return context.auth.db.task.findUnique({ where: { id } });
+    },
+
+    async list({ query, context }) {
+      return context.auth.db.task.findMany({
+        take: query.limit ?? 100,
+      });
+    },
+  },
+});
+```
+
+Ablo gives you a Data Source URL, a signing secret, push/events URL, and status.
+Your app stores:
+
+```bash
+ABLO_DATA_SOURCE_SIGNING_SECRET=whsec_...
+```
+
+The signing secret verifies Ablo's request. It is not a database credential.
+
+## 8. Agents
+
+Agents should use the same model methods as the app when they can import the
+schema.
+
+```ts
+const [task] = await ablo.tasks.load({ where: { id: taskId } });
+if (!task) return;
+
+const intents = ablo.intents.list({ resource: 'tasks', id: taskId });
+if (intents.length > 0) return { skipped: true, reason: 'busy' };
+
+const snap = ablo.snapshot({ tasks: taskId });
+
+await ablo.tasks.update(
+  taskId,
+  { status: 'done', summary: await summarize(task) },
+  { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
+);
+```
+
+Use AI SDK for the model loop. Put Ablo inside the tool that persists the final
+change.
+
+```ts
+const completeTask = tool({
+  description: 'Mark a task done with a summary',
+  inputSchema: z.object({
+    taskId: z.string(),
+    summary: z.string(),
+  }),
+  execute: async ({ taskId, summary }) => {
+    const snap = ablo.snapshot({ tasks: taskId });
+    return ablo.tasks.update(
+      taskId,
+      { status: 'done', summary },
+      { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
+    );
+  },
+});
+```
+
+Use schema-less `agent.run(...)`, `resource(...)`, and `commits.create(...)` only
+for custom server runtimes that intentionally cannot import the schema.
+
+## Optional Surface
+
+| Optional piece | Why it exists |
+|---|---|
+| `/react` | Live React selectors, provider lifecycle, presence, sync status. |
+| `/testing` | Test harnesses and deterministic mocks. |
+| `Data Source` | Keep your app database canonical. |
+| `persistence: 'indexeddb'` | Durable browser cache and offline queueing for apps that need it. |
+| `intents` | Show active work and coordinate before a write. |
+| `snapshot` + `readAt` | Reject writes based on stale state. |
+| `mutable`, `readOnly`, `field`, `indexed` | Advanced schema and local-cache tuning. |
+| `resource(...)` and `commits.create(...)` | Low-level protocol access for custom runtimes. |
+
+The first integration should not need most of these. Start with schema and
+model methods, then add the optional pieces where the product actually needs
+them.
+
+## Method Cheatsheet
+
+| Method | Use it for |
+|---|---|
+| `load({ where })` | Async hydration from backing store/server. |
+| `retrieve(id)` | Synchronous local read of one loaded row. |
+| `list(options?)` | Synchronous local collection read. |
+| `count(options?)` | Synchronous local count. |
+| `create(data, options?)` | Create through the model resource. |
+| `update(id, data, options?)` | Update through the model resource. |
+| `delete(id, options?)` | Delete through the model resource. |
+| `intents.list(target)` | See active work on a resource. |
+| `intents.waitFor(target)` | Wait on the live intent stream. |
+
+Do not use `ablo.commit` as the first write API. Most callers should never need
+the low-level commit plane directly.

package/docs/interaction-model.md

@@ -0,0 +1,140 @@
+# Interaction Model
+
+Ablo separates the data path from the authority path.
+
+The data path is what your application does on every write:
+
+```
+Schema -> Model load -> Intent -> Model update -> Confirmation
+```
+
+The authority path is what makes that write defensible:
+
+```
+Capability -> Task -> Usage
+```
+
+## Primitives
+
+| Primitive | Plane | Purpose |
+|---|---|---|
+| `Schema` | State | Declares typed models the app and agents can read and write. |
+| `Model` | State | The generated `ablo.<model>` resource. Use `load`, `retrieve`, `create`, `update`, and `delete`. |
+| `Intent` | State | Pre-write coordination. It says what this actor is preparing to change. |
+| `Commit` | Protocol | The durable write underneath model updates. Most users do not call it directly. |
+| `Receipt` | Protocol | The lower-level durable result for custom runtimes. Schema writes use `wait: 'confirmed'`. |
+| `Capability` | Control | Signed credentials. It says who can do what, where, for how long, and on whose behalf. |
+| `Task` | Control | One agent run. It groups prompts, commits, child tasks, and cost. |
+| `Usage` | Control | Metering and audit rows derived from accepted work. |
+
+Capabilities, tasks, and usage do not mutate product data. They define and
+record the authority around mutation.
+
+### Why each primitive is separate
+
+The plane separation isn't ceremony — collapsing any two of these would
+lose a property that's hard to recover later. A reader coming from
+Replicache or Yjs would expect just `Commit`; here's what the others buy
+you over that minimum:
+
+- **`Intent` is not a lock.** A pessimistic lock blocks a writer; an
+  intent *announces* one. Other writers can yield, wait, or proceed —
+  the choice is theirs, not the system's. This is the only primitive
+  that lets two agents discover each other's planned work *before* the
+  conflict and self-arbitrate. Without intents, agents only learn about
+  contention at commit time, when one of them has already wasted a
+  token budget.
+- **`Receipt` is not a `200 OK`.** It's the durable artifact a commit
+  produced — accepted commit id, server-assigned timestamps, stale-check
+  outcome — addressable after the fact and replayable into a different
+  client. A status code can't be re-read by a sub-agent that wasn't on
+  the original call.
+- **`Capability` is not the actor.** The actor (`Task`) is what *ran*;
+  the capability is what it was *allowed* to do. Same human can spawn
+  many tasks under one cap (cheap re-run); same task can attenuate to
+  many sub-caps (sub-agent delegation). Folding them collapses both
+  directions of that fan.
+- **`Task` is not the credential.** It's the audit envelope: prompt,
+  commits, child tasks, tokens, duration. Long after the cap has
+  expired, the task row is what answers "what did this run do." Folding
+  task into capability loses the post-expiry audit.
+- **`Usage` is not derived from logs.** It's denormalized at commit
+  accept time so quota enforcement and billing reads stay O(1). Log
+  scans would work for audit but not for hot-path gating.
+
+The shape is borrowed from systems that learned the cost of collapse:
+intents from operational-transform CRDTs and Linear's
+optimistic-multiplayer model, capabilities + tasks from AWS IAM
+(`Role` ≠ `RoleSession`) and Vault (`policy` ≠ `lease`).
+
+## Run Loop
+
+A normal schema-backed run is:
+
+```
+const [task] = await ablo.tasks.load({ where: { id } });
+const busy = ablo.intents.list({ resource: 'tasks', id });
+const snap = ablo.snapshot({ tasks: id });
+await ablo.tasks.update(id, patch, {
+  readAt: snap.stamp,
+  onStale: 'reject',
+  wait: 'confirmed',
+});
+```
+
+## Participants
+
+Every action is performed by one of three kinds:
+
+- `user` — a human, authenticated via session.
+- `agent` — an AI process acting on behalf of a human, authenticated via a capability minted from that human's session.
+- `system` — a customer-backend process acting on behalf of an organization, authenticated via an API key.
+
+The participant kind is enforced at the boundary. An agent capability cannot impersonate a user. A user session cannot open a task.
+
+## Delegation chain
+
+Every capability resolves to a `delegationChainRootUserId` — the human at the head of the chain. The chain is denormalized onto every commit's `on_behalf_of_*` columns so audit queries answer "what did this human authorize" with one lookup, not a recursive join.
+
+## Enforcement
+
+Capabilities are enforced per operation, not per request. When a commit arrives, Ablo decodes the bearer token, checks each operation against `operations` and `syncGroups`, and rejects with `capability_scope_denied` if the scope is missing. Revocation takes effect within seconds of `DELETE /v1/capabilities/:id`.
+
+Three independent checks gate every commit. The redundancy is intentional — each check covers a failure mode the others don't:
+
+- **Lease (TTL on the token).** Decoded from the bearer; no DB lookup. Caps the lifetime of a leaked token. Without this, a stolen token works until manually revoked.
+- **Signature + scope verification.** Stateless. Detects forged or tampered tokens and rejects operations outside the cap's `operations` / `syncGroups`. Without this, a malformed token with the right shape could pass.
+- **Revocation.** `DELETE /v1/capabilities/:id` flips status server-side; live WS sessions close, future commits reject. Closes the gap between lease refresh cycles when you need *immediate* cutoff. Without this, a compromised cap with a long lease leaks until expiry.
+
+Removing any one of the three leaves a class of attack uncovered. The pattern matches AWS STS, Vault leases, and the OAuth 2.1 / MCP agent-auth recommendation; see [Capabilities](./capabilities.md#the-three-layer-security-model) for the full design discussion.
+
+## Coordination
+
+Intents broadcast across the org. When `agent:task-writer` declares an intent to
+update a task, schema clients can see it through `ablo.intents.list(...)` or the
+live intent stream. Callers decide whether to yield, wait, or fail fast.
+
+## Conflict resolution
+
+Schema updates can carry `readAt` and `onStale`. If the state advanced past
+`readAt`, Ablo applies the `onStale` policy:
+
+- `reject` — fail the commit (first writer wins).
+- `merge` — apply the write if it does not overlap with concurrent changes.
+- `force` — apply the write unconditionally.
+
+The choice is per-commit. No CRDT default; the policy is explicit.
+
+## Audit
+
+Three tables observe the run:
+
+- `agent_tasks` — one row per open/close cycle. Cost stats, prompt hash, capability id.
+- `agent_actions_log` — one row per write, attributed to the task and the capability.
+- `usage_event` — one row per accounted API call, attributed to the api key, the participant, and the task.
+
+Joins between them answer "what did this agent do, on whose authority, at what cost." That answer is what makes giving an agent write access defensible.
+
+## The contract in one sentence
+
+Declare schema, load state, coordinate intent, update the model, and wait for confirmation.

package/docs/mcp/claude-code.md

@@ -0,0 +1,43 @@
+# Claude Code
+
+## Install
+
+```bash
+claude mcp add --transport http ablo-sync https://<your-app>/api/mcp
+```
+
+That's it. The next `/help` in Claude Code will list the Ablo Sync tools.
+
+## With auth
+
+If your deployment requires a capability token (production setups should):
+
+```bash
+claude mcp add --transport http ablo-sync https://<your-app>/api/mcp \
+  --header "Authorization=Bearer $ABLO_MCP_TOKEN"
+```
+
+Create a session-scoped capability from the dashboard or via the API — see
+[MCP overview](/docs/mcp#auth).
+
+## Verify
+
+In Claude Code, run:
+
+```
+/mcp list
+```
+
+You should see `ablo-sync` with the resource tools enumerated.
+
+## Removing
+
+```bash
+claude mcp remove ablo-sync
+```
+
+## More
+
+- [MCP overview](/docs/mcp) — how the transport works.
+- [Cursor setup](/docs/mcp/cursor) — same JSON, different UI.
+- [Windsurf setup](/docs/mcp/windsurf) — same JSON, different UI.