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

package/dist/esm/build-config/build-environment.mjs

@@ -1,147 +1,28 @@
-import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { accessSync, chmodSync, constants, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { createRequire } from "node:module";
+import { createRequire, findPackageJSON } from "node:module";
 import { tmpdir } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
-const EFFECT_TSGO_PACKAGE = '@effect/tsgo';
-const EFFECT_TSGO_BIN = 'effect-tsgo';
+import { basename, join } from "node:path";
+import "node:url";
+const owningModuleUrl = import.meta.url;
+const owningManifest = findPackageJSON(owningModuleUrl, owningModuleUrl);
+if (!owningManifest) throw new Error('Cannot find owning build-config package manifest');
+const owningName = JSON.parse(readFileSync(owningManifest, 'utf8')).name;
+if ('string' != typeof owningName || 0 === owningName.length) throw new Error(`Invalid owning build-config package name: ${owningManifest}`);
+const { effectCompilerDiscoveryFailureStage: effectCompilerDiscoveryFailureStage, resolveInstalledEffectCompiler: resolveInstalledEffectCompiler } = createRequire(owningModuleUrl)(`${owningName}/internal-effect-discovery`);
 const EFFECT_TSGO_RESOLUTION_ERROR = 'Unable to resolve the Effect TS-Go compiler. Install "@effect/tsgo" and a native TypeScript backend for this build config, or set EFFECT_TSGO_BIN.';
 const executableEffectTsgoCompilers = new Map();
-const BUILD_CONFIG_ENVIRONMENT_PLUGIN = 'ModernJsBuildConfigEnvironmentLeasePlugin';
-const ENVIRONMENT_LEASE_REGISTRY_KEY = Symbol.for('@modern-js/app-tools/build-config-environment-lease-registry/v1');
-const ENVIRONMENT_LEASE_REGISTRY_BRAND = Symbol.for('@modern-js/app-tools/build-config-environment-lease-registry-brand/v1');
-const LIFECYCLE_HOOK_NAMES = [
-    'run',
-    'watchRun',
-    'afterDone',
-    'failed',
-    'shutdown',
-    'watchClose'
-];
-function restoreEnvironment(name, value) {
-    if (void 0 === value) delete process.env[name];
-    else process.env[name] = value;
-}
-function createEnvironmentLeaseRegistry() {
-    const environmentLeases = new Map();
-    return Object.freeze({
-        acquire (name, value) {
-            let lease = environmentLeases.get(name);
-            if (lease) {
-                if (lease.value !== value) throw new Error(`Build config environment "${name}" already has an active lease for a different value.`);
-                if (process.env[name] !== lease.value) throw new Error(`Build config environment lease for "${name}" lost ownership before another lease was acquired.`);
-            } else {
-                lease = {
-                    originalValue: process.env[name],
-                    owners: new Set(),
-                    value
-                };
-                process.env[name] = value;
-                environmentLeases.set(name, lease);
-            }
-            const owner = Symbol(name);
-            lease.owners.add(owner);
-            let released = false;
-            return ()=>{
-                if (released) return;
-                if (environmentLeases.get(name) !== lease || !lease.owners.has(owner)) throw new Error(`Build config environment lease for "${name}" cannot be restored because its ownership record was lost.`);
-                released = true;
-                const lostOwnership = process.env[name] !== lease.value;
-                lease.owners.delete(owner);
-                if (0 === lease.owners.size) {
-                    environmentLeases.delete(name);
-                    restoreEnvironment(name, lease.originalValue);
-                } else if (lostOwnership) process.env[name] = lease.value;
-                if (lostOwnership) throw new Error(`Build config environment lease for "${name}" lost ownership before restoration.`);
-            };
-        },
-        brand: ENVIRONMENT_LEASE_REGISTRY_BRAND
-    });
-}
-function getEnvironmentLeaseRegistry() {
-    const descriptor = Object.getOwnPropertyDescriptor(process, ENVIRONMENT_LEASE_REGISTRY_KEY);
-    if (descriptor) {
-        const registry = descriptor.value;
-        if (descriptor.configurable || descriptor.enumerable || descriptor.writable || registry?.brand !== ENVIRONMENT_LEASE_REGISTRY_BRAND || 'function' != typeof registry.acquire) throw new Error('The process-global build config environment lease registry is occupied by an incompatible value.');
-        return registry;
-    }
-    const registry = createEnvironmentLeaseRegistry();
-    Object.defineProperty(process, ENVIRONMENT_LEASE_REGISTRY_KEY, {
-        configurable: false,
-        enumerable: false,
-        value: registry,
-        writable: false
+function effectTsgoResolutionError(cause, stage, from) {
+    const detail = cause instanceof Error ? `${cause.name}: ${cause.message}` : String(cause);
+    return new Error(`${EFFECT_TSGO_RESOLUTION_ERROR}\n${stage} failed for ${String(from)}: ${detail}`, {
+        cause
     });
-    return registry;
-}
-function acquireEnvironmentLease(name, value) {
-    return getEnvironmentLeaseRegistry().acquire(name, value);
-}
-function releaseAfterFailure(release, originalError) {
-    try {
-        release();
-    } catch (restorationError) {
-        throw new AggregateError([
-            originalError,
-            restorationError
-        ], 'Build config environment setup and restoration both failed.');
-    }
-    throw originalError;
-}
-class BuildConfigEnvironmentLeasePlugin {
-    apply(compiler) {
-        const hooks = compiler.hooks;
-        try {
-            const lifecycleHooks = {};
-            for (const hookName of LIFECYCLE_HOOK_NAMES){
-                const hook = hooks[hookName];
-                if (!hook || 'function' != typeof hook.tap) throw new Error(`Rspack does not expose the "${hookName}" lifecycle hook required to restore build config environment leases.`);
-                lifecycleHooks[hookName] = hook;
-            }
-            let mode = 'pending';
-            const modeTap = {
-                name: BUILD_CONFIG_ENVIRONMENT_PLUGIN,
-                stage: Number.MIN_SAFE_INTEGER
-            };
-            const releaseTap = {
-                name: BUILD_CONFIG_ENVIRONMENT_PLUGIN,
-                stage: Number.MAX_SAFE_INTEGER
-            };
-            const releaseAfterOneShot = ()=>{
-                if ('watch' !== mode && true !== compiler.watchMode) this.release();
-            };
-            lifecycleHooks.run.tap(modeTap, ()=>{
-                mode = 'run';
-            });
-            lifecycleHooks.watchRun.tap(modeTap, ()=>{
-                mode = 'watch';
-            });
-            lifecycleHooks.afterDone.tap(releaseTap, releaseAfterOneShot);
-            lifecycleHooks.failed.tap(releaseTap, releaseAfterOneShot);
-            lifecycleHooks.shutdown.tap(releaseTap, this.release);
-            lifecycleHooks.watchClose.tap(releaseTap, this.release);
-        } catch (error) {
-            releaseAfterFailure(this.release, error);
-        }
-    }
-    constructor(release){
-        this.release = release;
-    }
-}
-function resolveEffectTsgoCli(from) {
-    const projectRequire = createRequire(from);
-    const packageJsonPath = projectRequire.resolve(`${EFFECT_TSGO_PACKAGE}/package.json`);
-    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
-    const bin = 'string' == typeof packageJson.bin ? packageJson.bin : packageJson.bin?.[EFFECT_TSGO_BIN];
-    if (!bin) throw new Error(EFFECT_TSGO_RESOLUTION_ERROR);
-    return resolve(dirname(packageJsonPath), bin);
 }
 function resolveExecutableEffectTsgoCompiler(compilerPath) {
     if ('win32' === process.platform) return compilerPath;
     const sourcePath = realpathSync(compilerPath);
     const source = lstatSync(sourcePath);
-    if (!source.isFile()) throw new Error(EFFECT_TSGO_RESOLUTION_ERROR);
+    if (!source.isFile()) throw new Error(`Effect TS-Go compiler path is not a regular file: ${sourcePath}`);
     try {
         accessSync(sourcePath, constants.X_OK);
         return compilerPath;
@@ -188,37 +69,22 @@ function resolveExecutableEffectTsgoCompiler(compilerPath) {
 function getBuildConfigEnvironment(name) {
     return process.env[name];
 }
-function withBuildConfigEnvironment(name, value, setup) {
-    return async (config, ...args)=>{
-        const release = acquireEnvironmentLease(name, value);
-        try {
-            const configured = await setup(config, ...args) ?? config;
-            configured.plugins = [
-                ...configured.plugins ?? [],
-                new BuildConfigEnvironmentLeasePlugin(release)
-            ];
-            return configured;
-        } catch (error) {
-            releaseAfterFailure(release, error);
-        }
-    };
-}
 function resolveEffectTsgoCompiler(options) {
     const configuredCompiler = getBuildConfigEnvironment('EFFECT_TSGO_BIN')?.trim();
     if (configuredCompiler) try {
         return resolveExecutableEffectTsgoCompiler(configuredCompiler);
-    } catch  {
-        throw new Error(EFFECT_TSGO_RESOLUTION_ERROR);
+    } catch (cause) {
+        throw effectTsgoResolutionError(cause, 'Configured compiler validation', options.from);
     }
+    let stage = 'Package CLI resolution';
     try {
-        const compiler = execFileSync(process.execPath, [
-            resolveEffectTsgoCli(options.from),
-            'get-exe-path'
-        ], {
-            encoding: 'utf-8'
-        }).trim();
-        if (compiler) return resolveExecutableEffectTsgoCompiler(compiler);
-    } catch  {}
-    throw new Error(EFFECT_TSGO_RESOLUTION_ERROR);
+        const compiler = resolveInstalledEffectCompiler(options.from).trim();
+        stage = 'Compiler backend lookup';
+        if (!compiler) throw new Error('Effect TS-Go discovery returned an empty compiler path');
+        stage = 'Compiler executable validation';
+        return resolveExecutableEffectTsgoCompiler(compiler);
+    } catch (cause) {
+        throw effectTsgoResolutionError(cause, effectCompilerDiscoveryFailureStage(cause) ?? stage, options.from);
+    }
 }
-export { getBuildConfigEnvironment, resolveEffectTsgoCompiler, withBuildConfigEnvironment };
+export { getBuildConfigEnvironment, resolveEffectTsgoCompiler };

package/dist/esm/build-config/internal-effect-discovery.mjs

@@ -0,0 +1,102 @@
+import { lstatSync, readFileSync, realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const EFFECT_TSGO_PACKAGE = '@effect/tsgo';
+const EFFECT_TSGO_BIN = 'effect-tsgo';
+const NATIVE_TYPESCRIPT_PACKAGES = [
+    "typescript",
+    "@typescript/native"
+];
+const failureStages = new WeakMap();
+function effectCompilerDiscoveryFailureStage(error) {
+    return error && 'object' == typeof error ? failureStages.get(error) : void 0;
+}
+function resolveEffectTsgoPackage(from) {
+    const projectRequire = createRequire(from);
+    const packageJsonPath = projectRequire.resolve(`${EFFECT_TSGO_PACKAGE}/package.json`);
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    const bin = 'string' == typeof packageJson.bin ? packageJson.bin : packageJson.bin?.[EFFECT_TSGO_BIN];
+    if (!bin) throw new Error(`Resolved ${EFFECT_TSGO_PACKAGE} package has no ${EFFECT_TSGO_BIN} bin: ${packageJsonPath}`);
+    const cliPath = realpathSync(resolve(dirname(packageJsonPath), bin));
+    if (!lstatSync(cliPath).isFile()) throw new Error(`Effect TS-Go CLI is not a regular file: ${cliPath}`);
+    return {
+        packageJsonPath,
+        packageJson,
+        cliPath
+    };
+}
+function isAbsentNativeTypeScriptPackage(projectRequire, from, packageName, error) {
+    const filename = 'string' != typeof from || from.startsWith('file:') ? fileURLToPath(from) : from;
+    if (!(error instanceof Error) || !('code' in error) || 'MODULE_NOT_FOUND' !== error.code || 'path' in error && void 0 !== error.path || error.message.split('\n')[0] !== `Cannot find module '${packageName}/package.json'` || !('requireStack' in error) || !Array.isArray(error.requireStack) || error.requireStack[0] !== filename) return false;
+    for (const searchDirectory of projectRequire.resolve.paths(packageName) ?? [])try {
+        lstatSync(join(searchDirectory, packageName));
+        return false;
+    } catch (presenceError) {
+        if (!(presenceError instanceof Error) || !('code' in presenceError) || ![
+            'ENOENT',
+            'ENOTDIR'
+        ].includes(String(presenceError.code))) throw presenceError;
+    }
+    return true;
+}
+function resolveNativeTypeScriptPackage(from) {
+    const projectRequire = createRequire(from);
+    for (const packageName of NATIVE_TYPESCRIPT_PACKAGES){
+        let packageJsonPath;
+        try {
+            packageJsonPath = projectRequire.resolve(`${packageName}/package.json`);
+        } catch (error) {
+            if (isAbsentNativeTypeScriptPackage(projectRequire, from, packageName, error)) continue;
+            throw error;
+        }
+        const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+        const major = packageJson.version?.match(/^(\d+)\.\d+\.\d+(?:[-+].*)?$/u)?.[1];
+        if (!major) throw new Error(`Resolved TypeScript package has no valid version: ${packageJsonPath}`);
+        if (Number(major) >= 7) return packageJsonPath;
+    }
+    throw new Error(`No native TypeScript backend is installed for ${String(from)}. Install typescript >=7 or @typescript/native.`);
+}
+function resolveNativeTypeScriptManifest(from) {
+    const packageJsonPath = resolveNativeTypeScriptPackage(from);
+    const directory = dirname(packageJsonPath);
+    const discoveryPackage = resolveNativeTypeScriptPackage(join(directory, '__ultramodern_effect_backend__.cjs'));
+    if (realpathSync(discoveryPackage) !== realpathSync(packageJsonPath)) throw new Error(`Effect discovery would select a different native TypeScript installation from ${directory}: ${discoveryPackage}`);
+    return packageJsonPath;
+}
+function readCompilerArtifact(filename) {
+    const canonicalPath = realpathSync(filename);
+    const stats = lstatSync(canonicalPath);
+    if (!stats.isFile()) throw new Error(`Compiler artifact is not a regular file: ${filename}`);
+    if (0 === stats.size) throw new Error(`Compiler artifact is empty: ${filename}`);
+    return canonicalPath;
+}
+function resolveInstalledEffectCompiler(from) {
+    let stage = 'Package CLI resolution';
+    try {
+        const effect = resolveEffectTsgoPackage(from);
+        stage = 'Native TypeScript package resolution';
+        const typeScriptManifest = resolveNativeTypeScriptManifest(from);
+        const typeScript = JSON.parse(readFileSync(typeScriptManifest, 'utf8'));
+        const nativeName = `@typescript/typescript-${process.platform}-${process.arch}`;
+        const nativeManifest = createRequire(typeScriptManifest).resolve(`${nativeName}/package.json`);
+        const native = JSON.parse(readFileSync(nativeManifest, 'utf8'));
+        if (native.name !== nativeName || native.version !== typeScript.version || 'string' != typeof native.version || !/^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/u.test(native.version) || 'string' != typeof native.gitHead || !/^[a-f\d]{40}$/u.test(native.gitHead) || native.gitHead !== typeScript.gitHead) throw new Error(`Native TypeScript platform does not match its selected package: ${nativeManifest}`);
+        const binaryName = 'win32' === process.platform ? 'tsc.exe' : 'tsc';
+        readCompilerArtifact(join(dirname(nativeManifest), 'lib', binaryName));
+        stage = 'Compiler backend lookup';
+        const effectName = `@effect/tsgo-${process.platform}-${process.arch}`;
+        const effectManifest = createRequire(effect.cliPath).resolve(`${effectName}/package.json`);
+        const platform = JSON.parse(readFileSync(effectManifest, 'utf8'));
+        if (platform.name !== effectName || 'string' != typeof effect.packageJson.version || platform.version !== effect.packageJson.version) throw new Error(`Effect platform does not match its selected provider: ${effectManifest}`);
+        const metadataPath = join(dirname(effectManifest), 'lib', 'upstream.json');
+        const metadata = JSON.parse(readFileSync(metadataPath, 'utf8'));
+        const component = metadata.components?.typescript?.[native.version];
+        if (5 !== metadata.schemaVersion || component?.provider !== "typescript-go" || component.gitHead !== native.gitHead) throw new Error(`Effect replacement metadata does not match the selected native TypeScript backend: ${metadataPath}`);
+        return readCompilerArtifact(join(dirname(effectManifest), 'artifacts', "typescript", native.version, binaryName));
+    } catch (error) {
+        if (error && 'object' == typeof error && !failureStages.has(error)) failureStages.set(error, stage);
+        throw error;
+    }
+}
+export { effectCompilerDiscoveryFailureStage, resolveInstalledEffectCompiler };

package/dist/esm/build-config/public.mjs

@@ -1 +1 @@
-export { getBuildConfigEnvironment, resolveEffectTsgoCompiler, withBuildConfigEnvironment } from "./build-environment.mjs";
+export { getBuildConfigEnvironment, resolveEffectTsgoCompiler } from "./build-environment.mjs";

package/dist/esm/build-config/remote-address.mjs

@@ -0,0 +1,20 @@
+import { resolveBrowserManifestAddress } from "@modern-js/surface-resolution";
+import { resolveDeployTarget } from "../deploy-output/target.mjs";
+import { getBuildConfigEnvironment } from "./build-environment.mjs";
+function createRemoteManifestUrl(options) {
+    const env = {
+        ...Object.fromEntries([
+            options.manifestEnv,
+            options.publicUrlEnv,
+            'ULTRAMODERN_CLOUDFLARE_WORKERS_DEV_SUBDOMAIN'
+        ].map((name)=>[
+                name,
+                getBuildConfigEnvironment(name)
+            ])),
+        MODERNJS_DEPLOY: resolveDeployTarget().target
+    };
+    const address = resolveBrowserManifestAddress(env, options, getBuildConfigEnvironment('NODE_ENV') ?? 'production');
+    if (!address.ok) throw new Error(`Remote ${options.mfName}: ${address.reason}`);
+    return env[options.manifestEnv]?.trim() || `${options.mfName}@${address.manifestUrl}`;
+}
+export { createRemoteManifestUrl };

package/dist/esm/cloudflare/artifacts.mjs

@@ -1,5 +1,6 @@
 import node_path from "node:path";
 import { fs } from "@modern-js/utils";
+import { CLOUDFLARE_PUBLIC_ASSET_SCOPE, normalizeDeclaredPublicAssets, stageDeclaredPublicAssets } from "../deploy-output/public-assets.mjs";
 import { RESERVED_ARTIFACT_DESTINATION_DIRECTORIES, RESERVED_ARTIFACT_DESTINATION_FILES, ROUTE_SPEC_OUTPUT } from "./constants.mjs";
 import { normalizeRelativePath } from "./utils.mjs";
 const normalizeCloudflareArtifact = (artifact, index)=>{
@@ -15,18 +16,7 @@ const normalizeCloudflareArtifact = (artifact, index)=>{
     };
 };
 const getCloudflareArtifacts = (modernConfig)=>(modernConfig.deploy?.worker?.artifacts ?? []).map(normalizeCloudflareArtifact);
-const normalizeCloudflarePublicAsset = (asset, index)=>{
-    const from = normalizeRelativePath(asset.from, `deploy.worker.publicAssets[${index}].from`, 'app root');
-    const to = normalizeRelativePath(asset.to, `deploy.worker.publicAssets[${index}].to`, 'Cloudflare public output', {
-        allowRoot: true
-    });
-    return {
-        from,
-        to,
-        index
-    };
-};
-const getCloudflarePublicAssets = (modernConfig)=>(modernConfig.deploy?.worker?.publicAssets ?? []).map(normalizeCloudflarePublicAsset);
+const getCloudflarePublicAssets = (modernConfig)=>normalizeDeclaredPublicAssets(modernConfig.deploy?.worker?.publicAssets, CLOUDFLARE_PUBLIC_ASSET_SCOPE);
 const copyCloudflareArtifacts = async (appDirectory, outputDirectory, artifacts)=>{
     for (const artifact of artifacts){
         const sourcePath = node_path.join(appDirectory, artifact.from);
@@ -34,13 +24,12 @@ const copyCloudflareArtifacts = async (appDirectory, outputDirectory, artifacts)
         await fs.copy(sourcePath, node_path.join(outputDirectory, artifact.to));
     }
 };
-const copyCloudflarePublicAssets = async (appDirectory, publicDirectory, publicAssets)=>{
-    for (const asset of publicAssets){
-        const sourcePath = node_path.join(appDirectory, asset.from);
-        if (!await fs.pathExists(sourcePath)) throw new Error(`deploy.worker.publicAssets[${asset.index}].from does not exist: ${asset.from}`);
-        await fs.copy(sourcePath, node_path.join(publicDirectory, asset.to));
-    }
-};
+const copyCloudflarePublicAssets = async (appDirectory, outputDirectory, publicAssets)=>stageDeclaredPublicAssets({
+        appDirectory,
+        outputDirectory,
+        assets: publicAssets,
+        scope: CLOUDFLARE_PUBLIC_ASSET_SCOPE
+    });
 const copyCloudflareD1Migrations = async (appDirectory, outputDirectory, modernConfig)=>{
     for (const [index, database] of (modernConfig.deploy?.worker?.d1Databases ?? []).entries()){
         if (!database.migrationsDir) continue;

package/dist/esm/cloudflare/delivery-unit.mjs

@@ -1,13 +1,21 @@
 import node_path from "node:path";
-import { ULTRAMODERN_BUILD_ARTIFACT_PATH, isUltramodernBuildArtifact, nonEmptyString, toDeliveryUnitIdentity } from "@modern-js/backend-federation-contracts";
+import { isDeepStrictEqual } from "node:util";
+import { ULTRAMODERN_BUILD_ARTIFACT_FILE, ULTRAMODERN_BUILD_ARTIFACT_PATH, assertRendererProfileCompatibility, assertUltramodernBuildArtifact, formatBackendFederationValidationErrors, immutableRendererRouterBindings, nonEmptyString, toDeliveryUnitIdentity, validateRendererIdentity, validateRendererProfile, validateRendererRouterBindings } from "@modern-js/backend-federation-contracts";
 import { fs } from "@modern-js/utils";
 import { resolveUltramodernReleaseIdentity } from "../release-identity.mjs";
 import { isRecord } from "./utils.mjs";
-const COMPACT_CONFIG_PATH = '.modernjs/ultramodern.json';
+const TOPOLOGY_PATH = 'topology/reference-topology.json';
+const RENDERER_PROJECTION_FIELDS = [
+    'renderer',
+    'rendererIdentity',
+    'rendererIdentities',
+    'rendererProfile',
+    'routerBindings'
+];
 const findWorkspaceRoot = async (appDirectory)=>{
     let current = node_path.resolve(appDirectory);
     for(;;){
-        if (await fs.pathExists(node_path.join(current, COMPACT_CONFIG_PATH))) return current;
+        if (await fs.pathExists(node_path.join(current, TOPOLOGY_PATH))) return current;
         const parent = node_path.dirname(current);
         if (parent === current) return;
         current = parent;
@@ -24,51 +32,83 @@ const stampReleaseIdentity = (identity, workspaceRoot)=>{
         })
     };
 };
-const resolveCompactApp = async (appDirectory)=>{
+const resolveTopologyApp = async (appDirectory)=>{
     const workspaceRoot = await findWorkspaceRoot(appDirectory);
     if (!workspaceRoot) return;
-    let compactConfig;
-    try {
-        compactConfig = await fs.readJSON(node_path.join(workspaceRoot, COMPACT_CONFIG_PATH));
-    } catch  {
-        return {
-            workspaceRoot
-        };
-    }
-    if (!isRecord(compactConfig)) return {
-        workspaceRoot
-    };
-    const topology = isRecord(compactConfig.topology) ? compactConfig.topology : void 0;
-    const apps = Array.isArray(topology?.apps) ? topology.apps : void 0;
-    if (!apps) return {
-        app: compactConfig,
-        workspaceRoot
-    };
+    const topology = await fs.readJSON(node_path.join(workspaceRoot, TOPOLOGY_PATH));
+    if (!isRecord(topology) || !isRecord(topology.shell) || !Array.isArray(topology.verticals) || void 0 !== topology.shells && !Array.isArray(topology.shells)) throw new Error('[cloudflare-delivery-unit] Invalid declared reference topology.');
+    const apps = [
+        topology.shell,
+        ...topology.verticals,
+        ...Array.isArray(topology.shells) ? topology.shells : []
+    ];
     const resolvedAppDirectory = node_path.resolve(appDirectory);
     const app = apps.find((candidate)=>{
         if (!isRecord(candidate)) return false;
         const appPath = nonEmptyString(candidate.path);
         return void 0 !== appPath && node_path.resolve(workspaceRoot, appPath.replace(/^\.\/+/u, '')) === resolvedAppDirectory;
     });
+    if (!isRecord(app)) throw new Error(`[cloudflare-delivery-unit] ${appDirectory} is missing from the declared reference topology.`);
     return {
-        ...isRecord(app) ? {
-            app
-        } : {},
+        app,
+        role: app === topology.shell || Array.isArray(topology.shells) && topology.shells.includes(app) ? 'shell' : 'microvertical',
         workspaceRoot
     };
 };
-const createDeliveryUnitStamp = (identity, app)=>{
-    const surfaceProfile = nonEmptyString(app?.surfaceProfile);
+const resolveTopologyReleaseRole = async (appDirectory)=>{
+    const resolved = await resolveTopologyApp(appDirectory);
+    if (!resolved?.app) return;
+    const kind = 'shell' === resolved.role ? 'shell' : 'vertical';
+    if (resolved.app.kind !== kind) throw new Error('[cloudflare-delivery-unit] Declared app kind disagrees with its topology membership.');
+    return resolved.role;
+};
+const createTopologyDeliveryUnitStamp = (identity, app)=>{
+    const surfaceProfile = nonEmptyString(app.surfaceProfile);
+    if (void 0 !== surfaceProfile && ![
+        'api-only',
+        'ui-only',
+        'full-stack'
+    ].includes(surfaceProfile)) throw new Error('[cloudflare-delivery-unit] Declared app has an invalid surface profile.');
     const emitsUi = 'api-only' !== surfaceProfile;
     const emitsApi = 'ui-only' !== surfaceProfile;
+    const appId = nonEmptyString(app.id);
+    if (!appId) throw new Error('[cloudflare-delivery-unit] Declared app requires an id.');
+    let ui;
+    if (emitsUi) if (RENDERER_PROJECTION_FIELDS.every((field)=>!Object.hasOwn(app, field))) ui = {
+        ...identity,
+        surface: 'ui'
+    };
+    else {
+        const routerBindings = isRecord(app.routerBindings) ? app.routerBindings : {};
+        const errors = [
+            ...validateRendererIdentity(app.rendererIdentity).errors,
+            ...validateRendererProfile(app.rendererProfile).errors,
+            ...validateRendererRouterBindings(app.routerBindings, Object.keys(routerBindings), 'routerBindings').errors
+        ];
+        if (errors.length) throw new Error(`[cloudflare-delivery-unit] ${formatBackendFederationValidationErrors(errors)}`);
+        const rendererIdentity = app.rendererIdentity;
+        const rendererProfile = app.rendererProfile;
+        if (!Object.hasOwn(routerBindings, rendererIdentity.entryName)) throw new Error('[cloudflare-delivery-unit] Topology routerBindings must include the primary renderer identity entry.');
+        const declaredIdentity = toDeliveryUnitIdentity(app.deliveryUnit);
+        if (rendererIdentity.renderer !== app.renderer || rendererIdentity.renderer !== rendererProfile.renderer || rendererIdentity.appId !== app.id || rendererIdentity.buildId !== declaredIdentity?.buildMarker) throw new Error('[cloudflare-delivery-unit] Topology UI renderer metadata must match its app and delivery-unit identity.');
+        ui = {
+            ...identity,
+            surface: 'ui',
+            rendererIdentity: {
+                ...rendererIdentity,
+                buildId: identity.buildMarker
+            },
+            rendererProfile,
+            routerBindings: immutableRendererRouterBindings(routerBindings)
+        };
+    }
+    else if (void 0 !== app.rendererIdentity || void 0 !== app.rendererProfile || void 0 !== app.routerBindings) throw new Error('[cloudflare-delivery-unit] API-only topology must not declare a UI renderer identity or profile.');
     return {
         ...identity,
+        appId,
         surfaces: {
-            ...emitsUi ? {
-                ui: {
-                    ...identity,
-                    surface: 'ui'
-                }
+            ...ui ? {
+                ui
             } : {},
             ...emitsApi ? {
                 api: {
@@ -80,22 +120,61 @@ const createDeliveryUnitStamp = (identity, app)=>{
     };
 };
 const resolveTopologyDeliveryUnit = async (appDirectory)=>{
-    const resolved = await resolveCompactApp(appDirectory);
+    const resolved = await resolveTopologyApp(appDirectory);
     if (!resolved?.app) return;
     const identity = toDeliveryUnitIdentity(resolved.app.deliveryUnit);
-    return identity ? createDeliveryUnitStamp(stampReleaseIdentity(identity, resolved.workspaceRoot), resolved.app) : void 0;
+    if (!identity) throw new Error('[cloudflare-delivery-unit] Declared app is missing a valid delivery-unit identity.');
+    return createTopologyDeliveryUnitStamp(stampReleaseIdentity(identity, resolved.workspaceRoot), resolved.app);
 };
-const resolveWorkerDeliveryUnitStamp = async (appDirectory)=>{
-    const buildArtifactPath = node_path.join(appDirectory, ULTRAMODERN_BUILD_ARTIFACT_PATH);
-    let identity;
-    if (await fs.pathExists(buildArtifactPath)) {
-        const artifact = await fs.readJSON(buildArtifactPath);
-        if (!isUltramodernBuildArtifact(artifact)) return;
-        identity = toDeliveryUnitIdentity(artifact.deliveryUnit);
+const resolveWorkerDeliveryUnitStamp = async (appDirectory, distDirectory)=>{
+    const buildArtifactPath = node_path.join(distDirectory, ULTRAMODERN_BUILD_ARTIFACT_FILE);
+    if (!await fs.pathExists(buildArtifactPath)) {
+        if (await fs.pathExists(node_path.join(appDirectory, ULTRAMODERN_BUILD_ARTIFACT_PATH))) throw new Error('[cloudflare-delivery-unit] Finalized build artifact is required before worker output stamping.');
+        return;
+    }
+    const artifact = await fs.readJSON(buildArtifactPath);
+    assertUltramodernBuildArtifact(artifact);
+    const identity = {
+        unitId: artifact.deliveryUnit.unitId,
+        buildMarker: artifact.deliveryUnit.buildMarker,
+        sourceRevision: artifact.deliveryUnit.sourceRevision
+    };
+    const resolved = await resolveTopologyApp(appDirectory);
+    const stampedArtifact = artifact;
+    let emitsApi = true;
+    if (resolved?.app) {
+        if (stampedArtifact.deliveryUnit.appId !== resolved.app.id) throw new Error('[cloudflare-delivery-unit] Build artifact appId must match the declared topology app.');
+        const declaredIdentity = toDeliveryUnitIdentity(resolved.app.deliveryUnit);
+        if (!declaredIdentity) throw new Error('[cloudflare-delivery-unit] Declared app is missing a valid delivery-unit identity.');
+        const expected = createTopologyDeliveryUnitStamp(identity, resolved.app);
+        for (const field of [
+            'unitId'
+        ])if (declaredIdentity[field] !== identity[field]) throw new Error(`[cloudflare-delivery-unit] Build artifact ${field} must match the declared topology delivery-unit identity.`);
+        const ui = stampedArtifact.surfaces.ui;
+        if (Boolean(expected.surfaces.ui) !== Boolean(ui)) throw new Error('[cloudflare-delivery-unit] Build artifact UI surface must match the declared topology surface profile.');
+        if (expected.surfaces.ui?.rendererIdentity && ui) {
+            if (!isDeepStrictEqual(expected.surfaces.ui.routerBindings, ui.routerBindings)) throw new Error('[cloudflare-delivery-unit] Finalized build routerBindings must match the declared topology router bindings.');
+            for (const field of [
+                'renderer',
+                'appId',
+                'entryName',
+                'protocolVersion',
+                'buildId'
+            ])if (expected.surfaces.ui.rendererIdentity[field] !== ui.rendererIdentity[field]) throw new Error(`[cloudflare-delivery-unit] Build artifact UI rendererIdentity.${field} must match the declared topology renderer identity.`);
+            assertRendererProfileCompatibility(expected.surfaces.ui.rendererProfile, ui.rendererProfile);
+        }
+        emitsApi = void 0 !== expected.surfaces.api;
     }
-    if (!identity) return;
-    const resolved = await resolveCompactApp(appDirectory);
-    if (resolved) identity = stampReleaseIdentity(identity, resolved.workspaceRoot);
-    return createDeliveryUnitStamp(identity, resolved?.app);
+    return {
+        ...stampedArtifact.deliveryUnit,
+        surfaces: {
+            ...emitsApi ? {
+                api: stampedArtifact.surfaces.api
+            } : {},
+            ...stampedArtifact.surfaces.ui ? {
+                ui: stampedArtifact.surfaces.ui
+            } : {}
+        }
+    };
 };
-export { resolveTopologyDeliveryUnit, resolveWorkerDeliveryUnitStamp };
+export { resolveTopologyDeliveryUnit, resolveTopologyReleaseRole, resolveWorkerDeliveryUnitStamp };