@milaboratories/pl-flight-recorder 0.2.0

package/dist/data_summary.js

@@ -0,0 +1,73 @@
+//#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)
+	};
+	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
+	};
+}
+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\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 { kind: \"inline\", entries: data.length, approxBytes: approxInlineBytes(data) };\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// 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":";AA0BA,SAAgB,cAAc,MAA4B;CACxD,IAAI,SAAS,QAAQ,SAAS,KAAA,GAAW,OAAO,EAAE,MAAM,SAAS;CACjE,IAAI,MAAM,QAAQ,IAAI,GAEpB,OAAO;EAAE,MAAM;EAAU,SAAS,KAAK;EAAQ,aAAa,kBAAkB,IAAI;CAAE;CAEtF,IAAI,OAAO,SAAS,UAAU,OAAO,EAAE,MAAM,OAAO,KAAK;CAEzD,MAAM,OAAO;CACb,QAAQ,KAAK,MAAb;EACE,KAAK,QACH,OAAO;GACL,MAAM;GACN,WAAW,SAAS,KAAK,SAAS;GAClC,SAAS,UAAU,KAAK,IAAI;EAC9B;EACF,KAAK;EACL,KAAK,qBACH,OAAO;GACL,MAAM,KAAK;GACX,oBAAoB,SAAS,KAAK,kBAAkB;GACpD,OAAO,UAAU,KAAK,KAAK;EAC7B;EACF,KAAK,sBACH,OAAO,iBAAiB,IAAI;EAC9B,SACE,OAAO,EAAE,MAAM,KAAK,QAAQ,WAAW,IAAI,EAAE;CACjD;AACF;AAIA,SAAS,iBAAiB,MAA+C;CACvE,MAAM,QAAQ,OAAO,OAAQ,KAAK,SAAS,CAAC,CAA6B;CACzE,IAAI,OAAO;CACX,IAAI,QAAQ;CACZ,IAAI,YAAY;CAChB,KAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,QACJ,MACC;EACH,IAAI,CAAC,OAAO;EACZ;EACA,IAAI,OAAO,MAAM,iBAAiB,UAAU,QAAQ,MAAM;EAC1D,IAAI,MAAM,MAAM,UAAU,MAAM,KAAK,UAAU,KAAK,IAAI,MAAM,KAAK,QAAQ,CAAC,CAAC;CAC/E;CACA,OAAO;EACL,MAAM;EACN,oBAAoB,SAAS,KAAK,kBAAkB;EACpD,OAAO,MAAM;EACb,gBAAgB;EAChB,MAAM,YAAY,IAAI,OAAO,KAAA;EAC7B,OAAO,YAAY,IAAI,QAAQ,KAAA;CACjC;AACF;AAIA,SAAS,kBAAkB,QAA2B;CACpD,MAAM,aAAa,KAAK,IAAI,OAAO,QAAQ,EAAE;CAC7C,IAAI,eAAe,GAAG,OAAO;CAC7B,IAAI,QAAQ;CACZ,KAAK,IAAI,IAAI,GAAG,IAAI,YAAY,KAAK;EACnC,MAAM,QAAQ,OAAO,KAAK,MAAO,IAAI,OAAO,SAAU,UAAU;EAChE,SAAS,KAAK,UAAU,SAAS,IAAI,CAAC,EAAE,UAAU;CACpD;CACA,OAAO,KAAK,MAAO,QAAQ,aAAc,OAAO,MAAM;AACxD;AAEA,SAAS,UAAU,OAAoC;CACrD,OAAO,SAAS,OAAO,UAAU,WAAW,OAAO,KAAK,KAAK,CAAC,CAAC,SAAS,KAAA;AAC1E;AAEA,SAAS,SAAS,OAAoC;CACpD,OAAO,OAAO,UAAU,WAAW,QAAQ,KAAA;AAC7C;AAEA,SAAS,WAAW,OAAuB;CACzC,OAAQ,MAA8C,aAAa,QAAQ;AAC7E;AAEA,SAAS,IAAI,QAA0B;CACrC,OAAO,OAAO,QAAQ,KAAK,UAAU,MAAM,OAAO,CAAC;AACrD"}

package/dist/digest.d.ts

@@ -0,0 +1,28 @@
+import { RedactionStats } from "./redact.js";
+//#region src/digest.d.ts
+/**
+ * What a definition record carries.
+ *
+ * The definition is recorded structurally (see `redact`) rather than through a
+ * hand-written digest per definition type. Structural rules are not run here:
+ * they belong to the analyzer, so nothing is computed on the hot path and the
+ * rules can be revised against logs that already exist.
+ */
+export declare const REDACTION: {
+  readonly kept: readonly ["definition shape", "column and axis names", "value types", "axis domains", "filter operators", "row, byte and partition counts"];
+  readonly hashed: readonly ["filter reference values", "annotation values", "column ids", "every other string"];
+  readonly dropped: readonly ["cell values", "inline column payloads", "partition keys"];
+};
+export type DefKind = "PTableDef" | "PTableDefV2" | "PFrameDef";
+export type DefDigest = {
+  kind: DefKind;
+  /** Redacted definition, same shape as the original. */
+  def: unknown;
+  redaction: RedactionStats & {
+    bytes: number;
+  };
+};
+/** Records one definition: redacted, measured, and tagged with its API shape. */
+export declare function digestDef(kind: DefKind, def: unknown): DefDigest;
+//#endregion
+//# sourceMappingURL=digest.d.ts.map

package/dist/digest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"digest.d.ts","names":[],"sources":["../src/digest.ts"],"mappings":";;;;;;;;;;qBAWa;WACX;WAQA;WACA;;YAGU;YAEA;EACV,MAAM;;EAEN;EACA,WAAW;IAAmB;;;;wBAIhB,UAAU,MAAM,SAAS,eAAe"}

package/dist/digest.js

@@ -0,0 +1,55 @@
+import { redact } from "./redact.js";
+//#region src/digest.ts
+/**
+* What a definition record carries.
+*
+* The definition is recorded structurally (see `redact`) rather than through a
+* hand-written digest per definition type. Structural rules are not run here:
+* they belong to the analyzer, so nothing is computed on the hot path and the
+* rules can be revised against logs that already exist.
+*/
+const REDACTION = {
+	kept: [
+		"definition shape",
+		"column and axis names",
+		"value types",
+		"axis domains",
+		"filter operators",
+		"row, byte and partition counts"
+	],
+	hashed: [
+		"filter reference values",
+		"annotation values",
+		"column ids",
+		"every other string"
+	],
+	dropped: [
+		"cell values",
+		"inline column payloads",
+		"partition keys"
+	]
+};
+/** 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 { REDACTION, 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 const REDACTION = {\n  kept: [\n    \"definition shape\",\n    \"column and axis names\",\n    \"value types\",\n    \"axis domains\",\n    \"filter operators\",\n    \"row, byte and partition counts\",\n  ],\n  hashed: [\"filter reference values\", \"annotation values\", \"column ids\", \"every other string\"],\n  dropped: [\"cell values\", \"inline column payloads\", \"partition keys\"],\n} as const;\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":";;;;;;;;;;AAWA,MAAa,YAAY;CACvB,MAAM;EACJ;EACA;EACA;EACA;EACA;EACA;CACF;CACA,QAAQ;EAAC;EAA2B;EAAqB;EAAc;CAAoB;CAC3F,SAAS;EAAC;EAAe;EAA0B;CAAgB;AACrE;;AAYA,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,89 @@
+//#region src/events.d.ts
+/**
+ * Record types written to a flight 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 FlightRecordBase} 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;
+};
+export type FlightRecordBase = {
+  /** 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 FlightRecord = FlightRecordBase & {
+  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 = FlightRecordBase & {
+  type: "mem-sampler";
+  rss: number;
+  peakRss: number;
+  freeMemory: number;
+  totalMemory: number;
+};
+/** 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 flight 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;
+};
+export type CrashReason = "js-heap-out-of-memory" | "killed-by-os" | "abort-or-fatal-allocation-failure" | "worker-exit" | "nonzero-exit" | "unknown";
+export declare const SESSION_RECORD = "session";
+export declare const SESSION_END_RECORD = "session-end";
+export declare const FLIGHT_FILE_PREFIX = "flight";
+export declare const SAMPLER_FILE_PREFIX = "mem";
+export declare const CRASH_FILE_PREFIX = "crash";
+//#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;;YAGU;;EAEV;;EAEA;;EAEA;EACA;;YAGU,eAAe;EACzB,MAAM;;EAEN;GACC;;;YAIS;EACV;EACA;EACA;EACA;EACA;EACA;EACA;;;YAIU,gBAAgB;EAC1B;EACA;EACA;EACA;EACA;;;YAIU;EACV;EACA;;;;;;;EAOA;;;;;;EAMA;;EAEA;EACA,QAAQ;EACR;EACA;EACA;EACA;EACA;EACA;;YAGU;qBAQC;qBAGA;qBACA;qBACA;qBACA"}

package/dist/events.js

@@ -0,0 +1,12 @@
+//#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 FLIGHT_FILE_PREFIX = "flight";
+const SAMPLER_FILE_PREFIX = "mem";
+const CRASH_FILE_PREFIX = "crash";
+//#endregion
+export { CRASH_FILE_PREFIX, FLIGHT_FILE_PREFIX, MEM_BASELINE_RECORD, SAMPLER_FILE_PREFIX, SESSION_END_RECORD, 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 flight 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 FlightRecordBase} 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\nexport type FlightRecordBase = {\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 FlightRecord = FlightRecordBase & {\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 = FlightRecordBase & {\n  type: \"mem-sampler\";\n  rss: number;\n  peakRss: number;\n  freeMemory: number;\n  totalMemory: number;\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 flight 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\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 FLIGHT_FILE_PREFIX = \"flight\";\nexport const SAMPLER_FILE_PREFIX = \"mem\";\nexport const CRASH_FILE_PREFIX = \"crash\";\n"],"mappings":";AA+FA,MAAa,iBAAiB;;AAE9B,MAAa,sBAAsB;AACnC,MAAa,qBAAqB;AAClC,MAAa,qBAAqB;AAClC,MAAa,sBAAsB;AACnC,MAAa,oBAAoB"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import { CRASH_FILE_PREFIX, CrashMarker, CrashReason, FLIGHT_FILE_PREFIX, FlightRecord, MemorySnapshot, SAMPLER_FILE_PREFIX, SESSION_END_RECORD, SESSION_RECORD, SamplerRecord, SessionEnvironment } from "./events.js";
+import { ParsedSession, Recorder, RecorderOptions, SessionFileInfo, listSessions, newSessionId, openRecorder, readSession, sessionIdFromFile, startSelfSampler } from "./recorder.js";
+import { MemorySampler, MemorySamplerOptions, startMemorySampler } from "./sampler.js";
+import { HandleOrigin, HandleRegistry, RenderInfo, createHandleRegistry, recordModelRender, recordModelRenderSync, wrapDataDriver, wrapModelDriver } from "./instrument.js";
+import { FLIGHT_DIR_ENV, FLIGHT_SESSION_ENV, FlightSession, FlightSessionOptions, openFlightSession } from "./session.js";
+import { CrashMarkerInput, SuperviseOptions, SupervisedWorker, readCrashMarkers, superviseWorker, writeCrashMarker } from "./supervisor.js";
+import { DataSummary, summarizeData } from "./data_summary.js";
+import { COUNTED_KEYS, HashedString, RedactOptions, RedactionStats, SCHEMA_KEYS, SCHEMA_SUBTREE_KEYS, SUMMARISED_KEYS, hashString, isHashedString, redact } from "./redact.js";
+import { DefDigest, DefKind, REDACTION, digestDef } from "./digest.js";
+import { AxisDescriptor, FindingSeverity, JoinShape, StructuralFinding, axesUnder, axisKey, axisNameKey, inputRowsMax, isJoinNode, joinChildren, joinShapes, structuralFindings } from "./rules.js";
+import { Finding, MemoryAnalysis, OperationSummary, RenderSummary, SessionAnalysis, THRESHOLDS, Verdict, analyzeLatest, analyzeSession, formatBytes, formatCount } from "./analyze.js";
+import { renderReport } from "./report.js";
+export { type AxisDescriptor, COUNTED_KEYS, CRASH_FILE_PREFIX, type CrashMarker, type CrashMarkerInput, type CrashReason, type DataSummary, type DefDigest, type DefKind, FLIGHT_DIR_ENV, FLIGHT_FILE_PREFIX, FLIGHT_SESSION_ENV, type Finding, type FindingSeverity, type FlightRecord, type FlightSession, type FlightSessionOptions, type HandleOrigin, type HandleRegistry, type HashedString, type JoinShape, type MemoryAnalysis, type MemorySampler, type MemorySamplerOptions, type MemorySnapshot, type OperationSummary, type ParsedSession, REDACTION, type Recorder, type RecorderOptions, type RedactOptions, type RedactionStats, type RenderInfo, type RenderSummary, SAMPLER_FILE_PREFIX, SCHEMA_KEYS, SCHEMA_SUBTREE_KEYS, SESSION_END_RECORD, SESSION_RECORD, SUMMARISED_KEYS, type SamplerRecord, type SessionAnalysis, type SessionEnvironment, type SessionFileInfo, type StructuralFinding, type SuperviseOptions, type SupervisedWorker, THRESHOLDS, type Verdict, analyzeLatest, analyzeSession, axesUnder, axisKey, axisNameKey, createHandleRegistry, digestDef, formatBytes, formatCount, hashString, inputRowsMax, isHashedString, isJoinNode, joinChildren, joinShapes, listSessions, newSessionId, openFlightSession, openRecorder, readCrashMarkers, readSession, recordModelRender, recordModelRenderSync, redact, renderReport, sessionIdFromFile, startMemorySampler, startSelfSampler, structuralFindings, summarizeData, superviseWorker, wrapDataDriver, wrapModelDriver, writeCrashMarker };

package/dist/index.js

@@ -0,0 +1,13 @@
+import { CRASH_FILE_PREFIX, FLIGHT_FILE_PREFIX, SAMPLER_FILE_PREFIX, SESSION_END_RECORD, SESSION_RECORD } from "./events.js";
+import { listSessions, newSessionId, openRecorder, readSession, sessionIdFromFile, startSelfSampler } from "./recorder.js";
+import { startMemorySampler } from "./sampler.js";
+import { summarizeData } from "./data_summary.js";
+import { COUNTED_KEYS, SCHEMA_KEYS, SCHEMA_SUBTREE_KEYS, SUMMARISED_KEYS, hashString, isHashedString, redact } from "./redact.js";
+import { REDACTION, digestDef } from "./digest.js";
+import { createHandleRegistry, recordModelRender, recordModelRenderSync, wrapDataDriver, wrapModelDriver } from "./instrument.js";
+import { FLIGHT_DIR_ENV, FLIGHT_SESSION_ENV, openFlightSession } from "./session.js";
+import { readCrashMarkers, superviseWorker, writeCrashMarker } from "./supervisor.js";
+import { axesUnder, axisKey, axisNameKey, inputRowsMax, isJoinNode, joinChildren, joinShapes, structuralFindings } from "./rules.js";
+import { THRESHOLDS, analyzeLatest, analyzeSession, formatBytes, formatCount } from "./analyze.js";
+import { renderReport } from "./report.js";
+export { COUNTED_KEYS, CRASH_FILE_PREFIX, FLIGHT_DIR_ENV, FLIGHT_FILE_PREFIX, FLIGHT_SESSION_ENV, REDACTION, SAMPLER_FILE_PREFIX, SCHEMA_KEYS, SCHEMA_SUBTREE_KEYS, SESSION_END_RECORD, SESSION_RECORD, SUMMARISED_KEYS, THRESHOLDS, analyzeLatest, analyzeSession, axesUnder, axisKey, axisNameKey, createHandleRegistry, digestDef, formatBytes, formatCount, hashString, inputRowsMax, isHashedString, isJoinNode, joinChildren, joinShapes, listSessions, newSessionId, openFlightSession, openRecorder, readCrashMarkers, readSession, recordModelRender, recordModelRenderSync, redact, renderReport, sessionIdFromFile, startMemorySampler, startSelfSampler, structuralFindings, summarizeData, superviseWorker, wrapDataDriver, wrapModelDriver, writeCrashMarker };

package/dist/instrument.d.ts

@@ -0,0 +1,82 @@
+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.
+ */
+export 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;
+};
+export type ModelDriverLike<H> = {
+  createPFrame(def: never): H;
+  createPTable(def: never): H;
+  createPTableV2(def: never): H;
+};
+export type RenderInfo = {
+  blockId?: string;
+  block?: string;
+  blockVersion?: 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;
+/**
+ * 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.
+ */
+export declare function recordModelRender<T>(recorder: Recorder | undefined, info: RenderInfo, fn: () => Promise<T>): Promise<T>;
+/** 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":";;;;;;;;;;;;;;;YAmBY;;EAEV;EACA;EACA;IAAa;IAAe;;;YAGlB;EACV,IAAI,gBAAgB,QAAQ;EAC5B,IAAI,iBAAiB;EACrB,QAAQ,gBAAgB;IAAY;IAAe;;;YAGzC,gBAAgB;EAC1B,aAAa,aAAa;EAC1B,aAAa,aAAa;EAC1B,eAAe,aAAa;;YAGlB;EACV;EACA;EACA;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;;;;;;;;wBAgImB,kBAAkB,GACtC,UAAU,sBACV,MAAM,YACN,UAAU,QAAQ,KACjB,QAAQ;;wBA4BK,sBAAsB,GACpC,UAAU,sBACV,MAAM,YACN,UAAU,IACT"}