@abloatai/humans 0.38.0 → 0.40.0

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

@@ -419,11 +419,19 @@ export class MutationQueue extends EventEmitter {
         const notificationsByTarget = new Map();
         let holdsEntireBatch = false;
         for (const notification of notifications) {
-            const candidates = targets.filter((target) => target.id === notification.id);
-            const notificationKey = this.receiptTargetKey(notification.model, notification.id);
+            // Scope is decided before any target matching. A group premise fires over
+            // the WHOLE batch by convention, and its `target` now names the row that
+            // actually moved — which may well be a row this batch is writing, so
+            // matching first would misread a batch-wide hold as a per-row one.
+            if (notification.scope === 'group') {
+                holdsEntireBatch = true;
+                continue;
+            }
+            const candidates = targets.filter((target) => target.id === notification.target.id);
+            const notificationKey = this.receiptTargetKey(notification.target.model, notification.target.id);
             const exactTargets = candidates.filter((target) => target.key === notificationKey);
             const candidateKeys = new Set((exactTargets.length > 0 ? exactTargets : candidates).map((target) => target.key));
-            if (notification.group || candidates.length === 0) {
+            if (candidates.length === 0) {
                 holdsEntireBatch = true;
                 continue;
             }

package/dist/local/utils/mobxSetup.d.ts

@@ -16,6 +16,7 @@ import { type PropertyMetadata, type ReferenceMetadata } from '@abloatai/transac
 interface M1Target {
     _hasCustomObservability?: boolean;
     _isConstructing?: boolean;
+    _isHydrating?: boolean;
     _extraMobxAnnotations?: Record<string, AnnotationMapEntry>;
     setupObservability?(): void;
     propertyChanged?(name: string, oldValue: unknown, newValue: unknown): void;

package/dist/local/utils/mobxSetup.js

@@ -245,6 +245,11 @@ export function M1(target, propertyMetadata, referenceMetadata) {
                             // would otherwise spuriously fill `modifiedProperties`.
                             if (target._isConstructing)
                                 return;
+                            // Hydration writes (`updateFromData`) are inbound wire data,
+                            // not user edits: the forward's result is discarded by the
+                            // `modifiedProperties` swap anyway, so skip the work.
+                            if (target._isHydrating)
+                                return;
                             if (typeof target.propertyChanged === 'function') {
                                 target.propertyChanged(propName, change.oldValue, change.newValue);
                             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/humans",
-  "version": "0.38.0",
+  "version": "0.40.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.38.0",
+    "@abloatai/transaction": "^0.40.0",
     "mobx": "^6.13.7",
     "uuid": "^11.1.0",
     "zod": "^4.4.3"

package/src/core.ts

@@ -110,7 +110,10 @@ export {
   drainProfileSnapshot,
   resetDrainProfile,
   drainProfilingEnabled,
+  drainAcknowledgeStamps,
+  type AcknowledgeStamp,
   type DrainProfile,
+  type DrainBatchRow,
   type DrainStage,
   type DrainStageTotals,
 } from './local/sync/drainProfile.js';

package/src/local/BaseSyncedStore.ts

@@ -187,12 +187,30 @@ export interface SmartSyncOptions {
   maxBootstrapSize?: number;
   batchingDelay?: number;
   maxBatchSize?: number;
+  /**
+   * Upper bound on deltas revealed per apply slice. A large flush batch is
+   * split at TRANSACTION boundaries into slices of at most this many deltas,
+   * with the event loop yielded between slices, so a catch-up wave never
+   * holds the thread for one long synchronous apply. A transaction larger
+   * than the bound still applies whole — the commit stays the atomic unit of
+   * visibility. `Infinity` restores single-slice behavior.
+   */
+  applySliceDeltas?: number;
 }
 
 // RehydrationStats is defined alongside the bootstrap-apply path and is
 // re-exported here.
 export type { RehydrationStats } from './sync/bootstrapApply.js';
 
+/** Bench-diagnostic slice-bound override; absent everywhere but the bench. */
+function benchApplySliceOverride(): number | undefined {
+  const host = globalThis as { process?: { env?: Record<string, string | undefined> } };
+  const raw = host.process?.env?.ABLO_APPLY_SLICE_DELTAS;
+  if (!raw) return undefined;
+  const value = Number(raw);
+  return Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
 /**
  * Bootstrap retry configuration.
  *
@@ -644,8 +662,26 @@ export class BaseSyncedStore<
     this.smartSyncOptions = {
       maxDeltasBeforeBootstrap: 1000,
       maxBootstrapSize: 10 * 1024 * 1024,
-      batchingDelay: 100,
+      // The inbound-delta flush debounce. Under sustained traffic the
+      // `maxBatchSize` force-flush governs batching, so this timer decides
+      // exactly one thing: how long the FINAL partial batch of a burst sits
+      // before it materializes. At 100 ms it was the largest single term in
+      // the observer's drain tail on the throughput bench; 10 ms coalesces a
+      // trickle just as well and keeps burst tails inside the drain budget.
+      batchingDelay: 10,
       maxBatchSize: 50,
+      // ~600 deltas ≈ 9 to 14 ms of apply — inside a no-visible-stall
+      // budget, and a full 500-op commit reveals in one slice. The yield
+      // itself is TIME-budgeted in the pipeline (one or two yields per
+      // batch), because a host yield costs milliseconds under load.
+      // History: the "sliced-apply wedge" that briefly held this at
+      // Infinity was kernel memory limits against the bench's many-isolate
+      // process (semispace commits refused at stock max_map_count /
+      // CommitLimit), not this pipeline — with the limits raised, the
+      // sliced path ran the full certification load with zero errors and
+      // cut writer ack latency threefold. `ABLO_APPLY_SLICE_DELTAS` remains
+      // the bench-diagnostic override.
+      applySliceDeltas: benchApplySliceOverride() ?? 600,
     };
 
     // Create internal helpers

package/src/local/Database.ts

@@ -391,48 +391,85 @@ export class Database {
 
     const out: ModelData = {};
 
-    for (const [key, value] of Object.entries(data)) {
-      // Drop redundant or ephemeral markers
-      if (key === '__typename' || key === '__class' || key === 'clientId' || key === 'syncStatus') {
-        continue;
-      }
+    for (const key in data) {
+      if (!Object.prototype.hasOwnProperty.call(data, key)) continue;
+      this.compactAssign(out, key, data[key]);
+    }
 
-      // Skip only `undefined`; preserve explicit `null`, which is a
-      // meaningful value for a nullable column.
-      if (value === undefined) {
-        continue;
-      }
+    // Always ensure id is present
+    if (!out.id && data.id) out.id = data.id;
 
-      if (Array.isArray(value)) {
-        if (value.length === 0) continue;
-        out[key] = value;
-        continue;
-      }
+    return out;
+  }
 
-      if (typeof value === 'object') {
-        // Preserve explicit null values
-        if (value === null) {
-          out[key] = null;
-          continue;
-        }
+  /**
+   * The one definition of the per-key compaction rule: drops the redundant
+   * markers `__typename`, `__class`, `clientId`, and `syncStatus`, drops
+   * `undefined`, empty arrays, and empty plain objects, and preserves
+   * explicit `null` (a meaningful "clear this field" for a nullable column)
+   * and `Date` instances (IndexedDB can clone these). `compactRecord` applies
+   * it into a fresh object; the batched in-memory delta path applies it
+   * directly onto the merge target so a delta costs one object, not four.
+   */
+  private compactAssign(out: ModelData, key: string, value: unknown): void {
+    if (key === '__typename' || key === '__class' || key === 'clientId' || key === 'syncStatus') {
+      return;
+    }
 
-        // Preserve Date objects (IndexedDB can clone these)
-        if (value instanceof Date) {
-          out[key] = value;
-          continue;
-        }
+    if (value === undefined) return;
+
+    if (Array.isArray(value)) {
+      if (value.length === 0) return;
+      out[key] = value;
+      return;
+    }
+
+    if (typeof value === 'object') {
+      if (value === null) {
+        out[key] = null;
+        return;
+      }
 
-        // For plain objects, drop if empty
-        if (Object.keys(value).length === 0) continue;
+      if (value instanceof Date) {
         out[key] = value;
-        continue;
+        return;
       }
 
+      if (Object.keys(value).length === 0) return;
       out[key] = value;
+      return;
     }
 
-    // Always ensure id is present
-    if (!out.id && data.id) out.id = data.id;
+    out[key] = value;
+  }
+
+  /**
+   * Compact a wire delta's payload in one pass, mirroring
+   * `compactRecord({ id: modelId, ...data })` exactly: the id key is
+   * processed first with the payload's own `id` winning over the envelope's,
+   * then each payload key in order. Passing an existing record as `out`
+   * makes this the update merge — compacted keys override, dropped keys
+   * leave the existing values untouched — without the intermediate
+   * id-injected and compacted copies the spread form allocates.
+   */
+  private compactDeltaRecord(
+    modelId: string,
+    data: Record<string, unknown>,
+    out: ModelData = {},
+  ): ModelData {
+    const hasOwnId = Object.prototype.hasOwnProperty.call(data, 'id');
+    this.compactAssign(out, 'id', hasOwnId ? data.id : modelId);
+
+    for (const key in data) {
+      if (key === 'id') continue;
+      if (!Object.prototype.hasOwnProperty.call(data, key)) continue;
+      this.compactAssign(out, key, data[key]);
+    }
+
+    if (!out.id) {
+      const idValue = hasOwnId ? data.id : modelId;
+      if (idValue) out.id = idValue;
+    }
 
     return out;
   }
@@ -1109,45 +1146,45 @@ export class Database {
       // catch-up frame. Apply the already-ordered batch directly, matching the
       // synchronous request scheduling used by the IndexedDB transaction path.
       for (const [index, delta] of deltas.entries()) {
-        const { actionType, modelName, modelId, data, syncId } = delta;
+        const { actionType, modelName, modelId, data, syncId, transactionId } = delta;
         const store = this.getStore(modelName, 'processDeltaBatch');
         let single: AppliedChange;
 
         if (!store || (typeof syncId === 'number' && syncId <= lastApplied)) {
-          single = { action: 'verify', modelName, modelId };
+          single = { action: 'verify', modelName, modelId, transactionId };
         } else {
           const memoryStore = store as InMemoryObjectStore;
-          const dataWithId =
-            data && typeof data === 'object'
-              ? { id: modelId, ...(data as Record<string, unknown>) }
-              : data;
-          const compacted =
-            dataWithId && typeof dataWithId === 'object'
-              ? this.compactRecord(modelName, dataWithId)
-              : dataWithId;
 
           switch (actionType) {
             case 'C':
-            case 'I':
+            case 'I': {
+              const compacted =
+                data && typeof data === 'object'
+                  ? this.compactDeltaRecord(modelId, data)
+                  : data;
               if (compacted && typeof compacted === 'object') {
                 memoryStore.putSync(compacted);
               }
-              single = { action: 'add', modelName, modelId, data: compacted };
+              single = { action: 'add', modelName, modelId, data: compacted, transactionId };
               break;
+            }
             case 'U': {
               const existing = memoryStore.getSync(modelId);
               if (!existing) {
-                single = { action: 'verify', modelName, modelId, data: null };
+                single = { action: 'verify', modelName, modelId, data: null, transactionId };
               } else {
-                const merged = { ...existing, ...compacted };
+                const merged: ModelData = { ...existing };
+                if (data && typeof data === 'object') {
+                  this.compactDeltaRecord(modelId, data, merged);
+                }
                 memoryStore.putSync(merged);
-                single = { action: 'update', modelName, modelId, data: merged };
+                single = { action: 'update', modelName, modelId, data: merged, transactionId };
               }
               break;
             }
             case 'D':
               memoryStore.deleteSync(modelId);
-              single = { action: 'remove', modelName, modelId };
+              single = { action: 'remove', modelName, modelId, transactionId };
               break;
             case 'A': {
               const archivedData = this.compactRecord(modelName, {
@@ -1156,18 +1193,18 @@ export class Database {
                 archivedAt: new Date(),
               });
               memoryStore.putSync(archivedData);
-              single = { action: 'archive', modelName, modelId, data: archivedData };
+              single = { action: 'archive', modelName, modelId, data: archivedData, transactionId };
               break;
             }
             case 'V':
             case 'G':
             case 'S':
-              single = { action: 'verify', modelName, modelId, data };
+              single = { action: 'verify', modelName, modelId, data, transactionId };
               break;
           }
         }
 
-        inMemResults[index] = { ...single, transactionId: delta.transactionId };
+        inMemResults[index] = single;
         if (
           single.action !== 'verify' &&
           typeof syncId === 'number' &&