gitx.do 0.0.1 → 0.0.3

package/dist/tiered/migration.d.ts

@@ -1,135 +1,443 @@
 /**
- * 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 });
+ * }
+ * ```
  */
 import { StorageTier } from '../storage/object-index';
 /**
- * Migration policy configuration
+ * Migration policy configuration.
+ *
+ * @description
+ * Defines the criteria for determining when objects should be migrated
+ * from the hot tier to the warm tier. Objects meeting ANY of these criteria
+ * may be migrated.
+ *
+ * @example
+ * ```typescript
+ * const policy: MigrationPolicy = {
+ *   maxAgeInHot: 7 * 24 * 60 * 60 * 1000, // 7 days
+ *   minAccessCount: 10, // Stay hot if accessed 10+ times
+ *   maxHotSize: 500 * 1024 * 1024 // Trigger migration if hot > 500MB
+ * };
+ * ```
  */
 export interface MigrationPolicy {
-    /** Maximum age in hot tier before migration (milliseconds) */
+    /**
+     * Maximum age in hot tier before migration (milliseconds).
+     * Objects older than this may be migrated to warm tier.
+     * Use Infinity to disable age-based migration.
+     */
     maxAgeInHot: number;
-    /** Minimum access count to stay in hot tier */
+    /**
+     * Minimum access count to stay in hot tier.
+     * Objects with fewer accesses may be migrated.
+     * Use 0 to disable access-count-based migration.
+     */
     minAccessCount: number;
-    /** Maximum total size of hot tier (bytes) */
+    /**
+     * Maximum total size of hot tier (bytes).
+     * When exceeded, oldest/coldest objects are migrated.
+     */
     maxHotSize: number;
 }
 /**
- * Migration job state
+ * Migration job state enumeration.
+ *
+ * @description
+ * Represents the lifecycle states of a migration job:
+ * - `pending`: Job created but not started
+ * - `in_progress`: Migration actively running
+ * - `completed`: Migration finished successfully
+ * - `failed`: Migration failed (may be retried)
+ * - `cancelled`: Job was cancelled by user
+ * - `rolled_back`: Migration failed and changes were reverted
  */
 export type MigrationState = 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled' | 'rolled_back';
 /**
- * Migration job progress
+ * Migration job progress tracking.
+ *
+ * @description
+ * Tracks the progress of data transfer during a migration job.
+ * Useful for long-running migrations of large objects.
+ *
+ * @example
+ * ```typescript
+ * const job = await migrator.startMigrationJob(sha, 'hot', 'r2');
+ * console.log(`Progress: ${job.progress.bytesTransferred}/${job.progress.totalBytes}`);
+ * ```
  */
 export interface MigrationProgress {
+    /** Number of bytes transferred so far */
     bytesTransferred: number;
+    /** Total number of bytes to transfer */
     totalBytes: number;
 }
 /**
- * Migration job tracking
+ * Migration job tracking information.
+ *
+ * @description
+ * Contains all information about an active or completed migration job,
+ * including progress tracking, timing, and state.
+ *
+ * @example
+ * ```typescript
+ * const job = await migrator.startMigrationJob(sha, 'hot', 'r2');
+ * console.log(`Job ${job.id} started at ${new Date(job.startedAt)}`);
+ * console.log(`State: ${job.state}`);
+ * ```
  */
 export interface MigrationJob {
+    /** Unique identifier for the migration job */
     id: string;
+    /** SHA of the object being migrated */
     sha: string;
+    /** Source storage tier */
     sourceTier: StorageTier;
+    /** Target storage tier */
     targetTier: StorageTier;
+    /** Current state of the migration */
     state: MigrationState;
+    /** Whether a lock was successfully acquired */
     lockAcquired: boolean;
+    /** Progress tracking for the migration */
     progress: MigrationProgress;
+    /** Timestamp when the job started (ms since epoch) */
     startedAt: number;
+    /** Timestamp when the job completed (ms since epoch), if completed */
     completedAt?: number;
 }
 /**
- * Migration result
+ * Result of a migration operation.
+ *
+ * @description
+ * Contains the outcome of a single object migration, including success/failure
+ * status, verification results, and error information if applicable.
+ *
+ * @example
+ * ```typescript
+ * const result = await migrator.migrate(sha, 'hot', 'r2', { verifyChecksum: true });
+ * if (result.success) {
+ *   console.log('Migration successful');
+ *   if (result.checksumVerified) {
+ *     console.log('Data integrity verified');
+ *   }
+ * } else if (result.skipped) {
+ *   console.log('Object was already migrated');
+ * } else if (result.rolledBack) {
+ *   console.log(`Migration rolled back: ${result.rollbackReason}`);
+ * }
+ * ```
  */
 export interface MigrationResult {
+    /** Whether the migration completed successfully */
     success: boolean;
+    /** Whether the migration was skipped (e.g., already in target tier) */
     skipped?: boolean;
+    /** Whether the migration was rolled back due to an error */
     rolledBack?: boolean;
+    /** Whether checksum verification passed (if requested) */
     checksumVerified?: boolean;
+    /** Error details if migration failed */
     error?: MigrationError;
+    /** Reason for rollback if rolledBack is true */
     rollbackReason?: string;
 }
 /**
- * Batch migration result
+ * Result of a batch migration operation.
+ *
+ * @description
+ * Contains arrays of successful and failed SHA hashes after a batch migration.
+ *
+ * @example
+ * ```typescript
+ * const result = await migrator.migrateBatch(shas, 'hot', 'r2');
+ * console.log(`Migrated: ${result.successful.length}`);
+ * console.log(`Failed: ${result.failed.length}`);
+ * ```
  */
 export interface BatchMigrationResult {
+    /** SHAs of objects that were successfully migrated */
     successful: string[];
+    /** SHAs of objects that failed to migrate */
     failed: string[];
 }
 /**
- * Batch migration options
+ * Options for batch migration operations.
+ *
+ * @description
+ * Configures batch migration behavior, particularly concurrency.
+ *
+ * @example
+ * ```typescript
+ * // Migrate with limited concurrency to avoid overwhelming storage
+ * const result = await migrator.migrateBatch(shas, 'hot', 'r2', {
+ *   concurrency: 5
+ * });
+ * ```
  */
 export interface BatchMigrationOptions {
+    /**
+     * Number of concurrent migrations.
+     * @default shas.length (all at once)
+     */
     concurrency?: number;
 }
 /**
- * Migration options
+ * Options for individual migration operations.
+ *
+ * @description
+ * Configures behavior of a single migration operation.
+ *
+ * @example
+ * ```typescript
+ * const result = await migrator.migrate(sha, 'hot', 'r2', {
+ *   verifyChecksum: true,
+ *   lockTimeout: 10000
+ * });
+ * ```
  */
 export interface MigrateOptions {
+    /**
+     * Whether to verify checksums after migration.
+     * Adds overhead but ensures data integrity.
+     * @default false
+     */
     verifyChecksum?: boolean;
+    /**
+     * Timeout in milliseconds for acquiring the lock.
+     * @default 5000
+     */
     lockTimeout?: number;
 }
 /**
- * Migration history entry
+ * Migration history entry.
+ *
+ * @description
+ * Records a single migration event for an object, useful for
+ * auditing and debugging migration issues.
+ *
+ * @example
+ * ```typescript
+ * const history = await migrator.getMigrationHistory(sha);
+ * for (const entry of history) {
+ *   console.log(`${entry.timestamp}: ${entry.sourceTier} -> ${entry.targetTier}: ${entry.state}`);
+ * }
+ * ```
  */
 export interface MigrationHistoryEntry {
+    /** SHA of the migrated object */
     sha: string;
+    /** Source storage tier */
     sourceTier: StorageTier;
+    /** Target storage tier */
     targetTier: StorageTier;
+    /** Final state of the migration */
     state: MigrationState;
+    /** Timestamp of the migration event */
     timestamp: number;
 }
 /**
- * Access pattern for an object
+ * Access pattern information for an object.
+ *
+ * @description
+ * Contains detailed access statistics for an object, used to make
+ * informed migration decisions.
+ *
+ * @example
+ * ```typescript
+ * const pattern = await tracker.getAccessPattern(sha);
+ * console.log(`Reads: ${pattern.readCount}, Writes: ${pattern.writeCount}`);
+ * console.log(`Access frequency: ${pattern.accessFrequency.toFixed(2)}/sec`);
+ * ```
  */
 export interface AccessPattern {
+    /** SHA of the object */
     sha: string;
+    /** Number of read operations */
     readCount: number;
+    /** Number of write operations */
     writeCount: number;
+    /** Timestamp of last access (ms since epoch) */
     lastAccessedAt: number;
+    /** Access frequency (accesses per second) */
     accessFrequency: number;
+    /** Total bytes read from this object */
     totalBytesRead?: number;
+    /** Average latency in milliseconds for accessing this object */
     avgLatencyMs?: number;
 }
 /**
- * Access statistics
+ * Aggregate access statistics.
+ *
+ * @description
+ * Provides summary statistics about access patterns across all tracked objects.
+ *
+ * @example
+ * ```typescript
+ * const stats = await tracker.getAccessStats();
+ * console.log(`Total reads: ${stats.totalReads}`);
+ * console.log(`Unique objects: ${stats.uniqueObjectsAccessed}`);
+ * ```
  */
 export interface AccessStats {
+    /** Total number of read operations across all objects */
     totalReads: number;
+    /** Total number of write operations across all objects */
     totalWrites: number;
+    /** Number of unique objects that have been accessed */
     uniqueObjectsAccessed: number;
 }
 /**
- * Hot/cold object identification criteria
+ * Criteria for identifying hot or cold objects.
+ *
+ * @description
+ * Specifies filters for querying objects based on access patterns.
+ *
+ * @example
+ * ```typescript
+ * // Find frequently accessed objects
+ * const hotObjects = await tracker.identifyHotObjects({
+ *   minAccessCount: 100
+ * });
+ *
+ * // Find rarely accessed objects
+ * const coldObjects = await tracker.identifyColdObjects({
+ *   maxAccessCount: 2,
+ *   minAgeMs: 7 * 24 * 60 * 60 * 1000 // 7 days old
+ * });
+ * ```
  */
 export interface ObjectIdentificationCriteria {
+    /** Minimum total access count (reads + writes) */
     minAccessCount?: number;
+    /** Maximum total access count (reads + writes) */
     maxAccessCount?: number;
+    /** Minimum age in milliseconds since last access */
     minAgeMs?: number;
 }
 /**
- * Access decay options
+ * Options for applying access count decay.
+ *
+ * @description
+ * Configures how access counts are decayed over time to gradually
+ * "forget" old access patterns and respond to changing usage.
+ *
+ * @example
+ * ```typescript
+ * // Apply 50% decay to all access counts
+ * await tracker.applyDecay({
+ *   decayFactor: 0.5,
+ *   minAgeForDecayMs: 24 * 60 * 60 * 1000 // Only decay after 24 hours
+ * });
+ * ```
  */
 export interface DecayOptions {
+    /**
+     * Multiplier applied to access counts (0-1).
+     * 0.5 means counts are halved.
+     */
     decayFactor: number;
+    /**
+     * Minimum age in milliseconds before decay is applied.
+     * Prevents decay of recently accessed objects.
+     */
     minAgeForDecayMs: number;
 }
 /**
- * Custom access metrics
+ * Custom metrics for access recording.
+ *
+ * @description
+ * Additional metrics that can be recorded with each access operation.
+ *
+ * @example
+ * ```typescript
+ * await tracker.recordAccess(sha, 'read', {
+ *   bytesRead: 1024,
+ *   latencyMs: 15
+ * });
+ * ```
  */
 export interface AccessMetrics {
+    /** Number of bytes read in this operation */
     bytesRead?: number;
+    /** Latency of this operation in milliseconds */
     latencyMs?: number;
 }
 /**
- * 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 declare class MigrationError extends Error {
     readonly code: string;
@@ -137,50 +445,380 @@ export declare class MigrationError extends Error {
     readonly sourceTier: StorageTier;
     readonly targetTier: StorageTier;
     readonly cause?: Error | undefined;
+    /** Always false for error objects */
     readonly success: boolean;
+    /** Whether rollback was performed */
     readonly rolledBack: boolean;
+    /** Reason for rollback (from cause error) */
     readonly rollbackReason?: string;
+    /**
+     * 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: string, code: string, sha: string, sourceTier: StorageTier, targetTier: StorageTier, cause?: Error | undefined);
     /**
-     * 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(): MigrationError;
 }
 /**
- * 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 declare class MigrationRollback {
     private storage;
+    /**
+     * Creates a new MigrationRollback handler.
+     *
+     * @param storage - The tier storage implementation
+     */
     constructor(storage: unknown);
+    /**
+     * 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'
+     * ```
+     */
     rollback(job: MigrationJob): Promise<void>;
 }
 /**
- * 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 declare class ConcurrentAccessHandler {
     private storage;
+    /**
+     * Creates a new ConcurrentAccessHandler.
+     *
+     * @param storage - The tier storage implementation
+     */
     constructor(storage: unknown);
+    /**
+     * 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
+     * }
+     * ```
+     */
     handleRead(sha: string): Promise<Uint8Array | null>;
+    /**
+     * 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);
+     * ```
+     */
     handleWrite(sha: string, data: Uint8Array): Promise<void>;
 }
 /**
- * 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 declare class AccessTracker {
     private storage;
     private accessPatterns;
+    /**
+     * Creates a new AccessTracker.
+     *
+     * @param storage - The tier storage implementation
+     *
+     * @example
+     * ```typescript
+     * const tracker = new AccessTracker(storage);
+     * ```
+     */
     constructor(storage: unknown);
+    /**
+     * 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
+     * });
+     * ```
+     */
     recordAccess(sha: string, type: 'read' | 'write', metrics?: AccessMetrics): Promise<void>;
     private persistPattern;
+    /**
+     * 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`);
+     * ```
+     */
     getAccessPattern(sha: string): Promise<AccessPattern>;
+    /**
+     * 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`);
+     * ```
+     */
     identifyHotObjects(criteria: ObjectIdentificationCriteria): Promise<string[]>;
+    /**
+     * 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`);
+     * ```
+     */
     identifyColdObjects(criteria: ObjectIdentificationCriteria): Promise<string[]>;
+    /**
+     * 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
+     * });
+     * ```
+     */
     applyDecay(options: DecayOptions): Promise<void>;
+    /**
+     * 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}`);
+     * ```
+     */
     getAccessStats(): Promise<AccessStats>;
+    /**
+     * 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();
+     * ```
+     */
     loadFromStorage(): Promise<void>;
 }
 /**
- * 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 declare class TierMigrator {
     private storage;
@@ -188,54 +826,278 @@ export declare class TierMigrator {
     private migrationHistory;
     private migratingObjects;
     private pendingWrites;
+    /**
+     * Creates a new TierMigrator.
+     *
+     * @param storage - The tier storage implementation
+     *
+     * @example
+     * ```typescript
+     * const migrator = new TierMigrator(storage);
+     * ```
+     */
     constructor(storage: unknown);
     /**
-     * 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`);
+     * ```
      */
     findMigrationCandidates(policy: MigrationPolicy): Promise<string[]>;
     /**
-     * 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}`);
+     * }
+     * ```
      */
     migrate(sha: string, sourceTier: StorageTier, targetTier: StorageTier, options?: MigrateOptions): Promise<MigrationResult>;
     private recordHistory;
     /**
-     * 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);
+     * ```
      */
     startMigrationJob(sha: string, sourceTier: StorageTier, targetTier: StorageTier): Promise<MigrationJob>;
     /**
-     * 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!)}`);
+     * ```
      */
     completeMigrationJob(job: MigrationJob): Promise<void>;
     /**
-     * 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');
+     * }
+     * ```
      */
     rollbackMigrationJob(job: MigrationJob): Promise<void>;
     /**
-     * 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);
+     * ```
      */
     cancelMigrationJob(jobId: string): Promise<void>;
     /**
-     * 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}`);
+     * }
+     * ```
      */
     getActiveMigrationJobs(): Promise<MigrationJob[]>;
     /**
-     * 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}`);
+     * }
+     * ```
      */
     getMigrationHistory(sha: string): Promise<MigrationHistoryEntry[]>;
     /**
-     * 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}`);
+     * ```
      */
     migrateBatch(shas: string[], sourceTier: StorageTier, targetTier: StorageTier, options?: BatchMigrationOptions): Promise<BatchMigrationResult>;
     /**
-     * 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
+     * }
+     * ```
      */
     readDuringMigration(sha: string): Promise<Uint8Array | null>;
     /**
-     * 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);
+     * ```
      */
     writeDuringMigration(sha: string, data: Uint8Array): Promise<void>;
     /**
-     * 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}`);
+     * ```
      */
     computeChecksum(data: Uint8Array): Promise<string>;
 }