@canonical/pragma-cli 0.35.0 → 0.36.0

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

@@ -485,6 +485,98 @@ describe("weights validation (a weight that can never apply is rejected)", () =>
   });
 });
 
+describe("nameFallback validation (a derived name needs a class to vouch for it)", () => {
+  it("accepts the fallback beside a class constraint", () => {
+    const definition = {
+      noun: "gadget",
+      lookup: { by: "ex:name", nameFallback: "iri", type: "ex:Widget" },
+    };
+    expect(parsePackDefinition(definition, "t")).toEqual(definition);
+  });
+
+  it("REJECTS the fallback with no class constraint", () => {
+    // Without one there is no triple bounding `?uri`, so the derived-name
+    // population would be scanned over the whole graph — and a derived name is
+    // only as trustworthy as the class vouching for the entity it came from.
+    expect(() =>
+      parsePackDefinition(
+        { noun: "gadget", lookup: { by: "ex:name", nameFallback: "iri" } },
+        "t",
+      ),
+    ).toThrow(/nameFallback/);
+  });
+});
+
+describe("filter vocabulary validation (where a value-free filter's values live)", () => {
+  const listShape = {
+    query: "SELECT ?uri ?kind WHERE { ?uri a ex:Widget ; ex:kind ?kind }",
+    columns: [{ field: "uri" }],
+  };
+
+  it("accepts a vocabulary SELECT on a value-free filter", () => {
+    const definition = {
+      noun: "widget",
+      list: {
+        ...listShape,
+        filters: [
+          {
+            param: "kind",
+            variable: "kind",
+            vocabulary: { query: "SELECT ?kind WHERE { ?k a ex:Kind }" },
+          },
+        ],
+      },
+    };
+    expect(parsePackDefinition(definition, "t")).toEqual(definition);
+  });
+
+  it("REJECTS a vocabulary beside a declared `values` set", () => {
+    // A declared set IS the vocabulary — the filter projects it as an enum and
+    // canonicalizes against it. A second, graph-read one alongside is a silent
+    // no-op at best and a disagreement at worst.
+    expect(() =>
+      parsePackDefinition(
+        {
+          noun: "widget",
+          list: {
+            ...listShape,
+            filters: [
+              {
+                param: "kind",
+                variable: "kind",
+                values: ["a", "b"],
+                vocabulary: { query: "SELECT ?kind WHERE { ?k a ex:Kind }" },
+              },
+            ],
+          },
+        },
+        "t",
+      ),
+    ).toThrow(/mutually exclusive/);
+  });
+
+  it("REJECTS a vocabulary query that is not a SELECT", () => {
+    expect(() =>
+      parsePackDefinition(
+        {
+          noun: "widget",
+          list: {
+            ...listShape,
+            filters: [
+              {
+                param: "kind",
+                variable: "kind",
+                vocabulary: { query: "ASK { ?k a ex:Kind }" },
+              },
+            ],
+          },
+        },
+        "t",
+      ),
+    ).toThrow(/SELECT/);
+  });
+});
+
 describe("compileListable — absolute IRIs reach the prefixed contract", () => {
   it("compacts an absolute lookup type, and its weight key with it", () => {
     // `PackLookup.type`/`types` accept a prefixed name OR an absolute IRI, but

package/src/kernel/packs/renderPack.ts

@@ -55,7 +55,7 @@ export interface RenderMeta {
  * list on a BUILT store (a cold store would have failed with STORE_UNAVAILABLE
  * first) means "nothing matched", so point at both possible fixes.
  */
-const DEFAULT_EMPTY_HINT = `Build the store with \`${BIN_NAME} sources update\`, or broaden the filter or channel.`;
+const DEFAULT_EMPTY_HINT = `Either nothing matched — try a wider filter — or the store has nothing in it yet: build it with \`${BIN_NAME} sources update\`.`;
 
 /** Build the list formatters for a list-shaped verb (list or an extra verb). */
 export function listFormatters(
@@ -89,7 +89,7 @@ export function listFormatters(
     json: (rows) => JSON.stringify(rows, null, 2),
     // Zero rows: the dispatcher routes this to stderr (exit 0) so the plain
     // stdout stream stays pure data; llm/json keep their own empty shapes.
-    emptyNotice: (rows) =>
+    notice: (rows) =>
       rows.length === 0 ? renderListEmptyNotice(options) : undefined,
   };
 }
@@ -132,7 +132,7 @@ export function lookupOptions(
   };
 }
 
-/** Build the lookup formatters (renders every resolved entity, then any errors). */
+/** Build the lookup formatters (every resolved entity, then errors, then the notice). */
 export function lookupFormatters(
   lookup: PackLookup,
   prefixes: Readonly<Record<string, string>>,

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

@@ -7,8 +7,18 @@
  * and nothing else — as accepting a name, a prefixed name, an absolute IRI, or
  * a glob. These assert that the resolver honours the shape it is handed rather
  * than the source its pack declares, that an entity is addressable by IRI even
- * when it carries no `by` value, and that an ambiguous name resolves to the
- * same entity on every store and every machine.
+ * when it carries no `by` value, and that an ambiguous name answers with the
+ * same entity on every store and every machine — while NAMING the ones it did
+ * not answer with.
+ *
+ * That last clause is a REVERSAL, signed off by the owner. It used to read "an
+ * ambiguous name resolves to the SAME entity every time", and the suite proved
+ * it: a total `ORDER BY` under a `LIMIT 1` does make the answer reproducible.
+ * It just made it reproducibly SILENT — `block lookup button` answered with
+ * Launchpad's Button on every machine, because `apps_launchpad…` sorts before
+ * `global…`, and nothing in the payload said the global one existed. The arity
+ * is unchanged and deliberately so; what the old assertions took for the whole
+ * property, determinism, was only half of it.
  */
 
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
@@ -20,7 +30,7 @@ import {
 import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
 import type { PragmaRuntime } from "../runtime/types.js";
 import { compilePack } from "./compile.js";
-import { lookupOptions } from "./renderPack.js";
+import { lookupFormatters, lookupOptions } from "./renderPack.js";
 import type { LookupOutput } from "./resolveEntity.js";
 import type { PackDefinition, PackLookup } from "./types.js";
 import { distributionSource } from "./types.js";
@@ -79,6 +89,14 @@ describe("pack lookup addressing (PROTECTED)", () => {
     return verb.run({ name }, rt) as Promise<LookupOutput>;
   };
 
+  const lookupNoticeVia = (
+    definition: PackDefinition,
+    out: LookupOutput,
+  ): string | undefined =>
+    lookupFormatters(definition.lookup as PackLookup, BLOCK_PREFIXES).notice?.(
+      out,
+    );
+
   const uris = (out: LookupOutput): string[] =>
     out.results.map((entity) => String(entity.uri));
 
@@ -182,32 +200,75 @@ describe("pack lookup addressing (PROTECTED)", () => {
     });
   });
 
-  describe("an ambiguous name resolves to the SAME entity every time", () => {
+  describe("an ambiguous name answers with EVERY entity it reaches", () => {
     // `ds:zeta.chip` is declared BEFORE `ds:alpha.chip` in the fixture, so the
-    // store enumerates it first while IRI order puts `alpha` first. Without an
-    // explicit ORDER BY the winner is whichever the store happens to yield —
-    // exactly the cross-tier `Button` ambiguity in the live graph.
-    it("picks the lowest IRI on the sparql path", async () => {
+    // store enumerates it first while IRI order puts `alpha` first. Neither of
+    // these stories declares a ranking, so the order is the total `STR(?uri)`
+    // it always was — what changed is that BOTH chips come back. Both paths,
+    // because the resolve is generated SPARQL either way and only the field
+    // fetch differs.
+    it("answers with both, best first, on the sparql path", async () => {
       const out = await lookupVia(SPQ, "Chip");
-      expect(uris(out)).toEqual([`${DS}alpha.chip`]);
+      expect(uris(out)).toEqual([`${DS}alpha.chip`, `${DS}zeta.chip`]);
     });
 
-    it("picks the lowest IRI on the graphql path", async () => {
+    it("answers with both, best first, on the graphql path", async () => {
       const out = await lookupVia(GQL, "Chip");
-      expect(uris(out)).toEqual([`${DS}alpha.chip`]);
+      expect(uris(out)).toEqual([`${DS}alpha.chip`, `${DS}zeta.chip`]);
     });
 
     it("agrees with itself across repeated resolves", async () => {
+      // Determinism was never the property in question — `LIMIT 1` over a total
+      // order was already deterministic. It is pinned because the order now
+      // carries the ranking's judgement, and an order that varied by store
+      // would make the first result mean nothing.
       const runs = await Promise.all([
         lookupVia(SPQ, "Chip"),
         lookupVia(SPQ, "chip"),
         lookupVia(GQL, "CHIP"),
       ]);
       expect(runs.map(uris)).toEqual([
-        [`${DS}alpha.chip`],
-        [`${DS}alpha.chip`],
-        [`${DS}alpha.chip`],
+        [`${DS}alpha.chip`, `${DS}zeta.chip`],
+        [`${DS}alpha.chip`, `${DS}zeta.chip`],
+        [`${DS}alpha.chip`, `${DS}zeta.chip`],
       ]);
     });
+
+    it("answers with ONE entity for an unambiguous name", async () => {
+      // The plural case costs the singular one nothing: a unique name still
+      // returns an array of one, which is the payload it always had.
+      const out = await lookupVia(GQL, "Modal");
+      expect(uris(out)).toEqual([`${DS}modal`]);
+    });
+
+    it("answers with ONE entity for an IRI, even a shared name's IRI", async () => {
+      // An IRI is one entity by construction, so the IRI form keeps its
+      // `LIMIT 1`: there is nothing to rank and nothing else to reach.
+      const out = await lookupVia(SPQ, "ds:zeta.chip");
+      expect(uris(out)).toEqual([`${DS}zeta.chip`]);
+    });
+
+    it("reaches both entities when a GLOB expands onto the shared name", async () => {
+      // The glob population is DISTINCT names, so "Chip" expands to ONE
+      // candidate — a glob was never the escape a shared name needs. Live,
+      // `block lookup 'Butt*'` listed Launchpad's Button and ButtonLink while
+      // the global Button appeared nowhere. Now the shared name reaches both
+      // through the glob for the same reason it does through a plain name.
+      const out = await lookupVia(SPQ, "Chi*");
+      expect(uris(out)).toEqual([`${DS}alpha.chip`, `${DS}zeta.chip`]);
+    });
+
+    it("adds no notice — the payload IS the address", async () => {
+      // An earlier draft kept the arity and named the outranked IRIs in a
+      // notice. With every entity returned there is nothing set aside to name,
+      // and a sentence restating what the payload already carries is noise.
+      // The zero-record notice is untouched; only the ambiguity one is gone.
+      expect(
+        lookupNoticeVia(SPQ, await lookupVia(SPQ, "Chip")),
+      ).toBeUndefined();
+      expect(
+        lookupNoticeVia(SPQ, await lookupVia(SPQ, "Modal")),
+      ).toBeUndefined();
+    });
   });
 });

package/src/kernel/packs/resolveEntity.ts

@@ -42,6 +42,7 @@ import type {
   PackChildRow,
   PackEntity,
   PackLookup,
+  PackRow,
   StorySource,
 } from "./types.js";
 
@@ -53,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[];
@@ -80,6 +89,9 @@ 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: {},
       }),
     });
   }
@@ -103,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;
@@ -186,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,
@@ -195,47 +235,71 @@ 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,
     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;
 }
 
 /**

package/src/kernel/packs/runBodies.ts

@@ -19,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;
@@ -45,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). */
@@ -88,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),
         });
       }
     }
@@ -119,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);