@pgpmjs/transform 0.19.0 → 0.21.0

package/bundle-driver.js

@@ -13,8 +13,8 @@ exports.buildExtensionRouter = buildExtensionRouter;
 exports.buildSchemaRouter = buildSchemaRouter;
 exports.makeSchemaTranspiler = makeSchemaTranspiler;
 exports.makeNamespaceValidator = makeNamespaceValidator;
+const semantics_1 = require("@pgsql/semantics");
 const transform_1 = require("@pgsql/transform");
-const transform_2 = require("@pgsql/transform");
 /**
  * Build an {@link ExtensionRouter} from the declarative {@link ExtensionRoutingInput}:
  * an explicit `routes` spec when given, otherwise the "move everything matched
@@ -27,8 +27,8 @@ function buildExtensionRouter(input) {
     if (input.inventory)
         opts.inventory = input.inventory;
     if (input.routes)
-        return new transform_2.ExtensionRouter(input.routes, opts);
-    return transform_2.ExtensionRouter.toSchema(input.toSchema ?? null, {
+        return new transform_1.ExtensionRouter(input.routes, opts);
+    return transform_1.ExtensionRouter.toSchema(input.toSchema ?? null, {
         ...opts,
         extensions: input.only,
         from: input.from
@@ -75,7 +75,7 @@ function buildSchemaRouter(options) {
                     ...(route.toName !== undefined ? { name: route.toName } : {})
                 };
     }
-    return new transform_2.SchemaRouter(spec);
+    return new transform_1.SchemaRouter(spec);
 }
 /**
  * Rewrite the schema segment of a pgpm change path to the object's routed
@@ -125,14 +125,14 @@ function makeSchemaTranspiler(options) {
     // after schema routing on each script. Each is a self-contained parse →
     // rewrite → deparse pass, so they compose by threading the SQL through.
     const extRouter = options.extensions ? buildExtensionRouter(options.extensions) : undefined;
-    const roleRouter = options.roles ? transform_2.RoleRouter.from(options.roles) : undefined;
-    const extensionResult = extRouter ? (0, transform_2.createExtensionResult)() : undefined;
-    const roleResult = roleRouter ? (0, transform_2.createRoleResult)() : undefined;
+    const roleRouter = options.roles ? transform_1.RoleRouter.from(options.roles) : undefined;
+    const extensionResult = extRouter ? (0, transform_1.createExtensionResult)() : undefined;
+    const roleResult = roleRouter ? (0, transform_1.createRoleResult)() : undefined;
     const renameChange = (name) => renameChangePath(name, router);
     const transformScript = (sql, _ctx) => {
-        let out = (0, transform_2.transformSql)(sql, router, options.transform, result).content;
+        let out = (0, transform_1.transformSql)(sql, router, options.transform, result).content;
         if (extRouter) {
-            const r = (0, transform_2.transformExtensions)(out, extRouter);
+            const r = (0, transform_1.transformExtensions)(out, extRouter);
             out = r.sql;
             for (const [name, schema] of r.result.installsMoved) {
                 extensionResult.installsMoved.set(name, schema);
@@ -142,7 +142,7 @@ function makeSchemaTranspiler(options) {
             }
         }
         if (roleRouter) {
-            const r = (0, transform_2.transformRoles)(out, roleRouter);
+            const r = (0, transform_1.transformRoles)(out, roleRouter);
             out = r.sql;
             for (const [name, count] of r.result.rolesRenamed) {
                 roleResult.rolesRenamed.set(name, (roleResult.rolesRenamed.get(name) ?? 0) + count);
@@ -162,7 +162,7 @@ function makeNamespaceValidator(options) {
     const allowed = new Set(options.allowedSchemas);
     return (sql, _ctx) => {
         const violations = new Set();
-        for (const facts of (0, transform_1.classifyStatements)(sql)) {
+        for (const facts of (0, semantics_1.classifyStatements)(sql)) {
             for (const ref of [...facts.creates, ...facts.references, ...facts.fkTargets]) {
                 if (ref.schema && !allowed.has(ref.schema)) {
                     violations.add(`${facts.nodeTag}: ${ref.schema}.${ref.name}`);

package/categorize.d.ts

@@ -1,4 +1,4 @@
-import { StatementFacts } from '@pgsql/transform';
+import { StatementFacts } from '@pgsql/semantics';
 /**
  * A category is a chunk-seam key a change is assigned to. Free-form string; the
  * built-in {@link TIER_PROFILE} uses `'security' | 'functionality' | 'fixtures'

package/categorize.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TIER_PROFILE = void 0;
 exports.categorizeChange = categorizeChange;
 exports.buildCategoryOf = buildCategoryOf;
-const transform_1 = require("@pgsql/transform");
+const semantics_1 = require("@pgsql/semantics");
 /**
  * Default tier profile: isolates the security surface and procedural code out
  * of the schema base. Precedence, highest first — a change is placed in the
@@ -37,7 +37,7 @@ exports.TIER_PROFILE = {
  * (defaults to {@link TIER_PROFILE}).
  */
 function categorizeChange(sql, changeName, profile = exports.TIER_PROFILE) {
-    return profile.categorize((0, transform_1.classifyStatements)(sql), changeName);
+    return profile.categorize((0, semantics_1.classifyStatements)(sql), changeName);
 }
 /**
  * Build a `categoryOf(changeName)` seam function from a map of change name to

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/bundle-driver.js

@@ -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 { classifyStatements } from '@pgsql/transform';
+import { classifyStatements } from '@pgsql/semantics';
 import { createExtensionResult, createRoleResult, ExtensionRouter, RoleRouter, SchemaRouter, transformExtensions, transformRoles, transformSql } from '@pgsql/transform';
 /**
  * Build an {@link ExtensionRouter} from the declarative {@link ExtensionRoutingInput}:

package/esm/categorize.js

@@ -1,4 +1,4 @@
-import { classifyStatements } from '@pgsql/transform';
+import { classifyStatements } from '@pgsql/semantics';
 /**
  * Default tier profile: isolates the security surface and procedural code out
  * of the schema base. Precedence, highest first — a change is placed in the

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,4 +1,4 @@
-import { classifyStatements } from '@pgsql/transform';
+import { classifyStatements } from '@pgsql/semantics';
 import { TIER_PROFILE } from './categorize';
 function objectKey(schema, name) {
     return `${schema ?? ''}\u0000${name}`;

package/esm/granularity-driver.js

@@ -1,25 +1,10 @@
-/**
- * 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 { classifyStatements } from '@pgsql/semantics';
+import { buildStatementGraph, 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 +38,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 +91,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 +124,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 +170,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);

package/esm/index.js

@@ -1,9 +1,10 @@
 export { buildExtensionRouter, buildSchemaRouter, makeNamespaceValidator, makeSchemaTranspiler, } from './bundle-driver';
 export { diffCatalogSnapshots, snapshotCatalog, withoutColumnOrder } from './catalog-check';
 export { buildCategoryOf, categorizeChange, TIER_PROFILE, } from './categorize';
+export { defaultConstraintName, firstColumnRef } from './constraint-names';
 export { resolveFixtureClosure } from './fixture-closure';
-export { defaultChangeName, restructureChanges, } from './granularity-driver';
-export { checkOverwrite, writeControlFile, writeModule } from './module-emit';
+export { CHANGE_GRANULARITIES, defaultChangeName, isChangeGranularity, restructureChanges, } from './granularity-driver';
+export { appendModule, checkOverwrite, writeControlFile, writeModule } from './module-emit';
 export { loadModuleSource, stripTransactionWrapper } from './module-source';
 export { parsePartitionConfig, partitionExportRows } from './partition';
 export { PartitionCycleError, partitionUnits, RESIDUAL_UNIT_PATH, } from './partition-driver';
@@ -11,5 +12,6 @@ export { emitSqlProgram, parseSqlProgram } from './program';
 export { classifyScript, isStubScript, regenerateScripts, } from './regen';
 export { EXPORT_GRANULARITIES, isExportGranularity, restructureExportRows } from './restructure';
 export { diffChangeSets, diffSchemas, } from './semantic-diff-driver';
+export { nameUnnamedConstraints, subObjectIdentityOf } from './sub-object';
 export * from '@pgsql/transform';
 export { loadModule } from 'plpgsql-parser';

package/esm/module-emit.js

@@ -9,7 +9,7 @@
  * `pgpm import` all emit byte-identical module layouts instead of each
  * carrying its own copy of the writer.
  */
-import { writePgpmFiles, writePgpmPlan } from '@pgpmjs/ast';
+import { parseAuthor, parsePlanFile, writePgpmFiles, writePgpmPlan, writePlanFile } from '@pgpmjs/ast';
 import * as fs from 'fs';
 import * as path from 'path';
 /** Write a module's Postgres extension `.control` file. */
@@ -48,6 +48,76 @@ export const writeModule = (outBase, model, extraRequires = []) => {
     writePgpmFiles(model.rows, opts);
     return dir;
 };
+/**
+ * Append plan-ordered {@link PgpmRow}s into an *existing* module rather than
+ * writing a fresh package. Existing changes, their scripts, and the `.control`
+ * file are left untouched; only the new changes are written (deploy/revert/
+ * verify) and appended to `pgpm.plan` after the current changes.
+ *
+ * Rows whose change name already exists are skipped (never overwritten).
+ * A new change's dependency bracket is filtered to names that resolve within
+ * the plan (existing changes, other appended changes, or `pkg:`-external
+ * references); a dangling internal dependency is dropped with a warning
+ * (plan order still sequences it after the current changes).
+ */
+export const appendModule = (moduleDir, rows, options = {}) => {
+    const planPath = path.join(moduleDir, 'pgpm.plan');
+    if (!fs.existsSync(planPath)) {
+        throw new Error(`No pgpm.plan found at ${planPath}; append mode expects an existing pgpm module directory.`);
+    }
+    const parsed = parsePlanFile(planPath);
+    if (!parsed.data) {
+        throw new Error(`Failed to parse ${planPath}: ${parsed.errors
+            .map(e => `line ${e.line}: ${e.message}`)
+            .join('; ')}`);
+    }
+    const plan = parsed.data;
+    const existingNames = new Set(plan.changes.map(c => c.name));
+    const incomingNames = new Set(rows.map(r => r.deploy));
+    const appended = new Set();
+    const added = [];
+    const skipped = [];
+    const warnings = [];
+    const newRows = [];
+    const { fullName, email } = parseAuthor(options.author || 'constructive');
+    const timestamp = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+    for (const row of rows) {
+        if (existingNames.has(row.deploy) || appended.has(row.deploy)) {
+            skipped.push(row.deploy);
+            warnings.push(`change ${row.deploy} already exists in ${plan.package}; left untouched`);
+            continue;
+        }
+        const deps = (row.deps ?? []).filter(dep => {
+            if (dep.includes(':'))
+                return true; // cross-package (pkg:change) external
+            if (existingNames.has(dep) || incomingNames.has(dep))
+                return true;
+            warnings.push(`change ${row.deploy}: dropped dependency ${dep} (not present in ${plan.package})`);
+            return false;
+        });
+        plan.changes.push({
+            name: row.deploy,
+            dependencies: deps,
+            timestamp,
+            planner: fullName,
+            email: email || `${fullName}@constructive.io`,
+            comment: `add ${row.name ?? row.deploy}`
+        });
+        newRows.push({ ...row, deps });
+        appended.add(row.deploy);
+        added.push(row.deploy);
+    }
+    if (newRows.length) {
+        const opts = {
+            outdir: path.dirname(moduleDir),
+            name: path.basename(moduleDir),
+            replacer: (str) => str
+        };
+        writePgpmFiles(newRows, opts);
+        writePlanFile(planPath, plan);
+    }
+    return { dir: moduleDir, added, skipped, warnings };
+};
 /**
  * Guard against clobbering: writing into the source directory requires
  * `--write`, as does overwriting any existing package directory.

package/esm/partition-driver.js

@@ -1,7 +1,7 @@
 /**
  * Partition dial: project one deploy surface into a set of pgpm packages.
  *
- * The object graph (statements classified by `@pgsql/transform`, grouped
+ * The object graph (statements classified by `@pgsql/semantics`, grouped
  * into identity-keyed units) is the source of truth; which package a unit
  * lives in is a *derived projection* of a declarative partition config.
  * Units can be assigned by schema, by object kind, by explicit cherry-pick
@@ -21,7 +21,8 @@
  * pgpm.plan + deploy trees, feed a bundle, ...).
  */
 import { pathFor } from '@pgpmjs/naming-spec';
-import { buildStatementGraph, classifyStatements, identityOf } from '@pgsql/transform';
+import { classifyStatements } from '@pgsql/semantics';
+import { buildStatementGraph, identityOf } from '@pgsql/transform';
 /** A partition whose packages require each other in a cycle — unshippable. */
 export class PartitionCycleError extends Error {
     packages;

package/esm/program.js

@@ -1,4 +1,4 @@
-import { classifyStatements } from '@pgsql/transform';
+import { classifyStatements } from '@pgsql/semantics';
 import { Deparser, parseSql } from 'plpgsql-parser';
 /**
  * Parse a SQL script into a statement program. Requires `loadModule()` from

package/esm/regen.js

@@ -1,5 +1,5 @@
 import { revertFor, verifyFor } from '@pgsql/scripts';
-import { classifyStatements } from '@pgsql/transform';
+import { classifyStatements } from '@pgsql/semantics';
 /**
  * Classify a pgpm script's substantive statements: every top-level statement
  * except transaction control (`BEGIN`/`COMMIT`/`ROLLBACK` wrappers).

package/esm/restructure.js

@@ -33,7 +33,12 @@ export const restructureExportRows = async (rows, granularity, options = {}) =>
         name: row.deploy,
         dependencies: row.deps ?? [],
         deploy: row.content
-    })), { granularity, changeName });
+    })), {
+        granularity,
+        changeGranularity: options.changeGranularity,
+        changeName,
+        subObjectName: identity => pathFor(identity, { style })
+    });
     const counters = new Map();
     const taken = new Set();
     const restructured = changes.map(change => {