@flyingrobots/graft 0.4.0 → 0.5.0

package/src/git/diff.ts

@@ -1,7 +1,8 @@
-import { execFileSync } from "node:child_process";
+import type { GitClient } from "../ports/git.js";
 
 export interface ChangedFilesOptions {
   cwd: string;
+  git: GitClient;
   base?: string | undefined;
   head?: string | undefined;
 }
@@ -13,26 +14,26 @@ export class GitError extends Error {
   }
 }
 
-function git(args: string[], cwd: string): string {
-  return execFileSync("git", args, {
-    cwd,
-    encoding: "utf-8",
-    stdio: ["pipe", "pipe", "pipe"],
-  });
+async function git(gitClient: GitClient, args: readonly string[], cwd: string): Promise<string> {
+  const result = await gitClient.run({ args, cwd });
+  if (result.error !== undefined || result.status !== 0) {
+    throw result.error ?? new Error(result.stderr.trim() || `git exited with status ${String(result.status)}`);
+  }
+  return result.stdout;
 }
 
-function refExists(ref: string, cwd: string): boolean {
+async function refExists(ref: string, cwd: string, gitClient: GitClient): Promise<boolean> {
   try {
-    git(["rev-parse", "--verify", ref], cwd);
+    await git(gitClient, ["rev-parse", "--verify", ref], cwd);
     return true;
   } catch {
     return false;
   }
 }
 
-function objectExists(ref: string, filePath: string, cwd: string): boolean {
+async function objectExists(ref: string, filePath: string, cwd: string, gitClient: GitClient): Promise<boolean> {
   try {
-    git(["cat-file", "-e", `${ref}:${filePath}`], cwd);
+    await git(gitClient, ["cat-file", "-e", `${ref}:${filePath}`], cwd);
     return true;
   } catch {
     return false;
@@ -47,14 +48,14 @@ function objectExists(ref: string, filePath: string, cwd: string): boolean {
  * Throws GitError for invalid refs or non-git directories.
  * Returns empty array only when there are genuinely no changes.
  */
-export function getChangedFiles(opts: ChangedFilesOptions): string[] {
+export async function getChangedFiles(opts: ChangedFilesOptions): Promise<string[]> {
   const base = opts.base ?? "HEAD";
   const args = opts.head !== undefined
-    ? ["diff", "--name-only", base, opts.head]
-    : ["diff", "--name-only", base];
+    ? ["diff-tree", "--no-commit-id", "--name-only", "-r", base, opts.head]
+    : ["diff-index", "--name-only", base, "--"];
 
   try {
-    const output = git(args, opts.cwd).trim();
+    const output = (await git(opts.git, args, opts.cwd)).trim();
     if (output === "") return [];
     return output.split("\n");
   } catch (err: unknown) {
@@ -71,24 +72,27 @@ export function getChangedFiles(opts: ChangedFilesOptions): string[] {
  * Uses `git rev-parse --verify` and `git cat-file -e` for stable
  * detection — no error message parsing.
  */
-export function getFileAtRef(
+export async function getFileAtRef(
   ref: string,
   filePath: string,
-  cwd: string,
-): string | null {
+  opts: {
+    cwd: string;
+    git: GitClient;
+  },
+): Promise<string | null> {
   // Validate the ref exists (stable probe, no message parsing)
-  if (!refExists(ref, cwd)) {
+  if (!(await refExists(ref, opts.cwd, opts.git))) {
     throw new GitError(`ref does not exist: ${ref}`);
   }
 
   // Check if the object exists at this ref (stable probe)
-  if (!objectExists(ref, filePath, cwd)) {
+  if (!(await objectExists(ref, filePath, opts.cwd, opts.git))) {
     return null; // Clean absence — file not in this ref
   }
 
   // Object exists — read it
   try {
-    return git(["show", `${ref}:${filePath}`], cwd);
+    return await git(opts.git, ["show", `${ref}:${filePath}`], opts.cwd);
   } catch (err: unknown) {
     const msg = err instanceof Error ? err.message : String(err);
     throw new GitError(`git show ${ref}:${filePath} failed: ${msg}`);

package/src/git/target-git-hook-bootstrap.ts

@@ -0,0 +1,56 @@
+import * as path from "node:path";
+
+export const TARGET_GIT_TRANSITION_HOOKS = [
+  "post-checkout",
+  "post-merge",
+  "post-rewrite",
+] as const;
+
+export const TARGET_GIT_HOOK_MARKER = "graft-target-repo-git-hook";
+
+export function resolveGitHooksPath(
+  worktreeRoot: string,
+  gitCommonDir: string,
+  configuredCoreHooksPath: string | null,
+): string {
+  if (configuredCoreHooksPath === null) {
+    return path.join(gitCommonDir, "hooks");
+  }
+  return path.isAbsolute(configuredCoreHooksPath)
+    ? configuredCoreHooksPath
+    : path.resolve(worktreeRoot, configuredCoreHooksPath);
+}
+
+export function isRecognizedTargetGitHook(
+  content: string,
+  hookName: (typeof TARGET_GIT_TRANSITION_HOOKS)[number],
+): boolean {
+  return content.includes(`# ${TARGET_GIT_HOOK_MARKER}:${hookName}`);
+}
+
+export function isTargetGitTransitionHookName(
+  value: string,
+): value is (typeof TARGET_GIT_TRANSITION_HOOKS)[number] {
+  return TARGET_GIT_TRANSITION_HOOKS.includes(value as (typeof TARGET_GIT_TRANSITION_HOOKS)[number]);
+}
+
+export function buildTargetGitHookScript(
+  hookName: (typeof TARGET_GIT_TRANSITION_HOOKS)[number],
+): string {
+  return [
+    "#!/bin/sh",
+    `# ${TARGET_GIT_HOOK_MARKER}:${hookName}`,
+    "set -eu",
+    "GRAFT_WORKTREE_ROOT=\"$(git rev-parse --show-toplevel 2>/dev/null || pwd)\"",
+    "node -e '",
+    "const fs = require(\"node:fs\");",
+    "const path = require(\"node:path\");",
+    "const [hookName, worktreeRoot, ...hookArgs] = process.argv.slice(1);",
+    "const runtimeDir = path.join(worktreeRoot, \".graft\", \"runtime\");",
+    "fs.mkdirSync(runtimeDir, { recursive: true });",
+    "const event = { hookName, hookArgs, worktreeRoot, observedAt: new Date().toISOString() };",
+    "fs.appendFileSync(path.join(runtimeDir, \"git-transitions.ndjson\"), JSON.stringify(event) + \"\\n\");",
+    `' "${hookName}" "$GRAFT_WORKTREE_ROOT" "$@"`,
+    "",
+  ].join("\n");
+}

package/src/hooks/posttooluse-read.ts

@@ -2,102 +2,49 @@
 // PostToolUse hook for Read — educates the agent on context cost
 // ---------------------------------------------------------------------------
 //
-// After a Read completes, evaluates what safe_read would have done and
-// tells the agent the cost difference. Does not block — just feedback.
+// After a Read completes, evaluates whether a large JS/TS file bypassed
+// graft's governed path and tells the agent the cost difference.
+// Does not block — just feedback.
 //
 // The agent sees messages like:
-//   "[graft] You just read 450 lines (18KB). safe_read would have
-//    returned a 2KB outline, saving 16KB of context."
+//   "[graft] This large code read bypassed graft's governed path ...
+//    safe_read would have returned a 2KB outline, saving 16KB."
 //
 // This teaches the agent to prefer graft's MCP tools voluntarily.
 //
 // Invoked as: node --import tsx src/hooks/posttooluse-read.ts
 // Receives JSON on stdin from Claude Code hooks system.
 // ---------------------------------------------------------------------------
-
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { evaluatePolicy, STATIC_THRESHOLDS } from "../policy/evaluate.js";
-import { ContentResult, RefusedResult } from "../policy/types.js";
-import { loadGraftignore } from "../policy/graftignore.js";
-import { HookInput, HookOutput, safeRelativePath, runHook } from "./shared.js";
+import { HookInput, HookOutput, runHook } from "./shared.js";
+import { renderOversizedReadEducation } from "./read-messages.js";
+import {
+  inspectHookRead,
+} from "./read-governor.js";
 
 export { HookInput, HookOutput };
 
 export async function handlePostReadHook(input: HookInput): Promise<HookOutput> {
-  const filePath = input.tool_input.file_path;
-
-  // Path outside project — no feedback
-  const relPath = safeRelativePath(input.cwd, filePath);
-  if (relPath === null) {
-    return new HookOutput(0, "");
-  }
-
-  // Read file to get dimensions
-  let rawContent: string;
-  try {
-    rawContent = fs.readFileSync(filePath, "utf-8");
-  } catch {
+  const inspection = inspectHookRead(input);
+  if (!inspection?.isGovernedCodeRead()) {
     return new HookOutput(0, "");
   }
 
-  const lines = rawContent.split("\n");
-  const bytes = Buffer.byteLength(rawContent, "utf-8");
-
-  // Load .graftignore patterns
-  let graftignorePatterns: string[] | undefined;
-  try {
-    const ignoreFile = fs.readFileSync(
-      path.join(input.cwd, ".graftignore"),
-      "utf-8",
-    );
-    graftignorePatterns = loadGraftignore(ignoreFile);
-  } catch {
-    // No .graftignore
-  }
-
-  // Evaluate what safe_read would have done
-  const policy = evaluatePolicy(
-    { path: relPath, lines: lines.length, bytes },
-    { graftignorePatterns },
+  const { extractOutlineForFile } = await import("../parser/outline.js");
+  const outline = extractOutlineForFile(
+    inspection.absolutePath,
+    inspection.rawContent,
   );
-
-  // Small file — no feedback needed, Read was the right call
-  if (policy instanceof ContentResult) {
-    return new HookOutput(0, "");
-  }
-
-  // Refused — PreToolUse should have caught this, but just in case
-  if (policy instanceof RefusedResult) {
-    return new HookOutput(0, "");
-  }
-
-  // Outline projection — the agent just dumped a large file into context
-  // when safe_read would have returned a compact outline
-  const { detectLang } = await import("../parser/lang.js");
-  const lang = detectLang(filePath);
-  if (lang === null) {
-    // Non-JS/TS — no outline available, Read was reasonable
+  if (outline === null) {
     return new HookOutput(0, "");
   }
 
   const { CanonicalJsonCodec } = await import("../adapters/canonical-json.js");
-  const { extractOutline } = await import("../parser/outline.js");
   const codec = new CanonicalJsonCodec();
-  const outline = extractOutline(rawContent, lang);
   const outlineBytes = Buffer.byteLength(codec.encode(outline), "utf-8");
-  const saved = bytes - outlineBytes;
-  const savedKb = (saved / 1024).toFixed(1);
-  const bytesKb = (bytes / 1024).toFixed(1);
-
-  return new HookOutput(0, [
-    `[graft] You just read ${String(lines.length)} lines (${bytesKb}KB) into context.`,
-    `safe_read would have returned a structural outline (${String(outlineBytes)} bytes),`,
-    `saving ${savedKb}KB of context. Threshold: ${String(STATIC_THRESHOLDS.lines)} lines / ${String(STATIC_THRESHOLDS.bytes / 1024)}KB.`,
-    "",
-    "Consider using graft's safe_read tool for large files —",
-    "it returns outlines with jump tables for targeted read_range.",
-  ].join("\n"));
+  return new HookOutput(
+    0,
+    renderOversizedReadEducation(inspection, outlineBytes),
+  );
 }
 
 // ---------------------------------------------------------------------------

package/src/hooks/pretooluse-read.ts

@@ -1,83 +1,47 @@
 // ---------------------------------------------------------------------------
-// PreToolUse hook for Read — blocks banned files only
+// PreToolUse hook for Read — blocks banned files and redirects large code reads
 // ---------------------------------------------------------------------------
 //
 // Intercepts Claude Code's Read tool and evaluates graft policy:
 //   - Refused (banned file): exit 2 — hard block with refusal reason
+//   - Oversized JS/TS file: exit 2 — redirect to graft's bounded-read path
 //   - Everything else: exit 0 — let native Read proceed
 //
 // Banned files (.env, binaries, lockfiles, minified, build output,
-// .graftignore matches) are the only hard enforcement. Large file
-// governance is handled by the PostToolUse hook via education.
+// .graftignore matches) stay hard blocks. Large JS/TS files now route
+// through graft's governed path before native Read can dump them into
+// context. PostToolUse remains a backstop if an oversized code read
+// still slips through.
 //
 // Invoked as: node --import tsx src/hooks/pretooluse-read.ts
 // Receives JSON on stdin from Claude Code hooks system.
 // ---------------------------------------------------------------------------
-
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { evaluatePolicy } from "../policy/evaluate.js";
 import { RefusedResult } from "../policy/types.js";
-import { loadGraftignore } from "../policy/graftignore.js";
-import { HookInput, HookOutput, safeRelativePath, runHook } from "./shared.js";
+import {
+  renderGovernedReadRedirect,
+  renderRefusedReadMessage,
+} from "./read-messages.js";
+import {
+  inspectHookRead,
+} from "./read-governor.js";
+import { HookInput, HookOutput, runHook } from "./shared.js";
 
 export { HookInput, HookOutput };
 
 export function handleReadHook(input: HookInput): HookOutput {
-  const filePath = input.tool_input.file_path;
-
-  // Path outside project — let Read handle it, not our concern
-  const relPath = safeRelativePath(input.cwd, filePath);
-  if (relPath === null) {
+  const inspection = inspectHookRead(input);
+  if (inspection === null) {
     return new HookOutput(0, "");
   }
 
-  // Read file to get dimensions for policy
-  let rawContent: string;
-  try {
-    rawContent = fs.readFileSync(filePath, "utf-8");
-  } catch {
-    // File errors (ENOENT, EACCES, EISDIR) — let Read handle natively
-    return new HookOutput(0, "");
+  if (inspection.policy instanceof RefusedResult) {
+    return new HookOutput(2, renderRefusedReadMessage(inspection.policy));
   }
 
-  const lines = rawContent.split("\n");
-  const bytes = Buffer.byteLength(rawContent, "utf-8");
-
-  // Load .graftignore patterns
-  let graftignorePatterns: string[] | undefined;
-  try {
-    const ignoreFile = fs.readFileSync(
-      path.join(input.cwd, ".graftignore"),
-      "utf-8",
-    );
-    graftignorePatterns = loadGraftignore(ignoreFile);
-  } catch {
-    // No .graftignore — that's fine
-  }
-
-  // Evaluate policy
-  const policy = evaluatePolicy(
-    { path: relPath, lines: lines.length, bytes },
-    { graftignorePatterns },
-  );
-
-  // Only block refused files — everything else passes through
-  if (policy instanceof RefusedResult) {
-    const nextSteps = policy.next.map((n) => `  - ${n}`).join("\n");
-    return new HookOutput(2, [
-      `[graft] Refused: ${policy.reason}`,
-      policy.reasonDetail,
-      "",
-      "Next steps:",
-      nextSteps,
-      "",
-      "Graft tools: use file_outline to see the file's structure,",
-      "or safe_read for a policy-aware read with caching.",
-    ].join("\n"));
+  if (inspection.isGovernedCodeRead()) {
+    return new HookOutput(2, renderGovernedReadRedirect(inspection));
   }
 
-  // Content or outline — let Read proceed. PostToolUse will educate.
   return new HookOutput(0, "");
 }
 

package/src/hooks/read-governor.ts

@@ -0,0 +1,95 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { SupportedLang } from "../parser/lang.js";
+import { detectLang } from "../parser/lang.js";
+import { evaluatePolicy } from "../policy/evaluate.js";
+import type { PolicyResult } from "../policy/types.js";
+import { loadGraftignore } from "../policy/graftignore.js";
+import { HookInput, safeRelativePath } from "./shared.js";
+
+export class HookReadInspection {
+  readonly absolutePath: string;
+  readonly relativePath: string;
+  readonly rawContent: string;
+  readonly lines: number;
+  readonly bytes: number;
+  readonly lang: SupportedLang | null;
+  readonly policy: PolicyResult;
+
+  constructor(opts: {
+    absolutePath: string;
+    relativePath: string;
+    rawContent: string;
+    lines: number;
+    bytes: number;
+    lang: SupportedLang | null;
+    policy: PolicyResult;
+  }) {
+    if (opts.absolutePath.length === 0) {
+      throw new Error("HookReadInspection: absolutePath must be non-empty");
+    }
+    if (opts.relativePath.length === 0) {
+      throw new Error("HookReadInspection: relativePath must be non-empty");
+    }
+    if (opts.lines < 0) {
+      throw new Error("HookReadInspection: lines must be non-negative");
+    }
+    if (opts.bytes < 0) {
+      throw new Error("HookReadInspection: bytes must be non-negative");
+    }
+
+    this.absolutePath = opts.absolutePath;
+    this.relativePath = opts.relativePath;
+    this.rawContent = opts.rawContent;
+    this.lines = opts.lines;
+    this.bytes = opts.bytes;
+    this.lang = opts.lang;
+    this.policy = opts.policy;
+    Object.freeze(this);
+  }
+
+  isGovernedCodeRead(): boolean {
+    return this.lang !== null && this.policy.projection === "outline";
+  }
+}
+
+function loadGraftignorePatterns(cwd: string): string[] | undefined {
+  try {
+    const ignoreFile = fs.readFileSync(path.join(cwd, ".graftignore"), "utf-8");
+    return loadGraftignore(ignoreFile);
+  } catch {
+    return undefined;
+  }
+}
+
+export function inspectHookRead(input: HookInput): HookReadInspection | null {
+  const absolutePath = input.tool_input.file_path;
+  const relativePath = safeRelativePath(input.cwd, absolutePath);
+  if (relativePath === null) {
+    return null;
+  }
+
+  let rawContent: string;
+  try {
+    rawContent = fs.readFileSync(absolutePath, "utf-8");
+  } catch {
+    return null;
+  }
+
+  const lines = rawContent.split("\n").length;
+  const bytes = Buffer.byteLength(rawContent, "utf-8");
+  const policy = evaluatePolicy(
+    { path: relativePath, lines, bytes },
+    { graftignorePatterns: loadGraftignorePatterns(input.cwd) },
+  );
+
+  return new HookReadInspection({
+    absolutePath,
+    relativePath,
+    rawContent,
+    lines,
+    bytes,
+    lang: detectLang(absolutePath),
+    policy,
+  });
+}

package/src/hooks/read-messages.ts

@@ -0,0 +1,53 @@
+import { STATIC_THRESHOLDS } from "../policy/evaluate.js";
+import { RefusedResult } from "../policy/types.js";
+import { HookReadInspection } from "./read-governor.js";
+
+function formatKilobytes(bytes: number): string {
+  return (bytes / 1024).toFixed(1);
+}
+
+export function renderRefusedReadMessage(policy: RefusedResult): string {
+  const nextSteps = policy.next.map((step) => `  - ${step}`).join("\n");
+  return [
+    `[graft] Refused: ${policy.reason}`,
+    policy.reasonDetail,
+    "",
+    "Next steps:",
+    nextSteps,
+    "",
+    "Graft tools: use file_outline to see the file's structure,",
+    "or safe_read for a policy-aware read with caching.",
+  ].join("\n");
+}
+
+export function renderGovernedReadRedirect(
+  inspection: HookReadInspection,
+): string {
+  return [
+    `[graft] Governed read: ${inspection.relativePath}`,
+    `Native Read would dump ${String(inspection.lines)} lines (${formatKilobytes(inspection.bytes)}KB) into context.`,
+    "This large JS/TS file should go through graft's bounded-read path instead.",
+    "",
+    "Next steps:",
+    `  - Call safe_read on ${inspection.relativePath}`,
+    "  - Use read_range with jump table entries for the exact region you need",
+    "  - Use file_outline if you only need symbol structure",
+    "",
+    `Threshold: ${String(STATIC_THRESHOLDS.lines)} lines / ${String(STATIC_THRESHOLDS.bytes / 1024)}KB.`,
+  ].join("\n");
+}
+
+export function renderOversizedReadEducation(
+  inspection: HookReadInspection,
+  outlineBytes: number,
+): string {
+  const savedBytes = inspection.bytes - outlineBytes;
+  return [
+    `[graft] This large code read bypassed graft's governed path for ${inspection.relativePath}.`,
+    `safe_read would have returned a structural outline (${String(outlineBytes)} bytes) instead of ${String(inspection.lines)} lines (${formatKilobytes(inspection.bytes)}KB),`,
+    `saving ${formatKilobytes(savedBytes)}KB of context. Threshold: ${String(STATIC_THRESHOLDS.lines)} lines / ${String(STATIC_THRESHOLDS.bytes / 1024)}KB.`,
+    "",
+    "If this was unexpected, verify the Claude PreToolUse hook is installed and active.",
+    "Use read_range with jump table entries after safe_read for targeted follow-up.",
+  ].join("\n");
+}

package/src/mcp/burden.ts

@@ -0,0 +1,123 @@
+import type { McpToolName } from "../contracts/output-schemas.js";
+
+export const BURDEN_KINDS = ["read", "search", "shell", "state", "diagnostic"] as const;
+
+export type BurdenKind = typeof BURDEN_KINDS[number];
+
+export interface BurdenBucket {
+  readonly calls: number;
+  readonly bytesReturned: number;
+}
+
+export type BurdenByKind = Record<BurdenKind, BurdenBucket>;
+
+const ZERO_BUCKET: BurdenBucket = Object.freeze({ calls: 0, bytesReturned: 0 });
+
+const TOOL_BURDEN_KIND: Record<McpToolName, BurdenKind> = {
+  safe_read: "read",
+  file_outline: "read",
+  read_range: "read",
+  changed_since: "read",
+  graft_diff: "search",
+  graft_since: "search",
+  graft_map: "search",
+  code_show: "search",
+  code_find: "search",
+  code_refs: "search",
+  daemon_repos: "diagnostic",
+  daemon_status: "diagnostic",
+  daemon_sessions: "diagnostic",
+  daemon_monitors: "diagnostic",
+  monitor_start: "diagnostic",
+  monitor_pause: "diagnostic",
+  monitor_resume: "diagnostic",
+  monitor_stop: "diagnostic",
+  workspace_authorize: "diagnostic",
+  workspace_authorizations: "diagnostic",
+  workspace_revoke: "diagnostic",
+  workspace_bind: "diagnostic",
+  workspace_status: "diagnostic",
+  causal_status: "diagnostic",
+  causal_attach: "diagnostic",
+  activity_view: "diagnostic",
+  workspace_rebind: "diagnostic",
+  run_capture: "shell",
+  state_save: "state",
+  state_load: "state",
+  set_budget: "diagnostic",
+  explain: "diagnostic",
+  doctor: "diagnostic",
+  stats: "diagnostic",
+};
+
+export function emptyBurdenByKind(): BurdenByKind {
+  return {
+    read: ZERO_BUCKET,
+    search: ZERO_BUCKET,
+    shell: ZERO_BUCKET,
+    state: ZERO_BUCKET,
+    diagnostic: ZERO_BUCKET,
+  };
+}
+
+export function cloneBurdenByKind(source: Readonly<BurdenByKind>): BurdenByKind {
+  return {
+    read: { ...source.read },
+    search: { ...source.search },
+    shell: { ...source.shell },
+    state: { ...source.state },
+    diagnostic: { ...source.diagnostic },
+  };
+}
+
+export function freezeBurdenByKind(source: BurdenByKind): Readonly<BurdenByKind> {
+  for (const kind of BURDEN_KINDS) {
+    Object.freeze(source[kind]);
+  }
+  return Object.freeze(source);
+}
+
+export function burdenKindForTool(tool: McpToolName): BurdenKind {
+  return TOOL_BURDEN_KIND[tool];
+}
+
+export function isNonReadBurdenKind(kind: BurdenKind): boolean {
+  return kind !== "read";
+}
+
+export function projectBurdenByKind(
+  source: Readonly<BurdenByKind>,
+  tool: McpToolName,
+  returnedBytes: number,
+): Readonly<BurdenByKind> {
+  const next = cloneBurdenByKind(source);
+  const kind = burdenKindForTool(tool);
+  const current = next[kind];
+  next[kind] = {
+    calls: current.calls + 1,
+    bytesReturned: current.bytesReturned + returnedBytes,
+  };
+  return freezeBurdenByKind(next);
+}
+
+export function totalNonReadBytesReturned(source: Readonly<BurdenByKind>): number {
+  return BURDEN_KINDS
+    .filter((kind) => isNonReadBurdenKind(kind))
+    .reduce((sum, kind) => sum + source[kind].bytesReturned, 0);
+}
+
+export function topBurdenKind(
+  source: Readonly<BurdenByKind>,
+): { kind: BurdenKind; calls: number; bytesReturned: number } | null {
+  let best: { kind: BurdenKind; calls: number; bytesReturned: number } | null = null;
+
+  for (const kind of BURDEN_KINDS) {
+    const bucket = source[kind];
+    if (bucket.bytesReturned === 0) continue;
+    if (best === null || bucket.bytesReturned > best.bytesReturned) {
+      best = { kind, calls: bucket.calls, bytesReturned: bucket.bytesReturned };
+    }
+  }
+
+  return best;
+}