@happyvertical/smrt-core 0.40.70 → 0.42.0

package/dist/migrations/integer-width.d.ts

@@ -0,0 +1,99 @@
+import { DatabaseInterface } from '@happyvertical/sql';
+import { SchemaDefinition } from '../schema/types.js';
+/** A table and its SMRT-owned integer columns. */
+export interface IntegerWidthTarget {
+    table: string;
+    columns: string[];
+}
+/** The width state of one declared integer column. */
+export type IntegerWidthColumnState = 'pending' | 'current' | 'missing' | 'unexpected';
+/** Preflight finding for one declared integer column. */
+export interface IntegerWidthColumnReport {
+    table: string;
+    column: string;
+    state: IntegerWidthColumnState;
+    /** Live `information_schema.columns.data_type`, when the column exists. */
+    declaredType: string | null;
+}
+/** Preflight findings for a single SMRT-owned table. */
+export interface IntegerWidthTableReport {
+    table: string;
+    /** Number of rows when at least one column still needs widening. */
+    rowCount: number | null;
+    columns: IntegerWidthColumnReport[];
+}
+/** Read-only assessment of a deployment's legacy int4 columns. */
+export interface IntegerWidthPreflightResult {
+    engine: string;
+    /** False for SQLite and adapters without a native 32-bit integer width. */
+    supported: boolean;
+    tables: IntegerWidthTableReport[];
+    pendingColumns: number;
+    currentColumns: number;
+    missingColumns: number;
+    unexpectedColumns: number;
+    /** Tables that need a maintenance-window table rewrite. */
+    pendingTables: number;
+    /** Human-readable output suitable for an operator change record. */
+    summary: string;
+}
+/** Shared options for the read-only preflight and mutating widening pass. */
+export interface IntegerWidthOptions {
+    /** Adapter hint when its URL does not identify the engine. */
+    engineHint?: string;
+}
+/** Options that make the widening pass safely repeatable. */
+export interface IntegerWidthWidenOptions extends IntegerWidthOptions {
+    /** Stable `_smrt_backfills` audit marker, unique to this migration owner. */
+    backfillName: string;
+    /** Package recorded alongside the marker. */
+    packageName?: string;
+    /** PostgreSQL lock timeout in milliseconds (defaults to 30 seconds). */
+    lockTimeout?: number;
+    /** PostgreSQL statement timeout in milliseconds (defaults to 60 seconds). */
+    statementTimeout?: number;
+}
+/** Result of {@link widenIntegerColumnsToBigInt}. */
+export interface IntegerWidthWidenResult {
+    /** False when no legacy columns remain or the engine is unsupported. */
+    ran: boolean;
+    preflight: IntegerWidthPreflightResult;
+    widenedColumns: Array<{
+        table: string;
+        column: string;
+    }>;
+    statements: string[];
+}
+/**
+ * Collect every integer column owned by loaded application schemas and, when
+ * requested, by hand-written core system-table DDL.
+ */
+export declare function collectIntegerWidthTargets(schemas: Record<string, SchemaDefinition>, options?: {
+    includeSystemTables?: boolean;
+}): IntegerWidthTarget[];
+/** Build the exact, lossless ALTER statement for one target column. */
+export declare function buildIntegerWidthStatements(engine: string, table: string, column: string): string[];
+/**
+ * Build lossless widening statements for every pending column in one table.
+ *
+ * PostgreSQL performs a table rewrite for an integer-width change, so all of
+ * one table's pending columns must share one ALTER TABLE and one lock window.
+ * DuckDB keeps its one-column form because its ALTER COLUMN grammar is not
+ * equivalently composable across supported adapter versions.
+ */
+export declare function buildIntegerWidthTableStatements(engine: string, table: string, columns: string[]): string[];
+/**
+ * Inspect explicit SMRT-owned integer targets without changing the database.
+ *
+ * PostgreSQL and DuckDB expose their live widths through
+ * `information_schema.columns`. SQLite is deliberately a no-op because its
+ * INTEGER storage class already holds signed 64-bit values.
+ */
+export declare function preflightIntegerWidthWidening(db: DatabaseInterface, targets: IntegerWidthTarget[], options?: IntegerWidthOptions): Promise<IntegerWidthPreflightResult>;
+/**
+ * Widen legacy int4 columns to BIGINT and record a marker after every ALTER
+ * succeeds. This is intentionally never called by normal schema migration or
+ * framework bootstrap: PostgreSQL rewrites each altered table.
+ */
+export declare function widenIntegerColumnsToBigInt(db: DatabaseInterface, targets: IntegerWidthTarget[], options: IntegerWidthWidenOptions): Promise<IntegerWidthWidenResult>;
+//# sourceMappingURL=integer-width.d.ts.map

package/dist/migrations/integer-width.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integer-width.d.ts","sourceRoot":"","sources":["../../src/migrations/integer-width.ts"],"names":[],"mappings":"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"}

package/dist/migrations/integer-width.js

@@ -0,0 +1,237 @@
+import { toSafeInteger } from "../utils/safe-integer.js";
+import { detectEngine } from "../schema/ddl/index.js";
+import { getSystemTableShapes } from "../schema/system-table-shapes.js";
+import { parsePostgresTimeoutMs } from "../postgres-timeouts.js";
+import { BackfillTracker } from "./backfill-tracker.js";
+//#region src/migrations/integer-width.ts
+var DEFAULT_POSTGRES_LOCK_TIMEOUT_MS = 3e4;
+var DEFAULT_POSTGRES_STATEMENT_TIMEOUT_MS = 6e4;
+/**
+* Collect every integer column owned by loaded application schemas and, when
+* requested, by hand-written core system-table DDL.
+*/
+function collectIntegerWidthTargets(schemas, options = {}) {
+	const byTable = /* @__PURE__ */ new Map();
+	const add = (table, column) => {
+		if (!byTable.has(table)) byTable.set(table, /* @__PURE__ */ new Set());
+		byTable.get(table)?.add(column);
+	};
+	for (const [key, schema] of Object.entries(schemas)) {
+		const table = schema?.tableName || key;
+		for (const [column, definition] of Object.entries(schema?.columns ?? {})) if (definition.type === "INTEGER") add(table, column);
+	}
+	if (options.includeSystemTables ?? true) {
+		for (const shape of getSystemTableShapes("postgres").values()) for (const column of shape.columns) if (isBigIntType(column.type)) add(shape.tableName, column.name);
+	}
+	return [...byTable].map(([table, columns]) => ({
+		table,
+		columns: [...columns].sort()
+	})).sort((left, right) => left.table.localeCompare(right.table));
+}
+/** Build the exact, lossless ALTER statement for one target column. */
+function buildIntegerWidthStatements(engine, table, column) {
+	return buildIntegerWidthTableStatements(engine, table, [column]);
+}
+/**
+* Build lossless widening statements for every pending column in one table.
+*
+* PostgreSQL performs a table rewrite for an integer-width change, so all of
+* one table's pending columns must share one ALTER TABLE and one lock window.
+* DuckDB keeps its one-column form because its ALTER COLUMN grammar is not
+* equivalently composable across supported adapter versions.
+*/
+function buildIntegerWidthTableStatements(engine, table, columns) {
+	const quotedTable = quoteIdentifier(table);
+	const quotedColumns = columns.map(quoteIdentifier);
+	if (quotedColumns.length === 0) return [];
+	if (engine !== "postgres" && engine !== "duckdb") return [];
+	if (engine === "postgres") return [`ALTER TABLE ${quotedTable} ${quotedColumns.map((column) => `ALTER COLUMN ${column} TYPE BIGINT`).join(", ")}`];
+	return quotedColumns.map((column) => `ALTER TABLE ${quotedTable} ALTER COLUMN ${column} TYPE BIGINT`);
+}
+/**
+* Inspect explicit SMRT-owned integer targets without changing the database.
+*
+* PostgreSQL and DuckDB expose their live widths through
+* `information_schema.columns`. SQLite is deliberately a no-op because its
+* INTEGER storage class already holds signed 64-bit values.
+*/
+async function preflightIntegerWidthWidening(db, targets, options = {}) {
+	const engine = resolveEngine(db, options.engineHint);
+	const normalizedTargets = normalizeTargets(targets);
+	if (engine !== "postgres" && engine !== "duckdb") return {
+		engine,
+		supported: false,
+		tables: [],
+		pendingColumns: 0,
+		currentColumns: 0,
+		missingColumns: 0,
+		unexpectedColumns: 0,
+		pendingTables: 0,
+		summary: `Integer-width widening preflight (engine=${engine}): not applicable; this engine does not expose a distinct native int4 storage type.`
+	};
+	const tables = [];
+	for (const target of normalizedTargets) {
+		const types = await readColumnTypes(db, engine, target.table);
+		const columns = target.columns.map((column) => {
+			const declaredType = types.get(column) ?? null;
+			return {
+				table: target.table,
+				column,
+				declaredType,
+				state: classifyIntegerWidth(declaredType)
+			};
+		});
+		const needsWidening = columns.some((column) => column.state === "pending");
+		tables.push({
+			table: target.table,
+			rowCount: needsWidening ? await countRows(db, target.table) : null,
+			columns
+		});
+	}
+	const allColumns = tables.flatMap((table) => table.columns);
+	const result = {
+		engine,
+		supported: true,
+		tables,
+		pendingColumns: allColumns.filter((column) => column.state === "pending").length,
+		currentColumns: allColumns.filter((column) => column.state === "current").length,
+		missingColumns: allColumns.filter((column) => column.state === "missing").length,
+		unexpectedColumns: allColumns.filter((column) => column.state === "unexpected").length,
+		pendingTables: tables.filter((table) => table.columns.some((column) => column.state === "pending")).length
+	};
+	return {
+		...result,
+		summary: renderSummary(result)
+	};
+}
+/**
+* Widen legacy int4 columns to BIGINT and record a marker after every ALTER
+* succeeds. This is intentionally never called by normal schema migration or
+* framework bootstrap: PostgreSQL rewrites each altered table.
+*/
+async function widenIntegerColumnsToBigInt(db, targets, options) {
+	const preflight = await preflightIntegerWidthWidening(db, targets, options);
+	if (!preflight.supported) return {
+		ran: false,
+		preflight,
+		widenedColumns: [],
+		statements: []
+	};
+	if (preflight.unexpectedColumns > 0) throw new Error("Integer-width widening refused because declared integer columns have unexpected live types. Resolve ordinary schema drift first.\n" + preflight.summary);
+	if (preflight.pendingColumns === 0) return {
+		ran: false,
+		preflight,
+		widenedColumns: [],
+		statements: []
+	};
+	const statements = [];
+	const widenedColumns = [];
+	await new BackfillTracker({ db }).initialize();
+	const applyWidening = async (writeDb) => {
+		for (const table of preflight.tables) {
+			const pendingColumns = table.columns.filter((column) => column.state === "pending").map((column) => column.column);
+			if (pendingColumns.length === 0) continue;
+			for (const sql of buildIntegerWidthTableStatements(preflight.engine, table.table, pendingColumns)) {
+				await writeDb.query(sql);
+				statements.push(sql);
+			}
+			widenedColumns.push(...pendingColumns.map((column) => ({
+				table: table.table,
+				column
+			})));
+		}
+		await new BackfillTracker({ db: writeDb }).recordApplied(options.backfillName, {
+			description: "Widened legacy int4 SMRT columns to BIGINT after #2373 changed fresh-schema defaults.",
+			packageName: options.packageName
+		});
+	};
+	if (preflight.engine === "postgres") {
+		if (!db.transaction) throw new Error("Integer-width widening on PostgreSQL requires transaction support.");
+		const lockTimeout = parsePostgresTimeoutMs(options.lockTimeout, DEFAULT_POSTGRES_LOCK_TIMEOUT_MS);
+		const statementTimeout = parsePostgresTimeoutMs(options.statementTimeout, DEFAULT_POSTGRES_STATEMENT_TIMEOUT_MS);
+		await db.transaction(async (tx) => {
+			const txDb = {
+				...tx,
+				transaction: async (callback) => callback(tx)
+			};
+			BackfillTracker.inheritInitialization(txDb, db);
+			await txDb.query(`SET LOCAL lock_timeout = '${formatPostgresTimeout(lockTimeout)}'`);
+			await txDb.query(`SET LOCAL statement_timeout = '${formatPostgresTimeout(statementTimeout)}'`);
+			await applyWidening(txDb);
+		});
+	} else await applyWidening(db);
+	return {
+		ran: true,
+		preflight,
+		widenedColumns,
+		statements
+	};
+}
+function resolveEngine(db, engineHint) {
+	const dbWithConfig = db;
+	return detectEngine(db.url || dbWithConfig.config?.url || "", engineHint);
+}
+function normalizeTargets(targets) {
+	const byTable = /* @__PURE__ */ new Map();
+	for (const target of targets) {
+		quoteIdentifier(target.table);
+		if (!byTable.has(target.table)) byTable.set(target.table, /* @__PURE__ */ new Set());
+		for (const column of target.columns) {
+			quoteIdentifier(column);
+			byTable.get(target.table)?.add(column);
+		}
+	}
+	return [...byTable].map(([table, columns]) => ({
+		table,
+		columns: [...columns].sort()
+	})).sort((left, right) => left.table.localeCompare(right.table));
+}
+function quoteIdentifier(name) {
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new Error(`Integer-width widening: '${name}' is not a plain SQL identifier.`);
+	return `"${name}"`;
+}
+function formatPostgresTimeout(milliseconds) {
+	return `${milliseconds}ms`;
+}
+function isLegacyInt4Type(type) {
+	return /^(INTEGER|INT|INT4)$/i.test(type.trim());
+}
+function isBigIntType(type) {
+	return /^(BIGINT|INT8)$/i.test(type.trim());
+}
+function classifyIntegerWidth(type) {
+	if (type === null) return "missing";
+	if (isLegacyInt4Type(type)) return "pending";
+	if (isBigIntType(type)) return "current";
+	return "unexpected";
+}
+async function readColumnTypes(db, engine, table) {
+	const result = await db.query(engine === "postgres" ? `SELECT column_name, data_type
+           FROM information_schema.columns
+          WHERE table_schema = current_schema() AND table_name = ?` : `SELECT column_name, data_type
+           FROM information_schema.columns
+          WHERE table_name = ?`, table);
+	const types = /* @__PURE__ */ new Map();
+	for (const row of result.rows) if (typeof row.column_name === "string") types.set(row.column_name, String(row.data_type ?? ""));
+	return types;
+}
+async function countRows(db, table) {
+	return toSafeInteger((await db.query(`SELECT COUNT(*) AS row_count FROM ${quoteIdentifier(table)}`)).rows?.[0]?.row_count ?? 0, `Integer-width row count for ${table}`);
+}
+function renderSummary(result) {
+	const lines = [
+		`Integer-width widening preflight (engine=${result.engine})`,
+		`  tables: ${result.pendingTables} pending`,
+		`  columns: ${result.pendingColumns} pending, ${result.currentColumns} already BIGINT, ${result.missingColumns} missing, ${result.unexpectedColumns} unexpected`
+	];
+	for (const table of result.tables) {
+		const pending = table.columns.filter((column) => column.state === "pending");
+		if (pending.length === 0) continue;
+		lines.push(`  - ${table.table}: ${table.rowCount ?? 0} row(s); ${pending.map((column) => `${column.column} (${column.declaredType})`).join(", ")}`);
+	}
+	return lines.join("\n");
+}
+//#endregion
+export { buildIntegerWidthStatements, buildIntegerWidthTableStatements, collectIntegerWidthTargets, preflightIntegerWidthWidening, widenIntegerColumnsToBigInt };
+
+//# sourceMappingURL=integer-width.js.map

package/dist/migrations/integer-width.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integer-width.js","names":[],"sources":["../../src/migrations/integer-width.ts"],"sourcesContent":["/**\n * Explicit one-time widening for deployments created before #2373.\n *\n * Fresh PostgreSQL and DuckDB schemas now materialize SMRT's abstract\n * `INTEGER` as `BIGINT`. The migration differ deliberately treats int4 and\n * int8 as equivalent, so existing deployments need this separate, operator\n * initiated maintenance-window migration rather than an automatic repair.\n */\n\nimport type { DatabaseInterface } from '@happyvertical/sql';\nimport { parsePostgresTimeoutMs } from '../postgres-timeouts.js';\nimport { detectEngine } from '../schema/ddl/index.js';\nimport { getSystemTableShapes } from '../schema/system-table-shapes.js';\nimport type { SchemaDefinition } from '../schema/types.js';\nimport { toSafeInteger } from '../utils/safe-integer.js';\nimport { BackfillTracker } from './backfill-tracker.js';\n\nconst DEFAULT_POSTGRES_LOCK_TIMEOUT_MS = 30_000;\nconst DEFAULT_POSTGRES_STATEMENT_TIMEOUT_MS = 60_000;\n\n/** A table and its SMRT-owned integer columns. */\nexport interface IntegerWidthTarget {\n  table: string;\n  columns: string[];\n}\n\n/** The width state of one declared integer column. */\nexport type IntegerWidthColumnState =\n  | 'pending'\n  | 'current'\n  | 'missing'\n  | 'unexpected';\n\n/** Preflight finding for one declared integer column. */\nexport interface IntegerWidthColumnReport {\n  table: string;\n  column: string;\n  state: IntegerWidthColumnState;\n  /** Live `information_schema.columns.data_type`, when the column exists. */\n  declaredType: string | null;\n}\n\n/** Preflight findings for a single SMRT-owned table. */\nexport interface IntegerWidthTableReport {\n  table: string;\n  /** Number of rows when at least one column still needs widening. */\n  rowCount: number | null;\n  columns: IntegerWidthColumnReport[];\n}\n\n/** Read-only assessment of a deployment's legacy int4 columns. */\nexport interface IntegerWidthPreflightResult {\n  engine: string;\n  /** False for SQLite and adapters without a native 32-bit integer width. */\n  supported: boolean;\n  tables: IntegerWidthTableReport[];\n  pendingColumns: number;\n  currentColumns: number;\n  missingColumns: number;\n  unexpectedColumns: number;\n  /** Tables that need a maintenance-window table rewrite. */\n  pendingTables: number;\n  /** Human-readable output suitable for an operator change record. */\n  summary: string;\n}\n\n/** Shared options for the read-only preflight and mutating widening pass. */\nexport interface IntegerWidthOptions {\n  /** Adapter hint when its URL does not identify the engine. */\n  engineHint?: string;\n}\n\n/** Options that make the widening pass safely repeatable. */\nexport interface IntegerWidthWidenOptions extends IntegerWidthOptions {\n  /** Stable `_smrt_backfills` audit marker, unique to this migration owner. */\n  backfillName: string;\n  /** Package recorded alongside the marker. */\n  packageName?: string;\n  /** PostgreSQL lock timeout in milliseconds (defaults to 30 seconds). */\n  lockTimeout?: number;\n  /** PostgreSQL statement timeout in milliseconds (defaults to 60 seconds). */\n  statementTimeout?: number;\n}\n\n/** Result of {@link widenIntegerColumnsToBigInt}. */\nexport interface IntegerWidthWidenResult {\n  /** False when no legacy columns remain or the engine is unsupported. */\n  ran: boolean;\n  preflight: IntegerWidthPreflightResult;\n  widenedColumns: Array<{ table: string; column: string }>;\n  statements: string[];\n}\n\n/**\n * Collect every integer column owned by loaded application schemas and, when\n * requested, by hand-written core system-table DDL.\n */\nexport function collectIntegerWidthTargets(\n  schemas: Record<string, SchemaDefinition>,\n  options: { includeSystemTables?: boolean } = {},\n): IntegerWidthTarget[] {\n  const byTable = new Map<string, Set<string>>();\n  const add = (table: string, column: string) => {\n    if (!byTable.has(table)) byTable.set(table, new Set());\n    byTable.get(table)?.add(column);\n  };\n\n  for (const [key, schema] of Object.entries(schemas)) {\n    const table = schema?.tableName || key;\n    for (const [column, definition] of Object.entries(schema?.columns ?? {})) {\n      if (definition.type === 'INTEGER') add(table, column);\n    }\n  }\n\n  if (options.includeSystemTables ?? true) {\n    for (const shape of getSystemTableShapes('postgres').values()) {\n      for (const column of shape.columns) {\n        if (isBigIntType(column.type)) add(shape.tableName, column.name);\n      }\n    }\n  }\n\n  return [...byTable]\n    .map(([table, columns]) => ({ table, columns: [...columns].sort() }))\n    .sort((left, right) => left.table.localeCompare(right.table));\n}\n\n/** Build the exact, lossless ALTER statement for one target column. */\nexport function buildIntegerWidthStatements(\n  engine: string,\n  table: string,\n  column: string,\n): string[] {\n  return buildIntegerWidthTableStatements(engine, table, [column]);\n}\n\n/**\n * Build lossless widening statements for every pending column in one table.\n *\n * PostgreSQL performs a table rewrite for an integer-width change, so all of\n * one table's pending columns must share one ALTER TABLE and one lock window.\n * DuckDB keeps its one-column form because its ALTER COLUMN grammar is not\n * equivalently composable across supported adapter versions.\n */\nexport function buildIntegerWidthTableStatements(\n  engine: string,\n  table: string,\n  columns: string[],\n): string[] {\n  const quotedTable = quoteIdentifier(table);\n  const quotedColumns = columns.map(quoteIdentifier);\n  if (quotedColumns.length === 0) return [];\n  if (engine !== 'postgres' && engine !== 'duckdb') return [];\n  if (engine === 'postgres') {\n    return [\n      `ALTER TABLE ${quotedTable} ${quotedColumns\n        .map((column) => `ALTER COLUMN ${column} TYPE BIGINT`)\n        .join(', ')}`,\n    ];\n  }\n  return quotedColumns.map(\n    (column) => `ALTER TABLE ${quotedTable} ALTER COLUMN ${column} TYPE BIGINT`,\n  );\n}\n\n/**\n * Inspect explicit SMRT-owned integer targets without changing the database.\n *\n * PostgreSQL and DuckDB expose their live widths through\n * `information_schema.columns`. SQLite is deliberately a no-op because its\n * INTEGER storage class already holds signed 64-bit values.\n */\nexport async function preflightIntegerWidthWidening(\n  db: DatabaseInterface,\n  targets: IntegerWidthTarget[],\n  options: IntegerWidthOptions = {},\n): Promise<IntegerWidthPreflightResult> {\n  const engine = resolveEngine(db, options.engineHint);\n  const normalizedTargets = normalizeTargets(targets);\n  if (engine !== 'postgres' && engine !== 'duckdb') {\n    const result = {\n      engine,\n      supported: false,\n      tables: [],\n      pendingColumns: 0,\n      currentColumns: 0,\n      missingColumns: 0,\n      unexpectedColumns: 0,\n      pendingTables: 0,\n    };\n    return {\n      ...result,\n      summary:\n        `Integer-width widening preflight (engine=${engine}): not applicable; ` +\n        'this engine does not expose a distinct native int4 storage type.',\n    };\n  }\n\n  const tables: IntegerWidthTableReport[] = [];\n  for (const target of normalizedTargets) {\n    const types = await readColumnTypes(db, engine, target.table);\n    const columns = target.columns.map((column) => {\n      const declaredType = types.get(column) ?? null;\n      return {\n        table: target.table,\n        column,\n        declaredType,\n        state: classifyIntegerWidth(declaredType),\n      };\n    });\n    const needsWidening = columns.some((column) => column.state === 'pending');\n    tables.push({\n      table: target.table,\n      rowCount: needsWidening ? await countRows(db, target.table) : null,\n      columns,\n    });\n  }\n\n  const allColumns = tables.flatMap((table) => table.columns);\n  const result = {\n    engine,\n    supported: true,\n    tables,\n    pendingColumns: allColumns.filter((column) => column.state === 'pending')\n      .length,\n    currentColumns: allColumns.filter((column) => column.state === 'current')\n      .length,\n    missingColumns: allColumns.filter((column) => column.state === 'missing')\n      .length,\n    unexpectedColumns: allColumns.filter(\n      (column) => column.state === 'unexpected',\n    ).length,\n    pendingTables: tables.filter((table) =>\n      table.columns.some((column) => column.state === 'pending'),\n    ).length,\n  };\n  return { ...result, summary: renderSummary(result) };\n}\n\n/**\n * Widen legacy int4 columns to BIGINT and record a marker after every ALTER\n * succeeds. This is intentionally never called by normal schema migration or\n * framework bootstrap: PostgreSQL rewrites each altered table.\n */\nexport async function widenIntegerColumnsToBigInt(\n  db: DatabaseInterface,\n  targets: IntegerWidthTarget[],\n  options: IntegerWidthWidenOptions,\n): Promise<IntegerWidthWidenResult> {\n  const preflight = await preflightIntegerWidthWidening(db, targets, options);\n  if (!preflight.supported) {\n    return { ran: false, preflight, widenedColumns: [], statements: [] };\n  }\n  if (preflight.unexpectedColumns > 0) {\n    throw new Error(\n      'Integer-width widening refused because declared integer columns have unexpected live types. Resolve ordinary schema drift first.\\n' +\n        preflight.summary,\n    );\n  }\n\n  // Current declared widths are the idempotency guard. A fixed marker cannot\n  // safely be the guard because a later successful discovery may reveal a\n  // package/table absent from the earlier target set.\n  if (preflight.pendingColumns === 0) {\n    return { ran: false, preflight, widenedColumns: [], statements: [] };\n  }\n\n  const statements: string[] = [];\n  const widenedColumns: Array<{ table: string; column: string }> = [];\n  await new BackfillTracker({ db }).initialize();\n\n  const applyWidening = async (writeDb: DatabaseInterface) => {\n    for (const table of preflight.tables) {\n      const pendingColumns = table.columns\n        .filter((column) => column.state === 'pending')\n        .map((column) => column.column);\n      if (pendingColumns.length === 0) continue;\n      for (const sql of buildIntegerWidthTableStatements(\n        preflight.engine,\n        table.table,\n        pendingColumns,\n      )) {\n        await writeDb.query(sql);\n        statements.push(sql);\n      }\n      widenedColumns.push(\n        ...pendingColumns.map((column) => ({ table: table.table, column })),\n      );\n    }\n\n    await new BackfillTracker({ db: writeDb }).recordApplied(\n      options.backfillName,\n      {\n        description:\n          'Widened legacy int4 SMRT columns to BIGINT after #2373 changed fresh-schema defaults.',\n        packageName: options.packageName,\n      },\n    );\n  };\n\n  if (preflight.engine === 'postgres') {\n    if (!db.transaction) {\n      throw new Error(\n        'Integer-width widening on PostgreSQL requires transaction support.',\n      );\n    }\n    const lockTimeout = parsePostgresTimeoutMs(\n      options.lockTimeout,\n      DEFAULT_POSTGRES_LOCK_TIMEOUT_MS,\n    );\n    const statementTimeout = parsePostgresTimeoutMs(\n      options.statementTimeout,\n      DEFAULT_POSTGRES_STATEMENT_TIMEOUT_MS,\n    );\n    await db.transaction(async (tx) => {\n      const txDb = {\n        ...tx,\n        transaction: async <T>(\n          callback: (transactionDb: DatabaseInterface) => Promise<T>,\n        ) => callback(tx as DatabaseInterface),\n      } as DatabaseInterface;\n      BackfillTracker.inheritInitialization(txDb, db);\n      await txDb.query(\n        `SET LOCAL lock_timeout = '${formatPostgresTimeout(lockTimeout)}'`,\n      );\n      await txDb.query(\n        `SET LOCAL statement_timeout = '${formatPostgresTimeout(statementTimeout)}'`,\n      );\n      await applyWidening(txDb);\n    });\n  } else {\n    await applyWidening(db);\n  }\n\n  return { ran: true, preflight, widenedColumns, statements };\n}\n\nfunction resolveEngine(db: DatabaseInterface, engineHint?: string): string {\n  const dbWithConfig = db as DatabaseInterface & { config?: { url?: string } };\n  return detectEngine(db.url || dbWithConfig.config?.url || '', engineHint);\n}\n\nfunction normalizeTargets(targets: IntegerWidthTarget[]): IntegerWidthTarget[] {\n  const byTable = new Map<string, Set<string>>();\n  for (const target of targets) {\n    quoteIdentifier(target.table);\n    if (!byTable.has(target.table)) byTable.set(target.table, new Set());\n    for (const column of target.columns) {\n      quoteIdentifier(column);\n      byTable.get(target.table)?.add(column);\n    }\n  }\n  return [...byTable]\n    .map(([table, columns]) => ({ table, columns: [...columns].sort() }))\n    .sort((left, right) => left.table.localeCompare(right.table));\n}\n\nfunction quoteIdentifier(name: string): string {\n  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {\n    throw new Error(\n      `Integer-width widening: '${name}' is not a plain SQL identifier.`,\n    );\n  }\n  return `\"${name}\"`;\n}\n\nfunction formatPostgresTimeout(milliseconds: number): string {\n  return `${milliseconds}ms`;\n}\n\nfunction isLegacyInt4Type(type: string): boolean {\n  return /^(INTEGER|INT|INT4)$/i.test(type.trim());\n}\n\nfunction isBigIntType(type: string): boolean {\n  return /^(BIGINT|INT8)$/i.test(type.trim());\n}\n\nfunction classifyIntegerWidth(type: string | null): IntegerWidthColumnState {\n  if (type === null) return 'missing';\n  if (isLegacyInt4Type(type)) return 'pending';\n  if (isBigIntType(type)) return 'current';\n  return 'unexpected';\n}\n\nasync function readColumnTypes(\n  db: DatabaseInterface,\n  engine: string,\n  table: string,\n): Promise<Map<string, string>> {\n  const result = await db.query(\n    engine === 'postgres'\n      ? `SELECT column_name, data_type\n           FROM information_schema.columns\n          WHERE table_schema = current_schema() AND table_name = ?`\n      : `SELECT column_name, data_type\n           FROM information_schema.columns\n          WHERE table_name = ?`,\n    table,\n  );\n  const types = new Map<string, string>();\n  for (const row of result.rows as {\n    column_name?: unknown;\n    data_type?: unknown;\n  }[]) {\n    if (typeof row.column_name === 'string') {\n      types.set(row.column_name, String(row.data_type ?? ''));\n    }\n  }\n  return types;\n}\n\nasync function countRows(\n  db: DatabaseInterface,\n  table: string,\n): Promise<number> {\n  const result = await db.query(\n    `SELECT COUNT(*) AS row_count FROM ${quoteIdentifier(table)}`,\n  );\n  return toSafeInteger(\n    result.rows?.[0]?.row_count ?? 0,\n    `Integer-width row count for ${table}`,\n  );\n}\n\nfunction renderSummary(\n  result: Omit<IntegerWidthPreflightResult, 'summary'>,\n): string {\n  const lines = [\n    `Integer-width widening preflight (engine=${result.engine})`,\n    `  tables: ${result.pendingTables} pending`,\n    `  columns: ${result.pendingColumns} pending, ${result.currentColumns} already BIGINT, ${result.missingColumns} missing, ${result.unexpectedColumns} unexpected`,\n  ];\n  for (const table of result.tables) {\n    const pending = table.columns.filter(\n      (column) => column.state === 'pending',\n    );\n    if (pending.length === 0) continue;\n    lines.push(\n      `  - ${table.table}: ${table.rowCount ?? 0} row(s); ${pending\n        .map((column) => `${column.column} (${column.declaredType})`)\n        .join(', ')}`,\n    );\n  }\n  return lines.join('\\n');\n}\n"],"mappings":"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"}

package/dist/migrations/minor-units.d.ts

@@ -0,0 +1,162 @@
+import { DatabaseInterface } from './types.js';
+/** A table and the money columns on it that must move to minor units. */
+export interface MoneyColumnTarget {
+    /** Physical table name, e.g. `payments`. */
+    table: string;
+    /** Physical column names, e.g. `['amount', 'native_amount']`. */
+    columns: string[];
+}
+/** What the preflight found about one column. */
+export type MinorUnitsColumnState = 
+/** Floating-point today: needs converting. */
+'pending'
+/** Already an integer column: nothing to do. */
+ | 'converted'
+/** Table or column absent (package not installed, older schema). */
+ | 'missing';
+/** One row that cannot be converted without losing information. */
+export interface MinorUnitsProblemRow {
+    /** Primary key, when the table has an `id` column. */
+    id: string | null;
+    /** The stored major-unit value. */
+    value: number;
+    /** `value * scale`, before rounding. */
+    scaled: number;
+}
+/** Preflight findings for a single column. */
+export interface MinorUnitsColumnReport {
+    table: string;
+    column: string;
+    state: MinorUnitsColumnState;
+    /** Declared column type as the database reports it, when resolvable. */
+    declaredType: string | null;
+    /** Non-null values inspected. `0` unless `state` is `pending`. */
+    inspectedRows: number;
+    /** Values whose scaled form is not a whole number — rounding loses money. */
+    nonIntegral: MinorUnitsProblemRow[];
+    /** Values whose scaled form exceeds JavaScript's safe integer range. */
+    overflow: MinorUnitsProblemRow[];
+}
+/** Result of {@link preflightMinorUnitsRescale}. */
+export interface MinorUnitsPreflightResult {
+    engine: string;
+    scale: number;
+    columns: MinorUnitsColumnReport[];
+    /** Columns still holding floating-point major units. */
+    pendingColumns: number;
+    /** Columns already integer. */
+    convertedColumns: number;
+    /** Columns whose table/column does not exist. */
+    missingColumns: number;
+    /** Total rows that would be rounded. */
+    nonIntegralRows: number;
+    /** Total rows that would exceed JavaScript's safe integer range. */
+    overflowRows: number;
+    /** No row would lose information. */
+    ok: boolean;
+    /** Human-readable report, suitable for pasting into a migration log or PR. */
+    summary: string;
+}
+/** Options shared by the preflight and the rescale. */
+export interface MinorUnitsOptions {
+    /** Minor units per major unit. Default `100` (cents). */
+    scale?: number;
+    /** Engine hint for adapters whose URL does not identify the engine. */
+    engineHint?: string;
+    /** Problem rows recorded per column before truncating. Default `20`. */
+    maxProblemRows?: number;
+}
+/** Options for {@link rescaleMoneyColumnsToMinorUnits}. */
+export interface MinorUnitsRescaleOptions extends MinorUnitsOptions {
+    /**
+     * Stable marker name recorded in `_smrt_backfills`, e.g.
+     * `@happyvertical/smrt-commerce:money-minor-units:v1`.
+     *
+     * This is what makes the migration idempotent on SQLite, where the rescale
+     * is an `UPDATE` no column type can distinguish from an unconverted table.
+     */
+    backfillName: string;
+    /** Package recorded alongside the marker. */
+    packageName?: string;
+    /**
+     * Convert even when the preflight found rows that would be rounded or
+     * overflow. Off by default: silently rounding a half-cent away is exactly
+     * the failure this migration exists to prevent.
+     */
+    force?: boolean;
+}
+/** Result of {@link rescaleMoneyColumnsToMinorUnits}. */
+export interface MinorUnitsRescaleResult {
+    /** `false` when the backfill marker was already present. */
+    ran: boolean;
+    engine: string;
+    scale: number;
+    /** The preflight that gated the run. */
+    preflight: MinorUnitsPreflightResult;
+    /** Columns whose values were rescaled. */
+    rescaledColumns: Array<{
+        table: string;
+        column: string;
+    }>;
+    /** Statements executed, in order — useful for logs and tests. */
+    statements: string[];
+    /**
+     * Columns whose values are now minor units but whose *declared* type is
+     * still floating-point. Only ever populated on SQLite, which cannot alter a
+     * column type in place; clearing it needs the table-rebuild path (#2370).
+     */
+    declaredTypeChangePending: Array<{
+        table: string;
+        column: string;
+    }>;
+}
+/**
+ * A money-losing preflight finding blocked the conversion.
+ *
+ * Carries the full preflight so a caller can print the summary, fix the data,
+ * and retry rather than re-deriving what went wrong.
+ */
+export declare class MinorUnitsPreflightError extends Error {
+    readonly preflight: MinorUnitsPreflightResult;
+    constructor(preflight: MinorUnitsPreflightResult);
+}
+/**
+ * The statements that convert one column, for one engine.
+ *
+ * Exported so the emitted DDL can be asserted without a live PostgreSQL or
+ * DuckDB connection; each owning package's `test:postgres` lane then proves the
+ * same SQL runs against a real server.
+ *
+ * @param engine - `postgres`, `duckdb`, or anything SQLite-shaped.
+ * @param table - Physical table name.
+ * @param column - Physical column name.
+ * @param scale - Minor units per major unit.
+ * @returns Statements in execution order.
+ */
+export declare function buildMinorUnitsStatements(engine: string, table: string, column: string, scale: number): string[];
+/**
+ * Report what {@link rescaleMoneyColumnsToMinorUnits} would do, without
+ * writing anything.
+ *
+ * @param db - Root database handle.
+ * @param targets - Tables and money columns owned by the calling package.
+ * @param options - Scale, engine hint, problem-row cap.
+ * @returns Per-column state plus the rows that would lose information.
+ */
+export declare function preflightMinorUnitsRescale(db: DatabaseInterface, targets: MoneyColumnTarget[], options?: MinorUnitsOptions): Promise<MinorUnitsPreflightResult>;
+/**
+ * Convert floating-point major-unit money columns to integer minor units.
+ *
+ * Idempotent: the run is wrapped in a {@link BackfillTracker} marker, so a
+ * second call is a no-op even on SQLite where the column type cannot record
+ * that the conversion already happened.
+ *
+ * @param db - Root database handle (must support `query`).
+ * @param targets - Tables and money columns owned by the calling package.
+ * @param options - Marker name, scale, and whether to convert despite
+ *   information-losing rows.
+ * @throws {MinorUnitsPreflightError} when the preflight found rows that would
+ *   be rounded or overflow and `force` was not set.
+ */
+export declare function rescaleMoneyColumnsToMinorUnits(db: DatabaseInterface, targets: MoneyColumnTarget[], options: MinorUnitsRescaleOptions): Promise<MinorUnitsRescaleResult>;
+//# sourceMappingURL=minor-units.d.ts.map

package/dist/migrations/minor-units.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"minor-units.d.ts","sourceRoot":"","sources":["../../src/migrations/minor-units.ts"],"names":[],"mappings":"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"}