@bymax-one/nest-logger 1.2.7 → 1.3.0

package/CHANGELOG.md

@@ -11,6 +11,568 @@ heading here.
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-08-18
+
+### Fixed
+
+- **A frozen `Error` lost every field, including its own message.** A consumer that freezes its
+  errors — deliberate and documented practice, so nobody mutates an issue list after the throw —
+  hands over properties that are neither writable nor configurable. The redactor's clone inherited
+  those descriptors, and rewriting any key whose walked value is a fresh object (a censored secret,
+  or simply the structural copy the walk makes of a nested array) could not redefine it. That
+  failure reached the fail-closed guard and dropped the **whole** record, so the entry became
+  `_redactionFailed: true` and nothing else — total silent loss on the error that crashed the
+  process, which is the one entry worth logging.
+
+  A frozen error carrying only scalars never showed it, because redefining a property with the same
+  primitive succeeds; it took a nested object to expose it. Reported against 1.2.7 by a consumer and
+  reproduced unchanged on 1.2.9.
+
+  The clone is transient — built, serialized, discarded — so it is now built with relaxed
+  descriptors and the write always lands. **The caller's error is never touched**, and freezing
+  remains the caller's guarantee about the caller's own object.
+
+  A non-configurable secret is now **censored** rather than dropped: same protection, without
+  losing the surrounding fields. The frozen error also keeps its **stack** again — V8 exposes it as
+  an own property bound to the original's internal state, so the clone pins a resolved copy, and on
+  a frozen error that pin was failing silently too. The case that did NOT drop the record was
+  therefore already reaching the sink with its trace erased, which is the same defect wearing a
+  healthy face; a consumer measured that independently. `LOGGER_REDACTION_FAILED` is unchanged for the case it was written
+  for — a record the walk cannot READ, such as a throwing getter or a hostile proxy.
+
+### Documentation
+
+- **The limit of field-based redaction now ships.** A value interpolated into the message has no
+  field name for any strategy to match — not an uncovered one, none — so no configuration closes
+  that gap and the rule is "a value that matters is a field, not text". It was stated only in
+  `docs/OBSERVABILITY-CONTRACT.md`, which is not in `files`: it reached whoever had the repository
+  and nobody who installs from npm. The decision it governs is made at a call site in a derived
+  backend whose only copy of this contract is what the registry delivers, so it is in the README's
+  security model now, beside the case it sharpens — that one covers a secret inside a field's
+  **value**, this one a value with no field at all.
+
+- **The `minLevel` entry below, under 1.2.9, now names the direction of its change.** The behaviour
+  changed in that release and its record stays there; what shipped here is the paragraph explaining
+  what upgrading does. A sink configured with an unrecognised level was silent and starts delivering
+  at the module level, which arrives as a step change in ingestion cost and reads as a noise
+  regression unless the note says which way it moves. Two consumers asked for this independently.
+
+## [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.
+
+  **On upgrade this changes your log volume, upward, and it will not look like a fix.** A sink
+  that was configured with an unrecognised level and was therefore silent starts delivering at
+  the module level the moment you install this version. Read as a graph, that is a step change in
+  ingestion cost arriving with a patch; read correctly, it is entries that were always supposed
+  to be delivered and never were. If you see one, check that destination's `minLevel` before
+  treating it as a regression — the value has to be one of `'trace'`, `'debug'`, `'info'`,
+  `'warn'`, `'error'` or `'fatal'`. `'verbose'` and `'log'` are NestJS level names, not Pino
+  ones, and are the likely culprits for anyone arriving from `LoggerService`.
+
+- **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 +641,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 +1794,12 @@ 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.3.0...HEAD
+[1.3.0]: https://github.com/bymaxone/nest-logger/compare/v1.2.9...v1.3.0
+[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