@pgpmjs/core 7.13.0 → 7.15.0

package/apply/types.d.ts

@@ -0,0 +1,172 @@
+/**
+ * The apply-spec ("proxy module") types.
+ *
+ * A proxy module is a directory containing a single `pgpm.apply.json` file:
+ * "apply <source module> transpiled with this schema map, under my name". It
+ * needs no `.control`, no `pgpm.plan`, and no deploy/revert/verify scripts —
+ * workspace discovery synthesizes a module entry from the spec, so the proxy
+ * participates in dependency resolution by name exactly like a regular
+ * module. At deploy/verify/revert time the engine transpiles the source
+ * module in memory and runs the normal migration path against the result;
+ * transpiled code is never committed.
+ */
+/** File name of the apply spec inside a proxy module directory. */
+export declare const APPLY_SPEC_FILE = "pgpm.apply.json";
+/** Expanded reference to the source module a proxy module applies. */
+export interface ApplySpecSource {
+    /**
+     * Control/module name of the source module as it appears in the workspace
+     * module map (e.g. `pgpm-totp`). The source is typically installed into the
+     * workspace extensions directory via `pgpm install`; it is source material,
+     * not a runtime dependency, so it must not appear in `requires`.
+     */
+    module: string;
+    /** Optional npm package name the source is installed from (e.g. `@pgpm/totp`). */
+    package?: string;
+    /** Optional exact version pin for the source package. */
+    version?: string;
+    /**
+     * Optional content-addressed pin: the expected `manifest.digest` of the
+     * source bundle. When present, apply refuses to proceed if the installed
+     * source does not hash to exactly this digest.
+     */
+    bundleDigest?: string;
+}
+/**
+ * An object-level route in a `pgpm.apply.json` spec: send one named object out
+ * of a source schema to a target schema, overriding the whole-schema default
+ * for that object only. Kinds are expressed as separate properties (no dotted
+ * identity strings), so a table and a function of the same name route
+ * independently.
+ */
+export interface ApplyRouteEntry {
+    /** Source schema the object is defined in (e.g. `users`). */
+    fromSchema: string;
+    /** Object namespace: `table`/`view` → relation, `procedure` → function. */
+    kind: 'table' | 'view' | 'function' | 'procedure' | 'type';
+    /** Unqualified object name (e.g. `accounts`). */
+    name: string;
+    /** Target schema the object is routed to (e.g. `reporting`). */
+    toSchema: string;
+}
+/**
+ * A per-tenant seed object in a reuse spec: the objects that must be
+ * materialized once *per tenant*. `@pgpmjs/slice`'s `partitionModule` starts
+ * from these seeds and marks every change that transitively reaches one as
+ * per-tenant; everything else is proven shared and emitted once. Expressed as
+ * separate properties (no dotted identity strings), matching {@link ApplyRouteEntry}.
+ */
+export interface ApplyReuseSeed {
+    /** Source schema the seed object is defined in (e.g. `catalog`). */
+    fromSchema: string;
+    /** Object namespace: `table`/`view` → relation, `procedure` → function. */
+    kind: 'table' | 'view' | 'function' | 'procedure' | 'type';
+    /** Unqualified object name (e.g. `products`). */
+    name: string;
+}
+/**
+ * Reuse declaration: split the source into a *shared* module (deployed once,
+ * reused by every tenant via ordinary `requires`) and a *per-tenant* module
+ * (materialized per instance). The classifier proves the split from the
+ * `perTenant` seeds; a shared object that would depend on a per-tenant one is
+ * rejected as unsound rather than silently deployed.
+ */
+export interface ApplyReuseSpec {
+    /**
+     * Source schema → *shared* target schema. Shared objects land here; this
+     * mapping must be stable across tenant instances so the shared module has a
+     * deterministic identity and deploys exactly once.
+     */
+    sharedSchema: Record<string, string>;
+    /** Per-tenant seed objects (non-empty). */
+    perTenant: ApplyReuseSeed[];
+    /**
+     * Optional explicit shared-module name. Defaults to a deterministic name
+     * derived from the source module and the shared-schema mapping, so two tenant
+     * proxies over the same source + shared mapping resolve to one shared module.
+     */
+    sharedName?: string;
+}
+/**
+ * Extension-routing declaration in a `pgpm.apply.json`: where the transpiled
+ * instance should install extensions and resolve the symbols they provide
+ * (e.g. isolate `pgcrypto` in a dedicated `extensions` schema, qualifying bare
+ * `crypt(...)` calls, or the reverse). A distinct dimension from schema
+ * routing — driven by a version-aware symbol inventory, not by the objects the
+ * SQL itself creates. Forwarded to `@pgpmjs/transform`'s extension router.
+ */
+export interface ApplyExtensionsSpec {
+    /**
+     * Install the matched extensions and route their provided symbols to this
+     * schema. `null` strips qualification (rely on `search_path`). Ignored when
+     * `routes` is given.
+     */
+    toSchema?: string | null;
+    /** With `toSchema`: limit to these extensions (default: every inventoried one). */
+    only?: string[];
+    /**
+     * With `toSchema`: which source qualifications to rewrite (a `null` entry
+     * also rewrites bare references). Defaults to `public` + bare.
+     */
+    from?: (string | null)[];
+    /**
+     * Advanced: explicit per-extension routes (`{ "<ext>": { "to": "<schema>|null",
+     * "from"?: [...] } }`). Overrides `toSchema`/`only`/`from`.
+     */
+    routes?: Record<string, {
+        to: string | null;
+        from?: (string | null)[];
+    }>;
+    /** Target PostgreSQL major version, for core-graduation awareness. */
+    serverVersion?: number;
+}
+/** Role-name translation: source role name → target role name. */
+export type ApplyRolesSpec = Record<string, string>;
+/** The parsed, normalized `pgpm.apply.json` spec. */
+export interface PgpmApplySpec {
+    /**
+     * Module name this instance is deployed as. Defaults to the proxy
+     * directory's name.
+     */
+    name?: string;
+    /** Source module reference: a module name, or the expanded object form. */
+    source: string | ApplySpecSource;
+    /**
+     * Whole-schema default: source schema → target schema (drives the AST + plan
+     * rewrite). Optional when `route` fully covers the objects being moved.
+     */
+    schemas?: Record<string, string>;
+    /**
+     * Object-level routes. Each entry overrides the `schemas` default for its
+     * specific object, letting one source schema fan out per object (e.g. a
+     * table into a tenant schema and a function into a shared schema).
+     */
+    route?: ApplyRouteEntry[];
+    /**
+     * Reuse declaration: split shared vs per-tenant objects (see
+     * {@link ApplyReuseSpec}). When present, this proxy expands into two modules —
+     * a shared module and a per-tenant module that `requires` it.
+     */
+    reuse?: ApplyReuseSpec;
+    /**
+     * Extension routing: where to install extensions and resolve their provided
+     * symbols in the transpiled instance (see {@link ApplyExtensionsSpec}).
+     */
+    extensions?: ApplyExtensionsSpec;
+    /**
+     * Role-name translation applied to the transpiled instance's SQL
+     * (see {@link ApplyRolesSpec}). Renames role identifiers only.
+     */
+    roles?: ApplyRolesSpec;
+    /**
+     * Runtime requires of the transpiled output (native extensions and other
+     * modules). Defaults to the source module's own requires.
+     */
+    requires?: string[];
+    /** Version reported for this instance (default: the source's version). */
+    version?: string;
+}
+/** {@link PgpmApplySpec} with `source` normalized to the object form. */
+export interface ResolvedApplySpec extends Omit<PgpmApplySpec, 'source'> {
+    source: ApplySpecSource;
+}

package/apply/types.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * The apply-spec ("proxy module") types.
+ *
+ * A proxy module is a directory containing a single `pgpm.apply.json` file:
+ * "apply <source module> transpiled with this schema map, under my name". It
+ * needs no `.control`, no `pgpm.plan`, and no deploy/revert/verify scripts —
+ * workspace discovery synthesizes a module entry from the spec, so the proxy
+ * participates in dependency resolution by name exactly like a regular
+ * module. At deploy/verify/revert time the engine transpiles the source
+ * module in memory and runs the normal migration path against the result;
+ * transpiled code is never committed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APPLY_SPEC_FILE = void 0;
+/** File name of the apply spec inside a proxy module directory. */
+exports.APPLY_SPEC_FILE = 'pgpm.apply.json';

package/bundle/artifact.d.ts

@@ -0,0 +1,35 @@
+import { CreateBundleOptions, MigrationBundle } from '@pgpmjs/bundle';
+/**
+ * Artifact file name for a module's stored bundle: it lives beside the packaged
+ * `sql/<name>--<version>.sql` as `sql/<name>--<version>.bundle.tar.gz`.
+ */
+export declare function bundleArtifactFileName(name: string, version: string): string;
+/**
+ * Locate a module's stored bundle artifact, if it has one.
+ *
+ * Prefers the version declared in the module's `.control` file, then falls back
+ * to any single `sql/*.bundle.tar.gz` present — so a module packaged at a
+ * different version still gets the fast path instead of silently degrading.
+ * Returns `null` when the module ships no artifact.
+ */
+export declare function resolveBundleArtifactPath(moduleDir: string): string | null;
+/**
+ * Build the executable form of a module's bundle: the content-addressed AST
+ * snapshot plus, per change, the deploy SQL with transaction / `CREATE
+ * EXTENSION` statements stripped (`cleanSql`).
+ *
+ * That pre-computation is the whole point of the artifact — the parse/deparse
+ * work moves from every deploy to the one-time package step, while the digests
+ * still cover the exact bytes that will be executed.
+ */
+export declare function buildExecutableBundle(moduleDir: string, options?: CreateBundleOptions): Promise<MigrationBundle>;
+/**
+ * Emit a module's stored bundle artifact into `sql/`, returning its path.
+ */
+export declare function writeBundleArtifact(moduleDir: string, version: string, options?: CreateBundleOptions): Promise<string>;
+/**
+ * Read a module's stored bundle artifact, or `null` when it has none or the
+ * archive cannot be read. Never throws — a broken artifact must degrade to the
+ * normal packaging path, not fail the deploy.
+ */
+export declare function readBundleArtifact(moduleDir: string): MigrationBundle | null;

package/bundle/artifact.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bundleArtifactFileName = bundleArtifactFileName;
+exports.resolveBundleArtifactPath = resolveBundleArtifactPath;
+exports.buildExecutableBundle = buildExecutableBundle;
+exports.writeBundleArtifact = writeBundleArtifact;
+exports.readBundleArtifact = readBundleArtifact;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const files_1 = require("@pgpmjs/ast/files");
+const bundle_1 = require("@pgpmjs/bundle");
+const clean_1 = require("../migrate/clean");
+/**
+ * Artifact file name for a module's stored bundle: it lives beside the packaged
+ * `sql/<name>--<version>.sql` as `sql/<name>--<version>.bundle.tar.gz`.
+ */
+function bundleArtifactFileName(name, version) {
+    return `${name}--${version}${bundle_1.BUNDLE_ARCHIVE_EXTENSION}`;
+}
+/**
+ * Locate a module's stored bundle artifact, if it has one.
+ *
+ * Prefers the version declared in the module's `.control` file, then falls back
+ * to any single `sql/*.bundle.tar.gz` present — so a module packaged at a
+ * different version still gets the fast path instead of silently degrading.
+ * Returns `null` when the module ships no artifact.
+ */
+function resolveBundleArtifactPath(moduleDir) {
+    const sqlDir = (0, path_1.join)(moduleDir, 'sql');
+    if (!(0, fs_1.existsSync)(sqlDir))
+        return null;
+    let name;
+    try {
+        name = (0, files_1.getExtensionName)(moduleDir);
+    }
+    catch {
+        return null;
+    }
+    const controlPath = (0, path_1.join)(moduleDir, `${name}.control`);
+    if ((0, fs_1.existsSync)(controlPath)) {
+        const { version } = (0, files_1.parseControlContent)((0, fs_1.readFileSync)(controlPath, 'utf-8'));
+        if (version) {
+            const versioned = (0, path_1.join)(sqlDir, bundleArtifactFileName(name, version));
+            if ((0, fs_1.existsSync)(versioned))
+                return versioned;
+        }
+    }
+    const candidates = (0, fs_1.readdirSync)(sqlDir).filter(file => file.startsWith(`${name}--`) && file.endsWith(bundle_1.BUNDLE_ARCHIVE_EXTENSION));
+    if (candidates.length !== 1)
+        return null;
+    return (0, path_1.join)(sqlDir, candidates[0]);
+}
+/**
+ * Build the executable form of a module's bundle: the content-addressed AST
+ * snapshot plus, per change, the deploy SQL with transaction / `CREATE
+ * EXTENSION` statements stripped (`cleanSql`).
+ *
+ * That pre-computation is the whole point of the artifact — the parse/deparse
+ * work moves from every deploy to the one-time package step, while the digests
+ * still cover the exact bytes that will be executed.
+ */
+async function buildExecutableBundle(moduleDir, options) {
+    const bundle = (0, bundle_1.bundleFromModule)(moduleDir, options);
+    const execSql = {};
+    for (const change of bundle.changes) {
+        if (!change.deploy)
+            continue;
+        execSql[change.name] = await (0, clean_1.cleanSql)(change.deploy.sql, false, '$EOFCODE$');
+    }
+    return (0, bundle_1.withExecutableSql)(bundle, execSql);
+}
+/**
+ * Emit a module's stored bundle artifact into `sql/`, returning its path.
+ */
+async function writeBundleArtifact(moduleDir, version, options) {
+    const bundle = await buildExecutableBundle(moduleDir, options);
+    const outPath = (0, path_1.join)(moduleDir, 'sql', bundleArtifactFileName(bundle.manifest.name, version));
+    (0, bundle_1.writeBundleArchiveFile)(bundle, outPath);
+    return outPath;
+}
+/**
+ * Read a module's stored bundle artifact, or `null` when it has none or the
+ * archive cannot be read. Never throws — a broken artifact must degrade to the
+ * normal packaging path, not fail the deploy.
+ */
+function readBundleArtifact(moduleDir) {
+    const artifactPath = resolveBundleArtifactPath(moduleDir);
+    if (!artifactPath)
+        return null;
+    try {
+        return (0, bundle_1.readBundleArchiveFile)(artifactPath);
+    }
+    catch {
+        return null;
+    }
+}

package/bundle/deploy-bundled.d.ts

@@ -0,0 +1,71 @@
+import { BundleChange } from '@pgpmjs/bundle';
+import { PgConfig } from 'pg-env';
+/**
+ * Why the one-shot path could not be used, so the caller falls back to the
+ * per-change migration path.
+ */
+export type BundledDeploySkipReason = 'no-executable-sql' | 'unsupported-hash-method';
+/** How the executable bundle for a module was obtained. */
+export type BundleSource = 'artifact' | 'packaged';
+export interface BundledDeployResult {
+    /** Module (package) name from the bundle manifest. */
+    name: string;
+    /** Where the executable bundle came from. */
+    source: BundleSource;
+    /** Changes executed and recorded on this run, in deploy order. */
+    deployed: string[];
+    /** Changes already present in the ledger with a matching hash. */
+    skipped: string[];
+}
+export interface BundledDeployOptions {
+    config: PgConfig;
+    /** Target database (defaults to `config.database`). */
+    database?: string;
+    /** Record ledger rows without executing the DDL. */
+    logOnly?: boolean;
+    /** Wrap execution + ledger writes in one transaction. Default true. */
+    useTransaction?: boolean;
+    /**
+     * Ledger hash scheme in force. The bundle's per-change digests are sha256 of
+     * the deploy script's bytes, i.e. identical to `PgpmMigrate`'s `content`
+     * scheme; the `ast` scheme is not reproducible here, so it is reported as a
+     * skip and the caller falls back.
+     */
+    hashMethod?: 'content' | 'ast';
+}
+/** Thrown when the ledger already holds a change with different content. */
+export declare class BundledDeployConflictError extends Error {
+    readonly packageName: string;
+    readonly changeName: string;
+    constructor(packageName: string, changeName: string);
+}
+/**
+ * The ledger hash for a change: the sha256 of the deploy script bytes.
+ *
+ * This is deliberately the same value `PgpmMigrate.calculateScriptHash` derives
+ * from `deploy/<change>.sql` under the default `content` hash method, so a
+ * change hashed at package time and the hash recorded/compared at deploy time
+ * agree — the one-shot and per-change paths are interchangeable and idempotent
+ * against each other.
+ */
+export declare function ledgerHashForChange(change: BundleChange): string | null;
+/**
+ * Deploy a module in one shot **and** record the migration ledger — the `fast`
+ * deploy strategy.
+ *
+ * Pending changes' deploy SQL is concatenated and executed as a single
+ * statement (the speed of the old fast path), then one `pgpm_migrate.changes`
+ * row per change is bulk-inserted with the deploy script's own sha256 as
+ * `script_hash` — one round-trip, instead of an `isDeployed` + `readScript` +
+ * `CALL pgpm_migrate.deploy` per change. Because the ledger is written, the
+ * path is idempotent and resumable: re-deploys skip changes whose stored hash
+ * matches, and a same-name/different-content change raises
+ * {@link BundledDeployConflictError} exactly as the per-change path does.
+ *
+ * Returns a {@link BundledDeploySkipReason} (rather than throwing) when it
+ * cannot honour the requested semantics, so the caller falls back to the
+ * per-change migration path. Genuine SQL failures still throw.
+ */
+export declare function deployModuleFast(moduleDir: string, options: BundledDeployOptions): Promise<BundledDeployResult | BundledDeploySkipReason>;
+/** True when the value is a real deploy result rather than a skip reason. */
+export declare function isBundledDeployResult(value: BundledDeployResult | BundledDeploySkipReason): value is BundledDeployResult;

package/bundle/deploy-bundled.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BundledDeployConflictError = void 0;
+exports.ledgerHashForChange = ledgerHashForChange;
+exports.deployModuleFast = deployModuleFast;
+exports.isBundledDeployResult = isBundledDeployResult;
+const logger_1 = require("@pgpmjs/logger");
+const bundle_1 = require("@pgpmjs/bundle");
+const pg_cache_1 = require("pg-cache");
+const client_1 = require("../migrate/client");
+const artifact_1 = require("./artifact");
+const log = new logger_1.Logger('deploy-fast');
+/** Thrown when the ledger already holds a change with different content. */
+class BundledDeployConflictError extends Error {
+    packageName;
+    changeName;
+    constructor(packageName, changeName) {
+        super(`Change ${changeName} already deployed in package ${packageName} with different content`);
+        this.packageName = packageName;
+        this.changeName = changeName;
+        this.name = 'BundledDeployConflictError';
+    }
+}
+exports.BundledDeployConflictError = BundledDeployConflictError;
+/**
+ * The ledger hash for a change: the sha256 of the deploy script bytes.
+ *
+ * This is deliberately the same value `PgpmMigrate.calculateScriptHash` derives
+ * from `deploy/<change>.sql` under the default `content` hash method, so a
+ * change hashed at package time and the hash recorded/compared at deploy time
+ * agree — the one-shot and per-change paths are interchangeable and idempotent
+ * against each other.
+ */
+function ledgerHashForChange(change) {
+    return change.deploy?.digest ?? null;
+}
+/**
+ * Load a module's executable bundle: its stored artifact when one verifies,
+ * otherwise built from `deploy/` on the fly.
+ *
+ * The artifact is purely an optimization — it removes the read+parse work, not
+ * a capability. Whatever the source, the resulting bundle is byte-identical in
+ * what it executes and in the hashes it records, so a module without an
+ * artifact deploys exactly the same way, just slower.
+ */
+async function loadExecutableBundle(moduleDir) {
+    const stored = (0, artifact_1.readBundleArtifact)(moduleDir);
+    if (stored) {
+        const issues = (0, bundle_1.verifyBundle)(stored);
+        if (issues.length === 0) {
+            return { bundle: stored, source: 'artifact' };
+        }
+        log.warn(`⚠️ Bundle artifact for ${stored.manifest.name} failed verification ` +
+            `(${issues.map(i => i.kind).join(', ')}); rebuilding from deploy/.`);
+    }
+    return { bundle: await (0, artifact_1.buildExecutableBundle)(moduleDir), source: 'packaged' };
+}
+/**
+ * Deploy a module in one shot **and** record the migration ledger — the `fast`
+ * deploy strategy.
+ *
+ * Pending changes' deploy SQL is concatenated and executed as a single
+ * statement (the speed of the old fast path), then one `pgpm_migrate.changes`
+ * row per change is bulk-inserted with the deploy script's own sha256 as
+ * `script_hash` — one round-trip, instead of an `isDeployed` + `readScript` +
+ * `CALL pgpm_migrate.deploy` per change. Because the ledger is written, the
+ * path is idempotent and resumable: re-deploys skip changes whose stored hash
+ * matches, and a same-name/different-content change raises
+ * {@link BundledDeployConflictError} exactly as the per-change path does.
+ *
+ * Returns a {@link BundledDeploySkipReason} (rather than throwing) when it
+ * cannot honour the requested semantics, so the caller falls back to the
+ * per-change migration path. Genuine SQL failures still throw.
+ */
+async function deployModuleFast(moduleDir, options) {
+    if ((options.hashMethod ?? 'content') !== 'content') {
+        return 'unsupported-hash-method';
+    }
+    const { bundle, source } = await loadExecutableBundle(moduleDir);
+    const executable = bundle.changes.filter(change => change.deploy);
+    if (executable.length === 0 || executable.some(change => !change.exec)) {
+        return 'no-executable-sql';
+    }
+    const packageName = bundle.manifest.name;
+    const config = options.database
+        ? { ...options.config, database: options.database }
+        : options.config;
+    // Ensures the pgpm_migrate schema/procedures exist, exactly as the
+    // per-change deploy path does.
+    await new client_1.PgpmMigrate(config, { hashMethod: 'content' }).initialize();
+    const pool = (0, pg_cache_1.getPgPool)(config);
+    const existing = await pool.query('SELECT change_name, script_hash FROM pgpm_migrate.changes WHERE package = $1', [packageName]);
+    const deployedHashes = new Map(existing.rows.map(row => [row.change_name, row.script_hash]));
+    const pending = [];
+    const skipped = [];
+    for (const change of executable) {
+        const hash = ledgerHashForChange(change);
+        const recorded = deployedHashes.get(change.name);
+        if (recorded === undefined) {
+            pending.push(change);
+            continue;
+        }
+        if (recorded !== hash) {
+            throw new BundledDeployConflictError(packageName, change.name);
+        }
+        skipped.push(change.name);
+    }
+    if (pending.length === 0) {
+        log.info(`⚡ ${packageName}: all ${skipped.length} change(s) already deployed.`);
+        return { name: packageName, source, deployed: [], skipped };
+    }
+    const changeNames = pending.map(change => change.name);
+    const hashes = pending.map(change => ledgerHashForChange(change));
+    const depChanges = [];
+    const depRequires = [];
+    for (const change of pending) {
+        for (const dep of new Set(change.dependencies)) {
+            depChanges.push(change.name);
+            depRequires.push(dep.includes(':') ? dep : `${packageName}:${dep}`);
+        }
+    }
+    const deploySql = pending.map(change => change.exec.sql).join('\n');
+    const client = await pool.connect();
+    const useTransaction = options.useTransaction ?? true;
+    try {
+        if (useTransaction)
+            await client.query('BEGIN');
+        if (!options.logOnly) {
+            await client.query(deploySql);
+        }
+        await client.query('INSERT INTO pgpm_migrate.packages (package) VALUES ($1) ON CONFLICT (package) DO NOTHING', [packageName]);
+        await client.query(`WITH input AS (
+         SELECT change_name, script_hash
+         FROM unnest($2::text[], $3::text[]) AS t(change_name, script_hash)
+       ), inserted AS (
+         INSERT INTO pgpm_migrate.changes (change_id, change_name, package, script_hash)
+         SELECT encode(sha256(($1 || change_name || script_hash)::bytea), 'hex'),
+                change_name, $1, script_hash
+         FROM input
+         ON CONFLICT (package, change_name) DO NOTHING
+         RETURNING change_id, change_name
+       ), deps AS (
+         INSERT INTO pgpm_migrate.dependencies (change_id, requires)
+         SELECT inserted.change_id, d.requires
+         FROM unnest($4::text[], $5::text[]) AS d(change_name, requires)
+         JOIN inserted ON inserted.change_name = d.change_name
+         ON CONFLICT DO NOTHING
+         RETURNING change_id
+       )
+       INSERT INTO pgpm_migrate.events (event_type, change_name, package)
+       SELECT 'deploy', change_name, $1 FROM inserted`, [packageName, changeNames, hashes, depChanges, depRequires]);
+        if (useTransaction)
+            await client.query('COMMIT');
+    }
+    catch (error) {
+        if (useTransaction) {
+            try {
+                await client.query('ROLLBACK');
+            }
+            catch {
+                // the connection is already unusable; surface the original error
+            }
+        }
+        throw error;
+    }
+    finally {
+        client.release();
+    }
+    log.success(`⚡ ${packageName}: ${changeNames.length} change(s) ${options.logOnly ? 'logged' : 'deployed'} ` +
+        `from ${source === 'artifact' ? 'bundle artifact' : 'packaged deploy/'} ` +
+        `(${skipped.length} already deployed).`);
+    return { name: packageName, source, deployed: changeNames, skipped };
+}
+/** True when the value is a real deploy result rather than a skip reason. */
+function isBundledDeployResult(value) {
+    return typeof value !== 'string';
+}

package/bundle/index.d.ts

@@ -11,3 +11,5 @@
 export * from '@pgpmjs/bundle';
 export * from './apply';
 export * from './apply-envelope';
+export * from './artifact';
+export * from './deploy-bundled';

package/bundle/index.js

@@ -31,3 +31,7 @@ __exportStar(require("@pgpmjs/bundle"), exports);
 __exportStar(require("./apply"), exports);
 // applyEnvelope: schema apply + data/fixtures part replay for a BundleEnvelope.
 __exportStar(require("./apply-envelope"), exports);
+// The stored `sql/<name>--<version>.bundle.tar.gz` artifact: emit + resolve.
+__exportStar(require("./artifact"), exports);
+// The bundle-backed deploy fast path (one-shot execute + ledger).
+__exportStar(require("./deploy-bundled"), exports);

package/core/class/pgpm.d.ts

@@ -97,6 +97,14 @@ export declare class PgpmPackage {
      * Handles naming collisions by preferring the shortest path.
      */
     listModules(): ModuleMap;
+    /**
+     * Discover apply-spec proxy modules (`pgpm.apply.json`) and synthesize
+     * module-map entries for them so they participate in dependency resolution
+     * by name like any other module. A proxy needs no `.control` or `pgpm.plan`;
+     * its `requires` default to the source module's requires. Control-file
+     * modules win name collisions.
+     */
+    private addApplyModules;
     getModuleMap(): ModuleMap;
     getAvailableModules(): Promise<string[]>;
     getModuleProject(name: string): PgpmPackage;
@@ -271,6 +279,18 @@ export declare class PgpmPackage {
         resolved: string[];
         external: string[];
     }>;
+    /**
+     * Dependency closure for a named module. Proxy (apply-spec) modules have no
+     * pgpm.plan, so they resolve straight off the workspace module map instead
+     * of instantiating a module-rooted package.
+     */
+    private getModuleExtensionsFor;
+    /**
+     * Directory the migration engine should run against for a named module:
+     * the module's own directory, or — for proxy (apply-spec) modules — the
+     * materialized transpiled instance.
+     */
+    private getEffectiveModulePathFor;
     private parsePackageTarget;
     deploy(opts: PgpmOptions, target?: string, recursive?: boolean): Promise<void>;
     /**