@korajs/core 0.3.2 → 0.5.0

package/dist/index.cjs

@@ -20,36 +20,70 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  APPLY_FAILURE_CODES: () => APPLY_FAILURE_CODES,
+  APPLY_RESULTS: () => APPLY_RESULTS,
   ArrayFieldBuilder: () => ArrayFieldBuilder,
   CONNECTION_QUALITIES: () => CONNECTION_QUALITIES,
+  CausalTracker: () => CausalTracker,
   ClockDriftError: () => ClockDriftError,
   EnumFieldBuilder: () => EnumFieldBuilder,
   FieldBuilder: () => FieldBuilder,
   HybridLogicalClock: () => HybridLogicalClock,
+  KORA_ERROR_FIX_SUGGESTIONS: () => KORA_ERROR_FIX_SUGGESTIONS,
   KoraError: () => KoraError,
   MERGE_STRATEGIES: () => MERGE_STRATEGIES,
   MergeConflictError: () => MergeConflictError,
+  MigrationBuilder: () => MigrationBuilder,
+  MigrationRollbackError: () => MigrationRollbackError,
   OperationError: () => OperationError,
+  RollbackBuilder: () => RollbackBuilder,
   SchemaValidationError: () => SchemaValidationError,
   StorageError: () => StorageError,
   SyncError: () => SyncError,
   advanceVector: () => advanceVector,
+  applyOperationTransforms: () => applyOperationTransforms,
+  buildScopeMap: () => buildScopeMap,
+  buildStateMachineConstraints: () => buildStateMachineConstraints,
+  canAutoRollback: () => canAutoRollback,
+  collectSchemaScopeFields: () => collectSchemaScopeFields,
+  collectSchemaScopeValueKeys: () => collectSchemaScopeValueKeys,
   computeDelta: () => computeDelta,
   createOperation: () => createOperation,
+  createReversibleMigration: () => createReversibleMigration,
   createVersionVector: () => createVersionVector,
+  defaultApplyFailureReason: () => defaultApplyFailureReason,
+  defaultSequenceFormat: () => defaultSequenceFormat,
   defineSchema: () => defineSchema,
   deserializeVector: () => deserializeVector,
   dominates: () => dominates,
+  extractScopeValuesFromClaims: () => extractScopeValuesFromClaims,
   extractTimestamp: () => extractTimestamp,
+  formatSequenceValue: () => formatSequenceValue,
   generateFullDDL: () => generateFullDDL,
+  generateProtoDefinitions: () => generateProtoDefinitions,
+  generateRollbackSteps: () => generateRollbackSteps,
   generateSQL: () => generateSQL,
   generateUUIDv7: () => generateUUIDv7,
+  getCollectionScopeBindings: () => getCollectionScopeBindings,
+  getKoraErrorFix: () => getKoraErrorFix,
+  getTransitionMap: () => getTransitionMap,
+  hasSchemaSyncRules: () => hasSchemaSyncRules,
+  isApplyFailure: () => isApplyFailure,
+  isAtomicOp: () => isAtomicOp,
+  isCollectionSyncScoped: () => isCollectionSyncScoped,
   isValidOperation: () => isValidOperation,
   isValidUUIDv7: () => isValidUUIDv7,
   mergeVectors: () => mergeVectors,
+  migrate: () => migrate,
+  migrationStepsToSQL: () => migrationStepsToSQL,
+  op: () => op,
+  resolveAtomicOp: () => resolveAtomicOp,
+  rollbackStepsToSQL: () => rollbackStepsToSQL,
   serializeVector: () => serializeVector,
   t: () => t,
+  toAtomicOp: () => toAtomicOp,
   validateRecord: () => validateRecord,
+  validateTransition: () => validateTransition,
   vectorsEqual: () => vectorsEqual,
   verifyOperationIntegrity: () => verifyOperationIntegrity
 });
@@ -65,6 +99,23 @@ var MERGE_STRATEGIES = [
 ];
 var CONNECTION_QUALITIES = ["excellent", "good", "fair", "poor", "offline"];
 
+// src/errors/error-fixes.ts
+var KORA_ERROR_FIX_SUGGESTIONS = {
+  SCHEMA_VALIDATION: "Review your defineSchema() definition: every collection needs at least one field and a positive version.",
+  OPERATION_ERROR: "Check the operation payload matches your schema field types and required fields.",
+  MERGE_CONFLICT: "Add a custom resolver for the conflicting field in defineSchema(), or adjust constraint onConflict rules.",
+  SYNC_ERROR: "Verify the sync server URL, auth token, and that the server accepts your schema version.",
+  STORAGE_ERROR: "Confirm the storage adapter is supported in this environment and the database path is writable.",
+  CLOCK_DRIFT: "Sync device wall-clock time (NTP). Kora refuses new timestamps when drift exceeds five minutes.",
+  PERSISTENCE_ERROR: "IndexedDB persistence failed; check browser storage settings and available disk quota.",
+  MISSING_WORKER_URL: "Pass store.workerUrl pointing to sqlite-wasm-worker.js (see create-kora-app templates).",
+  INVALID_SYNC_URL: "Use ws:// or wss:// for WebSocket transport, or http(s):// for HTTP long-polling.",
+  APP_NOT_READY: "Await app.ready before querying or mutating collections, or wrap the tree in <KoraProvider app={app}>."
+};
+function getKoraErrorFix(code) {
+  return KORA_ERROR_FIX_SUGGESTIONS[code];
+}
+
 // src/errors/errors.ts
 var KoraError = class extends Error {
   constructor(message, code, context) {
@@ -75,6 +126,16 @@ var KoraError = class extends Error {
   }
   code;
   context;
+  /**
+   * Actionable hint for resolving this error (from registry or error context).
+   */
+  get fix() {
+    const fromContext = this.context?.fix;
+    if (typeof fromContext === "string" && fromContext.length > 0) {
+      return fromContext;
+    }
+    return getKoraErrorFix(this.code);
+  }
 };
 var SchemaValidationError = class extends KoraError {
   constructor(message, context) {
@@ -172,6 +233,7 @@ var HybridLogicalClock = class {
    */
   receive(remote) {
     const physicalTime = this.timeSource.now();
+    const wasColdStart = this.wallTime === 0;
     if (physicalTime > this.wallTime && physicalTime > remote.wallTime) {
       this.wallTime = physicalTime;
       this.logical = 0;
@@ -183,7 +245,9 @@ var HybridLogicalClock = class {
     } else {
       this.logical++;
     }
-    this.checkDrift(physicalTime);
+    if (!wasColdStart) {
+      this.checkDrift(physicalTime);
+    }
     return { wallTime: this.wallTime, logical: this.logical, nodeId: this.nodeId };
   }
   /**
@@ -232,6 +296,50 @@ var HybridLogicalClock = class {
   }
 };
 
+// src/causal/causal-tracker.ts
+var CausalTracker = class {
+  lastOpIdByCollection = /* @__PURE__ */ new Map();
+  lastTransactionOpId = null;
+  /**
+   * Start a new transaction boundary. Clears in-transaction op ids.
+   */
+  beginTransaction() {
+    this.lastTransactionOpId = null;
+  }
+  /**
+   * Clear the transaction boundary without recording ops (after rollback).
+   */
+  clearTransaction() {
+    this.lastTransactionOpId = null;
+  }
+  /**
+   * Compute causal dependencies for the next operation in a collection.
+   * Uses direct parents only: collection head and the previous op in the open transaction.
+   */
+  nextCausalDeps(collection, inTransaction) {
+    const deps = [];
+    const lastInCollection = this.lastOpIdByCollection.get(collection);
+    if (lastInCollection !== void 0) {
+      deps.push(lastInCollection);
+    }
+    if (inTransaction && this.lastTransactionOpId !== null) {
+      if (!deps.includes(this.lastTransactionOpId)) {
+        deps.push(this.lastTransactionOpId);
+      }
+    }
+    return deps;
+  }
+  /**
+   * Record an operation after it has been created and assigned an id.
+   */
+  afterOperation(collection, operationId, inTransaction) {
+    this.lastOpIdByCollection.set(collection, operationId);
+    if (inTransaction) {
+      this.lastTransactionOpId = operationId;
+    }
+  }
+};
+
 // src/identifiers/uuid-v7.ts
 var defaultRandom = globalThis.crypto;
 function generateUUIDv7(timestamp = Date.now(), randomSource = defaultRandom) {
@@ -268,23 +376,61 @@ function formatUUID(bytes) {
   return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
 }
 
+// src/operations/apply-result.ts
+var APPLY_RESULTS = ["applied", "duplicate", "skipped", "rejected", "deferred"];
+var APPLY_FAILURE_CODES = {
+  APPLY_FAILED: "APPLY_FAILED",
+  APPLY_SKIPPED: "APPLY_SKIPPED",
+  APPLY_REJECTED: "APPLY_REJECTED",
+  APPLY_DEFERRED: "APPLY_DEFERRED",
+  CLOCK_DRIFT: "CLOCK_DRIFT",
+  REFERENTIAL_INTEGRITY: "REFERENTIAL_INTEGRITY",
+  SCHEMA_MISMATCH: "SCHEMA_MISMATCH"
+};
+function isApplyFailure(result) {
+  return result === "skipped" || result === "rejected" || result === "deferred";
+}
+function defaultApplyFailureReason(result, overrides) {
+  const base = result === "deferred" ? {
+    code: APPLY_FAILURE_CODES.APPLY_DEFERRED,
+    message: "Operation apply was deferred.",
+    retriable: true
+  } : result === "rejected" ? {
+    code: APPLY_FAILURE_CODES.APPLY_REJECTED,
+    message: "Operation apply was rejected.",
+    retriable: false
+  } : {
+    code: APPLY_FAILURE_CODES.APPLY_SKIPPED,
+    message: "Operation apply was skipped.",
+    retriable: false
+  };
+  return { ...base, ...overrides };
+}
+
 // src/operations/content-hash.ts
 async function computeOperationId(input, timestamp) {
-  const canonical = canonicalize({
+  const hashInput = {
     type: input.type,
     collection: input.collection,
     recordId: input.recordId,
     data: input.data,
     timestamp,
     nodeId: input.nodeId
-  });
+  };
+  if (input.atomicOps !== void 0 && Object.keys(input.atomicOps).length > 0) {
+    hashInput.atomicOps = input.atomicOps;
+  }
+  const canonical = canonicalize(hashInput);
   const encoded = new TextEncoder().encode(canonical);
   const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", encoded);
   return bufferToHex(hashBuffer);
 }
 function canonicalize(obj) {
-  if (obj === null || obj === void 0) {
-    return JSON.stringify(obj);
+  if (obj === null) {
+    return "null";
+  }
+  if (obj === void 0) {
+    return "null";
   }
   if (typeof obj !== "object") {
     return JSON.stringify(obj);
@@ -296,7 +442,7 @@ function canonicalize(obj) {
   const keys = Object.keys(obj).sort();
   const pairs = keys.map((key) => {
     const value = obj[key];
-    return `${JSON.stringify(key)}:${canonicalize(value)}`;
+    return `${JSON.stringify(key)}:${canonicalize(value === void 0 ? null : value)}`;
   });
   return `{${pairs.join(",")}}`;
 }
@@ -322,7 +468,10 @@ async function createOperation(input, clock) {
     timestamp,
     sequenceNumber: input.sequenceNumber,
     causalDeps: [...input.causalDeps],
-    schemaVersion: input.schemaVersion
+    schemaVersion: input.schemaVersion,
+    ...input.atomicOps !== void 0 && Object.keys(input.atomicOps).length > 0 ? { atomicOps: { ...input.atomicOps } } : {},
+    ...input.transactionId !== void 0 ? { transactionId: input.transactionId } : {},
+    ...input.mutationName !== void 0 ? { mutationName: input.mutationName } : {}
   };
   return deepFreeze(operation);
 }
@@ -390,29 +539,31 @@ function validateOperationParams(input) {
     });
   }
 }
-async function verifyOperationIntegrity(op) {
+async function verifyOperationIntegrity(op2) {
   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
+    nodeId: op2.nodeId,
+    type: op2.type,
+    collection: op2.collection,
+    recordId: op2.recordId,
+    data: op2.data,
+    previousData: op2.previousData,
+    sequenceNumber: op2.sequenceNumber,
+    causalDeps: op2.causalDeps,
+    schemaVersion: op2.schemaVersion,
+    ...op2.atomicOps !== void 0 ? { atomicOps: op2.atomicOps } : {}
   };
-  const serializedTs = HybridLogicalClock.serialize(op.timestamp);
+  const serializedTs = HybridLogicalClock.serialize(op2.timestamp);
   const expectedId = await computeOperationId(input, serializedTs);
-  return op.id === expectedId;
+  return op2.id === expectedId;
 }
 function isValidOperation(value) {
   if (typeof value !== "object" || value === null) return false;
-  const op = value;
-  return typeof op.id === "string" && typeof op.nodeId === "string" && (op.type === "insert" || op.type === "update" || op.type === "delete") && typeof op.collection === "string" && typeof op.recordId === "string" && typeof op.sequenceNumber === "number" && Array.isArray(op.causalDeps) && typeof op.schemaVersion === "number" && typeof op.timestamp === "object" && op.timestamp !== null;
+  const op2 = value;
+  return typeof op2.id === "string" && typeof op2.nodeId === "string" && (op2.type === "insert" || op2.type === "update" || op2.type === "delete") && typeof op2.collection === "string" && typeof op2.recordId === "string" && typeof op2.sequenceNumber === "number" && Array.isArray(op2.causalDeps) && typeof op2.schemaVersion === "number" && typeof op2.timestamp === "object" && op2.timestamp !== null;
 }
 function deepFreeze(obj) {
   if (typeof obj !== "object" || obj === null) return obj;
+  if (ArrayBuffer.isView(obj)) return obj;
   Object.freeze(obj);
   for (const value of Object.values(obj)) {
     if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
@@ -422,10 +573,257 @@ function deepFreeze(obj) {
   return obj;
 }
 
+// src/operations/atomic-ops.ts
+var KORA_ATOMIC_OP = /* @__PURE__ */ Symbol.for("kora.atomic_op");
+function isAtomicOp(value) {
+  return typeof value === "object" && value !== null && KORA_ATOMIC_OP in value && value[KORA_ATOMIC_OP] === true;
+}
+function resolveAtomicOp(currentValue, sentinel) {
+  switch (sentinel.type) {
+    case "increment": {
+      const current = typeof currentValue === "number" ? currentValue : 0;
+      const operand = sentinel.value;
+      return current + operand;
+    }
+    case "max": {
+      const current = typeof currentValue === "number" ? currentValue : Number.NEGATIVE_INFINITY;
+      return Math.max(current, sentinel.value);
+    }
+    case "min": {
+      const current = typeof currentValue === "number" ? currentValue : Number.POSITIVE_INFINITY;
+      return Math.min(current, sentinel.value);
+    }
+    case "append": {
+      const current = Array.isArray(currentValue) ? [...currentValue] : [];
+      current.push(sentinel.value);
+      return current;
+    }
+    case "remove": {
+      if (!Array.isArray(currentValue)) return [];
+      return currentValue.filter((item) => item !== sentinel.value);
+    }
+  }
+}
+function createSentinel(type, value) {
+  return Object.freeze({
+    [KORA_ATOMIC_OP]: true,
+    type,
+    value
+  });
+}
+var op = {
+  /**
+   * Increment a number field by the given amount.
+   * Concurrent increments compose: the sum of all deltas is applied to the base.
+   *
+   * @param n - The amount to increment (use negative values to decrement)
+   */
+  increment(n) {
+    return createSentinel("increment", n);
+  },
+  /**
+   * Decrement a number field by the given amount.
+   * Syntactic sugar for `op.increment(-n)`.
+   *
+   * @param n - The amount to decrement
+   */
+  decrement(n) {
+    return createSentinel("increment", -n);
+  },
+  /**
+   * Set the field to the maximum of the current value and the given value.
+   * Concurrent max operations take the maximum of all values.
+   *
+   * @param n - The value to compare against the current value
+   */
+  max(n) {
+    return createSentinel("max", n);
+  },
+  /**
+   * Set the field to the minimum of the current value and the given value.
+   * Concurrent min operations take the minimum of all values.
+   *
+   * @param n - The value to compare against the current value
+   */
+  min(n) {
+    return createSentinel("min", n);
+  },
+  /**
+   * Append an item to an array field.
+   * Concurrent appends include all appended items.
+   *
+   * @param item - The item to append to the array
+   */
+  append(item) {
+    return createSentinel("append", item);
+  },
+  /**
+   * Remove an item from an array field (by value equality).
+   * Concurrent removes of the same item are idempotent.
+   *
+   * @param item - The item to remove from the array
+   */
+  remove(item) {
+    return createSentinel("remove", item);
+  }
+};
+function toAtomicOp(sentinel) {
+  return { type: sentinel.type, value: sentinel.value };
+}
+
+// src/scopes/sync-scope-bindings.ts
+function hasSchemaSyncRules(schema) {
+  return schema.sync !== void 0 && Object.keys(schema.sync).length > 0;
+}
+function getCollectionScopeBindings(schema, collectionName) {
+  const syncRule = schema.sync?.[collectionName];
+  if (syncRule && Object.keys(syncRule.where).length > 0) {
+    return { ...syncRule.where };
+  }
+  const scopeFields = schema.collections[collectionName]?.scope ?? [];
+  if (scopeFields.length === 0) {
+    return null;
+  }
+  const bindings = {};
+  for (const field of scopeFields) {
+    bindings[field] = field;
+  }
+  return bindings;
+}
+function isCollectionSyncScoped(schema, collectionName) {
+  if (hasSchemaSyncRules(schema)) {
+    if (schema.sync?.[collectionName]) {
+      return true;
+    }
+    const legacyScope = schema.collections[collectionName]?.scope ?? [];
+    return legacyScope.length > 0;
+  }
+  return getCollectionScopeBindings(schema, collectionName) !== null;
+}
+function collectSchemaScopeValueKeys(schema) {
+  const keys = /* @__PURE__ */ new Set();
+  for (const collection of Object.values(schema.collections)) {
+    for (const field of collection.scope) {
+      keys.add(field);
+    }
+  }
+  if (schema.sync) {
+    for (const rule of Object.values(schema.sync)) {
+      for (const scopeKey of Object.values(rule.where)) {
+        keys.add(scopeKey);
+      }
+    }
+  }
+  return [...keys];
+}
+function normalizeSyncRuleWhere(collectionName, where) {
+  const normalized = {};
+  for (const [field, scopeKey] of Object.entries(where)) {
+    if (scopeKey === true) {
+      normalized[field] = field;
+      continue;
+    }
+    if (typeof scopeKey === "string" && scopeKey.length > 0) {
+      normalized[field] = scopeKey;
+      continue;
+    }
+    throw new Error(
+      `Invalid sync rule for collection "${collectionName}": where.${field} must be true or a non-empty scope key string`
+    );
+  }
+  return normalized;
+}
+
+// src/state-machine/state-machine.ts
+function validateTransition(constraint, fromValue, toValue) {
+  const from = String(fromValue);
+  const to = String(toValue);
+  const allowedTargets = constraint.transitions[from] ?? [];
+  return {
+    valid: allowedTargets.includes(to),
+    from,
+    to,
+    field: constraint.field,
+    collection: constraint.collection,
+    allowedTargets
+  };
+}
+function buildStateMachineConstraints(schema) {
+  const constraints = [];
+  for (const [collectionName, collection] of Object.entries(schema.collections)) {
+    for (const [fieldName, descriptor] of Object.entries(collection.fields)) {
+      if (descriptor.kind === "enum" && descriptor.transitions !== null) {
+        constraints.push({
+          field: fieldName,
+          collection: collectionName,
+          transitions: descriptor.transitions
+        });
+      }
+    }
+  }
+  return constraints;
+}
+function getTransitionMap(schema, collection, field) {
+  const collectionDef = schema.collections[collection];
+  if (!collectionDef) {
+    return null;
+  }
+  const fieldDef = collectionDef.fields[field];
+  if (!fieldDef || fieldDef.kind !== "enum") {
+    return null;
+  }
+  return fieldDef.transitions;
+}
+function validateStateMachineDefinition(collectionName, sm, fields) {
+  const fieldDef = fields[sm.field];
+  if (!fieldDef) {
+    throw new SchemaValidationError(
+      `State machine field "${sm.field}" does not exist in collection "${collectionName}". Available fields: ${Object.keys(fields).join(", ")}`,
+      { collection: collectionName, field: sm.field }
+    );
+  }
+  if (fieldDef.kind !== "enum") {
+    throw new SchemaValidationError(
+      `State machine field "${sm.field}" in collection "${collectionName}" must be an enum field, but got "${fieldDef.kind}"`,
+      { collection: collectionName, field: sm.field, kind: fieldDef.kind }
+    );
+  }
+  const enumValues = fieldDef.enumValues;
+  if (!enumValues || enumValues.length === 0) {
+    throw new SchemaValidationError(
+      `State machine field "${sm.field}" in collection "${collectionName}" has no enum values defined`,
+      { collection: collectionName, field: sm.field }
+    );
+  }
+  const validValues = new Set(enumValues);
+  for (const [state, targets] of Object.entries(sm.transitions)) {
+    if (!validValues.has(state)) {
+      throw new SchemaValidationError(
+        `State machine transition source "${state}" is not a valid enum value for field "${sm.field}" in collection "${collectionName}". Valid values: ${[...validValues].join(", ")}`,
+        { collection: collectionName, field: sm.field, state }
+      );
+    }
+    for (const target of targets) {
+      if (!validValues.has(target)) {
+        throw new SchemaValidationError(
+          `State machine transition target "${target}" is not a valid enum value for field "${sm.field}" in collection "${collectionName}". Valid values: ${[...validValues].join(", ")}`,
+          { collection: collectionName, field: sm.field, state, target }
+        );
+      }
+    }
+  }
+  if (sm.onInvalidTransition !== "reject" && sm.onInvalidTransition !== "last-valid-state") {
+    throw new SchemaValidationError(
+      `State machine onInvalidTransition must be "reject" or "last-valid-state", got "${sm.onInvalidTransition}" in collection "${collectionName}"`,
+      { collection: collectionName, onInvalidTransition: sm.onInvalidTransition }
+    );
+  }
+}
+
 // src/schema/define.ts
 var COLLECTION_NAME_RE = /^[a-z][a-z0-9_]*$/;
 var FIELD_NAME_RE = /^[a-z][a-zA-Z0-9_]*$/;
-var RESERVED_FIELDS = /* @__PURE__ */ new Set(["id", "_created_at", "_updated_at", "_deleted"]);
+var RESERVED_FIELDS = /* @__PURE__ */ new Set(["id", "_created_at", "_updated_at", "_version", "_deleted"]);
 function defineSchema(input) {
   validateVersion(input.version);
   const collections = {};
@@ -443,7 +841,40 @@ function defineSchema(input) {
       relations[name] = { ...relationInput };
     }
   }
-  return { version: input.version, collections, relations };
+  const migrations = {};
+  if (input.migrations) {
+    for (const [versionStr, migration] of Object.entries(input.migrations)) {
+      const version = Number(versionStr);
+      if (!Number.isInteger(version) || version < 2) {
+        throw new SchemaValidationError(
+          `Migration key "${versionStr}" is invalid. Must be an integer >= 2 (version 1 is the initial schema).`,
+          { version: versionStr }
+        );
+      }
+      if (version > input.version) {
+        throw new SchemaValidationError(
+          `Migration version ${version} exceeds schema version ${input.version}. Migrations must target versions <= schema version.`,
+          { migrationVersion: version, schemaVersion: input.version }
+        );
+      }
+      if (!migration.steps || migration.steps.length === 0) {
+        throw new SchemaValidationError(
+          `Migration for version ${version} has no steps. Use migrate() to define at least one step.`,
+          { version }
+        );
+      }
+      migrations[version] = migration;
+    }
+  }
+  const sync = buildSyncRules(input.sync, collections);
+  applySyncRulesToCollectionScope(collections, sync);
+  return {
+    version: input.version,
+    collections,
+    relations,
+    migrations,
+    ...sync ? { sync } : {}
+  };
 }
 function validateVersion(version) {
   if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
@@ -505,7 +936,81 @@ function buildCollection(name, input) {
       resolvers[fieldName] = resolver;
     }
   }
-  return { fields, indexes, constraints, resolvers };
+  const scope = [];
+  if (input.scope) {
+    for (const scopeField of input.scope) {
+      if (!(scopeField in fields)) {
+        throw new SchemaValidationError(
+          `Scope field "${scopeField}" does not exist in collection "${name}". Available fields: ${Object.keys(fields).join(", ")}`,
+          { collection: name, field: scopeField }
+        );
+      }
+      scope.push(scopeField);
+    }
+  }
+  let stateMachine;
+  if (input.stateMachine) {
+    validateStateMachineDefinition(name, input.stateMachine, fields);
+    stateMachine = { ...input.stateMachine };
+  }
+  return { fields, indexes, constraints, resolvers, scope, stateMachine };
+}
+function buildSyncRules(syncInput, collections) {
+  if (!syncInput) {
+    return void 0;
+  }
+  const sync = {};
+  for (const [collectionName, ruleInput] of Object.entries(syncInput)) {
+    if (!(collectionName in collections)) {
+      throw new SchemaValidationError(
+        `Sync rule references collection "${collectionName}" which does not exist. Available collections: ${Object.keys(collections).join(", ")}`,
+        { collection: collectionName }
+      );
+    }
+    if (!ruleInput.where || Object.keys(ruleInput.where).length === 0) {
+      throw new SchemaValidationError(
+        `Sync rule for collection "${collectionName}" must declare at least one where binding`,
+        { collection: collectionName }
+      );
+    }
+    const collection = collections[collectionName];
+    if (!collection) {
+      continue;
+    }
+    for (const fieldName of Object.keys(ruleInput.where)) {
+      if (!(fieldName in collection.fields)) {
+        throw new SchemaValidationError(
+          `Sync rule where field "${fieldName}" does not exist in collection "${collectionName}". Available fields: ${Object.keys(collection.fields).join(", ")}`,
+          { collection: collectionName, field: fieldName }
+        );
+      }
+    }
+    try {
+      sync[collectionName] = { where: normalizeSyncRuleWhere(collectionName, ruleInput.where) };
+    } catch (error) {
+      throw new SchemaValidationError(
+        error instanceof Error ? error.message : "Invalid sync rule",
+        { collection: collectionName }
+      );
+    }
+  }
+  return sync;
+}
+function applySyncRulesToCollectionScope(collections, sync) {
+  if (!sync) {
+    return;
+  }
+  for (const [collectionName, rule] of Object.entries(sync)) {
+    const collection = collections[collectionName];
+    if (!collection) {
+      continue;
+    }
+    for (const fieldName of Object.keys(rule.where)) {
+      if (!collection.scope.includes(fieldName)) {
+        collection.scope.push(fieldName);
+      }
+    }
+  }
 }
 function validateFieldName(collection, fieldName) {
   if (RESERVED_FIELDS.has(fieldName)) {
@@ -594,6 +1099,7 @@ function generateSQL(collectionName, collection, relations) {
   }
   columns.push("_created_at INTEGER NOT NULL");
   columns.push("_updated_at INTEGER NOT NULL");
+  columns.push("_version TEXT NOT NULL DEFAULT ''");
   columns.push("_deleted INTEGER NOT NULL DEFAULT 0");
   statements.push(`CREATE TABLE IF NOT EXISTS ${collectionName} (
   ${columns.join(",\n  ")}
@@ -603,6 +1109,10 @@ function generateSQL(collectionName, collection, relations) {
     statements.push(`--kora:safe-alter
 ALTER TABLE ${collectionName} ADD COLUMN ${colDef}`);
   }
+  statements.push(
+    `--kora:safe-alter
+ALTER TABLE ${collectionName} ADD COLUMN _version TEXT NOT NULL DEFAULT ''`
+  );
   for (const indexField of collection.indexes) {
     statements.push(
       `CREATE INDEX IF NOT EXISTS idx_${collectionName}_${indexField} ON ${collectionName} (${indexField})`
@@ -639,6 +1149,21 @@ function generateFullDDL(schema) {
   statements.push(
     "CREATE TABLE IF NOT EXISTS _kora_version_vector (\n  node_id TEXT PRIMARY KEY NOT NULL,\n  sequence_number INTEGER NOT NULL\n)"
   );
+  statements.push(
+    "CREATE TABLE IF NOT EXISTS _kora_sequences (\n  name TEXT NOT NULL,\n  scope TEXT NOT NULL DEFAULT '',\n  node_id TEXT NOT NULL,\n  counter INTEGER NOT NULL DEFAULT 0,\n  PRIMARY KEY (name, scope, node_id)\n)"
+  );
+  statements.push(
+    "CREATE TABLE IF NOT EXISTS _kora_sync_queue (\n  id TEXT PRIMARY KEY NOT NULL,\n  payload TEXT NOT NULL\n)"
+  );
+  statements.push(
+    "CREATE TABLE IF NOT EXISTS _kora_audit_traces (\n  id TEXT PRIMARY KEY NOT NULL,\n  recorded_at INTEGER NOT NULL,\n  event_type TEXT NOT NULL,\n  collection TEXT NOT NULL,\n  record_id TEXT NOT NULL,\n  field TEXT NOT NULL,\n  strategy TEXT NOT NULL,\n  tier INTEGER NOT NULL,\n  constraint_name TEXT,\n  trace_json TEXT NOT NULL\n)"
+  );
+  statements.push(
+    "CREATE INDEX IF NOT EXISTS idx_kora_audit_traces_recorded_at ON _kora_audit_traces (recorded_at)"
+  );
+  statements.push(
+    "CREATE INDEX IF NOT EXISTS idx_kora_audit_traces_collection ON _kora_audit_traces (collection)"
+  );
   for (const [name, collection] of Object.entries(schema.collections)) {
     statements.push(...generateSQL(name, collection, schema.relations));
   }
@@ -692,23 +1217,47 @@ var FieldBuilder = class _FieldBuilder {
   _required;
   _defaultValue;
   _auto;
-  constructor(kind, required = true, defaultValue = void 0, auto = false) {
+  _mergeStrategy;
+  constructor(kind, required = true, defaultValue = void 0, auto = false, mergeStrategy = null) {
     this._kind = kind;
     this._required = required;
     this._defaultValue = defaultValue;
     this._auto = auto;
+    this._mergeStrategy = mergeStrategy;
   }
   /** Mark this field as optional (not required on insert) */
   optional() {
-    return new _FieldBuilder(this._kind, false, this._defaultValue, this._auto);
+    return new _FieldBuilder(this._kind, false, this._defaultValue, this._auto, this._mergeStrategy);
   }
   /** Set a default value for this field. Implicitly makes the field optional. */
   default(value) {
-    return new _FieldBuilder(this._kind, false, value, this._auto);
+    return new _FieldBuilder(this._kind, false, value, this._auto, this._mergeStrategy);
   }
   /** Mark this field as auto-populated (e.g., createdAt timestamps). Developers cannot set auto fields. */
   auto() {
-    return new _FieldBuilder(this._kind, false, void 0, true);
+    return new _FieldBuilder(this._kind, false, void 0, true, this._mergeStrategy);
+  }
+  /**
+   * Declare a merge strategy for this field.
+   * Controls how concurrent modifications are resolved during sync.
+   *
+   * @param strategy - The merge strategy to use:
+   *   - `'lww'`: Last-write-wins (default for scalar fields)
+   *   - `'counter'`: Sum of deltas from base (for numbers)
+   *   - `'max'`: Keep the maximum value (for numbers/timestamps)
+   *   - `'min'`: Keep the minimum value (for numbers/timestamps)
+   *   - `'union'`: Set-union merge (default for arrays)
+   *   - `'append-only'`: Concatenate additions (for arrays)
+   *   - `'server-authoritative'`: Always prefer the remote/server value
+   */
+  merge(strategy) {
+    return new _FieldBuilder(
+      this._kind,
+      this._required,
+      this._defaultValue,
+      this._auto,
+      strategy
+    );
   }
   /** @internal Build the final FieldDescriptor. Used by defineSchema(). */
   _build() {
@@ -718,24 +1267,102 @@ var FieldBuilder = class _FieldBuilder {
       defaultValue: this._defaultValue,
       auto: this._auto,
       enumValues: null,
-      itemKind: null
+      itemKind: null,
+      mergeStrategy: this._mergeStrategy,
+      transitions: null
     };
   }
 };
 var EnumFieldBuilder = class _EnumFieldBuilder extends FieldBuilder {
   _enumValues;
-  constructor(values, required = true, defaultValue = void 0, auto = false) {
-    super("enum", required, defaultValue, auto);
+  _transitions;
+  constructor(values, required = true, defaultValue = void 0, auto = false, mergeStrategy = null, transitions = null) {
+    super("enum", required, defaultValue, auto, mergeStrategy);
     this._enumValues = values;
+    this._transitions = transitions;
   }
   optional() {
-    return new _EnumFieldBuilder(this._enumValues, false, this._defaultValue, this._auto);
+    return new _EnumFieldBuilder(
+      this._enumValues,
+      false,
+      this._defaultValue,
+      this._auto,
+      this._mergeStrategy,
+      this._transitions
+    );
   }
   default(value) {
-    return new _EnumFieldBuilder(this._enumValues, false, value, this._auto);
+    return new _EnumFieldBuilder(
+      this._enumValues,
+      false,
+      value,
+      this._auto,
+      this._mergeStrategy,
+      this._transitions
+    );
   }
   auto() {
-    return new _EnumFieldBuilder(this._enumValues, false, void 0, true);
+    return new _EnumFieldBuilder(
+      this._enumValues,
+      false,
+      void 0,
+      true,
+      this._mergeStrategy,
+      this._transitions
+    );
+  }
+  merge(strategy) {
+    return new _EnumFieldBuilder(
+      this._enumValues,
+      this._required,
+      this._defaultValue,
+      this._auto,
+      strategy,
+      this._transitions
+    );
+  }
+  /**
+   * Declare allowed state transitions for this enum field.
+   * Enables state machine validation during mutations and merges.
+   *
+   * @param map - Map of state to allowed next states
+   *
+   * @example
+   * ```typescript
+   * t.enum(['draft', 'pending', 'confirmed', 'cancelled']).transitions({
+   *   draft: ['pending', 'cancelled'],
+   *   pending: ['confirmed', 'cancelled'],
+   *   confirmed: [],
+   *   cancelled: [],
+   * })
+   * ```
+   */
+  transitions(map) {
+    const validValues = new Set(this._enumValues);
+    for (const [state, targets] of Object.entries(map)) {
+      if (!validValues.has(state)) {
+        throw new SchemaValidationError(
+          `Invalid source state "${state}" in transition map. Valid values: ${[...validValues].join(", ")}`,
+          { state, validValues: [...validValues] }
+        );
+      }
+      for (const target of targets) {
+        if (!validValues.has(target)) {
+          throw new SchemaValidationError(
+            `Invalid target state "${target}" in transition from "${state}". Valid values: ${[...validValues].join(", ")}`,
+            { state, target, validValues: [...validValues] }
+          );
+        }
+      }
+    }
+    return new _EnumFieldBuilder(
+      this._enumValues,
+      this._required,
+      this._defaultValue,
+      this._auto,
+      this._mergeStrategy,
+      map
+    );
   }
   _build() {
     return {
@@ -744,14 +1371,16 @@ var EnumFieldBuilder = class _EnumFieldBuilder extends FieldBuilder {
       defaultValue: this._defaultValue,
       auto: this._auto,
       enumValues: this._enumValues,
-      itemKind: null
+      itemKind: null,
+      mergeStrategy: this._mergeStrategy,
+      transitions: this._transitions
     };
   }
 };
 var ArrayFieldBuilder = class _ArrayFieldBuilder extends FieldBuilder {
   _itemKind;
-  constructor(itemBuilder, required = true, defaultValue = void 0, auto = false) {
-    super("array", required, defaultValue, auto);
+  constructor(itemBuilder, required = true, defaultValue = void 0, auto = false, mergeStrategy = null) {
+    super("array", required, defaultValue, auto, mergeStrategy);
     this._itemKind = itemBuilder._build().kind;
   }
   optional() {
@@ -759,14 +1388,36 @@ var ArrayFieldBuilder = class _ArrayFieldBuilder extends FieldBuilder {
       new FieldBuilder(this._itemKind),
       false,
       this._defaultValue,
-      this._auto
+      this._auto,
+      this._mergeStrategy
     );
   }
   default(value) {
-    return new _ArrayFieldBuilder(new FieldBuilder(this._itemKind), false, value, this._auto);
+    return new _ArrayFieldBuilder(
+      new FieldBuilder(this._itemKind),
+      false,
+      value,
+      this._auto,
+      this._mergeStrategy
+    );
   }
   auto() {
-    return new _ArrayFieldBuilder(new FieldBuilder(this._itemKind), false, void 0, true);
+    return new _ArrayFieldBuilder(
+      new FieldBuilder(this._itemKind),
+      false,
+      void 0,
+      true,
+      this._mergeStrategy
+    );
+  }
+  merge(strategy) {
+    return new _ArrayFieldBuilder(
+      new FieldBuilder(this._itemKind),
+      this._required,
+      this._defaultValue,
+      this._auto,
+      strategy
+    );
   }
   _build() {
     return {
@@ -775,7 +1426,9 @@ var ArrayFieldBuilder = class _ArrayFieldBuilder extends FieldBuilder {
       defaultValue: this._defaultValue,
       auto: this._auto,
       enumValues: null,
-      itemKind: this._itemKind
+      itemKind: this._itemKind,
+      mergeStrategy: this._mergeStrategy,
+      transitions: null
     };
   }
 };
@@ -829,10 +1482,14 @@ function validateRecord(collection, collectionDef, data, operationType) {
     }
     if (operationType === "update") {
       if (hasValue) {
-        if (value !== void 0 && value !== null) {
+        if (isAtomicOp(value)) {
+          result[fieldName] = value;
+        } else if (value !== void 0 && value !== null) {
           validateFieldValue(collection, fieldName, descriptor, value);
+          result[fieldName] = value;
+        } else {
+          result[fieldName] = value;
         }
-        result[fieldName] = value;
       }
       continue;
     }
@@ -995,34 +1652,34 @@ function matchesJsType(value, expected) {
 function topologicalSort(operations) {
   if (operations.length <= 1) return [...operations];
   const opMap = /* @__PURE__ */ new Map();
-  for (const op of operations) {
-    opMap.set(op.id, op);
+  for (const op2 of operations) {
+    opMap.set(op2.id, op2);
   }
   const inDegree = /* @__PURE__ */ new Map();
   const dependents = /* @__PURE__ */ new Map();
-  for (const op of operations) {
-    if (!inDegree.has(op.id)) {
-      inDegree.set(op.id, 0);
+  for (const op2 of operations) {
+    if (!inDegree.has(op2.id)) {
+      inDegree.set(op2.id, 0);
     }
-    if (!dependents.has(op.id)) {
-      dependents.set(op.id, []);
+    if (!dependents.has(op2.id)) {
+      dependents.set(op2.id, []);
     }
-    for (const depId of op.causalDeps) {
+    for (const depId of op2.causalDeps) {
       if (opMap.has(depId)) {
-        inDegree.set(op.id, (inDegree.get(op.id) ?? 0) + 1);
+        inDegree.set(op2.id, (inDegree.get(op2.id) ?? 0) + 1);
         const deps = dependents.get(depId);
         if (deps) {
-          deps.push(op.id);
+          deps.push(op2.id);
         } else {
-          dependents.set(depId, [op.id]);
+          dependents.set(depId, [op2.id]);
         }
       }
     }
   }
   const heap = new MinHeap(compareByTimestamp);
-  for (const op of operations) {
-    if ((inDegree.get(op.id) ?? 0) === 0) {
-      heap.push(op);
+  for (const op2 of operations) {
+    if ((inDegree.get(op2.id) ?? 0) === 0) {
+      heap.push(op2);
     }
   }
   const result = [];
@@ -1034,8 +1691,8 @@ function topologicalSort(operations) {
       const deg = (inDegree.get(depId) ?? 0) - 1;
       inDegree.set(depId, deg);
       if (deg === 0) {
-        const op = opMap.get(depId);
-        if (op) heap.push(op);
+        const op2 = opMap.get(depId);
+        if (op2) heap.push(op2);
       }
     }
   }
@@ -1076,28 +1733,30 @@ var MinHeap = class {
     return top;
   }
   bubbleUp(index) {
-    while (index > 0) {
-      const parentIndex = index - 1 >> 1;
-      if (this.cmp(this.data[index], this.data[parentIndex]) >= 0) break;
-      this.swap(index, parentIndex);
-      index = parentIndex;
+    let current = index;
+    while (current > 0) {
+      const parentIndex = current - 1 >> 1;
+      if (this.cmp(this.data[current], this.data[parentIndex]) >= 0) break;
+      this.swap(current, parentIndex);
+      current = parentIndex;
     }
   }
   sinkDown(index) {
     const length = this.data.length;
+    let current = index;
     while (true) {
-      let smallest = index;
-      const left = 2 * index + 1;
-      const right = 2 * index + 2;
+      let smallest = current;
+      const left = 2 * current + 1;
+      const right = 2 * current + 2;
       if (left < length && this.cmp(this.data[left], this.data[smallest]) < 0) {
         smallest = left;
       }
       if (right < length && this.cmp(this.data[right], this.data[smallest]) < 0) {
         smallest = right;
       }
-      if (smallest === index) break;
-      this.swap(index, smallest);
-      index = smallest;
+      if (smallest === current) break;
+      this.swap(current, smallest);
+      current = smallest;
     }
   }
   swap(i, j) {
@@ -1136,12 +1795,13 @@ function vectorsEqual(a, b) {
   }
   return true;
 }
-function computeDelta(localVector, remoteVector, operationLog) {
+async function computeDelta(localVector, remoteVector, operationLog) {
   const missing = [];
   for (const [nodeId, localSeq] of localVector) {
     const remoteSeq = remoteVector.get(nodeId) ?? 0;
     if (localSeq > remoteSeq) {
-      missing.push(...operationLog.getRange(nodeId, remoteSeq + 1, localSeq));
+      const ops = await operationLog.getRange(nodeId, remoteSeq + 1, localSeq);
+      missing.push(...ops);
     }
   }
   return topologicalSort(missing);
@@ -1154,38 +1814,716 @@ function deserializeVector(s) {
   const entries = JSON.parse(s);
   return new Map(entries);
 }
+
+// src/scopes/build-scope-map.ts
+function buildScopeMap(schema, scopeValues) {
+  const result = {};
+  const partialSync = hasSchemaSyncRules(schema);
+  for (const collName of Object.keys(schema.collections)) {
+    if (partialSync && !isCollectionSyncScoped(schema, collName)) {
+      continue;
+    }
+    const bindings = getCollectionScopeBindings(schema, collName);
+    if (bindings) {
+      const collScope = {};
+      for (const [field, scopeKey] of Object.entries(bindings)) {
+        if (scopeKey in scopeValues) {
+          collScope[field] = scopeValues[scopeKey];
+        }
+      }
+      result[collName] = collScope;
+    } else {
+      result[collName] = {};
+    }
+  }
+  return result;
+}
+
+// src/scopes/extract-scope-from-claims.ts
+function collectSchemaScopeFields(schema) {
+  return collectSchemaScopeValueKeys(schema);
+}
+function extractScopeValuesFromClaims(schema, claims) {
+  const scopeFields = collectSchemaScopeValueKeys(schema);
+  if (scopeFields.length === 0) {
+    return {};
+  }
+  const nestedScope = claims.scope;
+  const scopeObject = typeof nestedScope === "object" && nestedScope !== null && !Array.isArray(nestedScope) ? nestedScope : {};
+  const result = {};
+  for (const field of scopeFields) {
+    if (field in claims) {
+      result[field] = claims[field];
+      continue;
+    }
+    if (field in scopeObject) {
+      result[field] = scopeObject[field];
+      continue;
+    }
+    if (field === "userId" && typeof claims.sub === "string") {
+      result.userId = claims.sub;
+    }
+  }
+  return result;
+}
+
+// src/sequences/sequence-format.ts
+function formatSequenceValue(template, counter, nodeId, now) {
+  const date = now ?? /* @__PURE__ */ new Date();
+  const yyyy = String(date.getUTCFullYear());
+  const mm = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const dd = String(date.getUTCDate()).padStart(2, "0");
+  const dateStr = `${yyyy}${mm}${dd}`;
+  return template.replace(/\{([^}]+)\}/g, (_match, token) => {
+    if (token === "date") return dateStr;
+    if (token === "node4") return nodeId.slice(0, 4);
+    if (token === "node8") return nodeId.slice(0, 8);
+    if (token === "seq") return String(counter).padStart(4, "0");
+    if (token.startsWith("seq:")) {
+      const width = Number.parseInt(token.slice(4), 10);
+      if (Number.isNaN(width) || width < 1) {
+        return String(counter).padStart(4, "0");
+      }
+      return String(counter).padStart(width, "0");
+    }
+    return `{${token}}`;
+  });
+}
+function defaultSequenceFormat(name) {
+  return `${name}-{seq:4}`;
+}
+
+// src/migration/apply-operation-transforms.ts
+var MAX_TRANSFORM_STEPS = 32;
+function applyOperationTransforms(operation, targetSchemaVersion, transforms) {
+  let current = operation;
+  for (let step = 0; step < MAX_TRANSFORM_STEPS; step++) {
+    if (current.schemaVersion === targetSchemaVersion) {
+      return current;
+    }
+    const transform = transforms.find(
+      (candidate) => candidate.fromVersion === current.schemaVersion
+    );
+    if (!transform) {
+      return null;
+    }
+    const next = transform.transform(current);
+    if (next === null) {
+      return null;
+    }
+    current = next;
+  }
+  return null;
+}
+
+// src/migrations/migration-builder.ts
+var RollbackBuilder = class {
+  _steps = [];
+  /**
+   * Add a field during rollback (to reverse a removeField).
+   */
+  addField(collection, field, builder) {
+    this._steps.push({ type: "addField", collection, field, descriptor: builder._build() });
+    return this;
+  }
+  /**
+   * Remove a field during rollback (to reverse an addField).
+   */
+  removeField(collection, field) {
+    this._steps.push({ type: "removeField", collection, field });
+    return this;
+  }
+  /**
+   * Rename a field during rollback (to reverse a renameField).
+   */
+  renameField(collection, from, to) {
+    this._steps.push({ type: "renameField", collection, from, to });
+    return this;
+  }
+  /**
+   * Add an index during rollback (to reverse a removeIndex).
+   */
+  addIndex(collection, field) {
+    this._steps.push({ type: "addIndex", collection, field });
+    return this;
+  }
+  /**
+   * Remove an index during rollback (to reverse an addIndex).
+   */
+  removeIndex(collection, field) {
+    this._steps.push({ type: "removeIndex", collection, field });
+    return this;
+  }
+  /**
+   * Run a backfill during rollback (to reverse a previous backfill).
+   */
+  backfill(collection, transform) {
+    this._steps.push({ type: "backfill", collection, transform });
+    return this;
+  }
+  /**
+   * Get the accumulated rollback steps.
+   */
+  _getSteps() {
+    return [...this._steps];
+  }
+};
+var MigrationBuilder = class _MigrationBuilder {
+  steps;
+  rollbackSteps;
+  safelyReversible;
+  constructor(steps = [], rollbackSteps, safelyReversible) {
+    this.steps = steps;
+    this.rollbackSteps = rollbackSteps;
+    this.safelyReversible = safelyReversible ?? this._computeSafelyReversible(steps, rollbackSteps);
+  }
+  /**
+   * Add a new field to a collection.
+   * The field builder provides the type and default value.
+   */
+  addField(collection, field, builder) {
+    return new _MigrationBuilder([
+      ...this.steps,
+      { type: "addField", collection, field, descriptor: builder._build() }
+    ]);
+  }
+  /**
+   * Remove a field from a collection.
+   * Optionally accepts a field builder to preserve the descriptor for rollback.
+   * Without the descriptor, rollback of this step requires a custom `.down()`.
+   *
+   * @param collection - The collection name
+   * @param field - The field name to remove
+   * @param builder - Optional field builder preserving the type info for rollback
+   */
+  removeField(collection, field, builder) {
+    const step = builder ? { type: "removeField", collection, field, descriptor: builder._build() } : { type: "removeField", collection, field };
+    return new _MigrationBuilder([...this.steps, step]);
+  }
+  /**
+   * Rename a field in a collection.
+   * Implemented as ALTER TABLE RENAME COLUMN (SQLite 3.25+).
+   */
+  renameField(collection, from, to) {
+    return new _MigrationBuilder([...this.steps, { type: "renameField", collection, from, to }]);
+  }
+  /**
+   * Add an index on a field.
+   */
+  addIndex(collection, field) {
+    return new _MigrationBuilder([...this.steps, { type: "addIndex", collection, field }]);
+  }
+  /**
+   * Remove an index on a field.
+   */
+  removeIndex(collection, field) {
+    return new _MigrationBuilder([...this.steps, { type: "removeIndex", collection, field }]);
+  }
+  /**
+   * Backfill records in a collection using a transform function.
+   * The transform receives each record and returns the fields to update.
+   * Runs after structural changes (addField, renameField, etc.).
+   *
+   * @param collection - The collection name
+   * @param transform - Forward transform function
+   * @param reverseTransform - Optional reverse transform for rollback support
+   */
+  backfill(collection, transform, reverseTransform) {
+    return new _MigrationBuilder([
+      ...this.steps,
+      { type: "backfill", collection, transform, reverseTransform }
+    ]);
+  }
+  /**
+   * Define explicit rollback steps for this migration.
+   * If not called, inverse steps are auto-generated from forward steps.
+   *
+   * @param fn - Function that receives a RollbackBuilder to define rollback steps
+   * @returns A new MigrationBuilder with the rollback steps attached
+   *
+   * @example
+   * ```typescript
+   * migrate()
+   *   .addField('todos', 'priority', t.enum(['low', 'medium', 'high']).default('medium'))
+   *   .addIndex('todos', 'priority')
+   *   .down((rollback) => {
+   *     rollback
+   *       .removeIndex('todos', 'priority')
+   *       .removeField('todos', 'priority')
+   *   })
+   * ```
+   */
+  down(fn) {
+    const rollbackBuilder = new RollbackBuilder();
+    fn(rollbackBuilder);
+    const rbSteps = rollbackBuilder._getSteps();
+    return new _MigrationBuilder(this.steps, rbSteps, true);
+  }
+  /**
+   * Determine if a migration is safely reversible based on its steps.
+   * A migration is not safely reversible if:
+   * - It has a backfill step without a reverseTransform and no explicit rollback
+   * - It has a removeField without a stored descriptor and no explicit rollback
+   */
+  _computeSafelyReversible(steps, rollbackSteps) {
+    if (rollbackSteps !== void 0) {
+      return true;
+    }
+    for (const step of steps) {
+      if (step.type === "backfill" && !step.reverseTransform) {
+        return false;
+      }
+      if (step.type === "removeField" && !step.descriptor) {
+        return false;
+      }
+    }
+    return true;
+  }
+};
+function migrate() {
+  return new MigrationBuilder();
+}
+
+// src/migrations/migration-rollback.ts
+var MigrationRollbackError = class extends KoraError {
+  constructor(step) {
+    super(
+      `Cannot auto-generate rollback for "${step.type}" step on collection "${step.collection}". Provide an explicit .down() definition for this migration.`,
+      "MIGRATION_ROLLBACK",
+      { stepType: step.type, collection: step.collection }
+    );
+    this.name = "MigrationRollbackError";
+  }
+};
+function canAutoRollback(step) {
+  switch (step.type) {
+    case "addField":
+    case "addIndex":
+    case "removeIndex":
+    case "renameField":
+      return true;
+    case "removeField":
+    case "backfill":
+      return false;
+  }
+}
+function generateRollbackSteps(forwardSteps) {
+  const rollbackSteps = [];
+  for (let i = forwardSteps.length - 1; i >= 0; i--) {
+    const step = forwardSteps[i];
+    if (step === void 0) continue;
+    const rollback = generateSingleRollbackStep(step);
+    rollbackSteps.push(rollback);
+  }
+  return rollbackSteps;
+}
+function generateSingleRollbackStep(step) {
+  switch (step.type) {
+    case "addField":
+      return { type: "removeField", collection: step.collection, field: step.field };
+    case "removeField":
+      if (step.descriptor) {
+        return {
+          type: "addField",
+          collection: step.collection,
+          field: step.field,
+          descriptor: step.descriptor
+        };
+      }
+      throw new MigrationRollbackError(step);
+    case "renameField":
+      return { type: "renameField", collection: step.collection, from: step.to, to: step.from };
+    case "addIndex":
+      return { type: "removeIndex", collection: step.collection, field: step.field };
+    case "removeIndex":
+      return { type: "addIndex", collection: step.collection, field: step.field };
+    case "backfill":
+      if (step.reverseTransform) {
+        return {
+          type: "backfill",
+          collection: step.collection,
+          transform: step.reverseTransform
+        };
+      }
+      throw new MigrationRollbackError(step);
+  }
+}
+function createReversibleMigration(upSteps, downSteps, fromVersion, toVersion) {
+  const down = downSteps !== null ? [...downSteps] : generateRollbackSteps(upSteps);
+  return {
+    up: [...upSteps],
+    down,
+    fromVersion,
+    toVersion
+  };
+}
+
+// src/migrations/migration-sql.ts
+function migrationStepsToSQL(steps) {
+  const statements = [];
+  for (const step of steps) {
+    switch (step.type) {
+      case "addField":
+        statements.push(addFieldSQL(step.collection, step.field, step.descriptor));
+        break;
+      case "removeField":
+        statements.push(`ALTER TABLE ${step.collection} DROP COLUMN ${step.field}`);
+        break;
+      case "renameField":
+        statements.push(`ALTER TABLE ${step.collection} RENAME COLUMN ${step.from} TO ${step.to}`);
+        break;
+      case "addIndex":
+        statements.push(
+          `CREATE INDEX IF NOT EXISTS idx_${step.collection}_${step.field} ON ${step.collection} (${step.field})`
+        );
+        break;
+      case "removeIndex":
+        statements.push(`DROP INDEX IF EXISTS idx_${step.collection}_${step.field}`);
+        break;
+      case "backfill":
+        break;
+    }
+  }
+  return statements;
+}
+function rollbackStepsToSQL(migration) {
+  const rollbackSteps = migration.rollbackSteps ?? generateRollbackSteps(migration.steps);
+  return migrationStepsToSQL(rollbackSteps);
+}
+function addFieldSQL(collection, field, descriptor) {
+  const sqlType = mapFieldType2(descriptor);
+  const parts = [`ALTER TABLE ${collection} ADD COLUMN ${field}`, sqlType];
+  if (descriptor.defaultValue !== void 0) {
+    parts.push(`DEFAULT ${sqlDefault2(descriptor.defaultValue)}`);
+  }
+  if (descriptor.kind === "enum" && descriptor.enumValues) {
+    const values = descriptor.enumValues.map((v) => `'${v}'`).join(", ");
+    parts.push(`CHECK (${field} IN (${values}))`);
+  }
+  return parts.join(" ");
+}
+function mapFieldType2(descriptor) {
+  switch (descriptor.kind) {
+    case "string":
+      return "TEXT";
+    case "number":
+      return "REAL";
+    case "boolean":
+      return "INTEGER";
+    case "enum":
+      return "TEXT";
+    case "timestamp":
+      return "INTEGER";
+    case "array":
+      return "TEXT";
+    case "richtext":
+      return "BLOB";
+  }
+}
+function sqlDefault2(value) {
+  if (value === null) return "NULL";
+  if (typeof value === "string") return `'${value}'`;
+  if (typeof value === "number") return String(value);
+  if (typeof value === "boolean") return value ? "1" : "0";
+  return `'${JSON.stringify(value)}'`;
+}
+
+// src/codegen/proto-generator.ts
+var SCALAR_TYPE_MAP = {
+  string: "string",
+  number: "double",
+  boolean: "bool",
+  timestamp: "int64",
+  richtext: "bytes"
+};
+var ARRAY_ITEM_TYPE_MAP = {
+  string: "string",
+  number: "double",
+  boolean: "bool",
+  timestamp: "int64"
+};
+function toPascalCase(name) {
+  return name.split("_").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+function toSnakeCase(name) {
+  return name.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}
+function resolveProtoType(fieldName, descriptor, messageName) {
+  if (descriptor.kind === "enum") {
+    return `${messageName}${toPascalCase(fieldName)}`;
+  }
+  if (descriptor.kind === "array") {
+    const itemType = descriptor.itemKind ? ARRAY_ITEM_TYPE_MAP[descriptor.itemKind] ?? "string" : "string";
+    return itemType;
+  }
+  return SCALAR_TYPE_MAP[descriptor.kind];
+}
+function generateEnumBlock(enumTypeName, enumValues, indent) {
+  const lines = [];
+  lines.push(`${indent}enum ${enumTypeName} {`);
+  lines.push(`${indent}	${enumTypeName.toUpperCase()}_UNSPECIFIED = 0;`);
+  for (let i = 0; i < enumValues.length; i++) {
+    const value = enumValues[i];
+    if (value === void 0) continue;
+    lines.push(`${indent}	${enumTypeName.toUpperCase()}_${value.toUpperCase()} = ${i + 1};`);
+  }
+  lines.push(`${indent}}`);
+  return lines.join("\n");
+}
+function generateCollectionMessage(collectionName, collection, typeMap) {
+  const messageName = `${toPascalCase(collectionName)}Record`;
+  const lines = [];
+  const nestedEnums = [];
+  lines.push(`message ${messageName} {`);
+  lines.push("	string id = 1;");
+  typeMap.set(`${collectionName}.id`, "string");
+  let fieldNumber = 2;
+  const entries = Object.entries(collection.fields);
+  for (const [fieldName, descriptor] of entries) {
+    const protoFieldName = toSnakeCase(fieldName);
+    const protoType = resolveProtoType(fieldName, descriptor, messageName);
+    const mapKey = `${collectionName}.${fieldName}`;
+    if (descriptor.kind === "enum" && descriptor.enumValues) {
+      const enumTypeName = `${messageName}${toPascalCase(fieldName)}`;
+      nestedEnums.push(generateEnumBlock(enumTypeName, descriptor.enumValues, "	"));
+      typeMap.set(mapKey, enumTypeName);
+      lines.push(`	${enumTypeName} ${protoFieldName} = ${fieldNumber};`);
+    } else if (descriptor.kind === "array") {
+      typeMap.set(mapKey, `repeated ${protoType}`);
+      lines.push(`	repeated ${protoType} ${protoFieldName} = ${fieldNumber};`);
+    } else {
+      typeMap.set(mapKey, protoType);
+      lines.push(`	${protoType} ${protoFieldName} = ${fieldNumber};`);
+    }
+    fieldNumber++;
+  }
+  if (nestedEnums.length > 0) {
+    lines.push("");
+    for (const enumBlock of nestedEnums) {
+      lines.push(enumBlock);
+    }
+  }
+  lines.push("}");
+  return lines.join("\n");
+}
+var KORA_OPERATION_MESSAGE = `message KoraOperation {
+	string id = 1;
+	string node_id = 2;
+	string type = 3;
+	string collection = 4;
+	string record_id = 5;
+	bytes data = 6;
+	bytes previous_data = 7;
+	int64 wall_time = 8;
+	int32 logical = 9;
+	string timestamp_node_id = 10;
+	int64 sequence_number = 11;
+	repeated string causal_deps = 12;
+	int32 schema_version = 13;
+}`;
+var OPERATION_BATCH_MESSAGE = `message OperationBatch {
+	repeated KoraOperation operations = 1;
+	bool is_final = 2;
+}`;
+var HANDSHAKE_MESSAGE = `message HandshakeMessage {
+	map<string, int64> version_vector = 1;
+	int32 schema_version = 2;
+	string node_id = 3;
+}`;
+var HANDSHAKE_RESPONSE_MESSAGE = `message HandshakeResponse {
+	map<string, int64> version_vector = 1;
+	int32 schema_version = 2;
+}`;
+var ACKNOWLEDGMENT_MESSAGE = `message Acknowledgment {
+	int64 sequence_number = 1;
+	string node_id = 2;
+}`;
+function buildJsonDescriptor(schema) {
+  const nested = {};
+  for (const [collectionName, collection] of Object.entries(schema.collections)) {
+    const messageName = `${toPascalCase(collectionName)}Record`;
+    const fields = {
+      id: { type: "string", id: 1 }
+    };
+    const nestedTypes = {};
+    let fieldNumber = 2;
+    for (const [fieldName, descriptor] of Object.entries(collection.fields)) {
+      const protoFieldName = toSnakeCase(fieldName);
+      const fieldDef = { id: fieldNumber };
+      if (descriptor.kind === "enum" && descriptor.enumValues) {
+        const enumTypeName = `${messageName}${toPascalCase(fieldName)}`;
+        fieldDef.type = enumTypeName;
+        const enumValuesObj = {
+          [`${enumTypeName.toUpperCase()}_UNSPECIFIED`]: 0
+        };
+        for (let i = 0; i < descriptor.enumValues.length; i++) {
+          const val = descriptor.enumValues[i];
+          if (val === void 0) continue;
+          enumValuesObj[`${enumTypeName.toUpperCase()}_${val.toUpperCase()}`] = i + 1;
+        }
+        nestedTypes[enumTypeName] = { values: enumValuesObj };
+      } else if (descriptor.kind === "array") {
+        const itemType = descriptor.itemKind ? ARRAY_ITEM_TYPE_MAP[descriptor.itemKind] ?? "string" : "string";
+        fieldDef.type = itemType;
+        fieldDef.rule = "repeated";
+      } else {
+        fieldDef.type = SCALAR_TYPE_MAP[descriptor.kind];
+      }
+      fields[protoFieldName] = fieldDef;
+      fieldNumber++;
+    }
+    const messageDescriptor = { fields };
+    if (Object.keys(nestedTypes).length > 0) {
+      messageDescriptor.nested = nestedTypes;
+    }
+    nested[messageName] = messageDescriptor;
+  }
+  nested.KoraOperation = {
+    fields: {
+      id: { type: "string", id: 1 },
+      node_id: { type: "string", id: 2 },
+      type: { type: "string", id: 3 },
+      collection: { type: "string", id: 4 },
+      record_id: { type: "string", id: 5 },
+      data: { type: "bytes", id: 6 },
+      previous_data: { type: "bytes", id: 7 },
+      wall_time: { type: "int64", id: 8 },
+      logical: { type: "int32", id: 9 },
+      timestamp_node_id: { type: "string", id: 10 },
+      sequence_number: { type: "int64", id: 11 },
+      causal_deps: { type: "string", id: 12, rule: "repeated" },
+      schema_version: { type: "int32", id: 13 }
+    }
+  };
+  nested.OperationBatch = {
+    fields: {
+      operations: { type: "KoraOperation", id: 1, rule: "repeated" },
+      is_final: { type: "bool", id: 2 }
+    }
+  };
+  nested.HandshakeMessage = {
+    fields: {
+      version_vector: { keyType: "string", type: "int64", id: 1 },
+      schema_version: { type: "int32", id: 2 },
+      node_id: { type: "string", id: 3 }
+    }
+  };
+  nested.HandshakeResponse = {
+    fields: {
+      version_vector: { keyType: "string", type: "int64", id: 1 },
+      schema_version: { type: "int32", id: 2 }
+    }
+  };
+  nested.Acknowledgment = {
+    fields: {
+      sequence_number: { type: "int64", id: 1 },
+      node_id: { type: "string", id: 2 }
+    }
+  };
+  return {
+    nested: {
+      kora: { nested }
+    }
+  };
+}
+function generateProtoDefinitions(schema) {
+  const typeMap = /* @__PURE__ */ new Map();
+  const sections = [];
+  sections.push('syntax = "proto3";');
+  sections.push("");
+  sections.push("package kora;");
+  const collectionEntries = Object.entries(schema.collections);
+  if (collectionEntries.length > 0) {
+    sections.push("");
+    sections.push("// Collection record messages");
+    for (const [collectionName, collection] of collectionEntries) {
+      sections.push("");
+      sections.push(generateCollectionMessage(collectionName, collection, typeMap));
+    }
+  }
+  sections.push("");
+  sections.push("// Sync protocol messages");
+  sections.push("");
+  sections.push(KORA_OPERATION_MESSAGE);
+  sections.push("");
+  sections.push(OPERATION_BATCH_MESSAGE);
+  sections.push("");
+  sections.push(HANDSHAKE_MESSAGE);
+  sections.push("");
+  sections.push(HANDSHAKE_RESPONSE_MESSAGE);
+  sections.push("");
+  sections.push(ACKNOWLEDGMENT_MESSAGE);
+  const proto = `${sections.join("\n")}
+`;
+  const jsonDescriptor = buildJsonDescriptor(schema);
+  return { proto, typeMap, jsonDescriptor };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  APPLY_FAILURE_CODES,
+  APPLY_RESULTS,
   ArrayFieldBuilder,
   CONNECTION_QUALITIES,
+  CausalTracker,
   ClockDriftError,
   EnumFieldBuilder,
   FieldBuilder,
   HybridLogicalClock,
+  KORA_ERROR_FIX_SUGGESTIONS,
   KoraError,
   MERGE_STRATEGIES,
   MergeConflictError,
+  MigrationBuilder,
+  MigrationRollbackError,
   OperationError,
+  RollbackBuilder,
   SchemaValidationError,
   StorageError,
   SyncError,
   advanceVector,
+  applyOperationTransforms,
+  buildScopeMap,
+  buildStateMachineConstraints,
+  canAutoRollback,
+  collectSchemaScopeFields,
+  collectSchemaScopeValueKeys,
   computeDelta,
   createOperation,
+  createReversibleMigration,
   createVersionVector,
+  defaultApplyFailureReason,
+  defaultSequenceFormat,
   defineSchema,
   deserializeVector,
   dominates,
+  extractScopeValuesFromClaims,
   extractTimestamp,
+  formatSequenceValue,
   generateFullDDL,
+  generateProtoDefinitions,
+  generateRollbackSteps,
   generateSQL,
   generateUUIDv7,
+  getCollectionScopeBindings,
+  getKoraErrorFix,
+  getTransitionMap,
+  hasSchemaSyncRules,
+  isApplyFailure,
+  isAtomicOp,
+  isCollectionSyncScoped,
   isValidOperation,
   isValidUUIDv7,
   mergeVectors,
+  migrate,
+  migrationStepsToSQL,
+  op,
+  resolveAtomicOp,
+  rollbackStepsToSQL,
   serializeVector,
   t,
+  toAtomicOp,
   validateRecord,
+  validateTransition,
   vectorsEqual,
   verifyOperationIntegrity
 });