dotdo 0.0.1 → 0.1.0

package/dist/objects/lifecycle/Clone.js

@@ -0,0 +1,1499 @@
+/**
+ * Clone Lifecycle Module
+ *
+ * Handles all clone operations for Durable Objects:
+ * - Atomic clone: All-or-nothing clone operation
+ * - Staged clone: Two-phase commit with prepare/commit
+ * - Eventual clone: Background async clone with eventual consistency
+ * - Resumable clone: Checkpoint-based clone that can be resumed
+ */
+import * as schema from '../../db';
+// Storage prefixes
+const STAGING_PREFIX = 'staging:';
+const CHECKPOINT_PREFIX = 'checkpoint:';
+const TWO_PC_PREFIX = '2pc:';
+const DEFAULT_TOKEN_TIMEOUT = 5 * 60 * 1000; // 5 minutes
+const DEFAULT_COORDINATOR_TIMEOUT = 30000; // 30 seconds
+const DEFAULT_ACK_TIMEOUT = 10000; // 10 seconds
+const DEFAULT_MAX_RETRIES = 3;
+/**
+ * Clone lifecycle module implementing Strategy pattern.
+ */
+export class CloneModule {
+    ctx;
+    // In-memory state for clone operations
+    _conflictResolvers = new Map();
+    _completionCallbacks = new Map();
+    _errorCallbacks = new Map();
+    _resumableClones = new Map();
+    _cloneLocks = new Map();
+    _broadcastCallbacks = [];
+    initialize(context) {
+        this.ctx = context;
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // MAIN CLONE METHOD
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Clone current state to a new DO with configurable modes.
+     */
+    async clone(target, options, validColos) {
+        const { mode, includeHistory = false, includeState = true, shallow = false, transform, branch: targetBranch, version: targetVersion, colo, timeout = 30000, correlationId = crypto.randomUUID(), } = options;
+        // Validate mode first
+        const validModes = ['atomic', 'staged', 'eventual', 'resumable'];
+        if (!validModes.includes(mode)) {
+            throw new Error(`Invalid mode: '${mode}' is not a valid clone mode`);
+        }
+        // Handle eventual mode
+        if (mode === 'eventual') {
+            return this.initiateEventualClone(target, options);
+        }
+        // Handle staged mode (two-phase commit)
+        if (mode === 'staged') {
+            return this.prepareStagedClone(target, options);
+        }
+        // Handle resumable mode (checkpoint-based)
+        if (mode === 'resumable') {
+            return this.initiateResumableClone(target, options);
+        }
+        const startTime = Date.now();
+        // === VALIDATION ===
+        // Validate options
+        if (typeof timeout !== 'number' || timeout < 0) {
+            throw new Error('Invalid timeout: must be a non-negative number');
+        }
+        // Validate colo code if provided
+        if (colo && !validColos.has(colo)) {
+            throw new Error(`Invalid colo: '${colo}' is not a valid location code`);
+        }
+        // Validate target namespace URL format
+        try {
+            const url = new URL(target);
+            if (!['http:', 'https:'].includes(url.protocol)) {
+                throw new Error('Invalid namespace URL: must use http or https protocol');
+            }
+        }
+        catch (e) {
+            if (e.message?.includes('Invalid namespace URL')) {
+                throw e;
+            }
+            throw new Error(`Invalid namespace URL: ${target}`);
+        }
+        // Prevent cloning to same namespace
+        if (target === this.ctx.ns) {
+            throw new Error('Cannot clone to same namespace');
+        }
+        // Validate branch if specified
+        if (targetBranch) {
+            const branches = await this.ctx.db.select().from(schema.branches);
+            const branchExists = branches.some((b) => b.name === targetBranch);
+            if (!branchExists) {
+                throw new Error(`Branch not found: '${targetBranch}'`);
+            }
+        }
+        // Validate version if specified
+        if (targetVersion !== undefined) {
+            if (targetVersion < 0 || !Number.isInteger(targetVersion)) {
+                throw new Error(`Invalid version: ${targetVersion}`);
+            }
+            const branches = await this.ctx.db.select().from(schema.branches);
+            const mainBranch = branches.find((b) => b.name === 'main' || b.name === null);
+            const allThings = await this.ctx.db.select().from(schema.things);
+            const maxVersion = Math.max(allThings.length, mainBranch?.head ?? 0);
+            if (targetVersion > maxVersion) {
+                throw new Error(`Version not found: ${targetVersion}`);
+            }
+        }
+        // Get things to validate source has state
+        let things = await this.ctx.db.select().from(schema.things);
+        if (targetBranch) {
+            things = things.filter((t) => t.branch === targetBranch);
+        }
+        const nonDeletedThings = things.filter((t) => !t.deleted);
+        if (includeState && nonDeletedThings.length === 0) {
+            throw new Error('No state to clone: source is empty');
+        }
+        const relationships = await this.ctx.db.select().from(schema.relationships);
+        // Acquire exclusive lock using blockConcurrencyWhile
+        return this.ctx.ctx.blockConcurrencyWhile(async () => {
+            try {
+                await this.ctx.emitEvent('clone.started', {
+                    target,
+                    mode,
+                    correlationId,
+                    thingsCount: nonDeletedThings.length,
+                });
+                if (!this.ctx.env.DO) {
+                    throw new Error('DO namespace not configured');
+                }
+                const targetUrl = new URL(target);
+                const doId = this.ctx.env.DO.idFromName(target);
+                const stub = this.ctx.env.DO.get(doId);
+                // Health check
+                try {
+                    const healthResponse = await Promise.race([
+                        stub.fetch(new Request(`${targetUrl.origin}/health`)),
+                        new Promise((_, reject) => setTimeout(() => reject(new Error('Health check timeout')), Math.min(timeout, 5000))),
+                    ]);
+                    if (!healthResponse.ok && healthResponse.status !== 404) {
+                        if (healthResponse.status === 409) {
+                            throw new Error('Target already exists: conflict detected');
+                        }
+                        throw new Error(`Target health check failed: ${healthResponse.status}`);
+                    }
+                }
+                catch (e) {
+                    const errorMessage = e.message || String(e);
+                    if (errorMessage.includes('Connection refused') ||
+                        errorMessage.includes('unreachable') ||
+                        errorMessage.includes('Health check')) {
+                        throw new Error(`Target unreachable: health check failed - ${errorMessage}`);
+                    }
+                    throw e;
+                }
+                // Get latest version of each thing
+                const latestVersions = new Map();
+                if (includeState) {
+                    for (const thing of nonDeletedThings) {
+                        const existing = latestVersions.get(thing.id);
+                        if (!existing) {
+                            latestVersions.set(thing.id, thing);
+                        }
+                    }
+                }
+                // Prepare data for transfer
+                const thingsToClone = includeState
+                    ? Array.from(latestVersions.values()).map((t) => ({
+                        id: t.id,
+                        type: t.type,
+                        branch: t.branch,
+                        name: t.name,
+                        data: t.data,
+                        deleted: false,
+                    }))
+                    : [];
+                const relationshipsToClone = shallow
+                    ? []
+                    : relationships.map((r) => ({
+                        id: r.id,
+                        verb: r.verb,
+                        from: r.from,
+                        to: r.to,
+                        data: r.data,
+                        createdAt: r.createdAt,
+                    }));
+                let actionsToClone = [];
+                let eventsToClone = [];
+                if (includeHistory) {
+                    const actions = await this.ctx.db.select().from(schema.actions);
+                    actionsToClone = actions;
+                    const events = await this.ctx.db.select().from(schema.events);
+                    eventsToClone = events;
+                }
+                // Apply transform function if provided
+                let finalThingsToClone = thingsToClone;
+                let finalRelationshipsToClone = relationshipsToClone;
+                if (transform) {
+                    try {
+                        const stateForTransform = {
+                            things: thingsToClone.map((t) => ({
+                                id: t.id,
+                                type: t.type,
+                                branch: t.branch,
+                                name: t.name,
+                                data: t.data,
+                                deleted: t.deleted,
+                            })),
+                            relationships: relationshipsToClone.map((r) => ({
+                                id: r.id,
+                                verb: r.verb,
+                                from: r.from,
+                                to: r.to,
+                                data: r.data,
+                            })),
+                        };
+                        const transformedState = await Promise.resolve(transform(stateForTransform));
+                        finalThingsToClone = transformedState.things.map((t) => ({
+                            id: t.id,
+                            type: t.type,
+                            branch: t.branch,
+                            name: t.name,
+                            data: t.data,
+                            deleted: t.deleted,
+                        }));
+                        finalRelationshipsToClone = (transformedState.relationships || []).map((r) => ({
+                            id: r.id,
+                            verb: r.verb,
+                            from: r.from,
+                            to: r.to,
+                            data: r.data,
+                            createdAt: new Date(),
+                        }));
+                    }
+                    catch (transformError) {
+                        throw new Error(`Transform error: ${transformError.message}`);
+                    }
+                }
+                // Step 1: Initialize target
+                const initResponse = await Promise.race([
+                    stub.fetch(new Request(`${targetUrl.origin}/init`, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify({
+                            correlationId,
+                            mode: 'atomic',
+                        }),
+                    })),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error(`Clone timeout after ${timeout}ms`)), timeout)),
+                ]);
+                if (!initResponse.ok) {
+                    throw new Error(`Init failed: ${initResponse.status} ${initResponse.statusText}`);
+                }
+                // Step 2: Transfer data to target
+                const response = await Promise.race([
+                    stub.fetch(new Request(`${targetUrl.origin}/transfer`, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify({
+                            things: finalThingsToClone,
+                            relationships: finalRelationshipsToClone,
+                            actions: includeHistory ? actionsToClone : undefined,
+                            events: includeHistory ? eventsToClone : undefined,
+                            correlationId,
+                        }),
+                    })),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error(`Clone timeout after ${timeout}ms`)), timeout)),
+                ]);
+                if (!response.ok) {
+                    throw new Error(`Transfer failed: ${response.status} ${response.statusText}`);
+                }
+                const duration = Date.now() - startTime;
+                await this.ctx.emitEvent('clone.completed', {
+                    target,
+                    doId: doId.toString(),
+                    correlationId,
+                    thingsCount: finalThingsToClone.length,
+                    duration,
+                });
+                return {
+                    success: true,
+                    ns: target,
+                    doId: doId.toString(),
+                    mode: 'atomic',
+                    thingsCloned: finalThingsToClone.length,
+                    relationshipsCloned: finalRelationshipsToClone.length,
+                    duration,
+                    historyIncluded: includeHistory,
+                };
+            }
+            catch (error) {
+                const errorMessage = error.message || String(error);
+                await this.ctx.emitEvent('clone.failed', {
+                    target,
+                    error: errorMessage,
+                    correlationId,
+                });
+                await this.ctx.emitEvent('clone.rollback', {
+                    target,
+                    reason: errorMessage,
+                    correlationId,
+                });
+                throw error;
+            }
+        });
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // STAGED CLONE OPERATIONS (TWO-PHASE COMMIT)
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Prepare a staged clone (Phase 1 of two-phase commit)
+     */
+    async prepareStagedClone(target, options) {
+        const token = crypto.randomUUID();
+        const timeout = options.tokenTimeout ?? DEFAULT_TOKEN_TIMEOUT;
+        const expiresAt = new Date(Date.now() + timeout);
+        const stagingNs = `${target}-staging-${token.slice(0, 8)}`;
+        options.onPrepareProgress?.(0);
+        try {
+            new URL(target);
+        }
+        catch {
+            throw new Error(`Invalid namespace URL: ${target}`);
+        }
+        if (options.validateTarget) {
+            const existingObjects = await this.ctx.db.select().from(schema.objects);
+            const occupied = existingObjects.some((obj) => obj.ns === target && obj.primary);
+            if (occupied) {
+                throw new Error(`Target namespace is occupied: ${target}`);
+            }
+        }
+        // Check for concurrent staging
+        const existingStagings = await this.ctx.ctx.storage.list({ prefix: STAGING_PREFIX });
+        for (const [, value] of existingStagings) {
+            const staging = value;
+            if (staging.targetNs === target && staging.status === 'prepared') {
+                if (new Date(staging.expiresAt) > new Date()) {
+                    throw new Error(`Target namespace is locked by pending clone operation`);
+                }
+            }
+        }
+        await this.ctx.emitEvent('clone.staging.started', { token, target });
+        // Get things to clone
+        const things = await this.ctx.db.select().from(schema.things);
+        const branchThings = things.filter((t) => !t.deleted && (t.branch === null || t.branch === this.ctx.currentBranch));
+        if (branchThings.length === 0) {
+            throw new Error('No state to clone: source is empty');
+        }
+        // Get latest version of each thing
+        const latestVersions = new Map();
+        for (const thing of branchThings) {
+            if (!latestVersions.has(thing.id)) {
+                latestVersions.set(thing.id, thing);
+            }
+        }
+        const thingsToClone = Array.from(latestVersions.values());
+        const totalItems = thingsToClone.length;
+        // Create checkpoints
+        const checkpoints = [];
+        const checkpointInterval = options.checkpointInterval ?? 0;
+        const maxCheckpoints = options.maxCheckpoints ?? 100;
+        let itemsProcessed = 0;
+        const clonedThingIds = [];
+        const clonedRelationshipIds = [];
+        for (const thing of thingsToClone) {
+            clonedThingIds.push(thing.id);
+            itemsProcessed++;
+            if (checkpointInterval > 0 && itemsProcessed % checkpointInterval === 0) {
+                const checkpoint = this.createStagedCheckpoint(token, checkpoints.length + 1, itemsProcessed, totalItems, clonedThingIds.slice(), clonedRelationshipIds.slice(), this.ctx.currentBranch, itemsProcessed, options.validationMode === 'strict');
+                checkpoints.push(checkpoint);
+                while (checkpoints.length > maxCheckpoints) {
+                    checkpoints.shift();
+                }
+            }
+            const progress = Math.floor((itemsProcessed / totalItems) * 100);
+            options.onPrepareProgress?.(progress);
+        }
+        // Final checkpoint
+        if (checkpointInterval > 0 && itemsProcessed > 0 && itemsProcessed % checkpointInterval !== 0) {
+            const finalCheckpoint = this.createStagedCheckpoint(token, checkpoints.length + 1, itemsProcessed, totalItems, clonedThingIds.slice(), clonedRelationshipIds.slice(), this.ctx.currentBranch, itemsProcessed, options.validationMode === 'strict');
+            checkpoints.push(finalCheckpoint);
+            while (checkpoints.length > maxCheckpoints) {
+                checkpoints.shift();
+            }
+        }
+        const sizeBytes = JSON.stringify(thingsToClone).length;
+        const mappedThings = thingsToClone.map((t) => ({
+            id: t.id,
+            type: t.type,
+            branch: t.branch,
+            name: t.name,
+            data: t.data,
+            deleted: t.deleted ?? false,
+        }));
+        const stagingData = {
+            sourceNs: this.ctx.ns,
+            targetNs: target,
+            stagingNs,
+            things: mappedThings,
+            expiresAt: expiresAt.toISOString(),
+            status: 'prepared',
+            createdAt: new Date().toISOString(),
+            integrityHash: this.computeStagingIntegrityHash(mappedThings),
+            metadata: {
+                thingsCount: thingsToClone.length,
+                sizeBytes,
+                branch: this.ctx.currentBranch,
+                version: thingsToClone.length,
+            },
+        };
+        await this.ctx.ctx.storage.put(`${STAGING_PREFIX}${token}`, stagingData);
+        for (const checkpoint of checkpoints) {
+            await this.ctx.ctx.storage.put(`${CHECKPOINT_PREFIX}${token}:${checkpoint.id}`, checkpoint);
+        }
+        // Store 2PC prepare decision
+        await this.ctx.ctx.storage.put(`${TWO_PC_PREFIX}prepare:${token}`, {
+            phase: 'prepared',
+            target,
+            createdAt: new Date(),
+            expiresAt,
+        });
+        // Store 2PC config
+        await this.ctx.ctx.storage.put(`${TWO_PC_PREFIX}config:${token}`, {
+            coordinatorTimeout: options.coordinatorTimeout ?? DEFAULT_COORDINATOR_TIMEOUT,
+            participantAckTimeout: options.participantAckTimeout ?? DEFAULT_ACK_TIMEOUT,
+            maxAckRetries: options.maxAckRetries ?? DEFAULT_MAX_RETRIES,
+            prepareTimeout: options.prepareTimeout,
+            commitTimeout: options.commitTimeout,
+            abortTimeout: options.abortTimeout,
+        });
+        // Initialize audit log
+        const auditLog = {
+            token,
+            sourceNs: this.ctx.ns,
+            targetNs: [target],
+            events: [
+                {
+                    type: 'prepare',
+                    status: 'completed',
+                    timestamp: new Date(),
+                    data: { thingsCount: thingsToClone.length, sizeBytes },
+                },
+            ],
+            createdAt: new Date(),
+        };
+        await this.ctx.ctx.storage.put(`${TWO_PC_PREFIX}audit:${token}`, auditLog);
+        // Initialize participant history
+        const participantHistory = {
+            target,
+            transitions: [{ from: 'initial', to: 'prepared', timestamp: new Date() }],
+        };
+        await this.ctx.ctx.storage.put(`${TWO_PC_PREFIX}history:${token}:${target}`, participantHistory);
+        options.onPrepareProgress?.(100);
+        await this.ctx.emitEvent('clone.staging.completed', { token, target, thingsCount: thingsToClone.length });
+        await this.ctx.emitEvent('clone.prepared', { token, target, expiresAt });
+        const participantAck = {
+            target,
+            status: 'ready',
+            vote: 'yes',
+            timestamp: new Date(),
+        };
+        return {
+            phase: 'prepared',
+            token,
+            expiresAt,
+            stagingNs,
+            metadata: {
+                thingsCount: thingsToClone.length,
+                sizeBytes,
+                branch: this.ctx.currentBranch,
+                version: thingsToClone.length,
+            },
+            participantAck,
+        };
+    }
+    /**
+     * Commit a staged clone (Phase 2 of two-phase commit)
+     */
+    async commitClone(token, options) {
+        if (!token || token.trim() === '') {
+            throw new Error('Invalid token: token is empty');
+        }
+        const staging = (await this.ctx.ctx.storage.get(`${STAGING_PREFIX}${token}`));
+        if (!staging) {
+            await this.ctx.emitEvent('clone.commit.failed', { token, reason: 'Invalid or not found' });
+            throw new Error('Invalid or not found: staging token');
+        }
+        if (staging.status === 'committed') {
+            await this.ctx.emitEvent('clone.commit.failed', { token, reason: 'Already committed' });
+            throw new Error('Clone already committed');
+        }
+        if (staging.status === 'aborted') {
+            await this.ctx.emitEvent('clone.commit.failed', { token, reason: 'Already aborted' });
+            throw new Error('Clone was aborted');
+        }
+        if (new Date(staging.expiresAt) < new Date()) {
+            await this.ctx.emitEvent('clone.commit.failed', { token, reason: 'Token expired' });
+            throw new Error('Token expired');
+        }
+        // Verify integrity
+        const currentHash = this.computeStagingIntegrityHash(staging.things);
+        if (currentHash !== staging.integrityHash) {
+            await this.ctx.emitEvent('clone.staging.corrupted', { token, target: staging.targetNs });
+            await this.ctx.emitEvent('clone.commit.failed', { token, reason: 'Integrity check failed' });
+            throw new Error('Staging data corrupted: integrity check failed');
+        }
+        // Validate checkpoints
+        const checkpointKeys = await this.ctx.ctx.storage.list({ prefix: `${CHECKPOINT_PREFIX}${token}:` });
+        for (const [, value] of checkpointKeys) {
+            const checkpoint = value;
+            const expectedChecksum = this.computeCheckpointChecksum(checkpoint.state);
+            if (checkpoint.checksum !== expectedChecksum) {
+                await this.ctx.emitEvent('clone.commit.failed', { token, reason: 'Checkpoint validation failed' });
+                throw new Error('Checkpoint validation failed: checksum mismatch');
+            }
+        }
+        await this.ctx.emitEvent('clone.commit.started', { token, target: staging.targetNs });
+        // Persist coordinator decision
+        const commitDecision = {
+            decision: 'commit',
+            startedAt: new Date(),
+            completedAt: null,
+        };
+        await this.ctx.ctx.storage.put(`${TWO_PC_PREFIX}decision:${token}`, commitDecision);
+        // Broadcast commit
+        for (const callback of this._broadcastCallbacks) {
+            callback('commit', staging.targetNs);
+        }
+        // Update audit log
+        const auditLog = (await this.ctx.ctx.storage.get(`${TWO_PC_PREFIX}audit:${token}`));
+        if (auditLog) {
+            auditLog.events.push({ type: 'commit', status: 'started', timestamp: new Date() }, { type: 'broadcast', status: 'completed', timestamp: new Date(), participant: staging.targetNs });
+            await this.ctx.ctx.storage.put(`${TWO_PC_PREFIX}audit:${token}`, auditLog);
+        }
+        // Create target DO and transfer state
+        if (!this.ctx.env.DO) {
+            throw new Error('DO namespace not configured');
+        }
+        const doId = this.ctx.env.DO.idFromName(staging.targetNs);
+        const stub = this.ctx.env.DO.get(doId);
+        await stub.fetch(new Request(`https://${staging.targetNs}/init`, {
+            method: 'POST',
+            body: JSON.stringify({ things: staging.things }),
+        }));
+        const committedAt = new Date();
+        commitDecision.completedAt = committedAt;
+        await this.ctx.ctx.storage.put(`${TWO_PC_PREFIX}decision:${token}`, commitDecision);
+        // Store tombstone
+        const tombstone = { ...staging, things: [], status: 'committed' };
+        await this.ctx.ctx.storage.put(`${STAGING_PREFIX}${token}`, tombstone);
+        // Clean up checkpoints
+        for (const [key] of checkpointKeys) {
+            await this.ctx.ctx.storage.delete(key);
+        }
+        // Update participant history
+        const historyKey = `${TWO_PC_PREFIX}history:${token}:${staging.targetNs}`;
+        const history = (await this.ctx.ctx.storage.get(historyKey));
+        if (history) {
+            history.transitions.push({ from: 'prepared', to: 'committed', timestamp: committedAt });
+            await this.ctx.ctx.storage.put(historyKey, history);
+        }
+        // Update audit log
+        if (auditLog) {
+            auditLog.events.push({ type: 'commit', status: 'completed', timestamp: committedAt }, { type: 'participant_ack', status: 'completed', timestamp: committedAt, participant: staging.targetNs });
+            auditLog.outcome = 'committed';
+            await this.ctx.ctx.storage.put(`${TWO_PC_PREFIX}audit:${token}`, auditLog);
+        }
+        await this.ctx.emitEvent('clone.committed', {
+            token,
+            target: staging.targetNs,
+            result: { ns: staging.targetNs, doId: doId.toString(), mode: 'staged' },
+        });
+        const participantAcks = [
+            { target: staging.targetNs, status: 'committed', timestamp: committedAt },
+        ];
+        return {
+            phase: 'committed',
+            result: {
+                ns: staging.targetNs,
+                doId: doId.toString(),
+                mode: 'staged',
+                staged: { prepareId: token, committed: true },
+            },
+            committedAt,
+            participantAcks,
+        };
+    }
+    /**
+     * Abort a staged clone
+     */
+    async abortClone(token, reason) {
+        const staging = (await this.ctx.ctx.storage.get(`${STAGING_PREFIX}${token}`));
+        const abortedAt = new Date();
+        if (staging) {
+            const tombstone = { ...staging, things: [], status: 'aborted' };
+            await this.ctx.ctx.storage.put(`${STAGING_PREFIX}${token}`, tombstone);
+            const checkpointKeys = await this.ctx.ctx.storage.list({ prefix: `${CHECKPOINT_PREFIX}${token}:` });
+            for (const [key] of checkpointKeys) {
+                await this.ctx.ctx.storage.delete(key);
+            }
+            await this.ctx.emitEvent('clone.aborted', { token, target: staging.targetNs, reason });
+        }
+        return { phase: 'aborted', token, reason, abortedAt };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // STAGED CLONE HELPERS
+    // ═══════════════════════════════════════════════════════════════════════════
+    createStagedCheckpoint(cloneId, sequence, itemsProcessed, totalItems, clonedThingIds, clonedRelationshipIds, branch, lastVersion, validated) {
+        const state = { clonedThingIds, clonedRelationshipIds, branch, lastVersion };
+        const checksum = this.computeCheckpointChecksum(state);
+        return {
+            id: `cp-${cloneId.slice(0, 8)}-${sequence}`,
+            cloneId,
+            sequence,
+            itemsProcessed,
+            totalItems,
+            createdAt: new Date(),
+            checksum,
+            state,
+            validated,
+        };
+    }
+    computeCheckpointChecksum(state) {
+        const content = JSON.stringify(state);
+        let hash = 0;
+        for (let i = 0; i < content.length; i++) {
+            const char = content.charCodeAt(i);
+            hash = ((hash << 5) - hash) + char;
+            hash = hash & hash;
+        }
+        return Math.abs(hash).toString(36);
+    }
+    computeStagingIntegrityHash(things) {
+        const content = JSON.stringify(things);
+        let hash = 0;
+        for (let i = 0; i < content.length; i++) {
+            const char = content.charCodeAt(i);
+            hash = ((hash << 5) - hash) + char;
+            hash = hash & hash;
+        }
+        return Math.abs(hash).toString(36);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // STAGING STATUS METHODS
+    // ═══════════════════════════════════════════════════════════════════════════
+    async getStagingStatus(stagingNs) {
+        const allStagings = await this.ctx.ctx.storage.list({ prefix: STAGING_PREFIX });
+        for (const [key, value] of allStagings) {
+            const staging = value;
+            if (staging.stagingNs === stagingNs) {
+                if (staging.status === 'aborted' || staging.status === 'committed') {
+                    return null;
+                }
+                const token = key.replace(STAGING_PREFIX, '');
+                return {
+                    exists: true,
+                    status: staging.status === 'prepared' ? 'ready' : staging.status,
+                    token,
+                    createdAt: new Date(staging.createdAt),
+                    expiresAt: new Date(staging.expiresAt),
+                    integrityHash: staging.integrityHash,
+                };
+            }
+        }
+        return null;
+    }
+    async getCloneTokenStatus(token) {
+        const staging = (await this.ctx.ctx.storage.get(`${STAGING_PREFIX}${token}`));
+        if (!staging) {
+            return { valid: false, status: 'not_found' };
+        }
+        const expiresAt = new Date(staging.expiresAt);
+        if (expiresAt < new Date()) {
+            return { valid: false, status: 'expired', expiresAt };
+        }
+        return { valid: staging.status === 'prepared', status: staging.status, expiresAt };
+    }
+    async getCloneCheckpoints(token) {
+        const checkpointKeys = await this.ctx.ctx.storage.list({ prefix: `${CHECKPOINT_PREFIX}${token}:` });
+        const checkpoints = [];
+        for (const [, value] of checkpointKeys) {
+            checkpoints.push(value);
+        }
+        checkpoints.sort((a, b) => a.sequence - b.sequence);
+        return checkpoints;
+    }
+    async validateCheckpoint(checkpointId) {
+        const allCheckpoints = await this.ctx.ctx.storage.list({ prefix: CHECKPOINT_PREFIX });
+        for (const [, value] of allCheckpoints) {
+            const checkpoint = value;
+            if (checkpoint.id === checkpointId) {
+                const expectedChecksum = this.computeCheckpointChecksum(checkpoint.state);
+                if (checkpoint.checksum === expectedChecksum) {
+                    return { valid: true };
+                }
+                else {
+                    return { valid: false, error: 'Checksum mismatch' };
+                }
+            }
+        }
+        return { valid: false, error: 'Checkpoint not found' };
+    }
+    async resumeCloneFromCheckpoint(checkpointId) {
+        const allCheckpoints = await this.ctx.ctx.storage.list({ prefix: CHECKPOINT_PREFIX });
+        let foundCheckpoint = null;
+        let originalToken = null;
+        for (const [key, value] of allCheckpoints) {
+            const checkpoint = value;
+            if (checkpoint.id === checkpointId) {
+                foundCheckpoint = checkpoint;
+                const parts = key.split(':');
+                if (parts.length >= 2) {
+                    originalToken = parts[1] ?? null;
+                }
+                break;
+            }
+        }
+        if (!foundCheckpoint || !originalToken) {
+            throw new Error(`Checkpoint not found: ${checkpointId}`);
+        }
+        const staging = (await this.ctx.ctx.storage.get(`${STAGING_PREFIX}${originalToken}`));
+        if (!staging) {
+            throw new Error(`Original staging data not found for checkpoint`);
+        }
+        const newToken = crypto.randomUUID();
+        const expiresAt = new Date(Date.now() + DEFAULT_TOKEN_TIMEOUT);
+        const stagingNs = `${staging.targetNs}-staging-${newToken.slice(0, 8)}`;
+        const newStagingData = {
+            ...staging,
+            stagingNs,
+            expiresAt: expiresAt.toISOString(),
+            status: 'prepared',
+            createdAt: new Date().toISOString(),
+        };
+        await this.ctx.ctx.storage.put(`${STAGING_PREFIX}${newToken}`, newStagingData);
+        const originalCheckpoints = await this.getCloneCheckpoints(originalToken);
+        for (const cp of originalCheckpoints) {
+            const newCheckpoint = { ...cp, cloneId: newToken };
+            await this.ctx.ctx.storage.put(`${CHECKPOINT_PREFIX}${newToken}:${cp.id}`, newCheckpoint);
+        }
+        return {
+            phase: 'prepared',
+            token: newToken,
+            expiresAt,
+            stagingNs,
+            metadata: staging.metadata,
+        };
+    }
+    async gcStagingAreas() {
+        let cleaned = 0;
+        let checkpointsCleaned = 0;
+        const now = new Date();
+        const allStagings = await this.ctx.ctx.storage.list({ prefix: STAGING_PREFIX });
+        for (const [key, value] of allStagings) {
+            const staging = value;
+            const expiresAt = new Date(staging.expiresAt);
+            if (expiresAt < now) {
+                const token = key.replace(STAGING_PREFIX, '');
+                await this.ctx.emitEvent('clone.expired', { token, target: staging.targetNs });
+                await this.ctx.ctx.storage.delete(key);
+                cleaned++;
+                const checkpointKeys = await this.ctx.ctx.storage.list({ prefix: `${CHECKPOINT_PREFIX}${token}:` });
+                for (const [cpKey] of checkpointKeys) {
+                    await this.ctx.ctx.storage.delete(cpKey);
+                    checkpointsCleaned++;
+                }
+            }
+        }
+        return { cleaned, checkpointsCleaned };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // EVENTUAL CLONE OPERATIONS
+    // ═══════════════════════════════════════════════════════════════════════════
+    async initiateEventualClone(target, options) {
+        try {
+            new URL(target);
+        }
+        catch {
+            throw new Error(`Invalid namespace URL: ${target}`);
+        }
+        const id = crypto.randomUUID();
+        const things = await this.ctx.db.select().from(schema.things);
+        const cloneBranch = options?.branch || this.ctx.currentBranch;
+        const branchFilter = cloneBranch === 'main' ? null : cloneBranch;
+        const branchThings = things.filter((t) => t.branch === branchFilter && !t.deleted);
+        const totalItems = branchThings.length;
+        const eventualOptions = options;
+        const syncInterval = eventualOptions?.syncInterval ?? 5000;
+        const maxDivergence = eventualOptions?.maxDivergence ?? 100;
+        const conflictResolution = eventualOptions?.conflictResolution ?? 'last-write-wins';
+        const chunked = eventualOptions?.chunked ?? false;
+        const chunkSize = eventualOptions?.chunkSize ?? 1000;
+        const rateLimit = eventualOptions?.rateLimit ?? null;
+        const customResolver = eventualOptions?.conflictResolver;
+        if (customResolver) {
+            this._conflictResolvers.set(id, customResolver);
+        }
+        const state = {
+            id,
+            targetNs: target,
+            status: 'pending',
+            progress: 0,
+            phase: 'initial',
+            itemsSynced: 0,
+            totalItems,
+            itemsRemaining: totalItems,
+            lastSyncAt: null,
+            divergence: totalItems,
+            maxDivergence,
+            syncInterval,
+            errorCount: 0,
+            lastError: null,
+            conflictResolution: customResolver ? 'custom' : conflictResolution,
+            hasCustomResolver: !!customResolver,
+            chunked,
+            chunkSize,
+            rateLimit,
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            lastSyncedVersion: 0,
+        };
+        await this.ctx.ctx.storage.put(`eventual:${id}`, state);
+        await this.ctx.emitEvent('clone.initiated', { id, target, mode: 'eventual' });
+        // Schedule initial sync
+        const currentAlarm = await this.ctx.ctx.storage.getAlarm();
+        if (!currentAlarm || currentAlarm > Date.now() + 100) {
+            await this.ctx.ctx.storage.setAlarm(Date.now() + 100);
+        }
+        return this.createEventualHandle(id, state);
+    }
+    createEventualHandle(id, initialState) {
+        const self = this;
+        let currentStatus = initialState.status;
+        const handle = {
+            id,
+            get status() {
+                return currentStatus;
+            },
+            async getProgress() {
+                const state = await self.getEventualCloneState(id);
+                if (state)
+                    currentStatus = state.status;
+                return state?.progress ?? 0;
+            },
+            async getSyncStatus() {
+                const state = await self.getEventualCloneState(id);
+                if (state)
+                    currentStatus = state.status;
+                return {
+                    phase: state?.phase ?? 'initial',
+                    itemsSynced: state?.itemsSynced ?? 0,
+                    totalItems: state?.totalItems ?? 0,
+                    lastSyncAt: state?.lastSyncAt ? new Date(state.lastSyncAt) : null,
+                    divergence: state?.divergence ?? 0,
+                    maxDivergence: state?.maxDivergence ?? 100,
+                    syncInterval: state?.syncInterval ?? 5000,
+                    errorCount: state?.errorCount ?? 0,
+                    lastError: state?.lastError ? new Error(state.lastError) : null,
+                };
+            },
+            async pause() {
+                const state = await self.getEventualCloneState(id);
+                if (!state)
+                    throw new Error(`Clone operation not found: ${id}`);
+                state.status = 'paused';
+                state.updatedAt = new Date().toISOString();
+                await self.ctx.ctx.storage.put(`eventual:${id}`, state);
+                currentStatus = 'paused';
+                await self.ctx.emitEvent('clone.paused', { id });
+            },
+            async resume() {
+                const state = await self.getEventualCloneState(id);
+                if (!state)
+                    throw new Error(`Clone operation not found: ${id}`);
+                state.status = state.phase === 'delta' || state.phase === 'catchup' ? 'active' : 'syncing';
+                state.updatedAt = new Date().toISOString();
+                await self.ctx.ctx.storage.put(`eventual:${id}`, state);
+                currentStatus = state.status;
+                await self.ctx.emitEvent('clone.resumed', { id });
+                const currentAlarm = await self.ctx.ctx.storage.getAlarm();
+                if (!currentAlarm || currentAlarm > Date.now() + 100) {
+                    await self.ctx.ctx.storage.setAlarm(Date.now() + 100);
+                }
+            },
+            async sync() {
+                return self.performEventualSync(id);
+            },
+            async cancel() {
+                const state = await self.getEventualCloneState(id);
+                if (!state)
+                    throw new Error(`Clone operation not found: ${id}`);
+                state.status = 'cancelled';
+                state.updatedAt = new Date().toISOString();
+                await self.ctx.ctx.storage.put(`eventual:${id}`, state);
+                currentStatus = 'cancelled';
+                await self.ctx.emitEvent('clone.cancelled', { id });
+            },
+        };
+        return handle;
+    }
+    async getEventualCloneState(id) {
+        return (await this.ctx.ctx.storage.get(`eventual:${id}`));
+    }
+    async performEventualSync(id) {
+        const startTime = Date.now();
+        const state = await this.getEventualCloneState(id);
+        if (!state)
+            throw new Error(`Clone operation not found: ${id}`);
+        if (state.status === 'cancelled' || state.status === 'paused') {
+            return { itemsSynced: 0, duration: 0, conflicts: [] };
+        }
+        const conflicts = [];
+        let itemsSynced = 0;
+        try {
+            if (state.status === 'pending') {
+                state.status = 'syncing';
+                state.phase = 'bulk';
+                await this.ctx.ctx.storage.put(`eventual:${id}`, state);
+                await this.ctx.emitEvent('clone.syncing', { id, progress: state.progress });
+            }
+            const things = await this.ctx.db.select().from(schema.things);
+            const branchThings = things.filter((t) => (t.branch === null || t.branch === this.ctx.currentBranch) && !t.deleted);
+            const latestVersions = new Map();
+            for (const thing of branchThings) {
+                latestVersions.set(thing.id, thing);
+            }
+            let itemsToSync = [];
+            if (state.phase === 'bulk' || state.phase === 'initial') {
+                itemsToSync = Array.from(latestVersions.values());
+            }
+            else {
+                itemsToSync = Array.from(latestVersions.values()).filter((_, idx) => idx >= state.lastSyncedVersion);
+            }
+            if (state.chunked && itemsToSync.length > state.chunkSize) {
+                itemsToSync = itemsToSync.slice(0, state.chunkSize);
+            }
+            if (state.rateLimit && itemsToSync.length > state.rateLimit) {
+                itemsToSync = itemsToSync.slice(0, state.rateLimit);
+            }
+            if (this.ctx.env.DO && itemsToSync.length > 0) {
+                const doId = this.ctx.env.DO.idFromName(state.targetNs);
+                const stub = this.ctx.env.DO.get(doId);
+                const response = await stub.fetch(new Request(`https://${state.targetNs}/sync`, {
+                    method: 'POST',
+                    body: JSON.stringify({
+                        cloneId: id,
+                        things: itemsToSync.map((t) => ({
+                            id: t.id,
+                            type: t.type,
+                            branch: null,
+                            name: t.name,
+                            data: t.data,
+                            deleted: false,
+                            version: things.indexOf(t) + 1,
+                        })),
+                    }),
+                }));
+                if (response.ok) {
+                    itemsSynced = itemsToSync.length;
+                    try {
+                        const responseData = (await response.json());
+                        if (responseData.conflicts && Array.isArray(responseData.conflicts)) {
+                            for (const conflict of responseData.conflicts) {
+                                const resolution = state.hasCustomResolver ? 'custom' : state.conflictResolution;
+                                const conflictInfo = {
+                                    thingId: conflict.thingId,
+                                    sourceVersion: conflict.sourceVersion,
+                                    targetVersion: conflict.targetVersion,
+                                    resolution,
+                                    resolvedAt: new Date(),
+                                };
+                                conflicts.push(conflictInfo);
+                                await this.ctx.emitEvent('clone.conflict', { id, ...conflictInfo });
+                            }
+                        }
+                    }
+                    catch {
+                        // Response may not be JSON
+                    }
+                }
+            }
+            // Update state
+            state.itemsSynced += itemsSynced;
+            state.lastSyncedVersion += itemsSynced;
+            state.lastSyncAt = new Date().toISOString();
+            state.itemsRemaining = Math.max(0, state.totalItems - state.itemsSynced);
+            state.progress = state.totalItems > 0 ? Math.floor((state.itemsSynced / state.totalItems) * 100) : 100;
+            state.divergence = state.itemsRemaining;
+            state.errorCount = 0;
+            state.lastError = null;
+            state.updatedAt = new Date().toISOString();
+            await this.ctx.emitEvent('clone.progress', {
+                id,
+                progress: state.progress,
+                itemsSynced: state.itemsSynced,
+                totalItems: state.totalItems,
+                phase: state.phase,
+            });
+            if (state.progress >= 100) {
+                state.status = 'active';
+                state.phase = 'delta';
+                await this.ctx.emitEvent('clone.active', { id, target: state.targetNs });
+            }
+            else if (state.itemsSynced > 0 && state.phase === 'bulk') {
+                state.phase = state.progress >= 80 ? 'catchup' : 'bulk';
+            }
+            await this.ctx.ctx.storage.put(`eventual:${id}`, state);
+            const duration = Date.now() - startTime;
+            await this.ctx.emitEvent('clone.sync.completed', { id, itemsSynced, duration });
+            return { itemsSynced, duration, conflicts };
+        }
+        catch (error) {
+            state.errorCount++;
+            state.lastError = error.message;
+            state.updatedAt = new Date().toISOString();
+            if (state.errorCount >= 10) {
+                state.status = 'error';
+                await this.ctx.emitEvent('clone.error', { id, error: state.lastError });
+            }
+            await this.ctx.ctx.storage.put(`eventual:${id}`, state);
+            return { itemsSynced: 0, duration: Date.now() - startTime, conflicts: [] };
+        }
+    }
+    async handleEventualCloneAlarms() {
+        const keys = await this.ctx.ctx.storage.list({ prefix: 'eventual:' });
+        let nextAlarmTime = null;
+        for (const [, value] of keys) {
+            const state = value;
+            if (state.status === 'cancelled' || state.status === 'paused' || state.status === 'error') {
+                continue;
+            }
+            const lastSync = state.lastSyncAt ? new Date(state.lastSyncAt).getTime() : 0;
+            const now = Date.now();
+            const nextSync = lastSync + state.syncInterval;
+            const needsSync = now >= nextSync || state.divergence > state.maxDivergence;
+            if (needsSync || state.status === 'pending') {
+                await this.performEventualSync(state.id);
+                const updatedState = await this.getEventualCloneState(state.id);
+                if (updatedState &&
+                    updatedState.status !== 'active' &&
+                    updatedState.status !== 'cancelled' &&
+                    updatedState.status !== 'error') {
+                    const nextSyncTime = Date.now() + updatedState.syncInterval;
+                    if (!nextAlarmTime || nextSyncTime < nextAlarmTime) {
+                        nextAlarmTime = nextSyncTime;
+                    }
+                }
+            }
+            else {
+                if (!nextAlarmTime || nextSync < nextAlarmTime) {
+                    nextAlarmTime = nextSync;
+                }
+            }
+        }
+        if (nextAlarmTime) {
+            await this.ctx.ctx.storage.setAlarm(nextAlarmTime);
+        }
+        await this.processResumableClones();
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // RESUMABLE CLONE OPERATIONS
+    // ═══════════════════════════════════════════════════════════════════════════
+    async initiateResumableClone(target, options) {
+        const batchSize = options?.batchSize || 100;
+        const checkpointInterval = options?.checkpointInterval || 1;
+        const maxRetries = options?.maxRetries || 3;
+        const retryDelay = options?.retryDelay || 1000;
+        const lockTimeout = options?.lockTimeout || 300000;
+        const checkpointRetentionMs = options?.checkpointRetentionMs || 3600000;
+        const compress = options?.compress || false;
+        const maxBandwidth = options?.maxBandwidth;
+        try {
+            new URL(target);
+        }
+        catch {
+            throw new Error(`Invalid namespace URL: ${target}`);
+        }
+        // Check for existing lock
+        const existingLock = this._cloneLocks.get(target) ||
+            (await this.ctx.ctx.storage.get(`clone-lock:${target}`));
+        const now = Date.now();
+        if (existingLock && !existingLock.isStale && new Date(existingLock.expiresAt).getTime() > now) {
+            if (!options?.forceLock) {
+                throw new Error(`Clone operation already in progress for target: ${target}`);
+            }
+            await this.releaseCloneLock(target, existingLock.cloneId);
+        }
+        let state;
+        let cloneId;
+        if (options?.resumeFrom) {
+            const existingState = await this.findResumableStateFromCheckpoint(options.resumeFrom);
+            if (!existingState) {
+                throw new Error(`Checkpoint not found: ${options.resumeFrom}`);
+            }
+            state = existingState;
+            cloneId = state.id;
+            state.status = 'transferring';
+            state.pauseRequested = false;
+        }
+        else {
+            cloneId = crypto.randomUUID();
+            state = {
+                id: cloneId,
+                targetNs: target,
+                status: 'initializing',
+                checkpoints: [],
+                position: 0,
+                batchSize,
+                checkpointInterval,
+                maxRetries,
+                retryDelay,
+                retryCount: 0,
+                compress,
+                maxBandwidth,
+                checkpointRetentionMs,
+                pauseRequested: false,
+                cancelRequested: false,
+                createdAt: new Date(),
+                bytesTransferred: 0,
+                totalBytes: 0,
+                startedAt: null,
+            };
+        }
+        // Acquire lock
+        const lockId = crypto.randomUUID();
+        const lock = {
+            lockId,
+            cloneId,
+            target,
+            acquiredAt: new Date(),
+            expiresAt: new Date(now + lockTimeout),
+            isStale: false,
+        };
+        this._cloneLocks.set(target, lock);
+        await this.ctx.ctx.storage.put(`clone-lock:${target}`, lock);
+        await this.ctx.emitEvent('clone.lock.acquired', { lockId, target, cloneId });
+        this._resumableClones.set(cloneId, state);
+        await this.ctx.ctx.storage.put(`resumable:${cloneId}`, state);
+        this.cleanupOrphanedCheckpoints(checkpointRetentionMs).catch(() => { });
+        const currentAlarm = await this.ctx.ctx.storage.getAlarm();
+        if (!currentAlarm || currentAlarm > Date.now() + 100) {
+            await this.ctx.ctx.storage.setAlarm(Date.now() + 100);
+        }
+        return this.createResumableCloneHandle(cloneId);
+    }
+    createResumableCloneHandle(cloneId) {
+        const self = this;
+        const handle = {
+            id: cloneId,
+            get status() {
+                const state = self._resumableClones.get(cloneId);
+                return state?.status || 'failed';
+            },
+            get checkpoints() {
+                const state = self._resumableClones.get(cloneId);
+                return state?.checkpoints || [];
+            },
+            async getProgress() {
+                const state = await self.getResumableState(cloneId);
+                return state?.progress || 0;
+            },
+            async pause() {
+                const state = await self.getResumableState(cloneId);
+                if (!state)
+                    throw new Error('Clone not found');
+                state.pauseRequested = true;
+                state.status = 'paused';
+                await self.ctx.ctx.storage.put(`resumable:${cloneId}`, state);
+                self._resumableClones.set(cloneId, state);
+                const lastCheckpoint = state.checkpoints[state.checkpoints.length - 1];
+                await self.ctx.emitEvent('clone.paused', { id: cloneId, checkpoint: lastCheckpoint, progress: state.progress });
+            },
+            async resume() {
+                const state = await self.getResumableState(cloneId);
+                if (!state)
+                    throw new Error('Clone not found');
+                state.pauseRequested = false;
+                state.status = 'transferring';
+                await self.ctx.ctx.storage.put(`resumable:${cloneId}`, state);
+                self._resumableClones.set(cloneId, state);
+                const lastCheckpoint = state.checkpoints[state.checkpoints.length - 1];
+                await self.ctx.emitEvent('clone.resumed', { id: cloneId, fromCheckpoint: lastCheckpoint });
+                const currentAlarm = await self.ctx.ctx.storage.getAlarm();
+                if (!currentAlarm || currentAlarm > Date.now() + 100) {
+                    await self.ctx.ctx.storage.setAlarm(Date.now() + 100);
+                }
+            },
+            async cancel() {
+                const state = await self.getResumableState(cloneId);
+                if (!state)
+                    throw new Error('Clone not found');
+                const progress = state.progress || 0;
+                const checkpointsCreated = state.checkpoints.length;
+                state.cancelRequested = true;
+                state.status = 'cancelled';
+                await self.ctx.ctx.storage.put(`resumable:${cloneId}`, state);
+                self._resumableClones.set(cloneId, state);
+                await self.releaseCloneLock(state.targetNs, cloneId);
+                await self.cleanupCloneCheckpoints(cloneId);
+                await self.ctx.emitEvent('clone.cancelled', { id: cloneId, progress, checkpointsCreated });
+            },
+            async waitForCheckpoint() {
+                const pollInterval = 50;
+                const maxWait = 60000;
+                const startTime = Date.now();
+                return new Promise((resolve, reject) => {
+                    const poll = async () => {
+                        const state = await self.getResumableState(cloneId);
+                        if (!state) {
+                            reject(new Error('Clone not found'));
+                            return;
+                        }
+                        if (state.checkpoints.length > 0) {
+                            resolve(state.checkpoints[state.checkpoints.length - 1]);
+                            return;
+                        }
+                        if (Date.now() - startTime > maxWait) {
+                            reject(new Error('Timeout waiting for checkpoint'));
+                            return;
+                        }
+                        setTimeout(poll, pollInterval);
+                    };
+                    poll();
+                });
+            },
+            async canResumeFrom(checkpointId) {
+                const checkpoint = await self.ctx.ctx.storage.get(`checkpoint:${checkpointId}`);
+                if (!checkpoint)
+                    return false;
+                return self.validateCheckpointHash(checkpoint);
+            },
+            async getIntegrityHash() {
+                const state = await self.getResumableState(cloneId);
+                if (!state || state.checkpoints.length === 0)
+                    return '';
+                return state.checkpoints[state.checkpoints.length - 1].hash;
+            },
+            async getLockInfo() {
+                const state = await self.getResumableState(cloneId);
+                if (!state)
+                    return null;
+                const lock = self._cloneLocks.get(state.targetNs) ||
+                    (await self.ctx.ctx.storage.get(`clone-lock:${state.targetNs}`));
+                if (!lock || lock.cloneId !== cloneId)
+                    return null;
+                return {
+                    lockId: lock.lockId,
+                    cloneId: lock.cloneId,
+                    acquiredAt: new Date(lock.acquiredAt),
+                    expiresAt: new Date(lock.expiresAt),
+                    isStale: lock.isStale || new Date(lock.expiresAt).getTime() < Date.now(),
+                };
+            },
+            async forceOverrideLock() {
+                const state = await self.getResumableState(cloneId);
+                if (!state)
+                    throw new Error('Clone not found');
+                await self.releaseCloneLock(state.targetNs, cloneId);
+            },
+        };
+        return handle;
+    }
+    async processResumableClones() {
+        const storageKeys = await this.ctx.ctx.storage.list({ prefix: 'resumable:' });
+        for (const [key, value] of storageKeys) {
+            const cloneId = key.replace('resumable:', '');
+            if (!this._resumableClones.has(cloneId)) {
+                this._resumableClones.set(cloneId, value);
+            }
+        }
+        for (const [cloneId, state] of this._resumableClones) {
+            if (state.status === 'paused' || state.pauseRequested)
+                continue;
+            if (state.status === 'cancelled' || state.cancelRequested)
+                continue;
+            if (state.status === 'completed' || state.status === 'failed')
+                continue;
+            await this.processResumableCloneBatch(cloneId);
+        }
+    }
+    async processResumableCloneBatch(cloneId) {
+        const state = await this.getResumableState(cloneId);
+        if (!state)
+            return;
+        if (state.pauseRequested || state.status === 'paused')
+            return;
+        if (state.cancelRequested || state.status === 'cancelled')
+            return;
+        if (state.status === 'initializing') {
+            state.status = 'transferring';
+            state.startedAt = new Date();
+        }
+        try {
+            const allThings = await this.ctx.db.select().from(schema.things);
+            const nonDeletedThings = allThings.filter((t) => !t.deleted);
+            const totalItems = nonDeletedThings.length;
+            if (state.totalBytes === 0) {
+                state.totalBytes = nonDeletedThings.reduce((acc, t) => acc + JSON.stringify(t).length, 0);
+            }
+            const batch = nonDeletedThings.slice(state.position, state.position + state.batchSize);
+            if (batch.length === 0) {
+                await this.completeResumableClone(cloneId, state);
+                return;
+            }
+            // Apply bandwidth throttling
+            if (state.maxBandwidth) {
+                const batchBytes = batch.reduce((acc, t) => acc + JSON.stringify(t).length, 0);
+                const expectedTime = (batchBytes / state.maxBandwidth) * 1000;
+                if (expectedTime > 0) {
+                    await this.sleep(Math.floor(expectedTime));
+                    if (expectedTime > 100) {
+                        await this.ctx.emitEvent('clone.throttled', { id: cloneId, delayMs: expectedTime, batchBytes });
+                    }
+                }
+            }
+            await this.transferBatchToTarget(state.targetNs, batch, state.compress);
+            const batchBytes = batch.reduce((acc, t) => acc + JSON.stringify(t).length, 0);
+            state.bytesTransferred += batchBytes;
+            state.position += batch.length;
+            state.progress = Math.round((state.position / totalItems) * 100);
+            const batchNumber = Math.ceil(state.position / state.batchSize);
+            await this.ctx.emitEvent('clone.batch.completed', {
+                id: cloneId,
+                batchNumber,
+                itemsInBatch: batch.length,
+                itemsProcessed: state.position,
+                progress: state.progress,
+            });
+            const shouldCreateCheckpoint = batchNumber % state.checkpointInterval === 0;
+            if (shouldCreateCheckpoint) {
+                const checkpoint = await this.createResumableCheckpoint(cloneId, state, batch, batchNumber);
+                state.checkpoints.push(checkpoint);
+                await this.ctx.ctx.storage.put(`checkpoint:${cloneId}:${checkpoint.id}`, checkpoint);
+                await this.ctx.ctx.storage.put(`checkpoint:${checkpoint.id}`, checkpoint);
+                await this.ctx.emitEvent('clone.checkpoint', {
+                    id: cloneId,
+                    checkpoint,
+                    checkpointId: checkpoint.id,
+                    position: checkpoint.position,
+                    hash: checkpoint.hash,
+                });
+            }
+            state.retryCount = 0;
+            await this.ctx.ctx.storage.put(`resumable:${cloneId}`, state);
+            this._resumableClones.set(cloneId, state);
+            if (state.position < totalItems && !state.pauseRequested && !state.cancelRequested) {
+                const currentAlarm = await this.ctx.ctx.storage.getAlarm();
+                if (!currentAlarm || currentAlarm > Date.now() + 100) {
+                    await this.ctx.ctx.storage.setAlarm(Date.now() + 100);
+                }
+            }
+            else if (state.position >= totalItems) {
+                await this.completeResumableClone(cloneId, state);
+            }
+        }
+        catch (error) {
+            await this.handleResumableCloneError(cloneId, state, error);
+        }
+    }
+    async createResumableCheckpoint(cloneId, state, batch, batchNumber) {
+        const batchJson = JSON.stringify(batch);
+        const hashBuffer = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(batchJson));
+        const hashArray = Array.from(new Uint8Array(hashBuffer));
+        const hash = hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+        return {
+            id: crypto.randomUUID(),
+            position: state.position,
+            hash,
+            timestamp: new Date(),
+            itemsProcessed: state.position,
+            batchNumber,
+            cloneId,
+            compressed: state.compress,
+        };
+    }
+    async completeResumableClone(cloneId, state) {
+        const duration = state.startedAt ? Date.now() - new Date(state.startedAt).getTime() : 0;
+        state.status = 'completed';
+        await this.ctx.ctx.storage.put(`resumable:${cloneId}`, state);
+        this._resumableClones.set(cloneId, state);
+        await this.releaseCloneLock(state.targetNs, cloneId);
+        await this.cleanupCloneCheckpoints(cloneId);
+        await this.ctx.emitEvent('clone.completed', {
+            id: cloneId,
+            totalCheckpoints: state.checkpoints.length,
+            totalItems: state.position,
+            duration,
+        });
+    }
+    async handleResumableCloneError(cloneId, state, error) {
+        state.retryCount++;
+        await this.ctx.emitEvent('clone.retry', { id: cloneId, attempt: state.retryCount, error: error.message });
+        if (state.retryCount >= state.maxRetries) {
+            state.status = 'failed';
+            await this.ctx.ctx.storage.put(`resumable:${cloneId}`, state);
+            this._resumableClones.set(cloneId, state);
+            await this.ctx.emitEvent('clone.failed', { id: cloneId, error: error.message, retryCount: state.retryCount });
+            await this.releaseCloneLock(state.targetNs, cloneId);
+            return;
+        }
+        const baseDelay = state.retryDelay * Math.pow(2, state.retryCount - 1);
+        const jitter = Math.random() * baseDelay * 0.25;
+        const delay = Math.floor(baseDelay + jitter);
+        await this.ctx.ctx.storage.put(`resumable:${cloneId}`, state);
+        this._resumableClones.set(cloneId, state);
+        const currentAlarm = await this.ctx.ctx.storage.getAlarm();
+        if (!currentAlarm || currentAlarm > Date.now() + delay) {
+            await this.ctx.ctx.storage.setAlarm(Date.now() + delay);
+        }
+    }
+    async transferBatchToTarget(targetNs, batch, compress) {
+        if (!this.ctx.env.DO) {
+            throw new Error('DO namespace not configured');
+        }
+        await Promise.resolve();
+    }
+    async getResumableState(cloneId) {
+        let state = this._resumableClones.get(cloneId);
+        if (state)
+            return state;
+        state = await this.ctx.ctx.storage.get(`resumable:${cloneId}`);
+        if (state) {
+            this._resumableClones.set(cloneId, state);
+        }
+        return state || null;
+    }
+    async findResumableStateFromCheckpoint(checkpointId) {
+        const checkpoint = await this.ctx.ctx.storage.get(`checkpoint:${checkpointId}`);
+        if (!checkpoint || !checkpoint.cloneId)
+            return null;
+        return this.getResumableState(checkpoint.cloneId);
+    }
+    async validateCheckpointHash(checkpoint) {
+        if (!checkpoint.hash || !/^[a-f0-9]{64}$/.test(checkpoint.hash))
+            return false;
+        if (checkpoint.position < 0)
+            return false;
+        return true;
+    }
+    async releaseCloneLock(target, cloneId) {
+        const lock = this._cloneLocks.get(target) ||
+            (await this.ctx.ctx.storage.get(`clone-lock:${target}`));
+        if (lock && lock.cloneId === cloneId) {
+            this._cloneLocks.delete(target);
+            await this.ctx.ctx.storage.delete(`clone-lock:${target}`);
+            await this.ctx.emitEvent('clone.lock.released', { lockId: lock.lockId, target });
+        }
+    }
+    async cleanupCloneCheckpoints(cloneId) {
+        const state = await this.getResumableState(cloneId);
+        if (!state)
+            return;
+        for (const checkpoint of state.checkpoints) {
+            await this.ctx.ctx.storage.delete(`checkpoint:${cloneId}:${checkpoint.id}`);
+            await this.ctx.ctx.storage.delete(`checkpoint:${checkpoint.id}`);
+        }
+    }
+    async cleanupOrphanedCheckpoints(retentionMs) {
+        const now = Date.now();
+        const cutoff = now - retentionMs;
+        const checkpointKeys = await this.ctx.ctx.storage.list({ prefix: 'checkpoint:' });
+        for (const [key, value] of checkpointKeys) {
+            const checkpoint = value;
+            if (!checkpoint.timestamp)
+                continue;
+            const checkpointTime = new Date(checkpoint.timestamp).getTime();
+            if (checkpointTime < cutoff) {
+                if (checkpoint.cloneId) {
+                    const state = await this.getResumableState(checkpoint.cloneId);
+                    if (state && state.status === 'paused')
+                        continue;
+                }
+                await this.ctx.ctx.storage.delete(key);
+            }
+        }
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    // Test helper methods
+    async _corruptCheckpoint(token, checkpointId) {
+        const checkpointKey = `${CHECKPOINT_PREFIX}${token}:${checkpointId}`;
+        const checkpoint = (await this.ctx.ctx.storage.get(checkpointKey));
+        if (checkpoint) {
+            checkpoint.checksum = 'corrupted-checksum';
+            await this.ctx.ctx.storage.put(checkpointKey, checkpoint);
+        }
+    }
+    async _corruptStagingArea(token) {
+        const staging = (await this.ctx.ctx.storage.get(`${STAGING_PREFIX}${token}`));
+        if (staging) {
+            staging.integrityHash = 'corrupted-hash';
+            await this.ctx.ctx.storage.put(`${STAGING_PREFIX}${token}`, staging);
+        }
+    }
+}
+// Export singleton factory
+export function createCloneModule() {
+    return new CloneModule();
+}
+//# sourceMappingURL=Clone.js.map