@ductape/cli 0.2.23 → 0.3.0

package/dist/commands/migration-artifact.d.ts

@@ -0,0 +1,32 @@
+export declare const MIGRATION_ARTIFACT_SCHEMAS: {
+    version: number;
+    artifacts: {
+        $schema: string;
+        title: string;
+        type: string;
+        required: string[];
+        properties: {
+            version: {
+                const: number;
+            };
+            artifact_kind: {
+                const: string;
+            };
+        };
+        additionalProperties: boolean;
+    }[];
+};
+export declare function runMigrationArtifactValidate(opts: {
+    file: string;
+    json?: boolean;
+}): void;
+export declare function runMigrationArtifactRecover(opts: {
+    file: string;
+    json?: boolean;
+}): void;
+export declare function runMigrationArtifactMigrate(opts: {
+    file: string;
+    output: string;
+    json?: boolean;
+}): void;
+export declare function runMigrationArtifactSchemas(json?: boolean): void;

package/dist/commands/migration-artifact.js

@@ -0,0 +1,48 @@
+import path from 'node:path';
+import { printJson } from '../lib/output.js';
+import { migrateMigrationJson, readMigrationJson, recoverMigrationJson, } from '../lib/migration-artifact.js';
+export const MIGRATION_ARTIFACT_SCHEMAS = {
+    version: 1,
+    artifacts: [
+        'ai_migration_review_ledger',
+        'ductape_migration_slice',
+        'ductape_migration_portfolio',
+        'ductape_migration_partition_proposal',
+        'ductape_migration_e2e_baseline',
+        'ductape_migration_generated_vendor_evidence',
+        'ductape_migration_assurance',
+        'ductape_migration_verification_matrix',
+        'ductape_database_baseline',
+        'ductape_database_data',
+        'ductape_database_cutover',
+        'ductape_review_ledger_signature',
+    ].map((artifact_kind) => ({
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        title: artifact_kind,
+        type: 'object',
+        required: ['version', 'artifact_kind'],
+        properties: {
+            version: { const: 1 },
+            artifact_kind: { const: artifact_kind },
+        },
+        additionalProperties: true,
+    })),
+};
+export function runMigrationArtifactValidate(opts) {
+    const value = readMigrationJson(opts.file);
+    const schema = MIGRATION_ARTIFACT_SCHEMAS.artifacts.find((candidate) => candidate.properties.artifact_kind.const === value.artifact_kind);
+    if (!schema || value.version !== 1)
+        throw new Error('[ARTIFACT_VERSION_UNSUPPORTED] Unknown artifact kind or version.');
+    printJson({ file: path.resolve(opts.file), valid: true, artifact_kind: value.artifact_kind, version: value.version }, Boolean(opts.json));
+}
+export function runMigrationArtifactRecover(opts) {
+    recoverMigrationJson(opts.file);
+    printJson({ file: path.resolve(opts.file), recovered: true }, Boolean(opts.json));
+}
+export function runMigrationArtifactMigrate(opts) {
+    migrateMigrationJson(opts.file, opts.output);
+    printJson({ source: path.resolve(opts.file), output: path.resolve(opts.output), version: 1 }, Boolean(opts.json));
+}
+export function runMigrationArtifactSchemas(json) {
+    printJson(MIGRATION_ARTIFACT_SCHEMAS, Boolean(json));
+}

package/dist/commands/migration-assurance.d.ts

@@ -0,0 +1,10 @@
+export declare function validateMigrationAssurance(file: string): {
+    file: string;
+    ready: boolean;
+    blockers: string[];
+};
+export declare function runMigrationAssuranceValidate(opts: {
+    file: string;
+    strict?: boolean;
+    json?: boolean;
+}): void;

package/dist/commands/migration-assurance.js

@@ -0,0 +1,120 @@
+import path from 'node:path';
+import { printJson } from '../lib/output.js';
+import { readMigrationJson } from '../lib/migration-artifact.js';
+function read(file) {
+    return readMigrationJson(file);
+}
+function evidenceComplete(value) {
+    const item = value;
+    return Boolean(item?.requirement?.trim() && item.evidence?.trim() &&
+        Array.isArray(item.tests) && item.tests.length &&
+        item.tests.every((test) => typeof test === 'string' && test.trim()));
+}
+function requireEvidenceArray(blockers, label, values) {
+    if (!Array.isArray(values) || values.length === 0) {
+        blockers.push(`${label}: at least one evidence record is required`);
+        return;
+    }
+    values.forEach((value, index) => {
+        if (!evidenceComplete(value))
+            blockers.push(`${label}[${index}]: requirement, evidence, and tests are required`);
+    });
+}
+const requiredSession = [
+    'frontend_to_backend', 'backend_to_event', 'event_to_feature', 'scheduled_work',
+    'refresh', 'revocation', 'logout', 'account_switching', 'expiry', 'actor_audit_not_authorization',
+];
+const requiredFeature = [
+    'duplicate_delivery', 'signal_handling', 'compensation', 'restart_recovery',
+    'layered_retry_budget', 'fallback', 'quota', 'health_check',
+];
+const requiredComponents = {
+    graph: ['schema', 'edges', 'indexes', 'traversal', 'reconciliation'],
+    vector: ['dimensions', 'metric', 'embedding_version', 'metadata_schema', 'batching', 'quality'],
+    storage: ['object_keys', 'metadata', 'acl', 'encryption', 'retention', 'multipart', 'checksums'],
+    cache: ['keys', 'ttl', 'invalidation', 'stampede', 'consistency', 'fallback'],
+    notifications: ['templates', 'channels', 'providers', 'suppression', 'retry', 'delivery', 'privacy'],
+    analytics: ['event_schema', 'identity', 'consent', 'masking', 'delivery', 'dashboard_parity'],
+};
+function requireNamedRequirements(blockers, label, values, required) {
+    requireEvidenceArray(blockers, label, values);
+    const names = new Set(Array.isArray(values) ? values.map((value) => value?.requirement) : []);
+    for (const requirement of required) {
+        if (!names.has(requirement))
+            blockers.push(`${label}: missing requirement ${requirement}`);
+    }
+}
+export function validateMigrationAssurance(file) {
+    const resolved = path.resolve(file);
+    const value = read(resolved);
+    if (value.artifact_kind !== 'ductape_migration_assurance' || value.version !== 1) {
+        throw new Error('Invalid migration assurance artifact version.');
+    }
+    const blockers = [];
+    requireNamedRequirements(blockers, 'session_flows', value.session_flows, requiredSession);
+    requireNamedRequirements(blockers, 'feature_resilience', value.feature_resilience, requiredFeature);
+    requireEvidenceArray(blockers, 'third_party_calls', value.third_party_calls);
+    for (const [index, call] of (value.third_party_calls ?? []).entries()) {
+        for (const field of [
+            'call_path', 'client', 'base_url', 'auth', 'headers', 'timeout', 'retries',
+            'pagination', 'rate_limits', 'error_normalization', 'webhook_replay',
+        ]) {
+            if (!String(call?.[field] ?? '').trim())
+                blockers.push(`third_party_calls[${index}].${field}: required`);
+        }
+        if (!Array.isArray(call.wrapper_chain) || !call.wrapper_chain.length) {
+            blockers.push(`third_party_calls[${index}].wrapper_chain: at least one inspected call site is required`);
+        }
+    }
+    for (const [component, requirements] of Object.entries(requiredComponents)) {
+        requireNamedRequirements(blockers, `components.${component}`, value.components?.[component], requirements);
+    }
+    requireEvidenceArray(blockers, 'provider_migrations', value.provider_migrations);
+    for (const language of ['typescript', 'go', 'java', 'dotnet']) {
+        requireEvidenceArray(blockers, `runtime.procedures.${language}`, value.runtime?.procedures?.[language]);
+    }
+    for (const kind of ['request', 'query', 'event', 'feature', 'external_effect']) {
+        requireEvidenceArray(blockers, `runtime.correlations.${kind}`, value.runtime?.correlations?.[kind]);
+    }
+    for (const concern of [
+        'trace_log_compatibility', 'load_concurrency', 'lifecycle_recovery',
+        'redaction', 'monitoring_alerts',
+    ]) {
+        requireEvidenceArray(blockers, `runtime.${concern}`, value.runtime?.[concern]);
+    }
+    const matrices = new Map((value.sdk_matrix ?? []).map((entry) => [entry.language, entry]));
+    for (const language of ['typescript', 'go', 'java', 'dotnet']) {
+        const matrix = matrices.get(language);
+        if (!matrix) {
+            blockers.push(`sdk_matrix: missing ${language}`);
+            continue;
+        }
+        if (!matrix.package?.trim() || !matrix.version?.trim() || !matrix.unsupported_policy?.trim()) {
+            blockers.push(`sdk_matrix.${language}: package, version, and unsupported_policy are required`);
+        }
+        for (const field of ['lifecycle_requirements', 'error_mapping', 'examples', 'anti_patterns']) {
+            if (!Array.isArray(matrix[field]) || !matrix[field].length) {
+                blockers.push(`sdk_matrix.${language}.${field}: at least one entry is required`);
+            }
+        }
+        if (!Array.isArray(matrix.capabilities) || !matrix.capabilities.length) {
+            blockers.push(`sdk_matrix.${language}.capabilities: at least one capability is required`);
+        }
+        else {
+            matrix.capabilities.forEach((capability, index) => {
+                if (!capability.name?.trim() || !capability.installed_evidence?.trim() ||
+                    !Array.isArray(capability.parity_tests) || !capability.parity_tests.length) {
+                    blockers.push(`sdk_matrix.${language}.capabilities[${index}]: installed evidence and parity tests are required`);
+                }
+            });
+        }
+    }
+    return { file: resolved, ready: blockers.length === 0, blockers };
+}
+export function runMigrationAssuranceValidate(opts) {
+    const result = validateMigrationAssurance(opts.file);
+    printJson(result, Boolean(opts.json));
+    if (opts.strict && !result.ready) {
+        throw new Error('Migration assurance is not ready: resolve every reported blocker.');
+    }
+}

package/dist/commands/migration-database.d.ts

@@ -0,0 +1,21 @@
+export declare function initDatabaseMigration(opts: {
+    definition: string;
+    output: string;
+}): {
+    output: string;
+};
+export declare function validateDatabaseMigration(directory: string): {
+    directory: string;
+    ready: boolean;
+    blockers: string[];
+};
+export declare function runMigrationDatabaseInit(opts: {
+    definition: string;
+    output: string;
+    json?: boolean;
+}): void;
+export declare function runMigrationDatabaseValidate(opts: {
+    directory: string;
+    strict?: boolean;
+    json?: boolean;
+}): void;

package/dist/commands/migration-database.js

@@ -0,0 +1,162 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { printJson } from '../lib/output.js';
+import { readMigrationJson, writeMigrationJson } from '../lib/migration-artifact.js';
+const REQUIRED = {
+    baseline: ['database_tag', 'owners', 'providers', 'code_schema_evidence', 'migration_history_evidence', 'applied_history_evidence', 'live_snd_schema_evidence', 'proposed_schema_evidence', 'drift', 'objects', 'security', 'topology', 'compatibility', 'performance_baseline'],
+    data: ['transformations', 'batching', 'checkpoints', 'idempotency', 'resume_strategy', 'validation', 'reconciliation', 'failure_recovery', 'pii_controls', 'retention', 'seed_data'],
+    cutover: ['phases', 'expand', 'backfill', 'dual_compatibility', 'contract', 'deployment_order', 'migration_locking', 'backup', 'restore_test', 'rollback', 'irreversible_changes', 'monitoring', 'reconciliation', 'approval'],
+};
+function read(file) { return readMigrationJson(file); }
+function missing(value, keys) {
+    return keys.filter(k => value[k] == null || value[k] === '' || (Array.isArray(value[k]) && !value[k].length));
+}
+function digest(file) {
+    return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+function object(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+function text(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+export function initDatabaseMigration(opts) {
+    const d = read(path.resolve(opts.definition));
+    const out = path.resolve(opts.output);
+    fs.mkdirSync(out, { recursive: true });
+    for (const name of ['baseline', 'data', 'cutover']) {
+        if (!d[name] || typeof d[name] !== 'object')
+            throw new Error(`Definition requires ${name}.`);
+        writeMigrationJson(path.join(out, `database-${name}.json`), { version: 1, artifact_kind: `ductape_database_${name}`, ...d[name] }, { createOnly: true });
+    }
+    return { output: out };
+}
+export function validateDatabaseMigration(directory) {
+    const dir = path.resolve(directory);
+    const blockers = [];
+    const artifacts = {};
+    for (const name of ['baseline', 'data', 'cutover']) {
+        const file = path.join(dir, `database-${name}.json`);
+        if (!fs.existsSync(file)) {
+            blockers.push(`${name}: artifact missing`);
+            continue;
+        }
+        const artifact = read(file);
+        artifacts[name] = artifact;
+        if (artifact.version !== 1 || artifact.artifact_kind !== `ductape_database_${name}`) {
+            blockers.push(`${name}: unsupported artifact version or kind`);
+        }
+        for (const field of missing(artifact, REQUIRED[name]))
+            blockers.push(`${name}.${field}: evidence required`);
+        if (!text(artifact.migration_id))
+            blockers.push(`${name}.migration_id: required for cross-artifact consistency`);
+    }
+    const baseline = artifacts.baseline;
+    if (baseline) {
+        if (!text(baseline.database_tag) || !Array.isArray(baseline.owners) || !baseline.owners.every(text) ||
+            !Array.isArray(baseline.providers) || !baseline.providers.every((provider) => object(provider) && text(provider.provider) && text(provider.environment) && text(provider.evidence))) {
+            blockers.push('baseline: database_tag, owners, and typed provider environment evidence are required');
+        }
+        const snapshots = baseline.schema_snapshots;
+        const snapshotKinds = new Set();
+        if (!Array.isArray(snapshots) || !snapshots.length) {
+            blockers.push('baseline.schema_snapshots: typed schema provenance is required');
+        }
+        else {
+            for (const [index, snapshot] of snapshots.entries()) {
+                if (!object(snapshot) || !text(snapshot.kind) || !text(snapshot.database_tag) ||
+                    !text(snapshot.structure_hash) || !text(snapshot.source_file) || !text(snapshot.checksum) ||
+                    !text(snapshot.captured_at) || !text(snapshot.evidence)) {
+                    blockers.push(`baseline.schema_snapshots[${index}]: kind, database_tag, structure hash, source checksum, timestamp, and evidence are required`);
+                    continue;
+                }
+                snapshotKinds.add(snapshot.kind);
+                const sourceFile = path.resolve(snapshot.source_file);
+                if (!fs.existsSync(sourceFile) || digest(sourceFile) !== snapshot.checksum) {
+                    blockers.push(`baseline.schema_snapshots[${index}]: source evidence is stale or missing`);
+                }
+                if (snapshot.database_tag !== baseline.database_tag) {
+                    blockers.push(`baseline.schema_snapshots[${index}]: database_tag mismatch`);
+                }
+            }
+            for (const kind of ['code', 'migration', 'applied', 'live', 'proposed']) {
+                if (!snapshotKinds.has(kind))
+                    blockers.push(`baseline.schema_snapshots: missing ${kind} structure`);
+            }
+        }
+        const comparison = baseline.structural_comparison;
+        if (!object(comparison) || !['matched', 'approved_differences'].includes(String(comparison.status)) ||
+            !Array.isArray(comparison.differences) || !text(comparison.evidence) ||
+            (comparison.status === 'approved_differences' && !comparison.differences.length)) {
+            blockers.push('baseline.structural_comparison: matched or evidenced approved differences are required');
+        }
+    }
+    const data = artifacts.data;
+    if (data) {
+        if (!Array.isArray(data.transformations) || !data.transformations.length) {
+            blockers.push('data.transformations: at least one versioned source/target mapping is required');
+        }
+        else {
+            for (const [index, transformation] of data.transformations.entries()) {
+                if (!object(transformation) || !text(transformation.id) || !text(transformation.version) ||
+                    !text(transformation.source) || !text(transformation.target) ||
+                    !Array.isArray(transformation.field_mappings) || !transformation.field_mappings.length ||
+                    !transformation.field_mappings.every((mapping) => object(mapping) && text(mapping.source) && text(mapping.target) && text(mapping.transformation))) {
+                    blockers.push(`data.transformations[${index}]: versioned source/target field mappings are required`);
+                }
+            }
+        }
+        const batching = data.batching;
+        if (!object(batching) || !Number.isInteger(batching.batch_size) || Number(batching.batch_size) <= 0 ||
+            !Number.isInteger(batching.max_concurrency) || Number(batching.max_concurrency) <= 0 ||
+            !Number.isFinite(batching.memory_limit_mb) || Number(batching.memory_limit_mb) <= 0 ||
+            !Number.isFinite(batching.timeout_ms) || Number(batching.timeout_ms) <= 0) {
+            blockers.push('data.batching: positive batch_size, max_concurrency, memory_limit_mb, and timeout_ms are required');
+        }
+        const checkpoints = data.checkpoints;
+        if (!object(checkpoints) || !text(checkpoints.store) || !text(checkpoints.key) ||
+            checkpoints.atomic !== true || !text(checkpoints.replay_test)) {
+            blockers.push('data.checkpoints: persistent store, key, atomic writes, and replay test evidence are required');
+        }
+    }
+    const cutover = artifacts.cutover;
+    if (cutover) {
+        const phases = cutover.phases;
+        if (!Array.isArray(phases) || !phases.length) {
+            blockers.push('cutover.phases: ordered phases are required');
+        }
+        else {
+            const ids = new Set(phases.filter(object).map((phase) => phase.id));
+            const orders = phases.filter(object).map((phase) => Number(phase.order));
+            if (new Set(orders).size !== orders.length || orders.some((order) => !Number.isInteger(order) || order < 1)) {
+                blockers.push('cutover.phases: unique positive order values are required');
+            }
+            for (const [index, phase] of phases.entries()) {
+                if (!object(phase) || !text(phase.id) || !Array.isArray(phase.prerequisites) ||
+                    !phase.prerequisites.every((required) => ids.has(required))) {
+                    blockers.push(`cutover.phases[${index}]: id and existing prerequisites are required`);
+                }
+            }
+        }
+    }
+    const ids = ['baseline', 'data', 'cutover'].map((name) => artifacts[name]?.migration_id);
+    if (ids.every(text) && new Set(ids).size !== 1)
+        blockers.push('database artifacts use different migration_id values');
+    if (baseline && data && cutover) {
+        for (const [name, artifact] of [['data', data], ['cutover', cutover]]) {
+            if (artifact.database_tag !== baseline.database_tag)
+                blockers.push(`${name}.database_tag does not match baseline`);
+        }
+    }
+    return { directory: dir, ready: !blockers.length, blockers };
+}
+export function runMigrationDatabaseInit(opts) {
+    printJson(initDatabaseMigration(opts), Boolean(opts.json));
+}
+export function runMigrationDatabaseValidate(opts) {
+    const r = validateDatabaseMigration(opts.directory);
+    printJson(r, Boolean(opts.json));
+    if (opts.strict && !r.ready)
+        throw new Error('Database migration is not ready: resolve every reported blocker.');
+}

package/dist/commands/migration-e2e.d.ts

@@ -0,0 +1,68 @@
+interface E2EDefinition {
+    command: string;
+    suite_files: string[];
+    baseline: {
+        status: 'passed' | 'failed';
+        evidence: string[];
+        environment: string;
+    };
+}
+interface FinalEvidence {
+    command: string;
+    status: 'passed' | 'failed';
+    evidence: string[];
+    environment: string;
+    suite_root: string;
+}
+interface E2EManifest {
+    version: 1;
+    artifact_kind: 'ductape_migration_e2e_baseline';
+    source: string;
+    created_at: string;
+    command: string;
+    suite: Array<{
+        file: string;
+        checksum: string;
+    }>;
+    baseline: E2EDefinition['baseline'];
+    final: (FinalEvidence & {
+        recorded_at: string;
+    }) | null;
+}
+export declare function initializeMigrationE2E(opts: {
+    source: string;
+    definition: string;
+    output?: string;
+}): {
+    path: string;
+    manifest: E2EManifest;
+};
+export declare function recordMigrationE2EFinal(manifestFile: string, evidenceFile: string): E2EManifest;
+export declare function validateMigrationE2E(manifestFile: string): {
+    manifest: string;
+    ready: boolean;
+    suite_files: number;
+    blockers: string[];
+};
+export declare function validateMigrationE2EBaseline(manifestFile: string): {
+    manifest: string;
+    ready: boolean;
+    blockers: string[];
+};
+export declare function runMigrationE2EInit(opts: {
+    source: string;
+    definition: string;
+    output?: string;
+    json?: boolean;
+}): void;
+export declare function runMigrationE2EFinal(opts: {
+    manifest: string;
+    evidence: string;
+    json?: boolean;
+}): void;
+export declare function runMigrationE2EValidate(opts: {
+    manifest: string;
+    strict?: boolean;
+    json?: boolean;
+}): void;
+export {};

package/dist/commands/migration-e2e.js

@@ -0,0 +1,189 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { printJson } from '../lib/output.js';
+import { readMigrationJson, writeMigrationJson } from '../lib/migration-artifact.js';
+function readJson(file) {
+    return readMigrationJson(file);
+}
+function checksum(file) {
+    return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+function relativeFile(source, file) {
+    if (!file || path.isAbsolute(file))
+        throw new Error(`E2E suite file must be repository-relative: ${file}`);
+    const normalized = path.normalize(file).replaceAll('\\', '/');
+    if (normalized === '..' || normalized.startsWith('../')) {
+        throw new Error(`E2E suite file escapes the source repository: ${file}`);
+    }
+    const resolved = path.resolve(source, normalized);
+    if (!fs.statSync(resolved).isFile())
+        throw new Error(`E2E suite file does not exist: ${normalized}`);
+    return normalized;
+}
+function requireEvidence(value, label) {
+    if (!value.command?.trim())
+        throw new Error(`${label} command is required.`);
+    if (value.status !== 'passed')
+        throw new Error(`${label} must have passed before it can be recorded.`);
+    if (!value.environment?.trim())
+        throw new Error(`${label} environment evidence is required.`);
+    if (!Array.isArray(value.evidence) || value.evidence.length === 0 ||
+        value.evidence.some((item) => !item?.trim())) {
+        throw new Error(`${label} requires at least one non-empty evidence entry.`);
+    }
+}
+export function initializeMigrationE2E(opts) {
+    const source = path.resolve(opts.source);
+    if (!fs.statSync(source).isDirectory())
+        throw new Error(`Migration source is not a directory: ${source}`);
+    const definition = readJson(path.resolve(opts.definition));
+    requireEvidence({ command: definition.command, ...definition.baseline }, 'Baseline E2E run');
+    if (!Array.isArray(definition.suite_files) || definition.suite_files.length === 0) {
+        throw new Error('Baseline E2E suite_files must contain at least one test or fixture.');
+    }
+    const files = [...new Set(definition.suite_files.map((file) => relativeFile(source, file)))].sort();
+    if (files.length !== definition.suite_files.length)
+        throw new Error('Baseline E2E suite_files contains duplicates.');
+    const output = path.resolve(opts.output ?? path.join(source, 'ductape', 'migration-guidance', 'e2e-baseline.json'));
+    if (fs.existsSync(output))
+        throw new Error(`Migration E2E baseline already exists: ${output}`);
+    const manifest = {
+        version: 1,
+        artifact_kind: 'ductape_migration_e2e_baseline',
+        source,
+        created_at: new Date().toISOString(),
+        command: definition.command,
+        suite: files.map((file) => ({ file, checksum: checksum(path.join(source, file)) })),
+        baseline: definition.baseline,
+        final: null,
+    };
+    fs.mkdirSync(path.dirname(output), { recursive: true });
+    writeMigrationJson(output, manifest, { createOnly: true });
+    return { path: output, manifest };
+}
+export function recordMigrationE2EFinal(manifestFile, evidenceFile) {
+    const resolved = path.resolve(manifestFile);
+    const manifest = readJson(resolved);
+    if (manifest.artifact_kind !== 'ductape_migration_e2e_baseline') {
+        throw new Error('Invalid migration E2E baseline manifest.');
+    }
+    if (manifest.final)
+        throw new Error('Final E2E evidence is already recorded.');
+    const evidence = readJson(path.resolve(evidenceFile));
+    requireEvidence(evidence, 'Final E2E run');
+    if (evidence.command !== manifest.command) {
+        throw new Error('Final E2E command must exactly match the original baseline command.');
+    }
+    if (!evidence.suite_root?.trim() || !path.isAbsolute(evidence.suite_root) ||
+        !fs.existsSync(evidence.suite_root) || !fs.statSync(evidence.suite_root).isDirectory()) {
+        throw new Error('Final E2E suite_root must be an existing absolute migrated-codebase directory.');
+    }
+    const changed = manifest.suite.filter(({ file, checksum: expected }) => {
+        try {
+            return checksum(path.join(manifest.source, file)) !== expected;
+        }
+        catch {
+            return true;
+        }
+    });
+    if (changed.length) {
+        throw new Error(`Original E2E baseline changed or is missing: ${changed.map((item) => item.file).join(', ')}`);
+    }
+    const migratedMismatch = manifest.suite.filter(({ file, checksum: expected }) => {
+        try {
+            return checksum(path.join(evidence.suite_root, file)) !== expected;
+        }
+        catch {
+            return true;
+        }
+    });
+    if (migratedMismatch.length) {
+        throw new Error(`Migrated codebase is not using the original E2E suite: ${migratedMismatch.map((item) => item.file).join(', ')}`);
+    }
+    manifest.final = { ...evidence, recorded_at: new Date().toISOString() };
+    writeMigrationJson(resolved, manifest, { backup: true });
+    return manifest;
+}
+export function validateMigrationE2E(manifestFile) {
+    const resolved = path.resolve(manifestFile);
+    const manifest = readJson(resolved);
+    if (manifest.artifact_kind !== 'ductape_migration_e2e_baseline') {
+        throw new Error('Invalid migration E2E baseline manifest.');
+    }
+    const blockers = [];
+    if (!manifest.suite?.length)
+        blockers.push('original E2E suite is empty');
+    for (const item of manifest.suite ?? []) {
+        try {
+            if (checksum(path.join(manifest.source, item.file)) !== item.checksum) {
+                blockers.push(`${item.file}: original baseline checksum changed`);
+            }
+        }
+        catch {
+            blockers.push(`${item.file}: original baseline file is missing`);
+        }
+    }
+    if (manifest.baseline?.status !== 'passed' || !manifest.baseline.evidence?.length) {
+        blockers.push('passing baseline E2E evidence is missing');
+    }
+    if (!manifest.final)
+        blockers.push('final run against the original E2E suite is missing');
+    else {
+        if (manifest.final.command !== manifest.command)
+            blockers.push('final command differs from baseline command');
+        if (manifest.final.status !== 'passed' || !manifest.final.evidence?.length) {
+            blockers.push('passing final E2E evidence is missing');
+        }
+        for (const item of manifest.suite ?? []) {
+            try {
+                if (checksum(path.join(manifest.final.suite_root, item.file)) !== item.checksum) {
+                    blockers.push(`${item.file}: migrated suite differs from original baseline`);
+                }
+            }
+            catch {
+                blockers.push(`${item.file}: migrated suite file is missing`);
+            }
+        }
+    }
+    return { manifest: resolved, ready: blockers.length === 0, suite_files: manifest.suite?.length ?? 0, blockers };
+}
+export function validateMigrationE2EBaseline(manifestFile) {
+    const resolved = path.resolve(manifestFile);
+    const manifest = readJson(resolved);
+    if (manifest.artifact_kind !== 'ductape_migration_e2e_baseline') {
+        throw new Error('Invalid migration E2E baseline manifest.');
+    }
+    const blockers = [];
+    if (!manifest.suite?.length)
+        blockers.push('original E2E suite is empty');
+    for (const item of manifest.suite ?? []) {
+        try {
+            if (checksum(path.join(manifest.source, item.file)) !== item.checksum) {
+                blockers.push(`${item.file}: original baseline checksum changed`);
+            }
+        }
+        catch {
+            blockers.push(`${item.file}: original baseline file is missing`);
+        }
+    }
+    if (manifest.baseline?.status !== 'passed' || !manifest.baseline.evidence?.length) {
+        blockers.push('passing baseline E2E evidence is missing');
+    }
+    return { manifest: resolved, ready: blockers.length === 0, blockers };
+}
+export function runMigrationE2EInit(opts) {
+    const result = initializeMigrationE2E(opts);
+    printJson({ path: result.path, suite_files: result.manifest.suite.length }, Boolean(opts.json));
+}
+export function runMigrationE2EFinal(opts) {
+    const manifest = recordMigrationE2EFinal(opts.manifest, opts.evidence);
+    printJson({ manifest: path.resolve(opts.manifest), final_status: manifest.final?.status }, Boolean(opts.json));
+}
+export function runMigrationE2EValidate(opts) {
+    const result = validateMigrationE2E(opts.manifest);
+    printJson(result, Boolean(opts.json));
+    if (opts.strict && !result.ready) {
+        throw new Error('Migration E2E gate is not ready: resolve every reported blocker.');
+    }
+}