@pgpmjs/core 7.14.0 → 7.16.0

package/esm/core/class/pgpm.js

@@ -11,6 +11,7 @@ import { getPgPool } from 'pg-cache';
 import yanse from 'yanse';
 import { resolveEffectiveModulePath } from '../../apply/materialize';
 import { hasApplySpec, readApplySpec } from '../../apply/apply-spec';
+import { isReuseSpec, resolveSharedModuleName } from '../../apply/reuse';
 import { APPLY_SPEC_FILE } from '../../apply/types';
 import { getAvailableExtensions } from '../../extensions/extensions';
 import { generatePlan, writePlan, writePlanFile } from '@pgpmjs/ast/files';
@@ -21,8 +22,9 @@ import { parsePlanFile } from '@pgpmjs/ast/files/plan/parser';
 import { isValidChangeName, isValidTagName, parseReference } from '@pgpmjs/ast/files/plan/validators';
 import { PgpmMigrate } from '../../migrate/client';
 import { getExtensionsAndModules, getExtensionsAndModulesChanges, latestChange, latestChangeAndVersion } from '../../modules/modules';
-import { packageModule } from '../../packaging/package';
+import { deployModuleFast, isBundledDeployResult } from '../../bundle/deploy-bundled';
 import { syncModuleVersions } from '../../packaging/sync-versions';
+import { findExtensionInstall, roleMapFromRoles } from '../../extensions/resolve-install';
 import { resolveDependencies, resolveExtensionDependencies } from '../../resolution/deps';
 import { movePath } from '../../utils/fs';
 import { globPaths, globPattern, toPosixPath } from '../../utils/glob';
@@ -274,13 +276,30 @@ export class PgpmPackage {
             if (moduleMap[name])
                 continue;
             const source = moduleMap[spec.source.module];
-            moduleMap[name] = {
-                path: path
-                    .dirname(path.relative(this.workspacePath, file))
-                    .replace(/\\/g, '/'),
-                requires: spec.requires ?? source?.requires ?? [],
-                version: spec.version ?? source?.version ?? '0.0.1'
-            };
+            const relPath = path
+                .dirname(path.relative(this.workspacePath, file))
+                .replace(/\\/g, '/');
+            const baseRequires = spec.requires ?? source?.requires ?? [];
+            const version = spec.version ?? source?.version ?? '0.0.1';
+            if (isReuseSpec(spec)) {
+                // A reuse proxy expands into two modules that both materialize from
+                // this one directory: a shared module (deployed once, reused across
+                // tenants) and the per-tenant module that `requires` it. Multiple
+                // tenant proxies over the same source/shared/seed config resolve to
+                // the same deterministic shared name, so it is added at most once.
+                const sharedName = resolveSharedModuleName(spec);
+                if (!moduleMap[sharedName]) {
+                    moduleMap[sharedName] = { path: relPath, requires: baseRequires, version };
+                }
+                moduleMap[name] = {
+                    path: relPath,
+                    requires: [...baseRequires, sharedName],
+                    version
+                };
+            }
+            else {
+                moduleMap[name] = { path: relPath, requires: baseRequires, version };
+            }
         }
         return moduleMap;
     }
@@ -1295,12 +1314,6 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
         const log = new Logger('deploy');
         const { name, toChange } = this.parsePackageTarget(target);
         if (recursive) {
-            // Cache for fast deployment
-            const deployFastCache = {};
-            const getCacheKey = (pg, name, database) => {
-                const { host, port, user } = pg ?? {};
-                return `${host}:${port}:${user}:${database}:${name}`;
-            };
             const modules = this.getModuleMap();
             let extensions;
             if (name === null) {
@@ -1311,61 +1324,45 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
                 extensions = this.getModuleExtensionsFor(name);
             }
             const pgPool = getPgPool(opts.pg);
+            const localModules = extensions.resolved.filter((m) => !extensions.external.includes(m));
+            const roleMap = roleMapFromRoles(opts.db?.roles);
             const targetDescription = name === null ? 'all modules' : name;
             log.success(`🚀 Starting deployment to database ${opts.pg.database}...`);
             for (const extension of extensions.resolved) {
                 try {
                     if (extensions.external.includes(extension)) {
-                        const msg = `CREATE EXTENSION IF NOT EXISTS "${extension}" CASCADE;`;
-                        log.info(`📥 Installing external extension: ${extension}`);
-                        await pgPool.query(msg);
+                        const install = findExtensionInstall(extension, localModules, modules, this.workspacePath, { roleMap });
+                        if (install) {
+                            log.info(`📥 Installing external extension (declarative): ${extension}`);
+                            for (const stmt of install.deploy) {
+                                await pgPool.query(stmt);
+                            }
+                        }
+                        else {
+                            const msg = `CREATE EXTENSION IF NOT EXISTS "${extension}" CASCADE;`;
+                            log.info(`📥 Installing external extension: ${extension}`);
+                            await pgPool.query(msg);
+                        }
                     }
                     else {
                         const modulePath = await resolveEffectiveModulePath(extension, resolve(this.workspacePath, modules[extension].path), modules, this.workspacePath);
                         log.info(`📂 Deploying local module: ${extension}`);
-                        if (opts.deployment.fast) {
-                            const cacheKey = getCacheKey(opts.pg, extension, opts.pg.database);
-                            if (opts.deployment.cache && deployFastCache[cacheKey]) {
-                                log.warn(`⚡ Using cached pkg for ${extension}.`);
-                                await pgPool.query(deployFastCache[cacheKey].sql);
+                        if (opts.deployment.fast || opts.deployment.bundled) {
+                            // Fast strategy: one-shot execution plus a bulk-written
+                            // pgpm_migrate ledger, from the module's verified bundle artifact
+                            // when it has one and from `deploy/` when it does not.
+                            const outcome = await deployModuleFast(modulePath, {
+                                config: opts.pg,
+                                logOnly: opts.deployment.logOnly,
+                                useTransaction: opts.deployment.useTx,
+                                hashMethod: opts.deployment.hashMethod
+                            });
+                            if (isBundledDeployResult(outcome)) {
                                 continue;
                             }
-                            let pkg;
-                            try {
-                                pkg = await packageModule(modulePath, {
-                                    usePlan: opts.deployment.usePlan,
-                                    extension: false
-                                });
-                            }
-                            catch (err) {
-                                const errorLines = [];
-                                errorLines.push(`❌ Failed to package module "${extension}" at path: ${modulePath}`);
-                                errorLines.push(`   Module Path: ${modulePath}`);
-                                errorLines.push(`   Workspace Path: ${this.workspacePath}`);
-                                errorLines.push(`   Error Code: ${err.code || 'N/A'}`);
-                                errorLines.push(`   Error Message: ${err.message || 'Unknown error'}`);
-                                if (err.code === 'ENOENT') {
-                                    errorLines.push('💡 Hint: File or directory not found. Check if the module path is correct.');
-                                }
-                                else if (err.code === 'EACCES') {
-                                    errorLines.push('💡 Hint: Permission denied. Check file permissions.');
-                                }
-                                else if (err.message && err.message.includes('pgpm.plan')) {
-                                    errorLines.push('💡 Hint: pgpm.plan file issue. Check if the plan file exists and is valid.');
-                                }
-                                log.error(errorLines.join('\n'));
-                                console.error(err);
-                                throw errors.DEPLOYMENT_FAILED({
-                                    type: 'Deployment',
-                                    module: extension
-                                });
-                            }
-                            await pgPool.query(pkg.sql);
-                            if (opts.deployment.cache) {
-                                deployFastCache[cacheKey] = pkg;
-                            }
+                            log.info(`↩️ Fast deploy unavailable for ${extension} (${outcome}); using per-change path.`);
                         }
-                        else {
+                        {
                             try {
                                 const client = new PgpmMigrate(opts.pg);
                                 // Only apply toChange to the target module, not its dependencies

package/esm/extensions/compile.js

@@ -0,0 +1,109 @@
+const SPECIAL_ROLES = new Set(['public', 'current_user', 'session_user']);
+const quoteIdent = (name) => `"${name.replace(/"/g, '""')}"`;
+const routeRole = (role, roleMap) => {
+    if (!roleMap)
+        return role;
+    if (SPECIAL_ROLES.has(role.toLowerCase()))
+        return role;
+    return roleMap[role] ?? role;
+};
+const grantObjectClause = (on, schema) => {
+    const s = quoteIdent(schema);
+    switch (on) {
+        case 'schema':
+            return `SCHEMA ${s}`;
+        case 'all-tables':
+            return `ALL TABLES IN SCHEMA ${s}`;
+        case 'all-sequences':
+            return `ALL SEQUENCES IN SCHEMA ${s}`;
+        case 'all-functions':
+            return `ALL FUNCTIONS IN SCHEMA ${s}`;
+    }
+};
+const grantSql = (verb, grant, schema, roleMap) => {
+    const roles = (Array.isArray(grant.to) ? grant.to : [grant.to])
+        .map((r) => routeRole(r, roleMap))
+        .join(', ');
+    const obj = grantObjectClause(grant.on, schema);
+    return verb === 'GRANT'
+        ? `GRANT ${grant.privileges} ON ${obj} TO ${roles};`
+        : `REVOKE ${grant.privileges} ON ${obj} FROM ${roles};`;
+};
+/**
+ * Compile a single `provides` declaration into deploy / revert / verify SQL.
+ *
+ * Pure and deterministic: given the same input it returns byte-identical SQL,
+ * with no dynamic `EXECUTE`. This is the nuts-and-bolts primitive; wiring it
+ * into the deploy path (and eventually into real plan changes exempt from
+ * `filterStatements` stripping) composes on top of it.
+ */
+export function compileExtensionInstall(extname, provide, options = {}) {
+    const { roleMap, fixedSchema } = options;
+    const schema = provide.schema === undefined ? null : provide.schema;
+    const relocatable = provide.relocatable ?? true;
+    const ifNotExists = provide.ifNotExists ?? true;
+    const cascade = provide.cascade ?? false;
+    const createSchema = provide.createSchema ?? schema !== null;
+    const dropSchema = provide.dropSchema ?? false;
+    const grants = provide.grants ?? [];
+    // A fixed-schema extension can only be placed at its own fixed schema.
+    if (!relocatable && schema !== null && fixedSchema != null && schema !== fixedSchema) {
+        throw new Error(`Extension "${extname}" is non-relocatable (fixed schema "${fixedSchema}") and cannot be installed into "${schema}".`);
+    }
+    if (grants.length > 0 && schema === null) {
+        throw new Error(`Extension "${extname}" declares grants but no schema; schema-qualified grants require an install schema.`);
+    }
+    const ext = quoteIdent(extname);
+    const deploy = [];
+    const revert = [];
+    const verify = [];
+    if (schema !== null && createSchema) {
+        deploy.push(`CREATE SCHEMA IF NOT EXISTS ${quoteIdent(schema)};`);
+    }
+    const createParts = ['CREATE EXTENSION'];
+    if (ifNotExists)
+        createParts.push('IF NOT EXISTS');
+    createParts.push(ext);
+    if (schema !== null)
+        createParts.push(`WITH SCHEMA ${quoteIdent(schema)}`);
+    if (cascade)
+        createParts.push('CASCADE');
+    deploy.push(`${createParts.join(' ')};`);
+    for (const g of grants) {
+        deploy.push(grantSql('GRANT', g, schema, roleMap));
+    }
+    // Revert: drop grants (best-effort), then extension, then optionally schema.
+    for (const g of [...grants].reverse()) {
+        revert.push(grantSql('REVOKE', g, schema, roleMap));
+    }
+    revert.push(`DROP EXTENSION IF EXISTS ${ext};`);
+    if (schema !== null && createSchema && dropSchema) {
+        revert.push(`DROP SCHEMA IF EXISTS ${quoteIdent(schema)};`);
+    }
+    // Verify: assert the extension exists in the expected namespace.
+    if (schema !== null) {
+        verify.push([
+            'SELECT 1 / count(*)::int AS ok',
+            'FROM pg_catalog.pg_extension e',
+            'JOIN pg_catalog.pg_namespace n ON n.oid = e.extnamespace',
+            `WHERE e.extname = ${quoteLiteral(extname)} AND n.nspname = ${quoteLiteral(schema)};`
+        ].join('\n'));
+    }
+    else {
+        verify.push([
+            'SELECT 1 / count(*)::int AS ok',
+            'FROM pg_catalog.pg_extension e',
+            `WHERE e.extname = ${quoteLiteral(extname)};`
+        ].join('\n'));
+    }
+    return { deploy, revert, verify };
+}
+const quoteLiteral = (s) => `'${s.replace(/'/g, "''")}'`;
+/** Compile every `provides` entry in a manifest, keyed by extension name. */
+export function compileExtensionInstalls(provides, options = {}) {
+    const out = {};
+    for (const [extname, provide] of Object.entries(provides)) {
+        out[extname] = compileExtensionInstall(extname, provide, options);
+    }
+    return out;
+}

package/esm/extensions/index.js

@@ -0,0 +1,4 @@
+export * from './compile';
+export * from './extensions';
+export * from './manifest';
+export * from './resolve-install';

package/esm/extensions/manifest.js

@@ -0,0 +1,139 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+/**
+ * Declarative extension manifest (`extensions.json`) that lives next to a
+ * module's `pgpm.plan` / `.control`. It makes a module self-describing about
+ * the PostgreSQL extensions it relates to:
+ *
+ * - `provides` — the module *is* the extension wrapper: it installs the
+ *   extension into a chosen schema (with grants). This is what replaces the
+ *   dynamic `DO $$ EXECUTE 'CREATE EXTENSION ... SCHEMA x' $$` hack, since a
+ *   literal `CREATE EXTENSION` is stripped at package time.
+ * - `consumes` — the module merely *uses* symbols from an extension installed
+ *   elsewhere (e.g. a bare `crypt()` call) and needs them qualified to wherever
+ *   the extension actually landed. This is the transform/routing side.
+ *
+ * `.control` `requires` still names the extension (dependency ordering is
+ * unchanged); this manifest only adds the *where + grants* that `.control`
+ * cannot express.
+ */
+/** Candidate file names, in precedence order. */
+export const EXTENSIONS_MANIFEST_FILES = ['pgpm.extensions.json', 'extensions.json'];
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const GRANT_TARGETS = new Set([
+    'schema',
+    'all-tables',
+    'all-sequences',
+    'all-functions'
+]);
+/**
+ * Validate + normalize a parsed manifest object. Throws with a precise message
+ * on malformed input so authors get actionable errors rather than silent
+ * misconfiguration.
+ */
+export function validateExtensionsManifest(raw, source = 'extensions.json') {
+    if (!isPlainObject(raw)) {
+        throw new Error(`${source}: manifest must be a JSON object`);
+    }
+    const manifest = {};
+    if (raw.provides !== undefined) {
+        if (!isPlainObject(raw.provides)) {
+            throw new Error(`${source}: "provides" must be an object keyed by extension name`);
+        }
+        const provides = {};
+        for (const [extname, value] of Object.entries(raw.provides)) {
+            provides[extname] = validateProvide(extname, value, source);
+        }
+        manifest.provides = provides;
+    }
+    if (raw.consumes !== undefined) {
+        if (!isPlainObject(raw.consumes)) {
+            throw new Error(`${source}: "consumes" must be an object keyed by extension name`);
+        }
+        const consumes = {};
+        for (const [extname, value] of Object.entries(raw.consumes)) {
+            if (!isPlainObject(value)) {
+                throw new Error(`${source}: consumes."${extname}" must be an object`);
+            }
+            const entry = {};
+            if (value.symbols !== undefined) {
+                if (!Array.isArray(value.symbols) || value.symbols.some((s) => typeof s !== 'string' || !s.trim())) {
+                    throw new Error(`${source}: consumes."${extname}".symbols must be an array of non-empty strings`);
+                }
+                entry.symbols = value.symbols;
+            }
+            consumes[extname] = entry;
+        }
+        manifest.consumes = consumes;
+    }
+    return manifest;
+}
+function validateProvide(extname, value, source) {
+    if (!isPlainObject(value)) {
+        throw new Error(`${source}: provides."${extname}" must be an object`);
+    }
+    const provide = {};
+    if (value.schema !== undefined) {
+        if (value.schema !== null && (typeof value.schema !== 'string' || !value.schema.trim())) {
+            throw new Error(`${source}: provides."${extname}".schema must be a non-empty string or null`);
+        }
+        provide.schema = value.schema;
+    }
+    for (const flag of ['relocatable', 'ifNotExists', 'cascade', 'createSchema', 'dropSchema']) {
+        if (value[flag] !== undefined) {
+            if (typeof value[flag] !== 'boolean') {
+                throw new Error(`${source}: provides."${extname}".${flag} must be a boolean`);
+            }
+            provide[flag] = value[flag];
+        }
+    }
+    if (value.grants !== undefined) {
+        if (!Array.isArray(value.grants)) {
+            throw new Error(`${source}: provides."${extname}".grants must be an array`);
+        }
+        provide.grants = value.grants.map((g, i) => validateGrant(extname, g, i, source));
+    }
+    return provide;
+}
+function validateGrant(extname, value, index, source) {
+    const where = `provides."${extname}".grants[${index}]`;
+    if (!isPlainObject(value)) {
+        throw new Error(`${source}: ${where} must be an object`);
+    }
+    if (typeof value.privileges !== 'string' || !value.privileges.trim()) {
+        throw new Error(`${source}: ${where}.privileges must be a non-empty string`);
+    }
+    if (typeof value.on !== 'string' || !GRANT_TARGETS.has(value.on)) {
+        throw new Error(`${source}: ${where}.on must be one of ${[...GRANT_TARGETS].join(', ')}`);
+    }
+    const toValid = (typeof value.to === 'string' && value.to.trim()) ||
+        (Array.isArray(value.to) && value.to.length > 0 && value.to.every((r) => typeof r === 'string' && r.trim()));
+    if (!toValid) {
+        throw new Error(`${source}: ${where}.to must be a role name or non-empty array of role names`);
+    }
+    return {
+        privileges: value.privileges,
+        on: value.on,
+        to: value.to
+    };
+}
+/**
+ * Read + validate the `extensions.json` (or `pgpm.extensions.json`) manifest for
+ * a module directory. Returns `undefined` when the module declares no manifest.
+ */
+export function readExtensionsManifest(moduleDir) {
+    for (const file of EXTENSIONS_MANIFEST_FILES) {
+        const p = join(moduleDir, file);
+        if (existsSync(p)) {
+            let parsed;
+            try {
+                parsed = JSON.parse(readFileSync(p, 'utf-8'));
+            }
+            catch (e) {
+                throw new Error(`Failed to parse ${file} at ${moduleDir}: ${e.message}`);
+            }
+            return validateExtensionsManifest(parsed, file);
+        }
+    }
+    return undefined;
+}

package/esm/extensions/resolve-install.js

@@ -0,0 +1,70 @@
+import { resolve } from 'path';
+import { compileExtensionInstall } from './compile';
+import { readExtensionsManifest } from './manifest';
+/**
+ * Build a grant role-name map (workspace portability profile) from the
+ * configured {@link RoleMapping}. Keys are the conceptual role names a module
+ * author writes in its manifest (`anonymous`/`authenticated`/`administrator`);
+ * values are the actual role names for this database.
+ */
+export function roleMapFromRoles(roles) {
+    if (!roles)
+        return undefined;
+    const map = {};
+    for (const key of ['anonymous', 'authenticated', 'administrator', 'authenticatedClient']) {
+        const value = roles[key];
+        if (value)
+            map[key] = value;
+    }
+    return Object.keys(map).length > 0 ? map : undefined;
+}
+/**
+ * Find a declarative install for an external extension by scanning the resolved
+ * local modules for an `extensions.json` that `provides` it, and compiling it.
+ *
+ * Returns `undefined` when no module declares the extension — the caller then
+ * falls back to the legacy `CREATE EXTENSION ... CASCADE` (no schema, no grants).
+ * The first declaring module wins; a later contradictory declaration throws.
+ */
+export function findExtensionInstall(extname, localModules, modules, workspacePath, options = {}) {
+    let winner;
+    for (const moduleName of localModules) {
+        const mod = modules[moduleName];
+        if (!mod)
+            continue;
+        const manifest = readExtensionsManifest(resolve(workspacePath, mod.path));
+        const provide = manifest?.provides?.[extname];
+        if (!provide)
+            continue;
+        if (winner && !sameProvide(winner.provide, provide)) {
+            throw new Error(`Conflicting extensions.json "provides" for "${extname}": ` +
+                `module "${winner.moduleName}" and module "${moduleName}" declare incompatible ` +
+                `install schema/grants. Exactly one provider (or identical declarations) is required.`);
+        }
+        if (!winner)
+            winner = { moduleName, provide };
+    }
+    return winner ? compileExtensionInstall(extname, winner.provide, options) : undefined;
+}
+/** Structural equality of two provide declarations (order-insensitive grants). */
+function sameProvide(a, b) {
+    return normalizeProvide(a) === normalizeProvide(b);
+}
+function normalizeProvide(p) {
+    const grants = (p.grants ?? [])
+        .map(g => ({
+        privileges: g.privileges,
+        on: g.on,
+        to: (Array.isArray(g.to) ? [...g.to] : [g.to]).sort()
+    }))
+        .sort((x, y) => JSON.stringify(x).localeCompare(JSON.stringify(y)));
+    return JSON.stringify({
+        schema: p.schema ?? null,
+        relocatable: p.relocatable ?? null,
+        ifNotExists: p.ifNotExists ?? null,
+        cascade: p.cascade ?? null,
+        createSchema: p.createSchema ?? null,
+        dropSchema: p.dropSchema ?? null,
+        grants
+    });
+}

package/esm/index.js

@@ -1,6 +1,6 @@
 export * from './core/class/pgpm';
 export * from './rebundle';
-export * from './extensions/extensions';
+export * from './extensions';
 export * from './modules/modules';
 export * from './packaging/package';
 export * from './packaging/sync-versions';

package/esm/migrate/clean.js

@@ -2,8 +2,7 @@ import { deparse, parse } from 'pgsql-parser';
 const filterStatements = (stmts) => {
     const filteredStmts = stmts.filter(node => {
         const stmt = node.stmt;
-        return stmt && !stmt.hasOwnProperty('TransactionStmt') &&
-            !stmt.hasOwnProperty('CreateExtensionStmt');
+        return stmt && !stmt.hasOwnProperty('TransactionStmt');
     });
     const hasFiltered = filteredStmts.length !== stmts.length;
     return { filteredStmts, hasFiltered };

package/esm/packaging/package.js

@@ -4,6 +4,7 @@ import { relative } from 'path';
 import { deparse } from 'pgsql-deparser';
 import { parse } from 'pgsql-parser';
 import { getExtensionName } from '@pgpmjs/ast/files';
+import { writeBundleArtifact } from '../bundle/artifact';
 import { resolve, resolveWithPlan } from '../resolution/resolve';
 import { transformProps } from './transform';
 const log = new Logger('package');
@@ -78,7 +79,7 @@ export const packageModule = async (packageDir, { usePlan = true, extension = tr
         throw e;
     }
 };
-export const writePackage = async ({ version, extension = true, usePlan = true, packageDir, outputDiff = false, }) => {
+export const writePackage = async ({ version, extension = true, usePlan = true, packageDir, outputDiff = false, bundle = true, }) => {
     const pkgPath = `${packageDir}/package.json`;
     const pkg = require(pkgPath);
     const extname = await getExtensionName(packageDir);
@@ -115,4 +116,10 @@ export const writePackage = async ({ version, extension = true, usePlan = true,
     const writePath = `${outPath}/${sqlFileName}`;
     writeFileSync(writePath, sql);
     log.success(`${relative(packageDir, writePath)} written`);
+    if (bundle) {
+        const bundlePath = await writeBundleArtifact(packageDir, version, {
+            createdWith: '@pgpmjs/core'
+        });
+        log.success(`${relative(packageDir, bundlePath)} written`);
+    }
 };

package/esm/projects/deploy.js

@@ -6,16 +6,11 @@ import * as path from 'path';
 import { getPgPool } from 'pg-cache';
 import { resolveEffectiveModulePath } from '../apply/materialize';
 import { hasApplySpec } from '../apply/apply-spec';
+import { deployModuleFast, isBundledDeployResult } from '../bundle/deploy-bundled';
 import { PgpmPackage } from '../core/class/pgpm';
+import { findExtensionInstall, roleMapFromRoles } from '../extensions';
 import { PgpmMigrate } from '../migrate/client';
-import { packageModule } from '../packaging/package';
 import { resolveExtensionDependencies } from '../resolution/deps';
-// Cache for fast deployment
-const deployFastCache = {};
-const getCacheKey = (pg, name, database) => {
-    const { host, port, user } = pg ?? {};
-    return `${host}:${port}:${user}:${database}:${name}`;
-};
 const log = new Logger('deploy');
 export const deployProject = async (opts, name, database, pkg, toChange) => {
     const mergedOpts = getEnvOptions(opts);
@@ -33,14 +28,28 @@ export const deployProject = async (opts, name, database, pkg, toChange) => {
         ? resolveExtensionDependencies(name, modules)
         : new PgpmPackage(modulePath, { extensionsDir: pkg.extensionsDir }).getModuleExtensions();
     const pgPool = getPgPool({ ...opts.pg, database });
+    // Local modules (in resolve order) that may carry an `extensions.json`
+    // declaring how an external extension should be installed (schema + grants).
+    const localModules = extensions.resolved.filter((m) => !extensions.external.includes(m));
+    const roleMap = roleMapFromRoles(mergedOpts.db?.roles);
     log.success(`🚀 Starting deployment to database ${database}...`);
     for (const extension of extensions.resolved) {
         try {
             if (extensions.external.includes(extension)) {
-                const msg = `CREATE EXTENSION IF NOT EXISTS "${extension}" CASCADE;`;
-                log.info(`📥 Installing external extension: ${extension}`);
-                log.debug(`> ${msg}`);
-                await pgPool.query(msg);
+                const install = findExtensionInstall(extension, localModules, modules, pkg.workspacePath, { roleMap });
+                if (install) {
+                    log.info(`📥 Installing external extension (declarative): ${extension}`);
+                    for (const stmt of install.deploy) {
+                        log.debug(`> ${stmt}`);
+                        await pgPool.query(stmt);
+                    }
+                }
+                else {
+                    const msg = `CREATE EXTENSION IF NOT EXISTS "${extension}" CASCADE;`;
+                    log.info(`📥 Installing external extension: ${extension}`);
+                    log.debug(`> ${msg}`);
+                    await pgPool.query(msg);
+                }
             }
             else {
                 const sourcePath = resolve(pkg.workspacePath, modules[extension].path);
@@ -50,56 +59,25 @@ export const deployProject = async (opts, name, database, pkg, toChange) => {
                 if (modulePath !== sourcePath) {
                     log.info(`🔁 Applying transpiled module (spec in ${sourcePath})`);
                 }
-                if (mergedOpts.deployment.fast) {
-                    // Use fast deployment strategy
-                    const localProject = new PgpmPackage(modulePath, { extensionsDir: pkg.extensionsDir });
-                    const cacheKey = getCacheKey(mergedOpts.pg, extension, database);
-                    if (mergedOpts.deployment.cache && deployFastCache[cacheKey]) {
-                        log.warn(`⚡ Using cached package for ${extension}.`);
-                        await pgPool.query(deployFastCache[cacheKey].sql);
+                // The fast strategy is opt-in; everything else uses the per-change path.
+                if (mergedOpts.deployment.fast || mergedOpts.deployment.bundled) {
+                    // Fast strategy: execute the module in one shot AND record the
+                    // migration ledger, from the pre-built bundle artifact when one
+                    // verifies and from `deploy/` otherwise. If the semantics cannot be
+                    // honoured, fall through to the per-change migration path rather than
+                    // deploying without a ledger.
+                    const outcome = await deployModuleFast(modulePath, {
+                        config: { ...mergedOpts.pg, database },
+                        logOnly: mergedOpts.deployment.logOnly,
+                        useTransaction: mergedOpts.deployment.useTx,
+                        hashMethod: mergedOpts.deployment.hashMethod
+                    });
+                    if (isBundledDeployResult(outcome)) {
                         continue;
                     }
-                    let modulePackage;
-                    try {
-                        modulePackage = await packageModule(localProject.modulePath, {
-                            usePlan: mergedOpts.deployment.usePlan,
-                            extension: false
-                        });
-                    }
-                    catch (err) {
-                        // Build comprehensive error message
-                        const errorLines = [];
-                        errorLines.push(`❌ Failed to package module "${extension}" at path: ${modulePath}`);
-                        errorLines.push(`   Module Path: ${modulePath}`);
-                        errorLines.push(`   Workspace Path: ${pkg.workspacePath}`);
-                        errorLines.push(`   Error Code: ${err.code || 'N/A'}`);
-                        errorLines.push(`   Error Message: ${err.message || 'Unknown error'}`);
-                        // Provide debugging hints
-                        if (err.code === 'ENOENT') {
-                            errorLines.push('💡 Hint: File or directory not found. Check if the module path is correct.');
-                        }
-                        else if (err.code === 'EACCES') {
-                            errorLines.push('💡 Hint: Permission denied. Check file permissions.');
-                        }
-                        else if (err.message && err.message.includes('pgpm.plan')) {
-                            errorLines.push('💡 Hint: pgpm.plan file issue. Check if the plan file exists and is valid.');
-                        }
-                        // Log the consolidated error message
-                        log.error(errorLines.join('\n'));
-                        console.error(err); // Preserve full stack trace
-                        throw errors.DEPLOYMENT_FAILED({
-                            type: 'Deployment',
-                            module: extension
-                        });
-                    }
-                    log.debug(`→ Command: sqitch deploy db:pg:${database}`);
-                    log.debug(`> ${modulePackage.sql}`);
-                    await pgPool.query(modulePackage.sql);
-                    if (mergedOpts.deployment.cache) {
-                        deployFastCache[cacheKey] = modulePackage;
-                    }
+                    log.info(`↩️ Fast deploy unavailable for ${extension} (${outcome}); using per-change path.`);
                 }
-                else {
+                {
                     // Use new migration system
                     log.debug(`→ Command: constructive migrate deploy db:pg:${database}`);
                     try {