Skip to content

armgit / Ix

Public Imported from GitHub
0

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

perf(llm): carry eight characters of an id, not thirty-six (#690)

Ian Hock4a4c97e8315b
diff --git a/docs/llm-format.md b/docs/llm-format.md
index 6ad50863..3d0b0fb5 100644
--- a/docs/llm-format.md
+++ b/docs/llm-format.md
@@ -43,6 +43,15 @@ which value it ignored, on stderr, when a person is there to read it.
- **No decorative whitespace, separators, or headers.**
- **Omitted fields:** null, undefined, and empty values are dropped. Zeros and
other defaults are dropped where they carry no signal.
+- **Ids are eight characters.** Any field holding an opaque identifier — `id`,
+ `parent`, `src`, `dst`, `entity`, `claim_a`/`claim_b` — carries the first
+ eight characters of it, which is what `/v1/resolve-prefix` accepts, so the
+ short form can be passed straight back to the CLI. A 36-character UUID
+ tokenizes at roughly 1.8 characters per token, and on `ix map` the ids alone
+ outweigh the labels beside them. A reference is shortened on both sides, so
+ `parent=` still matches some other row's `id=`. `--format json` carries the
+ full id. Ids that are not opaque blobs — a slug like `root`, a prefixed id
+ like `c-8f31a2` — are left whole.
- **Quoting:** a value containing a space, `=`, `"`, `\`, or a control
character is wrapped in double quotes. Inside quotes, `"` and `\` are
backslash-escaped and newline / carriage-return / tab are encoded as `\n` /
diff --git a/ix-cli/src/cli/__tests__/llm-short-ids.test.ts b/ix-cli/src/cli/__tests__/llm-short-ids.test.ts
new file mode 100644
index 00000000..898532a7
--- /dev/null
+++ b/ix-cli/src/cli/__tests__/llm-short-ids.test.ts
@@ -0,0 +1,82 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+import { describe, expect, it } from "vitest";
+
+import { llmShortId } from "../llm.js";
+import { renderEdgeResultsLlm, renderNodesLlm, renderConflictsLlm, sliceEdgeResults } from "../format.js";
+import { renderEntityLlm } from "../commands/entity.js";
+import { renderSubsystemScoreLlm } from "../commands/subsystems.js";
+
+const UUID = "8ebf63f9-a75b-ccd0-d899-b02950ecb240";
+const UUID_2 = "21309739-2f48-31d9-bfcc-be8652fd95e6";
+
+/** A full v4-shaped id anywhere in a record is what this task exists to remove. */
+const FULL_UUID = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+
+describe("llmShortId", () => {
+ it("cuts an opaque id to a prefix the CLI still accepts", () => {
+ expect(llmShortId(UUID)).toBe("8ebf63f9");
+ expect(llmShortId("d41d8cd98f00b204e9800998ecf8427e")).toBe("d41d8cd9");
+ });
+
+ it("leaves anything that is not an opaque id alone", () => {
+ // Truncating these would corrupt a value rather than abbreviate one.
+ expect(llmShortId("c-8f31a2")).toBe("c-8f31a2");
+ expect(llmShortId("root")).toBe("root");
+ expect(llmShortId("ix-cli/src/cli/format.ts")).toBe("ix-cli/src/cli/format.ts");
+ });
+
+ it("drops nothing-values the way every other field does", () => {
+ expect(llmShortId(undefined)).toBeUndefined();
+ expect(llmShortId(null)).toBeUndefined();
+ expect(llmShortId("")).toBeUndefined();
+ });
+});
+
+describe("no renderer emits a full id", () => {
+ it("entity, with its edges", () => {
+ const lines = renderEntityLlm({
+ node: { id: UUID, kind: "function", name: "relativePath", createdRev: 2500 },
+ edges: [{ predicate: "CALLS", dst: UUID_2 }],
+ });
+ expect(lines.join("\n")).not.toMatch(FULL_UUID);
+ expect(lines[0]).toContain("id=8ebf63f9");
+ expect(lines[1]).toContain("dst=21309739");
+ });
+
+ it("nodes", () => {
+ expect(renderNodesLlm([{ id: UUID, kind: "class", name: "Foo" }]).join("\n")).not.toMatch(FULL_UUID);
+ });
+
+ it("edge results", () => {
+ const lines = renderEdgeResultsLlm(
+ // #688 made this take a Slice rather than a bare array.
+ sliceEdgeResults([{ id: UUID, name: "handleLogin", kind: "method", provenance: { source_uri: "src/a.ts" } }], 10),
+ "callers", "verify_token", "graph",
+ );
+ expect(lines.join("\n")).not.toMatch(FULL_UUID);
+ });
+
+ it("conflicts, which name two claims and nothing else", () => {
+ const lines = renderConflictsLlm([{ reason: "r", recommendation: "x", claimA: UUID, claimB: UUID_2 }]);
+ expect(lines.join("\n")).not.toMatch(FULL_UUID);
+ });
+
+ it("subsystem regions", () => {
+ const line = renderSubsystemScoreLlm({
+ region_id: UUID, name: "CLI", label_kind: "module", level: 1, file_count: 107,
+ health_score: 0.5, chunk_density: 0, smell_files: 0, confidence: 0.7,
+ } as never);
+ expect(line).not.toMatch(FULL_UUID);
+ expect(line).toContain("id=8ebf63f9");
+ });
+});
+
+describe("a shortened reference still resolves inside the same output", () => {
+ it("keeps an id and a reference to it in step", () => {
+ // `parent=` on one region has to match `id=` on another, so both sides go
+ // through the same shortener or the tree stops being re-buildable.
+ expect(llmShortId(UUID_2)).toBe(llmShortId(UUID_2.toLowerCase()));
+ expect(llmShortId(UUID_2)).toBe("21309739");
+ });
+});
diff --git a/ix-cli/src/cli/__tests__/llm-tier4.test.ts b/ix-cli/src/cli/__tests__/llm-tier4.test.ts
index 36297c0c..2af7310d 100644
--- a/ix-cli/src/cli/__tests__/llm-tier4.test.ts
+++ b/ix-cli/src/cli/__tests__/llm-tier4.test.ts
@@ -12,7 +12,9 @@ describe("renderEntityLlm", () => {
claims: [],
edges: [{ predicate: "CONTAINS", dst: "deadbeef00000000" }],
});
- expect(lines[0]).toBe("entity id=abcdef1234567890 kind=class name=Foo path=src/a.ts rev=3 edges=1");
+ // The id is shortened on the header too now — it was the one record that
+ // still carried a full one (C-11).
+ expect(lines[0]).toBe("entity id=abcdef12 kind=class name=Foo path=src/a.ts rev=3 edges=1");
expect(lines[1]).toBe("edge pred=CONTAINS dst=deadbeef");
});
});
diff --git a/ix-cli/src/cli/commands/context.ts b/ix-cli/src/cli/commands/context.ts
index dc3c6e99..d81187ef 100644
--- a/ix-cli/src/cli/commands/context.ts
+++ b/ix-cli/src/cli/commands/context.ts
@@ -20,7 +20,7 @@ import type {
} from "../../client/types.js";
import { getEndpoint } from "../config.js";
import { collectFacts, type ContextFacts, type EntityLocation } from "../explain/facts.js";
-import { llmLine, printLlmLines } from "../llm.js";
+import { llmLine, llmShortId, printLlmLines } from "../llm.js";
import { parseBudgetOption, parsePickOption, parseRevisionOption } from "../options.js";
import { resolveFileOrReport } from "../resolve.js";
import { createStaleProbe, hasCompletedSourceGraphBaseline } from "../stale.js";
@@ -1256,7 +1256,8 @@ function entityRecord(change: RecordChange) {
change,
// Relationship records name their endpoints by entity id, so this is
// what lets a reader resolve `src=`/`dst=` to something it has seen.
- id: e.id,
+ // Shortened on both sides of that reference, so it still resolves.
+ id: llmShortId(e.id),
kind: e.kind,
name: e.name,
path: e.path,
@@ -1282,8 +1283,8 @@ function claimRecord(change: RecordChange) {
return (c: ContextBundle["claims"][number]): string =>
llmLine("claim", {
change,
- id: c.id,
- entity: c.entityId,
+ id: llmShortId(c.id),
+ entity: llmShortId(c.entityId),
status: c.status,
statement: c.statement,
});
@@ -1369,8 +1370,8 @@ export function renderInvestigationDiff(
// than the format it is meant to replace is the wrong trade.
...diff.added.entities.map(entityRecord("added")),
...diff.removed.entities.map(entityRecord("removed")),
- ...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.relationships.map((r) => llmLine("relationship", { change: "added", src: llmShortId(r.src), pred: r.predicate, dst: llmShortId(r.dst) })),
+ ...diff.removed.relationships.map((r) => llmLine("relationship", { change: "removed", src: llmShortId(r.src), pred: r.predicate, dst: llmShortId(r.dst) })),
...diff.added.evidence.map(evidenceRecord("added")),
...diff.removed.evidence.map(evidenceRecord("removed")),
// `statement=` is the field that says what changed. The id is the
diff --git a/ix-cli/src/cli/commands/depends.ts b/ix-cli/src/cli/commands/depends.ts
index f5505b1a..114ae1eb 100644
--- a/ix-cli/src/cli/commands/depends.ts
+++ b/ix-cli/src/cli/commands/depends.ts
@@ -6,7 +6,7 @@ import { IxClient } from "../../client/api.js";
import { getEndpoint } from "../config.js";
import { resolveFileOrReport, printResolved, isRawId } from "../resolve.js";
import { compactTreeNode, relativePath } from "../format.js";
-import { llmLine } from "../llm.js";
+import { llmLine, llmShortId } from "../llm.js";
import { parsePickOption } from "../options.js";
// ── Tree types ──────────────────────────────────────────────────────
@@ -173,7 +173,7 @@ export function renderDependsLlm(
lines.push(llmLine("dep", [
["name", node.resolved ? node.name : undefined],
["kind", node.kind],
- ["id", node.id?.slice(0, 8)],
+ ["id", llmShortId(node.id)],
["parent", parentId?.slice(0, 8)],
["rel", node.relation],
["path", relativePath(node.path)],
diff --git a/ix-cli/src/cli/commands/entity.ts b/ix-cli/src/cli/commands/entity.ts
index 4db308e0..8cbc768f 100644
--- a/ix-cli/src/cli/commands/entity.ts
+++ b/ix-cli/src/cli/commands/entity.ts
@@ -5,7 +5,7 @@ import chalk from "chalk";
import { IxClient } from "../../client/api.js";
import { getEndpoint } from "../config.js";
import { lineSpan, relativePath, rowLocation, stripNulls } from "../format.js";
-import { llmLine } from "../llm.js";
+import { llmLine, llmShortId } from "../llm.js";
/** Render entity details as llm records: a header line then one `edge` row per edge. */
export function renderEntityLlm(result: any): string[] {
@@ -13,7 +13,7 @@ export function renderEntityLlm(result: any): string[] {
const loc = rowLocation(node);
const edges = result.edges ?? [];
const lines = [llmLine("entity", [
- ["id", node.id],
+ ["id", llmShortId(node.id)],
["kind", node.kind],
["name", node.name || node.attrs?.name],
["path", loc.path],
@@ -27,7 +27,7 @@ export function renderEntityLlm(result: any): string[] {
for (const e of edges) {
lines.push(llmLine("edge", [
["pred", e.predicate],
- ["dst", typeof e.dst === "string" ? e.dst.slice(0, 8) : e.dst],
+ ["dst", llmShortId(e.dst)],
]));
}
return lines;
diff --git a/ix-cli/src/cli/commands/locate.ts b/ix-cli/src/cli/commands/locate.ts
index 4af448c1..4dfc83e7 100644
--- a/ix-cli/src/cli/commands/locate.ts
+++ b/ix-cli/src/cli/commands/locate.ts
@@ -10,7 +10,7 @@ import {
import { isFileStale } from "../stale.js";
import { stderr } from "../stderr.js";
import { relativePath } from "../format.js";
-import { llmLine, llmError } from "../llm.js";
+import { llmLine, llmError, llmShortId } from "../llm.js";
import { parsePickOption } from "../options.js";
import { getEffectiveSystemPath, hasMapData } from "../hierarchy.js";
import { humanizeLabel } from "../impact/risk-semantics.js";
@@ -257,7 +257,7 @@ export function renderLocateLlm(output: LocateOutput, symbol: string): string[]
const lines = [llmLine("locate", [
["target", t.name],
["kind", t.kind],
- ["id", typeof t.id === "string" ? t.id.slice(0, 8) : undefined],
+ ["id", llmShortId(t.id)],
["path", t.path],
["line_start", output.lineRange?.start],
["line_end", output.lineRange?.end],
diff --git a/ix-cli/src/cli/commands/map.ts b/ix-cli/src/cli/commands/map.ts
index efc0ebcd..128bfcc7 100644
--- a/ix-cli/src/cli/commands/map.ts
+++ b/ix-cli/src/cli/commands/map.ts
@@ -5,7 +5,7 @@ import chalk from "chalk";
import { IxClient } from "../../client/api.js";
import { clearMapBaseline, getEndpoint } from "../config.js";
import { roundFloat } from "../format.js";
-import { llmLine, llmError } from "../llm.js";
+import { llmLine, llmError, llmShortId } from "../llm.js";
import { bootstrap, resolveWorkspaceId } from "../bootstrap.js";
import { formatFetchError } from "../errors.js";
import { ingestFiles, type IngestFilesSummary } from "./ingest.js";
@@ -687,12 +687,12 @@ export function renderMapLlm(
]));
for (const r of regions) {
console.log(llmLine("region", [
- ["id", r.id],
+ ["id", llmShortId(r.id)],
["kind", r.label_kind],
["label", r.label],
["level", r.level],
["files", r.file_count],
- ["parent", r.parent_id],
+ ["parent", llmShortId(r.parent_id)],
["children", r.child_region_count > 0 ? r.child_region_count : undefined],
["cohesion", roundFloat(r.cohesion)],
["coupling", roundFloat(r.external_coupling)],
diff --git a/ix-cli/src/cli/commands/read.ts b/ix-cli/src/cli/commands/read.ts
index 66df9571..8c5b3aef 100644
--- a/ix-cli/src/cli/commands/read.ts
+++ b/ix-cli/src/cli/commands/read.ts
@@ -10,7 +10,7 @@ import { resolveEntityFull, activeReadScope, ensureReadScope } from "../resolve.
import { stderr } from "../stderr.js";
import { isFileStale } from "../stale.js";
import { relativePath } from "../format.js";
-import { llmError, llmLine, printLlmLines } from "../llm.js";
+import { llmError, llmLine, llmShortId, printLlmLines } from "../llm.js";
import { parsePickOption } from "../options.js";
import { reportUnresolvedTarget } from "../ui.js";
@@ -132,7 +132,7 @@ export function renderReadAmbiguityLlm(result: AmbiguityResult, target: string):
["name", c.name],
["kind", c.kind],
["path", c.path ? relativePath(c.path) ?? c.path : undefined],
- ["id", c.id],
+ ["id", llmShortId(c.id)],
]));
});
lines.push(llmLine("hint", [[
diff --git a/ix-cli/src/cli/commands/search.ts b/ix-cli/src/cli/commands/search.ts
index c4076856..f194659e 100644
--- a/ix-cli/src/cli/commands/search.ts
+++ b/ix-cli/src/cli/commands/search.ts
@@ -9,7 +9,7 @@ import { formatNodes, relativePath } from "../format.js";
import { scoreCandidate, resolveReadSystemId } from "../resolve.js";
import { applyRoleFilter, roleHint } from "../role-filter.js";
import { stderr } from "../stderr.js";
-import { llmLine } from "../llm.js";
+import { llmLine, llmShortId } from "../llm.js";
import { normalizePathSeparators } from "../path-match.js";
/** Render `ix search` as llm records: a header line then one `node` row per hit (rank = order). */
@@ -20,7 +20,7 @@ export function renderSearchLlm(
const lines = [llmLine("search", [["count", results.length], ["candidates", totalCandidates]])];
for (const r of results) {
lines.push(llmLine("node", [
- ["name", r.name], ["kind", r.kind], ["id", r.id?.slice(0, 8)],
+ ["name", r.name], ["kind", r.kind], ["id", llmShortId(r.id)],
["path", r.path], ["score", r.score],
]));
}
diff --git a/ix-cli/src/cli/commands/subsystems.ts b/ix-cli/src/cli/commands/subsystems.ts
index 75d2a61d..3631c3c4 100644
--- a/ix-cli/src/cli/commands/subsystems.ts
+++ b/ix-cli/src/cli/commands/subsystems.ts
@@ -7,7 +7,7 @@ import { getEndpoint } from "../config.js";
import { resolveWorkspaceId } from "../bootstrap.js";
import { resolveReadSystemId } from "../resolve.js";
import { roundFloat } from "../format.js";
-import { llmLine, llmError } from "../llm.js";
+import { llmLine, llmError, llmShortId } from "../llm.js";
import { parsePickOption } from "../options.js";
import { renderMapText, renderMapLlm, type MapRegion, type MapResult } from "./map.js";
import {
@@ -313,7 +313,7 @@ Examples:
export function renderSubsystemScoreLlm(s: SubsystemScore): string {
// chunk_density is dropped when 0 (uncomputed / no signal); see docs/llm-format.md.
return llmLine("region", [
- ["id", s.region_id],
+ ["id", llmShortId(s.region_id)],
["label", s.name],
["kind", s.label_kind],
["level", s.level],
@@ -329,14 +329,14 @@ export function renderScopedSubsystemLlm(result: ScopedSubsystemResult): string[
const t = result.target;
const lines = [
llmLine("target", [
- ["id", t.id],
+ ["id", llmShortId(t.id)],
["label", t.label],
["kind", t.label_kind],
["level", t.level],
["files", t.file_count],
["confidence", roundFloat(t.confidence)],
["cross_cutting", t.is_cross_cutting ? true : undefined],
- ["parent", result.parent?.id],
+ ["parent", llmShortId(result.parent?.id)],
["signals", t.dominant_signals.length > 0 ? t.dominant_signals.join(",") : undefined],
]),
llmLine("health", [
@@ -348,12 +348,12 @@ export function renderScopedSubsystemLlm(result: ScopedSubsystemResult): string[
];
const emit = (region: ScopedSubsystemRegion): void => {
lines.push(llmLine("region", [
- ["id", region.id],
+ ["id", llmShortId(region.id)],
["label", region.label],
["kind", region.label_kind],
["level", region.level],
["files", region.file_count],
- ["parent", region.parent_id],
+ ["parent", llmShortId(region.parent_id)],
["confidence", roundFloat(region.confidence)],
["cross_cutting", region.is_cross_cutting ? true : undefined],
["signals", region.dominant_signals.length > 0 ? region.dominant_signals.join(",") : undefined],
diff --git a/ix-cli/src/cli/commands/trace.ts b/ix-cli/src/cli/commands/trace.ts
index bd6ab740..eaf44f1a 100644
--- a/ix-cli/src/cli/commands/trace.ts
+++ b/ix-cli/src/cli/commands/trace.ts
@@ -15,7 +15,7 @@ import {
reportUnresolvedTarget,
} from "../ui.js";
import { compactTreeNode, relativePath } from "../format.js";
-import { llmLine, type LlmValue } from "../llm.js";
+import { llmLine, llmShortId, type LlmValue } from "../llm.js";
import { parsePickOption } from "../options.js";
// ── Types ────────────────────────────────────────────────────────────
@@ -344,7 +344,7 @@ function traceNodesLlm(record: string, tree: TraceNode[], rootId: string): strin
lines.push(llmLine(record, [
["name", node.resolved ? node.name : undefined],
["kind", node.kind],
- ["id", node.id?.slice(0, 8)],
+ ["id", llmShortId(node.id)],
["parent", parentId?.slice(0, 8)],
["path", relativePath(node.path)],
["cycle", node.cycle ? true : undefined],
diff --git a/ix-cli/src/cli/explain/llm.ts b/ix-cli/src/cli/explain/llm.ts
index 7ec132e3..3034688b 100644
--- a/ix-cli/src/cli/explain/llm.ts
+++ b/ix-cli/src/cli/explain/llm.ts
@@ -1,6 +1,6 @@
// Copyright 2026 Ix Infrastructure Inc.
-import { llmLine } from "../llm.js";
+import { llmLine, llmShortId } from "../llm.js";
import { relativePath } from "../format.js";
import type { EntityFacts, EntityLocation } from "./facts.js";
import type { RoleInference } from "./role-inference.js";
@@ -43,7 +43,7 @@ export function renderExplainLlm(
const lines: string[] = [];
lines.push(llmLine("entity", [
- ["id", facts.id],
+ ["id", llmShortId(facts.id)],
["name", facts.name],
["kind", facts.kind],
["path", facts.path],
@@ -171,7 +171,7 @@ export function renderExplainRawLlm(result: {
const lines: string[] = [];
lines.push(llmLine("entity", [
- ["id", result.id],
+ ["id", llmShortId(result.id)],
["name", result.name],
["kind", result.kind],
["path", result.file],
diff --git a/ix-cli/src/cli/format.ts b/ix-cli/src/cli/format.ts
index 4367d0fb..cbabc073 100644
--- a/ix-cli/src/cli/format.ts
+++ b/ix-cli/src/cli/format.ts
@@ -1,7 +1,7 @@
// Copyright 2026 Ix Infrastructure Inc.
import chalk from "chalk";
-import { llmLine } from "./llm.js";
+import { llmLine, llmShortId } from "./llm.js";
export type ResultSource = "graph" | "text" | "graph+text" | "heuristic";
@@ -247,7 +247,7 @@ export function renderNodesLlm(nodes: any[]): string[] {
const loc = rowLocation(n);
return llmLine("node", [
["kind", n.kind],
- ["id", typeof n.id === "string" ? n.id.slice(0, 8) : undefined],
+ ["id", llmShortId(n.id)],
["name", n.name || n.attrs?.name || n.attrs?.title || "(unnamed)"],
["path", loc.path],
["lines", lineSpan(loc)],
@@ -645,10 +645,10 @@ export function renderEdgeResultsLlm(
for (const ref of refs) {
lines.push(ref.resolved
? llmLine("ref", [
- ["name", ref.name], ["kind", ref.kind], ["id", ref.id?.slice(0, 8)],
+ ["name", ref.name], ["kind", ref.kind], ["id", llmShortId(ref.id)],
["path", ref.path], ["lines", lineSpan(ref)],
])
- : llmLine("ref", [["kind", ref.kind], ["id", ref.id?.slice(0, 8)], ["resolved", false]]));
+ : llmLine("ref", [["kind", ref.kind], ["id", llmShortId(ref.id)], ["resolved", false]]));
}
return lines;
}
@@ -761,8 +761,8 @@ export function renderConflictsLlm(conflicts: any[]): string[] {
lines.push(llmLine("conflict", [
["reason", c.reason],
["recommendation", c.recommendation],
- ["claim_a", c.claimA],
- ["claim_b", c.claimB],
+ ["claim_a", llmShortId(c.claimA)],
+ ["claim_b", llmShortId(c.claimB)],
]));
}
return lines;
diff --git a/ix-cli/src/cli/llm.ts b/ix-cli/src/cli/llm.ts
index a1e62fed..de3fb69b 100644
--- a/ix-cli/src/cli/llm.ts
+++ b/ix-cli/src/cli/llm.ts
@@ -48,6 +48,49 @@ export function llmQuote(raw: string): string {
return `"${escaped}"`;
}
+/**
+ * The id prefix records carry.
+ *
+ * Eight hex characters, which is what `/v1/resolve-prefix` already accepts
+ * everywhere the CLI takes an id, so the short form is not a display-only
+ * abbreviation — it is a value the caller can pass straight back. A full v4
+ * UUID is 36 characters and tokenizes at roughly 1.8 characters per token, so
+ * on `ix map` (30 regions, each with its own id and its parent's) the ids alone
+ * outweigh the labels they are attached to.
+ *
+ * Only ids that *are* opaque blobs are shortened. Region ids are UUIDs here but
+ * claim ids look like `c-8f31a2` and region ids can be slugs (`root`,
+ * `cli-commands`); truncating those would corrupt a value rather than
+ * abbreviate it.
+ */
+const SHORT_ID_LENGTH = 8;
+const HEX_ONLY = /^[0-9a-f]+$/i;
+const MIN_OPAQUE_LENGTH = 16;
+
+/**
+ * Hex, ignoring dashes, and long enough that no part of it is a word.
+ *
+ * Both halves matter. Hex-only rules out a slug (`root`, `cli-commands`) and a
+ * prefixed id (`c-8f31a2`), and the length floor rules out a short hex-looking
+ * word — `cafe`, `decade` — that happens to be a label. Anything that passes is
+ * an opaque identifier whose first eight characters carry the same meaning as
+ * all of them.
+ *
+ * Idempotent: an already-shortened `8ebf63f9` is seven characters of hex short
+ * of the floor and comes back unchanged.
+ */
+function isOpaqueId(raw: string): boolean {
+ const hex = raw.replace(/-/g, "");
+ return hex.length >= MIN_OPAQUE_LENGTH && HEX_ONLY.test(hex);
+}
+
+export function llmShortId(value: LlmValue): string | undefined {
+ if (value === null || value === undefined) return undefined;
+ const raw = String(value);
+ if (raw === "") return undefined;
+ return isOpaqueId(raw) ? raw.slice(0, SHORT_ID_LENGTH) : raw;
+}
+
/** Render a single `key=value` token, or null if the value is omitted. */
export function llmField(key: string, value: LlmValue): string | null {
if (value === null || value === undefined) return null;