@canonical/pragma-cli 0.34.0 → 0.35.0

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,19 +8,23 @@
  * name or absolute IRI addresses the subject exactly.
  */
 
-import { BIN_NAME } from "../../constants.js";
+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",
@@ -32,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: `${BIN_NAME} graph inspect ds:button` },
-    { cmd: `${BIN_NAME} 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

@@ -10,9 +10,9 @@
  */
 
 import { BIN_NAME } from "../../constants.js";
-import type { PragmaRuntime } from "../../kernel/runtime/types.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
@@ -40,7 +40,7 @@ const queryVerb: VerbSpec<Record<string, unknown>, QueryResult> = {
       note: "list every component subject",
     },
     {
-      cmd: `${BIN_NAME} 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,9 +10,8 @@
  */
 
 import type { QueryResult } from "@canonical/ke";
-import { PragmaError } from "../../kernel/error/PragmaError.js";
-import { cliRecovery } from "../../kernel/error/recovery.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.

package/src/capabilities/index.ts

@@ -14,7 +14,7 @@
  * `--help`/`__complete` fast paths stay free of the config reader and zod.
  */
 
-import type { CapabilityModule } from "../kernel/spec/types.js";
+import type { CapabilityModule } from "../kernel/spec/index.js";
 import { capabilitiesModule } from "./capabilities/index.js";
 import { colophonModule } from "./colophon/index.js";
 import { configModule } from "./config/index.js";
@@ -30,10 +30,12 @@ import { setupModule } from "./setup/index.js";
 import { skillModule } from "./skill/index.js";
 import { sourcesModule } from "./sources/index.js";
 import { upgradeModule } from "./upgrade/index.js";
+import { versionModule } from "./version/index.js";
 
 /** The modules with hand-written code, in authoring order. */
 const authored: readonly CapabilityModule[] = [
   infoModule,
+  versionModule,
   configModule,
   createModule,
   sourcesModule,

package/src/capabilities/info/collectInfo.ts

@@ -18,14 +18,15 @@ import {
   entityTotal,
   readPackIndex,
 } from "../../kernel/completion/entitySource.js";
-import { readConfig } from "../../kernel/config/readConfig.js";
+import { readConfig } from "../../kernel/config/index.js";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
 import { resolveSources } from "../../kernel/runtime/resolveSources.js";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
 import {
+  checkRegistryVersion,
   detectInstallSource,
+  PRAGMA_PACKAGE,
   pmUpdateCommand,
-} from "../shared/packageManager.js";
-import { checkRegistryVersion, PRAGMA_PACKAGE } from "../shared/registry.js";
+} from "../shared/index.js";
 import type { InfoData, InfoUpdate } from "./types.js";
 
 /**

package/src/capabilities/info/info.render.ts

@@ -4,7 +4,7 @@
 
 import { BIN_NAME } from "../../constants.js";
 import type { ConfigOrigin } from "../../kernel/config/types.js";
-import type { Formatters } from "../../kernel/spec/types.js";
+import type { Formatters } from "../../kernel/spec/index.js";
 import type { InfoData } from "./types.js";
 
 /** A `[layer]` marker for values a config file supplied (blank for defaults). */

package/src/capabilities/info/info.verb.ts

@@ -8,7 +8,7 @@
 
 import { BIN_NAME } from "../../constants.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
-import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
+import type { CapabilityModule, VerbSpec } from "../../kernel/spec/index.js";
 import { infoFormatters } from "./info.render.js";
 import type { InfoData } from "./types.js";
 

package/src/capabilities/lazy.test.ts

@@ -140,6 +140,38 @@ describe("lazy dispatch — module-graph probe (PROTECTED)", () => {
     }
   });
 
+  // The create surface's registration machinery — summon-core's projection
+  // helpers, its Commander adapter, and Commander itself — must stay behind
+  // the mount's dynamic import: `--help` and `__complete` both import this
+  // barrel and neither registers a single create command, so an eager edge
+  // here taxes every fast-path spawn for work only a dispatched `create`
+  // invocation performs. The registered flag/positional spellings the fast
+  // paths DO need (completion tokens, reference syntax) are baked into
+  // `createSurface.generated.ts` at build time, so nothing on this graph has
+  // to call the projection to learn them. Type-only imports are allowed —
+  // they are erased — which is why this walks import STATEMENTS rather than
+  // grepping for the specifier.
+  it("capabilities/index pulls no summon-core projection, adapter, or commander value import (PROTECTED)", () => {
+    const banned = [/^@canonical\/summon-core\/projection/, /^commander$/];
+    const graph = staticImportGraph(resolve(here, "index.ts"));
+    const pkgRoot = resolve(here, "..", "..");
+    // Anchored to line start so the word "import" inside a docblock cannot
+    // open a match that swallows prose down to the next real specifier.
+    const importRe = /^import\s+([^;]*?)from\s*["']([^"']+)["']/gm;
+    const offenders: string[] = [];
+    for (const file of graph) {
+      const source = readFileSync(file, "utf-8");
+      for (const match of source.matchAll(importRe)) {
+        const clause = match[1] as string;
+        const specifier = match[2] as string;
+        if (!banned.some((re) => re.test(specifier))) continue;
+        if (/^type\s/.test(clause.trim())) continue;
+        offenders.push(`${relative(pkgRoot, file)} → ${specifier}`);
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+
   it("NO module on that graph statically imports zod (PROTECTED)", () => {
     // This used to pin an exact set of one — `graphpack/types.ts`, reached via
     // `resolveSources` → `packIsComplete` → `readManifest` → `manifestSchema

package/src/capabilities/meta/complete.verb.ts

@@ -10,7 +10,7 @@
  * Storeless: the entity tier reads the index off disk, never booting the store.
  */
 
-import type { VerbSpec } from "../../kernel/spec/types.js";
+import type { VerbSpec } from "../../kernel/spec/index.js";
 
 /** The `__complete` verb spec. */
 export const completeVerb: VerbSpec<Record<string, unknown>, string[]> = {

package/src/capabilities/meta/index.ts

@@ -4,7 +4,7 @@
  */
 
 import { asVerb } from "../../kernel/spec/asVerb.js";
-import type { CapabilityModule } from "../../kernel/spec/types.js";
+import type { CapabilityModule } from "../../kernel/spec/index.js";
 import { completeVerb } from "./complete.verb.js";
 import { mcpVerb } from "./mcp.verb.js";