@abloatai/humans 0.42.0 → 0.43.0

package/dist/local/BaseSyncedStore.js

@@ -1173,6 +1173,7 @@ export class BaseSyncedStore {
             advancePersisted: (syncId) => { this.syncClient.position.advancePersisted(syncId); },
             // Persistence + pool writes.
             processDeltaBatch: (deltas) => this.database.processDeltaBatch(deltas),
+            projectDeltaBatchForPool: (results) => this.syncClient.projectDeltaBatchForPool(results),
             applyDeltaBatchToPool: (results) => { this.applyChangesToPool(results); },
             acknowledge: (syncId) => { this.syncWebSocket.acknowledge(syncId); },
             get objectPool() { return store.objectPool; },

package/dist/local/InstanceCache.d.ts

@@ -57,6 +57,18 @@ export declare class InstanceCache {
      */
     subscribe<T extends Model>(modelClass: ModelConstructor<T>, callback: (model: T) => void): () => void;
     private notifySubscribers;
+    /**
+     * Maximum fresh wire rows worth constructing from one atomic apply batch.
+     *
+     * A headless cache has no recency signal: every never-read resident is
+     * equally useful, while the local database remains the authoritative full
+     * state. Once that cache is full, replacing cold rows with other cold rows
+     * is pure construction/eviction churn, so only currently free slots are
+     * admitted. Active row subscribers and incremental views are different:
+     * they must observe every addition even when the cache is bounded, so
+     * those batches opt out of admission limiting.
+     */
+    wireAddRetentionLimit(modelNames: ReadonlySet<string>): number | undefined;
     constructor(config?: PoolConfig, modelRegistry?: ModelRegistry);
     private resolveModel;
     get<T extends Model = Model>(id: string): T | undefined;

package/dist/local/InstanceCache.js

@@ -111,6 +111,26 @@ export class InstanceCache {
             }
         }
     }
+    /**
+     * Maximum fresh wire rows worth constructing from one atomic apply batch.
+     *
+     * A headless cache has no recency signal: every never-read resident is
+     * equally useful, while the local database remains the authoritative full
+     * state. Once that cache is full, replacing cold rows with other cold rows
+     * is pure construction/eviction churn, so only currently free slots are
+     * admitted. Active row subscribers and incremental views are different:
+     * they must observe every addition even when the cache is bounded, so
+     * those batches opt out of admission limiting.
+     */
+    wireAddRetentionLimit(modelNames) {
+        for (const modelName of modelNames) {
+            if ((this.subscriptions.get(modelName)?.size ?? 0) > 0 ||
+                this.viewRegistry.hasViews(modelName)) {
+                return undefined;
+            }
+        }
+        return Math.max(0, this.config.maxSize - this.entries.size);
+    }
     constructor(config = {}, modelRegistry) {
         this.config = {
             maxSize: config.maxSize ?? 10000,

package/dist/local/SyncClient.d.ts

@@ -483,6 +483,17 @@ export declare class SyncClient extends EventEmitter {
      */
     getMutationQueue(): MutationQueue;
     applyDeltaBatchToPool(dbResults: readonly AppliedChange[], enrichRelations: (modelName: string, data: Record<string, unknown>) => Record<string, unknown>): void;
+    /**
+     * Drop fresh adds beyond a headless cache's currently free capacity. The
+     * rows are already durable; with no row-level consumer there is no recency
+     * signal that makes replacing one cold resident with another useful, so the
+     * projection avoids constructing thousands of doomed Model/MobX objects.
+     *
+     * This must run before apply slicing. A 300k catch-up batch is revealed in
+     * ~600-delta slices, each smaller than the 10k cache cap; projecting each
+     * slice independently would therefore miss the redundant work entirely.
+     */
+    projectDeltaBatchForPool(dbResults: readonly AppliedChange[]): readonly AppliedChange[];
     private applyDeltaBatchToPoolInAction;
     /**
      * Apply bootstrap data to the InstanceCache with ghost removal.

package/dist/local/SyncClient.js

@@ -1525,6 +1525,7 @@ export class SyncClient extends EventEmitter {
         return this.mutationQueue;
     }
     applyDeltaBatchToPool(dbResults, enrichRelations) {
+        const projectedResults = this.projectDeltaBatchForPool(dbResults);
         // The WHOLE batch — conflict resolution and model mutation included, not
         // just the pool bookkeeping at the end — runs in one MobX action.
         // `resolveConflicts` writes model fields via `updateFromData`; when those
@@ -1533,7 +1534,50 @@ export class SyncClient extends EventEmitter {
         // reaction pass per delta and an observer could see a partially applied
         // frame between them.
         runInAction(() => {
-            this.applyDeltaBatchToPoolInAction(dbResults, enrichRelations);
+            this.applyDeltaBatchToPoolInAction(projectedResults, enrichRelations);
+        });
+    }
+    /**
+     * Drop fresh adds beyond a headless cache's currently free capacity. The
+     * rows are already durable; with no row-level consumer there is no recency
+     * signal that makes replacing one cold resident with another useful, so the
+     * projection avoids constructing thousands of doomed Model/MobX objects.
+     *
+     * This must run before apply slicing. A 300k catch-up batch is revealed in
+     * ~600-delta slices, each smaller than the 10k cache cap; projecting each
+     * slice independently would therefore miss the redundant work entirely.
+     */
+    projectDeltaBatchForPool(dbResults) {
+        const idsBeingRemoved = new Set();
+        const freshAddTypes = new Set();
+        let freshAddCount = 0;
+        for (const result of dbResults) {
+            if (result.action === 'remove')
+                idsBeingRemoved.add(result.modelId);
+        }
+        for (const result of dbResults) {
+            if (result.action === 'add' &&
+                result.data &&
+                !idsBeingRemoved.has(result.modelId) &&
+                !this.objectPool.has(result.modelId)) {
+                freshAddTypes.add(result.modelName);
+                freshAddCount++;
+            }
+        }
+        const retentionLimit = this.objectPool.wireAddRetentionLimit(freshAddTypes);
+        let freshAddsToDiscard = retentionLimit === undefined ? 0 : Math.max(0, freshAddCount - retentionLimit);
+        if (freshAddsToDiscard === 0)
+            return dbResults;
+        return dbResults.filter((result) => {
+            if (freshAddsToDiscard > 0 &&
+                result.action === 'add' &&
+                result.data &&
+                !idsBeingRemoved.has(result.modelId) &&
+                !this.objectPool.has(result.modelId)) {
+                freshAddsToDiscard--;
+                return false;
+            }
+            return true;
         });
     }
     applyDeltaBatchToPoolInAction(dbResults, enrichRelations) {

package/dist/local/sync/deltaPipeline.d.ts

@@ -60,6 +60,8 @@ export interface DeltaPipelineContext {
     }>;
     /** Applies persisted delta results to the in-memory pool, with the host's relation enrichment bound. */
     applyDeltaBatchToPool(results: AppliedChange[]): void;
+    /** Optional whole-batch projection performed before bounded apply slicing. */
+    projectDeltaBatchForPool?(results: readonly AppliedChange[]): readonly AppliedChange[];
     /** Acknowledges a sync id back to the server; a no-op when the socket is down. */
     acknowledge(syncId: number): void;
     readonly objectPool: {

package/dist/local/sync/deltaPipeline.js

@@ -437,7 +437,8 @@ async function flushDeltaBatchInner(ctx, queuedDeltas) {
     // synchronous block. Each slice is still one MobX action (reactions fire
     // once per slice), and a transaction never splits across slices — the
     // commit remains the atomic unit of visibility.
-    const slices = sliceApplyChanges(dbResults, ctx.smartSyncOptions.applySliceDeltas);
+    const poolResults = ctx.projectDeltaBatchForPool?.(dbResults) ?? dbResults;
+    const slices = sliceApplyChanges(poolResults, ctx.smartSyncOptions.applySliceDeltas);
     await timeDrainStageAsync('apply', async () => {
         const hasApplyPlugins = pluginsForStage(stagePlugins, 'apply').length > 0;
         // Yield on a TIME budget, not per slice: a host yield costs milliseconds

package/dist/local/views/ViewRegistry.d.ts

@@ -11,6 +11,7 @@ export declare class ViewRegistry {
     private views;
     register(typename: string, view: IncrementalView): void;
     unregister(typename: string, view: IncrementalView): void;
+    hasViews(typename: string): boolean;
     /** Called by InstanceCache after a model is added to the pool. */
     notifyAdded(typename: string, model: Model): void;
     /** Called by InstanceCache after a model is updated in the pool. */

package/dist/local/views/ViewRegistry.js

@@ -25,6 +25,9 @@ export class ViewRegistry {
             this.views.delete(typename);
         }
     }
+    hasViews(typename) {
+        return (this.views.get(typename)?.size ?? 0) > 0;
+    }
     /** Called by InstanceCache after a model is added to the pool. */
     notifyAdded(typename, model) {
         const set = this.views.get(typename);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/humans",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "description": "The optional human-facing local-state package for Ablo: presence, live queries, and React bindings.",
   "license": "Apache-2.0",
   "type": "module",
@@ -84,7 +84,7 @@
     "directory": "packages/humans"
   },
   "dependencies": {
-    "@abloatai/transaction": "^0.42.0",
+    "@abloatai/transaction": "^0.43.0",
     "mobx": "^6.13.7",
     "uuid": "^11.1.0",
     "zod": "^4.4.3"

package/src/local/BaseSyncedStore.ts

@@ -1568,6 +1568,8 @@ export class BaseSyncedStore<
       advancePersisted: (syncId) => { this.syncClient.position.advancePersisted(syncId); },
       // Persistence + pool writes.
       processDeltaBatch: (deltas) => this.database.processDeltaBatch(deltas),
+      projectDeltaBatchForPool: (results) =>
+        this.syncClient.projectDeltaBatchForPool(results),
       applyDeltaBatchToPool: (results) => { this.applyChangesToPool(results); },
       acknowledge: (syncId) => { this.syncWebSocket.acknowledge(syncId); },
       get objectPool() { return store.objectPool; },

package/src/local/InstanceCache.ts

@@ -162,6 +162,29 @@ export class InstanceCache {
     }
   }
 
+  /**
+   * Maximum fresh wire rows worth constructing from one atomic apply batch.
+   *
+   * A headless cache has no recency signal: every never-read resident is
+   * equally useful, while the local database remains the authoritative full
+   * state. Once that cache is full, replacing cold rows with other cold rows
+   * is pure construction/eviction churn, so only currently free slots are
+   * admitted. Active row subscribers and incremental views are different:
+   * they must observe every addition even when the cache is bounded, so
+   * those batches opt out of admission limiting.
+   */
+  wireAddRetentionLimit(modelNames: ReadonlySet<string>): number | undefined {
+    for (const modelName of modelNames) {
+      if (
+        (this.subscriptions.get(modelName)?.size ?? 0) > 0 ||
+        this.viewRegistry.hasViews(modelName)
+      ) {
+        return undefined;
+      }
+    }
+    return Math.max(0, this.config.maxSize - this.entries.size);
+  }
+
   constructor(config: PoolConfig = {}, modelRegistry?: ModelRegistry) {
     this.config = {
       maxSize: config.maxSize ?? 10000,

package/src/local/SyncClient.ts

@@ -1889,6 +1889,7 @@ export class SyncClient extends EventEmitter {
     dbResults: readonly AppliedChange[],
     enrichRelations: (modelName: string, data: Record<string, unknown>) => Record<string, unknown>,
   ): void {
+    const projectedResults = this.projectDeltaBatchForPool(dbResults);
     // The WHOLE batch — conflict resolution and model mutation included, not
     // just the pool bookkeeping at the end — runs in one MobX action.
     // `resolveConflicts` writes model fields via `updateFromData`; when those
@@ -1897,7 +1898,57 @@ export class SyncClient extends EventEmitter {
     // reaction pass per delta and an observer could see a partially applied
     // frame between them.
     runInAction(() => {
-      this.applyDeltaBatchToPoolInAction(dbResults, enrichRelations);
+      this.applyDeltaBatchToPoolInAction(projectedResults, enrichRelations);
+    });
+  }
+
+  /**
+   * Drop fresh adds beyond a headless cache's currently free capacity. The
+   * rows are already durable; with no row-level consumer there is no recency
+   * signal that makes replacing one cold resident with another useful, so the
+   * projection avoids constructing thousands of doomed Model/MobX objects.
+   *
+   * This must run before apply slicing. A 300k catch-up batch is revealed in
+   * ~600-delta slices, each smaller than the 10k cache cap; projecting each
+   * slice independently would therefore miss the redundant work entirely.
+   */
+  projectDeltaBatchForPool(
+    dbResults: readonly AppliedChange[],
+  ): readonly AppliedChange[] {
+    const idsBeingRemoved = new Set<string>();
+    const freshAddTypes = new Set<string>();
+    let freshAddCount = 0;
+    for (const result of dbResults) {
+      if (result.action === 'remove') idsBeingRemoved.add(result.modelId);
+    }
+    for (const result of dbResults) {
+      if (
+        result.action === 'add' &&
+        result.data &&
+        !idsBeingRemoved.has(result.modelId) &&
+        !this.objectPool.has(result.modelId)
+      ) {
+        freshAddTypes.add(result.modelName);
+        freshAddCount++;
+      }
+    }
+    const retentionLimit = this.objectPool.wireAddRetentionLimit(freshAddTypes);
+    let freshAddsToDiscard =
+      retentionLimit === undefined ? 0 : Math.max(0, freshAddCount - retentionLimit);
+    if (freshAddsToDiscard === 0) return dbResults;
+
+    return dbResults.filter((result) => {
+      if (
+        freshAddsToDiscard > 0 &&
+        result.action === 'add' &&
+        result.data &&
+        !idsBeingRemoved.has(result.modelId) &&
+        !this.objectPool.has(result.modelId)
+      ) {
+        freshAddsToDiscard--;
+        return false;
+      }
+      return true;
     });
   }
 

package/src/local/sync/deltaPipeline.ts

@@ -85,6 +85,8 @@ export interface DeltaPipelineContext {
   ): Promise<{ results: AppliedChange[]; persistedSyncId: number }>;
   /** Applies persisted delta results to the in-memory pool, with the host's relation enrichment bound. */
   applyDeltaBatchToPool(results: AppliedChange[]): void;
+  /** Optional whole-batch projection performed before bounded apply slicing. */
+  projectDeltaBatchForPool?(results: readonly AppliedChange[]): readonly AppliedChange[];
   /** Acknowledges a sync id back to the server; a no-op when the socket is down. */
   acknowledge(syncId: number): void;
 
@@ -572,7 +574,8 @@ async function flushDeltaBatchInner(
   // synchronous block. Each slice is still one MobX action (reactions fire
   // once per slice), and a transaction never splits across slices — the
   // commit remains the atomic unit of visibility.
-  const slices = sliceApplyChanges(dbResults, ctx.smartSyncOptions.applySliceDeltas);
+  const poolResults = ctx.projectDeltaBatchForPool?.(dbResults) ?? dbResults;
+  const slices = sliceApplyChanges(poolResults, ctx.smartSyncOptions.applySliceDeltas);
   await timeDrainStageAsync('apply', async () => {
     const hasApplyPlugins = pluginsForStage(stagePlugins, 'apply').length > 0;
     // Yield on a TIME budget, not per slice: a host yield costs milliseconds

package/src/local/views/ViewRegistry.ts

@@ -30,6 +30,10 @@ export class ViewRegistry {
     }
   }
 
+  hasViews(typename: string): boolean {
+    return (this.views.get(typename)?.size ?? 0) > 0;
+  }
+
   /** Called by InstanceCache after a model is added to the pool. */
   notifyAdded(typename: string, model: Model): void {
     const set = this.views.get(typename);