@rehearsal-db/core 1.1.0 → 1.3.0

package/dist/src/cli/workload_command_handlers.d.mts

@@ -0,0 +1,2 @@
+import { type CommandDefinition } from "./command_contract.mjs";
+export declare const createWorkloadCommandHandlers: () => readonly CommandDefinition[];

package/dist/src/cli/workload_command_handlers.mjs

@@ -0,0 +1,38 @@
+/** Inspect/recover queue metadata without needing Docker, config or a project lock. */
+import { inspectWorkloads, recoverWorkloads, withWorkloadDiagnostics, } from "../runtime/workload_queue.mjs";
+import { exactCommands, renderedCommand, } from "./command_contract.mjs";
+import { RehearsalError } from "../shared/diagnostics.mjs";
+export const createWorkloadCommandHandlers = () => [
+    exactCommands("workloads", ["workloads"], async () => renderedCommand({
+        data: await withWorkloadDiagnostics(() => inspectWorkloads()),
+        render: (result) => [
+            "LOCAL WORKLOAD QUEUE — READ ONLY",
+            "Participating lifecycle phases only. Host/VM capacity is not measured.",
+            ...result.entries.map((entry) => `${entry.command} · ${entry.phase} · owner ${entry.owner} · PID ${entry.pid}${entry.recoveryRequired ? " · recovery required" : ""}`),
+            result.entries.length
+                ? ""
+                : "No participating workload is queued or held.",
+            ...(result.recoveryDigest
+                ? [
+                    "A dead holder may have surviving children. Check its owned commands before recovery.",
+                    `After checking: rehearsal workloads recover --confirm-workloads=${result.recoveryDigest}`,
+                    "Recovery clears exactly reviewed queue metadata; it does not stop processes or change databases.",
+                ]
+                : []),
+        ]
+            .filter(Boolean)
+            .join("\n"),
+    })),
+    exactCommands("workloads-recover", ["workloads recover"], async ({ flags }) => {
+        if (!flags.workloadConfirmation)
+            throw new RehearsalError({
+                category: "configuration_invalid",
+                code: "CONFIGURATION_INVALID",
+                message: "Inspect rehearsal workloads and review dead holders before using --confirm-workloads=<digest>. Check their owned commands first; recovery does not stop surviving children.",
+            });
+        return renderedCommand({
+            data: await withWorkloadDiagnostics(() => recoverWorkloads(flags.workloadConfirmation)),
+            render: (result) => `Recovered ${result.recovered} reviewed dead workload holder(s). No process, container or database was changed.`,
+        });
+    }),
+];

package/dist/src/project/configuration_contract.d.mts

@@ -4,6 +4,11 @@ export type RunPersistenceMode = "keep-until-stop" | "stop-after-run";
 export type OpenPersistenceMode = "keep-until-stop" | "stop-on-application-exit";
 export type ApplicationRequiredService = "database" | "auth" | "storage" | "postgrest" | "gateway" | "mail" | "studio" | "realtime" | "edge-functions" | "analytics" | "image-transforms";
 export interface RehearsalResourcePolicy {
+    /** Cooperatively serialize participating local runtime lifecycle phases. */
+    workloadQueue?: {
+        enabled: boolean;
+        waitTimeoutSeconds?: number;
+    };
     /** Review cutoff based on container start/stop, not application or database use. */
     staleAfterSeconds?: number | null;
     /** Advisory limit; retained databases are never automatically deleted. */

package/dist/src/project/configuration_normalization.d.mts

@@ -54,6 +54,10 @@ export declare const normalizeRehearsalConfig: (input: unknown) => Readonly<{
         retainBaselineGenerations: number;
     }>;
     resources: Readonly<{
+        workloadQueue?: {
+            enabled: boolean;
+            waitTimeoutSeconds: number;
+        };
         staleAfterSeconds: number | null;
         retainedEnvironmentCount: number;
         maximumBytes: number | null;

package/dist/src/project/configuration_resolution.d.mts

@@ -54,6 +54,10 @@ export declare const loadRehearsalConfig: ({ projectRoot, configPath, }?: Rehear
             retainBaselineGenerations: number;
         }>;
         resources: Readonly<{
+            workloadQueue?: {
+                enabled: boolean;
+                waitTimeoutSeconds: number;
+            };
             staleAfterSeconds: number | null;
             retainedEnvironmentCount: number;
             maximumBytes: number | null;

package/dist/src/project/configuration_resource_policy.d.mts

@@ -3,6 +3,10 @@ import type { ApplicationRequiredService } from "./configuration_contract.mjs";
 import { type PlainObject } from "./configuration_validation.mjs";
 export declare const APPLICATION_REQUIRED_SERVICES: readonly ["database", "auth", "storage", "postgrest", "gateway", "mail", "studio", "realtime", "edge-functions", "analytics", "image-transforms"];
 export declare const normalizeResourcePolicy: (resources: PlainObject) => Readonly<{
+    workloadQueue?: {
+        enabled: boolean;
+        waitTimeoutSeconds: number;
+    };
     staleAfterSeconds: number | null;
     retainedEnvironmentCount: number;
     maximumBytes: number | null;

package/dist/src/project/configuration_resource_policy.mjs

@@ -1,5 +1,5 @@
 /** Resource limits and proof dependencies, validated before any runtime starts. */
-import { assertPositiveInteger, } from "./configuration_validation.mjs";
+import { assertKnownKeys, assertPlainObject, assertPositiveInteger, } from "./configuration_validation.mjs";
 export const APPLICATION_REQUIRED_SERVICES = Object.freeze([
     "database",
     "auth",
@@ -29,6 +29,24 @@ const nullablePositiveInteger = (value, path) => {
     return normalized;
 };
 export const normalizeResourcePolicy = (resources) => {
+    let workloadQueue;
+    if (resources.workloadQueue !== undefined) {
+        const path = "config.resources.workloadQueue";
+        const value = assertPlainObject(resources.workloadQueue, path);
+        assertKnownKeys(value, ["enabled", "waitTimeoutSeconds"], path);
+        if (typeof value.enabled !== "boolean")
+            throw new Error(`${path}.enabled must be a boolean.`);
+        const waitTimeoutSeconds = value.waitTimeoutSeconds === undefined ? 30 : value.waitTimeoutSeconds;
+        if (!Number.isInteger(waitTimeoutSeconds) ||
+            typeof waitTimeoutSeconds !== "number" ||
+            waitTimeoutSeconds < 0 ||
+            waitTimeoutSeconds > 300)
+            throw new Error(`${path}.waitTimeoutSeconds must be an integer from 0 to 300.`);
+        workloadQueue = Object.freeze({
+            enabled: value.enabled,
+            waitTimeoutSeconds,
+        });
+    }
     const schedule = resources.cleanupSchedule ?? "manual";
     if (typeof schedule !== "string" ||
         !["manual", "daily-preview", "weekly-preview"].includes(schedule)) {
@@ -39,6 +57,7 @@ export const normalizeResourcePolicy = (resources) => {
         throw new Error("config.resources.retainedEnvironmentCount must be at most 1000.");
     }
     return Object.freeze({
+        ...(workloadQueue === undefined ? {} : { workloadQueue }),
         staleAfterSeconds: nullablePositiveInteger(resources.staleAfterSeconds, "config.resources.staleAfterSeconds"),
         retainedEnvironmentCount,
         maximumBytes: nullablePositiveInteger(resources.maximumBytes, "config.resources.maximumBytes"),

package/dist/src/project/configuration_schema.mjs

@@ -92,6 +92,7 @@ export const validateConfigurationSchema = (input) => {
         "retainedEnvironmentCount",
         "maximumBytes",
         "cleanupSchedule",
+        "workloadQueue",
     ], "config.resources");
     const preparation = root.preparation === undefined
         ? null

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

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

@@ -0,0 +1,18 @@
+/** Fixed catalog predicates. They inspect metadata, never evaluate stored SQL. */
+type RelationAlias = "r" | "p";
+/**
+ * Even COUNT planning opens indexes, including invalid ones, and may evaluate
+ * stored expressions. Permit only plain scalar bootstrap btree/hash metadata.
+ * Arrays/composites/domains are excluded because native support can delegate to
+ * their element/member operators. This is not protection against a compromised
+ * server or privileged replacement of PostgreSQL's bootstrap catalog contents.
+ */
+export declare const nativeMigrationImpactIndexes: (alias: RelationAlias) => string;
+/** PostgreSQL may const-fold expression statistics before consulting their data. */
+export declare const nativeMigrationImpactStatistics: (alias: RelationAlias) => string;
+/**
+ * Require one exact native default for each comparison AM. No binary-coercible
+ * fallback: varchar/bpchar are deliberately outside comparison recognition.
+ */
+export declare const nativeMigrationImpactComparison: (alias: "t") => string;
+export {};