@sensigo/realm-cli 0.13.0 → 0.14.1

package/dist/extensions/load-project-extensions.js

@@ -1,31 +1,59 @@
-// load-project-extensions.ts — the ONE loader for workflow-declared project extension modules.
+// load-project-extensions.ts — the ONE project loader: workflow-declared extension CODE
+// modules (#117) plus the deployment MANIFEST (`<deployment root>/realm.yaml`, v0.14) that
+// owns ALL deployment configuration — adapter construction (built-in catalog + custom
+// factories), handler/processor construction config, secret bindings, gate-notifier config.
 //
-// Every step-executing or config-validating CLI entry point (run, agent, listen, serve, mcp,
-// test, validate, register, watch) resolves extensions through this function. Core resolves and
-// stores PATHS only (source_dir / trust_root / declared relative paths on the definition) — the
-// dynamic import lives here, in the CLI composition layer.
+// Every step-executing or config-validating CLI entry point (run, agent, listen, serve,
+// mcp, test, validate, register, watch) resolves through this function. Core validates
+// SHAPES and stores PATHS only — fs, dynamic import, secret resolution, and construction
+// live here, in the CLI composition layer.
 //
-// Trust model: extension module paths originate ONLY from operator-registered workflow
-// definitions or from the operator-typed --extensions-module flag — never from request data.
-// Declared paths resolve against the definition's source_dir and must realpath-contain within
-// its trust_root (nearest package.json/.git ancestor, derived at registration time).
+// Anchor mechanics (v6 §1): definitions WITH trust_root → manifest at
+// `<trust_root>/realm.yaml`, loaded iff present (absent = defaults only; no walking).
+// Definitions WITHOUT trust_root (agent-origin, from-string) → the DAEMON's deployment
+// root via `--project` (default cwd for serve/agent/run ONLY; `realm mcp` has NO default —
+// its stdio cwd is CLIENT-controlled, a recorded security decision).
+//
+// Trust model: manifest-write = credential-redirection = code-write-equivalent. Extension
+// module paths and manifest `use:` refs originate ONLY from operator-registered definitions,
+// the operator's deployment root, or operator-typed flags — never from request data.
 import { createRequire } from 'node:module';
-import { realpathSync } from 'node:fs';
-import { resolve, sep } from 'node:path';
+import { readFileSync, realpathSync, existsSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { createDefaultRegistry } from '@sensigo/realm';
-import { computeExtensionIdentity, errorExtensionIdentityEntry } from './extension-identity.js';
+import { load as loadYaml } from 'js-yaml';
+import { createDefaultRegistry, WorkflowError, validateDeploymentManifest, collectManifestSecretRefs, interpolateConfigTree, findSecretRefSites, VERSION, GitHubAdapter, SlackAdapter, GenericHttpAdapter, AirtableAdapter, GorgiasAdapter, ShopifyAdapter, NotionAdapter, ParcelPanelAdapter, FileSystemAdapter, MockAdapter, } from '@sensigo/realm';
+import { computeExtensionIdentity, errorExtensionIdentityEntry, sha256HexOf, } from './extension-identity.js';
+import { resolveManifestSecrets, redactSecretValues } from './manifest-secrets.js';
 /** Registration surfaces of a declarative extension module, keyed by export map name. */
 const EXTENSION_SURFACES = [
     { mapKey: 'adapters', type: 'adapter', probeMembers: ['fetch', 'create', 'update'] },
     { mapKey: 'handlers', type: 'handler', probeMembers: ['execute'] },
     { mapKey: 'processors', type: 'processor', probeMembers: ['process'] },
 ];
+const PROBE_MEMBERS = {
+    adapter: ['fetch', 'create', 'update'],
+    handler: ['execute'],
+    processor: ['process'],
+};
+/**
+ * The built-in adapter catalog: name → factory wrapping the constructor. The factory
+ * contract is the ONE construction shape: `({ id, config }) => instance`.
+ * `filesystem` and `mock` are config-less — declaring `config:` for them is an ERROR.
+ */
+const BUILTIN_ADAPTER_CATALOG = {
+    github: { factory: ({ id, config }) => new GitHubAdapter(id, config) },
+    slack: { factory: ({ id, config }) => new SlackAdapter(id, config) },
+    http: { factory: ({ id, config }) => new GenericHttpAdapter(id, config) },
+    airtable: { factory: ({ id, config }) => new AirtableAdapter(id, config) },
+    gorgias: { factory: ({ id, config }) => new GorgiasAdapter(id, config) },
+    shopify: { factory: ({ id, config }) => new ShopifyAdapter(id, config) },
+    notion: { factory: ({ id, config }) => new NotionAdapter(id, config) },
+    parcelpanel: { factory: ({ id, config }) => new ParcelPanelAdapter(id, config) },
+    filesystem: { factory: ({ id }) => new FileSystemAdapter(id), configless: true },
+    mock: { factory: ({ id }) => new MockAdapter(id, {}), configless: true },
+};
 const DEFAULT_REGISTRY_CACHE_KEY = '\u0000default-registry\u0000';
-// Process-lifetime cache keyed by the ORDERED list of resolved module paths (plus a sentinel
-// for the extension-less default registry). Restart-required semantics: module CONTENT changes
-// in long-lived processes (listen parent, serve, mcp) need a process restart — there is no
-// cache-busting re-import (ESM module cache would defeat it anyway).
 const cache = new Map();
 /** @internal Test-only: clears the process-lifetime registry cache. */
 export function clearProjectExtensionsCache() {
@@ -55,81 +83,406 @@ function normalizeDeclared(extensions) {
     return typeof extensions === 'string' ? [extensions] : extensions;
 }
 /**
- * Loads the project extension modules declared by a workflow definition (or an operator
- * override) and returns a registry (defaults + extensions applied) plus a manifest of what
- * was loaded. No `extensions` on the definition and no override → `createDefaultRegistry()`
- * plus an empty manifest — the byte-identical fallback, cached process-wide.
+ * Orphaned-manifest guard (#123): throws when a `realm.yaml` sits anywhere in the span
+ * `[sourceDir, trustRoot)` — from the workflow directory walking UP to, but NOT including,
+ * the trust root. Such a manifest is silently ignored by the strict-single-location loader,
+ * so surfacing it loudly turns a confusing downstream `adapter 'X' not registered` (or total
+ * silence under validate/sentinel/fixture paths) into an actionable placement error.
  *
- * Precedence: defaults < legacy env-gated built-ins (applied by `realm agent`, see agent.ts)
- * < declared extensions < --extensions-module override.
+ * Path-keyed (takes the two directories, NOT a definition) so callers that don't stamp a
+ * definition — `realm workflow validate` on an extension-free workflow — can reuse it with a
+ * `findTrustRoot(workflowDir)` result. Callers guarantee both paths are known: the loader
+ * calls it only when a definition carries both source_dir and trust_root (agent-origin /
+ * from-string definitions have no source_dir → never scanned). A workflow dir that is its
+ * own trust root has an empty span (no-op). Never scans at or above trust_root — a stray at
+ * trust_root IS the loaded manifest; Case C (above trust_root) is deliberately out of #123.
+ */
+export function checkForOrphanedManifests(sourceDir, trustRoot) {
+    if (sourceDir === trustRoot)
+        return; // empty span
+    const orphans = [];
+    let current = sourceDir;
+    // Walk [source_dir, trust_root): stop BEFORE trust_root; guard against a source_dir that
+    // is not actually under trust_root (never terminates otherwise).
+    while (current !== trustRoot) {
+        const candidate = join(current, 'realm.yaml');
+        if (existsSync(candidate))
+            orphans.push(candidate);
+        const parent = dirname(current);
+        if (parent === current)
+            break; // hit the filesystem root without meeting trust_root
+        current = parent;
+    }
+    if (orphans.length === 0)
+        return;
+    const found = orphans.length === 1
+        ? `Deployment manifest at '${orphans[0]}'`
+        : `Deployment manifests at ${orphans.map((o) => `'${o}'`).join(', ')}`;
+    const nearest = orphans[0];
+    // Throw WorkflowError (VALIDATION class — the same class the yaml-loader raises for
+    // structural validation failures) so `realm workflow validate`'s existing
+    // `if (err instanceof WorkflowError)` handler renders it as `Invalid:` rather than a stack
+    // trace, and every execution/registration path treats it as a load failure.
+    throw new WorkflowError(`${found} will NOT be loaded — manifests are read only from the deployment root ` +
+        `'${join(trustRoot, 'realm.yaml')}'. Move it to '${join(trustRoot, 'realm.yaml')}' ` +
+        `(the nearest package.json/.git ancestor of the workflow), or add a package.json/.git ` +
+        `at '${dirname(nearest)}' to make that the deployment root.`, {
+        code: 'VALIDATION_WORKFLOW_SCHEMA',
+        category: 'VALIDATION',
+        agentAction: 'report_to_user',
+        retryable: false,
+    });
+}
+/**
+ * Resolves the deployment root and loads+validates the manifest document when present.
+ * Definitions WITH trust_root anchor there; definitions WITHOUT it anchor at the daemon's
+ * `--project` root (absent → no manifest, defaults only — NO walking, NO error).
+ */
+function loadManifestContext(definition, projectDir) {
+    const root = definition.trust_root ?? projectDir;
+    if (root === undefined)
+        return undefined;
+    // Orphaned-manifest guard (#123): manifests load ONLY from <trust_root>/realm.yaml.
+    // A realm.yaml placed anywhere in the span [source_dir, trust_root) — the workflow dir
+    // or an intermediate dir below the resolved trust_root — is silently ignored, which is
+    // the common misplacement (workflow in a repo subdir whose package.json/.git is an
+    // ancestor). Detect it and fail loud BEFORE loading, consistent with the invalid-YAML /
+    // schema-error throws below. Runs before the trust_root load: a correctly-placed
+    // manifest does NOT excuse a stray one below it (the stray is still ignored, still
+    // operator error). Detection-only — LOADING semantics stay strict-single-location.
+    // Case C (realm.yaml ABOVE trust_root) is deliberately NOT scanned (see #123).
+    //
+    // Scan only when the definition carries both source_dir and trust_root: agent-origin /
+    // from-string definitions have no source_dir (and reach the manifest via `--project`),
+    // and `root === trust_root` here whenever trust_root is defined (root = trust_root ??
+    // projectDir), so passing definition.trust_root preserves the previous trust_root===root
+    // gate — the `--project`-fallback path never scans.
+    if (definition.source_dir !== undefined && definition.trust_root !== undefined) {
+        checkForOrphanedManifests(definition.source_dir, definition.trust_root);
+    }
+    const manifestPath = join(root, 'realm.yaml');
+    let bytes;
+    try {
+        bytes = readFileSync(manifestPath);
+    }
+    catch {
+        return undefined; // absent manifest = defaults only, valid for config-free projects
+    }
+    let raw;
+    try {
+        raw = loadYaml(bytes.toString('utf8'));
+    }
+    catch (err) {
+        throw new Error(`Deployment manifest '${manifestPath}' is not valid YAML: ${errMsg(err)}`);
+    }
+    const errors = validateDeploymentManifest(raw);
+    if (errors.length > 0) {
+        throw new Error(`Deployment manifest '${manifestPath}' is invalid:\n  ${errors.join('\n  ')}`);
+    }
+    const document = raw;
+    // dotenv bytes participate in the freshness hash ONLY (rotation detection) — never in
+    // drift evidence.
+    const dotenvPath = join(dirname(manifestPath), document.secrets?.dotenv ?? '.env');
+    let dotenvBytes;
+    try {
+        dotenvBytes = readFileSync(dotenvPath);
+    }
+    catch {
+        dotenvBytes = Buffer.alloc(0);
+    }
+    return {
+        document,
+        path: manifestPath,
+        realPath: realpathOrFail(manifestPath, `deployment manifest '${manifestPath}'`),
+        dir: dirname(manifestPath),
+        rootReal: realpathOrFail(root, `deployment root '${root}'`),
+        bytes,
+        contentHash: sha256HexOf(bytes),
+        dotenvBytes,
+    };
+}
+/** `use:` disambiguation — contains `/` or a module file extension → module ref. */
+function isModuleRef(use) {
+    const beforeHash = use.split('#')[0];
+    return beforeHash.includes('/') || /\.(js|mjs|cjs|ts|mts|cts)$/.test(beforeHash);
+}
+/**
+ * Loads the project extensions and deployment configuration for a definition:
+ * workflow-declared CODE modules + the deployment manifest's constructed instances,
+ * one registry, one namespace, one collision map. No extensions, no manifest → the
+ * process-stable filesystem-only default registry.
  *
  * CONTRACT: returned registries are shared process-lifetime cache entries. The only
- * permitted mutation is `getOrCreateRateLimiter` (serve bucket persistence, by design);
- * any tier composition on top requires `ExtensionRegistry.clone()`.
+ * permitted mutation is `getOrCreateRateLimiter` (serve bucket persistence, by design).
  */
 export async function loadProjectExtensions(definition, opts) {
+    const secretMode = opts?.secretMode ?? 'real';
     const moduleRefs = resolveModuleRefs(definition, opts?.overrideModule);
-    if (moduleRefs === undefined) {
-        // Extension-free fallback: byte-identical default registry, process-lifetime cached
-        // (the sentinel keeps rate-limiter buckets stable across requests in serve/mcp too).
+    const manifestCtx = loadManifestContext(definition, opts?.projectDir);
+    if (moduleRefs === undefined && manifestCtx === undefined) {
+        // Extension-free, manifest-free fallback: process-stable default registry.
         let entry = cache.get(DEFAULT_REGISTRY_CACHE_KEY);
         if (entry === undefined) {
-            entry = { registry: createDefaultRegistry(), manifest: emptyManifest() };
+            entry = { result: { registry: createDefaultRegistry(), manifest: emptyManifest() } };
             cache.set(DEFAULT_REGISTRY_CACHE_KEY, entry);
         }
-        return entry;
+        return entry.result;
     }
-    const cacheKey = moduleRefs.map((m) => m.resolved).join('\n');
+    // Resolve manifest `use:` module refs up front — they are part of the cache key.
+    const useModuleRefs = manifestCtx !== undefined ? resolveUseModuleRefs(manifestCtx) : new Map();
+    const cacheKey = [
+        `mode:${secretMode}`,
+        `manifest:${manifestCtx?.realPath ?? '\u0000none'}`,
+        `root:${manifestCtx?.rootReal ?? '\u0000none'}`,
+        ...(moduleRefs ?? []).map((m) => `ext:${m.resolved}`),
+        ...[...useModuleRefs.values()].sort().map((p) => `use:${p}`),
+    ].join('\n');
+    const freshness = manifestCtx !== undefined
+        ? sha256HexOf(Buffer.concat([manifestCtx.bytes, Buffer.from('\u0000'), manifestCtx.dotenvBytes]))
+        : undefined;
     const cached = cache.get(cacheKey);
-    if (cached !== undefined)
-        return cached;
+    if (cached !== undefined && cached.freshness === freshness)
+        return cached.result;
+    // freshness mismatch → rebuild-and-REPLACE (dotenv rotation / manifest edit reaches
+    // the next run without restart; rate-limiter buckets reset with the new registry).
     const registry = createDefaultRegistry();
     const builtinNames = {
         adapter: new Set(registry.names('adapter')),
         handler: new Set(registry.names('handler')),
         processor: new Set(registry.names('processor')),
     };
-    // `${type}:${name}` → declared path of the module that first claimed it.
     const claimedBy = new Map();
     const manifest = {
-        modules: moduleRefs,
+        modules: moduleRefs ?? [],
         adapters: [],
         handlers: [],
         processors: [],
     };
     const moduleFormats = new Map();
-    for (const ref of moduleRefs) {
-        const { exported, format } = await importExtensionModule(ref);
+    for (const ref of moduleRefs ?? []) {
+        const { namespace, format } = await importModuleNamespace(ref.resolved, ref.declared);
         moduleFormats.set(ref.resolved, format);
-        applyModule(exported, ref, registry, builtinNames, claimedBy, manifest);
+        applyModule(defaultExportOf(namespace, ref.declared), ref, registry, builtinNames, claimedBy, manifest);
+    }
+    const sentinelWarnings = [];
+    let notifiers;
+    let secretValues;
+    const identityModules = (moduleRefs ?? []).map((ref) => ({
+        declared: ref.declared,
+        resolved: ref.resolved,
+        format: moduleFormats.get(ref.resolved) ?? 'esm',
+    }));
+    let secretNames = [];
+    if (manifestCtx !== undefined) {
+        const applied = await applyDeploymentManifest(manifestCtx, useModuleRefs, registry, builtinNames, claimedBy, manifest, secretMode, sentinelWarnings);
+        notifiers = applied.notifiers;
+        secretNames = applied.secretNames;
+        secretValues = applied.secretValues;
+        for (const [use, real] of useModuleRefs) {
+            identityModules.push({
+                declared: use,
+                resolved: real,
+                format: moduleFormats.get(real) ?? applied.useFormats.get(real) ?? 'esm',
+            });
+        }
     }
-    // Drift evidence (issue #119): capture the identity of the loaded code ONCE per cache
-    // entry, at module-LOAD time (what is actually in memory). Capture failure NEVER fails
-    // loading — an error entry is attached and logged instead. The extension-less sentinel
-    // above gets NO identity: extension-free runs record nothing.
+    // Drift evidence: identity captured ONCE per cache entry at module-LOAD time. The
+    // manifest contributes its content hash (never a sweep root); `use:`-resolved module
+    // FILES contribute sweep roots exactly like extension-list modules; secret NAMES are
+    // recorded, never compared; the freshness hash is NEVER recorded.
     const overrideActive = opts?.overrideModule !== undefined;
     try {
-        registry.setIdentity(computeExtensionIdentity(moduleRefs.map((ref) => ({
-            declared: ref.declared,
-            resolved: ref.resolved,
-            format: moduleFormats.get(ref.resolved) ?? 'esm',
-        })), {
+        registry.setIdentity(computeExtensionIdentity(identityModules, {
             ...(definition.trust_root !== undefined ? { trustRoot: definition.trust_root } : {}),
             ...(overrideActive ? { overrideActive: true } : {}),
+            ...(manifestCtx !== undefined
+                ? { manifest: { path: manifestCtx.path, content_hash: manifestCtx.contentHash } }
+                : {}),
+            secretNames,
         }));
     }
     catch (err) {
         console.error(`[realm] extension identity capture failed: ${errMsg(err)} — drift evidence will carry an error entry for this load.`);
         registry.setIdentity(errorExtensionIdentityEntry(`identity capture failed: ${errMsg(err)}`, overrideActive ? { overrideActive: true } : {}));
     }
-    const result = { registry, manifest };
-    cache.set(cacheKey, result);
+    const result = {
+        registry,
+        manifest,
+        ...(notifiers !== undefined ? { notifiers } : {}),
+        ...(sentinelWarnings.length > 0 ? { sentinelWarnings } : {}),
+        ...(secretValues !== undefined && secretValues.length > 0 ? { secretValues } : {}),
+    };
+    cache.set(cacheKey, { result, ...(freshness !== undefined ? { freshness } : {}) });
     return result;
 }
+/** Resolves every manifest `use:` module ref (realpathed + containment-checked). */
+function resolveUseModuleRefs(ctx) {
+    const resolvedRefs = new Map();
+    const sections = [
+        ctx.document.adapters,
+        ctx.document.handlers,
+        ctx.document.processors,
+    ];
+    for (const section of sections) {
+        for (const entry of Object.values(section ?? {})) {
+            if (entry.use === undefined || !isModuleRef(entry.use))
+                continue;
+            const modulePath = entry.use.split('#')[0];
+            if (resolvedRefs.has(entry.use))
+                continue;
+            const resolved = resolve(ctx.dir, modulePath);
+            const real = realpathOrFail(resolved, `manifest module '${modulePath}' (from '${ctx.path}', resolved: ${resolved})`);
+            if (!isContainedIn(real, ctx.rootReal)) {
+                throw new Error(`Deployment manifest module '${modulePath}' resolves to '${real}', which is OUTSIDE ` +
+                    `the deployment root '${ctx.rootReal}'. Manifest 'use:' modules must live within ` +
+                    `the deployment root — move the module inside it, or fix the reference in '${ctx.path}'.`);
+            }
+            resolvedRefs.set(entry.use, real);
+        }
+    }
+    return resolvedRefs;
+}
+/** Parses/constructs/registers everything the manifest declares. */
+async function applyDeploymentManifest(ctx, useModuleRefs, registry, builtinNames, claimedBy, manifest, secretMode, sentinelWarnings) {
+    const refs = collectManifestSecretRefs(ctx.document);
+    const resolved = resolveManifestSecrets(refs, ctx.document.secrets, ctx.dir, secretMode);
+    const resolveName = (name) => resolved.values[name] ?? '';
+    const secretValues = Object.values(resolved.values);
+    const useFormats = new Map();
+    const secretBearingHandlers = [];
+    const secretBearingProcessors = [];
+    const sections = [
+        { key: 'adapters', type: 'adapter' },
+        { key: 'handlers', type: 'handler' },
+        { key: 'processors', type: 'processor' },
+    ];
+    for (const section of sections) {
+        for (const [name, entry] of Object.entries(ctx.document[section.key] ?? {})) {
+            const site = `${section.key}.${name}`;
+            if (entry.use === undefined) {
+                throw new Error(`Deployment manifest '${ctx.path}': ${site} needs 'use:' — a catalog name ` +
+                    `(adapters) or a module reference './path.js#Export'.`);
+            }
+            const factory = await resolveEntryFactory(ctx, useModuleRefs, useFormats, section.type, name, entry, site);
+            const hasRefs = findSecretRefSites(entry.config, site).sites.length > 0;
+            if (section.type === 'handler' && hasRefs)
+                secretBearingHandlers.push(name);
+            if (section.type === 'processor' && hasRefs)
+                secretBearingProcessors.push(name);
+            const config = interpolateConfigTree(entry.config ?? {}, resolveName);
+            let instance;
+            try {
+                instance = factory({ id: name, config });
+            }
+            catch (err) {
+                const redacted = redactSecretValues(`Deployment manifest '${ctx.path}': constructing ${site} (use: ${entry.use}) failed: ${errMsg(err)}`, secretValues);
+                if (secretMode === 'sentinel') {
+                    // Sentinel degrade: warn-and-skip — never a hard failure, never silent.
+                    sentinelWarnings.push(`${redacted} (sentinel mode — entry skipped)`);
+                    continue;
+                }
+                throw new Error(redacted);
+            }
+            probeShape(instance, section.type, PROBE_MEMBERS[section.type], name, {
+                declared: `${ctx.path}#${site}`,
+                resolved: ctx.realPath,
+            });
+            const claimKey = `${section.type}:${name}`;
+            const previousClaim = claimedBy.get(claimKey);
+            if (previousClaim !== undefined) {
+                throw new Error(`Extension ${section.type} '${name}' is declared by both '${previousClaim}' and the ` +
+                    `deployment manifest '${ctx.path}' — manifest entries and code-module exports ` +
+                    `share one namespace; names must be unique.`);
+            }
+            claimedBy.set(claimKey, `manifest ${ctx.path}`);
+            if (builtinNames[section.type].has(name)) {
+                console.warn(`[realm] manifest ${section.type} '${name}' overrides the built-in ${section.type} '${name}'.`);
+            }
+            registry.register(section.type, name, instance);
+            manifest[section.key].push(name);
+        }
+    }
+    if (secretBearingHandlers.length > 0)
+        manifest.secret_bearing_handlers = secretBearingHandlers;
+    if (secretBearingProcessors.length > 0)
+        manifest.secret_bearing_processors = secretBearingProcessors;
+    let notifiers;
+    const slackGate = ctx.document.notifiers?.slack_gate;
+    if (slackGate !== undefined) {
+        notifiers = {
+            slack_gate: interpolateConfigTree(slackGate.config, resolveName),
+        };
+    }
+    return {
+        ...(notifiers !== undefined ? { notifiers } : {}),
+        secretNames: [...new Set(refs.map((r) => r.name))].sort(),
+        // Values-only, frozen, real-mode only: the agent redaction feed. Never persisted.
+        secretValues: resolved.sentinel
+            ? Object.freeze([])
+            : Object.freeze([...new Set(Object.values(resolved.values))].filter((v) => v.length >= 4)),
+        useFormats,
+    };
+}
+/** Resolves an entry's factory: catalog name (adapters only) or module ref `#Export`. */
+async function resolveEntryFactory(ctx, useModuleRefs, useFormats, type, name, entry, site) {
+    const use = entry.use;
+    if (!isModuleRef(use)) {
+        if (type !== 'adapter') {
+            throw new Error(`Deployment manifest '${ctx.path}': ${site} — there is no built-in catalog for ` +
+                `${type}s; use a module reference './path.js#ExportName'.`);
+        }
+        const catalogEntry = BUILTIN_ADAPTER_CATALOG[use];
+        if (catalogEntry === undefined) {
+            throw new Error(`Deployment manifest '${ctx.path}': ${site} — unknown catalog adapter '${use}'. ` +
+                `Valid catalog names (realm v${VERSION}): ${Object.keys(BUILTIN_ADAPTER_CATALOG).join(', ')}. ` +
+                `For a custom adapter use a module reference './path.js#ExportName'.`);
+        }
+        if (catalogEntry.configless === true && entry.config !== undefined) {
+            throw new Error(`Deployment manifest '${ctx.path}': ${site} — catalog adapter '${use}' takes no ` +
+                `config; remove the 'config:' block.`);
+        }
+        return catalogEntry.factory;
+    }
+    const [modulePath, exportName] = use.split('#');
+    const real = useModuleRefs.get(use) ?? useModuleRefs.get(modulePath);
+    if (real === undefined) {
+        throw new Error(`Deployment manifest '${ctx.path}': ${site} — unresolved module '${use}'.`);
+    }
+    const { namespace, format } = await importModuleNamespace(real, `${ctx.path}#${site}`);
+    useFormats.set(real, format);
+    const candidate = pickExport(namespace, exportName, use, ctx.path, site);
+    if (typeof candidate !== 'function') {
+        throw new Error(`Deployment manifest '${ctx.path}': ${site} — '${use}' must export a FACTORY ` +
+            `(ctx: { id, config }) => instance; got ${typeof candidate}.`);
+    }
+    return candidate;
+}
+/** Picks the named (or default) export, naming the available exports on a miss. */
+function pickExport(namespace, exportName, use, manifestPath, site) {
+    const unwrapped = unwrapCjsNamespace(namespace);
+    const wanted = exportName ?? 'default';
+    const candidate = unwrapped[wanted];
+    if (candidate !== undefined)
+        return candidate;
+    const available = Object.keys(unwrapped).filter((k) => k !== '__esModule');
+    throw new Error(`Deployment manifest '${manifestPath}': ${site} — module '${use}' has no ` +
+        `${exportName !== undefined ? `export '${exportName}'` : 'default export'}. ` +
+        `Available exports: ${available.length > 0 ? available.join(', ') : '(none)'}.`);
+}
+/** Flattens the tsc-CJS `{ default: { __esModule, ...exports } }` interop wrapper. */
+function unwrapCjsNamespace(namespace) {
+    const def = namespace['default'];
+    if (typeof def === 'object' &&
+        def !== null &&
+        def['__esModule'] === true) {
+        return { ...namespace, ...def };
+    }
+    return namespace;
+}
 /**
- * Resolves the list of modules to load. Returns undefined for the extension-free fallback.
- * Enforces the trust model for declared modules: agent-origin refusal, re-register guidance
- * when resolution metadata is missing, and realpath containment within trust_root.
+ * Resolves the list of extension CODE modules. Returns undefined when none are declared.
+ * Enforces the trust model: agent-origin refusal, re-register guidance when resolution
+ * metadata is missing, and realpath containment within trust_root.
  */
 function resolveModuleRefs(definition, overrideModule) {
     if (overrideModule !== undefined) {
@@ -168,60 +521,68 @@ function resolveModuleRefs(definition, overrideModule) {
     });
 }
 /**
- * Imports one extension module (jiti-bridged for TypeScript paths) and returns its default
- * export plus the load format (descriptive metadata for the drift-evidence identity record:
- * ts-jiti for TypeScript paths, cjs for .cjs / detected CJS-interop wrappers, esm otherwise).
+ * Imports one module (jiti-bridged for TypeScript paths) and returns its full namespace
+ * plus the load format (ts-jiti for TypeScript paths, cjs for .cjs / detected CJS-interop
+ * wrappers, esm otherwise).
  */
-async function importExtensionModule(ref) {
-    const isTypescript = /\.(ts|mts|cts)$/.test(ref.resolved);
-    let mod;
+async function importModuleNamespace(resolvedPath, label) {
+    const isTypescript = /\.(ts|mts|cts)$/.test(resolvedPath);
+    let namespace;
     if (isTypescript) {
-        mod = await importViaJiti(ref);
+        namespace = await importViaJiti(resolvedPath, label);
     }
     else {
         try {
-            mod = (await import(pathToFileURL(ref.resolved).href));
+            namespace = (await import(pathToFileURL(resolvedPath).href));
         }
         catch (err) {
-            throw new Error(`Failed to import extension module '${ref.declared}' (${ref.resolved}): ${errMsg(err)}`);
+            throw new Error(`Failed to import module '${label}' (${resolvedPath}): ${errMsg(err)}`);
         }
     }
     let format = isTypescript
         ? 'ts-jiti'
-        : ref.resolved.endsWith('.cjs')
+        : resolvedPath.endsWith('.cjs')
             ? 'cjs'
             : 'esm';
-    let exported = mod['default'];
+    const def = namespace['default'];
+    if (!isTypescript &&
+        typeof def === 'object' &&
+        def !== null &&
+        def['__esModule'] === true) {
+        format = 'cjs';
+    }
+    return { namespace, format };
+}
+/** The workflow-extensions default-export contract: unwraps tsc-CJS interop, requires default. */
+function defaultExportOf(namespace, declared) {
+    let exported = namespace['default'];
     // CJS-ESM interop: `import()` of a tsc-CommonJS build ("type" not "module") yields
     // namespace.default = module.exports = { __esModule: true, default: <manifest> }.
-    // Unwrap that wrapper so CJS consumers get the same contract as ESM ones.
     if (typeof exported === 'object' &&
         exported !== null &&
         exported['__esModule'] === true &&
         'default' in exported) {
         exported = exported['default'];
-        if (!isTypescript)
-            format = 'cjs';
     }
     if (exported === undefined) {
-        throw new Error(`Extension module '${ref.declared}' has no default export — export a declarative object: ` +
+        throw new Error(`Extension module '${declared}' has no default export — export a declarative object: ` +
             `export default { adapters: { name: instance }, handlers: { ... }, processors: { ... } }`);
     }
-    return { exported, format };
+    return exported;
 }
 /**
  * TypeScript modules load through jiti resolved from the MODULE'S OWN directory (the consumer
  * project's node_modules) — never from the CLI install (npx/global installs carry no jiti).
  * Compiled JS is the documented default; jiti is a consumer-side optional peer.
  */
-async function importViaJiti(ref) {
-    const requireFromModule = createRequire(ref.resolved);
+async function importViaJiti(resolvedPath, label) {
+    const requireFromModule = createRequire(resolvedPath);
     let jitiPath;
     try {
         jitiPath = requireFromModule.resolve('jiti');
     }
     catch {
-        throw new Error(`Extension module '${ref.declared}' (${ref.resolved}) is TypeScript, but 'jiti' is not ` +
+        throw new Error(`Module '${label}' (${resolvedPath}) is TypeScript, but 'jiti' is not ` +
             `installed in your project. Install jiti in your project (npm install --save-dev jiti), ` +
             `or compile the module to JS and declare the compiled path.`);
     }
@@ -236,14 +597,14 @@ async function importViaJiti(ref) {
         // jiti v2: createJiti(parentPath).import(path) → module namespace.
         const createJiti = jitiModule['createJiti'];
         if (typeof createJiti === 'function') {
-            const jiti = createJiti(ref.resolved);
-            return (await jiti.import(ref.resolved));
+            const jiti = createJiti(resolvedPath);
+            return (await jiti.import(resolvedPath));
         }
         // jiti v1: default export is a factory returning a require-like function.
         const factory = jitiModule['default'];
         if (typeof factory === 'function') {
-            const jitiRequire = factory(ref.resolved, { interopDefault: false });
-            const required = jitiRequire(ref.resolved);
+            const jitiRequire = factory(resolvedPath, { interopDefault: false });
+            const required = jitiRequire(resolvedPath);
             if (typeof required === 'object' && required !== null && 'default' in required) {
                 return required;
             }
@@ -251,7 +612,7 @@ async function importViaJiti(ref) {
         }
     }
     catch (err) {
-        throw new Error(`Failed to import TypeScript extension module '${ref.declared}' via jiti: ${errMsg(err)}`);
+        throw new Error(`Failed to import TypeScript module '${label}' via jiti: ${errMsg(err)}`);
     }
     throw new Error(`Unrecognized 'jiti' package shape at '${jitiPath}' — upgrade jiti in your project, or ` +
         `compile the extension module to JS.`);
@@ -349,10 +710,14 @@ function warnOnIdMismatch(impl, type, name, ref) {
 }
 /**
  * Builds a `registryProvider` for the MCP server (serve / mcp stdio): resolves each
- * definition's extensions through the process-lifetime loader cache. An operator override
- * replaces declared modules for EVERY definition served by this process.
+ * definition through the process-lifetime project loader. `--extensions-module` overrides
+ * CODE modules; `projectDir` anchors the manifest for definitions without trust_root
+ * (`realm mcp` passes it ONLY when --project was given — no cwd default there).
  */
-export function makeRegistryProvider(overrideModule) {
-    return async (definition) => (await loadProjectExtensions(definition, overrideModule !== undefined ? { overrideModule } : {})).registry;
+export function makeRegistryProvider(overrideModule, projectDir) {
+    return async (definition) => (await loadProjectExtensions(definition, {
+        ...(overrideModule !== undefined ? { overrideModule } : {}),
+        ...(projectDir !== undefined ? { projectDir } : {}),
+    })).registry;
 }
 //# sourceMappingURL=load-project-extensions.js.map