@milaboratories/pl-crash-recorder 0.3.0

package/dist/recorder.js

@@ -0,0 +1,278 @@
+import { MEM_BASELINE_RECORD, SESSION_END_RECORD, SESSION_FILE_PREFIX, SESSION_RECORD } from "./events.js";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import v8 from "node:v8";
+//#region src/recorder.ts
+/**
+* Opens a crash log for this process and writes the session header.
+*
+* Records are appended with a synchronous write rather than through a stream:
+* the process being recorded dies without warning — V8 fatal out-of-memory, a
+* failed native allocation, the OS out-of-memory killer — so no exit hook, no
+* flush and no `finally` block runs. Anything still sitting in a userspace
+* buffer is exactly the part that would have explained the death.
+*/
+function openRecorder(options) {
+	const { dir, role = "middle-layer", meta = {}, maxFileBytes = 32 * 1024 * 1024, sessionId = newSessionId() } = options;
+	fs.mkdirSync(dir, { recursive: true });
+	const file = path.join(dir, `${SESSION_FILE_PREFIX}-${sessionId}.ndjson`);
+	const state = {
+		fd: fs.openSync(file, "a"),
+		bytes: 0,
+		preambleBytes: 0,
+		seq: 0,
+		closed: false,
+		header: void 0,
+		baselineMem: void 0,
+		openBegins: /* @__PURE__ */ new Map(),
+		sticky: /* @__PURE__ */ new Map()
+	};
+	const memorySnapshot = () => {
+		const usage = process.memoryUsage();
+		return {
+			rss: usage.rss,
+			heapUsed: usage.heapUsed,
+			heapTotal: usage.heapTotal,
+			external: usage.external,
+			arrayBuffers: usage.arrayBuffers,
+			heapLimit: v8.getHeapStatistics().heap_size_limit
+		};
+	};
+	const event = (type, payload = {}) => {
+		if (state.closed) return -1;
+		const seq = ++state.seq;
+		const record = {
+			seq,
+			t: monotonic(),
+			wall: Date.now(),
+			type,
+			...payload
+		};
+		if (state.baselineMem === void 0 && record.mem) state.baselineMem = record.mem;
+		trackOpenOperation(state, record);
+		writeLine(state, file, maxFileBytes, record);
+		return seq;
+	};
+	const sticky = (key, type, payload) => {
+		if (state.sticky.has(key)) return;
+		const retained = state.sticky.size < MAX_STICKY_RECORDS;
+		const seq = event(type, retained ? payload : {
+			...payload,
+			notRetained: true
+		});
+		if (!retained) return;
+		const record = {
+			...payload,
+			seq,
+			type
+		};
+		state.sticky.set(key, record);
+	};
+	const recorder = {
+		sessionId,
+		file,
+		event,
+		sticky,
+		memorySnapshot,
+		close(reason = "normal") {
+			if (state.closed) return;
+			event(SESSION_END_RECORD, {
+				reason,
+				mem: memorySnapshot()
+			});
+			state.closed = true;
+			try {
+				fs.closeSync(state.fd);
+			} catch {}
+		}
+	};
+	state.header = {
+		role,
+		pid: process.pid,
+		meta,
+		env: describeEnvironment()
+	};
+	event(SESSION_RECORD, {
+		...state.header,
+		mem: memorySnapshot()
+	});
+	return recorder;
+}
+/**
+* Periodic memory record written by the recorded thread itself.
+*
+* Doubles as a stall detector. This timer cannot fire while its thread is inside
+* a long synchronous call, so a gap here that the independent sampler thread
+* does not share means the thread was blocked — which is also why the heap
+* reading nearest a synchronous blow-up is always stale.
+*/
+function startSelfSampler(recorder, intervalMs = 500) {
+	let last = Date.now();
+	const timer = setInterval(() => {
+		const now = Date.now();
+		recorder.event("mem-self", {
+			mem: recorder.memorySnapshot(),
+			stallMs: Math.max(0, now - last - intervalMs)
+		});
+		last = now;
+	}, intervalMs);
+	timer.unref();
+	return () => clearInterval(timer);
+}
+/** Crash logs in a directory, newest first, each flagged as crashed or clean. */
+function listSessions(dir) {
+	let names;
+	try {
+		names = fs.readdirSync(dir);
+	} catch {
+		return [];
+	}
+	return names.filter((name) => name.startsWith(`session-`) && name.endsWith(".ndjson")).map((name) => {
+		const file = path.join(dir, name);
+		const stat = fs.statSync(file);
+		return {
+			file,
+			mtimeMs: stat.mtimeMs,
+			bytes: stat.size,
+			crashed: !hasSessionEnd(file)
+		};
+	}).sort((lhs, rhs) => rhs.mtimeMs - lhs.mtimeMs);
+}
+/**
+* Mints a session id. A parent that supervises a worker calls this, hands the id
+* to the worker, and keeps it for the crash marker, so both sides agree on the
+* session by construction. The leading timestamp is what
+* {@link sessionStartFromId} reads back.
+*/
+function newSessionId() {
+	return `${Date.now()}-${process.pid}-${randomTag()}`;
+}
+/** Session id embedded in a crash log's file name. */
+function sessionIdFromFile(file) {
+	const match = path.basename(file).match(new RegExp(`^${SESSION_FILE_PREFIX}-(.+)\\.ndjson(\\.1)?$`));
+	return match ? match[1] : path.basename(file);
+}
+/** How many sticky records a session may keep, bounding the rewritten preamble. */
+const MAX_STICKY_RECORDS = 64;
+/** Cap on carried-forward begins, so a leak cannot make the preamble unbounded. */
+const MAX_CARRIED_BEGINS = 256;
+function writeLine(state, file, maxFileBytes, record) {
+	let line;
+	try {
+		line = `${JSON.stringify(record, bigintSafe)}\n`;
+	} catch {
+		line = `${JSON.stringify({
+			seq: record.seq,
+			type: "record-serialization-failed"
+		})}\n`;
+	}
+	try {
+		if (state.bytes - state.preambleBytes + line.length > maxFileBytes) {
+			rotate(state, file);
+			writePreamble(state);
+		}
+		fs.writeSync(state.fd, line);
+		state.bytes += line.length;
+	} catch {}
+}
+function rotate(state, file) {
+	fs.closeSync(state.fd);
+	try {
+		fs.renameSync(file, `${file}.1`);
+	} catch {}
+	state.fd = fs.openSync(file, "a");
+	state.bytes = 0;
+	state.preambleBytes = 0;
+}
+/**
+* Rewrites into the new segment the three things a report cannot be produced
+* without, so repeated rotation costs only completed operations.
+*
+* Losing an *open* begin record would remove that operation from pairing
+* entirely, and the operation still running at the moment of death is the one
+* the report exists to name. Losing the earliest memory reading would leave the
+* heap series starting mid-session while the sampler's resident series still
+* starts at zero, which biases the classifier toward blaming native memory.
+*/
+function writePreamble(state) {
+	if (state.header) emitPreambleRecord(state, {
+		seq: ++state.seq,
+		t: monotonic(),
+		wall: Date.now(),
+		type: SESSION_RECORD,
+		...state.header,
+		continuation: true
+	});
+	if (state.baselineMem) emitPreambleRecord(state, {
+		seq: ++state.seq,
+		t: monotonic(),
+		wall: Date.now(),
+		type: MEM_BASELINE_RECORD,
+		mem: state.baselineMem,
+		carriedForward: true
+	});
+	for (const record of state.sticky.values()) emitPreambleRecord(state, {
+		...record,
+		carriedForward: true
+	});
+	for (const begin of state.openBegins.values()) emitPreambleRecord(state, {
+		...begin,
+		carriedForward: true
+	});
+}
+function emitPreambleRecord(state, record) {
+	try {
+		const line = `${JSON.stringify(record, bigintSafe)}\n`;
+		fs.writeSync(state.fd, line);
+		state.bytes += line.length;
+		state.preambleBytes += line.length;
+	} catch {}
+}
+function trackOpenOperation(state, record) {
+	if (record.type.endsWith("-begin")) {
+		if (state.openBegins.size < MAX_CARRIED_BEGINS) state.openBegins.set(record.seq, record);
+		return;
+	}
+	if (record.type.endsWith("-end") || record.type.endsWith("-error")) {
+		if (typeof record.begin === "number") state.openBegins.delete(record.begin);
+	}
+}
+function hasSessionEnd(file) {
+	const size = fs.statSync(file).size;
+	if (size === 0) return false;
+	const window = Math.min(size, 8192);
+	const buffer = Buffer.alloc(window);
+	const fd = fs.openSync(file, "r");
+	try {
+		fs.readSync(fd, buffer, 0, window, size - window);
+	} finally {
+		fs.closeSync(fd);
+	}
+	return buffer.toString("utf8").includes(`"type":"${SESSION_END_RECORD}"`);
+}
+function describeEnvironment() {
+	const maxOldSpaceFlag = process.execArgv.find((arg) => arg.startsWith("--max-old-space-size"));
+	return {
+		node: process.version,
+		platform: `${process.platform}-${process.arch}`,
+		cpus: os.cpus().length,
+		totalMemory: os.totalmem(),
+		heapLimit: v8.getHeapStatistics().heap_size_limit,
+		execArgv: [...process.execArgv],
+		maxOldSpaceSize: maxOldSpaceFlag ? Number(maxOldSpaceFlag.split("=")[1]) : void 0
+	};
+}
+function bigintSafe(_key, value) {
+	return typeof value === "bigint" ? Number(value) : value;
+}
+function monotonic() {
+	return Math.round(performance.now() * 1e3) / 1e3;
+}
+function randomTag() {
+	return Math.random().toString(36).slice(2, 8);
+}
+//#endregion
+export { listSessions, newSessionId, openRecorder, sessionIdFromFile, startSelfSampler };
+
+//# sourceMappingURL=recorder.js.map

package/dist/recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.js","names":[],"sources":["../src/recorder.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport os from \"node:os\";\nimport v8 from \"node:v8\";\nimport {\n  SESSION_FILE_PREFIX,\n  MEM_BASELINE_RECORD,\n  SESSION_END_RECORD,\n  SESSION_RECORD,\n  type LogRecord,\n  type MemorySnapshot,\n  type SessionEnvironment,\n} from \"./events\";\n\nexport type RecorderOptions = {\n  /** Directory holding crash logs; created if absent. */\n  dir: string;\n  /** Which part of the app is recording, e.g. `middle-layer`. */\n  role?: string;\n  /** Free-form context stored in the session header (app version, project id). */\n  meta?: Record<string, unknown>;\n  /** Log is rotated past this size so the tail, which explains the crash, survives. */\n  maxFileBytes?: number;\n  /**\n   * Session id assigned by a supervising parent, so the crash marker the parent\n   * writes names this session with certainty rather than by inference.\n   * Generated when absent.\n   */\n  sessionId?: string;\n};\n\nexport type Recorder = {\n  readonly sessionId: string;\n  readonly file: string;\n  /** Appends one record and returns its sequence number. Never throws. */\n  event(type: string, payload?: Record<string, unknown>): number;\n  /**\n   * Appends a record that every later segment of the log gets again.\n   *\n   * For a fact stated once that the rest of the log is unreadable without — what\n   * a block id stands for, say. Written once per `key`; a rotation that discards\n   * the original rewrites it, so a long session cannot outlive its own legend.\n   *\n   * Past a cap on how many such facts a session may carry, the record is still\n   * written once and marked `notRetained`: it then survives only until the\n   * rotation that discards it.\n   */\n  sticky(key: string, type: string, payload?: Record<string, unknown>): void;\n  /** Memory reading for the calling thread; `rss` is process-wide. */\n  memorySnapshot(): MemorySnapshot;\n  /** Writes the terminating record. Its absence is how a crash is detected. */\n  close(reason?: string): void;\n};\n\nexport type SessionFileInfo = {\n  file: string;\n  mtimeMs: number;\n  bytes: number;\n  /** True when the log has no terminating record, i.e. the process died. */\n  crashed: boolean;\n};\n\ntype ParsedSession = {\n  file: string;\n  records: LogRecord[];\n  /** True when the last line was cut mid-write by the kill. */\n  truncatedTail: boolean;\n};\n\n/**\n * Opens a crash log for this process and writes the session header.\n *\n * Records are appended with a synchronous write rather than through a stream:\n * the process being recorded dies without warning — V8 fatal out-of-memory, a\n * failed native allocation, the OS out-of-memory killer — so no exit hook, no\n * flush and no `finally` block runs. Anything still sitting in a userspace\n * buffer is exactly the part that would have explained the death.\n */\nexport function openRecorder(options: RecorderOptions): Recorder {\n  const {\n    dir,\n    role = \"middle-layer\",\n    meta = {},\n    maxFileBytes = 32 * 1024 * 1024,\n    sessionId = newSessionId(),\n  } = options;\n  fs.mkdirSync(dir, { recursive: true });\n\n  const file = path.join(dir, `${SESSION_FILE_PREFIX}-${sessionId}.ndjson`);\n  const state: WriterState = {\n    fd: fs.openSync(file, \"a\"),\n    bytes: 0,\n    preambleBytes: 0,\n    seq: 0,\n    closed: false,\n    header: undefined,\n    baselineMem: undefined,\n    openBegins: new Map(),\n    sticky: new Map(),\n  };\n\n  const memorySnapshot = (): MemorySnapshot => {\n    const usage = process.memoryUsage();\n    return {\n      rss: usage.rss,\n      heapUsed: usage.heapUsed,\n      heapTotal: usage.heapTotal,\n      external: usage.external,\n      arrayBuffers: usage.arrayBuffers,\n      heapLimit: v8.getHeapStatistics().heap_size_limit,\n    };\n  };\n\n  const event = (type: string, payload: Record<string, unknown> = {}): number => {\n    if (state.closed) return -1;\n    const seq = ++state.seq;\n    const record: LogRecord = {\n      seq,\n      t: monotonic(),\n      wall: Date.now(),\n      type,\n      ...payload,\n    };\n    if (state.baselineMem === undefined && record.mem) state.baselineMem = record.mem;\n    trackOpenOperation(state, record);\n    writeLine(state, file, maxFileBytes, record);\n    return seq;\n  };\n\n  const sticky = (key: string, type: string, payload?: Record<string, unknown>): void => {\n    if (state.sticky.has(key)) return;\n    // The preamble is rewritten in full at every rotation, so it cannot grow\n    // without bound. Past the cap the fact is still written once — losing it\n    // entirely would leave records naming a block nothing can identify — and\n    // only its survival across rotation is given up. The record says so, so a\n    // reader can tell a missing legend from one that was never written.\n    const retained = state.sticky.size < MAX_STICKY_RECORDS;\n    const seq = event(type, retained ? payload : { ...payload, notRetained: true });\n    if (!retained) return;\n    const record = { ...payload, seq, type } as LogRecord;\n    state.sticky.set(key, record);\n  };\n\n  const recorder: Recorder = {\n    sessionId,\n    file,\n    event,\n    sticky,\n    memorySnapshot,\n    close(reason = \"normal\") {\n      if (state.closed) return;\n      event(SESSION_END_RECORD, { reason, mem: memorySnapshot() });\n      state.closed = true;\n      try {\n        fs.closeSync(state.fd);\n      } catch {\n        // Closing an already-dead descriptor must not fail shutdown.\n      }\n    },\n  };\n\n  // Kept so a rotated log can be given the same header again: the active file\n  // must describe its own session even if the parked segment is lost.\n  state.header = { role, pid: process.pid, meta, env: describeEnvironment() };\n  event(SESSION_RECORD, { ...state.header, mem: memorySnapshot() });\n\n  return recorder;\n}\n\n/**\n * Periodic memory record written by the recorded thread itself.\n *\n * Doubles as a stall detector. This timer cannot fire while its thread is inside\n * a long synchronous call, so a gap here that the independent sampler thread\n * does not share means the thread was blocked — which is also why the heap\n * reading nearest a synchronous blow-up is always stale.\n */\nexport function startSelfSampler(recorder: Recorder, intervalMs = 500): () => void {\n  let last = Date.now();\n  const timer = setInterval(() => {\n    const now = Date.now();\n    recorder.event(\"mem-self\", {\n      mem: recorder.memorySnapshot(),\n      stallMs: Math.max(0, now - last - intervalMs),\n    });\n    last = now;\n  }, intervalMs);\n  timer.unref();\n  return () => clearInterval(timer);\n}\n\n/** Crash logs in a directory, newest first, each flagged as crashed or clean. */\nexport function listSessions(dir: string): SessionFileInfo[] {\n  let names: string[];\n  try {\n    names = fs.readdirSync(dir);\n  } catch {\n    return [];\n  }\n  return names\n    .filter((name) => name.startsWith(`${SESSION_FILE_PREFIX}-`) && name.endsWith(\".ndjson\"))\n    .map((name) => {\n      const file = path.join(dir, name);\n      const stat = fs.statSync(file);\n      return { file, mtimeMs: stat.mtimeMs, bytes: stat.size, crashed: !hasSessionEnd(file) };\n    })\n    .sort((lhs, rhs) => rhs.mtimeMs - lhs.mtimeMs);\n}\n\n/**\n * Parses a crash log, tolerating a final line cut short by a hard kill.\n *\n * A rotated session spans two files: the parked `.1` segment holds the original\n * header and the earlier operations, the active file holds the tail. Both are\n * read so begin records in one segment can be paired with end records in the\n * other; sequence numbers run across the boundary.\n */\nexport function readSession(file: string): ParsedSession {\n  const records: LogRecord[] = [];\n  let truncatedTail = false;\n  const parked = `${file}.1`;\n  if (fs.existsSync(parked)) {\n    for (const line of fs.readFileSync(parked, \"utf8\").split(\"\\n\")) {\n      if (line === \"\") continue;\n      try {\n        records.push(JSON.parse(line) as LogRecord);\n      } catch {\n        // A damaged line in the parked segment costs one record, not the session.\n      }\n    }\n  }\n  const lines = fs.readFileSync(file, \"utf8\").split(\"\\n\");\n  for (const [index, line] of lines.entries()) {\n    if (line === \"\") continue;\n    try {\n      records.push(JSON.parse(line) as LogRecord);\n    } catch {\n      if (index >= lines.length - 2) truncatedTail = true;\n    }\n  }\n  return { file, records, truncatedTail };\n}\n\n/**\n * Mints a session id. A parent that supervises a worker calls this, hands the id\n * to the worker, and keeps it for the crash marker, so both sides agree on the\n * session by construction. The leading timestamp is what\n * {@link sessionStartFromId} reads back.\n */\nexport function newSessionId(): string {\n  return `${Date.now()}-${process.pid}-${randomTag()}`;\n}\n\n/** Wall-clock start of a session, taken from the id its file name carries. */\nexport function sessionStartFromId(sessionId: string): number {\n  const start = Number(sessionId.split(\"-\")[0]);\n  return Number.isFinite(start) ? start : 0;\n}\n\n/** Session id embedded in a crash log's file name. */\nexport function sessionIdFromFile(file: string): string {\n  const match = path\n    .basename(file)\n    .match(new RegExp(`^${SESSION_FILE_PREFIX}-(.+)\\\\.ndjson(\\\\.1)?$`));\n  return match ? match[1] : path.basename(file);\n}\n\n// Internals\n\n/** How many sticky records a session may keep, bounding the rewritten preamble. */\nconst MAX_STICKY_RECORDS = 64;\n\ntype WriterState = {\n  fd: number;\n  bytes: number;\n  /** Bytes of the carried-forward preamble, which do not count toward the limit. */\n  preambleBytes: number;\n  seq: number;\n  closed: boolean;\n  header: Record<string, unknown> | undefined;\n  /** Earliest memory reading of the session, so growth stays measurable. */\n  baselineMem: MemorySnapshot | undefined;\n  /** Begin records with no end yet, keyed by their sequence number. */\n  openBegins: Map<number, LogRecord>;\n  /** Records rewritten into every later segment, keyed by the caller's key. */\n  sticky: Map<string, LogRecord>;\n};\n\n/** Cap on carried-forward begins, so a leak cannot make the preamble unbounded. */\nconst MAX_CARRIED_BEGINS = 256;\n\nfunction writeLine(\n  state: WriterState,\n  file: string,\n  maxFileBytes: number,\n  record: LogRecord,\n): void {\n  let line: string;\n  try {\n    line = `${JSON.stringify(record, bigintSafe)}\\n`;\n  } catch {\n    line = `${JSON.stringify({ seq: record.seq, type: \"record-serialization-failed\" })}\\n`;\n  }\n  try {\n    // The preamble is not charged against the limit, so a large preamble cannot\n    // trigger another rotation on the very next write.\n    if (state.bytes - state.preambleBytes + line.length > maxFileBytes) {\n      rotate(state, file);\n      writePreamble(state);\n    }\n    fs.writeSync(state.fd, line);\n    state.bytes += line.length;\n  } catch {\n    // A recorder that cannot write stays silent rather than cascading into the\n    // application it is only supposed to observe.\n  }\n}\n\n// The tail is the only part that explains a crash, so the old file is parked\n// beside the new one instead of the new writes being dropped. Exactly one parked\n// segment is kept, which bounds a session's disk use at twice the file limit.\nfunction rotate(state: WriterState, file: string): void {\n  fs.closeSync(state.fd);\n  try {\n    fs.renameSync(file, `${file}.1`);\n  } catch {\n    // If the parked slot cannot be written, recording simply continues.\n  }\n  state.fd = fs.openSync(file, \"a\");\n  state.bytes = 0;\n  state.preambleBytes = 0;\n}\n\n/**\n * Rewrites into the new segment the three things a report cannot be produced\n * without, so repeated rotation costs only completed operations.\n *\n * Losing an *open* begin record would remove that operation from pairing\n * entirely, and the operation still running at the moment of death is the one\n * the report exists to name. Losing the earliest memory reading would leave the\n * heap series starting mid-session while the sampler's resident series still\n * starts at zero, which biases the classifier toward blaming native memory.\n */\nfunction writePreamble(state: WriterState): void {\n  if (state.header) {\n    emitPreambleRecord(state, {\n      seq: ++state.seq,\n      t: monotonic(),\n      wall: Date.now(),\n      type: SESSION_RECORD,\n      ...state.header,\n      continuation: true,\n    });\n  }\n  if (state.baselineMem) {\n    emitPreambleRecord(state, {\n      seq: ++state.seq,\n      t: monotonic(),\n      wall: Date.now(),\n      type: MEM_BASELINE_RECORD,\n      mem: state.baselineMem,\n      carriedForward: true,\n    });\n  }\n  for (const record of state.sticky.values()) {\n    emitPreambleRecord(state, { ...record, carriedForward: true });\n  }\n  // Original sequence numbers are kept, which is what lets an end record in a\n  // later segment pair with a begin first written in an overwritten one.\n  for (const begin of state.openBegins.values()) {\n    emitPreambleRecord(state, { ...begin, carriedForward: true });\n  }\n}\n\nfunction emitPreambleRecord(state: WriterState, record: LogRecord): void {\n  try {\n    const line = `${JSON.stringify(record, bigintSafe)}\\n`;\n    fs.writeSync(state.fd, line);\n    state.bytes += line.length;\n    state.preambleBytes += line.length;\n  } catch {\n    // A preamble that cannot be written must not stop the session.\n  }\n}\n\n// Open operations are tracked by the same suffix convention the analyzer pairs\n// on, so the recorder needs no separate vocabulary for them.\nfunction trackOpenOperation(state: WriterState, record: LogRecord): void {\n  if (record.type.endsWith(\"-begin\")) {\n    if (state.openBegins.size < MAX_CARRIED_BEGINS) state.openBegins.set(record.seq, record);\n    return;\n  }\n  if (record.type.endsWith(\"-end\") || record.type.endsWith(\"-error\")) {\n    if (typeof record.begin === \"number\") state.openBegins.delete(record.begin);\n  }\n}\n\nfunction hasSessionEnd(file: string): boolean {\n  const size = fs.statSync(file).size;\n  if (size === 0) return false;\n  const window = Math.min(size, 8192);\n  const buffer = Buffer.alloc(window);\n  const fd = fs.openSync(file, \"r\");\n  try {\n    fs.readSync(fd, buffer, 0, window, size - window);\n  } finally {\n    fs.closeSync(fd);\n  }\n  return buffer.toString(\"utf8\").includes(`\"type\":\"${SESSION_END_RECORD}\"`);\n}\n\nfunction describeEnvironment(): SessionEnvironment {\n  const maxOldSpaceFlag = process.execArgv.find((arg) => arg.startsWith(\"--max-old-space-size\"));\n  return {\n    node: process.version,\n    platform: `${process.platform}-${process.arch}`,\n    cpus: os.cpus().length,\n    totalMemory: os.totalmem(),\n    heapLimit: v8.getHeapStatistics().heap_size_limit,\n    execArgv: [...process.execArgv],\n    maxOldSpaceSize: maxOldSpaceFlag ? Number(maxOldSpaceFlag.split(\"=\")[1]) : undefined,\n  };\n}\n\nfunction bigintSafe(_key: string, value: unknown): unknown {\n  return typeof value === \"bigint\" ? Number(value) : value;\n}\n\nfunction monotonic(): number {\n  return Math.round(performance.now() * 1000) / 1000;\n}\n\nfunction randomTag(): string {\n  return Math.random().toString(36).slice(2, 8);\n}\n"],"mappings":"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"}

package/dist/redact.js

@@ -0,0 +1,141 @@
+import { summarizeData } from "./data_summary.js";
+import crypto from "node:crypto";
+//#region src/redact.ts
+/**
+* Structure-preserving redaction for anything a driver seam is handed.
+*
+* The definition a block model builds is recorded by *shape* rather than by a
+* hand-written digest per definition type. Keys, numbers and the small set of
+* strings that are schema survive verbatim; every other string is replaced by a
+* hash and a length. That keeps the record useful for diagnosis, keeps customer
+* data out of it by default rather than by enumeration, and works unchanged for
+* definition shapes this code has never seen — the V2 query API included.
+*
+* The default for an unrecognised string is to hash it. A new field can
+* therefore make a report less informative, but never make it leak.
+*/
+/** Keys whose string value is schema, kept as written. */
+const SCHEMA_KEYS = /* @__PURE__ */ new Set([
+	"type",
+	"name",
+	"valueType",
+	"kind",
+	"operator",
+	"mode"
+]);
+/** Keys under which every string is schema, at any depth (axis identity). */
+const SCHEMA_SUBTREE_KEYS = /* @__PURE__ */ new Set(["domain", "contextDomain"]);
+/** Keys never descended into; summarised by counts instead. */
+const SUMMARISED_KEYS = /* @__PURE__ */ new Set(["data", "dataInfo"]);
+/** Keys reduced to a cardinality, because their contents are values. */
+const COUNTED_KEYS = /* @__PURE__ */ new Set(["references", "parts"]);
+/** Redacts a definition, returning the new value and what had to be elided. */
+function redact(value, options = {}) {
+	const limits = {
+		maxDepth: options.maxDepth ?? 32,
+		maxArrayItems: options.maxArrayItems ?? 64,
+		maxStringLength: options.maxStringLength ?? 128,
+		maxNodes: options.maxNodes ?? 2e4
+	};
+	const stats = {
+		hashedStrings: 0,
+		truncatedArrays: 0,
+		omittedItems: 0,
+		depthCapped: 0,
+		opaqueObjects: 0,
+		budgetExhausted: false
+	};
+	return {
+		value: walk(value, {
+			key: void 0,
+			schemaSubtree: false,
+			depth: 0
+		}, limits, stats, {
+			nodes: 0,
+			seen: /* @__PURE__ */ new WeakSet()
+		}),
+		stats
+	};
+}
+/** Stable short hash plus the original length. Never reversible to the value. */
+function hashString(value) {
+	return {
+		h: crypto.createHash("sha256").update(value).digest("hex").slice(0, 12),
+		n: value.length
+	};
+}
+function walk(value, at, limits, stats, state) {
+	if (state.nodes++ > limits.maxNodes) {
+		stats.budgetExhausted = true;
+		return { $budget: true };
+	}
+	if (value === null || value === void 0) return value ?? null;
+	if (typeof value === "bigint") return Number(value);
+	if (typeof value === "number" || typeof value === "boolean") return value;
+	if (typeof value === "string") return redactString(value, at, limits, stats);
+	if (typeof value !== "object") return { $type: typeof value };
+	if (at.depth >= limits.maxDepth) {
+		stats.depthCapped++;
+		return { $depth: at.depth };
+	}
+	if (state.seen.has(value)) return { $cycle: true };
+	if (Array.isArray(value)) {
+		state.seen.add(value);
+		return walkArray(value, at, limits, stats, state);
+	}
+	if (!isPlainObject(value)) {
+		stats.opaqueObjects++;
+		return { $opaque: className(value) };
+	}
+	state.seen.add(value);
+	const out = {};
+	for (const [key, child] of Object.entries(value)) {
+		if (SUMMARISED_KEYS.has(key)) {
+			out[key] = summarizeData(child);
+			continue;
+		}
+		if (COUNTED_KEYS.has(key)) {
+			out[key] = { $count: countOf(child) };
+			continue;
+		}
+		out[key] = walk(child, {
+			key,
+			schemaSubtree: at.schemaSubtree || SCHEMA_SUBTREE_KEYS.has(key),
+			depth: at.depth + 1
+		}, limits, stats, state);
+	}
+	return out;
+}
+function walkArray(value, at, limits, stats, state) {
+	const kept = value.slice(0, limits.maxArrayItems).map((item) => walk(item, {
+		key: at.key,
+		schemaSubtree: at.schemaSubtree,
+		depth: at.depth + 1
+	}, limits, stats, state));
+	const omitted = value.length - kept.length;
+	if (omitted <= 0) return kept;
+	stats.truncatedArrays++;
+	stats.omittedItems += omitted;
+	return [...kept, { $omitted: omitted }];
+}
+function redactString(value, at, limits, stats) {
+	if (at.schemaSubtree || at.key !== void 0 && SCHEMA_KEYS.has(at.key)) return value.length > limits.maxStringLength ? `${value.slice(0, limits.maxStringLength)}…` : value;
+	stats.hashedStrings++;
+	return hashString(value);
+}
+function countOf(value) {
+	if (Array.isArray(value)) return value.length;
+	if (isPlainObject(value)) return Object.keys(value).length;
+}
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+function className(value) {
+	return value.constructor?.name ?? "unknown";
+}
+//#endregion
+export { redact };
+
+//# sourceMappingURL=redact.js.map

package/dist/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","names":[],"sources":["../src/redact.ts"],"sourcesContent":["import crypto from \"node:crypto\";\nimport { summarizeData, type DataSummary } from \"./data_summary\";\n\n/**\n * Structure-preserving redaction for anything a driver seam is handed.\n *\n * The definition a block model builds is recorded by *shape* rather than by a\n * hand-written digest per definition type. Keys, numbers and the small set of\n * strings that are schema survive verbatim; every other string is replaced by a\n * hash and a length. That keeps the record useful for diagnosis, keeps customer\n * data out of it by default rather than by enumeration, and works unchanged for\n * definition shapes this code has never seen — the V2 query API included.\n *\n * The default for an unrecognised string is to hash it. A new field can\n * therefore make a report less informative, but never make it leak.\n */\n\n/** Keys whose string value is schema, kept as written. */\nconst SCHEMA_KEYS = new Set([\"type\", \"name\", \"valueType\", \"kind\", \"operator\", \"mode\"]);\n\n/** Keys under which every string is schema, at any depth (axis identity). */\nconst SCHEMA_SUBTREE_KEYS = new Set([\"domain\", \"contextDomain\"]);\n\n/** Keys never descended into; summarised by counts instead. */\nconst SUMMARISED_KEYS = new Set([\"data\", \"dataInfo\"]);\n\n/** Keys reduced to a cardinality, because their contents are values. */\nconst COUNTED_KEYS = new Set([\"references\", \"parts\"]);\n\nexport type RedactionStats = {\n  hashedStrings: number;\n  truncatedArrays: number;\n  omittedItems: number;\n  depthCapped: number;\n  opaqueObjects: number;\n  budgetExhausted: boolean;\n};\n\ntype RedactOptions = {\n  maxDepth?: number;\n  maxArrayItems?: number;\n  maxStringLength?: number;\n  /** Ceiling on emitted values, so one pathological definition cannot fill the log. */\n  maxNodes?: number;\n};\n\ntype HashedString = { h: string; n: number };\n\n/** Redacts a definition, returning the new value and what had to be elided. */\nexport function redact(\n  value: unknown,\n  options: RedactOptions = {},\n): { value: unknown; stats: RedactionStats } {\n  const limits = {\n    maxDepth: options.maxDepth ?? 32,\n    maxArrayItems: options.maxArrayItems ?? 64,\n    maxStringLength: options.maxStringLength ?? 128,\n    maxNodes: options.maxNodes ?? 20_000,\n  };\n  const stats: RedactionStats = {\n    hashedStrings: 0,\n    truncatedArrays: 0,\n    omittedItems: 0,\n    depthCapped: 0,\n    opaqueObjects: 0,\n    budgetExhausted: false,\n  };\n  const state = { nodes: 0, seen: new WeakSet<object>() };\n  return {\n    value: walk(value, { key: undefined, schemaSubtree: false, depth: 0 }, limits, stats, state),\n    stats,\n  };\n}\n\n/** Stable short hash plus the original length. Never reversible to the value. */\nfunction hashString(value: string): HashedString {\n  return {\n    h: crypto.createHash(\"sha256\").update(value).digest(\"hex\").slice(0, 12),\n    n: value.length,\n  };\n}\n\n/** True for the object form produced in place of a redacted string. */\nexport function isHashedString(value: unknown): value is HashedString {\n  return typeof value === \"object\" && value !== null && \"h\" in value && \"n\" in value;\n}\n\n// Internals\n\ntype Position = { key: string | undefined; schemaSubtree: boolean; depth: number };\ntype Limits = Required<RedactOptions>;\ntype State = { nodes: number; seen: WeakSet<object> };\n\nfunction walk(\n  value: unknown,\n  at: Position,\n  limits: Limits,\n  stats: RedactionStats,\n  state: State,\n): unknown {\n  if (state.nodes++ > limits.maxNodes) {\n    stats.budgetExhausted = true;\n    return { $budget: true };\n  }\n\n  if (value === null || value === undefined) return value ?? null;\n  if (typeof value === \"bigint\") return Number(value);\n  if (typeof value === \"number\" || typeof value === \"boolean\") return value;\n  if (typeof value === \"string\") return redactString(value, at, limits, stats);\n  if (typeof value !== \"object\") return { $type: typeof value };\n\n  if (at.depth >= limits.maxDepth) {\n    stats.depthCapped++;\n    return { $depth: at.depth };\n  }\n  // A definition can carry live accessors and other class instances whose\n  // internals reference each other; walking those is neither safe nor useful.\n  if (state.seen.has(value)) return { $cycle: true };\n\n  if (Array.isArray(value)) {\n    state.seen.add(value);\n    return walkArray(value, at, limits, stats, state);\n  }\n  if (!isPlainObject(value)) {\n    stats.opaqueObjects++;\n    return { $opaque: className(value) };\n  }\n\n  state.seen.add(value);\n  const out: Record<string, unknown> = {};\n  for (const [key, child] of Object.entries(value)) {\n    if (SUMMARISED_KEYS.has(key)) {\n      out[key] = summarizeData(child);\n      continue;\n    }\n    if (COUNTED_KEYS.has(key)) {\n      out[key] = { $count: countOf(child) };\n      continue;\n    }\n    out[key] = walk(\n      child,\n      {\n        key,\n        schemaSubtree: at.schemaSubtree || SCHEMA_SUBTREE_KEYS.has(key),\n        depth: at.depth + 1,\n      },\n      limits,\n      stats,\n      state,\n    );\n  }\n  return out;\n}\n\nfunction walkArray(\n  value: unknown[],\n  at: Position,\n  limits: Limits,\n  stats: RedactionStats,\n  state: State,\n): unknown[] {\n  const kept = value\n    .slice(0, limits.maxArrayItems)\n    .map((item) =>\n      walk(\n        item,\n        { key: at.key, schemaSubtree: at.schemaSubtree, depth: at.depth + 1 },\n        limits,\n        stats,\n        state,\n      ),\n    );\n  const omitted = value.length - kept.length;\n  if (omitted <= 0) return kept;\n  // Arrays stay arrays so the rules can still walk join entries; the loss is\n  // recorded in the array itself rather than in a side channel.\n  stats.truncatedArrays++;\n  stats.omittedItems += omitted;\n  return [...kept, { $omitted: omitted }];\n}\n\nfunction redactString(\n  value: string,\n  at: Position,\n  limits: Limits,\n  stats: RedactionStats,\n): string | HashedString {\n  if (at.schemaSubtree || (at.key !== undefined && SCHEMA_KEYS.has(at.key))) {\n    return value.length > limits.maxStringLength\n      ? `${value.slice(0, limits.maxStringLength)}…`\n      : value;\n  }\n  stats.hashedStrings++;\n  return hashString(value);\n}\n\nfunction countOf(value: unknown): number | undefined {\n  if (Array.isArray(value)) return value.length;\n  if (isPlainObject(value)) return Object.keys(value).length;\n  return undefined;\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) return false;\n  const proto = Object.getPrototypeOf(value) as object | null;\n  return proto === Object.prototype || proto === null;\n}\n\nfunction className(value: object): string {\n  return (value as { constructor?: { name?: string } }).constructor?.name ?? \"unknown\";\n}\n\nexport type { DataSummary };\n"],"mappings":";;;;;;;;;;;;;;;;;AAkBA,MAAM,8BAAc,IAAI,IAAI;CAAC;CAAQ;CAAQ;CAAa;CAAQ;CAAY;AAAM,CAAC;;AAGrF,MAAM,sCAAsB,IAAI,IAAI,CAAC,UAAU,eAAe,CAAC;;AAG/D,MAAM,kCAAkB,IAAI,IAAI,CAAC,QAAQ,UAAU,CAAC;;AAGpD,MAAM,+BAAe,IAAI,IAAI,CAAC,cAAc,OAAO,CAAC;;AAsBpD,SAAgB,OACd,OACA,UAAyB,CAAC,GACiB;CAC3C,MAAM,SAAS;EACb,UAAU,QAAQ,YAAY;EAC9B,eAAe,QAAQ,iBAAiB;EACxC,iBAAiB,QAAQ,mBAAmB;EAC5C,UAAU,QAAQ,YAAY;CAChC;CACA,MAAM,QAAwB;EAC5B,eAAe;EACf,iBAAiB;EACjB,cAAc;EACd,aAAa;EACb,eAAe;EACf,iBAAiB;CACnB;CAEA,OAAO;EACL,OAAO,KAAK,OAAO;GAAE,KAAK,KAAA;GAAW,eAAe;GAAO,OAAO;EAAE,GAAG,QAAQ,OAAO;GAFxE,OAAO;GAAG,sBAAM,IAAI,QAAgB;EAEwC,CAAC;EAC3F;CACF;AACF;;AAGA,SAAS,WAAW,OAA6B;CAC/C,OAAO;EACL,GAAG,OAAO,WAAW,QAAQ,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,GAAG,EAAE;EACtE,GAAG,MAAM;CACX;AACF;AAaA,SAAS,KACP,OACA,IACA,QACA,OACA,OACS;CACT,IAAI,MAAM,UAAU,OAAO,UAAU;EACnC,MAAM,kBAAkB;EACxB,OAAO,EAAE,SAAS,KAAK;CACzB;CAEA,IAAI,UAAU,QAAQ,UAAU,KAAA,GAAW,OAAO,SAAS;CAC3D,IAAI,OAAO,UAAU,UAAU,OAAO,OAAO,KAAK;CAClD,IAAI,OAAO,UAAU,YAAY,OAAO,UAAU,WAAW,OAAO;CACpE,IAAI,OAAO,UAAU,UAAU,OAAO,aAAa,OAAO,IAAI,QAAQ,KAAK;CAC3E,IAAI,OAAO,UAAU,UAAU,OAAO,EAAE,OAAO,OAAO,MAAM;CAE5D,IAAI,GAAG,SAAS,OAAO,UAAU;EAC/B,MAAM;EACN,OAAO,EAAE,QAAQ,GAAG,MAAM;CAC5B;CAGA,IAAI,MAAM,KAAK,IAAI,KAAK,GAAG,OAAO,EAAE,QAAQ,KAAK;CAEjD,IAAI,MAAM,QAAQ,KAAK,GAAG;EACxB,MAAM,KAAK,IAAI,KAAK;EACpB,OAAO,UAAU,OAAO,IAAI,QAAQ,OAAO,KAAK;CAClD;CACA,IAAI,CAAC,cAAc,KAAK,GAAG;EACzB,MAAM;EACN,OAAO,EAAE,SAAS,UAAU,KAAK,EAAE;CACrC;CAEA,MAAM,KAAK,IAAI,KAAK;CACpB,MAAM,MAA+B,CAAC;CACtC,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,KAAK,GAAG;EAChD,IAAI,gBAAgB,IAAI,GAAG,GAAG;GAC5B,IAAI,OAAO,cAAc,KAAK;GAC9B;EACF;EACA,IAAI,aAAa,IAAI,GAAG,GAAG;GACzB,IAAI,OAAO,EAAE,QAAQ,QAAQ,KAAK,EAAE;GACpC;EACF;EACA,IAAI,OAAO,KACT,OACA;GACE;GACA,eAAe,GAAG,iBAAiB,oBAAoB,IAAI,GAAG;GAC9D,OAAO,GAAG,QAAQ;EACpB,GACA,QACA,OACA,KACF;CACF;CACA,OAAO;AACT;AAEA,SAAS,UACP,OACA,IACA,QACA,OACA,OACW;CACX,MAAM,OAAO,MACV,MAAM,GAAG,OAAO,aAAa,CAAC,CAC9B,KAAK,SACJ,KACE,MACA;EAAE,KAAK,GAAG;EAAK,eAAe,GAAG;EAAe,OAAO,GAAG,QAAQ;CAAE,GACpE,QACA,OACA,KACF,CACF;CACF,MAAM,UAAU,MAAM,SAAS,KAAK;CACpC,IAAI,WAAW,GAAG,OAAO;CAGzB,MAAM;CACN,MAAM,gBAAgB;CACtB,OAAO,CAAC,GAAG,MAAM,EAAE,UAAU,QAAQ,CAAC;AACxC;AAEA,SAAS,aACP,OACA,IACA,QACA,OACuB;CACvB,IAAI,GAAG,iBAAkB,GAAG,QAAQ,KAAA,KAAa,YAAY,IAAI,GAAG,GAAG,GACrE,OAAO,MAAM,SAAS,OAAO,kBACzB,GAAG,MAAM,MAAM,GAAG,OAAO,eAAe,EAAE,KAC1C;CAEN,MAAM;CACN,OAAO,WAAW,KAAK;AACzB;AAEA,SAAS,QAAQ,OAAoC;CACnD,IAAI,MAAM,QAAQ,KAAK,GAAG,OAAO,MAAM;CACvC,IAAI,cAAc,KAAK,GAAG,OAAO,OAAO,KAAK,KAAK,CAAC,CAAC;AAEtD;AAEA,SAAS,cAAc,OAAkD;CACvE,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,KAAK,GAAG,OAAO;CAChF,MAAM,QAAQ,OAAO,eAAe,KAAK;CACzC,OAAO,UAAU,OAAO,aAAa,UAAU;AACjD;AAEA,SAAS,UAAU,OAAuB;CACxC,OAAQ,MAA8C,aAAa,QAAQ;AAC7E"}

package/dist/sampler.d.ts

@@ -0,0 +1,8 @@
+//#region src/sampler.d.ts
+export type MemorySampler = {
+  /** Sibling log the sampler appends to. */
+  readonly file: string;
+  stop(): void;
+};
+//#endregion
+//# sourceMappingURL=sampler.d.ts.map

package/dist/sampler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler.d.ts","names":[],"sources":["../src/sampler.ts"],"mappings":";YAWY;;WAED;EACT"}

package/dist/sampler.js

@@ -0,0 +1,33 @@
+import { SAMPLER_FILE_PREFIX } from "./events.js";
+import path from "node:path";
+import { Worker } from "node:worker_threads";
+//#region src/sampler.ts
+/**
+* Starts the out-of-band memory sampler for a session.
+*
+* The sampler runs on a thread of its own with a small heap of its own, so it
+* keeps producing readings when the observed thread is blocked and when the
+* observed thread's heap is the thing that is full.
+*/
+function startMemorySampler(options) {
+	const { dir, sessionId, intervalMs = 250 } = options;
+	const file = path.join(dir, `${SAMPLER_FILE_PREFIX}-${sessionId}.ndjson`);
+	const worker = new Worker(new URL("./sampler_thread.js", import.meta.url), {
+		workerData: {
+			file,
+			intervalMs
+		},
+		resourceLimits: { maxOldGenerationSizeMb: 32 }
+	});
+	worker.unref();
+	return {
+		file,
+		stop: () => {
+			worker.terminate();
+		}
+	};
+}
+//#endregion
+export { startMemorySampler };
+
+//# sourceMappingURL=sampler.js.map

package/dist/sampler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler.js","names":[],"sources":["../src/sampler.ts"],"sourcesContent":["import path from \"node:path\";\nimport { Worker } from \"node:worker_threads\";\nimport { SAMPLER_FILE_PREFIX } from \"./events\";\n\ntype MemorySamplerOptions = {\n  dir: string;\n  sessionId: string;\n  /** Sampling period; 250 ms is roughly four short appends per second. */\n  intervalMs?: number;\n};\n\nexport type MemorySampler = {\n  /** Sibling log the sampler appends to. */\n  readonly file: string;\n  stop(): void;\n};\n\n/**\n * Starts the out-of-band memory sampler for a session.\n *\n * The sampler runs on a thread of its own with a small heap of its own, so it\n * keeps producing readings when the observed thread is blocked and when the\n * observed thread's heap is the thing that is full.\n */\nexport function startMemorySampler(options: MemorySamplerOptions): MemorySampler {\n  const { dir, sessionId, intervalMs = 250 } = options;\n  const file = path.join(dir, `${SAMPLER_FILE_PREFIX}-${sessionId}.ndjson`);\n  const worker = new Worker(new URL(\"./sampler_thread.js\", import.meta.url), {\n    workerData: { file, intervalMs },\n    resourceLimits: { maxOldGenerationSizeMb: 32 },\n  });\n  // Unreferenced so a sampler that is never stopped cannot hold the process open.\n  worker.unref();\n  return {\n    file,\n    stop: () => {\n      void worker.terminate();\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;AAwBA,SAAgB,mBAAmB,SAA8C;CAC/E,MAAM,EAAE,KAAK,WAAW,aAAa,QAAQ;CAC7C,MAAM,OAAO,KAAK,KAAK,KAAK,GAAG,oBAAoB,GAAG,UAAU,QAAQ;CACxE,MAAM,SAAS,IAAI,OAAO,IAAI,IAAI,uBAAuB,OAAO,KAAK,GAAG,GAAG;EACzE,YAAY;GAAE;GAAM;EAAW;EAC/B,gBAAgB,EAAE,wBAAwB,GAAG;CAC/C,CAAC;CAED,OAAO,MAAM;CACb,OAAO;EACL;EACA,YAAY;GACV,OAAY,UAAU;EACxB;CACF;AACF"}

package/dist/sampler_thread.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/sampler_thread.js

@@ -0,0 +1,53 @@
+import { readMachineMemory } from "./machine_memory.js";
+import fs from "node:fs";
+import os from "node:os";
+import { workerData } from "node:worker_threads";
+//#region src/sampler_thread.ts
+/**
+* Memory sampler, run on its own worker thread.
+*
+* It exists because the thread worth watching is the one that blocks. While the
+* middle layer sits inside a synchronous pframes call its own timers do not
+* fire, so its memory series goes dark exactly while memory is growing fastest.
+* This thread stays responsive and keeps the resident-size curve intact right up
+* to the moment the process dies.
+*
+* `rss` and `freeMemory` are process- and machine-wide and so are meaningful
+* from here. Heap figures are per-isolate and would describe only this thread,
+* so they are deliberately not recorded; the observed thread reports its own.
+*
+* Resident size alone understates a process under pressure, because the OS moves
+* its pages into the compressor or out to swap and they stop being resident. The
+* machine's own account of where memory went is therefore sampled alongside it,
+* less often because it costs a subprocess.
+*/
+const { file, intervalMs, machineIntervalMs = 1e3 } = workerData;
+const fd = fs.openSync(file, "a");
+let seq = 0;
+let peakRss = 0;
+let machineDueAt = 0;
+setInterval(() => {
+	const rss = process.memoryUsage.rss();
+	if (rss > peakRss) peakRss = rss;
+	const now = Date.now();
+	const machine = now >= machineDueAt ? readMachineMemory() : void 0;
+	if (machine) machineDueAt = now + machineIntervalMs;
+	const record = {
+		seq: ++seq,
+		t: Math.round(performance.now() * 1e3) / 1e3,
+		wall: now,
+		type: "mem-sampler",
+		rss,
+		peakRss,
+		maxRss: process.resourceUsage().maxRSS * 1024,
+		freeMemory: os.freemem(),
+		totalMemory: os.totalmem(),
+		...machine ? { machine } : {}
+	};
+	try {
+		fs.writeSync(fd, `${JSON.stringify(record)}\n`);
+	} catch {}
+}, intervalMs);
+//#endregion
+
+//# sourceMappingURL=sampler_thread.js.map

package/dist/sampler_thread.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler_thread.js","names":[],"sources":["../src/sampler_thread.ts"],"sourcesContent":["/**\n * Memory sampler, run on its own worker thread.\n *\n * It exists because the thread worth watching is the one that blocks. While the\n * middle layer sits inside a synchronous pframes call its own timers do not\n * fire, so its memory series goes dark exactly while memory is growing fastest.\n * This thread stays responsive and keeps the resident-size curve intact right up\n * to the moment the process dies.\n *\n * `rss` and `freeMemory` are process- and machine-wide and so are meaningful\n * from here. Heap figures are per-isolate and would describe only this thread,\n * so they are deliberately not recorded; the observed thread reports its own.\n *\n * Resident size alone understates a process under pressure, because the OS moves\n * its pages into the compressor or out to swap and they stop being resident. The\n * machine's own account of where memory went is therefore sampled alongside it,\n * less often because it costs a subprocess.\n */\n\nimport fs from \"node:fs\";\nimport os from \"node:os\";\nimport { workerData } from \"node:worker_threads\";\nimport type { SamplerRecord } from \"./events\";\nimport { readMachineMemory } from \"./machine_memory\";\n\ntype SamplerWorkerData = { file: string; intervalMs: number; machineIntervalMs?: number };\n\nconst { file, intervalMs, machineIntervalMs = 1000 } = workerData as SamplerWorkerData;\nconst fd = fs.openSync(file, \"a\");\nlet seq = 0;\nlet peakRss = 0;\nlet machineDueAt = 0;\n\nsetInterval(() => {\n  const rss = process.memoryUsage.rss();\n  if (rss > peakRss) peakRss = rss;\n  const now = Date.now();\n  // Taken on the first tick and then on its own schedule, so the curve keeps its\n  // sampling rate while the costlier reading stays occasional.\n  const machine = now >= machineDueAt ? readMachineMemory() : undefined;\n  if (machine) machineDueAt = now + machineIntervalMs;\n  const record: SamplerRecord = {\n    seq: ++seq,\n    t: Math.round(performance.now() * 1000) / 1000,\n    wall: now,\n    type: \"mem-sampler\",\n    rss,\n    peakRss,\n    // The kernel's own high-water mark, which no sampling interval can miss.\n    maxRss: process.resourceUsage().maxRSS * 1024,\n    freeMemory: os.freemem(),\n    totalMemory: os.totalmem(),\n    ...(machine ? { machine } : {}),\n  };\n  try {\n    fs.writeSync(fd, `${JSON.stringify(record)}\\n`);\n  } catch {\n    // Sampling must never take the application down.\n  }\n}, intervalMs);\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AA2BA,MAAM,EAAE,MAAM,YAAY,oBAAoB,QAAS;AACvD,MAAM,KAAK,GAAG,SAAS,MAAM,GAAG;AAChC,IAAI,MAAM;AACV,IAAI,UAAU;AACd,IAAI,eAAe;AAEnB,kBAAkB;CAChB,MAAM,MAAM,QAAQ,YAAY,IAAI;CACpC,IAAI,MAAM,SAAS,UAAU;CAC7B,MAAM,MAAM,KAAK,IAAI;CAGrB,MAAM,UAAU,OAAO,eAAe,kBAAkB,IAAI,KAAA;CAC5D,IAAI,SAAS,eAAe,MAAM;CAClC,MAAM,SAAwB;EAC5B,KAAK,EAAE;EACP,GAAG,KAAK,MAAM,YAAY,IAAI,IAAI,GAAI,IAAI;EAC1C,MAAM;EACN,MAAM;EACN;EACA;EAEA,QAAQ,QAAQ,cAAc,CAAC,CAAC,SAAS;EACzC,YAAY,GAAG,QAAQ;EACvB,aAAa,GAAG,SAAS;EACzB,GAAI,UAAU,EAAE,QAAQ,IAAI,CAAC;CAC/B;CACA,IAAI;EACF,GAAG,UAAU,IAAI,GAAG,KAAK,UAAU,MAAM,EAAE,GAAG;CAChD,QAAQ,CAER;AACF,GAAG,UAAU"}

package/dist/session.d.ts

@@ -0,0 +1,40 @@
+import { Recorder } from "./recorder.js";
+import { MemorySampler } from "./sampler.js";
+import { HandleRegistry } from "./instrument.js";
+//#region src/session.d.ts
+/** Environment variable naming the directory crash logs are written to. */
+export declare const CRASH_DIR_ENV = "MI_CRASH_RECORDER_DIR";
+/**
+ * Environment variable carrying the session id a supervising parent assigned.
+ * Set it alongside {@link CRASH_DIR_ENV} when spawning the worker and pass the
+ * same id to `superviseWorker`.
+ */
+export declare const CRASH_SESSION_ENV = "MI_CRASH_RECORDER_SESSION";
+export type RecordingSessionOptions = {
+  /** Overrides the directory from the environment. */
+  dir?: string;
+  /** Overrides the session id from the environment. */
+  sessionId?: string;
+  role?: string;
+  meta?: Record<string, unknown>;
+  samplerIntervalMs?: number;
+  selfSamplerIntervalMs?: number;
+};
+export type RecordingSession = {
+  readonly recorder: Recorder;
+  readonly sampler: MemorySampler;
+  /** Shared so create calls and later data calls agree on handle identity. */
+  readonly registry: HandleRegistry;
+  close(reason?: string): void;
+};
+/**
+ * Opens a recording session, or returns undefined when recording is not enabled.
+ *
+ * Recording is opt-in for now: it appends synchronously on every recorded
+ * operation, and that cost has not been measured against a real project, so it
+ * is switched on by pointing {@link CRASH_DIR_ENV} at a directory rather than
+ * being on by default.
+ */
+export declare function openRecordingSession(options?: RecordingSessionOptions): RecordingSession | undefined;
+//#endregion
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","names":[],"sources":["../src/session.ts"],"mappings":";;;;;qBAKa;;;;;;qBAOA;YAED;;EAEV;;EAEA;EACA;EACA,OAAO;EACP;EACA;;YAGU;WACD,UAAU;WACV,SAAS;;WAET,UAAU;EACnB,MAAM;;;;;;;;;;wBAWQ,qBACd,UAAS,0BACR"}