@canonical/pragma-cli 0.33.0 → 0.35.0

package/src/kernel/packs/compile.test.ts

@@ -8,12 +8,14 @@
  */
 
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { RECOVERY_CLI_PREFIX } from "../../constants.js";
 import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
 import type { PragmaRuntime } from "../runtime/types.js";
-import { compilePack } from "./compile.js";
+import { compileListable, compilePack, compileStoryModule } from "./compile.js";
 import type { LookupOutput } from "./resolveEntity.js";
 import { parsePackDefinition } from "./schema.js";
 import type { PackDefinition, PackRow } from "./types.js";
+import { distributionSource } from "./types.js";
 import { assertUniqueVerbs, verbKey } from "./uniqueness.js";
 
 const PREFIXES = {
@@ -92,8 +94,33 @@ describe("pack compiler — round-trip + shape (PROTECTED, storeless)", () => {
     expect(parsePackDefinition(raw, "test:widget")).toEqual(WIDGET_PACK);
   });
 
+  it("round-trips a fixed-count sample — the field the no-argument samples declare", () => {
+    // `sample.fixedCount` is a documented grammar field (packs/types.ts) that
+    // three of the distribution's own stories use and the covenant freezes
+    // (`block sample` takes no argument). It was missing from the `.strict()`
+    // sample schema, so ANY config- or package-declared story using it died
+    // with a fatal CONFIG_ERROR before ever reaching the compiler.
+    const lookup = WIDGET_PACK.lookup as NonNullable<PackDefinition["lookup"]>;
+    const fixed: PackDefinition = {
+      ...WIDGET_PACK,
+      lookup: { ...lookup, sample: { fixedCount: true } },
+    };
+    expect(parsePackDefinition(JSON.parse(JSON.stringify(fixed)), "t")).toEqual(
+      fixed,
+    );
+    // …and the compiler honours it: no `[count]` positional on the sample verb.
+    const sample = compilePack(fixed, distributionSource("t"), PREFIXES).find(
+      (v) => verbKey(v.path) === "widget sample",
+    );
+    expect(sample?.params).toEqual([]);
+  });
+
   it("projects list, lookup, and sample verbs with unique keys", () => {
-    const verbs = compilePack(WIDGET_PACK, "bundled:widget", PREFIXES);
+    const verbs = compilePack(
+      WIDGET_PACK,
+      distributionSource("bundled:widget"),
+      PREFIXES,
+    );
     expect(verbs.map((v) => verbKey(v.path))).toEqual([
       "widget list",
       "widget lookup",
@@ -103,7 +130,11 @@ describe("pack compiler — round-trip + shape (PROTECTED, storeless)", () => {
   });
 
   it("projects list filters as params (enum) + a search flag", () => {
-    const [list] = compilePack(WIDGET_PACK, "bundled:widget", PREFIXES);
+    const [list] = compilePack(
+      WIDGET_PACK,
+      distributionSource("bundled:widget"),
+      PREFIXES,
+    );
     expect(list?.params.map((p) => p.name)).toEqual(["kind", "search"]);
     const kind = list?.params.find((p) => p.name === "kind");
     expect(kind?.kind).toBe("enum");
@@ -112,7 +143,11 @@ describe("pack compiler — round-trip + shape (PROTECTED, storeless)", () => {
   });
 
   it("projects the lookup as a variadic name-completing positional + disclosure", () => {
-    const verbs = compilePack(WIDGET_PACK, "bundled:widget", PREFIXES);
+    const verbs = compilePack(
+      WIDGET_PACK,
+      distributionSource("bundled:widget"),
+      PREFIXES,
+    );
     const lookup = verbs.find((v) => verbKey(v.path) === "widget lookup");
     const name = lookup?.params.at(0);
     expect(name?.kind).toBe("string[]");
@@ -132,7 +167,7 @@ describe("pack compiler — round-trip + shape (PROTECTED, storeless)", () => {
       PackDefinition["lookup"]
     >;
     const nameParam = (def: PackDefinition) =>
-      compilePack(def, "bundled:widget", PREFIXES)
+      compilePack(def, distributionSource("bundled:widget"), PREFIXES)
         .find((v) => verbKey(v.path) === "widget lookup")
         ?.params.at(0);
 
@@ -162,6 +197,125 @@ describe("pack compiler — round-trip + shape (PROTECTED, storeless)", () => {
   });
 });
 
+describe("the grammar rejects what the compiler cannot build (PROTECTED)", () => {
+  // A definition that compiles to a duplicate `(noun, verb)` key or a duplicate
+  // CLI option is not merely odd — it throws out of `assembleEffectiveModules`
+  // or out of `buildProgram`, both of which run BEFORE the command tree exists.
+  // For a package-shipped story that means every command dies, `doctor` and
+  // `sources update` included. The collision is a property of the definition,
+  // so it is rejected here, where a package story degrades to a dropped file.
+  const listShape = {
+    query: "SELECT ?uri WHERE { ?uri a ex:Widget }",
+    columns: [{ field: "uri" }],
+  };
+  const parse = (def: unknown) => () =>
+    parsePackDefinition(def, "pkg/stories/widget.json");
+
+  it("rejects an extra verb that repeats list, lookup, sample, or itself", () => {
+    const lookup = { by: "ex:name", type: "ex:Widget", sample: true };
+    expect(
+      parse({
+        noun: "widget",
+        list: listShape,
+        verbs: [{ ...listShape, verb: "list" }],
+      }),
+    ).toThrow(/verb "list" is already compiled/);
+    expect(
+      parse({
+        noun: "widget",
+        lookup,
+        verbs: [{ ...listShape, verb: "lookup" }],
+      }),
+    ).toThrow(/verb "lookup" is already compiled/);
+    expect(
+      parse({
+        noun: "widget",
+        lookup,
+        verbs: [{ ...listShape, verb: "sample" }],
+      }),
+    ).toThrow(/verb "sample" is already compiled/);
+    expect(
+      parse({
+        noun: "widget",
+        list: listShape,
+        verbs: [
+          { ...listShape, verb: "categories" },
+          { ...listShape, verb: "categories" },
+        ],
+      }),
+    ).toThrow(/verb "categories" is already compiled/);
+  });
+
+  it("rejects a filter param declared twice, on list or on an extra verb", () => {
+    const twice = [
+      { param: "kind", variable: "uri" },
+      { param: "kind", variable: "uri" },
+    ];
+    expect(
+      parse({ noun: "widget", list: { ...listShape, filters: twice } }),
+    ).toThrow(/filter param "kind" is declared twice/);
+    expect(
+      parse({
+        noun: "widget",
+        list: listShape,
+        verbs: [{ ...listShape, verb: "categories", filters: twice }],
+      }),
+    ).toThrow(/filter param "kind" is declared twice/);
+  });
+
+  it("still accepts the distinct forms, and they compile to unique keys/params", () => {
+    const definition = parsePackDefinition(
+      {
+        noun: "widget",
+        list: {
+          ...listShape,
+          filters: [
+            { param: "kind", variable: "uri" },
+            { param: "tier", variable: "uri" },
+          ],
+        },
+        verbs: [{ ...listShape, verb: "categories" }],
+        lookup: { by: "ex:name", type: "ex:Widget", sample: true },
+      },
+      "pkg/stories/widget.json",
+    );
+    const verbs = compilePack(
+      definition,
+      { label: "pkg/stories/widget.json", origin: "package" },
+      PREFIXES,
+    );
+    expect(verbs.map((v) => verbKey(v.path))).toEqual([
+      "widget list",
+      "widget categories",
+      "widget lookup",
+      "widget sample",
+    ]);
+    expect(() => assertUniqueVerbs(verbs)).not.toThrow();
+    expect(verbs.at(0)?.params.map((p) => p.name)).toEqual(["kind", "tier"]);
+  });
+
+  it("names the shape a noun must have, not the regex", () => {
+    expect(parse({ noun: "Bad Noun", list: listShape })).toThrow(
+      /noun: must be lowercase kebab-case/,
+    );
+  });
+
+  it("rejects an emptyRecovery.cli that names a binary, and names the change", () => {
+    // The hint is rendered as `<consuming distribution> <cli>`, so a story
+    // carrying the old prefixed form would render `pragma pragma sources
+    // update`. Third-party packs are third-party DATA: they get an error that
+    // names the grammar change, not a silently doubled string.
+    const withCli = (cli: string) => ({
+      noun: "widget",
+      list: { ...listShape, emptyRecovery: { message: "None.", cli } },
+    });
+    expect(parse(withCli(`${RECOVERY_CLI_PREFIX}sources update`))).toThrow(
+      /WITHOUT the binary name/,
+    );
+    expect(parse(withCli("sources update"))).not.toThrow();
+  });
+});
+
 describe("pack compiler — SPARQL fetch path (PROTECTED)", () => {
   let rt: PragmaRuntime;
 
@@ -178,9 +332,11 @@ describe("pack compiler — SPARQL fetch path (PROTECTED)", () => {
   });
 
   const run = <R>(verbLabel: string, params: Record<string, unknown>) => {
-    const verb = compilePack(WIDGET_PACK, "bundled:widget", PREFIXES).find(
-      (v) => verbKey(v.path) === `widget ${verbLabel}`,
-    );
+    const verb = compilePack(
+      WIDGET_PACK,
+      distributionSource("bundled:widget"),
+      PREFIXES,
+    ).find((v) => verbKey(v.path) === `widget ${verbLabel}`);
     if (!verb) throw new Error(`no widget ${verbLabel}`);
     return verb.run(params, rt) as Promise<R>;
   };
@@ -227,3 +383,132 @@ describe("pack compiler — SPARQL fetch path (PROTECTED)", () => {
     expect(data.totalCount).toBe(2);
   });
 });
+
+/**
+ * The listing a story contributes to the MCP resource surface is DERIVED from
+ * the types its lookup already names — the story author writes the type set
+ * once, for the name resolve, and the resource listing reads that same
+ * declaration. Nothing to keep in sync because there is nothing written twice.
+ */
+describe("declared listing (derived from the lookup's types)", () => {
+  it("derives one collection per declared type, unweighted types at 1", () => {
+    expect(
+      compileListable({
+        noun: "gadget",
+        lookup: { by: "ex:name", types: ["ex:Widget", "ex:Part"] },
+      }),
+    ).toEqual({
+      sources: [
+        { type: "ex:Widget", as: "collection", weight: 1 },
+        { type: "ex:Part", as: "collection", weight: 1 },
+      ],
+    });
+  });
+
+  it("carries a declared weight onto the type it names", () => {
+    const listable = compileListable({
+      noun: "gadget",
+      lookup: {
+        by: "ex:name",
+        types: ["ex:Widget", "ex:Part"],
+        weights: { "ex:Part": 0.6 },
+      },
+    });
+    expect(listable?.sources.map((s) => s.weight)).toEqual([1, 0.6]);
+  });
+
+  it("declares nothing for a list-only noun (it addresses no class)", () => {
+    expect(
+      compileListable({ noun: "gadget", list: { query: "", columns: [] } }),
+    ).toBeUndefined();
+  });
+
+  it("carries the listing onto the compiled module, beside its verbs", () => {
+    const module = compileStoryModule(
+      { noun: "gadget", lookup: { by: "ex:name", type: "ex:Widget" } },
+      distributionSource("t"),
+      PREFIXES,
+    );
+    expect(module.story).toBe(true);
+    expect(module.mcpListable?.sources).toEqual([
+      { type: "ex:Widget", as: "collection", weight: 1 },
+    ]);
+  });
+});
+
+describe("weights validation (a weight that can never apply is rejected)", () => {
+  it("accepts a weight naming a type the lookup addresses", () => {
+    const definition = {
+      noun: "gadget",
+      lookup: {
+        by: "ex:name",
+        types: ["ex:Widget", "ex:Part"],
+        weights: { "ex:Part": 0.6 },
+      },
+    };
+    expect(parsePackDefinition(definition, "t")).toEqual(definition);
+  });
+
+  it("REJECTS a weight naming a type the lookup does not address", () => {
+    // A silent no-op is how a weight that never applied survives review: the
+    // type gets renamed, the weight stays pointed at the old name, and nothing
+    // says so — the ranking simply stops changing.
+    expect(() =>
+      parsePackDefinition(
+        {
+          noun: "gadget",
+          lookup: {
+            by: "ex:name",
+            types: ["ex:Widget"],
+            weights: { "ex:Gone": 0.6 },
+          },
+        },
+        "t",
+      ),
+    ).toThrow(/ex:Gone/);
+  });
+
+  it("REJECTS a weight outside 0–1", () => {
+    expect(() =>
+      parsePackDefinition(
+        {
+          noun: "gadget",
+          lookup: {
+            by: "ex:name",
+            type: "ex:Widget",
+            weights: { "ex:Widget": 2 },
+          },
+        },
+        "t",
+      ),
+    ).toThrow();
+  });
+});
+
+describe("compileListable — absolute IRIs reach the prefixed contract", () => {
+  it("compacts an absolute lookup type, and its weight key with it", () => {
+    // `PackLookup.type`/`types` accept a prefixed name OR an absolute IRI, but
+    // the listing is keyed on the index's prefixed types. Verbatim, such a story
+    // compiled clean and then matched no class and no weight.
+    const listable = compileListable({
+      noun: "widget",
+      lookup: {
+        by: "ds:name",
+        types: ["https://ds.canonical.com/Component", "ds:Pattern"],
+        weights: { "https://ds.canonical.com/Component": 0.4 },
+      },
+    } as PackDefinition);
+
+    expect(listable?.sources.map((s) => s.type)).toEqual([
+      "ds:Component",
+      "ds:Pattern",
+    ]);
+    // The weight followed its type through the same compaction, so it still
+    // applies — keying it on the raw IRI would have silently dropped it.
+    const component = listable?.sources.find((s) => s.type === "ds:Component");
+    expect(component?.weight).toBe(0.4);
+    expect(listable?.sources.find((s) => s.type === "ds:Pattern")?.weight).toBe(
+      1,
+    );
+  });
+});

package/src/kernel/packs/compile.ts

@@ -7,15 +7,24 @@
  *
  * Pure, storeless spec-generation: it builds paths, params, formatters, and run
  * closures without touching the store or zod, so it runs on the
- * `--help`/`__complete` fast path (the bundled packs compile at import; the
- * dynamic merge is `collect.assembleEffectiveModules`/`loadEffectiveModules`).
+ * `--help`/`__complete` fast path (the distribution's declared stories compile
+ * at import, in `capabilities/distribution.ts`; the dynamic merge is
+ * `collect.assembleEffectiveModules`/`loadEffectiveModules`).
  * The heavy work is deferred into the run closures (behind the lazy runtime
  * facade).
  */
 
-import type { PragmaRuntime } from "../runtime/types.js";
+import { BIN_NAME } from "../../constants.js";
+import { compactUri, DEFAULT_PREFIX_MAP } from "../render/index.js";
+import type { PragmaRuntime } from "../runtime/index.js";
 import { asVerb } from "../spec/asVerb.js";
-import type { DisclosureSpec, ParamSpec, VerbSpec } from "../spec/types.js";
+import type {
+  CapabilityModule,
+  DisclosureSpec,
+  McpListable,
+  ParamSpec,
+  VerbSpec,
+} from "../spec/types.js";
 import {
   listFormatters,
   lookupFormatters,
@@ -35,6 +44,7 @@ import type {
   PackLookup,
   PackRow,
   PackSearch,
+  StorySource,
 } from "./types.js";
 
 // The run bodies pull the SPARQL/GraphQL fetch layer; they are dynamic-imported
@@ -62,7 +72,7 @@ const READ_CAPABILITY = {
  */
 export function compilePack(
   definition: PackDefinition,
-  source: string,
+  source: StorySource,
   prefixes: Readonly<Record<string, string>>,
 ): VerbSpec[] {
   const { noun } = definition;
@@ -104,6 +114,83 @@ export function compilePack(
   return verbs;
 }
 
+/**
+ * Derive a story's MCP resource listing from the types its lookup addresses.
+ *
+ * ZERO new authoring: a read story ALREADY declares its type set
+ * (`lookup.type` / `lookup.types`) because that is what its name resolve is
+ * constrained by, so the slice of the index the noun contributes to the listing
+ * IS that declaration read a second time by a different reader — never written
+ * a second time by the author. Each type contributes ONE collection entry (its
+ * class entry, carrying the instance count); the individuals stay reachable
+ * through the `{+uri}` template and its autocomplete.
+ *
+ * Returns `undefined` for a story with no lookup (a list-only noun addresses no
+ * class, so it can name no slice).
+ *
+ * @param definition - A validated pack definition.
+ * @returns Its declared listing, or `undefined` when it declares no types.
+ */
+export function compileListable(
+  definition: PackDefinition,
+): McpListable | undefined {
+  const lookup = definition.lookup;
+  if (!lookup) return undefined;
+  const types = lookup.types ?? (lookup.type ? [lookup.type] : []);
+  if (types.length === 0) return undefined;
+  // `PackLookup.type`/`types` accept a prefixed name OR an absolute IRI, but the
+  // listing is keyed on the index's PREFIXED types. Copied verbatim, a lookup
+  // legitimately constrained to `https://…/Widget` compiles clean and then
+  // matches no class and no weight — a story that is valid everywhere else and
+  // silently contributes nothing here. Compacted against the same map
+  // `resolveUri` expands with, so the two directions agree.
+  const compact = (type: string): string =>
+    compactUri(type, DEFAULT_PREFIX_MAP);
+  const weights = Object.fromEntries(
+    Object.entries(lookup.weights ?? {}).map(([type, weight]) => [
+      compact(type),
+      weight,
+    ]),
+  );
+  return {
+    sources: types.map(compact).map((type) => ({
+      type,
+      as: "collection" as const,
+      // Unlisted types weigh 1 — the default is "as important as any other",
+      // so a story that declares no weights needs no weights.
+      weight: weights[type] ?? 1,
+    })),
+  };
+}
+
+/**
+ * Compile a story into the capability module that carries it.
+ *
+ * The ONE place a {@link PackDefinition} becomes a {@link CapabilityModule} —
+ * the distribution's static stories and the dynamic (config/package) ones come
+ * through here alike, so a module-level projection derived from the story
+ * (today: {@link compileListable}) cannot reach one tier and miss the other.
+ *
+ * @param definition - A validated pack definition.
+ * @param source - Where the definition came from, for diagnostics.
+ * @param prefixes - The merged prefix map used for display compaction.
+ * @returns The module: the compiled verbs plus the story's module-level data.
+ */
+export function compileStoryModule(
+  definition: PackDefinition,
+  source: StorySource,
+  prefixes: Readonly<Record<string, string>>,
+): CapabilityModule {
+  const listable = compileListable(definition);
+  return {
+    name: definition.noun,
+    story: true,
+    verbs: compilePack(definition, source, prefixes),
+    colophon: definition.colophon,
+    ...(listable ? { mcpListable: listable } : {}),
+  };
+}
+
 /** Presentation facts for one compiled list-shaped verb. */
 interface ListVerbMeta {
   readonly noun: string;
@@ -111,7 +198,7 @@ interface ListVerbMeta {
   readonly summary: string;
   /** The authored MCP tool description (from `toolDescription`), if any. */
   readonly doc?: string;
-  readonly source: string;
+  readonly source: StorySource;
   readonly prefixes: Readonly<Record<string, string>>;
 }
 
@@ -135,17 +222,17 @@ function compileListVerb(shape: PackList, meta: ListVerbMeta): VerbSpec {
       }),
     },
     examples: [
-      { cmd: `pragma ${meta.noun} ${meta.verb}` },
+      { cmd: `${BIN_NAME} ${meta.noun} ${meta.verb}` },
       ...(filterExample
         ? [
             {
-              cmd: `pragma ${meta.noun} ${meta.verb} --${filterExample.param} ${quoteExample(
+              cmd: `${BIN_NAME} ${meta.noun} ${meta.verb} --${filterExample.param} ${quoteExample(
                 filterExample.values?.at(0) ?? "",
               )}`,
             },
           ]
         : []),
-      { cmd: `pragma ${meta.noun} ${meta.verb} --format llm` },
+      { cmd: `${BIN_NAME} ${meta.noun} ${meta.verb} --format llm` },
     ],
     capability: READ_CAPABILITY,
     run: (params: Record<string, unknown>, rt: PragmaRuntime) =>
@@ -160,7 +247,7 @@ function compileListVerb(shape: PackList, meta: ListVerbMeta): VerbSpec {
 function compileLookupVerb(
   lookup: PackLookup,
   noun: string,
-  source: string,
+  source: StorySource,
   prefixes: Readonly<Record<string, string>>,
 ): VerbSpec {
   // Derive-by-default: every lookup completes its `<name>` from the pack index
@@ -197,7 +284,7 @@ function compileLookupVerb(
     ...(lookup.toolDescription ? { doc: lookup.toolDescription } : {}),
     params: [nameParam],
     output: { formatters: lookupFormatters(lookup, prefixes) },
-    examples: [{ cmd: `pragma ${noun} lookup <name>` }],
+    examples: [{ cmd: `${BIN_NAME} ${noun} lookup <name>` }],
     ...(lookup.disclosure
       ? { disclosure: disclosureSpec(lookup.disclosure) }
       : {}),
@@ -214,7 +301,7 @@ function compileLookupVerb(
 function compileSampleVerb(
   lookup: PackLookup,
   noun: string,
-  source: string,
+  source: StorySource,
   prefixes: Readonly<Record<string, string>>,
 ): VerbSpec {
   const defaultCount = sampleDefaultCount(lookup);
@@ -241,8 +328,8 @@ function compileSampleVerb(
     params: countParam,
     output: { formatters: sampleFormatters(lookup, noun, prefixes) },
     examples: [
-      { cmd: `pragma ${noun} sample` },
-      ...(config?.fixedCount ? [] : [{ cmd: `pragma ${noun} sample 3` }]),
+      { cmd: `${BIN_NAME} ${noun} sample` },
+      ...(config?.fixedCount ? [] : [{ cmd: `${BIN_NAME} ${noun} sample 3` }]),
     ],
     capability: READ_CAPABILITY,
     run: (params: Record<string, unknown>, rt: PragmaRuntime) =>
@@ -284,9 +371,15 @@ function projectFilters(
         name: filter.param,
         doc,
         values: [...filter.values],
+        repeatable: true,
       } satisfies ParamSpec;
     }
-    return { kind: "string", name: filter.param, doc } satisfies ParamSpec;
+    return {
+      kind: "string",
+      name: filter.param,
+      doc,
+      repeatable: true,
+    } satisfies ParamSpec;
   });
 }
 

package/src/kernel/packs/disclosure.test.ts

@@ -66,13 +66,16 @@ const PACK: PackDefinition = {
 };
 
 const lookupVerb = () =>
-  compilePack(PACK, "test:widget", PREFIXES).find(
+  compilePack(PACK, { label: "test:widget", origin: "package" }, PREFIXES).find(
     (v) => verbKey(v.path) === "widget lookup",
   );
 
 async function lookupAt(
   detail?: "summary" | "standard" | "detailed",
-  config?: { configDetail: string; detailOrigin: "global" | "project" },
+  config?: {
+    configDetail: "summary" | "standard" | "detailed";
+    detailOrigin: "global" | "project";
+  },
 ): Promise<Record<string, unknown>> {
   const { rt } = await buildFixtureRuntime({
     ttl: TTL,

package/src/kernel/packs/disclosure.ts

@@ -18,8 +18,8 @@
  */
 
 import { DETAIL_LEVELS } from "../../constants.js";
-import { resolveDetail } from "../render/disclosure.js";
-import type { PragmaRuntime } from "../runtime/types.js";
+import { resolveDetail } from "../render/index.js";
+import type { PragmaRuntime } from "../runtime/index.js";
 import type { PackDisclosure, PackExpand, PackField } from "./types.js";
 
 /** The canonical level names, lowest → highest. */

package/src/kernel/packs/graphql/buildLookupDocument.ts

@@ -23,7 +23,7 @@
  * stays off the storeless fast path).
  */
 
-import { PragmaError } from "../../error/PragmaError.js";
+import { PragmaError } from "../../error/index.js";
 import { activeExpands, activeFields } from "./../sparql/buildLookupQuery.js";
 import type {
   PackExpand,

package/src/kernel/packs/graphql/fetchGraphqlLookup.ts

@@ -14,8 +14,8 @@
  * composed only from validated pack terms and compiled schema names.
  */
 
-import { PragmaError } from "../../error/PragmaError.js";
-import type { PragmaRuntime } from "../../runtime/types.js";
+import { cliRecovery, PragmaError } from "../../error/index.js";
+import type { PragmaRuntime } from "../../runtime/index.js";
 import type { PackChildRow, PackEntity, PackLookup } from "../types.js";
 import {
   buildLookupDocument,
@@ -55,12 +55,12 @@ export async function fetchGraphqlLookup(
       .map((error) => error.message)
       .join("; ");
     throw PragmaError.storeUnavailable(`GraphQL lookup failed: ${messages}`, {
-      recovery: {
-        message: "Check the loaded ontology and namespaces.",
-        // `graph inspect` needs a <uri>; `ontology list` is runnable as-is.
-        cli: "pragma ontology list",
-        mcp: { tool: "ontology_list" },
-      },
+      // `graph inspect` needs a <uri>; `ontology list` is runnable as-is.
+      recovery: cliRecovery(
+        "ontology list",
+        "Check the loaded ontology and namespaces.",
+        { tool: "ontology_list" },
+      ),
     });
   }
 
@@ -71,11 +71,11 @@ export async function fetchGraphqlLookup(
     // ontology). That is a runtime not-found, not an unavailable store (exit 3).
     throw new PragmaError({
       code: "ENTITY_NOT_FOUND",
-      message: `Could not resolve <${entityUri}> — its rdf:type may be missing from the ontology.`,
-      recovery: {
-        message: "Inspect the entity's triples to check its rdf:type.",
-        cli: `pragma graph inspect ${entityUri}`,
-      },
+      message: `Cannot resolve <${entityUri}> — its rdf:type may be missing from the ontology.`,
+      recovery: cliRecovery(
+        `graph inspect ${entityUri}`,
+        "Inspect the entity's triples to check its rdf:type.",
+      ),
     });
   }
 

package/src/kernel/packs/graphql/index.ts

@@ -0,0 +1,20 @@
+/**
+ * The GraphQL lookup path — what a `source: "graphql"` pack story executes
+ * once SPARQL has resolved its name to an entity IRI.
+ *
+ * The three files here are one function split for testability, not three
+ * services: the naming rules derive schema field names from the RDF properties
+ * a pack declares, the document generator turns a lookup declaration plus
+ * those names into the single query to run, and the fetcher executes it and
+ * unwraps the Relay envelope into the same flat entity shape the SPARQL path
+ * produces. Only the last of those is something a caller does.
+ *
+ * So the barrel is one export, and the narrowness is the point. The document
+ * generator's contract is that the entity IRI travels as a query VARIABLE and
+ * never as interpolated text, and that a document is composed only from
+ * validated pack terms and compiled schema names. Handing out the generator on
+ * its own would hand out a way to build a document and execute it by some
+ * other route; handing out the fetcher hands out the guarantee with it.
+ */
+
+export { fetchGraphqlLookup } from "./fetchGraphqlLookup.js";