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

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

@@ -1,8 +1,9 @@
 import { createHash } from "node:crypto";
 import promises from "node:fs/promises";
 import node_path from "node:path";
+import { formatBackendFederationValidationErrors, immutableRendererRouterBindings, validateRendererIdentity, validateRendererProfile, validateRendererProfileCompatibility, validateRendererRouterBindings } from "@modern-js/backend-federation-contracts";
 import { canonicalSerializeMicroVerticalReleaseEnvelope, digestMicroVerticalReleaseEnvelopePayload, releaseEnvelopePayload } from "./canonical.mjs";
-import { MICROVERTICAL_RELEASE_ENVELOPE_KIND, MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION, MICROVERTICAL_RELEASE_TARGETS } from "./types.mjs";
+import { MICROVERTICAL_RELEASE_ENVELOPE_KIND, MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION, MICROVERTICAL_RELEASE_TARGETS, SHELL_RELEASE_ENVELOPE_KIND } from "./types.mjs";
 const SHA256_PATTERN = /^[a-f0-9]{64}$/u;
 const SOURCE_REVISION_PATTERN = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u;
 const TARGETS = new Set(MICROVERTICAL_RELEASE_TARGETS);
@@ -26,6 +27,10 @@ const assertTarget = (value, location = 'target')=>{
     if (!TARGETS.has(target)) throw new Error(`${location} must be one of: ${MICROVERTICAL_RELEASE_TARGETS.join(', ')}.`);
     return target;
 };
+const assertEnvelopeKind = (value)=>{
+    if (value !== MICROVERTICAL_RELEASE_ENVELOPE_KIND && value !== SHELL_RELEASE_ENVELOPE_KIND) throw new Error(`envelope.kind must be "${MICROVERTICAL_RELEASE_ENVELOPE_KIND}" or "${SHELL_RELEASE_ENVELOPE_KIND}".`);
+    return value;
+};
 const assertReleaseIdentity = (value, location = 'identity')=>{
     const identity = assertRecord(value, location);
     assertExactKeys(identity, [
@@ -184,7 +189,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
@@ -193,26 +198,51 @@ const assertSurfacePaths = (value, location)=>{
     if (new Set(paths).size !== paths.length) throw new Error(`${location} must not contain duplicate artifact paths.`);
     return paths;
 };
-const assertSurfaces = (value)=>{
+const assertSurfaces = (value, kind)=>{
     const surfaces = assertRecord(value, 'surfaces');
     assertExactKeys(surfaces, [
         'uiClient',
         'ssr',
         'apiBackend',
-        'backendFederation'
+        ...kind !== SHELL_RELEASE_ENVELOPE_KIND && Object.hasOwn(surfaces, 'backendFederation') ? [
+            'backendFederation'
+        ] : []
     ], 'surfaces');
-    const backendFederation = assertRecord(surfaces.backendFederation, 'surfaces.backendFederation');
-    assertExactKeys(backendFederation, [
+    const backendFederation = Object.hasOwn(surfaces, 'backendFederation') ? assertRecord(surfaces.backendFederation, 'surfaces.backendFederation') : void 0;
+    if (backendFederation) assertExactKeys(backendFederation, [
         '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 && (backendFederation || 0 === uiClient.length)) throw new Error('surfaces.apiBackend must contain at least one artifact path.');
+    if (kind === SHELL_RELEASE_ENVELOPE_KIND) {
+        if (0 === uiClient.length || 0 === ssr.length) throw new Error('Shell surfaces.uiClient and surfaces.ssr must each contain at least one artifact path.');
+        return {
+            kind,
+            surfaces: {
+                uiClient,
+                ssr,
+                apiBackend
+            }
+        };
+    }
+    if (apiBackend.length > 0 && !backendFederation) throw new Error('surfaces.backendFederation is required when API/backend is declared.');
     return {
-        uiClient: assertSurfacePaths(surfaces.uiClient, 'surfaces.uiClient'),
-        ssr: assertSurfacePaths(surfaces.ssr, 'surfaces.ssr'),
-        apiBackend: assertSurfacePaths(surfaces.apiBackend, 'surfaces.apiBackend'),
-        backendFederation: {
-            manifest: assertNormalizedLogicalPath(backendFederation.manifest, 'surfaces.backendFederation.manifest'),
-            container: assertNormalizedLogicalPath(backendFederation.container, 'surfaces.backendFederation.container')
+        kind,
+        surfaces: {
+            uiClient,
+            ssr,
+            apiBackend,
+            ...backendFederation ? {
+                backendFederation: {
+                    manifest: assertNormalizedLogicalPath(backendFederation.manifest, 'surfaces.backendFederation.manifest'),
+                    container: assertNormalizedLogicalPath(backendFederation.container, 'surfaces.backendFederation.container')
+                }
+            } : {}
         }
     };
 };
@@ -222,12 +252,14 @@ const assertSurfaceReferences = (artifacts, surfaces)=>{
         uiClient: surfaces.uiClient,
         ssr: surfaces.ssr,
         apiBackend: surfaces.apiBackend,
-        'backendFederation.manifest': [
-            surfaces.backendFederation.manifest
-        ],
-        'backendFederation.container': [
-            surfaces.backendFederation.container
-        ]
+        ...'backendFederation' in surfaces && surfaces.backendFederation ? {
+            'backendFederation.manifest': [
+                surfaces.backendFederation.manifest
+            ],
+            'backendFederation.container': [
+                surfaces.backendFederation.container
+            ]
+        } : {}
     }))for (const logicalPath of paths)if (!artifactPaths.has(logicalPath)) throw new Error(`surfaces.${surface} references unbound artifact "${logicalPath}".`);
 };
 const assertTargetSurfaceContract = (target, artifacts, surfaces)=>{
@@ -245,12 +277,14 @@ const assertTargetSurfaceContract = (target, artifacts, surfaces)=>{
     assertRuntime(surfaces.uiClient, 'browser', 'UI/client');
     assertRuntime(surfaces.ssr, 'node' === target ? 'nodejs' : 'workerd', 'SSR');
     assertRuntime(surfaces.apiBackend, 'node' === target ? 'nodejs' : 'workerd-effect', 'API/backend');
-    assertRuntime([
-        surfaces.backendFederation.manifest
-    ], 'module-federation-manifest', 'backend federation manifest');
-    assertRuntime([
-        surfaces.backendFederation.container
-    ], 'node' === target ? 'nodejs' : 'commonjs-module', 'backend federation container');
+    if ('backendFederation' in surfaces && surfaces.backendFederation) {
+        assertRuntime([
+            surfaces.backendFederation.manifest
+        ], 'module-federation-manifest', 'backend federation manifest');
+        assertRuntime([
+            surfaces.backendFederation.container
+        ], 'node' === target ? 'nodejs' : 'commonjs-module', 'backend federation container');
+    }
 };
 const deepFreeze = (value)=>{
     if (null !== value && 'object' == typeof value && !Object.isFrozen(value)) {
@@ -259,6 +293,51 @@ const deepFreeze = (value)=>{
     }
     return value;
 };
+const assertReleaseUi = (value, identity, surfaces)=>{
+    if (0 === surfaces.uiClient.length) {
+        if (void 0 !== value) throw new Error('envelope.ui is forbidden for an API-only release.');
+        return;
+    }
+    const ui = assertRecord(value, 'envelope.ui');
+    assertExactKeys(ui, [
+        'rendererIdentity',
+        'rendererProfile',
+        'routerBindings'
+    ], 'envelope.ui');
+    const routerBindings = assertRecord(ui.routerBindings, 'envelope.ui.routerBindings');
+    const errors = [
+        ...validateRendererIdentity(ui.rendererIdentity, 'envelope.ui.rendererIdentity').errors,
+        ...validateRendererProfile(ui.rendererProfile, 'envelope.ui.rendererProfile').errors,
+        ...validateRendererRouterBindings(routerBindings, Object.keys(routerBindings), 'envelope.ui.routerBindings').errors
+    ];
+    if (errors.length > 0) throw new Error(formatBackendFederationValidationErrors(errors));
+    const rendererIdentity = ui.rendererIdentity;
+    const rendererProfile = ui.rendererProfile;
+    if (!Object.hasOwn(routerBindings, rendererIdentity.entryName)) throw new Error('envelope.ui.routerBindings must include the primary rendererIdentity.entryName.');
+    if (rendererIdentity.buildId !== identity.buildMarker) throw new Error('envelope.ui.rendererIdentity.buildId must match identity.buildMarker.');
+    for (const field of [
+        'renderer',
+        'protocolVersion'
+    ])if (rendererIdentity[field] !== rendererProfile[field]) throw new Error(`envelope.ui.rendererProfile.${field} must match rendererIdentity.${field}.`);
+    return {
+        rendererIdentity: {
+            ...rendererIdentity
+        },
+        rendererProfile: {
+            ...rendererProfile,
+            compiler: {
+                ...rendererProfile.compiler
+            },
+            hydration: {
+                ...rendererProfile.hydration
+            },
+            router: {
+                ...rendererProfile.router
+            }
+        },
+        routerBindings: immutableRendererRouterBindings(routerBindings)
+    };
+};
 const assertEnvelope = (value)=>{
     const envelope = assertRecord(value, 'envelope');
     assertExactKeys(envelope, [
@@ -266,26 +345,35 @@ const assertEnvelope = (value)=>{
         'kind',
         'target',
         'identity',
+        ...Object.hasOwn(envelope, 'ui') ? [
+            'ui'
+        ] : [],
         'artifacts',
         'surfaces',
         'envelopeDigest'
     ], 'envelope');
     if (envelope.schemaVersion !== MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION) throw new Error(`envelope.schemaVersion must be ${MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION}.`);
-    if (envelope.kind !== MICROVERTICAL_RELEASE_ENVELOPE_KIND) throw new Error(`envelope.kind must be "${MICROVERTICAL_RELEASE_ENVELOPE_KIND}".`);
+    const kind = assertEnvelopeKind(envelope.kind);
     if (!Array.isArray(envelope.artifacts) || 0 === envelope.artifacts.length) throw new Error('envelope.artifacts must contain at least one artifact.');
     const artifacts = envelope.artifacts.map((artifact, index)=>assertReleaseArtifact(artifact, `envelope.artifacts[${index}]`));
     assertUniqueSortedArtifacts(artifacts, 'envelope.artifacts');
     const target = assertTarget(envelope.target, 'envelope.target');
-    const surfaces = assertSurfaces(envelope.surfaces);
+    const releaseSurfaces = assertSurfaces(envelope.surfaces, kind);
+    const { surfaces } = releaseSurfaces;
+    if (0 === surfaces.uiClient.length && Object.hasOwn(envelope, 'ui')) throw new Error('envelope.ui is forbidden for an API-only release.');
     assertSurfaceReferences(artifacts, surfaces);
     assertTargetSurfaceContract(target, artifacts, surfaces);
+    const identity = assertReleaseIdentity(envelope.identity, 'envelope.identity');
+    const ui = assertReleaseUi(envelope.ui, identity, surfaces);
     const parsed = {
+        ...releaseSurfaces,
         schemaVersion: MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION,
-        kind: MICROVERTICAL_RELEASE_ENVELOPE_KIND,
         target,
-        identity: assertReleaseIdentity(envelope.identity, 'envelope.identity'),
+        identity,
+        ...ui ? {
+            ui
+        } : {},
         artifacts,
-        surfaces,
         envelopeDigest: assertNonEmptyString(envelope.envelopeDigest, 'envelope.envelopeDigest')
     };
     if (!SHA256_PATTERN.test(parsed.envelopeDigest)) throw new Error('envelope.envelopeDigest must be a lowercase SHA-256 digest.');
@@ -293,36 +381,59 @@ const assertEnvelope = (value)=>{
     if (parsed.envelopeDigest !== expectedDigest) throw new Error('envelope.envelopeDigest does not match canonical payload.');
     return parsed;
 };
-const createMicroVerticalReleaseEnvelope = async (input)=>{
+async function createMicroVerticalReleaseEnvelope(input) {
     const artifactRoot = await promises.realpath(node_path.resolve(input.artifactRoot));
     const target = assertTarget(input.target);
     const identity = assertReleaseIdentity(input.identity);
+    const kind = assertEnvelopeKind(void 0 === input.kind ? MICROVERTICAL_RELEASE_ENVELOPE_KIND : input.kind);
     if (!Array.isArray(input.artifacts) || 0 === input.artifacts.length) throw new Error('artifacts must contain at least one artifact.');
     const inputs = input.artifacts.map((artifact, index)=>assertArtifactInput(artifact, `artifacts[${index}]`));
     const sortedInputs = [
         ...inputs
     ].sort((left, right)=>left.logicalPath.localeCompare(right.logicalPath));
     assertUniqueSortedArtifacts(sortedInputs, 'artifacts');
-    const surfaces = assertSurfaces(input.surfaces);
+    const releaseSurfaces = assertSurfaces(input.surfaces, kind);
+    const { surfaces } = releaseSurfaces;
+    if (0 === surfaces.uiClient.length && Object.hasOwn(input, 'ui')) throw new Error('envelope.ui is forbidden for an API-only release.');
     assertSurfaceReferences(sortedInputs, surfaces);
     assertTargetSurfaceContract(target, sortedInputs, surfaces);
+    const ui = assertReleaseUi(input.ui, identity, surfaces);
     const artifacts = await Promise.all(sortedInputs.map((artifact)=>readFinalArtifact(artifactRoot, artifact)));
     assertTargetSurfaceContract(target, artifacts, surfaces);
     const payload = {
+        ...releaseSurfaces,
         schemaVersion: MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION,
-        kind: MICROVERTICAL_RELEASE_ENVELOPE_KIND,
         target,
         identity,
-        artifacts,
-        surfaces
+        ...ui ? {
+            ui
+        } : {},
+        artifacts
     };
     return deepFreeze({
         ...payload,
         envelopeDigest: digestMicroVerticalReleaseEnvelopePayload(payload)
     });
-};
-const verifyMicroVerticalReleaseEnvelope = async (value, options)=>{
+}
+async function verifyMicroVerticalReleaseEnvelope(value, options) {
     const envelope = assertEnvelope(value);
+    if (void 0 !== options.expectedRendererProfile) {
+        const result = validateRendererProfileCompatibility(options.expectedRendererProfile, envelope.ui?.rendererProfile, 'envelope.ui.rendererProfile');
+        if (!result.ok) throw new Error(formatBackendFederationValidationErrors(result.errors));
+    }
+    if (void 0 !== options.expectedRendererIdentity) {
+        const expected = options.expectedRendererIdentity;
+        const result = validateRendererIdentity(expected, 'expectedRendererIdentity');
+        if (!result.ok) throw new Error(formatBackendFederationValidationErrors(result.errors));
+        for (const field of [
+            'renderer',
+            'protocolVersion',
+            'appId',
+            'entryName',
+            'buildId'
+        ])if (envelope.ui?.rendererIdentity[field] !== expected[field]) throw new Error(`envelope.ui.rendererIdentity.${field} must match the consuming renderer identity.`);
+    }
+    if (void 0 !== options.expectedKind && envelope.kind !== options.expectedKind) throw new Error(`envelope.kind must be "${options.expectedKind}" for this release owner; received "${envelope.kind}".`);
     if (void 0 !== options.expectedTarget && envelope.target !== options.expectedTarget) throw new Error(`envelope.target must be "${options.expectedTarget}" for this staging target; received "${envelope.target}".`);
     const artifactRoot = await promises.realpath(node_path.resolve(options.artifactRoot));
     for (const artifact of envelope.artifacts){
@@ -331,5 +442,5 @@ const verifyMicroVerticalReleaseEnvelope = async (value, options)=>{
         if (!matches) throw new Error('file' === artifact.kind && 'file' === finalArtifact.kind ? `Artifact "${artifact.logicalPath}" digest does not match final artifact bytes.` : `Artifact "${artifact.logicalPath}" does not match its final filesystem binding.`);
     }
     return deepFreeze(envelope);
-};
-export { MICROVERTICAL_RELEASE_ENVELOPE_KIND, MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION, MICROVERTICAL_RELEASE_TARGETS, canonicalSerializeMicroVerticalReleaseEnvelope, createMicroVerticalReleaseEnvelope, verifyMicroVerticalReleaseEnvelope };
+}
+export { MICROVERTICAL_RELEASE_ENVELOPE_KIND, MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION, MICROVERTICAL_RELEASE_TARGETS, SHELL_RELEASE_ENVELOPE_KIND, canonicalSerializeMicroVerticalReleaseEnvelope, createMicroVerticalReleaseEnvelope, verifyMicroVerticalReleaseEnvelope };

package/dist/esm/release-envelope/plugin.mjs

@@ -1,48 +1,57 @@
 import node_path from "node:path";
+import { NODE_PUBLIC_ASSET_SCOPE, normalizeDeclaredPublicAssets, resolveAddedDeclaredPublicAssetPaths } from "../deploy-output/public-assets.mjs";
+import { getDeployingTarget } from "../deploy-output/target.mjs";
 import { emitFrameworkMicroVerticalReleaseEnvelope, emitNodeStagedReleaseEnvelope, verifyBuildOutputReleaseEnvelope, verifyNodeReleaseEnvelopeStaging } from "./framework-output.mjs";
-const resolveActiveDeployTarget = (api, resolveDeployTarget)=>{
-    const { metaName } = api.getAppContext();
-    const config = api.getNormalizedConfig();
-    if ('modern-js' !== metaName && !config.deploy?.target && !process.env.MODERNJS_DEPLOY) return;
-    return resolveDeployTarget(config);
-};
-const createUltramodernReleaseEnvelopePlugin = ({ resolveDeployTarget })=>({
+const createUltramodernReleaseEnvelopePlugin = ({ resolveRendererProfile } = {})=>({
         name: '@modern-js/ultramodern-release-envelope',
         pre: [
             '@modern-js/backend-federation-build',
             '@modern-js/plugin-bff',
-            '@modern-js/deploy-output-aliases'
+            '@modern-js/deploy-output-aliases',
+            '@modern-js/deploy-output-public-assets'
         ],
         post: [
             '@modern-js/plugin-deploy'
         ],
         setup (api) {
-            const emitBuildEnvelope = async (target)=>{
-                const { apiOnly, distDirectory } = api.getAppContext();
+            const emitBuildEnvelope = async (target, requirePromotable = true)=>{
+                const { apiOnly, appDirectory, distDirectory } = api.getAppContext();
                 await emitFrameworkMicroVerticalReleaseEnvelope({
                     apiOnly,
+                    appDirectory,
                     distDirectory,
-                    target
+                    role: api.getNormalizedConfig().deploy?.releaseEnvelopeRole,
+                    requirePromotable,
+                    target,
+                    ...!apiOnly && resolveRendererProfile ? {
+                        expectedRendererProfile: resolveRendererProfile(api.getNormalizedConfig())
+                    } : {}
                 });
             };
             api.onAfterBuild(async ()=>{
-                const configuredTarget = resolveDeployTarget(api.getNormalizedConfig());
+                const configuredTarget = api.getAppContext().deployTarget?.target;
                 if ('node' !== configuredTarget && 'cloudflare' !== configuredTarget) return;
-                await emitBuildEnvelope(configuredTarget);
+                await emitBuildEnvelope(configuredTarget, false);
             });
             api.onBeforeDeploy(async ()=>{
-                const configuredTarget = resolveActiveDeployTarget(api, resolveDeployTarget);
+                const configuredTarget = getDeployingTarget(api.getAppContext());
                 if ('node' !== configuredTarget) return;
                 await emitBuildEnvelope(configuredTarget);
                 const { distDirectory } = api.getAppContext();
                 await verifyBuildOutputReleaseEnvelope(distDirectory, configuredTarget);
             });
             api.onAfterDeploy(async ()=>{
-                const configuredTarget = resolveActiveDeployTarget(api, resolveDeployTarget);
+                const configuredTarget = getDeployingTarget(api.getAppContext());
                 if ('node' !== configuredTarget) return;
                 const { appDirectory, distDirectory } = api.getAppContext();
                 const outputDirectory = node_path.join(appDirectory, '.output');
                 const releaseEnvelope = await emitNodeStagedReleaseEnvelope({
+                    declaredPublicAssets: await resolveAddedDeclaredPublicAssetPaths({
+                        appDirectory,
+                        assets: normalizeDeclaredPublicAssets(api.getNormalizedConfig().deploy?.node?.publicAssets, NODE_PUBLIC_ASSET_SCOPE),
+                        generatedRoot: distDirectory,
+                        scope: NODE_PUBLIC_ASSET_SCOPE
+                    }),
                     distDirectory,
                     outputDirectory
                 });

package/dist/esm/release-envelope/renderer-output-stamp.mjs

@@ -0,0 +1,112 @@
+import { randomUUID } from "node:crypto";
+import promises from "node:fs/promises";
+import node_path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { ULTRAMODERN_BUILD_ARTIFACT_FILE, ULTRAMODERN_BUILD_ARTIFACT_PATH, assertUltramodernBuildArtifact, formatBackendFederationValidationErrors, stampUltramodernBuildArtifactIdentity, validateRendererIdentity, validateRendererProfile, validateRendererRouterBindings } from "@modern-js/backend-federation-contracts";
+const validateFinalizedRendererBuild = (output, context, appId)=>{
+    const entryNames = context.entrypoints.map((entry)=>entry.entryName);
+    const primary = context.entrypoints.find((entry)=>entry.isMainEntry) ?? context.entrypoints[0];
+    const errors = [
+        ...validateRendererIdentity(output.ui.rendererIdentity).errors,
+        ...validateRendererProfile(output.ui.rendererProfile).errors,
+        ...validateRendererRouterBindings(output.ui.routerBindings, entryNames, 'routerBindings').errors
+    ];
+    if (errors.length) throw new Error(formatBackendFederationValidationErrors(errors));
+    if (!primary || new Set(entryNames).size !== entryNames.length || context.entrypoints.filter((entry)=>entry.isMainEntry).length > 1 || output.ui.rendererIdentity.entryName !== primary.entryName || output.ui.rendererIdentity.appId !== appId || output.ui.rendererIdentity.buildId !== output.buildMarker || output.ui.rendererIdentity.renderer !== output.ui.rendererProfile.renderer) throw new Error('Finalized renderer output conflicts with the actual application entries and release identity.');
+};
+const stampFinalizedRendererBuildArtifact = (artifact, output, context)=>{
+    assertUltramodernBuildArtifact(artifact);
+    const ui = artifact.surfaces.ui;
+    if (!ui) throw new Error('Finalized renderer output requires a declared UI artifact');
+    validateFinalizedRendererBuild(output, context, artifact.deliveryUnit.appId);
+    const drifted = [
+        !isDeepStrictEqual({
+            ...ui.rendererIdentity,
+            buildId: output.ui.rendererIdentity.buildId
+        }, output.ui.rendererIdentity) && `rendererIdentity (captured entry ${ui.rendererIdentity.entryName}, built entry ${output.ui.rendererIdentity.entryName})`,
+        !isDeepStrictEqual(ui.rendererProfile, output.ui.rendererProfile) && 'rendererProfile',
+        !isDeepStrictEqual(ui.routerBindings, output.ui.routerBindings) && `routerBindings (captured entries ${Object.keys(ui.routerBindings).join(', ')}, built entries ${Object.keys(output.ui.routerBindings).join(', ')})`
+    ].filter(Boolean);
+    if (drifted.length) throw new Error(`Finalized renderer output conflicts with the captured application profile or router bindings: ${drifted.join('; ')} differ from ${ULTRAMODERN_BUILD_ARTIFACT_PATH}. After changing modern.config entries, renderer or router, recapture it with \`ultramodern-create ultramodern sync-delivery-unit\`.`);
+    const identity = {
+        buildMarker: output.buildMarker,
+        sourceRevision: output.sourceRevision
+    };
+    const stamped = stampUltramodernBuildArtifactIdentity(artifact, identity);
+    return stampUltramodernBuildArtifactIdentity({
+        ...stamped,
+        surfaces: {
+            ...stamped.surfaces,
+            ui: {
+                ...stamped.surfaces.ui,
+                ...output.ui
+            }
+        }
+    }, identity);
+};
+async function writeOwnedArtifact(file, bytes) {
+    await promises.mkdir(node_path.dirname(file), {
+        recursive: true
+    });
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    let created = false;
+    try {
+        const handle = await promises.open(temporary, 'wx');
+        created = true;
+        try {
+            await handle.writeFile(bytes);
+        } finally{
+            await handle.close();
+        }
+        await promises.rename(temporary, file);
+    } finally{
+        if (created) await promises.rm(temporary, {
+            force: true
+        });
+    }
+}
+async function emitRendererBuildArtifact(context, options) {
+    const source = node_path.join(context.appDirectory, ULTRAMODERN_BUILD_ARTIFACT_PATH);
+    const bytes = await promises.readFile(source).catch((error)=>{
+        if ('ENOENT' === error.code) return;
+        throw error;
+    });
+    if (!bytes) {
+        const declaration = await promises.stat(source.replace(/\.json$/u, '.ts')).catch((error)=>{
+            if ('ENOENT' === error.code) return;
+            throw error;
+        });
+        if (declaration) throw new Error('Generated UI artifact declaration is missing its build carrier');
+        return;
+    }
+    const artifact = JSON.parse(bytes.toString('utf8'));
+    assertUltramodernBuildArtifact(artifact);
+    const finalized = await options.resolveRendererBuild(context);
+    const stamped = stampFinalizedRendererBuildArtifact(artifact, finalized, context);
+    const serialized = `${JSON.stringify(stamped, null, 2)}\n`;
+    for (const directory of [
+        context.distDirectory,
+        node_path.join(context.distDirectory, 'public')
+    ])await writeOwnedArtifact(node_path.join(directory, ULTRAMODERN_BUILD_ARTIFACT_FILE), serialized);
+    return stamped;
+}
+function rendererBuildArtifactStampPlugin(options) {
+    if ('string' != typeof options.rendererBuildPlugin || !options.rendererBuildPlugin || options.rendererBuildPlugin.trim() !== options.rendererBuildPlugin || 'function' != typeof options.resolveRendererBuild) throw new Error('Renderer artifact stamping requires its owning metadata producer');
+    return {
+        name: '@modern-js/renderer-build-artifact-stamp',
+        pre: [
+            options.rendererBuildPlugin
+        ],
+        required: [
+            options.rendererBuildPlugin
+        ],
+        setup (api) {
+            api.onAfterBuild(async ()=>{
+                const context = api.getAppContext();
+                if (context.apiOnly) return;
+                await emitRendererBuildArtifact(context, options);
+            });
+        }
+    };
+}
+export { emitRendererBuildArtifact, rendererBuildArtifactStampPlugin, stampFinalizedRendererBuildArtifact, validateFinalizedRendererBuild };

package/dist/esm/release-envelope/types.mjs

@@ -1,7 +1,6 @@
-const MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION = 3;
-const MICROVERTICAL_RELEASE_ENVELOPE_KIND = 'ultramodern-target-microvertical-release-envelope';
 const MICROVERTICAL_RELEASE_TARGETS = [
     'node',
     'cloudflare'
 ];
-export { MICROVERTICAL_RELEASE_ENVELOPE_KIND, MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION, MICROVERTICAL_RELEASE_TARGETS };
+export { MICROVERTICAL_RELEASE_ENVELOPE_KIND, MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION, SHELL_RELEASE_ENVELOPE_KIND } from "./contract.mjs";
+export { MICROVERTICAL_RELEASE_TARGETS };

package/dist/esm/release-identity.mjs

@@ -1,12 +1,15 @@
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
+const invokeGit = execFileSync;
 const BUILD_MARKER_NAMESPACE = 'ultramodern-delivery-unit-release-build-marker:v1';
 const PROMOTABLE_SOURCE_REVISION_PATTERN = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u;
+const workspaceGitEnv = ()=>Object.fromEntries(Object.entries(process.env).filter(([name])=>!name.toUpperCase().startsWith('GIT_')));
 const gitOutput = (workspaceRoot, args)=>{
     try {
-        return execFileSync('git', args, {
+        return invokeGit('git', args, {
             cwd: workspaceRoot,
             encoding: 'utf8',
+            env: workspaceGitEnv(),
             stdio: [
                 'ignore',
                 'pipe',
@@ -18,9 +21,9 @@ const gitOutput = (workspaceRoot, args)=>{
     }
 };
 const createUltramodernReleaseBuildMarker = ({ generationBuildMarker, sourceRevision, unitId })=>createHash('sha256').update(`${BUILD_MARKER_NAMESPACE}:${unitId}:${generationBuildMarker}:${sourceRevision}`).digest('hex').slice(0, 16);
-const resolveUltramodernSourceRevision = (workspaceRoot = process.cwd(), configuredSourceRevision)=>{
+const resolveUltramodernSourceRevision = (workspaceRoot = process.cwd(), configuredSourceRevision, environment = process.env)=>{
     const configuredArgumentValue = configuredSourceRevision?.trim();
-    const configuredEnvironmentValue = process.env.ULTRAMODERN_SOURCE_REVISION?.trim();
+    const configuredEnvironmentValue = environment.ULTRAMODERN_SOURCE_REVISION?.trim();
     const configuredArgument = configuredArgumentValue && 'workspace' !== configuredArgumentValue ? configuredArgumentValue : void 0;
     const configuredEnvironment = configuredEnvironmentValue && 'workspace' !== configuredEnvironmentValue ? configuredEnvironmentValue : void 0;
     if (configuredArgument && configuredEnvironment && configuredArgument !== configuredEnvironment) throw new Error(`Configured source revision ${configuredArgument} does not match environment source revision ${configuredEnvironment}.`);
@@ -48,9 +51,9 @@ const resolveUltramodernSourceRevision = (workspaceRoot = process.cwd(), configu
     if (configured && configured !== revision) throw new Error(`Configured source revision ${configured} does not match clean Git HEAD ${revision}.`);
     return revision;
 };
-const resolveUltramodernReleaseIdentity = ({ generationBuildMarker, sourceRevision: configuredSourceRevision, unitId, workspaceRoot })=>{
+const resolveUltramodernReleaseIdentity = ({ generationBuildMarker, sourceRevision: configuredSourceRevision, unitId, workspaceRoot, environment })=>{
     const explicitSourceRevision = configuredSourceRevision?.trim();
-    const sourceRevision = resolveUltramodernSourceRevision(workspaceRoot, explicitSourceRevision);
+    const sourceRevision = resolveUltramodernSourceRevision(workspaceRoot, explicitSourceRevision, environment);
     return {
         buildMarker: 'workspace' === sourceRevision ? generationBuildMarker : createUltramodernReleaseBuildMarker({
             generationBuildMarker,

package/dist/esm/renderer-build-identity.mjs

@@ -0,0 +1,82 @@
+import { createHash, randomUUID } from "node:crypto";
+import node_fs from "node:fs";
+import node_path from "node:path";
+import { immutableRendererRouterBindings, validateRendererProfile, validateRendererRouterBindings } from "@modern-js/backend-federation-contracts";
+import { resolveUltramodernSourceRevision } from "./release-identity.mjs";
+const LOCKFILES = [
+    'pnpm-lock.yaml',
+    'package-lock.json',
+    'yarn.lock',
+    'bun.lock',
+    'bun.lockb'
+];
+const processNonce = randomUUID();
+const sha256 = (value)=>createHash('sha256').update(value).digest('hex');
+function rendererProfileKey(profile) {
+    return sha256(JSON.stringify([
+        profile.renderer,
+        profile.protocolVersion,
+        profile.compiler,
+        profile.hydration,
+        profile.router,
+        Object.entries(profile.dependencies ?? {}).sort(([left], [right])=>left < right ? -1 : left > right ? 1 : 0)
+    ]));
+}
+function lockfileHash(projectRoot) {
+    let directory = node_path.resolve(projectRoot);
+    for(;;){
+        for (const name of LOCKFILES)try {
+            return sha256(node_fs.readFileSync(node_path.join(directory, name)));
+        } catch (error) {
+            if ('ENOENT' !== error.code) throw error;
+        }
+        const parent = node_path.dirname(directory);
+        if (parent === directory) return '';
+        directory = parent;
+    }
+}
+function resolveRendererBuildIdentities(options) {
+    const profile = {
+        renderer: options.profile.renderer,
+        protocolVersion: options.profile.protocolVersion,
+        compiler: options.profile.compiler,
+        hydration: options.profile.hydration,
+        router: options.profile.router
+    };
+    const validation = validateRendererProfile(profile);
+    if (!validation.ok || options.renderer !== profile.renderer) throw new Error(`Renderer/profile identity mismatch: ${JSON.stringify(validation.errors)}.`);
+    const entries = [
+        ...options.entryNames
+    ].sort();
+    if (0 === entries.length || new Set(entries).size !== entries.length || entries.some((value)=>!value || '__proto__' === value)) throw new Error('Renderer build identity requires unique nonempty entry names.');
+    const routerValidation = validateRendererRouterBindings(options.routerBindings, entries, 'routerBindings', options.routerFrameworks);
+    if (!routerValidation.ok) throw new Error(`Invalid renderer router bindings: ${JSON.stringify(routerValidation.errors)}.`);
+    const projectRoot = node_path.resolve(options.projectRoot);
+    const appId = options.appId ?? JSON.parse(node_fs.readFileSync(node_path.join(projectRoot, 'package.json'), 'utf8')).name;
+    if ('string' != typeof appId || !appId || appId.trim() !== appId) throw new Error('Renderer application identity requires a delivery artifact appId or a package name.');
+    const profileKey = rendererProfileKey(options.profile);
+    const sourceRevision = resolveUltramodernSourceRevision(projectRoot, options.sourceRevision);
+    const buildId = sha256(JSON.stringify([
+        profileKey,
+        lockfileHash(projectRoot),
+        'development' === options.mode || 'workspace' === sourceRevision ? processNonce : sourceRevision
+    ]));
+    const identities = Object.fromEntries(entries.map((entryName)=>[
+            entryName,
+            Object.freeze({
+                renderer: options.renderer,
+                appId,
+                entryName,
+                protocolVersion: 1,
+                buildId
+            })
+        ]));
+    return Object.freeze({
+        identities: Object.freeze(identities),
+        buildId,
+        profileKey,
+        sourceRevision,
+        routerBindings: immutableRendererRouterBindings(options.routerBindings)
+    });
+}
+export { rendererProfileKey, resolveRendererBuildIdentities };