@milaboratories/pl-flight-recorder 0.2.0

package/dist/rules.js

@@ -0,0 +1,245 @@
+//#region src/rules.ts
+/** Joins that keep only keys present in every entry; an entry missing part of the key fans out. */
+const INTERSECT_JOINS = /* @__PURE__ */ new Set(["inner", "innerJoin"]);
+/** Joins that keep keys present in any entry, filling the rest with nulls. */
+const UNION_JOINS = /* @__PURE__ */ new Set(["full", "fullJoin"]);
+/** Joins driven by one side: the primary or linker decides which keys exist. */
+const DRIVEN_JOINS = /* @__PURE__ */ new Set([
+	"outer",
+	"outerJoin",
+	"linkerJoin"
+]);
+/** Structural findings for a recorded definition, most specific first. */
+function structuralFindings(def) {
+	const findings = [];
+	visit(def, "root", (node, path) => collect(node, path, findings));
+	return findings;
+}
+/** Shape of every join node in a definition, outermost first. */
+function joinShapes(def) {
+	const shapes = [];
+	visit(def, "root", (node, path) => shapes.push(shapeOf(node, path)));
+	return shapes;
+}
+/**
+* Largest input row count the definition declares, used to judge how much a
+* join amplified. Unknown when no workflow recorded chunk statistics.
+*/
+function inputRowsMax(def) {
+	const rows = childRowCounts(def);
+	return rows.length > 0 ? Math.max(...rows) : estimateRows(def);
+}
+/** Canonical axis identity, matching how join keys are formed. */
+function axisKey(axis) {
+	return `${axis.type}|${axis.name}|${canonicalDomain(axis.domain)}`;
+}
+/** Axis identity ignoring domain, used to spot near-miss axes that fail to join. */
+function axisNameKey(axis) {
+	return `${axis.type}|${axis.name}`;
+}
+/** True when a node is a join, by its discriminator. */
+function isJoinNode(node) {
+	const type = discriminator(node);
+	return type !== void 0 && (INTERSECT_JOINS.has(type) || UNION_JOINS.has(type) || DRIVEN_JOINS.has(type));
+}
+/**
+* A join's children, by position. The V2 API wraps each child in `{ entry }`;
+* that wrapper is left in place because every read here descends through it.
+*/
+function joinChildren(node) {
+	const record = asRecord(node);
+	if (!record) return [];
+	if (Array.isArray(record.entries)) return record.entries;
+	return [record.primary ?? record.linker, ...toArray(record.secondary)].filter((child) => child !== void 0 && child !== null);
+}
+/** Axis descriptors anywhere beneath a node, deduplicated by identity. */
+function axesUnder(node) {
+	const out = /* @__PURE__ */ new Map();
+	gatherAxes(node, out, 0);
+	return [...out.values()];
+}
+const MAX_WALK_DEPTH = 40;
+function visit(node, path, onJoin, depth = 0) {
+	if (depth > MAX_WALK_DEPTH || !isTraversable(node)) return;
+	if (isJoinNode(node)) {
+		onJoin(node, path);
+		const join = discriminator(node) ?? "join";
+		for (const [index, child] of joinChildren(node).entries()) visit(child, `${path}/${join}[${index}]`, onJoin, depth + 1);
+		return;
+	}
+	for (const child of childValues(node)) visit(child, path, onJoin, depth + 1);
+}
+function shapeOf(node, path) {
+	const join = discriminator(node) ?? "join";
+	const children = joinChildren(node);
+	const keySets = children.map((child) => new Set(axesUnder(child).map(axisKey)));
+	const union = /* @__PURE__ */ new Set();
+	for (const set of keySets) for (const key of set) union.add(key);
+	const disjointPairs = [];
+	for (let i = 0; i < keySets.length; i++) for (let j = i + 1; j < keySets.length; j++) {
+		if (keySets[i].size === 0 || keySets[j].size === 0) continue;
+		if ([...keySets[i]].some((key) => keySets[j].has(key))) continue;
+		disjointPairs.push([i, j]);
+	}
+	const rows = children.map(estimateRows);
+	const known = rows.filter((value) => typeof value === "number");
+	return {
+		join,
+		path,
+		childCount: children.length,
+		axisUnion: [...union],
+		sharedAxes: [...union].filter((key) => keySets.every((set) => set.has(key))),
+		disjointPairs,
+		inputRowsMax: known.length > 0 ? Math.max(...known) : void 0,
+		rowsUpperBound: known.length === rows.length && known.length > 0 ? product(known) : void 0
+	};
+}
+function collect(node, path, findings) {
+	const shape = shapeOf(node, path);
+	const children = joinChildren(node);
+	if (shape.disjointPairs.length > 0) findings.push({
+		rule: "cross-join",
+		severity: "critical",
+		path,
+		join: shape.join,
+		detail: `join siblings share no axis: pairs ${JSON.stringify(shape.disjointPairs)}`,
+		rowsUpperBound: shape.rowsUpperBound
+	});
+	for (const nearMiss of nearMissAxes(children)) findings.push({
+		rule: "axis-domain-mismatch",
+		severity: "high",
+		path,
+		join: shape.join,
+		detail: `axis ${nearMiss.axis} appears with ${nearMiss.domains.length} different domains`,
+		domains: nearMiss.domains
+	});
+	if (!INTERSECT_JOINS.has(shape.join) || shape.disjointPairs.length > 0) return;
+	const missing = children.map((child, index) => {
+		const own = new Set(axesUnder(child).map(axisKey));
+		return {
+			index,
+			missing: shape.axisUnion.filter((key) => !own.has(key))
+		};
+	}).filter((entry) => entry.missing.length > 0);
+	if (missing.length === 0) return;
+	findings.push({
+		rule: "partial-key-fan-out",
+		severity: "medium",
+		path,
+		join: shape.join,
+		detail: `${missing.length} sibling(s) lack part of the node's axis union and get replicated`,
+		missing
+	});
+}
+function nearMissAxes(children) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const [index, child] of children.entries()) for (const axis of axesUnder(child)) {
+		const nameKey = axisNameKey(axis);
+		let perDomain = byName.get(nameKey);
+		if (!perDomain) byName.set(nameKey, perDomain = /* @__PURE__ */ new Map());
+		const domainKey = canonicalDomain(axis.domain);
+		let indices = perDomain.get(domainKey);
+		if (!indices) perDomain.set(domainKey, indices = /* @__PURE__ */ new Set());
+		indices.add(index);
+	}
+	const out = [];
+	for (const [axis, perDomain] of byName) {
+		if (perDomain.size < 2) continue;
+		out.push({
+			axis,
+			domains: [...perDomain.entries()].map(([domain, indices]) => ({
+				domain: domain || "(none)",
+				children: [...indices]
+			}))
+		});
+	}
+	return out;
+}
+function estimateRows(node, depth = 0) {
+	if (depth > MAX_WALK_DEPTH || !isTraversable(node)) return void 0;
+	if (isJoinNode(node)) {
+		const join = discriminator(node) ?? "";
+		const rows = joinChildren(node).map((child) => estimateRows(child, depth + 1)).filter((value) => typeof value === "number");
+		if (rows.length === 0) return void 0;
+		return INTERSECT_JOINS.has(join) ? Math.max(...rows) : sum(rows);
+	}
+	const own = ownRows(node);
+	if (own !== void 0) return own;
+	const rows = childValues(node).map((child) => estimateRows(child, depth + 1)).filter((value) => typeof value === "number");
+	return rows.length > 0 ? Math.max(...rows) : void 0;
+}
+function childRowCounts(def) {
+	return joinShapes(def).map((shape) => shape.inputRowsMax).filter((value) => typeof value === "number");
+}
+function ownRows(node) {
+	const record = asRecord(node);
+	if (!record) return void 0;
+	for (const key of ["data", "dataInfo"]) {
+		const summary = record[key];
+		if (!summary || typeof summary !== "object") continue;
+		if (typeof summary.rows === "number") return summary.rows;
+		if (typeof summary.entries === "number") return summary.entries;
+	}
+}
+function gatherAxes(node, out, depth) {
+	if (depth > MAX_WALK_DEPTH || !isTraversable(node)) return;
+	const record = asRecord(node);
+	if (record) for (const key of ["axesSpec", "axes"]) {
+		const value = record[key];
+		if (!Array.isArray(value)) continue;
+		for (const item of value) {
+			const axis = asAxis(item);
+			if (axis) out.set(axisKey(axis), axis);
+		}
+	}
+	for (const child of childValues(node)) gatherAxes(child, out, depth + 1);
+}
+function asAxis(value) {
+	const record = asRecord(value);
+	if (!record) return void 0;
+	const { name, type, domain } = record;
+	if (typeof name !== "string" || typeof type !== "string") return void 0;
+	return {
+		name,
+		type,
+		domain: plainStringMap(domain)
+	};
+}
+function plainStringMap(value) {
+	const record = asRecord(value);
+	if (!record) return void 0;
+	const out = {};
+	for (const [key, item] of Object.entries(record)) if (typeof item === "string") out[key] = item;
+	return Object.keys(out).length > 0 ? out : void 0;
+}
+function canonicalDomain(domain) {
+	return Object.entries(domain ?? {}).sort(([lhs], [rhs]) => lhs < rhs ? -1 : 1).map(([key, value]) => `${key}=${value}`).join(",");
+}
+function discriminator(node) {
+	const type = asRecord(node)?.type;
+	return typeof type === "string" ? type : void 0;
+}
+function childValues(node) {
+	if (Array.isArray(node)) return node;
+	const record = asRecord(node);
+	return record ? Object.values(record) : [];
+}
+function asRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+function isTraversable(value) {
+	return typeof value === "object" && value !== null;
+}
+function toArray(value) {
+	return Array.isArray(value) ? value : value === void 0 || value === null ? [] : [value];
+}
+function sum(values) {
+	return values.reduce((acc, value) => acc + value, 0);
+}
+function product(values) {
+	return values.reduce((acc, value) => acc * value, 1);
+}
+//#endregion
+export { axesUnder, axisKey, axisNameKey, inputRowsMax, isJoinNode, joinChildren, joinShapes, structuralFindings };
+
+//# sourceMappingURL=rules.js.map

package/dist/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.js","names":[],"sources":["../src/rules.ts"],"sourcesContent":["import type {\n  JoinEntry,\n  SpecQueryLinkerJoin,\n  SpecQueryOuterJoin,\n  SpecQuerySymmetricJoin,\n} from \"@milaboratories/pl-model-common\";\nimport type { DataSummary } from \"./data_summary\";\n\n/**\n * Structural faults in a join, read from the recorded shape of its definition.\n *\n * Two faults make a join's output size unbounded and both are visible before any\n * data is touched: siblings that share no axis at all, which is a cartesian\n * product, and siblings whose axes agree on name and type but disagree on\n * domain, where the join key silently fails to match.\n *\n * These run in the analyzer rather than at record time. Nothing is computed on\n * the hot path, the thresholds and the rules can be revised against logs that\n * already exist, and one implementation covers every definition shape: the join\n * nodes are recognised by their discriminator and their children by position, so\n * both the original tree API and the V2 query API are read by the same walk.\n */\n\nexport type FindingSeverity = \"critical\" | \"high\" | \"medium\" | \"low\";\n\nexport type StructuralFinding = {\n  rule: \"cross-join\" | \"axis-domain-mismatch\" | \"partial-key-fan-out\";\n  severity: FindingSeverity;\n  /** Position in the definition, e.g. `root/innerJoin[1]`. */\n  path: string;\n  join: string;\n  detail: string;\n  rowsUpperBound?: number;\n  domains?: { domain: string; children: number[] }[];\n  missing?: { index: number; missing: string[] }[];\n};\n\nexport type AxisDescriptor = {\n  name: string;\n  type: string;\n  domain?: Record<string, string>;\n};\n\nexport type JoinShape = {\n  join: string;\n  path: string;\n  childCount: number;\n  axisUnion: string[];\n  sharedAxes: string[];\n  disjointPairs: [number, number][];\n  inputRowsMax?: number;\n  /** Loose but true: no join of these inputs can exceed the product of their rows. */\n  rowsUpperBound?: number;\n};\n\n// The discriminators are pinned to the model's own literal types, so renaming a\n// join kind in pl-model-common fails this build instead of silently disabling a\n// rule. The model exports the names only as types, never as runtime constants.\ntype TreeJoinType = Extract<\n  JoinEntry<unknown>,\n  { entries: unknown } | { primary: unknown }\n>[\"type\"];\ntype QueryJoinType = (SpecQuerySymmetricJoin | SpecQueryOuterJoin | SpecQueryLinkerJoin)[\"type\"];\n\n/** Joins that keep only keys present in every entry; an entry missing part of the key fans out. */\nconst INTERSECT_JOINS: ReadonlySet<string> = new Set([\"inner\", \"innerJoin\"] satisfies (\n  | TreeJoinType\n  | QueryJoinType\n)[]);\n/** Joins that keep keys present in any entry, filling the rest with nulls. */\nconst UNION_JOINS: ReadonlySet<string> = new Set([\"full\", \"fullJoin\"] satisfies (\n  | TreeJoinType\n  | QueryJoinType\n)[]);\n/** Joins driven by one side: the primary or linker decides which keys exist. */\nconst DRIVEN_JOINS: ReadonlySet<string> = new Set([\"outer\", \"outerJoin\", \"linkerJoin\"] satisfies (\n  | TreeJoinType\n  | QueryJoinType\n)[]);\n\n/** Structural findings for a recorded definition, most specific first. */\nexport function structuralFindings(def: unknown): StructuralFinding[] {\n  const findings: StructuralFinding[] = [];\n  visit(def, \"root\", (node, path) => collect(node, path, findings));\n  return findings;\n}\n\n/** Shape of every join node in a definition, outermost first. */\nexport function joinShapes(def: unknown): JoinShape[] {\n  const shapes: JoinShape[] = [];\n  visit(def, \"root\", (node, path) => shapes.push(shapeOf(node, path)));\n  return shapes;\n}\n\n/**\n * Largest input row count the definition declares, used to judge how much a\n * join amplified. Unknown when no workflow recorded chunk statistics.\n */\nexport function inputRowsMax(def: unknown): number | undefined {\n  const rows = childRowCounts(def);\n  return rows.length > 0 ? Math.max(...rows) : estimateRows(def);\n}\n\n/** Canonical axis identity, matching how join keys are formed. */\nexport function axisKey(axis: AxisDescriptor): string {\n  return `${axis.type}|${axis.name}|${canonicalDomain(axis.domain)}`;\n}\n\n/** Axis identity ignoring domain, used to spot near-miss axes that fail to join. */\nexport function axisNameKey(axis: AxisDescriptor): string {\n  return `${axis.type}|${axis.name}`;\n}\n\n/** True when a node is a join, by its discriminator. */\nexport function isJoinNode(node: unknown): boolean {\n  const type = discriminator(node);\n  return (\n    type !== undefined &&\n    (INTERSECT_JOINS.has(type) || UNION_JOINS.has(type) || DRIVEN_JOINS.has(type))\n  );\n}\n\n/**\n * A join's children, by position. The V2 API wraps each child in `{ entry }`;\n * that wrapper is left in place because every read here descends through it.\n */\nexport function joinChildren(node: unknown): unknown[] {\n  const record = asRecord(node);\n  if (!record) return [];\n  if (Array.isArray(record.entries)) return record.entries;\n  const driven = [record.primary ?? record.linker, ...toArray(record.secondary)];\n  return driven.filter((child) => child !== undefined && child !== null);\n}\n\n/** Axis descriptors anywhere beneath a node, deduplicated by identity. */\nexport function axesUnder(node: unknown): AxisDescriptor[] {\n  const out = new Map<string, AxisDescriptor>();\n  gatherAxes(node, out, 0);\n  return [...out.values()];\n}\n\n// Internals\n\nconst MAX_WALK_DEPTH = 40;\n\nfunction visit(\n  node: unknown,\n  path: string,\n  onJoin: (node: unknown, path: string) => void,\n  depth = 0,\n): void {\n  if (depth > MAX_WALK_DEPTH || !isTraversable(node)) return;\n  if (isJoinNode(node)) {\n    onJoin(node, path);\n    const join = discriminator(node) ?? \"join\";\n    for (const [index, child] of joinChildren(node).entries()) {\n      visit(child, `${path}/${join}[${index}]`, onJoin, depth + 1);\n    }\n    return;\n  }\n  for (const child of childValues(node)) visit(child, path, onJoin, depth + 1);\n}\n\nfunction shapeOf(node: unknown, path: string): JoinShape {\n  const join = discriminator(node) ?? \"join\";\n  const children = joinChildren(node);\n  const keySets = children.map((child) => new Set(axesUnder(child).map(axisKey)));\n\n  const union = new Set<string>();\n  for (const set of keySets) for (const key of set) union.add(key);\n\n  const disjointPairs: [number, number][] = [];\n  for (let i = 0; i < keySets.length; i++) {\n    for (let j = i + 1; j < keySets.length; j++) {\n      if (keySets[i].size === 0 || keySets[j].size === 0) continue;\n      if ([...keySets[i]].some((key) => keySets[j].has(key))) continue;\n      disjointPairs.push([i, j]);\n    }\n  }\n\n  const rows = children.map(estimateRows);\n  const known = rows.filter((value): value is number => typeof value === \"number\");\n  return {\n    join,\n    path,\n    childCount: children.length,\n    axisUnion: [...union],\n    sharedAxes: [...union].filter((key) => keySets.every((set) => set.has(key))),\n    disjointPairs,\n    inputRowsMax: known.length > 0 ? Math.max(...known) : undefined,\n    rowsUpperBound: known.length === rows.length && known.length > 0 ? product(known) : undefined,\n  };\n}\n\nfunction collect(node: unknown, path: string, findings: StructuralFinding[]): void {\n  const shape = shapeOf(node, path);\n  const children = joinChildren(node);\n\n  if (shape.disjointPairs.length > 0) {\n    findings.push({\n      rule: \"cross-join\",\n      severity: \"critical\",\n      path,\n      join: shape.join,\n      detail: `join siblings share no axis: pairs ${JSON.stringify(shape.disjointPairs)}`,\n      rowsUpperBound: shape.rowsUpperBound,\n    });\n  }\n\n  for (const nearMiss of nearMissAxes(children)) {\n    findings.push({\n      rule: \"axis-domain-mismatch\",\n      severity: \"high\",\n      path,\n      join: shape.join,\n      detail: `axis ${nearMiss.axis} appears with ${nearMiss.domains.length} different domains`,\n      domains: nearMiss.domains,\n    });\n  }\n\n  // Fan-out is worth reporting only where the node still has a working join key\n  // and its entries are peers; on a cartesian node it restates the cross-join,\n  // and on a driven join a narrower secondary is the intended behaviour.\n  if (!INTERSECT_JOINS.has(shape.join) || shape.disjointPairs.length > 0) return;\n  const missing = children\n    .map((child, index) => {\n      const own = new Set(axesUnder(child).map(axisKey));\n      return { index, missing: shape.axisUnion.filter((key) => !own.has(key)) };\n    })\n    .filter((entry) => entry.missing.length > 0);\n  if (missing.length === 0) return;\n  findings.push({\n    rule: \"partial-key-fan-out\",\n    severity: \"medium\",\n    path,\n    join: shape.join,\n    detail: `${missing.length} sibling(s) lack part of the node's axis union and get replicated`,\n    missing,\n  });\n}\n\n// Axes agreeing on name and type but disagreeing on domain never match as a\n// join key, which turns an intended join into a product or an empty result.\nfunction nearMissAxes(\n  children: unknown[],\n): { axis: string; domains: { domain: string; children: number[] }[] }[] {\n  const byName = new Map<string, Map<string, Set<number>>>();\n  for (const [index, child] of children.entries()) {\n    for (const axis of axesUnder(child)) {\n      const nameKey = axisNameKey(axis);\n      let perDomain = byName.get(nameKey);\n      if (!perDomain) byName.set(nameKey, (perDomain = new Map()));\n      const domainKey = canonicalDomain(axis.domain);\n      let indices = perDomain.get(domainKey);\n      if (!indices) perDomain.set(domainKey, (indices = new Set()));\n      indices.add(index);\n    }\n  }\n  const out: { axis: string; domains: { domain: string; children: number[] }[] }[] = [];\n  for (const [axis, perDomain] of byName) {\n    if (perDomain.size < 2) continue;\n    out.push({\n      axis,\n      domains: [...perDomain.entries()].map(([domain, indices]) => ({\n        domain: domain || \"(none)\",\n        children: [...indices],\n      })),\n    });\n  }\n  return out;\n}\n\nfunction estimateRows(node: unknown, depth = 0): number | undefined {\n  if (depth > MAX_WALK_DEPTH || !isTraversable(node)) return undefined;\n  if (isJoinNode(node)) {\n    const join = discriminator(node) ?? \"\";\n    const rows = joinChildren(node)\n      .map((child) => estimateRows(child, depth + 1))\n      .filter((value): value is number => typeof value === \"number\");\n    if (rows.length === 0) return undefined;\n    // An intersection cannot exceed its largest input; a union adds up.\n    return INTERSECT_JOINS.has(join) ? Math.max(...rows) : sum(rows);\n  }\n  const own = ownRows(node);\n  if (own !== undefined) return own;\n  const rows = childValues(node)\n    .map((child) => estimateRows(child, depth + 1))\n    .filter((value): value is number => typeof value === \"number\");\n  return rows.length > 0 ? Math.max(...rows) : undefined;\n}\n\nfunction childRowCounts(def: unknown): number[] {\n  const shapes = joinShapes(def);\n  return shapes\n    .map((shape) => shape.inputRowsMax)\n    .filter((value): value is number => typeof value === \"number\");\n}\n\nfunction ownRows(node: unknown): number | undefined {\n  const record = asRecord(node);\n  if (!record) return undefined;\n  for (const key of [\"data\", \"dataInfo\"]) {\n    const summary = record[key] as DataSummary | undefined;\n    if (!summary || typeof summary !== \"object\") continue;\n    if (typeof summary.rows === \"number\") return summary.rows;\n    if (typeof summary.entries === \"number\") return summary.entries;\n  }\n  return undefined;\n}\n\nfunction gatherAxes(node: unknown, out: Map<string, AxisDescriptor>, depth: number): void {\n  if (depth > MAX_WALK_DEPTH || !isTraversable(node)) return;\n  const record = asRecord(node);\n  if (record) {\n    for (const key of [\"axesSpec\", \"axes\"]) {\n      const value = record[key];\n      if (!Array.isArray(value)) continue;\n      for (const item of value) {\n        const axis = asAxis(item);\n        if (axis) out.set(axisKey(axis), axis);\n      }\n    }\n  }\n  for (const child of childValues(node)) gatherAxes(child, out, depth + 1);\n}\n\nfunction asAxis(value: unknown): AxisDescriptor | undefined {\n  const record = asRecord(value);\n  if (!record) return undefined;\n  const { name, type, domain } = record;\n  if (typeof name !== \"string\" || typeof type !== \"string\") return undefined;\n  return { name, type, domain: plainStringMap(domain) };\n}\n\nfunction plainStringMap(value: unknown): Record<string, string> | undefined {\n  const record = asRecord(value);\n  if (!record) return undefined;\n  const out: Record<string, string> = {};\n  for (const [key, item] of Object.entries(record)) {\n    if (typeof item === \"string\") out[key] = item;\n  }\n  return Object.keys(out).length > 0 ? out : undefined;\n}\n\nfunction canonicalDomain(domain: Record<string, string> | undefined): string {\n  return Object.entries(domain ?? {})\n    .sort(([lhs], [rhs]) => (lhs < rhs ? -1 : 1))\n    .map(([key, value]) => `${key}=${value}`)\n    .join(\",\");\n}\n\nfunction discriminator(node: unknown): string | undefined {\n  const type = asRecord(node)?.type;\n  return typeof type === \"string\" ? type : undefined;\n}\n\nfunction childValues(node: unknown): unknown[] {\n  if (Array.isArray(node)) return node;\n  const record = asRecord(node);\n  return record ? Object.values(record) : [];\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> | undefined {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value)\n    ? (value as Record<string, unknown>)\n    : undefined;\n}\n\nfunction isTraversable(value: unknown): boolean {\n  return typeof value === \"object\" && value !== null;\n}\n\nfunction toArray(value: unknown): unknown[] {\n  return Array.isArray(value) ? value : value === undefined || value === null ? [] : [value];\n}\n\nfunction sum(values: number[]): number {\n  return values.reduce((acc, value) => acc + value, 0);\n}\n\nfunction product(values: number[]): number {\n  return values.reduce((acc, value) => acc * value, 1);\n}\n"],"mappings":";;AAiEA,MAAM,kCAAuC,IAAI,IAAI,CAAC,SAAS,WAAW,CAGvE;;AAEH,MAAM,8BAAmC,IAAI,IAAI,CAAC,QAAQ,UAAU,CAGjE;;AAEH,MAAM,+BAAoC,IAAI,IAAI;CAAC;CAAS;CAAa;AAAY,CAGlF;;AAGH,SAAgB,mBAAmB,KAAmC;CACpE,MAAM,WAAgC,CAAC;CACvC,MAAM,KAAK,SAAS,MAAM,SAAS,QAAQ,MAAM,MAAM,QAAQ,CAAC;CAChE,OAAO;AACT;;AAGA,SAAgB,WAAW,KAA2B;CACpD,MAAM,SAAsB,CAAC;CAC7B,MAAM,KAAK,SAAS,MAAM,SAAS,OAAO,KAAK,QAAQ,MAAM,IAAI,CAAC,CAAC;CACnE,OAAO;AACT;;;;;AAMA,SAAgB,aAAa,KAAkC;CAC7D,MAAM,OAAO,eAAe,GAAG;CAC/B,OAAO,KAAK,SAAS,IAAI,KAAK,IAAI,GAAG,IAAI,IAAI,aAAa,GAAG;AAC/D;;AAGA,SAAgB,QAAQ,MAA8B;CACpD,OAAO,GAAG,KAAK,KAAK,GAAG,KAAK,KAAK,GAAG,gBAAgB,KAAK,MAAM;AACjE;;AAGA,SAAgB,YAAY,MAA8B;CACxD,OAAO,GAAG,KAAK,KAAK,GAAG,KAAK;AAC9B;;AAGA,SAAgB,WAAW,MAAwB;CACjD,MAAM,OAAO,cAAc,IAAI;CAC/B,OACE,SAAS,KAAA,MACR,gBAAgB,IAAI,IAAI,KAAK,YAAY,IAAI,IAAI,KAAK,aAAa,IAAI,IAAI;AAEhF;;;;;AAMA,SAAgB,aAAa,MAA0B;CACrD,MAAM,SAAS,SAAS,IAAI;CAC5B,IAAI,CAAC,QAAQ,OAAO,CAAC;CACrB,IAAI,MAAM,QAAQ,OAAO,OAAO,GAAG,OAAO,OAAO;CAEjD,OAAO,CADS,OAAO,WAAW,OAAO,QAAQ,GAAG,QAAQ,OAAO,SAAS,CAChE,CAAC,CAAC,QAAQ,UAAU,UAAU,KAAA,KAAa,UAAU,IAAI;AACvE;;AAGA,SAAgB,UAAU,MAAiC;CACzD,MAAM,sBAAM,IAAI,IAA4B;CAC5C,WAAW,MAAM,KAAK,CAAC;CACvB,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC;AACzB;AAIA,MAAM,iBAAiB;AAEvB,SAAS,MACP,MACA,MACA,QACA,QAAQ,GACF;CACN,IAAI,QAAQ,kBAAkB,CAAC,cAAc,IAAI,GAAG;CACpD,IAAI,WAAW,IAAI,GAAG;EACpB,OAAO,MAAM,IAAI;EACjB,MAAM,OAAO,cAAc,IAAI,KAAK;EACpC,KAAK,MAAM,CAAC,OAAO,UAAU,aAAa,IAAI,CAAC,CAAC,QAAQ,GACtD,MAAM,OAAO,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,IAAI,QAAQ,QAAQ,CAAC;EAE7D;CACF;CACA,KAAK,MAAM,SAAS,YAAY,IAAI,GAAG,MAAM,OAAO,MAAM,QAAQ,QAAQ,CAAC;AAC7E;AAEA,SAAS,QAAQ,MAAe,MAAyB;CACvD,MAAM,OAAO,cAAc,IAAI,KAAK;CACpC,MAAM,WAAW,aAAa,IAAI;CAClC,MAAM,UAAU,SAAS,KAAK,UAAU,IAAI,IAAI,UAAU,KAAK,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC;CAE9E,MAAM,wBAAQ,IAAI,IAAY;CAC9B,KAAK,MAAM,OAAO,SAAS,KAAK,MAAM,OAAO,KAAK,MAAM,IAAI,GAAG;CAE/D,MAAM,gBAAoC,CAAC;CAC3C,KAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAClC,KAAK,IAAI,IAAI,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAAK;EAC3C,IAAI,QAAQ,EAAE,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC,SAAS,GAAG;EACpD,IAAI,CAAC,GAAG,QAAQ,EAAE,CAAC,CAAC,MAAM,QAAQ,QAAQ,EAAE,CAAC,IAAI,GAAG,CAAC,GAAG;EACxD,cAAc,KAAK,CAAC,GAAG,CAAC,CAAC;CAC3B;CAGF,MAAM,OAAO,SAAS,IAAI,YAAY;CACtC,MAAM,QAAQ,KAAK,QAAQ,UAA2B,OAAO,UAAU,QAAQ;CAC/E,OAAO;EACL;EACA;EACA,YAAY,SAAS;EACrB,WAAW,CAAC,GAAG,KAAK;EACpB,YAAY,CAAC,GAAG,KAAK,CAAC,CAAC,QAAQ,QAAQ,QAAQ,OAAO,QAAQ,IAAI,IAAI,GAAG,CAAC,CAAC;EAC3E;EACA,cAAc,MAAM,SAAS,IAAI,KAAK,IAAI,GAAG,KAAK,IAAI,KAAA;EACtD,gBAAgB,MAAM,WAAW,KAAK,UAAU,MAAM,SAAS,IAAI,QAAQ,KAAK,IAAI,KAAA;CACtF;AACF;AAEA,SAAS,QAAQ,MAAe,MAAc,UAAqC;CACjF,MAAM,QAAQ,QAAQ,MAAM,IAAI;CAChC,MAAM,WAAW,aAAa,IAAI;CAElC,IAAI,MAAM,cAAc,SAAS,GAC/B,SAAS,KAAK;EACZ,MAAM;EACN,UAAU;EACV;EACA,MAAM,MAAM;EACZ,QAAQ,sCAAsC,KAAK,UAAU,MAAM,aAAa;EAChF,gBAAgB,MAAM;CACxB,CAAC;CAGH,KAAK,MAAM,YAAY,aAAa,QAAQ,GAC1C,SAAS,KAAK;EACZ,MAAM;EACN,UAAU;EACV;EACA,MAAM,MAAM;EACZ,QAAQ,QAAQ,SAAS,KAAK,gBAAgB,SAAS,QAAQ,OAAO;EACtE,SAAS,SAAS;CACpB,CAAC;CAMH,IAAI,CAAC,gBAAgB,IAAI,MAAM,IAAI,KAAK,MAAM,cAAc,SAAS,GAAG;CACxE,MAAM,UAAU,SACb,KAAK,OAAO,UAAU;EACrB,MAAM,MAAM,IAAI,IAAI,UAAU,KAAK,CAAC,CAAC,IAAI,OAAO,CAAC;EACjD,OAAO;GAAE;GAAO,SAAS,MAAM,UAAU,QAAQ,QAAQ,CAAC,IAAI,IAAI,GAAG,CAAC;EAAE;CAC1E,CAAC,CAAC,CACD,QAAQ,UAAU,MAAM,QAAQ,SAAS,CAAC;CAC7C,IAAI,QAAQ,WAAW,GAAG;CAC1B,SAAS,KAAK;EACZ,MAAM;EACN,UAAU;EACV;EACA,MAAM,MAAM;EACZ,QAAQ,GAAG,QAAQ,OAAO;EAC1B;CACF,CAAC;AACH;AAIA,SAAS,aACP,UACuE;CACvE,MAAM,yBAAS,IAAI,IAAsC;CACzD,KAAK,MAAM,CAAC,OAAO,UAAU,SAAS,QAAQ,GAC5C,KAAK,MAAM,QAAQ,UAAU,KAAK,GAAG;EACnC,MAAM,UAAU,YAAY,IAAI;EAChC,IAAI,YAAY,OAAO,IAAI,OAAO;EAClC,IAAI,CAAC,WAAW,OAAO,IAAI,SAAU,4BAAY,IAAI,IAAI,CAAE;EAC3D,MAAM,YAAY,gBAAgB,KAAK,MAAM;EAC7C,IAAI,UAAU,UAAU,IAAI,SAAS;EACrC,IAAI,CAAC,SAAS,UAAU,IAAI,WAAY,0BAAU,IAAI,IAAI,CAAE;EAC5D,QAAQ,IAAI,KAAK;CACnB;CAEF,MAAM,MAA6E,CAAC;CACpF,KAAK,MAAM,CAAC,MAAM,cAAc,QAAQ;EACtC,IAAI,UAAU,OAAO,GAAG;EACxB,IAAI,KAAK;GACP;GACA,SAAS,CAAC,GAAG,UAAU,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,cAAc;IAC5D,QAAQ,UAAU;IAClB,UAAU,CAAC,GAAG,OAAO;GACvB,EAAE;EACJ,CAAC;CACH;CACA,OAAO;AACT;AAEA,SAAS,aAAa,MAAe,QAAQ,GAAuB;CAClE,IAAI,QAAQ,kBAAkB,CAAC,cAAc,IAAI,GAAG,OAAO,KAAA;CAC3D,IAAI,WAAW,IAAI,GAAG;EACpB,MAAM,OAAO,cAAc,IAAI,KAAK;EACpC,MAAM,OAAO,aAAa,IAAI,CAAC,CAC5B,KAAK,UAAU,aAAa,OAAO,QAAQ,CAAC,CAAC,CAAC,CAC9C,QAAQ,UAA2B,OAAO,UAAU,QAAQ;EAC/D,IAAI,KAAK,WAAW,GAAG,OAAO,KAAA;EAE9B,OAAO,gBAAgB,IAAI,IAAI,IAAI,KAAK,IAAI,GAAG,IAAI,IAAI,IAAI,IAAI;CACjE;CACA,MAAM,MAAM,QAAQ,IAAI;CACxB,IAAI,QAAQ,KAAA,GAAW,OAAO;CAC9B,MAAM,OAAO,YAAY,IAAI,CAAC,CAC3B,KAAK,UAAU,aAAa,OAAO,QAAQ,CAAC,CAAC,CAAC,CAC9C,QAAQ,UAA2B,OAAO,UAAU,QAAQ;CAC/D,OAAO,KAAK,SAAS,IAAI,KAAK,IAAI,GAAG,IAAI,IAAI,KAAA;AAC/C;AAEA,SAAS,eAAe,KAAwB;CAE9C,OADe,WAAW,GACd,CAAC,CACV,KAAK,UAAU,MAAM,YAAY,CAAC,CAClC,QAAQ,UAA2B,OAAO,UAAU,QAAQ;AACjE;AAEA,SAAS,QAAQ,MAAmC;CAClD,MAAM,SAAS,SAAS,IAAI;CAC5B,IAAI,CAAC,QAAQ,OAAO,KAAA;CACpB,KAAK,MAAM,OAAO,CAAC,QAAQ,UAAU,GAAG;EACtC,MAAM,UAAU,OAAO;EACvB,IAAI,CAAC,WAAW,OAAO,YAAY,UAAU;EAC7C,IAAI,OAAO,QAAQ,SAAS,UAAU,OAAO,QAAQ;EACrD,IAAI,OAAO,QAAQ,YAAY,UAAU,OAAO,QAAQ;CAC1D;AAEF;AAEA,SAAS,WAAW,MAAe,KAAkC,OAAqB;CACxF,IAAI,QAAQ,kBAAkB,CAAC,cAAc,IAAI,GAAG;CACpD,MAAM,SAAS,SAAS,IAAI;CAC5B,IAAI,QACF,KAAK,MAAM,OAAO,CAAC,YAAY,MAAM,GAAG;EACtC,MAAM,QAAQ,OAAO;EACrB,IAAI,CAAC,MAAM,QAAQ,KAAK,GAAG;EAC3B,KAAK,MAAM,QAAQ,OAAO;GACxB,MAAM,OAAO,OAAO,IAAI;GACxB,IAAI,MAAM,IAAI,IAAI,QAAQ,IAAI,GAAG,IAAI;EACvC;CACF;CAEF,KAAK,MAAM,SAAS,YAAY,IAAI,GAAG,WAAW,OAAO,KAAK,QAAQ,CAAC;AACzE;AAEA,SAAS,OAAO,OAA4C;CAC1D,MAAM,SAAS,SAAS,KAAK;CAC7B,IAAI,CAAC,QAAQ,OAAO,KAAA;CACpB,MAAM,EAAE,MAAM,MAAM,WAAW;CAC/B,IAAI,OAAO,SAAS,YAAY,OAAO,SAAS,UAAU,OAAO,KAAA;CACjE,OAAO;EAAE;EAAM;EAAM,QAAQ,eAAe,MAAM;CAAE;AACtD;AAEA,SAAS,eAAe,OAAoD;CAC1E,MAAM,SAAS,SAAS,KAAK;CAC7B,IAAI,CAAC,QAAQ,OAAO,KAAA;CACpB,MAAM,MAA8B,CAAC;CACrC,KAAK,MAAM,CAAC,KAAK,SAAS,OAAO,QAAQ,MAAM,GAC7C,IAAI,OAAO,SAAS,UAAU,IAAI,OAAO;CAE3C,OAAO,OAAO,KAAK,GAAG,CAAC,CAAC,SAAS,IAAI,MAAM,KAAA;AAC7C;AAEA,SAAS,gBAAgB,QAAoD;CAC3E,OAAO,OAAO,QAAQ,UAAU,CAAC,CAAC,CAAC,CAChC,MAAM,CAAC,MAAM,CAAC,SAAU,MAAM,MAAM,KAAK,CAAE,CAAC,CAC5C,KAAK,CAAC,KAAK,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC,CACxC,KAAK,GAAG;AACb;AAEA,SAAS,cAAc,MAAmC;CACxD,MAAM,OAAO,SAAS,IAAI,CAAC,EAAE;CAC7B,OAAO,OAAO,SAAS,WAAW,OAAO,KAAA;AAC3C;AAEA,SAAS,YAAY,MAA0B;CAC7C,IAAI,MAAM,QAAQ,IAAI,GAAG,OAAO;CAChC,MAAM,SAAS,SAAS,IAAI;CAC5B,OAAO,SAAS,OAAO,OAAO,MAAM,IAAI,CAAC;AAC3C;AAEA,SAAS,SAAS,OAAqD;CACrE,OAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK,IACrE,QACD,KAAA;AACN;AAEA,SAAS,cAAc,OAAyB;CAC9C,OAAO,OAAO,UAAU,YAAY,UAAU;AAChD;AAEA,SAAS,QAAQ,OAA2B;CAC1C,OAAO,MAAM,QAAQ,KAAK,IAAI,QAAQ,UAAU,KAAA,KAAa,UAAU,OAAO,CAAC,IAAI,CAAC,KAAK;AAC3F;AAEA,SAAS,IAAI,QAA0B;CACrC,OAAO,OAAO,QAAQ,KAAK,UAAU,MAAM,OAAO,CAAC;AACrD;AAEA,SAAS,QAAQ,QAA0B;CACzC,OAAO,OAAO,QAAQ,KAAK,UAAU,MAAM,OAAO,CAAC;AACrD"}

package/dist/sampler.d.ts

@@ -0,0 +1,22 @@
+//#region src/sampler.d.ts
+export type MemorySamplerOptions = {
+  dir: string;
+  sessionId: string;
+  /** Sampling period; 250 ms is roughly four short appends per second. */
+  intervalMs?: number;
+};
+export type MemorySampler = {
+  /** Sibling log the sampler appends to. */
+  readonly file: string;
+  stop(): void;
+};
+/**
+ * Starts the out-of-band memory sampler for a session.
+ *
+ * The sampler runs on a thread of its own with a small heap of its own, so it
+ * keeps producing readings when the observed thread is blocked and when the
+ * observed thread's heap is the thing that is full.
+ */
+export declare function startMemorySampler(options: MemorySamplerOptions): MemorySampler;
+//#endregion
+//# sourceMappingURL=sampler.d.ts.map

package/dist/sampler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler.d.ts","names":[],"sources":["../src/sampler.ts"],"mappings":";YAIY;EACV;EACA;;EAEA;;YAGU;;WAED;EACT;;;;;;;;;wBAUc,mBAAmB,SAAS,uBAAuB"}

package/dist/sampler.js

@@ -0,0 +1,33 @@
+import "./events.js";
+import path from "node:path";
+import { Worker } from "node:worker_threads";
+//#region src/sampler.ts
+/**
+* Starts the out-of-band memory sampler for a session.
+*
+* The sampler runs on a thread of its own with a small heap of its own, so it
+* keeps producing readings when the observed thread is blocked and when the
+* observed thread's heap is the thing that is full.
+*/
+function startMemorySampler(options) {
+	const { dir, sessionId, intervalMs = 250 } = options;
+	const file = path.join(dir, `mem-${sessionId}.ndjson`);
+	const worker = new Worker(new URL("./sampler_thread.js", import.meta.url), {
+		workerData: {
+			file,
+			intervalMs
+		},
+		resourceLimits: { maxOldGenerationSizeMb: 32 }
+	});
+	worker.unref();
+	return {
+		file,
+		stop: () => {
+			worker.terminate();
+		}
+	};
+}
+//#endregion
+export { startMemorySampler };
+
+//# sourceMappingURL=sampler.js.map

package/dist/sampler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler.js","names":[],"sources":["../src/sampler.ts"],"sourcesContent":["import path from \"node:path\";\nimport { Worker } from \"node:worker_threads\";\nimport { SAMPLER_FILE_PREFIX } from \"./events\";\n\nexport type MemorySamplerOptions = {\n  dir: string;\n  sessionId: string;\n  /** Sampling period; 250 ms is roughly four short appends per second. */\n  intervalMs?: number;\n};\n\nexport type MemorySampler = {\n  /** Sibling log the sampler appends to. */\n  readonly file: string;\n  stop(): void;\n};\n\n/**\n * Starts the out-of-band memory sampler for a session.\n *\n * The sampler runs on a thread of its own with a small heap of its own, so it\n * keeps producing readings when the observed thread is blocked and when the\n * observed thread's heap is the thing that is full.\n */\nexport function startMemorySampler(options: MemorySamplerOptions): MemorySampler {\n  const { dir, sessionId, intervalMs = 250 } = options;\n  const file = path.join(dir, `${SAMPLER_FILE_PREFIX}-${sessionId}.ndjson`);\n  const worker = new Worker(new URL(\"./sampler_thread.js\", import.meta.url), {\n    workerData: { file, intervalMs },\n    resourceLimits: { maxOldGenerationSizeMb: 32 },\n  });\n  // Unreferenced so a sampler that is never stopped cannot hold the process open.\n  worker.unref();\n  return {\n    file,\n    stop: () => {\n      void worker.terminate();\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;AAwBA,SAAgB,mBAAmB,SAA8C;CAC/E,MAAM,EAAE,KAAK,WAAW,aAAa,QAAQ;CAC7C,MAAM,OAAO,KAAK,KAAK,KAAK,OAA0B,UAAU,QAAQ;CACxE,MAAM,SAAS,IAAI,OAAO,IAAI,IAAI,uBAAuB,OAAO,KAAK,GAAG,GAAG;EACzE,YAAY;GAAE;GAAM;EAAW;EAC/B,gBAAgB,EAAE,wBAAwB,GAAG;CAC/C,CAAC;CAED,OAAO,MAAM;CACb,OAAO;EACL;EACA,YAAY;GACV,OAAY,UAAU;EACxB;CACF;AACF"}

package/dist/sampler_thread.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/sampler_thread.js

@@ -0,0 +1,41 @@
+import fs from "node:fs";
+import os from "node:os";
+import { workerData } from "node:worker_threads";
+//#region src/sampler_thread.ts
+/**
+* Memory sampler, run on its own worker thread.
+*
+* It exists because the thread worth watching is the one that blocks. While the
+* middle layer sits inside a synchronous pframes call its own timers do not
+* fire, so its memory series goes dark exactly while memory is growing fastest.
+* This thread stays responsive and keeps the resident-size curve intact right up
+* to the moment the process dies.
+*
+* `rss` and `freeMemory` are process- and machine-wide and so are meaningful
+* from here. Heap figures are per-isolate and would describe only this thread,
+* so they are deliberately not recorded; the observed thread reports its own.
+*/
+const { file, intervalMs } = workerData;
+const fd = fs.openSync(file, "a");
+let seq = 0;
+let peakRss = 0;
+setInterval(() => {
+	const rss = process.memoryUsage.rss();
+	if (rss > peakRss) peakRss = rss;
+	const record = {
+		seq: ++seq,
+		t: Math.round(performance.now() * 1e3) / 1e3,
+		wall: Date.now(),
+		type: "mem-sampler",
+		rss,
+		peakRss,
+		freeMemory: os.freemem(),
+		totalMemory: os.totalmem()
+	};
+	try {
+		fs.writeSync(fd, `${JSON.stringify(record)}\n`);
+	} catch {}
+}, intervalMs);
+//#endregion
+
+//# sourceMappingURL=sampler_thread.js.map

package/dist/sampler_thread.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler_thread.js","names":[],"sources":["../src/sampler_thread.ts"],"sourcesContent":["/**\n * Memory sampler, run on its own worker thread.\n *\n * It exists because the thread worth watching is the one that blocks. While the\n * middle layer sits inside a synchronous pframes call its own timers do not\n * fire, so its memory series goes dark exactly while memory is growing fastest.\n * This thread stays responsive and keeps the resident-size curve intact right up\n * to the moment the process dies.\n *\n * `rss` and `freeMemory` are process- and machine-wide and so are meaningful\n * from here. Heap figures are per-isolate and would describe only this thread,\n * so they are deliberately not recorded; the observed thread reports its own.\n */\n\nimport fs from \"node:fs\";\nimport os from \"node:os\";\nimport { workerData } from \"node:worker_threads\";\nimport type { SamplerRecord } from \"./events\";\n\ntype SamplerWorkerData = { file: string; intervalMs: number };\n\nconst { file, intervalMs } = workerData as SamplerWorkerData;\nconst fd = fs.openSync(file, \"a\");\nlet seq = 0;\nlet peakRss = 0;\n\nsetInterval(() => {\n  const rss = process.memoryUsage.rss();\n  if (rss > peakRss) peakRss = rss;\n  const record: SamplerRecord = {\n    seq: ++seq,\n    t: Math.round(performance.now() * 1000) / 1000,\n    wall: Date.now(),\n    type: \"mem-sampler\",\n    rss,\n    peakRss,\n    freeMemory: os.freemem(),\n    totalMemory: os.totalmem(),\n  };\n  try {\n    fs.writeSync(fd, `${JSON.stringify(record)}\\n`);\n  } catch {\n    // Sampling must never take the application down.\n  }\n}, intervalMs);\n"],"mappings":";;;;;;;;;;;;;;;;;AAqBA,MAAM,EAAE,MAAM,eAAe;AAC7B,MAAM,KAAK,GAAG,SAAS,MAAM,GAAG;AAChC,IAAI,MAAM;AACV,IAAI,UAAU;AAEd,kBAAkB;CAChB,MAAM,MAAM,QAAQ,YAAY,IAAI;CACpC,IAAI,MAAM,SAAS,UAAU;CAC7B,MAAM,SAAwB;EAC5B,KAAK,EAAE;EACP,GAAG,KAAK,MAAM,YAAY,IAAI,IAAI,GAAI,IAAI;EAC1C,MAAM,KAAK,IAAI;EACf,MAAM;EACN;EACA;EACA,YAAY,GAAG,QAAQ;EACvB,aAAa,GAAG,SAAS;CAC3B;CACA,IAAI;EACF,GAAG,UAAU,IAAI,GAAG,KAAK,UAAU,MAAM,EAAE,GAAG;CAChD,QAAQ,CAER;AACF,GAAG,UAAU"}

package/dist/session.d.ts

@@ -0,0 +1,40 @@
+import { Recorder } from "./recorder.js";
+import { MemorySampler } from "./sampler.js";
+import { HandleRegistry } from "./instrument.js";
+//#region src/session.d.ts
+/** Environment variable naming the directory flight logs are written to. */
+export declare const FLIGHT_DIR_ENV = "MI_FLIGHT_RECORDER_DIR";
+/**
+ * Environment variable carrying the session id a supervising parent assigned.
+ * Set it alongside {@link FLIGHT_DIR_ENV} when spawning the worker and pass the
+ * same id to `superviseWorker`.
+ */
+export declare const FLIGHT_SESSION_ENV = "MI_FLIGHT_RECORDER_SESSION";
+export type FlightSessionOptions = {
+  /** Overrides the directory from the environment. */
+  dir?: string;
+  /** Overrides the session id from the environment. */
+  sessionId?: string;
+  role?: string;
+  meta?: Record<string, unknown>;
+  samplerIntervalMs?: number;
+  selfSamplerIntervalMs?: number;
+};
+export type FlightSession = {
+  readonly recorder: Recorder;
+  readonly sampler: MemorySampler;
+  /** Shared so create calls and later data calls agree on handle identity. */
+  readonly registry: HandleRegistry;
+  close(reason?: string): void;
+};
+/**
+ * Opens a flight session, or returns undefined when recording is not enabled.
+ *
+ * Recording is opt-in for now: it appends synchronously on every recorded
+ * operation, and that cost has not been measured against a real project, so it
+ * is switched on by pointing {@link FLIGHT_DIR_ENV} at a directory rather than
+ * being on by default.
+ */
+export declare function openFlightSession(options?: FlightSessionOptions): FlightSession | undefined;
+//#endregion
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","names":[],"sources":["../src/session.ts"],"mappings":";;;;;qBAKa;;;;;;qBAOA;YAED;;EAEV;;EAEA;EACA;EACA,OAAO;EACP;EACA;;YAGU;WACD,UAAU;WACV,SAAS;;WAET,UAAU;EACnB,MAAM;;;;;;;;;;wBAWQ,kBAAkB,UAAS,uBAA4B"}

package/dist/session.js

@@ -0,0 +1,50 @@
+import { openRecorder, startSelfSampler } from "./recorder.js";
+import { startMemorySampler } from "./sampler.js";
+import { createHandleRegistry } from "./instrument.js";
+//#region src/session.ts
+/** Environment variable naming the directory flight logs are written to. */
+const FLIGHT_DIR_ENV = "MI_FLIGHT_RECORDER_DIR";
+/**
+* Environment variable carrying the session id a supervising parent assigned.
+* Set it alongside {@link FLIGHT_DIR_ENV} when spawning the worker and pass the
+* same id to `superviseWorker`.
+*/
+const FLIGHT_SESSION_ENV = "MI_FLIGHT_RECORDER_SESSION";
+/**
+* Opens a flight session, or returns undefined when recording is not enabled.
+*
+* Recording is opt-in for now: it appends synchronously on every recorded
+* operation, and that cost has not been measured against a real project, so it
+* is switched on by pointing {@link FLIGHT_DIR_ENV} at a directory rather than
+* being on by default.
+*/
+function openFlightSession(options = {}) {
+	const dir = options.dir ?? process.env["MI_FLIGHT_RECORDER_DIR"];
+	if (!dir) return void 0;
+	const recorder = openRecorder({
+		dir,
+		role: options.role,
+		meta: options.meta,
+		sessionId: options.sessionId ?? process.env["MI_FLIGHT_RECORDER_SESSION"] ?? void 0
+	});
+	const sampler = startMemorySampler({
+		dir,
+		sessionId: recorder.sessionId,
+		intervalMs: options.samplerIntervalMs
+	});
+	const stopSelfSampler = startSelfSampler(recorder, options.selfSamplerIntervalMs);
+	return {
+		recorder,
+		sampler,
+		registry: createHandleRegistry(),
+		close(reason) {
+			stopSelfSampler();
+			sampler.stop();
+			recorder.close(reason);
+		}
+	};
+}
+//#endregion
+export { FLIGHT_DIR_ENV, FLIGHT_SESSION_ENV, openFlightSession };
+
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","names":[],"sources":["../src/session.ts"],"sourcesContent":["import { openRecorder, startSelfSampler, type Recorder } from \"./recorder\";\nimport { startMemorySampler, type MemorySampler } from \"./sampler\";\nimport { createHandleRegistry, type HandleRegistry } from \"./instrument\";\n\n/** Environment variable naming the directory flight logs are written to. */\nexport const FLIGHT_DIR_ENV = \"MI_FLIGHT_RECORDER_DIR\";\n\n/**\n * Environment variable carrying the session id a supervising parent assigned.\n * Set it alongside {@link FLIGHT_DIR_ENV} when spawning the worker and pass the\n * same id to `superviseWorker`.\n */\nexport const FLIGHT_SESSION_ENV = \"MI_FLIGHT_RECORDER_SESSION\";\n\nexport type FlightSessionOptions = {\n  /** Overrides the directory from the environment. */\n  dir?: string;\n  /** Overrides the session id from the environment. */\n  sessionId?: string;\n  role?: string;\n  meta?: Record<string, unknown>;\n  samplerIntervalMs?: number;\n  selfSamplerIntervalMs?: number;\n};\n\nexport type FlightSession = {\n  readonly recorder: Recorder;\n  readonly sampler: MemorySampler;\n  /** Shared so create calls and later data calls agree on handle identity. */\n  readonly registry: HandleRegistry;\n  close(reason?: string): void;\n};\n\n/**\n * Opens a flight session, or returns undefined when recording is not enabled.\n *\n * Recording is opt-in for now: it appends synchronously on every recorded\n * operation, and that cost has not been measured against a real project, so it\n * is switched on by pointing {@link FLIGHT_DIR_ENV} at a directory rather than\n * being on by default.\n */\nexport function openFlightSession(options: FlightSessionOptions = {}): FlightSession | undefined {\n  const dir = options.dir ?? process.env[FLIGHT_DIR_ENV];\n  if (!dir) return undefined;\n\n  const recorder = openRecorder({\n    dir,\n    role: options.role,\n    meta: options.meta,\n    sessionId: options.sessionId ?? process.env[FLIGHT_SESSION_ENV] ?? undefined,\n  });\n  const sampler = startMemorySampler({\n    dir,\n    sessionId: recorder.sessionId,\n    intervalMs: options.samplerIntervalMs,\n  });\n  const stopSelfSampler = startSelfSampler(recorder, options.selfSamplerIntervalMs);\n\n  return {\n    recorder,\n    sampler,\n    registry: createHandleRegistry(),\n    close(reason) {\n      stopSelfSampler();\n      sampler.stop();\n      recorder.close(reason);\n    },\n  };\n}\n"],"mappings":";;;;;AAKA,MAAa,iBAAiB;;;;;;AAO9B,MAAa,qBAAqB;;;;;;;;;AA6BlC,SAAgB,kBAAkB,UAAgC,CAAC,GAA8B;CAC/F,MAAM,MAAM,QAAQ,OAAO,QAAQ,IAAA;CACnC,IAAI,CAAC,KAAK,OAAO,KAAA;CAEjB,MAAM,WAAW,aAAa;EAC5B;EACA,MAAM,QAAQ;EACd,MAAM,QAAQ;EACd,WAAW,QAAQ,aAAa,QAAQ,IAAA,iCAA2B,KAAA;CACrE,CAAC;CACD,MAAM,UAAU,mBAAmB;EACjC;EACA,WAAW,SAAS;EACpB,YAAY,QAAQ;CACtB,CAAC;CACD,MAAM,kBAAkB,iBAAiB,UAAU,QAAQ,qBAAqB;CAEhF,OAAO;EACL;EACA;EACA,UAAU,qBAAqB;EAC/B,MAAM,QAAQ;GACZ,gBAAgB;GAChB,QAAQ,KAAK;GACb,SAAS,MAAM,MAAM;EACvB;CACF;AACF"}

package/dist/supervisor.d.ts

@@ -0,0 +1,58 @@
+import { CrashMarker, CrashReason } from "./events.js";
+//#region src/supervisor.d.ts
+export type CrashMarkerInput = {
+  /** Session id the parent assigned to the worker. Omitted, the marker carries no identity. */
+  sessionId?: string;
+  reason?: CrashReason;
+  error?: (Error & {
+    code?: string;
+  }) | unknown;
+  code?: number;
+  signal?: string;
+  stderrTail?: string;
+};
+export type SuperviseOptions = {
+  /**
+   * The session id handed to the worker at spawn (see `FLIGHT_SESSION_ENV`).
+   * With it the marker names the dying session with certainty. Without it the
+   * analyzer has to attribute the marker by timing, and will decline to
+   * attribute it at all when more than one session looks dead.
+   */
+  sessionId?: string;
+  onCrash?: (info: {
+    kind: "error" | "exit";
+    markerFile: string;
+    error?: unknown;
+    code?: number;
+  }) => void;
+};
+/** Minimal view of a worker, so callers are not forced to import worker_threads. */
+export type SupervisedWorker = {
+  on(event: "error", listener: (error: Error) => void): unknown;
+  on(event: "exit", listener: (code: number) => void): unknown;
+};
+/**
+ * Records an abnormal end observed from outside the dying thread.
+ *
+ * A thread that runs out of heap cannot describe its own death: the last reading
+ * it wrote predates the blow-up, and when the blow-up is synchronous no sampler
+ * tick of its own lands either. The parent is the only place where the cause is
+ * known rather than inferred — Node reports `ERR_WORKER_OUT_OF_MEMORY` to it —
+ * so the parent writes the verdict down on the dead thread's behalf.
+ */
+export declare function writeCrashMarker(dir: string, input?: CrashMarkerInput): string;
+/** Crash markers in a directory, oldest first. */
+export declare function readCrashMarkers(dir: string): CrashMarker[];
+/**
+ * Attaches crash recording to a middle-layer worker thread.
+ *
+ * A worker whose isolate exhausts its heap dies alone and the parent receives
+ * `ERR_WORKER_OUT_OF_MEMORY`, with or without `resourceLimits`. What
+ * `resourceLimits.maxOldGenerationSizeMb` adds is a chosen ceiling: V8's default
+ * is several gigabytes, so on a small machine the OS can run out of memory and
+ * kill the whole process before V8 ever reports the worker's heap as full — and
+ * then there is no parent left to write anything.
+ */
+export declare function superviseWorker(worker: SupervisedWorker, dir: string, options?: SuperviseOptions): void;
+//#endregion
+//# sourceMappingURL=supervisor.d.ts.map

package/dist/supervisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.d.ts","names":[],"sources":["../src/supervisor.ts"],"mappings":";;YAKY;;EAEV;EACA,SAAS;EACT,SAAS;IAAU;;EACnB;EACA;EACA;;YAGU;;;;;;;EAOV;EACA,WAAW;IACT;IACA;IACA;IACA;;;;YAKQ;EACV,GAAG,gBAAgB,WAAW,OAAO;EACrC,GAAG,eAAe,WAAW;;;;;;;;;;;wBAYf,iBAAiB,aAAa,QAAO;;wBA2BrC,iBAAiB,cAAc;;;;;;;;;;;wBA+B/B,gBACd,QAAQ,kBACR,aACA,UAAS"}