@a0n/aeon 5.0.1

package/dist/versioning/index.cjs

@@ -0,0 +1,1164 @@
+'use strict';
+
+// src/utils/logger.ts
+var consoleLogger = {
+  debug: (...args) => {
+    console.debug("[AEON:DEBUG]", ...args);
+  },
+  info: (...args) => {
+    console.info("[AEON:INFO]", ...args);
+  },
+  warn: (...args) => {
+    console.warn("[AEON:WARN]", ...args);
+  },
+  error: (...args) => {
+    console.error("[AEON:ERROR]", ...args);
+  }
+};
+var currentLogger = consoleLogger;
+function getLogger() {
+  return currentLogger;
+}
+var logger = {
+  debug: (...args) => getLogger().debug(...args),
+  info: (...args) => getLogger().info(...args),
+  warn: (...args) => getLogger().warn(...args),
+  error: (...args) => getLogger().error(...args)
+};
+
+// src/versioning/SchemaVersionManager.ts
+var SchemaVersionManager = class {
+  versions = /* @__PURE__ */ new Map();
+  versionHistory = [];
+  compatibilityMatrix = /* @__PURE__ */ new Map();
+  currentVersion = null;
+  constructor() {
+    this.initializeDefaultVersions();
+  }
+  /**
+   * Initialize default versions
+   */
+  initializeDefaultVersions() {
+    const v1_0_0 = {
+      major: 1,
+      minor: 0,
+      patch: 0,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      description: "Initial schema version",
+      breaking: false
+    };
+    this.registerVersion(v1_0_0);
+    this.currentVersion = v1_0_0;
+  }
+  /**
+   * Register a new schema version
+   */
+  registerVersion(version) {
+    const versionString = this.versionToString(version);
+    this.versions.set(versionString, version);
+    this.versionHistory.push(version);
+    logger.debug("[SchemaVersionManager] Version registered", {
+      version: versionString,
+      breaking: version.breaking,
+      description: version.description
+    });
+  }
+  /**
+   * Get current version
+   */
+  getCurrentVersion() {
+    if (!this.currentVersion) {
+      throw new Error("No current version set");
+    }
+    return this.currentVersion;
+  }
+  /**
+   * Set current version
+   */
+  setCurrentVersion(version) {
+    if (!this.versions.has(this.versionToString(version))) {
+      throw new Error(
+        `Version ${this.versionToString(version)} not registered`
+      );
+    }
+    this.currentVersion = version;
+    logger.debug("[SchemaVersionManager] Current version set", {
+      version: this.versionToString(version)
+    });
+  }
+  /**
+   * Get version history
+   */
+  getVersionHistory() {
+    return [...this.versionHistory];
+  }
+  /**
+   * Check if version exists
+   */
+  hasVersion(version) {
+    return this.versions.has(this.versionToString(version));
+  }
+  /**
+   * Get version by string (e.g., "1.2.3")
+   */
+  getVersion(versionString) {
+    return this.versions.get(versionString);
+  }
+  /**
+   * Register compatibility rule
+   */
+  registerCompatibility(rule) {
+    if (!this.compatibilityMatrix.has(rule.from)) {
+      this.compatibilityMatrix.set(rule.from, []);
+    }
+    const rules = this.compatibilityMatrix.get(rule.from);
+    if (rules) {
+      rules.push(rule);
+    }
+    logger.debug("[SchemaVersionManager] Compatibility rule registered", {
+      from: rule.from,
+      to: rule.to,
+      compatible: rule.compatible,
+      requiresMigration: rule.requiresMigration
+    });
+  }
+  /**
+   * Check if migration path exists
+   */
+  canMigrate(fromVersion, toVersion) {
+    const fromStr = typeof fromVersion === "string" ? fromVersion : this.versionToString(fromVersion);
+    const toStr = typeof toVersion === "string" ? toVersion : this.versionToString(toVersion);
+    const rules = this.compatibilityMatrix.get(fromStr) || [];
+    return rules.some((r) => r.to === toStr && r.requiresMigration);
+  }
+  /**
+   * Get migration path
+   */
+  getMigrationPath(fromVersion, toVersion) {
+    const path = [];
+    let current = fromVersion;
+    const maxSteps = 100;
+    let steps = 0;
+    while (this.compareVersions(current, toVersion) !== 0 && steps < maxSteps) {
+      const fromStr = this.versionToString(current);
+      const rules = this.compatibilityMatrix.get(fromStr) || [];
+      let found = false;
+      for (const rule of rules) {
+        const nextVersion = this.getVersion(rule.to);
+        if (nextVersion) {
+          if (this.compareVersions(nextVersion, toVersion) <= 0 || this.compareVersions(current, nextVersion) < this.compareVersions(current, toVersion)) {
+            current = nextVersion;
+            path.push(current);
+            found = true;
+            break;
+          }
+        }
+      }
+      if (!found) {
+        break;
+      }
+      steps++;
+    }
+    return path;
+  }
+  /**
+   * Compare two versions
+   * Returns: -1 if v1 < v2, 0 if equal, 1 if v1 > v2
+   */
+  compareVersions(v1, v2) {
+    const ver1 = typeof v1 === "string" ? this.parseVersion(v1) : v1;
+    const ver2 = typeof v2 === "string" ? this.parseVersion(v2) : v2;
+    if (ver1.major !== ver2.major) {
+      return ver1.major < ver2.major ? -1 : 1;
+    }
+    if (ver1.minor !== ver2.minor) {
+      return ver1.minor < ver2.minor ? -1 : 1;
+    }
+    if (ver1.patch !== ver2.patch) {
+      return ver1.patch < ver2.patch ? -1 : 1;
+    }
+    return 0;
+  }
+  /**
+   * Parse version string to SchemaVersion
+   */
+  parseVersion(versionString) {
+    const parts = versionString.split(".").map(Number);
+    const safeInt = (v) => v !== void 0 && Number.isFinite(v) ? v : 0;
+    return {
+      major: safeInt(parts[0]),
+      minor: safeInt(parts[1]),
+      patch: safeInt(parts[2]),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      description: "",
+      breaking: false
+    };
+  }
+  /**
+   * Create new version
+   */
+  createVersion(major, minor, patch, description, breaking = false) {
+    return {
+      major,
+      minor,
+      patch,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      description,
+      breaking
+    };
+  }
+  /**
+   * Convert version to string
+   */
+  versionToString(version) {
+    return `${version.major}.${version.minor}.${version.patch}`;
+  }
+  /**
+   * Get version metadata
+   */
+  getVersionMetadata(version) {
+    const history = this.versionHistory;
+    const currentIndex = history.findIndex(
+      (v) => this.versionToString(v) === this.versionToString(version)
+    );
+    return {
+      version,
+      previousVersion: currentIndex > 0 ? history[currentIndex - 1] : void 0,
+      changes: [version.description],
+      migrationsRequired: this.canMigrate(
+        this.currentVersion || version,
+        version
+      ) ? [this.versionToString(version)] : [],
+      rollbackPossible: currentIndex > 0
+    };
+  }
+  /**
+   * Get all registered versions
+   */
+  getAllVersions() {
+    return Array.from(this.versions.values()).sort(
+      (a, b) => this.compareVersions(a, b)
+    );
+  }
+  /**
+   * Clear all versions (for testing)
+   */
+  clear() {
+    this.versions.clear();
+    this.versionHistory = [];
+    this.compatibilityMatrix.clear();
+    this.currentVersion = null;
+  }
+};
+
+// src/versioning/MigrationEngine.ts
+var MigrationEngine = class {
+  migrations = /* @__PURE__ */ new Map();
+  executedMigrations = [];
+  state = {
+    currentVersion: "1.0.0",
+    appliedMigrations: [],
+    failedMigrations: [],
+    lastMigrationTime: (/* @__PURE__ */ new Date()).toISOString(),
+    totalMigrationsRun: 0
+  };
+  /**
+   * Register a migration
+   */
+  registerMigration(migration) {
+    this.migrations.set(migration.id, migration);
+    logger.debug("[MigrationEngine] Migration registered", {
+      id: migration.id,
+      version: migration.version,
+      name: migration.name
+    });
+  }
+  /**
+   * Execute a migration
+   */
+  async executeMigration(migrationId, data) {
+    const migration = this.migrations.get(migrationId);
+    if (!migration) {
+      throw new Error(`Migration ${migrationId} not found`);
+    }
+    const startTime = Date.now();
+    const result = {
+      migrationId,
+      success: false,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      duration: 0,
+      itemsAffected: 0,
+      errors: []
+    };
+    try {
+      logger.debug("[MigrationEngine] Executing migration", {
+        id: migrationId,
+        version: migration.version
+      });
+      migration.up(data);
+      result.success = true;
+      result.itemsAffected = Array.isArray(data) ? data.length : 1;
+      result.duration = Date.now() - startTime;
+      this.state.appliedMigrations.push(migrationId);
+      this.state.currentVersion = migration.version;
+      this.state.totalMigrationsRun++;
+      this.state.lastMigrationTime = result.timestamp;
+      this.executedMigrations.push(result);
+      logger.debug("[MigrationEngine] Migration executed successfully", {
+        id: migrationId,
+        duration: result.duration,
+        itemsAffected: result.itemsAffected
+      });
+      return result;
+    } catch (error) {
+      result.errors = [error instanceof Error ? error.message : String(error)];
+      this.state.failedMigrations.push(migrationId);
+      this.executedMigrations.push(result);
+      logger.error("[MigrationEngine] Migration failed", {
+        id: migrationId,
+        error: result.errors[0]
+      });
+      throw new Error(`Migration ${migrationId} failed: ${result.errors[0]}`);
+    }
+  }
+  /**
+   * Rollback a migration
+   */
+  async rollbackMigration(migrationId, data) {
+    const migration = this.migrations.get(migrationId);
+    if (!migration) {
+      throw new Error(`Migration ${migrationId} not found`);
+    }
+    if (!migration.down) {
+      throw new Error(`Migration ${migrationId} does not support rollback`);
+    }
+    const startTime = Date.now();
+    const result = {
+      migrationId,
+      success: false,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      duration: 0,
+      itemsAffected: 0,
+      errors: []
+    };
+    try {
+      logger.debug("[MigrationEngine] Rolling back migration", {
+        id: migrationId,
+        version: migration.version
+      });
+      migration.down(data);
+      result.success = true;
+      result.itemsAffected = Array.isArray(data) ? data.length : 1;
+      result.duration = Date.now() - startTime;
+      this.state.appliedMigrations = this.state.appliedMigrations.filter(
+        (id) => id !== migrationId
+      );
+      this.executedMigrations.push(result);
+      logger.debug("[MigrationEngine] Migration rolled back", {
+        id: migrationId,
+        duration: result.duration
+      });
+      return result;
+    } catch (error) {
+      result.errors = [error instanceof Error ? error.message : String(error)];
+      this.executedMigrations.push(result);
+      logger.error("[MigrationEngine] Rollback failed", {
+        id: migrationId,
+        error: result.errors[0]
+      });
+      throw new Error(
+        `Rollback for ${migrationId} failed: ${result.errors[0]}`
+      );
+    }
+  }
+  /**
+   * Get migration state
+   */
+  getState() {
+    return { ...this.state };
+  }
+  /**
+   * Get migration execution history
+   */
+  getExecutionHistory() {
+    return [...this.executedMigrations];
+  }
+  /**
+   * Get migration by ID
+   */
+  getMigration(migrationId) {
+    return this.migrations.get(migrationId);
+  }
+  /**
+   * Get all registered migrations
+   */
+  getAllMigrations() {
+    return Array.from(this.migrations.values());
+  }
+  /**
+   * Get applied migrations
+   */
+  getAppliedMigrations() {
+    return [...this.state.appliedMigrations];
+  }
+  /**
+   * Get failed migrations
+   */
+  getFailedMigrations() {
+    return [...this.state.failedMigrations];
+  }
+  /**
+   * Get pending migrations
+   */
+  getPendingMigrations() {
+    return this.getAllMigrations().filter(
+      (m) => !this.state.appliedMigrations.includes(m.id)
+    );
+  }
+  /**
+   * Get migration statistics
+   */
+  getStatistics() {
+    const successful = this.executedMigrations.filter((m) => m.success).length;
+    const failed = this.executedMigrations.filter((m) => !m.success).length;
+    const totalDuration = this.executedMigrations.reduce(
+      (sum, m) => sum + m.duration,
+      0
+    );
+    const totalAffected = this.executedMigrations.reduce(
+      (sum, m) => sum + m.itemsAffected,
+      0
+    );
+    return {
+      totalExecuted: this.executedMigrations.length,
+      successful,
+      failed,
+      successRate: this.executedMigrations.length > 0 ? successful / this.executedMigrations.length * 100 : 0,
+      totalDurationMs: totalDuration,
+      averageDurationMs: this.executedMigrations.length > 0 ? totalDuration / this.executedMigrations.length : 0,
+      totalAffected
+    };
+  }
+  /**
+   * Clear history (for testing)
+   */
+  clear() {
+    this.migrations.clear();
+    this.executedMigrations = [];
+    this.state = {
+      currentVersion: "1.0.0",
+      appliedMigrations: [],
+      failedMigrations: [],
+      lastMigrationTime: (/* @__PURE__ */ new Date()).toISOString(),
+      totalMigrationsRun: 0
+    };
+  }
+};
+
+// src/versioning/DataTransformer.ts
+var DataTransformer = class {
+  rules = /* @__PURE__ */ new Map();
+  transformationHistory = [];
+  /**
+   * Register a transformation rule
+   */
+  registerRule(rule) {
+    this.rules.set(rule.field, rule);
+    logger.debug("[DataTransformer] Rule registered", {
+      field: rule.field,
+      required: rule.required,
+      hasDefault: rule.defaultValue !== void 0
+    });
+  }
+  /**
+   * Transform a single field value
+   */
+  transformField(field, value) {
+    const rule = this.rules.get(field);
+    if (!rule) {
+      return value;
+    }
+    try {
+      return rule.transformer(value);
+    } catch (error) {
+      if (rule.required) {
+        throw new Error(
+          `Failed to transform required field ${field}: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+      return rule.defaultValue !== void 0 ? rule.defaultValue : value;
+    }
+  }
+  /**
+   * Transform a single object
+   */
+  transformObject(data) {
+    const transformed = {};
+    for (const [key, value] of Object.entries(data)) {
+      try {
+        transformed[key] = this.transformField(key, value);
+      } catch (error) {
+        logger.warn("[DataTransformer] Field transformation failed", {
+          field: key,
+          error: error instanceof Error ? error.message : String(error)
+        });
+        const rule = this.rules.get(key);
+        if (!rule || !rule.required) {
+          transformed[key] = value;
+        }
+      }
+    }
+    return transformed;
+  }
+  /**
+   * Transform a collection of items
+   */
+  transformCollection(items) {
+    const startTime = Date.now();
+    const result = {
+      success: true,
+      itemsTransformed: 0,
+      itemsFailed: 0,
+      errors: [],
+      warnings: [],
+      duration: 0
+    };
+    for (let i = 0; i < items.length; i++) {
+      const item = items[i];
+      try {
+        if (typeof item === "object" && item !== null && !Array.isArray(item)) {
+          this.transformObject(item);
+          result.itemsTransformed++;
+        } else {
+          result.warnings.push(`Item ${i} is not a transformable object`);
+        }
+      } catch (error) {
+        result.errors.push({
+          item,
+          error: error instanceof Error ? error.message : String(error)
+        });
+        result.itemsFailed++;
+      }
+    }
+    result.duration = Date.now() - startTime;
+    result.success = result.itemsFailed === 0;
+    this.transformationHistory.push(result);
+    logger.debug("[DataTransformer] Collection transformed", {
+      total: items.length,
+      transformed: result.itemsTransformed,
+      failed: result.itemsFailed,
+      duration: result.duration
+    });
+    return result;
+  }
+  /**
+   * Validate transformed data
+   */
+  validateTransformation(original, transformed) {
+    const issues = [];
+    if (original.length !== transformed.length) {
+      issues.push(
+        `Item count mismatch: ${original.length} -> ${transformed.length}`
+      );
+    }
+    for (let i = 0; i < Math.min(original.length, transformed.length); i++) {
+      const orig = original[i];
+      const trans = transformed[i];
+      if (!this.validateItem(orig, trans)) {
+        issues.push(`Item ${i} validation failed`);
+      }
+    }
+    return {
+      valid: issues.length === 0,
+      issues
+    };
+  }
+  /**
+   * Validate a single item transformation
+   */
+  validateItem(original, transformed) {
+    if (original === null || original === void 0) {
+      return true;
+    }
+    if (typeof original === "object" && typeof transformed !== "object") {
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Get transformation history
+   */
+  getTransformationHistory() {
+    return [...this.transformationHistory];
+  }
+  /**
+   * Get transformation statistics
+   */
+  getStatistics() {
+    const totalTransformed = this.transformationHistory.reduce(
+      (sum, r) => sum + r.itemsTransformed,
+      0
+    );
+    const totalFailed = this.transformationHistory.reduce(
+      (sum, r) => sum + r.itemsFailed,
+      0
+    );
+    const totalDuration = this.transformationHistory.reduce(
+      (sum, r) => sum + r.duration,
+      0
+    );
+    return {
+      totalBatches: this.transformationHistory.length,
+      totalTransformed,
+      totalFailed,
+      successRate: totalTransformed + totalFailed > 0 ? totalTransformed / (totalTransformed + totalFailed) * 100 : 0,
+      totalDurationMs: totalDuration,
+      averageBatchDurationMs: this.transformationHistory.length > 0 ? totalDuration / this.transformationHistory.length : 0
+    };
+  }
+  /**
+   * Get registered rules
+   */
+  getRules() {
+    return Array.from(this.rules.values());
+  }
+  /**
+   * Get rule for field
+   */
+  getRule(field) {
+    return this.rules.get(field);
+  }
+  /**
+   * Clear all rules (for testing)
+   */
+  clearRules() {
+    this.rules.clear();
+  }
+  /**
+   * Clear history (for testing)
+   */
+  clearHistory() {
+    this.transformationHistory = [];
+  }
+  /**
+   * Clear all state (for testing)
+   */
+  clear() {
+    this.clearRules();
+    this.clearHistory();
+  }
+};
+
+// src/versioning/MigrationTracker.ts
+var MigrationTracker = class _MigrationTracker {
+  static DEFAULT_PERSIST_KEY = "aeon:migration-tracker:v1";
+  static INTEGRITY_ROOT = "aeon:migration-integrity-root:v1";
+  migrations = [];
+  snapshots = /* @__PURE__ */ new Map();
+  persistence = null;
+  persistTimer = null;
+  persistInFlight = false;
+  persistPending = false;
+  constructor(options) {
+    if (options?.persistence) {
+      this.persistence = {
+        ...options.persistence,
+        key: options.persistence.key ?? _MigrationTracker.DEFAULT_PERSIST_KEY,
+        autoPersist: options.persistence.autoPersist ?? true,
+        autoLoad: options.persistence.autoLoad ?? false,
+        persistDebounceMs: options.persistence.persistDebounceMs ?? 25
+      };
+    }
+    if (this.persistence?.autoLoad) {
+      void this.loadFromPersistence().catch((error) => {
+        logger.error("[MigrationTracker] Failed to load persistence", {
+          key: this.persistence?.key,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      });
+    }
+  }
+  /**
+   * Track a new migration
+   */
+  recordMigration(record) {
+    this.migrations.push({ ...record });
+    this.schedulePersist();
+    logger.debug("[MigrationTracker] Migration recorded", {
+      id: record.id,
+      migrationId: record.migrationId,
+      version: record.version,
+      status: record.status
+    });
+  }
+  /**
+   * Track migration with snapshot
+   */
+  trackMigration(migrationId, version, beforeHash, afterHash, itemCount, duration, itemsAffected, appliedBy = "system") {
+    const record = {
+      id: `${migrationId}-${Date.now()}`,
+      migrationId,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      version,
+      direction: "up",
+      status: "applied",
+      duration,
+      itemsAffected,
+      dataSnapshot: {
+        beforeHash,
+        afterHash,
+        itemCount
+      },
+      appliedBy
+    };
+    this.recordMigration(record);
+    this.snapshots.set(record.id, {
+      beforeHash,
+      afterHash,
+      itemCount
+    });
+  }
+  /**
+   * Get all migration records
+   */
+  getMigrations() {
+    return this.migrations.map((m) => ({ ...m }));
+  }
+  /**
+   * Get migrations for a specific version
+   */
+  getMigrationsForVersion(version) {
+    return this.migrations.filter((m) => m.version === version);
+  }
+  /**
+   * Get migration by ID
+   */
+  getMigration(id) {
+    return this.migrations.find((m) => m.id === id);
+  }
+  /**
+   * Check if can rollback
+   */
+  canRollback(fromVersion, toVersion) {
+    const fromIndex = this.migrations.findIndex(
+      (m) => m.version === fromVersion
+    );
+    const toIndex = this.migrations.findIndex((m) => m.version === toVersion);
+    if (fromIndex === -1 || toIndex === -1) {
+      return false;
+    }
+    if (toIndex >= fromIndex) {
+      return false;
+    }
+    for (let i = fromIndex; i > toIndex; i--) {
+      if (!this.migrations[i]?.dataSnapshot) {
+        return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * Get rollback path
+   */
+  getRollbackPath(fromVersion, toVersion) {
+    const canRollback = this.canRollback(fromVersion, toVersion);
+    const path = [];
+    const affectedVersions = [];
+    let estimatedDuration = 0;
+    if (canRollback) {
+      const fromIndex = this.migrations.findIndex(
+        (m) => m.version === fromVersion
+      );
+      const toIndex = this.migrations.findIndex((m) => m.version === toVersion);
+      for (let i = fromIndex; i > toIndex; i--) {
+        const migration = this.migrations[i];
+        if (migration) {
+          path.push(migration.migrationId);
+          affectedVersions.push(migration.version);
+          estimatedDuration += migration.duration;
+        }
+      }
+    }
+    return {
+      path,
+      canRollback,
+      affectedVersions,
+      estimatedDuration
+    };
+  }
+  /**
+   * Get applied migrations
+   */
+  getAppliedMigrations() {
+    return this.migrations.filter((m) => m.status === "applied");
+  }
+  /**
+   * Get failed migrations
+   */
+  getFailedMigrations() {
+    return this.migrations.filter((m) => m.status === "failed");
+  }
+  /**
+   * Get pending migrations
+   */
+  getPendingMigrations() {
+    return this.migrations.filter((m) => m.status === "pending");
+  }
+  /**
+   * Get latest migration
+   */
+  getLatestMigration() {
+    return this.migrations[this.migrations.length - 1];
+  }
+  /**
+   * Get migration timeline
+   */
+  getTimeline() {
+    return this.migrations.map((m) => ({
+      timestamp: m.timestamp,
+      version: m.version,
+      status: m.status
+    }));
+  }
+  /**
+   * Get migration statistics
+   */
+  getStatistics() {
+    const applied = this.migrations.filter(
+      (m) => m.status === "applied"
+    ).length;
+    const failed = this.migrations.filter((m) => m.status === "failed").length;
+    const pending = this.migrations.filter(
+      (m) => m.status === "pending"
+    ).length;
+    const rolledBack = this.migrations.filter(
+      (m) => m.status === "rolled-back"
+    ).length;
+    const totalDuration = this.migrations.reduce(
+      (sum, m) => sum + m.duration,
+      0
+    );
+    const totalAffected = this.migrations.reduce(
+      (sum, m) => sum + m.itemsAffected,
+      0
+    );
+    return {
+      total: this.migrations.length,
+      applied,
+      failed,
+      pending,
+      rolledBack,
+      successRate: this.migrations.length > 0 ? applied / this.migrations.length * 100 : 0,
+      totalDurationMs: totalDuration,
+      averageDurationMs: this.migrations.length > 0 ? totalDuration / this.migrations.length : 0,
+      totalItemsAffected: totalAffected
+    };
+  }
+  /**
+   * Get audit trail
+   */
+  getAuditTrail(migrationId) {
+    const filtered = migrationId ? this.migrations.filter((m) => m.migrationId === migrationId) : this.migrations;
+    return filtered.map((m) => ({
+      id: m.id,
+      timestamp: m.timestamp,
+      migrationId: m.migrationId,
+      version: m.version,
+      status: m.status,
+      appliedBy: m.appliedBy,
+      duration: m.duration,
+      itemsAffected: m.itemsAffected,
+      error: m.errorMessage
+    }));
+  }
+  /**
+   * Get data snapshot for recovery
+   */
+  getSnapshot(recordId) {
+    return this.snapshots.get(recordId);
+  }
+  /**
+   * Update migration status
+   */
+  updateMigrationStatus(recordId, status, error) {
+    const migration = this.migrations.find((m) => m.id === recordId);
+    if (migration) {
+      migration.status = status;
+      if (error) {
+        migration.errorMessage = error;
+      }
+      logger.debug("[MigrationTracker] Migration status updated", {
+        recordId,
+        status,
+        hasError: !!error
+      });
+      this.schedulePersist();
+    }
+  }
+  /**
+   * Persist tracker state with integrity chain verification metadata.
+   */
+  async saveToPersistence() {
+    if (!this.persistence) {
+      return;
+    }
+    const normalizedMigrations = this.migrations.map((migration) => ({
+      ...migration,
+      previousHash: void 0,
+      integrityHash: void 0
+    }));
+    const integrityEntries = [];
+    let previousHash = _MigrationTracker.INTEGRITY_ROOT;
+    for (const migration of normalizedMigrations) {
+      const hash = await this.computeDigestHex(
+        `${previousHash}|${this.stableStringify(migration)}`
+      );
+      integrityEntries.push({
+        recordId: migration.id,
+        previousHash,
+        hash
+      });
+      previousHash = hash;
+    }
+    const persistedMigrations = normalizedMigrations.map(
+      (migration, index) => ({
+        ...migration,
+        previousHash: integrityEntries[index]?.previousHash,
+        integrityHash: integrityEntries[index]?.hash
+      })
+    );
+    const data = {
+      migrations: persistedMigrations,
+      snapshots: Array.from(this.snapshots.entries()).map(
+        ([recordId, snapshot]) => ({
+          recordId,
+          beforeHash: snapshot.beforeHash,
+          afterHash: snapshot.afterHash,
+          itemCount: snapshot.itemCount
+        })
+      ),
+      integrity: {
+        algorithm: "sha256-chain-v1",
+        entries: integrityEntries,
+        rootHash: previousHash
+      }
+    };
+    const envelope = {
+      version: 1,
+      updatedAt: Date.now(),
+      data
+    };
+    const serialize = this.persistence.serializer ?? ((value) => JSON.stringify(value));
+    await this.persistence.adapter.setItem(
+      this.persistence.key,
+      serialize(envelope)
+    );
+  }
+  /**
+   * Load tracker state and verify integrity chain.
+   */
+  async loadFromPersistence() {
+    if (!this.persistence) {
+      return { migrations: 0, snapshots: 0 };
+    }
+    const raw = await this.persistence.adapter.getItem(this.persistence.key);
+    if (!raw) {
+      return { migrations: 0, snapshots: 0 };
+    }
+    const deserialize = this.persistence.deserializer ?? ((value) => JSON.parse(
+      value
+    ));
+    const envelope = deserialize(raw);
+    if (envelope.version !== 1 || !envelope.data) {
+      throw new Error("Invalid migration tracker persistence payload");
+    }
+    if (!Array.isArray(envelope.data.migrations) || !Array.isArray(envelope.data.snapshots) || !envelope.data.integrity || !Array.isArray(envelope.data.integrity.entries) || typeof envelope.data.integrity.rootHash !== "string") {
+      throw new Error("Invalid migration tracker persistence structure");
+    }
+    if (envelope.data.integrity.algorithm !== "sha256-chain-v1") {
+      throw new Error("Unsupported migration integrity algorithm");
+    }
+    if (envelope.data.integrity.entries.length !== envelope.data.migrations.length) {
+      throw new Error("Migration integrity entry count mismatch");
+    }
+    const validatedMigrations = [];
+    let previousHash = _MigrationTracker.INTEGRITY_ROOT;
+    for (let i = 0; i < envelope.data.migrations.length; i++) {
+      const migration = envelope.data.migrations[i];
+      const integrity = envelope.data.integrity.entries[i];
+      if (!this.isValidMigrationRecord(migration)) {
+        throw new Error("Invalid persisted migration record");
+      }
+      if (!integrity || integrity.recordId !== migration.id || integrity.previousHash !== previousHash) {
+        throw new Error("Migration integrity chain mismatch");
+      }
+      const expectedHash = await this.computeDigestHex(
+        `${previousHash}|${this.stableStringify({
+          ...migration,
+          previousHash: void 0,
+          integrityHash: void 0
+        })}`
+      );
+      if (expectedHash !== integrity.hash) {
+        throw new Error("Migration integrity verification failed");
+      }
+      validatedMigrations.push({
+        ...migration,
+        previousHash: integrity.previousHash,
+        integrityHash: integrity.hash
+      });
+      previousHash = expectedHash;
+    }
+    if (previousHash !== envelope.data.integrity.rootHash) {
+      throw new Error("Migration integrity root hash mismatch");
+    }
+    const validatedSnapshots = /* @__PURE__ */ new Map();
+    for (const snapshot of envelope.data.snapshots) {
+      if (typeof snapshot.recordId !== "string" || typeof snapshot.beforeHash !== "string" || typeof snapshot.afterHash !== "string" || typeof snapshot.itemCount !== "number") {
+        throw new Error("Invalid persisted migration snapshot");
+      }
+      validatedSnapshots.set(snapshot.recordId, {
+        beforeHash: snapshot.beforeHash,
+        afterHash: snapshot.afterHash,
+        itemCount: snapshot.itemCount
+      });
+    }
+    this.migrations = validatedMigrations;
+    this.snapshots = validatedSnapshots;
+    logger.debug("[MigrationTracker] Loaded from persistence", {
+      key: this.persistence.key,
+      migrations: this.migrations.length,
+      snapshots: this.snapshots.size
+    });
+    return {
+      migrations: this.migrations.length,
+      snapshots: this.snapshots.size
+    };
+  }
+  /**
+   * Remove persisted migration tracker state.
+   */
+  async clearPersistence() {
+    if (!this.persistence) {
+      return;
+    }
+    await this.persistence.adapter.removeItem(this.persistence.key);
+  }
+  /**
+   * Clear history (for testing)
+   */
+  clear() {
+    this.migrations = [];
+    this.snapshots.clear();
+    this.schedulePersist();
+  }
+  /**
+   * Get total migrations tracked
+   */
+  getTotalMigrations() {
+    return this.migrations.length;
+  }
+  /**
+   * Find migrations by time range
+   */
+  getMigrationsByTimeRange(startTime, endTime) {
+    const start = new Date(startTime).getTime();
+    const end = new Date(endTime).getTime();
+    return this.migrations.filter((m) => {
+      const time = new Date(m.timestamp).getTime();
+      return time >= start && time <= end;
+    });
+  }
+  schedulePersist() {
+    if (!this.persistence || this.persistence.autoPersist === false) {
+      return;
+    }
+    if (this.persistTimer) {
+      clearTimeout(this.persistTimer);
+    }
+    this.persistTimer = setTimeout(() => {
+      void this.persistSafely();
+    }, this.persistence.persistDebounceMs ?? 25);
+  }
+  async persistSafely() {
+    if (!this.persistence) {
+      return;
+    }
+    if (this.persistInFlight) {
+      this.persistPending = true;
+      return;
+    }
+    this.persistInFlight = true;
+    try {
+      await this.saveToPersistence();
+    } catch (error) {
+      logger.error("[MigrationTracker] Persistence write failed", {
+        key: this.persistence.key,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    } finally {
+      this.persistInFlight = false;
+      const shouldRunAgain = this.persistPending;
+      this.persistPending = false;
+      if (shouldRunAgain) {
+        void this.persistSafely();
+      }
+    }
+  }
+  isValidMigrationRecord(value) {
+    if (typeof value !== "object" || value === null) {
+      return false;
+    }
+    const record = value;
+    const validDirection = record.direction === "up" || record.direction === "down";
+    const validStatus = record.status === "pending" || record.status === "applied" || record.status === "failed" || record.status === "rolled-back";
+    return typeof record.id === "string" && typeof record.migrationId === "string" && typeof record.timestamp === "string" && typeof record.version === "string" && validDirection && validStatus && typeof record.duration === "number" && typeof record.itemsAffected === "number" && typeof record.appliedBy === "string";
+  }
+  stableStringify(value) {
+    if (value === null || typeof value !== "object") {
+      return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+      return `[${value.map((item) => this.stableStringify(item)).join(",")}]`;
+    }
+    const entries = Object.entries(value).sort(
+      ([a], [b]) => a.localeCompare(b)
+    );
+    return `{${entries.map(
+      ([key, entryValue]) => `${JSON.stringify(key)}:${this.stableStringify(entryValue)}`
+    ).join(",")}}`;
+  }
+  async computeDigestHex(value) {
+    if (globalThis.crypto?.subtle) {
+      const bytes = new TextEncoder().encode(value);
+      const normalized = bytes.buffer.slice(
+        bytes.byteOffset,
+        bytes.byteOffset + bytes.byteLength
+      );
+      const digest = await globalThis.crypto.subtle.digest(
+        "SHA-256",
+        normalized
+      );
+      return this.toHex(new Uint8Array(digest));
+    }
+    return this.fallbackDigestHex(value);
+  }
+  toHex(bytes) {
+    return Array.from(bytes).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+  }
+  fallbackDigestHex(value) {
+    let hash = 2166136261;
+    for (let i = 0; i < value.length; i++) {
+      hash ^= value.charCodeAt(i);
+      hash = Math.imul(hash, 16777619);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+  }
+};
+
+exports.DataTransformer = DataTransformer;
+exports.MigrationEngine = MigrationEngine;
+exports.MigrationTracker = MigrationTracker;
+exports.SchemaVersionManager = SchemaVersionManager;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map