@aiwg/cli 2026.8.19 → 2026.8.25

package/dist/src/storage/migration-protocol.js

@@ -0,0 +1,378 @@
+import { createHash, randomUUID } from 'node:crypto';
+export const STORAGE_MIGRATION_PROTOCOL = 'aiwg.storage-migration/v1';
+export class MigrationProtocolError extends Error {
+    code;
+    retryable;
+    constructor(code, message, retryable = false) {
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.name = 'MigrationProtocolError';
+    }
+}
+export class StorageMigrationCoordinator {
+    source;
+    destination;
+    store;
+    routing;
+    options;
+    batchSize;
+    concurrency;
+    maxRetries;
+    baseBackoffMs;
+    rollbackWindowMs;
+    now;
+    random;
+    persistChain = Promise.resolve();
+    constructor(source, destination, store, routing, options) {
+        this.source = source;
+        this.destination = destination;
+        this.store = store;
+        this.routing = routing;
+        this.options = options;
+        this.batchSize = boundedInteger(options.batchSize, 100, 1, 10_000, 'batchSize');
+        this.concurrency = boundedInteger(options.concurrency, 4, 1, 32, 'concurrency');
+        this.maxRetries = boundedInteger(options.maxRetries, 5, 0, 20, 'maxRetries');
+        this.baseBackoffMs = boundedInteger(options.baseBackoffMs, 25, 1, 60_000, 'baseBackoffMs');
+        this.rollbackWindowMs = boundedInteger(options.rollbackWindowMs, 86_400_000, 1, 31_536_000_000, 'rollbackWindowMs');
+        this.now = options.now ?? (() => new Date());
+        this.random = options.random ?? Math.random;
+    }
+    async preview() {
+        this.throwIfAborted();
+        const snapshot = await this.source.snapshot(this.options.signal);
+        const createdAt = this.now().toISOString();
+        const sourceDigest = digestRecords(snapshot.records);
+        const manifest = {
+            protocol: STORAGE_MIGRATION_PROTOCOL,
+            migrationId: randomUUID(),
+            mode: this.options.mode,
+            state: 'preview',
+            source: this.source.identity,
+            destination: this.destination.identity,
+            toolVersion: this.options.toolVersion,
+            createdAt,
+            updatedAt: createdAt,
+            snapshot: {
+                id: snapshot.id,
+                highWaterMark: snapshot.highWaterMark,
+                ...(snapshot.cursor === undefined ? {} : { cursor: snapshot.cursor }),
+            },
+            checkpoint: { highWaterMark: snapshot.highWaterMark, committedBatches: 0 },
+            counts: {
+                source: snapshot.records.length,
+                upserts: snapshot.records.filter(record => !record.tombstone).length,
+                tombstones: snapshot.records.filter(record => record.tombstone).length,
+                committed: 0,
+            },
+            digests: { source: sourceDigest },
+            records: [],
+        };
+        await this.store.save(manifest);
+        return manifest;
+    }
+    async apply(manifest) {
+        validateManifest(manifest, this.source.identity, this.destination.identity);
+        const snapshot = await this.source.snapshot(this.options.signal);
+        if (snapshot.id !== manifest.snapshot.id || digestRecords(snapshot.records) !== manifest.digests.source) {
+            throw new MigrationProtocolError('AIWG_MIGRATION_SNAPSHOT_CHANGED', 'source snapshot no longer matches the preview; create a new preview');
+        }
+        manifest.state = 'copying';
+        await this.persist(manifest);
+        await this.copyRecords(snapshot.records, manifest);
+        if (manifest.mode === 'online') {
+            if (!this.source.changes) {
+                throw new MigrationProtocolError('AIWG_MIGRATION_CURSOR_UNAVAILABLE', 'online migration requires a source change cursor');
+            }
+            manifest.state = 'replaying';
+            await this.persist(manifest);
+            let cursor = manifest.snapshot.cursor;
+            for (;;) {
+                this.throwIfAborted();
+                const page = await this.source.changes(cursor, this.options.signal);
+                await this.copyRecords(page.records, manifest);
+                cursor = page.nextCursor;
+                manifest.checkpoint = {
+                    ...manifest.checkpoint,
+                    ...(cursor === undefined ? {} : { cursor }),
+                    highWaterMark: page.highWaterMark,
+                    drained: page.records.length === 0 || cursor === undefined,
+                };
+                await this.persist(manifest);
+                if (page.records.length === 0 || cursor === undefined)
+                    break;
+            }
+        }
+        manifest.state = 'verifying';
+        await this.persist(manifest);
+        const verification = await this.verify(manifest);
+        if (!verification.valid) {
+            manifest.state = 'failed';
+            manifest.failure = { stage: 'verify', message: summarizeVerificationFailure(verification) };
+            await this.persist(manifest);
+            throw new MigrationProtocolError('AIWG_MIGRATION_PARITY_FAILED', manifest.failure.message);
+        }
+        manifest.digests.destination = verification.destinationDigest;
+        manifest.state = 'awaiting-approval';
+        manifest.updatedAt = this.now().toISOString();
+        manifest.digests.approval = approvalDigest(manifest);
+        await this.save(manifest);
+        return manifest;
+    }
+    async verify(manifest) {
+        const [sourceRecords, destinationRecords] = await Promise.all([
+            this.source.readAll(this.options.signal),
+            this.destination.readAll(this.options.signal),
+        ]);
+        const sourceMap = recordMap(sourceRecords);
+        const destinationMap = recordMap(destinationRecords);
+        const missing = [...sourceMap.keys()].filter(key => !destinationMap.has(key)).sort();
+        const unexpected = [...destinationMap.keys()].filter(key => !sourceMap.has(key)).sort();
+        const corrupt = [...sourceMap.entries()]
+            .filter(([key, record]) => {
+            const destination = destinationMap.get(key);
+            return destination !== undefined && (destination.digest !== record.digest ||
+                Boolean(destination.tombstone) !== Boolean(record.tombstone));
+        })
+            .map(([key]) => key)
+            .sort();
+        const lag = manifest.mode === 'online' ? Number(!manifest.checkpoint.drained) : 0;
+        const sourceDigest = digestRecords(sourceRecords);
+        const destinationDigest = digestRecords(destinationRecords);
+        return {
+            valid: missing.length === 0 && unexpected.length === 0 && corrupt.length === 0 && lag === 0,
+            sourceCount: sourceRecords.length,
+            destinationCount: destinationRecords.length,
+            sourceDigest,
+            destinationDigest,
+            missing,
+            unexpected,
+            corrupt,
+            lag,
+        };
+    }
+    async cutover(manifest, approval) {
+        validateManifest(manifest, this.source.identity, this.destination.identity);
+        if (manifest.state !== 'awaiting-approval') {
+            throw new MigrationProtocolError('AIWG_MIGRATION_NOT_READY', 'migration is not awaiting cutover approval');
+        }
+        const expected = approvalDigest(manifest);
+        if (approval !== expected || manifest.digests.approval !== expected) {
+            throw new MigrationProtocolError('AIWG_MIGRATION_APPROVAL_MISMATCH', 'cutover approval is not bound to this verified manifest');
+        }
+        const verification = await this.verify(manifest);
+        if (!verification.valid) {
+            throw new MigrationProtocolError('AIWG_MIGRATION_PARITY_FAILED', summarizeVerificationFailure(verification));
+        }
+        manifest.state = 'cutover';
+        await this.persist(manifest);
+        try {
+            await this.routing.switchReads(manifest);
+            await this.routing.switchWrites(manifest);
+        }
+        catch (error) {
+            await this.routing.restoreSource(manifest);
+            manifest.state = 'failed';
+            manifest.failure = { stage: 'cutover', message: errorMessage(error) };
+            await this.persist(manifest);
+            throw new MigrationProtocolError('AIWG_MIGRATION_CUTOVER_FAILED', manifest.failure.message);
+        }
+        manifest.state = 'observing';
+        manifest.rollbackWindowEndsAt = new Date(this.now().getTime() + this.rollbackWindowMs).toISOString();
+        await this.persist(manifest);
+        return manifest;
+    }
+    async complete(manifest) {
+        if (manifest.state !== 'observing') {
+            throw new MigrationProtocolError('AIWG_MIGRATION_NOT_OBSERVING', 'migration is not in its rollback window');
+        }
+        manifest.state = 'completed';
+        await this.persist(manifest);
+        return manifest;
+    }
+    async rollback(manifest) {
+        if (!['cutover', 'observing', 'failed'].includes(manifest.state)) {
+            throw new MigrationProtocolError('AIWG_MIGRATION_NOT_ROLLBACKABLE', `cannot roll back state ${manifest.state}`);
+        }
+        await this.routing.restoreSource(manifest);
+        manifest.state = 'rolled-back';
+        await this.persist(manifest);
+        return manifest;
+    }
+    async copyRecords(records, manifest) {
+        const completed = new Set(manifest.records.map(receiptKey));
+        const pending = records.filter(record => !completed.has(recordKey(record)));
+        const batches = chunk(pending, this.batchSize);
+        let next = 0;
+        const workers = Array.from({ length: Math.min(this.concurrency, batches.length) }, async () => {
+            for (;;) {
+                const index = next++;
+                if (index >= batches.length)
+                    return;
+                const batch = batches[index];
+                const mutations = batch.map(record => mutationFor(manifest.migrationId, record));
+                const receipt = await this.retry(() => this.destination.commitBatch(mutations, this.options.signal), `batch ${index}`);
+                if (!receipt.committed || receipt.recordReceipts.length !== batch.length) {
+                    throw new MigrationProtocolError('AIWG_MIGRATION_INVALID_RECEIPT', `destination returned an invalid receipt for batch ${index}`);
+                }
+                const committedAt = this.now().toISOString();
+                const committedByIdentity = new Map(receipt.recordReceipts.map(recordReceipt => [identityKey(recordReceipt.identity), recordReceipt]));
+                for (let recordIndex = 0; recordIndex < batch.length; recordIndex++) {
+                    const record = batch[recordIndex];
+                    const committed = committedByIdentity.get(identityKey(record.identity));
+                    if (!committed || committed.digest !== record.digest) {
+                        throw new MigrationProtocolError('AIWG_MIGRATION_CORRUPT_RECEIPT', `destination receipt diverged for ${identityKey(record.identity)}`);
+                    }
+                    manifest.records.push({
+                        identity: record.identity,
+                        sourceRevision: record.sourceRevision,
+                        contentDigest: record.digest,
+                        destinationRevision: committed.sourceRevision,
+                        tombstone: Boolean(record.tombstone),
+                        idempotencyKey: mutations[recordIndex].idempotencyKey,
+                        batchId: receipt.batchId,
+                        committedAt,
+                    });
+                }
+                manifest.counts.committed = manifest.records.length;
+                manifest.checkpoint.committedBatches += 1;
+                manifest.checkpoint.highWaterMark = receipt.highWaterMark;
+                await this.persist(manifest);
+            }
+        });
+        await Promise.all(workers);
+    }
+    async retry(operation, label) {
+        let attempt = 0;
+        for (;;) {
+            this.throwIfAborted();
+            try {
+                return await operation();
+            }
+            catch (error) {
+                const retryable = error instanceof MigrationProtocolError && error.retryable;
+                if (!retryable)
+                    throw error;
+                if (attempt >= this.maxRetries) {
+                    throw new MigrationProtocolError('AIWG_MIGRATION_RETRY_EXHAUSTED', `${label} failed after ${attempt + 1} attempt(s): ${errorMessage(error)}`);
+                }
+                const exponential = this.baseBackoffMs * 2 ** attempt;
+                const jitter = Math.floor(exponential * 0.25 * this.random());
+                await abortableDelay(Math.min(exponential + jitter, 60_000), this.options.signal);
+                attempt += 1;
+            }
+        }
+    }
+    async persist(manifest) {
+        manifest.updatedAt = this.now().toISOString();
+        await this.save(manifest);
+    }
+    async save(manifest) {
+        const snapshot = structuredClone(manifest);
+        const save = this.persistChain.then(() => this.store.save(snapshot));
+        this.persistChain = save.catch(() => undefined);
+        await save;
+    }
+    throwIfAborted() {
+        if (this.options.signal?.aborted) {
+            throw new MigrationProtocolError('AIWG_MIGRATION_CANCELLED', 'migration cancelled by operator');
+        }
+    }
+}
+export function digestRecords(records) {
+    const normalized = [...records]
+        .map(record => ({
+        identity: record.identity,
+        sourceRevision: record.sourceRevision,
+        digest: record.digest,
+        tombstone: record.tombstone ?? null,
+    }))
+        .sort((left, right) => identityKey(left.identity).localeCompare(identityKey(right.identity)));
+    return sha256(stableStringify(normalized));
+}
+export function approvalDigest(manifest) {
+    const copy = structuredClone(manifest);
+    delete copy.digests.approval;
+    return sha256(stableStringify(copy));
+}
+export function validateManifest(manifest, source, destination) {
+    if (manifest.protocol !== STORAGE_MIGRATION_PROTOCOL) {
+        throw new MigrationProtocolError('AIWG_MIGRATION_PROTOCOL_UNSUPPORTED', `unsupported migration protocol ${String(manifest.protocol)}`);
+    }
+    if (!manifest.migrationId || !manifest.snapshot?.id || !manifest.digests?.source) {
+        throw new MigrationProtocolError('AIWG_MIGRATION_MANIFEST_CORRUPT', 'migration manifest is missing required identity or digest fields');
+    }
+    if (source && stableStringify(manifest.source) !== stableStringify(source)) {
+        throw new MigrationProtocolError('AIWG_MIGRATION_SOURCE_MISMATCH', 'manifest source does not match the active source');
+    }
+    if (destination && stableStringify(manifest.destination) !== stableStringify(destination)) {
+        throw new MigrationProtocolError('AIWG_MIGRATION_DESTINATION_MISMATCH', 'manifest destination does not match the active destination');
+    }
+}
+function mutationFor(migrationId, record) {
+    return {
+        operation: record.tombstone ? 'delete' : 'upsert',
+        record,
+        idempotencyKey: sha256(`${migrationId}\0${recordKey(record)}`),
+    };
+}
+function recordMap(records) {
+    return new Map(records.map(record => [identityKey(record.identity), record]));
+}
+function identityKey(identity) {
+    return `${identity.tenant}\0${identity.subsystem}\0${identity.path}`;
+}
+function recordKey(record) {
+    return `${identityKey(record.identity)}\0${record.sourceRevision}\0${record.digest}`;
+}
+function receiptKey(receipt) {
+    return `${identityKey(receipt.identity)}\0${receipt.sourceRevision}\0${receipt.contentDigest}`;
+}
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function stableStringify(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    if (value && typeof value === 'object') {
+        return `{${Object.entries(value)
+            .filter(([, child]) => child !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, child]) => `${JSON.stringify(key)}:${stableStringify(child)}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function chunk(items, size) {
+    const chunks = [];
+    for (let index = 0; index < items.length; index += size)
+        chunks.push(items.slice(index, index + size));
+    return chunks;
+}
+function boundedInteger(raw, fallback, min, max, label) {
+    const value = raw ?? fallback;
+    if (!Number.isInteger(value) || value < min || value > max) {
+        throw new MigrationProtocolError('AIWG_MIGRATION_INVALID_OPTION', `${label} must be an integer from ${min} through ${max}`);
+    }
+    return value;
+}
+function summarizeVerificationFailure(verification) {
+    return `migration parity failed: missing=${verification.missing.length} unexpected=${verification.unexpected.length} corrupt=${verification.corrupt.length} lag=${verification.lag}`;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function abortableDelay(ms, signal) {
+    if (!signal) {
+        await new Promise(resolve => setTimeout(resolve, ms));
+        return;
+    }
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(resolve, ms);
+        signal.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(new MigrationProtocolError('AIWG_MIGRATION_CANCELLED', 'migration cancelled by operator'));
+        }, { once: true });
+    });
+}
+//# sourceMappingURL=migration-protocol.js.map