@canonical/pragma-cli 0.34.0 → 0.35.0

package/src/kernel/error/PragmaError.ts

@@ -1,3 +1,4 @@
+import { ISSUES_URL } from "../../constants.js";
 import type { ErrorCode, PragmaErrorData, Recovery } from "./types.js";
 
 /**
@@ -168,13 +169,14 @@ class PragmaError extends Error {
    * Factory: unexpected internal failure (a bug).
    *
    * @param reason - Description of the internal error.
-   * @returns PragmaError with code `INTERNAL_ERROR` and a "please report" hint.
+   * @returns PragmaError with code `INTERNAL_ERROR` and a report-this hint
+   *   naming the issue tracker.
    */
   static internalError(reason: string): PragmaError {
     return new PragmaError({
       code: "INTERNAL_ERROR",
       message: `Internal error: ${reason}`,
-      recovery: { message: "Please report this issue." },
+      recovery: { message: `Report this issue at ${ISSUES_URL}.` },
     });
   }
 }

package/src/kernel/error/constants.ts

@@ -25,11 +25,13 @@ const ERROR_CODES = [
   "CONFIG_ERROR",
   "INTERNAL_ERROR",
   // A runtime condition that is NOT a bug and NOT a usage mistake, so it must
-  // NOT collapse to INTERNAL_ERROR's "please report this issue": a capability
-  // genuinely unavailable in this build/environment (`create package` /
-  // `create application` in the compiled binary, whose generators read their
-  // templates from disk rather than through the embedded manifest —
-  // `create component` reads through it and runs), OR an external command
+  // NOT collapse to INTERNAL_ERROR's "report this issue": a capability
+  // genuinely unavailable in this environment (`create` refusing when its
+  // lazily-imported generator runtime cannot be loaded at all — the
+  // module-not-found backstop in `capabilities/create/create.verb.ts`, which
+  // means the `@canonical/summon-*` dependencies could not be resolved, i.e. a
+  // broken or pruned install; every declared generator otherwise runs
+  // everywhere), OR an external command
   // that RAN and failed for a fixable environment reason (a denied global
   // `npm i -g`, a network/registry failure — see `shared/assertExecOk`). Both
   // carry an actionable recovery and map to the generic runtime exit 1.

package/src/kernel/error/fromTaskError.ts

@@ -6,7 +6,7 @@
  * `MISSING_REQUIRED_ANSWER` / `GENERATOR_INVALID_ANSWER` for absent or invalid
  * non-interactive answers. `runTask` rethrows these as a `TaskExecutionError`
  * carrying `.code`. Without a bridge the CLI/MCP boundary collapses every
- * non-`PragmaError` to INTERNAL_ERROR + "please report this issue" — telling a
+ * non-`PragmaError` to INTERNAL_ERROR + "report this issue" — telling a
  * user to file a bug for cancelling their own scaffold.
  *
  * The codes are matched as STRING LITERALS, never imported from summon-core, so
@@ -62,15 +62,37 @@ export function isInterruption(error: unknown): boolean {
   return taskErrorCode(error) === TASK_INTERRUPTED;
 }
 
+/**
+ * The {@link PragmaError} a task failure CARRIES, if any. A task-layer failure
+ * raised through the failure channel (`failPragma` — so an enclosing `recover`
+ * such as setup's per-step isolation can catch it, which a synchronous throw
+ * bypasses) stores the original PragmaError as the TaskError's `cause`;
+ * `runTask` then wraps that TaskError in a `TaskExecutionError` whose
+ * `taskError` carries it. Walk both wrappers (bounded — the shapes nest at
+ * most a few levels) so the boundary recovers the ORIGINAL error with its
+ * code, message, and recovery intact.
+ */
+function carriedPragmaError(error: unknown): PragmaError | undefined {
+  let current: unknown = error;
+  for (let depth = 0; depth < 4 && current !== undefined; depth += 1) {
+    if (current instanceof PragmaError) return current;
+    const record = current as { taskError?: unknown; cause?: unknown } | null;
+    current = record?.taskError ?? record?.cause;
+  }
+  return undefined;
+}
+
 /**
  * Coerce a thrown value into a {@link PragmaError} for the CLI/MCP boundary,
- * bridging summon-core task-error codes: absent/invalid non-interactive answers
- * become INVALID_INPUT (a usage error, exit 2); a `PragmaError` passes through
- * unchanged; everything else stays INTERNAL_ERROR. Cancellation is handled
- * separately by {@link isCancellation} as a clean, non-error outcome.
+ * bridging summon-core task-error codes: a `PragmaError` (direct, or carried
+ * through the task failure channel as a TaskError `cause`) passes through
+ * unchanged; absent/invalid non-interactive answers become INVALID_INPUT (a
+ * usage error, exit 2); everything else stays INTERNAL_ERROR. Cancellation is
+ * handled separately by {@link isCancellation} as a clean, non-error outcome.
  */
 export function asPragmaError(error: unknown): PragmaError {
-  if (error instanceof PragmaError) return error;
+  const carried = carriedPragmaError(error);
+  if (carried !== undefined) return carried;
   const message = error instanceof Error ? error.message : String(error);
   const code = taskErrorCode(error);
   if (code !== undefined && ANSWER_USAGE_CODES.has(code)) {

package/src/kernel/error/recovery.ts

@@ -10,6 +10,20 @@
  * that were actually wrong were raw `cli:` object literals that never reached
  * this function at all. `kernel/copy.test.ts` covers those, at the position.
  *
+ * A THIRD authoring route is also legal and reached by NEITHER guard: a `cli`
+ * DERIVED from the program's own name at the call site. One site does this —
+ * the create mount (`capabilities/create/mount.ts`,
+ * `[...detail.chain, suggestion].join(" ")`), whose `chain[0]` is the root
+ * Commander program's name, `BIN_NAME` by wiring. It bypasses
+ * {@link cliRecovery}, and the position rule is structurally blind to it (it
+ * flags QUOTED literals containing the distribution's name, never a computed
+ * expression) — so D5 holds there by derivation, and the derivation is pinned
+ * where the value surfaces: `createGrammar.test.ts` COMPOSES its expected
+ * `cli` from {@link RECOVERY_CLI_PREFIX}, so a renamed root program reddens
+ * the cell naming the constant. (A separate `startsWith` assertion cannot
+ * pin it — behind an exact pin of the same value it has no reachable
+ * failing input.)
+ *
  * `kernel/packs/schema.ts` holds a user-authored pack's `emptyRecovery.cli` to
  * the same shape from the other side — it must NOT carry a prefix, because the
  * consuming distribution's renderer supplies one.

package/src/kernel/error/renderError.ts

@@ -7,6 +7,7 @@
  * whichever transport they use.
  */
 
+import type { OutputFormat } from "../../constants.js";
 import type { PragmaError } from "./PragmaError.js";
 import { serializeError } from "./serialize.js";
 
@@ -98,4 +99,44 @@ function renderErrorJson(error: PragmaError): string {
   return JSON.stringify({ ok: false, error: serializeError(error) });
 }
 
-export { renderErrorJson, renderErrorLlm, renderErrorPlain };
+/**
+ * Render an error for an EXPLICITLY requested machine format, or decline.
+ *
+ * The ONE machine-format envelope decision for the usage-error surfaces —
+ * `handleProgramError`'s Commander parse failures (the unknown-command arm
+ * included), the create mount's projection usage-error writer, and
+ * `writeRefusal`: an explicit `--format json` renders the failure envelope,
+ * an explicit `--format llm` the condensed Markdown form, and anything else
+ * returns `undefined` so the caller keeps its raw default bytes.
+ * Auto-detected llm is excluded by construction — `parseGlobalFlags` leaves
+ * `format` at `"plain"` under auto-detection and records `autoLlm`
+ * separately — so an inferred output mode can never move the default
+ * (cross-CLI parity) bytes. Hoisted so the gate and the renderer pick exist
+ * ONCE instead of drifting per call site (they had already split: sites
+ * gated on json only vs json|llm, and `--format llm` enveloped some members
+ * of the usage-error class while siblings stayed raw). Deliberately NOT
+ * routed through here: the always-render sites with no raw arm to arbitrate
+ * — `renderStartupError`, bin.ts's bad-`--format` rejection,
+ * `handleProgramError`'s non-Commander fallthrough, and dispatch's
+ * `renderError` (which deliberately includes autoLlm for run errors) — each
+ * picks a PragmaError renderer directly.
+ *
+ * @param error - The structured error to render.
+ * @param format - The parsed global `--format` value.
+ * @returns The rendered string for `json`/`llm`; `undefined` for `plain`.
+ */
+function renderErrorForFormat(
+  error: PragmaError,
+  format: OutputFormat,
+): string | undefined {
+  if (format === "json") return renderErrorJson(error);
+  if (format === "llm") return renderErrorLlm(error);
+  return undefined;
+}
+
+export {
+  renderErrorForFormat,
+  renderErrorJson,
+  renderErrorLlm,
+  renderErrorPlain,
+};

package/src/kernel/error/types.ts

@@ -17,7 +17,10 @@ type ErrorCode = (typeof ERROR_CODES)[number];
  * `cli` — when present — is the command as a user would type it: this
  * distribution's own bin name (`RECOVERY_CLI_PREFIX`) plus a grammar path (D5).
  * `cliRecovery` takes the path alone and prepends the prefix, so there is no
- * assertion to make — see the docblock on `error/recovery.ts`.
+ * assertion to make; the one COMPUTED producer (the create mount) derives
+ * the prefix from the program's own name, pinned by a test expectation
+ * COMPOSED from `RECOVERY_CLI_PREFIX` — the routes are enumerated in the
+ * docblock on `error/recovery.ts`.
  */
 interface Recovery {
   /** Human-readable recovery guidance. */
@@ -54,6 +57,23 @@ interface PragmaErrorData {
 interface ErrorPayload {
   readonly code: ErrorCode;
   readonly message: string;
+  /**
+   * Fuzzy-matched alternative names — BARE candidate tokens the caller can
+   * substitute for the one token it typed (a verb, a tree segment), never
+   * full invocations. The FUZZY tiers serialize this one convention:
+   * bin.ts's unknown-command tier emits the candidate name (`block`) and
+   * the create mount's unknown-segment tier the candidate segment
+   * (`react`); the corrected full command line, when one is shown, lives
+   * in the default prose did-you-mean rendering, not in this field. An
+   * excess positional is NOT a fuzzy match — its matched operand may be
+   * the very token its message calls unexpected, or one the message never
+   * names — so that producer omits this field entirely and instead ships
+   * the runnable corrected command as `recovery.cli` WHEN an operand
+   * names a sibling or child segment resolving to a declared runnable
+   * leaf (the prose did-you-mean condition, narrowed to runnable — a
+   * matched namespace keeps the prose hint but ships no recovery); with
+   * no runnable match the envelope carries neither optional field.
+   */
   readonly suggestions?: readonly string[];
   readonly recovery?: Recovery;
   readonly validOptions?: readonly string[];

package/src/kernel/index.ts

@@ -0,0 +1,26 @@
+/**
+ * The kernel's own top-level declarations — the small set of facts that belong
+ * to no sub-domain because every sub-domain may need them.
+ *
+ * This is NOT a facade over the kernel. `kernel/` is a namespace of domains,
+ * each of which keeps its own barrel (`config/`, `render/`, `runtime/`,
+ * `packs/`, `error/`, `spec/`, `completion/`, `project/…`); a consumer wanting
+ * one of those imports that domain's barrel, not this one. What lives here is
+ * only what sits directly in `kernel/`, and the bar for putting a file there
+ * is high: it must be a declaration the kernel makes about itself rather than
+ * a step in any one pipeline.
+ *
+ * Today that is the declared vocabulary — the distribution's mapping from the
+ * roles the CLI knows (a prompt, a resource) onto the RDF terms that actually
+ * carry them in the active graph. It is parsed once at module load and read
+ * from the prompt capability, the MCP prompt source, and the pack index
+ * builder, none of which owns it and any of which would otherwise hardcode
+ * someone else's IRIs.
+ *
+ * The copy-gate rule table (`copy.ts`) deliberately stays off this barrel. It
+ * is reviewed data consumed by its own test and by nothing else at runtime;
+ * exporting it here would advertise a runtime API the gate does not have.
+ */
+
+export type { DeclaredVocabulary } from "./vocabulary.js";
+export { VOCABULARY } from "./vocabulary.js";

package/src/kernel/packs/collect.ts

@@ -24,11 +24,11 @@
  * costs nothing on `--help`/`__complete`.
  */
 
-import type { ConfigLayers } from "../config/types.js";
-import { PragmaError } from "../error/PragmaError.js";
+import type { ConfigLayers } from "../config/index.js";
+import { PragmaError } from "../error/index.js";
 import type { PackStoryRecord } from "../runtime/graphpack/stories.js";
-import type { CapabilityModule } from "../spec/types.js";
-import { compilePack } from "./compile.js";
+import type { CapabilityModule } from "../spec/index.js";
+import { compileStoryModule } from "./compile.js";
 import { parsePackDefinition } from "./schema.js";
 import type { PackDefinition, PackEntry } from "./types.js";
 import { assertUniqueVerbs } from "./uniqueness.js";
@@ -172,16 +172,14 @@ export function assembleEffectiveModules(
   // story both on its pack and at the top level is a refinement, not an error.
   const dynamic = new Map<string, CapabilityModule>();
   for (const entry of packageStories) {
-    dynamic.set(entry.definition.noun, {
-      name: entry.definition.noun,
-      story: true,
-      verbs: compilePack(
+    dynamic.set(
+      entry.definition.noun,
+      compileStoryModule(
         entry.definition,
         { label: entry.source, origin: "package" },
         prefixes,
       ),
-      colophon: entry.definition.colophon,
-    });
+    );
   }
   for (const tier of tiers) {
     const seen = new Set<string>();
@@ -201,16 +199,14 @@ export function assembleEffectiveModules(
         );
       }
       seen.add(definition.noun);
-      dynamic.set(definition.noun, {
-        name: definition.noun,
-        story: true,
-        verbs: compilePack(
+      dynamic.set(
+        definition.noun,
+        compileStoryModule(
           definition,
           { label: "config", origin: "config" },
           prefixes,
         ),
-        colophon: definition.colophon,
-      });
+      );
     }
   }
 

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

@@ -11,7 +11,7 @@ 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";
@@ -383,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

@@ -15,9 +15,16 @@
  */
 
 import { BIN_NAME } from "../../constants.js";
-import type { PragmaRuntime } from "../runtime/types.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,
@@ -107,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;
@@ -287,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.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,9 +14,8 @@
  * composed only from validated pack terms and compiled schema names.
  */
 
-import { PragmaError } from "../../error/PragmaError.js";
-import { cliRecovery } from "../../error/recovery.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,
@@ -72,7 +71,7 @@ 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.`,
+      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";

package/src/kernel/packs/index.ts

@@ -0,0 +1,40 @@
+/**
+ * The packs domain — declared stories become runnable verbs.
+ *
+ * One pipeline runs end to end inside this folder: a JSON pack declaration is
+ * parsed and validated, compiled into `VerbSpec`s, and given run bodies that
+ * resolve entities out of the graph and formatters that render them. The
+ * intermediate stages — the schema parser, the query/render/run-body builders,
+ * the entity resolver, the sampler, the glob expander — are steps in that
+ * pipeline, not services, and they stay off this barrel: a caller reaching for
+ * one of them is a caller reassembling the pipeline by hand, and the whole
+ * point of compiling a pack once is that nobody has to.
+ *
+ * What crosses the boundary is the pipeline's ends and the contracts naming
+ * them. `compilePack` is the entry the distribution and the config-story path
+ * both take. `validateStories` and `loadEffectiveModules` are the two ways
+ * third-party stories are admitted — the first screens records and reports
+ * every problem (which is how `doctor` reports a story the CLI drops rather
+ * than letting it vanish), the second is the full load the MCP server and the
+ * `capabilities` verb take. `resolvePackDetail` and `resolveUri` are the two
+ * decisions a pack's own reads defer to the runtime, and `verbKey` is the
+ * identity function every surface keys a verb by.
+ *
+ * `loadEffectiveModules` reads config and the answering pack behind DYNAMIC
+ * imports so a bare `--help` never pays for either; consumers reach it lazily
+ * today for exactly that reason, and routing it through this barrel statically
+ * would put the config reader back on the fast path.
+ */
+
+export type { StoryProblem } from "./collect.js";
+export { loadEffectiveModules, validateStories } from "./collect.js";
+export { compilePack } from "./compile.js";
+export { resolvePackDetail } from "./disclosure.js";
+export { resolveUri } from "./iri.js";
+export type {
+  PackDefinition,
+  PackRow,
+  StorySource,
+} from "./types.js";
+export { distributionSource } from "./types.js";
+export { verbKey } from "./uniqueness.js";