@abloatai/humans 0.38.0 → 0.40.0

package/dist/core.d.ts

@@ -33,4 +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, type DrainProfile, type DrainStage, type DrainStageTotals, } from './local/sync/drainProfile.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

@@ -49,4 +49,4 @@ 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, } from './local/sync/drainProfile.js';
+export { drainProfileSnapshot, resetDrainProfile, drainProfilingEnabled, drainAcknowledgeStamps, } from './local/sync/drainProfile.js';

package/dist/local/BaseSyncedStore.d.ts

@@ -126,6 +126,15 @@ 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;
 }
 export type { RehydrationStats } from './sync/bootstrapApply.js';
 /**

package/dist/local/BaseSyncedStore.js

@@ -36,6 +36,15 @@ import * as groupChange from './sync/groupChange.js';
 import * as bootstrapApply from './sync/bootstrapApply.js';
 import * as deltaPipeline from './sync/deltaPipeline.js';
 import { queryByClass as runQueryByClass, countModels } from './store/queryApi.js';
+/** Bench-diagnostic slice-bound override; absent everywhere but the bench. */
+function benchApplySliceOverride() {
+    const host = globalThis;
+    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.
  *
@@ -370,8 +379,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
         this.queryProcessor = new QueryProcessor({

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;
@@ -54,6 +60,18 @@ export declare class InstanceCache {
     constructor(config?: PoolConfig, modelRegistry?: ModelRegistry);
     private resolveModel;
     get<T extends Model = Model>(id: string): T | 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.
+     */
+    peek<T extends Model = Model>(id: string): T | undefined;
     /**
      * Look a row up **within one model**.
      *
@@ -205,17 +223,31 @@ 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.
      *
-     * 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.
+     * 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.
+     *
+     * 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;
+    /**
+     * 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;
     private isLargeModel;
     /**
      * Register a foreign key field for indexing on a model type.