@canonical/pragma-cli 0.34.0 → 0.36.0

package/src/capabilities/doctor/types.ts

@@ -2,15 +2,17 @@
  * Data shapes for `pragma doctor` (ported verbatim from the old shell).
  */
 
-/**
- * One of the two config bands a check can concern. Mirrors the harnesses
- * `ScopeBand` structurally but is redeclared here so this statically-reachable
- * type module never pulls the harnesses runtime into the fast-path module graph.
- */
-export type ScopeBand = "project" | "global";
+// The scope and status types are part of the rendering vocabulary — the one
+// module that owns both the states and the words (and glyphs) for them.
+// Re-exported here so doctor's type surface stays complete; the definitions,
+// the `available` tier's rationale, and the structural pin against
+// `@canonical/harnesses` live with the vocabulary.
+import type { CheckStatus, Scope } from "../../kernel/render/vocabulary.js";
 
-/** Status of a doctor check or one of its sub-items. */
-export type CheckStatus = "pass" | "fail" | "skip";
+export type {
+  CheckStatus,
+  Scope,
+} from "../../kernel/render/vocabulary.js";
 
 /**
  * A structured sub-item under a check — e.g. one resolved package under
@@ -35,22 +37,27 @@ export interface CheckResult {
   readonly detail: string;
   /** Optional structured breakdown, rendered as indented sub-items. */
   readonly items?: readonly CheckItem[];
-  /** Remedial instruction shown inline under a failing check. */
+  /**
+   * Remedial instruction shown inline under the check: for `fail` the fix,
+   * for `available` the setup command that enables the integration.
+   */
   readonly remedy?: string;
   /**
-   * Which config band the check concerns, if any: `global` for the user/home
+   * Which config scope the check concerns, if any: `global` for the user/home
    * level (shell completions), `project` for per-repo config (skills). The MCP
-   * checks derive their band from the harnesses they found. The renderer groups
-   * banded checks into Global/Project sections; environment checks (Node,
-   * versions, store) carry no band.
+   * checks derive their scope from the harnesses they found. The renderer groups
+   * scoped checks into Global/Project sections; environment checks (Node,
+   * versions, store) carry no scope.
    */
-  readonly band?: ScopeBand;
+  readonly scope?: Scope;
 }
 
-/** Aggregated results from all doctor checks. */
+/** Aggregated results from all doctor checks — one count per status tier. */
 export interface DoctorData {
   readonly checks: readonly CheckResult[];
   readonly passed: number;
   readonly failed: number;
+  /** Opt-in integrations detected but not set up — counted apart from failures. */
+  readonly available: number;
   readonly skipped: number;
 }

package/src/capabilities/emptyRecovery.test.ts

@@ -35,6 +35,9 @@ function storyFor(noun: string): PackDefinition {
 const PREFIXES = {
   ds: "https://ds.canonical.com/",
   cs: "https://ds.canonical.com/code-standards/",
+  // The `standard` list query names `skos:broader` for its category roll-up —
+  // a CORE prefix on the real build path, which this in-memory helper bypasses.
+  skos: "http://www.w3.org/2004/02/skos/core#",
   owl: "http://www.w3.org/2002/07/owl#",
   rdfs: "http://www.w3.org/2000/01/rdf-schema#",
   xsd: "http://www.w3.org/2001/XMLSchema#",
@@ -85,7 +88,12 @@ const listVerb = (pack: PackDefinition): VerbSpec =>
 const PACK_LISTS: readonly { pack: PackDefinition; hint: RegExp }[] = [
   { pack: storyFor("modifier"), hint: /pragma sources update/ },
   { pack: storyFor("token"), hint: /pragma sources update/ },
-  { pack: storyFor("standard"), hint: /broaden your filter/ },
+  // CHANGED DELIBERATELY. `standard` used to fall through to the generic
+  // build/broaden hint, and the build half of it is actively WRONG for this
+  // noun: the code standards ride the embedded snapshot and answer with no
+  // `sources update` at all. It now authors its own, pointing at the one
+  // surface that reads the category vocabulary out of the graph.
+  { pack: storyFor("standard"), hint: /pragma standard categories/ },
 ];
 
 const REAL = { dryRun: false, undo: false, yes: false };
@@ -101,21 +109,23 @@ describe("pack list empty-state (U5, PROTECTED)", () => {
 
   it.each(
     PACK_LISTS,
-  )("$pack.noun list renders a non-blank message (+ hint) and keeps JSON []", ({
+  )("$pack.noun list declares a non-blank empty notice (+ hint), JSON stays []", ({
     pack,
     hint,
   }) => {
     const { formatters } = listVerb(pack).output;
-    const plain = formatters.plain([]);
-    expect(plain).toContain(`No ${pack.noun} entries found.`);
-    expect(plain).toMatch(hint);
+    // The message + runnable hint live on the empty-state seam — the
+    // dispatcher routes them to stderr, keeping plain stdout pure data.
+    const notice = formatters.notice?.([]);
+    expect(notice).toContain(`No ${pack.noun} entries found.`);
+    expect(notice).toMatch(hint);
     // JSON is the uniform empty array — unchanged by the message.
     expect(formatters.json([])).toBe("[]");
     // The llm view stays non-blank too (the `(0)` heading plus the message).
     expect(formatters.llm([]).trim().length).toBeGreaterThan(0);
   });
 
-  it("dispatch prints the empty message on stdout and exits 0 (end-to-end)", async () => {
+  it("dispatch routes the empty message to stderr and exits 0 (end-to-end)", async () => {
     const outcome = await executeVerb(
       listVerb(storyFor("modifier")),
       {},
@@ -123,7 +133,10 @@ describe("pack list empty-state (U5, PROTECTED)", () => {
       rt,
     );
     expect(outcome.exitCode).toBe(0);
-    expect(outcome.stdout).toContain("No modifier entries found.");
-    expect(outcome.stdout).toContain("pragma sources update");
+    // stdout carries no prose a pipe would read as a record; the calm notice
+    // and its hint reach the human on stderr.
+    expect(outcome.stdout ?? "").not.toContain("No modifier entries found.");
+    expect(outcome.stderr).toContain("No modifier entries found.");
+    expect(outcome.stderr).toContain("pragma sources update");
   });
 });

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",
+    });
+  });
+});