first commit

docs/foundation/flow/queue-distribution/src/internal/noop-logger.md

@@ -0,0 +1,50 @@
+# `NOOP_LOGGER`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`NOOP_LOGGER` is a shared `LoggerLike` implementation whose four methods (`debug` / `info` / `warn` / `error`) all return `undefined`. Components inside `@suaveplan/queue-distribution` use it as the default when no logger is injected, so they can call `this.logger.warn(...)` unconditionally without a per-call `?.` check. Sharing one constant across `WorkerPool`, `WorkerManager`, `PeriodicHealthChecker`, `AbstractWorker`, and the supervisor avoids per-file duplication of dead-code stubs that would otherwise show up as uncovered branches in coverage reports.
+
+## Features
+
+- Conforms to the `LoggerLike` structural contract from `@suaveplan/types`.
+- All four methods return `undefined` synchronously.
+- Lazy by construction: no allocation per call, just an immediate return.
+- Reused across every component that accepts an optional `LoggerLike`.
+
+## Usage: Basic Example
+
+```ts
+import { NOOP_LOGGER } from "@suaveplan/queue-distribution/internal/noop-logger";
+
+const logger = process.env.DEBUG === "1" ? console : NOOP_LOGGER;
+logger.info("starting up");
+```
+
+## Usage: Advanced Example
+
+Use the noop logger when wiring a test fixture that doesn't care about log output. Tests that DO want to inspect logs can substitute a simple array-pusher:
+
+```ts
+import type { LoggerLike } from "@suaveplan/types";
+import { WorkerPool } from "@suaveplan/queue-distribution/pool/pool";
+
+const lines: string[] = [];
+const probe: LoggerLike = {
+    debug: (m) => lines.push(`debug: ${m}`),
+    info: (m) => lines.push(`info: ${m}`),
+    warn: () => {},
+    error: () => {},
+};
+const pool = new WorkerPool({ logger: probe });
+```
+
+## API Reference
+
+- `const NOOP_LOGGER: LoggerLike` — frozen-in-shape no-op implementation.
+
+## Implementation Notes
+
+Centralising the noop methods here means coverage tools see one set of empty-body functions rather than one per component, and a single test covers all of them (`internal/noop-logger.test.ts`). Components import `NOOP_LOGGER` rather than declaring their own local constant to keep this contract honest. The methods are written as `(): void => {}` rather than the shorter `noop` shorthand so TypeScript's structural typing matches the `LoggerLike` signature exactly.