@stonyx/logs 1.0.1-beta.18 → 1.0.1-beta.19

package/README.md

@@ -57,7 +57,11 @@ const log = new Log();
 
 log.info('Info: sample application has started');
 log.warn('Warning: this is just a sample');
-log.error('Error: no application logic detected', true); // logs to logs/error.log file
+
+// logs to logs/error.log; a failed write rejects, and handling that rejection is required
+// see "Handling write failures" below
+log.error('Error: no application logic detected', true)
+  .catch(err => { /* err.code is the underlying fs error code, e.g. 'EACCES' */ });
 ```
 
 Easily define your own logging mechanism and color-coding preference:
@@ -91,8 +95,15 @@ const log = new Log({
   suffix: '\n=============================================================== \n',
 });
 
-log.info('Info: sample application has started');
+log.info('Info: sample application has started')
+  .catch(err => { /* see "Handling write failures" */ });
 ```
+
+> **Caveat:** with `logToFileByDefault: true`, every log call *except* [`debug()`](#the-debug-method)
+> becomes a file write, and therefore returns a promise that can reject. A failing log directory turns
+> an unhandled `log.info()` into a process-terminating rejection. See
+> [handling write failures](#handling-write-failures).
+
 ![](https://github.com/abofs/stonyx-logs/raw/main/media/examples/custom-options.jpg)
 
 
@@ -107,6 +118,7 @@ const log = new Log({ additionalLogs: { question: 'green' } });
 log.defineType('query', log.chalk().black.bgGreen);
 
 log.question('What will a fully custom chalk color function look like?');
+// second argument writes to file, so this can reject -- see "Handling write failures"
 await log.query('This is what a custom chalk color setting looks like', true);
 ```
 ![](https://github.com/abofs/stonyx-logs/raw/main/media/examples/additional-logs.jpg)
@@ -153,13 +165,20 @@ These methods can then be called in your application with [logging parameters](#
 
 Color settings are handled by determining whether your input is a color name or a hex value (prefixed with **#**). For example, passing `red` as a color setting will utilize `chalk.red`, while passing `#ff0000` would use `chalk.hex('#ff0000')` instead. A [list of available colors](https://github.com/chalk/chalk#colors) can be found in chalks' documentation.
 
-Additionally, these methods return a promise when `logToFile` is true, allowing you use them with `await` in an async method, or append `then(), catch(), or finally()` for more advanced callback usage.
+Additionally, these methods return a promise when `logToFile` is true, allowing you to use them with `await` in an async method, or to append `then()`, `catch()` or `finally()`.
+
+When `logToFile` is true that promise **can reject**, and handling the rejection is **required** --
+see [handling write failures](#handling-write-failures) for the full contract.
 
 ```js
 async method() {
-  await log.error('error message', true);
+  try {
+    await log.error('error message', true);
 
-  // do something after logs/error.log (default) is created
+    // do something after logs/error.log (default) is created
+  } catch (err) {
+    // err.code is the underlying fs error code, e.g. 'EACCES'
+  }
 }
 ```
 
@@ -177,6 +196,11 @@ JSON.stringify(content, null, 2);
 
 We believe that when wanting to output complicated objects or debug **typescript** applications, there are better methods than utilizing this **Log** package. But for anyone who's fully incorporated **Log** into their project, this function offers some convenience.
 
+`debug(content, logToFile)` writes to file on the same contract as every other log type -- a failed
+write rejects with the underlying `fs` error and must be handled -- with one difference: `debug()`
+ignores [`logToFileByDefault`](#configuration), so it writes to file only when you pass `true`.
+See [handling write failures](#handling-write-failures).
+
 ### Logging Parameters
 
 ```js
@@ -186,10 +210,161 @@ log.error('error message', true, false); // content, logToFile, overwrite
 | Parameter | Type | Default | Description |
 | :---: | :---: | :---: | :--- |
 | `content` | **String** | | Content of log that will output on your console. |
-| `logToFile` | **Boolean** | *false* | Option to log content to file. |
+| `logToFile` | **Boolean** | *false* | Option to log content to file. When true, the call returns a promise that rejects if the write fails -- see [handling write failures](#handling-write-failures). |
 | `overwrite` | **Boolean** | *false <br> (true on debug())* | Option to overwrite log file, rather than append to it. This option is redundant if logToFile is false.  |
 
 **logToFile** will log to *<project-root>/logs* unless [configured](#configuration) differently during instantiation. <br>
+
+### Handling Write Failures
+
+Any call that writes to a file returns a promise that **rejects when the write fails**. That covers
+`log.error(content, true)`, `log.debug(content, true)`, and every log call except `debug()` when
+[`logToFileByDefault`](#configuration) is `true` -- `debug()` is a direct method that never consults
+`logToFileByDefault`, so it only writes to file when you pass `true` explicitly.
+
+That rejection is the only actionable failure signal, so every file-writing call must be awaited
+inside `try`/`catch`, or have `.catch()` attached. The console line is written *before* the file
+write is attempted, so a rejection means only the file copy was lost -- do not re-log the message in
+your handler, or it prints twice.
+
+> **A rejection is terminal. Do not retry it.**
+>
+> For the recoverable directory-level codes -- `ENOENT`, `EACCES`, `EPERM`, `EROFS` -- **Log** has
+> already retried internally by the time the rejection reaches you (see
+> [self-healing retry](#self-healing-retry) below), so that retry ran and failed too. Every other
+> code -- `EISDIR`, `ENOTDIR` and `ENOSPC` among them -- is not itself retried, because a retry
+> cannot help it. Either way a consumer-side retry layer races the internal self-heal or repeats a call that
+> already cannot succeed, and only delays the disable or back-off that your error path exists to
+> trigger.
+>
+> Treat the **first** rejection as the signal to disable file logging or back off, and do not attempt
+> the write again straight away. If you do want file logging to come back without a restart, re-arm
+> on a timer -- see [recovering after a latch](#recovering-after-a-latch).
+
+#### What the Promise Rejects With
+
+The rejection value is the underlying Node `fs` error - a `NodeJS.ErrnoException` passed through
+unmodified, with `err.code`, `err.syscall`, `err.errno` and `err.path` all preserved.
+
+```js
+try {
+  await log.error('error message', true);
+} catch (err) {
+  // err.code is the underlying fs error code, e.g. 'EACCES'
+  // err.syscall is the failing call, e.g. 'mkdir' or 'open'
+}
+```
+
+Codes you are most likely to see are `EACCES` and `EPERM` (no permission to create the log directory
+or write the log file), `ENOENT` (the directory disappeared and could not be recreated) and `EROFS`
+(read-only filesystem) - but any error the filesystem raises reaches the caller as-is.
+
+**An unhandled rejection terminates your process** under Node's default `--unhandled-rejections=throw`.
+A fire-and-forget `log.error('...', true)` pointed at an unwritable log directory exits the process
+with `Error: EACCES: permission denied, mkdir '...'`.
+
+The recommended consumer shape is a latch that trips on the first rejection:
+
+```js
+let fileLoggingDisabled = false;
+
+async function logError(message) {
+  // once file logging has failed, stay on the console
+  if (fileLoggingDisabled) return log.error(message);
+
+  try {
+    await log.error(message, true);
+  } catch (err) {
+    // the first rejection is terminal - disable, do not retry
+    fileLoggingDisabled = true;
+  }
+}
+```
+
+That latch is deliberately terminal for the lifetime of the process: nothing in it ever re-enables
+file logging. Records are degraded rather than lost, because the console line is still written on
+every call -- but a consumer using the file sink for audit or compliance should treat the first
+rejection as an **alertable** event, or fail closed, rather than degrade silently.
+
+#### Recovering After a Latch
+
+If file logging must come back without a restart, re-arm the latch on a **timer**, never on the next
+log call. Hold it closed for a fixed back-off window -- a minute or more, long enough that a
+permissions fix or a freed disk has a chance to land -- then let exactly one write through. If that
+write rejects, latch again and lengthen the window; if it succeeds, clear the latch. Anything faster
+is a consumer-side retry under another name.
+
+This also decides what your operators can see. `log-write-recovered` (see
+[structured stderr notices](#structured-stderr-notices)) is emitted **only** on a subsequent
+successful write, and a consumer that latches off permanently never issues one. Its entire stderr
+output for the episode is a single `log-write-failed` followed by silence, which is indistinguishable
+from a failure that self-healed -- so an alert-clear rule keyed on `log-write-recovered` will never
+fire for it. Either treat `log-write-failed` as latching on the operator side too, or use the timed
+re-arm above, which is what makes a recovery notice reachable at all.
+
+#### Self-Healing Retry
+
+A cached log directory can outlive the directory it describes - for example, something deletes
+`logs/` while your process is running. To cover that, a failure whose `err.code` is `ENOENT`,
+`EACCES`, `EPERM` or `EROFS` drops the cached directory entry and retries the write **exactly once**.
+Any other code -- `EISDIR`, `ENOTDIR`, `ENOSPC`, `EMFILE` and the rest -- does not itself trigger
+a retry. The decision is keyed on the *first* attempt's code, so a rejection carrying one of these
+can still arrive after a retry if conditions changed mid-call.
+
+A retry that succeeds emits no *failure* notice: the promise resolves normally and the write counts
+as a success, closing any failure episode already open for that directory with the usual
+`log-write-recovered`. A rejection carrying one of those four codes has therefore already spent its
+single retry; every other code was never retryable in the first place. The retry is per call and per
+`Log` instance -- independent instances retry independently.
+
+#### Structured stderr Notices
+
+Alongside the rejection, **Log** emits a machine-parseable notice to `stderr` so that operators have
+something to key on. The write-failure path must never re-enter the logger itself, so these notices
+bypass all formatting and configuration: they are emitted via `console.error` as one JSON object per
+line (JSONL), regardless of your color, prefix, suffix or path settings. Anything that wraps or
+patches `console.error` sees them too. Notices are informational; the promise rejection is the
+failure signal.
+
+| Field | Value |
+| :---: | :--- |
+| `ts` | ISO-8601 timestamp of the notice |
+| `surface` | Always `"stonyx-logs"` |
+| `sessionKey` | Always `null` |
+| `project` | Always `null` |
+| `severity` | `"error"` for a failure, `"warn"` for a recovery |
+| `event` | `"log-write-failed"` or `"log-write-recovered"` |
+| `payload` | Event-specific, see below |
+| `schemaVersion` | Always `1` |
+
+`log-write-failed` payload:
+
+| Field | Description |
+| :---: | :--- |
+| `targetLog` | Resolved path of the log file that could not be written |
+| `path` | Resolved log *directory*, with trailing separator - this is the dedupe key |
+| `syscall` | The failing syscall, e.g. `"mkdir"` or `"open"` |
+| `code` | The same `err.code` carried by the rejection |
+| `cached` | Whether the directory was already cached when the write started |
+| `suppressedCount` | Always `0` on a failure notice |
+
+`log-write-recovered` carries `targetLog`, `path` and `suppressedCount` only.
+
+**Dedupe:** notices are one per failure episode, keyed on the resolved directory and scoped to the
+`Log` instance -- the failure counters are instance state, so two instances writing to the same
+directory emit one notice each. The first failure for a directory emits `log-write-failed`; every
+subsequent failure for that same directory is silent. The next successful write to it emits a single
+`log-write-recovered` carrying `suppressedCount` - the number of notices that were suppressed, i.e.
+`N - 1` for an episode of `N` consecutive failures.
+Every failure still rejects its own promise; only the notices are deduped.
+
+Five consecutive failures followed by one success emit exactly these two records:
+
+```jsonl
+{"ts":"2026-08-29T23:08:50.343Z","surface":"stonyx-logs","sessionKey":null,"project":null,"severity":"error","event":"log-write-failed","payload":{"targetLog":"/private/tmp/my-app/logs/error.log","path":"/private/tmp/my-app/logs/","syscall":"mkdir","code":"EACCES","cached":false,"suppressedCount":0},"schemaVersion":1}
+{"ts":"2026-08-29T23:08:50.344Z","surface":"stonyx-logs","sessionKey":null,"project":null,"severity":"warn","event":"log-write-recovered","payload":{"targetLog":"/private/tmp/my-app/logs/error.log","path":"/private/tmp/my-app/logs/","suppressedCount":4},"schemaVersion":1}
+```
+
 ### Configuration
 
 When instantiating **Log**, you can pass an object to customize your settings. Below is the default configuration:
@@ -213,7 +388,7 @@ const log = new Log({
 
 | Option | Type | Default | Description |
 | :---: | :---: | :---: | :--- |
-| `logToFileByDefault` | **Boolean** | *false* | Option to change default setting for `logToFile` parameter of logging functions. |
+| `logToFileByDefault` | **Boolean** | *false* | Option to change default setting for `logToFile` parameter of logging functions. When true, every log call except `debug()` becomes a rejectable file write -- see [handling write failures](#handling-write-failures). |
 | `logTimestamp` | **Boolean** | *false* | Option to include timestamp in console logging. Timestamps are automatically included in file logs. |
 | `path` | **String** | *'logs/'* | Path in which to store log files. This setting is relative to your project's root directory. |
 | `prefix` | **String** | *''* | Prefix string to prepend all log messages for all log types with the exception of *debug*. |

package/dist/index.d.ts

@@ -17,21 +17,129 @@ export default class Log {
     directoryCache: Map<string, Promise<void>>;
     writeFailures: Map<string, number>;
     [key: string]: unknown;
+    /**
+     * Logs `content` to the console in the `info` color, and to file when `logToFile` is true.
+     *
+     * **A failed file write rejects the returned promise, and that rejection is terminal - do not retry
+     * it.** `ENOENT`, `EACCES`, `EPERM` and `EROFS` have already been retried once internally by the
+     * time one reaches you; every other code (`EISDIR`, `ENOTDIR`, `ENOSPC`, `EMFILE`, ...) is never
+     * retried, because a retry cannot help it. Handle the first rejection by disabling file logging or
+     * backing off - never by writing again. The rejection value is the underlying
+     * `NodeJS.ErrnoException` with `err.code` preserved, and leaving it unhandled terminates the
+     * process.
+     *
+     * @see https://github.com/abofs/stonyx-logs#handling-write-failures
+     */
     info: (content: string, logToFile?: boolean, overwrite?: boolean) => Promise<void>;
+    /**
+     * Logs `content` to the console in the `warn` color, and to file when `logToFile` is true.
+     *
+     * **A failed file write rejects the returned promise, and that rejection is terminal - do not retry
+     * it.** `ENOENT`, `EACCES`, `EPERM` and `EROFS` have already been retried once internally by the
+     * time one reaches you; every other code (`EISDIR`, `ENOTDIR`, `ENOSPC`, `EMFILE`, ...) is never
+     * retried, because a retry cannot help it. Handle the first rejection by disabling file logging or
+     * backing off - never by writing again. The rejection value is the underlying
+     * `NodeJS.ErrnoException` with `err.code` preserved, and leaving it unhandled terminates the
+     * process.
+     *
+     * @see https://github.com/abofs/stonyx-logs#handling-write-failures
+     */
     warn: (content: string, logToFile?: boolean, overwrite?: boolean) => Promise<void>;
+    /**
+     * Logs `content` to the console in the `error` color, and to file when `logToFile` is true.
+     *
+     * **A failed file write rejects the returned promise, and that rejection is terminal - do not retry
+     * it.** `ENOENT`, `EACCES`, `EPERM` and `EROFS` have already been retried once internally by the
+     * time one reaches you; every other code (`EISDIR`, `ENOTDIR`, `ENOSPC`, `EMFILE`, ...) is never
+     * retried, because a retry cannot help it. Handle the first rejection by disabling file logging or
+     * backing off - never by writing again. The rejection value is the underlying
+     * `NodeJS.ErrnoException` with `err.code` preserved, and leaving it unhandled terminates the
+     * process.
+     *
+     * @see https://github.com/abofs/stonyx-logs#handling-write-failures
+     */
     error: (content: string, logToFile?: boolean, overwrite?: boolean) => Promise<void>;
     constructor(options?: Partial<LogOptions>);
     defineType(type: string, setting: ColorSetting, options?: Partial<LogOptions> | null): void;
     createConvenienceMethod(type: string): void;
+    /**
+     * Validates params and applies configuration-based defaults for logging. Every convenience method
+     * created by `defineType` - including `info`, `warn` and `error` - routes through here. Note that
+     * `debug` does not: it is a direct method that never consults `logToFileByDefault`.
+     *
+     * **A failed file write rejects the returned promise, and that rejection is terminal - do not retry
+     * it.** `ENOENT`, `EACCES`, `EPERM` and `EROFS` have already been retried once internally by the
+     * time one reaches you; every other code (`EISDIR`, `ENOTDIR`, `ENOSPC`, `EMFILE`, ...) is never
+     * retried, because a retry cannot help it. Handle the first rejection by disabling file logging or
+     * backing off - never by writing again. The rejection value is the underlying
+     * `NodeJS.ErrnoException` with `err.code` preserved, and leaving it unhandled terminates the
+     * process.
+     *
+     * @see https://github.com/abofs/stonyx-logs#handling-write-failures
+     */
     logAction(type: string, content: string, logToFile?: boolean, overwrite?: boolean): Promise<void>;
     getOptionForType(type: string, option: keyof LogOptions): LogOptions[keyof LogOptions];
     chalk(): ReturnType<Color['getChalkInstance']>;
+    /**
+     * Logs to console, and conditionally to file.
+     *
+     * When `logToFile` is true this awaits `writeToFile` and propagates its rejection unchanged, so
+     * the caller receives the underlying `NodeJS.ErrnoException`. Callers must handle it: see the
+     * `writeToFile` contract below.
+     */
     log(content: string, type: string, logToFile: boolean, overwrite: boolean): Promise<void>;
+    /**
+     * Direct hardcoded debug method (limited file logging). Unlike the `defineType` convenience
+     * methods this does not route through `logAction`, so it never consults `logToFileByDefault` and
+     * only writes to file when `logToFile` is passed explicitly.
+     *
+     * When `logToFile` is true this awaits `writeToFile` and propagates its rejection unchanged, on
+     * exactly the same contract as `log` - see `writeToFile` below.
+     */
     debug(content: unknown, logToFile?: boolean, overwrite?: boolean): Promise<void>;
+    /**
+     * Writes `content` to the resolved target for `type`, creating the target's directory on first
+     * use for that directory.
+     *
+     * The returned promise rejecting with the underlying `NodeJS.ErrnoException` (with `err.code`
+     * preserved) is the sole failure signal - callers that care must handle it. The structured
+     * stderr notice emitted alongside a failure is informational only and is deduped per episode.
+     *
+     * On `ENOENT`, `EACCES`, `EPERM` or `EROFS` the cached directory entry is dropped and the write
+     * is retried exactly once. Other codes do not themselves trigger a retry; the decision is keyed
+     * on the first attempt's code.
+     *
+     * A rejection is terminal either way. For those four codes the self-heal has already run and
+     * failed by the time one escapes; the rest were never retryable, so repeating the call cannot
+     * change the outcome. Consumers must not layer their own retry on top - doing so either races the
+     * internal one or repeats a call that already cannot succeed, and delays the disable/back-off the
+     * rejection exists to trigger. The correct response to the first rejection is to stop writing.
+     * See README "Handling write failures".
+     */
     writeToFile(type: string, content: string, overwrite: boolean): Promise<void>;
+    /**
+     * One structured stderr notice per failure episode: an emit on the first failure, silence while
+     * it keeps failing, one recovery emit on the next success. A null payload records a success.
+     *
+     * Keyed on the directory rather than the resolved target, matching `directoryCache`: every code
+     * in the retry allowlist is a directory-level condition, so keying on the target would strand an
+     * un-reaped entry - and silently drop its suppressed count - whenever a `{date}` template rotates
+     * away from a still-failing filename.
+     */
     noticeWriteResult(path: string, targetLog: string, payload: Record<string, unknown> | null): void;
+    /**
+     * The write-failure path must never re-enter this logger, so notices go straight out through
+     * `console.error` as a single JSONL record, bypassing all of this package's formatting. Field
+     * order is the canonical one mandated by the framework logging schema, with the optional
+     * `schemaVersion` last.
+     */
     emitNotice(severity: Severity, event: string, payload: Record<string, unknown>): void;
     resolveFilename(template: string, type: string): string;
+    /**
+     * Ensures the target's directory exists. Both write paths auto-create the file itself, so no
+     * bootstrap write is needed. `targetLog` is unused but retained for signature compatibility:
+     * resolveFilename strips separators, so the only cached invariant is the directory.
+     */
     validateFileAndDirectory(path: string, targetLog: string): Promise<void>;
     sanitizePath(path: string): string;
 }

package/dist/index.js

@@ -72,7 +72,21 @@ export default class Log {
     createConvenienceMethod(type) {
         this[type] = (content, logToFile, overwrite = false) => this.logAction(type, content, logToFile, overwrite);
     }
-    // validates params and sets configuration-based defaults for logging
+    /**
+     * Validates params and applies configuration-based defaults for logging. Every convenience method
+     * created by `defineType` - including `info`, `warn` and `error` - routes through here. Note that
+     * `debug` does not: it is a direct method that never consults `logToFileByDefault`.
+     *
+     * **A failed file write rejects the returned promise, and that rejection is terminal - do not retry
+     * it.** `ENOENT`, `EACCES`, `EPERM` and `EROFS` have already been retried once internally by the
+     * time one reaches you; every other code (`EISDIR`, `ENOTDIR`, `ENOSPC`, `EMFILE`, ...) is never
+     * retried, because a retry cannot help it. Handle the first rejection by disabling file logging or
+     * backing off - never by writing again. The rejection value is the underlying
+     * `NodeJS.ErrnoException` with `err.code` preserved, and leaving it unhandled terminates the
+     * process.
+     *
+     * @see https://github.com/abofs/stonyx-logs#handling-write-failures
+     */
     logAction(type, content, logToFile, overwrite) {
         // set logToFile default based on class options when not set
         if (logToFile === undefined)
@@ -93,7 +107,13 @@ export default class Log {
     chalk() {
         return this.color.getChalkInstance();
     }
-    // logs to console, and conditionally to file; propagates any writeToFile rejection to the caller
+    /**
+     * Logs to console, and conditionally to file.
+     *
+     * When `logToFile` is true this awaits `writeToFile` and propagates its rejection unchanged, so
+     * the caller receives the underlying `NodeJS.ErrnoException`. Callers must handle it: see the
+     * `writeToFile` contract below.
+     */
     async log(content, type, logToFile, overwrite) {
         const logTimestamp = this.getOptionForType(type, 'logTimestamp');
         const timestamp = `[${new Date().toLocaleString('en-US')}]`;
@@ -112,14 +132,21 @@ export default class Log {
             return;
         await this.writeToFile(type, `${timestamp} ${content}\n`, overwrite);
     }
-    // direct hardcoded debug method (limited file logging); propagates any writeToFile rejection
+    /**
+     * Direct hardcoded debug method (limited file logging). Unlike the `defineType` convenience
+     * methods this does not route through `logAction`, so it never consults `logToFileByDefault` and
+     * only writes to file when `logToFile` is passed explicitly.
+     *
+     * When `logToFile` is true this awaits `writeToFile` and propagates its rejection unchanged, on
+     * exactly the same contract as `log` - see `writeToFile` below.
+     */
     async debug(content, logToFile = false, overwrite = true) {
         console.dir(content, { depth: 6 }); // eslint-disable-line no-console
         if (!logToFile)
             return;
         await this.writeToFile('debug', JSON.stringify(content, null, 2), overwrite);
     }
-    /*
+    /**
      * Writes `content` to the resolved target for `type`, creating the target's directory on first
      * use for that directory.
      *
@@ -128,7 +155,15 @@ export default class Log {
      * stderr notice emitted alongside a failure is informational only and is deduped per episode.
      *
      * On `ENOENT`, `EACCES`, `EPERM` or `EROFS` the cached directory entry is dropped and the write
-     * is retried exactly once; every other code rejects on the first attempt without a retry.
+     * is retried exactly once. Other codes do not themselves trigger a retry; the decision is keyed
+     * on the first attempt's code.
+     *
+     * A rejection is terminal either way. For those four codes the self-heal has already run and
+     * failed by the time one escapes; the rest were never retryable, so repeating the call cannot
+     * change the outcome. Consumers must not layer their own retry on top - doing so either races the
+     * internal one or repeats a call that already cannot succeed, and delays the disable/back-off the
+     * rejection exists to trigger. The correct response to the first rejection is to stop writing.
+     * See README "Handling write failures".
      */
     async writeToFile(type, content, overwrite) {
         const path = this.getOptionForType(type, 'path');
@@ -161,7 +196,7 @@ export default class Log {
         }
         this.noticeWriteResult(path, targetLog, null);
     }
-    /*
+    /**
      * One structured stderr notice per failure episode: an emit on the first failure, silence while
      * it keeps failing, one recovery emit on the next success. A null payload records a success.
      *
@@ -190,10 +225,11 @@ export default class Log {
             });
         }
     }
-    /*
-     * The write-failure path must never re-enter this logger, so notices go straight to stderr as a
-     * single JSONL record. Field order is the canonical one mandated by the framework logging
-     * schema, with the optional `schemaVersion` last.
+    /**
+     * The write-failure path must never re-enter this logger, so notices go straight out through
+     * `console.error` as a single JSONL record, bypassing all of this package's formatting. Field
+     * order is the canonical one mandated by the framework logging schema, with the optional
+     * `schemaVersion` last.
      */
     emitNotice(severity, event, payload) {
         const ts = new Date().toISOString();
@@ -229,7 +265,7 @@ export default class Log {
         // sanitize: prevent path traversal and disallow directory separators
         return resolved.replace(/\.\./g, '').replace(/[/\\]/g, '');
     }
-    /*
+    /**
      * Ensures the target's directory exists. Both write paths auto-create the file itself, so no
      * bootstrap write is needed. `targetLog` is unused but retained for signature compatibility:
      * resolveFilename strips separators, so the only cached invariant is the directory.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonyx/logs",
-  "version": "1.0.1-beta.18",
+  "version": "1.0.1-beta.19",
   "description": "Simplified logging for node applications",
   "type": "module",
   "main": "dist/index.js",