@abloatai/ablo 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.25.0
+
+### Minor Changes
+
+- ca30064: Logical replication is now the documented default storage path, with self-service data-source registration from the CLI.
+  - **`ablo connect --register`** — registers your database as an Ablo data source over logical replication in one step: it runs the same pre-flight replication probe `ablo connect` uses (server reachable, `REPLICATION` privilege, `wal_level=logical`, publication/slot creatable), and on success `POST`s the connection to the engine's `/v1/datasources`. The `ek_`-authed call scopes the source to your org automatically; the password is stored decomposed as a secret, never echoed back. This is the "registration is the enable" path — there is no separate tier or flag to pick.
+  - **`ablo init` leads with logical replication** — the default storage mode is now `replication` (was `endpoint`); the generated env + next-steps point at `ablo connect` / `ablo connect --register`. The signed-endpoint and direct modes remain as the explicit fallback / legacy options.
+  - **`ablo status`** — a data-plane diagnostic that probes whether your registered source is reachable and replicating (failure-only reporting, so it never falsely reports healthy).
+  - **`ablo push`** — minor guard/UX refinements (deploy-target clarity).
+  - **Docs (README, `docs/data-sources.md`, `llms.txt`)** rewritten to the one-path model: Ablo consumes your database's logical-replication stream and your application owns the write path. The security wording is precise — a logical-replication connection requires the `REPLICATION` privilege (it is **not** a read-only SQL account), so reviews are not misled by a "read-only" claim.
+
+  No breaking changes to the SDK runtime API. The server-side WAL read cutover these CLI changes support ships by deploying the engine, not this package.
+
 ## 0.24.0
 
 ### Minor Changes

package/README.md

@@ -55,11 +55,13 @@ claims are visible while the work is still in progress.
 [Version History & Migration Guide](./docs/migration.md)
 
 It works with the auth and database you already have. **In production, your
-database is the system of record.** Ablo is the transaction layer on top of it:
-realtime data is scoped to *sync groups* from your own identity, and every
-committed row lives in your Postgres. (Trying Ablo with no database yet? The
-hosted **sandbox** can host rows in Ablo's test plane — apiKey only, like
-Stripe test mode — so you can explore before pointing it at your Postgres.)
+database is the system of record.** Ablo is the sync + coordination layer on top
+of it: it consumes your Postgres' logical-replication stream, scopes realtime
+data to *sync groups* from your own identity, and your application keeps owning
+the write path — every row lives in your Postgres. (Trying Ablo with no database
+yet? A **sandbox** `sk_test` key holds throwaway **test data** — like Stripe test
+mode — so you can explore before pointing it at your Postgres. Test-mode only; in
+production every row lives in your database.)
 
 **Built for** collaborative editors, AI agent workflows, and internal tools —
 anywhere people and agents change shared state and everyone has to see it live.
@@ -92,11 +94,11 @@ what's configured at any time.
 
 **Keys & runtime.** Ablo needs Node 24+ and TypeScript 5+. Keys come in two of
 *your* environments — `sk_test_` and `sk_live_`, like Stripe — and `ablo login`
-mints both. Keep the key and the database URL in trusted server runtimes only.
-In the browser, `<AbloProvider>` authenticates with the signed-in user's
-session — never the raw key, never the database URL. Prefer the connection
-string never leaving your infrastructure? Expose a signed
-[Data Source endpoint](./docs/data-sources.md) instead and omit `databaseUrl`.
+mints both. Keep the key in trusted server runtimes only. In the browser,
+`<AbloProvider>` authenticates with the signed-in user's session — never the raw
+key. Your database is connected once, out of band, via `npx ablo connect`
+(logical replication); if it can't grant a replication role, expose a signed
+[Data Source endpoint](./docs/data-sources.md) instead.
 
 For production (React, an existing backend, Data Source, agents), the
 [Integration Guide](./docs/integration-guide.md) is the deeper map.
@@ -175,8 +177,9 @@ const schema = defineSchema({
 const ablo = Ablo({
   schema,
   apiKey: process.env.ABLO_API_KEY, // written to .env.local by `npx ablo push`
-  databaseUrl: process.env.DATABASE_URL, // your Postgres, passed explicitly — rows live here
 });
+// Your Postgres is connected once via `npx ablo connect` (logical replication) —
+// not passed here. Ablo tails its WAL; your rows never leave your database.
 
 await ablo.ready();
 
@@ -403,10 +406,12 @@ each other's changes in real time — that's the default, not a feature you turn
 - `useAblo(...)` gives React clients the live row, kept current automatically.
 - `ablo.<model>.claim({ id })` / `claim.state({ id })` / `claim.queue({ id })` let humans and agents coordinate (and observe) active work on a row — and the line waiting behind it — before a write lands.
 
-Always write through Ablo — either the SDK model methods
-(`ablo.<model>.create/update/delete`) or the HTTP write endpoint below. If you
-write straight to your own database instead, those changes won't reach connected
-clients.
+Your application owns the write path: writes that land in your database — through
+your own backend, your existing API, any path — are tailed off the WAL and fanned
+out to connected clients automatically (the Electric model). The SDK model
+methods (`ablo.<model>.create/update/delete`) and the HTTP write endpoint are the
+*JavaScript/agent* ergonomic surface — they participate in claims and confirmation
+— but they are not a requirement for your normal writes to show up.
 
 ## HTTP Writes
 
@@ -429,35 +434,39 @@ curl https://api.abloatai.com/v1/commits \
 
 ## Your Database
 
-In production, every schema model is backed by **your own database** — Ablo is
-the transaction layer on top of it. Two ways to connect it:
+In production, every schema model is backed by **your own database** — Ablo
+**consumes** it, never owns it. The model is Electric's (and PowerSync's, and
+Zero's): Ablo consumes your Postgres' logical-replication stream and fans the
+changes out; **your application continues to own the write path.** Two ways Ablo
+connects:
 
-| | How Ablo reaches your Postgres | Use when |
+| | How Ablo connects to your Postgres | Use when |
 | --- | --- | --- |
-| **Connection string** (primary) | `databaseUrl` at init — passed explicitly, never auto-read from the environment. Ablo registers the connection once (sent over TLS, stored sealed, never echoed back) and commits each write directly — through a non-superuser role, behind row-level security. | You can hand over a scoped connection string. |
-| **Signed endpoint** | Your app exposes one route built from an ORM adapter (`prismaDataSource` / `drizzleDataSource`); Ablo sends signed commit requests and your app writes its own database. | Database credentials must never leave your infrastructure. |
+| **Logical replication** (primary) | `npx ablo connect` prints the setup SQL (`wal_level=logical`, a publication, a `REPLICATION` role); `npx ablo connect --register` tells Ablo to replicate it. Ablo tails the WAL — it never runs DDL on, writes to, owns, or migrates your database. | Your database can grant a `REPLICATION` role (most can). |
+| **Signed endpoint** (fallback) | Your app exposes one route built from an ORM adapter (`prismaDataSource` / `drizzleDataSource`); Ablo sends signed requests and your app touches its own database. Needs no database configuration. | Your database **can't** grant a replication role (a locked-down managed DB). |
 
-(No database yet? The hosted **sandbox** can host rows in Ablo's test plane —
-omit `databaseUrl` and pass an `apiKey` only, like Stripe test mode — so you can
-try Ablo before connecting your Postgres.)
+(No database yet? A **sandbox** `sk_test` key lets you try Ablo's full API and
+coordination with throwaway **test data** — like Stripe test mode — before you
+connect your own Postgres. Test-mode only: in production your rows always live in
+your database and Ablo holds just the transaction log, never your data.)
 
-Same product, same truth either way: in production your database is the system of
-record. See
-[Connect Your Database](./docs/data-sources.md) for both shapes.
+Your database is the system of record. The old `databaseUrl` dial-in (Ablo
+holding a read/write connection) is **deprecated and being removed** — connect
+via logical replication instead. See
+[Connect Your Database](./docs/data-sources.md).
 
 ## Configuration
 
-`Ablo({ ... })` takes your schema, your key, and — in production — your database,
-either as an explicit `databaseUrl` here or as a signed
-[Data Source endpoint](./docs/data-sources.md) in your app. (`databaseUrl` is
-never auto-read from the environment; omit it to try Ablo against the hosted
-sandbox.) Every other option has correct defaults:
+`Ablo({ ... })` takes your schema and your key. Your database is connected
+**out of band** — once, via `npx ablo connect` (logical replication) or a signed
+[Data Source endpoint](./docs/data-sources.md) — not through the constructor.
+Every other option has correct defaults:
 
 | Option | Type | Default | Purpose |
 | --- | --- | --- | --- |
 | `schema` | `Schema` | — (required) | Typed model proxies (`ablo.<model>.*`) |
 | `apiKey` | `string \| ApiKeySetter \| null` | `process.env.ABLO_API_KEY` | Server key — a string, or an async function for rotation |
-| `databaseUrl` | `string \| null` | `—` | Your Postgres, registered as the data plane. **Must be passed explicitly — it is not auto-read from the environment.** If you have a `DATABASE_URL` set for another tool (Prisma, Drizzle, docker-compose), `Ablo()` ignores it unless you pass `databaseUrl` explicitly. Server runtimes only — the SDK throws if it sees this in a browser. Omit it when your app exposes a signed [Data Source endpoint](./docs/data-sources.md) instead, or when trying Ablo against the hosted sandbox. |
+| `databaseUrl` | `string \| null` | `—` | **Deprecated — being removed.** The old dial-in (Ablo holding a read/write connection to your DB). Connect via `npx ablo connect` (logical replication) instead; Ablo tails your WAL rather than dialing in. See [Connect Your Database](./docs/data-sources.md). |
 
 Keep `apiKey` in trusted server runtimes. In the browser, `<AbloProvider>`
 authenticates with the signed-in user's session; the raw-key path is gated
@@ -512,7 +521,7 @@ contract; there are no retry or timeout knobs to tune.
 - [React](./docs/react.md) — `<AbloProvider>`, `useAblo`, presence, status, and bootstrap gating.
 - [Coordination](./docs/coordination.md) — `claim` / `claim.state` / `claim.queue` / `claim.release` reference: hold a row across slow agent work, and observe the line waiting behind it.
 - [Client Behavior](./docs/client-behavior.md) — options, errors, retries, timeouts, and public imports.
-- [Connect Your Database](./docs/data-sources.md) — connect your Postgres by connection string (`databaseUrl`) or signed endpoint; your database is the system of record either way.
+- [Connect Your Database](./docs/data-sources.md) — connect your Postgres by logical replication (`npx ablo connect`) or, as a fallback, a signed endpoint; your database is the system of record either way.
 - [Existing Python Backend](./docs/examples/existing-python-backend.md) — migrate existing Python endpoints to multiplayer and agent-safe writes gradually.
 - [AI SDK Tool](./docs/examples/ai-sdk-tool.md) — use Ablo inside an AI SDK tool call.
 - [Server Agent](./docs/examples/server-agent.md) — schema-backed worker.

package/dist/cli.cjs

@@ -212120,17 +212120,19 @@ var require_commonjs2 = __commonJS({
     }
     function expand_(str, max, isTop) {
       const expansions = [];
-      const m2 = (0, balanced_match_1.balanced)("{", "}", str);
-      if (!m2)
-        return [str];
-      const pre = m2.pre;
-      const post = m2.post.length ? expand_(m2.post, max, false) : [""];
-      if (/\$$/.test(m2.pre)) {
-        for (let k3 = 0; k3 < post.length && k3 < max; k3++) {
-          const expansion = pre + "{" + m2.body + "}" + post[k3];
-          expansions.push(expansion);
+      for (; ; ) {
+        const m2 = (0, balanced_match_1.balanced)("{", "}", str);
+        if (!m2)
+          return [str];
+        const pre = m2.pre;
+        if (/\$$/.test(m2.pre)) {
+          const post2 = m2.post.length ? expand_(m2.post, max, false) : [""];
+          for (let k3 = 0; k3 < post2.length && k3 < max; k3++) {
+            const expansion = pre + "{" + m2.body + "}" + post2[k3];
+            expansions.push(expansion);
+          }
+          return expansions;
         }
-      } else {
         const isNumericSequence = /^-?\d+\.\.-?\d+(?:\.\.-?\d+)?$/.test(m2.body);
         const isAlphaSequence = /^[a-zA-Z]\.\.[a-zA-Z](?:\.\.-?\d+)?$/.test(m2.body);
         const isSequence = isNumericSequence || isAlphaSequence;
@@ -212138,10 +212140,12 @@ var require_commonjs2 = __commonJS({
         if (!isSequence && !isOptions) {
           if (m2.post.match(/,(?!,).*\}/)) {
             str = m2.pre + "{" + m2.body + escClose + m2.post;
-            return expand_(str, max, true);
+            isTop = true;
+            continue;
           }
           return [str];
         }
+        const post = m2.post.length ? expand_(m2.post, max, false) : [""];
         let n;
         if (isSequence) {
           n = m2.body.split(/\.\./);
@@ -212205,8 +212209,8 @@ var require_commonjs2 = __commonJS({
             }
           }
         }
+        return expansions;
       }
-      return expansions;
     }
   }
 });
@@ -280268,6 +280272,12 @@ async function push(argv) {
           `  One or more synced tables don't have FORCE ROW LEVEL SECURITY. Run ${import_picocolors3.default.bold("npx ablo migrate")} to (re)apply the tenant policies, then re-push.`
         )
       );
+    } else if (code === "capability_scope_denied" || code === "capability_invalid") {
+      console.error(
+        import_picocolors3.default.dim(
+          `  This is a ${import_picocolors3.default.bold("database privilege")} error (Postgres 42501 / row-level security), not a key scope \u2014 a different API key won't help. The role behind this org's database can't write the target. Provision a writable, RLS-scoped role with ${import_picocolors3.default.bold("npx ablo migrate")}, or check the org's database registration. See docs/plans/read-path-logical-replication-vs-hosting.md.`
+        )
+      );
     } else if (args.apiKey != null && classifyCredentialKind(args.apiKey) === "restricted") {
       console.error(
         import_picocolors3.default.dim(
@@ -280464,6 +280474,8 @@ var ABLO_PUBLICATION = "ablo_publication";
 var ABLO_REPLICATION_ROLE = "ablo_replicator";
 function parseConnectArgs(argv) {
   let check2 = false;
+  let register = false;
+  let auditInfra = false;
   let tables = [];
   let role = ABLO_REPLICATION_ROLE;
   for (let i = 0; i < argv.length; i++) {
@@ -280472,6 +280484,12 @@ function parseConnectArgs(argv) {
       case "--check":
         check2 = true;
         break;
+      case "--register":
+        register = true;
+        break;
+      case "--audit-infra":
+        auditInfra = true;
+        break;
       case "--tables": {
         const value = argv[++i] ?? "";
         tables = value.split(",").map((t) => t.trim()).filter((t) => t.length > 0);
@@ -280484,7 +280502,7 @@ function parseConnectArgs(argv) {
         throw new AbloValidationError(`unknown flag: ${arg}`, { code: "cli_invalid_arguments" });
     }
   }
-  return { check: check2, tables, role };
+  return { check: check2, register, auditInfra, tables, role };
 }
 function quoteIdent(id) {
   return `"${id.replace(/"/g, '""')}"`;
@@ -280508,12 +280526,12 @@ function connectSetupSql(input) {
 function printConnectRecipe(args) {
   const sql = connectSetupSql({ tables: args.tables, role: args.role });
   console.log(`
-  ${brand("ablo")} ${import_picocolors5.default.dim("connect")}  ${import_picocolors5.default.dim("logical replication \u2014 the one way to connect a real database")}
+  ${brand("ablo")} ${import_picocolors5.default.dim("connect")}  ${import_picocolors5.default.dim("logical replication \u2014 the read path (your writes stay on your own backend)")}
 `);
   console.log(
-    `  Ablo READS your write-ahead log (WAL) and ${import_picocolors5.default.bold("never")} runs DDL, owns, or migrates your
-  schema. Your app keeps writing through your own backend \u2014 Ablo only tails the changes.
-  Run this once against your Postgres ${import_picocolors5.default.dim("(as a superuser / the DB owner)")}:
+    `  Ablo consumes your write-ahead log (WAL) via logical replication and ${import_picocolors5.default.bold("never")} runs DDL,
+  owns, hosts, or migrates your schema. Your app continues to own the write path \u2014 Ablo tails
+  the changes and serves them as live shapes. Run this once against your Postgres ${import_picocolors5.default.dim("(as a superuser / DB owner)")}:
 `
   );
   console.log(`  ${import_picocolors5.default.bold("1.")} Enable logical decoding ${import_picocolors5.default.dim("(then RESTART Postgres \u2014 wal_level is not reloadable)")}`);
@@ -280549,12 +280567,24 @@ function printConnectRecipe(args) {
   );
   console.log(
     import_picocolors5.default.dim(
-      `  Reminder: Ablo never writes to your database on this path. Provisioning tables with
-  ${import_picocolors5.default.bold("ablo migrate")} is a separate, optional escape hatch \u2014 connecting a real database is this.`
+      `  Reminder: this is the READ path \u2014 Ablo tails your WAL and never writes to your database.
+  Your writes keep going through your own backend. (Ablo HOSTING your rows, or dialing in via
+  ${import_picocolors5.default.bold("databaseUrl")}, is the deprecated posture \u2014 see the read-path decision doc.)`
     )
   );
   console.log();
 }
+var SYNC_INFRA_RELATIONS = [
+  "sync_deltas",
+  "sync_id_seq",
+  "sync_metadata",
+  "mutation_log"
+];
+var SYNC_INFRA_TYPES = [
+  "participant_kind",
+  "backfill_provenance",
+  "confirmation_state"
+];
 function printCheckItem(item) {
   if (item.ok) {
     console.log(`  ${import_picocolors5.default.green("\u2713")} ${item.label}`);
@@ -280568,14 +280598,17 @@ function printCheckItem(item) {
 async function probeReadiness(sql, opts = {}) {
   const publication = opts.publication ?? ABLO_PUBLICATION;
   const items = [];
-  const walRows = await sql.unsafe(`SHOW wal_level`);
+  const walRows = await sql.unsafe(
+    `SELECT setting FROM pg_settings WHERE name = 'wal_level'`
+  );
   const walLevel = walRows[0]?.setting ?? "unknown";
   items.push(
     walLevel === "logical" ? { ok: true, label: `wal_level is ${import_picocolors5.default.bold("logical")}` } : {
       ok: false,
       label: `wal_level is ${import_picocolors5.default.bold(walLevel)} (need ${import_picocolors5.default.bold("logical")})`,
       fix: `ALTER SYSTEM SET wal_level = 'logical'; then RESTART Postgres.
-On RDS/Aurora set rds.logical_replication = 1 in the parameter group, then reboot.`
+On RDS/Aurora set rds.logical_replication = 1 in the parameter group, then reboot.
+On Neon enable Logical Replication in the project (Console \u2192 Settings \u2192 Logical Replication, or the API) \u2014 Neon forbids ALTER SYSTEM; the toggle sets wal_level=logical.`
     }
   );
   const pubRows = await sql.unsafe(
@@ -280636,17 +280669,35 @@ On RDS: GRANT rds_replication TO <your_role>;`
   }
   return items;
 }
-async function runCheck() {
+async function auditTenantSyncInfra(sql) {
+  const artifacts = [];
+  for (const name of SYNC_INFRA_RELATIONS) {
+    const rows = await sql.unsafe(
+      `SELECT to_regclass($1)::text AS reg`,
+      [`public.${name}`]
+    );
+    artifacts.push({ kind: "relation", name, present: rows[0]?.reg != null });
+  }
+  for (const name of SYNC_INFRA_TYPES) {
+    const rows = await sql.unsafe(
+      `SELECT to_regtype($1)::text AS reg`,
+      [`public.${name}`]
+    );
+    artifacts.push({ kind: "type", name, present: rows[0]?.reg != null });
+  }
+  return artifacts;
+}
+function requireDatabaseUrl(verb) {
   const dbUrl = readProjectDatabaseUrl();
   if (!dbUrl) {
     console.error(
-      import_picocolors5.default.red("  No DATABASE_URL found (checked process env, .env.local, .env).") + import_picocolors5.default.dim(` Set it to the Postgres you want Ablo to read, then re-run ${import_picocolors5.default.bold("ablo connect --check")}.`)
+      import_picocolors5.default.red("  No DATABASE_URL found (checked process env, .env.local, .env).") + import_picocolors5.default.dim(` Set it to the Postgres you want Ablo to read, then re-run ${import_picocolors5.default.bold(`ablo connect ${verb}`)}.`)
     );
     process.exit(1);
   }
-  console.log(`
-  ${brand("ablo")} ${import_picocolors5.default.dim("connect --check")}  ${import_picocolors5.default.dim("logical-replication readiness")}
-`);
+  return dbUrl;
+}
+async function probeAndReport(dbUrl) {
   const sql = src_default(dbUrl, { max: 1, prepare: false, onnotice: () => {
   } });
   let items;
@@ -280660,7 +280711,14 @@ async function runCheck() {
   }
   await sql.end({ timeout: 2 });
   for (const item of items) printCheckItem(item);
-  const failures = items.filter((i) => !i.ok).length;
+  return items.filter((i) => !i.ok).length;
+}
+async function runCheck() {
+  const dbUrl = requireDatabaseUrl("--check");
+  console.log(`
+  ${brand("ablo")} ${import_picocolors5.default.dim("connect --check")}  ${import_picocolors5.default.dim("logical-replication readiness")}
+`);
+  const failures = await probeAndReport(dbUrl);
   console.log();
   if (failures === 0) {
     console.log(`  ${import_picocolors5.default.green("\u2713")} Ready \u2014 Ablo can connect and tail this database's WAL.
@@ -280673,6 +280731,104 @@ async function runCheck() {
   );
   process.exit(1);
 }
+async function runRegister() {
+  const dbUrl = requireDatabaseUrl("--register");
+  const apiKey = resolveApiKey();
+  if (!apiKey) {
+    console.error(
+      import_picocolors5.default.red("  Not logged in.") + import_picocolors5.default.dim(` Run ${import_picocolors5.default.bold("ablo login")} (or set ${import_picocolors5.default.bold("ABLO_API_KEY")}) so Ablo knows which project to register this database for.`)
+    );
+    process.exit(1);
+  }
+  console.log(`
+  ${brand("ablo")} ${import_picocolors5.default.dim("connect --register")}  ${import_picocolors5.default.dim("register this database for replication")}
+`);
+  const failures = await probeAndReport(dbUrl);
+  if (failures > 0) {
+    console.log(
+      `
+  ${import_picocolors5.default.red(`${failures} item${failures === 1 ? "" : "s"} to fix`)} ${import_picocolors5.default.dim("\u2014 a database that isn\u2019t replication-ready can\u2019t stream. Fix the above, then re-run.")}
+`
+    );
+    process.exit(1);
+  }
+  const apiUrl2 = (process.env.ABLO_API_URL ?? DEFAULT_URL).replace(/\/+$/, "");
+  let res;
+  try {
+    res = await fetch(`${apiUrl2}/v1/datasources`, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
+      body: JSON.stringify({ connectionString: dbUrl })
+    });
+  } catch (err) {
+    console.error(import_picocolors5.default.red(`
+  Couldn't reach ${apiUrl2}: ${err instanceof Error ? err.message : String(err)}
+`));
+    process.exit(1);
+  }
+  if (res.ok) {
+    const body2 = await res.json().catch(() => ({}));
+    console.log(
+      `
+  ${import_picocolors5.default.green("\u2713")} Registered${body2.host ? ` ${import_picocolors5.default.dim(body2.host)}` : ""}${body2.id ? ` ${import_picocolors5.default.dim(`(${body2.id})`)}` : ""} \u2014 Ablo will replicate this database on the next sync.
+`
+    );
+    process.exit(0);
+  }
+  const body = await res.json().catch(() => ({}));
+  const code = body.error?.code;
+  const message = body.error?.message ?? `HTTP ${res.status}`;
+  console.error(import_picocolors5.default.red(`
+  Registration failed: ${message}`));
+  if (code === "forbidden") {
+    console.error(import_picocolors5.default.dim(`  Registering a database needs a ${import_picocolors5.default.bold("secret")} key (sk_\u2026). Run ${import_picocolors5.default.bold("ablo login")} for one.`));
+  } else if (code === "datasource_direct_deprecated") {
+    console.error(
+      import_picocolors5.default.dim(
+        `  This deployment doesn\u2019t accept new connection-string registrations yet. The operator must enable it (${import_picocolors5.default.bold("ABLO_ALLOW_DIRECT_DATASOURCE=true")}) \u2014 see ${import_picocolors5.default.bold("docs/runbooks/connect-customer-database-byo-replication.md")}.`
+      )
+    );
+  } else if (code === "datasource_connection_unsupported") {
+    console.error(
+      import_picocolors5.default.dim(`  This deployment can\u2019t accept connection strings \u2014 use a self-hosted/hosted engine, or the signed endpoint fallback.`)
+    );
+  }
+  console.error();
+  process.exit(1);
+}
+async function runAuditInfra() {
+  const dbUrl = requireDatabaseUrl("--audit-infra");
+  const sql = src_default(dbUrl, { max: 1, prepare: false, onnotice: () => {
+  } });
+  let artifacts;
+  try {
+    artifacts = await auditTenantSyncInfra(sql);
+  } catch (err) {
+    const pg = err ?? {};
+    console.error(import_picocolors5.default.red(`  Couldn't audit the database: ${pg.message ?? String(err)}`));
+    await sql.end({ timeout: 2 });
+    process.exit(1);
+  }
+  await sql.end({ timeout: 2 });
+  console.log(`
+  ${brand("ablo")} ${import_picocolors5.default.dim("connect --audit-infra")}  ${import_picocolors5.default.dim("Stage 5 tenant DB sync-infra audit")}
+`);
+  const present = artifacts.filter((a) => a.present);
+  if (present.length === 0) {
+    console.log(`  ${import_picocolors5.default.green("\u2713")} No deprecated Ablo sync infrastructure found in public.
+`);
+    process.exit(0);
+  }
+  for (const artifact of present) {
+    const label = artifact.kind === "type" ? "type" : "relation";
+    console.log(`  ${import_picocolors5.default.yellow("!")} ${label} ${import_picocolors5.default.bold(`public.${artifact.name}`)} exists`);
+  }
+  console.log(
+    `
+  ${import_picocolors5.default.yellow(`${present.length} artifact${present.length === 1 ? "" : "s"} found`)} ` + import_picocolors5.default.dim("\u2014 do not drop automatically. Confirm the org/environment is log-authoritative, then follow ") + import_picocolors5.default.bold("docs/runbooks/wal-stage5-customer-db-infra-cleanup.md") + import_picocolors5.default.dim(".\n")
+  );
+  process.exit(1);
+}
 async function connect(argv) {
   let args;
   try {
@@ -280685,18 +280841,28 @@ async function connect(argv) {
     await runCheck();
     return;
   }
+  if (args.register) {
+    await runRegister();
+    return;
+  }
+  if (args.auditInfra) {
+    await runAuditInfra();
+    return;
+  }
   printConnectRecipe(args);
 }
-var CONNECT_USAGE = `  ablo connect \u2014 connect a real database to Ablo via logical replication (the one way)
+var CONNECT_USAGE = `  ablo connect \u2014 connect your database for the read path, via logical replication
 
-  Ablo READS your WAL and never runs DDL, owns, or migrates your schema. Your app
-  keeps writing through your own backend.
+  The Electric/PowerSync/Zero model: Ablo consumes your WAL via logical replication and
+  never runs DDL, owns, hosts, or migrates your schema. Your app continues to own the write path.
 
   Usage:
     npx ablo connect                      Print the exact setup SQL for your Postgres
     npx ablo connect --tables a,b,c       Publish only these tables (default: all tables)
     npx ablo connect --role <name>        Name the replication role (default: ablo_replicator)
-    npx ablo connect --check              Validate DATABASE_URL is replication-ready`;
+    npx ablo connect --check              Validate DATABASE_URL is replication-ready
+    npx ablo connect --register           Register DATABASE_URL so Ablo replicates it (one self-service step)
+    npx ablo connect --audit-infra        Read-only Stage 5 audit for deprecated Ablo sync tables/types`;
 
 // src/cli/generate.ts
 init_cjs_shims();
@@ -281445,6 +281611,45 @@ async function fetchPushedSchema(apiUrl2, apiKey) {
     clearTimeout(t);
   }
 }
+async function sampleRead(apiUrl2, apiKey, modelTypename, n) {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), 4e3);
+  try {
+    const res = await fetch(
+      `${apiUrl2}/v1/models/${encodeURIComponent(modelTypename)}/__ablo_health_probe_${n}__`,
+      { headers: { authorization: `Bearer ${apiKey}` }, signal: ctrl.signal }
+    );
+    if (res.ok) return "routed";
+    let code;
+    try {
+      const body = await res.json();
+      code = body.code ?? body.error?.code;
+    } catch {
+    }
+    if (code === "entity_not_found") return "routed";
+    if (code === "tenant_routing_failed") return "no_route";
+    if (res.status === 401 || res.status === 403) return { forbidden: code };
+    return { other: `${res.status}${code ? ` ${code}` : ""}` };
+  } catch {
+    return { other: "unreachable" };
+  } finally {
+    clearTimeout(t);
+  }
+}
+async function probeDataPlane(apiUrl2, apiKey, modelTypename) {
+  if (!apiKey) return { status: "skipped" };
+  const samples = [];
+  for (let i = 0; i < 3; i++) samples.push(await sampleRead(apiUrl2, apiKey, modelTypename, i));
+  const forbidden = samples.find((s) => typeof s === "object" && "forbidden" in s);
+  if (forbidden) return { status: "forbidden", detail: forbidden.forbidden };
+  const routed = samples.filter((s) => s === "routed").length;
+  const noRoute = samples.filter((s) => s === "no_route").length;
+  if (routed === samples.length) return { status: "ok" };
+  if (noRoute === samples.length) return { status: "no_database" };
+  if (routed > 0 && noRoute > 0) return { status: "intermittent", ok: routed, failed: noRoute };
+  const other = samples.find((s) => typeof s === "object" && "other" in s);
+  return { status: "unknown", detail: other?.other ?? "inconclusive" };
+}
 function formatConflict(conflict) {
   if (!conflict) return "";
   const parts = ["user", "agent", "system"].flatMap((k3) => conflict[k3] ? [`${k3}:${conflict[k3]}`] : []);
@@ -281550,6 +281755,28 @@ async function status(args = []) {
     } else if (pushed && !pushed.active) {
       console.log(`  ${import_picocolors11.default.dim("schema")}  ${import_picocolors11.default.yellow("none pushed")} ${import_picocolors11.default.dim(`(run ${import_picocolors11.default.bold("ablo push")} or ${import_picocolors11.default.bold("ablo dev")})`)}`);
     }
+    if (pushed && pushed.active && pushed.models.length > 0) {
+      const probe = await probeDataPlane(apiUrl2, introspectKey, pushed.models[0].typename);
+      if (probe.status === "no_database") {
+        console.log(`  ${import_picocolors11.default.dim("data")}    ${import_picocolors11.default.red("\u2717 no database registered")}${org ? import_picocolors11.default.dim(` for org ${org}`) : ""}`);
+        console.log(
+          `          ${import_picocolors11.default.dim(
+            `reads/writes will fail with ${import_picocolors11.default.bold("tenant_routing_failed")}. Connect one with ${import_picocolors11.default.bold("ablo connect")}, or point ${import_picocolors11.default.bold("ABLO_API_KEY")} at an org that has a database.`
+          )}`
+        );
+      } else if (probe.status === "intermittent") {
+        console.log(`  ${import_picocolors11.default.dim("data")}    ${import_picocolors11.default.red(`\u2717 database routing is intermittent`)} ${import_picocolors11.default.dim(`(${probe.ok} ok / ${probe.failed} failed of ${probe.ok + probe.failed})`)}${org ? import_picocolors11.default.dim(` for org ${org}`) : ""}`);
+        console.log(
+          `          ${import_picocolors11.default.dim(
+            `some reads/writes fail with ${import_picocolors11.default.bold("tenant_routing_failed")} \u2014 the registration is unstable. Re-establish it with ${import_picocolors11.default.bold("ablo connect")} (or check for a recent server redeploy).`
+          )}`
+        );
+      } else if (probe.status === "forbidden") {
+        console.log(`  ${import_picocolors11.default.dim("data")}    ${import_picocolors11.default.yellow("? key not authorized to read")}${probe.detail ? import_picocolors11.default.dim(` (${probe.detail})`) : ""}`);
+      } else if (probe.status === "unknown") {
+        console.log(`  ${import_picocolors11.default.dim("data")}    ${import_picocolors11.default.yellow(`? data-plane check inconclusive (${probe.detail})`)}`);
+      }
+    }
   }
   console.log();
 }
@@ -283055,6 +283282,7 @@ async function main() {
     console.log(`    npx ablo check                         Check your existing database fits the schema (read-only, creates no tables)`);
     console.log(`    npx ablo connect                       Connect a real database \u2014 prints the logical-replication setup SQL (the one way)`);
     console.log(`    npx ablo connect --check               Validate DATABASE_URL is replication-ready (wal_level, publication, role, replica identity)`);
+    console.log(`    npx ablo connect --audit-infra         Read-only audit for deprecated Ablo sync infra in a customer DB`);
     console.log(`    npx ablo migrate                       Provision your synced-model tables in your own Postgres (optional escape hatch \u2014 \`connect\` is the way)`);
     console.log(`    npx ablo migrate --dry-run             Print the SQL without executing (preview)`);
     console.log(`    npx ablo push                          Upload your schema definition to Ablo (metadata only \u2014 rows stay in your DB)`);
@@ -283080,7 +283308,7 @@ function bailIfCancelled(value) {
 }
 var INIT_FRAMEWORKS = ["nextjs", "vite", "remix", "vanilla"];
 var INIT_AUTHS = ["apikey", "firebase", "auth0", "clerk", "supabase", "betterauth", "jwt"];
-var INIT_STORAGES = ["endpoint", "direct", "datasource"];
+var INIT_STORAGES = ["replication", "endpoint", "direct", "datasource"];
 function parseInitArgs(args) {
   const has = (flag2) => args.includes(flag2);
   const val = (flag2) => {
@@ -283206,15 +283434,15 @@ async function init(args = []) {
   const storageChoice = await chooseOption(
     "storage",
     opts.storage,
-    "endpoint",
+    "replication",
     INIT_STORAGES,
     false,
-    () => Promise.resolve("endpoint")
+    () => Promise.resolve("replication")
   );
   const storage = storageChoice === "datasource" ? "endpoint" : storageChoice;
   if (storage === "direct") {
     Me(
-      "`--storage direct` uses the deprecated databaseUrl connector. The signed Data\nSource endpoint is the supported path.",
+      "`--storage direct` uses the deprecated databaseUrl connector. Logical replication\n(`npx ablo connect`) is the supported path; a signed Data Source endpoint is the fallback.",
       import_picocolors20.default.yellow("Deprecated")
     );
   }
@@ -283335,7 +283563,9 @@ async function init(args = []) {
     `Run ${import_picocolors20.default.bold("npx ablo login")} (or add ${import_picocolors20.default.bold("ABLO_API_KEY")} to ${import_picocolors20.default.bold(envFile)})`,
     `Set ${import_picocolors20.default.bold("DATABASE_URL")} in ${import_picocolors20.default.bold(envFile)} \u2014 your Postgres is the system of record; rows live there, never with Ablo`,
     `Run ${import_picocolors20.default.bold("npx ablo dev")} \u2014 pushes your schema definition and watches for changes`,
-    ...storage === "direct" ? [
+    ...storage === "replication" ? [
+      `Connect your database: ${import_picocolors20.default.bold("npx ablo connect")} prints the logical-replication setup SQL (run it once on your Postgres), then ${import_picocolors20.default.bold("npx ablo connect --register")} tells Ablo to replicate it \u2014 your app keeps writing through your own backend, Ablo tails the WAL`
+    ] : storage === "direct" ? [
       `Provision your DB: ${import_picocolors20.default.bold("npx ablo migrate")} (creates your synced-model tables with row-level security; keep your own migrations for everything else)`
     ] : [
       `Provision your DB: ${import_picocolors20.default.bold("npx ablo migrate")} (creates your Ablo-model tables + the adapter tables; keep your own migrations for everything else), then mount ${import_picocolors20.default.bold(`${abloDir}/data-source.ts`)} at ${import_picocolors20.default.bold("/api/ablo/source")}`
@@ -283440,7 +283670,7 @@ export {};
 }
 function generateEnv(storage, opts = {}) {
   const { includeApiKey = true } = opts;
-  const databaseBlock = storage === "direct" ? "# DEPRECATED direct connector. The client registers this connection (sent once\n# over TLS, stored sealed) so Ablo dials into your Postgres. Prefer a signed Data\n# Source endpoint; to keep the transaction log in your infra too, self-host the engine.\n# Use a dedicated non-superuser role; the browser never sees this value.\nDATABASE_URL=postgres://user:password@host:5432/db\n" : "# Used by ablo/data-source.ts (your DB endpoint) + `ablo migrate` \u2014 NOT the client.\n# Ablo never sees it; the browser never sees it. Your DB stays in your app.\nDATABASE_URL=postgres://user:password@host:5432/db\n";
+  const databaseBlock = storage === "direct" ? "# DEPRECATED direct connector. The client registers this connection (sent once\n# over TLS, stored sealed) so Ablo dials into your Postgres. Prefer logical\n# replication (`npx ablo connect`); to keep the transaction log in your infra too,\n# self-host the engine. Use a dedicated non-superuser role; the browser never sees this.\nDATABASE_URL=postgres://user:password@host:5432/db\n" : storage === "replication" ? "# Used by `npx ablo connect` to set up + register logical replication \u2014 the\n# DIRECT (un-pooled) endpoint. Ablo TAILS your WAL from here; it never writes.\n# The client never sees it; the browser never sees it. Your DB stays yours.\nDATABASE_URL=postgres://user:password@host:5432/db\n" : "# Used by ablo/data-source.ts (your DB endpoint) + `ablo migrate` \u2014 NOT the client.\n# Ablo never sees it; the browser never sees it. Your DB stays in your app.\nDATABASE_URL=postgres://user:password@host:5432/db\n";
   const webhookBlock = storage === "endpoint" ? "# Signing secret for the webhook receiver (app/api/ablo/webhooks/route.ts).\n# Ablo mints this when you register the endpoint's URL (POST /v1/webhook_endpoints\n# or the dashboard) and returns it once \u2014 paste it here.\nABLO_WEBHOOK_SECRET=whsec_your_endpoint_secret_here\n" : "";
   const apiKeyBlock = includeApiKey ? "# Ablo Sync Engine \u2014 use a sk_test_ key for local dev (`npx ablo push`)\nABLO_API_KEY=sk_test_your_key_here\n" : "";
   return `${apiKeyBlock}${webhookBlock}${databaseBlock}`;

package/docs/data-sources.md

@@ -6,7 +6,8 @@ schema, and never migrates it**. Your application keeps writing to its own
 Postgres through its own backend, exactly as it does today; Ablo only tails the
 changes and fans the confirmed rows out to every connected human and agent. This
 is the same model ElectricSQL, PowerSync, and Zero use — a publication plus a
-replication slot, read-only.
+replication slot. Ablo consumes the logical-replication stream; your application
+continues to own the write path.
 
 > **Just trying Ablo?** You don't need a database at all to start. The hosted
 > **sandbox** can host rows in Ablo's test plane — pass an `apiKey` only and omit
@@ -94,8 +95,10 @@ Re-run it until every item is green.
 
 ### 4. Point Ablo at the database with the replication role
 
-Give Ablo the connection string for the **replication role** you created. This is
-a read-only WAL connection — the same value `--check` validated:
+Give Ablo the connection string for the **replication role** you created — a
+`REPLICATION`-attributed role that streams the WAL and `SELECT`s, nothing more
+(not a read-only account; see the privilege note below). The same value `--check`
+validated:
 
 ```bash
 # .env — server runtime only, never the browser
@@ -156,8 +159,12 @@ Operational reality you should know up front:
   WAL accumulates and consumes disk. **Ablo monitors slot lag and WAL retention**
   and surfaces it so you're never surprised by disk pressure; an abandoned slot is
   dropped rather than left to grow unbounded.
-- **The role is read-only.** It can stream replication and `SELECT`. It cannot
-  write, and the recipe never grants it more.
+- **The role's privilege footprint is narrow and precise — not a "read-only"
+  account.** It carries the `REPLICATION` attribute, which lets it stream the WAL
+  and `SELECT`; it cannot `INSERT`/`UPDATE`/`DELETE`, run DDL, or own objects, and
+  the recipe never grants it more. (For a security review, state it that way — a
+  logical-replication role is a real privilege, just a tightly-scoped one — rather
+  than calling it "read-only", which a reviewer will correctly push back on.)
 
 What Ablo explicitly does **not** do:
 

package/llms.txt

@@ -122,9 +122,11 @@ A schema is model fields and relations. Advanced schema helpers such as `mutable
 
 ## Storage Boundary
 
-`databaseUrl` is an OPTIONAL, server-only constructor option on `Ablo(...)`. It is NOT auto-read from the environment — pass it EXPLICITLY to register your Postgres directly. Omit it when you expose a signed Data Source endpoint, or when trying Ablo against the hosted sandbox (apiKey only). A `DATABASE_URL` set for another tool (Prisma, Drizzle, docker-compose) is ignored unless you pass `databaseUrl` explicitly.
+THE ONE PATH IS LOGICAL REPLICATION. In production every schema model is backed by YOUR OWN database, and Ablo connects to it by CONSUMING ITS WRITE-AHEAD LOG (logical replication) — the Electric/PowerSync/Zero model. Ablo tails the WAL and fans changes out; YOUR APPLICATION CONTINUES TO OWN THE WRITE PATH (your own backend, your existing API). Ablo never runs DDL on, writes to, owns, or migrates your database. Connect once with `npx ablo connect` (prints the setup SQL: `wal_level=logical`, a publication, a `REPLICATION` role) then `npx ablo connect --register`. Validate with `npx ablo connect --check`. The role's privilege footprint is narrow but real — a `REPLICATION`-attributed role that streams the WAL and `SELECT`s; do NOT describe it as "read-only" (a security reviewer will push back — it is a replication privilege, just tightly scoped).
 
-In production, every schema model is backed by YOUR OWN database. The PRIMARY path is the connection string: pass `databaseUrl` (most users already have a Postgres — often Prisma- or Drizzle-managed for auth/audit/log tables that are NOT in the Ablo schema; Ablo syncs a SUBSET of models against it). Most users do NOT run `ablo migrate` — they ADOPT existing tables with `npx ablo pull` / `npx ablo check`, or keep managing tables with their own migration tool. Run `npx ablo migrate` only when Ablo should OWN the tables (it provisions the synced-model tables in your DB). The alternative to the connection string is a signed Data Source endpoint that hands Ablo an ORM `adapter` (Drizzle is the default; Prisma and Kysely are also supported) — it owns the transaction, exactly-once idempotency, and outbox in ONE pass (no hand-written `commit`/`events`); use it when database credentials must never leave your infrastructure (or for a local/private-range DB, which Ablo's cloud cannot reach over the network).
+FALLBACK (only when the database can't grant a `REPLICATION` role, e.g. a locked-down managed DB): a signed Data Source endpoint that hands Ablo an ORM `adapter` (Drizzle default; Prisma and Kysely supported) — it owns the transaction, exactly-once idempotency, and outbox in ONE pass; your credentials never leave your infrastructure.
+
+DEPRECATED — being removed, do NOT recommend or scaffold: the `databaseUrl` constructor option (the dial-in, where Ablo held a read/write connection and committed directly to your DB). The end-state constructor is `Ablo({ schema, apiKey })`; the database is connected out of band via `ablo connect`, not through `databaseUrl`. (Note: `ablo init` still defaults to `--storage direct` scaffolding `databaseUrl` — that default is itself slated to lead with `ablo connect`; prefer logical replication regardless of what `init` scaffolds.)
 
 GOTCHA the user WILL hit: `DATABASE_URL` must use a NON-superuser, NON-BYPASSRLS role (Ablo enforces row-level security; owner roles are rejected with `database_role_cannot_enforce_rls`). Neon's and Supabase's default dashboard connection strings use the database OWNER (e.g. `neondb_owner`) and are rejected. EASIEST: `npx ablo migrate` detects the unsafe role and creates the scoped one automatically from the user's machine (owner credential never reaches Ablo; new DATABASE_URL written to the env file). Manual alternative — create a scoped role first: `CREATE ROLE ablo_app LOGIN PASSWORD '...' NOSUPERUSER NOBYPASSRLS; GRANT CREATE, CONNECT ON DATABASE <db> TO ablo_app; GRANT CREATE, USAGE ON SCHEMA public TO ablo_app;` — then swap user/password into the same host/db string.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",