@abloatai/ablo 0.9.0 → 0.9.2

package/dist/source/migrations.js

@@ -0,0 +1,39 @@
+/**
+ * The table-creation SQL every ORM adapter ships for its OWN infrastructure tables —
+ * `ablo_idempotency` (dedupe by clientTxId) and `ablo_outbox` (transactional
+ * outbox the `events()` feed reads). Defined ONCE here so the Prisma adapter, the
+ * Drizzle adapter, and `ablo migrate` can never disagree on the shape (they used
+ * to inline their own copies, which had already drifted in whitespace).
+ *
+ * These are NOT model tables and are NOT emitted by the hosted provisioner
+ * (`generateProvisionPlan`) — the hosted path uses `sync_deltas` directly. They
+ * exist only on a customer's own database in Data Source mode.
+ */
+/** Canonical adapter-owned table-creation SQL. Idempotent (`IF NOT EXISTS`). */
+export function adapterTableMigrations() {
+    return [
+        {
+            name: 'ablo_idempotency',
+            up: `CREATE TABLE IF NOT EXISTS ablo_idempotency (
+  client_tx_id TEXT PRIMARY KEY,
+  response     JSONB NOT NULL,
+  created_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);`,
+        },
+        {
+            name: 'ablo_outbox',
+            up: `CREATE TABLE IF NOT EXISTS ablo_outbox (
+  cursor          BIGSERIAL PRIMARY KEY,
+  id              TEXT NOT NULL UNIQUE,
+  model           TEXT NOT NULL,
+  entity_id       TEXT NOT NULL,
+  type            TEXT NOT NULL,
+  data            JSONB,
+  organization_id TEXT,
+  client_tx_id    TEXT,
+  occurred_at     BIGINT,
+  created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
+);`,
+        },
+    ];
+}

package/dist/types/streams.d.ts

@@ -52,7 +52,8 @@ export interface AgentDelta {
     capabilityId?: string | null;
     /** Whether the human explicitly approved the change. */
     confirmationState?: ConfirmationState | null;
-    /** Turn handle that caused this commit. */
+    /** Agent-task id that caused this commit, if any. Dormant on new client
+     *  writes (turns/tasks removed); may hold historical values. */
     causedByTaskId?: string | null;
     createdAt: string;
 }

package/dist/wire/frames.d.ts

@@ -76,14 +76,12 @@ export interface CommitMessage {
         operations: CommitOperation[];
         clientTxId: string;
         /**
-         * Optional turn handle. When the SDK opens a turn via
-         * `SyncAgent.beginTurn(...)`, subsequent commits within the handle's
-         * scope auto-attach the `turnId` here. The Hub validates the turn
-         * belongs to the same agent and is open, then threads it onto every
-         * delta's `caused_by_task_id` column. Absent for human-direct commits
-         * and for SDKs that predate the turn protocol — those produce deltas
-         * with `caused_by_task_id = NULL`, which the audit pane treats as "no
-         * prompt-side context recorded."
+         * Dormant agent-task lineage field. The SDK no longer populates it —
+         * turns/tasks were removed and write attribution now rides on the
+         * claim (`intent`) id plus the server-stamped actor/capability. Kept
+         * optional for wire-compat; when present the Hub still validates and
+         * threads it onto `caused_by_task_id`, but client writes leave it
+         * `null` (the audit pane treats null as "no prompt-side context").
          */
         causedByTaskId?: string | null;
     };

package/docs/api.md

@@ -8,7 +8,7 @@ row, you can optionally `claim` it so they serialize instead of clobbering
 each other.
 
 Two things to know before the method list. **Reads come in two flavors:**
-`retrieve(id)` / `list({ where })` are async and hit the server (use them when
+`retrieve({ id })` / `list({ where })` are async and hit the server (use them when
 the row may not be local yet); `get(id)` / `getAll({ where })` / `getCount({ where })`
 are synchronous reads off the local graph (use them in render, after data has
 synced). **Claims don't lock.** If another writer holds the row, `claim` waits

package/docs/cli.md

@@ -57,9 +57,9 @@ either mode) defines the same models test and live see; only the rows differ.
 | `ablo dev`                         | **Hosted** — push the schema to your test sandbox, then watch `ablo/schema.ts` and re-push on save.                                           | `--no-watch`, `--schema <path>`, `--export <name>`, `--url <url>`                                      |
 | `ablo logs`                        | Tail your scope's commit activity (`stripe logs tail`). Follows by default.                                                                   | `-n, --tail <N>`, `--since <dur\|ts>`, `--model`, `--op`, `--json`, `--no-follow`, `--mode test\|live` |
 | `ablo push`                        | **Hosted** — upload the schema to Ablo; the server diffs, migrates, and activates it.                                                         | `--force`, `--rename old:new`, `--backfill model.field=value`, `--schema`, `--export`, `--url`         |
-| `ablo migrate`                     | **Direct Postgres** — apply the schema to your own `DATABASE_URL` (you run the DDL).                                                          | `--dry-run`, `--output <file>`, `--schema`, `--export`                                                 |
+| `ablo migrate`                     | **Direct Postgres** — provision just the synced models (plus the adapter's `ablo_outbox` / `ablo_idempotency`) in your own `DATABASE_URL`. Leaves your other tables alone.                                                          | `--dry-run`, `--output <file>`, `--schema`, `--export`                                                 |
 | `ablo pull`                        | **Direct Postgres** — generate `defineSchema(...)` from your existing tables (read-only, like `prisma db pull`).                              | `--out <path>`, `--app-schema <name>`, `--import <pkg>`, `--force`                                     |
-| `ablo check`                       | **Direct Postgres** — verify your _existing_ tables fit the schema (read-only, no DDL).                                                       | `--schema <path>`, `--export <name>`, `--app-schema <name>`                                            |
+| `ablo check`                       | **Direct Postgres** — verify your _existing_ tables fit the schema (read-only, no schema changes).                                                       | `--schema <path>`, `--export <name>`, `--app-schema <name>`                                            |
 | `ablo generate`                    | Emit TypeScript types from the schema.                                                                                                        | `--out <path>`, `--schema`, `--export`                                                                 |
 
 ## `ablo dev`
@@ -144,9 +144,9 @@ reshaping it. `ablo check` is read-only; it never proposes a migration.
 ## `migrate` (Direct Postgres) vs `push` (Hosted)
 
 Same engine, two setups. If you use the **Direct Postgres connector**, use
-`ablo migrate` — it applies the schema to your own `DATABASE_URL`, and you run
-the DDL. If Ablo manages the sandbox/hosted store, use `ablo push` and
-`ablo dev` — the server applies the change and version-gates connecting clients.
+`ablo migrate` — it provisions the synced models in your own `DATABASE_URL`. If
+Ablo manages the sandbox/hosted store, use `ablo push` and `ablo dev` — the
+server applies the change and version-gates connecting clients.
 
 ```bash
 ablo migrate --dry-run            # preview the exact SQL
@@ -154,6 +154,19 @@ ablo migrate                      # apply to DATABASE_URL
 ablo migrate --output schema.sql  # write SQL to a file
 ```
 
+### One database, two schemas
+
+`ablo migrate` does **not** own your whole database. It creates exactly the
+models in your `defineSchema(...)` — the synced, collaborative tables — plus the
+adapter's bookkeeping tables (`ablo_outbox`, `ablo_idempotency`). Nothing else.
+
+Your auth, billing, and any other non-synced tables stay in **your own ORM
+schema** (Drizzle's `schema.ts`, Prisma's `schema.prisma`) and are provisioned by
+**your own migrations** (`drizzle-kit push` / `prisma migrate`). The Ablo schema
+is not a replacement for `schema.prisma`, and `ablo migrate` won't touch, drop,
+or adopt the tables it doesn't manage. One database, two schemas, side by side —
+each owned by its own migration tool.
+
 ## Zod → Postgres type mapping
 
 The one type map, shared by both paths (there is no second mapping):

package/docs/data-sources.md

@@ -10,10 +10,16 @@ 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.
+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 (plus the small `ablo_outbox` / `ablo_idempotency` bookkeeping
+tables its adapter needs); you keep owning everything else. `ablo check` reflects
+this — it reports your other tables as "ignored / owned by you," which is exactly
+right.
 
 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
@@ -66,8 +72,8 @@ Multiplayer behavior is the same in both modes. Writes made through
 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
 
@@ -100,59 +106,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,37 +208,18 @@ 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,
-
-  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.
+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.
 
 ## Production Checklist
 
@@ -246,14 +227,18 @@ Before using a customer-owned database 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.
 
+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.
+
 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.)

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