@abloatai/humans 0.38.0 → 0.39.0

package/src/local/SyncClient.ts

@@ -1290,34 +1290,25 @@ export class SyncClient extends EventEmitter {
    * local model has unsynced changes, so the two sides stay consistent.
    */
   resolveConflicts(localModel: Model, serverData: Record<string, unknown>): Model {
-    const hasLocalChanges = localModel.hasChanges;
-    // Safely get timestamp, handling both Date objects and strings
-    const localUpdatedAt = localModel.updatedAt
-      ? localModel.updatedAt instanceof Date
-        ? localModel.updatedAt.getTime()
-        : new Date(localModel.updatedAt).getTime()
-      : 0;
-    const serverUpdatedAt = toEpochMs(serverData.updatedAt);
-
-    this.runtime.logger.debug('Conflict resolution', {
-      modelId: localModel.id,
-      modelType: localModel.getModelName(),
-      hasLocalChanges,
-      localUpdatedAt: localModel.updatedAt?.toString(),
-      serverUpdatedAt: serverData.updatedAt,
-      localChanges: localModel.getChanges(),
-      serverState: this.extractCriticalState(serverData),
-    });
-
-    // PRIORITY 1: Check for critical server states that must be respected
-    // These states override any local changes to maintain data consistency
-    const criticalServerStates = this.extractCriticalState(serverData);
-    const shouldForceAcceptServer = this.hasCriticalStateChange(criticalServerStates);
+    // No entry-point debug here: this runs once per incoming update delta,
+    // and a debug call's payload is BUILT even when the logger discards it —
+    // a per-delta model scan on the apply hot path. The outcome branches
+    // below log the cases worth reading.
+
+    // PRIORITY 1: Check for critical server states that must be respected.
+    // These states override any local changes to maintain data consistency.
+    // Checked inline — the collected-object form (`extractCriticalState`)
+    // only materializes on the rare force-accept branch, for its log line.
+    const shouldForceAcceptServer =
+      (serverData.deletedAt !== undefined && serverData.deletedAt !== null) ||
+      (serverData.archivedAt !== undefined && serverData.archivedAt !== null) ||
+      serverData.isActive === false ||
+      (serverData.unassignedAt !== undefined && serverData.unassignedAt !== null);
 
     if (shouldForceAcceptServer) {
       this.runtime.logger.debug('Accepting server update - critical state change detected', {
         modelId: localModel.id,
-        criticalStates: criticalServerStates,
+        criticalStates: this.extractCriticalState(serverData),
       });
 
       // Force accept server state for critical changes
@@ -1329,7 +1320,7 @@ export class SyncClient extends EventEmitter {
 
     // Local-first: if we have local dirty fields, merge by field.
     // Keep locally changed fields; apply server for the rest.
-    if (hasLocalChanges) {
+    if (localModel.hasChanges) {
       const localChanges = localModel.getChanges();
       this.runtime.logger.debug('Merging server update with local dirty fields', {
         modelId: localModel.id,
@@ -1341,6 +1332,13 @@ export class SyncClient extends EventEmitter {
 
       // Preserve the most recent updatedAt without clearing dirty flags
       if (serverData.updatedAt || localModel.updatedAt) {
+        // Safely get timestamp, handling both Date objects and strings
+        const localUpdatedAt = localModel.updatedAt
+          ? localModel.updatedAt instanceof Date
+            ? localModel.updatedAt.getTime()
+            : new Date(localModel.updatedAt).getTime()
+          : 0;
+        const serverUpdatedAt = toEpochMs(serverData.updatedAt);
         const mergedUpdatedAt = new Date(Math.max(localUpdatedAt, serverUpdatedAt));
         // updateFromData accepts Date or ISO string for dates
         merged.updatedAt = mergedUpdatedAt;
@@ -1351,10 +1349,9 @@ export class SyncClient extends EventEmitter {
       return localModel;
     }
 
-    // No local changes: fall back to LWW to converge
-    // Accept server regardless of timestamp equality to stay in sync
-    const acceptReason = serverUpdatedAt > localUpdatedAt ? 'server is newer' : 'no local changes';
-    this.runtime.logger.debug(`Accepting server update - ${acceptReason}`);
+    // No local changes: fall back to LWW to converge. Accept server
+    // regardless of timestamp equality to stay in sync. Not logged — this is
+    // the common path for every collaborator update a client receives.
     localModel.updateFromData(serverData);
     localModel.clearChanges();
     localModel.markAsSynced();
@@ -1392,17 +1389,6 @@ export class SyncClient extends EventEmitter {
     return critical;
   }
 
-  /**
-   * Check if critical state changes exist that require forcing server state
-   */
-  private hasCriticalStateChange(criticalStates: Record<string, unknown>): boolean {
-    // Any critical state present means we should force accept server
-    return (
-      Object.keys(criticalStates).length > 0 &&
-      Object.values(criticalStates).some((v) => v !== null && v !== undefined)
-    );
-  }
-
   /**
    * Handle network reconnection
    */
@@ -1901,6 +1887,22 @@ export class SyncClient extends EventEmitter {
   applyDeltaBatchToPool(
     dbResults: readonly AppliedChange[],
     enrichRelations: (modelName: string, data: Record<string, unknown>) => Record<string, unknown>,
+  ): void {
+    // 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
+    // writes ran before the action, every delta opened its own top-level
+    // action and flushed reactions at its boundary, so a large frame paid one
+    // reaction pass per delta and an observer could see a partially applied
+    // frame between them.
+    runInAction(() => {
+      this.applyDeltaBatchToPoolInAction(dbResults, enrichRelations);
+    });
+  }
+
+  private applyDeltaBatchToPoolInAction(
+    dbResults: readonly AppliedChange[],
+    enrichRelations: (modelName: string, data: Record<string, unknown>) => Record<string, unknown>,
   ): void {
     const modelsToAdd: Model[] = [];
     const modelsToUpsert: Model[] = [];
@@ -2002,27 +2004,21 @@ export class SyncClient extends EventEmitter {
       }
     }
 
-    // Reveal the whole frame in a single MobX action. `addBatch`,
-    // `upsertBatch`, `removeBatch`, and `updateScope` are each individually
-    // wrapped in an action, so calling them in sequence flushes reactions at
-    // every action boundary — a catch-up frame that adds, updates, and removes
-    // would fire every dependent reaction several times in a row, re-rendering
-    // and re-sorting on each. Wrapping them in one outer `runInAction` defers
-    // all reaction flushes to a single boundary, so dependents recompute
-    // exactly once regardless of how many models or operation kinds the frame
-    // touched. The app therefore never observes a partially applied frame.
-    runInAction(() => {
-      if (modelsToAdd.length > 0) this.objectPool.addBatch(modelsToAdd, ModelScope.live);
-      if (modelsToUpsert.length > 0) this.objectPool.upsertBatch(modelsToUpsert, ModelScope.live);
-      if (idsToRemove.length > 0) this.objectPool.removeBatch(idsToRemove);
-      for (const id of idsToArchive) this.objectPool.updateScope(id, ModelScope.archived);
-
-      // Emit changed model types so QueryProcessor can auto-invalidate.
-      // Kept inside the action so any observable query-cache state it
-      // flips is part of the same atomic reveal.
-      const changedTypes = new Set(dbResults.map(r => r.modelName));
-      if (changedTypes.size > 0) this.emit('models:changed', changedTypes);
-    });
+    // Reveal the whole frame at one reaction boundary: the caller's single
+    // action covers the collection loop above and these batch pool writes, so
+    // dependents recompute exactly once regardless of how many models or
+    // operation kinds the frame touched, and the app never observes a
+    // partially applied frame.
+    if (modelsToAdd.length > 0) this.objectPool.addBatch(modelsToAdd, ModelScope.live);
+    if (modelsToUpsert.length > 0) this.objectPool.upsertBatch(modelsToUpsert, ModelScope.live);
+    if (idsToRemove.length > 0) this.objectPool.removeBatch(idsToRemove);
+    for (const id of idsToArchive) this.objectPool.updateScope(id, ModelScope.archived);
+
+    // Emit changed model types so QueryProcessor can auto-invalidate.
+    // Kept inside the action so any observable query-cache state it
+    // flips is part of the same atomic reveal.
+    const changedTypes = new Set(dbResults.map(r => r.modelName));
+    if (changedTypes.size > 0) this.emit('models:changed', changedTypes);
   }
 
   /**

package/src/local/client/reactiveEngine.ts

@@ -13,6 +13,7 @@
  */
 
 import type { Schema, SchemaRecord } from '@abloatai/transaction/schema/schema';
+import { omittedModelError } from '@abloatai/transaction/schema/select';
 import {
   durableCommitOperationSchema,
   type DurableCommitOperation,
@@ -934,5 +935,22 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
     },
   } as Ablo<S>;
 
+  // A model the schema projection left out answers with an error naming the
+  // model and the fix, not `undefined`. An app can compile against the full
+  // source schema while running a projection, so the type system never sees
+  // this gap; without the stub the caller crashes one property later with a
+  // bare TypeError ("reading 'local'") that names neither. Non-enumerable so
+  // spread, Object.keys, and JSON.stringify walk past the stubs untriggered.
+  for (const name of schema.omittedModels ?? []) {
+    if (name in engine) continue;
+    Object.defineProperty(engine, name, {
+      get() {
+        throw omittedModelError(name);
+      },
+      enumerable: false,
+      configurable: true,
+    });
+  }
+
   return engine;
 }

package/src/local/sync/SyncWebSocket.ts

@@ -272,12 +272,9 @@ export class SyncWebSocket<
   protected override handleDelta(rawDelta: unknown): void {
     const delta = this.normalizeWireDelta(rawDelta);
     if (!delta) return;
-    getContext().logger.debug('Received delta', {
-      action: delta.actionType,
-      model: delta.modelName,
-      id: delta.modelId,
-      syncId: delta.id,
-    });
+    // No per-delta debug here: the payload object is built even when the
+    // logger discards it, and this runs at the full live wire rate. Dropped
+    // malformed deltas are still logged by `normalizeWireDelta`.
 
     // Do not advance `this.cursor.lastSyncId` on receipt. The runtime cursor
     // must stay consistent with what has been persisted locally; otherwise the

package/src/local/sync/deltaPipeline.ts

@@ -24,7 +24,14 @@ import {
   type AbloPlugin,
   type AppliedChange,
 } from '../../plugin.js';
-import { observeDrainBatch, timeDrainStage, timeDrainStageAsync } from './drainProfile.js';
+import {
+  observeDrainBatch,
+  observeDrainAcknowledge,
+  timeDrainStage,
+  timeDrainStageAsync,
+  openDrainBatchRow,
+  closeDrainBatchRow,
+} from './drainProfile.js';
 
 /**
  * What the pipeline needs back from the surrounding store: the shared mutable
@@ -408,6 +415,18 @@ function yieldToHost(): Promise<void> {
 async function flushDeltaBatch(
   ctx: DeltaPipelineContext,
   queuedDeltas: SyncDelta[],
+): Promise<void> {
+  openDrainBatchRow(queuedDeltas.length);
+  try {
+    await flushDeltaBatchInner(ctx, queuedDeltas);
+  } finally {
+    closeDrainBatchRow();
+  }
+}
+
+async function flushDeltaBatchInner(
+  ctx: DeltaPipelineContext,
+  queuedDeltas: SyncDelta[],
 ): Promise<void> {
   const stagePlugins = ctx.stagePlugins ?? [];
   const deduplicatedDeltas = timeDrainStage('dedupe', () => ctx.deduplicateDeltas(queuedDeltas));
@@ -489,6 +508,7 @@ async function flushDeltaBatch(
     timeDrainStage('acknowledge', () => {
       ctx.acknowledge(persistedSyncId);
       ctx.advancePersisted(persistedSyncId);
+      observeDrainAcknowledge(persistedSyncId);
       runStage(stagePlugins, 'acknowledge', { syncId: persistedSyncId });
     });
   }

package/src/local/sync/drainProfile.ts

@@ -32,6 +32,19 @@ export interface DrainStageTotals {
   readonly calls: number;
 }
 
+/**
+ * One flush batch on the wall clock. Wall time (`Date.now`) rather than
+ * `performance.now`, because rows cross the worker boundary and each thread
+ * has its own `performance` origin — the drain-tail stamps learned the same
+ * lesson. Stage entries are the batch's own share of each pipeline stage.
+ */
+export interface DrainBatchRow {
+  readonly startedAtWallMs: number;
+  readonly endedAtWallMs: number;
+  readonly deltas: number;
+  readonly stages: Readonly<Partial<Record<DrainStage, number>>>;
+}
+
 export interface DrainProfile {
   /** Flush batches drained. The per-batch fixed cost multiplies by this. */
   readonly batches: number;
@@ -42,6 +55,12 @@ export interface DrainProfile {
   /** Wall time from the first observed stage to the last. */
   readonly spanMs: number;
   readonly stages: Readonly<Record<DrainStage, DrainStageTotals>>;
+  /**
+   * The most recent flush batches, oldest first, capped — enough to cover a
+   * drain tail. Optional because derived profiles (window subtraction, fleet
+   * merges) drop it; only a worker's own snapshot carries rows.
+   */
+  readonly recentBatches?: readonly DrainBatchRow[];
 }
 
 const DRAIN_STAGES: readonly DrainStage[] = [
@@ -72,6 +91,73 @@ let deduplicated = 0;
 let firstMark: number | undefined;
 let lastMark = 0;
 
+/** Ring of recent batch rows. ~50 batches/sec at benchmark rates, so this covers seconds of tail. */
+const BATCH_ROW_CAP = 128;
+let batchRows: DrainBatchRow[] = [];
+interface OpenBatchRow {
+  startedAtWallMs: number;
+  deltas: number;
+  stages: Partial<Record<DrainStage, number>>;
+}
+/**
+ * The batch currently being flushed. Module-global like the totals above, so
+ * an isolate hosting several stores attributes interleaved awaits to whichever
+ * batch is open — the same per-isolate approximation the totals already make.
+ */
+let currentRow: OpenBatchRow | null = null;
+
+/**
+ * Wall-stamped persisted-cursor advances, oldest first. The benchmark's drain
+ * gate reads THESE rather than observing the cursor from a timer or a
+ * cross-thread poll: any observation that has to be scheduled onto the
+ * worker's event loop queues behind the very drain burst it is measuring and
+ * reports the queue's latency as drain. A stamp taken synchronously inside
+ * the acknowledge stage cannot be deferred by anything.
+ */
+export interface AcknowledgeStamp {
+  readonly syncId: number;
+  readonly atWallMs: number;
+}
+const ACK_STAMP_CAP = 512;
+let ackStamps: AcknowledgeStamp[] = [];
+
+/**
+ * Record a persisted-cursor advance. Called by the pipeline's acknowledge
+ * stage. Unlike every stage timer here, this is NOT gated on the profiler
+ * flag: it is one wall-clock read and one bounded push per flush batch —
+ * nothing against the batch's own work — and the certification benchmark
+ * runs unprofiled (the profiler costs ~15%), so the honest drain stamp must
+ * exist without it.
+ */
+export function observeDrainAcknowledge(syncId: number): void {
+  ackStamps.push({ syncId, atWallMs: Date.now() });
+  if (ackStamps.length > ACK_STAMP_CAP) ackStamps.shift();
+}
+
+/** The recorded persisted-advance stamps, oldest first. */
+export function drainAcknowledgeStamps(): readonly AcknowledgeStamp[] {
+  return [...ackStamps];
+}
+
+/** Begin a batch row. Called by the pipeline at flush entry when profiling. */
+export function openDrainBatchRow(deltaCount: number): void {
+  if (!enabled) return;
+  currentRow = { startedAtWallMs: Date.now(), deltas: deltaCount, stages: {} };
+}
+
+/** Close the open batch row and commit it to the ring. */
+export function closeDrainBatchRow(): void {
+  if (!enabled || currentRow === null) return;
+  batchRows.push({
+    startedAtWallMs: currentRow.startedAtWallMs,
+    endedAtWallMs: Date.now(),
+    deltas: currentRow.deltas,
+    stages: currentRow.stages,
+  });
+  if (batchRows.length > BATCH_ROW_CAP) batchRows.shift();
+  currentRow = null;
+}
+
 /**
  * Read once. A profiler that consults the environment on every delta would
  * itself become a per-delta cost in the path it is measuring.
@@ -98,6 +184,9 @@ export function observeDrainStage(stage: DrainStage, elapsedMs: number): void {
   const entry = totals[stage];
   entry.totalMs += elapsedMs;
   entry.calls += 1;
+  if (currentRow !== null) {
+    currentRow.stages[stage] = (currentRow.stages[stage] ?? 0) + elapsedMs;
+  }
   mark(elapsedMs);
 }
 
@@ -150,6 +239,7 @@ export function drainProfileSnapshot(): DrainProfile {
     deduplicated,
     spanMs: firstMark === undefined ? 0 : lastMark - firstMark,
     stages,
+    recentBatches: [...batchRows],
   };
 }
 
@@ -161,4 +251,7 @@ export function resetDrainProfile(): void {
   deduplicated = 0;
   firstMark = undefined;
   lastMark = 0;
+  batchRows = [];
+  currentRow = null;
+  ackStamps = [];
 }