@stardeck-customer-apps/compose 0.13.0 → 0.14.1

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

@@ -2259,10 +2259,12 @@ var modulePermissionClaimSchema = import_zod.z.object({
   /** Human label for the deployment auth config row. */
   description: descriptionSchema,
   /**
-   * The default organization roles that hold this key when the platform
-   * first registers it on an app (a Blueprint fork, a Module install). Admin
-   * holds every key without being listed; External Viewer never holds one.
-   * Changing a role's grants afterwards is the organization's business.
+   * The standard organization roles that hold this key. The platform sets them on every app
+   * (a Blueprint fork, a Module install or uninstall, every Blueprint update), so this list is
+   * the truth: a role added here gains the key, a role removed loses it, and nobody can edit a
+   * standard role's grants on a Module key. Admin holds every key without being listed;
+   * External Viewer never holds one. An organization that wants different access duplicates the
+   * standard role and edits the copy.
    */
   roles: import_zod.z.array(import_zod.z.enum(MODULE_PERMISSION_DEFAULT_ROLES)).optional()
 }).strict();
@@ -3560,17 +3562,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 +3674,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;
         }
@@ -3979,6 +3984,7 @@ var JSON_SECRET_PAIR = new RegExp(
   "g"
 );
 var SECRET_QUOTE_OPENER = new RegExp(String.raw`\b${SECRET_NAME}\s*=\s*(['"])`, "g");
+var SHELL_QUOTE_CONTINUATION = String.raw`\''`;
 function redactSecrets(text) {
   return text.replace(/x-access-token:[^@\s]+@/g, "x-access-token:***@").replace(/https:\/\/(?!x-access-token:)[^/\s:@]+:[^/\s@]+@/gi, "https://***:***@").replace(/\b(gh[pousr]_)[A-Za-z0-9]+/g, "$1***").replace(/\b(github_pat_)[A-Za-z0-9_]+/g, "$1***").replace(/\b(postgres(?:ql)?:\/\/)([^:\s/@]+):([^@\s/]+)@/gi, "$1$2:***@").replace(/\b(npm_[A-Za-z0-9]+)/g, "npm_***").replace(/(_authToken=)([^\s&]+)/gi, "$1***").replace(SECRET_ASSIGNMENT, "$1=***").replace(JSON_SECRET_PAIR, '"$1"$2"***"').replace(/\b(Authorization:\s*(?:Bearer|Basic)\s+)\S+/gi, "$1***");
 }
@@ -4150,6 +4156,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 +4678,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(),
@@ -4804,6 +4830,9 @@ function enhancementImport(owner, peer) {
 function scopeLabel(scope) {
   return scope.kind === "root" ? "root" : `enhancement:${scope.peer}`;
 }
+function endpointMarkerOwnsStub(marker, stub) {
+  return stub != null && marker?.kind === "endpoint" && marker.owner === stub.owner;
+}
 function formatEndpointMarker(owner, scope) {
   return `// ${MODULE_STUB_MARKER} owner=${owner} scope=${scopeLabel(scope)}`;
 }
@@ -5142,6 +5171,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 +5180,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 +5191,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} />;",
     "}",
@@ -5500,7 +5534,7 @@ function planCompositionArtifacts(input) {
     const legacy = parseLegacyApiAdapter(pagePath, content);
     const plannedRoute = plannedRouteByPath.get(pagePath);
     const plannedEndpoint = plannedEndpointByPath.get(pagePath);
-    const isExactPlannedMatch = plannedRoute != null && marker != null && marker.kind === "route" && marker.owner === plannedRoute.owner && marker.nextRelativePath === plannedRoute.nextRelativePath || plannedEndpoint != null && (marker != null && marker.kind === "endpoint" && marker.owner === plannedEndpoint.owner && scopeLabel(marker.scope) === scopeLabel(plannedEndpoint.scope) || legacy != null) || plannedRoute != null && legacyRouteAdapterMatchesStub(pagePath, content, plannedRoute);
+    const isExactPlannedMatch = plannedRoute != null && marker != null && marker.kind === "route" && marker.owner === plannedRoute.owner && marker.nextRelativePath === plannedRoute.nextRelativePath || plannedEndpoint != null && (endpointMarkerOwnsStub(marker, plannedEndpoint) || legacy != null) || plannedRoute != null && legacyRouteAdapterMatchesStub(pagePath, content, plannedRoute);
     if (isExactPlannedMatch) {
       continue;
     }
@@ -5643,9 +5677,7 @@ function planCompositionArtifacts(input) {
     }
     if (marker.kind === "endpoint") {
       const stub = endpointStubByPath.get(path5);
-      const ownerMatches = stub != null && marker.owner === stub.owner;
-      const scopeMatches = stub != null && scopeLabel(marker.scope) === scopeLabel(stub.scope);
-      if (!ownerMatches || !scopeMatches) {
+      if (!endpointMarkerOwnsStub(marker, stub)) {
         return {
           ok: false,
           error: `[ModuleRail] composition artifacts: refusing to overwrite incongruent marker ownership at ${path5} (existing owner=${marker.owner} scope=${scopeLabel(marker.scope)} vs planned owner=${stub?.owner ?? "?"} scope=${stub ? scopeLabel(stub.scope) : "?"})`,
@@ -6288,39 +6320,24 @@ async function assertNoRootRoutesWhenMountsEmpty(context, moduleName) {
     );
   }
 }
-async function assertNoEnhancementRoutes(context, moduleName) {
-  const enhancementsDir = `${MODULES_SANDBOX_DIR}/${moduleName}/enhancements`;
-  const enhancementEntries = await listImmediateEntries(context.sandbox, enhancementsDir, {
-    optional: true,
-    label: `enhancements for ${moduleName}`
-  });
-  for (const entry of enhancementEntries) {
-    if (entry.kind !== "dir") continue;
-    const sliceRoutes = `${enhancementsDir}/${entry.name}/routes`;
-    const sliceProbe = await context.sandbox.exec(
-      [
-        `p=${shellQuote(sliceRoutes)}`,
-        `if test -L "$p" || test -e "$p"; then exit 2; else exit 0; fi`
-      ].join("\n"),
-      { raiseOnError: false }
-    );
-    if (sliceProbe.exitCode === 2) {
+async function assertNoEnhancementRoutePaths(context, paths) {
+  const kinds = await classifySandboxPathPresenceKindMany(context, paths, "enhancement-route-kind");
+  for (const sliceRoutes of paths) {
+    const kind = kinds.get(sliceRoutes);
+    if (kind === "absent") continue;
+    if (kind !== "unreadable" && kind !== void 0) {
       throw new Error(
         `[ModuleRail] composition artifacts: enhancement slice routes/ are forbidden at ${sliceRoutes}`
       );
     }
-    if (sliceProbe.exitCode !== 0) {
-      const detail = typeof sliceProbe.error === "string" && sliceProbe.error.trim() || sliceProbe.output.trim() || `exit ${sliceProbe.exitCode}`;
-      throw new Error(
-        `[ModuleRail] composition artifacts: cannot probe ${sliceRoutes}: ${redactSecrets(detail)}`
-      );
-    }
+    throw new Error(
+      `[ModuleRail] composition artifacts: cannot probe ${sliceRoutes}: entry-kind:${kind ?? "missing"}`
+    );
   }
 }
-async function discoverModuleRouteEntries(context, moduleName) {
+async function discoverRootRouteEntries(context, moduleName) {
   const modulePath = `${MODULES_SANDBOX_DIR}/${moduleName}`;
   const routesDir = `${modulePath}/routes`;
-  await assertNoEnhancementRoutes(context, moduleName);
   const quotedRoutes = shellQuote(routesDir);
   const listResult = await context.sandbox.exec(
     [
@@ -6774,7 +6791,8 @@ async function classifySandboxPathPresenceKindMany(context, paths, probeToken) {
         `# Leaf is missing. A missing intermediate parent means the path is simply`,
         `# absent (new nested writes). Only an existing-but-inaccessible parent`,
         `# is unreadable \u2014 never conflate ENOENT parents with EACCES.`,
-        `parent=$(dirname -- "$p")`,
+        // Probe paths are nested repo-relative paths; do not spawn dirname per missing file.
+        `parent=\${p%/*}`,
         `if test ! -e "$parent" && test ! -L "$parent"; then`,
         `  printf 'entry-kind:absent\\t%s\\n' "$p"`,
         `elif ls -ld -- "$parent" >/dev/null 2>&1; then`,
@@ -6958,6 +6976,9 @@ async function readConventionalEntryIfRealFile(path5, kind, presences, files) {
     case "initializeEnhancement":
       assertInitializeEnhancementExport(source, path5);
       break;
+    case "initializeModule":
+      assertInitializeModuleExport(source, path5);
+      break;
   }
   return source;
 }
@@ -6994,7 +7015,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 +7107,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 +7158,7 @@ async function collectCompositionEntryFacts(context, registry) {
       hasRootContributions,
       hasRootSlots,
       hasServerRegistrations,
+      hasRootInitializeServer,
       rootLocales,
       enhancements
     });
@@ -7300,14 +7337,21 @@ async function reconcileCompositionArtifacts(context, options = {}) {
     manifestsByName
   );
   const routeEntriesByOwner = {};
+  await assertNoEnhancementRoutePaths(
+    context,
+    moduleRuntimeFacts.flatMap(
+      ({ moduleName, onDiskEnhancementDirs }) => onDiskEnhancementDirs.map(
+        (peer) => `${MODULES_SANDBOX_DIR}/${moduleName}/enhancements/${peer}/routes`
+      )
+    )
+  );
   for (const moduleName of composedNames) {
     const manifest = manifestsByName[moduleName];
-    await assertNoEnhancementRoutes(context, moduleName);
     if (manifest.mounts.length === 0) {
       await assertNoRootRoutesWhenMountsEmpty(context, moduleName);
       routeEntriesByOwner[moduleName] = [];
     } else {
-      routeEntriesByOwner[moduleName] = await discoverModuleRouteEntries(context, moduleName);
+      routeEntriesByOwner[moduleName] = await discoverRootRouteEntries(context, moduleName);
     }
   }
   const existingGeneratedPaths = await listExistingGeneratedStubPaths(context);

package/dist/index.js

@@ -2097,6 +2097,7 @@ var JSON_SECRET_PAIR = new RegExp(
   "g"
 );
 var SECRET_QUOTE_OPENER = new RegExp(String.raw`\b${SECRET_NAME}\s*=\s*(['"])`, "g");
+var SHELL_QUOTE_CONTINUATION = String.raw`\''`;
 function redactSecrets(text) {
   return text.replace(/x-access-token:[^@\s]+@/g, "x-access-token:***@").replace(/https:\/\/(?!x-access-token:)[^/\s:@]+:[^/\s@]+@/gi, "https://***:***@").replace(/\b(gh[pousr]_)[A-Za-z0-9]+/g, "$1***").replace(/\b(github_pat_)[A-Za-z0-9_]+/g, "$1***").replace(/\b(postgres(?:ql)?:\/\/)([^:\s/@]+):([^@\s/]+)@/gi, "$1$2:***@").replace(/\b(npm_[A-Za-z0-9]+)/g, "npm_***").replace(/(_authToken=)([^\s&]+)/gi, "$1***").replace(SECRET_ASSIGNMENT, "$1=***").replace(JSON_SECRET_PAIR, '"$1"$2"***"').replace(/\b(Authorization:\s*(?:Bearer|Basic)\s+)\S+/gi, "$1***");
 }
@@ -2388,10 +2389,12 @@ var modulePermissionClaimSchema = import_zod2.z.object({
   /** Human label for the deployment auth config row. */
   description: descriptionSchema,
   /**
-   * The default organization roles that hold this key when the platform
-   * first registers it on an app (a Blueprint fork, a Module install). Admin
-   * holds every key without being listed; External Viewer never holds one.
-   * Changing a role's grants afterwards is the organization's business.
+   * The standard organization roles that hold this key. The platform sets them on every app
+   * (a Blueprint fork, a Module install or uninstall, every Blueprint update), so this list is
+   * the truth: a role added here gains the key, a role removed loses it, and nobody can edit a
+   * standard role's grants on a Module key. Admin holds every key without being listed;
+   * External Viewer never holds one. An organization that wants different access duplicates the
+   * standard role and edits the copy.
    */
   roles: import_zod2.z.array(import_zod2.z.enum(MODULE_PERMISSION_DEFAULT_ROLES)).optional()
 }).strict();
@@ -3689,17 +3692,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 +3804,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 +4166,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 +4688,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(),
@@ -4814,6 +4840,9 @@ function enhancementImport(owner, peer) {
 function scopeLabel(scope) {
   return scope.kind === "root" ? "root" : `enhancement:${scope.peer}`;
 }
+function endpointMarkerOwnsStub(marker, stub) {
+  return stub != null && marker?.kind === "endpoint" && marker.owner === stub.owner;
+}
 function formatEndpointMarker(owner, scope) {
   return `// ${MODULE_STUB_MARKER} owner=${owner} scope=${scopeLabel(scope)}`;
 }
@@ -5152,6 +5181,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 +5190,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 +5201,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} />;",
     "}",
@@ -5510,7 +5544,7 @@ function planCompositionArtifacts(input) {
     const legacy = parseLegacyApiAdapter(pagePath, content);
     const plannedRoute = plannedRouteByPath.get(pagePath);
     const plannedEndpoint = plannedEndpointByPath.get(pagePath);
-    const isExactPlannedMatch = plannedRoute != null && marker != null && marker.kind === "route" && marker.owner === plannedRoute.owner && marker.nextRelativePath === plannedRoute.nextRelativePath || plannedEndpoint != null && (marker != null && marker.kind === "endpoint" && marker.owner === plannedEndpoint.owner && scopeLabel(marker.scope) === scopeLabel(plannedEndpoint.scope) || legacy != null) || plannedRoute != null && legacyRouteAdapterMatchesStub(pagePath, content, plannedRoute);
+    const isExactPlannedMatch = plannedRoute != null && marker != null && marker.kind === "route" && marker.owner === plannedRoute.owner && marker.nextRelativePath === plannedRoute.nextRelativePath || plannedEndpoint != null && (endpointMarkerOwnsStub(marker, plannedEndpoint) || legacy != null) || plannedRoute != null && legacyRouteAdapterMatchesStub(pagePath, content, plannedRoute);
     if (isExactPlannedMatch) {
       continue;
     }
@@ -5653,9 +5687,7 @@ function planCompositionArtifacts(input) {
     }
     if (marker.kind === "endpoint") {
       const stub = endpointStubByPath.get(path4);
-      const ownerMatches = stub != null && marker.owner === stub.owner;
-      const scopeMatches = stub != null && scopeLabel(marker.scope) === scopeLabel(stub.scope);
-      if (!ownerMatches || !scopeMatches) {
+      if (!endpointMarkerOwnsStub(marker, stub)) {
         return {
           ok: false,
           error: `[ModuleRail] composition artifacts: refusing to overwrite incongruent marker ownership at ${path4} (existing owner=${marker.owner} scope=${scopeLabel(marker.scope)} vs planned owner=${stub?.owner ?? "?"} scope=${stub ? scopeLabel(stub.scope) : "?"})`,
@@ -6298,39 +6330,24 @@ async function assertNoRootRoutesWhenMountsEmpty(context, moduleName) {
     );
   }
 }
-async function assertNoEnhancementRoutes(context, moduleName) {
-  const enhancementsDir = `${MODULES_SANDBOX_DIR}/${moduleName}/enhancements`;
-  const enhancementEntries = await listImmediateEntries(context.sandbox, enhancementsDir, {
-    optional: true,
-    label: `enhancements for ${moduleName}`
-  });
-  for (const entry of enhancementEntries) {
-    if (entry.kind !== "dir") continue;
-    const sliceRoutes = `${enhancementsDir}/${entry.name}/routes`;
-    const sliceProbe = await context.sandbox.exec(
-      [
-        `p=${shellQuote(sliceRoutes)}`,
-        `if test -L "$p" || test -e "$p"; then exit 2; else exit 0; fi`
-      ].join("\n"),
-      { raiseOnError: false }
-    );
-    if (sliceProbe.exitCode === 2) {
+async function assertNoEnhancementRoutePaths(context, paths) {
+  const kinds = await classifySandboxPathPresenceKindMany(context, paths, "enhancement-route-kind");
+  for (const sliceRoutes of paths) {
+    const kind = kinds.get(sliceRoutes);
+    if (kind === "absent") continue;
+    if (kind !== "unreadable" && kind !== void 0) {
       throw new Error(
         `[ModuleRail] composition artifacts: enhancement slice routes/ are forbidden at ${sliceRoutes}`
       );
     }
-    if (sliceProbe.exitCode !== 0) {
-      const detail = typeof sliceProbe.error === "string" && sliceProbe.error.trim() || sliceProbe.output.trim() || `exit ${sliceProbe.exitCode}`;
-      throw new Error(
-        `[ModuleRail] composition artifacts: cannot probe ${sliceRoutes}: ${redactSecrets(detail)}`
-      );
-    }
+    throw new Error(
+      `[ModuleRail] composition artifacts: cannot probe ${sliceRoutes}: entry-kind:${kind ?? "missing"}`
+    );
   }
 }
-async function discoverModuleRouteEntries(context, moduleName) {
+async function discoverRootRouteEntries(context, moduleName) {
   const modulePath = `${MODULES_SANDBOX_DIR}/${moduleName}`;
   const routesDir = `${modulePath}/routes`;
-  await assertNoEnhancementRoutes(context, moduleName);
   const quotedRoutes = shellQuote(routesDir);
   const listResult = await context.sandbox.exec(
     [
@@ -6784,7 +6801,8 @@ async function classifySandboxPathPresenceKindMany(context, paths, probeToken) {
         `# Leaf is missing. A missing intermediate parent means the path is simply`,
         `# absent (new nested writes). Only an existing-but-inaccessible parent`,
         `# is unreadable \u2014 never conflate ENOENT parents with EACCES.`,
-        `parent=$(dirname -- "$p")`,
+        // Probe paths are nested repo-relative paths; do not spawn dirname per missing file.
+        `parent=\${p%/*}`,
         `if test ! -e "$parent" && test ! -L "$parent"; then`,
         `  printf 'entry-kind:absent\\t%s\\n' "$p"`,
         `elif ls -ld -- "$parent" >/dev/null 2>&1; then`,
@@ -6968,6 +6986,9 @@ async function readConventionalEntryIfRealFile(path4, kind, presences, files) {
     case "initializeEnhancement":
       assertInitializeEnhancementExport(source, path4);
       break;
+    case "initializeModule":
+      assertInitializeModuleExport(source, path4);
+      break;
   }
   return source;
 }
@@ -7004,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`);
@@ -7092,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(
@@ -7132,6 +7168,7 @@ async function collectCompositionEntryFacts(context, registry) {
       hasRootContributions,
       hasRootSlots,
       hasServerRegistrations,
+      hasRootInitializeServer,
       rootLocales,
       enhancements
     });
@@ -7310,14 +7347,21 @@ async function reconcileCompositionArtifacts(context, options = {}) {
     manifestsByName
   );
   const routeEntriesByOwner = {};
+  await assertNoEnhancementRoutePaths(
+    context,
+    moduleRuntimeFacts.flatMap(
+      ({ moduleName, onDiskEnhancementDirs }) => onDiskEnhancementDirs.map(
+        (peer) => `${MODULES_SANDBOX_DIR}/${moduleName}/enhancements/${peer}/routes`
+      )
+    )
+  );
   for (const moduleName of composedNames) {
     const manifest = manifestsByName[moduleName];
-    await assertNoEnhancementRoutes(context, moduleName);
     if (manifest.mounts.length === 0) {
       await assertNoRootRoutesWhenMountsEmpty(context, moduleName);
       routeEntriesByOwner[moduleName] = [];
     } else {
-      routeEntriesByOwner[moduleName] = await discoverModuleRouteEntries(context, moduleName);
+      routeEntriesByOwner[moduleName] = await discoverRootRouteEntries(context, moduleName);
     }
   }
   const existingGeneratedPaths = await listExistingGeneratedStubPaths(context);

package/dist/index.mjs

@@ -2078,6 +2078,7 @@ var JSON_SECRET_PAIR = new RegExp(
   "g"
 );
 var SECRET_QUOTE_OPENER = new RegExp(String.raw`\b${SECRET_NAME}\s*=\s*(['"])`, "g");
+var SHELL_QUOTE_CONTINUATION = String.raw`\''`;
 function redactSecrets(text) {
   return text.replace(/x-access-token:[^@\s]+@/g, "x-access-token:***@").replace(/https:\/\/(?!x-access-token:)[^/\s:@]+:[^/\s@]+@/gi, "https://***:***@").replace(/\b(gh[pousr]_)[A-Za-z0-9]+/g, "$1***").replace(/\b(github_pat_)[A-Za-z0-9_]+/g, "$1***").replace(/\b(postgres(?:ql)?:\/\/)([^:\s/@]+):([^@\s/]+)@/gi, "$1$2:***@").replace(/\b(npm_[A-Za-z0-9]+)/g, "npm_***").replace(/(_authToken=)([^\s&]+)/gi, "$1***").replace(SECRET_ASSIGNMENT, "$1=***").replace(JSON_SECRET_PAIR, '"$1"$2"***"').replace(/\b(Authorization:\s*(?:Bearer|Basic)\s+)\S+/gi, "$1***");
 }
@@ -2369,10 +2370,12 @@ var modulePermissionClaimSchema = z2.object({
   /** Human label for the deployment auth config row. */
   description: descriptionSchema,
   /**
-   * The default organization roles that hold this key when the platform
-   * first registers it on an app (a Blueprint fork, a Module install). Admin
-   * holds every key without being listed; External Viewer never holds one.
-   * Changing a role's grants afterwards is the organization's business.
+   * The standard organization roles that hold this key. The platform sets them on every app
+   * (a Blueprint fork, a Module install or uninstall, every Blueprint update), so this list is
+   * the truth: a role added here gains the key, a role removed loses it, and nobody can edit a
+   * standard role's grants on a Module key. Admin holds every key without being listed;
+   * External Viewer never holds one. An organization that wants different access duplicates the
+   * standard role and edits the copy.
    */
   roles: z2.array(z2.enum(MODULE_PERMISSION_DEFAULT_ROLES)).optional()
 }).strict();
@@ -3670,17 +3673,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 +3785,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 +4147,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 +4669,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(),
@@ -4795,6 +4821,9 @@ function enhancementImport(owner, peer) {
 function scopeLabel(scope) {
   return scope.kind === "root" ? "root" : `enhancement:${scope.peer}`;
 }
+function endpointMarkerOwnsStub(marker, stub) {
+  return stub != null && marker?.kind === "endpoint" && marker.owner === stub.owner;
+}
 function formatEndpointMarker(owner, scope) {
   return `// ${MODULE_STUB_MARKER} owner=${owner} scope=${scopeLabel(scope)}`;
 }
@@ -5133,6 +5162,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 +5171,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 +5182,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} />;",
     "}",
@@ -5491,7 +5525,7 @@ function planCompositionArtifacts(input) {
     const legacy = parseLegacyApiAdapter(pagePath, content);
     const plannedRoute = plannedRouteByPath.get(pagePath);
     const plannedEndpoint = plannedEndpointByPath.get(pagePath);
-    const isExactPlannedMatch = plannedRoute != null && marker != null && marker.kind === "route" && marker.owner === plannedRoute.owner && marker.nextRelativePath === plannedRoute.nextRelativePath || plannedEndpoint != null && (marker != null && marker.kind === "endpoint" && marker.owner === plannedEndpoint.owner && scopeLabel(marker.scope) === scopeLabel(plannedEndpoint.scope) || legacy != null) || plannedRoute != null && legacyRouteAdapterMatchesStub(pagePath, content, plannedRoute);
+    const isExactPlannedMatch = plannedRoute != null && marker != null && marker.kind === "route" && marker.owner === plannedRoute.owner && marker.nextRelativePath === plannedRoute.nextRelativePath || plannedEndpoint != null && (endpointMarkerOwnsStub(marker, plannedEndpoint) || legacy != null) || plannedRoute != null && legacyRouteAdapterMatchesStub(pagePath, content, plannedRoute);
     if (isExactPlannedMatch) {
       continue;
     }
@@ -5634,9 +5668,7 @@ function planCompositionArtifacts(input) {
     }
     if (marker.kind === "endpoint") {
       const stub = endpointStubByPath.get(path4);
-      const ownerMatches = stub != null && marker.owner === stub.owner;
-      const scopeMatches = stub != null && scopeLabel(marker.scope) === scopeLabel(stub.scope);
-      if (!ownerMatches || !scopeMatches) {
+      if (!endpointMarkerOwnsStub(marker, stub)) {
         return {
           ok: false,
           error: `[ModuleRail] composition artifacts: refusing to overwrite incongruent marker ownership at ${path4} (existing owner=${marker.owner} scope=${scopeLabel(marker.scope)} vs planned owner=${stub?.owner ?? "?"} scope=${stub ? scopeLabel(stub.scope) : "?"})`,
@@ -6279,39 +6311,24 @@ async function assertNoRootRoutesWhenMountsEmpty(context, moduleName) {
     );
   }
 }
-async function assertNoEnhancementRoutes(context, moduleName) {
-  const enhancementsDir = `${MODULES_SANDBOX_DIR}/${moduleName}/enhancements`;
-  const enhancementEntries = await listImmediateEntries(context.sandbox, enhancementsDir, {
-    optional: true,
-    label: `enhancements for ${moduleName}`
-  });
-  for (const entry of enhancementEntries) {
-    if (entry.kind !== "dir") continue;
-    const sliceRoutes = `${enhancementsDir}/${entry.name}/routes`;
-    const sliceProbe = await context.sandbox.exec(
-      [
-        `p=${shellQuote(sliceRoutes)}`,
-        `if test -L "$p" || test -e "$p"; then exit 2; else exit 0; fi`
-      ].join("\n"),
-      { raiseOnError: false }
-    );
-    if (sliceProbe.exitCode === 2) {
+async function assertNoEnhancementRoutePaths(context, paths) {
+  const kinds = await classifySandboxPathPresenceKindMany(context, paths, "enhancement-route-kind");
+  for (const sliceRoutes of paths) {
+    const kind = kinds.get(sliceRoutes);
+    if (kind === "absent") continue;
+    if (kind !== "unreadable" && kind !== void 0) {
       throw new Error(
         `[ModuleRail] composition artifacts: enhancement slice routes/ are forbidden at ${sliceRoutes}`
       );
     }
-    if (sliceProbe.exitCode !== 0) {
-      const detail = typeof sliceProbe.error === "string" && sliceProbe.error.trim() || sliceProbe.output.trim() || `exit ${sliceProbe.exitCode}`;
-      throw new Error(
-        `[ModuleRail] composition artifacts: cannot probe ${sliceRoutes}: ${redactSecrets(detail)}`
-      );
-    }
+    throw new Error(
+      `[ModuleRail] composition artifacts: cannot probe ${sliceRoutes}: entry-kind:${kind ?? "missing"}`
+    );
   }
 }
-async function discoverModuleRouteEntries(context, moduleName) {
+async function discoverRootRouteEntries(context, moduleName) {
   const modulePath = `${MODULES_SANDBOX_DIR}/${moduleName}`;
   const routesDir = `${modulePath}/routes`;
-  await assertNoEnhancementRoutes(context, moduleName);
   const quotedRoutes = shellQuote(routesDir);
   const listResult = await context.sandbox.exec(
     [
@@ -6765,7 +6782,8 @@ async function classifySandboxPathPresenceKindMany(context, paths, probeToken) {
         `# Leaf is missing. A missing intermediate parent means the path is simply`,
         `# absent (new nested writes). Only an existing-but-inaccessible parent`,
         `# is unreadable \u2014 never conflate ENOENT parents with EACCES.`,
-        `parent=$(dirname -- "$p")`,
+        // Probe paths are nested repo-relative paths; do not spawn dirname per missing file.
+        `parent=\${p%/*}`,
         `if test ! -e "$parent" && test ! -L "$parent"; then`,
         `  printf 'entry-kind:absent\\t%s\\n' "$p"`,
         `elif ls -ld -- "$parent" >/dev/null 2>&1; then`,
@@ -6949,6 +6967,9 @@ async function readConventionalEntryIfRealFile(path4, kind, presences, files) {
     case "initializeEnhancement":
       assertInitializeEnhancementExport(source, path4);
       break;
+    case "initializeModule":
+      assertInitializeModuleExport(source, path4);
+      break;
   }
   return source;
 }
@@ -6985,7 +7006,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 +7098,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 +7149,7 @@ async function collectCompositionEntryFacts(context, registry) {
       hasRootContributions,
       hasRootSlots,
       hasServerRegistrations,
+      hasRootInitializeServer,
       rootLocales,
       enhancements
     });
@@ -7291,14 +7328,21 @@ async function reconcileCompositionArtifacts(context, options = {}) {
     manifestsByName
   );
   const routeEntriesByOwner = {};
+  await assertNoEnhancementRoutePaths(
+    context,
+    moduleRuntimeFacts.flatMap(
+      ({ moduleName, onDiskEnhancementDirs }) => onDiskEnhancementDirs.map(
+        (peer) => `${MODULES_SANDBOX_DIR}/${moduleName}/enhancements/${peer}/routes`
+      )
+    )
+  );
   for (const moduleName of composedNames) {
     const manifest = manifestsByName[moduleName];
-    await assertNoEnhancementRoutes(context, moduleName);
     if (manifest.mounts.length === 0) {
       await assertNoRootRoutesWhenMountsEmpty(context, moduleName);
       routeEntriesByOwner[moduleName] = [];
     } else {
-      routeEntriesByOwner[moduleName] = await discoverModuleRouteEntries(context, moduleName);
+      routeEntriesByOwner[moduleName] = await discoverRootRouteEntries(context, moduleName);
     }
   }
   const existingGeneratedPaths = await listExistingGeneratedStubPaths(context);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stardeck-customer-apps/compose",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "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",
@@ -34,7 +34,7 @@
     "build": "rm -rf dist && tsup",
     "dev": "tsup --watch",
     "format": "prettier --write . && oxlint . --fix",
-    "typecheck": "tsgo -p tsconfig.test.json",
+    "typecheck": "node ../../scripts/typecheck.mjs -p tsconfig.test.json",
     "lint": "oxlint src/",
     "test": "vitest run",
     "test:watch": "vitest"