@canonical/pragma-cli 0.34.0 → 0.36.0

package/src/kernel/runtime/graphpack/embedded.ts

@@ -1,6 +1,6 @@
 /**
  * The embedded pack: the distribution's own graph, compiled from the packs
- * `pragma.conf.ts` declares and inlined into the binary as escaped strings
+ * `pragma.conf.ts` declares and inlined into the source as escaped strings
  * (`pack.generated.ts`, produced by `scripts/bundle.ts`). It is the store the
  * CLI boots when the user has not pinned their own packs and has not built
  * anything yet — so a fresh install answers real store-backed reads with no
@@ -22,8 +22,8 @@
  * their OWN generated module (like the index): dispatch reads them on every
  * command, and pulling them out of `pack.generated.ts` would load its ~1.9 MB
  * of n-quads with them — a measured +28 ms on every invocation. Inlining as JS strings
- * (rather than file assets) guarantees the content survives `bun build
- * --compile` with no asset-embedding step.
+ * (rather than file assets) means the pack travels with the emitted modules —
+ * it needs no asset step in any build, and no file lookup at run time.
  */
 
 import {

package/src/kernel/runtime/graphpack/manifest.ts

@@ -104,7 +104,7 @@ export function readManifest(dir: string): Manifest | undefined {
  * would silently drop every package-declared noun. Requiring all four present +
  * non-empty makes `buildPack` rebuild a torn pack and makes the boot decision
  * surface STORE_UNAVAILABLE (the ordinary "not built" recovery) instead of a
- * "please report this" crash. `stories.json` is additionally gated on its SHAPE
+ * "report this" crash. `stories.json` is additionally gated on its SHAPE
  * — see {@link storiesAreReadable} for why it, and only it, is parsed here. */
 export function packIsComplete(dir: string): boolean {
   if (readManifest(dir) === undefined) return false;

package/src/kernel/runtime/graphpack/read.ts

@@ -16,8 +16,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { createStore } from "@canonical/ke";
 import { compileFromExtraction } from "@canonical/ke-graphql";
-import { PragmaError } from "../../error/PragmaError.js";
-import { cliRecovery } from "../../error/recovery.js";
+import { cliRecovery, PragmaError } from "../../error/index.js";
 import type { StoreSession } from "../types.js";
 import { readManifest } from "./manifest.js";
 import { packIndexSchema } from "./schemas.js";

package/src/kernel/runtime/loadSession.ts

@@ -9,7 +9,7 @@
  * than silently reaching out.
  */
 
-import type { ConfigLayers } from "../config/types.js";
+import type { ConfigLayers } from "../config/index.js";
 import { materializeEmbeddedPack } from "./graphpack/embedded.js";
 import { readPack } from "./graphpack/read.js";
 import { resolveSources } from "./resolveSources.js";

package/src/kernel/runtime/probe.ts

@@ -1,12 +1,12 @@
 /**
  * The `__store-probe` diagnostic — boot the embedded pack and report a count.
  *
- * Its whole reason to exist is the compiled binary: it exercises the full
- * store-boot path (oxigraph WASM load, n-quads cache load, `compileFromExtraction`,
- * a SPARQL count) so a spawned-binary smoke test can prove the WASM and the
- * embedded pack survive `bun build --compile`. A silent store-boot failure in
- * the standalone binary is the one failure vitest's in-process suite cannot
- * catch, so this is the guard. Storeless code never imports it — the bin
+ * Its whole reason to exist is the PROCESS BOUNDARY: it exercises the full
+ * store-boot path (oxigraph WASM load, n-quads cache load,
+ * `compileFromExtraction`, a SPARQL count) so a spawned smoke test can prove the
+ * WASM and the embedded pack load from what actually ships. A silent store-boot
+ * failure in the shipped artifact is the one failure vitest's in-process suite
+ * cannot catch, so this is the guard (`wasmEmbed.test.ts` spawns it). Storeless code never imports it — the bin
  * fast-paths it behind a dynamic import.
  */
 

package/src/kernel/runtime/readEntity.ts

@@ -1,6 +1,5 @@
 /**
- * Store-backed single-entity read: every triple where a URI is the subject,
- * grouped by predicate.
+ * Store-backed single-entity read: the GRAPH NEIGHBOURHOOD of one URI.
  *
  * The ONE reader shared by the `graph inspect` CLI verb and the MCP resource
  * `read` — so a resource read and a `graph inspect` of the same URI return
@@ -11,52 +10,328 @@
  * absolute IRI addresses the subject exactly and user input never reaches the
  * query text raw.
  *
+ * Four things make the payload answerable rather than merely faithful:
+ *
+ * - **Typed terms.** Read from ke's `termBindings` (the term-preserving view of
+ *   the SAME rows), never the stringly `bindings`. This is what makes prefix
+ *   compaction SAFE: only a `NamedNode` is compacted, so a literal whose text
+ *   happens to start with a namespace IRI is no longer silently rewritten into
+ *   something that reads as an IRI. It also keeps `datatype`/`language`, which
+ *   the string view drops.
+ * - **Inbound relations.** Everything pointing AT the subject, grouped by
+ *   predicate. Without it the entity that a resource is supposed to describe
+ *   cannot answer "what implements this?" or "what inherits from this?" — the
+ *   relations live on the OTHER side of the arrow and were simply invisible.
+ * - **Nested blank nodes.** A blank node is a store-local handle: it re-mints on
+ *   every load and is unreachable through `pragma:{+uri}`. Inlining one level
+ *   turns a dead `_:hash` into the record it stands for (a changelog entry's
+ *   text/type/timestamp). Depth ONE is not a shortcut — 11 of this graph's 922
+ *   blank nodes nest, so one level is what there is to inline.
+ * - **Neighbour titles.** Every named neighbour carries the human name the index
+ *   already holds, so a reader is not forced into a second read per IRI just to
+ *   learn that `ds:tag.needsdocumentation` is "needs:documentation".
+ *
+ * Bounded by the SHARED disclosure ladder, and by what an inbound group IS —
+ * because not every edge pointing at an entity is the same kind of thing:
+ *
+ * - A RELATION fans in narrowly and every subject is part of the answer
+ *   (`ds:implementsBlock`, `ds:inheritsFrom`), so it is LISTED.
+ * - A ROSTER fans in without bound because it grows with the data rather than
+ *   the model — a class extension (`rdf:type`), a tier's membership (`ds:tier`,
+ *   141 deep here) — and is already answered by `pragma/instanceCount` and by
+ *   the noun's list verb. So it is SAMPLED: a few exemplars, flagged `sampled`,
+ *   never a page. Listing rosters cost a `detailed` read 19.5 KB on one class
+ *   and 20.9 KB on one tier, restating what a single `*_list` answers properly.
+ *
+ * The two are told apart by FAN-IN, not by predicate name, so the kernel names
+ * no vocabulary and a graph whose rosters hang off different predicates is
+ * bounded just the same. `count` always reports the TRUE total either way: a
+ * sample that silently passed for the whole set is how "3 implementations"
+ * becomes a wrong answer.
+ *
  * Reached only behind the lazy store (a `needsStore` verb / a resource read), so
  * it never lands on the storeless fast path.
  */
 
-import { PragmaError } from "../error/PragmaError.js";
-import { cliRecovery } from "../error/recovery.js";
+import type { DetailLevel } from "../../constants.js";
+import { cliRecovery, PragmaError } from "../error/index.js";
 import { resolveUri } from "../packs/iri.js";
+import { compactUri, resolveDetail } from "../render/index.js";
+import type { PackIndex } from "./graphpack/types.js";
 import type { PragmaRuntime } from "./types.js";
 
-/** All objects asserted for one predicate on a subject. */
+// Inline `import("…")` type (no `from`) — a static `import type` from
+// @canonical/ke still puts the package on the module graph the lazy-dispatch
+// probe walks (`capabilities/lazy.test.ts`), which would drag the store runtime
+// onto the storeless `--help`/`__complete` fast path. Same device, and same
+// reason, as `graph/query.render.ts`.
+type Term = import("@canonical/ke").Term;
+
+/**
+ * Where a relation stops being an answer and becomes a roster.
+ *
+ * A group at or under this fan-in is LISTED: every subject is part of the
+ * answer, and there are few enough that reading them is cheaper than going to
+ * fetch them. Above it, listing the head is not more useful than showing a few
+ * — only longer — so the group is SAMPLED instead.
+ *
+ * Derived from fan-in rather than from a predicate name, which is what keeps the
+ * kernel free of vocabulary: `rdf:type` inbound is the obvious roster (a class
+ * extension, unbounded by construction and already answered by
+ * `pragma/instanceCount` and the noun's list verb), but it is NOT the only one.
+ * Membership edges behave identically — this graph's `ds:tier` fans in 141 deep
+ * — and a rule keyed on `rdf:type` would have left a `detailed` read of one tier
+ * at 20.9 KB while congratulating itself on having fixed classes.
+ */
+const ROSTER_THRESHOLD = 20;
+
+/** How many subjects each level lists for a genuine ANSWER (fan-in ≤ threshold). */
+const ANSWER_CAP: Readonly<Record<DetailLevel, number>> = {
+  summary: 0,
+  standard: 10,
+  detailed: ROSTER_THRESHOLD,
+};
+
+/**
+ * How many EXEMPLARS each level shows for a roster — the move the `*_sample`
+ * verbs make, and for the same reason: enough to see the shape of a member,
+ * never the roster itself. `count` stays exact and {@link InboundGroup.sampled}
+ * says which kind of answer this is, so a reader reaches for the list verb
+ * rather than trying to page a resource read into one.
+ */
+const SAMPLE_CAP: Readonly<Record<DetailLevel, number>> = {
+  summary: 0,
+  standard: 3,
+  detailed: 5,
+};
+
+/**
+ * How many characters of a LITERAL each level carries.
+ *
+ * The measured cost of a rich entity is not its structure but its prose: one
+ * button spent 8,572 of its 9,734 literal characters on two fields
+ * (`ds:guidelines` 5,814, `ds:usage` 2,758). Serving those in full at the
+ * DEFAULT level makes every read of that entity pay for documentation the
+ * reader may not have asked for — and the noun's own lookup verb serves the
+ * same fields under its own disclosure, properly.
+ *
+ * So long-form prose is what `detailed` is FOR. Below it a literal is previewed
+ * and marked {@link ReadTerm.truncated} with its true {@link ReadTerm.length},
+ * so a reader can always see that there is more and how much.
+ */
+const LITERAL_CAP: Readonly<Record<DetailLevel, number>> = {
+  summary: 120,
+  standard: 400,
+  detailed: Number.POSITIVE_INFINITY,
+};
+
+/**
+ * Ceiling on the EXEMPLAR rows fetched — never on the counts.
+ *
+ * Counting and exhibiting are two different questions, and answering both from
+ * one capped query 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 from the read entirely — while
+ * `InboundGroup.count` promised the true total. Counts now come from an
+ * aggregate the store computes; only the exemplars are bounded.
+ */
+const EXEMPLAR_FETCH_LIMIT = 500;
+
+/** The predicate whose object is a subject's type — hoisted out of nested records. */
+const RDF_TYPE = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type";
+
+/** An RDF term as the read projects it: typed, compacted, and named. */
+export interface ReadTerm {
+  readonly termType: "NamedNode" | "BlankNode" | "Literal";
+  /** The full lexical value (the IRI, the literal text, or the blank label). */
+  readonly value: string;
+  /** Prefixed form — `NamedNode` only, and only when a namespace matches. */
+  readonly prefixed?: string;
+  /** Human name from the pack index — `NamedNode` only, when the index knows it. */
+  readonly title?: string;
+  /** Literal datatype, compacted; absent for plain `xsd:string` (ke's convention). */
+  readonly datatype?: string;
+  /** Literal language tag, when the literal carries one. */
+  readonly language?: string;
+  /**
+   * Base direction of an RDF 1.2 directional literal. Dropped, `"hello"@en--ltr`
+   * is indistinguishable from a plain `"hello"@en` — which is exactly the kind
+   * of quiet flattening reading the TERM view was meant to stop.
+   */
+  readonly direction?: "ltr" | "rtl";
+  /** Set when `value` is a PREFIX of the real literal (see {@link length}). */
+  readonly truncated?: true;
+  /** The literal's true character count, present only when truncated. */
+  readonly length?: number;
+  /**
+   * Marks a term no `pragma:{+uri}` read can resolve. Only blank nodes carry it:
+   * their labels are store-local and re-mint on every load, so following one is
+   * always a dead end — stated here rather than left for the reader to discover.
+   */
+  readonly addressable?: false;
+}
+
+/** One inlined blank node: its fields, keyed by predicate, as terms. */
+export type NestedRecord = Record<string, ReadTerm>;
+
+/** All objects asserted for one predicate on the subject. */
 export interface PredicateGroup {
-  readonly predicate: string;
-  readonly objects: string[];
+  readonly predicate: ReadTerm;
+  readonly objects: ReadTerm[];
+}
+
+/** Everything asserting one predicate ABOUT the subject. */
+export interface InboundGroup {
+  readonly predicate: ReadTerm;
+  /** The TRUE number of subjects, whatever `subjects` was capped to. */
+  readonly count: number;
+  /** Subjects — listed for a relation, sampled for a roster; level-capped. */
+  readonly subjects: ReadTerm[];
+  /** Set when `subjects` is shorter than `count`. */
+  readonly truncated?: true;
+  /**
+   * Set when the group is a ROSTER rather than a relation: `subjects` are
+   * EXEMPLARS chosen to show the shape of a member, not the head of a page.
+   * Reach for the noun's list verb for the full set — paging a resource read
+   * will not produce one.
+   */
+  readonly sampled?: true;
+  /**
+   * How many subjects this level would have exhibited, had any been nameable.
+   *
+   * Without it an empty `subjects` is ambiguous: at `summary` every group is
+   * empty because the level shows none, which is not the same as a group whose
+   * members are all blank nodes and cannot be shown at all. A renderer needs to
+   * tell those apart before it says anything about why the list is empty.
+   */
+  readonly exhibits: number;
 }
 
 /** The result of inspecting one subject URI. */
 export interface InspectResult {
   /** The resolved (full) subject URI. */
   readonly uri: string;
+  /** The subject's prefixed form, when a namespace matches. */
+  readonly prefixed?: string;
   /** Human label from the pack index, when known. */
   readonly label?: string | null;
-  /** Predicate/object groups, ordered by predicate. */
+  /** Predicate/object groups asserted BY the subject, ordered by predicate. */
   readonly groups: PredicateGroup[];
+  /** Predicate groups asserted ABOUT the subject, ordered by predicate. */
+  readonly inbound: InboundGroup[];
+  /**
+   * Blank-node objects inlined one level, keyed by the predicate that reaches
+   * them. Omitted at `summary`.
+   *
+   * Field values are TERMS, not strings: a record's members are as much a part
+   * of the graph as the subject's own, and flattening them would reintroduce
+   * exactly the IRI-versus-literal ambiguity the term projection exists to
+   * close — and leave the Turtle serializer unable to tell `ds:Foo` from
+   * `"ds:Foo"`.
+   */
+  readonly nested: Record<string, NestedRecord[]>;
+  /** The disclosure level this payload was built at. */
+  readonly detail: DetailLevel;
+  /**
+   * The prefix map every compacted name in this payload was produced from.
+   *
+   * Carried rather than left to be re-derived: a renderer that reconstructs it
+   * from the terms can only learn the prefixes that happen to appear on a named
+   * NODE, and misses any used solely by the subject, a nested record's key, or a
+   * literal's datatype — emitting compact names with no matching `@prefix`, i.e.
+   * invalid Turtle. The reader knows the real map; it should say so.
+   */
+  readonly prefixes: Readonly<Record<string, string>>;
+}
+
+/**
+ * Whether a name tells a reader anything the URI's own local name did not.
+ *
+ * Measured on this graph, EVERY title a button's neighbourhood carried merely
+ * restated its local name in different casing (`ds:implementsBlock` titled
+ * "implementsBlock", `ds:apps.component.file_tree` titled "FileTree"). Emitting
+ * those spends a reader's attention — and an agent's context — to say the same
+ * word twice. A graph whose labels are real prose (a concept at `ds:concept.pd`
+ * named "Progressive disclosure") still keeps them, so this thins noise without
+ * deciding that labels are worthless.
+ */
+function isInformativeName(name: string, short: string): boolean {
+  const normalize = (value: string): string =>
+    value.replace(/[\s._:-]/g, "").toLowerCase();
+  const local = short.split(/[:.]/).pop() ?? short;
+  return normalize(name) !== normalize(local);
+}
+
+/** Index lookup for a neighbour's human name (`label`, else the first alt name). */
+function nameIndex(index: PackIndex): ReadonlyMap<string, string> {
+  const names = new Map<string, string>();
+  for (const entity of index.entities) {
+    if (!entity.uri) continue;
+    const name = entity.label ?? entity.altNames?.[0];
+    if (name && !names.has(entity.uri)) names.set(entity.uri, name);
+  }
+  return names;
+}
+
+/** Project one ke term into a {@link ReadTerm}, previewing long literals. */
+function toReadTerm(
+  term: Term,
+  prefixes: Readonly<Record<string, string>>,
+  names: ReadonlyMap<string, string>,
+  detail: DetailLevel,
+): ReadTerm {
+  if (term.termType === "NamedNode") {
+    const prefixed = compactUri(term.value, prefixes);
+    const name = names.get(term.value);
+    const title = name && isInformativeName(name, prefixed) ? name : undefined;
+    return {
+      termType: "NamedNode",
+      value: term.value,
+      // compactUri returns the input unchanged when no namespace matches, so an
+      // unmatched IRI carries no `prefixed` rather than one echoing `value`.
+      ...(prefixed === term.value ? {} : { prefixed }),
+      ...(title ? { title } : {}),
+    };
+  }
+  if (term.termType === "BlankNode") {
+    return { termType: "BlankNode", value: term.value, addressable: false };
+  }
+  const cap = LITERAL_CAP[detail];
+  const overlong = term.value.length > cap;
+  return {
+    termType: "Literal",
+    value: overlong ? term.value.slice(0, cap) : term.value,
+    ...(overlong
+      ? { truncated: true as const, length: term.value.length }
+      : {}),
+    ...(term.datatype ? { datatype: compactUri(term.datatype, prefixes) } : {}),
+    ...(term.language ? { language: term.language } : {}),
+    ...(term.direction ? { direction: term.direction } : {}),
+  };
 }
 
 /**
- * Read one entity's triples, grouped by predicate.
+ * Read one entity's graph neighbourhood.
  *
- * @param rt - The runtime (lazy store + query facade).
+ * @param rt - The runtime (lazy store, query facade, config, global flags).
  * @param uri - A prefixed name or absolute IRI.
- * @returns The resolved URI, its index label, and predicate groups.
- * @throws PragmaError ENTITY_NOT_FOUND when the subject has no triples.
- * @note Impure — boots the store and queries it.
+ * @returns The resolved subject, its outbound groups, inbound groups, inlined
+ *   blank nodes, and the detail level the payload was built at.
+ * @throws PragmaError ENTITY_NOT_FOUND when the subject asserts no triples.
+ * @note Impure — boots the store and queries it (three reads: out, in, nested).
  */
 export async function readEntity(
-  rt: Pick<PragmaRuntime, "store" | "query">,
+  rt: Pick<PragmaRuntime, "store" | "query" | "loadConfig" | "globalFlags">,
   uri: string,
 ): Promise<InspectResult> {
   const session = await rt.store.get();
   const resolved = resolveUri(uri, session.prefixes);
 
-  const result = await rt.query.sparql(
+  const outbound = await rt.query.sparql(
     `SELECT ?predicate ?object WHERE { <${resolved}> ?predicate ?object } ORDER BY ?predicate ?object`,
   );
 
-  if (result.type !== "select" || result.bindings.length === 0) {
+  if (outbound.type !== "select" || outbound.termBindings.length === 0) {
     throw PragmaError.notFound("entity", uri, {
       recovery: cliRecovery(
         `graph query 'SELECT ?s WHERE { ?s ?p ?o } LIMIT 10'`,
@@ -66,19 +341,188 @@ export async function readEntity(
     });
   }
 
-  const groupMap = new Map<string, string[]>();
-  for (const binding of result.bindings) {
-    const predicate = binding.predicate ?? "";
-    const object = binding.object ?? "";
-    const objects = groupMap.get(predicate) ?? [];
-    objects.push(object);
-    groupMap.set(predicate, objects);
+  // The level is resolved from the SAME sources as every other disclosure: the
+  // `--detail` flag (which the MCP `detail` param also seeds), then config. A
+  // resource read carries no params of its own, so it lands on the config value
+  // — `config_set detail detailed` is how an agent asks a resource for more.
+  const detail = resolveDetail({
+    flag: rt.globalFlags.detail,
+    config: (await rt.loadConfig()).config.detail,
+  });
+  const names = nameIndex(session.index);
+  const term = (value: Term): ReadTerm =>
+    toReadTerm(value, session.prefixes, names, detail);
+
+  const groupMap = new Map<string, ReadTerm[]>();
+  const predicates = new Map<string, ReadTerm>();
+  let hasBlankObject = false;
+  for (const binding of outbound.termBindings) {
+    const predicate = binding.predicate;
+    const object = binding.object;
+    if (!predicate || !object) continue;
+    if (object.termType === "BlankNode") hasBlankObject = true;
+    predicates.set(predicate.value, term(predicate));
+    const objects = groupMap.get(predicate.value) ?? [];
+    objects.push(term(object));
+    groupMap.set(predicate.value, objects);
   }
-  const groups = [...groupMap.entries()].map(([predicate, objects]) => ({
-    predicate,
-    objects,
-  }));
+  const groups: PredicateGroup[] = [...groupMap.entries()].map(
+    ([predicate, objects]) => ({
+      // Every key was written from a binding above, so the lookup cannot miss.
+      predicate: predicates.get(predicate) as ReadTerm,
+      objects,
+    }),
+  );
+
+  const inbound = await readInbound(rt, resolved, detail, term);
+  const nested =
+    detail === "summary" || !hasBlankObject
+      ? {}
+      : await readNested(rt, resolved, session.prefixes, term);
 
+  const prefixed = compactUri(resolved, session.prefixes);
   const label = session.index.entities.find((e) => e.uri === resolved)?.label;
-  return { uri: resolved, ...(label != null ? { label } : {}), groups };
+  return {
+    uri: resolved,
+    ...(prefixed === resolved ? {} : { prefixed }),
+    ...(label != null ? { label } : {}),
+    groups,
+    inbound,
+    nested,
+    detail,
+    prefixes: session.prefixes,
+  };
+}
+
+/**
+ * Everything asserting a predicate about the subject, grouped and capped.
+ *
+ * One query rather than one per predicate: the rows are grouped in memory, so a
+ * hub costs the same round trip as a leaf.
+ */
+async function readInbound(
+  rt: Pick<PragmaRuntime, "query">,
+  resolved: string,
+  detail: DetailLevel,
+  term: (value: Term) => ReadTerm,
+): Promise<InboundGroup[]> {
+  // Counts from an AGGREGATE, so every predicate is counted in full and no
+  // predicate can be pushed out of the answer by a noisy neighbour.
+  const totals = await rt.query.sparql(
+    `SELECT ?predicate (COUNT(*) AS ?total) WHERE { ?subject ?predicate <${resolved}> } GROUP BY ?predicate ORDER BY ?predicate`,
+  );
+  if (totals.type !== "select") return [];
+
+  const counts = new Map<string, number>();
+  const predicates = new Map<string, Term>();
+  for (const binding of totals.termBindings) {
+    const predicate = binding.predicate;
+    const total = binding.total;
+    if (!predicate || !total) continue;
+    predicates.set(predicate.value, predicate);
+    counts.set(predicate.value, Number(total.value));
+  }
+  if (counts.size === 0) return [];
+
+  // Exemplars in a second, separately bounded pass. Blank nodes are excluded in
+  // the QUERY rather than after it, so the limit is spent on subjects that can
+  // actually be exhibited — a hub whose members are all blank returns nothing
+  // here and is reported by its count alone.
+  const retained = new Map<string, Term[]>();
+  const widest = Math.max(
+    ...Object.values(ANSWER_CAP),
+    ...Object.values(SAMPLE_CAP),
+  );
+  if (widest > 0) {
+    const exemplars = await rt.query.sparql(
+      `SELECT ?predicate ?subject WHERE { ?subject ?predicate <${resolved}> . FILTER(isIRI(?subject)) } ORDER BY ?predicate ?subject LIMIT ${EXEMPLAR_FETCH_LIMIT}`,
+    );
+    if (exemplars.type === "select") {
+      for (const binding of exemplars.termBindings) {
+        const predicate = binding.predicate;
+        const subject = binding.subject;
+        if (!predicate || !subject) continue;
+        const rows = retained.get(predicate.value) ?? [];
+        if (rows.length < widest) rows.push(subject);
+        retained.set(predicate.value, rows);
+      }
+    }
+  }
+
+  return [...counts.entries()].map(([key, count]) => {
+    // What the group IS decides how it is shown: a relation is listed, a roster
+    // is sampled. Derived from fan-in, so no predicate is named here.
+    const roster = count > ROSTER_THRESHOLD;
+    const cap = roster ? SAMPLE_CAP[detail] : ANSWER_CAP[detail];
+    const subjects = (retained.get(key) ?? []).slice(0, cap).map(term);
+    return {
+      predicate: term(predicates.get(key) as Term),
+      count,
+      subjects,
+      exhibits: cap,
+      ...(subjects.length < count ? { truncated: true as const } : {}),
+      ...(roster ? { sampled: true as const } : {}),
+    };
+  });
+}
+
+/**
+ * Blank-node objects inlined one level, as one record per node.
+ *
+ * Records rather than triples: the same content is roughly half the bytes and
+ * reads as the thing it models (a changelog entry, a property) instead of a
+ * scatter of rows the reader has to reassemble. `rdf:type` is hoisted to `type`
+ * — it is the record's kind, not one of its fields, and repeating it inline put
+ * the same IRI on every row.
+ */
+async function readNested(
+  rt: Pick<PragmaRuntime, "query">,
+  resolved: string,
+  prefixes: Readonly<Record<string, string>>,
+  term: (value: Term) => ReadTerm,
+): Promise<Record<string, NestedRecord[]>> {
+  const result = await rt.query.sparql(
+    `SELECT ?predicate ?node ?nodePredicate ?nodeObject WHERE { <${resolved}> ?predicate ?node . FILTER(isBlank(?node)) . ?node ?nodePredicate ?nodeObject } ORDER BY ?predicate ?node ?nodePredicate`,
+  );
+  if (result.type !== "select") return {};
+
+  // Keyed by blank-node label so repeated nodes under one predicate stay
+  // separate records; the label itself never reaches the payload.
+  const records = new Map<string, { via: string; row: NestedRecord }>();
+  for (const binding of result.termBindings) {
+    const predicate = binding.predicate;
+    const node = binding.node;
+    const nodePredicate = binding.nodePredicate;
+    const nodeObject = binding.nodeObject;
+    if (!predicate || !node || !nodePredicate || !nodeObject) continue;
+    const via = compactUri(predicate.value, prefixes);
+    // Keyed by predicate AND node. Keyed by node alone, a blank node linked from
+    // two predicates kept only whichever `via` arrived first and the second edge
+    // silently disappeared — and in Turtle the ordinary blank object is filtered
+    // out too, so nothing was left to notice it by.
+    const key = `${predicate.value}\u0000${node.value}`;
+    const record = records.get(key) ?? { via, row: {} };
+    const field =
+      nodePredicate.value === RDF_TYPE
+        ? "type"
+        : compactUri(nodePredicate.value, prefixes);
+    record.row[field] = term(nodeObject);
+    records.set(key, record);
+  }
+
+  const nested: Record<string, NestedRecord[]> = {};
+  for (const { via, row } of records.values()) {
+    const rows = nested[via] ?? [];
+    rows.push(row);
+    nested[via] = rows;
+  }
+  // Order records by their CONTENT, never by the blank-node label that grouped
+  // them. Oxigraph re-mints those labels on every load, so ordering by them made
+  // two reads of the same unchanged entity return the same records in different
+  // orders — nondeterminism the mirror test caught and a caller diffing two
+  // reads would have seen as spurious change.
+  for (const rows of Object.values(nested)) {
+    rows.sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+  }
+  return nested;
 }

package/src/kernel/runtime/refs/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Package refs — turning what a project DECLARED into pinned, on-disk RDF.
+ *
+ * `sources update` is the only caller, and this domain is its whole
+ * resolution: parse a `packs` entry into a typed reference, resolve that
+ * reference to a revision and the TTL/story files it carries, and report what
+ * the resulting set of sources says about itself. Three declaration kinds
+ * (`npm`, `file`, `git`) resolve three different ways but converge on one
+ * `ResolvedPackage`, so callers pin, hash, and build from a single shape.
+ *
+ * The prefix inspectors belong here rather than with the pack builder because
+ * they answer a question about the RESOLVED SET, not about any one package: a
+ * label two packages bind to different IRIs is a conflict nobody can see from
+ * inside either one, and it must be caught before the sources are built rather
+ * than after, when it would surface as a query that silently reads the wrong
+ * namespace.
+ *
+ * `redactUrl` is on the surface because every one of these paths ends in a
+ * message: a git URL may carry a token, and the caller that reports what it
+ * resolved needs the redactor as much as it needs the result.
+ *
+ * The git operations underneath — clone, fetch, head — stay internal. They are
+ * how `git` refs resolve, and they are safe because refs and URLs reach them
+ * as argv and never as shell text; exposing them would offer the operations
+ * without the parsing that validated their arguments.
+ */
+
+export type { PackageRef } from "./parseRef.js";
+export { parsePackDeclaration, redactUrl } from "./parseRef.js";
+export type {
+  PrefixClash,
+  ResolvedPackage,
+  ResolveOptions,
+} from "./resolve.js";
+export {
+  detectPrefixClashes,
+  harvestPrefixes,
+  resolvePackage,
+} from "./resolve.js";