@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/kernel/packs/sparql/runSelect.test.ts

@@ -0,0 +1,80 @@
+/**
+ * `runSelect` — the single choke point for every TRUSTED, generated SPARQL read.
+ *
+ * Pins the unseeded-store remap: a generated pack query only references the
+ * pack's own `ds:`/`cs:` prefixes, so a "Prefix not found" from the facade means
+ * the store was never built — an actionable STORE_UNAVAILABLE, NOT a raw error
+ * collapsing to INTERNAL_ERROR ("please report this issue"). The recovery carries
+ * BOTH the CLI command (`pragma sources update`) and the MCP tool an agent calls
+ * (`sources_update`), so either surface can recover.
+ */
+
+import { describe, expect, it } from "vitest";
+import type { PragmaRuntime } from "../../runtime/types.js";
+import { runSelect } from "./runSelect.js";
+
+/** A runtime whose query facade throws the given error for every SPARQL call. */
+function throwingRuntime(error: unknown): Pick<PragmaRuntime, "query"> {
+  return {
+    query: {
+      sparql: async () => {
+        throw error;
+      },
+    } as unknown as PragmaRuntime["query"],
+  };
+}
+
+/** A runtime whose facade resolves a fixed SELECT result. */
+function selectRuntime(
+  bindings: Record<string, string>[],
+): Pick<PragmaRuntime, "query"> {
+  return {
+    query: {
+      sparql: async () => ({ type: "select", bindings }),
+    } as unknown as PragmaRuntime["query"],
+  };
+}
+
+describe("runSelect — unseeded-store remap (ROOT A)", () => {
+  it("remaps a 'Prefix not found' to STORE_UNAVAILABLE with CLI + MCP recovery", async () => {
+    let caught: unknown;
+    try {
+      await runSelect(
+        throwingRuntime(new Error("Prefix not found: ds")),
+        "SELECT ?x WHERE { ?x a ds:Thing }",
+        "block",
+      );
+    } catch (error) {
+      caught = error;
+    }
+
+    // The whole point: it is NOT an unclassified INTERNAL_ERROR.
+    expect(caught).toMatchObject({ code: "STORE_UNAVAILABLE" });
+    const recovery = (caught as { recovery?: Record<string, unknown> })
+      .recovery;
+    expect(recovery?.cli).toBe("pragma sources update");
+    // An agent cannot run a shell command — it recovers via the tool.
+    expect(recovery?.mcp).toMatchObject({ tool: "sources_update" });
+  });
+
+  it("passes a non-prefix facade error through unchanged (not remapped)", async () => {
+    const boom = new Error("some other engine failure");
+    let caught: unknown;
+    try {
+      await runSelect(throwingRuntime(boom), "SELECT ?x WHERE {}", "block");
+    } catch (error) {
+      caught = error;
+    }
+    // A generic failure is NOT masquerading as a cold store.
+    expect(caught).toBe(boom);
+  });
+
+  it("returns the bindings on a well-formed SELECT", async () => {
+    const rows = await runSelect(
+      selectRuntime([{ name: "Button" }, { name: "Card" }]),
+      "SELECT ?name WHERE { ?x ds:name ?name }",
+      "block",
+    );
+    expect(rows).toEqual([{ name: "Button" }, { name: "Card" }]);
+  });
+});

package/src/kernel/packs/sparql/runSelect.ts

@@ -0,0 +1,84 @@
+/**
+ * Run a pack story's SELECT through the query facade and return its rows.
+ *
+ * The store rejects non-read queries at the engine level; this guards the result
+ * shape so a pack whose query is not a SELECT fails with a recoverable config
+ * error instead of a shape mismatch downstream. The facade boots the store
+ * lazily and auto-applies the pack's prefixes, so generated queries use prefixed
+ * terms directly. This is the single choke point for every TRUSTED, generated
+ * SPARQL read (list stories, lookup name→URI resolves, expands) — user SPARQL
+ * (`graph query`) goes through the facade directly and stays INVALID_INPUT.
+ */
+
+import { RECOVERY_CLI_PREFIX } from "../../../constants.js";
+import { PragmaError } from "../../error/PragmaError.js";
+import { cliRecovery } from "../../error/recovery.js";
+import type { PragmaRuntime } from "../../runtime/types.js";
+import type { PackRow } from "../types.js";
+
+/**
+ * True when a trusted, generated query failed because the store does not know a
+ * prefix it used. A generated pack query only references the pack's own
+ * ontology prefixes (`ds:`/`cs:`), so a "prefix not found" means the store is
+ * unseeded — the fresh-install embedded fallback carries no design-system
+ * ontology — rather than a query bug.
+ */
+function isUnseededStoreError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return /prefix/i.test(message) && /not\s+found/i.test(message);
+}
+
+/**
+ * Run the facade query, remapping an unseeded-store failure. A generated pack
+ * query hitting an unknown prefix means the store was never built for this
+ * design system (the first thing a fresh install hits) — surface the actionable
+ * STORE_UNAVAILABLE with the canonical `pragma sources update` recovery instead
+ * of a raw SPARQL "Prefix not found" wrapped as INTERNAL_ERROR ("please report
+ * this issue"). Returns the inferred facade result type, so this module stays
+ * clear of a static `@canonical/ke` import (the lazy-dispatch guard).
+ */
+async function queryOrRemap(rt: Pick<PragmaRuntime, "query">, query: string) {
+  try {
+    return await rt.query.sparql(query);
+  } catch (error) {
+    if (error instanceof PragmaError) throw error;
+    if (isUnseededStoreError(error)) {
+      throw PragmaError.storeUnavailable(
+        "The store has not been built for this project yet.",
+        {
+          recovery: cliRecovery(
+            `${RECOVERY_CLI_PREFIX}sources update`,
+            "Build the local store from the configured design-system packages.",
+            // An agent recovers by calling the tool, then retrying (PR9 C1 cold-
+            // store retry makes the post-update retry succeed).
+            { tool: "sources_update" },
+          ),
+        },
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * @param rt - The runtime (its query facade over the lazy store).
+ * @param query - SPARQL SELECT text (prefixes auto-applied by the store).
+ * @param source - The pack source, for error attribution.
+ * @returns One record per row, keyed by SELECT variable name.
+ * @throws PragmaError CONFIG_ERROR when the query is not a SELECT;
+ *   STORE_UNAVAILABLE (exit 3) when the store is unseeded.
+ * @note Impure — queries the store through the facade.
+ */
+export async function runSelect(
+  rt: Pick<PragmaRuntime, "query">,
+  query: string,
+  source: string,
+): Promise<PackRow[]> {
+  const result = await queryOrRemap(rt, query);
+  if (result.type !== "select") {
+    throw PragmaError.configError(
+      `Story query in ${source} must be a SELECT (got ${result.type}).`,
+    );
+  }
+  return result.bindings as PackRow[];
+}

package/src/kernel/packs/toolDescription.test.ts

@@ -0,0 +1,81 @@
+/**
+ * PROTECTED — the pack `toolDescription` → MCP tool description wiring.
+ *
+ * A pack authors `toolDescription` FOR the agent-facing MCP tool description
+ * (see kernel/packs/types.ts, "MCP tool description"). The compiler routes it
+ * into `VerbSpec.doc`, the MCP projector emits `doc ?? summary` as the tool
+ * description, and the CLI projector renders `doc` in verb help WITHOUT the
+ * MCP tool-call example (`noun_verb {…}` is MCP-transport syntax).
+ *
+ * This pins representative text on BOTH surfaces so the routing can't silently
+ * regress: the rich description must reach MCP, and the MCP tool-call example
+ * must never leak into CLI `--help`.
+ */
+
+import { describe, expect, it } from "vitest";
+import { standardModule } from "../../capabilities/standard/index.js";
+import { tokenModule } from "../../capabilities/token/index.js";
+import { projectMcp } from "../../testing/helpers/projectMcp.js";
+import { formatVerbHelp } from "../project/cli/verbHelp.js";
+import type { VerbSpec } from "../spec/types.js";
+
+const verb = (
+  module: { verbs: readonly VerbSpec[] },
+  label: string,
+): VerbSpec => {
+  const found = module.verbs.find((v) => v.path[1] === label);
+  if (!found) throw new Error(`no verb "${label}"`);
+  return found;
+};
+
+describe("pack toolDescription wiring (PROTECTED)", () => {
+  it("routes the lookup-level toolDescription to MCP, whole (with the call example)", async () => {
+    const mcp = await projectMcp([tokenModule]);
+    const desc = (await mcp.listTools()).find(
+      (t) => t.name === "token_lookup",
+    )?.description;
+    await mcp.cleanup();
+    expect(desc).toContain(
+      "Get type and theme values for one or more design tokens by name.",
+    );
+    // The authored MCP tool-call example survives on the MCP surface.
+    expect(desc).toContain(
+      'Example: token_lookup { names: ["color.primary"] }',
+    );
+  });
+
+  it("routes the definition-level toolDescription to the MCP list tool", async () => {
+    const mcp = await projectMcp([tokenModule]);
+    const desc = (await mcp.listTools()).find(
+      (t) => t.name === "token_list",
+    )?.description;
+    await mcp.cleanup();
+    // The rich description reaches MCP (was previously dropped — only `summary`
+    // reached the tool), including the authored call example.
+    expect(desc).toContain("List all design tokens with their type.");
+    expect(desc).toContain("Example: token_list {}");
+  });
+
+  it("routes an extra-verb toolDescription to its MCP tool", async () => {
+    const mcp = await projectMcp([standardModule]);
+    const desc = (await mcp.listTools()).find(
+      (t) => t.name === "standard_categories",
+    )?.description;
+    await mcp.cleanup();
+    expect(desc).toBe("List all code standard categories.");
+  });
+
+  it("CLI --help shows the rich prose but NEVER the MCP tool-call syntax", () => {
+    const lookupHelp = formatVerbHelp("pragma", verb(tokenModule, "lookup"));
+    expect(lookupHelp).toContain(
+      "Get type and theme values for one or more design tokens by name.",
+    );
+    // No-leaks: the `token_lookup {…}` MCP call shape must not reach CLI help.
+    expect(lookupHelp).not.toContain("token_lookup {");
+    expect(lookupHelp).not.toContain("Example:");
+
+    const listHelp = formatVerbHelp("pragma", verb(tokenModule, "list"));
+    expect(listHelp).toContain("List all design tokens with their type.");
+    expect(listHelp).not.toContain("token_list {");
+  });
+});

package/src/kernel/packs/types.ts

@@ -0,0 +1,337 @@
+/**
+ * The pack grammar (v2) — "reads as data".
+ *
+ * A pack maps a noun to preferred queries: a SPARQL SELECT for the list story
+ * and a generated, injection-safe lookup. One grammar and one compiler
+ * ({@link ../compile}) project a pack into {@link ../../spec/types.VerbSpec}s;
+ * the CLI and MCP projectors then treat pack verbs like any other. This closes
+ * the two old forks — three read-noun styles collapse to one pack shape, and
+ * the two pack compilers collapse to one.
+ *
+ * These types are hand-authored and zod-free so the compiler (reached on the
+ * `--help`/`__complete` fast path via `capabilities/index`) never pulls zod;
+ * {@link ../schema} validates the same shapes and is imported lazily, only for
+ * dynamic (config/package) packs and in tests.
+ *
+ * Progressive disclosure is CANONICAL: a level tag names one of
+ * `constants.DETAIL_LEVELS` (`summary` < `standard` < `detailed`), and gating
+ * is by that canonical index — a pack's declared `levels` is any ordered subset
+ * of the canonical set.
+ */
+
+/** A list column: a SELECT variable to display. */
+export interface PackColumn {
+  /** SELECT variable name (without `?`). */
+  readonly field: string;
+  /** Column heading (defaults to the field name). */
+  readonly label?: string;
+}
+
+/** A looked-up value: an output name bound to a property of the entity. */
+export interface PackField {
+  /** Output field name on the looked-up entity. */
+  readonly name: string;
+  /** Property to read — a prefixed name (`ds:tier`) or absolute IRI. */
+  readonly property: string;
+  /** Display label (defaults to the field name). */
+  readonly label?: string;
+  /**
+   * Explicit GraphQL field name for `source: "graphql"` lookups — the escape
+   * hatch when the ontology→schema derivation does not match the compiled
+   * schema. Ignored on the SPARQL path.
+   */
+  readonly graphqlField?: string;
+  /**
+   * Minimum canonical disclosure level at which this value is fetched and
+   * rendered. Omitted means the base level (always included). Below its level
+   * the value is excluded from the generated query/document.
+   */
+  readonly level?: string;
+}
+
+/** A long-form lookup section (inline field or code block). */
+export interface PackSection extends PackField {
+  /** Rendering kind (inline field or fenced code block). */
+  readonly kind?: "field" | "code";
+}
+
+/** A field read from each child node of a {@link PackExpand}. */
+export interface PackExpandField {
+  /** Output field name on the child record. */
+  readonly name: string;
+  /** Property to read on the child node — prefixed name, IRI, or path. */
+  readonly property: string;
+  /** Display label (defaults to the field name). */
+  readonly label?: string;
+  /** Explicit GraphQL field name (escape hatch). Ignored on the SPARQL path. */
+  readonly graphqlField?: string;
+}
+
+/**
+ * A second-hop projection inside an expand's `select` — GraphQL source only.
+ * One extra level (child → grandchildren); a nested expand's `select` admits
+ * only scalar fields, so nesting stops here. Rejected on `source: "sparql"`.
+ */
+export interface PackNestedExpand {
+  /** Output field holding the grandchild values on each child record. */
+  readonly name: string;
+  /** Relation from the child node to each grandchild — prefixed name or IRI. */
+  readonly relation: string;
+  /** Explicit GraphQL field name (escape hatch over the derived name). */
+  readonly graphqlField?: string;
+  /** Scalar fields to read from each grandchild. */
+  readonly select: readonly PackExpandField[];
+}
+
+/** One entry of an expand's `select`: a child field or a nested expand. */
+export type PackExpandSelect = PackExpandField | PackNestedExpand;
+
+/** Whether an expand-select entry is a nested expand (vs a plain field). */
+export function isNestedExpand(
+  entry: PackExpandSelect,
+): entry is PackNestedExpand {
+  return "relation" in entry;
+}
+
+/**
+ * A multi-valued nested projection: `entity → relation → child nodes`, each
+ * child projected to a small record. Resolved with a generated, injection-safe
+ * sub-SELECT bound to the already-resolved entity IRI (never user input) on the
+ * SPARQL path, or one document hop on the GraphQL path.
+ */
+export interface PackExpand {
+  /** Output field holding the child array on the looked-up entity. */
+  readonly name: string;
+  /** Section heading (defaults to the field name). */
+  readonly heading?: string;
+  /** Render kind for the array (`list` or `table`; defaults to `list`). */
+  readonly kind?: "list" | "table";
+  /** Relation from the entity to each child node — prefixed name, IRI, or path. */
+  readonly relation: string;
+  /** Explicit GraphQL field name (escape hatch). Ignored on the SPARQL path. */
+  readonly graphqlField?: string;
+  /**
+   * Fields to read from each child node. On `source: "graphql"` lookups an
+   * entry may instead be one {@link PackNestedExpand} level.
+   */
+  readonly select: readonly PackExpandSelect[];
+  /** Render the section even when the array is empty (default: false). */
+  readonly showWhenEmpty?: boolean;
+  /** Minimum canonical disclosure level at which this expand is fetched. */
+  readonly level?: string;
+}
+
+/**
+ * Progressive-disclosure capability for a lookup. Declares an ordered subset of
+ * the canonical levels (the first is the base/default, always shown); the
+ * compiler derives a `--detail`/`detail` selector and gates fields/expands by
+ * canonical index.
+ */
+export interface PackDisclosure {
+  /** Ordered canonical level names (`⊆ constants.DETAIL_LEVELS`). */
+  readonly levels: readonly string[];
+  /** Default level when none is requested (must be one of `levels`). */
+  readonly default?: string;
+}
+
+/**
+ * A declarative list filter: a CLI/MCP parameter constraining one SELECT
+ * variable. Filters are row predicates applied AFTER the author query runs — the
+ * query text is never modified, so filter input cannot inject SPARQL.
+ */
+export interface PackFilter {
+  /** Parameter name — a single lowercase word (`--param` / MCP key). */
+  readonly param: string;
+  /** SELECT variable the filter constrains (without `?`). */
+  readonly variable: string;
+  /**
+   * Allowed values; anything else is rejected with INVALID_INPUT and the set
+   * projects to an enum. Omitted when the value set is data-driven (a free
+   * string matched case-insensitively against the variable).
+   */
+  readonly values?: readonly string[];
+  /** Help text (defaults to a generated description). */
+  readonly description?: string;
+}
+
+/**
+ * Free-text search over list rows: a `--search` string keeping a row when ANY
+ * named SELECT variable contains the term (case-insensitive substring). Applied
+ * after the author query, so input never touches the query text.
+ */
+export interface PackSearch {
+  /** SELECT variables searched (without `?`). */
+  readonly variables: readonly string[];
+  /** Help text (defaults to a generated description). */
+  readonly description?: string;
+}
+
+/** Opt-in empty-result recovery for a list story. */
+export interface PackEmptyRecovery {
+  /** Human-readable cause + fix (e.g. which packages provide the data). */
+  readonly message: string;
+  /** Runnable pragma command fixing the emptiness (rendered on the CLI). */
+  readonly cli?: string;
+}
+
+/** The list half of a pack (always SPARQL-sourced). */
+export interface PackList {
+  /** SPARQL SELECT producing one row per item. */
+  readonly query: string;
+  /** Columns to render, referencing SELECT variables. */
+  readonly columns: readonly PackColumn[];
+  /** Declarative filters projected to CLI flags and MCP parameters. */
+  readonly filters?: readonly PackFilter[];
+  /** Free-text search projected to a `--search` flag / `search` parameter. */
+  readonly search?: PackSearch;
+  /** Opt-in empty-result recovery (typed EMPTY_RESULTS instead of an empty list). */
+  readonly emptyRecovery?: PackEmptyRecovery;
+}
+
+/**
+ * An additional list-shaped verb: `<noun> <verb>` compiled through the SAME
+ * machinery as `list` (e.g. standard's `categories`). May not collide with the
+ * compiled `list`/`lookup`/`sample` verbs.
+ */
+export interface PackVerb extends PackList {
+  /** Verb name (kebab-case), e.g. `"categories"`. */
+  readonly verb: string;
+  /** CLI description for the command. */
+  readonly description?: string;
+  /** MCP tool description (defaults to the CLI description). */
+  readonly toolDescription?: string;
+}
+
+/**
+ * The sample capability: `<noun> sample [count]` returns 1–5 randomly selected
+ * complete entities (resolved through the lookup path at the HIGHEST level).
+ */
+export interface PackSample {
+  /** Default sample count when none is requested (1–5; default 2). */
+  readonly count?: number;
+  /**
+   * Omit the `[count]` positional — the sample always returns {@link count}
+   * (default 2) entries. Used where the covenant freezes a no-argument sample
+   * (`block`/`modifier`/`token`); `standard` keeps the `[count]` positional.
+   */
+  readonly fixedCount?: boolean;
+  /** CLI description for the command. */
+  readonly description?: string;
+  /** MCP tool description (defaults to the CLI description). */
+  readonly toolDescription?: string;
+}
+
+/**
+ * Per-family autocomplete override for a lookup's `<name>` positional. Name
+ * completion is DERIVED-BY-DEFAULT from the family's index type; this tunes or
+ * opts out of it. Absent means "completion on, engine defaults".
+ */
+export interface PackCompletion {
+  /** `false` opts the family out of name completion (default: on). */
+  readonly enabled?: boolean;
+  /** Match strategy against the partial (default: substring). */
+  readonly match?: "prefix" | "substring" | "fuzzy";
+  /** Minimum typed chars before the shell execs completion (default: global). */
+  readonly minChars?: number;
+}
+
+/**
+ * The lookup half of a pack. The query is generated from `by` and `type`/`types`
+ * — user-supplied names are escaped by the generator, never interpolated by the
+ * author. The `source` selects the field-fetch strategy; the name→URI resolve is
+ * ALWAYS generated SPARQL regardless of source (an implementation detail, not a
+ * second declared source).
+ */
+export interface PackLookup {
+  /**
+   * Field-fetch strategy (default `"sparql"`). `"graphql"` keeps the SPARQL
+   * name→URI resolve, then fetches all fields/sections/expands in ONE generated
+   * document executed in-process against the compiled schema. Both sources
+   * unwrap to the same flat {@link PackEntity} shape.
+   */
+  readonly source?: "sparql" | "graphql";
+  /** Property whose value names the entity — prefixed name or IRI. */
+  readonly by: string;
+  /** Optional single class constraint — prefixed name or IRI. */
+  readonly type?: string;
+  /** CLI description for the lookup command (defaults to a generated one). */
+  readonly description?: string;
+  /** MCP tool description for the lookup verb (authored one-liner). */
+  readonly toolDescription?: string;
+  /**
+   * Class constraints when entities span several classes — projected as a SPARQL
+   * VALUES constraint on the name resolve. Mutually exclusive with `type`.
+   */
+  readonly types?: readonly string[];
+  /**
+   * GraphQL type or interface the generated document's inline fragment targets
+   * (`source: "graphql"` only). Defaults to the local name of `type`; required
+   * when `types` is used (an interface covering all of them, e.g. `"UIBlock"`).
+   */
+  readonly graphqlType?: string;
+  /** Inline fields shown under the entity title. */
+  readonly fields?: readonly PackField[];
+  /** Long-form sections shown after the fields. */
+  readonly sections?: readonly PackSection[];
+  /** Multi-valued nested projections (structured sections). */
+  readonly expand?: readonly PackExpand[];
+  /** Progressive-disclosure levels; enables the derived `--detail` flag. */
+  readonly disclosure?: PackDisclosure;
+  /** Sample capability: `true` for defaults, or a configured sample. */
+  readonly sample?: true | PackSample;
+  /** Autocomplete override for the `<name>` positional (derive-by-default). */
+  readonly completion?: PackCompletion;
+}
+
+/** A pack list row / flat lookup base: variable name → string value. */
+export type PackRow = Record<string, string>;
+
+/**
+ * A child record under an expand. Scalar values come from child fields; a nested
+ * expand contributes either a collapsed string array (single-field select) or
+ * one small record per grandchild.
+ */
+export type PackChildRow = Record<
+  string,
+  string | readonly string[] | readonly PackRow[]
+>;
+
+/**
+ * A looked-up pack entity: flat string values plus any expanded child arrays.
+ * Both fetch sources resolve to this same shape, so rendering, `--format json`,
+ * and the MCP envelope are identical downstream regardless of the fetch layer.
+ */
+export type PackEntity = Record<string, string | readonly PackChildRow[]>;
+
+/** One declarative read story: a noun with its preferred queries. */
+export interface PackDefinition {
+  /** Command noun (kebab-case), e.g. `"standard"` → `pragma standard list`. */
+  readonly noun: string;
+  /** CLI description for the list command. */
+  readonly description?: string;
+  /** MCP tool description (defaults to the CLI description). */
+  readonly toolDescription?: string;
+  /**
+   * The list story. Optional so a pack can serve only the lookup verb of a noun
+   * whose list stays hand-written (e.g. `block`). At least one of `list`/`lookup`
+   * must be declared.
+   */
+  readonly list?: PackList;
+  /** Additional list-shaped verbs beyond `list` (e.g. `categories`). */
+  readonly verbs?: readonly PackVerb[];
+  /** The lookup story. */
+  readonly lookup?: PackLookup;
+  /**
+   * Markdown narrating how this pack's domain is made — its ontology/graph
+   * story. Data, like the queries. Surfaced storelessly (off the effective
+   * modules) by `pragma colophon`, after pragma's own built-in colophon.
+   */
+  readonly colophon?: string;
+}
+
+/** A validated pack definition paired with where it was declared. */
+export interface PackEntry {
+  /** Where the definition was declared (config path, package file, or bundled). */
+  readonly source: string;
+  readonly definition: PackDefinition;
+}

package/src/kernel/packs/uniqueness.ts

@@ -0,0 +1,35 @@
+/**
+ * Plain `(noun, verb)` uniqueness across compiled verbs.
+ *
+ * Replaces the old reserved-verb / derive-reserved machinery: every verb the
+ * projectors see — authored, bundled-pack, or dynamic-pack — must own a distinct
+ * `(noun, verb)` key. Precedence (config > package > bundled) is resolved by
+ * NOUN before this runs, so a surviving collision here is a real conflict (a
+ * dynamic pack claiming an authored noun's verb), reported with both sources.
+ */
+
+import type { VerbSpec } from "../spec/types.js";
+
+/** The `(noun, verb)` key for a verb path (`["standard","list"]` → `standard list`). */
+export function verbKey(path: readonly [string, string?]): string {
+  return path[1] ? `${path[0]} ${path[1]}` : path[0];
+}
+
+/**
+ * Assert that no two verbs share a `(noun, verb)` key.
+ *
+ * @param verbs - Every verb the projectors will see.
+ * @throws Error naming the colliding key on the first duplicate.
+ */
+export function assertUniqueVerbs(verbs: readonly VerbSpec[]): void {
+  const seen = new Set<string>();
+  for (const verb of verbs) {
+    const key = verbKey(verb.path);
+    if (seen.has(key)) {
+      throw new Error(
+        `duplicate command "${key}" — two capabilities claim it.`,
+      );
+    }
+    seen.add(key);
+  }
+}