@canonical/pragma-cli 0.32.0 → 0.34.0

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

@@ -0,0 +1,283 @@
+/**
+ * Doc-example tests: every `pragma` command shown in the published README and
+ * the getting-started guide must be REAL. Two tiers, both driven off the live
+ * grammar (never a hand-copied list):
+ *
+ * - Tier 1 (grammar) — every extracted command's noun/verb resolves and every
+ *   `--flag` is one the verb (or the global/mutation set) declares. Storeless.
+ * - Tier 2 (execution) — a curated set of read commands is PARSED through the
+ *   real CLI grammar (so the param bag is derived from the documented string,
+ *   never hand-supplied) and then booted against the canonical fixture graph
+ *   and asserted to exit 0, proving the documented reads run, not just parse.
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { capabilities } from "../../capabilities/index.js";
+import {
+  executeVerb,
+  extractParams,
+} from "../../kernel/project/cli/dispatch.js";
+import {
+  nounVerbMap,
+  resolveUnknownCommand,
+} from "../../kernel/project/cli/suggest.js";
+import { kebabCase } from "../../kernel/spec/emitSurface.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import {
+  CANONICAL_CONFIG,
+  CANONICAL_TTL,
+} from "../fixtures/graph/canonical.js";
+import { extractPragmaCommands } from "../helpers/extractSnippets.js";
+import { bootFixtureRuntime } from "../helpers/fixtureGraph.js";
+import { projectCli } from "../helpers/projectCli.js";
+
+/** Read a shipped doc exactly as a reader (or lychee) would. */
+function readDoc(relPath: string): string {
+  return readFileSync(
+    fileURLToPath(new URL(relPath, import.meta.url)),
+    "utf-8",
+  );
+}
+
+/** Every hand-written doc whose fenced `pragma` examples must be real grammar. */
+const HAND_WRITTEN_DOCS = [
+  "../../../README.md",
+  "../../../docs/getting-started.md",
+  "../../../docs/mcp-integration.md",
+  "../../../docs/config-model.md",
+  "../../../docs/architecture.md",
+  "../../../docs/skills.md",
+];
+
+const commands = HAND_WRITTEN_DOCS.flatMap((doc) =>
+  extractPragmaCommands(readDoc(doc)),
+);
+
+/** Every non-hidden verb, flattened from the live catalog. */
+const allVerbs: VerbSpec[] = capabilities
+  .flatMap((module) => [...module.verbs])
+  .filter((verb) => !verb.hidden);
+const nouns = nounVerbMap(allVerbs);
+
+/** `"noun verb"` (or `"noun"` for a self-verb) → the runnable spec. */
+const specByKey = new Map<string, VerbSpec>();
+for (const verb of allVerbs) {
+  const sub = verb.path[1];
+  specByKey.set(
+    sub === undefined ? verb.path[0] : `${verb.path[0]} ${sub}`,
+    verb,
+  );
+}
+
+/** Flags valid on every command, beyond a verb's own declared flags. */
+const AMBIENT_FLAGS = new Set([
+  "--llm",
+  "--format",
+  "--verbose",
+  "--detail",
+  "--dry-run",
+  "--undo",
+  "--yes",
+  "--help",
+  "--version",
+]);
+
+/** The positional tokens of a command (drops `pragma` and every `-`-prefixed token). */
+function readPositionals(command: string): string[] {
+  return command
+    .split(/\s+/)
+    .slice(1)
+    .filter((token) => !token.startsWith("-"));
+}
+
+/** Resolve a command's `VerbSpec` from its positionals (verb pair, else self-verb). */
+function resolveSpec(positionals: readonly string[]): VerbSpec | undefined {
+  const noun = positionals.at(0);
+  const verb = positionals.at(1);
+  if (noun === undefined) return undefined;
+  const paired =
+    verb !== undefined ? specByKey.get(`${noun} ${verb}`) : undefined;
+  return paired ?? specByKey.get(noun);
+}
+
+/** The set of flags a verb accepts: its own declared flags plus the ambient set. */
+function collectValidFlags(verb: VerbSpec): Set<string> {
+  const flags = new Set(AMBIENT_FLAGS);
+  for (const param of verb.params) {
+    if (!param.positional) flags.add(`--${kebabCase(param.name)}`);
+  }
+  return flags;
+}
+
+describe("doc examples — Tier 1: every documented command is grammatical", () => {
+  it("extracts commands from the docs", () => {
+    // A guard against a broken extractor silently passing everything else.
+    expect(commands.length).toBeGreaterThan(0);
+  });
+
+  it("resolves every command's noun and verb", () => {
+    for (const command of commands) {
+      const unknown = resolveUnknownCommand(readPositionals(command), nouns);
+      expect(unknown, `unresolved command: ${command}`).toBeUndefined();
+    }
+  });
+
+  it("uses only flags the verb or the ambient set declares", () => {
+    for (const command of commands) {
+      const spec = resolveSpec(readPositionals(command));
+      expect(spec, `no spec for: ${command}`).toBeDefined();
+      if (!spec) continue;
+      const allowed = collectValidFlags(spec);
+      for (const token of command.split(/\s+/)) {
+        if (!token.startsWith("--")) continue;
+        const flag = token.split("=").at(0) ?? token;
+        expect(allowed.has(flag), `unknown flag ${flag} in: ${command}`).toBe(
+          true,
+        );
+      }
+    }
+  });
+});
+
+/**
+ * One curated read: its documented form, the verb key it must route to, and the
+ * param bag the real parser must derive from {@link ReadCase.command} (the
+ * oracle Tier 2 asserts the parse against before executing).
+ */
+interface ReadCase {
+  readonly command: string;
+  readonly key: string;
+  readonly params: Record<string, unknown>;
+}
+
+/** Reads that can run storelessly or against the canonical fixture graph. */
+const READ_CASES: readonly ReadCase[] = [
+  { command: "pragma block list", key: "block list", params: {} },
+  {
+    command: "pragma block lookup Button",
+    key: "block lookup",
+    params: { name: ["Button"] },
+  },
+  { command: "pragma standard list", key: "standard list", params: {} },
+  { command: "pragma token list", key: "token list", params: {} },
+  { command: "pragma tier list", key: "tier list", params: {} },
+  { command: "pragma ontology list", key: "ontology list", params: {} },
+  { command: "pragma config show", key: "config show", params: {} },
+  { command: "pragma sources status", key: "sources status", params: {} },
+  { command: "pragma doctor", key: "doctor", params: {} },
+  { command: "pragma info", key: "info", params: {} },
+  { command: "pragma capabilities", key: "capabilities", params: {} },
+  { command: "pragma colophon", key: "colophon", params: {} },
+];
+
+const NO_MUTATION = { dryRun: false, undo: false, yes: false };
+
+/**
+ * Thrown by the capture hook to halt a parse at the resolved verb — before the
+ * real dispatch (and its runtime boot) fires — carrying the routed path plus the
+ * Commander-parsed operands and options.
+ */
+class ParsedCommand extends Error {
+  constructor(
+    readonly path: readonly string[],
+    readonly positionals: string[],
+    readonly opts: Record<string, unknown>,
+  ) {
+    super("parsed");
+  }
+}
+
+/**
+ * Parse a documented `pragma …` line through the REAL CLI grammar and return the
+ * verb it routes to plus the coerced param bag {@link extractParams} derives —
+ * WITHOUT running it. A `preAction` hook captures the resolved command and
+ * throws before its action, so no runtime boots. Deriving the bag from the
+ * STRING (rather than hand-supplying it) is what closes the Tier-2 gap: a
+ * documented positional in the wrong slot now yields a different bag, instead of
+ * a hand-fed bag masking the mistake.
+ *
+ * @param command - The documented `pragma …` command line.
+ * @returns The routed verb key, its spec, and the parser-derived param bag.
+ */
+async function parseDocumented(
+  command: string,
+): Promise<{ key: string; spec: VerbSpec; params: Record<string, unknown> }> {
+  const program = projectCli(capabilities);
+  program.hook("preAction", (_root, action) => {
+    const parentName = action.parent?.name();
+    const routed =
+      parentName !== undefined && parentName !== "pragma"
+        ? [parentName, action.name()]
+        : [action.name()];
+    throw new ParsedCommand(routed, [...action.args], action.opts());
+  });
+
+  const argv = command.split(/\s+/).slice(1); // drop the leading `pragma`
+  try {
+    await program.parseAsync(argv, { from: "user" });
+  } catch (error) {
+    if (!(error instanceof ParsedCommand)) throw error;
+    const key = error.path.join(" ");
+    const spec = specByKey.get(key);
+    if (spec === undefined) {
+      throw new Error(`documented command routed to unknown verb: ${key}`);
+    }
+    return {
+      key,
+      spec,
+      params: extractParams(spec.params, error.positionals, error.opts),
+    };
+  }
+  throw new Error(`documented command reached no verb action: ${command}`);
+}
+
+describe("doc examples — Tier 2: curated read commands run green", () => {
+  let fixture: Awaited<ReturnType<typeof bootFixtureRuntime>> | undefined;
+  const documented = new Set(commands);
+
+  beforeAll(async () => {
+    fixture = await bootFixtureRuntime({
+      ttl: CANONICAL_TTL,
+      config: CANONICAL_CONFIG,
+    });
+  });
+
+  afterAll(async () => {
+    await fixture?.dispose();
+  });
+
+  for (const readCase of READ_CASES) {
+    it(`\`${readCase.command}\` parses to its verb and exits 0`, async () => {
+      expect(
+        documented.has(readCase.command),
+        `not documented: ${readCase.command}`,
+      ).toBe(true);
+
+      // Derive the verb + param bag from the DOCUMENTED string via the real
+      // grammar, then assert both against the oracle: a mis-slotted positional
+      // would route elsewhere or yield a different bag, failing here.
+      const parsed = await parseDocumented(readCase.command);
+      expect(parsed.key, `routed to the wrong verb: ${readCase.command}`).toBe(
+        readCase.key,
+      );
+      expect(
+        parsed.params,
+        `parsed bag ≠ expected for: ${readCase.command}`,
+      ).toEqual(readCase.params);
+
+      if (!fixture) return;
+      const outcome = await executeVerb(
+        parsed.spec,
+        parsed.params,
+        NO_MUTATION,
+        fixture.runtime,
+      );
+      expect(
+        outcome.exitCode,
+        `${readCase.command} → ${outcome.stderr ?? ""}`,
+      ).toBe(0);
+    });
+  }
+});

package/src/testing/behavioral/errorMatrix.mcp.test.ts

@@ -32,9 +32,10 @@ import { listVerbs, lookupVerbs } from "./liveReadSurface.js";
 
 /**
  * List verbs with a STRING or ENUM (narrowable, non-boolean) flag — e.g.
- * `standard_list --category`. Excludes boolean escape hatches like `block
- * list --all-tiers`, which reject a string value at the schema layer rather
- * than narrowing to an empty result.
+ * `standard_list --category`. Boolean flags are excluded: they reject a string
+ * value at the schema layer rather than narrowing to an empty result. (`block
+ * list --all-tiers` used to be the example; it retired with the hand-written
+ * filtering in L-OPEN-9.)
  */
 const filteredListVerbs = listVerbs
   .map((v) => {

package/src/testing/behavioral/errorMatrix.storeless.test.ts

@@ -46,7 +46,8 @@ const MATRIX: readonly {
   {
     label: "validOptions",
     error: PragmaError.invalidInput("format", "yaml", {
-      validOptions: ["plain", "json"],
+      // The live `--format` set (mirrors bin.ts): plain, llm, json.
+      validOptions: ["plain", "llm", "json"],
     }),
   },
   {
@@ -60,7 +61,7 @@ const MATRIX: readonly {
   },
   {
     label: "recovery (mcp-only, no cli)",
-    error: PragmaError.storeUnavailable("no lock", {
+    error: PragmaError.storeUnavailable("the store has not been built", {
       recovery: { message: "Please report this issue." },
     }),
   },

package/src/testing/behavioral/exitCodes.e2e.test.ts

@@ -37,14 +37,15 @@ describe("exit-code covenant, spawn-observed (A4, e2e)", () => {
     expect(result.stderr).toContain('Invalid format "yaml"');
   });
 
-  it("3 — store unavailable (configured packages, never built)", () => {
+  it("3 — store unavailable (configured packs, never built)", () => {
     const cwd = mkdtempSync(join(tmpdir(), "pragma-exit3-"));
-    // A pragma.config.ts with custom `packages` flips `origins.packages` to
-    // "project" — with no `pragma.lock.json`, resolveSources refuses to boot
-    // (no network probing) rather than fall back to the embedded pack.
+    // A pragma.config.ts with custom `packs` flips `origins.packs` to
+    // "project" — with nothing built for this project, resolveSources refuses
+    // to boot (no network probing) rather than serve the embedded pack, which
+    // is a DIFFERENT graph from the one this project asked for.
     writeFileSync(
       join(cwd, "pragma.config.ts"),
-      'export default { packages: [{ name: "never-built", source: "file:///nonexistent" }] };\n',
+      'export default { packs: [{ name: "never-built", source: "file:///nonexistent" }] };\n',
     );
     const result = runCli(["block", "list"], { cwd });
     expect(result.exitCode).toBe(3);

package/src/testing/behavioral/harness.foundation.test.ts

@@ -2,8 +2,8 @@
  * Harness-foundation smoke tests (commit 1).
  *
  * Validates the framework pieces PR4 adds — NOT per-noun behavior (that's
- * commits 2/4's job). Proves: (1) `bootFixtureRuntime` boots a real,
- * lock-backed store that BOTH the CLI and MCP surfaces resolve identically
+ * commits 2/4's job). Proves: (1) `bootFixtureRuntime` boots a real, built-pack
+ * store that BOTH the CLI and MCP surfaces resolve identically
  * (via the shared canonical graph, one real lookup); (2) the compiler/runtime
  * is ontology-agnostic — a pack over the foreign `ex:` recipe namespace
  * registers its 2 tools and resolves on both surfaces; (3) `runCli` can spawn
@@ -12,7 +12,7 @@
 
 import { homedir, tmpdir } from "node:os";
 import { describe, expect, it } from "vitest";
-import { blockModule } from "../../capabilities/block/index.js";
+import { storyModules } from "../../capabilities/distribution.js";
 import { VERSION } from "../../constants.js";
 import { compilePack } from "../../kernel/packs/compile.js";
 import { verbKey } from "../../kernel/packs/uniqueness.js";
@@ -31,8 +31,13 @@ import { plain } from "../helpers/golden.js";
 import { assertCliMcpParity } from "../helpers/parity.js";
 import { runCli } from "../helpers/runCli.js";
 
+const blockModule = storyModules.get("block");
+if (!blockModule) {
+  throw new Error('pragma.conf.ts declares no story for "block"');
+}
+
 describe("bootFixtureRuntime — the shared canonical graph (commit-1 smoke)", () => {
-  it("boots a lock-backed store both CLI and MCP resolve identically", async () => {
+  it("boots a built-pack store both CLI and MCP resolve identically", async () => {
     const fixture = await bootFixtureRuntime({
       ttl: CANONICAL_TTL,
       config: CANONICAL_CONFIG,
@@ -68,7 +73,11 @@ describe("foreign-namespace generic-pack proof (compiler is DS-agnostic)", () =>
     try {
       const recipeModule: CapabilityModule = {
         name: "recipe",
-        verbs: compilePack(recipePack, "test:recipe", RECIPE_PREFIXES),
+        verbs: compilePack(
+          recipePack,
+          { label: "test:recipe", origin: "package" },
+          RECIPE_PREFIXES,
+        ),
       };
       expect(recipeModule.verbs.map((v) => verbKey(v.path)).sort()).toEqual([
         "recipe list",

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

@@ -1,6 +1,5 @@
 /**
- * B9 — the tier-chain / channel CLI journey (PR3 Risk5's ONE hand-written
- * verb, `block list`).
+ * B9 — the `block list` CLI journey, re-pinned on the DECLARED contract.
  *
  * BACKING ADAPTATION: the plan lists this as "fixture + spawn"; the PR4 quality
  * bar (R7 — keep the spawn-e2e layer to exactly A1-A4/A7) overrides that, so
@@ -9,42 +8,86 @@
  * against the fixture, rather than spawning. It still exercises the true CLI
  * seam (typed params -> dispatch -> render), just without forking a process.
  *
+ * CONTRACT CHANGE (L-OPEN-9): this journey used to enumerate four different
+ * answers — one per tier config, one per channel, one for `--all-tiers`. That
+ * hand-written filtering is gone; `block list` is the block story's compiled,
+ * UNFILTERED list. So the journey pins the honest NEW behaviour, which is a
+ * STRONGER claim than the old one: the SAME graph under FOUR different configs
+ * gives ONE answer, containing every block in the store. `config.tier` and
+ * `config.channel` no longer reach the query at all, and the owner-signed
+ * consequence — experimental/alpha blocks are visible to everyone — is asserted
+ * here rather than left to prose.
+ *
  * CONTENT ADAPTATION (R2 — verified against the live `block lookup`, not
  * assumed): the plan's wording describes an unscoped `block lookup` returning
  * multiple tier-disambiguated matches — that mechanism doesn't exist in v2
  * (`block lookup` resolves by name GLOBALLY with no tier awareness at all;
- * PARITY_GAPS `block-lookup-not-tier-scoped`). Only `block list` is
- * tier/channel-aware, so this journey is entirely about `block list` under
- * different tier configs on the SAME canonical graph.
+ * PARITY_GAPS `block-lookup-not-tier-scoped`). Since L-OPEN-9 neither block
+ * verb is tier-aware, so both halves of the noun now agree.
  */
 
 import { afterAll, describe, expect, it } from "vitest";
-import { blockModule } from "../../capabilities/block/index.js";
+import { storyModules } from "../../capabilities/distribution.js";
 import { verbKey } from "../../kernel/packs/uniqueness.js";
 import { executeVerb } from "../../kernel/project/cli/dispatch.js";
 import { bootRuntime } from "../../kernel/runtime/boot.js";
 import type { VerbSpec } from "../../kernel/spec/types.js";
 import {
+  ALL_VISIBLE_CONFIG,
   CANONICAL_CONFIG,
   CANONICAL_TTL,
+  FILTERED_CONFIG,
 } from "../fixtures/graph/canonical.js";
 import {
   bootFixtureRuntime,
   type FixtureGraph,
+  type FixtureGraphOptions,
 } from "../helpers/fixtureGraph.js";
 import { JSON_FLAGS, NO_MUTATION } from "../helpers/parity.js";
 
+const blockModule = storyModules.get("block");
+if (!blockModule) {
+  throw new Error('pragma.conf.ts declares no story for "block"');
+}
+
 const listVerb = blockModule.verbs.find(
   (v) => verbKey(v.path) === "block list",
 ) as VerbSpec;
 
-async function blockListNames(
-  fixture: FixtureGraph,
-  allTiers = false,
-): Promise<string[]> {
+/**
+ * Every block the canonical fixture carries: two global components, one scoped
+ * to `apps/lxd`, one gated to the `beta` release channel, and one UNTIERED
+ * subcomponent. Under the hand-written verb NO single invocation returned all
+ * five — the tier chain hid `LXD Panel`, the channel hid `Beta Widget`, and only
+ * `--all-tiers` revealed `Button Icon`. The declared list returns all five, and
+ * returns them whatever the config says.
+ */
+const EVERY_BLOCK = [
+  "Beta Widget",
+  "Button",
+  "Button Icon",
+  "LXD Panel",
+  "Modal",
+];
+
+const fixtures: FixtureGraph[] = [];
+afterAll(async () => {
+  await Promise.all(fixtures.map((f) => f.dispose()));
+});
+
+/** Boot a tracked canonical fixture under `config`, for auto-disposal. */
+async function bootWith(
+  config: FixtureGraphOptions["config"],
+): Promise<FixtureGraph> {
+  const fixture = await bootFixtureRuntime({ ttl: CANONICAL_TTL, config });
+  fixtures.push(fixture);
+  return fixture;
+}
+
+async function blockListNames(fixture: FixtureGraph): Promise<string[]> {
   const out = await executeVerb(
     listVerb,
-    { allTiers },
+    {},
     NO_MUTATION,
     bootRuntime(JSON_FLAGS, fixture.cwd),
   );
@@ -52,78 +95,78 @@ async function blockListNames(
   return rows.map((r) => r.name).sort();
 }
 
-const fixtures: FixtureGraph[] = [];
-afterAll(async () => {
-  await Promise.all(fixtures.map((f) => f.dispose()));
-});
+describe("block list — the declared, unfiltered list (B9, in-process CLI dispatch)", () => {
+  it("with no tier configured, lists every block in the store", async () => {
+    expect(await blockListNames(await bootWith(CANONICAL_CONFIG))).toEqual(
+      EVERY_BLOCK,
+    );
+  });
 
-describe("block list — tier-chain inheritance (B9, in-process CLI dispatch)", () => {
-  it("unscoped (no tier configured) sees every tier", async () => {
-    const fixture = await bootFixtureRuntime({
-      ttl: CANONICAL_TTL,
-      config: CANONICAL_CONFIG, // channel: normal, no tier set
-    });
-    fixtures.push(fixture);
-    // normal channel drops the beta-only block; no tier set -> every tier.
-    expect(await blockListNames(fixture)).toEqual([
-      "Button",
-      "LXD Panel",
-      "Modal",
-    ]);
+  it("a configured tier does NOT narrow the list — tier scopes nothing", async () => {
+    // The old verb answered ["Button", "Modal"] here: `global` excluded the
+    // apps/lxd block, and the required `ds:tier` join hid the untiered
+    // subcomponent. Nothing filters now, so the tier config is inert.
+    const fixture = await bootWith({ tier: "global", channel: "normal" });
+    expect(await blockListNames(fixture)).toEqual(EVERY_BLOCK);
   });
 
-  it("scoped to the global tier excludes the apps/lxd-only block", async () => {
-    const fixture = await bootFixtureRuntime({
-      ttl: CANONICAL_TTL,
-      config: { tier: "global", channel: "normal" },
-    });
-    fixtures.push(fixture);
-    expect(await blockListNames(fixture)).toEqual(["Button", "Modal"]);
+  it("the deepest tier in the chain gets the same answer as the shallowest", async () => {
+    // Tier-chain inheritance was the point of the hand-written query
+    // (`apps/lxd` -> [global, apps, apps/lxd]). With no filtering there is no
+    // chain to walk, so `apps/lxd` and `global` are indistinguishable.
+    expect(await blockListNames(await bootWith(FILTERED_CONFIG))).toEqual(
+      EVERY_BLOCK,
+    );
   });
+});
 
-  it("scoped to apps/lxd includes its OWN block plus the inherited chain", async () => {
-    const fixture = await bootFixtureRuntime({
-      ttl: CANONICAL_TTL,
-      config: { tier: "apps/lxd", channel: "normal" },
-    });
-    fixtures.push(fixture);
-    // resolveTierChain("apps/lxd") = [global, apps, apps/lxd] — Button/Modal
-    // (global) are inherited; LXD Panel is the tier's own block.
-    expect(await blockListNames(fixture)).toEqual([
-      "Button",
-      "LXD Panel",
-      "Modal",
-    ]);
+describe("block list — channel visibility is gone too (B9)", () => {
+  it("the `normal` channel shows the beta-gated block — the signed-off consequence", async () => {
+    // `ds:betaWidget` carries `ds:release ds:beta`. The hand-written verb hid it
+    // from every channel but `prerelease`; the declared list shows it to
+    // everyone. This is the owner-signed visible consequence of L-OPEN-9,
+    // pinned so it stays a decision on record rather than a silent regression.
+    const names = await blockListNames(await bootWith(CANONICAL_CONFIG));
+    expect(names).toContain("Beta Widget");
   });
 
-  it("--all-tiers ignores a configured tier scope", async () => {
-    const fixture = await bootFixtureRuntime({
-      ttl: CANONICAL_TTL,
-      config: { tier: "global", channel: "normal" },
-    });
-    fixtures.push(fixture);
-    // Scoped (no flag) excludes LXD Panel; --all-tiers restores it.
-    expect(await blockListNames(fixture, false)).toEqual(["Button", "Modal"]);
-    expect(await blockListNames(fixture, true)).toEqual([
-      "Button",
-      "LXD Panel",
-      "Modal",
-    ]);
+  it("`prerelease` — once the only config that saw everything — is now unremarkable", async () => {
+    expect(await blockListNames(await bootWith(ALL_VISIBLE_CONFIG))).toEqual(
+      EVERY_BLOCK,
+    );
   });
 });
 
-describe("block list — channel visibility (B9)", () => {
-  it("prerelease channel is the one config where all 4 components list", async () => {
-    const fixture = await bootFixtureRuntime({
-      ttl: CANONICAL_TTL,
-      config: { channel: "prerelease" },
-    });
-    fixtures.push(fixture);
-    expect(await blockListNames(fixture)).toEqual([
-      "Beta Widget",
-      "Button",
-      "LXD Panel",
-      "Modal",
+describe("block list — the row shape the declared columns emit (B9)", () => {
+  it("derives name/type/tier in SPARQL, and leaves an untiered block's tier unset", async () => {
+    const fixture = await bootWith(CANONICAL_CONFIG);
+    const out = await executeVerb(
+      listVerb,
+      {},
+      NO_MUTATION,
+      bootRuntime(JSON_FLAGS, fixture.cwd),
+    );
+    const rows = JSON.parse(out.stdout as string).data as {
+      name: string;
+      type?: string;
+      tier?: string;
+      uri: string;
+      modifiers?: string;
+    }[];
+    const byName = new Map(rows.map((row) => [row.name, row]));
+
+    // `type` is the LOWERCASED local name of the matched class — the BIND that
+    // replaced the hand-written `normalizeType`.
+    expect(byName.get("Button")?.type).toBe("component");
+    expect(byName.get("Button Icon")?.type).toBe("subcomponent");
+    // `tier` is the tier IRI's local name; an untiered block simply has none.
+    expect(byName.get("Button")?.tier).toBe("global");
+    expect(byName.get("Button Icon")?.tier).toBeUndefined();
+    expect(byName.get("Button")?.uri).toBe("https://ds.canonical.com/button");
+    // GROUP_CONCAT of the modifier family names (order-independent).
+    expect(byName.get("Button")?.modifiers?.split(", ").sort()).toEqual([
+      "density",
+      "importance",
     ]);
   });
 });