@abloatai/humans 0.38.0 → 0.40.0

package/src/local/InstanceCache.ts

@@ -13,7 +13,7 @@ import { ModelRegistry } from './ModelRegistry.js';
 import { globalRuntime } from './context.js';
 import type { RuntimeContext } from './RuntimeContext.js';
 import { AbloValidationError } from '@abloatai/transaction/errors';
-import { ModelScope } from '@abloatai/transaction/types';
+import { ModelScope, PropertyType } from '@abloatai/transaction/types';
 import { ViewRegistry } from './views/ViewRegistry.js';
 import { QueryView, type QueryViewOptions } from './views/QueryView.js';
 
@@ -48,15 +48,39 @@ interface DeltaInfo {
  * entity resolves to a single instance.
  */
 export class InstanceCache {
-  // Single source of truth for all models (observable for reactivity)
-  private entries = observable.map<string, ModelEntry>();
-  private typeIndex = observable.map<string, Set<string>>();
+  // Single source of truth for all models (observable for reactivity).
+  // Shallow on purpose, and the reactivity contract depends on it: readers
+  // track MEMBERSHIP (keys), and every entry-level change re-sets the whole
+  // entry (see `updateScope`) — in-place field writes on an entry do not
+  // notify. The deep default additionally converted every stored ModelEntry
+  // into an observable object, a per-add extendObservable/defineProperty
+  // pass that profiled as the single largest term of create-apply on the
+  // wire-ingestion path, bought nothing the contract uses, and meant
+  // `entries.get()` returned a converted wrapper rather than the object
+  // the insert stored.
+  private entries = observable.map<string, ModelEntry>({}, { deep: false });
+  private typeIndex = observable.map<string, Set<string>>({}, { deep: false });
 
   // 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 +227,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,13 +274,45 @@ 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();
     return model ?? undefined;
   }
 
+  /**
+   * Ingestion-side lookup: resolve a row WITHOUT crossing the consumer
+   * boundary. Same resolution semantics as {@link get} — weak-ref revival,
+   * disposed rows filtered, access recency stamped — but the model is NOT
+   * activated. The delta-apply loop reads every row it updates, and reading
+   * through `get()` made the stream itself install per-field MobX
+   * instrumentation on rows no consumer ever observes; that activation is
+   * the dominant term of apply cost (measured 12.9 vs 2.9 µs/delta in
+   * `applyPool.bench.test.ts`). Consumer reads must keep using `get()`,
+   * which is what activates a deferred model.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
+  peek<T extends Model = Model>(id: string): T | undefined {
+    const entry = this.entries.get(id);
+    if (!entry) return undefined;
+
+    let model = entry.model as T | undefined;
+    if (!model && entry.weakRef) {
+      const restoredModel = entry.weakRef.deref();
+      if (!restoredModel) return undefined;
+      model = restoredModel as T;
+      runInAction(() => {
+        entry.model = restoredModel;
+      });
+    }
+
+    if (model?.disposed) return undefined;
+
+    this.touchAccess(id, Date.now());
+    return model ?? undefined;
+  }
+
   /**
    * Look a row up **within one model**.
    *
@@ -312,7 +368,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 +437,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 +471,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 +518,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 +528,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 +577,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 +592,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);
         }
@@ -705,6 +761,11 @@ export class InstanceCache {
 
       const model = this.resolveModel(entry, id);
       if (model && !model.disposed) {
+        // Bulk reads are a consumer boundary: rows land cold from the wire
+        // (delta ingestion applies with `peek` and never activates), so
+        // every read that hands models out must activate them, exactly as
+        // `get()` does. Idempotent — an active row pays one boolean check.
+        model.ensureObservable();
         result.push(model);
       }
     }
@@ -732,6 +793,8 @@ export class InstanceCache {
 
       const model = this.resolveModel(entry, id);
       if (model && !model.disposed) {
+        // Consumer boundary — activate, as in getByType.
+        model.ensureObservable();
         result.push(model);
       }
     }
@@ -773,7 +836,7 @@ export class InstanceCache {
       runInAction(() => {
         this.entries.set(id, { ...entry, scope });
       });
-      this.accessTimes.set(id, Date.now());
+      this.touchAccess(id, Date.now());
     }
   }
 
@@ -989,7 +1052,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 +1071,7 @@ export class InstanceCache {
       return false;
     }
 
-    this.accessTimes.set(id, Date.now());
+    this.touchAccess(id, Date.now());
     return true;
   }
 
@@ -1107,7 +1170,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 +1246,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,34 +1287,72 @@ 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++;
       }
     });
   }
 
+  /**
+   * Data-field keys to probe per model, resolved once per model name. Only
+   * stored-value fields can carry bulk; walking the whole instance also
+   * visited the base class's bookkeeping (`_mobxProperties`,
+   * `modifiedProperties`, `validationRules`, …) and JSON-stringified each of
+   * those empty containers on EVERY add — a first-order term of wire-ingest
+   * create apply. Reference/computed keys are deliberately excluded: reading
+   * them would execute their getters.
+   */
+  private sizeProbeKeys = new Map<string, readonly string[]>();
+
   private isLargeModel(model: Model): boolean {
     try {
-      // Most synchronized rows contain only short scalars. Serializing the
-      // entire model merely to discover that fact doubled wire-ingest object
-      // walking. Accumulate cheap scalar sizes and serialize only nested
-      // payloads that can plausibly cross the WeakRef threshold.
+      const modelName = model.getModelName();
+      let keys = this.sizeProbeKeys.get(modelName);
+      if (!keys) {
+        const props = this.registry.getProperties(modelName);
+        keys = [...props.entries()]
+          .filter(([, meta]) => meta.type === PropertyType.property || meta.type === PropertyType.ephemeralProperty)
+          .map(([key]) => key);
+        this.sizeProbeKeys.set(modelName, keys);
+      }
+      // A model with no registered stored fields (e.g. a custom entity) keeps
+      // the whole-instance walk, since its payload lives outside the schema.
+      const values: Iterable<unknown> = keys.length > 0
+        ? keys.map((key): unknown => Reflect.get(model, key))
+        : Object.values(model);
+
+      // Most synchronized rows contain only short scalars. Accumulate cheap
+      // scalar sizes and serialize only nested payloads that can plausibly
+      // cross the WeakRef threshold.
       let size = 0;
-      for (const value of Object.values(model)) {
+      for (const value of values) {
         if (typeof value === 'string') {
           size += value.length;
         } else if (
@@ -1369,6 +1448,9 @@ export class InstanceCache {
       if (!this.matchesScope(entry.scope, ModelScope.live)) { droppedScope++; continue; }
       const model = this.resolveModel(entry, id);
       if (model && !model.disposed) {
+        // Consumer boundary — activate, as in getByType. `hasMany` reads
+        // (`section.blocks`) observe fields off these rows directly.
+        model.ensureObservable();
         result.push(model);
       } else if (model?.disposed) {
         droppedDisposed++;

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
@@ -108,6 +121,17 @@ export abstract class Model {
   /** MobX observable properties storage */
   _mobxProperties: ModelData = {};
 
+  /**
+   * True while {@link updateFromData} assigns inbound wire data. The
+   * `observe()` bridge (`mobxSetup.M1`) checks it and skips the forward to
+   * {@link propertyChanged} entirely: hydration writes are not user edits, and
+   * the bridge's work per changed field — a nested action, map bookkeeping,
+   * and a fabricated `updatedAt` stamp — was already being discarded by the
+   * `modifiedProperties` swap in `updateFromData`. The swap stays as the
+   * correctness backstop; this flag removes the cost.
+   */
+  _isHydrating = false;
+
   /** Referenced models cache */
   _referencedModels: Record<string, Model | null> = {};
 
@@ -120,6 +144,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 +327,8 @@ export abstract class Model {
    */
   markAsPersisted(): void {
     this._isNew = false;
-    this._originalData = this.captureSnapshot();
+    this._originalData = undefined;
+    this._originalDataStale = true;
   }
 
   /**
@@ -315,6 +352,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 +365,8 @@ export abstract class Model {
   clearChanges(): void {
     runInAction(() => {
       this.modifiedProperties.clear();
-      this._originalData = this.captureSnapshot();
+      this._originalData = undefined;
+      this._originalDataStale = true;
     });
   }
 
@@ -580,48 +622,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 +667,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)
    *
@@ -661,16 +732,20 @@ export abstract class Model {
     runInAction(() => {
       const originalTracking = this.modifiedProperties;
       this.modifiedProperties = new Map();
-
-      // No `onWrite` → this call records nothing itself.
-      this.assignFieldsFromData(data);
-
-      this.modifiedProperties = originalTracking;
+      this._isHydrating = true;
+      try {
+        // No `onWrite` → this call records nothing itself.
+        this.assignFieldsFromData(data);
+      } finally {
+        this._isHydrating = false;
+        this.modifiedProperties = originalTracking;
+      }
     });
 
     // Mark as persisted if updating existing model
     if (!this._isNew) {
-      this._originalData = this.captureSnapshot();
+      this._originalData = undefined;
+      this._originalDataStale = true;
     }
 
     this.didUpdate();