fix(runtime): loadArtifactBundle forward-converts the loaded artifact once, before mergeRuntimeModule and every reader

An option-B artifact built before a retirement was refused by the runtime's
first reader of packages[] (createStandaloneStack, through
resolveArtifactCollections), before the metadata door's own conversion ran.
The loader now runs applyArtifactForwardConversions once on the loaded bundle,
so every runtime reader sees the converted package bodies. The AppPlugin
comment that said no conversion reaches the bodies is corrected.

Claude-Session: https://claude.ai/code/session_01ADzJtzYTLUfgrRZHxkagkX
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

packages/runtime/src/app-plugin.ts

@@ -498,11 +498,13 @@ export class AppPlugin implements Plugin {
         // served the artifact door's converted copy of it, and what handed the
         // email loader a template it refuses to send.
         //
-        // A bundle carrying `packages[]` is handed over as authored, as before:
-        // the `manifest` service registers its package BODIES, which no
-        // conversion reaches (the ADR-0087 pass walks the definition's own
-        // collections, at the artifact door too), and `forwardConverted` would
-        // resolve `packages[]` here, ahead of the `manifest` service (#15292).
+        // A bundle carrying `packages[]` is handed over as it arrived, as before:
+        // `forwardConverted` would resolve `packages[]` here, ahead of the
+        // `manifest` service (#15292). Its package BODIES are already converted
+        // when the bundle came through `loadArtifactBundle`, which runs the
+        // ADR-0087 pass once over every body at load (#23027); a bundle handed
+        // to this plugin by any other route reaches the `manifest` service as
+        // authored.
         const servicePayload = (this.bundle as { packages?: unknown }).packages === undefined
             ? this.forwardConverted(ctx).definition
             : this.bundle.manifest

packages/runtime/src/load-artifact-bundle.ts

@@ -30,8 +30,51 @@ import { readFile } from 'node:fs/promises';
 import { resolve as resolvePath, isAbsolute, dirname } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
+import { applyArtifactForwardConversions } from '@objectstack/metadata-core';
+
 import { resolveArtifactCollections } from './artifact-collections.js';
 
+/**
+ * The ADR-0087 D2 forward conversion at the runtime's artifact load (#23027):
+ * one call of `applyArtifactForwardConversions`, under the window the artifact's
+ * own `engines.protocol` opens, over the definition and every
+ * `packages[i].manifest` body.
+ *
+ * A loaded artifact is data at rest. Every runtime reader of a multi-package
+ * one parses each package body strictly: `resolveArtifactPackageOrder` gates
+ * each entry, reached through `resolveArtifactCollections`
+ * (`createStandaloneStack`'s surfaced stack, `AppPlugin`'s `collections`,
+ * `mergeRuntimeModule`) and through the `manifest` service's `register()`. So
+ * an artifact built before a retirement was refused by the first of those
+ * readers, before the metadata door's own conversion could run. Converting the
+ * bundle once, where it is read from disk, gives every reader the same
+ * converted bytes. ⛔ Never a conversion per reader: that is N copies of one
+ * policy, and the readers could then disagree about which artifacts load.
+ *
+ * The one other place on the boot path that reads an artifact FILE,
+ * `readConfigDeclaredDefault` (`resolve-project-database.ts`), calls this same
+ * function on what it read.
+ *
+ * Silent by design. On an artifact boot `createStandaloneStack` composes
+ * `MetadataPlugin` with `artifactSource` naming this same file, and its door
+ * converts the raw file again and prints the one operator summary per
+ * conversion. A line here as well would name each conversion twice per boot.
+ * Converting before the protocol handshake changes no verdict: the handshake
+ * reads `manifest.engines`, which no conversion rewrites.
+ *
+ * An envelope that was not unwrapped (`{ schemaVersion, metadata }`) has its
+ * `metadata` converted, the position the metadata door converts. Copy-on-write:
+ * the input comes back by reference when nothing converted.
+ */
+export function convertArtifactAtLoad(bundle: any): any {
+    if (bundle === null || typeof bundle !== 'object' || Array.isArray(bundle)) return bundle;
+    if (bundle.schemaVersion != null && bundle.metadata !== undefined) {
+        const metadata = applyArtifactForwardConversions(bundle.metadata).definition;
+        return metadata === bundle.metadata ? bundle : { ...bundle, metadata };
+    }
+    return applyArtifactForwardConversions(bundle).definition;
+}
+
 export interface LoadArtifactBundleOptions {
     /** Optional log tag for warnings (defaults to `[loadArtifactBundle]`). */
     tag?: string;
@@ -128,6 +171,10 @@ export async function loadArtifactBundle(
         return null;
     }
 
+    // [#23027] Converted HERE, once, before `mergeRuntimeModule` and before any
+    // reader is handed the bundle — see `convertArtifactAtLoad`.
+    bundle = convertArtifactAtLoad(bundle);
+
     if (isUrl) {
         // Remote artifacts cannot dynamic-import a sibling ESM runtime module
         // safely (Node does not allow importing arbitrary URLs and we never