@wildo-ai/saas-frontend-lib 1.0.1

package/dist/esm/core/resources/rmm/ResourceMutationManager.js

@@ -0,0 +1,1577 @@
+/**
+ * ResourceMutationManager — Production Implementation (Phase 1.1)
+ *
+ * Pure TypeScript class that owns all mutation state for a single resource instance.
+ * Consumers observe state via useSyncExternalStore(rmm.subscribe, rmm.getSnapshot).
+ * Side-effect events via useEffect([snapshot.lastEvent?.id]).
+ *
+ * State machine: IDLE → QUEUED → SAVING → IDLE (happy path)
+ *                SAVING → ERROR → SAVING (retry) → IDLE (exhaust)
+ *                SAVING → CONFLICT → IDLE (acknowledge)
+ *                ANY → DELETED (terminal)
+ */
+import { DataMode, extractCrdtFieldNames, lwwFieldWinner, nextMonotonicTimestamp, CrdtResolutionWinner, sanitizeFieldMeta, } from '@wildo-ai/saas-models';
+import { RMMState, RMMEventType, MutationType, MutationSourceType, MutationErrorType, OperationResultStatus, ConflictStrategy, ConflictReason, MutationPriority, MutationCancelledError, ResourceDeletedError, BackpressureRejectedError, } from './types.js';
+import { RMM_HARD_TIMEOUT_MS, RMM_MAX_QUEUE_DEPTH, RMM_SERVER_RETRY_DELAY_MS, RMM_SOFT_TIMEOUT_MS, RMM_TRANSIENT_RETRY_DELAYS, } from './rmm-constants.js';
+import { rmmFieldPathsOverlap, rmmNormalizeFieldPath, rmmReadPathValue } from './field-path.utils.js';
+import { LoggerFrontendService } from '../../../core/monitoring/logger.frontend.service.js';
+// =============================================================================
+// LOGGING
+// =============================================================================
+const logger = LoggerFrontendService.getLogger();
+const logDebug = logger.debugByType('ResourceMutationManager');
+logger.setDebugTypeLogging('ResourceMutationManager', false);
+// =============================================================================
+// MODULE HELPERS
+// =============================================================================
+function deepSetByPath(obj, path, value) {
+    const segments = rmmNormalizeFieldPath(path).split('.').filter(Boolean);
+    let current = obj;
+    for (let i = 0; i < segments.length - 1; i++) {
+        const seg = segments[i];
+        const nextSegment = segments[i + 1];
+        const nextContainer = /^\d+$/.test(nextSegment) ? [] : {};
+        if (current[seg] === undefined || current[seg] === null || typeof current[seg] !== 'object') {
+            if (value === undefined)
+                return;
+            current[seg] = nextContainer;
+        }
+        current = current[seg];
+    }
+    const lastSeg = segments[segments.length - 1];
+    if (value === undefined) {
+        if (Array.isArray(current) && /^\d+$/.test(lastSeg)) {
+            delete current[Number(lastSeg)];
+        }
+        else {
+            delete current[lastSeg];
+        }
+    }
+    else {
+        if (Array.isArray(current) && /^\d+$/.test(lastSeg)) {
+            current[Number(lastSeg)] = value;
+        }
+        else {
+            current[lastSeg] = value;
+        }
+    }
+}
+// =============================================================================
+// INTERNAL TYPES
+// =============================================================================
+var TransitionEventType;
+(function (TransitionEventType) {
+    TransitionEventType["QUEUE_MUTATION"] = "QUEUE_MUTATION";
+    TransitionEventType["START_SAVING"] = "START_SAVING";
+    TransitionEventType["SAVE_SUCCESS"] = "SAVE_SUCCESS";
+    TransitionEventType["SAVE_ERROR"] = "SAVE_ERROR";
+    TransitionEventType["RETRY"] = "RETRY";
+    TransitionEventType["CONFLICT_DETECTED"] = "CONFLICT_DETECTED";
+    TransitionEventType["CONFLICT_ACKNOWLEDGED"] = "CONFLICT_ACKNOWLEDGED";
+    TransitionEventType["CANCEL"] = "CANCEL";
+    TransitionEventType["DELETE"] = "DELETE";
+    TransitionEventType["REMOTE_UPDATE"] = "REMOTE_UPDATE";
+})(TransitionEventType || (TransitionEventType = {}));
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+const DEFAULT_AUTOSAVE_SOURCE = { type: MutationSourceType.FORM, subscriberId: 'autosave' };
+const DEFAULT_BACKPRESSURE = {
+    maxQueueDepth: RMM_MAX_QUEUE_DEPTH,
+    softTimeoutMs: RMM_SOFT_TIMEOUT_MS,
+    hardTimeoutMs: RMM_HARD_TIMEOUT_MS,
+};
+// =============================================================================
+// CLASS
+// =============================================================================
+export class ResourceMutationManager {
+    // --- Identity ---
+    resourceType;
+    _resourceId;
+    // --- Data (two-tier: confirmed vs optimistic) ---
+    _confirmedData = null;
+    _version = null;
+    // --- Mutation State ---
+    _pendingFields = new Map();
+    _queue = [];
+    _activeMutation = null;
+    _state = RMMState.IDLE;
+    _lastError = null;
+    // --- Declarative Event Model ---
+    _lastEvent = null;
+    _eventCounter = 0;
+    // --- Snapshot (for useSyncExternalStore) ---
+    _snapshotVersion = 0;
+    _cachedSnapshot = null;
+    _cachedSnapshotVersion = -1;
+    _snapshotListeners = new Set();
+    // --- Optimistic Data Memoization ---
+    _optimisticDataVersion = -1;
+    _cachedOptimisticData = null;
+    // --- Config ---
+    _config;
+    _mutationIdCounter = 0;
+    // --- Retry ---
+    _retryTimer = null;
+    _retryDelays = [...RMM_TRANSIENT_RETRY_DELAYS];
+    _serverRetryDelay = RMM_SERVER_RETRY_DELAY_MS;
+    _authoritativeRecoveryTimer = null;
+    // --- Backpressure ---
+    _backpressure;
+    _softTimer = null;
+    _hardTimer = null;
+    // --- WebSocket Event Deferral (Phase 4 — data structure only) ---
+    _deferredSelfEvents = [];
+    _allowSettledSelfEventRepair = false;
+    // --- CRDT Metadata ---
+    _crdtFieldNames;
+    _fieldMeta = null;
+    _pendingFieldTimestamps = new Map();
+    _lastIssuedLocalTimestamp = 0;
+    _clockOffset = 0;
+    // --- Destroy ---
+    _onDrainCallbacks = [];
+    constructor(config) {
+        this._config = config;
+        this.resourceType = config.resourceType;
+        this._resourceId = config.resourceId;
+        const bp = config.backpressure;
+        this._backpressure = {
+            maxQueueDepth: bp?.maxQueueDepth ?? DEFAULT_BACKPRESSURE.maxQueueDepth,
+            softTimeoutMs: bp?.softTimeoutMs ?? DEFAULT_BACKPRESSURE.softTimeoutMs,
+            hardTimeoutMs: bp?.hardTimeoutMs ?? DEFAULT_BACKPRESSURE.hardTimeoutMs,
+        };
+        this._crdtFieldNames = extractCrdtFieldNames(config.resourceSchema);
+        this.subscribe = this.subscribe.bind(this);
+        this.getSnapshot = this.getSnapshot.bind(this);
+        logDebug('constructor', {
+            resourceType: config.resourceType,
+            resourceId: config.resourceId,
+            conflictStrategy: config.conflictPolicy.strategy,
+            operationPathKey: config.operationPathKey,
+            crdtFieldCount: this._crdtFieldNames.size,
+            crdtFields: Array.from(this._crdtFieldNames),
+        });
+    }
+    /**
+     * Returns a strictly positive client timestamp for CRDT ordering.
+     * Uses clock calibration from the registry; falls back to raw Date.now() when offset is 0.
+     *
+     * For a given CRDT field, the timestamp reflects the **last** local edit
+     * enqueued (e.g. last autosave batch / submit merge), not the first keystroke.
+     */
+    _getAdjustedTimestamp() {
+        const raw = Date.now() + this._clockOffset;
+        this._lastIssuedLocalTimestamp = nextMonotonicTimestamp(Math.max(1, raw), this._lastIssuedLocalTimestamp);
+        return this._lastIssuedLocalTimestamp;
+    }
+    _isCrdtManagedField(field) {
+        return this._crdtFieldNames.has(field) || this._crdtFieldNames.has(field.split('.')[0] ?? field);
+    }
+    set clockOffset(offset) {
+        this._clockOffset = offset;
+    }
+    // =============================================================================
+    // PUBLIC API — Identity
+    // =============================================================================
+    get resourceId() {
+        return this._resourceId;
+    }
+    /** Contextual parameters used for doOperation routing (e.g., parent IDs for nested resources). */
+    get contextualParameters() {
+        return this._config.contextualParameters;
+    }
+    /** Context identifiers used to authorize and subscribe to the resource room. */
+    get contextResourceIdentifiers() {
+        return this._config.contextResourceIdentifiers ?? {};
+    }
+    /** Parent resource requirements for nested resource resolution during reconnection refetch. */
+    get parentResourcesRequirements() {
+        return this._config.parentResourcesRequirements;
+    }
+    /** Canonical READ path used for authoritative reseed/read-back flows. */
+    get readOperationPathKey() {
+        return this._config.readOperationPathKey;
+    }
+    /**
+     * Applies runtime updates after the RMM was created via
+     * `RMMRegistry.getOrCreate`. Registry identity stays `(resourceType, resourceId)`;
+     * this patches the config used for `OperationDescriptor`, transport ownership,
+     * self-event detection, and any caller-provided conflict / CRDT semantics that
+     * are expected to stay aligned when a live surface reuses an existing instance.
+     */
+    syncRuntimeRoutingConfig(patch) {
+        if (this._state === RMMState.DELETED)
+            return;
+        const didUpdateOperationPathKey = patch.operationPathKey !== undefined && patch.operationPathKey !== this._config.operationPathKey;
+        const didUpdateReadOperationPathKey = patch.readOperationPathKey !== undefined && patch.readOperationPathKey !== this._config.readOperationPathKey;
+        const didUpdateTransportAdapter = patch.transportAdapter !== undefined && patch.transportAdapter !== this._config.transportAdapter;
+        const didUpdateConflictPolicy = patch.conflictPolicy !== undefined
+            && patch.conflictPolicy.strategy !== this._config.conflictPolicy.strategy;
+        const didUpdateResourceSchema = patch.resourceSchema !== undefined && patch.resourceSchema !== this._config.resourceSchema;
+        this._config = {
+            ...this._config,
+            ...(patch.transportAdapter !== undefined ? { transportAdapter: patch.transportAdapter } : {}),
+            currentUserId: patch.currentUserId,
+            ...(patch.contextResourceIdentifiers !== undefined
+                ? { contextResourceIdentifiers: { ...patch.contextResourceIdentifiers } }
+                : {}),
+            contextualParameters: { ...patch.contextualParameters },
+            ...(patch.parentResourcesRequirements !== undefined
+                ? { parentResourcesRequirements: patch.parentResourcesRequirements }
+                : {}),
+            ...(patch.operationPathKey !== undefined ? { operationPathKey: patch.operationPathKey } : {}),
+            ...(patch.readOperationPathKey !== undefined ? { readOperationPathKey: patch.readOperationPathKey } : {}),
+            ...(patch.conflictPolicy !== undefined ? { conflictPolicy: patch.conflictPolicy } : {}),
+            ...(patch.resourceSchema !== undefined ? { resourceSchema: patch.resourceSchema } : {}),
+        };
+        if (didUpdateResourceSchema) {
+            this._crdtFieldNames = extractCrdtFieldNames(patch.resourceSchema);
+        }
+        logDebug('syncRuntimeRoutingConfig', {
+            resourceType: this.resourceType,
+            resourceId: this._resourceId,
+            hasUserId: patch.currentUserId.length > 0,
+            didUpdateOperationPathKey,
+            didUpdateReadOperationPathKey,
+            didUpdateTransportAdapter,
+            didUpdateConflictPolicy,
+            didUpdateResourceSchema,
+            crdtFieldCount: this._crdtFieldNames.size,
+        });
+        if (didUpdateOperationPathKey || didUpdateReadOperationPathKey) {
+            this._invalidateSnapshot();
+        }
+    }
+    // =============================================================================
+    // PUBLIC API — State Management
+    // =============================================================================
+    /**
+     * May be called multiple times (e.g., on refetch or WS reconnection).
+     * Replaces _confirmedData and _version. Preserves _pendingFields.
+     */
+    setInitialState(data, version, _fieldMeta) {
+        if (this._state === RMMState.DELETED)
+            return;
+        this._confirmedData = { ...data };
+        this._version = version;
+        this._clearAuthoritativeRecoveryTimer();
+        this._allowSettledSelfEventRepair = false;
+        const rawMeta = _fieldMeta ?? data._field_meta;
+        this._fieldMeta = rawMeta != null ? sanitizeFieldMeta(rawMeta) : null;
+        this._invalidateSnapshot();
+        logDebug('setInitialState', {
+            resourceId: this._resourceId,
+            version,
+            fieldCount: Object.keys(data).length,
+            pendingFieldCount: this._pendingFields.size,
+            hasFieldMeta: this._fieldMeta !== null,
+        });
+    }
+    // =============================================================================
+    // PUBLIC API — Mutations
+    // =============================================================================
+    /**
+     * Queue a mutation. Returns a Promise that resolves with MutationResult on
+     * completion (success or server error). Rejects only for cancellation
+     * (MutationCancelledError) or deletion (ResourceDeletedError).
+     *
+     * For HIGH-priority mutations (submit/draft/publish), all pending LOW fields
+     * are merged in and the accumulator is cleared.
+     */
+    queueMutation(fields, options) {
+        if (this._state === RMMState.DELETED) {
+            logDebug('queueMutation: rejected — resource deleted', { resourceId: this._resourceId });
+            return Promise.reject(new ResourceDeletedError());
+        }
+        const priority = options?.priority ?? MutationPriority.LOW;
+        const type = options?.type ?? MutationType.AUTOSAVE;
+        const source = options?.source ?? DEFAULT_AUTOSAVE_SOURCE;
+        if (this._queue.length >= this._backpressure.maxQueueDepth && priority <= MutationPriority.LOW) {
+            logDebug('queueMutation: rejected — backpressure', {
+                queueDepth: this._queue.length,
+                maxDepth: this._backpressure.maxQueueDepth,
+            });
+            return Promise.reject(new BackpressureRejectedError());
+        }
+        logDebug('queueMutation', {
+            type,
+            priority,
+            source: source.subscriberId,
+            fields: Object.keys(fields),
+            state: this._state,
+            queueDepth: this._queue.length,
+            pendingFieldCount: this._pendingFields.size,
+        });
+        return new Promise((resolve, reject) => {
+            const entry = {
+                id: `mut_${++this._mutationIdCounter}`,
+                type,
+                fields: { ...fields },
+                priority,
+                source,
+                resolve,
+                reject,
+                signal: options?.signal,
+                transportOverride: options?.transportOverride,
+            };
+            if (priority >= MutationPriority.HIGH) {
+                for (const [key, value] of this._pendingFields) {
+                    if (!(key in entry.fields)) {
+                        entry.fields[key] = value;
+                    }
+                }
+                this._pendingFields.clear();
+                // Record timestamps for CRDT fields in the submit that weren't already timestamped
+                for (const key of Object.keys(entry.fields)) {
+                    if (this._isCrdtManagedField(key) && !this._pendingFieldTimestamps.has(key)) {
+                        this._pendingFieldTimestamps.set(key, this._getAdjustedTimestamp());
+                    }
+                }
+            }
+            else {
+                for (const [key, value] of Object.entries(fields)) {
+                    this._pendingFields.set(key, value);
+                    if (this._isCrdtManagedField(key)) {
+                        this._pendingFieldTimestamps.set(key, this._getAdjustedTimestamp());
+                    }
+                }
+            }
+            this._queue.push(entry);
+            this._queue.sort((a, b) => b.priority - a.priority);
+            if (this._queue.length > 1) {
+                this._autoCoalesceQueue();
+            }
+            this._transition({ type: TransitionEventType.QUEUE_MUTATION });
+            this._processQueue();
+        });
+    }
+    /**
+     * Fire-and-forget convenience for autosave.
+     * Errors are observable via snapshot.lastEvent, not via Promise.
+     */
+    autosave(fields) {
+        this.queueMutation(fields, {
+            type: MutationType.AUTOSAVE,
+            priority: MutationPriority.LOW,
+            source: DEFAULT_AUTOSAVE_SOURCE,
+        }).catch(() => {
+            // Swallowed — errors delivered via lastEvent
+        });
+    }
+    /**
+     * Queue all accumulated pending fields as a single mutation.
+     * Returns null if no pending fields exist.
+     */
+    flushPendingFields(options) {
+        if (this._pendingFields.size === 0)
+            return Promise.resolve(null);
+        const fields = {};
+        for (const [key, value] of this._pendingFields) {
+            fields[key] = value;
+        }
+        return this.queueMutation(fields, {
+            type: MutationType.AUTOSAVE,
+            priority: options?.priority ?? MutationPriority.NORMAL,
+            source: options?.source ?? DEFAULT_AUTOSAVE_SOURCE,
+            signal: options?.signal,
+        });
+    }
+    /**
+     * Cancel all pending and in-flight mutations. Rejects Promises with
+     * MutationCancelledError. Aborts in-flight via AbortController.
+     * Pending field accumulator is preserved (hasUnsavedChanges stays true).
+     */
+    cancelPendingMutations(source) {
+        if (this._state === RMMState.DELETED)
+            return;
+        logDebug('cancelPendingMutations', {
+            source: source?.subscriberId,
+            queueDepth: this._queue.length,
+            hasActiveMutation: this._activeMutation !== null,
+            pendingFieldCount: this._pendingFields.size,
+        });
+        if (this._retryTimer) {
+            clearTimeout(this._retryTimer);
+            this._retryTimer = null;
+        }
+        if (this._activeMutation) {
+            this._activeMutation.abortController.abort();
+            this._activeMutation.entry.reject(new MutationCancelledError(source));
+            this._activeMutation = null;
+        }
+        for (const entry of this._queue) {
+            entry.reject(new MutationCancelledError(source));
+        }
+        this._queue = [];
+        this._deferredSelfEvents = [];
+        this._pendingFieldTimestamps.clear();
+        this._transition({ type: TransitionEventType.CANCEL });
+    }
+    /**
+     * Transition out of CONFLICT state. Typically called by the consumer after
+     * showing a conflict banner and resetting the form to remote data.
+     */
+    acknowledgeConflict() {
+        if (this._state !== RMMState.CONFLICT)
+            return;
+        logDebug('acknowledgeConflict', { resourceId: this._resourceId });
+        this._transition({ type: TransitionEventType.CONFLICT_ACKNOWLEDGED });
+        this._processQueue();
+    }
+    // =============================================================================
+    // PUBLIC API — Remote Events
+    // =============================================================================
+    /**
+     * Apply a remote update from another user (typically via WebSocket).
+     *
+     * Self-event handling: when `initiatorUserId === currentUserId` and a mutation
+     * is in-flight, the event is deferred (pushed to `_deferredSelfEvents`) and
+     * reconciled when the HTTP response arrives. Without an in-flight mutation,
+     * self-events are discarded immediately (the HTTP response already updated state).
+     *
+     * Silent merge when no pending field overlap. Falls through to conflictPolicy
+     * when overlap exists.
+     */
+    applyRemoteUpdate(changedFields, version, initiatorUserId, _fieldMeta) {
+        if (this._state === RMMState.DELETED)
+            return;
+        if (initiatorUserId && this._config.currentUserId && initiatorUserId === this._config.currentUserId) {
+            if (this._activeMutation !== null) {
+                // Self-originated websocket echoes are deferred while the matching
+                // mutation is still in flight so the canonical HTTP/read-back path gets
+                // first chance to settle confirmed truth.
+                logDebug('applyRemoteUpdate: self-event deferred (mutation in-flight)', {
+                    version,
+                    activeMutationId: this._activeMutation.entry.id,
+                });
+                this._deferredSelfEvents.push({ changedFields, version, initiatorUserId, fieldMeta: _fieldMeta });
+                return;
+            }
+            if (this._allowSettledSelfEventRepair) {
+                // If the immediate authoritative read-back missed, one later settled
+                // self-event may repair confirmed truth instead of being discarded as a
+                // normal echo.
+                this._clearAuthoritativeRecoveryTimer();
+                this._allowSettledSelfEventRepair = false;
+                logDebug('applyRemoteUpdate: accepting settled self-event after canonical read-back miss', { version });
+                this._applyRemoteUpdateInternal(changedFields, version, initiatorUserId, _fieldMeta, true);
+                return;
+            }
+            logDebug('applyRemoteUpdate: self-event discarded (no in-flight mutation)', { version });
+            return;
+        }
+        this._applyRemoteUpdateInternal(changedFields, version, initiatorUserId, _fieldMeta);
+    }
+    /**
+     * Transition to DELETED from any state. Aborts in-flight, rejects all queued
+     * Promises with ResourceDeletedError.
+     */
+    handleDeletion(reason, deletedBy) {
+        logDebug('handleDeletion', { reason, deletedBy, resourceId: this._resourceId });
+        this._transition({ type: TransitionEventType.DELETE, reason, deletedBy });
+    }
+    // =============================================================================
+    // PUBLIC API — Snapshot (for useSyncExternalStore)
+    // =============================================================================
+    subscribe(callback) {
+        this._snapshotListeners.add(callback);
+        return () => {
+            this._snapshotListeners.delete(callback);
+        };
+    }
+    /**
+     * Returns a referentially stable snapshot. Same object reference when
+     * state hasn't changed — useSyncExternalStore won't trigger re-render.
+     */
+    getSnapshot() {
+        if (this._cachedSnapshot && this._cachedSnapshotVersion === this._snapshotVersion) {
+            return this._cachedSnapshot;
+        }
+        const optimisticData = this._getOptimisticData();
+        const pendingFieldNames = Array.from(this._pendingFields.keys());
+        const pendingFieldValues = {};
+        for (const [key, value] of this._pendingFields) {
+            pendingFieldValues[key] = value;
+        }
+        this._cachedSnapshot = {
+            state: this._state,
+            version: this._version,
+            confirmedData: this._confirmedData,
+            optimisticData,
+            pendingFieldNames,
+            pendingFieldValues,
+            isSaving: this._state === RMMState.SAVING,
+            isDeleted: this._state === RMMState.DELETED,
+            hasUnsavedChanges: this._pendingFields.size > 0 || this._queue.length > 0 || this._activeMutation !== null,
+            error: this._lastError,
+            queueDepth: this._queue.length,
+            lastEvent: this._lastEvent,
+        };
+        this._cachedSnapshotVersion = this._snapshotVersion;
+        return this._cachedSnapshot;
+    }
+    // =============================================================================
+    // PUBLIC API — Lifecycle
+    // =============================================================================
+    /**
+     * Flush pending fields, wait for in-flight to complete, then clean up.
+     * Called by the registry when refCount reaches zero after DESTROY_DELAY_MS.
+     *
+     * Bounded flush loop: retry-exhausted fields may be returned to _pendingFields
+     * after the first flush completes, so we re-check up to 3 times.
+     */
+    async destroy() {
+        logDebug('destroy: starting', {
+            resourceId: this._resourceId,
+            pendingFieldCount: this._pendingFields.size,
+            queueDepth: this._queue.length,
+            hasActiveMutation: this._activeMutation !== null,
+        });
+        let flushAttempts = 0;
+        while (this._pendingFields.size > 0 && flushAttempts++ < 3) {
+            try {
+                await this.flushPendingFields();
+            }
+            catch (err) {
+                logDebug('destroy: flushPendingFields failed', {
+                    resourceId: this._resourceId,
+                    attempt: flushAttempts,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                break;
+            }
+        }
+        if (this._pendingFields.size > 0) {
+            logDebug('destroy: completing with pending fields remaining (flush exhausted or failed)', {
+                resourceId: this._resourceId,
+                pendingFieldCount: this._pendingFields.size,
+            });
+        }
+        if (this._activeMutation || this._queue.length > 0) {
+            logDebug('destroy: waiting for drain', { queueDepth: this._queue.length });
+            await new Promise((resolve) => {
+                this._onDrainCallbacks.push(resolve);
+            });
+        }
+        this._clearTimers();
+        this._clearAuthoritativeRecoveryTimer();
+        this._snapshotListeners.clear();
+        logDebug('destroy: complete', { resourceId: this._resourceId });
+    }
+    // =============================================================================
+    // INTERNAL — State Machine
+    // =============================================================================
+    /**
+     * Single dispatch method for all state transitions. Structured for future
+     * XState v5 migration: guards are pure checks, side effects grouped as
+     * actions, no ad-hoc state assignments outside this method.
+     */
+    _transition(event) {
+        const prevState = this._state;
+        switch (event.type) {
+            case TransitionEventType.QUEUE_MUTATION:
+                if (this._state === RMMState.IDLE) {
+                    this._state = RMMState.QUEUED;
+                }
+                else if (this._state === RMMState.ERROR && !this._retryTimer) {
+                    this._state = RMMState.QUEUED;
+                }
+                this._invalidateSnapshot();
+                return;
+            case TransitionEventType.START_SAVING:
+                if (this._state === RMMState.QUEUED) {
+                    this._state = RMMState.SAVING;
+                    this._lastError = null;
+                    this._startBackpressureTimers();
+                }
+                break;
+            case TransitionEventType.SAVE_SUCCESS: {
+                this._state =
+                    this._queue.length > 0 || this._pendingFields.size > 0 ? RMMState.QUEUED : RMMState.IDLE;
+                this._lastError = null;
+                this._clearTimers();
+                if (event.result.data) {
+                    this._mergeResponseDataIntoConfirmed(event.result.data);
+                }
+                if (event.result.newVersion !== undefined) {
+                    this._version = event.result.newVersion;
+                }
+                this._lastEvent = {
+                    type: RMMEventType.MUTATION_RESULT,
+                    result: {
+                        success: true,
+                        savedFields: event.savedFields,
+                        newVersion: event.result.newVersion,
+                        responseData: event.result.data,
+                    },
+                    source: event.source,
+                    id: ++this._eventCounter,
+                };
+                break;
+            }
+            case TransitionEventType.SAVE_ERROR: {
+                const errorType = event.result.error?.type;
+                const mutationError = event.result.error
+                    ? {
+                        type: event.result.error.type,
+                        status: event.result.error.status,
+                        validationErrors: event.result.error.validationErrors,
+                        message: event.result.error.message,
+                        conflictDetails: event.result.error.conflictDetails,
+                    }
+                    : { type: MutationErrorType.SERVER, message: 'Unknown error' };
+                this._lastError = mutationError;
+                // --- Conflict (409) ---
+                if (errorType === MutationErrorType.CONFLICT) {
+                    this._clearTimers();
+                    this._state = RMMState.CONFLICT;
+                    const allDiscardedFields = [...new Set([
+                            ...event.savedFields,
+                            ...this._pendingFields.keys(),
+                        ])];
+                    for (const entry of this._queue) {
+                        entry.reject(new MutationCancelledError());
+                    }
+                    this._queue = [];
+                    this._pendingFields.clear();
+                    this._pendingFieldTimestamps.clear();
+                    this._deferredSelfEvents = [];
+                    const cd = mutationError.conflictDetails;
+                    const serverSlice = cd?.currentValues;
+                    const currentData = serverSlice && Object.keys(serverSlice).length > 0
+                        ? { ...(this._confirmedData ?? {}), ...serverSlice }
+                        : (this._confirmedData ?? {});
+                    const currentVersion = cd?.currentVersion ?? this._version ?? 0;
+                    this._confirmedData = { ...currentData };
+                    this._version = currentVersion;
+                    this._lastEvent = {
+                        type: RMMEventType.CONFLICT_RESET,
+                        discardedFields: allDiscardedFields,
+                        reason: ConflictReason.VERSION_CONFLICT,
+                        currentData,
+                        currentVersion,
+                        conflictDetails: cd,
+                        id: ++this._eventCounter,
+                    };
+                    break;
+                }
+                // --- Abort (no retry, no lastEvent — communicated via Promise rejection) ---
+                if (errorType === MutationErrorType.ABORT) {
+                    this._clearTimers();
+                    const nextState = this._queue.length > 0 || this._pendingFields.size > 0 ? RMMState.QUEUED : RMMState.IDLE;
+                    this._state = nextState;
+                    if (nextState === RMMState.IDLE) {
+                        this._lastError = null;
+                    }
+                    break;
+                }
+                // --- Validation / Not Found (no retry, with lastEvent) ---
+                if (errorType === MutationErrorType.VALIDATION || errorType === MutationErrorType.NOT_FOUND) {
+                    this._clearTimers();
+                    if (errorType === MutationErrorType.VALIDATION && this._activeMutation) {
+                        for (const field of event.savedFields) {
+                            if (!this._pendingFields.has(field)) {
+                                this._pendingFields.set(field, this._activeMutation.savingFields[field]);
+                            }
+                        }
+                    }
+                    this._lastEvent = {
+                        type: RMMEventType.MUTATION_RESULT,
+                        result: {
+                            success: false,
+                            savedFields: event.savedFields,
+                            error: mutationError,
+                            retriesRemaining: 0,
+                        },
+                        source: event.source,
+                        id: ++this._eventCounter,
+                    };
+                    this._state =
+                        this._queue.length > 0 || this._pendingFields.size > 0 ? RMMState.QUEUED : RMMState.IDLE;
+                    break;
+                }
+                // --- Transient / Server (may retry) ---
+                const retryCount = this._activeMutation?.retryCount ?? 0;
+                const maxRetries = errorType === MutationErrorType.TRANSIENT
+                    ? this._retryDelays.length
+                    : errorType === MutationErrorType.SERVER
+                        ? 1
+                        : 0;
+                if (retryCount < maxRetries) {
+                    const delay = errorType === MutationErrorType.TRANSIENT
+                        ? this._retryDelays[retryCount]
+                        : this._serverRetryDelay;
+                    this._state = RMMState.ERROR;
+                    this._lastEvent = {
+                        type: RMMEventType.MUTATION_RESULT,
+                        result: {
+                            success: false,
+                            savedFields: event.savedFields,
+                            error: mutationError,
+                            retriesRemaining: maxRetries - retryCount,
+                        },
+                        source: event.source,
+                        id: ++this._eventCounter,
+                    };
+                    this._retryTimer = setTimeout(() => {
+                        this._retryTimer = null;
+                        if (this._state !== RMMState.ERROR || !this._activeMutation)
+                            return;
+                        this._activeMutation.retryCount++;
+                        logDebug('retry: attempt', {
+                            mutationId: this._activeMutation.entry.id,
+                            retryCount: this._activeMutation.retryCount,
+                            maxRetries,
+                            delayMs: delay,
+                        });
+                        this._transition({ type: TransitionEventType.RETRY });
+                        this._executeTransport(this._activeMutation);
+                    }, delay);
+                    break;
+                }
+                // --- Retry exhausted ---
+                this._clearTimers();
+                if (this._activeMutation) {
+                    for (const field of event.savedFields) {
+                        if (!this._pendingFields.has(field)) {
+                            this._pendingFields.set(field, this._activeMutation.savingFields[field]);
+                        }
+                    }
+                }
+                this._lastEvent = {
+                    type: RMMEventType.MUTATION_RESULT,
+                    result: {
+                        success: false,
+                        savedFields: event.savedFields,
+                        error: mutationError,
+                        retriesRemaining: 0,
+                    },
+                    source: event.source,
+                    id: ++this._eventCounter,
+                };
+                this._state =
+                    this._queue.length > 0 || this._pendingFields.size > 0 ? RMMState.QUEUED : RMMState.IDLE;
+                break;
+            }
+            case TransitionEventType.RETRY:
+                if (this._state === RMMState.ERROR) {
+                    this._state = RMMState.SAVING;
+                }
+                break;
+            case TransitionEventType.CONFLICT_DETECTED: {
+                this._clearTimers();
+                this._state = RMMState.CONFLICT;
+                if (this._activeMutation) {
+                    this._activeMutation.abortController.abort();
+                    this._activeMutation.entry.reject(new MutationCancelledError());
+                    this._activeMutation = null;
+                }
+                for (const entry of this._queue) {
+                    entry.reject(new MutationCancelledError());
+                }
+                this._queue = [];
+                this._pendingFields.clear();
+                this._pendingFieldTimestamps.clear();
+                this._deferredSelfEvents = [];
+                this._confirmedData = { ...event.currentData };
+                this._version = event.currentVersion;
+                this._lastEvent = {
+                    type: RMMEventType.CONFLICT_RESET,
+                    discardedFields: event.discardedFields,
+                    reason: event.reason,
+                    currentData: event.currentData,
+                    currentVersion: event.currentVersion,
+                    conflictDetails: event.conflictDetails,
+                    id: ++this._eventCounter,
+                };
+                break;
+            }
+            case TransitionEventType.CONFLICT_ACKNOWLEDGED:
+                if (this._state === RMMState.CONFLICT) {
+                    this._state = this._queue.length > 0 ? RMMState.QUEUED : RMMState.IDLE;
+                    this._lastError = null;
+                }
+                break;
+            case TransitionEventType.CANCEL:
+                this._state = RMMState.IDLE;
+                this._lastError = null;
+                break;
+            case TransitionEventType.DELETE: {
+                this._clearTimers();
+                if (this._activeMutation) {
+                    this._activeMutation.abortController.abort();
+                    this._activeMutation.entry.reject(new ResourceDeletedError());
+                    this._activeMutation = null;
+                }
+                for (const entry of this._queue) {
+                    entry.reject(new ResourceDeletedError());
+                }
+                this._queue = [];
+                this._pendingFields.clear();
+                this._pendingFieldTimestamps.clear();
+                this._deferredSelfEvents = [];
+                this._state = RMMState.DELETED;
+                this._lastEvent = {
+                    type: RMMEventType.RESOURCE_DELETED,
+                    reason: event.reason,
+                    deletedBy: event.deletedBy,
+                    id: ++this._eventCounter,
+                };
+                break;
+            }
+            case TransitionEventType.REMOTE_UPDATE:
+                this._lastEvent = {
+                    type: RMMEventType.REMOTE_UPDATE,
+                    changedFields: event.changedFields,
+                    mergedFields: event.mergedFields,
+                    version: event.version,
+                    initiatorUserId: event.initiatorUserId,
+                    crdtResolutions: event.crdtResolutions,
+                    id: ++this._eventCounter,
+                };
+                break;
+        }
+        if (this._state !== prevState) {
+            logDebug('_transition', {
+                event: event.type,
+                from: prevState,
+                to: this._state,
+                queueDepth: this._queue.length,
+                pendingFieldCount: this._pendingFields.size,
+                hasActiveMutation: this._activeMutation !== null,
+                lastEventType: this._lastEvent?.type,
+            });
+        }
+        this._invalidateSnapshot();
+    }
+    // =============================================================================
+    // INTERNAL — Queue Processing
+    // =============================================================================
+    /**
+     * Process the next mutation in the queue if no mutation is currently in-flight.
+     * Uses move semantics: fields are moved from _pendingFields into savingFields.
+     */
+    _processQueue() {
+        if (this._activeMutation !== null)
+            return;
+        if (this._queue.length === 0)
+            return;
+        if (this._state === RMMState.CONFLICT || this._state === RMMState.DELETED || this._state === RMMState.ERROR)
+            return;
+        const entry = this._queue.shift();
+        let savingFields;
+        if (entry.type === MutationType.SUBMIT || entry.type === MutationType.DRAFT || entry.type === MutationType.PUBLISH) {
+            savingFields = { ...entry.fields };
+            this._pendingFields.clear();
+        }
+        else {
+            savingFields = {};
+            for (const key of Object.keys(entry.fields)) {
+                if (this._pendingFields.has(key)) {
+                    savingFields[key] = this._pendingFields.get(key);
+                    this._pendingFields.delete(key);
+                }
+                else {
+                    savingFields[key] = entry.fields[key];
+                }
+            }
+        }
+        logDebug('_processQueue: dequeued', {
+            mutationId: entry.id,
+            type: entry.type,
+            priority: entry.priority,
+            savingFields: Object.keys(savingFields),
+            remainingQueue: this._queue.length,
+            remainingPending: this._pendingFields.size,
+        });
+        const abortController = new AbortController();
+        // AbortSignal composition: wire caller's signal to our controller
+        if (entry.signal) {
+            if (entry.signal.aborted) {
+                entry.reject(new MutationCancelledError(entry.source));
+                this._processQueue();
+                return;
+            }
+            entry.signal.addEventListener('abort', () => abortController.abort(), { once: true });
+        }
+        this._activeMutation = {
+            entry,
+            savingFields,
+            abortController,
+            retryCount: 0,
+        };
+        this._transition({ type: TransitionEventType.START_SAVING });
+        this._executeTransport(this._activeMutation);
+    }
+    /**
+     * Execute the transport adapter for a mutation. Captures `thisMutation`
+     * reference before the async call to detect stale callbacks — if
+     * cancelPendingMutations() runs during the await, the callback bails out.
+     */
+    _executeTransport(mutation) {
+        const thisMutation = mutation;
+        logDebug('_executeTransport: sending', {
+            mutationId: mutation.entry.id,
+            type: mutation.entry.type,
+            fields: Object.keys(mutation.savingFields),
+            version: this._version,
+            retryCount: mutation.retryCount,
+        });
+        // Build field timestamps for CRDT fields being sent
+        const fieldTimestamps = {};
+        for (const field of Object.keys(mutation.savingFields)) {
+            if (this._isCrdtManagedField(field)) {
+                const ts = this._pendingFieldTimestamps.get(field);
+                if (ts !== undefined) {
+                    fieldTimestamps[field] = ts;
+                }
+            }
+        }
+        const transportOverride = thisMutation.entry.transportOverride;
+        const descriptor = {
+            operationPathKey: transportOverride?.operationPathKey ?? this._config.operationPathKey ?? this._config.resourceType,
+            contextualParameters: transportOverride?.contextualParameters ?? this._config.contextualParameters,
+            parentResourcesRequirements: transportOverride?.parentResourcesRequirements ?? this._config.parentResourcesRequirements,
+            requestData: transportOverride?.requestData ?? mutation.savingFields,
+            expectedVersion: this._version,
+            signal: mutation.abortController.signal,
+            fieldTimestamps: Object.keys(fieldTimestamps).length > 0
+                ? fieldTimestamps
+                : undefined,
+        };
+        this._config.transportAdapter.execute(descriptor).then(async (rawResult) => {
+            if (this._activeMutation !== thisMutation) {
+                logDebug('_executeTransport: stale callback — ignored', { mutationId: thisMutation.entry.id });
+                return;
+            }
+            const savedFields = Object.keys(thisMutation.savingFields);
+            const source = thisMutation.entry.source;
+            const result = rawResult.status === OperationResultStatus.SUCCESS && transportOverride?.readBackOnSuccess
+                ? await this._readBackConfirmedState(rawResult)
+                : rawResult;
+            if (result.status === OperationResultStatus.SUCCESS) {
+                logDebug('_executeTransport: success', {
+                    mutationId: thisMutation.entry.id,
+                    savedFields,
+                    newVersion: result.newVersion,
+                });
+                // Store _fieldMeta from transport response (preserve null semantics)
+                const rawTransportMeta = result.fieldMeta ?? result.data?._field_meta;
+                if (rawTransportMeta != null) {
+                    this._fieldMeta = sanitizeFieldMeta(rawTransportMeta);
+                }
+                for (const field of savedFields) {
+                    this._pendingFieldTimestamps.delete(field);
+                }
+                this._transition({ type: TransitionEventType.SAVE_SUCCESS, result, savedFields, source });
+                this._activeMutation = null;
+                this._processDeferredSelfEvents(result.newVersion);
+                this._invalidateSnapshot();
+                thisMutation.entry.resolve({
+                    success: true,
+                    savedFields,
+                    newVersion: result.newVersion,
+                    responseData: result.data,
+                });
+                this._processQueue();
+                this._notifyDrained();
+            }
+            else {
+                logDebug('_executeTransport: error', {
+                    mutationId: thisMutation.entry.id,
+                    errorType: result.error?.type,
+                    errorStatus: result.error?.status,
+                    errorMessage: result.error?.message,
+                    savedFields,
+                });
+                this._transition({ type: TransitionEventType.SAVE_ERROR, result, savedFields, source });
+                if (this._state === RMMState.ERROR) {
+                    // Retry scheduled — mutation stays alive, don't resolve/reject yet
+                }
+                else if (this._state === RMMState.CONFLICT) {
+                    this._activeMutation = null;
+                    this._processDeferredSelfEvents(result.newVersion);
+                    this._invalidateSnapshot();
+                    thisMutation.entry.resolve({
+                        success: false,
+                        savedFields,
+                        error: {
+                            type: MutationErrorType.CONFLICT,
+                            conflictDetails: result.error?.conflictDetails,
+                        },
+                    });
+                    this._notifyDrained();
+                }
+                else if (result.error?.type === MutationErrorType.ABORT) {
+                    this._activeMutation = null;
+                    this._processDeferredSelfEvents(result.newVersion);
+                    this._invalidateSnapshot();
+                    thisMutation.entry.reject(new MutationCancelledError(thisMutation.entry.source));
+                    this._processQueue();
+                    this._notifyDrained();
+                }
+                else {
+                    this._activeMutation = null;
+                    this._processDeferredSelfEvents(result.newVersion);
+                    this._invalidateSnapshot();
+                    thisMutation.entry.resolve({
+                        success: false,
+                        savedFields,
+                        error: result.error
+                            ? {
+                                type: result.error.type,
+                                status: result.error.status,
+                                validationErrors: result.error.validationErrors,
+                                message: result.error.message,
+                            }
+                            : undefined,
+                    });
+                    this._processQueue();
+                    this._notifyDrained();
+                }
+            }
+        }, (error) => {
+            if (this._activeMutation !== thisMutation) {
+                logDebug('_executeTransport: stale rejection — ignored', { mutationId: thisMutation.entry.id });
+                return;
+            }
+            const savedFields = Object.keys(thisMutation.savingFields);
+            const source = thisMutation.entry.source;
+            logDebug('_executeTransport: transport rejected', {
+                mutationId: thisMutation.entry.id,
+                error: error instanceof Error ? error.message : String(error),
+                savedFields,
+            });
+            this._transition({
+                type: TransitionEventType.SAVE_ERROR,
+                result: {
+                    status: OperationResultStatus.ERROR,
+                    error: {
+                        type: MutationErrorType.TRANSIENT,
+                        message: error instanceof Error ? error.message : String(error),
+                    },
+                },
+                savedFields,
+                source,
+            });
+            if (this._state === RMMState.ERROR) {
+                // Retry scheduled — mutation stays alive
+            }
+            else {
+                this._activeMutation = null;
+                this._processDeferredSelfEvents(undefined);
+                this._invalidateSnapshot();
+                thisMutation.entry.resolve({
+                    success: false,
+                    savedFields,
+                    error: {
+                        type: MutationErrorType.TRANSIENT,
+                        message: error instanceof Error ? error.message : String(error),
+                    },
+                });
+                this._processQueue();
+                this._notifyDrained();
+            }
+        });
+    }
+    // =============================================================================
+    // INTERNAL — Authoritative Refresh
+    // =============================================================================
+    async _readBackConfirmedState(result) {
+        const readOperationPathKey = this._config.readOperationPathKey;
+        if (!readOperationPathKey) {
+            return result;
+        }
+        // Successful mutations still prefer one canonical RAW reread before the
+        // mutation result is promoted to confirmedData. That keeps mutation success
+        // and websocket replay on the same authoritative read contract.
+        const readResult = await this._config.transportAdapter.execute({
+            operationPathKey: readOperationPathKey,
+            contextualParameters: this._config.contextualParameters,
+            parentResourcesRequirements: this._config.parentResourcesRequirements,
+            dataMode: DataMode.RAW,
+            signal: undefined,
+        });
+        if (readResult.status !== OperationResultStatus.SUCCESS) {
+            this._allowSettledSelfEventRepair = true;
+            this._scheduleAuthoritativeRecovery();
+            // Keep the mutation marked successful, but strip read-shaped data/field
+            // metadata so callers do not accidentally trust a partial mutation
+            // response as canonical confirmed state.
+            logDebug('_readBackConfirmedState: falling back to mutation response', {
+                errorType: readResult.error?.type,
+                errorStatus: readResult.error?.status,
+            });
+            return {
+                ...result,
+                data: undefined,
+                fieldMeta: undefined,
+            };
+        }
+        this._clearAuthoritativeRecoveryTimer();
+        this._allowSettledSelfEventRepair = false;
+        return {
+            ...result,
+            data: readResult.data,
+            newVersion: readResult.newVersion ?? result.newVersion,
+            fieldMeta: readResult.fieldMeta ?? result.fieldMeta,
+        };
+    }
+    // =============================================================================
+    // INTERNAL — Optimistic Data
+    // =============================================================================
+    /**
+     * Merges transport success payload into `_confirmedData` using `deepSetByPath` per
+     * entry so dotted keys and nested shapes match optimistic/remote merge semantics
+     * (avoids shallow spread clobbering nested objects).
+     */
+    _mergeResponseDataIntoConfirmed(data) {
+        const base = this._confirmedData !== null ? structuredClone(this._confirmedData) : {};
+        for (const [path, value] of Object.entries(data)) {
+            deepSetByPath(base, path, value);
+        }
+        this._confirmedData = base;
+    }
+    /**
+     * Path-aware deep merge of _confirmedData + in-flight savingFields + _pendingFields.
+     * Uses deepSetByPath for nested paths (e.g., "metadata.theme" sets the nested property,
+     * not a top-level key named "metadata.theme").
+     */
+    _getOptimisticData() {
+        if (!this._confirmedData)
+            return null;
+        if (this._pendingFields.size === 0 && !this._activeMutation) {
+            return this._confirmedData;
+        }
+        if (this._optimisticDataVersion === this._snapshotVersion) {
+            return this._cachedOptimisticData;
+        }
+        const result = structuredClone(this._confirmedData);
+        if (this._activeMutation) {
+            for (const [key, value] of Object.entries(this._activeMutation.savingFields)) {
+                deepSetByPath(result, key, value);
+            }
+        }
+        for (const [key, value] of this._pendingFields) {
+            deepSetByPath(result, key, value);
+        }
+        this._cachedOptimisticData = result;
+        this._optimisticDataVersion = this._snapshotVersion;
+        return result;
+    }
+    // =============================================================================
+    // INTERNAL — Snapshot Management
+    // =============================================================================
+    _invalidateSnapshot() {
+        this._snapshotVersion++;
+        this._cachedSnapshot = null;
+        for (const listener of this._snapshotListeners) {
+            listener();
+        }
+    }
+    /**
+     * Internal merge logic shared by applyRemoteUpdate and _processDeferredSelfEvents.
+     * Skips the self-event guard — callers are responsible for determining whether
+     * the event should be processed.
+     */
+    _applyRemoteUpdateInternal(changedFields, version, initiatorUserId, _fieldMeta, acceptEqualVersion = false) {
+        if (this._state === RMMState.DELETED)
+            return;
+        const previousVersion = this._version;
+        this._clearAuthoritativeRecoveryTimer();
+        const localSubmittedBase = structuredClone(this._confirmedData ?? {});
+        if (this._activeMutation) {
+            for (const [field, value] of Object.entries(this._activeMutation.savingFields)) {
+                deepSetByPath(localSubmittedBase, field, value);
+            }
+        }
+        for (const [field, value] of this._pendingFields) {
+            deepSetByPath(localSubmittedBase, field, value);
+        }
+        if (this._version !== null && (acceptEqualVersion ? version < this._version : version <= this._version)) {
+            logDebug('_applyRemoteUpdateInternal: stale — ignored', {
+                incomingVersion: version,
+                currentVersion: this._version,
+            });
+            return;
+        }
+        const changedFieldNames = Object.keys(changedFields);
+        const pendingFieldNames = [...this._pendingFields.keys()];
+        const savingFieldNames = this._activeMutation
+            ? Object.keys(this._activeMutation.savingFields)
+            : [];
+        const localDirtyFieldNames = [...new Set([...savingFieldNames, ...pendingFieldNames])];
+        const overlapping = changedFieldNames.filter((remoteField) => (localDirtyFieldNames.some((localField) => rmmFieldPathsOverlap(remoteField, localField))));
+        logDebug('_applyRemoteUpdateInternal', {
+            version,
+            changedFields: changedFieldNames,
+            overlappingFields: overlapping,
+            initiatorUserId,
+            state: this._state,
+        });
+        // --- Field-level merge (CRDT-aware) ---
+        // Separate overlapping fields into CRDT and non-CRDT
+        const crdtOverlap = [];
+        const nonCrdtOverlap = [];
+        for (const field of overlapping) {
+            if (this._isCrdtManagedField(field)) {
+                crdtOverlap.push(field);
+            }
+            else {
+                nonCrdtOverlap.push(field);
+            }
+        }
+        const mergedFields = [];
+        const crdtResolutions = {};
+        const updated = structuredClone(this._confirmedData ?? {});
+        // Non-overlapping fields: always merge silently
+        for (const field of changedFieldNames) {
+            if (!overlapping.includes(field)) {
+                deepSetByPath(updated, field, changedFields[field]);
+                mergedFields.push(field);
+            }
+        }
+        // CRDT overlapping fields: use shared LWW winner function
+        for (const field of crdtOverlap) {
+            const pendingConflictField = localDirtyFieldNames.find((localField) => rmmFieldPathsOverlap(field, localField));
+            const remoteTs = _fieldMeta?.[field]?.ts ?? 0;
+            const localTs = pendingConflictField
+                ? this._pendingFieldTimestamps.get(pendingConflictField) ?? 0
+                : 0;
+            const winner = lwwFieldWinner(remoteTs, localTs);
+            crdtResolutions[field] = winner;
+            if (winner === CrdtResolutionWinner.INCOMING) {
+                if (pendingConflictField) {
+                    this._pendingFields.delete(pendingConflictField);
+                    this._pendingFieldTimestamps.delete(pendingConflictField);
+                }
+                deepSetByPath(updated, field, changedFields[field]);
+                mergedFields.push(field);
+                logDebug('CRDT LWW: remote wins', { field, remoteTs, localTs });
+            }
+            else {
+                logDebug('CRDT LWW: local wins (keep pending)', { field, remoteTs, localTs });
+            }
+        }
+        this._confirmedData = updated;
+        // Update field meta from remote (sanitize to guard against corrupted payloads)
+        if (_fieldMeta != null) {
+            this._fieldMeta = { ...sanitizeFieldMeta(this._fieldMeta), ...sanitizeFieldMeta(_fieldMeta) };
+        }
+        this._version = version;
+        const hasCrdtResolutions = Object.keys(crdtResolutions).length > 0 ? crdtResolutions : undefined;
+        // If all overlapping fields were resolved (no non-CRDT conflicts remain):
+        if (nonCrdtOverlap.length === 0) {
+            this._transition({
+                type: TransitionEventType.REMOTE_UPDATE,
+                changedFields: changedFieldNames,
+                mergedFields,
+                version,
+                initiatorUserId,
+                crdtResolutions: hasCrdtResolutions,
+            });
+            return;
+        }
+        // Non-CRDT overlap remains — fall through to conflictPolicy
+        if (this._config.conflictPolicy.strategy === ConflictStrategy.LAST_WRITE_WINS) {
+            this._transition({
+                type: TransitionEventType.REMOTE_UPDATE,
+                changedFields: changedFieldNames,
+                mergedFields,
+                version,
+                initiatorUserId,
+                crdtResolutions: hasCrdtResolutions,
+            });
+            return;
+        }
+        // accept-remote: transition to CONFLICT for non-CRDT overlap.
+        // CRDT fields that local won must survive the conflict transition.
+        const crdtWonEntries = new Map();
+        const crdtWonTimestamps = new Map();
+        for (const field of crdtOverlap) {
+            const pendingConflictField = localDirtyFieldNames.find((localField) => rmmFieldPathsOverlap(field, localField));
+            const localTs = pendingConflictField
+                ? this._pendingFieldTimestamps.get(pendingConflictField) ?? 0
+                : 0;
+            const remoteTs = _fieldMeta?.[field]?.ts ?? 0;
+            if (pendingConflictField
+                && lwwFieldWinner(remoteTs, localTs) === CrdtResolutionWinner.EXISTING
+                && this._pendingFields.has(pendingConflictField)) {
+                crdtWonEntries.set(pendingConflictField, this._pendingFields.get(pendingConflictField));
+                const ts = this._pendingFieldTimestamps.get(pendingConflictField);
+                if (ts !== undefined)
+                    crdtWonTimestamps.set(pendingConflictField, ts);
+            }
+        }
+        const newData = structuredClone(this._confirmedData ?? {});
+        for (const [field, value] of Object.entries(changedFields)) {
+            deepSetByPath(newData, field, value);
+        }
+        const discardedFields = localDirtyFieldNames
+            .filter((field) => !crdtWonEntries.has(field));
+        const conflictDetails = {
+            currentVersion: version,
+            expectedVersion: previousVersion ?? version,
+            conflictingFields: overlapping,
+            currentValues: Object.fromEntries(overlapping.map((field) => [field, rmmReadPathValue(newData, field)])),
+            submittedValues: Object.fromEntries(overlapping.map((field) => [field, rmmReadPathValue(localSubmittedBase, field)])),
+        };
+        this._transition({
+            type: TransitionEventType.CONFLICT_DETECTED,
+            discardedFields,
+            reason: ConflictReason.REMOTE_UPDATE,
+            currentData: newData,
+            currentVersion: version,
+            conflictDetails,
+        });
+        // Restore CRDT-won pending fields after the conflict transition
+        for (const [field, value] of crdtWonEntries) {
+            this._pendingFields.set(field, value);
+        }
+        for (const [field, ts] of crdtWonTimestamps) {
+            this._pendingFieldTimestamps.set(field, ts);
+        }
+    }
+    /**
+     * Process deferred self-events after an HTTP response arrives.
+     * - Version matches response → discard (same mutation, already handled)
+     * - Version differs → process as genuine remote change (another tab/device saved)
+     */
+    _processDeferredSelfEvents(responseVersion) {
+        if (this._deferredSelfEvents.length === 0)
+            return;
+        const deferred = this._deferredSelfEvents;
+        this._deferredSelfEvents = [];
+        for (const event of deferred) {
+            if (responseVersion !== undefined && event.version === responseVersion) {
+                if (this._allowSettledSelfEventRepair) {
+                    this._clearAuthoritativeRecoveryTimer();
+                    this._allowSettledSelfEventRepair = false;
+                    logDebug('_processDeferredSelfEvents: accepting deferred self-event after canonical read-back miss', {
+                        version: event.version,
+                    });
+                    this._applyRemoteUpdateInternal(event.changedFields, event.version, event.initiatorUserId, event.fieldMeta, true);
+                    continue;
+                }
+                logDebug('_processDeferredSelfEvents: discarded (version matches response)', {
+                    version: event.version,
+                });
+                continue;
+            }
+            logDebug('_processDeferredSelfEvents: processing as remote change', {
+                eventVersion: event.version,
+                responseVersion,
+            });
+            this._applyRemoteUpdateInternal(event.changedFields, event.version, event.initiatorUserId, event.fieldMeta);
+        }
+    }
+    // =============================================================================
+    // INTERNAL — Timer Management
+    // =============================================================================
+    _clearTimers() {
+        if (this._retryTimer) {
+            clearTimeout(this._retryTimer);
+            this._retryTimer = null;
+        }
+        if (this._softTimer) {
+            clearTimeout(this._softTimer);
+            this._softTimer = null;
+        }
+        if (this._hardTimer) {
+            clearTimeout(this._hardTimer);
+            this._hardTimer = null;
+        }
+    }
+    /**
+     * Schedules one later canonical RAW reread after a successful mutation whose
+     * immediate authoritative read-back failed. This keeps confirmed truth
+     * canonical while avoiding total dependence on websocket self-repair delivery.
+     */
+    _scheduleAuthoritativeRecovery() {
+        if (this._authoritativeRecoveryTimer || this._state === RMMState.DELETED) {
+            return;
+        }
+        this._authoritativeRecoveryTimer = setTimeout(() => {
+            this._authoritativeRecoveryTimer = null;
+            void this._retryAuthoritativeRecovery();
+        }, this._serverRetryDelay);
+    }
+    _clearAuthoritativeRecoveryTimer() {
+        if (this._authoritativeRecoveryTimer) {
+            clearTimeout(this._authoritativeRecoveryTimer);
+            this._authoritativeRecoveryTimer = null;
+        }
+    }
+    async _retryAuthoritativeRecovery() {
+        if (this._state === RMMState.DELETED || !this._allowSettledSelfEventRepair) {
+            return;
+        }
+        // This is the mutation-owned recovery path after a read-back miss. It is
+        // intentionally separate from RMMWebSocketBridge refetches, which are
+        // driven by websocket ingress and reconnection rather than mutation cleanup.
+        const readOperationPathKey = this._config.readOperationPathKey;
+        if (!readOperationPathKey) {
+            return;
+        }
+        const readResult = await this._config.transportAdapter.execute({
+            operationPathKey: readOperationPathKey,
+            contextualParameters: this._config.contextualParameters,
+            parentResourcesRequirements: this._config.parentResourcesRequirements,
+            dataMode: DataMode.RAW,
+            signal: undefined,
+        });
+        if (readResult.status !== OperationResultStatus.SUCCESS || !readResult.data) {
+            logDebug('_retryAuthoritativeRecovery: canonical reread still unavailable', {
+                errorType: readResult.error?.type,
+                errorStatus: readResult.error?.status,
+            });
+            return;
+        }
+        const recoveredVersion = readResult.newVersion ?? this._version;
+        if (recoveredVersion == null) {
+            logDebug('_retryAuthoritativeRecovery: canonical reread missing version', {
+                resourceId: this._resourceId,
+            });
+            return;
+        }
+        logDebug('_retryAuthoritativeRecovery: restored canonical confirmed state', {
+            resourceId: this._resourceId,
+            version: recoveredVersion,
+        });
+        this.setInitialState(readResult.data, recoveredVersion, readResult.fieldMeta);
+    }
+    /**
+     * Start backpressure timers on first START_SAVING. Timers persist across retries
+     * (measuring total elapsed time, not per-attempt). Only started if not already running.
+     *
+     * **Soft timeout:** Emits a non-success `MUTATION_RESULT` on `lastEvent` for UX/telemetry
+     * only — it does **not** abort the transport; the request may still complete and produce
+     * a subsequent event. Treat as "slow operation", not terminal failure.
+     *
+     * **Hard timeout:** Aborts via `AbortSignal` and rejects the mutation — terminal for
+     * the in-flight operation.
+     */
+    _startBackpressureTimers() {
+        if (this._softTimer)
+            return;
+        this._softTimer = setTimeout(() => {
+            this._softTimer = null;
+            if (!this._activeMutation)
+                return;
+            logDebug('backpressure: soft timeout', {
+                mutationId: this._activeMutation.entry.id,
+                timeoutMs: this._backpressure.softTimeoutMs,
+            });
+            this._lastEvent = {
+                type: RMMEventType.MUTATION_RESULT,
+                result: {
+                    success: false,
+                    error: { type: MutationErrorType.TRANSIENT, message: 'Operation taking longer than expected' },
+                },
+                source: this._activeMutation.entry.source,
+                id: ++this._eventCounter,
+            };
+            this._invalidateSnapshot();
+        }, this._backpressure.softTimeoutMs);
+        this._hardTimer = setTimeout(() => {
+            this._hardTimer = null;
+            this._clearTimers();
+            logDebug('backpressure: hard timeout — aborting', {
+                mutationId: this._activeMutation?.entry.id,
+                timeoutMs: this._backpressure.hardTimeoutMs,
+            });
+            const source = this._activeMutation?.entry.source;
+            if (this._activeMutation) {
+                this._activeMutation.abortController.abort();
+                this._activeMutation.entry.reject(new MutationCancelledError(this._activeMutation.entry.source));
+                this._activeMutation = null;
+            }
+            this._deferredSelfEvents = [];
+            const nextState = this._queue.length > 0 || this._pendingFields.size > 0 ? RMMState.QUEUED : RMMState.IDLE;
+            this._state = nextState;
+            if (nextState === RMMState.IDLE) {
+                this._lastError = null;
+            }
+            else {
+                this._lastError = { type: MutationErrorType.TRANSIENT, message: 'Hard timeout exceeded' };
+            }
+            this._lastEvent = {
+                type: RMMEventType.MUTATION_RESULT,
+                result: {
+                    success: false,
+                    error: { type: MutationErrorType.TRANSIENT, message: 'Hard timeout exceeded' },
+                    retriesRemaining: 0,
+                },
+                source: source ?? DEFAULT_AUTOSAVE_SOURCE,
+                id: ++this._eventCounter,
+            };
+            this._invalidateSnapshot();
+            this._processQueue();
+            this._notifyDrained();
+        }, this._backpressure.hardTimeoutMs);
+    }
+    // =============================================================================
+    // INTERNAL — Queue Coalescing
+    // =============================================================================
+    /**
+     * Auto-coalesce when queue depth > 1: merge all entries into the highest-priority
+     * survivor. Absorbed entries' Promises are chained to the survivor's resolution.
+     */
+    _autoCoalesceQueue() {
+        if (this._queue.length <= 1)
+            return;
+        if (this._queue.some((entry) => entry.transportOverride !== undefined)) {
+            return;
+        }
+        let survivorIdx = 0;
+        for (let i = 1; i < this._queue.length; i++) {
+            if (this._queue[i].priority >= this._queue[survivorIdx].priority) {
+                survivorIdx = i;
+            }
+        }
+        const survivor = this._queue[survivorIdx];
+        const absorbed = [];
+        for (let i = 0; i < this._queue.length; i++) {
+            if (i === survivorIdx)
+                continue;
+            const entry = this._queue[i];
+            for (const [key, value] of Object.entries(entry.fields)) {
+                if (!(key in survivor.fields)) {
+                    survivor.fields[key] = value;
+                }
+            }
+            absorbed.push(entry);
+        }
+        logDebug('_autoCoalesceQueue', {
+            survivorId: survivor.id,
+            absorbedCount: absorbed.length,
+            absorbedIds: absorbed.map((e) => e.id),
+            mergedFieldCount: Object.keys(survivor.fields).length,
+        });
+        const originalResolve = survivor.resolve;
+        const originalReject = survivor.reject;
+        survivor.resolve = (result) => {
+            originalResolve(result);
+            for (const entry of absorbed)
+                entry.resolve(result);
+        };
+        survivor.reject = (error) => {
+            originalReject(error);
+            for (const entry of absorbed)
+                entry.reject(error);
+        };
+        this._queue = [survivor];
+    }
+    // =============================================================================
+    // INTERNAL — Destroy Support
+    // =============================================================================
+    _notifyDrained() {
+        if (this._activeMutation !== null || this._queue.length > 0)
+            return;
+        for (const cb of this._onDrainCallbacks)
+            cb();
+        this._onDrainCallbacks = [];
+    }
+}
+//# sourceMappingURL=ResourceMutationManager.js.map