@abloatai/ablo 0.9.2 → 0.9.4

package/dist/transactions/TransactionQueue.js

@@ -13,6 +13,7 @@ import { getActiveRegistry } from '../ModelRegistry.js';
 import { MutationOperationType } from '../types/index.js';
 import { handleMutationError } from './mutation-error-handler.js';
 import { AbloError, AbloConnectionError, errorCodeSpec } from '../errors.js';
+import { SyncPosition } from '../sync/syncPosition.js';
 /**
  * Framework-internal keys added by `Model.toJSON()` that must never
  * reach the wire. The server treats each top-level key as a target
@@ -117,13 +118,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;
 }
@@ -305,10 +324,21 @@ export class TransactionQueue extends EventEmitter {
     // cleared on `'connected'`. The reconnect-retry behavior of the queue
     // is preserved for brief blips; this only catches persistent disconnects.
     commitOfflineGraceTimer = null;
-    // Track the highest syncId received from WebSocket deltas
-    // Used to immediately confirm transactions when HTTP response arrives AFTER the delta
-    // (fixes race condition where WebSocket delta arrives before HTTP response)
-    lastSeenSyncId = 0;
+    /**
+     * THE client's place in the global delta order — the SHARED instance
+     * (injected by SyncClient; standalone construction gets its own). The
+     * queue advances `acked` on commit responses; the store advances
+     * `applied`/`persisted`; snapshots/claims read `readFloor`. Contract +
+     * rationale live in `sync/syncPosition.ts`.
+     */
+    position;
+    /** Applied-cursor alias, kept so the many internal read sites stay legible. */
+    get lastSeenSyncId() {
+        return this.position.applied;
+    }
+    noteAck(lastSyncId) {
+        this.position.noteAck(lastSyncId);
+    }
     // Delta confirmation retry config (Replicache-style exponential backoff)
     // Max retries before requesting full reconciliation
     static DELTA_MAX_RETRIES = 5;
@@ -328,6 +358,7 @@ export class TransactionQueue extends EventEmitter {
     confirmationResolvers = new Map();
     constructor(config) {
         super();
+        this.position = config?.position ?? new SyncPosition();
         if (config) {
             this.config = { ...this.config, ...config };
         }
@@ -552,7 +583,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 +961,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,
@@ -954,6 +985,7 @@ export class TransactionQueue extends EventEmitter {
                         // the coalescing test's tight bound on batch count.
                         const result = await this.mutationExecutor.commit(operations);
                         const lastSyncId = result?.lastSyncId ?? 0;
+                        this.noteAck(lastSyncId);
                         // Detect server bug: lastSyncId 0 means mutation succeeded but no sync delta was emitted
                         if (lastSyncId === 0) {
                             getContext().observability.captureCommitZeroSyncId({
@@ -981,34 +1013,44 @@ export class TransactionQueue extends EventEmitter {
                                 });
                                 continue;
                             }
-                            // FIX: Check if delta already arrived before HTTP response (race condition)
-                            // WebSocket can be faster than HTTP, so the delta might already be here
-                            // Guard: only do immediate confirm if lastSyncId > 0 (valid server response)
-                            if (lastSyncId > 0 && this.lastSeenSyncId >= lastSyncId) {
-                                // Delta already arrived! Confirm immediately without timeout
+                            // ACK-BASED CONFIRMATION. A successful commit response with a
+                            // real watermark means the server durably applied the write —
+                            // that IS the confirmation (the documented `wait: 'confirmed'`
+                            // contract, and how Replicache/Zero treat the push response's
+                            // lastMutationID). The delta echo is NOT an acknowledgement
+                            // channel: it's replication for OTHER clients, and this
+                            // client's own echo is suppressed by the OptimisticEchoTracker
+                            // anyway. Gating confirmation on the echo coupled "did my
+                            // write land" to subscription-stream health — a bare-Node
+                            // client with no live delta stream hung forever in
+                            // `awaiting_delta` on a write the server had already applied.
+                            if (lastSyncId > 0) {
                                 this.store.updateStatus(tx.id, 'completed');
                                 this.emit('transaction:completed', tx);
                                 this.emit(`transaction:completed:${tx.id}`, tx);
                                 this.optimisticUpdates.delete(tx.id);
-                                getContext().logger.debug('tx:confirm_immediate', {
+                                getContext().logger.debug('tx:confirm_ack', {
                                     txId: tx.id.slice(0, 8),
                                     model: tx.modelName,
-                                    neededSyncId: lastSyncId,
+                                    serverSyncId: lastSyncId,
                                     lastSeenSyncId: this.lastSeenSyncId,
-                                    reason: 'delta_arrived_before_http',
                                 });
                             }
                             else {
-                                // Delta hasn't arrived yet, wait for it
+                                // lastSyncId === 0 on a non-DELETE: the server accepted the
+                                // commit but emitted no delta — a server-side anomaly
+                                // (already captured via captureCommitZeroSyncId above). Keep
+                                // the delta-wait + reconciliation timeout for THIS case
+                                // only, so the anomaly surfaces instead of silently
+                                // confirming a write with no watermark.
                                 this.store.updateStatus(tx.id, 'awaiting_delta');
                                 getContext().logger.debug('tx:awaiting_delta', {
                                     txId: tx.id.slice(0, 8),
                                     model: tx.modelName,
                                     neededSyncId: lastSyncId,
                                     lastSeenSyncId: this.lastSeenSyncId,
-                                    gap: lastSyncId - this.lastSeenSyncId,
+                                    reason: 'zero_sync_id_anomaly',
                                 });
-                                // Schedule timeout-based rollback for unconfirmed transactions
                                 this.scheduleDeltaConfirmationTimeout(tx, this.config.deltaConfirmationTimeout);
                             }
                         }
@@ -1135,16 +1177,9 @@ export class TransactionQueue extends EventEmitter {
      * @param syncId - The sync ID of the received delta
      */
     onDeltaReceived(syncId) {
-        const prevLastSeen = this.lastSeenSyncId;
-        // Track highest syncId seen (fixes race: delta arrives before HTTP response)
-        if (syncId > this.lastSeenSyncId) {
-            this.lastSeenSyncId = syncId;
-            getContext().logger.debug('tx:highwater_update', {
-                prev: prevLastSeen,
-                new: syncId,
-                delta: syncId - prevLastSeen,
-            });
-        }
+        // Cursor advancing happens where the delta is APPLIED (the store calls
+        // position.advanceApplied / advancePersisted); this hook only resolves
+        // confirmation thresholds against the incoming id.
         const awaitingTxs = this.store.getByStatus('awaiting_delta');
         const executingTxs = this.store.getByStatus('executing');
         // Debug: Show state when delta arrives
@@ -1358,6 +1393,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();
     }
     /**
@@ -1385,6 +1426,7 @@ export class TransactionQueue extends EventEmitter {
                         causedByTaskId: tx.causedByTaskId ?? undefined,
                     });
                     tx.lastSyncId = result?.lastSyncId ?? 0;
+                    this.noteAck(tx.lastSyncId);
                     tx.status = 'completed';
                     this.commitLane.shift();
                     this.emit('transaction:completed', tx);
@@ -1674,7 +1716,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/api-keys.md

@@ -23,7 +23,7 @@ Use API keys from trusted (server-side) runtimes:
 
 Never ship a secret API key to a browser bundle.
 
-## Test mode and sandboxes
+## Sandboxes and production
 
 Test and live keys are the same shape; the prefix names the environment:
 
@@ -31,11 +31,11 @@ Test and live keys are the same shape; the prefix names the environment:
   to that sandbox and are invisible to live keys (and to other sandboxes).
 - `sk_live_…` — a key against your live data.
 
-Every org has a default **Test mode** sandbox, plus any number of additional
+Every org has a default sandbox, plus any number of additional
 sandboxes you create. **Data is isolated per sandbox; the schema is shared
 across the whole org.** A schema you push from a test key defines the same
 models your live keys see — only the rows differ. This mirrors how Stripe
-separates test and live data while keeping the API shape identical.
+separates sandbox and production data while keeping the API shape identical.
 
 ## Scopes
 
@@ -51,7 +51,7 @@ restricted to exactly those grants:
 - `sandbox:<id>` — identifies which sandbox the key belongs to. (The key's data
   isolation comes from that sandbox binding, not from this scope string.)
 
-A key minted from the default **Test mode** sandbox carries `schema:push`, so
+A key minted from the default sandbox carries `schema:push`, so
 `ablo dev` works out of the box. Keys from other sandboxes are **data-only** by
 default — enable "schema authoring" when minting if you want that key to push
 schema too. Hand data-only keys to embedded apps and CI agents; reserve

package/docs/cli.md

@@ -32,7 +32,7 @@ mirrors `stripe login`.
 | `ablo login`             | Authorize in the browser; provisions + stores a test and a live key.       |
 | `ablo logout`            | Remove the stored keys.                                                    |
 | `ablo status`            | Show the active org, mode, both keys (prefix + expiry), and server health. |
-| `ablo mode [test\|live]` | Switch the active mode. With no argument, prompts.                         |
+| `ablo mode [sandbox\|production]` | Switch the active environment. With no argument, prompts.                         |
 
 Keys are stored in `~/.config/ablo/config.json` (mode `0600`). In **CI**, don't
 log in — set `ABLO_API_KEY`, which always overrides the stored key.
@@ -41,11 +41,11 @@ log in — set `ABLO_API_KEY`, which always overrides the stored key.
 
 Like Stripe, every account has a **test** mode and a **live** mode, and a key
 belongs to one of them. Test keys are bound to an isolated sandbox: their reads
-and writes never touch live data. Switch with `ablo mode`; `ablo dev` is always
-test mode by design.
+and writes never touch production data. Switch with `ablo mode`; `ablo dev` is always
+the sandbox by design.
 
 The schema, however, is **shared** across the org — pushing a schema (from
-either mode) defines the same models test and live see; only the rows differ.
+either environment) defines the same models sandbox and production see; only the rows differ.
 
 ## Commands
 
@@ -53,9 +53,9 @@ either mode) defines the same models test and live see; only the rows differ.
 | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
 | `ablo init`                        | Scaffold `ablo/` (`schema.ts`, client, optional Data Source / agent / component), write `.env`, install the SDK. Offers to log in at the end. | —                                                                                                      |
 | `ablo login` / `logout` / `status` | Authentication & status (above).                                                                                                              | —                                                                                                      |
-| `ablo mode [test\|live]`           | Switch active mode.                                                                                                                           | —                                                                                                      |
+| `ablo mode [sandbox\|production]`   | Switch active environment.                                                                                                                           | —                                                                                                      |
 | `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 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 sandbox\|production` |
 | `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** — 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`                                     |

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

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