@pgpmjs/core 7.13.0 → 7.15.0

package/core/class/pgpm.js

@@ -48,6 +48,10 @@ const parse_package_name_1 = require("parse-package-name");
 const path_1 = __importStar(require("path"));
 const pg_cache_1 = require("pg-cache");
 const yanse_1 = __importDefault(require("yanse"));
+const materialize_1 = require("../../apply/materialize");
+const apply_spec_1 = require("../../apply/apply-spec");
+const reuse_1 = require("../../apply/reuse");
+const types_2 = require("../../apply/types");
 const extensions_1 = require("../../extensions/extensions");
 const files_1 = require("@pgpmjs/ast/files");
 const files_2 = require("@pgpmjs/ast/files");
@@ -57,7 +61,7 @@ const parser_1 = require("@pgpmjs/ast/files/plan/parser");
 const validators_1 = require("@pgpmjs/ast/files/plan/validators");
 const client_1 = require("../../migrate/client");
 const modules_1 = require("../../modules/modules");
-const package_1 = require("../../packaging/package");
+const deploy_bundled_1 = require("../../bundle/deploy-bundled");
 const sync_versions_1 = require("../../packaging/sync-versions");
 const deps_1 = require("../../resolution/deps");
 const fs_2 = require("../../utils/fs");
@@ -281,11 +285,61 @@ class PgpmPackage {
             }
         });
         // Parse the selected control files
-        return Array.from(selectedFiles.entries()).reduce((acc, [moduleName, file]) => {
+        const moduleMap = Array.from(selectedFiles.entries()).reduce((acc, [moduleName, file]) => {
             const module = (0, files_2.parseControlFile)(file, this.workspacePath);
             acc[moduleName] = module;
             return acc;
         }, {});
+        return this.addApplyModules(moduleMap, packageDirs);
+    }
+    /**
+     * 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.
+     */
+    addApplyModules(moduleMap, packageDirs) {
+        const specFiles = [...new Set(packageDirs.flatMap(dir => glob.sync((0, glob_1.globPattern)(dir, `**/${types_2.APPLY_SPEC_FILE}`))))].filter((file) => !/node_modules/.test(file)).sort((a, b) => a.localeCompare(b));
+        for (const file of specFiles) {
+            let spec;
+            try {
+                spec = (0, apply_spec_1.readApplySpec)(path_1.default.dirname(file));
+            }
+            catch (err) {
+                console.warn(`Skipping invalid apply spec ${file}: ${err instanceof Error ? err.message : err}`);
+                continue;
+            }
+            const name = spec.name;
+            if (moduleMap[name])
+                continue;
+            const source = moduleMap[spec.source.module];
+            const relPath = path_1.default
+                .dirname(path_1.default.relative(this.workspacePath, file))
+                .replace(/\\/g, '/');
+            const baseRequires = spec.requires ?? source?.requires ?? [];
+            const version = spec.version ?? source?.version ?? '0.0.1';
+            if ((0, reuse_1.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 = (0, reuse_1.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;
     }
     getModuleMap() {
         if (!this.workspacePath)
@@ -1235,6 +1289,38 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
             external: external
         };
     }
+    /**
+     * 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.
+     */
+    getModuleExtensionsFor(name) {
+        const modules = this.getModuleMap();
+        if (!modules[name]) {
+            throw types_1.errors.MODULE_NOT_FOUND({ name });
+        }
+        const modulePath = (0, path_1.resolve)(this.workspacePath, modules[name].path);
+        if ((0, apply_spec_1.hasApplySpec)(modulePath)) {
+            return (0, deps_1.resolveExtensionDependencies)(name, modules);
+        }
+        return this.getModuleProject(name).getModuleExtensions();
+    }
+    /**
+     * 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.
+     */
+    async getEffectiveModulePathFor(name) {
+        const modules = this.getModuleMap();
+        if (!modules[name]) {
+            throw types_1.errors.MODULE_NOT_FOUND({ name });
+        }
+        const modulePath = (0, path_1.resolve)(this.workspacePath, modules[name].path);
+        if ((0, apply_spec_1.hasApplySpec)(modulePath)) {
+            return (0, materialize_1.resolveEffectiveModulePath)(name, modulePath, modules, this.workspacePath);
+        }
+        return this.getModuleProject(name).getModulePath();
+    }
     parsePackageTarget(target) {
         let name;
         let toChange;
@@ -1266,12 +1352,6 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
         const log = new logger_1.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) {
@@ -1279,8 +1359,7 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
                 extensions = await this.resolveWorkspaceExtensionDependencies();
             }
             else {
-                const moduleProject = this.getModuleProject(name);
-                extensions = moduleProject.getModuleExtensions();
+                extensions = this.getModuleExtensionsFor(name);
             }
             const pgPool = (0, pg_cache_1.getPgPool)(opts.pg);
             const targetDescription = name === null ? 'all modules' : name;
@@ -1293,52 +1372,24 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
                         await pgPool.query(msg);
                     }
                     else {
-                        const modulePath = (0, path_1.resolve)(this.workspacePath, modules[extension].path);
+                        const modulePath = await (0, materialize_1.resolveEffectiveModulePath)(extension, (0, path_1.resolve)(this.workspacePath, modules[extension].path), modules, this.workspacePath);
                         log.info(`📂 Deploying local module: ${extension}`);
-                        if (opts.deployment.fast) {
-                            const localProject = this.getModuleProject(extension);
-                            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 (0, deploy_bundled_1.deployModuleFast)(modulePath, {
+                                config: opts.pg,
+                                logOnly: opts.deployment.logOnly,
+                                useTransaction: opts.deployment.useTx,
+                                hashMethod: opts.deployment.hashMethod
+                            });
+                            if ((0, deploy_bundled_1.isBundledDeployResult)(outcome)) {
                                 continue;
                             }
-                            let pkg;
-                            try {
-                                pkg = await (0, package_1.packageModule)(localProject.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 types_1.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 client_1.PgpmMigrate(opts.pg);
                                 // Only apply toChange to the target module, not its dependencies
@@ -1374,8 +1425,7 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
             if (name === null) {
                 throw types_1.errors.WORKSPACE_OPERATION_ERROR({ operation: 'deployment' });
             }
-            const moduleProject = this.getModuleProject(name);
-            const modulePath = moduleProject.getModulePath();
+            const modulePath = await this.getEffectiveModulePathFor(name);
             if (!modulePath) {
                 throw types_1.errors.PATH_NOT_FOUND({ path: name, type: 'module' });
             }
@@ -1442,7 +1492,7 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
                         }
                     }
                     else {
-                        const modulePath = (0, path_1.resolve)(this.workspacePath, modules[extension].path);
+                        const modulePath = await (0, materialize_1.resolveEffectiveModulePath)(extension, (0, path_1.resolve)(this.workspacePath, modules[extension].path), modules, this.workspacePath);
                         log.info(`📂 Reverting local module: ${extension}`);
                         try {
                             const client = new client_1.PgpmMigrate(opts.pg);
@@ -1475,8 +1525,7 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
             if (name === null) {
                 throw types_1.errors.WORKSPACE_OPERATION_ERROR({ operation: 'revert' });
             }
-            const moduleProject = this.getModuleProject(name);
-            const modulePath = moduleProject.getModulePath();
+            const modulePath = await this.getEffectiveModulePathFor(name);
             if (!modulePath) {
                 throw types_1.errors.PATH_NOT_FOUND({ path: name, type: 'module' });
             }
@@ -1503,8 +1552,7 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
                 extensions = await this.resolveWorkspaceExtensionDependencies();
             }
             else {
-                const moduleProject = this.getModuleProject(name);
-                extensions = moduleProject.getModuleExtensions();
+                extensions = this.getModuleExtensionsFor(name);
             }
             const pgPool = (0, pg_cache_1.getPgPool)(opts.pg);
             const targetDescription = name === null ? 'all modules' : name;
@@ -1517,7 +1565,7 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
                         await pgPool.query(query, [extension]);
                     }
                     else {
-                        const modulePath = (0, path_1.resolve)(this.workspacePath, modules[extension].path);
+                        const modulePath = await (0, materialize_1.resolveEffectiveModulePath)(extension, (0, path_1.resolve)(this.workspacePath, modules[extension].path), modules, this.workspacePath);
                         log.info(`📂 Verifying local module: ${extension}`);
                         try {
                             const client = new client_1.PgpmMigrate(opts.pg);
@@ -1549,8 +1597,7 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
             if (name === null) {
                 throw types_1.errors.WORKSPACE_OPERATION_ERROR({ operation: 'verification' });
             }
-            const moduleProject = this.getModuleProject(name);
-            const modulePath = moduleProject.getModulePath();
+            const modulePath = await this.getEffectiveModulePathFor(name);
             if (!modulePath) {
                 throw types_1.errors.PATH_NOT_FOUND({ path: name, type: 'module' });
             }

package/esm/apply/apply-spec.js

@@ -0,0 +1,160 @@
+import { existsSync, readFileSync } from 'fs';
+import { basename, dirname, join } from 'path';
+import { APPLY_SPEC_FILE } from './types';
+/** Whether a module directory is an apply-spec proxy module. */
+export function hasApplySpec(moduleDir) {
+    return existsSync(join(moduleDir, APPLY_SPEC_FILE));
+}
+/**
+ * Read, validate, and normalize a proxy module's `pgpm.apply.json`.
+ *
+ * Normalizations: `source` is expanded to its object form and `name` defaults
+ * to the proxy directory's name.
+ *
+ * @throws when the file is missing, unparsable, or structurally invalid.
+ */
+export function readApplySpec(moduleDir) {
+    const specPath = join(moduleDir, APPLY_SPEC_FILE);
+    if (!existsSync(specPath)) {
+        throw new Error(`No ${APPLY_SPEC_FILE} found in ${moduleDir}`);
+    }
+    return parseApplySpec(readFileSync(specPath, 'utf-8'), specPath);
+}
+/** In-memory core of {@link readApplySpec}. */
+export function parseApplySpec(content, specPath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (err) {
+        throw new Error(`Failed to parse ${specPath}: ${err instanceof Error ? err.message : err}`);
+    }
+    const source = typeof parsed?.source === 'string' ? { module: parsed.source } : parsed?.source;
+    if (!source || typeof source.module !== 'string' || !source.module) {
+        throw new Error(`${specPath}: "source" (source module name, or { "module": ... }) is required`);
+    }
+    const isSchemaMap = (value) => typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.keys(value).length > 0 &&
+        Object.entries(value).every(([from, to]) => typeof from === 'string' && typeof to === 'string' && !!from && !!to);
+    const hasSchemas = parsed.schemas !== undefined;
+    if (hasSchemas && !isSchemaMap(parsed.schemas)) {
+        throw new Error(`${specPath}: "schemas" must be a non-empty string → string map`);
+    }
+    const ROUTE_KINDS = ['table', 'view', 'function', 'procedure', 'type'];
+    const hasRoute = parsed.route !== undefined;
+    if (hasRoute) {
+        if (!Array.isArray(parsed.route) || parsed.route.length === 0) {
+            throw new Error(`${specPath}: "route" must be a non-empty array of route entries`);
+        }
+        for (const entry of parsed.route) {
+            if (!entry ||
+                typeof entry !== 'object' ||
+                typeof entry.fromSchema !== 'string' ||
+                !entry.fromSchema ||
+                typeof entry.name !== 'string' ||
+                !entry.name ||
+                typeof entry.toSchema !== 'string' ||
+                !entry.toSchema ||
+                !ROUTE_KINDS.includes(entry.kind)) {
+                throw new Error(`${specPath}: each "route" entry needs { fromSchema, kind (${ROUTE_KINDS.join('|')}), name, toSchema } as non-empty strings`);
+            }
+        }
+    }
+    const hasReuse = parsed.reuse !== undefined;
+    if (hasReuse) {
+        const reuse = parsed.reuse;
+        if (typeof reuse !== 'object' || reuse === null || Array.isArray(reuse)) {
+            throw new Error(`${specPath}: "reuse" must be an object`);
+        }
+        if (!isSchemaMap(reuse.sharedSchema)) {
+            throw new Error(`${specPath}: "reuse.sharedSchema" must be a non-empty string → string map`);
+        }
+        if (!Array.isArray(reuse.perTenant) || reuse.perTenant.length === 0) {
+            throw new Error(`${specPath}: "reuse.perTenant" must be a non-empty array of seed objects`);
+        }
+        for (const seed of reuse.perTenant) {
+            if (!seed ||
+                typeof seed !== 'object' ||
+                typeof seed.fromSchema !== 'string' ||
+                !seed.fromSchema ||
+                typeof seed.name !== 'string' ||
+                !seed.name ||
+                !ROUTE_KINDS.includes(seed.kind)) {
+                throw new Error(`${specPath}: each "reuse.perTenant" seed needs { fromSchema, kind (${ROUTE_KINDS.join('|')}), name } as non-empty strings`);
+            }
+        }
+        if (reuse.sharedName !== undefined && (typeof reuse.sharedName !== 'string' || !reuse.sharedName)) {
+            throw new Error(`${specPath}: "reuse.sharedName" must be a non-empty string`);
+        }
+        if (!hasSchemas) {
+            throw new Error(`${specPath}: "reuse" requires "schemas" (the per-tenant source → target schema map)`);
+        }
+        for (const seed of reuse.perTenant) {
+            if (!(seed.fromSchema in parsed.schemas)) {
+                throw new Error(`${specPath}: "reuse.perTenant" seed schema "${seed.fromSchema}" has no per-tenant ` +
+                    `target in "schemas"`);
+            }
+            if (!(seed.fromSchema in reuse.sharedSchema)) {
+                throw new Error(`${specPath}: "reuse.perTenant" seed schema "${seed.fromSchema}" has no shared ` +
+                    `target in "reuse.sharedSchema"`);
+            }
+        }
+    }
+    const hasExtensions = parsed.extensions !== undefined;
+    if (hasExtensions) {
+        const ext = parsed.extensions;
+        if (typeof ext !== 'object' || ext === null || Array.isArray(ext)) {
+            throw new Error(`${specPath}: "extensions" must be an object`);
+        }
+        const isSchemaOrNull = (v) => v === null || (typeof v === 'string' && !!v);
+        const hasRoutes = ext.routes !== undefined;
+        if (hasRoutes) {
+            if (typeof ext.routes !== 'object' || ext.routes === null || Array.isArray(ext.routes)) {
+                throw new Error(`${specPath}: "extensions.routes" must be an object keyed by extension name`);
+            }
+            for (const [name, route] of Object.entries(ext.routes)) {
+                if (!route || typeof route !== 'object' || !isSchemaOrNull(route.to)) {
+                    throw new Error(`${specPath}: "extensions.routes.${name}" must be { to: schema | null, from?: (string|null)[] }`);
+                }
+            }
+        }
+        else if (!('toSchema' in ext)) {
+            throw new Error(`${specPath}: "extensions" needs "toSchema" (schema | null) or "routes"`);
+        }
+        else if (!isSchemaOrNull(ext.toSchema)) {
+            throw new Error(`${specPath}: "extensions.toSchema" must be a non-empty string or null`);
+        }
+        if (ext.only !== undefined && (!Array.isArray(ext.only) || ext.only.some((e) => typeof e !== 'string' || !e))) {
+            throw new Error(`${specPath}: "extensions.only" must be an array of extension names`);
+        }
+        if (ext.serverVersion !== undefined && typeof ext.serverVersion !== 'number') {
+            throw new Error(`${specPath}: "extensions.serverVersion" must be a number`);
+        }
+    }
+    const hasRoles = parsed.roles !== undefined;
+    if (hasRoles && !isSchemaMap(parsed.roles)) {
+        throw new Error(`${specPath}: "roles" must be a non-empty string → string map`);
+    }
+    if (!hasSchemas && !hasRoute && !hasExtensions && !hasRoles) {
+        throw new Error(`${specPath}: at least one of "schemas", "route", "extensions", or "roles" is required`);
+    }
+    const name = parsed.name ?? basename(dirname(specPath));
+    if (typeof name !== 'string' || !name) {
+        throw new Error(`${specPath}: "name" must be a non-empty string`);
+    }
+    if (name === source.module) {
+        throw new Error(`${specPath}: apply module "${name}" cannot apply itself`);
+    }
+    const requires = parsed.requires;
+    if (requires !== undefined &&
+        (!Array.isArray(requires) || requires.some((r) => typeof r !== 'string' || !r))) {
+        throw new Error(`${specPath}: "requires" must be an array of module names`);
+    }
+    if (requires?.includes(source.module)) {
+        throw new Error(`${specPath}: "requires" must not include the source module "${source.module}" — ` +
+            `it is source material, not a runtime dependency`);
+    }
+    return { ...parsed, name, source, requires };
+}

package/esm/apply/index.js

@@ -0,0 +1,4 @@
+export * from './materialize';
+export * from './apply-spec';
+export * from './reuse';
+export * from './types';

package/esm/apply/materialize.js

@@ -0,0 +1,129 @@
+import { mkdtempSync } from 'fs';
+import { tmpdir } from 'os';
+import { join, resolve } from 'path';
+import { bundleFromModule, materializeBundle, transpileBundle, verifyBundle } from '@pgpmjs/bundle';
+import { loadModule, makeSchemaTranspiler } from '@pgpmjs/transform';
+import { hasApplySpec, readApplySpec } from './apply-spec';
+import { isReuseSpec, materializeReuseModule, resolveSharedModuleName } from './reuse';
+// Functions that take a bare schema name as a string-literal first argument.
+// The AST pass only remaps dotted literals ('schema.object'); these helpers
+// (ubiquitous in verify scripts) name the schema alone, so a string-level
+// pre-pass remaps them.
+const SCHEMA_NAME_LITERAL_FUNCS = ['verify_schema', 'has_schema_privilege'];
+const schemaNameLiteralPass = (content, schemaMapping) => {
+    const pattern = new RegExp(`\\b(${SCHEMA_NAME_LITERAL_FUNCS.join('|')})\\s*\\(\\s*'([^']+)'`, 'gi');
+    return content.replace(pattern, (match, _fn, schema) => {
+        const mapped = schemaMapping.get(schema);
+        return mapped ? match.replace(`'${schema}'`, `'${mapped}'`) : match;
+    });
+};
+/**
+ * Transpile a source module per an apply spec and materialize the result as a
+ * deployable module directory carrying the instance's identity.
+ *
+ * Pure pipeline over existing primitives: `bundleFromModule` →
+ * `transpileBundle(makeSchemaTranspiler)` → `verifyBundle` →
+ * `materializeBundle`. Deterministic — identical source + spec always produce
+ * an identical bundle (and digest), which is what makes verify/revert able to
+ * re-derive the exact deployed artifact.
+ */
+export async function materializeApplyModule(options) {
+    const { sourceDir, spec } = options;
+    const instanceName = spec.name;
+    // the schema transpiler's SQL/PLpgSQL parser is WASM-backed and needs a
+    // one-time async init (idempotent)
+    await loadModule();
+    const source = bundleFromModule(sourceDir);
+    if (spec.source.bundleDigest && spec.source.bundleDigest !== source.manifest.digest) {
+        throw new Error(`Apply spec for "${instanceName}" pins source bundle digest ${spec.source.bundleDigest}, ` +
+            `but the installed source "${spec.source.module}" hashes to ${source.manifest.digest}. ` +
+            `Reinstall the pinned version or update the spec.`);
+    }
+    // Every distinct target schema is treated as "may already exist": apply
+    // deploys into consumer-chosen namespaces that can pre-exist (a shared schema,
+    // another tenant), so `CREATE SCHEMA` is emitted idempotently. This is what
+    // lets the same source apply cleanly whether or not the destination exists.
+    const targetSchemas = [
+        ...new Set([
+            ...Object.values(spec.schemas ?? {}),
+            ...(spec.route ?? []).map(r => r.toSchema)
+        ])
+    ];
+    const { renameChange, transformScript, result } = makeSchemaTranspiler({
+        schemaMap: spec.schemas,
+        routes: spec.route,
+        extensions: spec.extensions,
+        roles: spec.roles,
+        transform: {
+            prePasses: [schemaNameLiteralPass],
+            assumeSchemasExist: targetSchemas
+        }
+    });
+    const transpiled = transpileBundle(source, {
+        renameChange,
+        transformScript,
+        renameModule: instanceName,
+        provenance: {
+            appliedFrom: spec.source.module,
+            ...(spec.source.package ? { sourcePackage: spec.source.package } : {}),
+            ...(spec.source.version ? { sourceVersion: spec.source.version } : {})
+        }
+    });
+    if (result.errors.length > 0) {
+        const detail = result.errors.map(e => `${e.file}: ${e.error}`).join('; ');
+        throw new Error(`Apply transpile of "${spec.source.module}" as "${instanceName}" failed: ${detail}`);
+    }
+    const issues = verifyBundle(transpiled);
+    if (issues.length > 0) {
+        throw new Error(`Transpiled bundle for "${instanceName}" failed integrity verification: ` +
+            issues.map(i => i.kind).join(', '));
+    }
+    const outDir = options.outDir ?? mkdtempSync(join(tmpdir(), `pgpm-apply-${instanceName}-`));
+    materializeBundle(transpiled, outDir);
+    return { bundle: transpiled, outDir };
+}
+// One materialization per proxy path per process: the pipeline is
+// deterministic, so re-deriving within a process is pure waste.
+const materializedCache = new Map();
+/**
+ * Deploy-path dispatch seam: given a resolved module's directory, return the
+ * directory the migration engine should actually run against.
+ *
+ * Non-proxy modules pass through unchanged. For proxy modules (directories
+ * carrying a `pgpm.apply.json`), the source module is located in the workspace
+ * module map, transpiled per the spec, and materialized to a cached temp dir
+ * carrying the instance's identity.
+ */
+export async function resolveEffectiveModulePath(moduleName, modulePath, moduleMap, workspacePath) {
+    if (!hasApplySpec(modulePath))
+        return modulePath;
+    // A reuse proxy resolves under two names (shared + per-tenant) from one
+    // directory, so the cache is keyed by the requested module name too.
+    const cacheKey = `${modulePath}::${moduleName}`;
+    const cached = materializedCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const spec = readApplySpec(modulePath);
+    const sourceModule = moduleMap[spec.source.module];
+    if (!sourceModule) {
+        throw new Error(`Apply spec in "${moduleName}" references source module "${spec.source.module}", ` +
+            `which was not found in the workspace. Run \`pgpm install\` to install it` +
+            (spec.source.package ? ` (${spec.source.package})` : '') +
+            `.`);
+    }
+    const sourceDir = resolve(workspacePath, sourceModule.path);
+    if (isReuseSpec(spec)) {
+        const result = await materializeReuseModule({ sourceDir, spec });
+        materializedCache.set(`${modulePath}::${result.sharedName}`, result.shared.outDir);
+        materializedCache.set(`${modulePath}::${result.perTenantName}`, result.perTenant.outDir);
+        const outDir = moduleName === resolveSharedModuleName(spec) ? result.shared.outDir : result.perTenant.outDir;
+        return outDir;
+    }
+    const { outDir } = await materializeApplyModule({ sourceDir, spec });
+    materializedCache.set(cacheKey, outDir);
+    return outDir;
+}
+/** Test seam: clear the per-process materialization cache. */
+export function clearApplyMaterializationCache() {
+    materializedCache.clear();
+}