@canonical/pragma-cli 0.33.0 → 0.35.0

package/src/capabilities/graph/examples.exec.test.ts

@@ -0,0 +1,107 @@
+/**
+ * The documented examples, EXECUTED against the shipped pack (PROTECTED).
+ *
+ * The existing documentation suite validates example GRAMMAR — that a `cmd`
+ * parses as a command this CLI declares. Grammar is not truth: the previous
+ * `graph inspect ds:button` examples passed that check for as long as they
+ * existed while 404ing for every user who copied them, and the `graph query`
+ * ASK example passed while quietly answering `false`.
+ *
+ * So these run the examples as WRITTEN, against the embedded graph, and assert
+ * they answer. An example is a promise to a stranger; this is the only check
+ * that reads it as one.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { verbKey } from "../../kernel/packs/uniqueness.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { InspectResult } from "../../kernel/runtime/readEntity.js";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { TEST_FLAGS } from "../../testing/helpers/projectCli.js";
+import { graphModule } from "./index.js";
+
+const verb = (name: string): VerbSpec =>
+  graphModule.verbs.find((v) => verbKey(v.path) === name) as VerbSpec;
+
+/**
+ * The name of a verb's single positional, read from the verb rather than
+ * retyped — the point of this file is that documentation and code agree, so it
+ * should not itself hardcode a name that could drift.
+ */
+const positionalOf = (spec: VerbSpec): string =>
+  spec.params.find((p) => p.positional)?.name ?? "";
+
+/**
+ * The argument an example passes, recovered from the example's own `cmd`.
+ *
+ * Read from the declaration rather than retyped, so editing an example without
+ * editing this file cannot leave the test asserting the old one.
+ */
+function exampleArg(spec: VerbSpec, index: number): string {
+  const cmd = spec.examples?.[index]?.cmd ?? "";
+  const quoted = cmd.match(/"([^"]*)"/);
+  if (quoted?.[1]) return quoted[1];
+  return cmd.trim().split(/\s+/).slice(3).join(" ");
+}
+
+// ONE store for the file. Booting per case tripled this suite's cost against
+// the shipped pack for no extra coverage, and the whole package already flakes
+// under parallel contention — a test that need not add load should not.
+let rt: PragmaRuntime;
+beforeAll(() => {
+  rt = bootRuntime(TEST_FLAGS);
+});
+afterAll(async () => {
+  (await rt.store.get()).store.dispose();
+});
+
+describe("documented examples resolve against the shipped graph (PROTECTED)", () => {
+  it("runs every `graph inspect` example as written", async () => {
+    const inspect = verb("graph inspect");
+    expect(inspect.examples?.length).toBeGreaterThan(0);
+
+    for (const [index] of (inspect.examples ?? []).entries()) {
+      const uri = exampleArg(inspect, index);
+      const result = (await inspect.run(
+        { [positionalOf(inspect)]: uri },
+        rt,
+      )) as InspectResult;
+      // The prefixed and absolute forms are two spellings of one subject.
+      expect(
+        result.uri,
+        `example ${index} (${uri}) did not resolve to the documented entity`,
+      ).toBe("https://ds.canonical.com/global.component.button");
+      expect(result.groups.length).toBeGreaterThan(0);
+    }
+  });
+
+  it("runs the `graph query` ASK example and gets a true answer", async () => {
+    // The old example returned `false` — syntactically fine, semantically a lie
+    // about the graph. Asserting the ANSWER is what catches that.
+    const query = verb("graph query");
+    const ask = (query.examples ?? []).findIndex((e) => e.cmd.includes("ASK"));
+    expect(ask, "no ASK example to execute").toBeGreaterThanOrEqual(0);
+
+    const result = (await query.run(
+      { [positionalOf(query)]: exampleArg(query, ask) },
+      rt,
+    )) as { type: string; result?: boolean };
+
+    expect(result.type).toBe("ask");
+    expect(result.result, "the documented ASK example answers false").toBe(
+      true,
+    );
+  });
+
+  it("runs the `graph query` SELECT example and gets rows", async () => {
+    const query = verb("graph query");
+    const result = (await query.run(
+      { [positionalOf(query)]: exampleArg(query, 0) },
+      rt,
+    )) as { type: string; bindings?: unknown[] };
+
+    expect(result.type).toBe("select");
+    expect(result.bindings?.length ?? 0).toBeGreaterThan(0);
+  });
+});

package/src/capabilities/graph/index.ts

@@ -3,7 +3,7 @@
  * (the raw SPARQL escape hatch, PR6). The covenant blesses both.
  */
 
-import type { CapabilityModule } from "../../kernel/spec/types.js";
+import type { CapabilityModule } from "../../kernel/spec/index.js";
 import { resourceProvider } from "../resources/index.js";
 import { graphInspectVerb } from "./inspect.verb.js";
 import { graphQueryVerb } from "./query.verb.js";

package/src/capabilities/graph/inspect.render.ts

@@ -1,38 +1,86 @@
 /**
- * Formatters for `graph inspect` — predicate/object groups, prefix-compacted.
+ * Formatters for `graph inspect` — the entity's neighbourhood in three shapes.
+ *
+ * Terms arrive ALREADY compacted and named: the reader does it against the
+ * store's own merged prefix map, which is the map the graph was actually built
+ * with, so these formatters neither carry a prefix map nor re-derive one. They
+ * choose between the forms the reader supplies and nothing more.
  */
 
-import { compactUri } from "../../kernel/render/compactUri.js";
-import { DEFAULT_PREFIX_MAP } from "../../kernel/render/prefixes.js";
-import type { InspectResult } from "../../kernel/runtime/readEntity.js";
-import type { Formatters } from "../../kernel/spec/types.js";
+import { toTurtle } from "../../kernel/render/turtle.js";
+import type {
+  InboundGroup,
+  InspectResult,
+  ReadTerm,
+} from "../../kernel/runtime/readEntity.js";
+import type { Formatters } from "../../kernel/spec/index.js";
 
-const compact = (value: string): string =>
-  compactUri(value, DEFAULT_PREFIX_MAP);
+/** The short form of a term: prefixed when there is one, else the raw value. */
+const short = (term: ReadTerm): string => term.prefixed ?? term.value;
+
+/** A term as a reader should see it — short form, with its name when known. */
+const named = (term: ReadTerm): string =>
+  term.title ? `${short(term)} (${term.title})` : short(term);
+
+/**
+ * `predicate (330, sample of 5)` — the count is the truth, the list is not.
+ *
+ * A roster and a truncated relation read differently on purpose: "sample of"
+ * tells a reader that paging will not produce the rest and the noun's list verb
+ * is where the full set lives, where "showing" invites them to ask for more.
+ */
+function inboundHeading(group: InboundGroup): string {
+  if (group.sampled) {
+    return `${short(group.predicate)} (${group.count}, sample of ${group.subjects.length})`;
+  }
+  const suffix = group.truncated
+    ? `${group.count}, showing ${group.subjects.length}`
+    : `${group.count}`;
+  return `${short(group.predicate)} (${suffix})`;
+}
 
 export const inspectFormatters: Formatters<InspectResult> = {
   plain(data) {
     const title = data.label
-      ? `${compact(data.uri)} — ${data.label}`
-      : compact(data.uri);
+      ? `${short({ termType: "NamedNode", value: data.uri, ...(data.prefixed ? { prefixed: data.prefixed } : {}) })} — ${data.label}`
+      : (data.prefixed ?? data.uri);
     const lines = [title, "═".repeat(Math.max(title.length, 24)), ""];
     for (const group of data.groups) {
-      lines.push(`  ${compact(group.predicate)}:`);
-      for (const object of group.objects) lines.push(`    ${compact(object)}`);
+      lines.push(`  ${short(group.predicate)}:`);
+      for (const object of group.objects) lines.push(`    ${named(object)}`);
     }
-    return lines.join("\n").trimEnd();
-  },
-  llm(data) {
-    const lines = [
-      `## ${compact(data.uri)}${data.label ? ` — ${data.label}` : ""}`,
-      "",
-    ];
-    for (const group of data.groups) {
-      lines.push(
-        `- **${compact(group.predicate)}**: ${group.objects.map(compact).join(", ")}`,
-      );
+    for (const [via, rows] of Object.entries(data.nested)) {
+      lines.push("", `  ${via}:`);
+      for (const row of rows) {
+        // Values are TERMS; `String(term)` rendered every nested field as
+        // `[object Object]`, which made the whole plain-format record unreadable.
+        const fields = Object.entries(row)
+          .map(([key, value]) => `${key}=${named(value)}`)
+          .join("  ");
+        lines.push(`    ${fields}`);
+      }
+    }
+    if (data.inbound.length > 0) {
+      lines.push("", "  Referenced by:");
+      for (const group of data.inbound) {
+        lines.push(`    ${inboundHeading(group)}`);
+        for (const subject of group.subjects) {
+          lines.push(`      ${named(subject)}`);
+        }
+      }
     }
     return lines.join("\n").trimEnd();
   },
+  /**
+   * The agent-facing format IS Turtle — same bytes the `pragma:{+uri}` resource
+   * read serves, which is what keeps the mirror contract meaningful now that the
+   * two are no longer both JSON. Measured on one button: 15.8 KB of JSON against
+   * 4.5 KB of Turtle for the same neighbourhood.
+   *
+   * `prefixes` comes from the reader, not from this formatter: it compacted the
+   * terms against the store's own merged map, so re-deriving a map here could
+   * only disagree with the names already in the payload.
+   */
+  llm: (data) => toTurtle(data, data.prefixes),
   json: (data) => JSON.stringify(data, null, 2),
 };

package/src/capabilities/graph/inspect.test.ts

@@ -41,13 +41,185 @@ describe("graph inspect", () => {
       rt,
     )) as InspectResult;
     expect(result.uri).toBe(`${DS}button`);
+    expect(result.prefixed).toBe("ds:button");
     const rdfType = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type";
-    const typeGroup = result.groups.find((g) => g.predicate === rdfType);
-    expect(typeGroup?.objects).toContain(`${DS}Component`);
-    const summary = result.groups.find((g) => g.predicate === `${DS}summary`);
-    expect(summary?.objects[0]).toBe(
-      "Primary action trigger with optional icon and label.",
+    const typeGroup = result.groups.find((g) => g.predicate.value === rdfType);
+    // The object is a NamedNode, so it compacts and stays addressable.
+    expect(typeGroup?.objects[0]).toMatchObject({
+      termType: "NamedNode",
+      value: `${DS}Component`,
+      prefixed: "ds:Component",
+    });
+    const summary = result.groups.find(
+      (g) => g.predicate.value === `${DS}summary`,
     );
+    expect(summary?.objects[0]).toMatchObject({
+      termType: "Literal",
+      value: "Primary action trigger with optional icon and label.",
+    });
+  });
+
+  it("never compacts a literal, only a named node", async () => {
+    // The lossy string view could not tell these apart, so a literal whose text
+    // began with a namespace IRI was rewritten into something that read back as
+    // an IRI. Reading ke's term view is what closes that: `ds:figmaLink` here
+    // holds a STRING that starts with the `ds:` namespace.
+    const result = (await inspectVerb.run(
+      { uri: "ds:literalTrap" },
+      rt,
+    )) as InspectResult;
+    const trap = result.groups.find(
+      (g) => g.predicate.value === `${DS}figmaLink`,
+    );
+    expect(trap?.objects[0]?.termType).toBe("Literal");
+    expect(trap?.objects[0]?.value).toBe(`${DS}not-an-iri`);
+    expect(trap?.objects[0]?.prefixed).toBeUndefined();
+  });
+
+  it("carries inbound relations with a true count, capped by detail", async () => {
+    // `ds:button.icon` is the OBJECT of `ds:hasSubcomponent` — the relation
+    // lives on the other side of the arrow, so a subject-only read could never
+    // surface who holds this subcomponent.
+    const result = (await inspectVerb.run(
+      { uri: "ds:button.icon" },
+      rt,
+    )) as InspectResult;
+    const held = result.inbound.find(
+      (g) => g.predicate.value === `${DS}hasSubcomponent`,
+    );
+    expect(held?.count).toBeGreaterThan(0);
+    expect(held?.subjects[0]?.prefixed).toBe("ds:button");
+  });
+
+  it("inlines blank nodes as records rather than dead handles", async () => {
+    const result = (await inspectVerb.run(
+      { uri: "ds:blankHolder" },
+      rt,
+    )) as InspectResult;
+    // The blank object itself is marked unreachable...
+    const via = result.groups.find(
+      (g) => g.predicate.value === `${DS}changeLog`,
+    );
+    expect(via?.objects[0]).toMatchObject({
+      termType: "BlankNode",
+      addressable: false,
+    });
+    // ...and its content is served as records instead. Asserted as a SET: the
+    // order is content-derived (see the next case), never the input order.
+    // Record VALUES are terms, not strings: a record's members are as much part
+    // of the graph as the subject's own, and flattening them would reintroduce
+    // the IRI-versus-literal ambiguity the term projection exists to close.
+    const changes = result.nested["ds:changeLog"] ?? [];
+    expect(changes).toHaveLength(2);
+    expect(changes.map((row) => row["ds:changeType"]?.value).sort()).toEqual([
+      "decision",
+      "revision",
+    ]);
+    expect(changes[0]?.["ds:changeType"]?.termType).toBe("Literal");
+    // `rdf:type` is hoisted to `type` rather than repeated as a field, and stays
+    // a NamedNode — so the Turtle serializer can write it back as `a ds:X`.
+    expect(changes[0]?.type).toMatchObject({
+      termType: "NamedNode",
+      prefixed: "ds:ChangeLogEntry",
+    });
+  });
+
+  it("counts every inbound edge at summary while listing none", async () => {
+    // The cap is what keeps a hub read bounded — this graph's worst is 335
+    // inbound edges. `count` must stay the TRUE total at every level: a sample
+    // silently passing for the whole set is how "1 implementation" becomes a
+    // wrong answer. `ds:global` is the tier both fixture blocks point at.
+    const summary = await buildFixtureRuntime({
+      ttl: BLOCK_TTL,
+      prefixes: BLOCK_PREFIXES,
+      detail: "summary",
+    });
+    const result = (await inspectVerb.run(
+      { uri: "ds:global" },
+      summary.rt,
+    )) as InspectResult;
+    (await summary.rt.store.get()).store.dispose();
+
+    const tier = result.inbound.find((g) => g.predicate.value === `${DS}tier`);
+    expect(result.detail).toBe("summary");
+    expect(tier?.count).toBe(2);
+    expect(tier?.subjects).toEqual([]);
+    expect(tier?.truncated).toBe(true);
+    // Blank-node inlining is skipped at summary — it is the expensive half.
+    expect(result.nested).toEqual({});
+  });
+
+  it("samples a roster instead of listing it, keeping the count exact", async () => {
+    // A relation and a roster are not the same kind of edge. `ds:tier` here
+    // fans in 22 deep — past the threshold — so the read shows exemplars and
+    // says so, rather than paging a list verb's job through a resource read.
+    // Listing rosters cost a `detailed` read 19.5 KB on one class of the real
+    // graph and 20.9 KB on one tier.
+    const detailed = await buildFixtureRuntime({
+      ttl: BLOCK_TTL,
+      prefixes: BLOCK_PREFIXES,
+      detail: "detailed",
+    });
+    const result = (await inspectVerb.run(
+      { uri: "ds:rosterHub" },
+      detailed.rt,
+    )) as InspectResult;
+    (await detailed.rt.store.get()).store.dispose();
+
+    const roster = result.inbound.find(
+      (g) => g.predicate.value === `${DS}tier`,
+    );
+    expect(roster?.count).toBe(22);
+    expect(roster?.sampled).toBe(true);
+    expect(roster?.truncated).toBe(true);
+    // Exemplars, not a page — far fewer than the 22 a listed relation would show.
+    expect(roster?.subjects.length).toBeLessThan(10);
+    expect(roster?.subjects.length).toBeGreaterThan(0);
+  });
+
+  it("lists a narrow relation in full, unsampled", async () => {
+    // The counterpart: `ds:hasSubcomponent` fans in once, so every subject is
+    // part of the answer and none of this bounding applies.
+    const result = (await inspectVerb.run(
+      { uri: "ds:button.icon" },
+      rt,
+    )) as InspectResult;
+    const held = result.inbound.find(
+      (g) => g.predicate.value === `${DS}hasSubcomponent`,
+    );
+    expect(held?.sampled).toBeUndefined();
+    expect(held?.truncated).toBeUndefined();
+    expect(held?.subjects).toHaveLength(held?.count ?? 0);
+  });
+
+  it("resolves the level from config when no flag is given", async () => {
+    // A resource read carries no params, so config is the level it lands on.
+    const configured = await buildFixtureRuntime({
+      ttl: BLOCK_TTL,
+      prefixes: BLOCK_PREFIXES,
+      configDetail: "summary",
+      detailOrigin: "project",
+    });
+    const result = (await inspectVerb.run(
+      { uri: "ds:global" },
+      configured.rt,
+    )) as InspectResult;
+    (await configured.rt.store.get()).store.dispose();
+    expect(result.detail).toBe("summary");
+  });
+
+  it("orders nested records by content, not by blank-node label", async () => {
+    // Oxigraph re-mints blank-node labels on every load, so ordering by them
+    // made two reads of the same unchanged entity disagree.
+    const first = (await inspectVerb.run(
+      { uri: "ds:blankHolder" },
+      rt,
+    )) as InspectResult;
+    const second = (await inspectVerb.run(
+      { uri: "ds:blankHolder" },
+      rt,
+    )) as InspectResult;
+    expect(first.nested).toEqual(second.nested);
   });
 
   it("resolves an absolute IRI to the same result", async () => {
@@ -78,3 +250,86 @@ describe("graph inspect", () => {
     ).rejects.toMatchObject({ code: "INVALID_INPUT" });
   });
 });
+
+describe("bounds and losslessness the review surfaced", () => {
+  it("counts EVERY inbound predicate exactly, whatever the exemplar bound", async () => {
+    // One capped query answered counting and exhibiting at once, and answered
+    // neither: a single LIMIT applies to the whole ordered result, so the first
+    // predicate to fill it under-reported its own count AND every predicate
+    // after it vanished — while `count` promised the true total. The roster hub
+    // here fans in 22 deep, well past what any level exhibits.
+    const result = (await inspectVerb.run(
+      { uri: "ds:rosterHub" },
+      rt,
+    )) as InspectResult;
+    const roster = result.inbound.find(
+      (g) => g.predicate.value === `${DS}tier`,
+    );
+    expect(roster?.count).toBe(22);
+    // Counted in full, exhibited in part — the two are now separate questions.
+    expect(roster?.subjects.length).toBeLessThan(22);
+    // And the quiet neighbour survives the noisy one. Under the single capped
+    // query, a predicate ordered after one that filled the limit was dropped
+    // from the answer entirely.
+    const quiet = result.inbound.find(
+      (g) => g.predicate.value === `${DS}hasSubcomponent`,
+    );
+    expect(quiet?.count).toBe(1);
+    expect(quiet?.subjects[0]?.prefixed).toBe("ds:probe.quiet");
+  });
+
+  it("keeps a blank node reachable from two predicates under both", async () => {
+    // Keyed by node alone, whichever `via` arrived first won and the second
+    // edge disappeared — and Turtle filters the ordinary blank object out too,
+    // so nothing was left to notice the loss by.
+    const result = (await inspectVerb.run(
+      { uri: "ds:doubleLinked" },
+      rt,
+    )) as InspectResult;
+    expect(result.nested["ds:changeLog"]).toHaveLength(1);
+    expect(result.nested["ds:usageNote"]).toHaveLength(1);
+  });
+
+  it("says nothing about addressability at a level that exhibits none", async () => {
+    // At `summary` EVERY group is empty because the level shows no exemplars.
+    // Concluding "none individually addressable" there libels subjects that are
+    // perfectly nameable, so the group records what it WOULD have shown.
+    const summary = await buildFixtureRuntime({
+      ttl: BLOCK_TTL,
+      prefixes: BLOCK_PREFIXES,
+      detail: "summary",
+    });
+    const result = (await inspectVerb.run(
+      { uri: "ds:global" },
+      summary.rt,
+    )) as InspectResult;
+    (await summary.rt.store.get()).store.dispose();
+    const tier = result.inbound.find((g) => g.predicate.value === `${DS}tier`);
+    expect(tier?.exhibits).toBe(0);
+    expect(tier?.count).toBeGreaterThan(0);
+  });
+
+  it("carries the prefix map the payload was compacted against", async () => {
+    // A renderer that re-derives it from named nodes misses any prefix used
+    // only by the subject, a nested record key, or a literal datatype — and
+    // then emits compact names with no matching `@prefix`, i.e. invalid Turtle.
+    const result = (await inspectVerb.run(
+      { uri: "ds:button" },
+      rt,
+    )) as InspectResult;
+    expect(result.prefixes.ds).toBe(DS);
+  });
+
+  it("keeps an RDF 1.2 literal direction rather than flattening it", async () => {
+    const result = (await inspectVerb.run(
+      { uri: "ds:directional" },
+      rt,
+    )) as InspectResult;
+    const label = result.groups.find((g) => g.predicate.value === `${DS}name`);
+    expect(label?.objects[0]).toMatchObject({
+      termType: "Literal",
+      language: "ar",
+      direction: "rtl",
+    });
+  });
+});

package/src/capabilities/graph/inspect.verb.ts

@@ -8,18 +8,23 @@
  * name or absolute IRI addresses the subject exactly.
  */
 
+import {
+  BIN_NAME,
+  DEFAULT_DETAIL_LEVEL,
+  DETAIL_LEVELS,
+} from "../../constants.js";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
 import type { InspectResult } from "../../kernel/runtime/readEntity.js";
 import { readEntity } from "../../kernel/runtime/readEntity.js";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
-import type { VerbSpec } from "../../kernel/spec/types.js";
+import type { VerbSpec } from "../../kernel/spec/index.js";
 import { inspectFormatters } from "./inspect.render.js";
 
 const inspectVerb: VerbSpec<Record<string, unknown>, InspectResult> = {
   path: ["graph", "inspect"],
   summary:
     "Show every triple where a URI is the subject, grouped by predicate.",
-  doc: "Inspect one entity: all predicate/object pairs asserted on the subject. Address it by prefixed name (ds:button) or absolute IRI.",
+  doc: "Inspect one entity: all predicate/object pairs asserted on the subject. Address it by prefixed name (ds:global.component.button) or absolute IRI.",
   params: [
     {
       kind: "string",
@@ -31,9 +36,17 @@ const inspectVerb: VerbSpec<Record<string, unknown>, InspectResult> = {
     },
   ],
   output: { formatters: inspectFormatters },
+  // The read is BOUNDED by disclosure — inbound exemplars and literal previews
+  // both widen with the level — so the verb must declare the ladder it honours.
+  // Without this the CLI `--detail` flag has nothing to validate against and the
+  // MCP projector injects no `detail` argument at all, so the documented knob
+  // was one an agent could not actually reach.
+  disclosure: { levels: [...DETAIL_LEVELS], default: DEFAULT_DETAIL_LEVEL },
   examples: [
-    { cmd: "pragma graph inspect ds:button" },
-    { cmd: "pragma graph inspect https://ds.canonical.com/button" },
+    { cmd: `${BIN_NAME} graph inspect ds:global.component.button` },
+    {
+      cmd: `${BIN_NAME} graph inspect https://ds.canonical.com/global.component.button`,
+    },
   ],
   capability: {
     needsStore: true,

package/src/capabilities/graph/query.render.ts

@@ -9,7 +9,7 @@
  * - json: the serialized {@link QueryResult}.
  */
 
-import type { Formatters } from "../../kernel/spec/types.js";
+import type { Formatters } from "../../kernel/spec/index.js";
 
 // Inline `import("…")` type (no `from`) — keeps the ke types off the static
 // import graph the lazy-dispatch probe walks (see query.verb.ts).
@@ -36,9 +36,21 @@ function formatTriples(
 }
 
 export const queryFormatters: Formatters<QueryResult> = {
+  // Zero rows/triples: plain stdout stays empty — the notice is
+  // `emptyNotice`, routed to stderr (exit 0) by the dispatcher so a pipe
+  // reads no prose. ASK always has a result and never goes empty.
+  emptyNotice(result) {
+    if (result.type === "select" && result.bindings.length === 0) {
+      return "No results.";
+    }
+    if (result.type === "construct" && result.triples.length === 0) {
+      return "No triples.";
+    }
+    return undefined;
+  },
   plain(result) {
     if (result.type === "select") {
-      if (result.bindings.length === 0) return "No results.";
+      if (result.bindings.length === 0) return "";
       const cols = Object.keys(result.bindings[0] ?? {});
       const rows = result.bindings.map((b) =>
         cols.map((c) => b[c] ?? "").join("\t"),
@@ -48,7 +60,7 @@ export const queryFormatters: Formatters<QueryResult> = {
     if (result.type === "ask") {
       return `ASK: ${String(result.result)}`;
     }
-    return formatTriples(result.triples);
+    return result.triples.length === 0 ? "" : formatTriples(result.triples);
   },
 
   llm(result) {

package/src/capabilities/graph/query.verb.ts

@@ -9,9 +9,10 @@
  * query surfaces as INVALID_INPUT with a recovery pointer to `ontology list`.
  */
 
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import { BIN_NAME } from "../../constants.js";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
-import type { VerbSpec } from "../../kernel/spec/types.js";
+import type { VerbSpec } from "../../kernel/spec/index.js";
 import { queryFormatters } from "./query.render.js";
 
 // Inline `import("…")` type (no `from`) so the ke types stay OFF the static
@@ -35,11 +36,11 @@ const queryVerb: VerbSpec<Record<string, unknown>, QueryResult> = {
   output: { formatters: queryFormatters },
   examples: [
     {
-      cmd: 'pragma graph query "SELECT ?s WHERE { ?s a ds:Component }"',
+      cmd: `${BIN_NAME} graph query "SELECT ?s WHERE { ?s a ds:Component }"`,
       note: "list every component subject",
     },
     {
-      cmd: 'pragma graph query "ASK { ds:button a ds:Component }" --format json',
+      cmd: `${BIN_NAME} graph query "ASK { <https://ds.canonical.com/global.component.button> a ds:Component }" --format json`,
     },
   ],
   capability: {

package/src/capabilities/graph/runQuery.ts

@@ -10,8 +10,8 @@
  */
 
 import type { QueryResult } from "@canonical/ke";
-import { PragmaError } from "../../kernel/error/PragmaError.js";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import { cliRecovery, PragmaError } from "../../kernel/error/index.js";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
 
 /**
  * Execute a raw SPARQL query against the booted store.
@@ -39,11 +39,13 @@ export async function runQuery(
       message: detail
         ? `Invalid SPARQL query: ${detail}`
         : "Invalid SPARQL query.",
-      recovery: {
-        message: "Check your SPARQL syntax and the loaded namespaces.",
-        cli: "pragma ontology list",
-        mcp: { tool: "ontology_list" },
-      },
+      recovery: cliRecovery(
+        "ontology list",
+        "Check your SPARQL syntax and the loaded namespaces.",
+        {
+          tool: "ontology_list",
+        },
+      ),
     });
   }
 }