@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/kernel/runtime/types.ts

@@ -0,0 +1,210 @@
+/**
+ * Runtime context shapes threaded through the kernel.
+ *
+ * The grammar (`VerbSpec.run`) receives a {@link PragmaRuntime}; the CLI and
+ * MCP projectors build one per invocation. The interface grows one field-group
+ * per PR as each layer lands — global flags with the CLI projector, resolved
+ * config + provenance with the config layer — so a verb only ever sees fields
+ * that are actually populated by the time it runs.
+ */
+
+import type { DetailLevel, OutputFormat } from "../../constants.js";
+import type { ConfigLayers } from "../config/types.js";
+
+/**
+ * Global flags parsed once, before the command tree runs, and shared by every
+ * verb. The renderer reads these to pick a formatter; auto-LLM is recorded
+ * separately so inferred mode can shape output without switching behaviour.
+ */
+export interface GlobalFlags {
+  /** Condensed Markdown output, from `--format llm` or auto-detection. */
+  readonly llm: boolean;
+  /** True when `llm` was inferred from a non-interactive stdout, not requested. */
+  readonly autoLlm?: boolean;
+  /** Selected output format; `--format text` is normalised to `plain`. */
+  readonly format: OutputFormat;
+  /** Diagnostic output to stderr. */
+  readonly verbose: boolean;
+  /** Explicit progressive-disclosure level from `--detail`, if any. */
+  readonly detail?: DetailLevel;
+}
+
+/**
+ * A booted store session: the immutable bundle a pack read produces. ke/graphql
+ * types are referenced inline so this module carries no static import of the
+ * heavy runtime — the store code stays dynamic-import-only.
+ */
+export interface StoreSession {
+  /** The ke triple store (booted from the pack's n-quads cache). */
+  readonly store: import("@canonical/ke").Store;
+  /** The executable GraphQL schema (rebuilt from the extraction artifact). */
+  readonly schema: import("graphql").GraphQLSchema;
+  /** Create a fresh execution context bound to a store (accepts a Promise). */
+  readonly createContext: (
+    store:
+      | import("@canonical/ke").Store
+      | Promise<import("@canonical/ke").Store>,
+  ) => import("@canonical/ke-graphql").CompilerContext;
+  /** The prefixes the store (and every query) was built with. */
+  readonly prefixes: Readonly<Record<string, string>>;
+  /** The storeless entity index shipped with the pack. */
+  readonly index: import("./graphpack/types.js").PackIndex;
+}
+
+/**
+ * The lazy store handle. `get()` memoizes a successful {@link StoreSession}
+ * boot (a rejected boot is not memoized — a cold store throws STORE_UNAVAILABLE
+ * and a later `get()` retries); `booted` reports whether the store has actually
+ * been constructed (the storeless-guarantee spy target); `invalidate()` drops
+ * the memoized session (and the config memo it depends on) so the next `get()`
+ * re-boots — the long-lived MCP server calls it after every real mutation.
+ */
+export interface LazyStore {
+  /** Boot (once) and return the store session; throws STORE_UNAVAILABLE cold. */
+  get(): Promise<StoreSession>;
+  /** Whether the store has been constructed yet (spy target). */
+  readonly booted: boolean;
+  /** Drop the memoized session so the next `get()` re-boots against disk. */
+  invalidate(): void;
+}
+
+/**
+ * The query facade: `graphql` is the default typed spine (executed against the
+ * pack's precompiled schema); `sparql` is the raw, auto-prefixed escape hatch.
+ * Both boot the store lazily on first use.
+ */
+export interface QueryFacade {
+  /** Execute a GraphQL document against the pack's precompiled schema. */
+  graphql(
+    document: string,
+    variables?: Record<string, unknown> | null,
+  ): Promise<import("graphql").ExecutionResult>;
+  /** Execute a raw SPARQL query against the store (prefixes auto-applied). */
+  sparql(text: string): Promise<import("@canonical/ke").QueryResult>;
+}
+
+/**
+ * Mutation-invocation context — present only for a mutating verb, set by the
+ * CLI/MCP projector just before `run`. `preview` is true for a plan-only
+ * invocation (`--dry-run` on the CLI, or an MCP tool call without `confirm`): a
+ * mutating verb reads it to describe its intended effects WITHOUT performing
+ * network or heavy setup, so a preview stays side-effect-free. Real execution
+ * leaves it false. This is the generic seam every mutation verb copies.
+ */
+export interface MutationRuntime {
+  /** True for a plan-only preview; false for a real execution. */
+  readonly preview: boolean;
+}
+
+/**
+ * How this invocation reaches the user — populated by the projector for a
+ * mutating verb. An interactive verb reads it to pick its prompt strategy: an
+ * attended CLI without `--yes` gets a wizard; a non-interactive CLI (or `--yes`)
+ * gets flags+defaults; MCP gets params-or-error. `signal` aborts a run.
+ *
+ * NOTE (PR6): interactive setup mutations reuse this exact shape.
+ */
+export interface InteractionRuntime {
+  /**
+   * Both stdin and STDERR are a TTY (CLI); always false over MCP. Gated on
+   * stderr — not stdout — because the interactive Ink wizard renders to stderr
+   * and reads stdin, so `pragma <verb> 2>/dev/null` (stderr redirected) must
+   * fall to the non-interactive path rather than mounting an invisible render
+   * that blocks on stdin.
+   */
+  readonly isTTY: boolean;
+  /** Which projector is driving this run. */
+  readonly transport: "cli" | "mcp";
+  /** The user asked to skip an interactive confirmation (`--yes` / MCP confirm). */
+  readonly yes: boolean;
+  /** Abort signal for the run, if the projector wired one. */
+  readonly signal?: AbortSignal;
+  /**
+   * Abort the run (internal seam field, NOT covenant surface). An interactive
+   * verb threads this into its wizard so an in-Ink Ctrl-C — which Ink's raw
+   * mode swallows before it can become a SIGINT — aborts the run's
+   * `AbortController`, firing the interpreter's `checkInterrupted` between
+   * effects. The projector wires it alongside `signal`.
+   */
+  readonly abort?: () => void;
+}
+
+/**
+ * The opaque runner options a mutating verb's `run` assembles and the projector
+ * spreads into the node interpreter on the REAL-run branch only (never on
+ * dry-run/undo, which stay handler-free and mock prompts). It carries the
+ * interactivity + progress seam: the prompt handler, the stamping/progress
+ * effect callbacks, log routing, and an optional teardown the projector runs in
+ * a `finally` (e.g. to dispose an Ink render).
+ *
+ * The task-effect types are referenced inline so this module carries no static
+ * import of the node interpreter — the runtime stays cheap to construct.
+ */
+export interface RunnerOptions {
+  /** Resolve each interactive `Prompt` effect (the injected UI strategy). */
+  promptHandler?: (
+    effect: import("@canonical/task").Effect & { _tag: "Prompt" },
+  ) => Promise<unknown>;
+  /** Called before each effect — the stamping + progress seam. */
+  onEffectStart?: (effect: import("@canonical/task").Effect) => void;
+  /** Called after each effect completes (with its duration). */
+  onEffectComplete?: (
+    effect: import("@canonical/task").Effect,
+    duration: number,
+  ) => void;
+  /** Route task log output. */
+  onLog?: (level: "debug" | "info" | "warn" | "error", message: string) => void;
+  /**
+   * The per-call write root: relative fs-effect paths resolve against it in the
+   * node interpreter (`RunTaskOptions.cwd`), and it is the SAME `rt.cwd` the
+   * SEC-2 path jail validates — so a mutating verb's output can never land
+   * outside the directory the jail checked (no jail bypass). Absolute effect
+   * paths are unchanged; omitting it falls back to `process.cwd()`. Honest as of
+   * PR7 (the node interpreter now honours `RunTaskOptions.cwd`).
+   */
+  cwd?: string;
+  /** Abort signal, forwarded to the interpreter. */
+  signal?: AbortSignal;
+  /** Teardown run by the projector after the task settles (e.g. unmount Ink). */
+  dispose?: () => void | Promise<void>;
+}
+
+/**
+ * Per-invocation runtime handed to every verb `run`. Storeless verbs use only
+ * `cwd`/`version`/`globalFlags`/`loadConfig`; store-backed verbs reach the graph
+ * through `store`/`query`. The dispatcher boots the store only for
+ * `capability.needsStore` verbs, so a storeless verb never constructs it.
+ */
+export interface PragmaRuntime {
+  /** Directory the invocation resolves project state (config) against. */
+  readonly cwd: string;
+  /** CLI version string, surfaced by `info`. */
+  readonly version: string;
+  /** Global flags for this invocation. */
+  readonly globalFlags: GlobalFlags;
+  /** Memoized layered-config loader (resolved once per invocation). */
+  readonly loadConfig: () => Promise<ConfigLayers>;
+  /** The lazy store — booted only for `needsStore` verbs. */
+  readonly store: LazyStore;
+  /** The query facade over the lazy store. */
+  readonly query: QueryFacade;
+  /** Mutation context, set by the projector for a mutating verb (else absent). */
+  readonly mutation?: MutationRuntime;
+  /** How this run reaches the user, set by the projector for a mutating verb. */
+  readonly interaction?: InteractionRuntime;
+  /**
+   * Progress seam for a long mutating verb. Set by the projector (the CLI writes
+   * each message to stderr) so a verb can STREAM stage lines while it does heavy
+   * EAGER work — the resolve/parse/build that runs before its Task is even
+   * returned, which the Task interpreter's `onLog` therefore never sees. A verb
+   * emits through `runtime.report?.(…)`; unset (e.g. over MCP) makes it a no-op.
+   * Diagnostic-only: progress goes to stderr, never the stdout data stream.
+   */
+  readonly report?: (message: string) => void;
+  /**
+   * The runner options a mutating verb's `run` assembles for its real
+   * execution. NOT readonly: the verb writes it as its last act before
+   * returning the Task, and the projector reads it back on the real-run branch.
+   */
+  exec?: RunnerOptions;
+}

package/src/kernel/runtime/wasmEmbed.test.ts

@@ -0,0 +1,144 @@
+import { spawnSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+/**
+ * The store-boot path only fully lives in the standalone binary: this is the
+ * one thing vitest's in-process suite cannot catch — whether oxigraph's WASM
+ * and the embedded pack survive `bun build --compile`. So compile a fresh
+ * binary from the current source and spawn it. If the WASM did not embed, the
+ * probe crashes and this fails loudly (rather than the compiled CLI silently
+ * failing every store-backed command in production).
+ */
+const packageRoot = fileURLToPath(new URL("../../../", import.meta.url));
+
+let workdir: string;
+let binary: string;
+
+beforeAll(() => {
+  workdir = mkdtempSync(join(tmpdir(), "pragma-wasm-smoke-"));
+  binary = join(workdir, "pragma-smoke");
+  const build = spawnSync(
+    "bun",
+    [
+      "build",
+      "--compile",
+      "--target=bun-linux-x64",
+      "src/bin.ts",
+      "--outfile",
+      binary,
+    ],
+    { cwd: packageRoot, stdio: "pipe", encoding: "utf-8" },
+  );
+  if (build.status !== 0) {
+    throw new Error(`smoke build failed:\n${build.stderr}`);
+  }
+}, 120_000);
+
+afterAll(() => {
+  rmSync(workdir, { recursive: true, force: true });
+});
+
+/** Run the compiled binary in a scratch cwd with isolated XDG dirs (no local
+ * node_modules, no real cache) — proves the binary is self-contained. */
+const runBinary = (args: string[]) =>
+  spawnSync(binary, args, {
+    cwd: workdir,
+    stdio: "pipe",
+    encoding: "utf-8",
+    env: {
+      ...process.env,
+      HOME: workdir,
+      XDG_CACHE_HOME: join(workdir, "cache"),
+      XDG_STATE_HOME: join(workdir, "state"),
+      XDG_CONFIG_HOME: join(workdir, "config"),
+    },
+  });
+
+describe("oxigraph WASM + embedded pack embed in the compiled binary (PROTECTED)", () => {
+  it("dist binary boots the embedded store via __store-probe (needsStore path)", () => {
+    const run = runBinary(["__store-probe"]);
+    expect(run.status, run.stderr).toBe(0);
+    const out = JSON.parse(run.stdout.trim()) as {
+      ok: boolean;
+      entities: number;
+      triples: string;
+    };
+    expect(out.ok).toBe(true);
+    expect(out.entities).toBe(6);
+    expect(Number(out.triples)).toBeGreaterThan(0);
+  });
+
+  it("dist binary runs storeless sources status", () => {
+    const run = runBinary(["sources", "status", "--format", "json"]);
+    expect(run.status, run.stderr).toBe(0);
+    const envelope = JSON.parse(run.stdout.trim()) as {
+      ok: boolean;
+      data: { lockPresent: boolean; cached: boolean };
+    };
+    expect(envelope.ok).toBe(true);
+    // A fresh install: no lock, store not yet built.
+    expect(envelope.data.lockPresent).toBe(false);
+    expect(envelope.data.cached).toBe(false);
+  });
+
+  // Regression guard: `sources update` walks a package's TTL directories. The
+  // compiled binary's node:fs globSync mishandles `**` (returns bogus paths),
+  // which the in-process suite could not catch — so exercise the real binary.
+  it("dist binary runs sources update end-to-end (build + lock + status)", () => {
+    const pkg = join(workdir, "pkg");
+    const proj = join(workdir, "proj");
+    mkdirSync(join(pkg, "definitions"), { recursive: true });
+    mkdirSync(proj, { recursive: true });
+    writeFileSync(
+      join(pkg, "definitions", "w.ttl"),
+      `@prefix ex: <https://ex.test/#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+ex:Widget a owl:Class ; rdfs:label "Widget" .
+ex:one a ex:Widget ; rdfs:label "One" .
+`,
+    );
+    writeFileSync(
+      join(proj, "pragma.config.ts"),
+      `export default { packages: [{ name: "pkg-a", source: "file://${pkg}" }] };\n`,
+    );
+
+    const env = {
+      HOME: workdir,
+      XDG_CACHE_HOME: join(workdir, "cache"),
+      XDG_STATE_HOME: join(workdir, "state"),
+      XDG_CONFIG_HOME: join(workdir, "config"),
+    };
+    const inProj = (args: string[]) =>
+      spawnSync(binary, args, {
+        cwd: proj,
+        stdio: "pipe",
+        encoding: "utf-8",
+        env: { ...process.env, ...env },
+      });
+
+    const update = inProj(["sources", "update", "--yes", "--format", "json"]);
+    expect(update.status, update.stderr).toBe(0);
+    expect(existsSync(join(proj, "pragma.lock.json"))).toBe(true);
+
+    const status = inProj(["sources", "status", "--format", "json"]);
+    const envelope = JSON.parse(status.stdout.trim()) as {
+      data: { lockPresent: boolean; cached: boolean; entityCount: number };
+    };
+    expect(envelope.data.lockPresent).toBe(true);
+    expect(envelope.data.cached).toBe(true);
+    // Distinct abox subjects: the one individual (ex:one). The ex:Widget class
+    // is tbox schema, not an entity — the raw entity count would double this (A1).
+    expect(envelope.data.entityCount).toBe(1);
+  });
+});

package/src/kernel/spec/asVerb.ts

@@ -0,0 +1,23 @@
+/**
+ * Widen a strongly-typed verb to the base {@link VerbSpec} at the registry
+ * boundary.
+ *
+ * A `VerbSpec<P, R>` with a concrete `R` cannot be placed directly in a
+ * `CapabilityModule.verbs` array (`VerbSpec<…, unknown>[]`) because `Formatters`
+ * is invariant in its data type. Authoring keeps the strong `R` so the
+ * formatters in each `*.render.ts` are type-checked against the real payload;
+ * this erases only that phantom `R` where the module is composed. The
+ * projectors re-narrow through the verb's own formatters at run time.
+ */
+
+import type { VerbSpec } from "./types.js";
+
+/**
+ * Erase a verb's concrete data type for registry composition.
+ *
+ * @param verb - A strongly-typed verb spec.
+ * @returns The same verb widened to the base `VerbSpec`.
+ */
+export function asVerb<P, R>(verb: VerbSpec<P, R>): VerbSpec {
+  return verb as unknown as VerbSpec;
+}

package/src/kernel/spec/emitReference.test.ts

@@ -0,0 +1,196 @@
+import { describe, expect, it } from "vitest";
+import {
+  fixtureModule,
+  fixtureReferenceModule,
+} from "../../testing/fixtures/fixtureCapability.js";
+import { ERROR_CODES } from "../error/constants.js";
+import { emitReference } from "./emitReference.js";
+
+/** The four pages every reference doc set carries. */
+const PAGES = ["index.md", "commands.md", "tools.md", "errors.md"];
+
+describe("emitReference", () => {
+  const docs = emitReference([fixtureReferenceModule]);
+  const index = docs.get("index.md") ?? "";
+  const commands = docs.get("commands.md") ?? "";
+  const tools = docs.get("tools.md") ?? "";
+  const errors = docs.get("errors.md") ?? "";
+
+  it("emits exactly the four reference pages", () => {
+    expect([...docs.keys()].sort()).toEqual([...PAGES].sort());
+  });
+
+  it("ends every page in exactly one trailing newline", () => {
+    for (const content of docs.values()) {
+      expect(content.endsWith("\n")).toBe(true);
+      expect(content.endsWith("\n\n")).toBe(false);
+    }
+  });
+
+  it("is deterministic — the same catalog yields byte-identical pages", () => {
+    const again = emitReference([fixtureReferenceModule]);
+    for (const page of PAGES) {
+      expect(again.get(page)).toBe(docs.get(page));
+    }
+  });
+
+  describe("index.md", () => {
+    it("reports counts derived from the live grammar", () => {
+      // gizmo + ping = 2 nouns; local/scan/tidy/wipe/ping = 5 commands (hidden
+      // dropped); scan/tidy/wipe/ping = 4 tools (local withheld); 1 resource
+      // template (the module's `mcpResources` surface).
+      expect(index).toContain("**2** command nouns");
+      expect(index).toContain("**5** CLI commands");
+      expect(index).toContain("**4** MCP tools");
+      expect(index).toContain("**1** resource template(s)");
+    });
+
+    it("links the three sibling pages with relative paths", () => {
+      expect(index).toContain("(./commands.md)");
+      expect(index).toContain("(./tools.md)");
+      expect(index).toContain("(./errors.md)");
+    });
+  });
+
+  describe("commands.md", () => {
+    it("groups verbs under noun headings, sorted, hidden excluded", () => {
+      expect(commands).toContain("## gizmo");
+      expect(commands).toContain("## ping");
+      expect(commands.indexOf("## gizmo")).toBeLessThan(
+        commands.indexOf("## ping"),
+      );
+      expect(commands).not.toContain("hidden");
+    });
+
+    it("renders a read verb's usage, args, flags, attributes, and examples", () => {
+      expect(commands).toContain("### pragma gizmo scan");
+      expect(commands).toContain("pragma gizmo scan [targets...] [options]");
+      // Optional variadic positional token.
+      expect(commands).toContain("| `[targets...]` | no |");
+      // Enum flag: escaped pipe token, enum values, and default in the description.
+      expect(commands).toContain("| `--mode` | `<fast\\|slow>` |");
+      expect(commands).toContain("(one of: fast, slow) (default: fast)");
+      // Each flag kind renders its value placeholder.
+      expect(commands).toContain("| `--limit` | `<number>` |");
+      expect(commands).toContain("| `--label` | `<string>` |");
+      expect(commands).toContain("| `--include` | `<value...>` |");
+      // A bare boolean switch has no value placeholder.
+      expect(commands).toContain("| `--deep` | — |");
+      expect(commands).toContain("- Store: storeless.");
+      expect(commands).toContain("- MCP: exposed as the `gizmo_scan` tool.");
+      // A note becomes a trailing comment; a noteless example stays bare.
+      expect(commands).toContain("pragma gizmo scan  # scan everything");
+      expect(commands).toContain("pragma gizmo scan alpha --mode slow");
+    });
+
+    it("marks a store-backed destructive mutation's CLI attributes", () => {
+      expect(commands).toContain("### pragma gizmo wipe");
+      expect(commands).toContain("pragma gizmo wipe <path>");
+      expect(commands).toContain(
+        "- Store: reads the local store (`pragma sources update` builds it).",
+      );
+      expect(commands).toContain("- Mutation: plan-first");
+    });
+
+    it("marks a visible verb withheld from MCP", () => {
+      expect(commands).toContain("### pragma gizmo local");
+      expect(commands).toContain("- MCP: not exposed (CLI-only).");
+    });
+
+    it("renders a self-verb with no sub-command in its invocation", () => {
+      expect(commands).toContain("### pragma ping");
+      expect(commands).toContain("```\npragma ping\n```");
+    });
+
+    it("falls back to the summary when a verb has no doc", () => {
+      // `ping` has no `doc`; its summary is the section body.
+      const pingSection = commands.slice(commands.indexOf("### pragma ping"));
+      expect(pingSection).toContain("Ping the gizmo host.");
+    });
+  });
+
+  describe("tools.md", () => {
+    it("adds the disclosure `detail` param and comma-joined enum types", () => {
+      expect(tools).toContain("### gizmo_scan");
+      expect(tools).toContain("| `mode` | enum(fast, slow) | no |");
+      expect(tools).toContain("| `include` | string[] | no |");
+      expect(tools).toContain(
+        "| `detail` | enum(summary, detailed) | no | Progressive-disclosure level (default summary). |",
+      );
+    });
+
+    it("adds confirm + cwd to a mutating tool and flags it destructive", () => {
+      const wipe = tools.slice(tools.indexOf("### gizmo_wipe"));
+      expect(wipe).toContain("| `confirm` | boolean | no |");
+      expect(wipe).toContain("| `cwd` | string | no |");
+      expect(tools).toContain(
+        "Mutation — plan-first (set `confirm: true` to apply). Marked destructive.",
+      );
+    });
+
+    it("marks a non-destructive mutating tool as such", () => {
+      const tidy = tools.slice(tools.indexOf("### gizmo_tidy"));
+      expect(tidy).toContain("| `confirm` | boolean | no |");
+      // The `destructive: false` branch of `formatToolAnnotations`.
+      expect(tools).toContain(
+        "Mutation — plan-first (set `confirm: true` to apply). Non-destructive.",
+      );
+    });
+
+    it("omits verbs withheld from MCP", () => {
+      expect(tools).not.toContain("gizmo_local");
+    });
+
+    it("marks a no-param tool as taking no input", () => {
+      const ping = tools.slice(tools.indexOf("### ping"));
+      expect(ping.slice(0, 200)).toContain("_No input parameters._");
+    });
+
+    it("renders every non-tool surface bullet the module declares", () => {
+      expect(tools).toContain("## Non-tool surface");
+      // The module declares an `mcpResources` template surface (its `surface.
+      // templates` id) and an `mcpPrompts` native surface, so all three bullets
+      // render — exercising both optional branches of `renderNonToolSurface`.
+      expect(tools).toContain("- **Resources**: `gizmo:{+uri}`");
+      expect(tools).toContain("- **Prompts**:");
+      expect(tools).toContain("- **Instructions**:");
+    });
+  });
+
+  describe("errors.md", () => {
+    it("renders the exit-code table and the full error catalog", () => {
+      expect(errors).toContain("| `0` | success |");
+      expect(errors).toContain("| `3` | store unavailable |");
+      expect(errors).toContain("| `ENTITY_NOT_FOUND` |");
+      expect(errors).toContain("| `UNSUPPORTED` |");
+    });
+
+    it("lists every code in the closed ERROR_CODES tuple (exhaustive)", () => {
+      // Non-circular exhaustiveness: iterate the source-of-truth tuple and
+      // assert each code's `catalog` row is present, so a code added to the
+      // kernel without a catalog entry fails here (not just the 2 spot-checks).
+      for (const code of ERROR_CODES) {
+        expect(errors, `errors.md is missing \`${code}\``).toContain(
+          `\`${code}\``,
+        );
+      }
+    });
+
+    it("embeds the response envelope as a JSON block", () => {
+      expect(errors).toContain("```json");
+      expect(errors).toContain('"ok": true');
+      expect(errors).toContain('"code": "<ErrorCode>"');
+    });
+  });
+});
+
+describe("emitReference — MCP annotation branches", () => {
+  it("renders a destructive fixture tool and a native-prompt-free surface", () => {
+    // `fixtureModule.make` is exposed, mutating, and destructive — the same
+    // `Marked destructive.` branch, driven from the emitSurface fixture.
+    const tools = emitReference([fixtureModule]).get("tools.md") ?? "";
+    expect(tools).toContain("### widget_make");
+    expect(tools).toContain("Marked destructive.");
+    expect(tools).not.toContain("- **Prompts**:");
+  });
+});