bazis 0.96.1

package/core/kernel/config/Configuration.ts

@@ -0,0 +1,110 @@
+import { ConfigKeyMissingError, KernelError } from "../errors";
+import type { ConfigSource } from "../types";
+import { Secret } from "./Secret";
+
+/**
+ * Immutable merged configuration: a flat map of dot-separated keys
+ * ("db.host") to string values. Built once from layered sources
+ * (defaults -> file -> env -> CLI), later sources override earlier ones.
+ */
+export class Configuration {
+  private readonly values: ReadonlyMap<string, string>;
+  private readonly origins: ReadonlyMap<string, { readonly source: string; readonly priority: number }>;
+
+  public constructor(values: ReadonlyMap<string, string>, origins: ReadonlyMap<string, { readonly source: string; readonly priority: number }> = new Map()) {
+    this.values = new Map([...values].map(([key, value]) => [key.toLowerCase(), value]));
+    this.origins = new Map([...origins].map(([key, value]) => [key.toLowerCase(), Object.freeze({ ...value })]));
+  }
+
+  public static empty(): Configuration {
+    return new Configuration(new Map());
+  }
+
+  public has(key: string): boolean {
+    return this.values.has(key.toLowerCase());
+  }
+
+  public get(key: string): string | undefined {
+    return this.values.get(key.toLowerCase());
+  }
+
+  public origin(key: string): { readonly source: string; readonly priority: number } {
+    return this.origins.get(key.toLowerCase()) ?? { source: "configuration", priority: 0 };
+  }
+
+  public getOrDefault(key: string, defaultValue: string): string {
+    return this.get(key) ?? defaultValue;
+  }
+
+  public require(key: string): string {
+    const value = this.get(key);
+    if (value === undefined) {
+      throw new ConfigKeyMissingError(key);
+    }
+    return value;
+  }
+
+  public getNumber(key: string): number | undefined {
+    const raw = this.get(key);
+    if (raw === undefined) {
+      return undefined;
+    }
+    const parsed = Number(raw);
+    if (!raw.trim() || !Number.isFinite(parsed)) {
+      throw new KernelError(`Configuration key "${key}" must be a finite number.`);
+    }
+    return parsed;
+  }
+
+  public requireNumber(key: string): number {
+    const value = this.getNumber(key);
+    if (value === undefined) {
+      throw new ConfigKeyMissingError(key);
+    }
+    return value;
+  }
+
+  public getBoolean(key: string): boolean | undefined {
+    const raw = this.get(key);
+    if (raw === undefined) {
+      return undefined;
+    }
+    const normalized = raw.toLowerCase();
+    if (normalized === "true" || normalized === "1") {
+      return true;
+    }
+    if (normalized === "false" || normalized === "0") {
+      return false;
+    }
+    throw new KernelError(`Configuration key "${key}" is not a boolean.`);
+  }
+
+  /** Wraps the value into a Secret so it cannot leak through logs. */
+  public getSecret(key: string): Secret | undefined {
+    const raw = this.get(key);
+    return raw === undefined ? undefined : new Secret(raw);
+  }
+
+  public requireSecret(key: string): Secret {
+    return new Secret(this.require(key));
+  }
+
+  public keys(): readonly string[] {
+    return [...this.values.keys()];
+  }
+}
+
+/** Merges sources in order: later sources win. */
+export async function loadConfiguration(sources: readonly ConfigSource[]): Promise<Configuration> {
+  const merged = new Map<string, string>();
+  const origins = new Map<string, { source: string; priority: number }>();
+  for (let index = 0; index < sources.length; index += 1) {
+    const source = sources[index] as ConfigSource;
+    const values = await source.load();
+    for (const [key, value] of Object.entries(values)) {
+      merged.set(key.toLowerCase(), value);
+      origins.set(key.toLowerCase(), { source: source.description ?? `source[${index}]`, priority: index });
+    }
+  }
+  return new Configuration(merged, origins);
+}

package/core/kernel/config/README.md

@@ -0,0 +1,62 @@
+# Configuration contracts
+
+Date: 2026-09-14. Contracts per MODULE_ARCHITECTURE §5.4.
+A component of the existing kernel; no new architectural module is created.
+
+Isolation of the views of each kernel, its services and connectors is implemented and
+checked: [report](https://github.com/asus97178/osnova/blob/33a4513a56abb43a1694e7a6e56373187b928a70/docs/audits/kernel-config-isolation-2026-09-14.md).
+
+`defineConfig` returns an immutable `ConfigDefinition<T>` declaration.
+The `default`, `development`, `test`, `production` fields are kept. Additions:
+
+| Input | Type / default | Rule |
+| --- | --- | --- |
+| `env` | Optional map of local key → name or array of names | Explicit extra BAZIS_* names; the canonical name is accepted too; different values in one source are an error |
+| `validate` | Optional map of key → `(value) => string \| undefined` | Synchronous domain check; a string is a safe error description without the value |
+| `configEnum(values, defaultValue)` | A non-empty readonly array of strings or numbers, the default taken from it | Restricts both the TS type and the runtime env; needed for fields with a literal union |
+| `resolve(environment?, configuration?)` | Environment; an immutable Configuration | Creates an independent ConfigView; without sources it snapshots BAZIS_* at call time |
+| `token` | InjectionToken<ConfigView<T>> | The kernel registers the view in the existing DI for every declaration from Module.config |
+| `ConfigRegistry.get(definition)` | A declaration from the current kernel's graph | Returns the one view of this kernel; an unknown declaration is an error |
+| `AppConfig.resolve(environment?, configuration?)` | Optional factory of a user declaration | A composite config builds its own independent view from the kernel snapshot; all its consumers use the same result |
+| `ConfigView.inspect()` | No arguments | Key, type, allowed env names, source and a safe value; a Secret is always `***` |
+
+Default → environment section → sources snapshot. Kernel sources are merged in
+registration order; if no list is given, env and then CLI args are used.
+Flat Configuration key names are case-insensitive. A later source also wins
+between the canonical name and an explicit env alias.
+Numbers are finite; an empty string never becomes zero; a Secret does not allow an
+empty or whitespace value. TypeScript forbids unsupported object types.
+
+A declaration stores no chosen environment, values or cache. `get/has/ensureValid`
+stay for standalone reading of the process env, but `ensureValid` no longer
+switches later reads. Host code gets `resolve`, a service injects
+`definition.token`, a connector gets `ConfigRegistry` as the create argument.
+All built-in connectors use this argument; a custom connector reads
+`configs?.get(config) ?? config`. A direct global get inside a service does not
+read the settings of its kernel.
+
+A custom configuration with nested values, for example a set of session protection
+keys, implements `resolve(environment, configuration)` if the values depend on the
+run. The factory returns an immutable `AppConfig` and does not change the
+declaration. Older objects with only `ensureValid` stay compatible as
+validators/ready values; their author is responsible for having no mutable shared
+run state. The session protection adapter also reads the registry view.
+
+The kernel collects the errors of all declarations before creating DI clients. An
+error in one kernel does not change the other views. The historical activeStand
+guard is removed only together with the regressions for two kernels, sources,
+secrets and connectors.
+
+Health: `HealthService.check(options?)` / `Kernel.health(options?)` accept
+`timeoutMs` (the whole report, default 5000), `checkTimeoutMs` (one check, default
+1000), `concurrency` (default 4) and an optional `signal`. Numbers are positive
+integers, timers up to 2147483647 ms, concurrency up to 1024. Results come in
+registration order. `HealthCheck.check(signal?)` gets the cancellation; a timeout
+or an exception gives unhealthy. Expired checks that have not started are not run.
+This bounds the wait; a custom check must honor the signal to stop its own work.
+Diagnostics go through the existing redaction.
+Concurrent reports of one HealthService share one operation per singleton
+check instance. Cancelling one report does not abort the others.
+When all waiters finish, the operation's signal is aborted. If the operation keeps
+hanging, repeated reports give unhealthy until it actually finishes, without starting
+duplicates. The next call after it finishes runs a fresh check.

package/core/kernel/config/Secret.ts

@@ -0,0 +1,29 @@
+const REDACTED = "***";
+
+/**
+ * A secret value that never leaks through logs: toString/toJSON/inspect all
+ * print "***". The raw value is available only via an explicit `reveal()`.
+ */
+export class Secret {
+  readonly #value: string;
+
+  public constructor(value: string) {
+    this.#value = value;
+  }
+
+  public reveal(): string {
+    return this.#value;
+  }
+
+  public toString(): string {
+    return REDACTED;
+  }
+
+  public toJSON(): string {
+    return REDACTED;
+  }
+
+  public [Symbol.for("nodejs.util.inspect.custom")](): string {
+    return `Secret(${REDACTED})`;
+  }
+}

package/core/kernel/config/addConfigOptions.ts

@@ -0,0 +1,63 @@
+import type { InjectionToken, Options, ProviderDefinition, ServiceCollection, ServiceResolver } from "../../di";
+import { DI, OPTIONS_STARTUP_VALIDATOR, OptionsValidationError } from "../../di";
+import { ConfigKeyMissingError } from "../errors";
+import { Configuration } from "./Configuration";
+
+export interface ConfigOptionsBinding<T> {
+  /** Maps the merged configuration to a typed options value. */
+  readonly bind: (config: Configuration) => T;
+  /** Returns a list of problems; empty list or `undefined` means valid. */
+  readonly validate?: (value: T) => readonly string[] | undefined;
+}
+
+/**
+ * Config-bound validated options (Symfony bundle configuration style):
+ * a module declares its own options next to itself, binding reads from the
+ * kernel `Configuration`, and the kernel fails fast on start with every
+ * config problem aggregated.
+ *
+ * Module usage: `providers: [...configOptions(SMTP_OPTIONS, { bind, validate })]`.
+ */
+export function configOptions<T>(
+  token: InjectionToken<Options<T>>,
+  binding: ConfigOptionsBinding<T>,
+): readonly ProviderDefinition[] {
+  const optionsDefinition = DI.singleton(
+    DI.factoryProvider(token, [Configuration] as const, (config): Options<T> => {
+      const name = token.description;
+      let value: T;
+      try {
+        value = binding.bind(config);
+      } catch (error) {
+        // Missing keys become validation issues, so the startup check can
+        // aggregate them with every other config problem.
+        if (error instanceof ConfigKeyMissingError) {
+          throw new OptionsValidationError([`${name}: ${error.message}`]);
+        }
+        throw error;
+      }
+      const issues = binding.validate?.(value) ?? [];
+      if (issues.length > 0) {
+        throw new OptionsValidationError(issues.map((issue) => `${name}: ${issue}`));
+      }
+      return { value };
+    }),
+  );
+
+  const validatorDefinition = DI.transient(
+    DI.factoryProviderWithResolver(OPTIONS_STARTUP_VALIDATOR, [], (resolver: ServiceResolver) => (): void => {
+      resolver.resolve(token);
+    }),
+  );
+
+  return [optionsDefinition, validatorDefinition];
+}
+
+/** Collection-style registration of the same config-bound options. */
+export function addConfigOptions<T>(
+  services: ServiceCollection,
+  token: InjectionToken<Options<T>>,
+  binding: ConfigOptionsBinding<T>,
+): void {
+  services.addMany(configOptions(token, binding));
+}

package/core/kernel/config/defineConfig.ts

@@ -0,0 +1,211 @@
+import { createToken, type InjectionToken } from "../../di";
+import { Environment } from "../Environment";
+import { KernelError } from "../errors";
+import { Configuration } from "./Configuration";
+import { Secret } from "./Secret";
+import { ENV_PREFIX } from "./sources";
+import { isSensitiveKey, redactSensitiveText } from "../../../library/redaction";
+
+type Stand = "development" | "test" | "production";
+type Primitive = string | number | boolean;
+export interface SecretSpec { readonly __secret: true; readonly default?: string }
+export function secret(value?: string): SecretSpec {
+  return Object.freeze(value === undefined ? { __secret: true } : { __secret: true, default: value });
+}
+export interface ConfigEnum<T extends string | number = string | number> {
+  readonly __enum: true;
+  readonly values: readonly T[];
+  readonly default: T;
+}
+export function configEnum<const V extends readonly [string | number, ...(string | number)[]]>(values: V, defaultValue: V[number]): ConfigEnum<V[number]> {
+  if (!values.length || !values.includes(defaultValue) || values.some(value => typeof value !== typeof defaultValue || (typeof value === "number" && !Number.isFinite(value)))) {
+    throw new KernelError("configEnum requires non-empty homogeneous finite values and a declared default.");
+  }
+  return Object.freeze({ __enum: true, values: Object.freeze([...values]), default: defaultValue });
+}
+type Cell = Primitive | SecretSpec | ConfigEnum;
+type Defaults = Record<string, Cell>;
+export type ConfigValueType = Primitive | Secret;
+export type ConfigShape = Record<string, ConfigValueType>;
+type Resolved<V> = V extends SecretSpec ? Secret : V extends ConfigEnum<infer E> ? E : V extends number ? number : V extends boolean ? boolean : string;
+type ResolveAll<D extends Defaults> = { [K in keyof D]: Resolved<D[K]> };
+type WidenCell<V> = V extends SecretSpec ? SecretSpec : V extends ConfigEnum<infer E> ? E : V extends number ? number : V extends boolean ? boolean : string;
+type CellFor<T> = [T] extends [Secret] ? SecretSpec : [T] extends [string] ? (string extends T ? string : ConfigEnum<T & string>) : [T] extends [number] ? (number extends T ? number : ConfigEnum<T & number>) : [T] extends [boolean] ? (boolean extends T ? boolean : never) : never;
+type Declaration<T extends object> = { [K in keyof T]: CellFor<T[K]> };
+type OverrideFor<T> = T extends Secret ? SecretSpec : T;
+interface Rules<T extends object> {
+  readonly env?: Partial<{ [K in keyof T]: string | readonly string[] }>;
+  readonly validate?: Partial<{ [K in keyof T]: (value: T[K]) => string | undefined }>;
+}
+export interface ConfigSchema<D extends Defaults> extends Rules<ResolveAll<D>> {
+  readonly default: D;
+  readonly development?: Partial<{ [K in keyof D]: WidenCell<D[K]> }>;
+  readonly test?: Partial<{ [K in keyof D]: WidenCell<D[K]> }>;
+  readonly production?: Partial<{ [K in keyof D]: WidenCell<D[K]> }>;
+}
+export interface SchemaFor<T extends object> extends Rules<T> {
+  readonly default: Declaration<T>;
+  readonly development?: Partial<{ [K in keyof T]: OverrideFor<T[K]> }>;
+  readonly test?: Partial<{ [K in keyof T]: OverrideFor<T[K]> }>;
+  readonly production?: Partial<{ [K in keyof T]: OverrideFor<T[K]> }>;
+}
+export interface ValidatableConfig {
+  ensureValid(environment?: Stand): void;
+  /** Derived declarations create a fresh view from this kernel's source snapshot. */
+  resolve?(environment?: Stand, configuration?: Configuration): ValidatableConfig;
+}
+export interface AppConfig<T extends object> extends ValidatableConfig {
+  get<K extends keyof T>(key: K): T[K];
+  has<K extends keyof T>(key: K): boolean;
+  resolve?(environment?: Stand, configuration?: Configuration): AppConfig<T>;
+}
+export interface ConfigInspection {
+  readonly key: string;
+  readonly type: "string" | "number" | "boolean" | "secret";
+  readonly env: readonly string[];
+  readonly source: string;
+  readonly value: Primitive;
+}
+export interface ConfigView<T extends object> extends AppConfig<T> {
+  readonly environment: Stand;
+  inspect(): readonly ConfigInspection[];
+}
+export interface ConfigDefinition<T extends object> extends AppConfig<T> {
+  readonly token: InjectionToken<ConfigView<T>>;
+  resolve(environment?: Stand, configuration?: Configuration): ConfigView<T>;
+}
+const definitions = new WeakSet<object>();
+export function isConfigDefinition(config: ValidatableConfig): config is ConfigDefinition<object> {
+  return definitions.has(config);
+}
+export function processConfiguration(): Configuration {
+  const values = new Map<string, string>();
+  const origins = new Map<string, { source: string; priority: number }>();
+  for (const [name, value] of Object.entries(process.env)) {
+    if (name.startsWith(ENV_PREFIX) && value !== undefined) {
+      const key = name.slice(ENV_PREFIX.length).toLowerCase().replaceAll("__", ".");
+      values.set(key, value);
+      origins.set(key, { source: "env(BAZIS_*)", priority: 0 });
+    }
+  }
+  return new Configuration(values, origins);
+}
+function isSecret(cell: Cell): cell is SecretSpec { return typeof cell === "object" && cell !== null && "__secret" in cell; }
+function isEnum(cell: Cell): cell is ConfigEnum { return typeof cell === "object" && cell !== null && "__enum" in cell; }
+function copyCell(cell: Cell): Cell {
+  if (isSecret(cell)) return secret(cell.default);
+  if (isEnum(cell)) return Object.freeze({ ...cell, values: Object.freeze([...cell.values]) });
+  if (["string", "number", "boolean"].includes(typeof cell)) return cell;
+  throw new KernelError("Configuration supports only primitive values, secret() and configEnum().");
+}
+function safeValue(key: string, value: ConfigValueType): Primitive {
+  if (value instanceof Secret || (typeof value === "string" && isSensitiveKey(key))) return "***";
+  if (typeof value !== "string") return value;
+  try {
+    const url = new URL(value);
+    if (url.username || url.password) { url.username = "***"; url.password = "***"; return redactSensitiveText(url.toString()); }
+  } catch { /* Most strings are not URLs. */ }
+  return redactSensitiveText(value);
+}
+export function defineConfig<const D extends Defaults>(schema: ConfigSchema<D>): ConfigDefinition<ResolveAll<D>>;
+export function defineConfig<const D extends Defaults>(prefix: string, schema: ConfigSchema<D>): ConfigDefinition<ResolveAll<D>>;
+export function defineConfig<T extends object>(schema: SchemaFor<T>): ConfigDefinition<T>;
+export function defineConfig<T extends object>(prefix: string, schema: SchemaFor<T>): ConfigDefinition<T>;
+export function defineConfig(prefixOrSchema: string | ConfigSchema<Defaults>, maybeSchema?: ConfigSchema<Defaults>): ConfigDefinition<ConfigShape> {
+  const prefix = typeof prefixOrSchema === "string" ? prefixOrSchema : "";
+  const input = typeof prefixOrSchema === "string" ? maybeSchema! : prefixOrSchema;
+  const schema = Object.freeze({
+    default: Object.freeze(Object.fromEntries(Object.entries(input.default).map(([key, value]) => [key, copyCell(value)]))),
+    ...Object.fromEntries((["development", "test", "production"] as const).map(stand => [stand, Object.freeze(Object.fromEntries(Object.entries(input[stand] ?? {}).map(([key, value]) => [key, copyCell(value as Cell)])))])),
+  }) as ConfigSchema<Defaults>;
+  const validators = { ...input.validate };
+  const keys = Object.keys(schema.default);
+  const fullKey = (key: string) => prefix ? `${prefix}.${key}` : key;
+  const names = new Map<string, readonly string[]>();
+  const claimed = new Set<string>();
+  for (const key of keys) {
+    const alias = input.env?.[key];
+    const env = [...new Set([`${ENV_PREFIX}${fullKey(key).replaceAll(".", "__").toUpperCase()}`, ...(typeof alias === "string" ? [alias] : alias ?? [])])];
+    for (const name of env) {
+      if (!name.startsWith(ENV_PREFIX) || name.length === ENV_PREFIX.length || !/^[A-Z0-9_-]+$/.test(name) || claimed.has(name)) throw new KernelError(`Invalid or duplicate configuration environment name: ${name}.`);
+      claimed.add(name);
+    }
+    names.set(key, Object.freeze(env));
+  }
+  for (const stand of ["development", "test", "production"] as const) {
+    for (const key of Object.keys(schema[stand] ?? {})) if (!keys.includes(key)) throw new KernelError(`Unknown configuration key: ${fullKey(key)}.`);
+  }
+  const resolve = (environment: Stand = Environment.fromProcess().name, configuration = processConfiguration()): ConfigView<ConfigShape> => {
+    if (!["development", "test", "production"].includes(environment)) throw new KernelError("Unknown configuration environment.");
+    const values = new Map<string, ConfigValueType>();
+    const inspection: ConfigInspection[] = [];
+    const issues: string[] = [];
+    for (const key of keys) {
+      const base = schema.default[key]!;
+      const override = schema[environment]?.[key];
+      const cell = override ?? base;
+      const type = isSecret(base) ? "secret" : isEnum(base) ? typeof base.default : typeof base;
+      const candidates: { raw: string; source: string; priority: number }[] = [];
+      for (const name of names.get(key)!) {
+        const sourceKey = name.slice(ENV_PREFIX.length).toLowerCase().replaceAll("__", ".");
+        const raw = configuration.get(sourceKey);
+        if (raw === undefined) continue;
+        const origin = configuration.origin(sourceKey);
+        candidates.push({ raw, ...origin });
+      }
+      const priority = Math.max(...candidates.map(candidate => candidate.priority));
+      const winners = candidates.filter(candidate => candidate.priority === priority);
+      const selected = winners[0];
+      if (winners.some(candidate => candidate.raw !== selected?.raw)) issues.push(`${fullKey(key)}: conflicting environment aliases`);
+      const raw = selected?.raw ?? (isSecret(cell) || isEnum(cell) ? cell.default : cell);
+      let value: ConfigValueType | undefined;
+      if (type === "secret") {
+        if (typeof raw !== "string" || !raw.trim()) issues.push(`${fullKey(key)}: required non-empty secret is not set (${names.get(key)!.join(", ")})`);
+        else value = new Secret(raw);
+      } else if (type === "number") {
+        const parsed = Number(raw);
+        if (raw === undefined || (typeof raw === "string" && !raw.trim()) || !Number.isFinite(parsed)) issues.push(`${fullKey(key)}: expected a finite number`);
+        else value = parsed;
+      } else if (type === "boolean") {
+        const normalized = String(raw).toLowerCase();
+        if (normalized === "true" || normalized === "1") value = true;
+        else if (normalized === "false" || normalized === "0") value = false;
+        else issues.push(`${fullKey(key)}: expected a boolean`);
+      } else if (typeof raw === "string") value = raw;
+      else issues.push(`${fullKey(key)}: expected a string`);
+      if (value === undefined) continue;
+      if (isEnum(base) && !base.values.includes(value as string | number)) issues.push(`${fullKey(key)}: value is not one of the declared enum values`);
+      try {
+        const issue = validators[key]?.(value);
+        if (issue) issues.push(`${fullKey(key)}: ${issue}`);
+      } catch { issues.push(`${fullKey(key)}: validator failed`); }
+      values.set(key, value);
+      inspection.push(Object.freeze({ key: fullKey(key), type: type as ConfigInspection["type"], env: names.get(key)!, source: selected?.source ?? (override === undefined ? "default" : environment), value: safeValue(fullKey(key), value) }));
+    }
+    if (issues.length) {
+      let message = issues.join("; ");
+      for (const [key, value] of values) {
+        const sensitive = value instanceof Secret ? value.reveal() : typeof value === "string" && isSensitiveKey(key) ? value : undefined;
+        if (sensitive) message = message.replaceAll(sensitive, "***");
+      }
+      throw new KernelError(`Invalid configuration (environment "${environment}"): ${message}.`);
+    }
+    const rows = Object.freeze(inspection);
+    return Object.freeze({
+      environment,
+      get: <K extends keyof ConfigShape>(key: K): ConfigShape[K] => values.get(String(key)) as ConfigShape[K],
+      has: <K extends keyof ConfigShape>(key: K) => values.has(String(key)),
+      ensureValid(stand?: Stand) { if (stand !== undefined && stand !== environment) throw new KernelError("A resolved configuration view cannot change environment."); },
+      inspect: () => rows,
+    });
+  };
+  const definition: ConfigDefinition<ConfigShape> = Object.freeze({
+    token: Object.freeze(createToken<ConfigView<ConfigShape>>(`Config:${prefix || "default"}`)),
+    resolve,
+    get: <K extends keyof ConfigShape>(key: K): ConfigShape[K] => resolve().get(key),
+    has: <K extends keyof ConfigShape>(key: K) => resolve().has(key),
+    ensureValid(environment?: Stand) { resolve(environment); },
+  });
+  definitions.add(definition);
+  return definition;
+}

package/core/kernel/config/sources.ts

@@ -0,0 +1,123 @@
+import { KernelError } from "../errors";
+import type { ConfigSource } from "../types";
+
+type ConfigTree = { [key: string]: ConfigTreeValue };
+type ConfigTreeValue = string | number | boolean | null | ConfigTreeValue[] | ConfigTree;
+
+/** In-memory defaults. Nested objects are flattened into dot keys. */
+/** Prefix of framework environment variables: `BAZIS_DB__HOST` -> `db.host`. */
+export const ENV_PREFIX = "BAZIS_";
+
+export function memorySource(values: ConfigTree, description = "memory"): ConfigSource {
+  return {
+    description,
+    load: () => flatten(values),
+  };
+}
+
+/**
+ * Environment variables. `BAZIS_DB__HOST=x` -> `db.host = "x"`:
+ * the prefix is stripped, `__` becomes `.`, keys are lowercased.
+ */
+export function envSource(options?: {
+  readonly prefix?: string;
+  /** Override for tests; defaults to process.env. */
+  readonly variables?: Record<string, string | undefined>;
+}): ConfigSource {
+  const prefix = options?.prefix ?? ENV_PREFIX;
+  return {
+    description: `env(${prefix}*)`,
+    load: () => {
+      const variables = options?.variables ?? process.env;
+      const result: Record<string, string> = {};
+      for (const [name, value] of Object.entries(variables)) {
+        if (value === undefined || !name.startsWith(prefix)) {
+          continue;
+        }
+        const key = name.slice(prefix.length).toLowerCase().replaceAll("__", ".");
+        if (key.length > 0) {
+          result[key] = value;
+        }
+      }
+      return result;
+    },
+  };
+}
+
+/** CLI arguments in the form `--db.host=localhost`. */
+export function argsSource(argv: readonly string[] = Bun.argv.slice(2)): ConfigSource {
+  return {
+    description: "args",
+    load: () => {
+      const result: Record<string, string> = {};
+      for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index] as string;
+        if (!arg.startsWith("--")) {
+          continue;
+        }
+        const separator = arg.indexOf("=");
+        if (separator <= 2) {
+          continue;
+        }
+        result[arg.slice(2, separator)] = arg.slice(separator + 1);
+      }
+      return result;
+    },
+  };
+}
+
+/**
+ * JSON config file read at runtime via Bun.file — the file lives next to the
+ * compiled binary, not inside it. Nested objects are flattened into dot keys.
+ */
+export function jsonFileSource(path: string, options?: { readonly optional?: boolean }): ConfigSource {
+  return {
+    description: `json(${path})`,
+    load: async () => {
+      const file = Bun.file(path);
+      if (!(await file.exists())) {
+        if (options?.optional === true) {
+          return {};
+        }
+        throw new KernelError(`Configuration file not found: "${path}".`);
+      }
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(await file.text());
+      } catch {
+        // Parser messages may quote the input, including credentials.
+        throw new KernelError(`Configuration file "${path}" is not valid JSON.`);
+      }
+      if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new KernelError(`Configuration file "${path}" must contain a JSON object at the top level.`);
+      }
+      return flatten(parsed as ConfigTree);
+    },
+  };
+}
+
+function flatten(tree: ConfigTree, prefix = "", into: Record<string, string> = {}): Record<string, string> {
+  for (const [key, value] of Object.entries(tree)) {
+    const fullKey = prefix.length > 0 ? `${prefix}.${key}` : key;
+    if (value === null) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      for (let index = 0; index < value.length; index += 1) {
+        const item = value[index];
+        if (item !== null && typeof item === "object" && !Array.isArray(item)) {
+          flatten(item, `${fullKey}.${index}`, into);
+        } else if (item !== null && item !== undefined) {
+          into[`${fullKey}.${index}`] = String(item);
+        }
+      }
+      continue;
+    }
+    if (typeof value === "object") {
+      flatten(value, fullKey, into);
+      continue;
+    }
+    into[fullKey] = String(value);
+  }
+  return into;
+}

package/core/kernel/correlation/requestContext.ts

@@ -0,0 +1,57 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/** HTTP header used for inbound/outbound correlation IDs. */
+export const REQUEST_ID_HEADER = "x-request-id";
+
+/** W3C Trace Context header propagated on outbound HTTP calls when present. */
+export const TRACEPARENT_HEADER = "traceparent";
+
+/** Key in {@link HttpContext.state} for the active request ID. */
+export const REQUEST_ID_STATE_KEY = "bazis.requestId";
+
+/** Key in {@link HttpContext.state} for inbound W3C traceparent. */
+export const TRACEPARENT_STATE_KEY = "bazis.traceparent";
+
+export interface RequestLogContext {
+  readonly requestId: string;
+  readonly traceparent?: string;
+}
+
+const storage = new AsyncLocalStorage<RequestLogContext>();
+
+/** Returns the correlation ID for the current async context, if any. */
+export function getRequestId(): string | undefined {
+  return storage.getStore()?.requestId;
+}
+
+/** Returns the active W3C traceparent value, if any. */
+export function getTraceparent(): string | undefined {
+  return storage.getStore()?.traceparent;
+}
+
+/** Headers to attach to outbound HTTP requests from the current async context. */
+export function getOutboundCorrelationHeaders(): Readonly<Record<string, string>> {
+  const headers: Record<string, string> = {};
+  const requestId = getRequestId();
+  if (requestId !== undefined) {
+    headers[REQUEST_ID_HEADER] = requestId;
+  }
+  const traceparent = getTraceparent();
+  if (traceparent !== undefined) {
+    headers[TRACEPARENT_HEADER] = traceparent;
+  }
+  return headers;
+}
+
+/** Runs `fn` with the given request context bound to the async local store. */
+export function runWithRequestContext<T>(context: RequestLogContext, fn: () => T): T {
+  return storage.run(context, fn);
+}
+
+/** Runs async `fn` with the given request context bound to the async local store. */
+export async function runWithRequestContextAsync<T>(
+  context: RequestLogContext,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return storage.run(context, fn);
+}

package/core/kernel/errors/ConfigKeyMissingError.ts

@@ -0,0 +1,7 @@
+import { KernelError } from "./KernelError";
+
+export class ConfigKeyMissingError extends KernelError {
+  public constructor(public readonly key: string) {
+    super(`Required configuration key "${key}" is missing.`);
+  }
+}

package/core/kernel/errors/KernelError.ts

@@ -0,0 +1,7 @@
+/** Base class for all kernel errors. */
+export class KernelError extends Error {
+  public constructor(message: string) {
+    super(message);
+    this.name = new.target.name;
+  }
+}