@typicalday/firegraph 0.3.0 → 0.5.0

package/dist/index.cjs

@@ -40,6 +40,7 @@ __export(index_exports, {
   InvalidQueryError: () => InvalidQueryError,
   META_EDGE_TYPE: () => META_EDGE_TYPE,
   META_NODE_TYPE: () => META_NODE_TYPE,
+  MigrationError: () => MigrationError,
   NODE_TYPE_SCHEMA: () => NODE_TYPE_SCHEMA,
   NodeNotFoundError: () => NodeNotFoundError,
   QueryClient: () => QueryClient,
@@ -47,39 +48,53 @@ __export(index_exports, {
   QuerySafetyError: () => QuerySafetyError,
   RegistryScopeError: () => RegistryScopeError,
   RegistryViolationError: () => RegistryViolationError,
+  SERIALIZATION_TAG: () => SERIALIZATION_TAG,
   TraversalError: () => TraversalError,
   ValidationError: () => ValidationError,
   analyzeQuerySafety: () => analyzeQuerySafety,
+  applyMigrationChain: () => applyMigrationChain,
   buildEdgeQueryPlan: () => buildEdgeQueryPlan,
   buildEdgeRecord: () => buildEdgeRecord,
   buildNodeQueryPlan: () => buildNodeQueryPlan,
   buildNodeRecord: () => buildNodeRecord,
+  compileMigrationFn: () => compileMigrationFn,
+  compileMigrations: () => compileMigrations,
   compileSchema: () => compileSchema,
   computeEdgeDocId: () => computeEdgeDocId,
   computeNodeDocId: () => computeNodeDocId,
   createBootstrapRegistry: () => createBootstrapRegistry,
   createGraphClient: () => createGraphClient,
+  createMergedRegistry: () => createMergedRegistry,
   createRegistry: () => createRegistry,
   createRegistryFromGraph: () => createRegistryFromGraph,
   createTraversal: () => createTraversal,
+  defaultExecutor: () => defaultExecutor,
   defineConfig: () => defineConfig,
   defineViews: () => defineViews,
+  deserializeFirestoreTypes: () => deserializeFirestoreTypes,
+  destroySandboxWorker: () => destroySandboxWorker,
   discoverEntities: () => discoverEntities,
   generateDeterministicUid: () => generateDeterministicUid,
   generateId: () => generateId,
   generateIndexConfig: () => generateIndexConfig,
   generateTypes: () => generateTypes,
   isAncestorUid: () => isAncestorUid,
+  isTaggedValue: () => isTaggedValue,
   jsonSchemaToFieldMeta: () => jsonSchemaToFieldMeta,
   matchScope: () => matchScope,
   matchScopeAny: () => matchScopeAny,
+  migrateRecord: () => migrateRecord,
+  migrateRecords: () => migrateRecords,
+  precompileSource: () => precompileSource,
   resolveAncestorCollection: () => resolveAncestorCollection,
-  resolveView: () => resolveView
+  resolveView: () => resolveView,
+  serializeFirestoreTypes: () => serializeFirestoreTypes,
+  validateMigrationChain: () => validateMigrationChain
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/client.ts
-var import_firestore4 = require("@google-cloud/firestore");
+var import_firestore5 = require("@google-cloud/firestore");
 
 // src/docid.ts
 var import_node_crypto = require("crypto");
@@ -207,6 +222,12 @@ var RegistryScopeError = class extends FiregraphError {
     this.name = "RegistryScopeError";
   }
 };
+var MigrationError = class extends FiregraphError {
+  constructor(message) {
+    super(message, "MIGRATION_ERROR");
+    this.name = "MigrationError";
+  }
+};
 
 // src/query.ts
 function buildEdgeQueryPlan(params) {
@@ -397,7 +418,7 @@ function createPipelineQueryAdapter(db, collectionPath) {
 }
 
 // src/transaction.ts
-var import_firestore2 = require("@google-cloud/firestore");
+var import_firestore3 = require("@google-cloud/firestore");
 
 // src/query-safety.ts
 var SAFE_INDEX_PATTERNS = [
@@ -447,24 +468,248 @@ function analyzeQuerySafety(filters) {
   };
 }
 
+// src/serialization.ts
+var import_firestore2 = require("@google-cloud/firestore");
+var SERIALIZATION_TAG = "__firegraph_ser__";
+var KNOWN_TYPES = /* @__PURE__ */ new Set(["Timestamp", "GeoPoint", "VectorValue", "DocumentReference"]);
+var _docRefWarned = false;
+function isTaggedValue(value) {
+  if (value === null || typeof value !== "object") return false;
+  const tag = value[SERIALIZATION_TAG];
+  return typeof tag === "string" && KNOWN_TYPES.has(tag);
+}
+function isTimestamp(value) {
+  return value instanceof import_firestore2.Timestamp;
+}
+function isGeoPoint(value) {
+  return value instanceof import_firestore2.GeoPoint;
+}
+function isDocumentReference(value) {
+  if (value === null || typeof value !== "object") return false;
+  const v = value;
+  return typeof v.path === "string" && v.firestore !== void 0 && typeof v.id === "string" && v.constructor?.name === "DocumentReference";
+}
+function isVectorValue(value) {
+  if (value === null || typeof value !== "object") return false;
+  const v = value;
+  return v.constructor?.name === "VectorValue" && Array.isArray(v._values);
+}
+function serializeFirestoreTypes(data) {
+  return serializeValue(data);
+}
+function serializeValue(value) {
+  if (value === null || value === void 0) return value;
+  if (typeof value !== "object") return value;
+  if (isTimestamp(value)) {
+    return { [SERIALIZATION_TAG]: "Timestamp", seconds: value.seconds, nanoseconds: value.nanoseconds };
+  }
+  if (isGeoPoint(value)) {
+    return { [SERIALIZATION_TAG]: "GeoPoint", latitude: value.latitude, longitude: value.longitude };
+  }
+  if (isDocumentReference(value)) {
+    return { [SERIALIZATION_TAG]: "DocumentReference", path: value.path };
+  }
+  if (isVectorValue(value)) {
+    const v = value;
+    const values = typeof v.toArray === "function" ? v.toArray() : v._values;
+    return { [SERIALIZATION_TAG]: "VectorValue", values: [...values] };
+  }
+  if (Array.isArray(value)) {
+    return value.map(serializeValue);
+  }
+  const result = {};
+  for (const key of Object.keys(value)) {
+    result[key] = serializeValue(value[key]);
+  }
+  return result;
+}
+function deserializeFirestoreTypes(data, db) {
+  return deserializeValue(data, db);
+}
+function deserializeValue(value, db) {
+  if (value === null || value === void 0) return value;
+  if (typeof value !== "object") return value;
+  if (isTimestamp(value) || isGeoPoint(value) || isDocumentReference(value) || isVectorValue(value)) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((v) => deserializeValue(v, db));
+  }
+  const obj = value;
+  if (isTaggedValue(obj)) {
+    const tag = obj[SERIALIZATION_TAG];
+    switch (tag) {
+      case "Timestamp":
+        if (typeof obj.seconds !== "number" || typeof obj.nanoseconds !== "number") return obj;
+        return new import_firestore2.Timestamp(obj.seconds, obj.nanoseconds);
+      case "GeoPoint":
+        if (typeof obj.latitude !== "number" || typeof obj.longitude !== "number") return obj;
+        return new import_firestore2.GeoPoint(obj.latitude, obj.longitude);
+      case "VectorValue":
+        if (!Array.isArray(obj.values)) return obj;
+        return import_firestore2.FieldValue.vector(obj.values);
+      case "DocumentReference":
+        if (typeof obj.path !== "string") return obj;
+        if (db) {
+          return db.doc(obj.path);
+        }
+        if (!_docRefWarned) {
+          _docRefWarned = true;
+          console.warn(
+            "[firegraph] DocumentReference encountered during migration deserialization but no Firestore instance available. The reference will remain as a tagged object with its path. Enable write-back for full reconstruction."
+          );
+        }
+        return obj;
+      default:
+        return obj;
+    }
+  }
+  const result = {};
+  for (const key of Object.keys(obj)) {
+    result[key] = deserializeValue(obj[key], db);
+  }
+  return result;
+}
+
+// src/migration.ts
+async function applyMigrationChain(data, currentVersion, targetVersion, migrations) {
+  const sorted = [...migrations].sort((a, b) => a.fromVersion - b.fromVersion);
+  let result = { ...data };
+  let version = currentVersion;
+  for (const step of sorted) {
+    if (step.fromVersion === version) {
+      try {
+        result = await step.up(result);
+      } catch (err) {
+        if (err instanceof MigrationError) throw err;
+        throw new MigrationError(
+          `Migration from v${step.fromVersion} to v${step.toVersion} failed: ${err.message}`
+        );
+      }
+      if (!result || typeof result !== "object") {
+        throw new MigrationError(
+          `Migration from v${step.fromVersion} to v${step.toVersion} returned invalid data (expected object)`
+        );
+      }
+      version = step.toVersion;
+    }
+  }
+  if (version !== targetVersion) {
+    throw new MigrationError(
+      `Incomplete migration chain: reached v${version} but target is v${targetVersion}`
+    );
+  }
+  return result;
+}
+function validateMigrationChain(migrations, label) {
+  if (migrations.length === 0) return;
+  const seen = /* @__PURE__ */ new Set();
+  for (const step of migrations) {
+    if (step.toVersion <= step.fromVersion) {
+      throw new MigrationError(
+        `${label}: migration step has toVersion (${step.toVersion}) <= fromVersion (${step.fromVersion})`
+      );
+    }
+    if (seen.has(step.fromVersion)) {
+      throw new MigrationError(
+        `${label}: duplicate migration step for fromVersion ${step.fromVersion}`
+      );
+    }
+    seen.add(step.fromVersion);
+  }
+  const sorted = [...migrations].sort((a, b) => a.fromVersion - b.fromVersion);
+  const targetVersion = Math.max(...migrations.map((m) => m.toVersion));
+  let version = 0;
+  for (const step of sorted) {
+    if (step.fromVersion === version) {
+      version = step.toVersion;
+    } else if (step.fromVersion > version) {
+      throw new MigrationError(
+        `${label}: migration chain has a gap \u2014 no step covers v${version} \u2192 v${step.fromVersion}`
+      );
+    }
+  }
+  if (version !== targetVersion) {
+    throw new MigrationError(
+      `${label}: migration chain does not reach v${targetVersion} (stuck at v${version})`
+    );
+  }
+}
+async function migrateRecord(record, registry, globalWriteBack = "off") {
+  const entry = registry.lookup(record.aType, record.axbType, record.bType);
+  if (!entry?.migrations?.length || !entry.schemaVersion) {
+    return { record, migrated: false, writeBack: "off" };
+  }
+  const currentVersion = record.v ?? 0;
+  if (currentVersion >= entry.schemaVersion) {
+    return { record, migrated: false, writeBack: "off" };
+  }
+  const migratedData = await applyMigrationChain(
+    record.data,
+    currentVersion,
+    entry.schemaVersion,
+    entry.migrations
+  );
+  const writeBack = entry.migrationWriteBack ?? globalWriteBack ?? "off";
+  return {
+    record: { ...record, data: migratedData, v: entry.schemaVersion },
+    migrated: true,
+    writeBack
+  };
+}
+async function migrateRecords(records, registry, globalWriteBack = "off") {
+  return Promise.all(
+    records.map((r) => migrateRecord(r, registry, globalWriteBack))
+  );
+}
+
 // src/transaction.ts
 var GraphTransactionImpl = class {
-  constructor(adapter, registry, scanProtection = "error", scopePath = "") {
+  constructor(adapter, registry, scanProtection = "error", scopePath = "", globalWriteBack = "off", db) {
     this.adapter = adapter;
     this.registry = registry;
     this.scanProtection = scanProtection;
     this.scopePath = scopePath;
+    this.globalWriteBack = globalWriteBack;
+    this.db = db;
   }
   async getNode(uid) {
     const docId = computeNodeDocId(uid);
-    return this.adapter.getDoc(docId);
+    const record = await this.adapter.getDoc(docId);
+    if (!record || !this.registry) return record;
+    const result = await migrateRecord(record, this.registry, this.globalWriteBack);
+    if (result.migrated && result.writeBack !== "off") {
+      const update = {
+        data: deserializeFirestoreTypes(result.record.data, this.db),
+        updatedAt: import_firestore3.FieldValue.serverTimestamp()
+      };
+      if (result.record.v !== void 0) {
+        update.v = result.record.v;
+      }
+      this.adapter.updateDoc(docId, update);
+    }
+    return result.record;
   }
   async getEdge(aUid, axbType, bUid) {
     const docId = computeEdgeDocId(aUid, axbType, bUid);
-    return this.adapter.getDoc(docId);
+    const record = await this.adapter.getDoc(docId);
+    if (!record || !this.registry) return record;
+    const result = await migrateRecord(record, this.registry, this.globalWriteBack);
+    if (result.migrated && result.writeBack !== "off") {
+      const update = {
+        data: deserializeFirestoreTypes(result.record.data, this.db),
+        updatedAt: import_firestore3.FieldValue.serverTimestamp()
+      };
+      if (result.record.v !== void 0) {
+        update.v = result.record.v;
+      }
+      this.adapter.updateDoc(docId, update);
+    }
+    return result.record;
   }
   async edgeExists(aUid, axbType, bUid) {
-    const record = await this.getEdge(aUid, axbType, bUid);
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    const record = await this.adapter.getDoc(docId);
     return record !== null;
   }
   checkQuerySafety(filters, allowCollectionScan) {
@@ -478,21 +723,45 @@ var GraphTransactionImpl = class {
   }
   async findEdges(params) {
     const plan = buildEdgeQueryPlan(params);
+    let records;
     if (plan.strategy === "get") {
       const record = await this.adapter.getDoc(plan.docId);
-      return record ? [record] : [];
+      records = record ? [record] : [];
+    } else {
+      this.checkQuerySafety(plan.filters, params.allowCollectionScan);
+      records = await this.adapter.query(plan.filters, plan.options);
     }
-    this.checkQuerySafety(plan.filters, params.allowCollectionScan);
-    return this.adapter.query(plan.filters, plan.options);
+    return this.applyMigrations(records);
   }
   async findNodes(params) {
     const plan = buildNodeQueryPlan(params);
+    let records;
     if (plan.strategy === "get") {
       const record = await this.adapter.getDoc(plan.docId);
-      return record ? [record] : [];
+      records = record ? [record] : [];
+    } else {
+      this.checkQuerySafety(plan.filters, params.allowCollectionScan);
+      records = await this.adapter.query(plan.filters, plan.options);
+    }
+    return this.applyMigrations(records);
+  }
+  async applyMigrations(records) {
+    if (!this.registry || records.length === 0) return records;
+    const results = await migrateRecords(records, this.registry, this.globalWriteBack);
+    for (const result of results) {
+      if (result.migrated && result.writeBack !== "off") {
+        const docId = result.record.axbType === NODE_RELATION ? computeNodeDocId(result.record.aUid) : computeEdgeDocId(result.record.aUid, result.record.axbType, result.record.bUid);
+        const update = {
+          data: deserializeFirestoreTypes(result.record.data, this.db),
+          updatedAt: import_firestore3.FieldValue.serverTimestamp()
+        };
+        if (result.record.v !== void 0) {
+          update.v = result.record.v;
+        }
+        this.adapter.updateDoc(docId, update);
+      }
     }
-    this.checkQuerySafety(plan.filters, params.allowCollectionScan);
-    return this.adapter.query(plan.filters, plan.options);
+    return results.map((r) => r.record);
   }
   async putNode(aType, uid, data) {
     if (this.registry) {
@@ -500,6 +769,12 @@ var GraphTransactionImpl = class {
     }
     const docId = computeNodeDocId(uid);
     const record = buildNodeRecord(aType, uid, data);
+    if (this.registry) {
+      const entry = this.registry.lookup(aType, NODE_RELATION, aType);
+      if (entry?.schemaVersion && entry.schemaVersion > 0) {
+        record.v = entry.schemaVersion;
+      }
+    }
     this.adapter.setDoc(docId, record);
   }
   async putEdge(aType, aUid, axbType, bType, bUid, data) {
@@ -508,13 +783,19 @@ var GraphTransactionImpl = class {
     }
     const docId = computeEdgeDocId(aUid, axbType, bUid);
     const record = buildEdgeRecord(aType, aUid, axbType, bType, bUid, data);
+    if (this.registry) {
+      const entry = this.registry.lookup(aType, axbType, bType);
+      if (entry?.schemaVersion && entry.schemaVersion > 0) {
+        record.v = entry.schemaVersion;
+      }
+    }
     this.adapter.setDoc(docId, record);
   }
   async updateNode(uid, data) {
     const docId = computeNodeDocId(uid);
     this.adapter.updateDoc(docId, {
       ...data,
-      updatedAt: import_firestore2.FieldValue.serverTimestamp()
+      updatedAt: import_firestore3.FieldValue.serverTimestamp()
     });
   }
   async removeNode(uid) {
@@ -528,7 +809,7 @@ var GraphTransactionImpl = class {
 };
 
 // src/batch.ts
-var import_firestore3 = require("@google-cloud/firestore");
+var import_firestore4 = require("@google-cloud/firestore");
 var GraphBatchImpl = class {
   constructor(adapter, registry, scopePath = "") {
     this.adapter = adapter;
@@ -541,6 +822,12 @@ var GraphBatchImpl = class {
     }
     const docId = computeNodeDocId(uid);
     const record = buildNodeRecord(aType, uid, data);
+    if (this.registry) {
+      const entry = this.registry.lookup(aType, NODE_RELATION, aType);
+      if (entry?.schemaVersion && entry.schemaVersion > 0) {
+        record.v = entry.schemaVersion;
+      }
+    }
     this.adapter.setDoc(docId, record);
   }
   async putEdge(aType, aUid, axbType, bType, bUid, data) {
@@ -549,13 +836,19 @@ var GraphBatchImpl = class {
     }
     const docId = computeEdgeDocId(aUid, axbType, bUid);
     const record = buildEdgeRecord(aType, aUid, axbType, bType, bUid, data);
+    if (this.registry) {
+      const entry = this.registry.lookup(aType, axbType, bType);
+      if (entry?.schemaVersion && entry.schemaVersion > 0) {
+        record.v = entry.schemaVersion;
+      }
+    }
     this.adapter.setDoc(docId, record);
   }
   async updateNode(uid, data) {
     const docId = computeNodeDocId(uid);
     this.adapter.updateDoc(docId, {
       ...data,
-      updatedAt: import_firestore3.FieldValue.serverTimestamp()
+      updatedAt: import_firestore4.FieldValue.serverTimestamp()
     });
   }
   async removeNode(uid) {
@@ -714,7 +1007,7 @@ async function removeNodeCascade(db, collectionPath, reader, uid, options) {
 }
 
 // src/dynamic-registry.ts
-var import_node_crypto2 = require("crypto");
+var import_node_crypto3 = require("crypto");
 
 // src/json-schema.ts
 var import_ajv = __toESM(require("ajv"), 1);
@@ -845,6 +1138,9 @@ function matchSegments(path, pi, pattern, qi) {
 function tripleKey(aType, axbType, bType) {
   return `${aType}:${axbType}:${bType}`;
 }
+function tripleKeyFor(e) {
+  return tripleKey(e.aType, e.axbType, e.bType);
+}
 function createRegistry(input) {
   const map = /* @__PURE__ */ new Map();
   let entries;
@@ -860,6 +1156,13 @@ function createRegistry(input) {
         `Entry (${entry.aType}) -[${entry.axbType}]-> (${entry.bType}) has invalid targetGraph "${entry.targetGraph}" \u2014 must be a single segment (no "/")`
       );
     }
+    if (entry.migrations?.length) {
+      const label = `Entry (${entry.aType}) -[${entry.axbType}]-> (${entry.bType})`;
+      validateMigrationChain(entry.migrations, label);
+      entry.schemaVersion = Math.max(...entry.migrations.map((m) => m.toVersion));
+    } else {
+      entry.schemaVersion = void 0;
+    }
     const key = tripleKey(entry.aType, entry.axbType, entry.bType);
     const validator = entry.jsonSchema ? compileSchema(entry.jsonSchema, `(${entry.aType}) -[${entry.axbType}]-> (${entry.bType})`) : void 0;
     map.set(key, { entry, validate: validator });
@@ -911,6 +1214,45 @@ function createRegistry(input) {
     }
   };
 }
+function createMergedRegistry(base, extension) {
+  const baseKeys = new Set(base.entries().map(tripleKeyFor));
+  return {
+    lookup(aType, axbType, bType) {
+      return base.lookup(aType, axbType, bType) ?? extension.lookup(aType, axbType, bType);
+    },
+    lookupByAxbType(axbType) {
+      const baseResults = base.lookupByAxbType(axbType);
+      const extResults = extension.lookupByAxbType(axbType);
+      if (extResults.length === 0) return baseResults;
+      if (baseResults.length === 0) return extResults;
+      const seen = new Set(baseResults.map(tripleKeyFor));
+      const merged = [...baseResults];
+      for (const entry of extResults) {
+        if (!seen.has(tripleKeyFor(entry))) {
+          merged.push(entry);
+        }
+      }
+      return Object.freeze(merged);
+    },
+    validate(aType, axbType, bType, data, scopePath) {
+      if (baseKeys.has(tripleKey(aType, axbType, bType))) {
+        return base.validate(aType, axbType, bType, data, scopePath);
+      }
+      return extension.validate(aType, axbType, bType, data, scopePath);
+    },
+    entries() {
+      const extEntries = extension.entries();
+      if (extEntries.length === 0) return base.entries();
+      const merged = [...base.entries()];
+      for (const entry of extEntries) {
+        if (!baseKeys.has(tripleKeyFor(entry))) {
+          merged.push(entry);
+        }
+      }
+      return Object.freeze(merged);
+    }
+  };
+}
 function discoveryToEntries(discovery) {
   const entries = [];
   for (const [name, entity] of discovery.nodes) {
@@ -922,7 +1264,9 @@ function discoveryToEntries(discovery) {
       description: entity.description,
       titleField: entity.titleField,
       subtitleField: entity.subtitleField,
-      allowedIn: entity.allowedIn
+      allowedIn: entity.allowedIn,
+      migrations: entity.migrations,
+      migrationWriteBack: entity.migrationWriteBack
     });
   }
   for (const [axbType, entity] of discovery.edges) {
@@ -948,7 +1292,9 @@ function discoveryToEntries(discovery) {
           titleField: entity.titleField,
           subtitleField: entity.subtitleField,
           allowedIn: entity.allowedIn,
-          targetGraph: resolvedTargetGraph
+          targetGraph: resolvedTargetGraph,
+          migrations: entity.migrations,
+          migrationWriteBack: entity.migrationWriteBack
         });
       }
     }
@@ -956,9 +1302,259 @@ function discoveryToEntries(discovery) {
   return entries;
 }
 
+// src/sandbox.ts
+var import_node_worker_threads = require("worker_threads");
+var import_node_crypto2 = require("crypto");
+var import_meta = {};
+var _worker = null;
+var _requestId = 0;
+var _pending = /* @__PURE__ */ new Map();
+var WORKER_SOURCE = [
+  `'use strict';`,
+  `var _wt = require('node:worker_threads');`,
+  `var _mod = require('node:module');`,
+  `var _crypto = require('node:crypto');`,
+  `var parentPort = _wt.parentPort;`,
+  `var workerData = _wt.workerData;`,
+  ``,
+  `// Load SES using the parent module's resolution context`,
+  `var esmRequire = _mod.createRequire(workerData.parentUrl);`,
+  `esmRequire('ses');`,
+  ``,
+  `lockdown({`,
+  `  errorTaming: 'unsafe',`,
+  `  consoleTaming: 'unsafe',`,
+  `  evalTaming: 'safe-eval',`,
+  `  overrideTaming: 'moderate',`,
+  `  stackFiltering: 'verbose'`,
+  `});`,
+  ``,
+  `// Defense-in-depth: verify lockdown() actually hardened JSON.`,
+  `if (!Object.isFrozen(JSON)) {`,
+  `  throw new Error('SES lockdown failed: JSON is not frozen');`,
+  `}`,
+  ``,
+  `var cache = new Map();`,
+  ``,
+  `function hashSource(s) {`,
+  `  return _crypto.createHash('sha256').update(s).digest('hex');`,
+  `}`,
+  ``,
+  `function buildWrapper(source) {`,
+  `  return '(function() {' +`,
+  `    '  var fn = (' + source + ');\\n' +`,
+  `    '  if (typeof fn !== "function") return null;\\n' +`,
+  `    '  return function(jsonIn) {\\n' +`,
+  `    '    var data = JSON.parse(jsonIn);\\n' +`,
+  `    '    var result = fn(data);\\n' +`,
+  `    '    if (result !== null && typeof result === "object" && typeof result.then === "function") {\\n' +`,
+  `    '      return result.then(function(r) { return JSON.stringify(r); });\\n' +`,
+  `    '    }\\n' +`,
+  `    '    return JSON.stringify(result);\\n' +`,
+  `    '  };\\n' +`,
+  `    '})()';`,
+  `}`,
+  ``,
+  `function compileSource(source) {`,
+  `  var key = hashSource(source);`,
+  `  var cached = cache.get(key);`,
+  `  if (cached) return cached;`,
+  ``,
+  `  var compartmentFn;`,
+  `  try {`,
+  `    var c = new Compartment({ JSON: JSON });`,
+  `    compartmentFn = c.evaluate(buildWrapper(source));`,
+  `  } catch (err) {`,
+  `    throw new Error('Failed to compile migration source: ' + (err.message || String(err)));`,
+  `  }`,
+  ``,
+  `  if (typeof compartmentFn !== 'function') {`,
+  `    throw new Error('Migration source did not produce a function: ' + source.slice(0, 80));`,
+  `  }`,
+  ``,
+  `  cache.set(key, compartmentFn);`,
+  `  return compartmentFn;`,
+  `}`,
+  ``,
+  `parentPort.on('message', function(msg) {`,
+  `  var id = msg.id;`,
+  `  try {`,
+  `    if (msg.type === 'compile') {`,
+  `      compileSource(msg.source);`,
+  `      parentPort.postMessage({ id: id, type: 'compiled' });`,
+  `      return;`,
+  `    }`,
+  `    if (msg.type === 'execute') {`,
+  `      var fn = compileSource(msg.source);`,
+  `      var raw;`,
+  `      try {`,
+  `        raw = fn(msg.jsonData);`,
+  `      } catch (err) {`,
+  `        parentPort.postMessage({ id: id, type: 'error', message: 'Migration function threw: ' + (err.message || String(err)) });`,
+  `        return;`,
+  `      }`,
+  `      if (raw !== null && typeof raw === 'object' && typeof raw.then === 'function') {`,
+  `        raw.then(`,
+  `          function(jsonResult) {`,
+  `            if (jsonResult === undefined || jsonResult === null) {`,
+  `              parentPort.postMessage({ id: id, type: 'error', message: 'Migration returned a non-JSON-serializable value' });`,
+  `            } else {`,
+  `              parentPort.postMessage({ id: id, type: 'result', jsonResult: jsonResult });`,
+  `            }`,
+  `          },`,
+  `          function(err) {`,
+  `            parentPort.postMessage({ id: id, type: 'error', message: 'Async migration function threw: ' + (err.message || String(err)) });`,
+  `          }`,
+  `        );`,
+  `        return;`,
+  `      }`,
+  `      if (raw === undefined || raw === null) {`,
+  `        parentPort.postMessage({ id: id, type: 'error', message: 'Migration returned a non-JSON-serializable value' });`,
+  `      } else {`,
+  `        parentPort.postMessage({ id: id, type: 'result', jsonResult: raw });`,
+  `      }`,
+  `    }`,
+  `  } catch (err) {`,
+  `    parentPort.postMessage({ id: id, type: 'error', message: err.message || String(err) });`,
+  `  }`,
+  `});`
+].join("\n");
+function ensureWorker() {
+  if (_worker) return _worker;
+  _worker = new import_node_worker_threads.Worker(WORKER_SOURCE, {
+    eval: true,
+    workerData: { parentUrl: import_meta.url }
+  });
+  _worker.unref();
+  _worker.on("message", (msg) => {
+    if (msg.id === void 0) return;
+    const pending = _pending.get(msg.id);
+    if (!pending) return;
+    _pending.delete(msg.id);
+    if (msg.type === "error") {
+      pending.reject(new MigrationError(msg.message ?? "Unknown sandbox error"));
+    } else {
+      pending.resolve(msg);
+    }
+  });
+  _worker.on("error", (err) => {
+    for (const [, p] of _pending) {
+      p.reject(new MigrationError(`Sandbox worker error: ${err.message}`));
+    }
+    _pending.clear();
+    _worker = null;
+  });
+  _worker.on("exit", (code) => {
+    if (_pending.size > 0) {
+      for (const [, p] of _pending) {
+        p.reject(new MigrationError(`Sandbox worker exited with code ${code}`));
+      }
+      _pending.clear();
+    }
+    _worker = null;
+  });
+  return _worker;
+}
+function sendToWorker(msg) {
+  const worker = ensureWorker();
+  if (_requestId >= Number.MAX_SAFE_INTEGER) _requestId = 0;
+  const id = ++_requestId;
+  return new Promise((resolve2, reject) => {
+    _pending.set(id, { resolve: resolve2, reject });
+    worker.postMessage({ ...msg, id });
+  });
+}
+var compiledCache = /* @__PURE__ */ new WeakMap();
+function getExecutorCache(executor) {
+  let cache = compiledCache.get(executor);
+  if (!cache) {
+    cache = /* @__PURE__ */ new Map();
+    compiledCache.set(executor, cache);
+  }
+  return cache;
+}
+function hashSource(source) {
+  return (0, import_node_crypto2.createHash)("sha256").update(source).digest("hex");
+}
+function defaultExecutor(source) {
+  ensureWorker();
+  return ((data) => {
+    const jsonData = JSON.stringify(serializeFirestoreTypes(data));
+    return sendToWorker({ type: "execute", source, jsonData }).then(
+      (response) => {
+        if (response.jsonResult === void 0 || response.jsonResult === null) {
+          throw new MigrationError("Migration returned a non-JSON-serializable value");
+        }
+        try {
+          return deserializeFirestoreTypes(JSON.parse(response.jsonResult));
+        } catch {
+          throw new MigrationError("Migration returned a non-JSON-serializable value");
+        }
+      }
+    );
+  });
+}
+async function precompileSource(source, executor) {
+  if (executor && executor !== defaultExecutor) {
+    try {
+      executor(source);
+    } catch (err) {
+      if (err instanceof MigrationError) throw err;
+      throw new MigrationError(
+        `Failed to compile migration source: ${err.message}`
+      );
+    }
+    return;
+  }
+  await sendToWorker({ type: "compile", source });
+}
+function compileMigrationFn(source, executor = defaultExecutor) {
+  const cache = getExecutorCache(executor);
+  const key = hashSource(source);
+  const cached = cache.get(key);
+  if (cached) return cached;
+  try {
+    const fn = executor(source);
+    cache.set(key, fn);
+    return fn;
+  } catch (err) {
+    if (err instanceof MigrationError) throw err;
+    throw new MigrationError(
+      `Failed to compile migration source: ${err.message}`
+    );
+  }
+}
+function compileMigrations(stored, executor) {
+  return stored.map((step) => ({
+    fromVersion: step.fromVersion,
+    toVersion: step.toVersion,
+    up: compileMigrationFn(step.up, executor)
+  }));
+}
+async function destroySandboxWorker() {
+  if (!_worker) return;
+  const w = _worker;
+  _worker = null;
+  for (const [, p] of _pending) {
+    p.reject(new MigrationError("Sandbox worker terminated"));
+  }
+  _pending.clear();
+  await w.terminate();
+}
+
 // src/dynamic-registry.ts
 var META_NODE_TYPE = "nodeType";
 var META_EDGE_TYPE = "edgeType";
+var STORED_MIGRATION_STEP_SCHEMA = {
+  type: "object",
+  required: ["fromVersion", "toVersion", "up"],
+  properties: {
+    fromVersion: { type: "integer", minimum: 0 },
+    toVersion: { type: "integer", minimum: 1 },
+    up: { type: "string", minLength: 1 }
+  },
+  additionalProperties: false
+};
 var NODE_TYPE_SCHEMA = {
   type: "object",
   required: ["name", "jsonSchema"],
@@ -970,7 +1566,10 @@ var NODE_TYPE_SCHEMA = {
     subtitleField: { type: "string" },
     viewTemplate: { type: "string" },
     viewCss: { type: "string" },
-    allowedIn: { type: "array", items: { type: "string", minLength: 1 } }
+    allowedIn: { type: "array", items: { type: "string", minLength: 1 } },
+    schemaVersion: { type: "integer", minimum: 0 },
+    migrations: { type: "array", items: STORED_MIGRATION_STEP_SCHEMA },
+    migrationWriteBack: { type: "string", enum: ["off", "eager", "background"] }
   },
   additionalProperties: false
 };
@@ -999,7 +1598,10 @@ var EDGE_TYPE_SCHEMA = {
     viewTemplate: { type: "string" },
     viewCss: { type: "string" },
     allowedIn: { type: "array", items: { type: "string", minLength: 1 } },
-    targetGraph: { type: "string", minLength: 1, pattern: "^[^/]+$" }
+    targetGraph: { type: "string", minLength: 1, pattern: "^[^/]+$" },
+    schemaVersion: { type: "integer", minimum: 0 },
+    migrations: { type: "array", items: STORED_MIGRATION_STEP_SCHEMA },
+    migrationWriteBack: { type: "string", enum: ["off", "eager", "background"] }
   },
   additionalProperties: false
 };
@@ -1023,15 +1625,33 @@ function createBootstrapRegistry() {
   return createRegistry([...BOOTSTRAP_ENTRIES]);
 }
 function generateDeterministicUid(metaType, name) {
-  const hash = (0, import_node_crypto2.createHash)("sha256").update(`${metaType}:${name}`).digest("base64url");
+  const hash = (0, import_node_crypto3.createHash)("sha256").update(`${metaType}:${name}`).digest("base64url");
   return hash.slice(0, 21);
 }
-async function createRegistryFromGraph(reader) {
+async function createRegistryFromGraph(reader, executor) {
   const [nodeTypes, edgeTypes] = await Promise.all([
     reader.findNodes({ aType: META_NODE_TYPE }),
     reader.findNodes({ aType: META_EDGE_TYPE })
   ]);
   const entries = [...BOOTSTRAP_ENTRIES];
+  const prevalidations = [];
+  for (const record of nodeTypes) {
+    const data = record.data;
+    if (data.migrations) {
+      for (const m of data.migrations) {
+        prevalidations.push(precompileSource(m.up, executor));
+      }
+    }
+  }
+  for (const record of edgeTypes) {
+    const data = record.data;
+    if (data.migrations) {
+      for (const m of data.migrations) {
+        prevalidations.push(precompileSource(m.up, executor));
+      }
+    }
+  }
+  await Promise.all(prevalidations);
   for (const record of nodeTypes) {
     const data = record.data;
     entries.push({
@@ -1042,13 +1662,16 @@ async function createRegistryFromGraph(reader) {
       description: data.description,
       titleField: data.titleField,
       subtitleField: data.subtitleField,
-      allowedIn: data.allowedIn
+      allowedIn: data.allowedIn,
+      migrations: data.migrations ? compileMigrations(data.migrations, executor) : void 0,
+      migrationWriteBack: data.migrationWriteBack
     });
   }
   for (const record of edgeTypes) {
     const data = record.data;
     const fromTypes = Array.isArray(data.from) ? data.from : [data.from];
     const toTypes = Array.isArray(data.to) ? data.to : [data.to];
+    const compiledMigrations = data.migrations ? compileMigrations(data.migrations, executor) : void 0;
     for (const aType of fromTypes) {
       for (const bType of toTypes) {
         entries.push({
@@ -1061,7 +1684,9 @@ async function createRegistryFromGraph(reader) {
           titleField: data.titleField,
           subtitleField: data.subtitleField,
           allowedIn: data.allowedIn,
-          targetGraph: data.targetGraph
+          targetGraph: data.targetGraph,
+          migrations: compiledMigrations,
+          migrationWriteBack: data.migrationWriteBack
         });
       }
     }
@@ -1077,14 +1702,14 @@ var GraphClientImpl = class _GraphClientImpl {
     this.db = db;
     this.scopePath = scopePath;
     this.adapter = createFirestoreAdapter(db, collectionPath);
-    if (options?.registry && options?.registryMode) {
-      throw new DynamicRegistryError(
-        'Cannot provide both "registry" and "registryMode". Use "registry" for static mode or "registryMode" for dynamic mode.'
-      );
-    }
+    this.globalWriteBack = options?.migrationWriteBack ?? "off";
+    this.migrationSandbox = options?.migrationSandbox;
     if (options?.registryMode) {
       this.dynamicConfig = options.registryMode;
       this.bootstrapRegistry = createBootstrapRegistry();
+      if (options.registry) {
+        this.staticRegistry = options.registry;
+      }
       const metaCollectionPath = options.registryMode.collection;
       if (metaCollectionPath && metaCollectionPath !== collectionPath) {
         this.metaAdapter = createFirestoreAdapter(db, metaCollectionPath);
@@ -1130,24 +1755,29 @@ var GraphClientImpl = class _GraphClientImpl {
   metaPipelineAdapter;
   // Subgraph scope tracking
   scopePath;
+  // Migration settings
+  globalWriteBack;
+  migrationSandbox;
   // ---------------------------------------------------------------------------
   // Registry routing
   // ---------------------------------------------------------------------------
   /**
    * Get the appropriate registry for validating a write to the given type.
    *
-   * - Static mode: returns staticRegistry (or undefined if none set)
-   * - Dynamic mode:
+   * - Static-only mode: returns staticRegistry (or undefined if none set)
+   * - Dynamic mode (pure or merged):
    *   - Meta-types (nodeType, edgeType): validated against bootstrapRegistry
    *   - Domain types: validated against dynamicRegistry (falls back to
    *     bootstrapRegistry which rejects unknown types)
+   *   - Merged mode: dynamicRegistry is a merged wrapper (static + dynamic
+   *     extension), so static entries take priority automatically.
    */
   getRegistryForType(aType) {
     if (!this.dynamicConfig) return this.staticRegistry;
     if (aType === META_NODE_TYPE || aType === META_EDGE_TYPE) {
       return this.bootstrapRegistry;
     }
-    return this.dynamicRegistry ?? this.bootstrapRegistry;
+    return this.dynamicRegistry ?? this.staticRegistry ?? this.bootstrapRegistry;
   }
   /**
    * Get the Firestore adapter for writing the given type.
@@ -1161,13 +1791,13 @@ var GraphClientImpl = class _GraphClientImpl {
   }
   /**
    * Get the combined registry for transaction/batch context.
-   * In static mode, returns staticRegistry.
+   * In static-only mode, returns staticRegistry.
    * In dynamic mode, returns dynamicRegistry (which includes bootstrap entries)
-   * or bootstrapRegistry if not yet reloaded.
+   * or falls back to staticRegistry (merged mode) or bootstrapRegistry.
    */
   getCombinedRegistry() {
     if (!this.dynamicConfig) return this.staticRegistry;
-    return this.dynamicRegistry ?? this.bootstrapRegistry;
+    return this.dynamicRegistry ?? this.staticRegistry ?? this.bootstrapRegistry;
   }
   // ---------------------------------------------------------------------------
   // Query dispatch
@@ -1197,37 +1827,114 @@ var GraphClientImpl = class _GraphClientImpl {
     console.warn(`[firegraph] Query safety warning: ${result.reason}`);
   }
   // ---------------------------------------------------------------------------
+  // Migration helpers
+  // ---------------------------------------------------------------------------
+  /**
+   * Apply migration to a single record. Returns the (possibly migrated)
+   * record and triggers write-back if applicable.
+   */
+  async applyMigration(record, docId) {
+    const registry = this.getCombinedRegistry();
+    if (!registry) return record;
+    const result = await migrateRecord(record, registry, this.globalWriteBack);
+    if (result.migrated) {
+      this.handleWriteBack(result, docId);
+    }
+    return result.record;
+  }
+  /**
+   * Apply migrations to an array of records. Returns all records
+   * (migrated where applicable) and triggers write-backs.
+   */
+  async applyMigrations(records) {
+    const registry = this.getCombinedRegistry();
+    if (!registry || records.length === 0) return records;
+    const results = await migrateRecords(records, registry, this.globalWriteBack);
+    for (const result of results) {
+      if (result.migrated) {
+        const docId = result.record.axbType === NODE_RELATION ? computeNodeDocId(result.record.aUid) : computeEdgeDocId(result.record.aUid, result.record.axbType, result.record.bUid);
+        this.handleWriteBack(result, docId);
+      }
+    }
+    return results.map((r) => r.record);
+  }
+  /**
+   * Handle write-back for a migrated record based on the resolved mode.
+   *
+   * Both `'eager'` and `'background'` are fire-and-forget (not awaited by
+   * the caller). The difference is logging level on failure:
+   * - `eager`: logs an error via `console.error`
+   * - `background`: logs a warning via `console.warn`
+   *
+   * For truly synchronous write-back guarantees, use transactions — the
+   * `GraphTransactionImpl` performs write-back inline within the transaction.
+   */
+  handleWriteBack(result, docId) {
+    if (result.writeBack === "off") return;
+    const doWriteBack = async () => {
+      try {
+        const update = {
+          data: deserializeFirestoreTypes(result.record.data, this.db),
+          updatedAt: import_firestore5.FieldValue.serverTimestamp()
+        };
+        if (result.record.v !== void 0) {
+          update.v = result.record.v;
+        }
+        await this.adapter.updateDoc(docId, update);
+      } catch (err) {
+        const msg = `[firegraph] Migration write-back failed for ${docId}: ${err.message}`;
+        if (result.writeBack === "eager") {
+          console.error(msg);
+        } else {
+          console.warn(msg);
+        }
+      }
+    };
+    void doWriteBack();
+  }
+  // ---------------------------------------------------------------------------
   // GraphReader
   // ---------------------------------------------------------------------------
   async getNode(uid) {
     const docId = computeNodeDocId(uid);
-    return this.adapter.getDoc(docId);
+    const record = await this.adapter.getDoc(docId);
+    if (!record) return null;
+    return this.applyMigration(record, docId);
   }
   async getEdge(aUid, axbType, bUid) {
     const docId = computeEdgeDocId(aUid, axbType, bUid);
-    return this.adapter.getDoc(docId);
+    const record = await this.adapter.getDoc(docId);
+    if (!record) return null;
+    return this.applyMigration(record, docId);
   }
   async edgeExists(aUid, axbType, bUid) {
-    const record = await this.getEdge(aUid, axbType, bUid);
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    const record = await this.adapter.getDoc(docId);
     return record !== null;
   }
   async findEdges(params) {
     const plan = buildEdgeQueryPlan(params);
+    let records;
     if (plan.strategy === "get") {
       const record = await this.adapter.getDoc(plan.docId);
-      return record ? [record] : [];
+      records = record ? [record] : [];
+    } else {
+      this.checkQuerySafety(plan.filters, params.allowCollectionScan);
+      records = await this.executeQuery(plan.filters, plan.options);
     }
-    this.checkQuerySafety(plan.filters, params.allowCollectionScan);
-    return this.executeQuery(plan.filters, plan.options);
+    return this.applyMigrations(records);
   }
   async findNodes(params) {
     const plan = buildNodeQueryPlan(params);
+    let records;
     if (plan.strategy === "get") {
       const record = await this.adapter.getDoc(plan.docId);
-      return record ? [record] : [];
+      records = record ? [record] : [];
+    } else {
+      this.checkQuerySafety(plan.filters, params.allowCollectionScan);
+      records = await this.executeQuery(plan.filters, plan.options);
     }
-    this.checkQuerySafety(plan.filters, params.allowCollectionScan);
-    return this.executeQuery(plan.filters, plan.options);
+    return this.applyMigrations(records);
   }
   // ---------------------------------------------------------------------------
   // GraphWriter
@@ -1240,6 +1947,12 @@ var GraphClientImpl = class _GraphClientImpl {
     const adapter = this.getAdapterForType(aType);
     const docId = computeNodeDocId(uid);
     const record = buildNodeRecord(aType, uid, data);
+    if (registry) {
+      const entry = registry.lookup(aType, NODE_RELATION, aType);
+      if (entry?.schemaVersion && entry.schemaVersion > 0) {
+        record.v = entry.schemaVersion;
+      }
+    }
     await adapter.setDoc(docId, record);
   }
   async putEdge(aType, aUid, axbType, bType, bUid, data) {
@@ -1250,13 +1963,19 @@ var GraphClientImpl = class _GraphClientImpl {
     const adapter = this.getAdapterForType(aType);
     const docId = computeEdgeDocId(aUid, axbType, bUid);
     const record = buildEdgeRecord(aType, aUid, axbType, bType, bUid, data);
+    if (registry) {
+      const entry = registry.lookup(aType, axbType, bType);
+      if (entry?.schemaVersion && entry.schemaVersion > 0) {
+        record.v = entry.schemaVersion;
+      }
+    }
     await adapter.setDoc(docId, record);
   }
   async updateNode(uid, data) {
     const docId = computeNodeDocId(uid);
     await this.adapter.updateDoc(docId, {
       ...data,
-      updatedAt: import_firestore4.FieldValue.serverTimestamp()
+      updatedAt: import_firestore5.FieldValue.serverTimestamp()
     });
   }
   async removeNode(uid) {
@@ -1277,7 +1996,7 @@ var GraphClientImpl = class _GraphClientImpl {
         this.adapter.collectionPath,
         firestoreTx
       );
-      const graphTx = new GraphTransactionImpl(adapter, this.getCombinedRegistry(), this.scanProtection, this.scopePath);
+      const graphTx = new GraphTransactionImpl(adapter, this.getCombinedRegistry(), this.scanProtection, this.scopePath, this.globalWriteBack, this.db);
       return fn(graphTx);
     });
   }
@@ -1309,7 +2028,9 @@ var GraphClientImpl = class _GraphClientImpl {
       {
         registry: this.getCombinedRegistry(),
         queryMode: this.queryMode === "pipeline" ? "pipeline" : "standard",
-        scanProtection: this.scanProtection
+        scanProtection: this.scanProtection,
+        migrationWriteBack: this.globalWriteBack,
+        migrationSandbox: this.migrationSandbox
       },
       newScopePath
     );
@@ -1339,7 +2060,8 @@ var GraphClientImpl = class _GraphClientImpl {
       q = q.limit(plan.options.limit);
     }
     const snap = await q.get();
-    return snap.docs.map((doc) => doc.data());
+    const records = snap.docs.map((doc) => doc.data());
+    return this.applyMigrations(records);
   }
   // ---------------------------------------------------------------------------
   // Bulk operations
@@ -1364,6 +2086,11 @@ var GraphClientImpl = class _GraphClientImpl {
         `Cannot define type "${name}": this name is reserved for the meta-registry.`
       );
     }
+    if (this.staticRegistry?.lookup(name, NODE_RELATION, name)) {
+      throw new DynamicRegistryError(
+        `Cannot define node type "${name}": already defined in the static registry.`
+      );
+    }
     const uid = generateDeterministicUid(META_NODE_TYPE, name);
     const data = { name, jsonSchema };
     if (description !== void 0) data.description = description;
@@ -1372,6 +2099,10 @@ var GraphClientImpl = class _GraphClientImpl {
     if (options?.viewTemplate !== void 0) data.viewTemplate = options.viewTemplate;
     if (options?.viewCss !== void 0) data.viewCss = options.viewCss;
     if (options?.allowedIn !== void 0) data.allowedIn = options.allowedIn;
+    if (options?.migrationWriteBack !== void 0) data.migrationWriteBack = options.migrationWriteBack;
+    if (options?.migrations !== void 0) {
+      data.migrations = await this.serializeMigrations(options.migrations);
+    }
     await this.putNode(META_NODE_TYPE, uid, data);
   }
   async defineEdgeType(name, topology, jsonSchema, description, options) {
@@ -1385,6 +2116,19 @@ var GraphClientImpl = class _GraphClientImpl {
         `Cannot define type "${name}": this name is reserved for the meta-registry.`
       );
     }
+    if (this.staticRegistry) {
+      const fromTypes = Array.isArray(topology.from) ? topology.from : [topology.from];
+      const toTypes = Array.isArray(topology.to) ? topology.to : [topology.to];
+      for (const aType of fromTypes) {
+        for (const bType of toTypes) {
+          if (this.staticRegistry.lookup(aType, name, bType)) {
+            throw new DynamicRegistryError(
+              `Cannot define edge type "${name}" for (${aType}) -> (${bType}): already defined in the static registry.`
+            );
+          }
+        }
+      }
+    }
     const uid = generateDeterministicUid(META_EDGE_TYPE, name);
     const data = {
       name,
@@ -1400,6 +2144,10 @@ var GraphClientImpl = class _GraphClientImpl {
     if (options?.viewTemplate !== void 0) data.viewTemplate = options.viewTemplate;
     if (options?.viewCss !== void 0) data.viewCss = options.viewCss;
     if (options?.allowedIn !== void 0) data.allowedIn = options.allowedIn;
+    if (options?.migrationWriteBack !== void 0) data.migrationWriteBack = options.migrationWriteBack;
+    if (options?.migrations !== void 0) {
+      data.migrations = await this.serializeMigrations(options.migrations);
+    }
     await this.putNode(META_EDGE_TYPE, uid, data);
   }
   async reloadRegistry() {
@@ -1409,7 +2157,27 @@ var GraphClientImpl = class _GraphClientImpl {
       );
     }
     const reader = this.createMetaReader();
-    this.dynamicRegistry = await createRegistryFromGraph(reader);
+    const dynamicOnly = await createRegistryFromGraph(reader, this.migrationSandbox);
+    if (this.staticRegistry) {
+      this.dynamicRegistry = createMergedRegistry(this.staticRegistry, dynamicOnly);
+    } else {
+      this.dynamicRegistry = dynamicOnly;
+    }
+  }
+  /**
+   * Serialize migration steps for storage in Firestore.
+   * Function objects are converted via `.toString()`; strings are stored as-is.
+   * Each migration is validated at define-time by pre-compiling in the sandbox.
+   */
+  async serializeMigrations(migrations) {
+    const result = migrations.map((m) => {
+      const source = typeof m.up === "function" ? m.up.toString() : m.up;
+      return { fromVersion: m.fromVersion, toVersion: m.toVersion, up: source };
+    });
+    await Promise.all(
+      result.map((m) => precompileSource(m.up, this.migrationSandbox))
+    );
+    return result;
   }
   /**
    * Create a GraphReader for the meta-collection.
@@ -1777,7 +2545,7 @@ function resolveView(resolverConfig, availableViewNames, context) {
 var import_node_fs = require("fs");
 var import_node_module = require("module");
 var import_node_path = require("path");
-var import_meta = {};
+var import_meta2 = {};
 var DiscoveryError = class extends FiregraphError {
   constructor(message) {
     super(message, "DISCOVERY_ERROR");
@@ -1816,7 +2584,7 @@ function loadSchema(dir, entityLabel) {
 var _jiti;
 function getJiti() {
   if (!_jiti) {
-    const base = typeof __filename !== "undefined" ? __filename : import_meta.url;
+    const base = typeof __filename !== "undefined" ? __filename : import_meta2.url;
     const esmRequire = (0, import_node_module.createRequire)(base);
     const { createJiti } = esmRequire("jiti");
     _jiti = createJiti(base, { interopDefault: true });
@@ -1849,11 +2617,39 @@ function findViewsFile(dir) {
   }
   return void 0;
 }
+var MIGRATION_EXTENSIONS = [".ts", ".js", ".mts", ".mjs"];
+function findMigrationsFile(dir) {
+  for (const ext of MIGRATION_EXTENSIONS) {
+    const candidate = (0, import_node_path.join)(dir, `migrations${ext}`);
+    if ((0, import_node_fs.existsSync)(candidate)) return candidate;
+  }
+  return void 0;
+}
+function loadMigrations(filePath, entityLabel) {
+  try {
+    const jiti = getJiti();
+    const mod = jiti(filePath);
+    const migrations = mod && typeof mod === "object" && "default" in mod ? mod.default : mod;
+    if (!Array.isArray(migrations)) {
+      throw new DiscoveryError(
+        `Migrations file ${filePath} for ${entityLabel} must default-export an array of MigrationStep.`
+      );
+    }
+    return migrations;
+  } catch (err) {
+    if (err instanceof DiscoveryError) throw err;
+    throw new DiscoveryError(
+      `Failed to load migrations ${filePath} for ${entityLabel}: ${err.message}`
+    );
+  }
+}
 function loadNodeEntity(dir, name) {
   const schema = loadSchema(dir, `node type "${name}"`);
   const meta = readJsonIfExists((0, import_node_path.join)(dir, "meta.json"));
   const sampleData = readJsonIfExists((0, import_node_path.join)(dir, "sample.json"));
   const viewsPath = findViewsFile(dir);
+  const migrationsPath = findMigrationsFile(dir);
+  const migrations = migrationsPath ? loadMigrations(migrationsPath, `node type "${name}"`) : void 0;
   return {
     kind: "node",
     name,
@@ -1864,7 +2660,9 @@ function loadNodeEntity(dir, name) {
     viewDefaults: meta?.viewDefaults,
     viewsPath,
     sampleData,
-    allowedIn: meta?.allowedIn
+    allowedIn: meta?.allowedIn,
+    migrations,
+    migrationWriteBack: meta?.migrationWriteBack
   };
 }
 function loadEdgeEntity(dir, name) {
@@ -1889,6 +2687,8 @@ function loadEdgeEntity(dir, name) {
   const meta = readJsonIfExists((0, import_node_path.join)(dir, "meta.json"));
   const sampleData = readJsonIfExists((0, import_node_path.join)(dir, "sample.json"));
   const viewsPath = findViewsFile(dir);
+  const migrationsPath = findMigrationsFile(dir);
+  const migrations = migrationsPath ? loadMigrations(migrationsPath, `edge type "${name}"`) : void 0;
   return {
     kind: "edge",
     name,
@@ -1901,7 +2701,9 @@ function loadEdgeEntity(dir, name) {
     viewsPath,
     sampleData,
     allowedIn: meta?.allowedIn,
-    targetGraph: topology.targetGraph ?? meta?.targetGraph
+    targetGraph: topology.targetGraph ?? meta?.targetGraph,
+    migrations,
+    migrationWriteBack: meta?.migrationWriteBack
   };
 }
 function getSubdirectories(dir) {
@@ -2412,6 +3214,7 @@ var QueryClient = class {
   InvalidQueryError,
   META_EDGE_TYPE,
   META_NODE_TYPE,
+  MigrationError,
   NODE_TYPE_SCHEMA,
   NodeNotFoundError,
   QueryClient,
@@ -2419,33 +3222,47 @@ var QueryClient = class {
   QuerySafetyError,
   RegistryScopeError,
   RegistryViolationError,
+  SERIALIZATION_TAG,
   TraversalError,
   ValidationError,
   analyzeQuerySafety,
+  applyMigrationChain,
   buildEdgeQueryPlan,
   buildEdgeRecord,
   buildNodeQueryPlan,
   buildNodeRecord,
+  compileMigrationFn,
+  compileMigrations,
   compileSchema,
   computeEdgeDocId,
   computeNodeDocId,
   createBootstrapRegistry,
   createGraphClient,
+  createMergedRegistry,
   createRegistry,
   createRegistryFromGraph,
   createTraversal,
+  defaultExecutor,
   defineConfig,
   defineViews,
+  deserializeFirestoreTypes,
+  destroySandboxWorker,
   discoverEntities,
   generateDeterministicUid,
   generateId,
   generateIndexConfig,
   generateTypes,
   isAncestorUid,
+  isTaggedValue,
   jsonSchemaToFieldMeta,
   matchScope,
   matchScopeAny,
+  migrateRecord,
+  migrateRecords,
+  precompileSource,
   resolveAncestorCollection,
-  resolveView
+  resolveView,
+  serializeFirestoreTypes,
+  validateMigrationChain
 });
 //# sourceMappingURL=index.cjs.map