@canonical/pragma-cli 0.34.0 → 0.36.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,
@@ -32,6 +42,7 @@ import type {
   PackChildRow,
   PackEntity,
   PackLookup,
+  PackRow,
   StorySource,
 } from "./types.js";
 
@@ -43,7 +54,15 @@ export interface LookupError {
   readonly suggestions?: readonly string[];
 }
 
-/** The result of a (possibly multi-name) lookup. */
+/**
+ * The result of a (possibly multi-name) lookup.
+ *
+ * `results` may be LONGER than the arguments that produced it: a name several
+ * entities share answers with all of them, ranked. There is no companion field
+ * naming the ones not answered with, because there are none — an earlier draft
+ * kept the single-entity arity and carried the rest as IRIs in a notice, which
+ * is a sentence about an address where the payload is the address.
+ */
 export interface LookupOutput {
   readonly results: PackEntity[];
   readonly errors: LookupError[];
@@ -70,11 +89,21 @@ export async function resolveLookup(
     throw PragmaError.invalidInput("names", "(empty)", {
       recovery: cliRecovery(`${noun} list`, `List available ${noun} entries.`, {
         tool: `${noun}_list`,
+        // A concrete, valid argument bag rather than a bare tool name: an
+        // agent can call the recovery as written instead of guessing one.
+        params: {},
       }),
     });
   }
 
-  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(
@@ -86,7 +115,7 @@ export async function resolveLookup(
     const query = expanded.names[index];
     if (query === undefined) continue;
     if (outcome.status === "fulfilled") {
-      results.push(outcome.value);
+      results.push(...outcome.value);
       continue;
     }
     const error = outcome.reason;
@@ -110,17 +139,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 +174,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,
@@ -142,7 +198,35 @@ async function expandQueries(
   return { names, globErrors };
 }
 
-/** Look up one entity, dispatching to the pack's declared fetch source. */
+/**
+ * Look up every entity a lookup argument reaches, dispatching to the pack's
+ * declared fetch source.
+ *
+ * One argument, EVERY entity it reaches — ranked, best first.
+ *
+ * `lookup` is deliberately one tool for the singular and the plural case. An
+ * agent that had to decide up front whether a name is unique would pay two
+ * round trips to find out, and the answer is not knowable from the name: 25
+ * live block names reach two or three blocks apiece, and the caller cannot
+ * tell which until it asks. Returning them all costs the caller nothing when a
+ * name is unique — the array is one long — and saves a whole exchange when it
+ * is not.
+ *
+ * That is why the `LIMIT 1` had to go rather than be compensated for. With it,
+ * `block lookup button` answered with Launchpad's Button and gave no sign the
+ * global one existed, because `apps_launchpad…` sorts before `global…`. An
+ * earlier draft of this change kept the arity and named the losers in a notice;
+ * a notice is a sentence about an address, and the payload is the address.
+ *
+ * Ranking still matters, and matters more: it is now what ORDERS the answer
+ * rather than what silently picks it. The best row leads, so a caller reading
+ * only the first gets the entity the ranking believes was meant.
+ *
+ * The rows are collapsed to one per `?uri` first. The sparql form projects its
+ * fields in the same SELECT, so a multi-valued field yields one row per value;
+ * that has always been true and `LIMIT 1` merely hid it. Without the collapse
+ * one entity would report itself as several.
+ */
 async function lookupOne(
   rt: LookupRuntime,
   lookup: PackLookup,
@@ -151,59 +235,94 @@ async function lookupOne(
   source: StorySource,
   prefixes: Readonly<Record<string, string>>,
   level: string | undefined,
-): Promise<PackEntity> {
+): Promise<PackEntity[]> {
   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);
-  if (!base?.uri) {
+  const bases = firstRowPerEntity(rows);
+  if (bases.length === 0) {
     const candidates = await listEntityNames(rt, lookup, source);
     throw PragmaError.notFound(noun, query, {
       suggestions: suggestNames(query, candidates),
       recovery: cliRecovery(`${noun} list`, `List available ${noun} entries.`, {
         tool: `${noun}_list`,
+        // A concrete, valid argument bag rather than a bare tool name: an
+        // agent can call the recovery as written instead of guessing one.
+        params: {},
       }),
     });
   }
 
   if (graphqlSourced) {
-    return fetchGraphqlLookup(
-      rt,
-      lookup,
-      base.uri,
-      base.name ?? query,
-      // The GraphQL lane's only use of the source is CONFIG_ERROR attribution,
-      // which is right for any origin — so it takes the label, not provenance.
-      source.label,
-      prefixes,
-      level,
+    return Promise.all(
+      bases.map((base) =>
+        fetchGraphqlLookup(
+          rt,
+          lookup,
+          String(base.uri),
+          base.name ?? query,
+          // The GraphQL lane's only use of the source is CONFIG_ERROR
+          // attribution, which is right for any origin — so it takes the label,
+          // not provenance.
+          source.label,
+          prefixes,
+          level,
+        ),
+      ),
     );
   }
 
-  const entity: PackEntity = { ...base };
-  for (const expand of activeExpands(lookup, level)) {
-    entity[expand.name] = (await runSelect(
-      rt,
-      buildExpandQuery(expand, base.uri),
-      source,
-    )) as readonly PackChildRow[];
+  const entities: PackEntity[] = [];
+  for (const base of bases) {
+    const entity: PackEntity = { ...base };
+    for (const expand of activeExpands(lookup, level)) {
+      entity[expand.name] = (await runSelect(
+        rt,
+        buildExpandQuery(expand, String(base.uri)),
+        source,
+      )) as readonly PackChildRow[];
+    }
+    entities.push(entity);
+  }
+  return entities;
+}
+
+/** Collapse a ranked resolve to one row per entity, keeping the best-ranked. */
+function firstRowPerEntity(rows: readonly PackRow[]): PackRow[] {
+  const seen = new Set<string>();
+  const bases: PackRow[] = [];
+  for (const row of rows) {
+    if (!row.uri || seen.has(row.uri)) continue;
+    seen.add(row.uri);
+    bases.push(row);
   }
-  return entity;
+  return bases;
 }
 
-/** 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 +332,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 +342,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 {
@@ -20,14 +19,39 @@ import {
   resolveLookup,
 } from "./resolveEntity.js";
 import { parseSampleCount, pickRandom } from "./sample.js";
-import { applyPackFilters } from "./sparql/applyFilters.js";
+import {
+  applyPackFilters,
+  type FilterVocabularies,
+} from "./sparql/applyFilters.js";
 import { applyPackSearch } from "./sparql/applySearch.js";
 import { runSelect } from "./sparql/runSelect.js";
-import type { PackList, PackLookup, PackRow, StorySource } from "./types.js";
+import type {
+  PackFilter,
+  PackList,
+  PackLookup,
+  PackRow,
+  StorySource,
+} from "./types.js";
 
 /** The highest canonical level — sample fetches everything for shape discovery. */
 const HIGHEST_LEVEL = "detailed";
 
+/**
+ * The recovery every lookup-shaped miss carries: browse the noun's list.
+ *
+ * `mcp.params` is populated rather than left off. A bare tool NAME is only half
+ * an instruction to an agent — it still has to guess an argument bag, and a
+ * guess that misses returns `-32602 Invalid arguments`, which reads like the
+ * recovery itself was wrong. `{}` is the concrete, valid call: every compiled
+ * list verb's params are optional, so the recovery is now copy-pasteable.
+ */
+function listRecovery(noun: string) {
+  return cliRecovery(`${noun} list`, `List available ${noun} entries.`, {
+    tool: `${noun}_list`,
+    params: {},
+  });
+}
+
 /** Facts a list-shaped run body needs beyond its `shape`. */
 export interface ListRunMeta {
   readonly source: StorySource;
@@ -46,16 +70,64 @@ export function makeListRun(
   shape: PackList,
   meta: ListRunMeta,
 ): (params: Record<string, unknown>, rt: PragmaRuntime) => Promise<PackRow[]> {
-  return async (params, rt) =>
-    applyPackSearch(
-      applyPackFilters(
-        await runSelect(rt, shape.query, meta.source),
-        shape.filters,
-        params,
-      ),
+  return async (params, rt) => {
+    const rows = await runSelect(rt, shape.query, meta.source);
+    const vocabularies = await readFilterVocabularies(
+      rt,
+      shape.filters,
+      params,
+      meta.source,
+    );
+    return applyPackSearch(
+      applyPackFilters(rows, shape.filters, params, vocabularies),
       shape.search,
       params,
     );
+  };
+}
+
+/**
+ * Read the declared vocabulary of each value-free filter the caller actually
+ * used.
+ *
+ * WHY a second query rather than the rows already in hand: the rows are a
+ * population, not a vocabulary. A category the graph declares with no standards
+ * filed under it, or a `ds:ConceptType` no concept uses yet, is a REAL value
+ * that appears in no row — and rejecting it as `INVALID_INPUT` contradicts both
+ * `standard categories` (which lists it, with count 0) and the documented calm
+ * empty list. The query reads the same terms the enumerating surface reads, so
+ * "the graph is the vocabulary" stays true of the graph rather than of whatever
+ * the list happened to return.
+ *
+ * Only for a filter that is DECLARED with a vocabulary, carries no `values`
+ * (a declared set is already the vocabulary), and was actually PROVIDED — an
+ * unfiltered `list` runs exactly the one query it always did.
+ */
+async function readFilterVocabularies(
+  rt: PragmaRuntime,
+  filters: readonly PackFilter[] | undefined,
+  params: Record<string, unknown>,
+  source: StorySource,
+): Promise<FilterVocabularies | undefined> {
+  const needed = (filters ?? []).filter(
+    (filter) =>
+      filter.vocabulary !== undefined &&
+      filter.values === undefined &&
+      params[filter.param] !== undefined,
+  );
+  if (needed.length === 0) return undefined;
+  const resolved = new Map<string, readonly string[]>();
+  for (const filter of needed) {
+    const vocabulary = filter.vocabulary;
+    if (!vocabulary) continue;
+    const variable = vocabulary.variable ?? filter.variable;
+    const rows = await runSelect(rt, vocabulary.query, source);
+    resolved.set(
+      filter.param,
+      rows.map((row) => row[variable] ?? "").filter((value) => value !== ""),
+    );
+  }
+  return resolved;
 }
 
 /** Build the run body for a lookup verb (variadic names → resolved entities). */
@@ -89,11 +161,7 @@ export function makeLookupRun(
           code: first.code as PragmaError["code"],
           message: first.message,
           suggestions: first.suggestions ? [...first.suggestions] : undefined,
-          recovery: cliRecovery(
-            `${noun} list`,
-            `List available ${noun} entries.`,
-            { tool: `${noun}_list` },
-          ),
+          recovery: listRecovery(noun),
         });
       }
     }
@@ -120,11 +188,7 @@ export function makeSampleRun(
     if (names.length === 0) {
       throw PragmaError.emptyResults(noun, {
         message: `No ${noun} entries to sample.`,
-        recovery: cliRecovery(
-          `${noun} list`,
-          `List available ${noun} entries.`,
-          { tool: `${noun}_list` },
-        ),
+        recovery: listRecovery(noun),
       });
     }
     const selected = pickRandom(names, count);

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-]*$/;
@@ -41,6 +41,16 @@ const TERM_PATTERN =
 /** Params a filter/verb may not claim (they are the shared read vocabulary). */
 const RESERVED_PARAMS = new Set(["search", "detail", "name", "count"]);
 
+/**
+ * Whether an author-supplied query is a SELECT (optionally preceded by its own
+ * PREFIX lines). Every author query a story declares runs through `runSelect`,
+ * which reads `result.bindings` — so a non-SELECT is a shape mismatch caught
+ * here rather than downstream.
+ */
+function isSelectQuery(query: string): boolean {
+  return /^\s*(?:PREFIX\s+[^\n]*\n\s*)*SELECT\s/i.test(query);
+}
+
 const term = z.string().regex(TERM_PATTERN, "must be a prefixed name or IRI");
 const graphqlName = z.string().regex(GRAPHQL_NAME_PATTERN);
 const fieldName = z.string().regex(FIELD_PATTERN);
@@ -49,16 +59,35 @@ const columnSchema = z
   .object({ field: fieldName, label: z.string().optional() })
   .strict();
 
+const vocabularySchema = z
+  .object({
+    query: z.string().min(1),
+    variable: fieldName.optional(),
+  })
+  .strict();
+
 const filterSchema = z
   .object({
     param: z.string().regex(FILTER_PARAM_PATTERN),
     variable: fieldName,
     values: z.array(z.string()).min(1).optional(),
+    match: z.enum(["exact", "set"]).optional(),
+    vocabulary: vocabularySchema.optional(),
     description: z.string().optional(),
   })
   .strict()
   .refine((f) => !RESERVED_PARAMS.has(f.param), {
     message: "filter param is a reserved name",
+  })
+  // A declared `values` set IS the vocabulary — the filter projects it as an
+  // enum and canonicalizes against it. A second, graph-read one alongside would
+  // be a silent no-op at best and a disagreement at worst.
+  .refine((f) => !(f.values && f.vocabulary), {
+    message:
+      '"values" and "vocabulary" are mutually exclusive — a declared value set is already the vocabulary',
+  })
+  .refine((f) => !f.vocabulary || isSelectQuery(f.vocabulary.query), {
+    message: '"vocabulary.query" must be a SPARQL SELECT query',
   });
 
 const searchSchema = z
@@ -204,14 +233,31 @@ const completionSchema = z
   })
   .strict();
 
+/**
+ * The declared scope-ranking factor (`PackScopeWeight`). `falloff` is bounded
+ * the same way `weights` is — a factor outside 0–1 is a promotion, and this
+ * declaration only ever DEMOTES a deeper scope below a shallower one.
+ */
+const scopeWeightSchema = z
+  .object({
+    via: term,
+    by: term,
+    falloff: z.number().min(0).max(1),
+    asserted: term.optional(),
+  })
+  .strict();
+
 const lookupSchema = z
   .object({
     source: z.enum(["sparql", "graphql"]).optional(),
     by: term,
+    nameFallback: z.enum(["iri"]).optional(),
     type: term.optional(),
     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(),
+    scopeWeight: scopeWeightSchema.optional(),
     graphqlType: graphqlName.optional(),
     fields: z.array(fieldSchema).min(1).optional(),
     sections: z.array(sectionSchema).min(1).optional(),
@@ -240,10 +286,7 @@ const definitionSchema = z
         message: 'a pack must declare at least one of "list" or "lookup".',
       });
     }
-    if (
-      def.list &&
-      !/^\s*(?:PREFIX\s+[^\n]*\n\s*)*SELECT\s/i.test(def.list.query)
-    ) {
+    if (def.list && !isSelectQuery(def.list.query)) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
         message: '"list.query" must be a SPARQL SELECT query.',
@@ -332,6 +375,36 @@ function refineLookup(
     });
   }
 
+  // An IRI-derived name is only as trustworthy as the class vouching for the
+  // entity it came from, and without a class constraint nothing bounds the scan
+  // the derived-name population would run. Rejected rather than ignored, for the
+  // same reason a stale weight is: a silent no-op is how a declaration that
+  // never applied survives review.
+  if (lookup.nameFallback !== undefined && !lookup.type && !lookup.types) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message:
+        '"lookup.nameFallback" requires a class constraint ("lookup.type" or "lookup.types") to vouch for the entities it names.',
+      path: ["lookup", "nameFallback"],
+    });
+  }
+
+  // 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,