@bleedingdev/modern-js-app-tools-extensions 3.9.0-ultramodern.12 → 3.9.0-ultramodern.13

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

@@ -10,6 +10,11 @@ const MICROVERTICAL_RELEASE_IDENTITY_CARRIERS_KIND = 'ultramodern-release-identi
 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 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 isRecord = (value)=>'object' == typeof value && null !== value && !Array.isArray(value);
 const flattenStrings = (value)=>'string' == typeof value ? [
         value
@@ -130,7 +135,7 @@ const readBuildArtifact = async (distDirectory, requirePromotable = true)=>{
     if (!isUltramodernBuildArtifact(artifact)) throw new Error(`[ultramodern-release-envelope] ${ULTRAMODERN_BUILD_ARTIFACT_FILE} is missing or invalid.`);
     if ('workspace' === artifact.deliveryUnit.sourceRevision) {
         if (!requirePromotable) return;
-        throw new Error('[ultramodern-release-envelope] sourceRevision "workspace" cannot produce a promotable full-stack envelope.');
+        throw new Error('[ultramodern-release-envelope] sourceRevision "workspace" cannot produce a promotable envelope.');
     }
     return artifact;
 };
@@ -200,7 +205,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);
@@ -240,12 +245,12 @@ 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)=>{
     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.');
+    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 && !isPublicMetadataPath(logicalPath) || [
             'index.html',
             'mf-manifest.json',
             'mf-stats.json',
@@ -254,16 +259,17 @@ 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) && !isEffectBffWorkerArtifact(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)) : files.filter(isEffectBffWorkerArtifact);
+    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 ('node' === target && 0 === nodeApiEntryPaths.length || 'cloudflare' === target && !files.some((logicalPath)=>EFFECT_BFF_WORKER_PATTERN.test(logicalPath)) || 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){
@@ -273,6 +279,8 @@ 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([
@@ -330,15 +338,14 @@ const pathExists = async (filePath)=>{
     }
 };
 const emitFrameworkMicroVerticalReleaseEnvelope = async ({ apiOnly, distDirectory, requirePromotable = true, 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.');
+    if (!hasBackendManifest && !hasBackendContainer && !apiOnly) return;
+    if (!hasBackendManifest || !hasBackendContainer) throw new Error('[ultramodern-release-envelope] MicroVertical backend federation manifest and container must be emitted together.');
     const buildArtifact = await readBuildArtifact(distDirectory, requirePromotable);
     if (!buildArtifact) return;
     const identity = {
@@ -348,7 +355,7 @@ const emitFrameworkMicroVerticalReleaseEnvelope = async ({ apiOnly, distDirector
         releaseVersion: buildArtifact.deliveryUnit.version
     };
     await readBackendManifest(distDirectory, identity);
-    const { artifacts, surfaces } = await createReleaseArtifactInputs(distDirectory, identity, target);
+    const { artifacts, surfaces } = await createReleaseArtifactInputs(distDirectory, identity, target, apiOnly);
     const envelope = await createMicroVerticalReleaseEnvelope({
         artifactRoot: distDirectory,
         target,
@@ -379,19 +386,16 @@ const readFrameworkMicroVerticalReleaseEnvelope = async ({ artifactRoot, expecte
     });
 };
 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({
@@ -399,7 +403,7 @@ const verifyNodeReleaseEnvelopeStaging = async ({ outputDirectory })=>readFramew
         expectedTarget: 'node',
         required: true
     });
-const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity)=>{
+const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity, apiOnly)=>{
     const files = await collectFiles(outputDirectory);
     for (const requiredPath of [
         'index.js',
@@ -413,7 +417,7 @@ const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity)=
     ]);
     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 && !isPublicMetadataPath(logicalPath) || [
             'index.html',
             'mf-manifest.json',
             'mf-stats.json',
@@ -424,6 +428,7 @@ 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 (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',
@@ -431,22 +436,24 @@ 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 && (!apiOnly || 'Node API/backend' === surface)) 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');
+    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');
@@ -456,7 +463,7 @@ const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity)=
             BACKEND_FEDERATION_MANIFEST_FILE,
             BACKEND_FEDERATION_REMOTE_ENTRY_FILE
         ],
-        ssr: [
+        ssr: apiOnly ? [] : [
             ...new Set([
                 ...ssrExecutionPaths,
                 ...ssrPaths.filter((logicalPath)=>'index.js' !== logicalPath)
@@ -475,7 +482,7 @@ const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity)=
             uiClient: [
                 ...uiClientPaths
             ].sort((left, right)=>left.localeCompare(right)),
-            ssr: [
+            ssr: apiOnly ? [] : [
                 ...ssrPaths
             ].sort((left, right)=>left.localeCompare(right)),
             apiBackend: [
@@ -491,7 +498,7 @@ const createNodeStagedReleaseArtifactInputs = async (outputDirectory, identity)=
 const emitNodeStagedReleaseEnvelope = async ({ distDirectory, outputDirectory })=>{
     const source = await verifyBuildOutputReleaseEnvelope(distDirectory, 'node');
     if (!source) return;
-    const { artifacts, surfaces } = await createNodeStagedReleaseArtifactInputs(outputDirectory, source.identity);
+    const { artifacts, surfaces } = await createNodeStagedReleaseArtifactInputs(outputDirectory, source.identity, 0 === source.surfaces.uiClient.length);
     const staged = await createMicroVerticalReleaseEnvelope({
         artifactRoot: outputDirectory,
         target: 'node',
@@ -509,21 +516,25 @@ 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)=>{
     const files = await collectFiles(outputDirectory);
     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 = files.filter(isEffectBffWorkerArtifact);
+    if (!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) && !isEffectBffWorkerArtifact(logicalPath));
+    const uiClientPaths = files.filter((logicalPath)=>logicalPath.startsWith('public/') && logicalPath !== CRAWLER_POLICY_PATH && !isPublicMetadataPath(logicalPath) && logicalPath !== PUBLIC_BUILD_ARTIFACT_PATH && logicalPath !== backendManifestPath && logicalPath !== backendContainerPath);
+    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',
@@ -531,27 +542,29 @@ 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.`);
+    ])if (0 === paths.length && (!apiOnly || 'Cloudflare API/backend' === surface)) 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');
-    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.');
+    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');
+    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');
     add([
         backendManifestPath
@@ -565,7 +578,7 @@ const createCloudflareStagedReleaseArtifactInputs = async (outputDirectory, iden
             backendManifestPath,
             backendContainerPath
         ],
-        ssr: [
+        ssr: apiOnly ? [] : [
             ...new Set([
                 ...ssrExecutionPaths,
                 ...ssrPaths.filter((logicalPath)=>logicalPath.startsWith('worker/'))
@@ -584,7 +597,7 @@ const createCloudflareStagedReleaseArtifactInputs = async (outputDirectory, iden
             uiClient: [
                 ...uiClientPaths
             ].sort((left, right)=>left.localeCompare(right)),
-            ssr: [
+            ssr: apiOnly ? [] : [
                 ...ssrPaths
             ].sort((left, right)=>left.localeCompare(right)),
             apiBackend: [
@@ -600,7 +613,7 @@ const createCloudflareStagedReleaseArtifactInputs = async (outputDirectory, iden
 const emitCloudflareStagedReleaseEnvelope = async ({ distDirectory, outputDirectory })=>{
     const source = await verifyBuildOutputReleaseEnvelope(distDirectory, 'cloudflare');
     if (!source) return;
-    const { artifacts, surfaces } = await createCloudflareStagedReleaseArtifactInputs(outputDirectory, source.identity);
+    const { artifacts, surfaces } = await createCloudflareStagedReleaseArtifactInputs(outputDirectory, source.identity, 0 === source.surfaces.uiClient.length);
     const staged = await createMicroVerticalReleaseEnvelope({
         artifactRoot: outputDirectory,
         target: 'cloudflare',

package/dist/esm-node/release-envelope/index.mjs

@@ -185,7 +185,7 @@ const assertUniqueSortedArtifacts = (artifacts, location)=>{
     if (paths.some((logicalPath, index)=>logicalPath !== sorted[index])) throw new Error(`${location} must be sorted by logicalPath.`);
 };
 const assertSurfacePaths = (value, location)=>{
-    if (!Array.isArray(value) || 0 === value.length) throw new Error(`${location} must contain at least one artifact path.`);
+    if (!Array.isArray(value)) throw new Error(`${location} must be an array of artifact paths.`);
     const paths = value.map((item, index)=>assertNormalizedLogicalPath(item, `${location}[${index}]`));
     const sorted = [
         ...paths
@@ -207,10 +207,16 @@ const assertSurfaces = (value)=>{
         'manifest',
         'container'
     ], 'surfaces.backendFederation');
+    const uiClient = assertSurfacePaths(surfaces.uiClient, 'surfaces.uiClient');
+    const ssr = assertSurfacePaths(surfaces.ssr, 'surfaces.ssr');
+    const apiBackend = assertSurfacePaths(surfaces.apiBackend, 'surfaces.apiBackend');
+    if (uiClient.length > 0 && 0 === ssr.length) throw new Error('surfaces.ssr must contain at least one artifact path when UI/client is declared.');
+    if (ssr.length > 0 && 0 === uiClient.length) throw new Error('surfaces.uiClient must contain at least one artifact path when SSR is declared.');
+    if (0 === apiBackend.length) throw new Error('surfaces.apiBackend must contain at least one artifact path.');
     return {
-        uiClient: assertSurfacePaths(surfaces.uiClient, 'surfaces.uiClient'),
-        ssr: assertSurfacePaths(surfaces.ssr, 'surfaces.ssr'),
-        apiBackend: assertSurfacePaths(surfaces.apiBackend, 'surfaces.apiBackend'),
+        uiClient,
+        ssr,
+        apiBackend,
         backendFederation: {
             manifest: assertNormalizedLogicalPath(backendFederation.manifest, 'surfaces.backendFederation.manifest'),
             container: assertNormalizedLogicalPath(backendFederation.container, 'surfaces.backendFederation.container')

package/dist/types/backend-federation-build/codegen.d.ts

@@ -53,6 +53,36 @@ export declare const createBackendManifest: (workspaceRoot: string, distDirector
     }[];
     shared: never[];
     backendFederation: {
+        role: string;
+        appId: string;
+        name: string;
+        runtimeFramework: string;
+        strictEffectApproach: boolean;
+        contractVersion: string;
+        nodeAdapterVersion: string;
+        remoteType: string;
+        expose: string;
+        manifestUrl: string;
+        containerEntry: string;
+        source: {
+            module: string;
+        };
+        rpcPath: string | undefined;
+        rpcSerialization: string;
+        deliveryUnit?: import("@modern-js/backend-federation-contracts").DeliveryUnitContractBlock | undefined;
+        versionBoundary: {
+            invariant: string;
+            packageName: string | undefined;
+            version: string | undefined;
+            buildVersion: string | undefined;
+            uiManifestUrl?: string | undefined;
+            deliveryUnit?: {
+                unitId: string;
+                buildMarker: string;
+                sourceRevision: string;
+            } | undefined;
+        };
+    } | {
         role: string;
         appId: string;
         name: string;

package/dist/types/backend-federation-build/config.d.ts

@@ -1,13 +1,23 @@
 import { type DeliveryUnitContractBlock, type UltramodernBuildArtifact } from '@modern-js/backend-federation-contracts';
-export declare const COMPACT_CONFIG_PATH = ".modernjs/ultramodern.json";
-export type CompactApp = {
+export declare const REFERENCE_TOPOLOGY_PATH = "topology/reference-topology.json";
+export declare const DEVELOPMENT_OVERLAY_PATH = "topology/local-overlays/development.json";
+export type TopologyApp = {
     id?: unknown;
+    domain?: unknown;
     kind?: unknown;
     path?: unknown;
     package?: unknown;
-    port?: unknown;
+    portEnv?: unknown;
+    cloudflare?: {
+        publicUrlEnv?: unknown;
+    };
     api?: {
-        prefix?: unknown;
+        bff?: {
+            prefix?: unknown;
+        };
+        protocol?: unknown;
+        rpcPath?: unknown;
+        rpcSerialization?: unknown;
         stem?: unknown;
     };
     moduleFederation?: {
@@ -37,19 +47,23 @@ export type CompactApp = {
         packageName?: unknown;
         version?: unknown;
     };
-    serverExecution?: {
+};
+export type DevelopmentOverlay = {
+    ports?: Record<string, unknown>;
+    manifests?: Record<string, unknown>;
+    serverExecution?: Record<string, {
         node?: {
             remoteName?: unknown;
             manifestUrl?: unknown;
             containerEntry?: unknown;
             remoteType?: unknown;
         };
-    };
+    }>;
 };
-export type CompactConfig = {
-    topology?: {
-        apps?: CompactApp[];
-    };
+export type ReferenceTopology = {
+    shell?: TopologyApp;
+    shells?: TopologyApp[];
+    verticals?: TopologyApp[];
 };
 export type BackendFederationApp = {
     id: string;
@@ -62,13 +76,15 @@ export type BackendFederationApp = {
     deliveryUnit?: DeliveryUnitContractBlock;
     port: number;
     apiPrefix: string;
+    apiProtocol: 'rest' | 'rpc';
+    rpcPath?: string;
     apiStem: string;
     backendName: string;
     manifestUrl: string;
     containerEntry: string;
     remoteType: string;
     uiManifestUrl?: string;
-    compactDeliveryUnit?: {
+    topologyDeliveryUnit?: {
         unitId?: string;
         buildMarker?: string;
         sourceRevision?: string;
@@ -98,5 +114,8 @@ export declare const createStampedDeliveryUnit: (input: {
     version?: string;
     sourceRevision: string;
 }) => DeliveryUnitContractBlock | undefined;
-export declare const createAppFromCompactMetadata: (workspaceRoot: string, appDirectory: string, compactApp: CompactApp) => BackendFederationApp | undefined;
-export declare const findBackendFederationApp: (workspaceRoot: string, appDirectory: string) => Promise<BackendFederationApp | undefined>;
+export declare const createAppFromTopology: (workspaceRoot: string, appDirectory: string, topologyApp: TopologyApp, overlay: DevelopmentOverlay, packageManifest: {
+    name?: unknown;
+    version?: unknown;
+}) => BackendFederationApp | undefined;
+export declare const findBackendFederationApp: (workspaceRoot: string, appDirectory: string) => Promise<BackendFederationApp>;

package/dist/types/cloudflare/delivery-unit.d.ts

@@ -11,7 +11,7 @@ export type DeliveryUnitStamp = DeliveryUnitIdentity & {
 };
 /**
  * Resolve the delivery-unit record declared for this app by the workspace
- * compact config (`.modernjs/ultramodern.json`). This is the topology source
+ * reference topology. This is the topology source
  * of truth the Cloudflare worker snapshot is verified against.
  */
 export declare const resolveTopologyDeliveryUnit: (appDirectory: string) => Promise<DeliveryUnitStamp | undefined>;

package/dist/types/cloudflare-builder.d.ts

@@ -7,6 +7,7 @@ export interface CloudflareBuilderNormalizedConfig {
     };
 }
 export interface CloudflareBuilderAppContext {
+    apiOnly?: boolean;
     apiDirectory: string;
     appDirectory: string;
 }

package/dist/types/cloudflare-output-contract.d.ts

@@ -10,6 +10,6 @@ export declare const CLOUDFLARE_RUNTIME_TYPE = "cloudflare-module-worker";
 export declare const CLOUDFLARE_OUTPUT_PACKAGE_TYPE = "module";
 export declare const CLOUDFLARE_WORKER_PACKAGE_TYPE = "commonjs";
 export declare const CLOUDFLARE_WORKER_BUNDLE_FORMAT = "commonjs";
-export declare const CLOUDFLARE_WORKER_NODE_BUILTINS: readonly ['assert', 'assert/strict', 'async_hooks', 'buffer', 'child_process', 'crypto', 'dgram', 'dns', 'domain', 'events', 'fs', 'fs/promises', 'http', 'http2', 'inspector', 'module', 'net', 'os', 'path', 'process', 'readline', 'readline/promises', 'repl', 'sqlite', 'stream', 'stream/consumers', 'stream/promises', 'stream/web', 'string_decoder', 'timers', 'timers/promises', 'tls', 'trace_events', 'tty', 'url', 'util', 'util/types', 'v8', 'vm', 'wasi', 'worker_threads', 'zlib'];
+export declare const CLOUDFLARE_WORKER_NODE_BUILTINS: readonly ['assert', 'assert/strict', 'async_hooks', 'buffer', 'child_process', 'crypto', 'dgram', 'dns', 'domain', 'events', 'fs', 'fs/promises', 'http', 'http2', 'https', 'inspector', 'module', 'net', 'os', 'path', 'process', 'readline', 'readline/promises', 'repl', 'sqlite', 'stream', 'stream/consumers', 'stream/promises', 'stream/web', 'string_decoder', 'timers', 'timers/promises', 'tls', 'trace_events', 'tty', 'url', 'util', 'util/types', 'v8', 'vm', 'wasi', 'worker_threads', 'zlib'];
 export declare const CLOUDFLARE_WORKER_PLATFORM_MODULES: readonly ['cloudflare:sockets'];
 export declare const CLOUDFLARE_REQUIRED_COMPATIBILITY_FLAGS: readonly ['nodejs_compat', 'global_fetch_strictly_public'];

package/package.json

@@ -11,7 +11,7 @@
     "directory": "packages/solutions/app-tools-extensions"
   },
   "license": "MIT",
-  "version": "3.9.0-ultramodern.12",
+  "version": "3.9.0-ultramodern.13",
   "files": [
     "dist",
     "src"
@@ -142,38 +142,38 @@
     "node": ">=26.7.0"
   },
   "dependencies": {
-    "@babel/parser": "^8.0.4",
-    "@babel/traverse": "^8.0.4",
+    "@babel/parser": "^8.0.6",
+    "@babel/traverse": "^8.0.6",
     "@loadable/component": "5.16.7",
-    "@modern-js/backend-federation-contracts": "npm:@bleedingdev/modern-js-backend-federation-contracts@3.9.0-ultramodern.12",
-    "@modern-js/builder": "npm:@bleedingdev/modern-js-builder@3.9.0-ultramodern.12",
-    "@modern-js/prod-server": "npm:@bleedingdev/modern-js-prod-server@3.9.0-ultramodern.12",
-    "@modern-js/runtime-renderer-extensions": "npm:@bleedingdev/modern-js-runtime-renderer-extensions@3.9.0-ultramodern.12",
-    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.9.0-ultramodern.12",
-    "@modern-js/server-runtime-extensions": "npm:@bleedingdev/modern-js-server-runtime-extensions@3.9.0-ultramodern.12",
-    "@modern-js/surface-resolution": "npm:@bleedingdev/modern-js-surface-resolution@3.9.0-ultramodern.12",
-    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.9.0-ultramodern.12",
-    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.9.0-ultramodern.12",
+    "@modern-js/backend-federation-contracts": "npm:@bleedingdev/modern-js-backend-federation-contracts@3.9.0-ultramodern.13",
+    "@modern-js/builder": "npm:@bleedingdev/modern-js-builder@3.9.0-ultramodern.13",
+    "@modern-js/prod-server": "npm:@bleedingdev/modern-js-prod-server@3.9.0-ultramodern.13",
+    "@modern-js/runtime-renderer-extensions": "npm:@bleedingdev/modern-js-runtime-renderer-extensions@3.9.0-ultramodern.13",
+    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.9.0-ultramodern.13",
+    "@modern-js/server-runtime-extensions": "npm:@bleedingdev/modern-js-server-runtime-extensions@3.9.0-ultramodern.13",
+    "@modern-js/surface-resolution": "npm:@bleedingdev/modern-js-surface-resolution@3.9.0-ultramodern.13",
+    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.9.0-ultramodern.13",
+    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.9.0-ultramodern.13",
     "@swc/helpers": "^0.5.23",
     "compression-webpack-plugin": "^12.0.0",
     "esbuild": "^0.28.2",
     "std-env": "4.2.0"
   },
   "peerDependencies": {
-    "@rsbuild/core": "2.2.3"
+    "@rsbuild/core": "2.2.9"
   },
   "devDependencies": {
-    "@modern-js/plugin": "npm:@bleedingdev/modern-js-plugin@3.9.0-ultramodern.12",
-    "@modern-js/plugin-bff-extensions": "npm:@bleedingdev/modern-js-plugin-bff-extensions@3.9.0-ultramodern.12",
-    "@module-federation/runtime-tools": "2.9.0",
-    "@rsbuild/core": "2.2.3",
-    "@rslib/core": "1.0.0",
+    "@modern-js/plugin": "npm:@bleedingdev/modern-js-plugin@3.9.0-ultramodern.13",
+    "@modern-js/plugin-bff-extensions": "npm:@bleedingdev/modern-js-plugin-bff-extensions@3.9.0-ultramodern.13",
+    "@module-federation/runtime-tools": "npm:@bleedingdev/mf-runtime-tools@2.9.1",
+    "@rsbuild/core": "2.2.9",
+    "@rslib/core": "1.0.2",
     "@scripts/rstest-config": "2.66.0",
     "@types/babel__traverse": "7.28.0",
-    "@types/node": "^26.4.1",
+    "@types/node": "^26.6.2",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "core-js": "^3.50.0",
-    "effect": "4.0.0-rc.112",
+    "effect": "npm:@bleedingdev/effect@4.0.0-rc.117",
     "ndepe": "^0.1.13"
   },
   "sideEffects": false,

package/src/backend-federation-build/codegen.ts

@@ -204,8 +204,12 @@ export const createBackendManifest = (
       source: {
         module: sourceModule,
       },
-      readinessPath: `${app.apiPrefix}/${app.apiStem}/readiness`,
-      openapiPath: `${app.apiPrefix}/openapi.json`,
+      ...(app.apiProtocol === 'rpc'
+        ? { rpcPath: app.rpcPath, rpcSerialization: 'json' }
+        : {
+            readinessPath: `${app.apiPrefix}/${app.apiStem}/readiness`,
+            openapiPath: `${app.apiPrefix}/openapi.json`,
+          }),
       ...(app.deliveryUnit ? { deliveryUnit: app.deliveryUnit } : {}),
       versionBoundary: {
         invariant: 'web-and-api-same-build',