@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/config/resolver.ts

@@ -0,0 +1,687 @@
+import { requestContext } from "@cosmicdrift/kumiko-framework/api";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configuredPiiSubjectKms,
+  decryptPiiValueForSubject,
+  type KmsContext,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import type { DbConnection, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type {
+  ConfigCascade,
+  ConfigCascadeLevel,
+  ConfigKeyDefinition,
+  ConfigResolver,
+  ConfigSecretsReader,
+  ConfigValueSource,
+  ConfigValueWithSource,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
+import { assertUnreachable, parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
+import { selectConfigRowsForKeys, selectConfigRowsForScope } from "./db/queries/resolver.js";
+import { configValuesTable } from "./table.js";
+
+type ConfigRow = {
+  id: string;
+  key: string;
+  value: string | null;
+  tenantId: string;
+  userId: string | null;
+};
+
+// Re-export so existing call sites that imported ConfigResolver from
+// "../resolver" keep compiling — the shape now lives in the framework.
+export type { ConfigResolver };
+
+export function deserializeValue(
+  raw: string | null,
+  type: ConfigKeyDefinition["type"],
+): string | number | boolean | undefined {
+  if (raw === null || raw === undefined) return undefined;
+  const parsed = parseJsonOrThrow<unknown>(raw, `config value (type=${type})`);
+  switch (type) {
+    case "number": {
+      const n = typeof parsed === "number" ? parsed : Number(parsed);
+      if (!Number.isFinite(n)) {
+        throw new Error(`config value (type=number): "${raw}" does not deserialize to a number.`);
+      }
+      return n;
+    }
+    case "boolean":
+      return typeof parsed === "boolean" ? parsed : parsed === "true";
+    case "text":
+    case "select":
+      return String(parsed);
+    default:
+      assertUnreachable(type, "config key type");
+  }
+}
+
+// App-Boot overrides: deploy-time defaults that sit between the
+// tenant/system rows and the feature-declared `default`. Use-case: the
+// framework ships a default of 10 MB for maxUploadSizeMB, but this
+// particular deploy is a photo-app that wants 200 MB — no DB-seed needed,
+// just a single Map at boot.
+//
+// Keys are the fully-qualified names (e.g. "files:config:max-upload-size-mb").
+// Values are the raw primitive — serialization happens as part of the
+// cascade so the boot-code doesn't need to know about JSON encoding.
+//
+// Validation at construction time (buildServer-path): unknown keys,
+// type-mismatches, and bounds violations throw synchronously. See
+// validateAppOverrides below.
+export type AppConfigOverrides = ReadonlyMap<string, string | number | boolean>;
+
+export type ConfigResolverOptions = {
+  // Envelope cipher for `encrypted: true` keys. run{Prod,Dev}App wire it
+  // automatically from the secrets master key — apps only pass their own
+  // to override (tests, custom providers).
+  cipher?: EnvelopeCipher;
+  appOverrides?: AppConfigOverrides;
+};
+
+// Decrypt gate for encrypted keys: an encrypted row without a cipher MUST
+// throw — passing the ciphertext through as the "value" (the pre-envelope
+// behavior) silently feeds base64 garbage to whatever consumes the key
+// (e.g. an SMTP password) and is a debugging nightmare.
+async function decryptEncrypted(
+  cipher: EnvelopeCipher | undefined,
+  raw: string,
+  qualifiedKey: string,
+): Promise<string> {
+  if (!cipher) {
+    throw new InternalError({
+      message:
+        `[config] key "${qualifiedKey}" is encrypted but no cipher is wired — the boot must ` +
+        `provide a master key (KUMIKO_SECRETS_MASTER_KEY_V<n>) or pass ConfigResolverOptions.cipher.`,
+      i18nKey: "config.errors.cipher_missing",
+    });
+  }
+  return cipher.decrypt(raw);
+}
+
+// Decrypt gate for piiEncrypted keys, mirroring decryptEncrypted above.
+// The subject lives inside the ciphertext (kumiko-pii:v1:<subject>:...),
+// so unlike the write side, no scope/subject resolution is needed here —
+// same call works for a user-row or a tenant-row value.
+async function decryptPiiEncrypted(raw: string, qualifiedKey: string): Promise<string> {
+  const kms = configuredPiiSubjectKms();
+  if (!kms) {
+    throw new InternalError({
+      message:
+        `[config] key "${qualifiedKey}" is piiEncrypted but no PII subject-KMS is wired — the ` +
+        `boot must configure one via runProdApp({ kms }) / configurePiiSubjectKms(adapter).`,
+      i18nKey: "config.errors.cipher_missing",
+    });
+  }
+  const kmsCtx: KmsContext = { requestId: requestContext.get()?.requestId ?? "config:resolver" };
+  return decryptPiiValueForSubject(kms, raw, kmsCtx, qualifiedKey);
+}
+
+// backing="secrets" keys store their value in the secrets store (flat per
+// (tenant,key) at SYSTEM_TENANT_ID), not in config_values. Both read paths
+// (getWithSource + buildCascade) route the system rung here. Missing reader =
+// the app never wired extraContext.secrets → fail loud, never silently miss.
+async function readBackingSecret(
+  secretsReader: ConfigSecretsReader | undefined,
+  qualifiedKey: string,
+): Promise<string | undefined> {
+  if (!secretsReader) {
+    throw new InternalError({
+      message:
+        `[config] backing="secrets" key "${qualifiedKey}" was read without a secrets ` +
+        `reader — wire extraContext.secrets (and a MasterKeyProvider) so the secrets ` +
+        `store is reachable at request time.`,
+    });
+  }
+  const secret = await secretsReader.get(SYSTEM_TENANT_ID, qualifiedKey);
+  return secret?.reveal();
+}
+
+// Shared cascade-builder. Single-key path passes a `findRow`-bound row
+// fetcher (one SQL per lookup); batch path passes a closure over
+// pre-loaded rows. The builder itself is unaware of which.
+async function buildCascade(
+  qualifiedKey: string,
+  keyDef: ConfigKeyDefinition,
+  tenantId: string,
+  userId: string,
+  db: DbConnection | TenantDb,
+  fetchRow: (
+    tenantId: string,
+    userId: string | null,
+  ) => Promise<ConfigRow | null> | ConfigRow | null,
+  appOverrides: AppConfigOverrides | undefined,
+  cipher: EnvelopeCipher | undefined,
+  secretsReader: ConfigSecretsReader | undefined,
+): Promise<ConfigCascade> {
+  type Lookup = {
+    tenantId: string;
+    userId: string | null;
+    source: ConfigValueSource;
+    label: string;
+  };
+  const lookups: Lookup[] = [];
+
+  switch (keyDef.scope) {
+    case "user":
+      lookups.push({ tenantId, userId, source: "user-row", label: "User" });
+      lookups.push({ tenantId, userId: null, source: "tenant-row", label: "Tenant" });
+      lookups.push({
+        tenantId: SYSTEM_TENANT_ID,
+        userId: null,
+        source: "system-row",
+        label: "System",
+      });
+      break;
+    case "tenant":
+      lookups.push({ tenantId, userId: null, source: "tenant-row", label: "Tenant" });
+      lookups.push({
+        tenantId: SYSTEM_TENANT_ID,
+        userId: null,
+        source: "system-row",
+        label: "System",
+      });
+      break;
+    case "system":
+      lookups.push({
+        tenantId: SYSTEM_TENANT_ID,
+        userId: null,
+        source: "system-row",
+        label: "System",
+      });
+      break;
+    default:
+      assertUnreachable(keyDef.scope, "config scope");
+  }
+
+  const levels: ConfigCascadeLevel[] = [];
+  let activeIndex = -1;
+
+  for (const lookup of lookups) {
+    // backing="secrets" is system-only (boot-guard), so the single system-row
+    // rung reads from the secrets store instead of config_values. The secret
+    // value is the same JSON-serialized form a config row would hold (set.write
+    // serializes before handing it to secrets), so deserializeValue applies;
+    // no config-level decrypt — the secrets envelope already returned plaintext.
+    if (keyDef.backing === "secrets" && lookup.source === "system-row") {
+      const secret = await readBackingSecret(secretsReader, qualifiedKey);
+      if (secret !== undefined) {
+        if (activeIndex === -1) activeIndex = levels.length;
+        levels.push({
+          label: lookup.label,
+          value: deserializeValue(secret, keyDef.type),
+          source: lookup.source,
+          isActive: false,
+          hasValue: true,
+        });
+      } else {
+        levels.push({
+          label: lookup.label,
+          value: undefined,
+          source: lookup.source,
+          isActive: false,
+          hasValue: false,
+        });
+      }
+      continue;
+    }
+
+    const row = await fetchRow(lookup.tenantId, lookup.userId);
+    if (row?.value !== null && row?.value !== undefined) {
+      let raw = row.value;
+      if (keyDef.encrypted) {
+        raw = await decryptEncrypted(cipher, raw, qualifiedKey);
+      } else if (keyDef.piiEncrypted) {
+        raw = await decryptPiiEncrypted(raw, qualifiedKey);
+      }
+      if (activeIndex === -1) activeIndex = levels.length;
+      levels.push({
+        label: lookup.label,
+        value: deserializeValue(raw, keyDef.type),
+        source: lookup.source,
+        isActive: false,
+        hasValue: true,
+      });
+    } else {
+      levels.push({
+        label: lookup.label,
+        value: undefined,
+        source: lookup.source,
+        isActive: false,
+        hasValue: false,
+      });
+    }
+  }
+
+  const overrideValue = appOverrides?.get(qualifiedKey);
+  const hasOverride = overrideValue !== undefined;
+  if (activeIndex === -1 && hasOverride) activeIndex = levels.length;
+  levels.push({
+    label: "App-Override",
+    value: overrideValue,
+    source: "app-override",
+    isActive: false,
+    hasValue: hasOverride,
+  });
+
+  if (keyDef.computed) {
+    const value = await keyDef.computed({ tenantId, userId, db });
+    if (activeIndex === -1) activeIndex = levels.length;
+    levels.push({
+      label: "Computed",
+      value,
+      source: "computed",
+      isActive: false,
+      hasValue: true,
+    });
+  } else {
+    levels.push({
+      label: "Computed",
+      value: undefined,
+      source: "computed",
+      isActive: false,
+      hasValue: false,
+    });
+  }
+
+  if (keyDef.default !== undefined) {
+    if (activeIndex === -1) activeIndex = levels.length;
+    levels.push({
+      label: "Default",
+      value: keyDef.default,
+      source: "default",
+      isActive: false,
+      hasValue: true,
+    });
+  } else {
+    if (activeIndex === -1) activeIndex = levels.length;
+    levels.push({
+      label: "Default",
+      value: undefined,
+      source: "missing",
+      isActive: false,
+      hasValue: false,
+    });
+  }
+
+  const active = activeIndex >= 0 ? levels[activeIndex] : undefined;
+  if (active !== undefined) {
+    levels[activeIndex] = { ...active, isActive: true };
+  }
+
+  return {
+    value: active?.value,
+    source: active?.source ?? "missing",
+    levels,
+  };
+}
+
+export function createConfigResolver(options: ConfigResolverOptions = {}): ConfigResolver {
+  const { cipher, appOverrides } = options;
+  async function findRow(
+    key: string,
+    tenantId: string,
+    userId: string | null,
+    db: DbConnection | TenantDb,
+  ): Promise<ConfigRow | null> {
+    const row = await fetchOne<ConfigRow>(db, configValuesTable, {
+      key,
+      tenantId,
+      userId,
+    });
+
+    return row ?? null;
+  }
+
+  return {
+    async get(qualifiedKey, keyDef, tenantId, userId, db, secretsReader) {
+      // get() is a thin wrapper around getWithSource that discards the
+      // source tag. Keeps the hot-path a single implementation.
+      const result = await this.getWithSource(
+        qualifiedKey,
+        keyDef,
+        tenantId,
+        userId,
+        db,
+        secretsReader,
+      );
+      return result.value;
+    },
+
+    async getWithSource(
+      qualifiedKey,
+      keyDef,
+      tenantId,
+      userId,
+      db,
+      secretsReader,
+    ): Promise<ConfigValueWithSource> {
+      // backing="secrets": the value lives in the secrets store at the system
+      // tenant, not config_values. Read it directly (system-only by boot-guard)
+      // and skip the config-row lookups; app-override/computed/default still
+      // form the fallback ladder when the secret is unset.
+      if (keyDef.backing === "secrets") {
+        const secret = await readBackingSecret(secretsReader, qualifiedKey);
+        if (secret !== undefined) {
+          return { value: deserializeValue(secret, keyDef.type), source: "system-row" };
+        }
+        if (appOverrides?.has(qualifiedKey)) {
+          return { value: appOverrides.get(qualifiedKey), source: "app-override" };
+        }
+        if (keyDef.computed) {
+          const value = await keyDef.computed({ tenantId, userId, db });
+          return { value, source: "computed" };
+        }
+        if (keyDef.default !== undefined) {
+          return { value: keyDef.default, source: "default" };
+        }
+        return { value: undefined, source: "missing" };
+      }
+      // Resolution cascade based on scope
+      // user:   userId+tenantId → tenantId → SYSTEM_TENANT_ID → default
+      // tenant: tenantId → SYSTEM_TENANT_ID → default
+      // system: SYSTEM_TENANT_ID → default
+      const lookups: Array<{
+        tenantId: string;
+        userId: string | null;
+        source: ConfigValueSource;
+      }> = [];
+
+      switch (keyDef.scope) {
+        case "user":
+          lookups.push({ tenantId, userId, source: "user-row" });
+          lookups.push({ tenantId, userId: null, source: "tenant-row" });
+          lookups.push({ tenantId: SYSTEM_TENANT_ID, userId: null, source: "system-row" });
+          break;
+        case "tenant":
+          lookups.push({ tenantId, userId: null, source: "tenant-row" });
+          lookups.push({ tenantId: SYSTEM_TENANT_ID, userId: null, source: "system-row" });
+          break;
+        case "system":
+          lookups.push({ tenantId: SYSTEM_TENANT_ID, userId: null, source: "system-row" });
+          break;
+        default:
+          assertUnreachable(keyDef.scope, "config scope");
+      }
+
+      for (const lookup of lookups) {
+        const row = await findRow(qualifiedKey, lookup.tenantId, lookup.userId, db);
+        if (row?.value !== null && row?.value !== undefined) {
+          let raw = row.value;
+          if (keyDef.encrypted) {
+            raw = await decryptEncrypted(cipher, raw, qualifiedKey);
+          } else if (keyDef.piiEncrypted) {
+            raw = await decryptPiiEncrypted(raw, qualifiedKey);
+          }
+          return { value: deserializeValue(raw, keyDef.type), source: lookup.source };
+        }
+      }
+
+      // App-Boot-Override: one step above the feature-declared default.
+      // The override only kicks in when no scope-specific row exists —
+      // a tenant-admin that deliberately set a value still wins.
+      if (appOverrides?.has(qualifiedKey)) {
+        return { value: appOverrides.get(qualifiedKey), source: "app-override" };
+      }
+
+      // Computed fallback: plan-based values, feature-flag-Resolver etc.
+      // Called after rows + app-overrides miss, before the static default.
+      if (keyDef.computed) {
+        const value = await keyDef.computed({ tenantId, userId, db });
+        return { value, source: "computed" };
+      }
+
+      if (keyDef.default !== undefined) {
+        return { value: keyDef.default, source: "default" };
+      }
+
+      return { value: undefined, source: "missing" };
+    },
+
+    // NOTE: getAll reads only config_values rows and does NOT dispatch to the
+    // secrets store (unlike get/getCascade/getWithSource). A backing="secrets"
+    // key has no config_values row, so it is simply ABSENT from the result map
+    // — never a stale/undefined value. Callers needing a secrets-backed value
+    // must use get/getCascade; this bulk reader is for config_values-backed
+    // keys only.
+    async getAll(tenantId, userId, db) {
+      // Only load rows relevant to this user/tenant (system + tenant + user scope)
+      const rows = await selectConfigRowsForScope(db, SYSTEM_TENANT_ID, tenantId, userId);
+
+      const result = new Map<string, ConfigRow>();
+      for (const r of rows) {
+        // Higher specificity wins: user > tenant > system. Under the ES
+        // schema system rows carry SYSTEM_TENANT_ID instead of NULL, so the
+        // "tenant set" check compares against the sentinel rather than null.
+        const specificityOf = (candidate: ConfigRow) =>
+          (candidate.userId !== null ? 2 : 0) + (candidate.tenantId !== SYSTEM_TENANT_ID ? 1 : 0);
+        const existing = result.get(r.key);
+        if (!existing || specificityOf(r) > specificityOf(existing)) {
+          result.set(r.key, r);
+        }
+      }
+
+      return result;
+    },
+
+    async getCascade(
+      qualifiedKey,
+      keyDef,
+      tenantId,
+      userId,
+      db,
+      secretsReader,
+    ): Promise<ConfigCascade> {
+      // Single-key path uses findRow per cascade step. The batch path
+      // bulk-loads all rows up-front; both build identical levels arrays.
+      return buildCascade(
+        qualifiedKey,
+        keyDef,
+        tenantId,
+        userId,
+        db,
+        (tid, uid) => findRow(qualifiedKey, tid, uid, db),
+        appOverrides,
+        cipher,
+        secretsReader,
+      );
+    },
+
+    async getCascadeBatch(
+      keys,
+      keyDefs,
+      tenantId,
+      userId,
+      db,
+      secretsReader,
+    ): Promise<ReadonlyMap<string, ConfigCascade>> {
+      if (keys.length === 0) return new Map();
+
+      // One SQL query for all keys + every scope (user-row,
+      // tenant-row, system-row). The cascade-builder then matches
+      // per-key from this preloaded set instead of querying again.
+      const rows = await selectConfigRowsForKeys(db, keys, SYSTEM_TENANT_ID, tenantId, userId);
+
+      const grouped = new Map<string, ConfigRow[]>();
+      for (const r of rows) {
+        const g = grouped.get(r.key) ?? [];
+        g.push(r);
+        grouped.set(r.key, g);
+      }
+
+      const result = new Map<string, ConfigCascade>();
+      for (const key of keys) {
+        const keyDef = keyDefs.get(key);
+        if (!keyDef) continue;
+
+        const keyRows = grouped.get(key) ?? [];
+        const cascade = await buildCascade(
+          key,
+          keyDef,
+          tenantId,
+          userId,
+          db,
+          (tid, uid) =>
+            keyRows.find((r) => r.tenantId === tid && (r.userId ?? null) === uid) ?? null,
+          appOverrides,
+          cipher,
+          secretsReader,
+        );
+        result.set(key, cascade);
+      }
+
+      return result;
+    },
+  };
+}
+
+// Validates an app-override Map against a registry before the resolver
+// ingests it. Call this from buildServer (or the app's boot wiring) with
+// the registry's config keys + the overrides the app-dev provided.
+//
+// Four classes of errors, all thrown eagerly so a typo in boot-code fails
+// immediately instead of silently returning stale defaults in production:
+//   1. unknown key → feature probably renamed or not required
+//   2. type mismatch → wrong primitive (number for a text key, etc.)
+//   3. bounds / options violation → same rule as tenant-admin Set
+//   4. computed conflict → app-override would silently beat plan-based
+//      logic; incompatible paradigm, requires explicit resolution
+//
+// The return is a narrowed Map ready to hand to createConfigResolver.
+export function validateAppOverrides(
+  registry: {
+    getConfigKey: (
+      key: string,
+    ) => import("@cosmicdrift/kumiko-framework/engine").ConfigKeyDefinition | undefined;
+  },
+  overrides: Readonly<Record<string, string | number | boolean>>,
+): AppConfigOverrides {
+  const validated = new Map<string, string | number | boolean>();
+
+  for (const [key, value] of Object.entries(overrides)) {
+    const keyDef = registry.getConfigKey(key);
+    if (!keyDef) {
+      throw new Error(
+        `App-Boot-Override for unknown config key "${key}" — no feature declares it. Typo or missing feature-require?`,
+      );
+    }
+
+    // computed keys encode plan-based business logic ("zahlender Tenant
+    // bekommt 100 MB"). An app-override would silently beat that — the
+    // cascade puts overrides above computed, so the plan becomes invisible.
+    // Force an explicit decision: either drop the override and trust the
+    // computed function, or drop computed if the deploy really wants a
+    // static default for everyone. Mixing silently is a footgun.
+    if (keyDef.computed) {
+      throw new Error(
+        `App-Boot-Override for "${key}": this key has a computed resolver (plan-based / derived). App-overrides would silently bypass that logic — remove the override, or remove the computed resolver if a flat deploy-default is intended.`,
+      );
+    }
+
+    // Per keyDef.type narrow value inline — TS narrowt nicht durch
+    // `typeof value !== typeForKey(...)` (typeForKey returnt string,
+    // kein discriminator). Das vermeidet `value as string|number` casts
+    // unten, weil value innerhalb des Branches schon typed ist.
+    if (keyDef.type === "number") {
+      if (typeof value !== "number") {
+        throw new Error(`App-Boot-Override for "${key}": expected number, got ${typeof value}`);
+      }
+      if (keyDef.bounds) {
+        const { min, max } = keyDef.bounds;
+        if (min !== undefined && value < min) {
+          throw new Error(
+            `App-Boot-Override for "${key}": value ${value} is below bounds.min (${min})`,
+          );
+        }
+        if (max !== undefined && value > max) {
+          throw new Error(
+            `App-Boot-Override for "${key}": value ${value} is above bounds.max (${max})`,
+          );
+        }
+      }
+    } else if (keyDef.type === "boolean") {
+      if (typeof value !== "boolean") {
+        throw new Error(`App-Boot-Override for "${key}": expected boolean, got ${typeof value}`);
+      }
+    } else {
+      // text or select
+      if (typeof value !== "string") {
+        throw new Error(`App-Boot-Override for "${key}": expected string, got ${typeof value}`);
+      }
+      if (keyDef.type === "select" && keyDef.options && !keyDef.options.includes(value)) {
+        throw new Error(
+          `App-Boot-Override for "${key}": value "${value}" is not in options [${keyDef.options.join(", ")}]`,
+        );
+      }
+    }
+
+    validated.set(key, value);
+  }
+
+  return validated;
+}
+
+// --- ENV → App-Override Bridge ---
+//
+// Realises the `env` field of a config key: at boot every config
+// key that declares `env` reads its value from the process environment and
+// injects it as an app-override default (the cascade rung between the
+// tenant/system rows and the declared default). String env values are coerced
+// to the key's type; a mismatch fails the boot loudly rather than silently
+// resolving to the wrong value. Reuses validateAppOverrides for the
+// existence / bounds / options / computed-conflict gates.
+//
+// undefined OR blank env vars are skipped — an unset, empty (`FOO=`) or
+// whitespace-only (`FOO="   "`) variable must not clobber a declared default.
+
+type EnvSource = Readonly<Record<string, string | undefined>>;
+
+type ConfigKeyRegistry = {
+  getAllConfigKeys: () => ReadonlyMap<string, ConfigKeyDefinition>;
+  getConfigKey: (key: string) => ConfigKeyDefinition | undefined;
+};
+
+function coerceEnvValue(
+  qualifiedKey: string,
+  envName: string,
+  type: ConfigKeyDefinition["type"],
+  raw: string,
+): string | number | boolean {
+  if (type === "number") {
+    const n = Number(raw.trim());
+    if (!Number.isFinite(n)) {
+      throw new Error(
+        `ENV config bridge: "${envName}" → "${qualifiedKey}" expects a number, got "${raw}".`,
+      );
+    }
+    return n;
+  }
+  if (type === "boolean") {
+    const v = raw.trim().toLowerCase();
+    if (v === "true" || v === "1") return true;
+    if (v === "false" || v === "0") return false;
+    throw new Error(
+      `ENV config bridge: "${envName}" → "${qualifiedKey}" expects a boolean (true/false/1/0), got "${raw}".`,
+    );
+  }
+  // text | select — trimmed so e.g. `THEME=" dark"` resolves to a real option;
+  // select-option membership is validated by validateAppOverrides.
+  return raw.trim();
+}
+
+export function buildEnvConfigOverrides(
+  registry: ConfigKeyRegistry,
+  env: EnvSource,
+): AppConfigOverrides {
+  const record: Record<string, string | number | boolean> = {};
+  for (const [qualifiedKey, keyDef] of registry.getAllConfigKeys()) {
+    const envName = keyDef.env;
+    if (!envName) continue;
+    const raw = env[envName];
+    if (raw === undefined || raw.trim() === "") continue;
+    record[qualifiedKey] = coerceEnvValue(qualifiedKey, envName, keyDef.type, raw);
+  }
+  return validateAppOverrides(registry, record);
+}