Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
Merge #456's llm records, and make the budget block records too
KageBinary401b8bd1ff76
diff --cc ix-cli/src/cli/__tests__/context-investigation.test.tsindex 0175072a,98dbe151..89234100--- a/ix-cli/src/cli/__tests__/context-investigation.test.ts+++ b/ix-cli/src/cli/__tests__/context-investigation.test.ts@@@ -268,111 -267,141 +268,253 @@@ describe("ix context investigation statexpect(existsSync(join(home, ".version-check.json"))).toBe(false);});- // `--diff --format llm` used to fall through to the prose renderer (the- // diff path only branched on `json`). The llm branch mirrors `renderBundle`'s- // contract: counts always emitted, items prefixed with `+`/`-` so the wire- // format stays one-record-per-line. These tests pin that.+ it("exposes effective budgets on every --diff diff, sourced from the saved investigation", () => {+ // The reproduction in B-4 showed that --max-* flags on the CLI do not change+ // the fresh side's budget: buildFreshBundle always receives saved.bundle.budgets.+ // The transparency fix surfaces that fact as data instead of hiding it, so+ // agents reading the diff JSON can answer "what budget governed this comparison"+ // without reading the source.+ const saved = bundleWith([makeClaim("renders to DOM", 0.9)]);+ saved.budgets = { maxEntities: 5, maxRelationships: 1, maxEvidence: 2, maxChars: 12000 };+ saveInvestigation("widget-check", saved);+ const stored = loadInvestigation("widget-check")!;+ const fresh = bundleWith([makeClaim("renders to DOM", 0.9)]);++ // Without CLI overrides, requested is absent and effective mirrors saved.+ const baselineDiff = diffInvestigations(stored, fresh);+ expect(baselineDiff.budgets.saved).toEqual({ maxEntities: 5, maxRelationships: 1, maxEvidence: 2, maxChars: 12000 });+ expect(baselineDiff.budgets.requested).toBeUndefined();+ expect(baselineDiff.budgets.effective).toEqual(baselineDiff.budgets.saved);+ expect(baselineDiff.budgets.note).toMatch(/no --max-\* overrides/i);++ // With CLI overrides parsed from raw commander strings, requested captures+ // every flag the user passed (even ones that disagree with saved), and the+ // note makes the precedence explicit.+ const requested = parseRequestedBudgets({ maxEntities: "50", maxEvidence: "25", maxRelationships: "100" });+ expect(requested).toEqual({ maxEntities: 50, maxEvidence: 25, maxRelationships: 100 });++ const overrideDiff = diffInvestigations(stored, fresh, requested);+ expect(overrideDiff.budgets.requested).toEqual(requested);+ // Critical invariant: the fresh bundle was still built with saved budgets,+ // so effective is the saved snapshot, not the requested one.+ expect(overrideDiff.budgets.effective).toEqual(overrideDiff.budgets.saved);+ expect(overrideDiff.budgets.note).toMatch(/--max-\* flags on the CLI are recorded/i);+ });++ it("treats whitespace, empty, or non-numeric --max-* strings as not provided", () => {+ // parseRequestedBudgets must mirror commander semantics: only flag-shaped+ // arguments count as "user override", not noise from shell quoting or+ // accidental empty strings. This is what stops the diff output from+ // reporting a phantom override. Numeric "0" is a real override (someone+ // asking for "0 entities" forces an empty bundle and is what they meant),+ // so it survives the parse — but non-strings, blanks, and NaN-producing+ // tokens do not.+ expect(parseRequestedBudgets({})).toBeUndefined();+ expect(parseRequestedBudgets({ maxEntities: "", maxEvidence: " " })).toBeUndefined();+ expect(parseRequestedBudgets({ maxEntities: undefined })).toBeUndefined();+ expect(parseRequestedBudgets({ maxEntities: "abc" })).toBeUndefined();+ expect(parseRequestedBudgets({ maxEntities: "0" })).toEqual({ maxEntities: 0 });+ expect(parseRequestedBudgets({ maxEntities: "10", maxChars: undefined })).toEqual({ maxEntities: 10 });+ const partial = parseRequestedBudgets({ maxEntities: "10", maxEvidence: "5", maxRelationships: "0", maxChars: "12000" });+ expect(partial).toEqual({ maxEntities: 10, maxEvidence: 5, maxRelationships: 0, maxChars: 12000 });+ });++ it("renders the budget block in --diff text and llm output", () => {+ // Spy on console.log so we can assert exactly what humans and LLMs see.+ // This is the regression guard for the user-visible transparency: if a+ // future refactor flattens renderInvestigationDiff back to "entities/-+ // +", the budget block disappears and the silent ignore comes back.+ const saved = bundleWith([makeClaim("renders to DOM", 0.9)]);+ saved.budgets = { maxEntities: 5, maxRelationships: 1, maxEvidence: 2, maxChars: 12000 };+ saveInvestigation("widget-check", saved);+ const stored = loadInvestigation("widget-check")!;+ const fresh = bundleWith([makeClaim("renders to DOM", 0.9)]);+ const requested = { maxEvidence: 25 };++ const capture = () => {+ const lines: string[] = [];+ const spy = vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {+ lines.push(args.map((a) => String(a)).join(" "));+ });+ return { lines, restore: () => spy.mockRestore() };+ };++ const text = capture();+ try {+ renderInvestigationDiff(stored, fresh, "text", requested);+ } finally {+ text.restore();+ }+ expect(text.lines.some((l) => l.includes("budgets:"))).toBe(true);+ expect(text.lines.some((l) => l.includes("saved :"))).toBe(true);+ expect(text.lines.some((l) => l.includes("requested :")) && text.lines.some((l) => l.includes("evidence=25"))).toBe(true);+ expect(text.lines.some((l) => l.includes("effective :") && l.includes("evidence=2"))).toBe(true);++ const llm = capture();+ try {+ renderInvestigationDiff(stored, fresh, "llm", requested);+ } finally {+ llm.restore();+ }- expect(llm.lines.some((l) => l.trim() === "budgets")).toBe(true);- expect(llm.lines.some((l) => l.includes("saved :") && l.includes("evidence=2"))).toBe(true);- expect(llm.lines.some((l) => l.includes("requested :") && l.includes("evidence=25"))).toBe(true);- expect(llm.lines.some((l) => l.includes("effective :") && l.includes("evidence=2"))).toBe(true);++ // Records, not the prose block with the colons moved. `scope=requested`++ // carries `applied=false` so the precedence rule — saved budgets govern++ // --diff — is a field an agent can test rather than a sentence to read.++ expect(llm.lines).toContain("budgets scope=saved entities=5 relationships=1 evidence=2 chars=12000");++ expect(llm.lines).toContain("budgets scope=requested evidence=25 applied=false");++ expect(llm.lines).toContain("budgets scope=effective entities=5 relationships=1 evidence=2 chars=12000");++ // And none of the prose survives into the record stream.++ expect(llm.lines.some((l) => l.includes(":") && l.startsWith(" "))).toBe(false);++ // json format must already cover this branch in diffInvestigations itself,+ // but assert here that the path is wired and the renderer doesn't double-print.+ const json = capture();+ try {+ renderInvestigationDiff(stored, fresh, "json", requested);+ } finally {+ json.restore();+ }+ expect(json.lines).toHaveLength(1);- const parsed = JSON.parse(json.lines[0].replace(/^undefined$/, ""));++ const parsed = JSON.parse(json.lines[0]);+ expect(parsed.budgets.saved).toEqual(saved.budgets);+ expect(parsed.budgets.requested).toEqual(requested);+ expect(parsed.budgets.effective).toEqual(saved.budgets);+ });++++ // `--diff --format llm` used to fall through to the prose renderer, because++ // the diff path only branched on `json`. The llm branch emits records built++ // by `llmLine`, so a value carrying a space is quoted rather than splitting++ // the record. These tests pin that.+ describe("--format llm rendering", () => {+ function captureLog(fn: () => void): string[] {+ const lines: string[] = [];+ const orig = console.log;+ console.log = (...args: unknown[]) => {+ for (const arg of args) lines.push(String(arg));+ };+ try {+ fn();+ } finally {+ console.log = orig;+ }+ return lines;+ }++ it("emits a header and counts for an empty diff without falling back to prose", () => {+ const saved = bundleWith([makeClaim("renders to DOM", 0.9)]);+ saveInvestigation("widget-llm", saved);+ const stored = loadInvestigation("widget-llm")!;+ const fresh = bundleWith([makeClaim("renders to DOM", 0.9)]);++ const lines = captureLog(() => renderInvestigationDiff(stored, fresh, "llm"));++ expect(lines[0]).toBe(+ "diff investigation=widget-llm target=Widget freshness_previous=current freshness_current=current",+ );+ // Zero is the answer to the question --diff was asked, so it is carried+ // rather than dropped as a default.- expect(lines[1]).toBe(++ expect(lines).toContain(+ "count added_entities=0 removed_entities=0 added_relationships=0 removed_relationships=0" ++ " added_evidence=0 removed_evidence=0 added_claims=0 removed_claims=0",+ );+ // No `renderSection` lines means we did not fall back to prose.+ expect(lines.some((l) => l.startsWith("==") || l.startsWith(" "))).toBe(false);+ });++ it("lists added and removed entities, relationships, evidence and claims", () => {+ const saved = bundleWith([makeClaim("renders to DOM", 0.9)]);+ saveInvestigation("widget-llm-busy", saved);+ const stored = loadInvestigation("widget-llm-busy")!;++ const fresh = buildBundle({+ resolved: { id: "entity-1", name: "Widget", kind: "class", resolutionMode: "exact" },+ facts: makeFacts(),+ context: makeContext({+ claims: [makeClaim("renders to DOM", 0.9), makeClaim("mounts to DOM", 0.7)],+ 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: 1,+ createdAt: "2026-01-01T00:00:00Z",+ updatedAt: "2026-01-01T00:00:00Z",+ },+ {+ id: "entity-3",+ kind: "method",+ name: "mount",+ attrs: {},+ provenance: { sourceUri: "src/widget.ts", extractor: "tree-sitter", sourceType: "source", observedAt: "2026-01-01T00:00:00Z" },+ createdRev: 2,+ createdAt: "2026-01-01T00:00:00Z",+ updatedAt: "2026-01-01T00:00:00Z",+ },+ ],+ // Fresh side replaces the saved `calls` edge with `holds` — so the+ // diff sees a removed relationship (calls) and an added one (holds),+ // matching what an agent would observe when a refactor renames a+ // graph predicate.+ edges: [+ { id: "edge-add", src: "entity-1", dst: "entity-3", predicate: "holds", attrs: {}, createdRev: 2 },+ ],+ }),+ provenance: { sourceType: "source", extractor: "tree-sitter", observedAt: "2026-01-01T00:00:00Z" },+ asOfRev: undefined,+ depth: undefined,+ budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 },+ });++ const lines = captureLog(() => renderInvestigationDiff(stored, fresh, "llm"));++ // Counts match the deterministic diff structure. The fresh bundle adds+ // a new claim (mounts to DOM) and replaces the `calls` evidence with a+ // `holds` one, so it has 2 added evidence records and 1 removed — the+ // skolem IDs are `claim:<claim_id>` and+ // `relationship:<src>:<dst>:<predicate>`, so a stale predicate in the+ // ranked evidence list yields a real added/removed pair.- expect(lines[1]).toBe(++ expect(lines).toContain(+ "count added_entities=1 removed_entities=0 added_relationships=1 removed_relationships=1" ++ " added_evidence=2 removed_evidence=1 added_claims=1 removed_claims=0",+ );++ // The change is a field, not a prefix fused to the record kind, so a+ // consumer routing on `entity` matches both sides of the comparison.+ expect(lines).toContain("entity change=added kind=method name=mount");+ expect(lines).toContain("relationship change=removed src=entity-1 pred=calls dst=entity-2");+ expect(lines).toContain("relationship change=added src=entity-1 pred=holds dst=entity-3");++ // A claim id carries the statement, so it contains spaces — quoted, per+ // docs/llm-format.md. Unquoted, `id=claim-mounts to DOM` is three tokens+ // and a consumer reads the id as `claim-mounts`.+ expect(lines).toContain('claim change=added id="claim-mounts to DOM" status=active');++ // An evidence title is a sentence. Same rule, and the reason the value+ // must never be built with a template literal.+ expect(lines).toContain(+ 'evidence change=added score=30 kind=relationship title="entity-1 --holds--> entity-3"',+ );+ expect(lines).toContain(+ 'evidence change=removed score=30 kind=relationship title="entity-1 --calls--> entity-2"',+ );++ // One record per line — the wire format invariant.+ for (const line of lines) expect(line).not.toContain("\n");+ });++ it("does not regress the prose (text) renderer", () => {+ const saved = bundleWith([makeClaim("renders to DOM", 0.9)]);+ saveInvestigation("widget-llm-text", saved);+ const stored = loadInvestigation("widget-llm-text")!;+ const fresh = bundleWith([makeClaim("renders to DOM", 0.9), makeClaim("mounts to DOM", 0.7)]);++ const lines = captureLog(() => renderInvestigationDiff(stored, fresh, "text"));++ // Prose path still emits its summary header and the `+N`/`-N` totals.+ expect(lines.some((l) => l.includes("Investigation diff: widget-llm-text"))).toBe(true);+ expect(lines.some((l) => /claims:\s+-\d+\s+\+\d+/.test(l))).toBe(true);+ expect(lines.some((l) => /entities:\s+-\d+\s+\+\d+/.test(l))).toBe(true);+ });+ });});diff --cc ix-cli/src/cli/commands/context.tsindex 4879ea3c,8f42d65f..664e4254--- a/ix-cli/src/cli/commands/context.ts+++ b/ix-cli/src/cli/commands/context.ts@@@ -400,51 -390,7 +400,72 @@@ function renderSavedInvestigation(id: srenderBundle(saved.bundle, format);}-export function diffInvestigations(saved: SavedInvestigation, fresh: ContextBundle): InvestigationDiff {+interface BudgetSnapshot {+ maxEntities: number;+ maxRelationships: number;+ maxEvidence: number;+ maxChars: number;+}+++/**++ * A budget snapshot as llm record fields.++ *++ * Absent values are simply absent — `llmField` drops nullish, so a partial++ * override needs no `not-given` sentinel the way the prose form does.++ */++function budgetFields(b: Partial<BudgetSnapshot>): Record<string, number | undefined> {++ return {++ entities: b.maxEntities,++ relationships: b.maxRelationships,++ evidence: b.maxEvidence,++ chars: b.maxChars,++ };++}+++/** Compact one-line representation of a budget snapshot for human rendering. */+function formatBudgets(b: Partial<BudgetSnapshot>, partial = false): string {+ const fmt = (val: number | undefined, key: string): string =>+ `${key}=${val === undefined ? "not-given" : String(val)}`;+ const segments = [+ fmt(b.maxEntities, "entities"),+ fmt(b.maxRelationships, "relationships"),+ fmt(b.maxEvidence, "evidence"),+ fmt(b.maxChars, "chars"),+ ].join(" ");+ return partial ? `${segments} (CLI override; not applied to --diff fresh side)` : segments;+}++/**- * Apply the same clamping rules the action handler uses for direct --save runs- * to a budget object parsed from raw commander string values. Treats an absent- * or whitespace-only string as "user did not pass this flag".++ * Read the raw `--max-*` strings commander collected into numbers.++ *++ * Deliberately *not* clamped, unlike the action handler's `clampInt` calls for++ * a direct run: these values are reported, never applied — saved budgets++ * govern `--diff` — so clamping them would misreport what the caller actually++ * asked for. If they are ever made to win on the fresh side, they must be++ * clamped at that point, and the ranges live in the handler.++ *++ * An absent or whitespace-only string means the flag was not passed.+ */+export function parseRequestedBudgets(opts: Partial<ContextOptions>): Partial<BudgetSnapshot> | undefined {+ const fields: Array<keyof BudgetSnapshot> = ["maxEntities", "maxRelationships", "maxEvidence", "maxChars"];+ const out: Partial<BudgetSnapshot> = {};+ let provided = false;+ for (const key of fields) {+ const raw = opts[key] as string | undefined;+ if (typeof raw !== "string" || raw.trim() === "") continue;+ const parsed = Number.parseInt(raw, 10);+ if (!Number.isFinite(parsed)) continue;+ out[key] = parsed;+ provided = true;+ }+ return provided ? out : undefined;+}++export function diffInvestigations(+ saved: SavedInvestigation,+ fresh: ContextBundle,+ requestedBudgets?: Partial<BudgetSnapshot>,+): InvestigationDiff {const prev = saved.bundle;const addedEntities = fresh.entities.filter((e) => !prev.entities.some((p) => p.id === e.id));const removedEntities = prev.entities.filter((p) => !fresh.entities.some((e) => e.id === p.id));@@@ -528,29 -446,55 +549,76 @@@ export function renderInvestigationDiffconsole.log(JSON.stringify(diff, null, 2));return;}+ if (format === "llm") {+ // `ix context --diff --format llm` used to fall through to the prose+ // renderer below, because this path only branched on `json`. That made the+ // most common agent path the worst one: escaping the prose is what `llm`+ // exists for.+ //+ // Every line goes through `llmLine`, never a template literal. The values+ // here are the ones most likely to contain a space in the whole CLI — an+ // evidence title is a sentence, and a claim id carries the statement — and+ // `key=value` with an unquoted space is not a record a consumer can split.+ // `llmQuote` also encodes newlines, so a title cannot break the one+ // record per line invariant.+ printLlmLines([+ llmLine("diff", {+ investigation: saved.id,+ target: fresh.target.name,+ freshness_previous: prev.freshness.classification,+ freshness_current: fresh.freshness.classification,+ }),++ // Which budgets governed the comparison. `scope=requested` appears++ // only when --max-* flags were passed, and carries `applied=false`++ // rather than a sentence explaining itself: the precedence rule is++ // that saved budgets govern --diff, and a field an agent can test++ // beats a note it has to read.++ llmLine("budgets", { scope: "saved", ...budgetFields(diff.budgets.saved) }),++ ...(diff.budgets.requested++ ? [llmLine("budgets", { scope: "requested", ...budgetFields(diff.budgets.requested), applied: false })]++ : []),++ llmLine("budgets", { scope: "effective", ...budgetFields(diff.budgets.effective) }),+ // One record rather than eight, and the zeros are kept: "nothing was+ // added" is the answer to the question `--diff` was asked, so dropping+ // it as a default would remove the signal.+ llmLine("count", {+ added_entities: diff.added.entities.length,+ removed_entities: diff.removed.entities.length,+ added_relationships: diff.added.relationships.length,+ removed_relationships: diff.removed.relationships.length,+ added_evidence: diff.added.evidence.length,+ removed_evidence: diff.removed.evidence.length,+ added_claims: diff.added.claims.length,+ removed_claims: diff.removed.claims.length,+ }),+ // `change=` rather than a `+`/`-` prefix on the record kind: a consumer+ // routing on the kind should still match `entity` on both sides of the+ // comparison, and a fused marker means it matches neither.+ ...diff.added.entities.map((e) => llmLine("entity", { change: "added", kind: e.kind, name: e.name })),+ ...diff.removed.entities.map((e) => llmLine("entity", { change: "removed", kind: e.kind, name: e.name })),+ ...diff.added.relationships.map((r) => llmLine("relationship", { change: "added", src: r.src, pred: r.predicate, dst: r.dst })),+ ...diff.removed.relationships.map((r) => llmLine("relationship", { change: "removed", src: r.src, pred: r.predicate, dst: r.dst })),+ ...diff.added.evidence.map((e) => llmLine("evidence", { change: "added", score: e.score, kind: e.kind, title: e.title })),+ ...diff.removed.evidence.map((e) => llmLine("evidence", { change: "removed", score: e.score, kind: e.kind, title: e.title })),+ ...diff.added.claims.map((c) => llmLine("claim", { change: "added", id: c.id, status: c.status })),+ ...diff.removed.claims.map((c) => llmLine("claim", { change: "removed", id: c.id, status: c.status })),+ ]);+ return;+ }renderSection(`Investigation diff: ${saved.id}`);console.log(` freshness: ${prev.freshness.classification} -> ${fresh.freshness.classification}`);- if (format === "llm") {- console.log(` budgets`);- console.log(` saved : ${formatBudgets(diff.budgets.saved)}`);- if (diff.budgets.requested) {- console.log(` requested : ${formatBudgets(diff.budgets.requested as BudgetSnapshot, true)}`);- } else {- console.log(` requested : (none — no --max-* flags passed)`);- }- console.log(` effective : ${formatBudgets(diff.budgets.effective)}`);- console.log(` note : ${diff.budgets.note}`);++ // Prose only: `--format llm` returned above with records of its own. The++ // llm branch here used to be this same block with the colons moved, which++ // is the one thing the format is defined not to be.++ console.log(` budgets:`);++ console.log(` saved : ${formatBudgets(diff.budgets.saved)}`);++ if (diff.budgets.requested) {++ console.log(` requested : ${formatBudgets(diff.budgets.requested, true)}`);+ } else {- console.log(` budgets:`);- console.log(` saved : ${formatBudgets(diff.budgets.saved)}`);- if (diff.budgets.requested) {- console.log(` requested : ${formatBudgets(diff.budgets.requested as BudgetSnapshot, true)}`);- } else {- console.log(` requested : (none)`);- }- console.log(` effective : ${formatBudgets(diff.budgets.effective)}`);++ console.log(` requested : (none)`);+ }++ console.log(` effective : ${formatBudgets(diff.budgets.effective)}`);console.log(` entities: -${diff.removed.entities.length} +${diff.added.entities.length}`);console.log(` relationships: -${diff.removed.relationships.length} +${diff.added.relationships.length}`);console.log(` evidence: -${diff.removed.evidence.length} +${diff.added.evidence.length}`);