@pgpmjs/diff 0.1.2 → 0.3.0

package/diff-source.d.ts

@@ -1,16 +1,17 @@
 /**
  * Input ingestion + migration emission for `pgpm diff`.
  *
- * A diff side can be a pgpm module directory, a raw .sql file, or a live
+ * A diff side can be a pgpm module directory, a pgpm workspace (flattened by
+ * the CLI, which owns module-map resolution), a raw .sql file, or a live
  * database (handled by the CLI via pg_dump; the dump text lands here through
  * {@link sqlToDiffChanges}). Every side normalizes to the same
  * `DiffInputChange[]` seam the semantic diff driver consumes, so the
  * comparison is source- and dial-invariant.
  */
 import { PgpmRow } from '@pgpmjs/ast';
-import type { DiffInputChange, SemanticDeltaChange } from '@pgpmjs/transform';
+import type { DiffInputChange, ModuleSource, SemanticDeltaChange } from '@pgpmjs/transform';
 /** What a diff side spec resolves to. */
-export type DiffSideKind = 'module' | 'sql' | 'database';
+export type DiffSideKind = 'module' | 'sql' | 'database' | 'workspace';
 /** A diff side normalized to the semantic diff driver's input seam. */
 export interface DiffSide {
     kind: DiffSideKind;
@@ -22,7 +23,8 @@ export interface DiffSide {
 /**
  * Classify a side spec: `db:<name>` or a postgres:// / postgresql://
  * connection string is a live database; a directory containing pgpm.plan is
- * a module; an existing file is raw SQL.
+ * a module; a directory containing a workspace config (pgpm.json /
+ * pgpm.config.js) is a workspace; an existing file is raw SQL.
  */
 export declare const resolveDiffSideKind: (spec: string) => DiffSideKind;
 /**
@@ -33,9 +35,18 @@ export declare const resolveDiffSideKind: (spec: string) => DiffSideKind;
 export declare const stripDumpPreamble: (sql: string) => string;
 /** Wrap raw SQL text (a .sql file or a schema dump) as a single diff change. */
 export declare const sqlToDiffChanges: (sql: string, name: string) => DiffInputChange[];
+/**
+ * Flatten loaded workspace modules (in cross-module topological order) into
+ * diff input changes. Names are package-qualified (`pkg:change`) and local
+ * dependencies are qualified with their own package, matching how the ledger
+ * records cross-package requires.
+ */
+export declare const workspaceModulesToDiffChanges: (modules: ModuleSource[]) => DiffInputChange[];
 /**
  * Load an on-disk diff side (module directory or .sql file). Live databases
- * are dumped by the caller and fed through {@link sqlToDiffChanges}.
+ * are dumped by the caller and fed through {@link sqlToDiffChanges};
+ * workspaces are flattened by the caller (module-map resolution needs
+ * `@pgpmjs/core`) and fed through {@link workspaceModulesToDiffChanges}.
  */
 export declare const loadDiffSideFromDisk: (spec: string) => DiffSide;
 /**

package/diff-source.js

@@ -33,15 +33,18 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.deltaChangesToRows = exports.loadDiffSideFromDisk = exports.sqlToDiffChanges = exports.stripDumpPreamble = exports.resolveDiffSideKind = void 0;
+exports.deltaChangesToRows = exports.loadDiffSideFromDisk = exports.workspaceModulesToDiffChanges = exports.sqlToDiffChanges = exports.stripDumpPreamble = exports.resolveDiffSideKind = void 0;
 const naming_spec_1 = require("@pgpmjs/naming-spec");
 const transform_1 = require("@pgpmjs/transform");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+/** Files whose presence marks a directory as a pgpm workspace root. */
+const WORKSPACE_CONFIG_FILES = ['pgpm.json', 'pgpm.config.js'];
 /**
  * Classify a side spec: `db:<name>` or a postgres:// / postgresql://
  * connection string is a live database; a directory containing pgpm.plan is
- * a module; an existing file is raw SQL.
+ * a module; a directory containing a workspace config (pgpm.json /
+ * pgpm.config.js) is a workspace; an existing file is raw SQL.
  */
 const resolveDiffSideKind = (spec) => {
     if (/^postgres(ql)?:\/\//.test(spec) || spec.startsWith('db:'))
@@ -51,11 +54,13 @@ const resolveDiffSideKind = (spec) => {
         if (fs.statSync(resolved).isDirectory()) {
             if (fs.existsSync(path.join(resolved, 'pgpm.plan')))
                 return 'module';
-            throw new Error(`${spec}: directory has no pgpm.plan (not a pgpm module)`);
+            if (WORKSPACE_CONFIG_FILES.some(f => fs.existsSync(path.join(resolved, f))))
+                return 'workspace';
+            throw new Error(`${spec}: directory has no pgpm.plan or workspace config (not a pgpm module or workspace)`);
         }
         return 'sql';
     }
-    throw new Error(`${spec}: not a module directory, .sql file, db:<name>, or connection string`);
+    throw new Error(`${spec}: not a module directory, workspace, .sql file, db:<name>, or connection string`);
 };
 exports.resolveDiffSideKind = resolveDiffSideKind;
 /** Lines pg_dump emits that carry no schema content. */
@@ -84,15 +89,32 @@ const sqlToDiffChanges = (sql, name) => [
     }
 ];
 exports.sqlToDiffChanges = sqlToDiffChanges;
+/**
+ * Flatten loaded workspace modules (in cross-module topological order) into
+ * diff input changes. Names are package-qualified (`pkg:change`) and local
+ * dependencies are qualified with their own package, matching how the ledger
+ * records cross-package requires.
+ */
+const workspaceModulesToDiffChanges = (modules) => modules.flatMap(mod => mod.changes.map(change => ({
+    name: `${mod.name}:${change.name}`,
+    dependencies: change.dependencies.map(dep => dep.includes(':') ? dep : `${mod.name}:${dep}`),
+    deploy: change.deploy
+})));
+exports.workspaceModulesToDiffChanges = workspaceModulesToDiffChanges;
 /**
  * Load an on-disk diff side (module directory or .sql file). Live databases
- * are dumped by the caller and fed through {@link sqlToDiffChanges}.
+ * are dumped by the caller and fed through {@link sqlToDiffChanges};
+ * workspaces are flattened by the caller (module-map resolution needs
+ * `@pgpmjs/core`) and fed through {@link workspaceModulesToDiffChanges}.
  */
 const loadDiffSideFromDisk = (spec) => {
     const kind = (0, exports.resolveDiffSideKind)(spec);
     if (kind === 'database') {
         throw new Error(`${spec}: live database sides must be dumped by the caller`);
     }
+    if (kind === 'workspace') {
+        throw new Error(`${spec}: workspace sides must be flattened by the caller`);
+    }
     const resolved = path.resolve(spec);
     if (kind === 'module') {
         const source = (0, transform_1.loadModuleSource)(resolved);

package/esm/diff-source.js

@@ -2,10 +2,13 @@ import { alterationPathFor } from '@pgpmjs/naming-spec';
 import { loadModuleSource, stripTransactionWrapper } from '@pgpmjs/transform';
 import * as fs from 'fs';
 import * as path from 'path';
+/** Files whose presence marks a directory as a pgpm workspace root. */
+const WORKSPACE_CONFIG_FILES = ['pgpm.json', 'pgpm.config.js'];
 /**
  * Classify a side spec: `db:<name>` or a postgres:// / postgresql://
  * connection string is a live database; a directory containing pgpm.plan is
- * a module; an existing file is raw SQL.
+ * a module; a directory containing a workspace config (pgpm.json /
+ * pgpm.config.js) is a workspace; an existing file is raw SQL.
  */
 export const resolveDiffSideKind = (spec) => {
     if (/^postgres(ql)?:\/\//.test(spec) || spec.startsWith('db:'))
@@ -15,11 +18,13 @@ export const resolveDiffSideKind = (spec) => {
         if (fs.statSync(resolved).isDirectory()) {
             if (fs.existsSync(path.join(resolved, 'pgpm.plan')))
                 return 'module';
-            throw new Error(`${spec}: directory has no pgpm.plan (not a pgpm module)`);
+            if (WORKSPACE_CONFIG_FILES.some(f => fs.existsSync(path.join(resolved, f))))
+                return 'workspace';
+            throw new Error(`${spec}: directory has no pgpm.plan or workspace config (not a pgpm module or workspace)`);
         }
         return 'sql';
     }
-    throw new Error(`${spec}: not a module directory, .sql file, db:<name>, or connection string`);
+    throw new Error(`${spec}: not a module directory, workspace, .sql file, db:<name>, or connection string`);
 };
 /** Lines pg_dump emits that carry no schema content. */
 const DUMP_NOISE = [
@@ -45,15 +50,31 @@ export const sqlToDiffChanges = (sql, name) => [
         deploy: stripDumpPreamble(stripTransactionWrapper(sql))
     }
 ];
+/**
+ * Flatten loaded workspace modules (in cross-module topological order) into
+ * diff input changes. Names are package-qualified (`pkg:change`) and local
+ * dependencies are qualified with their own package, matching how the ledger
+ * records cross-package requires.
+ */
+export const workspaceModulesToDiffChanges = (modules) => modules.flatMap(mod => mod.changes.map(change => ({
+    name: `${mod.name}:${change.name}`,
+    dependencies: change.dependencies.map(dep => dep.includes(':') ? dep : `${mod.name}:${dep}`),
+    deploy: change.deploy
+})));
 /**
  * Load an on-disk diff side (module directory or .sql file). Live databases
- * are dumped by the caller and fed through {@link sqlToDiffChanges}.
+ * are dumped by the caller and fed through {@link sqlToDiffChanges};
+ * workspaces are flattened by the caller (module-map resolution needs
+ * `@pgpmjs/core`) and fed through {@link workspaceModulesToDiffChanges}.
  */
 export const loadDiffSideFromDisk = (spec) => {
     const kind = resolveDiffSideKind(spec);
     if (kind === 'database') {
         throw new Error(`${spec}: live database sides must be dumped by the caller`);
     }
+    if (kind === 'workspace') {
+        throw new Error(`${spec}: workspace sides must be flattened by the caller`);
+    }
     const resolved = path.resolve(spec);
     if (kind === 'module') {
         const source = loadModuleSource(resolved);

package/esm/index.js

@@ -1 +1,2 @@
-export { deltaChangesToRows, loadDiffSideFromDisk, resolveDiffSideKind, sqlToDiffChanges, stripDumpPreamble } from './diff-source';
+export { deltaChangesToRows, loadDiffSideFromDisk, resolveDiffSideKind, sqlToDiffChanges, stripDumpPreamble, workspaceModulesToDiffChanges } from './diff-source';
+export { classifyAgainstLedger, emitLedgerBackfill, selectBackfillEntries } from './ledger';

package/esm/ledger.js

@@ -0,0 +1,135 @@
+/**
+ * Ledger-aware classification and backfill for `pgpm diff`.
+ *
+ * The `pgpm_migrate` ledger is a cursor into a workspace's deployment
+ * history: which plan changes a database has executed, with what script
+ * hashes, in what order. These pure helpers relate a workspace's plan to a
+ * ledger snapshot (classification) and project a set of already-satisfied
+ * changes into idempotent ledger writes (backfill) so a database can adopt a
+ * regenerated/reordered plan without re-executing what it already has.
+ */
+const refKey = (pkg, name) => `${pkg}:${name}`;
+/**
+ * Classify a plan against a ledger snapshot. Pure and name/hash-based:
+ * `deployed-identical` requires the ledger's recorded hash to be one of the
+ * plan entry's candidate hashes; a name match with a foreign hash is
+ * `deployed-drifted`. Semantic satisfaction (same objects under different
+ * names) is the coverage layer's job (`coverChanges`), not this one's.
+ */
+export function classifyAgainstLedger(plan, ledger) {
+    const ledgerByKey = new Map();
+    for (const row of ledger) {
+        ledgerByKey.set(refKey(row.package, row.changeName), row);
+    }
+    const planKeys = new Set(plan.map(ref => refKey(ref.package, ref.name)));
+    const entries = plan.map(ref => {
+        const row = ledgerByKey.get(refKey(ref.package, ref.name));
+        if (!row)
+            return { package: ref.package, name: ref.name, status: 'pending' };
+        return {
+            package: ref.package,
+            name: ref.name,
+            status: ref.hashes.includes(row.scriptHash) ? 'deployed-identical' : 'deployed-drifted',
+            ledgerHash: row.scriptHash
+        };
+    });
+    const orphaned = ledger.filter(row => !planKeys.has(refKey(row.package, row.changeName)));
+    // Inversion detection: walk the ledger in deploy order and flag any
+    // plan-known change that lands after a change the plan places later.
+    const planIndex = new Map();
+    plan.forEach((ref, i) => planIndex.set(refKey(ref.package, ref.name), i));
+    const outOfOrder = [];
+    let maxSeen = -1;
+    for (const row of ledger) {
+        const idx = planIndex.get(refKey(row.package, row.changeName));
+        if (idx === undefined)
+            continue;
+        if (idx < maxSeen)
+            outOfOrder.push(refKey(row.package, row.changeName));
+        else
+            maxSeen = idx;
+    }
+    return { entries, orphaned, outOfOrder };
+}
+/**
+ * Choose which plan entries to backfill: those the ledger does not record
+ * (`pending`) but whose objects side A already has (coverage `satisfied`).
+ * Entries with `inert` or `partial` coverage are reported as unprovable and
+ * left for a normal deploy — backfilling them would claim DDL ran that did
+ * not. Pure: the caller supplies the plan refs, the ledger classification,
+ * and the coverage.
+ */
+export function selectBackfillEntries(refs, classification, coverage) {
+    // Coverage names follow the side: `pkg:change` for workspaces, bare change
+    // names for a single module. Accept either.
+    const coverageByName = new Map();
+    for (const cov of coverage)
+        coverageByName.set(cov.name, cov);
+    const coverageFor = (ref) => coverageByName.get(refKey(ref.package, ref.name)) ?? coverageByName.get(ref.name);
+    const pending = new Set(classification.entries.filter(e => e.status === 'pending').map(e => refKey(e.package, e.name)));
+    const backfilled = [];
+    const unprovable = [];
+    const entries = [];
+    for (const ref of refs) {
+        if (!pending.has(refKey(ref.package, ref.name)))
+            continue;
+        const status = coverageFor(ref)?.status;
+        if (status === 'inert' || status === 'partial') {
+            unprovable.push(refKey(ref.package, ref.name));
+            continue;
+        }
+        if (status !== 'satisfied')
+            continue;
+        // The content hash is what a default `pgpm deploy` records and skips by;
+        // without one there is nothing meaningful to record.
+        const scriptHash = ref.hashes[0];
+        if (!scriptHash)
+            continue;
+        backfilled.push(refKey(ref.package, ref.name));
+        entries.push({
+            package: ref.package,
+            changeName: ref.name,
+            scriptHash,
+            requires: ref.dependencies
+        });
+    }
+    return { entries, backfilled, unprovable };
+}
+const sqlLiteral = (value) => `'${value.replace(/'/g, "''")}'`;
+/**
+ * Project backfill entries into an idempotent SQL script that records them in
+ * `pgpm_migrate` without executing any DDL, by calling the same
+ * `pgpm_migrate.deploy` procedure a real deploy uses with `p_log_only =>
+ * TRUE` and an empty script. Entries must be in plan order (the procedure
+ * enforces that requires are already recorded). The target database must
+ * already have the `pgpm_migrate` schema (any prior `pgpm deploy` creates
+ * it).
+ */
+export function emitLedgerBackfill(entries, options = {}) {
+    const transaction = options.transaction !== false;
+    const lines = [
+        '-- pgpm ledger backfill: record already-satisfied changes in pgpm_migrate',
+        '-- without executing them (log-only deploys through pgpm_migrate.deploy).',
+        ''
+    ];
+    if (transaction)
+        lines.push('BEGIN;', '');
+    for (const entry of entries) {
+        const requires = entry.requires.length > 0
+            ? `ARRAY[${entry.requires.map(sqlLiteral).join(', ')}]`
+            : 'NULL';
+        lines.push('CALL pgpm_migrate.deploy(' +
+            [
+                sqlLiteral(entry.package),
+                sqlLiteral(entry.changeName),
+                sqlLiteral(entry.scriptHash),
+                requires,
+                "''",
+                'TRUE'
+            ].join(', ') +
+            ');');
+    }
+    if (transaction)
+        lines.push('', 'COMMIT;');
+    return `${lines.join('\n')}\n`;
+}

package/index.d.ts

@@ -1,2 +1,4 @@
 export type { DiffSide, DiffSideKind } from './diff-source';
-export { deltaChangesToRows, loadDiffSideFromDisk, resolveDiffSideKind, sqlToDiffChanges, stripDumpPreamble } from './diff-source';
+export { deltaChangesToRows, loadDiffSideFromDisk, resolveDiffSideKind, sqlToDiffChanges, stripDumpPreamble, workspaceModulesToDiffChanges } from './diff-source';
+export type { BackfillSelection, CoverageStatus, LedgerBackfillEntry, LedgerChangeRecord, LedgerClassification, LedgerEntryClassification, LedgerStatus, PlanChangeRef } from './ledger';
+export { classifyAgainstLedger, emitLedgerBackfill, selectBackfillEntries } from './ledger';

package/index.js

@@ -1,9 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stripDumpPreamble = exports.sqlToDiffChanges = exports.resolveDiffSideKind = exports.loadDiffSideFromDisk = exports.deltaChangesToRows = void 0;
+exports.selectBackfillEntries = exports.emitLedgerBackfill = exports.classifyAgainstLedger = exports.workspaceModulesToDiffChanges = exports.stripDumpPreamble = exports.sqlToDiffChanges = exports.resolveDiffSideKind = exports.loadDiffSideFromDisk = exports.deltaChangesToRows = void 0;
 var diff_source_1 = require("./diff-source");
 Object.defineProperty(exports, "deltaChangesToRows", { enumerable: true, get: function () { return diff_source_1.deltaChangesToRows; } });
 Object.defineProperty(exports, "loadDiffSideFromDisk", { enumerable: true, get: function () { return diff_source_1.loadDiffSideFromDisk; } });
 Object.defineProperty(exports, "resolveDiffSideKind", { enumerable: true, get: function () { return diff_source_1.resolveDiffSideKind; } });
 Object.defineProperty(exports, "sqlToDiffChanges", { enumerable: true, get: function () { return diff_source_1.sqlToDiffChanges; } });
 Object.defineProperty(exports, "stripDumpPreamble", { enumerable: true, get: function () { return diff_source_1.stripDumpPreamble; } });
+Object.defineProperty(exports, "workspaceModulesToDiffChanges", { enumerable: true, get: function () { return diff_source_1.workspaceModulesToDiffChanges; } });
+var ledger_1 = require("./ledger");
+Object.defineProperty(exports, "classifyAgainstLedger", { enumerable: true, get: function () { return ledger_1.classifyAgainstLedger; } });
+Object.defineProperty(exports, "emitLedgerBackfill", { enumerable: true, get: function () { return ledger_1.emitLedgerBackfill; } });
+Object.defineProperty(exports, "selectBackfillEntries", { enumerable: true, get: function () { return ledger_1.selectBackfillEntries; } });

package/ledger.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Ledger-aware classification and backfill for `pgpm diff`.
+ *
+ * The `pgpm_migrate` ledger is a cursor into a workspace's deployment
+ * history: which plan changes a database has executed, with what script
+ * hashes, in what order. These pure helpers relate a workspace's plan to a
+ * ledger snapshot (classification) and project a set of already-satisfied
+ * changes into idempotent ledger writes (backfill) so a database can adopt a
+ * regenerated/reordered plan without re-executing what it already has.
+ */
+/** One row of a database's `pgpm_migrate` ledger, in deploy order. */
+export interface LedgerChangeRecord {
+    package: string;
+    changeName: string;
+    scriptHash: string;
+    deployedAt?: Date;
+    requires?: string[];
+}
+/** One plan entry of a workspace/module side, with its candidate hashes. */
+export interface PlanChangeRef {
+    package: string;
+    name: string;
+    /**
+     * Hashes that count as "this exact script": typically the content hash
+     * (what `pgpm deploy` records by default) plus the AST hash (formatting-
+     * and comment-proof, what `DEPLOYMENT_HASH_METHOD=ast` records).
+     */
+    hashes: string[];
+    /** Plan dependencies as written (local names or `pkg:change`). */
+    dependencies: string[];
+}
+/** How one plan entry relates to the ledger. */
+export type LedgerStatus = 'deployed-identical' | 'deployed-drifted' | 'pending';
+export interface LedgerEntryClassification {
+    package: string;
+    name: string;
+    status: LedgerStatus;
+    /** The hash the ledger recorded, when the change name is in the ledger. */
+    ledgerHash?: string;
+}
+export interface LedgerClassification {
+    entries: LedgerEntryClassification[];
+    /** Ledger rows whose (package, change) appears in no plan entry. */
+    orphaned: LedgerChangeRecord[];
+    /**
+     * Plan-known changes whose recorded deploy order inverts the plan order
+     * (deployed before a change that precedes them in the plan).
+     */
+    outOfOrder: string[];
+}
+/**
+ * Classify a plan against a ledger snapshot. Pure and name/hash-based:
+ * `deployed-identical` requires the ledger's recorded hash to be one of the
+ * plan entry's candidate hashes; a name match with a foreign hash is
+ * `deployed-drifted`. Semantic satisfaction (same objects under different
+ * names) is the coverage layer's job (`coverChanges`), not this one's.
+ */
+export declare function classifyAgainstLedger(plan: PlanChangeRef[], ledger: LedgerChangeRecord[]): LedgerClassification;
+/**
+ * A change's semantic coverage, as produced by `coverChanges`. Structural so
+ * this layer stays free of the transform driver's imports.
+ */
+export interface CoverageStatus {
+    /** Change name as the diff side reported it (`pkg:change` or `change`). */
+    name: string;
+    status: 'satisfied' | 'unsatisfied' | 'partial' | 'inert';
+}
+/** Which plan entries a ledger backfill should record, and which it cannot. */
+export interface BackfillSelection {
+    /** Ledger rows to write, in plan order. */
+    entries: LedgerBackfillEntry[];
+    /** Entries backfilled: semantically satisfied but absent from the ledger. */
+    backfilled: string[];
+    /** Entries whose satisfaction is unprovable (inert/partial); left to deploy. */
+    unprovable: string[];
+}
+/**
+ * Choose which plan entries to backfill: those the ledger does not record
+ * (`pending`) but whose objects side A already has (coverage `satisfied`).
+ * Entries with `inert` or `partial` coverage are reported as unprovable and
+ * left for a normal deploy — backfilling them would claim DDL ran that did
+ * not. Pure: the caller supplies the plan refs, the ledger classification,
+ * and the coverage.
+ */
+export declare function selectBackfillEntries(refs: PlanChangeRef[], classification: LedgerClassification, coverage: CoverageStatus[]): BackfillSelection;
+/** One ledger row to backfill without executing anything. */
+export interface LedgerBackfillEntry {
+    package: string;
+    changeName: string;
+    scriptHash: string;
+    /** Requires exactly as the plan records them (local or `pkg:change`). */
+    requires: string[];
+}
+/**
+ * Project backfill entries into an idempotent SQL script that records them in
+ * `pgpm_migrate` without executing any DDL, by calling the same
+ * `pgpm_migrate.deploy` procedure a real deploy uses with `p_log_only =>
+ * TRUE` and an empty script. Entries must be in plan order (the procedure
+ * enforces that requires are already recorded). The target database must
+ * already have the `pgpm_migrate` schema (any prior `pgpm deploy` creates
+ * it).
+ */
+export declare function emitLedgerBackfill(entries: LedgerBackfillEntry[], options?: {
+    transaction?: boolean;
+}): string;

package/ledger.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * Ledger-aware classification and backfill for `pgpm diff`.
+ *
+ * The `pgpm_migrate` ledger is a cursor into a workspace's deployment
+ * history: which plan changes a database has executed, with what script
+ * hashes, in what order. These pure helpers relate a workspace's plan to a
+ * ledger snapshot (classification) and project a set of already-satisfied
+ * changes into idempotent ledger writes (backfill) so a database can adopt a
+ * regenerated/reordered plan without re-executing what it already has.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyAgainstLedger = classifyAgainstLedger;
+exports.selectBackfillEntries = selectBackfillEntries;
+exports.emitLedgerBackfill = emitLedgerBackfill;
+const refKey = (pkg, name) => `${pkg}:${name}`;
+/**
+ * Classify a plan against a ledger snapshot. Pure and name/hash-based:
+ * `deployed-identical` requires the ledger's recorded hash to be one of the
+ * plan entry's candidate hashes; a name match with a foreign hash is
+ * `deployed-drifted`. Semantic satisfaction (same objects under different
+ * names) is the coverage layer's job (`coverChanges`), not this one's.
+ */
+function classifyAgainstLedger(plan, ledger) {
+    const ledgerByKey = new Map();
+    for (const row of ledger) {
+        ledgerByKey.set(refKey(row.package, row.changeName), row);
+    }
+    const planKeys = new Set(plan.map(ref => refKey(ref.package, ref.name)));
+    const entries = plan.map(ref => {
+        const row = ledgerByKey.get(refKey(ref.package, ref.name));
+        if (!row)
+            return { package: ref.package, name: ref.name, status: 'pending' };
+        return {
+            package: ref.package,
+            name: ref.name,
+            status: ref.hashes.includes(row.scriptHash) ? 'deployed-identical' : 'deployed-drifted',
+            ledgerHash: row.scriptHash
+        };
+    });
+    const orphaned = ledger.filter(row => !planKeys.has(refKey(row.package, row.changeName)));
+    // Inversion detection: walk the ledger in deploy order and flag any
+    // plan-known change that lands after a change the plan places later.
+    const planIndex = new Map();
+    plan.forEach((ref, i) => planIndex.set(refKey(ref.package, ref.name), i));
+    const outOfOrder = [];
+    let maxSeen = -1;
+    for (const row of ledger) {
+        const idx = planIndex.get(refKey(row.package, row.changeName));
+        if (idx === undefined)
+            continue;
+        if (idx < maxSeen)
+            outOfOrder.push(refKey(row.package, row.changeName));
+        else
+            maxSeen = idx;
+    }
+    return { entries, orphaned, outOfOrder };
+}
+/**
+ * Choose which plan entries to backfill: those the ledger does not record
+ * (`pending`) but whose objects side A already has (coverage `satisfied`).
+ * Entries with `inert` or `partial` coverage are reported as unprovable and
+ * left for a normal deploy — backfilling them would claim DDL ran that did
+ * not. Pure: the caller supplies the plan refs, the ledger classification,
+ * and the coverage.
+ */
+function selectBackfillEntries(refs, classification, coverage) {
+    // Coverage names follow the side: `pkg:change` for workspaces, bare change
+    // names for a single module. Accept either.
+    const coverageByName = new Map();
+    for (const cov of coverage)
+        coverageByName.set(cov.name, cov);
+    const coverageFor = (ref) => coverageByName.get(refKey(ref.package, ref.name)) ?? coverageByName.get(ref.name);
+    const pending = new Set(classification.entries.filter(e => e.status === 'pending').map(e => refKey(e.package, e.name)));
+    const backfilled = [];
+    const unprovable = [];
+    const entries = [];
+    for (const ref of refs) {
+        if (!pending.has(refKey(ref.package, ref.name)))
+            continue;
+        const status = coverageFor(ref)?.status;
+        if (status === 'inert' || status === 'partial') {
+            unprovable.push(refKey(ref.package, ref.name));
+            continue;
+        }
+        if (status !== 'satisfied')
+            continue;
+        // The content hash is what a default `pgpm deploy` records and skips by;
+        // without one there is nothing meaningful to record.
+        const scriptHash = ref.hashes[0];
+        if (!scriptHash)
+            continue;
+        backfilled.push(refKey(ref.package, ref.name));
+        entries.push({
+            package: ref.package,
+            changeName: ref.name,
+            scriptHash,
+            requires: ref.dependencies
+        });
+    }
+    return { entries, backfilled, unprovable };
+}
+const sqlLiteral = (value) => `'${value.replace(/'/g, "''")}'`;
+/**
+ * Project backfill entries into an idempotent SQL script that records them in
+ * `pgpm_migrate` without executing any DDL, by calling the same
+ * `pgpm_migrate.deploy` procedure a real deploy uses with `p_log_only =>
+ * TRUE` and an empty script. Entries must be in plan order (the procedure
+ * enforces that requires are already recorded). The target database must
+ * already have the `pgpm_migrate` schema (any prior `pgpm deploy` creates
+ * it).
+ */
+function emitLedgerBackfill(entries, options = {}) {
+    const transaction = options.transaction !== false;
+    const lines = [
+        '-- pgpm ledger backfill: record already-satisfied changes in pgpm_migrate',
+        '-- without executing them (log-only deploys through pgpm_migrate.deploy).',
+        ''
+    ];
+    if (transaction)
+        lines.push('BEGIN;', '');
+    for (const entry of entries) {
+        const requires = entry.requires.length > 0
+            ? `ARRAY[${entry.requires.map(sqlLiteral).join(', ')}]`
+            : 'NULL';
+        lines.push('CALL pgpm_migrate.deploy(' +
+            [
+                sqlLiteral(entry.package),
+                sqlLiteral(entry.changeName),
+                sqlLiteral(entry.scriptHash),
+                requires,
+                "''",
+                'TRUE'
+            ].join(', ') +
+            ');');
+    }
+    if (transaction)
+        lines.push('', 'COMMIT;');
+    return `${lines.join('\n')}\n`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgpmjs/diff",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "pgpm diff — identity-keyed semantic schema diff between pgpm modules, SQL dumps, and live databases",
   "main": "index.js",
@@ -42,9 +42,9 @@
     "makage": "^0.3.0"
   },
   "dependencies": {
-    "@pgpmjs/ast": "^0.10.3",
-    "@pgpmjs/naming-spec": "^0.2.0",
-    "@pgpmjs/transform": "^0.20.0"
+    "@pgpmjs/ast": "^0.11.1",
+    "@pgpmjs/naming-spec": "^0.3.0",
+    "@pgpmjs/transform": "^0.22.0"
   },
-  "gitHead": "e6a7a57f88c9deb2a4acecaba2451320d1be8203"
+  "gitHead": "6da0705f8aa49d62dc2defb8b135b71674611483"
 }