@milaboratories/pl-crash-recorder 0.3.0

package/README.md

@@ -0,0 +1,119 @@
+# @milaboratories/pl-flight-recorder
+
+Explains an out-of-memory death in the block model layer after the fact, when
+the process is already gone and the data that caused it cannot be obtained.
+
+## Why it is built this way
+
+The failure this exists for kills the process in seconds and runs no shutdown
+path: V8 fatal out-of-memory, a failed native allocation, the OS out-of-memory
+killer. That rules out anything that collects on demand from a live process —
+`pprofDump`, cache metrics, a log that flushes on exit — because by the time
+anyone asks, there is nothing to ask.
+
+Three consequences shape the design:
+
+- **Records are appended synchronously.** A buffered stream loses exactly the
+  tail that explains the death. The absence of a terminating `session-end`
+  record is how a crash is detected.
+- **Memory is sampled from another thread.** While the middle layer sits inside
+  a synchronous pframes call its own timers do not fire, so its memory series
+  goes dark precisely when memory is growing fastest.
+- **The parent records the cause.** A thread that runs out of heap cannot
+  describe its own death; its last reading predates the blow-up. Node reports
+  `ERR_WORKER_OUT_OF_MEMORY` to the parent, which turns a guess into a fact.
+
+## Enabling it
+
+Inert unless `MI_FLIGHT_RECORDER_DIR` points at a directory. Recording appends
+on every recorded operation and that cost has not yet been measured against a
+real project, so it is opt-in rather than on by default.
+
+```
+MI_FLIGHT_RECORDER_DIR=~/platforma-flight <start the app>
+```
+
+## Reading a log
+
+```ts
+import { analyzeLatest, renderReport } from "@milaboratories/pl-flight-recorder";
+
+const analysis = analyzeLatest(dir); // prefers the session that crashed
+console.log(renderReport(analysis));
+```
+
+The verdict combines three independent lines of evidence, none sufficient alone:
+
+1. **What was in flight.** Every operation writes a begin and an end record, so
+   an unmatched begin names the exact call that was running when memory ran out.
+2. **Which memory ran out.** JS heap (confirmed by the parent), off-heap
+   ArrayBuffers handed out by the engine, native allocation, or the machine.
+   This decides whether `--max-old-space-size` is even relevant.
+3. **Why the data was that big.** Structural faults readable from the recorded
+   shape before any data is touched — a cartesian join, or axes that agree on
+   name and type but differ in domain — plus the observed row count against the
+   input the definition declared.
+
+## What is recorded, and how
+
+A definition is recorded by **shape**, not by a hand-written digest per
+definition type. `redact` walks whatever the seam was handed and rebuilds it:
+keys, numbers and the small set of strings that are schema survive verbatim,
+every other string becomes a hash and a length, and a column payload is replaced
+by counts. The default for an unrecognised string is to hash it, so a field this
+code has never seen can make a report less informative but never make it leak.
+
+- Kept: definition shape, column and axis names, value types, axis domains
+  (they carry join identity), filter operators, row/byte/partition counts.
+- Hashed: filter reference values, annotation values (`pl7.app/label` carries
+  user-entered sample names), column ids, every other string. The hash is
+  stable, so two labels can be compared without either being revealed.
+- Dropped: cell values, inline column payloads, partition keys.
+
+Two things bound one record: arrays keep their head and carry an `$omitted`
+marker, and a node budget stops a pathological definition from filling the log.
+A session's log is bounded the same way, at two segments of 32 MiB. Rotation
+rewrites into the new segment the three things a report cannot be produced
+without — the session header, the earliest memory reading, and the begin record
+of every operation still open — so repeated rotation costs only operations that
+already completed. The report states how many rotations happened.
+Class instances are named (`$opaque`) rather than walked, which matters because
+a definition can carry live accessors that reference each other.
+
+On a realistic definition (two columns, 72 partitions, a 1200-value filter) the
+record is ~1 KB against ~23 KB for the definition as it stands — but size is not
+why this exists. The definition as it stands cannot be sent to us at all.
+
+Only one module knows a definition's types: `data_summary`, which reads row
+counts and byte sizes out of `DataInfo` because those numbers live at
+type-specific positions and they are what predicts a join's cost.
+
+## Rules run in the analyzer
+
+Structural rules are not evaluated while recording. Nothing is computed on the
+hot path, the rules can be revised against logs that already exist, and one
+implementation covers every definition shape: join nodes are recognised by their
+discriminator and their children by position, so the original tree API and the
+V2 query API are read by the same walk.
+
+## Where it hooks in
+
+- `pl-middle-layer/src/middle_layer/driver_kit.ts` wraps the pFrame driver once.
+  Every join a model builds and every row it reads passes through it, so both
+  the creation calls and the data calls are covered without touching call sites.
+- `pl-middle-layer/src/js_render/index.ts` opens a render span per block, and one
+  per resumption of a deferred render. Driver calls carry no block identity of
+  their own, so the enclosing span is what attributes a join to a block.
+
+`executeSingleLambda` is deliberately not instrumented: it evaluates `args()`
+style lambdas with no computable context, so it reaches no driver.
+
+## Known gaps
+
+- The synchronous append cost is unmeasured on a real project; the sampler
+  interval and event granularity should be revisited with that number in hand.
+- A table view can die in the renderer process rather than in the middle-layer
+  worker. That path needs `render-process-gone` in the desktop app and is not
+  covered here.
+- Domain values are kept because they carry join identity. If any producer puts
+  a sample name in a domain value, it needs hashing too.

package/dist/data_summary.js

@@ -0,0 +1,100 @@
+//#region src/data_summary.ts
+function summarizeData(data) {
+	if (data === null || data === void 0) return { kind: "absent" };
+	if (Array.isArray(data)) return {
+		kind: "inline",
+		entries: data.length,
+		approxBytes: approxInlineBytes(data),
+		...inlineAxisCardinality(data)
+	};
+	if (typeof data !== "object") return { kind: typeof data };
+	const info = data;
+	switch (info.type) {
+		case "Json": return {
+			kind: "Json",
+			keyLength: numberOr(info.keyLength),
+			entries: countKeys(info.data)
+		};
+		case "JsonPartitioned":
+		case "BinaryPartitioned": return {
+			kind: info.type,
+			partitionKeyLength: numberOr(info.partitionKeyLength),
+			parts: countKeys(info.parts)
+		};
+		case "ParquetPartitioned": return summarizeParquet(info);
+		default: return { kind: info.type ?? opaqueKind(data) };
+	}
+}
+function summarizeParquet(info) {
+	const parts = Object.values(info.parts ?? {});
+	let rows = 0;
+	let bytes = 0;
+	let withStats = 0;
+	for (const part of parts) {
+		const stats = part?.stats;
+		if (!stats) continue;
+		withStats++;
+		if (typeof stats.numberOfRows === "number") rows += stats.numberOfRows;
+		if (stats.size) bytes += (stats.size.column ?? 0) + sum(stats.size.axes ?? []);
+	}
+	return {
+		kind: "ParquetPartitioned",
+		partitionKeyLength: numberOr(info.partitionKeyLength),
+		parts: parts.length,
+		partsWithStats: withStats,
+		rows: withStats > 0 ? rows : void 0,
+		bytes: withStats > 0 ? bytes : void 0
+	};
+}
+/**
+* How many entries may be walked to count distinct axis keys.
+*
+* Counting is exact and needs a set per axis, so it costs memory in proportion
+* to the distinct keys it finds — which is the wrong thing to spend in the
+* situation this code exists to diagnose. Past the cap the count is declined
+* rather than approximated, so a number that is present is always true.
+*/
+const CARDINALITY_LIMIT = 1e5;
+function inlineAxisCardinality(values) {
+	if (values.length > CARDINALITY_LIMIT) return { axisCardinalityUncounted: true };
+	const firstKey = values[0]?.key;
+	if (!Array.isArray(firstKey)) return {};
+	const perAxis = firstKey.map(() => /* @__PURE__ */ new Set());
+	const tuples = /* @__PURE__ */ new Set();
+	for (const entry of values) {
+		const key = entry.key;
+		if (!Array.isArray(key) || key.length !== perAxis.length) return {};
+		for (const [axis, value] of key.entries()) perAxis[axis].add(value);
+		tuples.add(key.map((value) => String(value)).join("\0"));
+	}
+	return {
+		axisCardinality: perAxis.map((set) => set.size),
+		distinctKeys: tuples.size
+	};
+}
+function approxInlineBytes(values) {
+	const sampleSize = Math.min(values.length, 64);
+	if (sampleSize === 0) return 0;
+	let bytes = 0;
+	for (let i = 0; i < sampleSize; i++) {
+		const value = values[Math.floor(i * values.length / sampleSize)];
+		bytes += JSON.stringify(value ?? null)?.length ?? 0;
+	}
+	return Math.round(bytes / sampleSize * values.length);
+}
+function countKeys(value) {
+	return value && typeof value === "object" ? Object.keys(value).length : void 0;
+}
+function numberOr(value) {
+	return typeof value === "number" ? value : void 0;
+}
+function opaqueKind(value) {
+	return value.constructor?.name ?? "opaque";
+}
+function sum(values) {
+	return values.reduce((acc, value) => acc + value, 0);
+}
+//#endregion
+export { summarizeData };
+
+//# sourceMappingURL=data_summary.js.map

package/dist/data_summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data_summary.js","names":[],"sources":["../src/data_summary.ts"],"sourcesContent":["/**\n * Counts and sizes for a column payload, never the payload.\n *\n * This is the one place that has to know the shape of `DataInfo`, because the\n * numbers that predict a join's cost — rows per partition and their byte sizes —\n * live at type-specific positions inside it. Everything else about a definition\n * is recorded structurally.\n *\n * Chunk statistics are optional: the producing workflow fills them in, so row\n * counts are reported when present and left unknown otherwise rather than\n * guessed.\n */\n\nexport type DataSummary = {\n  kind: string;\n  /** Entries for inline or JSON payloads. */\n  entries?: number;\n  approxBytes?: number;\n  keyLength?: number;\n  partitionKeyLength?: number;\n  parts?: number;\n  partsWithStats?: number;\n  rows?: number;\n  bytes?: number;\n  /**\n   * Distinct values per axis, in the order the column declares its axes.\n   *\n   * Counted independently, so multiplying them gives an upper bound on the\n   * distinct key tuples rather than their number: axes are usually correlated,\n   * and a product invents combinations that never occur. Use `distinctKeys`\n   * where the key in question is the whole tuple.\n   */\n  axisCardinality?: number[];\n  /**\n   * Distinct whole key tuples, which is exact where a join keys on every axis\n   * the column has — the ordinary case for two columns sharing their key.\n   */\n  distinctKeys?: number;\n  /** Set when the entries were too many to count distinct keys over. */\n  axisCardinalityUncounted?: boolean;\n};\n\nexport function summarizeData(data: unknown): DataSummary {\n  if (data === null || data === undefined) return { kind: \"absent\" };\n  if (Array.isArray(data)) {\n    // Inline values, built inside the model sandbox.\n    return {\n      kind: \"inline\",\n      entries: data.length,\n      approxBytes: approxInlineBytes(data),\n      ...inlineAxisCardinality(data),\n    };\n  }\n  if (typeof data !== \"object\") return { kind: typeof data };\n\n  const info = data as { type?: string; [key: string]: unknown };\n  switch (info.type) {\n    case \"Json\":\n      return {\n        kind: \"Json\",\n        keyLength: numberOr(info.keyLength),\n        entries: countKeys(info.data),\n      };\n    case \"JsonPartitioned\":\n    case \"BinaryPartitioned\":\n      return {\n        kind: info.type,\n        partitionKeyLength: numberOr(info.partitionKeyLength),\n        parts: countKeys(info.parts),\n      };\n    case \"ParquetPartitioned\":\n      return summarizeParquet(info);\n    default:\n      return { kind: info.type ?? opaqueKind(data) };\n  }\n}\n\n// Internals\n\nfunction summarizeParquet(info: { [key: string]: unknown }): DataSummary {\n  const parts = Object.values((info.parts ?? {}) as Record<string, unknown>);\n  let rows = 0;\n  let bytes = 0;\n  let withStats = 0;\n  for (const part of parts) {\n    const stats = (\n      part as { stats?: { numberOfRows?: number; size?: { axes?: number[]; column?: number } } }\n    )?.stats;\n    if (!stats) continue;\n    withStats++;\n    if (typeof stats.numberOfRows === \"number\") rows += stats.numberOfRows;\n    if (stats.size) bytes += (stats.size.column ?? 0) + sum(stats.size.axes ?? []);\n  }\n  return {\n    kind: \"ParquetPartitioned\",\n    partitionKeyLength: numberOr(info.partitionKeyLength),\n    parts: parts.length,\n    partsWithStats: withStats,\n    rows: withStats > 0 ? rows : undefined,\n    bytes: withStats > 0 ? bytes : undefined,\n  };\n}\n\n/**\n * How many entries may be walked to count distinct axis keys.\n *\n * Counting is exact and needs a set per axis, so it costs memory in proportion\n * to the distinct keys it finds — which is the wrong thing to spend in the\n * situation this code exists to diagnose. Past the cap the count is declined\n * rather than approximated, so a number that is present is always true.\n */\nconst CARDINALITY_LIMIT = 100_000;\n\nfunction inlineAxisCardinality(values: unknown[]): {\n  axisCardinality?: number[];\n  distinctKeys?: number;\n  axisCardinalityUncounted?: boolean;\n} {\n  if (values.length > CARDINALITY_LIMIT) return { axisCardinalityUncounted: true };\n  const firstKey = (values[0] as { key?: unknown } | undefined)?.key;\n  if (!Array.isArray(firstKey)) return {};\n\n  const perAxis = firstKey.map(() => new Set<unknown>());\n  // Counted alongside the per-axis sets rather than derived from them: the two\n  // are equal only when the axes vary independently, which they rarely do.\n  const tuples = new Set<string>();\n  for (const entry of values) {\n    const key = (entry as { key?: unknown }).key;\n    if (!Array.isArray(key) || key.length !== perAxis.length) return {};\n    for (const [axis, value] of key.entries()) perAxis[axis].add(value);\n    tuples.add(key.map((value) => String(value)).join(\"\\u0000\"));\n  }\n  return { axisCardinality: perAxis.map((set) => set.size), distinctKeys: tuples.size };\n}\n\n// Sampled rather than measured: walking millions of entries to size them is\n// itself a memory risk in the situation this code exists to diagnose.\nfunction approxInlineBytes(values: unknown[]): number {\n  const sampleSize = Math.min(values.length, 64);\n  if (sampleSize === 0) return 0;\n  let bytes = 0;\n  for (let i = 0; i < sampleSize; i++) {\n    const value = values[Math.floor((i * values.length) / sampleSize)];\n    bytes += JSON.stringify(value ?? null)?.length ?? 0;\n  }\n  return Math.round((bytes / sampleSize) * values.length);\n}\n\nfunction countKeys(value: unknown): number | undefined {\n  return value && typeof value === \"object\" ? Object.keys(value).length : undefined;\n}\n\nfunction numberOr(value: unknown): number | undefined {\n  return typeof value === \"number\" ? value : undefined;\n}\n\nfunction opaqueKind(value: object): string {\n  return (value as { constructor?: { name?: string } }).constructor?.name ?? \"opaque\";\n}\n\nfunction sum(values: number[]): number {\n  return values.reduce((acc, value) => acc + value, 0);\n}\n"],"mappings":"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"}

package/dist/digest.js

@@ -0,0 +1,26 @@
+import { redact } from "./redact.js";
+//#region src/digest.ts
+/** Records one definition: redacted, measured, and tagged with its API shape. */
+function digestDef(kind, def) {
+	const { value, stats } = redact(def);
+	const json = safeLength(value);
+	return {
+		kind,
+		def: value,
+		redaction: {
+			...stats,
+			bytes: json
+		}
+	};
+}
+function safeLength(value) {
+	try {
+		return JSON.stringify(value)?.length ?? 0;
+	} catch {
+		return 0;
+	}
+}
+//#endregion
+export { digestDef };
+
+//# sourceMappingURL=digest.js.map

package/dist/digest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"digest.js","names":[],"sources":["../src/digest.ts"],"sourcesContent":["import { redact, type RedactionStats } from \"./redact\";\n\n/**\n * What a definition record carries.\n *\n * The definition is recorded structurally (see `redact`) rather than through a\n * hand-written digest per definition type. Structural rules are not run here:\n * they belong to the analyzer, so nothing is computed on the hot path and the\n * rules can be revised against logs that already exist.\n */\n\nexport type DefKind = \"PTableDef\" | \"PTableDefV2\" | \"PFrameDef\";\n\nexport type DefDigest = {\n  kind: DefKind;\n  /** Redacted definition, same shape as the original. */\n  def: unknown;\n  redaction: RedactionStats & { bytes: number };\n};\n\n/** Records one definition: redacted, measured, and tagged with its API shape. */\nexport function digestDef(kind: DefKind, def: unknown): DefDigest {\n  const { value, stats } = redact(def);\n  const json = safeLength(value);\n  return { kind, def: value, redaction: { ...stats, bytes: json } };\n}\n\n// Internals\n\nfunction safeLength(value: unknown): number {\n  try {\n    return JSON.stringify(value)?.length ?? 0;\n  } catch {\n    return 0;\n  }\n}\n"],"mappings":";;;AAqBA,SAAgB,UAAU,MAAe,KAAyB;CAChE,MAAM,EAAE,OAAO,UAAU,OAAO,GAAG;CACnC,MAAM,OAAO,WAAW,KAAK;CAC7B,OAAO;EAAE;EAAM,KAAK;EAAO,WAAW;GAAE,GAAG;GAAO,OAAO;EAAK;CAAE;AAClE;AAIA,SAAS,WAAW,OAAwB;CAC1C,IAAI;EACF,OAAO,KAAK,UAAU,KAAK,CAAC,EAAE,UAAU;CAC1C,QAAQ;EACN,OAAO;CACT;AACF"}

package/dist/events.d.ts

@@ -0,0 +1,149 @@
+//#region src/events.d.ts
+/**
+ * Record types written to a crash log.
+ *
+ * The log is append-only NDJSON, one record per line, and is read back by
+ * tooling that may be older or newer than the writer, so every field beyond
+ * {@link LogRecordBase} is optional and unknown record types are skipped
+ * rather than rejected.
+ */
+/** Memory reading taken by the thread that wrote the record. */
+export type MemorySnapshot = {
+  /** Resident set size of the whole process. */
+  rss: number;
+  /** Heap in use by the writing thread's isolate. */
+  heapUsed: number;
+  heapTotal: number;
+  external: number;
+  arrayBuffers: number;
+  /** V8 heap ceiling for the writing thread's isolate. */
+  heapLimit: number;
+};
+type LogRecordBase = {
+  /** Monotonically increasing within one session; used to pair begin with end. */
+  seq: number;
+  /** Milliseconds since process start, for durations. */
+  t: number;
+  /** Wall clock, for correlating with the sampler series and crash markers. */
+  wall: number;
+  type: string;
+};
+export type LogRecord = LogRecordBase & {
+  mem?: MemorySnapshot;
+  /** Sequence number of the matching begin record, on end and error records. */
+  begin?: number;
+  [key: string]: unknown;
+};
+/** Session header, always the first record. */
+export type SessionEnvironment = {
+  node: string;
+  platform: string;
+  cpus: number;
+  totalMemory: number;
+  heapLimit: number;
+  execArgv: string[];
+  maxOldSpaceSize?: number;
+};
+/** Written by the sampler thread to its own sibling file. */
+export type SamplerRecord = LogRecordBase & {
+  type: "mem-sampler";
+  rss: number;
+  peakRss: number;
+  /** Highest resident size the kernel has seen for this process. */
+  maxRss?: number;
+  freeMemory: number;
+  totalMemory: number;
+  /** Where the machine's memory actually is, refreshed less often than `rss`. */
+  machine?: MachineMemory;
+};
+/**
+ * A reading only the application process can take.
+ *
+ * Resident size falls when the OS compresses or pages a process out, so it
+ * cannot say whether the memory was released or merely moved. Private bytes can:
+ * they are unshared and stay committed until the process actually gives them
+ * back. That is the difference between "our process is holding this" and "the
+ * machine is short of memory for some other reason", which nothing else here
+ * distinguishes.
+ */
+export type HostRecord = LogRecordBase & {
+  type: "mem-host";
+  /** Unshared, still-committed bytes of the process hosting the middle layer. */
+  private?: number;
+  /** What the machine has paged out, where the platform reports it. */
+  swapUsed?: number;
+  swapTotal?: number;
+  /** The same figure per process, where the host can enumerate its own. */
+  processes?: {
+    pid: number;
+    name?: string;
+    private?: number;
+  }[];
+};
+/**
+ * The machine's own account of its memory.
+ *
+ * Resident size is not the whole story on a machine under pressure: macOS moves
+ * pages out of a process's resident set into the compressor, and both Unixes
+ * swap, so a process can appear to shrink while the memory it asked for is still
+ * held. These readings are what a resident-size curve has to be read against.
+ */
+export type MachineMemory = {
+  /** Bytes of process memory the compressor holds, counted before compression. */
+  compressedStored?: number;
+  /** Physical bytes the compressor itself occupies. */
+  compressedOccupied?: number;
+  swapUsed?: number;
+  swapTotal?: number;
+  anonymous?: number;
+  fileBacked?: number;
+  wired?: number;
+  /** Why the reading is missing, when it is. */
+  unavailable?: string;
+};
+/** Written by the parent when a supervised thread or process dies. */
+export type CrashMarker = {
+  type: "external-crash";
+  wall: number;
+  /**
+   * Session the marker belongs to. Present only when the parent assigned the id
+   * to the worker and therefore knows it; never inferred, because a wrong id
+   * here would both misattribute the death and stop the right session from
+   * claiming it.
+   */
+  sessionId?: string;
+  /**
+   * Advisory only: the newest open crash log at the moment of death. A
+   * concurrent live session can make this wrong, so it is never matched against
+   * — it exists to help a human read a directory by hand.
+   */
+  guessedSessionId?: string;
+  /** Written by an older recorder that put a guess in `sessionId`. */
+  sessionIdSource?: "assigned" | "guessed";
+  reason: CrashReason;
+  errorCode?: string;
+  errorName?: string;
+  message?: string;
+  exitCode?: number;
+  signal?: string;
+  stderrTail?: string;
+  /**
+   * What memory looked like when the death was observed, taken by the parent.
+   *
+   * Without it a marker reading `worker-exit` with exit code 1 is
+   * indistinguishable from an ordinary application error, and a reader who
+   * starts here would classify an exhausted machine as a bug in the code that
+   * happened to be running.
+   */
+  memoryAtDeath?: {
+    /** Resident size of the parent process, which hosts the dying worker. */
+    rss: number;
+    /** Highest resident size the kernel recorded for it. */
+    maxRss: number;
+    freeMemory: number;
+    totalMemory: number;
+  };
+};
+export type CrashReason = "js-heap-out-of-memory" | "killed-by-os" | "abort-or-fatal-allocation-failure" | "worker-exit" | "nonzero-exit" | "unknown";
+//#endregion
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","names":[],"sources":["../src/events.ts"],"mappings":";;;;;;;;;;YAUY;;EAEV;;EAEA;EACA;EACA;EACA;;EAEA;;KAGG;;EAEH;;EAEA;;EAEA;EACA;;YAGU,YAAY;EACtB,MAAM;;EAEN;GACC;;;YAIS;EACV;EACA;EACA;EACA;EACA;EACA;EACA;;;YAIU,gBAAgB;EAC1B;EACA;EACA;;EAEA;EACA;EACA;;EAEA,UAAU;;;;;;;;;;;;YAaA,aAAa;EACvB;;EAEA;;EAEA;EACA;;EAEA;IAAc;IAAa;IAAe;;;;;;;;;;;YAWhC;;EAEV;;EAEA;EACA;EACA;EACA;EACA;EACA;;EAEA;;;YAIU;EACV;EACA;;;;;;;EAOA;;;;;;EAMA;;EAEA;EACA,QAAQ;EACR;EACA;EACA;EACA;EACA;EACA;;;;;;;;;EASA;;IAEE;;IAEA;IACA;IACA;;;YAIQ"}

package/dist/events.js

@@ -0,0 +1,13 @@
+//#region src/events.ts
+const SESSION_RECORD = "session";
+/** Earliest memory reading of a session, rewritten into every rotated segment. */
+const MEM_BASELINE_RECORD = "mem-baseline";
+const SESSION_END_RECORD = "session-end";
+const HOST_FILE_PREFIX = "host";
+const SESSION_FILE_PREFIX = "session";
+const SAMPLER_FILE_PREFIX = "memory";
+const DEATH_FILE_PREFIX = "death";
+//#endregion
+export { DEATH_FILE_PREFIX, HOST_FILE_PREFIX, MEM_BASELINE_RECORD, SAMPLER_FILE_PREFIX, SESSION_END_RECORD, SESSION_FILE_PREFIX, SESSION_RECORD };
+
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","names":[],"sources":["../src/events.ts"],"sourcesContent":["/**\n * Record types written to a crash log.\n *\n * The log is append-only NDJSON, one record per line, and is read back by\n * tooling that may be older or newer than the writer, so every field beyond\n * {@link LogRecordBase} is optional and unknown record types are skipped\n * rather than rejected.\n */\n\n/** Memory reading taken by the thread that wrote the record. */\nexport type MemorySnapshot = {\n  /** Resident set size of the whole process. */\n  rss: number;\n  /** Heap in use by the writing thread's isolate. */\n  heapUsed: number;\n  heapTotal: number;\n  external: number;\n  arrayBuffers: number;\n  /** V8 heap ceiling for the writing thread's isolate. */\n  heapLimit: number;\n};\n\ntype LogRecordBase = {\n  /** Monotonically increasing within one session; used to pair begin with end. */\n  seq: number;\n  /** Milliseconds since process start, for durations. */\n  t: number;\n  /** Wall clock, for correlating with the sampler series and crash markers. */\n  wall: number;\n  type: string;\n};\n\nexport type LogRecord = LogRecordBase & {\n  mem?: MemorySnapshot;\n  /** Sequence number of the matching begin record, on end and error records. */\n  begin?: number;\n  [key: string]: unknown;\n};\n\n/** Session header, always the first record. */\nexport type SessionEnvironment = {\n  node: string;\n  platform: string;\n  cpus: number;\n  totalMemory: number;\n  heapLimit: number;\n  execArgv: string[];\n  maxOldSpaceSize?: number;\n};\n\n/** Written by the sampler thread to its own sibling file. */\nexport type SamplerRecord = LogRecordBase & {\n  type: \"mem-sampler\";\n  rss: number;\n  peakRss: number;\n  /** Highest resident size the kernel has seen for this process. */\n  maxRss?: number;\n  freeMemory: number;\n  totalMemory: number;\n  /** Where the machine's memory actually is, refreshed less often than `rss`. */\n  machine?: MachineMemory;\n};\n\n/**\n * A reading only the application process can take.\n *\n * Resident size falls when the OS compresses or pages a process out, so it\n * cannot say whether the memory was released or merely moved. Private bytes can:\n * they are unshared and stay committed until the process actually gives them\n * back. That is the difference between \"our process is holding this\" and \"the\n * machine is short of memory for some other reason\", which nothing else here\n * distinguishes.\n */\nexport type HostRecord = LogRecordBase & {\n  type: \"mem-host\";\n  /** Unshared, still-committed bytes of the process hosting the middle layer. */\n  private?: number;\n  /** What the machine has paged out, where the platform reports it. */\n  swapUsed?: number;\n  swapTotal?: number;\n  /** The same figure per process, where the host can enumerate its own. */\n  processes?: { pid: number; name?: string; private?: number }[];\n};\n\n/**\n * The machine's own account of its memory.\n *\n * Resident size is not the whole story on a machine under pressure: macOS moves\n * pages out of a process's resident set into the compressor, and both Unixes\n * swap, so a process can appear to shrink while the memory it asked for is still\n * held. These readings are what a resident-size curve has to be read against.\n */\nexport type MachineMemory = {\n  /** Bytes of process memory the compressor holds, counted before compression. */\n  compressedStored?: number;\n  /** Physical bytes the compressor itself occupies. */\n  compressedOccupied?: number;\n  swapUsed?: number;\n  swapTotal?: number;\n  anonymous?: number;\n  fileBacked?: number;\n  wired?: number;\n  /** Why the reading is missing, when it is. */\n  unavailable?: string;\n};\n\n/** Written by the parent when a supervised thread or process dies. */\nexport type CrashMarker = {\n  type: \"external-crash\";\n  wall: number;\n  /**\n   * Session the marker belongs to. Present only when the parent assigned the id\n   * to the worker and therefore knows it; never inferred, because a wrong id\n   * here would both misattribute the death and stop the right session from\n   * claiming it.\n   */\n  sessionId?: string;\n  /**\n   * Advisory only: the newest open crash log at the moment of death. A\n   * concurrent live session can make this wrong, so it is never matched against\n   * — it exists to help a human read a directory by hand.\n   */\n  guessedSessionId?: string;\n  /** Written by an older recorder that put a guess in `sessionId`. */\n  sessionIdSource?: \"assigned\" | \"guessed\";\n  reason: CrashReason;\n  errorCode?: string;\n  errorName?: string;\n  message?: string;\n  exitCode?: number;\n  signal?: string;\n  stderrTail?: string;\n  /**\n   * What memory looked like when the death was observed, taken by the parent.\n   *\n   * Without it a marker reading `worker-exit` with exit code 1 is\n   * indistinguishable from an ordinary application error, and a reader who\n   * starts here would classify an exhausted machine as a bug in the code that\n   * happened to be running.\n   */\n  memoryAtDeath?: {\n    /** Resident size of the parent process, which hosts the dying worker. */\n    rss: number;\n    /** Highest resident size the kernel recorded for it. */\n    maxRss: number;\n    freeMemory: number;\n    totalMemory: number;\n  };\n};\n\nexport type CrashReason =\n  | \"js-heap-out-of-memory\"\n  | \"killed-by-os\"\n  | \"abort-or-fatal-allocation-failure\"\n  | \"worker-exit\"\n  | \"nonzero-exit\"\n  | \"unknown\";\n\nexport const SESSION_RECORD = \"session\";\n/** Earliest memory reading of a session, rewritten into every rotated segment. */\nexport const MEM_BASELINE_RECORD = \"mem-baseline\";\nexport const SESSION_END_RECORD = \"session-end\";\nexport const HOST_FILE_PREFIX = \"host\";\nexport const SESSION_FILE_PREFIX = \"session\";\nexport const SAMPLER_FILE_PREFIX = \"memory\";\nexport const DEATH_FILE_PREFIX = \"death\";\n"],"mappings":";AA8JA,MAAa,iBAAiB;;AAE9B,MAAa,sBAAsB;AACnC,MAAa,qBAAqB;AAClC,MAAa,mBAAmB;AAChC,MAAa,sBAAsB;AACnC,MAAa,sBAAsB;AACnC,MAAa,oBAAoB"}

package/dist/host_sampler.d.ts

@@ -0,0 +1,35 @@
+import { HostRecord } from "./events.js";
+//#region src/host_sampler.d.ts
+export type HostReading = Omit<HostRecord, "seq" | "t" | "wall" | "type">;
+export type HostSamplerOptions = {
+  dir: string;
+  sessionId: string;
+  /**
+   * Takes one reading. Supplied by the caller because the useful numbers come
+   * from the application framework rather than from Node, and this package must
+   * not depend on it.
+   */
+  read: () => HostReading | Promise<HostReading>;
+  /** Sampling period; these readings change slowly and cost more than resident size. */
+  intervalMs?: number;
+};
+export type HostSampler = {
+  /** Sibling log this sampler appends to. */
+  readonly file: string;
+  stop(): void;
+};
+/**
+ * Records what only the host process can measure, beside the session it hosts.
+ *
+ * Its own file rather than the session log: that log belongs to another thread
+ * and has its own descriptor and sequence, and two writers sharing them would
+ * corrupt both. Readers join the two by wall clock, as they already do with the
+ * memory sampler.
+ *
+ * This one runs wherever the caller runs, so a blocked host stops it — which is
+ * why it supplements the sampler thread rather than replacing it. What it adds
+ * is attribution, and attribution a second stale is still attribution.
+ */
+export declare function startHostSampler(options: HostSamplerOptions): HostSampler;
+//#endregion
+//# sourceMappingURL=host_sampler.d.ts.map

package/dist/host_sampler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host_sampler.d.ts","names":[],"sources":["../src/host_sampler.ts"],"mappings":";;YAIY,cAAc,KAAK;YAEnB;EACV;EACA;;;;;;EAMA,YAAY,cAAc,QAAQ;;EAElC;;YAGU;;WAED;EACT;;;;;;;;;;;;;;wBAec,iBAAiB,SAAS,qBAAqB"}

package/dist/host_sampler.js

@@ -0,0 +1,54 @@
+import { HOST_FILE_PREFIX } from "./events.js";
+import fs from "node:fs";
+import path from "node:path";
+//#region src/host_sampler.ts
+/**
+* Records what only the host process can measure, beside the session it hosts.
+*
+* Its own file rather than the session log: that log belongs to another thread
+* and has its own descriptor and sequence, and two writers sharing them would
+* corrupt both. Readers join the two by wall clock, as they already do with the
+* memory sampler.
+*
+* This one runs wherever the caller runs, so a blocked host stops it — which is
+* why it supplements the sampler thread rather than replacing it. What it adds
+* is attribution, and attribution a second stale is still attribution.
+*/
+function startHostSampler(options) {
+	const { dir, sessionId, read, intervalMs = 1e3 } = options;
+	fs.mkdirSync(dir, { recursive: true });
+	const file = path.join(dir, `${HOST_FILE_PREFIX}-${sessionId}.ndjson`);
+	const fd = fs.openSync(file, "a");
+	let seq = 0;
+	let writing = false;
+	const timer = setInterval(() => {
+		if (writing) return;
+		writing = true;
+		Promise.resolve().then(read).then((reading) => {
+			const record = {
+				seq: ++seq,
+				t: Math.round(performance.now() * 1e3) / 1e3,
+				wall: Date.now(),
+				type: "mem-host",
+				...reading
+			};
+			fs.writeSync(fd, `${JSON.stringify(record)}\n`);
+		}).catch(() => {}).finally(() => {
+			writing = false;
+		});
+	}, intervalMs);
+	timer.unref();
+	return {
+		file,
+		stop: () => {
+			clearInterval(timer);
+			try {
+				fs.closeSync(fd);
+			} catch {}
+		}
+	};
+}
+//#endregion
+export { startHostSampler };
+
+//# sourceMappingURL=host_sampler.js.map

package/dist/host_sampler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host_sampler.js","names":[],"sources":["../src/host_sampler.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { HOST_FILE_PREFIX, type HostRecord } from \"./events\";\n\nexport type HostReading = Omit<HostRecord, \"seq\" | \"t\" | \"wall\" | \"type\">;\n\nexport type HostSamplerOptions = {\n  dir: string;\n  sessionId: string;\n  /**\n   * Takes one reading. Supplied by the caller because the useful numbers come\n   * from the application framework rather than from Node, and this package must\n   * not depend on it.\n   */\n  read: () => HostReading | Promise<HostReading>;\n  /** Sampling period; these readings change slowly and cost more than resident size. */\n  intervalMs?: number;\n};\n\nexport type HostSampler = {\n  /** Sibling log this sampler appends to. */\n  readonly file: string;\n  stop(): void;\n};\n\n/**\n * Records what only the host process can measure, beside the session it hosts.\n *\n * Its own file rather than the session log: that log belongs to another thread\n * and has its own descriptor and sequence, and two writers sharing them would\n * corrupt both. Readers join the two by wall clock, as they already do with the\n * memory sampler.\n *\n * This one runs wherever the caller runs, so a blocked host stops it — which is\n * why it supplements the sampler thread rather than replacing it. What it adds\n * is attribution, and attribution a second stale is still attribution.\n */\nexport function startHostSampler(options: HostSamplerOptions): HostSampler {\n  const { dir, sessionId, read, intervalMs = 1000 } = options;\n  fs.mkdirSync(dir, { recursive: true });\n  const file = path.join(dir, `${HOST_FILE_PREFIX}-${sessionId}.ndjson`);\n  const fd = fs.openSync(file, \"a\");\n  let seq = 0;\n  let writing = false;\n\n  const timer = setInterval(() => {\n    // A reading that outlives its interval must not queue up behind itself.\n    if (writing) return;\n    writing = true;\n    void Promise.resolve()\n      .then(read)\n      .then((reading) => {\n        const record: HostRecord = {\n          seq: ++seq,\n          t: Math.round(performance.now() * 1000) / 1000,\n          wall: Date.now(),\n          type: \"mem-host\",\n          ...reading,\n        };\n        fs.writeSync(fd, `${JSON.stringify(record)}\\n`);\n      })\n      .catch(() => {\n        // Sampling must never take the application down.\n      })\n      .finally(() => {\n        writing = false;\n      });\n  }, intervalMs);\n  // Unreferenced so a sampler that is never stopped cannot hold the host open.\n  timer.unref();\n\n  return {\n    file,\n    stop: () => {\n      clearInterval(timer);\n      try {\n        fs.closeSync(fd);\n      } catch {\n        // Closing an already-dead descriptor must not fail shutdown.\n      }\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAqCA,SAAgB,iBAAiB,SAA0C;CACzE,MAAM,EAAE,KAAK,WAAW,MAAM,aAAa,QAAS;CACpD,GAAG,UAAU,KAAK,EAAE,WAAW,KAAK,CAAC;CACrC,MAAM,OAAO,KAAK,KAAK,KAAK,GAAG,iBAAiB,GAAG,UAAU,QAAQ;CACrE,MAAM,KAAK,GAAG,SAAS,MAAM,GAAG;CAChC,IAAI,MAAM;CACV,IAAI,UAAU;CAEd,MAAM,QAAQ,kBAAkB;EAE9B,IAAI,SAAS;EACb,UAAU;EACV,QAAa,QAAQ,CAAC,CACnB,KAAK,IAAI,CAAC,CACV,MAAM,YAAY;GACjB,MAAM,SAAqB;IACzB,KAAK,EAAE;IACP,GAAG,KAAK,MAAM,YAAY,IAAI,IAAI,GAAI,IAAI;IAC1C,MAAM,KAAK,IAAI;IACf,MAAM;IACN,GAAG;GACL;GACA,GAAG,UAAU,IAAI,GAAG,KAAK,UAAU,MAAM,EAAE,GAAG;EAChD,CAAC,CAAC,CACD,YAAY,CAEb,CAAC,CAAC,CACD,cAAc;GACb,UAAU;EACZ,CAAC;CACL,GAAG,UAAU;CAEb,MAAM,MAAM;CAEZ,OAAO;EACL;EACA,YAAY;GACV,cAAc,KAAK;GACnB,IAAI;IACF,GAAG,UAAU,EAAE;GACjB,QAAQ,CAER;EACF;CACF;AACF"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { CrashMarker, CrashReason, HostRecord, LogRecord, MachineMemory, MemorySnapshot, SamplerRecord, SessionEnvironment } from "./events.js";
+import { Recorder, RecorderOptions, SessionFileInfo, listSessions, newSessionId, openRecorder, sessionIdFromFile } from "./recorder.js";
+import { HandleRegistry, RenderInfo, createHandleRegistry, recordModelRenderSync, wrapDataDriver, wrapModelDriver } from "./instrument.js";
+import { CRASH_DIR_ENV, CRASH_SESSION_ENV, RecordingSession, RecordingSessionOptions, openRecordingSession } from "./session.js";
+import { HostReading, HostSampler, HostSamplerOptions, startHostSampler } from "./host_sampler.js";
+import { SuperviseOptions, SupervisedWorker, readCrashMarkers, superviseWorker } from "./supervisor.js";
+export { CRASH_DIR_ENV, CRASH_SESSION_ENV, type CrashMarker, type CrashReason, type HandleRegistry, type HostReading, type HostRecord, type HostSampler, type HostSamplerOptions, type LogRecord, type MachineMemory, type MemorySnapshot, type Recorder, type RecorderOptions, type RecordingSession, type RecordingSessionOptions, type RenderInfo, type SamplerRecord, type SessionEnvironment, type SessionFileInfo, type SuperviseOptions, type SupervisedWorker, createHandleRegistry, listSessions, newSessionId, openRecorder, openRecordingSession, readCrashMarkers, recordModelRenderSync, sessionIdFromFile, startHostSampler, superviseWorker, wrapDataDriver, wrapModelDriver };

package/dist/index.js

@@ -0,0 +1,6 @@
+import { listSessions, newSessionId, openRecorder, sessionIdFromFile } from "./recorder.js";
+import { createHandleRegistry, recordModelRenderSync, wrapDataDriver, wrapModelDriver } from "./instrument.js";
+import { CRASH_DIR_ENV, CRASH_SESSION_ENV, openRecordingSession } from "./session.js";
+import { startHostSampler } from "./host_sampler.js";
+import { readCrashMarkers, superviseWorker } from "./supervisor.js";
+export { CRASH_DIR_ENV, CRASH_SESSION_ENV, createHandleRegistry, listSessions, newSessionId, openRecorder, openRecordingSession, readCrashMarkers, recordModelRenderSync, sessionIdFromFile, startHostSampler, superviseWorker, wrapDataDriver, wrapModelDriver };

package/dist/instrument.d.ts

@@ -0,0 +1,79 @@
+import { Recorder } from "./recorder.js";
+//#region src/instrument.d.ts
+/**
+ * Wrappers for the seams the model layer passes through.
+ *
+ * Every operation writes a begin record and an end record. That pairing is what
+ * makes a crash legible: when the process dies mid-operation the end record is
+ * missing, so the log names the exact call that was running when memory ran out
+ * — the question a post-crash report has to answer.
+ *
+ * The wrappers are structural rather than tied to one driver interface, because
+ * the same three creation methods appear twice with different return types: the
+ * model-facing driver hands back a bare handle, the internal one hands back a
+ * pool entry.
+ */
+type HandleOrigin = {
+  /** Sequence number of the record holding the definition. */
+  seq: number;
+  op: string;
+  observed?: {
+    rows?: number;
+    columns?: number;
+  };
+};
+export type HandleRegistry = {
+  put(handle: string, origin: HandleOrigin): void;
+  get(handle: string): HandleOrigin | undefined;
+  observe(handle: string, observed: {
+    rows?: number;
+    columns?: number;
+  }): void;
+};
+type ModelDriverLike<H> = {
+  createPFrame(def: never): H;
+  createPTable(def: never): H;
+  createPTableV2(def: never): H;
+};
+export type RenderInfo = {
+  blockId?: string;
+  /** What the block is, as `organization:name` — not the id it has in a project. */
+  block?: string;
+  blockVersion?: string;
+  /** Where the block came from: a registry, a local pack, a dev folder. */
+  blockSource?: string;
+  /** SDK the block's model was built against. */
+  sdkVersion?: string;
+  key?: string;
+  argsHash?: string;
+  /** Which lambda of the block's model is being rendered. */
+  lambda?: string;
+  /** Nth resumption of a deferred render, counted from one. */
+  recalculation?: number;
+  /** Read after the render, so sandbox counters cover the whole call. */
+  getStats?: () => unknown;
+  /** Any further context the call site wants on the record. */
+  [key: string]: unknown;
+};
+/** Maps driver handles back to the join that produced them. */
+export declare function createHandleRegistry(limit?: number): HandleRegistry;
+/**
+ * Wraps the driver that block models call to build frames and tables.
+ *
+ * Records the redacted join tree and its structural findings, then remembers
+ * which handle came from which join so later data calls can be attributed back
+ * to the definition that caused them.
+ */
+export declare function wrapModelDriver<D extends ModelDriverLike<unknown>>(driver: D, recorder: Recorder, registry: HandleRegistry, handleOf?: (result: unknown) => string): D;
+/**
+ * Wraps the asynchronous data-access driver.
+ *
+ * Adds the observed table shape, the size of what crossed back into JavaScript,
+ * and the amplification between input and output rows — the empirical
+ * counterpart to the structural findings taken from the join tree.
+ */
+export declare function wrapDataDriver<D extends object>(driver: D, recorder: Recorder, registry: HandleRegistry): D;
+/** Synchronous variant, for a render that is not driven by a promise. */
+export declare function recordModelRenderSync<T>(recorder: Recorder | undefined, info: RenderInfo, fn: () => T): T;
+//#endregion
+//# sourceMappingURL=instrument.d.ts.map

package/dist/instrument.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrument.d.ts","names":[],"sources":["../src/instrument.ts"],"mappings":";;;;;;;;;;;;;;;KAmBK;;EAEH;EACA;EACA;IAAa;IAAe;;;YAGlB;EACV,IAAI,gBAAgB,QAAQ;EAC5B,IAAI,iBAAiB;EACrB,QAAQ,gBAAgB;IAAY;IAAe;;;KAGhD,gBAAgB;EACnB,aAAa,aAAa;EAC1B,aAAa,aAAa;EAC1B,eAAe,aAAa;;YAGlB;EACV;;EAEA;EACA;;EAEA;;EAEA;EACA;EACA;;EAEA;;EAEA;;EAEA;;GAEC;;;wBAIa,qBAAqB,iBAAc;;;;;;;;wBA2BnC,gBAAgB,UAAU,0BACxC,QAAQ,GACR,UAAU,UACV,UAAU,gBACV,YAAW,6BACV;;;;;;;;wBA8Ba,eAAe,kBAC7B,QAAQ,GACR,UAAU,UACV,UAAU,iBACT;;wBAgKa,sBAAsB,GACpC,UAAU,sBACV,MAAM,YACN,UAAU,IACT"}