gitx.do 0.0.1 → 0.0.3

package/dist/tiered/migration.js

@@ -1,15 +1,83 @@
 /**
- * Tier Migration (Hot -> Warm)
+ * @fileoverview Tier Migration Module (Hot -> Warm)
  *
- * Handles migration of git objects between storage tiers:
- * - Hot: SQLite (local Durable Object storage for frequently accessed objects)
- * - Warm/R2: Packed in R2 object storage (for larger objects or archives)
+ * This module handles the migration of Git objects between storage tiers in the
+ * gitdo tiered storage architecture. It provides comprehensive functionality for:
  *
- * gitdo-jcf: GREEN phase - Tier migration implementation
+ * ## 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
- * Also implements MigrationResult-like properties for compatibility
+ * 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;
@@ -17,9 +85,22 @@ export class MigrationError extends Error {
     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;
@@ -31,20 +112,57 @@ export class MigrationError extends Error {
         this.rollbackReason = cause?.message;
     }
     /**
-     * Get this error as a MigrationResult
+     * 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
+ * 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);
@@ -56,13 +174,56 @@ export class MigrationRollback {
     }
 }
 /**
- * Handler for concurrent access during migration
+ * 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);
@@ -71,21 +232,104 @@ export class ConcurrentAccessHandler {
         // 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
+ * 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) {
@@ -125,6 +369,25 @@ export class AccessTracker {
             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();
@@ -153,6 +416,25 @@ export class AccessTracker {
             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;
@@ -164,6 +446,26 @@ export class AccessTracker {
         }
         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;
@@ -178,6 +480,25 @@ export class AccessTracker {
         }
         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) {
@@ -185,6 +506,23 @@ export class AccessTracker {
             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;
@@ -202,6 +540,19 @@ export class AccessTracker {
             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;
@@ -213,7 +564,54 @@ export class AccessTracker {
     }
 }
 /**
- * Main tier migration service
+ * 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;
@@ -221,6 +619,16 @@ export class TierMigrator {
     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();
@@ -230,7 +638,27 @@ export class TierMigrator {
         // checksumCache reserved for integrity verification during migration
     }
     /**
-     * Find objects that are candidates for migration based on policy
+     * 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();
@@ -275,7 +703,42 @@ export class TierMigrator {
         return filtered.map(c => c.sha);
     }
     /**
-     * Migrate a single object between tiers
+     * 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
@@ -413,7 +876,28 @@ export class TierMigrator {
         this.migrationHistory.set(sha, history);
     }
     /**
-     * Start a migration job (for long-running migrations)
+     * 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
@@ -449,7 +933,22 @@ export class TierMigrator {
         return job;
     }
     /**
-     * Complete a migration 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;
@@ -481,7 +980,22 @@ export class TierMigrator {
         this.recordHistory(job.sha, job.sourceTier, job.targetTier, 'completed');
     }
     /**
-     * Rollback a migration job
+     * 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
@@ -496,7 +1010,19 @@ export class TierMigrator {
         this.recordHistory(job.sha, job.sourceTier, job.targetTier, 'rolled_back');
     }
     /**
-     * Cancel a migration job
+     * 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);
@@ -513,19 +1039,71 @@ export class TierMigrator {
         this.activeJobs.delete(jobId);
     }
     /**
-     * Get active migration jobs
+     * 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');
     }
     /**
-     * Get migration history for an object
+     * 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) ?? [];
     }
     /**
-     * Migrate multiple objects in a batch
+     * 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;
@@ -555,7 +1133,23 @@ export class TierMigrator {
         return { successful, failed };
     }
     /**
-     * Read object data during an in-progress migration
+     * 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
@@ -566,7 +1160,21 @@ export class TierMigrator {
         return this.storage.getFromWarm(sha);
     }
     /**
-     * Write object data during an in-progress migration
+     * 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
@@ -581,7 +1189,21 @@ export class TierMigrator {
         await this.storage.putToHot(sha, data);
     }
     /**
-     * Compute checksum for data verification
+     * 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);