Skip to content

armgit / Ix

Public Imported from GitHub
0

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

docs: one slug for an unresolved target, and document the status booleans (#538)

KageBinary07bf4a7252a8
diff --git a/docs/llm-format.md b/docs/llm-format.md
index 00c3fd75..68ed1501 100644
--- a/docs/llm-format.md
+++ b/docs/llm-format.md
@@ -25,7 +25,11 @@ so consumers can pass the flag unconditionally without a per-command lookup.
backslash-escaped and newline / carriage-return / tab are encoded as `\n` /
`\r` / `\t`, so a record never spans more than one line.
- **Errors:** a uniform `error code=<slug> message="..."` line in the same
- format as data lines; the process still exits non-zero.
+ format as data lines; the process still exits non-zero. A target that does
+ not exist is always `unresolved_target`, whichever command was asked —
+ `context`, `explain`, `read`, `locate`, `subsystems`, `trace`. (The backend
+ spells the same condition `unknown_target` in its own JSON bodies; that is a
+ wire detail and is translated on the way out, so a consumer never sees both.)
## Hierarchies
@@ -170,7 +174,7 @@ when that was.
Error line:
```
-error code=unknown_target message="No entity named 'IngestionService' found" suggestions=Ingestion,Service
+error code=unresolved_target message="No entity named 'IngestionService' found" suggestions=Ingestion,Service
```
## Status
@@ -197,9 +201,21 @@ Two deliberate exceptions remain:
one-record-per-line invariant is relaxed, and the count is what lets a
consumer relax it safely.
- **`status` is not smaller** — it is within a byte or two of `json`, because
- the payload is a handful of scalars either way. It is in Tier 5 for the
- explicit `stale=true|false` field, which is the question the command gets
- called to answer and which `text` only implied through a warning line.
+ the payload is a handful of scalars either way. It is in Tier 5 for its
+ explicit boolean fields, which are the questions the command gets called to
+ answer and which `text` only implied through warning lines:
+
+ ```
+ status backend=ok endpoint=http://localhost:8090 graph_complete=true map_complete=false rev=2467 last_ingest_at=2026-08-29T01:38:43.341Z stale_files=0 stale=false
+ ```
+
+ `graph_complete` and `map_complete` are two different questions and a
+ workspace can sit at `true`/`false`. The source graph is ingested and current
+ — search, `read`, `context` and `explain` all answer from it — while no
+ architecture hierarchy has been recorded for that revision, so `map`,
+ `subsystems` and region-scoped views may be empty or stale. `stale` follows
+ `graph_complete`, not `map_complete`: it is a claim about files having
+ changed, and a missing hierarchy does not make a file out of date.
Still routing to `text`: `diff --content` (verbatim hunks) and `ingest`, a
hidden implementation-detail command whose output is a completion summary.
diff --git a/ix-cli/src/cli/__tests__/llm-renderers.test.ts b/ix-cli/src/cli/__tests__/llm-renderers.test.ts
index 46a4d957..01cd6968 100644
--- a/ix-cli/src/cli/__tests__/llm-renderers.test.ts
+++ b/ix-cli/src/cli/__tests__/llm-renderers.test.ts
@@ -114,9 +114,9 @@ describe("renderSubsystemErrorLlm", () => {
const line = renderSubsystemErrorLlm({ error: "ambiguous_target", target_query: "Auth", candidates: [{ pick: 1, label: "Auth", level: 2, label_kind: "subsystem", file_count: 4 }, { pick: 2, label: "AuthZ", level: 2, label_kind: "subsystem", file_count: 2 }] });
expect(line).toBe('error code=ambiguous_target message="Multiple regions matched \\"Auth\\"." candidates=1:Auth,2:AuthZ');
});
- it("renders unknown_target with suggestions", () => {
+ it("renders the backend's unknown_target body as an unresolved_target record", () => {
const line = renderSubsystemErrorLlm({ error: "unknown_target", target_query: "Foo", message: "No region named Foo.", suggestions: ["Bar", "Baz"] });
- expect(line).toBe('error code=unknown_target message="No region named Foo." suggestions=Bar,Baz');
+ expect(line).toBe('error code=unresolved_target message="No region named Foo." suggestions=Bar,Baz');
});
});
diff --git a/ix-cli/src/cli/__tests__/llm-tier4.test.ts b/ix-cli/src/cli/__tests__/llm-tier4.test.ts
index 0fc9c9e8..5a70ffdb 100644
--- a/ix-cli/src/cli/__tests__/llm-tier4.test.ts
+++ b/ix-cli/src/cli/__tests__/llm-tier4.test.ts
@@ -56,6 +56,6 @@ describe("renderLocateLlm", () => {
it("emits a structured error when nothing resolves", () => {
const lines = renderLocateLlm({ resolvedTarget: null, resolutionMode: "none", systemPath: null, diagnostics: ["No graph entity found."] } as any, "foo");
- expect(lines).toEqual(['error code=unknown_target message="No graph entity found for \\"foo\\"."']);
+ expect(lines).toEqual(['error code=unresolved_target message="No graph entity found for \\"foo\\"."']);
});
});
diff --git a/ix-cli/src/cli/__tests__/llm.test.ts b/ix-cli/src/cli/__tests__/llm.test.ts
index 24e6e5f7..213ebced 100644
--- a/ix-cli/src/cli/__tests__/llm.test.ts
+++ b/ix-cli/src/cli/__tests__/llm.test.ts
@@ -78,11 +78,11 @@ describe("llmLine", () => {
describe("llmError", () => {
it("renders a uniform error record", () => {
- const line = llmError("unknown_target", "No entity named 'Foo' found", [
+ const line = llmError("unresolved_target", "No entity named 'Foo' found", [
["suggestions", "Bar,Baz"],
]);
expect(line).toBe(
- 'error code=unknown_target message="No entity named \'Foo\' found" suggestions=Bar,Baz'
+ 'error code=unresolved_target message="No entity named \'Foo\' found" suggestions=Bar,Baz'
);
});
});
diff --git a/ix-cli/src/cli/__tests__/mcp.test.ts b/ix-cli/src/cli/__tests__/mcp.test.ts
index 49bd0e79..daf853c2 100644
--- a/ix-cli/src/cli/__tests__/mcp.test.ts
+++ b/ix-cli/src/cli/__tests__/mcp.test.ts
@@ -113,7 +113,7 @@ describe("ix mcp", () => {
});
it("marks a structured LLM error as an MCP error when the CLI exits successfully", async () => {
- const error = 'error code=unknown_target message="No graph entity found for \\"Missing\\"."';
+ const error = 'error code=unresolved_target message="No graph entity found for \\"Missing\\"."';
const client = await connect(async () => ({
ok: true,
stdout: error,
diff --git a/ix-cli/src/cli/commands/locate.ts b/ix-cli/src/cli/commands/locate.ts
index ac22163b..a4975e28 100644
--- a/ix-cli/src/cli/commands/locate.ts
+++ b/ix-cli/src/cli/commands/locate.ts
@@ -219,7 +219,7 @@ function humanizeBreadcrumb(nodes: Array<{ name: string; kind: string }>): strin
export function renderLocateLlm(output: LocateOutput, symbol: string): string[] {
const t = output.resolvedTarget;
if (!t) {
- return [llmError("unknown_target", `No graph entity found for "${symbol}".`)];
+ return [llmError("unresolved_target", `No graph entity found for "${symbol}".`)];
}
const lines = [llmLine("locate", [
["target", t.name],
diff --git a/ix-cli/src/cli/commands/subsystems.ts b/ix-cli/src/cli/commands/subsystems.ts
index fa79ac75..d8d2eb7b 100644
--- a/ix-cli/src/cli/commands/subsystems.ts
+++ b/ix-cli/src/cli/commands/subsystems.ts
@@ -30,6 +30,14 @@ interface AmbiguousSubsystemResult {
}>;
}
+/**
+ * The backend's own error body for a region name it could not resolve — see
+ * `SubsystemRoutes.scala`. `unknown_target` is its spelling and stays as it is
+ * here: this type and the guard below describe a wire response, not anything
+ * this CLI chose. What we emit for it is `unresolved_target`, the one slug
+ * every command uses for "that target does not exist", so an agent routing on
+ * the code has one branch rather than two.
+ */
interface UnknownSubsystemTargetResult {
error: "unknown_target";
target_query: string;
@@ -361,7 +369,7 @@ export function renderSubsystemErrorLlm(body: unknown): string {
]);
}
if (isUnknownSubsystemTargetResult(body)) {
- return llmError("unknown_target", body.message, [
+ return llmError("unresolved_target", body.message, [
["suggestions", (body.suggestions ?? []).join(",") || undefined],
]);
}