@abloatai/ablo 0.5.1 → 0.7.0

package/docs/integration-guide.md

@@ -52,18 +52,17 @@ that same model path.
 schema -> ablo.<model>.load(...) -> ablo.<model>.update(...)
 ```
 
-Capabilities, tasks, commits, and receipts exist under the hood. Most apps do
-not create them by hand.
+Commits and receipts exist under the hood. Most apps do not create protocol
+objects 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. |
+| 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. |
 
 Do not pass a database URL to `Ablo(...)`. Application and agent code use
 `ABLO_API_KEY`. If your database stays canonical, expose a signed Data Source
@@ -74,7 +73,7 @@ endpoint from your app and keep the database credentials inside your app.
 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.
+Codex and ask it to wire one real model 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:
@@ -92,7 +91,7 @@ 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.
+Add Ablo to this app for one model 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.
@@ -102,67 +101,65 @@ wait: 'confirmed' }), and add a smoke test for two concurrent writers.
 
 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.
+them.
 
 ```ts
-// src/ablo.schema.ts
+// src/ablo/schema.ts
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 export const schema = defineSchema(
   {
-    tasks: model({
+    weatherReports: model({
       id: z.string(),
       projectId: z.string(),
-      title: z.string(),
-      status: z.enum(['todo', 'doing', 'done']),
+      location: z.string(),
+      status: z.enum(['pending', 'ready']),
       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.
+    // Identity-anchored sync-group roles. The server walks these to build each
+    // participant's allowed subscription set from the resolved identity context.
+    // `kind` is the group prefix; `source` is the identity field to read — both
+    // consumer-controlled, no hardcoded `org:` / `user:` convention anywhere in
+    // the engine. Pure data (no closures), so the schema stays JSON-serializable.
+    // Omit `identityRoles` entirely if you don'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)] : []),
-      },
+      identityRole({ kind: 'org', source: 'organizationId' }),
+      identityRole({ kind: 'user', source: '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.
+> **Canonical reference: [Identity & Sync Groups](./identity.md).** This is the
+> short version — `scope` (root), `parent` (containment), `grants` (membership),
+> and the model-form `scope` prop are all covered in depth there. Read it once;
+> this guide only shows the minimal shape inline.
+
+Per-row tenancy and per-entity sync-group anchors live on the `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 each row fans out on.
 
 ```ts
 model(
-  { /* fields */ },
+  {
+    /* 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}',
-  },
-)
+    // Scope root: rows form the group `matter:<id>`. Children point at it with
+    // `relation.belongsTo('matters', 'matterId', { parent: true })` to inherit.
+    scope: 'matter',
+  }
+);
 ```
 
 For rows that don't carry `organization_id` themselves but inherit
@@ -177,7 +174,7 @@ Trusted runtimes can use `ABLO_API_KEY`.
 ```ts
 // src/ablo.ts
 import Ablo from '@abloatai/ablo';
-import { schema } from './ablo.schema';
+import { schema } from './ablo/schema';
 
 export const ablo = Ablo({
   schema,
@@ -185,7 +182,7 @@ export const ablo = Ablo({
 });
 ```
 
-Browser apps should use the React provider or a scoped session/capability, not a
+Browser apps should use the React provider or a scoped session token, not a
 server API key in the bundle.
 
 ```tsx
@@ -193,7 +190,7 @@ server API key in the bundle.
 'use client';
 
 import { AbloProvider } from '@abloatai/ablo/react';
-import { schema } from '@/ablo.schema';
+import { schema } from '@/ablo/schema';
 
 export function Providers({ children }: { children: React.ReactNode }) {
   return <AbloProvider schema={schema}>{children}</AbloProvider>;
@@ -208,15 +205,14 @@ 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:
+A browser is not that environment. The React provider exchanges your API key for
+a short-lived, narrowly scoped bearer token. The browser holds that scoped token;
+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
+ABLO_API_KEY ─exchange─►  scoped token ────────► narrow scope, leased
 (long-lived,             (short-lived,
  broad scope,             per-actor scope,
  server only)             revocable)
@@ -225,10 +221,8 @@ ABLO_API_KEY ─exchange─►  Capability token ────► narrow scope, l
 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.
+You never type that token into your app; the SDK mints one when it needs one and
+refreshes before expiry.
 
 ## 3. Read State
 
@@ -237,18 +231,18 @@ 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');
+const [report] = await ablo.weatherReports.load({ where: { id: 'report_stockholm' } });
+if (!report) throw new Error('report not found');
 ```
 
-Use `retrieve`, `list`, and `count` for synchronous local reads after data has
+Use `retrieve`, `list`, and `count` for synchronous reads after data has
 loaded.
 
 ```ts
-const task = ablo.tasks.retrieve('task_123');
-const activeTasks = ablo.tasks.list({
+const report = ablo.weatherReports.retrieve('report_stockholm');
+const activeReports = ablo.weatherReports.list({
   where: { projectId: 'proj_123' },
-  filter: (task) => task.status !== 'done',
+  filter: (report) => report.status !== 'ready',
   orderBy: { updatedAt: 'desc' },
   limit: 50,
 });
@@ -261,17 +255,15 @@ In React, selector `useAblo` is the public read API:
 
 import { useAblo } from '@abloatai/ablo/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>
-  );
+export function ReportRow({
+  report: serverReport,
+}: {
+  report: { id: string; location: string; status: string };
+}) {
+  const report = useAblo((ablo) => ablo.weatherReports.retrieve(serverReport.id)) ?? serverReport;
+  const active = useAblo((ablo) => ablo.weatherReports.claimState(serverReport.id));
+
+  return <button disabled={Boolean(active) || report.status === 'ready'}>{report.location}</button>;
 }
 ```
 
@@ -286,27 +278,23 @@ const ablo = useAblo();
 For simple writes:
 
 ```ts
-await ablo.tasks.update(
-  'task_123',
-  { status: 'done' },
-  { wait: 'confirmed' },
-);
+await ablo.weatherReports.update('report_stockholm', { status: 'ready' }, { 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' });
+const snap = ablo.snapshot({ weatherReports: 'report_stockholm' });
 
-await ablo.tasks.update(
-  'task_123',
-  { status: 'done' },
+await ablo.weatherReports.update(
+  'report_stockholm',
+  { status: 'ready' },
   {
     readAt: snap.stamp,
     onStale: 'reject',
     wait: 'confirmed',
-  },
+  }
 );
 ```
 
@@ -317,16 +305,16 @@ back optimistic local state and throw a typed `AbloError`.
 
 There is no separate multiplayer setup.
 
-If humans, server actions, and agents use the same schema model resource, they
+If humans, server actions, and agents use the same schema client, they
 share the same stream:
 
 ```txt
-human UI -> ablo.tasks.update(...)
-agent    -> ablo.tasks.update(...)
-server   -> ablo.tasks.update(...)
+human UI -> ablo.weatherReports.update(...)
+agent    -> ablo.weatherReports.update(...)
+server   -> ablo.weatherReports.update(...)
 ```
 
-Ablo coordinates those writes, fans out confirmed deltas, exposes active intents,
+Ablo coordinates those writes, fans out confirmed deltas, exposes active claims,
 and lets callers reject stale writes with `readAt`.
 
 Direct writes to your own database bypass that stream until your app reports the
@@ -342,7 +330,7 @@ the records that need multiplayer now and agent-safe writes later.
 
 ```txt
 Button
-  -> ablo.tasks.update(...)
+  -> ablo.weatherReports.update(...)
   -> Ablo
   -> signed Data Source request
   -> existing backend service
@@ -352,13 +340,13 @@ Button
 
 The migration can be gradual:
 
-1. Declare schema for one resource, such as `tasks`.
+1. Declare schema for one model, such as `reports`.
 2. Keep existing server loads for first paint.
-3. Add `useAblo((ablo) => ablo.tasks.retrieve(id)) ?? serverTask` for live rows.
+3. Add `useAblo((ablo) => ablo.weatherReports.retrieve(id)) ?? serverReport` 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(...)`.
+5. Move one mutation button from `fetch('/api/reports/...')` to `ablo.weatherReports.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(...)`.
+7. Let agents use the same `ablo.weatherReports.load(...)` and `ablo.weatherReports.update(...)`.
 
 For the full Python shape, see
 [Existing Python Backend](./examples/existing-python-backend.md).
@@ -370,7 +358,7 @@ Use a Data Source when your app database remains the source of truth.
 ```ts
 // app/api/ablo/source/route.ts
 import { dataSource } from '@abloatai/ablo';
-import { schema } from '@/ablo.schema';
+import { schema } from '@/ablo/schema';
 import { db } from '@/db';
 
 export const POST = dataSource({
@@ -390,13 +378,13 @@ export const POST = dataSource({
     return { rows };
   },
 
-  tasks: {
+  reports: {
     async load({ id, context }) {
-      return context.auth.db.task.findUnique({ where: { id } });
+      return context.auth.db.report.findUnique({ where: { id } });
     },
 
     async list({ query, context }) {
-      return context.auth.db.task.findMany({
+      return context.auth.db.report.findMany({
         take: query.limit ?? 100,
       });
     },
@@ -420,18 +408,19 @@ 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' },
+const [report] = await ablo.weatherReports.load({ where: { id: reportId } });
+if (!report) return;
+
+await ablo.weatherReports.claim(
+  reportId,
+  async (claimed) => {
+    await ablo.weatherReports.update(
+      claimed.id,
+      { status: 'ready', forecast: await getForecast(claimed) },
+      { wait: 'confirmed' }
+    );
+  },
+  { wait: false, action: 'forecasting' }
 );
 ```
 
@@ -439,38 +428,36 @@ 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',
+const completeReport = tool({
+  description: 'Mark a weather report ready with a forecast',
   inputSchema: z.object({
-    taskId: z.string(),
-    summary: z.string(),
+    reportId: z.string(),
+    forecast: 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' },
+  execute: async ({ reportId, forecast }) => {
+    const snap = ablo.snapshot({ weatherReports: reportId });
+    return ablo.weatherReports.update(
+      reportId,
+      { status: 'ready', forecast },
+      { 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.
+Keep agent writes on the same schema client surface as the app.
 
 ## 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. |
+| 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 that survives reloads, for apps that need it. |
+| `claim` / `claimState` / `queue`          | Show active work and coordinate before a write.                   |
+| `snapshot` + `readAt`                     | Reject writes based on stale state.                               |
+| `mutable`, `readOnly`, `field`, `indexed` | Advanced schema and read tuning.                                  |
 
 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
@@ -478,17 +465,16 @@ 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.
+| Method                       | Use it for                                                       |
+| ---------------------------- | ---------------------------------------------------------------- |
+| `load({ where })`            | Async hydration from backing store/server.                       |
+| `retrieve(id)`               | Synchronous read of one already-loaded row.                      |
+| `list(options?)`             | Synchronous collection read of loaded rows.                      |
+| `count(options?)`            | Synchronous count of loaded rows.                                |
+| `create(data, options?)`     | Create through the model client.                                  |
+| `update(id, data, options?)` | Update through the model client.                                  |
+| `delete(id, options?)`       | Delete through the model client.                                  |
+| `claimState(id)`             | See active work on a model row.                                  |
+| `claim(id, work, options?)`  | Wait for your turn, re-read, and hold the row while `work` runs. |
+
+Keep first integrations on the model methods above.