@abloatai/humans 0.37.1 → 0.39.0

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' &&

package/src/local/InstanceCache.ts

@@ -55,8 +55,23 @@ export class InstanceCache {
   // Non-observable access time tracking — kept outside observable.map so that
   // updating timestamps in get() during React render does NOT trigger MobX
   // reactions (which would cause infinite re-render loops).
+  //
+  // Every write goes through `touchAccess`, which moves the key to the map's
+  // back, so iteration order IS recency order (oldest first). Eviction relies
+  // on that: `evictOldestBatch` takes the first eligible keys instead of
+  // scanning every entry.
   private accessTimes = new Map<string, number>();
 
+  /**
+   * Record an access. The delete-then-set moves an existing key to the back
+   * of the map's insertion order, which is what keeps `accessTimes` iterable
+   * oldest-first for eviction.
+   */
+  private touchAccess(id: string, at: number): void {
+    this.accessTimes.delete(id);
+    this.accessTimes.set(id, at);
+  }
+
   // Deduplication tracking
   private recentAdditions = new Map<string, number>(); // "modelType:modelId" -> timestamp
   private deltaHistory = new Map<
@@ -203,7 +218,7 @@ export class InstanceCache {
       const model = entry.weakRef.deref();
       if (model) {
         entry.model = model;
-        if (id) this.accessTimes.set(id, Date.now());
+        if (id) this.touchAccess(id, Date.now());
         return model;
       }
     }
@@ -250,7 +265,7 @@ export class InstanceCache {
     }
 
     // Update access time in non-observable map — prevents MobX reactions during render
-    this.accessTimes.set(id, Date.now());
+    this.touchAccess(id, Date.now());
     this.metrics.hits++;
 
     model?.ensureObservable();
@@ -312,7 +327,7 @@ export class InstanceCache {
         runInAction(() => {
           this.entries.set(id, { ...existingEntry, scope });
         });
-        this.accessTimes.set(id, Date.now());
+        this.touchAccess(id, Date.now());
       }
       this.metrics.duplicatesSkipped++;
       return;
@@ -381,7 +396,7 @@ export class InstanceCache {
       entry.weakRef = new WeakRef(model);
     }
 
-    this.accessTimes.set(id, Date.now());
+    this.touchAccess(id, Date.now());
     runInAction(() => {
       this.entries.set(id, entry);
       this.addToTypeIndex(id, model.getModelName());
@@ -415,7 +430,7 @@ export class InstanceCache {
         runInAction(() => {
           this.entries.set(id, { ...existingEntry, scope });
         });
-        this.accessTimes.set(id, Date.now());
+        this.touchAccess(id, Date.now());
       }
 
       this.notifySubscribers(existingModel);
@@ -462,7 +477,7 @@ export class InstanceCache {
       if (existingEntry?.model && !existingEntry.model.disposed) {
         if (existingEntry.scope !== scope) {
           this.entries.set(id, { ...existingEntry, scope });
-          this.accessTimes.set(id, now);
+          this.touchAccess(id, now);
         }
         this.metrics.duplicatesSkipped++;
         continue;
@@ -472,7 +487,7 @@ export class InstanceCache {
         model,
         scope,
       };
-      this.accessTimes.set(id, now);
+      this.touchAccess(id, now);
 
       if (this.config.useWeakRefs && this.isLargeModel(model)) {
         entry.weakRef = new WeakRef(model);
@@ -521,7 +536,7 @@ export class InstanceCache {
         }
         if (existingEntry.scope !== scope) {
           this.entries.set(id, { ...existingEntry, scope });
-          this.accessTimes.set(id, Date.now());
+          this.touchAccess(id, Date.now());
         }
         this.notifySubscribers(existingEntry.model);
         // Notify views of the update
@@ -536,7 +551,7 @@ export class InstanceCache {
           this.evictOldest();
         }
         const entry: ModelEntry = { model, scope };
-        this.accessTimes.set(id, Date.now());
+        this.touchAccess(id, Date.now());
         if (this.config.useWeakRefs && this.isLargeModel(model)) {
           entry.weakRef = new WeakRef(model);
         }
@@ -773,7 +788,7 @@ export class InstanceCache {
       runInAction(() => {
         this.entries.set(id, { ...entry, scope });
       });
-      this.accessTimes.set(id, Date.now());
+      this.touchAccess(id, Date.now());
     }
   }
 
@@ -989,7 +1004,7 @@ export class InstanceCache {
     // Restore access times: clear then re-add preserved
     this.accessTimes.clear();
     for (const [id, time] of preservedAccessTimes) {
-      this.accessTimes.set(id, time);
+      this.touchAccess(id, time);
     }
     // No cache to invalidate — typeIndex + entries are directly observable
   }
@@ -1008,7 +1023,7 @@ export class InstanceCache {
       return false;
     }
 
-    this.accessTimes.set(id, Date.now());
+    this.touchAccess(id, Date.now());
     return true;
   }
 
@@ -1107,7 +1122,7 @@ export class InstanceCache {
             model.hasObservedCollections()
           ) {
             // Model has active React observers - refresh access time and skip GC
-            this.accessTimes.set(id, now);
+            this.touchAccess(id, now);
             skippedObserved++;
             continue;
           }
@@ -1183,59 +1198,37 @@ export class InstanceCache {
   }
 
   /**
-   * Free capacity for a whole incoming frame in one scan.
+   * Free capacity for a whole incoming frame by taking the first eligible
+   * keys of the recency-ordered `accessTimes` map.
+   *
+   * Every access moves its key to the back of that map (`touchAccess`), so
+   * iterating from the front visits entries oldest-first — the eviction
+   * order — at O(count) for a sustained publication frame. The previous
+   * shape kept a bounded max-heap but still walked EVERY cache entry per
+   * incoming frame, which at a 10k cap and ~1.3k-delta frames made the scan
+   * itself a first-order term of the observer's apply cost.
    *
-   * Calling evictOldest once per model made a full 10k-entry cache scan
-   * `incomingCount` times. A 400-row delta frame therefore performed four
-   * million entry visits before constructing models. Keep only the `count`
-   * oldest candidates in a bounded max-heap: a full sort paid
-   * O(cache log cache) for every sustained publication frame even though it
-   * consumed only the first few hundred entries. The heap preserves the same
-   * LRU/observed-model contract at O(cache log count) time and O(count) space.
+   * The observed-model contract is unchanged: a model React is observing is
+   * skipped and stays in place, so it is reconsidered (and skipped again)
+   * on later evictions until it is no longer observed.
    */
   private evictOldestBatch(count: number): void {
     if (count <= 0) return;
     runInAction(() => {
-      interface Candidate { id: string; accessedAt: number }
-      const oldest: Candidate[] = [];
-      const candidateAt = (index: number): Candidate => {
-        const candidate = oldest[index];
-        if (!candidate) throw new Error(`Missing eviction candidate at index ${index}`);
-        return candidate;
-      };
-      const swap = (left: number, right: number): void => {
-        const leftValue = candidateAt(left);
-        const rightValue = candidateAt(right);
-        oldest[left] = rightValue;
-        oldest[right] = leftValue;
-      };
-      const siftUp = (start: number): void => {
-        let index = start;
-        while (index > 0) {
-          const parent = Math.floor((index - 1) / 2);
-          if (candidateAt(parent).accessedAt >= candidateAt(index).accessedAt) break;
-          swap(parent, index);
-          index = parent;
-        }
-      };
-      const siftDown = (): void => {
-        let index = 0;
-        for (;;) {
-          const left = index * 2 + 1;
-          if (left >= oldest.length) return;
-          const right = left + 1;
-          const larger =
-            right < oldest.length &&
-            candidateAt(right).accessedAt > candidateAt(left).accessedAt
-              ? right
-              : left;
-          if (candidateAt(index).accessedAt >= candidateAt(larger).accessedAt) return;
-          swap(index, larger);
-          index = larger;
+      const toEvict: string[] = [];
+      const staleAccessKeys: string[] = [];
+
+      for (const id of this.accessTimes.keys()) {
+        if (toEvict.length >= count) break;
+
+        const entry = this.entries.get(id);
+        if (!entry) {
+          // remove()/clear() delete from both maps, so a stale key means a
+          // divergence — clean it up rather than let it linger.
+          staleAccessKeys.push(id);
+          continue;
         }
-      };
 
-      for (const [id, entry] of this.entries) {
         // Skip models that are being observed by React - they must stay alive
         const model = entry.model ?? entry.weakRef?.deref();
         if (
@@ -1246,21 +1239,34 @@ export class InstanceCache {
           continue;
         }
 
-        const candidate = {
-          id,
-          accessedAt: this.accessTimes.get(id) ?? 0,
-        };
-        if (oldest.length < count) {
-          oldest.push(candidate);
-          siftUp(oldest.length - 1);
-        } else if (candidate.accessedAt < candidateAt(0).accessedAt) {
-          oldest[0] = candidate;
-          siftDown();
+        toEvict.push(id);
+      }
+
+      for (const id of staleAccessKeys) this.accessTimes.delete(id);
+
+      // Safety net for an entry that never received an access stamp: it is
+      // invisible to the recency map, so fall back to the entry scan the old
+      // implementation always paid. Every add path stamps `accessTimes`, so
+      // this loop finds nothing and costs nothing in the normal case (it only
+      // runs at all when the recency map came up short).
+      if (toEvict.length < count) {
+        for (const [id, entry] of this.entries) {
+          if (toEvict.length >= count) break;
+          if (this.accessTimes.has(id)) continue;
+          const model = entry.model ?? entry.weakRef?.deref();
+          if (
+            model &&
+            typeof model.hasObservedCollections === 'function' &&
+            model.hasObservedCollections()
+          ) {
+            continue;
+          }
+          toEvict.push(id);
         }
       }
 
-      for (const candidate of oldest) {
-        this.remove(candidate.id);
+      for (const id of toEvict) {
+        this.remove(id);
         this.metrics.evictions++;
       }
     });

package/src/local/Model.ts

@@ -89,6 +89,19 @@ export interface ModelChanges {
 /** Shared frozen default for {@link Model.getDerivedGetterNames}. */
 const EMPTY_DERIVED_GETTERS: readonly string[] = Object.freeze([]);
 
+/**
+ * How {@link Model.assignFieldsFromData} treats one key on instances of one
+ * model class. Resolved once per (class, key) and cached: the decision depends
+ * only on class shape — prototype getters, registry annotations, declared
+ * fields — which is identical across instances of a generated model class.
+ * Every write disposition is still guarded per instance by a `key in this`
+ * check, so an instance that genuinely lacks the key falls back to the full
+ * resolution instead of trusting the cache.
+ */
+type FieldDisposition = 'write' | 'write-date' | 'skip-absent' | 'skip-readonly';
+
+const fieldWritePlans = new WeakMap<object, Map<string, FieldDisposition>>();
+
 /**
  * The abstract base class every domain model extends. It holds the model's id
  * and timestamps, tracks in-place property changes for change detection and
@@ -120,6 +133,18 @@ export abstract class Model {
   /** Original data snapshot */
   private _originalData?: ModelData;
 
+  /**
+   * Whether the persisted baseline needs recapturing. Hydration and ack land
+   * far more often than anything reads the baseline — an observer-only client
+   * reads it never — so each of those sites marks the snapshot stale and
+   * {@link getOriginalSnapshot} materializes it on first read. Correctness
+   * rests on the tracking invariant: every non-hydration write is recorded in
+   * `modifiedProperties` (first-old-wins), so between the stale mark and the
+   * read, untracked fields still hold exactly the values an eager capture
+   * would have recorded.
+   */
+  private _originalDataStale = false;
+
   /** Sync status */
   syncStatus: 'pending' | 'syncing' | 'synced' = 'pending';
 
@@ -291,7 +316,8 @@ export abstract class Model {
    */
   markAsPersisted(): void {
     this._isNew = false;
-    this._originalData = this.captureSnapshot();
+    this._originalData = undefined;
+    this._originalDataStale = true;
   }
 
   /**
@@ -315,6 +341,10 @@ export abstract class Model {
    * last acknowledged state would already be the authoritative baseline.
    */
   getOriginalSnapshot(): Readonly<ModelData> | undefined {
+    if (this._originalDataStale) {
+      this._originalData = this.captureSnapshot();
+      this._originalDataStale = false;
+    }
     return this._originalData;
   }
 
@@ -324,7 +354,8 @@ export abstract class Model {
   clearChanges(): void {
     runInAction(() => {
       this.modifiedProperties.clear();
-      this._originalData = this.captureSnapshot();
+      this._originalData = undefined;
+      this._originalDataStale = true;
     });
   }
 
@@ -580,48 +611,39 @@ export abstract class Model {
     data: ModelData,
     onWrite?: (key: string, oldValue: unknown, newValue: unknown) => void,
   ): void {
-    // Update properties with safety checks for read-only/computed accessors
-    for (const [key, raw] of Object.entries(data)) {
-      if (key === 'id') continue;
-
-      // Only attempt to set if the property exists on instance or prototype
-      if (!(this.hasOwnProperty(key) || key in this)) continue;
+    let plan = fieldWritePlans.get(this.constructor);
+    if (!plan) {
+      plan = new Map();
+      fieldWritePlans.set(this.constructor, plan);
+    }
 
-      // Never assign to MobX computed properties (they may expose a setter that throws)
-      try {
-        if (isComputedProp(this, key)) {
-          continue;
-        }
-      } catch {
-        // If MobX internals are unavailable for some reason, fall back to descriptor checks below
-      }
+    for (const key in data) {
+      if (key === 'id') continue;
+      if (!Object.prototype.hasOwnProperty.call(data, key)) continue;
+      const raw = data[key];
 
-      // Resolve property descriptor from own or prototype chain
-      const ownDesc = Object.getOwnPropertyDescriptor(this, key);
-      let desc = ownDesc;
-      if (!desc) {
-        let proto = Object.getPrototypeOf(this) as object | null;
-        while (proto && proto !== Object.prototype && !desc) {
-          desc = Object.getOwnPropertyDescriptor(proto, key);
-          proto = Object.getPrototypeOf(proto) as object | null;
-        }
+      let disposition = plan.get(key);
+      if (disposition === undefined) {
+        disposition = this.resolveFieldDisposition(key);
+        plan.set(key, disposition);
       }
 
-      // Determine writability: allow if data descriptor writable, or accessor with setter
-      const writable = desc
-        ? ('writable' in desc && !!desc.writable) ||
-          ('set' in desc && typeof desc.set === 'function')
-        : true;
-      if (!writable) {
-        // Skip read-only accessor properties (getter-only)
+      if (disposition === 'skip-readonly') continue;
+      if (disposition === 'skip-absent') {
+        // The plan was built from an instance that lacked this key. Re-resolve
+        // for this instance without touching the cache, so heterogeneous
+        // shapes stay correct at the cost of the slow path.
+        if (!(key in this)) continue;
+        disposition = this.resolveFieldDisposition(key);
+        if (disposition === 'skip-readonly' || disposition === 'skip-absent') continue;
+      } else if (!(key in this)) {
         continue;
       }
 
       // Handle date conversions
-      const value =
-        (key === 'createdAt' || key === 'updatedAt' || key === 'archivedAt') && raw
-          ? new Date(raw as string | number)
-          : raw;
+      const value = disposition === 'write-date' && raw
+        ? new Date(raw as string | number)
+        : raw;
 
       // Capture the pre-write value BEFORE assignment so trackers
       // (undo inverse, getChanges) see the true previous value.
@@ -634,6 +656,44 @@ export abstract class Model {
     }
   }
 
+  /**
+   * The uncached decision for one key: existence on instance or prototype,
+   * never a MobX computed (its setter may throw), and writability resolved
+   * through the descriptor chain — a data descriptor's `writable` or an
+   * accessor's setter.
+   */
+  private resolveFieldDisposition(key: string): FieldDisposition {
+    if (!(key in this)) return 'skip-absent';
+
+    try {
+      if (isComputedProp(this, key)) {
+        return 'skip-readonly';
+      }
+    } catch {
+      // If MobX internals are unavailable for some reason, fall back to descriptor checks below
+    }
+
+    const ownDesc = Object.getOwnPropertyDescriptor(this, key);
+    let desc = ownDesc;
+    if (!desc) {
+      let proto = Object.getPrototypeOf(this) as object | null;
+      while (proto && proto !== Object.prototype && !desc) {
+        desc = Object.getOwnPropertyDescriptor(proto, key);
+        proto = Object.getPrototypeOf(proto) as object | null;
+      }
+    }
+
+    const writable = desc
+      ? ('writable' in desc && !!desc.writable) ||
+        ('set' in desc && typeof desc.set === 'function')
+      : true;
+    if (!writable) return 'skip-readonly';
+
+    return key === 'createdAt' || key === 'updatedAt' || key === 'archivedAt'
+      ? 'write-date'
+      : 'write';
+  }
+
   /**
    * Update from raw data (hydration)
    *
@@ -670,7 +730,8 @@ export abstract class Model {
 
     // Mark as persisted if updating existing model
     if (!this._isNew) {
-      this._originalData = this.captureSnapshot();
+      this._originalData = undefined;
+      this._originalDataStale = true;
     }
 
     this.didUpdate();