@rehearsal-db/core 1.0.2 → 1.2.0

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 {};

package/dist/src/runtime/migration_impact_catalog.mjs

@@ -0,0 +1,116 @@
+const namespace = "(select oid from pg_catalog.pg_namespace where nspname = 'pg_catalog')";
+const scalarTypes = "('bool', 'int2', 'int4', 'int8', 'numeric', 'float4', 'float8', 'text', 'varchar', 'bpchar', 'uuid', 'date', 'timestamp', 'timestamptz')";
+const relationAlias = (value) => {
+    if (value !== "r" && value !== "p")
+        throw new Error("The fixed migration-impact catalog alias is unsupported.");
+    return value;
+};
+/** Only bootstrap functions; arbitrary objects merely named pg_catalog do not qualify. */
+const nativeProcedure = (oid) => `exists (
+  select 1 from pg_catalog.pg_proc mi_proc
+  where mi_proc.oid = ${oid} and mi_proc.oid < 16384
+    and mi_proc.pronamespace = ${namespace}
+    and mi_proc.prokind = 'f' and mi_proc.prolang in (12, 13)
+)`;
+/** Fixed aliases mi_class/mi_am belong to the enclosing predicate's subquery. */
+const nativeClass = () => `(
+  mi_class.oid < 16384 and mi_class.opcnamespace = ${namespace}
+  and mi_class.opcmethod = mi_am.oid
+  and mi_am.amtype = 'i'
+  and ((mi_am.oid = 403 and mi_am.amname = 'btree')
+    or (mi_am.oid = 405 and mi_am.amname = 'hash'))
+  and ${nativeProcedure("mi_am.amhandler")}
+  and exists (select 1 from pg_catalog.pg_opfamily mi_family
+    where mi_family.oid = mi_class.opcfamily and mi_family.oid < 16384
+      and mi_family.opfnamespace = ${namespace}
+      and mi_family.opfmethod = mi_am.oid
+      and not exists (select 1 from pg_catalog.pg_amop mi_member
+        where mi_member.amopfamily = mi_family.oid and not (
+          mi_member.oid < 16384 and mi_member.amopmethod = mi_am.oid
+          and exists (select 1 from pg_catalog.pg_operator mi_operator
+            where mi_operator.oid = mi_member.amopopr and mi_operator.oid < 16384
+              and mi_operator.oprnamespace = ${namespace}
+              and ${nativeProcedure("mi_operator.oprcode")}
+              and (mi_operator.oprrest = 0 or ${nativeProcedure("mi_operator.oprrest")})
+              and (mi_operator.oprjoin = 0 or ${nativeProcedure("mi_operator.oprjoin")}))
+        ))
+      and not exists (select 1 from pg_catalog.pg_amproc mi_support
+        where mi_support.amprocfamily = mi_family.oid and not (
+          mi_support.oid < 16384 and ${nativeProcedure("mi_support.amproc")}
+        ))
+  )
+)`;
+/**
+ * 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 const nativeMigrationImpactIndexes = (alias) => {
+    const owner = relationAlias(alias);
+    return `(not exists (
+    select 1 from pg_catalog.pg_index mi_index
+    where mi_index.indrelid = ${owner}.oid and (
+      mi_index.indexprs is null and mi_index.indpred is null
+      and mi_index.indnkeyatts > 0
+      and pg_catalog.array_length(mi_index.indkey::pg_catalog.int2[], 1) = mi_index.indnatts
+      and pg_catalog.array_length(mi_index.indclass::pg_catalog.oid[], 1) = mi_index.indnkeyatts
+      and pg_catalog.array_length(mi_index.indcollation::pg_catalog.oid[], 1) = mi_index.indnkeyatts
+      and exists (select 1 from pg_catalog.pg_class mi_index_relation
+        join pg_catalog.pg_am mi_am on mi_am.oid = mi_index_relation.relam
+        where mi_index_relation.oid = mi_index.indexrelid
+          and mi_index_relation.relkind = 'i' and not mi_index_relation.relispartition
+          and mi_am.amtype = 'i'
+          and ((mi_am.oid = 403 and mi_am.amname = 'btree')
+            or (mi_am.oid = 405 and mi_am.amname = 'hash'))
+          and ${nativeProcedure("mi_am.amhandler")}
+          and not exists (select 1 from pg_catalog.unnest(mi_index.indclass::pg_catalog.oid[]) mi_key(class_oid)
+            where not exists (select 1 from pg_catalog.pg_opclass mi_class
+              join pg_catalog.pg_type mi_input on mi_input.oid = mi_class.opcintype
+              where mi_class.oid = mi_key.class_oid
+                and mi_input.oid < 16384 and mi_input.typnamespace = ${namespace}
+                and mi_input.typbasetype = 0 and mi_input.typname in ${scalarTypes}
+                and ${nativeClass()}))
+      )
+      and not exists (select 1 from pg_catalog.unnest(mi_index.indkey::pg_catalog.int2[]) mi_key(attribute_number)
+        where not exists (select 1 from pg_catalog.pg_attribute mi_attribute
+          join pg_catalog.pg_type mi_type on mi_type.oid = mi_attribute.atttypid
+          where mi_attribute.attrelid = ${owner}.oid
+            and mi_attribute.attnum = mi_key.attribute_number and mi_attribute.attnum > 0
+            and not mi_attribute.attisdropped and mi_attribute.attgenerated in ('', 's')
+            and mi_type.oid < 16384 and mi_type.typnamespace = ${namespace}
+            and mi_type.typbasetype = 0 and mi_type.typname in ${scalarTypes}))
+      and not exists (select 1 from pg_catalog.unnest(mi_index.indcollation::pg_catalog.oid[]) mi_key(collation_oid)
+        where mi_key.collation_oid <> 0 and not exists (
+          select 1 from pg_catalog.pg_collation mi_collation
+          where mi_collation.oid = mi_key.collation_oid and mi_collation.oid < 16384
+            and mi_collation.collnamespace = ${namespace} and mi_collation.collisdeterministic))
+    ) is not true
+  ))`;
+};
+/** PostgreSQL may const-fold expression statistics before consulting their data. */
+export const nativeMigrationImpactStatistics = (alias) => {
+    const owner = relationAlias(alias);
+    return `(not exists (select 1 from pg_catalog.pg_statistic_ext mi_statistics
+    where mi_statistics.stxrelid = ${owner}.oid and mi_statistics.stxexprs is not null))`;
+};
+/**
+ * Require one exact native default for each comparison AM. No binary-coercible
+ * fallback: varchar/bpchar are deliberately outside comparison recognition.
+ */
+export const nativeMigrationImpactComparison = (alias) => {
+    if (alias !== "t")
+        throw new Error("The fixed migration-impact catalog alias is unsupported.");
+    return `(${[403, 405]
+        .map((method) => `(
+    (select pg_catalog.count(*) from pg_catalog.pg_opclass mi_default
+      where mi_default.opcintype = t.oid and mi_default.opcmethod = ${method}
+        and mi_default.opcdefault) = 1
+    and exists (select 1 from pg_catalog.pg_opclass mi_class
+      join pg_catalog.pg_am mi_am on mi_am.oid = mi_class.opcmethod
+      where mi_class.opcintype = t.oid and mi_class.opcdefault
+        and mi_am.oid = ${method} and ${nativeClass()})
+  )`)
+        .join(" and ")})`;
+};

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

@@ -0,0 +1,47 @@
+export interface MigrationImpactRelation {
+    readonly schema: string;
+    readonly name: string;
+}
+export type MigrationImpactUnknownReason = "unsupported_sql" | "malformed_sql" | "input_limit";
+interface MigrationImpactTaskSource {
+    readonly relation: MigrationImpactRelation;
+    readonly line: number;
+    readonly column: number;
+}
+/** Private measurement inputs, never a public SQL/identifier payload. */
+export type MigrationImpactTask = MigrationImpactTaskSource & ({
+    readonly metric: "rows";
+    readonly operation: "drop_table" | "truncate" | "broad_delete";
+} | {
+    readonly metric: "populated";
+    readonly operation: "drop_column";
+    readonly columns: readonly [string];
+} | {
+    readonly metric: "nulls";
+    readonly operation: "not_null";
+    readonly columns: readonly [string];
+} | {
+    readonly metric: "duplicate_rows";
+    readonly operation: "new_constraint";
+    readonly columns: readonly string[];
+} | {
+    readonly metric: "orphan_rows";
+    readonly operation: "new_constraint";
+    readonly columns: readonly string[];
+    readonly referencedRelation: MigrationImpactRelation;
+    readonly referencedColumns: readonly string[];
+});
+export interface MigrationImpactSqlPlan {
+    /** Coverage of the narrow recognizer, never SQL validity or a safe verdict. */
+    readonly complete: boolean;
+    readonly tasks: readonly MigrationImpactTask[];
+    readonly unknownReasons: readonly MigrationImpactUnknownReason[];
+}
+/**
+ * Plan narrow, current pre-migration snapshot measurements. No statement is
+ * executed; tasks do not predict earlier/later migration effects. The caller
+ * must validate the owned target, ordinary non-inherited/non-RLS tables and
+ * supported built-in column/operator semantics before using these private specs.
+ */
+export declare const planMigrationImpactSql: (source: string) => MigrationImpactSqlPlan;
+export {};