@bleedingdev/modern-js-app-tools-extensions 3.9.0-ultramodern.2 → 3.9.0-ultramodern.20

package/src/release-envelope/framework-output.ts

@@ -7,7 +7,7 @@ import {
   isUltramodernBuildArtifact,
   ULTRAMODERN_BUILD_ARTIFACT_FILE,
   type UltramodernBuildArtifact,
-} from '@modern-js/utils/universal';
+} from '@modern-js/backend-federation-contracts';
 import {
   canonicalSerializeMicroVerticalReleaseEnvelope,
   createMicroVerticalReleaseEnvelope,
@@ -33,6 +33,38 @@ 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: string) =>
+  EFFECT_BFF_WORKER_PATTERN.test(logicalPath) ||
+  EFFECT_BFF_WORKER_SUPPORT_PATTERN.test(logicalPath);
+const CRAWLER_POLICY_PATH = 'public/robots.txt';
+const isPublicMetadataPath = (logicalPath: string) =>
+  logicalPath === 'public/_headers' ||
+  /^public\/\.well-known\/[^/]+\.json$/u.test(logicalPath);
+const PUBLIC_BUILD_ARTIFACT_PATH = `public/${ULTRAMODERN_BUILD_ARTIFACT_FILE}`;
+// Files an app declared through `deploy.<target>.publicAssets`. The deploy
+// output stages them from app-root sources; they are served data, not a
+// UI/client surface, so API-only units may carry them.
+const DECLARED_PUBLIC_ASSET_RUNTIME = 'public-asset';
+
+const resolveDeclaredPublicAssets = (
+  files: readonly string[],
+  declaredPublicAssets: readonly string[],
+  target: 'Node' | 'Cloudflare',
+) => {
+  const staged = new Set(files);
+  const declared = new Set<string>();
+  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: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -57,6 +89,111 @@ const collectNestedStrings = (value: unknown, key: string): string[] => {
   ]);
 };
 
+// Empty native MF producers emit no remote entry or exposed execution assets.
+// Only their routeAssets declarations may supply the missing browser evidence.
+const emptyProducerRouteModules = async (
+  distDirectory: string,
+  files: string[],
+  manifest: unknown,
+  manifestLogicalPath: string,
+): Promise<string[]> => {
+  if (
+    !isRecord(manifest) ||
+    !Array.isArray(manifest.exposes) ||
+    manifest.exposes.length !== 0 ||
+    !Array.isArray(manifest.remotes) ||
+    manifest.remotes.length !== 0 ||
+    !isRecord(manifest.metaData) ||
+    !isRecord(manifest.metaData.remoteEntry) ||
+    manifest.metaData.remoteEntry.name !== '' ||
+    manifest.metaData.remoteEntry.path !== '' ||
+    manifest.metaData.remoteEntry.type !== 'global'
+  ) {
+    return [];
+  }
+  const publicPath = manifest.metaData.publicPath;
+  // Reject encoded/ambiguous paths before URL parsing can normalize traversal.
+  const safeReference = (value: unknown): value is string =>
+    typeof value === 'string' &&
+    value.length > 0 &&
+    !/[\\\\%?#\s]/u.test(value) &&
+    !value.split('/').some(segment => segment === '.' || segment === '..');
+  if (!safeReference(publicPath)) {
+    return [];
+  }
+  const absoluteBase = /^https?:\/\//u.test(publicPath);
+  if (
+    publicPath !== 'auto' &&
+    (!publicPath.endsWith('/') ||
+      (!absoluteBase &&
+        (!publicPath.startsWith('/') || publicPath.startsWith('//'))))
+  ) {
+    return [];
+  }
+  if (absoluteBase) {
+    const base = new URL(publicPath);
+    if (base.username || base.password || base.href !== publicPath) {
+      return [];
+    }
+  }
+  const directory = path.posix.dirname(manifestLogicalPath);
+  const routesManifest = await readJson(
+    path.join(distDirectory, directory, 'routes-manifest.json'),
+  );
+  if (!isRecord(routesManifest) || !isRecord(routesManifest.routeAssets)) {
+    return [];
+  }
+  const modules = new Set<string>();
+  for (const route of Object.values(routesManifest.routeAssets)) {
+    if (!isRecord(route) || !Array.isArray(route.assets)) {
+      return [];
+    }
+    for (const reference of route.assets) {
+      if (!safeReference(reference) || reference.startsWith('//')) {
+        return [];
+      }
+      let relative = reference;
+      if (/^https?:\/\//u.test(reference)) {
+        if (!absoluteBase || !reference.startsWith(publicPath)) {
+          return [];
+        }
+        relative = reference.slice(publicPath.length);
+      } else if (reference.startsWith('/')) {
+        const prefix =
+          publicPath === 'auto'
+            ? '/'
+            : absoluteBase
+              ? new URL(publicPath).pathname
+              : publicPath;
+        if (!reference.startsWith(prefix)) {
+          return [];
+        }
+        relative = reference.slice(prefix.length);
+      }
+      // Never allow API, SSR, backend containers, or unrelated on-disk modules.
+      if (
+        !/^(?:static|html|public)\/[^:]+$/u.test(relative) ||
+        relative.includes('//')
+      ) {
+        return [];
+      }
+      const logicalPath = path.posix.join(directory, relative);
+      if (!files.includes(logicalPath)) {
+        return [];
+      }
+      // A browser-named symlink to server/private bytes is not browser evidence.
+      const assetStat = await fs.lstat(path.join(distDirectory, logicalPath));
+      if (!assetStat.isFile()) {
+        return [];
+      }
+      if (COMPILED_MODULE_PATTERN.test(logicalPath)) {
+        modules.add(logicalPath);
+      }
+    }
+  }
+  return [...modules];
+};
+
 const manifestReferencedClientModules = async (
   distDirectory: string,
   files: string[],
@@ -77,7 +214,7 @@ const manifestReferencedClientModules = async (
       .map(value => value.replace(/^https?:\/\/[^/]+/u, ''))
       .map(value => value.replace(/^\/+/u, '')),
   );
-  return files.filter(
+  const modules = files.filter(
     logicalPath =>
       COMPILED_MODULE_PATTERN.test(logicalPath) &&
       [...normalizedReferences].some(
@@ -87,6 +224,14 @@ const manifestReferencedClientModules = async (
           logicalPath.endsWith(`/${reference}`),
       ),
   );
+  return modules.length > 0
+    ? modules
+    : emptyProducerRouteModules(
+        distDirectory,
+        files,
+        manifest,
+        manifestLogicalPath,
+      );
 };
 
 const routeReferencedSsrModules = async (
@@ -209,7 +354,8 @@ const writeReleaseEnvelope = async (
 
 const readBuildArtifact = async (
   distDirectory: string,
-): Promise<UltramodernBuildArtifact> => {
+  requirePromotable = true,
+): Promise<UltramodernBuildArtifact | undefined> => {
   const artifactPath = path.join(
     distDirectory,
     ULTRAMODERN_BUILD_ARTIFACT_FILE,
@@ -221,8 +367,17 @@ const readBuildArtifact = async (
     );
   }
   if (artifact.deliveryUnit.sourceRevision === 'workspace') {
+    // `resolveUltramodernSourceRevision` deliberately labels a dirty or
+    // non-Git checkout `workspace` so development stays usable; only a
+    // promotion may not carry that identity. A plain `modern build` is the
+    // development path, so it skips the envelope instead of failing the
+    // build. The deploy path still asks for a promotable artifact, which is
+    // where the release gate belongs.
+    if (!requirePromotable) {
+      return undefined;
+    }
     throw new Error(
-      '[ultramodern-release-envelope] sourceRevision "workspace" cannot produce a promotable full-stack envelope.',
+      '[ultramodern-release-envelope] sourceRevision "workspace" cannot produce a promotable envelope.',
     );
   }
   return artifact;
@@ -393,7 +548,11 @@ const writeReleaseIdentityCarrierMetadata = async (
     ReleaseIdentityCarrierSurface,
     string[],
   ][]) {
-    if (logicalPaths.length === 0) {
+    if (
+      logicalPaths.length === 0 &&
+      surface !== 'ssr' &&
+      surface !== 'uiClient'
+    ) {
       throw new Error(
         `[ultramodern-release-envelope] ${surface} has no declared release-identity carrier artifact.`,
       );
@@ -468,12 +627,10 @@ const createReleaseArtifactInputs = async (
   distDirectory: string,
   identity: MicroVerticalReleaseIdentity,
   target: MicroVerticalReleaseTarget,
+  apiOnly: boolean,
 ) => {
   const files = await collectFiles(distDirectory);
-  if (
-    target === 'node' &&
-    files.some(logicalPath => EFFECT_BFF_WORKER_PATTERN.test(logicalPath))
-  ) {
+  if (target === 'node' && 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.',
     );
@@ -483,7 +640,9 @@ const createReleaseArtifactInputs = async (
     return (
       topLevel === 'static' ||
       topLevel === 'html' ||
-      topLevel === 'public' ||
+      (topLevel === 'public' &&
+        logicalPath !== CRAWLER_POLICY_PATH &&
+        !isPublicMetadataPath(logicalPath)) ||
       [
         'index.html',
         'mf-manifest.json',
@@ -505,7 +664,7 @@ const createReleaseArtifactInputs = async (
           logicalPath =>
             logicalPath.startsWith('worker/') &&
             COMPILED_MODULE_PATTERN.test(logicalPath) &&
-            !EFFECT_BFF_WORKER_PATTERN.test(logicalPath),
+            !isEffectBffWorkerArtifact(logicalPath),
         );
   const nodeApiEntryPaths = files.filter(
     logicalPath =>
@@ -520,44 +679,48 @@ const createReleaseArtifactInputs = async (
               logicalPath.startsWith('shared/')) &&
             COMPILED_MODULE_PATTERN.test(logicalPath),
         )
-      : files.filter(logicalPath =>
-          EFFECT_BFF_WORKER_PATTERN.test(logicalPath),
-        );
+      : files.filter(isEffectBffWorkerArtifact);
 
-  if (uiClientPaths.length === 0) {
+  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 && uiClientPaths.length === 0) {
     throw new Error(
       `[ultramodern-release-envelope] ${target} full-stack MicroVertical has no UI/client artifacts.`,
     );
   }
-  if (ssrPaths.length === 0) {
+  if (!apiOnly && ssrPaths.length === 0) {
     throw new Error(
       `[ultramodern-release-envelope] ${target} full-stack MicroVertical has no ${target === 'node' ? 'Node' : 'workerd'} SSR artifacts.`,
     );
   }
   if (
     (target === 'node' && nodeApiEntryPaths.length === 0) ||
+    (target === 'cloudflare' &&
+      !files.some(logicalPath =>
+        EFFECT_BFF_WORKER_PATTERN.test(logicalPath),
+      )) ||
     apiBackendPaths.length === 0
   ) {
     throw new Error(
-      `[ultramodern-release-envelope] ${target} full-stack MicroVertical has no actual ${target === 'node' ? 'compiled Node Effect API artifact' : 'Effect API/BFF worker artifact'}.`,
+      `[ultramodern-release-envelope] ${target} MicroVertical has no actual ${target === 'node' ? 'compiled Node Effect API artifact' : 'Effect API/BFF worker artifact'}.`,
     );
   }
 
-  const clientExecutionPaths = await manifestReferencedClientModules(
-    distDirectory,
-    files,
-  );
-  if (clientExecutionPaths.length === 0) {
+  const clientExecutionPaths = apiOnly
+    ? []
+    : await manifestReferencedClientModules(distDirectory, files);
+  if (!apiOnly && clientExecutionPaths.length === 0) {
     throw new Error(
       '[ultramodern-release-envelope] UI/client manifest references no compiled execution module.',
     );
   }
-  const ssrExecutionPaths = await routeReferencedSsrModules(
-    distDirectory,
-    files,
-    target,
-  );
-  if (ssrExecutionPaths.length === 0) {
+  const ssrExecutionPaths = apiOnly
+    ? []
+    : await routeReferencedSsrModules(distDirectory, files, target);
+  if (!apiOnly && ssrExecutionPaths.length === 0) {
     throw new Error(
       `[ultramodern-release-envelope] route manifest references no emitted ${target === 'node' ? 'Node' : 'Cloudflare'} SSR execution module.`,
     );
@@ -576,6 +739,11 @@ const createReleaseArtifactInputs = async (
     }
   };
   add(uiClientPaths, 'browser');
+  add(
+    files.filter(logicalPath => logicalPath === CRAWLER_POLICY_PATH),
+    'crawler-policy',
+  );
+  add(files.filter(isPublicMetadataPath), 'public-metadata');
   add(ssrPaths, target === 'node' ? 'nodejs' : 'workerd');
   add(apiBackendPaths, target === 'node' ? 'nodejs' : 'workerd-effect');
   add([BACKEND_FEDERATION_MANIFEST_FILE], 'module-federation-manifest');
@@ -635,15 +803,14 @@ const pathExists = async (filePath: string) => {
 export const emitFrameworkMicroVerticalReleaseEnvelope = async ({
   apiOnly,
   distDirectory,
+  requirePromotable = true,
   target,
 }: {
   apiOnly: boolean;
   distDirectory: string;
+  requirePromotable?: boolean;
   target: MicroVerticalReleaseTarget;
 }): Promise<MicroVerticalReleaseEnvelope | undefined> => {
-  if (apiOnly) {
-    return undefined;
-  }
   const backendManifestPath = path.join(
     distDirectory,
     BACKEND_FEDERATION_MANIFEST_FILE,
@@ -656,16 +823,22 @@ export const emitFrameworkMicroVerticalReleaseEnvelope = async ({
     pathExists(backendManifestPath),
     pathExists(backendContainerPath),
   ]);
-  if (!hasBackendManifest && !hasBackendContainer) {
+  if (!hasBackendManifest && !hasBackendContainer && !apiOnly) {
     return undefined;
   }
   if (!hasBackendManifest || !hasBackendContainer) {
     throw new Error(
-      '[ultramodern-release-envelope] full-stack MicroVertical backend federation manifest and container must be emitted together.',
+      '[ultramodern-release-envelope] MicroVertical backend federation manifest and container must be emitted together.',
     );
   }
 
-  const buildArtifact = await readBuildArtifact(distDirectory);
+  const buildArtifact = await readBuildArtifact(
+    distDirectory,
+    requirePromotable,
+  );
+  if (!buildArtifact) {
+    return undefined;
+  }
   const identity = {
     unitId: buildArtifact.deliveryUnit.unitId,
     buildMarker: buildArtifact.deliveryUnit.buildMarker,
@@ -677,6 +850,7 @@ export const emitFrameworkMicroVerticalReleaseEnvelope = async ({
     distDirectory,
     identity,
     target,
+    apiOnly,
   );
   const envelope = await createMicroVerticalReleaseEnvelope({
     artifactRoot: distDirectory,
@@ -723,21 +897,14 @@ export const verifyBuildOutputReleaseEnvelope = async (
   distDirectory: string,
   expectedTarget?: MicroVerticalReleaseTarget,
 ) => {
-  const [hasEnvelope, hasBuildArtifact, hasBackendManifest, hasBackendEntry] =
-    await Promise.all([
-      pathExists(path.join(distDirectory, MICROVERTICAL_RELEASE_ENVELOPE_PATH)),
-      pathExists(path.join(distDirectory, ULTRAMODERN_BUILD_ARTIFACT_FILE)),
-      pathExists(path.join(distDirectory, BACKEND_FEDERATION_MANIFEST_FILE)),
-      pathExists(
-        path.join(distDirectory, BACKEND_FEDERATION_REMOTE_ENTRY_FILE),
-      ),
-    ]);
-  const isFullStackMicroVertical =
-    hasBuildArtifact && (hasBackendManifest || hasBackendEntry);
+  const [hasEnvelope, hasBuildArtifact] = await Promise.all([
+    pathExists(path.join(distDirectory, MICROVERTICAL_RELEASE_ENVELOPE_PATH)),
+    pathExists(path.join(distDirectory, ULTRAMODERN_BUILD_ARTIFACT_FILE)),
+  ]);
   return readFrameworkMicroVerticalReleaseEnvelope({
     artifactRoot: distDirectory,
     ...(expectedTarget ? { expectedTarget } : {}),
-    required: hasEnvelope || isFullStackMicroVertical,
+    required: hasEnvelope || hasBuildArtifact,
   });
 };
 
@@ -756,8 +923,15 @@ export const verifyNodeReleaseEnvelopeStaging = async ({
 const createNodeStagedReleaseArtifactInputs = async (
   outputDirectory: string,
   identity: MicroVerticalReleaseIdentity,
+  apiOnly: boolean,
+  declaredPublicAssets: readonly string[],
 ) => {
   const files = await collectFiles(outputDirectory);
+  const declaredPublicAssetPaths = resolveDeclaredPublicAssets(
+    files,
+    declaredPublicAssets,
+    'Node',
+  );
   for (const requiredPath of [
     'index.js',
     'package.json',
@@ -780,7 +954,10 @@ const createNodeStagedReleaseArtifactInputs = async (
     return (
       topLevel === 'static' ||
       topLevel === 'html' ||
-      topLevel === 'public' ||
+      (topLevel === 'public' &&
+        logicalPath !== CRAWLER_POLICY_PATH &&
+        !isPublicMetadataPath(logicalPath) &&
+        !declaredPublicAssetPaths.has(logicalPath)) ||
       [
         'index.html',
         'mf-manifest.json',
@@ -802,27 +979,35 @@ const createNodeStagedReleaseArtifactInputs = async (
       (logicalPath.startsWith('api/') || logicalPath.startsWith('shared/')) &&
       COMPILED_MODULE_PATTERN.test(logicalPath),
   );
+  if (
+    apiOnly &&
+    (uiClientPaths.length > 0 || ssrPaths.some(path => path !== 'index.js'))
+  ) {
+    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', uiClientPaths],
-    ['Node SSR', ssrPaths],
+    ['Node SSR', apiOnly ? [] : ssrPaths],
     ['Node API/backend', apiBackendPaths],
   ] as const) {
-    if (paths.length === 0) {
+    if (paths.length === 0 && (!apiOnly || surface === 'Node API/backend')) {
       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 (clientExecutionPaths.length === 0 || ssrExecutionPaths.length === 0) {
+  const clientExecutionPaths = apiOnly
+    ? []
+    : await manifestReferencedClientModules(outputDirectory, files);
+  const ssrExecutionPaths = apiOnly
+    ? []
+    : await routeReferencedSsrModules(outputDirectory, files, 'node');
+  if (
+    !apiOnly &&
+    (clientExecutionPaths.length === 0 || ssrExecutionPaths.length === 0)
+  ) {
     throw new Error(
       '[ultramodern-release-envelope] final Node manifests must reference emitted UI/client and SSR execution modules.',
     );
@@ -836,7 +1021,16 @@ const createNodeStagedReleaseArtifactInputs = async (
   for (const logicalPath of uiClientPaths) {
     runtimeByPath.set(logicalPath, 'browser');
   }
-  for (const logicalPath of ssrPaths) {
+  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) {
@@ -857,12 +1051,14 @@ const createNodeStagedReleaseArtifactInputs = async (
         BACKEND_FEDERATION_MANIFEST_FILE,
         BACKEND_FEDERATION_REMOTE_ENTRY_FILE,
       ],
-      ssr: [
-        ...new Set([
-          ...ssrExecutionPaths,
-          ...ssrPaths.filter(logicalPath => logicalPath !== 'index.js'),
-        ]),
-      ],
+      ssr: apiOnly
+        ? []
+        : [
+            ...new Set([
+              ...ssrExecutionPaths,
+              ...ssrPaths.filter(logicalPath => logicalPath !== 'index.js'),
+            ]),
+          ],
       uiClient: uiClientPaths.filter(logicalPath =>
         COMPILED_MODULE_PATTERN.test(logicalPath),
       ),
@@ -879,7 +1075,9 @@ const createNodeStagedReleaseArtifactInputs = async (
       uiClient: [...uiClientPaths].sort((left, right) =>
         left.localeCompare(right),
       ),
-      ssr: [...ssrPaths].sort((left, right) => left.localeCompare(right)),
+      ssr: apiOnly
+        ? []
+        : [...ssrPaths].sort((left, right) => left.localeCompare(right)),
       apiBackend: [...apiBackendPaths].sort((left, right) =>
         left.localeCompare(right),
       ),
@@ -892,9 +1090,12 @@ const createNodeStagedReleaseArtifactInputs = async (
 };
 
 export const emitNodeStagedReleaseEnvelope = async ({
+  declaredPublicAssets = [],
   distDirectory,
   outputDirectory,
 }: {
+  /** Staged `deploy.node.publicAssets` files, relative to `outputDirectory`. */
+  declaredPublicAssets?: readonly string[];
   distDirectory: string;
   outputDirectory: string;
 }) => {
@@ -905,6 +1106,8 @@ export const emitNodeStagedReleaseEnvelope = async ({
   const { artifacts, surfaces } = await createNodeStagedReleaseArtifactInputs(
     outputDirectory,
     source.identity,
+    source.surfaces.uiClient.length === 0,
+    declaredPublicAssets,
   );
   const staged = await createMicroVerticalReleaseEnvelope({
     artifactRoot: outputDirectory,
@@ -946,14 +1149,21 @@ export const stageCloudflareReleaseEnvelope = async ({
 const createCloudflareStagedReleaseArtifactInputs = async (
   outputDirectory: string,
   identity: MicroVerticalReleaseIdentity,
+  apiOnly: boolean,
+  declaredPublicAssets: readonly string[],
 ) => {
   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(
@@ -974,28 +1184,47 @@ const createCloudflareStagedReleaseArtifactInputs = async (
   }
   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 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) &&
-      !EFFECT_BFF_WORKER_PATTERN.test(logicalPath),
+      !isEffectBffWorkerArtifact(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 (
+    apiOnly &&
+    (uiClientPaths.length > 0 ||
+      ssrPaths.some(path => path !== 'server/index.mjs'))
+  ) {
+    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', uiClientPaths],
-    ['Cloudflare SSR', ssrPaths],
+    ['Cloudflare SSR', apiOnly ? [] : ssrPaths],
     ['Cloudflare API/backend', apiBackendPaths],
   ] as const) {
-    if (paths.length === 0) {
+    if (
+      paths.length === 0 &&
+      (!apiOnly || surface === 'Cloudflare API/backend')
+    ) {
       throw new Error(
         `[ultramodern-release-envelope] final Cloudflare staging has no ${surface} artifacts.`,
       );
@@ -1009,18 +1238,25 @@ const createCloudflareStagedReleaseArtifactInputs = async (
     }
   }
 
-  const clientExecutionPaths = await manifestReferencedClientModules(
-    outputDirectory,
-    files,
-    'public/mf-manifest.json',
-  );
-  const ssrExecutionPaths = await routeReferencedSsrModules(
-    outputDirectory,
-    files,
-    'cloudflare',
-    'server/route.json',
-  );
-  if (clientExecutionPaths.length === 0 || ssrExecutionPaths.length === 0) {
+  const clientExecutionPaths = apiOnly
+    ? []
+    : await manifestReferencedClientModules(
+        outputDirectory,
+        files,
+        'public/mf-manifest.json',
+      );
+  const ssrExecutionPaths = apiOnly
+    ? []
+    : await routeReferencedSsrModules(
+        outputDirectory,
+        files,
+        'cloudflare',
+        'server/route.json',
+      );
+  if (
+    !apiOnly &&
+    (clientExecutionPaths.length === 0 || ssrExecutionPaths.length === 0)
+  ) {
     throw new Error(
       '[ultramodern-release-envelope] final Cloudflare manifests must reference emitted UI/client and SSR execution modules.',
     );
@@ -1036,7 +1272,12 @@ const createCloudflareStagedReleaseArtifactInputs = async (
     }
   };
   add(uiClientPaths, 'browser');
-  add(ssrPaths, 'workerd');
+  add([...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');
   add([backendManifestPath], 'module-federation-manifest');
   add([backendContainerPath], 'commonjs-module');
@@ -1047,12 +1288,16 @@ const createCloudflareStagedReleaseArtifactInputs = async (
     {
       apiBackend: apiBackendPaths,
       backendFederation: [backendManifestPath, backendContainerPath],
-      ssr: [
-        ...new Set([
-          ...ssrExecutionPaths,
-          ...ssrPaths.filter(logicalPath => logicalPath.startsWith('worker/')),
-        ]),
-      ],
+      ssr: apiOnly
+        ? []
+        : [
+            ...new Set([
+              ...ssrExecutionPaths,
+              ...ssrPaths.filter(logicalPath =>
+                logicalPath.startsWith('worker/'),
+              ),
+            ]),
+          ],
       uiClient: uiClientPaths.filter(logicalPath =>
         COMPILED_MODULE_PATTERN.test(logicalPath),
       ),
@@ -1069,7 +1314,9 @@ const createCloudflareStagedReleaseArtifactInputs = async (
       uiClient: [...uiClientPaths].sort((left, right) =>
         left.localeCompare(right),
       ),
-      ssr: [...ssrPaths].sort((left, right) => left.localeCompare(right)),
+      ssr: apiOnly
+        ? []
+        : [...ssrPaths].sort((left, right) => left.localeCompare(right)),
       apiBackend: [...apiBackendPaths].sort((left, right) =>
         left.localeCompare(right),
       ),
@@ -1082,9 +1329,12 @@ const createCloudflareStagedReleaseArtifactInputs = async (
 };
 
 export const emitCloudflareStagedReleaseEnvelope = async ({
+  declaredPublicAssets = [],
   distDirectory,
   outputDirectory,
 }: {
+  /** Staged `deploy.worker.publicAssets` files, relative to `outputDirectory`. */
+  declaredPublicAssets?: readonly string[];
   distDirectory: string;
   outputDirectory: string;
 }) => {
@@ -1099,6 +1349,8 @@ export const emitCloudflareStagedReleaseEnvelope = async ({
     await createCloudflareStagedReleaseArtifactInputs(
       outputDirectory,
       source.identity,
+      source.surfaces.uiClient.length === 0,
+      declaredPublicAssets,
     );
   const staged = await createMicroVerticalReleaseEnvelope({
     artifactRoot: outputDirectory,