turbine-orm 0.65.0 → 0.66.0

package/dist/cli/mcp.js

@@ -3,11 +3,12 @@ import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import pg from 'pg';
 import { findMissingRelationIndexes } from '../index-advisor.js';
-import { addAutoManyToManyRelations, buildRelationsFromForeignKeys, isUnknownTsType, } from '../introspect.js';
+import { deriveCatalogRelations } from '../introspect.js';
 import { QueryInterface, quoteIdent } from '../query/index.js';
-import { registerUtcTemporalParsers } from '../query/utils.js';
+import { ownLookup, registerUtcTemporalParsers } from '../query/utils.js';
 import { isDateType, pgArrayType, pgTypeToTs, snakeToCamel, } from '../schema.js';
 import { listMigrationFiles } from './migrate.js';
+import { assertNoPiiPredicates as assertNoPiiPredicatesShared } from './pii-predicate-guard.js';
 import { applyPiiTags, loadPiiTags } from './pii-tags.js';
 import { redactUrl } from './ui.js';
 /**
@@ -588,7 +589,11 @@ async function explainQuery(ctx, args) {
             throw jsonRpcError(-32602, err instanceof Error ? err.message : String(err));
         }
         // QueryInterface emits unqualified identifiers; pin search_path like Studio.
-        await client.query(`SELECT set_config('search_path', $1, true)`, [ctx.options.schema]);
+        // The bound value's CONTENTS are parsed as an identifier list, so the name
+        // has to carry its own quotes: a raw `My.Schema` pins search_path to nothing
+        // and the statement below fails with `relation "..." does not exist`, while
+        // a raw mixed-case name silently case-folds onto a different schema.
+        await client.query(`SELECT set_config('search_path', $1, true)`, [quoteIdent(ctx.options.schema)]);
         const result = await client.query(`EXPLAIN (FORMAT JSON) ${deferred.sql}`, deferred.params);
         return {
             table: table.name,
@@ -598,17 +603,6 @@ async function explainQuery(ctx, args) {
         };
     });
 }
-/** Relation-filter wrappers whose body is a clause against the relation's target. */
-const RELATION_FILTER_WRAPPERS = ['some', 'none', 'every', 'is', 'isNot'];
-/**
- * Recursion bound for the PII guard walk. Reaching it REFUSES the request, it
- * is not a quiet stop: returning at the cap would mean a payload padded with
- * enough nested `NOT` wrappers walks the guard off the end of its own recursion
- * and then hands the untouched predicate to the builder. Sits far above the
- * builder's own depth-10 relation cap, so nothing buildable is refused for
- * depth alone.
- */
-const PII_GUARD_MAX_DEPTH = 32;
 /**
  * Refuse an `explain_query` that filters or sorts on a hidden column: one that
  * is PII-tagged, or one whose NAME matches {@link SECRET_NAME_PATTERN}.
@@ -630,9 +624,12 @@ const PII_GUARD_MAX_DEPTH = 32;
  * refuse the predicate. It matches the rule the rest of the codebase already
  * states: predicates on PII are allowed IN THE ORM because they return no
  * value, and that reasoning stops holding the moment the query's SELECTIVITY is
- * itself the reply. Studio drew the same line for the same reason
- * (`assertNoPiiPredicates`, and its `filters` param refuses even `isNull`,
- * because null-ness is an oracle too).
+ * itself the reply. Studio drew the same line for the same reason, which is why
+ * the WALK is now one shared module (`cli/pii-predicate-guard.ts`) rather than a
+ * second copy of it here: the two copies had the same job, the same name, and
+ * the same hole, and only a shared walk makes closing it once close it in both.
+ * What stays here is the part that is genuinely the MCP server's: the two
+ * reasons a column is hidden, and a JSON-RPC refusal.
  *
  * `select` is NOT refused: explain returns no rows, and naming a column reveals
  * nothing about its contents.
@@ -648,82 +645,39 @@ function assertNoPiiPredicates(args, table, metadata, piiTags) {
             `query does not filter or sort on a PII column, and row estimates on such a column are an extraction ` +
             `oracle. Re-run \`turbine generate\`, or call explain_query without where/orderBy.`);
     }
-    const assertWithinDepth = (depth) => {
-        if (depth <= PII_GUARD_MAX_DEPTH)
-            return;
-        throw jsonRpcError(-32602, `Query is nested more than ${PII_GUARD_MAX_DEPTH} levels deep, past the point where the PII guard can ` +
-            `prove it does not filter or sort on a tagged column, so it is refused. Flatten the query.`);
-    };
-    const refuse = (owner, column, why) => {
-        throw jsonRpcError(-32602, `Column "${column}" on "${owner.name}" ${why}, so it cannot be used in a where or orderBy here: ` +
-            `EXPLAIN reports the planner's row estimate, and the estimate for a predicate on a hidden value ` +
-            `reveals that value one character at a time. Filter on a visible column instead.`);
-    };
-    /**
-     * Why this column may not appear in a predicate, or null when it may.
-     *
-     * The two reasons are the two `sample_rows` already refuses to FETCH
-     * (`classifyHiddenColumns`), and they are deliberately the same set: a column
-     * whose bytes are too sensitive to sample is too sensitive to binary-search
-     * out of the planner. A column absent from the table is not judged here, the
-     * builder rejects it by name a moment later.
-     */
-    const hiddenReason = (owner, column) => {
-        if (owner.columns.some((col) => col.name === column && col.pii === true))
-            return 'is PII-tagged';
-        if (SECRET_NAME_PATTERN.test(column))
-            return 'has a secret-looking name';
-        return null;
-    };
-    const visitClause = (node, owner, depth) => {
-        assertWithinDepth(depth);
-        if (!owner || node === null || typeof node !== 'object')
-            return;
-        // `orderBy` accepts an array of single-key objects, and so does a `NOT`
-        // list. Element order carries no nesting, so the depth is unchanged.
-        if (Array.isArray(node)) {
-            for (const item of node)
-                visitClause(item, owner, depth);
-            return;
-        }
-        for (const [key, value] of Object.entries(node)) {
-            if (key === 'AND' || key === 'OR' || key === 'NOT') {
-                visitClause(value, owner, depth + 1);
-                continue;
-            }
-            const relation = Object.hasOwn(owner.relations, key) ? owner.relations[key] : undefined;
-            if (relation) {
-                visitRelationValue(value, metadata.tables[relation.to], depth + 1);
-                continue;
-            }
-            // A predicate may name a column by its camelCase field OR by its real
-            // column name; both compile to the same SQL, so both have to be checked.
-            const column = Object.hasOwn(owner.columnMap, key) ? owner.columnMap[key] : key;
-            const why = hiddenReason(owner, column);
-            if (why)
-                refuse(owner, column, why);
-        }
-    };
-    /**
-     * A relation predicate arrives either bare (`{ user: { email: {...} } }`) or
-     * wrapped in a cardinality operator (`{ user: { is: { email: {...} } } }`),
-     * and BOTH resolve against the relation's target. Walking the wrapper as if
-     * `is` were a column of the target would skip the inner clause entirely, so
-     * descend into every wrapper member AND into the node itself.
-     */
-    const visitRelationValue = (value, target, depth) => {
-        assertWithinDepth(depth);
-        if (!target || value === null || typeof value !== 'object')
-            return;
-        const node = value;
-        for (const wrapper of RELATION_FILTER_WRAPPERS) {
-            if (Object.hasOwn(node, wrapper))
-                visitClause(node[wrapper], target, depth + 1);
-        }
-        visitClause(node, target, depth);
-    };
-    visitClause(args.where, table, 0);
-    visitClause(args.orderBy, table, 0);
+    assertNoPiiPredicatesShared(args, table, {
+        metadata,
+        /**
+         * Why this column may not appear in a predicate, or null when it may.
+         *
+         * The two reasons are the two `sample_rows` already refuses to FETCH
+         * (`classifyHiddenColumns`), and they are deliberately the same set: a
+         * column whose bytes are too sensitive to sample is too sensitive to
+         * binary-search out of the planner. A column absent from the table is not
+         * judged here, the builder rejects it by name a moment later.
+         */
+        hiddenReason: (owner, column) => {
+            if (owner.columns.some((col) => col.name === column && col.pii === true))
+                return 'is PII-tagged';
+            if (SECRET_NAME_PATTERN.test(column))
+                return 'has a secret-looking name';
+            return null;
+        },
+        refuseColumn: (owner, column, why) => {
+            throw jsonRpcError(-32602, `Column "${column}" on "${owner.name}" ${why}, so it cannot be used in a where or orderBy here: ` +
+                `EXPLAIN reports the planner's row estimate, and the estimate for a predicate on a hidden value ` +
+                `reveals that value one character at a time. Filter on a visible column instead.`);
+        },
+        refuseDepth: (maxDepth) => {
+            throw jsonRpcError(-32602, `Query is nested more than ${maxDepth} levels deep, past the point where the PII guard can ` +
+                `prove it does not filter or sort on a tagged column, so it is refused. Flatten the query.`);
+        },
+        refuseShape: (owner, key) => {
+            throw jsonRpcError(-32602, `The PII guard does not recognize "${key}" in a query on "${owner.name}", so it cannot prove the ` +
+                `query does not filter or sort on a hidden column, and refuses it rather than guessing. ` +
+                `Remove it and explain the query without it.`);
+        },
+    });
 }
 /**
  * Extract the allowed findMany subset for explain_query (no `with` / raw SQL).
@@ -862,27 +816,103 @@ async function loadSchemaMetadata(client, options) {
        FROM information_schema.columns
        WHERE table_schema = $1
        ORDER BY table_name, ordinal_position`, [options.schema]),
-        client.query(`SELECT tc.table_name, kcu.column_name
+        client.query(
+        // Joined on the table as well as the constraint name. Not because two
+        // primary keys can share a name (they cannot: a PK is backed by an INDEX,
+        // and index names ARE unique per schema, so Postgres itself refuses the
+        // second `CREATE TABLE ... CONSTRAINT pk_shared PRIMARY KEY` with
+        // `relation "pk_shared" already exists`, verified on PG 16) but because
+        // the join reads as if the name were the identity, which is what put the
+        // FOREIGN KEY query below one refactor away from a silent cross product.
+        // A foreign key has no backing index and so genuinely can collide.
+        `SELECT tc.table_name, kcu.column_name
        FROM information_schema.table_constraints tc
        JOIN information_schema.key_column_usage kcu
-         ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+         ON tc.constraint_name = kcu.constraint_name
+        AND tc.table_schema = kcu.table_schema
+        AND tc.table_name = kcu.table_name
        WHERE tc.constraint_type = 'PRIMARY KEY' AND tc.table_schema = $1
        ORDER BY tc.table_name, kcu.ordinal_position`, [options.schema]),
-        client.query(`SELECT tc.table_name AS source_table, kcu.column_name AS source_column,
-              ccu.table_name AS target_table, ccu.column_name AS target_column, tc.constraint_name
-       FROM information_schema.table_constraints tc
-       JOIN information_schema.key_column_usage kcu
-         ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
-       JOIN information_schema.constraint_column_usage ccu
-         ON tc.constraint_name = ccu.constraint_name AND tc.table_schema = ccu.table_schema
-       WHERE tc.constraint_type = 'FOREIGN KEY' AND tc.table_schema = $1`, [options.schema]),
-        client.query(`SELECT tc.table_name, tc.constraint_name, kcu.column_name
+        // Foreign keys come from pg_catalog, not information_schema, and the reason
+        // is the same one written up over `SQL_FOREIGN_KEYS` in ../introspect.ts
+        // (KEEP THE TWO IN LOCKSTEP: this is a second copy of that query because
+        // introspect.ts does not export it, and mcp reads through its own pooled
+        // client inside a read-only transaction rather than opening the pool
+        // `introspect()` owns). The information_schema formulation this replaces
+        // joined key_column_usage (constrained columns) to constraint_column_usage
+        // (referenced columns) on the constraint NAME, which is wrong twice:
+        //
+        //   1. Those two column lists have no positional link, so the join is an
+        //      N-by-N cross product: a two-column FK came back as four rows and
+        //      grouped into four AND-ed correlations, two of them pairing the wrong
+        //      columns. Every read through the relation silently returned nothing.
+        //   2. A constraint name is unique per TABLE (conrelid, conname), not per
+        //      schema, so two tables may both have a `shared_fk`. This is specific
+        //      to foreign keys: a PRIMARY KEY or UNIQUE constraint is backed by an
+        //      index and index names ARE schema-unique, so Postgres refuses that
+        //      collision outright, while an FK has no backing index and the
+        //      collision is legal. On the name alone the two cross: measured on PG
+        //      16, two tables with a `shared_fk` produced EIGHT rows instead of two,
+        //      which grouped by name into one entry, so one table lost its relation
+        //      entirely and the other pointed at a column its target does not have
+        //      (42703 at query time). Which one won depended on catalog row order.
+        //
+        // conkey and confkey are parallel arrays, so unnesting BOTH `WITH
+        // ORDINALITY` and joining on the ordinal IS the pairing, exactly; the OID is
+        // the grouping key because it is unique catalog-wide.
+        //
+        // The target is constrained to the SAME schema, which is what the old query
+        // did implicitly (it joined on ccu.table_schema). Keeping it explicit
+        // matters: `buildRelations` resolves targets by bare name against the
+        // introspected table set, so a cross-schema reference to a same-named table
+        // would silently bind to the local one.
+        //
+        // `conparentid = 0` (declared constraints only) and the by-NAME ordering are
+        // both part of the lockstep: one FK against a partitioned table otherwise
+        // yields an extra phantom relation per partition, and ordering by `con.oid`
+        // makes relation naming a function of DDL execution order rather than of the
+        // schema. Both are written up at length over SQL_FOREIGN_KEYS.
+        client.query(`SELECT
+         con.oid::text AS constraint_oid,
+         con.conname AS constraint_name,
+         src.relname AS source_table,
+         src_att.attname AS source_column,
+         tgt.relname AS target_table,
+         tgt_att.attname AS target_column
+       FROM pg_catalog.pg_constraint con
+       JOIN pg_catalog.pg_class src ON src.oid = con.conrelid
+       JOIN pg_catalog.pg_namespace src_ns ON src_ns.oid = src.relnamespace
+       JOIN pg_catalog.pg_class tgt ON tgt.oid = con.confrelid
+       JOIN pg_catalog.pg_namespace tgt_ns ON tgt_ns.oid = tgt.relnamespace
+       JOIN LATERAL unnest(con.conkey) WITH ORDINALITY AS sk(attnum, ord) ON TRUE
+       JOIN LATERAL unnest(con.confkey) WITH ORDINALITY AS tk(attnum, ord) ON tk.ord = sk.ord
+       JOIN pg_catalog.pg_attribute src_att
+         ON src_att.attrelid = con.conrelid AND src_att.attnum = sk.attnum
+       JOIN pg_catalog.pg_attribute tgt_att
+         ON tgt_att.attrelid = con.confrelid AND tgt_att.attnum = tk.attnum
+       WHERE con.contype = 'f'
+         AND con.conparentid = 0
+         AND src_ns.nspname = $1
+         AND tgt_ns.nspname = src_ns.nspname
+       ORDER BY src.relname, con.conname, sk.ord`, [options.schema]),
+        client.query(
+        // Joined on the table too, same reasoning as the primary-key query above:
+        // a UNIQUE constraint is index-backed and therefore cannot collide, and
+        // the join says so.
+        `SELECT tc.table_name, tc.constraint_name, kcu.column_name
        FROM information_schema.table_constraints tc
        JOIN information_schema.key_column_usage kcu
-         ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+         ON tc.constraint_name = kcu.constraint_name
+        AND tc.table_schema = kcu.table_schema
+        AND tc.table_name = kcu.table_name
        WHERE tc.constraint_type = 'UNIQUE' AND tc.table_schema = $1
        ORDER BY tc.table_name, tc.constraint_name, kcu.ordinal_position`, [options.schema]),
-        client.query(`SELECT tablename, indexname, indexdef FROM pg_indexes WHERE schemaname = $1`, [options.schema]),
+        client.query(
+        // Ordered for the same reason SQL_INDEXES is: these rows feed the
+        // unique-set detection that decides hasOne-versus-hasMany, and they are
+        // reported verbatim by the schema tools, so physical catalog order must
+        // not leak into either answer. Index names are unique per schema.
+        `SELECT tablename, indexname, indexdef FROM pg_indexes WHERE schemaname = $1 ORDER BY tablename, indexname`, [options.schema]),
         client.query(`SELECT t.typname, e.enumlabel
        FROM pg_type t
        JOIN pg_enum e ON t.oid = e.enumtypid
@@ -969,7 +999,7 @@ async function loadSchemaMetadata(client, options) {
         labels.push(row.enumlabel);
         enums[row.typname] = labels;
     }
-    const relationsByTable = buildRelations(tableNames, columnsByTable, pkByTable, fkResult.rows, enums);
+    const relationsByTable = buildRelations(tableNames, columnsByTable, pkByTable, fkResult.rows, uniqueByTable, indexesByTable, enums);
     const tables = {};
     for (const tableName of tableNames) {
         const columns = columnsByTable.get(tableName) ?? [];
@@ -1031,20 +1061,36 @@ async function loadSchemaMetadata(client, options) {
     return { metadata, piiTags };
 }
 /**
- * Group raw FK rows into constraint-level entries and delegate relation
- * naming to the SHARED introspection builder (`buildRelationsFromForeignKeys`
- * + `addAutoManyToManyRelations` in ../introspect.ts). MCP previously carried
- * a stale copy of a retired naming scheme, so `turbine mcp` and `turbine
- * generate` derived DIFFERENT relation names from the same database.
- * Exported for the parity unit test.
+ * Group raw FK rows into constraint-level entries and delegate relation naming
+ * to `deriveCatalogRelations` in ../introspect.ts, the SAME entry point
+ * `turbine generate` goes through. MCP introspects for itself (it cannot assume
+ * generated metadata exists), so any divergence here is a divergence a live MCP
+ * client trips over: it reads a relation name out of the MCP schema tool, passes
+ * it back in a query, and the core builder rejects it.
+ *
+ * MCP used to assemble the pipeline by hand and drifted twice over, both times
+ * by OMITTING an optional argument, which is silently type-correct and changes
+ * the answer: without `uniqueSetsByTable` a UNIQUE foreign key came back as
+ * `users.profiles` (hasMany) where generate said `users.profile` (hasOne), and
+ * without `uniqueIndexColsByTable` every Prisma-style PK-less junction lost its
+ * auto-m2m relations. Passing the whole input set to one shared function is what
+ * makes those two failures impossible rather than merely fixed.
+ *
+ * `uniqueByTable` and `indexesByTable` are therefore REQUIRED parameters, not
+ * optional ones: an optional catalog input is exactly how the hasOne flip went
+ * missing here in the first place. Exported for the parity unit test.
  */
-export function buildRelations(tableNames, columnsByTable, pkByTable, rows, enums = {}) {
+export function buildRelations(tableNames, columnsByTable, pkByTable, rows, uniqueByTable, indexesByTable, enums = {}) {
     const tableSet = new Set(tableNames);
     const groups = new Map();
     for (const row of rows) {
         if (!tableSet.has(row.source_table) || !tableSet.has(row.target_table))
             continue;
-        const group = groups.get(row.constraint_name) ?? {
+        // Keyed on the constraint OID, never the name: see ForeignKeyRow. The query
+        // orders by (source table, constraint name, source ordinal), so the two
+        // column lists stay paired and the walk order does not depend on the order
+        // the constraints happened to be created in.
+        const group = groups.get(row.constraint_oid) ?? {
             sourceTable: row.source_table,
             sourceColumns: [],
             targetTable: row.target_table,
@@ -1053,20 +1099,17 @@ export function buildRelations(tableNames, columnsByTable, pkByTable, rows, enum
         };
         group.sourceColumns.push(row.source_column);
         group.targetColumns.push(row.target_column);
-        groups.set(row.constraint_name, group);
-    }
-    const foreignKeys = [...groups.values()];
-    const columnFieldsByTable = new Map();
-    const unknownTypedFieldsByTable = new Map();
-    for (const [tbl, cols] of columnsByTable) {
-        columnFieldsByTable.set(tbl, new Set(cols.map((c) => c.field)));
-        // Enum-typed columns also report tsType 'unknown', but the generated type
-        // layer gives them a concrete union, only json/jsonb qualify as shadows.
-        unknownTypedFieldsByTable.set(tbl, new Set(cols.filter((c) => isUnknownTsType(c.tsType) && !Object.hasOwn(enums, c.pgType)).map((c) => c.field)));
+        groups.set(row.constraint_oid, group);
     }
-    const relations = buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable, undefined, unknownTypedFieldsByTable);
-    addAutoManyToManyRelations(tableNames, foreignKeys, pkByTable, new Map(Array.from(columnsByTable, ([tbl, cols]) => [tbl, cols.map((c) => c.name)])), relations, columnFieldsByTable, unknownTypedFieldsByTable);
-    return relations;
+    return deriveCatalogRelations({
+        tableNames,
+        foreignKeys: [...groups.values()],
+        pkByTable,
+        columnsByTable,
+        uniqueByTable,
+        indexesByTable,
+        enums,
+    });
 }
 async function estimateRows(client, schema) {
     const result = await client.query(`SELECT c.relname, c.reltuples::bigint::text AS reltuples
@@ -1079,7 +1122,7 @@ async function estimateRows(client, schema) {
     return counts;
 }
 function requireTable(metadata, tableName) {
-    const table = metadata.tables[tableName];
+    const table = ownLookup(metadata.tables, tableName);
     if (!table) {
         const available = Object.keys(metadata.tables).join(', ') || '(none)';
         throw jsonRpcError(-32602, `Unknown table "${tableName}". Available: ${available}`);

package/dist/cli/migrate.d.ts

@@ -15,6 +15,14 @@ import pg from 'pg';
 import type { DatabaseAdapter } from '../adapters/index.js';
 import { type Dialect } from '../dialect.js';
 import { type DestructiveStatement } from './destructive.js';
+import { splitSqlStatements } from './sql-statements.js';
+/**
+ * Re-exported from `./sql-statements.js`, which owns the one tokenizer this
+ * module and `destructive.js` both speak. It used to live here, and the guard
+ * carried a second, subtly different copy: see that module's header for what
+ * they disagreed about and what it cost.
+ */
+export { splitSqlStatements };
 export interface MigrationFile {
     /** Full filename (e.g. "20260325120000_create_users.sql") */
     filename: string;
@@ -79,6 +87,17 @@ export interface MigrationRunResult {
 }
 /** Extract the YYYYMMDDHHMMSS timestamp prefix from a migration name, or null. */
 export declare function migrationTimestamp(name: string): string | null;
+/**
+ * Refuse any migration in the batch that manages its own transactions.
+ *
+ * `-- turbine:no-transaction` files are exempt: they were never wrapped, so
+ * theirs is a real (and supported) transaction to manage. Pre-flight over the
+ * WHOLE batch, before anything runs, so a bad file at position 3 does not leave
+ * migrations 1 and 2 applied.
+ *
+ * @internal exported for tests.
+ */
+export declare function assertNoEmbeddedTransactions(files: MigrationFile[], section: 'up' | 'down'): void;
 /** Scan a set of migration files' UP sections for data-destroying statements. */
 export declare function collectUpDestructive(files: MigrationFile[]): DestructiveOffender[];
 /**
@@ -86,6 +105,25 @@ export declare function collectUpDestructive(files: MigrationFile[]): Destructiv
  * Expected format: YYYYMMDDHHMMSS_description.sql
  */
 export declare function parseMigrationFilename(filename: string): MigrationFile | null;
+/**
+ * A migration name as it can safely appear in a file's `-- Migration:` header
+ * comment.
+ *
+ * The header sits ABOVE the `-- UP` marker, and the raw CLI argument used to be
+ * interpolated into it verbatim. A `--` comment ends at the first newline, so a
+ * name carrying one closes the comment and everything after it becomes file
+ * content: a name of `x\n-- turbine:no-transaction\n-- UP\nDROP TABLE users;`
+ * wrote both an execution directive and executable SQL into a migration the
+ * user never authored. Only the FILENAME was sanitized, which is the one place
+ * the injection could not reach.
+ *
+ * Collapsing every run of whitespace to a single space is the whole fix: the
+ * argument then cannot leave the one comment line it was written on, and `\s`
+ * covers `\r` and the Unicode line separators too, all of which Postgres also
+ * treats as ending a `--` comment. The readable spelling is preserved, unlike
+ * {@link sanitizeName}, because this is documentation for a human.
+ */
+export declare function headerSafeName(name: string): string;
 /**
  * Sanitize a migration name: lowercase, replace non-alnum with _, collapse duplicates, trim.
  */
@@ -112,24 +150,24 @@ export interface ParsedMigration {
 }
 /**
  * Parse migration content string into UP and DOWN sections plus directives.
+ *
+ * Throws `MigrationError` when the file carries no `-- UP` marker at all.
+ * Returning `{ up: '', down: '' }` there meant the entire file was treated as
+ * preamble and the migration recorded as applied having executed nothing, which
+ * is worse than any error: the database is missing the change and the history
+ * says it is present. `source` (a path) is only used to name the file.
+ *
  * Exported for unit testing.
  */
-export declare function parseMigrationContent(content: string): ParsedMigration;
+export declare function parseMigrationContent(content: string, source?: string): ParsedMigration;
 /**
- * Split a SQL script into individual statements on top-level semicolons.
- *
- * A correct tokenizer, not a `split(';')`: a semicolon inside a single-quoted
- * string (including a backslash-escaping `E'...'` string), a double-quoted
- * identifier, a dollar-quoted body, a line comment
- * (`--`), or a block comment (`/* *\/`, which Postgres allows to nest) must NOT
- * split. This is the one production-destroying failure mode of no-transaction
- * migrations (a partial statement executed against production), so the behavior
- * is pinned by exhaustive unit tests.
+ * Top-level transaction-control statements in a migration body, as displayable
+ * text. Empty for a clean file. Comment- and literal-aware via the shared
+ * tokenizer, so a `COMMIT` inside a comment or a string is not flagged.
  *
- * Comment-only fragments are dropped; every returned statement is trimmed and
- * carries no trailing semicolon.
+ * @internal exported for tests.
  */
-export declare function splitSqlStatements(sql: string): string[];
+export declare function findTransactionControlStatements(body: string): string[];
 /**
  * Parse a migration file into UP and DOWN sections.
  */
@@ -240,6 +278,62 @@ export declare function createMigration(migrationsDir: string, name: string, aut
  * without contending on a single hardcoded lock ID.
  */
 export declare function deriveLockId(databaseName: string): number;
+/**
+ * The connection surface the migration lock needs. `pg.Client` satisfies it;
+ * tests substitute a fake so the dedicated-connection wiring can be exercised
+ * without a database.
+ *
+ * @internal
+ */
+export interface MigrationLockClient {
+    query(sql: string, params?: unknown[]): Promise<unknown>;
+    end(): Promise<void>;
+}
+/** A held (or refused) migration lock, and whatever must be released with it. */
+export interface MigrationLock {
+    /** False when another migration already holds the lock. */
+    acquired: boolean;
+    lockId: number;
+    adapter: DatabaseAdapter;
+    /**
+     * The dedicated connection holding the lock, present only for adapters whose
+     * lock lives in an open transaction. Closed by {@link releaseMigrationLock}.
+     */
+    lockClient?: MigrationLockClient;
+}
+/**
+ * Take the migration lock, on a DEDICATED connection when the adapter needs one.
+ *
+ * The CockroachDB and YugabyteDB adapters lock a row in `_turbine_lock` with
+ * `SELECT ... FOR UPDATE NOWAIT` and deliberately leave that transaction OPEN,
+ * because a row lock only exists for as long as its transaction does. The runner
+ * then applies every migration on the SAME connection, and
+ * `runMigrationInTransaction` issues BEGIN ... COMMIT per file. That COMMIT ends
+ * the LOCK's transaction: from migration 2 onward the run was unprotected, a
+ * concurrent `turbine migrate` could take the lock and replay those files, and
+ * `releaseLock`'s later COMMIT was a no-op that warned rather than failed, so
+ * nothing surfaced. The same collision had a second face: a
+ * `-- turbine:no-transaction` migration running FIRST executed inside the still
+ * open lock transaction, so `CREATE INDEX CONCURRENTLY` failed with "cannot run
+ * inside a transaction block" while the identical file placed second succeeded.
+ *
+ * A second connection separates the two transaction scopes, which is the only
+ * thing that makes the lock outlive a migration. The advisory-lock path (plain
+ * Postgres, AlloyDB, Timescale) is session-scoped rather than
+ * transaction-scoped, opens NO second connection, and is byte-identical to what
+ * it has always done.
+ *
+ * @internal exported for tests.
+ */
+export declare function acquireMigrationLock(runner: MigrationLockClient, lockId: number, adapter: DatabaseAdapter | undefined, openLockConnection: () => Promise<MigrationLockClient>): Promise<MigrationLock>;
+/**
+ * Release a lock taken by {@link acquireMigrationLock}, and close the dedicated
+ * connection when there is one. A refused lock owns nothing, so releasing it is
+ * a no-op rather than an unlock of somebody else's lock.
+ *
+ * @internal exported for tests.
+ */
+export declare function releaseMigrationLock(lock: MigrationLock, runner: MigrationLockClient): Promise<void>;
 /**
  * The minimal query surface a transactional migration body needs.
  * `pg.Client` satisfies it; tests supply a fake.
@@ -327,6 +421,33 @@ export declare function migrateDeploy(connectionString: string, migrationsDir: s
     adapter?: DatabaseAdapter;
     allowDrift?: boolean;
 }): Promise<MigrationRunResult>;
+/**
+ * Roll back a prepared LIFO batch, newest first, stopping at the first
+ * migration that cannot be rolled back.
+ *
+ * A rollback batch is strictly LIFO and must have NO GAPS. The
+ * "file not found" and "no DOWN section" branches used to `continue`, so a
+ * `--step 3` whose middle migration had no DOWN section rolled back 3 and then
+ * 1: the oldest migration's schema was torn down while the data migration 2 had
+ * seeded into it was still expected to exist, and the tracking table was left
+ * claiming migration 2 alone was applied. The next `migrate up` then re-ran 1
+ * and 3 and never re-ran 2, so that data was gone permanently. Both branches
+ * now stop, which is what the SQL-failure branches have always done.
+ *
+ * Split out of {@link migrateDown} so the ordering contract is testable against
+ * a fake client, without a database.
+ *
+ * @internal exported for tests; not part of the CLI's public surface.
+ */
+export declare function rollbackMigrations(client: MigrationTxClient, toRollback: Array<{
+    name: string;
+}>, fileMap: Map<string, MigrationFile>, deleteApplied: string): Promise<{
+    rolledBack: MigrationFile[];
+    errors: Array<{
+        file: MigrationFile;
+        error: string;
+    }>;
+}>;
 /**
  * Rollback the last N migrations (DOWN).
  *