@cosmicdrift/kumiko-dev-server 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @cosmicdrift/kumiko-dev-server
 
+## 0.8.0
+
+### Minor Changes
+
+- f34af9a: Add framework-core env-schema (Sprint 9.2, Migration Phase 1).
+
+  **New API:**
+
+  - `frameworkCoreEnvSchema` exported from `@cosmicdrift/kumiko-dev-server` — Zod-object covering the vars read by framework-core: `PORT` (default `"3000"`), `DATABASE_URL`, `REDIS_URL`, `KUMIKO_INSTANCE_ID`, `KUMIKO_SKIP_ES_OPS`. `DATABASE_URL` + `REDIS_URL` carry `.meta({ kumiko: { pulumi: { secret: true } } })` so `KUMIKO_DRY_RUN_ENV=pulumi` emits `--secret` flags. Plus `FrameworkCoreEnv` type via `z.infer`. `NODE_ENV` is excluded: build-prod-bundle inlines it as a literal at build-time (esbuild define), so runtime env-validation can't observe it.
+  - `composeEnvSchema({ core, features, extend, optionalFeatures })` accepts a new `core?` option. Keys from `core` are tagged with source `"framework-core"` in the resulting sources map and in `KumikoBootError.format()` output. Conflict detection runs across core/features/extend — a feature or `extend` block that re-declares a core var throws `KumikoBootError` at compose-time.
+
+  **Why:** Phase 1 of the Sprint 9 env-schema migration (`kumiko-studio/docs/plans/sprint-9-env-schemas.md`). Apps wire `composeEnvSchema({ core: frameworkCoreEnvSchema, features, extend })` into `runProdApp` to get aggregated boot-validation for the vars that framework-core reads. `KUMIKO_DRY_RUN_ENV=pulumi|k8s` then enumerates them with source attribution per row — operators see "(framework-core)" next to `DATABASE_URL` rather than guessing whether the framework or the app is the consumer.
+
+  **Backward-compat:** Purely additive. `runProdApp`'s existing `requireEnv("DATABASE_URL")` / `process.env["KUMIKO_INSTANCE_ID"]` reads remain unchanged. Apps that don't pass `envSchema` behave exactly as before.
+
+  **Feature-specific vars (Phase 2):** `JWT_SECRET` (auth-email-password), `KUMIKO_SECRETS_MASTER_KEY_*` (secrets), `SMTP_*` (channel-email-smtp), `STRIPE_*` / `MOLLIE_*` (subscription-\*) stay scoped to their owning feature's `r.envSchema()` and are NOT in `frameworkCoreEnvSchema`.
+
+- dff4123: Add Zod-based env-schema declarations and boot-time validation (Sprint 9.1).
+
+  **New API:**
+
+  - `r.envSchema(z.object({...}))` — declare per-feature env-vars at registration time.
+  - `@cosmicdrift/kumiko-framework/env`: `composeEnvSchema({features, extend, optionalFeatures})` merges feature schemas into one app-wide schema, returning `{schema, sources}`. `parseEnv(schema, env, {sources, pulumiPrefix})` validates `process.env` and throws `KumikoBootError` listing ALL problems at once (aggregated, not first-fail).
+  - `@cosmicdrift/kumiko-framework/env/dry-run`: `renderDryRun(composed, mode, opts)` for `human|json|pulumi|k8s` introspection of the required env-vars without booting.
+  - `runProdApp({envSchema, pulumiPrefix, bootErrorReporter, envSource})` runs schema validation before any DB/Redis connection. `KUMIKO_DRY_RUN_ENV=1|human|json|pulumi|k8s` prints the inventory and exits.
+  - Per-var metadata via Zod's `.meta({ kumiko: { pulumi: { name, generator, secret } } })` for deploy-time tooling overrides.
+
+  **Backward-compat:** Apps without `envSchema` keep working — existing `requireEnv("DATABASE_URL")` calls in `runProdApp` are untouched. Sprint-9.2-9.5 migrates framework + bundled-features + apps to schema-only env handling.
+
+  **Why:** 2026-05-21 Studio deploy stacked 7 hacks chasing missing env-vars (10+ pipeline-fail iterations, ended in rollback). Schema-first boot validation surfaces ALL misconfigs upfront with `pulumi config set …` suggestions, replacing the discover-by-failing loop with a single dry-run + secrets-bootstrap pass.
+
+### Patch Changes
+
+- Updated dependencies [145b8df]
+- Updated dependencies [f34af9a]
+- Updated dependencies [dff4123]
+  - @cosmicdrift/kumiko-bundled-features@0.8.0
+  - @cosmicdrift/kumiko-framework@0.8.0
+
 ## 0.7.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.7.0",
+  "version": "0.8.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>",
@@ -48,8 +48,8 @@
     "kumiko-dev": "./bin/kumiko-dev.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.7.0",
-    "@cosmicdrift/kumiko-framework": "0.7.0"
+    "@cosmicdrift/kumiko-bundled-features": "0.8.0",
+    "@cosmicdrift/kumiko-framework": "0.8.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/__tests__/env-schema.integration.ts

@@ -0,0 +1,185 @@
+// Integration-style spec for runProdApp's envSchema boot-stage.
+// Focus: the env-validation path BEFORE any DB/Redis connection.
+// We never reach `requireEnv("DATABASE_URL")` here — invalid env
+// throws (via bootErrorReporter override) and KUMIKO_DRY_RUN_ENV
+// returns the dry-run handle without booting.
+
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { composeEnvSchema, KumikoBootError } from "@cosmicdrift/kumiko-framework/env";
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { frameworkCoreEnvSchema } from "../env-schema";
+import * as devServerPublicApi from "../index";
+import { runProdApp } from "../run-prod-app";
+
+const secretsFeature = defineFeature("secrets", (r) => {
+  r.envSchema(
+    z.object({
+      KUMIKO_SECRETS_MASTER_KEY_V1: z
+        .string()
+        .describe("AES-256 KEK")
+        .meta({ kumiko: { pulumi: { generator: "openssl rand -base64 32", secret: true } } }),
+    }),
+  );
+});
+
+const authFeature = defineFeature("auth-email-password", (r) => {
+  r.envSchema(
+    z.object({
+      JWT_SECRET: z.string().min(32).describe("JWT signing key"),
+    }),
+  );
+});
+
+const composed = composeEnvSchema({
+  features: [secretsFeature, authFeature],
+  extend: z.object({
+    STUDIO_ADMIN_EMAIL: z.email(),
+  }),
+});
+
+describe("public-export smoke", () => {
+  it("re-exports frameworkCoreEnvSchema via dev-server's package entry", () => {
+    expect(devServerPublicApi.frameworkCoreEnvSchema).toBe(frameworkCoreEnvSchema);
+  });
+});
+
+describe("runProdApp envSchema integration", () => {
+  it("aggregates all env-errors at boot, not first-fail", async () => {
+    let captured: KumikoBootError | undefined;
+    try {
+      await runProdApp({
+        features: [],
+        envSchema: composed,
+        pulumiPrefix: "studio",
+        envSource: {
+          // KUMIKO_SECRETS_MASTER_KEY_V1 missing
+          JWT_SECRET: "short", // invalid (min 32)
+          STUDIO_ADMIN_EMAIL: "not-an-email", // invalid format
+        },
+        bootErrorReporter: (err) => {
+          captured = err;
+          throw err;
+        },
+      });
+    } catch (err) {
+      expect(err).toBeInstanceOf(KumikoBootError);
+    }
+    expect(captured).toBeDefined();
+    expect(captured!.errors.length).toBe(3);
+    const names = captured!.errors.map((e) => e.name).sort();
+    expect(names).toEqual(["JWT_SECRET", "KUMIKO_SECRETS_MASTER_KEY_V1", "STUDIO_ADMIN_EMAIL"]);
+    const kek = captured!.errors.find((e) => e.name === "KUMIKO_SECRETS_MASTER_KEY_V1");
+    expect(kek?.kind).toBe("missing");
+    expect(kek?.suggestion).toBe(
+      'Set via: pulumi config set --secret studioKumikoSecretsMasterKeyV1 "$(openssl rand -base64 32)"',
+    );
+  });
+
+  it("KUMIKO_DRY_RUN_ENV=human prints inventory and returns a dry-run handle", async () => {
+    const logs: string[] = [];
+    const realLog = console.log;
+    console.log = (...args: unknown[]) => {
+      logs.push(args.map(String).join(" "));
+    };
+    try {
+      const handle = await runProdApp({
+        features: [],
+        envSchema: composed,
+        envSource: {
+          KUMIKO_DRY_RUN_ENV: "human",
+        },
+      });
+      expect(handle).toBeDefined();
+      const out = logs.join("\n");
+      expect(out).toContain("Required env-vars:");
+      expect(out).toContain("KUMIKO_SECRETS_MASTER_KEY_V1");
+      expect(out).toContain("(secrets)");
+      expect(out).toContain("JWT_SECRET");
+      expect(out).toContain("(auth-email-password)");
+      expect(out).toContain("STUDIO_ADMIN_EMAIL");
+      expect(out).toContain("(app)");
+    } finally {
+      console.log = realLog;
+    }
+  });
+
+  it("KUMIKO_DRY_RUN_ENV=pulumi emits `pulumi config set` lines with prefix", async () => {
+    const logs: string[] = [];
+    const realLog = console.log;
+    console.log = (...args: unknown[]) => {
+      logs.push(args.map(String).join(" "));
+    };
+    try {
+      await runProdApp({
+        features: [],
+        envSchema: composed,
+        pulumiPrefix: "studio",
+        envSource: { KUMIKO_DRY_RUN_ENV: "pulumi" },
+      });
+      const out = logs.join("\n");
+      expect(out).toContain(
+        'pulumi config set --secret studioKumikoSecretsMasterKeyV1 "$(openssl rand -base64 32)"',
+      );
+      expect(out).toContain('pulumi config set studioStudioAdminEmail "<set-me>"');
+    } finally {
+      console.log = realLog;
+    }
+  });
+
+  it("composes frameworkCoreEnvSchema with feature schemas; reports core-source on missing PORT/DATABASE_URL", async () => {
+    const composedWithCore = composeEnvSchema({
+      core: frameworkCoreEnvSchema,
+      features: [secretsFeature, authFeature],
+      extend: z.object({ STUDIO_ADMIN_EMAIL: z.email() }),
+    });
+    let captured: KumikoBootError | undefined;
+    try {
+      await runProdApp({
+        features: [],
+        envSchema: composedWithCore,
+        pulumiPrefix: "studio",
+        envSource: {
+          // DATABASE_URL + REDIS_URL missing (framework-core)
+          // JWT_SECRET + KUMIKO_SECRETS_MASTER_KEY_V1 missing (features)
+          // STUDIO_ADMIN_EMAIL missing (app)
+          PORT: "invalid-port",
+        },
+        bootErrorReporter: (err) => {
+          captured = err;
+          throw err;
+        },
+      });
+    } catch (err) {
+      expect(err).toBeInstanceOf(KumikoBootError);
+    }
+    expect(captured).toBeDefined();
+    const port = captured!.errors.find((e) => e.name === "PORT");
+    expect(port?.source).toBe("framework-core");
+    expect(port?.kind).toBe("invalid");
+    const db = captured!.errors.find((e) => e.name === "DATABASE_URL");
+    expect(db?.source).toBe("framework-core");
+    expect(db?.kind).toBe("missing");
+    const formatted = captured!.format();
+    expect(formatted).toContain("✗ DATABASE_URL (framework-core, required, missing)");
+    expect(formatted).toContain("✗ REDIS_URL (framework-core, required, missing)");
+  });
+
+  it("KUMIKO_DRY_RUN_ENV=1 aliases to human-mode", async () => {
+    const logs: string[] = [];
+    const realLog = console.log;
+    console.log = (...args: unknown[]) => {
+      logs.push(args.map(String).join(" "));
+    };
+    try {
+      await runProdApp({
+        features: [],
+        envSchema: composed,
+        envSource: { KUMIKO_DRY_RUN_ENV: "1" },
+      });
+      expect(logs.join("\n")).toContain("Required env-vars:");
+    } finally {
+      console.log = realLog;
+    }
+  });
+});

package/src/__tests__/env-schema.test.ts

@@ -0,0 +1,93 @@
+import { composeEnvSchema, KumikoBootError, parseEnv } from "@cosmicdrift/kumiko-framework/env";
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { type FrameworkCoreEnv, frameworkCoreEnvSchema } from "../env-schema";
+
+describe("frameworkCoreEnvSchema", () => {
+  it("accepts a valid minimal env", () => {
+    const env = parseEnv(frameworkCoreEnvSchema, {
+      DATABASE_URL: "postgres://localhost:5432/db",
+      REDIS_URL: "redis://localhost:6379",
+    });
+    // Defaults populated, optional keys remain undefined.
+    expect(env.PORT).toBe("3000");
+    expect(env.DATABASE_URL).toBe("postgres://localhost:5432/db");
+    expect(env.REDIS_URL).toBe("redis://localhost:6379");
+    expect(env.KUMIKO_INSTANCE_ID).toBeUndefined();
+    expect(env.KUMIKO_SKIP_ES_OPS).toBeUndefined();
+  });
+
+  it("aggregates missing required vars (DATABASE_URL + REDIS_URL)", () => {
+    try {
+      parseEnv(frameworkCoreEnvSchema, {});
+      throw new Error("should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(KumikoBootError);
+      const boot = err as KumikoBootError;
+      const names = boot.errors.map((e) => e.name).sort();
+      expect(names).toContain("DATABASE_URL");
+      expect(names).toContain("REDIS_URL");
+      // PORT has a default → not in the error set
+      expect(names).not.toContain("PORT");
+    }
+  });
+
+  it("rejects an invalid PORT (non-numeric)", () => {
+    try {
+      parseEnv(frameworkCoreEnvSchema, {
+        DATABASE_URL: "postgres://localhost:5432/db",
+        REDIS_URL: "redis://localhost:6379",
+        PORT: "not-a-port",
+      });
+      throw new Error("should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(KumikoBootError);
+      const port = (err as KumikoBootError).errors.find((e) => e.name === "PORT");
+      expect(port?.kind).toBe("invalid");
+    }
+  });
+
+  it("KUMIKO_SKIP_ES_OPS accepts any string (matches runtime semantics)", () => {
+    // Runtime check is `!== "1"` — non-"1" values are silently ignored.
+    // The schema mirrors that: validate string-or-unset, not "1"-only.
+    const env = parseEnv(frameworkCoreEnvSchema, {
+      DATABASE_URL: "postgres://localhost:5432/db",
+      REDIS_URL: "redis://localhost:6379",
+      KUMIKO_SKIP_ES_OPS: "true",
+    });
+    expect(env.KUMIKO_SKIP_ES_OPS).toBe("true");
+  });
+
+  it("composes into an app-wide schema with source attribution", () => {
+    const { schema, sources } = composeEnvSchema({
+      core: frameworkCoreEnvSchema,
+      features: [],
+      extend: z.object({ STUDIO_ADMIN_EMAIL: z.email() }),
+    });
+    expect(sources["DATABASE_URL"]).toBe("framework-core");
+    expect(sources["PORT"]).toBe("framework-core");
+    expect(sources["STUDIO_ADMIN_EMAIL"]).toBe("app");
+
+    try {
+      parseEnv(schema, {}, { sources });
+    } catch (err) {
+      const boot = err as KumikoBootError;
+      const formatted = boot.format();
+      expect(formatted).toContain("✗ DATABASE_URL (framework-core, required, missing)");
+      expect(formatted).toContain("✗ REDIS_URL (framework-core, required, missing)");
+      expect(formatted).toContain("✗ STUDIO_ADMIN_EMAIL (app, required, missing)");
+    }
+  });
+
+  it("z.infer<typeof frameworkCoreEnvSchema> typechecks the expected shape", () => {
+    // Compile-time test — typecheck must accept this shape exactly.
+    const env: FrameworkCoreEnv = {
+      PORT: "3000",
+      DATABASE_URL: "postgres://localhost/x",
+      REDIS_URL: "redis://localhost",
+      KUMIKO_INSTANCE_ID: "pod-7",
+      KUMIKO_SKIP_ES_OPS: "1",
+    };
+    expect(env.PORT).toBe("3000");
+  });
+});

package/src/env-schema.ts

@@ -0,0 +1,64 @@
+// Framework-core env-schema — the vars that runProdApp + buildServer
+// + the connection-pool read directly from process.env today. Apps merge
+// this into their app-wide schema via `composeEnvSchema({ core, ... })`.
+//
+// Sprint 9.2 is purely additive: the schema is exposed, but the call-sites
+// in run-prod-app.ts (requireEnv("DATABASE_URL"), …) and api/server.ts
+// (process.env["KUMIKO_INSTANCE_ID"]) keep reading process.env directly.
+// Apps that opt into the schema get aggregated boot-validation errors
+// BEFORE those legacy reads run; apps that don't, behave as before.
+//
+// Feature-specific vars (JWT_SECRET, KUMIKO_SECRETS_MASTER_KEY_*) live
+// in their owning feature's envSchema — Phase 2 (bundled-features).
+
+import { z } from "zod";
+
+/** Env-vars read by framework-core (api/server, db/connection,
+ *  dev-server/run-prod-app). NOT including feature-specific vars.
+ *
+ *  PORT-default "3000" is the same fallback as
+ *  `packages/dev-server/src/run-prod-app.ts:533` — keep in sync when the
+ *  call-site is refactored to consume parsed env (Sprint 9.5 Phase 4). */
+export const frameworkCoreEnvSchema = z.object({
+  PORT: z
+    .string()
+    .regex(/^\d+$/, "PORT must be a positive integer string")
+    .default("3000")
+    .describe("HTTP listen port. runProdApp defaults to 3000 when unset."),
+
+  DATABASE_URL: z
+    .url("DATABASE_URL must be a valid postgres:// URL")
+    .describe("Primary Postgres connection string (write + read).")
+    .meta({ kumiko: { pulumi: { secret: true } } }),
+
+  REDIS_URL: z
+    .url("REDIS_URL must be a valid redis:// URL")
+    .describe("Redis connection string for SSE-broker + job-queues.")
+    .meta({ kumiko: { pulumi: { secret: true } } }),
+
+  KUMIKO_INSTANCE_ID: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      "Stable per-process identifier (pod name, hostname). " +
+        "Multi-instance deploys SHOULD set this so per-instance consumers " +
+        "(SSE) don't accumulate orphaned cursor-rows on restart.",
+    ),
+
+  // `z.string().optional()` (not `z.literal("1")`) — the run-prod-app
+  // call-site (`process.env["KUMIKO_SKIP_ES_OPS"] !== "1"`) ignores any
+  // value other than literal "1". A stricter schema would reject e.g.
+  // "true" / "yes" that the runtime silently ignores, surfacing
+  // boot-errors for inputs the framework doesn't actually care about.
+  KUMIKO_SKIP_ES_OPS: z
+    .string()
+    .optional()
+    .describe(
+      "Set to '1' to skip event-store ops (seed/migrate) at boot. " +
+        "Any other value is treated as 'not set' by run-prod-app. " +
+        "Used by integration-test stacks that manage ES-ops out-of-band.",
+    ),
+});
+
+export type FrameworkCoreEnv = z.infer<typeof frameworkCoreEnvSchema>;

package/src/index.ts

@@ -32,6 +32,7 @@ export {
   type KumikoServerHandle,
   resolveStylesheet,
 } from "./create-kumiko-server";
+export { type FrameworkCoreEnv, frameworkCoreEnvSchema } from "./env-schema";
 export type {
   AuthoringStyle,
   BuildFewShotCorpusOptions,

package/src/run-prod-app.ts

@@ -58,6 +58,12 @@ import {
   type ApiEntrypointOptions,
   createApiEntrypoint,
 } from "@cosmicdrift/kumiko-framework/entrypoint";
+import {
+  type ComposedEnvSchema,
+  KumikoBootError,
+  parseEnv,
+} from "@cosmicdrift/kumiko-framework/env";
+import { type DryRunMode, renderDryRun } from "@cosmicdrift/kumiko-framework/env/dry-run";
 import {
   createEsOperationsTable,
   createSeedMigrationContext,
@@ -120,6 +126,48 @@ function readEnv(name: string): string | undefined {
   return value === undefined || value === "" ? undefined : value;
 }
 
+// Parse `KUMIKO_DRY_RUN_ENV=…` into a DryRunMode. Truthy "1" aliases
+// "human" — the most common deploy-Q quick-look. Unknown values are
+// warned-and-ignored: a typo like `=humans` would otherwise look like
+// a confused boot 30 seconds later when the schema fails.
+function parseDryRunMode(raw: string | undefined): DryRunMode | null {
+  if (!raw) return null;
+  const v = raw.toLowerCase();
+  if (v === "1" || v === "true" || v === "human") return "human";
+  if (v === "json" || v === "pulumi" || v === "k8s") return v;
+  // biome-ignore lint/suspicious/noConsole: boot-time warn for typo discovery
+  console.warn(
+    `[runProdApp] KUMIKO_DRY_RUN_ENV="${raw}" unrecognized ` +
+      `(expected 1|human|json|pulumi|k8s); continuing with normal boot.`,
+  );
+  return null;
+}
+
+function defaultBootErrorReporter(err: KumikoBootError): never {
+  // biome-ignore lint/suspicious/noConsole: boot-time error, no logger configured yet
+  console.error(err.format());
+  process.exit(1);
+}
+
+// Returned from runProdApp when KUMIKO_DRY_RUN_ENV is set AND envSource
+// was passed (= test-mode). The handle is intentionally inert — listen()
+// and stop() are no-ops; tests inspect the dry-run console output and
+// move on.
+function makeDryRunHandle(): ProdAppHandle {
+  const noop = async () => {
+    /* dry-run handle: no server was constructed */
+  };
+  return {
+    // @cast-boundary dry-run-mode: no ApiEntrypoint exists because no
+    // boot ran; the handle only surfaces test/CLI inspection and the
+    // entrypoint is never reached by callers in dry-run.
+    entrypoint: undefined as unknown as ApiEntrypoint,
+    fetch: () => new Response("dry-run", { status: 503 }),
+    listen: noop,
+    stop: noop,
+  };
+}
+
 /** Wrapper-API für den Password-Reset-Flow.
  *
  *  Setup = Feature-Options (PasswordResetOptions = hmacSecret +
@@ -374,9 +422,39 @@ export type RunProdAppOptions = {
    *  createLateBoundHolder + post-boot runtime.initialize in einem
    *  seed-fn (db ist erst nach migrations + features ready). */
   readonly effectiveFeatures?: (tenantId: TenantId) => ReadonlySet<string>;
+  /** Composed Zod-schema for env-validation (from `composeEnvSchema({
+   *  features, extend })` in @cosmicdrift/kumiko-framework/env). When set:
+   *  - `process.env` is parsed against it BEFORE any boot work; missing
+   *    or invalid vars throw a `KumikoBootError` listing ALL problems
+   *    at once (not first-fail).
+   *  - `KUMIKO_DRY_RUN_ENV=human|json|pulumi|k8s` introspects the schema
+   *    and prints the env-var inventory, then exits without booting.
+   *
+   *  9.1 is additive: features that still read `process.env` directly
+   *  keep working. Migration to the schema is Sprint-9.2-9.5. */
+  readonly envSchema?: ComposedEnvSchema;
+  /** Prefix for `pulumi config set <prefix><CamelCase(VAR)>` in dry-run
+   *  output and boot-error suggestions. Without this, suggestions use
+   *  bare `camelCase(VAR)` and ops has to guess the app prefix. */
+  readonly pulumiPrefix?: string;
+  /** Handler for KumikoBootError. Default: print formatted error to
+   *  stderr and `process.exit(1)` so the container restarts with a
+   *  visible log line. Override in tests that drive runProdApp directly
+   *  (avoid the exit). Return type is `void` rather than `never` to keep
+   *  test-overrides honest — if a reporter returns, runProdApp falls
+   *  through to a regular `throw err` as the safety net. */
+  readonly bootErrorReporter?: (err: KumikoBootError) => void;
+  /** Override `process.env` for env-validation. Default: `process.env`.
+   *  Tests use this to feed crafted env-maps without polluting the
+   *  global. */
+  readonly envSource?: Record<string, string | undefined>;
 };
 
 export type ProdAppHandle = {
+  /** The composed ApiEntrypoint. In KUMIKO_DRY_RUN_ENV mode WITH
+   *  `envSource` injected (test path), no boot ran and this slot is an
+   *  undefined-cast — do not access. Production dry-run hits
+   *  `process.exit(0)` before returning a handle. */
   readonly entrypoint: ApiEntrypoint;
   /** The fetch-handler — wired into Bun.serve in production, called
    *  directly in tests. Composes Hono + static-fallback. */
@@ -390,6 +468,56 @@ export type ProdAppHandle = {
 };
 
 export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHandle> {
+  // 0. Env-Schema validation + dry-run modes. Runs FIRST so:
+  //    - operators can introspect env-requirements without a real boot
+  //      (no DB connection needed, KUMIKO_DRY_RUN_ENV=… → render + exit)
+  //    - missing/invalid env-vars produce a structured KumikoBootError
+  //      with ALL problems aggregated (not first-fail), before we waste
+  //      seconds on a Postgres connection that was never configured.
+  //
+  //    Both code paths are no-ops when no envSchema is passed — Sprint-9
+  //    migration is per-feature additive; pre-migration apps keep the
+  //    legacy `requireEnv("DATABASE_URL")` checks below.
+  //
+  //    Ordering invariant: this step runs BEFORE the Temporal polyfill,
+  //    so env-schemas MUST use only Temporal-free Zod types. Don't author
+  //    `z.iso.date()`/`Temporal.Instant` fields on env-vars — they'd crash
+  //    at parse-time before the polyfill loads. Plain strings + .regex /
+  //    .min / .email / .url cover every env-var shape we've actually
+  //    needed in 9.1's audit (37 references, 25 distinct vars).
+  if (options.envSchema) {
+    const envSource = options.envSource ?? process.env;
+    const dryRunMode = parseDryRunMode(envSource["KUMIKO_DRY_RUN_ENV"]);
+    if (dryRunMode !== null) {
+      // biome-ignore lint/suspicious/noConsole: dry-run output IS the deliverable
+      console.log(
+        renderDryRun(options.envSchema, dryRunMode, {
+          ...(options.pulumiPrefix ? { pulumiPrefix: options.pulumiPrefix } : {}),
+          sources: options.envSchema.sources,
+        }),
+      );
+      // Tests inject envSource and want a return-value, not exit. Detecting
+      // "this is a test" via envSource is brittle; instead exit when running
+      // against the real process.env (the deploy-flow), return otherwise.
+      if (options.envSource === undefined) {
+        process.exit(0);
+      }
+      return makeDryRunHandle();
+    }
+    try {
+      parseEnv(options.envSchema.schema, envSource, {
+        sources: options.envSchema.sources,
+        ...(options.pulumiPrefix ? { pulumiPrefix: options.pulumiPrefix } : {}),
+      });
+    } catch (err) {
+      if (err instanceof KumikoBootError) {
+        const reporter = options.bootErrorReporter ?? defaultBootErrorReporter;
+        reporter(err);
+      }
+      throw err;
+    }
+  }
+
   // 1. Polyfill before anything else — feature code references Temporal.
   const { ensureTemporalPolyfill } = await import("@cosmicdrift/kumiko-framework/time");
   await ensureTemporalPolyfill();