@originals/sdk 1.1.0

package/src/migration/rollback/RollbackManager.ts

@@ -0,0 +1,170 @@
+/**
+ * RollbackManager - Handles migration rollbacks
+ */
+
+import {
+  MigrationStateEnum,
+  RollbackResult,
+  MigrationError,
+  MigrationErrorType,
+  IRollbackManager
+} from '../types';
+import { OriginalsConfig } from '../../types';
+import { CheckpointManager } from '../checkpoint/CheckpointManager';
+import { DIDManager } from '../../did/DIDManager';
+
+export class RollbackManager implements IRollbackManager {
+  constructor(
+    private config: OriginalsConfig,
+    private checkpointManager: CheckpointManager,
+    private didManager: DIDManager
+  ) {}
+
+  /**
+   * Rollback a migration to its checkpoint state
+   */
+  async rollback(migrationId: string, checkpointId: string): Promise<RollbackResult> {
+    const startTime = Date.now();
+    const errors: MigrationError[] = [];
+
+    try {
+      // Retrieve checkpoint
+      const checkpoint = await this.checkpointManager.getCheckpoint(checkpointId);
+      if (!checkpoint) {
+        const error: MigrationError = {
+          type: MigrationErrorType.ROLLBACK_ERROR,
+          code: 'CHECKPOINT_NOT_FOUND',
+          message: `Checkpoint ${checkpointId} not found`,
+          migrationId,
+          timestamp: Date.now()
+        };
+        errors.push(error);
+
+        return {
+          success: false,
+          migrationId,
+          checkpointId,
+          restoredState: MigrationStateEnum.QUARANTINED,
+          duration: Date.now() - startTime,
+          errors
+        };
+      }
+
+      // Verify checkpoint belongs to this migration
+      if (checkpoint.migrationId !== migrationId) {
+        const error: MigrationError = {
+          type: MigrationErrorType.ROLLBACK_ERROR,
+          code: 'CHECKPOINT_MISMATCH',
+          message: `Checkpoint ${checkpointId} does not belong to migration ${migrationId}`,
+          migrationId,
+          timestamp: Date.now()
+        };
+        errors.push(error);
+
+        return {
+          success: false,
+          migrationId,
+          checkpointId,
+          restoredState: MigrationStateEnum.QUARANTINED,
+          duration: Date.now() - startTime,
+          errors
+        };
+      }
+
+      // Perform rollback based on source layer
+      await this.performLayerSpecificRollback(checkpoint);
+
+      // Clean up any partial migration artifacts
+      await this.cleanupMigrationArtifacts(migrationId);
+
+      const duration = Date.now() - startTime;
+
+      // Verify rollback success
+      if (errors.length === 0) {
+        return {
+          success: true,
+          migrationId,
+          checkpointId,
+          restoredState: MigrationStateEnum.ROLLED_BACK,
+          duration,
+          errors: []
+        };
+      } else {
+        return {
+          success: false,
+          migrationId,
+          checkpointId,
+          restoredState: MigrationStateEnum.QUARANTINED,
+          duration,
+          errors
+        };
+      }
+    } catch (error) {
+      const rollbackError: MigrationError = {
+        type: MigrationErrorType.ROLLBACK_ERROR,
+        code: 'ROLLBACK_FAILED',
+        message: 'Rollback operation failed',
+        technicalDetails: error instanceof Error ? error.message : String(error),
+        migrationId,
+        timestamp: Date.now()
+      };
+      errors.push(rollbackError);
+
+      return {
+        success: false,
+        migrationId,
+        checkpointId,
+        restoredState: MigrationStateEnum.QUARANTINED,
+        duration: Date.now() - startTime,
+        errors
+      };
+    }
+  }
+
+  /**
+   * Perform layer-specific rollback operations
+   */
+  private async performLayerSpecificRollback(checkpoint: any): Promise<void> {
+    // For now, rollback mainly involves:
+    // 1. Ensuring source DID is still valid (it should be, as we don't delete it)
+    // 2. Cleaning up any partial artifacts on target layer
+    // 3. Restoring any modified state
+
+    // Verify source DID still resolves
+    const sourceDid = await this.didManager.resolveDID(checkpoint.sourceDid);
+    if (!sourceDid) {
+      throw new Error(`Source DID ${checkpoint.sourceDid} could not be resolved during rollback`);
+    }
+
+    // Layer-specific cleanup would go here
+    // For peer → webvh: Remove any published resources
+    // For webvh → btco: Nothing to do (Bitcoin tx cannot be reversed)
+    // For peer → btco: Nothing to do (Bitcoin tx cannot be reversed)
+  }
+
+  /**
+   * Clean up migration artifacts
+   */
+  private async cleanupMigrationArtifacts(migrationId: string): Promise<void> {
+    // Clean up any temporary files, partial uploads, etc.
+    // This is a placeholder for actual cleanup logic
+  }
+
+  /**
+   * Check if a rollback is possible
+   */
+  async canRollback(migrationId: string, checkpointId: string): Promise<boolean> {
+    try {
+      const checkpoint = await this.checkpointManager.getCheckpoint(checkpointId);
+      if (!checkpoint || checkpoint.migrationId !== migrationId) {
+        return false;
+      }
+
+      // Bitcoin transactions cannot be rolled back
+      // But we can still restore the source DID to working state
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+}

package/src/migration/state/StateMachine.ts

@@ -0,0 +1,92 @@
+/**
+ * StateMachine - Defines valid migration state transitions
+ */
+
+import { MigrationStateEnum } from '../types';
+
+export class StateMachine {
+  private transitions: Map<MigrationStateEnum, MigrationStateEnum[]>;
+
+  constructor() {
+    this.transitions = this.initializeTransitions();
+  }
+
+  /**
+   * Initialize valid state transitions
+   */
+  private initializeTransitions(): Map<MigrationStateEnum, MigrationStateEnum[]> {
+    const transitions = new Map<MigrationStateEnum, MigrationStateEnum[]>();
+
+    // PENDING can transition to VALIDATING or FAILED
+    transitions.set(MigrationStateEnum.PENDING, [
+      MigrationStateEnum.VALIDATING,
+      MigrationStateEnum.FAILED
+    ]);
+
+    // VALIDATING can transition to CHECKPOINTED or FAILED
+    transitions.set(MigrationStateEnum.VALIDATING, [
+      MigrationStateEnum.CHECKPOINTED,
+      MigrationStateEnum.FAILED
+    ]);
+
+    // CHECKPOINTED can transition to IN_PROGRESS or FAILED
+    transitions.set(MigrationStateEnum.CHECKPOINTED, [
+      MigrationStateEnum.IN_PROGRESS,
+      MigrationStateEnum.FAILED
+    ]);
+
+    // IN_PROGRESS can transition to ANCHORING (for btco), COMPLETED, or FAILED
+    transitions.set(MigrationStateEnum.IN_PROGRESS, [
+      MigrationStateEnum.ANCHORING,
+      MigrationStateEnum.COMPLETED,
+      MigrationStateEnum.FAILED
+    ]);
+
+    // ANCHORING can transition to COMPLETED or FAILED
+    transitions.set(MigrationStateEnum.ANCHORING, [
+      MigrationStateEnum.COMPLETED,
+      MigrationStateEnum.FAILED
+    ]);
+
+    // FAILED can transition to ROLLED_BACK or QUARANTINED
+    transitions.set(MigrationStateEnum.FAILED, [
+      MigrationStateEnum.ROLLED_BACK,
+      MigrationStateEnum.QUARANTINED
+    ]);
+
+    // COMPLETED, ROLLED_BACK, and QUARANTINED are terminal states
+    transitions.set(MigrationStateEnum.COMPLETED, []);
+    transitions.set(MigrationStateEnum.ROLLED_BACK, []);
+    transitions.set(MigrationStateEnum.QUARANTINED, []);
+
+    return transitions;
+  }
+
+  /**
+   * Check if a state transition is valid
+   */
+  canTransition(fromState: MigrationStateEnum, toState: MigrationStateEnum): boolean {
+    const validTransitions = this.transitions.get(fromState);
+    if (!validTransitions) {
+      return false;
+    }
+    return validTransitions.includes(toState);
+  }
+
+  /**
+   * Get all valid transitions from a given state
+   * Returns a copy to prevent external mutation of the transition table
+   */
+  getValidTransitions(fromState: MigrationStateEnum): MigrationStateEnum[] {
+    const transitions = this.transitions.get(fromState);
+    return transitions ? [...transitions] : [];
+  }
+
+  /**
+   * Check if a state is terminal (no further transitions)
+   */
+  isTerminalState(state: MigrationStateEnum): boolean {
+    const validTransitions = this.transitions.get(state);
+    return !validTransitions || validTransitions.length === 0;
+  }
+}

package/src/migration/state/StateTracker.ts

@@ -0,0 +1,156 @@
+/**
+ * StateTracker - Tracks migration state throughout the migration lifecycle
+ */
+
+import { v4 as uuidv4 } from 'uuid';
+import {
+  MigrationOptions,
+  MigrationState,
+  MigrationStateEnum,
+  IStateTracker
+} from '../types';
+import { OriginalsConfig } from '../../types';
+import { StateMachine } from './StateMachine';
+
+export class StateTracker implements IStateTracker {
+  private states: Map<string, MigrationState>;
+  private stateMachine: StateMachine;
+
+  constructor(private config: OriginalsConfig) {
+    this.states = new Map();
+    this.stateMachine = new StateMachine();
+  }
+
+  /**
+   * Create a new migration state
+   */
+  async createMigration(options: MigrationOptions): Promise<MigrationState> {
+    const migrationId = `mig_${uuidv4()}`;
+    const sourceLayer = this.extractLayer(options.sourceDid);
+
+    if (!sourceLayer) {
+      throw new Error(`Invalid source DID format: ${options.sourceDid}`);
+    }
+
+    const state: MigrationState = {
+      migrationId,
+      state: MigrationStateEnum.PENDING,
+      sourceDid: options.sourceDid,
+      sourceLayer,
+      targetLayer: options.targetLayer,
+      progress: 0,
+      currentOperation: 'Initializing migration',
+      startTime: Date.now()
+    };
+
+    this.states.set(migrationId, state);
+    return state;
+  }
+
+  /**
+   * Update migration state
+   */
+  async updateState(migrationId: string, updates: Partial<MigrationState>): Promise<void> {
+    const currentState = this.states.get(migrationId);
+    if (!currentState) {
+      throw new Error(`Migration ${migrationId} not found`);
+    }
+
+    // Validate state transition if state is being updated
+    if (updates.state && updates.state !== currentState.state) {
+      if (!this.stateMachine.canTransition(currentState.state, updates.state)) {
+        throw new Error(
+          `Invalid state transition from ${currentState.state} to ${updates.state}`
+        );
+      }
+    }
+
+    // Update the state
+    const updatedState = {
+      ...currentState,
+      ...updates
+    };
+
+    // Set end time if migration is completed, failed, or rolled back
+    if (
+      updatedState.state === MigrationStateEnum.COMPLETED ||
+      updatedState.state === MigrationStateEnum.FAILED ||
+      updatedState.state === MigrationStateEnum.ROLLED_BACK ||
+      updatedState.state === MigrationStateEnum.QUARANTINED
+    ) {
+      updatedState.endTime = Date.now();
+    }
+
+    this.states.set(migrationId, updatedState);
+  }
+
+  /**
+   * Get migration state
+   */
+  async getState(migrationId: string): Promise<MigrationState | null> {
+    return this.states.get(migrationId) || null;
+  }
+
+  /**
+   * Query migration states by filters
+   */
+  async queryStates(filters: Partial<MigrationState>): Promise<MigrationState[]> {
+    const results: MigrationState[] = [];
+
+    for (const state of this.states.values()) {
+      let matches = true;
+
+      for (const [key, value] of Object.entries(filters)) {
+        if (state[key as keyof MigrationState] !== value) {
+          matches = false;
+          break;
+        }
+      }
+
+      if (matches) {
+        results.push(state);
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Get all active migrations
+   */
+  async getActiveMigrations(): Promise<MigrationState[]> {
+    return this.queryStates({
+      state: MigrationStateEnum.IN_PROGRESS
+    });
+  }
+
+  /**
+   * Clean up old completed migrations
+   */
+  async cleanupOldStates(olderThanMs: number = 7 * 24 * 60 * 60 * 1000): Promise<void> {
+    const cutoffTime = Date.now() - olderThanMs;
+    const toDelete: string[] = [];
+
+    for (const [id, state] of this.states.entries()) {
+      if (
+        state.endTime &&
+        state.endTime < cutoffTime &&
+        (state.state === MigrationStateEnum.COMPLETED ||
+          state.state === MigrationStateEnum.ROLLED_BACK)
+      ) {
+        toDelete.push(id);
+      }
+    }
+
+    for (const id of toDelete) {
+      this.states.delete(id);
+    }
+  }
+
+  private extractLayer(did: string): 'peer' | 'webvh' | 'btco' | null {
+    if (did.startsWith('did:peer:')) return 'peer';
+    if (did.startsWith('did:webvh:')) return 'webvh';
+    if (did.startsWith('did:btco:')) return 'btco';
+    return null;
+  }
+}