@pgpmjs/core 7.13.0 → 7.15.0

package/apply/apply-spec.d.ts

@@ -0,0 +1,14 @@
+import { ResolvedApplySpec } from './types';
+/** Whether a module directory is an apply-spec proxy module. */
+export declare function hasApplySpec(moduleDir: string): boolean;
+/**
+ * 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 declare function readApplySpec(moduleDir: string): ResolvedApplySpec;
+/** In-memory core of {@link readApplySpec}. */
+export declare function parseApplySpec(content: string, specPath: string): ResolvedApplySpec;

package/apply/apply-spec.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasApplySpec = hasApplySpec;
+exports.readApplySpec = readApplySpec;
+exports.parseApplySpec = parseApplySpec;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const types_1 = require("./types");
+/** Whether a module directory is an apply-spec proxy module. */
+function hasApplySpec(moduleDir) {
+    return (0, fs_1.existsSync)((0, path_1.join)(moduleDir, types_1.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.
+ */
+function readApplySpec(moduleDir) {
+    const specPath = (0, path_1.join)(moduleDir, types_1.APPLY_SPEC_FILE);
+    if (!(0, fs_1.existsSync)(specPath)) {
+        throw new Error(`No ${types_1.APPLY_SPEC_FILE} found in ${moduleDir}`);
+    }
+    return parseApplySpec((0, fs_1.readFileSync)(specPath, 'utf-8'), specPath);
+}
+/** In-memory core of {@link readApplySpec}. */
+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 ?? (0, path_1.basename)((0, path_1.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/apply/index.d.ts

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

package/apply/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+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.d.ts

@@ -0,0 +1,40 @@
+import { MigrationBundle } from '@pgpmjs/bundle';
+import { ModuleMap } from '../modules/modules';
+import { ResolvedApplySpec } from './types';
+export interface MaterializeApplyOptions {
+    /** Directory of the source module being applied. */
+    sourceDir: string;
+    /** The apply spec (typically read from the proxy via {@link readApplySpec}). */
+    spec: ResolvedApplySpec;
+    /** Directory to materialize into (default: a fresh temp dir). */
+    outDir?: string;
+}
+export interface MaterializeApplyResult {
+    /** The transpiled, content-addressed bundle that was materialized. */
+    bundle: MigrationBundle;
+    /** The deployable module directory the bundle was written to. */
+    outDir: string;
+}
+/**
+ * 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 declare function materializeApplyModule(options: MaterializeApplyOptions): Promise<MaterializeApplyResult>;
+/**
+ * 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 declare function resolveEffectiveModulePath(moduleName: string, modulePath: string, moduleMap: ModuleMap, workspacePath: string): Promise<string>;
+/** Test seam: clear the per-process materialization cache. */
+export declare function clearApplyMaterializationCache(): void;

package/apply/materialize.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.materializeApplyModule = materializeApplyModule;
+exports.resolveEffectiveModulePath = resolveEffectiveModulePath;
+exports.clearApplyMaterializationCache = clearApplyMaterializationCache;
+const fs_1 = require("fs");
+const os_1 = require("os");
+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
+// 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.
+ */
+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 (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 "${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 } = (0, transform_1.makeSchemaTranspiler)({
+        schemaMap: spec.schemas,
+        routes: spec.route,
+        extensions: spec.extensions,
+        roles: spec.roles,
+        transform: {
+            prePasses: [schemaNameLiteralPass],
+            assumeSchemasExist: targetSchemas
+        }
+    });
+    const transpiled = (0, bundle_1.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 = (0, bundle_1.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 ?? (0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), `pgpm-apply-${instanceName}-`));
+    (0, bundle_1.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.
+ */
+async function resolveEffectiveModulePath(moduleName, modulePath, moduleMap, workspacePath) {
+    if (!(0, apply_spec_1.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 = (0, apply_spec_1.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 = (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(cacheKey, outDir);
+    return outDir;
+}
+/** Test seam: clear the per-process materialization cache. */
+function clearApplyMaterializationCache() {
+    materializedCache.clear();
+}

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;
+}