@ductape/cli 0.2.23 → 0.3.1

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

@@ -0,0 +1,28 @@
+type JsonSchema = {
+    $schema: string;
+    title: string;
+    type: 'object';
+    required: string[];
+    properties: Record<string, unknown>;
+    additionalProperties: boolean;
+};
+export declare const MIGRATION_ARTIFACT_SCHEMAS: {
+    version: number;
+    artifacts: JsonSchema[];
+    definitions: JsonSchema[];
+};
+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;
+export {};

package/dist/commands/migration-artifact.js

@@ -0,0 +1,101 @@
+import path from 'node:path';
+import { printJson } from '../lib/output.js';
+import { migrateMigrationJson, readMigrationJson, recoverMigrationJson, } from '../lib/migration-artifact.js';
+const objectSchema = (title, required, properties = {}) => ({
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    title,
+    type: 'object',
+    required,
+    properties,
+    additionalProperties: true,
+});
+const artifact = (kind, required) => objectSchema(kind, ['version', 'artifact_kind', ...required], { version: { const: 1 }, artifact_kind: { const: kind } });
+export const MIGRATION_ARTIFACT_SCHEMAS = {
+    version: 2,
+    artifacts: [
+        artifact('ai_review_bootstrap', ['authority', 'source', 'mode', 'destination', 'review_queue']),
+        artifact('ai_migration_review_ledger', ['source', 'entries']),
+        artifact('ductape_migration_slice', ['tag', 'name', 'ledger', 'files', 'surfaces', 'product_boundary']),
+        artifact('ductape_migration_portfolio', ['ledger', 'partitions', 'slices', 'cross_slice_contracts']),
+        artifact('ductape_migration_partition_proposal', ['authority', 'ledger', 'limits', 'partitions']),
+        artifact('ductape_migration_e2e_baseline', ['source', 'created_at', 'command', 'suite', 'baseline', 'final']),
+        artifact('ductape_migration_generated_vendor_evidence', ['analysis', 'generated', 'vendor']),
+        artifact('ductape_migration_assurance', [
+            'session_flows', 'feature_resilience', 'third_party_calls', 'components',
+            'provider_migrations', 'runtime', 'sdk_matrix',
+        ]),
+        artifact('ductape_migration_verification_matrix', ['categories']),
+        artifact('ductape_database_baseline', [
+            'migration_id', 'database_tag', 'owners', 'providers', 'schema_snapshots',
+            'structural_comparison',
+        ]),
+        artifact('ductape_database_data', [
+            'migration_id', 'transformations', 'batching', 'checkpoints', 'idempotency',
+            'resume_strategy', 'validation', 'reconciliation',
+        ]),
+        artifact('ductape_database_cutover', [
+            'migration_id', 'phases', 'expand', 'backfill', 'dual_compatibility', 'contract',
+            'deployment_order', 'migration_locking', 'backup', 'restore_test', 'rollback',
+        ]),
+        artifact('ductape_review_ledger_signature', [
+            'ledger', 'ledger_sha256', 'algorithm', 'key_id', 'signature', 'signed_at',
+        ]),
+        artifact('ductape_service_product_map', ['analysis', 'mappings', 'assets', 'promotions']),
+        artifact('ductape_secret_migration_map', ['analysis', 'classifications']),
+        artifact('ductape_sdk_capability_matrix', ['authority', 'unsupported_policy', 'sdks']),
+    ],
+    definitions: [
+        objectSchema('migration_e2e_definition', ['command', 'suite_files', 'baseline']),
+        objectSchema('migration_e2e_final_evidence', ['command', 'status', 'evidence', 'environment', 'suite_root']),
+        objectSchema('migration_slice_definition', [
+            'surfaces', 'product_boundary', 'sdk_capabilities', 'interface_contracts',
+            'functional_requirements', 'operational_requirements', 'parity_evidence',
+            'frontend_parity', 'required_assets', 'tests', 'failure_tests', 'runtime_evidence',
+            'smoke_checks', 'cutover_conditions', 'rollback_conditions', 'deployment_cutover',
+        ]),
+        objectSchema('migration_portfolio_definition', ['partitions', 'slices', 'cross_slice_contracts']),
+        objectSchema('migration_database_definition', ['baseline', 'data', 'cutover']),
+        objectSchema('migration_product_map_definition', ['mappings', 'assets', 'promotions']),
+        objectSchema('migration_secret_map_definition', ['classifications']),
+        objectSchema('migration_generated_vendor_definition', ['generated', 'vendor']),
+        objectSchema('migration_review_record_definition', [
+            'purpose', 'dependencies', 'interfaces', 'functional_parity_requirements',
+            'operational_parity_requirements', 'findings',
+        ]),
+        objectSchema('migration_assurance_definition', [
+            'version', 'artifact_kind', 'session_flows', 'feature_resilience', 'third_party_calls',
+            'components', 'provider_migrations', 'runtime', 'sdk_matrix',
+        ]),
+        objectSchema('migration_verification_definition', ['version', 'artifact_kind', 'categories']),
+        objectSchema('migration_environment_inventory', ['environments']),
+    ],
+};
+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.');
+    }
+    const missing = schema.required.filter((field) => !(field in value) || value[field] == null);
+    if (missing.length) {
+        throw new Error(`[ARTIFACT_SCHEMA_INVALID] Missing required fields: ${missing.join(', ')}`);
+    }
+    printJson({
+        file: path.resolve(opts.file),
+        valid: true,
+        artifact_kind: value.artifact_kind,
+        version: value.version,
+        schema_catalog_version: MIGRATION_ARTIFACT_SCHEMAS.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-capabilities.d.ts

@@ -0,0 +1,53 @@
+export type SupportedLanguage = 'typescript' | 'go' | 'java' | 'dotnet';
+export declare const SDK_CAPABILITY_MATRIX: {
+    readonly version: 1;
+    readonly artifact_kind: "ductape_sdk_capability_matrix";
+    readonly authority: "source_verified_catalog";
+    readonly generated_from: "repository source; update and test this catalog with every supported SDK release";
+    readonly unsupported_policy: {
+        readonly rule: "Never infer cross-language parity or synthesize a missing API.";
+        readonly action: "Inspect the installed package exports, record the capability as unsupported, and stop for an approved fallback.";
+    };
+    readonly sdks: readonly [{
+        readonly language: "typescript";
+        readonly package: "@ductape/sdk";
+        readonly version: "0.1.101";
+        readonly status: "supported";
+        readonly source_version: "sdk/ts/package.json";
+        readonly public_surface_evidence: "sdk/ts/src/index.ts";
+        readonly capabilities: readonly ["actions", "agents", "cache", "cloud", "databases", "events", "features", "graphs", "imports", "jobs", "logs", "models", "notifications", "products", "resilience", "secrets", "sessions", "storage", "vectors", "warehouse"];
+        readonly lifecycle: readonly ["await asynchronous operations", "close/disconnect owned clients during application shutdown"];
+    }, {
+        readonly language: "go";
+        readonly package: "github.com/ductape/ductape/sdk/go";
+        readonly version: "v0.0.1";
+        readonly status: "supported";
+        readonly source_version: "sdk/go git tag v0.0.1";
+        readonly public_surface_evidence: "sdk/go/ductape";
+        readonly capabilities: readonly ["actions", "agents", "cache", "cloud", "databases", "events", "features", "graphs", "imports", "jobs", "logs", "models", "notifications", "products", "resilience", "secrets", "sessions", "storage", "vectors", "warehouse"];
+        readonly lifecycle: readonly ["propagate context.Context cancellation", "close owned clients during application shutdown"];
+    }, {
+        readonly language: "java";
+        readonly package: "app.ductape:ductape-sdk";
+        readonly version: "0.1.9-SNAPSHOT";
+        readonly status: "supported-source-snapshot";
+        readonly source_version: "sdk/java/build.gradle";
+        readonly public_surface_evidence: "sdk/java/src/main/java/app/ductape/sdk/Ductape.java";
+        readonly capabilities: readonly ["actions", "agents", "cache", "cloud", "databases", "events", "features", "graphs", "imports", "jobs", "logs", "models", "notifications", "products", "resilience", "secrets", "sessions", "storage", "vectors", "warehouse"];
+        readonly lifecycle: readonly ["propagate interruption/cancellation", "close owned clients during application shutdown"];
+    }, {
+        readonly language: "dotnet";
+        readonly package: "Ductape.Sdk";
+        readonly version: "0.1.12";
+        readonly status: "supported";
+        readonly source_version: "sdk/dotnet/src/Ductape.Sdk/Ductape.Sdk.csproj";
+        readonly public_surface_evidence: "sdk/dotnet/src/Ductape.Sdk/Ductape.cs";
+        readonly capabilities: readonly ["actions", "agents", "cache", "cloud", "databases", "events", "features", "graphs", "imports", "jobs", "logs", "models", "notifications", "products", "resilience", "secrets", "sessions", "storage", "vectors", "warehouse"];
+        readonly lifecycle: readonly ["propagate CancellationToken", "dispose owned clients during application shutdown"];
+    }];
+};
+export declare function runMigrationCapabilities(opts: {
+    language?: SupportedLanguage;
+    version?: string;
+    json?: boolean;
+}): void;

package/dist/commands/migration-capabilities.js

@@ -0,0 +1,66 @@
+import { printJson } from '../lib/output.js';
+const COMMON_RUNTIME_CAPABILITIES = [
+    'actions', 'agents', 'cache', 'cloud', 'databases', 'events', 'features',
+    'graphs', 'imports', 'jobs', 'logs', 'models', 'notifications', 'products',
+    'resilience', 'secrets', 'sessions', 'storage', 'vectors', 'warehouse',
+];
+export const SDK_CAPABILITY_MATRIX = {
+    version: 1,
+    artifact_kind: 'ductape_sdk_capability_matrix',
+    authority: 'source_verified_catalog',
+    generated_from: 'repository source; update and test this catalog with every supported SDK release',
+    unsupported_policy: {
+        rule: 'Never infer cross-language parity or synthesize a missing API.',
+        action: 'Inspect the installed package exports, record the capability as unsupported, and stop for an approved fallback.',
+    },
+    sdks: [
+        {
+            language: 'typescript',
+            package: '@ductape/sdk',
+            version: '0.1.101',
+            status: 'supported',
+            source_version: 'sdk/ts/package.json',
+            public_surface_evidence: 'sdk/ts/src/index.ts',
+            capabilities: [...COMMON_RUNTIME_CAPABILITIES],
+            lifecycle: ['await asynchronous operations', 'close/disconnect owned clients during application shutdown'],
+        },
+        {
+            language: 'go',
+            package: 'github.com/ductape/ductape/sdk/go',
+            version: 'v0.0.1',
+            status: 'supported',
+            source_version: 'sdk/go git tag v0.0.1',
+            public_surface_evidence: 'sdk/go/ductape',
+            capabilities: [...COMMON_RUNTIME_CAPABILITIES],
+            lifecycle: ['propagate context.Context cancellation', 'close owned clients during application shutdown'],
+        },
+        {
+            language: 'java',
+            package: 'app.ductape:ductape-sdk',
+            version: '0.1.9-SNAPSHOT',
+            status: 'supported-source-snapshot',
+            source_version: 'sdk/java/build.gradle',
+            public_surface_evidence: 'sdk/java/src/main/java/app/ductape/sdk/Ductape.java',
+            capabilities: [...COMMON_RUNTIME_CAPABILITIES],
+            lifecycle: ['propagate interruption/cancellation', 'close owned clients during application shutdown'],
+        },
+        {
+            language: 'dotnet',
+            package: 'Ductape.Sdk',
+            version: '0.1.12',
+            status: 'supported',
+            source_version: 'sdk/dotnet/src/Ductape.Sdk/Ductape.Sdk.csproj',
+            public_surface_evidence: 'sdk/dotnet/src/Ductape.Sdk/Ductape.cs',
+            capabilities: [...COMMON_RUNTIME_CAPABILITIES],
+            lifecycle: ['propagate CancellationToken', 'dispose owned clients during application shutdown'],
+        },
+    ],
+};
+export function runMigrationCapabilities(opts) {
+    const sdks = SDK_CAPABILITY_MATRIX.sdks.filter((sdk) => (!opts.language || sdk.language === opts.language) &&
+        (!opts.version || sdk.version === opts.version));
+    if (!sdks.length) {
+        throw new Error(`No supported SDK capability matrix matches ${opts.language ?? '*'}@${opts.version ?? '*'}.`);
+    }
+    printJson({ ...SDK_CAPABILITY_MATRIX, sdks }, Boolean(opts.json));
+}

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

@@ -0,0 +1,26 @@
+export declare const REQUIRED_DATABASE_FIELDS: {
+    readonly baseline: readonly ["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"];
+    readonly data: readonly ["transformations", "batching", "checkpoints", "idempotency", "resume_strategy", "validation", "reconciliation", "failure_recovery", "pii_controls", "retention", "seed_data"];
+    readonly cutover: readonly ["phases", "expand", "backfill", "dual_compatibility", "contract", "deployment_order", "migration_locking", "backup", "restore_test", "rollback", "irreversible_changes", "monitoring", "reconciliation", "approval"];
+};
+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';
+export const REQUIRED_DATABASE_FIELDS = {
+    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_DATABASE_FIELDS[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 {};