@abloatai/ablo 0.23.0 → 0.24.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/package.json

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