@bleedingdev/modern-js-plugin-bff 3.5.0-ultramodern.9 → 3.5.0-ultramodern.90

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

@@ -0,0 +1,128 @@
+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/runtime/effect/adapter/constants.mjs

@@ -0,0 +1,6 @@
+const before = [
+    'custom-server-hook',
+    'custom-server-middleware',
+    'render'
+];
+export { before };

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

@@ -0,0 +1,23 @@
+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/runtime/effect/adapter/entry.mjs

@@ -0,0 +1,44 @@
+import { API_DIR, findExists, fs, isProd } 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}`)) || void 0;
+}
+function builtEntryPath(entryPath) {
+    return entryPath.replace(/\.(?:[cm]?ts|tsx|jsx)$/u, '.js');
+}
+function relativeAppPath(appDirectory, entryPath) {
+    const relativePath = path.relative(appDirectory, entryPath);
+    return '..' === relativePath || relativePath.startsWith(`..${path.sep}`) ? void 0 : relativePath;
+}
+function resolveEffectAdapterEntryFile(api) {
+    const { appDirectory, apiDirectory, distDirectory } = api.getServerContext();
+    const appRoot = path.resolve(appDirectory || process.cwd());
+    const productionRoot = isProd() && distDirectory ? distDirectory : void 0;
+    const bffConfig = api.getServerConfig()?.bff;
+    const configuredEntry = bffConfig?.effect?.entry;
+    if (configuredEntry) {
+        const sourceEntry = path.isAbsolute(configuredEntry) ? configuredEntry : path.resolve(appRoot, configuredEntry);
+        if (productionRoot) {
+            const relativeEntry = relativeAppPath(appRoot, sourceEntry);
+            return relativeEntry ? resolveJsOrTsEntry(builtEntryPath(path.resolve(productionRoot, relativeEntry))) : void 0;
+        }
+        return resolveJsOrTsEntry(sourceEntry);
+    }
+    const relativeApiDirectory = apiDirectory ? path.isAbsolute(apiDirectory) ? relativeAppPath(appRoot, apiDirectory) : apiDirectory : API_DIR;
+    if (!relativeApiDirectory) return;
+    const apiRoot = path.resolve(productionRoot || appRoot, relativeApiDirectory);
+    return resolveJsOrTsEntry(path.resolve(apiRoot, 'index'));
+}
+export { resolveEffectAdapterEntryFile };

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

@@ -0,0 +1,41 @@
+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/runtime/effect/adapter/handler.mjs

@@ -0,0 +1,15 @@
+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/runtime/effect/adapter.mjs

@@ -1,91 +1,16 @@
-import { API_DIR, compatibleRequire, findExists, fs, isProd, logger } from "@modern-js/utils";
-import { HttpApi } from "effect/unstable/httpapi";
+import { fs, isProd, logger } from "@modern-js/utils";
 import path from "path";
-import { checkCrossProjectPolicyForRequest, resolveAdapterCrossProjectPolicy } from "../../utils/crossProjectServerPolicy.mjs";
-import { createSafeFailureResponse } from "../safe-failure.mjs";
-import { createEffectOperationContext, runWithEffectContext } from "./context.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}`));
-}
-function normalizePrefix(prefix) {
-    if ('/' === prefix) return '';
-    return prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
-}
-function removePrefixFromPath(pathname, prefix) {
-    const normalized = normalizePrefix(prefix);
-    if (!normalized || pathname !== normalized && !pathname.startsWith(`${normalized}/`)) return pathname;
-    const sliced = pathname.slice(normalized.length);
-    return sliced.startsWith('/') ? sliced : `/${sliced}`;
-}
-function createRequestForMountedPrefix(req, prefix) {
-    const url = new URL(req.url);
-    const nextPath = removePrefixFromPath(url.pathname, prefix);
-    if (nextPath === url.pathname) return req;
-    url.pathname = nextPath;
-    return new Request(url, req);
-}
-function maybeResponse(value) {
-    return value instanceof Response;
-}
+import { loadEffectSourceModule } from "../../utils/effectSourceLoader.mjs";
+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";
 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;
@@ -101,18 +26,20 @@ class EffectAdapter {
             return;
         }
         await this.disposeCurrentHandler();
-        const resolvedEntryFile = require.resolve(entryFile);
-        if (Object.hasOwn(require.cache, resolvedEntryFile)) delete require.cache[resolvedEntryFile];
         let mod;
         try {
-            mod = await compatibleRequire(entryFile, false);
+            const { appDirectory } = this.api.getServerContext();
+            mod = await loadEffectSourceModule({
+                resourcePath: entryFile,
+                appDir: appDirectory || path.dirname(entryFile)
+            });
         } catch (error) {
             logger.error(`[BFF][Effect] Failed to load Effect entry: ${entryFile}\n${String(error)}`);
             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;
@@ -126,48 +53,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';
@@ -189,28 +81,16 @@ 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);
                     }
-                    let response;
-                    try {
-                        const effectRequest = createRequestForMountedPrefix(c.req.raw, prefix);
-                        const effectContext = {
-                            request: effectRequest,
-                            env: c.env,
-                            path: c.req.path,
-                            method: c.req.method,
-                            operationContext: createEffectOperationContext({
-                                request: effectRequest,
-                                env: c.env,
-                                path: c.req.path,
-                                method: c.req.method
-                            })
-                        };
-                        response = await runWithEffectContext(effectContext, ()=>this.handler.length > 1 ? this.handler(effectRequest, effectContext) : this.handler(effectRequest));
-                    } catch (error) {
-                        return this.handleRuntimeError(error, c);
-                    }
-                    if (!maybeResponse(response)) return this.handleRuntimeError(new Error('[BFF][Effect] Effect handler must return a Response instance.'), c);
+                    const response = await dispatchEffectBffRequestWithContext(this.handler, c.req.raw, {
+                        prefix,
+                        env: c.env,
+                        path: c.req.path,
+                        method: c.req.method,
+                        runWithEffectContext: runWithEffectContext,
+                        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/runtime/effect/backend-federation/entry.mjs

@@ -0,0 +1,61 @@
+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/runtime/effect/backend-federation/identity.mjs

@@ -0,0 +1,41 @@
+import { isRecord } from "./utils.mjs";
+function validateExpectedBackendFederationIdentity(loaded, expected, options = {}) {
+    const allowMissing = true === options.allowMissingIdentityMetadata;
+    const issues = [];
+    const contract = isRecord(loaded) ? loaded.backendFederationContract : void 0;
+    const compatibility = isRecord(contract) ? contract.compatibility : void 0;
+    if (!isRecord(compatibility)) {
+        if (allowMissing) return [];
+        return [
+            {
+                path: 'backendFederationContract.compatibility',
+                message: 'loaded module declares no compatibility metadata; delivery-unit identity cannot be validated'
+            }
+        ];
+    }
+    const unitId = compatibility.unitId;
+    if ('string' != typeof unitId || 0 === unitId.length) {
+        if (!allowMissing) issues.push({
+            path: 'backendFederationContract.compatibility.unitId',
+            message: `missing delivery-unit id; expected ${expected.unitId}`
+        });
+    } else if (unitId !== expected.unitId) issues.push({
+        path: 'backendFederationContract.compatibility.unitId',
+        message: `expected ${expected.unitId}, received ${unitId}`
+    });
+    const build = compatibility.build;
+    if ('string' != typeof build || 0 === build.length) {
+        if (!allowMissing) issues.push({
+            path: 'backendFederationContract.compatibility.build',
+            message: `missing build marker; expected ${expected.buildMarker}`
+        });
+    } else if (build !== expected.buildMarker) issues.push({
+        path: 'backendFederationContract.compatibility.build',
+        message: `expected ${expected.buildMarker}, received ${build}`
+    });
+    return issues;
+}
+function formatBackendFederationIdentityIssues(issues) {
+    return issues.map((issue)=>`${issue.path}: ${issue.message}`).join('; ');
+}
+export { formatBackendFederationIdentityIssues, validateExpectedBackendFederationIdentity };

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

@@ -0,0 +1,28 @@
+import { BACKEND_FEDERATION_EFFECT_EXPOSE } from "@modern-js/utils/universal";
+import { formatBackendFederationIdentityIssues, validateExpectedBackendFederationIdentity } from "./identity.mjs";
+import { createBackendFederationRuntime } from "./runtime.mjs";
+import { isRecord, normalizeExpose } from "./utils.mjs";
+const LEGACY_LOAD_WARNING = '[BFF][Effect] loadBackendFederatedEffectApi was called without an expected delivery-unit identity (expected.unitId + expected.buildMarker). Identity-less public backend loads are deprecated (ADR-0019/MV-G23) and will be rejected in a future major.';
+async function loadBackendFederatedEffectApi(options) {
+    const remoteName = options.remote?.name ?? options.remoteName;
+    if (!remoteName) throw new Error('[BFF][Effect] Missing backend federation remote name.');
+    if (void 0 === options.expected) console.warn(LEGACY_LOAD_WARNING);
+    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.`);
+    if (void 0 !== options.expected) {
+        const issues = validateExpectedBackendFederationIdentity(loaded, options.expected, {
+            allowMissingIdentityMetadata: true === options.allowMissingIdentityMetadata
+        });
+        if (issues.length > 0) throw new Error(`[BFF][Effect] Backend federation expose ${remoteRequest} delivery-unit identity mismatch: ${formatBackendFederationIdentityIssues(issues)}.`);
+    }
+    return loaded;
+}
+export { loadBackendFederatedEffectApi };

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

@@ -0,0 +1,15 @@
+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/runtime/effect/backend-federation/remotes.mjs

@@ -0,0 +1,12 @@
+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 };