@canonical/pragma-cli 0.32.0 → 0.34.0

package/src/testing/behavioral/journeys.interactiveTty.e2e.test.ts

@@ -0,0 +1,66 @@
+/**
+ * E4 (AV-231, Backlog E) — the interactive TTY journey. SCAFFOLD.
+ *
+ * No test in the suite ever drove a REAL terminal, so the interactive-cancel and
+ * no-freeze guarantees (H1–H3, C3/C4) were never exercised end to end. Confirming
+ * them needs a pseudo-terminal: spawn the compiled `pragma` under a PTY, send raw
+ * keystrokes (Ctrl-C = `\x03`, EOF = `\x04`), and observe the exit code + output.
+ *
+ * `node-pty` is NOT available in this environment (it is a native addon, absent
+ * from the dependency set — verified at authoring time), so the journey is
+ * scaffolded as `it.todo` behind a `node-pty` availability gate rather than
+ * blocking the P0 work. Each todo names the exact behaviour and the exit contract
+ * the CLI already promises (see `kernel/project/cli/dispatch.ts`):
+ *
+ *  - H1: an at-prompt Ctrl-C is a DECLINE — a clean cancel, "Cancelled." on
+ *    stderr, exit 0 (`EXIT.OK`).
+ *  - H2: a Ctrl-C DURING execution is an INTERRUPT — aborts work underway,
+ *    "Cancelled." on stderr, exit 130 (`EXIT.INTERRUPTED`, 128 + SIGINT).
+ *  - H3: `create 2>/dev/null` must not freeze — interactivity gates on stderr
+ *    being a TTY, so a redirected stderr picks the non-interactive strategy
+ *    instead of mounting an invisible wizard that blocks on stdin.
+ *  - C3: EOF (`\x04`) on a prompt resolves to a usage error, never a hang.
+ *  - C4: an empty select (Enter on a no-default list) does not hang.
+ *
+ * TODO(AV-231/E4): when `node-pty` (or an equivalent PTY shim) is on the
+ * devDependency set, replace each `it.todo` with a PTY-driven `it` that spawns
+ * `dist/pragma create …` under a pty, writes the keystroke, and asserts the exit
+ * code + "Cancelled." line. The compiled binary is already provisioned for the
+ * spawn-e2e layer by `testing/perf/globalSetup.ts`.
+ */
+
+import { describe, it } from "vitest";
+
+/** True when a real PTY driver is importable (kept async-free: a resolve probe). */
+async function ptyAvailable(): Promise<boolean> {
+  try {
+    await import("node-pty" as string);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Authoring-time: `node-pty` is absent, so this resolves to `describe.skip` and
+// the todos below stand in as the recorded, unblocked plan. The probe is awaited
+// lazily so a future environment with node-pty flips the gate with no edit here.
+const hasPty = await ptyAvailable();
+const ptyGate = hasPty ? describe : describe.skip;
+
+ptyGate(
+  "interactive TTY journey — cancel + no-freeze (E4, node-pty) [SCAFFOLD]",
+  () => {
+    // These become PTY-driven `it`s once node-pty is available (see module TODO).
+    it.todo(
+      "H1: Ctrl-C at a wizard prompt cancels cleanly (stderr 'Cancelled.', exit 0)",
+    );
+    it.todo(
+      "H2: Ctrl-C during execution aborts the run (stderr 'Cancelled.', exit 130)",
+    );
+    it.todo(
+      "H3: `create 2>/dev/null` does not freeze (non-TTY stderr -> non-interactive)",
+    );
+    it.todo("C3: EOF on a prompt resolves to a usage error, never a hang");
+    it.todo("C4: an empty select does not hang");
+  },
+);

package/src/testing/behavioral/journeys.livePack.e2e.test.ts

@@ -0,0 +1,129 @@
+/**
+ * E3 (AV-231, Backlog E) — the network-gated, NON-BLOCKING live-pack job.
+ *
+ * A handful of behaviours can only be confirmed against a REAL oxigraph store
+ * built from the REAL default pack: result ordering (A3/A9), which language a
+ * multilingual label resolves to under real store order (A7), ke truncation of
+ * long literals, and `buildIndex`'s `Promise.all` re-entrancy when the same pack
+ * is built concurrently. Those depend on the network (fetching the shipped pack)
+ * and on real build cost, so this suite is GATED OFF by default — it never runs
+ * (or flakes) in the ordinary `bun test` pass. Set `PRAGMA_LIVE_PACK=1` to run
+ * it (a dedicated, non-required CI job).
+ *
+ * The assertions here run against the VENDORED default pack as a faithful local
+ * proxy for the shipped one, so a maintainer who flips the gate gets real signal
+ * today. Each carries a TODO for wiring the ACTUAL network pack fetch — the one
+ * piece this environment cannot provide.
+ *
+ * TODO(AV-231/E3): resolve the real shipped default pack (git/npm source) here
+ * instead of the vendored TTL, so ordering/truncation are asserted against the
+ * bytes agents actually receive.
+ */
+
+import { describe, expect, it } from "vitest";
+import { buildPack } from "../../kernel/runtime/graphpack/build.js";
+import {
+  DEFAULT_PACK_PREFIXES,
+  DEFAULT_PACK_TTL,
+} from "../fixtures/graph/defaultPack.js";
+import {
+  bootFixtureRuntime,
+  type FixtureGraph,
+} from "../helpers/fixtureGraph.js";
+
+/** Non-blocking gate: skipped unless a maintainer opts in (or CI's live job). */
+const liveGate = process.env.PRAGMA_LIVE_PACK ? describe : describe.skip;
+
+liveGate(
+  "live-pack journey — real oxigraph ordering + build re-entrancy (E3)",
+  () => {
+    it("a SELECT ... ORDER BY returns a STABLE, deterministic ordering (A3/A9)", async () => {
+      const fixture = await bootFixtureRuntime({ ttl: DEFAULT_PACK_TTL });
+      try {
+        const query =
+          "SELECT ?name WHERE { ?c a ds:Component ; ds:name ?name } ORDER BY ?name";
+        const first = await fixture.runtime.query.sparql(query);
+        const second = await fixture.runtime.query.sparql(query);
+        const names = (result: typeof first): string[] =>
+          result.type === "select"
+            ? result.bindings.map((binding) => String(binding.name))
+            : [];
+        // Repeated evaluation is identical, and ORDER BY is honoured.
+        expect(names(first)).toEqual(names(second));
+        expect(names(first)).toEqual(["Beta Badge", "Button", "Orphan Widget"]);
+      } finally {
+        await fixture.dispose();
+      }
+    });
+
+    it("a multilingual label resolves to a SINGLE, tag-stripped value under real store order (A7)", async () => {
+      // TODO(AV-231/E3): against the live pack, pin the EXACT language the store
+      // yields first, so the index-label choice is a confirmed contract rather than
+      // the store-order accident it is today (see the A7 note in the E1 journey).
+      const fixture = await bootFixtureRuntime({ ttl: DEFAULT_PACK_TTL });
+      try {
+        const result = await fixture.runtime.query.sparql(
+          "SELECT ?l WHERE { ds:button rdfs:label ?l } ORDER BY ?l",
+        );
+        const labels =
+          result.type === "select"
+            ? result.bindings.map((binding) => String(binding.l))
+            : [];
+        expect(labels).toEqual(["Bouton", "Button"]);
+      } finally {
+        await fixture.dispose();
+      }
+    });
+
+    it("building the same sources CONCURRENTLY is re-entrant — one hash, no torn pack (buildIndex Promise.all)", async () => {
+      // buildIndex fans out four bulk SPARQL queries under Promise.all, and buildPack
+      // publishes atomically; N concurrent builds of identical sources must converge
+      // on ONE content hash with every pack complete (no half-written cache).
+      const inputs = [
+        { path: "concurrent/pack.ttl", content: DEFAULT_PACK_TTL },
+      ];
+      const options = {
+        name: "pragma",
+        version: "0.0.0-e3",
+        sourceRef: "e3-reentrancy",
+        prefixes: DEFAULT_PACK_PREFIXES,
+      };
+      const results = await Promise.all(
+        Array.from({ length: 5 }, () => buildPack(inputs, options)),
+      );
+      const hashes = new Set(results.map((result) => result.contentHash));
+      expect(hashes.size).toBe(1);
+      for (const result of results) {
+        expect(result.contentHash).toMatch(/^[0-9a-f]{64}$/);
+      }
+    });
+
+    it("a long literal survives the build round-trip without silent ke truncation", async () => {
+      // TODO(AV-231/E3): confirm against the live pack, whose real summaries/guidelines
+      // are long enough to trip any downstream ke truncation (A7/A9 tail).
+      const longText = "x".repeat(20_000);
+      const ttl = `@prefix ds: <https://ds.canonical.com/> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+ds:Component a owl:Class .
+ds:summary a owl:DatatypeProperty ; rdfs:range xsd:string .
+ds:big a ds:Component ; ds:summary "${longText}" .`;
+      let fixture: FixtureGraph | undefined;
+      try {
+        fixture = await bootFixtureRuntime({ ttl });
+        const result = await fixture.runtime.query.sparql(
+          "SELECT ?s WHERE { ds:big ds:summary ?s }",
+        );
+        const value =
+          result.type === "select"
+            ? String(
+                (result.bindings.at(0) as { s?: string } | undefined)?.s ?? "",
+              )
+            : "";
+        expect(value.length).toBe(longText.length);
+      } finally {
+        await fixture?.dispose();
+      }
+    });
+  },
+);

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

@@ -0,0 +1,179 @@
+/**
+ * E2 (AV-231, Backlog E) — the MCP lifecycle journey over a LONG-LIVED,
+ * in-process server.
+ *
+ * Fresh-runtime unit tests structurally cannot catch the MCP memoization bugs:
+ * they build a new runtime per assertion, so a store/config memo that outlives a
+ * mutation is never exercised. The real MCP server boots ONE runtime for its
+ * whole lifetime and shares it across every tool call — the exact condition
+ * under which a cold-store rejection could be memoized forever, or a stale config
+ * layer could survive a `config_set`. This file drives that server the way an
+ * agent does, over a single connection:
+ *
+ *  - COLD read → STORE_UNAVAILABLE → `sources_update` (confirm) → the SAME
+ *    server's retry read SUCCEEDS. Guards C1: a rejected boot must NOT be
+ *    memoized, and a real mutation must invalidate the shared store so the next
+ *    read re-boots against the freshly built pack.
+ *  - `config_set` → a subsequent `config_show` on the same server sees the new
+ *    value. Guards C2: the mutation must drop the config memo the store boot
+ *    depends on.
+ *  - The discovery sequence resolves from a COLD store (the storeless
+ *    `capabilities` catalog boots with no pack), then browse → inspect works once
+ *    the store is warm.
+ *
+ * Uses the in-process `projectMcp` harness (SDK in-memory transport) — no stdio,
+ * no network — over the vendored default pack.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { capabilities } from "../../capabilities/index.js";
+import { readActivePack } from "../../kernel/runtime/paths.js";
+import { DEFAULT_PACK_TTL } from "../fixtures/graph/defaultPack.js";
+import { type McpHarness, projectMcp } from "../helpers/projectMcp.js";
+
+/** The transient roots one test creates; removed in `afterEach`. */
+let roots: string[] = [];
+const tempDir = (prefix: string): string => {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  roots.push(dir);
+  return dir;
+};
+
+/**
+ * A COLD project directory: a `pragma.config.ts` pointing at a real file
+ * package, but nothing built yet — so the store boots cold until `sources_update`.
+ */
+function coldProject(ttl: string): string {
+  const pkg = tempDir("e2-pkg-");
+  mkdirSync(join(pkg, "definitions"), { recursive: true });
+  writeFileSync(join(pkg, "definitions", "pack.ttl"), ttl);
+  const cwd = tempDir("e2-proj-");
+  writeFileSync(
+    join(cwd, "pragma.config.ts"),
+    `export default { packs: [{ name: "default", source: "file://${pkg}" }] };\n`,
+  );
+  return cwd;
+}
+
+let mcp: McpHarness | undefined;
+beforeEach(() => {
+  roots = [];
+});
+afterEach(async () => {
+  await mcp?.cleanup();
+  mcp = undefined;
+  for (const dir of roots) rmSync(dir, { recursive: true, force: true });
+});
+
+describe("MCP lifecycle — cold store recovers after sources_update (E2, C1)", () => {
+  it("a cold read fails STORE_UNAVAILABLE with the sources_update recovery, then the retry succeeds", async () => {
+    const cwd = coldProject(DEFAULT_PACK_TTL);
+    mcp = await projectMcp(capabilities, cwd);
+
+    // 1) COLD: the store has no pack — a store-backed read must fail cleanly,
+    //    pointing the agent at the recovery TOOL (not just a CLI string).
+    const cold = await mcp.callTool("block_list");
+    expect(cold.ok).toBe(false);
+    const error = cold.error as {
+      code: string;
+      recovery?: { mcp?: { tool?: string } };
+    };
+    expect(error.code).toBe("STORE_UNAVAILABLE");
+    expect(error.recovery?.mcp?.tool).toBe("sources_update");
+    expect(readActivePack(cwd)).toBeUndefined();
+
+    // 2) The agent runs the recovery tool for real (confirm) — it builds the pack.
+    const update = await mcp.callTool("sources_update", { confirm: true });
+    expect(update.ok).toBe(true);
+    // A real execution, not a plan-only preview.
+    expect(update.meta).not.toMatchObject({ planOnly: true });
+    expect((update.data as { contentHash: string }).contentHash).toMatch(
+      /^[0-9a-f]{64}$/,
+    );
+    expect(readActivePack(cwd)).toMatch(/^[0-9a-f]{64}$/);
+
+    // 3) RETRY on the SAME server: the shared store was invalidated by the
+    //    mutation, so the memoized cold rejection is gone and the read re-boots
+    //    against the new pack. This is the guarantee a fresh-runtime test cannot
+    //    make.
+    const warm = await mcp.callTool("block_list");
+    expect(warm.ok).toBe(true);
+    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.
+    expect(names).toEqual(["Beta Badge", "Button", "Card", "Orphan Widget"]);
+  });
+});
+
+describe("MCP lifecycle — config_set is visible to the next read (E2, C2)", () => {
+  it("config_set updates the layer a subsequent config_show reads on the same server", async () => {
+    const cwd = tempDir("e2-cfg-");
+    mcp = await projectMcp(capabilities, cwd);
+
+    // Before: the default channel, from the default (unset) origin.
+    const before = await mcp.callTool("config_show");
+    const beforeData = before.data as {
+      config: { channel: string };
+      origins: { channel: string };
+    };
+    expect(beforeData.config.channel).toBe("normal");
+    expect(beforeData.origins.channel).toBe("default");
+
+    // Mutate: set the channel for real (confirm).
+    const set = await mcp.callTool("config_set", {
+      key: "channel",
+      value: "experimental",
+      confirm: true,
+    });
+    expect(set.ok).toBe(true);
+
+    // After: the SAME long-lived server's read reflects the write — proving the
+    // mutation dropped the config memo the boot depends on (not a stale layer).
+    const after = await mcp.callTool("config_show");
+    const afterData = after.data as {
+      config: { channel: string };
+      origins: { channel: string };
+    };
+    expect(afterData.config.channel).toBe("experimental");
+    // The write landed in the global layer, so the origin flips accordingly.
+    expect(afterData.origins.channel).toBe("global");
+  });
+});
+
+describe("MCP lifecycle — discovery from a cold store (E2)", () => {
+  it("the capabilities catalog resolves cold, then browse -> inspect works once warm", async () => {
+    const cwd = coldProject(DEFAULT_PACK_TTL);
+    mcp = await projectMcp(capabilities, cwd);
+
+    // Discovery is storeless: the capabilities catalog answers even with a cold
+    // store, so an agent can orient before the pack exists.
+    const catalog = await mcp.callTool("capabilities");
+    expect(catalog.ok).toBe(true);
+    const catalogData = catalog.data as {
+      discovery_sequence: unknown;
+      tools: unknown;
+    };
+    expect(catalogData.discovery_sequence).toBeDefined();
+    expect(catalogData.tools).toBeDefined();
+
+    // Warm the store, then follow a browse -> inspect discovery step end to end.
+    await mcp.callTool("sources_update", { confirm: true });
+    const list = await mcp.callTool("block_list");
+    expect(list.ok).toBe(true);
+    const first = (list.data as { name: string }[]).at(0);
+    expect(first?.name).toBeDefined();
+
+    const lookup = await mcp.callTool("block_lookup", {
+      name: [first?.name ?? ""],
+    });
+    expect(lookup.ok).toBe(true);
+    const results = (lookup.data as { results: { name: string }[] }).results;
+    expect(results.at(0)?.name).toBe(first?.name);
+  });
+});

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

@@ -0,0 +1,188 @@
+/**
+ * The package tier, end to end: a noun the binary never shipped.
+ *
+ * A package that ships `stories/*.json` and is declared as a `file:` pack
+ * contributes a working command to a project that declares it — resolved by
+ * `sources update`, hashed into the pack, written into the pack directory, read
+ * back storelessly at dispatch, and answered from the fixture graph. Proven both
+ * in-process and through the COMPILED binary in a real subprocess.
+ *
+ * The same package also ships a malformed story and a schema-invalid one. Those
+ * must be DROPPED, not fatal: package stories reach dispatch before the command
+ * tree exists, so a throw there fails every command — including `sources update`
+ * and `doctor`, the only two that can recover from it. Both of those are run
+ * here after the bad stories are in the pack.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { runTask } from "@canonical/task/node";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+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 { packDir, readActivePack } from "../../kernel/runtime/paths.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import {
+  bootFixtureRuntime,
+  type FixtureGraph,
+} from "../helpers/fixtureGraph.js";
+import { runCli } from "../helpers/runCli.js";
+
+const TTL = `
+@prefix ex: <https://example.org/kitchen#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+ex:Recipe a owl:Class .
+ex:name a owl:DatatypeProperty ; rdfs:domain ex:Recipe ; rdfs:range xsd:string .
+
+ex:soup a ex:Recipe ; ex:name "Soup" .
+ex:stew a ex:Recipe ; ex:name "Stew" .
+`;
+
+/** A valid read story — the noun the binary never shipped. */
+const RECIPE_STORY = JSON.stringify({
+  noun: "recipe",
+  description: "List recipes.",
+  colophon: "Recipes are modelled as ex:Recipe individuals.",
+  list: {
+    query:
+      "SELECT ?uri ?name WHERE { ?uri a ex:Recipe ; ex:name ?name } ORDER BY ?name",
+    columns: [{ field: "uri" }, { field: "name" }],
+  },
+});
+
+/** Schema-invalid: a well-formed JSON document the pack grammar rejects. */
+const INVALID_STORY = JSON.stringify({ noun: "Bad Noun", list: {} });
+
+let graph: FixtureGraph;
+beforeAll(async () => {
+  graph = await bootFixtureRuntime({
+    ttl: TTL,
+    stories: {
+      "recipe.json": RECIPE_STORY,
+      // Not JSON at all.
+      "broken.json": "{ this is not json",
+      "invalid.json": INVALID_STORY,
+    },
+  });
+}, 60_000);
+afterAll(async () => {
+  await graph.dispose();
+});
+
+describe("a package's stories reach the pack", () => {
+  it("sources update carries all three story files into the pack, verbatim", () => {
+    const hash = readActivePack(graph.cwd);
+    expect(hash).toBeDefined();
+    const carried = JSON.parse(
+      readFileSync(join(packDir(hash as string), "stories.json"), "utf-8"),
+    ) as { source: string; content: string }[];
+    expect(carried.map((record) => record.source)).toEqual([
+      "fixture/stories/broken.json",
+      "fixture/stories/invalid.json",
+      "fixture/stories/recipe.json",
+    ]);
+    expect(
+      carried.find((r) => r.source === "fixture/stories/recipe.json")?.content,
+    ).toBe(RECIPE_STORY);
+  });
+});
+
+describe("a package-declared noun answers reads (in-process)", () => {
+  it("recipe list returns rows from the package's own graph", async () => {
+    const { modules } = await loadEffectiveModules(capabilities, graph.cwd);
+    const recipe = modules.find((module) => module.name === "recipe");
+    expect(recipe?.story).toBe(true);
+    expect(recipe?.colophon).toBe(
+      "Recipes are modelled as ex:Recipe individuals.",
+    );
+    const list = recipe?.verbs.find(
+      (verb) => verb.path.join(" ") === "recipe list",
+    ) as VerbSpec;
+    const rows = (await list.run({}, graph.runtime)) as { name: string }[];
+    expect(rows.map((row) => row.name)).toEqual(["Soup", "Stew"]);
+  });
+
+  it("names the unusable stories without failing the load", async () => {
+    const { problems } = await loadEffectiveModules(capabilities, graph.cwd);
+    expect(problems.map((problem) => problem.source).sort()).toEqual([
+      "fixture/stories/broken.json",
+      "fixture/stories/invalid.json",
+    ]);
+    // Each says WHY, not just that something was wrong.
+    const invalid = problems.find((p) => p.source.endsWith("invalid.json"));
+    expect(invalid?.message).toMatch(/Invalid story/);
+  });
+});
+
+describe("the two recoveries still run with bad stories in the pack", () => {
+  it("sources update re-resolves and reports the carried story count", async () => {
+    const result = await runTask(await buildUpdateTask(graph.runtime));
+    expect(result.packs).toEqual([
+      {
+        name: "fixture",
+        resolved: expect.any(String),
+        sourceCount: 1,
+        storyCount: 3,
+      },
+    ]);
+  });
+
+  it("doctor passes `pack refs` and lists each ignored story as a failing item", async () => {
+    const data = await runChecks(graph.runtime);
+    const check = data.checks.find((entry) => entry.name === "pack refs");
+    // The pack DOES answer reads, so the check passes…
+    expect(check?.status).toBe("pass");
+    expect(check?.detail).toContain("2 stories ignored");
+    // …with the unusable stories named underneath it.
+    expect(check?.items?.map((item) => item.label).sort()).toEqual([
+      "fixture/stories/broken.json",
+      "fixture/stories/invalid.json",
+    ]);
+    for (const item of check?.items ?? []) expect(item.status).toBe("fail");
+  });
+});
+
+describe("the compiled binary answers the package's noun (subprocess)", () => {
+  it("pragma recipe list --format json returns the package's rows", () => {
+    const result = runCli(["recipe", "list", "--format", "json"], {
+      cwd: graph.cwd,
+    });
+    expect(result.exitCode).toBe(0);
+    const rows = (JSON.parse(result.stdout) as { data: { name: string }[] })
+      .data;
+    expect(rows.map((row) => row.name)).toEqual(["Soup", "Stew"]);
+    // The bad stories are named on stderr, never on stdout — `--format json`
+    // stays machine-readable.
+    expect(result.stderr).toContain("fixture/stories/broken.json");
+    expect(result.stderr).toContain("fixture/stories/invalid.json");
+  });
+
+  it("pragma capabilities lists the package's tools — the surface agents read", () => {
+    // The MCP server registers its tools from the effective modules, so a
+    // catalog built from the STATIC registry would omit exactly the nouns
+    // `tools/list` advertises. `config show` points agents here for the verbs a
+    // story produces; that pointer has to be true.
+    const result = runCli(["capabilities", "--format", "json"], {
+      cwd: graph.cwd,
+    });
+    expect(result.exitCode).toBe(0);
+    const { data } = JSON.parse(result.stdout) as {
+      data: { tools: { name: string }[] };
+    };
+    expect(data.tools.map((tool) => tool.name)).toContain("recipe_list");
+  });
+
+  it("pragma --help does NOT list recipe — the documented fast-path limit", () => {
+    // `--help` reads the STATIC capability set (no config, no pack read), which
+    // is what keeps its budget. A package-declared noun is dispatch-only.
+    const help = runCli(["--help"], { cwd: graph.cwd });
+    expect(help.exitCode).toBe(0);
+    expect(help.stdout).not.toContain("recipe");
+    // …and the command it does not advertise still runs (asserted above).
+  });
+});

package/src/testing/behavioral/liveReadSurface.ts

@@ -61,9 +61,10 @@ 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).
+ * list→lookup→batch suites drive uniformly. The one bespoke single-name lookup
+ * left (`prompt_lookup`) has its own tests, so it is excluded here structurally
+ * (by param shape, not by naming the noun — R2). `tier_lookup` joined the pack
+ * contract in L-OPEN-9, so it is swept here like every other declared lookup.
  */
 export const lookupVerbs: readonly LiveVerb[] = liveVerbs.filter(
   (v) =>

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

@@ -21,6 +21,8 @@
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { capabilities } from "../../capabilities/index.js";
 import { readPackIndex } from "../../kernel/completion/entitySource.js";
+import type { PackIndex } from "../../kernel/runtime/graphpack/types.js";
+import { resolveSources } from "../../kernel/runtime/resolveSources.js";
 import {
   ALL_VISIBLE_CONFIG,
   CANONICAL_TTL,
@@ -41,6 +43,8 @@ let mcp: Awaited<ReturnType<typeof projectMcp>>;
 let firstNameByNoun: Map<string, string>;
 /** The registered tool list, fetched once (annotations are call-invariant). */
 let registeredTools: Awaited<ReturnType<typeof mcp.listTools>>;
+/** The index of the pack the fixture's boot decision names. */
+let activeIndex: PackIndex | undefined;
 
 beforeAll(async () => {
   fixture = await bootFixtureRuntime({
@@ -49,6 +53,9 @@ beforeAll(async () => {
   });
   mcp = await projectMcp(capabilities, fixture.cwd);
   registeredTools = await mcp.listTools();
+  activeIndex = readPackIndex(
+    resolveSources(await fixture.runtime.loadConfig(), fixture.cwd),
+  );
 
   firstNameByNoun = new Map();
   for (const v of listVerbs) {
@@ -81,18 +88,16 @@ function representativeValue(
   param: LiveVerb["spec"]["params"][number],
 ): unknown {
   if (param.name === "prefix") {
-    const prefix = Object.keys(readPackIndex(fixture.cwd)?.prefixes ?? {}).find(
+    const prefix = Object.keys(activeIndex?.prefixes ?? {}).find(
       (p) => p !== "owl" && p !== "rdfs" && p !== "rdf" && p !== "xsd",
     );
     return prefix ?? "ds";
   }
   if (param.name === "uri") {
-    const entity = readPackIndex(fixture.cwd)?.entities.find(
-      (e) => e.box === "abox",
-    );
+    const entity = activeIndex?.entities.find((e) => e.box === "abox");
     return entity?.prefixed ?? entity?.name ?? "";
   }
-  // An enum positional (e.g. `config channel <name>`, `config set <key>`) must
+  // An enum positional (e.g. `config set <key>`) must
   // get a real member — a placeholder would fail the tool's zod schema at the
   // SDK layer, before the handler, yielding a protocol error rather than a
   // well-formed envelope.