@rehearsal-db/core 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -3,7 +3,33 @@
 All notable Rehearsal package changes are documented here. The format follows Keep
 a Changelog, and published versions follow Semantic Versioning.
 
-## [Unreleased]
+## [1.2.0] - 2026-10-24
+
+### Added
+
+- An optional `migrationImpact: 1` contract: offline `inspect impact` and explicitly
+  confirmed `measure impact` for one selected, already-verified disposable local
+  sandbox. Bounded read-only snapshot aggregates cover narrow supported row,
+  populated/NULL, duplicate and foreign-key orphan counts; unsupported or incomplete
+  evidence stays unknown. No pending migration is executed, no runtime is started
+  or repaired, and no SQL, object names or row contents are returned. Counts are
+  not sequential simulation, production prediction or a safety verdict. Existing
+  project locking/cancellation is reused without adding a rehearsal gate or CLI fee.
+- An optional versioned `inspect insights` contract for bounded, read-only static
+  migration warnings. Findings bind to exact pending file bytes and the complete
+  existing candidate digest, with fixed explanations and lexical locations.
+  Unsupported, malformed or truncated analysis remains unknown; no detected
+  warning is never SQL validity, database verification or a safety verdict.
+- Project-local input bounds, unchanged leaf/directory identity checks and shared
+  input hash binding. Inspection neither executes SQL nor starts an engine or
+  contacts a database. Existing migration-plan v1 and failure diagnosis remain
+  separate, unchanged contracts.
+
+### Documentation
+
+- Clarify reviewed PostgreSQL/application/full service dependencies and resource
+  measurement limits without adding service exclusions or a new acceptance gate.
+- Distinguish project runtime hooks from native migration-tool history support.
 
 ## [1.1.0] - 2026-10-21
 

package/COMPATIBILITY.md

@@ -38,6 +38,37 @@ through the project's existing version manager or use the helper's explicit exec
 path; see [OS setup](installers/README.md). Helpers never install Node or switch a
 project's runtime automatically.
 
+The 1.2.0 source candidate adds optional capability
+`rehearsalContracts.migrationInsights: 1` and `inspect insights --json`. It preserves
+existing migration-plan v1, baseline formats, digest meaning and failure diagnosis.
+Consumers must check the capability and exact plan/file bindings; absent or
+unavailable static analysis is not safety evidence. This candidate version and its
+setup target do not establish publication or completed editor/native acceptance.
+
+Further source work adds optional `rehearsalContracts.migrationImpact: 1` with
+`inspect impact` and `measure impact`. Consumers must explicitly select a configured
+local target and bind measurement consent to the exact whole-plan digest. Preview
+does not contact a database; measurement reads only the current verified sandbox,
+without applying migrations, starting/repairing a runtime or changing database data.
+Aggregate execution requires PostgreSQL 17 or newer with server-side transaction
+deadlines and narrowly supported ordinary-table/built-in semantics; older servers
+remain unknown, with no automatic database upgrade.
+Supabase measurement uses the ownership-proven local container's built-in
+`supabase_admin` socket role so the fixed disk bound and catalog lock can be enforced.
+It does not promote `postgres`, change grants, load credentials or connect remotely.
+Read-only catalog preflight is separate from the count snapshot. Bounded strong
+relation locks precede that snapshot and temporarily block writers and metadata
+changes in the selected disposable sandbox; this is not a nonblocking query promise.
+Counts are decimal strings or `null` with an explicit unknown reason, never a safety
+verdict, sequential simulation or production prediction. Partial/unknown measurement
+uses `not_ready` with the existing not-ready exit `1`; normal rehearsal gates and existing JSON contracts
+are unchanged. This unpublished source capability does not claim a new editor UI,
+new database family or additional platform/native acceptance.
+Older strict editor activity consumers can reject the new `measure impact` operation
+kind, including a retained completed receipt. Pair this capability with an editor
+consumer explicitly supporting that kind; the CLI does not silently rename the
+operation, relax unknown-kind validation or update an active editor installation.
+
 ## Operating systems and execution location
 
 Core 1.0.1's platform boundary distinguishes the computer running VS Code from the

package/README.md

@@ -47,7 +47,7 @@ it through a reviewed privacy policy, and retire the access again. It is never p
 production deployment tool.
 
 The CLI is free and MIT-licensed, with stable releases on
-[npm](https://www.npmjs.com/package/@rehearsal-db/core). This guide targets **1.1.0**;
+[npm](https://www.npmjs.com/package/@rehearsal-db/core). This guide targets **1.2.0**;
 install only a version actually published there. Prefer a visual workflow?
 [Install the free VS Code Starter preview](docs/vscode.md). Its included features are
 free indefinitely for personal or commercial development—no account, card, or trial.
@@ -198,6 +198,7 @@ Start here:
 - [VS Code extension](docs/vscode.md) — use the project-aware visual workbench
 - [Safe hands-on tutorial](docs/tutorial.md) — try the full flow in a disposable project
 - [Troubleshooting](docs/troubleshooting.md) — fix common setup problems
+- [Updates](docs/updating.md) — update the CLI or extension without resetting data
 - [Next steps](docs/roadmap.md) — see the current product sequence
 
 Reference:
@@ -214,9 +215,12 @@ Reference:
 - [Standalone workflow and security gates](docs/standalone-workflow.md)
 - [Runtime and local identity policies](docs/runtime-policies.md)
 - [Glossary](docs/glossary.md)
-- [Repository architecture](docs/architecture.md)
 - [Stability and the first stable release](docs/stability.md)
-- [Release process](docs/releasing.md)
+
+For maintainers developing and publishing Rehearsal:
+
+- [Repository architecture](docs/architecture.md)
+- [Maintainer release process](docs/releasing.md)
 
 ## Getting support
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rehearsal-db/core",
-    "version": "1.1.0",
+    "version": "1.2.0",
     "private": false,
     "description": "Catch PostgreSQL and Supabase migrations that pass on empty databases but fail on real data—before deploy.",
     "repository": {
@@ -27,6 +27,8 @@
         "resourceInventory": 1,
         "resourceManager": 1,
         "migrationReview": 1,
+        "migrationInsights": 1,
+        "migrationImpact": 1,
         "configurationReview": 1,
         "baselineShape": 1
     },

package/dist/src/cli/arguments.mjs

@@ -150,6 +150,7 @@ export const commandMutatesProject = ({ command, flags, guided, }) => {
         "open",
         "start",
         "migrate",
+        "measure impact",
         "reset",
         "stop",
         "discard",

package/dist/src/cli/basic_command_handlers.mjs

@@ -35,6 +35,9 @@ Commands:
   inspect baseline           Show verified baseline provenance
   inspect migrations         Classify represented, applied, and candidate migrations
   inspect plan               Review ordered migrations, required dependencies, and warnings
+  inspect insights           Review bounded static SQL warnings; never a safety verdict
+  inspect impact             Preview aggregate measurements for one explicit --target
+  measure impact             Measure reviewed aggregates on that running local sandbox
   start                      Start an existing verified local runtime
   migrate --confirm-candidates= Apply the exact candidate suffix without resetting
   reset                      Restore and verify the immutable local baseline
@@ -48,6 +51,7 @@ Commands:
 
 Options: --help, -h --version, -V --json --verbose --debug --plain
          --config=<path> --target=<provider for setup; configured name for runtime>
+         --confirm-candidates=<whole-plan digest for run, migrate, or measure impact>
          --confirm-source-access=<digest> --confirm-source-retirement=<digest>
          --confirm-refresh=<digest>`;
 export const createBasicCommandHandlers = () => [

package/dist/src/cli/editor_command_handlers.mjs

@@ -1,9 +1,33 @@
 /** Versioned, read-only contracts for editor review; never a second runtime engine. */
 import { inspectMigrationReviewPlan } from "../runtime/migration_plan.mjs";
+import { inspectMigrationInsights, renderMigrationInsights, } from "../runtime/migration_insights.mjs";
+import { inspectMigrationImpact, measureMigrationImpact, renderMigrationImpact, } from "../runtime/migration_impact.mjs";
 import { exactCommands, renderedCommand } from "./command_contract.mjs";
 import { applyStopStalePlan, inspectStopStalePlan, stopReviewedStaleTarget, } from "../runtime/stale_environment_plan.mjs";
 import { inspectConfigurationMetadata, reviewConfigurationProposal, } from "../project/configuration_review.mjs";
 export const createEditorCommandHandlers = () => [
+    exactCommands("migration-impact-preview", ["inspect impact"], async ({ planOptions, flags }) => {
+        const data = await inspectMigrationImpact(planOptions, flags.target);
+        return renderedCommand({ data, render: renderMigrationImpact });
+    }),
+    exactCommands("migration-impact-measurement", ["measure impact"], async ({ planOptions, flags }) => {
+        const data = await measureMigrationImpact({
+            options: planOptions,
+            targetName: flags.target,
+            confirmation: flags.confirmation,
+        });
+        const incomplete = ["partial", "unknown"].includes(data.measurementStatus);
+        return renderedCommand({
+            data,
+            render: renderMigrationImpact,
+            status: incomplete ? "not_ready" : "success",
+            ...(incomplete ? { exitCode: 1 } : {}),
+        });
+    }),
+    exactCommands("migration-insights", ["inspect insights"], async ({ planOptions }) => {
+        const data = await inspectMigrationInsights(planOptions);
+        return renderedCommand({ data, render: renderMigrationInsights });
+    }),
     exactCommands("configuration", ["configuration", "configuration review"], async ({ command, planOptions, flags }) => {
         const data = command === "configuration review"
             ? await reviewConfigurationProposal(planOptions, flags.proposalPath ??

package/dist/src/runtime/migration_history.d.mts

@@ -24,7 +24,11 @@ export interface MigrationReplayReceipt {
     entries: MigrationReplayEntry[];
     historySha256: string;
 }
-export declare const readMigrationFileInventory: (directory: URL) => Promise<MigrationFileEntry[]>;
+export declare const readMigrationFileInventory: (directory: URL, options?: {
+    readonly maximumFiles?: number;
+    readonly maximumDirectoryEntries?: number;
+    readonly readBytes?: (path: URL, filename: string) => Promise<Buffer>;
+}) => Promise<MigrationFileEntry[]>;
 export declare const readMigrationSourceBundle: ({ directory, sourceLedger, }: {
     directory: URL;
     sourceLedger: readonly MigrationLedgerEntry[];

package/dist/src/runtime/migration_history.mjs

@@ -4,7 +4,7 @@
  * this module is reusable script infrastructure.
  */
 import { createHash } from "node:crypto";
-import { readFile, readdir } from "node:fs/promises";
+import { opendir, readFile, readdir } from "node:fs/promises";
 const migrationNamePattern = /^(\d{14})_(.+)\.sql$/u;
 const sha256 = (value) => createHash("sha256").update(value).digest("hex");
 const canonicalJson = (value) => `${JSON.stringify(value, null, "\t")}\n`;
@@ -32,17 +32,35 @@ const assertOrderedUniqueHistory = (entries, label) => {
     }
     return entries;
 };
-export const readMigrationFileInventory = async (directory) => {
-    const names = (await readdir(directory))
-        .filter((name) => name.endsWith(".sql"))
-        .sort();
+export const readMigrationFileInventory = async (directory, options = {}) => {
+    let names = [];
+    if (options.maximumDirectoryEntries === undefined) {
+        names = (await readdir(directory)).filter((name) => name.endsWith(".sql"));
+    }
+    else {
+        let visited = 0;
+        // Async directory iteration closes its descriptor on success and refusal.
+        // Bounded callers must not allocate an arbitrary directory listing first.
+        for await (const entry of await opendir(directory)) {
+            if (++visited > options.maximumDirectoryEntries)
+                throw new Error("Migration inspection exceeds its bounded directory inventory.");
+            if (entry.name.endsWith(".sql"))
+                names.push(entry.name);
+        }
+    }
+    names.sort();
+    if (options.maximumFiles !== undefined && names.length > options.maximumFiles)
+        throw new Error("Migration inspection exceeds its bounded file inventory.");
     const entries = [];
     for (const filename of names) {
         const match = migrationNamePattern.exec(filename);
         if (!match) {
             throw new Error(`Invalid migration filename in ${directory}: ${filename}`);
         }
-        const bytes = await readFile(new URL(filename, directory));
+        const path = new URL(filename, directory);
+        const bytes = options.readBytes
+            ? await options.readBytes(path, filename)
+            : await readFile(path);
         entries.push({
             version: match[1],
             name: match[2],

package/dist/src/runtime/migration_impact.d.mts

@@ -0,0 +1,125 @@
+import type { RehearsalConfigPathOptions } from "../project/configuration.mjs";
+import { type MigrationImpactTask, type MigrationImpactUnknownReason } from "./migration_impact_plan.mjs";
+import { type MigrationImpactCount } from "./migration_impact_queries.mjs";
+import { openMigrationImpactRuntime } from "../targets/migration_impact_runtime.mjs";
+type CountUnknownReason = "unsupported_runtime_metadata" | "unsupported_server_version" | "query_failed" | "lock_timeout" | "statement_timeout" | "total_timeout" | "input_limit";
+interface PreparedEntry {
+    readonly filename: string;
+    readonly sha256: string;
+    readonly tasks: readonly MigrationImpactTask[];
+    readonly unknownReasons: readonly MigrationImpactUnknownReason[];
+}
+declare const prepare: (options: RehearsalConfigPathOptions, targetName: string | undefined) => Promise<{
+    projectRoot: string;
+    target: import("./topology.mjs").RuntimeTopologyTarget & {
+        summary: ReturnType<(inspection: {
+            baselineGenerationId: string;
+            baselineCutoff: string;
+            candidateSha256: string;
+            migrations: {
+                version: string;
+                name: string;
+                filename: string;
+                sha256: string;
+                status: string;
+            }[];
+            definitions: {
+                represented_by_baseline: string;
+                applied_to_current_runtime: string;
+                candidate: string;
+                modified: string;
+                invalid: string;
+            };
+        }) => Readonly<{
+            baselineGenerationId: string;
+            candidateSha256: string;
+            candidateCount: number;
+            candidates: readonly {
+                version: string;
+                name: string;
+                filename: string;
+                sha256: string;
+                status: string;
+            }[];
+        }>>;
+    };
+    baseline: import("../baseline/artifact.mjs").BaselineManifest;
+    entries: PreparedEntry[];
+    binding: string;
+    candidateSha256: string;
+    candidateCount: number;
+}>;
+type Prepared = Awaited<ReturnType<typeof prepare>>;
+declare const reportFor: ({ prepared, measured, counts, reason, snapshotAt, runtimeIdentitySha256, contactedDatabase, }: {
+    prepared: Prepared;
+    measured?: boolean;
+    counts?: readonly MigrationImpactCount[];
+    reason?: CountUnknownReason;
+    snapshotAt?: string | null;
+    runtimeIdentitySha256?: string | null;
+    contactedDatabase?: boolean;
+}) => {
+    schemaVersion: 1;
+    inspectorVersion: string;
+    candidateSha256: string;
+    candidateCount: number;
+    target: {
+        name: string;
+        provider: "postgresql" | "supabase";
+        baselineGenerationId: string;
+        candidateSha256: string;
+    };
+    mode: "measurement" | "preview";
+    measurementStatus: "measured" | "not_required" | "partial" | "planned" | "unknown";
+    snapshotAt: string | null;
+    runtimeIdentitySha256: string | null;
+    entries: {
+        filename: string;
+        sha256: string;
+        coverage: "incomplete" | "recognized_forms";
+        unknownReasons: readonly MigrationImpactUnknownReason[];
+        measurements: {
+            operation: "broad_delete" | "drop_column" | "drop_table" | "new_constraint" | "not_null" | "truncate";
+            metric: "duplicate_rows" | "nulls" | "orphan_rows" | "populated" | "rows";
+            line: number;
+            column: number;
+            evidence: "measured_current_snapshot" | "planned" | "unknown";
+            count: string | null;
+            unknownReason: CountUnknownReason | null;
+        }[];
+    }[];
+    summary: {
+        plannedCount: number;
+        measuredCount: number;
+        unknownMeasurementCount: number;
+        unknownEntryCount: number;
+    };
+    limits: Readonly<{
+        maximumMeasurements: 100;
+        lockTimeoutMilliseconds: 1000;
+        statementTimeoutMilliseconds: 5000;
+        totalTimeoutMilliseconds: 30000;
+        maximumOutputBytes: 131072;
+        maximumScriptBytes: 262144;
+    }>;
+    safety: {
+        appliesMigrations: boolean;
+        startsOrRepairsRuntime: boolean;
+        returnsRowContents: boolean;
+        returnsSqlOrObjectNames: boolean;
+        contactsDatabase: boolean;
+        transaction: "repeatable_read_read_only" | null;
+    };
+    limitation: string;
+};
+export type MigrationImpactReport = ReturnType<typeof reportFor>;
+export declare const inspectMigrationImpact: (options?: RehearsalConfigPathOptions, targetName?: string) => Promise<MigrationImpactReport>;
+export declare const measureMigrationImpact: ({ options, targetName, confirmation, }: {
+    options?: RehearsalConfigPathOptions;
+    targetName?: string | undefined;
+    confirmation?: string | undefined;
+}, implementation?: {
+    openRuntime?: typeof openMigrationImpactRuntime;
+}) => Promise<MigrationImpactReport>;
+export declare const renderMigrationImpact: (report: MigrationImpactReport) => string;
+export {};

package/dist/src/runtime/migration_impact.mjs

@@ -0,0 +1,278 @@
+/** Bind aggregate-only sandbox measurements to exact reviewed pending inputs. */
+import { createHash } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { performance } from "node:perf_hooks";
+import { verifyActiveBaseline } from "../baseline/artifact.mjs";
+import { REHEARSAL_VERSION, RehearsalError } from "../shared/diagnostics.mjs";
+import { getOperationCancellationSignal, throwIfOperationCancelled, } from "../shared/cancellation.mjs";
+import { inspectRehearsalMigrations } from "./plan.mjs";
+import { inspectRuntimeTopologyCandidates } from "./topology.mjs";
+import { createMigrationInsightsInput, MIGRATION_INSIGHTS_LIMITS, } from "./migration_insights_input.mjs";
+import { planMigrationImpactSql, } from "./migration_impact_plan.mjs";
+import { buildMigrationImpactScript, parseMigrationImpactBatchOutput, MIGRATION_IMPACT_LIMITS, } from "./migration_impact_queries.mjs";
+import { openMigrationImpactRuntime, MigrationImpactRuntimeError, } from "../targets/migration_impact_runtime.mjs";
+const refusal = (message, unsafe = false) => new RehearsalError({
+    category: unsafe ? "unsafe_environment" : "configuration_invalid",
+    code: unsafe ? "UNSAFE_ENVIRONMENT" : "CONFIGURATION_INVALID",
+    message,
+    refused: "No migration was applied, no runtime was started or repaired, and no row contents are returned.",
+    suggestions: [
+        "Review a fresh impact plan and explicitly select its already-running disposable local target.",
+    ],
+});
+const prepare = async (options, targetName) => {
+    if (typeof targetName !== "string" || !targetName || targetName.length > 128)
+        throw refusal("Impact review requires one explicit configured --target name, including primary.");
+    const projectRoot = await realpath(resolve(options.projectRoot ?? process.cwd()));
+    const input = createMigrationInsightsInput(projectRoot);
+    const candidates = await inspectRuntimeTopologyCandidates({ ...options, projectRoot }, (selected) => inspectRehearsalMigrations(selected, input.readInventory));
+    if (candidates.candidateCount > MIGRATION_INSIGHTS_LIMITS.maximumCandidates)
+        throw refusal("Impact review exceeds its bounded pending-migration input.");
+    const target = candidates.targets.find((entry) => entry.name === targetName);
+    if (!target)
+        throw refusal("Impact review requires one target from this project's configuration.");
+    let remaining = MIGRATION_IMPACT_LIMITS.maximumMeasurements;
+    const entries = target.summary.candidates.map((candidate) => {
+        const source = input.sourceFor(join(target.paths.migrationDirectory, candidate.filename), candidate.sha256);
+        if (source === undefined)
+            throw refusal("The exact impact-review input could not be retained. Refresh the plan.");
+        const plan = planMigrationImpactSql(source);
+        const tasks = plan.tasks.slice(0, remaining);
+        remaining -= tasks.length;
+        const unknownReasons = [
+            ...new Set([
+                ...plan.unknownReasons,
+                ...(tasks.length < plan.tasks.length ? ["input_limit"] : []),
+            ]),
+        ];
+        return {
+            filename: candidate.filename,
+            sha256: candidate.sha256,
+            tasks,
+            unknownReasons,
+        };
+    });
+    const baseline = await verifyActiveBaseline({
+        artifactRoot: target.paths.artifactDirectory,
+    });
+    if (baseline.generationId !== target.summary.baselineGenerationId)
+        throw refusal("The active baseline changed during impact review. Refresh the plan.");
+    const binding = createHash("sha256")
+        .update(JSON.stringify({
+        candidateSha256: candidates.candidateSha256,
+        target: target.name,
+        config: target.config,
+        paths: target.paths,
+        baseline,
+        inputs: entries.map((entry) => ({
+            filename: entry.filename,
+            sha256: entry.sha256,
+        })),
+    }))
+        .digest("hex");
+    return {
+        projectRoot,
+        target,
+        baseline,
+        entries,
+        binding,
+        candidateSha256: candidates.candidateSha256,
+        candidateCount: candidates.candidateCount,
+    };
+};
+const reportFor = ({ prepared, measured = false, counts, reason, snapshotAt = null, runtimeIdentitySha256 = null, contactedDatabase = false, }) => {
+    let index = 0;
+    let measuredCount = 0;
+    let unknownMeasurementCount = 0;
+    let unknownEntryCount = 0;
+    const entries = prepared.entries.map((entry) => {
+        const measurements = entry.tasks.map((task) => {
+            const count = counts?.[index++];
+            const unknownReason = reason ?? count?.reason ?? null;
+            const evidence = !measured
+                ? "planned"
+                : count?.count !== null &&
+                    count?.count !== undefined &&
+                    unknownReason === null
+                    ? "measured_current_snapshot"
+                    : "unknown";
+            if (evidence === "measured_current_snapshot")
+                measuredCount++;
+            if (evidence === "unknown")
+                unknownMeasurementCount++;
+            return {
+                operation: task.operation,
+                metric: task.metric,
+                line: task.line,
+                column: task.column,
+                evidence,
+                count: evidence === "measured_current_snapshot" ? count.count : null,
+                unknownReason: evidence === "unknown" ? (unknownReason ?? "query_failed") : null,
+            };
+        });
+        if (entry.unknownReasons.length ||
+            measurements.some((entry) => entry.evidence === "unknown"))
+            unknownEntryCount++;
+        return {
+            filename: entry.filename,
+            sha256: entry.sha256,
+            coverage: entry.unknownReasons.length
+                ? "incomplete"
+                : "recognized_forms",
+            unknownReasons: entry.unknownReasons,
+            measurements,
+        };
+    });
+    const plannedCount = entries.reduce((total, entry) => total + entry.measurements.length, 0);
+    const measurementStatus = !measured
+        ? "planned"
+        : unknownEntryCount
+            ? measuredCount
+                ? "partial"
+                : "unknown"
+            : plannedCount
+                ? "measured"
+                : "not_required";
+    return {
+        schemaVersion: 1,
+        inspectorVersion: REHEARSAL_VERSION,
+        candidateSha256: prepared.candidateSha256,
+        candidateCount: prepared.candidateCount,
+        target: {
+            name: prepared.target.name,
+            provider: prepared.target.config.runtime.target,
+            baselineGenerationId: prepared.baseline.generationId,
+            candidateSha256: prepared.target.summary.candidateSha256,
+        },
+        mode: measured ? "measurement" : "preview",
+        measurementStatus,
+        snapshotAt,
+        runtimeIdentitySha256,
+        entries,
+        summary: {
+            plannedCount,
+            measuredCount,
+            unknownMeasurementCount,
+            unknownEntryCount,
+        },
+        limits: MIGRATION_IMPACT_LIMITS,
+        safety: {
+            appliesMigrations: false,
+            startsOrRepairsRuntime: false,
+            returnsRowContents: false,
+            returnsSqlOrObjectNames: false,
+            contactsDatabase: contactedDatabase,
+            transaction: measured && snapshotAt !== null
+                ? "repeatable_read_read_only"
+                : null,
+        },
+        limitation: "Counts describe one current disposable-sandbox snapshot before any pending migration. They do not simulate sequential migration effects, establish SQL validity or safety, measure cascade/trigger effects, or predict production locks and performance. Unsupported objects, expressions and incomplete evidence stay unknown.",
+    };
+};
+export const inspectMigrationImpact = async (options = {}, targetName) => reportFor({ prepared: await prepare(options, targetName) });
+export const measureMigrationImpact = async ({ options = {}, targetName, confirmation, }, implementation = {}) => {
+    const controller = new AbortController();
+    const externalSignal = getOperationCancellationSignal();
+    const signal = externalSignal
+        ? AbortSignal.any([externalSignal, controller.signal])
+        : controller.signal;
+    const deadline = performance.now() + MIGRATION_IMPACT_LIMITS.totalTimeoutMilliseconds;
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, MIGRATION_IMPACT_LIMITS.totalTimeoutMilliseconds);
+    const checkpoint = () => {
+        throwIfOperationCancelled();
+        if (timedOut || performance.now() >= deadline) {
+            timedOut = true;
+            controller.abort();
+            throw new MigrationImpactRuntimeError("cancelled");
+        }
+    };
+    try {
+        const prepared = await prepare(options, targetName);
+        if (confirmation !== prepared.candidateSha256)
+            throw refusal("Measurement requires the exact whole-plan --confirm-candidates digest from a fresh impact review.");
+        const tasks = prepared.entries.flatMap((entry) => entry.tasks);
+        let contactedDatabase = false;
+        try {
+            checkpoint();
+            if (!tasks.length)
+                return reportFor({ prepared, measured: true });
+            const runtime = await (implementation.openRuntime ?? openMigrationImpactRuntime)({
+                projectRoot: prepared.projectRoot,
+                target: prepared.target,
+                baseline: prepared.baseline,
+                signal,
+            });
+            checkpoint();
+            try {
+                buildMigrationImpactScript(tasks);
+            }
+            catch {
+                return reportFor({ prepared, measured: true, reason: "input_limit" });
+            }
+            contactedDatabase = true;
+            const result = parseMigrationImpactBatchOutput(await runtime.runSql(() => {
+                checkpoint();
+                const script = buildMigrationImpactScript(tasks, Math.max(1, Math.floor(deadline - performance.now())));
+                checkpoint();
+                return script;
+            }), tasks.length);
+            checkpoint();
+            await runtime.assertCurrent();
+            checkpoint();
+            const current = await prepare(options, targetName);
+            checkpoint();
+            if (prepared.binding !== current.binding)
+                throw refusal("The reviewed configuration, baseline or migration inputs changed during measurement. No counts are returned.");
+            return reportFor({
+                prepared,
+                measured: true,
+                counts: result.counts,
+                snapshotAt: result.snapshotAt,
+                runtimeIdentitySha256: runtime.identitySha256,
+                contactedDatabase,
+            });
+        }
+        catch (error) {
+            throwIfOperationCancelled();
+            if (error instanceof RehearsalError)
+                throw error;
+            if (error instanceof MigrationImpactRuntimeError &&
+                ["runtime_unavailable", "ownership_mismatch", "stale_runtime"].includes(error.reason))
+                throw refusal("The selected sandbox is not a verified, unchanged running local runtime. No counts are returned.", true);
+            const reason = timedOut ||
+                (error instanceof MigrationImpactRuntimeError &&
+                    error.reason === "transaction_timeout")
+                ? "total_timeout"
+                : error instanceof MigrationImpactRuntimeError &&
+                    ["lock_timeout", "statement_timeout"].includes(error.reason)
+                    ? error.reason
+                    : "query_failed";
+            return reportFor({ prepared, measured: true, reason, contactedDatabase });
+        }
+    }
+    finally {
+        clearTimeout(timer);
+        controller.abort();
+    }
+};
+export const renderMigrationImpact = (report) => [
+    `MIGRATION DATA IMPACT — ${report.measurementStatus.toUpperCase()}`,
+    `${report.target.name}: ${report.summary.measuredCount} measured / ${report.summary.plannedCount} planned aggregates; ${report.summary.unknownEntryCount} incomplete files`,
+    `Exact whole-plan digest: ${report.candidateSha256}`,
+    ...(report.snapshotAt
+        ? [`Current-row snapshot: ${report.snapshotAt}`]
+        : []),
+    ...report.entries.flatMap((entry) => [
+        entry.filename,
+        ...entry.measurements.map((metric) => `  ${metric.line}:${metric.column} ${metric.metric}: ${metric.count ?? metric.evidence} ${metric.unknownReason ?? ""}`.trimEnd()),
+        ...(entry.unknownReasons.length
+            ? ["  Unsupported or bounded SQL remains unknown."]
+            : []),
+    ]),
+    report.limitation,
+].join("\n");