@canonical/pragma-cli 0.36.0 → 0.38.0

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

@@ -0,0 +1,156 @@
+/**
+ * A truncated list says so — in EVERY format it is read in.
+ *
+ * The page notice reached `plain` (stderr) and `json` (`meta.notice`) but never
+ * `llm`, which is the form an agent reads and the form ANY piped invocation
+ * auto-detects. So `pragma token list --type color` ended at row 300 under a
+ * heading that said `(300)`, with nothing anywhere saying a page had been cut.
+ *
+ * The heading admits it too. The total is NOT named: a page is cut with one
+ * extra row rather than a second COUNT over the filtered population, so "more
+ * exist" is the strongest claim the read can honestly make.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
+import { executeVerb } from "../project/cli/dispatch.js";
+import type { GlobalFlags, PragmaRuntime } from "../runtime/types.js";
+import type { VerbSpec } from "../spec/types.js";
+import { compilePack } from "./compile.js";
+import type { PackDefinition } from "./types.js";
+import { distributionSource } from "./types.js";
+import { verbKey } from "./uniqueness.js";
+
+const PREFIXES = {
+  ex: "https://example.org/widgets#",
+  owl: "http://www.w3.org/2002/07/owl#",
+  rdfs: "http://www.w3.org/2000/01/rdf-schema#",
+  xsd: "http://www.w3.org/2001/XMLSchema#",
+};
+
+const TTL = `
+@prefix ex: <https://example.org/widgets#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+ex:Widget a owl:Class .
+ex:name a owl:DatatypeProperty ; rdfs:domain ex:Widget ; rdfs:range xsd:string .
+ex:kind a owl:DatatypeProperty ; rdfs:domain ex:Widget ; rdfs:range xsd:string .
+
+ex:button a ex:Widget ; ex:name "Button" ; ex:kind "input" .
+ex:label  a ex:Widget ; ex:name "Label"  ; ex:kind "display" .
+ex:slider a ex:Widget ; ex:name "Slider" ; ex:kind "input" .
+`;
+
+/** The recovery a story authors for an EMPTY POPULATION — never for a filter. */
+const EMPTY_RECOVERY = {
+  message: "No widgets in the store.",
+  cli: "sources update",
+} as const;
+
+const WIDGET_LIST = {
+  query: [
+    "SELECT ?uri ?name ?kind WHERE {",
+    "  ?uri a ex:Widget ; ex:name ?name .",
+    "  OPTIONAL { ?uri ex:kind ?kind }",
+    "} ORDER BY ?name",
+  ].join("\n"),
+  columns: [
+    { field: "uri", label: "IRI" },
+    { field: "name", label: "Name" },
+    { field: "kind", label: "Kind" },
+  ],
+  filters: [{ param: "kind", variable: "kind", values: ["input", "display"] }],
+  search: { variables: ["name"] },
+  emptyRecovery: EMPTY_RECOVERY,
+};
+
+/** Three rows — enough to cut a page in two. */
+const WIDGET_PACK: PackDefinition = {
+  noun: "widget",
+  description: "List widgets.",
+  list: WIDGET_LIST,
+};
+
+const listVerb = (pack: PackDefinition): VerbSpec =>
+  compilePack(pack, distributionSource("test:list"), PREFIXES).find(
+    (v) => verbKey(v.path) === `${pack.noun} list`,
+  ) as VerbSpec;
+
+const REAL = { dryRun: false, undo: false, yes: false };
+
+const PLAIN: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+const LLM: GlobalFlags = { ...PLAIN, llm: true, format: "llm" };
+const JSON_FLAGS: GlobalFlags = { ...PLAIN, format: "json" };
+
+let rt: PragmaRuntime;
+/** The same runtime, reading in another format. */
+const as = (flags: GlobalFlags): PragmaRuntime => ({
+  ...rt,
+  globalFlags: flags,
+});
+
+beforeAll(async () => {
+  ({ rt } = await buildFixtureRuntime({ ttl: TTL, prefixes: PREFIXES }));
+});
+afterAll(async () => {
+  (await rt.store.get()).store.dispose();
+});
+
+describe("a truncated page says so in every format", () => {
+  it("plain: the notice is the last thing the reader is told", async () => {
+    const outcome = await executeVerb(
+      listVerb(WIDGET_PACK),
+      { limit: 2 },
+      REAL,
+      as(PLAIN),
+    );
+    expect(outcome.exitCode).toBe(0);
+    expect(outcome.stdout).toContain("Button");
+    const notice = `${outcome.stdout ?? ""}${outcome.stderr ?? ""}`;
+    expect(notice).toContain("Showing 2 widget entries, and more exist.");
+    expect(notice).toContain("--after");
+  });
+
+  it("llm: the heading admits the page and the body ends with the notice", async () => {
+    const outcome = await executeVerb(
+      listVerb(WIDGET_PACK),
+      { limit: 2 },
+      REAL,
+      as(LLM),
+    );
+    const stdout = outcome.stdout ?? "";
+    expect(stdout).toContain("## Widget (2, more exist)");
+    expect(stdout.trimEnd().split("\n").at(-1)).toContain(
+      "Showing 2 widget entries, and more exist.",
+    );
+  });
+
+  it("json: the notice keeps riding meta", async () => {
+    const outcome = await executeVerb(
+      listVerb(WIDGET_PACK),
+      { limit: 2 },
+      REAL,
+      as(JSON_FLAGS),
+    );
+    const envelope = JSON.parse(outcome.stdout as string);
+    expect(envelope.meta.notice).toContain("and more exist");
+    expect(envelope.data).toHaveLength(2);
+  });
+
+  it("a whole answer says nothing extra, in any format", async () => {
+    const plain = await executeVerb(listVerb(WIDGET_PACK), {}, REAL, as(PLAIN));
+    expect(`${plain.stdout ?? ""}${plain.stderr ?? ""}`).not.toContain(
+      "more exist",
+    );
+    const llm = await executeVerb(listVerb(WIDGET_PACK), {}, REAL, as(LLM));
+    expect(llm.stdout).toContain("## Widget (3)");
+    expect(llm.stdout).not.toContain("more exist");
+  });
+});

package/src/kernel/packs/paging.ts

@@ -0,0 +1,110 @@
+/**
+ * The page a list-shaped verb answers with: how many rows, and where from.
+ *
+ * WHY A DEFAULT AT ALL. Before this, no list carried a cap: every declared
+ * story returned its whole population on every call, and an agent calling one
+ * speculatively paid for all of it. A default is what makes the cap real — a
+ * `--limit` nobody passes bounds nothing.
+ *
+ * WHY THIS DEFAULT. It answers to TWO constraints, and it is the largest number
+ * that satisfies both.
+ *
+ * From below: it stays above the row count of every story that already existed
+ * when the page arrived (the largest, `block list`, is 252), so no answer that
+ * was whole before the pair is truncated by it now.
+ *
+ * From above: the payload budget bounds ONE answer, and the suite that enforces
+ * it requires the largest default answer to sit under 0.8 of the ceiling —
+ * 100,000 bytes — so a ceiling nothing approaches keeps catching things and one
+ * sitting on the measurement does not flake. The fattest row any declared story
+ * serialises is `token values` at 244 bytes, so 300 rows of it is about 73 KB
+ * and the gate holds with room to spare.
+ *
+ * The first constraint alone gave 500, which is what this was, and the second
+ * retired it: the token-graph stories brought populations of 745, 1,156, 1,237
+ * and 1,746 rows, and at 500 rows `token values` measured 121,776 bytes —
+ * inside the ceiling and past the gate, with no headroom left. So the number is
+ * now derived from the budget rather than from a population that no longer
+ * bounds anything.
+ *
+ * It is still a KERNEL default and not a per-story one — a story has no
+ * page-size knob, so there is exactly one number to know, and it is written
+ * here, in the help text of every list verb, and in `BUDGETS.md` beside the
+ * payload it bounds. A per-story knob is what to reach for when one story's
+ * rows are so much fatter than the rest that one number cannot serve both;
+ * that is not true of any story today.
+ *
+ * WHY A CEILING AS WELL. The page's two integers are emitted into the query
+ * ({@link ./sparql/buildListQuery}), and the store's own `LIMIT`/`OFFSET` must
+ * fit a 32-bit integer while `Number.isInteger` admits anything up to 2^53. So
+ * `--limit 9007199254740991` — the natural "give me everything" an agent
+ * writes — used to reach the engine and come back as a raw parse error wrapped
+ * in INTERNAL_ERROR and "report this issue", from a flag whose own help invited
+ * a larger number. {@link MAX_LIST_WINDOW} is where both halves of the window
+ * are refused instead, with the typed INVALID_INPUT the rest of the pair uses
+ * and the ceiling named in the message.
+ *
+ * The cursor that carries a caller from one page to the next is
+ * {@link ./cursor}, kept apart because it hashes and this module is reached
+ * from the compiler on the storeless `--help` path. It bounds its own offset by
+ * the same ceiling, from here.
+ */
+
+import { PragmaError } from "../error/index.js";
+
+/**
+ * Rows a list-shaped verb returns when the caller names no `--limit`.
+ *
+ * Derived from the payload budget and from the populations that predate the
+ * page — see the module note for both halves of the arithmetic.
+ */
+export const DEFAULT_LIST_LIMIT = 300;
+
+/**
+ * The largest `--limit`, and the largest cursor offset, the kernel admits.
+ *
+ * NOT the engine's limit, which is an implementation detail of the pinned store
+ * and would make the refusal a fact about oxigraph. It comes from the payload
+ * budget instead, which is a fact about the answer: `BUDGETS.md`'s
+ * `LIST_PAYLOAD_BUDGET_BYTES` is 125,000, and the narrowest row a story can
+ * possibly serialise is `{}` plus its separating comma — three bytes — so no
+ * answer of more than 41,666 rows can be inside the budget whatever a story's
+ * columns are. A limit that cannot produce a legal answer is not a legal limit;
+ * rounded down to a number a message can carry, that is 40,000. It stays 22×
+ * the largest population the distribution ships (1,746) and 133× the default
+ * page, so it refuses nothing a caller could want today.
+ *
+ * The cursor's OFFSET takes the same ceiling, for a reason of its own: an offset
+ * is a count of rows already answered, and a walk that has passed 40,000 of
+ * them is walking a population more than two orders of magnitude larger than
+ * any single legal answer — the point at which the cursor to spend is a keyset
+ * cursor, which is what the encoding's `v` field exists to allow. Until such a
+ * story exists, an offset that large is a hand-built or tampered token, and one
+ * typed refusal is the honest answer to both.
+ *
+ * `listBudget.shipped.exec.test.ts` asserts the arithmetic tying this to the
+ * budget, so the two cannot drift apart in silence.
+ */
+export const MAX_LIST_WINDOW = 40_000;
+
+/**
+ * Read the `--limit`/`limit` argument.
+ *
+ * @param provided - The raw argument, if any.
+ * @returns The requested limit, or {@link DEFAULT_LIST_LIMIT}.
+ * @throws PragmaError INVALID_INPUT for anything that is not a whole number
+ *   between 1 and {@link MAX_LIST_WINDOW}. The ceiling is named in the message:
+ *   a refusal that does not say what it would accept is a guessing game.
+ */
+export function readLimit(provided: unknown): number {
+  if (provided === undefined) return DEFAULT_LIST_LIMIT;
+  const value = typeof provided === "number" ? provided : Number(provided);
+  if (!Number.isInteger(value) || value < 1 || value > MAX_LIST_WINDOW) {
+    throw PragmaError.invalidInput("limit", String(provided), {
+      recovery: {
+        message: `--limit takes a whole number of rows, 1 to ${MAX_LIST_WINDOW} (default ${DEFAULT_LIST_LIMIT}).`,
+      },
+    });
+  }
+  return value;
+}

package/src/kernel/packs/renderPack.ts

@@ -26,13 +26,17 @@ import {
   renderLookupPlain,
 } from "../render/renderers.js";
 import type { Formatters } from "../spec/index.js";
+import { kebabCase } from "../spec/index.js";
 import type { LookupOutput } from "./resolveEntity.js";
-import type {
-  PackChildRow,
-  PackEntity,
-  PackList,
-  PackLookup,
-  PackRow,
+import {
+  EVERY_TIER,
+  type PackAppliedFilter,
+  type PackChildRow,
+  type PackEntity,
+  type PackList,
+  type PackLookup,
+  type PackPage,
+  type PackRow,
 } from "./types.js";
 
 /** Sample output: the drawn exemplars, the population size, and agent follow-ups. */
@@ -57,11 +61,31 @@ export interface RenderMeta {
  */
 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). */
+/**
+ * Build the list formatters for a list-shaped verb (list or an extra verb).
+ *
+ * Every mode renders the page's ROWS, so the three output contracts are exactly
+ * what they were before a list carried a page: `plain` a table, `llm` its
+ * frozen condensed form, `json` the bare array. What the page adds rides the
+ * `notice` seam — the channel that already exists for what the data cannot say
+ * about itself, and which both machine surfaces project into `meta.notice`.
+ *
+ * EVERY format says it, though, because a truncation nobody is told about is a
+ * wrong answer in any dialect. The seam alone did not reach `llm`: the
+ * dispatcher routes a notice to stderr in `plain` and into `meta.notice` in
+ * `json`, but the `llm` branch renders the body and nothing else — and `llm`
+ * is what an agent (or any piped invocation, which auto-detects it) actually
+ * reads. So the condensed form carries the sentence in its own body, as a final
+ * line, and its heading admits the page is a page.
+ *
+ * A page that is the whole answer says nothing, which is why declaring the
+ * default page size above every story's population left every existing answer
+ * untouched, notice included.
+ */
 export function listFormatters(
   shape: PackList,
   meta: RenderMeta,
-): Formatters<PackRow[]> {
+): Formatters<PackPage> {
   const columns: ColumnDef<PackRow>[] = shape.columns.map((column) => ({
     key: column.field,
     label: column.label ?? column.field,
@@ -84,16 +108,138 @@ export function listFormatters(
     emptyHint,
   };
   return {
-    plain: (rows, context) => renderListPlain(rows, options, context),
-    llm: (rows) => renderListLlm(rows, options),
-    json: (rows) => JSON.stringify(rows, null, 2),
+    plain: (page, context) => renderListPlain(page.rows, options, context),
+    llm: (page) => {
+      const body = renderListLlm(page.rows, emptyCopy(page, meta, options), {
+        more: page.nextAfter !== undefined,
+        ...(scopeText(page) === undefined
+          ? {}
+          : { scope: scopeText(page) as string }),
+      });
+      const notice = listNotice(page, meta);
+      return notice ? `${body}\n\n${notice}` : body;
+    },
+    json: (page) => JSON.stringify(page.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.
-    notice: (rows) =>
-      rows.length === 0 ? renderListEmptyNotice(options) : undefined,
+    notice: (page) =>
+      page.rows.length === 0
+        ? joinNotices([
+            renderListEmptyNotice(emptyCopy(page, meta, options)),
+            scopeNotice(page),
+          ])
+        : listNotice(page, meta),
+    // The scope rides the envelope as DATA as well as prose: an agent deciding
+    // whether to widen the read should not have to parse a sentence to learn
+    // which tiers it got.
+    meta: (page) => (page.scope ? { scope: page.scope } : undefined),
   };
 }
 
+/** The tier scope in the words `--tier` accepts, or nothing when unscoped. */
+function scopeText(page: PackPage): string | undefined {
+  return page.scope ? page.scope.tiers.join(", ") : undefined;
+}
+
+/**
+ * What a SCOPED page says for itself: which tiers it answered from, and the
+ * argument that widens it.
+ *
+ * The plain table has no heading to carry it (a plain list is columns a pipe
+ * reads as records), so the sentence is the plain surface's whole account of
+ * the scope — and the notice seam is where this package already puts what the
+ * data cannot say about itself.
+ */
+function scopeNotice(page: PackPage): string | undefined {
+  const scope = scopeText(page);
+  if (scope === undefined) return undefined;
+  return (
+    `Tier scope: ${scope}. ` +
+    `Pass \`--tier <name>\` for one tier and its ancestors, or \`--tier ${EVERY_TIER}\` for every tier.`
+  );
+}
+
+/** The page's notices, in the order a reader needs them: scope, then paging. */
+function listNotice(page: PackPage, meta: RenderMeta): string | undefined {
+  return joinNotices([scopeNotice(page), pageNotice(page, meta)]);
+}
+
+/** Join what a page has to say into one notice, dropping what it has not. */
+function joinNotices(
+  notices: readonly (string | undefined)[],
+): string | undefined {
+  const present = notices.filter((notice): notice is string => Boolean(notice));
+  return present.length === 0 ? undefined : present.join(" ");
+}
+
+/**
+ * The empty-state copy this page deserves.
+ *
+ * Two facts can empty a list and zero rows cannot tell them apart: nothing was
+ * there, or a filter missed what was. Both are worth saying and they are not
+ * exclusive, so a filtered empty page says both — the kernel's own sentence
+ * names the arguments the caller typed, and the story's `emptyRecovery` follows
+ * it on the next line, exactly as it does on an unfiltered page.
+ *
+ * It did not, briefly: a filtered empty page reported only the narrowing,
+ * because the recoveries of the day asserted an empty store ("No token symbols
+ * in the store … run `pragma sources update`") and so told a reader with 745
+ * symbols in it to rebuild for nothing. That is a WORDING defect, and it is
+ * fixed where it lives — a story's recovery is now written to hold whether the
+ * population is empty or a filter missed a populated one, or the story declares
+ * none. Suppressing it here cost more than it saved: `token consumers --symbol
+ * color.text` narrows a table that records no bindings at all, and "No token
+ * matches `--symbol color.text`." on its own read as a mistyped symbol while
+ * withholding the one account of the emptiness that verb has.
+ *
+ * @param page - The rendered page (its rows and the filters that cut them).
+ * @param meta - The noun, for the sentence.
+ * @param base - The story's own empty copy.
+ * @returns `base` unchanged, or `base` with the filter-shaped message — the
+ *   story's own hint is kept either way.
+ */
+function emptyCopy(
+  page: PackPage,
+  meta: RenderMeta,
+  base: RenderListOptions<PackRow>,
+): RenderListOptions<PackRow> {
+  const applied = page.filters ?? [];
+  if (page.rows.length > 0 || applied.length === 0) return base;
+  return {
+    ...base,
+    emptyMessage: `No ${meta.noun} matches ${listFilters(applied)}.`,
+  };
+}
+
+/** The filters in force, as flags a reader can edit: `\`--kind input\`` … */
+function listFilters(applied: readonly PackAppliedFilter[]): string {
+  const flags = applied.map(
+    (filter) => `\`--${kebabCase(filter.param)} ${filter.value}\``,
+  );
+  const last = flags.at(-1) as string;
+  return flags.length === 1
+    ? last
+    : `${flags.slice(0, -1).join(", ")} and ${last}`;
+}
+
+/**
+ * What a truncated page says for itself: that it is one, and the exact argument
+ * that fetches the next.
+ *
+ * The cursor is printed rather than described. An opaque token a caller has to
+ * be told how to obtain is a token they will guess at, and the two surfaces
+ * that carry this are read by agents — so the sentence contains the flag, the
+ * value, and the tool parameter, ready to copy.
+ */
+function pageNotice(page: PackPage, meta: RenderMeta): string | undefined {
+  if (page.nextAfter === undefined) return undefined;
+  return (
+    `Showing ${page.rows.length} ${meta.noun} entries, and more exist. ` +
+    `For the next page pass \`--after ${page.nextAfter}\` ` +
+    `(\`after\` over MCP), or raise \`--limit\` (currently ${page.limit}).`
+  );
+}
+
 /** Build the shared per-entity render options for a lookup (reused by sample). */
 export function lookupOptions(
   lookup: PackLookup,
@@ -110,6 +256,7 @@ export function lookupOptions(
       key: section.name,
       heading: section.label ?? section.name,
       kind: section.kind ?? "field",
+      ...(section.note ? { note: section.note } : {}),
     }),
   );
   const expandSections: SectionDef<PackEntity>[] = (lookup.expand ?? []).map(
@@ -118,6 +265,7 @@ export function lookupOptions(
       heading: expand.heading ?? expand.name,
       kind: expand.kind ?? "list",
       ...(expand.showWhenEmpty ? { showWhenEmpty: true } : {}),
+      ...(expand.note ? { note: expand.note } : {}),
     }),
   );
   return {
@@ -177,6 +325,29 @@ export function sampleFormatters(
   };
 }
 
+/**
+ * What a lookup answered from OUTSIDE the tier scope says for itself.
+ *
+ * One line per name, and it is in the BODY rather than on the notice seam: the
+ * answer it explains is on stdout, and a reader piping `block lookup back-link`
+ * would otherwise see a block from a tier they are not reading with no way to
+ * tell from the output why. The machine surfaces carry the same fact
+ * structurally (`outOfScope` rides the payload), so this is one fact in two
+ * registers, not two facts.
+ */
+function scopeFallbackLines(
+  output: LookupOutput,
+  mode: "plain" | "llm",
+): string[] {
+  const bullet = mode === "llm" ? "- " : "";
+  return (output.outOfScope ?? []).map(
+    (answer) =>
+      `${bullet}No "${answer.query}" in the tier scope (${answer.scope}) — ` +
+      `answering from ${answer.tiers.join(", ")}. ` +
+      `Pass \`--tier ${EVERY_TIER}\` for every tier.`,
+  );
+}
+
 /** Render each result entity, appending a compact note for any error entries. */
 function renderOutput(
   output: LookupOutput,
@@ -184,6 +355,8 @@ function renderOutput(
   mode: "plain" | "llm" = "plain",
 ): string {
   const bodies = output.results.map(render);
+  const fallback = scopeFallbackLines(output, mode);
+  if (fallback.length > 0) bodies.push(fallback.join("\n"));
   if (output.errors.length > 0) {
     const bullet = mode === "llm" ? "- " : "  ";
     const lines = output.errors.map(

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

@@ -7,9 +7,10 @@
  * 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 answers with the
- * same entity on every store and every machine — while NAMING the ones it did
- * not answer with.
+ * when it carries no `by` value, that a name reaches its entity through the
+ * whitespace either side may be padded with, 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
@@ -149,6 +150,64 @@ describe("pack lookup addressing (PROTECTED)", () => {
     });
   });
 
+  describe("a name resolves through the whitespace the graph carries", () => {
+    // `ds:padded.timeline` is named "Timeline " in the fixture, exactly as 66
+    // shipped names are — the transform that reads the source document keeps the
+    // cell's trailing space. That padding is not part of the name: no surface
+    // prints it and no user can type it on purpose, so a resolve it can defeat
+    // is broken for every one of those entities.
+    it("resolves a padded name by the name a user can type", async () => {
+      const out = await lookupVia(SPQ, "Timeline");
+      expect(out.errors).toEqual([]);
+      expect(uris(out)).toEqual([`${DS}padded.timeline`]);
+    });
+
+    it("resolves it on the graphql path too, where the resolve is the same SPARQL", async () => {
+      const out = await lookupVia(GQL, "Timeline");
+      expect(out.errors).toEqual([]);
+      expect(uris(out)).toEqual([`${DS}padded.timeline`]);
+    });
+
+    it("trims the ARGUMENT as well, so a pasted name reaches a clean entity", async () => {
+      // The other direction, and the reason both sides are trimmed rather than
+      // just `?name`: a name copied out of a table cell arrives padded, and
+      // Modal's own name is not.
+      const out = await lookupVia(SPQ, "  Modal\t");
+      expect(out.errors).toEqual([]);
+      expect(uris(out)).toEqual([`${DS}modal`]);
+    });
+
+    it("still folds case while it folds the padding", async () => {
+      expect(uris(await lookupVia(SPQ, "timeline"))).toEqual([
+        `${DS}padded.timeline`,
+      ]);
+    });
+
+    it("keeps the entity's own name LITERAL in the answer", async () => {
+      // The trim is a matching rule, not a rendering one. What the graph holds
+      // is what a reader is shown, so the upstream correction to the transform
+      // is visible when it lands instead of being papered over here.
+      const out = await lookupVia(SPQ, "Timeline");
+      expect(out.results.at(0)?.name).toBe("Timeline ");
+    });
+
+    it("suggests it by its literal name on a genuine typo", async () => {
+      // A real miss still names the padded candidate exactly as the graph holds
+      // it — the trim decides what MATCHES and changes nothing about what a
+      // reader is shown. What can no longer happen is the reported
+      // `Did you mean? - Timeline` whose only difference from the query was the
+      // padding: that case resolves now, and the suggester's own refusal to
+      // restate a query is asserted in `project/cli/suggest.test.ts`.
+      const reason = await lookupVia(SPQ, "Timelime").catch(
+        (error: unknown) => error,
+      );
+      expect(reason).toMatchObject({ code: "ENTITY_NOT_FOUND" });
+      expect((reason as { suggestions: string[] }).suggestions).toContain(
+        "Timeline ",
+      );
+    });
+  });
+
   describe("a glob expands over the population its own shape addresses", () => {
     it("expands an IRI-shaped glob on a sparql-sourced pack", async () => {
       const out = await lookupVia(SPQ, "ds:*.chip");