@venizia/ignis-docs 0.2.0 → 0.2.1-0

package/content/best-practices/error-handling.md

@@ -24,24 +24,67 @@ throw getError({
   message: 'User not found',
 });
 
-// Error with details
+// Error with context - any key the framework does not model lands in `extra`
 throw getError({
   statusCode: HTTP.ResultCodes.RS_4.BadRequest,
   message: 'Invalid request',
-  details: {
-    field: 'email',
-    reason: 'Must be a valid email address',
-  },
+  details: { field: 'email', reason: 'Must be a valid email address' },
+});
+// -> error.extra.details
+
+// The same thing, explicit. Prefer this when the context could be mistaken for a field.
+throw getError({
+  statusCode: HTTP.ResultCodes.RS_4.BadRequest,
+  message: 'Invalid request',
+  extra: { details: { field: 'email' } },
 });
 
-// Error with context (for logging)
+// Wrapping a lower-level failure - `cause` reaches the native Error.cause
 throw getError({
   statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
   message: '[UserService][create] Database connection failed',
-  details: { userId: requestedId },
+  cause: error,
+  extra: { userId: requestedId },
 });
 ```
 
+> [!NOTE]
+> Any key `getError` does not model rides into `extra` - that is how a throw site attaches context the framework knows nothing about. The trade is that a **misspelling** goes the same way: `getError({ message, statuscode: 503 })` compiles, `statusCode` stays `400`, and `503` sits in `extra.statuscode`. The framework cannot tell your context from your typo.
+
+### Catalogue a domain failure, raise the rest free-form
+
+The form above is right for a failure that carries no i18n code: an invariant, a misconfiguration, a seed guard. Nobody translates `'[UserService][create] Database connection failed'`.
+
+A **domain** failure - one a client localizes and branches on - belongs in a catalog instead. Retyping its code and status at each throw is how two call sites end up raising `category.create.duplicate_name` and `category.duplicate_name` for the same thing:
+
+```typescript
+import { ErrorScopes, getError, HTTP } from '@venizia/ignis-helpers';
+import type { TErrorDefinition, TRegisterErrors } from '@venizia/ignis-helpers';
+
+export const UserErrors = {
+  CREATE_DUPLICATE_EMAIL: {
+    message: {
+      text: 'An account with %{email} already exists.',
+      code: 'server.core.user.create.duplicate_email',
+    },
+    statusCode: HTTP.ResultCodes.RS_4.Conflict,
+    category: ErrorScopes.VALIDATION,
+    description: 'Sign-up rejected because the email is already registered.',
+  },
+} as const satisfies Record<string, TErrorDefinition>;
+
+declare module '@venizia/ignis-helpers' {
+  interface IErrorKeyRegistry extends TRegisterErrors<typeof UserErrors> {}
+}
+
+// At every throw site:
+throw getError({ error: UserErrors.CREATE_DUPLICATE_EMAIL, messageArgs: { email } });
+```
+
+Pass the definition as `error` - **never spread it**. `getError({ ...UserErrors.CREATE_DUPLICATE_EMAIL, messageArgs: { email } })` reads naturally and is wrong: spreading skips the `error:` field entirely, so `category` and `description` - fields only modeled inside a definition - fall through into `extra` instead of staying structured. `statusCode` and `message` happen to still resolve correctly only because their shapes collide with what `getError` expects standalone; nothing catches the rest for you.
+
+See the [Error helper reference](/extensions/helpers/error/) for the full surface.
+
 ## 2. HTTP Status Code Reference
 
 Use the correct status code for each error type:
@@ -90,9 +133,9 @@ export class UserService extends BaseService {
     try {
       await this.emailService.sendWelcome(data.email);
     } catch (error) {
-      // Log but don't fail user creation
+      // Log but don't fail user creation - never a silent catch
       this.logger.error('[createUser] Failed to send welcome email | email: %s | error: %s',
-        data.email, error.message);
+        data.email, error);
     }
 
     // create returns { count, data }
@@ -158,9 +201,18 @@ Database errors in SQLSTATE classes `22` (data exception), `23` (integrity const
 ```json
 {
   "message": "Unique constraint violation\nDetail: Key (email)=(test@example.com) already exists.\nTable: User\nConstraint: UQ_User_email",
-  "messageCode": "core.system_error",
   "statusCode": 400,
-  "requestId": "abc123"
+  "normalized": {
+    "text": "Unique constraint violation\nDetail: Key (email)=(test@example.com) already exists.\nTable: User\nConstraint: UQ_User_email",
+    "code": "core.system_error",
+    "args": {}
+  },
+  "requestId": "abc123",
+  "details": {
+    "url": "http://localhost:3000/users",
+    "path": "/users",
+    "stack": "Error: Unique constraint violation\n    at ..."
+  }
 }
 ```
 
@@ -168,18 +220,24 @@ Database errors in SQLSTATE classes `22` (data exception), `23` (integrity const
 In production the message is the **base message only** - `Detail:` (which echoes row values like emails), `Table:`, and `Constraint:` are stripped, and `details.stack`/`details.cause` are omitted. Unexpected (non-client) database errors and connection failures return a generic `"Internal Server Error"`, so SQL, schema names, and connection host/port never leak. Use `requestId` + server logs to diagnose.
 
 ```json
-{ "message": "Unique constraint violation", "messageCode": "core.system_error", "statusCode": 400, "requestId": "abc123" }
+{
+  "message": "Unique constraint violation",
+  "statusCode": 400,
+  "normalized": { "text": "Unique constraint violation", "code": "core.system_error", "args": {} },
+  "requestId": "abc123",
+  "details": { "url": "http://localhost:3000/users", "path": "/users" }
+}
 ```
 :::
 
 You don't need to wrap repository calls in try-catch for constraint errors. If you need custom error messages, you can still handle them explicitly:
 
 ```typescript
-import { DefaultCRUDRepository } from '@venizia/ignis';
+import { DefaultRelationalRepository, type TCount } from '@venizia/ignis';
 import { getError, HTTP } from '@venizia/ignis-helpers';
 
-export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
-  async createWithCustomError(data: TCreateUser): Promise<TCreateResult<TUser>> {
+export class UserRepository extends DefaultRelationalRepository<typeof User.schema> {
+  async createWithCustomError(data: TCreateUser): Promise<TCount & { data: TUser }> {
     try {
       return await this.create({ data });
     } catch (error) {
@@ -198,41 +256,43 @@ export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
 
 ## 4. Global Error Handler
 
-IGNIS includes a built-in error handler. Customize behavior in your application:
+IGNIS wires a built-in handler by default - `AppErrorMiddleware` from `@venizia/ignis` is a class, registered as `new AppErrorMiddleware({ logger, rootKey }).value()`, and `value()` returns the Hono `ErrorHandler`. You rarely need to replace it; when you do, keep the same response contract:
 
 ```typescript
 import { BaseApplication } from '@venizia/ignis';
-import { ApplicationError, MessageCode } from '@venizia/ignis-helpers';
+import { isApplicationError, MessageCode } from '@venizia/ignis-helpers';
 
 export class Application extends BaseApplication {
   override setupMiddlewares(): void {
     super.setupMiddlewares();
 
-    // Custom error handler (optional)
-    this.server.onError((error, c) => {
+    // Custom error handler (optional) - the default AppErrorMiddleware already does this.
+    // `this.server` is `{ hono, runtime, instance }` - reach the Hono app via getServer().
+    this.getServer().onError((error, c) => {
       const requestId = c.get('requestId') ?? 'unknown';
 
       // Log all errors
-      this.logger.error('[%s] Error | %s', requestId, error.message);
+      this.logger.error('[%s] Error | %s', requestId, error);
 
-      // Handle known application errors
-      if (error instanceof ApplicationError) {
+      // Handle known application errors - isApplicationError(), never `instanceof
+      // ApplicationError` (unreliable across package boundaries)
+      if (isApplicationError(error)) {
         return c.json({
           statusCode: error.statusCode,
           message: error.message,
-          messageCode: error.messageCode, // already lower-cased, never undefined
-          details: error.details,
+          normalized: error.normalized, // { text, code, args } - never undefined
+          extra: error.extra,
           requestId,
-        }, error.statusCode as StatusCode);
+        }, error.statusCode as Parameters<typeof c.json>[1]);
       }
 
-      // Handle Zod validation errors
+      // Handle Zod validation errors - Zod v4 exposes `issues`, not `errors`
       if (error.name === 'ZodError') {
         return c.json({
           statusCode: 422,
           message: 'Validation failed',
-          messageCode: MessageCode.DEFAULT,
-          details: { cause: error.errors },
+          normalized: { text: 'Validation failed', code: MessageCode.DEFAULT, args: {} },
+          details: { cause: error.issues },
           requestId,
         }, 422);
       }
@@ -241,7 +301,7 @@ export class Application extends BaseApplication {
       return c.json({
         statusCode: 500,
         message: 'Internal server error',
-        messageCode: MessageCode.DEFAULT,
+        normalized: { text: 'Internal server error', code: MessageCode.DEFAULT, args: {} },
         requestId,
       }, 500);
     });
@@ -257,51 +317,61 @@ All errors should follow a consistent format:
 interface ErrorResponse {
   statusCode: number;
   message: string;
-  messageCode?: string; // stable, localizable code (validation: from params.code or the raw Zod code)
+  normalized: {
+    text: string;
+    code: string; // stable, localizable code (validation: from params.code or the raw Zod code)
+    args: Record<string, unknown>;
+  };
   requestId: string;
   extra?: Record<string, unknown>; // structured context attached via getError(...)
-  details?: {
-    cause?: Array<{
-      path: string;
-      message: string;
-      code: string;
-    }>;
+  details: {
+    url: string;
+    path: string;
+    stack?: string; // non-production only
+    cause?: unknown; // non-production only, or the Zod issue list for 422s
     [key: string]: unknown;
   };
 }
 ```
 
+There is no top-level `messageCode` - read `normalized.code`. `extra` never mirrors `messageArgs`; the resolved interpolation values live at `normalized.args`.
+
 **Example Responses:**
 
 ```json
 // 400 Bad Request
 {
-  "statusCode": 400,
   "message": "Invalid request body",
-  "messageCode": "core.system_error",
-  "requestId": "abc123"
+  "statusCode": 400,
+  "normalized": { "text": "Invalid request body", "code": "core.system_error", "args": {} },
+  "requestId": "abc123",
+  "details": { "url": "http://localhost:3000/users", "path": "/users" }
 }
 
 // 404 Not Found
 // Extra keys passed to getError(...) (e.g. `details`) surface under `extra`;
 // the top-level `details` object is reserved for middleware context (url, path, stack, cause).
 {
-  "statusCode": 404,
   "message": "User not found",
-  "messageCode": "core.system_error",
+  "statusCode": 404,
+  "normalized": { "text": "User not found", "code": "core.system_error", "args": {} },
   "requestId": "abc123",
-  "extra": { "details": { "id": "user-uuid" } }
+  "extra": { "details": { "id": "user-uuid" } },
+  "details": { "url": "http://localhost:3000/users/user-uuid", "path": "/users/:id" }
 }
 
 // 422 Validation Error
-// `message`/`messageCode` come from the first failing issue - its `params.code` if the schema set
-// one, otherwise the raw Zod code (e.g. `invalid_type`, `too_small`). The full list stays in `details.cause`.
+// `message`/`normalized.code` come from the first failing issue - its `params.code` if the schema
+// set one, otherwise the raw Zod code (e.g. `invalid_type`, `too_small`). `normalized.args` is
+// always empty for a Zod issue; the full list of issues stays in `details.cause`.
 {
-  "statusCode": 422,
   "message": "Invalid email format",
-  "messageCode": "user.email.invalid",
+  "statusCode": 422,
+  "normalized": { "text": "Invalid email format", "code": "user.email.invalid", "args": {} },
   "requestId": "abc123",
   "details": {
+    "url": "http://localhost:3000/users",
+    "path": "/users",
     "cause": [
       {
         "path": "email",
@@ -314,10 +384,11 @@ interface ErrorResponse {
 
 // 500 Internal Error (production)
 {
-  "statusCode": 500,
   "message": "Internal server error",
-  "messageCode": "core.system_error",
-  "requestId": "abc123"
+  "statusCode": 500,
+  "normalized": { "text": "Internal server error", "code": "core.system_error", "args": {} },
+  "requestId": "abc123",
+  "details": { "url": "http://localhost:3000/orders", "path": "/orders" }
 }
 ```
 
@@ -325,27 +396,27 @@ interface ErrorResponse {
 
 ### `%s`, Never `%j`, for an `Error`
 
-`message` and `stack` are non-enumerable properties on a native `Error` (and on `ApplicationError`, which extends it). `%j` serializes via `JSON.stringify`, which only visits enumerable own properties - so `logger.error('... | error: %j', error)` silently drops both `message` and `stack`, logging little more than `{}`. Always use `%s` to log an `Error` instance; reserve `%j`/`%o` for plain data objects.
+`message` and `stack` are non-enumerable properties on a native `Error` (and on `ApplicationError`, which extends it). `%j` serializes via `JSON.stringify`, which only visits enumerable own properties - so `logger.error('... | error: %j', error)` silently drops both. Always use `%s` to log an `Error` instance; reserve `%j`/`%o` for plain data objects.
 
 ```typescript
 // ✅ Good - %s prints message + stack
 this.logger.error('[createOrder] Failed | error: %s', error);
 
-// ❌ Bad - %j drops message and stack (non-enumerable)
+// ❌ Bad - %j drops the stack
 this.logger.error('[createOrder] Failed | error: %j', error);
 ```
 
+> [!NOTE]
+> An `ApplicationError` logged with `%j` does show its message text, because the text rides inside the enumerable `normalized.text`. That is incidental, not a reprieve: the **stack** is still gone, which is the reason the rule exists. A plain `Error` under `%j` still logs little more than `{}`.
+
 ### What to Log
 
 ```typescript
-// ✅ Good - Context for debugging
+// ✅ Good - Context for debugging. `%s` on the error itself carries message + stack
 this.logger.error('[createOrder] Failed | userId: %s | orderId: %s | error: %s',
-  userId, orderId, error.message);
-
-// ✅ Good - Include stack trace for unexpected errors
-this.logger.error('[createOrder] Unexpected error | %s', error.stack);
+  userId, orderId, error);
 
-// ❌ Bad - No context
+// ❌ Bad - No context, and `.message` throws the stack away
 this.logger.error(error.message);
 
 // ❌ Bad - Sensitive data
@@ -354,12 +425,15 @@ this.logger.error('Login failed for user | password: %s', password);
 
 ### Log Levels
 
+`ILogger` has exactly five levels, each a direct method. `alert`, `http`, `verbose` and `silly` do not exist.
+
 | Level | Use For |
 |-------|---------|
+| `emerg` | The process cannot continue - unrecoverable |
 | `error` | Exceptions that need attention |
 | `warn` | Recoverable issues, deprecation warnings |
 | `info` | Important business events |
-| `debug` | Detailed debugging information |
+| `debug` | Detailed debugging information (gated on `DEBUG`) |
 
 ```typescript
 // Error - requires attention
@@ -381,30 +455,29 @@ this.logger.debug('[query] Executing | sql: %s | params: %j', sql, params);
 
 ```typescript
 // ✅ Good - Errors propagate naturally with async/await
-async function processOrder(orderId: string) {
+const processOrder = async (orderId: string) => {
   const order = await orderRepository.findById({ id: orderId }); // Throws if fails
-  const payment = await paymentService.charge(order); // Throws if fails
-  return payment;
-}
+  return paymentService.charge(order); // Throws if fails
+};
 
 // ✅ Good - Explicit catch when you need to handle
-async function processOrderWithFallback(orderId: string) {
+const processOrderWithFallback = async (order: TOrder) => {
   try {
     return await paymentService.charge(order);
   } catch (error) {
-    this.logger.warn('[processOrder] Primary payment failed, trying backup');
-    return await backupPaymentService.charge(order);
+    this.logger.warn('[processOrder] Primary payment failed, trying backup | error: %s', error);
+    return backupPaymentService.charge(order);
   }
-}
+};
 
 // ❌ Bad - Swallowing errors
-async function processOrder(orderId: string) {
+const processOrderSilently = async () => {
   try {
     await dangerousOperation();
   } catch (error) {
     // Error is swallowed - no one knows it happened!
   }
-}
+};
 ```
 
 ### Fire-and-Forget with Error Handling
@@ -412,7 +485,7 @@ async function processOrder(orderId: string) {
 ```typescript
 // ✅ Good - Log errors from fire-and-forget operations
 this.sendNotification(userId).catch(error => {
-  this.logger.error('[notify] Failed | userId: %s | error: %s', userId, error.message);
+  this.logger.error('[notify] Failed | userId: %s | error: %s', userId, error);
 });
 
 // ✅ Good - Use void to indicate intentional fire-and-forget
@@ -425,35 +498,44 @@ this.sendNotification(userId); // If this rejects, crash!
 ## 8. Transaction Error Handling
 
 ```typescript
-async function transferFunds(from: string, to: string, amount: number) {
-  const tx = await accountRepository.beginTransaction();
+import { getError, HTTP } from '@venizia/ignis-helpers';
+
+const transferFunds = async (opts: { from: string; to: string; amount: number }) => {
+  const { from, to, amount } = opts;
+  const transaction = await accountRepository.beginTransaction();
 
   try {
-    await accountRepository.debit({ id: from, amount, options: { transaction: tx } });
-    await accountRepository.credit({ id: to, amount, options: { transaction: tx } });
+    await accountRepository.debit({ id: from, amount, options: { transaction } });
+    await accountRepository.credit({ id: to, amount, options: { transaction } });
 
-    await tx.commit();
+    await transaction.commit();
     return { success: true };
   } catch (error) {
-    await tx.rollback();
+    await transaction.rollback();
 
     // Re-throw with context
     throw getError({
       statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
       message: '[transferFunds] Transaction failed',
-      details: { from, to, amount, originalError: error.message },
+      cause: error,
+      extra: { from, to, amount },
     });
   }
-}
+};
 ```
 
+> [!NOTE]
+> `rollback()` throws on failure, so it belongs in the `catch` exactly as above - never after a
+> `commit()` you already awaited outside one. A rollback that follows a **failed** commit is a
+> deliberate no-op: the transaction is already torn down, so this canonical shape stays safe.
+
 ## 9. Client-Side Error Handling
 
 Guide for API consumers:
 
 ```typescript
 // TypeScript client example
-async function createUser(data: CreateUserRequest): Promise<User> {
+const createUser = async (data: TCreateUserRequest): Promise<TUser> => {
   const response = await fetch('/api/users', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
@@ -463,31 +545,38 @@ async function createUser(data: CreateUserRequest): Promise<User> {
   if (!response.ok) {
     const error = await response.json();
 
+    // Branch on `normalized.code` - it is always present. There is no top-level `messageCode`.
     switch (response.status) {
-      case 400:
-        throw new ValidationError(error.message, error.details);
-      case 401:
-        // Redirect to login
+      case 400: {
+        // Context passed to getError(...) arrives under `extra`, not `details`
+        throw new ValidationError(error.message, error.extra);
+      }
+      case 401: {
         window.location.href = '/login';
         throw new AuthError('Please log in');
-      case 404:
+      }
+      case 404: {
         throw new NotFoundError(error.message);
-      case 422:
-        // Handle field-level errors
-        const fieldErrors = error.details?.cause?.reduce((acc, e) => {
-          acc[e.path] = e.message;
-          return acc;
+      }
+      case 422: {
+        // Field-level issues live in details.cause
+        const fieldErrors = error.details?.cause?.reduce((accumulator, issue) => {
+          accumulator[issue.path] = issue.message;
+          return accumulator;
         }, {});
-        throw new ValidationError('Validation failed', fieldErrors);
-      case 429:
+        throw new ValidationError(error.normalized.code, fieldErrors);
+      }
+      case 429: {
         throw new RateLimitError('Too many requests. Try again later.');
-      default:
+      }
+      default: {
         throw new ApiError(error.message || 'Something went wrong');
+      }
     }
   }
 
   return response.json();
-}
+};
 ```
 
 ## Error Handling Checklist
@@ -495,7 +584,7 @@ async function createUser(data: CreateUserRequest): Promise<User> {
 | Category | Check |
 |----------|-------|
 | **Services** | Business rule violations throw appropriate errors |
-| **Repositories** | Database errors are caught and wrapped |
+| **Repositories** | Constraint errors left to the global handler; only custom messages wrapped |
 | **Controllers** | Errors propagate to global handler |
 | **Async** | All promises have error handling |
 | **Transactions** | Always rollback on error |

package/content/best-practices/index.md

@@ -102,6 +102,9 @@ Controller → Service → Repository → DataSource
 // ✅ Error Handling
 throw getError({ statusCode: 404, message: 'User not found' });
 
+// ✅ Scoped Logging (ILogger - never names a provider)
+this.logger.for('createUser').info('User created | id: %s', user.id);
+
 // ✅ Input Validation
 request: { body: jsonContent({ schema: z.object({ email: z.string().email() }) }) }
 ```
@@ -120,6 +123,9 @@ async getUser(c: Context) {
 // ❌ Catching all errors silently
 try { await riskyOperation(); } catch (e) { /* swallowed */ }
 
+// ❌ Raw Error - loses statusCode, messageCode and the normalized response shape
+throw new Error('User not found'); // Use getError()
+
 // ❌ Using `any` type
 const data: any = await fetchData(); // Use proper types!
 ```

package/content/best-practices/performance-optimization.md

@@ -9,6 +9,7 @@ Identify bottlenecks before optimizing:
 ```typescript
 import { executeWithPerformanceMeasure } from '@venizia/ignis-helpers';
 
+// `logger` is optional and typed `ILogger` - it falls back to `console` when omitted.
 await executeWithPerformanceMeasure({
   logger: this.logger,
   scope: 'DataProcessing',
@@ -148,13 +149,22 @@ if (!cached) {
 
 | Setting | Value | Why |
 |---------|-------|-----|
-| `NODE_ENV` | `production` | Enables library optimizations |
-| Process Manager | PM2, systemd, Docker | Auto-restart, cluster mode |
-| Cluster Mode | CPU cores | Utilize all CPUs |
+| `NODE_ENV` | `production` | Enables library optimizations; also gates error-detail leakage (unset is treated as production) |
+| `APP_ENV_LOGGER_LEVEL` | `info` or `warn` | Keep hot-path logging off the critical path |
+| Process Manager | systemd, Docker, Kubernetes | Auto-restart, supervision |
+| Horizontal Scaling | One process per CPU core | Utilize all CPUs |
+
+Bun has no PM2-style cluster mode, and `Bun.serve` is started without `reusePort` - two processes cannot share a port. Scale out with one process per port behind a reverse proxy, or with container replicas:
+
+```bash
+# Each replica binds its own port; nginx / a load balancer fans out across them
+APP_ENV_SERVER_PORT=3000 NODE_ENV=production bun run dist/index.js &
+APP_ENV_SERVER_PORT=3001 NODE_ENV=production bun run dist/index.js &
+```
 
-**PM2 Cluster Mode:**
 ```bash
-pm2 start dist/index.js -i max  # Use all CPU cores
+# Or let the orchestrator do it
+docker compose up -d --scale app=4
 ```
 
 ## 6. Transaction Support
@@ -208,12 +218,12 @@ Connection pooling significantly improves performance by reusing database connec
 ```typescript
 import { Pool } from 'pg';
 import { datasource } from '@venizia/ignis';
-import { BasePostgresDataSource } from '@venizia/ignis/postgres';
+import { BaseRelationalDataSource } from '@venizia/ignis/postgres';
 import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
 
 // IDataSourceConfigs: your settings interface (host/port/user/password/database)
 @datasource({ driver: NodePostgresDriver })
-export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfigs> {
+export class PostgresDataSource extends BaseRelationalDataSource<IDataSourceConfigs> {
   override configure(): void {
     // Keep the pool on `this.client` - NodePostgresDriver above wires the driver and Drizzle
     // connector from it lazily, on first getConnector()/beginTransaction()
@@ -385,9 +395,9 @@ const logger = HfLogger.get('OrderEngine');
 const MSG_ORDER_SENT = HfLogger.encodeMessage('Order sent');
 const MSG_ORDER_FILLED = HfLogger.encodeMessage('Order filled');
 
-// Start background flusher
+// Start background flusher (writes to stdout by default; pass { filePath } or { sink })
 const flusher = new HfLogFlusher();
-flusher.start(100); // Flush every 100ms
+flusher.start(100); // Flush interval in ms - 100 is also the default
 
 // In hot path (~100-300ns, zero allocation):
 logger.log('info', MSG_ORDER_SENT);
@@ -395,11 +405,14 @@ logger.log('info', MSG_ORDER_FILLED);
 ```
 
 **Key points:**
+- `log(level, bytes)` is the zero-allocation path. Passing a string, or any `...args`, falls back to formatting
+- Levels are the same five as `ILogger`: `debug`, `info`, `warn`, `error`, `emerg`
 - Pre-encode messages at initialization, not in hot path
-- Use background flushing to avoid I/O blocking
-- HfLogger uses a lock-free ring buffer (64K entries, 16MB)
+- HfLogger uses a lock-free ring buffer (64K entries x 256 bytes = 16MB), allocated lazily on first use
+- Scope truncates at 32 UTF-8 bytes, message at 213 - silently
+- For the standard logger, narrow output with `APP_ENV_LOGGER_LEVEL` in production and keep debug lines behind the `DEBUG` gate (pre-computed at module load, near-zero cost when off)
 
-> **Deep Dive:** See [Logger Helper](../extensions/helpers/logger/) for complete HfLogger API.
+> **Deep Dive:** See [HfLogger](../extensions/helpers/logger/hf-logger.md) for the complete API.
 
 ## Performance Checklist
 
@@ -414,7 +427,7 @@ logger.log('info', MSG_ORDER_FILLED);
 | **Memory** | Large datasets processed in batches | High |
 | **Caching** | Expensive queries cached | High |
 | **Workers** | CPU-intensive tasks offloaded | High |
-| **Logging** | HfLogger for hot paths (HFT) | High |
+| **Logging** | HfLogger for hot paths (HFT); `APP_ENV_LOGGER_LEVEL` in production | High |
 | **Monitoring** | Performance logging enabled | Low |
 
 ## See Also