@abloatai/humans 0.37.0 → 0.38.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, type DrainProfile, 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, } 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/client/createModelProxy.js

@@ -142,15 +142,17 @@ defaultWait) {
         typeof value.release === 'function';
     const mutationOptions = (params) => {
         const rest = {
-            idempotencyKey: params.idempotencyKey,
-            label: params.label,
-            wait: params.wait,
-            readAt: params.readAt,
-            onStale: params.onStale,
-            fenceToken: params.fenceToken,
-            claimRef: params.claimRef,
-            reads: params.reads,
-            track: params.track,
+            ...(params.idempotencyKey !== undefined
+                ? { idempotencyKey: params.idempotencyKey }
+                : {}),
+            ...(params.label !== undefined ? { label: params.label } : {}),
+            ...(params.wait !== undefined ? { wait: params.wait } : {}),
+            ...(params.readAt !== undefined ? { readAt: params.readAt } : {}),
+            ...(params.onStale !== undefined ? { onStale: params.onStale } : {}),
+            ...(params.fenceToken !== undefined ? { fenceToken: params.fenceToken } : {}),
+            ...(params.claimRef !== undefined ? { claimRef: params.claimRef } : {}),
+            ...(params.reads !== undefined ? { reads: params.reads } : {}),
+            ...(params.track !== undefined ? { track: params.track } : {}),
         };
         // The write-options schema — the runtime twin of the compile-time params.
         // Catches plain-JavaScript callers (for example `onStale: 'rejct'`) at the
@@ -312,7 +314,7 @@ defaultWait) {
         return {
             object: 'claim',
             id: lease.id,
-            readAt: snapshot.stamp,
+            readAt: lease.readAt ?? snapshot.stamp,
             // The fencing token the server minted for this grant, forwarded from the
             // lease so writes taken under this handle carry it (Option B).
             ...(lease.fenceToken !== undefined ? { fenceToken: lease.fenceToken } : {}),
@@ -746,7 +748,7 @@ defaultWait) {
                 const effective = claimed
                     ? {
                         wait: 'confirmed',
-                        readAt: claimed.snapshot.stamp,
+                        readAt: claimed.lease.readAt ?? claimed.snapshot.stamp,
                         onStale: 'reject',
                         claimRef: { id: claimed.lease.id },
                         ...opts,
@@ -816,7 +818,7 @@ defaultWait) {
             const effective = claimed
                 ? {
                     wait: 'confirmed',
-                    readAt: claimed.snapshot.stamp,
+                    readAt: claimed.lease.readAt ?? claimed.snapshot.stamp,
                     onStale: 'reject',
                     claimRef: { id: claimed.lease.id },
                     ...(claimed.lease.fenceToken !== undefined

package/dist/local/client/options.d.ts

@@ -434,6 +434,13 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * identity from the token through the identity endpoint instead.
      */
     organizationId?: string;
+    /**
+     * Immutable branch selected by a self-hosted credential. Hosted clients
+     * receive this from the credential exchange.
+     */
+    branchId?: string;
+    /** Whether the selected self-hosted branch is the project's root branch. */
+    branchRoot?: boolean;
     /** The client-wide write default — see {@link AbloOptions.wait}. Projected
      *  from the public option rather than restated, so the two cannot diverge. */
     wait?: AbloOptions['wait'];

package/dist/local/client/reactiveEngine.js

@@ -250,7 +250,7 @@ export function buildReactiveEngine(inputs) {
             }
         });
     }
-    function wrapClaimHandle(claim, waited = false, fenceToken) {
+    function wrapClaimHandle(claim, waited = false, fenceToken, readAt) {
         const release = () => {
             claim.revoke?.();
             return Promise.resolve();
@@ -265,6 +265,7 @@ export function buildReactiveEngine(inputs) {
             description: claim.description,
             target: claim.target,
             waited,
+            ...(readAt !== undefined ? { readAt } : {}),
             ...(resolvedFenceToken !== undefined ? { fenceToken: resolvedFenceToken } : {}),
             release,
             revoke: claim.revoke,
@@ -293,9 +294,10 @@ export function buildReactiveEngine(inputs) {
             // holds the lease, never a half-claimed one racing the queue.
             let waited = false;
             let fenceToken;
+            let readAt;
             if (claimOptions.queue) {
                 try {
-                    ({ waited, fenceToken } = await awaitClaimGrant(transport, claim.id, {
+                    ({ waited, fenceToken, readAt } = await awaitClaimGrant(transport, claim.id, {
                         timeoutMs: claimOptions.waitTimeoutMs,
                         maxQueueDepth: claimOptions.maxQueueDepth,
                         signal: claimOptions.signal,
@@ -310,7 +312,7 @@ export function buildReactiveEngine(inputs) {
                     throw err;
                 }
             }
-            return wrapClaimHandle(claim, waited, fenceToken);
+            return wrapClaimHandle(claim, waited, fenceToken, readAt);
         },
         list(target) {
             return listModelClaims(target);

package/dist/local/client/storeLifecycle.js

@@ -107,7 +107,7 @@ export function startStoreLifecycle(deps) {
                     auth: authCredentials,
                     logger,
                 });
-                const { userId, accountScope, projectId, environment, sandboxId, teamIds, capabilityToken, syncGroups, participantKind, } = resolved;
+                const { userId, accountScope, projectId, branchId, branchRoot, teamIds, capabilityToken, syncGroups, participantKind, } = resolved;
                 // Fail-loud guard: detect the degenerate "no real sync groups
                 // resolved" state before opening the socket. It is the same class of bug as
                 // a sensible-looking default that's functionally broken: the
@@ -155,12 +155,15 @@ export function startStoreLifecycle(deps) {
                 // agents default to 'none' (transactional participant — see
                 // option doc) and everyone else defaults to 'full'.
                 const resolvedBootstrapMode = internalOptions.bootstrapMode ?? (participantKind === 'agent' ? 'none' : 'full');
+                if (!branchId) {
+                    throw new AbloConnectionError('The server did not resolve an Ablo branch for this credential.', { code: 'invalid_request' });
+                }
                 const gen = store.initialize({
                     userId,
                     organizationId: accountScope,
                     projectId,
-                    environment,
-                    sandboxId,
+                    branchId,
+                    branchRoot,
                     teamIds,
                     kind: participantKind,
                     capabilityToken,

package/dist/local/stores/DatabaseManager.d.ts

@@ -15,8 +15,8 @@ export interface DatabaseInfo {
     workspaceId: string;
     participantKind: string;
     projectId: string | null;
-    environment: 'sandbox' | 'production' | null;
-    sandboxId: string | null;
+    branchId: string;
+    branchRoot: boolean;
     schemaHash: string;
     schemaVersion: number;
     userVersion?: number;

package/dist/local/stores/DatabaseManager.js

@@ -114,8 +114,8 @@ export class DatabaseManager {
             workspaceId: identity.organizationId,
             participantKind: identity.participantKind,
             projectId: identity.projectId,
-            environment: identity.environment,
-            sandboxId: identity.sandboxId,
+            branchId: identity.branchId,
+            branchRoot: identity.branchRoot,
             schemaHash,
             schemaVersion,
             userVersion,

package/dist/local/stores/persistenceIdentity.d.ts

@@ -1,15 +1,14 @@
 /**
- * The complete authenticated plane that owns one local replica. The same
- * participant can have different data in a project, sandbox, or environment;
- * those replicas must never share a namespace.
+ * The complete authenticated branch that owns one local replica. A branch id
+ * is authoritative.
  */
 export interface PersistenceIdentity {
     readonly participantId: string;
     readonly participantKind: string;
     readonly organizationId: string;
     readonly projectId: string | null;
-    readonly environment: 'sandbox' | 'production' | null;
-    readonly sandboxId: string | null;
+    readonly branchId: string;
+    readonly branchRoot: boolean;
 }
 export interface PersistedIdentityMetadata {
     readonly namespaceVersion?: number;
@@ -17,10 +16,10 @@ export interface PersistedIdentityMetadata {
     readonly workspaceId: string;
     readonly participantKind?: string;
     readonly projectId?: string | null;
-    readonly environment?: 'sandbox' | 'production' | null;
-    readonly sandboxId?: string | null;
+    readonly branchId?: string;
+    readonly branchRoot?: boolean;
 }
-export declare const PERSISTENCE_NAMESPACE_VERSION = 2;
+export declare const PERSISTENCE_NAMESPACE_VERSION = 4;
 /** Collision-resistant IndexedDB name for one authenticated data plane. */
 export declare function persistenceDatabaseName(identity: PersistenceIdentity, userVersion?: number): Promise<string>;
 /** Defense-in-depth check after namespace lookup and before persisted reads. */

package/dist/local/stores/persistenceIdentity.js

@@ -1,11 +1,10 @@
 import { AbloConnectionError } from '@abloatai/transaction/errors';
-export const PERSISTENCE_NAMESPACE_VERSION = 2;
+export const PERSISTENCE_NAMESPACE_VERSION = 4;
 function canonicalIdentity(identity, userVersion) {
     return JSON.stringify([
         PERSISTENCE_NAMESPACE_VERSION,
         identity.projectId,
-        identity.environment,
-        identity.sandboxId,
+        ['branch', identity.branchId, identity.branchRoot],
         identity.organizationId,
         identity.participantKind,
         identity.participantId,
@@ -33,6 +32,6 @@ export function persistenceIdentityMatches(info, identity) {
         info.workspaceId === identity.organizationId &&
         info.participantKind === identity.participantKind &&
         (info.projectId ?? null) === identity.projectId &&
-        (info.environment ?? null) === identity.environment &&
-        (info.sandboxId ?? null) === identity.sandboxId);
+        info.branchId === identity.branchId &&
+        (info.branchRoot ?? false) === identity.branchRoot);
 }

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

@@ -94,7 +94,14 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * and an observability breadcrumb; it is never applied. There is one parse per
      * delta — callers must not re-parse.
      */
+    /**
+     * Wire validation runs once per delta, so at drain scale it is a per-delta
+     * fixed cost rather than a payload-proportional one. The guard keeps the
+     * normal path free: when profiling is off this is a boolean test and a
+     * direct call, with no closure allocated per delta.
+     */
     private normalizeWireDelta;
+    private parseWireDelta;
     /**
      * Handle incoming sync delta (untrusted wire input — validated and
      * normalized by {@link normalizeWireDelta}; malformed deltas are dropped).

package/dist/local/sync/SyncWebSocket.js

@@ -11,6 +11,7 @@
  */
 import { getContext } from '../context.js';
 import { clientSyncDeltaSchema } from '@abloatai/transaction/wire/delta';
+import { drainProfilingEnabled, observeDrainStage } from './drainProfile.js';
 import { WsTransport, } from '@abloatai/transaction/transport/wsTransport';
 import { isRecord } from './wsFrameHandlers.js';
 // Sync-position state (lastSyncId watermark, version vector, server cursor).
@@ -123,7 +124,24 @@ export class SyncWebSocket extends WsTransport {
      * and an observability breadcrumb; it is never applied. There is one parse per
      * delta — callers must not re-parse.
      */
+    /**
+     * Wire validation runs once per delta, so at drain scale it is a per-delta
+     * fixed cost rather than a payload-proportional one. The guard keeps the
+     * normal path free: when profiling is off this is a boolean test and a
+     * direct call, with no closure allocated per delta.
+     */
     normalizeWireDelta(raw) {
+        if (!drainProfilingEnabled())
+            return this.parseWireDelta(raw);
+        const startedAt = performance.now();
+        try {
+            return this.parseWireDelta(raw);
+        }
+        finally {
+            observeDrainStage('parse', performance.now() - startedAt);
+        }
+    }
+    parseWireDelta(raw) {
         let candidate = raw;
         if (isRecord(raw)) {
             const normalized = { ...raw };

package/dist/local/sync/deltaPipeline.js

@@ -14,6 +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';
 /**
  * One drain per store. Incoming WebSocket frames may arrive while persistence
  * and pool application are awaiting. Without a single-flight guard every
@@ -80,6 +81,23 @@ function isSameState(a, b) {
 }
 /** Deduplicate deltas to the same entity — keep meaningful state transitions only */
 export function deduplicateDeltas(ctx, deltas) {
+    // The dominant live-publication shape is a frame of independent entity
+    // creates. When every entity key occurs once, reconciliation cannot remove
+    // or reorder anything: preserve the already commit-ordered input directly
+    // and avoid allocating a bucket array, state signature, and two sorts per
+    // delta. The first duplicate falls through to the full transition logic.
+    const uniqueEntities = new Set();
+    let hasDuplicateEntity = false;
+    for (const delta of deltas) {
+        const key = `${delta.modelName}:${delta.modelId}`;
+        if (uniqueEntities.has(key)) {
+            hasDuplicateEntity = true;
+            break;
+        }
+        uniqueEntities.add(key);
+    }
+    if (!hasDuplicateEntity)
+        return deltas;
     const byEntity = new Map();
     for (const d of deltas) {
         const key = `${d.modelName}:${d.modelId}`;
@@ -278,7 +296,8 @@ function yieldToHost() {
 }
 async function flushDeltaBatch(ctx, queuedDeltas) {
     const stagePlugins = ctx.stagePlugins ?? [];
-    const deduplicatedDeltas = ctx.deduplicateDeltas(queuedDeltas);
+    const deduplicatedDeltas = timeDrainStage('dedupe', () => ctx.deduplicateDeltas(queuedDeltas));
+    observeDrainBatch(queuedDeltas.length, deduplicatedDeltas.length);
     runStage(stagePlugins, 'dedupe', { deltas: deduplicatedDeltas });
     // Custom entities → apply straight to the pool, skipping the local store.
     const customDeltas = deduplicatedDeltas.filter((d) => ctx.isCustomEntity(d.modelName));
@@ -315,7 +334,7 @@ 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));
-    const batch = await ctx.processDeltaBatch(regularDeltas.map((d) => ({
+    const batch = await timeDrainStageAsync('persist', () => ctx.processDeltaBatch(regularDeltas.map((d) => ({
         syncId: d.id,
         actionType: d.actionType,
         modelName: d.modelName,
@@ -324,7 +343,7 @@ async function flushDeltaBatch(ctx, queuedDeltas) {
         // Thread `transactionId` through so the receive layer can recognize
         // echoes of locally-applied transactions and skip the pool mutation.
         transactionId: d.transactionId,
-    })));
+    }))));
     const dbResults = batch.results;
     runStage(stagePlugins, 'persist', { deltas: regularDeltas });
     // Apply the batch results to the in-memory graph. When a plugin has
@@ -332,12 +351,14 @@ 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.
-    if (pluginsForStage(stagePlugins, 'apply').length > 0) {
-        runStage(stagePlugins, 'apply', { changes: dbResults });
-    }
-    else {
-        ctx.applyDeltaBatchToPool(dbResults);
-    }
+    timeDrainStage('apply', () => {
+        if (pluginsForStage(stagePlugins, 'apply').length > 0) {
+            runStage(stagePlugins, 'apply', { changes: dbResults });
+        }
+        else {
+            ctx.applyDeltaBatchToPool(dbResults);
+        }
+    });
     // Acknowledge and advance the sync cursor, gated on persistence.
     //
     // We must acknowledge `persistedSyncId` — the high-water mark of deltas whose
@@ -348,10 +369,14 @@ async function flushDeltaBatch(ctx, queuedDeltas) {
     // be lost. The cursor and the persisted state must move together.
     const persistedSyncId = batch.persistedSyncId;
     if (persistedSyncId > ctx.lastAckedId) {
-        ctx.acknowledge(persistedSyncId);
-        ctx.advancePersisted(persistedSyncId);
-        runStage(stagePlugins, 'acknowledge', { syncId: persistedSyncId });
+        timeDrainStage('acknowledge', () => {
+            ctx.acknowledge(persistedSyncId);
+            ctx.advancePersisted(persistedSyncId);
+            runStage(stagePlugins, 'acknowledge', { syncId: persistedSyncId });
+        });
     }
     // Cache invalidation happens automatically via the 'models:changed' event.
-    runStage(stagePlugins, 'notify', { changes: dbResults });
+    timeDrainStage('notify', () => {
+        runStage(stagePlugins, 'notify', { changes: dbResults });
+    });
 }

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

@@ -0,0 +1,59 @@
+/**
+ * Where the drain's seconds go.
+ *
+ * A commit's receipt is confirmed the moment its PostgreSQL transaction
+ * commits, but an observer is not caught up until it has applied the last
+ * delta. Server publication p95 is single-digit milliseconds while the final
+ * observer takes seconds, so the gap is client-side and has never been
+ * attributed to a stage. Two fixes aimed at wire bytes (project filtering,
+ * patch-only UPDATE delivery) each returned well under a third, which is
+ * evidence the dominant term is a per-delta or per-batch fixed cost rather
+ * than payload size.
+ *
+ * This times the stages a delta actually passes through so a benchmark run can
+ * state the attribution instead of inferring it. It is off unless
+ * `ABLO_PROFILE_DRAIN=true`, and every entry point returns before doing work
+ * when off, mirroring the server's commit profiler.
+ *
+ * The stage vocabulary derives from {@link PipelineStage}; `parse` is the one
+ * addition, because wire validation happens in the transport before a delta
+ * reaches the pipeline at all.
+ */
+import type { PipelineStage } from '../../plugin.js';
+/** The pipeline's own stages plus the transport-level wire validation ahead of them. */
+export type DrainStage = 'parse' | PipelineStage;
+export interface DrainStageTotals {
+    /** Accumulated wall time attributed to this stage. */
+    readonly totalMs: number;
+    /** How many times the stage ran. Per-delta for `parse`, per-batch for the rest. */
+    readonly calls: number;
+}
+export interface DrainProfile {
+    /** Flush batches drained. The per-batch fixed cost multiplies by this. */
+    readonly batches: number;
+    /** Deltas that reached the pipeline. The per-delta fixed cost multiplies by this. */
+    readonly deltas: number;
+    /** Deltas dropped by the dedupe stage before persistence. */
+    readonly deduplicated: number;
+    /** Wall time from the first observed stage to the last. */
+    readonly spanMs: number;
+    readonly stages: Readonly<Record<DrainStage, DrainStageTotals>>;
+}
+/** 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. */
+export declare function observeDrainStage(stage: DrainStage, elapsedMs: number): void;
+/** Time a synchronous stage. Returns the callback's value untouched. */
+export declare function timeDrainStage<T>(stage: DrainStage, run: () => T): T;
+/** Time an asynchronous stage. Returns the callback's value untouched. */
+export declare function timeDrainStageAsync<T>(stage: DrainStage, run: () => Promise<T>): Promise<T>;
+/**
+ * Record one drained batch: how many deltas entered it and how many survived
+ * deduplication. Batch count is the multiplier on every per-batch cost, so it
+ * is reported alongside the timings rather than derived from them.
+ */
+export declare function observeDrainBatch(received: number, survived: number): void;
+/** The totals accumulated since the last reset. */
+export declare function drainProfileSnapshot(): DrainProfile;
+/** Clear the totals so a phase measures only its own traffic. */
+export declare function resetDrainProfile(): void;

package/dist/local/sync/drainProfile.js

@@ -0,0 +1,127 @@
+/**
+ * Where the drain's seconds go.
+ *
+ * A commit's receipt is confirmed the moment its PostgreSQL transaction
+ * commits, but an observer is not caught up until it has applied the last
+ * delta. Server publication p95 is single-digit milliseconds while the final
+ * observer takes seconds, so the gap is client-side and has never been
+ * attributed to a stage. Two fixes aimed at wire bytes (project filtering,
+ * patch-only UPDATE delivery) each returned well under a third, which is
+ * evidence the dominant term is a per-delta or per-batch fixed cost rather
+ * than payload size.
+ *
+ * This times the stages a delta actually passes through so a benchmark run can
+ * state the attribution instead of inferring it. It is off unless
+ * `ABLO_PROFILE_DRAIN=true`, and every entry point returns before doing work
+ * when off, mirroring the server's commit profiler.
+ *
+ * The stage vocabulary derives from {@link PipelineStage}; `parse` is the one
+ * addition, because wire validation happens in the transport before a delta
+ * reaches the pipeline at all.
+ */
+const DRAIN_STAGES = [
+    'parse',
+    'receive',
+    'dedupe',
+    'persist',
+    'apply',
+    'acknowledge',
+    'notify',
+];
+function emptyTotals() {
+    const totals = {};
+    for (const stage of DRAIN_STAGES)
+        totals[stage] = { totalMs: 0, calls: 0 };
+    return totals;
+}
+let totals = emptyTotals();
+let batches = 0;
+let deltas = 0;
+let deduplicated = 0;
+let firstMark;
+let lastMark = 0;
+/**
+ * Read once. A profiler that consults the environment on every delta would
+ * itself become a per-delta cost in the path it is measuring.
+ */
+const enabled = (() => {
+    const host = globalThis;
+    return host.process?.env?.ABLO_PROFILE_DRAIN === 'true';
+})();
+/** Whether drain profiling is on. Callers skip their own bookkeeping when it is not. */
+export function drainProfilingEnabled() {
+    return enabled;
+}
+function mark(elapsedMs) {
+    const now = performance.now();
+    firstMark ??= now - elapsedMs;
+    lastMark = now;
+}
+/** Attribute already-measured wall time to a stage. */
+export function observeDrainStage(stage, elapsedMs) {
+    if (!enabled)
+        return;
+    const entry = totals[stage];
+    entry.totalMs += elapsedMs;
+    entry.calls += 1;
+    mark(elapsedMs);
+}
+/** Time a synchronous stage. Returns the callback's value untouched. */
+export function timeDrainStage(stage, run) {
+    if (!enabled)
+        return run();
+    const startedAt = performance.now();
+    try {
+        return run();
+    }
+    finally {
+        observeDrainStage(stage, performance.now() - startedAt);
+    }
+}
+/** Time an asynchronous stage. Returns the callback's value untouched. */
+export async function timeDrainStageAsync(stage, run) {
+    if (!enabled)
+        return run();
+    const startedAt = performance.now();
+    try {
+        return await run();
+    }
+    finally {
+        observeDrainStage(stage, performance.now() - startedAt);
+    }
+}
+/**
+ * Record one drained batch: how many deltas entered it and how many survived
+ * deduplication. Batch count is the multiplier on every per-batch cost, so it
+ * is reported alongside the timings rather than derived from them.
+ */
+export function observeDrainBatch(received, survived) {
+    if (!enabled)
+        return;
+    batches += 1;
+    deltas += received;
+    deduplicated += Math.max(0, received - survived);
+}
+/** The totals accumulated since the last reset. */
+export function drainProfileSnapshot() {
+    const stages = {};
+    for (const stage of DRAIN_STAGES) {
+        stages[stage] = { totalMs: totals[stage].totalMs, calls: totals[stage].calls };
+    }
+    return {
+        batches,
+        deltas,
+        deduplicated,
+        spanMs: firstMark === undefined ? 0 : lastMark - firstMark,
+        stages,
+    };
+}
+/** Clear the totals so a phase measures only its own traffic. */
+export function resetDrainProfile() {
+    totals = emptyTotals();
+    batches = 0;
+    deltas = 0;
+    deduplicated = 0;
+    firstMark = undefined;
+    lastMark = 0;
+}

package/dist/local/sync/initialize.js

@@ -13,8 +13,8 @@ export function* initialize(host, context, signal) {
             organizationId: context.organizationId,
             participantKind: context.kind ?? 'user',
             projectId: context.projectId ?? context.organizationId,
-            environment: context.environment ?? null,
-            sandboxId: context.sandboxId ?? null,
+            branchId: context.branchId,
+            branchRoot: context.branchRoot ?? false,
         });
         // Propagate identity only after storage is ready, then restore sealed
         // requests before accepting fresh mutations.

package/dist/local/transactions/mutations/MutationQueue.js

@@ -861,17 +861,18 @@ export class MutationQueue extends EventEmitter {
      * transaction.
      */
     confirmationFor(modelName, modelId) {
-        const candidates = [
-            ...this.store.getByStatus('pending'),
-            ...this.store.getByStatus('executing'),
-            ...this.store.getByStatus('awaiting_delta'),
-        ].filter((tx) => tx.modelName === modelName && tx.modelId === modelId);
-        if (candidates.length === 0)
-            return Promise.resolve();
-        const latest = candidates.sort((a, b) => b.createdAt - a.createdAt)[0];
-        if (!latest)
-            return Promise.resolve();
-        return latest.confirmation ?? Promise.resolve();
+        const transactions = this.store.getAll();
+        for (let index = transactions.length - 1; index >= 0; index--) {
+            const transaction = transactions[index];
+            if (transaction?.modelName === modelName &&
+                transaction.modelId === modelId &&
+                (transaction.status === 'pending' ||
+                    transaction.status === 'executing' ||
+                    transaction.status === 'awaiting_delta')) {
+                return transaction.confirmation ?? Promise.resolve();
+            }
+        }
+        return Promise.resolve();
     }
     /**
      * Attaches a `confirmation` promise to a newly created transaction. Call this
@@ -1046,7 +1047,26 @@ export class MutationQueue extends EventEmitter {
         return this.pendingDrainPromise;
     }
     async drainPendingInternal() {
-        await drainPendingSettlements(this.pendingDrainContext);
+        // The normal batch scheduler and the explicit/reconnect drain are two
+        // ways to drive the same durable queue. They must never seal the same
+        // staged source records concurrently: the first seal consumes those
+        // records, so the second would correctly reject them as already claimed.
+        //
+        // `isProcessing` is acquired synchronously before either path awaits,
+        // making it the queue-wide execution lock. If the normal lane already
+        // owns it, that lane will finish the pending work; callers waiting on a
+        // specific confirmation remain attached to the exact transaction.
+        if (this.isProcessing)
+            return;
+        this.isProcessing = true;
+        try {
+            await drainPendingSettlements(this.pendingDrainContext);
+        }
+        finally {
+            this.isProcessing = false;
+            if (this.executionQueue.length > 0)
+                this.scheduleProcessing(true);
+        }
     }
     async create(model, context, writeOptions, sourceMutationId) {
         return createModel(this.modelMutationContext, model, context, writeOptions, sourceMutationId);