@milaboratories/pl-flight-recorder 0.2.0

package/dist/report.js

@@ -0,0 +1,377 @@
+import { readSession } from "./recorder.js";
+import { REDACTION } from "./digest.js";
+import { axesUnder, axisKey, isJoinNode, joinChildren, joinShapes } from "./rules.js";
+import { formatBytes, formatCount } from "./analyze.js";
+//#region src/report.ts
+/** Renders an analysis as the markdown report a developer reads. */
+function renderReport(analysis) {
+	const { records } = readSession(analysis.file);
+	const culprit = findCulpritJoin(records, analysis);
+	const offHeap = (analysis.memory.externalGrowth ?? 0) + (analysis.memory.arrayBuffersGrowth ?? 0);
+	return [
+		"# Platforma OOM flight report",
+		"",
+		`**Verdict — ${analysis.verdict.likelyCause ?? "no rule matched"}**`,
+		"",
+		analysis.verdict.summary,
+		"",
+		table("Where it stopped", [
+			row("Outcome", analysis.verdict.outcome),
+			row("Last unfinished operation", analysis.verdict.where),
+			row("Memory region that grew", analysis.verdict.memoryRegion ?? "not classified"),
+			row("Peak RSS", formatBytes(analysis.memory.peakRss)),
+			row("RSS at last sample", formatBytes(analysis.memory.rssAtDeath)),
+			row("JS heap at last record", `${formatBytes(analysis.memory.heapUsedAtDeath)} of ${formatBytes(analysis.memory.heapLimit)}` + (analysis.memory.heapPressure ? ` (${Math.round(analysis.memory.heapPressure * 100)}%)` : "")),
+			row("Off-heap allocated (external + ArrayBuffers)", `${formatBytes(offHeap)} — allocated size, which exceeds resident memory when pages are never written`),
+			row("Sampler series", analysis.memory.samplerPresent ? `${analysis.memory.sampleCount} samples` : "absent (in-thread records only)"),
+			row("Worst recorded thread stall", `${Math.round(analysis.memory.worstStallMs)} ms`),
+			row("Log tail truncated by the kill", String(analysis.truncatedTail)),
+			row("Log rotations", analysis.rotations === 0 ? "none — the whole session is present" : `${analysis.rotations} — operations older than the retained segments are absent`),
+			row("Supervisor crash marker", analysis.crashMarker ? `${analysis.crashMarker.reason}${analysis.crashMarker.errorCode ? ` (${analysis.crashMarker.errorCode})` : ""}` : "none — the parent process did not record the cause")
+		]),
+		"",
+		"## RSS over the session",
+		"",
+		"```",
+		sparkline(analysis.memory.rssSeries),
+		"```",
+		"",
+		findingsSection(analysis),
+		"",
+		attributionSection(analysis),
+		"",
+		culpritSection(culprit),
+		"",
+		rendersSection(analysis),
+		"",
+		timelineSection(analysis),
+		"",
+		nextStepsSection(analysis),
+		"",
+		table("Environment", [
+			row("Role", analysis.role),
+			row("Node", analysis.env?.node),
+			row("Platform", analysis.env?.platform),
+			row("Machine memory", formatBytes(analysis.env?.totalMemory)),
+			row("CPUs", analysis.env?.cpus),
+			row("V8 heap limit", formatBytes(analysis.env?.heapLimit)),
+			row("execArgv", (analysis.env?.execArgv ?? []).join(" ") || "(none)"),
+			row("App meta", JSON.stringify(analysis.meta ?? {})),
+			row("Session", analysis.sessionId),
+			row("Records", analysis.recordCount)
+		]),
+		"",
+		"## What this report contains",
+		"",
+		`Kept: ${REDACTION.kept.join(", ")}.`,
+		"",
+		`Never recorded: ${REDACTION.dropped.join(", ")}.`,
+		""
+	].join("\n");
+}
+function findingsSection(analysis) {
+	if (analysis.findings.length === 0) return "## Findings\n\nNo rule fired.";
+	const lines = [
+		"## Findings",
+		"",
+		"| Severity | Rule | Detail |",
+		"| --- | --- | --- |"
+	];
+	for (const finding of analysis.findings) lines.push(`| ${finding.severity} | \`${finding.rule}\` | ${escapeCell(finding.detail)} |`);
+	return lines.join("\n");
+}
+function attributionSection(analysis) {
+	if (analysis.attribution.length === 0) return "## Memory attribution\n\nNo completed operation carried a memory delta.";
+	const lines = [
+		"## Memory attribution — RSS growth per completed operation",
+		"",
+		"| Op | seq | Duration | RSS delta | Heap delta |",
+		"| --- | --- | --- | --- | --- |"
+	];
+	for (const op of analysis.attribution) lines.push(`| ${op.op} | ${op.seq} | ${op.ms ?? "?"} ms | ${formatBytes(op.rssDelta)} | ${formatBytes(op.heapDelta ?? 0)} |`);
+	lines.push("", "The operation that never completed does not appear here — it is in the verdict above.");
+	return lines.join("\n");
+}
+function culpritSection(culprit) {
+	if (!culprit) return "## Definition in flight\n\nNo definition was recorded for the failing operation.";
+	const digest = culprit.def;
+	const def = digest?.def;
+	const lines = [
+		`## Definition in flight (seq ${culprit.seq}, \`${culprit.type}\`, ${digest?.kind ?? "unknown shape"})`,
+		"",
+		"```",
+		renderDefTree(def, ""),
+		"```"
+	];
+	const elided = describeElisions(digest?.redaction);
+	if (elided) lines.push("", elided);
+	return lines.join("\n");
+}
+function describeElisions(redaction) {
+	if (!redaction) return void 0;
+	const notes = [];
+	if (redaction.omittedItems) notes.push(`${redaction.omittedItems} array item(s) omitted across ${redaction.truncatedArrays} array(s)`);
+	if (redaction.depthCapped) notes.push(`${redaction.depthCapped} subtree(s) cut at the depth cap`);
+	if (redaction.budgetExhausted) notes.push("the node budget was exhausted, so the tail is missing");
+	const all = [redaction.bytes !== void 0 ? formatBytes(redaction.bytes) : void 0, ...notes].filter(Boolean);
+	return all.length > 0 ? `Recorded shape: ${all.join("; ")}.` : void 0;
+}
+/**
+* Renders the recorded definition as a tree.
+*
+* The walk is driven by the shape rather than by a known definition type: a node
+* with a join discriminator gets the join line, a node carrying a column spec
+* gets the column line, and anything else with a discriminator is printed as a
+* pass-through step. The same code therefore renders both the original tree API
+* and the V2 query API.
+*/
+function renderDefTree(node, indent, depth = 0) {
+	if (depth > 24) return `${indent}…`;
+	if (node === null || node === void 0) return `${indent}(none)`;
+	if (Array.isArray(node)) return node.map((child) => renderDefTree(child, indent, depth + 1)).join("\n");
+	if (typeof node !== "object") return `${indent}${String(node)}`;
+	const record = node;
+	const payload = columnPayload(record);
+	if (payload) return `${indent}${columnLine(record, payload)}`;
+	if (isJoinNode(record)) {
+		const shape = joinShapes(record)[0];
+		const children = joinChildren(record);
+		return [
+			`${indent}${shape?.join ?? "join"}  children=${children.length}  sharedAxes=${shape?.sharedAxes.length ?? 0}` + (shape?.disjointPairs.length ? `  !! DISJOINT ${JSON.stringify(shape.disjointPairs)}` : "") + `  inputRowsMax=${formatCount(shape?.inputRowsMax)}` + (shape?.rowsUpperBound ? `  rowsUpperBound=${formatCount(shape.rowsUpperBound)}` : ""),
+			`${indent}  axisUnion: ${(shape?.axisUnion ?? []).join("  ") || "(none)"}`,
+			...children.map((child) => renderDefTree(child, `${indent}    `, depth + 1))
+		].join("\n");
+	}
+	const discriminator = typeof record.type === "string" ? record.type : void 0;
+	const interesting = Object.entries(record).filter(([, value]) => isStructural(value));
+	if (discriminator) {
+		const detail = [filtersNote(record), typeof record.$omitted === "number" ? `omitted=${record.$omitted}` : void 0].filter(Boolean).join("  ");
+		return [`${indent}${discriminator}${detail ? `  ${detail}` : ""}`, ...interesting.map(([, value]) => renderDefTree(value, `${indent}  `, depth + 1))].join("\n");
+	}
+	return interesting.length > 0 ? interesting.map(([, value]) => renderDefTree(value, indent, depth + 1)).join("\n") : `${indent}${describeLeafObject(record)}`;
+}
+function filtersNote(record) {
+	const parts = [];
+	for (const key of [
+		"filters",
+		"partitionFilters",
+		"sorting"
+	]) {
+		const value = record[key];
+		if (Array.isArray(value) && value.length > 0) parts.push(`${key}=${value.length}`);
+	}
+	const predicate = record.predicate;
+	if (typeof predicate?.operator === "string") parts.push(`op=${predicate.operator}`);
+	return parts.length > 0 ? parts.join(" ") : void 0;
+}
+function columnLine(outer, payload) {
+	const spec = payload.spec ?? {};
+	const data = payload.data ?? payload.dataInfo ?? {};
+	const axes = axesUnder(payload).map(axisKey).join(" , ");
+	const rows = data.rows ?? data.entries;
+	return `${typeof outer.type === "string" ? outer.type : "column"}  ${asText(spec.name)} : ${asText(spec.valueType)}  axes=[${axes}]  data=${data.kind ?? "?"}` + (data.parts !== void 0 ? ` parts=${data.parts}` : "") + (rows !== void 0 ? ` rows=${formatCount(rows)}` : " rows=unknown") + (data.bytes !== void 0 ? ` bytes=${formatBytes(data.bytes)}` : "");
+}
+/** The record carrying a column spec: the node itself, or the column it wraps. */
+function columnPayload(record) {
+	if (carriesSpec(record)) return record;
+	const inner = record.column;
+	return carriesSpec(inner) ? inner : void 0;
+}
+function carriesSpec(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const spec = value.spec;
+	return Array.isArray(spec?.axesSpec);
+}
+function isStructural(value) {
+	return typeof value === "object" && value !== null;
+}
+function describeLeafObject(record) {
+	if (typeof record.$omitted === "number") return `… ${record.$omitted} more omitted`;
+	if (record.$depth !== void 0) return "… cut at the depth cap";
+	if (record.$budget !== void 0) return "… node budget exhausted";
+	if (typeof record.$opaque === "string") return `(${record.$opaque})`;
+	const keys = Object.keys(record);
+	return keys.length > 0 ? `{ ${keys.join(", ")} }` : "{}";
+}
+function asText(value) {
+	return typeof value === "string" ? value : "?";
+}
+function rendersSection(analysis) {
+	if (analysis.renders.length === 0) return "## Model renders\n\nNone recorded.";
+	const lines = [
+		"## Model renders",
+		"",
+		"| Block | seq | Finished | ms | Sandbox bytes out |",
+		"| --- | --- | --- | --- | --- |"
+	];
+	for (const render of analysis.renders.slice(-12)) {
+		const name = render.blockId ?? render.block ?? render.key ?? "?";
+		const finished = render.end ? render.failed ? "error" : "yes" : "**NO**";
+		const serOut = render.stats?.serOutBytes !== void 0 ? formatBytes(render.stats.serOutBytes) : "-";
+		lines.push(`| ${name} | ${render.seq} | ${finished} | ${render.ms ?? "-"} | ${serOut} |`);
+	}
+	return lines.join("\n");
+}
+function timelineSection(analysis) {
+	const lines = [
+		"## Last records before the log ends",
+		"",
+		"```"
+	];
+	for (const record of analysis.timeline) {
+		const type = record.type;
+		if (type === "mem-sampler" || type === "mem-self") continue;
+		const rss = record.rss;
+		const time = new Date(record.wall).toISOString().slice(11, 23);
+		lines.push(`${String(record.seq).padStart(5)}  ${time}  ${(rss !== void 0 ? formatBytes(rss) : "").padStart(9)}  ${type}` + extraFields(record));
+	}
+	lines.push("```");
+	return lines.join("\n");
+}
+const TIMELINE_FIELDS = [
+	"blockId",
+	"handle",
+	"rows",
+	"columns",
+	"amplification",
+	"returnedBytes",
+	"unbounded",
+	"tableRows",
+	"columnCount",
+	"ms",
+	"error"
+];
+function extraFields(record) {
+	const parts = [];
+	for (const key of TIMELINE_FIELDS) {
+		const value = record[key];
+		if (value === void 0) continue;
+		parts.push(`${key}=${key === "returnedBytes" ? formatBytes(value) : value}`);
+	}
+	const range = record.range;
+	if (range) parts.push(`range=${range.offset}+${range.length}`);
+	if (record.defSummary) parts.push(`def=${JSON.stringify(record.defSummary)}`);
+	return parts.length > 0 ? `  ${parts.join(" ")}` : "";
+}
+const NEXT_STEPS = [
+	{
+		rule: "cross-join",
+		step: "The join tree has siblings with no axis in common. Find where the model assembles that join and check the axis specs of the columns it pulls from the result pool — output size is the product of the inputs."
+	},
+	{
+		rule: "axis-domain-mismatch",
+		step: "The same axis name and type appears with different domains inside one join, so the join key does not match. Compare the domains listed in the findings against what the producing block writes."
+	},
+	{
+		rule: "unbounded-getData",
+		step: "A getData call has no row range. Page it, or drive it from the table viewport."
+	},
+	{
+		rule: "join-amplification",
+		step: "Output rows far exceed the largest input. Log the axis union at each join node and find the level where the count explodes."
+	},
+	{
+		rule: "huge-inline-column",
+		step: "The model built a large inline column inside the sandbox. Move that work into the workflow so it never crosses the QuickJS boundary."
+	},
+	{
+		rule: "js-heap-exhaustion-confirmed",
+		step: "The supervisor confirmed a JS heap limit breach in the middle-layer thread, so the growth is in JavaScript objects, not the native engine. Reproduce with --heapsnapshot-near-heap-limit=1 on that worker to get the retaining set."
+	},
+	{
+		rule: "js-heap-exhaustion",
+		step: "Growth is inside the JS heap. A heap snapshot from the next reproduction would name the retaining objects."
+	},
+	{
+		rule: "off-heap-buffer-growth",
+		step: "Growth is outside the JS heap, so raising --max-old-space-size will not help. Ask for a pframes engine heap profile (pprofDump) alongside this report."
+	},
+	{
+		rule: "native-allocation-growth",
+		step: "Growth is outside the JS heap, so raising --max-old-space-size will not help. Ask for a pframes engine heap profile (pprofDump) alongside this report."
+	},
+	{
+		rule: "unattributed-crash-marker",
+		step: "A crash marker could not be attributed because more than one session in the directory stopped writing around the same time. Spawn the middle-layer worker with an assigned flight session id, which removes the ambiguity entirely."
+	},
+	{
+		rule: "heap-reading-stale",
+		step: "The heap was not sampled near the crash because the thread was blocked. Treat the heap numbers in this report as a floor, not a measurement."
+	}
+];
+function nextStepsSection(analysis) {
+	const rules = new Set(analysis.findings.map((finding) => finding.rule));
+	const steps = NEXT_STEPS.filter((entry) => rules.has(entry.rule)).map((entry) => entry.step);
+	if (analysis.rotations > 1) steps.push("This session rotated more than once, so only the last two segments are on disk and the earliest operations are gone. The verdict above rests on the tail, which is intact; treat the operation list as partial.");
+	if (!analysis.memory.samplerPresent) steps.push("No sampler series in this session: the RSS curve came from in-thread records only and may have gaps where the thread was blocked.");
+	if (steps.length === 0) steps.push("No rule fired. Send the raw flight log so the thresholds can be revisited.");
+	return [
+		"## Next steps",
+		"",
+		...steps.map((step, index) => `${index + 1}. ${step}`)
+	].join("\n");
+}
+function findCulpritJoin(records, analysis) {
+	const bySeq = new Map(records.map((record) => [record.seq, record]));
+	const inFlight = analysis.inFlightAtDeath;
+	if (inFlight) {
+		const beginRecord = bySeq.get(inFlight.seq);
+		if (beginRecord?.def) return {
+			seq: inFlight.seq,
+			type: inFlight.op,
+			def: beginRecord.def
+		};
+		const joinSeq = beginRecord?.joinSeq;
+		const join = joinSeq === void 0 ? void 0 : bySeq.get(joinSeq);
+		if (join?.def) return {
+			seq: join.seq,
+			type: opName(join.type),
+			def: join.def
+		};
+	}
+	const fallback = records.findLast((record) => record.def && record.findings?.length) ?? records.findLast((record) => record.def);
+	return fallback ? {
+		seq: fallback.seq,
+		type: opName(fallback.type),
+		def: fallback.def
+	} : void 0;
+}
+function opName(recordType) {
+	return recordType.replace(/-(begin|end|error)$/, "");
+}
+function sparkline(series, width = 72) {
+	if (series.length === 0) return "(no samples)";
+	const values = series.map((sample) => sample.rss ?? 0);
+	const max = Math.max(...values);
+	const min = Math.min(...values);
+	const chars = "▁▂▃▄▅▆▇█";
+	const step = Math.max(1, Math.ceil(values.length / width));
+	let line = "";
+	for (let i = 0; i < values.length; i += step) {
+		const bucket = values.slice(i, i + step);
+		const peak = Math.max(...bucket);
+		const index = max === min ? 0 : Math.round((peak - min) / (max - min) * 7);
+		line += chars[index];
+	}
+	const spanMs = (series[series.length - 1].wall ?? 0) - (series[0].wall ?? 0);
+	return `${line}\n${formatBytes(min)} → ${formatBytes(max)} over ${(spanMs / 1e3).toFixed(1)}s (${values.length} samples)`;
+}
+function table(title, rows) {
+	return [
+		`## ${title}`,
+		"",
+		"| | |",
+		"| --- | --- |",
+		...rows
+	].join("\n");
+}
+function row(key, value) {
+	return `| ${key} | ${value ?? "unknown"} |`;
+}
+function escapeCell(value) {
+	return String(value ?? "").replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+//#endregion
+export { renderReport };
+
+//# sourceMappingURL=report.js.map

package/dist/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","names":[],"sources":["../src/report.ts"],"sourcesContent":["import { readSession } from \"./recorder\";\nimport { REDACTION } from \"./digest\";\nimport { axesUnder, axisKey, isJoinNode, joinChildren, joinShapes } from \"./rules\";\nimport { formatBytes, formatCount, type SessionAnalysis } from \"./analyze\";\nimport type { FlightRecord } from \"./events\";\n\n/** Renders an analysis as the markdown report a developer reads. */\nexport function renderReport(analysis: SessionAnalysis): string {\n  const { records } = readSession(analysis.file);\n  const culprit = findCulpritJoin(records, analysis);\n  const offHeap = (analysis.memory.externalGrowth ?? 0) + (analysis.memory.arrayBuffersGrowth ?? 0);\n\n  return [\n    \"# Platforma OOM flight report\",\n    \"\",\n    `**Verdict — ${analysis.verdict.likelyCause ?? \"no rule matched\"}**`,\n    \"\",\n    analysis.verdict.summary,\n    \"\",\n    table(\"Where it stopped\", [\n      row(\"Outcome\", analysis.verdict.outcome),\n      row(\"Last unfinished operation\", analysis.verdict.where),\n      row(\"Memory region that grew\", analysis.verdict.memoryRegion ?? \"not classified\"),\n      row(\"Peak RSS\", formatBytes(analysis.memory.peakRss)),\n      row(\"RSS at last sample\", formatBytes(analysis.memory.rssAtDeath)),\n      row(\n        \"JS heap at last record\",\n        `${formatBytes(analysis.memory.heapUsedAtDeath)} of ${formatBytes(analysis.memory.heapLimit)}` +\n          (analysis.memory.heapPressure\n            ? ` (${Math.round(analysis.memory.heapPressure * 100)}%)`\n            : \"\"),\n      ),\n      row(\n        \"Off-heap allocated (external + ArrayBuffers)\",\n        `${formatBytes(offHeap)} — allocated size, which exceeds resident memory when pages are never written`,\n      ),\n      row(\n        \"Sampler series\",\n        analysis.memory.samplerPresent\n          ? `${analysis.memory.sampleCount} samples`\n          : \"absent (in-thread records only)\",\n      ),\n      row(\"Worst recorded thread stall\", `${Math.round(analysis.memory.worstStallMs)} ms`),\n      row(\"Log tail truncated by the kill\", String(analysis.truncatedTail)),\n      row(\n        \"Log rotations\",\n        analysis.rotations === 0\n          ? \"none — the whole session is present\"\n          : `${analysis.rotations} — operations older than the retained segments are absent`,\n      ),\n      row(\n        \"Supervisor crash marker\",\n        analysis.crashMarker\n          ? `${analysis.crashMarker.reason}${\n              analysis.crashMarker.errorCode ? ` (${analysis.crashMarker.errorCode})` : \"\"\n            }`\n          : \"none — the parent process did not record the cause\",\n      ),\n    ]),\n    \"\",\n    \"## RSS over the session\",\n    \"\",\n    \"```\",\n    sparkline(analysis.memory.rssSeries),\n    \"```\",\n    \"\",\n    findingsSection(analysis),\n    \"\",\n    attributionSection(analysis),\n    \"\",\n    culpritSection(culprit),\n    \"\",\n    rendersSection(analysis),\n    \"\",\n    timelineSection(analysis),\n    \"\",\n    nextStepsSection(analysis),\n    \"\",\n    table(\"Environment\", [\n      row(\"Role\", analysis.role),\n      row(\"Node\", analysis.env?.node),\n      row(\"Platform\", analysis.env?.platform),\n      row(\"Machine memory\", formatBytes(analysis.env?.totalMemory)),\n      row(\"CPUs\", analysis.env?.cpus),\n      row(\"V8 heap limit\", formatBytes(analysis.env?.heapLimit)),\n      row(\"execArgv\", (analysis.env?.execArgv ?? []).join(\" \") || \"(none)\"),\n      row(\"App meta\", JSON.stringify(analysis.meta ?? {})),\n      row(\"Session\", analysis.sessionId),\n      row(\"Records\", analysis.recordCount),\n    ]),\n    \"\",\n    \"## What this report contains\",\n    \"\",\n    `Kept: ${REDACTION.kept.join(\", \")}.`,\n    \"\",\n    `Never recorded: ${REDACTION.dropped.join(\", \")}.`,\n    \"\",\n  ].join(\"\\n\");\n}\n\n// Internals\n\ntype Culprit = { seq: number; type: string; def: Record<string, unknown> };\n\nfunction findingsSection(analysis: SessionAnalysis): string {\n  if (analysis.findings.length === 0) return \"## Findings\\n\\nNo rule fired.\";\n  const lines = [\"## Findings\", \"\", \"| Severity | Rule | Detail |\", \"| --- | --- | --- |\"];\n  for (const finding of analysis.findings) {\n    lines.push(`| ${finding.severity} | \\`${finding.rule}\\` | ${escapeCell(finding.detail)} |`);\n  }\n  return lines.join(\"\\n\");\n}\n\nfunction attributionSection(analysis: SessionAnalysis): string {\n  if (analysis.attribution.length === 0) {\n    return \"## Memory attribution\\n\\nNo completed operation carried a memory delta.\";\n  }\n  const lines = [\n    \"## Memory attribution — RSS growth per completed operation\",\n    \"\",\n    \"| Op | seq | Duration | RSS delta | Heap delta |\",\n    \"| --- | --- | --- | --- | --- |\",\n  ];\n  for (const op of analysis.attribution) {\n    lines.push(\n      `| ${op.op} | ${op.seq} | ${op.ms ?? \"?\"} ms | ${formatBytes(op.rssDelta)} | ${formatBytes(\n        op.heapDelta ?? 0,\n      )} |`,\n    );\n  }\n  lines.push(\n    \"\",\n    \"The operation that never completed does not appear here — it is in the verdict above.\",\n  );\n  return lines.join(\"\\n\");\n}\n\nfunction culpritSection(culprit: Culprit | undefined): string {\n  if (!culprit) {\n    return \"## Definition in flight\\n\\nNo definition was recorded for the failing operation.\";\n  }\n  const digest = culprit.def as\n    | { kind?: string; def?: unknown; redaction?: RedactionSummary }\n    | undefined;\n  const def = digest?.def;\n  const lines = [\n    `## Definition in flight (seq ${culprit.seq}, \\`${culprit.type}\\`, ${digest?.kind ?? \"unknown shape\"})`,\n    \"\",\n    \"```\",\n    renderDefTree(def, \"\"),\n    \"```\",\n  ];\n\n  const elided = describeElisions(digest?.redaction);\n  if (elided) lines.push(\"\", elided);\n  return lines.join(\"\\n\");\n}\n\ntype RedactionSummary = {\n  bytes?: number;\n  hashedStrings?: number;\n  truncatedArrays?: number;\n  omittedItems?: number;\n  depthCapped?: number;\n  opaqueObjects?: number;\n  budgetExhausted?: boolean;\n};\n\nfunction describeElisions(redaction: RedactionSummary | undefined): string | undefined {\n  if (!redaction) return undefined;\n  const notes: string[] = [];\n  if (redaction.omittedItems) {\n    notes.push(\n      `${redaction.omittedItems} array item(s) omitted across ${redaction.truncatedArrays} array(s)`,\n    );\n  }\n  if (redaction.depthCapped) notes.push(`${redaction.depthCapped} subtree(s) cut at the depth cap`);\n  if (redaction.budgetExhausted)\n    notes.push(\"the node budget was exhausted, so the tail is missing\");\n  const size = redaction.bytes !== undefined ? formatBytes(redaction.bytes) : undefined;\n  const all = [size, ...notes].filter(Boolean);\n  return all.length > 0 ? `Recorded shape: ${all.join(\"; \")}.` : undefined;\n}\n\n/**\n * Renders the recorded definition as a tree.\n *\n * The walk is driven by the shape rather than by a known definition type: a node\n * with a join discriminator gets the join line, a node carrying a column spec\n * gets the column line, and anything else with a discriminator is printed as a\n * pass-through step. The same code therefore renders both the original tree API\n * and the V2 query API.\n */\nfunction renderDefTree(node: unknown, indent: string, depth = 0): string {\n  if (depth > 24) return `${indent}…`;\n  if (node === null || node === undefined) return `${indent}(none)`;\n  if (Array.isArray(node)) {\n    return node.map((child) => renderDefTree(child, indent, depth + 1)).join(\"\\n\");\n  }\n  if (typeof node !== \"object\") return `${indent}${String(node)}`;\n\n  const record = node as Record<string, unknown>;\n  // Both APIs wrap a column as `{ type: \"column\", column: … }`, so the wrapper\n  // and the column it carries are printed as one line rather than two.\n  const payload = columnPayload(record);\n  if (payload) return `${indent}${columnLine(record, payload)}`;\n\n  if (isJoinNode(record)) {\n    const shape = joinShapes(record)[0];\n    const children = joinChildren(record);\n    const head =\n      `${indent}${shape?.join ?? \"join\"}  children=${children.length}` +\n      `  sharedAxes=${shape?.sharedAxes.length ?? 0}` +\n      (shape?.disjointPairs.length ? `  !! DISJOINT ${JSON.stringify(shape.disjointPairs)}` : \"\") +\n      `  inputRowsMax=${formatCount(shape?.inputRowsMax)}` +\n      (shape?.rowsUpperBound ? `  rowsUpperBound=${formatCount(shape.rowsUpperBound)}` : \"\");\n    const axes = `${indent}  axisUnion: ${(shape?.axisUnion ?? []).join(\"  \") || \"(none)\"}`;\n    return [\n      head,\n      axes,\n      ...children.map((child) => renderDefTree(child, `${indent}    `, depth + 1)),\n    ].join(\"\\n\");\n  }\n\n  const discriminator = typeof record.type === \"string\" ? record.type : undefined;\n  const interesting = Object.entries(record).filter(([, value]) => isStructural(value));\n  if (discriminator) {\n    const detail = [\n      filtersNote(record),\n      typeof record.$omitted === \"number\" ? `omitted=${record.$omitted}` : undefined,\n    ]\n      .filter(Boolean)\n      .join(\"  \");\n    const head = `${indent}${discriminator}${detail ? `  ${detail}` : \"\"}`;\n    return [\n      head,\n      ...interesting.map(([, value]) => renderDefTree(value, `${indent}  `, depth + 1)),\n    ].join(\"\\n\");\n  }\n  // A transparent wrapper (the V2 `{ entry }` shape, or a plain container):\n  // print nothing for it and keep the indentation of its parent.\n  return interesting.length > 0\n    ? interesting.map(([, value]) => renderDefTree(value, indent, depth + 1)).join(\"\\n\")\n    : `${indent}${describeLeafObject(record)}`;\n}\n\nfunction filtersNote(record: Record<string, unknown>): string | undefined {\n  const parts: string[] = [];\n  for (const key of [\"filters\", \"partitionFilters\", \"sorting\"]) {\n    const value = record[key];\n    if (Array.isArray(value) && value.length > 0) parts.push(`${key}=${value.length}`);\n  }\n  const predicate = record.predicate as { operator?: unknown } | undefined;\n  if (typeof predicate?.operator === \"string\") parts.push(`op=${predicate.operator}`);\n  return parts.length > 0 ? parts.join(\" \") : undefined;\n}\n\nfunction columnLine(outer: Record<string, unknown>, payload: Record<string, unknown>): string {\n  const spec = (payload.spec ?? {}) as {\n    name?: unknown;\n    valueType?: unknown;\n    axesSpec?: unknown[];\n  };\n  const data = (payload.data ?? payload.dataInfo ?? {}) as {\n    kind?: string;\n    rows?: number;\n    bytes?: number;\n    parts?: number;\n    entries?: number;\n  };\n  const axes = axesUnder(payload).map(axisKey).join(\" , \");\n  const rows = data.rows ?? data.entries;\n  return (\n    `${typeof outer.type === \"string\" ? outer.type : \"column\"}  ` +\n    `${asText(spec.name)} : ${asText(spec.valueType)}` +\n    `  axes=[${axes}]` +\n    `  data=${data.kind ?? \"?\"}` +\n    (data.parts !== undefined ? ` parts=${data.parts}` : \"\") +\n    (rows !== undefined ? ` rows=${formatCount(rows)}` : \" rows=unknown\") +\n    (data.bytes !== undefined ? ` bytes=${formatBytes(data.bytes)}` : \"\")\n  );\n}\n\n/** The record carrying a column spec: the node itself, or the column it wraps. */\nfunction columnPayload(record: Record<string, unknown>): Record<string, unknown> | undefined {\n  if (carriesSpec(record)) return record;\n  const inner = record.column;\n  return carriesSpec(inner) ? (inner as Record<string, unknown>) : undefined;\n}\n\nfunction carriesSpec(value: unknown): boolean {\n  if (typeof value !== \"object\" || value === null) return false;\n  const spec = (value as { spec?: { axesSpec?: unknown } }).spec;\n  return Array.isArray(spec?.axesSpec);\n}\n\nfunction isStructural(value: unknown): boolean {\n  return typeof value === \"object\" && value !== null;\n}\n\nfunction describeLeafObject(record: Record<string, unknown>): string {\n  if (typeof record.$omitted === \"number\") return `… ${record.$omitted} more omitted`;\n  if (record.$depth !== undefined) return \"… cut at the depth cap\";\n  if (record.$budget !== undefined) return \"… node budget exhausted\";\n  if (typeof record.$opaque === \"string\") return `(${record.$opaque})`;\n  const keys = Object.keys(record);\n  return keys.length > 0 ? `{ ${keys.join(\", \")} }` : \"{}\";\n}\n\nfunction asText(value: unknown): string {\n  return typeof value === \"string\" ? value : \"?\";\n}\n\nfunction rendersSection(analysis: SessionAnalysis): string {\n  if (analysis.renders.length === 0) return \"## Model renders\\n\\nNone recorded.\";\n  const lines = [\n    \"## Model renders\",\n    \"\",\n    \"| Block | seq | Finished | ms | Sandbox bytes out |\",\n    \"| --- | --- | --- | --- | --- |\",\n  ];\n  for (const render of analysis.renders.slice(-12)) {\n    const name = render.blockId ?? render.block ?? render.key ?? \"?\";\n    const finished = render.end ? (render.failed ? \"error\" : \"yes\") : \"**NO**\";\n    const serOut =\n      render.stats?.serOutBytes !== undefined ? formatBytes(render.stats.serOutBytes) : \"-\";\n    lines.push(`| ${name} | ${render.seq} | ${finished} | ${render.ms ?? \"-\"} | ${serOut} |`);\n  }\n  return lines.join(\"\\n\");\n}\n\nfunction timelineSection(analysis: SessionAnalysis): string {\n  const lines = [\"## Last records before the log ends\", \"\", \"```\"];\n  for (const record of analysis.timeline) {\n    const type = record.type as string;\n    if (type === \"mem-sampler\" || type === \"mem-self\") continue;\n    const rss = record.rss as number | undefined;\n    const time = new Date(record.wall as number).toISOString().slice(11, 23);\n    lines.push(\n      `${String(record.seq).padStart(5)}  ${time}  ` +\n        `${(rss !== undefined ? formatBytes(rss) : \"\").padStart(9)}  ${type}` +\n        extraFields(record),\n    );\n  }\n  lines.push(\"```\");\n  return lines.join(\"\\n\");\n}\n\nconst TIMELINE_FIELDS = [\n  \"blockId\",\n  \"handle\",\n  \"rows\",\n  \"columns\",\n  \"amplification\",\n  \"returnedBytes\",\n  \"unbounded\",\n  \"tableRows\",\n  \"columnCount\",\n  \"ms\",\n  \"error\",\n];\n\nfunction extraFields(record: Record<string, unknown>): string {\n  const parts: string[] = [];\n  for (const key of TIMELINE_FIELDS) {\n    const value = record[key];\n    if (value === undefined) continue;\n    parts.push(`${key}=${key === \"returnedBytes\" ? formatBytes(value as number) : value}`);\n  }\n  const range = record.range as { offset: number; length: number } | null | undefined;\n  if (range) parts.push(`range=${range.offset}+${range.length}`);\n  if (record.defSummary) parts.push(`def=${JSON.stringify(record.defSummary)}`);\n  return parts.length > 0 ? `  ${parts.join(\" \")}` : \"\";\n}\n\nconst NEXT_STEPS: { rule: string; step: string }[] = [\n  {\n    rule: \"cross-join\",\n    step: \"The join tree has siblings with no axis in common. Find where the model assembles that join and check the axis specs of the columns it pulls from the result pool — output size is the product of the inputs.\",\n  },\n  {\n    rule: \"axis-domain-mismatch\",\n    step: \"The same axis name and type appears with different domains inside one join, so the join key does not match. Compare the domains listed in the findings against what the producing block writes.\",\n  },\n  {\n    rule: \"unbounded-getData\",\n    step: \"A getData call has no row range. Page it, or drive it from the table viewport.\",\n  },\n  {\n    rule: \"join-amplification\",\n    step: \"Output rows far exceed the largest input. Log the axis union at each join node and find the level where the count explodes.\",\n  },\n  {\n    rule: \"huge-inline-column\",\n    step: \"The model built a large inline column inside the sandbox. Move that work into the workflow so it never crosses the QuickJS boundary.\",\n  },\n  {\n    rule: \"js-heap-exhaustion-confirmed\",\n    step: \"The supervisor confirmed a JS heap limit breach in the middle-layer thread, so the growth is in JavaScript objects, not the native engine. Reproduce with --heapsnapshot-near-heap-limit=1 on that worker to get the retaining set.\",\n  },\n  {\n    rule: \"js-heap-exhaustion\",\n    step: \"Growth is inside the JS heap. A heap snapshot from the next reproduction would name the retaining objects.\",\n  },\n  {\n    rule: \"off-heap-buffer-growth\",\n    step: \"Growth is outside the JS heap, so raising --max-old-space-size will not help. Ask for a pframes engine heap profile (pprofDump) alongside this report.\",\n  },\n  {\n    rule: \"native-allocation-growth\",\n    step: \"Growth is outside the JS heap, so raising --max-old-space-size will not help. Ask for a pframes engine heap profile (pprofDump) alongside this report.\",\n  },\n  {\n    rule: \"unattributed-crash-marker\",\n    step: \"A crash marker could not be attributed because more than one session in the directory stopped writing around the same time. Spawn the middle-layer worker with an assigned flight session id, which removes the ambiguity entirely.\",\n  },\n  {\n    rule: \"heap-reading-stale\",\n    step: \"The heap was not sampled near the crash because the thread was blocked. Treat the heap numbers in this report as a floor, not a measurement.\",\n  },\n];\n\nfunction nextStepsSection(analysis: SessionAnalysis): string {\n  const rules = new Set(analysis.findings.map((finding) => finding.rule));\n  const steps = NEXT_STEPS.filter((entry) => rules.has(entry.rule)).map((entry) => entry.step);\n  if (analysis.rotations > 1) {\n    steps.push(\n      \"This session rotated more than once, so only the last two segments are on disk and the earliest operations are gone. The verdict above rests on the tail, which is intact; treat the operation list as partial.\",\n    );\n  }\n  if (!analysis.memory.samplerPresent) {\n    steps.push(\n      \"No sampler series in this session: the RSS curve came from in-thread records only and may have gaps where the thread was blocked.\",\n    );\n  }\n  if (steps.length === 0) {\n    steps.push(\"No rule fired. Send the raw flight log so the thresholds can be revisited.\");\n  }\n  return [\"## Next steps\", \"\", ...steps.map((step, index) => `${index + 1}. ${step}`)].join(\"\\n\");\n}\n\nfunction findCulpritJoin(records: FlightRecord[], analysis: SessionAnalysis): Culprit | undefined {\n  const bySeq = new Map(records.map((record) => [record.seq, record]));\n  const inFlight = analysis.inFlightAtDeath;\n\n  // An in-flight data call points back at the join that produced its handle.\n  if (inFlight) {\n    const beginRecord = bySeq.get(inFlight.seq);\n    if (beginRecord?.def) {\n      return {\n        seq: inFlight.seq,\n        type: inFlight.op,\n        def: beginRecord.def as Record<string, unknown>,\n      };\n    }\n    const joinSeq = beginRecord?.joinSeq as number | undefined;\n    const join = joinSeq === undefined ? undefined : bySeq.get(joinSeq);\n    if (join?.def) {\n      return { seq: join.seq, type: opName(join.type), def: join.def as Record<string, unknown> };\n    }\n  }\n  // Otherwise the most recent join carrying a structural finding.\n  const flagged = records.findLast(\n    (record) => record.def && (record.findings as unknown[] | undefined)?.length,\n  );\n  const fallback = flagged ?? records.findLast((record) => record.def);\n  return fallback\n    ? {\n        seq: fallback.seq,\n        type: opName(fallback.type),\n        def: fallback.def as Record<string, unknown>,\n      }\n    : undefined;\n}\n\nfunction opName(recordType: string): string {\n  return recordType.replace(/-(begin|end|error)$/, \"\");\n}\n\nfunction sparkline(series: { wall: number; rss?: number }[], width = 72): string {\n  if (series.length === 0) return \"(no samples)\";\n  const values = series.map((sample) => sample.rss ?? 0);\n  const max = Math.max(...values);\n  const min = Math.min(...values);\n  const chars = \"▁▂▃▄▅▆▇█\";\n  const step = Math.max(1, Math.ceil(values.length / width));\n  let line = \"\";\n  for (let i = 0; i < values.length; i += step) {\n    const bucket = values.slice(i, i + step);\n    const peak = Math.max(...bucket);\n    const index = max === min ? 0 : Math.round(((peak - min) / (max - min)) * (chars.length - 1));\n    line += chars[index];\n  }\n  const spanMs = (series[series.length - 1].wall ?? 0) - (series[0].wall ?? 0);\n  return `${line}\\n${formatBytes(min)} → ${formatBytes(max)} over ${(spanMs / 1000).toFixed(1)}s (${\n    values.length\n  } samples)`;\n}\n\nfunction table(title: string, rows: string[]): string {\n  return [`## ${title}`, \"\", \"| | |\", \"| --- | --- |\", ...rows].join(\"\\n\");\n}\n\nfunction row(key: string, value: unknown): string {\n  return `| ${key} | ${value ?? \"unknown\"} |`;\n}\n\nfunction escapeCell(value: string): string {\n  return String(value ?? \"\")\n    .replace(/\\|/g, \"\\\\|\")\n    .replace(/\\n/g, \" \");\n}\n"],"mappings":"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"}

package/dist/rules.d.ts

@@ -0,0 +1,73 @@
+//#region src/rules.d.ts
+/**
+ * Structural faults in a join, read from the recorded shape of its definition.
+ *
+ * Two faults make a join's output size unbounded and both are visible before any
+ * data is touched: siblings that share no axis at all, which is a cartesian
+ * product, and siblings whose axes agree on name and type but disagree on
+ * domain, where the join key silently fails to match.
+ *
+ * These run in the analyzer rather than at record time. Nothing is computed on
+ * the hot path, the thresholds and the rules can be revised against logs that
+ * already exist, and one implementation covers every definition shape: the join
+ * nodes are recognised by their discriminator and their children by position, so
+ * both the original tree API and the V2 query API are read by the same walk.
+ */
+export type FindingSeverity = "critical" | "high" | "medium" | "low";
+export type StructuralFinding = {
+  rule: "cross-join" | "axis-domain-mismatch" | "partial-key-fan-out";
+  severity: FindingSeverity;
+  /** Position in the definition, e.g. `root/innerJoin[1]`. */
+  path: string;
+  join: string;
+  detail: string;
+  rowsUpperBound?: number;
+  domains?: {
+    domain: string;
+    children: number[];
+  }[];
+  missing?: {
+    index: number;
+    missing: string[];
+  }[];
+};
+export type AxisDescriptor = {
+  name: string;
+  type: string;
+  domain?: Record<string, string>;
+};
+export type JoinShape = {
+  join: string;
+  path: string;
+  childCount: number;
+  axisUnion: string[];
+  sharedAxes: string[];
+  disjointPairs: [number, number][];
+  inputRowsMax?: number;
+  /** Loose but true: no join of these inputs can exceed the product of their rows. */
+  rowsUpperBound?: number;
+};
+/** Structural findings for a recorded definition, most specific first. */
+export declare function structuralFindings(def: unknown): StructuralFinding[];
+/** Shape of every join node in a definition, outermost first. */
+export declare function joinShapes(def: unknown): JoinShape[];
+/**
+ * Largest input row count the definition declares, used to judge how much a
+ * join amplified. Unknown when no workflow recorded chunk statistics.
+ */
+export declare function inputRowsMax(def: unknown): number | undefined;
+/** Canonical axis identity, matching how join keys are formed. */
+export declare function axisKey(axis: AxisDescriptor): string;
+/** Axis identity ignoring domain, used to spot near-miss axes that fail to join. */
+export declare function axisNameKey(axis: AxisDescriptor): string;
+/** True when a node is a join, by its discriminator. */
+export declare function isJoinNode(node: unknown): boolean;
+/**
+ * A join's children, by position. The V2 API wraps each child in `{ entry }`;
+ * that wrapper is left in place because every read here descends through it.
+ */
+export declare function joinChildren(node: unknown): unknown[];
+/** Axis descriptors anywhere beneath a node, deduplicated by identity. */
+export declare function axesUnder(node: unknown): AxisDescriptor[];
+//#endregion
+//# sourceMappingURL=rules.d.ts.map

package/dist/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","names":[],"sources":["../src/rules.ts"],"mappings":";;;;;;;;;;;;;;;YAuBY;YAEA;EACV;EACA,UAAU;;EAEV;EACA;EACA;EACA;EACA;IAAY;IAAgB;;EAC5B;IAAY;IAAe;;;YAGjB;EACV;EACA;EACA,SAAS;;YAGC;EACV;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;;;wBA6Bc,mBAAmB,eAAe;;wBAOlC,WAAW,eAAe;;;;;wBAU1B,aAAa;;wBAMb,QAAQ,MAAM;;wBAKd,YAAY,MAAM;;wBAKlB,WAAW;;;;;wBAYX,aAAa;;wBASb,UAAU,gBAAgB"}