@milaboratories/pl-flight-recorder 0.2.0

package/src/rules.ts

@@ -0,0 +1,383 @@
+import type {
+  JoinEntry,
+  SpecQueryLinkerJoin,
+  SpecQueryOuterJoin,
+  SpecQuerySymmetricJoin,
+} from "@milaboratories/pl-model-common";
+import type { DataSummary } from "./data_summary";
+
+/**
+ * Structural faults in a join, read from the recorded shape of its definition.
+ *
+ * Two faults make a join's output size unbounded and both are visible before any
+ * data is touched: siblings that share no axis at all, which is a cartesian
+ * product, and siblings whose axes agree on name and type but disagree on
+ * domain, where the join key silently fails to match.
+ *
+ * These run in the analyzer rather than at record time. Nothing is computed on
+ * the hot path, the thresholds and the rules can be revised against logs that
+ * already exist, and one implementation covers every definition shape: the join
+ * nodes are recognised by their discriminator and their children by position, so
+ * both the original tree API and the V2 query API are read by the same walk.
+ */
+
+export type FindingSeverity = "critical" | "high" | "medium" | "low";
+
+export type StructuralFinding = {
+  rule: "cross-join" | "axis-domain-mismatch" | "partial-key-fan-out";
+  severity: FindingSeverity;
+  /** Position in the definition, e.g. `root/innerJoin[1]`. */
+  path: string;
+  join: string;
+  detail: string;
+  rowsUpperBound?: number;
+  domains?: { domain: string; children: number[] }[];
+  missing?: { index: number; missing: string[] }[];
+};
+
+export type AxisDescriptor = {
+  name: string;
+  type: string;
+  domain?: Record<string, string>;
+};
+
+export type JoinShape = {
+  join: string;
+  path: string;
+  childCount: number;
+  axisUnion: string[];
+  sharedAxes: string[];
+  disjointPairs: [number, number][];
+  inputRowsMax?: number;
+  /** Loose but true: no join of these inputs can exceed the product of their rows. */
+  rowsUpperBound?: number;
+};
+
+// The discriminators are pinned to the model's own literal types, so renaming a
+// join kind in pl-model-common fails this build instead of silently disabling a
+// rule. The model exports the names only as types, never as runtime constants.
+type TreeJoinType = Extract<
+  JoinEntry<unknown>,
+  { entries: unknown } | { primary: unknown }
+>["type"];
+type QueryJoinType = (SpecQuerySymmetricJoin | SpecQueryOuterJoin | SpecQueryLinkerJoin)["type"];
+
+/** Joins that keep only keys present in every entry; an entry missing part of the key fans out. */
+const INTERSECT_JOINS: ReadonlySet<string> = new Set(["inner", "innerJoin"] satisfies (
+  | TreeJoinType
+  | QueryJoinType
+)[]);
+/** Joins that keep keys present in any entry, filling the rest with nulls. */
+const UNION_JOINS: ReadonlySet<string> = new Set(["full", "fullJoin"] satisfies (
+  | TreeJoinType
+  | QueryJoinType
+)[]);
+/** Joins driven by one side: the primary or linker decides which keys exist. */
+const DRIVEN_JOINS: ReadonlySet<string> = new Set(["outer", "outerJoin", "linkerJoin"] satisfies (
+  | TreeJoinType
+  | QueryJoinType
+)[]);
+
+/** Structural findings for a recorded definition, most specific first. */
+export function structuralFindings(def: unknown): StructuralFinding[] {
+  const findings: StructuralFinding[] = [];
+  visit(def, "root", (node, path) => collect(node, path, findings));
+  return findings;
+}
+
+/** Shape of every join node in a definition, outermost first. */
+export function joinShapes(def: unknown): JoinShape[] {
+  const shapes: JoinShape[] = [];
+  visit(def, "root", (node, path) => shapes.push(shapeOf(node, path)));
+  return shapes;
+}
+
+/**
+ * Largest input row count the definition declares, used to judge how much a
+ * join amplified. Unknown when no workflow recorded chunk statistics.
+ */
+export function inputRowsMax(def: unknown): number | undefined {
+  const rows = childRowCounts(def);
+  return rows.length > 0 ? Math.max(...rows) : estimateRows(def);
+}
+
+/** Canonical axis identity, matching how join keys are formed. */
+export function axisKey(axis: AxisDescriptor): string {
+  return `${axis.type}|${axis.name}|${canonicalDomain(axis.domain)}`;
+}
+
+/** Axis identity ignoring domain, used to spot near-miss axes that fail to join. */
+export function axisNameKey(axis: AxisDescriptor): string {
+  return `${axis.type}|${axis.name}`;
+}
+
+/** True when a node is a join, by its discriminator. */
+export function isJoinNode(node: unknown): boolean {
+  const type = discriminator(node);
+  return (
+    type !== undefined &&
+    (INTERSECT_JOINS.has(type) || UNION_JOINS.has(type) || DRIVEN_JOINS.has(type))
+  );
+}
+
+/**
+ * A join's children, by position. The V2 API wraps each child in `{ entry }`;
+ * that wrapper is left in place because every read here descends through it.
+ */
+export function joinChildren(node: unknown): unknown[] {
+  const record = asRecord(node);
+  if (!record) return [];
+  if (Array.isArray(record.entries)) return record.entries;
+  const driven = [record.primary ?? record.linker, ...toArray(record.secondary)];
+  return driven.filter((child) => child !== undefined && child !== null);
+}
+
+/** Axis descriptors anywhere beneath a node, deduplicated by identity. */
+export function axesUnder(node: unknown): AxisDescriptor[] {
+  const out = new Map<string, AxisDescriptor>();
+  gatherAxes(node, out, 0);
+  return [...out.values()];
+}
+
+// Internals
+
+const MAX_WALK_DEPTH = 40;
+
+function visit(
+  node: unknown,
+  path: string,
+  onJoin: (node: unknown, path: string) => void,
+  depth = 0,
+): void {
+  if (depth > MAX_WALK_DEPTH || !isTraversable(node)) return;
+  if (isJoinNode(node)) {
+    onJoin(node, path);
+    const join = discriminator(node) ?? "join";
+    for (const [index, child] of joinChildren(node).entries()) {
+      visit(child, `${path}/${join}[${index}]`, onJoin, depth + 1);
+    }
+    return;
+  }
+  for (const child of childValues(node)) visit(child, path, onJoin, depth + 1);
+}
+
+function shapeOf(node: unknown, path: string): JoinShape {
+  const join = discriminator(node) ?? "join";
+  const children = joinChildren(node);
+  const keySets = children.map((child) => new Set(axesUnder(child).map(axisKey)));
+
+  const union = new Set<string>();
+  for (const set of keySets) for (const key of set) union.add(key);
+
+  const disjointPairs: [number, number][] = [];
+  for (let i = 0; i < keySets.length; i++) {
+    for (let j = i + 1; j < keySets.length; j++) {
+      if (keySets[i].size === 0 || keySets[j].size === 0) continue;
+      if ([...keySets[i]].some((key) => keySets[j].has(key))) continue;
+      disjointPairs.push([i, j]);
+    }
+  }
+
+  const rows = children.map(estimateRows);
+  const known = rows.filter((value): value is number => typeof value === "number");
+  return {
+    join,
+    path,
+    childCount: children.length,
+    axisUnion: [...union],
+    sharedAxes: [...union].filter((key) => keySets.every((set) => set.has(key))),
+    disjointPairs,
+    inputRowsMax: known.length > 0 ? Math.max(...known) : undefined,
+    rowsUpperBound: known.length === rows.length && known.length > 0 ? product(known) : undefined,
+  };
+}
+
+function collect(node: unknown, path: string, findings: StructuralFinding[]): void {
+  const shape = shapeOf(node, path);
+  const children = joinChildren(node);
+
+  if (shape.disjointPairs.length > 0) {
+    findings.push({
+      rule: "cross-join",
+      severity: "critical",
+      path,
+      join: shape.join,
+      detail: `join siblings share no axis: pairs ${JSON.stringify(shape.disjointPairs)}`,
+      rowsUpperBound: shape.rowsUpperBound,
+    });
+  }
+
+  for (const nearMiss of nearMissAxes(children)) {
+    findings.push({
+      rule: "axis-domain-mismatch",
+      severity: "high",
+      path,
+      join: shape.join,
+      detail: `axis ${nearMiss.axis} appears with ${nearMiss.domains.length} different domains`,
+      domains: nearMiss.domains,
+    });
+  }
+
+  // Fan-out is worth reporting only where the node still has a working join key
+  // and its entries are peers; on a cartesian node it restates the cross-join,
+  // and on a driven join a narrower secondary is the intended behaviour.
+  if (!INTERSECT_JOINS.has(shape.join) || shape.disjointPairs.length > 0) return;
+  const missing = children
+    .map((child, index) => {
+      const own = new Set(axesUnder(child).map(axisKey));
+      return { index, missing: shape.axisUnion.filter((key) => !own.has(key)) };
+    })
+    .filter((entry) => entry.missing.length > 0);
+  if (missing.length === 0) return;
+  findings.push({
+    rule: "partial-key-fan-out",
+    severity: "medium",
+    path,
+    join: shape.join,
+    detail: `${missing.length} sibling(s) lack part of the node's axis union and get replicated`,
+    missing,
+  });
+}
+
+// Axes agreeing on name and type but disagreeing on domain never match as a
+// join key, which turns an intended join into a product or an empty result.
+function nearMissAxes(
+  children: unknown[],
+): { axis: string; domains: { domain: string; children: number[] }[] }[] {
+  const byName = new Map<string, Map<string, Set<number>>>();
+  for (const [index, child] of children.entries()) {
+    for (const axis of axesUnder(child)) {
+      const nameKey = axisNameKey(axis);
+      let perDomain = byName.get(nameKey);
+      if (!perDomain) byName.set(nameKey, (perDomain = new Map()));
+      const domainKey = canonicalDomain(axis.domain);
+      let indices = perDomain.get(domainKey);
+      if (!indices) perDomain.set(domainKey, (indices = new Set()));
+      indices.add(index);
+    }
+  }
+  const out: { axis: string; domains: { domain: string; children: number[] }[] }[] = [];
+  for (const [axis, perDomain] of byName) {
+    if (perDomain.size < 2) continue;
+    out.push({
+      axis,
+      domains: [...perDomain.entries()].map(([domain, indices]) => ({
+        domain: domain || "(none)",
+        children: [...indices],
+      })),
+    });
+  }
+  return out;
+}
+
+function estimateRows(node: unknown, depth = 0): number | undefined {
+  if (depth > MAX_WALK_DEPTH || !isTraversable(node)) return undefined;
+  if (isJoinNode(node)) {
+    const join = discriminator(node) ?? "";
+    const rows = joinChildren(node)
+      .map((child) => estimateRows(child, depth + 1))
+      .filter((value): value is number => typeof value === "number");
+    if (rows.length === 0) return undefined;
+    // An intersection cannot exceed its largest input; a union adds up.
+    return INTERSECT_JOINS.has(join) ? Math.max(...rows) : sum(rows);
+  }
+  const own = ownRows(node);
+  if (own !== undefined) return own;
+  const rows = childValues(node)
+    .map((child) => estimateRows(child, depth + 1))
+    .filter((value): value is number => typeof value === "number");
+  return rows.length > 0 ? Math.max(...rows) : undefined;
+}
+
+function childRowCounts(def: unknown): number[] {
+  const shapes = joinShapes(def);
+  return shapes
+    .map((shape) => shape.inputRowsMax)
+    .filter((value): value is number => typeof value === "number");
+}
+
+function ownRows(node: unknown): number | undefined {
+  const record = asRecord(node);
+  if (!record) return undefined;
+  for (const key of ["data", "dataInfo"]) {
+    const summary = record[key] as DataSummary | undefined;
+    if (!summary || typeof summary !== "object") continue;
+    if (typeof summary.rows === "number") return summary.rows;
+    if (typeof summary.entries === "number") return summary.entries;
+  }
+  return undefined;
+}
+
+function gatherAxes(node: unknown, out: Map<string, AxisDescriptor>, depth: number): void {
+  if (depth > MAX_WALK_DEPTH || !isTraversable(node)) return;
+  const record = asRecord(node);
+  if (record) {
+    for (const key of ["axesSpec", "axes"]) {
+      const value = record[key];
+      if (!Array.isArray(value)) continue;
+      for (const item of value) {
+        const axis = asAxis(item);
+        if (axis) out.set(axisKey(axis), axis);
+      }
+    }
+  }
+  for (const child of childValues(node)) gatherAxes(child, out, depth + 1);
+}
+
+function asAxis(value: unknown): AxisDescriptor | undefined {
+  const record = asRecord(value);
+  if (!record) return undefined;
+  const { name, type, domain } = record;
+  if (typeof name !== "string" || typeof type !== "string") return undefined;
+  return { name, type, domain: plainStringMap(domain) };
+}
+
+function plainStringMap(value: unknown): Record<string, string> | undefined {
+  const record = asRecord(value);
+  if (!record) return undefined;
+  const out: Record<string, string> = {};
+  for (const [key, item] of Object.entries(record)) {
+    if (typeof item === "string") out[key] = item;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+function canonicalDomain(domain: Record<string, string> | undefined): string {
+  return Object.entries(domain ?? {})
+    .sort(([lhs], [rhs]) => (lhs < rhs ? -1 : 1))
+    .map(([key, value]) => `${key}=${value}`)
+    .join(",");
+}
+
+function discriminator(node: unknown): string | undefined {
+  const type = asRecord(node)?.type;
+  return typeof type === "string" ? type : undefined;
+}
+
+function childValues(node: unknown): unknown[] {
+  if (Array.isArray(node)) return node;
+  const record = asRecord(node);
+  return record ? Object.values(record) : [];
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function isTraversable(value: unknown): boolean {
+  return typeof value === "object" && value !== null;
+}
+
+function toArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : value === undefined || value === null ? [] : [value];
+}
+
+function sum(values: number[]): number {
+  return values.reduce((acc, value) => acc + value, 0);
+}
+
+function product(values: number[]): number {
+  return values.reduce((acc, value) => acc * value, 1);
+}

package/src/sampler.ts

@@ -0,0 +1,40 @@
+import path from "node:path";
+import { Worker } from "node:worker_threads";
+import { SAMPLER_FILE_PREFIX } from "./events";
+
+export type MemorySamplerOptions = {
+  dir: string;
+  sessionId: string;
+  /** Sampling period; 250 ms is roughly four short appends per second. */
+  intervalMs?: number;
+};
+
+export type MemorySampler = {
+  /** Sibling log the sampler appends to. */
+  readonly file: string;
+  stop(): void;
+};
+
+/**
+ * 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.
+ */
+export function startMemorySampler(options: MemorySamplerOptions): MemorySampler {
+  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 },
+  });
+  // Unreferenced so a sampler that is never stopped cannot hold the process open.
+  worker.unref();
+  return {
+    file,
+    stop: () => {
+      void worker.terminate();
+    },
+  };
+}

package/src/sampler_thread.ts

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import { workerData } from "node:worker_threads";
+import type { SamplerRecord } from "./events";
+
+type SamplerWorkerData = { file: string; intervalMs: number };
+
+const { file, intervalMs } = workerData as SamplerWorkerData;
+const fd = fs.openSync(file, "a");
+let seq = 0;
+let peakRss = 0;
+
+setInterval(() => {
+  const rss = process.memoryUsage.rss();
+  if (rss > peakRss) peakRss = rss;
+  const record: SamplerRecord = {
+    seq: ++seq,
+    t: Math.round(performance.now() * 1000) / 1000,
+    wall: Date.now(),
+    type: "mem-sampler",
+    rss,
+    peakRss,
+    freeMemory: os.freemem(),
+    totalMemory: os.totalmem(),
+  };
+  try {
+    fs.writeSync(fd, `${JSON.stringify(record)}\n`);
+  } catch {
+    // Sampling must never take the application down.
+  }
+}, intervalMs);

package/src/session.ts

@@ -0,0 +1,69 @@
+import { openRecorder, startSelfSampler, type Recorder } from "./recorder";
+import { startMemorySampler, type MemorySampler } from "./sampler";
+import { createHandleRegistry, type HandleRegistry } from "./instrument";
+
+/** Environment variable naming the directory flight logs are written to. */
+export const FLIGHT_DIR_ENV = "MI_FLIGHT_RECORDER_DIR";
+
+/**
+ * Environment variable carrying the session id a supervising parent assigned.
+ * Set it alongside {@link FLIGHT_DIR_ENV} when spawning the worker and pass the
+ * same id to `superviseWorker`.
+ */
+export const FLIGHT_SESSION_ENV = "MI_FLIGHT_RECORDER_SESSION";
+
+export type FlightSessionOptions = {
+  /** 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 FlightSession = {
+  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 flight 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 FLIGHT_DIR_ENV} at a directory rather than
+ * being on by default.
+ */
+export function openFlightSession(options: FlightSessionOptions = {}): FlightSession | undefined {
+  const dir = options.dir ?? process.env[FLIGHT_DIR_ENV];
+  if (!dir) return undefined;
+
+  const recorder = openRecorder({
+    dir,
+    role: options.role,
+    meta: options.meta,
+    sessionId: options.sessionId ?? process.env[FLIGHT_SESSION_ENV] ?? undefined,
+  });
+  const sampler = startMemorySampler({
+    dir,
+    sessionId: recorder.sessionId,
+    intervalMs: options.samplerIntervalMs,
+  });
+  const stopSelfSampler = startSelfSampler(recorder, options.selfSamplerIntervalMs);
+
+  return {
+    recorder,
+    sampler,
+    registry: createHandleRegistry(),
+    close(reason) {
+      stopSelfSampler();
+      sampler.stop();
+      recorder.close(reason);
+    },
+  };
+}

package/src/supervisor.ts

@@ -0,0 +1,150 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CRASH_FILE_PREFIX, type CrashMarker, type CrashReason } from "./events";
+import { listSessions, sessionIdFromFile } from "./recorder";
+
+export type CrashMarkerInput = {
+  /** Session id the parent assigned to the worker. Omitted, the marker carries no identity. */
+  sessionId?: string;
+  reason?: CrashReason;
+  error?: (Error & { code?: string }) | unknown;
+  code?: number;
+  signal?: string;
+  stderrTail?: string;
+};
+
+export type SuperviseOptions = {
+  /**
+   * The session id handed to the worker at spawn (see `FLIGHT_SESSION_ENV`).
+   * With it the marker names the dying session with certainty. Without it the
+   * analyzer has to attribute the marker by timing, and will decline to
+   * attribute it at all when more than one session looks dead.
+   */
+  sessionId?: string;
+  onCrash?: (info: {
+    kind: "error" | "exit";
+    markerFile: string;
+    error?: unknown;
+    code?: number;
+  }) => void;
+};
+
+/** Minimal view of a worker, so callers are not forced to import worker_threads. */
+export type SupervisedWorker = {
+  on(event: "error", listener: (error: Error) => void): unknown;
+  on(event: "exit", listener: (code: number) => void): unknown;
+};
+
+/**
+ * Records an abnormal end observed from outside the dying thread.
+ *
+ * A thread that runs out of heap cannot describe its own death: the last reading
+ * it wrote predates the blow-up, and when the blow-up is synchronous no sampler
+ * tick of its own lands either. The parent is the only place where the cause is
+ * known rather than inferred — Node reports `ERR_WORKER_OUT_OF_MEMORY` to it —
+ * so the parent writes the verdict down on the dead thread's behalf.
+ */
+export function writeCrashMarker(dir: string, input: CrashMarkerInput = {}): string {
+  fs.mkdirSync(dir, { recursive: true });
+  const error = input.error as (Error & { code?: string }) | undefined;
+  // Only an id the parent handed to the worker is certain, and only a certain
+  // id goes in `sessionId`. Reading the newest open flight log names whichever
+  // session wrote last, which a concurrent live session makes wrong; recorded
+  // as identity that would misattribute the death and, worse, stop the session
+  // that actually died from claiming the marker. So it is advisory only.
+  const marker: CrashMarker = {
+    type: "external-crash",
+    wall: Date.now(),
+    sessionId: input.sessionId,
+    guessedSessionId: input.sessionId === undefined ? newestOpenSessionId(dir) : undefined,
+    reason: input.reason ?? classifyReason(input),
+    errorCode: error?.code,
+    errorName: error?.name,
+    message: truncate(String(error?.message ?? input.error ?? ""), 2000),
+    exitCode: input.code,
+    signal: input.signal,
+    stderrTail: truncate(input.stderrTail ?? "", 4000),
+  };
+  const file = path.join(dir, `${CRASH_FILE_PREFIX}-${marker.wall}.ndjson`);
+  fs.writeFileSync(file, `${JSON.stringify(marker)}\n`);
+  return file;
+}
+
+/** Crash markers in a directory, oldest first. */
+export function readCrashMarkers(dir: string): CrashMarker[] {
+  let names: string[];
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const markers: CrashMarker[] = [];
+  for (const name of names) {
+    if (!name.startsWith(`${CRASH_FILE_PREFIX}-`) || !name.endsWith(".ndjson")) continue;
+    try {
+      const first = fs.readFileSync(path.join(dir, name), "utf8").split("\n")[0];
+      markers.push(JSON.parse(first) as CrashMarker);
+    } catch {
+      // A marker that cannot be parsed is skipped; it is one line of evidence,
+      // not the report.
+    }
+  }
+  return markers.sort((lhs, rhs) => lhs.wall - rhs.wall);
+}
+
+/**
+ * Attaches crash recording to a middle-layer worker thread.
+ *
+ * A worker whose isolate exhausts its heap dies alone and the parent receives
+ * `ERR_WORKER_OUT_OF_MEMORY`, with or without `resourceLimits`. What
+ * `resourceLimits.maxOldGenerationSizeMb` adds is a chosen ceiling: V8's default
+ * is several gigabytes, so on a small machine the OS can run out of memory and
+ * kill the whole process before V8 ever reports the worker's heap as full — and
+ * then there is no parent left to write anything.
+ */
+export function superviseWorker(
+  worker: SupervisedWorker,
+  dir: string,
+  options: SuperviseOptions = {},
+): void {
+  // One death fires `error` and then `exit`. Only `error` carries the cause, so
+  // a later `exit` must not overwrite it with a bare exit code.
+  let recorded = false;
+  worker.on("error", (error: Error) => {
+    recorded = true;
+    const markerFile = writeCrashMarker(dir, { error, sessionId: options.sessionId });
+    options.onCrash?.({ kind: "error", error, markerFile });
+  });
+  worker.on("exit", (code: number) => {
+    if (code === 0 || recorded) return;
+    const markerFile = writeCrashMarker(dir, {
+      reason: "worker-exit",
+      code,
+      sessionId: options.sessionId,
+    });
+    options.onCrash?.({ kind: "exit", code, markerFile });
+  });
+}
+
+// Internals
+
+// Advisory only, for a human reading a directory by hand: the dying session has
+// no terminating record, so among the sessions that look dead this names the one
+// that wrote last. Never used as identity — see `CrashMarker.guessedSessionId`.
+function newestOpenSessionId(dir: string): string | undefined {
+  const open = listSessions(dir).find((session) => session.crashed);
+  return open ? sessionIdFromFile(open.file) : undefined;
+}
+
+function classifyReason({ error, code, signal }: CrashMarkerInput): CrashReason {
+  const errorCode = (error as { code?: string } | undefined)?.code;
+  if (errorCode === "ERR_WORKER_OUT_OF_MEMORY") return "js-heap-out-of-memory";
+  if (signal === "SIGKILL") return "killed-by-os";
+  if (signal === "SIGABRT" || code === 134) return "abort-or-fatal-allocation-failure";
+  if (typeof code === "number" && code !== 0) return "nonzero-exit";
+  return "unknown";
+}
+
+function truncate(value: string, limit: number): string {
+  return value.length > limit ? `${value.slice(0, limit)}…` : value;
+}