@canonical/pragma-cli 0.36.0 → 0.38.0

package/src/capabilities/block.parity.test.ts

@@ -6,13 +6,19 @@
  * `lookup` both compile from the declared story, so parity is asserted directly
  * against the graph. Two halves:
  *
- * - `block list` — the UNFILTERED list. Every block in the store, whatever the
- *   tier or channel, including the UNTIERED subcomponent the old hand-written
- *   query's required `ds:tier` join dropped (A2, formerly reachable only under
- *   `--all-tiers`). The row shape the hand-written verb built in TypeScript —
- *   the name fallback, the lowercased type, the tier's local name — is now
- *   derived IN SPARQL by `BIND`/`COALESCE`, and this file is what holds those
- *   BINDs to the shapes the old `blockList.verb.ts` produced.
+ * - `block list` — the TIER-SCOPED list. Every block the scope admits,
+ *   whatever its channel, including the UNTIERED subcomponent the old
+ *   hand-written query's required `ds:tier` join dropped (A2, formerly
+ *   reachable only under `--all-tiers`) — an entity the scope cannot place is
+ *   not one it may hide, so no scope drops it either. This fixture declares one
+ *   tier, `global`, so the scope admits everything in it and the row-shape
+ *   cases below read what they always read; what the scope decides is asserted
+ *   in `kernel/packs/tierScope.test.ts` and, over the shipped pack's fifteen
+ *   tiers, in `block.tierRank.exec.test.ts`. The row shape the hand-written
+ *   verb built in TypeScript — the name fallback, the lowercased type, the
+ *   tier's local name — is now derived IN SPARQL by `BIND`/`COALESCE`, and this
+ *   file is what holds those BINDs to the shapes the old `blockList.verb.ts`
+ *   produced.
  * - `block lookup` — unchanged GraphQL content parity, moved here from the
  *   deleted `capabilities/block/parity.test.ts`. Button and Modal resolve with
  *   the same content a direct SPARQL oracle returns (summary, guidance,
@@ -26,7 +32,7 @@
 
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import type { LookupOutput } from "../kernel/packs/resolveEntity.js";
-import type { PackRow } from "../kernel/packs/types.js";
+import type { PackPage } from "../kernel/packs/types.js";
 import { verbKey } from "../kernel/packs/uniqueness.js";
 import type { PragmaRuntime } from "../kernel/runtime/types.js";
 import type { VerbSpec } from "../kernel/spec/types.js";
@@ -66,13 +72,13 @@ async function lookup(name: string): Promise<Record<string, unknown>> {
   return out.results.at(0) as Record<string, unknown>;
 }
 
-describe("block list parity — the declared, unfiltered list", () => {
+describe("block list parity — the declared, tier-scoped list", () => {
   it("lists EVERY block, including the untiered subcomponent (A2)", async () => {
     // `ds:button.icon` is a `ds:Subcomponent` with NO `ds:tier`. The
     // hand-written query inner-joined `?c ds:tier ?t` in its default view and
     // surfaced it only under `--all-tiers`; the declared query's OPTIONAL join
     // means there is no view it can fall out of.
-    const rows = (await verb("list").run({}, rt)) as PackRow[];
+    const rows = ((await verb("list").run({}, rt)) as PackPage).rows;
     expect(rows.map((row) => row.name)).toEqual([
       "Button",
       "Button Icon",
@@ -81,7 +87,7 @@ describe("block list parity — the declared, unfiltered list", () => {
   });
 
   it("derives the summary row shape in SPARQL, matching the old hand-built row", async () => {
-    const rows = (await verb("list").run({}, rt)) as PackRow[];
+    const rows = ((await verb("list").run({}, rt)) as PackPage).rows;
     const byName = new Map(rows.map((row) => [row.name, row]));
     const button = byName.get("Button");
     // `type`: the LOWERCASED local name of the matched class — the BIND that
@@ -99,30 +105,73 @@ describe("block list parity — the declared, unfiltered list", () => {
   });
 
   it("an untiered block simply carries no tier — it is not dropped or blanked", async () => {
-    const rows = (await verb("list").run({}, rt)) as PackRow[];
+    const rows = ((await verb("list").run({}, rt)) as PackPage).rows;
     const icon = rows.find((row) => row.name === "Button Icon");
     expect(icon).toBeDefined();
     expect(icon?.tier).toBeUndefined();
     expect(icon?.uri).toBe(`${DS}button.icon`);
   });
 
-  it("is CONFIG-INDEPENDENT: a configured tier and channel change nothing", async () => {
-    // The signed-off consequence of L-OPEN-9, pinned at the verb: the run body
-    // never reads `loadConfig()`, so the same rows come back under any scope.
-    const scoped = {
+  it("READS the configured tier as its scope, and the channel not at all", async () => {
+    // The `tier` key used to scope nothing: this suite pinned the list as
+    // CONFIG-INDEPENDENT, which was the signed-off consequence of the
+    // hand-written filtering's removal. The tier scope reverses exactly that
+    // half and only that half — `tier` decides which tiers a read answers
+    // from, `channel` still decides nothing (it selects an npm dist-tag).
+    //
+    // This fixture declares ONE tier (`global`, the base), so the scope it
+    // resolves to is the same set by either route; what this holds is that the
+    // config is READ and REPORTED. Narrowing down a real chain is asserted
+    // where a chain exists — `tierScope.test.ts` over a nested fixture, and
+    // `block.tierRank.exec.test.ts` over the shipped pack's fifteen tiers.
+    const withConfig = (tier: string, channel: "normal" | "experimental") =>
+      ({
+        ...rt,
+        loadConfig: async () => ({
+          ...(await rt.loadConfig()),
+          config: { ...(await rt.loadConfig()).config, tier, channel },
+        }),
+      }) as PragmaRuntime;
+
+    const scoped = (await verb("list").run(
+      {},
+      withConfig("global", "experimental"),
+    )) as PackPage;
+    expect(scoped.scope).toEqual({ tiers: ["global"] });
+    expect(scoped.rows.map((row) => row.name)).toEqual([
+      "Button",
+      "Button Icon",
+      "Modal",
+    ]);
+
+    // `all` turns the scope off, and the page then reports none — the shape
+    // every unscoped story's page has always had.
+    const all = (await verb("list").run(
+      {},
+      withConfig("all", "normal"),
+    )) as PackPage;
+    expect(all.scope).toBeUndefined();
+    expect(all.rows).toEqual(
+      ((await verb("list").run({}, rt)) as PackPage).rows,
+    );
+  });
+
+  it("refuses a configured tier no tier answers to, naming the ones that do", async () => {
+    // A `tier` nothing in the pack carries used to be inert — accepted by the
+    // validator and read by nobody. Now it decides a scope, so a value that
+    // names no tier is a misconfiguration worth saying out loud rather than
+    // silently answering from a scope the reader did not ask for.
+    const stale = {
       ...rt,
       loadConfig: async () => ({
         ...(await rt.loadConfig()),
-        config: {
-          ...(await rt.loadConfig()).config,
-          tier: "apps/lxd",
-          channel: "experimental" as const,
-        },
+        config: { ...(await rt.loadConfig()).config, tier: "apps/lxd" },
       }),
     } as PragmaRuntime;
-    const scopedRows = (await verb("list").run({}, scoped)) as PackRow[];
-    const plainRows = (await verb("list").run({}, rt)) as PackRow[];
-    expect(scopedRows).toEqual(plainRows);
+    await expect(verb("list").run({}, stale)).rejects.toMatchObject({
+      code: "INVALID_INPUT",
+      validOptions: ["all", "global"],
+    });
   });
 
   it("zero rows is a calm empty list, not an error (the declared-family semantics)", async () => {
@@ -139,12 +188,12 @@ ds:Component a owl:Class .
       prefixes: BLOCK_PREFIXES,
     });
     try {
-      const rows = (await verb("list").run({}, emptyRt)) as PackRow[];
-      expect(rows).toEqual([]);
+      const page = (await verb("list").run({}, emptyRt)) as PackPage;
+      expect(page.rows).toEqual([]);
       // The same semantics, on the empty-state seam: the calm message + its
       // runnable hint now reach the user via stderr (`notice`), keeping
       // plain stdout pure data.
-      const notice = verb("list").output.formatters.notice?.(rows);
+      const notice = verb("list").output.formatters.notice?.(page);
       expect(notice).toContain("No blocks in the store.");
       expect(notice).toContain("pragma sources update");
     } finally {
@@ -208,11 +257,142 @@ describe("block lookup — Button content parity (GraphQL, detailed)", () => {
     expect(llm).toContain("#### When not to use");
     expect(llm).not.toContain("\n### When to use\n");
     expect(llm).toContain("### Anatomy (DSL)");
+    // The anatomy is a NOTATION, and its one unguessable rule is stated where
+    // the reader is looking: a bracketed value reads as a set of equals and is
+    // in fact an ordered fallback chain.
+    expect(llm).toContain(
+      "### Anatomy (DSL)\nA list value is the fallback chain the implementation reads, first wins.",
+    );
     expect(llm).toContain("### Modifier Families");
     expect(llm).toContain("primary");
   });
 });
 
+describe("block lookup — the tokens a block consumes (SPARQL-lane expand)", () => {
+  it("lists one row per binding, with all six identity columns", async () => {
+    const button = await lookup("Button");
+    // Six columns and not five: the anatomy's `styleKey` and `styleState`
+    // carry no rdfs:domain, so the GraphQL document this lookup otherwise
+    // builds derives no field for either and dropped both WITHOUT a word —
+    // leaving `appearance.background` rank 1 and rank 2 looking like one fact
+    // repeated. That is why this expand declares the SPARQL lane.
+    expect(button.tokens).toEqual([
+      {
+        symbol: "color.background",
+        key: "appearance.background",
+        state: "default",
+        rank: "1",
+        node: "$root",
+      },
+      {
+        symbol: "color.background.hover",
+        key: "appearance.background",
+        state: "hover",
+        rank: "2",
+        node: "$root",
+      },
+      {
+        symbol: "color.text",
+        key: "typography.color",
+        state: "default",
+        rank: "1",
+        node: "$root",
+      },
+      {
+        symbol: "color.icon",
+        key: "appearance.background",
+        state: "default",
+        rank: "1",
+        via: "Button Icon",
+        node: "$root/icon",
+      },
+    ]);
+  });
+
+  it("orders the rows by node, then key, then rank", async () => {
+    // The fixture declares them in another order on purpose: the store's own
+    // scan order is undefined, and a table of a node's styles is only readable
+    // one node at a time, one key at a time, each key's fallback chain in the
+    // order the implementation walks it.
+    const button = await lookup("Button");
+    const rows = button.tokens as {
+      node: string;
+      key: string;
+      rank: string;
+    }[];
+    expect(rows.map((row) => [row.node, row.key, row.rank])).toEqual([
+      ["$root", "appearance.background", "1"],
+      ["$root", "appearance.background", "2"],
+      ["$root", "typography.color", "1"],
+      ["$root/icon", "appearance.background", "1"],
+    ]);
+  });
+
+  it("blanks the via on the block's own tree and prints it otherwise", async () => {
+    // `ds:viaBlock` is asserted on EVERY record and equals the block on the
+    // block's own tree, so printing it raw put "Button" in every one of
+    // Button's own rows — a cell that is only ever news when it differs.
+    const button = await lookup("Button");
+    const rows = button.tokens as { via?: string; node: string }[];
+    for (const row of rows.filter((row) => row.node === "$root")) {
+      expect(row.via).toBeUndefined();
+    }
+    expect(rows.find((row) => row.node === "$root/icon")?.via).toBe(
+      "Button Icon",
+    );
+
+    // Modal consumes nothing of its own: its one row is Button's binding,
+    // reached through the Button its anatomy embeds, so the via is the whole
+    // point of the row.
+    const modal = await lookup("Modal");
+    expect(modal.tokens).toEqual([
+      {
+        symbol: "color.background",
+        key: "appearance.background",
+        state: "default",
+        rank: "1",
+        via: "Button",
+        node: "$root/footer",
+      },
+    ]);
+  });
+
+  it("renders the section under its own heading, with the reading note", async () => {
+    const llm = verb("lookup").output.formatters.llm(
+      (await verb("lookup").run({ name: ["Button"] }, rt)) as never,
+    );
+    // The same sentence `Anatomy (DSL)` carries, because the rank column is
+    // that notation's fallback chain seen from the other side.
+    expect(llm).toContain(
+      "### Tokens\nA list value in the anatomy is the fallback chain the implementation reads, first wins; rank is the position in that chain.",
+    );
+    expect(llm).toContain("symbol: color.text | key: typography.color");
+  });
+
+  it("prints no Tokens heading for a block that consumes nothing", async () => {
+    // What every other section on this lookup does when it is empty: no
+    // heading at all, rather than a heading with nothing under it. The key is
+    // still present in the payload as an empty array, so the machine shape
+    // stays uniform.
+    const icon = await lookup("Button Icon");
+    expect(icon.tokens).toEqual([]);
+    const llm = verb("lookup").output.formatters.llm(
+      (await verb("lookup").run({ name: ["Button Icon"] }, rt)) as never,
+    );
+    expect(llm).not.toContain("### Tokens");
+  });
+
+  it("is withheld at the summary level with the other detailed expands", async () => {
+    const out = (await verb("lookup").run(
+      { name: ["Button"] },
+      { ...rt, globalFlags: { ...rt.globalFlags, detail: "summary" } },
+    )) as LookupOutput;
+    expect(
+      (out.results.at(0) as Record<string, unknown>).tokens,
+    ).toBeUndefined();
+  });
+});
+
 describe("block lookup — Modal content parity (GraphQL, detailed)", () => {
   it("resolves the full Modal spec (a different block, same document engine)", async () => {
     const modal = await lookup("Modal");

package/src/capabilities/block.shipped.exec.test.ts

@@ -131,6 +131,44 @@ const DECLARED_PROPERTIES: readonly DeclaredTerm[] = [
   ]),
 ];
 
+/**
+ * Standard RDF vocabulary, which no domain ontology declares and every graph
+ * carries — the same exemption, for the same reason, that the token stories'
+ * shipped sweep makes: the distribution's own vocabulary declaration leaves
+ * `rdfs:label` out because "the kernel treats standard vocabulary as
+ * universal", and the shipped pack accordingly carries no T-box triple about
+ * it at all. Nothing upstream can retire a W3C term, which is the defect this
+ * file exists to catch.
+ *
+ * A readable list rather than a widened ASK, so the sweep stays a hard
+ * requirement on every DOMAIN term.
+ */
+const STANDARD_VOCABULARY = new Set(["rdfs:label", "rdfs:comment"]);
+
+/**
+ * The property STEPS one declaration names — more than one when it is a path.
+ *
+ * A SPARQL-lane declaration may read a grandchild through a path
+ * (`ds:consumesSymbol/rdfs:label`), and every domain step of it is a term the
+ * ontology has to define: a retired step anywhere along a path renders exactly
+ * as silently as a retired single term. Split rather than skipped — a path
+ * spliced whole into the ASK's subject position would not even parse, so the
+ * check would have raised instead of judging, and skipping paths outright
+ * would leave their steps unguarded.
+ *
+ * An absolute IRI is left whole: a `/` inside `https://…` is not a path
+ * separator, which is the grammar's own test for a property path.
+ */
+function pathSteps(property: string): readonly string[] {
+  if (!property.includes("/") || property.includes("://")) {
+    return STANDARD_VOCABULARY.has(property) ? [] : [property];
+  }
+  return property
+    .split("/")
+    .map((step) => step.replace(/^\^/, "").replace(/[*+?]$/, ""))
+    .filter((step) => step !== "" && !STANDARD_VOCABULARY.has(step));
+}
+
 /** The IRI of the block whose usage narrative is asserted on below. */
 const BUTTON = "https://ds.canonical.com/global.component.button";
 
@@ -167,25 +205,129 @@ describe("the `block` story declares vocabulary the shipped ontology defines (PR
     expect(DECLARED_PROPERTIES.length).toBeGreaterThan(0);
   });
 
-  it.each(
-    DECLARED_PROPERTIES,
-  )("$what reads $property, which the shipped ontology defines", async ({
-    what,
-    property,
-  }) => {
-    const result = await rt.query.sparql(
+  it.each(DECLARED_PROPERTIES)(
+    "$what reads $property, which the shipped ontology defines",
+    async ({ what, property }) => {
+      for (const hop of pathSteps(property)) {
+        const result = await rt.query.sparql(
+          [
+            "ASK {",
+            `  ${hop} a ?kind .`,
+            "  VALUES ?kind { owl:DatatypeProperty owl:ObjectProperty }",
+            "}",
+          ].join("\n"),
+        );
+        expect(result.type).toBe("ask");
+        expect(
+          result.type === "ask" ? result.result : false,
+          `${what} reads ${property}, whose hop ${hop} the shipped ontology does not define — it can never render, for any block, on any install`,
+        ).toBe(true);
+      }
+    },
+  );
+});
+
+describe("block lookup lists the tokens a block consumes (PROTECTED)", () => {
+  it("renders one row per binding record, with all six identity columns", async () => {
+    // The binding records are the design system's, derived from the anatomies,
+    // and they ride the embedded snapshot — so the ONE thing a fixture cannot
+    // prove is that the shipped corpus reaches this expand at all. Button is
+    // asserted on rather than any block: it is the block whose anatomy every
+    // other lookup test reads, and it carries bindings on its own tree AND on
+    // the tree of the icon it embeds.
+    const records = await scalar(
+      `SELECT (COUNT(*) AS ?n) WHERE { <${BUTTON}> ds:hasTokenBinding ?r }`,
+    );
+    expect(Number(records)).toBeGreaterThan(0);
+
+    const llm = await renderLookup(BUTTON);
+    expect(llm).toContain("### Tokens");
+    // The note, because a rank column without it is a number with no stated
+    // meaning.
+    expect(llm).toContain("rank is the position in that chain");
+
+    // One rendered row per record, and every row carrying the two columns the
+    // GraphQL lane cannot derive (neither `anatomy:styleKey` nor
+    // `anatomy:styleState` has an rdfs:domain, so no field exists for either
+    // on `TokenBinding`). Their absence is what made two of Button's rows
+    // byte-identical, so their presence is the assertion.
+    const rows = (llm.split("### Tokens")[1] ?? "")
+      .split("\n")
+      .filter((line) => line.startsWith("- symbol: "));
+    expect(rows).toHaveLength(Number(records));
+    for (const row of rows) {
+      expect(row).toContain(" | key: ");
+      expect(row).toContain(" | node: ");
+    }
+    // And no two rows the same — the defect a dropped identity column causes.
+    expect(new Set(rows).size).toBe(rows.length);
+  });
+
+  it("blanks the via on a block's own tree and prints an inherited one", async () => {
+    // `ds:viaBlock` is asserted on every record and its own definition says it
+    // equals the block in the own-tree case, so an unconditional column put
+    // the block's own name in every one of its rows.
+    const ownTree = await scalar(
+      [
+        "SELECT (COUNT(*) AS ?n) WHERE {",
+        `  <${BUTTON}> ds:hasTokenBinding ?r .`,
+        `  ?r ds:viaBlock <${BUTTON}> .`,
+        "}",
+      ].join("\n"),
+    );
+    expect(Number(ownTree)).toBeGreaterThan(0);
+
+    const llm = await renderLookup(BUTTON);
+    const rows = (llm.split("### Tokens")[1] ?? "")
+      .split("\n")
+      .filter((line) => line.startsWith("- symbol: "));
+    expect(rows.filter((row) => !row.includes(" | via: "))).toHaveLength(
+      Number(ownTree),
+    );
+
+    // A block whose bindings are ALL inherited, read from the graph rather
+    // than named here: every row of its section must carry a via.
+    const inheritor = await scalar(
       [
-        "ASK {",
-        `  ${property} a ?kind .`,
-        "  VALUES ?kind { owl:DatatypeProperty owl:ObjectProperty }",
+        "SELECT ?b WHERE {",
+        `  VALUES ?class { ${TYPE_VALUES} }`,
+        "  ?b a ?class ; ds:hasTokenBinding ?r .",
+        "  FILTER NOT EXISTS { ?b ds:hasTokenBinding/ds:viaBlock ?b }",
         "}",
+        "ORDER BY ?b",
+        "LIMIT 1",
       ].join("\n"),
     );
-    expect(result.type).toBe("ask");
     expect(
-      result.type === "ask" ? result.result : false,
-      `${what} reads ${property}, which the shipped ontology does not define — it can never render, for any block, on any install`,
-    ).toBe(true);
+      inheritor,
+      "no shipped block carries only inherited bindings",
+    ).toBeDefined();
+    const inheritedRows = (
+      (await renderLookup(inheritor as string)).split("### Tokens")[1] ?? ""
+    )
+      .split("\n")
+      .filter((line) => line.startsWith("- symbol: "));
+    expect(inheritedRows.length).toBeGreaterThan(0);
+    for (const row of inheritedRows) expect(row).toContain(" | via: ");
+  });
+
+  it("prints no Tokens heading for a block that consumes nothing", async () => {
+    // The shape every other section on this lookup has when it is empty. Read
+    // from the graph, because which blocks have no bindings is upstream's to
+    // change.
+    const uri = await scalar(
+      [
+        "SELECT ?b WHERE {",
+        `  VALUES ?class { ${TYPE_VALUES} }`,
+        "  ?b a ?class .",
+        "  FILTER NOT EXISTS { ?b ds:hasTokenBinding ?r }",
+        "}",
+        "ORDER BY ?b",
+        "LIMIT 1",
+      ].join("\n"),
+    );
+    expect(uri, "every shipped block carries bindings").toBeDefined();
+    expect(await renderLookup(uri as string)).not.toContain("### Tokens");
   });
 });
 

package/src/capabilities/block.tierRank.exec.test.ts

@@ -2,7 +2,7 @@
  * Which block a SHARED name means, EXECUTED against the shipped pack
  * (PROTECTED).
  *
- * 25 of the design system's block names are carried by two or three blocks
+ * 32 of the design system's block names are carried by two or three blocks
  * apiece, across tiers. `block lookup` used to answer each of them with whichever
  * IRI sorted first and say nothing about the rest, so `button` returned
  * Launchpad's Button — `apps_launchpad…` sorts before `global…` — and an agent
@@ -27,6 +27,8 @@
  */
 
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { MAX_LIST_WINDOW } from "../kernel/packs/paging.js";
+import type { PackPage } from "../kernel/packs/types.js";
 import { verbKey } from "../kernel/packs/uniqueness.js";
 import { bootRuntime } from "../kernel/runtime/boot.js";
 import type { PragmaRuntime } from "../kernel/runtime/types.js";
@@ -80,11 +82,23 @@ async function rows(query: string): Promise<Record<string, string>[]> {
     : [];
 }
 
-/** One `block lookup <name>`: the IRI it answered with, and the ones it did not. */
+/**
+ * One `block lookup <name>`: the IRI it answered with, and the ones it did not.
+ *
+ * ASKED FOR EVERY TIER, and that is load-bearing for this whole file. The claim
+ * under test is about RANKING — every block a shared name reaches comes back,
+ * best first — and the ranking orders a population the TIER SCOPE would
+ * otherwise cut: `block lookup button` answers with the global Button alone
+ * now, because the Launchpad one is out of the default scope. Both rules are
+ * about the same 25 collisions and they are not the same rule, so this suite
+ * widens the read to the population whose order it is judging. That the scope
+ * NARROWS it by default is asserted where that is the claim
+ * (`tierScope.test.ts`, and the shipped-pack cases below).
+ */
 async function lookup(
   name: string,
 ): Promise<{ chosen: string; others: string[] }> {
-  const out = (await lookupVerb.run({ name: [name] }, rt)) as {
+  const out = (await lookupVerb.run({ name: [name], tier: "all" }, rt)) as {
     results: { uri?: string }[];
   };
   // Every entity the name reached, best first. `chosen` is simply the head —
@@ -97,8 +111,12 @@ async function lookup(
  * Every block name the shipped graph gives to more than one block, with each
  * block's IRI, its tier's declared name and whether it is a subcomponent.
  *
- * Read with the SAME `LCASE` the resolve filters by, so a pair that collides
- * only for a lookup (`Button` vs `button`) is in this set too.
+ * Read with the SAME equality the resolve filters by — case-folded AND
+ * end-trimmed — so a pair that collides only for a lookup (`Button` vs
+ * `button`, `Timeline` vs the padded `Timeline ` 66 shipped names are spelled
+ * like) is in this set too. An oracle that folded less than the resolve would
+ * hand the sweep below a name reaching more blocks than the oracle listed, and
+ * read the resolve's correct answer as a failure.
  */
 async function collisions(): Promise<
   Map<string, { uri: string; tier: string; part: boolean }[]>
@@ -110,7 +128,7 @@ async function collisions(): Promise<
       "  ?uri a ?class .",
       `  ?uri ${blockLookup.by} ?name .`,
       `  OPTIONAL { ?uri ${scope.via} ?tier . ?tier ${scope.by} ?tn . }`,
-      "  BIND(LCASE(STR(?name)) AS ?key)",
+      '  BIND(LCASE(REPLACE(STR(?name), "^\\\\s+|\\\\s+$", "")) AS ?key)',
       '  BIND(COALESCE(?tn, "") AS ?tierName)',
       "  BIND(EXISTS { ?uri a ds:Subcomponent } AS ?part)",
       "}",
@@ -234,10 +252,29 @@ describe("a shared block name reaches every block that carries it (PROTECTED)",
 });
 
 describe("`block list` orders its ties totally (PROTECTED)", () => {
-  /** The entity IRIs of one `block list` run, in the order it printed them. */
+  /**
+   * The entity IRIs of one `block list` run, in the order it printed them —
+   * over EVERY tier, like the lookup cases above, and as ONE page over the whole
+   * population, because the order under test is the order of the whole
+   * population. A total order over the 313-block population is the property; the
+   * default scope's rows are a subsequence of it, so judging the order on the
+   * wider read judges both. A default-paged read used to be the whole population
+   * and quietly stopped being it: `DEFAULT_LIST_LIMIT` is 300, so the tail of
+   * the alphabet — `Timestamp`, `Tooltip`, and their launchpad twins — fell off
+   * the page and the cases below read a missing row as a lost row. The page is
+   * asserted COMPLETE rather than assumed so, so that the next time the
+   * population outgrows the window this says which it was.
+   */
   async function listOrder(): Promise<string[]> {
-    const data = (await listVerb.run({}, rt)) as { uri?: string }[];
-    return data.map((row) => String(row.uri));
+    const page = (await listVerb.run(
+      { tier: "all", limit: MAX_LIST_WINDOW },
+      rt,
+    )) as PackPage;
+    expect(
+      page.nextAfter,
+      `block list did not fit in one ${MAX_LIST_WINDOW}-row page`,
+    ).toBeUndefined();
+    return page.rows.map((row) => String(row.uri));
   }
 
   it("repeats the same order across runs", async () => {

package/src/capabilities/capabilities/catalog.ts

@@ -31,10 +31,19 @@ import type {
  * each other. `system` projects the distribution's identity rather than naming
  * a domain — the live tool catalog the same handshake carries already says
  * which nouns exist. `querying` is verbatim from the old shell (the SPARQL
- * model is still accurate for v2); `model` stopped claiming reads are
- * tier/channel-SCOPED when the hand-written filtering was removed (L-OPEN-9)
- * — the hierarchy is graph data now, not a query gate; `mutations` is new in
- * v2, surfacing the plan-first/confirm gate.
+ * model is still accurate for v2); `mutations` is new in v2, surfacing the
+ * plan-first/confirm gate.
+ *
+ * `model` is the one that has had to be rewritten twice, and both times because
+ * it was describing a gate that had moved. It stopped claiming reads were
+ * tier/channel-scoped when the hand-written filtering was removed (the
+ * hierarchy became graph data, not a query gate) — and "Reads are unscoped —
+ * every list shows everything" became false the day the tier scope landed. An
+ * agent reading it took a scoped `block_list` for the whole design system,
+ * which is the exact misreading the sentence existed to prevent. So it now says
+ * what is true of each half separately: the TIER hierarchy gates a read of a
+ * tiered noun and names the argument that widens it, while the CHANNEL is still
+ * data on the entity and gates nothing.
  */
 export const CONVENTIONS = {
   // `help` is authored as a bare phrase (`--help` renders it as one), so the
@@ -43,7 +52,7 @@ export const CONVENTIONS = {
   // otherwise reads "recipe graph.. A CLI and MCP server…".
   system: `${BIN_NAME} — ${PROGRAM_DESCRIPTION} (a CLI and MCP server over a knowledge graph).`,
   model:
-    "The graph models a tier hierarchy (e.g. global > apps > apps/lxd) and release channels (normal, experimental, prerelease) as DATA on each entity. Reads are unscoped — every list shows everything; filter by inspecting an entity's tier/release fields or with graph_query.",
+    'The tier hierarchy (global > apps > apps_lxd) SCOPES every read of a tiered entity: lists answer from the top-level tiers, lookups prefer them. Pass tier: "<name>" for a tier plus its ancestors, or tier: "all" for every tier; each answer states its scope. Channels scope nothing.',
   querying:
     "All queries run against an RDF triple store. Prefixed IRIs (e.g. prefix:name) identify entities. Use ontology_list to discover the active namespaces.",
   mutations: