@canonical/pragma-cli 0.31.0 → 0.32.0

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

@@ -0,0 +1,120 @@
+/**
+ * B3 — the error/recovery MATRIX, fixture-backed half: per-read-noun lookup
+ * misses, an empty-filtered list, and `ontology_show`'s bad-prefix error.
+ * Parameterized over `liveReadSurface.ts` — never a hard-coded noun.
+ *
+ * TWO ADAPTATIONS from the plan's wording, both verified empirically against
+ * the live kernel (not assumed):
+ *
+ * 1. `<noun>_lookup` on a SINGLE or ALL-unknown batch FAILS the call
+ *    (`ok:false, error.code==="ENTITY_NOT_FOUND"`) — `makeLookupRun` throws on
+ *    a total miss; only a PARTIAL batch reports the miss while staying
+ *    `ok:true` (that shape is B1's job, `agentSession.mcp.test.ts`). See
+ *    PARITY_GAPS `single-lookup-miss-fails-batch-partial-reports`.
+ * 2. A filtered list narrowed to zero rows is `{ok:true, data:[], meta:{}}` —
+ *    there is no `meta.count` field on any read envelope (`dispatch.ts`
+ *    always renders reads with `meta:{}`). See PARITY_GAPS
+ *    `read-meta-always-empty`.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { capabilities } from "../../capabilities/index.js";
+import {
+  ALL_VISIBLE_CONFIG,
+  CANONICAL_TTL,
+} from "../fixtures/graph/canonical.js";
+import {
+  bootFixtureRuntime,
+  type FixtureGraph,
+} from "../helpers/fixtureGraph.js";
+import { projectMcp } from "../helpers/projectMcp.js";
+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.
+ */
+const filteredListVerbs = listVerbs
+  .map((v) => {
+    const flag = v.spec.params.find(
+      (p) => !p.positional && (p.kind === "string" || p.kind === "enum"),
+    );
+    return flag
+      ? { noun: v.noun, tool: v.tool as string, param: flag.name }
+      : undefined;
+  })
+  .filter(
+    (v): v is { noun: string; tool: string; param: string } => v !== undefined,
+  );
+
+let fixture: FixtureGraph;
+let mcp: Awaited<ReturnType<typeof projectMcp>>;
+
+beforeAll(async () => {
+  fixture = await bootFixtureRuntime({
+    ttl: CANONICAL_TTL,
+    config: ALL_VISIBLE_CONFIG,
+  });
+  mcp = await projectMcp(capabilities, fixture.cwd);
+});
+
+afterAll(async () => {
+  await mcp.cleanup();
+  await fixture.dispose();
+});
+
+describe("lookup miss — total miss fails the call (B3, adapted)", () => {
+  it.each(
+    lookupVerbs.map((v) => v.noun),
+  )("%s_lookup: a single unknown name fails with ENTITY_NOT_FOUND", async (noun) => {
+    const result = await mcp.callTool(`${noun}_lookup`, {
+      name: ["zzz-definitely-not-a-real-entity"],
+    });
+    expect(result.ok).toBe(false);
+    expect((result.error as { code: string }).code).toBe("ENTITY_NOT_FOUND");
+  });
+
+  it.each(
+    lookupVerbs.map((v) => v.noun),
+  )("%s_lookup: an all-unknown batch ALSO fails (not a partial report)", async (noun) => {
+    const result = await mcp.callTool(`${noun}_lookup`, {
+      name: ["zzz-nope-one", "zzz-nope-two"],
+    });
+    expect(result.ok).toBe(false);
+    expect((result.error as { code: string }).code).toBe("ENTITY_NOT_FOUND");
+  });
+});
+
+describe("list — a narrowing filter to zero rows is a plain empty list (B3, adapted)", () => {
+  it("has at least one filtered list verb to sweep", () => {
+    // A guard, not a no-op: if this ever goes empty the sweep below silently
+    // covers nothing, which would be a silent coverage loss worth noticing.
+    expect(filteredListVerbs.length).toBeGreaterThan(0);
+  });
+
+  it.each(
+    filteredListVerbs,
+  )("$tool: an unmatched filter value narrows to [] (no EMPTY_RESULTS)", async ({
+    tool,
+    param,
+  }) => {
+    const result = await mcp.callTool(tool, {
+      [param]: "zzz-definitely-not-a-real-value",
+    });
+    expect(result.ok).toBe(true);
+    expect(result.data).toEqual([]);
+    expect(result.meta).toEqual({});
+  });
+});
+
+describe("ontology_show — an unknown prefix is INVALID_INPUT (B3)", () => {
+  it("fails with the enumerated valid prefixes", async () => {
+    const result = await mcp.callTool("ontology_show", { prefix: "nope" });
+    expect(result.ok).toBe(false);
+    const error = result.error as { code: string; validOptions: string[] };
+    expect(error.code).toBe("INVALID_INPUT");
+    expect(error.validOptions).toContain("ds");
+  });
+});

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

@@ -0,0 +1,123 @@
+/**
+ * A8 — the error/recovery MATRIX (shape), storeless half.
+ *
+ * `renderError{Plain,Llm,Json}` (`kernel/error/renderError.ts`) had NO dedicated
+ * test before this file (confirmed — only the `PragmaError` factories and the
+ * `recovery.cli` D5 invariant are unit-tested; the render layer's SECTION
+ * handling — "Did you mean?" / "Active filters:" / "Valid options:" /
+ * "Run `…`" / "Recovery: `…`" — was untested). This sweeps a representative
+ * MATRIX of error shapes (suggestions, filters, validOptions, a CLI recovery,
+ * an MCP-only recovery) across plain/llm/json, then grounds it with one REAL
+ * spawn (`skill lookup <unknown>`) so the matrix isn't purely synthetic.
+ *
+ * The `error.filters` shape has no LIVE trigger among PR3's read nouns yet (see
+ * PARITY_GAPS `no-empty-hook-on-free-filter`) — swept here with a directly
+ * constructed error so the render layer's handling of it is proven regardless.
+ */
+
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { PragmaError } from "../../kernel/error/PragmaError.js";
+import {
+  renderErrorJson,
+  renderErrorLlm,
+  renderErrorPlain,
+} from "../../kernel/error/renderError.js";
+import { freshXdgEnv, runCli } from "../helpers/runCli.js";
+
+const MATRIX: readonly {
+  readonly label: string;
+  readonly error: PragmaError;
+}[] = [
+  {
+    label: "suggestions",
+    error: PragmaError.notFound("block", "Buton", {
+      suggestions: ["Button"],
+    }),
+  },
+  {
+    label: "filters",
+    error: PragmaError.emptyResults("standard", {
+      filters: { category: "nonexistent" },
+    }),
+  },
+  {
+    label: "validOptions",
+    error: PragmaError.invalidInput("format", "yaml", {
+      validOptions: ["plain", "json"],
+    }),
+  },
+  {
+    label: "recovery.cli",
+    error: PragmaError.notFound("skill", "docs", {
+      recovery: {
+        message: "List discovered skills.",
+        cli: "pragma skill list",
+      },
+    }),
+  },
+  {
+    label: "recovery (mcp-only, no cli)",
+    error: PragmaError.storeUnavailable("no lock", {
+      recovery: { message: "Please report this issue." },
+    }),
+  },
+];
+
+describe("error/recovery matrix — render shapes (A8, storeless)", () => {
+  it.each(MATRIX)("plain renders the $label section", ({ error }) => {
+    const text = renderErrorPlain(error);
+    expect(text).toContain(`Error: ${error.message}`);
+    if (error.suggestions.length > 0) expect(text).toContain("Did you mean?");
+    if (error.filters) expect(text).toContain("Active filters:");
+    if (error.validOptions) expect(text).toContain("Valid options:");
+    if (error.recovery) {
+      // The human guidance is ALWAYS shown — even when a runnable `cli` is
+      // present (it used to be dropped, losing the WHY).
+      expect(text).toContain(error.recovery.message);
+      if (error.recovery.cli)
+        expect(text).toContain(`Run \`${error.recovery.cli}\``);
+    }
+  });
+
+  it.each(MATRIX)("llm renders the $label section", ({ error }) => {
+    const text = renderErrorLlm(error);
+    expect(text).toContain(`## Error: ${error.code}`);
+    if (error.suggestions.length > 0) expect(text).toContain("Suggestions:");
+    if (error.filters) expect(text).toContain("Filters:");
+    if (error.validOptions) expect(text).toContain("Valid options:");
+    if (error.recovery) {
+      expect(text).toContain(`Recovery: ${error.recovery.message}`);
+      if (error.recovery.cli)
+        expect(text).toContain(`\`${error.recovery.cli}\``);
+    }
+  });
+
+  it.each(MATRIX)("json renders the failure envelope for $label", ({
+    error,
+  }) => {
+    const envelope = JSON.parse(renderErrorJson(error)) as {
+      ok: boolean;
+      error: { code: string };
+    };
+    expect(envelope.ok).toBe(false);
+    expect(envelope.error.code).toBe(error.code);
+  });
+});
+
+describe("error/recovery matrix — grounded in a real spawn (A8, e2e)", () => {
+  it("skill lookup <unknown> renders suggestions + recovery on stderr", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-errmatrix-skill-"));
+    const result = runCli(["skill", "lookup", "docz"], {
+      cwd,
+      // Force plain (not the piped-stdout auto-llm default) — this test grounds
+      // the PLAIN render shape; llm/json are already covered above.
+      env: { ...freshXdgEnv(), XDG_DATA_HOME: cwd, PRAGMA_NO_AUTO_LLM: "1" },
+    });
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain("Error:");
+    expect(result.stderr).toContain("Run `pragma skill list`");
+  });
+});

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

@@ -0,0 +1,53 @@
+/**
+ * A4 — the 4-code exit covenant, observed through the REAL binary.
+ *
+ * `mapExitCode`'s table is PR1-protected (`kernel/project/cli/exitCodes.test.ts`,
+ * unit level). This is the spawn-observed pin: one representative real command
+ * per code, through the actual process exit path (`bin.ts`'s catch ladder →
+ * `dispatch`/`handleProgramError` → `process.exitCode`).
+ *
+ * DIVERGENCE NOTE (kept from the plan, verified against `exitCodes.ts`): v2
+ * COLLAPSED the old shell's 6-code exit map (NOT_FOUND=1, EMPTY=2,
+ * INVALID/AMBIGUOUS=3, CONFIG=4, STORE=5, INTERNAL=127) into 4 codes — success,
+ * a generic runtime failure (1), a usage failure (2), and an unavailable store
+ * (3). This test pins v2's table, not the old one.
+ */
+
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { runCli } from "../helpers/runCli.js";
+
+describe("exit-code covenant, spawn-observed (A4, e2e)", () => {
+  it("0 — success", () => {
+    expect(runCli(["info"]).exitCode).toBe(0);
+  });
+
+  it("1 — runtime failure (entity not found)", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-exit1-"));
+    const result = runCli(["skill", "lookup", "does-not-exist"], { cwd });
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain("not found");
+  });
+
+  it("2 — usage failure (invalid input)", () => {
+    const result = runCli(["--format", "yaml", "info"]);
+    expect(result.exitCode).toBe(2);
+    expect(result.stderr).toContain('Invalid format "yaml"');
+  });
+
+  it("3 — store unavailable (configured packages, 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.
+    writeFileSync(
+      join(cwd, "pragma.config.ts"),
+      'export default { packages: [{ name: "never-built", source: "file:///nonexistent" }] };\n',
+    );
+    const result = runCli(["block", "list"], { cwd });
+    expect(result.exitCode).toBe(3);
+    expect(result.stderr).toContain("sources update");
+  });
+});

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

@@ -0,0 +1,40 @@
+/**
+ * A1 — first-run onboarding, observed through the real compiled binary.
+ *
+ * Unit mechanics (`ensureFirstRun`/`firstRunTask`) are PR1-protected
+ * (`kernel/config/firstRun.test.ts`); this is the e2e pin: a fresh XDG config
+ * home produces the greeting on STDERR (never stdout — command output must stay
+ * uncorrupted), seeds `config.json`, and a second run is silent.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { freshXdgEnv, runCli } from "../helpers/runCli.js";
+
+describe("first-run onboarding (A1, e2e)", () => {
+  it("greets on stderr, seeds config.json, and stays silent on the second run", () => {
+    const env = freshXdgEnv();
+    const configPath = join(env.XDG_CONFIG_HOME, "pragma", "config.json");
+
+    const first = runCli(["info"], {
+      env: { ...env, PRAGMA_NO_AUTO_LLM: "1" },
+    });
+    expect(first.exitCode).toBe(0);
+    expect(first.stderr).toContain("Hello!");
+    expect(first.stderr).toContain("pre-release");
+    expect(first.stderr).toContain(configPath);
+    // Command output stays on stdout, untouched by the greeting.
+    expect(first.stdout).not.toContain("Hello!");
+    expect(first.stdout).toContain("pragma v");
+
+    expect(existsSync(configPath)).toBe(true);
+    expect(readFileSync(configPath, "utf-8")).toBe("{}\n");
+
+    const second = runCli(["info"], {
+      env: { ...env, PRAGMA_NO_AUTO_LLM: "1" },
+    });
+    expect(second.exitCode).toBe(0);
+    expect(second.stderr).toBe("");
+  });
+});

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

@@ -0,0 +1,136 @@
+/**
+ * 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
+ * (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
+ * and capture the real bin; (4) the golden `plain()` normalizer does its job.
+ */
+
+import { homedir, tmpdir } from "node:os";
+import { describe, expect, it } from "vitest";
+import { blockModule } from "../../capabilities/block/index.js";
+import { VERSION } from "../../constants.js";
+import { compilePack } from "../../kernel/packs/compile.js";
+import { verbKey } from "../../kernel/packs/uniqueness.js";
+import type { CapabilityModule } from "../../kernel/spec/types.js";
+import {
+  CANONICAL_CONFIG,
+  CANONICAL_TTL,
+} from "../fixtures/graph/canonical.js";
+import {
+  RECIPE_PREFIXES,
+  RECIPE_TTL,
+  recipePack,
+} from "../fixtures/packs/recipe.js";
+import { bootFixtureRuntime } from "../helpers/fixtureGraph.js";
+import { plain } from "../helpers/golden.js";
+import { assertCliMcpParity } from "../helpers/parity.js";
+import { runCli } from "../helpers/runCli.js";
+
+describe("bootFixtureRuntime — the shared canonical graph (commit-1 smoke)", () => {
+  it("boots a lock-backed store both CLI and MCP resolve identically", async () => {
+    const fixture = await bootFixtureRuntime({
+      ttl: CANONICAL_TTL,
+      config: CANONICAL_CONFIG,
+    });
+    try {
+      const lookupVerb = blockModule.verbs.find(
+        (v) => verbKey(v.path) === "block lookup",
+      );
+      expect(lookupVerb).toBeDefined();
+      if (!lookupVerb) return;
+
+      const envelope = await assertCliMcpParity({
+        modules: [blockModule],
+        verb: lookupVerb,
+        tool: "block_lookup",
+        cwd: fixture.cwd,
+        params: { name: ["Button"] },
+      });
+      const data = envelope.data as {
+        results: { name: string; uri: string }[];
+      };
+      expect(data.results[0]?.name).toBe("Button");
+      expect(data.results[0]?.uri).toBe("https://ds.canonical.com/button");
+    } finally {
+      await fixture.dispose();
+    }
+  });
+});
+
+describe("foreign-namespace generic-pack proof (compiler is DS-agnostic)", () => {
+  it("a pack over `ex:` recipes registers 2 tools and resolves on both surfaces", async () => {
+    const fixture = await bootFixtureRuntime({ ttl: RECIPE_TTL });
+    try {
+      const recipeModule: CapabilityModule = {
+        name: "recipe",
+        verbs: compilePack(recipePack, "test:recipe", RECIPE_PREFIXES),
+      };
+      expect(recipeModule.verbs.map((v) => verbKey(v.path)).sort()).toEqual([
+        "recipe list",
+        "recipe lookup",
+      ]);
+
+      const listVerb = recipeModule.verbs.find(
+        (v) => verbKey(v.path) === "recipe list",
+      );
+      expect(listVerb).toBeDefined();
+      if (!listVerb) return;
+
+      const listEnvelope = await assertCliMcpParity({
+        modules: [recipeModule],
+        verb: listVerb,
+        tool: "recipe_list",
+        cwd: fixture.cwd,
+      });
+      const rows = listEnvelope.data as { name: string; cuisine: string }[];
+      expect(rows.map((r) => r.name).sort()).toEqual(["Gazpacho", "Pancakes"]);
+
+      const lookupVerb = recipeModule.verbs.find(
+        (v) => verbKey(v.path) === "recipe lookup",
+      );
+      expect(lookupVerb).toBeDefined();
+      if (!lookupVerb) return;
+
+      const lookupEnvelope = await assertCliMcpParity({
+        modules: [recipeModule],
+        verb: lookupVerb,
+        tool: "recipe_lookup",
+        cwd: fixture.cwd,
+        params: { name: ["Pancakes"] },
+      });
+      const data = lookupEnvelope.data as {
+        results: { instructions: string }[];
+      };
+      expect(data.results[0]?.instructions).toContain("griddle");
+    } finally {
+      await fixture.dispose();
+    }
+  });
+});
+
+describe("runCli — spawn-capture smoke", () => {
+  it("captures --version from the source entry point", () => {
+    const result = runCli(["--version"], { mode: "source" });
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout.trim()).toBe(VERSION);
+    expect(result.stderr).toBe("");
+  });
+});
+
+describe("golden plain() normalizer", () => {
+  it("strips ANSI escapes and tokenizes machine-specific paths", () => {
+    const colored = "\x1b[1mHello\x1b[0m world";
+    expect(plain(colored)).toBe("Hello world");
+
+    const withTmp = `wrote to ${tmpdir()}/foo.json`;
+    expect(plain(withTmp)).toBe("wrote to <tmp>/foo.json");
+
+    const withHome = `config at ${homedir()}/.config/pragma`;
+    expect(plain(withHome)).toBe("config at <home>/.config/pragma");
+  });
+});

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

@@ -0,0 +1,129 @@
+/**
+ * B9 — the tier-chain / channel CLI journey (PR3 Risk5's ONE hand-written
+ * verb, `block list`).
+ *
+ * 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
+ * this drives `block list` through the REAL CLI dispatch path (`executeVerb`,
+ * the same function the compiled binary's `dispatch()` calls) IN-PROCESS
+ * against the fixture, rather than spawning. It still exercises the true CLI
+ * seam (typed params -> dispatch -> render), just without forking a process.
+ *
+ * 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.
+ */
+
+import { afterAll, describe, expect, it } from "vitest";
+import { blockModule } from "../../capabilities/block/index.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 {
+  CANONICAL_CONFIG,
+  CANONICAL_TTL,
+} from "../fixtures/graph/canonical.js";
+import {
+  bootFixtureRuntime,
+  type FixtureGraph,
+} from "../helpers/fixtureGraph.js";
+import { JSON_FLAGS, NO_MUTATION } from "../helpers/parity.js";
+
+const listVerb = blockModule.verbs.find(
+  (v) => verbKey(v.path) === "block list",
+) as VerbSpec;
+
+async function blockListNames(
+  fixture: FixtureGraph,
+  allTiers = false,
+): Promise<string[]> {
+  const out = await executeVerb(
+    listVerb,
+    { allTiers },
+    NO_MUTATION,
+    bootRuntime(JSON_FLAGS, fixture.cwd),
+  );
+  const rows = JSON.parse(out.stdout as string).data as { name: string }[];
+  return rows.map((r) => r.name).sort();
+}
+
+const fixtures: FixtureGraph[] = [];
+afterAll(async () => {
+  await Promise.all(fixtures.map((f) => f.dispose()));
+});
+
+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("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("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",
+    ]);
+  });
+
+  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",
+    ]);
+  });
+});
+
+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",
+    ]);
+  });
+});

package/src/testing/behavioral/liveReadSurface.ts

@@ -0,0 +1,80 @@
+/**
+ * The live read-noun surface, parameterized (R2 discipline).
+ *
+ * Every B-tier test in this directory drives its assertions over THIS —
+ * never a noun list copied from the plan. It cross-references
+ * `emitSurface(capabilities)` (the authoritative "what's live, what's hidden,
+ * what's MCP-exposed" projection) against the raw `capabilities` array (for
+ * the runnable `VerbSpec`), so the derived lists below automatically grow as
+ * PR5/6/7 add nouns — nothing here names a specific noun.
+ */
+
+import { capabilities } from "../../capabilities/index.js";
+import { verbKey } from "../../kernel/packs/uniqueness.js";
+import { emitSurface } from "../../kernel/spec/emitSurface.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+
+/** One live, non-hidden verb: its emitted facts plus the runnable spec. */
+export interface LiveVerb {
+  readonly noun: string;
+  /** The verb label (`emitSurface`'s `v` — the noun itself for a self-verb). */
+  readonly verb: string;
+  /** The MCP tool name, or `false` when withheld from MCP. */
+  readonly tool: string | false;
+  readonly needsStore: boolean;
+  readonly mutates: boolean;
+  readonly spec: VerbSpec;
+}
+
+function buildLiveVerbs(): readonly LiveVerb[] {
+  const specByKey = new Map<string, VerbSpec>();
+  for (const module of capabilities) {
+    for (const verb of module.verbs) {
+      if (verb.hidden) continue;
+      specByKey.set(verbKey(verb.path), verb);
+    }
+  }
+
+  const emitted = emitSurface(capabilities);
+  const live: LiveVerb[] = [];
+  for (const [noun, { verbs }] of Object.entries(emitted.nouns)) {
+    for (const entry of verbs) {
+      const key = entry.v === noun ? noun : `${noun} ${entry.v}`;
+      const spec = specByKey.get(key);
+      if (!spec) continue; // Should not happen — emission mirrors the registry.
+      live.push({
+        noun,
+        verb: entry.v,
+        tool: entry.mcp ?? false,
+        needsStore: entry.needsStore === true,
+        mutates: entry.mutates === true,
+        spec,
+      });
+    }
+  }
+  return live;
+}
+
+/** Every live, non-hidden verb across the whole capability catalog. */
+export const liveVerbs: readonly LiveVerb[] = buildLiveVerbs();
+
+/**
+ * Read nouns' `lookup` verbs, MCP-exposed, store-backed — restricted to the
+ * PACK-lookup contract (a variadic `<name...>` positional), which the B-tier
+ * list→lookup→batch suites drive uniformly. Bespoke single-name lookups
+ * (`tier_lookup`, `prompt_lookup`) have their own tests, so they are excluded
+ * here structurally (by param shape, not by naming the noun — R2).
+ */
+export const lookupVerbs: readonly LiveVerb[] = liveVerbs.filter(
+  (v) =>
+    v.verb === "lookup" &&
+    v.tool !== false &&
+    v.needsStore &&
+    !v.mutates &&
+    v.spec.params.some((p) => p.positional && p.kind === "string[]"),
+);
+
+/** Read nouns' `list` verbs, MCP-exposed, store-backed. */
+export const listVerbs: readonly LiveVerb[] = liveVerbs.filter(
+  (v) => v.verb === "list" && v.tool !== false && v.needsStore && !v.mutates,
+);