@canonical/pragma-cli 0.34.0 → 0.35.0

package/src/kernel/packs/resolveEntity.ts

@@ -2,27 +2,37 @@
  * Look up one or more pack entities by name, prefixed name, absolute IRI, or
  * glob, via the fetch strategy the pack declares.
  *
- * The name→URI resolve is ALWAYS generated SPARQL (an escaped literal or a
- * validated `<iri>` BIND) regardless of `source`; from the resolved IRI, values
- * are fetched either through more generated SELECTs (`sparql`) or one generated
+ * The resolve is ALWAYS generated SPARQL (an escaped literal or a validated
+ * `<iri>` BIND) regardless of `source`; from the resolved IRI, values are
+ * fetched either through more generated SELECTs (`sparql`) or one generated
  * GraphQL document (`graphql`). One poisoned query never discards the batch —
  * per-query failures are collected as structured error entries.
  *
+ * WHICH query is chosen is decided by the ARGUMENT'S SHAPE first and the pack's
+ * `source` second, and both dispatches live here. Getting that order wrong is
+ * not a style question: it is what made an IRI reach a name FILTER on every
+ * graphql-sourced pack, and what left an IRI-shaped glob expanding against a
+ * population of names. The shape a user typed is a fact about the argument; the
+ * fetch strategy is a fact about the pack, and it cannot change what the
+ * argument means.
+ *
  * Reached only behind a dynamic import from the lookup run body, so its imports
  * (including the GraphQL path) stay off the storeless fast path.
  */
 
-import { PragmaError } from "../error/PragmaError.js";
-import { cliRecovery } from "../error/recovery.js";
+import { cliRecovery, PragmaError } from "../error/index.js";
 import { suggestNames } from "../project/cli/suggestNames.js";
-import type { PragmaRuntime } from "../runtime/types.js";
+import { compactUri } from "../render/index.js";
+import type { PragmaRuntime } from "../runtime/index.js";
 import { activeExpands } from "./disclosure.js";
 import { expandGlob, isGlobPattern } from "./glob.js";
 import { fetchGraphqlLookup } from "./graphql/fetchGraphqlLookup.js";
 import { isEmbeddableIri, resolveUri } from "./iri.js";
 import {
   buildExpandQuery,
+  buildIriResolveQuery,
   buildLookupByIriQuery,
+  buildLookupIrisQuery,
   buildLookupNamesQuery,
   buildLookupQuery,
   buildNameResolveQuery,
@@ -74,7 +84,14 @@ export async function resolveLookup(
     });
   }
 
-  const expanded = await expandQueries(rt, lookup, noun, source, queries);
+  const expanded = await expandQueries(
+    rt,
+    lookup,
+    noun,
+    source,
+    queries,
+    prefixes,
+  );
   const results: PackEntity[] = [];
   const errors: LookupError[] = [...expanded.globErrors];
   const settled = await Promise.allSettled(
@@ -110,17 +127,34 @@ export async function resolveLookup(
   return { results, errors };
 }
 
-/** Expand glob queries against the entity name list; literals pass through. */
+/**
+ * Expand glob queries against the population their own shape addresses;
+ * literals pass through.
+ *
+ * A name glob expands over the `by` values, an IRI glob over the entity IRIs —
+ * the same split {@link buildResolveQuery} makes, because a glob is just a
+ * lookup argument with a `*` in it. Expanding an IRI pattern over names was why
+ * `ds:global.component.but*` matched nothing on any pack while shell completion
+ * offered nothing BUT those IRIs. Each population is fetched at most once, and
+ * only when a glob of that shape is actually present.
+ */
 async function expandQueries(
   rt: LookupRuntime,
   lookup: PackLookup,
   noun: string,
   source: StorySource,
   queries: readonly string[],
+  prefixes: Readonly<Record<string, string>>,
 ): Promise<{ names: string[]; globErrors: LookupError[] }> {
   if (!queries.some(isGlobPattern))
     return { names: [...queries], globErrors: [] };
-  const allNames = await listEntityNames(rt, lookup, source);
+  const globs = queries.filter(isGlobPattern);
+  const byIri = globs.some(looksLikeIri)
+    ? await listEntityIriSpellings(rt, lookup, source, prefixes)
+    : new Map<string, string>();
+  const byName = globs.some((glob) => !looksLikeIri(glob))
+    ? await listEntityNames(rt, lookup, source)
+    : [];
   const names: string[] = [];
   const globErrors: LookupError[] = [];
   for (const query of queries) {
@@ -128,7 +162,17 @@ async function expandQueries(
       names.push(query);
       continue;
     }
-    const matches = expandGlob(query, allNames);
+    // An IRI glob expands over every spelling, then collapses to the entity:
+    // matching `ds:button` and its absolute twin must not list it twice.
+    const matches = looksLikeIri(query)
+      ? [
+          ...new Set(
+            expandGlob(query, [...byIri.keys()]).map(
+              (spelling) => byIri.get(spelling) ?? spelling,
+            ),
+          ),
+        ]
+      : expandGlob(query, byName);
     if (matches.length === 0) {
       globErrors.push({
         query,
@@ -155,9 +199,7 @@ async function lookupOne(
   const graphqlSourced = lookup.source === "graphql";
   const rows = await runSelect(
     rt,
-    graphqlSourced
-      ? buildNameResolveQuery(lookup, query)
-      : buildEntityQuery(lookup, query, prefixes, level),
+    buildResolveQuery(lookup, query, prefixes, level),
     source,
   );
   const base = rows.at(0);
@@ -196,14 +238,27 @@ async function lookupOne(
   return entity;
 }
 
-/** Build the base entity SELECT for the SPARQL path (name or IRI form). */
-function buildEntityQuery(
+/**
+ * Build the resolve SELECT for one lookup argument: shape first, source second.
+ *
+ * The four cells of that 2×2 are the whole dispatch. A graphql-sourced pack
+ * resolves to an IRI and fetches everything else through its document, so both
+ * of its queries are the minimal `?uri ?name` pair; a sparql-sourced pack reads
+ * its fields in the same SELECT, so both of its queries carry the level-gated
+ * projection.
+ */
+function buildResolveQuery(
   lookup: PackLookup,
   query: string,
   prefixes: Readonly<Record<string, string>>,
   level: string | undefined,
 ): string {
-  if (!looksLikeIri(query)) return buildLookupQuery(lookup, query, level);
+  const graphqlSourced = lookup.source === "graphql";
+  if (!looksLikeIri(query)) {
+    return graphqlSourced
+      ? buildNameResolveQuery(lookup, query)
+      : buildLookupQuery(lookup, query, level);
+  }
   const resolved = resolveUri(query, prefixes);
   if (!isEmbeddableIri(resolved)) {
     throw PragmaError.invalidInput("name", query, {
@@ -213,7 +268,9 @@ function buildEntityQuery(
       },
     });
   }
-  return buildLookupByIriQuery(lookup, resolved, level);
+  return graphqlSourced
+    ? buildIriResolveQuery(lookup, resolved)
+    : buildLookupByIriQuery(lookup, resolved, level);
 }
 
 /** Whether a lookup query addresses an entity by IRI or prefixed name. */
@@ -221,10 +278,47 @@ function looksLikeIri(query: string): boolean {
   return (
     query.startsWith("http://") ||
     query.startsWith("https://") ||
-    query.includes(":")
+    // Neither an IRI nor a SPARQL prefixed name may contain whitespace, so a
+    // colon in a spaced string is part of a plain entity name — e.g. the
+    // concept "Foundations: Grid" — not a prefix separator.
+    (query.includes(":") && !/\s/.test(query))
   );
 }
 
+/**
+ * Every SPELLING an IRI-shaped glob may be written against, mapped to the one
+ * entity it addresses.
+ *
+ * An entity under a registered prefix has two legal spellings — the compact
+ * `ds:button` shell completion offers, and the absolute
+ * `https://ds.canonical.com/button` a user pastes from a browser. Both resolve
+ * to the same entity in a literal lookup, so a glob must expand over both;
+ * offering only the compact form made `https://ds.canonical.com/but*` return
+ * EMPTY_RESULTS while the literal IRI it generalises succeeded.
+ *
+ * The map is spelling → CANONICAL IRI precisely so a pattern that matches an
+ * entity under both spellings still yields it once. Matching over a flat list
+ * of both would render the entity twice, which is why the previous shape
+ * offered only one.
+ */
+async function listEntityIriSpellings(
+  rt: LookupRuntime,
+  lookup: PackLookup,
+  source: StorySource,
+  prefixes: Readonly<Record<string, string>>,
+): Promise<Map<string, string>> {
+  const rows = await runSelect(rt, buildLookupIrisQuery(lookup), source);
+  const spellings = new Map<string, string>();
+  for (const row of rows) {
+    const uri = row.uri ?? "";
+    if (uri === "") continue;
+    spellings.set(uri, uri);
+    const compact = compactUri(uri, prefixes);
+    if (compact !== uri) spellings.set(compact, uri);
+  }
+  return spellings;
+}
+
 /** List every entity name the lookup can address (miss suggestions + sample/glob). */
 export async function listEntityNames(
   rt: LookupRuntime,

package/src/kernel/packs/runBodies.ts

@@ -9,9 +9,8 @@
  * factories carry no heavy static import.
  */
 
-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 { resolvePackDetail } from "./disclosure.js";
 import type { SampleOutput } from "./renderPack.js";
 import {

package/src/kernel/packs/sample.ts

@@ -6,7 +6,7 @@
  * the supported 1–5 range. Selection is a Fisher-Yates partial shuffle.
  */
 
-import { PragmaError } from "../error/PragmaError.js";
+import { PragmaError } from "../error/index.js";
 import type { PackLookup } from "./types.js";
 
 /** Smallest number of samples the `sample` verb returns. */

package/src/kernel/packs/schema.ts

@@ -18,7 +18,7 @@
 
 import { z } from "zod";
 import { DETAIL_LEVELS, RECOVERY_CLI_PREFIX } from "../../constants.js";
-import { PragmaError } from "../error/PragmaError.js";
+import { PragmaError } from "../error/index.js";
 import type { PackDefinition } from "./types.js";
 
 const NOUN_PATTERN = /^[a-z][a-z0-9-]*$/;
@@ -212,6 +212,7 @@ const lookupSchema = z
     description: z.string().optional(),
     toolDescription: z.string().optional(),
     types: z.array(term).min(1).optional(),
+    weights: z.record(term, z.number().min(0).max(1)).optional(),
     graphqlType: graphqlName.optional(),
     fields: z.array(fieldSchema).min(1).optional(),
     sections: z.array(sectionSchema).min(1).optional(),
@@ -332,6 +333,22 @@ function refineLookup(
     });
   }
 
+  // A weight naming a type the lookup does not address can never apply. Reject
+  // it rather than ignore it — a silent no-op is how a stale weight survives a
+  // rename (the type moves, the weight stays, and nothing says so).
+  const addressed = new Set<string>(
+    lookup.types ?? (lookup.type ? [lookup.type] : []),
+  );
+  for (const named of Object.keys(lookup.weights ?? {})) {
+    if (!addressed.has(named)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `"lookup.weights" names "${named}", which is not in "lookup.type"/"lookup.types".`,
+        path: ["lookup", "weights"],
+      });
+    }
+  }
+
   if (source === "graphql" && !lookup.graphqlType && !lookup.type) {
     ctx.addIssue({
       code: z.ZodIssueCode.custom,

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

@@ -6,10 +6,11 @@
  * preserved. With declared `values` the input is canonicalized against the set
  * (NFC, case-insensitive) and rows are matched case-insensitively; without them
  * the input is a free term matched the same way. A row lacking the variable never
- * matches. Several filters combine conjunctively.
+ * matches. Several filters combine conjunctively; several values for one
+ * filter (a repeated flag) combine as a union.
  */
 
-import { PragmaError } from "../../error/PragmaError.js";
+import { PragmaError } from "../../error/index.js";
 import type { PackFilter, PackRow } from "../types.js";
 
 /**
@@ -29,23 +30,21 @@ export function applyPackFilters(
   for (const filter of filters ?? []) {
     const provided = params[filter.param];
     if (provided === undefined) continue;
+    // A repeated CLI flag accumulates into an array; MCP args stay scalar.
+    // Several values for ONE filter are a union (a row matches any of them);
+    // several filters still combine conjunctively.
+    const occurrences = Array.isArray(provided) ? provided : [provided];
+    if (occurrences.length === 0) continue;
     const values = filter.values;
-    if (values === undefined) {
-      const term = requireStringValue(provided, filter).toLowerCase();
-      result = result.filter(
-        (row) => row[filter.variable]?.normalize("NFC").toLowerCase() === term,
-      );
-      continue;
-    }
-    const canonical = canonicalizeFilterValue(
-      provided,
-      filter,
-      values,
-    ).toLowerCase();
-    result = result.filter(
-      (row) =>
-        row[filter.variable]?.normalize("NFC").toLowerCase() === canonical,
+    const terms = occurrences.map((occurrence) =>
+      values === undefined
+        ? requireStringValue(occurrence, filter).toLowerCase()
+        : canonicalizeFilterValue(occurrence, filter, values).toLowerCase(),
     );
+    result = result.filter((row) => {
+      const cell = row[filter.variable]?.normalize("NFC").toLowerCase();
+      return cell !== undefined && terms.includes(cell);
+    });
   }
   return result;
 }

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

@@ -4,7 +4,7 @@
  * 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 ("please report this issue").
+ * 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

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

@@ -10,9 +10,8 @@
  * (`graph query`) goes through the facade directly and stays INVALID_INPUT.
  */
 
-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 { PackRow, StorySource } from "../types.js";
 
 /**
@@ -79,7 +78,7 @@ function unboundPrefixError(source: StorySource): PragmaError {
  * 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 ("please report this issue").
+ * "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).
  */

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

@@ -47,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 () => {
@@ -87,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

@@ -267,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

package/src/kernel/packs/uniqueness.ts

@@ -8,7 +8,7 @@
  * 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 {