@bleedingdev/modern-js-plugin-bff 3.5.0-ultramodern.30 → 3.5.0-ultramodern.32

package/dist/esm-node/runtime/data-platform/validation.mjs

@@ -0,0 +1,129 @@
+import "node:module";
+import { buildScopeKey, createOperationId, hashString, isPlainObject, normalizeOrigin, sanitizeSegment, stableStringify } from "./codec.mjs";
+import { formatTraceparentHeader, parseTraceparentHeader } from "./trace.mjs";
+function validateSelectionPlan(plan, options = {}) {
+    const maxDepthLimit = options.maxDepth ?? 8;
+    const maxFieldsLimit = options.maxFields ?? 256;
+    const allowedLeafPaths = options.allowedLeafPaths ? new Set(options.allowedLeafPaths) : null;
+    const errors = [];
+    let maxDepth = 0;
+    let fieldCount = 0;
+    const walk = (node, path)=>{
+        if (!isPlainObject(node)) return void errors.push(`Selection node at "${path.join('.') || '<root>'}" must be an object`);
+        const keys = Object.keys(node);
+        if (0 === keys.length) return void errors.push(`Selection node at "${path.join('.') || '<root>'}" cannot be empty`);
+        for (const key of keys){
+            fieldCount += 1;
+            if (fieldCount > maxFieldsLimit) return void errors.push(`Selection has too many fields: ${String(fieldCount)} > ${String(maxFieldsLimit)}`);
+            const nextPath = [
+                ...path,
+                key
+            ];
+            const depth = nextPath.length;
+            if (depth > maxDepth) maxDepth = depth;
+            if (depth > maxDepthLimit) return void errors.push(`Selection exceeds maxDepth at "${nextPath.join('.')}" (${String(depth)} > ${String(maxDepthLimit)})`);
+            const value = node[key];
+            if (true === value) {
+                if (allowedLeafPaths && !allowedLeafPaths.has(nextPath.join('.'))) errors.push(`Unknown selected field "${nextPath.join('.')}"`);
+                continue;
+            }
+            if (!isPlainObject(value)) {
+                errors.push(`Invalid selection value at "${nextPath.join('.')}"; expected true or nested object`);
+                continue;
+            }
+            walk(value, nextPath);
+        }
+    };
+    walk(plan, []);
+    return {
+        ok: 0 === errors.length,
+        errors,
+        stats: {
+            maxDepth,
+            fieldCount
+        }
+    };
+}
+function createRequestEnvelope(input) {
+    if (input.requireTraceContext && !input.traceContext) throw new Error('Trace context is required for this request envelope');
+    const traceparent = input.traceContext ? formatTraceparentHeader(input.traceContext) : void 0;
+    const envelope = {
+        protocolVersion: input.protocolVersion ?? 1,
+        operationId: createOperationId(input.operation),
+        appNamespace: sanitizeSegment(input.scope.appNamespace),
+        origin: normalizeOrigin(input.scope.origin),
+        requestMode: input.requestMode ?? 'cache-first',
+        mutationMode: input.mutationMode,
+        scopeKey: buildScopeKey(input.scope),
+        input: input.requestInput,
+        inputHash: hashString(stableStringify(input.requestInput ?? null)),
+        selectionPlan: input.selectionPlan,
+        selectionHash: input.selectionPlan ? hashString(stableStringify(input.selectionPlan)) : void 0,
+        traceparent,
+        timestamp: input.timestamp ?? Date.now()
+    };
+    return envelope;
+}
+function validateRequestEnvelope(envelope, options = {}) {
+    const errors = [];
+    if (void 0 !== options.expectedProtocolVersion && envelope.protocolVersion !== options.expectedProtocolVersion) errors.push(`Protocol mismatch: expected ${String(options.expectedProtocolVersion)} but received ${String(envelope.protocolVersion)}`);
+    if (options.expectedNamespace && envelope.appNamespace !== options.expectedNamespace) errors.push(`Namespace mismatch: expected ${options.expectedNamespace} but received ${envelope.appNamespace}`);
+    if (options.expectedOrigin) {
+        const expectedOrigin = normalizeOrigin(options.expectedOrigin);
+        if (envelope.origin !== expectedOrigin) errors.push(`Origin mismatch: expected ${expectedOrigin} but received ${envelope.origin}`);
+    }
+    if (!envelope.operationId) errors.push('Missing operationId');
+    if (!envelope.scopeKey) errors.push('Missing scopeKey');
+    if (options.requireTraceContext && !envelope.traceparent) errors.push('Missing trace context');
+    if (envelope.traceparent && !parseTraceparentHeader(envelope.traceparent)) errors.push('Invalid traceparent header');
+    const computedInputHash = hashString(stableStringify(envelope.input ?? null));
+    if (computedInputHash !== envelope.inputHash) errors.push('Input hash mismatch');
+    if (envelope.selectionPlan) {
+        const computedSelectionHash = hashString(stableStringify(envelope.selectionPlan));
+        if (computedSelectionHash !== envelope.selectionHash) errors.push('Selection hash mismatch');
+    }
+    return {
+        ok: 0 === errors.length,
+        errors
+    };
+}
+function createHydrationEnvelope(input) {
+    const envelopeWithoutChecksum = {
+        protocolVersion: input.protocolVersion ?? 1,
+        runtimeVersion: input.runtimeVersion,
+        appNamespace: sanitizeSegment(input.scope.appNamespace),
+        origin: normalizeOrigin(input.scope.origin),
+        createdAt: input.createdAt ?? Date.now(),
+        payload: input.payload
+    };
+    const checksum = hashString(stableStringify(envelopeWithoutChecksum));
+    return {
+        ...envelopeWithoutChecksum,
+        checksum
+    };
+}
+function validateHydrationEnvelope(envelope, options = {}) {
+    const errors = [];
+    if (void 0 !== options.expectedProtocolVersion && envelope.protocolVersion !== options.expectedProtocolVersion) errors.push(`Protocol mismatch: expected ${String(options.expectedProtocolVersion)} but received ${String(envelope.protocolVersion)}`);
+    if (options.expectedNamespace && envelope.appNamespace !== options.expectedNamespace) errors.push(`Namespace mismatch: expected ${options.expectedNamespace} but received ${envelope.appNamespace}`);
+    if (options.expectedOrigin) {
+        const expectedOrigin = normalizeOrigin(options.expectedOrigin);
+        if (envelope.origin !== expectedOrigin) errors.push(`Origin mismatch: expected ${expectedOrigin} but received ${envelope.origin}`);
+    }
+    if (options.expectedRuntimeVersion && envelope.runtimeVersion !== options.expectedRuntimeVersion) errors.push(`Runtime version mismatch: expected ${options.expectedRuntimeVersion} but received ${envelope.runtimeVersion}`);
+    const checksumBase = {
+        protocolVersion: envelope.protocolVersion,
+        runtimeVersion: envelope.runtimeVersion,
+        appNamespace: envelope.appNamespace,
+        origin: envelope.origin,
+        createdAt: envelope.createdAt,
+        payload: envelope.payload
+    };
+    const checksum = hashString(stableStringify(checksumBase));
+    if (checksum !== envelope.checksum) errors.push('Hydration checksum mismatch');
+    return {
+        ok: 0 === errors.length,
+        errors
+    };
+}
+export { createHydrationEnvelope, createRequestEnvelope, validateHydrationEnvelope, validateRequestEnvelope, validateSelectionPlan };

package/dist/esm-node/runtime/effect/adapter/constants.mjs

@@ -0,0 +1,7 @@
+import "node:module";
+const before = [
+    'custom-server-hook',
+    'custom-server-middleware',
+    'render'
+];
+export { before };

package/dist/esm-node/runtime/effect/adapter/cross-project-policy.mjs

@@ -0,0 +1,24 @@
+import "node:module";
+import { logger } from "@modern-js/utils";
+import { HttpApi } from "effect/unstable/httpapi";
+import { resolveAdapterCrossProjectPolicy } from "../../../utils/crossProjectServerPolicy.mjs";
+import { collectEffectEndpoints, extractHttpApiFromModule, toOperationContractSources } from "../endpoint-contracts.mjs";
+async function resolveEffectAdapterCrossProjectPolicy(api, prefix, mod) {
+    let contractSources = [];
+    if (mod) try {
+        const effectApi = await extractHttpApiFromModule(mod, HttpApi.isHttpApi);
+        if (effectApi) {
+            const reflect = (apiValue, handlers)=>HttpApi.reflect(apiValue, {
+                    onGroup: handlers.onGroup ?? (()=>{}),
+                    onEndpoint: handlers.onEndpoint
+                });
+            contractSources = toOperationContractSources(collectEffectEndpoints(reflect, effectApi, prefix));
+        }
+    } catch (error) {
+        logger.warn(`[BFF][Effect] Failed reflect HttpApi endpoints cross-project policy: ${String(error)}`);
+    }
+    const policy = resolveAdapterCrossProjectPolicy(api, contractSources);
+    if (policy?.enabled && 0 === contractSources.length) logger.warn('[BFF][Effect] Cross-project policy enabled but no HttpApi endpoints could be reflected; requests fail operation-contract matching unless allowUnknownOperations is enabled.');
+    return policy;
+}
+export { resolveEffectAdapterCrossProjectPolicy };

package/dist/esm-node/runtime/effect/adapter/entry.mjs

@@ -0,0 +1,30 @@
+import "node:module";
+import { API_DIR, findExists, fs } from "@modern-js/utils";
+import path from "path";
+const JS_OR_TS_EXTS = [
+    '.js',
+    '.jsx',
+    '.ts',
+    '.tsx',
+    '.mjs',
+    '.mts',
+    '.cjs',
+    '.cts'
+];
+function resolveJsOrTsEntry(entryWithoutOrWithExt) {
+    const extension = path.extname(entryWithoutOrWithExt);
+    if (JS_OR_TS_EXTS.includes(extension)) return fs.existsSync(entryWithoutOrWithExt) ? entryWithoutOrWithExt : void 0;
+    return findExists(JS_OR_TS_EXTS.map((ext)=>`${entryWithoutOrWithExt}${ext}`));
+}
+function resolveEffectAdapterEntryFile(api) {
+    const { appDirectory, apiDirectory } = api.getServerContext();
+    const bffConfig = api.getServerConfig()?.bff;
+    const configuredEntry = bffConfig?.effect?.entry;
+    if (configuredEntry) {
+        const entryWithoutExt = path.isAbsolute(configuredEntry) ? configuredEntry : path.resolve(appDirectory || process.cwd(), configuredEntry);
+        return resolveJsOrTsEntry(entryWithoutExt);
+    }
+    const apiRoot = path.resolve(appDirectory || process.cwd(), apiDirectory || API_DIR);
+    return resolveJsOrTsEntry(path.resolve(apiRoot, 'index'));
+}
+export { resolveEffectAdapterEntryFile };

package/dist/esm-node/runtime/effect/adapter/error-response.mjs

@@ -0,0 +1,42 @@
+import "node:module";
+import { logger } from "@modern-js/utils";
+import { createSafeFailureResponse } from "../../safe-failure.mjs";
+async function createEffectAdapterRuntimeErrorResponse(api, error, c) {
+    try {
+        const serverConfig = api.getServerConfig();
+        const onErrorHandler = serverConfig?.onError;
+        if (onErrorHandler) {
+            const onErrorContext = ensureJsonContext(c);
+            const result = await onErrorHandler(error instanceof Error ? error : new Error(String(error)), onErrorContext);
+            if (result instanceof Response) return result;
+        } else logger.error(error);
+    } catch (configError) {
+        logger.error(`Error in serverConfig.onError handler: ${configError}`);
+    }
+    return createSafeFailureResponse(error);
+}
+function ensureJsonContext(c) {
+    const maybeJsonContext = c;
+    if ('function' == typeof maybeJsonContext.json) return c;
+    const headers = {
+        'content-type': 'application/json; charset=utf-8'
+    };
+    const withJson = Object.assign({}, c, {
+        json (data, statusOrInit = 200, extraHeaders) {
+            const responseInit = 'number' == typeof statusOrInit ? {
+                status: statusOrInit,
+                headers: extraHeaders
+            } : statusOrInit;
+            const responseHeaders = new Headers(headers);
+            if (responseInit.headers) new Headers(responseInit.headers).forEach((value, key)=>{
+                responseHeaders.set(key, value);
+            });
+            return new Response(JSON.stringify(data), {
+                ...responseInit,
+                headers: responseHeaders
+            });
+        }
+    });
+    return withJson;
+}
+export { createEffectAdapterRuntimeErrorResponse };

package/dist/esm-node/runtime/effect/adapter/handler.mjs

@@ -0,0 +1,16 @@
+import "node:module";
+import { logger } from "@modern-js/utils";
+import { checkCrossProjectPolicyForRequest } from "../../../utils/crossProjectServerPolicy.mjs";
+import { resolveEffectBffModuleHandler } from "../module.mjs";
+async function loadEffectAdapterHandlerFromModule(api, mod, crossProjectPolicy) {
+    const effectConfig = api.getServerConfig()?.bff?.effect;
+    return resolveEffectBffModuleHandler(mod, {
+        openapi: effectConfig?.openapi,
+        dataPlatform: effectConfig?.dataPlatform,
+        validateRequest: (request)=>checkCrossProjectPolicyForRequest(request, crossProjectPolicy),
+        onWarning: (message)=>{
+            logger.warn(message);
+        }
+    });
+}
+export { loadEffectAdapterHandlerFromModule };

package/dist/esm-node/runtime/effect/adapter.mjs

@@ -1,74 +1,16 @@
 import __rslib_shim_module__ from "node:module";
 const require = /*#__PURE__*/ __rslib_shim_module__.createRequire(/*#__PURE__*/ (()=>import.meta.url)());
-import { API_DIR, compatibleRequire, findExists, fs, isProd, logger } from "@modern-js/utils";
-import { HttpApi } from "effect/unstable/httpapi";
-import path from "path";
-import { checkCrossProjectPolicyForRequest, resolveAdapterCrossProjectPolicy } from "../../utils/crossProjectServerPolicy.mjs";
-import { createSafeFailureResponse } from "../safe-failure.mjs";
+import { compatibleRequire, fs, isProd, logger } from "@modern-js/utils";
+import { before } from "./adapter/constants.mjs";
+import { resolveEffectAdapterCrossProjectPolicy } from "./adapter/cross-project-policy.mjs";
+import { resolveEffectAdapterEntryFile } from "./adapter/entry.mjs";
+import { createEffectAdapterRuntimeErrorResponse } from "./adapter/error-response.mjs";
+import { loadEffectAdapterHandlerFromModule } from "./adapter/handler.mjs";
 import { runWithEffectContext } from "./context.mjs";
 import { dispatchEffectBffRequestWithContext } from "./dispatch.mjs";
-import { collectEffectEndpoints, extractHttpApiFromModule, toOperationContractSources } from "./endpoint-contracts.mjs";
-import { resolveEffectBffModuleHandler } from "./module.mjs";
-const before = [
-    'custom-server-hook',
-    'custom-server-middleware',
-    'render'
-];
-const JS_OR_TS_EXTS = [
-    '.js',
-    '.jsx',
-    '.ts',
-    '.tsx',
-    '.mjs',
-    '.mts',
-    '.cjs',
-    '.cts'
-];
-function resolveJsOrTsEntry(entryWithoutOrWithExt) {
-    const extension = path.extname(entryWithoutOrWithExt);
-    if (JS_OR_TS_EXTS.includes(extension)) return fs.existsSync(entryWithoutOrWithExt) ? entryWithoutOrWithExt : void 0;
-    return findExists(JS_OR_TS_EXTS.map((ext)=>`${entryWithoutOrWithExt}${ext}`));
-}
 class EffectAdapter {
     resolveEntryFile() {
-        const { appDirectory, apiDirectory } = this.api.getServerContext();
-        const bffConfig = this.api.getServerConfig()?.bff;
-        const configuredEntry = bffConfig?.effect?.entry;
-        if (configuredEntry) {
-            const entryWithoutExt = path.isAbsolute(configuredEntry) ? configuredEntry : path.resolve(appDirectory || process.cwd(), configuredEntry);
-            return resolveJsOrTsEntry(entryWithoutExt);
-        }
-        const apiRoot = path.resolve(appDirectory || process.cwd(), apiDirectory || API_DIR);
-        return resolveJsOrTsEntry(path.resolve(apiRoot, 'index'));
-    }
-    async refreshCrossProjectPolicy(mod) {
-        let contractSources = [];
-        if (mod) try {
-            const api = await extractHttpApiFromModule(mod, HttpApi.isHttpApi);
-            if (api) {
-                const reflect = (apiValue, handlers)=>HttpApi.reflect(apiValue, {
-                        onGroup: handlers.onGroup ?? (()=>{}),
-                        onEndpoint: handlers.onEndpoint
-                    });
-                contractSources = toOperationContractSources(collectEffectEndpoints(reflect, api, this.prefix));
-            }
-        } catch (error) {
-            logger.warn(`[BFF][Effect] Failed to reflect HttpApi endpoints for the cross-project policy: ${String(error)}`);
-        }
-        const policy = resolveAdapterCrossProjectPolicy(this.api, contractSources);
-        this.crossProjectPolicy = policy;
-        if (this.crossProjectPolicy?.enabled && 0 === contractSources.length) logger.warn('[BFF][Effect] Cross-project policy is enabled but no HttpApi endpoints could be reflected; operation-contract matching is disabled for this server (envelope and operation-context checks still apply).');
-    }
-    async loadEffectHandlerFromModule(mod) {
-        const effectConfig = this.api.getServerConfig()?.bff?.effect;
-        return resolveEffectBffModuleHandler(mod, {
-            openapi: effectConfig?.openapi,
-            dataPlatform: effectConfig?.dataPlatform,
-            validateRequest: (request)=>checkCrossProjectPolicyForRequest(request, this.crossProjectPolicy),
-            onWarning: (message)=>{
-                logger.warn(message);
-            }
-        });
+        return resolveEffectAdapterEntryFile(this.api);
     }
     async reloadHandler() {
         if (!this.isEffect) return;
@@ -94,8 +36,8 @@ class EffectAdapter {
             this.handler = null;
             return;
         }
-        await this.refreshCrossProjectPolicy(mod);
-        const loaded = await this.loadEffectHandlerFromModule(mod);
+        this.crossProjectPolicy = await resolveEffectAdapterCrossProjectPolicy(this.api, this.prefix, mod);
+        const loaded = await loadEffectAdapterHandlerFromModule(this.api, mod, this.crossProjectPolicy);
         if (!loaded) {
             logger.warn(`[BFF][Effect] Invalid Effect entry module: ${entryFile}. Export defineEffectBff(...) or a { api, layer } HttpApi module.`);
             this.handler = null;
@@ -109,48 +51,13 @@ class EffectAdapter {
         try {
             await this.dispose();
         } catch (error) {
-            logger.warn(`[BFF][Effect] Failed to dispose previous handler: ${String(error)}`);
+            logger.warn(`[BFF][Effect] Failed dispose previous handler: ${String(error)}`);
         } finally{
             this.dispose = null;
         }
     }
-    async handleRuntimeError(error, c) {
-        try {
-            const serverConfig = this.api.getServerConfig();
-            const onErrorHandler = serverConfig?.onError;
-            if (onErrorHandler) {
-                const onErrorContext = this.ensureJsonContext(c);
-                const result = await onErrorHandler(error instanceof Error ? error : new Error(String(error)), onErrorContext);
-                if (result instanceof Response) return result;
-            } else logger.error(error);
-        } catch (configError) {
-            logger.error(`Error in serverConfig.onError handler: ${configError}`);
-        }
-        return createSafeFailureResponse(error);
-    }
-    ensureJsonContext(c) {
-        const maybeJsonContext = c;
-        if ('function' == typeof maybeJsonContext.json) return c;
-        const headers = {
-            'content-type': 'application/json; charset=utf-8'
-        };
-        const withJson = Object.assign({}, c, {
-            json: (data, status = 200, extraHeaders)=>{
-                const responseHeaders = new Headers(headers);
-                if (extraHeaders) new Headers(extraHeaders).forEach((value, key)=>{
-                    responseHeaders.set(key, value);
-                });
-                return new Response(JSON.stringify(data), {
-                    status,
-                    headers: responseHeaders
-                });
-            }
-        });
-        return withJson;
-    }
     constructor(api){
         this.isEffect = true;
-        this.effectMiddleware = null;
         this.handler = null;
         this.dispose = null;
         this.prefix = '/api';
@@ -172,7 +79,7 @@ class EffectAdapter {
                 handler: async (c, next)=>{
                     if (!this.handler) {
                         if (enableHandleWeb) return void await next();
-                        return this.handleRuntimeError(new Error('[BFF][Effect] Missing Effect entry. Define api/index or configure bff.effect.entry.'), c);
+                        return createEffectAdapterRuntimeErrorResponse(this.api, new Error('[BFF][Effect] Missing Effect entry. Define api/index or configure bff.effect.entry.'), c);
                     }
                     const response = await dispatchEffectBffRequestWithContext(this.handler, c.req.raw, {
                         prefix,
@@ -180,7 +87,7 @@ class EffectAdapter {
                         path: c.req.path,
                         method: c.req.method,
                         runWithEffectContext: runWithEffectContext,
-                        onError: (error)=>this.handleRuntimeError(error, c)
+                        onError: (error)=>createEffectAdapterRuntimeErrorResponse(this.api, error, c)
                     });
                     if (404 === response.status && enableHandleWeb) return void await next();
                     return new Response(response.body, response);

package/dist/esm-node/runtime/effect/backend-federation/entry.mjs

@@ -0,0 +1,62 @@
+import "node:module";
+import { isRecord, normalizeExpose } from "./utils.mjs";
+function decodeDataUrl(url) {
+    const commaIndex = url.indexOf(',');
+    if (commaIndex < 0) throw new Error('[BFF][Effect] Invalid backend federation data URL entry.');
+    return decodeURIComponent(url.slice(commaIndex + 1));
+}
+async function readCommonJsEntrySource(remote) {
+    if (remote.entry.startsWith('data:')) return decodeDataUrl(remote.entry);
+    if (remote.entry.startsWith('http://') || remote.entry.startsWith('https://')) {
+        const response = await fetch(remote.entry);
+        if (!response.ok) throw new Error(`[BFF][Effect] Failed to load backend federation remote ${remote.name}: ${response.status}`);
+        return response.text();
+    }
+    throw new Error(`[BFF][Effect] Backend federation remote ${remote.name} cannot load CommonJS entry ${remote.entry}.`);
+}
+function evaluateCommonJsEntry(remote, source) {
+    const module = {
+        exports: {}
+    };
+    const exports = module.exports;
+    const evaluate = new Function('module', 'exports', 'globalThis', source);
+    evaluate(module, exports, globalThis);
+    const entry = module.exports.default ?? module.exports;
+    if (!isRecord(entry)) throw new Error(`[BFF][Effect] Backend federation remote ${remote.name} entry must load object module.`);
+    return entry;
+}
+async function importModuleEntry(remote) {
+    const entry = await import(remote.entry);
+    return entry.default ?? entry;
+}
+async function resolvePluginEntry(remote, plugins) {
+    for (const plugin of plugins ?? []){
+        const loadEntry = plugin.loadEntry;
+        if ('function' != typeof loadEntry) continue;
+        const entry = await loadEntry({
+            remoteInfo: remote
+        });
+        if (entry) return entry;
+    }
+}
+async function loadBackendFederationEntry(remote, plugins) {
+    const pluginEntry = await resolvePluginEntry(remote, plugins);
+    if (pluginEntry) return pluginEntry;
+    if (remote.entryGlobalName) {
+        const globalEntry = globalThis[remote.entryGlobalName];
+        if (isRecord(globalEntry)) return globalEntry;
+    }
+    if ('module' === remote.type || remote.entry.startsWith('file:')) return importModuleEntry(remote);
+    return evaluateCommonJsEntry(remote, await readCommonJsEntrySource(remote));
+}
+async function loadBackendFederationExpose(remote, expose, options) {
+    const entry = await loadBackendFederationEntry(remote, options.plugins);
+    if ('function' == typeof entry.init) await entry.init({
+        hostName: options.hostName
+    });
+    if ('function' != typeof entry.get) throw new Error(`[BFF][Effect] Backend federation remote ${remote.name} entry must expose get().`);
+    const factory = await entry.get(expose);
+    if ('function' != typeof factory) throw new Error(`[BFF][Effect] Backend federation expose ${remote.name}/${normalizeExpose(expose)} must load factory function.`);
+    return factory();
+}
+export { loadBackendFederationExpose };

package/dist/esm-node/runtime/effect/backend-federation/load.mjs

@@ -0,0 +1,20 @@
+import "node:module";
+import { BACKEND_FEDERATION_EFFECT_EXPOSE } from "@modern-js/utils/universal";
+import { createBackendFederationRuntime } from "./runtime.mjs";
+import { isRecord, normalizeExpose } from "./utils.mjs";
+async function loadBackendFederatedEffectApi(options) {
+    const remoteName = options.remote?.name ?? options.remoteName;
+    if (!remoteName) throw new Error('[BFF][Effect] Missing backend federation remote name.');
+    const runtime = options.runtime ?? createBackendFederationRuntime(options);
+    const expose = options.expose ?? options.remote?.expose ?? BACKEND_FEDERATION_EFFECT_EXPOSE;
+    const remoteRequest = `${remoteName}/${normalizeExpose(expose)}`;
+    const loaded = await runtime.loadRemote(remoteRequest);
+    if (!isRecord(loaded)) throw new Error(`[BFF][Effect] Backend federation expose ${remoteRequest} must load an object module.`);
+    const backendContract = loaded.backendFederationContract;
+    if (!isRecord(backendContract) || true !== backendContract.strictEffectApproach) throw new Error(`[BFF][Effect] Backend federation expose ${remoteRequest} must expose strict Effect metadata (strictEffectApproach: true).`);
+    if ('effect' !== backendContract.runtimeFramework) throw new Error(`[BFF][Effect] Backend federation expose ${remoteRequest} must expose strict Effect metadata (runtimeFramework: "effect").`);
+    if ('string' == typeof backendContract.name && backendContract.name !== remoteName) throw new Error(`[BFF][Effect] Backend federation expose ${remoteRequest} metadata name mismatch: expected ${remoteName}, received ${backendContract.name}.`);
+    if (!('runtime' in loaded)) throw new Error(`[BFF][Effect] Backend federation expose ${remoteRequest} must expose api and runtime.`);
+    return loaded;
+}
+export { loadBackendFederatedEffectApi };

package/dist/esm-node/runtime/effect/backend-federation/plugin.mjs

@@ -0,0 +1,16 @@
+import "node:module";
+function createBackendFederationLoadEntryPlugin(options) {
+    return {
+        name: 'modernjs-backend-federation-load-entry',
+        async loadEntry ({ remoteInfo }) {
+            return options.resolveEntry({
+                name: remoteInfo.name,
+                entry: remoteInfo.entry,
+                type: remoteInfo.type,
+                entryGlobalName: remoteInfo.entryGlobalName,
+                shareScope: remoteInfo.shareScope
+            });
+        }
+    };
+}
+export { createBackendFederationLoadEntryPlugin };

package/dist/esm-node/runtime/effect/backend-federation/remotes.mjs

@@ -0,0 +1,13 @@
+import "node:module";
+function collectRemotes(options) {
+    const remotes = [
+        ...options.remotes ?? []
+    ];
+    if (options.remote) {
+        const existingIndex = remotes.findIndex((remote)=>remote.name === options.remote?.name);
+        if (existingIndex >= 0) remotes[existingIndex] = options.remote;
+        else remotes.push(options.remote);
+    }
+    return remotes;
+}
+export { collectRemotes };

package/dist/esm-node/runtime/effect/backend-federation/runtime.mjs

@@ -0,0 +1,27 @@
+import "node:module";
+import { loadBackendFederationExpose } from "./entry.mjs";
+import { collectRemotes } from "./remotes.mjs";
+import { normalizeExpose } from "./utils.mjs";
+function exposeForRemoteRequest(expose) {
+    return `./${normalizeExpose(expose)}`;
+}
+function parseRemoteRequest(request) {
+    const [remoteName, ...exposeParts] = request.split('/');
+    if (!remoteName || 0 === exposeParts.length) throw new Error(`[BFF][Effect] Invalid backend federation request ${request}.`);
+    return {
+        remoteName,
+        expose: exposeForRemoteRequest(exposeParts.join('/'))
+    };
+}
+function createBackendFederationRuntime(options) {
+    const remotes = collectRemotes(options);
+    return {
+        async loadRemote (request) {
+            const { remoteName, expose } = parseRemoteRequest(request);
+            const remote = remotes.find((candidate)=>candidate.name === remoteName);
+            if (!remote) throw new Error(`[BFF][Effect] Missing backend federation remote ${remoteName}.`);
+            return loadBackendFederationExpose(remote, expose, options);
+        }
+    };
+}
+export { createBackendFederationRuntime };

package/dist/esm-node/runtime/effect/backend-federation/types.mjs

@@ -0,0 +1 @@
+import "node:module";

package/dist/esm-node/runtime/effect/backend-federation/utils.mjs

@@ -0,0 +1,8 @@
+import "node:module";
+function normalizeExpose(expose) {
+    return expose.replace(/^\.\//u, '');
+}
+function isRecord(value) {
+    return 'object' == typeof value && null !== value;
+}
+export { isRecord, normalizeExpose };

package/dist/esm-node/runtime/effect/backend-federation-manifest/errors.mjs

@@ -0,0 +1,33 @@
+import "node:module";
+const BACKEND_FEDERATION_MANIFEST_ADAPTER_FAILURE_EVENT = 'modernjs:microvertical-server-fallback';
+class BackendFederationManifestAdapterError extends Error {
+    constructor(code, message, cause, details){
+        super(message), this.failureEvent = BACKEND_FEDERATION_MANIFEST_ADAPTER_FAILURE_EVENT;
+        this.name = 'BackendFederationManifestAdapterError';
+        this.code = code;
+        if (details) this.details = details;
+        if (void 0 !== cause) this.cause = cause;
+    }
+}
+function assertManifestAdapter(condition, code, message) {
+    if (!condition) throw new BackendFederationManifestAdapterError(code, message);
+}
+function assertVersionValue(actual, expected, label, details) {
+    if (void 0 === expected) return;
+    if (actual !== expected) throw new BackendFederationManifestAdapterError('version_mismatch', `[BFF][Effect] Backend federation ${label} mismatch: expected ${expected}, received ${actual ?? 'undefined'}.`, void 0, {
+        label,
+        expected,
+        received: actual,
+        ...details
+    });
+}
+function assertConsistentValue(left, right, label, details) {
+    if (void 0 === left || void 0 === right || left === right) return;
+    throw new BackendFederationManifestAdapterError('version_mismatch', `[BFF][Effect] Backend federation ${label} mismatch: expected ${left}, received ${right}.`, void 0, {
+        label,
+        expected: left,
+        received: right,
+        ...details
+    });
+}
+export { BACKEND_FEDERATION_MANIFEST_ADAPTER_FAILURE_EVENT, BackendFederationManifestAdapterError, assertConsistentValue, assertManifestAdapter, assertVersionValue };

package/dist/esm-node/runtime/effect/backend-federation-manifest/index.mjs

@@ -0,0 +1,5 @@
+import "node:module";
+export { BACKEND_FEDERATION_MANIFEST_ADAPTER_FAILURE_EVENT, BackendFederationManifestAdapterError } from "./errors.mjs";
+export { loadBackendFederatedEffectApiFromManifest } from "./load.mjs";
+export { loadBackendFederationManifest } from "./reference.mjs";
+export { resolveBackendFederationRemoteFromManifest } from "./remote.mjs";

package/dist/esm-node/runtime/effect/backend-federation-manifest/load.mjs

@@ -0,0 +1,37 @@
+import "node:module";
+import { BACKEND_FEDERATION_EFFECT_EXPOSE, loadBackendFederatedEffectApi } from "../backend-federation.mjs";
+import { BackendFederationManifestAdapterError } from "./errors.mjs";
+import { loadBackendFederationManifest, withTimeout } from "./reference.mjs";
+import { resolveBackendFederationRemoteFromManifest } from "./remote.mjs";
+import { classifyLoadError, validateBackendFederationManifest, validateLoadedBackendFederationContract } from "./validation.mjs";
+async function loadBackendFederatedEffectApiFromManifest(options) {
+    let manifest;
+    let remote;
+    try {
+        manifest = await loadBackendFederationManifest(options);
+        validateBackendFederationManifest(manifest, options.expected);
+        remote = resolveBackendFederationRemoteFromManifest(manifest, options.remote);
+        const loaded = await withTimeout(loadBackendFederatedEffectApi({
+            hostName: options.hostName,
+            remote,
+            ...options.plugins ? {
+                plugins: options.plugins
+            } : {},
+            ...options.runtime ? {
+                runtime: options.runtime
+            } : {}
+        }), options.timeoutMs, `Backend federation remote ${remote.name}`).catch((error)=>{
+            throw new BackendFederationManifestAdapterError(classifyLoadError(error), `[BFF][Effect] Backend federation remote ${remote?.name ?? 'unknown'} could not load ${remote?.expose ?? BACKEND_FEDERATION_EFFECT_EXPOSE}.`, error);
+        });
+        validateLoadedBackendFederationContract(loaded, manifest, remote);
+        return loaded;
+    } catch (error) {
+        const adapterError = error instanceof BackendFederationManifestAdapterError ? error : new BackendFederationManifestAdapterError('remote_unavailable', '[BFF][Effect] Backend federation manifest adapter failed.', error);
+        if (options.fallback) return options.fallback(adapterError, {
+            manifest,
+            remote
+        });
+        throw adapterError;
+    }
+}
+export { loadBackendFederatedEffectApiFromManifest };