@milaboratories/pl-flight-recorder 0.2.0

package/dist/instrument.js

@@ -0,0 +1,313 @@
+import { redact } from "./redact.js";
+import { digestDef } from "./digest.js";
+//#region src/instrument.ts
+/** Maps driver handles back to the join that produced them. */
+function createHandleRegistry(limit = 512) {
+	const map = /* @__PURE__ */ new Map();
+	return {
+		put(handle, origin) {
+			if (map.size >= limit) {
+				const oldest = map.keys().next();
+				if (!oldest.done) map.delete(oldest.value);
+			}
+			map.set(handle, origin);
+		},
+		get(handle) {
+			return map.get(handle);
+		},
+		observe(handle, observed) {
+			const origin = map.get(handle);
+			if (origin) origin.observed = observed;
+		}
+	};
+}
+/**
+* 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.
+*/
+function wrapModelDriver(driver, recorder, registry, handleOf = defaultHandleOf) {
+	return Object.assign(Object.create(driver), {
+		createPFrame(def) {
+			return record(recorder, registry, handleOf, "createPFrame", "PFrameDef", def, () => driver.createPFrame(def));
+		},
+		createPTable(def) {
+			return record(recorder, registry, handleOf, "createPTable", "PTableDef", def, () => driver.createPTable(def));
+		},
+		createPTableV2(def) {
+			return record(recorder, registry, handleOf, "createPTableV2", "PTableDefV2", def, () => driver.createPTableV2(def));
+		}
+	});
+}
+/**
+* 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.
+*/
+function wrapDataDriver(driver, recorder, registry) {
+	const source = driver;
+	return Object.assign(Object.create(driver), {
+		async getShape(handle, ...rest) {
+			const origin = registry.get(handle);
+			return await span(recorder, "getShape", {
+				handle: shortHandle(handle),
+				joinSeq: origin?.seq
+			}, async () => {
+				const shape = await source.getShape(handle, ...rest);
+				registry.observe(handle, {
+					rows: shape?.rows,
+					columns: shape?.columns
+				});
+				return {
+					result: shape,
+					detail: {
+						rows: shape?.rows,
+						columns: shape?.columns
+					}
+				};
+			});
+		},
+		async getData(handle, columnIndices, range, ...rest) {
+			const origin = registry.get(handle);
+			return await span(recorder, "getData", {
+				handle: shortHandle(handle),
+				joinSeq: origin?.seq,
+				columnCount: columnIndices?.length,
+				range: range ? {
+					offset: range.offset,
+					length: range.length
+				} : null,
+				unbounded: !range,
+				tableRows: origin?.observed?.rows
+			}, async () => {
+				const data = await source.getData(handle, columnIndices, range, ...rest);
+				return {
+					result: data,
+					detail: { returnedBytes: vectorsBytes(data) }
+				};
+			});
+		},
+		async calculateTableData(handle, request, ...rest) {
+			return await span(recorder, "calculateTableData", {
+				handle: shortHandle(handle),
+				def: digestDef("PTableDef", request)
+			}, async () => {
+				const data = await source.calculateTableData(handle, request, ...rest);
+				const vectors = (data ?? []).map((column) => column?.data);
+				return {
+					result: data,
+					detail: {
+						columns: data?.length,
+						returnedBytes: vectorsBytes(vectors)
+					}
+				};
+			});
+		},
+		async getUniqueValues(handle, request, ...rest) {
+			return await span(recorder, "getUniqueValues", {
+				handle: shortHandle(handle),
+				request: redact(request).value
+			}, async () => {
+				const response = await source.getUniqueValues(handle, request, ...rest);
+				return {
+					result: response,
+					detail: {
+						uniqueValues: vectorLength(response?.values),
+						overflow: response?.overflow,
+						returnedBytes: vectorsBytes([response?.values])
+					}
+				};
+			});
+		},
+		async findColumns(handle, request, ...rest) {
+			return await span(recorder, "findColumns", {
+				handle: shortHandle(handle),
+				request: redact(request).value
+			}, async () => {
+				const response = await source.findColumns(handle, request, ...rest);
+				return {
+					result: response,
+					detail: { hits: response?.hits?.length }
+				};
+			});
+		}
+	});
+}
+/**
+* Records one block model render.
+*
+* `getStats` exposes the middle layer's own sandbox accounting, whose
+* serialisation byte counts show how much data the model moved across the
+* QuickJS boundary — the model-layer memory cost that no driver call reports.
+*/
+async function recordModelRender(recorder, info, fn) {
+	if (!recorder) return await fn();
+	const { getStats, ...plain } = info;
+	const begin = recorder.event("render-begin", {
+		...plain,
+		mem: recorder.memorySnapshot()
+	});
+	const startedAt = performance.now();
+	try {
+		const result = await fn();
+		recorder.event("render-end", {
+			begin,
+			...plain,
+			ms: round(performance.now() - startedAt),
+			stats: getStats?.(),
+			mem: recorder.memorySnapshot()
+		});
+		return result;
+	} catch (error) {
+		recorder.event("render-error", {
+			begin,
+			...plain,
+			ms: round(performance.now() - startedAt),
+			error: describeError(error),
+			mem: recorder.memorySnapshot()
+		});
+		throw error;
+	}
+}
+/** Synchronous variant, for a render that is not driven by a promise. */
+function recordModelRenderSync(recorder, info, fn) {
+	if (!recorder) return fn();
+	const { getStats, ...plain } = info;
+	const begin = recorder.event("render-begin", {
+		...plain,
+		mem: recorder.memorySnapshot()
+	});
+	const startedAt = performance.now();
+	try {
+		const result = fn();
+		recorder.event("render-end", {
+			begin,
+			...plain,
+			ms: round(performance.now() - startedAt),
+			stats: getStats?.(),
+			mem: recorder.memorySnapshot()
+		});
+		return result;
+	} catch (error) {
+		recorder.event("render-error", {
+			begin,
+			...plain,
+			ms: round(performance.now() - startedAt),
+			error: describeError(error),
+			mem: recorder.memorySnapshot()
+		});
+		throw error;
+	}
+}
+function record(recorder, registry, handleOf, op, kind, def, call) {
+	let digest;
+	try {
+		digest = digestDef(kind, def);
+	} catch (error) {
+		digest = { digestFailed: describeError(error) };
+	}
+	const seq = recorder.event(`${op}-begin`, {
+		def: digest,
+		mem: recorder.memorySnapshot()
+	});
+	const startedAt = performance.now();
+	let result;
+	try {
+		result = call();
+	} catch (error) {
+		recorder.event(`${op}-error`, {
+			begin: seq,
+			ms: round(performance.now() - startedAt),
+			error: describeError(error),
+			mem: recorder.memorySnapshot()
+		});
+		throw error;
+	}
+	const handle = handleOf(result);
+	registry.put(handle, {
+		seq,
+		op
+	});
+	recorder.event(`${op}-end`, {
+		begin: seq,
+		ms: round(performance.now() - startedAt),
+		handle: shortHandle(handle),
+		mem: recorder.memorySnapshot()
+	});
+	return result;
+}
+async function span(recorder, op, info, fn) {
+	const begin = recorder.event(`${op}-begin`, {
+		...info,
+		mem: recorder.memorySnapshot()
+	});
+	const startedAt = performance.now();
+	try {
+		const { result, detail } = await fn();
+		recorder.event(`${op}-end`, {
+			begin,
+			ms: round(performance.now() - startedAt),
+			...detail,
+			mem: recorder.memorySnapshot()
+		});
+		return result;
+	} catch (error) {
+		recorder.event(`${op}-error`, {
+			begin,
+			ms: round(performance.now() - startedAt),
+			error: describeError(error),
+			mem: recorder.memorySnapshot()
+		});
+		throw error;
+	}
+}
+/** Accepts both a bare handle string and a pool entry wrapping one. */
+function defaultHandleOf(result) {
+	if (typeof result === "string") return result;
+	const key = result?.key;
+	return typeof key === "string" ? key : String(result);
+}
+function vectorsBytes(vectors) {
+	let bytes = 0;
+	for (const vector of vectors ?? []) {
+		const data = vector?.data;
+		if (!data) continue;
+		const byteLength = data.byteLength;
+		if (typeof byteLength === "number") bytes += byteLength;
+		else if (Array.isArray(data)) bytes += sampledArrayBytes(data);
+		const isNA = vector.isNA;
+		if (typeof isNA?.byteLength === "number") bytes += isNA.byteLength;
+	}
+	return bytes;
+}
+function vectorLength(vector) {
+	const data = vector?.data;
+	return typeof data?.length === "number" ? data.length : void 0;
+}
+function sampledArrayBytes(data) {
+	const sampleSize = Math.min(data.length, 32);
+	if (sampleSize === 0) return 0;
+	let sampled = 0;
+	for (let i = 0; i < sampleSize; i++) {
+		const value = data[Math.floor(i * data.length / sampleSize)];
+		sampled += typeof value === "string" ? value.length * 2 + 24 : 8;
+	}
+	return Math.round(sampled / sampleSize * data.length);
+}
+function shortHandle(handle) {
+	return typeof handle === "string" ? handle.slice(0, 24) : String(handle);
+}
+function describeError(error) {
+	return String(error?.message ?? error);
+}
+function round(value) {
+	return Math.round(value * 100) / 100;
+}
+//#endregion
+export { createHandleRegistry, recordModelRender, recordModelRenderSync, wrapDataDriver, wrapModelDriver };
+
+//# sourceMappingURL=instrument.js.map

package/dist/instrument.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrument.js","names":[],"sources":["../src/instrument.ts"],"sourcesContent":["import type { PColumn, PTableDef, PTableDefV2 } from \"@milaboratories/pl-model-common\";\nimport { digestDef, type DefDigest, type DefKind } from \"./digest\";\nimport { redact } from \"./redact\";\nimport type { Recorder } from \"./recorder\";\n\n/**\n * Wrappers for the seams the model layer passes through.\n *\n * Every operation writes a begin record and an end record. That pairing is what\n * makes a crash legible: when the process dies mid-operation the end record is\n * missing, so the log names the exact call that was running when memory ran out\n * — the question a post-crash report has to answer.\n *\n * The wrappers are structural rather than tied to one driver interface, because\n * the same three creation methods appear twice with different return types: the\n * model-facing driver hands back a bare handle, the internal one hands back a\n * pool entry.\n */\n\nexport type HandleOrigin = {\n  /** Sequence number of the record holding the definition. */\n  seq: number;\n  op: string;\n  observed?: { rows?: number; columns?: number };\n};\n\nexport type HandleRegistry = {\n  put(handle: string, origin: HandleOrigin): void;\n  get(handle: string): HandleOrigin | undefined;\n  observe(handle: string, observed: { rows?: number; columns?: number }): void;\n};\n\nexport type ModelDriverLike<H> = {\n  createPFrame(def: never): H;\n  createPTable(def: never): H;\n  createPTableV2(def: never): H;\n};\n\nexport type RenderInfo = {\n  blockId?: string;\n  block?: string;\n  blockVersion?: string;\n  key?: string;\n  argsHash?: string;\n  /** Which lambda of the block's model is being rendered. */\n  lambda?: string;\n  /** Nth resumption of a deferred render, counted from one. */\n  recalculation?: number;\n  /** Read after the render, so sandbox counters cover the whole call. */\n  getStats?: () => unknown;\n  /** Any further context the call site wants on the record. */\n  [key: string]: unknown;\n};\n\n/** Maps driver handles back to the join that produced them. */\nexport function createHandleRegistry(limit = 512): HandleRegistry {\n  const map = new Map<string, HandleOrigin>();\n  return {\n    put(handle, origin) {\n      if (map.size >= limit) {\n        const oldest = map.keys().next();\n        if (!oldest.done) map.delete(oldest.value);\n      }\n      map.set(handle, origin);\n    },\n    get(handle) {\n      return map.get(handle);\n    },\n    observe(handle, observed) {\n      const origin = map.get(handle);\n      if (origin) origin.observed = observed;\n    },\n  };\n}\n\n/**\n * Wraps the driver that block models call to build frames and tables.\n *\n * Records the redacted join tree and its structural findings, then remembers\n * which handle came from which join so later data calls can be attributed back\n * to the definition that caused them.\n */\nexport function wrapModelDriver<D extends ModelDriverLike<unknown>>(\n  driver: D,\n  recorder: Recorder,\n  registry: HandleRegistry,\n  handleOf: (result: unknown) => string = defaultHandleOf,\n): D {\n  const wrapped = {\n    createPFrame(def: readonly PColumn<unknown>[]) {\n      return record(recorder, registry, handleOf, \"createPFrame\", \"PFrameDef\", def, () =>\n        (driver.createPFrame as (d: unknown) => unknown)(def),\n      );\n    },\n    createPTable(def: PTableDef<PColumn<unknown>>) {\n      return record(recorder, registry, handleOf, \"createPTable\", \"PTableDef\", def, () =>\n        (driver.createPTable as (d: unknown) => unknown)(def),\n      );\n    },\n    createPTableV2(def: PTableDefV2<PColumn<unknown>>) {\n      return record(recorder, registry, handleOf, \"createPTableV2\", \"PTableDefV2\", def, () =>\n        (driver.createPTableV2 as (d: unknown) => unknown)(def),\n      );\n    },\n  };\n  // The three creation methods are replaced and everything else is inherited,\n  // so the wrapper satisfies whichever driver interface the caller holds.\n  return Object.assign(Object.create(driver as object) as D, wrapped);\n}\n\n/**\n * Wraps the asynchronous data-access driver.\n *\n * Adds the observed table shape, the size of what crossed back into JavaScript,\n * and the amplification between input and output rows — the empirical\n * counterpart to the structural findings taken from the join tree.\n */\nexport function wrapDataDriver<D extends object>(\n  driver: D,\n  recorder: Recorder,\n  registry: HandleRegistry,\n): D {\n  const source = driver as unknown as {\n    getShape(handle: string, ...rest: unknown[]): Promise<{ rows: number; columns: number }>;\n    getData(\n      handle: string,\n      columnIndices: number[],\n      range?: { offset: number; length: number },\n      ...rest: unknown[]\n    ): Promise<unknown[]>;\n    calculateTableData(handle: string, request: unknown, ...rest: unknown[]): Promise<unknown[]>;\n    getUniqueValues(\n      handle: string,\n      request: unknown,\n      ...rest: unknown[]\n    ): Promise<{ values?: { data?: unknown }; overflow?: boolean }>;\n    findColumns(\n      handle: string,\n      request: unknown,\n      ...rest: unknown[]\n    ): Promise<{ hits?: unknown[] }>;\n  };\n\n  const wrapped = {\n    async getShape(handle: string, ...rest: unknown[]) {\n      const origin = registry.get(handle);\n      return await span(\n        recorder,\n        \"getShape\",\n        { handle: shortHandle(handle), joinSeq: origin?.seq },\n        async () => {\n          const shape = await source.getShape(handle, ...rest);\n          registry.observe(handle, { rows: shape?.rows, columns: shape?.columns });\n          // How much this join amplified is judged in the analyzer, which can\n          // read the definition this handle came from without repeating the\n          // work here, on the hot path.\n          return { result: shape, detail: { rows: shape?.rows, columns: shape?.columns } };\n        },\n      );\n    },\n\n    async getData(\n      handle: string,\n      columnIndices: number[],\n      range?: { offset: number; length: number },\n      ...rest: unknown[]\n    ) {\n      const origin = registry.get(handle);\n      return await span(\n        recorder,\n        \"getData\",\n        {\n          handle: shortHandle(handle),\n          joinSeq: origin?.seq,\n          columnCount: columnIndices?.length,\n          range: range ? { offset: range.offset, length: range.length } : null,\n          // A fetch with no range pulls the whole table into the JS heap, which\n          // on a large table is an out-of-memory condition by itself.\n          unbounded: !range,\n          tableRows: origin?.observed?.rows,\n        },\n        async () => {\n          const data = await source.getData(handle, columnIndices, range, ...rest);\n          return { result: data, detail: { returnedBytes: vectorsBytes(data) } };\n        },\n      );\n    },\n\n    async calculateTableData(handle: string, request: unknown, ...rest: unknown[]) {\n      return await span(\n        recorder,\n        \"calculateTableData\",\n        { handle: shortHandle(handle), def: digestDef(\"PTableDef\", request) },\n        async () => {\n          const data = await source.calculateTableData(handle, request, ...rest);\n          const vectors = (data ?? []).map((column) => (column as { data?: unknown })?.data);\n          return {\n            result: data,\n            detail: { columns: data?.length, returnedBytes: vectorsBytes(vectors) },\n          };\n        },\n      );\n    },\n\n    // Both of these reach the engine as well, and a filter that matches most of\n    // a large axis is a plausible place to run out of memory. The request is\n    // recorded redacted: axis identity survives, filter values become hashes.\n    async getUniqueValues(handle: string, request: unknown, ...rest: unknown[]) {\n      return await span(\n        recorder,\n        \"getUniqueValues\",\n        { handle: shortHandle(handle), request: redact(request).value },\n        async () => {\n          const response = await source.getUniqueValues(handle, request, ...rest);\n          return {\n            result: response,\n            detail: {\n              uniqueValues: vectorLength(response?.values),\n              overflow: response?.overflow,\n              returnedBytes: vectorsBytes([response?.values]),\n            },\n          };\n        },\n      );\n    },\n\n    async findColumns(handle: string, request: unknown, ...rest: unknown[]) {\n      return await span(\n        recorder,\n        \"findColumns\",\n        { handle: shortHandle(handle), request: redact(request).value },\n        async () => {\n          const response = await source.findColumns(handle, request, ...rest);\n          return { result: response, detail: { hits: response?.hits?.length } };\n        },\n      );\n    },\n  };\n\n  return Object.assign(Object.create(driver) as D, wrapped);\n}\n\n/**\n * Records one block model render.\n *\n * `getStats` exposes the middle layer's own sandbox accounting, whose\n * serialisation byte counts show how much data the model moved across the\n * QuickJS boundary — the model-layer memory cost that no driver call reports.\n */\nexport async function recordModelRender<T>(\n  recorder: Recorder | undefined,\n  info: RenderInfo,\n  fn: () => Promise<T>,\n): Promise<T> {\n  if (!recorder) return await fn();\n  const { getStats, ...plain } = info;\n  const begin = recorder.event(\"render-begin\", { ...plain, mem: recorder.memorySnapshot() });\n  const startedAt = performance.now();\n  try {\n    const result = await fn();\n    recorder.event(\"render-end\", {\n      begin,\n      ...plain,\n      ms: round(performance.now() - startedAt),\n      stats: getStats?.(),\n      mem: recorder.memorySnapshot(),\n    });\n    return result;\n  } catch (error) {\n    recorder.event(\"render-error\", {\n      begin,\n      ...plain,\n      ms: round(performance.now() - startedAt),\n      error: describeError(error),\n      mem: recorder.memorySnapshot(),\n    });\n    throw error;\n  }\n}\n\n/** Synchronous variant, for a render that is not driven by a promise. */\nexport function recordModelRenderSync<T>(\n  recorder: Recorder | undefined,\n  info: RenderInfo,\n  fn: () => T,\n): T {\n  if (!recorder) return fn();\n  const { getStats, ...plain } = info;\n  const begin = recorder.event(\"render-begin\", { ...plain, mem: recorder.memorySnapshot() });\n  const startedAt = performance.now();\n  try {\n    const result = fn();\n    recorder.event(\"render-end\", {\n      begin,\n      ...plain,\n      ms: round(performance.now() - startedAt),\n      stats: getStats?.(),\n      mem: recorder.memorySnapshot(),\n    });\n    return result;\n  } catch (error) {\n    recorder.event(\"render-error\", {\n      begin,\n      ...plain,\n      ms: round(performance.now() - startedAt),\n      error: describeError(error),\n      mem: recorder.memorySnapshot(),\n    });\n    throw error;\n  }\n}\n\n// Internals\n\nfunction record<R>(\n  recorder: Recorder,\n  registry: HandleRegistry,\n  handleOf: (result: unknown) => string,\n  op: string,\n  kind: DefKind,\n  def: unknown,\n  call: () => R,\n): R {\n  let digest: DefDigest | { digestFailed: string };\n  try {\n    digest = digestDef(kind, def);\n  } catch (error) {\n    // Diagnostics must never be the reason a join fails to build.\n    digest = { digestFailed: describeError(error) };\n  }\n  // A creation call is synchronous but not free: it hands the definition to the\n  // native engine, which can allocate. It gets a begin/end pair like any other\n  // operation, so a death inside it is attributed to it and not to the render\n  // around it.\n  const seq = recorder.event(`${op}-begin`, { def: digest, mem: recorder.memorySnapshot() });\n  const startedAt = performance.now();\n\n  let result: R;\n  try {\n    result = call();\n  } catch (error) {\n    recorder.event(`${op}-error`, {\n      begin: seq,\n      ms: round(performance.now() - startedAt),\n      error: describeError(error),\n      mem: recorder.memorySnapshot(),\n    });\n    throw error;\n  }\n\n  const handle = handleOf(result);\n  registry.put(handle, { seq, op });\n  recorder.event(`${op}-end`, {\n    begin: seq,\n    ms: round(performance.now() - startedAt),\n    handle: shortHandle(handle),\n    mem: recorder.memorySnapshot(),\n  });\n  return result;\n}\n\nasync function span<T>(\n  recorder: Recorder,\n  op: string,\n  info: Record<string, unknown>,\n  fn: () => Promise<{ result: T; detail: Record<string, unknown> }>,\n): Promise<T> {\n  const begin = recorder.event(`${op}-begin`, { ...info, mem: recorder.memorySnapshot() });\n  const startedAt = performance.now();\n  try {\n    const { result, detail } = await fn();\n    recorder.event(`${op}-end`, {\n      begin,\n      ms: round(performance.now() - startedAt),\n      ...detail,\n      mem: recorder.memorySnapshot(),\n    });\n    return result;\n  } catch (error) {\n    recorder.event(`${op}-error`, {\n      begin,\n      ms: round(performance.now() - startedAt),\n      error: describeError(error),\n      mem: recorder.memorySnapshot(),\n    });\n    throw error;\n  }\n}\n\n/** Accepts both a bare handle string and a pool entry wrapping one. */\nfunction defaultHandleOf(result: unknown): string {\n  if (typeof result === \"string\") return result;\n  const key = (result as { key?: unknown } | null)?.key;\n  return typeof key === \"string\" ? key : String(result);\n}\n\nfunction vectorsBytes(vectors: unknown[]): number {\n  let bytes = 0;\n  for (const vector of vectors ?? []) {\n    const data = (vector as { data?: unknown; isNA?: { byteLength?: number } } | null)?.data;\n    if (!data) continue;\n    const byteLength = (data as { byteLength?: number }).byteLength;\n    if (typeof byteLength === \"number\") {\n      bytes += byteLength;\n    } else if (Array.isArray(data)) {\n      // String and Bytes columns arrive as plain arrays, and those are the ones\n      // that actually threaten the JS heap, so they are sampled not skipped.\n      bytes += sampledArrayBytes(data);\n    }\n    const isNA = (vector as { isNA?: { byteLength?: number } }).isNA;\n    if (typeof isNA?.byteLength === \"number\") bytes += isNA.byteLength;\n  }\n  return bytes;\n}\n\nfunction vectorLength(vector: unknown): number | undefined {\n  const data = (vector as { data?: { length?: number } } | undefined)?.data;\n  return typeof data?.length === \"number\" ? data.length : undefined;\n}\n\nfunction sampledArrayBytes(data: unknown[]): number {\n  const sampleSize = Math.min(data.length, 32);\n  if (sampleSize === 0) return 0;\n  let sampled = 0;\n  for (let i = 0; i < sampleSize; i++) {\n    const value = data[Math.floor((i * data.length) / sampleSize)];\n    sampled += typeof value === \"string\" ? value.length * 2 + 24 : 8;\n  }\n  return Math.round((sampled / sampleSize) * data.length);\n}\n\nfunction shortHandle(handle: string): string {\n  return typeof handle === \"string\" ? handle.slice(0, 24) : String(handle);\n}\n\nfunction describeError(error: unknown): string {\n  return String((error as { message?: unknown } | null)?.message ?? error);\n}\n\nfunction round(value: number): number {\n  return Math.round(value * 100) / 100;\n}\n"],"mappings":"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"}

package/dist/recorder.d.ts

@@ -0,0 +1,82 @@
+import { FlightRecord, MemorySnapshot } from "./events.js";
+//#region src/recorder.d.ts
+export type RecorderOptions = {
+  /** Directory holding flight logs; created if absent. */
+  dir: string;
+  /** Which part of the app is recording, e.g. `middle-layer`. */
+  role?: string;
+  /** Free-form context stored in the session header (app version, project id). */
+  meta?: Record<string, unknown>;
+  /** Log is rotated past this size so the tail, which explains the crash, survives. */
+  maxFileBytes?: number;
+  /**
+   * Session id assigned by a supervising parent, so the crash marker the parent
+   * writes names this session with certainty rather than by inference.
+   * Generated when absent.
+   */
+  sessionId?: string;
+};
+export type Recorder = {
+  readonly sessionId: string;
+  readonly file: string;
+  /** Appends one record and returns its sequence number. Never throws. */
+  event(type: string, payload?: Record<string, unknown>): number;
+  /** Memory reading for the calling thread; `rss` is process-wide. */
+  memorySnapshot(): MemorySnapshot;
+  /** Writes the terminating record. Its absence is how a crash is detected. */
+  close(reason?: string): void;
+};
+export type SessionFileInfo = {
+  file: string;
+  mtimeMs: number;
+  bytes: number;
+  /** True when the log has no terminating record, i.e. the process died. */
+  crashed: boolean;
+};
+export type ParsedSession = {
+  file: string;
+  records: FlightRecord[];
+  /** True when the last line was cut mid-write by the kill. */
+  truncatedTail: boolean;
+};
+/**
+ * Opens a flight 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.
+ */
+export declare function openRecorder(options: RecorderOptions): 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.
+ */
+export declare function startSelfSampler(recorder: Recorder, intervalMs?: number): () => void;
+/** Flight logs in a directory, newest first, each flagged as crashed or clean. */
+export declare function listSessions(dir: string): SessionFileInfo[];
+/**
+ * Parses a flight log, tolerating a final line cut short by a hard kill.
+ *
+ * A rotated session spans two files: the parked `.1` segment holds the original
+ * header and the earlier operations, the active file holds the tail. Both are
+ * read so begin records in one segment can be paired with end records in the
+ * other; sequence numbers run across the boundary.
+ */
+export declare function readSession(file: string): ParsedSession;
+/**
+ * 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.
+ */
+export declare function newSessionId(): string;
+/** Session id embedded in a flight log's file name. */
+export declare function sessionIdFromFile(file: string): string;
+//#endregion
+//# sourceMappingURL=recorder.d.ts.map

package/dist/recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.d.ts","names":[],"sources":["../src/recorder.ts"],"mappings":";;YAcY;;EAEV;;EAEA;;EAEA,OAAO;;EAEP;;;;;;EAMA;;YAGU;WACD;WACA;;EAET,MAAM,cAAc,UAAU;;EAE9B,kBAAkB;;EAElB,MAAM;;YAGI;EACV;EACA;EACA;;EAEA;;YAGU;EACV;EACA,SAAS;;EAET;;;;;;;;;;;wBAYc,aAAa,SAAS,kBAAkB;;;;;;;;;wBAmFxC,iBAAiB,UAAU,UAAU;;wBAerC,aAAa,cAAc;;;;;;;;;wBAyB3B,YAAY,eAAe;;;;;;;wBAgC3B;;wBAWA,kBAAkB"}