@canonical/pragma-cli 0.33.0 → 0.35.0

package/src/kernel/packs/resolveEntity.ts

@@ -2,32 +2,48 @@
  * 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, 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,
 } from "./sparql/buildLookupQuery.js";
 import { runSelect } from "./sparql/runSelect.js";
-import type { PackChildRow, PackEntity, PackLookup } from "./types.js";
+import type {
+  PackChildRow,
+  PackEntity,
+  PackLookup,
+  StorySource,
+} from "./types.js";
 
 /** A structured per-query lookup failure (never rejects the whole batch). */
 export interface LookupError {
@@ -56,21 +72,26 @@ export async function resolveLookup(
   lookup: PackLookup,
   noun: string,
   queries: readonly string[],
-  source: string,
+  source: StorySource,
   prefixes: Readonly<Record<string, string>>,
   level: string | undefined,
 ): Promise<LookupOutput> {
   if (queries.length === 0) {
     throw PragmaError.invalidInput("names", "(empty)", {
-      recovery: {
-        message: `List available ${noun} entries.`,
-        cli: `pragma ${noun} list`,
-        mcp: { tool: `${noun}_list` },
-      },
+      recovery: cliRecovery(`${noun} list`, `List available ${noun} entries.`, {
+        tool: `${noun}_list`,
+      }),
     });
   }
 
-  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(
@@ -106,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: 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) {
@@ -124,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,
@@ -144,16 +192,14 @@ async function lookupOne(
   lookup: PackLookup,
   noun: string,
   query: string,
-  source: string,
+  source: StorySource,
   prefixes: Readonly<Record<string, string>>,
   level: string | undefined,
 ): 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);
@@ -161,11 +207,9 @@ async function lookupOne(
     const candidates = await listEntityNames(rt, lookup, source);
     throw PragmaError.notFound(noun, query, {
       suggestions: suggestNames(query, candidates),
-      recovery: {
-        message: `List available ${noun} entries.`,
-        cli: `pragma ${noun} list`,
-        mcp: { tool: `${noun}_list` },
-      },
+      recovery: cliRecovery(`${noun} list`, `List available ${noun} entries.`, {
+        tool: `${noun}_list`,
+      }),
     });
   }
 
@@ -175,7 +219,9 @@ async function lookupOne(
       lookup,
       base.uri,
       base.name ?? query,
-      source,
+      // 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,
     );
@@ -192,24 +238,39 @@ 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, {
       recovery: {
         message:
-          "Use an absolute IRI (https://…), a prefixed name (ds:thing), or a plain entity name.",
+          "Use an absolute IRI (https://…), a prefixed name (prefix:local), or a plain entity name.",
       },
     });
   }
-  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. */
@@ -217,15 +278,52 @@ 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,
   lookup: PackLookup,
-  source: string,
+  source: StorySource,
 ): Promise<string[]> {
   const rows = await runSelect(rt, buildLookupNamesQuery(lookup), source);
   return rows.map((row) => row.name ?? "").filter((name) => name !== "");

package/src/kernel/packs/runBodies.ts

@@ -9,8 +9,8 @@
  * factories carry no heavy static import.
  */
 
-import { PragmaError } from "../error/PragmaError.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 {
@@ -22,14 +22,14 @@ import { parseSampleCount, pickRandom } from "./sample.js";
 import { applyPackFilters } from "./sparql/applyFilters.js";
 import { applyPackSearch } from "./sparql/applySearch.js";
 import { runSelect } from "./sparql/runSelect.js";
-import type { PackList, PackLookup, PackRow } from "./types.js";
+import type { PackList, PackLookup, PackRow, StorySource } from "./types.js";
 
 /** The highest canonical level — sample fetches everything for shape discovery. */
 const HIGHEST_LEVEL = "detailed";
 
 /** Facts a list-shaped run body needs beyond its `shape`. */
 export interface ListRunMeta {
-  readonly source: string;
+  readonly source: StorySource;
 }
 
 /**
@@ -61,7 +61,7 @@ export function makeListRun(
 export function makeLookupRun(
   lookup: PackLookup,
   noun: string,
-  source: string,
+  source: StorySource,
   prefixes: Readonly<Record<string, string>>,
 ): (
   params: Record<string, unknown>,
@@ -88,11 +88,11 @@ export function makeLookupRun(
           code: first.code as PragmaError["code"],
           message: first.message,
           suggestions: first.suggestions ? [...first.suggestions] : undefined,
-          recovery: {
-            message: `List available ${noun} entries.`,
-            cli: `pragma ${noun} list`,
-            mcp: { tool: `${noun}_list` },
-          },
+          recovery: cliRecovery(
+            `${noun} list`,
+            `List available ${noun} entries.`,
+            { tool: `${noun}_list` },
+          ),
         });
       }
     }
@@ -104,7 +104,7 @@ export function makeLookupRun(
 export function makeSampleRun(
   lookup: PackLookup,
   noun: string,
-  source: string,
+  source: StorySource,
   prefixes: Readonly<Record<string, string>>,
   defaultCount: number,
 ): (
@@ -119,11 +119,11 @@ export function makeSampleRun(
     if (names.length === 0) {
       throw PragmaError.emptyResults(noun, {
         message: `No ${noun} entries to sample.`,
-        recovery: {
-          message: `List available ${noun} entries.`,
-          cli: `pragma ${noun} list`,
-          mcp: { tool: `${noun}_list` },
-        },
+        recovery: cliRecovery(
+          `${noun} list`,
+          `List available ${noun} entries.`,
+          { tool: `${noun}_list` },
+        ),
       });
     }
     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

@@ -5,26 +5,38 @@
  * refinements that encode the source rule (§3): `type` XOR `types`, a
  * graphql-sourced lookup names its fragment target, SPARQL expands stay
  * single-hop, GraphQL fields reject property paths, and every disclosure `level`
- * names a declared canonical level.
+ * names a declared canonical level. Two more refinements make the definition
+ * COMPILABLE, not merely well-shaped: distinct compiled verb names and distinct
+ * filter params (see {@link refineVerbNames} / {@link refineFilterParams}).
  *
  * zod lives here and ONLY here in the pack layer, imported lazily (never on the
- * `--help`/`__complete` fast path). Bundled packs are authored in-repo and typed
- * by TypeScript, so `collect` skips validation for them (per-source skip); this
- * runs for config/package packs and in tests.
+ * `--help`/`__complete` fast path). The distribution's own stories are compiled
+ * statically by `capabilities/distribution.ts` and never revalidated at dispatch
+ * (`collect.projectStoryTiers`'s default-origin carve-out); this runs for config-
+ * and package-declared stories, and in `distribution.test.ts`'s round-trip.
  */
 
 import { z } from "zod";
-import { DETAIL_LEVELS } from "../../constants.js";
-import { PragmaError } from "../error/PragmaError.js";
+import { DETAIL_LEVELS, RECOVERY_CLI_PREFIX } from "../../constants.js";
+import { PragmaError } from "../error/index.js";
 import type { PackDefinition } from "./types.js";
 
 const NOUN_PATTERN = /^[a-z][a-z0-9-]*$/;
+/** Message for {@link NOUN_PATTERN} — third-party authors never see the regex. */
+const NOUN_MESSAGE = 'must be lowercase kebab-case, e.g. "design-token"';
 const FILTER_PARAM_PATTERN = /^[a-z][a-z0-9]*$/;
 const FIELD_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const GRAPHQL_NAME_PATTERN = /^[_A-Za-z][_0-9A-Za-z]*$/;
-/** A prefixed name (`ds:Thing`), a property path of them, or an absolute IRI. */
+/**
+ * A prefixed name (`ds:Thing`), a property path of them, or an absolute IRI.
+ * Each path segment may carry the SPARQL inverse marker (`^ds:tier`) — the
+ * contract (`types.ts`) admits "prefixed name, IRI, or path", and an inverse
+ * step IS a property path, so rejecting it here was a schema bug, not a
+ * grammar decision (L-OPEN-9: the tier story's `blocks` expand reads
+ * `^ds:tier`).
+ */
 const TERM_PATTERN =
-  /^(?:[A-Za-z][A-Za-z0-9+.-]*:\/\/[^<>"\s]+|[A-Za-z][\w-]*:[^/<>"\s]+(?:\/[A-Za-z][\w-]*:[^/<>"\s]+)*)$/;
+  /^(?:[A-Za-z][A-Za-z0-9+.-]*:\/\/[^<>"\s]+|\^?[A-Za-z][\w-]*:[^/<>"\s]+(?:\/\^?[A-Za-z][\w-]*:[^/<>"\s]+)*)$/;
 
 /** Params a filter/verb may not claim (they are the shared read vocabulary). */
 const RESERVED_PARAMS = new Set(["search", "detail", "name", "count"]);
@@ -59,9 +71,18 @@ const searchSchema = z
 const emptyRecoverySchema = z
   .object({
     message: z.string().min(1),
+    // The command WITHOUT a binary name — the renderer prepends the CONSUMING
+    // distribution's. A story is portable only if it does not name a binary, so
+    // the old prefixed form is rejected rather than accepted and doubled. Named
+    // loudly, in the `packages` → `packs` tradition, because a third-party pack
+    // written against the old grammar is data, not a typo.
     cli: z
       .string()
-      .startsWith("pragma ", 'emptyRecovery.cli must be a "pragma " command')
+      .min(1)
+      .refine(
+        (value) => !value.startsWith(RECOVERY_CLI_PREFIX),
+        `emptyRecovery.cli is now the command WITHOUT the binary name — write "sources update", not "${RECOVERY_CLI_PREFIX}sources update"`,
+      )
       .optional(),
   })
   .strict();
@@ -78,7 +99,7 @@ const listSchema = z.object(listShape).strict();
 const verbSchema = z
   .object({
     ...listShape,
-    verb: z.string().regex(NOUN_PATTERN),
+    verb: z.string().regex(NOUN_PATTERN, NOUN_MESSAGE),
     description: z.string().optional(),
     toolDescription: z.string().optional(),
   })
@@ -168,6 +189,7 @@ const sampleSchema = z.union([
   z
     .object({
       count: z.number().int().min(1).max(5).optional(),
+      fixedCount: z.boolean().optional(),
       description: z.string().optional(),
       toolDescription: z.string().optional(),
     })
@@ -190,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(),
@@ -202,7 +225,7 @@ const lookupSchema = z
 
 const definitionSchema = z
   .object({
-    noun: z.string().regex(NOUN_PATTERN),
+    noun: z.string().regex(NOUN_PATTERN, NOUN_MESSAGE),
     description: z.string().optional(),
     toolDescription: z.string().optional(),
     list: listSchema.optional(),
@@ -228,9 +251,73 @@ const definitionSchema = z
         path: ["list", "query"],
       });
     }
+    refineVerbNames(def, ctx);
+    if (def.list) refineFilterParams(def.list.filters, ["list"], ctx);
+    for (const [index, verb] of (def.verbs ?? []).entries()) {
+      refineFilterParams(verb.filters, ["verbs", index], ctx);
+    }
     if (def.lookup) refineLookup(def.lookup, ctx);
   });
 
+/**
+ * The compiled `(noun, verb)` keys must be distinct.
+ *
+ * `compilePack` emits `list`, then each `verbs[].verb`, then `lookup` and
+ * `sample`. A repeat there survives the grammar into `assembleEffectiveModules`,
+ * where `assertUniqueVerbs` throws — and package stories reach dispatch before
+ * the command tree exists, so that throw would fail EVERY command, `doctor` and
+ * `sources update` included. The collision is a property of the definition, so
+ * the grammar is where it is caught.
+ */
+function refineVerbNames(
+  def: {
+    list?: unknown;
+    verbs?: readonly { verb: string }[];
+    lookup?: unknown;
+  },
+  ctx: z.RefinementCtx,
+): void {
+  const emitted = new Set<string>(def.list ? ["list"] : []);
+  if (def.lookup) {
+    emitted.add("lookup");
+    if ((def.lookup as { sample?: unknown }).sample) emitted.add("sample");
+  }
+  const seen = new Set<string>();
+  for (const [index, verb] of (def.verbs ?? []).entries()) {
+    if (emitted.has(verb.verb) || seen.has(verb.verb)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `verb "${verb.verb}" is already compiled by this pack — every verb must be distinct.`,
+        path: ["verbs", index, "verb"],
+      });
+    }
+    seen.add(verb.verb);
+  }
+}
+
+/**
+ * Filter params project to CLI options, so a repeat inside one list shape makes
+ * Commander refuse to register the second `--<param>` — outside every error
+ * envelope the CLI owns.
+ */
+function refineFilterParams(
+  filters: readonly { param: string }[] | undefined,
+  path: readonly (string | number)[],
+  ctx: z.RefinementCtx,
+): void {
+  const seen = new Set<string>();
+  for (const [index, filter] of (filters ?? []).entries()) {
+    if (seen.has(filter.param)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `filter param "${filter.param}" is declared twice.`,
+        path: [...path, "filters", index, "param"],
+      });
+    }
+    seen.add(filter.param);
+  }
+}
+
 /** Cross-field lookup rules — the source rule (§3, F8). */
 function refineLookup(
   lookup: z.infer<typeof lookupSchema>,
@@ -246,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;
 }