runspec-node 0.19.0 → 0.22.0

package/dist/models.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runspec-node",
-  "version": "0.19.0",
+  "version": "0.22.0",
   "description": "Node/TypeScript language pack for runspec",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,7 +13,13 @@
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist"
   },
-  "keywords": ["runspec", "cli", "arguments", "agents", "mcp"],
+  "keywords": [
+    "runspec",
+    "cli",
+    "arguments",
+    "agents",
+    "mcp"
+  ],
   "author": "Jason Finestone",
   "license": "MIT",
   "repository": {

package/src/index.ts

@@ -1,5 +1,6 @@
 export { parse, loadSpec } from './parser';
 export { registerType, listTypes } from './types';
+export { tsTypeOf } from './inference';
 export { RunSpecError, MissingRequiredArg, InvalidChoice, OutOfRange, UnknownArg, GroupViolation, AutonomyViolation } from './errors';
 export { findConfig } from './finder';
 export { loadRaw } from './loader';

package/src/inference.ts

@@ -4,6 +4,31 @@ import { RunSpecError } from './errors';
 export const AUTONOMY_LEVELS = ['autonomous', 'confirm', 'supervised', 'manual'] as const;
 export const AUTONOMY_RANK = Object.fromEntries(AUTONOMY_LEVELS.map((l, i) => [l, i]));
 
+// Item-type name → its TypeScript type. Mirrors the JSON-Schema type map used
+// by emit; custom (register_type) names fall back to `unknown`.
+const TS_TYPE_NAMES: Record<string, string> = {
+  str: 'string',
+  int: 'number',
+  float: 'number',
+  bool: 'boolean',
+  flag: 'boolean',
+  path: 'string',
+  choice: 'string',
+  rest: 'string[]',
+};
+
+/** The TypeScript type of an arg's parsed value: the item type, suffixed `[]`
+ *  when the arg is `multiple` (`rest` is always `string[]`). `arg.type` itself
+ *  stays the item type — it drives per-item coercion. Pure helper, computed on
+ *  demand from a (typically inferred) ArgSpec; custom registered types fall
+ *  back to `"unknown"`. e.g. `tsTypeOf({type:"str", multiple:true})` → `"string[]"`. */
+export function tsTypeOf(arg: ArgSpec): string {
+  const type = arg.type ?? 'str';
+  if (type === 'rest') return 'string[]';
+  const base = TS_TYPE_NAMES[type] ?? 'unknown';
+  return arg.multiple ? `${base}[]` : base;
+}
+
 export function inferArg(raw: ArgSpec): ArgSpec {
   const result = { ...raw };
   const def = result.default;

package/src/loader.ts

@@ -40,10 +40,15 @@ function normaliseLogging(raw: Record<string, unknown> | undefined): LoggingConf
   // log-event counts by level. Suppress per-invocation with `--no-summary`
   // or `RUNSPEC_NO_SUMMARY=1`.
   if (raw === undefined) return undefined;
+  // `store` selects the file layout: 'single' = one rotating {runnable}.log;
+  // 'per-run' = one file per invocation. Unknown values fall back to 'single'
+  // — the schema check flags typos; runtime stays lenient.
+  const store = String(raw['store'] ?? 'single');
   return {
     rotate: String(raw['rotate'] ?? 'midnight'),
     keep: Number(raw['keep'] ?? 7),
     summary: raw['summary'] !== undefined ? Boolean(raw['summary']) : true,
+    store: store === 'per-run' ? 'per-run' : 'single',
   };
 }
 

package/src/logging_setup.ts

@@ -7,6 +7,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
+import { randomUUID } from 'crypto';
 import type { LoggingConfig } from './models';
 
 // ── internal state ────────────────────────────────────────────────────────────
@@ -15,7 +16,22 @@ let _configured = false;
 const _loggers = new Map<string, Logger>();
 const _handlers: Handler[] = [];
 
+// UUID4 assigned at configureLogging() time, injected into every file record as
+// extra.run_id (SPEC §run_id). Separates interleaved runs in a shared log, and
+// matches the run_id token in a per-run filename.
+let _runId: string | null = null;
+
 const RUN_SUMMARY_LOGGER = 'runspec.runsummary';
+// Uncaught exceptions are emitted on this dedicated logger so the file handler
+// records them while the console handlers drop them by name — console display is
+// handled explicitly in _handleUncaught (debug-gated).
+const EXCEPTION_LOGGER = 'runspec.exception';
+
+// Directory of the installed runspec-node package — used to filter internal
+// library frames out of the *displayed* compact trace (full trace still hits the file).
+const RUNSPEC_PKG_DIR = __dirname;
+
+let _debug = false; // mirrors the --debug flag; read by _handleUncaught for console rendering
 
 interface CapturedException {
   type: string;
@@ -23,6 +39,20 @@ interface CapturedException {
   traceback: string;
 }
 
+interface ExcFrame {
+  func: string;
+  file: string;
+  line: number | null;
+  code: string | null;
+}
+
+interface ExcStructured {
+  type: string;
+  message: string;
+  module: string | null;
+  frames: ExcFrame[];
+}
+
 interface SummaryState {
   counter: RunSummaryCounter;
   start: bigint;
@@ -83,6 +113,7 @@ interface LogRecord {
   message: string;
   error?: Error;
   extra?: Record<string, unknown>;
+  excStructured?: Record<string, unknown>;
 }
 
 interface Handler {
@@ -145,7 +176,12 @@ function formatJson(record: LogRecord): string {
     message: record.message,
   };
   if (record.error) obj['exc'] = record.error.stack ?? record.error.message;
-  if (record.extra) obj['extra'] = record.extra;
+  if (record.excStructured) obj['exc_structured'] = record.excStructured;
+  // run_id rides in extra on every file record (console output omits it — that
+  // handler uses formatConsole). Mirrors Python's _RunIdFilter.
+  if (record.extra || _runId !== null) {
+    obj['extra'] = { ...(record.extra ?? {}), ...(_runId !== null ? { run_id: _runId } : {}) };
+  }
   return JSON.stringify(obj);
 }
 
@@ -183,7 +219,7 @@ class StdoutHandler implements Handler {
 
   emit(record: LogRecord): void {
     if (record.levelNum >= 30) return; // WARNING+ belongs on stderr
-    if (record.loggerName === RUN_SUMMARY_LOGGER) return;
+    if (record.loggerName === RUN_SUMMARY_LOGGER || record.loggerName === EXCEPTION_LOGGER) return;
     try {
       process.stdout.write(formatConsole(record, this.showTracebacks) + '\n');
     } catch {
@@ -204,7 +240,7 @@ class StderrHandler implements Handler {
 
   emit(record: LogRecord): void {
     if (record.levelNum < 30) return;
-    if (record.loggerName === RUN_SUMMARY_LOGGER) return;
+    if (record.loggerName === RUN_SUMMARY_LOGGER || record.loggerName === EXCEPTION_LOGGER) return;
     try {
       process.stderr.write(formatConsole(record, this.showTracebacks) + '\n');
     } catch {
@@ -226,8 +262,8 @@ class RunSummaryCounter implements Handler {
   };
 
   emit(record: LogRecord): void {
-    // Don't count the summary record itself.
-    if (record.loggerName === RUN_SUMMARY_LOGGER) return;
+    // Don't count runspec's own bookkeeping records (summary + uncaught-exception).
+    if (record.loggerName === RUN_SUMMARY_LOGGER || record.loggerName === EXCEPTION_LOGGER) return;
     const label = LEVEL_LABEL[record.levelNum];
     if (label && label in this.counts) {
       this.counts[label]++;
@@ -317,6 +353,32 @@ class TimedRotatingFileHandler implements Handler {
   }
 }
 
+/**
+ * Plain append-only handler for `store = "per-run"` — one file per invocation,
+ * so there is nothing to rotate (and no rotation race across writers). The file
+ * is created lazily on first append, so a run that logs nothing leaves no empty
+ * file behind.
+ */
+class PlainFileHandler implements Handler {
+  constructor(
+    private readonly logPath: string,
+    readonly level: number,
+  ) {}
+
+  emit(record: LogRecord): void {
+    try {
+      fs.appendFileSync(this.logPath, formatJson(record) + '\n', 'utf-8');
+    } catch {
+      // never disrupt
+    }
+  }
+}
+
+/** Compact UTC stamp for per-run filenames: `YYYYMMDDThhmmssZ`. */
+function _perRunStamp(d: Date): string {
+  return d.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+}
+
 // ── size/rotate parser ────────────────────────────────────────────────────────
 
 const SIZE_RE = /^(\d+(?:\.\d+)?)\s*(KB|MB|GB)$/i;
@@ -462,6 +524,99 @@ export function emitRunSummary(): void {
   }
 }
 
+// ── uncaught exceptions ────────────────────────────────────────────────────────
+
+const STACK_FRAME_RE = /^\s*at (?:(.+?) \()?(.+?):(\d+):(\d+)\)?$/;
+
+/**
+ * Parse a V8 stack string into frames, innermost LAST (mirroring Python's
+ * traceback.extract_tb order). `code` is unavailable from a stack string.
+ */
+function parseStackFrames(stack: string): ExcFrame[] {
+  const frames: ExcFrame[] = [];
+  for (const lineStr of stack.split('\n')) {
+    const m = STACK_FRAME_RE.exec(lineStr);
+    if (!m) continue;
+    frames.push({ func: m[1] ?? '<anonymous>', file: m[2], line: parseInt(m[3], 10), code: null });
+  }
+  frames.reverse();
+  return frames;
+}
+
+/** Clean, machine-readable form of an error for the JSON audit / UI tables. */
+function buildExcStructured(err: Error): ExcStructured {
+  const frames = parseStackFrames(err.stack ?? '');
+  const last = frames.length ? frames[frames.length - 1] : null;
+  const module = last ? path.basename(last.file).replace(/\.[^.]+$/, '') : null;
+  return { type: err.name || 'Error', message: err.message || String(err), module, frames };
+}
+
+/**
+ * Neat, aligned, stdlib-only trace for --debug console output. Internal
+ * runspec frames are dropped from the *display* (full trace still hits the
+ * file). Falls back to the full list if filtering empties it.
+ */
+function formatCompactTrace(err: Error, frames: ExcFrame[]): string {
+  const shown = frames.filter((f) => !f.file.includes(RUNSPEC_PKG_DIR));
+  const use = shown.length ? shown : frames;
+  const locs = use.map((f) => `${path.basename(f.file)}:${f.line}`);
+  const width = Math.max(0, ...locs.map((l) => l.length));
+  const lines = [`${err.name || 'Error'}: ${err.message}`, ''];
+  use.forEach((f, i) => {
+    lines.push(`  ${locs[i].padEnd(width)}  ${f.func}`.trimEnd());
+  });
+  return lines.join('\n');
+}
+
+/** Emit the structured exception record straight to the handlers (file keeps it). */
+function emitExceptionRecord(err: Error, structured: ExcStructured): void {
+  if (_handlers.length === 0) return;
+  const record: LogRecord = {
+    ts: new Date(),
+    levelNum: 50,
+    loggerName: EXCEPTION_LOGGER,
+    message: 'uncaught exception',
+    error: err,
+    excStructured: structured as unknown as Record<string, unknown>,
+  };
+  for (const h of _handlers) {
+    try {
+      if (record.levelNum >= h.level) h.emit(record);
+    } catch {
+      // never disrupt
+    }
+  }
+}
+
+/**
+ * Uniform handling for an uncaught error: always write a structured record to
+ * the audit file, feed the run summary (when on), and show a neat compact
+ * trace on the console only with --debug (otherwise a single concise line).
+ * Exported for tests so they can exercise it without triggering process.exit.
+ */
+export function _handleUncaught(err: Error): void {
+  const structured = buildExcStructured(err);
+
+  // Always to the audit file (independent of --debug and of the summary toggle).
+  emitExceptionRecord(err, structured);
+
+  if (_summaryState) {
+    _summaryState.exception = { type: structured.type, message: structured.message, traceback: err.stack ?? '' };
+    _summaryState.exitCode = 1;
+  }
+
+  // Console: full compact trace only with --debug, else a one-liner.
+  try {
+    if (_debug) {
+      process.stderr.write(formatCompactTrace(err, structured.frames) + '\n');
+    } else {
+      process.stderr.write(`ERROR: ${structured.type}: ${structured.message}  (run with --debug for traceback)\n`);
+    }
+  } catch {
+    process.stderr.write((err.stack ?? String(err)) + '\n'); // safety fallback
+  }
+}
+
 function installExitHooks(): void {
   if (_exitHooksInstalled) return;
   _exitHooksInstalled = true;
@@ -469,43 +624,25 @@ function installExitHooks(): void {
   process.on('exit', (code) => {
     if (_summaryState && !_summaryState.emitted) {
       // process.exitCode wins over the explicit exception capture only if
-      // it's non-zero — uncaughtException already set state.exitCode=1.
+      // it's non-zero — _handleUncaught already set state.exitCode=1.
       if (code !== 0 && _summaryState.exitCode === 0) _summaryState.exitCode = code;
       emitRunSummary();
     }
   });
 
   // Skip the crash-handlers under jest — they call process.exit(1), which
-  // would tear down the test runner if any test ever produced an unhandled
-  // rejection. The 'exit' hook above is harmless and still runs.
+  // would tear down the test runner. _handleUncaught is unit-tested directly.
+  // The 'exit' hook above is harmless and still runs.
   if (process.env['JEST_WORKER_ID'] !== undefined) return;
 
   process.on('uncaughtException', (err: Error) => {
-    if (_summaryState) {
-      _summaryState.exception = {
-        type: err.name || 'Error',
-        message: err.message || String(err),
-        traceback: err.stack ?? '',
-      };
-      _summaryState.exitCode = 1;
-    }
-    // Preserve default Node behaviour: print and exit non-zero. The 'exit'
-    // hook above will fire and run emitRunSummary().
-    process.stderr.write((err.stack ?? String(err)) + '\n');
+    _handleUncaught(err);
     process.exit(1);
   });
 
   process.on('unhandledRejection', (reason: unknown) => {
-    if (_summaryState) {
-      const err = reason instanceof Error ? reason : new Error(String(reason));
-      _summaryState.exception = {
-        type: err.name || 'Error',
-        message: err.message || String(reason),
-        traceback: err.stack ?? '',
-      };
-      _summaryState.exitCode = 1;
-    }
-    process.stderr.write(`Unhandled rejection: ${reason instanceof Error ? (reason.stack ?? reason.message) : String(reason)}\n`);
+    const err = reason instanceof Error ? reason : new Error(String(reason));
+    _handleUncaught(err);
     process.exit(1);
   });
 }
@@ -554,14 +691,26 @@ export function configureLogging(opts: ConfigureLoggingOptions): void {
   if (!opts.logCfg || _configured) return;
 
   const debug = opts.debug ?? false;
+  _debug = debug;
   const floor = debug ? LEVEL_NUM['debug'] : LEVEL_NUM['info'];
 
+  // Unique ID for this invocation — injected into every file record (formatJson)
+  // and reused as the per-run filename token so file run_id == record run_id.
+  _runId = randomUUID();
+
   _handlers.push(new StdoutHandler(floor, debug));
   _handlers.push(new StderrHandler(debug));
 
   const logDir = resolveLogDir(opts.configPath);
-  const logPath = path.join(logDir, `${opts.runnableName}.log`);
-  _handlers.push(makeFileHandler(logPath, opts.logCfg.rotate, opts.logCfg.keep, floor));
+  if (opts.logCfg.store === 'per-run') {
+    // One file per invocation — multi-writer safe (no shared file, so no
+    // rotation race). rotate/keep are inert; retention is `runspec logs`.
+    const logPath = path.join(logDir, `${opts.runnableName}.${_perRunStamp(new Date())}.${_runId}.log`);
+    _handlers.push(new PlainFileHandler(logPath, floor));
+  } else {
+    const logPath = path.join(logDir, `${opts.runnableName}.log`);
+    _handlers.push(makeFileHandler(logPath, opts.logCfg.rotate, opts.logCfg.keep, floor));
+  }
 
   // Always attach the counter — cost is one dict increment per log call.
   // Only the exit hook + state population are conditional on summary mode.
@@ -589,9 +738,13 @@ export function configureLogging(opts: ConfigureLoggingOptions): void {
       user,
       userTarget,
     };
-    installExitHooks();
   }
 
+  // Uncaught-exception handling is always installed (independent of the summary
+  // toggle) so the structured exception record reaches the audit file even when
+  // summary is off. The exit hook only flushes a summary when _summaryState is set.
+  installExitHooks();
+
   _configured = true;
 }
 
@@ -599,6 +752,8 @@ export function configureLogging(opts: ConfigureLoggingOptions): void {
 
 export function _resetForTest(): void {
   _configured = false;
+  _debug = false;
+  _runId = null;
   _loggers.clear();
   _handlers.length = 0;
   _summaryState = null;
@@ -606,4 +761,4 @@ export function _resetForTest(): void {
   // they no-op when _summaryState is null, which is the test-time state.
 }
 
-export { _periodForDate, RUN_SUMMARY_LOGGER };
+export { _periodForDate, RUN_SUMMARY_LOGGER, EXCEPTION_LOGGER, buildExcStructured, formatCompactTrace };

package/src/models.ts

@@ -2,6 +2,9 @@ export interface LoggingConfig {
   rotate: string;
   keep: number;
   summary: boolean;
+  /** Log file layout: 'single' (default, one rotating {runnable}.log) or
+   *  'per-run' (one {runnable}.{utc-ts}.{run_id}.log per invocation). */
+  store?: string;
 }
 
 export interface RawConfig {

package/tests/test_emit_schema.test.ts

@@ -30,3 +30,19 @@ slug = {type = "str", pattern = "[a-z]+-[0-9]+", min-length = 3, max-length = 10
   expect(slug['minLength']).toBe(3);
   expect(slug['maxLength']).toBe(10);
 });
+
+test('multiple arg emits array with per-item constraints inside items', () => {
+  const schema = schemaFor(
+    `
+[deploy]
+[deploy.args]
+ticket = {type = "str", multiple = true, pattern = "[A-Z]+-[0-9]+"}
+`,
+    'deploy',
+  );
+  const props = (schema['inputSchema'] as Record<string, Record<string, unknown>>)['properties'];
+  const ticket = (props as Record<string, Record<string, unknown>>)['ticket'];
+  expect(ticket['type']).toBe('array');
+  // The per-item constraint validates each element, so it belongs in items.
+  expect(ticket['items']).toEqual({ type: 'string', pattern: '[A-Z]+-[0-9]+' });
+});

package/tests/test_inference.test.ts

@@ -1,4 +1,4 @@
-import { inferArg, inferScript, effectiveAutonomy, isMoreRestrictive } from '../src/inference';
+import { inferArg, inferScript, effectiveAutonomy, isMoreRestrictive, tsTypeOf } from '../src/inference';
 import { RunSpecError } from '../src/errors';
 import type { ArgSpec, ScriptSpec } from '../src/models';
 
@@ -151,3 +151,31 @@ test('manual is more restrictive than confirm', () => {
 test('autonomous is not more restrictive than confirm', () => {
   expect(isMoreRestrictive('autonomous', 'confirm')).toBe(false);
 });
+
+// ── tsTypeOf (derived value type, computed on demand) ──────────────────────────
+
+test('tsTypeOf: scalar types', () => {
+  expect(tsTypeOf(makeArg({ type: 'str' }))).toBe('string');
+  expect(tsTypeOf(makeArg({ type: 'int' }))).toBe('number');
+  expect(tsTypeOf(makeArg({ type: 'flag' }))).toBe('boolean');
+  expect(tsTypeOf(makeArg({ type: 'path' }))).toBe('string');
+});
+
+test('tsTypeOf: multiple suffixes []', () => {
+  expect(tsTypeOf(makeArg({ type: 'str', multiple: true }))).toBe('string[]');
+  expect(tsTypeOf(makeArg({ type: 'int', multiple: true }))).toBe('number[]');
+});
+
+test('tsTypeOf: rest is string[]', () => {
+  expect(tsTypeOf(makeArg({ type: 'rest' }))).toBe('string[]');
+});
+
+test('tsTypeOf: custom type falls back to unknown', () => {
+  expect(tsTypeOf(makeArg({ type: 'json-file', multiple: true }))).toBe('unknown[]');
+});
+
+test('tsTypeOf works on an inferred ArgSpec; type stays the item type', () => {
+  const arg = inferArg(makeArg({ type: 'str', multiple: true }));
+  expect(arg.type).toBe('str');
+  expect(tsTypeOf(arg)).toBe('string[]');
+});

package/tests/test_loader.test.ts

@@ -178,7 +178,35 @@ test('normalises [config.logging] with defaults', () => {
 description = "hi"
 `);
   const raw = loadRaw(file);
-  expect(raw.config.logging).toEqual({ rotate: 'midnight', keep: 7, summary: true });
+  expect(raw.config.logging).toEqual({ rotate: 'midnight', keep: 7, summary: true, store: 'single' });
+});
+
+test('normalises [config.logging] store = per-run', () => {
+  const dir = tmpDir();
+  const file = path.join(dir, 'runspec.toml');
+  fs.writeFileSync(file, `
+[config.logging]
+store = "per-run"
+
+[greet]
+description = "hi"
+`);
+  const raw = loadRaw(file);
+  expect(raw.config.logging?.store).toBe('per-run');
+});
+
+test('normalises [config.logging] unknown store falls back to single', () => {
+  const dir = tmpDir();
+  const file = path.join(dir, 'runspec.toml');
+  fs.writeFileSync(file, `
+[config.logging]
+store = "bogus"
+
+[greet]
+description = "hi"
+`);
+  const raw = loadRaw(file);
+  expect(raw.config.logging?.store).toBe('single');
 });
 
 test('normalises [config.logging] all fields', () => {
@@ -194,7 +222,7 @@ summary = false
 description = "hi"
 `);
   const raw = loadRaw(file);
-  expect(raw.config.logging).toEqual({ rotate: '10 MB', keep: 3, summary: false });
+  expect(raw.config.logging).toEqual({ rotate: '10 MB', keep: 3, summary: false, store: 'single' });
 });
 
 test('[config.logging] summary defaults to true when omitted', () => {

package/tests/test_logging_setup.test.ts

@@ -407,17 +407,20 @@ test('extra fields appear under "extra" key in JSON', () => {
   getLogger('test').info('connected', { user_id: '42', region: 'eu-west' });
   const content = fs.readFileSync(path.join(dir, 'logs', 'myscript.log'), 'utf-8').trim();
   const record = JSON.parse(content);
-  expect(record.extra).toEqual({ user_id: '42', region: 'eu-west' });
+  // run_id is always present on file records (SPEC §run_id); user fields ride alongside.
+  expect(record.extra).toMatchObject({ user_id: '42', region: 'eu-west' });
+  expect(typeof record.extra.run_id).toBe('string');
   expect(record.message).toBe('connected');
 });
 
-test('no "extra" key when no extra fields', () => {
+test('run_id is the only extra field when none supplied', () => {
   const dir = tmpDir();
   configureLogging(makeCfg(dir));
   getLogger('test').info('plain message');
   const content = fs.readFileSync(path.join(dir, 'logs', 'myscript.log'), 'utf-8').trim();
   const record = JSON.parse(content);
-  expect(record.extra).toBeUndefined();
+  expect(Object.keys(record.extra)).toEqual(['run_id']);
+  expect(typeof record.extra.run_id).toBe('string');
 });
 
 test('error key extracted from fields, not placed in extra', () => {
@@ -428,17 +431,17 @@ test('error key extracted from fields, not placed in extra', () => {
   const record = JSON.parse(content);
   expect(typeof record.exc).toBe('string');
   expect(record.exc).toContain('oops');
-  expect(record.extra).toEqual({ user_id: '42' });
+  expect(record.extra).toMatchObject({ user_id: '42' });
   expect(record.extra?.error).toBeUndefined();
 });
 
-test('error-only fields: no extra key', () => {
+test('error-only fields: extra holds just run_id', () => {
   const dir = tmpDir();
   configureLogging(makeCfg(dir));
   getLogger('test').error('boom', { error: new Error('oops') });
   const content = fs.readFileSync(path.join(dir, 'logs', 'myscript.log'), 'utf-8').trim();
   const record = JSON.parse(content);
-  expect(record.extra).toBeUndefined();
+  expect(Object.keys(record.extra)).toEqual(['run_id']);
   expect(typeof record.exc).toBe('string');
 });
 
@@ -473,3 +476,58 @@ test('extra fields appear in console output', () => {
   expect(lines.some(l => l.includes('user_id=42'))).toBe(true);
   stdoutWrite.mockRestore();
 });
+
+// ── store = "per-run" ───────────────────────────────────────────────────────────
+
+const PER_RUN_RE = /^myscript\.\d{8}T\d{6}Z\.[0-9a-fA-F-]{8,}\.log$/;
+
+function perRunFile(dir: string): string | undefined {
+  return fs.readdirSync(path.join(dir, 'logs')).find(f => PER_RUN_RE.test(f));
+}
+
+test('per-run: writes {runnable}.{ts}.{run_id}.log, not {runnable}.log', () => {
+  const dir = tmpDir();
+  configureLogging(makeCfg(dir, { store: 'per-run' }));
+  getLogger('test').info('hi');
+  const files = fs.readdirSync(path.join(dir, 'logs'));
+  expect(files.some(f => PER_RUN_RE.test(f))).toBe(true);
+  expect(files).not.toContain('myscript.log');
+});
+
+test('per-run: run_id in filename matches extra.run_id in records', () => {
+  const dir = tmpDir();
+  configureLogging(makeCfg(dir, { store: 'per-run' }));
+  getLogger('test').info('hi');
+  const fname = perRunFile(dir)!;
+  const fileRunId = fname.replace(/\.log$/, '').split('.').pop();
+  const record = JSON.parse(fs.readFileSync(path.join(dir, 'logs', fname), 'utf-8').trim());
+  expect(record.extra.run_id).toBe(fileRunId);
+});
+
+test('per-run: no rotation even when rotate is set', () => {
+  const dir = tmpDir();
+  // a tiny size threshold would rotate a single file immediately; per-run must not.
+  configureLogging(makeCfg(dir, { store: 'per-run', rotate: '1 KB' }));
+  const log = getLogger('test');
+  // ~30 × ~60 bytes well exceeds the 1 KB threshold a rotating handler would act on.
+  for (let i = 0; i < 30; i++) log.info(`line ${i} ${'x'.repeat(50)}`);
+  const files = fs.readdirSync(path.join(dir, 'logs'));
+  // exactly one per-run file, and no rotated backups (.log.1 etc.)
+  expect(files.filter(f => PER_RUN_RE.test(f))).toHaveLength(1);
+  expect(files.some(f => /\.log\.\d+$/.test(f))).toBe(false);
+});
+
+test('per-run: no empty file when nothing is logged', () => {
+  const dir = tmpDir();
+  configureLogging(makeCfg(dir, { store: 'per-run' }));
+  // summary is off in makeCfg and we log nothing → lazy append means no file.
+  expect(perRunFile(dir)).toBeUndefined();
+});
+
+test('default store is single ({runnable}.log)', () => {
+  const dir = tmpDir();
+  configureLogging(makeCfg(dir)); // no store override
+  getLogger('test').info('hi');
+  expect(fs.existsSync(path.join(dir, 'logs', 'myscript.log'))).toBe(true);
+  expect(perRunFile(dir)).toBeUndefined();
+});