@stardeck-customer-apps/compose 0.13.0 → 0.14.0

package/SKILL.md

@@ -12,7 +12,9 @@ Compose turns that declaration into the code Next.js actually builds:
 - `apps/web/src/modules.gen.ts` — the Module registry, `isModuleEnabled` and `isMountHeadless`
 - `apps/web/src/module-contributions.gen.ts`
 - `apps/web/src/module-i18n.gen.ts`
-- `apps/web/src/module-init.server.gen.ts`
+- `apps/web/src/module-init.server.gen.ts` — memoized `initializeActiveEnhancements()`:
+  each enabled Module's root `initializeModule`, then each active slice's
+  `initializeEnhancement`
 - `apps/web/src/module-datastores.gen.ts`
 - `apps/web/src/module-server.gen.ts` — `MODULE_SERVER_REGISTRATIONS`, one entry
   per composed Module that ships `server/registrations.ts`
@@ -149,6 +151,38 @@ a silent fallback. It holds deployment facts: gitignore it (`apps/web/.gitignore
   the bundle. Compose does not check the export names or shapes. The file
   counts as `server/**/*.ts`, so the Module also needs `server/index.ts`.
   Needs compose 0.8.0 or later.
+- **Module initializers.** Server registrations a Module makes into shared
+  registries (observers, resolvers, facets, drains) go in a root
+  `initialize.server.ts`, any Module kind:
+
+  ```ts
+  // src/modules/guest-ordering/initialize.server.ts — server-only, idempotent
+  import { registerPosCloseObserver } from "@/modules/pos/server";
+
+  import { wakeReconcileForClosedOrder } from "./server/reconcile";
+
+  export async function initializeModule() {
+    registerPosCloseObserver(wakeReconcileForClosedOrder);
+  }
+  ```
+
+  `initializeModule` must be a direct named function declaration callable with
+  zero required arguments (no arrow function, default export, re-export or
+  generator); compose fails otherwise. Compose imports it into
+  `module-init.server.gen.ts`, guarded by `isModuleEnabled("<module>")`, and
+  runs every Module initializer before any enhancement initializer, once per
+  instance. Every generated page stub (its render and its `generateMetadata`)
+  and every generated API route stub awaits `initializeActiveEnhancements()`
+  before its enablement guards, so the registrations exist in the route's own
+  module graph. Page stubs await it from compose 0.14.0; before that only API
+  stubs did. An `initialize()` export
+  run only from `instrumentation.ts` does not give you that: Next.js loads
+  instrumentation in a separate module graph, so on a cold instance the route
+  handlers and server components never see what it registered. A Module left
+  out by `--enabled` is not imported. Needs compose 0.14.0 or later (and
+  `@stardeck-customer-apps/eslint-plugin` 1.8.0 or later, whose
+  `no-module-internal-import` lets the generated file import it).
+
 - `@stardeck-customer-apps/compose/runtime` exports `isModuleEnabledByList`,
   the single enablement rule, and imports nothing — it is safe in client
   components.

package/dist/cli.js

@@ -3560,17 +3560,20 @@ var import_typescript3 = __toESM(require("typescript"), 1);
 var CONVENTIONAL_ENTRY_EXPORT_NAME = {
   contributions: "contributions",
   slotCatalogs: "slotCatalogs",
-  initializeEnhancement: "initializeEnhancement"
+  initializeEnhancement: "initializeEnhancement",
+  initializeModule: "initializeModule"
 };
 var CONVENTIONAL_ENTRY_DECLARATION_KIND = {
   contributions: "variable",
   slotCatalogs: "variable",
-  initializeEnhancement: "function"
+  initializeEnhancement: "function",
+  initializeModule: "function"
 };
 var CONVENTIONAL_ENTRY_FILENAME = {
   contributions: "contributions.ts",
   slotCatalogs: "slots.ts",
-  initializeEnhancement: "initialize.server.ts"
+  initializeEnhancement: "initialize.server.ts",
+  initializeModule: "initialize.server.ts"
 };
 function hasModifierKind(modifiers, kind) {
   return Boolean(modifiers?.some((m) => m.kind === kind));
@@ -3669,7 +3672,7 @@ function analyzeConventionalEntryExportWithTs(typescript, sourceText, kind, file
         }
         if (!isZeroArgumentInvocable(typescript, stmt.parameters)) {
           errors.push(
-            `"${entryName}" must be invocable with zero arguments (generated caller uses initializeEnhancement()); required parameters are forbidden \u2014 use optional, default, rest, or a this-parameter only`
+            `"${entryName}" must be invocable with zero arguments (generated caller uses ${entryName}()); required parameters are forbidden \u2014 use optional, default, rest, or a this-parameter only`
           );
           continue;
         }
@@ -4150,6 +4153,9 @@ function assertSlotCatalogsExport(source, pathLabel) {
 function assertInitializeEnhancementExport(source, pathLabel) {
   assertConventionalEntryExport(source, pathLabel, "initializeEnhancement");
 }
+function assertInitializeModuleExport(source, pathLabel) {
+  assertConventionalEntryExport(source, pathLabel, "initializeModule");
+}
 function assertClientSafeConventionalEntryImports(source, pathLabel, kind) {
   const { analysisErrors } = analyzeClientSafeEntryImports(
     source,
@@ -4669,30 +4675,47 @@ function deriveModuleLocaleLayers(registry, facts) {
   }
   return layers;
 }
-function emitModuleInitServerGenTs(input) {
+function moduleInitializerCalls(registry, facts) {
+  const installed = new Set(registry.modules.map((m) => m.name));
+  return facts.filter((f) => f.hasRootInitializeServer && installed.has(f.moduleName)).map((f) => f.moduleName).sort(compareNames).map((name, index) => {
+    if (!isValidModuleName(name)) {
+      throw new Error(`[ModuleRail] composition artifacts: invalid module name "${name}"`);
+    }
+    return {
+      exportName: "initializeModule",
+      guard: [name],
+      ident: `initializeModule${index}`,
+      importPath: `@/modules/${name}/initialize.server`
+    };
+  });
+}
+function enhancementInitializerCalls(registry, facts) {
   const calls = [];
-  const installed = new Set(input.registry.modules.map((m) => m.name));
-  let initializerIndex = 0;
-  for (const facts of [...input.facts].sort((a, b) => compareNames(a.moduleName, b.moduleName))) {
-    if (!installed.has(facts.moduleName)) continue;
-    const peers = activePeers(input.registry, facts.moduleName);
-    for (const enh of [...facts.enhancements].sort((a, b) => compareNames(a.peer, b.peer))) {
+  const installed = new Set(registry.modules.map((m) => m.name));
+  for (const f of [...facts].sort((a, b) => compareNames(a.moduleName, b.moduleName))) {
+    if (!installed.has(f.moduleName)) continue;
+    const peers = activePeers(registry, f.moduleName);
+    for (const enh of [...f.enhancements].sort((a, b) => compareNames(a.peer, b.peer))) {
       if (!enh.active || !peers.has(enh.peer)) continue;
       if (!enh.hasInitializeServer) continue;
-      const ident = `initializeEnhancement${initializerIndex++}`;
       calls.push({
-        owner: facts.moduleName,
-        peer: enh.peer,
-        ident,
-        importPath: `@/modules/${facts.moduleName}/enhancements/${enh.peer}/initialize.server`
+        exportName: "initializeEnhancement",
+        guard: [f.moduleName, enh.peer],
+        ident: `initializeEnhancement${calls.length}`,
+        importPath: `@/modules/${f.moduleName}/enhancements/${enh.peer}/initialize.server`
       });
     }
   }
-  const importLines = calls.map(
-    (c) => `import { initializeEnhancement as ${c.ident} } from ${JSON.stringify(c.importPath)};`
-  );
+  return calls;
+}
+function emitModuleInitServerGenTs(input) {
+  const moduleCalls = moduleInitializerCalls(input.registry, input.facts);
+  const enhancementCalls = enhancementInitializerCalls(input.registry, input.facts);
+  const calls = [...moduleCalls, ...enhancementCalls];
+  const importFor = (c) => `import { ${c.exportName} as ${c.ident} } from ${JSON.stringify(c.importPath)};`;
+  const importLines = moduleCalls.length === 0 ? calls.map(importFor) : [...calls].sort((a, b) => compareImportSpecifiers(a.importPath, b.importPath)).map(importFor);
   const callLines = calls.length === 0 ? ["      // Empty composition \u2014 no active enhancement initializers."] : calls.map(
-    (c) => `      if (enabled(${JSON.stringify(c.owner)}) && enabled(${JSON.stringify(c.peer)})) await ${c.ident}();`
+    (c) => `      if (${c.guard.map((name) => `enabled(${JSON.stringify(name)})`).join(" && ")}) await ${c.ident}();`
   );
   return [
     formatInitMarker(),
@@ -5142,6 +5165,7 @@ function buildRouteStubContent(input) {
     'import { notFound } from "next/navigation";',
     // simple-import-sort puts packages and "@/" aliases in separate groups.
     "",
+    'import { initializeActiveEnhancements } from "@/module-init.server.gen";',
     'import { isModuleEnabled, isMountHeadless } from "@/modules.gen";',
     `import Page from ${emitTsString(input.importModule)};`
   ];
@@ -5150,6 +5174,7 @@ function buildRouteStubContent(input) {
       `import { generateMetadata as sourceGenerateMetadata } from ${emitTsString(input.importModule)};`,
       "",
       "export async function generateMetadata(...args: Parameters<typeof sourceGenerateMetadata>) {",
+      "  await initializeActiveEnhancements();",
       ...emitGuardLines(guards, "return {};"),
       "  return sourceGenerateMetadata(...args);",
       "}"
@@ -5160,7 +5185,10 @@ function buildRouteStubContent(input) {
     "type PageProps =",
     "  Parameters<typeof Page> extends [infer P, ...unknown[]] ? NonNullable<P> : Record<never, never>;",
     "",
-    "export default function ModulePage(props: PageProps) {",
+    // Module and enhancement initializers run in this route's own module graph
+    // (memoized), so a cold server render sees their registrations.
+    "export default async function ModulePage(props: PageProps) {",
+    "  await initializeActiveEnhancements();",
     ...emitGuardLines(guards, "notFound();"),
     "  return <Page {...props} />;",
     "}",
@@ -6958,6 +6986,9 @@ async function readConventionalEntryIfRealFile(path5, kind, presences, files) {
     case "initializeEnhancement":
       assertInitializeEnhancementExport(source, path5);
       break;
+    case "initializeModule":
+      assertInitializeModuleExport(source, path5);
+      break;
   }
   return source;
 }
@@ -6994,7 +7025,11 @@ async function collectCompositionEntryFacts(context, registry) {
   for (const mod of registry.modules) {
     const modulePath = `${MODULES_SANDBOX_DIR}/${mod.name}`;
     localeDirs.push(`${modulePath}/i18n`);
-    conventionalPaths.push(`${modulePath}/contributions.ts`, `${modulePath}/slots.ts`);
+    conventionalPaths.push(
+      `${modulePath}/contributions.ts`,
+      `${modulePath}/slots.ts`,
+      `${modulePath}/initialize.server.ts`
+    );
     for (const enh of mod.enhancements) {
       const peerDir = `${modulePath}/enhancements/${enh.peer}`;
       localeDirs.push(`${peerDir}/i18n`);
@@ -7082,6 +7117,17 @@ async function collectCompositionEntryFacts(context, registry) {
       }
     }
     const hasServerRegistrations = hasRealServerRegistrations(modulePath, conventionalPresences);
+    const hasRootInitializeServer = await readConventionalEntryIfRealFile(
+      `${modulePath}/initialize.server.ts`,
+      "initializeModule",
+      conventionalPresences,
+      files
+    ) != null;
+    if (hasRootInitializeServer) {
+      console.log(
+        `[ModuleRail] runId=${context.runId} module=${mod.name} has root initialize.server.ts (initializeModule)`
+      );
+    }
     const rootLocales = localesByDir.get(`${modulePath}/i18n`);
     if (rootLocales.length > 0 && !rootLocales.includes("en")) {
       throw new Error(
@@ -7122,6 +7168,7 @@ async function collectCompositionEntryFacts(context, registry) {
       hasRootContributions,
       hasRootSlots,
       hasServerRegistrations,
+      hasRootInitializeServer,
       rootLocales,
       enhancements
     });

package/dist/index.js

@@ -3689,17 +3689,20 @@ var import_typescript3 = __toESM(require("typescript"), 1);
 var CONVENTIONAL_ENTRY_EXPORT_NAME = {
   contributions: "contributions",
   slotCatalogs: "slotCatalogs",
-  initializeEnhancement: "initializeEnhancement"
+  initializeEnhancement: "initializeEnhancement",
+  initializeModule: "initializeModule"
 };
 var CONVENTIONAL_ENTRY_DECLARATION_KIND = {
   contributions: "variable",
   slotCatalogs: "variable",
-  initializeEnhancement: "function"
+  initializeEnhancement: "function",
+  initializeModule: "function"
 };
 var CONVENTIONAL_ENTRY_FILENAME = {
   contributions: "contributions.ts",
   slotCatalogs: "slots.ts",
-  initializeEnhancement: "initialize.server.ts"
+  initializeEnhancement: "initialize.server.ts",
+  initializeModule: "initialize.server.ts"
 };
 function hasModifierKind(modifiers, kind) {
   return Boolean(modifiers?.some((m) => m.kind === kind));
@@ -3798,7 +3801,7 @@ function analyzeConventionalEntryExportWithTs(typescript, sourceText, kind, file
         }
         if (!isZeroArgumentInvocable(typescript, stmt.parameters)) {
           errors.push(
-            `"${entryName}" must be invocable with zero arguments (generated caller uses initializeEnhancement()); required parameters are forbidden \u2014 use optional, default, rest, or a this-parameter only`
+            `"${entryName}" must be invocable with zero arguments (generated caller uses ${entryName}()); required parameters are forbidden \u2014 use optional, default, rest, or a this-parameter only`
           );
           continue;
         }
@@ -4160,6 +4163,9 @@ function assertSlotCatalogsExport(source, pathLabel) {
 function assertInitializeEnhancementExport(source, pathLabel) {
   assertConventionalEntryExport(source, pathLabel, "initializeEnhancement");
 }
+function assertInitializeModuleExport(source, pathLabel) {
+  assertConventionalEntryExport(source, pathLabel, "initializeModule");
+}
 function assertClientSafeConventionalEntryImports(source, pathLabel, kind) {
   const { analysisErrors } = analyzeClientSafeEntryImports(
     source,
@@ -4679,30 +4685,47 @@ function deriveModuleLocaleLayers(registry, facts) {
   }
   return layers;
 }
-function emitModuleInitServerGenTs(input) {
+function moduleInitializerCalls(registry, facts) {
+  const installed = new Set(registry.modules.map((m) => m.name));
+  return facts.filter((f) => f.hasRootInitializeServer && installed.has(f.moduleName)).map((f) => f.moduleName).sort(compareNames).map((name, index) => {
+    if (!isValidModuleName(name)) {
+      throw new Error(`[ModuleRail] composition artifacts: invalid module name "${name}"`);
+    }
+    return {
+      exportName: "initializeModule",
+      guard: [name],
+      ident: `initializeModule${index}`,
+      importPath: `@/modules/${name}/initialize.server`
+    };
+  });
+}
+function enhancementInitializerCalls(registry, facts) {
   const calls = [];
-  const installed = new Set(input.registry.modules.map((m) => m.name));
-  let initializerIndex = 0;
-  for (const facts of [...input.facts].sort((a, b) => compareNames(a.moduleName, b.moduleName))) {
-    if (!installed.has(facts.moduleName)) continue;
-    const peers = activePeers(input.registry, facts.moduleName);
-    for (const enh of [...facts.enhancements].sort((a, b) => compareNames(a.peer, b.peer))) {
+  const installed = new Set(registry.modules.map((m) => m.name));
+  for (const f of [...facts].sort((a, b) => compareNames(a.moduleName, b.moduleName))) {
+    if (!installed.has(f.moduleName)) continue;
+    const peers = activePeers(registry, f.moduleName);
+    for (const enh of [...f.enhancements].sort((a, b) => compareNames(a.peer, b.peer))) {
       if (!enh.active || !peers.has(enh.peer)) continue;
       if (!enh.hasInitializeServer) continue;
-      const ident = `initializeEnhancement${initializerIndex++}`;
       calls.push({
-        owner: facts.moduleName,
-        peer: enh.peer,
-        ident,
-        importPath: `@/modules/${facts.moduleName}/enhancements/${enh.peer}/initialize.server`
+        exportName: "initializeEnhancement",
+        guard: [f.moduleName, enh.peer],
+        ident: `initializeEnhancement${calls.length}`,
+        importPath: `@/modules/${f.moduleName}/enhancements/${enh.peer}/initialize.server`
       });
     }
   }
-  const importLines = calls.map(
-    (c) => `import { initializeEnhancement as ${c.ident} } from ${JSON.stringify(c.importPath)};`
-  );
+  return calls;
+}
+function emitModuleInitServerGenTs(input) {
+  const moduleCalls = moduleInitializerCalls(input.registry, input.facts);
+  const enhancementCalls = enhancementInitializerCalls(input.registry, input.facts);
+  const calls = [...moduleCalls, ...enhancementCalls];
+  const importFor = (c) => `import { ${c.exportName} as ${c.ident} } from ${JSON.stringify(c.importPath)};`;
+  const importLines = moduleCalls.length === 0 ? calls.map(importFor) : [...calls].sort((a, b) => compareImportSpecifiers(a.importPath, b.importPath)).map(importFor);
   const callLines = calls.length === 0 ? ["      // Empty composition \u2014 no active enhancement initializers."] : calls.map(
-    (c) => `      if (enabled(${JSON.stringify(c.owner)}) && enabled(${JSON.stringify(c.peer)})) await ${c.ident}();`
+    (c) => `      if (${c.guard.map((name) => `enabled(${JSON.stringify(name)})`).join(" && ")}) await ${c.ident}();`
   );
   return [
     formatInitMarker(),
@@ -5152,6 +5175,7 @@ function buildRouteStubContent(input) {
     'import { notFound } from "next/navigation";',
     // simple-import-sort puts packages and "@/" aliases in separate groups.
     "",
+    'import { initializeActiveEnhancements } from "@/module-init.server.gen";',
     'import { isModuleEnabled, isMountHeadless } from "@/modules.gen";',
     `import Page from ${emitTsString(input.importModule)};`
   ];
@@ -5160,6 +5184,7 @@ function buildRouteStubContent(input) {
       `import { generateMetadata as sourceGenerateMetadata } from ${emitTsString(input.importModule)};`,
       "",
       "export async function generateMetadata(...args: Parameters<typeof sourceGenerateMetadata>) {",
+      "  await initializeActiveEnhancements();",
       ...emitGuardLines(guards, "return {};"),
       "  return sourceGenerateMetadata(...args);",
       "}"
@@ -5170,7 +5195,10 @@ function buildRouteStubContent(input) {
     "type PageProps =",
     "  Parameters<typeof Page> extends [infer P, ...unknown[]] ? NonNullable<P> : Record<never, never>;",
     "",
-    "export default function ModulePage(props: PageProps) {",
+    // Module and enhancement initializers run in this route's own module graph
+    // (memoized), so a cold server render sees their registrations.
+    "export default async function ModulePage(props: PageProps) {",
+    "  await initializeActiveEnhancements();",
     ...emitGuardLines(guards, "notFound();"),
     "  return <Page {...props} />;",
     "}",
@@ -6968,6 +6996,9 @@ async function readConventionalEntryIfRealFile(path4, kind, presences, files) {
     case "initializeEnhancement":
       assertInitializeEnhancementExport(source, path4);
       break;
+    case "initializeModule":
+      assertInitializeModuleExport(source, path4);
+      break;
   }
   return source;
 }
@@ -7004,7 +7035,11 @@ async function collectCompositionEntryFacts(context, registry) {
   for (const mod of registry.modules) {
     const modulePath = `${MODULES_SANDBOX_DIR}/${mod.name}`;
     localeDirs.push(`${modulePath}/i18n`);
-    conventionalPaths.push(`${modulePath}/contributions.ts`, `${modulePath}/slots.ts`);
+    conventionalPaths.push(
+      `${modulePath}/contributions.ts`,
+      `${modulePath}/slots.ts`,
+      `${modulePath}/initialize.server.ts`
+    );
     for (const enh of mod.enhancements) {
       const peerDir = `${modulePath}/enhancements/${enh.peer}`;
       localeDirs.push(`${peerDir}/i18n`);
@@ -7092,6 +7127,17 @@ async function collectCompositionEntryFacts(context, registry) {
       }
     }
     const hasServerRegistrations = hasRealServerRegistrations(modulePath, conventionalPresences);
+    const hasRootInitializeServer = await readConventionalEntryIfRealFile(
+      `${modulePath}/initialize.server.ts`,
+      "initializeModule",
+      conventionalPresences,
+      files
+    ) != null;
+    if (hasRootInitializeServer) {
+      console.log(
+        `[ModuleRail] runId=${context.runId} module=${mod.name} has root initialize.server.ts (initializeModule)`
+      );
+    }
     const rootLocales = localesByDir.get(`${modulePath}/i18n`);
     if (rootLocales.length > 0 && !rootLocales.includes("en")) {
       throw new Error(
@@ -7132,6 +7178,7 @@ async function collectCompositionEntryFacts(context, registry) {
       hasRootContributions,
       hasRootSlots,
       hasServerRegistrations,
+      hasRootInitializeServer,
       rootLocales,
       enhancements
     });

package/dist/index.mjs

@@ -3670,17 +3670,20 @@ import ts3 from "typescript";
 var CONVENTIONAL_ENTRY_EXPORT_NAME = {
   contributions: "contributions",
   slotCatalogs: "slotCatalogs",
-  initializeEnhancement: "initializeEnhancement"
+  initializeEnhancement: "initializeEnhancement",
+  initializeModule: "initializeModule"
 };
 var CONVENTIONAL_ENTRY_DECLARATION_KIND = {
   contributions: "variable",
   slotCatalogs: "variable",
-  initializeEnhancement: "function"
+  initializeEnhancement: "function",
+  initializeModule: "function"
 };
 var CONVENTIONAL_ENTRY_FILENAME = {
   contributions: "contributions.ts",
   slotCatalogs: "slots.ts",
-  initializeEnhancement: "initialize.server.ts"
+  initializeEnhancement: "initialize.server.ts",
+  initializeModule: "initialize.server.ts"
 };
 function hasModifierKind(modifiers, kind) {
   return Boolean(modifiers?.some((m) => m.kind === kind));
@@ -3779,7 +3782,7 @@ function analyzeConventionalEntryExportWithTs(typescript, sourceText, kind, file
         }
         if (!isZeroArgumentInvocable(typescript, stmt.parameters)) {
           errors.push(
-            `"${entryName}" must be invocable with zero arguments (generated caller uses initializeEnhancement()); required parameters are forbidden \u2014 use optional, default, rest, or a this-parameter only`
+            `"${entryName}" must be invocable with zero arguments (generated caller uses ${entryName}()); required parameters are forbidden \u2014 use optional, default, rest, or a this-parameter only`
           );
           continue;
         }
@@ -4141,6 +4144,9 @@ function assertSlotCatalogsExport(source, pathLabel) {
 function assertInitializeEnhancementExport(source, pathLabel) {
   assertConventionalEntryExport(source, pathLabel, "initializeEnhancement");
 }
+function assertInitializeModuleExport(source, pathLabel) {
+  assertConventionalEntryExport(source, pathLabel, "initializeModule");
+}
 function assertClientSafeConventionalEntryImports(source, pathLabel, kind) {
   const { analysisErrors } = analyzeClientSafeEntryImports(
     source,
@@ -4660,30 +4666,47 @@ function deriveModuleLocaleLayers(registry, facts) {
   }
   return layers;
 }
-function emitModuleInitServerGenTs(input) {
+function moduleInitializerCalls(registry, facts) {
+  const installed = new Set(registry.modules.map((m) => m.name));
+  return facts.filter((f) => f.hasRootInitializeServer && installed.has(f.moduleName)).map((f) => f.moduleName).sort(compareNames).map((name, index) => {
+    if (!isValidModuleName(name)) {
+      throw new Error(`[ModuleRail] composition artifacts: invalid module name "${name}"`);
+    }
+    return {
+      exportName: "initializeModule",
+      guard: [name],
+      ident: `initializeModule${index}`,
+      importPath: `@/modules/${name}/initialize.server`
+    };
+  });
+}
+function enhancementInitializerCalls(registry, facts) {
   const calls = [];
-  const installed = new Set(input.registry.modules.map((m) => m.name));
-  let initializerIndex = 0;
-  for (const facts of [...input.facts].sort((a, b) => compareNames(a.moduleName, b.moduleName))) {
-    if (!installed.has(facts.moduleName)) continue;
-    const peers = activePeers(input.registry, facts.moduleName);
-    for (const enh of [...facts.enhancements].sort((a, b) => compareNames(a.peer, b.peer))) {
+  const installed = new Set(registry.modules.map((m) => m.name));
+  for (const f of [...facts].sort((a, b) => compareNames(a.moduleName, b.moduleName))) {
+    if (!installed.has(f.moduleName)) continue;
+    const peers = activePeers(registry, f.moduleName);
+    for (const enh of [...f.enhancements].sort((a, b) => compareNames(a.peer, b.peer))) {
       if (!enh.active || !peers.has(enh.peer)) continue;
       if (!enh.hasInitializeServer) continue;
-      const ident = `initializeEnhancement${initializerIndex++}`;
       calls.push({
-        owner: facts.moduleName,
-        peer: enh.peer,
-        ident,
-        importPath: `@/modules/${facts.moduleName}/enhancements/${enh.peer}/initialize.server`
+        exportName: "initializeEnhancement",
+        guard: [f.moduleName, enh.peer],
+        ident: `initializeEnhancement${calls.length}`,
+        importPath: `@/modules/${f.moduleName}/enhancements/${enh.peer}/initialize.server`
       });
     }
   }
-  const importLines = calls.map(
-    (c) => `import { initializeEnhancement as ${c.ident} } from ${JSON.stringify(c.importPath)};`
-  );
+  return calls;
+}
+function emitModuleInitServerGenTs(input) {
+  const moduleCalls = moduleInitializerCalls(input.registry, input.facts);
+  const enhancementCalls = enhancementInitializerCalls(input.registry, input.facts);
+  const calls = [...moduleCalls, ...enhancementCalls];
+  const importFor = (c) => `import { ${c.exportName} as ${c.ident} } from ${JSON.stringify(c.importPath)};`;
+  const importLines = moduleCalls.length === 0 ? calls.map(importFor) : [...calls].sort((a, b) => compareImportSpecifiers(a.importPath, b.importPath)).map(importFor);
   const callLines = calls.length === 0 ? ["      // Empty composition \u2014 no active enhancement initializers."] : calls.map(
-    (c) => `      if (enabled(${JSON.stringify(c.owner)}) && enabled(${JSON.stringify(c.peer)})) await ${c.ident}();`
+    (c) => `      if (${c.guard.map((name) => `enabled(${JSON.stringify(name)})`).join(" && ")}) await ${c.ident}();`
   );
   return [
     formatInitMarker(),
@@ -5133,6 +5156,7 @@ function buildRouteStubContent(input) {
     'import { notFound } from "next/navigation";',
     // simple-import-sort puts packages and "@/" aliases in separate groups.
     "",
+    'import { initializeActiveEnhancements } from "@/module-init.server.gen";',
     'import { isModuleEnabled, isMountHeadless } from "@/modules.gen";',
     `import Page from ${emitTsString(input.importModule)};`
   ];
@@ -5141,6 +5165,7 @@ function buildRouteStubContent(input) {
       `import { generateMetadata as sourceGenerateMetadata } from ${emitTsString(input.importModule)};`,
       "",
       "export async function generateMetadata(...args: Parameters<typeof sourceGenerateMetadata>) {",
+      "  await initializeActiveEnhancements();",
       ...emitGuardLines(guards, "return {};"),
       "  return sourceGenerateMetadata(...args);",
       "}"
@@ -5151,7 +5176,10 @@ function buildRouteStubContent(input) {
     "type PageProps =",
     "  Parameters<typeof Page> extends [infer P, ...unknown[]] ? NonNullable<P> : Record<never, never>;",
     "",
-    "export default function ModulePage(props: PageProps) {",
+    // Module and enhancement initializers run in this route's own module graph
+    // (memoized), so a cold server render sees their registrations.
+    "export default async function ModulePage(props: PageProps) {",
+    "  await initializeActiveEnhancements();",
     ...emitGuardLines(guards, "notFound();"),
     "  return <Page {...props} />;",
     "}",
@@ -6949,6 +6977,9 @@ async function readConventionalEntryIfRealFile(path4, kind, presences, files) {
     case "initializeEnhancement":
       assertInitializeEnhancementExport(source, path4);
       break;
+    case "initializeModule":
+      assertInitializeModuleExport(source, path4);
+      break;
   }
   return source;
 }
@@ -6985,7 +7016,11 @@ async function collectCompositionEntryFacts(context, registry) {
   for (const mod of registry.modules) {
     const modulePath = `${MODULES_SANDBOX_DIR}/${mod.name}`;
     localeDirs.push(`${modulePath}/i18n`);
-    conventionalPaths.push(`${modulePath}/contributions.ts`, `${modulePath}/slots.ts`);
+    conventionalPaths.push(
+      `${modulePath}/contributions.ts`,
+      `${modulePath}/slots.ts`,
+      `${modulePath}/initialize.server.ts`
+    );
     for (const enh of mod.enhancements) {
       const peerDir = `${modulePath}/enhancements/${enh.peer}`;
       localeDirs.push(`${peerDir}/i18n`);
@@ -7073,6 +7108,17 @@ async function collectCompositionEntryFacts(context, registry) {
       }
     }
     const hasServerRegistrations = hasRealServerRegistrations(modulePath, conventionalPresences);
+    const hasRootInitializeServer = await readConventionalEntryIfRealFile(
+      `${modulePath}/initialize.server.ts`,
+      "initializeModule",
+      conventionalPresences,
+      files
+    ) != null;
+    if (hasRootInitializeServer) {
+      console.log(
+        `[ModuleRail] runId=${context.runId} module=${mod.name} has root initialize.server.ts (initializeModule)`
+      );
+    }
     const rootLocales = localesByDir.get(`${modulePath}/i18n`);
     if (rootLocales.length > 0 && !rootLocales.includes("en")) {
       throw new Error(
@@ -7113,6 +7159,7 @@ async function collectCompositionEntryFacts(context, registry) {
       hasRootContributions,
       hasRootSlots,
       hasServerRegistrations,
+      hasRootInitializeServer,
       rootLocales,
       enhancements
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stardeck-customer-apps/compose",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Regenerates a Stardeck app's Module-rail artifacts — the six src/*.gen.ts registries and every route/endpoint stub — from src/modules/*/module.json",
   "main": "dist/index.js",
   "module": "dist/index.mjs",