@canonical/pragma-cli 0.33.0 → 0.35.0

package/src/kernel/packs/sparql/buildLookupQuery.ts

@@ -6,6 +6,14 @@
  * user-supplied names are always escaped SPARQL string literals, and level-gated
  * fields below the active level are excluded from the projection (fetch-gating).
  * Matching on the `by` property is exact and case-insensitive.
+ *
+ * Every name-addressed resolve is TOTALLY ORDERED before its `LIMIT 1`. A name
+ * can recur across tiers, and an unordered `LIMIT 1` hands the tie to the
+ * store's enumeration order — a different answer on a different machine, or
+ * after a repack. `ORDER BY STR(?uri)` is a total, engine-independent order over
+ * a variable that is always bound (`?uri` carries the `by` triple), so it needs
+ * no unbound-value sentinel. It fixes WHICH answer is arbitrary, not WHETHER:
+ * declaring a precedence between tiers is an ontology change, tracked separately.
  */
 
 import { activeExpands, activeFields } from "../disclosure.js";
@@ -74,12 +82,32 @@ export function buildLookupQuery(
     body,
     `  FILTER (LCASE(STR(?name)) = LCASE("${escapeSparqlString(name)}"))`,
     "}",
+    "ORDER BY STR(?uri)",
     "LIMIT 1",
   ]
     .filter((line) => line !== "")
     .join("\n");
 }
 
+/**
+ * The `?name` clause for an IRI-addressed form.
+ *
+ * An IRI names the entity by itself, so the `by` value is a LABEL to project,
+ * not the thing that identifies it — and a class constraint is already a
+ * sufficient existence check. Requiring the `by` triple here made every entity
+ * that carries no name unaddressable by any means at all: 131 of the 144 live
+ * code standards have no `cs:name` (their displayed name is synthesized from the
+ * IRI by the list story), and shell completion offers their IRIs. So the triple
+ * is OPTIONAL wherever a class constraint can vouch for the entity, and
+ * REQUIRED only for a lookup that declares no `type`/`types` — where it is the
+ * one thing standing between a typo'd IRI and an empty entity.
+ */
+function iriNameClause(lookup: PackLookup): string {
+  const named = `?uri ${formatTerm(lookup.by)} ?name .`;
+  const constrained = Boolean(lookup.type ?? lookup.types?.length);
+  return constrained ? `  OPTIONAL { ${named} }` : `  ${named}`;
+}
+
 /**
  * Build the SELECT retrieving one entity addressed directly by IRI.
  *
@@ -102,7 +130,7 @@ export function buildLookupByIriQuery(
   return [
     header,
     `  BIND(<${iri}> AS ?uri)`,
-    `  ?uri ${formatTerm(lookup.by)} ?name .`,
+    iriNameClause(lookup),
     body,
     "}",
     "LIMIT 1",
@@ -127,13 +155,51 @@ export function buildNameResolveQuery(
     buildTypeConstraint(lookup).trimEnd(),
     `  FILTER (LCASE(STR(?name)) = LCASE("${escapeSparqlString(name)}"))`,
     "}",
-    // Names can recur across tiers; LIMIT 1 takes the store's first match.
+    "ORDER BY STR(?uri)",
+    "LIMIT 1",
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}
+
+/**
+ * Build the minimal IRI→entity resolve for a graphql-sourced lookup: the mirror
+ * of {@link buildNameResolveQuery} for the other argument shape.
+ *
+ * The GraphQL lane fetches by IRI, so this exists to ANSWER ONE QUESTION — does
+ * the pack's class constraint vouch for this entity? — and to pick up a display
+ * name if there is one. Injection-safe by construction: `iri` is already
+ * resolved and validated against the embeddable-IRI shape by the caller.
+ */
+export function buildIriResolveQuery(lookup: PackLookup, iri: string): string {
+  return [
+    "SELECT ?uri ?name WHERE {",
+    `  BIND(<${iri}> AS ?uri)`,
+    iriNameClause(lookup),
+    buildTypeConstraint(lookup).trimEnd(),
+    "}",
     "LIMIT 1",
   ]
     .filter((line) => line !== "")
     .join("\n");
 }
 
+/** Build the SELECT listing every entity IRI a lookup can address (IRI globs). */
+export function buildLookupIrisQuery(lookup: PackLookup): string {
+  const constraint = buildTypeConstraint(lookup).trimEnd();
+  return [
+    "SELECT DISTINCT ?uri WHERE {",
+    // A pack that constrains by class is asking about its class; one that does
+    // not has only the `by` triple to bound the scan, so it keeps that bound
+    // (and, like the name population, addresses only entities that carry one).
+    constraint !== "" ? constraint : `  ?uri ${formatTerm(lookup.by)} ?name .`,
+    "}",
+    "ORDER BY STR(?uri)",
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}
+
 /**
  * Build the sub-SELECT retrieving one expand's child rows for a resolved entity.
  *
@@ -166,7 +232,13 @@ export function buildExpandQuery(
 /** Build the SELECT listing all entity names — lookup-miss suggestions. */
 export function buildLookupNamesQuery(lookup: PackLookup): string {
   return [
-    "SELECT ?name WHERE {",
+    // DISTINCT: this population feeds miss-suggestions and glob expansion, and
+    // a name that several entities share is one CANDIDATE, not several. Without
+    // it a glob matching such a name expanded to it once per entity carrying
+    // it, and `lookup` then resolved each copy to the same winner — so
+    // `block lookup 'Butt*'` listed one Button twice while the other Button
+    // never appeared at all.
+    "SELECT DISTINCT ?name WHERE {",
     `  ?uri ${formatTerm(lookup.by)} ?name .`,
     buildTypeConstraint(lookup).trimEnd(),
     "}",

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

@@ -0,0 +1,37 @@
+/**
+ * The SPARQL path — every generated read a pack story performs, and the two
+ * row operations that must NOT be generated.
+ *
+ * The domain is organised around one invariant: user input never reaches query
+ * text. The query builders compose only from validated pack terms and escaped
+ * literals, so a name a user typed becomes a SPARQL string literal or nothing;
+ * `runSelect` is the single choke point every one of those trusted queries
+ * goes through, which is what makes "a generated query failed" distinguishable
+ * from "the user's own `graph query` failed". Filtering and search then run as
+ * predicates over the resolved ROWS rather than as clauses in the query —
+ * which is why they live in this domain despite touching no SPARQL at all:
+ * they are the operations that would otherwise be tempting to express as query
+ * text, and keeping them here keeps the temptation answered.
+ *
+ * The escaping primitives stay internal. They are how the builders keep that
+ * invariant, not a service for composing query text elsewhere — a caller with
+ * the escaper is a caller who can build an unvalidated query, which is exactly
+ * the shape this domain exists to prevent.
+ *
+ * Two names re-exported by `buildLookupQuery.ts` for its own callers'
+ * convenience — the disclosure-level field and expand selectors — are also
+ * omitted. They belong to `kernel/packs/disclosure.ts`; laundering them
+ * through here would make this domain look like their owner and freeze a
+ * pass-through that has no reason to be permanent.
+ */
+
+export { applyPackFilters } from "./applyFilters.js";
+export { applyPackSearch } from "./applySearch.js";
+export {
+  buildExpandQuery,
+  buildLookupByIriQuery,
+  buildLookupNamesQuery,
+  buildLookupQuery,
+  buildNameResolveQuery,
+} from "./buildLookupQuery.js";
+export { runSelect } from "./runSelect.js";

package/src/kernel/packs/sparql/runSelect.test.ts

@@ -1,18 +1,32 @@
 /**
  * `runSelect` — the single choke point for every TRUSTED, generated SPARQL read.
  *
- * Pins the unseeded-store remap: a generated pack query only references the
- * pack's own `ds:`/`cs:` prefixes, so a "Prefix not found" from the facade means
- * the store was never built — an actionable STORE_UNAVAILABLE, NOT a raw error
- * collapsing to INTERNAL_ERROR ("please report this issue"). The recovery carries
- * BOTH the CLI command (`pragma sources update`) and the MCP tool an agent calls
- * (`sources_update`), so either surface can recover.
+ * Pins the remap: a generated query is composed from declared and pack-authored
+ * terms, never from user input, so a "Prefix not found" from the facade means
+ * the store cannot answer this read — an actionable error, NOT a raw one
+ * collapsing to INTERNAL_ERROR ("report this issue").
+ *
+ * WHICH actionable error is the story's provenance to decide, which is the
+ * second thing pinned here. A DISTRIBUTION story keeps STORE_UNAVAILABLE and its
+ * recovery, carrying BOTH the CLI command (`pragma sources update`) and the MCP
+ * tool an agent calls (`sources_update`), so either surface can recover. A
+ * CONFIG or PACKAGE story gets CONFIG_ERROR naming the story instead: its author
+ * named a prefix nothing binds, and `sources update` cannot conjure a term.
  */
 
 import { describe, expect, it } from "vitest";
 import type { PragmaRuntime } from "../../runtime/types.js";
+import { distributionSource, type StorySource } from "../types.js";
 import { runSelect } from "./runSelect.js";
 
+/** A story declared by a package (a third party's own file). */
+const PACKAGE: StorySource = {
+  label: "@acme/recipes/stories/recipe.json",
+  origin: "package",
+};
+/** A story declared in the user's config. */
+const CONFIG: StorySource = { label: "config", origin: "config" };
+
 /** A runtime whose query facade throws the given error for every SPARQL call. */
 function throwingRuntime(error: unknown): Pick<PragmaRuntime, "query"> {
   return {
@@ -35,14 +49,14 @@ function selectRuntime(
   };
 }
 
-describe("runSelect — unseeded-store remap (ROOT A)", () => {
+describe("runSelect — unanswerable-store remap (ROOT A)", () => {
   it("remaps a 'Prefix not found' to STORE_UNAVAILABLE with CLI + MCP recovery", async () => {
     let caught: unknown;
     try {
       await runSelect(
         throwingRuntime(new Error("Prefix not found: ds")),
         "SELECT ?x WHERE { ?x a ds:Thing }",
-        "block",
+        distributionSource("block"),
       );
     } catch (error) {
       caught = error;
@@ -50,6 +64,12 @@ describe("runSelect — unseeded-store remap (ROOT A)", () => {
 
     // The whole point: it is NOT an unclassified INTERNAL_ERROR.
     expect(caught).toMatchObject({ code: "STORE_UNAVAILABLE" });
+    // …and it claims only what it knows. The same failure reaches a store that
+    // IS built, from a pack whose vocabulary is simply different, so the
+    // message must not tell that user their store is unbuilt.
+    expect((caught as { message: string }).message).toContain(
+      "not built from a pack that defines every term",
+    );
     const recovery = (caught as { recovery?: Record<string, unknown> })
       .recovery;
     expect(recovery?.cli).toBe("pragma sources update");
@@ -61,7 +81,11 @@ describe("runSelect — unseeded-store remap (ROOT A)", () => {
     const boom = new Error("some other engine failure");
     let caught: unknown;
     try {
-      await runSelect(throwingRuntime(boom), "SELECT ?x WHERE {}", "block");
+      await runSelect(
+        throwingRuntime(boom),
+        "SELECT ?x WHERE {}",
+        distributionSource("block"),
+      );
     } catch (error) {
       caught = error;
     }
@@ -73,8 +97,78 @@ describe("runSelect — unseeded-store remap (ROOT A)", () => {
     const rows = await runSelect(
       selectRuntime([{ name: "Button" }, { name: "Card" }]),
       "SELECT ?name WHERE { ?x ds:name ?name }",
-      "block",
+      distributionSource("block"),
     );
     expect(rows).toEqual([{ name: "Button" }, { name: "Card" }]);
   });
 });
+
+describe("runSelect — an unbound prefix is diagnosed by PROVENANCE", () => {
+  const unbound = (): Error => new Error("Prefix not found: acme");
+
+  for (const source of [PACKAGE, CONFIG]) {
+    it(`a ${source.origin} story gets CONFIG_ERROR naming the story`, async () => {
+      // `sources update` cannot help an author who named a prefix nothing
+      // binds — no amount of building conjures a term. Telling them to run it
+      // (as this path used to) sends them round a loop that cannot terminate.
+      // `buildIndex` already treats the same condition as the ordinary
+      // third-party case; the query path used to escalate it.
+      let caught: unknown;
+      try {
+        await runSelect(
+          throwingRuntime(unbound()),
+          "SELECT ?x WHERE { ?x a acme:Thing }",
+          source,
+        );
+      } catch (error) {
+        caught = error;
+      }
+      expect(caught).toMatchObject({ code: "CONFIG_ERROR" });
+      const { message } = caught as { message: string };
+      // It names the story, so the author knows which file to fix.
+      expect(message).toContain(source.label);
+      expect(message).toContain("does not bind");
+      // And it does NOT send them to the lever that cannot help.
+      expect(message).not.toContain("sources update");
+      expect(
+        (caught as { recovery?: { cli?: string } }).recovery?.cli,
+      ).toBeUndefined();
+    });
+  }
+
+  it("the distribution's own story keeps STORE_UNAVAILABLE", async () => {
+    // Unchanged, and the reason is real: the distribution's stories ship with
+    // the packs that bind their terms, so an unbound prefix there means nothing
+    // is built yet — which `sources update` does fix.
+    let caught: unknown;
+    try {
+      await runSelect(
+        throwingRuntime(unbound()),
+        "SELECT ?x WHERE { ?x a ds:Thing }",
+        distributionSource("pragma.conf.ts"),
+      );
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toMatchObject({ code: "STORE_UNAVAILABLE" });
+    expect((caught as { recovery?: { cli?: string } }).recovery?.cli).toBe(
+      "pragma sources update",
+    );
+  });
+
+  it("a non-SELECT still names the story on every origin", async () => {
+    const askRuntime = {
+      query: {
+        sparql: async () => ({ type: "ask", boolean: true }),
+      } as unknown as PragmaRuntime["query"],
+    };
+    for (const source of [PACKAGE, CONFIG, distributionSource("block")]) {
+      await expect(
+        runSelect(askRuntime, "ASK { ?x ?y ?z }", source),
+      ).rejects.toMatchObject({
+        code: "CONFIG_ERROR",
+        message: expect.stringContaining(source.label),
+      });
+    }
+  });
+});

package/src/kernel/packs/sparql/runSelect.ts

@@ -10,18 +10,27 @@
  * (`graph query`) goes through the facade directly and stays INVALID_INPUT.
  */
 
-import { RECOVERY_CLI_PREFIX } from "../../../constants.js";
-import { PragmaError } from "../../error/PragmaError.js";
-import { cliRecovery } from "../../error/recovery.js";
-import type { PragmaRuntime } from "../../runtime/types.js";
-import type { PackRow } from "../types.js";
+import { cliRecovery, PragmaError } from "../../error/index.js";
+import type { PragmaRuntime } from "../../runtime/index.js";
+import type { PackRow, StorySource } from "../types.js";
 
 /**
  * True when a trusted, generated query failed because the store does not know a
- * prefix it used. A generated pack query only references the pack's own
- * ontology prefixes (`ds:`/`cs:`), so a "prefix not found" means the store is
- * unseeded — the fresh-install embedded fallback carries no design-system
- * ontology — rather than a query bug.
+ * prefix it used. Generated queries are composed from terms the distribution
+ * declares and from a pack's own story text, never from user input — so an
+ * unknown prefix is never a query bug. It means this store was not built from a
+ * pack that binds that term: most often nothing was built at all, and otherwise
+ * a store built from a pack whose vocabulary is simply different.
+ *
+ * For a DISTRIBUTION story both are answered by the same lever
+ * (`sources update`), so both are remapped to it; the message says which claim
+ * it is actually making, and does NOT assert the store is unbuilt. Widening the
+ * detection any further would start hiding query bugs, which is the failure this
+ * whole choke point exists to prevent.
+ *
+ * A story from a package or a user's config is a different diagnosis, which is
+ * why {@link runSelect} now takes the query's provenance: see
+ * {@link unboundPrefixError}.
  */
 function isUnseededStoreError(error: unknown): boolean {
   const message = error instanceof Error ? error.message : String(error);
@@ -29,33 +38,60 @@ function isUnseededStoreError(error: unknown): boolean {
 }
 
 /**
- * Run the facade query, remapping an unseeded-store failure. A generated pack
- * query hitting an unknown prefix means the store was never built for this
- * design system (the first thing a fresh install hits) — surface the actionable
- * STORE_UNAVAILABLE with the canonical `pragma sources update` recovery instead
- * of a raw SPARQL "Prefix not found" wrapped as INTERNAL_ERROR ("please report
- * this issue"). Returns the inferred facade result type, so this module stays
- * clear of a static `@canonical/ke` import (the lazy-dispatch guard).
+ * The error for a generated query naming a prefix the graph does not bind,
+ * diagnosed by WHO declared the story.
+ *
+ * A distribution story ships with the packs that bind its terms, so the honest
+ * reading is "nothing is built yet" (or "what is built came from a pack with a
+ * different vocabulary") — both fixed by `sources update`, so it keeps today's
+ * STORE_UNAVAILABLE and that recovery.
+ *
+ * A config or package story is the author's own: they named a prefix the graph
+ * does not bind, and `sources update` cannot help them — `buildIndex` already
+ * treats the same condition as the ordinary third-party case and degrades
+ * gracefully, while this path escalated it. It is a CONFIG_ERROR naming the
+ * story, which is the module's own precedent for a declaration that cannot be
+ * served (ruling R3).
+ */
+function unboundPrefixError(source: StorySource): PragmaError {
+  if (source.origin !== "distribution") {
+    return PragmaError.configError(
+      `Story query in ${source.label} uses a prefix the graph does not bind. ` +
+        `Declare it under \`prefixes\`, or use a term the configured packs define.`,
+    );
+  }
+  return PragmaError.storeUnavailable(
+    "The local store was not built from a pack that defines every term this read uses.",
+    {
+      recovery: cliRecovery(
+        "sources update",
+        "Build the local store from the configured packs.",
+        // An agent recovers by calling the tool, then retrying (PR9 C1 cold-
+        // store retry makes the post-update retry succeed).
+        { tool: "sources_update" },
+      ),
+    },
+  );
+}
+
+/**
+ * Run the facade query, remapping a store that cannot answer it. A generated
+ * query hitting an unknown prefix surfaces an actionable error — chosen by the
+ * story's provenance, see {@link unboundPrefixError} — instead of a raw SPARQL
+ * "Prefix not found" wrapped as INTERNAL_ERROR ("report this issue").
+ * Returns the inferred facade result type, so this module stays clear of a
+ * static `@canonical/ke` import (the lazy-dispatch guard).
  */
-async function queryOrRemap(rt: Pick<PragmaRuntime, "query">, query: string) {
+async function queryOrRemap(
+  rt: Pick<PragmaRuntime, "query">,
+  query: string,
+  source: StorySource,
+) {
   try {
     return await rt.query.sparql(query);
   } catch (error) {
     if (error instanceof PragmaError) throw error;
-    if (isUnseededStoreError(error)) {
-      throw PragmaError.storeUnavailable(
-        "The store has not been built for this project yet.",
-        {
-          recovery: cliRecovery(
-            `${RECOVERY_CLI_PREFIX}sources update`,
-            "Build the local store from the configured design-system packages.",
-            // An agent recovers by calling the tool, then retrying (PR9 C1 cold-
-            // store retry makes the post-update retry succeed).
-            { tool: "sources_update" },
-          ),
-        },
-      );
-    }
+    if (isUnseededStoreError(error)) throw unboundPrefixError(source);
     throw error;
   }
 }
@@ -63,21 +99,23 @@ async function queryOrRemap(rt: Pick<PragmaRuntime, "query">, query: string) {
 /**
  * @param rt - The runtime (its query facade over the lazy store).
  * @param query - SPARQL SELECT text (prefixes auto-applied by the store).
- * @param source - The pack source, for error attribution.
+ * @param source - The story's provenance: its label for attribution, and the
+ *   layer that declared it, which decides how an unbound prefix is diagnosed.
  * @returns One record per row, keyed by SELECT variable name.
- * @throws PragmaError CONFIG_ERROR when the query is not a SELECT;
- *   STORE_UNAVAILABLE (exit 3) when the store is unseeded.
+ * @throws PragmaError CONFIG_ERROR when the query is not a SELECT, or when a
+ *   config/package story names a prefix the graph does not bind;
+ *   STORE_UNAVAILABLE (exit 3) when a distribution story finds one.
  * @note Impure — queries the store through the facade.
  */
 export async function runSelect(
   rt: Pick<PragmaRuntime, "query">,
   query: string,
-  source: string,
+  source: StorySource,
 ): Promise<PackRow[]> {
-  const result = await queryOrRemap(rt, query);
+  const result = await queryOrRemap(rt, query, source);
   if (result.type !== "select") {
     throw PragmaError.configError(
-      `Story query in ${source} must be a SELECT (got ${result.type}).`,
+      `Story query in ${source.label} must be a SELECT (got ${result.type}).`,
     );
   }
   return result.bindings as PackRow[];

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

@@ -13,12 +13,20 @@
  */
 
 import { describe, expect, it } from "vitest";
-import { standardModule } from "../../capabilities/standard/index.js";
-import { tokenModule } from "../../capabilities/token/index.js";
+import { storyModules } from "../../capabilities/distribution.js";
 import { projectMcp } from "../../testing/helpers/projectMcp.js";
 import { formatVerbHelp } from "../project/cli/verbHelp.js";
 import type { VerbSpec } from "../spec/types.js";
 
+const standardModule = storyModules.get("standard");
+if (!standardModule) {
+  throw new Error('pragma.conf.ts declares no story for "standard"');
+}
+const tokenModule = storyModules.get("token");
+if (!tokenModule) {
+  throw new Error('pragma.conf.ts declares no story for "token"');
+}
+
 const verb = (
   module: { verbs: readonly VerbSpec[] },
   label: string,
@@ -39,9 +47,7 @@ describe("pack toolDescription wiring (PROTECTED)", () => {
       "Get type and theme values for one or more design tokens by name.",
     );
     // The authored MCP tool-call example survives on the MCP surface.
-    expect(desc).toContain(
-      'Example: token_lookup { names: ["color.primary"] }',
-    );
+    expect(desc).toContain('Example: token_lookup { name: ["color.primary"] }');
   });
 
   it("routes the definition-level toolDescription to the MCP list tool", async () => {
@@ -79,3 +85,44 @@ describe("pack toolDescription wiring (PROTECTED)", () => {
     expect(listHelp).not.toContain("token_list {");
   });
 });
+
+describe("a tool-call example names a parameter the tool ACCEPTS (PROTECTED)", () => {
+  // Four `*_lookup` descriptions taught agents `{ names: [...] }` while every
+  // schema required `name`. An agent copying the example — which is what an
+  // example is for — got `-32602 Invalid arguments`, and the description is
+  // the only instruction it has. Prose that contradicts the schema beside it
+  // is worse than no prose: it is a documented wrong answer.
+  it("every `Example: tool { key: … }` uses a declared property", async () => {
+    const mcp = await projectMcp([...storyModules.values()]);
+    try {
+      const tools = await mcp.listTools();
+      const offenders: string[] = [];
+
+      for (const tool of tools) {
+        const example = /Example:\s*\w+\s*\{\s*([A-Za-z_$][\w$]*)\s*:/.exec(
+          tool.description ?? "",
+        );
+        const key = example?.[1];
+        if (key === undefined) continue; // No call example to check.
+        const properties = Object.keys(
+          (tool.inputSchema as { properties?: Record<string, unknown> })
+            ?.properties ?? {},
+        );
+        if (!properties.includes(key)) {
+          offenders.push(
+            `${tool.name}: example says \`${key}\`, schema declares ${properties.join(", ")}`,
+          );
+        }
+      }
+
+      expect(offenders).toEqual([]);
+      // Guard against a vacuous pass: some tool must actually carry an example.
+      expect(
+        tools.filter((t) => /Example:\s*\w+\s*\{/.test(t.description ?? ""))
+          .length,
+      ).toBeGreaterThan(0);
+    } finally {
+      await mcp.cleanup();
+    }
+  });
+});

package/src/kernel/packs/types.ts

@@ -170,7 +170,11 @@ export interface PackSearch {
 export interface PackEmptyRecovery {
   /** Human-readable cause + fix (e.g. which packages provide the data). */
   readonly message: string;
-  /** Runnable pragma command fixing the emptiness (rendered on the CLI). */
+  /**
+   * The command that fixes the emptiness, WITHOUT the binary name
+   * (`sources update`). The consuming distribution's renderer prepends its own
+   * name, so a story stays portable across distributions.
+   */
   readonly cli?: string;
 }
 
@@ -263,6 +267,19 @@ export interface PackLookup {
    * VALUES constraint on the name resolve. Mutually exclusive with `type`.
    */
   readonly types?: readonly string[];
+  /**
+   * Relative importance per addressed type, prefixed type → 0–1 (unlisted types
+   * default to 1). Editorial judgement about which of a noun's classes matters
+   * most, declared as DATA rather than frozen into the kernel — it feeds the MCP
+   * listing's `annotations.priority` AND breaks ties in URI-completion ranking,
+   * so a `ds:Subcomponent` at 0.6 sinks below every component at equal match.
+   *
+   * A separate map rather than an entry shape on `types` so `types` keeps its
+   * flat `readonly string[]` form and the addition is non-breaking. A key naming
+   * a type the lookup does not address is REJECTED, not ignored: a silent no-op
+   * is how a weight that never applied survives review.
+   */
+  readonly weights?: Readonly<Record<string, number>>;
   /**
    * GraphQL type or interface the generated document's inline fragment targets
    * (`source: "graphql"` only). Defaults to the local name of `type`; required
@@ -312,8 +329,8 @@ export interface PackDefinition {
   /** MCP tool description (defaults to the CLI description). */
   readonly toolDescription?: string;
   /**
-   * The list story. Optional so a pack can serve only the lookup verb of a noun
-   * whose list stays hand-written (e.g. `block`). At least one of `list`/`lookup`
+   * The list story. Optional so a pack can serve a noun that is addressable but
+   * not enumerable — a lookup with no list. At least one of `list`/`lookup`
    * must be declared.
    */
   readonly list?: PackList;
@@ -331,7 +348,38 @@ export interface PackDefinition {
 
 /** A validated pack definition paired with where it was declared. */
 export interface PackEntry {
-  /** Where the definition was declared (config path, package file, or bundled). */
+  /** The package story file it came from, e.g. `@acme/recipes/stories/recipe.json`. */
   readonly source: string;
   readonly definition: PackDefinition;
 }
+
+/**
+ * Which layer declared a story. The label alone cannot answer this — a label is
+ * free text for a human — and the difference changes what a failure MEANS.
+ *
+ * A generated query that names a prefix the graph does not bind is, from a
+ * `distribution` story, almost always an unbuilt store: the distribution's own
+ * stories and its packs ship together, so the terms exist as soon as anything is
+ * built. From a `config` or `package` story it is the opposite: the author named
+ * a prefix nothing binds, and no amount of building will conjure it. One is
+ * STORE_UNAVAILABLE with a `sources update` recovery, the other a CONFIG_ERROR
+ * naming the story — and telling them apart needs this at the failure site.
+ */
+export type StoryOrigin = "distribution" | "config" | "package";
+
+/**
+ * A story's provenance, threaded from where it was declared down to the query
+ * that runs on its behalf.
+ */
+export interface StorySource {
+  /** Human-readable location, used verbatim in diagnostics. */
+  readonly label: string;
+  /** The layer that declared it. */
+  readonly origin: StoryOrigin;
+}
+
+/** A story the distribution itself declares (`pragma.conf.ts` and its kin). */
+export const distributionSource = (label: string): StorySource => ({
+  label,
+  origin: "distribution",
+});

package/src/kernel/packs/uniqueness.ts

@@ -2,13 +2,13 @@
  * Plain `(noun, verb)` uniqueness across compiled verbs.
  *
  * Replaces the old reserved-verb / derive-reserved machinery: every verb the
- * projectors see — authored, bundled-pack, or dynamic-pack — must own a distinct
- * `(noun, verb)` key. Precedence (config > package > bundled) is resolved by
- * NOUN before this runs, so a surviving collision here is a real conflict (a
- * dynamic pack claiming an authored noun's verb), reported with both sources.
+ * projectors see — authored, distribution-declared, or dynamic — must own a
+ * distinct `(noun, verb)` key. Precedence (config > package > distribution) is
+ * resolved by NOUN before this runs, so a surviving collision here is a real
+ * conflict, reported with both sources.
  */
 
-import type { VerbSpec } from "../spec/types.js";
+import type { VerbSpec } from "../spec/index.js";
 
 /** The `(noun, verb)` key for a verb path (`["standard","list"]` → `standard list`). */
 export function verbKey(path: readonly [string, string?]): string {