@recordtimelabel/core 0.3.3 → 0.4.0

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 v2 gateway contract release is:
+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 durable identity and explicit entrypoint contract is prepared in package version `0.4.0` (publish it before updating consumers):
 
 ```json
-"@recordtimelabel/core": "0.3.2"
+"@recordtimelabel/core": "0.4.0"
 ```
 
 If this checkout's `package.json` is ahead of the published version, publish the new package before updating consumers to that version.
@@ -32,6 +32,9 @@ If this checkout's `package.json` is ahead of the published version, publish the
 - `mergeLocalRemote({ localState, remoteState, pendingOps, clientId, now })`
 - `applyOperation(state, operation)`
 - `applyRecordTimeLabelOperation(state, operation)`
+- `createRecordTimeLabelSyncEngine({ storage, cloud, session, client, clock, logger })`
+- `normalizeRecordTimeLabelOperationResults(operations, results)`
+- `normalizeRecordTimeLabelEnvelopeResponse(operations, response)`
 - `createSyncEngine({ storageAdapter, cloudAdapter, clientId, clock, logger })`
 - `createRecordTimeLabelController({ storageAdapter, cloudAdapter, clientId, settingKeys, clock, logger })`
 - `buildRecordTimeLabelSyncPayload({ data, previousCloudData, pendingOps, syncMode, clientId, now, groupOrderNormalizer })`
@@ -55,6 +58,8 @@ If this checkout's `package.json` is ahead of the published version, publish the
 - `RTL_SYNC_PROTOCOL_VERSION`
 - `hasMeaningfulRecordTimeLabelCloudState(data, options)`
 - `buildRecordTimeLabelContentFingerprint(data)`
+- `normalizeRecordTimeLabelDomainState(input)`
+- `migrateRecordTimeLabelExpandedGroups({ pendingOperations, currentView })`
 - `buildMigratedRecordTimeLabelV2State(legacyState, options)`
 - `RECORD_TIMELABEL_CLOUD_SCHEMAS`
 - `RECORD_TIMELABEL_SYNC_MODES`
@@ -63,6 +68,71 @@ If this checkout's `package.json` is ahead of the published version, publish the
 - `getActiveTrashEntries(entries, now)`
 - `RTL_TRASH_RETENTION_MS`
 
+The package exports four intentional entrypoints. The root (`@recordtimelabel/core`)
+keeps the complete backwards-compatible surface, `/protocol` contains only shared
+acknowledgement protocol helpers, `/firestore-v2` contains platform-neutral document
+and operation planners, and `/compat` contains the legacy `createSyncEngine` and
+`createRecordTimeLabelController` APIs.
+
+### Durable sync engine
+
+`createRecordTimeLabelSyncEngine` is the platform-neutral durable workspace API. Its storage port
+has `load()` and `save(workspace)` methods (adapters may consume the optional second
+`save(workspace, fenceContext)` argument to enforce the session/epoch atomically), and its cloud port has `bootstrap(context)`,
+`applyOperations(envelope, context)`, and `subscribe(listener, context)` methods. The session port
+provides `current()`, `subscribe(listener)`, and `isCurrent(sessionToken, uid, workspaceEpoch)`.
+
+The persisted workspace is versioned and contains only durable data:
+
+```js
+{
+  schemaVersion: 1,
+  ownerUid: 'user-id',
+  workspaceEpoch: 3,
+  remoteBaseline: { state, revision: 12, changeCursor: 'cursor-12' },
+  pendingOperations: [],
+  rejectedOperations: {},
+  syncMeta: {}
+}
+```
+
+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
+explicit identity does not match the current workspace is moved to
+`rejectedOperations` with a stable identity-mismatch reason before any cloud apply.
+
+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
+`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,
+content fingerprints, and Firestore v2 root documents exclude it. The migration helper consumes
+legacy `expandedGroups.update` operations in order, returns the resulting view projection, and is
+idempotent; legacy root fields are preserved verbatim when a compatibility document is rewritten
+so older clients can continue reading the view until they migrate.
+
+### Operation-result protocol
+
+The root package and `@recordtimelabel/core/protocol` export the shared acknowledgement
+normalizers. `normalizeRecordTimeLabelOperationResults(operations, results)` always returns one
+positional result per submitted operation. The only normalized statuses are `applied`, `noop`,
+`rejected`, and `retryable`; `retryable` is derived from that status, while the legacy `id` and
+`applied` fields remain available alongside `operationId`, `reason`, and `retryAfterMs`.
+
+`normalizeRecordTimeLabelEnvelopeResponse(operations, response)` prefers an explicit
+`operationResults` array. An explicitly provided non-array or mismatched array, and a failed
+envelope without results, throw an error whose `code` is `operation_result_count_mismatch`, so
+callers can reject the entire acknowledgement before changing durable state.
+
+During the compatibility window, a successful legacy envelope that omits the
+`operationResults` property acknowledges every submitted operation as `applied`. Failed envelopes
+and envelopes that explicitly provide a malformed result value never receive that fallback. Keep
+the fallback until all deployed gateways and clients send and consume the explicit array; removing
+it requires a coordinated breaking release.
+
 ## Firestore v1 Compatibility
 
 Phase 1 keeps the existing `users/{uid}` document shape:

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@recordtimelabel/core",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "type": "module",
   "description": "Shared RecordTimeLabel data model, merge logic, operations, and sync engine.",
   "main": "./src/index.js",
   "exports": {
-    ".": "./src/index.js"
+    ".": "./src/index.js",
+    "./protocol": "./src/protocol.js",
+    "./firestore-v2": "./src/firestore-v2.js",
+    "./compat": "./src/compat.js"
   },
   "scripts": {
     "test": "node --test tests/*.test.mjs"

package/src/compat.js

@@ -0,0 +1,8 @@
+// Compatibility surface for the pre-durable sync/controller APIs.  Keeping
+// these exports explicit lets adapters migrate without pulling in unrelated
+// Firestore-v2 planners.
+export {createRecordTimeLabelController, createSyncEngine} from './index.js';
+
+import {createRecordTimeLabelController, createSyncEngine} from './index.js';
+
+export default {createSyncEngine, createRecordTimeLabelController};

package/src/firestore-v2.js

@@ -0,0 +1,27 @@
+// Platform-neutral Firestore v2 planning and document helpers.  Runtime
+// adapters (Firebase SDKs, browser storage, and UI bindings) belong outside
+// the core package and should import this explicit surface.
+export {
+  FIRESTORE_V2_SETTINGS_DOC_ID,
+  OPERATION_TYPES,
+  RECORD_TIMELABEL_CLOUD_SCHEMAS,
+  RECORD_TIMELABEL_OPERATION_RESULT_STATUSES,
+  RTL_MAX_OPERATIONS_PER_REQUEST,
+  RTL_MAX_REQUEST_BYTES,
+  RTL_MAX_TARGET_WRITES,
+  RTL_SYNC_PROTOCOL_VERSION,
+  buildFirestoreV2DocumentChangeSet,
+  buildFirestoreV2DocumentsFromState,
+  buildFirestoreV2LogicalPaths,
+  buildFirestoreV2OperationReadPlan,
+  buildOperationsFromSnapshotDiff,
+  buildStateFromFirestoreV2Documents,
+  estimateFirestoreV2WriteUnits,
+  extendFirestoreV2OperationReadPlanWithRecords,
+  extendFirestoreV2OperationReadPlanWithTrash,
+  normalizeRecordTimeLabelEnvelopeResponse,
+  normalizeRecordTimeLabelOperationResults,
+  planFirestoreV2OperationChanges,
+  normalizeRecordTimeLabelDomainState,
+  validateRecordTimeLabelOperationBatch
+} from './index.js';