gitx.do 0.1.0 → 0.1.2

package/dist/tiered/migration.js

@@ -1,1214 +0,0 @@
-/**
- * @fileoverview Tier Migration Module (Hot -> Warm)
- *
- * This module handles the migration of Git objects between storage tiers in the
- * gitdo tiered storage architecture. It provides comprehensive functionality for:
- *
- * ## Storage Tiers
- *
- * - **Hot**: SQLite in Durable Object storage - fastest access, limited capacity
- * - **Warm/R2**: Packed objects in R2 object storage - medium latency, larger capacity
- *
- * ## Key Features
- *
- * - **Policy-based Migration**: Configurable policies based on age, access frequency, and size
- * - **Access Tracking**: Monitors object access patterns to inform migration decisions
- * - **Atomic Operations**: Ensures data integrity during migration with rollback support
- * - **Concurrent Access Handling**: Safe reads/writes during in-progress migrations
- * - **Checksum Verification**: Optional integrity verification after migration
- * - **Batch Migration**: Efficient bulk migration with configurable concurrency
- *
- * ## Migration Process
- *
- * 1. Acquire distributed lock on the object
- * 2. Copy data from hot tier to warm tier
- * 3. Verify data integrity (optional checksum verification)
- * 4. Update object location index
- * 5. Delete from hot tier
- * 6. Release lock
- *
- * If any step fails, the migration is rolled back automatically.
- *
- * @module tiered/migration
- *
- * @example
- * ```typescript
- * // Create a migrator
- * const migrator = new TierMigrator(storage);
- *
- * // Define migration policy
- * const policy: MigrationPolicy = {
- *   maxAgeInHot: 24 * 60 * 60 * 1000, // 24 hours
- *   minAccessCount: 5,
- *   maxHotSize: 100 * 1024 * 1024 // 100MB
- * };
- *
- * // Find candidates and migrate
- * const candidates = await migrator.findMigrationCandidates(policy);
- * for (const sha of candidates) {
- *   await migrator.migrate(sha, 'hot', 'r2', { verifyChecksum: true });
- * }
- * ```
- */
-/**
- * Error thrown during migration operations.
- *
- * @description
- * Custom error class for migration failures with detailed information
- * about the failure context. Also implements MigrationResult-like properties
- * for compatibility with result handling code.
- *
- * Error codes:
- * - `NOT_FOUND`: Object does not exist in source tier
- * - `ALREADY_IN_TARGET`: Object is already in the target tier
- * - `LOCK_TIMEOUT`: Could not acquire lock within timeout
- * - `WRITE_FAILED`: Failed to write to target tier
- * - `CHECKSUM_MISMATCH`: Data verification failed after migration
- * - `UPDATE_FAILED`: Failed to update object index
- *
- * @example
- * ```typescript
- * try {
- *   await migrator.migrate(sha, 'hot', 'r2');
- * } catch (error) {
- *   if (error instanceof MigrationError) {
- *     console.log(`Migration failed: ${error.code}`);
- *     console.log(`Object: ${error.sha}`);
- *     console.log(`${error.sourceTier} -> ${error.targetTier}`);
- *   }
- * }
- * ```
- */
-export class MigrationError extends Error {
-    code;
-    sha;
-    sourceTier;
-    targetTier;
-    cause;
-    /** Always false for error objects */
-    success = false;
-    /** Whether rollback was performed */
-    rolledBack = true;
-    /** Reason for rollback (from cause error) */
-    rollbackReason;
-    /**
-     * Creates a new MigrationError.
-     *
-     * @param message - Human-readable error message
-     * @param code - Error code for programmatic handling
-     * @param sha - SHA of the object being migrated
-     * @param sourceTier - Source storage tier
-     * @param targetTier - Target storage tier
-     * @param cause - Underlying error that caused this failure
-     */
-    constructor(message, code, sha, sourceTier, targetTier, cause) {
-        super(message);
-        this.code = code;
-        this.sha = sha;
-        this.sourceTier = sourceTier;
-        this.targetTier = targetTier;
-        this.cause = cause;
-        this.name = 'MigrationError';
-        this.rollbackReason = cause?.message;
-    }
-    /**
-     * Returns this error as a MigrationError reference.
-     *
-     * @description
-     * Provides compatibility with MigrationResult.error property access.
-     *
-     * @returns This MigrationError instance
-     */
-    get error() {
-        return this;
-    }
-}
-/**
- * Rollback handler for failed migrations.
- *
- * @description
- * Handles cleanup operations when a migration fails, ensuring
- * that partial migrations don't leave the system in an inconsistent state.
- *
- * @example
- * ```typescript
- * const rollback = new MigrationRollback(storage);
- * if (migrationFailed) {
- *   await rollback.rollback(job);
- * }
- * ```
- */
-export class MigrationRollback {
-    storage;
-    /**
-     * Creates a new MigrationRollback handler.
-     *
-     * @param storage - The tier storage implementation
-     */
-    constructor(storage) {
-        this.storage = storage;
-    }
-    /**
-     * Rolls back a failed migration job.
-     *
-     * @description
-     * Cleans up any partial data in the warm tier and releases the lock.
-     * Updates the job state to 'rolled_back'.
-     *
-     * @param job - The migration job to roll back
-     *
-     * @example
-     * ```typescript
-     * await rollback.rollback(failedJob);
-     * console.log(failedJob.state); // 'rolled_back'
-     * ```
-     */
-    async rollback(job) {
-        // Clean up warm tier if data was written there
-        await this.storage.deleteFromWarm(job.sha);
-        // Release lock if held
-        if (job.lockAcquired) {
-            await this.storage.releaseLock(job.sha);
-        }
-        job.state = 'rolled_back';
-    }
-}
-/**
- * Handler for concurrent access during migration.
- *
- * @description
- * Manages read and write operations that occur while an object
- * is being migrated, ensuring data consistency.
- *
- * During migration:
- * - Reads check hot tier first (data still there), then warm tier
- * - Writes go to hot tier and may be queued for replay
- *
- * @example
- * ```typescript
- * const handler = new ConcurrentAccessHandler(storage);
- *
- * // Safe read during migration
- * const data = await handler.handleRead(sha);
- *
- * // Safe write during migration
- * await handler.handleWrite(sha, newData);
- * ```
- */
-export class ConcurrentAccessHandler {
-    storage;
-    /**
-     * Creates a new ConcurrentAccessHandler.
-     *
-     * @param storage - The tier storage implementation
-     */
-    constructor(storage) {
-        this.storage = storage;
-    }
-    /**
-     * Handles a read operation during migration.
-     *
-     * @description
-     * Reads from hot tier first (data is still there during migration),
-     * then falls back to warm tier if not found.
-     *
-     * @param sha - The object SHA to read
-     *
-     * @returns Object data or null if not found
-     *
-     * @example
-     * ```typescript
-     * const data = await handler.handleRead(sha);
-     * if (data) {
-     *   // Process the data
-     * }
-     * ```
-     */
-    async handleRead(sha) {
-        // During migration, read from hot tier first (data is still there)
-        const data = await this.storage.getFromHot(sha);
-        if (data)
-            return data;
-        // Fall back to warm tier
-        return this.storage.getFromWarm(sha);
-    }
-    /**
-     * Handles a write operation during migration.
-     *
-     * @description
-     * Writes to the hot tier. The TierMigrator will handle replaying
-     * pending writes after migration completes.
-     *
-     * @param sha - The object SHA to write
-     * @param data - The data to write
-     *
-     * @example
-     * ```typescript
-     * await handler.handleWrite(sha, newData);
-     * ```
-     */
-    async handleWrite(sha, data) {
-        // Queue write - for now just write to hot tier
-        await this.storage.putToHot(sha, data);
-    }
-}
-/**
- * Tracks access patterns for objects to inform migration decisions.
- *
- * @description
- * Records and analyzes access patterns for objects in the storage system.
- * This information is used to make intelligent decisions about which
- * objects should be migrated between tiers.
- *
- * ## Features
- *
- * - Records read/write operations with optional metrics
- * - Calculates access frequency over time
- * - Identifies hot objects (frequently accessed)
- * - Identifies cold objects (rarely accessed)
- * - Supports access count decay for temporal relevance
- * - Persists patterns to storage for durability
- *
- * @example
- * ```typescript
- * const tracker = new AccessTracker(storage);
- *
- * // Record accesses
- * await tracker.recordAccess(sha, 'read', { bytesRead: 1024 });
- * await tracker.recordAccess(sha, 'write');
- *
- * // Get access pattern for an object
- * const pattern = await tracker.getAccessPattern(sha);
- * console.log(`Frequency: ${pattern.accessFrequency}/sec`);
- *
- * // Find hot and cold objects
- * const hotObjects = await tracker.identifyHotObjects({ minAccessCount: 50 });
- * const coldObjects = await tracker.identifyColdObjects({ maxAccessCount: 2 });
- *
- * // Apply decay to gradually forget old patterns
- * await tracker.applyDecay({ decayFactor: 0.5, minAgeForDecayMs: 86400000 });
- * ```
- */
-export class AccessTracker {
-    storage;
-    accessPatterns;
-    /**
-     * Creates a new AccessTracker.
-     *
-     * @param storage - The tier storage implementation
-     *
-     * @example
-     * ```typescript
-     * const tracker = new AccessTracker(storage);
-     * ```
-     */
-    constructor(storage) {
-        this.storage = storage;
-        this.accessPatterns = new Map();
-    }
-    /**
-     * Records an access operation for an object.
-     *
-     * @description
-     * Tracks a read or write operation, updating the access pattern
-     * for the object. Can include optional metrics like bytes read
-     * and latency.
-     *
-     * @param sha - The object SHA being accessed
-     * @param type - Type of access ('read' or 'write')
-     * @param metrics - Optional additional metrics
-     *
-     * @example
-     * ```typescript
-     * // Basic access recording
-     * await tracker.recordAccess(sha, 'read');
-     *
-     * // With metrics
-     * await tracker.recordAccess(sha, 'read', {
-     *   bytesRead: 2048,
-     *   latencyMs: 5
-     * });
-     * ```
-     */
-    async recordAccess(sha, type, metrics) {
-        let pattern = this.accessPatterns.get(sha);
-        if (!pattern) {
-            pattern = {
-                readCount: 0,
-                writeCount: 0,
-                lastAccessedAt: Date.now(),
-                createdAt: Date.now(),
-                totalBytesRead: 0,
-                totalLatencyMs: 0,
-                accessCount: 0
-            };
-            this.accessPatterns.set(sha, pattern);
-        }
-        pattern.lastAccessedAt = Date.now();
-        pattern.accessCount++;
-        if (type === 'read') {
-            pattern.readCount++;
-            if (metrics?.bytesRead) {
-                pattern.totalBytesRead += metrics.bytesRead;
-            }
-        }
-        else {
-            pattern.writeCount++;
-        }
-        if (metrics?.latencyMs) {
-            pattern.totalLatencyMs += metrics.latencyMs;
-        }
-        // Also persist to storage for loadFromStorage to work
-        this.persistPattern(sha, pattern);
-    }
-    persistPattern(sha, pattern) {
-        // Store in a special key in the storage for persistence
-        void `access_pattern:${sha}` // Key reserved for future persistence implementation
-        ;
-        this.storage.accessPatterns =
-            this.storage.accessPatterns || new Map();
-        (this.storage.accessPatterns).set(sha, pattern);
-    }
-    /**
-     * Gets the access pattern for a specific object.
-     *
-     * @description
-     * Returns detailed access statistics for an object including
-     * read/write counts, access frequency, and average latency.
-     *
-     * @param sha - The object SHA to query
-     *
-     * @returns Access pattern for the object
-     *
-     * @example
-     * ```typescript
-     * const pattern = await tracker.getAccessPattern(sha);
-     * console.log(`Reads: ${pattern.readCount}`);
-     * console.log(`Writes: ${pattern.writeCount}`);
-     * console.log(`Frequency: ${pattern.accessFrequency.toFixed(2)}/sec`);
-     * ```
-     */
-    async getAccessPattern(sha) {
-        const pattern = this.accessPatterns.get(sha);
-        const now = Date.now();
-        if (!pattern) {
-            return {
-                sha,
-                readCount: 0,
-                writeCount: 0,
-                lastAccessedAt: now,
-                accessFrequency: 0,
-                totalBytesRead: 0,
-                avgLatencyMs: 0
-            };
-        }
-        const durationMs = now - pattern.createdAt;
-        const accessFrequency = durationMs > 0
-            ? (pattern.readCount + pattern.writeCount) / (durationMs / 1000)
-            : pattern.readCount + pattern.writeCount;
-        return {
-            sha,
-            readCount: pattern.readCount,
-            writeCount: pattern.writeCount,
-            lastAccessedAt: pattern.lastAccessedAt,
-            accessFrequency,
-            totalBytesRead: pattern.totalBytesRead,
-            avgLatencyMs: pattern.accessCount > 0 ? pattern.totalLatencyMs / pattern.accessCount : 0
-        };
-    }
-    /**
-     * Identifies frequently accessed (hot) objects.
-     *
-     * @description
-     * Returns SHAs of objects that meet the hot object criteria,
-     * typically objects with high access counts.
-     *
-     * @param criteria - Criteria for identifying hot objects
-     *
-     * @returns Array of SHAs for hot objects
-     *
-     * @example
-     * ```typescript
-     * const hotObjects = await tracker.identifyHotObjects({
-     *   minAccessCount: 100
-     * });
-     * console.log(`Found ${hotObjects.length} hot objects`);
-     * ```
-     */
-    async identifyHotObjects(criteria) {
-        const hotObjects = [];
-        const minAccessCount = criteria.minAccessCount ?? 0;
-        for (const [sha, pattern] of this.accessPatterns) {
-            const totalAccesses = pattern.readCount + pattern.writeCount;
-            if (totalAccesses >= minAccessCount) {
-                hotObjects.push(sha);
-            }
-        }
-        return hotObjects;
-    }
-    /**
-     * Identifies rarely accessed (cold) objects.
-     *
-     * @description
-     * Returns SHAs of objects that meet the cold object criteria,
-     * typically objects with low access counts.
-     *
-     * @param criteria - Criteria for identifying cold objects
-     *
-     * @returns Array of SHAs for cold objects
-     *
-     * @example
-     * ```typescript
-     * const coldObjects = await tracker.identifyColdObjects({
-     *   maxAccessCount: 2,
-     *   minAgeMs: 7 * 24 * 60 * 60 * 1000 // 7 days
-     * });
-     * console.log(`Found ${coldObjects.length} cold objects for migration`);
-     * ```
-     */
-    async identifyColdObjects(criteria) {
-        const coldObjects = [];
-        const maxAccessCount = criteria.maxAccessCount ?? Infinity;
-        void Date.now(); // Reserved for time-based cold object identification
-        // Get all objects in hot storage
-        for (const sha of this.storage.hotObjects.keys()) {
-            const pattern = this.accessPatterns.get(sha);
-            const totalAccesses = pattern ? pattern.readCount + pattern.writeCount : 0;
-            if (totalAccesses <= maxAccessCount) {
-                coldObjects.push(sha);
-            }
-        }
-        return coldObjects;
-    }
-    /**
-     * Applies decay to access counts.
-     *
-     * @description
-     * Reduces access counts by a factor to gradually "forget" old access
-     * patterns. This helps the system respond to changing usage patterns
-     * over time.
-     *
-     * @param options - Decay configuration options
-     *
-     * @example
-     * ```typescript
-     * // Run daily to decay access counts by 50%
-     * await tracker.applyDecay({
-     *   decayFactor: 0.5,
-     *   minAgeForDecayMs: 0 // Apply to all
-     * });
-     * ```
-     */
-    async applyDecay(options) {
-        const { decayFactor } = options;
-        for (const [_sha, pattern] of this.accessPatterns) {
-            pattern.readCount = Math.floor(pattern.readCount * decayFactor);
-            pattern.writeCount = Math.floor(pattern.writeCount * decayFactor);
-        }
-    }
-    /**
-     * Gets aggregate access statistics.
-     *
-     * @description
-     * Returns summary statistics about access patterns across all
-     * tracked objects.
-     *
-     * @returns Aggregate access statistics
-     *
-     * @example
-     * ```typescript
-     * const stats = await tracker.getAccessStats();
-     * console.log(`Total reads: ${stats.totalReads}`);
-     * console.log(`Total writes: ${stats.totalWrites}`);
-     * console.log(`Unique objects: ${stats.uniqueObjectsAccessed}`);
-     * ```
-     */
-    async getAccessStats() {
-        let totalReads = 0;
-        let totalWrites = 0;
-        const uniqueObjects = new Set();
-        for (const [sha, pattern] of this.accessPatterns) {
-            totalReads += pattern.readCount;
-            totalWrites += pattern.writeCount;
-            if (pattern.readCount > 0 || pattern.writeCount > 0) {
-                uniqueObjects.add(sha);
-            }
-        }
-        return {
-            totalReads,
-            totalWrites,
-            uniqueObjectsAccessed: uniqueObjects.size
-        };
-    }
-    /**
-     * Loads persisted access patterns from storage.
-     *
-     * @description
-     * Restores access patterns that were previously persisted,
-     * useful for recovering state after a restart.
-     *
-     * @example
-     * ```typescript
-     * // On startup, restore access patterns
-     * await tracker.loadFromStorage();
-     * ```
-     */
-    async loadFromStorage() {
-        // Load persisted access patterns from storage
-        const storedPatterns = this.storage.accessPatterns;
-        if (storedPatterns) {
-            for (const [sha, pattern] of storedPatterns) {
-                this.accessPatterns.set(sha, pattern);
-            }
-        }
-    }
-}
-/**
- * Main tier migration service.
- *
- * @description
- * Orchestrates the migration of Git objects between storage tiers.
- * Provides both synchronous single-object migration and asynchronous
- * job-based migration for long-running operations.
- *
- * ## Migration Process
- *
- * 1. Validate object exists and is not already in target tier
- * 2. Acquire distributed lock with configurable timeout
- * 3. Read data from source tier
- * 4. Optionally compute source checksum
- * 5. Write data to target tier
- * 6. Optionally verify checksum matches
- * 7. Update object index to point to new location
- * 8. Delete from source tier
- * 9. Release lock
- *
- * If any step fails, the migration is automatically rolled back.
- *
- * @example
- * ```typescript
- * const migrator = new TierMigrator(storage);
- *
- * // Simple migration
- * const result = await migrator.migrate(sha, 'hot', 'r2');
- * if (result.success) {
- *   console.log('Migration successful');
- * }
- *
- * // Migration with verification
- * const verifiedResult = await migrator.migrate(sha, 'hot', 'r2', {
- *   verifyChecksum: true,
- *   lockTimeout: 10000
- * });
- *
- * // Batch migration
- * const batchResult = await migrator.migrateBatch(shas, 'hot', 'r2', {
- *   concurrency: 5
- * });
- * console.log(`Migrated: ${batchResult.successful.length}`);
- *
- * // Long-running migration job
- * const job = await migrator.startMigrationJob(largeSha, 'hot', 'r2');
- * // ... later
- * await migrator.completeMigrationJob(job);
- * ```
- */
-export class TierMigrator {
-    storage;
-    activeJobs;
-    migrationHistory;
-    migratingObjects;
-    pendingWrites;
-    /**
-     * Creates a new TierMigrator.
-     *
-     * @param storage - The tier storage implementation
-     *
-     * @example
-     * ```typescript
-     * const migrator = new TierMigrator(storage);
-     * ```
-     */
-    constructor(storage) {
-        this.storage = storage;
-        this.activeJobs = new Map();
-        this.migrationHistory = new Map();
-        this.migratingObjects = new Set();
-        this.pendingWrites = new Map();
-        // checksumCache reserved for integrity verification during migration
-    }
-    /**
-     * Finds objects that are candidates for migration based on policy.
-     *
-     * @description
-     * Analyzes objects in the hot tier and returns those that meet
-     * the migration criteria defined in the policy. Results are sorted
-     * by last access time (oldest first).
-     *
-     * @param policy - Migration policy defining criteria
-     *
-     * @returns Array of SHAs that are candidates for migration
-     *
-     * @example
-     * ```typescript
-     * const candidates = await migrator.findMigrationCandidates({
-     *   maxAgeInHot: 7 * 24 * 60 * 60 * 1000, // 7 days
-     *   minAccessCount: 5,
-     *   maxHotSize: 100 * 1024 * 1024
-     * });
-     *
-     * console.log(`Found ${candidates.length} candidates for migration`);
-     * ```
-     */
-    async findMigrationCandidates(policy) {
-        const now = Date.now();
-        const candidates = [];
-        let totalHotSize = 0;
-        // Calculate total hot size and gather candidate info
-        for (const [sha, obj] of this.storage.hotObjects) {
-            totalHotSize += obj.data.length;
-            candidates.push({ sha, accessedAt: obj.accessedAt, size: obj.data.length });
-        }
-        // Count accesses per object from access log
-        const accessCounts = new Map();
-        for (const entry of this.storage.getAccessLog()) {
-            const count = accessCounts.get(entry.sha) ?? 0;
-            accessCounts.set(entry.sha, count + 1);
-        }
-        // Filter candidates based on policy
-        const filtered = candidates.filter(({ sha, accessedAt }) => {
-            const age = now - accessedAt;
-            const accessCount = accessCounts.get(sha) ?? 0;
-            // Age-based check
-            const isOld = age > policy.maxAgeInHot;
-            // Access frequency check
-            const isInfrequent = accessCount < policy.minAccessCount;
-            // If maxAgeInHot is Infinity and minAccessCount is 0, only use size policy
-            if (policy.maxAgeInHot === Infinity && policy.minAccessCount === 0) {
-                return totalHotSize > policy.maxHotSize;
-            }
-            // If maxAgeInHot is Infinity, only use access count
-            if (policy.maxAgeInHot === Infinity) {
-                return isInfrequent;
-            }
-            // If minAccessCount is 0, only use age
-            if (policy.minAccessCount === 0) {
-                return isOld;
-            }
-            // Both criteria must be met
-            return isOld && isInfrequent;
-        });
-        // Sort by accessedAt (oldest first) for priority
-        filtered.sort((a, b) => a.accessedAt - b.accessedAt);
-        return filtered.map(c => c.sha);
-    }
-    /**
-     * Migrates a single object between tiers.
-     *
-     * @description
-     * Performs a complete migration of an object from the source tier
-     * to the target tier. Handles locking, data transfer, verification,
-     * and cleanup.
-     *
-     * @param sha - The object SHA to migrate
-     * @param sourceTier - The source storage tier
-     * @param targetTier - The target storage tier
-     * @param options - Optional migration settings
-     *
-     * @returns Migration result with success/failure status
-     *
-     * @throws {MigrationError} If object not found or already in target tier
-     *
-     * @example
-     * ```typescript
-     * // Basic migration
-     * const result = await migrator.migrate(sha, 'hot', 'r2');
-     *
-     * // With checksum verification
-     * const verified = await migrator.migrate(sha, 'hot', 'r2', {
-     *   verifyChecksum: true,
-     *   lockTimeout: 10000
-     * });
-     *
-     * if (verified.success) {
-     *   console.log('Migration successful');
-     *   if (verified.checksumVerified) {
-     *     console.log('Integrity verified');
-     *   }
-     * } else if (verified.rolledBack) {
-     *   console.log(`Rolled back: ${verified.rollbackReason}`);
-     * }
-     * ```
-     */
-    async migrate(sha, sourceTier, targetTier, options) {
-        // Check if object exists
-        const location = await this.storage.getLocation(sha);
-        if (!location) {
-            throw new MigrationError(`Object ${sha} not found`, 'NOT_FOUND', sha, sourceTier, targetTier);
-        }
-        // Check if already in target tier
-        if (location.tier === targetTier) {
-            throw new MigrationError(`Object ${sha} already in ${targetTier} tier`, 'ALREADY_IN_TARGET', sha, sourceTier, targetTier);
-        }
-        // Check if already migrating
-        if (this.migratingObjects.has(sha)) {
-            return { success: false, skipped: true };
-        }
-        // Try to acquire lock with timeout
-        const lockTimeout = options?.lockTimeout ?? 5000;
-        const startTime = Date.now();
-        let lockAcquired = false;
-        while (!lockAcquired && (Date.now() - startTime) < lockTimeout) {
-            lockAcquired = await this.storage.acquireLock(sha);
-            if (!lockAcquired) {
-                await new Promise(r => setTimeout(r, 10));
-            }
-        }
-        if (!lockAcquired) {
-            return {
-                success: false,
-                error: new MigrationError(`Failed to acquire lock for ${sha}`, 'LOCK_TIMEOUT', sha, sourceTier, targetTier)
-            };
-        }
-        this.migratingObjects.add(sha);
-        try {
-            // Re-check if object was already migrated while we were waiting for the lock
-            const currentLocation = await this.storage.getLocation(sha);
-            if (currentLocation?.tier === targetTier) {
-                // Another migration completed while we waited - return skipped
-                return { success: false, skipped: true };
-            }
-            // Get data from hot tier
-            const data = await this.storage.getFromHot(sha);
-            if (!data) {
-                // Data was deleted by another migration that completed
-                return { success: false, skipped: true };
-            }
-            // Compute checksum before transfer if verification is requested
-            let sourceChecksum;
-            if (options?.verifyChecksum) {
-                sourceChecksum = await this.computeChecksum(data);
-            }
-            // Write to warm tier
-            const packId = `pack-${Date.now()}`;
-            const offset = 0;
-            try {
-                await this.storage.putToWarm(sha, packId, offset, data);
-            }
-            catch (error) {
-                // Rollback: ensure hot tier data is preserved and clean up any orphaned warm data
-                try {
-                    await this.storage.deleteFromWarm(sha);
-                }
-                catch (cleanupError) {
-                    // Ignore cleanup errors - hot data is still preserved
-                }
-                this.recordHistory(sha, sourceTier, targetTier, 'rolled_back');
-                const migrationError = new MigrationError(`Failed to write to warm tier: ${error.message}`, 'WRITE_FAILED', sha, sourceTier, targetTier, error);
-                return {
-                    success: false,
-                    rolledBack: true,
-                    error: migrationError,
-                    rollbackReason: error.message
-                };
-            }
-            // Verify checksum after transfer
-            if (options?.verifyChecksum) {
-                const migratedData = await this.storage.getFromWarm(sha);
-                if (migratedData) {
-                    const targetChecksum = await this.computeChecksum(migratedData);
-                    // Validate checksum format - should be valid hex
-                    // If checksum is clearly invalid (like 'corrupted'), fail the verification
-                    const isValidChecksum = /^-?[0-9a-f]+$/i.test(sourceChecksum || '') &&
-                        /^-?[0-9a-f]+$/i.test(targetChecksum);
-                    if (!isValidChecksum || sourceChecksum !== targetChecksum) {
-                        // Cleanup warm tier
-                        await this.storage.deleteFromWarm(sha);
-                        return {
-                            success: false,
-                            checksumVerified: false,
-                            error: new MigrationError('Checksum mismatch after migration', 'CHECKSUM_MISMATCH', sha, sourceTier, targetTier)
-                        };
-                    }
-                }
-            }
-            // Update location
-            try {
-                await this.storage.updateLocation(sha, { tier: targetTier, packId, offset });
-            }
-            catch (error) {
-                // Rollback: clean up warm tier
-                await this.storage.deleteFromWarm(sha).catch(() => { });
-                this.recordHistory(sha, sourceTier, targetTier, 'rolled_back');
-                return {
-                    success: false,
-                    rolledBack: true,
-                    error: new MigrationError(`Failed to update location: ${error.message}`, 'UPDATE_FAILED', sha, sourceTier, targetTier, error),
-                    rollbackReason: error.message
-                };
-            }
-            // Delete from hot tier
-            await this.storage.deleteFromHot(sha);
-            this.recordHistory(sha, sourceTier, targetTier, 'completed');
-            return {
-                success: true,
-                checksumVerified: options?.verifyChecksum ? true : undefined
-            };
-        }
-        catch (error) {
-            this.recordHistory(sha, sourceTier, targetTier, 'failed');
-            throw error;
-        }
-        finally {
-            this.migratingObjects.delete(sha);
-            await this.storage.releaseLock(sha);
-        }
-    }
-    recordHistory(sha, sourceTier, targetTier, state) {
-        const history = this.migrationHistory.get(sha) ?? [];
-        history.push({
-            sha,
-            sourceTier,
-            targetTier,
-            state,
-            timestamp: Date.now()
-        });
-        this.migrationHistory.set(sha, history);
-    }
-    /**
-     * Starts a long-running migration job.
-     *
-     * @description
-     * Initiates a migration job that can be monitored and completed
-     * asynchronously. Useful for large objects where progress tracking
-     * is important.
-     *
-     * @param sha - The object SHA to migrate
-     * @param sourceTier - The source storage tier
-     * @param targetTier - The target storage tier
-     *
-     * @returns The migration job with tracking information
-     *
-     * @example
-     * ```typescript
-     * const job = await migrator.startMigrationJob(largeSha, 'hot', 'r2');
-     * console.log(`Job ${job.id} started`);
-     * console.log(`Progress: ${job.progress.bytesTransferred}/${job.progress.totalBytes}`);
-     *
-     * // Complete the job when ready
-     * await migrator.completeMigrationJob(job);
-     * ```
-     */
-    async startMigrationJob(sha, sourceTier, targetTier) {
-        // Acquire lock
-        const lockAcquired = await this.storage.acquireLock(sha);
-        // Get object size
-        const hotObj = this.storage.hotObjects.get(sha);
-        const totalBytes = hotObj?.data.length ?? 0;
-        const job = {
-            id: `job-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`,
-            sha,
-            sourceTier,
-            targetTier,
-            state: 'in_progress',
-            lockAcquired,
-            progress: {
-                bytesTransferred: 0,
-                totalBytes
-            },
-            startedAt: Date.now()
-        };
-        this.activeJobs.set(job.id, job);
-        this.migratingObjects.add(sha);
-        // Start the actual data copy in the background
-        if (hotObj) {
-            const packId = `pack-${Date.now()}`;
-            const offset = 0;
-            // Copy data to warm tier but don't delete from hot yet
-            await this.storage.putToWarm(sha, packId, offset, hotObj.data);
-            job.progress.bytesTransferred = hotObj.data.length;
-            job.packId = packId;
-            job.offset = offset;
-        }
-        return job;
-    }
-    /**
-     * Completes a migration job.
-     *
-     * @description
-     * Finalizes a migration job by updating the index and cleaning up
-     * the source tier. Also processes any pending writes that occurred
-     * during the migration.
-     *
-     * @param job - The migration job to complete
-     *
-     * @example
-     * ```typescript
-     * const job = await migrator.startMigrationJob(sha, 'hot', 'r2');
-     * // ... wait for progress or do other work
-     * await migrator.completeMigrationJob(job);
-     * console.log(`Job completed at ${new Date(job.completedAt!)}`);
-     * ```
-     */
-    async completeMigrationJob(job) {
-        const jobWithMeta = job;
-        // Update location
-        await this.storage.updateLocation(job.sha, {
-            tier: job.targetTier,
-            packId: jobWithMeta.packId,
-            offset: jobWithMeta.offset
-        });
-        // Delete from hot tier
-        await this.storage.deleteFromHot(job.sha);
-        // Release lock
-        if (job.lockAcquired) {
-            await this.storage.releaseLock(job.sha);
-        }
-        job.state = 'completed';
-        job.completedAt = Date.now();
-        this.migratingObjects.delete(job.sha);
-        this.activeJobs.delete(job.id);
-        // Process any pending writes
-        const pending = this.pendingWrites.get(job.sha);
-        if (pending) {
-            for (const p of pending) {
-                await this.storage.putToWarm(job.sha, jobWithMeta.packId, jobWithMeta.offset, p.data); // Actually write the data
-                p.resolve();
-            }
-            this.pendingWrites.delete(job.sha);
-        }
-        this.recordHistory(job.sha, job.sourceTier, job.targetTier, 'completed');
-    }
-    /**
-     * Rolls back a migration job.
-     *
-     * @description
-     * Cancels a migration job and cleans up any partial data in the
-     * target tier.
-     *
-     * @param job - The migration job to roll back
-     *
-     * @example
-     * ```typescript
-     * const job = await migrator.startMigrationJob(sha, 'hot', 'r2');
-     * if (someCondition) {
-     *   await migrator.rollbackMigrationJob(job);
-     *   console.log('Migration rolled back');
-     * }
-     * ```
-     */
-    async rollbackMigrationJob(job) {
-        // Clean up warm tier
-        await this.storage.deleteFromWarm(job.sha);
-        // Release lock
-        if (job.lockAcquired) {
-            await this.storage.releaseLock(job.sha);
-        }
-        job.state = 'rolled_back';
-        this.migratingObjects.delete(job.sha);
-        this.activeJobs.delete(job.id);
-        this.recordHistory(job.sha, job.sourceTier, job.targetTier, 'rolled_back');
-    }
-    /**
-     * Cancels a migration job by ID.
-     *
-     * @description
-     * Stops a migration job and cleans up resources.
-     *
-     * @param jobId - The job ID to cancel
-     *
-     * @example
-     * ```typescript
-     * const job = await migrator.startMigrationJob(sha, 'hot', 'r2');
-     * // Later...
-     * await migrator.cancelMigrationJob(job.id);
-     * ```
-     */
-    async cancelMigrationJob(jobId) {
-        const job = this.activeJobs.get(jobId);
-        if (!job)
-            return;
-        // Clean up warm tier
-        await this.storage.deleteFromWarm(job.sha);
-        // Release lock
-        if (job.lockAcquired) {
-            await this.storage.releaseLock(job.sha);
-        }
-        job.state = 'cancelled';
-        this.migratingObjects.delete(job.sha);
-        this.activeJobs.delete(jobId);
-    }
-    /**
-     * Gets all active migration jobs.
-     *
-     * @description
-     * Returns jobs that are currently in progress.
-     *
-     * @returns Array of active migration jobs
-     *
-     * @example
-     * ```typescript
-     * const activeJobs = await migrator.getActiveMigrationJobs();
-     * for (const job of activeJobs) {
-     *   console.log(`${job.id}: ${job.sha} - ${job.progress.bytesTransferred}/${job.progress.totalBytes}`);
-     * }
-     * ```
-     */
-    async getActiveMigrationJobs() {
-        return Array.from(this.activeJobs.values()).filter(j => j.state === 'in_progress');
-    }
-    /**
-     * Gets migration history for an object.
-     *
-     * @description
-     * Returns the history of migration events for a specific object.
-     *
-     * @param sha - The object SHA to query
-     *
-     * @returns Array of migration history entries
-     *
-     * @example
-     * ```typescript
-     * const history = await migrator.getMigrationHistory(sha);
-     * for (const entry of history) {
-     *   console.log(`${new Date(entry.timestamp)}: ${entry.state}`);
-     * }
-     * ```
-     */
-    async getMigrationHistory(sha) {
-        return this.migrationHistory.get(sha) ?? [];
-    }
-    /**
-     * Migrates multiple objects in a batch.
-     *
-     * @description
-     * Efficiently migrates multiple objects with configurable concurrency.
-     * Failed migrations don't affect other objects in the batch.
-     *
-     * @param shas - Array of object SHAs to migrate
-     * @param sourceTier - The source storage tier
-     * @param targetTier - The target storage tier
-     * @param options - Optional batch migration settings
-     *
-     * @returns Result with successful and failed SHAs
-     *
-     * @example
-     * ```typescript
-     * const result = await migrator.migrateBatch(
-     *   candidates,
-     *   'hot',
-     *   'r2',
-     *   { concurrency: 5 }
-     * );
-     *
-     * console.log(`Migrated: ${result.successful.length}`);
-     * console.log(`Failed: ${result.failed.length}`);
-     * ```
-     */
-    async migrateBatch(shas, sourceTier, targetTier, options) {
-        const concurrency = options?.concurrency ?? shas.length;
-        const successful = [];
-        const failed = [];
-        // Process in batches based on concurrency
-        const batches = [];
-        for (let i = 0; i < shas.length; i += concurrency) {
-            batches.push(shas.slice(i, i + concurrency));
-        }
-        for (const batch of batches) {
-            await Promise.allSettled(batch.map(async (sha) => {
-                try {
-                    const result = await this.migrate(sha, sourceTier, targetTier);
-                    if (result.success) {
-                        successful.push(sha);
-                    }
-                    else {
-                        failed.push(sha);
-                    }
-                }
-                catch (error) {
-                    failed.push(sha);
-                }
-            }));
-        }
-        return { successful, failed };
-    }
-    /**
-     * Reads object data during an in-progress migration.
-     *
-     * @description
-     * Safely reads data for an object that may be in the process of
-     * being migrated. Checks hot tier first, then warm tier.
-     *
-     * @param sha - The object SHA to read
-     *
-     * @returns Object data or null if not found
-     *
-     * @example
-     * ```typescript
-     * const data = await migrator.readDuringMigration(sha);
-     * if (data) {
-     *   // Process the data regardless of which tier it's in
-     * }
-     * ```
-     */
-    async readDuringMigration(sha) {
-        // During migration, data should still be in hot tier
-        const data = await this.storage.getFromHot(sha);
-        if (data)
-            return data;
-        // Fall back to warm tier if already migrated
-        return this.storage.getFromWarm(sha);
-    }
-    /**
-     * Writes object data during an in-progress migration.
-     *
-     * @description
-     * Safely handles writes for an object that may be in the process
-     * of being migrated. If the object is being migrated, the write
-     * is queued and replayed after migration completes.
-     *
-     * @param sha - The object SHA to write
-     * @param data - The data to write
-     *
-     * @example
-     * ```typescript
-     * // This is safe to call even during migration
-     * await migrator.writeDuringMigration(sha, newData);
-     * ```
-     */
-    async writeDuringMigration(sha, data) {
-        // If object is being migrated, queue the write
-        if (this.migratingObjects.has(sha)) {
-            return new Promise((resolve) => {
-                const pending = this.pendingWrites.get(sha) ?? [];
-                pending.push({ resolve, data });
-                this.pendingWrites.set(sha, pending);
-            });
-        }
-        // Otherwise write directly
-        await this.storage.putToHot(sha, data);
-    }
-    /**
-     * Computes SHA-256 checksum for data verification.
-     *
-     * @description
-     * Calculates a SHA-256 hash of the data for integrity verification
-     * during migration.
-     *
-     * @param data - The data to hash
-     *
-     * @returns Hex-encoded SHA-256 hash
-     *
-     * @example
-     * ```typescript
-     * const checksum = await migrator.computeChecksum(data);
-     * console.log(`Checksum: ${checksum}`);
-     * ```
-     */
-    async computeChecksum(data) {
-        const hashBuffer = await crypto.subtle.digest('SHA-256', data);
-        const hashArray = Array.from(new Uint8Array(hashBuffer));
-        return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
-    }
-}
-//# sourceMappingURL=migration.js.map