@rehearsal-db/core 1.1.0 → 1.2.0

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

package/dist/src/runtime/migration_impact_plan.mjs

@@ -0,0 +1,297 @@
+import { lexMigrationSql } from "./migration_sql_lexer.mjs";
+const maximumTasks = 100;
+// More columns are outside the supported grammar, not a whole-input limit.
+const maximumColumns = 8;
+const maximumIdentifierBytes = 63;
+/**
+ * The shared lexer folds words to uppercase. Check the original ASCII span as
+ * well: Unicode uppercase expansions must not become supported identifiers or
+ * keywords. This walk is linear and uses the lexer's UTF-16/CRLF coordinates.
+ */
+const asciiWords = (source, tokens) => {
+    const result = new Map();
+    let offset = 0;
+    let line = 1;
+    let column = 1;
+    const advance = () => {
+        const character = source[offset++];
+        if (character === "\r") {
+            if (source[offset] === "\n")
+                offset += 1;
+            line += 1;
+            column = 1;
+        }
+        else if (character === "\n") {
+            line += 1;
+            column = 1;
+        }
+        else
+            column += 1;
+    };
+    for (const token of tokens) {
+        while (offset < source.length &&
+            (line < token.line || (line === token.line && column < token.column)))
+            advance();
+        if (token.kind !== "word")
+            continue;
+        const start = offset;
+        if (!/[A-Za-z_]/u.test(source[offset] ?? ""))
+            continue;
+        while (/[A-Za-z0-9_$]/u.test(source[offset] ?? ""))
+            advance();
+        const raw = source.slice(start, offset);
+        if (raw.toUpperCase() === token.value)
+            result.set(token, raw.toLowerCase());
+    }
+    return result;
+};
+/** Exact token-shape matching, not a general PostgreSQL grammar/parser. */
+class StatementReader {
+    tokens;
+    words;
+    index = 0;
+    constructor(tokens, words) {
+        this.tokens = tokens;
+        this.words = words;
+    }
+    get current() {
+        return this.tokens[this.index];
+    }
+    get done() {
+        return this.index === this.tokens.length;
+    }
+    word(value) {
+        const token = this.current;
+        if (!token || this.words.get(token) !== value.toLowerCase())
+            return false;
+        this.index += 1;
+        return true;
+    }
+    symbol(value) {
+        const token = this.current;
+        if (token?.kind !== "symbol" || token.value !== value)
+            return false;
+        this.index += 1;
+        return true;
+    }
+    identifier() {
+        const token = this.current;
+        const value = token && this.words.get(token);
+        if (!value || value.length > maximumIdentifierBytes)
+            return undefined;
+        this.index += 1;
+        return value;
+    }
+    relation() {
+        const schema = this.identifier();
+        if (!schema || !this.symbol("."))
+            return undefined;
+        const name = this.identifier();
+        return name ? { schema, name } : undefined;
+    }
+    columns() {
+        if (!this.symbol("("))
+            return undefined;
+        const columns = [];
+        do {
+            const column = this.identifier();
+            if (!column ||
+                columns.length >= maximumColumns ||
+                columns.includes(column))
+                return undefined;
+            columns.push(column);
+        } while (this.symbol(","));
+        return this.symbol(")") ? columns : undefined;
+    }
+}
+const recognizeStatement = (tokens, words) => {
+    const reader = new StatementReader(tokens, words);
+    const first = reader.current;
+    if (!first)
+        return undefined;
+    const position = { line: first.line, column: first.column };
+    if (reader.word("DROP")) {
+        if (!reader.word("TABLE"))
+            return undefined;
+        if (reader.word("IF") && !reader.word("EXISTS"))
+            return undefined;
+        const relation = reader.relation();
+        reader.word("RESTRICT");
+        return relation && reader.done
+            ? { ...position, relation, metric: "rows", operation: "drop_table" }
+            : undefined;
+    }
+    if (reader.word("TRUNCATE")) {
+        reader.word("TABLE");
+        reader.word("ONLY");
+        const relation = reader.relation();
+        if ((reader.word("RESTART") || reader.word("CONTINUE")) &&
+            !reader.word("IDENTITY"))
+            return undefined;
+        reader.word("RESTRICT");
+        return relation && reader.done
+            ? { ...position, relation, metric: "rows", operation: "truncate" }
+            : undefined;
+    }
+    if (reader.word("DELETE")) {
+        if (!reader.word("FROM"))
+            return undefined;
+        reader.word("ONLY");
+        const relation = reader.relation();
+        return relation && reader.done
+            ? { ...position, relation, metric: "rows", operation: "broad_delete" }
+            : undefined;
+    }
+    if (!reader.word("ALTER") || !reader.word("TABLE"))
+        return undefined;
+    reader.word("ONLY");
+    const relation = reader.relation();
+    if (!relation)
+        return undefined;
+    const action = reader.current;
+    if (!action)
+        return undefined;
+    if (reader.word("DROP")) {
+        reader.word("COLUMN");
+        if (reader.word("IF") && !reader.word("EXISTS"))
+            return undefined;
+        const column = reader.identifier();
+        reader.word("RESTRICT");
+        return column && reader.done
+            ? {
+                relation,
+                line: action.line,
+                column: action.column,
+                operation: "drop_column",
+                metric: "populated",
+                columns: [column],
+            }
+            : undefined;
+    }
+    if (reader.word("ALTER")) {
+        reader.word("COLUMN");
+        const column = reader.identifier();
+        if (!column || !reader.word("SET"))
+            return undefined;
+        const not = reader.current;
+        if (!not || !reader.word("NOT") || !reader.word("NULL") || !reader.done)
+            return undefined;
+        return {
+            relation,
+            line: not.line,
+            column: not.column,
+            operation: "not_null",
+            metric: "nulls",
+            columns: [column],
+        };
+    }
+    if (!reader.word("ADD"))
+        return undefined;
+    if (reader.word("CONSTRAINT") && !reader.identifier())
+        return undefined;
+    const constraintPosition = { line: action.line, column: action.column };
+    if (reader.word("UNIQUE")) {
+        const columns = reader.columns();
+        return columns && reader.done
+            ? {
+                ...constraintPosition,
+                relation,
+                operation: "new_constraint",
+                metric: "duplicate_rows",
+                columns,
+            }
+            : undefined;
+    }
+    if (!reader.word("FOREIGN") || !reader.word("KEY"))
+        return undefined;
+    const columns = reader.columns();
+    if (!columns || !reader.word("REFERENCES"))
+        return undefined;
+    const referencedRelation = reader.relation();
+    const referencedColumns = reader.columns();
+    if (reader.word("MATCH") && !reader.word("SIMPLE"))
+        return undefined;
+    return referencedRelation &&
+        referencedColumns &&
+        columns.length === referencedColumns.length &&
+        reader.done
+        ? {
+            ...constraintPosition,
+            relation,
+            operation: "new_constraint",
+            metric: "orphan_rows",
+            columns,
+            referencedRelation,
+            referencedColumns,
+        }
+        : undefined;
+};
+/**
+ * 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 const planMigrationImpactSql = (source) => {
+    const lexical = lexMigrationSql(source);
+    const reasons = new Set(lexical.unknownReasons);
+    const refusal = () => ({
+        complete: false,
+        tasks: [],
+        unknownReasons: [...reasons].sort(),
+    });
+    // Lexical ambiguity, malformed input and limits invalidate all boundaries.
+    if (reasons.size > 0 || lexical.ambiguousQuotes)
+        return refusal();
+    const words = asciiWords(source, lexical.tokens);
+    const statements = [];
+    let statement = [];
+    for (const token of lexical.tokens) {
+        if (token.kind === "symbol" && token.value === ";" && token.depth === 0) {
+            if (statement.length > 0)
+                statements.push(statement);
+            statement = [];
+        }
+        else
+            statement.push(token);
+    }
+    if (statement.length > 0)
+        statements.push(statement);
+    // SQL-standard routine bodies and explicit transactions need a real parser /
+    // transactional model. Never reinterpret their inner statements as top-level.
+    const transactionCommands = new Set([
+        "begin",
+        "start",
+        "commit",
+        "end",
+        "rollback",
+        "abort",
+        "savepoint",
+        "release",
+        "prepare",
+    ]);
+    if (lexical.tokens.some((token, index) => words.get(token) === "begin" &&
+        words.get(lexical.tokens[index + 1]) === "atomic") ||
+        statements.some((tokens) => transactionCommands.has(words.get(tokens[0]) ?? ""))) {
+        reasons.add("unsupported_sql");
+        return refusal();
+    }
+    const tasks = [];
+    for (const tokens of statements) {
+        const task = recognizeStatement(tokens, words);
+        if (!task)
+            reasons.add("unsupported_sql");
+        else {
+            if (tasks.length >= maximumTasks) {
+                reasons.add("input_limit");
+                return refusal();
+            }
+            tasks.push(task);
+        }
+    }
+    return {
+        complete: reasons.size === 0,
+        tasks,
+        unknownReasons: [...reasons].sort(),
+    };
+};

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

@@ -0,0 +1,22 @@
+/** Compile only fixed aggregate queries; migration SQL and identifiers stay private. */
+import type { MigrationImpactTask } from "./migration_impact_plan.mjs";
+export declare const MIGRATION_IMPACT_LIMITS: Readonly<{
+    maximumMeasurements: 100;
+    lockTimeoutMilliseconds: 1000;
+    statementTimeoutMilliseconds: 5000;
+    totalTimeoutMilliseconds: 30000;
+    maximumOutputBytes: 131072;
+    maximumScriptBytes: 262144;
+}>;
+export interface MigrationImpactCount {
+    readonly index: number;
+    readonly count: string | null;
+    readonly reason: "unsupported_runtime_metadata" | "unsupported_server_version" | "total_timeout" | null;
+}
+/** One consistent current-row snapshot. No pending migration statement is executed. */
+export declare const buildMigrationImpactScript: (tasks: readonly MigrationImpactTask[], transactionTimeoutMilliseconds?: number) => string;
+export declare const parseMigrationImpactBatchOutput: (output: string, expectedCount: number) => {
+    readonly snapshotAt: string | null;
+    readonly counts: readonly MigrationImpactCount[];
+};
+export declare const parseMigrationImpactOutput: (output: string, expectedCount: number) => readonly MigrationImpactCount[];