@pgpmjs/core 7.15.0 → 7.17.0

package/apply/apply-spec.js

@@ -54,16 +54,21 @@ function parseApplySpec(content, specPath) {
             throw new Error(`${specPath}: "route" must be a non-empty array of route entries`);
         }
         for (const entry of parsed.route) {
+            const validToSchema = entry?.toSchema === undefined ||
+                entry.toSchema === null ||
+                (typeof entry.toSchema === 'string' && !!entry.toSchema);
+            const validToName = entry?.toName === undefined || (typeof entry.toName === 'string' && !!entry.toName);
             if (!entry ||
                 typeof entry !== 'object' ||
                 typeof entry.fromSchema !== 'string' ||
                 !entry.fromSchema ||
                 typeof entry.name !== 'string' ||
                 !entry.name ||
-                typeof entry.toSchema !== 'string' ||
-                !entry.toSchema ||
+                !validToSchema ||
+                !validToName ||
+                (entry.toSchema === undefined && entry.toName === undefined) ||
                 !ROUTE_KINDS.includes(entry.kind)) {
-                throw new Error(`${specPath}: each "route" entry needs { fromSchema, kind (${ROUTE_KINDS.join('|')}), name, toSchema } as non-empty strings`);
+                throw new Error(`${specPath}: each "route" entry needs { fromSchema, kind (${ROUTE_KINDS.join('|')}), name } plus "toSchema" (schema | null) and/or "toName"`);
             }
         }
     }
@@ -142,8 +147,20 @@ function parseApplySpec(content, specPath) {
     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 hasExclude = parsed.exclude !== undefined;
+    if (hasExclude) {
+        const ex = parsed.exclude;
+        if (typeof ex !== 'object' ||
+            ex === null ||
+            Array.isArray(ex) ||
+            !Array.isArray(ex.schemas) ||
+            ex.schemas.length === 0 ||
+            ex.schemas.some((s) => typeof s !== 'string' || !s)) {
+            throw new Error(`${specPath}: "exclude" must be { schemas: [non-empty schema names] }`);
+        }
+    }
+    if (!hasSchemas && !hasRoute && !hasExtensions && !hasRoles && !hasExclude) {
+        throw new Error(`${specPath}: at least one of "schemas", "route", "extensions", "roles", or "exclude" is required`);
     }
     const name = parsed.name ?? (0, path_1.basename)((0, path_1.dirname)(specPath));
     if (typeof name !== 'string' || !name) {

package/apply/index.d.ts

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

package/apply/index.js

@@ -15,6 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./materialize"), exports);
+__exportStar(require("./profile"), exports);
 __exportStar(require("./apply-spec"), exports);
 __exportStar(require("./reuse"), exports);
 __exportStar(require("./types"), exports);

package/apply/materialize.js

@@ -8,7 +8,9 @@ const os_1 = require("os");
 const path_1 = require("path");
 const bundle_1 = require("@pgpmjs/bundle");
 const transform_1 = require("@pgpmjs/transform");
+const slice_1 = require("@pgpmjs/slice");
 const apply_spec_1 = require("./apply-spec");
+const profile_1 = require("./profile");
 const reuse_1 = require("./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
@@ -22,6 +24,48 @@ const schemaNameLiteralPass = (content, schemaMapping) => {
         return mapped ? match.replace(`'${schema}'`, `'${mapped}'`) : match;
     });
 };
+/**
+ * Build the per-script subsystem stripper for an `exclude` spec, verifying
+ * cascade safety across the *whole* source bundle first: every deploy-script
+ * reference into an excluded schema (FKs, calls, policy predicates) must have
+ * a rebind route, or materialization refuses with each unsatisfied reference
+ * named. Checking bundle-wide (not per script) is what catches cross-change
+ * dependencies on the excluded subsystem.
+ */
+function makeSubsystemStripper(source, spec, instanceName) {
+    const selector = { schemas: spec.exclude.schemas };
+    const rebinds = (0, transform_1.buildSchemaRouter)({ schemaMap: spec.schemas, routes: spec.route });
+    const fullDeploySql = source.changes
+        .map(c => c.deploy?.sql ?? '')
+        .filter(Boolean)
+        .join('\n');
+    const analysis = (0, slice_1.excludeSubsystem)(fullDeploySql, selector, { rebinds });
+    if (analysis.unsatisfied.length > 0) {
+        const detail = [
+            ...new Set(analysis.unsatisfied.map(u => `${u.object.schema}.${u.object.name}${u.fk ? ' (foreign key target)' : ''}`))
+        ].join(', ');
+        throw new Error(`Cannot exclude schema(s) ${spec.exclude.schemas.join(', ')} from ` +
+            `"${spec.source.module}" as "${instanceName}": surviving statements still reference ` +
+            `${detail} with no route/rebind target. Add "route" entries substituting each ` +
+            `referenced object, or keep the subsystem.`);
+    }
+    // A change whose deploy consists entirely of subsystem statements (plus
+    // transaction control) is excluded *as a change*: its verify/revert scripts
+    // target dropped objects the classifier can't always see (bare DROPs,
+    // catalog probes), so all three scripts are blanked together.
+    const excludedChanges = new Set();
+    for (const change of source.changes) {
+        if (!change.deploy)
+            continue;
+        const stripped = (0, slice_1.stripSubsystemSql)(change.deploy.sql, selector);
+        const survivors = stripped.result.kept.filter(i => !stripped.dropped.includes(i) && stripped.result.statements[i].nodeTag !== 'TransactionStmt');
+        if (stripped.dropped.length > 0 && survivors.length === 0) {
+            excludedChanges.add(change.name);
+        }
+    }
+    const strip = (sql, change) => excludedChanges.has(change) ? (0, slice_1.blankScriptSql)(sql) : (0, slice_1.stripSubsystemSql)(sql, selector).sql;
+    return { strip, excludedChanges };
+}
 /**
  * Transpile a source module per an apply spec and materialize the result as a
  * deployable module directory carrying the instance's identity.
@@ -51,9 +95,14 @@ async function materializeApplyModule(options) {
     const targetSchemas = [
         ...new Set([
             ...Object.values(spec.schemas ?? {}),
-            ...(spec.route ?? []).map(r => r.toSchema)
+            ...(spec.route ?? [])
+                .map(r => r.toSchema)
+                .filter((s) => typeof s === 'string')
         ])
     ];
+    const stripSubsystem = spec.exclude
+        ? makeSubsystemStripper(source, spec, instanceName)
+        : undefined;
     const { renameChange, transformScript, result } = (0, transform_1.makeSchemaTranspiler)({
         schemaMap: spec.schemas,
         routes: spec.route,
@@ -64,9 +113,15 @@ async function materializeApplyModule(options) {
             assumeSchemasExist: targetSchemas
         }
     });
+    // Excluded changes keep their source identity (an emptied tombstone) —
+    // renaming them into the replacement provider's namespace would be a lie.
     const transpiled = (0, bundle_1.transpileBundle)(source, {
-        renameChange,
-        transformScript,
+        renameChange: stripSubsystem
+            ? (name) => (stripSubsystem.excludedChanges.has(name) ? name : renameChange(name))
+            : renameChange,
+        transformScript: stripSubsystem
+            ? (sql, ctx) => transformScript(stripSubsystem.strip(sql, ctx.change), ctx)
+            : transformScript,
         renameModule: instanceName,
         provenance: {
             appliedFrom: spec.source.module,
@@ -108,7 +163,7 @@ async function resolveEffectiveModulePath(moduleName, modulePath, moduleMap, wor
     const cached = materializedCache.get(cacheKey);
     if (cached)
         return cached;
-    const spec = (0, apply_spec_1.readApplySpec)(modulePath);
+    const spec = (0, profile_1.resolveEffectiveApplySpec)((0, apply_spec_1.readApplySpec)(modulePath), (0, profile_1.loadWorkspaceRoutingProfile)(workspacePath));
     const sourceModule = moduleMap[spec.source.module];
     if (!sourceModule) {
         throw new Error(`Apply spec in "${moduleName}" references source module "${spec.source.module}", ` +

package/apply/profile.d.ts

@@ -0,0 +1,14 @@
+import { PgpmRoutingProfile } from '@pgpmjs/types';
+import { ResolvedApplySpec } from './types';
+/**
+ * Load the workspace-level routing profile (the `portability` field of the
+ * workspace `pgpm.json` / `pgpm.config.js`). Returns `undefined` when the
+ * workspace has no config file or no profile.
+ */
+export declare function loadWorkspaceRoutingProfile(workspacePath: string): PgpmRoutingProfile | undefined;
+/**
+ * Resolve the routing profile effective for one apply spec: defaults →
+ * workspace `portability` → the spec's own routing keys, merged per key
+ * (inner scope wins; see {@link mergeRoutingProfiles}).
+ */
+export declare function resolveEffectiveApplySpec(spec: ResolvedApplySpec, workspaceProfile?: PgpmRoutingProfile): ResolvedApplySpec;

package/apply/profile.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadWorkspaceRoutingProfile = loadWorkspaceRoutingProfile;
+exports.resolveEffectiveApplySpec = resolveEffectiveApplySpec;
+const env_1 = require("@pgpmjs/env");
+const types_1 = require("@pgpmjs/types");
+/**
+ * Load the workspace-level routing profile (the `portability` field of the
+ * workspace `pgpm.json` / `pgpm.config.js`). Returns `undefined` when the
+ * workspace has no config file or no profile.
+ */
+function loadWorkspaceRoutingProfile(workspacePath) {
+    let config;
+    try {
+        config = (0, env_1.loadConfigSyncFromDir)(workspacePath);
+    }
+    catch {
+        return undefined;
+    }
+    return config?.portability;
+}
+/**
+ * Resolve the routing profile effective for one apply spec: defaults →
+ * workspace `portability` → the spec's own routing keys, merged per key
+ * (inner scope wins; see {@link mergeRoutingProfiles}).
+ */
+function resolveEffectiveApplySpec(spec, workspaceProfile) {
+    if (!workspaceProfile)
+        return spec;
+    const merged = (0, types_1.mergeRoutingProfiles)(workspaceProfile, {
+        schemas: spec.schemas,
+        route: spec.route,
+        extensions: spec.extensions,
+        roles: spec.roles,
+        exclude: spec.exclude
+    });
+    return { ...spec, ...merged };
+}

package/apply/types.d.ts

@@ -10,6 +10,7 @@
  * module in memory and runs the normal migration path against the result;
  * transpiled code is never committed.
  */
+import { PgpmExtensionsRouting, PgpmRolesRouting, PgpmRouteEntry, PgpmRoutingProfile } from '@pgpmjs/types';
 /** 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. */
@@ -33,22 +34,11 @@ export interface ApplySpecSource {
     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.
+ * An object-level route in a `pgpm.apply.json` spec. The shared
+ * routing-profile shape ({@link PgpmRouteEntry} from `@pgpmjs/types`), usable
+ * at both the workspace and per-import scopes.
  */
-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;
-}
+export type ApplyRouteEntry = PgpmRouteEntry;
 /**
  * A per-tenant seed object in a reuse spec: the objects that must be
  * materialized once *per tenant*. `@pgpmjs/slice`'s `partitionModule` starts
@@ -89,41 +79,20 @@ export interface ApplyReuseSpec {
 }
 /**
  * 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.
+ * instance should resolve the symbols extensions provide. The shared
+ * routing-profile shape ({@link PgpmExtensionsRouting} from `@pgpmjs/types`);
+ * 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;
-}
+export type ApplyExtensionsSpec = PgpmExtensionsRouting;
 /** 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 {
+export type ApplyRolesSpec = PgpmRolesRouting;
+/**
+ * The parsed, normalized `pgpm.apply.json` spec: a source-module reference
+ * plus a per-import routing profile ({@link PgpmRoutingProfile}). The routing
+ * keys override the workspace `portability` profile per key (inner scope
+ * wins).
+ */
+export interface PgpmApplySpec extends PgpmRoutingProfile {
     /**
      * Module name this instance is deployed as. Defaults to the proxy
      * directory's name.
@@ -131,33 +100,12 @@ export interface PgpmApplySpec {
     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.

package/bundle/artifact.d.ts

@@ -15,8 +15,8 @@ export declare function bundleArtifactFileName(name: string, version: string): s
 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`).
+ * snapshot plus, per change, the deploy SQL with transaction-control
+ * 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

package/bundle/artifact.js

@@ -52,8 +52,8 @@ function resolveBundleArtifactPath(moduleDir) {
 }
 /**
  * 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`).
+ * snapshot plus, per change, the deploy SQL with transaction-control
+ * 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

package/core/class/pgpm.js

@@ -63,6 +63,7 @@ const client_1 = require("../../migrate/client");
 const modules_1 = require("../../modules/modules");
 const deploy_bundled_1 = require("../../bundle/deploy-bundled");
 const sync_versions_1 = require("../../packaging/sync-versions");
+const resolve_install_1 = require("../../extensions/resolve-install");
 const deps_1 = require("../../resolution/deps");
 const fs_2 = require("../../utils/fs");
 const glob_1 = require("../../utils/glob");
@@ -1362,14 +1363,25 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
                 extensions = this.getModuleExtensionsFor(name);
             }
             const pgPool = (0, pg_cache_1.getPgPool)(opts.pg);
+            const localModules = extensions.resolved.filter((m) => !extensions.external.includes(m));
+            const roleMap = (0, resolve_install_1.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 = (0, resolve_install_1.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 (0, materialize_1.resolveEffectiveModulePath)(extension, (0, path_1.resolve)(this.workspacePath, modules[extension].path), modules, this.workspacePath);

package/esm/apply/apply-spec.js

@@ -49,16 +49,21 @@ export function parseApplySpec(content, specPath) {
             throw new Error(`${specPath}: "route" must be a non-empty array of route entries`);
         }
         for (const entry of parsed.route) {
+            const validToSchema = entry?.toSchema === undefined ||
+                entry.toSchema === null ||
+                (typeof entry.toSchema === 'string' && !!entry.toSchema);
+            const validToName = entry?.toName === undefined || (typeof entry.toName === 'string' && !!entry.toName);
             if (!entry ||
                 typeof entry !== 'object' ||
                 typeof entry.fromSchema !== 'string' ||
                 !entry.fromSchema ||
                 typeof entry.name !== 'string' ||
                 !entry.name ||
-                typeof entry.toSchema !== 'string' ||
-                !entry.toSchema ||
+                !validToSchema ||
+                !validToName ||
+                (entry.toSchema === undefined && entry.toName === undefined) ||
                 !ROUTE_KINDS.includes(entry.kind)) {
-                throw new Error(`${specPath}: each "route" entry needs { fromSchema, kind (${ROUTE_KINDS.join('|')}), name, toSchema } as non-empty strings`);
+                throw new Error(`${specPath}: each "route" entry needs { fromSchema, kind (${ROUTE_KINDS.join('|')}), name } plus "toSchema" (schema | null) and/or "toName"`);
             }
         }
     }
@@ -137,8 +142,20 @@ export function parseApplySpec(content, specPath) {
     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 hasExclude = parsed.exclude !== undefined;
+    if (hasExclude) {
+        const ex = parsed.exclude;
+        if (typeof ex !== 'object' ||
+            ex === null ||
+            Array.isArray(ex) ||
+            !Array.isArray(ex.schemas) ||
+            ex.schemas.length === 0 ||
+            ex.schemas.some((s) => typeof s !== 'string' || !s)) {
+            throw new Error(`${specPath}: "exclude" must be { schemas: [non-empty schema names] }`);
+        }
+    }
+    if (!hasSchemas && !hasRoute && !hasExtensions && !hasRoles && !hasExclude) {
+        throw new Error(`${specPath}: at least one of "schemas", "route", "extensions", "roles", or "exclude" is required`);
     }
     const name = parsed.name ?? basename(dirname(specPath));
     if (typeof name !== 'string' || !name) {

package/esm/apply/index.js

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

package/esm/apply/materialize.js

@@ -2,8 +2,10 @@ 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 { buildSchemaRouter, loadModule, makeSchemaTranspiler } from '@pgpmjs/transform';
+import { blankScriptSql, excludeSubsystem, stripSubsystemSql } from '@pgpmjs/slice';
 import { hasApplySpec, readApplySpec } from './apply-spec';
+import { loadWorkspaceRoutingProfile, resolveEffectiveApplySpec } from './profile';
 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
@@ -17,6 +19,48 @@ const schemaNameLiteralPass = (content, schemaMapping) => {
         return mapped ? match.replace(`'${schema}'`, `'${mapped}'`) : match;
     });
 };
+/**
+ * Build the per-script subsystem stripper for an `exclude` spec, verifying
+ * cascade safety across the *whole* source bundle first: every deploy-script
+ * reference into an excluded schema (FKs, calls, policy predicates) must have
+ * a rebind route, or materialization refuses with each unsatisfied reference
+ * named. Checking bundle-wide (not per script) is what catches cross-change
+ * dependencies on the excluded subsystem.
+ */
+function makeSubsystemStripper(source, spec, instanceName) {
+    const selector = { schemas: spec.exclude.schemas };
+    const rebinds = buildSchemaRouter({ schemaMap: spec.schemas, routes: spec.route });
+    const fullDeploySql = source.changes
+        .map(c => c.deploy?.sql ?? '')
+        .filter(Boolean)
+        .join('\n');
+    const analysis = excludeSubsystem(fullDeploySql, selector, { rebinds });
+    if (analysis.unsatisfied.length > 0) {
+        const detail = [
+            ...new Set(analysis.unsatisfied.map(u => `${u.object.schema}.${u.object.name}${u.fk ? ' (foreign key target)' : ''}`))
+        ].join(', ');
+        throw new Error(`Cannot exclude schema(s) ${spec.exclude.schemas.join(', ')} from ` +
+            `"${spec.source.module}" as "${instanceName}": surviving statements still reference ` +
+            `${detail} with no route/rebind target. Add "route" entries substituting each ` +
+            `referenced object, or keep the subsystem.`);
+    }
+    // A change whose deploy consists entirely of subsystem statements (plus
+    // transaction control) is excluded *as a change*: its verify/revert scripts
+    // target dropped objects the classifier can't always see (bare DROPs,
+    // catalog probes), so all three scripts are blanked together.
+    const excludedChanges = new Set();
+    for (const change of source.changes) {
+        if (!change.deploy)
+            continue;
+        const stripped = stripSubsystemSql(change.deploy.sql, selector);
+        const survivors = stripped.result.kept.filter(i => !stripped.dropped.includes(i) && stripped.result.statements[i].nodeTag !== 'TransactionStmt');
+        if (stripped.dropped.length > 0 && survivors.length === 0) {
+            excludedChanges.add(change.name);
+        }
+    }
+    const strip = (sql, change) => excludedChanges.has(change) ? blankScriptSql(sql) : stripSubsystemSql(sql, selector).sql;
+    return { strip, excludedChanges };
+}
 /**
  * Transpile a source module per an apply spec and materialize the result as a
  * deployable module directory carrying the instance's identity.
@@ -46,9 +90,14 @@ export async function materializeApplyModule(options) {
     const targetSchemas = [
         ...new Set([
             ...Object.values(spec.schemas ?? {}),
-            ...(spec.route ?? []).map(r => r.toSchema)
+            ...(spec.route ?? [])
+                .map(r => r.toSchema)
+                .filter((s) => typeof s === 'string')
         ])
     ];
+    const stripSubsystem = spec.exclude
+        ? makeSubsystemStripper(source, spec, instanceName)
+        : undefined;
     const { renameChange, transformScript, result } = makeSchemaTranspiler({
         schemaMap: spec.schemas,
         routes: spec.route,
@@ -59,9 +108,15 @@ export async function materializeApplyModule(options) {
             assumeSchemasExist: targetSchemas
         }
     });
+    // Excluded changes keep their source identity (an emptied tombstone) —
+    // renaming them into the replacement provider's namespace would be a lie.
     const transpiled = transpileBundle(source, {
-        renameChange,
-        transformScript,
+        renameChange: stripSubsystem
+            ? (name) => (stripSubsystem.excludedChanges.has(name) ? name : renameChange(name))
+            : renameChange,
+        transformScript: stripSubsystem
+            ? (sql, ctx) => transformScript(stripSubsystem.strip(sql, ctx.change), ctx)
+            : transformScript,
         renameModule: instanceName,
         provenance: {
             appliedFrom: spec.source.module,
@@ -103,7 +158,7 @@ export async function resolveEffectiveModulePath(moduleName, modulePath, moduleM
     const cached = materializedCache.get(cacheKey);
     if (cached)
         return cached;
-    const spec = readApplySpec(modulePath);
+    const spec = resolveEffectiveApplySpec(readApplySpec(modulePath), loadWorkspaceRoutingProfile(workspacePath));
     const sourceModule = moduleMap[spec.source.module];
     if (!sourceModule) {
         throw new Error(`Apply spec in "${moduleName}" references source module "${spec.source.module}", ` +

package/esm/apply/profile.js

@@ -0,0 +1,34 @@
+import { loadConfigSyncFromDir } from '@pgpmjs/env';
+import { mergeRoutingProfiles } from '@pgpmjs/types';
+/**
+ * Load the workspace-level routing profile (the `portability` field of the
+ * workspace `pgpm.json` / `pgpm.config.js`). Returns `undefined` when the
+ * workspace has no config file or no profile.
+ */
+export function loadWorkspaceRoutingProfile(workspacePath) {
+    let config;
+    try {
+        config = loadConfigSyncFromDir(workspacePath);
+    }
+    catch {
+        return undefined;
+    }
+    return config?.portability;
+}
+/**
+ * Resolve the routing profile effective for one apply spec: defaults →
+ * workspace `portability` → the spec's own routing keys, merged per key
+ * (inner scope wins; see {@link mergeRoutingProfiles}).
+ */
+export function resolveEffectiveApplySpec(spec, workspaceProfile) {
+    if (!workspaceProfile)
+        return spec;
+    const merged = mergeRoutingProfiles(workspaceProfile, {
+        schemas: spec.schemas,
+        route: spec.route,
+        extensions: spec.extensions,
+        roles: spec.roles,
+        exclude: spec.exclude
+    });
+    return { ...spec, ...merged };
+}

package/esm/bundle/artifact.js

@@ -45,8 +45,8 @@ export function resolveBundleArtifactPath(moduleDir) {
 }
 /**
  * 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`).
+ * snapshot plus, per change, the deploy SQL with transaction-control
+ * 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

package/esm/core/class/pgpm.js

@@ -24,6 +24,7 @@ import { PgpmMigrate } from '../../migrate/client';
 import { getExtensionsAndModules, getExtensionsAndModulesChanges, latestChange, latestChangeAndVersion } from '../../modules/modules';
 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';
@@ -1323,14 +1324,25 @@ ${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);