@abloatai/ablo 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.20.0
+
+### Minor Changes
+
+- Reactive reads now work out of the box. A read like `useAblo((a) => a.documents.get(id))` re-renders when a live delta updates the row — including in-place field updates (the common collaborative case), which previously fired no reaction and left the UI silently stale.
+
+  Two changes make this work:
+  - **Models are reactive by default.** Schema fields are now MobX-observable without opting in. `json` fields stay `observable.ref` (one atom for the whole blob, not a deep atom tree per node), so the default is cheap. Opt out per model with `lazyObservable: false` for very large read-only list models where the QueryView's entry-replaced reactivity is enough.
+  - **`useAblo` returns a plain row snapshot** (via the new `Model.toReactiveSnapshot()`) instead of the live model instance. Reading the fields inside the tracked function is what subscribes the reaction (MobX tracks property access, not values), and the fresh snapshot identity lets the hook detect the change. Consumers get plain row objects and never touch a MobX observable directly.
+
+  Also new: `deepEqual` and `stableStringify` exports for comparing `field.json()` values. A `jsonb`-backed json field round-trips with reordered object keys (Postgres `jsonb` does not preserve key order), so a naive `JSON.stringify(a) === JSON.stringify(b)` comparison is unreliable when reconciling against external state (e.g. a rich-text editor). These helpers compare key-order-insensitively.
+
 ## 0.19.0
 
 ### Minor Changes

package/dist/Model.d.ts

@@ -359,6 +359,28 @@ export declare abstract class Model {
      * Capture snapshot for change detection
      */
     protected captureSnapshot(): ModelData;
+    /**
+     * A fresh, plain row snapshot that READS every declared field through its
+     * MobX observable getter. This is the reactive read surface for
+     * `useReactive`/`useAblo`, and it relies on two MobX facts:
+     *
+     *  1. MobX tracks property *access*, not values — so reading each field here,
+     *     inside the caller's tracked function, SUBSCRIBES the reaction to that
+     *     field. A bare `return model` (the previous `modelAsRow`) dereferences
+     *     nothing, so an in-place delta update fires no reaction and the UI never
+     *     re-renders. (https://mobx.js.org/understanding-reactivity.html)
+     *  2. The returned object is a NEW identity each call, so the hook's equality
+     *     check detects the change — the same mutated instance would compare equal
+     *     and suppress the re-render even after tracking fired.
+     *
+     * Unlike `toJSON()`, values keep their runtime types (a `Date` stays a `Date`,
+     * a json field stays its parsed object) and wire-noise keys
+     * (`__class`/`clientId`/`syncStatus`) are omitted — this is exactly the row
+     * the schema's `T` describes. Computed relations (`referenceModel`/
+     * `referenceCollection`) and ephemeral fields are skipped, matching `toJSON`'s
+     * row projection; they're lazy/recursive and not part of the row's data.
+     */
+    toReactiveSnapshot<T = ModelData>(): T;
     /**
      * Get field changes for activity tracking
      */

package/dist/Model.js

@@ -731,6 +731,51 @@ export class Model {
         }
         return snapshot;
     }
+    /**
+     * A fresh, plain row snapshot that READS every declared field through its
+     * MobX observable getter. This is the reactive read surface for
+     * `useReactive`/`useAblo`, and it relies on two MobX facts:
+     *
+     *  1. MobX tracks property *access*, not values — so reading each field here,
+     *     inside the caller's tracked function, SUBSCRIBES the reaction to that
+     *     field. A bare `return model` (the previous `modelAsRow`) dereferences
+     *     nothing, so an in-place delta update fires no reaction and the UI never
+     *     re-renders. (https://mobx.js.org/understanding-reactivity.html)
+     *  2. The returned object is a NEW identity each call, so the hook's equality
+     *     check detects the change — the same mutated instance would compare equal
+     *     and suppress the re-render even after tracking fired.
+     *
+     * Unlike `toJSON()`, values keep their runtime types (a `Date` stays a `Date`,
+     * a json field stays its parsed object) and wire-noise keys
+     * (`__class`/`clientId`/`syncStatus`) are omitted — this is exactly the row
+     * the schema's `T` describes. Computed relations (`referenceModel`/
+     * `referenceCollection`) and ephemeral fields are skipped, matching `toJSON`'s
+     * row projection; they're lazy/recursive and not part of the row's data.
+     */
+    toReactiveSnapshot() {
+        const snapshot = {
+            id: this.id,
+            createdAt: this.createdAt,
+            updatedAt: this.updatedAt,
+        };
+        if (this.archivedAt !== undefined)
+            snapshot.archivedAt = this.archivedAt;
+        const properties = getActiveRegistry().getProperties(this.getModelName());
+        if (properties) {
+            const self = this;
+            for (const [propName, metadata] of properties) {
+                if (metadata.type === 'ephemeralProperty' ||
+                    metadata.type === 'referenceModel' ||
+                    metadata.type === 'referenceCollection') {
+                    continue;
+                }
+                // Reading through the observable getter is the point: it subscribes the
+                // enclosing MobX reaction to this field.
+                snapshot[propName] = self[propName];
+            }
+        }
+        return snapshot;
+    }
     /**
      * Get field changes for activity tracking
      */

package/dist/cli.cjs

@@ -276847,7 +276847,7 @@ var ERROR_CODES = {
   unique_violation: wire("conflict", 409, false, "A value violates a uniqueness constraint."),
   check_violation: wire("validation", 400, false, "A value violates a database check constraint."),
   constraint_violation: wire("validation", 400, false, "A database integrity constraint was violated."),
-  column_type_mismatch: wire("validation", 400, false, 'A structured (JSON) value was written to a column whose database type is not jsonb. The column was not provisioned as jsonb (often a pre-existing column adopted by `ablo push`); storing the value would silently corrupt it to "[object Object]". Run `ablo migrate` to alter the column to jsonb.'),
+  column_type_mismatch: wire("validation", 400, false, "A structured (JSON) value was written to a column whose database type cannot hold it. Ablo adapts a json field to either a jsonb column (native) or a text column (serialized) \u2014 but a scalar column (integer, boolean, uuid, timestamp, \u2026) cannot store a JSON object or array. Use a jsonb or text column for this field. Ablo adapts to your column; it does not alter your schema."),
   // ── tenant / unknown model (400) ───────────────────────────────────
   server_execute_unknown_model: wire("tenant", 400, false, "Wrote to a model the server does not know. The server keeps its own copy of the schema \u2014 run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` before writing to new or changed models."),
   mutate_create_unknown_model: wire("tenant", 400, false, "Created a model the server does not know. Run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` first \u2014 the server keeps its own copy of the schema."),

package/dist/client/Ablo.js

@@ -240,8 +240,19 @@ function registerModelsFromSchema(schema, registry) {
                 jsonSubFields.push({ fieldName, subSchema: inner });
             }
         }
-        // Create a dynamic Model subclass with JSON sub-property getters
-        const isLazy = modelDef.lazyObservable === true;
+        // Create a dynamic Model subclass with JSON sub-property getters.
+        //
+        // Field-level MobX observability is ON BY DEFAULT. A reactive read like
+        // `useAblo((a) => a.documents.get(id))` must re-render when a remote delta
+        // mutates the row IN PLACE (the common collaborative case); without
+        // per-field observability that update fires no reaction and the UI silently
+        // goes stale. Models opt OUT with an explicit `lazyObservable: false` —
+        // appropriate only for very large read-only list models where per-field
+        // atoms cost more than the QueryView's entry-replaced reactivity already
+        // provides. json fields register as `observable.ref` (see
+        // `registerModelsFromSchema`), so the default is ~one atom per scalar field
+        // per loaded row — cheap — not a deep atom tree per blob.
+        const isLazy = modelDef.lazyObservable !== false;
         // Base provenance fields (`organizationId`, `createdBy`) live in
         // `baseFieldsSchema`, not the per-model `shape`. The server stamps + emits
         // them (camelCased on the wire), but hydration (`Model.assignFieldsFromData`)

package/dist/errorCodes.js

@@ -202,7 +202,7 @@ export const ERROR_CODES = {
     unique_violation: wire('conflict', 409, false, 'A value violates a uniqueness constraint.'),
     check_violation: wire('validation', 400, false, 'A value violates a database check constraint.'),
     constraint_violation: wire('validation', 400, false, 'A database integrity constraint was violated.'),
-    column_type_mismatch: wire('validation', 400, false, 'A structured (JSON) value was written to a column whose database type is not jsonb. The column was not provisioned as jsonb (often a pre-existing column adopted by `ablo push`); storing the value would silently corrupt it to "[object Object]". Run `ablo migrate` to alter the column to jsonb.'),
+    column_type_mismatch: wire('validation', 400, false, 'A structured (JSON) value was written to a column whose database type cannot hold it. Ablo adapts a json field to either a jsonb column (native) or a text column (serialized) — but a scalar column (integer, boolean, uuid, timestamp, …) cannot store a JSON object or array. Use a jsonb or text column for this field. Ablo adapts to your column; it does not alter your schema.'),
     // ── tenant / unknown model (400) ───────────────────────────────────
     server_execute_unknown_model: wire('tenant', 400, false, 'Wrote to a model the server does not know. The server keeps its own copy of the schema — run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` before writing to new or changed models.'),
     mutate_create_unknown_model: wire('tenant', 400, false, 'Created a model the server does not know. Run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` first — the server keeps its own copy of the schema.'),

package/dist/index.d.ts

@@ -82,3 +82,4 @@ export type { ModelVerb, ListOptionKey, AbloOptionKey } from './surface.js';
 export type { Register, DefaultSyncShape } from './types/global.js';
 export { defineMutators } from './mutators/defineMutators.js';
 export { createTransaction, type Transaction } from './mutators/Transaction.js';
+export { deepEqual, stableStringify } from './utils/json.js';

package/dist/index.js

@@ -134,3 +134,9 @@ export { defineMutators } from './mutators/defineMutators.js';
 export { createTransaction } from './mutators/Transaction.js';
 // Undo runtime is intentionally not part of the public root surface. App code
 // uses `useUndoScope` from `@abloatai/ablo/react`.
+// JSON comparison helpers. A `field.json()` value backed by a Postgres `jsonb`
+// column round-trips with reordered object keys (jsonb doesn't preserve key
+// order), so a naive `JSON.stringify(a) === JSON.stringify(b)` guard misfires
+// when an app reconciles an Ablo row against external editor state. Use these
+// (key-order-insensitive) instead. See `utils/json.ts` for the full rationale.
+export { deepEqual, stableStringify } from './utils/json.js';

package/dist/mutators/undoApply.d.ts

@@ -24,6 +24,7 @@
  */
 import type { SyncStoreContract } from '../react/context.js';
 import type { InverseOp } from './inverseOp.js';
+import { deepEqual } from '../utils/json.js';
 /**
  * How undo/redo handles a field a collaborator changed after your op:
  *   - `skip-stale` (default): leave it — your change is already superseded, so
@@ -33,8 +34,12 @@ import type { InverseOp } from './inverseOp.js';
  */
 export type UndoConflictPolicy = 'skip-stale' | 'last-writer-wins';
 export declare const DEFAULT_UNDO_CONFLICT_POLICY: UndoConflictPolicy;
-/** Structural equality for JSON-shaped values (scalars, arrays, plain objects). */
-export declare function deepEqual(a: unknown, b: unknown): boolean;
+/**
+ * Structural equality for JSON-shaped values (scalars, arrays, plain objects).
+ * Re-exported from the shared `utils/json` helper (key order is ignored) so the
+ * undo path and app authors share one implementation.
+ */
+export { deepEqual };
 /**
  * Filter the ops to apply so they don't clobber concurrent collaborator edits.
  * See the module docblock. `last-writer-wins` returns the ops unchanged.

package/dist/mutators/undoApply.js

@@ -22,42 +22,14 @@
  * With no collaborator, the live value always equals what you set, so nothing
  * is dropped — single-user undo is byte-for-byte unchanged.
  */
+import { deepEqual } from '../utils/json.js';
 export const DEFAULT_UNDO_CONFLICT_POLICY = 'skip-stale';
-/** Structural equality for JSON-shaped values (scalars, arrays, plain objects). */
-export function deepEqual(a, b) {
-    if (a === b)
-        return true;
-    if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') {
-        return false;
-    }
-    const aArr = Array.isArray(a);
-    if (aArr !== Array.isArray(b))
-        return false;
-    if (aArr) {
-        const av = a;
-        const bv = b;
-        if (av.length !== bv.length)
-            return false;
-        for (let i = 0; i < av.length; i++) {
-            if (!deepEqual(av[i], bv[i]))
-                return false;
-        }
-        return true;
-    }
-    const ao = a;
-    const bo = b;
-    const ak = Object.keys(ao);
-    const bk = Object.keys(bo);
-    if (ak.length !== bk.length)
-        return false;
-    for (const k of ak) {
-        if (!Object.prototype.hasOwnProperty.call(bo, k))
-            return false;
-        if (!deepEqual(ao[k], bo[k]))
-            return false;
-    }
-    return true;
-}
+/**
+ * Structural equality for JSON-shaped values (scalars, arrays, plain objects).
+ * Re-exported from the shared `utils/json` helper (key order is ignored) so the
+ * undo path and app authors share one implementation.
+ */
+export { deepEqual };
 /**
  * Map `id → { field: establishedValue }` from the paired ops. Only update-family
  * ops carry per-field values worth comparing.

package/dist/react/useAblo.js

@@ -2,7 +2,7 @@
 import { useContext, useEffect, useState } from 'react';
 import { AbloInternalContext } from './internalContext.js';
 import { getModelClientMeta } from '../client/createModelProxy.js';
-import { Model, modelAsRow } from '../Model.js';
+import { Model } from '../Model.js';
 import { useReactive } from './useReactive.js';
 const EMPTY_CLAIMS = Object.freeze([]);
 function readModelResult(engine, modelClient, id, initial) {
@@ -16,9 +16,19 @@ function readModelResult(engine, modelClient, id, initial) {
         : EMPTY_CLAIMS;
     return { data, claims, claimed: claims.length > 0 };
 }
+/**
+ * Project a reactive read into the value `useReactive` caches and returns.
+ *
+ * For a `Model`, this MUST read the row's fields (via `toReactiveSnapshot`),
+ * not return the bare instance: MobX tracks property access, so reading the
+ * fields inside this tracked function is what subscribes the reaction to them —
+ * and the fresh object identity lets `useReactive`'s equality detect an
+ * in-place delta update. Returning `modelAsRow(value)` (the live instance, no
+ * field read) is why `useAblo(a => a.x.get(id))` used to ignore remote edits.
+ */
 function snapshotValue(value) {
     if (value instanceof Model) {
-        return modelAsRow(value);
+        return value.toReactiveSnapshot();
     }
     if (Array.isArray(value)) {
         return value.map((item) => snapshotValue(item));

package/dist/schema/ddl.d.ts

@@ -65,42 +65,6 @@ export declare function snakeToCamel(identifier: string): string;
 /** Quote an identifier (defense-in-depth; inputs are already slug/snake). */
 export declare function q(identifier: string): string;
 export declare function sqlType(fieldType: ModelJSON['fields'][string]['type']): string;
-/**
- * Detect and repair `field.json()` columns that exist in the live database as a
- * NON-jsonb type, and emit a salvaging in-place `ALTER … TYPE jsonb`.
- *
- * Why this is needed: provisioning uses `ADD COLUMN IF NOT EXISTS` and
- * `CREATE TABLE IF NOT EXISTS` (idempotent by design). When `ablo push` adopts
- * a table/column that PRE-EXISTS with a different type — e.g. a `content TEXT`
- * column from a legacy table — the additive DDL is a no-op and the column
- * silently stays `text`. The pure schema-to-schema differ
- * ({@link generateMigrationPlan}) can't see this: the schema says `json` on
- * both sides, so it emits no change. The drift is only visible by INTROSPECTING
- * the live database and comparing to the declared type — the drizzle-kit
- * `pull` discipline. A `json` value bound to a `text` column corrupts to the
- * literal `"[object Object]"`, so leaving the drift unrepaired is silent data
- * loss.
- *
- * The cast is SALVAGING, never aborting (Postgres won't auto-cast text→jsonb;
- * invalid rows would otherwise fail the whole ALTER): a row that `IS JSON`
- * parses to jsonb, anything else (including already-corrupted
- * `"[object Object]"`) is wrapped as a jsonb string via `to_jsonb`, and NULL
- * stays NULL. The `IS JSON` predicate requires Postgres 16+ (the fleet runs
- * 17); on an older engine the ALTER fails LOUD with a structured
- * `migration_failed` rather than silently — acceptable, since silent corruption
- * is the thing we're eliminating. See
- * https://echobind.com/post/safely-alter-postgres-columns-with-using.
- *
- * Pure + idempotent: emits a statement ONLY for a json field whose live column
- * type is present and not already `jsonb`/`json`. A correctly-provisioned schema
- * yields zero statements, so this is a no-op on every push after the first
- * repair. Columns absent from `liveColumnTypes` are left to the additive
- * provisioner (which adds them as jsonb).
- *
- * @param liveColumnTypes table name → (column name → information_schema
- *   `data_type`), as introspected from the target schema.
- */
-export declare function generateJsonColumnReconciliation(schema: SchemaJSON, liveColumnTypes: ReadonlyMap<string, ReadonlyMap<string, string>>, targetSchema: string): string[];
 /**
  * Build the additive, idempotent provisioning plan for an app. Pure — no DB
  * access.

package/dist/schema/ddl.js

@@ -66,72 +66,6 @@ export function sqlType(fieldType) {
     }
 }
 const BASE_COLUMNS = new Set(['id', 'organization_id', 'created_by', 'created_at', 'updated_at']);
-// ── JSON column drift reconciliation ─────────────────────────────────────────
-/**
- * Detect and repair `field.json()` columns that exist in the live database as a
- * NON-jsonb type, and emit a salvaging in-place `ALTER … TYPE jsonb`.
- *
- * Why this is needed: provisioning uses `ADD COLUMN IF NOT EXISTS` and
- * `CREATE TABLE IF NOT EXISTS` (idempotent by design). When `ablo push` adopts
- * a table/column that PRE-EXISTS with a different type — e.g. a `content TEXT`
- * column from a legacy table — the additive DDL is a no-op and the column
- * silently stays `text`. The pure schema-to-schema differ
- * ({@link generateMigrationPlan}) can't see this: the schema says `json` on
- * both sides, so it emits no change. The drift is only visible by INTROSPECTING
- * the live database and comparing to the declared type — the drizzle-kit
- * `pull` discipline. A `json` value bound to a `text` column corrupts to the
- * literal `"[object Object]"`, so leaving the drift unrepaired is silent data
- * loss.
- *
- * The cast is SALVAGING, never aborting (Postgres won't auto-cast text→jsonb;
- * invalid rows would otherwise fail the whole ALTER): a row that `IS JSON`
- * parses to jsonb, anything else (including already-corrupted
- * `"[object Object]"`) is wrapped as a jsonb string via `to_jsonb`, and NULL
- * stays NULL. The `IS JSON` predicate requires Postgres 16+ (the fleet runs
- * 17); on an older engine the ALTER fails LOUD with a structured
- * `migration_failed` rather than silently — acceptable, since silent corruption
- * is the thing we're eliminating. See
- * https://echobind.com/post/safely-alter-postgres-columns-with-using.
- *
- * Pure + idempotent: emits a statement ONLY for a json field whose live column
- * type is present and not already `jsonb`/`json`. A correctly-provisioned schema
- * yields zero statements, so this is a no-op on every push after the first
- * repair. Columns absent from `liveColumnTypes` are left to the additive
- * provisioner (which adds them as jsonb).
- *
- * @param liveColumnTypes table name → (column name → information_schema
- *   `data_type`), as introspected from the target schema.
- */
-export function generateJsonColumnReconciliation(schema, liveColumnTypes, targetSchema) {
-    const qs = q(targetSchema);
-    const statements = [];
-    for (const [key, model] of Object.entries(schema.models)) {
-        const table = model.tableName ?? key;
-        const liveCols = liveColumnTypes.get(table);
-        if (!liveCols)
-            continue; // table not provisioned yet — nothing to reconcile
-        const qt = `${qs}.${q(table)}`;
-        for (const [fieldName, meta] of Object.entries(model.fields)) {
-            if (meta.type !== 'json')
-                continue;
-            const col = meta.column ?? camelToSnake(fieldName);
-            const liveType = liveCols.get(col);
-            if (liveType === undefined)
-                continue; // column absent — provisioner adds jsonb
-            if (liveType === 'jsonb' || liveType === 'json')
-                continue; // already correct
-            const c = q(col);
-            statements.push(`ALTER TABLE ${qt} ALTER COLUMN ${c} TYPE jsonb USING (\n` +
-                `  CASE\n` +
-                `    WHEN ${c} IS NULL THEN NULL\n` +
-                `    WHEN ${c}::text IS JSON THEN ${c}::text::jsonb\n` +
-                `    ELSE to_jsonb(${c}::text)\n` +
-                `  END\n` +
-                `);`);
-        }
-    }
-    return statements;
-}
 // ── Foreign keys (relation-driven, sync-safe) ────────────────────────────────
 /**
  * A Postgres-identifier-safe constraint name ≤63 bytes. When the natural

package/dist/schema/index.d.ts

@@ -33,7 +33,7 @@ export { mutable, readOnly, type SugarOptions } from './sugar.js';
 export { defineSchema, composeIdentitySyncGroups, type Schema, type SchemaRecord, type Model, type InferModel, type InferCreate, type InferModelNames, type BaseModelFields, type InsertValue, type UpsertValue, type UpdateValue, type DeleteId, type DefineSchemaOptions, type Casing, type CasingConvention, type CasingFn, composeEntitySyncGroups, type IdentityRole, type IdentityContext, type IdentityRoleSource, type EntityRole, type EntityContext, type EntityRoleSource, type RoleSource, type RoleContext, type SyncGroup, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, type GroupsInput, } from './schema.js';
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, type SchemaJSON, type ModelJSON, type RelationJSON, } from './serialize.js';
 export { selectModels } from './select.js';
-export { generateProvisionPlan, generateMigrationPlan, generateJsonColumnReconciliation, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, type ProvisionPlan, type MigrationPlan, } from './ddl.js';
+export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, type ProvisionPlan, type MigrationPlan, } from './ddl.js';
 export { diffSchema, classifyMigration, classifyCast, isAutoApplicable, isBlockerResolved, unresolvedBlockers, type BackfillValue, type MigrationStep, type FieldChanges, type FieldColumnChange, type FieldTypeChange, type NullabilityChange, type EnumValuesChange, type IndexChange, type CastSafety, type FieldType, type RenameHints, type MigrationSignal, type MigrationClassification, type WarningCode, type BlockerCode, } from './diff.js';
 export { generateTypes } from './generate.js';
 export { query, defineQueries, type QueryDef, type QueryRecord, type Queries, type InferQueryInput, type InferQueryResult, } from './queries.js';

package/dist/schema/index.js

@@ -55,7 +55,7 @@ export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash,
 // Schema projection — derive an app's subset from one canonical schema.
 export { selectModels } from './select.js';
 // Schema → Postgres DDL (pure; shared by the hosted server and the CLI)
-export { generateProvisionPlan, generateMigrationPlan, generateJsonColumnReconciliation, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, } from './ddl.js';
+export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, } from './ddl.js';
 // Schema diff + migration planning (pure; SQL emission lowered by ddl.ts)
 export { diffSchema, classifyMigration, classifyCast, isAutoApplicable, isBlockerResolved, unresolvedBlockers, } from './diff.js';
 // Schema → TypeScript type emission (the `generate` half; pure)

package/dist/schema/sugar.js

@@ -66,7 +66,10 @@ function build(shape, opts, baseline) {
  *   - `.manual`   — never auto-loaded; explicit queries only
  */
 export const mutable = {
-    instant: (shape, opts) => build(shape, opts, { mutable: true, load: 'instant', lazyObservable: false }),
+    instant: (shape, opts) => 
+    // Reactive by default (see readonly.instant note): opt out with
+    // `lazyObservable: false` only for very large read-only list models.
+    build(shape, opts, { mutable: true, load: 'instant', lazyObservable: true }),
     lazy: (shape, opts) => build(shape, opts, { mutable: true, load: 'lazy', lazyObservable: true }),
     manual: (shape, opts) => build(shape, opts, { mutable: true, load: 'manual', lazyObservable: true }),
 };
@@ -82,7 +85,12 @@ export const mutable = {
  *     writes
  */
 export const readOnly = {
-    instant: (shape, opts) => build(shape, opts, { mutable: false, load: 'instant', lazyObservable: false }),
+    instant: (shape, opts) => 
+    // Reactive by default (like every variant now): a remote delta that mutates
+    // a row in place must re-render reactive reads. Opt out per-model with
+    // `lazyObservable: false` for very large read-only lists where per-field
+    // atoms cost more than the QueryView's entry-replaced reactivity.
+    build(shape, opts, { mutable: false, load: 'instant', lazyObservable: true }),
     lazy: (shape, opts) => build(shape, opts, { mutable: false, load: 'lazy', lazyObservable: true }),
     /**
      * Internal-only: never auto-loaded, never written by clients. The

package/dist/server/read-config.d.ts

@@ -57,4 +57,11 @@ export interface BootstrapModel {
     fieldColumns?: Record<string, string>;
     /** Physical-column aliases needed after SELECT * for `.from(...)` fields. */
     columnOverrides?: readonly ColumnOverride[];
+    /**
+     * Physical columns the schema declares as `json` (`field.json()`). A json
+     * field stored in a TEXT column comes back from `row_to_json` as a serialized
+     * string; the bootstrap re-parses these so the wire is the canonical object
+     * regardless of physical column type (jsonb returns objects natively → no-op).
+     */
+    jsonColumns?: readonly string[];
 }

package/dist/utils/json.d.ts

@@ -0,0 +1,39 @@
+/**
+ * json.ts — key-order-insensitive comparison helpers for JSON-shaped values.
+ *
+ * Why this exists as a first-class, exported util:
+ *
+ * A `field.json()` value may be backed by a Postgres `jsonb` column, and **jsonb
+ * does not preserve object key order** (it reorders keys by length, then
+ * bytewise, and drops insignificant whitespace — see
+ * https://www.postgresql.org/docs/current/datatype-json.html). So a document an
+ * app wrote as `{type,text}` streams back in a delta as `{text,type}`: the same
+ * value, a different serialization.
+ *
+ * That bites any app that reconciles an Ablo row against an *external* state
+ * container it doesn't control — a rich-text editor (Tiptap/ProseMirror/Slate),
+ * a `useState`, a form buffer. The natural guard, `JSON.stringify(remote) ===
+ * JSON.stringify(local)`, is silently wrong because the two sides serialize keys
+ * in different orders, so it never matches — and the app re-applies the remote
+ * value on every render, clobbering in-flight edits and fighting the cursor.
+ *
+ * The fix is to compare order-insensitively. `deepEqual` does structural
+ * equality directly; `stableStringify` produces a canonical string (recursively
+ * sorted keys) for when you need a stable cache key / dependency value. The SDK
+ * already uses `deepEqual` internally for store-level echo detection; this
+ * module makes the same guarantee available to app authors so they don't each
+ * reinvent it.
+ *
+ * (If you need byte-exact key order preserved end-to-end, store the field in a
+ * `text` column instead of `jsonb` — Ablo's adaptive codec serializes verbatim
+ * there, matching Postgres's `json` type behavior.)
+ */
+/** Structural equality for JSON-shaped values (scalars, arrays, plain objects); key order is ignored. */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/**
+ * Canonical JSON serialization: recursively sorts object keys so two values that
+ * differ only in key order (e.g. a jsonb round-trip) produce the same string.
+ * Use this when you need a comparable/cacheable string rather than a boolean —
+ * e.g. an echo guard or a `useEffect`/`useMemo` dependency.
+ */
+export declare function stableStringify(value: unknown): string;

package/dist/utils/json.js

@@ -0,0 +1,88 @@
+/**
+ * json.ts — key-order-insensitive comparison helpers for JSON-shaped values.
+ *
+ * Why this exists as a first-class, exported util:
+ *
+ * A `field.json()` value may be backed by a Postgres `jsonb` column, and **jsonb
+ * does not preserve object key order** (it reorders keys by length, then
+ * bytewise, and drops insignificant whitespace — see
+ * https://www.postgresql.org/docs/current/datatype-json.html). So a document an
+ * app wrote as `{type,text}` streams back in a delta as `{text,type}`: the same
+ * value, a different serialization.
+ *
+ * That bites any app that reconciles an Ablo row against an *external* state
+ * container it doesn't control — a rich-text editor (Tiptap/ProseMirror/Slate),
+ * a `useState`, a form buffer. The natural guard, `JSON.stringify(remote) ===
+ * JSON.stringify(local)`, is silently wrong because the two sides serialize keys
+ * in different orders, so it never matches — and the app re-applies the remote
+ * value on every render, clobbering in-flight edits and fighting the cursor.
+ *
+ * The fix is to compare order-insensitively. `deepEqual` does structural
+ * equality directly; `stableStringify` produces a canonical string (recursively
+ * sorted keys) for when you need a stable cache key / dependency value. The SDK
+ * already uses `deepEqual` internally for store-level echo detection; this
+ * module makes the same guarantee available to app authors so they don't each
+ * reinvent it.
+ *
+ * (If you need byte-exact key order preserved end-to-end, store the field in a
+ * `text` column instead of `jsonb` — Ablo's adaptive codec serializes verbatim
+ * there, matching Postgres's `json` type behavior.)
+ */
+/** Structural equality for JSON-shaped values (scalars, arrays, plain objects); key order is ignored. */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') {
+        return false;
+    }
+    const aArr = Array.isArray(a);
+    if (aArr !== Array.isArray(b))
+        return false;
+    if (aArr) {
+        const av = a;
+        const bv = b;
+        if (av.length !== bv.length)
+            return false;
+        for (let i = 0; i < av.length; i++) {
+            if (!deepEqual(av[i], bv[i]))
+                return false;
+        }
+        return true;
+    }
+    const ao = a;
+    const bo = b;
+    const ak = Object.keys(ao);
+    const bk = Object.keys(bo);
+    if (ak.length !== bk.length)
+        return false;
+    for (const k of ak) {
+        if (!Object.prototype.hasOwnProperty.call(bo, k))
+            return false;
+        if (!deepEqual(ao[k], bo[k]))
+            return false;
+    }
+    return true;
+}
+/**
+ * Canonical JSON serialization: recursively sorts object keys so two values that
+ * differ only in key order (e.g. a jsonb round-trip) produce the same string.
+ * Use this when you need a comparable/cacheable string rather than a boolean —
+ * e.g. an echo guard or a `useEffect`/`useMemo` dependency.
+ */
+export function stableStringify(value) {
+    return JSON.stringify(sortKeysDeep(value));
+}
+function sortKeysDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeysDeep);
+    if (value && typeof value === 'object') {
+        const source = value;
+        return Object.keys(source)
+            .sort()
+            .reduce((acc, key) => {
+            acc[key] = sortKeysDeep(source[key]);
+            return acc;
+        }, {});
+    }
+    return value;
+}

package/package.json

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