@pgpmjs/core 7.14.0 → 7.15.0

package/apply/apply-spec.js

@@ -38,14 +38,14 @@ function parseApplySpec(content, specPath) {
     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) {
-        if (typeof parsed.schemas !== 'object' ||
-            Array.isArray(parsed.schemas) ||
-            Object.keys(parsed.schemas).length === 0 ||
-            Object.entries(parsed.schemas).some(([from, to]) => typeof from !== 'string' || typeof to !== 'string' || !from || !to)) {
-            throw new Error(`${specPath}: "schemas" must be a non-empty string → string map`);
-        }
+    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;
@@ -67,8 +67,83 @@ function parseApplySpec(content, specPath) {
             }
         }
     }
-    if (!hasSchemas && !hasRoute) {
-        throw new Error(`${specPath}: at least one of "schemas" (string → string map) or "route" (object routes) is required`);
+    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 ?? (0, path_1.basename)((0, path_1.dirname)(specPath));
     if (typeof name !== 'string' || !name) {

package/apply/index.d.ts

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

package/apply/index.js

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

package/apply/materialize.js

@@ -9,6 +9,7 @@ const path_1 = require("path");
 const bundle_1 = require("@pgpmjs/bundle");
 const transform_1 = require("@pgpmjs/transform");
 const apply_spec_1 = require("./apply-spec");
+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
 // (ubiquitous in verify scripts) name the schema alone, so a string-level
@@ -56,6 +57,8 @@ async function materializeApplyModule(options) {
     const { renameChange, transformScript, result } = (0, transform_1.makeSchemaTranspiler)({
         schemaMap: spec.schemas,
         routes: spec.route,
+        extensions: spec.extensions,
+        roles: spec.roles,
         transform: {
             prePasses: [schemaNameLiteralPass],
             assumeSchemasExist: targetSchemas
@@ -99,7 +102,10 @@ const materializedCache = new Map();
 async function resolveEffectiveModulePath(moduleName, modulePath, moduleMap, workspacePath) {
     if (!(0, apply_spec_1.hasApplySpec)(modulePath))
         return modulePath;
-    const cached = materializedCache.get(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 = (0, apply_spec_1.readApplySpec)(modulePath);
@@ -111,8 +117,15 @@ async function resolveEffectiveModulePath(moduleName, modulePath, moduleMap, wor
             `.`);
     }
     const sourceDir = (0, path_1.resolve)(workspacePath, sourceModule.path);
+    if ((0, reuse_1.isReuseSpec)(spec)) {
+        const result = await (0, reuse_1.materializeReuseModule)({ sourceDir, spec });
+        materializedCache.set(`${modulePath}::${result.sharedName}`, result.shared.outDir);
+        materializedCache.set(`${modulePath}::${result.perTenantName}`, result.perTenant.outDir);
+        const outDir = moduleName === (0, reuse_1.resolveSharedModuleName)(spec) ? result.shared.outDir : result.perTenant.outDir;
+        return outDir;
+    }
     const { outDir } = await materializeApplyModule({ sourceDir, spec });
-    materializedCache.set(modulePath, outDir);
+    materializedCache.set(cacheKey, outDir);
     return outDir;
 }
 /** Test seam: clear the per-process materialization cache. */

package/apply/reuse.d.ts

@@ -0,0 +1,52 @@
+import { MigrationBundle } from '@pgpmjs/bundle';
+import { ResolvedApplySpec } from './types';
+/** A resolved apply spec that carries a reuse declaration. */
+export type ResolvedReuseSpec = ResolvedApplySpec & {
+    reuse: NonNullable<ResolvedApplySpec['reuse']>;
+};
+/** Whether an apply spec is a reuse (shared/per-tenant split) spec. */
+export declare function isReuseSpec(spec: ResolvedApplySpec): spec is ResolvedReuseSpec;
+/**
+ * Deterministic name of the shared module a reuse proxy expands into. Derived
+ * from the source module, the shared-schema mapping, and the per-tenant seed
+ * set — the exact inputs that determine the shared partition — so two tenant
+ * proxies over the same source/shared/seed configuration resolve to *one*
+ * shared module (deployed once), while any difference isolates them.
+ */
+export declare function resolveSharedModuleName(spec: ResolvedReuseSpec): string;
+export interface MaterializeReuseOptions {
+    /** Directory of the source module being applied. */
+    sourceDir: string;
+    /** The resolved reuse spec. */
+    spec: ResolvedReuseSpec;
+    /** Deployable directory for the shared module (default: a fresh temp dir). */
+    sharedOutDir?: string;
+    /** Deployable directory for the per-tenant module (default: a fresh temp dir). */
+    perTenantOutDir?: string;
+}
+export interface MaterializeReuseResult {
+    sharedName: string;
+    perTenantName: string;
+    shared: {
+        bundle: MigrationBundle;
+        outDir: string;
+    };
+    perTenant: {
+        bundle: MigrationBundle;
+        outDir: string;
+    };
+}
+/**
+ * Expand a reuse proxy into two deployable modules: a shared module (objects the
+ * classifier proves tenant-independent, deployed once) and a per-tenant module
+ * (objects reachable from the per-tenant seeds, materialized per instance) that
+ * `requires` the shared one.
+ *
+ * Pipeline over existing primitives:
+ * `bundleFromModule` → `partitionModule` (classifier) →
+ * `transpileBundle(makeSchemaTranspiler)` routing shared objects to the shared
+ * schema and per-tenant objects to the per-tenant schema in *one* pass (so
+ * cross-boundary references resolve correctly) → `splitBundle` with a per-tenant
+ * schema bootstrap → `verifyBundle` → `materializeBundle`.
+ */
+export declare function materializeReuseModule(options: MaterializeReuseOptions): Promise<MaterializeReuseResult>;

package/apply/reuse.js

@@ -0,0 +1,226 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isReuseSpec = isReuseSpec;
+exports.resolveSharedModuleName = resolveSharedModuleName;
+exports.materializeReuseModule = materializeReuseModule;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const ast_1 = require("@pgpmjs/ast");
+const bundle_1 = require("@pgpmjs/bundle");
+const slice_1 = require("@pgpmjs/slice");
+const transform_1 = require("@pgpmjs/transform");
+/** Whether an apply spec is a reuse (shared/per-tenant split) spec. */
+function isReuseSpec(spec) {
+    return spec.reuse !== undefined;
+}
+/** pgpm change-path folder → object route kind. */
+const FOLDER_KIND = {
+    tables: 'table',
+    views: 'view',
+    functions: 'function',
+    procedures: 'procedure',
+    types: 'type'
+};
+// Mirrors materialize.ts: bare-schema-name literal helpers the AST pass can't
+// reach are remapped by a narrow string pre-pass.
+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;
+    });
+};
+/** Parse a `schemas/<schema>/<folder>/<name>…` change path into its object identity. */
+function parseObjectChange(change) {
+    const parts = change.split('/');
+    if (parts[0] !== 'schemas' || parts.length < 2)
+        return null;
+    const schema = parts[1];
+    const folder = parts[2];
+    if (folder === undefined || folder === 'schema')
+        return { schema, folder: 'schema' };
+    return { schema, folder, name: parts[3] };
+}
+/**
+ * Deterministic name of the shared module a reuse proxy expands into. Derived
+ * from the source module, the shared-schema mapping, and the per-tenant seed
+ * set — the exact inputs that determine the shared partition — so two tenant
+ * proxies over the same source/shared/seed configuration resolve to *one*
+ * shared module (deployed once), while any difference isolates them.
+ */
+function resolveSharedModuleName(spec) {
+    if (spec.reuse.sharedName)
+        return spec.reuse.sharedName;
+    const canonical = JSON.stringify({
+        source: spec.source.module,
+        sharedSchema: Object.entries(spec.reuse.sharedSchema).sort(([a], [b]) => a.localeCompare(b)),
+        seeds: spec.reuse.perTenant
+            .map(s => `${s.fromSchema}.${s.kind}.${s.name}`)
+            .sort((a, b) => a.localeCompare(b))
+    });
+    return `${spec.source.module}-shared-${(0, ast_1.hashString)(canonical).slice(0, 8)}`;
+}
+/**
+ * Expand a reuse proxy into two deployable modules: a shared module (objects the
+ * classifier proves tenant-independent, deployed once) and a per-tenant module
+ * (objects reachable from the per-tenant seeds, materialized per instance) that
+ * `requires` the shared one.
+ *
+ * Pipeline over existing primitives:
+ * `bundleFromModule` → `partitionModule` (classifier) →
+ * `transpileBundle(makeSchemaTranspiler)` routing shared objects to the shared
+ * schema and per-tenant objects to the per-tenant schema in *one* pass (so
+ * cross-boundary references resolve correctly) → `splitBundle` with a per-tenant
+ * schema bootstrap → `verifyBundle` → `materializeBundle`.
+ */
+async function materializeReuseModule(options) {
+    const { sourceDir, spec } = options;
+    const perTenantName = spec.name;
+    const sharedName = resolveSharedModuleName(spec);
+    const reuse = spec.reuse;
+    await (0, transform_1.loadModule)();
+    const source = (0, bundle_1.bundleFromModule)(sourceDir);
+    if (spec.source.bundleDigest && spec.source.bundleDigest !== source.manifest.digest) {
+        throw new Error(`Apply spec for "${perTenantName}" 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.`);
+    }
+    // 1. Classify: which source changes must be per-tenant (a seed or a dependent).
+    const partition = (0, slice_1.partitionModule)({
+        moduleDir: sourceDir,
+        seedObjects: reuse.perTenant.map(s => ({ schema: s.fromSchema, name: s.name }))
+    });
+    const unknownSeeds = partition.warnings.filter(w => w.kind === 'unknown-seed');
+    if (unknownSeeds.length > 0) {
+        throw new Error(`Reuse spec for "${perTenantName}": seed object(s) not found in source "${spec.source.module}": ` +
+            unknownSeeds.map(w => w.change).join(', '));
+    }
+    // 2. Object routes: every per-tenant change's object goes to the per-tenant
+    //    target; everything else defaults (schemaMap) to the shared target. A
+    //    single router keeps cross-boundary references correct (a per-tenant
+    //    function landing in the tenant schema still references the shared helper
+    //    in the shared schema).
+    const routes = [];
+    for (const change of partition.perTenant) {
+        const obj = parseObjectChange(change);
+        if (!obj || obj.folder === 'schema' || !obj.name) {
+            throw new Error(`Reuse spec for "${perTenantName}": per-tenant change "${change}" is not an object change ` +
+                `and cannot be routed to a per-tenant schema; refine the seeds so it stays shared, or ` +
+                `it names an unsupported object kind`);
+        }
+        const kind = FOLDER_KIND[obj.folder];
+        if (!kind) {
+            throw new Error(`Reuse spec for "${perTenantName}": per-tenant change "${change}" has unsupported object ` +
+                `folder "${obj.folder}"`);
+        }
+        const toSchema = spec.schemas[obj.schema];
+        if (!toSchema) {
+            throw new Error(`Reuse spec for "${perTenantName}": per-tenant object in schema "${obj.schema}" has no ` +
+                `per-tenant target in "schemas"`);
+        }
+        routes.push({ fromSchema: obj.schema, kind, name: obj.name, toSchema });
+    }
+    const assumeSchemasExist = [
+        ...new Set([...Object.values(reuse.sharedSchema), ...Object.values(spec.schemas)])
+    ];
+    const provenance = {
+        appliedFrom: spec.source.module,
+        ...(spec.source.package ? { sourcePackage: spec.source.package } : {}),
+        ...(spec.source.version ? { sourceVersion: spec.source.version } : {})
+    };
+    // 3. Transpile once: schema default = shared target, per-object overrides =
+    //    per-tenant target.
+    const main = (0, transform_1.makeSchemaTranspiler)({
+        schemaMap: reuse.sharedSchema,
+        routes,
+        extensions: spec.extensions,
+        roles: spec.roles,
+        transform: { prePasses: [schemaNameLiteralPass], assumeSchemasExist }
+    });
+    const transpiled = (0, bundle_1.transpileBundle)(source, {
+        renameChange: main.renameChange,
+        transformScript: main.transformScript,
+        provenance
+    });
+    if (main.result.errors.length > 0) {
+        const detail = main.result.errors.map(e => `${e.file}: ${e.error}`).join('; ');
+        throw new Error(`Reuse transpile of "${spec.source.module}" for "${perTenantName}" failed: ${detail}`);
+    }
+    // The partition is in *source* change names; splitBundle works on the
+    // transpiled bundle, so map the per-tenant set through the same rename.
+    const perTenantTranspiled = [...partition.perTenant].map(main.renameChange);
+    // 4. Per-tenant schema bootstrap: the source's `CREATE SCHEMA` lands in the
+    //    shared module (shared target), but each tenant also needs its own
+    //    schema. Duplicate it — transpiled to the per-tenant target — into the
+    //    per-tenant module, re-pointing per-tenant dependencies off the shared
+    //    schema onto this local one.
+    const bootstrap = buildSchemaBootstraps(source, spec, main.renameChange, assumeSchemasExist);
+    const { shared, perTenant } = (0, bundle_1.splitBundle)(transpiled, {
+        perTenantChanges: perTenantTranspiled,
+        sharedName,
+        perTenantName,
+        perTenantBootstrap: bootstrap
+    });
+    for (const [label, bundle] of [
+        [sharedName, shared],
+        [perTenantName, perTenant]
+    ]) {
+        const issues = (0, bundle_1.verifyBundle)(bundle);
+        if (issues.length > 0) {
+            throw new Error(`Reuse bundle "${label}" failed integrity verification: ${issues.map(i => i.kind).join(', ')}`);
+        }
+    }
+    const sharedOutDir = options.sharedOutDir ?? (0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), `pgpm-apply-${sharedName}-`));
+    const perTenantOutDir = options.perTenantOutDir ?? (0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), `pgpm-apply-${perTenantName}-`));
+    (0, bundle_1.materializeBundle)(shared, sharedOutDir);
+    (0, bundle_1.materializeBundle)(perTenant, perTenantOutDir);
+    return {
+        sharedName,
+        perTenantName,
+        shared: { bundle: shared, outDir: sharedOutDir },
+        perTenant: { bundle: perTenant, outDir: perTenantOutDir }
+    };
+}
+/**
+ * Build a per-tenant `CREATE SCHEMA` bootstrap for each source schema that both
+ * creates a schema and has per-tenant objects. The scripts are the source
+ * schema-creation change transpiled to the per-tenant target; `replacesShared`
+ * is the shared-schema change the per-tenant objects would otherwise depend on.
+ */
+function buildSchemaBootstraps(source, spec, renameSharedChange, assumeSchemasExist) {
+    const bootstraps = [];
+    for (const [fromSchema, perTenantTarget] of Object.entries(spec.schemas)) {
+        const sharedTarget = spec.reuse.sharedSchema[fromSchema];
+        if (!sharedTarget || sharedTarget === perTenantTarget)
+            continue;
+        const sourceSchemaChange = `schemas/${fromSchema}/schema`;
+        const schemaChange = source.changes.find(c => c.name === sourceSchemaChange);
+        if (!schemaChange)
+            continue; // source doesn't create this schema; nothing to duplicate
+        // Transpile just the schema-creation change to the per-tenant target.
+        const single = {
+            ...source,
+            manifest: { ...source.manifest, changeCount: 1, deployOrder: [sourceSchemaChange] },
+            changes: [schemaChange]
+        };
+        const t = (0, transform_1.makeSchemaTranspiler)({
+            schemaMap: { [fromSchema]: perTenantTarget },
+            transform: { prePasses: [schemaNameLiteralPass], assumeSchemasExist }
+        });
+        const perTenantSchema = (0, bundle_1.transpileBundle)(single, {
+            renameChange: t.renameChange,
+            transformScript: t.transformScript
+        }).changes[0];
+        bootstraps.push({
+            name: `schemas/${perTenantTarget}/schema`,
+            dependencies: [],
+            deploy: perTenantSchema.deploy?.sql ?? null,
+            revert: perTenantSchema.revert?.sql ?? null,
+            verify: perTenantSchema.verify?.sql ?? null,
+            replacesShared: renameSharedChange(sourceSchemaChange)
+        });
+    }
+    return bootstraps;
+}

package/apply/types.d.ts

@@ -49,6 +49,79 @@ export interface ApplyRouteEntry {
     /** Target schema the object is routed to (e.g. `reporting`). */
     toSchema: string;
 }
+/**
+ * A per-tenant seed object in a reuse spec: the objects that must be
+ * materialized once *per tenant*. `@pgpmjs/slice`'s `partitionModule` starts
+ * from these seeds and marks every change that transitively reaches one as
+ * per-tenant; everything else is proven shared and emitted once. Expressed as
+ * separate properties (no dotted identity strings), matching {@link ApplyRouteEntry}.
+ */
+export interface ApplyReuseSeed {
+    /** Source schema the seed object is defined in (e.g. `catalog`). */
+    fromSchema: string;
+    /** Object namespace: `table`/`view` → relation, `procedure` → function. */
+    kind: 'table' | 'view' | 'function' | 'procedure' | 'type';
+    /** Unqualified object name (e.g. `products`). */
+    name: string;
+}
+/**
+ * Reuse declaration: split the source into a *shared* module (deployed once,
+ * reused by every tenant via ordinary `requires`) and a *per-tenant* module
+ * (materialized per instance). The classifier proves the split from the
+ * `perTenant` seeds; a shared object that would depend on a per-tenant one is
+ * rejected as unsound rather than silently deployed.
+ */
+export interface ApplyReuseSpec {
+    /**
+     * Source schema → *shared* target schema. Shared objects land here; this
+     * mapping must be stable across tenant instances so the shared module has a
+     * deterministic identity and deploys exactly once.
+     */
+    sharedSchema: Record<string, string>;
+    /** Per-tenant seed objects (non-empty). */
+    perTenant: ApplyReuseSeed[];
+    /**
+     * Optional explicit shared-module name. Defaults to a deterministic name
+     * derived from the source module and the shared-schema mapping, so two tenant
+     * proxies over the same source + shared mapping resolve to one shared module.
+     */
+    sharedName?: string;
+}
+/**
+ * Extension-routing declaration in a `pgpm.apply.json`: where the transpiled
+ * instance should install extensions and resolve the symbols they provide
+ * (e.g. isolate `pgcrypto` in a dedicated `extensions` schema, qualifying bare
+ * `crypt(...)` calls, or the reverse). A distinct dimension from schema
+ * routing — driven by a version-aware symbol inventory, not by the objects the
+ * SQL itself creates. Forwarded to `@pgpmjs/transform`'s extension router.
+ */
+export interface ApplyExtensionsSpec {
+    /**
+     * Install the matched extensions and route their provided symbols to this
+     * schema. `null` strips qualification (rely on `search_path`). Ignored when
+     * `routes` is given.
+     */
+    toSchema?: string | null;
+    /** With `toSchema`: limit to these extensions (default: every inventoried one). */
+    only?: string[];
+    /**
+     * With `toSchema`: which source qualifications to rewrite (a `null` entry
+     * also rewrites bare references). Defaults to `public` + bare.
+     */
+    from?: (string | null)[];
+    /**
+     * Advanced: explicit per-extension routes (`{ "<ext>": { "to": "<schema>|null",
+     * "from"?: [...] } }`). Overrides `toSchema`/`only`/`from`.
+     */
+    routes?: Record<string, {
+        to: string | null;
+        from?: (string | null)[];
+    }>;
+    /** Target PostgreSQL major version, for core-graduation awareness. */
+    serverVersion?: number;
+}
+/** Role-name translation: source role name → target role name. */
+export type ApplyRolesSpec = Record<string, string>;
 /** The parsed, normalized `pgpm.apply.json` spec. */
 export interface PgpmApplySpec {
     /**
@@ -69,6 +142,22 @@ export interface PgpmApplySpec {
      * 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

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