@canonical/pragma-cli 0.36.0 → 0.38.0

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

@@ -5,7 +5,8 @@
  * and which properties to read; the query text is generated here so
  * 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 name is exact and case-insensitive.
+ * Matching on the name is exact, and insensitive to case and to surrounding
+ * whitespace — see {@link nameFilter}.
  *
  * WHAT an entity's name IS lives in one place — {@link nameBinding} — and every
  * form here uses it: the asserted `by` value, plus, for a lookup that DECLARES
@@ -49,9 +50,49 @@
  */
 
 import { activeExpands, activeFields } from "../disclosure.js";
-import type { PackExpand, PackLookup } from "../types.js";
+import {
+  type PackExpand,
+  type PackExpandField,
+  type PackLookup,
+  RESERVED_VARIABLE_PREFIX,
+} from "../types.js";
 import { escapeSparqlString, formatTerm } from "./escape.js";
 
+/**
+ * The variable a scoped name resolve reports each match's tier in.
+ *
+ * Under the reserved prefix because it is the kernel's, not the story's: it
+ * exists so the resolver can tell an in-scope match from an out-of-scope one,
+ * and it is stripped before an entity is handed to a formatter
+ * ({@link ../resolveEntity}) so no answer grows a field a caller did not ask
+ * for.
+ */
+export const SCOPE_TIER_VARIABLE = "__pragmaTier";
+
+/**
+ * Report each match's tier, for a name resolve over a SCOPED noun.
+ *
+ * A name resolve RANKS and returns everything the name reaches, so the scope
+ * does not need to be a filter here — the resolver prefers the in-scope matches
+ * and falls back to the rest, which is what lets `block lookup button` answer
+ * the global Button while still being able to answer at all for a name that
+ * lives only in one product's tier. All it needs from the query is WHICH tier
+ * each match belongs to.
+ *
+ * `OPTIONAL`, so an entity with no tier is still reached: not being in any tier
+ * is not a reason to be unaddressable by name.
+ */
+function scopeTierProjection(via: string | undefined): {
+  variable: string;
+  optional: string;
+} {
+  if (via === undefined) return { variable: "", optional: "" };
+  return {
+    variable: ` ?${SCOPE_TIER_VARIABLE}`,
+    optional: `  OPTIONAL { ?uri ${formatTerm(via)} ?${SCOPE_TIER_VARIABLE} . }`,
+  };
+}
+
 /**
  * The class-constraint clause for a lookup: a single `a` triple for `type`, a
  * VALUES-constrained type triple for `types`, or nothing. All terms are
@@ -121,13 +162,17 @@ const DERIVED_NAME = 'REPLACE(REPLACE(STR(?uri), "^.*[#/]", ""), "\\\\.", "/")';
  *
  * A story whose `list` SYNTHESIZES a name instead of reading one declares
  * `nameFallback: "iri"`, and then the triple becomes OPTIONAL with
- * {@link DERIVED_NAME} behind it. `standard` is the case that exists: 22 of the
- * 156 live code standards carry a `cs:name`, and the code-standards ontology
- * says so deliberately — it is "an optional human-readable display title" that
- * "never participates in identity". `standard list` published
- * `react/component/tsdoc` while `standard lookup react/component/tsdoc`
- * answered ENTITY_NOT_FOUND with empty suggestions, because the only
- * addressable population was the ~13% carrying an asserted name.
+ * {@link DERIVED_NAME} behind it. `standard` is the case that exists. When the
+ * defect was measured, 22 of the then-156 live code standards carried a
+ * `cs:name`, and the code-standards ontology said so deliberately — "an
+ * optional human-readable display title" that "never participates in
+ * identity". `standard list` published `react/component/tsdoc` while
+ * `standard lookup react/component/tsdoc` answered ENTITY_NOT_FOUND with
+ * empty suggestions, because the only addressable population was the ~13%
+ * carrying an asserted name. (Upstream has since retired `cs:name` for
+ * `rdfs:label`, which every standard carries; the fallback stays because a
+ * pack is data, and a dropped label must degrade to the derived name rather
+ * than become unaddressable.)
  *
  * INFERRING the fallback from the mere PRESENCE of a class constraint is what
  * this option replaced, and it was over-reach in both directions of the same
@@ -344,12 +389,43 @@ function rankingClause(lookup: PackLookup): {
   };
 }
 
+/**
+ * The name FILTER both name-addressed resolves share.
+ *
+ * A name is matched insensitively to case AND to the whitespace it is padded
+ * with, because the padding is an artefact of where the name came from rather
+ * than part of the name. Sixty-six `ds:name` literals in the shipped graph end
+ * in a space, copied across from the source document, and `block lookup
+ * Timeline` answered ENTITY_NOT_FOUND while offering "Timeline " straight back
+ * as a suggestion — the query and the answer differing by a character no
+ * surface prints and no user can type deliberately. The upstream transform is
+ * being corrected separately; a resolve a stray space can defeat is a defect on
+ * its own, and this is where that half is fixed.
+ *
+ * BOTH sides are trimmed, never one: the store side by REPLACE over the two
+ * anchored runs, the argument side in TypeScript before it is escaped into the
+ * literal. Trimming only `?name` would leave `block lookup "Button "` — a name
+ * pasted out of a table cell — missing an entity whose own name is clean.
+ *
+ * The regex the engine reads is `^\s+|\s+$` — the doubled backslashes in the
+ * source are the SPARQL string-literal escape and not part of the pattern.
+ * Verified against the pinned oxigraph, whose REPLACE takes both the `\s`
+ * class and the alternation, and whose `^`/`$` anchor the whole value rather
+ * than each line of it.
+ *
+ * @param name - The user-supplied name, untrimmed and unescaped.
+ * @returns The FILTER line to splice into the WHERE clause.
+ */
+function nameFilter(name: string): string {
+  return `  FILTER (LCASE(REPLACE(STR(?name), "^\\\\s+|\\\\s+$", "")) = LCASE("${escapeSparqlString(name.trim())}"))`;
+}
+
 /**
  * Build the SELECT retrieving the entities a name reaches, with their declared
  * fields, best first. The caller answers with the first and names the rest.
  *
  * @param lookup - The pack's lookup declaration.
- * @param name - User-supplied entity name (escaped here).
+ * @param name - User-supplied entity name (trimmed and escaped here).
  * @param level - Active canonical level; gated fields below it are excluded.
  * @returns SPARQL SELECT text, ranked and unlimited.
  */
@@ -357,16 +433,19 @@ export function buildLookupQuery(
   lookup: PackLookup,
   name: string,
   level?: string,
+  scopeVia?: string,
 ): string {
   const { header, constraint, optionals } = lookupProjection(lookup, level);
   const ranking = rankingClause(lookup);
+  const scope = scopeTierProjection(scopeVia);
   return [
-    header,
+    header.replace(" WHERE {", `${scope.variable} WHERE {`),
     constraint,
     nameBinding(lookup),
     ranking.binds,
     optionals,
-    `  FILTER (LCASE(STR(?name)) = LCASE("${escapeSparqlString(name)}"))`,
+    scope.optional,
+    nameFilter(name),
     "}",
     ranking.orderBy,
   ]
@@ -410,7 +489,7 @@ export function buildLookupByIriQuery(
  * Build the minimal name→URI resolve for a graphql-sourced lookup (and the
  * shared entry point for the sparql path's name form): maps the user-supplied
  * name to the entity IRIs, everything else comes from the field fetch. The name
- * is an escaped literal; all terms are validated pack terms.
+ * is a trimmed, escaped literal; all terms are validated pack terms.
  *
  * Ranked and unlimited, exactly like {@link buildLookupQuery} — the two paths
  * differ in where the VALUES come from, never in which entities a name reaches.
@@ -421,14 +500,17 @@ export function buildLookupByIriQuery(
 export function buildNameResolveQuery(
   lookup: PackLookup,
   name: string,
+  scopeVia?: string,
 ): string {
   const ranking = rankingClause(lookup);
+  const scope = scopeTierProjection(scopeVia);
   return [
-    "SELECT ?uri ?name WHERE {",
+    `SELECT ?uri ?name${scope.variable} WHERE {`,
     buildTypeConstraint(lookup).trimEnd(),
     nameBinding(lookup),
     ranking.binds,
-    `  FILTER (LCASE(STR(?name)) = LCASE("${escapeSparqlString(name)}"))`,
+    scope.optional,
+    nameFilter(name),
     "}",
     ranking.orderBy,
   ]
@@ -479,27 +561,65 @@ export function buildLookupIrisQuery(lookup: PackLookup): string {
  *
  * Injection-safe: the only interpolated value is `entityUri`, the IRI the base
  * lookup already resolved from the store (never user input); the
- * relation/properties are validated pack terms. SPARQL expands are single-hop,
- * so every select entry here is a plain field.
+ * relation/properties, the ordering names and the entity's identity property
+ * are validated pack terms. SPARQL expands are single-hop, so every select
+ * entry here is a plain field.
+ *
+ * `lookup` is read for ONE thing — the entity's own identity property, which a
+ * `blankWhenSelf` field compares its value against. A lookup declaring no such
+ * field never binds it.
  */
 export function buildExpandQuery(
   expand: PackExpand,
   entityUri: string,
+  lookup?: Pick<PackLookup, "by">,
 ): string {
   const vars = expand.select.map((field) => `?${field.name}`).join(" ");
   const optionals = expand.select
     .map((field) =>
-      "property" in field
-        ? `  OPTIONAL { ?child ${formatTerm(field.property)} ?${field.name} . }`
-        : "",
+      "property" in field ? expandFieldClause(field, entityUri, lookup) : "",
     )
     .filter((line) => line !== "")
     .join("\n");
+  const order =
+    expand.orderBy && expand.orderBy.length > 0
+      ? `ORDER BY ${expand.orderBy.map((name) => `?${name}`).join(" ")}`
+      : "";
   return [
     `SELECT ${vars} WHERE {`,
     `  <${entityUri}> ${formatTerm(expand.relation)} ?child .`,
     optionals,
     "}",
+    order,
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}
+
+/**
+ * The OPTIONAL clause reading one child field.
+ *
+ * A plain field is one line. A `blankWhenSelf` field binds the ENTITY's own
+ * identity value beside the child's and keeps the row only where the two
+ * differ — inside the OPTIONAL, so a match leaves the variable UNBOUND (the
+ * blank cell) rather than dropping the child row. Compared as strings, because
+ * the identity value is a literal and the cell may be read through a path that
+ * ends at one too.
+ */
+function expandFieldClause(
+  field: PackExpandField,
+  entityUri: string,
+  lookup?: Pick<PackLookup, "by">,
+): string {
+  const read = `?child ${formatTerm(field.property)} ?${field.name} .`;
+  if (!field.blankWhenSelf || !lookup) return `  OPTIONAL { ${read} }`;
+  const self = `?${RESERVED_VARIABLE_PREFIX}Self`;
+  return [
+    "  OPTIONAL {",
+    `    ${read}`,
+    `    <${entityUri}> ${formatTerm(lookup.by)} ${self} .`,
+    `    FILTER(STR(?${field.name}) != STR(${self}))`,
+    "  }",
   ].join("\n");
 }
 

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

@@ -0,0 +1,86 @@
+/**
+ * One rejected filter value, ONE list of the values it should have been.
+ *
+ * `variable list --symbol nope` printed the 40-name head of a 745-name
+ * vocabulary twice — once as the options line, once inside the recovery
+ * message, about 1.4KB of duplicate terminal output. The vocabulary rides
+ * `validOptions`, which every renderer already spells out, truncates and
+ * counts; a recovery says what to DO.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  type PragmaError,
+  renderErrorLlm,
+  renderErrorPlain,
+} from "../../error/index.js";
+import type { PackFilter } from "../types.js";
+import { resolveFilterPredicates } from "./filterValues.js";
+
+/** The 745-name catalogue that made the duplication measurable. */
+const VOCABULARY = Array.from({ length: 745 }, (_, i) => `color.text.${i}`);
+
+const FREE_FILTER: PackFilter = { param: "symbol", variable: "symbol" };
+const SET_FILTER: PackFilter = {
+  param: "type",
+  variable: "type",
+  values: ["color", "dimension", "duration"],
+};
+
+/** The error a filter raises for a value it does not admit. */
+function rejection(
+  filter: PackFilter,
+  value: string,
+  vocabulary?: readonly string[],
+): PragmaError {
+  try {
+    resolveFilterPredicates(
+      [filter],
+      { [filter.param]: value },
+      vocabulary ? new Map([[filter.param, vocabulary]]) : undefined,
+      "test:story",
+    );
+  } catch (error) {
+    return error as PragmaError;
+  }
+  throw new Error("the filter admitted a value it should have refused");
+}
+
+/** How many times `needle` appears in `text`. */
+const occurrences = (text: string, needle: string): number =>
+  text.split(needle).length - 1;
+
+describe("a refused filter value names its vocabulary once", () => {
+  it("renders the catalogue once, not twice", () => {
+    const error = rejection(FREE_FILTER, "nope", VOCABULARY);
+    const plain = renderErrorPlain(error);
+
+    expect(occurrences(plain, "color.text.0,")).toBe(1);
+    expect(plain).toContain("Valid options (745), first 40:");
+    // The recovery says what to do, and names the flag — without the list.
+    expect(plain).toContain("Pick one of the 745 values --symbol accepts.");
+    expect(renderErrorLlm(error)).toContain("Pick one of the 745 values");
+    expect(occurrences(renderErrorLlm(error), "color.text.0,")).toBe(1);
+  });
+
+  it("keeps the whole vocabulary on the machine channel", () => {
+    // Truncation is a RENDERING decision; a machine consumer loses nothing.
+    expect(rejection(FREE_FILTER, "nope", VOCABULARY).validOptions).toEqual(
+      [...VOCABULARY].sort(),
+    );
+  });
+
+  it("says it once for a declared set too", () => {
+    const plain = renderErrorPlain(rejection(SET_FILTER, "nope"));
+
+    expect(occurrences(plain, "dimension")).toBe(1);
+    expect(plain).toContain("Valid options: color, dimension, duration");
+    expect(plain).toContain("Pick one of the 3 values --type accepts.");
+  });
+
+  it("a short vocabulary stays cheap to read", () => {
+    const plain = renderErrorPlain(rejection(SET_FILTER, "nope"));
+
+    expect(plain.length).toBeLessThan(200);
+  });
+});

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

@@ -0,0 +1,182 @@
+/**
+ * Admit (or refuse) the values a caller supplied for a list story's declared
+ * filters, and hand the admitted ones to the query builder.
+ *
+ * This is the half of filtering that does NOT move into the query. Deciding
+ * whether a value is admissible is a question about the graph's vocabulary;
+ * deciding which rows carry it is a question about the population. Keeping them
+ * apart is what makes the two answers a caller gets distinguishable, and that
+ * distinction is load-bearing:
+ *
+ * - a value the vocabulary does NOT admit is `INVALID_INPUT`, carrying the
+ *   admissible values as `validOptions` — the caller mistyped;
+ * - a value it DOES admit that no row carries is a calm empty list, exit 0,
+ *   with the story's own `emptyRecovery` as the hint — `standard categories`
+ *   reports a category with count 0, and asking for it is not a mistake.
+ *
+ * WHICH part of the graph is the vocabulary matters, and it is not the rows.
+ * Before the filters moved inside the query the rows were the FALLBACK
+ * vocabulary for a filter that declared none — knowingly narrower than the
+ * truth, but the only evidence there was. A page makes that fallback actively
+ * wrong: a real value outside the window would be refused as a bad argument,
+ * with a truncated list of alternatives. So the fallback is gone and the
+ * declaration rule replaces it — a filter declares `values` or a `vocabulary`
+ * query, and one that declares neither is refused where it is declared
+ * ({@link ../schema}) rather than misanswering at run time.
+ */
+
+import { PragmaError } from "../../error/index.js";
+import type { PackFilter } from "../types.js";
+import type { ListPredicate } from "./buildListQuery.js";
+
+/**
+ * Authoritative values per filter `param`, read from each filter's declared
+ * `vocabulary`. A filter with declared `values` needs no entry — the set IS the
+ * vocabulary.
+ */
+export type FilterVocabularies = ReadonlyMap<string, readonly string[]>;
+
+/**
+ * Turn the filter arguments a caller supplied into query predicates.
+ *
+ * @param filters - The story's declared filters (absent means none).
+ * @param params - Story parameters as provided by the surface.
+ * @param vocabularies - Authoritative values per value-free filter param.
+ * @param label - The story's label, for a configuration diagnosis.
+ * @returns One predicate per filter the caller supplied a value for.
+ * @throws PragmaError INVALID_INPUT when a value is not in a filter's declared
+ *   set or its graph vocabulary, or when a value-free filter receives a
+ *   non-string value; CONFIG_ERROR when a value-free filter declares no
+ *   vocabulary.
+ */
+export function resolveFilterPredicates(
+  filters: readonly PackFilter[] | undefined,
+  params: Record<string, unknown>,
+  vocabularies: FilterVocabularies | undefined,
+  label: string,
+): ListPredicate[] {
+  const predicates: ListPredicate[] = [];
+  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;
+    const terms = occurrences.map((occurrence) =>
+      values === undefined
+        ? requireStringValue(occurrence, filter)
+        : canonicalizeFilterValue(occurrence, filter, values),
+    );
+    if (values === undefined) {
+      rejectUnknownValue(
+        requireVocabulary(filter, vocabularies, label),
+        filter,
+        occurrences,
+        terms,
+      );
+    }
+    predicates.push({
+      variable: filter.variable,
+      match: filter.match ?? "exact",
+      terms,
+    });
+  }
+  return predicates;
+}
+
+/**
+ * The vocabulary a value-free filter is checked against.
+ *
+ * @throws PragmaError CONFIG_ERROR when the filter declares neither `values`
+ *   nor a `vocabulary` — the declaration rule the schema enforces, restated at
+ *   the point of use so a story that reached here another way still says why.
+ */
+function requireVocabulary(
+  filter: PackFilter,
+  vocabularies: FilterVocabularies | undefined,
+  label: string,
+): readonly string[] {
+  const vocabulary = vocabularies?.get(filter.param);
+  if (vocabulary) return vocabulary;
+  throw PragmaError.configError(
+    `Filter "--${filter.param}" in ${label} declares neither "values" nor a ` +
+      '"vocabulary" query, so there is nothing to check a caller\'s value against.',
+  );
+}
+
+/**
+ * Reject a value-free filter value the vocabulary does not admit, naming the
+ * ones it does.
+ *
+ * Silent when the vocabulary is EMPTY: an unbuilt or genuinely-empty store is
+ * not the caller's mistake, and the list's own `emptyRecovery` is the right
+ * voice for it.
+ *
+ * A value the vocabulary admits is never rejected here even when no row carries
+ * it — a real slug with zero standards is a calm empty list, which is what the
+ * tool descriptions document and what `standard categories` reporting count 0
+ * promises.
+ *
+ * @throws PragmaError INVALID_INPUT when a term matches none of the admissible
+ *   values, carrying them as `validOptions`.
+ */
+function rejectUnknownValue(
+  vocabulary: readonly string[],
+  filter: PackFilter,
+  occurrences: readonly unknown[],
+  terms: readonly string[],
+): void {
+  const admissible = new Map<string, string>();
+  for (const value of vocabulary) {
+    const key = value.normalize("NFC").toLowerCase();
+    if (!admissible.has(key)) admissible.set(key, value.normalize("NFC"));
+  }
+  if (admissible.size === 0) return;
+  const index = terms.findIndex((term) => !admissible.has(term.toLowerCase()));
+  if (index === -1) return;
+  const validOptions = [...admissible.values()].sort();
+  // The VALUES ride `validOptions`, which every renderer already prints (and
+  // truncates, and counts). Repeating them in the recovery printed the same
+  // 40-name, 1.4KB list twice on one error — see `error/validOptions.ts`.
+  throw PragmaError.invalidInput(filter.param, String(occurrences[index]), {
+    validOptions,
+    recovery: {
+      message: `Pick one of the ${validOptions.length} values --${filter.param} accepts.`,
+    },
+  });
+}
+
+/** @throws PragmaError INVALID_INPUT when a value-free filter value is not a string. */
+function requireStringValue(provided: unknown, filter: PackFilter): string {
+  if (typeof provided !== "string") {
+    throw PragmaError.invalidInput(filter.param, String(provided), {
+      recovery: { message: `Provide a string value for --${filter.param}.` },
+    });
+  }
+  return provided.trim().normalize("NFC");
+}
+
+/** @throws PragmaError INVALID_INPUT when the value is not in the declared set. */
+function canonicalizeFilterValue(
+  provided: unknown,
+  filter: PackFilter,
+  values: readonly string[],
+): string {
+  if (typeof provided === "string") {
+    const normalized = provided.trim().normalize("NFC");
+    const match = values.find(
+      (value) =>
+        value.normalize("NFC").toLowerCase() === normalized.toLowerCase(),
+    );
+    if (match !== undefined) return match.normalize("NFC");
+  }
+  throw PragmaError.invalidInput(filter.param, String(provided), {
+    validOptions: [...values],
+    recovery: {
+      message: `Pick one of the ${values.length} values --${filter.param} accepts.`,
+    },
+  });
+}

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

@@ -1,22 +1,31 @@
 /**
- * The SPARQL path — every generated read a pack story performs, and the two
- * row operations that must NOT be generated.
+ * The SPARQL path — every generated read a pack story performs.
  *
  * 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.
+ * TEXT. The query builders compose only from validated pack terms, the page's
+ * own integers, and escaped literals bound through `VALUES` — 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 used to sit here as predicates over the resolved ROWS —
+ * kept in this domain precisely because they were the operations it would
+ * otherwise be tempting to express as query text. They are query text now, and
+ * the temptation is answered a different way: {@link ./buildListQuery} is the
+ * only thing that composes a predicate, it binds every caller-supplied value,
+ * and it never edits the author's own query. What stayed on the row side is the
+ * part that was never about rows at all — deciding whether a value is
+ * ADMISSIBLE ({@link ./filterValues}), which is a question about the graph's
+ * vocabulary and is what keeps a refusal distinguishable from a calm empty
+ * answer.
  *
  * 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.
+ * the shape this domain exists to prevent. {@link ./projection}'s reader is
+ * internal for the same reason: it exists so a wrapping select can reproduce
+ * the author's own projection, not so callers can reason about author text.
  *
  * Two names re-exported by `buildLookupQuery.ts` for its own callers'
  * convenience — the disclosure-level field and expand selectors — are also
@@ -25,8 +34,12 @@
  * pass-through that has no reason to be permanent.
  */
 
-export { applyPackFilters } from "./applyFilters.js";
-export { applyPackSearch } from "./applySearch.js";
+export type {
+  ListPredicate,
+  ListSearch,
+  ListWindow,
+} from "./buildListQuery.js";
+export { buildListQuery } from "./buildListQuery.js";
 export {
   buildExpandQuery,
   buildLookupByIriQuery,
@@ -34,4 +47,7 @@ export {
   buildLookupQuery,
   buildNameResolveQuery,
 } from "./buildLookupQuery.js";
+export type { FilterVocabularies } from "./filterValues.js";
+export { resolveFilterPredicates } from "./filterValues.js";
 export { runSelect } from "./runSelect.js";
+export { readSearchTerm } from "./searchTerm.js";

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

@@ -172,3 +172,66 @@ describe("runSelect — an unbound prefix is diagnosed by PROVENANCE", () => {
     }
   });
 });
+
+describe("runSelect — one SECTION degrades where the answer itself raises", () => {
+  const unbound = (): Error => new Error("Prefix not found: anatomy");
+
+  it("answers no rows for a section whose vocabulary the store does not bind", async () => {
+    // A lookup's section can name a vocabulary from a different pack than the
+    // entity's: a block is `ds:`, and the style key and state of the tokens it
+    // consumes are the anatomy DSL's. Taking the whole entity down over one
+    // absent section would fail `block lookup` outright on a graph that can
+    // answer every other section — so the section renders empty, which is what
+    // the lookup's GraphQL lane already does with the same condition.
+    //
+    // It cannot hide an unbuilt store: a section is only read after the base
+    // resolve has already answered from it.
+    const rows = await runSelect(
+      throwingRuntime(unbound()),
+      "SELECT ?key WHERE { ?child anatomy:styleKey ?key }",
+      distributionSource("pragma.conf.ts"),
+      { degradeOnUnboundPrefix: true },
+    );
+    expect(rows).toEqual([]);
+  });
+
+  it("degrades for a package and config story too, by the same rule", async () => {
+    // The provenance split above is about WHICH error an unbound prefix is. A
+    // section that degrades raises none, so there is nothing left to diagnose
+    // — and a third party's section is no more entitled to take an entity down
+    // than the distribution's.
+    for (const source of [PACKAGE, CONFIG]) {
+      expect(
+        await runSelect(
+          throwingRuntime(unbound()),
+          "SELECT ?x WHERE { ?x a acme:Thing }",
+          source,
+          { degradeOnUnboundPrefix: true },
+        ),
+      ).toEqual([]);
+    }
+  });
+
+  it("still passes a non-prefix failure through, and still refuses a non-SELECT", async () => {
+    // Narrow by construction: the ONE condition it swallows is the one that
+    // says "this pack's vocabulary is narrower than the story's". Everything
+    // else is a bug and still raises.
+    const boom = new Error("some other engine failure");
+    await expect(
+      runSelect(throwingRuntime(boom), "SELECT ?x WHERE {}", PACKAGE, {
+        degradeOnUnboundPrefix: true,
+      }),
+    ).rejects.toBe(boom);
+
+    const askRuntime = {
+      query: {
+        sparql: async () => ({ type: "ask", boolean: true }),
+      } as unknown as PragmaRuntime["query"],
+    };
+    await expect(
+      runSelect(askRuntime, "ASK { ?x ?y ?z }", PACKAGE, {
+        degradeOnUnboundPrefix: true,
+      }),
+    ).rejects.toMatchObject({ code: "CONFIG_ERROR" });
+  });
+});