@bymax-one/nest-logger 1.2.7 → 1.2.9

package/CHANGELOG.md

@@ -11,6 +11,513 @@ heading here.
 
 ## [Unreleased]
 
+## [1.2.9] - 2026-08-16
+
+> **`1.2.8` was merged but never published.** The defect below was found in it after the merge and
+> before any tag existed, so the version was left untagged rather than released and superseded. npm
+> therefore goes `1.2.7` → `1.2.9`; the `1.2.8` section stays as the record of what landed, because
+> it is what `main` contains.
+
+### Fixed
+
+- **A destination whose `minLevel` was not one of the six levels received NOTHING, silently.**
+  `readonly minLevel?: LogLevel` is a compile-time claim, and a JavaScript consumer — or a
+  miscast one — can return any string; `'verbose'` is a real NestJS level name and a natural
+  thing to write. `pino.multistream` does not reject an unrecognised level: it builds without
+  complaint and the entry then matches nothing. Measured on a sink configured that way: **0 of 3
+  emitted entries delivered**, while the registry recorded it as covering the module level,
+  because `LOG_LEVEL_PRIORITY.indexOf` returned `-1` and lost the comparison. A destination
+  believed healthy and receiving, receiving nothing, is the worst failure this library has.
+  `safeMinLevel` now validates the value against the canonical list and treats an unrecognised
+  one as absent, so the destination falls back to the module level and keeps receiving.
+  `validateOptions` already held `options.level` to that same list; this is the check reaching
+  the one place it had not.
+
+- **A write returning a thenable that is not `instanceof Promise` no longer takes the synchronous
+  path, where its rejection escaped and its entry could be discarded.** `instanceof` is realm-local:
+  it answers `false` for a promise built in another realm — a worker, a `vm` context — and for any
+  structurally valid thenable. Measured, both:
+
+  ```
+  thenable instanceof Promise?                    false
+  promise from another realm instanceof Promise?  false
+  Promise.resolve() assimilates both?             true
+  ```
+
+  Such a write took the branch meant for synchronous sinks: the stream callback fired immediately, a
+  later rejection surfaced as an **unhandled rejection** instead of a reported
+  `LOGGER_DESTINATION_WRITE_FAILED`, and the write was never counted as in flight — so `1.2.8`'s
+  readiness check could tell a buffering destination that delivery was proven and let it discard its
+  only copy of an entry that was about to fail. Losing an entry is the one outcome this path does not
+  accept.
+
+  The branch is now on `undefined`, which is what the declared `void | PromiseLike<void>` actually
+  distinguishes, and the result goes through `Promise.resolve` — which assimilates both shapes.
+  Synchronous writes keep the synchronous path, so back-pressure is unchanged.
+
+  This library learned the realm-local lesson once already, from `instanceof Error`, which is why
+  `isErrorLike` exists. The same mistake sat one file away.
+
+### Breaking
+
+- **`ILogDestination` declares `void | PromiseLike<void>` instead of `void | Promise<void>`,** on
+  `write`, `onInit`, `onRegistryReady` and `onShutdown`. The fix above handles a thenable at runtime;
+  the public type still forbade one, so a TypeScript consumer could not return the very shape the
+  release claims to support — the tests needed casts precisely because of that gap, and the casts are
+  gone.
+
+  **This is source-breaking for CALLERS, and an earlier draft of this note wrongly said it was not.**
+  Widening what an implementation may return necessarily narrows what a caller receives: `PromiseLike`
+  exposes only `then`, so code that called `.catch()` or `.finally()` on the result no longer type-checks.
+
+  The call has to be narrowed first, in both versions: `write` has always been able to return
+  `void`, so `.catch()` was never available on the bare call.
+
+  ```ts
+  const result = destination.write(payload)
+
+  // before — `result` narrowed to `Promise<void>`, so `.catch` was there
+  if (result !== undefined) result.catch(handle)
+
+  // after — it narrows to `PromiseLike<void>`; assimilate to get `.catch` back
+  if (result !== undefined) Promise.resolve(result).catch(handle)
+  ```
+
+  There is no type that gives implementations the freedom and callers a full `Promise`; this release
+  chooses the implementations, because a destination that cannot be written in the first place is the
+  worse failure.
+
+### Fixed
+
+- **A throwing `minLevel` getter could abort application bootstrap.** `effectiveLevelOf` reads the
+  consumer-defined `minLevel`, and `readonly minLevel?: LogLevel` does not stop it being a getter.
+  It is read on BOTH branches of the init loop — including inside the catch that exists so a failing
+  destination cannot stop the application from starting — so a throw there took the app down at
+  start-up and stranded every destination after it. The read is guarded inside `effectiveLevelOf`,
+  which covers every call site at once, and falls back to the module level: what a destination
+  without a `minLevel` gets anyway. Same defect class as the `name` getter, in the sibling property.
+
+  The registry was not even the FIRST reader. `pino-factory` builds the multistream entry from
+  `destination.minLevel` at provider-construction time, outside any guard and before any lifecycle
+  hook — so a hostile getter failed the factory and the application never started, earlier than any
+  fail-soft path could contain it. Found by sweeping every consumer-defined property read in
+  `src/server` rather than by fixing the site that was reported: eight of the nine were already
+  inside a `try`, and that ninth one made the registry fix unreachable in practice. Both sites share
+  one `safeMinLevel` now, and it PINS the first answer per destination.
+
+  Guarding the read stops the throw but not the DISAGREEMENT. Nothing makes the getter pure, and two
+  independent consumers read it: the factory, which fixes the multistream entry's level, and the
+  registry, which records the same destination's health level. A stateful getter answering `info` to
+  one and `error` to the other would let an `error` sink be credited with covering held `info`
+  entries, and a buffering destination would discard its only copy of them — a loss path, not an
+  inconsistency. Pinning makes the two agree by construction; `readonly minLevel?: LogLevel` says it
+  should not change anyway.
+
+- **The shutdown reporter could be made to forge a second stderr record.** Its guard used
+  `escapeControlCharacters`, which preserves newlines ON PURPOSE because a stack trace is
+  legitimately multi-line — but it was applied to `cause.message` when no stack existed, and to any
+  non-Error thrown value. A destination rejecting with `'failed\n[forged entry]'` therefore wrote a
+  second raw line that an operator reads as a genuine record. The two escapers are not
+  interchangeable: a stack goes through `escapeControlCharacters`, a message or a non-Error value
+  through `toSingleLineMessage`. The regression asserts the emitted text is ONE line, not merely that
+  an escape appears in it.
+
+- **A failing `onShutdown` could abort the teardown of every destination behind it.** The registry
+  built its stderr report by coercing the thrown value ABOVE the guard: reading `stack`/`message` on
+  an `Error` with hostile getters, or `String(cause)` on a value with a throwing `Symbol.toPrimitive`,
+  throws from inside the very `catch` that exists to keep one bad sink from mattering. The throw then
+  propagated out of `onApplicationShutdown`, and every destination still queued lost its flush —
+  turning one destination's bad error object into lost entries everywhere.
+
+  The coercion is now inside its own guard, falls back to `UnknownError` when the value cannot be
+  read at all, and the text is escaped like every other terminal-bound path. The regression test
+  asserts that the SECOND destination still shuts down, not merely that nothing threw: continuing the
+  teardown is the property that matters. Reverting the guard makes it fail — verified, not assumed.
+
+  **The same gap existed at every other reporting call site, and the first fix only closed one of
+  them.** `reportWriteFailure(destination.name, …)` in the write adapter and `reportInitFailure`
+  in the registry both read the name at the call site — inside the catch — so a hostile getter turned
+  a contained write failure into an unhandled rejection, and a failed `onInit` into an aborted
+  bootstrap, contradicting the comment one line above it that the library never throws to abort boot.
+  A shared `safeDestinationName` now performs that read under a guard, and every reporter uses it.
+
+  The destination's own `name` is read inside a guard as well, and a separate one:
+  `readonly name: string` does not stop a consumer implementing it as a getter, and reading it at the
+  call site would have left it inside the `catch` with the same cost. That second gap was found by
+  reviewing the fix for the first — the correction had reproduced the defect one layer up.
+
+  The control-character escaping on this path is now asserted rather than assumed. Every shutdown
+  test used plain ASCII, so replacing the escaper with an identity function would have left them all
+  green — a 100% mutation score does not cover a transformation no test observes. The new case emits
+  a stack containing an ANSI escape and a C1 character, and asserts that those are neutralized while
+  the stack's own newlines survive.
+
+  Found by a review comment on the DOCUMENTATION examples. The examples mirrored the implementation
+  faithfully, which is exactly why the defect was worth chasing back into `src/`: a guarded writer
+  never guarded the arguments handed to it, and that had been true in three places.
+
+### Documentation
+
+- **Snippets that referenced symbols which were not there are now caught by a parser, not by
+  eye.** Five review rounds each found another documented example using `safeMinLevel`,
+  `LOGGER_OPTIONS_TOKEN`, `PREVIEW_LENGTH`, `this.reportShutdownFailure` or an outright invented
+  `RESERVED_LOG_KEYS.LOGGER_DESTINATION_SHUTDOWN_FAILED` with nothing to resolve them. `pnpm
+check:docs` parses every TypeScript block — both `ts` and `typescript` fences — and fails on
+  three things: a symbol this package declares in `src/` used without being imported or declared,
+  a `this.member` the class shown does not define, and a `CONSTANT.KEY` the real constant does not
+  have. It reads the syntax tree rather than the text, so a name in a comment is a mention and not
+  a use. It runs in CI and in `prepublishOnly`, because a gate nothing executes is not a gate.
+
+  The 43 pre-existing cases in the planning documents sit in a baseline that shrinks and does not
+  grow: regenerating writes the intersection with what still reproduces, so a defect introduced in
+  the same edit is never adopted, and an entry that stops reproducing fails too rather than
+  lingering. Widening what the check looks at is the one case where the list legitimately grows,
+  and it takes a separate `--adopt-new` flag so that decision is stated rather than taken
+  silently.
+
+- **The destinations guide credited the wrong component with building the fan-out.** It said
+  `DestinationRegistry` wraps each destination into the `pino.multistream` array; that happens in
+  `buildPinoInstance` (`src/server/pino-factory.ts:574`), and the registry owns the lifecycle hooks
+  and the health record instead. The mistake was not only prose — the snippet's relative imports
+  were written as `../utils/...`, which resolve only from `services/`, so following the guide gave
+  paths that do not exist from where the code actually lives.
+
+- **The specification gave the wrong reason for reporting init failures on stderr.** It said Pino
+  was not yet wired at that point. It is — the instance is built during provider construction,
+  which is why the same method emits `LOGGER_BOOTSTRAP_OK` through the logger a few lines later.
+  The actual reason is the fan-out: the logger writes to the very set containing the sink that
+  just failed. An implementer reading the old text would have inferred the wrong lifecycle order.
+
+- **The shipped `README.md` no longer teaches the old contract.** Its `ILogDestination` reference
+  still declared `Promise<void>` on `write`, `onInit` and `onShutdown`, and omitted `onRegistryReady`
+  entirely — so the one document most consumers read described types incompatible with the interface
+  and hid a hook from anyone who buffers. It ships inside the package, which makes it the copy that
+  matters most.
+
+- **Overflow was only reported when a later flush failed.** A request that stalls long enough to
+  overflow the cap and then SUCCEEDS runs no catch at all, so the discarded entries were lost with
+  nothing said — the opposite of the policy stated one paragraph above. Both examples report the
+  dropped count on every settlement, not only from the failure path.
+
+- **A guarded WRITER does not guard the arguments handed to it.** The documented adapters called
+  `writeStderrSafely` with an interpolated `${String(err)}`, and that coercion runs before the call:
+  an unknown rejection value with a hostile `Symbol.toPrimitive`, or an `Error` whose `message` getter
+  throws, takes the handler down before `callback()` — an unhandled rejection produced from inside the
+  containment. The previous release note credited the safe writer with a protection it never had.
+  Every documented adapter now uses `reportDestinationFailure`, which does the coercion inside its own
+  guard and escapes control characters.
+
+- **A raced timeout is not a timeout.** The database example briefly carried a `Promise.race`
+  deadline, which settles the AWAIT without cancelling the query: the batch would be requeued while
+  the original `createMany` was still running, the next flush would start a second one, and a slow
+  database would accumulate concurrent inserts of the same batch — duplicates, not just delay. The
+  bound belongs at the driver, where it aborts the statement server-side (`statement_timeout` on the
+  connection string), and the example says so instead of demonstrating a race. The HTTP example keeps
+  `AbortSignal.timeout`, which does cancel.
+
+- **Retaining a failed batch forever is a memory leak.** Requeueing on failure while `write` keeps
+  appending is an unbounded queue: a sustained outage ends in an OOM, which loses every held entry
+  AND the application. Both worked examples now cap the buffer and drop the OLDEST beyond it — the
+  newest entries describe the incident — and report the dropped count rather than discarding
+  silently. A destination that cannot lose anything is told to use a durable spool, not a buffer.
+
+- **Four defects in the specification's own examples**, all from wiring `DestinationHealth` through
+  them: the factory call site still passed the old three arguments, so a `LogLevel` landed where the
+  health tracker was expected; the adapter never checked `isFailed`/`shouldRescue`, though the
+  fan-out builds a stream for every registered destination and that branch is what keeps a
+  failed-init sink out of it; the new provider dependency omitted the explicit `@Inject` this
+  repository requires because tsup strips decorator metadata; and the shutdown loop contained
+  failures with `Promise.allSettled` while reporting none of them, contradicting the guarantee the
+  destination examples state.
+
+- **The consumer-facing stderr guard reintroduced a defect the library had already fixed.** It
+  remembered `guarded = true` in a boolean, which goes stale the moment anything else removes the
+  listener — a test doing cleanup is enough — and every later EPIPE is uncaught again. It also
+  treated ANY existing `'error'` listener as proof the stream was safe, though a consumer's handler
+  may rethrow. `safe-stdio.util.ts` arrived at the right shape after exactly this: check whether OUR
+  listener is in `stream.listeners('error')`, and only ever add. The documented helper now does the
+  same.
+
+- **The Loki example discarded its batch on every HTTP error.** `fetch` rejects only on a
+  network-level failure; 401, 429 and 500 resolve normally, so the retention path added for it never
+  ran on the failures a log sink actually sees. It checks `response.ok` and throws now. Its timer
+  also still detached the flush directly, which the same commit had fixed only in the Postgres
+  example.
+
+- **A background flush was invisible to shutdown.** Both examples now chain background flushes into
+  one tracked promise and `onShutdown` awaits it before the final drain: a flush that fails requeues
+  its batch, and without the await those entries sit in a buffer nobody drains again.
+
+- **The specification formatted failure reports inline instead of using `reportDestinationFailure`.**
+  An `Error` with a throwing `message` getter — or a non-Error with a throwing coercion hook — makes
+  an inline `String(cause)` throw from inside the very handler that exists to contain failures, and
+  the inline form also skips the control-character escaping applied to remote-derived text. All four
+  reporting sites in the document now go through the helper that does the coercion inside its own
+  guard.
+
+- **The batch-retention fix introduced a crash path of its own.** Making `flush()` rethrow is right
+  for the shutdown caller, which awaits it — and wrong for the two background callers, which detach
+  the promise. A detached rejection is an unhandled rejection, which terminates the process on
+  Node 24: a loss path traded for a crash path, in the same commit that closed the loss. The two
+  detached call sites now go through a `flushInBackground()` that swallows what `flush` already
+  retained and reported, while `onShutdown` still awaits `flush` directly, where the rejection has
+  somewhere to go.
+
+- **The Loki example was still discarding its batch** — the same defect as the Postgres one, one
+  section earlier, with `// Fail soft` written over it. Fail-soft means not crashing the host; it
+  never meant dropping the entries. It retains and reports now, and the guarded stderr helper both
+  examples use is defined once, ahead of its first use, instead of being named and left undefined.
+
+- **The documented adapters recorded a failure only after the promise rejected**, leaving the
+  in-flight window the implementation closes with `markWritePending`/`markWriteSettled`. Readiness
+  can be computed while a write is still pending; without the pending count it reads as silent
+  success, and a buffering sink discards its copy moments before that write rejects.
+
+- **The specification's registry example referenced members it did not declare** — `this.active`,
+  `this.health`, `this.effectiveLevelOf` — so the authoritative document showed an implementation
+  that would not compile. It now declares them, and its shutdown loop iterates the ACTIVE subset
+  rather than every registered destination, matching the implementation: a sink whose `onInit`
+  failed may never have acquired what `onShutdown` would close.
+
+- **The documented adapters reported a failed write but never RECORDED it.** The prose added with
+  them says the adapter "contains it, records it and reports it"; the examples did the first and the
+  third. Recording is the half that prevents the loss: without `markWriteFailed`, readiness still
+  counts the sink as having taken the entry and another destination may discard the copy it was
+  holding. The examples now take the health tracker and mark the sink before reporting.
+
+- **The worked Postgres destination still lost a batch, in the example that demonstrates not losing
+  one.** Removing the `try/catch` from its `write` was not enough: the flush it triggers runs after
+  that `write` returned, and `flush()` ended in `catch { /* fail-soft */ }`, discarding every entry
+  in the batch while the adapter had already recorded them as taken. A background flush is the one
+  failure a destination must handle itself — so it now returns the batch to the buffer, reports it,
+  and rethrows so the caller sees it. The stderr helper it uses is written out in full, because the
+  library's guarded one is internal and a consumer cannot import it.
+
+- **The specification contained two incompatible lifecycle contracts.** The `onRegistryReady`
+  guarantee added above says the hook runs for every registered destination; the `DestinationRegistry`
+  example further down truncated the registered list to the survivors of `onInit` and never called
+  the hook at all. The example now keeps the registered set, writes only to the active subset, and
+  awaits the hook for every destination with per-destination isolation.
+
+- **The guide told destinations to swallow their own write failures — a loss path, in the document
+  that defines the fail-soft contract.** "Catch every error in `write` and log it via
+  `process.stderr.write`" reads as prudence and is the opposite: a swallowed failure looks like a
+  successful write from outside, so `markWriteFailed` never runs for that sink, readiness can then
+  credit it with entries it dropped, and ANOTHER destination discards the held copies it was keeping.
+  The entry stops existing anywhere — exactly the outcome this release exists to prevent. The advice
+  is now to let the failure reach the adapter, which contains it, RECORDS it and reports it. Two
+  anti-pattern entries carried the same instruction, and the worked Postgres destination practised
+  it; all three are corrected.
+
+- **Every reporter in the documented examples wrote to `process.stderr` directly.** The guide
+  explains, three sections earlier, that a closed pipe reports EPIPE asynchronously and kills the
+  process — which is why `safe-stdio.util.ts` exists. The containment helpers added one commit ago
+  ignored that and would have traded a contained destination failure for an uncaught exception. The
+  library's own paths now route through `writeStderrSafely` in every example. The consumer-facing
+  examples do not, because that helper is internal and unexported; they point at the EPIPE note
+  instead, which is the honest instruction for code outside this package.
+
+- **The technical specification did not state that `onRegistryReady` runs for a destination whose own
+  `onInit` rejected.** It runs for every registered destination, verified against
+  `notifyRegistryReady`, and a sink that failed to initialize is exactly the one most likely to be
+  holding entries it now has to resolve. Left unstated, an implementer would reasonably assume the
+  opposite and strand them.
+
+- **The drain contract described a return value `_write` does not have.** It said the adapter signals
+  backpressure by `_write` returning `false`; `_write` returns `void`. Deferring its callback is the
+  actual mechanism — the chunk stays in flight, the internal buffer grows, and it is the PUBLIC
+  `writable.write()` that returns `false` at `highWaterMark`. The conclusion the section drew was
+  right and the model under it was not, which is the kind of text a destination author reasons from.
+
+- **The documented adapter examples contradicted the fail-soft contract they were illustrating.**
+  They routed a failed write into `callback(err)`, and the guide listed that as an advantage — "errors
+  are propagated as a callback err (not as an exception that crashes the app)". A `Writable` given an
+  error in its callback emits `'error'`, which with no listener terminates the host. The production
+  adapter has always done the opposite, and says so in a comment one line above the code: contain the
+  failure, report it on stderr, complete the write as successful. Every example, and the two prose
+  lines that recommended the pattern, now match it.
+
+- **Every documented `destinationToStream` example branched on `result instanceof Promise`** — the
+  exact defect fixed above, in the snippets that teach people how to write a destination. A reader
+  implementing against the guide, the specification or the plan documents would have reproduced the
+  escaped rejection and the lost entry. All of them now branch on `undefined` and assimilate with
+  `Promise.resolve`.
+
+  These two were found only because a review kept pulling the same thread. Correcting the interface
+  and the four excerpts that restate it still left the README and every worked example behind: a
+  contract lives in more places than the ones that quote its signature.
+
+  So the rule is now a gate rather than a habit. `check:published` compiled only README blocks that
+  **import** the package, on the reasoning that naming the API is not a claim about it — which left a
+  block that _re-declares_ an exported type unchecked, and that is exactly where the README drifted.
+  It now compiles those too, with three assertions because each covers what the previous one cannot:
+  mutual assignability catches a changed return type; key parity catches an omitted member, which is
+  assignable in both directions and is how the absent `onRegistryReady` survived; per-member type
+  identity catches a changed PARAMETER, which stays bivariant even under `strictFunctionTypes`.
+
+  Both of the later assertions were added because a measured version of the gate let a real drift
+  through: the first passed a README declaring `write(payload: unknown)`, and the second — comparing
+  members as `T[K]` — passed one that dropped `readonly`, because indexed access discards property
+  modifiers. Each hole was reproduced against the version that had it before being closed, and each
+  assertion is verified the same way: introduce the drift, watch the gate name it, restore.
+
+- **`heldEntriesDeliveredElsewhere` is documented as best-effort rather than as proof.** The JSDoc
+  said `true` requires no write still in flight, which reads as complete accounting — while the
+  `1.2.8` note already admitted that writes queued inside the `Writable` adapter are invisible until
+  `destination.write()` is called. Both statements shipped in the same release, and they contradict
+  each other.
+
+  Calling it best-effort was not enough on its own: the surrounding prose still framed the decision
+  as "discard only on proof", which is the same contradiction one paragraph up. The contract is now
+  stated as what it is — a **deduplication signal**, where `true` means the smaller risk is dropping
+  the held copy, not that the entry is safe. The library's own destinations dedupe on it because a
+  duplicated boot line is a smaller harm than a lost one; a destination that cannot tolerate any loss
+  is told to ignore the flag and always emit. The guide, the specification and the JSDoc now say the
+  same thing, so a reader meets one story instead of three.
+
+  Reframing the parameter was still not the end of it: `PrettyDevDestination` went on calling the
+  same value "a proven fact" in one comment and instructing the hook to "discard only what is proven
+  delivered" in another, and this changelog kept the word too. One class saying both things is worse
+  than either alone — "proven" invites a destination author to discard with full confidence, which is
+  precisely the loss this release refuses. The vocabulary is now one word everywhere: a signal, with
+  the queued-write blind spot named where the decision is taken.
+
+## 1.2.8 - 2026-08-15 (merged, never published)
+
+### Fixed
+
+- **A pretty destination registered alongside another sink no longer prints every boot entry twice.**
+  The fan-out hands each entry to every registered destination, so entries buffered before
+  `PrettyDevDestination.onInit` had ALSO been delivered to the co-destination. When the pretty sink
+  then failed to initialize, it drained its buffer raw to stdout, producing a second copy of every
+  boot line. Measured on the supported
+  `[DefaultStdoutDestination(), PrettyDevDestination()]` pair: two occurrences of one entry.
+
+  **You were affected only if you registered pretty ALONGSIDE another destination** — the shape a
+  derived backend reaches by adding an HTTP or file sink beside pretty for local development. A
+  one-element `destinations` list is structurally immune, because the option REPLACES the default
+  sink rather than adding to it, so pretty-alone and stdout-alone can never produce the pair.
+  Worth stating explicitly: "duplicated boot lines" is not a symptom from which a reader would guess
+  the triggering configuration.
+
+  The destination could not decide this alone: at `onInit` failure it has no way to know what became
+  of the entries. The decision moves to a new optional `ILogDestination.onRegistryReady`, which the
+  registry calls once every `onInit` has settled.
+
+  **The policy is: prefer a duplicated line over a lost one.** The hook carries ONE signal — whether
+  another live sink appears to have accepted everything this destination accepted — and the
+  destination dedupes only on that. `true` requires all of: another destination, initialized, at or
+  below this level, with no write failure and nothing still in flight. Anything less certain reads as
+  `false`, and the entries are emitted.
+
+  An earlier draft handed over three hints and let the destination judge. Every judgement had a
+  losing branch, and review found them one at a time: trusting "a sink survived" lost entries to a
+  sink at a higher level; trusting the level lost them to a sink that was itself the asker; then to
+  one whose writes were throwing; then to one whose write had not settled yet. Collapsing to a single
+  signal is what removed the class, rather than the four instances.
+
+  In the configuration that motivated this — pretty beside `DefaultStdoutDestination` — nothing
+  duplicates: the stdout sink is live at the same level, the signal reads `true`, and the held copies
+  are dropped. Duplication is left wherever the signal cannot be given, which is exactly where
+  discarding would risk silence.
+
+  **One narrow gap is known and left open rather than papered over, and it is the reason the value is
+  a signal and not a proof.** The accounting covers writes this library has SEEN — resolved, rejected,
+  or in flight. A write still queued inside the `Writable` adapter, behind a slow async destination
+  that has not been called yet, is invisible to it: the signal can read `true` while that entry has
+  not reached the sink. It will normally arrive (it is
+  queued, not lost); the residual risk is a queued write that later fails, and the entry existed only
+  in a buffer that was discarded on the strength of a different sink's record. Closing it means
+  readiness waiting for every pre-ready stream to drain, which is a larger change than the boot-time
+  cosmetic defect this whole path exists to fix. Stated here so a consumer can weigh it, rather than
+  implied by a guarantee that does not quite hold.
+
+  **One case is NOT deduplicated, and the first draft of this note claimed it was.** A shutdown that
+  happens before the registry's `onModuleInit` ran — the application aborting mid-bootstrap — still
+  drains the buffer raw. The multistream is wired by a provider factory while NestJS assembles the
+  graph, so entries can already have reached a co-destination by then, but the readiness hook has not
+  run and the destination has no way to learn that. It drains, because between a duplicated boot line
+  and a lost one this library picks the duplicate. Narrowing the claim rather than widening the fix:
+  making that path registry-aware would require the registry, which by definition has not run.
+
+  Reported by Copilot on the `1.2.6` pull request, in a review body rather than as an inline
+  comment — see the note below.
+
+### Security
+
+- **`messageFormat` interpolates every placeholder except `{msg}` raw, and that reopens terminal
+  log forging.** This library normalizes line separators and control characters in `msg` and in the
+  stack, never in metadata — escaping data would mean rewriting what a consumer asked to be logged.
+  `pino-pretty` substitutes whatever the field holds, so a newline in an interpolated field splits
+  one entry into two, and the second reads like a genuine record. Measured with a newline in
+  `context`:
+
+  ```
+  lines produced by ONE entry: 2
+    1: "[10:35:14.484] INFO: [Auth"
+    2: "[10:00:00.000] INFO: FORGED admin promoted] real entry …"
+  ```
+
+  The option stays — rejecting non-`msg` placeholders would remove the feature, and the interpolation
+  happens inside `pino-pretty` where this library cannot escape it. What changes is that the JSDoc
+  now says so, and the README no longer recommends the pattern without the warning: interpolate only
+  fields your own code sets, never one carrying user input.
+
+### Documentation
+
+- **`hideObject` is scoped to the pretty destination, not to the entry.** The doc said a field hidden
+  there "is not visible anywhere", which holds only when pretty is the sole destination. Registered
+  alongside another sink, that sink still receives the complete entry.
+
+- **The `safe-stdio` specs no longer leave `'error'` listeners on the shared process streams.** They
+  did so deliberately, with a rationale that the same pull request had already made stale: cleanup
+  had once broken the guarantee under test because the module remembered which streams it guarded,
+  and `ensureGuarded` was then changed to inspect the actual listener list. Every
+  `isolateModulesAsync` load installs a distinct handler, so the file accumulated one per case on a
+  stream that outlives the suite — where a later spec asserting an unhandled stream error propagates
+  would be silently satisfied. Each block now restores its exact baseline, and asserts that it did.
+
+- **A process note, recorded because it cost two releases.** Copilot reports some findings inside a
+  `Suppressed comments` block in the review BODY, where they never become review threads. Checking
+  `reviewThreads` for `isResolved == false` — the documented way to avoid trusting the page — reports
+  zero open and is telling the truth about threads while missing these entirely. Ten such findings
+  sat unread on the `1.2.6` pull request, including the two fixed above. Reviews are now read
+  alongside threads.
+
+- **A hand-built `PinoLoggerService` is not this library's behaviour, and the constructor doc used to
+  invite one without saying so.** `new PinoLoggerService(pino({...}, sink))` does not throw — the
+  parameter default exists for exactly that — but the Pino instance you built has none of the wiring
+  `buildPinoInstance` installs, and the omissions are silent. No `err` serializer, so the `cause`
+  chain **disappears entirely**: no marker, no warning, and a shape that reads as "the field was
+  never set". Also no name-based redaction, no trace-context mixin, no size bound.
+
+  Found the honest way: a consumer hand-built one to check whether a `cause` carried its `code`,
+  measured absence, and went to read the built `dist` before reporting it — where they found their
+  harness was the cause. The doc now names what such an instance lacks and points at booting the
+  module for a faithful one.
+
+- **What redaction covers, stated as a boundary rather than left to be inferred.** It matches field
+  NAMES, not values: a secret under a covered name is censored at any depth, and the same secret
+  embedded **inside a string** under an uncovered name travels intact. Scanning values for
+  secret-shaped text would mean rewriting what a consumer asked to be logged, wrong in both
+  directions and silently — so the boundary is real and belongs in the open. It matters more since
+  `1.2.7`: preserving an error's own fields at every depth makes whatever a `cause` carries more
+  visible, including what should not be there.
+
+  The README also now says which redactor governs what — `redactStrategy` covers the consumer's
+  payload, their child bindings and any serializer they supply; the built-in `err` serializer is the
+  library's own output and is always name-walked, because `fast-redact`'s four-wildcard ceiling
+  cannot reach a serialized `cause` chain.
+
+- **The `1.2.7` notes used `a catch in main.ts` as the example, and it is the wrong one.** Not false
+  as a general statement — a handler that wraps and logs does exist — but it became the canonical
+  example of the motivating case, and for the consumer who reported that case it describes a path
+  that does not exist: their config validation rejects inside `NestFactory.create`, before the
+  logger is attached, and reports through `console.error` on stderr without touching the serializer.
+  A reader anchors on the example. Now "any handler that wraps what it caught before logging it".
+  Corrected in the README and in the `1.2.7` entry; the `v1.2.7` tag annotation is left as published,
+  since rewriting a published tag is worse than the imprecision it would fix.
+
 ## [1.2.7] - 2026-08-15
 
 ### Security
@@ -79,7 +586,8 @@ heading here.
 - **An error's own properties now survive at every depth of the `cause` chain, not just at the top.**
   `code`, `statusCode` and any domain field an application attaches were copied onto the error handed
   to the log call and **dropped the moment that same error was wrapped as someone else's `cause`** —
-  which is what a `catch` in `main.ts` does routinely. Measured on the published `1.2.6`:
+  which is what any handler that wraps what it caught does before logging it. Measured on the
+  published `1.2.6`:
 
   ```json
   {
@@ -1231,7 +1739,11 @@ published `dist/` is identical — no runtime behaviour changes for consumers.
 - Professional CI suite: `ci.yml`, `bench.yml`, `codeql.yml`, `scorecard.yml`,
   `release.yml`, Dependabot, and issue templates
 
-[Unreleased]: https://github.com/bymaxone/nest-logger/compare/v1.2.7...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-logger/compare/v1.2.9...HEAD
+[1.2.9]: https://github.com/bymaxone/nest-logger/compare/v1.2.7...v1.2.9
+
+<!-- 1.2.8 has no link: it was merged but never tagged, so there is no v1.2.8 to compare against. See its section above. -->
+
 [1.2.7]: https://github.com/bymaxone/nest-logger/compare/v1.2.6...v1.2.7
 [1.2.6]: https://github.com/bymaxone/nest-logger/compare/v1.2.5...v1.2.6
 [1.2.5]: https://github.com/bymaxone/nest-logger/compare/v1.2.4...v1.2.5

package/README.md

@@ -556,7 +556,8 @@ error, `statusCode` from an HTTP layer, whatever domain fields you attached —
 
 This matters because `code` is usually the field you alert on. Until 1.2.7 those properties survived
 only on the error handed to the log call and were dropped the moment the same error was wrapped as
-someone else's `cause` — which is what a `catch` in `main.ts` does routinely. They never shadow a
+someone else's `cause` — which is what any handler that wraps what it caught does before
+logging it. They never shadow a
 field the serializer derives, and they pass through the same name-based redaction and size bound as
 any other serializer output.
 
@@ -790,6 +791,7 @@ new PrettyDevDestination({
 })
 
 // Message only, with the context pulled back into the line.
+// See the messageFormat warning below before interpolating any other field.
 new PrettyDevDestination({
   view: { hideObject: true, messageFormat: '[{context}] {msg}' }
 })
@@ -804,7 +806,7 @@ new PrettyDevDestination({
 | `translateTime` | `'SYS:HH:MM:ss.l'`       | Or `false` for the raw timestamp                                             |
 | `colorize`      | `true`                   | ANSI colour                                                                  |
 
-> **`hideObject` hides it everywhere.** In pretty mode there is no JSON copy behind the rendering, because `destinations` **replaces** stdout — so a field hidden here, `logKey` included, is not visible anywhere. That is what the option is for; `messageFormat` is how you pull a specific field back.
+> **`hideObject` hides it from THIS destination.** Any other destination you registered still receives the complete entry — the option is display-only and scoped to the pretty renderer. When pretty is your **only** destination that scope becomes total: `destinations` **replaces** stdout, so there is no JSON copy behind the rendering and a hidden field, `logKey` included, is not visible anywhere. That is what the option is for; `messageFormat` is how you pull a specific field back.
 
 > **A dot in `ignore` means "nested path", so a field name that CONTAINS a dot must escape it.** This library emits `event.name` as a literal top-level key, so the obvious spelling hides nothing at all — `pino-pretty` looks for an `event` object with a `name` inside, finds neither, and says nothing. Measured on one entry with only the option changing:
 >
@@ -817,6 +819,16 @@ new PrettyDevDestination({
 
 The shape is exported as `PrettyViewOptions` when you want to build the view separately — it is this library's own interface, not a re-export of `pino-pretty`'s `PrettyOptions`, so type-checking without the optional peer installed still resolves.
 
+> **`messageFormat` interpolates every placeholder except `{msg}` raw — that can forge a terminal entry.** This library normalizes line separators and control characters in `msg` and in the stack, never in metadata, because escaping data would mean rewriting what you asked to be logged. `pino-pretty` substitutes whatever the field holds, so a newline in an interpolated field splits one entry into two and the second reads like a genuine record. Measured, with a newline in `context`:
+>
+> ```
+> lines produced by ONE entry: 2
+>   1: "[10:35:14.484] INFO: [Auth"
+>   2: "[10:00:00.000] INFO: FORGED admin promoted] real entry …"
+> ```
+>
+> Interpolate only fields your own code sets. Never one carrying user input — `{tenantId}`, `{userId}`, a header, a query value. If you need one of those visible, leave it in the record instead. That closes **this** path and no more: a metadata value is not safe terminal text either, since `JSON.stringify` escapes only C0 and emits DEL, the C1 range (U+0085 NEL included), U+2028 and U+2029 verbatim — see _One entry, one line_ below, where the same boundary is stated. Only `msg` and the stack carry that guarantee.
+
 > **`destination` is not exposed, by design.** The library owns where entries go — a redirected stream would route around the fan-out and the last-resort rescue above. It is absent from the type and applied after your options are merged, so it cannot be overridden from untyped JavaScript either.
 
 **The first entries of a boot are held, not lost.** The transform cannot exist until `onInit` — loading the optional peer is async — so everything NestJS emits while instantiating providers arrives before it. Those entries are buffered and then rendered through the transform in arrival order. If the peer is missing, the bound is reached, or the app shuts down before init, they are written as raw NDJSON instead: degraded, never dropped.
@@ -1043,6 +1055,21 @@ Trace context is never copied verbatim into a log entry. The OTel mixin reads th
 
 Every `write()` runs inside a try/catch. A destination that throws or rejects produces a `LOGGER_DESTINATION_WRITE_FAILED` line on `stderr` — never back through the logger, which would turn a broken sink into a write → log → write feedback loop — and the entry is dropped for that sink only. A destination whose `onInit()` rejects is reported as `LOGGER_DESTINATION_INIT_FAILED` and excluded from the shutdown sequence without blocking boot; it stays in the write fan-out, where the same fail-soft wrapper contains it. A logging backend going down degrades logging — it never takes the application with it.
 
+### What redaction covers, and what it cannot
+
+Redaction here matches **field names**, not values. Under the default `redactStrategy: 'names'` a secret stored under a covered name is censored at any depth — under the legacy `'paths'` strategy the four-level `fast-redact` ceiling applies instead, and a deeper field is not covered. Either way, the same secret **embedded inside a string** under an uncovered name travels intact. Measured:
+
+```json
+{
+  "password": "[REDACTED]",
+  "renderedBody": "Hi Ana, your reset code is 481920. Expires in 10 minutes."
+}
+```
+
+There is no name rule that reaches the second one, and scanning inside values for secret-shaped text would mean rewriting what you asked to be logged — wrong in both directions, silently. **The boundary is yours to hold:** do not put rendered bodies, raw provider responses or whole request payloads into a field, and be aware that attaching an upstream error as `cause` carries whatever that error carries. Since 1.2.7 preserves an error's own fields at every depth of the chain, a cause that quotes something it should not quote is now more visible, not less.
+
+`redactStrategy` governs **your** payload — the record you log, your child bindings, and the output of any serializer you supply. The built-in `err` serializer is the library's own output and is always name-walked, including under `'paths'`, because `fast-redact`'s four-wildcard ceiling cannot reach the depth a `cause` chain serializes to.
+
 ### A closed pipe does not kill the process
 
 `node app | head` closes the read end of stdout while the application is still writing. The stream reports that as `EPIPE` **asynchronously**, through its `'error'` event, after `write()` has already returned — so a `try/catch` around the write catches nothing, and because Node attaches no default handler to `process.stdout`, the emit becomes an uncaught exception and the process dies. Measured, not assumed: `0` listeners, no synchronous throw, `UNCAUGHT:EPIPE`, exit 42.
@@ -1297,9 +1324,13 @@ interface ILogDestination {
   readonly name: string
   readonly minLevel?: LogLevel
   /** `payload` is a newline-terminated JSON entry, UTF-8 encoded — not an object. */
-  write(payload: string): void | Promise<void>
-  onInit?(): Promise<void>
-  onShutdown?(): Promise<void>
+  write(payload: string): void | PromiseLike<void>
+  onInit?(): void | PromiseLike<void>
+  /** Called once after EVERY destination's `onInit` settled. Only useful if you buffer. */
+  onRegistryReady?(status: {
+    readonly heldEntriesDeliveredElsewhere: boolean
+  }): void | PromiseLike<void>
+  onShutdown?(): void | PromiseLike<void>
 }
 ```