@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.9 → 3.5.0-ultramodern.90

package/dist/esm-node/ultramodern-release-envelope/framework-output.mjs

@@ -0,0 +1,525 @@
+import "node:module";
+import promises from "node:fs/promises";
+import node_path from "node:path";
+import { parse } from "@babel/parser";
+import { BACKEND_FEDERATION_MANIFEST_FILE, BACKEND_FEDERATION_REMOTE_ENTRY_FILE, ULTRAMODERN_BUILD_ARTIFACT_FILE, isUltramodernBuildArtifact } from "@modern-js/utils/universal";
+import { canonicalSerializeMicroVerticalReleaseEnvelope, createMicroVerticalReleaseEnvelope, verifyMicroVerticalReleaseEnvelope } from "./index.mjs";
+const MICROVERTICAL_RELEASE_ENVELOPE_PATH = 'release/microvertical-release-envelope.json';
+const COMPILED_MODULE_PATTERN = /\.(?:c|m)?js$/u;
+const EFFECT_BFF_WORKER_PATTERN = /^worker\/__modern_bff_effect\.(?:c|m)?js$/u;
+const isRecord = (value)=>'object' == typeof value && null !== value && !Array.isArray(value);
+const isAstNode = (value)=>isRecord(value) && 'string' == typeof value.type;
+const visitAst = (node, visitor)=>{
+    visitor(node);
+    for (const value of Object.values(node))if (isAstNode(value)) visitAst(value, visitor);
+    else if (Array.isArray(value)) {
+        for (const item of value)if (isAstNode(item)) visitAst(item, visitor);
+    }
+};
+const compiledModuleIdentityValues = (source)=>{
+    const values = new Set();
+    const ast = parse(source, {
+        sourceType: 'unambiguous'
+    });
+    visitAst(ast.program, (node)=>{
+        if ('StringLiteral' === node.type && 'string' == typeof node.value) values.add(node.value);
+        else if ('TemplateElement' === node.type && isRecord(node.value) && 'string' == typeof node.value.cooked) values.add(node.value.cooked);
+    });
+    return values;
+};
+const assertEveryCompiledIdentityCarrier = async (distDirectory, logicalPaths, identity, surface)=>{
+    const compiledLogicalPaths = logicalPaths.filter((pathname)=>COMPILED_MODULE_PATTERN.test(pathname));
+    if (0 === compiledLogicalPaths.length) throw new Error(`[ultramodern-release-envelope] ${surface} has no compiled execution module carrying release identity.`);
+    for (const logicalPath of compiledLogicalPaths){
+        const source = await promises.readFile(node_path.join(distDirectory, logicalPath), {
+            encoding: 'utf8'
+        });
+        const values = compiledModuleIdentityValues(source);
+        if (!values.has(identity.buildMarker) || !values.has(identity.sourceRevision) || !values.has(identity.releaseVersion)) throw new Error(`[ultramodern-release-envelope] ${surface} execution module ${logicalPath} does not carry exact buildMarker ${identity.buildMarker}, sourceRevision ${identity.sourceRevision}, and releaseVersion ${identity.releaseVersion}.`);
+    }
+};
+const flattenStrings = (value)=>'string' == typeof value ? [
+        value
+    ] : Array.isArray(value) ? value.flatMap(flattenStrings) : [];
+const collectNestedStrings = (value, key)=>{
+    if (Array.isArray(value)) return value.flatMap((item)=>collectNestedStrings(item, key));
+    if (!isRecord(value)) return [];
+    return Object.entries(value).flatMap(([entryKey, entryValue])=>[
+            ...entryKey === key ? flattenStrings(entryValue) : [],
+            ...collectNestedStrings(entryValue, key)
+        ]);
+};
+const manifestReferencedClientModules = async (distDirectory, files, manifestLogicalPath = 'mf-manifest.json')=>{
+    const manifest = await readJson(node_path.join(distDirectory, manifestLogicalPath));
+    const references = [
+        ...collectNestedStrings(manifest, 'path'),
+        ...collectNestedStrings(manifest, 'name'),
+        ...collectNestedStrings(manifest, 'sync'),
+        ...collectNestedStrings(manifest, 'async')
+    ];
+    const normalizedReferences = new Set(references.filter((value)=>'string' == typeof value).map((value)=>value.replace(/^https?:\/\/[^/]+/u, '')).map((value)=>value.replace(/^\/+/u, '')));
+    return files.filter((logicalPath)=>COMPILED_MODULE_PATTERN.test(logicalPath) && [
+            ...normalizedReferences
+        ].some((reference)=>reference === logicalPath || reference.endsWith(`/${logicalPath}`) || logicalPath.endsWith(`/${reference}`)));
+};
+const routeReferencedSsrModules = async (distDirectory, files, target, routeSpecLogicalPath = 'route.json')=>{
+    const routeSpec = await readJson(node_path.join(distDirectory, routeSpecLogicalPath));
+    const field = 'node' === target ? 'bundle' : 'worker';
+    const references = collectNestedStrings(routeSpec, field).map((value)=>value.replace(/^\/+/u, ''));
+    return files.filter((logicalPath)=>COMPILED_MODULE_PATTERN.test(logicalPath) && references.includes(logicalPath));
+};
+const readJson = async (filePath)=>JSON.parse(await promises.readFile(filePath, 'utf8'));
+const isFilesystemPathInside = (root, candidate)=>{
+    const relative = node_path.relative(root, candidate);
+    return '' === relative || !relative.startsWith(`..${node_path.sep}`) && '..' !== relative && !node_path.isAbsolute(relative);
+};
+const isMissingPathError = (error)=>isRecord(error) && 'ENOENT' === error.code;
+const resolveSafeReleaseEnvelopePath = async ({ artifactRoot, createDirectory })=>{
+    const resolvedRoot = node_path.resolve(artifactRoot);
+    const realRoot = await promises.realpath(resolvedRoot);
+    const releaseDirectory = node_path.join(resolvedRoot, 'release');
+    let releaseStat;
+    try {
+        releaseStat = await promises.lstat(releaseDirectory);
+    } catch (error) {
+        if (!isMissingPathError(error)) throw error;
+        if (!createDirectory) return;
+        await promises.mkdir(releaseDirectory);
+        releaseStat = await promises.lstat(releaseDirectory);
+    }
+    if (releaseStat.isSymbolicLink() || !releaseStat.isDirectory()) throw new Error('[ultramodern-release-envelope] release must be a real directory inside artifactRoot, not a symlink or file.');
+    const realReleaseDirectory = await promises.realpath(releaseDirectory);
+    if (!isFilesystemPathInside(realRoot, realReleaseDirectory)) throw new Error('[ultramodern-release-envelope] release directory resolves outside artifactRoot.');
+    const envelopePath = node_path.join(releaseDirectory, node_path.basename(MICROVERTICAL_RELEASE_ENVELOPE_PATH));
+    try {
+        const envelopeStat = await promises.lstat(envelopePath);
+        if (envelopeStat.isSymbolicLink() || !envelopeStat.isFile()) throw new Error('[ultramodern-release-envelope] release envelope must be a real file inside artifactRoot, not a symlink or directory.');
+        const realEnvelopePath = await promises.realpath(envelopePath);
+        if (!isFilesystemPathInside(realRoot, realEnvelopePath)) throw new Error('[ultramodern-release-envelope] release envelope resolves outside artifactRoot.');
+    } catch (error) {
+        if (!isMissingPathError(error)) throw error;
+        if (!createDirectory) return;
+    }
+    return envelopePath;
+};
+const writeReleaseEnvelope = async (artifactRoot, envelope)=>{
+    const envelopePath = await resolveSafeReleaseEnvelopePath({
+        artifactRoot,
+        createDirectory: true
+    });
+    if (!envelopePath) throw new Error('[ultramodern-release-envelope] could not resolve release envelope path.');
+    await promises.writeFile(envelopePath, `${canonicalSerializeMicroVerticalReleaseEnvelope(envelope)}\n`);
+};
+const readBuildArtifact = async (distDirectory)=>{
+    const artifactPath = node_path.join(distDirectory, ULTRAMODERN_BUILD_ARTIFACT_FILE);
+    const artifact = await readJson(artifactPath);
+    if (!isUltramodernBuildArtifact(artifact)) throw new Error(`[ultramodern-release-envelope] ${ULTRAMODERN_BUILD_ARTIFACT_FILE} is missing or invalid.`);
+    if ('workspace' === artifact.deliveryUnit.sourceRevision) throw new Error('[ultramodern-release-envelope] sourceRevision "workspace" cannot produce a promotable full-stack envelope.');
+    return artifact;
+};
+const assertIdentityBlock = (value, identity, location, includeReleaseVersion)=>{
+    if (!isRecord(value)) throw new Error(`[ultramodern-release-envelope] ${location} is missing delivery identity.`);
+    const expected = {
+        unitId: identity.unitId,
+        buildMarker: identity.buildMarker,
+        sourceRevision: identity.sourceRevision,
+        ...includeReleaseVersion ? {
+            version: identity.releaseVersion
+        } : void 0
+    };
+    for (const [field, expectedValue] of Object.entries(expected))if (value[field] !== expectedValue) throw new Error(`[ultramodern-release-envelope] ${location}.${field} must match ${expectedValue}; received ${String(value[field])}.`);
+};
+const readBackendManifest = async (distDirectory, identity)=>{
+    const manifest = await readJson(node_path.join(distDirectory, BACKEND_FEDERATION_MANIFEST_FILE));
+    if (!isRecord(manifest) || !isRecord(manifest.backendFederation)) throw new Error('[ultramodern-release-envelope] backend federation manifest is missing backendFederation metadata.');
+    assertIdentityBlock(manifest.backendFederation.deliveryUnit, identity, 'backendFederation.deliveryUnit', true);
+    const versionBoundary = manifest.backendFederation.versionBoundary;
+    assertIdentityBlock(isRecord(versionBoundary) ? versionBoundary.deliveryUnit : void 0, identity, 'backendFederation.versionBoundary.deliveryUnit', false);
+};
+const collectFiles = async (root)=>{
+    const resolvedRoot = node_path.resolve(root);
+    const realRoot = await promises.realpath(resolvedRoot);
+    const collectDirectory = async (relativeDirectory)=>{
+        const directory = node_path.join(resolvedRoot, ...relativeDirectory.split('/').filter(Boolean));
+        const entries = await promises.readdir(directory, {
+            withFileTypes: true
+        });
+        const files = [];
+        for (const entry of entries){
+            const logicalPath = node_path.posix.join(relativeDirectory, entry.name);
+            if ('release' === logicalPath || logicalPath.startsWith('release/')) continue;
+            if (entry.isDirectory()) {
+                files.push(...await collectDirectory(logicalPath));
+                continue;
+            }
+            if (entry.isFile()) {
+                files.push(logicalPath);
+                continue;
+            }
+            if (!entry.isSymbolicLink()) continue;
+            const lexicalPath = node_path.join(resolvedRoot, ...logicalPath.split('/'));
+            let realPath;
+            try {
+                realPath = await promises.realpath(lexicalPath);
+            } catch  {
+                throw new Error(`[ultramodern-release-envelope] symbolic link ${logicalPath} cannot be resolved.`);
+            }
+            if (!isFilesystemPathInside(realRoot, realPath)) throw new Error(`[ultramodern-release-envelope] symbolic link ${logicalPath} resolves outside artifactRoot.`);
+            const targetStat = await promises.stat(realPath);
+            if (!targetStat.isFile() && !targetStat.isDirectory()) throw new Error(`[ultramodern-release-envelope] symbolic link ${logicalPath} must resolve to a file or directory.`);
+            const targetLogicalPath = node_path.relative(realRoot, realPath).split(node_path.sep).join('/');
+            if ('release' === targetLogicalPath || targetLogicalPath.startsWith('release/')) throw new Error(`[ultramodern-release-envelope] symbolic link ${logicalPath} targets private release metadata.`);
+            if (targetStat.isDirectory() && isFilesystemPathInside(realPath, await promises.realpath(node_path.dirname(lexicalPath)))) throw new Error(`[ultramodern-release-envelope] symbolic link ${logicalPath} targets an ancestor directory.`);
+            files.push(logicalPath);
+        }
+        return files;
+    };
+    return (await collectDirectory('')).sort();
+};
+const releaseArtifact = (logicalPath, runtime)=>({
+        logicalPath,
+        runtime
+    });
+const createReleaseArtifactInputs = async (distDirectory, identity, target)=>{
+    const files = await collectFiles(distDirectory);
+    if ('node' === target && files.some((logicalPath)=>EFFECT_BFF_WORKER_PATTERN.test(logicalPath))) throw new Error('[ultramodern-release-envelope] Node target conflicts with a Cloudflare Effect API/BFF worker artifact; resolve the canonical deploy target instead of emitting a Node envelope for Cloudflare output.');
+    const uiClientPaths = files.filter((logicalPath)=>{
+        const topLevel = logicalPath.split('/')[0];
+        return 'static' === topLevel || 'html' === topLevel || 'public' === topLevel || [
+            'index.html',
+            'mf-manifest.json',
+            'mf-stats.json',
+            'remoteEntry.js',
+            'routes-manifest.json',
+            'loadable-stats.json'
+        ].includes(logicalPath);
+    });
+    const ssrPaths = 'node' === target ? files.filter((logicalPath)=>logicalPath.startsWith('bundles/') && COMPILED_MODULE_PATTERN.test(logicalPath)) : files.filter((logicalPath)=>logicalPath.startsWith('worker/') && COMPILED_MODULE_PATTERN.test(logicalPath) && !EFFECT_BFF_WORKER_PATTERN.test(logicalPath));
+    const nodeApiEntryPaths = files.filter((logicalPath)=>logicalPath.startsWith('api/') && COMPILED_MODULE_PATTERN.test(logicalPath));
+    const apiBackendPaths = 'node' === target ? files.filter((logicalPath)=>(logicalPath.startsWith('api/') || logicalPath.startsWith('shared/')) && COMPILED_MODULE_PATTERN.test(logicalPath)) : files.filter((logicalPath)=>EFFECT_BFF_WORKER_PATTERN.test(logicalPath));
+    if (0 === uiClientPaths.length) throw new Error(`[ultramodern-release-envelope] ${target} full-stack MicroVertical has no UI/client artifacts.`);
+    if (0 === ssrPaths.length) throw new Error(`[ultramodern-release-envelope] ${target} full-stack MicroVertical has no ${'node' === target ? 'Node' : 'workerd'} SSR artifacts.`);
+    if ('node' === target && 0 === nodeApiEntryPaths.length || 0 === apiBackendPaths.length) throw new Error(`[ultramodern-release-envelope] ${target} full-stack MicroVertical has no actual ${'node' === target ? 'compiled Node Effect API artifact' : 'Effect API/BFF worker artifact'}.`);
+    const clientExecutionPaths = await manifestReferencedClientModules(distDirectory, files);
+    if (0 === clientExecutionPaths.length) throw new Error('[ultramodern-release-envelope] UI/client manifest references no compiled execution module.');
+    const ssrExecutionPaths = await routeReferencedSsrModules(distDirectory, files, target);
+    await assertEveryCompiledIdentityCarrier(distDirectory, clientExecutionPaths, identity, 'manifest-referenced UI/client');
+    await assertEveryCompiledIdentityCarrier(distDirectory, ssrExecutionPaths, identity, 'node' === target ? 'route-referenced Node SSR' : 'route-referenced Cloudflare SSR');
+    await assertEveryCompiledIdentityCarrier(distDirectory, ssrPaths, identity, 'node' === target ? 'compiled Node SSR closure' : 'compiled Cloudflare SSR/workerd closure');
+    await assertEveryCompiledIdentityCarrier(distDirectory, 'node' === target ? nodeApiEntryPaths : apiBackendPaths, identity, 'node' === target ? 'Node API/backend' : 'Cloudflare API/backend');
+    await assertEveryCompiledIdentityCarrier(distDirectory, [
+        BACKEND_FEDERATION_REMOTE_ENTRY_FILE
+    ], identity, 'backend Module Federation container');
+    const runtimeByPath = new Map();
+    const add = (paths, runtime)=>{
+        for (const logicalPath of paths){
+            const existing = runtimeByPath.get(logicalPath);
+            if (existing && existing !== runtime) throw new Error(`[ultramodern-release-envelope] artifact "${logicalPath}" cannot carry conflicting runtimes "${existing}" and "${runtime}".`);
+            runtimeByPath.set(logicalPath, runtime);
+        }
+    };
+    add(uiClientPaths, 'browser');
+    add(ssrPaths, 'node' === target ? 'nodejs' : 'workerd');
+    add(apiBackendPaths, 'node' === target ? 'nodejs' : 'workerd-effect');
+    add([
+        BACKEND_FEDERATION_MANIFEST_FILE
+    ], 'module-federation-manifest');
+    add([
+        BACKEND_FEDERATION_REMOTE_ENTRY_FILE
+    ], 'node' === target ? 'nodejs' : 'commonjs-module');
+    const surfaces = {
+        uiClient: [
+            ...uiClientPaths
+        ].sort((left, right)=>left.localeCompare(right)),
+        ssr: [
+            ...ssrPaths
+        ].sort((left, right)=>left.localeCompare(right)),
+        apiBackend: [
+            ...apiBackendPaths
+        ].sort((left, right)=>left.localeCompare(right)),
+        backendFederation: {
+            manifest: BACKEND_FEDERATION_MANIFEST_FILE,
+            container: BACKEND_FEDERATION_REMOTE_ENTRY_FILE
+        }
+    };
+    const artifacts = [
+        ...runtimeByPath
+    ].map(([logicalPath, runtime])=>releaseArtifact(logicalPath, runtime)).sort((left, right)=>left.logicalPath.localeCompare(right.logicalPath));
+    return {
+        artifacts,
+        surfaces
+    };
+};
+const pathExists = async (filePath)=>{
+    try {
+        await promises.access(filePath);
+        return true;
+    } catch  {
+        return false;
+    }
+};
+const emitFrameworkMicroVerticalReleaseEnvelope = async ({ apiOnly, distDirectory, target })=>{
+    if (apiOnly) return;
+    const backendManifestPath = node_path.join(distDirectory, BACKEND_FEDERATION_MANIFEST_FILE);
+    const backendContainerPath = node_path.join(distDirectory, BACKEND_FEDERATION_REMOTE_ENTRY_FILE);
+    const [hasBackendManifest, hasBackendContainer] = await Promise.all([
+        pathExists(backendManifestPath),
+        pathExists(backendContainerPath)
+    ]);
+    if (!hasBackendManifest && !hasBackendContainer) return;
+    if (!hasBackendManifest || !hasBackendContainer) throw new Error('[ultramodern-release-envelope] full-stack MicroVertical backend federation manifest and container must be emitted together.');
+    const buildArtifact = await readBuildArtifact(distDirectory);
+    const identity = {
+        unitId: buildArtifact.deliveryUnit.unitId,
+        buildMarker: buildArtifact.deliveryUnit.buildMarker,
+        sourceRevision: buildArtifact.deliveryUnit.sourceRevision,
+        releaseVersion: buildArtifact.deliveryUnit.version
+    };
+    await readBackendManifest(distDirectory, identity);
+    const { artifacts, surfaces } = await createReleaseArtifactInputs(distDirectory, identity, target);
+    const envelope = await createMicroVerticalReleaseEnvelope({
+        artifactRoot: distDirectory,
+        target,
+        identity,
+        artifacts,
+        surfaces
+    });
+    await writeReleaseEnvelope(distDirectory, envelope);
+    return envelope;
+};
+const readFrameworkMicroVerticalReleaseEnvelope = async ({ artifactRoot, expectedTarget, logicalPathForArtifact, required = false })=>{
+    const envelopePath = await resolveSafeReleaseEnvelopePath({
+        artifactRoot,
+        createDirectory: false
+    });
+    if (!envelopePath) {
+        if (required) throw new Error(`[ultramodern-release-envelope] required envelope is missing at ${MICROVERTICAL_RELEASE_ENVELOPE_PATH}.`);
+        return;
+    }
+    return verifyMicroVerticalReleaseEnvelope(await readJson(envelopePath), {
+        artifactRoot,
+        ...expectedTarget ? {
+            expectedTarget
+        } : {},
+        ...logicalPathForArtifact ? {
+            logicalPathForArtifact
+        } : {}
+    });
+};
+const verifyBuildOutputReleaseEnvelope = async (distDirectory, expectedTarget)=>{
+    const [hasEnvelope, hasBuildArtifact, hasBackendManifest, hasBackendEntry] = await Promise.all([
+        pathExists(node_path.join(distDirectory, MICROVERTICAL_RELEASE_ENVELOPE_PATH)),
+        pathExists(node_path.join(distDirectory, ULTRAMODERN_BUILD_ARTIFACT_FILE)),
+        pathExists(node_path.join(distDirectory, BACKEND_FEDERATION_MANIFEST_FILE)),
+        pathExists(node_path.join(distDirectory, BACKEND_FEDERATION_REMOTE_ENTRY_FILE))
+    ]);
+    const isFullStackMicroVertical = hasBuildArtifact && (hasBackendManifest || hasBackendEntry);
+    return readFrameworkMicroVerticalReleaseEnvelope({
+        artifactRoot: distDirectory,
+        ...expectedTarget ? {
+            expectedTarget
+        } : {},
+        required: hasEnvelope || isFullStackMicroVertical
+    });
+};
+const verifyNodeReleaseEnvelopeStaging = async ({ outputDirectory })=>readFrameworkMicroVerticalReleaseEnvelope({
+        artifactRoot: outputDirectory,
+        expectedTarget: 'node',
+        required: true
+    });
+const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity)=>{
+    const files = await collectFiles(outputDirectory);
+    for (const requiredPath of [
+        'index.js',
+        'package.json',
+        BACKEND_FEDERATION_MANIFEST_FILE,
+        BACKEND_FEDERATION_REMOTE_ENTRY_FILE
+    ])if (!files.includes(requiredPath)) throw new Error(`[ultramodern-release-envelope] final Node staging is missing ${requiredPath}.`);
+    const backendFederationPaths = new Set([
+        BACKEND_FEDERATION_MANIFEST_FILE,
+        BACKEND_FEDERATION_REMOTE_ENTRY_FILE
+    ]);
+    const uiClientPaths = files.filter((logicalPath)=>{
+        const topLevel = logicalPath.split('/')[0];
+        return 'static' === topLevel || 'html' === topLevel || 'public' === topLevel || [
+            'index.html',
+            'mf-manifest.json',
+            'mf-stats.json',
+            'remoteEntry.js',
+            'routes-manifest.json',
+            'loadable-stats.json'
+        ].includes(logicalPath);
+    });
+    const ssrPaths = files.filter((logicalPath)=>'index.js' === logicalPath || logicalPath.startsWith('bundles/') && COMPILED_MODULE_PATTERN.test(logicalPath));
+    const apiBackendPaths = files.filter((logicalPath)=>(logicalPath.startsWith('api/') || logicalPath.startsWith('shared/')) && COMPILED_MODULE_PATTERN.test(logicalPath));
+    for (const [surface, paths] of [
+        [
+            'UI/client',
+            uiClientPaths
+        ],
+        [
+            'Node SSR',
+            ssrPaths
+        ],
+        [
+            'Node API/backend',
+            apiBackendPaths
+        ]
+    ])if (0 === paths.length) throw new Error(`[ultramodern-release-envelope] final Node staging has no ${surface} artifacts.`);
+    const clientExecutionPaths = await manifestReferencedClientModules(outputDirectory, files);
+    const ssrExecutionPaths = await routeReferencedSsrModules(outputDirectory, files, 'node');
+    await assertEveryCompiledIdentityCarrier(outputDirectory, clientExecutionPaths, identity, 'final manifest-referenced Node UI/client');
+    await assertEveryCompiledIdentityCarrier(outputDirectory, ssrExecutionPaths, identity, 'final route-referenced Node SSR');
+    await assertEveryCompiledIdentityCarrier(outputDirectory, ssrPaths.filter((logicalPath)=>'index.js' !== logicalPath), identity, 'final compiled Node SSR closure');
+    await assertEveryCompiledIdentityCarrier(outputDirectory, apiBackendPaths.filter((logicalPath)=>logicalPath.startsWith('api/')), identity, 'final Node API/backend');
+    await assertEveryCompiledIdentityCarrier(outputDirectory, [
+        BACKEND_FEDERATION_REMOTE_ENTRY_FILE
+    ], identity, 'final Node backend Module Federation container');
+    const runtimeByPath = new Map(files.filter((logicalPath)=>!backendFederationPaths.has(logicalPath)).map((logicalPath)=>[
+            logicalPath,
+            'nodejs-deployment'
+        ]));
+    for (const logicalPath of uiClientPaths)runtimeByPath.set(logicalPath, 'browser');
+    for (const logicalPath of ssrPaths)runtimeByPath.set(logicalPath, 'nodejs');
+    for (const logicalPath of apiBackendPaths)runtimeByPath.set(logicalPath, 'nodejs');
+    runtimeByPath.set(BACKEND_FEDERATION_MANIFEST_FILE, 'module-federation-manifest');
+    runtimeByPath.set(BACKEND_FEDERATION_REMOTE_ENTRY_FILE, 'nodejs');
+    return {
+        artifacts: [
+            ...runtimeByPath
+        ].map(([logicalPath, runtime])=>releaseArtifact(logicalPath, runtime)).sort((left, right)=>left.logicalPath.localeCompare(right.logicalPath)),
+        surfaces: {
+            uiClient: [
+                ...uiClientPaths
+            ].sort((left, right)=>left.localeCompare(right)),
+            ssr: [
+                ...ssrPaths
+            ].sort((left, right)=>left.localeCompare(right)),
+            apiBackend: [
+                ...apiBackendPaths
+            ].sort((left, right)=>left.localeCompare(right)),
+            backendFederation: {
+                manifest: BACKEND_FEDERATION_MANIFEST_FILE,
+                container: BACKEND_FEDERATION_REMOTE_ENTRY_FILE
+            }
+        }
+    };
+};
+const emitNodeStagedReleaseEnvelope = async ({ distDirectory, outputDirectory })=>{
+    const source = await verifyBuildOutputReleaseEnvelope(distDirectory, 'node');
+    if (!source) return;
+    const { artifacts, surfaces } = await createNodeStagedReleaseArtifactInputs(outputDirectory, source.identity);
+    const staged = await createMicroVerticalReleaseEnvelope({
+        artifactRoot: outputDirectory,
+        target: 'node',
+        identity: source.identity,
+        artifacts,
+        surfaces
+    });
+    await writeReleaseEnvelope(outputDirectory, staged);
+    return staged;
+};
+const stageCloudflareReleaseEnvelope = async ({ distDirectory, outputDirectory })=>{
+    const source = await verifyBuildOutputReleaseEnvelope(distDirectory, 'cloudflare');
+    if (!source) return;
+    const stagedEnvelopePath = node_path.join(outputDirectory, MICROVERTICAL_RELEASE_ENVELOPE_PATH);
+    if (await pathExists(stagedEnvelopePath)) throw new Error('[ultramodern-release-envelope] Cloudflare staging contains a stale envelope before final output generation.');
+    return source;
+};
+const createCloudflareStagedReleaseArtifactInputs = async (outputDirectory, identity)=>{
+    const files = await collectFiles(outputDirectory);
+    for (const requiredPath of [
+        'server/index.mjs',
+        'server/modern-worker-manifest.json',
+        'wrangler.json',
+        'package.json',
+        'worker/package.json'
+    ])if (!files.includes(requiredPath)) throw new Error(`[ultramodern-release-envelope] final Cloudflare staging is missing ${requiredPath}.`);
+    if (files.some((logicalPath)=>'public/release' === logicalPath || logicalPath.startsWith('public/release/'))) throw new Error('[ultramodern-release-envelope] final Cloudflare envelope must remain private and cannot be staged under public/release.');
+    const backendManifestPath = `public/${BACKEND_FEDERATION_MANIFEST_FILE}`;
+    const backendContainerPath = `public/${BACKEND_FEDERATION_REMOTE_ENTRY_FILE}`;
+    const apiBackendPaths = files.filter((logicalPath)=>EFFECT_BFF_WORKER_PATTERN.test(logicalPath));
+    const ssrPaths = files.filter((logicalPath)=>(logicalPath.startsWith('server/') || logicalPath.startsWith('worker/')) && COMPILED_MODULE_PATTERN.test(logicalPath) && !EFFECT_BFF_WORKER_PATTERN.test(logicalPath));
+    const uiClientPaths = files.filter((logicalPath)=>logicalPath.startsWith('public/') && logicalPath !== backendManifestPath && logicalPath !== backendContainerPath);
+    for (const [surface, paths] of [
+        [
+            'UI/client',
+            uiClientPaths
+        ],
+        [
+            'Cloudflare SSR',
+            ssrPaths
+        ],
+        [
+            'Cloudflare API/backend',
+            apiBackendPaths
+        ]
+    ])if (0 === paths.length) throw new Error(`[ultramodern-release-envelope] final Cloudflare staging has no ${surface} artifacts.`);
+    for (const logicalPath of [
+        backendManifestPath,
+        backendContainerPath
+    ])if (!files.includes(logicalPath)) throw new Error(`[ultramodern-release-envelope] final Cloudflare staging is missing ${logicalPath}.`);
+    const clientExecutionPaths = await manifestReferencedClientModules(outputDirectory, files, 'public/mf-manifest.json');
+    const ssrExecutionPaths = await routeReferencedSsrModules(outputDirectory, files, 'cloudflare', 'server/route.json');
+    await assertEveryCompiledIdentityCarrier(outputDirectory, clientExecutionPaths, identity, 'final manifest-referenced Cloudflare UI/client');
+    await assertEveryCompiledIdentityCarrier(outputDirectory, ssrExecutionPaths, identity, 'final route-referenced Cloudflare SSR');
+    await assertEveryCompiledIdentityCarrier(outputDirectory, ssrPaths.filter((logicalPath)=>logicalPath.startsWith('worker/')), identity, 'final compiled Cloudflare SSR/workerd closure');
+    await assertEveryCompiledIdentityCarrier(outputDirectory, apiBackendPaths, identity, 'final Cloudflare API/backend');
+    await assertEveryCompiledIdentityCarrier(outputDirectory, [
+        backendContainerPath
+    ], identity, 'final Cloudflare backend Module Federation container');
+    const runtimeByPath = new Map();
+    for (const logicalPath of files)runtimeByPath.set(logicalPath, 'cloudflare-deployment');
+    const add = (paths, runtime)=>{
+        for (const logicalPath of paths)runtimeByPath.set(logicalPath, runtime);
+    };
+    add(uiClientPaths, 'browser');
+    add(ssrPaths, 'workerd');
+    add(apiBackendPaths, 'workerd-effect');
+    add([
+        backendManifestPath
+    ], 'module-federation-manifest');
+    add([
+        backendContainerPath
+    ], 'commonjs-module');
+    return {
+        artifacts: [
+            ...runtimeByPath
+        ].map(([logicalPath, runtime])=>releaseArtifact(logicalPath, runtime)).sort((left, right)=>left.logicalPath.localeCompare(right.logicalPath)),
+        surfaces: {
+            uiClient: [
+                ...uiClientPaths
+            ].sort((left, right)=>left.localeCompare(right)),
+            ssr: [
+                ...ssrPaths
+            ].sort((left, right)=>left.localeCompare(right)),
+            apiBackend: [
+                ...apiBackendPaths
+            ].sort((left, right)=>left.localeCompare(right)),
+            backendFederation: {
+                manifest: backendManifestPath,
+                container: backendContainerPath
+            }
+        }
+    };
+};
+const emitCloudflareStagedReleaseEnvelope = async ({ distDirectory, outputDirectory })=>{
+    const source = await verifyBuildOutputReleaseEnvelope(distDirectory, 'cloudflare');
+    if (!source) return;
+    const { artifacts, surfaces } = await createCloudflareStagedReleaseArtifactInputs(outputDirectory, source.identity);
+    const staged = await createMicroVerticalReleaseEnvelope({
+        artifactRoot: outputDirectory,
+        target: 'cloudflare',
+        identity: source.identity,
+        artifacts,
+        surfaces
+    });
+    await writeReleaseEnvelope(outputDirectory, staged);
+    return staged;
+};
+const verifyCloudflareReleaseEnvelopeStaging = async (outputDirectory)=>readFrameworkMicroVerticalReleaseEnvelope({
+        artifactRoot: outputDirectory,
+        expectedTarget: 'cloudflare',
+        required: true
+    });
+export { MICROVERTICAL_RELEASE_ENVELOPE_PATH, emitCloudflareStagedReleaseEnvelope, emitFrameworkMicroVerticalReleaseEnvelope, emitNodeStagedReleaseEnvelope, readFrameworkMicroVerticalReleaseEnvelope, stageCloudflareReleaseEnvelope, verifyBuildOutputReleaseEnvelope, verifyCloudflareReleaseEnvelopeStaging, verifyNodeReleaseEnvelopeStaging };