Skip to content

armgit / Ix

Public Imported from GitHub
0

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

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.ts
index 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.ts
index 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.ts
index 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, writeFileSync
import { 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.ts
index 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,
});