@elisra-devops/docgen-skins 0.28.0 → 0.29.0

package/src/services/logger.ts

@@ -1,26 +1,229 @@
 "use strict";
 import * as winston from "winston";
+import * as fs from "fs";
+import * as path from "path";
+import Transport from "winston-transport";
+import { runContextStore } from "./runContext";
+import { getLogSink, DiagnosticEvent } from "./logSink";
 
-let logsPath = process.env.logs_path || "./logs/";
-const logFormat = winston.format.printf(
-  info => `${info.timestamp} - ${info.level}: ${info.message}`
+// Merges the ambient runId (set by content-control's request middleware, once Phase 3 lands
+// there) into every log record. A never-populated store is a harmless no-op — this package
+// only reads it, never sets it.
+export const withRunContext = winston.format((info) => {
+  const store = runContextStore.getStore();
+  if (store?.runId) (info as Record<string, unknown>).runId = store.runId;
+  // Phase 7b — same ambient, per-run treatment as runId.
+  if (store?.docType) (info as Record<string, unknown>).docType = store.docType;
+  return info;
+});
+
+// Defense-in-depth: scrubs known-sensitive keys out of any object attached to a log
+// call (meta, splat, an Error's own enumerable props). Does not redact secrets
+// interpolated into a message string — that's the corresponding call-site fixes' job;
+// this is a backstop for structured fields.
+// "accesskey" (not just "minioaccesskey") so this also catches an *AccessKeyId-style field —
+// a real gap found in api-gate's copy during the Phase 5 manifest work: only the *SecretKey
+// sibling was covered before, via "secret". Applied here too to keep the four copies in sync.
+const SENSITIVE_KEY = /token|pat|password|secret|authorization|accesskey|minioaccesskey|miniosecretkey/i;
+
+// A per-key try/catch on the *read*, not just around the whole loop: a getter that throws
+// (e.g. `{ get boom() { throw ... } }`) would otherwise abort redaction for every remaining
+// key in the same object, or — worse — survive redaction untouched and re-throw later, inside
+// winston's json() formatter, which is not wrapped in anything. redactValue always returns a
+// freshly built plain object/array, never the original reference, so once a value has passed
+// through here nothing downstream can re-trigger a throwing accessor on it.
+function safeRead(obj: Record<string, unknown>, key: string): { ok: true; value: unknown } | { ok: false } {
+  try {
+    return { ok: true, value: obj[key] };
+  } catch {
+    return { ok: false };
+  }
+}
+function redactValue(value: unknown, depth = 0, seen = new WeakSet<object>()): unknown {
+  if (depth > 6 || value === null || typeof value !== "object") return value;
+  if (seen.has(value as object)) return "[Circular]";
+  seen.add(value as object);
+  if (Array.isArray(value)) return value.map((v) => redactValue(v, depth + 1, seen));
+  const out: Record<string, unknown> = {};
+  for (const key of Object.keys(value as Record<string, unknown>)) {
+    const read = safeRead(value as Record<string, unknown>, key);
+    if (!read.ok) {
+      out[key] = "[Unreadable property]";
+      continue;
+    }
+    out[key] = SENSITIVE_KEY.test(key) ? "[REDACTED]" : redactValue(read.value, depth + 1, seen);
+  }
+  return out;
+}
+export const redact = winston.format((info) => {
+  const target = info as Record<string, unknown>;
+  for (const key of Object.keys(target)) {
+    // level/timestamp are always plain strings winston sets itself — never touched. message is
+    // NOT exempt: when logger.error(x) is called with a single non-string/non-Error argument,
+    // winston nests the whole thing under info.message (this is exactly the shape hit by a raw
+    // object argument), so message can carry a throwing getter or a sensitive key just as much
+    // as any other field — redactValue already no-ops on a plain string, so including it here
+    // costs nothing for the common case and closes that gap for the uncommon one.
+    if (key === "level" || key === "timestamp") continue;
+    const read = safeRead(target, key);
+    const value = !read.ok
+      ? "[Unreadable property]"
+      : // A top-level primitive (e.g. token: "abc") has no children for redactValue to walk into —
+        // the key itself has to be checked here too, not just inside the recursive object walk.
+        SENSITIVE_KEY.test(key)
+        ? "[REDACTED]"
+        : redactValue(read.value);
+    try {
+      target[key] = value;
+    } catch {
+      // The original property could be a getter-only accessor with no setter, which throws on
+      // plain assignment in strict mode — redefine it outright rather than skip it.
+      Object.defineProperty(target, key, { value, writable: true, enumerable: true, configurable: true });
+    }
+  }
+  return info;
+});
+
+// Resolves the package's own version for defaultMeta.
+function readOwnVersion(): string {
+  const candidates = [
+    path.resolve(__dirname, "../package.json"),
+    path.resolve(__dirname, "../../package.json"),
+    path.resolve(process.cwd(), "package.json"),
+  ];
+  for (const candidate of candidates) {
+    try {
+      if (!fs.existsSync(candidate)) continue;
+      return JSON.parse(fs.readFileSync(candidate, "utf8")).version || "unknown";
+    } catch {
+      // try next candidate
+    }
+  }
+  return "unknown";
+}
+
+// A template literal's implicit ToString throws on a Symbol value (unlike String(), which
+// calls Symbol.prototype.toString() explicitly) — logger.error(Symbol('x')) would otherwise
+// crash inside this formatter itself, the one place in the pipeline with no try/catch around
+// it. Symbol.toString() itself never throws, so this needs no further guarding.
+const safeMessageString = (value: unknown): string =>
+  typeof value === "symbol" ? value.toString() : String(value);
+
+const textFormat = winston.format.printf(
+  info => `${info.timestamp} - ${info.level}: ${safeMessageString(info.message)}`
 );
 
+// Bounded so one oversized message/stack can't produce an unbounded LogEvent document.
+const MAX_MESSAGE_LEN = 2000;
+const MAX_STACK_LEN = 4000;
+function clamp(value: unknown, max: number): string | undefined {
+  if (typeof value !== "string") return undefined;
+  return value.length > max ? value.slice(0, max) : value;
+}
+
+// Ships warn/error records to whatever LogSink the host process (docgen-content-control's
+// index.ts) has installed — this package never installs one itself, only reads it. Reads
+// info *after* the rest of the format chain has already run — redact() has already scrubbed
+// it by the time this transport sees it. Never throws, never blocks the call path, and never
+// logs through `logger` itself (that would recurse back into this same transport) — failures
+// go to console.error only.
+const DIAGNOSTICS_CAPTURE_ENABLED = (process.env.DIAGNOSTICS_CAPTURE_ENABLED || "true").toLowerCase() !== "false";
+// Exported for tests, the same treatment as redact()/withRunContext() — so a test pipeline
+// can exercise this transport without going through the real singleton logger's env-gated
+// json()/textFormat branch.
+export class DiagnosticsTransport extends Transport {
+  log(info: Record<string, unknown>, callback: () => void): void {
+    setImmediate(() => this.emit("logged", info));
+    try {
+      const level = info.level;
+      const isWarnOrError = level === "warn" || level === "error";
+      // Phase 6b — the logger's own level gate is now 'debug' (see createLogger below), so a
+      // debug/info call reaches this transport regardless of mode; this is the one place that
+      // decides whether it's actually persisted, keyed off the per-run capture mode rather
+      // than a process-wide setting — concurrent runs in 'normal' mode are unaffected by a
+      // sibling run's 'verbose'/'retain-on-failure' opt-in.
+      const captureMode = runContextStore.getStore()?.captureMode;
+      const isCapturedDebugOrInfo =
+        (level === "debug" || level === "info") && (captureMode === "verbose" || captureMode === "retain-on-failure");
+      if (DIAGNOSTICS_CAPTURE_ENABLED && (isWarnOrError || isCapturedDebugOrInfo)) {
+        // winston.errors({stack:true}) merges an Error's own enumerable properties (stack,
+        // and anything else the call site set, e.g. `err.code`) directly onto `info` — there
+        // is no separate nested info.err. `info.stack`'s presence is the only reliable signal
+        // that this record came from `logger.error('...', err)`/`logger.error(err)` rather
+        // than a plain string message. When present, info.message is already the
+        // stable-message-plus-error-message string winston produced, so err.message reuses it.
+        const hasErr = typeof info.stack === "string";
+        const message = clamp(info.message, MAX_MESSAGE_LEN) ?? "";
+        const event: DiagnosticEvent = {
+          ts: typeof info.timestamp === "string" ? info.timestamp : new Date().toISOString(),
+          level: String(info.level),
+          service: String(info.service ?? "@elisra-devops/docgen-skins"),
+          version: String(info.version ?? "unknown"),
+          runId: typeof info.runId === "string" ? info.runId : undefined,
+          docType: typeof info.docType === "string" ? info.docType : undefined,
+          step: typeof info.step === "string" ? info.step : undefined,
+          contentControlType: typeof info.contentControlType === "string" ? info.contentControlType : undefined,
+          contentControlTitle: typeof info.contentControlTitle === "string" ? info.contentControlTitle : undefined,
+          project: typeof info.project === "string" ? info.project : undefined,
+          userId: typeof info.userId === "string" ? info.userId : undefined,
+          message,
+          err: hasErr
+            ? {
+                message,
+                code: typeof info.code === "string" ? info.code : undefined,
+                stack: clamp(info.stack, MAX_STACK_LEN),
+              }
+            : undefined,
+          retainPending: !isWarnOrError && captureMode === "retain-on-failure" ? true : undefined,
+        };
+        getLogSink()?.push(event);
+      }
+    } catch (e) {
+      // eslint-disable-next-line no-console
+      console.error("DiagnosticsTransport failed to push event", e);
+    }
+    callback();
+  }
+}
+
+// LOG_FORMAT=json is the eventual default (structured stdout a collector can parse), but
+// stays opt-in for one release so switching is a config change, not an image rebuild, if
+// anyone reading raw console output needs to roll back.
+const useJson = (process.env.LOG_FORMAT || "text").toLowerCase() === "json";
+
+// Phase 6b — the Logger's own level gate must be 'debug' (winston's most permissive) so a
+// debug/info call always reaches every transport's log(); a static per-logger level can't
+// depend on the ALS store's per-run capture mode, so DiagnosticsTransport has to be the one
+// deciding what's actually persisted. The Console transport below gets its own explicit
+// level so stdout's default behavior (info/warn/error unless LOG_LEVEL=debug) is unchanged —
+// this only spends the format-chain cost on debug() calls that previously short-circuited
+// for free; info/warn/error volume (Phase 4's focus) is unaffected either way.
+const CONSOLE_LOG_LEVEL = process.env.LOG_LEVEL || "info";
+
 const logger: winston.Logger = winston.createLogger({
-  format: winston.format.timestamp(),
-  level: "silly",
-  transports: [
-    new winston.transports.File({
-      filename: `${logsPath}word-skins.log`,
-      level: "error",
-      format: logFormat
-    }),
-    new winston.transports.File({
-      filename: `${logsPath}word-skins-all.log`,
-      format: logFormat
-    }),
-    new winston.transports.Console({ format: logFormat, level: "debug" })
-  ]
+  level: "debug",
+  defaultMeta: { service: "@elisra-devops/docgen-skins", version: readOwnVersion() },
+  format: useJson
+    ? winston.format.combine(
+        winston.format.errors({ stack: true }),
+        winston.format.timestamp(),
+        withRunContext(),
+        redact(),
+        winston.format.splat(),
+        winston.format.json()
+      )
+    : winston.format.combine(
+        winston.format.errors({ stack: true }),
+        winston.format.timestamp(),
+        withRunContext(),
+        redact(),
+        winston.format.splat(),
+        textFormat
+      ),
+  // Stdout only — no File transports, consistent with the other DocGen services (no mounted
+  // log volume anywhere in this deployment, so a File transport is invisible to `kubectl logs`
+  // and can throw at import time under a read-only root filesystem).
+  transports: [new winston.transports.Console({ level: CONSOLE_LOG_LEVEL }), new DiagnosticsTransport()]
 });
 
 export default logger;

package/src/services/runContext.ts

@@ -0,0 +1,22 @@
+"use strict";
+import { AsyncLocalStorage } from "async_hooks";
+
+export interface RunContext {
+  runId: string;
+  // Phase 6b — this package never sets it, only reads it: content-control (the host process
+  // this package runs in-process inside) populates it via its own attachRunContext, and this
+  // package's DiagnosticsTransport reads the same in-process ALS store.
+  captureMode?: 'verbose' | 'retain-on-failure';
+  // Phase 7b — same read-only treatment as captureMode above.
+  docType?: string;
+}
+
+// Symbol.for uses the global symbol registry, so every duplicated copy of this file across
+// the DocGen packages — hoisted or nested at any depth by npm — converges on the same
+// AsyncLocalStorage instance. Keying by module identity instead would silently split into
+// two stores and runId would go missing with no visible error.
+const KEY = Symbol.for("elisradevops.docgen.runContext");
+
+export const runContextStore: AsyncLocalStorage<RunContext> =
+  ((globalThis as Record<symbol, unknown>)[KEY] as AsyncLocalStorage<RunContext> | undefined) ??
+  ((globalThis as Record<symbol, unknown>)[KEY] = new AsyncLocalStorage<RunContext>());

package/src/test/logger.test.ts

@@ -0,0 +1,268 @@
+import * as winston from 'winston';
+import Transport from 'winston-transport';
+import { redact, DiagnosticsTransport } from '../services/logger';
+import { installLogSink, LogSink, DiagnosticEvent } from '../services/logSink';
+import { runContextStore } from '../services/runContext';
+
+const applyRedact = (info: Record<string, unknown>) => (redact() as any).transform({ ...info });
+
+describe('logger redact format', () => {
+  test('scrubs a top-level token/password/secret regardless of key casing', () => {
+    const out = applyRedact({ level: 'info', message: 'x', token: 'abc', Password: 'p', SECRET: 's' });
+    expect(out.token).toBe('[REDACTED]');
+    expect(out.Password).toBe('[REDACTED]');
+    expect(out.SECRET).toBe('[REDACTED]');
+  });
+
+  test('scrubs nested config.auth.password and config.headers.Authorization — the AxiosError.toJSON() leak', () => {
+    const axiosLikeError = {
+      message: 'Request failed',
+      config: {
+        auth: { username: '', password: 'super-secret-pat' },
+        headers: { Authorization: 'Bearer abc.def.ghi' },
+      },
+    };
+    const out: any = applyRedact({ level: 'error', message: 'upstream failed', err: axiosLikeError });
+    expect(out.err.config.auth.password).toBe('[REDACTED]');
+    expect(out.err.config.headers.Authorization).toBe('[REDACTED]');
+    expect(out.err.message).toBe('Request failed');
+  });
+
+  test('leaves non-sensitive fields untouched', () => {
+    const out = applyRedact({ level: 'info', message: 'ok', project: 'Cube-ADCS', docType: 'SVD' });
+    expect(out.project).toBe('Cube-ADCS');
+    expect(out.docType).toBe('SVD');
+  });
+
+  test('never throws on a circular object', () => {
+    const circular: any = { name: 'x' };
+    circular.self = circular;
+    expect(() => applyRedact({ level: 'info', message: 'x', circular })).not.toThrow();
+  });
+
+  test('never throws and passes info through on null/undefined meta', () => {
+    expect(() => applyRedact({ level: 'info', message: 'x', meta: null })).not.toThrow();
+    expect(() => applyRedact({ level: 'info', message: 'x', meta: undefined })).not.toThrow();
+  });
+});
+
+// A capturing transport + the exact JSON format chain logger.ts uses (errors -> timestamp ->
+// redact -> splat -> json), so these tests exercise the real pipeline, not just redact() alone.
+class CaptureTransport extends Transport {
+  lines: Record<string, unknown>[] = [];
+  log(info: Record<string, unknown>, callback: () => void) {
+    this.lines.push(JSON.parse((info as any)[Symbol.for('message')] ?? JSON.stringify(info)));
+    callback();
+  }
+}
+function makeTestLogger() {
+  const capture = new CaptureTransport();
+  const logger = winston.createLogger({
+    level: 'silly',
+    format: winston.format.combine(
+      winston.format.errors({ stack: true }),
+      winston.format.timestamp(),
+      redact(),
+      winston.format.splat(),
+      winston.format.json()
+    ),
+    transports: [capture],
+  });
+  return { logger, capture };
+}
+
+describe('logger pipeline — errors({stack:true})', () => {
+  test('logger.error(err) (single-arg Error) still produces a non-empty message and a stack', () => {
+    // This is the regression errors({stack:true}) exists to prevent: without it, winston's
+    // single-arg path makes `info` *be* the Error, and message/stack are non-enumerable, so
+    // json() would emit {"level":"error","timestamp":"…"} — content-free.
+    const { logger, capture } = makeTestLogger();
+    logger.error(new Error('boom'));
+    expect(capture.lines).toHaveLength(1);
+    expect(capture.lines[0].message).toBe('boom');
+    expect(typeof capture.lines[0].stack).toBe('string');
+    expect((capture.lines[0].stack as string).length).toBeGreaterThan(0);
+  });
+});
+
+describe('logger pipeline — hostile inputs never throw', () => {
+  test.each([
+    ['null', null],
+    ['undefined', undefined],
+    ['NaN', NaN],
+    ['a circular object', (() => { const c: any = { a: 1 }; c.self = c; return c; })()],
+    ['an object with a throwing getter', { get boom() { throw new Error('nope'); } }],
+    ['a BigInt', BigInt(9007199254740993)],
+    ['a Symbol', Symbol('x')],
+    ['an Error with no message', new Error()],
+    ['a 10MB string', 'x'.repeat(10 * 1024 * 1024)],
+  ])('logger.error(%s) does not throw', (_label, value) => {
+    const { logger } = makeTestLogger();
+    expect(() => logger.error(value as any)).not.toThrow();
+  });
+});
+
+describe('DiagnosticsTransport (Phase 6a)', () => {
+  function makeDiagnosticsLogger() {
+    const capture = new CaptureTransport();
+    const logger = winston.createLogger({
+      level: 'silly',
+      format: winston.format.combine(
+        winston.format.errors({ stack: true }),
+        winston.format.timestamp(),
+        redact(),
+        winston.format.splat(),
+        winston.format.json()
+      ),
+      transports: [capture, new DiagnosticsTransport()],
+    });
+    return { logger, capture };
+  }
+
+  test('pushes warn/error records to whatever sink is installed', () => {
+    const events: DiagnosticEvent[] = [];
+    const sink: LogSink = { push: (e) => events.push(e) };
+    installLogSink(sink);
+    const { logger } = makeDiagnosticsLogger();
+    logger.warn('a stable warning');
+    logger.error('a stable error', Object.assign(new Error('boom'), { code: 'ECONN' }));
+    expect(events).toHaveLength(2);
+    expect(events[0].level).toBe('warn');
+    expect(events[1].err?.code).toBe('ECONN');
+    expect(events[1].err?.stack).toEqual(expect.any(String));
+  });
+
+  test('does not push info/debug records', () => {
+    const events: DiagnosticEvent[] = [];
+    installLogSink({ push: (e) => events.push(e) });
+    const { logger } = makeDiagnosticsLogger();
+    logger.info('not interesting to the dashboard');
+    expect(events).toHaveLength(0);
+  });
+
+  test('a throwing sink cannot break the log call', () => {
+    installLogSink({
+      push: () => {
+        throw new Error('sink is down');
+      },
+    });
+    const { logger } = makeDiagnosticsLogger();
+    expect(() => logger.error('still must not throw')).not.toThrow();
+  });
+
+  test.each([
+    ['null', null],
+    ['undefined', undefined],
+    ['NaN', NaN],
+    ['a circular object', (() => { const c: any = { a: 1 }; c.self = c; return c; })()],
+    ['an object with a throwing getter', { get boom() { throw new Error('nope'); } }],
+    ['a BigInt', BigInt(9007199254740993)],
+    ['a Symbol', Symbol('x')],
+    ['an Error with no message', new Error()],
+    ['a 10MB string', 'x'.repeat(10 * 1024 * 1024)],
+  ])('logger.error(%s) with a sink installed does not throw', (_label, value) => {
+    installLogSink({ push: () => undefined });
+    const { logger } = makeDiagnosticsLogger();
+    expect(() => logger.error(value as any)).not.toThrow();
+  });
+});
+
+describe('textFormat safety (regression)', () => {
+  // The hostile-input matrix above exercises makeTestLogger()'s json() pipeline — it never
+  // touched the real singleton logger's text-format branch (LOG_FORMAT's default), which is
+  // where a Symbol message crashed: a template literal's implicit ToString throws on a Symbol,
+  // and this formatter sits with no try/catch around it.
+  test('logger.error(Symbol) does not throw through the real default-exported logger', () => {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const logger = require('../services/logger').default;
+    expect(() => logger.error(Symbol('x'))).not.toThrow();
+  });
+});
+
+describe('DiagnosticsTransport capture policy (Phase 6b)', () => {
+  function makeDiagnosticsLogger() {
+    const capture = new CaptureTransport();
+    const logger = winston.createLogger({
+      level: 'silly',
+      format: winston.format.combine(
+        winston.format.errors({ stack: true }),
+        winston.format.timestamp(),
+        redact(),
+        winston.format.splat(),
+        winston.format.json()
+      ),
+      transports: [capture, new DiagnosticsTransport()],
+    });
+    return { logger, capture };
+  }
+
+  test('normal mode (no captureMode) does not persist debug/info', () => {
+    const events: DiagnosticEvent[] = [];
+    installLogSink({ push: (e) => events.push(e) });
+    const { logger } = makeDiagnosticsLogger();
+    runContextStore.run({ runId: 'run-1' }, () => {
+      logger.debug('a debug line');
+      logger.info('an info line');
+    });
+    expect(events).toHaveLength(0);
+  });
+
+  test('verbose mode persists debug and info', () => {
+    const events: DiagnosticEvent[] = [];
+    installLogSink({ push: (e) => events.push(e) });
+    const { logger } = makeDiagnosticsLogger();
+    runContextStore.run({ runId: 'run-2', captureMode: 'verbose' }, () => {
+      logger.debug('a debug line');
+      logger.info('an info line');
+    });
+    expect(events).toHaveLength(2);
+    expect(events[0].retainPending).toBeUndefined();
+  });
+
+  test('warn/error persist regardless of capture mode', () => {
+    const events: DiagnosticEvent[] = [];
+    installLogSink({ push: (e) => events.push(e) });
+    const { logger } = makeDiagnosticsLogger();
+    runContextStore.run({ runId: 'run-3' }, () => {
+      logger.warn('a warning');
+      logger.error('an error');
+    });
+    expect(events).toHaveLength(2);
+  });
+
+  test('retain-on-failure persists debug/info tagged retainPending: true', () => {
+    const events: DiagnosticEvent[] = [];
+    installLogSink({ push: (e) => events.push(e) });
+    const { logger } = makeDiagnosticsLogger();
+    runContextStore.run({ runId: 'run-4', captureMode: 'retain-on-failure' }, () => {
+      logger.debug('a debug line');
+    });
+    expect(events).toHaveLength(1);
+    expect(events[0].retainPending).toBe(true);
+  });
+
+  test('retain-on-failure does not tag warn/error as retainPending', () => {
+    const events: DiagnosticEvent[] = [];
+    installLogSink({ push: (e) => events.push(e) });
+    const { logger } = makeDiagnosticsLogger();
+    runContextStore.run({ runId: 'run-5', captureMode: 'retain-on-failure' }, () => {
+      logger.error('an error');
+    });
+    expect(events).toHaveLength(1);
+    expect(events[0].retainPending).toBeUndefined();
+  });
+
+  test('a concurrent normal-mode run is unaffected by a sibling verbose run', () => {
+    const events: DiagnosticEvent[] = [];
+    installLogSink({ push: (e) => events.push(e) });
+    const { logger } = makeDiagnosticsLogger();
+    runContextStore.run({ runId: 'verbose-run', captureMode: 'verbose' }, () => {
+      logger.debug('verbose debug');
+    });
+    runContextStore.run({ runId: 'normal-run' }, () => {
+      logger.debug('normal debug');
+    });
+    expect(events).toHaveLength(1);
+    expect(events[0].message).toBe('verbose debug');
+  });
+});

package/src/test/runContext.test.ts

@@ -0,0 +1,48 @@
+import * as winston from 'winston';
+import Transport from 'winston-transport';
+import { withRunContext } from '../services/logger';
+import { runContextStore } from '../services/runContext';
+
+class CaptureTransport extends Transport {
+  lines: Record<string, unknown>[] = [];
+  log(info: Record<string, unknown>, callback: () => void) {
+    this.lines.push(JSON.parse((info as any)[Symbol.for('message')] ?? JSON.stringify(info)));
+    callback();
+  }
+}
+function makeTestLogger() {
+  const capture = new CaptureTransport();
+  const logger = winston.createLogger({
+    level: 'silly',
+    format: winston.format.combine(withRunContext(), winston.format.json()),
+    transports: [capture],
+  });
+  return { logger, capture };
+}
+
+describe('withRunContext', () => {
+  test('is a no-op when the store was never populated', () => {
+    const { logger, capture } = makeTestLogger();
+    logger.info('outside any run');
+    expect(capture.lines[0].runId).toBeUndefined();
+  });
+
+  test('stamps runId onto every log emitted inside store.run(...)', () => {
+    const { logger, capture } = makeTestLogger();
+    runContextStore.run({ runId: 'run-123' }, () => {
+      logger.info('inside the run');
+    });
+    logger.info('outside again');
+    expect(capture.lines[0].runId).toBe('run-123');
+    expect(capture.lines[1].runId).toBeUndefined();
+  });
+
+  test('async work started inside the run keeps the runId across the await boundary', async () => {
+    const { logger, capture } = makeTestLogger();
+    await runContextStore.run({ runId: 'run-async' }, async () => {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      logger.info('after await');
+    });
+    expect(capture.lines[0].runId).toBe('run-async');
+  });
+});