@cosmicdrift/kumiko-framework 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @cosmicdrift/kumiko-framework
 
+## 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.
+
 ## 0.7.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -44,6 +44,14 @@
       "types": "./src/engine/types/index.ts",
       "default": "./src/engine/types/index.ts"
     },
+    "./env": {
+      "types": "./src/env/index.ts",
+      "default": "./src/env/index.ts"
+    },
+    "./env/dry-run": {
+      "types": "./src/env/dry-run.ts",
+      "default": "./src/env/dry-run.ts"
+    },
     "./engine/codemod": {
       "types": "./src/engine/codemod/index.ts",
       "default": "./src/engine/codemod/index.ts"
@@ -163,7 +171,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.7.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.8.0",
     "@types/uuid": "^11.0.0",
     "bun-types": "^1.3.13",
     "drizzle-kit": "^0.31.10",

package/src/engine/define-feature.ts

@@ -155,6 +155,9 @@ export function defineFeature<const TName extends string, TExports = undefined>(
   // closure-let-var nicht mit der `treeActions(...)` registrar-Methode.
   let treeActions: Readonly<Record<string, TreeActionDef>> | undefined;
   let treeProvider: TreeChildrenSubscribe | undefined;
+  // Optional Zod-schema for env-vars this feature reads at runtime,
+  // declared via r.envSchema(). At-most-one per feature.
+  let envSchema: z.ZodObject<z.ZodRawShape> | undefined;
 
   // Map handler name to entity via colon convention.
   // "task:create" → entity "task". No colon → standalone handler, no mapping.
@@ -573,6 +576,15 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       metrics[shortName] = { shortName, ...options };
     },
 
+    envSchema(schema: z.ZodObject<z.ZodRawShape>): void {
+      if (envSchema !== undefined) {
+        throw new Error(
+          `[Feature ${name}] r.envSchema() called twice — declare one composed Zod-object per feature.`,
+        );
+      }
+      envSchema = schema;
+    },
+
     secret(shortName: string, options: SecretOptions): SecretKeyHandle {
       if (secretKeys[shortName]) {
         throw new Error(
@@ -874,5 +886,6 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     rawTables,
     ...(treeActions !== undefined && { treeActions }),
     ...(treeProvider !== undefined && { treeProvider }),
+    ...(envSchema !== undefined && { envSchema }),
   };
 }

package/src/engine/feature-ast/extractors/index.ts

@@ -50,6 +50,7 @@ export {
   readScreenStatic,
 } from "./round4";
 export {
+  extractEnvSchema,
   extractExposesApi,
   extractExtendsRegistrar,
   extractUsesApi,

package/src/engine/feature-ast/extractors/round5.ts

@@ -1,9 +1,33 @@
 import type { CallExpression, SourceFile } from "ts-morph";
 import { SyntaxKind } from "ts-morph";
-import type { ExposesApiPattern, ExtendsRegistrarPattern, UsesApiPattern } from "../patterns";
+import type {
+  EnvSchemaPattern,
+  ExposesApiPattern,
+  ExtendsRegistrarPattern,
+  UsesApiPattern,
+} from "../patterns";
 import { sourceLocationFromNode } from "../source-location";
 import { type ExtractOutput, fail, ok } from "./shared";
 
+export function extractEnvSchema(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<EnvSchemaPattern> {
+  const arg = call.getArguments()[0];
+  if (!arg) {
+    return fail(
+      "envSchema",
+      sourceLocationFromNode(call, sourceFile),
+      "expected a single Zod-object schema argument (e.g. z.object({...}))",
+    );
+  }
+  return ok({
+    kind: "envSchema",
+    source: sourceLocationFromNode(call, sourceFile),
+    schemaBody: sourceLocationFromNode(arg, sourceFile),
+  });
+}
+
 export function extractExtendsRegistrar(
   call: CallExpression,
   sourceFile: SourceFile,

package/src/engine/feature-ast/parse.ts

@@ -32,6 +32,7 @@ import {
   extractDefineEvent,
   extractEntity,
   extractEntityHook,
+  extractEnvSchema,
   extractEventMigration,
   extractExposesApi,
   extractExtendsRegistrar,
@@ -359,6 +360,9 @@ function dispatchExtractor(
       return extractTreeActions(call, sourceFile);
     case "tree":
       return extractTree(call, sourceFile);
+    // Round 7 — env-schema contract (opaque, Zod-expression argument)
+    case "envSchema":
+      return extractEnvSchema(call, sourceFile);
     // Unknown method — UnknownPattern signal so Designer/AI surface it
     // as "custom call" without losing the source location.
     default:

package/src/engine/feature-ast/patterns.ts

@@ -387,6 +387,15 @@ export type ExposesApiPattern = {
 // API exists and needs its own pattern type here.
 // =============================================================================
 
+// r.envSchema(z.object({...})) — the env-vars contract for a feature.
+// Argument is a Zod-expression (computed); we keep the source-location of
+// the schema body so Designer / AI render the raw TS code (opaque).
+export type EnvSchemaPattern = {
+  readonly kind: "envSchema";
+  readonly source: SourceLocation;
+  readonly schemaBody: SourceLocation;
+};
+
 export type UnknownPattern = {
   readonly kind: "unknown";
   readonly source: SourceLocation;
@@ -435,6 +444,7 @@ export type FeaturePattern =
   | EventMigrationPattern
   | ExtendsRegistrarPattern
   | TreePattern
+  | EnvSchemaPattern
   // Catch-all
   | UnknownPattern;
 
@@ -492,6 +502,7 @@ export function getEditability(pattern: FeaturePattern): Editability {
     case "authClaims":
     case "extendsRegistrar":
     case "tree":
+    case "envSchema":
     case "unknown":
       return "opaque";
     default: {

package/src/engine/feature-ast/render.ts

@@ -23,6 +23,7 @@ import type {
   DefineEventPattern,
   EntityHookPattern,
   EntityPattern,
+  EnvSchemaPattern,
   EventMigrationPattern,
   ExposesApiPattern,
   ExtendsRegistrarPattern,
@@ -134,6 +135,8 @@ export function renderPattern(pattern: FeaturePattern): string {
       return renderTreeActions(pattern);
     case "tree":
       return renderTree(pattern);
+    case "envSchema":
+      return renderEnvSchema(pattern);
     case "unknown":
       return renderUnknown(pattern);
     default: {
@@ -495,6 +498,10 @@ function renderExtendsRegistrar(p: ExtendsRegistrarPattern): string {
   return `r.extendsRegistrar(${JSON.stringify(p.extensionName)}, ${p.defBody.raw});`;
 }
 
+function renderEnvSchema(p: EnvSchemaPattern): string {
+  return `r.envSchema(${p.schemaBody.raw});`;
+}
+
 function renderUsesApi(p: UsesApiPattern): string {
   return `r.usesApi(${JSON.stringify(p.apiName)});`;
 }

package/src/engine/pattern-library/__tests__/library.test.ts

@@ -59,6 +59,7 @@ const ALL_KINDS: readonly FeaturePatternKind[] = [
   "exposesApi",
   "treeActions",
   "tree",
+  "envSchema",
   "unknown",
 ];
 
@@ -346,6 +347,8 @@ function makePlaceholderPattern(kind: FeaturePatternKind): FeaturePattern {
       return { kind, source: PLACEHOLDER_LOC, definitions: {} };
     case "tree":
       return { kind, source: PLACEHOLDER_LOC, providerBody: PLACEHOLDER_BODY_LOC };
+    case "envSchema":
+      return { kind, source: PLACEHOLDER_LOC, schemaBody: PLACEHOLDER_BODY_LOC };
     case "unknown":
       return { kind, source: PLACEHOLDER_LOC, methodName: "x" };
     case "usesApi":

package/src/engine/pattern-library/library.ts

@@ -1092,6 +1092,24 @@ const treeSchema: PatternFormSchema = {
   ],
 };
 
+const envSchemaSchema: PatternFormSchema = {
+  kind: "envSchema",
+  label: { en: "Env schema", de: "Env-Schema" },
+  summary: {
+    en: "Zod-object declaring this feature's required env-vars. Apps merge it via composeEnvSchema for boot-validation.",
+  },
+  category: "advanced",
+  editability: "opaque",
+  fields: [
+    {
+      path: "schemaBody",
+      label: { en: "Schema", de: "Schema" },
+      input: "json-readonly",
+      readOnly: true,
+    },
+  ],
+};
+
 const unknownSchema: PatternFormSchema = {
   kind: "unknown",
   label: { en: "Unknown call", de: "Unbekannter Call" },
@@ -1153,6 +1171,7 @@ export const PATTERN_LIBRARY: Readonly<Record<FeaturePatternKind, PatternFormSch
   exposesApi: exposesApiSchema,
   treeActions: treeActionsSchema,
   tree: treeSchema,
+  envSchema: envSchemaSchema,
   unknown: unknownSchema,
 } satisfies Readonly<Record<FeaturePatternKind, PatternFormSchema>>;
 

package/src/engine/types/feature.ts

@@ -260,6 +260,12 @@ export type FeatureDefinition = {
   // system. Keyed by feature-local short name. The registry attaches
   // featureName on aggregation, lifting RawTableEntry → RawTableDef.
   readonly rawTables: Readonly<Record<string, RawTableEntry>>;
+  // Optional Zod-schema for env-vars this feature reads at runtime.
+  // Declared via `r.envSchema(z.object({...}))`. `composeEnvSchema` reads
+  // this to build one app-wide schema for boot-validation + dry-run
+  // rendering. Absence means the feature reads no env-vars (or hasn't
+  // been migrated yet — Sprint-9 migration is add-only per phase).
+  readonly envSchema?: z.ZodObject<z.ZodRawShape>;
 };
 
 // --- Feature Registrar (the "r" object in defineFeature) ---
@@ -574,6 +580,19 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     actions: TActions,
   ): TreeActionsHandle<TFeature, TActions>;
 
+  // Declare the Zod-schema for env-vars this feature reads at runtime.
+  // At-most-one call per feature. composeEnvSchema reads it across all
+  // features to build one app-wide schema, which runProdApp parses
+  // process.env against at boot. App-Authors can also call
+  // `KUMIKO_DRY_RUN_ENV=human|json|pulumi|k8s` to introspect the
+  // required env-vars without booting.
+  //
+  // Convention: keys are SHOUTING_SNAKE_CASE env-var names. Per-var
+  // metadata (Pulumi-config-key override, openssl-generator suggestion,
+  // k8s-secret hints) goes into `.meta({ kumiko: { pulumi: {...} } })`
+  // — see framework/env/index.ts for the meta-shape.
+  envSchema(schema: z.ZodObject<z.ZodRawShape>): void;
+
   // Register the tree-provider for this feature — the Subscribe-Function
   // that emits the top-level Tree-Knoten when the Visual-Workspace
   // (navigation: "tree") mounts. At-most-one call per feature.

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

@@ -0,0 +1,283 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { defineFeature } from "../../engine/define-feature";
+import { camelCase, composeEnvSchema, KumikoBootError, parseEnv, pulumiConfigKey } from "../index";
+
+describe("composeEnvSchema", () => {
+  it("merges per-feature schemas and tags sources", () => {
+    const secretsFeature = defineFeature("secrets", (r) => {
+      r.envSchema(
+        z.object({
+          KUMIKO_SECRETS_MASTER_KEY_V1: z.string().describe("AES-256 KEK"),
+        }),
+      );
+    });
+    const authFeature = defineFeature("auth", (r) => {
+      r.envSchema(
+        z.object({
+          JWT_SECRET: z.string().min(32).describe("Session JWT signing key"),
+        }),
+      );
+    });
+
+    const { schema, sources } = composeEnvSchema({
+      features: [secretsFeature, authFeature],
+      extend: z.object({
+        STUDIO_ADMIN_EMAIL: z.email(),
+      }),
+    });
+
+    expect(Object.keys(schema.shape).sort()).toEqual([
+      "JWT_SECRET",
+      "KUMIKO_SECRETS_MASTER_KEY_V1",
+      "STUDIO_ADMIN_EMAIL",
+    ]);
+    expect(sources).toEqual({
+      JWT_SECRET: "auth",
+      KUMIKO_SECRETS_MASTER_KEY_V1: "secrets",
+      STUDIO_ADMIN_EMAIL: "app",
+    });
+  });
+
+  it("detects feature/feature env-var conflicts", () => {
+    const a = defineFeature("feat-a", (r) => {
+      r.envSchema(z.object({ JWT_SECRET: z.string() }));
+    });
+    const b = defineFeature("feat-b", (r) => {
+      r.envSchema(z.object({ JWT_SECRET: z.string() }));
+    });
+
+    expect(() => composeEnvSchema({ features: [a, b] })).toThrow(KumikoBootError);
+  });
+
+  it("detects feature/app env-var conflicts", () => {
+    const a = defineFeature("feat-a", (r) => {
+      r.envSchema(z.object({ DATABASE_URL: z.string() }));
+    });
+    expect(() =>
+      composeEnvSchema({
+        features: [a],
+        extend: z.object({ DATABASE_URL: z.string() }),
+      }),
+    ).toThrow(KumikoBootError);
+  });
+
+  it("wraps optionalFeatures' vars as .optional()", () => {
+    const smtp = defineFeature("channel-email-smtp", (r) => {
+      r.envSchema(z.object({ SMTP_HOST: z.string() }));
+    });
+    const { schema } = composeEnvSchema({
+      features: [smtp],
+      optionalFeatures: ["channel-email-smtp"],
+    });
+    // Parsing without SMTP_HOST should now succeed.
+    const result = schema.safeParse({});
+    expect(result.success).toBe(true);
+  });
+
+  it("double-wrapping an already-optional field stays parseable", () => {
+    // Edge case: feature declares the field optional AND the app marks
+    // the whole feature as optionalFeatures. composeEnvSchema wraps again.
+    // Zod v4 treats .optional().optional() as idempotent.
+    const smtp = defineFeature("channel-email-smtp", (r) => {
+      r.envSchema(z.object({ SMTP_HOST: z.string().optional() }));
+    });
+    const { schema } = composeEnvSchema({
+      features: [smtp],
+      optionalFeatures: ["channel-email-smtp"],
+    });
+    expect(schema.safeParse({}).success).toBe(true);
+    expect(schema.safeParse({ SMTP_HOST: "mail.example" }).success).toBe(true);
+  });
+
+  it("ignores features without envSchema", () => {
+    const noEnv = defineFeature("no-env", () => {
+      // declares nothing
+    });
+    const { schema, sources } = composeEnvSchema({ features: [noEnv] });
+    expect(Object.keys(schema.shape)).toEqual([]);
+    expect(sources).toEqual({});
+  });
+
+  it("tags `core` vars with source 'framework-core'", () => {
+    const core = z.object({
+      PORT: z.string().default("3000"),
+      DATABASE_URL: z.url(),
+    });
+    const feature = defineFeature("auth", (r) => {
+      r.envSchema(z.object({ JWT_SECRET: z.string().min(32) }));
+    });
+    const { schema, sources } = composeEnvSchema({
+      core,
+      features: [feature],
+      extend: z.object({ STUDIO_ADMIN_EMAIL: z.email() }),
+    });
+    expect(Object.keys(schema.shape).sort()).toEqual([
+      "DATABASE_URL",
+      "JWT_SECRET",
+      "PORT",
+      "STUDIO_ADMIN_EMAIL",
+    ]);
+    expect(sources).toEqual({
+      DATABASE_URL: "framework-core",
+      JWT_SECRET: "auth",
+      PORT: "framework-core",
+      STUDIO_ADMIN_EMAIL: "app",
+    });
+  });
+
+  it("detects core/feature env-var conflicts (feature shadows core)", () => {
+    const core = z.object({ PORT: z.string() });
+    const sneaky = defineFeature("sneaky", (r) => {
+      r.envSchema(z.object({ PORT: z.string() }));
+    });
+    expect(() => composeEnvSchema({ core, features: [sneaky] })).toThrow(KumikoBootError);
+  });
+
+  it("detects core/extend env-var conflicts (app shadows core)", () => {
+    const core = z.object({ DATABASE_URL: z.url() });
+    expect(() =>
+      composeEnvSchema({
+        core,
+        features: [],
+        extend: z.object({ DATABASE_URL: z.string() }),
+      }),
+    ).toThrow(KumikoBootError);
+  });
+});
+
+describe("r.envSchema()", () => {
+  it("hangs the schema off the FeatureDefinition", () => {
+    const feature = defineFeature("foo", (r) => {
+      r.envSchema(z.object({ FOO_BAR: z.string() }));
+    });
+    expect(feature.envSchema).toBeDefined();
+    expect(Object.keys(feature.envSchema!.shape)).toEqual(["FOO_BAR"]);
+  });
+
+  it("throws when called twice", () => {
+    expect(() =>
+      defineFeature("foo", (r) => {
+        r.envSchema(z.object({ A: z.string() }));
+        r.envSchema(z.object({ B: z.string() }));
+      }),
+    ).toThrow(/envSchema\(\) called twice/);
+  });
+});
+
+describe("parseEnv", () => {
+  it("returns the typed value on success", () => {
+    const schema = z.object({
+      PORT: z.string().regex(/^\d+$/),
+      JWT_SECRET: z.string().min(32),
+    });
+    const value = parseEnv(schema, {
+      PORT: "3000",
+      JWT_SECRET: "x".repeat(32),
+    });
+    expect(value.PORT).toBe("3000");
+    expect(value.JWT_SECRET.length).toBe(32);
+  });
+
+  it("aggregates ALL errors, not first-fail", () => {
+    const schema = z.object({
+      DATABASE_URL: z.url(),
+      JWT_SECRET: z.string().min(32),
+      ADMIN_EMAIL: z.email(),
+    });
+    try {
+      parseEnv(schema, {
+        DATABASE_URL: "not-a-url",
+        // JWT_SECRET missing
+        ADMIN_EMAIL: "not-an-email",
+      });
+      throw new Error("should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(KumikoBootError);
+      const boot = err as KumikoBootError;
+      expect(boot.errors.length).toBe(3);
+      const names = boot.errors.map((e) => e.name).sort();
+      expect(names).toEqual(["ADMIN_EMAIL", "DATABASE_URL", "JWT_SECRET"]);
+      const jwt = boot.errors.find((e) => e.name === "JWT_SECRET");
+      expect(jwt?.kind).toBe("missing");
+    }
+  });
+
+  it("strips undefined values so missing vars get a 'missing' kind", () => {
+    const schema = z.object({ FOO: z.string() });
+    try {
+      parseEnv(schema, { FOO: undefined });
+      throw new Error("should have thrown");
+    } catch (err) {
+      const boot = err as KumikoBootError;
+      expect(boot.errors[0]!.kind).toBe("missing");
+    }
+  });
+
+  it("attaches pulumi suggestions when prefix is set", () => {
+    const schema = z.object({
+      JWT_SECRET: z
+        .string()
+        .min(32)
+        .meta({ kumiko: { pulumi: { generator: "openssl rand -base64 48", secret: true } } }),
+    });
+    try {
+      parseEnv(schema, {}, { pulumiPrefix: "studio" });
+    } catch (err) {
+      const boot = err as KumikoBootError;
+      expect(boot.errors[0]!.suggestion).toBe(
+        'Set via: pulumi config set --secret studioJwtSecret "$(openssl rand -base64 48)"',
+      );
+    }
+  });
+
+  it("formats aggregate output with all errors", () => {
+    const schema = z.object({
+      A: z.string(),
+      B: z.string().min(10).describe("Long-ish key"),
+    });
+    try {
+      parseEnv(schema, { B: "short" });
+    } catch (err) {
+      const formatted = (err as KumikoBootError).format();
+      expect(formatted).toContain("Boot failed: 2 env-var problems");
+      expect(formatted).toContain("✗ A (required, missing)");
+      expect(formatted).toContain("✗ B (invalid)");
+      expect(formatted).toContain("Long-ish key");
+    }
+  });
+
+  it("populates EnvError.source from options.sources, surfaced in format()", () => {
+    const schema = z.object({ JWT_SECRET: z.string().min(32) });
+    try {
+      parseEnv(schema, {}, { sources: { JWT_SECRET: "auth-email-password" } });
+    } catch (err) {
+      const boot = err as KumikoBootError;
+      expect(boot.errors[0]!.source).toBe("auth-email-password");
+      expect(boot.format()).toContain("✗ JWT_SECRET (auth-email-password, required, missing)");
+    }
+  });
+});
+
+describe("pulumiConfigKey + camelCase", () => {
+  it("camelCases SCREAMING_SNAKE_CASE", () => {
+    expect(camelCase("JWT_SECRET")).toBe("jwtSecret");
+    expect(camelCase("STUDIO_ADMIN_EMAIL")).toBe("studioAdminEmail");
+    expect(camelCase("KUMIKO_SECRETS_MASTER_KEY_V1")).toBe("kumikoSecretsMasterKeyV1");
+  });
+
+  it("applies a prefix with PascalCase'd tail", () => {
+    expect(pulumiConfigKey("JWT_SECRET", undefined, "studio")).toBe("studioJwtSecret");
+  });
+
+  it("uses meta.pulumi.name override when set", () => {
+    const f = z.string().meta({ kumiko: { pulumi: { name: "secretsMasterKey" } } });
+    expect(pulumiConfigKey("KUMIKO_SECRETS_MASTER_KEY_V1", f, "studio")).toBe(
+      "studioSecretsMasterKey",
+    );
+  });
+
+  it("returns the camelCase name when no prefix", () => {
+    expect(pulumiConfigKey("JWT_SECRET", undefined, undefined)).toBe("jwtSecret");
+  });
+});

package/src/env/__tests__/dry-run.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { defineFeature } from "../../engine/define-feature";
+import { renderDryRun } from "../dry-run";
+import { composeEnvSchema } from "../index";
+
+function buildComposed() {
+  const secretsFeature = defineFeature("secrets", (r) => {
+    r.envSchema(
+      z.object({
+        KUMIKO_SECRETS_MASTER_KEY_V1: z
+          .string()
+          .describe("AES-256 master-key for tenant-secrets")
+          .meta({
+            kumiko: {
+              pulumi: {
+                name: "secretsMasterKey",
+                generator: "openssl rand -base64 32",
+                secret: true,
+              },
+            },
+          }),
+        KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: z
+          .string()
+          .regex(/^\d+$/)
+          .default("1")
+          .describe("Active KEK version"),
+      }),
+    );
+  });
+  const authFeature = defineFeature("auth-email-password", (r) => {
+    r.envSchema(
+      z.object({
+        JWT_SECRET: z
+          .string()
+          .min(32)
+          .describe("Session JWT signing key (≥32 chars)")
+          .meta({
+            kumiko: { pulumi: { generator: "openssl rand -base64 48", secret: true } },
+          }),
+      }),
+    );
+  });
+  const smtpFeature = defineFeature("channel-email-smtp", (r) => {
+    r.envSchema(
+      z.object({
+        SMTP_HOST: z.string().optional().describe("Outbound SMTP host"),
+      }),
+    );
+  });
+  return composeEnvSchema({
+    features: [secretsFeature, authFeature, smtpFeature],
+    extend: z.object({
+      STUDIO_ADMIN_EMAIL: z.email().describe("Bootstrap admin user"),
+    }),
+  });
+}
+
+describe("renderDryRun", () => {
+  it("human mode groups by required / optional / defaulted with feature attribution", () => {
+    const composed = buildComposed();
+    const out = renderDryRun(composed, "human");
+    expect(out).toContain("Required env-vars:");
+    expect(out).toContain("Optional env-vars:");
+    expect(out).toContain("Defaulted env-vars:");
+    expect(out).toContain("JWT_SECRET");
+    expect(out).toContain("(auth-email-password)");
+    expect(out).toContain("Session JWT signing key");
+    expect(out).toContain("STUDIO_ADMIN_EMAIL");
+    expect(out).toContain("(app)");
+    expect(out).toContain("(channel-email-smtp)");
+    expect(out).toContain('[default: "1"]');
+  });
+
+  it("json mode emits structured data with pulumiName per entry", () => {
+    const composed = buildComposed();
+    const out = renderDryRun(composed, "json", { pulumiPrefix: "studio" });
+    const parsed = JSON.parse(out) as {
+      required: { name: string; feature: string; pulumiName: string; description?: string }[];
+      optional: { name: string }[];
+      withDefault: { name: string; default: unknown }[];
+    };
+    const jwt = parsed.required.find((r) => r.name === "JWT_SECRET");
+    expect(jwt?.feature).toBe("auth-email-password");
+    expect(jwt?.pulumiName).toBe("studioJwtSecret");
+    expect(jwt?.description).toContain("Session JWT");
+    const smtp = parsed.optional.find((r) => r.name === "SMTP_HOST");
+    expect(smtp).toBeDefined();
+    const ver = parsed.withDefault.find((r) => r.name.endsWith("CURRENT_VERSION"));
+    expect(ver?.default).toBe("1");
+  });
+
+  it("pulumi mode emits `pulumi config set` lines, omitting optional+defaulted", () => {
+    const composed = buildComposed();
+    const out = renderDryRun(composed, "pulumi", { pulumiPrefix: "studio" });
+    expect(out).toContain(
+      'pulumi config set --secret studioJwtSecret "$(openssl rand -base64 48)"',
+    );
+    expect(out).toContain(
+      'pulumi config set --secret studioSecretsMasterKey "$(openssl rand -base64 32)"',
+    );
+    expect(out).toContain('pulumi config set studioStudioAdminEmail "<set-me>"');
+    // Optional + default skipped:
+    expect(out).not.toContain("SMTP_HOST");
+    expect(out).not.toContain("CURRENT_VERSION");
+  });
+
+  it("k8s mode emits a Secret manifest", () => {
+    const composed = buildComposed();
+    const out = renderDryRun(composed, "k8s", {
+      k8sName: "studio-env",
+      k8sNamespace: "studio",
+    });
+    expect(out).toContain("apiVersion: v1");
+    expect(out).toContain("kind: Secret");
+    expect(out).toContain("name: studio-env");
+    expect(out).toContain("namespace: studio");
+    expect(out).toContain('JWT_SECRET: "<set-me>"');
+    expect(out).toContain('KUMIKO_SECRETS_MASTER_KEY_V1: "<set-me>"');
+  });
+});

package/src/env/_zod-introspect.ts

@@ -0,0 +1,51 @@
+// Zod v4 runtime-introspection helpers. Each cast is a deliberate
+// schema-walk into Zod's internal shape (`_def`, `.meta()`, `.shape[k]`).
+// Centralised here so the as-cast audit's @cast-boundary schema-walk
+// markers live in one place rather than scattered through callers.
+//
+// All helpers accept the *runtime* Zod instance — TypeScript wrapper
+// (`z.ZodType`) and core (`$ZodType`) are the same object at runtime.
+
+import type { z } from "zod";
+
+export type ZodDef = {
+  readonly innerType?: z.ZodType;
+  readonly in?: z.ZodType;
+  readonly defaultValue?: unknown;
+};
+
+/** Read Zod v4 `.meta()` value. Undefined when no meta is set. */
+export function zodMeta(field: z.ZodType): unknown {
+  // @cast-boundary schema-walk
+  const fn = (field as { meta?: () => unknown }).meta;
+  return typeof fn === "function" ? fn.call(field) : undefined;
+}
+
+/** Read the `_def` slot used by ZodDefault/ZodOptional drilling. */
+export function zodDef(field: z.ZodType): ZodDef | undefined {
+  // @cast-boundary schema-walk
+  return (field as { _def?: ZodDef })._def;
+}
+
+/** Read the field-level `.describe()` value. */
+export function zodDescription(field: z.ZodType): string | undefined {
+  // @cast-boundary schema-walk
+  const desc = (field as { description?: string }).description;
+  return typeof desc === "string" && desc.length > 0 ? desc : undefined;
+}
+
+/** Treat a ZodObject's `shape` values as `z.ZodType`. Zod v4 typing
+ *  exposes them as `$ZodType` (core) — same runtime instance. */
+export function zodShape(schema: z.ZodObject<z.ZodRawShape>): Record<string, z.ZodType> {
+  // @cast-boundary schema-walk
+  return schema.shape as Record<string, z.ZodType>;
+}
+
+/** Look up a single field on a ZodObject's shape. */
+export function zodShapeField(
+  schema: z.ZodObject<z.ZodRawShape>,
+  name: string,
+): z.ZodType | undefined {
+  // @cast-boundary schema-walk
+  return schema.shape[name] as z.ZodType | undefined;
+}

package/src/env/dry-run.ts

@@ -0,0 +1,191 @@
+// Renderers for `KUMIKO_DRY_RUN_ENV=<mode>`. Operators run this against
+// a built app to discover the required env-vars without booting:
+//   - `human` — tabular, grouped by required/optional/withDefault
+//   - `json`  — machine-readable for CI / tooling
+//   - `pulumi`— `pulumi config set …`-lines for bootstrap
+//   - `k8s`   — Secret YAML stub
+//
+// The same schema introspection (`classifyField`, `readKumikoMeta`) used
+// by parseEnv drives the output here — single source of truth.
+
+import type { z } from "zod";
+import { zodShape } from "./_zod-introspect";
+import {
+  type ComposedEnvSchema,
+  classifyField,
+  type EnvFieldClass,
+  getDefaultValue,
+  getFieldDescription,
+  pulumiConfigKey,
+  readKumikoMeta,
+} from "./index";
+
+export type DryRunMode = "human" | "json" | "pulumi" | "k8s";
+
+export type DryRunOptions = {
+  /** From composeEnvSchema. Drives the per-row feature-attribution. */
+  readonly sources?: Readonly<Record<string, string>>;
+  /** Prefix for `pulumi config set <prefix>…` keys. Default "". */
+  readonly pulumiPrefix?: string;
+  /** k8s Secret name. Default "kumiko-env". */
+  readonly k8sName?: string;
+  /** k8s namespace. Default "default". */
+  readonly k8sNamespace?: string;
+};
+
+type EnvField = {
+  readonly name: string;
+  readonly field: z.ZodType;
+  readonly klass: EnvFieldClass;
+  readonly description?: string;
+  readonly defaultValue?: unknown;
+  readonly source: string; // feature name or "app" or "unknown"
+};
+
+function collectFields(
+  schema: z.ZodObject<z.ZodRawShape>,
+  sources: Readonly<Record<string, string>>,
+): readonly EnvField[] {
+  const out: EnvField[] = [];
+  for (const [name, field] of Object.entries(zodShape(schema))) {
+    const f = field;
+    const klass = classifyField(f);
+    out.push({
+      name,
+      field: f,
+      klass,
+      description: getFieldDescription(f),
+      ...(klass === "withDefault" ? { defaultValue: getDefaultValue(f) } : {}),
+      source: sources[name] ?? "unknown",
+    });
+  }
+  // Sort by class (required first), then by source, then by name. Stable
+  // ordering matters for snapshot-tests + grep-ability.
+  const order: Record<EnvFieldClass, number> = {
+    required: 0,
+    optional: 1,
+    withDefault: 2,
+  };
+  return out.sort((a, b) => {
+    if (order[a.klass] !== order[b.klass]) return order[a.klass] - order[b.klass];
+    if (a.source !== b.source) return a.source.localeCompare(b.source);
+    return a.name.localeCompare(b.name);
+  });
+}
+
+export function renderDryRun(
+  composed: ComposedEnvSchema,
+  mode: DryRunMode,
+  options: DryRunOptions = {},
+): string {
+  const sources = options.sources ?? composed.sources;
+  const fields = collectFields(composed.schema, sources);
+  switch (mode) {
+    case "human":
+      return renderHuman(fields);
+    case "json":
+      return renderJson(fields, options);
+    case "pulumi":
+      return renderPulumi(fields, options);
+    case "k8s":
+      return renderK8s(fields, options);
+  }
+}
+
+function renderHuman(fields: readonly EnvField[]): string {
+  const grouped: Record<EnvFieldClass, EnvField[]> = {
+    required: [],
+    optional: [],
+    withDefault: [],
+  };
+  for (const f of fields) grouped[f.klass].push(f);
+
+  const lines: string[] = [];
+  const sectionTitle: Record<EnvFieldClass, string> = {
+    required: "Required env-vars:",
+    optional: "Optional env-vars:",
+    withDefault: "Defaulted env-vars:",
+  };
+  const longest = fields.reduce((m, f) => Math.max(m, f.name.length), 0);
+  let first = true;
+  for (const klass of ["required", "optional", "withDefault"] as const) {
+    const items = grouped[klass];
+    if (items.length === 0) continue;
+    if (!first) lines.push("");
+    first = false;
+    lines.push(sectionTitle[klass]);
+    for (const f of items) {
+      const padded = f.name.padEnd(longest, " ");
+      const src = `(${f.source})`;
+      const dflt =
+        f.klass === "withDefault" && f.defaultValue !== undefined
+          ? ` [default: ${JSON.stringify(f.defaultValue)}]`
+          : "";
+      const desc = f.description ? ` — ${f.description}` : "";
+      lines.push(`  ${padded}  ${src}${dflt}${desc}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function renderJson(fields: readonly EnvField[], options: DryRunOptions): string {
+  const required = fields.filter((f) => f.klass === "required");
+  const optional = fields.filter((f) => f.klass === "optional");
+  const withDefault = fields.filter((f) => f.klass === "withDefault");
+
+  const toEntry = (f: EnvField) => ({
+    name: f.name,
+    feature: f.source,
+    ...(f.description ? { description: f.description } : {}),
+    ...(f.defaultValue !== undefined ? { default: f.defaultValue } : {}),
+    pulumiName: pulumiConfigKey(f.name, f.field, options.pulumiPrefix),
+  });
+
+  return `${JSON.stringify(
+    {
+      required: required.map(toEntry),
+      optional: optional.map(toEntry),
+      withDefault: withDefault.map(toEntry),
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function renderPulumi(fields: readonly EnvField[], options: DryRunOptions): string {
+  // Defaulted vars are skipped — the framework provides them, ops doesn't.
+  const lines: string[] = [];
+  for (const f of fields) {
+    if (f.klass === "withDefault") continue;
+    if (f.klass === "optional") continue;
+    const meta = readKumikoMeta(f.field);
+    const key = pulumiConfigKey(f.name, f.field, options.pulumiPrefix);
+    const secretFlag = meta.pulumi?.secret ? " --secret" : "";
+    const value = meta.pulumi?.generator ? `"$(${meta.pulumi.generator})"` : `"<set-me>"`;
+    const comment = f.description
+      ? ` # ${f.name} (${f.source}): ${f.description}`
+      : ` # ${f.name} (${f.source})`;
+    lines.push(`pulumi config set${secretFlag} ${key} ${value}${comment}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function renderK8s(fields: readonly EnvField[], options: DryRunOptions): string {
+  const name = options.k8sName ?? "kumiko-env";
+  const namespace = options.k8sNamespace ?? "default";
+  const lines: string[] = [
+    "apiVersion: v1",
+    "kind: Secret",
+    "metadata:",
+    `  name: ${name}`,
+    `  namespace: ${namespace}`,
+    "type: Opaque",
+    "stringData:",
+  ];
+  for (const f of fields) {
+    if (f.klass === "withDefault") continue;
+    if (f.klass === "optional") continue;
+    lines.push(`  ${f.name}: "<set-me>"`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/env/index.ts

@@ -0,0 +1,349 @@
+// Env-Schema composition for Kumiko apps.
+//
+// Each feature declares its required env-vars via `r.envSchema(z.object({...}))`.
+// `composeEnvSchema({ features, extend })` merges those into one app-wide
+// Zod-object that `runProdApp` validates `process.env` against at boot.
+//
+// On invalid/missing vars `parseEnv` throws `KumikoBootError` with ALL
+// problems aggregated (Zod's safeParse traverses every field before
+// short-circuiting). `runProdApp` catches at its top level and renders
+// via `KumikoBootError.format()` — so apps don't repeat the try/catch.
+//
+// Per-var metadata for deploy-time tooling (Pulumi-config-key override,
+// generator command, k8s hints) lives in Zod's `.meta({ kumiko: {...} })`.
+// Without meta, defaults: `camelCase(envVarName)` for the Pulumi key,
+// `<set-me>` placeholder for the value, no `--secret` flag.
+
+import { z } from "zod";
+import type { FeatureDefinition } from "../engine/types/feature";
+import { zodDef, zodDescription, zodMeta, zodShape, zodShapeField } from "./_zod-introspect";
+
+// --- Per-env-var metadata (attach via Zod's `.meta()`) ---
+
+export type KumikoEnvMeta = {
+  readonly pulumi?: {
+    /** Override the auto-derived camelCase Pulumi-config-key name. Apps
+     *  setting `pulumiPrefix: "studio"` and authoring `STUDIO_ADMIN_EMAIL`
+     *  would otherwise get `studioStudioAdminEmail` — set
+     *  `.meta({ kumiko: { pulumi: { name: "adminEmail" } } })` to drop the
+     *  duplicated prefix. */
+    readonly name?: string;
+    /** Shell expression that generates a value, e.g. `openssl rand -base64 32`.
+     *  Without this, dry-run-pulumi emits `<set-me>` as the placeholder. */
+    readonly generator?: string;
+    /** Force the `--secret` flag in `pulumi config set`. Default false. */
+    readonly secret?: boolean;
+  };
+};
+
+function isKumikoMeta(value: unknown): value is KumikoEnvMeta {
+  if (value === null || typeof value !== "object") return false;
+  // @cast-boundary schema-walk — runtime-shape narrowing of zod-meta payload
+  const v = value as { pulumi?: unknown };
+  if (v.pulumi === undefined) return true;
+  if (v.pulumi === null || typeof v.pulumi !== "object") return false;
+  // @cast-boundary schema-walk
+  const p = v.pulumi as { name?: unknown; generator?: unknown; secret?: unknown };
+  if (p.name !== undefined && typeof p.name !== "string") return false;
+  if (p.generator !== undefined && typeof p.generator !== "string") return false;
+  if (p.secret !== undefined && typeof p.secret !== "boolean") return false;
+  return true;
+}
+
+export function readKumikoMeta(field: z.ZodType): KumikoEnvMeta {
+  const meta = zodMeta(field);
+  if (meta && typeof meta === "object" && meta !== null && "kumiko" in meta) {
+    // @cast-boundary schema-walk
+    const k = (meta as { kumiko?: unknown }).kumiko;
+    if (isKumikoMeta(k)) return k;
+  }
+  return {};
+}
+
+// --- Field-classification helpers (Zod v4 introspection) ---
+
+export type EnvFieldClass = "required" | "optional" | "withDefault";
+
+export function classifyField(field: z.ZodType): EnvFieldClass {
+  // Drill through ZodEffects/ZodPipe wrappers to find the inner kind.
+  let current: z.ZodType = field;
+  for (let i = 0; i < 8; i++) {
+    if (current instanceof z.ZodDefault) return "withDefault";
+    if (current instanceof z.ZodOptional || current instanceof z.ZodNullable) {
+      return "optional";
+    }
+    const inner = zodDef(current);
+    if (inner?.innerType) {
+      current = inner.innerType;
+      continue;
+    }
+    if (inner?.in) {
+      current = inner.in;
+      continue;
+    }
+    break;
+  }
+  return "required";
+}
+
+export function getDefaultValue(field: z.ZodType): unknown {
+  let current: z.ZodType = field;
+  for (let i = 0; i < 8; i++) {
+    if (current instanceof z.ZodDefault) {
+      // Zod v4: defaultValue is the raw value (v3 was a factory function).
+      // Support both shapes for forward/backward safety.
+      const raw = zodDef(current)?.defaultValue;
+      // @cast-boundary schema-walk — Zod v3 stored a thunk, v4 a raw value
+      return typeof raw === "function" ? (raw as () => unknown)() : raw;
+    }
+    const inner = zodDef(current);
+    if (inner?.innerType) {
+      current = inner.innerType;
+      continue;
+    }
+    break;
+  }
+  return undefined;
+}
+
+export function getFieldDescription(field: z.ZodType): string | undefined {
+  return zodDescription(field);
+}
+
+// --- Compose ---
+
+export type ComposeEnvSchemaOptions = {
+  /** All features whose envSchemas should be merged. */
+  readonly features: readonly FeatureDefinition[];
+  /** App-specific env-vars (e.g. `STUDIO_ADMIN_EMAIL`). Keys here are
+   *  tagged as source "app" in the resulting sources map. */
+  readonly extend?: z.ZodObject<z.ZodRawShape>;
+  /** Feature-names whose env-vars should be auto-`.optional()`-wrapped.
+   *  Lets an app opt out of e.g. `channel-email-smtp`'s vars without
+   *  manually `.partial()`-ing each shape at the call-site. */
+  readonly optionalFeatures?: readonly string[];
+  /** Framework-core env-vars (PORT, DATABASE_URL, REDIS_URL, …) from
+   *  `@cosmicdrift/kumiko-dev-server`. Keys here are tagged as source
+   *  "framework-core" in error output. Conflict-detection runs across
+   *  core/features/extend as one merged pool — same key declared in two
+   *  layers throws KumikoBootError at compose-time. */
+  readonly core?: z.ZodObject<z.ZodRawShape>;
+};
+
+export type ComposedEnvSchema = {
+  /** The merged Zod schema. Type-erased to `ZodObject<ZodRawShape>` — TS
+   *  can't variadic-merge N generic feature schemas without tuple gymnastics
+   *  that hurt readability. For type-safe `z.infer` in app code, build a
+   *  parallel typed schema manually (see Plan-Doc
+   *  `kumiko-studio/docs/plans/sprint-9-env-schemas.md` → API-Design)
+   *  and only pass `composed.schema` to `runProdApp` for validation. */
+  readonly schema: z.ZodObject<z.ZodRawShape>;
+  /** env-var-name → declaring source-name: feature-name from `r.envSchema()`,
+   *  "app" from `extend`, or "framework-core" from `core`. */
+  readonly sources: Readonly<Record<string, string>>;
+};
+
+export function composeEnvSchema(options: ComposeEnvSchemaOptions): ComposedEnvSchema {
+  const optionalSet = new Set(options.optionalFeatures ?? []);
+  const merged: Record<string, z.ZodType> = {};
+  const sources: Record<string, string> = {};
+
+  // Framework-core first so a feature that accidentally declares the same
+  // var (e.g. PORT) gets a clear conflict error citing "framework-core"
+  // rather than silently overwriting a deploy-critical default. The
+  // conflict-detection makes the order safe in both directions — both
+  // throw — but downstream tools that consume `sources` (e.g. the
+  // upcoming Phase-5 lint-guard) may rely on this insertion order.
+  if (options.core) {
+    for (const [key, field] of Object.entries(zodShape(options.core))) {
+      merged[key] = field;
+      sources[key] = "framework-core";
+    }
+  }
+
+  for (const feature of options.features) {
+    if (!feature.envSchema) continue;
+    const shape = zodShape(feature.envSchema);
+    const wrap = optionalSet.has(feature.name);
+    for (const [key, field] of Object.entries(shape)) {
+      if (merged[key] !== undefined) {
+        throw new KumikoBootError([
+          {
+            name: key,
+            kind: "invalid",
+            message:
+              `env-var conflict: "${key}" declared by both ` +
+              `"${sources[key]}" and "${feature.name}" — pick one owner.`,
+          },
+        ]);
+      }
+      merged[key] = wrap ? field.optional() : field;
+      sources[key] = feature.name;
+    }
+  }
+
+  if (options.extend) {
+    for (const [key, field] of Object.entries(zodShape(options.extend))) {
+      if (merged[key] !== undefined) {
+        throw new KumikoBootError([
+          {
+            name: key,
+            kind: "invalid",
+            message:
+              `env-var conflict: "${key}" declared by both "${sources[key]}" ` +
+              `and the app's extend block — rename one.`,
+          },
+        ]);
+      }
+      merged[key] = field;
+      sources[key] = "app";
+    }
+  }
+
+  return {
+    schema: z.object(merged),
+    sources,
+  };
+}
+
+// --- Errors ---
+
+export type EnvErrorKind = "missing" | "invalid";
+
+export type EnvError = {
+  readonly name: string;
+  readonly kind: EnvErrorKind;
+  readonly message: string;
+  /** Declaring source-name from `composeEnvSchema`'s sources map:
+   *  feature-name, "app" from `extend`, or "framework-core" from `core`.
+   *  Populated when parseEnv received `options.sources`. Surfaced by
+   *  `KumikoBootError.format()` so operators see WHICH source wants the
+   *  missing var, not just the var name. */
+  readonly source?: string;
+  /** "Set via: pulumi config set ..." line. Computed when pulumiPrefix is
+   *  passed to parseEnv. */
+  readonly suggestion?: string;
+};
+
+export class KumikoBootError extends Error {
+  readonly errors: readonly EnvError[];
+
+  constructor(errors: readonly EnvError[]) {
+    super(`Boot failed: ${errors.length} env-var problem${errors.length === 1 ? "" : "s"}`);
+    this.name = "KumikoBootError";
+    this.errors = errors;
+  }
+
+  format(): string {
+    const lines: string[] = [
+      `Boot failed: ${this.errors.length} env-var problem${this.errors.length === 1 ? "" : "s"}`,
+      "",
+    ];
+    for (const err of this.errors) {
+      const tag = err.kind === "missing" ? "required, missing" : "invalid";
+      const sourceTag = err.source ? `${err.source}, ${tag}` : tag;
+      lines.push(`  ✗ ${err.name} (${sourceTag})`);
+      lines.push(`    ${err.message}`);
+      if (err.suggestion) {
+        lines.push(`    ${err.suggestion}`);
+      }
+    }
+    lines.push("");
+    lines.push(
+      "See: kumiko-platform/docs/runbooks/standard-deploy-app.md#step-1-boot-dry-run-lokal",
+    );
+    return lines.join("\n");
+  }
+}
+
+// --- Parse ---
+
+export type ParseEnvOptions = {
+  /** From composeEnvSchema's return — enables per-var feature-source
+   *  attribution in suggestions. */
+  readonly sources?: Readonly<Record<string, string>>;
+  /** When set, error suggestions include `pulumi config set <prefix>...`. */
+  readonly pulumiPrefix?: string;
+};
+
+export function parseEnv<S extends z.ZodObject<z.ZodRawShape>>(
+  schema: S,
+  env: Record<string, string | undefined>,
+  options: ParseEnvOptions = {},
+): z.infer<S> {
+  // Filter undefined values to keep Zod's required-vs-invalid signal clean.
+  // (process.env returns string|undefined; passing undefined would parse
+  // as "field is set to undefined" which clouds the missing-key heuristic.)
+  const cleaned: Record<string, string> = {};
+  for (const [k, v] of Object.entries(env)) {
+    if (v !== undefined) cleaned[k] = v;
+  }
+
+  const result = schema.safeParse(cleaned);
+  if (result.success) {
+    // @cast-boundary schema-walk — z.infer<S> erasure across safeParse result
+    return result.data as z.infer<S>;
+  }
+
+  // Map Zod-issues → EnvError[], augmenting with suggestions when meta+prefix.
+  const errors: EnvError[] = result.error.issues.map((issue) => {
+    const name = String(issue.path[0] ?? "<unknown>");
+    const field = zodShapeField(schema, name);
+    // Zod v4 dropped the `received` property on invalid_type issues; the
+    // canonical signal for "value was missing" is now "the key isn't in
+    // the input object". Use input-presence as the missing/invalid switch.
+    const isMissing = issue.code === "invalid_type" && !(name in cleaned);
+    const kind: EnvErrorKind = isMissing ? "missing" : "invalid";
+    const desc = field ? getFieldDescription(field) : undefined;
+    const message = desc ? `${issue.message} — ${desc}` : issue.message;
+    const suggestion = field ? buildPulumiSuggestion(name, field, options.pulumiPrefix) : undefined;
+    const source = options.sources?.[name];
+    return {
+      name,
+      kind,
+      message,
+      ...(source ? { source } : {}),
+      ...(suggestion ? { suggestion } : {}),
+    };
+  });
+
+  throw new KumikoBootError(errors);
+}
+
+// --- Pulumi-suggestion ---
+
+function ucfirst(s: string): string {
+  return s.length === 0 ? s : s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+export function camelCase(snakeShout: string): string {
+  const parts = snakeShout.toLowerCase().split("_").filter(Boolean);
+  if (parts.length === 0) return snakeShout.toLowerCase();
+  return parts[0] + parts.slice(1).map(ucfirst).join("");
+}
+
+export function pulumiConfigKey(
+  envName: string,
+  field: z.ZodType | undefined,
+  prefix: string | undefined,
+): string {
+  const meta = field ? readKumikoMeta(field) : {};
+  if (meta.pulumi?.name) {
+    return prefix ? prefix + ucfirst(meta.pulumi.name) : meta.pulumi.name;
+  }
+  const camel = camelCase(envName);
+  return prefix ? prefix + ucfirst(camel) : camel;
+}
+
+export function buildPulumiSuggestion(
+  envName: string,
+  field: z.ZodType,
+  prefix: string | undefined,
+): string | undefined {
+  if (!prefix) return undefined;
+  const meta = readKumikoMeta(field);
+  const key = pulumiConfigKey(envName, field, prefix);
+  const secretFlag = meta.pulumi?.secret ? " --secret" : "";
+  const value = meta.pulumi?.generator ? `"$(${meta.pulumi.generator})"` : `"<set-me>"`;
+  return `Set via: pulumi config set${secretFlag} ${key} ${value}`;
+}