@aiwg/cli 2026.8.25 → 2026.8.27

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

@@ -37,10 +37,28 @@ export class StorageMigrationCoordinator {
         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;
+        if (options.mode === 'online' && !options.compareSourceRevisions) {
+            throw new MigrationProtocolError('AIWG_MIGRATION_REVISION_ORDER_REQUIRED', 'online migration requires a source-revision comparator');
+        }
     }
     async preview() {
         this.throwIfAborted();
-        const snapshot = await this.source.snapshot(this.options.signal);
+        const boundary = await this.options.safety.prepare(this.options.mode, this.source.identity, this.options.signal);
+        try {
+            assertBoundaryState(boundary, this.options.mode === 'offline' ? 'quiesced' : 'tracking', 'initial');
+        }
+        catch (error) {
+            await this.options.safety.release(boundary, 'failed');
+            throw error;
+        }
+        let snapshot;
+        try {
+            snapshot = await this.source.snapshot(this.options.signal);
+        }
+        catch (error) {
+            await this.options.safety.release(boundary, 'failed');
+            throw error;
+        }
         const createdAt = this.now().toISOString();
         const sourceDigest = digestRecords(snapshot.records);
         const manifest = {
@@ -67,57 +85,69 @@ export class StorageMigrationCoordinator {
             },
             digests: { source: sourceDigest },
             records: [],
+            boundaries: { initial: boundary },
         };
-        await this.store.save(manifest);
+        try {
+            await this.store.save(manifest);
+        }
+        catch (error) {
+            await this.options.safety.release(boundary, 'failed');
+            throw error;
+        }
         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');
+        try {
+            const snapshot = await this.source.snapshot(this.options.signal);
+            if (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 = 'replaying';
+            manifest.state = 'copying';
             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.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);
-                if (page.records.length === 0 || cursor === undefined)
-                    break;
+                await this.replayChanges(manifest);
             }
+            const finalBoundary = await this.options.safety.freeze(manifest, this.options.signal);
+            manifest.boundaries.final = finalBoundary;
+            assertBoundaryState(finalBoundary, 'quiesced', 'final');
+            await this.persist(manifest);
+            if (manifest.mode === 'online')
+                await this.replayChanges(manifest);
+            manifest.state = 'verifying';
+            await this.persist(manifest);
+            const verification = await this.verify(manifest);
+            if (!verification.valid) {
+                throw new MigrationProtocolError('AIWG_MIGRATION_PARITY_FAILED', summarizeVerificationFailure(verification));
+            }
+            manifest.digests.destination = verification.destinationDigest;
+            manifest.verification = verification;
+            manifest.digests.verification = sha256(stableStringify(verification));
+            manifest.state = 'awaiting-approval';
+            manifest.updatedAt = this.now().toISOString();
+            manifest.digests.approval = approvalDigest(manifest);
+            await this.save(manifest);
+            return manifest;
         }
-        manifest.state = 'verifying';
-        await this.persist(manifest);
-        const verification = await this.verify(manifest);
-        if (!verification.valid) {
+        catch (error) {
+            const stage = manifest.state;
             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.failure = { stage, message: errorMessage(error) };
+            try {
+                await this.persist(manifest);
+            }
+            catch {
+                // Preserve the triggering failure; the manifest store error is already observable at its source.
+            }
+            await this.options.safety.release(manifest.boundaries.final ?? manifest.boundaries.initial, 'failed');
+            throw error;
         }
-        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([
@@ -131,16 +161,35 @@ export class StorageMigrationCoordinator {
         const corrupt = [...sourceMap.entries()]
             .filter(([key, record]) => {
             const destination = destinationMap.get(key);
-            return destination !== undefined && (destination.digest !== record.digest ||
+            return destination !== undefined && (destination.sourceRevision !== record.sourceRevision ||
+                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 boundaryReady = manifest.boundaries.final?.state === 'quiesced';
+        const lag = Number(!boundaryReady || (manifest.mode === 'online' && !manifest.checkpoint.drained));
         const sourceDigest = digestRecords(sourceRecords);
         const destinationDigest = digestRecords(destinationRecords);
+        const sourceChunks = digestRecordChunks(sourceRecords, this.batchSize);
+        const destinationChunks = digestRecordChunks(destinationRecords, this.batchSize);
+        const chunks = {
+            valid: stableStringify(sourceChunks) === stableStringify(destinationChunks),
+            source: sourceChunks,
+            destination: destinationChunks,
+        };
+        const semantic = await this.options.verifier.verify({
+            manifest,
+            source: this.source,
+            destination: this.destination,
+            sourceRecords,
+            destinationRecords,
+            signal: this.options.signal,
+        });
+        validateSemanticVerification(semantic);
         return {
-            valid: missing.length === 0 && unexpected.length === 0 && corrupt.length === 0 && lag === 0,
+            valid: missing.length === 0 && unexpected.length === 0 && corrupt.length === 0 && lag === 0 &&
+                sourceDigest === destinationDigest && chunks.valid && semanticIsValid(semantic),
             sourceCount: sourceRecords.length,
             destinationCount: destinationRecords.length,
             sourceDigest,
@@ -149,6 +198,8 @@ export class StorageMigrationCoordinator {
             unexpected,
             corrupt,
             lag,
+            chunks,
+            semantic,
         };
     }
     async cutover(manifest, approval) {
@@ -164,14 +215,22 @@ export class StorageMigrationCoordinator {
         if (!verification.valid) {
             throw new MigrationProtocolError('AIWG_MIGRATION_PARITY_FAILED', summarizeVerificationFailure(verification));
         }
+        if (!manifest.digests.verification || sha256(stableStringify(verification)) !== manifest.digests.verification) {
+            throw new MigrationProtocolError('AIWG_MIGRATION_VERIFICATION_CHANGED', 'migration verification changed after approval; verify and approve a new manifest');
+        }
+        const finalBoundary = manifest.boundaries.final;
+        if (!finalBoundary) {
+            throw new MigrationProtocolError('AIWG_MIGRATION_BOUNDARY_MISSING', 'migration has no final quiesced source boundary');
+        }
         manifest.state = 'cutover';
         await this.persist(manifest);
         try {
-            await this.routing.switchReads(manifest);
-            await this.routing.switchWrites(manifest);
+            manifest.routingSwitch = await this.routing.switchAtomically(manifest);
+            await this.options.safety.release(finalBoundary, 'cutover');
         }
         catch (error) {
             await this.routing.restoreSource(manifest);
+            await this.options.safety.release(finalBoundary, 'failed');
             manifest.state = 'failed';
             manifest.failure = { stage: 'cutover', message: errorMessage(error) };
             await this.persist(manifest);
@@ -195,13 +254,47 @@ export class StorageMigrationCoordinator {
             throw new MigrationProtocolError('AIWG_MIGRATION_NOT_ROLLBACKABLE', `cannot roll back state ${manifest.state}`);
         }
         await this.routing.restoreSource(manifest);
+        await this.options.safety.release(manifest.boundaries.final ?? manifest.boundaries.initial, 'rollback');
         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 latest = new Map();
+        for (const receipt of manifest.records)
+            latest.set(identityKey(receipt.identity), receipt);
+        const selected = new Map();
+        for (const record of records) {
+            if (completed.has(recordKey(record)))
+                continue;
+            const key = identityKey(record.identity);
+            const receipt = latest.get(key);
+            if (receipt && this.options.compareSourceRevisions) {
+                const order = compareRevisions(this.options.compareSourceRevisions, record.sourceRevision, receipt.sourceRevision);
+                if (order < 0)
+                    continue;
+                if (order === 0) {
+                    if (record.digest !== receipt.contentDigest)
+                        throw revisionConflict(key, record.sourceRevision);
+                    continue;
+                }
+            }
+            const prior = selected.get(key);
+            if (!prior) {
+                selected.set(key, record);
+                continue;
+            }
+            if (!this.options.compareSourceRevisions) {
+                throw new MigrationProtocolError('AIWG_MIGRATION_DUPLICATE_IDENTITY', `snapshot contains multiple records for ${key}`);
+            }
+            const order = compareRevisions(this.options.compareSourceRevisions, record.sourceRevision, prior.sourceRevision);
+            if (order > 0)
+                selected.set(key, record);
+            else if (order === 0 && record.digest !== prior.digest)
+                throw revisionConflict(key, record.sourceRevision);
+        }
+        const pending = [...selected.values()].sort((left, right) => identityKey(left.identity).localeCompare(identityKey(right.identity)));
         const batches = chunk(pending, this.batchSize);
         let next = 0;
         const workers = Array.from({ length: Math.min(this.concurrency, batches.length) }, async () => {
@@ -210,7 +303,7 @@ export class StorageMigrationCoordinator {
                 if (index >= batches.length)
                     return;
                 const batch = batches[index];
-                const mutations = batch.map(record => mutationFor(manifest.migrationId, record));
+                const mutations = batch.map(record => mutationFor(manifest.migrationId, record, latest.get(identityKey(record.identity))?.destinationRevision));
                 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}`);
@@ -242,6 +335,27 @@ export class StorageMigrationCoordinator {
         });
         await Promise.all(workers);
     }
+    async replayChanges(manifest) {
+        if (!this.source.changes) {
+            throw new MigrationProtocolError('AIWG_MIGRATION_CURSOR_UNAVAILABLE', 'online migration requires a source change cursor');
+        }
+        let cursor = manifest.checkpoint.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 ?? page.highWaterMark;
+            manifest.checkpoint = {
+                ...manifest.checkpoint,
+                cursor,
+                highWaterMark: page.highWaterMark,
+                drained: page.records.length === 0 || page.nextCursor === undefined,
+            };
+            await this.persist(manifest);
+            if (manifest.checkpoint.drained)
+                break;
+        }
+    }
     async retry(operation, label) {
         let attempt = 0;
         for (;;) {
@@ -250,7 +364,7 @@ export class StorageMigrationCoordinator {
                 return await operation();
             }
             catch (error) {
-                const retryable = error instanceof MigrationProtocolError && error.retryable;
+                const retryable = isRetryableError(error);
                 if (!retryable)
                     throw error;
                 if (attempt >= this.maxRetries) {
@@ -290,6 +404,10 @@ export function digestRecords(records) {
         .sort((left, right) => identityKey(left.identity).localeCompare(identityKey(right.identity)));
     return sha256(stableStringify(normalized));
 }
+export function digestRecordChunks(records, chunkSize) {
+    const sorted = [...records].sort((left, right) => identityKey(left.identity).localeCompare(identityKey(right.identity)));
+    return chunk(sorted, chunkSize).map(recordsInChunk => digestRecords(recordsInChunk));
+}
 export function approvalDigest(manifest) {
     const copy = structuredClone(manifest);
     delete copy.digests.approval;
@@ -302,6 +420,10 @@ export function validateManifest(manifest, source, destination) {
     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 (!manifest.boundaries?.initial) {
+        throw new MigrationProtocolError('AIWG_MIGRATION_BOUNDARY_MISSING', 'migration manifest has no durable source boundary receipt');
+    }
+    assertBoundaryState(manifest.boundaries.initial, manifest.mode === 'offline' ? 'quiesced' : 'tracking', 'initial');
     if (source && stableStringify(manifest.source) !== stableStringify(source)) {
         throw new MigrationProtocolError('AIWG_MIGRATION_SOURCE_MISMATCH', 'manifest source does not match the active source');
     }
@@ -309,13 +431,29 @@ export function validateManifest(manifest, source, destination) {
         throw new MigrationProtocolError('AIWG_MIGRATION_DESTINATION_MISMATCH', 'manifest destination does not match the active destination');
     }
 }
-function mutationFor(migrationId, record) {
+function assertBoundaryState(boundary, expected, stage) {
+    if (!boundary.boundaryId || !boundary.establishedAt || boundary.state !== expected) {
+        throw new MigrationProtocolError('AIWG_MIGRATION_BOUNDARY_INVALID', `${stage} source boundary must provide a durable ${expected} receipt`);
+    }
+}
+function mutationFor(migrationId, record, expectedRevision) {
     return {
         operation: record.tombstone ? 'delete' : 'upsert',
         record,
         idempotencyKey: sha256(`${migrationId}\0${recordKey(record)}`),
+        ...(expectedRevision === undefined ? {} : { expectedRevision }),
     };
 }
+function revisionConflict(identity, revision) {
+    return new MigrationProtocolError('AIWG_MIGRATION_REVISION_CONFLICT', `source revision ${revision} has conflicting content for ${identity}`);
+}
+function compareRevisions(comparator, left, right) {
+    const result = comparator(left, right);
+    if (!Number.isFinite(result)) {
+        throw new MigrationProtocolError('AIWG_MIGRATION_REVISION_ORDER_INVALID', 'source-revision comparator returned a non-finite result');
+    }
+    return Math.sign(result);
+}
 function recordMap(records) {
     return new Map(records.map(record => [identityKey(record.identity), record]));
 }
@@ -357,11 +495,51 @@ function boundedInteger(raw, fallback, min, max, label) {
     return value;
 }
 function summarizeVerificationFailure(verification) {
-    return `migration parity failed: missing=${verification.missing.length} unexpected=${verification.unexpected.length} corrupt=${verification.corrupt.length} lag=${verification.lag}`;
+    const semanticFailures = Object.values(verification.semantic).filter(check => !check.valid).length;
+    return `migration parity failed: missing=${verification.missing.length} unexpected=${verification.unexpected.length} corrupt=${verification.corrupt.length} chunks=${verification.chunks.valid ? 'valid' : 'invalid'} semantic=${semanticFailures} lag=${verification.lag}`;
+}
+function validateSemanticVerification(verification) {
+    for (const dimension of [
+        'schema', 'constraints', 'countsByType', 'edgeIntegrity', 'queryParity', 'traversalParity',
+    ]) {
+        const check = verification?.[dimension];
+        if (!check || typeof check.valid !== 'boolean' || !Number.isInteger(check.declared) || check.declared < 0 ||
+            !Number.isInteger(check.checked) || check.checked < 0 || check.checked !== check.declared || !Array.isArray(check.failures)) {
+            throw new MigrationProtocolError('AIWG_MIGRATION_SEMANTIC_VERIFICATION_INVALID', `semantic verification is incomplete for ${dimension}`);
+        }
+        if (check.valid !== (check.failures.length === 0)) {
+            throw new MigrationProtocolError('AIWG_MIGRATION_SEMANTIC_VERIFICATION_INVALID', `semantic verification validity disagrees with failures for ${dimension}`);
+        }
+        if (check.evidenceDigest !== undefined && !/^[0-9A-Za-z._:-]+$/.test(check.evidenceDigest)) {
+            throw new MigrationProtocolError('AIWG_MIGRATION_SEMANTIC_VERIFICATION_INVALID', `semantic verification evidence digest is invalid for ${dimension}`);
+        }
+        if (['schema', 'constraints', 'queryParity'].includes(dimension) && check.declared < 1) {
+            throw new MigrationProtocolError('AIWG_MIGRATION_SEMANTIC_VERIFICATION_INVALID', `semantic verification must exercise at least one ${dimension} check`);
+        }
+        if (dimension === 'countsByType') {
+            if (!isCountMap(check.sourceCounts) || !isCountMap(check.destinationCounts)) {
+                throw new MigrationProtocolError('AIWG_MIGRATION_SEMANTIC_VERIFICATION_INVALID', 'countsByType must include non-negative integer source and destination maps');
+            }
+            const declaredTypes = new Set([...Object.keys(check.sourceCounts), ...Object.keys(check.destinationCounts)]).size;
+            if (check.declared !== declaredTypes || (check.valid && stableStringify(check.sourceCounts) !== stableStringify(check.destinationCounts))) {
+                throw new MigrationProtocolError('AIWG_MIGRATION_SEMANTIC_VERIFICATION_INVALID', 'countsByType scope or validity does not match its declared maps');
+            }
+        }
+    }
+}
+function semanticIsValid(verification) {
+    return Object.values(verification).every(check => check.valid);
+}
+function isCountMap(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) &&
+        Object.values(value).every(count => Number.isInteger(count) && count >= 0);
 }
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function isRetryableError(error) {
+    return typeof error === 'object' && error !== null && 'retryable' in error && error.retryable === true;
+}
 async function abortableDelay(ms, signal) {
     if (!signal) {
         await new Promise(resolve => setTimeout(resolve, ms));

package/dist/src/storage/qualification.js

@@ -0,0 +1,171 @@
+import { createHash } from 'node:crypto';
+import { digestRecords } from './migration-protocol.js';
+export const STORAGE_QUALIFICATION_REPORT = 'aiwg.storage-qualification/v1';
+/**
+ * Evidence-producing common gate. Correctness is evaluated before latency is
+ * reported, so an incomplete or corrupt run can never become a benchmark.
+ */
+export async function qualifyStorageBackend(endpoint, options) {
+    if (options.records.length !== options.scope.declaredRecords) {
+        throw new Error('declared record scope does not match the qualification corpus');
+    }
+    const readerCount = bounded(options.scope.readers, 1, 1, 32, 'readers');
+    if (options.scope.operations !== options.records.length + readerCount) {
+        throw new Error('declared operation scope must equal record writes plus concurrent readers');
+    }
+    const now = options.now ?? (() => new Date());
+    const startedAt = now().toISOString();
+    const cpuBefore = process.cpuUsage();
+    const rssBefore = process.memoryUsage().rss;
+    const start = performance.now();
+    const latencies = [];
+    const sideEffects = [];
+    let errors = 0;
+    let retries = 0;
+    const maxRetries = bounded(options.maxRetries, 5, 0, 20, 'maxRetries');
+    const baseBackoffMs = bounded(options.baseBackoffMs, 2, 0, 60_000, 'baseBackoffMs');
+    const batches = distribute(options.records, options.scope.writers);
+    const writes = Promise.all(batches.map(async (records, writer) => {
+        for (const record of records) {
+            const mutation = mutationFor(record, `qualification:${writer}:${record.identity.path}:${record.sourceRevision}`);
+            const operationStart = performance.now();
+            let receipt;
+            let replayed = false;
+            for (let attempt = 0;; attempt += 1) {
+                try {
+                    receipt = await endpoint.commitBatch([mutation]);
+                    break;
+                }
+                catch (error) {
+                    errors += 1;
+                    if (!isRetryable(error) || attempt >= maxRetries) {
+                        sideEffects.push({ operation: `write:${record.identity.path}`, outcome: 'failed' });
+                        throw error;
+                    }
+                    retries += 1;
+                    replayed = true;
+                    if (baseBackoffMs > 0)
+                        await new Promise(resolve => setTimeout(resolve, baseBackoffMs * 2 ** attempt));
+                }
+            }
+            latencies.push(performance.now() - operationStart);
+            sideEffects.push({ operation: `write:${record.identity.path}`, outcome: replayed ? 'replayed' : 'committed', batchId: receipt.batchId });
+        }
+    }));
+    const reads = Promise.all(Array.from({ length: readerCount }, async (_, reader) => {
+        const operationStart = performance.now();
+        try {
+            await endpoint.readAll();
+            latencies.push(performance.now() - operationStart);
+            sideEffects.push({ operation: `read:${reader}`, outcome: 'committed' });
+        }
+        catch (error) {
+            errors += 1;
+            sideEffects.push({ operation: `read:${reader}`, outcome: 'failed' });
+            throw error;
+        }
+    }));
+    await Promise.all([writes, reads]);
+    const expectedDigest = digestRecords(options.records);
+    const observed = [...await endpoint.readAll()];
+    const verification = verifyExactRecords(options.records, observed);
+    const durationMs = Math.max(performance.now() - start, 0.001);
+    const cpu = process.cpuUsage(cpuBefore);
+    const supplied = await options.resourceObservation?.() ?? {};
+    const operations = options.records.length + readerCount;
+    const report = {
+        schemaVersion: STORAGE_QUALIFICATION_REPORT,
+        runId: createHash('sha256').update(`${options.scope.commit}\0${options.scope.backend}\0${startedAt}`).digest('hex'),
+        startedAt,
+        completedAt: now().toISOString(),
+        scope: { ...options.scope, observedRecords: observed.length, observedOperations: sideEffects.length },
+        verification: { ...verification, expectedDigest, observedDigest: digestRecords(observed) },
+        latencyMs: percentiles(latencies),
+        throughputPerSecond: operations / (durationMs / 1000),
+        errors,
+        retries,
+        errorRate: errors / Math.max(operations, 1),
+        retryRate: retries / Math.max(operations, 1),
+        resources: {
+            cpuUserMicros: cpu.user, cpuSystemMicros: cpu.system,
+            rssBytes: Math.max(process.memoryUsage().rss, rssBefore),
+            databaseBytes: resourceMetric(supplied.databaseBytes, 'databaseBytes'),
+            writeAmplification: resourceMetric(supplied.writeAmplification, 'writeAmplification'),
+            walBytes: resourceMetric(supplied.walBytes, 'walBytes'),
+            lockWaits: resourceMetric(supplied.lockWaits, 'lockWaits'),
+            poolSaturation: resourceMetric(supplied.poolSaturation, 'poolSaturation'),
+            migrationMs: resourceMetric(supplied.migrationMs, 'migrationMs'),
+            recoveryMs: resourceMetric(supplied.recoveryMs, 'recoveryMs'),
+            transportOverheadMs: resourceMetric(supplied.transportOverheadMs, 'transportOverheadMs'),
+        },
+        sideEffects: sideEffects.sort((a, b) => a.operation.localeCompare(b.operation)),
+    };
+    if (!report.verification.valid)
+        throw new StorageQualificationError('AIWG_STORAGE_QUALIFICATION_PARITY_FAILED', report);
+    return report;
+}
+export class StorageQualificationError extends Error {
+    code;
+    report;
+    constructor(code, report) {
+        super(`${code}: correctness parity failed; benchmark evidence is invalid`);
+        this.code = code;
+        this.report = report;
+        this.name = 'StorageQualificationError';
+    }
+}
+export function verifyExactRecords(expected, observed) {
+    const key = (record) => `${record.identity.tenant}\0${record.identity.subsystem}\0${record.identity.path}`;
+    const expectedByKey = new Map(expected.map(record => [key(record), record]));
+    const observedByKey = new Map(observed.map(record => [key(record), record]));
+    const missing = [...expectedByKey.keys()].filter(item => !observedByKey.has(item)).sort();
+    const unexpected = [...observedByKey.keys()].filter(item => !expectedByKey.has(item)).sort();
+    const corrupt = [...expectedByKey].filter(([item, record]) => {
+        const candidate = observedByKey.get(item);
+        return candidate !== undefined && digestRecords([record]) !== digestRecords([candidate]);
+    }).map(([item]) => item).sort();
+    return { valid: missing.length === 0 && unexpected.length === 0 && corrupt.length === 0, missing, unexpected, corrupt };
+}
+export function assertCurrentStorageEvidence(report, commit) {
+    if (report.schemaVersion !== STORAGE_QUALIFICATION_REPORT || !report.verification.valid) {
+        throw new Error('storage performance claim lacks a valid qualification record');
+    }
+    if (report.scope.commit !== commit)
+        throw new Error('storage qualification record is stale for the requested commit');
+    if (report.scope.declaredRecords !== report.scope.observedRecords)
+        throw new Error('storage qualification scope is incomplete');
+    if (report.scope.operations !== report.scope.observedOperations)
+        throw new Error('storage qualification operation scope is incomplete');
+}
+function mutationFor(record, idempotencyKey) {
+    return { operation: record.tombstone ? 'delete' : 'upsert', record, idempotencyKey };
+}
+function distribute(records, workers) {
+    if (!Number.isInteger(workers) || workers < 1 || workers > 32)
+        throw new Error('writers must be an integer from 1 through 32');
+    const buckets = Array.from({ length: workers }, () => []);
+    records.forEach((record, index) => buckets[index % workers].push(record));
+    return buckets;
+}
+function percentiles(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    const at = (percentile) => sorted[Math.min(Math.ceil(percentile * sorted.length) - 1, sorted.length - 1)] ?? 0;
+    return { p50: at(0.5), p95: at(0.95), p99: at(0.99) };
+}
+function isRetryable(error) {
+    return typeof error === 'object' && error !== null && 'retryable' in error && error.retryable === true;
+}
+function bounded(value, fallback, min, max, label) {
+    const resolved = value ?? fallback;
+    if (!Number.isInteger(resolved) || resolved < min || resolved > max)
+        throw new Error(`${label} must be an integer from ${min} through ${max}`);
+    return resolved;
+}
+function resourceMetric(value, label) {
+    if (value === undefined || value === null)
+        return null;
+    if (!Number.isFinite(value) || value < 0)
+        throw new Error(`${label} must be a finite non-negative number`);
+    return value;
+}
+//# sourceMappingURL=qualification.js.map