@recordtimelabel/core 0.1.10 → 0.2.0

package/README.md

@@ -1,34 +1,34 @@
-# @recordtimelabel/core
-
-Shared RecordTimeLabel data model, normalization, merge logic, operation reducer, and sync engine.
-
-## Scope
-
-This package is intentionally platform-neutral. It must not import React, Firebase, Chrome extension APIs, Electron APIs, or app-specific UI code.
-
-Current consumers:
-
-- `D:\Programming\RecordTimeLabel`
-- `D:\Programming\YouTwitchDownloader`
-
+# @recordtimelabel/core
+
+Shared RecordTimeLabel data model, normalization, merge logic, operation reducer, and sync engine.
+
+## Scope
+
+This package is intentionally platform-neutral. It must not import React, Firebase, Chrome extension APIs, Electron APIs, or app-specific UI code.
+
+Current consumers:
+
+- `D:\Programming\RecordTimeLabel`
+- `D:\Programming\YouTwitchDownloader`
+
 During local development an app can consume a sibling checkout with:
-
-```json
-"@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 release is:
 
 ```json
-"@recordtimelabel/core": "0.1.10"
+"@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:
+
+```json
+"@recordtimelabel/core": "0.2.0"
 ```
 
 If this checkout's `package.json` is ahead of the published version, publish the new package before updating consumers to that version.
-
-## Public API
-
-- `normalizeState(input)`
-- `normalizeRecords(records, options)`
+
+## Public API
+
+- `normalizeState(input)`
+- `normalizeRecords(records, options)`
 - `mergeLocalRemote({ localState, remoteState, pendingOps, clientId, now })`
 - `applyOperation(state, operation)`
 - `applyRecordTimeLabelOperation(state, operation)`
@@ -45,6 +45,13 @@ If this checkout's `package.json` is ahead of the published version, publish the
 - `buildFirestoreV2DocumentsFromState(state, options)`
 - `buildFirestoreV2DocumentChangeSet(previousDocuments, nextDocuments, options)`
 - `buildStateFromFirestoreV2Documents(documents, options)`
+- `validateRecordTimeLabelOperationBatch(body)`
+- `buildFirestoreV2OperationReadPlan(operations)`
+- `extendFirestoreV2OperationReadPlanWithRecords(readPlan, records)`
+- `planFirestoreV2OperationChanges({ documents, operations, localState, now })`
+- `estimateFirestoreV2WriteUnits(changes, overhead)`
+- `buildOperationsFromSnapshotDiff({ previousState, nextState, now, operationIdPrefix, batchSize })`
+- `RTL_SYNC_PROTOCOL_VERSION`
 - `hasMeaningfulRecordTimeLabelCloudState(data, options)`
 - `buildRecordTimeLabelContentFingerprint(data)`
 - `buildMigratedRecordTimeLabelV2State(legacyState, options)`
@@ -52,27 +59,27 @@ If this checkout's `package.json` is ahead of the published version, publish the
 - `RECORD_TIMELABEL_SYNC_MODES`
 - `createOperation(type, payload, options)`
 - `OPERATION_TYPES`
-
-## Firestore v1 Compatibility
-
-Phase 1 keeps the existing `users/{uid}` document shape:
-
-- `folders`
-- `records`
-- `groupOrder`
-- `folderOrder`
-- `expandedGroups`
-- `settings`
-
-The core also normalizes and preserves these compatibility metadata fields:
-
-- `rtlSyncMeta`
-- `deletedRecordTombstones`
-- `deletedFolderTombstones`
-
+
+## Firestore v1 Compatibility
+
+Phase 1 keeps the existing `users/{uid}` document shape:
+
+- `folders`
+- `records`
+- `groupOrder`
+- `folderOrder`
+- `expandedGroups`
+- `settings`
+
+The core also normalizes and preserves these compatibility metadata fields:
+
+- `rtlSyncMeta`
+- `deletedRecordTombstones`
+- `deletedFolderTombstones`
+
 Deletion must be represented by tombstones or operations. Do not reintroduce the old heuristic that treats "local exists but cloud missing for more than five minutes" as deletion.
 
-## Firestore v2 Preparation
+## Firestore v2 Gateway Contract
 
 The package exposes platform-neutral v2 document helpers so app adapters can share the same record/folder/settings/ops shape before wiring Firebase SDK or REST calls:
 
@@ -81,10 +88,10 @@ The package exposes platform-neutral v2 document helpers so app adapters can sha
 - `users/{uid}/recordTimeLabel/main/folders/{folderId}`: per-folder documents
 - `users/{uid}/recordTimeLabel/main/ops/{opId}`: pending operation documents
 
-These helpers do not import Firebase and do not perform network writes.
-
-## Test
-
-```bash
-npm test
-```
+The v2 validator, bounded read planner, pure mutation planner, cost estimator, and snapshot-diff batch builder are also platform-neutral. They do not import Firebase and do not perform network writes. Functions and clients must use this package instead of maintaining app-specific planner copies.
+
+## Test
+
+```bash
+npm test
+```

package/package.json

@@ -1,20 +1,20 @@
-{
-  "name": "@recordtimelabel/core",
-  "version": "0.1.10",
-  "type": "module",
-  "description": "Shared RecordTimeLabel data model, merge logic, operations, and sync engine.",
-  "main": "./src/index.js",
-  "exports": {
-    ".": "./src/index.js"
-  },
-  "scripts": {
-    "test": "node --test tests/*.test.mjs"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "files": [
-    "src",
-    "README.md"
-  ]
-}
+{
+  "name": "@recordtimelabel/core",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Shared RecordTimeLabel data model, merge logic, operations, and sync engine.",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ]
+}