@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/kernel/runtime/store.ts

@@ -0,0 +1,90 @@
+/**
+ * The lazy store — the ONE guarded factory the storeless-guarantee spy targets.
+ *
+ * `get()` dynamic-imports the heavy session loader, so constructing a runtime —
+ * or importing any capability — never pulls ke/ke-graphql/oxigraph. The
+ * dispatcher calls `get()` only for `capability.needsStore` verbs, which is what
+ * makes the storeless guarantee hold by construction: a storeless verb has no
+ * path to the store factory, so `booted` stays false.
+ *
+ * Memoization WITH invalidation — the store is long-lived (the MCP server boots
+ * ONE runtime for its whole lifetime and shares it across every tool call), not
+ * one-shot:
+ *
+ * - A SUCCESSFUL boot is memoized (the session is immutable until invalidated).
+ *   A REJECTED boot is NOT: a cold store throws STORE_UNAVAILABLE from the
+ *   loader, and `get()` clears the memo before re-throwing so a later `get()`
+ *   retries from scratch. This matters precisely because the server is
+ *   long-lived: an agent that hits STORE_UNAVAILABLE can run `sources update`
+ *   (which builds the pack on disk) and retry — something DID change to make the
+ *   retry succeed, so memoizing the rejection would strand the session forever.
+ *   For a one-shot CLI (a single `get()` per process) clearing the memo on
+ *   failure is a harmless no-op.
+ * - `invalidate()` drops the memoized session so the next `get()` re-boots
+ *   against the current on-disk pack. Because boot reads config through
+ *   `ctx.loadConfig` (which is itself memoized upstream), invalidating the store
+ *   must also drop that config memo — otherwise a re-boot would reuse stale
+ *   config. `onInvalidate` is the hook the runtime wires for exactly that (it
+ *   clears the boot-level `configPromise`). The MCP projector calls
+ *   `invalidate()` after every real mutation so a `config_set`/`sources update`
+ *   becomes visible to the next read tool.
+ */
+
+import type { ConfigLayers } from "../config/types.js";
+import type { LazyStore, StoreSession } from "./types.js";
+
+/** What the lazy store needs to boot: a cwd and a memoized config loader. */
+export interface LazyStoreContext {
+  readonly cwd: string;
+  readonly loadConfig: () => Promise<ConfigLayers>;
+  /**
+   * Called by `invalidate()` after the store memo is dropped, so the runtime can
+   * also drop the sibling caches this store's boot depends on (the memoized
+   * config `loadConfig` resolves) — a re-boot must not reuse stale config.
+   */
+  readonly onInvalidate?: () => void;
+}
+
+/**
+ * Create a lazy store handle.
+ *
+ * @param ctx - The working directory, memoized config loader, and optional
+ *   invalidation hook.
+ * @returns The lazy store: a `get()` that memoizes a successful boot (never a
+ *   rejection), a `booted` flag, and an `invalidate()` reset.
+ */
+export function createLazyStore(ctx: LazyStoreContext): LazyStore {
+  let session: Promise<StoreSession> | undefined;
+  let booted = false;
+
+  return {
+    get booted(): boolean {
+      return booted;
+    },
+    get(): Promise<StoreSession> {
+      if (session === undefined) {
+        session = (async () => {
+          try {
+            const { loadStoreSession } = await import("./loadSession.js");
+            const loaded = await loadStoreSession(ctx);
+            booted = true;
+            return loaded;
+          } catch (err) {
+            // Clear the memo BEFORE the rejection propagates (inside the async
+            // IIFE, so there is no window where a concurrent caller adopts the
+            // rejected promise): the next `get()` retries a fresh boot, which a
+            // `sources update` between calls can make succeed.
+            session = undefined;
+            throw err;
+          }
+        })();
+      }
+      return session;
+    },
+    invalidate(): void {
+      session = undefined;
+      booted = false;
+      ctx.onInvalidate?.();
+    },
+  };
+}

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

@@ -0,0 +1,86 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { configModule } from "../../capabilities/config/index.js";
+import { infoModule } from "../../capabilities/info/index.js";
+import { completeVerb } from "../../capabilities/meta/complete.verb.js";
+import { sourcesModule } from "../../capabilities/sources/index.js";
+import { executeVerb } from "../project/cli/dispatch.js";
+import type { GlobalFlags, VerbSpec } from "../spec/types.js";
+import { bootRuntime } from "./boot.js";
+
+const NO_MUT = { dryRun: false, undo: false, yes: false };
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+
+const infoVerb = infoModule.verbs[0] as VerbSpec;
+const showVerb = configModule.verbs[0] as VerbSpec;
+const sourcesStatusVerb = sourcesModule.verbs[0] as VerbSpec;
+
+/** A needs-store READ verb whose body never touches the store — so a `booted`
+ * flag flipping to true proves the *dispatcher* booted it for `needsStore`. */
+const needsStoreVerb: VerbSpec = {
+  path: ["fixture", "needs-store"],
+  summary: "A store-backed read.",
+  params: [],
+  output: {
+    formatters: {
+      plain: (d) => JSON.stringify(d),
+      llm: (d) => JSON.stringify(d),
+      json: (d) => JSON.stringify(d),
+    },
+  },
+  capability: {
+    needsStore: true,
+    mutates: false,
+    mcp: { expose: false, reason: "test fixture" },
+  },
+  run: async () => ({ ok: true }),
+};
+
+const freshCwd = (): string => mkdtempSync(join(tmpdir(), "pragma-storeless-"));
+
+describe("storeless guarantee — the store never boots for storeless verbs (PROTECTED)", () => {
+  it("info does not construct the store", async () => {
+    const runtime = bootRuntime(FLAGS, freshCwd());
+    await executeVerb(infoVerb, {}, NO_MUT, runtime);
+    expect(runtime.store.booted).toBe(false);
+  });
+
+  it("config show does not construct the store", async () => {
+    const runtime = bootRuntime(FLAGS, freshCwd());
+    await executeVerb(showVerb, {}, NO_MUT, runtime);
+    expect(runtime.store.booted).toBe(false);
+  });
+
+  it("sources status does not construct the store (reports a cold store)", async () => {
+    const runtime = bootRuntime(FLAGS, freshCwd());
+    const outcome = await executeVerb(sourcesStatusVerb, {}, NO_MUT, runtime);
+    expect(outcome.exitCode).toBe(0);
+    expect(runtime.store.booted).toBe(false);
+  });
+
+  it("__complete does not construct the store", async () => {
+    const runtime = bootRuntime(FLAGS, freshCwd());
+    await executeVerb(
+      completeVerb as VerbSpec,
+      { words: ["config"] },
+      NO_MUT,
+      runtime,
+    );
+    expect(runtime.store.booted).toBe(false);
+  });
+
+  it("a needsStore verb DOES construct the store (spy fires)", async () => {
+    const runtime = bootRuntime(FLAGS, freshCwd());
+    expect(runtime.store.booted).toBe(false);
+    const outcome = await executeVerb(needsStoreVerb, {}, NO_MUT, runtime);
+    expect(outcome.exitCode).toBe(0);
+    expect(runtime.store.booted).toBe(true);
+  });
+});

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 for LLM/agent consumption. */
+  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,142 @@
+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);
+    expect(envelope.data.entityCount).toBe(2);
+  });
+});

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/emitSurface.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { fixtureModule } from "../../testing/fixtures/fixtureCapability.js";
+import {
+  emitSurface,
+  FIXED_SURFACE,
+  kebabCase,
+  toolName,
+  verbLabel,
+} from "./emitSurface.js";
+
+describe("naming rules", () => {
+  it("derives tool names from the path", () => {
+    expect(toolName(["info"])).toBe("info");
+    expect(toolName(["config", "show"])).toBe("config_show");
+  });
+
+  it("uses the last path segment as the verb label", () => {
+    expect(verbLabel(["info"])).toBe("info");
+    expect(verbLabel(["config", "show"])).toBe("show");
+  });
+
+  it("kebab-cases camelCase flag names", () => {
+    expect(kebabCase("withHistory")).toBe("with-history");
+    expect(kebabCase("allTiers")).toBe("all-tiers");
+    expect(kebabCase("name")).toBe("name");
+  });
+});
+
+describe("emitSurface", () => {
+  const surface = emitSurface([fixtureModule]);
+
+  it("excludes hidden verbs", () => {
+    const labels = surface.nouns.widget?.verbs.map((v) => v.v);
+    expect(labels).toEqual(["list", "make"]);
+    expect(labels).not.toContain("internal");
+  });
+
+  it("emits a bare read verb with only v + mcp", () => {
+    const list = surface.nouns.widget?.verbs.find((v) => v.v === "list");
+    expect(list).toEqual({ v: "list", mcp: "widget_list" });
+  });
+
+  it("emits args, flags, mutates, needsStore for a mutating verb", () => {
+    const make = surface.nouns.widget?.verbs.find((v) => v.v === "make");
+    expect(make).toEqual({
+      v: "make",
+      args: ["<name>"],
+      flags: ["--with-history"],
+      mutates: true,
+      needsStore: true,
+      mcp: "widget_make",
+    });
+  });
+
+  it("collects exposed tools, sorted, excluding hidden", () => {
+    expect(surface.mcpSurface.tools).toEqual(["widget_list", "widget_make"]);
+  });
+
+  it("merges in the fixed kernel sections verbatim", () => {
+    expect(surface.bins).toEqual(FIXED_SURFACE.bins);
+    expect(surface.globalFlags).toEqual(FIXED_SURFACE.globalFlags);
+    expect(surface.exitCodes).toEqual(FIXED_SURFACE.exitCodes);
+    expect(surface.budgets).toEqual(FIXED_SURFACE.budgets);
+  });
+});