@recordtimelabel/core 0.6.2 → 0.6.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 current published artifact is `0.6.2`:
+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.5`; verify that its registry tarball and lockfile integrity are available before updating consumers:
 
 ```json
-"@recordtimelabel/core": "0.6.2"
+"@recordtimelabel/core": "0.6.5"
 ```
 
 If this checkout's `package.json` is ahead of the published version, publish the new package before updating consumers to that version.
@@ -106,14 +106,22 @@ the whole session object as an authorization token, and `bootstrap`/`catchUp`/`a
 context no longer carries `token`. Platform adapters obtain Firebase credentials from
 their own credential provider.
 
-`normalizeRecordTimeLabelCloudFailure` preserves `status`, `reason`, `retryable`, and
-`retryAfterMs`, and assigns exactly one class: `transient`, `bootstrap-required`,
-`auth-transition-required`, `terminal`, or `stale-session`. Capability
-`cloud-failure-state-v1` advertises this contract. An `auth-transition-required`
-bootstrap or catch-up failure latches that session identity so repeated `init()`
-calls do not invoke `cloud.bootstrap` again. A changed SessionPort capture, UID, or
-workspace epoch clears the latch. `recoverBaseline` falls back from catch-up only for
-explicit `bootstrap-required` / cursor-gap outcomes; auth and transient failures keep
+`normalizeRecordTimeLabelCloudFailure` preserves `status`, `reason`, `code`,
+`message`, `retryable`, and `retryAfterMs`, and assigns exactly one class:
+`transient`, `bootstrap-required`, `auth-transition-required`, `terminal`, or
+`stale-session`. Classification uses only an explicit class, HTTP status,
+`retryable`, `bootstrapRequired`, and other platform-neutral fields. Adapters
+may keep a Firebase reason string, but Core does not interpret Firebase or JWT
+taxonomies. `{error: "reason"}` keeps that string as `reason`, `code`, and
+`message`. Capability `cloud-failure-state-v1` is part of
+`RECORD_TIMELABEL_PROTOCOL_CAPABILITIES`; clients must not invent that string.
+An `auth-transition-required` bootstrap or catch-up failure latches the captured
+session identity (`sessionToken` + UID + workspace epoch) so repeated `init()`
+calls do not invoke `cloud.bootstrap` again. A changed SessionPort identity,
+UID, or workspace epoch clears the latch. An ID token refresh that keeps the
+same `sessionToken` must not change session identity or current work.
+`recoverBaseline` falls back from catch-up only for explicit
+`bootstrap-required` / cursor-gap outcomes; auth and transient failures keep
 their class and must not start a second full walk.
 
 The persisted workspace is versioned and contains only durable data:
@@ -126,10 +134,22 @@ The persisted workspace is versioned and contains only durable data:
   remoteBaseline: { state, revision: 12, changeCursor: 'cursor-12' },
   pendingOperations: [],
   rejectedOperations: {},
-  syncMeta: {}
+  syncMeta: {
+    // Core-owned resume fence; the cursor itself remains opaque adapter data.
+    changeCursorBinding: {
+      ownerUid: 'user-id', uid: 'user-id', workspaceEpoch: 3,
+      authSessionBinding: 'auth-session-3'
+    }
+  }
 }
 ```
 
+`remoteBaseline.changeCursor` is an opaque string owned by the cloud adapter and
+must remain byte-for-byte stable across persistence. Core stores the owner,
+workspace-epoch, and non-credential auth binding separately in
+`syncMeta.changeCursorBinding` so a committed workspace can be resumed without
+embedding session credentials in the cursor.
+
 Every normalized pending operation also carries `ownerUid` and a non-negative
 `workspaceEpoch`. Dispatch stamps these fields from the captured session; legacy
 operations missing them inherit the migrated workspace identity. An operation whose

package/package.json

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

package/src/changefeed.js

@@ -72,15 +72,38 @@ export const applyFirestoreV2ResolvedChangeBatch = ({
   const inputRevision = Number(cache?.revision || 0);
   const inputDocuments = cache?.documents || {};
   const inputCache = {revision: inputRevision, documents: inputDocuments};
-  const expectedTarget = targetRevision == null ? null : Number(targetRevision);
-  if (!Number.isFinite(inputRevision) || inputRevision < 0) {
+  const hasExpectedTarget = targetRevision != null;
+  const expectedTarget = hasExpectedTarget ? Number(targetRevision) : null;
+  if (!Number.isSafeInteger(inputRevision) || inputRevision < 0 ||
+    (hasExpectedTarget && (!Number.isSafeInteger(expectedTarget) || expectedTarget < 0))) {
     return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.REVISION_GAP, inputCache);
   }
 
   const batch = Array.isArray(changes) ? changes : [];
   if (batch.length === 0) {
-    if (expectedTarget != null && Number.isFinite(expectedTarget) && expectedTarget < inputRevision) {
-      return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.CACHE_AHEAD, inputCache);
+    if (expectedTarget != null && Number.isFinite(expectedTarget)) {
+      if (expectedTarget < inputRevision) {
+        return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.CACHE_AHEAD, inputCache);
+      }
+    }
+    const resolvedRoot = resolvedDocuments?.root;
+    if (hasExpectedTarget || resolvedRoot !== undefined) {
+      const rootRevision = Number(resolvedRoot?.revision);
+      const expectedRootRevision = expectedTarget != null && Number.isFinite(expectedTarget)
+        ? expectedTarget
+        : inputRevision;
+      if (!resolvedRoot || !Number.isSafeInteger(rootRevision) || rootRevision < 0) {
+        return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.ROOT_DOCUMENT_MISSING, inputCache);
+      }
+      if (rootRevision < expectedRootRevision) {
+        return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.ROOT_DOCUMENT_MISSING, inputCache);
+      }
+      if (rootRevision > expectedRootRevision) {
+        return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.REVISION_OVERSHOOT, inputCache);
+      }
+    }
+    if (expectedTarget != null && Number.isFinite(expectedTarget) && expectedTarget > inputRevision) {
+      return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.REVISION_GAP, inputCache);
     }
     return {
       ok: true,
@@ -92,19 +115,30 @@ export const applyFirestoreV2ResolvedChangeBatch = ({
   }
 
   const firstRevision = Number(batch[0]?.revision || 0);
-  if (expectedTarget != null && Number.isFinite(expectedTarget) && inputRevision > expectedTarget) {
+  if (!Number.isSafeInteger(firstRevision) || firstRevision < 0) {
+    return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.REVISION_GAP, inputCache);
+  }
+  if (expectedTarget != null && inputRevision > expectedTarget) {
     return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.CACHE_AHEAD, inputCache);
   }
   if (firstRevision <= inputRevision) {
     return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.REVISION_DUPLICATE, inputCache);
   }
-  if (expectedTarget != null && Number.isFinite(expectedTarget) && firstRevision > expectedTarget) {
+  if (expectedTarget != null && firstRevision > expectedTarget) {
     return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.REVISION_OVERSHOOT, inputCache);
   }
   if (firstRevision > inputRevision + 1) {
     return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.REVISION_GAP, inputCache);
   }
 
+  // Keep the last applied revision available for root exactness when the
+  // caller did not provide a target.  A malformed or stale final entry is
+  // rejected before candidate mutation.
+  const finalRevision = Number(batch.at(-1)?.revision || 0);
+  if (!Number.isSafeInteger(finalRevision) || finalRevision < inputRevision) {
+    return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.REVISION_DUPLICATE, inputCache);
+  }
+
   const candidate = {
     revision: inputRevision,
     documents: cloneDocuments(inputDocuments)
@@ -114,13 +148,16 @@ export const applyFirestoreV2ResolvedChangeBatch = ({
   for (let index = 0; index < batch.length; index += 1) {
     const change = batch[index] || {};
     const revision = Number(change.revision || 0);
+    if (!Number.isSafeInteger(revision) || revision < 0) {
+      return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.REVISION_GAP, inputCache);
+    }
     if (revision !== candidate.revision + 1) {
       const reason = revision <= candidate.revision
         ? FIRESTORE_V2_BOOTSTRAP_REASONS.REVISION_DUPLICATE
         : FIRESTORE_V2_BOOTSTRAP_REASONS.REVISION_GAP;
       return fail(reason, inputCache);
     }
-    if (expectedTarget != null && Number.isFinite(expectedTarget) && revision > expectedTarget) {
+    if (expectedTarget != null && revision > expectedTarget) {
       return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.REVISION_OVERSHOOT, inputCache);
     }
 
@@ -165,7 +202,8 @@ export const applyFirestoreV2ResolvedChangeBatch = ({
     if (change.rootChanged === true) {
       const rootDocument = resolvedDocuments.root;
       const rootRevision = Number(rootDocument?.revision || 0);
-      if (!rootDocument || !Number.isFinite(rootRevision) || rootRevision < revision) {
+      if (!rootDocument || !Number.isSafeInteger(rootRevision) || rootRevision < 0 ||
+        rootRevision < revision) {
         return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.ROOT_DOCUMENT_MISSING, inputCache);
       }
       rootChanged = true;
@@ -206,6 +244,27 @@ export const applyFirestoreV2ResolvedChangeBatch = ({
     candidate.revision = revision;
   }
 
+  // When a change resolves the root (or a caller supplied one alongside the
+  // batch), its revision is the proof that all document reads belong to the
+  // same authoritative point.  A behind, missing, or overshooting root is a
+  // bootstrap condition; the candidate is discarded atomically.
+  const resolvedRoot = resolvedDocuments?.root;
+  if (hasExpectedTarget || rootChanged || resolvedRoot !== undefined) {
+    const rootRevision = Number(resolvedRoot?.revision);
+    const expectedRootRevision = expectedTarget != null && Number.isFinite(expectedTarget)
+      ? expectedTarget
+      : finalRevision;
+    if (!resolvedRoot || !Number.isSafeInteger(rootRevision) || rootRevision < 0) {
+      return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.ROOT_DOCUMENT_MISSING, inputCache);
+    }
+    if (rootRevision < expectedRootRevision) {
+      return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.ROOT_DOCUMENT_MISSING, inputCache);
+    }
+    if (rootRevision > expectedRootRevision) {
+      return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.REVISION_OVERSHOOT, inputCache);
+    }
+  }
+
   if (rootChanged) {
     const rootDocument = resolvedDocuments.root;
     candidate.documents.root = {id: 'main', ...rootDocument};

package/src/firestore-v2.js

@@ -7,12 +7,21 @@ export {
   RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE,
   RECORD_TIMELABEL_CAPABILITY_OPERATION_CONFLICT_QUARANTINE,
   RECORD_TIMELABEL_CAPABILITY_STRICT_OPERATION_RESULTS,
+  RECORD_TIMELABEL_CAPABILITY_DETERMINISTIC_PLANNER,
+  RECORD_TIMELABEL_CAPABILITY_STRICT_READINESS,
+  RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE_V1,
+  RECORD_TIMELABEL_CLOUD_FAILURE_SCHEMA_VERSION,
   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,
+  RECORD_TIMELABEL_PLANNER_MODES,
+  RECORD_TIMELABEL_SAFE_ID_MAX_BYTES,
+  isRecordTimeLabelSafeDocumentId,
+  normalizeRecordTimeLabelImmutableId,
+  normalizeRecordTimeLabelPlannerId,
   RTL_SYNC_PROTOCOL_VERSION,
   buildFirestoreV2DocumentChangeSet,
   buildFirestoreV2DocumentsFromState,
@@ -33,6 +42,8 @@ export {
   normalizeRecordTimeLabelEnvelopeResponse,
   normalizeRecordTimeLabelOperationResults,
   planFirestoreV2OperationChanges,
+  planRecordTimeLabelDeterministicOperationChanges,
+  planFirestoreV2DeterministicOperationChanges,
   toRecordTimeLabelWireOperation,
   normalizeRecordTimeLabelDomainState,
   validateRecordTimeLabelOperationBatch