@untangle-code/config 0.0.0-stage → 0.1.1

package/src/load.ts

@@ -0,0 +1,346 @@
+/**
+ * Top-level configuration loading: discovery + six-level layering (spec.md
+ * §4.1) + path resolution (spec.md §4.3) + validation (spec.md §4.8) +
+ * canonical hashing and embedding profile derivation (architecture.md §6.3).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+import { buildWorkspaceId } from "@untangle-code/domain";
+import { parse as parseToml } from "smol-toml";
+
+import { PRODUCT_DEFAULT_CONFIG } from "./defaults.js";
+import { discoverConfigFiles } from "./discovery.js";
+import { buildEnvConfigLayer } from "./env.js";
+import { computeConfigHash, deriveEmbeddingProfileId } from "./hash.js";
+import { mergeConfigLayers } from "./merge.js";
+import { migrateConfig } from "./migrations.js";
+import { resolveConfigPath } from "./paths.js";
+import type { RawConfigLayer, EffectiveUntangleConfigV1 } from "./types.js";
+import { resolveUserConfigPath } from "./user-config.js";
+import type { ConfigIssue } from "./validate.js";
+import { validateEffectiveConfig } from "./validate.js";
+
+export interface LoadConfigOptions {
+  /** Directory to start upward config-file discovery from. Defaults to `process.cwd()`. */
+  cwd?: string;
+  /** Highest-priority layer (spec.md §4.1 layer 1): explicit API/CLI arguments. */
+  explicit?: RawConfigLayer;
+  env?: NodeJS.ProcessEnv;
+  platform?: NodeJS.Platform;
+}
+
+export interface ConfigSources {
+  userConfigPath: string | undefined;
+  projectConfigPath: string | undefined;
+  /**
+   * `untangle.toml` (layer 4b) — the file `untangle init` writes. Reported
+   * separately so a diagnostic command can name the file the user actually
+   * has instead of the one it expected (WP-222).
+   */
+  tomlConfigPath: string | undefined;
+  localConfigPath: string | undefined;
+  explicitProvided: boolean;
+  /** `UNTANGLE_*` variables from `ENV_MAPPING` that were actually set. */
+  envVarsApplied: string[];
+  /**
+   * Fallback directory shown for diagnostics only: `.untangle.json`'s
+   * directory, else `untangle.toml`'s, else `.untangle.local.json`'s, else
+   * `cwd`. It is NOT
+   * necessarily what `repositories`/`contextArtifacts` paths were resolved
+   * against — each of those resolves against the directory of whichever
+   * layer actually defined it (spec.md §4.3; see `loadConfig`'s
+   * `originBaseDirFor`), which may be the OS user config directory or `cwd`
+   * (env/explicit layers) instead.
+   */
+  configBaseDir: string;
+  /** Logical project root for `.untangle/config.json`; legacy layouts keep their existing base. */
+  projectRoot?: string;
+}
+
+export interface LoadConfigResult {
+  effectiveConfig: EffectiveUntangleConfigV1;
+  warnings: ConfigIssue[];
+  errors: ConfigIssue[];
+  sources: ConfigSources;
+  /** Canonical effective-config hash; Qdrant excludes additive storage fields for legacy identity. */
+  configHash: string;
+  /** `buildWorkspaceId({ explicitId: effectiveConfig.workspaceId, configHash })` (spec.md §5.1). */
+  workspaceId: string;
+  /** `buildEmbeddingProfileId` over the derived profile (spec.md §5.7). */
+  embeddingProfileId: string;
+}
+
+interface FileLayerOutcome {
+  layer: RawConfigLayer;
+  error: ConfigIssue | undefined;
+}
+
+function readJsonConfigFile(path: string): FileLayerOutcome {
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (error) {
+    return {
+      layer: {},
+      error: {
+        code: "CONFIG_INVALID",
+        message: `failed to read config file "${path}": ${String(error)}`,
+        path,
+      },
+    };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    return {
+      layer: {},
+      error: {
+        code: "CONFIG_INVALID",
+        message: `"${path}" is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+        path,
+      },
+    };
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return {
+      layer: {},
+      error: { code: "CONFIG_INVALID", message: `"${path}" must contain a JSON object`, path },
+    };
+  }
+  const migrated = migrateConfig(parsed as Record<string, unknown>);
+  return { layer: migrated.config as RawConfigLayer, error: undefined };
+}
+
+/**
+ * Reads `untangle.toml` into the same raw layer shape a JSON config produces.
+ *
+ * The TOML file `untangle init` writes carries the SAME keys as
+ * `.untangle.json` — `schemaVersion`, `repositories`, `qdrant`, `embeddings`
+ * and so on — so it needs no separate schema, only a separate parser. It
+ * runs through `migrateConfig` and the ordinary validation like every other
+ * layer; a typo in it is reported the same way, in the same list, against
+ * the same paths.
+ */
+function readTomlConfigFile(path: string): FileLayerOutcome {
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (error) {
+    return {
+      layer: {},
+      error: {
+        code: "CONFIG_INVALID",
+        message: `failed to read config file "${path}": ${String(error)}`,
+        path,
+      },
+    };
+  }
+  let parsed: unknown;
+  try {
+    parsed = parseToml(text);
+  } catch (error) {
+    return {
+      layer: {},
+      error: {
+        code: "CONFIG_INVALID",
+        message: `"${path}" is not valid TOML: ${error instanceof Error ? error.message : String(error)}`,
+        path,
+      },
+    };
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return {
+      layer: {},
+      error: { code: "CONFIG_INVALID", message: `"${path}" must contain a TOML table`, path },
+    };
+  }
+  const migrated = migrateConfig(parsed as Record<string, unknown>);
+  return { layer: migrated.config as RawConfigLayer, error: undefined };
+}
+
+/**
+ * Loads and resolves the effective Untangle configuration through all six
+ * layers of spec.md §4.1: explicit args > env (`UNTANGLE_*`) >
+ * `.untangle.local.json` > `.untangle.json` > OS user config > product
+ * defaults. Never throws for validation problems — see {@link ConfigIssue}
+ * and `validate.ts`'s `assertConfigValid` for the "MUST abort" behavior
+ * spec.md §4.8 requires from a caller.
+ */
+export function loadConfig(options: LoadConfigOptions = {}): LoadConfigResult {
+  const cwd = options.cwd ?? process.cwd();
+  const env = options.env ?? process.env;
+  const platform = options.platform ?? process.platform;
+
+  const { projectConfigPath, tomlConfigPath, localConfigPath, projectRoot } =
+    discoverConfigFiles(cwd);
+  const userConfigPath = resolveUserConfigPath(env, platform);
+
+  const errors: ConfigIssue[] = [];
+
+  const userLayerOutcome: FileLayerOutcome = userConfigPath
+    ? readJsonConfigFile(userConfigPath)
+    : { layer: {}, error: undefined };
+  const projectLayerOutcome: FileLayerOutcome = projectConfigPath
+    ? readJsonConfigFile(projectConfigPath)
+    : { layer: {}, error: undefined };
+  const tomlLayerOutcome: FileLayerOutcome = tomlConfigPath
+    ? readTomlConfigFile(tomlConfigPath)
+    : { layer: {}, error: undefined };
+  const localLayerOutcome: FileLayerOutcome = localConfigPath
+    ? readJsonConfigFile(localConfigPath)
+    : { layer: {}, error: undefined };
+  for (const outcome of [
+    userLayerOutcome,
+    tomlLayerOutcome,
+    projectLayerOutcome,
+    localLayerOutcome,
+  ]) {
+    if (outcome.error) {
+      errors.push(outcome.error);
+    }
+  }
+
+  const envLayerResult = buildEnvConfigLayer(env);
+  for (const parseError of envLayerResult.parseErrors) {
+    errors.push({
+      code: "CONFIG_INVALID",
+      message: `environment variable ${parseError.env}: ${parseError.message}`,
+      path: parseError.env,
+    });
+  }
+
+  const explicitLayer: RawConfigLayer = options.explicit ?? {};
+
+  // Each layer's OWN directory (spec.md §4.3: a path resolves relative to
+  // the config file that declared it). Layers with no backing file (product
+  // defaults, the env layer, explicit args) have no directory of their own,
+  // so they fall back to `cwd` — the directory the caller is running from.
+  const namedLayers: readonly { layer: RawConfigLayer; baseDir: string }[] = [
+    { layer: PRODUCT_DEFAULT_CONFIG, baseDir: cwd },
+    { layer: userLayerOutcome.layer, baseDir: userConfigPath ? dirname(userConfigPath) : cwd },
+    // Layer 4b, directly beneath `.untangle.json`: `untangle.toml`. Where
+    // both exist the JSON file wins — and `warnings` says so out loud, so a
+    // user never wonders why an edit had no effect (WP-222).
+    { layer: tomlLayerOutcome.layer, baseDir: tomlConfigPath ? dirname(tomlConfigPath) : cwd },
+    {
+      layer: projectLayerOutcome.layer,
+      baseDir: projectConfigPath ? dirname(projectConfigPath) : cwd,
+    },
+    { layer: localLayerOutcome.layer, baseDir: localConfigPath ? dirname(localConfigPath) : cwd },
+    { layer: envLayerResult.layer, baseDir: cwd },
+    { layer: explicitLayer, baseDir: cwd },
+  ];
+
+  // Preserve existing Qdrant projects without letting the product-default
+  // qdrant section choose a backend for new projects. This compatibility
+  // default sits below every user layer: an explicit storage.backend at any
+  // priority overrides it, while storage.path alone never migrates an index.
+  const configuredLayers = namedLayers.slice(1).map((named) => named.layer);
+  const legacyStorageDefault: RawConfigLayer = configuredLayers.some(
+    (layer) => layer.qdrant !== undefined,
+  )
+    ? { storage: { backend: "qdrant" } }
+    : {};
+  const merged = mergeConfigLayers<Record<string, unknown>>([
+    PRODUCT_DEFAULT_CONFIG,
+    legacyStorageDefault,
+    ...configuredLayers,
+  ]);
+
+  const configBaseDir = projectConfigPath
+    ? dirname(projectConfigPath)
+    : tomlConfigPath
+      ? dirname(tomlConfigPath)
+      : localConfigPath
+        ? dirname(localConfigPath)
+        : cwd;
+
+  /**
+   * `mergeConfigLayers` REPLACES arrays wholesale rather than concatenating
+   * them (merge.ts) — so the final `repositories`/`contextArtifacts` array
+   * in `merged` originates entirely from ONE layer: the highest-priority
+   * layer that defined it. Its entries' `path` fields MUST resolve against
+   * THAT layer's own directory (spec.md §4.3), not a single global
+   * `configBaseDir` computed after the merge — otherwise a repository
+   * defined in the OS user config (or via an env/explicit layer) silently
+   * loses its origin and resolves against the wrong directory. Walking
+   * `namedLayers` highest-priority-first and taking the first one that set
+   * `key` recovers exactly the layer the merge itself used.
+   */
+  function originBaseDirFor(key: "repositories" | "contextArtifacts"): string {
+    for (let i = namedLayers.length - 1; i >= 0; i -= 1) {
+      const candidate = namedLayers[i];
+      if (candidate && Array.isArray((candidate.layer as Record<string, unknown>)[key])) {
+        return candidate.baseDir;
+      }
+    }
+    return cwd;
+  }
+
+  if (Array.isArray(merged["repositories"])) {
+    const baseDir = originBaseDirFor("repositories");
+    merged["repositories"] = (merged["repositories"] as { path: string }[]).map((repo) => ({
+      ...repo,
+      path: resolveConfigPath(repo.path, baseDir),
+    }));
+  }
+  if (Array.isArray(merged["contextArtifacts"])) {
+    const baseDir = originBaseDirFor("contextArtifacts");
+    merged["contextArtifacts"] = (merged["contextArtifacts"] as { path: string }[]).map(
+      (artifact) => ({
+        ...artifact,
+        path: resolveConfigPath(artifact.path, baseDir),
+      }),
+    );
+  }
+
+  const { errors: validationErrors, warnings } = validateEffectiveConfig(merged);
+  errors.push(...validationErrors);
+
+  if (projectConfigPath !== undefined && tomlConfigPath !== undefined) {
+    warnings.push({
+      code: "CONFIG_DUPLICATE_PROJECT_FILE",
+      message:
+        `both "${projectConfigPath}" and "${tomlConfigPath}" exist; ` +
+        `"${projectConfigPath}" wins for every key it sets`,
+      path: "(project config)",
+    });
+  }
+
+  const effectiveConfig = merged as unknown as EffectiveUntangleConfigV1;
+  const configHash = computeConfigHash(effectiveConfig);
+  const workspaceId = buildWorkspaceId(
+    effectiveConfig.workspaceId === undefined
+      ? { configHash }
+      : { explicitId: effectiveConfig.workspaceId, configHash },
+  );
+  const embeddingProfileId = deriveEmbeddingProfileId(effectiveConfig);
+
+  return {
+    effectiveConfig,
+    warnings,
+    errors,
+    sources: {
+      userConfigPath,
+      projectConfigPath,
+      tomlConfigPath,
+      localConfigPath,
+      explicitProvided: options.explicit !== undefined,
+      envVarsApplied: Object.keys(env).filter(
+        (key) => key.startsWith("UNTANGLE_") && env[key] !== undefined,
+      ),
+      configBaseDir,
+      ...(projectRoot === undefined ? {} : { projectRoot }),
+    },
+    configHash,
+    workspaceId,
+    embeddingProfileId,
+  };
+}
+
+/** Re-exported for callers that only need to check whether a discovered path exists (rare; mostly test convenience). */
+export function configFileExists(path: string | undefined): boolean {
+  return path !== undefined && existsSync(path);
+}

package/src/merge.ts

@@ -0,0 +1,69 @@
+/**
+ * Deep merge for the layering pipeline (spec.md §4.1).
+ *
+ * Array semantics: arrays REPLACE, they never concatenate. A layer with
+ * `index.extraExtensions: [".proto"]` fully replaces a lower layer's array —
+ * two layers are never spliced together, because there is no reasonable way
+ * to know whether a higher layer meant to add to or reset a list (e.g.
+ * `exclude` globs), and silent concatenation would make higher-priority
+ * layers unable to shrink a list at all.
+ *
+ * Relevance-policy bindings are another deliberate replacement boundary:
+ * entries below `search.relevancePolicies.<profileId>` are calibrated,
+ * corpus-bound units. Merging a new workspace/collection with thresholds
+ * inherited from a lower layer would silently apply one corpus's policy to
+ * another corpus.
+ */
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Merges `override` onto `base`. Plain objects merge key by key (recursively);
+ * arrays, primitives, `null` and any non-plain object (e.g. would-be class
+ * instances) from `override` replace the corresponding value in `base`
+ * wholesale. `undefined` values in `override` are treated as "not set" and do
+ * not overwrite a present `base` value — this lets a layer omit a field
+ * without needing to know the value from lower layers.
+ */
+export function deepMergeConfig<T>(base: T, override: unknown): T {
+  return deepMergeConfigAtPath(base, override, []);
+}
+
+function isAtomicReplacementPath(path: readonly string[]): boolean {
+  return path.length === 3 && path[0] === "search" && path[1] === "relevancePolicies";
+}
+
+function deepMergeConfigAtPath<T>(base: T, override: unknown, path: readonly string[]): T {
+  if (override === undefined) {
+    return base;
+  }
+  if (isAtomicReplacementPath(path)) {
+    return override as T;
+  }
+  if (!isPlainObject(base) || !isPlainObject(override)) {
+    return override as T;
+  }
+  const result: Record<string, unknown> = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    if (value === undefined) {
+      continue;
+    }
+    const baseValue = (base as Record<string, unknown>)[key];
+    result[key] =
+      isPlainObject(baseValue) && isPlainObject(value)
+        ? deepMergeConfigAtPath(baseValue, value, [...path, key])
+        : value;
+  }
+  return result as T;
+}
+
+/**
+ * Merges layers left to right — later layers win — mirroring spec.md §4.1's
+ * priority order when called with `[productDefaults, userConfig, projectConfig,
+ * localConfig, envLayer, explicitArgs]` (lowest priority first).
+ */
+export function mergeConfigLayers<T>(layers: readonly unknown[]): T {
+  return layers.reduce<unknown>((acc, layer) => deepMergeConfig(acc, layer), {}) as T;
+}

package/src/migrations.ts

@@ -0,0 +1,64 @@
+/**
+ * Migration scaffold for future `schemaVersion` jumps (architecture.md §6.3:
+ * "Migration älterer Configversionen"). spec.md is at `schemaVersion: 1`
+ * today; this registry lets a future WP register a `1 -> 2` step (etc.)
+ * without `loadConfig` needing to change.
+ */
+import { CURRENT_SCHEMA_VERSION } from "./defaults.js";
+
+export interface MigrationStep {
+  fromVersion: number;
+  toVersion: number;
+  /** Pure transform: old raw config shape in, new raw config shape out. */
+  migrate: (raw: Record<string, unknown>) => Record<string, unknown>;
+}
+
+const registry = new Map<number, MigrationStep>();
+
+/** Registers a migration step keyed by its `fromVersion`. Overwrites a step already registered for that version. */
+export function registerMigration(step: MigrationStep): void {
+  registry.set(step.fromVersion, step);
+}
+
+/** Removes every registered migration step (test isolation). */
+export function clearMigrations(): void {
+  registry.clear();
+}
+
+export interface MigrationResult {
+  config: Record<string, unknown>;
+  finalVersion: number;
+  /** Versions the config was migrated through, e.g. `[1, 2]` for a single `1 -> 2` hop. */
+  appliedFrom: number[];
+}
+
+/**
+ * Applies registered migration steps in sequence starting from
+ * `raw.schemaVersion` (defaulting to `1` when absent) until
+ * `targetVersion` (default: {@link CURRENT_SCHEMA_VERSION}) is reached.
+ *
+ * A config already at `targetVersion` is returned unchanged — the identity
+ * migration — without requiring any step to be registered for it.
+ */
+export function migrateConfig(
+  raw: Record<string, unknown>,
+  targetVersion: number = CURRENT_SCHEMA_VERSION,
+): MigrationResult {
+  let current: Record<string, unknown> = raw;
+  let version = typeof raw["schemaVersion"] === "number" ? raw["schemaVersion"] : 1;
+  const appliedFrom: number[] = [version];
+
+  while (version < targetVersion) {
+    const step = registry.get(version);
+    if (step === undefined) {
+      throw new Error(
+        `no migration registered from schemaVersion ${version} towards ${targetVersion}`,
+      );
+    }
+    current = { ...step.migrate(current), schemaVersion: step.toVersion };
+    version = step.toVersion;
+    appliedFrom.push(version);
+  }
+
+  return { config: current, finalVersion: version, appliedFrom };
+}

package/src/parse.ts

@@ -0,0 +1,18 @@
+import { parse as parseToml } from "smol-toml";
+
+import { migrateConfig } from "./migrations.js";
+import type { RawConfigLayer } from "./types.js";
+
+/**
+ * Parses a config document without filesystem access, defaults or environment
+ * overrides. Syntax and non-object input errors propagate to the caller.
+ */
+export function parseConfigText(text: string, format: "json" | "toml"): RawConfigLayer {
+  const parsed: unknown = format === "json" ? JSON.parse(text) : parseToml(text);
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new TypeError(
+      `Configuration must contain a ${format === "json" ? "JSON object" : "TOML table"}.`,
+    );
+  }
+  return migrateConfig(parsed as Record<string, unknown>).config as RawConfigLayer;
+}

package/src/paths.ts

@@ -0,0 +1,42 @@
+/**
+ * Path resolution relative to the configuration file (spec.md §4.3:
+ * "Pfade MÜSSEN relativ zur Konfigurationsdatei oder absolut auflösbar
+ * sein."). Results are canonical: absolute, `/`-separated, no trailing slash,
+ * no `.`/`..` segments.
+ */
+import { isAbsolute, resolve, sep } from "node:path";
+
+/** Canonicalizes a resolved absolute filesystem path to forward slashes, no trailing slash. */
+function toCanonicalAbsolute(absolutePath: string): string {
+  const normalized = absolutePath.split(sep).join("/");
+  if (normalized.length > 1 && normalized.endsWith("/")) {
+    return normalized.slice(0, -1);
+  }
+  return normalized;
+}
+
+/**
+ * Resolves `candidatePath` against `configFileDir` (the directory containing
+ * the config file that declared it). An already-absolute `candidatePath` is
+ * returned canonicalized as-is (spec.md §4.3 allows absolute paths).
+ */
+export function resolveConfigPath(candidatePath: string, configFileDir: string): string {
+  const absolute = isAbsolute(candidatePath)
+    ? candidatePath
+    : resolve(configFileDir, candidatePath);
+  return toCanonicalAbsolute(absolute);
+}
+
+/**
+ * Resolves every `RepositoryConfig.path` in `repositories` relative to
+ * `configFileDir`, returning new objects (inputs are not mutated).
+ */
+export function resolveRepositoryPaths<T extends { path: string }>(
+  repositories: readonly T[],
+  configFileDir: string,
+): T[] {
+  return repositories.map((repo) => ({
+    ...repo,
+    path: resolveConfigPath(repo.path, configFileDir),
+  }));
+}

package/src/schema.ts

@@ -0,0 +1,23 @@
+/**
+ * JSON Schema export (architecture.md §6.3, §7.3; docs/BUILD_PLAN.md §3
+ * assigns the repo-level `schemas/` directory to this package's WP).
+ *
+ * NOTE (openIssues): the task that produced this package restricts writes to
+ * `packages/config/**`, so the authoritative file lives at
+ * `packages/config/schemas/config-v1.json`, not the (currently empty, WP-02
+ * owned per docs/BUILD_PLAN.md §4) repo-root `schemas/`. It still needs to be
+ * mirrored to `schemas/config-v1.json` by whoever is authorized to write
+ * there.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const schemaUrl = new URL("../schemas/config-v1.json", import.meta.url);
+
+/** Absolute filesystem path to the hand-authored JSON Schema (Draft 2020-12) for `UntangleConfigV1`. */
+export const CONFIG_SCHEMA_PATH: string = fileURLToPath(schemaUrl);
+
+/** The parsed JSON Schema object itself, read once at module load. */
+export const CONFIG_SCHEMA: Record<string, unknown> = JSON.parse(
+  readFileSync(schemaUrl, "utf8"),
+) as Record<string, unknown>;

package/src/secrets.ts

@@ -0,0 +1,78 @@
+/**
+ * Secret references and redaction (spec.md §4.4/§4.5 `apiKeyEnv`; §24
+ * "API-Keys DÜRFEN nicht in Status, Logs oder Crash Reports erscheinen";
+ * architecture.md §23.2: "Der Wert wird nie in Effective Config Dumps
+ * geschrieben.").
+ *
+ * The primary guarantee is structural: `QdrantConfig`/`EmbeddingConfig` only
+ * ever carry `apiKeyEnv` — the NAME of an environment variable — never a
+ * resolved secret value, so an `EffectiveUntangleConfigV1` cannot contain a
+ * secret by construction. `redactSecrets` is a defense-in-depth belt: it
+ * scrubs any resolved-secret-shaped field (e.g. code elsewhere mistakenly
+ * attaching a resolved key onto a config object for convenience) before that
+ * object is serialized, dumped, or logged.
+ */
+
+const REDACTED_PLACEHOLDER = "[REDACTED]";
+
+// Field name ends in one of these -> looks like a *resolved* secret value.
+const SECRET_VALUE_KEY_PATTERN = /(apikey|secret|password|token|credential)$/i;
+// ...unless it ends in "Env" (e.g. `apiKeyEnv`), which holds an env var NAME
+// and is exactly what spec.md §24 requires to stay visible for transparency.
+const ENV_REFERENCE_SUFFIX_PATTERN = /env$/i;
+
+function looksLikeResolvedSecretKey(key: string): boolean {
+  if (ENV_REFERENCE_SUFFIX_PATTERN.test(key)) {
+    return false;
+  }
+  return SECRET_VALUE_KEY_PATTERN.test(key);
+}
+
+function redactRecursive(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(redactRecursive);
+  }
+  if (value !== null && typeof value === "object") {
+    const result: Record<string, unknown> = {};
+    for (const [key, entryValue] of Object.entries(value)) {
+      result[key] = looksLikeResolvedSecretKey(key)
+        ? REDACTED_PLACEHOLDER
+        : redactRecursive(entryValue);
+    }
+    return result;
+  }
+  return value;
+}
+
+/**
+ * Returns a deep copy of `value` with any field whose name looks like a
+ * resolved secret (`apiKey`, `token`, `password`, `secret`, `credential`, but
+ * NOT the `...Env` reference fields) replaced by a fixed placeholder. Safe to
+ * call on an `EffectiveUntangleConfigV1`, a partial layer, or arbitrary
+ * nested data.
+ */
+export function redactSecrets<T>(value: T): T {
+  return redactRecursive(value) as T;
+}
+
+/** `JSON.stringify` through {@link redactSecrets} — the one safe way to dump a config. */
+export function toRedactedJson(value: unknown, space?: number): string {
+  return JSON.stringify(redactSecrets(value), null, space);
+}
+
+/**
+ * Resolves an `apiKeyEnv` reference to its actual secret value AT CALL TIME.
+ * The result MUST NOT be stored back onto any config object — callers (e.g.
+ * a Qdrant/Ollama adapter) use it immediately for one connection attempt.
+ * Returns `undefined` when `envVarName` is unset or the variable is not
+ * present in `env`.
+ */
+export function resolveApiKey(
+  envVarName: string | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  if (envVarName === undefined || envVarName.length === 0) {
+    return undefined;
+  }
+  return env[envVarName];
+}