@abloatai/ablo 0.23.0 → 0.25.0

package/dist/client/Ablo.js

@@ -20,6 +20,7 @@
  */
 import { z } from 'zod';
 import { baseFieldsSchema } from '../schema/schema.js';
+import { schemaHash } from '../schema/serialize.js';
 import { AbloError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, AbloNotFoundError, translateHttpError, toAbloError, claimedError } from '../errors.js';
 import { descriptionFromMeta } from '../coordination/schema.js';
 import { LoadStrategy, PropertyType } from '../types/index.js';
@@ -222,6 +223,9 @@ function deriveConfigFromSchema(schema) {
         defaultNonCreatePriority: 50,
         essentialFields: {},
         classNameFallbackMap: {},
+        // Hash this client's schema once so bootstrap can detect drift against the
+        // server's active hash (same `schemaHash` the CLI push + server compute).
+        expectedSchemaHash: schemaHash(schema),
     };
 }
 // ── Auto model registration from schema ───────────────────────────────────

package/dist/interfaces/index.d.ts

@@ -380,6 +380,14 @@ export interface SyncEngineConfig {
      * e.g., { TaskModel: 'Task', ProjectModel: 'Project' }
      */
     classNameFallbackMap: Readonly<Record<string, string>>;
+    /**
+     * Content hash of the schema THIS client was built against (the same
+     * `schemaHash()` the CLI push + server compute). Used purely to detect
+     * schema drift: when the server reports a different active hash on bootstrap,
+     * the SDK warns the developer to run `ablo push` — otherwise drift only
+     * surfaces later as an opaque DB constraint error. Advisory, not enforced.
+     */
+    expectedSchemaHash?: string;
 }
 /**
  * Allows consumers to extend the WebSocket event map with

package/dist/sync/BootstrapHelper.d.ts

@@ -18,6 +18,12 @@ export interface BootstrapData {
     /** Model types whose server-side query failed (timeout, RLS error, etc.) */
     failedModels?: string[];
     timestamp: number;
+    /**
+     * The server's ACTIVE schema content hash for this tenant (same `schemaHash`
+     * the CLI push computes). Present once the tenant has pushed a schema; the
+     * client compares it to its own `config.expectedSchemaHash` to warn on drift.
+     */
+    schemaHash?: string;
 }
 export interface BootstrapFetchResult {
     notModified: boolean;
@@ -72,7 +78,17 @@ import { type ValidatedServerDelta } from './schemas.js';
 export declare class BootstrapHelper {
     private options;
     private abortController;
+    /** Warn about schema drift at most once per helper. */
+    private schemaDriftWarned;
     get baseUrl(): string;
+    /**
+     * Advisory schema-drift check: compare the server's active schema hash (on the
+     * bootstrap response) against the hash this client was built with. A mismatch
+     * means the app's schema and the deployed schema have diverged — reads/writes
+     * relying on undeployed changes will later fail with an opaque DB constraint
+     * error. Warn once, actionably; never throws or blocks the bootstrap.
+     */
+    private warnOnSchemaDrift;
     constructor(options: BootstrapOptions);
     /**
      * Update the offline-cache namespace once auth has resolved the server-side

package/dist/sync/BootstrapHelper.js

@@ -10,9 +10,34 @@ import { parseBootstrapResponse } from './schemas.js';
 export class BootstrapHelper {
     options;
     abortController = null;
+    /** Warn about schema drift at most once per helper. */
+    schemaDriftWarned = false;
     get baseUrl() {
         return this.options.baseUrl;
     }
+    /**
+     * Advisory schema-drift check: compare the server's active schema hash (on the
+     * bootstrap response) against the hash this client was built with. A mismatch
+     * means the app's schema and the deployed schema have diverged — reads/writes
+     * relying on undeployed changes will later fail with an opaque DB constraint
+     * error. Warn once, actionably; never throws or blocks the bootstrap.
+     */
+    warnOnSchemaDrift(serverHash) {
+        if (this.schemaDriftWarned || !serverHash)
+            return;
+        const clientHash = getContext().config.expectedSchemaHash;
+        if (!clientHash || clientHash === serverHash)
+            return;
+        this.schemaDriftWarned = true;
+        // Self-brand the message ("Ablo:") rather than rely on the default logger's
+        // `[Ablo]` namespace — consumers wiring their own logger (pino, etc.) lose
+        // that prefix, and a drift warning that reads like the app's own log is
+        // worse than none. The brand tells them at a glance who is talking.
+        getContext().logger.warn(`Ablo: Schema drift detected — this app was built against schema ${clientHash}, ` +
+            `but the deployed schema is ${serverHash}. Operations that depend on schema ` +
+            `changes not yet deployed will fail later with an opaque database error. Run ` +
+            `\`ablo push\` to deploy your schema (or update this app to match the deployed one).`, { clientSchemaHash: clientHash, serverSchemaHash: serverHash });
+    }
     constructor(options) {
         // Defaults are spread first; the explicit `baseUrl` then takes precedence
         // and is computed from `options.baseUrl` (or the localhost fallback).
@@ -254,6 +279,7 @@ export class BootstrapHelper {
         }
         const rawJson = await res.json();
         const data = parseBootstrapResponse(rawJson);
+        this.warnOnSchemaDrift(data.schemaHash);
         // Persist payload for offline
         try {
             if (this.options.cacheScope) {
@@ -326,6 +352,7 @@ export class BootstrapHelper {
         }
         const rawJson = await response.json();
         const data = parseBootstrapResponse(rawJson);
+        this.warnOnSchemaDrift(data.schemaHash);
         // Save a copy for offline
         try {
             if (this.options.cacheScope) {

package/dist/sync/schemas.d.ts

@@ -70,6 +70,7 @@ export declare const BootstrapResponseSchema: z.ZodObject<{
     deltaCount: z.ZodOptional<z.ZodNumber>;
     failedModels: z.ZodOptional<z.ZodArray<z.ZodString>>;
     timestamp: z.ZodDefault<z.ZodNumber>;
+    schemaHash: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>;
 export type ValidatedBootstrapResponse = z.infer<typeof BootstrapResponseSchema>;
 /**

package/dist/sync/schemas.js

@@ -54,6 +54,9 @@ export const BootstrapResponseSchema = z
     deltaCount: z.number().optional(),
     failedModels: z.array(z.string()).optional(),
     timestamp: z.number().default(() => Date.now()),
+    // Server's active schema hash (drift detection). Optional: absent from
+    // older servers / tenants that have never pushed a schema.
+    schemaHash: z.string().optional(),
 })
     .passthrough();
 // ─── Parse Helpers ───────────────────────────────────────────────────────────

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.23.0",
+  "version": "0.25.0",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",