@ogygia/devtools 0.0.0 → 0.11.0

package/dist/profiler/ledger.js

@@ -0,0 +1,440 @@
+import { REGEXP_FRAME, calls_name, function_body, import_aliases, tokens } from "./source-scan.js";
+import { app_relative } from "./app-path.js";
+// src/profiler/ledger.ts
+/** the package of a `node_modules`-relative path: `@acme/ui/hydrate/x.mjs:1` → `@acme/ui` */
+function pkg_of(file) {
+	const parts = file.split("/");
+	if (!parts[0] || !file.includes("/")) return "";
+	return parts[0].startsWith("@") && parts[1] ? parts[0] + "/" + parts[1] : parts[0];
+}
+/** the framework the app runs on: SvelteKit, Svelte, ogygia itself, Vite */
+const is_framework_pkg = (p) => p.startsWith("@sveltejs/") || p === "svelte" || p.startsWith("ogygia") || p === "@ogygia/core" || p === "vite";
+/** After `renders` more renders a leaking line holds about `renders` × what one render left; one
+*  filling a bounded cache holds its capacity's worth. At 80 % of `renders`× or more it grew with
+*  EVERY render measured. The limit, said plainly: a cache holding at least `renders` entries is
+*  indistinguishable from a leak in that many renders. */
+const grows_of = (grown, one, renders) => {
+	if (renders < GROWS_MIN_RENDERS || !(one > 0)) return void 0;
+	const ratio = grown / (one * renders);
+	return ratio >= .85 ? renders >= LEAK_MIN_RENDERS ? true : void 0 : ratio <= .5 ? false : void 0;
+};
+const GROWS_MIN_RENDERS = 5;
+/** A LEAK verdict needs 6 renders. The check is cut short on a tight time budget, and over 5 a
+*  cache that keeps 4 entries holds 4 of the 5 renders' worth: a leak's shape, told apart only by
+*  sampling noise (the slow-patterns key's bounded-cache decoy read "grows" in 1 run of 3).
+*  "Levels off" still reads from 5: a leak never looks flat. */
+const LEAK_MIN_RENDERS = 6;
+/** The steadier verdict: the same sampler read after `h` renders (`half`) and after `n` (`full`).
+*  A leaking line holds `n/h` times as much at the end as halfway; one feeding a bounded cache
+*  that filled holds about the same. The sampled objects are the same objects in both reads, so
+*  one sample's noise cancels; the middle band is still no verdict. */
+const grows_between = (half, full, h, n) => {
+	if (n < GROWS_MIN_RENDERS || h < 1 || h >= n) return void 0;
+	if (!(half > 0)) return void 0;
+	const expected = n / h;
+	const ratio = full / half;
+	if (ratio >= 1 + .85 * (expected - 1)) return n >= LEAK_MIN_RENDERS ? true : void 0;
+	if (ratio <= 1 + .5 * (expected - 1)) return false;
+};
+/** "grows" from the halfway read, CHECKED against the one-render amount: a leak holds about one
+*  render's worth per render (all `renders` of them), a cache with a size limit holds its capacity.
+*  The two sampled reads can land far enough apart by chance to read as growth (a 4-entry cache,
+*  sampled low halfway and high at the end); a line holding well under the renders' worth is not
+*  leaking — no verdict then. Stays "grows" when the one-render amount is unknown.
+*  One render's worth is the LARGER of two estimates: the separate one-render pass, and the
+*  halfway read over its renders (the same sampler as the end read, so their noise is shared).
+*  A low draw on one of them no longer makes a filled cache look like a leak. */
+const confirmed = (between, grown, one, renders, half) => {
+	if (between !== true || !(one > 0) || renders <= 0) return between;
+	return grown / (Math.max(one, half && half.renders > 0 ? half.bytes / half.renders : 0) * renders) >= .75 ? true : void 0;
+};
+/** a callee a line can be charged for: library code, never Svelte's markup internals or V8's own */
+const LIB = /* @__PURE__ */ new Set(["dependency", "node"]);
+const APP = /* @__PURE__ */ new Set(["app", "component"]);
+/** words before a `(` that are not calls */
+const CONTROL = /* @__PURE__ */ new Set([
+	"if",
+	"for",
+	"while",
+	"switch",
+	"catch",
+	"return",
+	"typeof",
+	"await",
+	"function"
+]);
+const ID_START = (s) => {
+	const c = s.charCodeAt(0);
+	return c >= 65 && c <= 90 || c >= 97 && c <= 122 || c === 95 || c === 36;
+};
+/** the calls that run a regular expression */
+const REGEXP_METHODS = [
+	"test",
+	"exec",
+	"match",
+	"matchAll",
+	"replace",
+	"replaceAll",
+	"split",
+	"search"
+];
+/** A readable path: from `src/` when the path has one, the package-relative path inside
+*  `node_modules`, else the last three segments. */
+function short_source(path) {
+	const p = path.startsWith("file://") ? path.slice(7) : path;
+	const nm = p.lastIndexOf("/node_modules/");
+	if (nm !== -1) return p.slice(nm + 14);
+	const own = app_relative(p);
+	if (own !== void 0) return own;
+	const src = p.lastIndexOf("/src/");
+	if (src !== -1) return p.slice(src + 1);
+	const parts = p.split("/");
+	return parts.length > 3 ? parts.slice(-3).join("/") : p;
+}
+/** a source path the reader could open and edit: not a dependency, not Node's own, not the
+*  framework's generated build output (a compiled route chunk nobody edits), and not ogygia's own
+*  source reached through a workspace link (`packages/core/src/…`: no node_modules segment, but
+*  the library all the same, as analyze's categorize already says) */
+const is_app_path = (path) => !!path && !path.includes("/node_modules/") && !path.startsWith("node:") && (!path.includes("/.svelte-kit/") || path.includes("/.svelte-kit/output/")) && !path.includes("/ogygia/src/") && !path.includes("/ogygia/dist/") && !path.includes("/packages/core/src/") && !path.includes("/packages/core/dist/") && !path.includes("/devtools/src/profiler/") && !path.includes("/devtools/dist/profiler/");
+const r2 = (n) => Math.round(n * 100) / 100;
+function build_ledger(input) {
+	const by = /* @__PURE__ */ new Map();
+	const acc = (path, file, line) => {
+		const k = path + "\0" + line;
+		let a = by.get(k);
+		if (!a) by.set(k, a = {
+			path,
+			file,
+			line,
+			cpu_ms: 0,
+			alloc_bytes: 0,
+			gc_ms: 0,
+			retained_bytes: 0,
+			who: /* @__PURE__ */ new Map(),
+			fn_ms: 0,
+			lib_ms: 0,
+			libs: [],
+			grown_bytes: 0,
+			half_bytes: 0,
+			merged_ms: 0
+		});
+		return a;
+	};
+	const credit = (a, name, weight) => a.who.set(name, (a.who.get(name) ?? 0) + weight);
+	for (const f of input.functions) {
+		if (!APP.has(f.category) || !f.lines?.length || !is_app_path(f.path)) continue;
+		for (const l of f.lines) {
+			if (l.line <= 0 || l.ms <= 0) continue;
+			const a = acc(f.path, f.url || short_source(f.path), l.line);
+			a.cpu_ms += l.ms;
+			credit(a, f.name, l.ms);
+			if (l.ms > a.fn_ms) {
+				a.fn = f.key;
+				a.fn_ms = l.ms;
+			}
+		}
+	}
+	if (input.source && input.uninlined?.length) {
+		const src = input.source;
+		const un_by_name = /* @__PURE__ */ new Map();
+		/** the un-inlined render's self time per line of each app function */
+		const un_lines = /* @__PURE__ */ new Map();
+		for (const f of input.uninlined) {
+			if (!APP.has(f.category) || f.total_ms <= 0 || !is_app_path(f.path) || f.name.startsWith("(")) continue;
+			const list = un_by_name.get(f.name) ?? [];
+			list.push({
+				path: f.path,
+				ms: f.total_ms
+			});
+			un_by_name.set(f.name, list);
+			if (f.lines?.length) {
+				const m = un_lines.get(f.name + "\0" + f.path) ?? /* @__PURE__ */ new Map();
+				for (const l of f.lines) m.set(l.line, (m.get(l.line) ?? 0) + l.ms);
+				un_lines.set(f.name + "\0" + f.path, m);
+			}
+		}
+		const renders = Math.max(1, input.renders ?? 1);
+		const main_ms = /* @__PURE__ */ new Map();
+		for (const f of input.functions) if (APP.has(f.category)) main_ms.set(f.name + "\0" + f.path, (main_ms.get(f.name + "\0" + f.path) ?? 0) + f.total_ms);
+		const kept_frame = (name, path, un_ms) => (main_ms.get(name + "\0" + path) ?? 0) / renders >= un_ms * .25;
+		/** an app function called on this line that ran with no frame of its own: its un-inlined time */
+		const inlined_calls = (line, caller) => {
+			const out = [];
+			const t = tokens(line);
+			for (let k = 0; k + 1 < t.length; k++) {
+				if (t[k + 1] !== "(" || t[k - 1] === "function" || t[k] === caller) continue;
+				const hits = un_by_name.get(t[k]);
+				if (hits?.length !== 1 || kept_frame(t[k], hits[0].path, hits[0].ms) || out.some((o) => o.name === t[k])) continue;
+				out.push({
+					name: t[k],
+					ms: hits[0].ms
+				});
+			}
+			return out;
+		};
+		const touched = /* @__PURE__ */ new Set();
+		for (const a of Array.from(by.values())) {
+			if (a.cpu_ms <= 0 || touched.has(a)) continue;
+			const caller = a.fn?.split(" ")[0];
+			const here = src(a.path, a.line, a.line)?.lines[0];
+			const own = here ? inlined_calls(here, caller) : [];
+			const caller_lines = caller ? un_lines.get(caller + "\0" + a.path) : void 0;
+			if (!caller_lines && !own.length) continue;
+			const own_ms = (caller_lines?.get(a.line) ?? 0) + own.reduce((s, c) => s + c.ms, 0);
+			const win = src(a.path, Math.max(1, a.line - 2), a.line + 1);
+			if (!win) continue;
+			const beside = [];
+			for (let i = 0; i < win.lines.length; i++) {
+				const at = win.start + i;
+				if (at === a.line) continue;
+				const calls = inlined_calls(win.lines[i], caller);
+				if (calls.length) beside.push({
+					line: at,
+					calls
+				});
+			}
+			if (!beside.length) continue;
+			const total = own_ms + beside.reduce((s, b) => s + b.calls.reduce((x, c) => x + c.ms, 0), 0);
+			if (total <= 0) continue;
+			const pool = a.cpu_ms;
+			for (const b of beside) {
+				const ms = pool * b.calls.reduce((x, c) => x + c.ms, 0) / total;
+				if (ms <= 0) continue;
+				const to = acc(a.path, a.file, b.line);
+				to.cpu_ms += ms;
+				a.cpu_ms -= ms;
+				for (const c of b.calls) credit(to, c.name, ms / b.calls.length);
+				to.fn ??= a.fn;
+				if (!to.merged || ms > to.merged_ms) {
+					to.merged = {
+						from: a.line,
+						callee: b.calls[0].name
+					};
+					to.merged_ms = ms;
+				}
+				touched.add(to);
+			}
+			touched.add(a);
+		}
+	}
+	if (input.source) {
+		const pkg_by_key = /* @__PURE__ */ new Map();
+		for (const f of input.functions) if (f.pkg) pkg_by_key.set(f.key, f.pkg);
+		const pkg_for = (c) => c.pkg ?? pkg_by_key.get(c.key) ?? (c.category === "node" ? "Node" : pkg_of(c.file));
+		const aliases = /* @__PURE__ */ new Map();
+		const aliases_of = (path) => {
+			let al = aliases.get(path);
+			if (!al) aliases.set(path, al = import_aliases(input.source, path));
+			return al;
+		};
+		const un = input.uninlined ?? [];
+		const un_by_fn = /* @__PURE__ */ new Map();
+		const un_by_key = /* @__PURE__ */ new Map();
+		for (const u of un) {
+			if (!APP.has(u.category)) continue;
+			if (u.key) un_by_key.set(u.key, u);
+			un_by_fn.set(u.name + "\0" + u.path, u);
+		}
+		/** where `f` really entered package `pkg`, from the inlining-off render: the app lines (in
+		*  `f`, or in the app functions it calls, three deep) that call into that package — each
+		*  given a share of `ms` by what it called there. Empty when that render cannot say */
+		const entered_by = (f, pkg, ms) => {
+			const found = [];
+			const start = un_by_fn.get(f.name + "\0" + f.path);
+			if (!start) return only_call(f, ms);
+			const seen = /* @__PURE__ */ new Set([start]);
+			let level = [start];
+			for (let depth = 0; depth < 4 && level.length && !found.length; depth++) {
+				const next = [];
+				for (const g of level) {
+					if (!g.callees?.length || !g.line || !is_app_path(g.path)) continue;
+					const body = function_body(input.source, g.path, g.line);
+					if (!body) continue;
+					for (const d of g.callees) {
+						if (APP.has(d.category)) {
+							const u = un_by_key.get(d.key);
+							if (u && !seen.has(u)) {
+								seen.add(u);
+								next.push(u);
+							}
+							continue;
+						}
+						if (!LIB.has(d.category) || d.name.startsWith("(") || pkg_for(d) !== pkg) continue;
+						const names = [d.name, ...aliases_of(g.path).get(d.name) ?? []];
+						const lines = [];
+						for (let i = 0; i < body.lines.length; i++) if (calls_name(body.lines[i], names)) lines.push(body.start + i);
+						for (const line of lines) found.push({
+							path: g.path,
+							file: g.url || short_source(g.path),
+							line,
+							w: d.ms / lines.length,
+							fn: g.key ?? f.key
+						});
+					}
+				}
+				level = next;
+			}
+			const total = found.reduce((s, x) => s + x.w, 0);
+			return total > 0 ? found.map((x) => ({
+				path: x.path,
+				file: x.file,
+				line: x.line,
+				ms: ms * x.w / total,
+				fn: x.fn
+			})) : only_call(f, ms);
+		};
+		/** the one line of `f`'s body that calls anything, when there is exactly one (a loop that
+		*  awaits a timer per turn, a wrapper around one library call): the library time came from
+		*  there, whatever V8 inlined. The inlining-off render is one render; a short function can
+		*  have no sample in it */
+		const only_call = (f, ms) => {
+			const body = function_body(input.source, f.path, f.line);
+			if (!body) return [];
+			let at = -1;
+			for (let i = 0; i < body.lines.length; i++) {
+				const t = tokens(body.lines[i]);
+				let calls = false;
+				for (let k = 0; k + 1 < t.length && !calls; k++) calls = t[k + 1] === "(" && t[k - 1] !== "function" && !CONTROL.has(t[k]) && ID_START(t[k]);
+				if (!calls) continue;
+				if (i === 0 && t.includes("function")) continue;
+				if (at !== -1) return [];
+				at = body.start + i;
+			}
+			return at === -1 ? [] : [{
+				path: f.path,
+				file: f.url || short_source(f.path),
+				line: at,
+				ms,
+				fn: f.key
+			}];
+		};
+		for (const f of input.functions) {
+			if (!APP.has(f.category) || !f.callees?.length || f.line <= 0 || !is_app_path(f.path)) continue;
+			const libs = f.callees.filter((c) => LIB.has(c.category) && !c.name.startsWith("(") && !is_framework_pkg(pkg_for(c)));
+			if (!libs.length) continue;
+			const body = function_body(input.source, f.path, f.line);
+			if (!body) continue;
+			let al = aliases.get(f.path);
+			if (!al) aliases.set(f.path, al = import_aliases(input.source, f.path));
+			for (const c of libs) {
+				const names = [c.name, ...al.get(c.name) ?? []];
+				const at = [];
+				const re = c.name.startsWith("RegExp: ") ? c.name.slice(REGEXP_FRAME.length) : null;
+				if (re !== null) {
+					for (let i = 0; i < body.lines.length; i++) if (body.lines[i].includes(`/${re}/`)) at.push(body.start + i);
+					if (!at.length) {
+						for (let i = 0; i < body.lines.length; i++) if (calls_name(body.lines[i], REGEXP_METHODS)) at.push(body.start + i);
+					}
+				}
+				for (let i = 0; re === null && i < body.lines.length; i++) if (calls_name(body.lines[i], names)) at.push(body.start + i);
+				const targets = at.map((line) => ({
+					path: f.path,
+					file: f.url || short_source(f.path),
+					line,
+					ms: c.ms / at.length,
+					fn: f.key
+				}));
+				if (!targets.length) targets.push(...entered_by(f, pkg_for(c), c.ms));
+				for (const t of targets) {
+					const a = acc(t.path, t.file, t.line);
+					a.lib_ms += t.ms;
+					a.libs.push({
+						name: c.name,
+						pkg: pkg_for(c),
+						ms: r2(t.ms),
+						...targets.length > 1 ? { shared: targets.length } : {}
+					});
+					credit(a, c.name, t.ms);
+					if (!a.fn) a.fn = t.fn;
+				}
+			}
+		}
+	}
+	const hottest = /* @__PURE__ */ new Map();
+	for (const f of input.functions) {
+		if (!APP.has(f.category) || !f.lines?.length || f.line <= 0 || !is_app_path(f.path)) continue;
+		let best = f.lines[0];
+		for (const l of f.lines) if (l.ms > best.ms) best = l;
+		if (best.line > 0 && best.ms > 0) hottest.set(f.path + "\0" + f.line, {
+			file: f.url || short_source(f.path),
+			line: best.line
+		});
+	}
+	const mem_row = (at) => {
+		const h = hottest.get(at.path + "\0" + at.line);
+		if (!h) return acc(at.path, short_source(at.path), at.line);
+		const a = acc(at.path, h.file, h.line);
+		a.mem_in_fn = true;
+		return a;
+	};
+	const entry_of_pkg = /* @__PURE__ */ new Map();
+	for (const a of by.values()) for (const lc of a.libs) {
+		const e = lc.pkg ? entry_of_pkg.get(lc.pkg) : void 0;
+		if (lc.pkg && (!e || lc.ms > e.ms)) entry_of_pkg.set(lc.pkg, {
+			a,
+			ms: lc.ms
+		});
+	}
+	const pkg_row = (url) => {
+		const i = url ? url.lastIndexOf("/node_modules/") : -1;
+		if (!url || i === -1) return void 0;
+		const pkg = pkg_of(url.slice(i + 14));
+		const e = entry_of_pkg.get(pkg);
+		if (e) e.a.mem_via = pkg;
+		return e?.a;
+	};
+	const row_for = (at, url) => at && at.line > 0 && is_app_path(at.path) ? mem_row(at) : !at ? pkg_row(url) : void 0;
+	for (const m of input.makers ?? []) {
+		const a = row_for(m.at, m.url);
+		if (!a) continue;
+		a.alloc_bytes += m.allocated;
+		a.gc_ms += m.gc_ms;
+		credit(a, m.name, m.allocated / 1e6);
+	}
+	for (const s of input.retained ?? []) {
+		const a = row_for(s.at, s.url);
+		if (!a) continue;
+		a.retained_bytes += s.bytes;
+		credit(a, s.name, s.bytes / 1e6);
+	}
+	for (const s of input.grown?.sites ?? []) {
+		const a = row_for(s.at, s.url);
+		if (a) a.grown_bytes += s.bytes;
+	}
+	for (const s of input.grown?.half?.sites ?? []) {
+		const a = row_for(s.at, s.url);
+		if (a) a.half_bytes += s.bytes;
+	}
+	const rows = [...by.values()];
+	const tot_cpu = rows.reduce((s, r) => s + r.cpu_ms + r.lib_ms, 0) || 1;
+	const tot_alloc = rows.reduce((s, r) => s + r.alloc_bytes, 0) || 1;
+	const tot_ret = rows.reduce((s, r) => s + r.retained_bytes, 0) || 1;
+	const raw = (r) => (r.cpu_ms + r.lib_ms) / tot_cpu + r.alloc_bytes / tot_alloc + r.retained_bytes / tot_ret;
+	rows.sort((a, b) => raw(b) - raw(a));
+	return rows.slice(0, input.limit ?? 40).map((r) => {
+		const code = input.code?.(r.path, r.line)?.trim();
+		return {
+			path: r.path,
+			file: r.file,
+			line: r.line,
+			...code ? { code: code.length > 140 ? code.slice(0, 139) + "…" : code } : {},
+			cpu_ms: r2(r.cpu_ms),
+			alloc_bytes: Math.round(r.alloc_bytes),
+			gc_ms: r2(r.gc_ms),
+			retained_bytes: Math.round(r.retained_bytes),
+			who: [...r.who].sort((a, b) => b[1] - a[1]).slice(0, 4).map(([n]) => n),
+			...r.fn ? { fn: r.fn } : {},
+			...r.mem_in_fn && (r.alloc_bytes > 0 || r.retained_bytes > 0) ? { mem_in_fn: true } : {},
+			...r.mem_via && (r.alloc_bytes > 0 || r.retained_bytes > 0) ? { mem_via: r.mem_via } : {},
+			...input.grown && r.retained_bytes > 0 ? { grows: input.grown.half && r.half_bytes > 0 ? confirmed(grows_between(r.half_bytes, r.grown_bytes, input.grown.half.renders, input.grown.renders), r.grown_bytes, r.retained_bytes, input.grown.renders, {
+				bytes: r.half_bytes,
+				renders: input.grown.half.renders
+			}) : grows_of(r.grown_bytes, r.retained_bytes, input.grown.renders) } : {},
+			lib_ms: r2(r.lib_ms),
+			...r.libs.length ? { libs: r.libs.sort((a, b) => b.ms - a.ms).slice(0, 4) } : {},
+			...r.merged ? { merged: r.merged } : {},
+			score: r2(raw(r))
+		};
+	});
+}
+export { build_ledger, confirmed, grows_between, grows_of, is_app_path, is_framework_pkg, pkg_of, short_source };

package/dist/profiler/lineage.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The `page.data` keys a component source reads, or `null` when it takes the whole object in a
+ * way that cannot be named (`...data`, `data` passed on, `Object.keys(data)`). `names` are the
+ * identifiers that hold the data (`data` by default; `page.data` / `$page.data` always count).
+ */
+export declare function data_reads(source: string, names?: readonly string[]): string[] | null;
+/** The 1-based line of the first place the source takes the data WHOLE (`const d = $page.data`,
+ *  `fn(data)`, `...data`), or null when it only reads named keys. Same scan as `data_reads`. */
+export declare function whole_read_line(source: string, names?: readonly string[]): number | null;
+/** The source with its comments (`//`, block, HTML) and string contents blanked to spaces, so
+ *  a word in prose or a URL never reads as code; positions are kept. A character walk. */
+export declare function blank_comments(src: string): string;
+/** the `let { data } = $props()` / `export let data` names a component gives its data prop —
+ *  plus any rename (`let { data: page_data } = $props()`) */
+export declare function data_prop_names(src: string): string[];
+/** `island`: an island names it (must ship) · `server`: read on the server, not shipped (fine) ·
+ *  `server-only`: read on the server only, yet shipped · `unread`: nobody reads it · `unknown`:
+ *  a reader could not be scanned, or an island takes the page whole */
+export type KeyVerdict = "island" | "server" | "server-only" | "unread" | "unknown";
+export interface LineageKey {
+  key: string;
+  /** the load file that returns it, when its source said */
+  from: string | null;
+  /** bytes the seed shipped for it (0: not shipped) */
+  shipped_bytes: number;
+  /** who reads it */
+  readers: {
+    name: string;
+    island: boolean;
+  }[];
+  verdict: KeyVerdict;
+  /** the waiting the load that produced it did (its upstream calls), when known */
+  load_wait_ms: number | null;
+}
+export interface LineageComponent {
+  name: string;
+  file: string;
+  island: boolean;
+  /** the keys it reads; null when it could not be told */
+  reads: string[] | null;
+  /** it reads the whole object (a spread, a pass-through): every key may be read */
+  whole: boolean;
+  /** where (1-based line in `file`) it first takes the object whole, when the source said */
+  whole_line?: number;
+}
+export interface Lineage {
+  keys: LineageKey[];
+  components: LineageComponent[];
+  /** keys nobody reads, by the wait behind them */
+  unread: LineageKey[];
+  /** keys shipped in the seed but read only on the server */
+  server_only: LineageKey[];
+  notes: string[];
+  /** every load's returned keys with the lines (1-based, in `from`) whose values end up in each
+   *  (source-scan `key_sources`): what a wait made on one of those lines was for */
+  sources?: {
+    key: string;
+    from: string;
+    lines: number[];
+    names?: string[];
+  }[];
+}
+export interface LineageInput {
+  /** every component of the page with its reads (server components scanned; islands from the build) */
+  components: {
+    name: string;
+    file: string;
+    island: boolean;
+    reads: string[] | null;
+    whole_line?: number;
+  }[];
+  /** the loads and the keys they return, plus the waiting each did */
+  lanes: {
+    file: string;
+    keys: string[] | null;
+    wait_ms?: number;
+  }[];
+  /** bytes per key in the seed */
+  seed: Record<string, number>;
+}
+export declare function build_lineage(input: LineageInput): Lineage | undefined;