@pgpmjs/transform 0.20.0 → 0.22.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/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/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,6 +1,7 @@
 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);

package/esm/index.js

@@ -11,7 +11,7 @@ export { PartitionCycleError, partitionUnits, RESIDUAL_UNIT_PATH, } from './part
 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 { coverChanges, diffChangeSets, diffSchemas, } from './semantic-diff-driver';
 export { nameUnnamedConstraints, subObjectIdentityOf } from './sub-object';
 export * from '@pgsql/transform';
 export { loadModule } from 'plpgsql-parser';

package/esm/module-source.js

@@ -1,10 +1,4 @@
-/**
- * Module ingestion for the dials pipeline: load an on-disk pgpm module into
- * the flattened, classified change list the transform/partition drivers
- * consume. `pgpm transform` uses this today; a future `pgpm import` (dumps)
- * and `pgpm diff` are expected to reuse the same seam.
- */
-import { parsePgpmHeader, parsePlanFile, readScript } from '@pgpmjs/ast';
+import { parsePgpmHeader, parsePlanFile, readScript, resolveReference } from '@pgpmjs/ast';
 import * as path from 'path';
 const TX_LINE = /^\s*(BEGIN|COMMIT|ROLLBACK)\s*;\s*$/i;
 /**
@@ -17,6 +11,31 @@ export const stripTransactionWrapper = (sql) => sql
     .filter(line => !TX_LINE.test(line))
     .join('\n')
     .trim();
+/**
+ * Resolve a plan dependency token to a concrete change name.
+ *
+ * Non-tag tokens (a bare change name, or a `pkg:change` cross-package name)
+ * pass through unchanged — they are already the identity the ledger and
+ * generated plans record. A tag token (`@tag`) is resolved to its change via
+ * the plan that defines it, so a dependency written against a tag is not
+ * re-emitted verbatim into a generated plan or a ledger row. Cross-package
+ * tags (`pkg:@tag`) cannot be resolved from a single module's plan and are
+ * left as-is with a warning; the resolver returns them unchanged. Anything
+ * that fails to resolve is kept verbatim (never dropped) with a warning.
+ */
+const resolveDependencyToken = (token, plan, warnings, changeName) => {
+    if (!token.includes('@'))
+        return token;
+    const resolved = resolveReference(token, plan, plan.package);
+    if (resolved.error || !resolved.change) {
+        warnings.push(`${changeName}: could not resolve dependency tag "${token}" (${resolved.error ?? 'no matching change'}); left as-is`);
+        return token;
+    }
+    if (resolved.change === token) {
+        warnings.push(`${changeName}: dependency tag "${token}" is cross-package; left unresolved (resolve it in workspace context)`);
+    }
+    return resolved.change;
+};
 /**
  * Load a pgpm module from disk: parse pgpm.plan and read each change's
  * deploy script, stripping pgpm headers and transaction wrappers so the
@@ -30,9 +49,10 @@ export const loadModuleSource = (moduleDir) => {
         const reasons = planResult.errors.map(e => e.message).join(', ');
         throw new Error(`Failed to parse pgpm.plan in ${modulePath}: ${reasons}`);
     }
+    const plan = planResult.data;
     const warnings = [];
     const changes = [];
-    for (const change of planResult.data.changes) {
+    for (const change of plan.changes) {
         const raw = readScript(modulePath, 'deploy', change.name);
         if (!raw) {
             warnings.push(`${change.name}: no deploy script found, skipping`);
@@ -41,7 +61,7 @@ export const loadModuleSource = (moduleDir) => {
         const { body } = parsePgpmHeader(raw);
         changes.push({
             name: change.name,
-            dependencies: change.dependencies ?? [],
+            dependencies: (change.dependencies ?? []).map(dep => resolveDependencyToken(dep, plan, warnings, change.name)),
             deploy: stripTransactionWrapper(body)
         });
     }

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

@@ -28,7 +28,8 @@
  */
 import { pathFor } from '@pgpmjs/naming-spec';
 import { existenceCheck, invertStatement, revertFor, verifyFor } from '@pgsql/scripts';
-import { buildStatementGraph, classifyStatements, cleanTree, identityOf } from '@pgsql/transform';
+import { classifyStatements } from '@pgsql/semantics';
+import { buildStatementGraph, cleanTree, identityOf } from '@pgsql/transform';
 import { Deparser, parseSync } from 'plpgsql-parser';
 import { defaultConstraintName } from './constraint-names';
 import { restructureChanges } from './granularity-driver';
@@ -501,3 +502,38 @@ export function diffChangeSets(from, to, options = {}) {
     const flatten = (changes) => changes.map(c => c.deploy.trim()).filter(Boolean).join('\n\n');
     return diffSchemas(flatten(from), flatten(to), options);
 }
+/**
+ * Cover each `to`-side change against a semantic diff's per-object delta:
+ * which of the objects the change touches are already present and identical
+ * on the `from` side. A `satisfied` change deploys nothing new — its ledger
+ * entry can be backfilled instead of executing it; an `unsatisfied` change is
+ * the genuine delta. Identity keying is shared with the diff itself, so
+ * regrouped/renamed/reordered authorship of the same objects covers the same.
+ *
+ * `diff` must come from diffing the same `from` side against these changes
+ * (`diffChangeSets(fromChanges, toChanges)`).
+ */
+export function coverChanges(changes, diff, options = {}) {
+    const style = options.style ?? 'directory';
+    const deltaByKey = new Map();
+    for (const obj of diff.objects) {
+        deltaByKey.set(identityKey(obj.identity), obj.delta);
+    }
+    return changes.map(change => {
+        const sideWarnings = [];
+        const side = readSide(change.deploy, sideWarnings, change.name);
+        const objects = side.order.map(key => {
+            const unit = side.units.get(key);
+            return {
+                path: pathFor(unit.identity, { style }),
+                delta: deltaByKey.get(key) ?? 'unchanged'
+            };
+        });
+        const touched = objects.filter(o => o.delta !== 'unchanged').length;
+        const status = objects.length === 0 ? 'inert'
+            : touched === 0 ? 'satisfied'
+                : touched === objects.length ? 'unsatisfied'
+                    : 'partial';
+        return { name: change.name, status, objects };
+    });
+}

package/fixture-closure.d.ts

@@ -1,4 +1,4 @@
-import { QualifiedName } from '@pgsql/transform';
+import { QualifiedName } from '@pgsql/semantics';
 import { CategoryProfile, ChangeCategory } from './categorize';
 /**
  * A change plus its deploy SQL. Optional plan `dependencies` (from `pgpm.plan`)

package/fixture-closure.js

@@ -1,13 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveFixtureClosure = resolveFixtureClosure;
-const transform_1 = require("@pgsql/transform");
+const semantics_1 = require("@pgsql/semantics");
 const categorize_1 = require("./categorize");
 function objectKey(schema, name) {
     return `${schema ?? ''}\u0000${name}`;
 }
 function analyze(change, profile) {
-    const facts = (0, transform_1.classifyStatements)(change.sql);
+    const facts = (0, semantics_1.classifyStatements)(change.sql);
     const category = profile.categorize(facts, change.name);
     const creates = [];
     const createsSchemas = [];

package/granularity-driver.d.ts

@@ -18,7 +18,8 @@
  * - `consolidated` — additionally inlines FKs proven safe by the graph.
  */
 import type { ObjectIdentity as NamingIdentity } from '@pgpmjs/naming-spec';
-import type { Granularity, StatementFacts } from '@pgsql/transform';
+import type { StatementFacts } from '@pgsql/semantics';
+import type { Granularity } from '@pgsql/transform';
 export type { Granularity } from '@pgsql/transform';
 /**
  * How statements are distributed across pgpm changes — orthogonal to

package/granularity-driver.js

@@ -5,6 +5,7 @@ exports.defaultChangeName = defaultChangeName;
 exports.restructureChanges = restructureChanges;
 const naming_spec_1 = require("@pgpmjs/naming-spec");
 const scripts_1 = require("@pgsql/scripts");
+const semantics_1 = require("@pgsql/semantics");
 const transform_1 = require("@pgsql/transform");
 const sub_object_1 = require("./sub-object");
 exports.CHANGE_GRANULARITIES = ['alteration', 'object', 'single'];
@@ -57,7 +58,7 @@ function restructureChanges(changes, options) {
     // 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 = (0, transform_1.classifyStatements)(sql);
+    const facts = (0, semantics_1.classifyStatements)(sql);
     if (options.changeGranularity === 'single') {
         const name = options.singleChangeName ?? 'module/init';
         const inputNames = new Set(changes.map(c => c.name));

package/index.d.ts

@@ -24,8 +24,8 @@ export type { GeneratedScript, RegeneratedScripts, } from './regen';
 export { classifyScript, isStubScript, regenerateScripts, } from './regen';
 export type { ExportGranularity, RestructureExportRowsOptions, RestructureExportRowsResult } from './restructure';
 export { EXPORT_GRANULARITIES, isExportGranularity, restructureExportRows } from './restructure';
-export type { DiffInputChange, ObjectDelta, SemanticDeltaChange, SemanticDiffOptions, SemanticDiffResult, SemanticObjectDiff, } from './semantic-diff-driver';
-export { diffChangeSets, diffSchemas, } from './semantic-diff-driver';
+export type { ChangeCoverage, ChangeObjectCoverage, ChangeObjectDelta, ChangeSatisfaction, DiffInputChange, ObjectDelta, SemanticDeltaChange, SemanticDiffOptions, SemanticDiffResult, SemanticObjectDiff, } from './semantic-diff-driver';
+export { coverChanges, diffChangeSets, diffSchemas, } from './semantic-diff-driver';
 export { nameUnnamedConstraints, subObjectIdentityOf } from './sub-object';
 export * from '@pgsql/transform';
 export { loadModule } from 'plpgsql-parser';

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.loadModule = exports.subObjectIdentityOf = exports.nameUnnamedConstraints = exports.diffSchemas = exports.diffChangeSets = exports.restructureExportRows = exports.isExportGranularity = exports.EXPORT_GRANULARITIES = exports.regenerateScripts = exports.isStubScript = exports.classifyScript = exports.parseSqlProgram = exports.emitSqlProgram = exports.RESIDUAL_UNIT_PATH = exports.partitionUnits = exports.PartitionCycleError = exports.partitionExportRows = exports.parsePartitionConfig = exports.stripTransactionWrapper = exports.loadModuleSource = exports.writeModule = exports.writeControlFile = exports.checkOverwrite = exports.appendModule = exports.restructureChanges = exports.isChangeGranularity = exports.defaultChangeName = exports.CHANGE_GRANULARITIES = exports.resolveFixtureClosure = exports.firstColumnRef = exports.defaultConstraintName = exports.TIER_PROFILE = exports.categorizeChange = exports.buildCategoryOf = exports.withoutColumnOrder = exports.snapshotCatalog = exports.diffCatalogSnapshots = exports.makeSchemaTranspiler = exports.makeNamespaceValidator = exports.buildSchemaRouter = exports.buildExtensionRouter = void 0;
+exports.loadModule = exports.subObjectIdentityOf = exports.nameUnnamedConstraints = exports.diffSchemas = exports.diffChangeSets = exports.coverChanges = exports.restructureExportRows = exports.isExportGranularity = exports.EXPORT_GRANULARITIES = exports.regenerateScripts = exports.isStubScript = exports.classifyScript = exports.parseSqlProgram = exports.emitSqlProgram = exports.RESIDUAL_UNIT_PATH = exports.partitionUnits = exports.PartitionCycleError = exports.partitionExportRows = exports.parsePartitionConfig = exports.stripTransactionWrapper = exports.loadModuleSource = exports.writeModule = exports.writeControlFile = exports.checkOverwrite = exports.appendModule = exports.restructureChanges = exports.isChangeGranularity = exports.defaultChangeName = exports.CHANGE_GRANULARITIES = exports.resolveFixtureClosure = exports.firstColumnRef = exports.defaultConstraintName = exports.TIER_PROFILE = exports.categorizeChange = exports.buildCategoryOf = exports.withoutColumnOrder = exports.snapshotCatalog = exports.diffCatalogSnapshots = exports.makeSchemaTranspiler = exports.makeNamespaceValidator = exports.buildSchemaRouter = exports.buildExtensionRouter = void 0;
 var bundle_driver_1 = require("./bundle-driver");
 Object.defineProperty(exports, "buildExtensionRouter", { enumerable: true, get: function () { return bundle_driver_1.buildExtensionRouter; } });
 Object.defineProperty(exports, "buildSchemaRouter", { enumerable: true, get: function () { return bundle_driver_1.buildSchemaRouter; } });
@@ -65,6 +65,7 @@ Object.defineProperty(exports, "EXPORT_GRANULARITIES", { enumerable: true, get:
 Object.defineProperty(exports, "isExportGranularity", { enumerable: true, get: function () { return restructure_1.isExportGranularity; } });
 Object.defineProperty(exports, "restructureExportRows", { enumerable: true, get: function () { return restructure_1.restructureExportRows; } });
 var semantic_diff_driver_1 = require("./semantic-diff-driver");
+Object.defineProperty(exports, "coverChanges", { enumerable: true, get: function () { return semantic_diff_driver_1.coverChanges; } });
 Object.defineProperty(exports, "diffChangeSets", { enumerable: true, get: function () { return semantic_diff_driver_1.diffChangeSets; } });
 Object.defineProperty(exports, "diffSchemas", { enumerable: true, get: function () { return semantic_diff_driver_1.diffSchemas; } });
 var sub_object_1 = require("./sub-object");

package/module-source.js

@@ -34,12 +34,6 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadModuleSource = exports.stripTransactionWrapper = void 0;
-/**
- * Module ingestion for the dials pipeline: load an on-disk pgpm module into
- * the flattened, classified change list the transform/partition drivers
- * consume. `pgpm transform` uses this today; a future `pgpm import` (dumps)
- * and `pgpm diff` are expected to reuse the same seam.
- */
 const ast_1 = require("@pgpmjs/ast");
 const path = __importStar(require("path"));
 const TX_LINE = /^\s*(BEGIN|COMMIT|ROLLBACK)\s*;\s*$/i;
@@ -54,6 +48,31 @@ const stripTransactionWrapper = (sql) => sql
     .join('\n')
     .trim();
 exports.stripTransactionWrapper = stripTransactionWrapper;
+/**
+ * Resolve a plan dependency token to a concrete change name.
+ *
+ * Non-tag tokens (a bare change name, or a `pkg:change` cross-package name)
+ * pass through unchanged — they are already the identity the ledger and
+ * generated plans record. A tag token (`@tag`) is resolved to its change via
+ * the plan that defines it, so a dependency written against a tag is not
+ * re-emitted verbatim into a generated plan or a ledger row. Cross-package
+ * tags (`pkg:@tag`) cannot be resolved from a single module's plan and are
+ * left as-is with a warning; the resolver returns them unchanged. Anything
+ * that fails to resolve is kept verbatim (never dropped) with a warning.
+ */
+const resolveDependencyToken = (token, plan, warnings, changeName) => {
+    if (!token.includes('@'))
+        return token;
+    const resolved = (0, ast_1.resolveReference)(token, plan, plan.package);
+    if (resolved.error || !resolved.change) {
+        warnings.push(`${changeName}: could not resolve dependency tag "${token}" (${resolved.error ?? 'no matching change'}); left as-is`);
+        return token;
+    }
+    if (resolved.change === token) {
+        warnings.push(`${changeName}: dependency tag "${token}" is cross-package; left unresolved (resolve it in workspace context)`);
+    }
+    return resolved.change;
+};
 /**
  * Load a pgpm module from disk: parse pgpm.plan and read each change's
  * deploy script, stripping pgpm headers and transaction wrappers so the
@@ -67,9 +86,10 @@ const loadModuleSource = (moduleDir) => {
         const reasons = planResult.errors.map(e => e.message).join(', ');
         throw new Error(`Failed to parse pgpm.plan in ${modulePath}: ${reasons}`);
     }
+    const plan = planResult.data;
     const warnings = [];
     const changes = [];
-    for (const change of planResult.data.changes) {
+    for (const change of plan.changes) {
         const raw = (0, ast_1.readScript)(modulePath, 'deploy', change.name);
         if (!raw) {
             warnings.push(`${change.name}: no deploy script found, skipping`);
@@ -78,7 +98,7 @@ const loadModuleSource = (moduleDir) => {
         const { body } = (0, ast_1.parsePgpmHeader)(raw);
         changes.push({
             name: change.name,
-            dependencies: change.dependencies ?? [],
+            dependencies: (change.dependencies ?? []).map(dep => resolveDependencyToken(dep, plan, warnings, change.name)),
             deploy: (0, exports.stripTransactionWrapper)(body)
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgpmjs/transform",
-  "version": "0.20.0",
+  "version": "0.22.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",
@@ -39,15 +39,16 @@
     "plpgsql"
   ],
   "devDependencies": {
-    "@pgpmjs/bundle": "^0.13.3",
+    "@pgpmjs/bundle": "^0.14.1",
     "makage": "^0.3.0"
   },
   "dependencies": {
-    "@pgpmjs/ast": "^0.10.3",
-    "@pgpmjs/naming-spec": "^0.2.0",
-    "@pgsql/scripts": "^18.3.1",
-    "@pgsql/transform": "^18.14.1",
-    "plpgsql-parser": "^18.5.1"
+    "@pgpmjs/ast": "^0.11.1",
+    "@pgpmjs/naming-spec": "^0.3.0",
+    "@pgsql/scripts": "^18.3.4",
+    "@pgsql/semantics": "^18.1.2",
+    "@pgsql/transform": "^18.15.2",
+    "plpgsql-parser": "^18.5.3"
   },
-  "gitHead": "e6a7a57f88c9deb2a4acecaba2451320d1be8203"
+  "gitHead": "6da0705f8aa49d62dc2defb8b135b71674611483"
 }

package/partition-driver.d.ts

@@ -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 { PathStyle } from '@pgpmjs/naming-spec';
-import { ObjectIdentity, ObjectIdentityKind, StatementKind } from '@pgsql/transform';
+import { StatementKind } from '@pgsql/semantics';
+import { ObjectIdentity, ObjectIdentityKind } 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. */

package/partition-driver.js

@@ -5,7 +5,7 @@ exports.partitionUnits = partitionUnits;
 /**
  * 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
@@ -25,6 +25,7 @@ exports.partitionUnits = partitionUnits;
  * pgpm.plan + deploy trees, feed a bundle, ...).
  */
 const naming_spec_1 = require("@pgpmjs/naming-spec");
+const semantics_1 = require("@pgsql/semantics");
 const transform_1 = require("@pgsql/transform");
 /** A partition whose packages require each other in a cycle — unshippable. */
 class PartitionCycleError extends Error {
@@ -84,7 +85,7 @@ exports.RESIDUAL_UNIT_PATH = 'misc/statements';
  * otherwise) that depend on their host unit.
  */
 function buildUnitGraph(sql, style, splitRiders) {
-    const facts = (0, transform_1.classifyStatements)(sql);
+    const facts = (0, semantics_1.classifyStatements)(sql);
     const graph = (0, transform_1.buildStatementGraph)(facts);
     const unitOf = new Array(facts.length).fill(-1);
     const units = [];

package/program.d.ts

@@ -9,7 +9,7 @@
  * untouched statements). A program with no dirty statements emits its source
  * byte-identically, so content-addressed hashes are preserved.
  */
-import type { StatementFacts } from '@pgsql/transform';
+import type { StatementFacts } from '@pgsql/semantics';
 /** A statement's location in the source script (byte offsets). */
 export type SqlStatementSpan = StatementFacts['span'];
 /** One statement of a parsed SQL script. */

package/program.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseSqlProgram = parseSqlProgram;
 exports.emitSqlProgram = emitSqlProgram;
-const transform_1 = require("@pgsql/transform");
+const semantics_1 = require("@pgsql/semantics");
 const plpgsql_parser_1 = require("plpgsql-parser");
 /**
  * Parse a SQL script into a statement program. Requires `loadModule()` from
@@ -11,7 +11,7 @@ const plpgsql_parser_1 = require("plpgsql-parser");
 function parseSqlProgram(source) {
     const parseResult = (0, plpgsql_parser_1.parseSql)(source);
     const stmts = parseResult?.stmts ?? [];
-    const facts = (0, transform_1.classifyStatements)(source);
+    const facts = (0, semantics_1.classifyStatements)(source);
     const statements = [];
     for (let i = 0; i < stmts.length; i++) {
         const rawStmt = stmts[i];

package/regen.d.ts

@@ -12,7 +12,7 @@
  * Requires `loadModule()` from `plpgsql-parser` to have completed.
  */
 import type { GeneratedScript } from '@pgsql/scripts';
-import type { StatementFacts } from '@pgsql/transform';
+import type { StatementFacts } from '@pgsql/semantics';
 export type { GeneratedScript } from '@pgsql/scripts';
 /** Generated revert and verify scripts for one change's deploy SQL. */
 export interface RegeneratedScripts {

package/regen.js

@@ -4,13 +4,13 @@ exports.classifyScript = classifyScript;
 exports.isStubScript = isStubScript;
 exports.regenerateScripts = regenerateScripts;
 const scripts_1 = require("@pgsql/scripts");
-const transform_1 = require("@pgsql/transform");
+const semantics_1 = require("@pgsql/semantics");
 /**
  * Classify a pgpm script's substantive statements: every top-level statement
  * except transaction control (`BEGIN`/`COMMIT`/`ROLLBACK` wrappers).
  */
 function classifyScript(sql) {
-    return (0, transform_1.classifyStatements)(sql).filter(f => f.nodeTag !== 'TransactionStmt');
+    return (0, semantics_1.classifyStatements)(sql).filter(f => f.nodeTag !== 'TransactionStmt');
 }
 /**
  * Whether a script is an empty stub: nothing but comments, whitespace, and

package/semantic-diff-driver.d.ts

@@ -90,3 +90,38 @@ export interface DiffInputChange {
  * schema yields an identical diff.
  */
 export declare function diffChangeSets(from: DiffInputChange[], to: DiffInputChange[], options?: SemanticDiffOptions): SemanticDiffResult;
+/** How one object a change touches relates to the diff's delta. */
+export type ChangeObjectDelta = ObjectDelta | 'unchanged';
+/**
+ * Whether a `to`-side change is already satisfied by the `from` side:
+ * - `satisfied`: every object it touches is unchanged in the diff
+ * - `unsatisfied`: every object it touches is added/modified in the diff
+ * - `partial`: a mix of unchanged and delta objects
+ * - `inert`: no identifiable objects (seed data, grants-only, dynamic SQL)
+ */
+export type ChangeSatisfaction = 'satisfied' | 'unsatisfied' | 'partial' | 'inert';
+export interface ChangeObjectCoverage {
+    /** Canonical naming-spec path for the object. */
+    path: string;
+    delta: ChangeObjectDelta;
+}
+export interface ChangeCoverage {
+    /** The input change's name (as given, e.g. `pkg:change`). */
+    name: string;
+    status: ChangeSatisfaction;
+    objects: ChangeObjectCoverage[];
+}
+/**
+ * Cover each `to`-side change against a semantic diff's per-object delta:
+ * which of the objects the change touches are already present and identical
+ * on the `from` side. A `satisfied` change deploys nothing new — its ledger
+ * entry can be backfilled instead of executing it; an `unsatisfied` change is
+ * the genuine delta. Identity keying is shared with the diff itself, so
+ * regrouped/renamed/reordered authorship of the same objects covers the same.
+ *
+ * `diff` must come from diffing the same `from` side against these changes
+ * (`diffChangeSets(fromChanges, toChanges)`).
+ */
+export declare function coverChanges(changes: DiffInputChange[], diff: SemanticDiffResult, options?: {
+    style?: PathStyle;
+}): ChangeCoverage[];

package/semantic-diff-driver.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.diffSchemas = diffSchemas;
 exports.diffChangeSets = diffChangeSets;
+exports.coverChanges = coverChanges;
 /**
  * Semantic diff driver: identity-keyed schema delta between two deploy
  * surfaces.
@@ -32,6 +33,7 @@ exports.diffChangeSets = diffChangeSets;
  */
 const naming_spec_1 = require("@pgpmjs/naming-spec");
 const scripts_1 = require("@pgsql/scripts");
+const semantics_1 = require("@pgsql/semantics");
 const transform_1 = require("@pgsql/transform");
 const plpgsql_parser_1 = require("plpgsql-parser");
 const constraint_names_1 = require("./constraint-names");
@@ -44,7 +46,7 @@ const identityKey = (id) => `${id.kind}\u0000${id.schema ?? ''}\u0000${id.table
  * statements are reported via `warnings`.
  */
 function readSide(sql, warnings, label) {
-    const facts = (0, transform_1.classifyStatements)(sql);
+    const facts = (0, semantics_1.classifyStatements)(sql);
     const graph = (0, transform_1.buildStatementGraph)(facts);
     const units = new Map();
     const order = [];
@@ -367,7 +369,7 @@ function diffSchemas(from, to, options = {}) {
      * statement to surface its not-derivable comment and warning.
      */
     const inverseOf = (deploy, context) => {
-        const facts = (0, transform_1.classifyStatements)(deploy);
+        const facts = (0, semantics_1.classifyStatements)(deploy);
         const graph = (0, transform_1.buildStatementGraph)(facts);
         const pieces = [];
         for (const i of [...graph.order].reverse()) {
@@ -390,7 +392,7 @@ function diffSchemas(from, to, options = {}) {
      */
     const verifyOf = (deploy, context) => {
         const pieces = [];
-        for (const fact of (0, transform_1.classifyStatements)(deploy)) {
+        for (const fact of (0, semantics_1.classifyStatements)(deploy)) {
             const nodes = (0, scripts_1.existenceCheck)(fact);
             if (nodes === null) {
                 const { warnings: w } = (0, scripts_1.verifyFor)([fact]);
@@ -505,3 +507,38 @@ function diffChangeSets(from, to, options = {}) {
     const flatten = (changes) => changes.map(c => c.deploy.trim()).filter(Boolean).join('\n\n');
     return diffSchemas(flatten(from), flatten(to), options);
 }
+/**
+ * Cover each `to`-side change against a semantic diff's per-object delta:
+ * which of the objects the change touches are already present and identical
+ * on the `from` side. A `satisfied` change deploys nothing new — its ledger
+ * entry can be backfilled instead of executing it; an `unsatisfied` change is
+ * the genuine delta. Identity keying is shared with the diff itself, so
+ * regrouped/renamed/reordered authorship of the same objects covers the same.
+ *
+ * `diff` must come from diffing the same `from` side against these changes
+ * (`diffChangeSets(fromChanges, toChanges)`).
+ */
+function coverChanges(changes, diff, options = {}) {
+    const style = options.style ?? 'directory';
+    const deltaByKey = new Map();
+    for (const obj of diff.objects) {
+        deltaByKey.set(identityKey(obj.identity), obj.delta);
+    }
+    return changes.map(change => {
+        const sideWarnings = [];
+        const side = readSide(change.deploy, sideWarnings, change.name);
+        const objects = side.order.map(key => {
+            const unit = side.units.get(key);
+            return {
+                path: (0, naming_spec_1.pathFor)(unit.identity, { style }),
+                delta: deltaByKey.get(key) ?? 'unchanged'
+            };
+        });
+        const touched = objects.filter(o => o.delta !== 'unchanged').length;
+        const status = objects.length === 0 ? 'inert'
+            : touched === 0 ? 'satisfied'
+                : touched === objects.length ? 'unsatisfied'
+                    : 'partial';
+        return { name: change.name, status, objects };
+    });
+}

package/sub-object.d.ts

@@ -10,7 +10,7 @@
  * every alteration.
  */
 import type { ObjectIdentity } from '@pgpmjs/naming-spec';
-import type { StatementFacts } from '@pgsql/transform';
+import type { StatementFacts } from '@pgsql/semantics';
 /**
  * The column or constraint a one-command `ALTER TABLE .. ADD COLUMN` /
  * `ADD CONSTRAINT` statement adds, as a naming-spec identity