@bymax-one/nest-logger 1.2.7 → 1.2.9

package/dist/server/index.cjs

@@ -354,10 +354,30 @@ function assignIfDefined(payload, key, value) {
 }
 exports.PinoLoggerService = class PinoLoggerService {
   /**
+   * **A hand-built instance is NOT this library's behaviour.** Constructing
+   * `new PinoLoggerService(pino({...}, sink))` directly works in the sense of not
+   * throwing, and the parameter default below 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 an `Error` is serialized by Pino's default.
+   *     The `cause` chain disappears ENTIRELY — no marker, no warning, and a
+   *     `cause` that reads as "the field was never set";
+   *   - **no name-based redaction** of serializer output or child bindings;
+   *   - **no trace-context mixin**, so `requestId` / `tenantId` / OTel ids are
+   *     absent;
+   *   - **no size bound**, so nothing is truncated.
+   *
+   * That matters most for tests, which is the use this doc used to invite without
+   * qualification: a consumer wrote one to check whether a `cause` carried its
+   * `code`, measured absence, and nearly filed it against this library. The
+   * absence was their harness. For a faithful harness, boot the module (or use
+   * `BymaxLoggerModule.forRoot` in a testing module) rather than hand-building.
+   *
    * @param pino - The wrapped Pino instance.
    * @param redact - The DEFAULT-coverage redactor, applied to `child()` bindings.
-   *   Defaults to the identity so a hand-built instance (benchmarks, unit tests)
-   *   still works; the module always injects the configured one.
+   *   Defaults to the identity so a hand-built instance still works; the module
+   *   always injects the configured one.
    */
   constructor(pino2, redact = (value) => value) {
     this.pino = pino2;
@@ -1097,9 +1117,35 @@ function reportDestinationFailure(logKey, name, cause, msg) {
   } catch {
   }
 }
+function safeDestinationName(destination) {
+  try {
+    return String(destination.name);
+  } catch {
+    return "unknown";
+  }
+}
+function isLogLevel(value) {
+  return LOG_LEVEL_PRIORITY.includes(value);
+}
+var resolvedMinLevels = /* @__PURE__ */ new WeakMap();
+function safeMinLevel(destination) {
+  if (resolvedMinLevels.has(destination)) {
+    return resolvedMinLevels.get(destination);
+  }
+  let resolved;
+  try {
+    const read = destination.minLevel;
+    resolved = isLogLevel(read) ? read : void 0;
+  } catch {
+    resolved = void 0;
+  }
+  resolvedMinLevels.set(destination, resolved);
+  return resolved;
+}
 
 // src/server/utils/destination-to-stream.ts
-function reportWriteFailure(name, cause) {
+function reportWriteFailure(destination, cause) {
+  const name = safeDestinationName(destination);
   reportDestinationFailure(
     RESERVED_LOG_KEYS.LOGGER_DESTINATION_WRITE_FAILED,
     name,
@@ -1119,7 +1165,8 @@ function destinationToStream(destination, health) {
     decodeStrings: false,
     write(chunk, _encoding, callback) {
       const onFailure = (cause) => {
-        reportWriteFailure(destination.name, cause);
+        health.markWriteFailed(destination);
+        reportWriteFailure(destination, cause);
         callback();
       };
       try {
@@ -1132,10 +1179,20 @@ function destinationToStream(destination, health) {
           return;
         }
         const result = destination.write(payload);
-        if (result instanceof Promise) {
-          result.then(() => callback(), onFailure);
-        } else {
+        if (result === void 0) {
           callback();
+        } else {
+          health.markWritePending(destination);
+          Promise.resolve(result).then(
+            () => {
+              health.markWriteSettled(destination);
+              callback();
+            },
+            (cause) => {
+              health.markWriteSettled(destination);
+              onFailure(cause);
+            }
+          );
         }
       } catch (cause) {
         onFailure(cause);
@@ -1580,7 +1637,11 @@ function buildPinoInstance(options, logContext, destinations, health) {
     }
   };
   const streams = destinations.map((destination) => ({
-    level: destination.minLevel ?? options.level,
+    // Guarded: this runs at provider construction, BEFORE any lifecycle hook, so a
+    // consumer implementing `minLevel` as a throwing getter would fail the factory
+    // and the application would never start — earlier than any fail-soft path can
+    // contain. Unreadable and absent give the same answer: the module level.
+    level: safeMinLevel(destination) ?? options.level,
     stream: destinationToStream(destination, health)
   }));
   return pino__default.default(pinoOptions, pino__default.default.multistream(streams));
@@ -1590,24 +1651,91 @@ var DestinationHealth = class {
     /** Destinations whose `onInit()` rejected. Identity-keyed, not name-keyed. */
     this.failed = /* @__PURE__ */ new Set();
     /**
-     * Whether ANY destination initialized successfully.
+     * Destinations that initialized, each with its effective level as an index into
+     * {@link LOG_LEVEL_PRIORITY}.
+     *
+     * Keyed by identity rather than reduced to a flag or a minimum, because the
+     * question a buffering destination asks is "did SOMEONE ELSE receive what I
+     * received?" — and a minimum cannot exclude the asker. A destination that is
+     * itself the only healthy sink would otherwise be told its held entries were
+     * delivered elsewhere, and discard its only copies.
+     *
+     * The level matters for the same reason it does everywhere here: `pino.multistream`
+     * filters per stream, so "alive" and "received what I received" are different
+     * facts.
+     */
+    this.healthy = /* @__PURE__ */ new Map();
+    /**
+     * Destinations whose `write()` threw or rejected at least once.
      *
-     * A boolean rather than a count, deliberately: the only question ever asked of
-     * it is "is there somewhere to write?". Mutation testing made the point — a
-     * counter incremented with `+=` survived being flipped to `-=`, because
-     * `count === 0` means the same thing either way. A value whose arithmetic
-     * cannot be observed was not a counter, it was a flag wearing a number.
+     * Init health says a sink is LIVE; it does not say the sink accepted anything.
+     * A destination that throws on write is reported and skipped per entry, so
+     * inferring delivery from level alone would credit it with entries it dropped.
+     * Uncertainty drains, so any write failure disqualifies it as proof of delivery
+     * for the whole window — coarser than per-entry tracking, and wrong only in the
+     * direction that duplicates rather than loses.
      */
-    this.hasHealthy = false;
+    this.writeFailed = /* @__PURE__ */ new Set();
+    /**
+     * In-flight asynchronous writes per destination.
+     *
+     * A rejected async write is only recorded when its promise settles, and the
+     * registry can compute readiness while one is still pending — so "no failure
+     * recorded" is not "every write landed". A destination with anything in flight
+     * is UNPROVEN rather than trusted: counting it as delivery would let a
+     * buffering sink discard its copy moments before the pending write rejects.
+     *
+     * A counter rather than a flag because writes overlap; it returns to zero only
+     * when the last one settles.
+     */
+    this.pendingWrites = /* @__PURE__ */ new Map();
     /**
      * The rescuer's severity index within {@link LOG_LEVEL_PRIORITY}. Starts above
      * every real level so the first `markFailed` always wins the comparison.
      */
     this.rescuerLevel = Number.POSITIVE_INFINITY;
   }
-  /** Record that a destination initialized successfully. */
-  markHealthy() {
-    this.hasHealthy = true;
+  /**
+   * Record that a destination's `write()` threw or rejected.
+   *
+   * Called from the fan-out's failure path, which already reports the entry as
+   * dropped. This is what stops {@link deliveredByHealthySink} from crediting a
+   * throwing sink with entries it never accepted.
+   *
+   * @param destination - The destination whose write failed.
+   */
+  markWriteFailed(destination) {
+    this.writeFailed.add(destination);
+  }
+  /**
+   * Record that an asynchronous write to a destination has started.
+   *
+   * @param destination - The destination being written to.
+   */
+  markWritePending(destination) {
+    this.pendingWrites.set(destination, (this.pendingWrites.get(destination) ?? 0) + 1);
+  }
+  /**
+   * Record that an asynchronous write has settled, however it settled.
+   *
+   * Paired with {@link markWritePending} on both the fulfilled and rejected
+   * paths — a counter that only decremented on success would never return to
+   * zero for a failing sink, which is a different claim from the one this makes.
+   *
+   * @param destination - The destination whose write settled.
+   */
+  markWriteSettled(destination) {
+    this.pendingWrites.set(destination, (this.pendingWrites.get(destination) ?? 1) - 1);
+  }
+  /**
+   * Record that a destination initialized successfully.
+   *
+   * @param destination - The destination that initialized.
+   * @param effectiveLevel - Its multistream level: `minLevel` when set, otherwise
+   *   the module-wide `level`.
+   */
+  markHealthy(destination, effectiveLevel) {
+    this.healthy.set(destination, LOG_LEVEL_PRIORITY.indexOf(effectiveLevel));
   }
   /**
    * Record that a destination failed to initialize, and re-elect the rescuer.
@@ -1658,7 +1786,31 @@ var DestinationHealth = class {
    *   rescuer.
    */
   shouldRescue(destination) {
-    return !this.hasHealthy && this.rescuer === destination;
+    return this.healthy.size === 0 && this.rescuer === destination;
+  }
+  /**
+   * Whether a LIVE sink received everything a destination at `effectiveLevel`
+   * received — the question a destination holding pre-init entries actually has
+   * before discarding them.
+   *
+   * Not "did any sink survive": `pino.multistream` filters per stream, so a
+   * healthy `error` sink never saw the `info` entries a pretty sink at `info`
+   * buffered. Discarding those because something else was alive would lose them,
+   * which is the failure the buffer exists to prevent. A healthy sink whose level
+   * is at or below this one accepted a superset, so those entries are delivered.
+   *
+   * @param effectiveLevel - The asking destination's multistream level.
+   * @returns `true` when a live sink accepted everything this destination did.
+   */
+  deliveredByHealthySink(asking, effectiveLevel) {
+    const level = LOG_LEVEL_PRIORITY.indexOf(effectiveLevel);
+    for (const [destination, healthyLevel] of this.healthy) {
+      const unproven = this.writeFailed.has(destination) || (this.pendingWrites.get(destination) ?? 0) > 0;
+      if (destination !== asking && !unproven && healthyLevel <= level) {
+        return true;
+      }
+    }
+    return false;
   }
 };
 DestinationHealth = __decorateClass([
@@ -1710,14 +1862,70 @@ var DestinationRegistry = class {
       try {
         await destination.onInit?.();
         this.active.push(destination);
-        this.health.markHealthy();
+        this.health.markHealthy(destination, this.effectiveLevelOf(destination));
       } catch (cause) {
-        this.health.markFailed(destination, destination.minLevel ?? this.options.level);
-        this.reportInitFailure(destination.name, cause);
+        this.health.markFailed(destination, this.effectiveLevelOf(destination));
+        this.reportInitFailure(destination, cause);
       }
     }
+    await this.notifyRegistryReady();
     this.announceBootstrap();
   }
+  /**
+   * Tell every REGISTERED destination — live or failed — what happened to the
+   * entries it may be holding, before the first post-init entry is emitted.
+   *
+   * The signal it carries is one the destination cannot compute: whether ANOTHER
+   * live sink appears to have accepted everything this one accepted.
+   * `pino.multistream` filters per stream, a destination is not its own witness, a
+   * sink whose write threw did not receive that entry, and one whose write has not
+   * settled has shown nothing yet — all of which live in `deliveredByHealthySink`.
+   *
+   * A signal rather than a proof, deliberately: a write still queued inside the
+   * `Writable` adapter is invisible to that accounting, so the flag says which
+   * risk is smaller, not that the entry is safe. See `ILogDestination.onRegistryReady`.
+   *
+   * Each notification is isolated: a destination that throws here is reported and
+   * skipped rather than aborting the remaining ones or the bootstrap entry.
+   * Failing at this hook cannot be allowed to cost more than the hook was worth.
+   */
+  async notifyRegistryReady() {
+    for (const destination of this.registered) {
+      try {
+        await destination.onRegistryReady?.({
+          heldEntriesDeliveredElsewhere: this.health.deliveredByHealthySink(
+            destination,
+            this.effectiveLevelOf(destination)
+          )
+        });
+      } catch (cause) {
+        this.reportHookFailure(destination, cause);
+      }
+    }
+  }
+  /**
+   * The severity a destination actually receives: the STRICTER of the module
+   * level and its own `minLevel`.
+   *
+   * Pino filters at the instance level BEFORE `pino.multistream` sees an entry,
+   * so a `minLevel` below the global one cannot widen what a destination gets —
+   * the factory's own docs say so. Recording the raw `minLevel` therefore
+   * understated delivery: with a global `error` and a healthy sink at `info`,
+   * both sinks in fact receive the same `error` entries, but a pretty sink
+   * declared at `trace` compared as `trace`, delivery read as unproven, and the
+   * buffer drained raw — a duplicate produced by arithmetic rather than by any
+   * real gap.
+   *
+   * @param destination - The destination whose threshold is being computed.
+   * @returns The level entries must clear to reach it.
+   */
+  effectiveLevelOf(destination) {
+    const configured = safeMinLevel(destination);
+    if (configured === void 0) {
+      return this.options.level;
+    }
+    return LOG_LEVEL_PRIORITY.indexOf(configured) > LOG_LEVEL_PRIORITY.indexOf(this.options.level) ? configured : this.options.level;
+  }
   /**
    * Report one destination init failure as a structured
    * `LOGGER_DESTINATION_INIT_FAILED` line on `process.stderr`.
@@ -1726,10 +1934,13 @@ var DestinationRegistry = class {
    * than restating the shape, so an operator greps one `logKey` regardless of
    * which stage failed — and the two cannot drift apart.
    *
-   * @param name - The failing destination's name.
+   * @param destination - The failing destination. Passed whole, so its `name` is
+   *   read under `safeDestinationName` rather than at the call site — which sits
+   *   inside the catch, where a throwing getter would abort bootstrap.
    * @param cause - The thrown or rejected value.
    */
-  reportInitFailure(name, cause) {
+  reportInitFailure(destination, cause) {
+    const name = safeDestinationName(destination);
     reportDestinationFailure(
       RESERVED_LOG_KEYS.LOGGER_DESTINATION_INIT_FAILED,
       name,
@@ -1737,6 +1948,30 @@ var DestinationRegistry = class {
       `Log destination "${name}" failed to initialize and will receive no entries. If no destination initializes, entries fall back to raw NDJSON on stdout.`
     );
   }
+  /**
+   * Report a failure from the readiness hook, with wording that matches the
+   * destination's actual state.
+   *
+   * The loop calls every registered destination, healthy and failed alike, so one
+   * message cannot be true for both. A healthy one keeps receiving entries and was
+   * never an init failure; a failed one was already dropped from the fan-out and
+   * saying it "remains active" would contradict the report it just got. The key
+   * stays `LOGGER_DESTINATION_INIT_FAILED` either way so an operator greps one
+   * thing across every destination-lifecycle problem.
+   *
+   * @param destination - The destination whose hook threw.
+   * @param cause - The thrown value.
+   */
+  reportHookFailure(destination, cause) {
+    const stillActive = !this.health.isFailed(destination);
+    const name = safeDestinationName(destination);
+    reportDestinationFailure(
+      RESERVED_LOG_KEYS.LOGGER_DESTINATION_INIT_FAILED,
+      name,
+      cause,
+      `Log destination "${name}" threw from onRegistryReady. ` + (stillActive ? "It initialized successfully and keeps receiving entries; only anything it was holding from before init may be affected." : "It had already failed to initialize and receives no entries; anything it was still holding is lost.")
+    );
+  }
   /**
    * Emit the one-shot bootstrap entries, AFTER every destination has been
    * initialized.
@@ -1793,14 +2028,50 @@ var DestinationRegistry = class {
       try {
         await destination.onShutdown?.();
       } catch (cause) {
-        const detail = cause instanceof Error ? cause.stack ?? cause.message : String(cause);
-        writeStderrSafely(
-          `[DestinationRegistry] Shutdown failed for "${destination.name}": ${detail}
-`
-        );
+        this.reportShutdownFailure(destination, cause);
       }
     }
   }
+  /**
+   * Report a failing `onShutdown` on stderr without letting the report itself
+   * abort the teardown of the destinations still queued behind it.
+   *
+   * The coercion is INSIDE the guard, not above it. Reading `stack`/`message` on
+   * an `Error` with hostile getters, and `String(cause)` on a value with a
+   * throwing `toString`/`Symbol.toPrimitive`, both throw — and this runs inside
+   * the `catch` that exists to keep one bad sink from mattering, so an escape
+   * here would propagate out of `onApplicationShutdown` and skip every remaining
+   * destination's flush. The never-throw contract has to cover READING the value,
+   * not just writing it, which is the same correction `reportDestinationFailure`
+   * already carries.
+   *
+   * The text is escaped for the same reason every other terminal-bound path is:
+   * a stack is legitimately multi-line, so `escapeControlCharacters` keeps its
+   * newlines and neutralizes everything else that can drive a terminal.
+   *
+   * The DESTINATION is passed rather than its name, so that read happens in here
+   * too. `name` is declared `readonly name: string` but nothing stops a consumer
+   * implementing it as a getter, and reading it at the call site would put it back
+   * outside the guard — inside the `catch`, where a throw has the same cost.
+   *
+   * Two separate guards, not one: a name that cannot be read must not also cost
+   * the failure detail, and a detail that cannot be read must not cost the name.
+   * Either alone still identifies which sink failed.
+   *
+   * @param destination - The destination whose `onShutdown` threw.
+   * @param cause - The thrown value, of any shape.
+   */
+  reportShutdownFailure(destination, cause) {
+    const name = toSingleLineMessage(safeDestinationName(destination));
+    let detail = "UnknownError";
+    try {
+      const stack = isErrorLike(cause) ? cause.stack : void 0;
+      detail = stack === void 0 ? toSingleLineMessage(isErrorLike(cause) ? String(cause.message) : String(cause)) : escapeControlCharacters(String(stack));
+    } catch {
+    }
+    writeStderrSafely(`[DestinationRegistry] Shutdown failed for "${name}": ${detail}
+`);
+  }
   /**
    * The destinations that initialized successfully.
    *
@@ -2151,9 +2422,6 @@ var PrettyDevDestination = class {
       });
     } catch {
       this.initFailed = true;
-      this.flushBuffer((payload) => {
-        writeRawToStdout(payload);
-      });
       throw new Error(
         "[PrettyDevDestination] pino-pretty is not installed. Install it as a peer dependency (`pnpm add -D pino-pretty`) or remove PrettyDevDestination from `destinations`."
       );
@@ -2204,6 +2472,41 @@ var PrettyDevDestination = class {
     this.buffer.push(payload);
     this.bufferedBytes += payloadBytes;
   }
+  /**
+   * Resolve anything still held, now that the registry knows what became of it.
+   *
+   * **Discard only where another sink is believed to have taken the same entries;
+   * emit everything else.** Losing a boot entry is not an acceptable outcome, and
+   * every richer policy tried here had a losing branch: trusting "a sink survived"
+   * lost entries to a sink at a higher level, trusting a 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. Each of those is now folded into the single
+   * signal handed in — and where it is uncertain, it says `false` and this drains.
+   *
+   * That signal is not a proof, and this hook does not treat it as one. It cannot
+   * see an entry still queued inside the `Writable` adapter, because the adapter
+   * has not called `destination.write()` for it yet. Discarding on it is a bet
+   * that a duplicated boot line costs less than a lost one — which is the trade
+   * this destination accepts, and which a destination that cannot lose anything
+   * should decline by ignoring the flag and always emitting.
+   *
+   * The cost is stated rather than hidden: when nothing survived, every holding
+   * destination drains, so N of them produce N copies of the boot entries. A
+   * duplicated line in an already-degraded boot is a smaller harm than a lost one,
+   * and it is loud rather than silent.
+   *
+   * A no-op once {@link onInit} succeeded — the buffer was flushed through the
+   * transform there and is already empty.
+   *
+   * @param status.heldEntriesDeliveredElsewhere - Another live sink appears to
+   *   have taken everything this one took. A deduplication signal, not a proof —
+   *   see `ILogDestination.onRegistryReady` for what it cannot see.
+   */
+  onRegistryReady(status) {
+    this.flushBuffer(
+      status.heldEntriesDeliveredElsewhere ? () => void 0 : writeRawToStdout
+    );
+  }
   /**
    * Hand every buffered entry to `emit`, in arrival order, and empty the buffer.
    *

package/dist/server/index.d.cts

@@ -69,12 +69,55 @@ interface ILogDestination {
      *
      * @param payload — Newline-terminated JSON entry, UTF-8 encoded.
      */
-    write(payload: string): void | Promise<void>;
+    write(payload: string): void | PromiseLike<void>;
     /**
      * Optional lifecycle hook — called once during NestJS module init.
      * Use for opening connections, allocating buffers, scheduling flushers.
      */
-    onInit?(): void | Promise<void>;
+    onInit?(): void | PromiseLike<void>;
+    /**
+     * Optional lifecycle hook — called once after EVERY destination's `onInit`
+     * has settled, successfully or not, and before the bootstrap entry is emitted.
+     *
+     * Only useful to a destination that holds entries written before its own
+     * `onInit` ran: until this point it cannot know what became of them. The
+     * fan-out hands each entry to every registered destination whose level accepts
+     * it, so a held copy may be a SECOND copy.
+     *
+     * **This is a deduplication signal, not a proof — and the difference is the
+     * whole contract.** A held copy may be a second copy, so emitting it duplicates
+     * a line and dropping it may lose one. The flag says which risk is smaller, as
+     * far as this library can see; it does not say the entry is safe.
+     *
+     * The library's own destinations act on it by discarding when it is `true` and
+     * emitting otherwise, because a duplicated boot line is a smaller harm than a
+     * lost one. **A destination that cannot tolerate ANY loss should emit
+     * regardless** — see the accounting limits on the flag below.
+     *
+     * Called on failed destinations too, which is the point: the one that could not
+     * initialize is exactly the one still holding entries.
+     *
+     * @param status.heldEntriesDeliveredElsewhere - Whether another live sink
+     *   accepted everything this destination accepted, as far as this library can
+     *   see. `true` requires that sink to be not this one, initialized, at or below
+     *   this level, with no write failure and no write still in flight; anything
+     *   less certain is `false`.
+     *
+     *   **What it cannot see:** a write still QUEUED inside the `Writable` adapter,
+     *   behind a slow async sink that has not been called yet. So `true` can precede
+     *   a queued write that later fails, and there is no flag that distinguishes
+     *   that case — which is exactly why this is a tradeoff rather than a
+     *   guarantee. It normally arrives, being queued rather than lost.
+     *
+     * @returns Nothing, or a promise the library AWAITS. Returning one is
+     *   supported deliberately: TypeScript accepts an `async` implementation where
+     *   a void-returning member is declared, so a hook that was not awaited would
+     *   reject into nothing and let the bootstrap entry be emitted before the
+     *   buffer had been resolved.
+     */
+    onRegistryReady?(status: {
+        readonly heldEntriesDeliveredElsewhere: boolean;
+    }): void | PromiseLike<void>;
     /**
      * Optional lifecycle hook — called during NestJS `onApplicationShutdown`.
      * MUST flush any pending writes and close resources.
@@ -82,7 +125,7 @@ interface ILogDestination {
      * The library awaits this — graceful shutdown blocks until all destinations
      * return.
      */
-    onShutdown?(): void | Promise<void>;
+    onShutdown?(): void | PromiseLike<void>;
 }
 
 /**
@@ -636,10 +679,30 @@ declare class PinoLoggerService implements LoggerService, OnApplicationShutdown
     private readonly redact;
     private context?;
     /**
+     * **A hand-built instance is NOT this library's behaviour.** Constructing
+     * `new PinoLoggerService(pino({...}, sink))` directly works in the sense of not
+     * throwing, and the parameter default below 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 an `Error` is serialized by Pino's default.
+     *     The `cause` chain disappears ENTIRELY — no marker, no warning, and a
+     *     `cause` that reads as "the field was never set";
+     *   - **no name-based redaction** of serializer output or child bindings;
+     *   - **no trace-context mixin**, so `requestId` / `tenantId` / OTel ids are
+     *     absent;
+     *   - **no size bound**, so nothing is truncated.
+     *
+     * That matters most for tests, which is the use this doc used to invite without
+     * qualification: a consumer wrote one to check whether a `cause` carried its
+     * `code`, measured absence, and nearly filed it against this library. The
+     * absence was their harness. For a faithful harness, boot the module (or use
+     * `BymaxLoggerModule.forRoot` in a testing module) rather than hand-building.
+     *
      * @param pino - The wrapped Pino instance.
      * @param redact - The DEFAULT-coverage redactor, applied to `child()` bindings.
-     *   Defaults to the identity so a hand-built instance (benchmarks, unit tests)
-     *   still works; the module always injects the configured one.
+     *   Defaults to the identity so a hand-built instance still works; the module
+     *   always injects the configured one.
      */
     constructor(pino: Logger, redact?: Redactor);
     /**
@@ -932,16 +995,42 @@ interface PrettyViewOptions {
      */
     ignore?: string;
     /**
-     * Render only the message line, hiding the record entirely. In pretty mode
-     * there is no JSON copy behind it (`destinations` REPLACES stdout), so a field
-     * hidden here is not visible anywhere — including `logKey`. That is the point
-     * of the option rather than a caveat; use `messageFormat` to pull a specific
-     * field back into the line. Default: `false`.
+     * Render only the message line, hiding the record entirely. Display-only, and
+     * scoped to THIS destination: a field hidden here is still delivered in full to
+     * every other destination registered alongside it.
+     *
+     * When pretty is the ONLY destination, that scope makes it total — `destinations`
+     * replaces the default stdout sink, so there is no JSON copy behind the
+     * rendering and a hidden field, `logKey` included, is not visible anywhere. That
+     * is the point of the option rather than a caveat; use `messageFormat` to pull a
+     * specific field back into the line. Default: `false`.
      */
     hideObject?: boolean;
     /**
      * Template for the message line, e.g. `'[{context}] {msg}'`. The way to keep a
      * chosen field visible when `hideObject` is on.
+     *
+     * **Every placeholder EXCEPT `{msg}` is interpolated raw, and that reopens
+     * terminal log forging.** This library normalizes line separators and control
+     * characters in `msg` and in the stack — not 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 …"
+     * ```
+     *
+     * So: interpolate only fields whose values your own code sets. Never a field
+     * carrying user input — `{tenantId}`, `{userId}`, a header, a query value. If
+     * you need one of those visible, leave it in the record instead of the format
+     * string. That closes THIS path — the raw placeholder — and no more: a metadata
+     * value is not safe terminal text either, because `JSON.stringify` escapes only
+     * C0 and emits DEL, the C1 range (U+0085 NEL included), U+2028 and U+2029
+     * verbatim. Only `msg` and the stack carry the one-entry-one-line guarantee.
      */
     messageFormat?: string;
     /** Timestamp format, or `false` to leave it raw. Default: `'SYS:HH:MM:ss.l'`. */
@@ -1046,6 +1135,39 @@ declare class PrettyDevDestination implements ILogDestination {
      * @param payload — Newline-terminated JSON entry, UTF-8 encoded.
      */
     write(payload: string): void;
+    /**
+     * Resolve anything still held, now that the registry knows what became of it.
+     *
+     * **Discard only where another sink is believed to have taken the same entries;
+     * emit everything else.** Losing a boot entry is not an acceptable outcome, and
+     * every richer policy tried here had a losing branch: trusting "a sink survived"
+     * lost entries to a sink at a higher level, trusting a 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. Each of those is now folded into the single
+     * signal handed in — and where it is uncertain, it says `false` and this drains.
+     *
+     * That signal is not a proof, and this hook does not treat it as one. It cannot
+     * see an entry still queued inside the `Writable` adapter, because the adapter
+     * has not called `destination.write()` for it yet. Discarding on it is a bet
+     * that a duplicated boot line costs less than a lost one — which is the trade
+     * this destination accepts, and which a destination that cannot lose anything
+     * should decline by ignoring the flag and always emitting.
+     *
+     * The cost is stated rather than hidden: when nothing survived, every holding
+     * destination drains, so N of them produce N copies of the boot entries. A
+     * duplicated line in an already-degraded boot is a smaller harm than a lost one,
+     * and it is loud rather than silent.
+     *
+     * A no-op once {@link onInit} succeeded — the buffer was flushed through the
+     * transform there and is already empty.
+     *
+     * @param status.heldEntriesDeliveredElsewhere - Another live sink appears to
+     *   have taken everything this one took. A deduplication signal, not a proof —
+     *   see `ILogDestination.onRegistryReady` for what it cannot see.
+     */
+    onRegistryReady(status: {
+        readonly heldEntriesDeliveredElsewhere: boolean;
+    }): void;
     /**
      * Hand every buffered entry to `emit`, in arrival order, and empty the buffer.
      *