@abloatai/humans 0.37.1 → 0.39.0

package/dist/core.d.ts

@@ -33,3 +33,4 @@ export { createClaimStream, type AttachableClaimStream, type ClaimStreamConfig,
 export { awaitClaimGrant, type GrantTransport, } from '@abloatai/transaction/coordination/awaitClaimGrant';
 export { LoadStrategy } from '@abloatai/transaction/types';
 export type { InternalAbloOptions } from './local/client/options.js';
+export { drainProfileSnapshot, resetDrainProfile, drainProfilingEnabled, drainAcknowledgeStamps, type AcknowledgeStamp, type DrainProfile, type DrainBatchRow, type DrainStage, type DrainStageTotals, } from './local/sync/drainProfile.js';

package/dist/core.js

@@ -46,3 +46,7 @@ export { awaitClaimGrant, } from '@abloatai/transaction/coordination/awaitClaimG
 // An enum naming the strategies for loading a model's data. Referenced when
 // registering models in extension code.
 export { LoadStrategy } from '@abloatai/transaction/types';
+// Stage timings for the delta drain, so a benchmark harness can report where
+// an observer's catch-up time went instead of inferring it. Inert unless
+// `ABLO_PROFILE_DRAIN=true`, and read-only: the pipeline does the recording.
+export { drainProfileSnapshot, resetDrainProfile, drainProfilingEnabled, drainAcknowledgeStamps, } from './local/sync/drainProfile.js';

package/dist/local/BaseSyncedStore.d.ts

@@ -86,8 +86,10 @@ export interface UserContext {
     organizationId: string;
     /** Authenticated data-plane coordinates used to isolate local persistence. */
     projectId?: string | null;
-    environment?: 'sandbox' | 'production' | null;
-    sandboxId?: string | null;
+    /** Immutable branch target. Authoritative whenever present. */
+    branchId: string;
+    /** True only when branchId is the project's production root. */
+    branchRoot?: boolean;
     role?: string;
     teamIds?: string[];
     /** Participant kind on the wire. Default 'user' for browser

package/dist/local/BaseSyncedStore.js

@@ -370,7 +370,13 @@ 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,
         };
         // Create internal helpers

package/dist/local/Database.d.ts

@@ -151,6 +151,26 @@ export declare class Database {
      * and bootstrap data is plain JSON from the server.
      */
     private compactRecord;
+    /**
+     * 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;
+    /**
+     * 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;
     /**
      * Mark that the next bootstrap must be a full bootstrap.
      * Called when a sync group change ("G" delta) is received — the client must

package/dist/local/Database.js

@@ -231,44 +231,77 @@ export class Database {
         if (!data || typeof data !== 'object')
             return data;
         const out = {};
-        for (const [key, value] of Object.entries(data)) {
-            // Drop redundant or ephemeral markers
-            if (key === '__typename' || key === '__class' || key === 'clientId' || key === 'syncStatus') {
-                continue;
-            }
-            // Skip only `undefined`; preserve explicit `null`, which is a
-            // meaningful value for a nullable column.
-            if (value === undefined) {
-                continue;
-            }
-            if (Array.isArray(value)) {
-                if (value.length === 0)
-                    continue;
-                out[key] = value;
+        for (const key in data) {
+            if (!Object.prototype.hasOwnProperty.call(data, key))
                 continue;
+            this.compactAssign(out, key, data[key]);
+        }
+        // Always ensure id is present
+        if (!out.id && data.id)
+            out.id = data.id;
+        return out;
+    }
+    /**
+     * 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.
+     */
+    compactAssign(out, key, value) {
+        if (key === '__typename' || key === '__class' || key === 'clientId' || key === 'syncStatus') {
+            return;
+        }
+        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;
             }
-            if (typeof value === 'object') {
-                // Preserve explicit null values
-                if (value === null) {
-                    out[key] = null;
-                    continue;
-                }
-                // Preserve Date objects (IndexedDB can clone these)
-                if (value instanceof Date) {
-                    out[key] = value;
-                    continue;
-                }
-                // 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;
+        }
+        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.
+     */
+    compactDeltaRecord(modelId, data, out = {}) {
+        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;
         }
-        // Always ensure id is present
-        if (!out.id && data.id)
-            out.id = data.id;
         return out;
     }
     /**
@@ -778,43 +811,44 @@ 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;
                 if (!store || (typeof syncId === 'number' && syncId <= lastApplied)) {
-                    single = { action: 'verify', modelName, modelId };
+                    single = { action: 'verify', modelName, modelId, transactionId };
                 }
                 else {
                     const memoryStore = store;
-                    const dataWithId = data && typeof data === 'object'
-                        ? { id: modelId, ...data }
-                        : 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 = { ...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, {
@@ -823,17 +857,17 @@ 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' &&
                     syncId > inMemPersistedSyncId) {

package/dist/local/InstanceCache.d.ts

@@ -35,6 +35,12 @@ export declare class InstanceCache {
     private entries;
     private typeIndex;
     private accessTimes;
+    /**
+     * 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;
     private recentAdditions;
     private deltaHistory;
     private foreignKeyIndexes;
@@ -205,15 +211,19 @@ export declare class InstanceCache {
     stopGC(): void;
     private evictOldest;
     /**
-     * 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;
     private isLargeModel;

package/dist/local/InstanceCache.js

@@ -27,7 +27,21 @@ 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.
     accessTimes = new Map();
+    /**
+     * 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.
+     */
+    touchAccess(id, at) {
+        this.accessTimes.delete(id);
+        this.accessTimes.set(id, at);
+    }
     // Deduplication tracking
     recentAdditions = new Map(); // "modelType:modelId" -> timestamp
     deltaHistory = new Map();
@@ -145,7 +159,7 @@ export class InstanceCache {
             if (model) {
                 entry.model = model;
                 if (id)
-                    this.accessTimes.set(id, Date.now());
+                    this.touchAccess(id, Date.now());
                 return model;
             }
         }
@@ -186,7 +200,7 @@ export class InstanceCache {
             return undefined;
         }
         // 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;
@@ -243,7 +257,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;
@@ -295,7 +309,7 @@ export class InstanceCache {
         if (this.config.useWeakRefs && this.isLargeModel(model)) {
             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());
@@ -324,7 +338,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);
             // Notify views of the update
@@ -366,7 +380,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;
@@ -375,7 +389,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);
             }
@@ -417,7 +431,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
@@ -433,7 +447,7 @@ export class InstanceCache {
                     this.evictOldest();
                 }
                 const entry = { 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);
                 }
@@ -632,7 +646,7 @@ export class InstanceCache {
             runInAction(() => {
                 this.entries.set(id, { ...entry, scope });
             });
-            this.accessTimes.set(id, Date.now());
+            this.touchAccess(id, Date.now());
         }
     }
     /**
@@ -784,7 +798,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
     }
@@ -800,7 +814,7 @@ export class InstanceCache {
         if (!entry) {
             return false;
         }
-        this.accessTimes.set(id, Date.now());
+        this.touchAccess(id, Date.now());
         return true;
     }
     getAllIds() {
@@ -884,7 +898,7 @@ export class InstanceCache {
                         typeof model.hasObservedCollections === 'function' &&
                         model.hasObservedCollections()) {
                         // Model has active React observers - refresh access time and skip GC
-                        this.accessTimes.set(id, now);
+                        this.touchAccess(id, now);
                         skippedObserved++;
                         continue;
                     }
@@ -949,61 +963,36 @@ export class InstanceCache {
         this.evictOldestBatch(1);
     }
     /**
-     * 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.
      */
     evictOldestBatch(count) {
         if (count <= 0)
             return;
         runInAction(() => {
-            const oldest = [];
-            const candidateAt = (index) => {
-                const candidate = oldest[index];
-                if (!candidate)
-                    throw new Error(`Missing eviction candidate at index ${index}`);
-                return candidate;
-            };
-            const swap = (left, right) => {
-                const leftValue = candidateAt(left);
-                const rightValue = candidateAt(right);
-                oldest[left] = rightValue;
-                oldest[right] = leftValue;
-            };
-            const siftUp = (start) => {
-                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 = () => {
-                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 = [];
+            const staleAccessKeys = [];
+            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 (model &&
@@ -1011,21 +1000,32 @@ export class InstanceCache {
                     model.hasObservedCollections()) {
                     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/dist/local/Model.d.ts

@@ -89,6 +89,17 @@ export declare abstract class Model {
     private _isNew;
     /** Original data snapshot */
     private _originalData?;
+    /**
+     * 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;
     /** Sync status */
     syncStatus: 'pending' | 'syncing' | 'synced';
     /** Timestamps */
@@ -279,6 +290,13 @@ export declare abstract class Model {
      * leaves that baseline intact.
      */
     private assignFieldsFromData;
+    /**
+     * 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;
     /**
      * Update from raw data (hydration)
      *