@pgpmjs/core 7.14.0 → 7.15.0

package/bundle/artifact.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bundleArtifactFileName = bundleArtifactFileName;
+exports.resolveBundleArtifactPath = resolveBundleArtifactPath;
+exports.buildExecutableBundle = buildExecutableBundle;
+exports.writeBundleArtifact = writeBundleArtifact;
+exports.readBundleArtifact = readBundleArtifact;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const files_1 = require("@pgpmjs/ast/files");
+const bundle_1 = require("@pgpmjs/bundle");
+const clean_1 = require("../migrate/clean");
+/**
+ * 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`.
+ */
+function bundleArtifactFileName(name, version) {
+    return `${name}--${version}${bundle_1.BUNDLE_ARCHIVE_EXTENSION}`;
+}
+/**
+ * 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.
+ */
+function resolveBundleArtifactPath(moduleDir) {
+    const sqlDir = (0, path_1.join)(moduleDir, 'sql');
+    if (!(0, fs_1.existsSync)(sqlDir))
+        return null;
+    let name;
+    try {
+        name = (0, files_1.getExtensionName)(moduleDir);
+    }
+    catch {
+        return null;
+    }
+    const controlPath = (0, path_1.join)(moduleDir, `${name}.control`);
+    if ((0, fs_1.existsSync)(controlPath)) {
+        const { version } = (0, files_1.parseControlContent)((0, fs_1.readFileSync)(controlPath, 'utf-8'));
+        if (version) {
+            const versioned = (0, path_1.join)(sqlDir, bundleArtifactFileName(name, version));
+            if ((0, fs_1.existsSync)(versioned))
+                return versioned;
+        }
+    }
+    const candidates = (0, fs_1.readdirSync)(sqlDir).filter(file => file.startsWith(`${name}--`) && file.endsWith(bundle_1.BUNDLE_ARCHIVE_EXTENSION));
+    if (candidates.length !== 1)
+        return null;
+    return (0, path_1.join)(sqlDir, candidates[0]);
+}
+/**
+ * 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.
+ */
+async function buildExecutableBundle(moduleDir, options) {
+    const bundle = (0, bundle_1.bundleFromModule)(moduleDir, options);
+    const execSql = {};
+    for (const change of bundle.changes) {
+        if (!change.deploy)
+            continue;
+        execSql[change.name] = await (0, clean_1.cleanSql)(change.deploy.sql, false, '$EOFCODE$');
+    }
+    return (0, bundle_1.withExecutableSql)(bundle, execSql);
+}
+/**
+ * Emit a module's stored bundle artifact into `sql/`, returning its path.
+ */
+async function writeBundleArtifact(moduleDir, version, options) {
+    const bundle = await buildExecutableBundle(moduleDir, options);
+    const outPath = (0, path_1.join)(moduleDir, 'sql', bundleArtifactFileName(bundle.manifest.name, version));
+    (0, bundle_1.writeBundleArchiveFile)(bundle, outPath);
+    return outPath;
+}
+/**
+ * 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.
+ */
+function readBundleArtifact(moduleDir) {
+    const artifactPath = resolveBundleArtifactPath(moduleDir);
+    if (!artifactPath)
+        return null;
+    try {
+        return (0, bundle_1.readBundleArchiveFile)(artifactPath);
+    }
+    catch {
+        return null;
+    }
+}

package/bundle/deploy-bundled.d.ts

@@ -0,0 +1,71 @@
+import { BundleChange } from '@pgpmjs/bundle';
+import { PgConfig } from 'pg-env';
+/**
+ * Why the one-shot path could not be used, so the caller falls back to the
+ * per-change migration path.
+ */
+export type BundledDeploySkipReason = 'no-executable-sql' | 'unsupported-hash-method';
+/** How the executable bundle for a module was obtained. */
+export type BundleSource = 'artifact' | 'packaged';
+export interface BundledDeployResult {
+    /** Module (package) name from the bundle manifest. */
+    name: string;
+    /** Where the executable bundle came from. */
+    source: BundleSource;
+    /** Changes executed and recorded on this run, in deploy order. */
+    deployed: string[];
+    /** Changes already present in the ledger with a matching hash. */
+    skipped: string[];
+}
+export interface BundledDeployOptions {
+    config: PgConfig;
+    /** Target database (defaults to `config.database`). */
+    database?: string;
+    /** Record ledger rows without executing the DDL. */
+    logOnly?: boolean;
+    /** Wrap execution + ledger writes in one transaction. Default true. */
+    useTransaction?: boolean;
+    /**
+     * Ledger hash scheme in force. The bundle's per-change digests are sha256 of
+     * the deploy script's bytes, i.e. identical to `PgpmMigrate`'s `content`
+     * scheme; the `ast` scheme is not reproducible here, so it is reported as a
+     * skip and the caller falls back.
+     */
+    hashMethod?: 'content' | 'ast';
+}
+/** Thrown when the ledger already holds a change with different content. */
+export declare class BundledDeployConflictError extends Error {
+    readonly packageName: string;
+    readonly changeName: string;
+    constructor(packageName: string, changeName: string);
+}
+/**
+ * The ledger hash for a change: the sha256 of the deploy script bytes.
+ *
+ * This is deliberately the same value `PgpmMigrate.calculateScriptHash` derives
+ * from `deploy/<change>.sql` under the default `content` hash method, so a
+ * change hashed at package time and the hash recorded/compared at deploy time
+ * agree — the one-shot and per-change paths are interchangeable and idempotent
+ * against each other.
+ */
+export declare function ledgerHashForChange(change: BundleChange): string | null;
+/**
+ * Deploy a module in one shot **and** record the migration ledger — the `fast`
+ * deploy strategy.
+ *
+ * Pending changes' deploy SQL is concatenated and executed as a single
+ * statement (the speed of the old fast path), then one `pgpm_migrate.changes`
+ * row per change is bulk-inserted with the deploy script's own sha256 as
+ * `script_hash` — one round-trip, instead of an `isDeployed` + `readScript` +
+ * `CALL pgpm_migrate.deploy` per change. Because the ledger is written, the
+ * path is idempotent and resumable: re-deploys skip changes whose stored hash
+ * matches, and a same-name/different-content change raises
+ * {@link BundledDeployConflictError} exactly as the per-change path does.
+ *
+ * Returns a {@link BundledDeploySkipReason} (rather than throwing) when it
+ * cannot honour the requested semantics, so the caller falls back to the
+ * per-change migration path. Genuine SQL failures still throw.
+ */
+export declare function deployModuleFast(moduleDir: string, options: BundledDeployOptions): Promise<BundledDeployResult | BundledDeploySkipReason>;
+/** True when the value is a real deploy result rather than a skip reason. */
+export declare function isBundledDeployResult(value: BundledDeployResult | BundledDeploySkipReason): value is BundledDeployResult;

package/bundle/deploy-bundled.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BundledDeployConflictError = void 0;
+exports.ledgerHashForChange = ledgerHashForChange;
+exports.deployModuleFast = deployModuleFast;
+exports.isBundledDeployResult = isBundledDeployResult;
+const logger_1 = require("@pgpmjs/logger");
+const bundle_1 = require("@pgpmjs/bundle");
+const pg_cache_1 = require("pg-cache");
+const client_1 = require("../migrate/client");
+const artifact_1 = require("./artifact");
+const log = new logger_1.Logger('deploy-fast');
+/** Thrown when the ledger already holds a change with different content. */
+class BundledDeployConflictError extends Error {
+    packageName;
+    changeName;
+    constructor(packageName, changeName) {
+        super(`Change ${changeName} already deployed in package ${packageName} with different content`);
+        this.packageName = packageName;
+        this.changeName = changeName;
+        this.name = 'BundledDeployConflictError';
+    }
+}
+exports.BundledDeployConflictError = BundledDeployConflictError;
+/**
+ * The ledger hash for a change: the sha256 of the deploy script bytes.
+ *
+ * This is deliberately the same value `PgpmMigrate.calculateScriptHash` derives
+ * from `deploy/<change>.sql` under the default `content` hash method, so a
+ * change hashed at package time and the hash recorded/compared at deploy time
+ * agree — the one-shot and per-change paths are interchangeable and idempotent
+ * against each other.
+ */
+function ledgerHashForChange(change) {
+    return change.deploy?.digest ?? null;
+}
+/**
+ * Load a module's executable bundle: its stored artifact when one verifies,
+ * otherwise built from `deploy/` on the fly.
+ *
+ * The artifact is purely an optimization — it removes the read+parse work, not
+ * a capability. Whatever the source, the resulting bundle is byte-identical in
+ * what it executes and in the hashes it records, so a module without an
+ * artifact deploys exactly the same way, just slower.
+ */
+async function loadExecutableBundle(moduleDir) {
+    const stored = (0, artifact_1.readBundleArtifact)(moduleDir);
+    if (stored) {
+        const issues = (0, bundle_1.verifyBundle)(stored);
+        if (issues.length === 0) {
+            return { bundle: stored, source: 'artifact' };
+        }
+        log.warn(`⚠️ Bundle artifact for ${stored.manifest.name} failed verification ` +
+            `(${issues.map(i => i.kind).join(', ')}); rebuilding from deploy/.`);
+    }
+    return { bundle: await (0, artifact_1.buildExecutableBundle)(moduleDir), source: 'packaged' };
+}
+/**
+ * Deploy a module in one shot **and** record the migration ledger — the `fast`
+ * deploy strategy.
+ *
+ * Pending changes' deploy SQL is concatenated and executed as a single
+ * statement (the speed of the old fast path), then one `pgpm_migrate.changes`
+ * row per change is bulk-inserted with the deploy script's own sha256 as
+ * `script_hash` — one round-trip, instead of an `isDeployed` + `readScript` +
+ * `CALL pgpm_migrate.deploy` per change. Because the ledger is written, the
+ * path is idempotent and resumable: re-deploys skip changes whose stored hash
+ * matches, and a same-name/different-content change raises
+ * {@link BundledDeployConflictError} exactly as the per-change path does.
+ *
+ * Returns a {@link BundledDeploySkipReason} (rather than throwing) when it
+ * cannot honour the requested semantics, so the caller falls back to the
+ * per-change migration path. Genuine SQL failures still throw.
+ */
+async function deployModuleFast(moduleDir, options) {
+    if ((options.hashMethod ?? 'content') !== 'content') {
+        return 'unsupported-hash-method';
+    }
+    const { bundle, source } = await loadExecutableBundle(moduleDir);
+    const executable = bundle.changes.filter(change => change.deploy);
+    if (executable.length === 0 || executable.some(change => !change.exec)) {
+        return 'no-executable-sql';
+    }
+    const packageName = bundle.manifest.name;
+    const config = options.database
+        ? { ...options.config, database: options.database }
+        : options.config;
+    // Ensures the pgpm_migrate schema/procedures exist, exactly as the
+    // per-change deploy path does.
+    await new client_1.PgpmMigrate(config, { hashMethod: 'content' }).initialize();
+    const pool = (0, pg_cache_1.getPgPool)(config);
+    const existing = await pool.query('SELECT change_name, script_hash FROM pgpm_migrate.changes WHERE package = $1', [packageName]);
+    const deployedHashes = new Map(existing.rows.map(row => [row.change_name, row.script_hash]));
+    const pending = [];
+    const skipped = [];
+    for (const change of executable) {
+        const hash = ledgerHashForChange(change);
+        const recorded = deployedHashes.get(change.name);
+        if (recorded === undefined) {
+            pending.push(change);
+            continue;
+        }
+        if (recorded !== hash) {
+            throw new BundledDeployConflictError(packageName, change.name);
+        }
+        skipped.push(change.name);
+    }
+    if (pending.length === 0) {
+        log.info(`⚡ ${packageName}: all ${skipped.length} change(s) already deployed.`);
+        return { name: packageName, source, deployed: [], skipped };
+    }
+    const changeNames = pending.map(change => change.name);
+    const hashes = pending.map(change => ledgerHashForChange(change));
+    const depChanges = [];
+    const depRequires = [];
+    for (const change of pending) {
+        for (const dep of new Set(change.dependencies)) {
+            depChanges.push(change.name);
+            depRequires.push(dep.includes(':') ? dep : `${packageName}:${dep}`);
+        }
+    }
+    const deploySql = pending.map(change => change.exec.sql).join('\n');
+    const client = await pool.connect();
+    const useTransaction = options.useTransaction ?? true;
+    try {
+        if (useTransaction)
+            await client.query('BEGIN');
+        if (!options.logOnly) {
+            await client.query(deploySql);
+        }
+        await client.query('INSERT INTO pgpm_migrate.packages (package) VALUES ($1) ON CONFLICT (package) DO NOTHING', [packageName]);
+        await client.query(`WITH input AS (
+         SELECT change_name, script_hash
+         FROM unnest($2::text[], $3::text[]) AS t(change_name, script_hash)
+       ), inserted AS (
+         INSERT INTO pgpm_migrate.changes (change_id, change_name, package, script_hash)
+         SELECT encode(sha256(($1 || change_name || script_hash)::bytea), 'hex'),
+                change_name, $1, script_hash
+         FROM input
+         ON CONFLICT (package, change_name) DO NOTHING
+         RETURNING change_id, change_name
+       ), deps AS (
+         INSERT INTO pgpm_migrate.dependencies (change_id, requires)
+         SELECT inserted.change_id, d.requires
+         FROM unnest($4::text[], $5::text[]) AS d(change_name, requires)
+         JOIN inserted ON inserted.change_name = d.change_name
+         ON CONFLICT DO NOTHING
+         RETURNING change_id
+       )
+       INSERT INTO pgpm_migrate.events (event_type, change_name, package)
+       SELECT 'deploy', change_name, $1 FROM inserted`, [packageName, changeNames, hashes, depChanges, depRequires]);
+        if (useTransaction)
+            await client.query('COMMIT');
+    }
+    catch (error) {
+        if (useTransaction) {
+            try {
+                await client.query('ROLLBACK');
+            }
+            catch {
+                // the connection is already unusable; surface the original error
+            }
+        }
+        throw error;
+    }
+    finally {
+        client.release();
+    }
+    log.success(`⚡ ${packageName}: ${changeNames.length} change(s) ${options.logOnly ? 'logged' : 'deployed'} ` +
+        `from ${source === 'artifact' ? 'bundle artifact' : 'packaged deploy/'} ` +
+        `(${skipped.length} already deployed).`);
+    return { name: packageName, source, deployed: changeNames, skipped };
+}
+/** True when the value is a real deploy result rather than a skip reason. */
+function isBundledDeployResult(value) {
+    return typeof value !== 'string';
+}

package/bundle/index.d.ts

@@ -11,3 +11,5 @@
 export * from '@pgpmjs/bundle';
 export * from './apply';
 export * from './apply-envelope';
+export * from './artifact';
+export * from './deploy-bundled';

package/bundle/index.js

@@ -31,3 +31,7 @@ __exportStar(require("@pgpmjs/bundle"), exports);
 __exportStar(require("./apply"), exports);
 // applyEnvelope: schema apply + data/fixtures part replay for a BundleEnvelope.
 __exportStar(require("./apply-envelope"), exports);
+// The stored `sql/<name>--<version>.bundle.tar.gz` artifact: emit + resolve.
+__exportStar(require("./artifact"), exports);
+// The bundle-backed deploy fast path (one-shot execute + ledger).
+__exportStar(require("./deploy-bundled"), exports);

package/core/class/pgpm.js

@@ -50,6 +50,7 @@ const pg_cache_1 = require("pg-cache");
 const yanse_1 = __importDefault(require("yanse"));
 const materialize_1 = require("../../apply/materialize");
 const apply_spec_1 = require("../../apply/apply-spec");
+const reuse_1 = require("../../apply/reuse");
 const types_2 = require("../../apply/types");
 const extensions_1 = require("../../extensions/extensions");
 const files_1 = require("@pgpmjs/ast/files");
@@ -60,7 +61,7 @@ const parser_1 = require("@pgpmjs/ast/files/plan/parser");
 const validators_1 = require("@pgpmjs/ast/files/plan/validators");
 const client_1 = require("../../migrate/client");
 const modules_1 = require("../../modules/modules");
-const package_1 = require("../../packaging/package");
+const deploy_bundled_1 = require("../../bundle/deploy-bundled");
 const sync_versions_1 = require("../../packaging/sync-versions");
 const deps_1 = require("../../resolution/deps");
 const fs_2 = require("../../utils/fs");
@@ -313,13 +314,30 @@ class PgpmPackage {
             if (moduleMap[name])
                 continue;
             const source = moduleMap[spec.source.module];
-            moduleMap[name] = {
-                path: path_1.default
-                    .dirname(path_1.default.relative(this.workspacePath, file))
-                    .replace(/\\/g, '/'),
-                requires: spec.requires ?? source?.requires ?? [],
-                version: spec.version ?? source?.version ?? '0.0.1'
-            };
+            const relPath = path_1.default
+                .dirname(path_1.default.relative(this.workspacePath, file))
+                .replace(/\\/g, '/');
+            const baseRequires = spec.requires ?? source?.requires ?? [];
+            const version = spec.version ?? source?.version ?? '0.0.1';
+            if ((0, reuse_1.isReuseSpec)(spec)) {
+                // A reuse proxy expands into two modules that both materialize from
+                // this one directory: a shared module (deployed once, reused across
+                // tenants) and the per-tenant module that `requires` it. Multiple
+                // tenant proxies over the same source/shared/seed config resolve to
+                // the same deterministic shared name, so it is added at most once.
+                const sharedName = (0, reuse_1.resolveSharedModuleName)(spec);
+                if (!moduleMap[sharedName]) {
+                    moduleMap[sharedName] = { path: relPath, requires: baseRequires, version };
+                }
+                moduleMap[name] = {
+                    path: relPath,
+                    requires: [...baseRequires, sharedName],
+                    version
+                };
+            }
+            else {
+                moduleMap[name] = { path: relPath, requires: baseRequires, version };
+            }
         }
         return moduleMap;
     }
@@ -1334,12 +1352,6 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
         const log = new logger_1.Logger('deploy');
         const { name, toChange } = this.parsePackageTarget(target);
         if (recursive) {
-            // Cache for fast deployment
-            const deployFastCache = {};
-            const getCacheKey = (pg, name, database) => {
-                const { host, port, user } = pg ?? {};
-                return `${host}:${port}:${user}:${database}:${name}`;
-            };
             const modules = this.getModuleMap();
             let extensions;
             if (name === null) {
@@ -1362,49 +1374,22 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
                     else {
                         const modulePath = await (0, materialize_1.resolveEffectiveModulePath)(extension, (0, path_1.resolve)(this.workspacePath, modules[extension].path), modules, this.workspacePath);
                         log.info(`📂 Deploying local module: ${extension}`);
-                        if (opts.deployment.fast) {
-                            const cacheKey = getCacheKey(opts.pg, extension, opts.pg.database);
-                            if (opts.deployment.cache && deployFastCache[cacheKey]) {
-                                log.warn(`⚡ Using cached pkg for ${extension}.`);
-                                await pgPool.query(deployFastCache[cacheKey].sql);
+                        if (opts.deployment.fast || opts.deployment.bundled) {
+                            // Fast strategy: one-shot execution plus a bulk-written
+                            // pgpm_migrate ledger, from the module's verified bundle artifact
+                            // when it has one and from `deploy/` when it does not.
+                            const outcome = await (0, deploy_bundled_1.deployModuleFast)(modulePath, {
+                                config: opts.pg,
+                                logOnly: opts.deployment.logOnly,
+                                useTransaction: opts.deployment.useTx,
+                                hashMethod: opts.deployment.hashMethod
+                            });
+                            if ((0, deploy_bundled_1.isBundledDeployResult)(outcome)) {
                                 continue;
                             }
-                            let pkg;
-                            try {
-                                pkg = await (0, package_1.packageModule)(modulePath, {
-                                    usePlan: opts.deployment.usePlan,
-                                    extension: false
-                                });
-                            }
-                            catch (err) {
-                                const errorLines = [];
-                                errorLines.push(`❌ Failed to package module "${extension}" at path: ${modulePath}`);
-                                errorLines.push(`   Module Path: ${modulePath}`);
-                                errorLines.push(`   Workspace Path: ${this.workspacePath}`);
-                                errorLines.push(`   Error Code: ${err.code || 'N/A'}`);
-                                errorLines.push(`   Error Message: ${err.message || 'Unknown error'}`);
-                                if (err.code === 'ENOENT') {
-                                    errorLines.push('💡 Hint: File or directory not found. Check if the module path is correct.');
-                                }
-                                else if (err.code === 'EACCES') {
-                                    errorLines.push('💡 Hint: Permission denied. Check file permissions.');
-                                }
-                                else if (err.message && err.message.includes('pgpm.plan')) {
-                                    errorLines.push('💡 Hint: pgpm.plan file issue. Check if the plan file exists and is valid.');
-                                }
-                                log.error(errorLines.join('\n'));
-                                console.error(err);
-                                throw types_1.errors.DEPLOYMENT_FAILED({
-                                    type: 'Deployment',
-                                    module: extension
-                                });
-                            }
-                            await pgPool.query(pkg.sql);
-                            if (opts.deployment.cache) {
-                                deployFastCache[cacheKey] = pkg;
-                            }
+                            log.info(`↩️ Fast deploy unavailable for ${extension} (${outcome}); using per-change path.`);
                         }
-                        else {
+                        {
                             try {
                                 const client = new client_1.PgpmMigrate(opts.pg);
                                 // Only apply toChange to the target module, not its dependencies

package/esm/apply/apply-spec.js

@@ -33,14 +33,14 @@ export 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;
@@ -62,8 +62,83 @@ export 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 ?? basename(dirname(specPath));
     if (typeof name !== 'string' || !name) {

package/esm/apply/index.js

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

package/esm/apply/materialize.js

@@ -4,6 +4,7 @@ import { join, resolve } from 'path';
 import { bundleFromModule, materializeBundle, transpileBundle, verifyBundle } from '@pgpmjs/bundle';
 import { loadModule, makeSchemaTranspiler } from '@pgpmjs/transform';
 import { hasApplySpec, readApplySpec } from './apply-spec';
+import { isReuseSpec, materializeReuseModule, resolveSharedModuleName } from './reuse';
 // Functions that take a bare schema name as a string-literal first argument.
 // The AST pass only remaps dotted literals ('schema.object'); these helpers
 // (ubiquitous in verify scripts) name the schema alone, so a string-level
@@ -51,6 +52,8 @@ export async function materializeApplyModule(options) {
     const { renameChange, transformScript, result } = makeSchemaTranspiler({
         schemaMap: spec.schemas,
         routes: spec.route,
+        extensions: spec.extensions,
+        roles: spec.roles,
         transform: {
             prePasses: [schemaNameLiteralPass],
             assumeSchemasExist: targetSchemas
@@ -94,7 +97,10 @@ const materializedCache = new Map();
 export async function resolveEffectiveModulePath(moduleName, modulePath, moduleMap, workspacePath) {
     if (!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 = readApplySpec(modulePath);
@@ -106,8 +112,15 @@ export async function resolveEffectiveModulePath(moduleName, modulePath, moduleM
             `.`);
     }
     const sourceDir = resolve(workspacePath, sourceModule.path);
+    if (isReuseSpec(spec)) {
+        const result = await materializeReuseModule({ sourceDir, spec });
+        materializedCache.set(`${modulePath}::${result.sharedName}`, result.shared.outDir);
+        materializedCache.set(`${modulePath}::${result.perTenantName}`, result.perTenant.outDir);
+        const outDir = moduleName === resolveSharedModuleName(spec) ? result.shared.outDir : result.perTenant.outDir;
+        return outDir;
+    }
     const { outDir } = await materializeApplyModule({ sourceDir, spec });
-    materializedCache.set(modulePath, outDir);
+    materializedCache.set(cacheKey, outDir);
     return outDir;
 }
 /** Test seam: clear the per-process materialization cache. */