@korajs/core 0.3.2 → 0.4.0

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   isValidOperation,
   topologicalSort,
   verifyOperationIntegrity
-} from "./chunk-KQYXWUFV.js";
+} from "./chunk-CFP5YFXC.js";
 
 // src/types.ts
 var MERGE_STRATEGIES = [
@@ -59,6 +59,190 @@ 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/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/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_]*$/;
@@ -80,7 +264,32 @@ 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;
+    }
+  }
+  return { version: input.version, collections, relations, migrations };
 }
 function validateVersion(version) {
   if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
@@ -142,7 +351,24 @@ 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 validateFieldName(collection, fieldName) {
   if (RESERVED_FIELDS.has(fieldName)) {
@@ -276,6 +502,9 @@ 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)"
+  );
   for (const [name, collection] of Object.entries(schema.collections)) {
     statements.push(...generateSQL(name, collection, schema.relations));
   }
@@ -329,23 +558,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() {
@@ -355,24 +608,88 @@ 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 {
@@ -381,14 +698,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() {
@@ -396,14 +715,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 {
@@ -412,7 +753,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
     };
   }
 };
@@ -466,10 +809,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;
     }
@@ -675,6 +1022,594 @@ function deserializeVector(s) {
   const entries = JSON.parse(s);
   return new Map(entries);
 }
+
+// src/scopes/build-scope-map.ts
+function buildScopeMap(schema, scopeValues) {
+  const result = {};
+  for (const [collName, collDef] of Object.entries(schema.collections)) {
+    if (collDef.scope.length > 0) {
+      const collScope = {};
+      for (const field of collDef.scope) {
+        if (field in scopeValues) {
+          collScope[field] = scopeValues[field];
+        }
+      }
+      result[collName] = collScope;
+    } else {
+      result[collName] = {};
+    }
+  }
+  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/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 };
+}
 export {
   ArrayFieldBuilder,
   CONNECTION_QUALITIES,
@@ -685,27 +1620,47 @@ export {
   KoraError,
   MERGE_STRATEGIES,
   MergeConflictError,
+  MigrationBuilder,
+  MigrationRollbackError,
   OperationError,
+  RollbackBuilder,
   SchemaValidationError,
   StorageError,
   SyncError,
   advanceVector,
+  buildScopeMap,
+  buildStateMachineConstraints,
+  canAutoRollback,
   computeDelta,
   createOperation,
+  createReversibleMigration,
   createVersionVector,
+  defaultSequenceFormat,
   defineSchema,
   deserializeVector,
   dominates,
   extractTimestamp,
+  formatSequenceValue,
   generateFullDDL,
+  generateProtoDefinitions,
+  generateRollbackSteps,
   generateSQL,
   generateUUIDv7,
+  getTransitionMap,
+  isAtomicOp,
   isValidOperation,
   isValidUUIDv7,
   mergeVectors,
+  migrate,
+  migrationStepsToSQL,
+  op,
+  resolveAtomicOp,
+  rollbackStepsToSQL,
   serializeVector,
   t,
+  toAtomicOp,
   validateRecord,
+  validateTransition,
   vectorsEqual,
   verifyOperationIntegrity
 };