@recordtimelabel/core 0.4.3 → 0.4.5

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 strict durable transport contract is prepared in package version `0.4.3` (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.3"
+"@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.
@@ -111,14 +111,18 @@ Pending operations also carry an internal `syncBatchId`. Operations dispatched i
 one call share a batch boundary, while legacy pending operations are assigned one
 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 operation IDs. `syncBatchId`, identity fences, and retry scheduling fields stay
-outside canonical wire operations.
+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.
+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
@@ -149,7 +153,7 @@ 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.3 behavior. Single
+`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;

package/package.json

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

package/src/index.js

@@ -31,7 +31,7 @@ const REQUIRED_FOLDERS = [
   { id: DEFAULT_FOLDER_ID, name: 'Uncategorized' }
 ];
 
-export const RECORD_TIMELABEL_CORE_VERSION = '0.4.3';
+export const RECORD_TIMELABEL_CORE_VERSION = '0.4.5';
 export const RTL_SYNC_PROTOCOL_VERSION = 2;
 export const RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES = Object.freeze([
   'fifo-retry-fence',
@@ -2648,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));
 
@@ -2763,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 = {}) => {
@@ -2883,6 +2881,34 @@ 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,
@@ -2905,6 +2931,19 @@ 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);
@@ -3095,11 +3134,15 @@ export const createRecordTimeLabelSyncEngine = ({
   session,
   client = 'recordtimelabel-client',
   clock = () => Date.now(),
-  logger = console
+  logger = console,
+  initialBaseline = 'require-fresh'
 } = {}) => {
   if (!storage?.load || !storage?.save) {
     throw new Error('createRecordTimeLabelSyncEngine requires storage.load() and storage.save()');
   }
+  if (initialBaseline !== 'require-fresh' && initialBaseline !== 'reuse-committed') {
+    throw new Error('recordtimelabel_invalid_initial_baseline_policy');
+  }
 
   let workspace = rtlEmptyDurableWorkspace();
   let initialized = false;
@@ -3226,6 +3269,49 @@ export const createRecordTimeLabelSyncEngine = ({
     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;
+  };
+
+  // Optional bounded catch-up port. `cloud.catchUp(context, {fromRevision,
+  // targetRevision, attemptId, mode})` resolves a FULL baseline object
+  // (`{success: true, state, revision, changeCursor?}`, the same shape
+  // normalizeBootstrapResponse accepts) or `{success: false,
+  // bootstrapRequired: true}`; it may throw on transport errors.  Gap
+  // recovery prefers it over `cloud.bootstrap` and falls back to a fresh
+  // bootstrap walk whenever it fails or is unavailable.
+  const recoverBaseline = async (context, targetRevision, mode) => {
+    if (typeof cloud?.catchUp === 'function') {
+      try {
+        const caught = await cloud.catchUp(context, {
+          fromRevision: workspace.remoteBaseline.revision,
+          targetRevision,
+          ...bootstrapAttemptOptions(`${mode}-catchup`)
+        });
+        if (rtlEnvelopeSuccess(caught)) {
+          return requireBootstrapRevision(normalizeBootstrapResponse(caught), targetRevision);
+        }
+      } catch (error) {
+        logger?.warn?.('[RecordTimeLabelCore] catch-up failed, falling back to bootstrap', error);
+      }
+    }
+    return requireBootstrapRevision(
+      normalizeBootstrapResponse(await cloud.bootstrap(
+        context,
+        bootstrapAttemptOptions(mode)
+      )),
+      targetRevision
+    );
+  };
+
   const normalizeLoadedWorkspace = (loaded, captured) => {
     const source = loaded && typeof loaded === 'object' ? loaded : {};
     const hasDurableShape = source.remoteBaseline || source.pendingOperations || source.schemaVersion === RTL_DURABLE_SCHEMA_VERSION;
@@ -3302,6 +3388,10 @@ export const createRecordTimeLabelSyncEngine = ({
           );
         });
       });
+      const migrationBatchId = rtlStableSyncBatchId(migratedOperations);
+      migratedOperations.forEach((operation) => {
+        if (!operation.syncBatchId) operation.syncBatchId = migrationBatchId;
+      });
       loadedWorkspace.remoteBaseline = rtlNormalizeRemoteBaseline({});
       loadedWorkspace.pendingOperations = [
         ...migratedOperations,
@@ -3405,10 +3495,7 @@ export const createRecordTimeLabelSyncEngine = ({
         return {success: false, reason: 'revision_gap', bootstrapRequired: true};
       }
       const context = rtlSessionContext(captured, candidate, client);
-      baselineValue = normalizeBootstrapResponse(await cloud.bootstrap(
-        context,
-        bootstrapAttemptOptions('gap-recovery')
-      ));
+      baselineValue = await recoverBaseline(context, remoteRevision, 'gap-recovery');
       if (!(await isCurrent(captured))) return {stale: true, reason: 'stale_session'};
     }
     const applied = applyRemoteBaseline(candidate, baselineValue);
@@ -3447,6 +3534,12 @@ export const createRecordTimeLabelSyncEngine = ({
     const captured = capture();
     const loaded = await storage.load();
     if (!(await isCurrent(captured))) return getSnapshot();
+    // The reuse predicate must read the RAW loaded owner before
+    // normalizeLoadedWorkspace adopts the current session identity onto the
+    // workspace; epochs are intentionally not compared (consumers may advance
+    // the persisted epoch on every launch).
+    const loadedOwnerUid = rtlNormalizeUid(loaded?.ownerUid);
+    const committedRevision = Number(loaded?.remoteBaseline?.revision || 0);
     let candidate = normalizeLoadedWorkspace(loaded, captured);
     const identityChecked = rtlQuarantineOperations(
       candidate,
@@ -3457,7 +3550,10 @@ export const createRecordTimeLabelSyncEngine = ({
     candidate.rejectedOperations = identityChecked.rejected;
     const context = rtlSessionContext(captured, candidate, client);
 
-    if (captured?.uid && typeof cloud?.bootstrap === 'function') {
+    const canReuseCommitted = initialBaseline === 'reuse-committed' &&
+      captured?.uid && loadedOwnerUid === rtlNormalizeUid(captured.uid) &&
+      committedRevision > 0;
+    if (captured?.uid && typeof cloud?.bootstrap === 'function' && !canReuseCommitted) {
       let bootstrap;
       try {
         bootstrap = normalizeBootstrapResponse(await cloud.bootstrap(
@@ -3727,10 +3823,12 @@ export const createRecordTimeLabelSyncEngine = ({
         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) {
@@ -3741,12 +3839,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),
@@ -3763,13 +3864,19 @@ 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 = await recoverBaseline(context, responseRevision, 'gap-recovery');
+      if (!(await isCurrent(captured))) return {success: false, reason: 'stale_session'};
+      applyRemoteBaseline(candidate, freshBaseline);
     }
     candidate.pendingOperations = nextPending;
     candidate.rejectedOperations = nextRejected;
@@ -3778,16 +3885,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 = normalizeBootstrapResponse(await cloud.bootstrap(
-          context,
-          bootstrapAttemptOptions('rejection-rebase')
-        ));
+        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;

package/src/protocol.js

@@ -59,6 +59,37 @@ const fnv1a = (value) => {
   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 {
@@ -73,14 +104,17 @@ export const toRecordTimeLabelWireOperation = (operation = {}) => {
 export const buildRecordTimeLabelRequestId = (namespace, operations = []) => {
   const safeNamespace = normalizeId(namespace)
     .replace(/[^A-Za-z0-9._:-]+/g, '-')
-    .slice(0, 64) || 'recordtimelabel';
-  const orderedIds = Array.isArray(operations)
-    ? operations.map((operation) => normalizeId(asObject(operation).id))
+    .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, 72) || 'empty';
-  return `rtl:${safeNamespace}:${firstOperationId}:${fnv1a(orderedIds.join('\u001f'))}`.slice(0, 160);
+    .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) => {