@abloatai/ablo 0.9.2 → 0.9.3

package/dist/source/adapters/kysely.js

@@ -0,0 +1,210 @@
+/**
+ * Kysely Data Source adapter. Same adapter interface + conformance shape as
+ * `prismaDataSource` / `drizzleDataSource`, built against Kysely's REAL
+ * query-builder API:
+ *   - `db.transaction().execute(async (trx) => …)` — interactive transaction.
+ *   - `insertInto/updateTable/deleteFrom/selectFrom` + `returningAll()` —
+ *     the fluent builder; table/column names are plain strings, so no raw
+ *     SQL tag is needed and this module imports NOTHING from `kysely`
+ *     (structural `KyselyLike`, mirroring the Prisma adapter's zero-dep
+ *     `PrismaLike`).
+ *
+ * SCHEMA-DRIVEN COLUMNS. Kysely is SQL-near: it passes the column names you
+ * give it through verbatim (no Prisma-style `@map`). Like the Drizzle
+ * adapter, every table + column name is derived from the SAME rule the
+ * provisioner uses (`generateProvisionPlan`):
+ *   table  = `model.tableName ?? key`
+ *   column = `fieldMeta.column ?? camelToSnake(field)`  (+ the tenancy column)
+ * so `ablo migrate` (which emits `operator_id`) and this adapter COMPOSE.
+ * The adapter is the translation boundary: rows in/out are field-keyed (the
+ * SDK shape); the physical columns it reads/writes are snake_case.
+ *
+ * JSONB note: the outbox `data` / idempotency `response` values are passed
+ * as JSON strings — Postgres infers the parameter type from the target
+ * `jsonb` column, so the coercion is server-side and driver-agnostic (no
+ * `::jsonb` cast available without raw SQL).
+ */
+import { AbloValidationError } from '../../errors.js';
+import { outboxEventSchema } from '../contract.js';
+import { adapterTableMigrations } from '../migrations.js';
+import { toSchemaJSON } from '../../schema/serialize.js';
+import { camelToSnake, snakeToCamel } from '../../schema/ddl.js';
+import { tenancyColumn } from '../../schema/tenancy.js';
+function rowId(op) {
+    const id = op.id ?? op.input?.id;
+    if (typeof id !== 'string' || id.length === 0) {
+        throw new AbloValidationError(`operation on "${op.model}" requires an id`, {
+            code: 'source_operation_id_required',
+        });
+    }
+    return id;
+}
+function buildColumnMaps(schema) {
+    const json = toSchemaJSON(schema);
+    const out = new Map();
+    for (const [key, model] of Object.entries(json.models)) {
+        const fieldToColumn = new Map();
+        const columnToField = new Map();
+        const register = (field, column) => {
+            if (column === camelToSnake(field))
+                return;
+            fieldToColumn.set(field, column);
+            columnToField.set(column, field);
+        };
+        for (const [field, meta] of Object.entries(model.fields)) {
+            if (meta.column)
+                register(field, meta.column);
+        }
+        const orgColumn = tenancyColumn(model.tenancy);
+        if (orgColumn)
+            register('organizationId', orgColumn);
+        out.set(key, { table: model.tableName ?? key, fieldToColumn, columnToField });
+    }
+    return out;
+}
+export function kyselyDataSource(db, schema) {
+    const maps = buildColumnMaps(schema);
+    const modelColumns = (model) => {
+        const mc = maps.get(model);
+        if (!mc) {
+            throw new AbloValidationError(`kyselyDataSource: no model "${model}" in schema`, {
+                code: 'source_adapter_misconfigured',
+            });
+        }
+        return mc;
+    };
+    const columnFor = (mc, field) => mc.fieldToColumn.get(field) ?? camelToSnake(field);
+    const fieldFor = (mc, column) => mc.columnToField.get(column) ?? snakeToCamel(column);
+    /** Field-keyed (SDK shape) → column-keyed (physical), for INSERT/UPDATE. */
+    const toColumns = (mc, row) => {
+        const out = {};
+        for (const k of Object.keys(row))
+            out[columnFor(mc, k)] = row[k];
+        return out;
+    };
+    /** Column-keyed (RETURNING * / SELECT *) → field-keyed (SDK shape). */
+    const toFields = (mc, row) => {
+        const out = {};
+        for (const k of Object.keys(row))
+            out[fieldFor(mc, k)] = row[k];
+        return out;
+    };
+    const applyOperation = async (trx, op) => {
+        const mc = modelColumns(op.model);
+        const id = rowId(op);
+        const input = op.input ?? {};
+        if (op.type === 'DELETE') {
+            const deleted = await trx
+                .deleteFrom(mc.table)
+                .where('id', '=', id)
+                .returningAll()
+                .execute();
+            return deleted[0] ? toFields(mc, deleted[0]) : { id };
+        }
+        if (op.type === 'CREATE') {
+            const inserted = await trx
+                .insertInto(mc.table)
+                .values(toColumns(mc, { id, ...input }))
+                .returningAll()
+                .execute();
+            return inserted[0] ? toFields(mc, inserted[0]) : { id, ...input };
+        }
+        // UPDATE / ARCHIVE / UNARCHIVE — the lifecycle field is `archivedAt`
+        // (camelCase) and goes through `toColumns` like any other, so it lands in
+        // `archived_at` — the same column the provisioner emits.
+        const patch = toColumns(mc, {
+            ...input,
+            ...(op.type === 'ARCHIVE' ? { archivedAt: new Date() } : {}),
+            ...(op.type === 'UNARCHIVE' ? { archivedAt: null } : {}),
+        });
+        const updated = await trx
+            .updateTable(mc.table)
+            .set(patch)
+            .where('id', '=', id)
+            .returningAll()
+            .execute();
+        return updated[0] ? toFields(mc, updated[0]) : { id, ...input };
+    };
+    return {
+        capabilities: { transactions: true, propose: false, schemaIntrospection: true },
+        migrations() {
+            return adapterTableMigrations();
+        },
+        async read(req) {
+            const mc = modelColumns(req.model);
+            if (req.kind === 'load') {
+                const rows = await db
+                    .selectFrom(mc.table)
+                    .selectAll()
+                    .where('id', '=', req.id)
+                    .limit(1)
+                    .execute();
+                return rows.map((r) => toFields(mc, r));
+            }
+            const limit = req.query?.limit ?? 1000;
+            const rows = await db.selectFrom(mc.table).selectAll().limit(limit).execute();
+            return rows.map((r) => toFields(mc, r));
+        },
+        async commit(change) {
+            return db.transaction().execute(async (trx) => {
+                const cached = await trx
+                    .selectFrom('ablo_idempotency')
+                    .selectAll()
+                    .where('client_tx_id', '=', change.clientTxId)
+                    .limit(1)
+                    .execute();
+                if (cached.length > 0) {
+                    const response = cached[0].response;
+                    return {
+                        rows: (typeof response === 'string' ? JSON.parse(response) : response),
+                    };
+                }
+                const rows = [];
+                for (const [index, op] of change.operations.entries()) {
+                    const row = await applyOperation(trx, op);
+                    rows.push(row);
+                    const entityId = String(row.id ?? rowId(op));
+                    await trx
+                        .insertInto('ablo_outbox')
+                        .values({
+                        id: `${change.clientTxId}:${index}`,
+                        model: op.model,
+                        entity_id: entityId,
+                        type: op.type,
+                        data: op.type === 'DELETE' ? null : JSON.stringify(row),
+                        client_tx_id: change.clientTxId,
+                        occurred_at: Date.now(),
+                    })
+                        .execute();
+                }
+                await trx
+                    .insertInto('ablo_idempotency')
+                    .values({ client_tx_id: change.clientTxId, response: JSON.stringify(rows) })
+                    .execute();
+                return { rows };
+            });
+        },
+        async events(cursor, limit) {
+            const after = cursor ?? '0';
+            const rows = await db
+                .selectFrom('ablo_outbox')
+                .selectAll()
+                .where('cursor', '>', after)
+                .orderBy('cursor', 'asc')
+                .limit(limit)
+                .execute();
+            const events = rows.map((r) => outboxEventSchema.parse({
+                id: r.id,
+                model: r.model,
+                entityId: r.entity_id,
+                type: r.type,
+                data: typeof r.data === 'string' ? JSON.parse(r.data) : r.data ?? null,
+                organizationId: r.organization_id ?? null,
+                clientTxId: r.client_tx_id ?? null,
+                occurredAt: r.occurred_at != null ? Number(r.occurred_at) : null,
+                cursor: String(r.cursor),
+            }));
+            return { events, nextCursor: events.length > 0 ? events[events.length - 1].cursor : null };
+        },
+    };
+}

package/dist/source/adapters/memory.js

@@ -8,10 +8,11 @@
  * It models the real semantics minimally but faithfully: one canonical row store
  * per model, an idempotency ledger keyed by `clientTxId`, and a monotonic outbox.
  */
+import { AbloValidationError } from '../../errors.js';
 function rowId(op) {
     const id = op.id ?? op.input?.id;
     if (typeof id !== 'string' || id.length === 0) {
-        throw new Error(`operation on "${op.model}" requires an id`);
+        throw new AbloValidationError(`operation on "${op.model}" requires an id`, { code: 'source_operation_id_required' });
     }
     return id;
 }

package/dist/source/adapters/prisma.js

@@ -12,6 +12,7 @@
  * (`PrismaLike`), so this compiles in the SDK package and is unit-testable with
  * a fake, while a real `PrismaClient` satisfies it at the call site.
  */
+import { AbloValidationError } from '../../errors.js';
 import { outboxEventSchema } from '../contract.js';
 import { adapterTableMigrations } from '../migrations.js';
 const lowerFirst = (s) => (s ? s[0].toLowerCase() + s.slice(1) : s);
@@ -32,7 +33,7 @@ const lowerFirst = (s) => (s ? s[0].toLowerCase() + s.slice(1) : s);
 function delegateFor(client, name) {
     const delegate = client[name];
     if (!delegate || typeof delegate.findMany !== 'function') {
-        throw new Error(`prismaDataSource: no Prisma delegate "${name}" on the client`);
+        throw new AbloValidationError(`prismaDataSource: no Prisma delegate "${name}" on the client`, { code: 'source_adapter_misconfigured' });
     }
     return delegate;
 }
@@ -97,7 +98,7 @@ function findManyArgs(query) {
 function rowId(op) {
     const id = op.id ?? op.input?.id;
     if (typeof id !== 'string' || id.length === 0) {
-        throw new Error(`operation on "${op.model}" requires an id`);
+        throw new AbloValidationError(`operation on "${op.model}" requires an id`, { code: 'source_operation_id_required' });
     }
     return id;
 }

package/dist/source/index.js

@@ -1,3 +1,4 @@
+import { AbloValidationError } from '../errors.js';
 import { changeSetSchema } from './contract.js';
 /**
  * Build the source-event marker customers should write to their outbox table in
@@ -10,7 +11,7 @@ import { changeSetSchema } from './contract.js';
 export function sourceEventForOperation(options) {
     const entityId = options.entityId ?? options.operation.id;
     if (typeof entityId !== 'string' || entityId.length === 0) {
-        throw new Error('sourceEventForOperation requires operation.id or an explicit entityId');
+        throw new AbloValidationError('sourceEventForOperation requires operation.id or an explicit entityId', { code: 'source_event_invalid' });
     }
     const occurredAt = normalizeEventOccurredAt(options.occurredAt);
     return {

package/dist/transactions/TransactionQueue.d.ts

@@ -10,7 +10,7 @@
 import { EventEmitter } from 'events';
 import type { Database } from '../Database.js';
 import { Model } from '../Model.js';
-import type { MutationOptions } from '../interfaces/index.js';
+import type { WriteOptions } from '../interfaces/index.js';
 export interface UserContext {
     userId: string;
     organizationId: string;
@@ -19,7 +19,6 @@ export interface UserContext {
 }
 /** Wire-format mutation payload (post-projection). */
 type MutationInput = Record<string, unknown>;
-type TransactionWriteOptions = Pick<MutationOptions, 'readAt' | 'onStale'>;
 export interface Transaction {
     id: string;
     type: 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
@@ -34,7 +33,7 @@ export interface Transaction {
     attempts: number;
     priority: 'normal' | 'high';
     priorityScore: number;
-    writeOptions?: TransactionWriteOptions;
+    writeOptions?: WriteOptions;
     batchId?: string;
     /** LINEAR PATTERN: syncId threshold - transaction confirms when delta.id >= this value */
     syncIdNeededForCompletion?: number;
@@ -237,16 +236,16 @@ export declare class TransactionQueue extends EventEmitter {
     /**
      * Create operation with optimistic update
      */
-    create(model: Model, context: UserContext, writeOptions?: TransactionWriteOptions): Promise<Transaction>;
+    create(model: Model, context: UserContext, writeOptions?: WriteOptions): Promise<Transaction>;
     /**
      * Update operation with conflict detection
      * @param precomputedChanges - Optional pre-captured changes (avoids re-reading from model)
      */
-    update(model: Model, context: UserContext, precomputedChanges?: Record<string, unknown>, writeOptions?: TransactionWriteOptions): Promise<Transaction>;
+    update(model: Model, context: UserContext, precomputedChanges?: Record<string, unknown>, writeOptions?: WriteOptions): Promise<Transaction>;
     /**
      * Delete operation with cascade handling
      */
-    delete(model: Model, context: UserContext, writeOptions?: TransactionWriteOptions): Promise<Transaction>;
+    delete(model: Model, context: UserContext, writeOptions?: WriteOptions): Promise<Transaction>;
     /**
      * Upload attachment — delegates to attachment-uploader.ts
      */
@@ -269,7 +268,7 @@ export declare class TransactionQueue extends EventEmitter {
     /**
      * Archive operation
      */
-    archive(model: Model, context: UserContext, writeOptions?: TransactionWriteOptions): Promise<Transaction>;
+    archive(model: Model, context: UserContext, writeOptions?: WriteOptions): Promise<Transaction>;
     /**
      * Unarchive operation
      */

package/dist/transactions/TransactionQueue.js

@@ -117,13 +117,31 @@ function hasStaleWriteOptions(options) {
     return (options?.readAt !== undefined ||
         options?.onStale !== undefined);
 }
-function applyStaleWriteOptions(op, transaction) {
+/**
+ * Project a transaction's `writeOptions` onto the wire operation. Stale
+ * guards (`readAt`/`onStale`) ride at the op root; `idempotencyKey`/`label`
+ * ride in the op's `options` slot (`MutationOperation.options` — the
+ * mutation_log cache key + audit tag). This is the single place the
+ * caller-supplied write vocabulary crosses onto the wire.
+ */
+function applyWriteOptions(op, transaction) {
     const operation = op;
-    if (transaction.writeOptions?.readAt !== undefined) {
-        operation.readAt = transaction.writeOptions.readAt;
-    }
-    if (transaction.writeOptions?.onStale !== undefined) {
-        operation.onStale = transaction.writeOptions.onStale;
+    const writeOptions = transaction.writeOptions;
+    if (!writeOptions)
+        return operation;
+    if (writeOptions.readAt !== undefined) {
+        operation.readAt = writeOptions.readAt;
+    }
+    if (writeOptions.onStale !== undefined) {
+        operation.onStale = writeOptions.onStale;
+    }
+    if (writeOptions.idempotencyKey != null || writeOptions.label !== undefined) {
+        operation.options = {
+            ...(writeOptions.idempotencyKey != null
+                ? { idempotencyKey: writeOptions.idempotencyKey }
+                : {}),
+            ...(writeOptions.label !== undefined ? { label: writeOptions.label } : {}),
+        };
     }
     return operation;
 }
@@ -552,7 +570,7 @@ export class TransactionQueue extends EventEmitter {
         // Build operations list
         const operations = pending.map((tx) => {
             this.ensureDerivedFields(tx);
-            return applyStaleWriteOptions({
+            return applyWriteOptions({
                 type: TX_TYPE_TO_MUTATION_OP[tx.type],
                 model: tx.modelKey,
                 id: tx.modelId,
@@ -930,7 +948,7 @@ export class TransactionQueue extends EventEmitter {
                     // matches it via `OptimisticEchoTracker.consumeEcho` to suppress
                     // double-applying optimistic mutations. Distinct from the
                     // batch-level idempotency key in mutation_log.
-                    const op = applyStaleWriteOptions({
+                    const op = applyWriteOptions({
                         type: TX_TYPE_TO_MUTATION_OP[tx.type],
                         model: tx.modelKey,
                         id: tx.modelId,
@@ -1358,6 +1376,12 @@ export class TransactionQueue extends EventEmitter {
         };
         this.commitStore.set(clientTxId, tx);
         this.commitLane.push(tx);
+        // Surface the envelope on its OWN event so the undo stream can record
+        // commit-lane writes too (`SyncClient.onLocalTransaction` enriches each
+        // operation with pool-captured previous state). Deliberately NOT
+        // `transaction:created` — that event also feeds the optimistic-echo
+        // tracker, and commit-lane ops have no optimistic pool apply to echo.
+        this.emit('commit:created', { clientTxId, operations: tx.operations });
         void this.processCommitLane();
     }
     /**
@@ -1674,7 +1698,7 @@ export class TransactionQueue extends EventEmitter {
         const input = (type === 'create' || type === 'update') ? data : undefined;
         try {
             await this.mutationExecutor.commit([
-                applyStaleWriteOptions({ type: mutationType, model, id: modelId, input }, transaction),
+                applyWriteOptions({ type: mutationType, model, id: modelId, input }, transaction),
             ]);
         }
         catch (error) {

package/dist/utils/duration.js

@@ -16,6 +16,7 @@
  * without breaking numeric callers — the wrapper below branches on
  * the input type.
  */
+import { AbloValidationError } from '../errors.js';
 const PATTERN = /^(\d+(?:\.\d+)?)(ms|s|m|h)$/;
 const UNIT_MS = {
     ms: 1,
@@ -34,8 +35,8 @@ export function toMs(input) {
         return input * 1_000;
     const match = PATTERN.exec(input);
     if (!match) {
-        throw new Error(`Invalid duration "${input}" — expected number (seconds) or ` +
-            `a string like "500ms" | "30s" | "3m" | "24h".`);
+        throw new AbloValidationError(`Invalid duration "${input}" — expected number (seconds) or ` +
+            `a string like "500ms" | "30s" | "3m" | "24h".`, { code: 'duration_invalid' });
     }
     const value = Number(match[1]);
     const unit = match[2];

package/docs/client-behavior.md

@@ -30,7 +30,7 @@ Common options:
 | `schema` | Required for typed model clients. |
 | `apiKey` | Bearer credential for trusted server runtimes. Defaults to `ABLO_API_KEY` when available. |
 | `baseURL` | Override the hosted sync endpoint for staging or private deployments. |
-| `persistence` | `volatile` by default. Use `indexeddb` for a durable browser cache that survives reloads. |
+| `persistence` | `memory` by default. Use `indexeddb` for a durable browser cache that survives reloads. |
 | `fetch` | Custom fetch implementation for tests or non-standard runtimes. |
 | `defaultHeaders` | Extra headers attached to every HTTP request. |
 | `defaultQuery` | Extra query parameters attached to every HTTP request. |

package/docs/data-sources.md

@@ -1,14 +1,14 @@
 # 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.
+**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:
 
-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.
+| | 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
@@ -16,17 +16,18 @@ 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.
+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.
 
-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.
+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.
 
-Use the SDK with an API key:
+## Connection String (default)
+
+The canonical client carries all three values:
 
 ```ts
 import Ablo from '@abloatai/ablo';
@@ -35,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.
+
+`databaseUrl` is server-only: the SDK throws if it sees one in a browser-like
+environment, and `dangerouslyAllowBrowser` does not override that.
+
+## Signed Endpoint
 
-| 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. |
+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:
 
-The SDK call is the same in both modes:
+```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' } });
@@ -65,9 +87,7 @@ 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
@@ -75,10 +95,10 @@ automatically. To keep everyone's screen up to date, your app reports those
 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
@@ -221,9 +241,9 @@ 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
+## Production Checklist (signed endpoint)
 
-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.
@@ -239,9 +259,8 @@ 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.)
+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/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
 

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