@pgpmjs/transform 0.15.3 → 0.16.0

package/esm/granularity-driver.js

@@ -1,4 +1,25 @@
-import { buildStatementGraph, classifyStatements, restructureSql } from '@pgsql/transform';
+/**
+ * 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';
 const KIND_DIRS = {
     table: 'tables',
     view: 'views',
@@ -10,21 +31,15 @@ const KIND_DIRS = {
     seed_dml: 'fixtures'
 };
 /**
- * Default pgpm-style change name for a statement group:
- * `schemas/<schema>` for schemas, `schemas/<schema>/<kind>/<name>` for
- * objects, `misc/<n>` when nothing better is known.
+ * Default change name for a statement group: the object's canonical naming
+ * spec v1 path — `identityOf(facts)` (Postgres-native identity, from
+ * `@pgsql/transform`) rendered through `pathFor` (`@pgpmjs/naming-spec`).
+ * Paths are pure projections of identity, never authored.
  */
 export function defaultChangeName(facts) {
-    const created = facts.creates[0];
-    if (facts.kind === 'schema' && created)
-        return `schemas/${created.name}`;
-    if (created) {
-        const dir = KIND_DIRS[facts.kind] ?? 'objects';
-        const schema = created.schema ?? 'public';
-        // Trigger/policy names are table-qualified (`table.trigger`).
-        const name = created.name.replace(/\./g, '/');
-        return `schemas/${schema}/${dir}/${name}`;
-    }
+    const identity = identityOf(facts);
+    if (identity)
+        return pathFor(identity);
     return 'misc/statements';
 }
 /**
@@ -85,13 +100,16 @@ export function restructureChanges(changes, options) {
             schemaGroup.set(f.creates[0].name, groupOf[i]);
         }
     });
-    // Slice statement text per group, in the emitted (topological) order.
+    // Slice statement text per group, in the emitted (topological) order,
+    // and collect each group's facts for revert/verify generation.
     const groupSql = groupNames.map(() => []);
+    const groupStatements = groupNames.map(() => []);
     facts.forEach((f, i) => {
         const text = sql.slice(f.span.start, f.span.start + f.span.len).trim();
         const g = groupOf[i];
         if (g !== -1 && text) {
             groupSql[g].push(text.endsWith(';') ? text : `${text};`);
+            groupStatements[g].push(f);
         }
     });
     // Change dependencies = statement edges projected onto groups, plus
@@ -128,10 +146,22 @@ export function restructureChanges(changes, options) {
     });
     const result = order
         .filter(g => groupSql[g].length > 0)
-        .map(g => ({
-        name: groupNames[g],
-        dependencies: [...groupDeps[g]].map(d => groupNames[d]).sort(),
-        deploy: groupSql[g].join('\n\n')
-    }));
+        .map(g => {
+        const revert = revertFor(groupStatements[g]);
+        const verify = verifyFor(groupStatements[g]);
+        for (const warning of revert.warnings) {
+            warnings.push(`${groupNames[g]}: ${warning}`);
+        }
+        for (const warning of verify.warnings) {
+            warnings.push(`${groupNames[g]}: ${warning}`);
+        }
+        return {
+            name: groupNames[g],
+            dependencies: [...groupDeps[g]].map(d => groupNames[d]).sort(),
+            deploy: groupSql[g].join('\n\n'),
+            revert: revert.sql,
+            verify: verify.sql
+        };
+    });
     return { changes: result, warnings };
 }

package/esm/index.js

@@ -2,6 +2,7 @@ export * from '@pgsql/transform';
 export { loadModule } from 'plpgsql-parser';
 export { buildExtensionRouter, buildSchemaRouter, makeNamespaceValidator, makeSchemaTranspiler, } from './bundle-driver';
 export { defaultChangeName, restructureChanges, } from './granularity-driver';
+export { PartitionCycleError, partitionUnits, RESIDUAL_UNIT_PATH, } from './partition-driver';
 export { buildCategoryOf, categorizeChange, TIER_PROFILE, } from './categorize';
 export { resolveFixtureClosure } from './fixture-closure';
 export { emitSqlProgram, parseSqlProgram } from './program';

package/esm/partition-driver.js

@@ -0,0 +1,363 @@
+/**
+ * Partition dial: project one deploy surface into a set of pgpm packages.
+ *
+ * The object graph (statements classified by `@pgsql/transform`, 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
+ * (identity or derived path), or dragged in as the dependency closure of a
+ * package's seeds. `requires` headers are a mechanical post-pass over the
+ * statement graph: intra-package edges become `requires: <path>`,
+ * cross-package edges become `requires: <pkg>:<path>` — both rendered
+ * through the naming spec, never authored.
+ *
+ * A partition is rejected (hard error) when packages require each other in
+ * a cycle: that is the one unshippable configuration, because no package
+ * install order can satisfy it.
+ *
+ * Like the other drivers in this package the emit shape is structurally
+ * typed on the change seam — no dependency on `@pgpmjs/bundle` or
+ * `@pgpmjs/core`. Callers materialize packages however they like (write
+ * pgpm.plan + deploy trees, feed a bundle, ...).
+ */
+import { pathFor } from '@pgpmjs/naming-spec';
+import { buildStatementGraph, classifyStatements, identityOf } from '@pgsql/transform';
+/** A partition whose packages require each other in a cycle — unshippable. */
+export class PartitionCycleError extends Error {
+    packages;
+    edges;
+    constructor(
+    /** The packages forming the cycle. */
+    packages, 
+    /** One offending edge per hop: `fromPkg:fromPath -> toPkg:toPath`. */
+    edges) {
+        super(`cross-package dependency cycle: ${packages.join(' -> ')} -> ${packages[0]}\n` +
+            edges.map(e => `  ${e}`).join('\n'));
+        this.packages = packages;
+        this.edges = edges;
+        this.name = 'PartitionCycleError';
+    }
+}
+const identityKey = (id) => `${id.kind}\u0000${id.schema ?? ''}\u0000${id.table ?? ''}\u0000${id.name}`;
+const matchField = (value, wanted) => {
+    if (wanted === undefined)
+        return true;
+    return Array.isArray(wanted) ? wanted.includes(value) : wanted === value;
+};
+function matches(unit, selector) {
+    if (!matchField(unit.path, selector.path))
+        return false;
+    if (!matchField(unit.primaryKind, selector.statementKind))
+        return false;
+    const id = unit.identity;
+    if (selector.kind === undefined && selector.schema === undefined &&
+        selector.name === undefined && selector.table === undefined) {
+        return true;
+    }
+    if (!id)
+        return false;
+    // A schema object's own name counts as its schema, so `{ schema: 'x' }`
+    // selects the schema together with everything in it.
+    const schema = id.kind === 'schema' ? id.name : id.schema;
+    return (matchField(id.kind, selector.kind) &&
+        matchField(schema, selector.schema) &&
+        matchField(id.name, selector.name) &&
+        matchField(id.table, selector.table));
+}
+/** Path of the residual unit for statements attributable to no object. */
+export const RESIDUAL_UNIT_PATH = 'misc/statements';
+/**
+ * Group a classified script into identity-keyed units and compute unit-level
+ * dependencies from the statement graph.
+ *
+ * Statements with no identity of their own (grants, comments) ride with the
+ * unit of the object they target — resolved through the statement graph's
+ * edges — falling back to the closest preceding statement's unit; lead-in
+ * statements with no unit at all land in a residual unit so nothing is
+ * silently dropped. Kinds listed in `splitRiders` become standalone units
+ * (named `<hostPath>/grants/<role>` for grants, `<hostPath>/<kind>/<n>`
+ * otherwise) that depend on their host unit.
+ */
+function buildUnitGraph(sql, style, splitRiders) {
+    const facts = classifyStatements(sql);
+    const graph = buildStatementGraph(facts);
+    const unitOf = new Array(facts.length).fill(-1);
+    const units = [];
+    const byIdentity = new Map();
+    const takenPaths = new Set();
+    const newUnit = (identity, primaryKind, path) => {
+        units.push({ identity, primaryKind, path, statements: [], sql: '', dynamicSql: false });
+        takenPaths.add(path);
+        return units.length - 1;
+    };
+    // Naming-spec path for a unit; ENABLE ROW LEVEL SECURITY uses the spec's
+    // dedicated rls template rather than its constraint-shaped identity.
+    const unitPath = (identity, kind) => {
+        if (kind === 'rls_enable' && identity.table) {
+            return `schemas/${identity.schema ?? 'public'}/tables/${identity.table}/policies/enable_row_level_security`;
+        }
+        return pathFor(identity, { style });
+    };
+    const unitFor = (identity, kind) => {
+        const key = identity ? identityKey(identity) : RESIDUAL_UNIT_PATH;
+        let u = byIdentity.get(key);
+        if (u === undefined) {
+            u = newUnit(identity, kind, identity ? unitPath(identity, kind) : RESIDUAL_UNIT_PATH);
+            byIdentity.set(key, u);
+        }
+        return u;
+    };
+    // Object-owning units by qualified name, for rider host resolution. Only
+    // top-level objects qualify (table-scoped identities share the table's
+    // qualified name and must not shadow it).
+    const objectUnits = new Map();
+    const registerObject = (identity, u) => {
+        if (identity.table)
+            return;
+        objectUnits.set(`${identity.schema ?? ''}.${identity.name}`, u);
+    };
+    /** Host unit of a rider statement: the unit owning the first object it
+     *  references, falling back to the preceding statement's unit. */
+    const hostOf = (i) => {
+        for (const r of facts[i].references) {
+            const u = objectUnits.get(`${r.schema ?? ''}.${r.name}`);
+            if (u !== undefined)
+                return u;
+        }
+        if (i > 0 && unitOf[i - 1] !== -1)
+            return unitOf[i - 1];
+        return -1;
+    };
+    const riderPath = (f, host) => {
+        const base = host !== -1 ? units[host].path : RESIDUAL_UNIT_PATH;
+        const dir = f.kind === 'grant' ? 'grants' : f.kind;
+        const label = f.roles.length > 0 ? f.roles.join('_') : f.kind;
+        let path = `${base}/${dir}/${label}`;
+        for (let n = 2; takenPaths.has(path); n++)
+            path = `${base}/${dir}/${label}-${n}`;
+        return path;
+    };
+    const hostUnit = new Map();
+    facts.forEach((f, i) => {
+        const identity = identityOf(f);
+        if (identity && !splitRiders.has(f.kind)) {
+            unitOf[i] = unitFor(identity, f.kind);
+            registerObject(identity, unitOf[i]);
+            return;
+        }
+        const host = hostOf(i);
+        if (splitRiders.has(f.kind)) {
+            unitOf[i] = newUnit(identity, f.kind, identity ? unitPath(identity, f.kind) : riderPath(f, host));
+            if (identity)
+                registerObject(identity, unitOf[i]);
+            if (host !== -1)
+                hostUnit.set(unitOf[i], host);
+            return;
+        }
+        // No identity: ride with the host unit.
+        if (host !== -1) {
+            unitOf[i] = host;
+            return;
+        }
+        unitOf[i] = unitFor(null, f.kind);
+    });
+    facts.forEach((f, i) => {
+        const text = sql.slice(f.span.start, f.span.start + f.span.len).trim();
+        if (!text)
+            return;
+        const unit = units[unitOf[i]];
+        unit.statements.push(i);
+        unit.sql += (unit.sql ? '\n\n' : '') + (text.endsWith(';') ? text : `${text};`);
+        if (f.dynamicSql)
+            unit.dynamicSql = true;
+    });
+    // Unit dependencies: statement edges (late edges do not constrain deploy
+    // order), plus schema membership (an object requires its schema's unit).
+    const deps = units.map(() => new Set());
+    for (const edge of graph.edges) {
+        if (edge.kind === 'late')
+            continue;
+        const from = unitOf[edge.from];
+        const to = unitOf[edge.to];
+        if (from !== -1 && to !== -1 && from !== to)
+            deps[from].add(to);
+    }
+    // A split rider requires its host object; a table-scoped object (trigger,
+    // policy, index, constraint, RLS) requires its table.
+    for (const [u, host] of hostUnit) {
+        if (u !== host)
+            deps[u].add(host);
+    }
+    units.forEach((u, i) => {
+        const id = u.identity;
+        if (!id?.table)
+            return;
+        const table = objectUnits.get(`${id.schema ?? ''}.${id.table}`);
+        if (table !== undefined && table !== i)
+            deps[i].add(table);
+    });
+    const schemaUnit = new Map();
+    units.forEach((u, i) => {
+        if (u.identity?.kind === 'schema')
+            schemaUnit.set(u.identity.name, i);
+    });
+    facts.forEach((f, i) => {
+        const from = unitOf[i];
+        if (from === -1)
+            return;
+        const schemas = new Set(f.referencedSchemas);
+        for (const created of f.creates) {
+            if (created.schema)
+                schemas.add(created.schema);
+        }
+        for (const schema of schemas) {
+            const to = schemaUnit.get(schema);
+            if (to !== undefined && to !== from)
+                deps[from].add(to);
+        }
+    });
+    return { facts, units, unitOf, deps, source: sql };
+}
+/**
+ * Partition a deploy surface into packages.
+ *
+ * Accepts either raw SQL or pgpm changes (whose deploy scripts are flattened
+ * in the given order — run the granularity dial first if a different unit
+ * shape is wanted). Requires `loadModule()` from `plpgsql-parser` first.
+ *
+ * Assignment: for each unit the first matching rule wins; unmatched units go
+ * to `defaultPackage`. Closure rules then pull the transitive dependency
+ * closure (hard + fk) of their units out of the default package. Finally the
+ * requires post-pass renders every unit dependency through the naming spec —
+ * same package as `<path>`, cross-package as `<pkg>:<path>` — and the
+ * package-level graph is checked for cycles ({@link PartitionCycleError}).
+ */
+export function partitionUnits(input, config) {
+    const style = config.style ?? 'directory';
+    const sql = typeof input === 'string'
+        ? input
+        : input.map(c => c.deploy.trim()).filter(Boolean).join('\n\n');
+    const { units, deps } = buildUnitGraph(sql, style, new Set(config.splitRiders ?? []));
+    const warnings = [];
+    // 1. Assignment: first matching rule wins.
+    const packageOf = units.map(unit => {
+        for (const rule of config.rules) {
+            if (rule.select.some(s => matches(unit, s)))
+                return rule.package;
+        }
+        return config.defaultPackage;
+    });
+    // 2. Closure: pull each closure rule's dependency closure out of the
+    // default package (never out of another rule's package).
+    const closureIncluded = new Map();
+    for (const rule of config.rules) {
+        if (!rule.closure)
+            continue;
+        const queue = units.map((_, i) => i).filter(i => packageOf[i] === rule.package);
+        const seen = new Set(queue);
+        while (queue.length > 0) {
+            const current = queue.shift();
+            for (const dep of deps[current]) {
+                if (seen.has(dep))
+                    continue;
+                seen.add(dep);
+                if (packageOf[dep] === rule.package) {
+                    queue.push(dep);
+                    continue;
+                }
+                if (packageOf[dep] !== config.defaultPackage)
+                    continue;
+                packageOf[dep] = rule.package;
+                closureIncluded.set(units[dep].path, rule.package);
+                queue.push(dep);
+            }
+        }
+    }
+    // Dynamic SQL makes edges incomplete: surface it, do not guess.
+    units.forEach((unit, i) => {
+        if (unit.dynamicSql && unit.statements.length > 0) {
+            warnings.push(`${units[i].path} (${packageOf[i]}) executes dynamic SQL; hidden references cannot be checked against the partition`);
+        }
+    });
+    // 3. Requires post-pass + package-level graph.
+    const pkgNames = [...new Set([...packageOf, config.defaultPackage])];
+    const pkgIndex = new Map(pkgNames.map((p, i) => [p, i]));
+    const pkgEdges = new Map();
+    const changesByPkg = new Map();
+    for (const p of pkgNames)
+        changesByPkg.set(p, []);
+    units.forEach((unit, i) => {
+        if (unit.statements.length === 0)
+            return;
+        const pkg = packageOf[i];
+        const dependencies = [...deps[i]]
+            .filter(d => units[d].statements.length > 0)
+            .map(d => {
+            const depPkg = packageOf[d];
+            if (depPkg === pkg)
+                return units[d].path;
+            const key = `${pkg}\u0000${depPkg}`;
+            if (!pkgEdges.has(key)) {
+                pkgEdges.set(key, {
+                    from: pkgIndex.get(pkg),
+                    to: pkgIndex.get(depPkg),
+                    via: `${pkg}:${unit.path} -> ${depPkg}:${units[d].path}`
+                });
+            }
+            return `${depPkg}:${units[d].path}`;
+        })
+            .sort();
+        changesByPkg.get(pkg).push({ name: unit.path, dependencies, deploy: unit.sql });
+    });
+    // 4. Cross-package cycle detection over the package graph.
+    detectCycles(pkgNames, [...pkgEdges.values()]);
+    const assignments = new Map();
+    units.forEach((unit, i) => {
+        if (unit.statements.length > 0)
+            assignments.set(unit.path, packageOf[i]);
+    });
+    const packages = pkgNames
+        .map(name => ({
+        name,
+        changes: changesByPkg.get(name),
+        requires: [...new Set([...pkgEdges.values()]
+                .filter(e => pkgNames[e.from] === name)
+                .map(e => pkgNames[e.to]))].sort()
+    }))
+        .filter(p => p.changes.length > 0);
+    return { packages, assignments, closureIncluded, warnings };
+}
+function detectCycles(pkgNames, edges) {
+    const out = new Map();
+    for (const e of edges) {
+        const list = out.get(e.from) ?? [];
+        list.push({ to: e.to, via: e.via });
+        out.set(e.from, list);
+    }
+    const state = new Array(pkgNames.length).fill(0); // 0 unseen, 1 on stack, 2 done
+    const stack = [];
+    const viaStack = [];
+    const visit = (v) => {
+        state[v] = 1;
+        stack.push(v);
+        for (const { to, via } of out.get(v) ?? []) {
+            if (state[to] === 2)
+                continue;
+            viaStack.push(via);
+            if (state[to] === 1) {
+                const start = stack.indexOf(to);
+                const cyclePkgs = stack.slice(start).map(i => pkgNames[i]);
+                const cycleEdges = viaStack.slice(viaStack.length - cyclePkgs.length);
+                throw new PartitionCycleError(cyclePkgs, cycleEdges);
+            }
+            visit(to);
+            viaStack.pop();
+        }
+        stack.pop();
+        state[v] = 2;
+    };
+    for (let v = 0; v < pkgNames.length; v++) {
+        if (state[v] === 0)
+            visit(v);
+    }
+}

package/granularity-driver.d.ts

@@ -1,52 +1,49 @@
-/**
- * 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 type { Granularity, StatementFacts } from '@pgsql/transform';
 export type { Granularity } from '@pgsql/transform';
 /** A change's deploy surface going into or out of the restructure. */
 export interface GranularityChange {
-    /** Change name (plan token, e.g. `schemas/app/tables/users`). */
+    /** Change name (plan token, e.g. `schemas/app/tables/users/table`). */
     name: string;
     /** Change names this change requires (within the same module). */
     dependencies: string[];
     /** Deploy SQL (headerless — the caller owns pgpm headers). */
     deploy: string;
 }
+/** A restructured change: deploy plus generated revert/verify scripts. */
+export interface RestructuredChange extends GranularityChange {
+    /**
+     * Generated revert SQL (headerless): mechanical inverses of the change's
+     * statements in reverse topological order within the group, via
+     * `revertFor`. Non-invertible statements leave a `-- revert not
+     * derivable` comment and a warning.
+     */
+    revert: string;
+    /**
+     * Generated verify SQL (headerless): one raise-on-failure existence check
+     * per created object, via `verifyFor`.
+     */
+    verify: string;
+}
 export interface RestructureModuleOptions {
     granularity: Granularity;
     /**
      * Derive a change name for a statement group from the facts of its primary
-     * (creating) statement. Defaults to {@link defaultChangeName}: pgpm-style
-     * `schemas/<schema>` / `schemas/<schema>/tables/<name>` paths.
+     * (creating) statement. Defaults to {@link defaultChangeName}: naming spec
+     * v1 paths (`identityOf` + `pathFor`).
      */
     changeName?: (facts: StatementFacts) => string;
 }
 export interface RestructureModuleResult {
     /** Restructured changes in deploy order, dependencies recomputed. */
-    changes: GranularityChange[];
+    changes: RestructuredChange[];
     /** Non-fatal notes (folds rejected to preserve ordering, etc.). */
     warnings: string[];
 }
 /**
- * Default pgpm-style change name for a statement group:
- * `schemas/<schema>` for schemas, `schemas/<schema>/<kind>/<name>` for
- * objects, `misc/<n>` when nothing better is known.
+ * Default change name for a statement group: the object's canonical naming
+ * spec v1 path — `identityOf(facts)` (Postgres-native identity, from
+ * `@pgsql/transform`) rendered through `pathFor` (`@pgpmjs/naming-spec`).
+ * Paths are pure projections of identity, never authored.
  */
 export declare function defaultChangeName(facts: StatementFacts): string;
 /**

package/granularity-driver.js

@@ -2,6 +2,27 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defaultChangeName = defaultChangeName;
 exports.restructureChanges = restructureChanges;
+/**
+ * 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.
+ */
+const naming_spec_1 = require("@pgpmjs/naming-spec");
+const scripts_1 = require("@pgsql/scripts");
 const transform_1 = require("@pgsql/transform");
 const KIND_DIRS = {
     table: 'tables',
@@ -14,21 +35,15 @@ const KIND_DIRS = {
     seed_dml: 'fixtures'
 };
 /**
- * Default pgpm-style change name for a statement group:
- * `schemas/<schema>` for schemas, `schemas/<schema>/<kind>/<name>` for
- * objects, `misc/<n>` when nothing better is known.
+ * Default change name for a statement group: the object's canonical naming
+ * spec v1 path — `identityOf(facts)` (Postgres-native identity, from
+ * `@pgsql/transform`) rendered through `pathFor` (`@pgpmjs/naming-spec`).
+ * Paths are pure projections of identity, never authored.
  */
 function defaultChangeName(facts) {
-    const created = facts.creates[0];
-    if (facts.kind === 'schema' && created)
-        return `schemas/${created.name}`;
-    if (created) {
-        const dir = KIND_DIRS[facts.kind] ?? 'objects';
-        const schema = created.schema ?? 'public';
-        // Trigger/policy names are table-qualified (`table.trigger`).
-        const name = created.name.replace(/\./g, '/');
-        return `schemas/${schema}/${dir}/${name}`;
-    }
+    const identity = (0, transform_1.identityOf)(facts);
+    if (identity)
+        return (0, naming_spec_1.pathFor)(identity);
     return 'misc/statements';
 }
 /**
@@ -89,13 +104,16 @@ function restructureChanges(changes, options) {
             schemaGroup.set(f.creates[0].name, groupOf[i]);
         }
     });
-    // Slice statement text per group, in the emitted (topological) order.
+    // Slice statement text per group, in the emitted (topological) order,
+    // and collect each group's facts for revert/verify generation.
     const groupSql = groupNames.map(() => []);
+    const groupStatements = groupNames.map(() => []);
     facts.forEach((f, i) => {
         const text = sql.slice(f.span.start, f.span.start + f.span.len).trim();
         const g = groupOf[i];
         if (g !== -1 && text) {
             groupSql[g].push(text.endsWith(';') ? text : `${text};`);
+            groupStatements[g].push(f);
         }
     });
     // Change dependencies = statement edges projected onto groups, plus
@@ -132,10 +150,22 @@ function restructureChanges(changes, options) {
     });
     const result = order
         .filter(g => groupSql[g].length > 0)
-        .map(g => ({
-        name: groupNames[g],
-        dependencies: [...groupDeps[g]].map(d => groupNames[d]).sort(),
-        deploy: groupSql[g].join('\n\n')
-    }));
+        .map(g => {
+        const revert = (0, scripts_1.revertFor)(groupStatements[g]);
+        const verify = (0, scripts_1.verifyFor)(groupStatements[g]);
+        for (const warning of revert.warnings) {
+            warnings.push(`${groupNames[g]}: ${warning}`);
+        }
+        for (const warning of verify.warnings) {
+            warnings.push(`${groupNames[g]}: ${warning}`);
+        }
+        return {
+            name: groupNames[g],
+            dependencies: [...groupDeps[g]].map(d => groupNames[d]).sort(),
+            deploy: groupSql[g].join('\n\n'),
+            revert: revert.sql,
+            verify: verify.sql
+        };
+    });
     return { changes: result, warnings };
 }

package/index.d.ts

@@ -2,8 +2,10 @@ export * from '@pgsql/transform';
 export { loadModule } from 'plpgsql-parser';
 export type { BundleScriptContext, ExtensionRoutingInput, NamespaceValidatorOptions, SchemaObjectRoute, SchemaTranspiler, SchemaTranspilerOptions, } from './bundle-driver';
 export { buildExtensionRouter, buildSchemaRouter, makeNamespaceValidator, makeSchemaTranspiler, } from './bundle-driver';
-export type { GranularityChange, RestructureModuleOptions, RestructureModuleResult, } from './granularity-driver';
+export type { GranularityChange, RestructuredChange, RestructureModuleOptions, RestructureModuleResult, } from './granularity-driver';
 export { defaultChangeName, restructureChanges, } from './granularity-driver';
+export type { PartitionConfig, PartitionedChange, PartitionedPackage, PartitionInputChange, PartitionRule, PartitionUnit, PartitionUnitsResult, UnitSelector, } from './partition-driver';
+export { PartitionCycleError, partitionUnits, RESIDUAL_UNIT_PATH, } from './partition-driver';
 export type { CategoryProfile, ChangeCategory, } from './categorize';
 export { buildCategoryOf, categorizeChange, TIER_PROFILE, } from './categorize';
 export type { ClosureChange, ClosureInputChange, ClosureReason, FixtureClosure, ResolveFixtureClosureOptions, } from './fixture-closure';

package/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseSqlProgram = exports.emitSqlProgram = exports.resolveFixtureClosure = exports.TIER_PROFILE = exports.categorizeChange = exports.buildCategoryOf = exports.restructureChanges = exports.defaultChangeName = exports.makeSchemaTranspiler = exports.makeNamespaceValidator = exports.buildSchemaRouter = exports.buildExtensionRouter = exports.loadModule = void 0;
+exports.parseSqlProgram = exports.emitSqlProgram = exports.resolveFixtureClosure = exports.TIER_PROFILE = exports.categorizeChange = exports.buildCategoryOf = exports.RESIDUAL_UNIT_PATH = exports.partitionUnits = exports.PartitionCycleError = exports.restructureChanges = exports.defaultChangeName = exports.makeSchemaTranspiler = exports.makeNamespaceValidator = exports.buildSchemaRouter = exports.buildExtensionRouter = exports.loadModule = void 0;
 __exportStar(require("@pgsql/transform"), exports);
 var plpgsql_parser_1 = require("plpgsql-parser");
 Object.defineProperty(exports, "loadModule", { enumerable: true, get: function () { return plpgsql_parser_1.loadModule; } });
@@ -26,6 +26,10 @@ Object.defineProperty(exports, "makeSchemaTranspiler", { enumerable: true, get:
 var granularity_driver_1 = require("./granularity-driver");
 Object.defineProperty(exports, "defaultChangeName", { enumerable: true, get: function () { return granularity_driver_1.defaultChangeName; } });
 Object.defineProperty(exports, "restructureChanges", { enumerable: true, get: function () { return granularity_driver_1.restructureChanges; } });
+var partition_driver_1 = require("./partition-driver");
+Object.defineProperty(exports, "PartitionCycleError", { enumerable: true, get: function () { return partition_driver_1.PartitionCycleError; } });
+Object.defineProperty(exports, "partitionUnits", { enumerable: true, get: function () { return partition_driver_1.partitionUnits; } });
+Object.defineProperty(exports, "RESIDUAL_UNIT_PATH", { enumerable: true, get: function () { return partition_driver_1.RESIDUAL_UNIT_PATH; } });
 var categorize_1 = require("./categorize");
 Object.defineProperty(exports, "buildCategoryOf", { enumerable: true, get: function () { return categorize_1.buildCategoryOf; } });
 Object.defineProperty(exports, "categorizeChange", { enumerable: true, get: function () { return categorize_1.categorizeChange; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgpmjs/transform",
-  "version": "0.15.3",
+  "version": "0.16.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "Change-aware SQL transformation for PGPM — superset of @pgsql/transform plus change categorization, fixture closure, and bundle transpile/apply drivers",
   "main": "index.js",
@@ -43,8 +43,10 @@
     "makage": "^0.3.0"
   },
   "dependencies": {
-    "@pgsql/transform": "^18.10.0",
+    "@pgpmjs/naming-spec": "^0.1.2",
+    "@pgsql/scripts": "^18.0.0",
+    "@pgsql/transform": "^18.11.0",
     "plpgsql-parser": "^18.2.2"
   },
-  "gitHead": "90f447482b056a4949134565db2665f21d11aca3"
+  "gitHead": "7a37da1f5655c36813343f09c6efa62ca0d7a855"
 }

package/partition-driver.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Partition dial: project one deploy surface into a set of pgpm packages.
+ *
+ * The object graph (statements classified by `@pgsql/transform`, 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
+ * (identity or derived path), or dragged in as the dependency closure of a
+ * package's seeds. `requires` headers are a mechanical post-pass over the
+ * statement graph: intra-package edges become `requires: <path>`,
+ * cross-package edges become `requires: <pkg>:<path>` — both rendered
+ * through the naming spec, never authored.
+ *
+ * A partition is rejected (hard error) when packages require each other in
+ * a cycle: that is the one unshippable configuration, because no package
+ * install order can satisfy it.
+ *
+ * Like the other drivers in this package the emit shape is structurally
+ * typed on the change seam — no dependency on `@pgpmjs/bundle` or
+ * `@pgpmjs/core`. Callers materialize packages however they like (write
+ * pgpm.plan + deploy trees, feed a bundle, ...).
+ */
+import { PathStyle } from '@pgpmjs/naming-spec';
+import { ObjectIdentity, ObjectIdentityKind, StatementKind } from '@pgsql/transform';
+/** One deployable unit: an object (by identity) and the statements that build it. */
+export interface PartitionUnit {
+    /** The object's identity, or `null` for split riders and the residual unit. */
+    identity: ObjectIdentity | null;
+    /** Statement kind of the unit's primary statement (`grant` for split grants, ...). */
+    primaryKind: StatementKind;
+    /** Canonical change path derived from the identity via the naming spec. */
+    path: string;
+    /** Indexes into the classified statement list, in source order. */
+    statements: number[];
+    /** The unit's deploy SQL (statement text joined in source order). */
+    sql: string;
+    /**
+     * A statement in this unit executes dynamic SQL: its edges are incomplete,
+     * so assignments involving it cannot be proven safe by the graph alone.
+     */
+    dynamicSql: boolean;
+}
+/**
+ * Matches units for assignment. Every given field must match (AND); array
+ * values match any element (OR). Omitted fields match everything, so
+ * `{ schema: 'billing' }` selects a whole schema, `{ kind: 'policy' }`
+ * selects every policy, and `{ path: 'schemas/app/tables/users/table' }`
+ * cherry-picks one object.
+ */
+export interface UnitSelector {
+    kind?: ObjectIdentityKind | ObjectIdentityKind[];
+    /**
+     * Statement-level kind of the unit's primary statement — selects units
+     * that have no object identity, like grants split out via
+     * {@link PartitionConfig.splitRiders} (`statementKind: 'grant'`).
+     */
+    statementKind?: StatementKind | StatementKind[];
+    schema?: string | string[];
+    name?: string | string[];
+    /** Owning table, for table-scoped kinds (trigger/policy/index/constraint/seed). */
+    table?: string | string[];
+    /** The derived naming-spec path — exact cherry-pick. */
+    path?: string | string[];
+}
+/** Assigns matching units to a package. Rules are tried in order; first match wins. */
+export interface PartitionRule {
+    package: string;
+    /** A unit matching ANY of these selectors is assigned to `package`. */
+    select: UnitSelector[];
+    /**
+     * Also pull in the transitive dependency closure (hard + fk edges) of the
+     * selected units. Only units that would otherwise land in the default
+     * package are pulled — a unit another rule claimed stays where it is and
+     * becomes an ordinary cross-package dependency.
+     */
+    closure?: boolean;
+}
+export interface PartitionConfig {
+    /** Assignment rules, in priority order. */
+    rules: PartitionRule[];
+    /** Package for units no rule matches. */
+    defaultPackage: string;
+    /** Naming-spec rendering style for derived paths (default `directory`). */
+    style?: PathStyle;
+    /**
+     * Statement kinds to split out of their host unit into standalone units
+     * (e.g. `['grant']` makes every GRANT its own selectable unit named
+     * `<hostPath>/grants/<role>`), so security surface can be partitioned
+     * independently of the objects it attaches to. Split units depend on
+     * their host, so ordering stays correct wherever they are assigned.
+     */
+    splitRiders?: StatementKind[];
+}
+/** One emitted change of a partitioned package. */
+export interface PartitionedChange {
+    /** Change path (naming spec). */
+    name: string;
+    /**
+     * Same-package dependencies as plain paths, cross-package dependencies as
+     * `<pkg>:<path>` — the pgpm cross-package requires convention.
+     */
+    dependencies: string[];
+    deploy: string;
+}
+export interface PartitionedPackage {
+    name: string;
+    /** Changes in a valid deploy order (statement-graph topological order). */
+    changes: PartitionedChange[];
+    /** Package names this package requires (from cross-package edges). */
+    requires: string[];
+}
+export interface PartitionUnitsResult {
+    packages: PartitionedPackage[];
+    /** unit path → package name, for every unit. */
+    assignments: Map<string, string>;
+    /** Units pulled in by closure rules: path → the rule's package. */
+    closureIncluded: Map<string, string>;
+    warnings: string[];
+}
+/** A partition whose packages require each other in a cycle — unshippable. */
+export declare class PartitionCycleError extends Error {
+    /** The packages forming the cycle. */
+    readonly packages: string[];
+    /** One offending edge per hop: `fromPkg:fromPath -> toPkg:toPath`. */
+    readonly edges: string[];
+    constructor(
+    /** The packages forming the cycle. */
+    packages: string[], 
+    /** One offending edge per hop: `fromPkg:fromPath -> toPkg:toPath`. */
+    edges: string[]);
+}
+/** Path of the residual unit for statements attributable to no object. */
+export declare const RESIDUAL_UNIT_PATH = "misc/statements";
+/** A change's deploy surface going into the partition (same seam as the granularity driver). */
+export interface PartitionInputChange {
+    name: string;
+    dependencies: string[];
+    deploy: string;
+}
+/**
+ * Partition a deploy surface into packages.
+ *
+ * Accepts either raw SQL or pgpm changes (whose deploy scripts are flattened
+ * in the given order — run the granularity dial first if a different unit
+ * shape is wanted). Requires `loadModule()` from `plpgsql-parser` first.
+ *
+ * Assignment: for each unit the first matching rule wins; unmatched units go
+ * to `defaultPackage`. Closure rules then pull the transitive dependency
+ * closure (hard + fk) of their units out of the default package. Finally the
+ * requires post-pass renders every unit dependency through the naming spec —
+ * same package as `<path>`, cross-package as `<pkg>:<path>` — and the
+ * package-level graph is checked for cycles ({@link PartitionCycleError}).
+ */
+export declare function partitionUnits(input: string | PartitionInputChange[], config: PartitionConfig): PartitionUnitsResult;

package/partition-driver.js

@@ -0,0 +1,368 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESIDUAL_UNIT_PATH = exports.PartitionCycleError = void 0;
+exports.partitionUnits = partitionUnits;
+/**
+ * Partition dial: project one deploy surface into a set of pgpm packages.
+ *
+ * The object graph (statements classified by `@pgsql/transform`, 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
+ * (identity or derived path), or dragged in as the dependency closure of a
+ * package's seeds. `requires` headers are a mechanical post-pass over the
+ * statement graph: intra-package edges become `requires: <path>`,
+ * cross-package edges become `requires: <pkg>:<path>` — both rendered
+ * through the naming spec, never authored.
+ *
+ * A partition is rejected (hard error) when packages require each other in
+ * a cycle: that is the one unshippable configuration, because no package
+ * install order can satisfy it.
+ *
+ * Like the other drivers in this package the emit shape is structurally
+ * typed on the change seam — no dependency on `@pgpmjs/bundle` or
+ * `@pgpmjs/core`. Callers materialize packages however they like (write
+ * pgpm.plan + deploy trees, feed a bundle, ...).
+ */
+const naming_spec_1 = require("@pgpmjs/naming-spec");
+const transform_1 = require("@pgsql/transform");
+/** A partition whose packages require each other in a cycle — unshippable. */
+class PartitionCycleError extends Error {
+    packages;
+    edges;
+    constructor(
+    /** The packages forming the cycle. */
+    packages, 
+    /** One offending edge per hop: `fromPkg:fromPath -> toPkg:toPath`. */
+    edges) {
+        super(`cross-package dependency cycle: ${packages.join(' -> ')} -> ${packages[0]}\n` +
+            edges.map(e => `  ${e}`).join('\n'));
+        this.packages = packages;
+        this.edges = edges;
+        this.name = 'PartitionCycleError';
+    }
+}
+exports.PartitionCycleError = PartitionCycleError;
+const identityKey = (id) => `${id.kind}\u0000${id.schema ?? ''}\u0000${id.table ?? ''}\u0000${id.name}`;
+const matchField = (value, wanted) => {
+    if (wanted === undefined)
+        return true;
+    return Array.isArray(wanted) ? wanted.includes(value) : wanted === value;
+};
+function matches(unit, selector) {
+    if (!matchField(unit.path, selector.path))
+        return false;
+    if (!matchField(unit.primaryKind, selector.statementKind))
+        return false;
+    const id = unit.identity;
+    if (selector.kind === undefined && selector.schema === undefined &&
+        selector.name === undefined && selector.table === undefined) {
+        return true;
+    }
+    if (!id)
+        return false;
+    // A schema object's own name counts as its schema, so `{ schema: 'x' }`
+    // selects the schema together with everything in it.
+    const schema = id.kind === 'schema' ? id.name : id.schema;
+    return (matchField(id.kind, selector.kind) &&
+        matchField(schema, selector.schema) &&
+        matchField(id.name, selector.name) &&
+        matchField(id.table, selector.table));
+}
+/** Path of the residual unit for statements attributable to no object. */
+exports.RESIDUAL_UNIT_PATH = 'misc/statements';
+/**
+ * Group a classified script into identity-keyed units and compute unit-level
+ * dependencies from the statement graph.
+ *
+ * Statements with no identity of their own (grants, comments) ride with the
+ * unit of the object they target — resolved through the statement graph's
+ * edges — falling back to the closest preceding statement's unit; lead-in
+ * statements with no unit at all land in a residual unit so nothing is
+ * silently dropped. Kinds listed in `splitRiders` become standalone units
+ * (named `<hostPath>/grants/<role>` for grants, `<hostPath>/<kind>/<n>`
+ * otherwise) that depend on their host unit.
+ */
+function buildUnitGraph(sql, style, splitRiders) {
+    const facts = (0, transform_1.classifyStatements)(sql);
+    const graph = (0, transform_1.buildStatementGraph)(facts);
+    const unitOf = new Array(facts.length).fill(-1);
+    const units = [];
+    const byIdentity = new Map();
+    const takenPaths = new Set();
+    const newUnit = (identity, primaryKind, path) => {
+        units.push({ identity, primaryKind, path, statements: [], sql: '', dynamicSql: false });
+        takenPaths.add(path);
+        return units.length - 1;
+    };
+    // Naming-spec path for a unit; ENABLE ROW LEVEL SECURITY uses the spec's
+    // dedicated rls template rather than its constraint-shaped identity.
+    const unitPath = (identity, kind) => {
+        if (kind === 'rls_enable' && identity.table) {
+            return `schemas/${identity.schema ?? 'public'}/tables/${identity.table}/policies/enable_row_level_security`;
+        }
+        return (0, naming_spec_1.pathFor)(identity, { style });
+    };
+    const unitFor = (identity, kind) => {
+        const key = identity ? identityKey(identity) : exports.RESIDUAL_UNIT_PATH;
+        let u = byIdentity.get(key);
+        if (u === undefined) {
+            u = newUnit(identity, kind, identity ? unitPath(identity, kind) : exports.RESIDUAL_UNIT_PATH);
+            byIdentity.set(key, u);
+        }
+        return u;
+    };
+    // Object-owning units by qualified name, for rider host resolution. Only
+    // top-level objects qualify (table-scoped identities share the table's
+    // qualified name and must not shadow it).
+    const objectUnits = new Map();
+    const registerObject = (identity, u) => {
+        if (identity.table)
+            return;
+        objectUnits.set(`${identity.schema ?? ''}.${identity.name}`, u);
+    };
+    /** Host unit of a rider statement: the unit owning the first object it
+     *  references, falling back to the preceding statement's unit. */
+    const hostOf = (i) => {
+        for (const r of facts[i].references) {
+            const u = objectUnits.get(`${r.schema ?? ''}.${r.name}`);
+            if (u !== undefined)
+                return u;
+        }
+        if (i > 0 && unitOf[i - 1] !== -1)
+            return unitOf[i - 1];
+        return -1;
+    };
+    const riderPath = (f, host) => {
+        const base = host !== -1 ? units[host].path : exports.RESIDUAL_UNIT_PATH;
+        const dir = f.kind === 'grant' ? 'grants' : f.kind;
+        const label = f.roles.length > 0 ? f.roles.join('_') : f.kind;
+        let path = `${base}/${dir}/${label}`;
+        for (let n = 2; takenPaths.has(path); n++)
+            path = `${base}/${dir}/${label}-${n}`;
+        return path;
+    };
+    const hostUnit = new Map();
+    facts.forEach((f, i) => {
+        const identity = (0, transform_1.identityOf)(f);
+        if (identity && !splitRiders.has(f.kind)) {
+            unitOf[i] = unitFor(identity, f.kind);
+            registerObject(identity, unitOf[i]);
+            return;
+        }
+        const host = hostOf(i);
+        if (splitRiders.has(f.kind)) {
+            unitOf[i] = newUnit(identity, f.kind, identity ? unitPath(identity, f.kind) : riderPath(f, host));
+            if (identity)
+                registerObject(identity, unitOf[i]);
+            if (host !== -1)
+                hostUnit.set(unitOf[i], host);
+            return;
+        }
+        // No identity: ride with the host unit.
+        if (host !== -1) {
+            unitOf[i] = host;
+            return;
+        }
+        unitOf[i] = unitFor(null, f.kind);
+    });
+    facts.forEach((f, i) => {
+        const text = sql.slice(f.span.start, f.span.start + f.span.len).trim();
+        if (!text)
+            return;
+        const unit = units[unitOf[i]];
+        unit.statements.push(i);
+        unit.sql += (unit.sql ? '\n\n' : '') + (text.endsWith(';') ? text : `${text};`);
+        if (f.dynamicSql)
+            unit.dynamicSql = true;
+    });
+    // Unit dependencies: statement edges (late edges do not constrain deploy
+    // order), plus schema membership (an object requires its schema's unit).
+    const deps = units.map(() => new Set());
+    for (const edge of graph.edges) {
+        if (edge.kind === 'late')
+            continue;
+        const from = unitOf[edge.from];
+        const to = unitOf[edge.to];
+        if (from !== -1 && to !== -1 && from !== to)
+            deps[from].add(to);
+    }
+    // A split rider requires its host object; a table-scoped object (trigger,
+    // policy, index, constraint, RLS) requires its table.
+    for (const [u, host] of hostUnit) {
+        if (u !== host)
+            deps[u].add(host);
+    }
+    units.forEach((u, i) => {
+        const id = u.identity;
+        if (!id?.table)
+            return;
+        const table = objectUnits.get(`${id.schema ?? ''}.${id.table}`);
+        if (table !== undefined && table !== i)
+            deps[i].add(table);
+    });
+    const schemaUnit = new Map();
+    units.forEach((u, i) => {
+        if (u.identity?.kind === 'schema')
+            schemaUnit.set(u.identity.name, i);
+    });
+    facts.forEach((f, i) => {
+        const from = unitOf[i];
+        if (from === -1)
+            return;
+        const schemas = new Set(f.referencedSchemas);
+        for (const created of f.creates) {
+            if (created.schema)
+                schemas.add(created.schema);
+        }
+        for (const schema of schemas) {
+            const to = schemaUnit.get(schema);
+            if (to !== undefined && to !== from)
+                deps[from].add(to);
+        }
+    });
+    return { facts, units, unitOf, deps, source: sql };
+}
+/**
+ * Partition a deploy surface into packages.
+ *
+ * Accepts either raw SQL or pgpm changes (whose deploy scripts are flattened
+ * in the given order — run the granularity dial first if a different unit
+ * shape is wanted). Requires `loadModule()` from `plpgsql-parser` first.
+ *
+ * Assignment: for each unit the first matching rule wins; unmatched units go
+ * to `defaultPackage`. Closure rules then pull the transitive dependency
+ * closure (hard + fk) of their units out of the default package. Finally the
+ * requires post-pass renders every unit dependency through the naming spec —
+ * same package as `<path>`, cross-package as `<pkg>:<path>` — and the
+ * package-level graph is checked for cycles ({@link PartitionCycleError}).
+ */
+function partitionUnits(input, config) {
+    const style = config.style ?? 'directory';
+    const sql = typeof input === 'string'
+        ? input
+        : input.map(c => c.deploy.trim()).filter(Boolean).join('\n\n');
+    const { units, deps } = buildUnitGraph(sql, style, new Set(config.splitRiders ?? []));
+    const warnings = [];
+    // 1. Assignment: first matching rule wins.
+    const packageOf = units.map(unit => {
+        for (const rule of config.rules) {
+            if (rule.select.some(s => matches(unit, s)))
+                return rule.package;
+        }
+        return config.defaultPackage;
+    });
+    // 2. Closure: pull each closure rule's dependency closure out of the
+    // default package (never out of another rule's package).
+    const closureIncluded = new Map();
+    for (const rule of config.rules) {
+        if (!rule.closure)
+            continue;
+        const queue = units.map((_, i) => i).filter(i => packageOf[i] === rule.package);
+        const seen = new Set(queue);
+        while (queue.length > 0) {
+            const current = queue.shift();
+            for (const dep of deps[current]) {
+                if (seen.has(dep))
+                    continue;
+                seen.add(dep);
+                if (packageOf[dep] === rule.package) {
+                    queue.push(dep);
+                    continue;
+                }
+                if (packageOf[dep] !== config.defaultPackage)
+                    continue;
+                packageOf[dep] = rule.package;
+                closureIncluded.set(units[dep].path, rule.package);
+                queue.push(dep);
+            }
+        }
+    }
+    // Dynamic SQL makes edges incomplete: surface it, do not guess.
+    units.forEach((unit, i) => {
+        if (unit.dynamicSql && unit.statements.length > 0) {
+            warnings.push(`${units[i].path} (${packageOf[i]}) executes dynamic SQL; hidden references cannot be checked against the partition`);
+        }
+    });
+    // 3. Requires post-pass + package-level graph.
+    const pkgNames = [...new Set([...packageOf, config.defaultPackage])];
+    const pkgIndex = new Map(pkgNames.map((p, i) => [p, i]));
+    const pkgEdges = new Map();
+    const changesByPkg = new Map();
+    for (const p of pkgNames)
+        changesByPkg.set(p, []);
+    units.forEach((unit, i) => {
+        if (unit.statements.length === 0)
+            return;
+        const pkg = packageOf[i];
+        const dependencies = [...deps[i]]
+            .filter(d => units[d].statements.length > 0)
+            .map(d => {
+            const depPkg = packageOf[d];
+            if (depPkg === pkg)
+                return units[d].path;
+            const key = `${pkg}\u0000${depPkg}`;
+            if (!pkgEdges.has(key)) {
+                pkgEdges.set(key, {
+                    from: pkgIndex.get(pkg),
+                    to: pkgIndex.get(depPkg),
+                    via: `${pkg}:${unit.path} -> ${depPkg}:${units[d].path}`
+                });
+            }
+            return `${depPkg}:${units[d].path}`;
+        })
+            .sort();
+        changesByPkg.get(pkg).push({ name: unit.path, dependencies, deploy: unit.sql });
+    });
+    // 4. Cross-package cycle detection over the package graph.
+    detectCycles(pkgNames, [...pkgEdges.values()]);
+    const assignments = new Map();
+    units.forEach((unit, i) => {
+        if (unit.statements.length > 0)
+            assignments.set(unit.path, packageOf[i]);
+    });
+    const packages = pkgNames
+        .map(name => ({
+        name,
+        changes: changesByPkg.get(name),
+        requires: [...new Set([...pkgEdges.values()]
+                .filter(e => pkgNames[e.from] === name)
+                .map(e => pkgNames[e.to]))].sort()
+    }))
+        .filter(p => p.changes.length > 0);
+    return { packages, assignments, closureIncluded, warnings };
+}
+function detectCycles(pkgNames, edges) {
+    const out = new Map();
+    for (const e of edges) {
+        const list = out.get(e.from) ?? [];
+        list.push({ to: e.to, via: e.via });
+        out.set(e.from, list);
+    }
+    const state = new Array(pkgNames.length).fill(0); // 0 unseen, 1 on stack, 2 done
+    const stack = [];
+    const viaStack = [];
+    const visit = (v) => {
+        state[v] = 1;
+        stack.push(v);
+        for (const { to, via } of out.get(v) ?? []) {
+            if (state[to] === 2)
+                continue;
+            viaStack.push(via);
+            if (state[to] === 1) {
+                const start = stack.indexOf(to);
+                const cyclePkgs = stack.slice(start).map(i => pkgNames[i]);
+                const cycleEdges = viaStack.slice(viaStack.length - cyclePkgs.length);
+                throw new PartitionCycleError(cyclePkgs, cycleEdges);
+            }
+            visit(to);
+            viaStack.pop();
+        }
+        stack.pop();
+        state[v] = 2;
+    };
+    for (let v = 0; v < pkgNames.length; v++) {
+        if (state[v] === 0)
+            visit(v);
+    }
+}