@recordtimelabel/core 0.4.4 → 0.4.6

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 current strict durable transport contract is prepared in package version `0.4.4` (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.6` (publish it before updating consumers):
 
 ```json
-"@recordtimelabel/core": "0.4.4"
+"@recordtimelabel/core": "0.4.6"
 ```
 
 If this checkout's `package.json` is ahead of the published version, publish the new package before updating consumers to that version.
@@ -33,6 +33,8 @@ If this checkout's `package.json` is ahead of the published version, publish the
 - `applyOperation(state, operation)`
 - `applyRecordTimeLabelOperation(state, operation)`
 - `createRecordTimeLabelSyncEngine({ storage, cloud, session, client, clock, logger })`
+- `RTL_MAX_SYNC_DRAIN_ROUNDS`
+- `RTL_SYNC_DRAIN_RETRY_DELAY_MS`
 - `RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES`
 - `RECORD_TIMELABEL_PROTOCOL_CAPABILITIES`
 - `toRecordTimeLabelWireOperation(operation)`
@@ -121,13 +123,24 @@ 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
-operations over `remoteBaseline.state`; rejected operations are kept in diagnostics and are not
-replayed. Session tokens are used for fencing but are never persisted. The legacy
+operation acknowledgement records its revision diagnostically and advances
+`remoteBaseline.revision` with a complete state, or with an all-applied no-state ACK at
+exactly the next revision; larger revision gaps trigger a fresh bootstrap. Re-dispatching
+the same operation ID and wire content is reported as deduplicated, while different wire
+content is quarantined as an ID conflict. Rejected entries are terminal diagnostics in this
+API; an intentional retry currently requires a new operation ID.
+
+The engine exposes `init()`, `dispatch(operations)`, `sync(reason)`,
+`syncUntilIdle(reason, options)`, `waitForIdle()`, `getSnapshot()`, `subscribe(listener)`,
+and `destroy()`. `sync()` preserves the one-FIFO-batch boundary. `syncUntilIdle()` drains
+subsequent batches up to `RTL_MAX_SYNC_DRAIN_ROUNDS`; it stops on retry/deferred/protocol
+conditions and reports `syncDrainLimitReached` as a retryable failure instead of silently
+reporting success. Hosts may provide `beforeRound({round, pendingCount, snapshot})` to block
+gateway writes while a host-specific hydration/import gate is active, and `runRound({round,
+pendingCount, run})` to serialize that gate check and the gateway call with host mutations.
+`getSnapshot().state` is derived by replaying pending operations over `remoteBaseline.state`;
+rejected operations are kept in diagnostics and are not replayed. Session tokens are used for
+fencing but are never persisted. The legacy
 `createSyncEngine` and app adapters remain available and are not implicitly migrated by this API.
 
 `expandedGroups` is a local view projection, not durable cloud domain state. Durable workspaces,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recordtimelabel/core",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "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.6';
 export const RTL_SYNC_PROTOCOL_VERSION = 2;
 export const RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES = Object.freeze([
   'fifo-retry-fence',
@@ -42,6 +42,8 @@ export const RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES = Object.freeze([
   RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE
 ]);
 export const RTL_MAX_OPERATIONS_PER_REQUEST = 20;
+export const RTL_MAX_SYNC_DRAIN_ROUNDS = 50;
+export const RTL_SYNC_DRAIN_RETRY_DELAY_MS = 1000;
 export const RTL_MAX_REQUEST_BYTES = 256 * 1024;
 export const RTL_MAX_TARGET_WRITES = 100;
 export const RTL_TRASH_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
@@ -2954,6 +2956,7 @@ const rtlQuarantineOperations = (workspace, operations, timestamp = Date.now())
     });
   }
   let rejectedCount = 0;
+  let deduplicatedCount = 0;
   toArray(operations).forEach((operation, index) => {
     const id = normalizeId(operation?.id);
     const fingerprint = rtlOperationWireFingerprint(operation);
@@ -2961,7 +2964,10 @@ const rtlQuarantineOperations = (workspace, operations, timestamp = Date.now())
     let reason = rtlOperationIdentityReason(operation, workspace);
     if (!reason) reason = rtlLifecycleOperationReason(operation, lifecycleState);
     if (!reason && knownFingerprint) {
-      if (knownFingerprint === fingerprint) return;
+      if (knownFingerprint === fingerprint) {
+        deduplicatedCount += 1;
+        return;
+      }
       reason = RECORD_TIMELABEL_OPERATION_IDENTITY_REASONS.ID_CONFLICT;
     }
     if (!reason) {
@@ -2991,7 +2997,7 @@ const rtlQuarantineOperations = (workspace, operations, timestamp = Date.now())
       }
     };
   });
-  return {accepted, rejected, rejectedCount};
+  return {accepted, rejected, rejectedCount, deduplicatedCount};
 };
 
 const rtlExtractSession = (session, fallbackEpoch = 0) => {
@@ -3134,11 +3140,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 +3287,42 @@ 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 on transport/protocol failure. A successful but stale
+  // catch-up response is fail-closed: falling back would hide a revision
+  // contract violation and could apply a baseline older than the ACK.
+  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) {
+        if (error?.code === 'recordtimelabel_bootstrap_revision_behind_required') {
+          throw 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 +3506,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 +3545,17 @@ export const createRecordTimeLabelSyncEngine = ({
     const captured = capture();
     const loaded = await storage.load();
     if (!(await isCurrent(captured))) return getSnapshot();
+    // Read the raw owner and baseline before normalizeLoadedWorkspace adopts
+    // the current session identity. Reuse still validates the normalized
+    // candidate below because owner/epoch fences may replace loaded data with
+    // an empty workspace.
+    const loadedOwnerUid = rtlNormalizeUid(loaded?.ownerUid);
+    const loadedBaseline = loaded?.remoteBaseline;
+    const committedRevision = Number(loadedBaseline?.revision);
+    const hasValidCommittedBaseline = rtlDurableIsObject(loadedBaseline) &&
+      rtlDurableIsObject(loadedBaseline.state) &&
+      Number.isFinite(committedRevision) &&
+      committedRevision > 0;
     let candidate = normalizeLoadedWorkspace(loaded, captured);
     const identityChecked = rtlQuarantineOperations(
       candidate,
@@ -3515,7 +3566,13 @@ 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) &&
+      hasValidCommittedBaseline &&
+      candidate.ownerUid === rtlNormalizeUid(captured.uid) &&
+      candidate.remoteBaseline.revision === committedRevision &&
+      (!captured.hasEpoch || Number(candidate.workspaceEpoch) === Number(captured.workspaceEpoch));
+    if (captured?.uid && typeof cloud?.bootstrap === 'function' && !canReuseCommitted) {
       let bootstrap;
       try {
         bootstrap = normalizeBootstrapResponse(await cloud.bootstrap(
@@ -3633,10 +3690,20 @@ export const createRecordTimeLabelSyncEngine = ({
         type: 'local_applied',
         operations: clone([...durableOperations, ...viewOperations]),
         operation: clone(viewOperations.at(-1) || durableOperations.at(-1)),
-        rejectedCount: identityChecked.rejectedCount
+        rejectedCount: identityChecked.rejectedCount,
+        deduplicatedCount: identityChecked.deduplicatedCount
+      });
+    } else if (identityChecked.deduplicatedCount > 0 && identityChecked.rejectedCount === 0) {
+      notify({
+        type: 'operations_deduplicated',
+        deduplicatedCount: identityChecked.deduplicatedCount
       });
     } else {
-      notify({type: 'operations_rejected', rejectedCount: identityChecked.rejectedCount});
+      notify({
+        type: 'operations_rejected',
+        rejectedCount: identityChecked.rejectedCount,
+        deduplicatedCount: identityChecked.deduplicatedCount
+      });
     }
     return getSnapshot();
   };
@@ -3830,19 +3897,28 @@ export const createRecordTimeLabelSyncEngine = ({
     const responseState = responseBaseline?.state ?? responseBaseline?.data;
     if (rtlDurableIsObject(responseState)) {
       applyRemoteBaseline(candidate, responseBaseline);
+    } else if (
+      rejectedCount === 0 &&
+      !sawRetryable &&
+      appliedOperations.length === completedOperations.length &&
+      appliedOperations.length > 0 &&
+      Number.isFinite(responseRevision) &&
+      responseRevision === candidate.remoteBaseline.revision + 1
+    ) {
+      // The v2 gateway ACK is intentionally compact and omits state. Promote
+      // only an all-applied transaction at exactly the next revision; any
+      // larger jump still needs an authoritative bootstrap baseline.
+      candidate.remoteBaseline.revision = responseRevision;
+      if (Object.prototype.hasOwnProperty.call(responseBaseline || {}, 'changeCursor')) {
+        candidate.remoteBaseline.changeCursor = responseBaseline.changeCursor ?? null;
+      }
     } 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
-      );
+      const freshBaseline = await recoverBaseline(context, responseRevision, 'gap-recovery');
       if (!(await isCurrent(captured))) return {success: false, reason: 'stale_session'};
       applyRemoteBaseline(candidate, freshBaseline);
     }
@@ -3898,6 +3974,120 @@ export const createRecordTimeLabelSyncEngine = ({
     };
   };
 
+  // `sync()` intentionally sends only one immutable FIFO batch. Consumers
+  // that own the outbox scan may use this method to drain subsequent batches
+  // without reimplementing the stop conditions in each host application.
+  // `beforeRound` is a host gate (hydration/import/account state); `runRound`
+  // can serialize that gate check and the gateway call with host mutations.
+  const syncUntilIdleInternal = async (reason, options = {}) => {
+    const maxRounds = Number.isSafeInteger(Number(options?.maxRounds)) &&
+      Number(options.maxRounds) > 0
+      ? Number(options.maxRounds)
+      : RTL_MAX_SYNC_DRAIN_ROUNDS;
+    const beforeRound = typeof options?.beforeRound === 'function'
+      ? options.beforeRound
+      : null;
+    const runRound = typeof options?.runRound === 'function'
+      ? options.runRound
+      : null;
+    const totals = {
+      appliedCount: 0,
+      syncedCount: 0,
+      rejectedCount: 0,
+      retryCount: 0,
+      identityRejectedCount: 0
+    };
+    let lastResult = null;
+    let rounds = 0;
+
+    for (let round = 0; round < maxRounds; round += 1) {
+      rounds += 1;
+      const executeRound = async () => {
+        if (beforeRound) {
+          const gate = await beforeRound({
+            round,
+            pendingCount: workspace.pendingOperations.length,
+            snapshot: getSnapshot()
+          });
+          if (gate === false || gate?.allowed === false) {
+            const details = gate && typeof gate === 'object' ? {...gate} : {};
+            delete details.allowed;
+            return {
+              ...details,
+              success: true,
+              deferred: true,
+              pendingSync: workspace.pendingOperations.length > 0,
+              reason: details.reason || 'sync_gate_blocked',
+              pendingCount: workspace.pendingOperations.length
+            };
+          }
+        }
+        return syncInternal(reason);
+      };
+      const result = runRound
+        ? await runRound({
+            round,
+            pendingCount: workspace.pendingOperations.length,
+            run: executeRound
+          })
+        : await executeRound();
+      lastResult = result && typeof result === 'object'
+        ? result
+        : {success: false, reason: 'sync_round_missing_result'};
+      Object.keys(totals).forEach((key) => {
+        const value = Number(lastResult?.[key]);
+        if (Number.isFinite(value)) totals[key] += value;
+      });
+
+      const pendingCount = Number(lastResult?.pendingCount ?? workspace.pendingOperations.length);
+      const madeProgress = Number(lastResult?.syncedCount || lastResult?.appliedCount || 0) > 0 ||
+        Number(lastResult?.rejectedCount || 0) > 0 ||
+        Number(lastResult?.retryCount || 0) > 0 ||
+        Number(lastResult?.identityRejectedCount || 0) > 0;
+      if (
+        lastResult.deferred ||
+        lastResult.success === false ||
+        lastResult.retryable ||
+        lastResult.protocolError ||
+        lastResult.skipped ||
+        lastResult.retryCount > 0 ||
+        pendingCount === 0 ||
+        !madeProgress
+      ) break;
+    }
+
+    const pendingCount = Number(lastResult?.pendingCount ?? workspace.pendingOperations.length);
+    const result = {
+      ...(lastResult || {success: true}),
+      ...totals,
+      pendingCount,
+      syncDrainRounds: rounds,
+      drained: pendingCount === 0
+    };
+    if (
+      pendingCount > 0 &&
+      rounds >= maxRounds &&
+      !result.deferred &&
+      result.success !== false &&
+      !result.retryable &&
+      !result.skipped
+    ) {
+      const retryAt = now() + RTL_SYNC_DRAIN_RETRY_DELAY_MS;
+      return {
+        ...result,
+        success: false,
+        retryable: true,
+        pendingSync: true,
+        reason: 'sync_drain_limit_reached',
+        syncDrainLimitReached: true,
+        drainLimitReached: true,
+        retryAfterMs: RTL_SYNC_DRAIN_RETRY_DELAY_MS,
+        retryAt
+      };
+    }
+    return result;
+  };
+
   const engine = {
     init() {
       return enqueue(async () => {
@@ -3914,6 +4104,14 @@ export const createRecordTimeLabelSyncEngine = ({
       return enqueue(() => syncInternal(reason));
     },
 
+    syncUntilIdle(reason, options = {}) {
+      return enqueue(() => syncUntilIdleInternal(reason, options));
+    },
+
+    waitForIdle() {
+      return queue.catch(() => null);
+    },
+
     getSnapshot,
 
     subscribe(listener) {
@@ -4964,6 +5162,8 @@ export default {
   RECORD_TIMELABEL_PROTOCOL_CAPABILITIES,
   RTL_SYNC_PROTOCOL_VERSION,
   RTL_MAX_OPERATIONS_PER_REQUEST,
+  RTL_MAX_SYNC_DRAIN_ROUNDS,
+  RTL_SYNC_DRAIN_RETRY_DELAY_MS,
   RTL_MAX_REQUEST_BYTES,
   RTL_MAX_TARGET_WRITES,
   RTL_TRASH_RETENTION_MS,