@typicalday/firegraph 0.4.0 → 0.5.0

package/dist/index.js

@@ -7,7 +7,7 @@ import {
 } from "./chunk-KFA7G37W.js";
 
 // src/client.ts
-import { FieldValue as FieldValue4 } from "@google-cloud/firestore";
+import { FieldValue as FieldValue5 } from "@google-cloud/firestore";
 
 // src/docid.ts
 import { createHash } from "crypto";
@@ -135,6 +135,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) {
@@ -325,7 +331,7 @@ function createPipelineQueryAdapter(db, collectionPath) {
 }
 
 // src/transaction.ts
-import { FieldValue as FieldValue2 } from "@google-cloud/firestore";
+import { FieldValue as FieldValue3 } from "@google-cloud/firestore";
 
 // src/query-safety.ts
 var SAFE_INDEX_PATTERNS = [
@@ -375,24 +381,248 @@ function analyzeQuerySafety(filters) {
   };
 }
 
+// src/serialization.ts
+import { Timestamp, GeoPoint, FieldValue as FieldValue2 } from "@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 Timestamp;
+}
+function isGeoPoint(value) {
+  return value instanceof 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 Timestamp(obj.seconds, obj.nanoseconds);
+      case "GeoPoint":
+        if (typeof obj.latitude !== "number" || typeof obj.longitude !== "number") return obj;
+        return new GeoPoint(obj.latitude, obj.longitude);
+      case "VectorValue":
+        if (!Array.isArray(obj.values)) return obj;
+        return FieldValue2.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: FieldValue3.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: FieldValue3.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) {
@@ -406,21 +636,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: FieldValue3.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) {
@@ -428,6 +682,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) {
@@ -436,13 +696,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: FieldValue2.serverTimestamp()
+      updatedAt: FieldValue3.serverTimestamp()
     });
   }
   async removeNode(uid) {
@@ -456,7 +722,7 @@ var GraphTransactionImpl = class {
 };
 
 // src/batch.ts
-import { FieldValue as FieldValue3 } from "@google-cloud/firestore";
+import { FieldValue as FieldValue4 } from "@google-cloud/firestore";
 var GraphBatchImpl = class {
   constructor(adapter, registry, scopePath = "") {
     this.adapter = adapter;
@@ -469,6 +735,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) {
@@ -477,13 +749,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: FieldValue3.serverTimestamp()
+      updatedAt: FieldValue4.serverTimestamp()
     });
   }
   async removeNode(uid) {
@@ -642,7 +920,7 @@ async function removeNodeCascade(db, collectionPath, reader, uid, options) {
 }
 
 // src/dynamic-registry.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 
 // src/json-schema.ts
 import Ajv from "ajv";
@@ -791,6 +1069,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 });
@@ -892,7 +1177,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) {
@@ -918,7 +1205,9 @@ function discoveryToEntries(discovery) {
           titleField: entity.titleField,
           subtitleField: entity.subtitleField,
           allowedIn: entity.allowedIn,
-          targetGraph: resolvedTargetGraph
+          targetGraph: resolvedTargetGraph,
+          migrations: entity.migrations,
+          migrationWriteBack: entity.migrationWriteBack
         });
       }
     }
@@ -926,9 +1215,258 @@ function discoveryToEntries(discovery) {
   return entries;
 }
 
+// src/sandbox.ts
+import { Worker } from "worker_threads";
+import { createHash as createHash2 } from "crypto";
+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 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 createHash2("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"],
@@ -940,7 +1478,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
 };
@@ -969,7 +1510,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
 };
@@ -993,15 +1537,33 @@ function createBootstrapRegistry() {
   return createRegistry([...BOOTSTRAP_ENTRIES]);
 }
 function generateDeterministicUid(metaType, name) {
-  const hash = createHash2("sha256").update(`${metaType}:${name}`).digest("base64url");
+  const hash = createHash3("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({
@@ -1012,13 +1574,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({
@@ -1031,7 +1596,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
         });
       }
     }
@@ -1047,6 +1614,8 @@ var GraphClientImpl = class _GraphClientImpl {
     this.db = db;
     this.scopePath = scopePath;
     this.adapter = createFirestoreAdapter(db, collectionPath);
+    this.globalWriteBack = options?.migrationWriteBack ?? "off";
+    this.migrationSandbox = options?.migrationSandbox;
     if (options?.registryMode) {
       this.dynamicConfig = options.registryMode;
       this.bootstrapRegistry = createBootstrapRegistry();
@@ -1098,6 +1667,9 @@ var GraphClientImpl = class _GraphClientImpl {
   metaPipelineAdapter;
   // Subgraph scope tracking
   scopePath;
+  // Migration settings
+  globalWriteBack;
+  migrationSandbox;
   // ---------------------------------------------------------------------------
   // Registry routing
   // ---------------------------------------------------------------------------
@@ -1167,37 +1739,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: FieldValue5.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
@@ -1210,6 +1859,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) {
@@ -1220,13 +1875,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: FieldValue4.serverTimestamp()
+      updatedAt: FieldValue5.serverTimestamp()
     });
   }
   async removeNode(uid) {
@@ -1247,7 +1908,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);
     });
   }
@@ -1279,7 +1940,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
     );
@@ -1309,7 +1972,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
@@ -1347,6 +2011,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) {
@@ -1388,6 +2056,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() {
@@ -1397,13 +2069,28 @@ var GraphClientImpl = class _GraphClientImpl {
       );
     }
     const reader = this.createMetaReader();
-    const dynamicOnly = 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.
    * If meta-collection is the same as main collection, returns `this`.
@@ -1841,11 +2528,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 = join(dir, `migrations${ext}`);
+    if (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(join(dir, "meta.json"));
   const sampleData = readJsonIfExists(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,
@@ -1856,7 +2571,9 @@ function loadNodeEntity(dir, name) {
     viewDefaults: meta?.viewDefaults,
     viewsPath,
     sampleData,
-    allowedIn: meta?.allowedIn
+    allowedIn: meta?.allowedIn,
+    migrations,
+    migrationWriteBack: meta?.migrationWriteBack
   };
 }
 function loadEdgeEntity(dir, name) {
@@ -1881,6 +2598,8 @@ function loadEdgeEntity(dir, name) {
   const meta = readJsonIfExists(join(dir, "meta.json"));
   const sampleData = readJsonIfExists(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,
@@ -1893,7 +2612,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) {
@@ -2084,6 +2805,7 @@ export {
   InvalidQueryError,
   META_EDGE_TYPE,
   META_NODE_TYPE,
+  MigrationError,
   NODE_TYPE_SCHEMA,
   NodeNotFoundError,
   QueryClient,
@@ -2091,13 +2813,17 @@ export {
   QuerySafetyError,
   RegistryScopeError,
   RegistryViolationError,
+  SERIALIZATION_TAG,
   TraversalError,
   ValidationError,
   analyzeQuerySafety,
+  applyMigrationChain,
   buildEdgeQueryPlan,
   buildEdgeRecord,
   buildNodeQueryPlan,
   buildNodeRecord,
+  compileMigrationFn,
+  compileMigrations,
   compileSchema,
   computeEdgeDocId,
   computeNodeDocId,
@@ -2107,18 +2833,27 @@ export {
   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.js.map