@canonical/pragma-cli 0.36.0 → 0.38.0

package/src/testing/behavioral/journeys.firstInstall.test.ts

@@ -16,7 +16,7 @@
 import { mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { storyModules } from "../../capabilities/distribution.js";
 import { checkPackageRefs } from "../../capabilities/doctor/checks/checkPackageRefs.js";
 import { promptListVerb } from "../../capabilities/prompt/verbs.js";
@@ -27,6 +27,14 @@ import { bootRuntime } from "../../kernel/runtime/boot.js";
 import type { GlobalFlags } from "../../kernel/runtime/types.js";
 import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
 
+// Every case here boots its own runtime — a fresh install is what is under test —
+// and the first read in the process parses the embedded pack cold: 65,000 triples,
+// three seconds on an idle machine and more when every package's suite runs at
+// once, which is how the release workflow runs them. The budget is a fact about
+// the pack's size, not about any assertion, and it belongs to the file because
+// whichever case runs first is the one that pays it.
+vi.setConfig({ testTimeout: 60_000 });
+
 const JSON_FLAGS: GlobalFlags = {
   llm: false,
   autoLlm: false,
@@ -113,10 +121,67 @@ describe("first install — an empty cwd answers real reads offline", () => {
 });
 
 describe("first install — empty results are honest, not papered over", () => {
-  it("token list exits calmly with no rows (the graph carries no ds:Token)", async () => {
-    expect(
-      await readData(verbOf(tokenModule, "token list"), emptyCwd()),
-    ).toEqual([]);
+  // `token list` used to be this describe's first case, asserting no rows
+  // "because the graph carries no ds:Token". That is no longer true and the
+  // change is the point: the noun addressed a class no shipped graph asserted,
+  // it now addresses the token symbols, and the embedded pack carries them with
+  // the name literal the story keys on — so a first install ANSWERS. The case
+  // moved rather than being deleted, and it moved in both directions.
+  // ONE case and ONE store boot for the whole token noun, deliberately. Each
+  // `readData` here boots its own runtime — which is the point of this file,
+  // since a fresh install is what is under test — and the embedded pack is the
+  // expensive part of that. Three separate cases meant three boots of a
+  // 53,467-triple store for three claims about the same install, which is a
+  // cost this file pays under every parallel run for no extra coverage.
+  it("the token noun answers a first install: rows, a named symbol, and honest emptiness", async () => {
+    const cwd = emptyCwd();
+    const runtime = bootRuntime(JSON_FLAGS, cwd);
+
+    const read = async (
+      verb: VerbSpec,
+      params: Record<string, unknown> = {},
+    ): Promise<unknown> => {
+      const outcome = await executeVerb(verb, params, NO_MUTATION, runtime);
+      return (JSON.parse(outcome.stdout as string) as { data: unknown }).data;
+    };
+
+    // The symbols resolve offline, from the embedded pack, with no build.
+    const rows = (await read(verbOf(tokenModule, "token list"))) as {
+      name: string;
+    }[];
+    expect(rows.length).toBeGreaterThan(0);
+    for (const row of rows) expect(row.name).toBeTruthy();
+
+    // Membership, never a count — but asserted through a FILTER rather than
+    // through the unfiltered page, because this is the first population large
+    // enough for the page to matter: 436 symbols sort before `color.text`, so
+    // it is not on the first page and an unfiltered `toContain` would be
+    // testing the alphabet. A filter compiles INTO the query, so it answers
+    // from the whole population however the rows happen to page.
+    const matched = (await read(verbOf(tokenModule, "token list"), {
+      search: "color.text",
+    })) as { name: string }[];
+    expect(matched.map((row) => row.name)).toContain("color.text");
+
+    // The bindings between blocks and symbols now ride the pack too — they
+    // are derived from the component anatomies the embedded snapshot carries —
+    // so this verb ANSWERS on a first install where it used to be the honest
+    // emptiness this describe was written around. The claim moved rather than
+    // being deleted: what a first install owes the reader is a usable answer,
+    // and the columns that make a row usable are asserted here.
+    const consumers = (await read(verbOf(tokenModule, "token consumers"))) as {
+      block: string;
+      via?: string;
+      symbol: string;
+    }[];
+    expect(consumers.length).toBeGreaterThan(0);
+    for (const row of consumers) {
+      // The CONSUMING block, which is the fact the verb exists for, and the
+      // via only where the binding came from another block's tree.
+      expect(row.block).toBeTruthy();
+      expect(row.symbol).toBeTruthy();
+      if (row.via) expect(row.via).not.toBe(row.block);
+    }
   });
 
   it("prompt list exits calmly with no prompts (the graph carries no ds:Prompt)", async () => {

package/src/testing/behavioral/journeys.mcpLifecycle.mcp.test.ts

@@ -104,9 +104,10 @@ describe("MCP lifecycle — cold store recovers after sources_update (E2, C1)",
     const names = (warm.data as { name: string }[])
       .map((row) => row.name)
       .sort();
-    // The whole pack — `block_list` is the declared, unfiltered list since
-    // L-OPEN-9, so no channel hides Beta Badge and no tier join hides the
-    // untiered Orphan Widget.
+    // The whole pack: no channel hides Beta Badge, no tier join hides the
+    // untiered Orphan Widget, and the tier scope admits the rest because every
+    // tier this fixture declares is top-level. Add a nested one upstream and
+    // this set becomes the default scope's, not the pack's.
     expect(names).toEqual(["Beta Badge", "Button", "Card", "Orphan Widget"]);
   });
 });

package/src/testing/behavioral/journeys.packageStories.test.ts

@@ -22,6 +22,7 @@ import { runChecks } from "../../capabilities/doctor/runChecks.js";
 import { capabilities } from "../../capabilities/index.js";
 import { buildUpdateTask } from "../../capabilities/sources/runUpdate.js";
 import { loadEffectiveModules } from "../../kernel/packs/collect.js";
+import type { PackPage } from "../../kernel/packs/types.js";
 import { packDir, readActivePack } from "../../kernel/runtime/paths.js";
 import type { VerbSpec } from "../../kernel/spec/types.js";
 import {
@@ -103,7 +104,7 @@ describe("a package-declared noun answers reads (in-process)", () => {
     const list = recipe?.verbs.find(
       (verb) => verb.path.join(" ") === "recipe list",
     ) as VerbSpec;
-    const rows = (await list.run({}, graph.runtime)) as { name: string }[];
+    const { rows } = (await list.run({}, graph.runtime)) as PackPage;
     expect(rows.map((row) => row.name)).toEqual(["Soup", "Stew"]);
   });
 

package/src/testing/behavioral/mcpSurface.test.ts

@@ -114,31 +114,34 @@ describe("every MCP tool is callable and returns a well-formed envelope (B4)", (
     expect(everyExposedVerb.length).toBeGreaterThan(0);
   });
 
-  it.each(
-    everyExposedVerb,
-  )("$tool: callable, well-formed envelope, annotations match capability.mutates", async (v) => {
-    const tool = v.tool as string;
-    const args = representativeArgs(v);
-    const result = await mcp.callTool(tool, args);
+  it.each(everyExposedVerb)(
+    "$tool: callable, well-formed envelope, annotations match capability.mutates",
+    async (v) => {
+      const tool = v.tool as string;
+      const args = representativeArgs(v);
+      const result = await mcp.callTool(tool, args);
 
-    expect(typeof result.ok).toBe("boolean");
-    if (result.ok) {
-      expect("data" in result).toBe(true);
-      expect(typeof result.meta).toBe("object");
-    } else {
-      const error = result.error as { code?: unknown; message?: unknown };
-      expect(typeof error.code).toBe("string");
-      expect(typeof error.message).toBe("string");
-    }
+      expect(typeof result.ok).toBe("boolean");
+      if (result.ok) {
+        expect("data" in result).toBe(true);
+        expect(typeof result.meta).toBe("object");
+      } else {
+        const error = result.error as { code?: unknown; message?: unknown };
+        expect(typeof error.code).toBe("string");
+        expect(typeof error.message).toBe("string");
+      }
 
-    const registered = registeredTools.find((t) => t.name === tool);
-    expect(registered).toBeDefined();
-    const annotations = registered?.annotations as
-      | { readOnlyHint?: boolean; destructiveHint?: boolean }
-      | undefined;
-    expect(annotations?.readOnlyHint).toBe(!v.mutates);
-    if (v.spec.capability.destructive !== undefined) {
-      expect(annotations?.destructiveHint).toBe(v.spec.capability.destructive);
-    }
-  });
+      const registered = registeredTools.find((t) => t.name === tool);
+      expect(registered).toBeDefined();
+      const annotations = registered?.annotations as
+        | { readOnlyHint?: boolean; destructiveHint?: boolean }
+        | undefined;
+      expect(annotations?.readOnlyHint).toBe(!v.mutates);
+      if (v.spec.capability.destructive !== undefined) {
+        expect(annotations?.destructiveHint).toBe(
+          v.spec.capability.destructive,
+        );
+      }
+    },
+  );
 });

package/src/testing/behavioral/parity.test.ts

@@ -197,28 +197,30 @@ describe("read-noun parity — every list/lookup/extra verb (B5)", () => {
     });
   });
 
-  it.each(
-    lookupVerbs,
-  )("$noun lookup: CLI --format json == MCP, for a known name", async (v) => {
-    const name = firstNameByNoun.get(v.noun);
-    if (!name) return;
-    await assertCliMcpParity({
-      modules: capabilities,
-      verb: v.spec,
-      tool: v.tool as string,
-      cwd: fixture.cwd,
-      params: { name: [name] },
-    });
-  });
+  it.each(lookupVerbs)(
+    "$noun lookup: CLI --format json == MCP, for a known name",
+    async (v) => {
+      const name = firstNameByNoun.get(v.noun);
+      if (!name) return;
+      await assertCliMcpParity({
+        modules: capabilities,
+        verb: v.spec,
+        tool: v.tool as string,
+        cwd: fixture.cwd,
+        params: { name: [name] },
+      });
+    },
+  );
 
-  it.each(
-    extraListShapedVerbs,
-  )("$noun $verb: CLI --format json == MCP", async (v) => {
-    await assertCliMcpParity({
-      modules: capabilities,
-      verb: v.spec,
-      tool: v.tool as string,
-      cwd: fixture.cwd,
-    });
-  });
+  it.each(extraListShapedVerbs)(
+    "$noun $verb: CLI --format json == MCP",
+    async (v) => {
+      await assertCliMcpParity({
+        modules: capabilities,
+        verb: v.spec,
+        tool: v.tool as string,
+        cwd: fixture.cwd,
+      });
+    },
+  );
 });

package/src/testing/eval/__snapshots__/eval.test.ts.snap

@@ -202,11 +202,21 @@ exports[`eval harness — seed gate > runs the full seed (stable + read-noun) ca
     "kind": "tool",
     "passed": true,
   },
+  {
+    "id": "tool-token-consumers-answers-or-recovers",
+    "kind": "tool",
+    "passed": true,
+  },
   {
     "id": "tool-token-lookup-addresses-only-what-list-publishes",
     "kind": "tool",
     "passed": true,
   },
+  {
+    "id": "tool-token-lookup-dotted-name-resolves-with-its-definitions",
+    "kind": "tool",
+    "passed": true,
+  },
   {
     "id": "tool-token-noun-is-read-only",
     "kind": "tool",
@@ -217,10 +227,20 @@ exports[`eval harness — seed gate > runs the full seed (stable + read-noun) ca
     "kind": "tool",
     "passed": true,
   },
+  {
+    "id": "tool-token-values-narrows-to-one-symbol",
+    "kind": "tool",
+    "passed": true,
+  },
   {
     "id": "tool-upgrade-is-plan-first",
     "kind": "tool",
     "passed": true,
   },
+  {
+    "id": "tool-variable-lookup-resolves-without-the-leading-dashes",
+    "kind": "tool",
+    "passed": true,
+  },
 ]
 `;

package/src/testing/eval/cases/effectful.ts

@@ -186,7 +186,13 @@ export const effectfulEvalCases: readonly EvalCase[] = [
         assert.ok(!tools.includes("token_add-config"));
         assert.deepEqual(
           tools.filter((name) => name.startsWith("token")).sort(),
-          ["token_list", "token_lookup", "token_sample"],
+          [
+            "token_consumers",
+            "token_list",
+            "token_lookup",
+            "token_sample",
+            "token_values",
+          ],
         );
       });
     },

package/src/testing/eval/cases/readNouns.ts

@@ -165,7 +165,7 @@ export const readNounEvalCases: readonly EvalCase[] = [
     id: "tool-token-lookup-addresses-only-what-list-publishes",
     kind: "tool",
     input:
-      "a ds:Token carrying no ds:tokenId appears in no token_list row, resolves through no token_lookup name, and is drawn by no token_sample.",
+      "a dt:TokenSymbol carrying no rdfs:label appears in no token_list row, resolves through no token_lookup name, and is drawn by no token_sample.",
     async expect() {
       await withCanonicalFixture(ALL_VISIBLE_CONFIG, async (mcp) => {
         const list = await mcp.callTool("token_list");
@@ -175,11 +175,11 @@ export const readNounEvalCases: readonly EvalCase[] = [
         );
         assert.ok(published.size > 0, "expected token_list to publish rows");
         // The IRI-derived spellings the fallback would have minted for
-        // `ds:token.legacy.borderRadius` (local name, dots as slashes).
-        for (const derived of [
-          "token.legacy.borderRadius",
-          "token/legacy/borderRadius",
-        ]) {
+        // `dt:legacy.borderRadius` — the local name, and the same local name
+        // with its dots published as slashes, which is what the kernel's
+        // derivation actually does and the reason the token noun declares no
+        // fallback at all.
+        for (const derived of ["legacy.borderRadius", "legacy/borderRadius"]) {
           assert.ok(
             !published.has(derived),
             `token_list must not publish ${derived}`,
@@ -265,15 +265,19 @@ export const readNounEvalCases: readonly EvalCase[] = [
     id: "content-canonical-graph-has-4-components",
     kind: "content",
     input:
-      "the canonical fixture graph carries 4 ds:Component individuals (Button, Modal, LXD Panel, Beta Widget); block_list also surfaces the untiered Button Icon subcomponent (A2).",
+      'the canonical fixture graph carries 4 ds:Component individuals (Button, Modal, LXD Panel, Beta Widget); block_list {tier:"all"} also surfaces the untiered Button Icon subcomponent (A2).',
     async expect() {
       await withCanonicalFixture(ALL_VISIBLE_CONFIG, async (mcp) => {
-        const result = await mcp.callTool("block_list");
+        // `tier: "all"` because the claim is about the POPULATION, and the
+        // default tier scope answers from the top-level tiers alone — LXD Panel
+        // is two levels down. The scope's own narrowing is asserted where that
+        // is the claim (`behavioral/journeys.cli.test.ts`).
+        const result = await mcp.callTool("block_list", { tier: "all" });
         const names = (result.data as { name: string }[])
           .map((r) => r.name)
           .sort();
-        // The declared list takes no arguments and filters nothing: the 4 tiered
-        // components plus the untiered Button Icon subcomponent (A2).
+        // Every tier, and nothing else filtered: the 4 tiered components plus
+        // the untiered Button Icon subcomponent (A2).
         assert.deepEqual(names, [
           "Beta Widget",
           "Button",
@@ -422,7 +426,10 @@ export const readNounEvalCases: readonly EvalCase[] = [
       const normal = await namesUnder(CANONICAL_CONFIG);
       const prerelease = await namesUnder(ALL_VISIBLE_CONFIG);
       // The signed-off consequence: an experimental block is visible to
-      // everyone, on every channel, until filtering returns in declared form.
+      // everyone, on every channel. The TIER scope narrows these reads (both
+      // configs set no tier, so both answer from the top-level tiers) and the
+      // channel narrows neither — which is exactly the asymmetry this case
+      // holds: the two answers are equal, and the beta block is in both.
       assert.ok(normal.includes("Beta Widget"));
       assert.deepEqual(normal, prerelease);
     },
@@ -456,6 +463,88 @@ export const readNounEvalCases: readonly EvalCase[] = [
       });
     },
   },
+  // The token-graph nouns run against the SHARED env rather than a fixture:
+  // the canonical fixture carries no token strata, and what these cases are
+  // for is that the SHIPPED pack answers them — the name literals both nouns
+  // key on ship with the pack, so a fixture would prove nothing about that.
+  {
+    id: "tool-token-lookup-dotted-name-resolves-with-its-definitions",
+    kind: "tool",
+    input:
+      "token_lookup {name:[color.text]} resolves the dotted name and carries definitions, coverage and values.",
+    async expect({ mcp }) {
+      const result = await mcp.callTool("token_lookup", {
+        name: ["color.text"],
+      });
+      assert.equal(result.ok, true);
+      const entity = (result.data as { results: Record<string, unknown>[] })
+        .results[0];
+      assert.equal(entity?.name, "color.text");
+      for (const section of ["definitions", "coverage", "values"]) {
+        assert.ok(
+          Array.isArray(entity?.[section]) &&
+            (entity[section] as unknown[]).length > 0,
+          `expected a non-empty ${section} array`,
+        );
+      }
+    },
+  },
+  {
+    id: "tool-variable-lookup-resolves-without-the-leading-dashes",
+    kind: "tool",
+    input:
+      "variable_lookup {name:[color-text]} resolves the dash-stripped CSS name and names the symbol it stands for.",
+    async expect({ mcp }) {
+      const result = await mcp.callTool("variable_lookup", {
+        name: ["color-text"],
+      });
+      assert.equal(result.ok, true);
+      const entity = (result.data as { results: Record<string, unknown>[] })
+        .results[0];
+      assert.equal(entity?.name, "color-text");
+      assert.equal(entity?.symbol, "color.text");
+      assert.ok(
+        Array.isArray(entity?.declarations) &&
+          (entity.declarations as unknown[]).length > 0,
+        "expected a non-empty declarations array",
+      );
+    },
+  },
+  {
+    id: "tool-token-values-narrows-to-one-symbol",
+    kind: "tool",
+    input:
+      "token_values {symbol:color.text} returns only that symbol's materialised positions, each with a value or a derivation.",
+    async expect({ mcp }) {
+      const result = await mcp.callTool("token_values", {
+        symbol: "color.text",
+      });
+      assert.equal(result.ok, true);
+      const rows = result.data as Record<string, string>[];
+      assert.ok(rows.length > 0, "expected at least one resolved value");
+      for (const row of rows) {
+        assert.equal(row.symbol, "color.text");
+        assert.ok(
+          row.value !== undefined || row.derivedFrom !== undefined,
+          "every row carries a value or a derivation",
+        );
+      }
+    },
+  },
+  {
+    id: "tool-token-consumers-answers-or-recovers",
+    kind: "tool",
+    input:
+      "token_consumers {} either returns binding rows or reports a recoverable empty result — never an error.",
+    async expect({ mcp }) {
+      // Deliberately not asserting emptiness: the design-system packs will
+      // record bindings, and a case pinning the empty answer would fail on
+      // that correct change. What must hold either way is that the call
+      // SUCCEEDS.
+      const result = await mcp.callTool("token_consumers", {});
+      assert.equal(result.ok, true);
+    },
+  },
   {
     id: "prompt-block-question-maps-to-block-lookup",
     kind: "prompt",

package/src/testing/fixtures/blockGraph.ts

@@ -32,6 +32,12 @@ export const BLOCK_PREFIXES: Readonly<Record<string, string>> = {
   owl: "http://www.w3.org/2002/07/owl#",
   rdfs: "http://www.w3.org/2000/01/rdf-schema#",
   xsd: "http://www.w3.org/2001/XMLSchema#",
+  // The token-binding record spans three vocabularies exactly as the live
+  // graph does: the design system owns the record and its edges, the token
+  // ontology the symbol it consumes, and the anatomy DSL the style key and
+  // state it applies at.
+  anatomy: "https://anatomy.canonical.com/",
+  dt: "https://dt.canonical.com/",
 };
 
 /**
@@ -52,6 +58,8 @@ export const BLOCK_TTL = `
 @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#> .
+@prefix anatomy: <https://anatomy.canonical.com/> .
+@prefix dt: <https://dt.canonical.com/> .
 
 # ---- Ontology (TBox) ----
 ds:UIBlock a owl:Class .
@@ -87,6 +95,29 @@ ds:optional a owl:DatatypeProperty ; rdfs:domain ds:BlockProperty ; rdfs:range x
 # Domain is ds:Component (not ds:UIBlock) — reached via subtype scoping.
 ds:hasSubcomponent a owl:ObjectProperty ; rdfs:domain ds:Component ; rdfs:range ds:Subcomponent .
 
+# The token-binding record, modelled with the live graph's split ownership —
+# which is what makes the block lookup's \`tokens\` expand a SPARQL-lane one.
+#
+# The five ds: edges carry a domain and a range, so ke-graphql derives a field
+# for each and a document could read them. \`anatomy:styleKey\` and
+# \`anatomy:styleState\` carry NO rdfs:domain, because they belong to the anatomy
+# vocabulary and apply to every styled thing rather than to this record — so no
+# field is derived for either, and a generated document drops them in SILENCE.
+# They are two of the six columns that IDENTIFY a binding, so dropping them
+# leaves rows a reader cannot tell apart. Preserved here deliberately: change
+# the fixture to declare a domain and the suite stops testing the condition the
+# lane exists for.
+ds:TokenBinding a owl:Class .
+ds:hasTokenBinding a owl:ObjectProperty ; rdfs:domain ds:UIBlock ; rdfs:range ds:TokenBinding .
+ds:consumesSymbol a owl:ObjectProperty, owl:FunctionalProperty ;
+  rdfs:domain ds:TokenBinding ; rdfs:range dt:TokenSymbol .
+ds:viaBlock a owl:ObjectProperty ; rdfs:domain ds:TokenBinding ; rdfs:range ds:UIBlock .
+ds:rank a owl:DatatypeProperty ; rdfs:domain ds:TokenBinding ; rdfs:range xsd:integer .
+ds:node a owl:DatatypeProperty ; rdfs:domain ds:TokenBinding ; rdfs:range xsd:string .
+dt:TokenSymbol a owl:Class .
+anatomy:styleKey a owl:DatatypeProperty ; rdfs:range xsd:string .
+anatomy:styleState a owl:DatatypeProperty ; rdfs:range xsd:string .
+
 # ---- Individuals (ABox) ----
 ds:global a ds:Tier ; ds:name "global" .
 
@@ -101,7 +132,9 @@ ds:button a ds:Component ;
   ds:figmaLink "https://figma.com/design/example/Button" ;
   ds:hasModifierFamily ds:family.importance, ds:family.density ;
   ds:hasProperty ds:button.prop.disabled ;
-  ds:hasSubcomponent ds:button.icon .
+  ds:hasSubcomponent ds:button.icon ;
+  ds:hasTokenBinding ds:binding.button.bg1, ds:binding.button.bg2,
+    ds:binding.button.text, ds:binding.button.icon .
 
 ds:modal a ds:Component ;
   ds:name "Modal" ;
@@ -111,10 +144,49 @@ ds:modal a ds:Component ;
   ds:guidelines "Always provide an explicit close affordance." ;
   ds:anatomyDsl "root: dialog; children: header, body, footer" ;
   ds:hasModifierFamily ds:family.size ;
-  ds:hasProperty ds:modal.prop.open .
+  ds:hasProperty ds:modal.prop.open ;
+  ds:hasTokenBinding ds:binding.modal.button .
 
 ds:button.icon a ds:Subcomponent ; ds:name "Button Icon" .
 
+# The symbols the bindings consume, addressed by the dotted name the token
+# noun publishes — which is what the expand's \`ds:consumesSymbol/rdfs:label\`
+# path reads, so a row here is an address \`token lookup\` takes.
+dt:color.background a dt:TokenSymbol ; rdfs:label "color.background" .
+dt:color.background.hover a dt:TokenSymbol ; rdfs:label "color.background.hover" .
+dt:color.text a dt:TokenSymbol ; rdfs:label "color.text" .
+dt:color.icon a dt:TokenSymbol ; rdfs:label "color.icon" .
+
+# Button's own tree. Two records share a node and a key and differ ONLY in
+# state and rank — the pair that proves the two columns the GraphQL lane cannot
+# see are the ones that tell the rows apart. The declaration order here is
+# deliberately NOT the reading order (node, then key, then rank), so the
+# expand's own ORDER BY is what puts them right.
+ds:binding.button.bg2 a ds:TokenBinding ;
+  ds:consumesSymbol dt:color.background.hover ;
+  anatomy:styleKey "appearance.background" ; anatomy:styleState "hover" ;
+  ds:rank 2 ; ds:viaBlock ds:button ; ds:node "$root" .
+ds:binding.button.bg1 a ds:TokenBinding ;
+  ds:consumesSymbol dt:color.background ;
+  anatomy:styleKey "appearance.background" ; anatomy:styleState "default" ;
+  ds:rank 1 ; ds:viaBlock ds:button ; ds:node "$root" .
+ds:binding.button.text a ds:TokenBinding ;
+  ds:consumesSymbol dt:color.text ;
+  anatomy:styleKey "typography.color" ; anatomy:styleState "default" ;
+  ds:rank 1 ; ds:viaBlock ds:button ; ds:node "$root" .
+# Reached through the subcomponent Button's anatomy embeds, so its via DIFFERS
+# from the block and must print.
+ds:binding.button.icon a ds:TokenBinding ;
+  ds:consumesSymbol dt:color.icon ;
+  anatomy:styleKey "appearance.background" ; anatomy:styleState "default" ;
+  ds:rank 1 ; ds:viaBlock ds:button.icon ; ds:node "$root/icon" .
+# Modal consumes nothing of its own: its one record is Button's, reached
+# through the Button its anatomy embeds.
+ds:binding.modal.button a ds:TokenBinding ;
+  ds:consumesSymbol dt:color.background ;
+  anatomy:styleKey "appearance.background" ; anatomy:styleState "default" ;
+  ds:rank 1 ; ds:viaBlock ds:button ; ds:node "$root/footer" .
+
 ds:button.prop.disabled a ds:BlockProperty ;
   ds:name "disabled" ; ds:propertyType "boolean" ; ds:optional true .
 ds:modal.prop.open a ds:BlockProperty ;
@@ -176,10 +248,17 @@ ${ROSTER_MEMBERS}
  * parity, ontology and GraphQL-engine suites assert over the base graph and
  * must keep seeing exactly two components.
  *
- * It models the three shapes the addressing path gets wrong: two components
+ * It models the four shapes the addressing path gets wrong: two components
  * sharing one `ds:name` (declared zeta-first so the store's enumeration order
- * and IRI order DISAGREE), and a component carrying no `ds:name` at all
- * (reachable only by IRI, the way 131 of the 144 live code standards are).
+ * and IRI order DISAGREE), a component carrying no `ds:name` at all (reachable
+ * only by IRI, the way 131 of the 144 live code standards are), and a component
+ * whose `ds:name` is PADDED with a trailing space.
+ *
+ * That last one is copied from the live graph, not invented: 66 shipped names
+ * end in a space, carried across by the transform that reads them out of the
+ * source document, and `block lookup Timeline` used to answer
+ * ENTITY_NOT_FOUND while suggesting "Timeline " back. It is spelled with the
+ * live name so the fixture reads as the report it came from.
  *
  * The shared name is a SHAPE probe, not the live ambiguity: neither chip's tier
  * outranks the other, so this fixture can only prove that both are returned in a
@@ -203,4 +282,9 @@ ds:alpha.chip a ds:Component ;
 ds:nameless.widget a ds:Component ;
   ds:tier ds:global ;
   ds:summary "Carries no ds:name; addressable only by IRI." .
+
+ds:padded.timeline a ds:Component ;
+  ds:name "Timeline " ;
+  ds:tier ds:global ;
+  ds:summary "Its ds:name carries the source document's trailing space." .
 `;