@happyvertical/smrt-core 0.45.3 → 0.46.0

package/dist/migrations/framework-base-tables.d.ts

@@ -0,0 +1,148 @@
+import { DatabaseInterface } from '@happyvertical/sql';
+import { DatabaseEngine } from '../schema/ddl/types.js';
+/**
+ * The exact five orphaned framework-base tables #2644 stopped planning.
+ *
+ * NEVER derive this list from `SchemaDiff.orphan_tables` or any other dynamic
+ * introspection — that would turn this narrow remediation into the same
+ * dangerous global orphan-drop that `includeDroppedTables` deliberately
+ * refuses to be. Every entry is a plain string literal, on purpose.
+ */
+export declare const FRAMEWORK_BASE_TABLE_NAMES: readonly ["smrt_objects", "smrt_classes", "smrt_collections", "smrt_hierarchicals", "smrt_polymorphic_associations"];
+export type FrameworkBaseTableName = (typeof FRAMEWORK_BASE_TABLE_NAMES)[number];
+/** Why a target table was refused. A table can carry more than one. */
+export type FrameworkBaseTableRefusal = {
+    kind: 'not-empty';
+    rowCount: number;
+} | {
+    kind: 'unexpected-shape';
+    actualColumns: string[];
+    missingColumns: string[];
+    extraColumns: string[];
+} | {
+    kind: 'unexpected-column-type';
+    mismatches: Array<{
+        column: string;
+        actualType: string;
+        expectedBuckets: string[];
+    }>;
+} | {
+    kind: 'referenced-by-foreign-key';
+    references: Array<{
+        table: string;
+        column: string;
+    }>;
+} | {
+    kind: 'introspection-unavailable';
+    reason: string;
+};
+/** Plan/refusal findings for one of the five candidate tables. */
+export interface FrameworkBaseTableReport {
+    table: FrameworkBaseTableName;
+    /** Whether this table exists in the live database at all. */
+    exists: boolean;
+    /** `null` when the table does not exist or its row count was not read. */
+    rowCount: number | null;
+    /** Live index names on this table, enumerated from the schema — never guessed. */
+    indexNames: string[];
+    /** Empty when this table (if it exists) is safe to drop. */
+    refusals: FrameworkBaseTableRefusal[];
+}
+/** The full remediation plan: what would be dropped, and why it is or isn't safe. */
+export interface FrameworkBaseTablesPlan {
+    engine: DatabaseEngine;
+    /** One entry per {@link FRAMEWORK_BASE_TABLE_NAMES}, in that order. */
+    tables: FrameworkBaseTableReport[];
+    /** True only when every existing target table has zero refusals. */
+    safe: boolean;
+    /**
+     * The plan for the `--dry-run` preview: `DROP INDEX` for every companion
+     * index (enumerated from the live schema, never guessed) followed by
+     * `DROP TABLE` for its table, per existing target table. Empty when
+     * `safe` is `false` or no target table exists.
+     *
+     * {@link dropFrameworkBaseTables} does not execute the `DROP INDEX`
+     * entries verbatim — see its doc comment for why — so this array is a
+     * complete and accurate *forecast* of what a real run does to the
+     * database, but is not literally replayed statement-by-statement.
+     */
+    statements: string[];
+}
+export interface PlanFrameworkBaseTableDropOptions {
+    /** Adapter hint when the database URL does not identify the engine. */
+    engineHint?: string;
+}
+/**
+ * Read-only preflight: is it safe to drop the five framework-base tables,
+ * and what exactly would that require?
+ *
+ * Never mutates the database. Safe to call for `--dry-run` and as the
+ * required first half of a real run.
+ */
+export declare function planFrameworkBaseTableDrop(db: DatabaseInterface, options?: PlanFrameworkBaseTableDropOptions): Promise<FrameworkBaseTablesPlan>;
+export interface DropFrameworkBaseTablesOptions {
+    /** PostgreSQL lock timeout in milliseconds (defaults to 30 seconds). */
+    lockTimeout?: number;
+    /** PostgreSQL statement timeout in milliseconds (defaults to 60 seconds). */
+    statementTimeout?: number;
+}
+export interface DropFrameworkBaseTablesResult {
+    droppedTables: string[];
+    droppedIndexes: string[];
+}
+/**
+ * Execute a plan produced by {@link planFrameworkBaseTableDrop}.
+ *
+ * Refuses outright when the plan is not `safe` — callers must resolve every
+ * refusal (by fixing the underlying data, or accepting that a table is not a
+ * genuine framework-base table) rather than forcing this function past them.
+ *
+ * On PostgreSQL the whole batch runs in one transaction bounded by
+ * `SET LOCAL lock_timeout` / `SET LOCAL statement_timeout` (#2362), so a
+ * batch that queues behind a long-running writer fails fast and rolls back
+ * instead of holding locks against every writer. Every target is then locked
+ * `IN ACCESS EXCLUSIVE MODE` — a plain `SELECT COUNT(*)` alone only takes an
+ * ACCESS SHARE lock, which would let a concurrent writer commit a row (or a
+ * concurrent DDL session replace the table entirely) between the check and
+ * the DROP; holding the exclusive lock first makes the check-then-drop
+ * sequence atomic.
+ *
+ * Immediately before dropping anything, this re-verifies column shape,
+ * column type, and emptiness inside that same transaction — not just the
+ * row count `planFrameworkBaseTableDrop()` already checked. This uses raw
+ * `information_schema.columns` (PostgreSQL) / `PRAGMA table_info`
+ * (SQLite/DuckDB) queries rather than `getTableSchema()`: `@happyvertical/sql`
+ * does not expose that richer introspection method on the transaction-scoped
+ * connection this callback receives, only `query()`. Foreign keys are
+ * deliberately **not** re-scanned here — doing so would need a fresh
+ * full-catalog scan on every drop.
+ *
+ * On PostgreSQL a foreign key that appeared after planning is still caught:
+ * its FK enforcement is dependency-based, so `DROP TABLE` itself refuses
+ * when a real dependent exists, empty parent or not. **This does not hold
+ * on SQLite** — verified directly: `DROP TABLE` there only checks FK
+ * enforcement against the rows actually being removed, so a parent with
+ * zero rows (exactly the state this function requires) drops cleanly even
+ * with a real, enforced foreign key pointing at it, leaving the referencing
+ * table with a dangling reference. On SQLite/DuckDB, the plan-time
+ * full-catalog scan is therefore the *only* gate against a foreign key on
+ * these two engines — narrower than PostgreSQL's, on top of the
+ * already-documented DuckDB introspection gap in
+ * {@link qualifyIdentifier}'s doc comment where that plan-time scan cannot
+ * see the reference at all. No data is lost either way (the target table is
+ * verified empty before every drop); the residual risk is a dangling
+ * reference in the very narrow window between planning and this
+ * transaction, on either engine, or an FK created after planning at all.
+ *
+ * Only `plan.statements`' `DROP TABLE` entries are executed — the
+ * `DROP INDEX` entries are not. An index name is unique per schema
+ * (PostgreSQL) / globally (SQLite), so nothing re-verifies it is still the
+ * same object between planning and execution the way the table itself now
+ * is; re-issuing a stale `DROP INDEX` by name could hit an unrelated index
+ * created under that name in the meantime. `DROP TABLE` cascades to every
+ * index actually owned by the table on every engine this module supports,
+ * resolved fresh from the database's own catalog at drop time — identity-safe
+ * by construction, unlike a second name-based statement would be.
+ */
+export declare function dropFrameworkBaseTables(db: DatabaseInterface, plan: FrameworkBaseTablesPlan, options?: DropFrameworkBaseTablesOptions): Promise<DropFrameworkBaseTablesResult>;
+//# sourceMappingURL=framework-base-tables.d.ts.map

package/dist/migrations/framework-base-tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework-base-tables.d.ts","sourceRoot":"","sources":["../../src/migrations/framework-base-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAI7D;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,sHAM7B,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAChC,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,CAAC;AAqG9C,uEAAuE;AACvE,MAAM,MAAM,yBAAyB,GACjC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACvC;IACE,IAAI,EAAE,kBAAkB,CAAC;IACzB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,GACD;IACE,IAAI,EAAE,wBAAwB,CAAC;IAC/B,UAAU,EAAE,KAAK,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,eAAe,EAAE,MAAM,EAAE,CAAC;KAC3B,CAAC,CAAC;CACJ,GACD;IACE,IAAI,EAAE,2BAA2B,CAAC;IAClC,UAAU,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtD,GACD;IAAE,IAAI,EAAE,2BAA2B,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,kEAAkE;AAClE,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,sBAAsB,CAAC;IAC9B,6DAA6D;IAC7D,MAAM,EAAE,OAAO,CAAC;IAChB,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,kFAAkF;IAClF,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,4DAA4D;IAC5D,QAAQ,EAAE,yBAAyB,EAAE,CAAC;CACvC;AAED,qFAAqF;AACrF,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,cAAc,CAAC;IACvB,uEAAuE;IACvE,MAAM,EAAE,wBAAwB,EAAE,CAAC;IACnC,oEAAoE;IACpE,IAAI,EAAE,OAAO,CAAC;IACd;;;;;;;;;;OAUG;IACH,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,iCAAiC;IAChD,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAgWD;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC9C,EAAE,EAAE,iBAAiB,EACrB,OAAO,GAAE,iCAAsC,GAC9C,OAAO,CAAC,uBAAuB,CAAC,CAoBlC;AAED,MAAM,WAAW,8BAA8B;IAC7C,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,6BAA6B;IAC5C,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAsB,uBAAuB,CAC3C,EAAE,EAAE,iBAAiB,EACrB,IAAI,EAAE,uBAAuB,EAC7B,OAAO,GAAE,8BAAmC,GAC3C,OAAO,CAAC,6BAA6B,CAAC,CA2GxC"}

package/dist/migrations/framework-base-tables.js

@@ -0,0 +1,419 @@
+import { toSafeInteger } from "../utils/safe-integer.js";
+import { quoteIdentifier } from "../schema/sql-identifiers.js";
+import { detectEngine } from "../schema/ddl/index.js";
+//#region src/migrations/framework-base-tables.ts
+/**
+* The exact five orphaned framework-base tables #2644 stopped planning.
+*
+* NEVER derive this list from `SchemaDiff.orphan_tables` or any other dynamic
+* introspection — that would turn this narrow remediation into the same
+* dangerous global orphan-drop that `includeDroppedTables` deliberately
+* refuses to be. Every entry is a plain string literal, on purpose.
+*/
+var FRAMEWORK_BASE_TABLE_NAMES = [
+	"smrt_objects",
+	"smrt_classes",
+	"smrt_collections",
+	"smrt_hierarchicals",
+	"smrt_polymorphic_associations"
+];
+function classifyColumnType(type) {
+	const normalized = type.toUpperCase().trim().replace(/\(\s*\d+\s*\)/g, "");
+	if (/^UUID$/.test(normalized)) return "uuid";
+	if (/^(TEXT|CLOB|STRING|VARCHAR|CHAR)/.test(normalized)) return "text";
+	if (/^(TIMESTAMP|DATETIME|DATE)/.test(normalized)) return "timestamp";
+	if (/^(INTEGER|INT|BIGINT|SMALLINT|TINYINT)$/.test(normalized)) return "integer";
+	return "other";
+}
+var UNIVERSAL_BASE_BUCKETS = {
+	id: ["text", "uuid"],
+	slug: ["text"],
+	context: ["text"],
+	created_at: ["timestamp"],
+	updated_at: ["timestamp"]
+};
+/**
+* The exact columns (and their expected type buckets) each of the five
+* tables may have — the universal base for three of them, extended for
+* `smrt_hierarchicals` (true parent-id tree: `parent_id`) and
+* `smrt_polymorphic_associations` (generic association: `meta_type`,
+* `meta_id`, `role`, `sort_order`), matching {@link SmrtHierarchical} /
+* {@link SmrtPolymorphicAssociation}'s own real field declarations exactly.
+* Anything more, or anything missing, on any of the five means the live
+* table is not what this remediation expects — most likely a consumer's
+* own unrelated table that happens to share the name — and must be refused
+* rather than guessed about.
+*/
+var EXPECTED_COLUMN_BUCKETS_BY_TABLE = {
+	smrt_objects: UNIVERSAL_BASE_BUCKETS,
+	smrt_classes: UNIVERSAL_BASE_BUCKETS,
+	smrt_collections: UNIVERSAL_BASE_BUCKETS,
+	smrt_hierarchicals: {
+		...UNIVERSAL_BASE_BUCKETS,
+		parent_id: ["text", "uuid"]
+	},
+	smrt_polymorphic_associations: {
+		...UNIVERSAL_BASE_BUCKETS,
+		meta_type: ["text"],
+		meta_id: ["text", "uuid"],
+		role: ["text"],
+		sort_order: ["integer"]
+	}
+};
+var DEFAULT_POSTGRES_LOCK_TIMEOUT_MS = 3e4;
+var DEFAULT_POSTGRES_STATEMENT_TIMEOUT_MS = 6e4;
+function resolveDatabaseUrl(db) {
+	const dbWithConfig = db;
+	return db.url || dbWithConfig.config?.url || "";
+}
+/**
+* Qualify a table or index identifier so execution resolves to exactly the
+* object inspection looked at.
+*
+* `getExistingTableNames()` and `getTableSchema()` both scope PostgreSQL
+* discovery to the `public` schema, but a plain `quoteIdentifier(name)` in a
+* `SELECT`/`DROP` statement resolves through the session's `search_path`
+* instead — which can list another schema before `public`. An empty,
+* unrelated same-named table or index earlier on that path would otherwise
+* satisfy every safety check yet let the DROP hit a different object than
+* the one just verified. SQLite and DuckDB have no equivalent search-path
+* ambiguity for this module's purposes, so only PostgreSQL is schema-qualified.
+*
+* Known limitation, documented rather than fixed: this module (like
+* `differ.ts` and `live-parity.ts` elsewhere in this package) only ever
+* discovers PostgreSQL objects in the `public` schema — multi-schema
+* PostgreSQL deployments are not a supported SMRT configuration anywhere in
+* this package. A table in a *different* schema with a foreign key onto one
+* of these five names is therefore invisible to the `referenced-by-foreign-key`
+* check. It is not, however, an actual data-loss risk: PostgreSQL's own
+* foreign-key enforcement refuses the `DROP TABLE` at execution time
+* ("cannot drop table ... because other objects depend on it") inside this
+* module's bounded transaction, so nothing is still dropped — exactly the
+* same fail-safe shape as the documented DuckDB foreign-key gap below, just
+* surfaced as a generic execution error instead of a curated refusal.
+*/
+function qualifyIdentifier(engine, name) {
+	return engine === "postgres" ? `"public".${quoteIdentifier(name)}` : quoteIdentifier(name);
+}
+async function getExistingTableNames(db, engine) {
+	const query = engine === "postgres" ? `SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'` : `SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'`;
+	const rows = (await db.query(query)).rows;
+	return new Set(rows.map((row) => row.name || row.table_name || "").filter(Boolean));
+}
+async function countRows(db, engine, table) {
+	return toSafeInteger((await db.query(`SELECT COUNT(*) AS row_count FROM ${qualifyIdentifier(engine, table)}`)).rows?.[0]?.row_count ?? 0, `Framework base-table row count for ${table}`);
+}
+/**
+* Render a millisecond timeout as a PostgreSQL interval literal.
+*
+* Mirrors `formatPostgresTimeout` in `migrations/tracker.ts` (#2362) — kept
+* as a tiny local copy rather than an import so this module stays a
+* self-contained, easily audited remediation rather than reaching into the
+* migration tracker's internals for one string helper.
+*/
+function formatPostgresTimeout(milliseconds) {
+	return `${Math.max(0, Math.trunc(milliseconds))}ms`;
+}
+/**
+* Column name → declared type, read with a query every engine supports
+* *inside a transaction* — unlike `getTableSchema()`, which
+* `@happyvertical/sql` does not expose on the connection object a
+* `db.transaction()` callback receives (verified directly: `typeof
+* tx.getTableSchema` is `undefined`). Used only for the execution-time
+* re-check in {@link dropFrameworkBaseTables}; planning uses the richer
+* `getTableSchema()` on the ordinary (non-transactional) connection.
+*
+* Returns `null` when the table cannot be described right now — SQLite
+* returns zero rows for an unknown table, DuckDB instead throws a Catalog
+* Error (caught below) — either way meaning "cannot confirm this is safe",
+* which must fail closed exactly like a table that no longer exists.
+*/
+async function inspectColumnTypes(db, engine, table) {
+	try {
+		if (engine === "postgres") {
+			const rows = (await db.query(`SELECT column_name, data_type FROM information_schema.columns WHERE table_schema = 'public' AND table_name = $1`, table)).rows;
+			if (rows.length === 0) return null;
+			const columns = {};
+			for (const row of rows) columns[row.column_name] = row.data_type;
+			return columns;
+		}
+		const rows = (await db.query(`PRAGMA table_info(${quoteIdentifier(table)})`)).rows;
+		if (rows.length === 0) return null;
+		const columns = {};
+		for (const row of rows) if (row.name) columns[row.name] = row.type ?? "";
+		return columns;
+	} catch {
+		return null;
+	}
+}
+/**
+* Compare a freshly-read column map against `table`'s expected shape/type,
+* returning a human-readable reason it is unsafe, or `null` when it matches
+* exactly. Shared by the execution-time re-check so its comparison logic
+* cannot drift from {@link assessTargets}'s own definitions
+* ({@link EXPECTED_COLUMN_BUCKETS_BY_TABLE}, {@link classifyColumnType}).
+*/
+function describeColumnMismatch(table, columns) {
+	const expectedBuckets = EXPECTED_COLUMN_BUCKETS_BY_TABLE[table];
+	const expectedColumns = Object.keys(expectedBuckets);
+	const actualColumns = Object.keys(columns).sort();
+	const missingColumns = expectedColumns.filter((column) => !(column in columns));
+	const extraColumns = actualColumns.filter((column) => !(column in expectedBuckets));
+	if (missingColumns.length > 0 || extraColumns.length > 0) return `unexpected column shape (actual columns: ${actualColumns.join(", ")})`;
+	const typeMismatches = expectedColumns.map((column) => {
+		const actualType = columns[column] ?? "";
+		const bucket = classifyColumnType(actualType);
+		return expectedBuckets[column].includes(bucket) ? null : `${column} is "${actualType}"`;
+	}).filter((entry) => entry !== null);
+	if (typeMismatches.length > 0) return `unexpected column type (${typeMismatches.join(", ")})`;
+	return null;
+}
+/**
+* Read-only assessment: for each of the five target names, is it safe to
+* drop, and why or why not?
+*
+* Used only by {@link planFrameworkBaseTableDrop}'s unlocked preflight, via
+* `getTableSchema()`. {@link dropFrameworkBaseTables}'s own execution-time
+* re-check does **not** call this function or reuse its logic wholesale: it
+* re-verifies shape and type from raw `information_schema.columns` /
+* `PRAGMA table_info` instead, because `getTableSchema()` is not available
+* on the transaction-scoped connection a `db.transaction()` callback
+* receives (see that function's own doc comment for the full rationale,
+* including why foreign keys are deliberately not re-scanned there). Never
+* mutates the database.
+*/
+async function assessTargets(db, engine) {
+	if (typeof db.getTableSchema !== "function") {
+		const existingTableNames = await getExistingTableNames(db, engine);
+		const tables = FRAMEWORK_BASE_TABLE_NAMES.map((name) => existingTableNames.has(name) ? {
+			table: name,
+			exists: true,
+			rowCount: null,
+			indexNames: [],
+			refusals: [{
+				kind: "introspection-unavailable",
+				reason: "The configured database adapter cannot describe tables (`getTableSchema` is unavailable), so table shape cannot be verified."
+			}]
+		} : {
+			table: name,
+			exists: false,
+			rowCount: null,
+			indexNames: [],
+			refusals: []
+		});
+		return {
+			tables,
+			safe: tables.every((table) => table.refusals.length === 0)
+		};
+	}
+	const existingTableNames = await getExistingTableNames(db, engine);
+	const inboundForeignKeys = /* @__PURE__ */ new Map();
+	for (const liveTable of existingTableNames) {
+		const liveSchema = await db.getTableSchema(liveTable);
+		for (const foreignKey of liveSchema?.foreignKeys ?? []) {
+			const references = inboundForeignKeys.get(foreignKey.referencesTable) ?? [];
+			references.push({
+				table: liveTable,
+				column: foreignKey.column
+			});
+			inboundForeignKeys.set(foreignKey.referencesTable, references);
+		}
+	}
+	const tables = [];
+	let safe = true;
+	for (const name of FRAMEWORK_BASE_TABLE_NAMES) {
+		if (!existingTableNames.has(name)) {
+			tables.push({
+				table: name,
+				exists: false,
+				rowCount: null,
+				indexNames: [],
+				refusals: []
+			});
+			continue;
+		}
+		const schema = await db.getTableSchema(name);
+		const refusals = [];
+		if (!schema) {
+			refusals.push({
+				kind: "introspection-unavailable",
+				reason: `getTableSchema("${name}") returned no result even though the table exists.`
+			});
+			tables.push({
+				table: name,
+				exists: true,
+				rowCount: null,
+				indexNames: [],
+				refusals
+			});
+			safe = false;
+			continue;
+		}
+		const expectedBucketsForTable = EXPECTED_COLUMN_BUCKETS_BY_TABLE[name];
+		const expectedColumnsForTable = Object.keys(expectedBucketsForTable);
+		const actualColumns = Object.keys(schema.columns).sort();
+		const missingColumns = expectedColumnsForTable.filter((column) => !schema.columns[column]);
+		const extraColumns = actualColumns.filter((column) => !(column in expectedBucketsForTable));
+		if (missingColumns.length > 0 || extraColumns.length > 0) refusals.push({
+			kind: "unexpected-shape",
+			actualColumns,
+			missingColumns,
+			extraColumns
+		});
+		else {
+			const mismatches = expectedColumnsForTable.map((column) => {
+				const actualType = schema.columns[column]?.type ?? "";
+				const bucket = classifyColumnType(actualType);
+				const expectedBuckets = expectedBucketsForTable[column];
+				return expectedBuckets.includes(bucket) ? null : {
+					column,
+					actualType,
+					expectedBuckets: [...expectedBuckets]
+				};
+			}).filter((mismatch) => mismatch !== null);
+			if (mismatches.length > 0) refusals.push({
+				kind: "unexpected-column-type",
+				mismatches
+			});
+		}
+		const references = inboundForeignKeys.get(name) ?? [];
+		if (references.length > 0) refusals.push({
+			kind: "referenced-by-foreign-key",
+			references
+		});
+		const rowCount = await countRows(db, engine, name);
+		if (rowCount > 0) refusals.push({
+			kind: "not-empty",
+			rowCount
+		});
+		const indexNames = (schema.indexes ?? []).map((index) => index.name);
+		if (refusals.length > 0) safe = false;
+		tables.push({
+			table: name,
+			exists: true,
+			rowCount,
+			indexNames,
+			refusals
+		});
+	}
+	return {
+		tables,
+		safe
+	};
+}
+/**
+* Read-only preflight: is it safe to drop the five framework-base tables,
+* and what exactly would that require?
+*
+* Never mutates the database. Safe to call for `--dry-run` and as the
+* required first half of a real run.
+*/
+async function planFrameworkBaseTableDrop(db, options = {}) {
+	const engine = detectEngine(resolveDatabaseUrl(db), options.engineHint);
+	const { tables, safe } = await assessTargets(db, engine);
+	const statements = [];
+	if (safe) for (const table of tables) {
+		if (!table.exists) continue;
+		for (const indexName of table.indexNames) statements.push(`DROP INDEX IF EXISTS ${qualifyIdentifier(engine, indexName)}`);
+		statements.push(`DROP TABLE IF EXISTS ${qualifyIdentifier(engine, table.table)}`);
+	}
+	return {
+		engine,
+		tables,
+		safe,
+		statements
+	};
+}
+/**
+* Execute a plan produced by {@link planFrameworkBaseTableDrop}.
+*
+* Refuses outright when the plan is not `safe` — callers must resolve every
+* refusal (by fixing the underlying data, or accepting that a table is not a
+* genuine framework-base table) rather than forcing this function past them.
+*
+* On PostgreSQL the whole batch runs in one transaction bounded by
+* `SET LOCAL lock_timeout` / `SET LOCAL statement_timeout` (#2362), so a
+* batch that queues behind a long-running writer fails fast and rolls back
+* instead of holding locks against every writer. Every target is then locked
+* `IN ACCESS EXCLUSIVE MODE` — a plain `SELECT COUNT(*)` alone only takes an
+* ACCESS SHARE lock, which would let a concurrent writer commit a row (or a
+* concurrent DDL session replace the table entirely) between the check and
+* the DROP; holding the exclusive lock first makes the check-then-drop
+* sequence atomic.
+*
+* Immediately before dropping anything, this re-verifies column shape,
+* column type, and emptiness inside that same transaction — not just the
+* row count `planFrameworkBaseTableDrop()` already checked. This uses raw
+* `information_schema.columns` (PostgreSQL) / `PRAGMA table_info`
+* (SQLite/DuckDB) queries rather than `getTableSchema()`: `@happyvertical/sql`
+* does not expose that richer introspection method on the transaction-scoped
+* connection this callback receives, only `query()`. Foreign keys are
+* deliberately **not** re-scanned here — doing so would need a fresh
+* full-catalog scan on every drop.
+*
+* On PostgreSQL a foreign key that appeared after planning is still caught:
+* its FK enforcement is dependency-based, so `DROP TABLE` itself refuses
+* when a real dependent exists, empty parent or not. **This does not hold
+* on SQLite** — verified directly: `DROP TABLE` there only checks FK
+* enforcement against the rows actually being removed, so a parent with
+* zero rows (exactly the state this function requires) drops cleanly even
+* with a real, enforced foreign key pointing at it, leaving the referencing
+* table with a dangling reference. On SQLite/DuckDB, the plan-time
+* full-catalog scan is therefore the *only* gate against a foreign key on
+* these two engines — narrower than PostgreSQL's, on top of the
+* already-documented DuckDB introspection gap in
+* {@link qualifyIdentifier}'s doc comment where that plan-time scan cannot
+* see the reference at all. No data is lost either way (the target table is
+* verified empty before every drop); the residual risk is a dangling
+* reference in the very narrow window between planning and this
+* transaction, on either engine, or an FK created after planning at all.
+*
+* Only `plan.statements`' `DROP TABLE` entries are executed — the
+* `DROP INDEX` entries are not. An index name is unique per schema
+* (PostgreSQL) / globally (SQLite), so nothing re-verifies it is still the
+* same object between planning and execution the way the table itself now
+* is; re-issuing a stale `DROP INDEX` by name could hit an unrelated index
+* created under that name in the meantime. `DROP TABLE` cascades to every
+* index actually owned by the table on every engine this module supports,
+* resolved fresh from the database's own catalog at drop time — identity-safe
+* by construction, unlike a second name-based statement would be.
+*/
+async function dropFrameworkBaseTables(db, plan, options = {}) {
+	if (!plan.safe) throw new Error("Refusing to drop framework base tables: the plan reported at least one unsafe table. Re-run planFrameworkBaseTableDrop() and resolve every refusal first — nothing was dropped.");
+	const targets = plan.tables.filter((table) => table.exists);
+	if (targets.length === 0) return {
+		droppedTables: [],
+		droppedIndexes: []
+	};
+	if (!db.transaction) throw new Error("Dropping framework base tables requires a database adapter with transaction support.");
+	const lockTimeoutMs = options.lockTimeout ?? DEFAULT_POSTGRES_LOCK_TIMEOUT_MS;
+	const statementTimeoutMs = options.statementTimeout ?? DEFAULT_POSTGRES_STATEMENT_TIMEOUT_MS;
+	const isPostgres = plan.engine === "postgres";
+	await db.transaction(async (tx) => {
+		if (isPostgres) {
+			await tx.query(`SET LOCAL lock_timeout = '${formatPostgresTimeout(lockTimeoutMs)}'`);
+			await tx.query(`SET LOCAL statement_timeout = '${formatPostgresTimeout(statementTimeoutMs)}'`);
+		}
+		if (isPostgres) for (const table of targets) await tx.query(`LOCK TABLE ${qualifyIdentifier(plan.engine, table.table)} IN ACCESS EXCLUSIVE MODE`);
+		for (const target of targets) {
+			const liveColumns = await inspectColumnTypes(tx, plan.engine, target.table);
+			if (!liveColumns) throw new Error(`Refusing to drop "${target.table}": it could not be re-verified inside the transaction (it may no longer exist). Nothing was dropped.`);
+			const mismatch = describeColumnMismatch(target.table, liveColumns);
+			if (mismatch) throw new Error(`Refusing to drop "${target.table}": a fresh check inside the transaction found an ${mismatch}. Nothing was dropped.`);
+			const rowCount = await countRows(tx, plan.engine, target.table);
+			if (rowCount > 0) throw new Error(`Refusing to drop "${target.table}": it now has ${rowCount} row(s) though it was empty when planned. Nothing was dropped.`);
+		}
+		for (const statement of plan.statements) {
+			if (statement.startsWith("DROP INDEX")) continue;
+			await tx.query(statement);
+		}
+	});
+	return {
+		droppedTables: targets.map((table) => table.table),
+		droppedIndexes: targets.flatMap((table) => table.indexNames)
+	};
+}
+//#endregion
+export { FRAMEWORK_BASE_TABLE_NAMES, dropFrameworkBaseTables, planFrameworkBaseTableDrop };
+
+//# sourceMappingURL=framework-base-tables.js.map