@abloatai/ablo 0.9.1 → 0.9.3

package/docs/data-sources.md

@@ -1,26 +1,33 @@
 # Connect Your Database
 
-By default, Ablo stores the rows for the models you define, so you don't need a
-database to get started. But if you already have your own application database
-and want it to stay the source of truth, you can attach it as a Data Source —
-then Ablo coordinates each write and calls your app to commit it, instead of
-storing the data itself.
-
-That default makes Ablo the managed state store for your models, the same way
-Stripe stores `Customer` and `PaymentIntent` objects that you create through
-Stripe's API.
-
-Either way, you define an Ablo schema with `defineSchema`, `model`, and Zod —
-the same way a Prisma project starts with a `schema.prisma`. Your schema
-describes your data once, and everything else (the SDK, agents, and your
-database connection) relies on that one definition.
-
-Your app can keep using its own `DATABASE_URL`. Store that value in your app or
-backend environment, not in Ablo. The integration boundary is the HTTPS
-endpoint your app exposes. The happy path uses the same server-side
-`ABLO_API_KEY` to verify Ablo calls.
-
-Use the SDK with an API key:
+**Your database is the system of record — Ablo never hosts your data.** Every
+synced model is backed by your own Postgres; Ablo is the transaction layer on
+top of it. There are two ways to connect, and they are the same product with the
+same writes — the only difference is where your database credential lives:
+
+| | How Ablo reaches your Postgres | Use when |
+|---|---|---|
+| **Connection string** (default) | You pass `databaseUrl` to `Ablo(...)`; Ablo registers the connection and commits each write directly, behind row-level security. | You can hand over a scoped connection string. |
+| **Signed endpoint** | Your app exposes one route built from an ORM adapter; Ablo sends signed commit requests and your app writes its own database. | Database credentials must never leave your infrastructure. |
+
+Either way, you define an Ablo schema with `defineSchema`, `model`, and Zod. The
+Ablo schema describes **only your synced, collaborative models** — the rows Ablo
+coordinates and fans out in realtime. It is *not* your whole-database schema and
+does *not* replace your `schema.prisma` (or your Drizzle schema). Your auth,
+billing, and any other non-synced tables stay in your own ORM schema, owned by
+your own migrations. One database, two schemas, side by side: Ablo owns the
+synced models; you keep owning everything else. `ablo check` reflects this — it
+reports your other tables as "ignored / owned by you," which is exactly right.
+
+What Ablo stores, in both shapes: your schema *definition* (model names, fields,
+types — pushed with `ablo push`), your hashed API keys, a safe projection of the
+connection registration (host, database, schema — the connection string itself
+is sealed and never echoed back), and the commit log that drives sync. Never
+your rows.
+
+## Connection String (default)
+
+The canonical client carries all three values:
 
 ```ts
 import Ablo from '@abloatai/ablo';
@@ -29,29 +36,50 @@ import { schema } from './ablo/schema';
 export const ablo = Ablo({
   schema,
   apiKey: process.env.ABLO_API_KEY,
+  databaseUrl: process.env.DATABASE_URL, // your Postgres — rows live here, never with Ablo
 });
 ```
 
-Do not pass a database URL to `Ablo(...)`.
-
-For the first production integration, prefer this shape:
-
 ```bash
-# Stored only in your app/backend
-DATABASE_URL=postgres://...
-
-# The only Ablo credential in the customer app
+# .env — server runtime only, never the browser
+DATABASE_URL=postgres://ablo_app:...@host:5432/db
 ABLO_API_KEY=sk_live_...
 ```
 
-## Backing Modes
+On first connect the SDK registers the connection — sent once over TLS, stored
+sealed, never returned by any API. From then on Ablo commits every confirmed
+write directly to your database and reads canonical rows from it.
+
+Safety requirements, enforced server-side before the first write:
+
+- **Non-superuser role.** The connection must not be a superuser or hold
+  `BYPASSRLS` — Ablo's tenant isolation is row-level security, and a role that
+  can bypass it is rejected outright.
+- **Row-level security on synced tables.** `npx ablo migrate` provisions your
+  synced-model tables with `FORCE ROW LEVEL SECURITY` already applied; tables
+  you create yourself must do the same.
+- **Public hosts only.** Connection strings resolving to loopback or private
+  address ranges are rejected.
 
-| Mode | Where rows live | What `create/update/delete` does | Use when |
-|---|---|---|---|
-| Ablo-managed | Ablo | Writes directly to Ablo's managed state store, then returns the confirmed row and fans out realtime deltas. | New collaborative/agent state that can live in Ablo. |
-| Data Source | Your app database | Sends a signed commit request to your route; your app writes its DB and returns canonical rows. | Existing app tables, regulated data, or teams that need their DB to stay canonical. |
+`databaseUrl` is server-only: the SDK throws if it sees one in a browser-like
+environment, and `dangerouslyAllowBrowser` does not override that.
 
-The SDK call is the same in both modes:
+## Signed Endpoint
+
+When a connection string must not leave your infrastructure, keep
+`DATABASE_URL` in your app and expose one HTTPS endpoint instead. Ablo signs a
+commit request; an ORM adapter in your route runs it in one transaction against
+your Postgres and returns the canonical rows. Omit `databaseUrl` from
+`Ablo(...)` in this setup — the client takes only the schema and the API key:
+
+```ts
+export const ablo = Ablo({
+  schema,
+  apiKey: process.env.ABLO_API_KEY,
+});
+```
+
+The SDK call is identical in both shapes:
 
 ```ts
 await ablo.weatherReports.create({ data: { location: 'Stockholm', status: 'pending' } });
@@ -59,20 +87,18 @@ await ablo.weatherReports.update({ id: 'report_stockholm', data: { status: 'read
 const report = ablo.weatherReports.get('report_stockholm');
 ```
 
-Only the backing store changes.
-
-Multiplayer behavior is the same in both modes. Writes made through
+Multiplayer behavior is built in. Writes made through
 `ablo.<model>.create/update/delete` are coordinated by Ablo, then confirmed rows
 fan out to subscribers. If something writes to your database without going
 through Ablo (a cron job, an admin tool), Ablo can't know about it
 automatically. To keep everyone's screen up to date, your app reports those
-outside changes back through an events feed — shown below in
-[External Writes](#external-writes).
+outside changes back through the outbox feed — shown below in
+[Outbox Events](#outbox-events).
 
-## When To Use A Data Source
+## Your Database Stays Canonical
 
-Use a Data Source only when your existing application database remains the
-source of truth and Ablo should coordinate writes against it.
+Your application database remains the source of truth and Ablo coordinates writes
+against it.
 
 If you are migrating an app where every button already calls a backend endpoint,
 read [Integration Guide](./integration-guide.md) first, then
@@ -100,59 +126,53 @@ The shape is the same as a production webhook integration:
 
 ## Route
 
+You don't hand-write the commit transaction, the idempotency upsert, or the
+outbox writes. You pass an ORM **adapter** and it does all of that for you —
+transaction, exactly-once idempotency, and outbox — driven by the same Ablo
+schema. The whole route is three fields:
+
 ```ts
 // app/api/ablo/source/route.ts
-import { dataSource, sourceEventForOperation } 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';
+import { prisma } from '@/lib/prisma';
 
-export const POST = dataSource({
+// Data Source routes touch the database, so they run on the Node runtime.
+export const runtime = 'nodejs';
+
+export const { POST } = dataSourceNext({
   schema,
-  apiKey: process.env.ABLO_API_KEY,
+  apiKey: process.env.ABLO_API_KEY!,
+  adapter: prismaDataSource(prisma, schema),
+});
+```
 
-  authorize() {
-    return { db };
-  },
+Using Drizzle instead of Prisma is the same shape — swap the adapter for
+`drizzleDataSource(db, schema)`:
 
-  async commit({ operations, clientTxId, context }) {
-    const rows = await context.auth.db.transaction(async (tx) => {
-      await tx.idempotency.upsert({ key: clientTxId, operations });
-      const changes = await applyOperations(tx, operations);
-      await tx.outbox.createMany({
-        data: changes.map(({ eventId, operation, entityId, data }) =>
-          sourceEventForOperation({
-            eventId,
-            operation,
-            entityId,
-            data,
-            ...(clientTxId ? { clientTxId } : {}),
-            ...(context.scope?.organizationId
-              ? { organizationId: context.scope.organizationId }
-              : {}),
-            occurredAt: Date.now(),
-          }),
-        ),
-      });
-      return changes.map(({ row }) => row);
-    });
-
-    return { rows };
-  },
+```ts
+// app/api/ablo/source/route.ts
+import { dataSourceNext } from '@abloatai/ablo/source/next';
+import { drizzleDataSource } from '@abloatai/ablo/source/drizzle';
+import { schema } from '@/ablo/schema';
+import { db } from '@/db';
 
-  reports: {
-    async load({ id, context }) {
-      return context.auth.db.report.findUnique({ where: { id } });
-    },
+export const runtime = 'nodejs';
 
-    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),
 });
 ```
 
+The adapter is constructed from your ORM client and the Ablo `schema` —
+`prismaDataSource(prisma, schema)` or `drizzleDataSource(db, schema)`. It maps
+each synced model to your table, wraps every commit in one transaction, dedupes
+on `clientTxId` via `ablo_idempotency`, and appends `ablo_outbox` rows for the
+external-write feed — the bookkeeping you used to write by hand.
+
 Your app code still writes through the normal model API:
 
 ```ts
@@ -208,55 +228,39 @@ events.
 
 ## Outbox Events
 
-Return your outbox feed from an `events` handler so connected humans and agents
-stay current. Include SDK-origin events too. If Ablo already appended the commit
-directly, `clientTxId` lets Ablo filter the echo; if the direct append failed,
-the same outbox row repairs it on the next poll or push.
+The adapter serves the outbox feed for you. Every `commit` it runs appends one
+`ablo_outbox` row per operation in the same transaction, and the adapter's
+built-in events handler streams those rows back to Ablo by cursor — so connected
+humans and agents stay current with no extra code. If Ablo already appended the
+commit directly, `clientTxId` lets Ablo filter the echo; if the direct append
+failed, the same outbox row repairs it on the next poll or push.
 
-```ts
-export const POST = dataSource({
-  schema,
-  apiKey: process.env.ABLO_API_KEY,
+Events without `clientTxId` are treated as external writes. The only thing you
+add by hand is recording *outside* writes — changes made to your tables by a
+cron job or admin tool that never went through Ablo. Append an `ablo_outbox` row
+(with no `clientTxId`) for those in the same transaction as the change, and the
+adapter's feed carries them to every connected screen.
 
-  async events({ cursor, limit, context }) {
-    const page = await context.auth.db.outbox.after(cursor, { limit });
-
-    return {
-      events: page.rows.map((row) => ({
-        id: row.id,
-        model: row.model,
-        entityId: row.entityId,
-        type: row.type,
-        data: row.data,
-        organizationId: row.organizationId,
-        clientTxId: row.clientTxId,
-        occurredAt: row.createdAt.getTime(),
-      })),
-      nextCursor: page.nextCursor,
-    };
-  },
-});
-```
-
-Events without `clientTxId` are treated as external writes.
+## Production Checklist (signed endpoint)
 
-## Production Checklist
-
-Before using a customer-owned database in production:
+Before using the signed-endpoint shape in production:
 
 - Keep `DATABASE_URL` in the customer app or backend environment.
 - Use only the Data Source endpoint and `ABLO_API_KEY` as the customer-facing integration boundary.
-- Verify signatures before opening a database transaction.
-- Store `clientTxId` in an idempotency table before applying writes.
-- Return canonical rows after each commit.
-- Write outbox events in the same transaction as every app-row write, including
-  Data Source `commit` writes.
-- Dedupe outbox events by event `id`.
+- Run the adapter migrations so `ablo_outbox` and `ablo_idempotency` exist
+  alongside your synced tables (`ablo migrate`).
+- Set `export const runtime = 'nodejs'` on the route so it can reach the database.
+- For writes that bypass Ablo (cron, admin tools), append an `ablo_outbox` row
+  (no `clientTxId`) in the same transaction as the change.
 - Monitor last success, last error, retry count, event lag, and cursor.
 
-Don't give Ablo your database URL for this integration — Ablo never connects to
-your database directly. (Direct database access would be a separate product with
-its own security model.)
+The adapter already handles the rest — signature verification, the commit
+transaction, `clientTxId` idempotency, returning canonical rows, the outbox
+append per operation, and deduping the feed by event `id`. You don't write any of
+that by hand.
+
+In this shape, leave `databaseUrl` out of `Ablo(...)` — the endpoint *is* the
+connection, and registering both would point Ablo at your database twice.
 
 ## Security
 

package/docs/examples/ai-sdk-tool.md

@@ -7,7 +7,8 @@ Claims don't lock. If another writer holds the row, `claim` waits for them, re-r
 ```ts
 import Ablo from '@abloatai/ablo';
 import { defineSchema, model, z as schemaZ } from '@abloatai/ablo/schema';
-import { streamText, tool } from 'ai';
+import { anthropic } from '@ai-sdk/anthropic';
+import { convertToModelMessages, streamText, tool, type UIMessage } from 'ai';
 import { z } from 'zod';
 
 const schema = defineSchema({
@@ -62,17 +63,22 @@ const updateReport = tool({
 });
 
 export async function POST(req: Request) {
-  const { messages, model } = await req.json();
+  // `useChat` posts UIMessage[]; the model is a server-bound provider instance,
+  // never read off the request body.
+  const { messages }: { messages: UIMessage[] } = await req.json();
 
   return streamText({
-    model,
-    messages,
+    model: anthropic('claude-sonnet-4-6'),
+    messages: await convertToModelMessages(messages),
     tools: { updateReport },
   }).toUIMessageStreamResponse();
 }
 ```
 
-The model provider is interchangeable. What matters is that the tool:
+The model provider is interchangeable — swap `anthropic(...)` for any
+server-bound provider instance. What matters is that the route binds the model
+on the server (never trusting one sent in the request body), converts the
+incoming `UIMessage[]` with `convertToModelMessages`, and that the tool:
 
 - reads the latest weather report with `retrieve` (a server read),
 - claims the row — if someone else holds it, the claim waits for them, then re-reads,

package/docs/examples/existing-python-backend.md

@@ -46,7 +46,7 @@ export const schema = defineSchema({
 ```
 
 ```ts
-// web/ablo.ts
+// web/ablo.ts — SERVER-ONLY client (holds the sk_ key; never imported in the browser).
 import Ablo from '@abloatai/ablo';
 import { schema } from './ablo/schema';
 
@@ -56,18 +56,40 @@ export const ablo = Ablo({
 });
 ```
 
-Mount the React provider near the app root so client components can subscribe to
-model clients without importing server credentials.
+Mount the React provider near the app root. Build the browser client first —
+with an `authEndpoint` so it mints a short-lived session token instead of
+carrying the secret key — then pass it to the provider via `client`.
 
 ```tsx
 // web/app/providers.tsx
 'use client';
 
+import Ablo from '@abloatai/ablo';
 import { AbloProvider } from '@abloatai/ablo/react';
 import { schema } from '@/ablo/schema';
 
+// Browser client: no secret key — `authEndpoint` mints the session token
+// server-side (see the session route below).
+const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session' });
+
 export function Providers({ children }: { children: React.ReactNode }) {
-  return <AbloProvider schema={schema}>{children}</AbloProvider>;
+  return <AbloProvider client={ablo}>{children}</AbloProvider>;
+}
+```
+
+The session route mints with the server client that holds the `sk_` key — the
+browser only ever sees the short-lived token:
+
+```ts
+// web/app/api/ablo-session/route.ts
+import { ablo } from '@/ablo';
+
+export const runtime = 'nodejs';
+
+export async function POST() {
+  const userId = await currentUserId(); // your auth
+  const { token } = await ablo.sessions.create({ user: { id: userId } });
+  return Response.json({ token });
 }
 ```
 

package/docs/examples/nextjs.md

@@ -36,9 +36,10 @@ import { ablo } from '@/lib/ablo';
 
 export default async function ReportPage({
   params,
-}: { params: { id: string } }) {
+}: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
   await ablo.ready();
-  const report = await ablo.weatherReports.retrieve({ id: params.id });
+  const report = await ablo.weatherReports.retrieve({ id });
   if (!report) return null;
 
   return <ReportEditor report={report} />;

package/docs/examples/scoped-agent.md

@@ -46,26 +46,53 @@ export const schema = defineSchema(
 ## 2. Dispatch — narrow the agent to the deck it's working on
 
 An agent can never reach more than the user who triggered it — that's the upper
-limit. From there you narrow it to a single deck with `scope`. You pass the
-**model and id** — `{ decks: deckId }`, never a `deck:<id>` string; the engine
-builds the group from the `decks` model's `scope`.
+limit. From there you narrow it to a single deck by minting the agent's session
+against **just that deck's sync group**. You build the group from the **model
+kind and id** with the typed `syncGroup` helper — `syncGroup('deck', deckId)`,
+never a hand-assembled `deck:<id>` string — where `'deck'` is the kind declared
+by the `decks` model's `scope`.
+
+Mint the scoped session on your backend (it holds the `sk_` key; the browser
+never does), then hand the short-lived token to the browser client:
+
+```ts
+// server — mints a scoped agent session for one deck
+import Ablo from '@abloatai/ablo';
+import { syncGroup } from '@abloatai/ablo/schema';
+import { schema } from './schema';
+
+const server = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+
+export async function mintDeckAgentSession(deckId: string, agentId: string) {
+  const { token } = await server.sessions.create({
+    agent: { id: agentId },
+    can: { slides: ['read', 'update'] }, // operation allowlist for this run
+    syncGroups: [syncGroup('deck', deckId)], // narrowed to just this deck
+  });
+  return token;
+}
+```
 
 ```tsx
+// client — the browser client carries only the scoped token.
+import Ablo from '@abloatai/ablo';
 import { AbloProvider } from '@abloatai/ablo/react';
+import { schema } from './schema';
+
+const ablo = Ablo({
+  schema,
+  getToken: async () => mintDeckAgentSession(deckId, agentId),
+});
 
 // The agent run is mounted on behalf of its triggering user.
-<AbloProvider
-  schema={schema}
-  userId={triggeringUser.id}   // ceiling: can't exceed this user's reach
-  scope={{ decks: deckId }}    // floor: narrowed to just this deck → deck:<deckId>
->
+<AbloProvider client={ablo} userId={triggeringUser.id}>
   {children}
 </AbloProvider>
 ```
 
-`scope` requests, it never grants: at connect the server intersects the groups
-you ask for with the groups the identity is actually allowed, so the agent can
-never reach a deck its triggering user couldn't.
+`syncGroups` requests, it never grants: at connect the server intersects the
+groups the session asks for with the groups the identity is actually allowed,
+so the agent can never reach a deck its triggering user couldn't.
 
 ## 3. Write — it fans out to everyone on that deck
 

package/docs/guarantees.md

@@ -109,7 +109,7 @@ authorized it, which run did it, and what state was it based on?"
 
 ## Persistence
 
-Ablo defaults to volatile in-memory persistence, so nothing is written to disk
+Ablo defaults to in-memory persistence ('memory'), so nothing is written to disk
 unless you ask for it.
 
 Opt into a durable browser cache that survives reloads when you need it:
@@ -122,7 +122,7 @@ const ablo = Ablo({
 });
 ```
 
-Node, SSR, tests, and agents use volatile in-memory persistence automatically.
+Node, SSR, tests, and agents use in-memory persistence ('memory') automatically.
 
 ## Storage Boundary