@abloatai/ablo 0.9.1 → 0.9.3

package/docs/identity.md

@@ -1,7 +1,7 @@
 # Identity & Sync Groups
 
 This is the doc the Quickstart skips: **who is connecting, and which slice
-of shared state do they get?** If you've wired `<AbloProvider schema={schema}>`
+of shared state do they get?** If you've wired `<AbloProvider client={ablo}>`
 and wondered where org / team / user actually come from — start here.
 
 ## Ablo does not do auth
@@ -37,9 +37,9 @@ runnable place, so the concepts below have code to attach to.
 
 The entire declaration surface is: `identityRoles` (who may see what), and on
 each model `scope` / `parent` / `grants` (which group a row fans out on), plus an
-optional `syncGroups` prop (narrowing). Read the three blocks first — a human
-gets their `org` / `team` scope, an agent gets one `deck` — then the sections
-after explain each.
+optional `scope` setting on the client (narrowing). Read the three blocks first —
+a human gets their `org` / `team` scope, an agent gets one `deck` — then the
+sections after explain each.
 
 ```ts
 // 1. src/ablo/schema.ts — map identity → groups, and anchor each model to a group
@@ -74,23 +74,28 @@ export const schema = defineSchema(
 ```
 
 ```tsx
-// 2. app/providers.tsx — a HUMAN gets their full org / team scope
-<AbloProvider schema={schema} userId={user.id} teamIds={user.teamIds}>
+// 2. app/providers.tsx — a HUMAN gets their full org / team scope.
+// teamIds is set on the client you build (Ablo({ schema, teamIds: user.teamIds })),
+// not passed to the provider; the provider just takes that client.
+<AbloProvider client={ablo} userId={user.id}>
   {children}
 </AbloProvider>
 ```
 
-```tsx
+```ts
 // 3. an AGENT run inherits its user, narrowed to the entities in play.
 // Pass the MODEL form — { decks: id } — not a hand-built `deck:<id>` string;
-// the engine derives the group from each model's `scope`.
-<AbloProvider
-  schema={schema}
-  userId={user.id}                // ceiling: the triggering user
-  scope={{ decks: deckId }}       // floor: just the deck it's working on
->
+// the engine derives the group from each model's `scope`. The narrowing lives
+// on the client you build, then the provider mounts it.
+const ablo = Ablo({
+  schema,
+  authEndpoint: '/api/ablo-session',
+  scope: { decks: deckId }, // floor: just the deck it's working on
+});
+
+<AbloProvider client={ablo} userId={user.id /* ceiling: the triggering user */}>
   {children}
-</AbloProvider>
+</AbloProvider>;
 ```
 
 That's the whole surface. The rest of this doc is the *why* behind each line.
@@ -126,8 +131,8 @@ That's why you never write per-user scope code, but you always pass an agent's
 scope at the call site. A user's org/team/user don't change per request, so
 their scope is a **rule the schema derives automatically**. An agent's reach
 depends on *what it's working on*, which is only knowable at dispatch — so you
-pass its `syncGroups` **at the call site, in code**. The schema's only job for
-entities is to declare *that* a model is
+set its `scope` on the client **at the dispatch site, in code**. The schema's
+only job for entities is to declare *that* a model is
 entity-scopable and *what its group is named* (`scope: 'deck'` → `deck:{id}`);
 it never declares *which* entities a given agent gets. (A human can opt into the
 same runtime narrowing — a page scoped to one deck — but by default a human's
@@ -298,45 +303,62 @@ server, never by the browser.**
 
 ## Wiring the provider
 
-The provider props carry the identity your server resolved. In a Next.js app,
-resolve the user in a Server Component and pass it down:
+The identity your server resolved is carried by the client you build and the
+`userId` prop. In a Next.js app, resolve the user in a Server Component and pass
+it down. Build the client once (the schema, `teamIds`, and any `scope` narrowing
+live here), then hand it to the provider:
+
+```ts
+// lib/ablo.ts
+import Ablo from '@abloatai/ablo';
+import { schema } from '@/ablo/schema';
+
+// Build the client from the identity your server already resolved.
+// teamIds → team sync groups via identityRoles.
+export function makeAblo(user: { teamIds: string[] }) {
+  return Ablo({
+    schema,
+    authEndpoint: '/api/ablo-session',
+    teamIds: user.teamIds,
+  });
+}
+```
 
 ```tsx
-// app/providers.tsx — 'use client'
+// app/providers.tsx
+'use client';
+
+import { useMemo } from 'react';
 import { AbloProvider } from '@abloatai/ablo/react';
-import { schema } from '@/ablo/schema';
+import { makeAblo } from '@/lib/ablo';
 
 export function Providers({
   children,
-  user,            // { id, teamIds } — resolved server-side from YOUR auth
+  user, // { id, teamIds } — resolved server-side from YOUR auth
 }: {
   children: React.ReactNode;
   user: { id: string; teamIds: string[] };
 }) {
+  const ablo = useMemo(() => makeAblo(user), [user.id]);
   return (
-    <AbloProvider
-      schema={schema}
-      userId={user.id}
-      teamIds={user.teamIds}
-      fallback={<AppSkeleton />}
-    >
+    <AbloProvider client={ablo} userId={user.id} fallback={<AppSkeleton />}>
       {children}
     </AbloProvider>
   );
 }
 ```
 
-What each identity-related prop does — and just as importantly, does *not* do:
+What carries identity — and just as importantly, what does *not* set the boundary:
 
-| Prop         | Purpose                                                                                          |
+| Where        | Purpose                                                                                          |
 | ------------ | ------------------------------------------------------------------------------------------------ |
-| `userId`     | App-level participant id, used for app-owned fields and read by your `identityRole` `source`. **Not** the security boundary — the server enforces scope from the authenticated request. |
-| `teamIds`    | Team ids expanded into team sync groups via your `identityRoles`.                                |
-| `syncGroups` | Optional. **Narrows** the subscription to a subset of what auth already allows — it can never widen it. Use it to scope a page to one entity (e.g. `['deck:abc123']`). |
+| `userId` prop | App-level participant id, used for app-owned fields and read by your `identityRole` `source`. **Not** the security boundary — the server enforces scope from the authenticated request. |
+| `teamIds` (on the client) | Team ids expanded into team sync groups via your `identityRoles`.                   |
+| `scope` (on the client) | Optional. **Narrows** the subscription to a subset of what auth already allows — it can never widen it. Use it to scope a page to one entity (e.g. `{ decks: 'abc123' }`). |
 
 Because the server is the boundary, a client that changes `userId` to another
 user's id does not gain their data — the server resolves and enforces the real
-identity on the connection. The props are how your app *tells* Ablo who it
+identity on the connection. These are how your app *tells* Ablo who it
 already authenticated, not how it *proves* it.
 
 ## Agents are participants too
@@ -374,16 +396,19 @@ decks:     model({ /* … */ }, {}, { orgScoped: true, scope: 'deck' }),
 Then a run subscribes only to the entity groups for the rows it works on — a
 subset of what its user could see:
 
-```tsx
-// agent run triggered by `user`, working on one document + one deck
-<AbloProvider
-  schema={schema}
-  // identity inherited from the triggering user (the ceiling)
-  userId={user.id}
+```ts
+// agent run triggered by `user`, working on one document + one deck.
+// The narrowing lives on the client; the provider just mounts it.
+const ablo = Ablo({
+  schema,
+  authEndpoint: '/api/ablo-session',
   // authority narrowed to just the entities in play (the floor).
   // Model form — keyed by model, resolved to groups via each model's `scope`.
-  scope={{ documents: documentId, decks: deckId }}
->
+  scope: { documents: documentId, decks: deckId },
+});
+
+// identity inherited from the triggering user (the ceiling)
+<AbloProvider client={ablo} userId={user.id}>
 ```
 
 As the run touches more entities its set **accretes** to cover them; it never
@@ -419,13 +444,13 @@ runs the [Coordinating long agent work](../README.md#coordinating-long-agent-wor
 `claim` loop is, to the scoping layer, that same participant — scoped to the row
 it claimed.
 
-## Narrowing to specific entities — the `scope` prop
+## Narrowing to specific entities — the `scope` setting
 
 A human gets their full membership automatically (`identityRoles`). To narrow a
 session — a page on one deck, or an agent pointed at the entities it's working
-on — pass `scope`. You give it the **model and id(s)**; the engine builds the
-group string from the model's `scope` (Half 2), so you never hand-write
-`deck:<id>`.
+on — set `scope` on the client you build (`Ablo({ schema, scope })`). You give it
+the **model and id(s)**; the engine builds the group string from the model's
+`scope` (Half 2), so you never hand-write `deck:<id>`.
 
 `scope` accepts four shapes, all resolved through the schema:
 
@@ -438,14 +463,16 @@ group string from the model's `scope` (Half 2), so you never hand-write
 
 ```tsx
 // a page on one deck
-<AbloProvider schema={schema} userId={user.id} scope={{ decks: deckId }} />
+const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session', scope: { decks: deckId } });
+<AbloProvider client={ablo} userId={user.id} />;
 
 // an agent working across two decks and a document
-<AbloProvider
-  schema={schema}
-  userId={user.id}
-  scope={{ decks: [deckA, deckB], documents: docId }}
-/>
+const ablo = Ablo({
+  schema,
+  authEndpoint: '/api/ablo-session',
+  scope: { decks: [deckA, deckB], documents: docId },
+});
+<AbloProvider client={ablo} userId={user.id} />;
 ```
 
 The key is the **model** (`decks`), the value is **which id(s)** — the `deck:`
@@ -453,8 +480,8 @@ prefix comes from that model's `scope: 'deck'`, never from a string you compose.
 
 > **`scope` means one thing: sync-group scope.** It appears in two places that
 > are the same concept — the model option `scope: 'deck'` (declares a scope root,
-> [Half 2](#half-2--per-model-scope-row--group)) and this `scope` prop (subscribe
-> to it). The lifecycle filter on [`list()`](./api.md#model-methods) is a separate
+> [Half 2](#half-2--per-model-scope-row--group)) and this `scope` client setting
+> (subscribe to it). The lifecycle filter on [`list()`](./api.md#model-methods) is a separate
 > axis and is named **`state`** (`'live' | 'archived' | 'all'`, GitHub's
 > open/closed/all), precisely so it doesn't share the word.
 
@@ -485,9 +512,9 @@ how to reason about it.
   the room/shape and the server signs off, as in
   [Pusher's channel authorization endpoint](https://pusher.com/docs/channels/server_api/authorizing-users/),
   [ElectricSQL **gatekeeper auth**](https://github.com/electric-sql/electric/blob/main/examples/gatekeeper-auth/README.md),
-  and Liveblocks **access tokens**. Ablo's `syncGroups` prop is the *narrowing*
-  half of this — but it can only ever shrink the server-derived set, never grow
-  it.
+  and Liveblocks **access tokens**. Ablo's client `scope` setting is the
+  *narrowing* half of this — but it can only ever shrink the server-derived set,
+  never grow it.
 
 The best practices Ablo inherits from that lineage:
 
@@ -503,9 +530,9 @@ The best practices Ablo inherits from that lineage:
    the line precisely: [token parameters are trusted and usable for access
    control; client parameters are not](https://docs.powersync.com/usage/sync-rules/advanced-topics/client-parameters).
    In Ablo terms, the identity your server vouches for is the *trusted* claim that
-   sets scope; the provider's `userId` / `scope` props are *untrusted client
-   input* — convenient for app-owned fields and narrowing, but never the boundary.
-   This is why changing `userId` in the browser grants nothing.
+   sets scope; the `userId` prop and the client's `scope` setting are *untrusted
+   client input* — convenient for app-owned fields and narrowing, but never the
+   boundary. This is why changing `userId` in the browser grants nothing.
 
 3. **Scope by a hierarchical naming convention, declared once.** Ablo's `kind:id`
    group naming (`org:…` / `team:…` from `identityRoles`, `deck:…` from a model's

package/docs/index.md

@@ -43,7 +43,7 @@ Three things stay true no matter how you use Ablo:
 - [Schema Contract](./schema-contract.md) — One schema becomes typed model clients, React reads, agent writes, Data Source shape, and schema push.
 - [CLI & Migrations](./cli.md) — `init` / `migrate` / `push` / `generate`, the shared Zod→Postgres type map, and structured migration errors.
 - [Identity & Sync Groups](./identity.md) — Use your own authentication; tell Ablo who's connecting and how org / team / user map to sync-group scope.
-- [Integration Guide](./integration-guide.md) — Choose Ablo-managed state, Data Source, React, multiplayer, and agent patterns.
+- [Integration Guide](./integration-guide.md) — Connect your database via Data Source, plus React, multiplayer, and agent patterns.
 - [Guarantees](./guarantees.md) — What confirmed writes, stale checks, and claims guarantee.
 - [Interaction Model](./interaction-model.md) — The schema, claim, update, confirmation loop.
 - [API Reference](./api.md) — Model-by-model method shape.
@@ -57,7 +57,7 @@ Three things stay true no matter how you use Ablo:
 | Plane | Primitives | Purpose |
 |---|---|---|
 | State | `Schema`, `Model`, `Claim`, `Receipt` | The product path. Load, coordinate, write, confirm. |
-| Storage | `Managed State`, `Data Source` | Ablo stores declared models by default; existing app tables use a signed Data Source. |
+| Storage | `Data Source` | Your rows live in your own database behind a signed Data Source endpoint. |
 
 ## Use cases
 

package/docs/integration-guide.md

@@ -42,14 +42,11 @@ schema -> ablo.<model>.list(...) -> ablo.<model>.update(...)
 Commits and receipts exist under the hood. Most apps do not create protocol
 objects by hand.
 
-## Pick The Backing Mode
+## Your Database
 
-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. |
+Every schema model is backed by **your own database**. You expose a signed Data
+Source endpoint; Ablo coordinates each write and your app commits it to your
+Postgres. The SDK call shape is the same everywhere.
 
 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
@@ -170,17 +167,49 @@ export const ablo = Ablo({
 ```
 
 Browser apps should use the React provider or a scoped session token, not a
-server API key in the bundle.
+server API key in the bundle. Build the client first, then hand it to the
+provider — `AbloProvider` takes `{ client, userId?, onError?, fallback? }`, and
+nothing else (`schema`, `teamIds`, `scope`, and `authEndpoint` all live on the
+client now).
+
+```tsx
+// src/ablo-client.ts
+import Ablo from '@abloatai/ablo';
+import { schema } from '@/ablo/schema';
+
+// The browser never holds the API key. The client mints a short-lived token
+// from your session route (see below) and refreshes it before expiry.
+export const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session' });
+```
 
 ```tsx
 // app/providers.tsx
 'use client';
 
 import { AbloProvider } from '@abloatai/ablo/react';
-import { schema } from '@/ablo/schema';
+import { ablo } from '@/ablo-client';
 
 export function Providers({ children }: { children: React.ReactNode }) {
-  return <AbloProvider schema={schema}>{children}</AbloProvider>;
+  return <AbloProvider client={ablo}>{children}</AbloProvider>;
+}
+```
+
+The session route mints the scoped token server-side, where the API key lives:
+
+```ts
+// app/api/ablo-session/route.ts
+import Ablo from '@abloatai/ablo';
+import { schema } from '@/ablo/schema';
+import { auth } from '@/auth';
+
+export const runtime = 'nodejs';
+
+const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+
+export async function POST() {
+  const session = await auth(); // your own auth — returns the signed-in user
+  const { token } = await sync.sessions.create({ user: { id: session.userId } });
+  return Response.json({ token });
 }
 ```
 
@@ -214,10 +243,11 @@ refreshes before expiry.
 ## 3. Read State
 
 Reads come in two flavors, and you pick based on whether you can wait.
-`retrieve(id)` and `list({ where })` hit the server (and hydrate the local
-store) — they're async, so you `await` them. `get(id)`, `getAll({ where })`,
-and `getCount({ where })` read the already-synced local graph synchronously, so
-they're the ones you call in render.
+`retrieve({ id })` and `list({ where })` hit the server (and hydrate the local
+store) — they're async, so you `await` them. `get(id)` (positional),
+`getAll({ where })`, and `getCount({ where })` read the already-synced local
+graph synchronously, so they're the ones you call in render — and the ones you
+use inside a `useAblo` selector, never the async `retrieve`/`list`.
 
 Use `retrieve` when the row may not be local yet — it fetches from the server
 and waits.
@@ -345,47 +375,41 @@ For the full Python shape, see
 
 ## 7. Data Source Endpoint
 
-Use a Data Source when your app database remains the source of truth.
+Use a Data Source when your app database remains the source of truth. Wire the
+route with `dataSourceNext` and an adapter — `prismaDataSource(prisma, schema)`
+or `drizzleDataSource(db, schema)`. You don't hand-write `commit`; the adapter
+owns transactional commit, idempotency, and reads.
 
 ```ts
 // app/api/ablo/source/route.ts
-import { dataSource } from '@abloatai/ablo';
+import { dataSourceNext } from '@abloatai/ablo/source/next';
+import { prismaDataSource } from '@abloatai/ablo/source';
 import { schema } from '@/ablo/schema';
-import { db } from '@/db';
-
-export const POST = dataSource({
-  schema,
-  apiKey: process.env.ABLO_API_KEY,
+import { prisma } from '@/db';
 
-  authorize() {
-    return { db };
-  },
+export const runtime = 'nodejs';
 
-  async commit({ operations, clientTxId, context }) {
-    const rows = await context.auth.db.transaction(async (tx) => {
-      await tx.idempotency.upsert({ key: clientTxId });
-      return applyOperations(tx, operations);
-    });
+export const { POST } = dataSourceNext({
+  schema,
+  apiKey: process.env.ABLO_API_KEY!,
+  adapter: prismaDataSource(prisma, schema),
+});
+```
 
-    return { rows };
-  },
+With Drizzle, pass `drizzleDataSource(db, schema)` instead — the adapter takes
+your Drizzle `db` and the Ablo `schema` (not your table objects):
 
-  reports: {
-    async load({ id, context }) {
-      return context.auth.db.report.findUnique({ where: { id } });
-    },
+```ts
+import { drizzleDataSource } from '@abloatai/ablo/source/drizzle';
 
-    async list({ query, context }) {
-      return context.auth.db.report.findMany({
-        take: query.limit ?? 100,
-      });
-    },
-  },
+export const { POST } = dataSourceNext({
+  schema,
+  apiKey: process.env.ABLO_API_KEY!,
+  adapter: drizzleDataSource(db, schema),
 });
 ```
 
-Ablo needs your Data Source endpoint and API key. External writes can be
-reported through an optional `events` handler on the same route. Your app
+Ablo needs your Data Source endpoint and API key. Your app
 stores one Ablo credential:
 
 ```bash
@@ -404,16 +428,18 @@ which a human might touch the same row. Wrap that work in a claim. Claims don't
 lock. If another writer holds the row, `claim` waits for them, re-reads the
 fresh row, then hands it to you — so two writers serialize instead of clobbering.
 
-```ts
-const report = await ablo.weatherReports.retrieve({ id: reportId });
-if (!report) return;
+A claim is a disposable handle (`await using`), not a callback: read the fresh
+row off `claim.data`, do your work, and the handle auto-releases when it leaves
+scope.
 
+```ts
 await using claim = await ablo.weatherReports.claim({
   id: reportId,
-  wait: false,
   action: 'forecasting',
 });
 const claimed = claim.data;
+if (!claimed) return;
+
 await ablo.weatherReports.update({
   id: claimed.id,
   data: { status: 'ready', forecast: await getForecast(claimed) },
@@ -464,17 +490,19 @@ them.
 
 ## Method Cheatsheet
 
-| Method                       | Use it for                                                                  |
-| ---------------------------- | --------------------------------------------------------------------------- |
-| `retrieve(id)`               | Async read of one row from the server (await it).                           |
-| `list({ where })`           | Async read of many rows from the server (await it).                         |
-| `get(id)`                    | Synchronous local read of one synced row (use in render).                   |
-| `getAll({ where })`         | Synchronous local read of many synced rows.                                 |
-| `getCount({ where })`       | Synchronous local count of synced 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.                                            |
-| `claim.state({ id })`            | See who is currently working on a row (synchronous).                       |
-| `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.
+| Method                                 | Use it for                                                                       |
+| -------------------------------------- | -------------------------------------------------------------------------------- |
+| `retrieve({ id })`                     | Async read of one row from the server (await it).                                |
+| `list({ where })`                      | Async read of many rows from the server (await it).                              |
+| `get(id)`                              | Synchronous local read of one synced row (positional id; use in render).         |
+| `getAll({ where })`                    | Synchronous local read of many synced rows.                                      |
+| `getCount({ where })`                  | Synchronous local count of synced rows.                                          |
+| `create({ data, id? })`                | Create through the model client.                                                 |
+| `update({ id, data, ...opts })`        | Update through the model client.                                                 |
+| `delete({ id, ...opts })`              | Delete through the model client.                                                 |
+| `claim.state({ id })`                  | See who is currently working on a row (synchronous).                             |
+| `claim({ id, action?, ttl? })`         | Acquire a disposable handle: wait for your turn, re-read, and hold the row.       |
+
+Keep first integrations on the model methods above. Every mutation and
+server-read verb takes one options object; only the synchronous `get(id)` stays
+positional.

package/docs/mcp.md

@@ -83,7 +83,7 @@ Per-client walkthroughs:
 | `get_recipe` | Returns the full markdown of one doc by name (e.g. `readme`, `quickstart`, `schema-contract`, `integration-guide`, `api`, `guarantees`). |
 | `get_api_surface` | Returns the structured export list for an SDK subpath (`@abloatai/ablo`, `./react`, `./schema`, `./testing`, …). Call with no argument to list every subpath. |
 | `validate_schema` | Lints `defineSchema` source against the DSL rules (camelCase fields, lowercase model keys, `scope`/`grants` sync groups, valid `load` strategies, no legacy builders) and returns a structured issue list. Runs no code. |
-| `scaffold_app` | Emits a starter file tree for a schema-first integration — `next`, `node-agent`, or `plain`, with `managed` or `data-source` storage. |
+| `scaffold_app` | Emits a starter file tree for a schema-first integration — `next`, `node-agent`, or `plain`, with a `data-source` (your own database) endpoint. |
 
 #### Resources