@aiwg/cli 2026.8.26 → 2026.8.28

package/dist/src/ops/cli.js

@@ -11,6 +11,11 @@
  * @implements #544
  */
 import { OpsRegistry } from './registry.js';
+import { appendFile, chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { parse as parseYaml } from 'yaml';
+import { prepareEvidenceForSink, } from '../governance/index.js';
 /**
  * Main CLI entry point for `aiwg ops <subcommand> [args]`
  */
@@ -53,6 +58,9 @@ export async function main(args) {
         case 'adopt':
             await handleAdopt(registry, subArgs);
             break;
+        case 'evidence':
+            await handleEvidence(subArgs);
+            break;
         default:
             printUsage();
             if (subcommand) {
@@ -61,6 +69,91 @@ export async function main(args) {
             break;
     }
 }
+function flagValue(args, name) {
+    const index = args.indexOf(name);
+    if (index === -1)
+        return undefined;
+    const value = args[index + 1];
+    if (!value || value.startsWith('--'))
+        throw new Error(`${name} requires a value`);
+    return value;
+}
+function parseData(source, label) {
+    try {
+        return JSON.parse(source);
+    }
+    catch {
+        try {
+            return parseYaml(source);
+        }
+        catch {
+            throw new Error(`${label} must contain valid JSON or YAML`);
+        }
+    }
+}
+async function readStdin(maxBytes = 16 * 1024 * 1024) {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of process.stdin) {
+        const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += value.length;
+        if (bytes > maxBytes)
+            throw new Error('evidence input exceeds 16 MiB');
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+async function readInput(args) {
+    const inputPath = flagValue(args, '--input');
+    return inputPath ? readFile(resolve(inputPath), 'utf8') : readStdin();
+}
+async function appendBoundaryAudit(cwd, value, configuredPath) {
+    const path = resolve(configuredPath ?? `${cwd}/.aiwg/ops/audit/governance-boundary.jsonl`);
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await appendFile(path, `${JSON.stringify(value)}\n`, { encoding: 'utf8', mode: 0o600 });
+    await chmod(path, 0o600);
+}
+async function writePreparedOutput(pathValue, value) {
+    const path = resolve(pathValue);
+    const temporary = `${path}.tmp-${randomUUID()}`;
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    await rename(temporary, path);
+    await chmod(path, 0o600);
+}
+async function handleEvidence(args) {
+    const action = args[0];
+    if (action !== 'prepare') {
+        throw new Error('Usage: aiwg ops evidence prepare [--input <json-or-yaml>] [--policy <json-or-yaml>] [--output <path>] [--audit <path>]');
+    }
+    const envelope = parseData(await readInput(args), 'evidence input');
+    if (!envelope || typeof envelope !== 'object' || !envelope.artifact || typeof envelope.sinkId !== 'string') {
+        throw new Error('evidence input requires artifact and sinkId');
+    }
+    const policyPath = flagValue(args, '--policy');
+    const policy = policyPath
+        ? parseData(await readFile(resolve(policyPath), 'utf8'), 'governance policy')
+        : undefined;
+    const result = prepareEvidenceForSink({
+        ...envelope,
+        policy,
+    });
+    await appendBoundaryAudit(process.cwd(), result.audit, flagValue(args, '--audit'));
+    const response = result.allowed && result.prepared
+        ? { schemaVersion: 'ops-prepared-evidence.aiwg.io/v1', prepared: result.prepared, audit: result.audit, auditRecorded: true }
+        : { schemaVersion: 'ops-prepared-evidence.aiwg.io/v1', denied: true, audit: result.audit, auditRecorded: true };
+    const outputPath = flagValue(args, '--output');
+    if (outputPath) {
+        if (!result.allowed)
+            throw new Error(`evidence publication denied: ${result.audit.reasonCodes.join(', ')}`);
+        await writePreparedOutput(outputPath, response);
+    }
+    else {
+        process.stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+    }
+    if (!result.allowed)
+        process.exitCode = 2;
+}
 async function handleInit(registry, args) {
     // Parse flags
     let silent = false;
@@ -225,6 +318,7 @@ Subcommands:
   push [--workspace <n>]  Push workspace repos to remote
   discover [root...]      Scan filesystem for orphaned ops-workspace clones
   adopt <path>            Register an existing local clone as a repo entry
+  evidence prepare        Sanitize and policy-gate evidence before publication
 
 Init options:
   --silent                Skip interactive prompts
@@ -251,6 +345,7 @@ Examples:
   aiwg ops push --workspace personal
   aiwg ops discover ~/projects ~/work --max-depth 4
   aiwg ops discover --register --workspace home
+  aiwg ops evidence prepare --input request.yaml --policy .aiwg/ops/governance-policy.yaml
 
 Discover options:
   --max-depth <n>         Max walk depth from each root (default: 3)

package/dist/src/serve/dispatch-router.js

@@ -85,7 +85,7 @@ async function dispatchV2(executor, payload, opts) {
     // discovery dependency to the compatibility path.
     if (clientOpts.protocolPolicy === '0.3') {
         clientOpts.selectedInterface = {
-            url: `${executor.transportEndpoints.rest.replace(/\/+$/, '')}/agents/${encodeURIComponent(a2aInstanceId)}`,
+            url: `${executor.transportEndpoints.rest.replace(/\/+$/, '')}/agents/${encodeURIComponent(a2aInstanceId)}/v1`,
             protocolBinding: 'REST',
             protocolVersion: '0.3',
             preference: 0,

package/dist/src/sessions/repository.js

@@ -1,21 +1,23 @@
-import { createRequire } from 'node:module';
+import { requireFeaturePackage } from '../features/runtime.js';
 import { CandidateReviewReceiptSchema, DeletionReceiptSchema, IntelligenceCandidateSchema, PromotionDependencyDecisionSchema, PromotionReceiptSchema, SessionContractError, sha256, } from './contracts.js';
 import { coverageFromBatchRun, } from './batch-contracts.js';
 import { redactSessionText, sanitizeNativeExtensions } from './policy.js';
 import { deriveSessionAnalytics, } from './analytics.js';
-const require = createRequire(import.meta.url);
 const POLICY_PROVIDER_MIGRATION = 'policy-provider-identity:v2';
 const EVENT_ORIGIN_INTENT_MIGRATION = 'event-origin-intent:v1';
 export class SessionRepository {
     db;
     constructor(path = ':memory:') {
+        let Database;
         try {
-            const Database = require('better-sqlite3');
-            this.db = new Database(path);
+            Database = requireFeaturePackage('better-sqlite3');
         }
-        catch {
-            throw new Error('session SQLite repository requires optional peer dependency better-sqlite3');
+        catch (cause) {
+            throw new Error('session SQLite catalog is unavailable because better-sqlite3 could not be loaded; ' +
+                'run `aiwg features install sqlite`, then retry. If the native build fails, install ' +
+                'Python 3, make, and a C/C++ compiler supported by node-gyp.', { cause });
         }
+        this.db = new Database(path);
         this.db.pragma('foreign_keys = ON');
         this.db.pragma('journal_mode = WAL');
         this.db.pragma('busy_timeout = 5000');

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));