@recordtimelabel/core 0.4.4 → 0.4.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recordtimelabel/core",
-  "version": "0.4.4",
+  "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.4';
+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',
@@ -3134,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;
@@ -3277,6 +3281,37 @@ export const createRecordTimeLabelSyncEngine = ({
     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;
@@ -3460,13 +3495,7 @@ export const createRecordTimeLabelSyncEngine = ({
         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
-      );
+      baselineValue = await recoverBaseline(context, remoteRevision, 'gap-recovery');
       if (!(await isCurrent(captured))) return {stale: true, reason: 'stale_session'};
     }
     const applied = applyRemoteBaseline(candidate, baselineValue);
@@ -3505,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,
@@ -3515,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(
@@ -3836,13 +3874,7 @@ export const createRecordTimeLabelSyncEngine = ({
       responseRevision > candidate.remoteBaseline.revision + 1 &&
       typeof cloud?.bootstrap === 'function'
     ) {
-      const freshBaseline = requireBootstrapRevision(
-        normalizeBootstrapResponse(await cloud.bootstrap(
-          context,
-          bootstrapAttemptOptions('gap-recovery')
-        )),
-        responseRevision
-      );
+      const freshBaseline = await recoverBaseline(context, responseRevision, 'gap-recovery');
       if (!(await isCurrent(captured))) return {success: false, reason: 'stale_session'};
       applyRemoteBaseline(candidate, freshBaseline);
     }