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
fix(context): validate saved investigation state on read, not just on write (#455)
Joseph Mikhailccc5cce92246
diff --git a/ix-cli/src/cli/__tests__/context-investigation.test.ts b/ix-cli/src/cli/__tests__/context-investigation.test.tsindex b10e6737..3aff7aa7 100644--- a/ix-cli/src/cli/__tests__/context-investigation.test.ts+++ b/ix-cli/src/cli/__tests__/context-investigation.test.ts@@ -1,7 +1,7 @@-import { existsSync, mkdtempSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";+import { existsSync, mkdtempSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";import { tmpdir } from "node:os";import { join } from "node:path";-import { afterEach, beforeEach, describe, expect, it } from "vitest";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";import type {ConflictReport,@@ -21,10 +21,16 @@ import {} from "../commands/context.js";let home: string;+let priorExitCode: number | string | undefined;beforeEach(() => {home = mkdtempSync(join(tmpdir(), "ix-investigation-test-"));process.env.IX_HOME = home;+ // loadInvestigation sets process.exitCode on a refusal. That is the host+ // process's exit code, so leaving it set would fail the whole vitest run even+ // with every test green.+ priorExitCode = process.exitCode;+ process.exitCode = undefined;// IX_HOME is the Ix home directory; investigations live in a subdirectory of// it, which saveInvestigation creates. Nothing is pre-created here — the tests// below assert on where the code actually writes, not on a directory the test@@ -36,9 +42,44 @@ const investigationsDir = () => join(home, "investigations");afterEach(() => {delete process.env.IX_HOME;+ process.exitCode = priorExitCode;rmSync(home, { recursive: true, force: true });});+/** Write a raw state file exactly where loadInvestigation looks for it. */+function writeState(id: string, state: unknown): void {+ mkdirSync(investigationsDir(), { recursive: true });+ writeFileSync(join(investigationsDir(), `${id}.json`), JSON.stringify(state), "utf8");+}++/** A well-formed envelope around `bundle`, so only the bundle is under test. */+function envelope(id: string, bundle: unknown) {+ return { schema: "ix-investigation/1", id, savedAt: "2026-01-01T00:00:00Z", bundle };+}++/**+ * Capture what renderWarning printed while `fn` ran.+ *+ * The refusal message is the only thing that says *which* guard rejected a+ * fixture; asserting on the return value alone cannot tell the envelope check+ * from the schema check. renderWarning goes to console.log (ui.ts), so that is+ * what gets spied on.+ */+function captureWarnings(fn: () => void): string {+ const lines: string[] = [];+ const spy = vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {+ lines.push(args.map(String).join(" "));+ });+ try {+ fn();+ } finally {+ spy.mockRestore();+ }+ // chalk wraps the message as a whole, so the text stays contiguous; strip the+ // colour codes anyway so a CI run with colour forced on matches a local one.+ return lines.join("\n").replace(/\u001b\[[0-9;]*m/g, "");+}+function makeFacts(overrides: Partial<EntityFacts> = {}): EntityFacts {return {id: "entity-1",@@ -156,6 +197,119 @@ describe("ix context investigation state", () => {expect(loadInvestigation("broken")).toBeUndefined();});+ it("refuses to resume a tampered bundle, and says the bundle was what failed", () => {+ // The write path is schema-checked, so a non-conforming bundle can only+ // reach disk by being put there — a hand-edited file, a truncated write, or+ // a state file from a different version. The envelope is deliberately+ // *correct* here, so only bundle validation can be what rejects it.+ writeState("tampered", envelope("tampered", { ...bundleWith([]), entities: "not-an-array" }));++ const warning = captureWarnings(() => {+ expect(loadInvestigation("tampered")).toBeUndefined();+ });++ // Which guard fired is only observable in the message. Asserting on the+ // envelope fields of the fixture object instead would compare a literal to+ // itself and could never fail, leaving the envelope check and the schema+ // check indistinguishable.+ expect(warning).toContain("does not match the ix-context-bundle/1 schema");+ expect(warning).not.toContain("unknown schema");+ expect(process.exitCode).toBe(1);+ });++ it("refuses a bundle written against a different contract version", () => {+ // The whole point of a versioned contract: `schema` is pinned to a literal,+ // so a v99 body cannot be rendered by --resume or re-sent by --diff as if+ // it were a v1 one. A `z.string()` here would accept this.+ writeState("skewed", envelope("skewed", { ...bundleWith([]), schema: "ix-context-bundle/99" }));++ const warning = captureWarnings(() => {+ expect(loadInvestigation("skewed")).toBeUndefined();+ });++ expect(warning).toContain("different contract than ix-context-bundle/1");+ });++ it("refuses an evidence item with no title, which the llm renderer dereferences", () => {+ // renderBundle does `item.title.replaceAll(...)` for --format llm. Validation+ // that accepts an untyped evidence record just moves the failure downstream+ // from a named refusal to an uncaught TypeError.+ const evidence = [{ id: "e1", kind: "provenance", source: "s", score: 1, reason: "r", refs: [] }];+ writeState("titleless", envelope("titleless", { ...bundleWith([]), evidence }));++ expect(loadInvestigation("titleless")).toBeUndefined();+ });++ it("refuses empty budgets, which would fabricate an all-removed diff", () => {+ // --diff forwards saved budgets into buildFreshBundle, where+ // `Math.min(n, undefined)` is NaN and `slice(0, NaN)` is []. The fresh side+ // comes back empty and every saved item is reported as removed — a delta+ // that never happened, with no error anywhere.+ writeState("budgetless", envelope("budgetless", { ...bundleWith([]), budgets: {} }));++ expect(loadInvestigation("budgetless")).toBeUndefined();+ });++ it("refuses metadata whose diff inputs are not the types --diff re-sends", () => {+ // mergeDiffOptions passes metadata.depth and metadata.asOfRev straight into+ // the next backend request. They are the only saved values besides+ // target.name that leave the machine, so they are typed, not trusted.+ const metadata = { rankingRule: "deterministic-tier", depth: { nested: true }, asOfRev: "not-a-number" };+ writeState("bad-metadata", envelope("bad-metadata", { ...bundleWith([]), metadata }));++ expect(loadInvestigation("bad-metadata")).toBeUndefined();+ });++ // One field per fixture. A single fixture breaking both `id` and `savedAt`+ // passes as soon as *either* rule fires, so it cannot show that both are+ // enforced — dropping the savedAt check entirely left such a test green.+ it("refuses an envelope whose id is not a string", () => {+ // id is rendered to the terminal and copied into the emitted+ // ix-investigation-diff/1 JSON as `investigation`, so an unvalidated+ // envelope prints `Resumed investigation "[object Object]"`.+ writeState("bad-id", { schema: "ix-investigation/1", id: {}, savedAt: "2026-01-01T00:00:00Z", bundle: bundleWith([]) });++ expect(loadInvestigation("bad-id")).toBeUndefined();+ });++ it("refuses an envelope whose savedAt is not a string", () => {+ // savedAt is rendered as `saved <value>` and copied into the emitted diff.+ // The id here is deliberately valid so the id rule cannot be what fires.+ writeState("bad-savedat", { schema: "ix-investigation/1", id: "bad-savedat", savedAt: null, bundle: bundleWith([]) });++ expect(loadInvestigation("bad-savedat")).toBeUndefined();+ });++ it("refuses an id carrying terminal control characters", () => {+ // sanitizeId escapes these on the way in, so a stored id can never contain+ // them; renderNote and renderSection write the id straight to the terminal.+ writeState("ansi", { ...envelope("bad\u001b[31mid", bundleWith([])) });++ expect(loadInvestigation("ansi")).toBeUndefined();+ });++ it("returns the validated bundle, not the raw file contents", () => {+ // Control for the refusals above — a validator that rejected everything+ // would fail here — and the sanitization guarantee: saveInvestigation+ // persists zod's parsed output, so the read side must too. Returning the raw+ // JSON.parse result instead would echo smuggled keys back out through+ // `--resume --format json` and into the emitted diff.+ const bundle = bundleWith([makeClaim("renders to DOM", 0.9)]);+ saveInvestigation("well-formed", bundle);+ const stored = JSON.parse(readFileSync(join(investigationsDir(), "well-formed.json"), "utf8"));+ stored.bundle.target.EXTRA = "smuggled";+ writeState("well-formed", stored);++ const loaded = loadInvestigation("well-formed");++ expect(loaded).toBeDefined();+ expect(loaded?.bundle.target.name).toBe("Widget");+ expect(loaded?.bundle.evidence).toEqual(bundle.evidence);+ expect(loaded?.bundle.target).not.toHaveProperty("EXTRA");+ // A successful load must not leave a failing status behind.+ expect(process.exitCode).toBeUndefined();+ });+it("refuses to save a bundle that does not match the versioned contract", () => {const malformed = { ...bundleWith([]), entities: "not-an-array" } as unknown as ReturnType<typeof buildBundle>;saveInvestigation("bad-shape", malformed);diff --git a/ix-cli/src/cli/__tests__/mcp.test.ts b/ix-cli/src/cli/__tests__/mcp.test.tsindex 7263affc..25a4678c 100644--- a/ix-cli/src/cli/__tests__/mcp.test.ts+++ b/ix-cli/src/cli/__tests__/mcp.test.ts@@ -47,7 +47,11 @@ function contextBundle() {decisions: [],conflicts: [],intents: [],- provenance: {},+ // buildBundle always emits these two (context.ts: `historyLength:+ // facts.historyLength` and `stale`), so an empty provenance is a bundle the+ // CLI cannot actually produce. The fixture has to be a bundle that could+ // come off the wire, or it proves nothing about the real contract.+ provenance: { historyLength: 0, stale: false },freshness: { stale: false, classification: "current" },evidence: [],budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 },diff --git a/ix-cli/src/cli/commands/context.ts b/ix-cli/src/cli/commands/context.tsindex 5d868db9..a2d7b846 100644--- a/ix-cli/src/cli/commands/context.ts+++ b/ix-cli/src/cli/commands/context.ts@@ -3,7 +3,11 @@ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSyncimport { homedir } from "node:os";import { dirname, join, resolve } from "node:path";-import { contextBundleSchema } from "../context-bundle-schema.js";+import {+ BUNDLE_SCHEMA,+ contextBundleSchema,+ savedInvestigationSchema,+} from "../context-bundle-schema.js";import { IxClient } from "../../client/api.js";import type {@@ -21,12 +25,6 @@ import { resolveFileOrEntity } from "../resolve.js";import { createStaleProbe } from "../stale.js";import { renderNote, renderSection, renderWarning } from "../ui.js";-/**- * Schema version for the deterministic bundle shape. Bump only on a breaking- * shape change, never per run.- */-const BUNDLE_SCHEMA = "ix-context-bundle/1";-interface ContextOptions {kind?: string;path?: string;@@ -360,23 +358,68 @@ export function mergeDiffOptions(};}+/**+ * Refuse a saved investigation: warn, and set a non-zero status so a scripted+ * `--resume`/`--diff` can tell a refusal from a successful render. The sibling+ * commands (config, init, map) already signal refusals this way.+ */+function refuseInvestigation(message: string): undefined {+ renderWarning(message);+ process.exitCode = 1;+ return undefined;+}+export function loadInvestigation(id: string): SavedInvestigation | undefined {const path = investigationPath(id);if (!existsSync(path)) {- renderWarning(`No saved investigation "${id}" at ${path}`);- return undefined;+ return refuseInvestigation(`No saved investigation "${id}" at ${path}`);}+ let raw: unknown;+ // Scoped to the read and the parse: those are the only calls here that throw,+ // and widening it would report a validation or rendering failure below as+ // "not valid JSON" — naming the wrong cause on a file that parses fine.try {- const parsed = JSON.parse(readFileSync(path, "utf8")) as SavedInvestigation;- if (parsed.schema !== "ix-investigation/1" || !parsed.bundle) {- renderWarning(`Saved investigation "${id}" has an unknown schema; refusing to resume.`);- return undefined;- }- return parsed;+ raw = JSON.parse(readFileSync(path, "utf8"));} catch {- renderWarning(`Saved investigation "${id}" is not valid JSON; refusing to resume.`);- return undefined;+ return refuseInvestigation(`Saved investigation "${id}" is not valid JSON; refusing to resume.`);+ }++ // Validate the whole envelope coming back off disk against the same versioned+ // contract the write side enforces (saveInvestigation and --out). The two+ // halves were asymmetric: writes were schema-checked, reads trusted a bare+ // `as` cast guarded only by a truthiness check on `bundle`. That gap is+ // reachable — `--diff` re-resolves `bundle.target.name`, `metadata.depth` and+ // `metadata.asOfRev` and sends them to the backend, and `--resume` renders the+ // bundle — so a file whose `schema` field was right and whose body was+ // anything at all used to be honoured.+ const parsed = savedInvestigationSchema.safeParse(raw);+ if (!parsed.success) {+ const issues = parsed.error.issues;+ // Distinguish the two version-skew cases from a generic shape mismatch, so+ // the warning names which contract was not met.+ if (issues.some((issue) => issue.path[0] === "schema")) {+ return refuseInvestigation(`Saved investigation "${id}" has an unknown schema; refusing to resume.`);+ }+ if (issues.some((issue) => issue.path[0] === "bundle" && issue.path[1] === "schema")) {+ return refuseInvestigation(+ `Saved investigation "${id}" holds a bundle from a different contract than ${BUNDLE_SCHEMA}; refusing to resume.`,+ );+ }+ return refuseInvestigation(+ `Saved investigation "${id}" does not match the ${BUNDLE_SCHEMA} schema (${issues.length} issue(s)); refusing to resume.`,+ );}+ // Return the validated value, not the raw parse: saveInvestigation persists+ // `parsed.data` for the same reason, so unknown keys smuggled into a+ // hand-edited file are dropped here rather than echoed back out by+ // `--resume --format json` or copied into the emitted diff.+ //+ // The assertion re-narrows the three report arrays the schema deliberately+ // leaves as open records (decisions/conflicts/intents, whose shapes belong to+ // the backend) plus the literals zod widens to `string`. Every field this file+ // dereferences has been checked by this point — unlike the `as` cast on raw+ // JSON.parse output that this replaces, which checked nothing.+ return parsed.data as unknown as SavedInvestigation;}function renderSavedInvestigation(id: string, format: string): void {diff --git a/ix-cli/src/cli/context-bundle-schema.ts b/ix-cli/src/cli/context-bundle-schema.tsindex ab54b03e..00fee85e 100644--- a/ix-cli/src/cli/context-bundle-schema.ts+++ b/ix-cli/src/cli/context-bundle-schema.ts@@ -1,21 +1,39 @@import { z } from "zod";+/**+ * Versioned id of the context bundle contract. Bump only on a breaking shape+ * change, never per run.+ */+export const BUNDLE_SCHEMA = "ix-context-bundle/1";++/** Versioned id of the saved-investigation envelope written by `--save`. */+export const INVESTIGATION_SCHEMA = "ix-investigation/1";+/*** Versioned contract for the deterministic context bundle produced by* `ix context` (schema `ix-context-bundle/1`).** This is the single source of truth for the bundle's shape. The MCP server* uses it as the `ix_context` output schema so agents get a structured- * contract, and the CLI validates every bundle with it before persisting it- * (investigation save and `--out`), so a malformed or unexpected backend- * payload can never be written to disk as if it were a valid bundle.+ * contract, and the CLI validates every bundle with it on the way to disk+ * (investigation save and `--out`) and on the way back off it+ * (`loadInvestigation`), so a malformed or unexpected payload can never be+ * written as if it were a valid bundle, nor honoured when read back.*- * Nested report objects (claims/decisions/conflicts/intents) keep their own- * internal shapes and are typed loosely here; the bundle's versioned `schema`- * field remains the authoritative marker.+ * The shapes below mirror the `ContextBundle` and `EvidenceItem` interfaces in+ * `commands/context.ts`. Fields the renderers and `--diff` dereference by name+ * — `evidence[].title`, the four `budgets`, the four `truncation` counters and+ * the `metadata` values `--diff` re-sends to the backend — are pinned to their+ * real types rather than left as open records: validation that accepts `{}`+ * where the code goes on to read `.title` or `.maxEntities` only moves the+ * failure downstream, from a named refusal to a TypeError or a NaN.+ *+ * The three backend report arrays (decisions/conflicts/intents) keep their own+ * internal shapes and stay deliberately loose here; the bundle's versioned+ * `schema` field remains the authoritative marker.*/export const contextBundleSchema = z.object({- schema: z.string(),+ schema: z.literal(BUNDLE_SCHEMA),generatedAt: z.string(),target: z.object({id: z.string(),@@ -27,14 +45,81 @@ export const contextBundleSchema = z.object({z.object({ id: z.string(), name: z.string(), kind: z.string(), path: z.string().optional(), stale: z.boolean() }),),relationships: z.array(z.object({ src: z.string(), dst: z.string(), predicate: z.string() })),- claims: z.array(z.record(z.string(), z.unknown())),+ claims: z.array(+ z+ .object({ id: z.string(), entityId: z.string(), statement: z.string(), status: z.string() })+ .catchall(z.unknown()),+ ),+ // DecisionReport/ConflictReport/IntentReport are the backend's own contracts+ // with their own shapes; they are forwarded, never dereferenced field-by-field+ // here, so they stay loose rather than duplicating those types in a second+ // place that could drift from them.decisions: z.array(z.record(z.string(), z.unknown())),conflicts: z.array(z.record(z.string(), z.unknown())),intents: z.array(z.record(z.string(), z.unknown())),- provenance: z.record(z.string(), z.unknown()),+ provenance: z+ .object({+ sourceUri: z.string().optional(),+ sourceHash: z.string().optional(),+ extractor: z.string().optional(),+ sourceType: z.string().optional(),+ observedAt: z.string().optional(),+ introducedRev: z.number().optional(),+ historyLength: z.number(),+ stale: z.boolean(),+ })+ .catchall(z.unknown()),freshness: z.object({ stale: z.boolean(), classification: z.string() }),- evidence: z.array(z.record(z.string(), z.unknown())),- budgets: z.record(z.string(), z.number()),- truncation: z.record(z.string(), z.number()),- metadata: z.record(z.string(), z.unknown()),+ evidence: z.array(+ z.object({+ id: z.string(),+ kind: z.string(),+ source: z.string(),+ title: z.string(),+ score: z.number(),+ reason: z.string(),+ refs: z.array(z.string()),+ }),+ ),+ budgets: z.object({+ maxEntities: z.number().int().positive(),+ maxRelationships: z.number().int().positive(),+ maxEvidence: z.number().int().positive(),+ maxChars: z.number().int().positive(),+ }),+ truncation: z.object({+ entitiesTruncated: z.number().int().nonnegative(),+ relationshipsTruncated: z.number().int().nonnegative(),+ evidenceTruncated: z.number().int().nonnegative(),+ charactersTruncated: z.number().int().nonnegative(),+ }),+ // `asOfRev` and `depth` are the two saved values `ix context --diff` re-sends+ // to the backend, so they are typed rather than accepted as anything.+ // Unknown keys pass through: metadata is the bundle's extension point, and+ // stripping them would silently drop data on the read-back path.+ metadata: z+ .object({+ asOfRev: z.number().optional(),+ depth: z.string().optional(),+ rankingRule: z.string(),+ })+ .catchall(z.unknown()),+});++/**+ * Contract for the on-disk saved-investigation envelope (`~/.ix/investigations`).+ *+ * `id` and `savedAt` are rendered to the terminal and copied into the emitted+ * `ix-investigation-diff/1` JSON, so they are validated here alongside the+ * bundle rather than trusted from a bare cast.+ */+export const savedInvestigationSchema = z.object({+ schema: z.literal(INVESTIGATION_SCHEMA),+ // `sanitizeId` percent-escapes anything outside this set on the way in, so a+ // stored id can only contain these characters. Pinning the same set on the+ // way out keeps control characters and ANSI escapes out of an id that+ // `renderNote`/`renderSection` write straight to the terminal.+ id: z.string().regex(/^[A-Za-z0-9._~-]+$/),+ savedAt: z.string(),+ bundle: contextBundleSchema,});