Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

27.4 KB
Raw Blame
// Copyright 2026 Ix Infrastructure Inc.

import { afterEach, describe, expect, it } from "vitest";

import type {
  ConflictReport,
  DecisionReport,
  EdgeSummary,
  GraphEdge,
  GraphNode,
  IntentReport,
  NodeSummary,
  ScoredClaim,
} from "../../client/types.js";
import type { EntityFacts } from "../explain/facts.js";
import {
  buildBundle, bundleFormat, bundleLlmLines, clampBudgets, llmNextByCut, llmNextLines, renderBundle, sanitizeId,
  textEvidenceLines,
} from "../commands/context.js";

function makeFacts(overrides: Partial<EntityFacts> = {}): EntityFacts {
  return {
    id: "entity-1",
    name: "Widget",
    kind: "class",
    members: ["render", "mount"],
    memberCount: 2,
    callerCount: 3,
    calleeCount: 2,
    dependentCount: 4,
    importerCount: 1,
    downstreamDependents: 6,
    downstreamDepth: 2,
    topCallers: ["App", "Panel", "Shell"],
    topDependents: ["App", "Panel", "Shell", "Frame"],
    historyLength: 5,
    introducedRev: 3,
    stale: false,
    diagnostics: [],
    ...overrides,
  };
}

function makeClaim(statement: string, relevance: number): ScoredClaim {
  return {
    claim: { id: `claim-${statement}`, entityId: "entity-1", statement, status: "active" },
    relevance,
    finalScore: relevance,
    confidence: {
      baseAuthority: { value: 0.5, reason: "base" },
      verification: { value: 0.5, reason: "verify" },
      recency: { value: 0.5, reason: "recent" },
      corroboration: { value: 0.5, reason: "corroborate" },
      conflictPenalty: { value: 0.5, reason: "penalty" },
      intentAlignment: { value: 0.5, reason: "intent" },
      score: 0.5,
    },
  };
}

function makeContext(overrides: Partial<{
  claims: ScoredClaim[];
  conflicts: ConflictReport[];
  decisions: DecisionReport[];
  intents: IntentReport[];
  nodes: GraphNode[];
  edges: GraphEdge[];
  nodeSummaries: NodeSummary[];
  edgeSummaries: EdgeSummary[];
}> = {}) {
  return {
    claims: overrides.claims ?? [makeClaim("renders to DOM", 0.9)],
    conflicts: overrides.conflicts ?? [],
    decisions: overrides.decisions ?? [],
    intents: overrides.intents ?? [],
    nodes:
      overrides.nodes ??
      ([
        {
          id: "entity-2",
          kind: "method",
          name: "render",
          attrs: {},
          provenance: { sourceUri: "src/widget.ts", extractor: "tree-sitter", sourceType: "source", observedAt: "2026-01-01T00:00:00Z" },
          createdRev: 3,
          createdAt: "2026-01-01T00:00:00Z",
          updatedAt: "2026-01-01T00:00:00Z",
        },
      ] as GraphNode[]),
    edges:
      overrides.edges ??
      ([
        { id: "edge-1", src: "entity-1", dst: "entity-2", predicate: "calls", attrs: {}, createdRev: 3 },
      ] as GraphEdge[]),
    nodeSummaries: overrides.nodeSummaries,
    edgeSummaries: overrides.edgeSummaries,
    metadata: { query: "Widget", seedEntities: ["entity-1"], hopsExpanded: 1, asOfRev: 3 },
  };
}

function input() {
  return {
    resolved: { id: "entity-1", name: "Widget", kind: "class", resolutionMode: "exact" },
    facts: makeFacts(),
    context: makeContext(),
    provenance: { sourceType: "source", extractor: "tree-sitter", observedAt: "2026-01-01T00:00:00Z" },
    asOfRev: undefined,
    depth: undefined,
    budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 },
  };
}

describe("ix context bundle", () => {
  it("is deterministic for identical input apart from the declared timestamp", () => {
    const first = buildBundle(input());
    const second = buildBundle(input());

    // The only permitted time-dependent field.
    expect(first.generatedAt).toBeTypeOf("string");
    const { generatedAt: _g1, ...firstStatic } = first;
    const { generatedAt: _g2, ...secondStatic } = second;
    expect(firstStatic).toEqual(secondStatic);
  });

  it("orders evidence by the deterministic tier and a stable id tiebreaker", () => {
    const bundle = buildBundle(input());
    const scores = bundle.evidence.map((item) => item.score);

    expect(scores).toEqual([...scores].sort((a, b) => a - b));
    // The resolved target is the most relevant item.
    expect(bundle.evidence[0]?.kind).toBe("target");
    // Direct structural facts rank above context claims.
    expect(bundle.evidence[1]?.kind).toBe("structural");
    const claimItem = bundle.evidence.find((item) => item.kind === "claim");
    expect(claimItem?.source).toBe("context.claims");
  });

  it("enforces budgets and reports explicit truncation", () => {
    const bundle = buildBundle({
      ...input(),
      budgets: { maxEntities: 1, maxRelationships: 0, maxEvidence: 2, maxTokens: 1500, maxChars: 12000 },
    });

    expect(bundle.entities).toHaveLength(1);
    expect(bundle.truncation.entitiesTruncated).toBeGreaterThan(0);
    expect(bundle.relationships).toHaveLength(0);
    expect(bundle.truncation.relationshipsTruncated).toBe(1);
    expect(bundle.evidence.length).toBeLessThanOrEqual(2);
    expect(bundle.truncation.evidenceTruncated).toBeGreaterThanOrEqual(0);
  });

  it("never keeps a relationship whose endpoint the entity budget cut", () => {
    // The two budgets used to be applied independently, so an edge could be kept
    // while one or both of its endpoints were cut. Measured on a real target at
    // --max-entities 10: 59 of 74 relationships referenced an entity no longer
    // in the bundle, 13 of them at both ends -- and relationshipsTruncated said
    // 0, because nothing had exceeded the RELATIONSHIP budget. The renderer
    // prints those as bare UUIDs, so it looked fine.
    const nodes = ["n1", "n2", "n3", "n4"].map((id) => ({
      id,
      kind: "method",
      name: id,
      attrs: {},
      provenance: { sourceUri: `src/${id}.ts`, extractor: "tree-sitter", sourceType: "source", observedAt: "2026-01-01T00:00:00Z" },
      createdRev: 3,
      createdAt: "2026-01-01T00:00:00Z",
      updatedAt: "2026-01-01T00:00:00Z",
    })) as GraphNode[];
    const edges = [
      { id: "e1", src: "entity-1", dst: "n1", predicate: "calls", attrs: {}, createdRev: 3 },
      { id: "e2", src: "n3", dst: "n4", predicate: "calls", attrs: {}, createdRev: 3 },
    ] as GraphEdge[];

    const bundle = buildBundle({
      ...input(),
      context: makeContext({ nodes, edges }),
      // Room for the target plus a couple of entities, not all four.
      budgets: { maxEntities: 3, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 },
    });

    const kept = new Set(bundle.entities.map((e) => e.id));
    for (const rel of bundle.relationships) {
      expect(kept.has(rel.src)).toBe(true);
      expect(kept.has(rel.dst)).toBe(true);
    }
    // And the count has to be honest: a relationship dropped because its
    // endpoint lost the ENTITY budget is still a relationship the caller did
    // not get, so it belongs in relationshipsTruncated.
    expect(bundle.truncation.relationshipsTruncated).toBe(
      edges.length - bundle.relationships.length,
    );
  });

  it("keeps every relationship when nothing was truncated", () => {
    // The fix must not cost edges in the common case -- it only removes ones
    // that referenced an entity the bundle no longer contains.
    const bundle = buildBundle(input());
    expect(bundle.relationships).toHaveLength(1);
    expect(bundle.truncation.relationshipsTruncated).toBe(0);
    const kept = new Set(bundle.entities.map((e) => e.id));
    expect(kept.has("entity-1") && kept.has("entity-2")).toBe(true);
  });

  it("builds entities and relationships from compact graph summaries", () => {
    const bundle = buildBundle({
      ...input(),
      context: makeContext({
        nodes: [],
        edges: [],
        nodeSummaries: [
          { id: "entity-1", kind: "class", name: "Widget", rev: 3, sourceUri: "src/widget.ts" },
          { id: "entity-2", kind: "method", name: "render", rev: 3, sourceUri: "src/widget.ts" },
          { id: "entity-3", kind: "method", name: "mount", rev: 3, sourceUri: "src/widget.ts" },
        ],
        edgeSummaries: [
          { id: "edge-1", src: "entity-1", dst: "entity-2", predicate: "calls", rev: 3 },
          { id: "edge-2", src: "entity-1", dst: "entity-3", predicate: "calls", rev: 3 },
        ],
      }),
    });

    expect(bundle.entities).toEqual([
      { id: "entity-1", name: "Widget", kind: "class", stale: false },
      { id: "entity-3", name: "mount", kind: "method", path: "src/widget.ts", stale: false },
      { id: "entity-2", name: "render", kind: "method", path: "src/widget.ts", stale: false },
    ]);
    expect(bundle.relationships).toEqual([
      { src: "entity-1", dst: "entity-2", predicate: "calls" },
      { src: "entity-1", dst: "entity-3", predicate: "calls" },
    ]);
  });

  it("classifies a workspace with no completed source graph as unverified", () => {
    const bundle = buildBundle({ ...input(), graphCompleted: false });

    expect(bundle.freshness.classification).toBe("unverified");
  });

  it("does not let an unverified workspace masquerade as stale", () => {
    // `stale` is a claim that a file changed since ingest. Without a baseline
    // nothing is known to have changed, so the two states stay distinguishable:
    // an agent can re-map on unverified without being told its files are dirty.
    const unverified = buildBundle({ ...input(), graphCompleted: false });
    const stale = buildBundle({
      ...input(), graphCompleted: true, facts: makeFacts({ stale: true }),
    });

    expect(unverified.freshness.classification).toBe("unverified");
    expect(unverified.freshness.stale).toBe(false);
    expect(stale.freshness.classification).toBe("stale");
  });

  it("asks about each entity's own staleness instead of copying the target's", () => {
    // `freshness` is the target's, from the facts collector. Every other entity
    // has its own source file and its own answer — stamping the target's onto
    // all of them reported untouched dependencies as stale whenever the target
    // was, which is the field an agent reads to decide what to trust.
    const asked: string[] = [];
    const bundle = buildBundle({
      ...input(),
      facts: makeFacts({ stale: true, path: "src/widget.ts" }),
      isStale: (path) => {
        asked.push(path);
        return false; // the dependency is current even though the target is not
      },
    });

    const target = bundle.entities.find((e) => e.id === "entity-1");
    const dependency = bundle.entities.find((e) => e.id === "entity-2");
    expect(target?.stale).toBe(true);
    expect(dependency?.stale).toBe(false);
    expect(bundle.freshness).toEqual({ stale: true, classification: "stale" });
    // The target is not re-probed; its answer was already collected.
    expect(asked).toEqual(["src/widget.ts"]);
  });

  it("probes no more entities than the budget keeps", () => {
    const nodes = Array.from({ length: 40 }, (_, i) => ({
      id: `n-${i}`,
      kind: "method",
      name: `m${i}`,
      attrs: {},
      provenance: { sourceUri: `src/f${i}.ts`, extractor: "tree-sitter", sourceType: "source", observedAt: "2026-01-01T00:00:00Z" },
      createdRev: 1,
      createdAt: "2026-01-01T00:00:00Z",
      updatedAt: "2026-01-01T00:00:00Z",
    })) as GraphNode[];
    let probes = 0;

    buildBundle({
      ...input(),
      context: makeContext({ nodes }),
      budgets: { maxEntities: 5, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 },
      isStale: () => { probes += 1; return false; },
    });

    // 5 kept, minus the target whose answer is already known.
    expect(probes).toBe(4);
  });

  it("classifies staleness from the collected facts", () => {
    const stale = buildBundle({ ...input(), facts: makeFacts({ stale: true }) });
    expect(stale.freshness).toEqual({ stale: true, classification: "stale" });

    const current = buildBundle({ ...input(), facts: makeFacts({ stale: false }) });
    expect(current.freshness).toEqual({ stale: false, classification: "current" });
  });

  it("orders claims, decisions, conflicts, and intents deterministically", () => {
    const decisions: DecisionReport[] = [
      { title: "zeta", rationale: "late", entityId: "entity-1", rev: 1 },
      { title: "alpha", rationale: "second", entityId: "entity-1", rev: 1 },
      { title: "alpha", rationale: "first", entityId: "entity-1", rev: 2 },
    ];
    const conflicts: ConflictReport[] = [
      { id: "c-1", claimA: "zeta claim", claimB: "delta claim", reason: "r", recommendation: "rec" },
      { id: "c-2", claimA: "alpha claim", claimB: "beta claim", reason: "r", recommendation: "rec" },
    ];
    const intents: IntentReport[] = [
      { id: "i-2", statement: "zeta intent", status: "active", confidence: 0.5 },
      { id: "i-1", statement: "alpha intent", status: "active", confidence: 0.5 },
    ];
    const claims = [makeClaim("zeta statement", 0.5), makeClaim("alpha one", 0.9), makeClaim("alpha two", 0.7)];
    const shuffled = {
      claims: [...claims].reverse(),
      conflicts: [...conflicts].reverse(),
      decisions: [...decisions].reverse(),
      intents: [...intents].reverse(),
    };

    const first = buildBundle({ ...input(), context: makeContext(shuffled) });
    const second = buildBundle({ ...input(), context: makeContext({ ...shuffled }) });

    expect(first.claims.map((c) => c.statement)).toEqual(["alpha one", "alpha two", "zeta statement"]);
    expect(first.decisions.map((d) => d.title)).toEqual(["alpha", "alpha", "zeta"]);
    expect(first.conflicts.map((c) => c.claimA)).toEqual(["alpha claim", "zeta claim"]);
    expect(first.intents.map((i) => i.statement)).toEqual(["alpha intent", "zeta intent"]);
    // Same data in any input order produces the same bundle sections.
    expect(second.claims).toEqual(first.claims);
    expect(second.decisions).toEqual(first.decisions);
    expect(second.conflicts).toEqual(first.conflicts);
    expect(second.intents).toEqual(first.intents);
  });

  it("keeps conflicts out of the evidence list", () => {
    const conflicts: ConflictReport[] = Array.from({ length: 8 }, (_, i) => ({
      id: `c-${i}`,
      claimA: `12e6db16-e88f-34d1-92ab-4d1700fd67a${i}`,
      claimB: `494d48cd-fff5-37a9-93f5-060c0760c52${i}`,
      reason: "Potential inconsistency (same field prefix)",
      recommendation: "rec",
    }));

    const bundle = buildBundle({ ...input(), context: makeContext({ conflicts }) });

    expect(bundle.evidence.some((item) => item.kind === "conflict")).toBe(false);
    // A claim uuid is not something an agent can act on; none should be
    // reachable through the evidence list at all.
    const rendered = JSON.stringify(bundle.evidence);
    expect(rendered).not.toContain("12e6db16");
    // The reports themselves are still carried, and still counted.
    expect(bundle.conflicts).toHaveLength(8);
  });

  it("leaves the evidence budget to real structure when conflicts are present", () => {
    // The regression this exists for: 8 conflicts used to take 8 of the 10
    // slots and push the structural facts out of the bundle entirely.
    const conflicts: ConflictReport[] = Array.from({ length: 8 }, (_, i) => ({
      id: `c-${i}`,
      claimA: `claim-a-${i}`,
      claimB: `claim-b-${i}`,
      reason: "Potential inconsistency (same field prefix)",
      recommendation: "rec",
    }));
    const budgets = { maxEntities: 50, maxRelationships: 100, maxEvidence: 10, maxTokens: 1500, maxChars: 12000 };

    const withConflicts = buildBundle({ ...input(), budgets, context: makeContext({ conflicts }) });
    const without = buildBundle({ ...input(), budgets, context: makeContext() });

    const structural = (b: typeof withConflicts) => b.evidence.filter((i) => i.kind === "structural").length;
    expect(structural(withConflicts)).toBe(structural(without));
    expect(structural(withConflicts)).toBeGreaterThan(0);
  });

  it("caps the conflict reports it carries and says how many it dropped", () => {
    const conflicts: ConflictReport[] = Array.from({ length: 31 }, (_, i) => ({
      id: `c-${String(i).padStart(2, "0")}`,
      claimA: `claim-a-${String(i).padStart(2, "0")}`,
      claimB: `claim-b-${String(i).padStart(2, "0")}`,
      reason: "Potential inconsistency (same field prefix)",
      recommendation: "rec",
    }));

    const bundle = buildBundle({ ...input(), context: makeContext({ conflicts }) });

    expect(bundle.conflicts).toHaveLength(10);
    expect(bundle.truncation.conflictsTruncated).toBe(21);
    // Kept + dropped still reports the true count to the renderers.
    expect(bundle.conflicts.length + bundle.truncation.conflictsTruncated).toBe(31);
    // The cut is taken after the deterministic sort, so it is reproducible.
    expect(bundle.conflicts.map((c) => c.claimA)).toEqual(
      Array.from({ length: 10 }, (_, i) => `claim-a-${String(i).padStart(2, "0")}`),
    );
  });

  it("reports no conflict truncation when the bundle is under the cap", () => {
    const bundle = buildBundle({ ...input(), context: makeContext() });
    expect(bundle.truncation.conflictsTruncated).toBe(0);
  });

  it("bounds evidence by the exact serialized representation, not an estimate", () => {
    const claims = Array.from({ length: 60 }, (_, i) => makeClaim(`statement number ${i} with some padding text`, 0.5));
    const budgets = { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 500 };

    const bundle = buildBundle({ ...input(), context: makeContext({ claims }), budgets });

    // maxChars bounds the sum of the serialized JSON sizes of the kept items.
    const keptSerialized = bundle.evidence.reduce((sum, item) => sum + JSON.stringify(item).length, 0);
    expect(keptSerialized).toBeLessThanOrEqual(500);
    expect(bundle.evidence.length).toBeLessThan(25); // the char budget bit before the count budget
    expect(bundle.truncation.evidenceTruncated).toBeGreaterThan(0);
    expect(bundle.truncation.charactersTruncated).toBeGreaterThan(0);
    // Identical inputs produce an identical budgeted list.
    expect(bundle.evidence).toEqual(
      buildBundle({ ...input(), context: makeContext({ claims }), budgets }).evidence,
    );
  });

  it("encodes investigation ids injectively so distinct ids never collide", () => {
    expect(sanitizeId("widget-check")).toBe("widget-check");
    expect(sanitizeId("a/b")).not.toBe(sanitizeId("a?b"));
    expect(sanitizeId("a/b")).not.toBe(sanitizeId("a:b"));
    expect(sanitizeId("a?b")).not.toBe(sanitizeId("a~2Fb"));
    expect(sanitizeId("~")).toBe("~7E");
    expect(sanitizeId("../../etc/passwd")).not.toContain("/");
    expect(sanitizeId("C:\\Windows")).not.toContain("\\");
    expect(sanitizeId("")).toBe("unnamed");
    // No id may produce a dotfile, and encoding the dot only in first position
    // keeps the mapping injective.
    expect(sanitizeId(".version-check")).toBe("~2Eversion-check");
    expect(sanitizeId(".version-check")).not.toBe(sanitizeId("~2Eversion-check"));
    expect(sanitizeId("a.b")).toBe("a.b");
    const names = ["a/b", "a?b", "a:b", "a~2Fb", "C:\\Windows", "../..", "~"].map(sanitizeId);
    expect(new Set(names).size).toBe(names.length);
  });
});

describe("ix context budget is charged against the emitted text", () => {
  const manyMembers = () => {
    const members = Array.from({ length: 150 }, (_, i) => `member_function_number_${i}`);
    const facts = makeFacts({ members, memberCount: 150 });
    const nodes = Array.from({ length: 150 }, (_, i) => ({
      id: `n-${i}`, kind: "function", name: `callee_${i}`, attrs: {},
      provenance: { sourceUri: `src/file_${i}.ts` }, createdRev: 1,
      createdAt: "2026-01-01T00:00:00Z", updatedAt: "2026-01-01T00:00:00Z",
    })) as GraphNode[];
    const edges = Array.from({ length: 150 }, (_, i) => ({
      id: `e-${i}`, src: "entity-1", dst: `n-${i}`, predicate: "calls", attrs: {}, createdRev: 1,
    })) as GraphEdge[];
    return { ...input(), facts, context: makeContext({ nodes, edges }) };
  };

  // Members with ranges, two sharing one, and some without: the shapes the
  // `next` rows skip or dedupe.
  const readableMembers = () => {
    const memberRefs = Array.from({ length: 12 }, (_, i) => ({
      id: `m-${i}`, name: `member_${i}`, kind: "function", path: "src/widget.ts",
      ...(i % 3 === 1 ? {} : { lineStart: i < 2 ? 10 : 10 + i * 20, lineEnd: i < 2 ? 20 : 20 + i * 20 }),
    }));
    const facts = makeFacts({
      path: "src/widget.ts", memberRefs, members: memberRefs.map((m) => m.name), memberCount: memberRefs.length,
    });
    return { ...input(), facts };
  };

  const emitted = (bundle: ReturnType<typeof buildBundle>, format: string): string => {
    const lines: string[] = [];
    const orig = console.log;
    console.log = (...a: unknown[]) => void lines.push(a.map(String).join(" "));
    try {
      renderBundle(bundle, format);
    } finally {
      console.log = orig;
    }
    return lines.join("\n");
  };

  const prevCaller = process.env.IX_CALLER;
  afterEach(() => {
    if (prevCaller === undefined) delete process.env.IX_CALLER;
    else process.env.IX_CALLER = prevCaller;
  });

  for (const caller of [undefined, "mcp"]) {
    it(`emits within 10% of maxChars in llm when evidence was cut (IX_CALLER=${caller ?? "unset"})`, () => {
      if (caller) process.env.IX_CALLER = caller;
      else delete process.env.IX_CALLER;
      const budgets = clampBudgets({ maxTokens: 600 }, "llm");
      const bundle = buildBundle({ ...manyMembers(), budgets, format: "llm" });
      expect(bundle.truncation.evidenceTruncated).toBeGreaterThan(0);
      const out = emitted(bundle, "llm");
      expect(out.length).toBeLessThanOrEqual(budgets.maxChars);
      expect(out.length).toBeGreaterThanOrEqual(0.9 * budgets.maxChars);
      expect(bundle.budgets.format).toBe("llm");
    });
  }

  // A sample of budgets, each probed at its own boundary: the output it
  // settled at, and one character under. Landing exactly on maxChars is where
  // a `truncated_chars` placeholder that grows after the fit was checked would
  // overrun, so each sample tests the tightest budgets rather than hoping a
  // dense sweep lands on them. Every 25th value keeps this to ~120 builds.
  it("never emits past maxChars in llm once the truncated_chars header is final", () => {
    delete process.env.IX_CALLER;
    const base = clampBudgets({ maxEvidence: 200 }, "llm");
    const build = (maxChars: number) => {
      const bundle = buildBundle({ ...manyMembers(), budgets: { ...base, maxChars }, format: "llm" });
      expect(bundle.truncation.evidenceTruncated, `cut at ${maxChars}`).toBeGreaterThan(0);
      expect(bundle.truncation.charactersTruncated).toBeGreaterThan(0);
      const out = emitted(bundle, "llm").length;
      expect(out, `emitted at maxChars=${maxChars}`).toBeLessThanOrEqual(maxChars);
      return { bundle, out };
    };
    let samples = 0;
    for (let maxChars = 1500; maxChars <= 2500; maxChars += 25) {
      const { bundle, out } = build(maxChars);
      // Exactly at the size it settled at, it keeps the same rows.
      expect(build(out).bundle.evidence.length).toBe(bundle.evidence.length);
      // One under, it must drop a row rather than overrun.
      build(out - 1);
      samples += 1;
    }
    expect(samples).toBe(41);
  });

  // The fitting loop measures the llm output at many cuts with the `next`
  // rows looked up, not recomputed (#834 makes them read files). The lookup
  // must give the lines a fresh computation would at every cut, or the size
  // measured is not the size printed.
  for (const caller of [undefined, "mcp"]) {
    it(`looks up the same next lines a fresh computation gives, at every cut (IX_CALLER=${caller ?? "unset"})`, () => {
      if (caller) process.env.IX_CALLER = caller;
      else delete process.env.IX_CALLER;
      const big = clampBudgets({ maxChars: 100000, maxEvidence: 200 }, "llm");
      const bundle = buildBundle({ ...readableMembers(), budgets: big, format: "llm" });
      const evidence = bundle.evidence;
      // Rows without a range and rows repeating one are in the list, so the
      // breakpoints are not simply the first three rows.
      expect(evidence.filter((e) => e.location?.lineStart === undefined).length).toBeGreaterThan(0);
      const nextAt = llmNextByCut(bundle, evidence);
      for (let count = 0; count <= evidence.length; count++) {
        const prefix = { ...bundle, evidence: evidence.slice(0, count) };
        expect(nextAt(count), `cut at ${count}`).toEqual(llmNextLines(prefix));
        expect(bundleLlmLines(prefix, nextAt(count))).toEqual(bundleLlmLines(prefix));
      }
    });
  }

  it("keeps every row when the whole bundle fits exactly (no reserved diagnostic)", () => {
    const big = clampBudgets({ maxChars: 100000, maxEvidence: 200 }, "llm");
    const full = buildBundle({ ...manyMembers(), budgets: big, format: "llm" });
    expect(full.truncation.evidenceTruncated).toBe(0);
    const exact = emitted(full, "llm").length;
    const tight = { ...big, maxChars: exact };
    const bundle = buildBundle({ ...manyMembers(), budgets: tight, format: "llm" });
    expect(bundle.evidence.length).toBe(full.evidence.length);
  });

  it("bounds json evidence by its serialization, and cuts only where the next row would not fit", () => {
    const budgets = clampBudgets({ maxTokens: 600 }, "json");
    const bundle = buildBundle({ ...manyMembers(), budgets, format: "json" });
    expect(bundle.truncation.evidenceTruncated).toBeGreaterThan(0);
    const kept = bundle.evidence.reduce((n, e) => n + JSON.stringify(e).length, 0);
    expect(kept).toBeLessThanOrEqual(budgets.maxChars);
    // The cut is a prefix, so how full it is depends on the size of the row at
    // the boundary (here the one "used by" row, larger than a member row). What
    // must hold is that the first dropped row did not fit.
    const all = buildBundle({ ...manyMembers(), budgets: clampBudgets({ maxEvidence: 200, maxTokens: 200_000 }, "json"), format: "json" });
    const next = all.evidence[bundle.evidence.length]!;
    expect(kept + JSON.stringify(next).length).toBeGreaterThan(budgets.maxChars);
    expect(kept).toBeGreaterThanOrEqual(0.8 * budgets.maxChars);
  });

  it("bounds text evidence by the lines it prints, leaving room for the header", () => {
    const budgets = clampBudgets({ maxTokens: 600 }, "text");
    const bundle = buildBundle({ ...manyMembers(), budgets, format: "text" });
    expect(bundle.truncation.evidenceTruncated).toBeGreaterThan(0);
    const kept = bundle.evidence.reduce(
      (n, e) => n + textEvidenceLines(e).reduce((m, l) => m + l.length + 1, 0), 0);
    expect(kept).toBeLessThanOrEqual(budgets.maxChars - 600);
  });

  it("keeps the target row when it alone is larger than the budget", () => {
    for (const format of ["llm", "json", "text"] as const) {
      const bundle = buildBundle({
        ...manyMembers(),
        budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 200, maxTokens: 500, maxChars: 10 },
        format,
      });
      expect(bundle.evidence.length).toBe(1);
      expect(bundle.evidence[0]!.kind).toBe("target");
    }
  });

  it("reports charactersTruncated as full minus kept in the format's own unit", () => {
    const budgets = clampBudgets({ maxTokens: 600, maxEvidence: 200 }, "json");
    const cut = buildBundle({ ...manyMembers(), budgets, format: "json" });
    const wide = buildBundle({
      ...manyMembers(), format: "json", budgets: { ...budgets, maxChars: 1_000_000 },
    });
    const full = wide.evidence.reduce((n, e) => n + JSON.stringify(e).length, 0);
    const kept = cut.evidence.reduce((n, e) => n + JSON.stringify(e).length, 0);
    expect(cut.truncation.charactersTruncated).toBe(full - kept);
  });

  it("maps formats the way renderBundle does", () => {
    expect(bundleFormat("json")).toBe("json");
    expect(bundleFormat("llm")).toBe("llm");
    expect(bundleFormat("text")).toBe("text");
    expect(bundleFormat(undefined)).toBe("text");
  });
});