@venizia/ignis-docs 0.2.1-0 → 0.2.1-1

package/content/extensions/helpers/logger/pino.md

@@ -6,21 +6,32 @@ difficulty: intermediate
 
 # Pino Provider
 
-`PinoLogger` is the second logger provider behind the `ILogger` contract - the throughput option. Where the built-in Winston provider gives colorized console, daily-rotating info/error files, and UDP shipping at ~1.2-1.6us per line, the pino provider emits newline-delimited JSON at ~0.5-0.6us per line (measured). Winston remains the DEFAULT; nothing changes for apps that never register pino.
+`PinoLogger` is the second logger provider behind the `ILogger` contract - the throughput option. Winston remains the DEFAULT. Nothing changes for apps that never register pino.
+
+| Provider | Output | Speed (measured) |
+|---|---|---|
+| Winston (built-in) | Colorized console, daily-rotating info/error files, UDP shipping | ~1.2-1.6us/line |
+| Pino | Newline-delimited JSON | ~0.5-0.6us/line |
 
 ## Registration - one line, order-independent
 
 ```typescript
-// entrypoint (e.g. src/index.ts)
+// entrypoint (for example, src/index.ts)
 import { LoggerFactory } from '@venizia/ignis-helpers';
 import { PinoLogger } from '@venizia/ignis-helpers/pino';
 
 LoggerFactory.use({ provider: PinoLogger });
 ```
 
-The two providers register symmetrically - `WinstonLogger` lives at `@venizia/ignis-helpers/winston` the same way. Both are sub-path only with optional peers, and exactly ONE provider is ever loaded: registering pino here means winston is never loaded (nor bundled).
+The two providers register symmetrically - `WinstonLogger` lives at `@venizia/ignis-helpers/winston` the same way. Both are sub-path only, with optional peers. Exactly ONE provider is ever loaded - registering pino here means winston is never loaded, nor bundled.
+
+From that moment, every factory-issued logger runs on pino:
+
+- `BaseHelper.logger` in every controller, service, repository, and helper
+- `ApplicationLogger.get(...)`
+- Even a module-level `const logger = LoggerFactory.getLogger([...])`, captured at import time before this line ran - thanks to swap-on-use delegation
 
-From that moment EVERY factory-issued logger runs on pino: `BaseHelper.logger` in every controller/service/repository/helper, `ApplicationLogger.get(...)`, and - thanks to swap-on-use delegation - even module-level `const logger = LoggerFactory.getLogger([...])` constants that were captured at import time, BEFORE this line ran. Import order does not matter; the factory re-points every wrapper it has ever issued when `use()` is called.
+Import order doesn't matter. The factory re-points every wrapper it has ever issued when `use()` is called.
 
 > [!IMPORTANT]
 > `Logger.get(...)` (the concrete `WinstonLogger` alias) and `defineCustomLogger` deliberately do NOT follow the registration - they name winston explicitly. See the name/role table in the [Full reference](/extensions/helpers/logger/reference).
@@ -32,16 +43,20 @@ The provider lives at the sub-path `@venizia/ignis-helpers/pino` only - importin
 | Peer | Needed when |
 |------|-------------|
 | `pino` | always (the sub-path values-imports it) |
-| `pino-pretty` | `APP_ENV_LOGGER_FORMAT=text` (colorized dev output) |
+| `pino-pretty` | `APP_ENV_LOGGER_FORMAT=text` (pretty dev output, colorized when the environment allows it) |
 | `pino-roll` | `APP_ENV_LOGGER_FOLDER_PATH` is set (file rotation) |
 
 A missing peer fails with the standard install-hint error BEFORE any worker thread spawns.
 
 ## Output modes
 
-- **Default (`APP_ENV_LOGGER_FORMAT=json`, or unset in production practice): NDJSON to stdout** - the k8s/docker collector pattern.
-- **`APP_ENV_LOGGER_FORMAT=text`**: pretty colorized lines via a `pino-pretty` worker-thread transport - dev only.
-- **`APP_ENV_LOGGER_FOLDER_PATH` set**: writes to a rotating file via `pino-roll`, honoring the SAME env vars winston uses:
+| Trigger | Output |
+|---|---|
+| `APP_ENV_LOGGER_FORMAT=json`, or unset in production practice | NDJSON to stdout - the k8s/docker collector pattern |
+| `APP_ENV_LOGGER_FORMAT=text` | Pretty lines via a `pino-pretty` worker-thread transport - dev only. Color follows the [Color](./reference#color) rules, and `pino-pretty` still drops it when stdout is not a terminal |
+| `APP_ENV_LOGGER_FOLDER_PATH` is set | A rotating file via `pino-roll`, honoring the same env vars winston uses (table below) |
+
+**`pino-roll` file rotation - env var mapping:**
 
 | Env | pino-roll meaning |
 |-----|-------------------|
@@ -50,11 +65,16 @@ A missing peer fails with the standard install-hint error BEFORE any worker thre
 | `APP_ENV_LOGGER_FILE_MAX_FILES` | retention -> file count: `'5d'` -> 120 files (hourly) / 5 (daily); a bare integer -> that count |
 | `APP_ENV_LOGGER_FILE_DATE_PATTERN` | NOT supported (pino-roll has no date pattern) |
 
-`APP_ENV_LOGGER_LEVEL` sets the floor exactly as with winston; `emerg` is the single custom pino level (above `error`), and the default `debug` floor admits every level - identical to the winston provider.
+`APP_ENV_LOGGER_LEVEL` sets the floor exactly as with winston. `emerg` is the single custom pino level, above `error`. The default `debug` floor admits every level - identical to the winston provider.
 
 ## What stays identical, what differs
 
-Identical by construction: the `[Scope] ` message prefix, args formatting through `formatLogMessage` (deep inspection + secret REDACTION - a `token` field renders `[REDACTED]` on pino exactly as on winston), the level vocabulary and floor semantics, the `DEBUG` gate on `debug()`.
+Identical by construction:
+
+- the `[Scope] ` message prefix
+- args formatting through `formatLogMessage` - deep inspection plus secret redaction; a `token` field renders `[REDACTED]` on pino exactly as on winston
+- the level vocabulary and floor semantics
+- the `DEBUG` gate on `debug()`
 
 Different on purpose (pino stays pino-native - every parity shim would cost the speed you came for):
 
@@ -71,7 +91,7 @@ If your operations depend on the left column, stay on winston - it is not deprec
 
 ## Advanced: injecting a backing instance
 
-`setPinoBackingLogger({ instance })` replaces the env-driven singleton with a pino instance you configured yourself (tests use this with an in-memory destination; apps can use it for exotic transports). The previous instance's transport is flushed and closed on replacement. `buildPinoOptions()` and `resolveDestinationPlan()` are exported for building compatible options.
+`setPinoBackingLogger({ instance })` replaces the env-driven singleton with a pino instance you configured yourself. Tests use this with an in-memory destination; apps can use it for exotic transports. The previous instance's transport is flushed and closed on replacement. `buildPinoOptions()` and `resolveDestinationPlan()` are exported for building compatible options.
 
 ## See also
 

package/content/extensions/helpers/logger/reference.md

@@ -8,7 +8,7 @@ difficulty: intermediate
 
 Exhaustive reference for `Logger`, `LoggerFactory`, `HfLogger`/`HfLogFlusher`, the Winston formatter and transport internals, and every environment variable. For a readable introduction and the common tasks, start with the [Logger overview](/extensions/helpers/logger/).
 
-The default provider is **Winston** (with `winston-daily-rotate-file` for file rotation). All provider packages are OPTIONAL peers - an application loads exactly ONE provider (single-provider loading, below).
+The default provider is **Winston**, paired with `winston-daily-rotate-file` for file rotation. All provider packages are OPTIONAL peers. An application loads exactly ONE provider - see [single-provider loading](#architecture-and-ilogger) below.
 
 **Files:**
 
@@ -25,9 +25,31 @@ The default provider is **Winston** (with `winston-daily-rotate-file` for file r
 - [`packages/helpers/src/modules/logger/hf/flusher.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/logger/hf/flusher.ts) - `HfLogFlusher`
 - [`packages/helpers/src/modules/logger/factory.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/logger/factory.ts) - `LoggerFactory`, `ApplicationLogger`
 
-## Architecture & ILogger
+## Find what you need
 
-The module follows IGNIS's house format: `common/` (the contract), `base/` (provider-independent plumbing), `winston/` (the built-in provider), `hf/` (the separate high-frequency logger), and a top-level `factory.ts` as the single acquisition path.
+| You want to | Go to |
+|---|---|
+| See how provider registration and delegation work | [Architecture and ILogger](#architecture-and-ilogger) |
+| Import the right class from the right sub-path | [Import paths](#import-paths) |
+| Get or cache a scoped logger instance | [Creating an Instance](#creating-an-instance) |
+| Know what each log level means and when to use it | [What each level means](#what-each-level-means) |
+| Keep nested fields visible when logging with `%s` | [Message Formatting](#message-formatting) |
+| Turn on file rotation or UDP shipping | [Transports](#transports) |
+| Fix `debug()` logs that aren't showing | [Debug Logging Behavior](#debug-logging-behavior) |
+| Log on a hot path doing 100k+ events/sec | [High-Frequency Logger](#high-frequency-logger) |
+| Look up one `APP_ENV_LOGGER_*` variable | [Environment Variables](#environment-variables) |
+| Find one exported symbol fast | [API Summary](#api-summary) |
+| Fix a specific error message | [Troubleshooting](#troubleshooting) |
+
+## Architecture and ILogger
+
+The module follows IGNIS's house format - one folder per concern:
+
+- `common/` - the contract
+- `base/` - provider-independent plumbing
+- `winston/` - the built-in provider
+- `hf/` - the separate high-frequency logger
+- `factory.ts` - the single acquisition path
 
 ```
 ILogger (interface)                common/types.ts
@@ -38,9 +60,12 @@ ILogger (interface)                common/types.ts
 ```
 
 - **Consumers type against `ILogger`, never a concrete class.** `LoggerFactory.getLogger()` and `BaseHelper.logger` both return `ILogger`. Which provider produced the instance stays invisible behind the interface.
-- **Provider registration.** `LoggerFactory.use({ provider })` selects the application's provider (default: `WinstonLogger`). The factory hands out stable delegating wrappers and re-points ALL of them when `use()` is called - even module-level loggers captured at import time follow the registration; the per-call cost is one property read (measured ~0ns).
-- **Single-provider loading.** Exactly ONE provider is ever loaded. Delegates resolve lazily at the first log call, so an app that registers pino at its entrypoint never loads winston. The winston default loads only when `use()` was never called by the first log line - it requires the winston peers installed (`bun add winston winston-transport winston-daily-rotate-file`). Compiled binaries (`bun build --compile`) must ALWAYS register a provider explicitly: only a class reference carries a provider into a bundle.
-- **Both providers are sub-path only**: `WinstonLogger` at `@venizia/ignis-helpers/winston`, `PinoLogger` at `@venizia/ignis-helpers/pino` ([guide](/extensions/helpers/logger/pino)). The root barrel is provider-free; importing it loads neither.
+- **Provider registration.** `LoggerFactory.use({ provider })` selects the application's provider (default: `WinstonLogger`). The factory hands out stable delegating wrappers.
+- **`use()` re-points every wrapper, even ones captured at import time.** The per-call cost after that: one property read (measured ~0ns).
+- **Single-provider loading.** Exactly ONE provider is ever loaded. Delegates resolve lazily at the first log call, so an app that registers pino at its entrypoint never loads winston.
+- **The winston default loads only when `use()` was never called first.** It requires the winston peers installed: `bun add winston winston-transport winston-daily-rotate-file`.
+- **Compiled binaries (`bun build --compile`) must ALWAYS register a provider explicitly.** Only a class reference carries a provider into a bundle.
+- **Both providers are sub-path only**: `WinstonLogger` at `@venizia/ignis-helpers/winston`, `PinoLogger` at `@venizia/ignis-helpers/pino` ([guide](/extensions/helpers/logger/pino)). The root barrel is provider-free - importing it loads neither.
 
 **Which names follow `use()`:**
 
@@ -79,6 +104,10 @@ import { HfLogger, HfLogFlusher } from '@venizia/ignis-helpers';
 import { LogLevels, LoggerFormats } from '@venizia/ignis-helpers';
 import type { TLogLevel, TLoggerFormat } from '@venizia/ignis-helpers';
 
+// Error rendering - a readable block instead of a raw object dump
+import { ErrorPrettier, formatLogMessage } from '@venizia/ignis-helpers';
+import type { IErrorSummary } from '@venizia/ignis-helpers';
+
 // Level resolution - provider-neutral
 import { resolveLoggerLevel } from '@venizia/ignis-helpers';
 
@@ -152,7 +181,7 @@ const customWinstonLogger = defineCustomLogger({
 const logger = Logger.get('MyService', customWinstonLogger);
 ```
 
-A custom-backed `Logger` is a fresh wrapper on every call - a scope-keyed cache cannot tell two different Winston instances apart, and the wrapper is cheap enough not to need one. `.for()` on a custom-backed logger keeps the same Winston instance.
+A custom-backed `Logger` is a fresh wrapper on every call. A scope-keyed cache can't tell two different Winston instances apart, and the wrapper is cheap enough not to need one. `.for()` on a custom-backed logger keeps the same Winston instance.
 
 ### Logger caching
 
@@ -170,7 +199,9 @@ const custom2 = Logger.get('MyService', customWinstonLogger);
 
 ### ApplicationLogger - the provider-following facade
 
-`ApplicationLogger` is "the APPLICATION's logger": `ApplicationLogger.get(scope)` always returns the provider registered via `LoggerFactory.use()` (winston unless the app registered another). Its TYPE is `ILogger`. It is no longer a class alias of `WinstonLogger` - `instanceof ApplicationLogger` is now a compile error (use `instanceof AbstractLogger` to test any provider instance); the concrete alias remains available as `Logger`.
+`ApplicationLogger` is "the APPLICATION's logger." `ApplicationLogger.get(scope)` always returns whatever provider `LoggerFactory.use()` registered - winston, unless the app registered something else. Its type is `ILogger`.
+
+It is no longer a class alias of `WinstonLogger`. `instanceof ApplicationLogger` is now a compile error - use `instanceof AbstractLogger` to test any provider instance instead. The concrete winston alias still exists, named `Logger`.
 
 ```typescript
 import { ApplicationLogger } from '@venizia/ignis-helpers';
@@ -178,7 +209,8 @@ import { ApplicationLogger } from '@venizia/ignis-helpers';
 const logger = ApplicationLogger.get('MyService'); // ILogger, follows LoggerFactory.use()
 ```
 
-The old scope-less `applicationLogger` instance was REMOVED - use `ApplicationLogger.get('YourScope')`; apps that need a raw winston instance build one with `defineCustomLogger` (sub-path `/winston`).
+> [!WARNING]
+> The old scope-less `applicationLogger` instance was REMOVED. Use `ApplicationLogger.get('YourScope')` instead. An app that needs a raw winston instance builds one with `defineCustomLogger` (sub-path `/winston`).
 
 ## Log Levels
 
@@ -197,18 +229,30 @@ logger.log('warn', 'Threshold exceeded');   // Generic method for any level
 
 ### What each level means
 
-The level set follows the npm/winston convention. Lower priority number = more severe; the level floor (`APP_ENV_LOGGER_LEVEL`) admits everything at or above its severity.
+Severity runs `emerg` > `error` > `warn` > `info` > `debug` in every provider. The level floor (`APP_ENV_LOGGER_LEVEL`) admits everything at or above its severity.
+
+| Level | Meaning | Use it for |
+|-------|---------|------------|
+| `emerg` | The process is in a fatal state | Out-of-memory, unrecoverable corruption, imminent shutdown |
+| `error` | An operation failed | Caught failures the line exists to diagnose - always pair an `Error` with `%s` |
+| `warn` | Something is off but handled | Retries, fallbacks taken, deprecated usage |
+| `info` | A business event happened | "Order created", lifecycle milestones, boot phases |
+| `debug` | Developer diagnostics | Values and timings useful only while developing - ALSO gated by `DEBUG` env |
+
+Each provider numbers those levels internally, and the numbers disagree. Read them only when debugging a provider, never as a cross-provider ranking.
+
+| Provider | Numbering | `emerg` / `error` / `warn` / `info` / `debug` |
+|---|---|---|
+| Winston | lower is more severe | `0` / `0` / `1` / `2` / `3` |
+| Pino | higher is more severe | `70` / `50` / `40` / `30` / `20` |
+| HfLogger | higher is more severe | `4` / `3` / `2` / `1` / `0` |
 
-| Level | Priority | Meaning | Use it for |
-|-------|----------|---------|------------|
-| `error` | 0 | An operation failed | Caught failures the line exists to diagnose - always pair an `Error` with `%s` |
-| `emerg` | 0 | The process is in a fatal state | Out-of-memory, unrecoverable corruption, imminent shutdown |
-| `warn` | 1 | Something is off but handled | Retries, fallbacks taken, deprecated usage |
-| `info` | 2 | A business event happened | "Order created", lifecycle milestones, boot phases |
-| `debug` | 3 | Developer diagnostics | Values and timings useful only while developing - ALSO gated by `DEBUG` env |
+Winston gives `emerg` and `error` the same number, so a winston transport cannot admit `emerg` while rejecting `error`.
 
 > [!NOTE]
-> Two gates apply to `debug`, one to everything else. Every level passes the floor (`APP_ENV_LOGGER_LEVEL`, default `debug` - which admits ALL five levels); `debug()` additionally requires the `DEBUG` env gate. The vocabulary was deliberately trimmed to these five (2026-07-18): `alert`/`http`/`verbose`/`silly` had zero call sites and no consuming infrastructure - `http` returns as an access-line level if the request-correlation feature lands.
+> Two gates apply to `debug`; only one applies to everything else. Every level passes the floor (`APP_ENV_LOGGER_LEVEL`, default `debug` - which admits all five levels). `debug()` also requires the `DEBUG` env gate.
+>
+> The vocabulary was deliberately trimmed to these five (2026-07-18). `alert`/`http`/`verbose`/`silly` had zero call sites and no consuming infrastructure. `http` may return as an access-line level if the request-correlation feature lands.
 
 `LogLevels` defines all available levels and provides validation:
 
@@ -244,7 +288,7 @@ Lower numeric values have higher priority. `error` and `emerg` share priority `0
 
 ## Method-Scoped Logging
 
-`.for()` creates a sub-scoped logger for a specific method, appending the method name to the scope with a `-` separator, backed by the same provider instance as the parent. Default-backed results are cached.
+`.for()` creates a sub-scoped logger for a specific method. It appends the method name to the scope with a `-` separator, backed by the same provider instance as the parent. Default-backed results are cached.
 
 ```typescript
 class UserService {
@@ -272,23 +316,25 @@ class UserService {
 
 ### Logging errors: `%s`, never `%j`
 
-- **`message` and `stack` are non-enumerable** on a native `Error`.
-- **`%j` formats via `JSON.stringify`**, which only visits enumerable own properties, so `logger.error('Failed: %j', error)` silently drops both `message` and `stack` - the two fields the log line exists to capture.
+- **`%s` routes an Error through `ErrorPrettier`**, which projects it down to identity, cause and frames.
+- **`%j` keeps every enumerable own property**, so a `pg` error carries its whole query along and a `jose` error its whole payload. That projection is the reason the rule exists.
 - **Always pair an `Error` argument with `%s`**; reserve `%j`/`%o` for plain data objects.
 
 ```typescript
 // Good - %s prints message + stack
 logger.error('Failed to create user: %s', error);
 
-// Bad - %j drops message and stack (non-enumerable on Error)
+// Bad - %j dumps every own property the error happens to carry
 logger.error('Failed to create user: %j', error);
 ```
 
-### Object inspection depth for `%s`
+`message` and `stack` are non-enumerable, so `JSON.stringify` alone would render an Error as `{}`. The formatter projects both in first, which makes a mistaken `%j` merely noisy rather than empty.
+
+### Object inspection depth for `%s` and `%j`
 
-- **Node hard-codes `depth: 0` for `%s`** in `util.format` - an object passed to `%s` collapses to `[Object]`, hiding the nested `extra` or `cause` a wrapped error carries.
-- **`deepSplat` widens that depth.** The formatter (`formatLogMessage`) pre-inspects any object bound to a `%s` placeholder before handing the message to Winston, so nested fields print instead of collapsing.
-- **Applies per-placeholder.** Only arguments matched to a `%s` token are affected, so `%j` still gets `JSON.stringify` semantics.
+- **Node hard-codes `depth: 0` for `%s`** in `util.format`. An object passed to `%s` collapses to `[Object]`, hiding the nested `extra` or `cause` a wrapped error carries.
+- **`deepSplat` widens that depth.** The formatter (`formatLogMessage`) pre-inspects any object bound to a `%s` placeholder before handing the message to Winston. So nested fields print instead of collapsing.
+- **`%j` is capped at the same depth**, and keeps JSON semantics. Below the cap it prints `"[Object]"`.
 
 ```typescript
 logger.error('Failed: %s', error); // nested `error.cause` is now visible, not `[Object]`
@@ -302,6 +348,92 @@ APP_ENV_LOGGER_INSPECT_DEPTH=8
 
 The value must be a non-negative integer. An absent, empty, negative, or unparseable value falls back to the default of `5` - there is no "unlimited" setting.
 
+### `%j` projects the argument first
+
+`JSON.stringify` renders the WHOLE argument as `[Circular]` when a single cycle sits anywhere inside it. One live handle in the payload - a transaction, a connector, a request context - therefore erased every other field:
+
+```typescript
+logger.debug('Updating user | Args: %j', { id, data, transaction });
+// Before: Updating user | Args: [Circular]
+```
+
+The formatter now projects a `%j` argument before `util.format` sees it. Three consequences:
+
+| Concern | Behavior |
+|---|---|
+| Cycles | Collapse to `"[Circular]"` on the offending branch only; sibling fields survive |
+| Secret-looking keys | Redacted, exactly as under `%s` |
+| Depth | Capped by `APP_ENV_LOGGER_INSPECT_DEPTH`, so a live connector cannot flood one line |
+
+A payload holding a transaction still prints its own fields, but the handle itself is noise. Keep live objects out of the logged arguments.
+
+### ErrorPrettier - a readable block instead of an object dump
+
+`Source ->` [`formatting/error-prettier.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/logger/formatting/error-prettier.ts)
+
+Widening the depth makes a nested `cause` visible, but it also prints everything else. A `pg`/`drizzle` failure carries the statement in `message`, in `stack` and in `query`, so one failure floods the log with the same SQL several times. `ErrorPrettier` projects the error down to what a reader needs, then renders it as a block.
+
+```typescript
+import { ErrorPrettier } from '@venizia/ignis-helpers';
+
+logger.error('Order recalculation failed | %s', ErrorPrettier.format({ error }));
+```
+
+- **Keeps** `name`, the full untruncated `message`, `code`, an `ApplicationError`'s `normalized.args` and `normalized.code`, the `pg` diagnostics (`hint`, `detail`, `table`, `constraint`), the root stack frames, and a flattened `cause` chain.
+- **Drops** `query`, `params`, the stack header that repeats the message, and the `getError` frame that names no call site.
+- **Returns a string**, so `%s` prints it verbatim and the message keeps its real newlines instead of `\n` escapes.
+- **Bounded.** The `cause` chain is cut at 5 levels and is cycle-safe; frames stop at 10.
+
+An `ApplicationError` message keeps its `%{placeholder}` tokens - i18n resolves them downstream, not here. So the block prints the values on their own `args:` line, right under the message:
+
+```
+- message: Field %{field} is fixed at creation and cannot be changed.
+- args: { field: 'ticketType' }
+- code: server.core.inventory.ticket.update.immutable_field
+```
+
+Args come from the root error only, are redacted like `extra`, and an empty map prints no line.
+
+#### `ErrorPrettier.format(opts)`
+
+| Option | Type | Default | Meaning |
+|---|---|---|---|
+| `error` | `unknown` | - | The thrown value. A string or plain object works too |
+| `messageCode` | `string` | - | Renders the `code:` line. Without it the error's own `normalized.code` is used |
+| `extra` | `Record<string, unknown>` | - | Caller context. Redacted before printing |
+| `includeStack` | `boolean` | `true` | Set `false` to drop frames entirely |
+| `maxStackFrames` | `number` | `10` | Frame budget, forwarded to `summarize` |
+| `format` | `TLoggerFormat` | `APP_ENV_LOGGER_FORMAT`, else `text` | `text` renders the block; `json` renders one line |
+
+#### One line for a log monitor
+
+A multi-line block becomes one record per line in Loki or CloudWatch, and the error loses its
+context. Set `APP_ENV_LOGGER_FORMAT=json` and the same projection renders as a single line:
+
+```json
+{"message":"Field %{field} is fixed at creation and cannot be changed.","args":{"field":"ticketType"},"code":"server.core.inventory.ticket.update.immutable_field","stack":["at TicketService.update (...)"]}
+```
+
+Absent fields are omitted rather than set to `null`. `stack` is an **array of frames** here, not the
+newline-joined string `text` prints, so a monitor can count and slice it. `args` and `extra` are
+redacted exactly as in `text`.
+
+#### `ErrorPrettier.summarize(opts)`
+
+Returns the same projection as a typed `IErrorSummary` object rather than a string - for a JSON sink or a log aggregator. `IErrorSummary.args` carries the root error's `normalized.args` unredacted; `format()` redacts on render.
+
+`code` and `messageCode` are separate fields on purpose. `code` is the error's own - a driver's `23505`, a gRPC `14` - and renders inside the `name:` line. `messageCode` is an `ApplicationError`'s `normalized.code`, the identifier an application filters on, and renders on the `code:` line. `MessageCode.DEFAULT` never surfaces, since every codeless error carries it.
+
+| Option | Type | Default | Meaning |
+|---|---|---|---|
+| `error` | `unknown` | - | The thrown value |
+| `includeStack` | `boolean` | `true` | Skips frame extraction entirely when `false` |
+| `maxCauseDepth` | `number` | `5` | Bounds a pathological or cyclic `cause` chain |
+| `maxStackFrames` | `number` | `10` | The throw site is near the top; the tail is framework plumbing |
+
+> [!TIP]
+> `AppErrorMiddleware` already renders every thrown error this way. Reach for `ErrorPrettier` when you log an error yourself.
+
 ### Log formats
 
 Output format is controlled by `APP_ENV_LOGGER_FORMAT` (default: `text`). `LoggerFormats` provides constants and validation:
@@ -330,7 +462,7 @@ const fmt: TLoggerFormat = 'text';
 ```
 
 > [!NOTE]
-> The label shown in log output (e.g. `APP`) comes from `APP_ENV_APPLICATION_NAME` (defaults to `'APP'`). Set this env var to customize the label for your application.
+> The label shown in log output (for example, `APP`) comes from `APP_ENV_APPLICATION_NAME` (defaults to `'APP'`). Set this env var to customize the label for your application.
 
 ### Custom formatters
 
@@ -353,19 +485,26 @@ const prettyFormatter = definePrettyLoggerFormatter({ label: 'my-app' });
 const plainFormatter = definePrettyLoggerFormatter({ label: 'my-app', colorize: false });
 ```
 
+Without an explicit `colorize`, `definePrettyLoggerFormatter` follows the [Color](#color) rules.
+
 `defineLogFormatter` throws an `ApplicationError` if `format` (or `APP_ENV_LOGGER_FORMAT`) is not `'json'` or `'text'`.
 
 ## Transports
 
 `Source ->` [`winston/define.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/logger/winston/define.ts)
 
-Every logger created by `defineCustomLogger` always includes a **Console** transport, which inherits the logger-level floor (`APP_ENV_LOGGER_LEVEL`, default `debug`). File and UDP transports are optional and are registered per transport group (`info`, `error`).
+Every logger created by `defineCustomLogger` always includes a **Console** transport. It inherits the logger-level floor (`APP_ENV_LOGGER_LEVEL`, default `debug`). File and UDP transports are optional, registered per transport group (`info`, `error`).
+
+Formatting happens in two stages:
+
+- a shared preparation format on the logger (label, timestamp, error normalization, deep splat)
+- a per-transport assembly format
 
-Formatting is split in two stages: a shared preparation format on the logger (label, timestamp, error normalization, deep splat) and a per-transport assembly format. In `text` mode the console assembly colorizes while the file assembly does not - log FILES never contain ANSI color codes. In `json` mode every transport assembles with plain `format.json()`. Passing `formatter` disables the split: that one format produces the final line for every transport.
+In `text` mode the console assembly colorizes; the file assembly does not - log FILES never carry ANSI color codes. In `json` mode every transport assembles with plain `format.json()`. Passing `formatter` disables the split - that one format produces the final line for every transport.
 
-### File rotation (DailyRotateFile)
+### File rotation transport
 
-Configure file rotation through environment variables or programmatically via `IFileTransportOptions`.
+Winston implements this transport with `DailyRotateFile`. Configure it through environment variables, or programmatically via `IFileTransportOptions`.
 
 **Environment variables:**
 
@@ -452,7 +591,9 @@ const transport = DgramTransport.fromPartial({
 // Returns null if label, host, port, levels (non-empty), or socketOptions is missing
 ```
 
-On a socket error the transport closes and nulls its client; the next `log()` call re-establishes the socket before sending. A failed `send` is logged to the console and the socket is dropped for reconnection - it is never re-emitted as an `'error'` event, so one lost UDP log line can never crash the process.
+On a socket error, the transport closes and nulls its client. The next `log()` call re-establishes the socket before sending.
+
+A failed `send` is logged to the console, and the socket is dropped for reconnection. It's never re-emitted as an `'error'` event - so one lost UDP log line can never crash the process.
 
 **Environment variables for the default application logger:**
 
@@ -485,6 +626,7 @@ interface ICustomLoggerOptions {
   formatter?: ReturnType<typeof winston.format.combine>;
   format?: TLoggerFormat; // 'json' | 'text'; defaults to APP_ENV_LOGGER_FORMAT
   level?: TLogLevel;      // logger-level floor; defaults to APP_ENV_LOGGER_LEVEL, then 'debug'
+  colorize?: boolean;     // console ANSI color; defaults to the Color rules above
   transports: {
     info: {
       file?: IFileTransportOptions;
@@ -498,7 +640,7 @@ interface ICustomLoggerOptions {
 }
 ```
 
-- **Both `info` and `error` transport groups support optional `file` (DailyRotateFile) and `dgram` (UDP) transports.**
+- **Both `info` and `error` transport groups support two optional transports:** `file` (DailyRotateFile) and `dgram` (UDP).
 - **A console transport is always included**, regardless of what is configured.
 - **Error file transports double as Winston exception handlers.**
 
@@ -522,11 +664,15 @@ APP_ENV_EXTRA_LOG_ENVS=qa,preview   # Comma-separated additional environments
 > [!IMPORTANT]
 > The debug flag check is pre-computed at module load time. Changing `DEBUG` or `NODE_ENV` at runtime has no effect - the values are captured once when the module is first imported.
 
-## High-Frequency Logger (HfLogger)
+## High-Frequency Logger
 
 `Source ->` [`hf/logger.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/logger/hf/logger.ts), [`hf/flusher.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/logger/hf/flusher.ts)
 
-For performance-critical applications (e.g. HFT systems, game servers), `HfLogger` provides ring-buffer logging with a 59.4ns bytes-path enqueue and a 66.0ns string no-args enqueue (Bun 1.3.14, 1M-iteration median). It extends `AbstractLogger` and implements `ILogger`, so it can be used anywhere an `ILogger` is expected - but it is still entirely separate from the Winston-backed `Logger` pipeline: no formatters, transports, or `APP_ENV_LOGGER_*` env vars apply to it. Read the [HfLogger guide](/extensions/helpers/logger/hf-logger) before using it - it carries hard usage rules (pre-encoded fixed message vocabulary, single-thread only, flush-interval sizing) and documented limitations.
+For performance-critical applications (for example, HFT systems or game servers), `HfLogger` provides ring-buffer logging. It measures a 59.4ns bytes-path enqueue and a 66.0ns string no-args enqueue (Bun 1.3.14, 1M-iteration median).
+
+It extends `AbstractLogger` and implements `ILogger`, so it works anywhere an `ILogger` is expected. But it stays entirely separate from the Winston-backed `Logger` pipeline - no formatters, transports, or `APP_ENV_LOGGER_*` env vars apply to it.
+
+Read the [HfLogger guide](/extensions/helpers/logger/hf-logger) before using it. It carries hard usage rules - a pre-encoded fixed message vocabulary, single-thread only, flush-interval sizing - and documented limitations.
 
 ```typescript
 import { HfLogger, HfLogFlusher } from '@venizia/ignis-helpers';
@@ -559,9 +705,9 @@ flusher.stop();
 | Method | Signature | Description |
 |--------|-----------|--------------|
 | `HfLogger.get` | `(scope: string) => HfLogger` | Get or create a cached logger instance (allocates the ring lazily on first call) |
-| `HfLogger.encodeMessage` | `(msg: string) => Uint8Array` | Pre-encode a message string to bytes; FIFO-bounded cache, cap `MESSAGE_CACHE_CAP = 4096` |
-| `logger.debug/info/warn/error/emerg` | `(message: string, ...args: AnyType[]) => void` | `ILogger` methods. No args: cache-lookup encode + bytes-path write. With args: `formatLogMessage` (deep inspection + redaction) then an uncached encode - the slow path |
-| `logger.log` | `(level: TLogLevel, message: string, ...args: AnyType[]) => void`<br>`(level: TLogLevel, messageBytes: Uint8Array) => void` | Overloaded: string form follows the `debug`/`info`/... cost model above; `Uint8Array` form is the legacy bytes hot path, unchanged signature |
+| `HfLogger.encodeMessage` | `(msg: string) => Uint8Array` | Pre-encode a message string to bytes. FIFO-bounded cache, capped at `MESSAGE_CACHE_CAP = 4096` |
+| `logger.debug/info/warn/error/emerg` | `(message: string, ...args: AnyType[]) => void` | `ILogger` methods. No args: cache-lookup encode, then the bytes-path write. With args: `formatLogMessage` (deep inspection, redaction), then an uncached encode - the slow path |
+| `logger.log` | `(level: TLogLevel, message: string, ...args: AnyType[]) => void`<br>`(level: TLogLevel, messageBytes: Uint8Array) => void` | Overloaded. The string form follows the `debug`/`info`/... cost model above. The `Uint8Array` form is the legacy bytes hot path, unchanged |
 | `logger.for` | `(methodName: string) => ILogger` | Returns `HfLogger.get(`${scope}-${methodName}`)`, same dash composition as `BaseLogger` |
 
 Supported levels (`TLogLevel`, full set): `debug` (0), `info` (1), `warn` (2), `error` (3), `emerg` (4).
@@ -570,12 +716,22 @@ Supported levels (`TLogLevel`, full set): `debug` (0), `info` (1), `warn` (2), `
 
 | Method | Signature | Description |
 |--------|-----------|--------------|
-| `new HfLogFlusher` | `(options?: IHfLogFlusherOptions) => HfLogFlusher` | `sink?: THfSink` (full custom delivery), `filePath?: string` (default sink appends here instead of stdout), `batchSize?: number` (entries rendered per batch before yielding, default `1024`; invalid values fall back with a `console.warn`) |
-| `flusher.flush` | `() => Promise<void>` | Drain the full backlog in bounded batches, yielding (`setImmediate`) between batches; re-entrant calls return the in-progress promise |
-| `flusher.start` | `(intervalMs?: number) => void` | Start a background `setInterval` flush loop (default `100`ms), unref'd so it never blocks process exit; idempotent - calling again restarts cleanly |
+| `new HfLogFlusher` | `(options?: IHfLogFlusherOptions) => HfLogFlusher` | Create a flusher; see `IHfLogFlusherOptions` below |
+| `flusher.flush` | `() => Promise<void>` | Drain the full backlog in bounded batches, yielding (`setImmediate`) between batches. Re-entrant calls return the in-progress promise |
+| `flusher.start` | `(intervalMs?: number) => void` | Start a background `setInterval` flush loop (default `100`ms), unref'd so it never blocks process exit. Idempotent - calling again restarts cleanly |
 | `flusher.stop` | `() => void` | Clear the interval started by `start()` |
 
-`THfSinkBatch` passed to a custom `sink`: `{ lines: Array<string>; dropped: number }` - `dropped` is the exact count of entries overwritten by the ring before the flusher could read them since the previous batch (see "Lap accounting" in the guide). The default sink (no `filePath`) writes `process.stdout.write(...)` once per batch; with `filePath`, it appends via `fs.appendFileSync` once per batch. A sink that throws is logged via `console.error` and does not abort the drain.
+#### IHfLogFlusherOptions
+
+| Option | Type | Default | Meaning |
+|--------|------|---------|---------|
+| `sink` | `THfSink` | the built-in stdout/file sink | Full custom delivery. Overrides `filePath` |
+| `filePath` | `string` | _(unset)_ | The default sink appends here instead of writing to stdout |
+| `batchSize` | `number` | `1024` | Entries rendered per batch before yielding. An invalid value falls back to the default with a `console.warn` |
+
+A custom `sink` receives `THfSinkBatch`: `{ lines: Array<string>; dropped: number }`. `dropped` is the exact count of entries the ring overwrote before the flusher could read them, since the previous batch. See "Lap accounting" in the [HfLogger guide](/extensions/helpers/logger/hf-logger).
+
+The default sink writes `process.stdout.write(...)` once per batch, or `fs.appendFileSync` once per batch when `filePath` is set. A sink that throws is logged via `console.error` and does not abort the drain.
 
 ### Line format
 
@@ -585,11 +741,17 @@ The default sink renders each entry as:
 <ISO timestamp> [<level name>] <scope> <message>
 ```
 
-For example: `2026-07-18T09:41:03.128Z [info] OrderEngine Order sent`. When a batch has `dropped > 0`, the default sink emits a `warn` marker line ahead of it: `<ISO timestamp> [warn] HfLogFlusher ring lapped - <N> entries overwritten before they could be read`.
+For example: `2026-07-18T09:41:03.128Z [info] OrderEngine Order sent`.
+
+When a batch has `dropped > 0`, the default sink emits a `warn` marker line ahead of it:
+
+```
+<ISO timestamp> [warn] HfLogFlusher ring lapped - <N> entries overwritten before they could be read
+```
 
 ### Ring buffer entry format
 
-Each entry occupies exactly 256 bytes in a 64K-entry (16MB) `ArrayBuffer`, allocated lazily on the first `HfLogger.get()` call (not at module import) and shared module-wide (not per-`HfLogger` instance):
+Each entry occupies exactly 256 bytes, inside a 64K-entry (16MB) `ArrayBuffer`. That buffer allocates lazily on the first `HfLogger.get()` call - not at module import - and is shared module-wide, not per-`HfLogger` instance:
 
 | Offset | Size | Field |
 |--------|------|-------|
@@ -600,10 +762,12 @@ Each entry occupies exactly 256 bytes in a 64K-entry (16MB) `ArrayBuffer`, alloc
 | 42 | 1 byte | Message length (0-213) |
 | 43-255 | 213 bytes | Message bytes |
 
-The explicit length bytes are what make reads exact: the flusher decodes only the bytes a field actually holds, so there is no NUL padding and no stale tail from a previous, longer entry in a reused slot. The buffer wraps around at 65,536 entries using bitwise AND masking (`writeIndex & (BUFFER_SIZE - 1)`); when the producer writes faster than the flusher drains, unflushed entries are overwritten, and the overwritten count is reported via `dropped` on the next sink batch rather than silently emitted.
+The explicit length bytes are what make reads exact. The flusher decodes only the bytes a field actually holds. That leaves no NUL padding and no stale tail from a longer entry that used to occupy the slot.
+
+The buffer wraps at 65,536 entries, using bitwise AND masking (`writeIndex & (BUFFER_SIZE - 1)`). When the producer writes faster than the flusher drains, unflushed entries get overwritten. That loss is never silent - the overwritten count is reported via `dropped` on the next sink batch.
 
 > [!WARNING]
-> Pre-encode messages at initialization time using `HfLogger.encodeMessage()` or by calling a no-args `ILogger` method once per distinct message. Calling either with dynamic, per-event strings puts UTF-8 encoding on the hot path and can evict other cached messages once the FIFO-bounded cache (4096 entries) fills.
+> Pre-encode messages at initialization time using `HfLogger.encodeMessage()` or by calling a no-args `ILogger` method once per distinct message. Calling either with dynamic, per-event strings puts UTF-8 encoding on the hot path. It can also evict other cached messages once the FIFO-bounded cache (4096 entries) fills.
 
 ## Environment Variables
 
@@ -616,10 +780,35 @@ The explicit length bytes are what make reads exact: the flusher decodes only th
 | `NODE_ENV` | _(unset)_ | Must be in `COMMON_ENVS` or unset for debug to activate |
 | `APP_ENV_EXTRA_LOG_ENVS` | _(empty)_ | Comma-separated additional environments to allow debug |
 | `APP_ENV_LOGGER_FORMAT` | `text` | Output format (`json` or `text`) |
-| `APP_ENV_LOGGER_LEVEL` | `debug` | Logger-level floor; transports without their own level inherit it. Invalid values fall back to `debug` with a console warning |
-| `APP_ENV_LOGGER_FOLDER_PATH` | _(unset)_ | Log files directory; file logging is OFF when unset |
-| `APP_ENV_LOGGER_INSPECT_DEPTH` | `5` | Object inspection depth for `%s` placeholders. Non-negative integer only; invalid or absent falls back to `5` |
-| `APP_ENV_LOGGER_DO_REDACT` | `true` | Secret redaction in log arguments. ONLY the literal `false` disables it - raw values (passwords, tokens, connection URLs) then reach the sinks. Any other value, unset included, keeps redaction ON. Never disable in production |
+| `APP_ENV_LOGGER_LEVEL` | `debug` | Logger-level floor. Transports without their own level inherit it. Invalid values fall back to `debug` with a console warning |
+| `APP_ENV_LOGGER_FOLDER_PATH` | _(unset)_ | Log files directory. File logging is OFF when unset |
+| `APP_ENV_LOGGER_INSPECT_DEPTH` | `5` | Object inspection depth for `%s` placeholders. Non-negative integer only - invalid or absent falls back to `5` |
+| `APP_ENV_LOGGER_DO_REDACT` | `true` | Secret redaction in log arguments. See the warning below before touching this |
+| `APP_ENV_LOGGER_COLOR` | _(unset)_ | ANSI color on console log lines. Unset means auto - see [Color](#color) |
+
+> [!WARNING]
+> Only the literal string `false` disables `APP_ENV_LOGGER_DO_REDACT`. Any other value - including unset - keeps redaction ON. Once disabled, raw secrets (passwords, tokens, connection URLs) reach the log sinks. Never disable this in production.
+
+### Color
+
+Color is a terminal affordance. In a deployed environment the same bytes land in a file or an aggregator as escape noise, so IGNIS turns color off outside a development `NODE_ENV`.
+
+The first rule that matches wins:
+
+| Rule | Result |
+|------|--------|
+| `APP_ENV_LOGGER_COLOR` is set | That value. `false` or `0` is off, anything else is on |
+| `NO_COLOR` is set and non-empty | Off ([no-color.org](https://no-color.org)) |
+| `NODE_ENV` is `local`, `debug`, `development`, `dev` or `sit` - or unset | On |
+| Anything else, including `production`, `staging`, `uat` and unrecognized names | Off |
+
+To keep color in a production terminal, set it back explicitly:
+
+```bash
+APP_ENV_LOGGER_COLOR=true
+```
+
+The file and UDP transports never colorize, in any environment. Under the pino provider the rule is a veto only: when it allows color, `pino-pretty` still suppresses it if stdout is not a terminal.
 
 ### File rotation
 
@@ -678,6 +867,8 @@ APP_ENV_LOGGER_DGRAM_LEVELS=error,warn,info
 | `ILoggerProvider` | interface | Static-side contract a provider class satisfies (`get(scope): ILogger`) |
 | `HfLogger` | class | `ILogger`-conformant ring-buffer logger for hot paths |
 | `HfLogFlusher` | class | Background flusher for `HfLogger` |
+| `ErrorPrettier` | class (statics) | `format({ error })` renders a thrown value as a readable block; `summarize({ error })` returns it as `IErrorSummary` |
+| `IErrorSummary` | interface | The projection `summarize` returns - `name`, `message`, `code`, `stack` (frames only), the `pg` diagnostics, and a nested `cause` |
 | `LogLevels` | class (constants) | Log level constants (`ERROR`, `EMERG`, `WARN`, `INFO`, `DEBUG`) with `isValid()` |
 | `LoggerFormats` | class (constants) | Format constants (`JSON`, `TEXT`) with `isValid()` |
 | `defineCustomLogger` | `(opts: ICustomLoggerOptions) => winston.Logger` | Create a fully configured Winston logger |
@@ -703,7 +894,7 @@ APP_ENV_LOGGER_DGRAM_LEVELS=error,warn,info
 **Fix:**
 1. Verify `DEBUG=true` is set in your environment.
 2. Verify `NODE_ENV` is set to one of: `local`, `debug`, `development`, `dev`, `sit`, `uat`, `alpha`, `beta`, `staging`, `production` - or is unset entirely.
-3. If you use a custom environment name (e.g. `qa`), add it to `APP_ENV_EXTRA_LOG_ENVS=qa`.
+3. If you use a custom environment name (for example, `qa`), add it to `APP_ENV_EXTRA_LOG_ENVS=qa`.
 
 ```bash
 DEBUG=true NODE_ENV=development bun run server:dev
@@ -725,7 +916,7 @@ APP_ENV_LOGGER_FORMAT=text
 
 **Fix:**
 1. Ensure **all four** dgram env vars are set: `APP_ENV_LOGGER_DGRAM_HOST`, `APP_ENV_LOGGER_DGRAM_PORT`, `APP_ENV_LOGGER_DGRAM_LABEL`, and `APP_ENV_LOGGER_DGRAM_LEVELS`.
-2. `APP_ENV_LOGGER_DGRAM_LEVELS` must contain at least one level (e.g. `error,warn,info`). An empty value results in no transport.
+2. `APP_ENV_LOGGER_DGRAM_LEVELS` must contain at least one level (for example, `error,warn,info`). An empty value results in no transport.
 3. Verify the UDP aggregator is reachable from your host (firewall, port binding).
 
 ### Log label shows "APP" instead of application name