@pgpmjs/transform 0.18.0 → 0.20.0

package/bundle-driver.d.ts

@@ -7,7 +7,7 @@
  * purpose — no dependency on `@pgpmjs/bundle`/`@pgpmjs/core` — so the driver
  * stays a pure function factory over `transformSql` and `classifyStatements`.
  */
-import { ExtensionDefinition, ExtensionRouteSpec, ExtensionRouter, ExtensionTransformResult, RoleRouteSpec, RoleTransformResult, SchemaRouter, SchemaTransformResult, TransformSqlOptions } from '@pgsql/transform';
+import { ExtensionDefinition, ExtensionRouter, ExtensionRouteSpec, ExtensionTransformResult, RoleRouteSpec, RoleTransformResult, SchemaRouter, SchemaTransformResult, TransformSqlOptions } from '@pgsql/transform';
 /** Identity of the script being transformed/validated (matches the bundle seams). */
 export interface BundleScriptContext {
     change: string;

package/catalog-check.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Structural catalog snapshot + equivalence check, used by
+ * `pgpm transform --check` to prove a transform is lossless: deploy the
+ * original and the transformed module(s) into two scratch databases and
+ * assert the resulting catalogs describe the same schema.
+ *
+ * The snapshot is intentionally order-insensitive per object class (objects
+ * are keyed by identity and compared by definition), but column order within
+ * a table IS part of the comparison — the dials pipeline preserves it.
+ */
+/** Minimal query surface: satisfied by pg Pool/PoolClient and test clients. */
+export interface CatalogQueryable {
+    query(text: string): Promise<{
+        rows: any[];
+    }>;
+}
+/** Catalog snapshot: object identity -> normalized definition. */
+export interface CatalogSnapshot {
+    schemas: Record<string, string>;
+    tables: Record<string, string>;
+    columns: Record<string, string>;
+    constraints: Record<string, string>;
+    indexes: Record<string, string>;
+    functions: Record<string, string>;
+    triggers: Record<string, string>;
+    policies: Record<string, string>;
+    rls: Record<string, string>;
+    grants: Record<string, string>;
+}
+/**
+ * Snapshot the user-schema surface of a database: schemas, tables, columns,
+ * constraints, indexes, functions, triggers, policies, RLS flags, and table
+ * grants. System schemas, `public`, and the pgpm ledger are excluded.
+ */
+export declare const snapshotCatalog: (db: CatalogQueryable) => Promise<CatalogSnapshot>;
+/**
+ * Column-order-insensitive view of a snapshot. Migrations that drop and add
+ * columns can never reproduce a fresh deploy's physical column order
+ * (Postgres appends), so migration-equivalence checks (`pgpm diff --verify`)
+ * compare columns by name and definition only.
+ */
+export declare const withoutColumnOrder: (snap: CatalogSnapshot) => CatalogSnapshot;
+/**
+ * Compare two catalog snapshots. Returns a flat list of human-readable
+ * differences; an empty list means the catalogs are structurally equivalent.
+ */
+export declare const diffCatalogSnapshots: (a: CatalogSnapshot, b: CatalogSnapshot) => string[];

package/catalog-check.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffCatalogSnapshots = exports.withoutColumnOrder = exports.snapshotCatalog = void 0;
+const SYSTEM_SCHEMAS = `('pg_catalog', 'information_schema', 'pg_toast', 'pgpm_migrate', 'public')`;
+const record = (rows, key, value) => {
+    const out = {};
+    for (const row of rows)
+        out[key(row)] = value(row);
+    return out;
+};
+/**
+ * Snapshot the user-schema surface of a database: schemas, tables, columns,
+ * constraints, indexes, functions, triggers, policies, RLS flags, and table
+ * grants. System schemas, `public`, and the pgpm ledger are excluded.
+ */
+const snapshotCatalog = async (db) => {
+    const schemas = await db.query(`
+    SELECT nspname FROM pg_namespace
+    WHERE nspname NOT IN ${SYSTEM_SCHEMAS} AND nspname NOT LIKE 'pg_temp%' AND nspname NOT LIKE 'pg_toast%'
+    ORDER BY nspname
+  `);
+    const tables = await db.query(`
+    SELECT table_schema, table_name FROM information_schema.tables
+    WHERE table_schema NOT IN ${SYSTEM_SCHEMAS} AND table_type = 'BASE TABLE'
+  `);
+    const columns = await db.query(`
+    SELECT table_schema, table_name, column_name, ordinal_position,
+           data_type, is_nullable, column_default, character_maximum_length
+    FROM information_schema.columns
+    WHERE table_schema NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const constraints = await db.query(`
+    SELECT n.nspname AS schema, cl.relname AS table, c.conname,
+           pg_get_constraintdef(c.oid) AS def
+    FROM pg_constraint c
+    JOIN pg_class cl ON cl.oid = c.conrelid
+    JOIN pg_namespace n ON n.oid = cl.relnamespace
+    WHERE n.nspname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const indexes = await db.query(`
+    SELECT schemaname, tablename, indexname, indexdef
+    FROM pg_indexes WHERE schemaname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const functions = await db.query(`
+    SELECT n.nspname AS schema, p.proname,
+           pg_get_function_identity_arguments(p.oid) AS args,
+           pg_get_functiondef(p.oid) AS def
+    FROM pg_proc p
+    JOIN pg_namespace n ON n.oid = p.pronamespace
+    WHERE n.nspname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const triggers = await db.query(`
+    SELECT n.nspname AS schema, cl.relname AS table, t.tgname,
+           pg_get_triggerdef(t.oid) AS def
+    FROM pg_trigger t
+    JOIN pg_class cl ON cl.oid = t.tgrelid
+    JOIN pg_namespace n ON n.oid = cl.relnamespace
+    WHERE NOT t.tgisinternal AND n.nspname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const policies = await db.query(`
+    SELECT schemaname, tablename, policyname, permissive, roles, cmd,
+           qual, with_check
+    FROM pg_policies WHERE schemaname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const rls = await db.query(`
+    SELECT n.nspname AS schema, cl.relname AS table,
+           cl.relrowsecurity, cl.relforcerowsecurity
+    FROM pg_class cl
+    JOIN pg_namespace n ON n.oid = cl.relnamespace
+    WHERE cl.relkind = 'r' AND n.nspname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const grants = await db.query(`
+    SELECT table_schema, table_name, grantee, privilege_type
+    FROM information_schema.role_table_grants
+    WHERE table_schema NOT IN ${SYSTEM_SCHEMAS}
+      AND grantee <> (SELECT current_user)
+  `);
+    return {
+        schemas: record(schemas.rows, r => r.nspname, () => 'schema'),
+        tables: record(tables.rows, r => `${r.table_schema}.${r.table_name}`, () => 'table'),
+        columns: record(columns.rows, r => `${r.table_schema}.${r.table_name}.${r.column_name}`, r => `#${r.ordinal_position} ${r.data_type}${r.character_maximum_length ? `(${r.character_maximum_length})` : ''} nullable=${r.is_nullable} default=${r.column_default ?? 'none'}`),
+        constraints: record(constraints.rows, r => `${r.schema}.${r.table}.${r.conname}`, r => r.def),
+        indexes: record(indexes.rows, r => `${r.schemaname}.${r.tablename}.${r.indexname}`, r => r.indexdef),
+        functions: record(functions.rows, r => `${r.schema}.${r.proname}(${r.args})`, r => r.def),
+        triggers: record(triggers.rows, r => `${r.schema}.${r.table}.${r.tgname}`, r => r.def),
+        policies: record(policies.rows, r => `${r.schemaname}.${r.tablename}.${r.policyname}`, r => `permissive=${r.permissive} roles=${[...(r.roles ?? [])].sort().join(',')} cmd=${r.cmd} qual=${r.qual ?? 'none'} check=${r.with_check ?? 'none'}`),
+        rls: record(rls.rows, r => `${r.schema}.${r.table}`, r => `enabled=${r.relrowsecurity} forced=${r.relforcerowsecurity}`),
+        grants: record(grants.rows, r => `${r.table_schema}.${r.table_name}:${r.grantee}:${r.privilege_type}`, () => 'grant')
+    };
+};
+exports.snapshotCatalog = snapshotCatalog;
+/**
+ * Column-order-insensitive view of a snapshot. Migrations that drop and add
+ * columns can never reproduce a fresh deploy's physical column order
+ * (Postgres appends), so migration-equivalence checks (`pgpm diff --verify`)
+ * compare columns by name and definition only.
+ */
+const withoutColumnOrder = (snap) => {
+    const columns = {};
+    for (const [key, value] of Object.entries(snap.columns)) {
+        columns[key] = value.replace(/^#\d+ /, '');
+    }
+    return { ...snap, columns };
+};
+exports.withoutColumnOrder = withoutColumnOrder;
+/**
+ * Compare two catalog snapshots. Returns a flat list of human-readable
+ * differences; an empty list means the catalogs are structurally equivalent.
+ */
+const diffCatalogSnapshots = (a, b) => {
+    const diffs = [];
+    for (const section of Object.keys(a)) {
+        const left = a[section];
+        const right = b[section];
+        for (const key of Object.keys(left).sort()) {
+            if (!(key in right)) {
+                diffs.push(`${section}: ${key} only in original`);
+            }
+            else if (left[key] !== right[key]) {
+                diffs.push(`${section}: ${key} differs\n  original:    ${left[key]}\n  transformed: ${right[key]}`);
+            }
+        }
+        for (const key of Object.keys(right).sort()) {
+            if (!(key in left))
+                diffs.push(`${section}: ${key} only in transformed`);
+        }
+    }
+    return diffs;
+};
+exports.diffCatalogSnapshots = diffCatalogSnapshots;

package/constraint-names.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Postgres default constraint names.
+ *
+ * When a constraint is authored without a name, Postgres derives one at
+ * deploy time (`ChooseConstraintName` in the server): `{table}_pkey` for
+ * primary keys, `{table}_{cols}_key` for unique constraints,
+ * `{table}_{col}_fkey` for foreign keys, `{table}_{col}_check` (first
+ * referenced column) or `{table}_check` for check constraints. Synthesizing
+ * the same names makes unnamed authorship comparable to (and revertible as)
+ * what the catalog will actually contain.
+ */
+/** A parsed `Constraint` node (structural — the fields this module reads). */
+export interface ConstraintNode {
+    contype?: string;
+    conname?: string;
+    keys?: {
+        String?: {
+            sval?: string;
+        };
+    }[];
+    fk_attrs?: {
+        String?: {
+            sval?: string;
+        };
+    }[];
+    raw_expr?: unknown;
+}
+/** First `ColumnRef` column name reached in an expression tree, DFS order. */
+export declare function firstColumnRef(node: unknown): string | null;
+/**
+ * The name Postgres would assign to an unnamed constraint on `table`, given
+ * the constraint node and (for column-attached constraints) the owning
+ * column. Returns `null` for kinds without a stable derivation (exclusion
+ * constraints and anything unrecognized).
+ */
+export declare function defaultConstraintName(table: string, constraint: ConstraintNode, column?: string): string | null;

package/constraint-names.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * Postgres default constraint names.
+ *
+ * When a constraint is authored without a name, Postgres derives one at
+ * deploy time (`ChooseConstraintName` in the server): `{table}_pkey` for
+ * primary keys, `{table}_{cols}_key` for unique constraints,
+ * `{table}_{col}_fkey` for foreign keys, `{table}_{col}_check` (first
+ * referenced column) or `{table}_check` for check constraints. Synthesizing
+ * the same names makes unnamed authorship comparable to (and revertible as)
+ * what the catalog will actually contain.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.firstColumnRef = firstColumnRef;
+exports.defaultConstraintName = defaultConstraintName;
+const svals = (items) => (items ?? []).map(k => k.String?.sval).filter((s) => typeof s === 'string');
+/** First `ColumnRef` column name reached in an expression tree, DFS order. */
+function firstColumnRef(node) {
+    if (Array.isArray(node)) {
+        for (const item of node) {
+            const found = firstColumnRef(item);
+            if (found)
+                return found;
+        }
+        return null;
+    }
+    if (node && typeof node === 'object') {
+        const record = node;
+        const ref = record.ColumnRef;
+        if (ref?.fields) {
+            const names = svals(ref.fields);
+            if (names.length > 0)
+                return names[names.length - 1];
+        }
+        for (const value of Object.values(record)) {
+            const found = firstColumnRef(value);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}
+/**
+ * The name Postgres would assign to an unnamed constraint on `table`, given
+ * the constraint node and (for column-attached constraints) the owning
+ * column. Returns `null` for kinds without a stable derivation (exclusion
+ * constraints and anything unrecognized).
+ */
+function defaultConstraintName(table, constraint, column) {
+    const cols = () => {
+        const keyed = svals(constraint.keys);
+        if (keyed.length > 0)
+            return keyed;
+        return column ? [column] : [];
+    };
+    switch (constraint.contype) {
+        case 'CONSTR_PRIMARY':
+            return `${table}_pkey`;
+        case 'CONSTR_UNIQUE': {
+            const names = cols();
+            return names.length > 0 ? `${table}_${names.join('_')}_key` : null;
+        }
+        case 'CONSTR_FOREIGN': {
+            const attrs = svals(constraint.fk_attrs);
+            const names = attrs.length > 0 ? attrs : column ? [column] : [];
+            return names.length > 0 ? `${table}_${names.join('_')}_fkey` : null;
+        }
+        case 'CONSTR_CHECK': {
+            const col = column ?? firstColumnRef(constraint.raw_expr);
+            return col ? `${table}_${col}_check` : `${table}_check`;
+        }
+        default:
+            return null;
+    }
+}

package/esm/catalog-check.js

@@ -0,0 +1,124 @@
+const SYSTEM_SCHEMAS = `('pg_catalog', 'information_schema', 'pg_toast', 'pgpm_migrate', 'public')`;
+const record = (rows, key, value) => {
+    const out = {};
+    for (const row of rows)
+        out[key(row)] = value(row);
+    return out;
+};
+/**
+ * Snapshot the user-schema surface of a database: schemas, tables, columns,
+ * constraints, indexes, functions, triggers, policies, RLS flags, and table
+ * grants. System schemas, `public`, and the pgpm ledger are excluded.
+ */
+export const snapshotCatalog = async (db) => {
+    const schemas = await db.query(`
+    SELECT nspname FROM pg_namespace
+    WHERE nspname NOT IN ${SYSTEM_SCHEMAS} AND nspname NOT LIKE 'pg_temp%' AND nspname NOT LIKE 'pg_toast%'
+    ORDER BY nspname
+  `);
+    const tables = await db.query(`
+    SELECT table_schema, table_name FROM information_schema.tables
+    WHERE table_schema NOT IN ${SYSTEM_SCHEMAS} AND table_type = 'BASE TABLE'
+  `);
+    const columns = await db.query(`
+    SELECT table_schema, table_name, column_name, ordinal_position,
+           data_type, is_nullable, column_default, character_maximum_length
+    FROM information_schema.columns
+    WHERE table_schema NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const constraints = await db.query(`
+    SELECT n.nspname AS schema, cl.relname AS table, c.conname,
+           pg_get_constraintdef(c.oid) AS def
+    FROM pg_constraint c
+    JOIN pg_class cl ON cl.oid = c.conrelid
+    JOIN pg_namespace n ON n.oid = cl.relnamespace
+    WHERE n.nspname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const indexes = await db.query(`
+    SELECT schemaname, tablename, indexname, indexdef
+    FROM pg_indexes WHERE schemaname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const functions = await db.query(`
+    SELECT n.nspname AS schema, p.proname,
+           pg_get_function_identity_arguments(p.oid) AS args,
+           pg_get_functiondef(p.oid) AS def
+    FROM pg_proc p
+    JOIN pg_namespace n ON n.oid = p.pronamespace
+    WHERE n.nspname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const triggers = await db.query(`
+    SELECT n.nspname AS schema, cl.relname AS table, t.tgname,
+           pg_get_triggerdef(t.oid) AS def
+    FROM pg_trigger t
+    JOIN pg_class cl ON cl.oid = t.tgrelid
+    JOIN pg_namespace n ON n.oid = cl.relnamespace
+    WHERE NOT t.tgisinternal AND n.nspname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const policies = await db.query(`
+    SELECT schemaname, tablename, policyname, permissive, roles, cmd,
+           qual, with_check
+    FROM pg_policies WHERE schemaname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const rls = await db.query(`
+    SELECT n.nspname AS schema, cl.relname AS table,
+           cl.relrowsecurity, cl.relforcerowsecurity
+    FROM pg_class cl
+    JOIN pg_namespace n ON n.oid = cl.relnamespace
+    WHERE cl.relkind = 'r' AND n.nspname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const grants = await db.query(`
+    SELECT table_schema, table_name, grantee, privilege_type
+    FROM information_schema.role_table_grants
+    WHERE table_schema NOT IN ${SYSTEM_SCHEMAS}
+      AND grantee <> (SELECT current_user)
+  `);
+    return {
+        schemas: record(schemas.rows, r => r.nspname, () => 'schema'),
+        tables: record(tables.rows, r => `${r.table_schema}.${r.table_name}`, () => 'table'),
+        columns: record(columns.rows, r => `${r.table_schema}.${r.table_name}.${r.column_name}`, r => `#${r.ordinal_position} ${r.data_type}${r.character_maximum_length ? `(${r.character_maximum_length})` : ''} nullable=${r.is_nullable} default=${r.column_default ?? 'none'}`),
+        constraints: record(constraints.rows, r => `${r.schema}.${r.table}.${r.conname}`, r => r.def),
+        indexes: record(indexes.rows, r => `${r.schemaname}.${r.tablename}.${r.indexname}`, r => r.indexdef),
+        functions: record(functions.rows, r => `${r.schema}.${r.proname}(${r.args})`, r => r.def),
+        triggers: record(triggers.rows, r => `${r.schema}.${r.table}.${r.tgname}`, r => r.def),
+        policies: record(policies.rows, r => `${r.schemaname}.${r.tablename}.${r.policyname}`, r => `permissive=${r.permissive} roles=${[...(r.roles ?? [])].sort().join(',')} cmd=${r.cmd} qual=${r.qual ?? 'none'} check=${r.with_check ?? 'none'}`),
+        rls: record(rls.rows, r => `${r.schema}.${r.table}`, r => `enabled=${r.relrowsecurity} forced=${r.relforcerowsecurity}`),
+        grants: record(grants.rows, r => `${r.table_schema}.${r.table_name}:${r.grantee}:${r.privilege_type}`, () => 'grant')
+    };
+};
+/**
+ * Column-order-insensitive view of a snapshot. Migrations that drop and add
+ * columns can never reproduce a fresh deploy's physical column order
+ * (Postgres appends), so migration-equivalence checks (`pgpm diff --verify`)
+ * compare columns by name and definition only.
+ */
+export const withoutColumnOrder = (snap) => {
+    const columns = {};
+    for (const [key, value] of Object.entries(snap.columns)) {
+        columns[key] = value.replace(/^#\d+ /, '');
+    }
+    return { ...snap, columns };
+};
+/**
+ * Compare two catalog snapshots. Returns a flat list of human-readable
+ * differences; an empty list means the catalogs are structurally equivalent.
+ */
+export const diffCatalogSnapshots = (a, b) => {
+    const diffs = [];
+    for (const section of Object.keys(a)) {
+        const left = a[section];
+        const right = b[section];
+        for (const key of Object.keys(left).sort()) {
+            if (!(key in right)) {
+                diffs.push(`${section}: ${key} only in original`);
+            }
+            else if (left[key] !== right[key]) {
+                diffs.push(`${section}: ${key} differs\n  original:    ${left[key]}\n  transformed: ${right[key]}`);
+            }
+        }
+        for (const key of Object.keys(right).sort()) {
+            if (!(key in left))
+                diffs.push(`${section}: ${key} only in transformed`);
+        }
+    }
+    return diffs;
+};

package/esm/constraint-names.js

@@ -0,0 +1,71 @@
+/**
+ * Postgres default constraint names.
+ *
+ * When a constraint is authored without a name, Postgres derives one at
+ * deploy time (`ChooseConstraintName` in the server): `{table}_pkey` for
+ * primary keys, `{table}_{cols}_key` for unique constraints,
+ * `{table}_{col}_fkey` for foreign keys, `{table}_{col}_check` (first
+ * referenced column) or `{table}_check` for check constraints. Synthesizing
+ * the same names makes unnamed authorship comparable to (and revertible as)
+ * what the catalog will actually contain.
+ */
+const svals = (items) => (items ?? []).map(k => k.String?.sval).filter((s) => typeof s === 'string');
+/** First `ColumnRef` column name reached in an expression tree, DFS order. */
+export function firstColumnRef(node) {
+    if (Array.isArray(node)) {
+        for (const item of node) {
+            const found = firstColumnRef(item);
+            if (found)
+                return found;
+        }
+        return null;
+    }
+    if (node && typeof node === 'object') {
+        const record = node;
+        const ref = record.ColumnRef;
+        if (ref?.fields) {
+            const names = svals(ref.fields);
+            if (names.length > 0)
+                return names[names.length - 1];
+        }
+        for (const value of Object.values(record)) {
+            const found = firstColumnRef(value);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}
+/**
+ * The name Postgres would assign to an unnamed constraint on `table`, given
+ * the constraint node and (for column-attached constraints) the owning
+ * column. Returns `null` for kinds without a stable derivation (exclusion
+ * constraints and anything unrecognized).
+ */
+export function defaultConstraintName(table, constraint, column) {
+    const cols = () => {
+        const keyed = svals(constraint.keys);
+        if (keyed.length > 0)
+            return keyed;
+        return column ? [column] : [];
+    };
+    switch (constraint.contype) {
+        case 'CONSTR_PRIMARY':
+            return `${table}_pkey`;
+        case 'CONSTR_UNIQUE': {
+            const names = cols();
+            return names.length > 0 ? `${table}_${names.join('_')}_key` : null;
+        }
+        case 'CONSTR_FOREIGN': {
+            const attrs = svals(constraint.fk_attrs);
+            const names = attrs.length > 0 ? attrs : column ? [column] : [];
+            return names.length > 0 ? `${table}_${names.join('_')}_fkey` : null;
+        }
+        case 'CONSTR_CHECK': {
+            const col = column ?? firstColumnRef(constraint.raw_expr);
+            return col ? `${table}_${col}_check` : `${table}_check`;
+        }
+        default:
+            return null;
+    }
+}

package/esm/fixture-closure.js

@@ -1,5 +1,5 @@
-import { TIER_PROFILE } from './categorize';
 import { classifyStatements } from '@pgsql/transform';
+import { TIER_PROFILE } from './categorize';
 function objectKey(schema, name) {
     return `${schema ?? ''}\u0000${name}`;
 }

package/esm/granularity-driver.js

@@ -1,25 +1,9 @@
-/**
- * Granularity driver: restructure a pgpm module's deploy surface between the
- * atomic, object, and consolidated shapes.
- *
- * The upstream pass (`restructureSql` in `@pgsql/transform`) rewrites one SQL
- * script between equivalent shapes, guarded by the statement dependency
- * graph. This driver lifts that to the pgpm change model: it flattens a
- * module's deploy scripts in plan order into one program, restructures it to
- * the target granularity, then re-slices the result into changes — one change
- * per created object — with change dependencies recomputed from the statement
- * graph. Like the other drivers in this package it is structurally typed on
- * the bundle seams: no dependency on `@pgpmjs/bundle` or `@pgpmjs/core`.
- *
- * - `atomic`       — the machine-emitted shape: bare CREATE TABLE plus one
- *                    ALTER per column/constraint.
- * - `object`       — each table fully baked; cross-object statements
- *                    (FKs, indexes, triggers, policies) stay separate.
- * - `consolidated` — additionally inlines FKs proven safe by the graph.
- */
 import { pathFor } from '@pgpmjs/naming-spec';
 import { revertFor, verifyFor } from '@pgsql/scripts';
 import { buildStatementGraph, classifyStatements, identityOf, restructureSql } from '@pgsql/transform';
+import { nameUnnamedConstraints, subObjectIdentityOf } from './sub-object';
+export const CHANGE_GRANULARITIES = ['alteration', 'object', 'single'];
+export const isChangeGranularity = (value) => CHANGE_GRANULARITIES.includes(value);
 const KIND_DIRS = {
     table: 'tables',
     view: 'views',
@@ -53,22 +37,50 @@ export function defaultChangeName(facts) {
  */
 export function restructureChanges(changes, options) {
     const nameFor = options.changeName ?? defaultChangeName;
+    const subNameFor = options.subObjectName ?? ((identity) => pathFor(identity));
+    const alteration = options.changeGranularity === 'alteration';
     const flattened = changes
         .map(c => c.deploy.trim())
         .filter(Boolean)
         .join('\n\n');
-    const { sql, warnings } = restructureSql(flattened, {
+    const restructured = restructureSql(flattened, {
         granularity: options.granularity
     });
+    const warnings = restructured.warnings;
+    const sql = alteration ? nameUnnamedConstraints(restructured.sql) : restructured.sql;
     // Re-classify the emitted script; group statements by the object they
     // target (creates[0]), so a table's CREATE and its remaining ALTERs land
     // in the same change regardless of statement kind.
     const facts = classifyStatements(sql);
+    if (options.changeGranularity === 'single') {
+        const name = options.singleChangeName ?? 'module/init';
+        const inputNames = new Set(changes.map(c => c.name));
+        const dependencies = [...new Set(changes.flatMap(c => c.dependencies).filter(d => !inputNames.has(d)))].sort();
+        const statements = facts
+            .map(f => sql.slice(f.span.start, f.span.start + f.span.len).trim())
+            .filter(Boolean)
+            .map(text => (text.endsWith(';') ? text : `${text};`));
+        const revert = revertFor(facts);
+        const verify = verifyFor(facts);
+        for (const warning of [...revert.warnings, ...verify.warnings]) {
+            warnings.push(`${name}: ${warning}`);
+        }
+        return {
+            changes: statements.length > 0
+                ? [{ name, dependencies, deploy: statements.join('\n\n'), revert: revert.sql, verify: verify.sql }]
+                : [],
+            warnings
+        };
+    }
     const graph = buildStatementGraph(facts);
     const groupOf = new Array(facts.length).fill(-1);
     const groupKeys = [];
     const groupFacts = [];
     const groupKeyToIndex = new Map();
+    /** Sub-object path for alteration groups; null means name via `nameFor`. */
+    const groupSubName = [];
+    /** For alteration groups: the object-group key of the owning table. */
+    const groupOwnerKey = [];
     facts.forEach((f, i) => {
         const created = f.creates[0];
         if (!created) {
@@ -78,12 +90,31 @@ export function restructureChanges(changes, options) {
                 groupOf[i] = groupOf[i - 1];
             return;
         }
+        if (alteration) {
+            const sub = subObjectIdentityOf(f);
+            if (sub) {
+                const key = `sub\u0000${sub.kind}\u0000${sub.schema ?? ''}\u0000${sub.table}\u0000${sub.name}`;
+                let g = groupKeyToIndex.get(key);
+                if (g === undefined) {
+                    g = groupKeys.length;
+                    groupKeys.push(key);
+                    groupFacts.push(f);
+                    groupSubName.push(subNameFor(sub));
+                    groupOwnerKey.push(`${sub.schema ?? ''}.${sub.table}`);
+                    groupKeyToIndex.set(key, g);
+                }
+                groupOf[i] = g;
+                return;
+            }
+        }
         const key = `${created.schema ?? ''}.${created.name}`;
         let g = groupKeyToIndex.get(key);
         if (g === undefined) {
             g = groupKeys.length;
             groupKeys.push(key);
             groupFacts.push(f);
+            groupSubName.push(null);
+            groupOwnerKey.push(null);
             groupKeyToIndex.set(key, g);
         }
         else if (!(groupFacts[g].kind in KIND_DIRS) && groupFacts[g].kind !== 'schema' && (f.kind in KIND_DIRS || f.kind === 'schema')) {
@@ -92,7 +123,7 @@ export function restructureChanges(changes, options) {
         }
         groupOf[i] = g;
     });
-    const groupNames = groupFacts.map(nameFor);
+    const groupNames = groupFacts.map((f, g) => groupSubName[g] ?? nameFor(f));
     // Schema producers, for schema-level change dependencies.
     const schemaGroup = new Map();
     facts.forEach((f, i) => {
@@ -138,6 +169,38 @@ export function restructureChanges(changes, options) {
                 groupDeps[from].add(to);
         }
     });
+    // Alteration groups depend on their table's own change, and constraint
+    // groups additionally on the column changes they key on — the statement
+    // graph keys everything by the table, so these finer edges are added here.
+    if (alteration) {
+        const columnGroup = new Map();
+        groupKeys.forEach((key, g) => {
+            const parts = key.split('\u0000');
+            if (parts[0] === 'sub' && parts[1] === 'column') {
+                columnGroup.set(`${parts[2]}.${parts[3]}.${parts[4]}`, g);
+            }
+        });
+        groupKeys.forEach((key, g) => {
+            const owner = groupOwnerKey[g];
+            if (owner === null)
+                return;
+            const tableGroup = groupKeyToIndex.get(owner);
+            if (tableGroup !== undefined && tableGroup !== g)
+                groupDeps[g].add(tableGroup);
+            const parts = key.split('\u0000');
+            if (parts[1] !== 'constraint')
+                return;
+            const constraint = groupFacts[g].stmt?.AlterTableStmt?.cmds?.[0]?.AlterTableCmd?.def?.Constraint;
+            const referenced = [...(constraint?.keys ?? []), ...(constraint?.fk_attrs ?? [])]
+                .map(k => k.String?.sval)
+                .filter((s) => typeof s === 'string');
+            for (const col of referenced) {
+                const to = columnGroup.get(`${owner}.${col}`);
+                if (to !== undefined && to !== g)
+                    groupDeps[g].add(to);
+            }
+        });
+    }
     // Emit groups in first-statement order (already topological).
     const order = [...groupNames.keys()].sort((a, b) => {
         const firstA = groupOf.indexOf(a);