@ontrails/config 1.0.0-beta.30 → 1.0.0-beta.32

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @ontrails/config
 
+## 1.0.0-beta.32
+
+### Patch Changes
+
+- 2b819f4: Rename config check reports to `ConfigReport` and `ConfigFieldReport`, and return field reports from `config.check`.
+- Updated dependencies [3e5c0fc]
+- Updated dependencies [f3c4fef]
+- Updated dependencies [cb0a9d8]
+- Updated dependencies [21c6dda]
+- Updated dependencies [fe72b84]
+  - @ontrails/core@1.0.0-beta.32
+
+## 1.0.0-beta.31
+
+### Patch Changes
+
+- Updated dependencies [4cd5d4e]
+- Updated dependencies [38907cc]
+  - @ontrails/core@1.0.0-beta.31
+
 ## 1.0.0-beta.30
 
 ### Patch Changes

package/README.md

@@ -166,7 +166,7 @@ export const myTrail = trail('my.trail', {
 
 ### `config.check`
 
-Validate config values against the schema. Returns diagnostics with field-level status (valid, missing, invalid, deprecated, default).
+Validate config values against the schema. Returns a config report with field-level status (valid, missing, invalid, deprecated, default) and the checked field values when available.
 
 ### `config.describe`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/config",
-  "version": "1.0.0-beta.30",
+  "version": "1.0.0-beta.32",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",
@@ -22,7 +22,7 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "peerDependencies": {
-    "@ontrails/core": "^1.0.0-beta.30",
+    "@ontrails/core": "^1.0.0-beta.32",
     "zod": "^4.3.5"
   }
 }

package/src/app-config.ts

@@ -7,7 +7,7 @@ import { dirname, join } from 'node:path';
 import { NotFoundError, Result, ValidationError } from '@ontrails/core';
 import type { z } from 'zod';
 
-import type { CheckResult } from './doctor.js';
+import type { ConfigReport } from './doctor.js';
 import { checkConfig } from './doctor.js';
 import type { FieldDescription } from './derive-fields.js';
 import { deriveConfigFields } from './derive-fields.js';
@@ -58,11 +58,11 @@ export interface AppConfig<T extends z.ZodType> {
   /** Describe all fields in the schema without needing values. */
   describe(): readonly FieldDescription[];
 
-  /** Check a config object against the schema and return diagnostics. */
+  /** Check a config object against the schema and return field reports. */
   check(
     values: Record<string, unknown>,
     options?: { readonly env?: Record<string, string | undefined> }
-  ): CheckResult;
+  ): ConfigReport;
 
   /** Show which source won for each config field. */
   explain(

package/src/collect.ts

@@ -79,6 +79,10 @@ const walkObjectShape = (
 
   for (const [key, fieldSchema] of Object.entries(shape)) {
     const path = prefix ? `${prefix}.${key}` : key;
+    const meta = extractConfigMeta(fieldSchema);
+    if (meta) {
+      result.set(path, meta);
+    }
 
     if (isZodObject(fieldSchema)) {
       queue.push({
@@ -87,11 +91,6 @@ const walkObjectShape = (
           Record<string, z.ZodType>
         >,
       });
-    } else {
-      const meta = extractConfigMeta(fieldSchema);
-      if (meta) {
-        result.set(path, meta);
-      }
     }
   }
 };

package/src/derive/env.ts

@@ -10,6 +10,7 @@ import { collectConfigMeta } from '../collect.js';
 import type { ConfigFieldMeta } from '../extensions.js';
 
 import { isLikelySecret } from '../secret-heuristics.js';
+import { isZodContainer } from '../zod-utils.js';
 
 import {
   formatValue,
@@ -80,6 +81,9 @@ const collectEnvEntries = (
     if (!fieldSchema) {
       continue;
     }
+    if (isZodContainer(fieldSchema)) {
+      continue;
+    }
     entries.push(...envEntry(fieldMeta.env, fieldSchema, fieldMeta));
     entries.push('');
   }

package/src/derive-provenance.ts

@@ -8,7 +8,14 @@ import type { z } from 'zod';
 
 import { collectConfigMeta } from './collect.js';
 import { isLikelySecret } from './secret-heuristics.js';
-import { getAtPath, isZodObject, unwrapToBase, zodDef } from './zod-utils.js';
+import {
+  getAtPath,
+  getSchemaAtPath,
+  isZodContainer,
+  isZodObject,
+  unwrapToBase,
+  zodDef,
+} from './zod-utils.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -64,21 +71,73 @@ const buildSecretSet = (
   return result;
 };
 
+/** Build a set of env-backed container paths that env overlay skips. */
+const buildSkippedEnvContainerSet = (
+  schema: z.ZodObject<Record<string, z.ZodType>>,
+  envMap: Map<string, string>
+): Set<string> => {
+  const result = new Set<string>();
+  for (const path of envMap.keys()) {
+    const fieldSchema = getSchemaAtPath(schema, path);
+    if (fieldSchema && isZodContainer(fieldSchema)) {
+      result.add(path);
+    }
+  }
+  return result;
+};
+
 /** Source entries in reverse precedence order for winner detection. */
 type SourceEntry = readonly [
   name: ProvenanceEntry['source'],
   values: Record<string, unknown> | undefined,
 ];
 
+/** Compare JSON-shaped config values for provenance winner detection. */
+const areConfigValuesEqual = (left: unknown, right: unknown): boolean => {
+  if (Object.is(left, right)) {
+    return true;
+  }
+  if (Array.isArray(left) || Array.isArray(right)) {
+    if (!(Array.isArray(left) && Array.isArray(right))) {
+      return false;
+    }
+    return (
+      left.length === right.length &&
+      left.every((value, index) => areConfigValuesEqual(value, right[index]))
+    );
+  }
+  if (
+    typeof left !== 'object' ||
+    left === null ||
+    typeof right !== 'object' ||
+    right === null
+  ) {
+    return false;
+  }
+  const leftRecord = left as Record<string, unknown>;
+  const rightRecord = right as Record<string, unknown>;
+  const leftKeys = Object.keys(leftRecord);
+  const rightKeys = Object.keys(rightRecord);
+  return (
+    leftKeys.length === rightKeys.length &&
+    leftKeys.every(
+      (key) =>
+        Object.hasOwn(rightRecord, key) &&
+        areConfigValuesEqual(leftRecord[key], rightRecord[key])
+    )
+  );
+};
+
 /** Determine which source provided the winning value for a given path. */
 const determineSource = (
   path: string,
   resolved: Record<string, unknown>,
   sources: readonly SourceEntry[],
   envMap: Map<string, string>,
+  skippedEnvContainers: Set<string>,
   envVars: Record<string, string | undefined> | undefined
 ): ProvenanceEntry['source'] => {
-  if (envVars && envMap.has(path)) {
+  if (envVars && envMap.has(path) && !skippedEnvContainers.has(path)) {
     const envVar = envMap.get(path);
     if (envVar && envVars[envVar] !== undefined) {
       return 'env';
@@ -87,7 +146,10 @@ const determineSource = (
 
   const resolvedValue = getAtPath(resolved, path);
   for (const [name, values] of sources) {
-    if (values && getAtPath(values, path) === resolvedValue) {
+    if (
+      values &&
+      areConfigValuesEqual(getAtPath(values, path), resolvedValue)
+    ) {
       return name;
     }
   }
@@ -143,6 +205,7 @@ export const deriveConfigProvenance = <T extends z.ZodType>(
   >;
   const envMap = buildEnvMap(objSchema);
   const secretSet = buildSecretSet(objSchema);
+  const skippedEnvContainers = buildSkippedEnvContainerSet(objSchema, envMap);
 
   const sources: readonly SourceEntry[] = [
     ['local', options.local],
@@ -158,6 +221,7 @@ export const deriveConfigProvenance = <T extends z.ZodType>(
       options.resolved,
       sources,
       envMap,
+      skippedEnvContainers,
       options.env
     );
     const envVarName = envMap.get(path);

package/src/doctor.ts

@@ -1,5 +1,5 @@
 /**
- * Config doctor — structured diagnostics for a config object against a schema.
+ * Config doctor — structured field reports for a config object against a schema.
  *
  * Reports which fields are valid, missing, using defaults, deprecated, or invalid.
  */
@@ -7,14 +7,22 @@
 import type { z } from 'zod';
 
 import { collectConfigMeta } from './collect.js';
-import { getAtPath, isZodObject, unwrapToBase, zodDef } from './zod-utils.js';
+import {
+  coerceEnvValue,
+  getAtPath,
+  getSchemaAtPath,
+  isZodContainer,
+  isZodObject,
+  unwrapToBase,
+  zodDef,
+} from './zod-utils.js';
 
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 
-/** Diagnostic status for a single config field. */
-export interface ConfigDiagnostic {
+/** Validation status for a single config field. */
+export interface ConfigFieldReport {
   readonly path: string;
   readonly status: 'valid' | 'missing' | 'invalid' | 'deprecated' | 'default';
   readonly message: string;
@@ -22,8 +30,8 @@ export interface ConfigDiagnostic {
 }
 
 /** Aggregated result from checking config against a schema. */
-export interface CheckResult {
-  readonly diagnostics: readonly ConfigDiagnostic[];
+export interface ConfigReport {
+  readonly fields: readonly ConfigFieldReport[];
   readonly valid: boolean;
 }
 
@@ -74,9 +82,20 @@ const applyEnvToValues = (
   const meta = collectConfigMeta(schema);
   const result = structuredClone(values) as Record<string, unknown>;
   for (const [path, fieldMeta] of meta) {
-    if (fieldMeta.env && envVars[fieldMeta.env] !== undefined) {
-      setAtPath(result, path, envVars[fieldMeta.env]);
+    const fieldSchema = getSchemaAtPath(schema, path);
+    const envName = fieldMeta.env;
+    const envValue = envName ? envVars[envName] : undefined;
+    if (!envName || envValue === undefined) {
+      continue;
     }
+    if (fieldSchema && isZodContainer(fieldSchema)) {
+      continue;
+    }
+    setAtPath(
+      result,
+      path,
+      fieldSchema ? coerceEnvValue(envValue, fieldSchema) : envValue
+    );
   }
   return result;
 };
@@ -96,7 +115,7 @@ const validateFieldValue = (
   path: string,
   fieldSchema: z.ZodType,
   value: unknown
-): ConfigDiagnostic => {
+): ConfigFieldReport => {
   const result = fieldSchema.safeParse(value);
   if (result.success) {
     return { message: 'OK', path, status: 'valid', value };
@@ -112,7 +131,7 @@ const classifyField = (
   fieldSchema: z.ZodType,
   values: Record<string, unknown>,
   deprecatedMeta: Map<string, string>
-): ConfigDiagnostic => {
+): ConfigFieldReport => {
   const value = getAtPath(values, path);
   const deprecationMsg = deprecatedMeta.get(path);
 
@@ -190,7 +209,7 @@ const collectLeaves = (schema: z.ZodType): WalkEntry[] => {
 // ---------------------------------------------------------------------------
 
 /**
- * Check a config object against a schema and return structured diagnostics.
+ * Check a config object against a schema and return structured field reports.
  *
  * Reports which fields are valid, missing, using defaults, deprecated, or invalid.
  */
@@ -198,7 +217,7 @@ export const checkConfig = <T extends z.ZodType>(
   schema: T,
   values: Record<string, unknown>,
   options?: { readonly env?: Record<string, string | undefined> }
-): CheckResult => {
+): ConfigReport => {
   const objSchema = schema as unknown as z.ZodObject<Record<string, z.ZodType>>;
   const effectiveValues = options?.env
     ? applyEnvToValues(values, objSchema, options.env)
@@ -207,13 +226,13 @@ export const checkConfig = <T extends z.ZodType>(
   const deprecatedMeta = collectDeprecatedPaths(objSchema);
   const leaves = collectLeaves(objSchema);
 
-  const diagnostics = leaves.map((leaf) =>
+  const fields = leaves.map((leaf) =>
     classifyField(leaf.path, leaf.schema, effectiveValues, deprecatedMeta)
   );
 
-  const valid = diagnostics.every(
+  const valid = fields.every(
     (d) => d.status !== 'missing' && d.status !== 'invalid'
   );
 
-  return { diagnostics, valid };
+  return { fields, valid };
 };

package/src/index.ts

@@ -36,8 +36,8 @@ export {
 export { deriveConfigFields, type FieldDescription } from './derive-fields.js';
 export {
   checkConfig,
-  type CheckResult,
-  type ConfigDiagnostic,
+  type ConfigReport,
+  type ConfigFieldReport,
 } from './doctor.js';
 export { env, secret, deprecated, type ConfigFieldMeta } from './extensions.js';
 export {

package/src/resolve.ts

@@ -9,7 +9,12 @@ import { Result, ValidationError } from '@ontrails/core';
 
 import { collectConfigMeta } from './collect.js';
 import { deepMerge } from './merge.js';
-import { zodDef } from './zod-utils.js';
+import {
+  coerceEnvValue,
+  getSchemaAtPath,
+  isZodContainer,
+  zodDef,
+} from './zod-utils.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -25,72 +30,6 @@ export interface DeriveConfigOptions<T extends z.ZodType> {
   readonly env?: Record<string, string | undefined> | undefined;
 }
 
-// ---------------------------------------------------------------------------
-// Env coercion helpers (defined before consumers)
-// ---------------------------------------------------------------------------
-
-/** Boolean string values we accept from environment variables. */
-const BOOL_TRUE = new Set(['true', '1']);
-const BOOL_FALSE = new Set(['false', '0']);
-
-/** Primitive type names we can coerce env strings into. */
-const PRIMITIVE_TYPES = new Set(['number', 'boolean', 'string']);
-
-/** Try to advance one level through a Zod wrapper, returning the inner type or undefined. */
-const unwrapOne = (
-  schema: z.ZodType
-): { typeName: string | undefined; inner: z.ZodType | undefined } => {
-  const def = zodDef(schema);
-  return {
-    inner: def['innerType'] as z.ZodType | undefined,
-    typeName: def['type'] as string | undefined,
-  };
-};
-
-/** Unwrap ZodDefault / ZodOptional / ZodNullable to find the base type name. */
-const resolveBaseTypeName = (schema: z.ZodType): string => {
-  let current: z.ZodType = schema;
-
-  for (let depth = 0; depth < 10; depth += 1) {
-    const { typeName, inner } = unwrapOne(current);
-    if (typeName && PRIMITIVE_TYPES.has(typeName)) {
-      return typeName;
-    }
-    if (!inner) {
-      break;
-    }
-    current = inner;
-  }
-
-  return 'string';
-};
-
-/** Coerce a boolean env string. Returns the original string if unrecognized. */
-const coerceBooleanEnv = (raw: string): unknown => {
-  if (BOOL_TRUE.has(raw)) {
-    return true;
-  }
-  if (BOOL_FALSE.has(raw)) {
-    return false;
-  }
-  return raw;
-};
-
-/** Coerce env var lookup table keyed by base type name. */
-const ENV_COERCERS: Record<string, (raw: string) => unknown> = {
-  boolean: coerceBooleanEnv,
-  number: (raw: string) => {
-    const n = Number(raw);
-    return Number.isNaN(n) ? raw : n;
-  },
-};
-
-/** Coerce a string env value to the type expected by the schema field. */
-const coerceEnvValue = (raw: string, schema: z.ZodType): unknown => {
-  const coercer = ENV_COERCERS[resolveBaseTypeName(schema)];
-  return coercer ? coercer(raw) : raw;
-};
-
 // ---------------------------------------------------------------------------
 // Path utilities
 // ---------------------------------------------------------------------------
@@ -132,33 +71,6 @@ const setAtPath = (
   parent[parts.at(-1) as string] = value;
 };
 
-/** Resolve one step of a Zod shape walk: find the field schema for a key. */
-const resolveShapeStep = (
-  current: z.ZodType,
-  key: string
-): z.ZodType | undefined => {
-  const shape = zodDef(current)['shape'] as
-    | Record<string, z.ZodType>
-    | undefined;
-  return shape?.[key];
-};
-
-/** Walk a Zod schema shape to find the field at a dot-separated path. */
-const getFieldSchema = (
-  schema: z.ZodType,
-  path: string
-): z.ZodType | undefined => {
-  let current: z.ZodType = schema;
-  for (const part of path.split('.')) {
-    const next = resolveShapeStep(current, part);
-    if (!next) {
-      return undefined;
-    }
-    current = next;
-  }
-  return current;
-};
-
 // ---------------------------------------------------------------------------
 // Env overlay
 // ---------------------------------------------------------------------------
@@ -170,7 +82,10 @@ const applyOneEnvOverride = (
   path: string,
   envValue: string
 ): void => {
-  const fieldSchema = getFieldSchema(schema, path);
+  const fieldSchema = getSchemaAtPath(schema, path);
+  if (fieldSchema && isZodContainer(fieldSchema)) {
+    return;
+  }
   const coerced = fieldSchema
     ? coerceEnvValue(envValue, fieldSchema)
     : envValue;

package/src/trails/config-check.ts

@@ -1,27 +1,36 @@
 /**
  * Infrastructure trail that validates config values against a schema.
  *
- * Returns structured diagnostics indicating which fields are valid,
+ * Returns structured field reports indicating which fields are valid,
  * missing, invalid, deprecated, or using defaults.
  */
 import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
 import { configResource } from '../config-resource.js';
+import { collectConfigMeta } from '../collect.js';
 import { checkConfig } from '../doctor.js';
 import { deepMerge } from '../merge.js';
+import { isLikelySecret } from '../secret-heuristics.js';
 
-const diagnosticSchema = z.object({
+const fieldReportSchema = z.object({
   message: z.string(),
   path: z.string(),
+  redacted: z.boolean().optional(),
   status: z.enum(['valid', 'missing', 'invalid', 'deprecated', 'default']),
+  value: z.unknown().optional(),
 });
 
 const outputSchema = z.object({
-  diagnostics: z.array(diagnosticSchema),
+  fields: z.array(fieldReportSchema),
   valid: z.boolean(),
 });
 
+type ConfigCheckFieldReport = ReturnType<typeof checkConfig>['fields'][number] &
+  Readonly<{
+    redacted?: boolean;
+  }>;
+
 /** Merge input values on top of resolved config values. */
 const mergeValues = (
   resolved: Record<string, unknown>,
@@ -31,13 +40,39 @@ const mergeValues = (
   return hasOverrides ? deepMerge(resolved, overrides) : resolved;
 };
 
+const redactSecretFields = (
+  schema: z.ZodObject<Record<string, z.ZodType>>,
+  fields: ReturnType<typeof checkConfig>['fields']
+): ConfigCheckFieldReport[] => {
+  const meta = collectConfigMeta(schema);
+  const redactedPaths = new Set(
+    [...meta.entries()]
+      .filter(
+        ([, fieldMeta]) =>
+          fieldMeta.secret === true ||
+          (fieldMeta.env !== undefined && isLikelySecret(fieldMeta.env))
+      )
+      .map(([path]) => path)
+  );
+  return fields.map((field) => {
+    const shouldRedact = [...redactedPaths].some(
+      (path) => field.path === path || field.path.startsWith(`${path}.`)
+    );
+    if (!shouldRedact || !('value' in field) || field.value === undefined) {
+      return field;
+    }
+
+    return { ...field, redacted: true, value: '[REDACTED]' };
+  });
+};
+
 export const configCheck = trail('config.check', {
   blaze: (input, ctx) => {
     const state = configResource.from(ctx);
     const effective = mergeValues(state.resolved, input.values);
     const checked = checkConfig(state.schema, effective);
     return Result.ok({
-      diagnostics: [...checked.diagnostics],
+      fields: redactSecretFields(state.schema, checked.fields),
       valid: checked.valid,
     });
   },

package/src/zod-utils.ts

@@ -9,15 +9,27 @@ import type { z } from 'zod';
 export const zodDef = (schema: z.ZodType): Record<string, unknown> =>
   schema.def as unknown as Record<string, unknown>;
 
-/** Wrapper types that should be peeled before checking the base type. */
-const WRAPPER_TYPES = new Set(['optional', 'default', 'nullable']);
+/** Wrapper types that preserve object traversal shape. */
+const TRAVERSAL_WRAPPER_TYPES = new Set(['optional', 'default', 'nullable']);
 
-/** Unwrap through optional/default/nullable wrappers to find the base schema. */
-export const unwrapToBase = (schema: z.ZodType): z.ZodType => {
+/** Wrapper types env overlay can inspect before coercing a string value. */
+const ENV_WRAPPER_TYPES = new Set([
+  ...TRAVERSAL_WRAPPER_TYPES,
+  'catch',
+  'nonoptional',
+  'prefault',
+  'readonly',
+]);
+
+/** Unwrap through selected wrappers to find the base schema. */
+const unwrapWith = (
+  schema: z.ZodType,
+  wrapperTypes: ReadonlySet<string>
+): z.ZodType => {
   let current = schema;
   for (let depth = 0; depth < 10; depth += 1) {
     const def = zodDef(current);
-    if (!WRAPPER_TYPES.has(def['type'] as string)) {
+    if (!wrapperTypes.has(def['type'] as string)) {
       return current;
     }
     const inner = def['innerType'] as z.ZodType | undefined;
@@ -29,6 +41,14 @@ export const unwrapToBase = (schema: z.ZodType): z.ZodType => {
   return current;
 };
 
+/** Unwrap through shape-preserving wrappers to find the base schema. */
+export const unwrapToBase = (schema: z.ZodType): z.ZodType =>
+  unwrapWith(schema, TRAVERSAL_WRAPPER_TYPES);
+
+/** Unwrap through env-coercion wrappers to find the env target schema. */
+const unwrapToEnvBase = (schema: z.ZodType): z.ZodType =>
+  unwrapWith(schema, ENV_WRAPPER_TYPES);
+
 /** Check if a schema is (or wraps) a ZodObject by inspecting its def. */
 export const isZodObject = (
   schema: z.ZodType
@@ -37,6 +57,85 @@ export const isZodObject = (
   return def['type'] === 'object' && 'shape' in def;
 };
 
+/** Container types an env string should not replace wholesale. */
+const CONTAINER_TYPES = new Set([
+  'object',
+  'array',
+  'tuple',
+  'record',
+  'map',
+  'set',
+]);
+
+/** Check whether a schema is a container shape after unwrapping defaults. */
+export const isZodContainer = (schema: z.ZodType): boolean => {
+  const def = zodDef(unwrapToEnvBase(schema));
+  return CONTAINER_TYPES.has(def['type'] as string);
+};
+
+/** Boolean string values we accept from environment variables. */
+const BOOL_TRUE = new Set(['true', '1']);
+const BOOL_FALSE = new Set(['false', '0']);
+
+/** Primitive type names we can coerce env strings into. */
+const PRIMITIVE_TYPES = new Set(['number', 'boolean', 'string']);
+
+/** Resolve the primitive base type name after unwrapping defaults. */
+const resolvePrimitiveBaseTypeName = (
+  schema: z.ZodType
+): string | undefined => {
+  const def = zodDef(unwrapToEnvBase(schema));
+  const typeName = def['type'] as string | undefined;
+  return typeName && PRIMITIVE_TYPES.has(typeName) ? typeName : undefined;
+};
+
+/** Coerce a boolean env string. Returns the original string if unrecognized. */
+const coerceBooleanEnv = (raw: string): unknown => {
+  if (BOOL_TRUE.has(raw)) {
+    return true;
+  }
+  if (BOOL_FALSE.has(raw)) {
+    return false;
+  }
+  return raw;
+};
+
+/** Coerce env var lookup table keyed by base type name. */
+const ENV_COERCERS: Record<string, (raw: string) => unknown> = {
+  boolean: coerceBooleanEnv,
+  number: (raw: string) => {
+    const n = Number(raw);
+    return Number.isNaN(n) ? raw : n;
+  },
+};
+
+/** Coerce a string env value to the type expected by the schema field. */
+export const coerceEnvValue = (raw: string, schema: z.ZodType): unknown => {
+  const typeName = resolvePrimitiveBaseTypeName(schema);
+  const coercer = typeName ? ENV_COERCERS[typeName] : undefined;
+  return coercer ? coercer(raw) : raw;
+};
+
+/** Resolve a schema at a dot-separated path through nested object shapes. */
+export const getSchemaAtPath = (
+  schema: z.ZodType,
+  path: string
+): z.ZodType | undefined => {
+  let current = schema;
+  for (const part of path.split('.')) {
+    const base = unwrapToBase(current);
+    const shape = zodDef(base)['shape'] as
+      | Record<string, z.ZodType>
+      | undefined;
+    const next = shape?.[part];
+    if (!next) {
+      return undefined;
+    }
+    current = next;
+  }
+  return current;
+};
+
 /** Read a value at a dot-separated path from a plain object. */
 export const getAtPath = (
   obj: Record<string, unknown>,