@recordtimelabel/core 0.6.6 → 0.6.8

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 release target is `0.6.6`; verify that its registry tarball and lockfile integrity are available 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 release target is `0.6.8`; verify that its registry tarball and lockfile integrity are available before updating consumers:
 
 ```json
-"@recordtimelabel/core": "0.6.6"
+"@recordtimelabel/core": "0.6.8"
 ```
 
 If this checkout's `package.json` is ahead of the published version, publish the new package before updating consumers to that version.
@@ -38,7 +38,9 @@ If this checkout's `package.json` is ahead of the published version, publish the
 - `RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES`
 - `RECORD_TIMELABEL_CAPABILITY_CLOUD_FAILURE_STATE`
 - `RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES`
+- `RECORD_TIMELABEL_CLOUD_RECOVERY_ACTIONS`
 - `normalizeRecordTimeLabelCloudFailure(input)`
+- `classifyRecordTimeLabelCloudRecovery(input)`
 - `toRecordTimeLabelCloudFailureError(input)`
 - `RECORD_TIMELABEL_PROTOCOL_CAPABILITIES`
 - `toRecordTimeLabelWireOperation(operation)`

package/package.json

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

package/src/index.js

@@ -8,12 +8,14 @@ import {
   RECORD_TIMELABEL_CAPABILITY_STRICT_READINESS,
   RECORD_TIMELABEL_CLOUD_FAILURE_SCHEMA_VERSION,
   RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES,
+  RECORD_TIMELABEL_CLOUD_RECOVERY_ACTIONS,
   RECORD_TIMELABEL_OPERATION_RESULT_STATUSES,
   RECORD_TIMELABEL_PROTOCOL_CAPABILITIES,
   buildRecordTimeLabelRequestId,
   createRecordTimeLabelTransportFailureResults,
   isRecordTimeLabelOperationConflictFailure,
   normalizeRecordTimeLabelCloudFailure,
+  classifyRecordTimeLabelCloudRecovery,
   normalizeRecordTimeLabelEnvelopeResponse,
   normalizeRecordTimeLabelOperationResults,
   normalizeRecordTimeLabelImmutableId,
@@ -32,12 +34,14 @@ export {
   RECORD_TIMELABEL_CAPABILITY_STRICT_READINESS,
   RECORD_TIMELABEL_CLOUD_FAILURE_SCHEMA_VERSION,
   RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES,
+  RECORD_TIMELABEL_CLOUD_RECOVERY_ACTIONS,
   RECORD_TIMELABEL_OPERATION_RESULT_STATUSES,
   RECORD_TIMELABEL_PROTOCOL_CAPABILITIES,
   buildRecordTimeLabelRequestId,
   createRecordTimeLabelTransportFailureResults,
   isRecordTimeLabelOperationConflictFailure,
   normalizeRecordTimeLabelCloudFailure,
+  classifyRecordTimeLabelCloudRecovery,
   normalizeRecordTimeLabelEnvelopeResponse,
   normalizeRecordTimeLabelOperationResults,
   normalizeRecordTimeLabelImmutableId,
@@ -141,7 +145,7 @@ export {
   selectBestMatchingTwitchVod
 };
 
-export const RECORD_TIMELABEL_CORE_VERSION = '0.6.6';
+export const RECORD_TIMELABEL_CORE_VERSION = '0.6.8';
 export const RTL_SYNC_PROTOCOL_VERSION = 2;
 export const RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES = Object.freeze([
   'fifo-retry-fence',
@@ -4044,6 +4048,7 @@ export const createRecordTimeLabelSyncEngine = ({
     })
   };
   let bootstrapAttemptSequence = 0;
+  const activeBootstrapAttempts = new Map();
   let authTransitionLatch = null;
   const listeners = new Set();
   let queue = Promise.resolve();
@@ -4164,7 +4169,7 @@ export const createRecordTimeLabelSyncEngine = ({
     return {changed, stale: false};
   };
 
-  const bootstrapAttemptOptions = (mode) => ({
+  const createBootstrapAttemptOptions = (mode) => ({
     mode,
     attemptId: `bootstrap:${mode}:${now()}:${++bootstrapAttemptSequence}:${
       globalThis.crypto?.randomUUID?.() || Math.random().toString(36).slice(2, 14)
@@ -4172,6 +4177,27 @@ export const createRecordTimeLabelSyncEngine = ({
     requireFresh: true
   });
 
+  const bootstrapAttemptIdentity = (context = {}) => JSON.stringify([
+    context.uid ?? null,
+    context.sessionToken ?? null,
+    Number(context.workspaceEpoch || 0)
+  ]);
+
+  const bootstrapAttemptOptions = (mode, context) => {
+    const identity = bootstrapAttemptIdentity(context);
+    const active = activeBootstrapAttempts.get(mode);
+    if (active?.identity === identity) return active.options;
+    const options = createBootstrapAttemptOptions(mode);
+    activeBootstrapAttempts.set(mode, {identity, options});
+    return options;
+  };
+
+  const clearBootstrapAttempt = (mode, options) => {
+    if (activeBootstrapAttempts.get(mode)?.options === options) {
+      activeBootstrapAttempts.delete(mode);
+    }
+  };
+
   const normalizeBootstrapResponse = (response) => {
     if (!rtlEnvelopeSuccess(response)) {
       const source = response && typeof response === 'object' ? response : {
@@ -4196,6 +4222,24 @@ export const createRecordTimeLabelSyncEngine = ({
     return {state, revision, changeCursor: remote.changeCursor ?? null};
   };
 
+  // A transient failure belongs to the same logical page walk. Keep its
+  // attempt ID so the platform bootstrap owner can resume the signed cursor;
+  // successful and non-transient outcomes retire the attempt.
+  const runBootstrapAttempt = async (context, mode) => {
+    const options = bootstrapAttemptOptions(mode, context);
+    try {
+      const baseline = normalizeBootstrapResponse(await cloud.bootstrap(context, options));
+      clearBootstrapAttempt(mode, options);
+      return baseline;
+    } catch (error) {
+      const failure = normalizeRecordTimeLabelCloudFailure(error);
+      if (failure.class !== RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT) {
+        clearBootstrapAttempt(mode, options);
+      }
+      throw error;
+    }
+  };
+
   const clearAuthTransitionLatchIfSessionChanged = (captured) => {
     if (!authTransitionLatch) return;
     if (!rtlSameSessionIdentity(authTransitionLatch, captured)) {
@@ -4279,7 +4323,7 @@ export const createRecordTimeLabelSyncEngine = ({
         const caught = await cloud.catchUp(context, {
           fromRevision: workspace.remoteBaseline.revision,
           targetRevision,
-          ...bootstrapAttemptOptions(`${mode}-catchup`)
+          ...createBootstrapAttemptOptions(`${mode}-catchup`)
         });
         if (rtlEnvelopeSuccess(caught)) {
           return requireBootstrapRevision(normalizeBootstrapResponse(caught), targetRevision);
@@ -4304,10 +4348,7 @@ export const createRecordTimeLabelSyncEngine = ({
     throwIfAuthTransitionLatched(captured);
     try {
       return requireBootstrapRevision(
-        normalizeBootstrapResponse(await cloud.bootstrap(
-          context,
-          bootstrapAttemptOptions(mode)
-        )),
+        await runBootstrapAttempt(context, mode),
         targetRevision
       );
     } catch (error) {
@@ -4581,10 +4622,7 @@ export const createRecordTimeLabelSyncEngine = ({
     }
     let baseline;
     try {
-      baseline = normalizeBootstrapResponse(await cloud.bootstrap(
-        context,
-        bootstrapAttemptOptions('apply-failure-rebase')
-      ));
+      baseline = await runBootstrapAttempt(context, 'apply-failure-rebase');
     } catch (bootstrapError) {
       if (!(await isCurrent(captured))) return {success: false, reason: 'stale_session'};
       rethrowClassifiedCloudFailure(captured, bootstrapError);
@@ -4751,10 +4789,7 @@ export const createRecordTimeLabelSyncEngine = ({
       if (typeof cloud?.bootstrap === 'function') {
         try {
           freshBaseline = requireBootstrapRevision(
-            normalizeBootstrapResponse(await cloud.bootstrap(
-              context,
-              bootstrapAttemptOptions('rejection-rebase')
-            )),
+            await runBootstrapAttempt(context, 'rejection-rebase'),
             requiredRevision
           );
         } catch (bootstrapError) {
@@ -5249,10 +5284,7 @@ export const createRecordTimeLabelSyncEngine = ({
       });
       let bootstrap;
       try {
-        bootstrap = normalizeBootstrapResponse(await cloud.bootstrap(
-          context,
-          bootstrapAttemptOptions('initial-hydration')
-        ));
+        bootstrap = await runBootstrapAttempt(context, 'initial-hydration');
       } catch (error) {
         if (!(await isCurrent(captured))) return getSnapshot();
         if (persistedHydrationRequired) {
@@ -5779,10 +5811,7 @@ export const createRecordTimeLabelSyncEngine = ({
       let freshBaseline;
       try {
         freshBaseline = requireBootstrapRevision(
-          normalizeBootstrapResponse(await cloud.bootstrap(
-            context,
-            bootstrapAttemptOptions('rejection-rebase')
-          )),
+          await runBootstrapAttempt(context, 'rejection-rebase'),
           responseRevision
         );
       } catch (error) {
@@ -5930,6 +5959,12 @@ export const createRecordTimeLabelSyncEngine = ({
         const captured = capture();
         clearAuthTransitionLatchIfSessionChanged(captured);
         if (initialized && !hydrationRequired && workspaceMatchesSession(captured)) {
+          // A transient listener failure stops only the provider subscription.
+          // Re-entering init for the same owner must reattach that subscription
+          // without discarding the committed workspace or bootstrapping again.
+          if (captured?.uid && !subscriptionContext && typeof cloud?.subscribe === 'function') {
+            startCloudSubscription(captured, workspace);
+          }
           return getSnapshot();
         }
         if (initialized && !hydrationRequired && !workspaceMatchesSession(captured)) {
@@ -7327,8 +7362,10 @@ export default {
   RECORD_TIMELABEL_CAPABILITY_STRICT_READINESS,
   RECORD_TIMELABEL_CLOUD_FAILURE_SCHEMA_VERSION,
   RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES,
+  RECORD_TIMELABEL_CLOUD_RECOVERY_ACTIONS,
   isRecordTimeLabelOperationConflictFailure,
   normalizeRecordTimeLabelCloudFailure,
+  classifyRecordTimeLabelCloudRecovery,
   toRecordTimeLabelCloudFailureError,
   RECORD_TIMELABEL_OPERATION_RESULT_STATUSES,
   RECORD_TIMELABEL_PROTOCOL_CAPABILITIES,

package/src/protocol.js

@@ -73,6 +73,16 @@ export const RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES = Object.freeze({
   STALE_SESSION: 'stale-session'
 });
 
+// Hosts must map class to these actions. They may choose the platform I/O
+// (alarm, timer, Web Lock, Main process), but they must not invent a fourth
+// strategy such as "rebuild the owner on 429".
+export const RECORD_TIMELABEL_CLOUD_RECOVERY_ACTIONS = Object.freeze({
+  IGNORE: 'ignore',
+  WAIT: 'wait',
+  BOOTSTRAP: 'bootstrap',
+  LOCK: 'lock'
+});
+
 const CLOUD_FAILURE_CLASS_VALUES = new Set(Object.values(RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES));
 
 // Keep operation-conflict aliases in one wire-compatibility table.  The
@@ -580,6 +590,28 @@ export const toRecordTimeLabelCloudFailureError = (input = {}) => {
   return error;
 };
 
+/**
+ * Shared recovery mapping for cloud-failure-state-v1. Core owns the class →
+ * action table so Extension and Flowmoor cannot fork "retry" into bootstrap.
+ *
+ * `wait` keeps the workspace, outbox, and cursor/attempt and honors
+ * `retryAfterMs`. It is not permission to rebuild an owner or start a page-1
+ * walk. `bootstrap` is the only action that may start a fresh hydration.
+ */
+export const classifyRecordTimeLabelCloudRecovery = (input = {}) => {
+  const failure = normalizeRecordTimeLabelCloudFailure(input);
+  if (failure.class === RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.STALE_SESSION) {
+    return {action: RECORD_TIMELABEL_CLOUD_RECOVERY_ACTIONS.IGNORE, failure};
+  }
+  if (failure.class === RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT) {
+    return {action: RECORD_TIMELABEL_CLOUD_RECOVERY_ACTIONS.WAIT, failure};
+  }
+  if (failure.class === RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.BOOTSTRAP_REQUIRED) {
+    return {action: RECORD_TIMELABEL_CLOUD_RECOVERY_ACTIONS.BOOTSTRAP, failure};
+  }
+  return {action: RECORD_TIMELABEL_CLOUD_RECOVERY_ACTIONS.LOCK, failure};
+};
+
 const ALLOWED_OPERATION_RESULT_STATUSES = new Set(
   Object.values(RECORD_TIMELABEL_OPERATION_RESULT_STATUSES)
 );
@@ -833,6 +865,7 @@ export default {
   RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE_V1,
   RECORD_TIMELABEL_CLOUD_FAILURE_SCHEMA_VERSION,
   RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES,
+  RECORD_TIMELABEL_CLOUD_RECOVERY_ACTIONS,
   RECORD_TIMELABEL_PROTOCOL_CAPABILITIES,
   toRecordTimeLabelWireOperation,
   buildRecordTimeLabelRequestId,
@@ -840,6 +873,7 @@ export default {
   normalizeRecordTimeLabelOperationResults,
   normalizeRecordTimeLabelEnvelopeResponse,
   normalizeRecordTimeLabelCloudFailure,
+  classifyRecordTimeLabelCloudRecovery,
   toRecordTimeLabelCloudFailureError,
   isRecordTimeLabelOperationConflictFailure,
   normalizeRecordTimeLabelImmutableId,