@cosmicdrift/kumiko-dev-server 0.48.1 → 0.50.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.48.1",
+  "version": "0.50.0",
   "description": "Development server bootstrap for Kumiko apps. Bundles the client, mints dev-JWTs, injects the resolved AppSchema, and seeds an admin. Not for production.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/src/__tests__/config-resolver-default.integration.test.ts

@@ -0,0 +1,97 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  configValuesTable,
+  createConfigAccessorFactory,
+  createConfigFeature,
+  createConfigResolver,
+} from "@cosmicdrift/kumiko-bundled-features/config";
+import { access, createTenantConfig, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { mergeConfigResolverDefault } from "../run-dev-app";
+
+// Pins runDevApp's ENV→config-app-override wiring: mergeConfigResolverDefault
+// builds the auth-mode configResolver-default with the ENV bridge (a key with
+// `env:` gets its env value as the app-override default, symmetric to
+// runProdApp), the envSource is injected (never the real process.env), and a
+// caller-supplied configResolver still overrides the default.
+
+const PAGE_SIZE = "devcfg:config:page-size";
+
+const devcfgFeature = defineFeature("devcfg", (r) => {
+  r.requires("config");
+  r.config({
+    keys: {
+      pageSize: createTenantConfig("number", {
+        env: "DEVCFG_PAGE_SIZE",
+        default: 10,
+        read: access.all,
+        write: access.all,
+      }),
+    },
+  });
+});
+
+// ctx=undefined → object form, configResolver is the only key (test boundary).
+type ExtraObj = { configResolver: ReturnType<typeof createConfigResolver> };
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [createConfigFeature(), devcfgFeature],
+    extraContext: ({ registry }) => {
+      const bootResolver = createConfigResolver();
+      return {
+        configResolver: bootResolver,
+        _configAccessorFactory: createConfigAccessorFactory(registry, bootResolver),
+      };
+    },
+  });
+  await unsafePushTables(stack.db, { configValuesTable });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+function resolverFor(envSource: Record<string, string | undefined>) {
+  const extra = mergeConfigResolverDefault(undefined, stack.registry, envSource) as ExtraObj;
+  return extra.configResolver;
+}
+
+function peekPageSize(resolver: ReturnType<typeof createConfigResolver>) {
+  const keyDef = stack.registry.getConfigKey(PAGE_SIZE);
+  if (!keyDef) throw new Error("page-size key missing from registry");
+  return resolver.get(
+    PAGE_SIZE,
+    keyDef,
+    TestUsers.systemAdmin.tenantId,
+    TestUsers.systemAdmin.id,
+    stack.db,
+  );
+}
+
+describe("runDevApp configResolver-default — ENV→app-override bridge", () => {
+  test("a key with `env:` resolves to the injected env value as app-override", async () => {
+    const value = await peekPageSize(resolverFor({ DEVCFG_PAGE_SIZE: "25" }));
+    expect(value).toBe(25); // number, coerced from env — not 10 (keyDef.default)
+  });
+
+  test("no env value → falls to keyDef.default (bridge is conditional, not always-on)", async () => {
+    const value = await peekPageSize(resolverFor({}));
+    expect(value).toBe(10);
+  });
+
+  test("a caller-supplied configResolver overrides the default", () => {
+    const custom = createConfigResolver();
+    const extra = mergeConfigResolverDefault({ configResolver: custom }, stack.registry, {
+      DEVCFG_PAGE_SIZE: "25",
+    }) as ExtraObj;
+    expect(extra.configResolver).toBe(custom);
+  });
+});

package/src/__tests__/renderer-web-css-relocation.integration.test.ts

@@ -0,0 +1,82 @@
+// Relocation-Test für den @source-Layout-Fix (#359).
+//
+// Der Bug: renderer-web/src/styles.css scannte seine eigenen Shell-Klassen
+// über einen MONOREPO-relativen @source (`../../renderer-web/src`). Im
+// Workspace löst der via Symlink auf (grün), in einem Standalone-Consumer
+// (echtes node_modules ohne Monorepo-Geschwister) findet er nichts → unstyled
+// prod (15KB statt 48KB). Der Fix macht die Zeile self-relativ (`./`), weil
+// das Paket `src` shippt.
+//
+// Am REALEN Ort der styles.css sind `./` und `../../renderer-web/src`
+// identisch — ein Test dort wäre grün mit Bug UND Fix. Der Diskriminator ist
+// RELOCATION: wir kopieren die echte styles.css an einen Ort, an dem der alte
+// Pfad tot ist und nur `./` greift. Der Ort liegt unter dem Repo-Root, damit
+// `@import "tailwindcss"` / `react-day-picker` weiter über node_modules
+// auflösen. Braucht Bun (Bun.spawn im Tailwind-One-Shot) — sonst silent skip.
+
+import { describe, expect, test } from "bun:test";
+import { execFileSync } from "node:child_process";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runTailwindOnce } from "../build-prod-bundle";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, "../../../..");
+const RENDERER_WEB_STYLES = resolve(__dirname, "../../../renderer-web/src/styles.css");
+const SELF_SOURCE = '@source "./**/*.{ts,tsx}";';
+const MONOREPO_SOURCE = '@source "../../renderer-web/src/**/*.{ts,tsx}";';
+
+function bunAvailable(): boolean {
+  try {
+    execFileSync("bun", ["--version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+describe("renderer-web styles.css @source relocation (#359)", () => {
+  test("self-relative @source scans the shell standalone; monorepo path would not", async () => {
+    if (!bunAvailable()) return;
+
+    // Tailwind v4 auto-scannt nur das cwd-Verzeichnis (empirisch bestätigt:
+    // das Verzeichnis der Input-CSS wird NICHT automatisch gescannt). Im echten
+    // Standalone-Consumer ist renderer-web zudem in node_modules (gitignored) →
+    // ebenfalls nicht auto-gescannt. Die Shell-Klassen erreicht also NUR der
+    // explizite @source der styles.css. Hier mirrorn wir das robust, ohne
+    // gitignore-/node_modules-Semantik: das Paket-`src` (mit der Shell-Probe)
+    // liegt AUSSERHALB des Build-cwd — nur der self-relative `@source "./**"`
+    // der relozierten styles.css erreicht es, der monorepo-Pfad ist tot.
+    // Temp unter REPO_ROOT, damit @import "tailwindcss"/react-day-picker via
+    // node_modules auflösen.
+    const dir = await mkdtemp(join(REPO_ROOT, ".reloc-rendererweb-"));
+    const buildCwd = join(dir, "app");
+    const pkgSrc = join(dir, "pkg");
+    try {
+      const realCss = await readFile(RENDERER_WEB_STYLES, "utf8");
+      // Guard: der Fix MUSS in der Quelle stehen, sonst testet die Relocation nichts.
+      expect(realCss).toContain(SELF_SOURCE);
+
+      await mkdir(buildCwd, { recursive: true });
+      await mkdir(join(pkgSrc, "layout"), { recursive: true });
+      await writeFile(
+        join(pkgSrc, "layout/probe.tsx"),
+        `export const P = () => <div className="min-h-screen" />;\n`,
+      );
+
+      await writeFile(join(pkgSrc, "styles.css"), realCss);
+      const fixed = await runTailwindOnce(join(pkgSrc, "styles.css"), buildCwd);
+      expect(fixed).toContain("min-h-screen");
+
+      // Diskriminator: mit dem ALTEN monorepo-relativen @source ist die Probe
+      // an diesem relozierten Ort unerreichbar → Sentinel fehlt. Beweist, dass
+      // der Fix kein No-op ist (der Test würde bei einem Revert rot).
+      await writeFile(join(pkgSrc, "styles.css"), realCss.replace(SELF_SOURCE, MONOREPO_SOURCE));
+      const buggy = await runTailwindOnce(join(pkgSrc, "styles.css"), buildCwd);
+      expect(buggy).not.toContain("min-h-screen");
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/__tests__/renderer-web-shell-sentinel.test.ts

@@ -0,0 +1,35 @@
+// Unit-Test für den CSS-Completeness-Guard (#359): nach dem Tailwind-One-Shot
+// prüft der Build, ob das Output-CSS die renderer-web-Shell-Sentinel-Klasse
+// enthält — aber NUR wenn auf das gepackte renderer-web-styles.css
+// zurückgefallen wurde. Fehlt sie dort, würde prod unstyled rendern → laut
+// failen mit Hinweis auf src/styles.css.
+
+import { describe, expect, test } from "bun:test";
+import { assertRendererWebShellPresent } from "../build-prod-bundle";
+
+const fallback = {
+  path: "/app/node_modules/renderer-web/src/styles.css",
+  isRendererWebFallback: true,
+};
+const appOwned = { path: "/app/src/styles.css", isRendererWebFallback: false };
+
+describe("assertRendererWebShellPresent (#359 CSS-completeness guard)", () => {
+  test("fallback + fehlende Shell-Sentinel-Klasse → wirft mit src/styles.css-Hinweis", () => {
+    expect(() => assertRendererWebShellPresent(".some-other{display:flex}", fallback)).toThrow(
+      /min-h-screen/,
+    );
+    expect(() => assertRendererWebShellPresent(".some-other{display:flex}", fallback)).toThrow(
+      /src\/styles\.css/,
+    );
+  });
+
+  test("fallback + Shell-Sentinel vorhanden → kein Throw", () => {
+    expect(() =>
+      assertRendererWebShellPresent(".min-h-screen{min-height:100vh}", fallback),
+    ).not.toThrow();
+  });
+
+  test("app-eigenes styles.css (kein Fallback) → nie asserten, auch ohne Sentinel", () => {
+    expect(() => assertRendererWebShellPresent("", appOwned)).not.toThrow();
+  });
+});

package/src/__tests__/run-dev-app-boot-validation.test.ts

@@ -0,0 +1,33 @@
+// runDevApp muss denselben Boot-Validator wie runProdApp ausführen (#359):
+// eine ganze Fehlerklasse (unqualifizierte nav-/handler-QNs, unauflösbare
+// navigate-Targets, screen-access) passierte früher den Dev-Server still und
+// crashte erst den Prod-Pod im CrashLoopBackOff. Hier: ein Feature mit einem
+// rowAction-navigate auf einen nie registrierten Screen — runDevApp muss
+// SYNCHRON beim Boot werfen, bevor ein Port gebunden oder der codegen-Watcher
+// gestartet wird (validateBoot läuft vor watchAndRegenerate).
+
+import { describe, expect, test } from "bun:test";
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { runDevApp } from "../run-dev-app";
+
+function unresolvableNavFeature() {
+  return defineFeature("shop", (r) => {
+    r.entity("product", createEntity({ fields: { name: createTextField() } }));
+    r.screen({
+      id: "product-list",
+      type: "entityList",
+      entity: "product",
+      columns: ["name"],
+      // "ghost-screen" wird nie via r.screen registriert → validateBoot wirft.
+      rowActions: [{ kind: "navigate", id: "edit", label: "actions.edit", screen: "ghost-screen" }],
+    });
+  });
+}
+
+describe("runDevApp boot-validation (#359)", () => {
+  test("unresolvable navigate-target throws at boot — dev/prod parity, no port bound", async () => {
+    await expect(runDevApp({ features: [unresolvableNavFeature()] })).rejects.toThrow(
+      /navigate-target "ghost-screen" does not resolve/,
+    );
+  });
+});

package/src/boot/apply-boot-seeds.ts

@@ -8,6 +8,7 @@ import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
 // missing call site (e.g. someone deletes the line from runDevApp)
 // surfaces as a missing-helper-use in code review rather than silently
 // shipping a server that never seeds.
+// @wrapper-known semantic-alias
 export async function applyBootSeeds(deps: {
   registry: Registry;
   db: DbConnection;

package/src/build-prod-bundle.ts

@@ -139,7 +139,8 @@ export async function buildProdBundle(options: BuildProdBundleOptions = {}): Pro
   //    der client.tsx ein "import './foo.css'" macht — den Fall lassen
   //    wir hier raus, Tailwind ist die einzige CSS-Quelle).
   if (stylesheet) {
-    const css = await runTailwindOnce(stylesheet, cwd);
+    const css = await runTailwindOnce(stylesheet.path, cwd);
+    assertRendererWebShellPresent(css, stylesheet);
     const hash = shortHash(css);
     const filename = `styles-${hash}.css`;
     await writeFile(join(assetsDir, filename), css);
@@ -284,17 +285,32 @@ export function discoverClientEntry(cwd: string): string | undefined {
   return only?.name === "client" ? only.sourceFile : undefined;
 }
 
+type ResolvedStylesheet = {
+  readonly path: string;
+  /** True nur wenn wir auf das gepackte renderer-web-styles.css zurückfallen
+   *  (App hat clientEntry + renderer-web-Dep, aber kein eigenes src/styles.css).
+   *  Steuert den Shell-Klassen-Sentinel im Build. */
+  readonly isRendererWebFallback: boolean;
+};
+
+// Äußerster Wrapper von DefaultAppShell/WorkspaceShell trägt diese Utility
+// (app-layout.tsx: "flex min-h-screen …"). Echtes Tailwind-Utility (landet
+// also im kompilierten Output) ohne CSS-Escaping → stabiler Substring-Sentinel.
+const RENDERER_WEB_SHELL_SENTINEL = "min-h-screen";
+
 function resolveStylesheetEntry(
   cwd: string,
   clientEntry: string | undefined,
   override: BuildProdBundleOptions["stylesheet"],
-): string | undefined {
+): ResolvedStylesheet | undefined {
   if (override === false) return undefined;
-  if (typeof override === "string") return resolve(cwd, override);
+  if (typeof override === "string") {
+    return { path: resolve(cwd, override), isRendererWebFallback: false };
+  }
 
   // App-eigenes styles.css schlägt den Default.
   const local = resolve(cwd, "src/styles.css");
-  if (existsSync(local)) return local;
+  if (existsSync(local)) return { path: local, isRendererWebFallback: false };
 
   // Sonst: nur wenn ein client da ist, fallback auf renderer-web/styles.css.
   // Sample-Apps und Showcases nutzen das alle — gleiche Logik wie der dev-
@@ -310,12 +326,30 @@ function resolveStylesheetEntry(
     if (!canResolveTailwindStylesheet(resolved, { bun, cwd })) {
       return undefined;
     }
-    return resolved;
+    return { path: resolved, isRendererWebFallback: true };
   } catch {
     return undefined;
   }
 }
 
+// Build-Zeit-Guard gegen unstyled prod (#359): fällt der Build auf renderer-
+// web/styles.css zurück und fehlt im kompilierten CSS die Shell-Sentinel-
+// Klasse, wurden die DefaultAppShell-Styles nicht gescannt (renderer-web
+// nicht dort installiert wo Tailwind scannt, oder ein @source-Regress).
+// Laut failen statt ein 15KB-Image zu liefern, das in prod nackt rendert.
+// @internal — exportiert nur für Unit-Tests.
+export function assertRendererWebShellPresent(css: string, stylesheet: ResolvedStylesheet): void {
+  if (!stylesheet.isRendererWebFallback) return;
+  if (css.includes(RENDERER_WEB_SHELL_SENTINEL)) return;
+  throw new Error(
+    `[kumiko build] renderer-web-Fallback-CSS ohne Shell-Klasse "${RENDERER_WEB_SHELL_SENTINEL}" — ` +
+      "die DefaultAppShell/WorkspaceShell-Styles fehlen, prod würde unstyled rendern. Meist ist " +
+      "@cosmicdrift/kumiko-renderer-web nicht dort installiert wo Tailwind seine Source scannt. " +
+      'Fix: src/styles.css anlegen mit `@import "@cosmicdrift/kumiko-renderer-web/styles.css";` ' +
+      '(+ `@source "./**/*.{ts,tsx}";` um auch eigene Komponenten zu scannen).',
+  );
+}
+
 // @internal — exported nur für Unit-Tests.
 export function discoverHtmlTemplate(cwd: string): string | undefined {
   for (const candidate of ["index.html", "public/index.html"]) {
@@ -329,7 +363,8 @@ export function discoverHtmlTemplate(cwd: string): string | undefined {
 // Build steps
 // ---------------------------------------------------------------------------
 
-async function runTailwindOnce(entry: string, cwd: string): Promise<string> {
+// @internal — exportiert nur für Unit-Tests (Relocation-Test des @source-Layouts).
+export async function runTailwindOnce(entry: string, cwd: string): Promise<string> {
   if (!hasBun) {
     throw new Error(
       "[kumiko build] Tailwind one-shot requires Bun (Bun.spawn) — run via `bun run …` or `bun kumiko build`.",

package/src/build-server-bundle.ts

@@ -267,6 +267,7 @@ export function formatServerBuildResult(
   const dim = "\x1b[2m";
   const green = "\x1b[32m";
   const reset = "\x1b[0m";
+  // @wrapper-known semantic-alias
   const mb = (bytes: number): string => (bytes / 1024 / 1024).toFixed(2);
   const lines: string[] = [];
   lines.push("");

package/src/create-kumiko-server.ts

@@ -49,8 +49,10 @@ const hasBun = typeof (globalThis as { Bun?: unknown }).Bun !== "undefined";
 type BunServer = typeof Bun extends undefined ? unknown : ReturnType<typeof Bun.serve>;
 
 // biome-ignore lint/suspicious/noConsole: dev-server status logging
+// @wrapper-known semantic-alias
 const logInfo = (msg: string): void => console.log(msg);
 // biome-ignore lint/suspicious/noConsole: dev-server error logging
+// @wrapper-known semantic-alias
 const logError = (...args: unknown[]): void => console.error(...args);
 
 /** Multi-Entry-Mode für Apps die mehrere getrennte Bundles ausliefern

package/src/kebab.ts

@@ -2,6 +2,7 @@
 // package-name + folder (`my-shop`, not `my-` or `my--shop`).
 const KEBAB_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 
+// @wrapper-known semantic-alias
 export function isKebabSegment(value: string): boolean {
   return KEBAB_RE.test(value);
 }

package/src/run-dev-app.ts

@@ -18,7 +18,10 @@ import {
   type SeedAdminOptions,
   seedAdmin,
 } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
-import { createConfigResolver } from "@cosmicdrift/kumiko-bundled-features/config";
+import {
+  buildEnvConfigOverrides,
+  createConfigResolver,
+} from "@cosmicdrift/kumiko-bundled-features/config";
 import {
   createSessionCallbacks,
   type SessionCallbacks,
@@ -26,12 +29,15 @@ import {
 import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
 import type { SessionMetadata } from "@cosmicdrift/kumiko-framework/api";
 import {
+  createRegistry,
   type EffectiveFeaturesResolver,
   type FeatureDefinition,
   findTierResolverUsage,
+  type Registry,
   type SessionUser,
   type TenantId,
   type TierResolverPlugin,
+  validateBoot,
 } from "@cosmicdrift/kumiko-framework/engine";
 import type { TestStack } from "@cosmicdrift/kumiko-framework/stack";
 import { applyBootSeeds } from "./boot/apply-boot-seeds";
@@ -140,6 +146,11 @@ export type RunDevAppOptions = {
   /** Extra-AppContext-Keys. Im auth-mode wird `configResolver` automatisch
    *  hinzugefügt — kein Override durch den Caller nötig. */
   readonly extraContext?: CreateKumikoServerOptions["extraContext"];
+  /** Env-Quelle für die ENV→config-app-override-Brücke (Keys mit `env:`
+   *  bekommen ihren env-Wert als app-override-Default — symmetrisch zu
+   *  runProdApp). Default `process.env`. Injizierbar als Test-Seam, damit
+   *  Tests eigene env-Werte reichen statt `process.env` global zu mutieren. */
+  readonly envSource?: Record<string, string | undefined>;
   /** Anonymous-Access für Public-Endpoints — Requests ohne JWT laufen
    *  als Pseudo-User mit Rolle `anonymous` durch, wenn der Handler die
    *  Rolle in `access.roles` führt. */
@@ -158,6 +169,23 @@ export type RunDevAppOptions = {
 };
 
 export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServerHandle> {
+  // Auto-mix Standard-Features im auth-mode via composeFeatures (single
+  // source of truth — auch runProdApp und der per-app drizzle-Schema-
+  // Generator nutzen denselben Helper, damit Migration und Runtime nie
+  // auseinanderdriften können).
+  const composeAuthOptions = buildComposeAuthOptions(options.auth);
+  const features = composeFeatures(options.features, {
+    includeBundled: !!options.auth,
+    ...(composeAuthOptions && { authOptions: composeAuthOptions }),
+  });
+
+  // Boot-Validation als allererstes — vor fs-Watcher und Server. Dieselbe
+  // Fehlerklasse (unqualifizierte nav-/handler-QNs, screen-access etc.),
+  // die früher nur runProdApp fing und sonst erst den Prod-Pod im
+  // CrashLoopBackOff sterben ließ (#359). Wirft synchron, bevor ein
+  // Socket oder Watcher (codegen-Write) aufgeht.
+  validateBoot(features);
+
   // Codegen + File-Watcher — schreibt `<appRoot>/.kumiko/types.generated.d.ts`
   // + `define.ts` aus den r.defineEvent-Aufrufen der App, einmal beim
   // Boot UND danach bei jeder relevanten Änderung unter `<appRoot>/src/`.
@@ -170,16 +198,6 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
   // process-exit räumt fs.watch-handles auf).
   watchAndRegenerate({ appRoot: process.cwd() });
 
-  // Auto-mix Standard-Features im auth-mode via composeFeatures (single
-  // source of truth — auch runProdApp und der per-app drizzle-Schema-
-  // Generator nutzen denselben Helper, damit Migration und Runtime nie
-  // auseinanderdriften können).
-  const composeAuthOptions = buildComposeAuthOptions(options.auth);
-  const features = composeFeatures(options.features, {
-    includeBundled: !!options.auth,
-    ...(composeAuthOptions && { authOptions: composeAuthOptions }),
-  });
-
   // Sprint-8a Tier-Composition auto-wire: scan features for a
   // tenantTierResolver-extension. If found AND user didn't supply own
   // effectiveFeatures, we wire a late-bound wrapper here and fill it
@@ -210,9 +228,17 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
   // configResolver-default fürs config-feature — im auth-mode immer
   // hinzufügen, im no-auth-mode dem Caller überlassen. Factory-form
   // wird gewrap't damit der spread auf das aufgerufene Result greift,
-  // nicht auf die function selbst (no-op).
+  // nicht auf die function selbst (no-op). Die ENV→config-Brücke (Keys mit
+  // `env:` → app-override-Default) läuft symmetrisch zu runProdApp; die
+  // throwaway-Registry hier extrahiert nur die config-Keys, weil der
+  // configResolver vor dem Server-Boot konstruiert wird (stack.registry
+  // gibt's erst onAfterSetup) — createKumikoServer baut intern seine eigene.
   const extraContext = options.auth
-    ? mergeConfigResolverDefault(options.extraContext)
+    ? mergeConfigResolverDefault(
+        options.extraContext,
+        createRegistry(features),
+        options.envSource ?? process.env,
+      )
     : options.extraContext;
 
   // Sessions opt-in: Holder lebt im closure, `createSessionCallbacks`
@@ -343,10 +369,20 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
   });
 }
 
-function mergeConfigResolverDefault(
+// Exported for the wiring-contract test (config-resolver-default.integration):
+// pins that the dev configResolver-default carries the ENV→app-override bridge
+// and that a caller-supplied configResolver still overrides it. Not re-exported
+// from the package barrel (index.ts lists only runDevApp).
+export function mergeConfigResolverDefault(
   ctx: CreateKumikoServerOptions["extraContext"],
+  registry: Registry,
+  envSource: Record<string, string | undefined>,
 ): CreateKumikoServerOptions["extraContext"] {
-  const defaults = { configResolver: createConfigResolver() };
+  const defaults = {
+    configResolver: createConfigResolver({
+      appOverrides: buildEnvConfigOverrides(registry, envSource),
+    }),
+  };
   if (ctx === undefined) return defaults;
   if (typeof ctx === "function") {
     return (deps) => ({ ...defaults, ...ctx(deps) });

package/src/run-prod-app.ts

@@ -36,7 +36,10 @@ import {
   type SeedAdminOptions,
   seedAdmin,
 } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
-import { createConfigResolver } from "@cosmicdrift/kumiko-bundled-features/config";
+import {
+  buildEnvConfigOverrides,
+  createConfigResolver,
+} from "@cosmicdrift/kumiko-bundled-features/config";
 import { createSessionCallbacks } from "@cosmicdrift/kumiko-bundled-features/sessions";
 import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
 import { UserQueries } from "@cosmicdrift/kumiko-bundled-features/user";
@@ -668,7 +671,12 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
       ? options.extraContext(deps)
       : (options.extraContext ?? {});
   const extraContext = options.auth
-    ? { configResolver: createConfigResolver(), ...resolvedExtraContext }
+    ? {
+        configResolver: createConfigResolver({
+          appOverrides: buildEnvConfigOverrides(registry, envSource),
+        }),
+        ...resolvedExtraContext,
+      }
     : resolvedExtraContext;
   const resolvedAnonymousAccess =
     typeof options.anonymousAccess === "function"
@@ -825,6 +833,7 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
       seedsDir: options.seedsDir,
       appliedBy: "boot",
       registry, // → dry-run-validator catched handler-QN-typos vor dem write
+      // @wrapper-known semantic-alias
       createContext: (dbRunner: DbRunner) =>
         createSeedMigrationContext({ dispatcher: seedDispatcher, dbRunner }),
     });

package/src/scaffold-app.ts

@@ -73,6 +73,7 @@ export function scaffoldApp(options: ScaffoldAppOptions): ScaffoldAppResult {
   return { destination, files, appName: options.name };
 }
 
+// @wrapper-known semantic-alias
 function write(path: string, content: string): void {
   writeFileSync(path, content);
 }
@@ -334,6 +335,7 @@ function deriveTenantId(name: string): string {
     state ^= ch.charCodeAt(0);
     state = Math.imul(state, 16777619) >>> 0;
   }
+  // @wrapper-known semantic-alias
   const hex = (n: number, len: number): string => n.toString(16).padStart(len, "0").slice(0, len);
   const a = hex(state, 8);
   state ^= state << 13;