@korajs/store 1.0.0-beta.11 → 1.0.0-beta.13

package/dist/internal.cjs

@@ -44,8 +44,8 @@ __export(internal_exports, {
   executeDelete: () => executeDelete,
   executeInsert: () => executeInsert,
   executeUpdate: () => executeUpdate,
+  hasUnsyncedOwnOperations: () => hasUnsyncedOwnOperations,
   isIncomingNewerThanRow: () => isIncomingNewerThanRow,
-  resolveCausalDeps: () => resolveCausalDeps,
   rowVersionFromRecord: () => rowVersionFromRecord,
   serializeOperation: () => serializeOperation,
   serializeRecord: () => serializeRecord,
@@ -149,8 +149,10 @@ function deserializeRecord(row, fields) {
 var ATOMIC_OPS_KEY = "__kora_atomic_ops__";
 var TX_ID_KEY = "__kora_tx_id__";
 var MUTATION_NAME_KEY = "__kora_mutation__";
+var FIELD_VERSIONS_KEY = "__kora_field_versions__";
+var HASH_VERSION_KEY = "__kora_hash_version__";
 function serializeOperation(op) {
-  const hasMetadata = op.transactionId !== void 0 || op.mutationName !== void 0;
+  const hasMetadata = op.transactionId !== void 0 || op.mutationName !== void 0 || op.hashVersion !== void 0;
   let dataPayload = null;
   if (op.data) {
     dataPayload = { ...op.data };
@@ -163,6 +165,12 @@ function serializeOperation(op) {
     if (op.mutationName !== void 0) {
       dataPayload[MUTATION_NAME_KEY] = op.mutationName;
     }
+    if (op.fieldVersions !== void 0) {
+      dataPayload[FIELD_VERSIONS_KEY] = op.fieldVersions;
+    }
+    if (op.hashVersion !== void 0) {
+      dataPayload[HASH_VERSION_KEY] = op.hashVersion;
+    }
   } else if (hasMetadata) {
     dataPayload = {};
     if (op.transactionId !== void 0) {
@@ -171,6 +179,9 @@ function serializeOperation(op) {
     if (op.mutationName !== void 0) {
       dataPayload[MUTATION_NAME_KEY] = op.mutationName;
     }
+    if (op.hashVersion !== void 0) {
+      dataPayload[HASH_VERSION_KEY] = op.hashVersion;
+    }
   }
   return {
     id: op.id,
@@ -190,6 +201,8 @@ function deserializeOperation(row) {
   let atomicOps;
   let transactionId;
   let mutationName;
+  let fieldVersions;
+  let hashVersion;
   if (row.data) {
     const parsed = JSON.parse(row.data);
     if (ATOMIC_OPS_KEY in parsed) {
@@ -201,8 +214,21 @@ function deserializeOperation(row) {
     if (MUTATION_NAME_KEY in parsed) {
       mutationName = parsed[MUTATION_NAME_KEY];
     }
-    const { [ATOMIC_OPS_KEY]: _a, [TX_ID_KEY]: _t, [MUTATION_NAME_KEY]: _m, ...rest } = parsed;
-    data = Object.keys(rest).length > 0 ? rest : null;
+    if (FIELD_VERSIONS_KEY in parsed) {
+      fieldVersions = parsed[FIELD_VERSIONS_KEY];
+    }
+    if (HASH_VERSION_KEY in parsed) {
+      hashVersion = parsed[HASH_VERSION_KEY];
+    }
+    const {
+      [ATOMIC_OPS_KEY]: _a,
+      [TX_ID_KEY]: _t,
+      [MUTATION_NAME_KEY]: _m,
+      [FIELD_VERSIONS_KEY]: _f,
+      [HASH_VERSION_KEY]: _h,
+      ...rest
+    } = parsed;
+    data = row.type !== "delete" || Object.keys(rest).length > 0 ? rest : null;
   }
   return {
     id: row.id,
@@ -219,13 +245,26 @@ function deserializeOperation(row) {
     schemaVersion: row.schema_version,
     ...atomicOps !== void 0 ? { atomicOps } : {},
     ...transactionId !== void 0 ? { transactionId } : {},
-    ...mutationName !== void 0 ? { mutationName } : {}
+    ...mutationName !== void 0 ? { mutationName } : {},
+    ...fieldVersions !== void 0 ? { fieldVersions } : {},
+    ...hashVersion !== void 0 ? { hashVersion } : {}
   };
 }
 function deserializeOperationWithCollection(row, collection) {
   const op = deserializeOperation(row);
   return { ...op, collection };
 }
+function toRichtextReadShape(data, fields) {
+  let out = data;
+  for (const [name, descriptor] of Object.entries(fields)) {
+    if (descriptor.kind !== "richtext" || !(name in data)) continue;
+    const value = data[name];
+    if (value === null || value === void 0 || value instanceof Uint8Array) continue;
+    if (out === data) out = { ...data };
+    out[name] = encodeRichtext(value);
+  }
+  return out;
+}
 function serializeValue(value, descriptor) {
   if (value === null || value === void 0) {
     return null;
@@ -241,9 +280,16 @@ function serializeValue(value, descriptor) {
     case "richtext":
       return encodeRichtext(value);
     default:
-      return value;
+      return typeof value === "string" && isRawTextKind(descriptor.kind) ? (0, import_core2.encodeStoredText)(value) : value;
   }
 }
+var RAW_TEXT_KINDS = /* @__PURE__ */ new Set(["string", "secret"]);
+function isRawTextKind(kind) {
+  return RAW_TEXT_KINDS.has(kind);
+}
+function encodeStoredFilterValue(value, descriptor) {
+  return typeof value === "string" && descriptor !== void 0 && isRawTextKind(descriptor.kind) ? (0, import_core2.encodeStoredText)(value) : value;
+}
 function deserializeValue(value, descriptor) {
   switch (descriptor.kind) {
     case "boolean":
@@ -263,7 +309,7 @@ function deserializeValue(value, descriptor) {
     case "richtext":
       return decodeRichtext(value);
     default:
-      return value;
+      return typeof value === "string" && isRawTextKind(descriptor.kind) ? (0, import_core2.decodeStoredText)(value) : value;
   }
 }
 
@@ -325,15 +371,20 @@ function buildSelectQuery(descriptor, fields) {
   if (descriptor.orderBy.length > 0) {
     const orderParts = descriptor.orderBy.map((o) => {
       validateFieldName(o.field, fields);
-      return `${(0, import_core5.quoteIdent)(o.field)} ${o.direction.toUpperCase()}`;
+      return `${(0, import_core5.quoteIdent)(resolveColumnName(o.field, fields))} ${sqlSortDirection(o.direction, o.field)}`;
     });
     parts.push(`ORDER BY ${orderParts.join(", ")}`);
   }
-  if (descriptor.limit !== void 0) {
-    parts.push(`LIMIT ${descriptor.limit}`);
+  const limit = descriptor.limit !== void 0 ? assertQueryCount(descriptor.limit, "limit") : null;
+  const offset = descriptor.offset !== void 0 ? assertQueryCount(descriptor.offset, "offset") : null;
+  if (limit !== null) {
+    parts.push("LIMIT ?");
+    params.push(limit);
   }
-  if (descriptor.offset !== void 0) {
-    parts.push(`OFFSET ${descriptor.offset}`);
+  if (offset !== null) {
+    if (limit === null) parts.push("LIMIT -1");
+    parts.push("OFFSET ?");
+    params.push(offset);
   }
   return { sql: parts.join(" "), params };
 }
@@ -401,6 +452,7 @@ function buildWhereClauseParts(where, fields, params) {
   for (const [fieldName, value] of Object.entries(where)) {
     validateFieldName(fieldName, fields);
     const descriptor = fields[fieldName];
+    const column = resolveColumnName(fieldName, fields);
     if (value !== null && typeof value === "object" && !Array.isArray(value)) {
       const ops = value;
       for (const [op, opValue] of Object.entries(ops)) {
@@ -411,18 +463,18 @@ function buildWhereClauseParts(where, fields, params) {
             validOperators: [...VALID_OPERATORS]
           });
         }
-        conditions.push(buildOperatorCondition(fieldName, op, opValue, descriptor, params));
+        conditions.push(buildOperatorCondition(fieldName, column, op, opValue, descriptor, params));
       }
     } else {
-      conditions.push(buildOperatorCondition(fieldName, "$eq", value, descriptor, params));
+      conditions.push(buildOperatorCondition(fieldName, column, "$eq", value, descriptor, params));
     }
   }
   if (conditions.length === 0) return null;
   return conditions.join(" AND ");
 }
-function buildOperatorCondition(fieldName, operator, value, descriptor, params) {
-  const sqlValue = descriptor?.kind === "boolean" && typeof value === "boolean" ? value ? 1 : 0 : value;
-  const column = (0, import_core5.quoteIdent)(fieldName);
+function buildOperatorCondition(fieldName, columnName, operator, value, descriptor, params) {
+  const sqlValue = toSqlFilterValue(value, descriptor);
+  const column = (0, import_core5.quoteIdent)(columnName);
   switch (operator) {
     case "$eq":
       if (sqlValue === null) {
@@ -457,9 +509,7 @@ function buildOperatorCondition(fieldName, operator, value, descriptor, params)
       }
       const placeholders = sqlValue.map(() => "?");
       for (const item of sqlValue) {
-        params.push(
-          descriptor?.kind === "boolean" && typeof item === "boolean" ? item ? 1 : 0 : item
-        );
+        params.push(toSqlFilterValue(item, descriptor));
       }
       return `${column} IN (${placeholders.join(", ")})`;
     }
@@ -467,12 +517,54 @@ function buildOperatorCondition(fieldName, operator, value, descriptor, params)
       throw new QueryError(`Unknown operator "${operator}"`, { operator });
   }
 }
+function toSqlFilterValue(value, descriptor) {
+  if (descriptor?.kind === "boolean" && typeof value === "boolean") return value ? 1 : 0;
+  return encodeStoredFilterValue(value, descriptor);
+}
+var VIRTUAL_TIMESTAMP_FIELDS = Object.freeze({
+  createdAt: "_created_at",
+  updatedAt: "_updated_at"
+});
+var VIRTUAL_TIMESTAMP_FIELD_NAMES = Object.freeze([
+  "createdAt",
+  "updatedAt"
+]);
+var SORT_DIRECTIONS = Object.freeze({
+  asc: "ASC",
+  desc: "DESC"
+});
+function resolveColumnName(fieldName, fields) {
+  if (Object.hasOwn(fields, fieldName)) return fieldName;
+  if (fieldName === "createdAt" || fieldName === "updatedAt") {
+    return VIRTUAL_TIMESTAMP_FIELDS[fieldName];
+  }
+  return fieldName;
+}
+function sqlSortDirection(direction, field) {
+  const key = typeof direction === "string" ? direction.toLowerCase() : "";
+  const keyword = Object.hasOwn(SORT_DIRECTIONS, key) ? SORT_DIRECTIONS[key] : void 0;
+  if (keyword === void 0) {
+    throw new QueryError(`Invalid sort direction for field "${field}". Use 'asc' or 'desc'.`, {
+      field,
+      direction: typeof direction === "string" ? direction.slice(0, 64) : typeof direction
+    });
+  }
+  return keyword;
+}
+function assertQueryCount(value, clause) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw new QueryError(
+      `Invalid ${clause}: expected a non-negative safe integer. Pass a whole number, for example .${clause}(10).`,
+      { clause, received: typeof value === "number" ? value : typeof value }
+    );
+  }
+  return value;
+}
 function validateFieldName(fieldName, fields) {
   const allowedFields = /* @__PURE__ */ new Set([
     ...Object.keys(fields),
     "id",
-    "createdAt",
-    "updatedAt",
+    ...VIRTUAL_TIMESTAMP_FIELD_NAMES,
     "_created_at",
     "_updated_at"
   ]);
@@ -484,8 +576,137 @@ function validateFieldName(fieldName, fields) {
   }
 }
 
-// src/mutations/execute-insert.ts
+// src/mutations/run-local-write.ts
+var import_core7 = require("@korajs/core");
+
+// src/mutations/write-context.ts
 var import_core6 = require("@korajs/core");
+var CausalScope = class {
+  constructor(tracker, chainOperations) {
+    this.tracker = tracker;
+    this.chainOperations = chainOperations;
+  }
+  tracker;
+  chainOperations;
+  lastByCollection = /* @__PURE__ */ new Map();
+  lastInScope = null;
+  recorded = [];
+  /**
+   * Direct causal parents for the next operation in `collection`.
+   *
+   * @param collection - Collection of the operation being built
+   * @param extra - Explicit parents (e.g. the delete that caused a cascade)
+   */
+  depsFor(collection, extra = []) {
+    const deps = [];
+    const add = (id) => {
+      if (id && !deps.includes(id)) deps.push(id);
+    };
+    for (const id of extra) add(id);
+    const local = this.lastByCollection.get(collection);
+    if (local !== void 0) {
+      add(local);
+    } else {
+      for (const id of this.tracker?.nextCausalDeps(collection, false) ?? []) add(id);
+    }
+    if (this.chainOperations) add(this.lastInScope);
+    return deps;
+  }
+  /** Record an operation built in this scope. */
+  record(collection, operationId) {
+    this.lastByCollection.set(collection, operationId);
+    this.lastInScope = operationId;
+    this.recorded.push({ collection, id: operationId });
+  }
+  /** Publish this scope's heads to the shared tracker. Call only after commit. */
+  publish() {
+    for (const { collection, id } of this.recorded) {
+      this.tracker?.afterOperation(collection, id, false);
+    }
+  }
+};
+var SequenceBlock = class {
+  constructor(tx, nodeId) {
+    this.tx = tx;
+    this.nodeId = nodeId;
+  }
+  tx;
+  nodeId;
+  last = null;
+  persisted = 0;
+  /** The next number of the block. */
+  async take() {
+    if (this.last === null) {
+      const rows = await this.tx.query(
+        `INSERT INTO _kora_version_vector (node_id, sequence_number) VALUES (?, 1)
+     ON CONFLICT(node_id) DO UPDATE SET sequence_number = sequence_number + 1
+     RETURNING sequence_number`,
+        [this.nodeId]
+      );
+      const first = rows[0]?.sequence_number;
+      if (first === void 0) {
+        throw new import_core6.KoraError(
+          `Failed to reserve a sequence number for node "${this.nodeId}"`,
+          "SEQUENCE_RESERVATION_FAILED",
+          { nodeId: this.nodeId }
+        );
+      }
+      this.last = first;
+      this.persisted = first;
+      return first;
+    }
+    this.last += 1;
+    return this.last;
+  }
+  /** Persist the end of the block. Must run inside the transaction, before commit. */
+  async close() {
+    if (this.last === null || this.last === this.persisted) return;
+    await this.tx.execute(
+      "UPDATE _kora_version_vector SET sequence_number = MAX(sequence_number, ?) WHERE node_id = ?",
+      [this.last, this.nodeId]
+    );
+    this.persisted = this.last;
+  }
+};
+async function withWriteScope(tx, nodeId, causal, write) {
+  const scope = { tx, sequence: new SequenceBlock(tx, nodeId), causal };
+  const result = await write(scope);
+  await scope.sequence.close();
+  return result;
+}
+
+// src/mutations/run-local-write.ts
+async function runLocalWrite(ctx, write) {
+  const causal = new CausalScope(ctx.causalTracker, false);
+  let result;
+  try {
+    await ctx.adapter.transaction(async (tx) => {
+      result = await withWriteScope(tx, ctx.nodeId, causal, write);
+    });
+  } catch (error) {
+    ctx.onStorageError?.(error);
+    throw error;
+  }
+  if (!result) {
+    throw new import_core7.KoraError("Local write transaction completed without a result", "WRITE_INCOMPLETE", {
+      collection: ctx.collection
+    });
+  }
+  causal.publish();
+  publishOperations(ctx, result);
+  return result;
+}
+function publishOperations(ctx, result) {
+  const ops = [];
+  if (result.operation) ops.push(result.operation);
+  ops.push(...result.sideEffects);
+  for (const op of ops) {
+    ctx.onMutation(op.collection, op);
+  }
+}
+
+// src/mutations/write-ops.ts
+var import_core10 = require("@korajs/core");
 
 // src/lww/field-versions.ts
 function parseFieldVersions(raw) {
@@ -511,119 +732,20 @@ function parseFieldVersions(raw) {
 function serializeFieldVersions(versions) {
   return JSON.stringify(versions);
 }
-function fieldVersionsForFields(fieldNames, version) {
-  const versions = {};
-  for (const field of fieldNames) {
-    versions[field] = version;
-  }
-  return versions;
-}
-
-// src/store/sequence-allocator.ts
-async function allocateNextSequenceInTransaction(tx, nodeId) {
-  const rows = await tx.query(
-    `INSERT INTO _kora_version_vector (node_id, sequence_number) VALUES (?, 1)
-     ON CONFLICT(node_id) DO UPDATE SET sequence_number = sequence_number + 1
-     RETURNING sequence_number`,
-    [nodeId]
-  );
-  const seq = rows[0]?.sequence_number;
-  if (seq === void 0) {
-    throw new Error(`Failed to allocate sequence number for node "${nodeId}" in transaction`);
-  }
-  return seq;
-}
-
-// src/mutations/resolve-causal-deps.ts
-function resolveCausalDeps(ctx) {
-  const merged = [];
-  for (const id of ctx.extraCausalDeps ?? []) {
-    if (!merged.includes(id)) {
-      merged.push(id);
-    }
-  }
-  for (const id of ctx.causalTracker?.nextCausalDeps(ctx.collection, ctx.inTransaction) ?? []) {
-    if (!merged.includes(id)) {
-      merged.push(id);
+function stampFieldVersions(currentRaw, fields, version) {
+  const versions = parseFieldVersions(currentRaw);
+  for (const field of fields) {
+    const existing = versions[field];
+    if (existing === void 0 || existing < version) {
+      versions[field] = version;
     }
   }
-  return merged;
+  return serializeFieldVersions(versions);
 }
 
-// src/mutations/execute-insert.ts
-async function executeInsert(ctx, data) {
-  const validated = (0, import_core6.validateRecord)(ctx.collection, ctx.definition, data, "insert");
-  const recordId = (0, import_core6.generateUUIDv7)();
-  for (const [fieldName, descriptor] of Object.entries(ctx.definition.fields)) {
-    if (descriptor.auto && descriptor.kind === "timestamp") {
-      validated[fieldName] = Date.now();
-    }
-  }
-  const writeData = await (0, import_core6.transformSecretFieldsForWrite)(
-    validated,
-    ctx.definition,
-    ctx.secretKeyProvider
-  );
-  const causalDeps = resolveCausalDeps(ctx);
-  let operation;
-  let record;
-  await ctx.adapter.transaction(async (tx) => {
-    const sequenceNumber = await allocateNextSequenceInTransaction(tx, ctx.nodeId);
-    operation = await (0, import_core6.createOperation)(
-      {
-        nodeId: ctx.nodeId,
-        type: "insert",
-        collection: ctx.collection,
-        recordId,
-        // 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(writeData, ctx.definition.fields),
-        previousData: null,
-        sequenceNumber,
-        causalDeps,
-        schemaVersion: ctx.schema.version
-      },
-      ctx.clock
-    );
-    ctx.causalTracker?.afterOperation(ctx.collection, operation.id, ctx.inTransaction);
-    const serializedData = serializeRecord(writeData, ctx.definition.fields);
-    const version = serializeRowVersion(operation.timestamp);
-    record = {
-      id: recordId,
-      ...serializedData,
-      _created_at: operation.timestamp.wallTime,
-      _updated_at: operation.timestamp.wallTime,
-      _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(
-      `_kora_ops_${ctx.collection}`,
-      serializeOperation(operation)
-    );
-    await tx.execute(builtInsert.sql, builtInsert.params);
-    await tx.execute(opInsert.sql, opInsert.params);
-  });
-  ctx.onMutation(ctx.collection, operation);
-  return {
-    id: recordId,
-    ...writeData,
-    createdAt: operation.timestamp.wallTime,
-    updatedAt: operation.timestamp.wallTime
-  };
-}
-
-// src/mutations/execute-update.ts
-var import_core8 = require("@korajs/core");
-
 // src/state-machine/state-validator.ts
-var import_core7 = require("@korajs/core");
-var InvalidStateTransitionError = class extends import_core7.KoraError {
+var import_core8 = require("@korajs/core");
+var InvalidStateTransitionError = class extends import_core8.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)"}`,
@@ -657,7 +779,7 @@ function validateStateTransition(collectionName, recordId, stateMachine, current
     collection: collectionName,
     transitions: stateMachine.transitions
   };
-  const transitionResult = (0, import_core7.validateTransition)(constraint, currentState, newState);
+  const transitionResult = (0, import_core8.validateTransition)(constraint, currentState, newState);
   if (transitionResult.valid) {
     return { valid: true, allowedStates: transitionResult.allowedTargets };
   }
@@ -675,10 +797,25 @@ function validateStateTransition(collectionName, recordId, stateMachine, current
   return { valid: false, allowedStates };
 }
 function validateUpdateStateMachine(collectionName, recordId, collectionDef, currentRecord, updateData) {
+  let result = updateData;
   const stateMachine = collectionDef.stateMachine;
-  if (stateMachine === void 0) {
-    return updateData;
+  if (stateMachine !== void 0) {
+    result = applyStateMachine(collectionName, recordId, stateMachine, currentRecord, result);
+  }
+  for (const [field, descriptor] of Object.entries(collectionDef.fields)) {
+    if (descriptor.kind !== "enum" || !descriptor.transitions) continue;
+    if (stateMachine?.field === field) continue;
+    result = applyStateMachine(
+      collectionName,
+      recordId,
+      { field, transitions: descriptor.transitions, onInvalidTransition: "reject" },
+      currentRecord,
+      result
+    );
   }
+  return result;
+}
+function applyStateMachine(collectionName, recordId, stateMachine, currentRecord, updateData) {
   const stateField = stateMachine.field;
   if (!(stateField in updateData)) {
     return updateData;
@@ -703,161 +840,340 @@ function validateUpdateStateMachine(collectionName, recordId, collectionDef, cur
   return filtered;
 }
 
-// src/mutations/execute-update.ts
-async function executeUpdate(ctx, id, data) {
-  const currentRows = await ctx.adapter.query(
-    `SELECT * FROM ${(0, import_core8.quoteIdent)(ctx.collection)} WHERE id = ? AND _deleted = 0`,
-    [id]
-  );
-  const currentRow = currentRows[0];
+// src/mutations/secret-write.ts
+var import_core9 = require("@korajs/core");
+function toAtRestWriteData(data, definition, secretKeyProvider) {
+  return (0, import_core9.transformSecretFieldsForWrite)(data, definition, secretKeyProvider);
+}
+
+// src/mutations/write-ops.ts
+async function prepareInsert(env, collection, data) {
+  const definition = requireDefinition(env, collection);
+  const validated = (0, import_core10.validateRecord)(collection, definition, data, "insert");
+  const now = Date.now();
+  for (const [fieldName, descriptor] of Object.entries(definition.fields)) {
+    if (descriptor.auto && descriptor.kind === "timestamp") {
+      validated[fieldName] = now;
+    }
+  }
+  const writeData = await toAtRestWriteData(validated, definition, env.secretKeyProvider);
+  return { collection, recordId: (0, import_core10.generateUUIDv7)(), data: writeData };
+}
+async function writeInsertInTx(env, scope, insert, extraCausalDeps = []) {
+  const definition = requireDefinition(env, insert.collection);
+  const operation = await buildLocalOperation(env, scope, {
+    type: "insert",
+    collection: insert.collection,
+    recordId: insert.recordId,
+    // Binary richtext values are tagged as canonical JSON BEFORE hashing, so the
+    // hash input, persisted JSON and wire payload are the identical value.
+    data: encodeRichtextFieldsForOpData(insert.data, definition.fields),
+    previousData: null,
+    extraCausalDeps
+  });
+  if (env.fold) {
+    await appendOperationRow(scope, operation);
+    await env.fold.applyInTx(scope.tx, operation, "local");
+  } else {
+    const serialized = serializeRecord(insert.data, definition.fields);
+    const version = serializeRowVersion(operation.timestamp);
+    const row = {
+      id: insert.recordId,
+      ...serialized,
+      _created_at: operation.timestamp.wallTime,
+      _updated_at: operation.timestamp.wallTime,
+      _version: version,
+      // Every inserted field is stamped with this operation's version, so later
+      // per-field LWW compares against a real writer, not the row fallback.
+      _field_versions: stampFieldVersions(null, Object.keys(serialized), version)
+    };
+    const rowInsert = buildInsertQuery(insert.collection, row);
+    await scope.tx.execute(rowInsert.sql, rowInsert.params);
+    await appendOperationRow(scope, operation);
+  }
+  return {
+    operation,
+    record: {
+      id: insert.recordId,
+      // A richtext value written as a string returns as the bytes reads return.
+      ...toRichtextReadShape(insert.data, definition.fields),
+      createdAt: operation.timestamp.wallTime,
+      updatedAt: operation.timestamp.wallTime
+    },
+    sideEffects: []
+  };
+}
+async function writeUpdateInTx(env, scope, collection, id, data, extraCausalDeps = []) {
+  const definition = requireDefinition(env, collection);
+  const currentRow = await readLiveRow(scope, collection, id);
   if (!currentRow) {
-    throw new RecordNotFoundError(ctx.collection, id);
-  }
-  let validated = (0, import_core8.validateRecord)(ctx.collection, ctx.definition, data, "update");
-  const currentRecord = deserializeRecord(currentRow, ctx.definition.fields);
-  validated = validateUpdateStateMachine(
-    ctx.collection,
-    id,
-    ctx.definition,
-    currentRecord,
-    validated
-  );
-  if (Object.keys(validated).length === 0) {
-    return { ...currentRecord };
+    throw new RecordNotFoundError(collection, id);
+  }
+  const currentRecord = deserializeRecord(currentRow, definition.fields);
+  const allowed = validateUpdateStateMachine(collection, id, definition, currentRecord, data);
+  if (Object.keys(allowed).length === 0) {
+    return { operation: null, record: currentRecord, sideEffects: [] };
   }
   const previousData = {};
-  const resolvedData = {};
+  const resolved = {};
   const atomicOps = {};
-  for (const key of Object.keys(validated)) {
-    const value = validated[key];
+  for (const [key, value] of Object.entries(allowed)) {
     previousData[key] = currentRecord[key];
-    if ((0, import_core8.isAtomicOp)(value)) {
-      resolvedData[key] = (0, import_core8.resolveAtomicOp)(currentRecord[key], value);
-      atomicOps[key] = (0, import_core8.toAtomicOp)(value);
+    if ((0, import_core10.isAtomicOp)(value)) {
+      resolved[key] = (0, import_core10.resolveAtomicOp)(currentRecord[key], value);
+      const descriptor = definition.fields[key];
+      if (descriptor) (0, import_core10.assertResolvedFieldValue)(collection, key, descriptor, resolved[key]);
+      atomicOps[key] = (0, import_core10.toAtomicOp)(value);
     } else {
-      resolvedData[key] = value;
+      resolved[key] = value;
     }
   }
-  const writeData = await (0, import_core8.transformSecretFieldsForWrite)(
-    resolvedData,
-    ctx.definition,
-    ctx.secretKeyProvider
-  );
-  const hasAtomicOps = Object.keys(atomicOps).length > 0;
-  const causalDeps = resolveCausalDeps(ctx);
-  let operation;
-  await ctx.adapter.transaction(async (tx) => {
-    const sequenceNumber = await allocateNextSequenceInTransaction(tx, ctx.nodeId);
-    operation = await (0, import_core8.createOperation)(
-      {
-        nodeId: ctx.nodeId,
-        type: "update",
-        collection: ctx.collection,
-        recordId: id,
-        // 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(writeData, ctx.definition.fields),
-        previousData: encodeRichtextFieldsForOpData(previousData, ctx.definition.fields),
-        sequenceNumber,
-        causalDeps,
-        schemaVersion: ctx.schema.version,
-        ...hasAtomicOps ? { atomicOps } : {}
-      },
-      ctx.clock
-    );
-    ctx.causalTracker?.afterOperation(ctx.collection, operation.id, ctx.inTransaction);
-    const serializedChanges = serializeRecord(writeData, ctx.definition.fields);
+  const writeData = await toAtRestWriteData(resolved, definition, env.secretKeyProvider);
+  const operation = await buildLocalOperation(env, scope, {
+    type: "update",
+    collection,
+    recordId: id,
+    data: encodeRichtextFieldsForOpData(writeData, definition.fields),
+    previousData: encodeRichtextFieldsForOpData(previousData, definition.fields),
+    extraCausalDeps,
+    ...Object.keys(atomicOps).length > 0 ? { atomicOps } : {}
+  });
+  if (env.fold) {
+    await appendOperationRow(scope, operation);
+    await env.fold.applyInTx(scope.tx, operation, "local");
+  } else {
+    const serializedChanges = serializeRecord(writeData, 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, {
+    const rowUpdate = buildUpdateQuery(collection, id, {
       ...serializedChanges,
       _updated_at: operation.timestamp.wallTime,
       _version: version,
-      _field_versions: serializeFieldVersions(mergedFieldVersions)
+      _field_versions: stampFieldVersions(
+        currentRow._field_versions,
+        Object.keys(serializedChanges),
+        version
+      )
     });
-    const opInsert = buildInsertQuery(
-      `_kora_ops_${ctx.collection}`,
-      serializeOperation(operation)
-    );
-    await tx.execute(updateQuery.sql, updateQuery.params);
-    await tx.execute(opInsert.sql, opInsert.params);
+    await scope.tx.execute(rowUpdate.sql, rowUpdate.params);
+    await appendOperationRow(scope, operation);
+  }
+  const updatedRow = await readLiveRow(scope, collection, id);
+  if (!updatedRow) {
+    throw new RecordNotFoundError(collection, id);
+  }
+  return {
+    operation,
+    record: deserializeRecord(updatedRow, definition.fields),
+    sideEffects: []
+  };
+}
+async function writeDeleteInTx(env, scope, collection, id, options = {}) {
+  const definition = requireDefinition(env, collection);
+  const currentRow = await readLiveRow(scope, collection, id);
+  if (!currentRow) {
+    throw new RecordNotFoundError(collection, id);
+  }
+  const operation = await buildLocalOperation(env, scope, {
+    type: "delete",
+    collection,
+    recordId: id,
+    data: null,
+    previousData: null,
+    extraCausalDeps: options.extraCausalDeps ?? []
   });
-  ctx.onMutation(ctx.collection, operation);
-  const rows = await ctx.adapter.query(
-    `SELECT * FROM ${(0, import_core8.quoteIdent)(ctx.collection)} WHERE id = ? AND _deleted = 0`,
+  if (!options.skipReferentialEnforcement && env.beforeLocalDelete) {
+    await env.beforeLocalDelete(operation, scope.tx);
+  }
+  if (env.fold) {
+    await appendOperationRow(scope, operation);
+    await env.fold.applyInTx(scope.tx, operation, "local");
+  } else {
+    const version = serializeRowVersion(operation.timestamp);
+    const softDelete = buildSoftDeleteQuery(collection, id, operation.timestamp.wallTime, version);
+    await scope.tx.execute(softDelete.sql, softDelete.params);
+    await appendOperationRow(scope, operation);
+  }
+  const sideEffects = [];
+  if (!options.skipReferentialEnforcement && env.relationEnforcer) {
+    const result = await env.relationEnforcer.enforceDelete(
+      collection,
+      id,
+      scope,
+      env,
+      operation.id
+    );
+    sideEffects.push(...result.operations);
+  }
+  return {
+    operation,
+    record: deserializeRecord(currentRow, definition.fields),
+    sideEffects
+  };
+}
+async function buildLocalOperation(env, scope, input) {
+  const sequenceNumber = await scope.sequence.take();
+  const causalDeps = scope.causal.depsFor(input.collection, input.extraCausalDeps);
+  const operation = await (0, import_core10.createOperation)(
+    {
+      nodeId: env.nodeId,
+      type: input.type,
+      collection: input.collection,
+      recordId: input.recordId,
+      data: input.data,
+      previousData: input.previousData,
+      sequenceNumber,
+      causalDeps,
+      schemaVersion: env.schema.version,
+      ...input.atomicOps !== void 0 ? { atomicOps: input.atomicOps } : {},
+      ...env.transactionId !== void 0 ? { transactionId: env.transactionId } : {},
+      ...env.mutationName !== void 0 ? { mutationName: env.mutationName } : {}
+    },
+    env.clock
+  );
+  const maxBytes = env.maxOperationBytes ?? import_core10.DEFAULT_MAX_OPERATION_BYTES;
+  const bytes = (0, import_core10.measureOperationBytes)(operation);
+  if (bytes > maxBytes) {
+    throw new import_core10.OperationTooLargeError(input.collection, input.recordId, bytes, maxBytes);
+  }
+  scope.causal.record(input.collection, operation.id);
+  return operation;
+}
+async function appendOperationRow(scope, operation) {
+  const opInsert = buildInsertQuery(
+    `_kora_ops_${operation.collection}`,
+    serializeOperation(operation)
+  );
+  await scope.tx.execute(opInsert.sql, opInsert.params);
+}
+async function readLiveRow(scope, collection, id) {
+  const rows = await scope.tx.query(
+    `SELECT * FROM ${(0, import_core10.quoteIdent)(collection)} WHERE id = ? AND _deleted = 0`,
     [id]
   );
-  const row = rows[0];
-  if (!row) {
-    throw new RecordNotFoundError(ctx.collection, id);
+  return rows[0];
+}
+function requireDefinition(env, collection) {
+  const definition = env.schema.collections[collection];
+  if (!definition) {
+    throw new import_core10.KoraError(
+      `Unknown collection "${collection}". Available: ${Object.keys(env.schema.collections).join(", ")}`,
+      "UNKNOWN_COLLECTION",
+      { collection }
+    );
   }
-  return deserializeRecord(row, ctx.definition.fields);
+  return definition;
+}
+
+// src/mutations/execute-insert.ts
+async function executeInsert(ctx, data) {
+  const prepared = await prepareInsert(ctx, ctx.collection, data);
+  const result = await runLocalWrite(
+    ctx,
+    (scope) => writeInsertInTx(ctx, scope, prepared, ctx.extraCausalDeps ?? [])
+  );
+  return result.record;
+}
+
+// src/mutations/execute-update.ts
+var import_core11 = require("@korajs/core");
+async function executeUpdate(ctx, id, data) {
+  const validated = (0, import_core11.validateRecord)(ctx.collection, ctx.definition, data, "update");
+  const result = await runLocalWrite(
+    ctx,
+    (scope) => writeUpdateInTx(ctx, scope, ctx.collection, id, validated, ctx.extraCausalDeps ?? [])
+  );
+  return result.record;
 }
 
 // src/mutations/execute-delete.ts
-var import_core9 = require("@korajs/core");
 async function executeDelete(ctx, id, options) {
-  const currentRows = await ctx.adapter.query(
-    `SELECT * FROM ${(0, import_core9.quoteIdent)(ctx.collection)} WHERE id = ? AND _deleted = 0`,
-    [id]
+  const result = await runLocalWrite(
+    ctx,
+    (scope) => writeDeleteInTx(ctx, scope, ctx.collection, id, {
+      skipReferentialEnforcement: options?.skipReferentialEnforcement ?? false,
+      extraCausalDeps: ctx.extraCausalDeps ?? []
+    })
   );
-  if (!currentRows[0]) {
-    throw new RecordNotFoundError(ctx.collection, id);
-  }
-  const causalDeps = resolveCausalDeps(ctx);
-  let operation = options?.operation;
-  const cascadedOps = [];
-  await ctx.adapter.transaction(async (tx) => {
-    if (!operation) {
-      const sequenceNumber = await allocateNextSequenceInTransaction(tx, ctx.nodeId);
-      operation = await (0, import_core9.createOperation)(
-        {
-          nodeId: ctx.nodeId,
-          type: "delete",
-          collection: ctx.collection,
-          recordId: id,
-          data: null,
-          previousData: null,
-          sequenceNumber,
-          causalDeps,
-          schemaVersion: ctx.schema.version
-        },
-        ctx.clock
-      );
-      ctx.causalTracker?.afterOperation(ctx.collection, operation.id, ctx.inTransaction);
+  return result.operation ? [result.operation, ...result.sideEffects] : result.sideEffects;
+}
+
+// src/sync/sync-state.ts
+var import_core12 = require("@korajs/core");
+
+// src/sync/sync-durability.ts
+var OWN_ACKED_THROUGH_META_KEY = "own_acked_through";
+
+// src/sync/local-sync-records.ts
+var TERMINAL_REJECTIONS_TABLE = "_kora_terminal_rejections";
+var LOCAL_NODES_TABLE = "_kora_local_nodes";
+var TERMINAL_REJECTIONS_DDL = `CREATE TABLE IF NOT EXISTS ${TERMINAL_REJECTIONS_TABLE} (
+  operation_id TEXT PRIMARY KEY NOT NULL,
+  node_id TEXT,
+  sequence_number INTEGER,
+  code TEXT NOT NULL,
+  rejected_at INTEGER NOT NULL
+)`;
+var LOCAL_NODES_DDL = `CREATE TABLE IF NOT EXISTS ${LOCAL_NODES_TABLE} (
+  node_id TEXT PRIMARY KEY NOT NULL,
+  created_at INTEGER NOT NULL,
+  accepted INTEGER NOT NULL DEFAULT 0,
+  held INTEGER NOT NULL DEFAULT 0,
+  refused_cycle INTEGER,
+  principal TEXT,
+  binding TEXT,
+  refused_principals TEXT
+)`;
+async function hasUnsyncedOwnOperations(db) {
+  const tables = new Set(
+    (await db.query("SELECT name FROM sqlite_master WHERE type = 'table'")).map(
+      (row) => row.name
+    )
+  );
+  const opsTables = [...tables].filter((name) => name.startsWith("_kora_ops_"));
+  if (opsTables.length === 0 || !tables.has("_kora_meta")) return false;
+  const nodes = /* @__PURE__ */ new Set();
+  if (tables.has(LOCAL_NODES_TABLE)) {
+    for (const row of await db.query(
+      `SELECT node_id FROM ${LOCAL_NODES_TABLE}`
+    )) {
+      nodes.add(row.node_id);
     }
-    if (ctx.relationEnforcer && !options?.skipReferentialEnforcement) {
-      const enforcementResult = await ctx.relationEnforcer.enforceDelete(ctx.collection, id, tx, [
-        operation.id
-      ]);
-      cascadedOps.push(...enforcementResult.operations);
+  }
+  const meta = await db.query(
+    "SELECT key, value FROM _kora_meta WHERE key = 'node_id' OR key = ? OR key LIKE ?",
+    [OWN_ACKED_THROUGH_META_KEY, `${OWN_ACKED_THROUGH_META_KEY}:%`]
+  );
+  const prefixes = /* @__PURE__ */ new Map();
+  for (const row of meta) {
+    if (row.key === "node_id") {
+      nodes.add(row.value);
+    } else if (row.key === OWN_ACKED_THROUGH_META_KEY) {
+      try {
+        const parsed = JSON.parse(row.value);
+        if (typeof parsed.nodeId === "string") {
+          nodes.add(parsed.nodeId);
+          if (typeof parsed.sequence === "number") prefixes.set(parsed.nodeId, parsed.sequence);
+        }
+      } catch {
+      }
+    } else {
+      const nodeId = row.key.slice(OWN_ACKED_THROUGH_META_KEY.length + 1);
+      const sequence = Number(row.value);
+      if (!prefixes.has(nodeId) && Number.isInteger(sequence)) prefixes.set(nodeId, sequence);
     }
-    const version = serializeRowVersion(operation.timestamp);
-    const deleteQuery = buildSoftDeleteQuery(
-      ctx.collection,
-      id,
-      operation.timestamp.wallTime,
-      version
-    );
-    const opInsert = buildInsertQuery(
-      `_kora_ops_${ctx.collection}`,
-      serializeOperation(operation)
-    );
-    await tx.execute(deleteQuery.sql, deleteQuery.params);
-    await tx.execute(opInsert.sql, opInsert.params);
-  });
-  if (!operation) {
-    throw new Error("Delete operation was not created");
   }
-  ctx.onMutation(ctx.collection, operation);
-  for (const cascadedOp of cascadedOps) {
-    ctx.onMutation(cascadedOp.collection, cascadedOp);
+  const exclude = tables.has(TERMINAL_REJECTIONS_TABLE) ? ` AND id NOT IN (SELECT operation_id FROM ${TERMINAL_REJECTIONS_TABLE})` : "";
+  for (const nodeId of nodes) {
+    const prefix = prefixes.get(nodeId) ?? 0;
+    for (const table of opsTables) {
+      const rows = await db.query(
+        `SELECT COUNT(*) AS n FROM "${table.replace(/"/g, '""')}" WHERE node_id = ? AND sequence_number > ?${exclude}`,
+        [nodeId, prefix]
+      );
+      if (Number(rows[0]?.n ?? 0) > 0) return true;
+    }
   }
-  return [operation, ...cascadedOps];
+  return false;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -875,8 +1191,8 @@ async function executeDelete(ctx, id, options) {
   executeDelete,
   executeInsert,
   executeUpdate,
+  hasUnsyncedOwnOperations,
   isIncomingNewerThanRow,
-  resolveCausalDeps,
   rowVersionFromRecord,
   serializeOperation,
   serializeRecord,