@bleedingdev/modern-js-app-tools-extensions 3.9.0-ultramodern.8 → 3.9.3-ultramodern.1

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

@@ -2,14 +2,34 @@ import "node:module";
 import { createHash } from "node:crypto";
 import promises from "node:fs/promises";
 import node_path from "node:path";
-import { BACKEND_FEDERATION_MANIFEST_FILE, BACKEND_FEDERATION_REMOTE_ENTRY_FILE, ULTRAMODERN_BUILD_ARTIFACT_FILE, isUltramodernBuildArtifact } from "@modern-js/backend-federation-contracts";
+import { isDeepStrictEqual } from "node:util";
+import { BACKEND_FEDERATION_MANIFEST_FILE, BACKEND_FEDERATION_REMOTE_ENTRY_FILE, ULTRAMODERN_BUILD_ARTIFACT_FILE, ULTRAMODERN_BUILD_ARTIFACT_PATH, assertRendererProfileCompatibility, isUltramodernBuildArtifact } from "@modern-js/backend-federation-contracts";
+import { readBuildIdentity } from "../backend-federation-build/config.mjs";
+import { resolveTopologyDeliveryUnit, resolveTopologyReleaseRole, resolveWorkerDeliveryUnitStamp } from "../cloudflare/delivery-unit.mjs";
 import { canonicalSerializeMicroVerticalReleaseEnvelope, createMicroVerticalReleaseEnvelope, verifyMicroVerticalReleaseEnvelope } from "./index.mjs";
+import { SHELL_RELEASE_ENVELOPE_KIND } from "./types.mjs";
 const MICROVERTICAL_RELEASE_ENVELOPE_PATH = 'release/microvertical-release-envelope.json';
 const MICROVERTICAL_RELEASE_IDENTITY_CARRIERS_PATH = 'release/microvertical-release-identity-carriers.json';
 const MICROVERTICAL_RELEASE_IDENTITY_CARRIERS_KIND = 'ultramodern-release-identity-carriers';
 const MICROVERTICAL_RELEASE_IDENTITY_CARRIERS_SCHEMA_VERSION = 1;
 const COMPILED_MODULE_PATTERN = /\.(?:c|m)?js$/u;
 const EFFECT_BFF_WORKER_PATTERN = /^worker\/__modern_bff_effect\.(?:c|m)?js$/u;
+const EFFECT_BFF_WORKER_SUPPORT_PATTERN = /^worker\/__modern_worker_(?:runtime|shared)_*\.(?:c|m)?js$/u;
+const isEffectBffWorkerArtifact = (logicalPath)=>EFFECT_BFF_WORKER_PATTERN.test(logicalPath) || EFFECT_BFF_WORKER_SUPPORT_PATTERN.test(logicalPath);
+const effectBffWorkerArtifacts = (files)=>files.some((logicalPath)=>EFFECT_BFF_WORKER_PATTERN.test(logicalPath)) ? files.filter(isEffectBffWorkerArtifact) : [];
+const CRAWLER_POLICY_PATH = 'public/robots.txt';
+const isPublicMetadataPath = (logicalPath)=>'public/_headers' === logicalPath || /^public\/\.well-known\/[^/]+\.json$/u.test(logicalPath);
+const PUBLIC_BUILD_ARTIFACT_PATH = `public/${ULTRAMODERN_BUILD_ARTIFACT_FILE}`;
+const DECLARED_PUBLIC_ASSET_RUNTIME = 'public-asset';
+const resolveDeclaredPublicAssets = (files, declaredPublicAssets, target)=>{
+    const staged = new Set(files);
+    const declared = new Set();
+    for (const logicalPath of declaredPublicAssets){
+        if (!logicalPath.startsWith('public/') || !staged.has(logicalPath)) throw new Error(`[ultramodern-release-envelope] final ${target} staging has no declared public asset file ${JSON.stringify(logicalPath)}.`);
+        declared.add(logicalPath);
+    }
+    return declared;
+};
 const isRecord = (value)=>'object' == typeof value && null !== value && !Array.isArray(value);
 const flattenStrings = (value)=>'string' == typeof value ? [
         value
@@ -23,7 +43,12 @@ const collectNestedStrings = (value, key)=>{
         ]);
 };
 const emptyProducerRouteModules = async (distDirectory, files, manifest, manifestLogicalPath)=>{
-    if (!isRecord(manifest) || !Array.isArray(manifest.exposes) || 0 !== manifest.exposes.length || !Array.isArray(manifest.remotes) || 0 !== manifest.remotes.length || !isRecord(manifest.metaData) || !isRecord(manifest.metaData.remoteEntry) || '' !== manifest.metaData.remoteEntry.name || '' !== manifest.metaData.remoteEntry.path || 'global' !== manifest.metaData.remoteEntry.type) return [];
+    if (!isRecord(manifest) || !Array.isArray(manifest.exposes) || 0 !== manifest.exposes.length || !Array.isArray(manifest.remotes) || manifest.remotes.some((remote)=>!isRecord(remote) || [
+            'federationContainerName',
+            'moduleName',
+            'alias',
+            'entry'
+        ].some((key)=>'string' != typeof remote[key] || 0 === remote[key].trim().length)) || !isRecord(manifest.metaData) || !isRecord(manifest.metaData.remoteEntry) || '' !== manifest.metaData.remoteEntry.name || '' !== manifest.metaData.remoteEntry.path || 'global' !== manifest.metaData.remoteEntry.type) return [];
     const publicPath = manifest.metaData.publicPath;
     const safeReference = (value)=>'string' == typeof value && value.length > 0 && !/[\\\\%?#\s]/u.test(value) && !value.split('/').some((segment)=>'.' === segment || '..' === segment);
     if (!safeReference(publicPath)) return [];
@@ -124,11 +149,14 @@ const writeReleaseEnvelope = async (artifactRoot, envelope)=>{
     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 readBuildArtifact = async (distDirectory, requirePromotable = true)=>{
     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.');
+    if ('workspace' === artifact.deliveryUnit.sourceRevision) {
+        if (!requirePromotable) return;
+        throw new Error('[ultramodern-release-envelope] sourceRevision "workspace" cannot produce a promotable envelope.');
+    }
     return artifact;
 };
 const assertIdentityBlock = (value, identity, location, includeReleaseVersion)=>{
@@ -197,7 +225,7 @@ const releaseArtifact = (logicalPath, runtime)=>({
 const writeReleaseIdentityCarrierMetadata = async (artifactRoot, identity, carrierPaths)=>{
     const surfacesByPath = new Map();
     for (const [surface, logicalPaths] of Object.entries(carrierPaths)){
-        if (0 === logicalPaths.length) throw new Error(`[ultramodern-release-envelope] ${surface} has no declared release-identity carrier artifact.`);
+        if (0 === logicalPaths.length && 'ssr' !== surface && 'uiClient' !== surface) throw new Error(`[ultramodern-release-envelope] ${surface} has no declared release-identity carrier artifact.`);
         for (const logicalPath of logicalPaths){
             const surfaces = surfacesByPath.get(logicalPath) ?? new Set();
             surfaces.add(surface);
@@ -237,12 +265,14 @@ const writeReleaseIdentityCarrierMetadata = async (artifactRoot, identity, carri
     }, null, 2)}\n`);
     return releaseArtifact(MICROVERTICAL_RELEASE_IDENTITY_CARRIERS_PATH, 'release-identity-metadata');
 };
-const createReleaseArtifactInputs = async (distDirectory, identity, target)=>{
+const createReleaseArtifactInputs = async (distDirectory, identity, target, apiOnly, uiOnly, shellConsumer)=>{
+    const backendProducer = !uiOnly && !shellConsumer;
     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 effectWorkerPaths = effectBffWorkerArtifacts(files);
+    if ('node' === target && files.some(isEffectBffWorkerArtifact)) 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 || [
+        return 'static' === topLevel || 'html' === topLevel || 'public' === topLevel && logicalPath !== CRAWLER_POLICY_PATH && logicalPath !== PUBLIC_BUILD_ARTIFACT_PATH && !isPublicMetadataPath(logicalPath) || [
             'index.html',
             'mf-manifest.json',
             'mf-stats.json',
@@ -251,16 +281,19 @@ const createReleaseArtifactInputs = async (distDirectory, identity, target)=>{
             '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 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) && !effectWorkerPaths.includes(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);
-    if (0 === ssrExecutionPaths.length) throw new Error(`[ultramodern-release-envelope] route manifest references no emitted ${'node' === target ? 'Node' : 'Cloudflare'} SSR execution module.`);
+    const apiBackendPaths = 'node' === target ? files.filter((logicalPath)=>(logicalPath.startsWith('api/') || logicalPath.startsWith('shared/')) && COMPILED_MODULE_PATTERN.test(logicalPath)) : effectWorkerPaths;
+    if (backendProducer && 'cloudflare' === target && 0 === effectWorkerPaths.length) throw new Error('[ultramodern-release-envelope] cloudflare MicroVertical has no actual Effect API/BFF worker artifact.');
+    if (apiOnly && (uiClientPaths.length > 0 || ssrPaths.length > 0)) throw new Error('[ultramodern-release-envelope] API-only MicroVertical emitted an undeclared UI/client or SSR surface.');
+    if (!apiOnly && 0 === uiClientPaths.length) throw new Error(`[ultramodern-release-envelope] ${target} full-stack MicroVertical has no UI/client artifacts.`);
+    if (!apiOnly && 0 === ssrPaths.length) throw new Error(`[ultramodern-release-envelope] ${target} full-stack MicroVertical has no ${'node' === target ? 'Node' : 'workerd'} SSR artifacts.`);
+    if (uiOnly && (apiBackendPaths.length > 0 || nodeApiEntryPaths.length > 0)) throw new Error('[ultramodern-release-envelope] UI-only application emitted an undeclared API/backend artifact.');
+    if (backendProducer && ('node' === target && 0 === nodeApiEntryPaths.length || 0 === apiBackendPaths.length)) throw new Error(`[ultramodern-release-envelope] ${target} MicroVertical has no actual ${'node' === target ? 'compiled Node Effect API artifact' : 'Effect API/BFF worker artifact'}.`);
+    const clientExecutionPaths = apiOnly ? [] : await manifestReferencedClientModules(distDirectory, files);
+    if (!apiOnly && 0 === clientExecutionPaths.length) throw new Error('[ultramodern-release-envelope] UI/client manifest references no compiled execution module.');
+    const ssrExecutionPaths = apiOnly ? [] : await routeReferencedSsrModules(distDirectory, files, target);
+    if (!apiOnly && 0 === ssrExecutionPaths.length) throw new Error(`[ultramodern-release-envelope] route manifest references no emitted ${'node' === target ? 'Node' : 'Cloudflare'} SSR execution module.`);
     const runtimeByPath = new Map();
     const add = (paths, runtime)=>{
         for (const logicalPath of paths){
@@ -270,14 +303,25 @@ const createReleaseArtifactInputs = async (distDirectory, identity, target)=>{
         }
     };
     add(uiClientPaths, 'browser');
+    add(files.filter((logicalPath)=>logicalPath === CRAWLER_POLICY_PATH), 'crawler-policy');
+    add(files.filter(isPublicMetadataPath), 'public-metadata');
     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');
+        ULTRAMODERN_BUILD_ARTIFACT_FILE
+    ], 'release-identity-metadata');
+    add(files.filter((logicalPath)=>logicalPath === PUBLIC_BUILD_ARTIFACT_PATH), 'release-identity-metadata');
+    if (backendProducer) {
+        add([
+            BACKEND_FEDERATION_MANIFEST_FILE
+        ], 'module-federation-manifest');
+        add([
+            BACKEND_FEDERATION_REMOTE_ENTRY_FILE
+        ], 'node' === target ? 'nodejs' : 'commonjs-module');
+    }
+    if (shellConsumer) {
+        for (const logicalPath of files)if (!runtimeByPath.has(logicalPath)) runtimeByPath.set(logicalPath, `${target}-deployment`);
+    }
     const surfaces = {
         uiClient: [
             ...uiClientPaths
@@ -288,20 +332,26 @@ const createReleaseArtifactInputs = async (distDirectory, identity, target)=>{
         apiBackend: [
             ...apiBackendPaths
         ].sort((left, right)=>left.localeCompare(right)),
-        backendFederation: {
-            manifest: BACKEND_FEDERATION_MANIFEST_FILE,
-            container: BACKEND_FEDERATION_REMOTE_ENTRY_FILE
-        }
+        ...backendProducer ? {
+            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));
     const identityCarrierMetadata = await writeReleaseIdentityCarrierMetadata(distDirectory, identity, {
-        apiBackend: apiBackendPaths,
-        backendFederation: [
-            BACKEND_FEDERATION_MANIFEST_FILE,
-            BACKEND_FEDERATION_REMOTE_ENTRY_FILE
-        ],
+        ...apiBackendPaths.length > 0 ? {
+            apiBackend: apiBackendPaths
+        } : {},
+        ...backendProducer ? {
+            backendFederation: [
+                BACKEND_FEDERATION_MANIFEST_FILE,
+                BACKEND_FEDERATION_REMOTE_ENTRY_FILE
+            ]
+        } : {},
         ssr: [
             ...new Set([
                 ...ssrExecutionPaths,
@@ -318,6 +368,25 @@ const createReleaseArtifactInputs = async (distDirectory, identity, target)=>{
         surfaces
     };
 };
+const releaseEnvelopeSurfaces = (surfaces, shellConsumer)=>{
+    if (!shellConsumer) return {
+        surfaces
+    };
+    const { uiClient, ssr, apiBackend } = surfaces;
+    return {
+        kind: SHELL_RELEASE_ENVELOPE_KIND,
+        surfaces: {
+            uiClient,
+            ssr,
+            apiBackend
+        }
+    };
+};
+const assertShellBuildIdentity = async (appDirectory, distDirectory)=>{
+    const source = await readBuildIdentity(appDirectory);
+    const finalized = await pathExists(node_path.join(distDirectory, ULTRAMODERN_BUILD_ARTIFACT_FILE)) ? await resolveWorkerDeliveryUnitStamp(appDirectory, distDirectory) : void 0;
+    if (!source.artifact || !finalized || finalized.unitId !== source.unitId) throw new Error('[ultramodern-release-envelope] Shell is missing its native compiled delivery-unit identity.');
+};
 const pathExists = async (filePath)=>{
     try {
         await promises.access(filePath);
@@ -326,36 +395,79 @@ const pathExists = async (filePath)=>{
         return false;
     }
 };
-const emitFrameworkMicroVerticalReleaseEnvelope = async ({ apiOnly, distDirectory, target })=>{
-    if (apiOnly) return;
+const emitFrameworkMicroVerticalReleaseEnvelope = async ({ apiOnly, appDirectory, distDirectory, requirePromotable = true, expectedRendererProfile, role, target })=>{
+    const declaredRole = appDirectory ? await resolveTopologyReleaseRole(appDirectory) : void 0;
+    if (void 0 !== role && void 0 !== declaredRole && role !== declaredRole) throw new Error('[ultramodern-release-envelope] Configured release role disagrees with the declared topology app.');
+    const shellConsumer = (declaredRole ?? role ?? 'microvertical') === 'shell';
     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);
+    if (shellConsumer) {
+        if (apiOnly || hasBackendManifest || hasBackendContainer || !appDirectory) throw new Error('[ultramodern-release-envelope] Shell requires a full-stack application source and cannot declare a backend federation producer.');
+        await assertShellBuildIdentity(appDirectory, distDirectory);
+    } else if (!apiOnly && !hasBackendManifest && !hasBackendContainer) {
+        const source = appDirectory ? node_path.join(appDirectory, ULTRAMODERN_BUILD_ARTIFACT_PATH) : void 0;
+        const participationPaths = [
+            node_path.join(distDirectory, ULTRAMODERN_BUILD_ARTIFACT_FILE),
+            backendManifestPath,
+            backendContainerPath,
+            ...source ? [
+                source,
+                source.replace(/\.json$/u, '.ts')
+            ] : []
+        ];
+        const hasParticipationEntry = (await Promise.all(participationPaths.map(async (filePath)=>{
+            try {
+                await promises.lstat(filePath);
+                return true;
+            } catch (error) {
+                if (isMissingPathError(error)) return false;
+                throw error;
+            }
+        }))).some(Boolean);
+        if (!hasParticipationEntry && (!appDirectory || !await resolveTopologyDeliveryUnit(appDirectory))) return;
+    }
+    const buildArtifact = await readBuildArtifact(distDirectory, requirePromotable);
+    const declared = appDirectory && buildArtifact ? await resolveWorkerDeliveryUnitStamp(appDirectory, distDirectory) : void 0;
+    const uiOnly = Boolean(declared?.surfaces.ui && !declared.surfaces.api);
+    if (uiOnly && (apiOnly || hasBackendManifest || hasBackendContainer)) throw new Error('[ultramodern-release-envelope] UI-only application cannot declare API-only configuration or backend federation output.');
+    if (!hasBackendManifest && !hasBackendContainer && !apiOnly && !buildArtifact) return;
+    if (!shellConsumer && !uiOnly && (!hasBackendManifest || !hasBackendContainer)) throw new Error('[ultramodern-release-envelope] MicroVertical backend federation manifest and container must be emitted together.');
+    if (!buildArtifact) return;
+    const builtUi = buildArtifact.surfaces.ui;
+    if (Boolean(builtUi) === apiOnly) throw new Error('[ultramodern-release-envelope] build artifact UI surface must match the configured application surface.');
+    if (void 0 !== expectedRendererProfile) assertRendererProfileCompatibility(expectedRendererProfile, builtUi?.rendererProfile);
+    const ui = builtUi ? {
+        rendererIdentity: builtUi.rendererIdentity,
+        rendererProfile: builtUi.rendererProfile,
+        routerBindings: builtUi.routerBindings
+    } : void 0;
     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);
+    if (!shellConsumer && !uiOnly) await readBackendManifest(distDirectory, identity);
+    const { artifacts, surfaces } = await createReleaseArtifactInputs(distDirectory, identity, target, apiOnly, uiOnly, shellConsumer);
     const envelope = await createMicroVerticalReleaseEnvelope({
         artifactRoot: distDirectory,
         target,
         identity,
+        ...ui ? {
+            ui
+        } : {},
         artifacts,
-        surfaces
+        ...releaseEnvelopeSurfaces(surfaces, shellConsumer)
     });
+    await verifyBuildArtifactCarriers(distDirectory, envelope);
     await writeReleaseEnvelope(distDirectory, envelope);
     return envelope;
 };
-const readFrameworkMicroVerticalReleaseEnvelope = async ({ artifactRoot, expectedTarget, logicalPathForArtifact, required = false })=>{
+const readFrameworkMicroVerticalReleaseEnvelope = async ({ artifactRoot, expectedTarget, logicalPathForArtifact, expectedRendererProfile, required = false })=>{
     const envelopePath = await resolveSafeReleaseEnvelopePath({
         artifactRoot,
         createDirectory: false
@@ -364,30 +476,55 @@ const readFrameworkMicroVerticalReleaseEnvelope = async ({ artifactRoot, expecte
         if (required) throw new Error(`[ultramodern-release-envelope] required envelope is missing at ${MICROVERTICAL_RELEASE_ENVELOPE_PATH}.`);
         return;
     }
-    return verifyMicroVerticalReleaseEnvelope(await readJson(envelopePath), {
+    const envelope = await verifyMicroVerticalReleaseEnvelope(await readJson(envelopePath), {
         artifactRoot,
         ...expectedTarget ? {
             expectedTarget
         } : {},
         ...logicalPathForArtifact ? {
             logicalPathForArtifact
+        } : {},
+        ...expectedRendererProfile ? {
+            expectedRendererProfile
         } : {}
     });
+    await verifyBuildArtifactCarriers(artifactRoot, envelope, logicalPathForArtifact);
+    return envelope;
+};
+const verifyBuildArtifactCarriers = async (artifactRoot, envelope, logicalPathForArtifact)=>{
+    const carriers = envelope.artifacts.filter((artifact)=>artifact.logicalPath === ULTRAMODERN_BUILD_ARTIFACT_FILE || artifact.logicalPath === PUBLIC_BUILD_ARTIFACT_PATH);
+    if (0 === carriers.length) throw new Error('[ultramodern-release-envelope] immutable build artifact must be bound to the release envelope.');
+    for (const artifact of carriers){
+        if ('file' !== artifact.kind || 'release-identity-metadata' !== artifact.runtime) throw new Error('[ultramodern-release-envelope] immutable build artifact must be a real file with runtime "release-identity-metadata".');
+        const logicalPath = logicalPathForArtifact?.(artifact) ?? artifact.logicalPath;
+        const built = await readJson(node_path.join(artifactRoot, logicalPath));
+        if (!isUltramodernBuildArtifact(built)) throw new Error('[ultramodern-release-envelope] bound build artifact is invalid.');
+        assertIdentityBlock(built.deliveryUnit, envelope.identity, 'buildArtifact.deliveryUnit', true);
+        if (Boolean(built.surfaces.ui) !== Boolean(envelope.ui)) throw new Error('[ultramodern-release-envelope] bound build artifact UI surface differs from the release envelope.');
+        if (envelope.ui && built.surfaces.ui) {
+            if (!isDeepStrictEqual(envelope.ui.routerBindings, built.surfaces.ui.routerBindings)) throw new Error('[ultramodern-release-envelope] buildArtifact.ui.routerBindings differ from the release envelope.');
+            assertRendererProfileCompatibility(envelope.ui.rendererProfile, built.surfaces.ui.rendererProfile);
+            for (const field of [
+                'renderer',
+                'protocolVersion',
+                'appId',
+                'entryName',
+                'buildId'
+            ])if (envelope.ui.rendererIdentity[field] !== built.surfaces.ui.rendererIdentity[field]) throw new Error(`[ultramodern-release-envelope] buildArtifact.ui.rendererIdentity.${field} differs from the release envelope.`);
+        }
+    }
 };
 const verifyBuildOutputReleaseEnvelope = async (distDirectory, expectedTarget)=>{
-    const [hasEnvelope, hasBuildArtifact, hasBackendManifest, hasBackendEntry] = await Promise.all([
+    const [hasEnvelope, hasBuildArtifact] = 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))
+        pathExists(node_path.join(distDirectory, ULTRAMODERN_BUILD_ARTIFACT_FILE))
     ]);
-    const isFullStackMicroVertical = hasBuildArtifact && (hasBackendManifest || hasBackendEntry);
     return readFrameworkMicroVerticalReleaseEnvelope({
         artifactRoot: distDirectory,
         ...expectedTarget ? {
             expectedTarget
         } : {},
-        required: hasEnvelope || isFullStackMicroVertical
+        required: hasEnvelope || hasBuildArtifact
     });
 };
 const verifyNodeReleaseEnvelopeStaging = async ({ outputDirectory })=>readFrameworkMicroVerticalReleaseEnvelope({
@@ -395,21 +532,26 @@ const verifyNodeReleaseEnvelopeStaging = async ({ outputDirectory })=>readFramew
         expectedTarget: 'node',
         required: true
     });
-const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity)=>{
+const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity, apiOnly, uiOnly, declaredPublicAssets, shellConsumer)=>{
+    const backendProducer = !uiOnly && !shellConsumer;
     const files = await collectFiles(outputDirectory);
+    const declaredPublicAssetPaths = resolveDeclaredPublicAssets(files, declaredPublicAssets, 'Node');
     for (const requiredPath of [
         'index.js',
         'package.json',
-        BACKEND_FEDERATION_MANIFEST_FILE,
-        BACKEND_FEDERATION_REMOTE_ENTRY_FILE
+        ...backendProducer ? [
+            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
     ]);
+    if (shellConsumer && files.some((logicalPath)=>backendFederationPaths.has(logicalPath))) throw new Error('[ultramodern-release-envelope] final Shell Node staging cannot contain a backend federation producer artifact.');
     const uiClientPaths = files.filter((logicalPath)=>{
         const topLevel = logicalPath.split('/')[0];
-        return 'static' === topLevel || 'html' === topLevel || 'public' === topLevel || [
+        return 'static' === topLevel || 'html' === topLevel || 'public' === topLevel && logicalPath !== CRAWLER_POLICY_PATH && logicalPath !== PUBLIC_BUILD_ARTIFACT_PATH && !isPublicMetadataPath(logicalPath) && !declaredPublicAssetPaths.has(logicalPath) || [
             'index.html',
             'mf-manifest.json',
             'mf-stats.json',
@@ -420,6 +562,8 @@ const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity)=
     });
     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));
+    if (uiOnly && (apiBackendPaths.length > 0 || files.some((logicalPath)=>backendFederationPaths.has(logicalPath)))) throw new Error('[ultramodern-release-envelope] final UI-only Node staging contains an undeclared API/backend or backend federation artifact.');
+    if (apiOnly && (uiClientPaths.length > 0 || ssrPaths.some((path)=>'index.js' !== path))) throw new Error('[ultramodern-release-envelope] final API-only Node staging contains an undeclared UI/client or SSR surface.');
     for (const [surface, paths] of [
         [
             'UI/client',
@@ -427,32 +571,45 @@ const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity)=
         ],
         [
             'Node SSR',
-            ssrPaths
+            apiOnly ? [] : 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');
-    if (0 === clientExecutionPaths.length || 0 === ssrExecutionPaths.length) throw new Error('[ultramodern-release-envelope] final Node manifests must reference emitted UI/client and SSR execution modules.');
+    ])if (0 === paths.length && ('Node API/backend' === surface ? backendProducer : !apiOnly)) throw new Error(`[ultramodern-release-envelope] final Node staging has no ${surface} artifacts.`);
+    const clientExecutionPaths = apiOnly ? [] : await manifestReferencedClientModules(outputDirectory, files);
+    const ssrExecutionPaths = apiOnly ? [] : await routeReferencedSsrModules(outputDirectory, files, 'node');
+    if (!apiOnly && (0 === clientExecutionPaths.length || 0 === ssrExecutionPaths.length)) throw new Error('[ultramodern-release-envelope] final Node manifests must reference emitted UI/client and SSR execution modules.');
     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 declaredPublicAssetPaths)runtimeByPath.set(logicalPath, DECLARED_PUBLIC_ASSET_RUNTIME);
+    if (files.includes(CRAWLER_POLICY_PATH)) runtimeByPath.set(CRAWLER_POLICY_PATH, 'crawler-policy');
+    for (const logicalPath of files.filter(isPublicMetadataPath))runtimeByPath.set(logicalPath, 'public-metadata');
+    for (const logicalPath of apiOnly ? [] : 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');
+    if (backendProducer) {
+        runtimeByPath.set(BACKEND_FEDERATION_MANIFEST_FILE, 'module-federation-manifest');
+        runtimeByPath.set(BACKEND_FEDERATION_REMOTE_ENTRY_FILE, 'nodejs');
+    }
+    for (const logicalPath of [
+        ULTRAMODERN_BUILD_ARTIFACT_FILE,
+        PUBLIC_BUILD_ARTIFACT_PATH
+    ])if (files.includes(logicalPath)) runtimeByPath.set(logicalPath, 'release-identity-metadata');
     const identityCarrierMetadata = await writeReleaseIdentityCarrierMetadata(outputDirectory, identity, {
-        apiBackend: apiBackendPaths,
-        backendFederation: [
-            BACKEND_FEDERATION_MANIFEST_FILE,
-            BACKEND_FEDERATION_REMOTE_ENTRY_FILE
-        ],
-        ssr: [
+        ...apiBackendPaths.length > 0 ? {
+            apiBackend: apiBackendPaths
+        } : {},
+        ...backendProducer ? {
+            backendFederation: [
+                BACKEND_FEDERATION_MANIFEST_FILE,
+                BACKEND_FEDERATION_REMOTE_ENTRY_FILE
+            ]
+        } : {},
+        ssr: apiOnly ? [] : [
             ...new Set([
                 ...ssrExecutionPaths,
                 ...ssrPaths.filter((logicalPath)=>'index.js' !== logicalPath)
@@ -471,30 +628,37 @@ const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity)=
             uiClient: [
                 ...uiClientPaths
             ].sort((left, right)=>left.localeCompare(right)),
-            ssr: [
+            ssr: apiOnly ? [] : [
                 ...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
-            }
+            ...backendProducer ? {
+                backendFederation: {
+                    manifest: BACKEND_FEDERATION_MANIFEST_FILE,
+                    container: BACKEND_FEDERATION_REMOTE_ENTRY_FILE
+                }
+            } : {}
         }
     };
 };
-const emitNodeStagedReleaseEnvelope = async ({ distDirectory, outputDirectory })=>{
+const emitNodeStagedReleaseEnvelope = async ({ declaredPublicAssets = [], distDirectory, outputDirectory })=>{
     const source = await verifyBuildOutputReleaseEnvelope(distDirectory, 'node');
     if (!source) return;
-    const { artifacts, surfaces } = await createNodeStagedReleaseArtifactInputs(outputDirectory, source.identity);
+    const shellConsumer = source.kind === SHELL_RELEASE_ENVELOPE_KIND;
+    const { artifacts, surfaces } = await createNodeStagedReleaseArtifactInputs(outputDirectory, source.identity, 0 === source.surfaces.uiClient.length, 0 === source.surfaces.apiBackend.length, declaredPublicAssets, shellConsumer);
     const staged = await createMicroVerticalReleaseEnvelope({
         artifactRoot: outputDirectory,
         target: 'node',
         identity: source.identity,
+        ...source.ui ? {
+            ui: source.ui
+        } : {},
         artifacts,
-        surfaces
+        ...releaseEnvelopeSurfaces(surfaces, shellConsumer)
     });
+    await verifyBuildArtifactCarriers(outputDirectory, staged);
     await writeReleaseEnvelope(outputDirectory, staged);
     return staged;
 };
@@ -505,21 +669,29 @@ const stageCloudflareReleaseEnvelope = async ({ distDirectory, outputDirectory }
     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 createCloudflareStagedReleaseArtifactInputs = async (outputDirectory, identity, apiOnly, uiOnly, declaredPublicAssets, shellConsumer)=>{
+    const backendProducer = !uiOnly && !shellConsumer;
     const files = await collectFiles(outputDirectory);
+    const declaredPublicAssetPaths = resolveDeclaredPublicAssets(files, declaredPublicAssets, 'Cloudflare');
     for (const requiredPath of [
         'server/index.mjs',
         'server/modern-worker-manifest.json',
         'wrangler.json',
         'package.json',
-        'worker/package.json'
+        ...apiOnly ? [] : [
+            '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);
+    const apiBackendPaths = effectBffWorkerArtifacts(files);
+    if (backendProducer && !files.some((logicalPath)=>EFFECT_BFF_WORKER_PATTERN.test(logicalPath))) throw new Error('[ultramodern-release-envelope] final Cloudflare staging has no actual Effect API/BFF worker artifact.');
+    const ssrPaths = files.filter((logicalPath)=>(logicalPath.startsWith('server/') || logicalPath.startsWith('worker/')) && COMPILED_MODULE_PATTERN.test(logicalPath) && !apiBackendPaths.includes(logicalPath));
+    const uiClientPaths = files.filter((logicalPath)=>logicalPath.startsWith('public/') && logicalPath !== CRAWLER_POLICY_PATH && !isPublicMetadataPath(logicalPath) && !declaredPublicAssetPaths.has(logicalPath) && logicalPath !== PUBLIC_BUILD_ARTIFACT_PATH && logicalPath !== backendManifestPath && logicalPath !== backendContainerPath);
+    if (shellConsumer && files.some((logicalPath)=>logicalPath === backendManifestPath || logicalPath === backendContainerPath)) throw new Error('[ultramodern-release-envelope] final Shell Cloudflare staging cannot contain a backend federation producer artifact.');
+    if (uiOnly && (apiBackendPaths.length > 0 || files.some((logicalPath)=>logicalPath === backendManifestPath || logicalPath === backendContainerPath || logicalPath.startsWith('api/') && COMPILED_MODULE_PATTERN.test(logicalPath)))) throw new Error('[ultramodern-release-envelope] final UI-only Cloudflare staging contains an undeclared API/backend or backend federation artifact.');
+    if (apiOnly && (uiClientPaths.length > 0 || ssrPaths.some((path)=>'server/index.mjs' !== path))) throw new Error('[ultramodern-release-envelope] final API-only Cloudflare staging contains an undeclared UI/client or SSR surface.');
     for (const [surface, paths] of [
         [
             'UI/client',
@@ -527,41 +699,53 @@ const createCloudflareStagedReleaseArtifactInputs = async (outputDirectory, iden
         ],
         [
             'Cloudflare SSR',
-            ssrPaths
+            apiOnly ? [] : 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 [
+    ])if (0 === paths.length && ('Cloudflare API/backend' === surface ? backendProducer : !apiOnly)) throw new Error(`[ultramodern-release-envelope] final Cloudflare staging has no ${surface} artifacts.`);
+    for (const logicalPath of backendProducer ? [
         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');
-    if (0 === clientExecutionPaths.length || 0 === ssrExecutionPaths.length) throw new Error('[ultramodern-release-envelope] final Cloudflare manifests must reference emitted UI/client and SSR execution modules.');
+    ] : [])if (!files.includes(logicalPath)) throw new Error(`[ultramodern-release-envelope] final Cloudflare staging is missing ${logicalPath}.`);
+    const clientExecutionPaths = apiOnly ? [] : await manifestReferencedClientModules(outputDirectory, files, 'public/mf-manifest.json');
+    const ssrExecutionPaths = apiOnly ? [] : await routeReferencedSsrModules(outputDirectory, files, 'cloudflare', 'server/route.json');
+    if (!apiOnly && (0 === clientExecutionPaths.length || 0 === ssrExecutionPaths.length)) throw new Error('[ultramodern-release-envelope] final Cloudflare manifests must reference emitted UI/client and SSR execution modules.');
     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');
-    const identityCarrierMetadata = await writeReleaseIdentityCarrierMetadata(outputDirectory, identity, {
-        apiBackend: apiBackendPaths,
-        backendFederation: [
-            backendManifestPath,
+        ...declaredPublicAssetPaths
+    ], DECLARED_PUBLIC_ASSET_RUNTIME);
+    if (files.includes(CRAWLER_POLICY_PATH)) runtimeByPath.set(CRAWLER_POLICY_PATH, 'crawler-policy');
+    add(files.filter(isPublicMetadataPath), 'public-metadata');
+    add(apiOnly ? [] : ssrPaths, 'workerd');
+    add(apiBackendPaths, 'workerd-effect');
+    if (backendProducer) {
+        add([
+            backendManifestPath
+        ], 'module-federation-manifest');
+        add([
             backendContainerPath
-        ],
-        ssr: [
+        ], 'commonjs-module');
+    }
+    add(files.filter((logicalPath)=>logicalPath === ULTRAMODERN_BUILD_ARTIFACT_FILE || logicalPath === PUBLIC_BUILD_ARTIFACT_PATH), 'release-identity-metadata');
+    const identityCarrierMetadata = await writeReleaseIdentityCarrierMetadata(outputDirectory, identity, {
+        ...apiBackendPaths.length > 0 ? {
+            apiBackend: apiBackendPaths
+        } : {},
+        ...backendProducer ? {
+            backendFederation: [
+                backendManifestPath,
+                backendContainerPath
+            ]
+        } : {},
+        ssr: apiOnly ? [] : [
             ...new Set([
                 ...ssrExecutionPaths,
                 ...ssrPaths.filter((logicalPath)=>logicalPath.startsWith('worker/'))
@@ -580,30 +764,37 @@ const createCloudflareStagedReleaseArtifactInputs = async (outputDirectory, iden
             uiClient: [
                 ...uiClientPaths
             ].sort((left, right)=>left.localeCompare(right)),
-            ssr: [
+            ssr: apiOnly ? [] : [
                 ...ssrPaths
             ].sort((left, right)=>left.localeCompare(right)),
             apiBackend: [
                 ...apiBackendPaths
             ].sort((left, right)=>left.localeCompare(right)),
-            backendFederation: {
-                manifest: backendManifestPath,
-                container: backendContainerPath
-            }
+            ...backendProducer ? {
+                backendFederation: {
+                    manifest: backendManifestPath,
+                    container: backendContainerPath
+                }
+            } : {}
         }
     };
 };
-const emitCloudflareStagedReleaseEnvelope = async ({ distDirectory, outputDirectory })=>{
+const emitCloudflareStagedReleaseEnvelope = async ({ declaredPublicAssets = [], distDirectory, outputDirectory })=>{
     const source = await verifyBuildOutputReleaseEnvelope(distDirectory, 'cloudflare');
     if (!source) return;
-    const { artifacts, surfaces } = await createCloudflareStagedReleaseArtifactInputs(outputDirectory, source.identity);
+    const shellConsumer = source.kind === SHELL_RELEASE_ENVELOPE_KIND;
+    const { artifacts, surfaces } = await createCloudflareStagedReleaseArtifactInputs(outputDirectory, source.identity, 0 === source.surfaces.uiClient.length, 0 === source.surfaces.apiBackend.length, declaredPublicAssets, shellConsumer);
     const staged = await createMicroVerticalReleaseEnvelope({
         artifactRoot: outputDirectory,
         target: 'cloudflare',
         identity: source.identity,
+        ...source.ui ? {
+            ui: source.ui
+        } : {},
         artifacts,
-        surfaces
+        ...releaseEnvelopeSurfaces(surfaces, shellConsumer)
     });
+    await verifyBuildArtifactCarriers(outputDirectory, staged);
     await writeReleaseEnvelope(outputDirectory, staged);
     return staged;
 };