@canonical/pragma-cli 0.33.0 → 0.34.0

package/src/kernel/project/mcp/prompts/prompts.test.ts

@@ -1,13 +1,18 @@
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { GetPromptRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { afterEach, describe, expect, it } from "vitest";
+import { CONVENTIONS } from "../../../../capabilities/capabilities/catalog.js";
 import { capabilities } from "../../../../capabilities/index.js";
 import type { McpHarness } from "../../../../testing/helpers/projectMcp.js";
 import { projectMcp } from "../../../../testing/helpers/projectMcp.js";
+import type { PragmaRuntime } from "../../../runtime/types.js";
+import { emitSurface } from "../../../spec/emitSurface.js";
 import type { CapabilityModule } from "../../../spec/types.js";
 import { buildInstructions, INSTRUCTIONS_MAX_CHARS } from "../instructions.js";
 import { fillTemplate, promptProvider } from "./provider.js";
+import { readPrompts } from "./source.js";
 
 const freshCwd = (): string => mkdtempSync(join(tmpdir(), "pragma-prompts-"));
 
@@ -39,14 +44,25 @@ describe("instructions — handshake orientation (PROTECTED)", () => {
     );
   });
 
-  it("derives its conventions from the shared catalog source", () => {
-    // The system convention string is authored once (capabilities/catalog.ts);
-    // instructions must carry it verbatim so the two can never diverge.
-    expect(buildInstructions(capabilities)).toContain(
-      "design-system knowledge graph",
+  it("opens with the shared catalog's conventions, verbatim and once", () => {
+    // The conventions are authored once (capabilities/catalog.ts); instructions
+    // must OPEN with them, so a second hand-written preamble cannot creep back
+    // in and drift from the `capabilities` tool the same handshake carries.
+    expect(buildInstructions(capabilities).startsWith(CONVENTIONS.system)).toBe(
+      true,
     );
   });
 
+  it("quotes the resource templates the MCP surface actually advertises", () => {
+    // The `pragma:` scheme is covenant-frozen protocol identity
+    // (surface.v2.json). The orientation DERIVES it from the emitted surface
+    // instead of hand-copying it, so the two cannot disagree.
+    const { resources } = emitSurface(capabilities).mcpSurface;
+    expect(resources.length).toBeGreaterThan(0);
+    const text = buildInstructions(capabilities);
+    for (const template of resources) expect(text).toContain(template);
+  });
+
   it("states the plan-first/confirm convention in the orientation (D2)", () => {
     // The confirm gate must be surfaced at handshake, not discovered by an agent
     // tripping it. Same single source as the `capabilities` tool's conventions.
@@ -91,6 +107,105 @@ describe("MCP handshake — capabilities advertised (PROTECTED)", () => {
   });
 });
 
+/** A runtime whose SPARQL facade always fails with `message`. */
+function createFailingRuntime(message: string): PragmaRuntime {
+  return {
+    query: {
+      sparql: () => Promise.reject(new Error(message)),
+    },
+  } as unknown as PragmaRuntime;
+}
+
+/** Every field at the default layer — the embedded pack answers, so the store IS available. */
+const DEFAULT_ORIGINS = {
+  tier: "default",
+  channel: "default",
+  detail: "default",
+  packs: "default",
+  stories: "default",
+  prefixes: "default",
+} as const;
+
+/**
+ * The same failing facade, wearing the shape `promptProvider.register` needs:
+ * a cwd whose store is AVAILABLE (so `guardStore` passes and the read is what
+ * fails) plus a `loadConfig` the readiness check can resolve.
+ */
+function createFailingProviderRuntime(
+  cwd: string,
+  message: string,
+): PragmaRuntime {
+  return {
+    cwd,
+    loadConfig: async () => ({
+      config: { channel: "normal" as const },
+      origins: DEFAULT_ORIGINS,
+      global: { path: "/nonexistent", exists: false },
+      project: { exists: false },
+    }),
+    query: { sparql: () => Promise.reject(new Error(message)) },
+  } as unknown as PragmaRuntime;
+}
+
+describe("native prompts/get — a failed read reaches the agent as one", () => {
+  it("carries the machine code and recovery, not a bare Error", async () => {
+    // The native surface signals failure by THROWING, so a read that fails must
+    // be projected the way the resource browser projects its own — with `code`
+    // and `recovery` in the JSON-RPC `data`. Otherwise the store diagnosis is
+    // lost between `prompt_lookup` (which envelopes it) and `prompts/get`.
+    const handlers = new Map<unknown, (request: unknown) => Promise<unknown>>();
+    const stubServer = {
+      server: {
+        registerCapabilities: () => {},
+        setRequestHandler: (
+          schema: unknown,
+          handler: (request: unknown) => Promise<unknown>,
+        ) => {
+          handlers.set(schema, handler);
+        },
+      },
+    };
+    await promptProvider.register(
+      stubServer as never,
+      createFailingProviderRuntime(freshCwd(), "Prefix not found: ds"),
+    );
+
+    const get = handlers.get(GetPromptRequestSchema);
+    expect(get).toBeDefined();
+    await expect(
+      get?.({ params: { name: "build-a-block" } }),
+    ).rejects.toMatchObject({
+      data: {
+        code: "STORE_UNAVAILABLE",
+        recovery: { mcp: { tool: "sources_update" } },
+      },
+    });
+  });
+});
+
+describe("readPrompts — a failed read is never an empty graph", () => {
+  it("reports an unbound prefix as a store that cannot answer, not as no prompts", async () => {
+    // A pack whose store does not know the declared prompt namespace cannot
+    // answer, and the actionable form of that is STORE_UNAVAILABLE with the
+    // build command — not a silent zero-prompt listing.
+    await expect(
+      readPrompts(createFailingRuntime("Prefix not found: ds")),
+    ).rejects.toMatchObject({
+      code: "STORE_UNAVAILABLE",
+      recovery: { mcp: { tool: "sources_update" } },
+    });
+  });
+
+  it("propagates a query failure instead of returning no prompts", async () => {
+    // The exact defect a bare `catch {}` here caused: a malformed declaration
+    // becomes a parse error, the parse error becomes `[]`, and the user is told
+    // the distribution ships no prompts. It must surface as a failure.
+    await expect(
+      readPrompts(createFailingRuntime("SPARQL syntax error at line 2")),
+    ).rejects.toThrow(/syntax error/);
+  });
+});
+
 describe("fillTemplate — argument substitution", () => {
   it("replaces {{arg}} placeholders and leaves unknowns intact", () => {
     expect(

package/src/kernel/project/mcp/prompts/provider.ts

@@ -12,14 +12,17 @@
  * module — never pulls the SDK types onto the `--help`/`__complete` fast path.
  *
  * Both handlers open with a STORELESS cold-store pre-check ({@link
- * checkStoreAvailable}) so the native surface converges with the store-backed
- * `prompt_list` tool: a cold store surfaces the SAME `STORE_UNAVAILABLE` +
- * `sources_update` recovery here as the tool's `needsStore` guard raises, rather
- * than a silent `[]` (list) or a bogus "not found" (get) that masks the cold
- * store. When the store is available (including the embedded fallback) both
- * handlers behave exactly as before.
+ * checkStoreAvailable}), and the store-backed `get` projects any read failure
+ * through {@link mcpErrorFrom}, so the native surface converges with the
+ * store-backed `prompt_list` tool: a cold store — or a store that cannot answer
+ * the prompt query — surfaces the SAME machine code and recovery here as the
+ * tool envelope carries, rather than a silent `[]` (list) or a bogus "not found"
+ * (get) that masks it. When the store is available (including the embedded
+ * fallback) both handlers behave exactly as before.
  */
 
+import { asPragmaError } from "../../../error/fromTaskError.js";
+import { resolveSources } from "../../../runtime/resolveSources.js";
 import { checkStoreAvailable } from "../../../runtime/storeReadiness.js";
 import type { McpPromptProvider } from "../../../spec/types.js";
 import { mcpErrorFrom } from "../mcpError.js";
@@ -68,7 +71,9 @@ export const promptProvider: McpPromptProvider = {
     server.server.setRequestHandler(ListPromptsRequestSchema, async () => {
       await guardStore();
       return {
-        prompts: listPromptSummaries(runtime).map((prompt) => ({
+        prompts: listPromptSummaries(
+          resolveSources(await runtime.loadConfig(), runtime.cwd),
+        ).map((prompt) => ({
           name: prompt.name,
           ...(prompt.description ? { description: prompt.description } : {}),
         })),
@@ -78,7 +83,16 @@ export const promptProvider: McpPromptProvider = {
     server.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
       await guardStore();
       const { name, arguments: args } = request.params;
-      const entry = await readPrompt(runtime, name);
+      // The read can fail (a store that cannot answer the prompt query), and a
+      // native surface signals that by THROWING — so project it the way the
+      // resource browser does, carrying the machine code and the recovery into
+      // the JSON-RPC `data` instead of letting a bare Error reach the agent.
+      let entry: Awaited<ReturnType<typeof readPrompt>>;
+      try {
+        entry = await readPrompt(runtime, name);
+      } catch (error) {
+        throw mcpErrorFrom(asPragmaError(error), { McpError, ErrorCode });
+      }
       if (!entry) {
         // Reached only when the store IS available — a genuine miss, not a cold
         // store (which `guardStore` already surfaced as STORE_UNAVAILABLE).

package/src/kernel/project/mcp/prompts/source.ts

@@ -1,27 +1,44 @@
 /**
- * The ONE source of truth for prompt entities — read TWO ways from ONE KG type
- * (`ds:Prompt`), so the native MCP `prompts/*` surface and the covenant
- * `prompt_list`/`prompt_lookup` content tools never diverge.
+ * The ONE source of truth for prompt entities — read TWO ways from ONE KG type,
+ * so the native MCP `prompts/*` surface and the covenant `prompt_list`/
+ * `prompt_lookup` content tools never diverge.
  *
- * A `ds:Prompt` is authored as:
- *   ds:prompt.x a ds:Prompt ;
- *     rdfs:label "x" ;                 # the prompt NAME (indexed → storeless list)
- *     rdfs:comment "…" ;               # the description (indexed)
- *     ds:promptBody "…" ;              # the template body (store-backed)
- *     ds:promptArgument [ ds:argName "a" ; rdfs:comment "…" ; ds:argRequired true ] .
+ * The type and its four properties are DECLARED by the distribution
+ * (`kernel/vocabulary.ts`), not named here — this module knows the shape of a
+ * prompt, not whose prompt it is. With `<type>`/`<body>`/`<argument>`/
+ * `<argName>`/`<argRequired>` standing for the declared terms, a prompt entity
+ * is authored as:
+ *
+ *   ex:prompt.x a <type> ;
+ *     rdfs:label "x" ;               # the prompt NAME (indexed → storeless list)
+ *     rdfs:comment "…" ;             # the description (indexed)
+ *     <body> "…" ;                   # the template body (store-backed)
+ *     <argument> [ <argName> "a" ; rdfs:comment "…" ; <argRequired> true ] .
  *
  * Listing is STORELESS (over the pack index — `label`/`description` are indexed),
  * so `prompts/list` and native discovery cost nothing until a `get`. A `get`
- * (body + arguments) is STORE-BACKED through the SPARQL facade — identical
- * laziness to the resource browser (list storeless, read store-backed). An empty
- * or missing index yields zero prompts (never a store boot on the list path).
+ * (body + arguments) is STORE-BACKED through `runSelect` — identical laziness to
+ * the resource browser (list storeless, read store-backed). An empty or missing
+ * index yields zero prompts (never a store boot on the list path).
+ *
+ * The store-backed reads route through `runSelect` and DO NOT catch. A cold
+ * store is already refused upstream — the tools are `needsStore`, and the native
+ * provider calls `guardStore()` first — so a swallowed failure here could only
+ * ever hide a real one, reporting a broken query as an empty graph. `runSelect`
+ * classifies an unbound prefix as STORE_UNAVAILABLE with its `sources update`
+ * recovery and lets everything else propagate.
  */
 
 import { readPackIndex } from "../../../completion/entitySource.js";
+import { runSelect } from "../../../packs/sparql/runSelect.js";
+import type { PackRow } from "../../../packs/types.js";
+import { distributionSource } from "../../../packs/types.js";
+import type { SourcesDecision } from "../../../runtime/resolveSources.js";
 import type { PragmaRuntime } from "../../../runtime/types.js";
+import { VOCABULARY } from "../../../vocabulary.js";
 
-/** The KG type (prefixed) every prompt entity carries. */
-export const PROMPT_TYPE = "ds:Prompt";
+/** The declared prompt terms this module reads the graph with. */
+const PROMPT = VOCABULARY.prompt;
 
 /** One declared argument of a prompt template. */
 export interface PromptArgument {
@@ -42,27 +59,29 @@ export interface PromptEntry extends PromptSummary {
   readonly arguments: readonly PromptArgument[];
 }
 
-/** Whether an index entity is a `ds:Prompt` (primary type or any type). */
+/** Whether an index entity carries the prompt type (primary type or any type). */
 function isPromptEntity(entity: {
   type: string;
   types?: readonly string[];
 }): boolean {
   return (
-    entity.type === PROMPT_TYPE ||
-    (Array.isArray(entity.types) && entity.types.includes(PROMPT_TYPE))
+    entity.type === PROMPT.type ||
+    (Array.isArray(entity.types) && entity.types.includes(PROMPT.type))
   );
 }
 
 /**
- * List prompt summaries STORELESSLY from the active pack index. Returns `[]`
- * when no index is reachable or the index carries no prompts — never boots the
- * store.
+ * List prompt summaries STORELESSLY from the index of the pack the boot decision
+ * names. Returns `[]` when no index is reachable (including an unavailable
+ * store) or the index carries no prompts — never boots the store.
  *
- * @param rt - The per-invocation runtime (for `cwd`).
+ * @param decision - The boot decision from `resolveSources`.
  * @returns Prompt summaries (name from the entity label, sorted by name).
  */
-export function listPromptSummaries(rt: PragmaRuntime): PromptSummary[] {
-  const index = readPackIndex(rt.cwd);
+export function listPromptSummaries(
+  decision: SourcesDecision,
+): PromptSummary[] {
+  const index = readPackIndex(decision);
   if (!index || !Array.isArray(index.entities)) return [];
   const summaries: PromptSummary[] = [];
   for (const entity of index.entities) {
@@ -76,21 +95,6 @@ export function listPromptSummaries(rt: PragmaRuntime): PromptSummary[] {
   return summaries.sort((a, b) => a.name.localeCompare(b.name));
 }
 
-/**
- * Rows the prompt SELECT returns (one per argument; body repeats). The facade's
- * SELECT bindings are keyed by variable name with PLAIN string values (an
- * unbound OPTIONAL variable is simply absent) — the same shape `runSelect`
- * consumes.
- */
-interface PromptRow {
-  readonly name?: string;
-  readonly description?: string;
-  readonly body?: string;
-  readonly argName?: string;
-  readonly argDescription?: string;
-  readonly argRequired?: string;
-}
-
 /** The SPARQL that materializes prompts (all, or one when `label` is bound). */
 function promptQuery(labelFilter?: string): string {
   const filter = labelFilter
@@ -98,24 +102,28 @@ function promptQuery(labelFilter?: string): string {
     : "";
   return [
     "SELECT ?name ?description ?body ?argName ?argDescription ?argRequired WHERE {",
-    "  ?prompt a ds:Prompt ;",
+    `  ?prompt a ${PROMPT.type} ;`,
     "          rdfs:label ?name .",
     filter,
     "  OPTIONAL { ?prompt rdfs:comment ?description }",
-    "  OPTIONAL { ?prompt ds:promptBody ?body }",
+    `  OPTIONAL { ?prompt ${PROMPT.body} ?body }`,
     "  OPTIONAL {",
-    "    ?prompt ds:promptArgument ?arg .",
-    "    ?arg ds:argName ?argName .",
+    `    ?prompt ${PROMPT.argument} ?arg .`,
+    `    ?arg ${PROMPT.argName} ?argName .`,
     "    OPTIONAL { ?arg rdfs:comment ?argDescription }",
-    "    OPTIONAL { ?arg ds:argRequired ?argRequired }",
+    `    OPTIONAL { ?arg ${PROMPT.argRequired} ?argRequired }`,
     "  }",
     "}",
     "ORDER BY ?name ?argName",
   ].join("\n");
 }
 
-/** Fold SELECT rows (one per argument) into distinct {@link PromptEntry}s. */
-function foldPromptRows(rows: readonly PromptRow[]): PromptEntry[] {
+/**
+ * Fold SELECT rows (one per argument; the body repeats) into distinct
+ * {@link PromptEntry}s. Rows are keyed by SELECT variable name with plain string
+ * values, and an unbound OPTIONAL variable is simply absent.
+ */
+function foldPromptRows(rows: readonly PackRow[]): PromptEntry[] {
   const byName = new Map<
     string,
     { description?: string; body: string; args: Map<string, PromptArgument> }
@@ -151,27 +159,19 @@ function foldPromptRows(rows: readonly PromptRow[]): PromptEntry[] {
     .sort((a, b) => a.name.localeCompare(b.name));
 }
 
-/** Extract the SELECT binding rows from a facade query result. */
-function selectRows(result: unknown): PromptRow[] {
-  const typed = result as { type?: string; bindings?: unknown };
-  if (typed.type !== "select" || !Array.isArray(typed.bindings)) return [];
-  return typed.bindings as PromptRow[];
-}
-
 /**
- * Read every prompt entity STORE-BACKED (body + arguments). Boots the store via
- * the SPARQL facade; returns `[]` on any query failure (graceful degradation).
+ * Read every prompt entity STORE-BACKED (body + arguments).
  *
  * @param rt - The per-invocation runtime.
  * @returns The materialized prompt entries, sorted by name.
+ * @throws PragmaError STORE_UNAVAILABLE when the store cannot answer; any other
+ *   query failure propagates, so a broken read is never an empty graph.
+ * @note Impure — boots the store through `runSelect`.
  */
 export async function readPrompts(rt: PragmaRuntime): Promise<PromptEntry[]> {
-  try {
-    const result = await rt.query.sparql(promptQuery());
-    return foldPromptRows(selectRows(result));
-  } catch {
-    return [];
-  }
+  return foldPromptRows(
+    await runSelect(rt, promptQuery(), distributionSource("prompt")),
+  );
 }
 
 /**
@@ -179,16 +179,17 @@ export async function readPrompts(rt: PragmaRuntime): Promise<PromptEntry[]> {
  *
  * @param rt - The per-invocation runtime.
  * @param name - The prompt name (its `rdfs:label`).
- * @returns The materialized prompt, or `undefined` when not found.
+ * @returns The materialized prompt, or `undefined` when the graph has no such
+ *   prompt — a genuine miss, never a failed read.
+ * @throws PragmaError STORE_UNAVAILABLE when the store cannot answer; any other
+ *   query failure propagates.
+ * @note Impure — boots the store through `runSelect`.
  */
 export async function readPrompt(
   rt: PragmaRuntime,
   name: string,
 ): Promise<PromptEntry | undefined> {
-  try {
-    const result = await rt.query.sparql(promptQuery(name));
-    return foldPromptRows(selectRows(result))[0];
-  } catch {
-    return undefined;
-  }
+  return foldPromptRows(
+    await runSelect(rt, promptQuery(name), distributionSource("prompt")),
+  ).at(0);
 }

package/src/kernel/project/mcp/registerVerb.ts

@@ -12,8 +12,8 @@
 
 import { statSync } from "node:fs";
 import { isAbsolute } from "node:path";
-import { describeEffect, dryRun, type Task } from "@canonical/task";
-import { runTask } from "@canonical/task/node";
+import { describeEffect, type Task } from "@canonical/task";
+import { runPreview, runTask } from "@canonical/task/node";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
@@ -199,10 +199,29 @@ function mutateHandler(verb: VerbSpec, runtime: PragmaRuntime) {
           | Promise<Task<unknown>>,
       );
       if (preview) {
-        const plan = dryRun(task)
-          .effects.filter((effect) => effect._tag !== "Prompt")
-          .map(describeEffect);
-        return toolSuccess({ plan }, { planOnly: true, confirmRequired: true });
+        // The HONEST preview (PR7), the same interpreter `--dry-run` uses:
+        // reads are real, writes are recorded and never executed. A tool call
+        // whose confirmed run would fail now returns that error instead of a
+        // confident plan, so plan-first predicts rather than reassures.
+        const previewExec = mutationRuntime.exec ?? {};
+        try {
+          const { effects } = await runPreview(task, {
+            cwd: previewExec.cwd,
+            onEffectStart: previewExec.onEffectStart,
+            onLog: logToStderr,
+          });
+          const plan = effects
+            .filter((effect) => effect._tag !== "Prompt")
+            .map(describeEffect);
+          return toolSuccess(
+            { plan },
+            { planOnly: true, confirmRequired: true },
+          );
+        } finally {
+          // No `store.invalidate()`: a preview cannot have changed disk. Only
+          // the verb's own teardown (e.g. an interactive session) runs here.
+          await previewExec.dispose?.();
+        }
       }
       // Real execution: spread the verb's runner options (prompt handler,
       // stamping) into the interpreter; run teardown afterwards.

package/src/kernel/project/mcp/serve.ts

@@ -15,8 +15,9 @@ import { buildServer } from "./buildServer.js";
 /**
  * Build the MCP server and serve it over stdio until the transport closes.
  *
- * The server is a real invocation (not a fast path), so it merges config-declared
- * story packs into the static capabilities before projecting the tool surface.
+ * The server is a real invocation (not a fast path), so it merges the package-
+ * and config-declared story packs into the static capabilities before projecting
+ * the tool surface.
  *
  * @param modules - The static capability modules to project.
  * @param cwd - The working directory for the server's runtime.
@@ -28,7 +29,14 @@ export async function serveMcp(
 ): Promise<void> {
   const dir = cwd ?? process.cwd();
   const effective = await loadEffectiveModules(modules, dir);
-  const server = await buildServer(effective, dir);
+  // stderr only — the stdio transport owns stdout, so naming an unusable
+  // package story here is safe and reaches the host's server log.
+  for (const problem of effective.problems) {
+    process.stderr.write(
+      `Ignored story ${problem.source}: ${problem.message}\n`,
+    );
+  }
+  const server = await buildServer(effective.modules, dir);
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }

package/src/kernel/project/mcp/toolDescriptions.test.ts

@@ -2,7 +2,7 @@
  * MCP tool descriptions carry NO CLI-syntax leaks (a PR8 doc→MCP residue).
  *
  * A verb's `doc` doubles as its MCP tool description (`registerVerb`), so a doc
- * authored in CLI terms leaks flags an agent can't use — `--all-tiers`,
+ * authored in CLI terms leaks flags an agent can't use — `--category`,
  * `--dry-run`/`--yes`, or a `pragma …` shell command — into the agent-facing
  * catalog. Tool descriptions are NOT frozen in the covenant, so this is the guard
  * against the leak (and its recurrence). Storeless: listing tools never boots the
@@ -68,7 +68,11 @@ describe("MCP tool descriptions — no CLI-syntax leaks (doc→MCP residue)", ()
     const byName = new Map(
       descriptions.map((tool) => [tool.name, tool.description]),
     );
-    expect(byName.get("block_list")).not.toContain("--all-tiers");
+    // `block_list` was the original leak site (`--all-tiers`); L-OPEN-9 removed
+    // the flag AND made the description declared content (`toolDescription` in
+    // pragma.conf.ts), so the guard widens to "no CLI flag of any name" — the
+    // failure mode a re-authored story description could reintroduce.
+    expect(byName.get("block_list")).not.toMatch(/--[a-z]/);
     expect(byName.get("graph_query")).not.toContain("pragma ontology list");
     expect(byName.get("setup")).not.toMatch(/--dry-run|--yes/);
     expect(byName.get("upgrade")).not.toContain("--dry-run");

package/src/kernel/render/disclosure.ts

@@ -4,8 +4,10 @@
  * A verb renders at one of {@link DETAIL_LEVELS}. The effective level is chosen
  * from four sources, most specific first: the `--detail` flag, the resolved
  * config's `detail`, the verb's own `disclosure.default`, and finally the
- * built-in `"standard"`. Unknown values (a stale config, a typo) fall back to
- * the default rather than erroring, so output never fails on disclosure.
+ * built-in `"standard"`. Every source is validated upstream (the flag by
+ * `readDetail`, the config field by `z.enum` at load, a spec default by the
+ * pack grammar), so the fall-back here is a last belt against a source added
+ * later without validation — output never fails on disclosure.
  */
 
 import {

package/src/kernel/render/prefixes.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { embeddedManifest } from "../runtime/graphpack/embedded.js";
+import { DEFAULT_PREFIX_MAP } from "./prefixes.js";
+
+describe("DEFAULT_PREFIX_MAP", () => {
+  it("is the standard RDF vocabulary plus the distribution's declared namespaces", () => {
+    // A literal pin, not a re-derivation: the point is that editing
+    // `pragma.conf.ts`'s `prefixes` is what moves this map, and that the
+    // standard half stays kernel-owned. A reviewer reads the values here.
+    expect(DEFAULT_PREFIX_MAP).toEqual({
+      rdfs: "http://www.w3.org/2000/01/rdf-schema#",
+      owl: "http://www.w3.org/2002/07/owl#",
+      skos: "http://www.w3.org/2004/02/skos/core#",
+      ds: "https://ds.canonical.com/",
+      cs: "http://pragma.canonical.com/codestandards#",
+    });
+  });
+
+  it("binds every prefix to the same IRI the shipped pack does", () => {
+    // Two independently produced maps: this compiled-in constant, and the
+    // committed embedded artifact's harvested manifest. Neither derives the
+    // other, so agreement is a real claim.
+    //
+    // It is also the guard against a silent bundler skip. `scripts/bundle.ts`
+    // writes nothing when the content hash matches, and that hash covers pack
+    // SOURCES only — so declaring a namespace in `pragma.conf.ts` cannot, by
+    // itself, make the shipped pack bind it. Without this test that mismatch
+    // shows up as entities compacting to nothing; with it, it fails here.
+    const shipped = embeddedManifest().prefixes;
+    for (const [prefix, namespace] of Object.entries(DEFAULT_PREFIX_MAP)) {
+      expect(shipped[prefix], `pack binding for \`${prefix}:\``).toBe(
+        namespace,
+      );
+    }
+  });
+});

package/src/kernel/render/prefixes.ts

@@ -1,21 +1,48 @@
 /**
- * The default display-compaction prefix set.
+ * The compiled-in prefix map — the CLI's prefixed↔full translation table.
  *
- * A minimal port of the v1 prefix map: only the namespaces the renderers use
- * to compact IRIs in output. The store's query prefix map (which layers in
- * package- and config-declared prefixes) is a store concern and joins when the
- * first store-backed capability lands — this display set is intentionally
- * small and static so the render layer stays store-free.
+ * NOT only display compaction, despite the name this module used to carry.
+ * Three readers make it behavioural, and every one of them predates any store:
+ * - `render/compactUri.ts` shortens IRIs for output.
+ * - `packs/iri.ts#resolveUri` expands a user-typed prefixed name into the IRI a
+ *   generated SPARQL read filters on, so a namespace missing here makes
+ *   `<noun> lookup <prefix>:<local>` fail with "Invalid prefix".
+ * - `packs/graphql/fetchGraphqlLookup.ts#expandPrefixed` expands the prefixed
+ *   values a GraphQL lookup returns, so a namespace missing here silently
+ *   leaks the *unexpanded* token into a field documented as a full IRI.
+ *
+ * Two halves, one map. The W3C namespaces below are universal vocabulary, so
+ * the kernel names them. The DOMAIN namespaces are the distribution's, so they
+ * are read from `pragma.conf.ts`'s `prefixes` — the same declaration that pins
+ * what `sources update` builds the store with, so what the CLI compacts and
+ * what the graph is indexed under cannot drift apart. `render/prefixes.test.ts`
+ * pins that agreement against the shipped pack's own manifest.
+ *
+ * The asymmetry, stated plainly: a PROJECT layer's `prefixes` reach the pack it
+ * builds — hence that pack's store session and index — but never this map. This
+ * is a compiled-in presentation default, read on the storeless `--help`/
+ * `__complete` fast path where no config layer is reachable at all.
  */
 
-/**
- * Namespaces compacted in list/lookup output. Keys are the prefixes shown to
- * the user (`ds:Button`); values are the absolute namespace IRIs matched.
- */
-export const DEFAULT_PREFIX_MAP: Readonly<Record<string, string>> = {
-  ds: "https://ds.canonical.com/",
-  cs: "http://pragma.canonical.com/codestandards#",
+import conf from "../../../pragma.conf.js";
+
+/** Standard RDF vocabulary — the same IRIs in every graph, domain or not. */
+const STANDARD_PREFIXES: Readonly<Record<string, string>> = {
   rdfs: "http://www.w3.org/2000/01/rdf-schema#",
   owl: "http://www.w3.org/2002/07/owl#",
   skos: "http://www.w3.org/2004/02/skos/core#",
 };
+
+/**
+ * Namespaces compacted and expanded across the CLI. Keys are the prefixes shown
+ * to the user (`rdfs:label`); values are the absolute namespace IRIs matched.
+ *
+ * The standard half is spread LAST so it wins a collision: `rdfs` means the
+ * same thing in every graph, and the kernel hardcodes those IRIs elsewhere
+ * (`buildIndex`'s label predicates, the prompt SELECT), so letting a
+ * declaration rebind them here would split one prefix across two meanings.
+ */
+export const DEFAULT_PREFIX_MAP: Readonly<Record<string, string>> = {
+  ...conf.prefixes,
+  ...STANDARD_PREFIXES,
+};

package/src/kernel/render/renderers.test.ts

@@ -182,7 +182,7 @@ describe("error render matrix (× plain/llm/json)", () => {
   it("renders each error across the three formats", () => {
     const notFound = PragmaError.notFound("block", "Buton", {
       suggestions: ["Button"],
-      recovery: cliRecovery("pragma block list", "List available blocks."),
+      recovery: cliRecovery("block list", "List available blocks."),
     });
     const empty = PragmaError.emptyResults("token", {
       filters: { channel: "stable", tier: "core" },