@korajs/store 0.3.2 → 0.4.0

package/dist/index.js

@@ -9,10 +9,22 @@ import {
 } from "./chunk-LAWV6CFH.js";
 
 // src/store/store.ts
-import { HybridLogicalClock as HybridLogicalClock2, createVersionVector, generateUUIDv7 as generateUUIDv72 } from "@korajs/core";
+import {
+  HybridLogicalClock as HybridLogicalClock2,
+  createVersionVector,
+  generateUUIDv7 as generateUUIDv73,
+  migrationStepsToSQL
+} from "@korajs/core";
 
 // src/collection/collection.ts
-import { createOperation, generateUUIDv7, validateRecord } from "@korajs/core";
+import {
+  createOperation,
+  generateUUIDv7,
+  isAtomicOp,
+  resolveAtomicOp,
+  toAtomicOp,
+  validateRecord
+} from "@korajs/core";
 
 // src/query/sql-builder.ts
 function buildSelectQuery(descriptor, fields) {
@@ -195,7 +207,9 @@ function decodeRichtext(value) {
   if (value instanceof ArrayBuffer) {
     return new Uint8Array(value);
   }
-  throw new Error("Richtext storage value must be Uint8Array, ArrayBuffer, Buffer, null, or undefined.");
+  throw new Error(
+    "Richtext storage value must be Uint8Array, ArrayBuffer, Buffer, null, or undefined."
+  );
 }
 function richtextToPlainText(value) {
   const encoded = encodeRichtext(value);
@@ -234,13 +248,38 @@ function deserializeRecord(row, fields) {
   }
   return result;
 }
+var ATOMIC_OPS_KEY = "__kora_atomic_ops__";
+var TX_ID_KEY = "__kora_tx_id__";
+var MUTATION_NAME_KEY = "__kora_mutation__";
 function serializeOperation(op) {
+  const hasMetadata = op.transactionId !== void 0 || op.mutationName !== void 0;
+  let dataPayload = null;
+  if (op.data) {
+    dataPayload = { ...op.data };
+    if (op.atomicOps !== void 0 && Object.keys(op.atomicOps).length > 0) {
+      dataPayload[ATOMIC_OPS_KEY] = op.atomicOps;
+    }
+    if (op.transactionId !== void 0) {
+      dataPayload[TX_ID_KEY] = op.transactionId;
+    }
+    if (op.mutationName !== void 0) {
+      dataPayload[MUTATION_NAME_KEY] = op.mutationName;
+    }
+  } else if (hasMetadata) {
+    dataPayload = {};
+    if (op.transactionId !== void 0) {
+      dataPayload[TX_ID_KEY] = op.transactionId;
+    }
+    if (op.mutationName !== void 0) {
+      dataPayload[MUTATION_NAME_KEY] = op.mutationName;
+    }
+  }
   return {
     id: op.id,
     node_id: op.nodeId,
     type: op.type,
     record_id: op.recordId,
-    data: op.data ? JSON.stringify(op.data) : null,
+    data: dataPayload ? JSON.stringify(dataPayload) : null,
     previous_data: op.previousData ? JSON.stringify(op.previousData) : null,
     timestamp: HybridLogicalClock.serialize(op.timestamp),
     sequence_number: op.sequenceNumber,
@@ -249,6 +288,24 @@ function serializeOperation(op) {
   };
 }
 function deserializeOperation(row) {
+  let data = null;
+  let atomicOps;
+  let transactionId;
+  let mutationName;
+  if (row.data) {
+    const parsed = JSON.parse(row.data);
+    if (ATOMIC_OPS_KEY in parsed) {
+      atomicOps = parsed[ATOMIC_OPS_KEY];
+    }
+    if (TX_ID_KEY in parsed) {
+      transactionId = parsed[TX_ID_KEY];
+    }
+    if (MUTATION_NAME_KEY in parsed) {
+      mutationName = parsed[MUTATION_NAME_KEY];
+    }
+    const { [ATOMIC_OPS_KEY]: _a, [TX_ID_KEY]: _t, [MUTATION_NAME_KEY]: _m, ...rest } = parsed;
+    data = Object.keys(rest).length > 0 ? rest : null;
+  }
   return {
     id: row.id,
     nodeId: row.node_id,
@@ -256,12 +313,15 @@ function deserializeOperation(row) {
     collection: "",
     // Collection name is derived from the table name by the caller
     recordId: row.record_id,
-    data: row.data ? JSON.parse(row.data) : null,
+    data,
     previousData: row.previous_data ? JSON.parse(row.previous_data) : null,
     timestamp: HybridLogicalClock.deserialize(row.timestamp),
     sequenceNumber: row.sequence_number,
     causalDeps: JSON.parse(row.causal_deps),
-    schemaVersion: row.schema_version
+    schemaVersion: row.schema_version,
+    ...atomicOps !== void 0 ? { atomicOps } : {},
+    ...transactionId !== void 0 ? { transactionId } : {},
+    ...mutationName !== void 0 ? { mutationName } : {}
   };
 }
 function deserializeOperationWithCollection(row, collection) {
@@ -299,9 +359,91 @@ function deserializeValue(value, descriptor) {
   }
 }
 
+// src/state-machine/state-validator.ts
+import { KoraError, validateTransition } from "@korajs/core";
+var InvalidStateTransitionError = class extends KoraError {
+  constructor(collection, recordId, field, fromState, toState, allowedStates) {
+    super(
+      `Invalid state transition in collection "${collection}": cannot transition field "${field}" from "${fromState}" to "${toState}". Allowed transitions from "${fromState}": ${allowedStates.length > 0 ? allowedStates.join(", ") : "(none -- terminal state)"}`,
+      "INVALID_STATE_TRANSITION",
+      { collection, recordId, field, fromState, toState, allowedStates }
+    );
+    this.collection = collection;
+    this.recordId = recordId;
+    this.field = field;
+    this.fromState = fromState;
+    this.toState = toState;
+    this.allowedStates = allowedStates;
+    this.name = "InvalidStateTransitionError";
+  }
+  collection;
+  recordId;
+  field;
+  fromState;
+  toState;
+  allowedStates;
+};
+function validateStateTransition(collectionName, recordId, stateMachine, currentState, newState) {
+  if (currentState === null) {
+    return { valid: true, allowedStates: [] };
+  }
+  if (currentState === newState) {
+    return { valid: true, allowedStates: stateMachine.transitions[currentState] ?? [] };
+  }
+  const constraint = {
+    field: stateMachine.field,
+    collection: collectionName,
+    transitions: stateMachine.transitions
+  };
+  const transitionResult = validateTransition(constraint, currentState, newState);
+  if (transitionResult.valid) {
+    return { valid: true, allowedStates: transitionResult.allowedTargets };
+  }
+  const allowedStates = transitionResult.allowedTargets;
+  if (stateMachine.onInvalidTransition === "reject") {
+    throw new InvalidStateTransitionError(
+      collectionName,
+      recordId,
+      stateMachine.field,
+      currentState,
+      newState,
+      allowedStates
+    );
+  }
+  return { valid: false, allowedStates };
+}
+function validateUpdateStateMachine(collectionName, recordId, collectionDef, currentRecord, updateData) {
+  const stateMachine = collectionDef.stateMachine;
+  if (stateMachine === void 0) {
+    return updateData;
+  }
+  const stateField = stateMachine.field;
+  if (!(stateField in updateData)) {
+    return updateData;
+  }
+  const currentState = currentRecord[stateField];
+  const newState = updateData[stateField];
+  if (typeof currentState !== "string" || typeof newState !== "string") {
+    return updateData;
+  }
+  const result = validateStateTransition(
+    collectionName,
+    recordId,
+    stateMachine,
+    currentState,
+    newState
+  );
+  if (result.valid) {
+    return updateData;
+  }
+  const filtered = { ...updateData };
+  delete filtered[stateField];
+  return filtered;
+}
+
 // src/collection/collection.ts
 var Collection = class {
-  constructor(name, definition, schema, adapter, clock, nodeId, getSequenceNumber, onMutation) {
+  constructor(name, definition, schema, adapter, clock, nodeId, getSequenceNumber, onMutation, relationEnforcer) {
     this.name = name;
     this.definition = definition;
     this.schema = schema;
@@ -310,6 +452,7 @@ var Collection = class {
     this.nodeId = nodeId;
     this.getSequenceNumber = getSequenceNumber;
     this.onMutation = onMutation;
+    this.relationEnforcer = relationEnforcer ?? null;
   }
   name;
   definition;
@@ -319,6 +462,7 @@ var Collection = class {
   nodeId;
   getSequenceNumber;
   onMutation;
+  relationEnforcer;
   /**
    * Insert a new record into the collection.
    * Generates a UUID v7 for the id, validates data, and persists atomically.
@@ -408,13 +552,37 @@ var Collection = class {
     if (!currentRow) {
       throw new RecordNotFoundError(this.name, id);
     }
-    const validated = validateRecord(this.name, this.definition, data, "update");
+    let validated = validateRecord(this.name, this.definition, data, "update");
     const now = Date.now();
-    const previousData = {};
     const currentRecord = deserializeRecord(currentRow, this.definition.fields);
+    validated = validateUpdateStateMachine(
+      this.name,
+      id,
+      this.definition,
+      currentRecord,
+      validated
+    );
+    if (Object.keys(validated).length === 0) {
+      const fullRecord = await this.findById(id);
+      if (!fullRecord) {
+        throw new RecordNotFoundError(this.name, id);
+      }
+      return fullRecord;
+    }
+    const previousData = {};
+    const resolvedData = {};
+    const atomicOps = {};
     for (const key of Object.keys(validated)) {
+      const value = validated[key];
       previousData[key] = currentRecord[key];
+      if (isAtomicOp(value)) {
+        resolvedData[key] = resolveAtomicOp(currentRecord[key], value);
+        atomicOps[key] = toAtomicOp(value);
+      } else {
+        resolvedData[key] = value;
+      }
     }
+    const hasAtomicOps = Object.keys(atomicOps).length > 0;
     const sequenceNumber = this.getSequenceNumber();
     const operation = await createOperation(
       {
@@ -422,15 +590,16 @@ var Collection = class {
         type: "update",
         collection: this.name,
         recordId: id,
-        data: { ...validated },
+        data: { ...resolvedData },
         previousData,
         sequenceNumber,
         causalDeps: [],
-        schemaVersion: this.schema.version
+        schemaVersion: this.schema.version,
+        ...hasAtomicOps ? { atomicOps } : {}
       },
       this.clock
     );
-    const serializedChanges = serializeRecord(validated, this.definition.fields);
+    const serializedChanges = serializeRecord(resolvedData, this.definition.fields);
     const updateQuery = buildUpdateQuery(this.name, id, {
       ...serializedChanges,
       _updated_at: now
@@ -458,8 +627,19 @@ var Collection = class {
   /**
    * Soft-delete a record by its ID.
    *
+   * When a RelationEnforcer is configured, referential integrity policies
+   * are enforced within the same transaction:
+   * - **cascade**: Recursively deletes all referencing records
+   * - **set-null**: Sets foreign keys to null on referencing records
+   * - **restrict**: Throws ReferentialIntegrityError if references exist
+   * - **no-action**: Does nothing (dangling references are left)
+   *
+   * All cascaded operations are created atomically within the same transaction
+   * and share causal dependencies with the original delete.
+   *
    * @param id - The record ID to delete
    * @throws {RecordNotFoundError} If the record doesn't exist or is already deleted
+   * @throws {ReferentialIntegrityError} If a 'restrict' policy is violated
    */
   async delete(id) {
     const currentRows = await this.adapter.query(
@@ -491,7 +671,17 @@ var Collection = class {
       `_kora_ops_${this.name}`,
       opRow
     );
+    const cascadedOps = [];
     await this.adapter.transaction(async (tx) => {
+      if (this.relationEnforcer) {
+        const enforcementResult = await this.relationEnforcer.enforceDelete(
+          this.name,
+          id,
+          tx,
+          [operation.id]
+        );
+        cascadedOps.push(...enforcementResult.operations);
+      }
       await tx.execute(deleteQuery.sql, deleteQuery.params);
       await tx.execute(opInsert.sql, opInsert.params);
       await tx.execute(
@@ -500,6 +690,9 @@ var Collection = class {
       );
     });
     this.onMutation(this.name, operation);
+    for (const cascadedOp of cascadedOps) {
+      this.onMutation(cascadedOp.collection, cascadedOp);
+    }
   }
   /** Get the collection name */
   getName() {
@@ -804,12 +997,500 @@ var QueryError2 = class extends Error {
   }
 };
 
+// src/relations/relation-enforcer.ts
+import { KoraError as KoraError2, createOperation as createOperation2 } from "@korajs/core";
+
+// src/relations/relation-lookup.ts
+function buildRelationLookup(schema) {
+  const lookup = /* @__PURE__ */ new Map();
+  for (const [relationName, relation] of Object.entries(schema.relations)) {
+    const targetCollection = relation.to;
+    const existing = lookup.get(targetCollection) ?? [];
+    existing.push({
+      relationName,
+      sourceCollection: relation.from,
+      foreignKeyField: relation.field,
+      onDelete: relation.onDelete,
+      relation
+    });
+    lookup.set(targetCollection, existing);
+  }
+  return lookup;
+}
+function getIncomingRelations(lookup, collection) {
+  return lookup.get(collection) ?? [];
+}
+
+// src/relations/relation-enforcer.ts
+var ReferentialIntegrityError = class extends KoraError2 {
+  constructor(collection, recordId, referencingCollection, relationName, referencingCount) {
+    super(
+      `Cannot delete record "${recordId}" from "${collection}": ${referencingCount} record(s) in "${referencingCollection}" reference it via relation "${relationName}" with onDelete: 'restrict'. Delete or reassign the referencing records first.`,
+      "REFERENTIAL_INTEGRITY",
+      {
+        collection,
+        recordId,
+        referencingCollection,
+        relationName,
+        referencingCount
+      }
+    );
+    this.name = "ReferentialIntegrityError";
+  }
+};
+var RelationEnforcer = class {
+  lookup;
+  schema;
+  adapter;
+  clock;
+  nodeId;
+  getSequenceNumber;
+  constructor(config) {
+    this.schema = config.schema;
+    this.adapter = config.adapter;
+    this.clock = config.clock;
+    this.nodeId = config.nodeId;
+    this.getSequenceNumber = config.getSequenceNumber;
+    this.lookup = buildRelationLookup(config.schema);
+  }
+  /**
+   * Enforce referential integrity after deleting a record.
+   *
+   * Must be called within a transaction. The transaction handle is used
+   * for all cascaded writes to ensure atomicity.
+   *
+   * @param collection - The collection the deleted record belongs to
+   * @param recordId - The ID of the deleted record
+   * @param tx - The active transaction handle
+   * @param causalDeps - Causal dependencies for generated operations
+   * @returns All additional operations created as side effects
+   * @throws {ReferentialIntegrityError} If a 'restrict' policy is violated
+   */
+  async enforceDelete(collection, recordId, tx, causalDeps) {
+    const incomingRelations = getIncomingRelations(this.lookup, collection);
+    if (incomingRelations.length === 0) {
+      return { operations: [] };
+    }
+    const allOperations = [];
+    const sortedRelations = [...incomingRelations].sort(
+      (a, b) => a.relationName.localeCompare(b.relationName)
+    );
+    for (const incoming of sortedRelations) {
+      const ops = await this.enforceRelation(incoming, recordId, tx, causalDeps);
+      allOperations.push(...ops);
+    }
+    return { operations: allOperations };
+  }
+  /**
+   * Enforce a single relation's onDelete policy.
+   */
+  async enforceRelation(incoming, deletedRecordId, tx, causalDeps) {
+    switch (incoming.onDelete) {
+      case "cascade":
+        return this.enforceCascade(incoming, deletedRecordId, tx, causalDeps);
+      case "set-null":
+        return this.enforceSetNull(incoming, deletedRecordId, tx, causalDeps);
+      case "restrict":
+        return this.enforceRestrict(incoming, deletedRecordId, tx);
+      case "no-action":
+        return [];
+    }
+  }
+  /**
+   * Cascade: delete all records in the source collection that reference
+   * the deleted record, then recursively cascade those deletes.
+   */
+  async enforceCascade(incoming, deletedRecordId, tx, causalDeps) {
+    const { sourceCollection, foreignKeyField } = incoming;
+    const referencingRows = await tx.query(
+      `SELECT id FROM ${sourceCollection} WHERE ${foreignKeyField} = ? AND _deleted = 0`,
+      [deletedRecordId]
+    );
+    if (referencingRows.length === 0) {
+      return [];
+    }
+    const operations = [];
+    for (const row of referencingRows) {
+      const now = Date.now();
+      const sequenceNumber = this.getSequenceNumber();
+      const operation = await createOperation2(
+        {
+          nodeId: this.nodeId,
+          type: "delete",
+          collection: sourceCollection,
+          recordId: row.id,
+          data: null,
+          previousData: null,
+          sequenceNumber,
+          causalDeps: [...causalDeps],
+          schemaVersion: this.schema.version
+        },
+        this.clock
+      );
+      const deleteQuery = buildSoftDeleteQuery(sourceCollection, row.id, now);
+      await tx.execute(deleteQuery.sql, deleteQuery.params);
+      const opRow = serializeOperation(operation);
+      const opInsert = buildInsertQuery(
+        `_kora_ops_${sourceCollection}`,
+        opRow
+      );
+      await tx.execute(opInsert.sql, opInsert.params);
+      await tx.execute(
+        "INSERT OR REPLACE INTO _kora_version_vector (node_id, sequence_number) VALUES (?, ?)",
+        [this.nodeId, sequenceNumber]
+      );
+      operations.push(operation);
+      const cascadeResult = await this.enforceDelete(sourceCollection, row.id, tx, [operation.id]);
+      operations.push(...cascadeResult.operations);
+    }
+    return operations;
+  }
+  /**
+   * Set-null: update all referencing records to set the foreign key to null.
+   */
+  async enforceSetNull(incoming, deletedRecordId, tx, causalDeps) {
+    const { sourceCollection, foreignKeyField } = incoming;
+    const collectionDef = this.schema.collections[sourceCollection];
+    if (!collectionDef) {
+      return [];
+    }
+    const referencingRows = await tx.query(
+      `SELECT id FROM ${sourceCollection} WHERE ${foreignKeyField} = ? AND _deleted = 0`,
+      [deletedRecordId]
+    );
+    if (referencingRows.length === 0) {
+      return [];
+    }
+    const operations = [];
+    for (const row of referencingRows) {
+      const now = Date.now();
+      const sequenceNumber = this.getSequenceNumber();
+      const updateData = { [foreignKeyField]: null };
+      const previousData = { [foreignKeyField]: deletedRecordId };
+      const operation = await createOperation2(
+        {
+          nodeId: this.nodeId,
+          type: "update",
+          collection: sourceCollection,
+          recordId: row.id,
+          data: { ...updateData },
+          previousData,
+          sequenceNumber,
+          causalDeps: [...causalDeps],
+          schemaVersion: this.schema.version
+        },
+        this.clock
+      );
+      const serializedChanges = serializeRecord(updateData, collectionDef.fields);
+      const updateQuery = buildUpdateQuery(sourceCollection, row.id, {
+        ...serializedChanges,
+        _updated_at: now
+      });
+      await tx.execute(updateQuery.sql, updateQuery.params);
+      const opRow = serializeOperation(operation);
+      const opInsert = buildInsertQuery(
+        `_kora_ops_${sourceCollection}`,
+        opRow
+      );
+      await tx.execute(opInsert.sql, opInsert.params);
+      await tx.execute(
+        "INSERT OR REPLACE INTO _kora_version_vector (node_id, sequence_number) VALUES (?, ?)",
+        [this.nodeId, sequenceNumber]
+      );
+      operations.push(operation);
+    }
+    return operations;
+  }
+  /**
+   * Restrict: refuse the delete if any referencing records exist.
+   */
+  async enforceRestrict(incoming, deletedRecordId, tx) {
+    const { sourceCollection, foreignKeyField, relationName } = incoming;
+    const countRows = await tx.query(
+      `SELECT COUNT(*) as cnt FROM ${sourceCollection} WHERE ${foreignKeyField} = ? AND _deleted = 0`,
+      [deletedRecordId]
+    );
+    const count = countRows[0]?.cnt ?? 0;
+    if (count > 0) {
+      const targetCollection = incoming.relation.to;
+      throw new ReferentialIntegrityError(
+        targetCollection,
+        deletedRecordId,
+        sourceCollection,
+        relationName,
+        count
+      );
+    }
+    return [];
+  }
+  /**
+   * Get the relation lookup map for external use (e.g., by the merge engine).
+   */
+  getRelationLookup() {
+    return this.lookup;
+  }
+};
+
+// src/sequences/sequence-manager.ts
+import { defaultSequenceFormat, formatSequenceValue } from "@korajs/core";
+var SequenceManager = class {
+  adapter;
+  nodeId;
+  constructor(adapter, nodeId) {
+    this.adapter = adapter;
+    this.nodeId = nodeId;
+  }
+  /**
+   * Get the next value in a sequence, atomically incrementing the counter.
+   *
+   * @param name - The sequence name (e.g., 'receipt', 'invoice')
+   * @param config - Optional configuration for scope, format, and starting value
+   * @returns The formatted sequence value
+   */
+  async next(name, config) {
+    const scope = config?.scope ?? "";
+    const startAt = config?.startAt ?? 1;
+    const format = config?.format ?? defaultSequenceFormat(name);
+    let counter = 0;
+    await this.adapter.transaction(async (tx) => {
+      const rows = await tx.query(
+        "SELECT counter FROM _kora_sequences WHERE name = ? AND scope = ? AND node_id = ?",
+        [name, scope, this.nodeId]
+      );
+      if (rows.length > 0) {
+        const row = rows[0];
+        counter = row.counter + 1;
+        await tx.execute(
+          "UPDATE _kora_sequences SET counter = ? WHERE name = ? AND scope = ? AND node_id = ?",
+          [counter, name, scope, this.nodeId]
+        );
+      } else {
+        counter = startAt;
+        await tx.execute(
+          "INSERT INTO _kora_sequences (name, scope, node_id, counter) VALUES (?, ?, ?, ?)",
+          [name, scope, this.nodeId, counter]
+        );
+      }
+    });
+    return formatSequenceValue(format, counter, this.nodeId);
+  }
+  /**
+   * Get the current counter value without incrementing.
+   *
+   * @param name - The sequence name
+   * @param config - Optional scope
+   * @returns The current counter value, or 0 if the sequence has never been used
+   */
+  async current(name, config) {
+    const scope = config?.scope ?? "";
+    const rows = await this.adapter.query(
+      "SELECT counter FROM _kora_sequences WHERE name = ? AND scope = ? AND node_id = ?",
+      [name, scope, this.nodeId]
+    );
+    if (rows.length > 0) {
+      return rows[0].counter;
+    }
+    return 0;
+  }
+  /**
+   * Reset a sequence counter.
+   *
+   * @param name - The sequence name
+   * @param config - Optional scope and target value
+   */
+  async reset(name, config) {
+    const scope = config?.scope ?? "";
+    const to = config?.to ?? 0;
+    await this.adapter.execute(
+      "DELETE FROM _kora_sequences WHERE name = ? AND scope = ? AND node_id = ?",
+      [name, scope, this.nodeId]
+    );
+    if (to > 0) {
+      await this.adapter.execute(
+        "INSERT INTO _kora_sequences (name, scope, node_id, counter) VALUES (?, ?, ?, ?)",
+        [name, scope, this.nodeId, to]
+      );
+    }
+  }
+};
+
+// src/subscription/bloom-filter.ts
+var FNV_OFFSET_BASIS = 2166136261;
+var FNV_PRIME = 16777619;
+function fnv1a32(input) {
+  let hash = FNV_OFFSET_BASIS;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, FNV_PRIME);
+  }
+  return hash >>> 0;
+}
+function optimalBitCount(expectedItems, falsePositiveRate) {
+  if (expectedItems <= 0) return 32;
+  if (falsePositiveRate <= 0 || falsePositiveRate >= 1) return 32;
+  const ln2Squared = Math.LN2 * Math.LN2;
+  const rawBits = -(expectedItems * Math.log(falsePositiveRate)) / ln2Squared;
+  const aligned = Math.ceil(rawBits / 32) * 32;
+  return Math.max(32, aligned);
+}
+function optimalHashCount(bitCount, expectedItems) {
+  if (expectedItems <= 0) return 1;
+  const raw = bitCount / expectedItems * Math.LN2;
+  return Math.max(1, Math.min(30, Math.round(raw)));
+}
+var SubscriptionBloomFilter = class {
+  bits;
+  bitCount;
+  hashCount;
+  itemCount = 0;
+  constructor(expectedItems, falsePositiveRate = 0.01) {
+    this.bitCount = optimalBitCount(expectedItems, falsePositiveRate);
+    this.hashCount = optimalHashCount(this.bitCount, expectedItems);
+    this.bits = new Uint32Array(this.bitCount / 32);
+  }
+  /**
+   * Add a collection (and optional field) to the bloom filter.
+   *
+   * @param collection - Collection name (e.g., "todos")
+   * @param field - Optional field name (e.g., "completed")
+   */
+  add(collection, field) {
+    const key = field !== void 0 ? `${collection}:${field}` : collection;
+    const positions = this.getPositions(key);
+    for (const pos of positions) {
+      const wordIndex = pos >>> 5;
+      const bitIndex = pos & 31;
+      const current = this.bits[wordIndex] ?? 0;
+      this.bits[wordIndex] = current | 1 << bitIndex;
+    }
+    this.itemCount++;
+  }
+  /**
+   * Check if a collection (and optional field) might be in the filter.
+   *
+   * A return value of `false` means the item is DEFINITELY NOT in the filter.
+   * A return value of `true` means the item MIGHT be in the filter (possible false positive).
+   *
+   * @param collection - Collection name to check
+   * @param field - Optional field name to check
+   * @returns false = definitely absent, true = possibly present
+   */
+  mightContain(collection, field) {
+    const key = field !== void 0 ? `${collection}:${field}` : collection;
+    const positions = this.getPositions(key);
+    for (const pos of positions) {
+      const wordIndex = pos >>> 5;
+      const bitIndex = pos & 31;
+      if (((this.bits[wordIndex] ?? 0) & 1 << bitIndex) === 0) {
+        return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * Reset the bloom filter, clearing all bits and the item count.
+   */
+  clear() {
+    this.bits.fill(0);
+    this.itemCount = 0;
+  }
+  /**
+   * Estimate the current false positive rate based on the number of items inserted.
+   *
+   * Formula: (1 - e^(-kn/m))^k
+   * where k = hash count, n = item count, m = bit count.
+   *
+   * @returns Estimated false positive rate as a number between 0 and 1
+   */
+  estimatedFalsePositiveRate() {
+    if (this.itemCount === 0) return 0;
+    const exponent = -(this.hashCount * this.itemCount) / this.bitCount;
+    return (1 - Math.exp(exponent)) ** this.hashCount;
+  }
+  /**
+   * @returns The number of items that have been added to the filter
+   */
+  getItemCount() {
+    return this.itemCount;
+  }
+  /**
+   * @returns The total number of bits in the filter
+   */
+  getBitCount() {
+    return this.bitCount;
+  }
+  /**
+   * @returns The number of hash functions used
+   */
+  getHashCount() {
+    return this.hashCount;
+  }
+  /**
+   * Count the number of bits currently set to 1.
+   * Uses Brian Kernighan's algorithm: each iteration clears the lowest set bit,
+   * so the loop runs exactly as many times as there are set bits.
+   *
+   * @returns Number of bits set to 1
+   */
+  getSetBitCount() {
+    let count = 0;
+    for (let i = 0; i < this.bits.length; i++) {
+      let word = this.bits[i] ?? 0;
+      while (word !== 0) {
+        word &= word - 1;
+        count++;
+      }
+    }
+    return count;
+  }
+  /**
+   * Compute k bit positions for a given key using Kirsch-Mitzenmacker double hashing.
+   *
+   * Instead of computing k independent hash functions, we compute two base hashes
+   * (h1 and h2) and derive the rest as: h_i = (h1 + i * h2) mod m.
+   * This technique is proven to have the same asymptotic false positive rate as
+   * k independent hash functions.
+   *
+   * We derive h1 and h2 from a single FNV-1a hash by splitting and mixing:
+   * h1 = fnv1a(key), h2 = fnv1a(key + "\0salt") to ensure independence.
+   */
+  getPositions(key) {
+    const h1 = fnv1a32(key);
+    const h2 = fnv1a32(`${key}\0bloom`);
+    const positions = new Array(this.hashCount);
+    for (let i = 0; i < this.hashCount; i++) {
+      positions[i] = (h1 + Math.imul(i, h2) >>> 0) % this.bitCount;
+    }
+    return positions;
+  }
+};
+
 // src/subscription/subscription-manager.ts
 var nextSubId = 0;
+var DEFAULT_BLOOM_THRESHOLD = 100;
+var DEFAULT_BLOOM_EXPECTED_ITEMS = 500;
+var DEFAULT_BLOOM_FALSE_POSITIVE_RATE = 0.01;
 var SubscriptionManager = class {
   subscriptions = /* @__PURE__ */ new Map();
   pendingCollections = /* @__PURE__ */ new Set();
   flushScheduled = false;
+  // Bloom filter state
+  bloomFilter = null;
+  bloomDirty = false;
+  bloomThreshold;
+  bloomExpectedItems;
+  bloomFalsePositiveRate;
+  // Performance stats
+  totalChecks = 0;
+  bloomFilterHits = 0;
+  bloomFilterMisses = 0;
+  falsePositives = 0;
+  totalCheckTimeMs = 0;
+  constructor(options) {
+    this.bloomThreshold = options?.bloomThreshold ?? DEFAULT_BLOOM_THRESHOLD;
+    this.bloomExpectedItems = options?.bloomExpectedItems ?? DEFAULT_BLOOM_EXPECTED_ITEMS;
+    this.bloomFalsePositiveRate = options?.bloomFalsePositiveRate ?? DEFAULT_BLOOM_FALSE_POSITIVE_RATE;
+  }
   /**
    * Register a new subscription.
    *
@@ -828,8 +1509,10 @@ var SubscriptionManager = class {
       lastResults: []
     };
     this.subscriptions.set(id, subscription);
+    this.bloomDirty = true;
     return () => {
       this.subscriptions.delete(id);
+      this.bloomDirty = true;
     };
   }
   /**
@@ -849,6 +1532,7 @@ var SubscriptionManager = class {
       lastResults: []
     };
     this.subscriptions.set(id, subscription);
+    this.bloomDirty = true;
     executeFn().then((results) => {
       if (this.subscriptions.has(id)) {
         subscription.lastResults = results;
@@ -857,6 +1541,7 @@ var SubscriptionManager = class {
     });
     return () => {
       this.subscriptions.delete(id);
+      this.bloomDirty = true;
     };
   }
   /**
@@ -876,19 +1561,7 @@ var SubscriptionManager = class {
     const collections = new Set(this.pendingCollections);
     this.pendingCollections.clear();
     this.flushScheduled = false;
-    const affected = [];
-    for (const sub of this.subscriptions.values()) {
-      if (collections.has(sub.descriptor.collection)) {
-        affected.push(sub);
-      } else if (sub.descriptor.includeCollections) {
-        for (const incCol of sub.descriptor.includeCollections) {
-          if (collections.has(incCol)) {
-            affected.push(sub);
-            break;
-          }
-        }
-      }
-    }
+    const affected = this.findAffectedSubscriptions(collections);
     for (const sub of affected) {
       try {
         const newResults = await sub.executeFn();
@@ -907,11 +1580,118 @@ var SubscriptionManager = class {
     this.subscriptions.clear();
     this.pendingCollections.clear();
     this.flushScheduled = false;
+    this.bloomFilter = null;
+    this.bloomDirty = false;
+    this.totalChecks = 0;
+    this.bloomFilterHits = 0;
+    this.bloomFilterMisses = 0;
+    this.falsePositives = 0;
+    this.totalCheckTimeMs = 0;
   }
   /** Number of active subscriptions (for testing/debugging) */
   get size() {
     return this.subscriptions.size;
   }
+  /**
+   * Get performance statistics for monitoring subscription checking efficiency.
+   * Useful for DevTools integration and performance tuning.
+   */
+  getStats() {
+    return {
+      totalChecks: this.totalChecks,
+      bloomFilterHits: this.bloomFilterHits,
+      bloomFilterMisses: this.bloomFilterMisses,
+      falsePositives: this.falsePositives,
+      averageCheckTimeMs: this.totalChecks > 0 ? this.totalCheckTimeMs / this.totalChecks : 0,
+      bloomFilterActive: this.isBloomActive(),
+      subscriptionCount: this.subscriptions.size
+    };
+  }
+  /**
+   * Check if bloom filter is currently active.
+   * Active when subscription count meets or exceeds the threshold.
+   */
+  isBloomActive() {
+    return this.subscriptions.size >= this.bloomThreshold;
+  }
+  /**
+   * Find subscriptions affected by mutations to the given collections.
+   * Uses two-level checking when bloom filter is active:
+   *
+   * Level 1: Bloom filter pre-check -- if no subscription depends on any
+   * of the mutated collections, skip everything (O(k) per collection).
+   *
+   * Level 2: Precise check -- linear scan of subscriptions, matching
+   * against the mutated collections.
+   */
+  findAffectedSubscriptions(collections) {
+    const startTime = performance.now();
+    this.totalChecks++;
+    const useBloom = this.isBloomActive();
+    if (useBloom) {
+      if (this.bloomDirty || this.bloomFilter === null) {
+        this.rebuildBloomFilter();
+      }
+      const filter = this.bloomFilter;
+      if (filter !== null) {
+        let anyPossibleMatch = false;
+        for (const col of collections) {
+          if (filter.mightContain(col)) {
+            anyPossibleMatch = true;
+            break;
+          }
+        }
+        if (!anyPossibleMatch) {
+          this.bloomFilterMisses++;
+          this.totalCheckTimeMs += performance.now() - startTime;
+          return [];
+        }
+        this.bloomFilterHits++;
+      }
+    }
+    const affected = [];
+    let anyPreciseMatch = false;
+    for (const sub of this.subscriptions.values()) {
+      if (collections.has(sub.descriptor.collection)) {
+        affected.push(sub);
+        anyPreciseMatch = true;
+      } else if (sub.descriptor.includeCollections) {
+        for (const incCol of sub.descriptor.includeCollections) {
+          if (collections.has(incCol)) {
+            affected.push(sub);
+            anyPreciseMatch = true;
+            break;
+          }
+        }
+      }
+    }
+    if (useBloom && !anyPreciseMatch) {
+      this.falsePositives++;
+    }
+    this.totalCheckTimeMs += performance.now() - startTime;
+    return affected;
+  }
+  /**
+   * Rebuild the bloom filter from all current subscriptions.
+   * Adds collection-level dependencies for every subscription, plus
+   * any included collection dependencies.
+   */
+  rebuildBloomFilter() {
+    const filter = new SubscriptionBloomFilter(
+      this.bloomExpectedItems,
+      this.bloomFalsePositiveRate
+    );
+    for (const sub of this.subscriptions.values()) {
+      filter.add(sub.descriptor.collection);
+      if (sub.descriptor.includeCollections) {
+        for (const incCol of sub.descriptor.includeCollections) {
+          filter.add(incCol);
+        }
+      }
+    }
+    this.bloomFilter = filter;
+    this.bloomDirty = false;
+  }
   scheduleFlush() {
     if (this.flushScheduled) return;
     this.flushScheduled = true;
@@ -930,6 +1710,322 @@ var SubscriptionManager = class {
   }
 };
 
+// src/transaction/transaction-context.ts
+import {
+  createOperation as createOperation3,
+  generateUUIDv7 as generateUUIDv72,
+  isAtomicOp as isAtomicOp2,
+  resolveAtomicOp as resolveAtomicOp2,
+  toAtomicOp as toAtomicOp2,
+  validateRecord as validateRecord2
+} from "@korajs/core";
+var TransactionContext = class {
+  transactionId;
+  mutationName;
+  buffer = [];
+  committed = false;
+  rolledBack = false;
+  config;
+  constructor(config) {
+    this.config = config;
+    this.transactionId = generateUUIDv72();
+  }
+  /**
+   * Set a human-readable mutation name for this transaction.
+   * Propagated to all operations for DevTools display.
+   */
+  setMutationName(name) {
+    this.mutationName = name;
+  }
+  /**
+   * Get the mutation name, if set.
+   */
+  getMutationName() {
+    return this.mutationName;
+  }
+  /**
+   * Get a collection accessor for buffered operations within this transaction.
+   */
+  collection(name) {
+    const definition = this.config.schema.collections[name];
+    if (!definition) {
+      throw new Error(
+        `Unknown collection "${name}". Available: ${Object.keys(this.config.schema.collections).join(", ")}`
+      );
+    }
+    return {
+      insert: (data) => this.insert(name, definition, data),
+      update: (id, data) => this.update(name, definition, id, data),
+      delete: (id) => this.deleteRecord(name, definition, id),
+      findById: (id) => this.findById(name, definition, id)
+    };
+  }
+  /**
+   * Commit all buffered operations atomically.
+   * Returns the list of operations and affected collections for subscription notification.
+   */
+  async commit() {
+    if (this.committed) {
+      throw new Error("Transaction already committed.");
+    }
+    if (this.rolledBack) {
+      throw new Error("Transaction was rolled back and cannot be committed.");
+    }
+    this.committed = true;
+    if (this.buffer.length === 0) {
+      return { operations: [], affectedCollections: /* @__PURE__ */ new Set() };
+    }
+    const operations = [];
+    const affectedCollections = /* @__PURE__ */ new Set();
+    await this.config.adapter.transaction(async (tx) => {
+      for (const entry of this.buffer) {
+        for (const cmd of entry.commands) {
+          await tx.execute(cmd.sql, cmd.params);
+        }
+        operations.push(entry.operation);
+        affectedCollections.add(entry.collection);
+      }
+    });
+    return { operations, affectedCollections };
+  }
+  /**
+   * Mark the transaction as rolled back. No operations will be committed.
+   */
+  rollback() {
+    this.rolledBack = true;
+    this.buffer.length = 0;
+  }
+  /**
+   * Get the transaction ID shared by all operations in this transaction.
+   */
+  getTransactionId() {
+    return this.transactionId;
+  }
+  ensureActive() {
+    if (this.committed) {
+      throw new Error("Cannot perform operations on a committed transaction.");
+    }
+    if (this.rolledBack) {
+      throw new Error("Cannot perform operations on a rolled-back transaction.");
+    }
+  }
+  async insert(collectionName, definition, data) {
+    this.ensureActive();
+    const validated = validateRecord2(collectionName, definition, data, "insert");
+    const recordId = generateUUIDv72();
+    const now = Date.now();
+    for (const [fieldName, descriptor] of Object.entries(definition.fields)) {
+      if (descriptor.auto && descriptor.kind === "timestamp") {
+        validated[fieldName] = now;
+      }
+    }
+    const sequenceNumber = this.config.getSequenceNumber();
+    const operation = await createOperation3(
+      {
+        nodeId: this.config.nodeId,
+        type: "insert",
+        collection: collectionName,
+        recordId,
+        data: { ...validated },
+        previousData: null,
+        sequenceNumber,
+        causalDeps: [],
+        schemaVersion: this.config.schema.version,
+        transactionId: this.transactionId,
+        ...this.mutationName !== void 0 ? { mutationName: this.mutationName } : {}
+      },
+      this.config.clock
+    );
+    const serializedData = serializeRecord(validated, definition.fields);
+    const record = {
+      id: recordId,
+      ...serializedData,
+      _created_at: now,
+      _updated_at: now
+    };
+    const insertQuery = buildInsertQuery(collectionName, record);
+    const opRow = serializeOperation(operation);
+    const opInsert = buildInsertQuery(
+      `_kora_ops_${collectionName}`,
+      opRow
+    );
+    this.buffer.push({
+      operation,
+      collection: collectionName,
+      commands: [
+        { sql: insertQuery.sql, params: insertQuery.params },
+        { sql: opInsert.sql, params: opInsert.params },
+        {
+          sql: "INSERT OR REPLACE INTO _kora_version_vector (node_id, sequence_number) VALUES (?, ?)",
+          params: [this.config.nodeId, sequenceNumber]
+        }
+      ]
+    });
+    return {
+      id: recordId,
+      ...validated,
+      createdAt: now,
+      updatedAt: now
+    };
+  }
+  async update(collectionName, definition, id, data) {
+    this.ensureActive();
+    const currentRecord = await this.getEffectiveRecord(collectionName, definition, id);
+    if (!currentRecord) {
+      throw new RecordNotFoundError(collectionName, id);
+    }
+    const validated = validateRecord2(collectionName, definition, data, "update");
+    const now = Date.now();
+    const previousData = {};
+    const resolvedData = {};
+    const atomicOps = {};
+    for (const key of Object.keys(validated)) {
+      const value = validated[key];
+      previousData[key] = currentRecord[key];
+      if (isAtomicOp2(value)) {
+        resolvedData[key] = resolveAtomicOp2(currentRecord[key], value);
+        atomicOps[key] = toAtomicOp2(value);
+      } else {
+        resolvedData[key] = value;
+      }
+    }
+    const hasAtomicOps = Object.keys(atomicOps).length > 0;
+    const sequenceNumber = this.config.getSequenceNumber();
+    const operation = await createOperation3(
+      {
+        nodeId: this.config.nodeId,
+        type: "update",
+        collection: collectionName,
+        recordId: id,
+        data: { ...resolvedData },
+        previousData,
+        sequenceNumber,
+        causalDeps: [],
+        schemaVersion: this.config.schema.version,
+        transactionId: this.transactionId,
+        ...this.mutationName !== void 0 ? { mutationName: this.mutationName } : {},
+        ...hasAtomicOps ? { atomicOps } : {}
+      },
+      this.config.clock
+    );
+    const serializedChanges = serializeRecord(resolvedData, definition.fields);
+    const updateQuery = buildUpdateQuery(collectionName, id, {
+      ...serializedChanges,
+      _updated_at: now
+    });
+    const opRow = serializeOperation(operation);
+    const opInsert = buildInsertQuery(
+      `_kora_ops_${collectionName}`,
+      opRow
+    );
+    this.buffer.push({
+      operation,
+      collection: collectionName,
+      commands: [
+        { sql: updateQuery.sql, params: updateQuery.params },
+        { sql: opInsert.sql, params: opInsert.params },
+        {
+          sql: "INSERT OR REPLACE INTO _kora_version_vector (node_id, sequence_number) VALUES (?, ?)",
+          params: [this.config.nodeId, sequenceNumber]
+        }
+      ]
+    });
+    return {
+      ...currentRecord,
+      ...resolvedData,
+      updatedAt: now
+    };
+  }
+  async deleteRecord(collectionName, definition, id) {
+    this.ensureActive();
+    const currentRecord = await this.getEffectiveRecord(collectionName, definition, id);
+    if (!currentRecord) {
+      throw new RecordNotFoundError(collectionName, id);
+    }
+    const now = Date.now();
+    const sequenceNumber = this.config.getSequenceNumber();
+    const operation = await createOperation3(
+      {
+        nodeId: this.config.nodeId,
+        type: "delete",
+        collection: collectionName,
+        recordId: id,
+        data: null,
+        previousData: null,
+        sequenceNumber,
+        causalDeps: [],
+        schemaVersion: this.config.schema.version,
+        transactionId: this.transactionId,
+        ...this.mutationName !== void 0 ? { mutationName: this.mutationName } : {}
+      },
+      this.config.clock
+    );
+    const deleteQuery = buildSoftDeleteQuery(collectionName, id, now);
+    const opRow = serializeOperation(operation);
+    const opInsert = buildInsertQuery(
+      `_kora_ops_${collectionName}`,
+      opRow
+    );
+    this.buffer.push({
+      operation,
+      collection: collectionName,
+      commands: [
+        { sql: deleteQuery.sql, params: deleteQuery.params },
+        { sql: opInsert.sql, params: opInsert.params },
+        {
+          sql: "INSERT OR REPLACE INTO _kora_version_vector (node_id, sequence_number) VALUES (?, ?)",
+          params: [this.config.nodeId, sequenceNumber]
+        }
+      ]
+    });
+  }
+  async findById(collectionName, definition, id) {
+    return this.getEffectiveRecord(collectionName, definition, id);
+  }
+  /**
+   * Get the effective state of a record, considering both the database and buffered operations.
+   * Buffered inserts/updates take precedence over the database state.
+   */
+  async getEffectiveRecord(collectionName, definition, id) {
+    for (let i = this.buffer.length - 1; i >= 0; i--) {
+      const entry = this.buffer[i];
+      if (entry.collection === collectionName && entry.operation.recordId === id) {
+        if (entry.operation.type === "delete") {
+          return null;
+        }
+        break;
+      }
+    }
+    const rows = await this.config.adapter.query(
+      `SELECT * FROM ${collectionName} WHERE id = ? AND _deleted = 0`,
+      [id]
+    );
+    let record = rows[0] ? deserializeRecord(rows[0], definition.fields) : null;
+    for (const entry of this.buffer) {
+      if (entry.collection !== collectionName || entry.operation.recordId !== id) {
+        continue;
+      }
+      if (entry.operation.type === "insert" && entry.operation.data) {
+        record = {
+          id,
+          ...entry.operation.data,
+          createdAt: entry.operation.timestamp.wallTime,
+          updatedAt: entry.operation.timestamp.wallTime
+        };
+      } else if (entry.operation.type === "update" && entry.operation.data && record) {
+        record = {
+          ...record,
+          ...entry.operation.data,
+          updatedAt: entry.operation.timestamp.wallTime
+        };
+      } else if (entry.operation.type === "delete") {
+        record = null;
+      }
+    }
+    return record;
+  }
+};
+
 // src/store/store.ts
 var Store = class {
   opened = false;
@@ -939,6 +2035,7 @@ var Store = class {
   clock = null;
   collections = /* @__PURE__ */ new Map();
   subscriptionManager = new SubscriptionManager();
+  sequenceManager = null;
   schema;
   adapter;
   configNodeId;
@@ -955,10 +2052,20 @@ var Store = class {
    */
   async open() {
     await this.adapter.open(this.schema);
+    await this.runMigrationsIfNeeded();
     this.nodeId = await this.loadOrGenerateNodeId();
     this.clock = new HybridLogicalClock2(this.nodeId);
+    this.sequenceManager = new SequenceManager(this.adapter, this.nodeId);
     this.sequenceNumber = await this.loadSequenceNumber();
     this.versionVector = await this.loadVersionVector();
+    const hasRelations = Object.keys(this.schema.relations).length > 0;
+    const relationEnforcer = hasRelations ? new RelationEnforcer({
+      schema: this.schema,
+      adapter: this.adapter,
+      clock: this.clock,
+      nodeId: this.nodeId,
+      getSequenceNumber: () => this.nextSequenceNumber()
+    }) : void 0;
     for (const [name, definition] of Object.entries(this.schema.collections)) {
       const col = new Collection(
         name,
@@ -973,7 +2080,8 @@ var Store = class {
           if (this.emitter) {
             this.emitter.emit({ type: "operation:created", operation });
           }
-        }
+        },
+        relationEnforcer
       );
       this.collections.set(name, col);
     }
@@ -1010,7 +2118,14 @@ var Store = class {
       findById: (id) => col.findById(id),
       update: (id, data) => col.update(id, data),
       delete: (id) => col.delete(id),
-      where: (conditions) => new QueryBuilder(name, definition, this.adapter, this.subscriptionManager, conditions, this.schema)
+      where: (conditions) => new QueryBuilder(
+        name,
+        definition,
+        this.adapter,
+        this.subscriptionManager,
+        conditions,
+        this.schema
+      )
     };
   }
   /**
@@ -1125,11 +2240,148 @@ var Store = class {
   getSubscriptionManager() {
     return this.subscriptionManager;
   }
+  /**
+   * Get the sequence manager for offline-safe sequence generation.
+   * @throws {StoreNotOpenError} If the store is not open
+   */
+  getSequenceManager() {
+    this.ensureOpen();
+    if (!this.sequenceManager) {
+      throw new StoreNotOpenError();
+    }
+    return this.sequenceManager;
+  }
+  /**
+   * Create a TransactionContext for atomic multi-collection operations.
+   * The returned context buffers all mutations and commits them atomically.
+   *
+   * After commit, the caller is responsible for notifying subscriptions
+   * and emitting events for each operation.
+   */
+  createTransaction() {
+    this.ensureOpen();
+    if (!this.clock) {
+      throw new StoreNotOpenError();
+    }
+    return new TransactionContext({
+      schema: this.schema,
+      adapter: this.adapter,
+      clock: this.clock,
+      nodeId: this.nodeId,
+      getSequenceNumber: () => this.nextSequenceNumber()
+    });
+  }
+  /**
+   * Execute a function within a transaction. All mutations performed on the
+   * TransactionContext are committed atomically. Subscription notifications
+   * are batched and fired after the commit.
+   *
+   * If the function throws, the transaction is rolled back and the error is re-thrown.
+   *
+   * @param fn - Function receiving a TransactionContext for buffered operations
+   * @returns The operations that were committed
+   */
+  async transaction(fn) {
+    const tx = this.createTransaction();
+    try {
+      await fn(tx);
+      const { operations, affectedCollections } = await tx.commit();
+      for (const op of operations) {
+        this.subscriptionManager.notify(op.collection, op);
+        if (this.emitter) {
+          this.emitter.emit({ type: "operation:created", operation: op });
+        }
+      }
+      return operations;
+    } catch (error) {
+      tx.rollback();
+      throw error;
+    }
+  }
   nextSequenceNumber() {
     this.sequenceNumber++;
     this.versionVector.set(this.nodeId, this.sequenceNumber);
     return this.sequenceNumber;
   }
+  /**
+   * Check the stored schema version and run any pending migrations.
+   * Migrations are applied in version order within a transaction.
+   */
+  async runMigrationsIfNeeded() {
+    const storedVersion = await this.getStoredSchemaVersion();
+    const targetVersion = this.schema.version;
+    if (storedVersion >= targetVersion) {
+      if (storedVersion === 0) {
+        await this.adapter.execute(
+          "INSERT OR REPLACE INTO _kora_meta (key, value) VALUES ('schema_version', ?)",
+          [String(targetVersion)]
+        );
+      }
+      return;
+    }
+    const migrations = this.schema.migrations ?? {};
+    for (let v = storedVersion + 1; v <= targetVersion; v++) {
+      const migration = migrations[v];
+      if (!migration) continue;
+      const sqlStatements = migrationStepsToSQL(migration.steps);
+      for (const sql of sqlStatements) {
+        try {
+          await this.adapter.execute(sql);
+        } catch (e) {
+          const msg = e.message || "";
+          if (!msg.includes("duplicate column name")) {
+            throw e;
+          }
+        }
+      }
+      const backfillSteps = migration.steps.filter(
+        (s) => s.type === "backfill"
+      );
+      for (const step of backfillSteps) {
+        await this.runBackfill(step.collection, step.transform);
+      }
+    }
+    await this.adapter.execute(
+      "INSERT OR REPLACE INTO _kora_meta (key, value) VALUES ('schema_version', ?)",
+      [String(targetVersion)]
+    );
+  }
+  /**
+   * Get the stored schema version from _kora_meta. Returns 0 if not set.
+   */
+  async getStoredSchemaVersion() {
+    const rows = await this.adapter.query(
+      "SELECT value FROM _kora_meta WHERE key = 'schema_version'"
+    );
+    return rows[0] ? Number(rows[0].value) : 0;
+  }
+  /**
+   * Run a backfill transform on all records in a collection.
+   * Reads all rows, applies the transform, and updates changed fields.
+   */
+  async runBackfill(collection, transform) {
+    const rows = await this.adapter.query(
+      `SELECT * FROM ${collection} WHERE _deleted = 0`
+    );
+    await this.adapter.transaction(async (tx) => {
+      for (const row of rows) {
+        const updates = transform(row);
+        const fields = Object.keys(updates);
+        if (fields.length === 0) continue;
+        const setClauses = fields.map((f) => `${f} = ?`).join(", ");
+        const values = fields.map((f) => {
+          const val = updates[f];
+          if (typeof val === "boolean") return val ? 1 : 0;
+          if (Array.isArray(val) || typeof val === "object" && val !== null) {
+            return JSON.stringify(val);
+          }
+          return val;
+        });
+        values.push(row.id);
+        await tx.execute(`UPDATE ${collection} SET ${setClauses} WHERE id = ?`, values);
+      }
+    });
+  }
   async loadOrGenerateNodeId() {
     if (this.configNodeId) {
       await this.adapter.execute(
@@ -1144,7 +2396,7 @@ var Store = class {
     if (rows[0]) {
       return rows[0].value;
     }
-    const newNodeId = generateUUIDv72();
+    const newNodeId = generateUUIDv73();
     await this.adapter.execute("INSERT INTO _kora_meta (key, value) VALUES ('node_id', ?)", [
       newNodeId
     ]);
@@ -1176,19 +2428,25 @@ var Store = class {
 export {
   AdapterError,
   Collection,
+  InvalidStateTransitionError,
   PersistenceError,
   QueryBuilder,
   QueryError,
   RecordNotFoundError,
+  SequenceManager,
   Store,
   StoreNotOpenError,
+  SubscriptionBloomFilter,
   SubscriptionManager,
+  TransactionContext,
   WorkerInitError,
   WorkerTimeoutError,
   decodeRichtext,
   encodeRichtext,
   pluralize,
   richtextToPlainText,
-  singularize
+  singularize,
+  validateStateTransition,
+  validateUpdateStateMachine
 };
 //# sourceMappingURL=index.js.map