@korajs/store 0.6.0 → 1.0.0-beta.1

package/dist/index.js

@@ -1,56 +1,67 @@
+import {
+  exportBackup,
+  readBackupManifest,
+  restoreBackup,
+  verifyBackupChecksum
+} from "./chunk-X57MWW35.js";
 import {
   decodeAuditExport,
   readAuditExportManifest,
   verifyAuditExportChecksum
-} from "./chunk-AGN3CIPB.js";
+} from "./chunk-FFYA7J5H.js";
 import {
   persistedAuditTraceFromEvent
 } from "./chunk-MYSJN3DF.js";
+import {
+  BlobIntegrityError,
+  MemoryBlobStore
+} from "./chunk-W4MTTNEZ.js";
 import {
   InvalidStateTransitionError,
   allocateNextSequenceInTransaction,
   allocateNextSequenceNumber,
   buildCountQuery,
+  buildFieldFastForwardUpdateQuery,
   buildInsertQuery,
   buildLwwSoftDeleteQuery,
-  buildLwwUpdateQuery,
   buildSelectQuery,
   buildSoftDeleteQuery,
   buildUpdateQuery,
   executeDelete,
   executeInsert,
   executeUpdate,
+  fieldVersionsForFields,
   isIncomingNewerThanRow,
+  parseFieldVersions,
   readSequenceNumber,
+  resolvePerFieldLww,
+  serializeFieldVersions,
   serializeRowVersion,
   validateStateTransition,
   validateUpdateStateMachine
-} from "./chunk-7BPETY5Y.js";
-import {
-  AdapterError,
-  PersistenceError,
-  QueryError,
-  RecordNotFoundError,
-  StoreNotOpenError,
-  WorkerInitError,
-  WorkerTimeoutError
-} from "./chunk-LAWV6CFH.js";
-import {
-  exportBackup,
-  readBackupManifest,
-  restoreBackup,
-  verifyBackupChecksum
-} from "./chunk-EZSTD2XC.js";
+} from "./chunk-ZLWAYQEQ.js";
 import {
   decodeRichtext,
+  decodeRichtextFieldsFromOpData,
   deserializeOperationWithCollection,
   deserializeRecord,
   encodeRichtext,
+  encodeRichtextFieldsForOpData,
   richtextStatesEqual,
   richtextToPlainText,
   serializeOperation,
   serializeRecord
-} from "./chunk-56LL4XP6.js";
+} from "./chunk-6NKLDBTY.js";
+import {
+  AdapterError,
+  OptimisticLockError,
+  PersistenceError,
+  QueryError,
+  RecordNotFoundError,
+  StoreNotOpenError,
+  WorkerInitError,
+  WorkerTimeoutError
+} from "./chunk-QL2XVZRN.js";
 
 // src/compaction/types.ts
 var COMPACTION_BASELINE_META_KEY = "compaction_baseline_at";
@@ -195,7 +206,7 @@ async function saveDeltaCursor(adapter, cursor) {
 // src/store/store.ts
 import {
   CausalTracker,
-  HybridLogicalClock as HybridLogicalClock2,
+  HybridLogicalClock as HybridLogicalClock3,
   createVersionVector as createVersionVector3,
   generateUUIDv7 as generateUUIDv73,
   migrationStepsToSQL
@@ -203,7 +214,7 @@ import {
 
 // src/collection/collection.ts
 var Collection = class {
-  constructor(name, definition, schema, adapter, clock, nodeId, allocateSequenceNumber, onMutation, relationEnforcer, mutationHandler, causalTracker) {
+  constructor(name, definition, schema, adapter, clock, nodeId, allocateSequenceNumber, onMutation, relationEnforcer, mutationHandler, causalTracker, secretKeyProvider) {
     this.name = name;
     this.definition = definition;
     this.schema = schema;
@@ -215,6 +226,7 @@ var Collection = class {
     this.relationEnforcer = relationEnforcer;
     this.mutationHandler = mutationHandler;
     this.causalTracker = causalTracker;
+    this.secretKeyProvider = secretKeyProvider;
   }
   name;
   definition;
@@ -227,6 +239,7 @@ var Collection = class {
   relationEnforcer;
   mutationHandler;
   causalTracker;
+  secretKeyProvider;
   mutationContext() {
     return {
       collection: this.name,
@@ -239,7 +252,8 @@ var Collection = class {
       onMutation: this.onMutation,
       relationEnforcer: this.relationEnforcer,
       causalTracker: this.causalTracker,
-      inTransaction: false
+      inTransaction: false,
+      secretKeyProvider: this.secretKeyProvider
     };
   }
   async insert(data) {
@@ -885,7 +899,9 @@ function applyOperationToMemory(state, op, schema) {
       }
       colMap.set(op.recordId, {
         id: op.recordId,
-        fields: { ...op.data },
+        // op.data stores binary richtext as tagged JSON; snapshots must
+        // expose record-shaped values (Uint8Array/string).
+        fields: decodeRichtextFieldsFromOpData(op.data, definition.fields),
         deleted: false,
         createdAt: wallTime,
         updatedAt: wallTime
@@ -896,9 +912,10 @@ function applyOperationToMemory(state, op, schema) {
       if (!op.data) {
         return;
       }
+      const decodedData = decodeRichtextFieldsFromOpData(op.data, definition.fields);
       const existing = colMap.get(op.recordId);
       if (existing && !existing.deleted) {
-        existing.fields = { ...existing.fields, ...op.data };
+        existing.fields = { ...existing.fields, ...decodedData };
         existing.updatedAt = wallTime;
         break;
       }
@@ -907,7 +924,7 @@ function applyOperationToMemory(state, op, schema) {
       }
       colMap.set(op.recordId, {
         id: op.recordId,
-        fields: { ...op.data },
+        fields: decodedData,
         deleted: false,
         createdAt: wallTime,
         updatedAt: wallTime
@@ -1458,6 +1475,137 @@ var SubscriptionManager = class {
   }
 };
 
+// src/sync/rebase-unsynced-operations.ts
+import { HybridLogicalClock as HybridLogicalClock2, MAX_LOGICAL } from "@korajs/core";
+import { computeOperationId } from "@korajs/core/internal";
+var LOGICAL_COUNTER_LIMIT = MAX_LOGICAL + 1;
+function emptyResult() {
+  return { operations: [], idMapping: {}, rebasedCount: 0, newMaxTimestamp: null };
+}
+async function rebaseUnsyncedOperationsInLog(adapter, schema, unsyncedOpIds, correctedNowMs) {
+  if (unsyncedOpIds.length === 0) {
+    return emptyResult();
+  }
+  const rebaseIds = new Set(unsyncedOpIds);
+  const rebased = [];
+  let maxOtherSerializedTs = null;
+  for (const collectionName of Object.keys(schema.collections)) {
+    const rows = await adapter.query(`SELECT * FROM _kora_ops_${collectionName}`);
+    for (const row of rows) {
+      if (rebaseIds.has(row.id)) {
+        rebased.push(deserializeOperationWithCollection(row, collectionName));
+      } else if (maxOtherSerializedTs === null || row.timestamp > maxOtherSerializedTs) {
+        maxOtherSerializedTs = row.timestamp;
+      }
+    }
+  }
+  if (rebased.length === 0) {
+    return emptyResult();
+  }
+  const maxOtherWallTime = maxOtherSerializedTs === null ? Number.NEGATIVE_INFINITY : HybridLogicalClock2.deserialize(maxOtherSerializedTs).wallTime;
+  const baseWallTime = Math.max(correctedNowMs, maxOtherWallTime + 1);
+  rebased.sort((a, b) => HybridLogicalClock2.compare(a.timestamp, b.timestamp));
+  const newTimestamps = rebased.map((op, i) => ({
+    // Spill into wallTime past the 5-digit logical serialization limit so the
+    // serialized order stays correct even for enormous offline queues.
+    wallTime: baseWallTime + Math.floor(i / LOGICAL_COUNTER_LIMIT),
+    logical: i % LOGICAL_COUNTER_LIMIT,
+    nodeId: op.nodeId
+  }));
+  const idMapping = {};
+  const newIds = [];
+  for (let i = 0; i < rebased.length; i++) {
+    const op = rebased[i];
+    const ts = newTimestamps[i];
+    if (!op || !ts) {
+      continue;
+    }
+    const input = {
+      nodeId: op.nodeId,
+      type: op.type,
+      collection: op.collection,
+      recordId: op.recordId,
+      data: op.data,
+      previousData: op.previousData,
+      sequenceNumber: op.sequenceNumber,
+      causalDeps: op.causalDeps,
+      schemaVersion: op.schemaVersion,
+      ...op.atomicOps !== void 0 ? { atomicOps: op.atomicOps } : {}
+    };
+    const newId = await computeOperationId(input, HybridLogicalClock2.serialize(ts));
+    idMapping[op.id] = newId;
+    newIds.push(newId);
+  }
+  const newOperations = [];
+  for (let i = 0; i < rebased.length; i++) {
+    const op = rebased[i];
+    const ts = newTimestamps[i];
+    const newId = newIds[i];
+    if (!op || !ts || newId === void 0) {
+      continue;
+    }
+    newOperations.push({
+      ...op,
+      id: newId,
+      timestamp: ts,
+      causalDeps: op.causalDeps.map((dep) => idMapping[dep] ?? dep)
+    });
+  }
+  await adapter.transaction(async (tx) => {
+    for (let i = 0; i < rebased.length; i++) {
+      const oldOp = rebased[i];
+      const newOp = newOperations[i];
+      if (!oldOp || !newOp) {
+        continue;
+      }
+      const opsTable = `_kora_ops_${oldOp.collection}`;
+      await tx.execute(`DELETE FROM ${opsTable} WHERE id = ?`, [oldOp.id]);
+      const opInsert = buildInsertQuery(
+        opsTable,
+        serializeOperation(newOp)
+      );
+      await tx.execute(opInsert.sql, opInsert.params);
+      const oldVersion = serializeRowVersion(oldOp.timestamp);
+      const newVersion = serializeRowVersion(newOp.timestamp);
+      await tx.execute(
+        `UPDATE ${oldOp.collection} SET _version = ?, _updated_at = ? WHERE id = ? AND _version = ?`,
+        [newVersion, newOp.timestamp.wallTime, oldOp.recordId, oldVersion]
+      );
+      const rows = await tx.query(
+        `SELECT _field_versions FROM ${oldOp.collection} WHERE id = ?`,
+        [oldOp.recordId]
+      );
+      const fieldVersions = parseFieldVersions(rows[0]?._field_versions);
+      let changed = false;
+      for (const [field, version] of Object.entries(fieldVersions)) {
+        if (version === oldVersion) {
+          fieldVersions[field] = newVersion;
+          changed = true;
+        }
+      }
+      if (changed) {
+        await tx.execute(`UPDATE ${oldOp.collection} SET _field_versions = ? WHERE id = ?`, [
+          serializeFieldVersions(fieldVersions),
+          oldOp.recordId
+        ]);
+      }
+      if (oldOp.type === "insert") {
+        await tx.execute(
+          `UPDATE ${oldOp.collection} SET _created_at = ? WHERE id = ? AND _created_at = ?`,
+          [newOp.timestamp.wallTime, oldOp.recordId, oldOp.timestamp.wallTime]
+        );
+      }
+    }
+  });
+  const newMaxTimestamp = newTimestamps[newTimestamps.length - 1] ?? null;
+  return {
+    operations: newOperations,
+    idMapping,
+    rebasedCount: newOperations.length,
+    newMaxTimestamp
+  };
+}
+
 // src/transaction/transaction-context.ts
 import {
   createOperation as createOperation2,
@@ -1607,7 +1755,9 @@ var TransactionContext = class {
         type: "insert",
         collection: collectionName,
         recordId,
-        data: { ...validated },
+        // Binary richtext values are tagged as canonical JSON before the
+        // operation is content-hashed (see encodeRichtextFieldsForOpData).
+        data: encodeRichtextFieldsForOpData(validated, definition.fields),
         previousData: null,
         sequenceNumber,
         causalDeps,
@@ -1678,8 +1828,10 @@ var TransactionContext = class {
         type: "update",
         collection: collectionName,
         recordId: id,
-        data: { ...resolvedData },
-        previousData,
+        // Binary richtext values (new and previous) are tagged as canonical
+        // JSON before the operation is content-hashed.
+        data: encodeRichtextFieldsForOpData(resolvedData, definition.fields),
+        previousData: encodeRichtextFieldsForOpData(previousData, definition.fields),
         sequenceNumber,
         causalDeps,
         schemaVersion: this.config.schema.version,
@@ -1786,14 +1938,16 @@ var TransactionContext = class {
       if (entry.operation.type === "insert" && entry.operation.data) {
         record = {
           id,
-          ...entry.operation.data,
+          // op.data stores binary richtext as tagged JSON; the effective
+          // record must expose record-shaped values (Uint8Array/string).
+          ...decodeRichtextFieldsFromOpData(entry.operation.data, definition.fields),
           createdAt: entry.operation.timestamp.wallTime,
           updatedAt: entry.operation.timestamp.wallTime
         };
       } else if (entry.operation.type === "update" && entry.operation.data && record) {
         record = {
           ...record,
-          ...entry.operation.data,
+          ...decodeRichtextFieldsFromOpData(entry.operation.data, definition.fields),
           updatedAt: entry.operation.timestamp.wallTime
         };
       } else if (entry.operation.type === "delete") {
@@ -1873,6 +2027,7 @@ var Store = class {
   localMutationHandler;
   relationEnforcer = null;
   causalTracker = null;
+  secretKeyProvider;
   constructor(config) {
     this.schema = config.schema;
     this.adapter = config.adapter;
@@ -1881,6 +2036,7 @@ var Store = class {
     this.isolation = config.isolation ?? "shared";
     this.emitter = config.emitter ?? null;
     this.localMutationHandler = config.localMutationHandler ?? null;
+    this.secretKeyProvider = config.secretKeyProvider;
     this.subscriptionManager = new SubscriptionManager({
       onQuerySubscribed: config.onQuerySubscribed
     });
@@ -1893,7 +2049,7 @@ var Store = class {
     await this.adapter.open(this.schema);
     await this.runMigrationsIfNeeded();
     this.nodeId = await this.loadOrGenerateNodeId();
-    this.clock = new HybridLogicalClock2(this.nodeId);
+    this.clock = new HybridLogicalClock3(this.nodeId);
     this.causalTracker = new CausalTracker();
     this.sequenceManager = new SequenceManager(this.adapter, this.nodeId);
     this.sequenceNumber = await this.loadSequenceNumber();
@@ -1923,7 +2079,8 @@ var Store = class {
         },
         this.relationEnforcer,
         this.localMutationHandler,
-        this.causalTracker
+        this.causalTracker,
+        this.secretKeyProvider
       );
       this.collections.set(name, col);
     }
@@ -1980,6 +2137,14 @@ var Store = class {
   /**
    * Get the node ID for this store instance.
    */
+  /**
+   * Records the offset between server time and this device's clock
+   * (serverTime - localTime), learned at sync handshake. Lets the store's HLC
+   * validate remote timestamps correctly even when the local clock is wrong.
+   */
+  setClockReferenceOffset(offsetMs) {
+    this.clock?.setReferenceOffset(offsetMs);
+  }
   getNodeId() {
     this.ensureOpen();
     return this.nodeId;
@@ -2006,45 +2171,158 @@ var Store = class {
     if (this.clock) {
       this.clock.receive(op.timestamp);
     }
-    const remoteVersion = serializeRowVersion(op.timestamp);
-    const wallTime = op.timestamp.wallTime;
+    const materializeTimestamp = options?.materializeTimestamp ?? op.timestamp;
+    const remoteVersion = serializeRowVersion(materializeTimestamp);
+    const wallTime = materializeTimestamp.wallTime;
+    const materializeSource = options?.materializeData ?? op.data;
     await this.adapter.transaction(async (tx) => {
-      if (op.type === "insert" && op.data) {
+      const checkGuard = (row) => {
+        const guard = options?.guardRowState;
+        if (!guard) {
+          return;
+        }
+        const version = typeof row?._version === "string" ? row._version : null;
+        const fieldVersions = typeof row?._field_versions === "string" ? row._field_versions : null;
+        if (version !== guard.version || fieldVersions !== guard.fieldVersions) {
+          throw new OptimisticLockError(collection, op.recordId);
+        }
+      };
+      if (op.type === "insert" && materializeSource) {
+        const serializedData = serializeRecord(materializeSource, definition.fields);
         const existing2 = await tx.query(
-          `SELECT _updated_at, _version FROM ${collection} WHERE id = ?`,
+          `SELECT _updated_at, _version, _field_versions, _deleted FROM ${collection} WHERE id = ?`,
           [op.recordId]
         );
         const row = existing2[0];
-        if (row && !isIncomingNewerThanRow(op.timestamp, row)) {
-        } else {
-          const serializedData = serializeRecord(op.data, definition.fields);
+        checkGuard(row);
+        if (!row) {
           const record = {
             id: op.recordId,
             ...serializedData,
             _created_at: wallTime,
             _updated_at: wallTime,
-            _version: remoteVersion
+            _version: remoteVersion,
+            // Stamp every inserted field so per-field LWW has a real baseline.
+            _field_versions: serializeFieldVersions(
+              fieldVersionsForFields(Object.keys(serializedData), remoteVersion)
+            )
           };
           const insertQuery = buildInsertQuery(collection, record);
           await tx.execute(insertQuery.sql, insertQuery.params);
+          await this.foldOrphanedOperations(tx, collection, definition, op.recordId);
+        } else if (row._deleted === 1) {
+          if (isIncomingNewerThanRow(materializeTimestamp, row)) {
+            const fieldChanges = {
+              ...serializedData,
+              _deleted: 0,
+              _field_versions: serializeFieldVersions(
+                fieldVersionsForFields(Object.keys(serializedData), remoteVersion)
+              )
+            };
+            const upsert = buildFieldFastForwardUpdateQuery(
+              collection,
+              op.recordId,
+              fieldChanges,
+              remoteVersion,
+              wallTime,
+              { maxCreatedAt: wallTime }
+            );
+            await tx.execute(upsert.sql, upsert.params);
+          }
+        } else {
+          const currentVersions = parseFieldVersions(row._field_versions);
+          const rowVersion = typeof row._version === "string" ? row._version : void 0;
+          const fieldChanges = {};
+          let fieldVersionsJson;
+          if (options?.forceMaterialize) {
+            const merged = { ...currentVersions };
+            for (const field of Object.keys(serializedData)) {
+              fieldChanges[field] = serializedData[field];
+              merged[field] = remoteVersion;
+            }
+            fieldVersionsJson = serializeFieldVersions(merged);
+          } else {
+            const { winners, merged } = resolvePerFieldLww(
+              currentVersions,
+              Object.keys(serializedData),
+              remoteVersion,
+              rowVersion
+            );
+            for (const field of winners) {
+              fieldChanges[field] = serializedData[field];
+            }
+            fieldVersionsJson = serializeFieldVersions(merged);
+          }
+          const upsert = buildFieldFastForwardUpdateQuery(
+            collection,
+            op.recordId,
+            { ...fieldChanges, _field_versions: fieldVersionsJson },
+            remoteVersion,
+            wallTime,
+            { maxCreatedAt: wallTime }
+          );
+          await tx.execute(upsert.sql, upsert.params);
         }
-      } else if (op.type === "update" && op.data) {
-        const serializedChanges = serializeRecord(op.data, definition.fields);
-        const updatePayload = {
-          ...serializedChanges,
-          _updated_at: wallTime,
-          _version: remoteVersion
-        };
-        if (options?.reactivateIfDeleted) {
-          updatePayload._deleted = 0;
-        }
-        const updateQuery = buildLwwUpdateQuery(
-          collection,
-          op.recordId,
-          updatePayload,
-          remoteVersion
+      } else if (op.type === "update" && materializeSource) {
+        const serializedChanges = serializeRecord(materializeSource, definition.fields);
+        const changedFields = Object.keys(serializedChanges);
+        const currentRows = await tx.query(
+          `SELECT _version, _field_versions FROM ${collection} WHERE id = ?`,
+          [op.recordId]
         );
-        await tx.execute(updateQuery.sql, updateQuery.params);
+        const currentRow = currentRows[0];
+        checkGuard(currentRow);
+        if (currentRow) {
+          const currentVersions = parseFieldVersions(currentRow._field_versions);
+          const rowVersion = typeof currentRow._version === "string" ? currentRow._version : void 0;
+          if (options?.forceMaterialize) {
+            const merged = { ...currentVersions };
+            for (const field of changedFields) {
+              merged[field] = remoteVersion;
+            }
+            const fieldChanges = {
+              ...serializedChanges,
+              _field_versions: serializeFieldVersions(merged)
+            };
+            if (options?.reactivateIfDeleted) {
+              fieldChanges._deleted = 0;
+            }
+            const forceQuery = buildFieldFastForwardUpdateQuery(
+              collection,
+              op.recordId,
+              fieldChanges,
+              remoteVersion,
+              wallTime
+            );
+            await tx.execute(forceQuery.sql, forceQuery.params);
+          } else {
+            const { winners, merged } = resolvePerFieldLww(
+              currentVersions,
+              changedFields,
+              remoteVersion,
+              rowVersion
+            );
+            if (winners.length > 0 || options?.reactivateIfDeleted) {
+              const winningChanges = {
+                _field_versions: serializeFieldVersions(merged)
+              };
+              for (const field of winners) {
+                winningChanges[field] = serializedChanges[field];
+              }
+              if (options?.reactivateIfDeleted) {
+                winningChanges._deleted = 0;
+              }
+              const forceQuery = buildFieldFastForwardUpdateQuery(
+                collection,
+                op.recordId,
+                winningChanges,
+                remoteVersion,
+                wallTime
+              );
+              await tx.execute(forceQuery.sql, forceQuery.params);
+            }
+          }
+        }
       } else if (op.type === "delete") {
         const deleteQuery = buildLwwSoftDeleteQuery(
           collection,
@@ -2072,6 +2350,67 @@ var Store = class {
     this.subscriptionManager.notify(collection, op);
     return "applied";
   }
+  /**
+   * Materialize update/delete operations that were logged for a record BEFORE
+   * its insert arrived (reordered delivery). Runs inside the insert's write
+   * transaction, folding each orphan in timestamp order through the exact
+   * per-field LWW / LWW-delete rules the normal apply paths use, so the final
+   * row state equals what a device that received the operations in causal
+   * order computed. Called only when the insert created a previously-absent
+   * row — in that case every logged update/delete for the record is
+   * necessarily an orphan (rows are soft-deleted, never removed, so a row
+   * that is absent now was never materialized).
+   */
+  async foldOrphanedOperations(tx, collection, definition, recordId) {
+    const orphanRows = await tx.query(
+      `SELECT * FROM _kora_ops_${collection} WHERE record_id = ? AND type IN ('update', 'delete')`,
+      [recordId]
+    );
+    if (orphanRows.length === 0) {
+      return;
+    }
+    const orphans = orphanRows.map((r) => deserializeOperationWithCollection(r, collection)).sort((a, b) => HybridLogicalClock3.compare(a.timestamp, b.timestamp));
+    for (const orphan of orphans) {
+      const orphanVersion = serializeRowVersion(orphan.timestamp);
+      const orphanWall = orphan.timestamp.wallTime;
+      if (orphan.type === "update" && orphan.data) {
+        const orphanChanges = serializeRecord(orphan.data, definition.fields);
+        const rows = await tx.query(
+          `SELECT _version, _field_versions FROM ${collection} WHERE id = ?`,
+          [recordId]
+        );
+        const current = rows[0];
+        if (!current) {
+          continue;
+        }
+        const { winners, merged } = resolvePerFieldLww(
+          parseFieldVersions(current._field_versions),
+          Object.keys(orphanChanges),
+          orphanVersion,
+          typeof current._version === "string" ? current._version : void 0
+        );
+        if (winners.length > 0) {
+          const winningChanges = {
+            _field_versions: serializeFieldVersions(merged)
+          };
+          for (const field of winners) {
+            winningChanges[field] = orphanChanges[field];
+          }
+          const query = buildFieldFastForwardUpdateQuery(
+            collection,
+            recordId,
+            winningChanges,
+            orphanVersion,
+            orphanWall
+          );
+          await tx.execute(query.sql, query.params);
+        }
+      } else if (orphan.type === "delete") {
+        const query = buildLwwSoftDeleteQuery(collection, recordId, orphanWall, orphanVersion);
+        await tx.execute(query.sql, query.params);
+      }
+    }
+  }
   /**
    * Get operations from a node within a sequence number range.
    * Implements the OperationLog interface for computeDelta.
@@ -2157,7 +2496,7 @@ var Store = class {
    */
   async exportAudit(options) {
     this.ensureOpen();
-    const { exportAudit: doExport } = await import("./export-audit-5GV6VRDZ.js");
+    const { exportAudit: doExport } = await import("./export-audit-AJ7RORNK.js");
     return doExport(this.adapter, this.schema, this.nodeId, this.schema.version, options);
   }
   /**
@@ -2202,7 +2541,8 @@ var Store = class {
       relationEnforcer: this.relationEnforcer,
       causalTracker: this.causalTracker,
       inTransaction: options?.inTransaction ?? false,
-      extraCausalDeps: options?.extraCausalDeps
+      extraCausalDeps: options?.extraCausalDeps,
+      secretKeyProvider: this.secretKeyProvider
     };
   }
   /**
@@ -2227,6 +2567,31 @@ var Store = class {
       deleted: row._deleted === 1
     };
   }
+  /**
+   * Raw version state of a materialized row, for optimistic-concurrency guarded
+   * applies: capture this snapshot before computing a merge, pass it as
+   * `guardRowState`, and the apply refuses to write if the row changed since.
+   * Returns null when no row exists (which is itself a valid guard state — the
+   * apply then requires the row to still be absent).
+   */
+  async getRowVersionState(collection, recordId) {
+    this.ensureOpen();
+    if (!this.schema.collections[collection]) {
+      return null;
+    }
+    const rows = await this.adapter.query(
+      `SELECT _version, _field_versions FROM ${collection} WHERE id = ?`,
+      [recordId]
+    );
+    const row = rows[0];
+    if (!row) {
+      return null;
+    }
+    return {
+      version: typeof row._version === "string" ? row._version : null,
+      fieldVersions: typeof row._field_versions === "string" ? row._field_versions : null
+    };
+  }
   /**
    * Latest operation from this device for a record (used for delete-vs-update merge on sync).
    */
@@ -2269,6 +2634,30 @@ var Store = class {
       (nodeId, fromSeq, toSeq) => this.getOperationRange(nodeId, fromSeq, toSeq)
     );
   }
+  /**
+   * Re-stamp never-acknowledged local operations after a fast device clock was
+   * corrected, so sync can resume immediately. Safe because unacknowledged
+   * operations are private to this device (like unpushed git commits);
+   * acknowledged/shared operations are immutable and never touched.
+   *
+   * After the rewrite the store's HLC is advanced past the highest new
+   * timestamp so subsequent local writes keep sorting after the rebased ops.
+   * No data-change notifications are emitted: materialized values are
+   * unchanged, only version stamps move.
+   */
+  async rebaseUnsyncedOperations(unsyncedOpIds, correctedNowMs) {
+    this.ensureOpen();
+    const result = await rebaseUnsyncedOperationsInLog(
+      this.adapter,
+      this.schema,
+      unsyncedOpIds,
+      correctedNowMs
+    );
+    if (result.newMaxTimestamp && this.clock) {
+      this.clock.advanceTo(result.newMaxTimestamp);
+    }
+    return result;
+  }
   /**
    * Count of local operations ahead of the server version vector.
    */
@@ -2318,7 +2707,7 @@ var Store = class {
     let latest = null;
     for (const row of rows) {
       const op = deserializeOperationWithCollection(row, collection);
-      if (!latest || HybridLogicalClock2.compare(op.timestamp, latest.timestamp) > 0) {
+      if (!latest || HybridLogicalClock3.compare(op.timestamp, latest.timestamp) > 0) {
         latest = op;
       }
     }
@@ -2402,7 +2791,7 @@ var Store = class {
    */
   async exportBackup(options) {
     this.ensureOpen();
-    const { exportBackup: doExport } = await import("./backup-JN3LB4YT.js");
+    const { exportBackup: doExport } = await import("./backup-ZV4Y424B.js");
     return doExport(this.adapter, this.schema, this.nodeId, this.schema.version, options);
   }
   /**
@@ -2414,7 +2803,7 @@ var Store = class {
    */
   async importBackup(data, options) {
     this.ensureOpen();
-    const { restoreBackup: doRestore } = await import("./backup-JN3LB4YT.js");
+    const { restoreBackup: doRestore } = await import("./backup-ZV4Y424B.js");
     return doRestore(this.adapter, this.schema, data, options);
   }
   /**
@@ -3044,12 +3433,519 @@ function asRichTextSyncEngine(engine) {
   }
   return engine;
 }
+
+// src/blob/opfs-blob-store.ts
+import { createBlobRef, hashBlob } from "@korajs/core";
+var OpfsBlobStore = class {
+  constructor(dir) {
+    this.dir = dir;
+  }
+  dir;
+  shardFor(hash) {
+    return hash.slice(0, 2);
+  }
+  async put(bytes, metadata = {}) {
+    const ref = await createBlobRef(bytes, metadata);
+    const shard = this.shardFor(ref.hash);
+    if (await this.dir.has(shard, ref.hash)) {
+      return ref;
+    }
+    const out = new Uint8Array(bytes.byteLength);
+    out.set(bytes);
+    await this.dir.write(shard, ref.hash, out);
+    return ref;
+  }
+  async get(hash) {
+    const bytes = await this.dir.read(this.shardFor(hash), hash);
+    if (bytes === null) {
+      return null;
+    }
+    const actual = await hashBlob(bytes);
+    if (actual !== hash) {
+      throw new BlobIntegrityError(hash, actual);
+    }
+    return bytes;
+  }
+  async has(hash) {
+    return this.dir.has(this.shardFor(hash), hash);
+  }
+  async delete(hash) {
+    return this.dir.remove(this.shardFor(hash), hash);
+  }
+  async size() {
+    return this.dir.count();
+  }
+  async list() {
+    return this.dir.keys();
+  }
+};
+function getStorageManager() {
+  const nav = globalThis.navigator;
+  if (!nav?.storage || typeof nav.storage.getDirectory !== "function") {
+    throw new Error(
+      "OPFS is unavailable in this environment. The OPFS blob store requires a browser with Origin Private File System support; use MemoryBlobStore or a server-side store elsewhere."
+    );
+  }
+  return nav.storage;
+}
+function isNotFoundError(error) {
+  return typeof error === "object" && error !== null && error.name === "NotFoundError";
+}
+async function createOpfsBlobDirectory(rootDirName = "kora-blobs") {
+  const storage = getStorageManager();
+  if (typeof storage.persist === "function") {
+    try {
+      await storage.persist();
+    } catch {
+    }
+  }
+  const opfsRoot = await storage.getDirectory();
+  const root = await opfsRoot.getDirectoryHandle(rootDirName, { create: true });
+  async function shardHandle(shard, create) {
+    try {
+      return await root.getDirectoryHandle(shard, { create });
+    } catch (error) {
+      if (isNotFoundError(error)) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  return {
+    async read(shard, name) {
+      const dir = await shardHandle(shard, false);
+      if (!dir) {
+        return null;
+      }
+      let handle;
+      try {
+        handle = await dir.getFileHandle(name, { create: false });
+      } catch (error) {
+        if (isNotFoundError(error)) {
+          return null;
+        }
+        throw error;
+      }
+      const file = await handle.getFile();
+      return new Uint8Array(await file.arrayBuffer());
+    },
+    async write(shard, name, bytes) {
+      const dir = await root.getDirectoryHandle(shard, { create: true });
+      const handle = await dir.getFileHandle(name, { create: true });
+      const writable = await handle.createWritable({ keepExistingData: false });
+      try {
+        await writable.write(bytes);
+      } finally {
+        await writable.close();
+      }
+    },
+    async remove(shard, name) {
+      const dir = await shardHandle(shard, false);
+      if (!dir) {
+        return false;
+      }
+      try {
+        await dir.removeEntry(name);
+        return true;
+      } catch (error) {
+        if (isNotFoundError(error)) {
+          return false;
+        }
+        throw error;
+      }
+    },
+    async has(shard, name) {
+      const dir = await shardHandle(shard, false);
+      if (!dir) {
+        return false;
+      }
+      try {
+        await dir.getFileHandle(name, { create: false });
+        return true;
+      } catch (error) {
+        if (isNotFoundError(error)) {
+          return false;
+        }
+        throw error;
+      }
+    },
+    async count() {
+      let total = 0;
+      for await (const shard of root.keys()) {
+        const dir = await shardHandle(shard, false);
+        if (!dir) {
+          continue;
+        }
+        for await (const name of dir.keys()) {
+          if (!name.endsWith(".tmp")) {
+            total++;
+          }
+        }
+      }
+      return total;
+    },
+    async keys() {
+      const names = [];
+      for await (const shard of root.keys()) {
+        const dir = await shardHandle(shard, false);
+        if (!dir) {
+          continue;
+        }
+        for await (const name of dir.keys()) {
+          if (!name.endsWith(".tmp")) {
+            names.push(name);
+          }
+        }
+      }
+      return names;
+    }
+  };
+}
+async function createOpfsBlobStore(rootDirName = "kora-blobs") {
+  return new OpfsBlobStore(await createOpfsBlobDirectory(rootDirName));
+}
+
+// src/blob/blob-chunking.ts
+import { hashBlob as hashBlob2 } from "@korajs/core";
+var DEFAULT_CHUNK_SIZE = 256 * 1024;
+async function chunkBlob(bytes, chunkSize = DEFAULT_CHUNK_SIZE, metadata = {}) {
+  if (chunkSize <= 0) {
+    throw new Error(`chunkBlob requires a positive chunkSize, got ${chunkSize}`);
+  }
+  const chunkHashes = [];
+  const chunks = /* @__PURE__ */ new Map();
+  for (let offset = 0; offset < bytes.byteLength; offset += chunkSize) {
+    const end = Math.min(offset + chunkSize, bytes.byteLength);
+    const chunk = new Uint8Array(end - offset);
+    chunk.set(bytes.subarray(offset, end));
+    const hash = await hashBlob2(chunk);
+    chunkHashes.push(hash);
+    if (!chunks.has(hash)) {
+      chunks.set(hash, chunk);
+    }
+  }
+  const blobHash = await hashBlob2(bytes);
+  const manifest = {
+    blobHash,
+    size: bytes.byteLength,
+    chunkSize,
+    chunkHashes
+  };
+  if (metadata.mimeType !== void 0) {
+    manifest.mimeType = metadata.mimeType;
+  }
+  if (metadata.filename !== void 0) {
+    manifest.filename = metadata.filename;
+  }
+  return { manifest, chunks };
+}
+async function reassembleBlob(manifest, chunkStore) {
+  const parts = [];
+  let total = 0;
+  for (const hash of manifest.chunkHashes) {
+    const chunk = await chunkStore.get(hash);
+    if (chunk === null) {
+      throw new Error(`Cannot reassemble blob ${manifest.blobHash}: missing chunk ${hash}`);
+    }
+    parts.push(chunk);
+    total += chunk.byteLength;
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const part of parts) {
+    out.set(part, offset);
+    offset += part.byteLength;
+  }
+  const actual = await hashBlob2(out);
+  if (actual !== manifest.blobHash) {
+    throw new BlobIntegrityError(manifest.blobHash, actual);
+  }
+  return out;
+}
+
+// src/blob/blob-transfer.ts
+import { hashBlob as hashBlob3 } from "@korajs/core";
+async function receiveBlob(manifest, provider, stores) {
+  let chunksFetched = 0;
+  let chunksSkipped = 0;
+  const seen = /* @__PURE__ */ new Set();
+  for (const hash of manifest.chunkHashes) {
+    if (seen.has(hash)) {
+      continue;
+    }
+    seen.add(hash);
+    if (await stores.chunkStore.has(hash)) {
+      chunksSkipped++;
+      continue;
+    }
+    const bytes = await provider.getChunk(hash);
+    if (bytes === null) {
+      throw new Error(`Blob transfer failed: provider could not supply chunk ${hash}`);
+    }
+    const actual = await hashBlob3(bytes);
+    if (actual !== hash) {
+      throw new BlobIntegrityError(hash, actual);
+    }
+    await stores.chunkStore.put(bytes);
+    chunksFetched++;
+  }
+  const full = await reassembleBlob(manifest, stores.chunkStore);
+  const ref = await stores.blobStore.put(full, {
+    mimeType: manifest.mimeType,
+    filename: manifest.filename
+  });
+  return { ref, chunksFetched, chunksSkipped };
+}
+async function prepareBlobForSend(bytes, chunkStore, options = {}) {
+  const { manifest, chunks } = await chunkBlob(bytes, options.chunkSize, {
+    mimeType: options.mimeType,
+    filename: options.filename
+  });
+  for (const chunk of chunks.values()) {
+    await chunkStore.put(chunk);
+  }
+  const provider = {
+    getChunk: (hash) => chunkStore.get(hash)
+  };
+  return { manifest, provider };
+}
+
+// src/blob/blob-manifest-transfer.ts
+import { hashBlob as hashBlob4 } from "@korajs/core";
+function serializeBlobManifest(manifest) {
+  const canonical = {
+    blobHash: manifest.blobHash,
+    size: manifest.size,
+    chunkSize: manifest.chunkSize,
+    chunkHashes: manifest.chunkHashes
+  };
+  if (manifest.mimeType !== void 0) {
+    canonical.mimeType = manifest.mimeType;
+  }
+  if (manifest.filename !== void 0) {
+    canonical.filename = manifest.filename;
+  }
+  return new TextEncoder().encode(JSON.stringify(canonical));
+}
+function parseBlobManifest(bytes) {
+  const parsed = JSON.parse(new TextDecoder().decode(bytes));
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new Error("Invalid blob manifest: not an object");
+  }
+  const obj = parsed;
+  if (typeof obj.blobHash !== "string") {
+    throw new Error("Invalid blob manifest: missing blobHash");
+  }
+  if (typeof obj.size !== "number" || typeof obj.chunkSize !== "number") {
+    throw new Error("Invalid blob manifest: missing size or chunkSize");
+  }
+  if (!Array.isArray(obj.chunkHashes) || obj.chunkHashes.some((h) => typeof h !== "string")) {
+    throw new Error("Invalid blob manifest: chunkHashes must be an array of strings");
+  }
+  const manifest = {
+    blobHash: obj.blobHash,
+    size: obj.size,
+    chunkSize: obj.chunkSize,
+    chunkHashes: obj.chunkHashes
+  };
+  if (typeof obj.mimeType === "string") {
+    manifest.mimeType = obj.mimeType;
+  }
+  if (typeof obj.filename === "string") {
+    manifest.filename = obj.filename;
+  }
+  return manifest;
+}
+async function putBlobForTransfer(store, bytes, options = {}) {
+  const { manifest, chunks } = await chunkBlob(bytes, options.chunkSize, {
+    ...options.mimeType !== void 0 ? { mimeType: options.mimeType } : {},
+    ...options.filename !== void 0 ? { filename: options.filename } : {}
+  });
+  for (const chunk of chunks.values()) {
+    await store.put(chunk);
+  }
+  const baseRef = await store.put(bytes, {
+    ...options.mimeType !== void 0 ? { mimeType: options.mimeType } : {},
+    ...options.filename !== void 0 ? { filename: options.filename } : {}
+  });
+  const manifestRef = await store.put(serializeBlobManifest(manifest));
+  return { ref: { ...baseRef, manifestHash: manifestRef.hash }, manifest };
+}
+async function fetchBlobManifest(provider, manifestHash) {
+  const bytes = await provider.getChunk(manifestHash);
+  if (bytes === null) {
+    throw new Error(`Blob manifest ${manifestHash} could not be fetched from the provider`);
+  }
+  const actual = await hashBlob4(bytes);
+  if (actual !== manifestHash) {
+    throw new BlobIntegrityError(manifestHash, actual);
+  }
+  return parseBlobManifest(bytes);
+}
+async function resolveBlobManifest(provider, ref) {
+  if (ref.manifestHash === void 0) {
+    throw new Error(
+      `Blob ${ref.hash} has no manifest to resolve. Store it with putBlobForTransfer (or app.blobs.put) so its reference carries a manifestHash, or pull with an explicit manifest.`
+    );
+  }
+  return fetchBlobManifest(provider, ref.manifestHash);
+}
+
+// src/blob/server-blob-callbacks.ts
+import { hashBlob as hashBlob5 } from "@korajs/core";
+function toServerBlobCallbacks(store) {
+  return {
+    resolveBlobChunk: (hash) => store.get(hash),
+    async persistBlobChunk(hash, bytes) {
+      const actual = await hashBlob5(bytes);
+      if (actual !== hash) {
+        return;
+      }
+      await store.put(bytes);
+    }
+  };
+}
+function createMemoryServerBlobStore() {
+  const store = new MemoryBlobStore();
+  return { store, callbacks: toServerBlobCallbacks(store) };
+}
+
+// src/blob/blob-gc.ts
+import { isBlobRef } from "@korajs/core";
+function extractBlobRefs(record) {
+  const refs = [];
+  for (const value of Object.values(record)) {
+    if (isBlobRef(value)) {
+      refs.push(value);
+    }
+  }
+  return refs;
+}
+async function collectBlobGarbage(store, liveRefs, options = {}) {
+  const live = /* @__PURE__ */ new Set();
+  for (const ref of liveRefs) {
+    live.add(ref.hash);
+    if (ref.manifestHash === void 0) {
+      continue;
+    }
+    live.add(ref.manifestHash);
+    try {
+      const manifestBytes = await store.get(ref.manifestHash);
+      if (manifestBytes !== null) {
+        const manifest = parseBlobManifest(manifestBytes);
+        for (const chunkHash of manifest.chunkHashes) {
+          live.add(chunkHash);
+        }
+      }
+    } catch {
+    }
+  }
+  const all = await store.list();
+  const collectedHashes = [];
+  for (const hash of all) {
+    if (live.has(hash)) {
+      continue;
+    }
+    collectedHashes.push(hash);
+    if (!options.dryRun) {
+      await store.delete(hash);
+    }
+  }
+  return {
+    scanned: all.length,
+    live: live.size,
+    collected: collectedHashes.length,
+    collectedHashes
+  };
+}
+
+// src/blob/blob-chunk-transport.ts
+import { generateUUIDv7 as generateUUIDv74 } from "@korajs/core";
+function createRemoteChunkProvider(port, options = {}) {
+  const timeoutMs = options.timeoutMs ?? 3e4;
+  const pending = /* @__PURE__ */ new Map();
+  port.onMessage((message) => {
+    if (message.type !== "blob-chunk-response") {
+      return;
+    }
+    const entry = pending.get(message.requestId);
+    if (!entry) {
+      return;
+    }
+    pending.delete(message.requestId);
+    clearTimeout(entry.timer);
+    entry.resolve(message.bytes);
+  });
+  return {
+    pendingCount: () => pending.size,
+    getChunk(hash) {
+      const requestId = generateUUIDv74();
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          pending.delete(requestId);
+          reject(new Error(`Blob chunk request for ${hash} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        pending.set(requestId, { resolve, reject, timer });
+        port.send({ type: "blob-chunk-request", requestId, hash });
+      });
+    }
+  };
+}
+function serveBlobChunks(port, blobStore) {
+  port.onMessage((message) => {
+    if (message.type !== "blob-chunk-request") {
+      return;
+    }
+    void blobStore.get(message.hash).then(
+      (bytes) => {
+        port.send({ type: "blob-chunk-response", requestId: message.requestId, bytes });
+      },
+      () => {
+        port.send({ type: "blob-chunk-response", requestId: message.requestId, bytes: null });
+      }
+    );
+  });
+}
+function createChunkPortPair() {
+  const handlersA = [];
+  const handlersB = [];
+  const a = {
+    send(message) {
+      queueMicrotask(() => {
+        for (const handler of handlersB) {
+          handler(message);
+        }
+      });
+    },
+    onMessage(handler) {
+      handlersA.push(handler);
+    }
+  };
+  const b = {
+    send(message) {
+      queueMicrotask(() => {
+        for (const handler of handlersA) {
+          handler(message);
+        }
+      });
+    },
+    onMessage(handler) {
+      handlersB.push(handler);
+    }
+  };
+  return { a, b };
+}
 export {
   AdapterError,
+  BlobIntegrityError,
   COMPACTION_BASELINE_META_KEY,
   Collection,
+  DEFAULT_CHUNK_SIZE,
   InvalidStateTransitionError,
   LAST_ACKED_SERVER_VECTOR_META_KEY,
+  MemoryBlobStore,
+  OpfsBlobStore,
+  OptimisticLockError,
   PersistenceError,
   QueryBuilder,
   QueryError,
@@ -3066,26 +3962,44 @@ export {
   WorkerTimeoutError,
   asRichTextSyncEngine,
   assertQueryReady,
+  chunkBlob,
+  collectBlobGarbage,
   collectOperationsAheadOfServer,
   compactOperationLog,
   computeAckCompactionWatermark,
+  createChunkPortPair,
+  createMemoryServerBlobStore,
+  createOpfsBlobDirectory,
+  createOpfsBlobStore,
+  createRemoteChunkProvider,
   createRichTextController,
   decodeAuditExport,
   decodeRichtext,
   deserializeVersionVectorFromMeta,
   encodeRichtext,
   exportBackup,
+  extractBlobRefs,
+  fetchBlobManifest,
   getSharedQueryStoreCache,
   mergeVersionVectors,
+  parseBlobManifest,
   persistedAuditTraceFromEvent,
   pluralize,
+  prepareBlobForSend,
+  putBlobForTransfer,
   readAuditExportManifest,
   readBackupManifest,
+  reassembleBlob,
+  receiveBlob,
+  resolveBlobManifest,
   restoreBackup,
   richtextStatesEqual,
   richtextToPlainText,
+  serializeBlobManifest,
   serializeVersionVectorToMeta,
+  serveBlobChunks,
   singularize,
+  toServerBlobCallbacks,
   validateStateTransition,
   validateUpdateStateMachine,
   verifyAuditExportChecksum,