@milaboratories/pl-flight-recorder 0.2.0

package/dist/recorder.js

@@ -0,0 +1,293 @@
+import { FLIGHT_FILE_PREFIX, MEM_BASELINE_RECORD, SESSION_END_RECORD, SESSION_RECORD } from "./events.js";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import v8 from "node:v8";
+//#region src/recorder.ts
+/**
+* Opens a flight log for this process and writes the session header.
+*
+* Records are appended with a synchronous write rather than through a stream:
+* the process being recorded dies without warning — V8 fatal out-of-memory, a
+* failed native allocation, the OS out-of-memory killer — so no exit hook, no
+* flush and no `finally` block runs. Anything still sitting in a userspace
+* buffer is exactly the part that would have explained the death.
+*/
+function openRecorder(options) {
+	const { dir, role = "middle-layer", meta = {}, maxFileBytes = 32 * 1024 * 1024, sessionId = newSessionId() } = options;
+	fs.mkdirSync(dir, { recursive: true });
+	const file = path.join(dir, `${FLIGHT_FILE_PREFIX}-${sessionId}.ndjson`);
+	const state = {
+		fd: fs.openSync(file, "a"),
+		bytes: 0,
+		preambleBytes: 0,
+		seq: 0,
+		closed: false,
+		header: void 0,
+		baselineMem: void 0,
+		openBegins: /* @__PURE__ */ new Map()
+	};
+	const memorySnapshot = () => {
+		const usage = process.memoryUsage();
+		return {
+			rss: usage.rss,
+			heapUsed: usage.heapUsed,
+			heapTotal: usage.heapTotal,
+			external: usage.external,
+			arrayBuffers: usage.arrayBuffers,
+			heapLimit: v8.getHeapStatistics().heap_size_limit
+		};
+	};
+	const event = (type, payload = {}) => {
+		if (state.closed) return -1;
+		const seq = ++state.seq;
+		const record = {
+			seq,
+			t: monotonic(),
+			wall: Date.now(),
+			type,
+			...payload
+		};
+		if (state.baselineMem === void 0 && record.mem) state.baselineMem = record.mem;
+		trackOpenOperation(state, record);
+		writeLine(state, file, maxFileBytes, record);
+		return seq;
+	};
+	const recorder = {
+		sessionId,
+		file,
+		event,
+		memorySnapshot,
+		close(reason = "normal") {
+			if (state.closed) return;
+			event(SESSION_END_RECORD, {
+				reason,
+				mem: memorySnapshot()
+			});
+			state.closed = true;
+			try {
+				fs.closeSync(state.fd);
+			} catch {}
+		}
+	};
+	state.header = {
+		role,
+		pid: process.pid,
+		meta,
+		env: describeEnvironment()
+	};
+	event(SESSION_RECORD, {
+		...state.header,
+		mem: memorySnapshot()
+	});
+	return recorder;
+}
+/**
+* Periodic memory record written by the recorded thread itself.
+*
+* Doubles as a stall detector. This timer cannot fire while its thread is inside
+* a long synchronous call, so a gap here that the independent sampler thread
+* does not share means the thread was blocked — which is also why the heap
+* reading nearest a synchronous blow-up is always stale.
+*/
+function startSelfSampler(recorder, intervalMs = 500) {
+	let last = Date.now();
+	const timer = setInterval(() => {
+		const now = Date.now();
+		recorder.event("mem-self", {
+			mem: recorder.memorySnapshot(),
+			stallMs: Math.max(0, now - last - intervalMs)
+		});
+		last = now;
+	}, intervalMs);
+	timer.unref();
+	return () => clearInterval(timer);
+}
+/** Flight logs in a directory, newest first, each flagged as crashed or clean. */
+function listSessions(dir) {
+	let names;
+	try {
+		names = fs.readdirSync(dir);
+	} catch {
+		return [];
+	}
+	return names.filter((name) => name.startsWith(`flight-`) && name.endsWith(".ndjson")).map((name) => {
+		const file = path.join(dir, name);
+		const stat = fs.statSync(file);
+		return {
+			file,
+			mtimeMs: stat.mtimeMs,
+			bytes: stat.size,
+			crashed: !hasSessionEnd(file)
+		};
+	}).sort((lhs, rhs) => rhs.mtimeMs - lhs.mtimeMs);
+}
+/**
+* Parses a flight log, tolerating a final line cut short by a hard kill.
+*
+* A rotated session spans two files: the parked `.1` segment holds the original
+* header and the earlier operations, the active file holds the tail. Both are
+* read so begin records in one segment can be paired with end records in the
+* other; sequence numbers run across the boundary.
+*/
+function readSession(file) {
+	const records = [];
+	let truncatedTail = false;
+	const parked = `${file}.1`;
+	if (fs.existsSync(parked)) for (const line of fs.readFileSync(parked, "utf8").split("\n")) {
+		if (line === "") continue;
+		try {
+			records.push(JSON.parse(line));
+		} catch {}
+	}
+	const lines = fs.readFileSync(file, "utf8").split("\n");
+	for (const [index, line] of lines.entries()) {
+		if (line === "") continue;
+		try {
+			records.push(JSON.parse(line));
+		} catch {
+			if (index >= lines.length - 2) truncatedTail = true;
+		}
+	}
+	return {
+		file,
+		records,
+		truncatedTail
+	};
+}
+/**
+* Mints a session id. A parent that supervises a worker calls this, hands the id
+* to the worker, and keeps it for the crash marker, so both sides agree on the
+* session by construction. The leading timestamp is what
+* {@link sessionStartFromId} reads back.
+*/
+function newSessionId() {
+	return `${Date.now()}-${process.pid}-${randomTag()}`;
+}
+/** Wall-clock start of a session, taken from the id its file name carries. */
+function sessionStartFromId(sessionId) {
+	const start = Number(sessionId.split("-")[0]);
+	return Number.isFinite(start) ? start : 0;
+}
+/** Session id embedded in a flight log's file name. */
+function sessionIdFromFile(file) {
+	const match = path.basename(file).match(/^flight-(.+)\.ndjson(\.1)?$/);
+	return match ? match[1] : path.basename(file);
+}
+/** Cap on carried-forward begins, so a leak cannot make the preamble unbounded. */
+const MAX_CARRIED_BEGINS = 256;
+function writeLine(state, file, maxFileBytes, record) {
+	let line;
+	try {
+		line = `${JSON.stringify(record, bigintSafe)}\n`;
+	} catch {
+		line = `${JSON.stringify({
+			seq: record.seq,
+			type: "record-serialization-failed"
+		})}\n`;
+	}
+	try {
+		if (state.bytes - state.preambleBytes + line.length > maxFileBytes) {
+			rotate(state, file);
+			writePreamble(state);
+		}
+		fs.writeSync(state.fd, line);
+		state.bytes += line.length;
+	} catch {}
+}
+function rotate(state, file) {
+	fs.closeSync(state.fd);
+	try {
+		fs.renameSync(file, `${file}.1`);
+	} catch {}
+	state.fd = fs.openSync(file, "a");
+	state.bytes = 0;
+	state.preambleBytes = 0;
+}
+/**
+* Rewrites into the new segment the three things a report cannot be produced
+* without, so repeated rotation costs only completed operations.
+*
+* Losing an *open* begin record would remove that operation from pairing
+* entirely, and the operation still running at the moment of death is the one
+* the report exists to name. Losing the earliest memory reading would leave the
+* heap series starting mid-session while the sampler's resident series still
+* starts at zero, which biases the classifier toward blaming native memory.
+*/
+function writePreamble(state) {
+	if (state.header) emitPreambleRecord(state, {
+		seq: ++state.seq,
+		t: monotonic(),
+		wall: Date.now(),
+		type: SESSION_RECORD,
+		...state.header,
+		continuation: true
+	});
+	if (state.baselineMem) emitPreambleRecord(state, {
+		seq: ++state.seq,
+		t: monotonic(),
+		wall: Date.now(),
+		type: MEM_BASELINE_RECORD,
+		mem: state.baselineMem,
+		carriedForward: true
+	});
+	for (const begin of state.openBegins.values()) emitPreambleRecord(state, {
+		...begin,
+		carriedForward: true
+	});
+}
+function emitPreambleRecord(state, record) {
+	try {
+		const line = `${JSON.stringify(record, bigintSafe)}\n`;
+		fs.writeSync(state.fd, line);
+		state.bytes += line.length;
+		state.preambleBytes += line.length;
+	} catch {}
+}
+function trackOpenOperation(state, record) {
+	if (record.type.endsWith("-begin")) {
+		if (state.openBegins.size < MAX_CARRIED_BEGINS) state.openBegins.set(record.seq, record);
+		return;
+	}
+	if (record.type.endsWith("-end") || record.type.endsWith("-error")) {
+		if (typeof record.begin === "number") state.openBegins.delete(record.begin);
+	}
+}
+function hasSessionEnd(file) {
+	const size = fs.statSync(file).size;
+	if (size === 0) return false;
+	const window = Math.min(size, 8192);
+	const buffer = Buffer.alloc(window);
+	const fd = fs.openSync(file, "r");
+	try {
+		fs.readSync(fd, buffer, 0, window, size - window);
+	} finally {
+		fs.closeSync(fd);
+	}
+	return buffer.toString("utf8").includes(`"type":"${SESSION_END_RECORD}"`);
+}
+function describeEnvironment() {
+	const maxOldSpaceFlag = process.execArgv.find((arg) => arg.startsWith("--max-old-space-size"));
+	return {
+		node: process.version,
+		platform: `${process.platform}-${process.arch}`,
+		cpus: os.cpus().length,
+		totalMemory: os.totalmem(),
+		heapLimit: v8.getHeapStatistics().heap_size_limit,
+		execArgv: [...process.execArgv],
+		maxOldSpaceSize: maxOldSpaceFlag ? Number(maxOldSpaceFlag.split("=")[1]) : void 0
+	};
+}
+function bigintSafe(_key, value) {
+	return typeof value === "bigint" ? Number(value) : value;
+}
+function monotonic() {
+	return Math.round(performance.now() * 1e3) / 1e3;
+}
+function randomTag() {
+	return Math.random().toString(36).slice(2, 8);
+}
+//#endregion
+export { listSessions, newSessionId, openRecorder, readSession, sessionIdFromFile, sessionStartFromId, startSelfSampler };
+
+//# sourceMappingURL=recorder.js.map

package/dist/recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.js","names":[],"sources":["../src/recorder.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport os from \"node:os\";\nimport v8 from \"node:v8\";\nimport {\n  FLIGHT_FILE_PREFIX,\n  MEM_BASELINE_RECORD,\n  SESSION_END_RECORD,\n  SESSION_RECORD,\n  type FlightRecord,\n  type MemorySnapshot,\n  type SessionEnvironment,\n} from \"./events\";\n\nexport type RecorderOptions = {\n  /** Directory holding flight logs; created if absent. */\n  dir: string;\n  /** Which part of the app is recording, e.g. `middle-layer`. */\n  role?: string;\n  /** Free-form context stored in the session header (app version, project id). */\n  meta?: Record<string, unknown>;\n  /** Log is rotated past this size so the tail, which explains the crash, survives. */\n  maxFileBytes?: number;\n  /**\n   * Session id assigned by a supervising parent, so the crash marker the parent\n   * writes names this session with certainty rather than by inference.\n   * Generated when absent.\n   */\n  sessionId?: string;\n};\n\nexport type Recorder = {\n  readonly sessionId: string;\n  readonly file: string;\n  /** Appends one record and returns its sequence number. Never throws. */\n  event(type: string, payload?: Record<string, unknown>): number;\n  /** Memory reading for the calling thread; `rss` is process-wide. */\n  memorySnapshot(): MemorySnapshot;\n  /** Writes the terminating record. Its absence is how a crash is detected. */\n  close(reason?: string): void;\n};\n\nexport type SessionFileInfo = {\n  file: string;\n  mtimeMs: number;\n  bytes: number;\n  /** True when the log has no terminating record, i.e. the process died. */\n  crashed: boolean;\n};\n\nexport type ParsedSession = {\n  file: string;\n  records: FlightRecord[];\n  /** True when the last line was cut mid-write by the kill. */\n  truncatedTail: boolean;\n};\n\n/**\n * Opens a flight log for this process and writes the session header.\n *\n * Records are appended with a synchronous write rather than through a stream:\n * the process being recorded dies without warning — V8 fatal out-of-memory, a\n * failed native allocation, the OS out-of-memory killer — so no exit hook, no\n * flush and no `finally` block runs. Anything still sitting in a userspace\n * buffer is exactly the part that would have explained the death.\n */\nexport function openRecorder(options: RecorderOptions): Recorder {\n  const {\n    dir,\n    role = \"middle-layer\",\n    meta = {},\n    maxFileBytes = 32 * 1024 * 1024,\n    sessionId = newSessionId(),\n  } = options;\n  fs.mkdirSync(dir, { recursive: true });\n\n  const file = path.join(dir, `${FLIGHT_FILE_PREFIX}-${sessionId}.ndjson`);\n  const state: WriterState = {\n    fd: fs.openSync(file, \"a\"),\n    bytes: 0,\n    preambleBytes: 0,\n    seq: 0,\n    closed: false,\n    header: undefined,\n    baselineMem: undefined,\n    openBegins: new Map(),\n  };\n\n  const memorySnapshot = (): MemorySnapshot => {\n    const usage = process.memoryUsage();\n    return {\n      rss: usage.rss,\n      heapUsed: usage.heapUsed,\n      heapTotal: usage.heapTotal,\n      external: usage.external,\n      arrayBuffers: usage.arrayBuffers,\n      heapLimit: v8.getHeapStatistics().heap_size_limit,\n    };\n  };\n\n  const event = (type: string, payload: Record<string, unknown> = {}): number => {\n    if (state.closed) return -1;\n    const seq = ++state.seq;\n    const record: FlightRecord = {\n      seq,\n      t: monotonic(),\n      wall: Date.now(),\n      type,\n      ...payload,\n    };\n    if (state.baselineMem === undefined && record.mem) state.baselineMem = record.mem;\n    trackOpenOperation(state, record);\n    writeLine(state, file, maxFileBytes, record);\n    return seq;\n  };\n\n  const recorder: Recorder = {\n    sessionId,\n    file,\n    event,\n    memorySnapshot,\n    close(reason = \"normal\") {\n      if (state.closed) return;\n      event(SESSION_END_RECORD, { reason, mem: memorySnapshot() });\n      state.closed = true;\n      try {\n        fs.closeSync(state.fd);\n      } catch {\n        // Closing an already-dead descriptor must not fail shutdown.\n      }\n    },\n  };\n\n  // Kept so a rotated log can be given the same header again: the active file\n  // must describe its own session even if the parked segment is lost.\n  state.header = { role, pid: process.pid, meta, env: describeEnvironment() };\n  event(SESSION_RECORD, { ...state.header, mem: memorySnapshot() });\n\n  return recorder;\n}\n\n/**\n * Periodic memory record written by the recorded thread itself.\n *\n * Doubles as a stall detector. This timer cannot fire while its thread is inside\n * a long synchronous call, so a gap here that the independent sampler thread\n * does not share means the thread was blocked — which is also why the heap\n * reading nearest a synchronous blow-up is always stale.\n */\nexport function startSelfSampler(recorder: Recorder, intervalMs = 500): () => void {\n  let last = Date.now();\n  const timer = setInterval(() => {\n    const now = Date.now();\n    recorder.event(\"mem-self\", {\n      mem: recorder.memorySnapshot(),\n      stallMs: Math.max(0, now - last - intervalMs),\n    });\n    last = now;\n  }, intervalMs);\n  timer.unref();\n  return () => clearInterval(timer);\n}\n\n/** Flight logs in a directory, newest first, each flagged as crashed or clean. */\nexport function listSessions(dir: string): SessionFileInfo[] {\n  let names: string[];\n  try {\n    names = fs.readdirSync(dir);\n  } catch {\n    return [];\n  }\n  return names\n    .filter((name) => name.startsWith(`${FLIGHT_FILE_PREFIX}-`) && name.endsWith(\".ndjson\"))\n    .map((name) => {\n      const file = path.join(dir, name);\n      const stat = fs.statSync(file);\n      return { file, mtimeMs: stat.mtimeMs, bytes: stat.size, crashed: !hasSessionEnd(file) };\n    })\n    .sort((lhs, rhs) => rhs.mtimeMs - lhs.mtimeMs);\n}\n\n/**\n * Parses a flight log, tolerating a final line cut short by a hard kill.\n *\n * A rotated session spans two files: the parked `.1` segment holds the original\n * header and the earlier operations, the active file holds the tail. Both are\n * read so begin records in one segment can be paired with end records in the\n * other; sequence numbers run across the boundary.\n */\nexport function readSession(file: string): ParsedSession {\n  const records: FlightRecord[] = [];\n  let truncatedTail = false;\n  const parked = `${file}.1`;\n  if (fs.existsSync(parked)) {\n    for (const line of fs.readFileSync(parked, \"utf8\").split(\"\\n\")) {\n      if (line === \"\") continue;\n      try {\n        records.push(JSON.parse(line) as FlightRecord);\n      } catch {\n        // A damaged line in the parked segment costs one record, not the session.\n      }\n    }\n  }\n  const lines = fs.readFileSync(file, \"utf8\").split(\"\\n\");\n  for (const [index, line] of lines.entries()) {\n    if (line === \"\") continue;\n    try {\n      records.push(JSON.parse(line) as FlightRecord);\n    } catch {\n      if (index >= lines.length - 2) truncatedTail = true;\n    }\n  }\n  return { file, records, truncatedTail };\n}\n\n/**\n * Mints a session id. A parent that supervises a worker calls this, hands the id\n * to the worker, and keeps it for the crash marker, so both sides agree on the\n * session by construction. The leading timestamp is what\n * {@link sessionStartFromId} reads back.\n */\nexport function newSessionId(): string {\n  return `${Date.now()}-${process.pid}-${randomTag()}`;\n}\n\n/** Wall-clock start of a session, taken from the id its file name carries. */\nexport function sessionStartFromId(sessionId: string): number {\n  const start = Number(sessionId.split(\"-\")[0]);\n  return Number.isFinite(start) ? start : 0;\n}\n\n/** Session id embedded in a flight log's file name. */\nexport function sessionIdFromFile(file: string): string {\n  const match = path.basename(file).match(/^flight-(.+)\\.ndjson(\\.1)?$/);\n  return match ? match[1] : path.basename(file);\n}\n\n// Internals\n\ntype WriterState = {\n  fd: number;\n  bytes: number;\n  /** Bytes of the carried-forward preamble, which do not count toward the limit. */\n  preambleBytes: number;\n  seq: number;\n  closed: boolean;\n  header: Record<string, unknown> | undefined;\n  /** Earliest memory reading of the session, so growth stays measurable. */\n  baselineMem: MemorySnapshot | undefined;\n  /** Begin records with no end yet, keyed by their sequence number. */\n  openBegins: Map<number, FlightRecord>;\n};\n\n/** Cap on carried-forward begins, so a leak cannot make the preamble unbounded. */\nconst MAX_CARRIED_BEGINS = 256;\n\nfunction writeLine(\n  state: WriterState,\n  file: string,\n  maxFileBytes: number,\n  record: FlightRecord,\n): void {\n  let line: string;\n  try {\n    line = `${JSON.stringify(record, bigintSafe)}\\n`;\n  } catch {\n    line = `${JSON.stringify({ seq: record.seq, type: \"record-serialization-failed\" })}\\n`;\n  }\n  try {\n    // The preamble is not charged against the limit, so a large preamble cannot\n    // trigger another rotation on the very next write.\n    if (state.bytes - state.preambleBytes + line.length > maxFileBytes) {\n      rotate(state, file);\n      writePreamble(state);\n    }\n    fs.writeSync(state.fd, line);\n    state.bytes += line.length;\n  } catch {\n    // A recorder that cannot write stays silent rather than cascading into the\n    // application it is only supposed to observe.\n  }\n}\n\n// The tail is the only part that explains a crash, so the old file is parked\n// beside the new one instead of the new writes being dropped. Exactly one parked\n// segment is kept, which bounds a session's disk use at twice the file limit.\nfunction rotate(state: WriterState, file: string): void {\n  fs.closeSync(state.fd);\n  try {\n    fs.renameSync(file, `${file}.1`);\n  } catch {\n    // If the parked slot cannot be written, recording simply continues.\n  }\n  state.fd = fs.openSync(file, \"a\");\n  state.bytes = 0;\n  state.preambleBytes = 0;\n}\n\n/**\n * Rewrites into the new segment the three things a report cannot be produced\n * without, so repeated rotation costs only completed operations.\n *\n * Losing an *open* begin record would remove that operation from pairing\n * entirely, and the operation still running at the moment of death is the one\n * the report exists to name. Losing the earliest memory reading would leave the\n * heap series starting mid-session while the sampler's resident series still\n * starts at zero, which biases the classifier toward blaming native memory.\n */\nfunction writePreamble(state: WriterState): void {\n  if (state.header) {\n    emitPreambleRecord(state, {\n      seq: ++state.seq,\n      t: monotonic(),\n      wall: Date.now(),\n      type: SESSION_RECORD,\n      ...state.header,\n      continuation: true,\n    });\n  }\n  if (state.baselineMem) {\n    emitPreambleRecord(state, {\n      seq: ++state.seq,\n      t: monotonic(),\n      wall: Date.now(),\n      type: MEM_BASELINE_RECORD,\n      mem: state.baselineMem,\n      carriedForward: true,\n    });\n  }\n  // Original sequence numbers are kept, which is what lets an end record in a\n  // later segment pair with a begin first written in an overwritten one.\n  for (const begin of state.openBegins.values()) {\n    emitPreambleRecord(state, { ...begin, carriedForward: true });\n  }\n}\n\nfunction emitPreambleRecord(state: WriterState, record: FlightRecord): void {\n  try {\n    const line = `${JSON.stringify(record, bigintSafe)}\\n`;\n    fs.writeSync(state.fd, line);\n    state.bytes += line.length;\n    state.preambleBytes += line.length;\n  } catch {\n    // A preamble that cannot be written must not stop the session.\n  }\n}\n\n// Open operations are tracked by the same suffix convention the analyzer pairs\n// on, so the recorder needs no separate vocabulary for them.\nfunction trackOpenOperation(state: WriterState, record: FlightRecord): void {\n  if (record.type.endsWith(\"-begin\")) {\n    if (state.openBegins.size < MAX_CARRIED_BEGINS) state.openBegins.set(record.seq, record);\n    return;\n  }\n  if (record.type.endsWith(\"-end\") || record.type.endsWith(\"-error\")) {\n    if (typeof record.begin === \"number\") state.openBegins.delete(record.begin);\n  }\n}\n\nfunction hasSessionEnd(file: string): boolean {\n  const size = fs.statSync(file).size;\n  if (size === 0) return false;\n  const window = Math.min(size, 8192);\n  const buffer = Buffer.alloc(window);\n  const fd = fs.openSync(file, \"r\");\n  try {\n    fs.readSync(fd, buffer, 0, window, size - window);\n  } finally {\n    fs.closeSync(fd);\n  }\n  return buffer.toString(\"utf8\").includes(`\"type\":\"${SESSION_END_RECORD}\"`);\n}\n\nfunction describeEnvironment(): SessionEnvironment {\n  const maxOldSpaceFlag = process.execArgv.find((arg) => arg.startsWith(\"--max-old-space-size\"));\n  return {\n    node: process.version,\n    platform: `${process.platform}-${process.arch}`,\n    cpus: os.cpus().length,\n    totalMemory: os.totalmem(),\n    heapLimit: v8.getHeapStatistics().heap_size_limit,\n    execArgv: [...process.execArgv],\n    maxOldSpaceSize: maxOldSpaceFlag ? Number(maxOldSpaceFlag.split(\"=\")[1]) : undefined,\n  };\n}\n\nfunction bigintSafe(_key: string, value: unknown): unknown {\n  return typeof value === \"bigint\" ? Number(value) : value;\n}\n\nfunction monotonic(): number {\n  return Math.round(performance.now() * 1000) / 1000;\n}\n\nfunction randomTag(): string {\n  return Math.random().toString(36).slice(2, 8);\n}\n"],"mappings":"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"}

package/dist/redact.d.ts

@@ -0,0 +1,53 @@
+import { DataSummary } from "./data_summary.js";
+//#region src/redact.d.ts
+/**
+ * Structure-preserving redaction for anything a driver seam is handed.
+ *
+ * The definition a block model builds is recorded by *shape* rather than by a
+ * hand-written digest per definition type. Keys, numbers and the small set of
+ * strings that are schema survive verbatim; every other string is replaced by a
+ * hash and a length. That keeps the record useful for diagnosis, keeps customer
+ * data out of it by default rather than by enumeration, and works unchanged for
+ * definition shapes this code has never seen — the V2 query API included.
+ *
+ * The default for an unrecognised string is to hash it. A new field can
+ * therefore make a report less informative, but never make it leak.
+ */
+/** Keys whose string value is schema, kept as written. */
+export declare const SCHEMA_KEYS: Set<string>;
+/** Keys under which every string is schema, at any depth (axis identity). */
+export declare const SCHEMA_SUBTREE_KEYS: Set<string>;
+/** Keys never descended into; summarised by counts instead. */
+export declare const SUMMARISED_KEYS: Set<string>;
+/** Keys reduced to a cardinality, because their contents are values. */
+export declare const COUNTED_KEYS: Set<string>;
+export type RedactionStats = {
+  hashedStrings: number;
+  truncatedArrays: number;
+  omittedItems: number;
+  depthCapped: number;
+  opaqueObjects: number;
+  budgetExhausted: boolean;
+};
+export type RedactOptions = {
+  maxDepth?: number;
+  maxArrayItems?: number;
+  maxStringLength?: number;
+  /** Ceiling on emitted values, so one pathological definition cannot fill the log. */
+  maxNodes?: number;
+};
+export type HashedString = {
+  h: string;
+  n: number;
+};
+/** Redacts a definition, returning the new value and what had to be elided. */
+export declare function redact(value: unknown, options?: RedactOptions): {
+  value: unknown;
+  stats: RedactionStats;
+};
+/** Stable short hash plus the original length. Never reversible to the value. */
+export declare function hashString(value: string): HashedString;
+/** True for the object form produced in place of a redacted string. */
+export declare function isHashedString(value: unknown): value is HashedString;
+//#endregion
+//# sourceMappingURL=redact.d.ts.map

package/dist/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","names":[],"sources":["../src/redact.ts"],"mappings":";;;;;;;;;;;;;;;;qBAkBa,aAAW;;qBAGX,qBAAmB;;qBAGnB,iBAAe;;qBAGf,cAAY;YAEb;EACV;EACA;EACA;EACA;EACA;EACA;;YAGU;EACV;EACA;EACA;;EAEA;;YAGU;EAAiB;EAAW;;;wBAGxB,OACd,gBACA,UAAS;EACN;EAAgB,OAAO;;;wBAuBZ,WAAW,gBAAgB;;wBAQ3B,eAAe,iBAAiB,SAAS"}

package/dist/redact.js

@@ -0,0 +1,145 @@
+import { summarizeData } from "./data_summary.js";
+import crypto from "node:crypto";
+//#region src/redact.ts
+/**
+* Structure-preserving redaction for anything a driver seam is handed.
+*
+* The definition a block model builds is recorded by *shape* rather than by a
+* hand-written digest per definition type. Keys, numbers and the small set of
+* strings that are schema survive verbatim; every other string is replaced by a
+* hash and a length. That keeps the record useful for diagnosis, keeps customer
+* data out of it by default rather than by enumeration, and works unchanged for
+* definition shapes this code has never seen — the V2 query API included.
+*
+* The default for an unrecognised string is to hash it. A new field can
+* therefore make a report less informative, but never make it leak.
+*/
+/** Keys whose string value is schema, kept as written. */
+const SCHEMA_KEYS = /* @__PURE__ */ new Set([
+	"type",
+	"name",
+	"valueType",
+	"kind",
+	"operator",
+	"mode"
+]);
+/** Keys under which every string is schema, at any depth (axis identity). */
+const SCHEMA_SUBTREE_KEYS = /* @__PURE__ */ new Set(["domain", "contextDomain"]);
+/** Keys never descended into; summarised by counts instead. */
+const SUMMARISED_KEYS = /* @__PURE__ */ new Set(["data", "dataInfo"]);
+/** Keys reduced to a cardinality, because their contents are values. */
+const COUNTED_KEYS = /* @__PURE__ */ new Set(["references", "parts"]);
+/** Redacts a definition, returning the new value and what had to be elided. */
+function redact(value, options = {}) {
+	const limits = {
+		maxDepth: options.maxDepth ?? 32,
+		maxArrayItems: options.maxArrayItems ?? 64,
+		maxStringLength: options.maxStringLength ?? 128,
+		maxNodes: options.maxNodes ?? 2e4
+	};
+	const stats = {
+		hashedStrings: 0,
+		truncatedArrays: 0,
+		omittedItems: 0,
+		depthCapped: 0,
+		opaqueObjects: 0,
+		budgetExhausted: false
+	};
+	return {
+		value: walk(value, {
+			key: void 0,
+			schemaSubtree: false,
+			depth: 0
+		}, limits, stats, {
+			nodes: 0,
+			seen: /* @__PURE__ */ new WeakSet()
+		}),
+		stats
+	};
+}
+/** Stable short hash plus the original length. Never reversible to the value. */
+function hashString(value) {
+	return {
+		h: crypto.createHash("sha256").update(value).digest("hex").slice(0, 12),
+		n: value.length
+	};
+}
+/** True for the object form produced in place of a redacted string. */
+function isHashedString(value) {
+	return typeof value === "object" && value !== null && "h" in value && "n" in value;
+}
+function walk(value, at, limits, stats, state) {
+	if (state.nodes++ > limits.maxNodes) {
+		stats.budgetExhausted = true;
+		return { $budget: true };
+	}
+	if (value === null || value === void 0) return value ?? null;
+	if (typeof value === "bigint") return Number(value);
+	if (typeof value === "number" || typeof value === "boolean") return value;
+	if (typeof value === "string") return redactString(value, at, limits, stats);
+	if (typeof value !== "object") return { $type: typeof value };
+	if (at.depth >= limits.maxDepth) {
+		stats.depthCapped++;
+		return { $depth: at.depth };
+	}
+	if (state.seen.has(value)) return { $cycle: true };
+	if (Array.isArray(value)) {
+		state.seen.add(value);
+		return walkArray(value, at, limits, stats, state);
+	}
+	if (!isPlainObject(value)) {
+		stats.opaqueObjects++;
+		return { $opaque: className(value) };
+	}
+	state.seen.add(value);
+	const out = {};
+	for (const [key, child] of Object.entries(value)) {
+		if (SUMMARISED_KEYS.has(key)) {
+			out[key] = summarizeData(child);
+			continue;
+		}
+		if (COUNTED_KEYS.has(key)) {
+			out[key] = { $count: countOf(child) };
+			continue;
+		}
+		out[key] = walk(child, {
+			key,
+			schemaSubtree: at.schemaSubtree || SCHEMA_SUBTREE_KEYS.has(key),
+			depth: at.depth + 1
+		}, limits, stats, state);
+	}
+	return out;
+}
+function walkArray(value, at, limits, stats, state) {
+	const kept = value.slice(0, limits.maxArrayItems).map((item) => walk(item, {
+		key: at.key,
+		schemaSubtree: at.schemaSubtree,
+		depth: at.depth + 1
+	}, limits, stats, state));
+	const omitted = value.length - kept.length;
+	if (omitted <= 0) return kept;
+	stats.truncatedArrays++;
+	stats.omittedItems += omitted;
+	return [...kept, { $omitted: omitted }];
+}
+function redactString(value, at, limits, stats) {
+	if (at.schemaSubtree || at.key !== void 0 && SCHEMA_KEYS.has(at.key)) return value.length > limits.maxStringLength ? `${value.slice(0, limits.maxStringLength)}…` : value;
+	stats.hashedStrings++;
+	return hashString(value);
+}
+function countOf(value) {
+	if (Array.isArray(value)) return value.length;
+	if (isPlainObject(value)) return Object.keys(value).length;
+}
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+function className(value) {
+	return value.constructor?.name ?? "unknown";
+}
+//#endregion
+export { COUNTED_KEYS, SCHEMA_KEYS, SCHEMA_SUBTREE_KEYS, SUMMARISED_KEYS, hashString, isHashedString, redact };
+
+//# sourceMappingURL=redact.js.map

package/dist/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","names":[],"sources":["../src/redact.ts"],"sourcesContent":["import crypto from \"node:crypto\";\nimport { summarizeData, type DataSummary } from \"./data_summary\";\n\n/**\n * Structure-preserving redaction for anything a driver seam is handed.\n *\n * The definition a block model builds is recorded by *shape* rather than by a\n * hand-written digest per definition type. Keys, numbers and the small set of\n * strings that are schema survive verbatim; every other string is replaced by a\n * hash and a length. That keeps the record useful for diagnosis, keeps customer\n * data out of it by default rather than by enumeration, and works unchanged for\n * definition shapes this code has never seen — the V2 query API included.\n *\n * The default for an unrecognised string is to hash it. A new field can\n * therefore make a report less informative, but never make it leak.\n */\n\n/** Keys whose string value is schema, kept as written. */\nexport const SCHEMA_KEYS = new Set([\"type\", \"name\", \"valueType\", \"kind\", \"operator\", \"mode\"]);\n\n/** Keys under which every string is schema, at any depth (axis identity). */\nexport const SCHEMA_SUBTREE_KEYS = new Set([\"domain\", \"contextDomain\"]);\n\n/** Keys never descended into; summarised by counts instead. */\nexport const SUMMARISED_KEYS = new Set([\"data\", \"dataInfo\"]);\n\n/** Keys reduced to a cardinality, because their contents are values. */\nexport const COUNTED_KEYS = new Set([\"references\", \"parts\"]);\n\nexport type RedactionStats = {\n  hashedStrings: number;\n  truncatedArrays: number;\n  omittedItems: number;\n  depthCapped: number;\n  opaqueObjects: number;\n  budgetExhausted: boolean;\n};\n\nexport type RedactOptions = {\n  maxDepth?: number;\n  maxArrayItems?: number;\n  maxStringLength?: number;\n  /** Ceiling on emitted values, so one pathological definition cannot fill the log. */\n  maxNodes?: number;\n};\n\nexport type HashedString = { h: string; n: number };\n\n/** Redacts a definition, returning the new value and what had to be elided. */\nexport function redact(\n  value: unknown,\n  options: RedactOptions = {},\n): { value: unknown; stats: RedactionStats } {\n  const limits = {\n    maxDepth: options.maxDepth ?? 32,\n    maxArrayItems: options.maxArrayItems ?? 64,\n    maxStringLength: options.maxStringLength ?? 128,\n    maxNodes: options.maxNodes ?? 20_000,\n  };\n  const stats: RedactionStats = {\n    hashedStrings: 0,\n    truncatedArrays: 0,\n    omittedItems: 0,\n    depthCapped: 0,\n    opaqueObjects: 0,\n    budgetExhausted: false,\n  };\n  const state = { nodes: 0, seen: new WeakSet<object>() };\n  return {\n    value: walk(value, { key: undefined, schemaSubtree: false, depth: 0 }, limits, stats, state),\n    stats,\n  };\n}\n\n/** Stable short hash plus the original length. Never reversible to the value. */\nexport function hashString(value: string): HashedString {\n  return {\n    h: crypto.createHash(\"sha256\").update(value).digest(\"hex\").slice(0, 12),\n    n: value.length,\n  };\n}\n\n/** True for the object form produced in place of a redacted string. */\nexport function isHashedString(value: unknown): value is HashedString {\n  return typeof value === \"object\" && value !== null && \"h\" in value && \"n\" in value;\n}\n\n// Internals\n\ntype Position = { key: string | undefined; schemaSubtree: boolean; depth: number };\ntype Limits = Required<RedactOptions>;\ntype State = { nodes: number; seen: WeakSet<object> };\n\nfunction walk(\n  value: unknown,\n  at: Position,\n  limits: Limits,\n  stats: RedactionStats,\n  state: State,\n): unknown {\n  if (state.nodes++ > limits.maxNodes) {\n    stats.budgetExhausted = true;\n    return { $budget: true };\n  }\n\n  if (value === null || value === undefined) return value ?? null;\n  if (typeof value === \"bigint\") return Number(value);\n  if (typeof value === \"number\" || typeof value === \"boolean\") return value;\n  if (typeof value === \"string\") return redactString(value, at, limits, stats);\n  if (typeof value !== \"object\") return { $type: typeof value };\n\n  if (at.depth >= limits.maxDepth) {\n    stats.depthCapped++;\n    return { $depth: at.depth };\n  }\n  // A definition can carry live accessors and other class instances whose\n  // internals reference each other; walking those is neither safe nor useful.\n  if (state.seen.has(value)) return { $cycle: true };\n\n  if (Array.isArray(value)) {\n    state.seen.add(value);\n    return walkArray(value, at, limits, stats, state);\n  }\n  if (!isPlainObject(value)) {\n    stats.opaqueObjects++;\n    return { $opaque: className(value) };\n  }\n\n  state.seen.add(value);\n  const out: Record<string, unknown> = {};\n  for (const [key, child] of Object.entries(value)) {\n    if (SUMMARISED_KEYS.has(key)) {\n      out[key] = summarizeData(child);\n      continue;\n    }\n    if (COUNTED_KEYS.has(key)) {\n      out[key] = { $count: countOf(child) };\n      continue;\n    }\n    out[key] = walk(\n      child,\n      {\n        key,\n        schemaSubtree: at.schemaSubtree || SCHEMA_SUBTREE_KEYS.has(key),\n        depth: at.depth + 1,\n      },\n      limits,\n      stats,\n      state,\n    );\n  }\n  return out;\n}\n\nfunction walkArray(\n  value: unknown[],\n  at: Position,\n  limits: Limits,\n  stats: RedactionStats,\n  state: State,\n): unknown[] {\n  const kept = value\n    .slice(0, limits.maxArrayItems)\n    .map((item) =>\n      walk(\n        item,\n        { key: at.key, schemaSubtree: at.schemaSubtree, depth: at.depth + 1 },\n        limits,\n        stats,\n        state,\n      ),\n    );\n  const omitted = value.length - kept.length;\n  if (omitted <= 0) return kept;\n  // Arrays stay arrays so the rules can still walk join entries; the loss is\n  // recorded in the array itself rather than in a side channel.\n  stats.truncatedArrays++;\n  stats.omittedItems += omitted;\n  return [...kept, { $omitted: omitted }];\n}\n\nfunction redactString(\n  value: string,\n  at: Position,\n  limits: Limits,\n  stats: RedactionStats,\n): string | HashedString {\n  if (at.schemaSubtree || (at.key !== undefined && SCHEMA_KEYS.has(at.key))) {\n    return value.length > limits.maxStringLength\n      ? `${value.slice(0, limits.maxStringLength)}…`\n      : value;\n  }\n  stats.hashedStrings++;\n  return hashString(value);\n}\n\nfunction countOf(value: unknown): number | undefined {\n  if (Array.isArray(value)) return value.length;\n  if (isPlainObject(value)) return Object.keys(value).length;\n  return undefined;\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) return false;\n  const proto = Object.getPrototypeOf(value) as object | null;\n  return proto === Object.prototype || proto === null;\n}\n\nfunction className(value: object): string {\n  return (value as { constructor?: { name?: string } }).constructor?.name ?? \"unknown\";\n}\n\nexport type { DataSummary };\n"],"mappings":"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"}

package/dist/report.d.ts

@@ -0,0 +1,6 @@
+import { SessionAnalysis } from "./analyze.js";
+//#region src/report.d.ts
+/** Renders an analysis as the markdown report a developer reads. */
+export declare function renderReport(analysis: SessionAnalysis): string;
+//#endregion
+//# sourceMappingURL=report.d.ts.map

package/dist/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","names":[],"sources":["../src/report.ts"],"mappings":";;;wBAOgB,aAAa,UAAU"}