@affectively/aeon 1.0.0 → 1.2.0

package/dist/versioning/index.js

@@ -75,7 +75,9 @@ var SchemaVersionManager = class {
    */
   setCurrentVersion(version) {
     if (!this.versions.has(this.versionToString(version))) {
-      throw new Error(`Version ${this.versionToString(version)} not registered`);
+      throw new Error(
+        `Version ${this.versionToString(version)} not registered`
+      );
     }
     this.currentVersion = version;
     logger.debug("[SchemaVersionManager] Current version set", {
@@ -361,7 +363,9 @@ var MigrationEngine = class {
         id: migrationId,
         error: result.errors[0]
       });
-      throw new Error(`Rollback for ${migrationId} failed: ${result.errors[0]}`);
+      throw new Error(
+        `Rollback for ${migrationId} failed: ${result.errors[0]}`
+      );
     }
   }
   /**
@@ -414,8 +418,14 @@ var MigrationEngine = class {
   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);
+    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,
@@ -469,7 +479,9 @@ var DataTransformer = class {
       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)}`);
+        throw new Error(
+          `Failed to transform required field ${field}: ${error instanceof Error ? error.message : String(error)}`
+        );
       }
       return rule.defaultValue !== void 0 ? rule.defaultValue : value;
     }
@@ -542,7 +554,9 @@ var DataTransformer = class {
   validateTransformation(original, transformed) {
     const issues = [];
     if (original.length !== transformed.length) {
-      issues.push(`Item count mismatch: ${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];
@@ -633,14 +647,40 @@ var DataTransformer = class {
 };
 
 // src/versioning/MigrationTracker.ts
-var MigrationTracker = class {
+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,
@@ -697,7 +737,9 @@ var MigrationTracker = class {
    * Check if can rollback
    */
   canRollback(fromVersion, toVersion) {
-    const fromIndex = this.migrations.findIndex((m) => m.version === fromVersion);
+    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;
@@ -721,7 +763,9 @@ var MigrationTracker = class {
     const affectedVersions = [];
     let estimatedDuration = 0;
     if (canRollback) {
-      const fromIndex = this.migrations.findIndex((m) => m.version === fromVersion);
+      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];
@@ -777,12 +821,24 @@ var MigrationTracker = class {
    * Get migration statistics
    */
   getStatistics() {
-    const applied = this.migrations.filter((m) => m.status === "applied").length;
+    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);
+    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,
@@ -833,7 +889,147 @@ var MigrationTracker = class {
         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)
@@ -841,6 +1037,7 @@ var MigrationTracker = class {
   clear() {
     this.migrations = [];
     this.snapshots.clear();
+    this.schedulePersist();
   }
   /**
    * Get total migrations tracked
@@ -859,6 +1056,91 @@ var MigrationTracker = class {
       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");
+  }
 };
 
 export { DataTransformer, MigrationEngine, MigrationTracker, SchemaVersionManager };