@aiwg/cli 2026.8.26 → 2026.8.27

package/dist/src/artifacts/backends/graphology-backend.js

@@ -11,6 +11,7 @@
  * @source @src/artifacts/graph-backend.ts
  * @tests @test/unit/artifacts/graphology-backend.test.ts
  */
+import { compareGraphIds, pageGraphIds } from '../graph-backend.js';
 import { normalizeEdges } from '../types.js';
 import { loadFeaturePackage } from '../../features/runtime.js';
 /**
@@ -73,7 +74,15 @@ export class GraphologyBackend {
         return this.graph.getNodeAttributes(id);
     }
     nodes() {
-        return this.graph.nodes();
+        return this.graph.nodes().sort(compareGraphIds);
+    }
+    queryNodes(filters) {
+        return this.graph.nodes()
+            .filter((id) => Object.entries(filters).every(([key, value]) => this.graph.getNodeAttribute(id, key) === value))
+            .sort(compareGraphIds);
+    }
+    pageNodes(limit, after) {
+        return pageGraphIds(this.graph.nodes(), limit, after);
     }
     // --- Traversal ---
     neighbors(nodeId, direction, edgeType) {
@@ -98,7 +107,7 @@ export class GraphologyBackend {
             // Add the "other" node
             results.add(src === nodeId ? tgt : src);
         }
-        return [...results];
+        return [...results].sort(compareGraphIds);
     }
     // --- Set operations ---
     intersection(setA, setB) {

package/dist/src/artifacts/backends/json-backend.js

@@ -9,6 +9,7 @@
  * @source @src/artifacts/graph-backend.ts
  * @tests @test/unit/artifacts/graph-backend.test.ts
  */
+import { compareGraphIds, pageGraphIds } from '../graph-backend.js';
 import { normalizeEdges } from '../types.js';
 /**
  * JSON-backed graph using plain objects and JS Set operations.
@@ -52,7 +53,16 @@ export class JsonGraphBackend {
         return this.graph.get(id)?.attrs;
     }
     nodes() {
-        return [...this.graph.keys()];
+        return [...this.graph.keys()].sort(compareGraphIds);
+    }
+    queryNodes(filters) {
+        return [...this.graph]
+            .filter(([, node]) => Object.entries(filters).every(([key, value]) => node.attrs[key] === value))
+            .map(([id]) => id)
+            .sort(compareGraphIds);
+    }
+    pageNodes(limit, after) {
+        return pageGraphIds([...this.graph.keys()], limit, after);
     }
     // --- Traversal ---
     neighbors(nodeId, direction, edgeType) {
@@ -74,7 +84,7 @@ export class JsonGraphBackend {
                 }
             }
         }
-        return [...results];
+        return [...results].sort(compareGraphIds);
     }
     // --- Set operations ---
     intersection(setA, setB) {

package/dist/src/artifacts/backends/sqlite-backend.js

@@ -13,6 +13,7 @@
  * @source @src/artifacts/graph-backend.ts
  * @tests @test/unit/artifacts/sqlite-backend.test.ts
  */
+import { compareGraphIds, pageGraphIds } from '../graph-backend.js';
 import { normalizeEdges } from '../types.js';
 import { requireFeaturePackage } from '../../features/runtime.js';
 const SCHEMA_VERSION = 1;
@@ -131,23 +132,35 @@ export class SqliteGraphBackend {
         return JSON.parse(row.attrs);
     }
     nodes() {
-        return this.db.prepare('SELECT id FROM nodes').all().map((r) => r.id);
+        return this.db.prepare('SELECT id FROM nodes ORDER BY id COLLATE BINARY').all()
+            .map((r) => r.id);
     }
     queryNodes(filters) {
         const clauses = [];
         const values = [];
         if (filters.type !== undefined) {
-            clauses.push('type = ?');
-            values.push(filters.type);
+            if (filters.type === null)
+                clauses.push('type IS NULL');
+            else {
+                clauses.push('type = ?');
+                values.push(filters.type);
+            }
         }
         if (filters.phase !== undefined) {
-            clauses.push('phase = ?');
-            values.push(filters.phase);
+            if (filters.phase === null)
+                clauses.push('phase IS NULL');
+            else {
+                clauses.push('phase = ?');
+                values.push(filters.phase);
+            }
         }
         const where = clauses.length ? `WHERE ${clauses.join(' AND ')}` : '';
-        return this.db.prepare(`SELECT id FROM nodes ${where} ORDER BY id`).all(...values)
+        return this.db.prepare(`SELECT id FROM nodes ${where} ORDER BY id COLLATE BINARY`).all(...values)
             .map((row) => row.id);
     }
+    pageNodes(limit, after) {
+        return pageGraphIds(this.nodes(), limit, after);
+    }
     // --- Traversal ---
     neighbors(nodeId, direction, edgeType) {
         const results = new Set();
@@ -171,7 +184,7 @@ export class SqliteGraphBackend {
             for (const row of rows)
                 results.add(row.target);
         }
-        return [...results];
+        return [...results].sort(compareGraphIds);
     }
     // --- Set operations (native SQL) ---
     intersection(setA, setB) {

package/dist/src/artifacts/graph-backend.js

@@ -10,6 +10,22 @@
  * @source @src/artifacts/types.ts
  * @tests @test/unit/artifacts/graph-backend.test.ts
  */
+/** SQLite BINARY collation and local backends share this UTF-8 byte order. */
+export function compareGraphIds(left, right) {
+    return Buffer.compare(Buffer.from(left, 'utf8'), Buffer.from(right, 'utf8'));
+}
+export function pageGraphIds(ids, limit, after) {
+    if (!Number.isInteger(limit) || limit < 1 || limit > 10_000) {
+        throw new Error('graph page limit must be an integer from 1 through 10000');
+    }
+    const ordered = [...ids].sort(compareGraphIds);
+    const eligible = after === undefined ? ordered : ordered.filter(id => compareGraphIds(id, after) > 0);
+    const nodes = eligible.slice(0, limit);
+    return {
+        nodes,
+        ...(eligible.length > limit && nodes.length ? { nextCursor: nodes[nodes.length - 1] } : {}),
+    };
+}
 /**
  * Create a graph backend instance.
  *

package/dist/src/storage/backends/postgres.js

@@ -387,7 +387,7 @@ async function createPool(options) {
     const Pool = (pg.Pool ?? defaultExport?.Pool);
     if (!Pool)
         throw new PostgresBackendError('AIWG_POSTGRES_DRIVER_INVALID', 'optional pg package does not export Pool');
-    return new Pool({
+    const pool = new Pool({
         connectionString,
         max: bounded(options.maxConnections, DEFAULT_POOL_MAX, 1, 100, 'maxConnections'),
         connectionTimeoutMillis: bounded(options.connectionTimeoutMs, DEFAULT_TIMEOUT_MS, 1, 600_000, 'connectionTimeoutMs'),
@@ -395,6 +395,11 @@ async function createPool(options) {
         application_name: options.applicationName ?? 'aiwg',
         ssl: options.ssl === 'disable' ? false : { rejectUnauthorized: options.ssl === 'verify-full' },
     });
+    // pg emits idle-client failures at pool scope. Registering a listener keeps
+    // server restarts from becoming uncaught process exceptions; failed clients
+    // are evicted by pg and the next backend operation reconnects normally.
+    pool.on?.('error', () => undefined);
+    return pool;
 }
 function isLoopbackPostgresUrl(connectionString) {
     try {

package/dist/src/storage/index.js

@@ -22,7 +22,7 @@ export { ObsidianAdapter } from './backends/obsidian.js';
 export { LogseqAdapter } from './backends/logseq.js';
 export { FortemiAdapter } from './backends/fortemi.js';
 export { STORAGE_BACKEND_CONTRACT, STORAGE_BACKEND_MATRIX, StorageCapabilityError, negotiateStorageCapabilities, } from './backend-contract.js';
-export { STORAGE_MIGRATION_PROTOCOL, MigrationProtocolError, StorageMigrationCoordinator, approvalDigest, digestRecords, validateManifest, } from './migration-protocol.js';
+export { STORAGE_MIGRATION_PROTOCOL, MigrationProtocolError, StorageMigrationCoordinator, approvalDigest, digestRecordChunks, digestRecords, validateManifest, } from './migration-protocol.js';
 export { PostgresStorageBackend, PostgresBackendError, } from './backends/postgres.js';
 export { POSTGRES_SCHEMA_VERSION, POSTGRES_SCHEMA_V1_SQL, inspectPostgresSchema, upgradePostgresSchemaV1, rollbackPostgresSchemaV1, postgresLeastPrivilegeSql, } from './backends/postgres-schema.js';
 export { PostgrestStorageBackend, PostgrestBackendError, } from './backends/postgrest.js';

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

@@ -9,6 +9,10 @@ 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();
@@ -21,7 +25,7 @@ export async function qualifyStorageBackend(endpoint, options) {
     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);
-    await Promise.all(batches.map(async (records, writer) => {
+    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();
@@ -48,19 +52,33 @@ export async function qualifyStorageBackend(endpoint, options) {
             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 = options.resourceObservation?.() ?? {};
-    const operations = options.records.length + options.scope.readers;
+    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 },
+        scope: { ...options.scope, observedRecords: observed.length, observedOperations: sideEffects.length },
         verification: { ...verification, expectedDigest, observedDigest: digestRecords(observed) },
         latencyMs: percentiles(latencies),
         throughputPerSecond: operations / (durationMs / 1000),
@@ -71,7 +89,14 @@ export async function qualifyStorageBackend(endpoint, options) {
         resources: {
             cpuUserMicros: cpu.user, cpuSystemMicros: cpu.system,
             rssBytes: Math.max(process.memoryUsage().rss, rssBefore),
-            ...supplied,
+            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)),
     };
@@ -109,6 +134,8 @@ export function assertCurrentStorageEvidence(report, 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 };
@@ -134,4 +161,11 @@ function bounded(value, fallback, min, max, label) {
         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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.8.26",
+  "version": "2026.8.27",
   "description": "Lightweight AIWG CLI for signed, versioned web-backed resources.",
   "type": "module",
   "license": "MIT",