@recordtimelabel/core 0.4.2 → 0.4.4

package/README.md

@@ -17,10 +17,10 @@ During local development an app can consume a sibling checkout with:
 "@recordtimelabel/core": "file:../recordtimelabel-core"
 ```
 
-For release builds, consume a fixed npm package, git tag, or private registry version so builds do not depend on a sibling folder path. The durable identity and explicit entrypoint contract is prepared in package version `0.4.2` (publish it before updating consumers):
+For release builds, consume a fixed npm package, git tag, or private registry version so builds do not depend on a sibling folder path. The current strict durable transport contract is prepared in package version `0.4.4` (publish it before updating consumers):
 
 ```json
-"@recordtimelabel/core": "0.4.2"
+"@recordtimelabel/core": "0.4.4"
 ```
 
 If this checkout's `package.json` is ahead of the published version, publish the new package before updating consumers to that version.
@@ -34,8 +34,12 @@ If this checkout's `package.json` is ahead of the published version, publish the
 - `applyRecordTimeLabelOperation(state, operation)`
 - `createRecordTimeLabelSyncEngine({ storage, cloud, session, client, clock, logger })`
 - `RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES`
-- `normalizeRecordTimeLabelOperationResults(operations, results)`
-- `normalizeRecordTimeLabelEnvelopeResponse(operations, response)`
+- `RECORD_TIMELABEL_PROTOCOL_CAPABILITIES`
+- `toRecordTimeLabelWireOperation(operation)`
+- `buildRecordTimeLabelRequestId(namespace, operations)`
+- `createRecordTimeLabelTransportFailureResults(operations, failure, options)`
+- `normalizeRecordTimeLabelOperationResults(operations, results, options)`
+- `normalizeRecordTimeLabelEnvelopeResponse(operations, response, options)`
 - `createSyncEngine({ storageAdapter, cloudAdapter, clientId, clock, logger })`
 - `createRecordTimeLabelController({ storageAdapter, cloudAdapter, clientId, settingKeys, clock, logger })`
 - `buildRecordTimeLabelSyncPayload({ data, previousCloudData, pendingOps, syncMode, clientId, now, groupOrderNormalizer })`
@@ -53,7 +57,7 @@ If this checkout's `package.json` is ahead of the published version, publish the
 - `buildFirestoreV2OperationReadPlan(operations)`
 - `extendFirestoreV2OperationReadPlanWithRecords(readPlan, records)`
 - `extendFirestoreV2OperationReadPlanWithTrash(readPlan, trashEntries)`
-- `planFirestoreV2OperationChanges({ documents, operations, localState, now })`
+- `planFirestoreV2OperationChanges({ documents, operations, localState, now, requireLifecycleGeneration })`
 - `estimateFirestoreV2WriteUnits(changes, overhead)`
 - `buildOperationsFromSnapshotDiff({ previousState, nextState, now, operationIdPrefix, batchSize })`（一般操作在 `batches`，`folder.delete` 在 `bulkOperations`）
 - `RTL_SYNC_PROTOCOL_VERSION`
@@ -79,7 +83,7 @@ and operation planners, and `/compat` contains the legacy `createSyncEngine` and
 
 `createRecordTimeLabelSyncEngine` is the platform-neutral durable workspace API. Its storage port
 has `load()` and `save(workspace)` methods (adapters may consume the optional second
-`save(workspace, fenceContext)` argument to enforce the session/epoch atomically), and its cloud port has `bootstrap(context)`,
+`save(workspace, fenceContext)` argument to enforce the session/epoch atomically), and its cloud port has `bootstrap(context, attemptOptions)`,
 `applyOperations(envelope, context)`, and `subscribe(listener, context)` methods. The session port
 provides `current()`, `subscribe(listener)`, and `isCurrent(sessionToken, uid, workspaceEpoch)`.
 
@@ -105,8 +109,20 @@ explicit identity does not match the current workspace is moved to
 
 Pending operations also carry an internal `syncBatchId`. Operations dispatched in
 one call share a batch boundary, while legacy pending operations are assigned one
-stable boundary during migration. Adapters may use this field to preserve immutable
-request envelopes across worker restarts; it must not be sent to the gateway.
+stable boundary during migration. The engine sends only the first FIFO batch boundary,
+capped at 20 operations, and derives a stable request ID from that boundary and the
+ordered canonical wire operations. Durable retry metadata does not affect request identity,
+while reusing an operation ID with different wire content is quarantined. A bounded history
+of completed operation fingerprints is kept in `syncMeta`; `syncBatchId`, identity fences,
+and retry scheduling fields stay outside canonical wire operations.
+
+Bootstrap attempts use `initial-hydration`, `rejection-rebase`, or `gap-recovery`
+modes with a unique `attemptId`; all require a fresh logical attempt. Structured
+failures, missing state, and missing/invalid revisions fail closed. UID or workspace
+epoch changes clear the visible workspace and require `init()` before another dispatch
+or sync; token refresh for the same UID/epoch only refreshes the subscription fence. An
+operation acknowledgement records its revision diagnostically but advances
+`remoteBaseline.revision` only with a complete state; revision gaps trigger a fresh bootstrap.
 
 The engine exposes `init()`, `dispatch(operations)`, `sync(reason)`, `getSnapshot()`,
 `subscribe(listener)`, and `destroy()`. `getSnapshot().state` is derived by replaying pending
@@ -123,21 +139,26 @@ so older clients can continue reading the view until they migrate.
 ### Operation-result protocol
 
 The root package and `@recordtimelabel/core/protocol` export the shared acknowledgement
-normalizers. `normalizeRecordTimeLabelOperationResults(operations, results)` always returns one
-positional result per submitted operation. The only normalized statuses are `applied`, `noop`,
+normalizers. `normalizeRecordTimeLabelOperationResults(operations, results)` verifies count,
+request membership, unique IDs, and completeness before returning results in request order.
+The only normalized statuses are `applied`, `noop`,
 `rejected`, and `retryable`; `retryable` is derived from that status, while the legacy `id` and
 `applied` fields remain available alongside `operationId`, `reason`, and `retryAfterMs`.
 
-`normalizeRecordTimeLabelEnvelopeResponse(operations, response)` prefers an explicit
-`operationResults` array. An explicitly provided non-array or mismatched array, and a failed
-envelope without results, throw an error whose `code` is `operation_result_count_mismatch`, so
-callers can reject the entire acknowledgement before changing durable state.
-
-During the compatibility window, a successful legacy envelope that omits the
-`operationResults` property acknowledges every submitted operation as `applied`. Failed envelopes
-and envelopes that explicitly provide a malformed result value never receive that fallback. Keep
-the fallback until all deployed gateways and clients send and consume the explicit array; removing
-it requires a coordinated breaking release.
+`normalizeRecordTimeLabelEnvelopeResponse(operations, response)` requires an explicit
+`operationResults` array by default. Malformed, duplicate, missing, unknown, or ambiguous IDs
+throw stable protocol errors so callers can reject the entire acknowledgement before changing
+durable state.
+
+Gateway-only compatibility code may opt into successful legacy envelopes with
+`{allowLegacySuccessWithoutResults: true}`. New durable clients never enable that fallback.
+Capabilities `operation-conflict-quarantine`, `strict-operation-results`, and
+`lifecycle-generation-fence` gate the corresponding 0.4.4 behavior. Single
+`record.restore`, `folder.restore`, and `trash.purge` operations require a positive
+`expectedGeneration`; batch lifecycle operations retain their existing contract. The gateway
+validator derives enforcement from `client.capabilities`. The planner is strict by default;
+the time-limited legacy gateway path must explicitly pass `requireLifecycleGeneration: false`
+for clients that did not declare the capability. A supplied but stale generation is always rejected.
 
 ## Firestore v1 Compatibility
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recordtimelabel/core",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "type": "module",
   "description": "Shared RecordTimeLabel data model, merge logic, operations, and sync engine.",
   "main": "./src/index.js",

package/src/firestore-v2.js

@@ -4,8 +4,12 @@
 export {
   FIRESTORE_V2_SETTINGS_DOC_ID,
   OPERATION_TYPES,
+  RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE,
+  RECORD_TIMELABEL_CAPABILITY_OPERATION_CONFLICT_QUARANTINE,
+  RECORD_TIMELABEL_CAPABILITY_STRICT_OPERATION_RESULTS,
   RECORD_TIMELABEL_CLOUD_SCHEMAS,
   RECORD_TIMELABEL_OPERATION_RESULT_STATUSES,
+  RECORD_TIMELABEL_PROTOCOL_CAPABILITIES,
   RTL_MAX_OPERATIONS_PER_REQUEST,
   RTL_MAX_REQUEST_BYTES,
   RTL_MAX_TARGET_WRITES,
@@ -14,14 +18,17 @@ export {
   buildFirestoreV2DocumentsFromState,
   buildFirestoreV2LogicalPaths,
   buildFirestoreV2OperationReadPlan,
+  buildRecordTimeLabelRequestId,
   buildOperationsFromSnapshotDiff,
   buildStateFromFirestoreV2Documents,
   estimateFirestoreV2WriteUnits,
+  createRecordTimeLabelTransportFailureResults,
   extendFirestoreV2OperationReadPlanWithRecords,
   extendFirestoreV2OperationReadPlanWithTrash,
   normalizeRecordTimeLabelEnvelopeResponse,
   normalizeRecordTimeLabelOperationResults,
   planFirestoreV2OperationChanges,
+  toRecordTimeLabelWireOperation,
   normalizeRecordTimeLabelDomainState,
   validateRecordTimeLabelOperationBatch
 } from './index.js';

package/src/index.js

@@ -1,13 +1,27 @@
 import {
+  RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE,
+  RECORD_TIMELABEL_CAPABILITY_OPERATION_CONFLICT_QUARANTINE,
+  RECORD_TIMELABEL_CAPABILITY_STRICT_OPERATION_RESULTS,
   RECORD_TIMELABEL_OPERATION_RESULT_STATUSES,
+  RECORD_TIMELABEL_PROTOCOL_CAPABILITIES,
+  buildRecordTimeLabelRequestId,
+  createRecordTimeLabelTransportFailureResults,
   normalizeRecordTimeLabelEnvelopeResponse,
-  normalizeRecordTimeLabelOperationResults
+  normalizeRecordTimeLabelOperationResults,
+  toRecordTimeLabelWireOperation
 } from './protocol.js';
 
 export {
+  RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE,
+  RECORD_TIMELABEL_CAPABILITY_OPERATION_CONFLICT_QUARANTINE,
+  RECORD_TIMELABEL_CAPABILITY_STRICT_OPERATION_RESULTS,
   RECORD_TIMELABEL_OPERATION_RESULT_STATUSES,
+  RECORD_TIMELABEL_PROTOCOL_CAPABILITIES,
+  buildRecordTimeLabelRequestId,
+  createRecordTimeLabelTransportFailureResults,
   normalizeRecordTimeLabelEnvelopeResponse,
-  normalizeRecordTimeLabelOperationResults
+  normalizeRecordTimeLabelOperationResults,
+  toRecordTimeLabelWireOperation
 } from './protocol.js';
 
 const DEFAULT_FOLDER_ID = 'uncategorized';
@@ -17,12 +31,15 @@ const REQUIRED_FOLDERS = [
   { id: DEFAULT_FOLDER_ID, name: 'Uncategorized' }
 ];
 
-export const RECORD_TIMELABEL_CORE_VERSION = '0.4.2';
+export const RECORD_TIMELABEL_CORE_VERSION = '0.4.4';
 export const RTL_SYNC_PROTOCOL_VERSION = 2;
 export const RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES = Object.freeze([
   'fifo-retry-fence',
   'baseline-refresh-after-rejection',
-  'sync-batch-boundary'
+  'sync-batch-boundary',
+  RECORD_TIMELABEL_CAPABILITY_OPERATION_CONFLICT_QUARANTINE,
+  RECORD_TIMELABEL_CAPABILITY_STRICT_OPERATION_RESULTS,
+  RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE
 ]);
 export const RTL_MAX_OPERATIONS_PER_REQUEST = 20;
 export const RTL_MAX_REQUEST_BYTES = 256 * 1024;
@@ -57,6 +74,11 @@ const ORDER_OPERATION_TYPES = new Set([
   OPERATION_TYPES.EXPANDED_GROUPS_UPDATE
 ]);
 
+const normalizeExpectedGeneration = (value) => {
+  const generation = Number(value);
+  return Number.isSafeInteger(generation) && generation > 0 ? generation : null;
+};
+
 export const RECORD_TIMELABEL_SYNC_MODES = Object.freeze({
   FULL: 'full',
   MERGE: 'merge'
@@ -71,7 +93,10 @@ export const FIRESTORE_V2_SETTINGS_DOC_ID = 'main';
 
 export const RECORD_TIMELABEL_OPERATION_IDENTITY_REASONS = Object.freeze({
   OWNER_MISMATCH: 'operation_owner_mismatch',
-  WORKSPACE_EPOCH_MISMATCH: 'operation_workspace_epoch_mismatch'
+  WORKSPACE_EPOCH_MISMATCH: 'operation_workspace_epoch_mismatch',
+  ID_CONFLICT: 'operation_id_conflict',
+  LIFECYCLE_GENERATION_REQUIRED: 'lifecycle_generation_required',
+  LIFECYCLE_CONFLICT: 'lifecycle_conflict'
 });
 
 const toArray = (value) => (Array.isArray(value) ? value : []);
@@ -951,8 +976,9 @@ export const applyOperation = (state = {}, operation = {}) => {
       const trashEntry = nextState.trashEntries[trashEntryId];
       if (!trashEntry || trashEntry.kind !== 'record') return normalized;
       if (toFiniteTimestamp(trashEntry.purgeAt) <= operationTime) return normalized;
-      if (payload.expectedGeneration &&
-        Number(payload.expectedGeneration) !== Number(trashEntry.lifecycleGeneration)) return normalized;
+      const expectedGeneration = normalizeExpectedGeneration(payload.expectedGeneration);
+      if (expectedGeneration === null ||
+        expectedGeneration !== Number(trashEntry.lifecycleGeneration)) return normalized;
       const recordId = normalizeId(trashEntry.entityId);
       if (!recordId || findRecordEntry(nextState.records, recordId)) return normalized;
       const recordSnapshot = trashEntry.payload?.record;
@@ -1080,8 +1106,9 @@ export const applyOperation = (state = {}, operation = {}) => {
       const trashEntry = nextState.trashEntries[trashEntryId];
       if (!trashEntry || trashEntry.kind !== 'folder') return normalized;
       if (toFiniteTimestamp(trashEntry.purgeAt) <= operationTime) return normalized;
-      if (payload.expectedGeneration &&
-        Number(payload.expectedGeneration) !== Number(trashEntry.lifecycleGeneration)) return normalized;
+      const expectedGeneration = normalizeExpectedGeneration(payload.expectedGeneration);
+      if (expectedGeneration === null ||
+        expectedGeneration !== Number(trashEntry.lifecycleGeneration)) return normalized;
       const folderId = normalizeId(trashEntry.entityId);
       if (!folderId || nextState.folders.some((folder) => folder.id === folderId)) return normalized;
       const folderSnapshot = trashEntry.payload?.folder;
@@ -1126,8 +1153,9 @@ export const applyOperation = (state = {}, operation = {}) => {
       const trashEntryId = normalizeId(payload.trashEntryId || payload.id);
       const trashEntry = nextState.trashEntries[trashEntryId];
       if (!trashEntry) return normalized;
-      if (payload.expectedGeneration &&
-        Number(payload.expectedGeneration) !== Number(trashEntry.lifecycleGeneration)) return normalized;
+      const expectedGeneration = normalizeExpectedGeneration(payload.expectedGeneration);
+      if (expectedGeneration === null ||
+        expectedGeneration !== Number(trashEntry.lifecycleGeneration)) return normalized;
       delete nextState.trashEntries[trashEntryId];
       break;
     }
@@ -2620,6 +2648,7 @@ export const createRecordTimeLabelController = ({
 const RTL_DURABLE_SCHEMA_VERSION = 1;
 const RTL_RETRY_BASE_MS = 1000;
 const RTL_RETRY_MAX_MS = 60 * 1000;
+const RTL_COMPLETED_OPERATION_FINGERPRINT_LIMIT = 512;
 
 const rtlDurableIsObject = (value) => Boolean(value && typeof value === 'object' && !Array.isArray(value));
 
@@ -2735,13 +2764,10 @@ const rtlNormalizePendingOperation = (operation, options = {}) => {
 };
 
 const rtlStableSyncBatchId = (operations = []) => {
-  const source = toArray(operations).map((operation) => normalizeId(operation?.id)).join('|');
-  let hash = 2166136261;
-  for (let index = 0; index < source.length; index += 1) {
-    hash ^= source.charCodeAt(index);
-    hash = Math.imul(hash, 16777619);
-  }
-  return `durable-batch:${(hash >>> 0).toString(16).padStart(8, '0')}`;
+  return buildRecordTimeLabelRequestId(
+    'durable-batch',
+    toArray(operations).map((operation) => toRecordTimeLabelWireOperation(operation))
+  );
 };
 
 const rtlNormalizeRemoteBaseline = (value = {}) => {
@@ -2841,23 +2867,115 @@ const rtlOperationIdentityReason = (operation, workspace) => {
   if (operationEpoch !== workspaceEpoch) {
     return RECORD_TIMELABEL_OPERATION_IDENTITY_REASONS.WORKSPACE_EPOCH_MISMATCH;
   }
+  if ([
+    OPERATION_TYPES.RECORD_RESTORE,
+    OPERATION_TYPES.FOLDER_RESTORE,
+    OPERATION_TYPES.TRASH_PURGE
+  ].includes(operation?.type) && normalizeExpectedGeneration(operation?.payload?.expectedGeneration) === null) {
+    return RECORD_TIMELABEL_OPERATION_IDENTITY_REASONS.LIFECYCLE_GENERATION_REQUIRED;
+  }
+  return null;
+};
+
+const rtlOperationWireFingerprint = (operation) => JSON.stringify(
+  canonicalizeFirestoreV2DocumentValue(toRecordTimeLabelWireOperation(operation))
+);
+
+const rtlCompletedOperationFingerprint = (value) => (
+  typeof value === 'string' ? value : value?.fingerprint
+);
+
+const rtlRememberCompletedOperations = (workspace, completedOperations, timestamp) => {
+  const existing = rtlDurableIsObject(workspace?.syncMeta?.completedOperationFingerprints)
+    ? workspace.syncMeta.completedOperationFingerprints
+    : {};
+  const history = {...existing};
+  toArray(completedOperations).forEach(({operation, status}) => {
+    const id = normalizeId(operation?.id);
+    if (!id) return;
+    delete history[id];
+    history[id] = {
+      fingerprint: rtlOperationWireFingerprint(operation),
+      completedAt: timestamp,
+      status
+    };
+  });
+  const boundedHistory = Object.fromEntries(
+    Object.entries(history).slice(-RTL_COMPLETED_OPERATION_FINGERPRINT_LIMIT)
+  );
+  workspace.syncMeta = {
+    ...(workspace.syncMeta || {}),
+    completedOperationFingerprints: boundedHistory
+  };
+};
+
+const rtlLifecycleOperationReason = (operation, state) => {
+  if (![
+    OPERATION_TYPES.RECORD_RESTORE,
+    OPERATION_TYPES.FOLDER_RESTORE,
+    OPERATION_TYPES.TRASH_PURGE
+  ].includes(operation?.type)) return null;
+  const expectedGeneration = normalizeExpectedGeneration(operation?.payload?.expectedGeneration);
+  if (expectedGeneration === null) {
+    return RECORD_TIMELABEL_OPERATION_IDENTITY_REASONS.LIFECYCLE_GENERATION_REQUIRED;
+  }
+  const trashEntryId = normalizeId(operation?.payload?.trashEntryId || operation?.payload?.id);
+  const trashEntry = state?.trashEntries?.[trashEntryId];
+  if (trashEntry && Number(trashEntry.lifecycleGeneration) !== expectedGeneration) {
+    return RECORD_TIMELABEL_OPERATION_IDENTITY_REASONS.LIFECYCLE_CONFLICT;
+  }
   return null;
 };
 
 const rtlQuarantineOperations = (workspace, operations, timestamp = Date.now()) => {
   const accepted = [];
   const rejected = {...(workspace?.rejectedOperations || {})};
+  const knownById = new Map();
+  Object.entries(workspace?.syncMeta?.completedOperationFingerprints || {}).forEach(([rawId, value]) => {
+    const id = normalizeId(rawId);
+    const fingerprint = rtlCompletedOperationFingerprint(value);
+    if (id && typeof fingerprint === 'string' && !knownById.has(id)) {
+      knownById.set(id, fingerprint);
+    }
+  });
+  Object.values(workspace?.rejectedOperations || {}).forEach((entry) => {
+    const id = normalizeId(entry?.operation?.id || entry?.id);
+    if (id && entry?.operation && !knownById.has(id)) {
+      knownById.set(id, rtlOperationWireFingerprint(entry.operation));
+    }
+  });
+  let lifecycleState = operations === workspace?.pendingOperations
+    ? normalizeRecordTimeLabelDomainState(workspace?.remoteBaseline?.state || {})
+    : rtlDeriveDurableVisibleState(workspace);
+  if (operations !== workspace?.pendingOperations) {
+    toArray(workspace?.pendingOperations).forEach((operation) => {
+      const id = normalizeId(operation?.id);
+      if (id && !knownById.has(id)) knownById.set(id, rtlOperationWireFingerprint(operation));
+    });
+  }
   let rejectedCount = 0;
   toArray(operations).forEach((operation, index) => {
-    const reason = rtlOperationIdentityReason(operation, workspace);
+    const id = normalizeId(operation?.id);
+    const fingerprint = rtlOperationWireFingerprint(operation);
+    const knownFingerprint = id ? knownById.get(id) : null;
+    let reason = rtlOperationIdentityReason(operation, workspace);
+    if (!reason) reason = rtlLifecycleOperationReason(operation, lifecycleState);
+    if (!reason && knownFingerprint) {
+      if (knownFingerprint === fingerprint) return;
+      reason = RECORD_TIMELABEL_OPERATION_IDENTITY_REASONS.ID_CONFLICT;
+    }
     if (!reason) {
       accepted.push(operation);
+      if (id) knownById.set(id, fingerprint);
+      lifecycleState = operation?.type === OPERATION_TYPES.EXPANDED_GROUPS_UPDATE
+        ? lifecycleState
+        : normalizeRecordTimeLabelDomainState(applyRecordTimeLabelOperation(lifecycleState, operation));
       return;
     }
     rejectedCount += 1;
-    const id = normalizeId(operation?.id) || `identity-rejected:${timestamp}:${index}`;
-    rejected[id] = {
-      id,
+    const rejectedId = id || `identity-rejected:${timestamp}:${index}`;
+    rejected[rejectedId] = {
+      id: rejectedId,
       operation: clone(operation),
       status: 'rejected',
       reason,
@@ -3024,10 +3142,12 @@ export const createRecordTimeLabelSyncEngine = ({
 
   let workspace = rtlEmptyDurableWorkspace();
   let initialized = false;
+  let hydrationRequired = true;
   let destroyed = false;
   let unsubscribeCloud = null;
   let unsubscribeSession = null;
   let subscriptionContext = null;
+  let bootstrapAttemptSequence = 0;
   const listeners = new Set();
   let queue = Promise.resolve();
 
@@ -3120,6 +3240,43 @@ export const createRecordTimeLabelSyncEngine = ({
     return {changed, stale: false};
   };
 
+  const bootstrapAttemptOptions = (mode) => ({
+    mode,
+    attemptId: `bootstrap:${mode}:${now()}:${++bootstrapAttemptSequence}:${
+      globalThis.crypto?.randomUUID?.() || Math.random().toString(36).slice(2, 14)
+    }`,
+    requireFresh: true
+  });
+
+  const normalizeBootstrapResponse = (response) => {
+    if (!rtlEnvelopeSuccess(response)) {
+      const error = new Error(response?.error?.message || response?.message || 'recordtimelabel_bootstrap_failed');
+      error.code = response?.error?.code || response?.code || 'recordtimelabel_bootstrap_failed';
+      throw error;
+    }
+    const remote = rtlEnvelopePayload(response);
+    const revision = Number(remote?.revision);
+    const state = remote?.state ?? remote?.data;
+    if (!remote || !rtlDurableIsObject(state) || !Number.isFinite(revision) || revision < 0) {
+      const error = new Error('recordtimelabel_invalid_bootstrap_response');
+      error.code = 'recordtimelabel_invalid_bootstrap_response';
+      throw error;
+    }
+    return {state, revision, changeCursor: remote.changeCursor ?? null};
+  };
+
+  const requireBootstrapRevision = (baseline, minimumRevision) => {
+    const minimum = Number(minimumRevision);
+    if (Number.isFinite(minimum) && Number(baseline?.revision) < minimum) {
+      const error = new Error('recordtimelabel_bootstrap_revision_behind_required');
+      error.code = 'recordtimelabel_bootstrap_revision_behind_required';
+      error.bootstrapRevision = Number(baseline?.revision);
+      error.minimumRevision = minimum;
+      throw error;
+    }
+    return baseline;
+  };
+
   const normalizeLoadedWorkspace = (loaded, captured) => {
     const source = loaded && typeof loaded === 'object' ? loaded : {};
     const hasDurableShape = source.remoteBaseline || source.pendingOperations || source.schemaVersion === RTL_DURABLE_SCHEMA_VERSION;
@@ -3196,6 +3353,10 @@ export const createRecordTimeLabelSyncEngine = ({
           );
         });
       });
+      const migrationBatchId = rtlStableSyncBatchId(migratedOperations);
+      migratedOperations.forEach((operation) => {
+        if (!operation.syncBatchId) operation.syncBatchId = migrationBatchId;
+      });
       loadedWorkspace.remoteBaseline = rtlNormalizeRemoteBaseline({});
       loadedWorkspace.pendingOperations = [
         ...migratedOperations,
@@ -3257,43 +3418,11 @@ export const createRecordTimeLabelSyncEngine = ({
   const normalizeOperationResults = (response, sentOperations) => {
     let results;
     try {
-      // Keep the Plan 017 engine's private input aliases compatible while the
-      // public shared contract remains strict about operationResults arrays.
-      const legacyOperationResults = response?.operationResults;
-      const compatibleResponse = rtlDurableIsObject(legacyOperationResults)
-        ? {
-          ...response,
-          operationResults: Object.entries(legacyOperationResults).map(([id, result]) => ({
-            ...(result || {}),
-            id: result?.id || id
-          }))
-        }
-        : (
-          !Object.prototype.hasOwnProperty.call(response || {}, 'operationResults') &&
-          Array.isArray(response?.results)
-            ? {...response, operationResults: response.results}
-            : response
-        );
-      results = normalizeRecordTimeLabelEnvelopeResponse(sentOperations, compatibleResponse);
+      results = normalizeRecordTimeLabelEnvelopeResponse(sentOperations, response);
     } catch (error) {
       return {error, results: null};
     }
-    const byId = new Map(sentOperations.map((operation) => [operation.id, operation]));
-    const normalized = [];
-    const seen = new Set();
-    for (let index = 0; index < results.length; index += 1) {
-      const result = results[index] || {};
-      const resultId = rtlResultOperationId(result) || sentOperations[index]?.id;
-      if (!resultId || !byId.has(resultId) || seen.has(resultId)) {
-        return {error: new Error('sync_protocol_invalid_operation_result'), results: null};
-      }
-      seen.add(resultId);
-      normalized.push({...clone(result), id: resultId});
-    }
-    if (seen.size !== sentOperations.length) {
-      return {error: new Error('sync_protocol_operation_result_count_mismatch'), results: null};
-    }
-    return {results: normalized};
+    return {results: results.map((result) => ({...clone(result), id: rtlResultOperationId(result)}))};
   };
 
   const operationRetryAt = (operation, result, retryAfterMs, timestamp) => {
@@ -3317,7 +3446,30 @@ export const createRecordTimeLabelSyncEngine = ({
   const processRemote = async (remoteValue, captured) => {
     if (!(await isCurrent(captured))) return {stale: true, reason: 'stale_session'};
     const candidate = clone(workspace);
-    const applied = applyRemoteBaseline(candidate, remoteValue);
+    const remote = rtlEnvelopePayload(remoteValue);
+    const remoteRevision = Number(remote?.revision);
+    if (!Number.isFinite(remoteRevision)) {
+      return {success: false, protocolError: true, reason: 'invalid_remote_revision'};
+    }
+    if (remoteRevision <= candidate.remoteBaseline.revision) {
+      return {success: true, ignored: true};
+    }
+    let baselineValue = remoteValue;
+    if (remoteRevision > candidate.remoteBaseline.revision + 1) {
+      if (typeof cloud?.bootstrap !== 'function') {
+        return {success: false, reason: 'revision_gap', bootstrapRequired: true};
+      }
+      const context = rtlSessionContext(captured, candidate, client);
+      baselineValue = requireBootstrapRevision(
+        normalizeBootstrapResponse(await cloud.bootstrap(
+          context,
+          bootstrapAttemptOptions('gap-recovery')
+        )),
+        remoteRevision
+      );
+      if (!(await isCurrent(captured))) return {stale: true, reason: 'stale_session'};
+    }
+    const applied = applyRemoteBaseline(candidate, baselineValue);
     if (applied.stale || !applied.changed) return {success: true, ignored: true};
     if (!(await persist(candidate, captured))) return {stale: true, reason: 'stale_session'};
     workspace = candidate;
@@ -3325,6 +3477,30 @@ export const createRecordTimeLabelSyncEngine = ({
     return getSnapshot();
   };
 
+  const stopCloudSubscription = () => {
+    if (typeof unsubscribeCloud === 'function') {
+      try { unsubscribeCloud(); } catch (error) {
+        logger?.error?.('[RecordTimeLabelCore] durable unsubscribe failed', error);
+      }
+    }
+    unsubscribeCloud = null;
+    subscriptionContext = null;
+  };
+
+  const startCloudSubscription = (captured, candidate) => {
+    stopCloudSubscription();
+    if (typeof cloud?.subscribe !== 'function' || !initialized || hydrationRequired) return;
+    const context = rtlSessionContext(captured, candidate, client);
+    subscriptionContext = context;
+    unsubscribeCloud = cloud.subscribe((remoteValue) => {
+      if (destroyed) return;
+      return enqueue(() => processRemote(remoteValue, captured)).catch((error) => {
+        logger?.error?.('[RecordTimeLabelCore] durable remote callback failed', error);
+        return {success: false, error};
+      });
+    }, context);
+  };
+
   const initialize = async () => {
     const captured = capture();
     const loaded = await storage.load();
@@ -3342,7 +3518,10 @@ export const createRecordTimeLabelSyncEngine = ({
     if (captured?.uid && typeof cloud?.bootstrap === 'function') {
       let bootstrap;
       try {
-        bootstrap = await cloud.bootstrap(context);
+        bootstrap = normalizeBootstrapResponse(await cloud.bootstrap(
+          context,
+          bootstrapAttemptOptions('initial-hydration')
+        ));
       } catch (error) {
         if (!(await isCurrent(captured))) return getSnapshot();
         throw error;
@@ -3356,25 +3535,41 @@ export const createRecordTimeLabelSyncEngine = ({
     if (!(await persist(candidate, captured))) return getSnapshot();
     workspace = candidate;
     initialized = true;
-
-    if (typeof cloud?.subscribe === 'function') {
-      subscriptionContext = context;
-      unsubscribeCloud = cloud.subscribe((remoteValue) => {
+    hydrationRequired = false;
+    startCloudSubscription(captured, candidate);
+    if (typeof session?.subscribe === 'function' && !unsubscribeSession) {
+      unsubscribeSession = session.subscribe(() => {
         if (destroyed) return;
-        return enqueue(() => processRemote(remoteValue, captured)).catch((error) => {
-          logger?.error?.('[RecordTimeLabelCore] durable remote callback failed', error);
-          return {success: false, error};
+        enqueue(async () => {
+          const current = capture();
+          const sameIdentity = current.uid === workspace.ownerUid &&
+            Number(current.workspaceEpoch) === Number(workspace.workspaceEpoch);
+          if (sameIdentity) {
+            startCloudSubscription(current, workspace);
+            return {success: true, tokenRefreshed: true};
+          }
+          stopCloudSubscription();
+          workspace = rtlEmptyDurableWorkspace({
+            ownerUid: current.uid,
+            workspaceEpoch: current.workspaceEpoch
+          });
+          initialized = false;
+          hydrationRequired = true;
+          notify({type: 'session_changed'});
+          return {success: true, sessionChanged: true};
+        }).catch((error) => {
+          logger?.error?.('[RecordTimeLabelCore] durable session callback failed', error);
         });
-      }, context);
-    }
-    if (typeof session?.subscribe === 'function' && !unsubscribeSession) {
-      unsubscribeSession = session.subscribe(() => {});
+      });
     }
     notify({type: 'initialized'});
     return getSnapshot();
   };
 
   const dispatchInternal = async (operations) => {
+    if (!initialized || hydrationRequired) {
+      return {success: false, code: 'recordtimelabel_hydration_required'};
+    }
     const captured = capture();
     if (!(await isCurrent(captured))) return getSnapshot();
     const input = Array.isArray(operations)
@@ -3447,6 +3642,9 @@ export const createRecordTimeLabelSyncEngine = ({
   };
 
   const syncInternal = async (reason) => {
+    if (!initialized || hydrationRequired) {
+      return {success: false, code: 'recordtimelabel_hydration_required'};
+    }
     const captured = capture();
     if (!(await isCurrent(captured))) return {success: false, reason: 'stale_session'};
     const timestamp = now();
@@ -3473,7 +3671,10 @@ export const createRecordTimeLabelSyncEngine = ({
     // is a head-of-line barrier; dependent operations behind it must not
     // overtake it merely because they do not have their own deadline yet.
     const ready = [];
+    const firstBatchId = workspace.pendingOperations[0]?.syncBatchId || null;
     for (const operation of workspace.pendingOperations) {
+      if (ready.length >= RTL_MAX_OPERATIONS_PER_REQUEST) break;
+      if (ready.length > 0 && operation.syncBatchId !== firstBatchId) break;
       if (Number.isFinite(Number(operation.nextRetryAt)) &&
           Number(operation.nextRetryAt) > timestamp) break;
       ready.push(operation);
@@ -3500,15 +3701,22 @@ export const createRecordTimeLabelSyncEngine = ({
       return {success: false, reason: 'missing_cloud_apply_operations'};
     }
     const context = rtlSessionContext(captured, workspace, client);
+    const wireOperations = ready.map((operation) => toRecordTimeLabelWireOperation(operation));
+    const requestId = buildRecordTimeLabelRequestId(
+      `${typeof client === 'string' ? client : client?.app || client?.id || 'client'}:${firstBatchId || 'batch'}`,
+      wireOperations
+    );
     let response;
     try {
       response = await cloud.applyOperations({
         schemaVersion: RTL_DURABLE_SCHEMA_VERSION,
+        requestId,
+        syncBatchId: firstBatchId,
         ownerUid: workspace.ownerUid,
         workspaceEpoch: workspace.workspaceEpoch,
         client: clone(client),
         reason: reason ?? null,
-        operations: clone(ready)
+        operations: clone(wireOperations)
       }, context);
     } catch (error) {
       if (!(await isCurrent(captured))) return {success: false, reason: 'stale_session'};
@@ -3561,15 +3769,28 @@ export const createRecordTimeLabelSyncEngine = ({
       };
     }
 
-    const parsed = normalizeOperationResults(response, ready);
+    const parsed = normalizeOperationResults(response, wireOperations);
     if (parsed.error) {
       logger?.error?.('[RecordTimeLabelCore] durable sync protocol error', parsed.error);
       return {success: false, error: parsed.error, protocolError: true};
     }
+    let sawRetryable = false;
+    for (const result of parsed.results) {
+      if (result.status === 'retryable') {
+        sawRetryable = true;
+      } else if (sawRetryable && (result.status === 'applied' || result.status === 'noop')) {
+        const error = new Error('sync_protocol_fifo_retry_barrier_violation');
+        error.code = 'sync_protocol_fifo_retry_barrier_violation';
+        logger?.error?.('[RecordTimeLabelCore] durable sync protocol error', error);
+        return {success: false, error, protocolError: true};
+      }
+    }
+    const rejectedCount = parsed.results.filter((result) => result.status === 'rejected').length;
     const candidate = clone(workspace);
     const resultById = new Map(parsed.results.map((result) => [result.id, result]));
     const readyIds = new Set(ready.map((operation) => operation.id));
     const appliedOperations = [];
+    const completedOperations = [];
     const nextPending = [];
     const nextRejected = {...candidate.rejectedOperations};
     for (const operation of candidate.pendingOperations) {
@@ -3580,12 +3801,15 @@ export const createRecordTimeLabelSyncEngine = ({
       const result = resultById.get(operation.id);
       if (result.status === 'applied') {
         appliedOperations.push(operation);
+        completedOperations.push({operation, status: result.status});
       } else if (result.status === 'noop') {
         // A noop is acknowledged but intentionally not promoted onto the
         // baseline: the server says the operation had no effect.
+        completedOperations.push({operation, status: result.status});
       } else if (result.status === 'retryable') {
         nextPending.push(makeRetryOperation(operation, result, null, timestamp));
       } else if (result.status === 'rejected') {
+        completedOperations.push({operation, status: result.status});
         nextRejected[operation.id] = {
           id: operation.id,
           operation: clone(operation),
@@ -3602,13 +3826,25 @@ export const createRecordTimeLabelSyncEngine = ({
       );
     });
     const responseRevision = Number(response.revision ?? response.remoteRevision);
-    if (Number.isFinite(responseRevision) && responseRevision >= candidate.remoteBaseline.revision) {
-      candidate.remoteBaseline.revision = responseRevision;
-    }
-    if (Object.prototype.hasOwnProperty.call(response || {}, 'changeCursor')) {
-      candidate.remoteBaseline.changeCursor = response.changeCursor === null || response.changeCursor === undefined
-        ? null
-        : String(response.changeCursor);
+    const responseBaseline = rtlEnvelopePayload(response);
+    const responseState = responseBaseline?.state ?? responseBaseline?.data;
+    if (rtlDurableIsObject(responseState)) {
+      applyRemoteBaseline(candidate, responseBaseline);
+    } else if (
+      rejectedCount === 0 &&
+      Number.isFinite(responseRevision) &&
+      responseRevision > candidate.remoteBaseline.revision + 1 &&
+      typeof cloud?.bootstrap === 'function'
+    ) {
+      const freshBaseline = requireBootstrapRevision(
+        normalizeBootstrapResponse(await cloud.bootstrap(
+          context,
+          bootstrapAttemptOptions('gap-recovery')
+        )),
+        responseRevision
+      );
+      if (!(await isCurrent(captured))) return {success: false, reason: 'stale_session'};
+      applyRemoteBaseline(candidate, freshBaseline);
     }
     candidate.pendingOperations = nextPending;
     candidate.rejectedOperations = nextRejected;
@@ -3617,13 +3853,26 @@ export const createRecordTimeLabelSyncEngine = ({
       lastSyncedAt: timestamp,
       lastSyncAttemptAt: timestamp,
       lastSyncReason: reason ?? null,
-      lastSyncError: null
+      lastSyncError: null,
+      ...(Number.isFinite(responseRevision) ? {
+        lastAcknowledgedRevision: Math.max(
+          rtlToFiniteNumber(candidate.syncMeta?.lastAcknowledgedRevision, 0),
+          candidate.remoteBaseline.revision,
+          responseRevision
+        )
+      } : {})
     };
-    const rejectedCount = parsed.results.filter((result) => result.status === 'rejected').length;
+    rtlRememberCompletedOperations(candidate, completedOperations, timestamp);
     if (rejectedCount > 0 && typeof cloud?.bootstrap === 'function') {
       let freshBaseline;
       try {
-        freshBaseline = await cloud.bootstrap(context);
+        freshBaseline = requireBootstrapRevision(
+          normalizeBootstrapResponse(await cloud.bootstrap(
+            context,
+            bootstrapAttemptOptions('rejection-rebase')
+          )),
+          responseRevision
+        );
       } catch (error) {
         if (!(await isCurrent(captured))) return {success: false, reason: 'stale_session'};
         throw error;
@@ -3652,7 +3901,7 @@ export const createRecordTimeLabelSyncEngine = ({
   const engine = {
     init() {
       return enqueue(async () => {
-        if (initialized) return getSnapshot();
+        if (initialized && !hydrationRequired) return getSnapshot();
         return initialize();
       });
     },
@@ -3676,15 +3925,12 @@ export const createRecordTimeLabelSyncEngine = ({
     destroy() {
       destroyed = true;
       initialized = false;
-      if (typeof unsubscribeCloud === 'function') {
-        try { unsubscribeCloud(); } catch (error) { logger?.error?.('[RecordTimeLabelCore] durable unsubscribe failed', error); }
-      }
+      hydrationRequired = true;
+      stopCloudSubscription();
       if (typeof unsubscribeSession === 'function') {
         try { unsubscribeSession(); } catch (error) { logger?.error?.('[RecordTimeLabelCore] durable session unsubscribe failed', error); }
       }
-      unsubscribeCloud = null;
       unsubscribeSession = null;
-      subscriptionContext = null;
       listeners.clear();
     }
   };
@@ -3919,7 +4165,7 @@ const rtlValidateIdList = (value, index, field, errors) => {
     errors.push(`operation_${index}_invalid_${field}`);
   }
 };
-const rtlValidateOperationPayload = (operation, index, errors) => {
+const rtlValidateOperationPayload = (operation, index, errors, options = {}) => {
   const payload = operation.payload || {};
   const recordId = rtlOperationRecordId(operation);
   const folderId = rtlOperationFolderId(operation);
@@ -3944,6 +4190,10 @@ const rtlValidateOperationPayload = (operation, index, errors) => {
       break;
     case OPERATION_TYPES.RECORD_RESTORE:
       if (!rtlOperationTrashEntryId(operation)) errors.push(`operation_${index}_missing_trash_entry_id`);
+      if (options.requireLifecycleGeneration === true &&
+        normalizeExpectedGeneration(payload.expectedGeneration) === null) {
+        errors.push(`operation_${index}_invalid_expected_generation`);
+      }
       break;
     case OPERATION_TYPES.RECORD_REORDER:
       if (!folderId) errors.push(`operation_${index}_missing_folder_id`);
@@ -3964,6 +4214,10 @@ const rtlValidateOperationPayload = (operation, index, errors) => {
     case OPERATION_TYPES.FOLDER_RESTORE:
     case OPERATION_TYPES.TRASH_PURGE:
       if (!rtlOperationTrashEntryId(operation)) errors.push(`operation_${index}_missing_trash_entry_id`);
+      if (options.requireLifecycleGeneration === true &&
+        normalizeExpectedGeneration(payload.expectedGeneration) === null) {
+        errors.push(`operation_${index}_invalid_expected_generation`);
+      }
       break;
     case OPERATION_TYPES.TRASH_RESTORE_BATCH:
     case OPERATION_TYPES.TRASH_PURGE_BATCH:
@@ -3999,8 +4253,12 @@ const rtlValidateOperationPayload = (operation, index, errors) => {
 /**
  * Validates one complete v2 gateway request without reading Firebase state.
  */
-export const validateRecordTimeLabelOperationBatch = (body = {}) => {
+export const validateRecordTimeLabelOperationBatch = (body = {}, options = {}) => {
   const errors = [];
+  const requireLifecycleGeneration = options.requireLifecycleGeneration === true ||
+    toArray(body?.client?.capabilities).includes(
+      RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE
+    );
   let requestBytes = 0;
   try {
     requestBytes = rtlByteLength(JSON.stringify(body));
@@ -4047,7 +4305,7 @@ export const validateRecordTimeLabelOperationBatch = (body = {}) => {
       if (rtlHasInvalidPayloadValue(operation.payload) || operationBytes > 128 * 1024) {
         errors.push(`operation_${index}_payload_too_large`);
       }
-      rtlValidateOperationPayload(operation, index, errors);
+      rtlValidateOperationPayload(operation, index, errors, {requireLifecycleGeneration});
     }
     if (!toFiniteTimestamp(operation?.createdAt)) {
       errors.push(`operation_${index}_invalid_created_at`);
@@ -4225,7 +4483,8 @@ export const planFirestoreV2OperationChanges = ({
   documents,
   operations,
   localState = {},
-  now = Date.now()
+  now = Date.now(),
+  requireLifecycleGeneration = true
 } = {}) => {
   const previousDocuments = rtlCloneDocuments(documents);
   const nextDocuments = rtlCloneDocuments(documents);
@@ -4381,6 +4640,15 @@ export const planFirestoreV2OperationChanges = ({
         const trashEntryId = rtlOperationTrashEntryId(operation);
         const trashEntry = nextDocuments.trash[trashEntryId];
         if (!trashEntry) { reason = 'trash_entry_not_found'; break; }
+        const expectedGeneration = normalizeExpectedGeneration(payload.expectedGeneration);
+        if (requireLifecycleGeneration !== false && expectedGeneration === null) {
+          reason = 'lifecycle_generation_required';
+          break;
+        }
+        if (expectedGeneration !== null && expectedGeneration !== Number(trashEntry.lifecycleGeneration)) {
+          reason = 'lifecycle_conflict';
+          break;
+        }
         if (toFiniteTimestamp(trashEntry.purgeAt) <= operationNow) {
           reason = 'trash_entry_expired';
           break;
@@ -4391,7 +4659,16 @@ export const planFirestoreV2OperationChanges = ({
           break;
         }
         lifecycleTombstoneId = rtlLifecycleTombstoneDocumentId('record', restoredRecordId);
-        applied = rtlApplyOperationToPartialDocuments({...nextDocuments, operation, now: operationNow});
+        // Explicit legacy compatibility is planner-local. It does not change the
+        // original operation, its wire bytes, or the strict durable reducer contract.
+        const reducerOperation = requireLifecycleGeneration === false && expectedGeneration === null
+          ? {...operation, payload: {...payload, expectedGeneration: trashEntry.lifecycleGeneration}}
+          : operation;
+        applied = rtlApplyOperationToPartialDocuments({
+          ...nextDocuments,
+          operation: reducerOperation,
+          now: operationNow
+        });
         const restoredRecord = applied.documents.records[restoredRecordId];
         if (!restoredRecord) { reason = 'restore_conflict'; break; }
         const targetFolderId = safeFolderId(restoredRecord.folderId || trashEntry.originalFolderId);
@@ -4415,8 +4692,12 @@ export const planFirestoreV2OperationChanges = ({
         const trashEntryId = rtlOperationTrashEntryId(operation);
         const trashEntry = nextDocuments.trash[trashEntryId];
         if (!trashEntry) { reason = 'trash_entry_not_found'; break; }
-        if (payload.expectedGeneration &&
-          Number(payload.expectedGeneration) !== Number(trashEntry.lifecycleGeneration)) {
+        const expectedGeneration = normalizeExpectedGeneration(payload.expectedGeneration);
+        if (requireLifecycleGeneration !== false && expectedGeneration === null) {
+          reason = 'lifecycle_generation_required';
+          break;
+        }
+        if (expectedGeneration !== null && expectedGeneration !== Number(trashEntry.lifecycleGeneration)) {
           reason = 'lifecycle_conflict';
           break;
         }
@@ -4676,7 +4957,11 @@ export const buildOperationsFromSnapshotDiff = ({
 export default {
   RECORD_TIMELABEL_CORE_VERSION,
   RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES,
+  RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE,
+  RECORD_TIMELABEL_CAPABILITY_OPERATION_CONFLICT_QUARANTINE,
+  RECORD_TIMELABEL_CAPABILITY_STRICT_OPERATION_RESULTS,
   RECORD_TIMELABEL_OPERATION_RESULT_STATUSES,
+  RECORD_TIMELABEL_PROTOCOL_CAPABILITIES,
   RTL_SYNC_PROTOCOL_VERSION,
   RTL_MAX_OPERATIONS_PER_REQUEST,
   RTL_MAX_REQUEST_BYTES,
@@ -4718,6 +5003,9 @@ export default {
   estimateFirestoreV2WriteUnits,
   normalizeRecordTimeLabelOperationResults,
   normalizeRecordTimeLabelEnvelopeResponse,
+  toRecordTimeLabelWireOperation,
+  buildRecordTimeLabelRequestId,
+  createRecordTimeLabelTransportFailureResults,
   buildOperationsFromSnapshotDiff,
   flushPendingOperations,
   mergeRemoteStateIntoLocal,

package/src/protocol.js

@@ -11,6 +11,18 @@ export const RECORD_TIMELABEL_OPERATION_RESULT_STATUSES = Object.freeze({
   RETRYABLE: 'retryable'
 });
 
+export const RECORD_TIMELABEL_CAPABILITY_OPERATION_CONFLICT_QUARANTINE =
+  'operation-conflict-quarantine';
+export const RECORD_TIMELABEL_CAPABILITY_STRICT_OPERATION_RESULTS =
+  'strict-operation-results';
+export const RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE =
+  'lifecycle-generation-fence';
+export const RECORD_TIMELABEL_PROTOCOL_CAPABILITIES = Object.freeze([
+  RECORD_TIMELABEL_CAPABILITY_OPERATION_CONFLICT_QUARANTINE,
+  RECORD_TIMELABEL_CAPABILITY_STRICT_OPERATION_RESULTS,
+  RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE
+]);
+
 const ALLOWED_OPERATION_RESULT_STATUSES = new Set(
   Object.values(RECORD_TIMELABEL_OPERATION_RESULT_STATUSES)
 );
@@ -27,6 +39,84 @@ const asObject = (value) => (
   value && typeof value === 'object' && !Array.isArray(value) ? value : {}
 );
 
+const createProtocolError = (code, details = {}) => {
+  const error = new Error(code);
+  error.code = code;
+  Object.assign(error, details);
+  return error;
+};
+
+const normalizeId = (value) => (
+  typeof value === 'string' || typeof value === 'number' ? String(value).trim() : ''
+);
+
+const fnv1a = (value) => {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, '0');
+};
+
+const djb2 = (value) => {
+  let hash = 5381;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = Math.imul(hash, 33) ^ value.charCodeAt(index);
+  }
+  return (hash >>> 0).toString(16).padStart(8, '0');
+};
+
+const canonicalizeRequestValue = (value, seen = new WeakSet()) => {
+  if (value === null || value === undefined || typeof value !== 'object') return value;
+  if (seen.has(value)) throw new TypeError('operation_request_circular_value');
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return value.map((entry) => canonicalizeRequestValue(entry, seen));
+    }
+    if (typeof value.toJSON === 'function') {
+      return canonicalizeRequestValue(value.toJSON(), seen);
+    }
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .map((key) => [key, canonicalizeRequestValue(value[key], seen)])
+    );
+  } finally {
+    seen.delete(value);
+  }
+};
+
+const requestDigest = (value) => `${fnv1a(value)}${djb2(value)}`;
+
+export const toRecordTimeLabelWireOperation = (operation = {}) => {
+  const source = asObject(operation);
+  return {
+    id: source.id ?? null,
+    type: source.type ?? null,
+    payload: asObject(source.payload),
+    clientId: source.clientId ?? null,
+    createdAt: source.createdAt ?? null
+  };
+};
+
+export const buildRecordTimeLabelRequestId = (namespace, operations = []) => {
+  const safeNamespace = normalizeId(namespace)
+    .replace(/[^A-Za-z0-9._:-]+/g, '-')
+    .slice(0, 48) || 'recordtimelabel';
+  const wireOperations = Array.isArray(operations)
+    ? operations.map((operation) => toRecordTimeLabelWireOperation(operation))
+    : [];
+  const orderedIds = wireOperations.map((operation) => normalizeId(operation.id));
+  const firstOperationId = (orderedIds[0] || 'empty')
+    .replace(/[^A-Za-z0-9._:-]+/g, '-')
+    .slice(0, 56) || 'empty';
+  const orderedIdDigest = requestDigest(orderedIds.join('\u001f'));
+  const wireDigest = requestDigest(JSON.stringify(canonicalizeRequestValue(wireOperations)));
+  return `rtl:${safeNamespace}:${firstOperationId}:${orderedIdDigest}:${wireDigest}`.slice(0, 160);
+};
+
 const normalizeStatus = (result) => {
   if (ALLOWED_OPERATION_RESULT_STATUSES.has(result.status)) {
     return result.status;
@@ -59,24 +149,46 @@ const isSuccessfulEnvelope = (response) => {
  * Unknown result properties are retained for forward compatibility, while
  * all contract fields below are replaced with their normalized values.
  */
-export const normalizeRecordTimeLabelOperationResults = (operations, results) => {
+export const normalizeRecordTimeLabelOperationResults = (operations, results, options = {}) => {
   if (!Array.isArray(operations) || !Array.isArray(results) || operations.length !== results.length) {
     throw createCountMismatchError(operations, results);
   }
+  const strict = options.strict !== false;
+  const operationIds = operations.map((operation) => normalizeId(asObject(operation).id));
+  if (strict && (operationIds.some((id) => !id) || new Set(operationIds).size !== operationIds.length)) {
+    throw createProtocolError('operation_request_invalid_ids');
+  }
 
-  return operations.map((rawOperation, index) => {
-    const operation = asObject(rawOperation);
-    const result = asObject(results[index]);
+  const normalizedById = new Map();
+  const normalized = results.map((rawResult, index) => {
+    const operation = asObject(operations[index]);
+    const result = asObject(rawResult);
     const status = normalizeStatus(result);
-    const operationId = result.operationId ?? result.id ?? operation.id ?? null;
-    const id = result.id ?? operationId;
+    const explicitOperationId = normalizeId(result.operationId);
+    const explicitId = normalizeId(result.id);
+    if (strict && explicitOperationId && explicitId && explicitOperationId !== explicitId) {
+      throw createProtocolError('operation_result_ambiguous_id', {resultIndex: index});
+    }
+    const operationId = explicitOperationId || explicitId || (strict ? '' : normalizeId(operation.id));
+    if (strict && !operationId) {
+      throw createProtocolError('operation_result_missing_id', {resultIndex: index});
+    }
+    if (strict && !operationIds.includes(operationId)) {
+      throw createProtocolError('operation_result_unknown_id', {resultIndex: index, operationId});
+    }
+    if (strict && normalizedById.has(operationId)) {
+      throw createProtocolError('operation_result_duplicate_id', {resultIndex: index, operationId});
+    }
+    const matchedOperation = strict
+      ? asObject(operations[operationIds.indexOf(operationId)])
+      : operation;
+    const id = strict ? operationId : (result.id ?? operationId ?? null);
     const retryAfterMs = result.retryAfterMs;
-
-    return {
+    const value = {
       ...result,
-      operationId,
+      operationId: operationId || null,
       id,
-      type: result.type ?? operation.type ?? null,
+      type: result.type ?? matchedOperation.type ?? null,
       applied: result.applied === true,
       status,
       retryable: status === RECORD_TIMELABEL_OPERATION_RESULT_STATUSES.RETRYABLE,
@@ -85,15 +197,21 @@ export const normalizeRecordTimeLabelOperationResults = (operations, results) =>
         ? retryAfterMs
         : null
     };
+    if (strict) normalizedById.set(operationId, value);
+    return value;
   });
+  if (!strict) return normalized;
+  if (normalizedById.size !== operations.length) {
+    throw createProtocolError('operation_result_incomplete');
+  }
+  return operationIds.map((id) => normalizedById.get(id));
 };
 
 /**
- * Normalize a successful operation envelope. During the compatibility
- * window, a successful legacy envelope with no operationResults property is
- * treated as acknowledging every submitted operation.
+ * Normalize a successful operation envelope. Legacy success without explicit
+ * results is available only when the caller opts into that compatibility path.
  */
-export const normalizeRecordTimeLabelEnvelopeResponse = (operations, response) => {
+export const normalizeRecordTimeLabelEnvelopeResponse = (operations, response, options = {}) => {
   if (!Array.isArray(operations)) {
     throw createCountMismatchError(operations, response?.operationResults);
   }
@@ -104,9 +222,9 @@ export const normalizeRecordTimeLabelEnvelopeResponse = (operations, response) =
     Object.prototype.hasOwnProperty.call(response, 'operationResults')
   );
   if (hasExplicitResults) {
-    return normalizeRecordTimeLabelOperationResults(operations, response.operationResults);
+    return normalizeRecordTimeLabelOperationResults(operations, response.operationResults, options);
   }
-  if (!isSuccessfulEnvelope(response)) {
+  if (!isSuccessfulEnvelope(response) || options.allowLegacySuccessWithoutResults !== true) {
     throw createCountMismatchError(operations, null);
   }
 
@@ -117,12 +235,44 @@ export const normalizeRecordTimeLabelEnvelopeResponse = (operations, response) =
       id: asObject(operation).id ?? null,
       applied: true,
       status: RECORD_TIMELABEL_OPERATION_RESULT_STATUSES.APPLIED
-    }))
+    })),
+    options
   );
 };
 
+export const createRecordTimeLabelTransportFailureResults = (
+  operations,
+  failure,
+  options = {}
+) => {
+  const retryable = options.retryable !== false;
+  const retryAfterMs = Number(options.retryAfterMs ?? failure?.retryAfterMs);
+  const reason = typeof failure === 'string'
+    ? failure
+    : failure?.code || failure?.reason || failure?.message || 'transport_failure';
+  return (Array.isArray(operations) ? operations : []).map((operation) => ({
+    operationId: normalizeId(asObject(operation).id) || null,
+    id: normalizeId(asObject(operation).id) || null,
+    type: asObject(operation).type ?? null,
+    applied: false,
+    status: retryable
+      ? RECORD_TIMELABEL_OPERATION_RESULT_STATUSES.RETRYABLE
+      : RECORD_TIMELABEL_OPERATION_RESULT_STATUSES.REJECTED,
+    retryable,
+    reason,
+    retryAfterMs: Number.isFinite(retryAfterMs) && retryAfterMs > 0 ? retryAfterMs : null
+  }));
+};
+
 export default {
   RECORD_TIMELABEL_OPERATION_RESULT_STATUSES,
+  RECORD_TIMELABEL_CAPABILITY_OPERATION_CONFLICT_QUARANTINE,
+  RECORD_TIMELABEL_CAPABILITY_STRICT_OPERATION_RESULTS,
+  RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE,
+  RECORD_TIMELABEL_PROTOCOL_CAPABILITIES,
+  toRecordTimeLabelWireOperation,
+  buildRecordTimeLabelRequestId,
+  createRecordTimeLabelTransportFailureResults,
   normalizeRecordTimeLabelOperationResults,
   normalizeRecordTimeLabelEnvelopeResponse
 };