@abloatai/humans 0.38.0 → 0.40.0

package/dist/local/SyncClient.d.ts

@@ -275,10 +275,6 @@ export declare class SyncClient extends EventEmitter {
      * conflict resolver reads exactly these fields and no others.
      */
     private extractCriticalState;
-    /**
-     * Check if critical state changes exist that require forcing server state
-     */
-    private hasCriticalStateChange;
     /**
      * Handle network reconnection
      */
@@ -487,6 +483,7 @@ export declare class SyncClient extends EventEmitter {
      */
     getMutationQueue(): MutationQueue;
     applyDeltaBatchToPool(dbResults: readonly AppliedChange[], enrichRelations: (modelName: string, data: Record<string, unknown>) => Record<string, unknown>): void;
+    private applyDeltaBatchToPoolInAction;
     /**
      * Apply bootstrap data to the InstanceCache with ghost removal.
      * Owns: model creation, batch upsert, ghost detection + removal.

package/dist/local/SyncClient.js

@@ -1038,31 +1038,22 @@ export class SyncClient extends EventEmitter {
      * local model has unsynced changes, so the two sides stay consistent.
      */
     resolveConflicts(localModel, serverData) {
-        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
             localModel.updateFromData(serverData);
@@ -1072,7 +1063,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,
@@ -1082,6 +1073,13 @@ export class SyncClient extends EventEmitter {
             const merged = { ...serverData, ...(localChanges || {}) };
             // 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;
@@ -1090,10 +1088,9 @@ export class SyncClient extends EventEmitter {
             // Intentionally DO NOT clearChanges here; pending tx will confirm and clear
             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();
@@ -1125,14 +1122,6 @@ export class SyncClient extends EventEmitter {
         }
         return critical;
     }
-    /**
-     * Check if critical state changes exist that require forcing server state
-     */
-    hasCriticalStateChange(criticalStates) {
-        // 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
      */
@@ -1536,6 +1525,18 @@ export class SyncClient extends EventEmitter {
         return this.mutationQueue;
     }
     applyDeltaBatchToPool(dbResults, enrichRelations) {
+        // 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);
+        });
+    }
+    applyDeltaBatchToPoolInAction(dbResults, enrichRelations) {
         const modelsToAdd = [];
         const modelsToUpsert = [];
         const idsToRemove = [];
@@ -1578,7 +1579,13 @@ export class SyncClient extends EventEmitter {
             }
             switch (action) {
                 case 'add': {
-                    const existing = this.objectPool.get(modelId);
+                    // `peek`, not `get`: this loop is ingestion, not a consumer read.
+                    // `get()` activates deferred MobX instrumentation, so reading
+                    // through it here made the delta stream itself instrument every
+                    // row it touched — the dominant term of apply cost for rows no
+                    // consumer observes. Activation belongs to the consumer-facing
+                    // reads (`get`, views, subscribers), which are unchanged.
+                    const existing = this.objectPool.peek(modelId);
                     if (existing) {
                         existing.markAsSynced();
                     }
@@ -1593,7 +1600,7 @@ export class SyncClient extends EventEmitter {
                     break;
                 }
                 case 'update': {
-                    const existing = this.objectPool.get(modelId);
+                    const existing = this.objectPool.peek(modelId);
                     if (existing && !existing.disposed && result.data) {
                         enrichRelations(modelName, result.data);
                         const resolved = this.resolveConflicts(existing, result.data);
@@ -1633,31 +1640,25 @@ export class SyncClient extends EventEmitter {
                     break;
             }
         }
-        // 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);
     }
     /**
      * Apply bootstrap data to the InstanceCache with ghost removal.

package/dist/local/client/reactiveEngine.js

@@ -11,6 +11,7 @@
  * host-built core client with the per-model surface split — the cut's own
  * design step (docs/plans/package-split.md).
  */
+import { omittedModelError } from '@abloatai/transaction/schema/select';
 import { durableCommitOperationSchema, } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
 import { AbloAuthenticationError, AbloConnectionError, AbloValidationError, claimedError } from '@abloatai/transaction/errors';
 import { batchFence, fenceTokenFor, modelTarget, streamTarget, subTarget, } from '@abloatai/transaction/coordination';
@@ -703,5 +704,22 @@ export function buildReactiveEngine(inputs) {
             });
         },
     };
+    // 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/dist/local/sync/SyncWebSocket.js

@@ -178,12 +178,9 @@ export class SyncWebSocket extends WsTransport {
         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
         // next `requestIncrementalSync()` (and the connect-time handshake) would

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

@@ -38,6 +38,7 @@ export interface DeltaPipelineContext {
     readonly smartSyncOptions: {
         readonly batchingDelay: number;
         readonly maxBatchSize: number;
+        readonly applySliceDeltas: number;
     };
     /** Pool-applied cursor (`syncClient.position.applied`). */
     readonly highestProcessedSyncId: number;
@@ -62,7 +63,8 @@ export interface DeltaPipelineContext {
     /** Acknowledges a sync id back to the server; a no-op when the socket is down. */
     acknowledge(syncId: number): void;
     readonly objectPool: {
-        get(id: string): Model | undefined;
+        /** Ingestion-side lookup — resolves without activating observability. */
+        peek(id: string): Model | undefined;
         add(model: Model, scope: ModelScope): void;
         remove(id: string): boolean;
         /** Full in-memory clear — the revocation-failure fallback (see
@@ -114,3 +116,32 @@ export declare function applyDeltaFrame(ctx: DeltaPipelineContext, deltas: SyncD
  * and advances the acknowledgement cursor once the store write has committed.
  */
 export declare function flushPendingDeltas(ctx: DeltaPipelineContext): Promise<void>;
+/**
+ * Wedge forensics: where the pipeline currently is, updated synchronously at
+ * every stage boundary. A hang diagnoses itself by which counter pair
+ * diverged and which phase the active flush froze in. Mirrored onto
+ * `globalThis.__abloPipelineDebug` so a bench watchdog in the same thread
+ * can read it without an import path into SDK internals — diagnostics only,
+ * a handful of numbers, no payload data.
+ */
+export declare const pipelineDebug: {
+    flushesStarted: number;
+    flushesSettled: number;
+    persistsStarted: number;
+    persistsSettled: number;
+    applySlices: number;
+    applyYields: number;
+    enqueued: number;
+    phase: string;
+};
+/**
+ * Split applied changes into slices of at most `maxDeltas`, never splitting a
+ * transaction: consecutive changes sharing a `transactionId` form one
+ * indivisible group (a commit reveals whole), while changes without one are
+ * individually splittable. A single transaction larger than the bound forms
+ * its own oversized slice, so apply always advances rather than stalling on
+ * an oversized commit — the same rule the server's publication chunking uses.
+ */
+export declare function sliceApplyChanges<T extends {
+    readonly transactionId?: string;
+}>(changes: readonly T[], maxDeltas: number): readonly T[][];

package/dist/local/sync/deltaPipeline.js

@@ -14,7 +14,7 @@ import { runInAction } from 'mobx';
 import { globalRuntime } from '../context.js';
 import { ModelScope } from '../InstanceCache.js';
 import { runStage, pluginsForStage, } from '../../plugin.js';
-import { observeDrainBatch, timeDrainStage, timeDrainStageAsync } from './drainProfile.js';
+import { observeDrainBatch, observeDrainAcknowledge, timeDrainStage, timeDrainStageAsync, openDrainBatchRow, closeDrainBatchRow, } from './drainProfile.js';
 /**
  * One drain per store. Incoming WebSocket frames may arrive while persistence
  * and pool application are awaiting. Without a single-flight guard every
@@ -199,6 +199,7 @@ export function enqueueDelta(ctx, delta, options = {}) {
     // The delta is accepted and queued — the `receive` stage boundary.
     runStage(ctx.stagePlugins ?? [], 'receive', { delta });
     ctx.pendingDeltas.push(delta);
+    pipelineDebug.enqueued += 1;
     return true;
 }
 /** Debounce a flush for live single-delta traffic. */
@@ -285,6 +286,68 @@ async function drainPendingDeltas(ctx) {
         ctx.batchTimer = null;
     }
 }
+/**
+ * Uninterrupted apply time allowed before the sliced loop yields — the
+ * "no visible stall" bound. Yields are amortized against it because one host
+ * yield costs milliseconds under load; at the measured per-delta apply cost
+ * this works out to roughly one yield per one to two 600-delta slices.
+ */
+const APPLY_YIELD_BUDGET_MS = 12;
+/**
+ * Wedge forensics: where the pipeline currently is, updated synchronously at
+ * every stage boundary. A hang diagnoses itself by which counter pair
+ * diverged and which phase the active flush froze in. Mirrored onto
+ * `globalThis.__abloPipelineDebug` so a bench watchdog in the same thread
+ * can read it without an import path into SDK internals — diagnostics only,
+ * a handful of numbers, no payload data.
+ */
+export const pipelineDebug = {
+    flushesStarted: 0,
+    flushesSettled: 0,
+    persistsStarted: 0,
+    persistsSettled: 0,
+    applySlices: 0,
+    applyYields: 0,
+    enqueued: 0,
+    phase: 'idle',
+};
+globalThis.__abloPipelineDebug =
+    pipelineDebug;
+/**
+ * Split applied changes into slices of at most `maxDeltas`, never splitting a
+ * transaction: consecutive changes sharing a `transactionId` form one
+ * indivisible group (a commit reveals whole), while changes without one are
+ * individually splittable. A single transaction larger than the bound forms
+ * its own oversized slice, so apply always advances rather than stalling on
+ * an oversized commit — the same rule the server's publication chunking uses.
+ */
+export function sliceApplyChanges(changes, maxDeltas) {
+    if (changes.length <= maxDeltas)
+        return changes.length > 0 ? [[...changes]] : [];
+    const slices = [];
+    let current = [];
+    let index = 0;
+    while (index < changes.length) {
+        // The indivisible unit starting here: one transaction's run, or a single
+        // untransacted change.
+        const transactionId = changes[index].transactionId;
+        let end = index + 1;
+        if (transactionId !== undefined) {
+            while (end < changes.length && changes[end].transactionId === transactionId)
+                end += 1;
+        }
+        const groupSize = end - index;
+        if (current.length > 0 && current.length + groupSize > maxDeltas) {
+            slices.push(current);
+            current = [];
+        }
+        current.push(...changes.slice(index, end));
+        index = end;
+    }
+    if (current.length > 0)
+        slices.push(current);
+    return slices;
+}
 function yieldToHost() {
     const immediate = globalThis.setImmediate;
     return new Promise((resolve) => {
@@ -295,7 +358,20 @@ function yieldToHost() {
     });
 }
 async function flushDeltaBatch(ctx, queuedDeltas) {
+    openDrainBatchRow(queuedDeltas.length);
+    pipelineDebug.flushesStarted += 1;
+    try {
+        await flushDeltaBatchInner(ctx, queuedDeltas);
+    }
+    finally {
+        pipelineDebug.flushesSettled += 1;
+        pipelineDebug.phase = 'idle';
+        closeDrainBatchRow();
+    }
+}
+async function flushDeltaBatchInner(ctx, queuedDeltas) {
     const stagePlugins = ctx.stagePlugins ?? [];
+    pipelineDebug.phase = 'dedupe';
     const deduplicatedDeltas = timeDrainStage('dedupe', () => ctx.deduplicateDeltas(queuedDeltas));
     observeDrainBatch(queuedDeltas.length, deduplicatedDeltas.length);
     runStage(stagePlugins, 'dedupe', { deltas: deduplicatedDeltas });
@@ -311,7 +387,7 @@ async function flushDeltaBatch(ctx, queuedDeltas) {
                 // gained permission to see the entity, so we insert it into the
                 // pool as if newly created.
                 if (delta.actionType === 'I' || delta.actionType === 'U' || delta.actionType === 'C') {
-                    const existing = ctx.objectPool.get(delta.modelId);
+                    const existing = ctx.objectPool.peek(delta.modelId);
                     if (existing) {
                         existing.updateFromData(data);
                     }
@@ -334,6 +410,8 @@ async function flushDeltaBatch(ctx, queuedDeltas) {
     // handleGroupRemoved) and never reach here, though the persistence
     // signature accepts them defensively.
     const regularDeltas = deduplicatedDeltas.filter((d) => !ctx.isCustomEntity(d.modelName));
+    pipelineDebug.phase = 'persist';
+    pipelineDebug.persistsStarted += 1;
     const batch = await timeDrainStageAsync('persist', () => ctx.processDeltaBatch(regularDeltas.map((d) => ({
         syncId: d.id,
         actionType: d.actionType,
@@ -344,6 +422,7 @@ async function flushDeltaBatch(ctx, queuedDeltas) {
         // echoes of locally-applied transactions and skip the pool mutation.
         transactionId: d.transactionId,
     }))));
+    pipelineDebug.persistsSettled += 1;
     const dbResults = batch.results;
     runStage(stagePlugins, 'persist', { deltas: regularDeltas });
     // Apply the batch results to the in-memory graph. When a plugin has
@@ -351,14 +430,42 @@ async function flushDeltaBatch(ctx, queuedDeltas) {
     // materialiser attached where it said it would. The direct call is the
     // bridge for stores constructed without plugins (subclasses, tests),
     // whose own apply is the whole pipeline.
-    timeDrainStage('apply', () => {
-        if (pluginsForStage(stagePlugins, 'apply').length > 0) {
-            runStage(stagePlugins, 'apply', { changes: dbResults });
-        }
-        else {
-            ctx.applyDeltaBatchToPool(dbResults);
+    //
+    // Large batches apply in TIME SLICES: split at transaction boundaries into
+    // bounded chunks with the event loop yielded between them, so a catch-up
+    // wave reveals commit-by-commit instead of holding the thread for one long
+    // 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);
+    await timeDrainStageAsync('apply', async () => {
+        const hasApplyPlugins = pluginsForStage(stagePlugins, 'apply').length > 0;
+        // Yield on a TIME budget, not per slice: a host yield costs milliseconds
+        // under load (measured ~7x throughput collapse when yielding every few
+        // deltas), so the yield decision amortizes it — only after the budget of
+        // uninterrupted apply work has been spent, and never before the first
+        // slice. Slices stay the atomicity unit; the budget only decides where
+        // the loop breathes.
+        let sliceStartedAt = performance.now();
+        for (let index = 0; index < slices.length; index++) {
+            if (index > 0 && performance.now() - sliceStartedAt > APPLY_YIELD_BUDGET_MS) {
+                pipelineDebug.phase = `apply-yield-${index}`;
+                pipelineDebug.applyYields += 1;
+                await yieldToHost();
+                sliceStartedAt = performance.now();
+            }
+            pipelineDebug.phase = `apply-slice-${index}`;
+            pipelineDebug.applySlices += 1;
+            const slice = slices[index];
+            if (hasApplyPlugins) {
+                runStage(stagePlugins, 'apply', { changes: slice });
+            }
+            else {
+                ctx.applyDeltaBatchToPool(slice);
+            }
         }
     });
+    pipelineDebug.phase = 'acknowledge';
     // Acknowledge and advance the sync cursor, gated on persistence.
     //
     // We must acknowledge `persistedSyncId` — the high-water mark of deltas whose
@@ -372,6 +479,7 @@ async function flushDeltaBatch(ctx, queuedDeltas) {
         timeDrainStage('acknowledge', () => {
             ctx.acknowledge(persistedSyncId);
             ctx.advancePersisted(persistedSyncId);
+            observeDrainAcknowledge(persistedSyncId);
             runStage(stagePlugins, 'acknowledge', { syncId: persistedSyncId });
         });
     }

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

@@ -28,6 +28,18 @@ export interface DrainStageTotals {
     /** How many times the stage ran. Per-delta for `parse`, per-batch for the rest. */
     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;
@@ -38,7 +50,40 @@ 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[];
 }
+/**
+ * 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;
+}
+/**
+ * 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 declare function observeDrainAcknowledge(syncId: number): void;
+/** The recorded persisted-advance stamps, oldest first. */
+export declare function drainAcknowledgeStamps(): readonly AcknowledgeStamp[];
+/** Begin a batch row. Called by the pipeline at flush entry when profiling. */
+export declare function openDrainBatchRow(deltaCount: number): void;
+/** Close the open batch row and commit it to the ring. */
+export declare function closeDrainBatchRow(): void;
 /** Whether drain profiling is on. Callers skip their own bookkeeping when it is not. */
 export declare function drainProfilingEnabled(): boolean;
 /** Attribute already-measured wall time to a stage. */

package/dist/local/sync/drainProfile.js

@@ -40,6 +40,54 @@ let deltas = 0;
 let deduplicated = 0;
 let firstMark;
 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 = [];
+/**
+ * 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 = null;
+const ACK_STAMP_CAP = 512;
+let ackStamps = [];
+/**
+ * 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) {
+    ackStamps.push({ syncId, atWallMs: Date.now() });
+    if (ackStamps.length > ACK_STAMP_CAP)
+        ackStamps.shift();
+}
+/** The recorded persisted-advance stamps, oldest first. */
+export function drainAcknowledgeStamps() {
+    return [...ackStamps];
+}
+/** Begin a batch row. Called by the pipeline at flush entry when profiling. */
+export function openDrainBatchRow(deltaCount) {
+    if (!enabled)
+        return;
+    currentRow = { startedAtWallMs: Date.now(), deltas: deltaCount, stages: {} };
+}
+/** Close the open batch row and commit it to the ring. */
+export function closeDrainBatchRow() {
+    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.
@@ -64,6 +112,9 @@ export function observeDrainStage(stage, elapsedMs) {
     const entry = totals[stage];
     entry.totalMs += elapsedMs;
     entry.calls += 1;
+    if (currentRow !== null) {
+        currentRow.stages[stage] = (currentRow.stages[stage] ?? 0) + elapsedMs;
+    }
     mark(elapsedMs);
 }
 /** Time a synchronous stage. Returns the callback's value untouched. */
@@ -114,6 +165,7 @@ export function drainProfileSnapshot() {
         deduplicated,
         spanMs: firstMark === undefined ? 0 : lastMark - firstMark,
         stages,
+        recentBatches: [...batchRows],
     };
 }
 /** Clear the totals so a phase measures only its own traffic. */
@@ -124,4 +176,7 @@ export function resetDrainProfile() {
     deduplicated = 0;
     firstMark = undefined;
     lastMark = 0;
+    batchRows = [];
+    currentRow = null;
+    ackStamps = [];
 }