@abloatai/humans 0.58.0 → 0.59.0

package/dist/local/Model.js

@@ -189,7 +189,16 @@ export class Model {
      * Track property changes
      */
     propertyChanged(propertyName, oldValue, newValue) {
-        if (oldValue === newValue)
+        // `createdAt` and `updatedAt` are server-managed bookkeeping, not
+        // user-authored model changes. In particular, every real field change
+        // advances `updatedAt` below. When a schema explicitly declares that
+        // timestamp, MobX observes the assignment and calls this method again;
+        // treating that callback as another edit recursively stamps `updatedAt`
+        // until the stack overflows. Ignore both timestamps at this boundary so
+        // they remain observable without entering the mutation payload.
+        if (oldValue === newValue ||
+            propertyName === 'createdAt' ||
+            propertyName === 'updatedAt')
             return;
         runInAction(() => {
             // Preserve the earliest captured `old` for this field until the entry

package/dist/local/client/schemaConfig.js

@@ -176,6 +176,7 @@ export function deriveConfigFromSchema(schema) {
         // the client compares only the models it declares, so an additive server
         // change stays silent and a real divergence names the exact models.
         expectedModelHashes: Object.fromEntries(Object.entries(toSchemaJSON(schema).models).map(([key, model]) => [key, modelHash(model)])),
+        expectedModelShapes: Object.fromEntries(Object.entries(toSchemaJSON(schema).models).map(([key, model]) => [key, Object.fromEntries(Object.entries(model.fields).map(([field, meta]) => [field, { type: meta.type, isOptional: meta.isOptional }]))])),
         // For a projection (`selectModels`/`omitModels`), also carry the full source
         // schema's hash. The drift check accepts a server match on either hash, so a
         // subset client stays quiet against a server running its full source schema.

package/dist/local/interfaces/index.d.ts

@@ -289,6 +289,11 @@ export interface RuntimeConfig {
      * Advisory, like the hashes above.
      */
     expectedModelHashes?: Readonly<Record<string, string>>;
+    /** Field shapes paired with expectedModelHashes so drift can name direction, not just a model. */
+    expectedModelShapes?: Readonly<Record<string, Readonly<Record<string, {
+        readonly type: string;
+        readonly isOptional: boolean;
+    }>>>>;
 }
 /**
  * Extends the WebSocket event map with your own collaboration events, such as

package/dist/local/sync/BootstrapFetcher.js

@@ -161,14 +161,14 @@ export class BootstrapFetcher {
         // network hiccup). Fire-and-forget: never blocks or fails the bootstrap.
         const clientModels = this.runtime.config.expectedModelHashes;
         if (clientModels && Object.keys(clientModels).length > 0) {
-            void this.resolveSemanticDrift(clientModels, clientHash, serverHash, where);
+            void this.resolveSemanticDrift(clientModels, clientHash, serverHash, where, this.runtime.config.expectedModelShapes);
             return;
         }
         this.warnWholeHashDrift(clientHash, serverHash, where);
     }
     /** Fetch the server's per-model schema surface and warn precisely — or stay
      *  silent when every model this client declares matches (additive lead). */
-    async resolveSemanticDrift(clientModels, clientHash, serverHash, where) {
+    async resolveSemanticDrift(clientModels, clientHash, serverHash, where, clientShapes) {
         try {
             const res = await fetch(`${this.options.baseUrl}/schema`, {
                 method: 'GET',
@@ -181,11 +181,11 @@ export class BootstrapFetcher {
                 ? body.models.flatMap((m) => {
                     const entry = m;
                     return typeof entry.key === 'string'
-                        ? [{ key: entry.key, ...(typeof entry.hash === 'string' ? { hash: entry.hash } : {}) }]
+                        ? [{ key: entry.key, ...(typeof entry.hash === 'string' ? { hash: entry.hash } : {}), ...(entry.fields && typeof entry.fields === 'object' ? { fields: entry.fields } : {}) }]
                         : [];
                 })
                 : [];
-            const finding = classifySchemaDrift(clientModels, models);
+            const finding = classifySchemaDrift(clientModels, models, clientShapes);
             if (finding.kind === 'aligned')
                 return; // additive server lead — not this client's concern
             if (finding.kind !== 'unknown') {

package/dist/local/sync/schemaDrift.d.ts

@@ -19,6 +19,16 @@ export interface ServerSchemaModel {
     readonly key: string;
     /** Per-model content hash; absent on servers older than this check. */
     readonly hash?: string;
+    readonly fields?: Readonly<Record<string, {
+        readonly type: string;
+        readonly isOptional: boolean;
+    }>>;
+}
+export interface SchemaFieldDrift {
+    readonly model: string;
+    readonly field: string;
+    readonly direction: 'client_only' | 'active_only' | 'changed';
+    readonly detail: string;
 }
 export type SchemaDriftFinding = 
 /** Every model this client declares exists server-side with matching content
@@ -38,13 +48,17 @@ export type SchemaDriftFinding =
     readonly kind: 'changed';
     readonly models: readonly string[];
     readonly unpushed: readonly string[];
+    readonly fields?: readonly SchemaFieldDrift[];
 }
 /** The server surface carries no per-model hashes (older server) — the
  *  caller falls back to the whole-hash comparison. */
  | {
     readonly kind: 'unknown';
 };
-export declare function classifySchemaDrift(clientModels: Readonly<Record<string, string>>, serverModels: readonly ServerSchemaModel[]): SchemaDriftFinding;
+export declare function classifySchemaDrift(clientModels: Readonly<Record<string, string>>, serverModels: readonly ServerSchemaModel[], clientShapes?: Readonly<Record<string, Readonly<Record<string, {
+    readonly type: string;
+    readonly isOptional: boolean;
+}>>>>): SchemaDriftFinding;
 /**
  * The warning for a real, named divergence. Calm and specific: which models,
  * what that means for this client, and the one next step. Never speaks about

package/dist/local/sync/schemaDrift.js

@@ -14,22 +14,38 @@
  *
  * Pure and transport-free; the BootstrapFetcher owns fetching the surface.
  */
-export function classifySchemaDrift(clientModels, serverModels) {
+import { reconcileClientToActive } from '@abloatai/transaction/schema';
+export function classifySchemaDrift(clientModels, serverModels, clientShapes = {}) {
     if (serverModels.length > 0 && serverModels.every((m) => !m.hash)) {
         return { kind: 'unknown' };
     }
     const server = new Map(serverModels.map((m) => [m.key, m.hash]));
     const unpushed = [];
     const changed = [];
+    const fields = [];
     for (const [key, hash] of Object.entries(clientModels)) {
         const serverHash = server.get(key);
         if (serverHash === undefined)
             unpushed.push(key);
-        else if (serverHash !== hash)
+        else if (serverHash !== hash) {
             changed.push(key);
+            const clientFields = clientShapes[key];
+            const activeFields = serverModels.find((model) => model.key === key)?.fields;
+            if (clientFields && activeFields)
+                for (const field of new Set([...Object.keys(clientFields), ...Object.keys(activeFields)])) {
+                    const client = clientFields[field];
+                    const active = activeFields[field];
+                    if (!active)
+                        fields.push({ model: key, field, direction: 'client_only', detail: 'present in this build but absent from the active schema' });
+                    else if (!client)
+                        fields.push({ model: key, field, direction: 'active_only', detail: 'present in the active schema but absent from this build' });
+                    else if (client.type !== active.type || client.isOptional !== active.isOptional)
+                        fields.push({ model: key, field, direction: 'changed', detail: `${client.type}${client.isOptional ? ' optional' : ' required'} in this build and ${active.type}${active.isOptional ? ' optional' : ' required'} in the active schema` });
+                }
+        }
     }
     if (changed.length > 0)
-        return { kind: 'changed', models: changed, unpushed };
+        return { kind: 'changed', models: changed, unpushed, ...(fields.length ? { fields } : {}) };
     if (unpushed.length > 0)
         return { kind: 'unpushed', models: unpushed };
     return { kind: 'aligned' };
@@ -40,14 +56,15 @@ export function classifySchemaDrift(clientModels, serverModels) {
  * hashes — the point of the semantic check is that nobody has to compare hex.
  */
 export function describeSchemaDrift(finding, serverLabel) {
-    if (finding.kind === 'unpushed') {
-        return (`Ablo: This build declares models the server at ${serverLabel} doesn't have yet ` +
-            `(${finding.models.join(', ')}). Writes to them will be declined until the schema is ` +
-            `pushed — run \`ablo push\` (and \`ablo status\` to confirm it targets this server).`);
-    }
-    const alsoUnpushed = finding.unpushed.length > 0 ? ` (${finding.unpushed.join(', ')} not pushed yet)` : '';
-    return (`Ablo: These models differ between this build and the server at ${serverLabel}: ` +
-        `${finding.models.join(', ')}${alsoUnpushed}. Reads and writes touching what changed may be ` +
-        `declined — \`ablo status\` shows the deployed shape; pushing your schema or deploying a ` +
-        `current build aligns them.`);
+    const findings = finding.kind === 'unpushed'
+        ? reconcileClientToActive([], finding.models, serverLabel)
+        : reconcileClientToActive(finding.models, finding.unpushed, serverLabel, finding.fields ?? []);
+    const changed = findings.filter(({ code }) => code === 'model_changed').map(({ model }) => model).filter(Boolean);
+    const unpushed = findings.filter(({ code }) => code === 'model_unpushed').map(({ model }) => model).filter(Boolean);
+    const summary = [
+        ...findings.filter(({ field }) => field !== undefined).map(({ message }) => message),
+        ...(changed.length ? [`Models ${changed.join(', ')} differ between this build and the active schema at ${serverLabel}.`] : []),
+        ...(unpushed.length ? [`Models ${unpushed.join(', ')} are declared by this build but are not active at ${serverLabel}.`] : []),
+    ];
+    return `Ablo: ${summary.join(' ')} ${findings.map(({ action }) => action).filter((value, index, all) => all.indexOf(value) === index).join(' ')}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/humans",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "description": "The optional human-facing local-state package for Ablo: presence, live queries, and React bindings.",
   "license": "Apache-2.0",
   "type": "module",
@@ -84,7 +84,7 @@
     "directory": "packages/humans"
   },
   "dependencies": {
-    "@abloatai/transaction": "^0.58.0",
+    "@abloatai/transaction": "^0.59.0",
     "mobx": "^6.13.7",
     "uuid": "^11.1.0",
     "zod": "^4.4.3"

package/src/local/Model.ts

@@ -281,7 +281,18 @@ export abstract class Model {
    * Track property changes
    */
   propertyChanged(propertyName: string, oldValue: unknown, newValue: unknown): void {
-    if (oldValue === newValue) return;
+    // `createdAt` and `updatedAt` are server-managed bookkeeping, not
+    // user-authored model changes. In particular, every real field change
+    // advances `updatedAt` below. When a schema explicitly declares that
+    // timestamp, MobX observes the assignment and calls this method again;
+    // treating that callback as another edit recursively stamps `updatedAt`
+    // until the stack overflows. Ignore both timestamps at this boundary so
+    // they remain observable without entering the mutation payload.
+    if (
+      oldValue === newValue ||
+      propertyName === 'createdAt' ||
+      propertyName === 'updatedAt'
+    ) return;
 
     runInAction(() => {
       // Preserve the earliest captured `old` for this field until the entry

package/src/local/client/schemaConfig.ts

@@ -185,6 +185,9 @@ export function deriveConfigFromSchema(schema: Schema): RuntimeConfig {
     expectedModelHashes: Object.fromEntries(
       Object.entries(toSchemaJSON(schema).models).map(([key, model]) => [key, modelHash(model)]),
     ),
+    expectedModelShapes: Object.fromEntries(
+      Object.entries(toSchemaJSON(schema).models).map(([key, model]) => [key, Object.fromEntries(Object.entries(model.fields).map(([field, meta]) => [field, { type: meta.type, isOptional: meta.isOptional }]))]),
+    ),
     // For a projection (`selectModels`/`omitModels`), also carry the full source
     // schema's hash. The drift check accepts a server match on either hash, so a
     // subset client stays quiet against a server running its full source schema.

package/src/local/interfaces/index.ts

@@ -436,6 +436,8 @@ export interface RuntimeConfig {
    * Advisory, like the hashes above.
    */
   expectedModelHashes?: Readonly<Record<string, string>>;
+  /** Field shapes paired with expectedModelHashes so drift can name direction, not just a model. */
+  expectedModelShapes?: Readonly<Record<string, Readonly<Record<string, { readonly type: string; readonly isOptional: boolean }>>>>;
 }
 
 // ─────────────────────────────────────────────

package/src/local/sync/BootstrapFetcher.ts

@@ -293,7 +293,7 @@ export class BootstrapFetcher {
     // network hiccup). Fire-and-forget: never blocks or fails the bootstrap.
     const clientModels = this.runtime.config.expectedModelHashes;
     if (clientModels && Object.keys(clientModels).length > 0) {
-      void this.resolveSemanticDrift(clientModels, clientHash, serverHash, where);
+      void this.resolveSemanticDrift(clientModels, clientHash, serverHash, where, this.runtime.config.expectedModelShapes);
       return;
     }
     this.warnWholeHashDrift(clientHash, serverHash, where);
@@ -306,6 +306,7 @@ export class BootstrapFetcher {
     clientHash: string,
     serverHash: string,
     where: string,
+    clientShapes: NonNullable<typeof this.runtime.config.expectedModelShapes> | undefined,
   ): Promise<void> {
     try {
       const res = await fetch(`${this.options.baseUrl}/schema`, {
@@ -316,13 +317,13 @@ export class BootstrapFetcher {
       const body = (await res.json()) as { models?: unknown };
       const models = Array.isArray(body.models)
         ? body.models.flatMap((m): ServerSchemaModel[] => {
-            const entry = m as { key?: unknown; hash?: unknown };
+            const entry = m as { key?: unknown; hash?: unknown; fields?: unknown };
             return typeof entry.key === 'string'
-              ? [{ key: entry.key, ...(typeof entry.hash === 'string' ? { hash: entry.hash } : {}) }]
+              ? [{ key: entry.key, ...(typeof entry.hash === 'string' ? { hash: entry.hash } : {}), ...(entry.fields && typeof entry.fields === 'object' ? { fields: entry.fields as ServerSchemaModel['fields'] } : {}) }]
               : [];
           })
         : [];
-      const finding = classifySchemaDrift(clientModels, models);
+      const finding = classifySchemaDrift(clientModels, models, clientShapes);
       if (finding.kind === 'aligned') return; // additive server lead — not this client's concern
       if (finding.kind !== 'unknown') {
         this.runtime.logger.warn(describeSchemaDrift(finding, where), {

package/src/local/sync/schemaDrift.ts

@@ -15,13 +15,18 @@
  * Pure and transport-free; the BootstrapFetcher owns fetching the surface.
  */
 
+import { reconcileClientToActive } from '@abloatai/transaction/schema';
+
 /** One model as the server's schema read-back reports it. */
 export interface ServerSchemaModel {
   readonly key: string;
   /** Per-model content hash; absent on servers older than this check. */
   readonly hash?: string;
+  readonly fields?: Readonly<Record<string, { readonly type: string; readonly isOptional: boolean }>>;
 }
 
+export interface SchemaFieldDrift { readonly model: string; readonly field: string; readonly direction: 'client_only' | 'active_only' | 'changed'; readonly detail: string; }
+
 export type SchemaDriftFinding =
   /** Every model this client declares exists server-side with matching content
    *  (the server may know more — that's an additive lead, not drift). */
@@ -35,6 +40,7 @@ export type SchemaDriftFinding =
       readonly kind: 'changed';
       readonly models: readonly string[];
       readonly unpushed: readonly string[];
+      readonly fields?: readonly SchemaFieldDrift[];
     }
   /** The server surface carries no per-model hashes (older server) — the
    *  caller falls back to the whole-hash comparison. */
@@ -43,6 +49,7 @@ export type SchemaDriftFinding =
 export function classifySchemaDrift(
   clientModels: Readonly<Record<string, string>>,
   serverModels: readonly ServerSchemaModel[],
+  clientShapes: Readonly<Record<string, Readonly<Record<string, { readonly type: string; readonly isOptional: boolean }>>>> = {},
 ): SchemaDriftFinding {
   if (serverModels.length > 0 && serverModels.every((m) => !m.hash)) {
     return { kind: 'unknown' };
@@ -50,12 +57,24 @@ export function classifySchemaDrift(
   const server = new Map(serverModels.map((m) => [m.key, m.hash]));
   const unpushed: string[] = [];
   const changed: string[] = [];
+  const fields: SchemaFieldDrift[] = [];
   for (const [key, hash] of Object.entries(clientModels)) {
     const serverHash = server.get(key);
     if (serverHash === undefined) unpushed.push(key);
-    else if (serverHash !== hash) changed.push(key);
+    else if (serverHash !== hash) {
+      changed.push(key);
+      const clientFields = clientShapes[key];
+      const activeFields = serverModels.find((model) => model.key === key)?.fields;
+      if (clientFields && activeFields) for (const field of new Set([...Object.keys(clientFields), ...Object.keys(activeFields)])) {
+        const client = clientFields[field];
+        const active = activeFields[field];
+        if (!active) fields.push({ model: key, field, direction: 'client_only', detail: 'present in this build but absent from the active schema' });
+        else if (!client) fields.push({ model: key, field, direction: 'active_only', detail: 'present in the active schema but absent from this build' });
+        else if (client.type !== active.type || client.isOptional !== active.isOptional) fields.push({ model: key, field, direction: 'changed', detail: `${client.type}${client.isOptional ? ' optional' : ' required'} in this build and ${active.type}${active.isOptional ? ' optional' : ' required'} in the active schema` });
+      }
+    }
   }
-  if (changed.length > 0) return { kind: 'changed', models: changed, unpushed };
+  if (changed.length > 0) return { kind: 'changed', models: changed, unpushed, ...(fields.length ? { fields } : {}) };
   if (unpushed.length > 0) return { kind: 'unpushed', models: unpushed };
   return { kind: 'aligned' };
 }
@@ -69,18 +88,15 @@ export function describeSchemaDrift(
   finding: Extract<SchemaDriftFinding, { kind: 'unpushed' | 'changed' }>,
   serverLabel: string,
 ): string {
-  if (finding.kind === 'unpushed') {
-    return (
-      `Ablo: This build declares models the server at ${serverLabel} doesn't have yet ` +
-      `(${finding.models.join(', ')}). Writes to them will be declined until the schema is ` +
-      `pushed — run \`ablo push\` (and \`ablo status\` to confirm it targets this server).`
-    );
-  }
-  const alsoUnpushed = finding.unpushed.length > 0 ? ` (${finding.unpushed.join(', ')} not pushed yet)` : '';
-  return (
-    `Ablo: These models differ between this build and the server at ${serverLabel}: ` +
-    `${finding.models.join(', ')}${alsoUnpushed}. Reads and writes touching what changed may be ` +
-    `declined — \`ablo status\` shows the deployed shape; pushing your schema or deploying a ` +
-    `current build aligns them.`
-  );
+  const findings = finding.kind === 'unpushed'
+    ? reconcileClientToActive([], finding.models, serverLabel)
+    : reconcileClientToActive(finding.models, finding.unpushed, serverLabel, finding.fields ?? []);
+  const changed = findings.filter(({ code }) => code === 'model_changed').map(({ model }) => model).filter(Boolean);
+  const unpushed = findings.filter(({ code }) => code === 'model_unpushed').map(({ model }) => model).filter(Boolean);
+  const summary = [
+    ...findings.filter(({ field }) => field !== undefined).map(({ message }) => message),
+    ...(changed.length ? [`Models ${changed.join(', ')} differ between this build and the active schema at ${serverLabel}.`] : []),
+    ...(unpushed.length ? [`Models ${unpushed.join(', ')} are declared by this build but are not active at ${serverLabel}.`] : []),
+  ];
+  return `Ablo: ${summary.join(' ')} ${findings.map(({ action }) => action).filter((value, index, all) => all.indexOf(value) === index).join(' ')}`;
 }