@bymax-one/nest-config 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -11,6 +11,75 @@ as the GitHub Release body, so each released version needs a matching
 
 ## [Unreleased]
 
+## [1.1.2] - 2026-08-14
+
+**Documentation only.** `dist/` is byte-identical to `1.1.1`, verified by hashing every file in
+the published tarball against a local build. Inside the package only `README.md`, `CHANGELOG.md`
+and the `version` field of `package.json` differ.
+
+### Documentation
+
+- **The `1.1.1` apply-note understated the work for a consumer with a mutation gate.** It said
+  a derived backend has nothing to change, which is true for correctness and wrong as an
+  estimate. Under Stryker, a message string literal is a mutant: authoring messages for rules
+  that had none converts operator-facing prose into tested behavior, and a repo gating at
+  `break: 100` fails until an assertion pins each message. Reported by a consumer adopting
+  `1.1.1`, which added one assertion per message to keep its gate green.
+
+  The honest version of the note: **upgrading changes nothing** — a rule that carries no
+  message renders exactly as it did before, verified byte-for-byte on a real boot. **Writing
+  the messages the release makes worth writing is real work**: wherever mutation testing is a
+  gate, every message needs an assertion that covers it — one assertion on the rendered report
+  can cover several — and that is the work the release exists to enable.
+
+  Also worth knowing before writing them: a rule whose variable is _absent_ rendered
+  `missing required value` on `1.1.0`, not `invalid value`. For a conditionally-required
+  variable that is the more misleading of the two — nothing was forgotten, another variable
+  made it required — so the before/after is larger than the `invalid value` case suggests.
+
+- The mutation badge read **99.59%**; the score measured as the `v1.1.1` release gate is
+  **99.61%**. The denominator grew with the new code — 14 more killed mutants in
+  `env-validator.ts`, the only file the release changed executably, and the same single
+  counted survivor — so the badge, the README claim and `docs/mutation_testing_results.md`
+  now state the measured number, with a dated re-run entry recording it.
+
+## [1.1.1] - 2026-08-14
+
+### Fixed
+
+- **A `custom` issue is reported with the message its author wrote.** `.check`, `.refine`
+  and `.superRefine` all raise Zod's `custom` code, which carries no structural constraint
+  to translate, so every one of them rendered as the literal `invalid value` and the rule's
+  own explanation was discarded. Built-in codes were unaffected, which is what made it easy
+  to miss: the report looked correct until a rule stopped being trivial. A conditional
+  requirement, a cross-field rule or a security floor states itself only through that
+  message, and the aggregated report is the one artifact an operator gets for a failure that
+  stops the process.
+
+  The message is used whether the variable is absent or present-but-invalid — "required
+  when `X` is enabled" explains an absent variable better than `missing required value`
+  does — while `issue.code` still classifies it as `BYMAX_CONFIG_MISSING` or
+  `BYMAX_CONFIG_INVALID`, so machine consumers are unaffected. Whitespace runs collapse to
+  single spaces to keep the one-line-per-variable layout; the column layout and the
+  resolved `variable` name are unchanged.
+
+  A `custom` issue raised without a message of its own still reads `invalid value`. Zod
+  fills a message-less `custom` issue with its locale default before the validator sees it,
+  so "no authored message" is recognized by matching that default (`Invalid input`) rather
+  than by absence. Two consequences, both deliberate: the string is reserved, so a schema
+  that authors it verbatim reports `invalid value`; and under a configured non-English Zod
+  locale or a global custom error map the localized default does not match and is reported
+  as written.
+
+  Value-free stays a contract for the text this library generates. An authored message is
+  schema text and is printed as written, including a value interpolated into it. The
+  exception is now stated everywhere the guarantee is made: the `ConfigIssue`,
+  `BymaxConfigValidationError` and `onValidationError` contracts, `env-validator`'s own
+  contract, the README (including the security table) and spec 6.1.
+
+  **Apply to a derived backend:** nothing to change. A schema that already raises `custom`
+  issues with messages starts reporting them on the next boot.
+
 ## [1.1.0] - 2026-08-11
 
 Coordinated ecosystem release aligning every `@bymax-one/*` package after the ioredis 6 /
@@ -193,4 +262,6 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.0.1]: https://github.com/bymaxone/nest-config/compare/v1.0.0...v1.0.1
 [1.0.3]: https://github.com/bymaxone/nest-config/compare/v1.0.2...v1.0.3
 [1.1.0]: https://github.com/bymaxone/nest-config/compare/v1.0.3...v1.1.0
-[Unreleased]: https://github.com/bymaxone/nest-config/compare/v1.1.0...HEAD
+[1.1.1]: https://github.com/bymaxone/nest-config/compare/v1.1.0...v1.1.1
+[1.1.2]: https://github.com/bymaxone/nest-config/compare/v1.1.1...v1.1.2
+[Unreleased]: https://github.com/bymaxone/nest-config/compare/v1.1.2...HEAD

package/README.md

@@ -14,7 +14,7 @@
   <a href="https://www.npmjs.com/package/@bymax-one/nest-config"><img src="https://img.shields.io/npm/dm/@bymax-one/nest-config?style=flat-square&colorA=000000&colorB=000000" alt="npm downloads" /></a>
   <a href="https://github.com/bymaxone/nest-config/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/bymaxone/nest-config/ci.yml?branch=main&style=flat-square&colorA=000000&label=CI" alt="CI status" /></a>
   <a href="https://github.com/bymaxone/nest-config/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square&colorA=000000" alt="coverage" /></a>
-  <a href="https://github.com/bymaxone/nest-config/blob/main/docs/mutation_testing_results.md"><img src="https://img.shields.io/badge/mutation-99.59%25-brightgreen?style=flat-square&colorA=000000" alt="mutation score" /></a>
+  <a href="https://github.com/bymaxone/nest-config/blob/main/docs/mutation_testing_results.md"><img src="https://img.shields.io/badge/mutation-99.61%25-brightgreen?style=flat-square&colorA=000000" alt="mutation score" /></a>
   <a href="https://scorecard.dev/viewer/?uri=github.com/bymaxone/nest-config"><img src="https://api.scorecard.dev/projects/github.com/bymaxone/nest-config/badge?style=flat-square" alt="OpenSSF Scorecard" /></a>
   <a href="https://github.com/bymaxone/nest-config/blob/main/LICENSE"><img src="https://img.shields.io/github/license/bymaxone/nest-config?style=flat-square&colorA=000000&colorB=000000" alt="license" /></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" /></a>
@@ -50,8 +50,9 @@ minimal.
 - **One round trip to fix the environment.** Every violation is collected and reported
   together, not the first one that fails.
 - **Errors are value-free by contract.** Configuration is where the secrets are, and the
-  report is the artifact that gets logged and pasted into issues — so messages carry the
-  expected constraint and the schema's own enum options, never the received value.
+  report is the artifact that gets logged and pasted into issues — so generated messages
+  carry the expected constraint and the schema's own enum options, never the received
+  value. Your own `custom` messages are the documented exception: they print as written.
 - **The schema is the type.** `get('database.url')` is `string` and `get('server.port')` is
   `number` because the schema says so; a typo in a path is a build error, not a runtime
   `undefined`.
@@ -66,8 +67,9 @@ minimal.
   application serves traffic; there is no lazy path that could discover a problem later
 - ✅ **Fail fast, fail complete** — every violation reported together in one aggregated
   error, so an operator fixes the environment in one round trip
-- ✅ **Never echo values** — messages carry variable names, paths and constraint
-  descriptions only, so a secret cannot reach a log or a crash report through this library
+- ✅ **Never echo values** — generated messages carry variable names, paths and constraint
+  descriptions only, so a secret cannot reach a log or a crash report through this library;
+  a `custom` message you write yourself is printed as written and is yours to keep value-free
 - ✅ **Zod v4 schemas** — the full type language, including coercion, refinements and
   defaults, with `defineEnv` shaping namespaces and leaves
 
@@ -202,8 +204,38 @@ BymaxConfigValidationError: environment validation failed (3 issues)
 Fix the variables above and restart the process.
 ```
 
-Raw values are never printed, not truncated, not masked, absent. This is a
-hard guarantee of the package, verified by tests.
+In a message this package generates, raw values are never printed — not
+truncated, not masked, absent. That is a hard guarantee, verified by tests. The
+one exception is a message you write yourself, described next.
+
+A rule you write yourself — a `.check`, `.refine` or `.superRefine` raising a
+`custom` issue — has no structural constraint to describe, so its own message is
+what the report prints:
+
+```
+BymaxConfigValidationError: environment validation failed (2 issues)
+
+  STORAGE_ENDPOINT      STORAGE_ENDPOINT is required when STORAGE_ENABLED is true.
+  LOG_PRETTY            LOG_PRETTY must be false when NODE_ENV is production.
+
+Fix the variables above and restart the process.
+```
+
+The message is used whether the variable is absent or present-but-invalid — a
+conditional rule explains an absent variable better than "missing required
+value" does — while `issue.code` still classifies it as
+`BYMAX_CONFIG_MISSING` or `BYMAX_CONFIG_INVALID`. Whitespace runs collapse to
+single spaces so a message wrapped across source lines keeps the one-line
+layout.
+
+A `custom` issue raised without a message falls back to `invalid value`. Zod
+fills a message-less `custom` issue with its own default text before the
+validator sees it, so "no message" is recognized by matching that default
+(`Invalid input`) rather than by its absence. Two consequences, both deliberate:
+that exact string is reserved — a schema that authors it verbatim reports
+`invalid value` — and under a configured non-English Zod locale (or a global
+custom error map) the default no longer matches, so the localized default is
+reported as written instead.
 
 ## 📖 API Reference
 
@@ -287,7 +319,7 @@ export interface ConfigIssue {
   readonly path: string // e.g. "database.url"
   readonly variable: string // e.g. "DATABASE_URL"
   readonly code: ConfigIssueCode
-  readonly message: string // value-free constraint description
+  readonly message: string // constraint description, or your own `custom` message
 }
 ```
 
@@ -353,7 +385,7 @@ that needs to reference the schema shape directly.
                       │                 │
                       ▼                 ▼
               deep-frozen        BymaxConfigValidationError
-              BYMAX_CONFIG       one aggregated, value-free report
+              BYMAX_CONFIG       one aggregated boot-time report
                       │                 │
                       ▼                 ▼
                ConfigService     the process does not start
@@ -380,15 +412,15 @@ accidentally pass because a variable happened to be set on the machine.
 
 ### Design Principles
 
-| Principle                            | Description                                                                                                                                                                                |
-| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 💥 **Refuse to start**               | A misconfigured process is stopped before it serves a request, rather than discovering the gap at the first call that needs the value                                                      |
-| 🤐 **Value-free by contract**        | `errors.ts`, `env-validator.ts` and `report-formatter.ts` each state it for themselves: the message carries the expected constraint and the schema's own options, never the received value |
-| 📋 **Report everything at once**     | Validation collects every failure before throwing, so fixing an environment is one cycle instead of one per variable                                                                       |
-| 🧊 **Frozen after validation**       | Nothing in the running process rewrites configuration under a component that already read it                                                                                               |
-| 🔤 **The schema is the type**        | Dot paths are checked against the schema at compile time, so a typo is a build error rather than a runtime `undefined`                                                                     |
-| ⚙️ **Configuration over convention** | Everything goes through `forRoot`/`forRootAsync`. No file discovery, no magic paths, no hidden precedence rules                                                                            |
-| 🧩 **One class identity**            | The module and `./testing` import the shared runtime by package specifier, so `ConfigService` is one injection token in ESM and CommonJS alike                                             |
+| Principle                            | Description                                                                                                                                                                                        |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 💥 **Refuse to start**               | A misconfigured process is stopped before it serves a request, rather than discovering the gap at the first call that needs the value                                                              |
+| 🤐 **Value-free by contract**        | `errors.ts`, `env-validator.ts` and `report-formatter.ts` each state it for themselves: a generated message carries the expected constraint and the schema's own options, never the received value |
+| 📋 **Report everything at once**     | Validation collects every failure before throwing, so fixing an environment is one cycle instead of one per variable                                                                               |
+| 🧊 **Frozen after validation**       | Nothing in the running process rewrites configuration under a component that already read it                                                                                                       |
+| 🔤 **The schema is the type**        | Dot paths are checked against the schema at compile time, so a typo is a build error rather than a runtime `undefined`                                                                             |
+| ⚙️ **Configuration over convention** | Everything goes through `forRoot`/`forRootAsync`. No file discovery, no magic paths, no hidden precedence rules                                                                                    |
+| 🧩 **One class identity**            | The module and `./testing` import the shared runtime by package specifier, so `ConfigService` is one injection token in ESM and CommonJS alike                                                     |
 
 ---
 
@@ -399,10 +431,11 @@ guaranteed to be printed, logged, and pasted into an issue. That shapes the whol
 
 ### Errors are value-free by contract
 
-Every message states the _expected_ constraint — the type, the allowed enum options taken
-from the schema, the bound — and never the received value. `env-validator` and
-`report-formatter` each say so in their own contracts, and property-based tests hold them
-to it.
+Every message this library generates states the _expected_ constraint — the type, the
+allowed enum options taken from the schema, the bound — and never the received value.
+`env-validator` and `report-formatter` each say so in their own contracts, and
+property-based tests hold them to it. The messages you write yourself are the exception,
+covered below.
 
 ### The service does not serialize its configuration
 
@@ -434,27 +467,31 @@ not choose.
 
 ### Your own messages are yours
 
-Value-free applies to this library's reports. If a `.refine` or a custom message in your
-schema includes a value, that message is printed as written.
+Value-free applies to this library's reports. A `custom` issue from your own `.check`,
+`.refine` or `.superRefine` is printed as written — it is schema text, and it is the only
+place a conditional or cross-field rule can state itself. That also means the message is
+yours to keep value-free: if it interpolates the received value, that value reaches the
+report.
 
 ---
 
 ## 🛡️ Security Table
 
-| Layer          | Implementation                                                                                                             |
-| -------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| Error messages | Expected constraint only — type, schema-declared enum options, bounds; never the received value                            |
-| Failure mode   | Refuse to start; the whole schema is validated before the context finishes building                                        |
-| Aggregation    | Every failure reported at once, so a fix cycle is one restart rather than one per variable                                 |
-| Immutability   | The validated result is frozen before it is provided                                                                       |
-| Service state  | The root lives in a private field; serializing the injected service yields namespace names only                            |
-| Sources        | `process.env` only — no file, no network, no remote provider                                                               |
-| Type surface   | Dot paths checked against the schema at compile time; a typo is a build error, not a runtime `undefined`                   |
-| Supply chain   | `dependencies: {}`; third-party Actions pinned by commit SHA (org-internal reusables by tag); CodeQL and OpenSSF Scorecard |
+| Layer          | Implementation                                                                                                                                                                  |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Error messages | Expected constraint only — type, schema-declared enum options, bounds; never the received value. A `custom` message from your own schema is the exception: it prints as written |
+| Failure mode   | Refuse to start; the whole schema is validated before the context finishes building                                                                                             |
+| Aggregation    | Every failure reported at once, so a fix cycle is one restart rather than one per variable                                                                                      |
+| Immutability   | The validated result is frozen before it is provided                                                                                                                            |
+| Service state  | The root lives in a private field; serializing the injected service yields namespace names only                                                                                 |
+| Sources        | `process.env` only — no file, no network, no remote provider                                                                                                                    |
+| Type surface   | Dot paths checked against the schema at compile time; a typo is a build error, not a runtime `undefined`                                                                        |
+| Supply chain   | `dependencies: {}`; third-party Actions pinned by commit SHA (org-internal reusables by tag); CodeQL and OpenSSF Scorecard                                                      |
 
 > [!IMPORTANT]
-> **Value-free applies to this library's own reports.** If your schema's `.refine`
-> or a custom message includes a value, that message is printed as written.
+> **Value-free applies to this library's own reports.** A `custom` message from your
+> schema's `.check`, `.refine` or `.superRefine` is printed as written — including a
+> value, if you interpolate one into it.
 
 ---
 
@@ -477,14 +514,15 @@ Configuration decides whether a process may start at all, so the suite is held t
 beyond "the tests pass".
 
 - ✅ **100% line coverage** — statements, branches, functions and lines, enforced as a gate
-- ✅ **99.59% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at
+- ✅ **99.61% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at
   `break: 95`; ten provable equivalents carry their reason inline, and the one survivor left
   is an equivalent no directive can reach, so it stays counted rather than silenced
   ([report](./docs/mutation_testing_results.md))
 - ✅ **The value-free guarantee is tested, not assumed** — a sentinel secret is placed in a
   source and the assertion is that it appears nowhere in the rendered report or in the thrown
   error, because a guarantee about what is _absent_ is the one thing an ordinary assertion
-  about output does not cover
+  about output does not cover; the schema under test writes no `custom` message, so what is
+  proven is the guarantee this package makes for its own generated text
 - ✅ **Published-artifact gates** — `check:exports` resolves the types the way each module
   system does, `check:runtime` loads every subpath from the packed tarball in ESM and
   CommonJS, and `check:published` compiles this README's snippets against `dist/`

package/dist/internal/index.cjs

@@ -87,7 +87,7 @@ var ConfigErrorCode = Object.freeze({
 });
 var BymaxConfigValidationError = class _BymaxConfigValidationError extends Error {
   /**
-   * Build the aggregated error from a list of value-free issues.
+   * Build the aggregated error from the collected issues.
    *
    * @param issues - Every collected violation; copied and frozen so neither the
    * caller nor consumer code can mutate the reported list.
@@ -146,6 +146,7 @@ function resolveNamespacePrefixes(schema) {
 // src/env-validator.ts
 var UNKNOWN_KEY_MESSAGE = "unknown variable not declared in the schema";
 var MISSING_MESSAGE = "missing required value";
+var ZOD_DEFAULT_CUSTOM_MESSAGE = "Invalid input";
 function collectPresentLeaves(bindings, source) {
   const present = [];
   for (const binding of bindings) {
@@ -189,13 +190,20 @@ function describeConstraint(issue) {
       return "invalid value";
   }
 }
+function authoredMessage(issue) {
+  if (issue.code !== "custom") return void 0;
+  const collapsed = issue.message.replace(/\s+/g, " ").trim();
+  if (collapsed.length === 0 || collapsed === ZOD_DEFAULT_CUSTOM_MESSAGE) return void 0;
+  return collapsed;
+}
 function toConfigIssue(binding, issue, source) {
   const isMissing = source.get(binding.variable) === void 0;
+  const authored = authoredMessage(issue);
   return {
     path: binding.path,
     variable: binding.variable,
     code: isMissing ? ConfigErrorCode.MISSING : ConfigErrorCode.INVALID,
-    message: isMissing ? MISSING_MESSAGE : describeConstraint(issue)
+    message: authored ?? (isMissing ? MISSING_MESSAGE : describeConstraint(issue))
   };
 }
 function translateIssues(zodIssues, bindings, source) {

package/dist/internal/index.d.cts

@@ -99,11 +99,12 @@ type Path<TConfig> = {
 type PathValue<TConfig, TPath extends Path<TConfig>> = TPath extends `${infer Namespace}.${infer Leaf}` ? Namespace extends keyof TConfig ? Leaf extends keyof TConfig[Namespace] ? TConfig[Namespace][Leaf] : never : never : never;
 
 /**
- * @fileoverview Value-free error model for the configuration validation
- * pipeline: the frozen issue-code catalog, the ConfigIssue shape, and the
+ * @fileoverview Error model for the configuration validation pipeline: the
+ * frozen issue-code catalog, the ConfigIssue shape, and the
  * BymaxConfigValidationError aggregate. The error carries every violation as a
  * structured, immutable issue list and renders a multi-line report that never
- * echoes a raw source value.
+ * echoes a raw source value of its own — see {@link ConfigIssue} for the one
+ * exception, a message written by the schema author.
  * @layer Error
  */
 /**
@@ -135,11 +136,17 @@ type ConfigValidationCode = typeof ConfigErrorCode.VALIDATION;
 /** Machine-readable code classifying a single {@link ConfigIssue}. */
 type ConfigIssueCode = typeof ConfigErrorCode.MISSING | typeof ConfigErrorCode.INVALID | typeof ConfigErrorCode.UNKNOWN_KEY;
 /**
- * A single configuration violation, described entirely without any raw value.
+ * A single configuration violation, described for the operator who must fix it.
  *
- * Every field is value-free by contract: `message` states the expected
- * constraint, never the received input, so an issue can be logged or serialized
- * without leaking a secret.
+ * Every description this package generates is value-free by contract: `message`
+ * states the expected constraint, never the received input, so an issue can be
+ * logged or serialized without leaking a secret.
+ *
+ * The one exception is the message a schema author attaches to a `custom` issue
+ * (`.check`, `.refine`, `.superRefine`), which is reported as written because it
+ * is the only statement of a rule that has no structural constraint to describe.
+ * A message that interpolates the received value therefore carries that value
+ * into the report; keeping an authored message value-free is the author's call.
  */
 interface ConfigIssue {
     /** Nested config path, e.g. `database.url`; the namespace alone (e.g. `database`) for an unknown-key issue. */
@@ -148,16 +155,17 @@ interface ConfigIssue {
     readonly variable: string;
     /** Stable machine-readable classification. */
     readonly code: ConfigIssueCode;
-    /** Human-readable constraint description, value-free. */
+    /** Human-readable constraint description; value-free unless a schema author's own `custom` message says otherwise. */
     readonly message: string;
 }
 /**
- * Aggregated, value-free configuration validation error.
+ * Aggregated configuration validation error.
  *
  * Thrown once at bootstrap when the source fails the schema. It carries every
  * violation in an immutable, structured {@link ConfigIssue} list and a
  * human-readable message that lists the offending variables and their expected
- * constraints, never their received values.
+ * constraints, never their received values — except where a schema author's own
+ * `custom` message says otherwise, as described on {@link ConfigIssue}.
  *
  * @example
  * ```typescript
@@ -176,7 +184,7 @@ declare class BymaxConfigValidationError extends Error {
     /** The immutable, aggregated list of collected violations. */
     readonly issues: ReadonlyArray<ConfigIssue>;
     /**
-     * Build the aggregated error from a list of value-free issues.
+     * Build the aggregated error from the collected issues.
      *
      * @param issues - Every collected violation; copied and frozen so neither the
      * caller nor consumer code can mutate the reported list.
@@ -187,7 +195,7 @@ declare class BymaxConfigValidationError extends Error {
 /**
  * @fileoverview Public options contract for the BymaxConfigModule dynamic
  * module: the schema to validate against, an optional raw source (defaulting to
- * the process environment inside the provider factory), an optional value-free
+ * the process environment inside the provider factory), an optional
  * observability hook invoked before the fail-fast throw, and an optional strict
  * unknown-key flag. This file declares only types and carries no runtime code.
  * @layer Types
@@ -217,10 +225,12 @@ interface BymaxConfigModuleOptions<TSchema extends EnvSchema = EnvSchema> {
      */
     readonly source?: Record<string, string | undefined>;
     /**
-     * Observability hook invoked once with the structured, value-free issue list
-     * immediately before the validation error is thrown. It is observability
-     * only and cannot suppress the failure: the error still propagates even when
-     * the hook itself throws.
+     * Observability hook invoked once with the structured issue list immediately
+     * before the validation error is thrown. The issues are value-free on the
+     * terms stated by {@link ConfigIssue}: generated descriptions never carry a
+     * received value, while a schema author's own `custom` message is passed
+     * through as written. It is observability only and cannot suppress the
+     * failure: the error still propagates even when the hook itself throws.
      */
     readonly onValidationError?: (issues: ReadonlyArray<ConfigIssue>) => void;
     /**
@@ -514,8 +524,8 @@ declare function defineEnv<TShape extends EnvShape>(shape: TShape): EnvSchema<TS
  * @fileoverview The BYMAX_CONFIG provider factory: the fail-fast heart of the
  * module. It resolves the source (defaulting to `process.env`, using a custom
  * source verbatim), runs the single-pass validator, and on success returns the
- * deep-frozen typed config. On failure it invokes the value-free observability
- * hook exactly once before rethrowing the aggregated error; the hook is
+ * deep-frozen typed config. On failure it invokes the observability hook
+ * exactly once before rethrowing the aggregated error; the hook is
  * observability only and can never suppress or replace the failure, so a
  * misconfigured process is stopped before any consumer provider is constructed.
  * @layer Provider

package/dist/internal/index.d.ts

@@ -99,11 +99,12 @@ type Path<TConfig> = {
 type PathValue<TConfig, TPath extends Path<TConfig>> = TPath extends `${infer Namespace}.${infer Leaf}` ? Namespace extends keyof TConfig ? Leaf extends keyof TConfig[Namespace] ? TConfig[Namespace][Leaf] : never : never : never;
 
 /**
- * @fileoverview Value-free error model for the configuration validation
- * pipeline: the frozen issue-code catalog, the ConfigIssue shape, and the
+ * @fileoverview Error model for the configuration validation pipeline: the
+ * frozen issue-code catalog, the ConfigIssue shape, and the
  * BymaxConfigValidationError aggregate. The error carries every violation as a
  * structured, immutable issue list and renders a multi-line report that never
- * echoes a raw source value.
+ * echoes a raw source value of its own — see {@link ConfigIssue} for the one
+ * exception, a message written by the schema author.
  * @layer Error
  */
 /**
@@ -135,11 +136,17 @@ type ConfigValidationCode = typeof ConfigErrorCode.VALIDATION;
 /** Machine-readable code classifying a single {@link ConfigIssue}. */
 type ConfigIssueCode = typeof ConfigErrorCode.MISSING | typeof ConfigErrorCode.INVALID | typeof ConfigErrorCode.UNKNOWN_KEY;
 /**
- * A single configuration violation, described entirely without any raw value.
+ * A single configuration violation, described for the operator who must fix it.
  *
- * Every field is value-free by contract: `message` states the expected
- * constraint, never the received input, so an issue can be logged or serialized
- * without leaking a secret.
+ * Every description this package generates is value-free by contract: `message`
+ * states the expected constraint, never the received input, so an issue can be
+ * logged or serialized without leaking a secret.
+ *
+ * The one exception is the message a schema author attaches to a `custom` issue
+ * (`.check`, `.refine`, `.superRefine`), which is reported as written because it
+ * is the only statement of a rule that has no structural constraint to describe.
+ * A message that interpolates the received value therefore carries that value
+ * into the report; keeping an authored message value-free is the author's call.
  */
 interface ConfigIssue {
     /** Nested config path, e.g. `database.url`; the namespace alone (e.g. `database`) for an unknown-key issue. */
@@ -148,16 +155,17 @@ interface ConfigIssue {
     readonly variable: string;
     /** Stable machine-readable classification. */
     readonly code: ConfigIssueCode;
-    /** Human-readable constraint description, value-free. */
+    /** Human-readable constraint description; value-free unless a schema author's own `custom` message says otherwise. */
     readonly message: string;
 }
 /**
- * Aggregated, value-free configuration validation error.
+ * Aggregated configuration validation error.
  *
  * Thrown once at bootstrap when the source fails the schema. It carries every
  * violation in an immutable, structured {@link ConfigIssue} list and a
  * human-readable message that lists the offending variables and their expected
- * constraints, never their received values.
+ * constraints, never their received values — except where a schema author's own
+ * `custom` message says otherwise, as described on {@link ConfigIssue}.
  *
  * @example
  * ```typescript
@@ -176,7 +184,7 @@ declare class BymaxConfigValidationError extends Error {
     /** The immutable, aggregated list of collected violations. */
     readonly issues: ReadonlyArray<ConfigIssue>;
     /**
-     * Build the aggregated error from a list of value-free issues.
+     * Build the aggregated error from the collected issues.
      *
      * @param issues - Every collected violation; copied and frozen so neither the
      * caller nor consumer code can mutate the reported list.
@@ -187,7 +195,7 @@ declare class BymaxConfigValidationError extends Error {
 /**
  * @fileoverview Public options contract for the BymaxConfigModule dynamic
  * module: the schema to validate against, an optional raw source (defaulting to
- * the process environment inside the provider factory), an optional value-free
+ * the process environment inside the provider factory), an optional
  * observability hook invoked before the fail-fast throw, and an optional strict
  * unknown-key flag. This file declares only types and carries no runtime code.
  * @layer Types
@@ -217,10 +225,12 @@ interface BymaxConfigModuleOptions<TSchema extends EnvSchema = EnvSchema> {
      */
     readonly source?: Record<string, string | undefined>;
     /**
-     * Observability hook invoked once with the structured, value-free issue list
-     * immediately before the validation error is thrown. It is observability
-     * only and cannot suppress the failure: the error still propagates even when
-     * the hook itself throws.
+     * Observability hook invoked once with the structured issue list immediately
+     * before the validation error is thrown. The issues are value-free on the
+     * terms stated by {@link ConfigIssue}: generated descriptions never carry a
+     * received value, while a schema author's own `custom` message is passed
+     * through as written. It is observability only and cannot suppress the
+     * failure: the error still propagates even when the hook itself throws.
      */
     readonly onValidationError?: (issues: ReadonlyArray<ConfigIssue>) => void;
     /**
@@ -514,8 +524,8 @@ declare function defineEnv<TShape extends EnvShape>(shape: TShape): EnvSchema<TS
  * @fileoverview The BYMAX_CONFIG provider factory: the fail-fast heart of the
  * module. It resolves the source (defaulting to `process.env`, using a custom
  * source verbatim), runs the single-pass validator, and on success returns the
- * deep-frozen typed config. On failure it invokes the value-free observability
- * hook exactly once before rethrowing the aggregated error; the hook is
+ * deep-frozen typed config. On failure it invokes the observability hook
+ * exactly once before rethrowing the aggregated error; the hook is
  * observability only and can never suppress or replace the failure, so a
  * misconfigured process is stopped before any consumer provider is constructed.
  * @layer Provider

package/dist/internal/index.mjs

@@ -85,7 +85,7 @@ var ConfigErrorCode = Object.freeze({
 });
 var BymaxConfigValidationError = class _BymaxConfigValidationError extends Error {
   /**
-   * Build the aggregated error from a list of value-free issues.
+   * Build the aggregated error from the collected issues.
    *
    * @param issues - Every collected violation; copied and frozen so neither the
    * caller nor consumer code can mutate the reported list.
@@ -144,6 +144,7 @@ function resolveNamespacePrefixes(schema) {
 // src/env-validator.ts
 var UNKNOWN_KEY_MESSAGE = "unknown variable not declared in the schema";
 var MISSING_MESSAGE = "missing required value";
+var ZOD_DEFAULT_CUSTOM_MESSAGE = "Invalid input";
 function collectPresentLeaves(bindings, source) {
   const present = [];
   for (const binding of bindings) {
@@ -187,13 +188,20 @@ function describeConstraint(issue) {
       return "invalid value";
   }
 }
+function authoredMessage(issue) {
+  if (issue.code !== "custom") return void 0;
+  const collapsed = issue.message.replace(/\s+/g, " ").trim();
+  if (collapsed.length === 0 || collapsed === ZOD_DEFAULT_CUSTOM_MESSAGE) return void 0;
+  return collapsed;
+}
 function toConfigIssue(binding, issue, source) {
   const isMissing = source.get(binding.variable) === void 0;
+  const authored = authoredMessage(issue);
   return {
     path: binding.path,
     variable: binding.variable,
     code: isMissing ? ConfigErrorCode.MISSING : ConfigErrorCode.INVALID,
-    message: isMissing ? MISSING_MESSAGE : describeConstraint(issue)
+    message: authored ?? (isMissing ? MISSING_MESSAGE : describeConstraint(issue))
   };
 }
 function translateIssues(zodIssues, bindings, source) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-config",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Typed and validated environment configuration entry point for NestJS 11 applications, built on Zod v4.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",