@korajs/store 0.5.0 → 1.0.0-beta.0

package/dist/index.cjs

@@ -30,6 +30,38 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/serialization/op-data-encoding.ts
+function encodeRichtextFieldsForOpData(data, fields) {
+  const result = { ...data };
+  for (const [key, value] of Object.entries(data)) {
+    if (fields[key]?.kind !== "richtext") {
+      continue;
+    }
+    if (typeof value === "string" || value instanceof Uint8Array || value instanceof ArrayBuffer) {
+      result[key] = (0, import_core4.encodeBytesForOpData)(value);
+    }
+  }
+  return result;
+}
+function decodeRichtextFieldsFromOpData(data, fields) {
+  const result = { ...data };
+  for (const [key, value] of Object.entries(data)) {
+    if (fields[key]?.kind !== "richtext" || value === null || value === void 0) {
+      continue;
+    }
+    result[key] = (0, import_core4.decodeBytesFromOpData)(value);
+  }
+  return result;
+}
+var import_core4, decodeRichtextOpDataValue;
+var init_op_data_encoding = __esm({
+  "src/serialization/op-data-encoding.ts"() {
+    "use strict";
+    import_core4 = require("@korajs/core");
+    decodeRichtextOpDataValue = import_core4.decodeBytesFromOpData;
+  }
+});
+
 // src/serialization/richtext-serializer.ts
 function encodeRichtext(value) {
   if (value === null || value === void 0) {
@@ -46,6 +78,10 @@ function encodeRichtext(value) {
   if (value instanceof ArrayBuffer) {
     return new Uint8Array(value);
   }
+  if ((0, import_core4.isKoraBytesValue)(value) || (0, import_core4.isLegacyNumericByteObject)(value)) {
+    const decoded = decodeRichtextOpDataValue(value);
+    return decoded instanceof Uint8Array ? decoded : null;
+  }
   throw new Error("Richtext value must be a string, Uint8Array, ArrayBuffer, null, or undefined.");
 }
 function decodeRichtext(value) {
@@ -84,6 +120,7 @@ var init_richtext_serializer = __esm({
   "src/serialization/richtext-serializer.ts"() {
     "use strict";
     Y = __toESM(require("yjs"), 1);
+    init_op_data_encoding();
     TEXT_KEY = "content";
   }
 });
@@ -147,7 +184,7 @@ function serializeOperation(op) {
     record_id: op.recordId,
     data: dataPayload ? JSON.stringify(dataPayload) : null,
     previous_data: op.previousData ? JSON.stringify(op.previousData) : null,
-    timestamp: import_core4.HybridLogicalClock.serialize(op.timestamp),
+    timestamp: import_core5.HybridLogicalClock.serialize(op.timestamp),
     sequence_number: op.sequenceNumber,
     causal_deps: JSON.stringify(op.causalDeps),
     schema_version: op.schemaVersion
@@ -181,7 +218,7 @@ function deserializeOperation(row) {
     recordId: row.record_id,
     data,
     previousData: row.previous_data ? JSON.parse(row.previous_data) : null,
-    timestamp: import_core4.HybridLogicalClock.deserialize(row.timestamp),
+    timestamp: import_core5.HybridLogicalClock.deserialize(row.timestamp),
     sequenceNumber: row.sequence_number,
     causalDeps: JSON.parse(row.causal_deps),
     schemaVersion: row.schema_version,
@@ -224,11 +261,11 @@ function deserializeValue(value, descriptor) {
       return value;
   }
 }
-var import_core4, ATOMIC_OPS_KEY, TX_ID_KEY, MUTATION_NAME_KEY;
+var import_core5, ATOMIC_OPS_KEY, TX_ID_KEY, MUTATION_NAME_KEY;
 var init_serializer = __esm({
   "src/serialization/serializer.ts"() {
     "use strict";
-    import_core4 = require("@korajs/core");
+    import_core5 = require("@korajs/core");
     init_richtext_serializer();
     ATOMIC_OPS_KEY = "__kora_atomic_ops__";
     TX_ID_KEY = "__kora_tx_id__";
@@ -609,11 +646,11 @@ async function computeSha256(data) {
   const hashArray = Array.from(new Uint8Array(hashBuffer));
   return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
 }
-var import_core5, BACKUP_VERSION;
+var import_core6, BACKUP_VERSION;
 var init_backup = __esm({
   "src/backup/backup.ts"() {
     "use strict";
-    import_core5 = require("@korajs/core");
+    import_core6 = require("@korajs/core");
     init_serializer();
     BACKUP_VERSION = 1;
   }
@@ -670,7 +707,7 @@ __export(audit_trace_store_exports, {
 });
 function persistedAuditTraceFromEvent(event) {
   return {
-    id: (0, import_core16.generateUUIDv7)(),
+    id: (0, import_core18.generateUUIDv7)(),
     recordedAt: Date.now(),
     eventType: event.type,
     constraint: event.type === "constraint:violated" ? event.constraint : void 0,
@@ -736,11 +773,11 @@ function auditTraceIndexFields(trace) {
     recordId: trace.operationA.recordId
   };
 }
-var import_core16;
+var import_core18;
 var init_audit_trace_store = __esm({
   "src/audit/audit-trace-store.ts"() {
     "use strict";
-    import_core16 = require("@korajs/core");
+    import_core18 = require("@korajs/core");
     init_audit_json();
   }
 });
@@ -940,9 +977,12 @@ __export(index_exports, {
   Collection: () => Collection,
   InvalidStateTransitionError: () => InvalidStateTransitionError,
   LAST_ACKED_SERVER_VECTOR_META_KEY: () => LAST_ACKED_SERVER_VECTOR_META_KEY,
+  OptimisticLockError: () => OptimisticLockError,
   PersistenceError: () => PersistenceError,
   QueryBuilder: () => QueryBuilder,
   QueryError: () => QueryError,
+  QueryStore: () => QueryStore,
+  QueryStoreCache: () => QueryStoreCache,
   RecordNotFoundError: () => RecordNotFoundError,
   SequenceManager: () => SequenceManager,
   Store: () => Store,
@@ -952,14 +992,18 @@ __export(index_exports, {
   TransactionContext: () => TransactionContext,
   WorkerInitError: () => WorkerInitError,
   WorkerTimeoutError: () => WorkerTimeoutError,
+  asRichTextSyncEngine: () => asRichTextSyncEngine,
+  assertQueryReady: () => assertQueryReady,
   collectOperationsAheadOfServer: () => collectOperationsAheadOfServer,
   compactOperationLog: () => compactOperationLog,
   computeAckCompactionWatermark: () => computeAckCompactionWatermark,
+  createRichTextController: () => createRichTextController,
   decodeAuditExport: () => decodeAuditExport,
   decodeRichtext: () => decodeRichtext,
   deserializeVersionVectorFromMeta: () => deserializeVersionVectorFromMeta,
   encodeRichtext: () => encodeRichtext,
   exportBackup: () => exportBackup,
+  getSharedQueryStoreCache: () => getSharedQueryStoreCache,
   mergeVersionVectors: () => mergeVersionVectors,
   persistedAuditTraceFromEvent: () => persistedAuditTraceFromEvent,
   pluralize: () => pluralize,
@@ -994,6 +1038,16 @@ var RecordNotFoundError = class extends import_core.KoraError {
     this.name = "RecordNotFoundError";
   }
 };
+var OptimisticLockError = class extends import_core.KoraError {
+  constructor(collection, recordId) {
+    super(
+      `Row version changed while merging record "${recordId}" in "${collection}"; retry with fresh state`,
+      "OPTIMISTIC_LOCK",
+      { collection, recordId }
+    );
+    this.name = "OptimisticLockError";
+  }
+};
 var AdapterError = class extends import_core.KoraError {
   constructor(message, context) {
     super(message, "ADAPTER_ERROR", context);
@@ -1170,27 +1224,27 @@ async function saveDeltaCursor(adapter, cursor) {
 }
 
 // src/store/store.ts
-var import_core17 = require("@korajs/core");
+var import_core19 = require("@korajs/core");
 init_backup();
 
 // src/mutations/execute-delete.ts
-var import_core7 = require("@korajs/core");
+var import_core8 = require("@korajs/core");
 
 // src/lww/row-version.ts
-var import_core6 = require("@korajs/core");
+var import_core7 = require("@korajs/core");
 var EMPTY_ROW_VERSION = "";
 function serializeRowVersion(timestamp) {
-  return import_core6.HybridLogicalClock.serialize(timestamp);
+  return import_core7.HybridLogicalClock.serialize(timestamp);
 }
 function rowVersionFromRecord(row) {
   const version = row._version;
   if (typeof version === "string" && version.length > 0) {
-    return import_core6.HybridLogicalClock.deserialize(version);
+    return import_core7.HybridLogicalClock.deserialize(version);
   }
   return { wallTime: row._updated_at, logical: 0, nodeId: "" };
 }
 function isIncomingNewerThanRow(incoming, row) {
-  return import_core6.HybridLogicalClock.compare(incoming, rowVersionFromRecord(row)) > 0;
+  return import_core7.HybridLogicalClock.compare(incoming, rowVersionFromRecord(row)) > 0;
 }
 function lwwVersionWhereClause(remoteVersion) {
   return {
@@ -1250,6 +1304,28 @@ function buildUpdateQuery(collection, id, changes) {
   const sql = `UPDATE ${collection} SET ${setClauses.join(", ")} WHERE id = ?`;
   return { sql, params };
 }
+function buildFieldFastForwardUpdateQuery(collection, id, fieldChanges, remoteVersion, wallTime, options) {
+  const fieldClauses = Object.keys(fieldChanges).map((col) => `${col} = ?`);
+  const setClauses = [
+    ...fieldClauses,
+    "_version = CASE WHEN _version >= ? THEN _version ELSE ? END",
+    "_updated_at = CASE WHEN _updated_at >= ? THEN _updated_at ELSE ? END"
+  ];
+  const params = [
+    ...Object.values(fieldChanges),
+    remoteVersion,
+    remoteVersion,
+    wallTime,
+    wallTime
+  ];
+  if (options?.maxCreatedAt !== void 0) {
+    setClauses.push("_created_at = CASE WHEN _created_at >= ? THEN _created_at ELSE ? END");
+    params.push(options.maxCreatedAt, options.maxCreatedAt);
+  }
+  params.push(id);
+  const sql = `UPDATE ${collection} SET ${setClauses.join(", ")} WHERE id = ?`;
+  return { sql, params };
+}
 function buildSoftDeleteQuery(collection, id, updatedAt, version) {
   if (version !== void 0) {
     return {
@@ -1262,13 +1338,6 @@ function buildSoftDeleteQuery(collection, id, updatedAt, version) {
     params: [updatedAt, id]
   };
 }
-function buildLwwUpdateQuery(collection, id, changes, remoteVersion) {
-  const setClauses = Object.keys(changes).map((col) => `${col} = ?`);
-  const lww = lwwVersionWhereClause(remoteVersion);
-  const sql = `UPDATE ${collection} SET ${setClauses.join(", ")} WHERE id = ? AND ${lww.sql}`;
-  const params = [...Object.values(changes), id, ...lww.params];
-  return { sql, params };
-}
 function buildLwwSoftDeleteQuery(collection, id, updatedAt, version) {
   const lww = lwwVersionWhereClause(version);
   return {
@@ -1433,7 +1502,7 @@ async function executeDelete(ctx, id, options) {
   await ctx.adapter.transaction(async (tx) => {
     if (!operation) {
       const sequenceNumber = await allocateNextSequenceInTransaction(tx, ctx.nodeId);
-      operation = await (0, import_core7.createOperation)(
+      operation = await (0, import_core8.createOperation)(
         {
           nodeId: ctx.nodeId,
           type: "delete",
@@ -1480,11 +1549,65 @@ async function executeDelete(ctx, id, options) {
 }
 
 // src/mutations/execute-insert.ts
-var import_core8 = require("@korajs/core");
+var import_core9 = require("@korajs/core");
+
+// src/lww/field-versions.ts
+function parseFieldVersions(raw) {
+  if (typeof raw !== "string" || raw.length === 0) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return {};
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(parsed)) {
+      if (typeof value === "string") {
+        result[key] = value;
+      }
+    }
+    return result;
+  } catch {
+    return {};
+  }
+}
+function serializeFieldVersions(versions) {
+  return JSON.stringify(versions);
+}
+function fieldVersionsForFields(fieldNames, version) {
+  const versions = {};
+  for (const field of fieldNames) {
+    versions[field] = version;
+  }
+  return versions;
+}
+function effectiveFieldVersion(current, field, rowVersion) {
+  const own = current[field];
+  if (own !== void 0) {
+    return own;
+  }
+  return rowVersion ?? EMPTY_ROW_VERSION;
+}
+function resolvePerFieldLww(current, incomingFields, incomingVersion, rowVersion) {
+  const winners = [];
+  const merged = { ...current };
+  for (const field of incomingFields) {
+    const stored = effectiveFieldVersion(current, field, rowVersion);
+    if (incomingVersion > stored) {
+      winners.push(field);
+      merged[field] = incomingVersion;
+    }
+  }
+  return { winners, merged };
+}
+
+// src/mutations/execute-insert.ts
+init_op_data_encoding();
 init_serializer();
 async function executeInsert(ctx, data) {
-  const validated = (0, import_core8.validateRecord)(ctx.collection, ctx.definition, data, "insert");
-  const recordId = (0, import_core8.generateUUIDv7)();
+  const validated = (0, import_core9.validateRecord)(ctx.collection, ctx.definition, data, "insert");
+  const recordId = (0, import_core9.generateUUIDv7)();
   for (const [fieldName, descriptor] of Object.entries(ctx.definition.fields)) {
     if (descriptor.auto && descriptor.kind === "timestamp") {
       validated[fieldName] = Date.now();
@@ -1495,13 +1618,16 @@ async function executeInsert(ctx, data) {
   let record;
   await ctx.adapter.transaction(async (tx) => {
     const sequenceNumber = await allocateNextSequenceInTransaction(tx, ctx.nodeId);
-    operation = await (0, import_core8.createOperation)(
+    operation = await (0, import_core9.createOperation)(
       {
         nodeId: ctx.nodeId,
         type: "insert",
         collection: ctx.collection,
         recordId,
-        data: { ...validated },
+        // Binary richtext values are tagged as canonical JSON BEFORE the
+        // operation is content-hashed, so the hash input, persisted JSON,
+        // and wire payload are the identical value.
+        data: encodeRichtextFieldsForOpData(validated, ctx.definition.fields),
         previousData: null,
         sequenceNumber,
         causalDeps,
@@ -1517,7 +1643,12 @@ async function executeInsert(ctx, data) {
       ...serializedData,
       _created_at: operation.timestamp.wallTime,
       _updated_at: operation.timestamp.wallTime,
-      _version: version
+      _version: version,
+      // Stamp every inserted field with this operation's version so later
+      // per-field LWW compares against a real writer, not the fallback.
+      _field_versions: serializeFieldVersions(
+        fieldVersionsForFields(Object.keys(serializedData), version)
+      )
     };
     const builtInsert = buildInsertQuery(ctx.collection, record);
     const opInsert = buildInsertQuery(
@@ -1537,12 +1668,13 @@ async function executeInsert(ctx, data) {
 }
 
 // src/mutations/execute-update.ts
-var import_core10 = require("@korajs/core");
+var import_core11 = require("@korajs/core");
+init_op_data_encoding();
 init_serializer();
 
 // src/state-machine/state-validator.ts
-var import_core9 = require("@korajs/core");
-var InvalidStateTransitionError = class extends import_core9.KoraError {
+var import_core10 = require("@korajs/core");
+var InvalidStateTransitionError = class extends import_core10.KoraError {
   constructor(collection, recordId, field, fromState, toState, allowedStates) {
     super(
       `Invalid state transition in collection "${collection}": cannot transition field "${field}" from "${fromState}" to "${toState}". Allowed transitions from "${fromState}": ${allowedStates.length > 0 ? allowedStates.join(", ") : "(none -- terminal state)"}`,
@@ -1576,7 +1708,7 @@ function validateStateTransition(collectionName, recordId, stateMachine, current
     collection: collectionName,
     transitions: stateMachine.transitions
   };
-  const transitionResult = (0, import_core9.validateTransition)(constraint, currentState, newState);
+  const transitionResult = (0, import_core10.validateTransition)(constraint, currentState, newState);
   if (transitionResult.valid) {
     return { valid: true, allowedStates: transitionResult.allowedTargets };
   }
@@ -1632,7 +1764,7 @@ async function executeUpdate(ctx, id, data) {
   if (!currentRow) {
     throw new RecordNotFoundError(ctx.collection, id);
   }
-  let validated = (0, import_core10.validateRecord)(ctx.collection, ctx.definition, data, "update");
+  let validated = (0, import_core11.validateRecord)(ctx.collection, ctx.definition, data, "update");
   const currentRecord = deserializeRecord(currentRow, ctx.definition.fields);
   validated = validateUpdateStateMachine(
     ctx.collection,
@@ -1650,9 +1782,9 @@ async function executeUpdate(ctx, id, data) {
   for (const key of Object.keys(validated)) {
     const value = validated[key];
     previousData[key] = currentRecord[key];
-    if ((0, import_core10.isAtomicOp)(value)) {
-      resolvedData[key] = (0, import_core10.resolveAtomicOp)(currentRecord[key], value);
-      atomicOps[key] = (0, import_core10.toAtomicOp)(value);
+    if ((0, import_core11.isAtomicOp)(value)) {
+      resolvedData[key] = (0, import_core11.resolveAtomicOp)(currentRecord[key], value);
+      atomicOps[key] = (0, import_core11.toAtomicOp)(value);
     } else {
       resolvedData[key] = value;
     }
@@ -1662,14 +1794,17 @@ async function executeUpdate(ctx, id, data) {
   let operation;
   await ctx.adapter.transaction(async (tx) => {
     const sequenceNumber = await allocateNextSequenceInTransaction(tx, ctx.nodeId);
-    operation = await (0, import_core10.createOperation)(
+    operation = await (0, import_core11.createOperation)(
       {
         nodeId: ctx.nodeId,
         type: "update",
         collection: ctx.collection,
         recordId: id,
-        data: { ...resolvedData },
-        previousData,
+        // Binary richtext values (new and previous) are tagged as canonical
+        // JSON BEFORE the operation is content-hashed, so the hash input,
+        // persisted JSON, and wire payload are the identical value.
+        data: encodeRichtextFieldsForOpData(resolvedData, ctx.definition.fields),
+        previousData: encodeRichtextFieldsForOpData(previousData, ctx.definition.fields),
         sequenceNumber,
         causalDeps,
         schemaVersion: ctx.schema.version,
@@ -1680,10 +1815,15 @@ async function executeUpdate(ctx, id, data) {
     ctx.causalTracker?.afterOperation(ctx.collection, operation.id, ctx.inTransaction);
     const serializedChanges = serializeRecord(resolvedData, ctx.definition.fields);
     const version = serializeRowVersion(operation.timestamp);
+    const mergedFieldVersions = parseFieldVersions(currentRow._field_versions);
+    for (const changedField of Object.keys(serializedChanges)) {
+      mergedFieldVersions[changedField] = version;
+    }
     const updateQuery = buildUpdateQuery(ctx.collection, id, {
       ...serializedChanges,
       _updated_at: operation.timestamp.wallTime,
-      _version: version
+      _version: version,
+      _field_versions: serializeFieldVersions(mergedFieldVersions)
     });
     const opInsert = buildInsertQuery(
       `_kora_ops_${ctx.collection}`,
@@ -2083,7 +2223,7 @@ var QueryError2 = class extends Error {
 };
 
 // src/relations/relation-enforcer.ts
-var import_core11 = require("@korajs/core");
+var import_core12 = require("@korajs/core");
 init_serializer();
 
 // src/relations/relation-lookup.ts
@@ -2108,7 +2248,7 @@ function getIncomingRelations(lookup, collection) {
 }
 
 // src/relations/relation-enforcer.ts
-var ReferentialIntegrityError = class extends import_core11.KoraError {
+var ReferentialIntegrityError = class extends import_core12.KoraError {
   constructor(collection, recordId, referencingCollection, relationName, referencingCount) {
     super(
       `Cannot delete record "${recordId}" from "${collection}": ${referencingCount} record(s) in "${referencingCollection}" reference it via relation "${relationName}" with onDelete: 'restrict'. Delete or reassign the referencing records first.`,
@@ -2197,7 +2337,7 @@ var RelationEnforcer = class {
     for (const row of referencingRows) {
       const now = Date.now();
       const sequenceNumber = await allocateNextSequenceInTransaction(tx, this.nodeId);
-      const operation = await (0, import_core11.createOperation)(
+      const operation = await (0, import_core12.createOperation)(
         {
           nodeId: this.nodeId,
           type: "delete",
@@ -2246,7 +2386,7 @@ var RelationEnforcer = class {
       const sequenceNumber = await allocateNextSequenceInTransaction(tx, this.nodeId);
       const updateData = { [foreignKeyField]: null };
       const previousData = { [foreignKeyField]: deletedRecordId };
-      const operation = await (0, import_core11.createOperation)(
+      const operation = await (0, import_core12.createOperation)(
         {
           nodeId: this.nodeId,
           type: "update",
@@ -2307,8 +2447,9 @@ var RelationEnforcer = class {
 };
 
 // src/replay/replay-to.ts
-var import_core12 = require("@korajs/core");
+var import_core13 = require("@korajs/core");
 var import_internal = require("@korajs/core/internal");
+init_op_data_encoding();
 function collectCausalClosure(allOps, targetOperationId) {
   const opMap = /* @__PURE__ */ new Map();
   for (const op of allOps) {
@@ -2316,7 +2457,7 @@ function collectCausalClosure(allOps, targetOperationId) {
   }
   const target = opMap.get(targetOperationId);
   if (!target) {
-    throw new import_core12.OperationError(
+    throw new import_core13.OperationError(
       `Operation "${targetOperationId}" not found in the local operation log`,
       {
         operationId: targetOperationId
@@ -2348,7 +2489,7 @@ function buildReplaySnapshot(schema, allOps, targetOperationId) {
   const operationsApplied = collectCausalClosure(allOps, targetOperationId);
   const targetOperation = operationsApplied.find((op) => op.id === targetOperationId);
   if (!targetOperation) {
-    throw new import_core12.OperationError(`Operation "${targetOperationId}" not found after causal sort`, {
+    throw new import_core13.OperationError(`Operation "${targetOperationId}" not found after causal sort`, {
       operationId: targetOperationId
     });
   }
@@ -2393,7 +2534,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
@@ -2404,9 +2547,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;
       }
@@ -2415,7 +2559,7 @@ function applyOperationToMemory(state, op, schema) {
       }
       colMap.set(op.recordId, {
         id: op.recordId,
-        fields: { ...op.data },
+        fields: decodedData,
         deleted: false,
         createdAt: wallTime,
         updatedAt: wallTime
@@ -2471,7 +2615,7 @@ function toCollectionRecord(record, definition) {
 }
 
 // src/sequences/sequence-manager.ts
-var import_core13 = require("@korajs/core");
+var import_core14 = require("@korajs/core");
 var SequenceManager = class {
   adapter;
   nodeId;
@@ -2489,7 +2633,7 @@ var SequenceManager = class {
   async next(name, config) {
     const scope = config?.scope ?? "";
     const startAt = config?.startAt ?? 1;
-    const format = config?.format ?? (0, import_core13.defaultSequenceFormat)(name);
+    const format = config?.format ?? (0, import_core14.defaultSequenceFormat)(name);
     let counter = 0;
     await this.adapter.transaction(async (tx) => {
       const rows = await tx.query(
@@ -2511,7 +2655,7 @@ var SequenceManager = class {
         );
       }
     });
-    return (0, import_core13.formatSequenceValue)(format, counter, this.nodeId);
+    return (0, import_core14.formatSequenceValue)(format, counter, this.nodeId);
   }
   /**
    * Get the current counter value without incrementing.
@@ -2969,8 +3113,141 @@ var SubscriptionManager = class {
   }
 };
 
+// src/sync/rebase-unsynced-operations.ts
+var import_core15 = require("@korajs/core");
+var import_internal2 = require("@korajs/core/internal");
+init_serializer();
+var LOGICAL_COUNTER_LIMIT = import_core15.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 : import_core15.HybridLogicalClock.deserialize(maxOtherSerializedTs).wallTime;
+  const baseWallTime = Math.max(correctedNowMs, maxOtherWallTime + 1);
+  rebased.sort((a, b) => import_core15.HybridLogicalClock.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 (0, import_internal2.computeOperationId)(input, import_core15.HybridLogicalClock.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
-var import_core14 = require("@korajs/core");
+var import_core16 = require("@korajs/core");
+init_op_data_encoding();
 init_serializer();
 var TransactionContext = class {
   transactionId;
@@ -2981,7 +3258,7 @@ var TransactionContext = class {
   config;
   constructor(config) {
     this.config = config;
-    this.transactionId = (0, import_core14.generateUUIDv7)();
+    this.transactionId = (0, import_core16.generateUUIDv7)();
   }
   /**
    * Set a human-readable mutation name for this transaction.
@@ -3096,8 +3373,8 @@ var TransactionContext = class {
   }
   async insert(collectionName, definition, data) {
     this.ensureActive();
-    const validated = (0, import_core14.validateRecord)(collectionName, definition, data, "insert");
-    const recordId = (0, import_core14.generateUUIDv7)();
+    const validated = (0, import_core16.validateRecord)(collectionName, definition, data, "insert");
+    const recordId = (0, import_core16.generateUUIDv7)();
     const now = Date.now();
     for (const [fieldName, descriptor] of Object.entries(definition.fields)) {
       if (descriptor.auto && descriptor.kind === "timestamp") {
@@ -3106,13 +3383,15 @@ var TransactionContext = class {
     }
     const sequenceNumber = await this.config.sequenceAllocator.allocate();
     const causalDeps = this.config.causalTracker?.nextCausalDeps(collectionName, true) ?? [];
-    const operation = await (0, import_core14.createOperation)(
+    const operation = await (0, import_core16.createOperation)(
       {
         nodeId: this.config.nodeId,
         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,
@@ -3159,7 +3438,7 @@ var TransactionContext = class {
     if (!currentRecord) {
       throw new RecordNotFoundError(collectionName, id);
     }
-    const validated = (0, import_core14.validateRecord)(collectionName, definition, data, "update");
+    const validated = (0, import_core16.validateRecord)(collectionName, definition, data, "update");
     const now = Date.now();
     const previousData = {};
     const resolvedData = {};
@@ -3167,9 +3446,9 @@ var TransactionContext = class {
     for (const key of Object.keys(validated)) {
       const value = validated[key];
       previousData[key] = currentRecord[key];
-      if ((0, import_core14.isAtomicOp)(value)) {
-        resolvedData[key] = (0, import_core14.resolveAtomicOp)(currentRecord[key], value);
-        atomicOps[key] = (0, import_core14.toAtomicOp)(value);
+      if ((0, import_core16.isAtomicOp)(value)) {
+        resolvedData[key] = (0, import_core16.resolveAtomicOp)(currentRecord[key], value);
+        atomicOps[key] = (0, import_core16.toAtomicOp)(value);
       } else {
         resolvedData[key] = value;
       }
@@ -3177,14 +3456,16 @@ var TransactionContext = class {
     const hasAtomicOps = Object.keys(atomicOps).length > 0;
     const sequenceNumber = await this.config.sequenceAllocator.allocate();
     const causalDeps = this.config.causalTracker?.nextCausalDeps(collectionName, true) ?? [];
-    const operation = await (0, import_core14.createOperation)(
+    const operation = await (0, import_core16.createOperation)(
       {
         nodeId: this.config.nodeId,
         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,
@@ -3230,7 +3511,7 @@ var TransactionContext = class {
     const now = Date.now();
     const sequenceNumber = await this.config.sequenceAllocator.allocate();
     const causalDeps = this.config.causalTracker?.nextCausalDeps(collectionName, true) ?? [];
-    const operation = await (0, import_core14.createOperation)(
+    const operation = await (0, import_core16.createOperation)(
       {
         nodeId: this.config.nodeId,
         type: "delete",
@@ -3291,14 +3572,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") {
@@ -3333,7 +3616,7 @@ var TransactionSequenceAllocator = class {
 };
 
 // src/store/tab-node-id.ts
-var import_core15 = require("@korajs/core");
+var import_core17 = require("@korajs/core");
 function perTabStorageKey(dbName) {
   return `kora-tab-node-${dbName}`;
 }
@@ -3354,7 +3637,7 @@ function resolvePerTabNodeId(dbName) {
   if (existing) {
     return existing;
   }
-  const nodeId = (0, import_core15.generateUUIDv7)();
+  const nodeId = (0, import_core17.generateUUIDv7)();
   savePerTabNodeId(dbName, nodeId);
   return nodeId;
 }
@@ -3364,7 +3647,7 @@ var Store = class {
   opened = false;
   nodeId = "";
   sequenceNumber = 0;
-  versionVector = (0, import_core17.createVersionVector)();
+  versionVector = (0, import_core19.createVersionVector)();
   clock = null;
   collections = /* @__PURE__ */ new Map();
   subscriptionManager;
@@ -3398,8 +3681,8 @@ var Store = class {
     await this.adapter.open(this.schema);
     await this.runMigrationsIfNeeded();
     this.nodeId = await this.loadOrGenerateNodeId();
-    this.clock = new import_core17.HybridLogicalClock(this.nodeId);
-    this.causalTracker = new import_core17.CausalTracker();
+    this.clock = new import_core19.HybridLogicalClock(this.nodeId);
+    this.causalTracker = new import_core19.CausalTracker();
     this.sequenceManager = new SequenceManager(this.adapter, this.nodeId);
     this.sequenceNumber = await this.loadSequenceNumber();
     this.versionVector = await this.loadVersionVector();
@@ -3485,6 +3768,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;
@@ -3511,45 +3802,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,
@@ -3577,6 +3981,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) => import_core19.HybridLogicalClock.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.
@@ -3732,6 +4197,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).
    */
@@ -3774,6 +4264,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.
    */
@@ -3788,7 +4302,7 @@ var Store = class {
   async compact(strategy) {
     this.ensureOpen();
     if (strategy.mode === "never") {
-      return compactOperationLog(this.adapter, this.schema, strategy, (0, import_core17.createVersionVector)());
+      return compactOperationLog(this.adapter, this.schema, strategy, (0, import_core19.createVersionVector)());
     }
     const serverVector = strategy.serverVector ?? await loadLastAckedServerVector(this.adapter);
     return compactOperationLog(this.adapter, this.schema, strategy, serverVector);
@@ -3823,7 +4337,7 @@ var Store = class {
     let latest = null;
     for (const row of rows) {
       const op = deserializeOperationWithCollection(row, collection);
-      if (!latest || import_core17.HybridLogicalClock.compare(op.timestamp, latest.timestamp) > 0) {
+      if (!latest || import_core19.HybridLogicalClock.compare(op.timestamp, latest.timestamp) > 0) {
         latest = op;
       }
     }
@@ -3966,7 +4480,7 @@ var Store = class {
     for (let v = storedVersion + 1; v <= targetVersion; v++) {
       const migration = migrations[v];
       if (!migration) continue;
-      const sqlStatements = (0, import_core17.migrationStepsToSQL)(migration.steps);
+      const sqlStatements = (0, import_core19.migrationStepsToSQL)(migration.steps);
       for (const sql of sqlStatements) {
         try {
           await this.adapter.execute(sql);
@@ -4044,7 +4558,7 @@ var Store = class {
     if (rows[0]) {
       return rows[0].value;
     }
-    const newNodeId = (0, import_core17.generateUUIDv7)();
+    const newNodeId = (0, import_core19.generateUUIDv7)();
     await this.adapter.execute("INSERT INTO _kora_meta (key, value) VALUES ('node_id', ?)", [
       newNodeId
     ]);
@@ -4061,7 +4575,7 @@ var Store = class {
     const rows = await this.adapter.query(
       "SELECT node_id, sequence_number FROM _kora_version_vector"
     );
-    const vector = (0, import_core17.createVersionVector)();
+    const vector = (0, import_core19.createVersionVector)();
     for (const row of rows) {
       vector.set(row.node_id, row.sequence_number);
     }
@@ -4074,6 +4588,483 @@ var Store = class {
   }
 };
 
+// src/reactivity/query-store.ts
+var EMPTY_ARRAY = Object.freeze([]);
+var QueryStore = class {
+  snapshot = EMPTY_ARRAY;
+  listeners = /* @__PURE__ */ new Set();
+  unsubscribeQuery = null;
+  active = false;
+  queryBuilder;
+  constructor(queryBuilder) {
+    this.queryBuilder = queryBuilder;
+  }
+  /**
+   * Subscribe to snapshot changes.
+   *
+   * @returns Unsubscribe function
+   */
+  subscribe = (onStoreChange) => {
+    this.listeners.add(onStoreChange);
+    if (!this.active) {
+      this.startSubscription();
+    }
+    return () => {
+      this.listeners.delete(onStoreChange);
+      if (this.listeners.size === 0) {
+        this.stopSubscription();
+      }
+    };
+  };
+  /** Synchronous read of the latest query results. */
+  getSnapshot = () => {
+    return this.snapshot;
+  };
+  /** Tear down listeners and the underlying query subscription. */
+  destroy() {
+    this.stopSubscription();
+    this.listeners.clear();
+    this.snapshot = EMPTY_ARRAY;
+  }
+  startSubscription() {
+    this.active = true;
+    this.unsubscribeQuery = this.queryBuilder.subscribe((results) => {
+      if (!this.active) return;
+      this.snapshot = Object.freeze([...results]);
+      this.notifyListeners();
+    });
+  }
+  stopSubscription() {
+    this.active = false;
+    if (this.unsubscribeQuery) {
+      this.unsubscribeQuery();
+      this.unsubscribeQuery = null;
+    }
+  }
+  notifyListeners() {
+    for (const listener of this.listeners) {
+      listener();
+    }
+  }
+};
+
+// src/reactivity/assert-query-ready.ts
+var import_core20 = require("@korajs/core");
+var LEGACY_PENDING_COLLECTION = "__pending__";
+function assertQueryReady(query) {
+  const descriptor = query.getDescriptor();
+  if (descriptor.collection === LEGACY_PENDING_COLLECTION) {
+    throw new import_core20.AppNotReadyError(
+      "Cannot use useQuery() before app.ready. Await app.ready or wrap your UI in <KoraProvider app={app}>."
+    );
+  }
+}
+
+// src/reactivity/query-store-cache.ts
+var QueryStoreCache = class {
+  constructor(scopeKey = "default") {
+    this.scopeKey = scopeKey;
+  }
+  scopeKey;
+  entries = /* @__PURE__ */ new Map();
+  getOrCreate(queryBuilder) {
+    const key = this.getKey(queryBuilder);
+    const existing = this.entries.get(key);
+    if (existing) {
+      existing.refCount++;
+      return existing.queryStore;
+    }
+    const queryStore = new QueryStore(queryBuilder);
+    this.entries.set(key, {
+      queryStore,
+      refCount: 1
+    });
+    return queryStore;
+  }
+  release(queryBuilder) {
+    const key = this.getKey(queryBuilder);
+    const entry = this.entries.get(key);
+    if (!entry) {
+      return;
+    }
+    entry.refCount--;
+    if (entry.refCount <= 0) {
+      entry.queryStore.destroy();
+      this.entries.delete(key);
+    }
+  }
+  clear() {
+    for (const entry of this.entries.values()) {
+      entry.queryStore.destroy();
+    }
+    this.entries.clear();
+  }
+  get size() {
+    return this.entries.size;
+  }
+  getKey(queryBuilder) {
+    return `${this.scopeKey}:${JSON.stringify(queryBuilder.getDescriptor())}`;
+  }
+};
+var sharedCache = null;
+function getSharedQueryStoreCache() {
+  if (!sharedCache) {
+    sharedCache = new QueryStoreCache();
+  }
+  return sharedCache;
+}
+
+// src/richtext/create-richtext-controller.ts
+var Y2 = __toESM(require("yjs"), 1);
+init_richtext_serializer();
+var LOAD_ORIGIN = "kora-load";
+var REMOTE_ORIGIN = "kora-remote";
+var DOC_CHANNEL_ORIGIN = "kora-doc-channel";
+var TEXT_KEY2 = "content";
+var COMPACT_AFTER_DELTAS = 20;
+var PERSIST_DEBOUNCE_MS = 400;
+function createRichTextController(options) {
+  const {
+    collection,
+    collectionName,
+    recordId,
+    fieldName,
+    store,
+    syncEngine = null,
+    useDocChannel
+  } = options;
+  const doc = new Y2.Doc();
+  const text = doc.getText(TEXT_KEY2);
+  const undoManager = new Y2.UndoManager(text);
+  let user = options.user;
+  let disposed = false;
+  let ready = false;
+  let error = null;
+  let canUndo = false;
+  let canRedo = false;
+  let cursors = [];
+  const listeners = /* @__PURE__ */ new Set();
+  let snapshot = {
+    ready: false,
+    error: null,
+    canUndo: false,
+    canRedo: false,
+    cursors: []
+  };
+  const baseUpdateRef = { current: null };
+  const pendingDeltasRef = { current: [] };
+  const docChannelActiveRef = { current: false };
+  let persistTimer = null;
+  let recordUnsubscribe = null;
+  let docChannelUnsubscribe = null;
+  let awarenessUnsubscribe = null;
+  const refreshSnapshot = () => {
+    snapshot = {
+      ready,
+      error,
+      canUndo,
+      canRedo,
+      cursors: [...cursors]
+    };
+  };
+  const notify = () => {
+    refreshSnapshot();
+    for (const listener of listeners) {
+      listener();
+    }
+  };
+  const syncHistoryState = () => {
+    canUndo = undoManager.undoStack.length > 0;
+    canRedo = undoManager.redoStack.length > 0;
+    notify();
+  };
+  const getSnapshot = () => snapshot;
+  const resolveAwarenessUser = () => {
+    if (user) {
+      return user;
+    }
+    if (syncEngine) {
+      const existing = syncEngine.getAwarenessManager().getLocalState()?.user;
+      if (existing) {
+        return existing;
+      }
+    }
+    return {
+      name: "Anonymous",
+      color: "#6366f1"
+    };
+  };
+  const setCursor = (anchor, head) => {
+    if (!syncEngine) {
+      return;
+    }
+    const awareness = syncEngine.getAwarenessManager();
+    const state = {
+      user: resolveAwarenessUser(),
+      cursor: {
+        collection: collectionName,
+        recordId,
+        field: fieldName,
+        anchor,
+        head
+      }
+    };
+    awareness.setLocalState(state);
+  };
+  const clearCursor = () => {
+    if (!syncEngine) {
+      return;
+    }
+    const awareness = syncEngine.getAwarenessManager();
+    const current = awareness.getLocalState();
+    if (!current?.cursor) {
+      return;
+    }
+    if (current.cursor.collection !== collectionName || current.cursor.recordId !== recordId || current.cursor.field !== fieldName) {
+      return;
+    }
+    awareness.setLocalState({ user: current.user });
+  };
+  const applyRemoteSnapshot = (value) => {
+    const encoded = encodeRichtextInput(value);
+    if (!encoded) {
+      return;
+    }
+    const currentSnapshot = Y2.encodeStateAsUpdate(doc);
+    if (updatesEqual(currentSnapshot, encoded)) {
+      return;
+    }
+    Y2.applyUpdate(doc, encoded, REMOTE_ORIGIN);
+    baseUpdateRef.current = encoded;
+    pendingDeltasRef.current = [];
+    syncHistoryState();
+  };
+  const flushPersist = async () => {
+    const snapshot2 = composeRichtextSnapshot(baseUpdateRef.current, pendingDeltasRef.current);
+    if (pendingDeltasRef.current.length >= COMPACT_AFTER_DELTAS) {
+      baseUpdateRef.current = snapshot2;
+      pendingDeltasRef.current = [];
+    }
+    try {
+      await collection.update(recordId, {
+        [fieldName]: snapshot2
+      });
+    } catch (cause) {
+      if (!disposed) {
+        error = cause instanceof Error ? cause : new Error(String(cause));
+        notify();
+      }
+    }
+  };
+  const schedulePersist = () => {
+    if (persistTimer) {
+      clearTimeout(persistTimer);
+    }
+    persistTimer = setTimeout(() => {
+      persistTimer = null;
+      void flushPersist();
+    }, PERSIST_DEBOUNCE_MS);
+  };
+  const onDocUpdate = (update, origin) => {
+    syncHistoryState();
+    if (origin === LOAD_ORIGIN || origin === REMOTE_ORIGIN || origin === DOC_CHANNEL_ORIGIN) {
+      return;
+    }
+    pendingDeltasRef.current.push(update);
+    if (docChannelActiveRef.current && syncEngine) {
+      syncEngine.getRichtextDocChannel?.().send(collectionName, recordId, fieldName, update);
+      schedulePersist();
+      return;
+    }
+    void flushPersist();
+  };
+  const subscribeRecordChanges = () => {
+    recordUnsubscribe?.();
+    recordUnsubscribe = store.collection(collectionName).where({ id: recordId }).subscribe((results) => {
+      const record = results[0];
+      if (!record) {
+        return;
+      }
+      applyRemoteSnapshot(record[fieldName]);
+    });
+  };
+  const subscribeDocChannel = () => {
+    docChannelUnsubscribe?.();
+    if (!ready || !syncEngine || !docChannelActiveRef.current) {
+      return;
+    }
+    const channel = syncEngine.getRichtextDocChannel?.();
+    if (!channel) {
+      return;
+    }
+    docChannelUnsubscribe = channel.subscribe(collectionName, recordId, fieldName, (update) => {
+      Y2.applyUpdate(doc, update, DOC_CHANNEL_ORIGIN);
+      syncHistoryState();
+    });
+  };
+  const updateCursors = () => {
+    if (!syncEngine) {
+      cursors = [];
+      notify();
+      return;
+    }
+    const awareness = syncEngine.getAwarenessManager();
+    const localClientId = awareness.clientId;
+    const states = awareness.getStates();
+    const fieldCursors = [];
+    for (const [clientId, state] of states) {
+      if (clientId === localClientId) continue;
+      if (!state.cursor) continue;
+      if (state.cursor.collection !== collectionName || state.cursor.recordId !== recordId || state.cursor.field !== fieldName) {
+        continue;
+      }
+      fieldCursors.push({
+        clientId,
+        userName: state.user.name,
+        color: state.user.color,
+        anchor: state.cursor.anchor,
+        head: state.cursor.head
+      });
+    }
+    cursors = fieldCursors;
+    notify();
+  };
+  const subscribeAwareness = () => {
+    awarenessUnsubscribe?.();
+    if (!syncEngine) {
+      cursors = [];
+      notify();
+      return;
+    }
+    const awareness = syncEngine.getAwarenessManager();
+    awarenessUnsubscribe = awareness.on("change", () => {
+      updateCursors();
+    });
+    updateCursors();
+  };
+  const initialize = async () => {
+    ready = false;
+    error = null;
+    notify();
+    try {
+      const record = await collection.findById(recordId);
+      if (disposed) return;
+      doc.transact(() => {
+        const target = doc.getText(TEXT_KEY2);
+        target.delete(0, target.length);
+      }, LOAD_ORIGIN);
+      const encoded = encodeRichtextInput(record?.[fieldName]);
+      baseUpdateRef.current = encoded;
+      pendingDeltasRef.current = [];
+      if (encoded) {
+        Y2.applyUpdate(doc, encoded, LOAD_ORIGIN);
+      }
+      const channel = syncEngine?.getRichtextDocChannel?.();
+      docChannelActiveRef.current = channel?.shouldUseChannel(encoded?.length ?? 0, useDocChannel) ?? false;
+      ready = true;
+      syncHistoryState();
+      subscribeRecordChanges();
+      subscribeDocChannel();
+      subscribeAwareness();
+      notify();
+    } catch (cause) {
+      if (disposed) return;
+      error = cause instanceof Error ? cause : new Error(String(cause));
+      notify();
+    }
+  };
+  doc.on("update", onDocUpdate);
+  void initialize();
+  return {
+    doc,
+    text,
+    getSnapshot,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    undo() {
+      undoManager.undo();
+      syncHistoryState();
+    },
+    redo() {
+      undoManager.redo();
+      syncHistoryState();
+    },
+    setCursor,
+    clearCursor,
+    setUser(nextUser) {
+      user = nextUser;
+    },
+    destroy() {
+      if (disposed) {
+        return;
+      }
+      disposed = true;
+      if (persistTimer) {
+        clearTimeout(persistTimer);
+        persistTimer = null;
+      }
+      doc.off("update", onDocUpdate);
+      recordUnsubscribe?.();
+      docChannelUnsubscribe?.();
+      awarenessUnsubscribe?.();
+      clearCursor();
+      undoManager.destroy();
+      baseUpdateRef.current = null;
+      pendingDeltasRef.current = [];
+      docChannelActiveRef.current = false;
+      listeners.clear();
+    }
+  };
+}
+function encodeRichtextInput(value) {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  try {
+    return encodeRichtext(value);
+  } catch {
+    if (typeof value === "string") {
+      const fallbackDoc = new Y2.Doc();
+      fallbackDoc.getText(TEXT_KEY2).insert(0, value);
+      return Y2.encodeStateAsUpdate(fallbackDoc);
+    }
+    throw new Error("Richtext record value must be a string, Uint8Array, ArrayBuffer, or null.");
+  }
+}
+function composeRichtextSnapshot(base, deltas) {
+  const mergedDoc = new Y2.Doc();
+  if (base) {
+    Y2.applyUpdate(mergedDoc, base);
+  }
+  for (const delta of deltas) {
+    Y2.applyUpdate(mergedDoc, delta);
+  }
+  return Y2.encodeStateAsUpdate(mergedDoc);
+}
+function updatesEqual(left, right) {
+  if (left.length !== right.length) {
+    return false;
+  }
+  for (let index = 0; index < left.length; index++) {
+    if (left[index] !== right[index]) {
+      return false;
+    }
+  }
+  return true;
+}
+
+// src/richtext/as-rich-text-sync-engine.ts
+function asRichTextSyncEngine(engine) {
+  if (engine == null) {
+    return null;
+  }
+  return engine;
+}
+
 // src/index.ts
 init_richtext_serializer();
 
@@ -4091,9 +5082,12 @@ init_export_audit();
   Collection,
   InvalidStateTransitionError,
   LAST_ACKED_SERVER_VECTOR_META_KEY,
+  OptimisticLockError,
   PersistenceError,
   QueryBuilder,
   QueryError,
+  QueryStore,
+  QueryStoreCache,
   RecordNotFoundError,
   SequenceManager,
   Store,
@@ -4103,14 +5097,18 @@ init_export_audit();
   TransactionContext,
   WorkerInitError,
   WorkerTimeoutError,
+  asRichTextSyncEngine,
+  assertQueryReady,
   collectOperationsAheadOfServer,
   compactOperationLog,
   computeAckCompactionWatermark,
+  createRichTextController,
   decodeAuditExport,
   decodeRichtext,
   deserializeVersionVectorFromMeta,
   encodeRichtext,
   exportBackup,
+  getSharedQueryStoreCache,
   mergeVersionVectors,
   persistedAuditTraceFromEvent,
   pluralize,