@abloatai/humans 0.58.0 → 0.59.1

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

@@ -141,7 +141,7 @@ import type { MutationOptions } from '@abloatai/transaction/client/resources/mut
  * `claim` are deliberately absent: both are resolved on the client before a write
  * is staged, so neither reaches this layer.
  */
-export type WriteOptions = Pick<MutationOptions, 'readAt' | 'idempotencyKey' | 'label' | 'fenceToken' | 'claimRef'>;
+export type WriteOptions = Pick<MutationOptions, 'readAt' | 'reads' | 'idempotencyKey' | 'label' | 'fenceToken' | 'claimRef'>;
 /** A single mutation within a batch. Its `options` travel with it so the server
  *  can cache and replay the operation for idempotent retries. */
 export interface MutationOperation {
@@ -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/dist/local/transactions/mutations/batchProcessing.js

@@ -1,5 +1,5 @@
 import { AbloError, AbloNotFoundError } from '@abloatai/transaction/errors';
-import { applyWriteOptions, normalizeModelKey, TX_TYPE_TO_MUTATION_OP } from './commitPayload.js';
+import { applyWriteOptions, collectQueuedReads, normalizeModelKey, TX_TYPE_TO_MUTATION_OP } from './commitPayload.js';
 export async function processBatch(ctx) {
     if (ctx.durableReplayBlock)
         return;
@@ -69,6 +69,7 @@ export async function processBatch(ctx) {
                         origin: 'model_batch',
                         operations: batchOps.map(({ op }) => op),
                         sourceMutationIds: ctx.sourceMutationIdsFor(batch),
+                        commitOptions: { reads: collectQueuedReads(batch) },
                         createdAt: Math.min(...batch.map((transaction) => transaction.createdAt)),
                         sealedAt: batch[0]?.commitEnvelope?.sealedAt ?? Date.now(),
                         sequence: batch[0]?.commitEnvelope?.sequence,
@@ -84,6 +85,9 @@ export async function processBatch(ctx) {
                     dispatchStarted = true;
                     const result = ctx.parseMutationCommitResult(await ctx.dispatchCommitBounded(operations, {
                         idempotencyKey: commitIdempotencyKey,
+                        ...(durableEnvelope.commitOptions.reads !== undefined
+                            ? { reads: durableEnvelope.commitOptions.reads }
+                            : {}),
                     }));
                     await ctx.persistDurableCommitAcceptance(durableEnvelope, result);
                     const lastSyncId = result.lastSyncId;

package/dist/local/transactions/mutations/commitPayload.d.ts

@@ -105,6 +105,8 @@ export interface QueuedMutation {
      */
     confirmation?: Promise<void>;
 }
+/** Merge per-write premises into the one batch-level read set sent on wire. */
+export declare function collectQueuedReads(transactions: readonly QueuedMutation[]): MutationOptions['reads'] | undefined;
 export declare const normalizeModelKey: (modelName: string) => string;
 export declare const stripModelSuffix: (modelName: string) => string;
 /**

package/dist/local/transactions/mutations/commitPayload.js

@@ -75,6 +75,20 @@ export function projectCommitPayload(modelName, source, opts, runtime = globalRu
     }
     return snapshotJsonValue(out, '$.input');
 }
+/** Merge per-write premises into the one batch-level read set sent on wire. */
+export function collectQueuedReads(transactions) {
+    const declared = transactions
+        .map((transaction) => transaction.writeOptions?.reads)
+        .filter((reads) => reads !== undefined);
+    if (declared.length === 0)
+        return undefined;
+    const unique = new Map();
+    for (const dependency of declared.flatMap((reads) => reads ?? [])) {
+        unique.set(JSON.stringify(dependency), dependency);
+    }
+    const reads = [...unique.values()];
+    return reads.length > 0 ? reads : null;
+}
 export const normalizeModelKey = (modelName) => modelName.replace('Model', '').toLowerCase();
 export const stripModelSuffix = (modelName) => modelName.replace('Model', '');
 /**

package/dist/local/transactions/mutations/pendingDrain.js

@@ -1,4 +1,4 @@
-import { applyWriteOptions, TX_TYPE_TO_MUTATION_OP } from './commitPayload.js';
+import { applyWriteOptions, collectQueuedReads, TX_TYPE_TO_MUTATION_OP } from './commitPayload.js';
 export async function drainPendingConfirmations(ctx) {
     ctx.assertDurableReplayOpen();
     // Kick the commit lane too: atomic envelopes from `commits.create()` may
@@ -39,6 +39,7 @@ export async function drainPendingConfirmations(ctx) {
                 origin: 'model_batch',
                 operations: projectedOperations,
                 sourceMutationIds: ctx.sourceMutationIdsFor(batch),
+                commitOptions: { reads: collectQueuedReads(batch) },
                 createdAt: Math.min(...batch.map((transaction) => transaction.createdAt)),
                 sealedAt: batch[0]?.commitEnvelope?.sealedAt ?? Date.now(),
                 sequence: batch[0]?.commitEnvelope?.sequence,
@@ -46,6 +47,9 @@ export async function drainPendingConfirmations(ctx) {
             ctx.assertEnvelopeInsideReplayWindow(durableEnvelope);
             const result = ctx.parseMutationCommitResult(await ctx.dispatchCommitBounded(durableEnvelope.operations, {
                 idempotencyKey,
+                ...(durableEnvelope.commitOptions.reads !== undefined
+                    ? { reads: durableEnvelope.commitOptions.reads }
+                    : {}),
             }));
             await ctx.persistDurableCommitAcceptance(durableEnvelope, result);
             if (result.status === 'queued') {

package/dist/local/transactions/mutations/replayValidation.d.ts

@@ -56,6 +56,15 @@ export declare const persistedTransactionSchema: z.ZodObject<{
     sourceMutationIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
     writeOptions: z.ZodOptional<z.ZodObject<{
         readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        reads: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            model: z.ZodString;
+            id: z.ZodString;
+            fields: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+            readAt: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            group: z.ZodTemplateLiteral<`${string}:${string}`>;
+            readAt: z.ZodNumber;
+        }, z.core.$strip>]>>>>;
         idempotencyKey: z.ZodOptional<z.ZodString>;
         label: z.ZodOptional<z.ZodString>;
         fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
@@ -97,6 +106,15 @@ export declare const persistedMutationSchema: z.ZodObject<{
     capturedChanges: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     writeOptions: z.ZodOptional<z.ZodObject<{
         readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        reads: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            model: z.ZodString;
+            id: z.ZodString;
+            fields: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+            readAt: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            group: z.ZodTemplateLiteral<`${string}:${string}`>;
+            readAt: z.ZodNumber;
+        }, z.core.$strip>]>>>>;
         idempotencyKey: z.ZodOptional<z.ZodString>;
         label: z.ZodOptional<z.ZodString>;
         fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
@@ -131,6 +149,15 @@ export declare const legacyPendingMutationRecordSchema: z.ZodObject<{
         capturedChanges: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         writeOptions: z.ZodOptional<z.ZodObject<{
             readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            reads: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                model: z.ZodString;
+                id: z.ZodString;
+                fields: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+                readAt: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                group: z.ZodTemplateLiteral<`${string}:${string}`>;
+                readAt: z.ZodNumber;
+            }, z.core.$strip>]>>>>;
             idempotencyKey: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
             fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
@@ -164,6 +191,15 @@ export declare const pendingMutationRecordSchema: z.ZodObject<{
         capturedChanges: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         writeOptions: z.ZodOptional<z.ZodObject<{
             readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            reads: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                model: z.ZodString;
+                id: z.ZodString;
+                fields: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+                readAt: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                group: z.ZodTemplateLiteral<`${string}:${string}`>;
+                readAt: z.ZodNumber;
+            }, z.core.$strip>]>>>>;
             idempotencyKey: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
             fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;

package/dist/local/transactions/mutations/replayValidation.js

@@ -18,10 +18,12 @@ import { z } from 'zod';
 import { computePriorityScore, normalizeModelKey } from './commitPayload.js';
 import { globalRuntime } from '../../context.js';
 import { commitEnvelopeMemberSchema, commitOutboxScopeSchema, } from '@abloatai/transaction/commit';
+import { readDependencySchema } from '@abloatai/transaction/coordination/schema';
 /** The subset of a write's options that is stored with each transaction or queued mutation. */
 const persistedWriteOptionsSchema = z
     .object({
     readAt: z.number().nullable().optional(),
+    reads: z.array(readDependencySchema).nullable().optional(),
     idempotencyKey: z.string().optional(),
     label: z.string().optional(),
     // Aligned with the `WriteOptions` type: a claimed write persisted locally

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/humans",
-  "version": "0.58.0",
+  "version": "0.59.1",
   "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.1",
     "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

@@ -242,7 +242,7 @@ import type { MutationOptions } from '@abloatai/transaction/client/resources/mut
  */
 export type WriteOptions = Pick<
   MutationOptions,
-  'readAt' | 'idempotencyKey' | 'label' | 'fenceToken' | 'claimRef'
+  'readAt' | 'reads' | 'idempotencyKey' | 'label' | 'fenceToken' | 'claimRef'
 >;
 
 /** A single mutation within a batch. Its `options` travel with it so the server
@@ -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(' ')}`;
 }

package/src/local/transactions/mutations/batchProcessing.ts

@@ -7,7 +7,7 @@ import type { DeltaConfirmationTracker } from './deltaConfirmation.js';
 import type { MutationCommitResult } from '@abloatai/transaction/commit';
 import type { DurableCommitEnvelope } from '@abloatai/transaction/commit';
 import { AbloError, AbloNotFoundError } from '@abloatai/transaction/errors';
-import { applyWriteOptions, normalizeModelKey, TX_TYPE_TO_MUTATION_OP, type WriteOperationFields } from './commitPayload.js';
+import { applyWriteOptions, collectQueuedReads, normalizeModelKey, TX_TYPE_TO_MUTATION_OP, type WriteOperationFields } from './commitPayload.js';
 import type { MutationOperationType } from '@abloatai/transaction/types';
 
 export interface BatchProcessingContext {
@@ -138,6 +138,7 @@ export async function processBatch(ctx: BatchProcessingContext): Promise<void> {
                 origin: 'model_batch',
                 operations: batchOps.map(({ op }) => op),
                 sourceMutationIds: ctx.sourceMutationIdsFor(batch),
+                commitOptions: { reads: collectQueuedReads(batch) },
                 createdAt: Math.min(...batch.map((transaction) => transaction.createdAt)),
                 sealedAt: batch[0]?.commitEnvelope?.sealedAt ?? Date.now(),
                 sequence: batch[0]?.commitEnvelope?.sequence,
@@ -155,6 +156,9 @@ export async function processBatch(ctx: BatchProcessingContext): Promise<void> {
               const result = ctx.parseMutationCommitResult(
                 await ctx.dispatchCommitBounded(operations, {
                   idempotencyKey: commitIdempotencyKey,
+                  ...(durableEnvelope.commitOptions.reads !== undefined
+                    ? { reads: durableEnvelope.commitOptions.reads }
+                    : {}),
                 }),
               );
               await ctx.persistDurableCommitAcceptance(

package/src/local/transactions/mutations/commitPayload.ts

@@ -160,6 +160,23 @@ export interface QueuedMutation {
   confirmation?: Promise<void>;
 }
 
+/** Merge per-write premises into the one batch-level read set sent on wire. */
+export function collectQueuedReads(
+  transactions: readonly QueuedMutation[],
+): MutationOptions['reads'] | undefined {
+  const declared = transactions
+    .map((transaction) => transaction.writeOptions?.reads)
+    .filter((reads) => reads !== undefined);
+  if (declared.length === 0) return undefined;
+
+  const unique = new Map<string, NonNullable<MutationOptions['reads']>[number]>();
+  for (const dependency of declared.flatMap((reads) => reads ?? [])) {
+    unique.set(JSON.stringify(dependency), dependency);
+  }
+  const reads = [...unique.values()];
+  return reads.length > 0 ? reads : null;
+}
+
 export const normalizeModelKey = (modelName: string): string =>
   modelName.replace('Model', '').toLowerCase();
 export const stripModelSuffix = (modelName: string): string => modelName.replace('Model', '');

package/src/local/transactions/mutations/pendingDrain.ts

@@ -4,7 +4,7 @@ import type { MutationStore } from './MutationStore.js';
 import type { OptimisticUpdateEntry } from './localMutation.js';
 import type { MutationCommitResult } from '@abloatai/transaction/commit';
 import type { DurableCommitEnvelope } from '@abloatai/transaction/commit';
-import { applyWriteOptions, TX_TYPE_TO_MUTATION_OP } from './commitPayload.js';
+import { applyWriteOptions, collectQueuedReads, TX_TYPE_TO_MUTATION_OP } from './commitPayload.js';
 
 export interface PendingDrainContext {
   readonly runtime: RuntimeContext;
@@ -81,6 +81,7 @@ export async function drainPendingConfirmations(ctx: PendingDrainContext): Promi
           origin: 'model_batch',
           operations: projectedOperations,
           sourceMutationIds: ctx.sourceMutationIdsFor(batch),
+          commitOptions: { reads: collectQueuedReads(batch) },
           createdAt: Math.min(...batch.map((transaction) => transaction.createdAt)),
           sealedAt: batch[0]?.commitEnvelope?.sealedAt ?? Date.now(),
           sequence: batch[0]?.commitEnvelope?.sequence,
@@ -89,6 +90,9 @@ export async function drainPendingConfirmations(ctx: PendingDrainContext): Promi
         const result = ctx.parseMutationCommitResult(
           await ctx.dispatchCommitBounded(durableEnvelope.operations, {
             idempotencyKey,
+            ...(durableEnvelope.commitOptions.reads !== undefined
+              ? { reads: durableEnvelope.commitOptions.reads }
+              : {}),
           }),
         );
         await ctx.persistDurableCommitAcceptance(durableEnvelope, result);

package/src/local/transactions/mutations/replayValidation.ts

@@ -24,11 +24,13 @@ import {
   commitEnvelopeMemberSchema,
   commitOutboxScopeSchema,
 } from '@abloatai/transaction/commit';
+import { readDependencySchema } from '@abloatai/transaction/coordination/schema';
 
 /** The subset of a write's options that is stored with each transaction or queued mutation. */
 const persistedWriteOptionsSchema = z
   .object({
     readAt: z.number().nullable().optional(),
+    reads: z.array(readDependencySchema).nullable().optional(),
     idempotencyKey: z.string().optional(),
     label: z.string().optional(),
     // Aligned with the `WriteOptions` type: a claimed write persisted locally