@cosmicdrift/kumiko-framework 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @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
+
+- bcf43b6: es-ops: `SeedMembershipRow` exposes `streamTenantId` (stream-tenant aus `kumiko_events.v1`) neben dem payload-`tenantId`. Seed-Authors müssen den `kumiko_events`-JOIN nicht mehr selbst bauen — `m.streamTenantId` ist der korrekte Wert für `systemWriteAs`'s `tenantIdOverride` wenn das Aggregate von einem fremden Executor angelegt wurde (typisches `seedTenantMembership(by=systemAdmin)`-Pattern).
+
 ## 0.6.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.6.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.6.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");
+  });
+});