@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/kernel/error/renderError.ts

@@ -0,0 +1,101 @@
+/**
+ * Render a {@link PragmaError} for each output surface.
+ *
+ * Plain text targets a human terminal (stderr), condensed Markdown targets an
+ * agent reading `--format llm`, and JSON emits the `{ ok: false, error }` envelope —
+ * the same failure shape the MCP projector returns, so agents see one contract
+ * whichever transport they use.
+ */
+
+import type { PragmaError } from "./PragmaError.js";
+import { serializeError } from "./serialize.js";
+
+/**
+ * Render a {@link PragmaError} as human-readable plain text for the terminal.
+ *
+ * @param error - The structured error to render.
+ * @returns Multi-line plain text string.
+ */
+function renderErrorPlain(error: PragmaError): string {
+  const lines: string[] = [`Error: ${error.message}`];
+
+  if (error.suggestions.length > 0) {
+    lines.push("", "Did you mean?");
+    for (const suggestion of error.suggestions) {
+      lines.push(`  - ${suggestion}`);
+    }
+  }
+
+  if (error.filters) {
+    lines.push("", "Active filters:");
+    for (const [key, value] of Object.entries(error.filters)) {
+      lines.push(`  ${key}: ${value}`);
+    }
+  }
+
+  if (error.validOptions && error.validOptions.length > 0) {
+    lines.push("", `Valid options: ${error.validOptions.join(", ")}`);
+  }
+
+  if (error.recovery) {
+    lines.push("");
+    // Keep the human guidance AND the runnable command — dropping the message
+    // when a `cli` is present loses the WHY (e.g. "Build the local store …").
+    lines.push(
+      error.recovery.cli
+        ? `${error.recovery.message} Run \`${error.recovery.cli}\``
+        : error.recovery.message,
+    );
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Render a {@link PragmaError} as condensed Markdown for agent consumption.
+ *
+ * @param error - The structured error to render.
+ * @returns Markdown-formatted string.
+ */
+function renderErrorLlm(error: PragmaError): string {
+  const lines: string[] = [`## Error: ${error.code}`, error.message];
+
+  if (error.suggestions.length > 0) {
+    lines.push(`Suggestions: ${error.suggestions.join(", ")}`);
+  }
+
+  if (error.filters) {
+    const filterParts = Object.entries(error.filters)
+      .map(([key, value]) => `${key}=${value}`)
+      .join(", ");
+    lines.push(`Filters: ${filterParts}`);
+  }
+
+  if (error.validOptions && error.validOptions.length > 0) {
+    lines.push(`Valid options: ${error.validOptions.join(", ")}`);
+  }
+
+  if (error.recovery) {
+    // Keep both the guidance and the runnable command (message was dropped when
+    // a `cli` was present).
+    lines.push(
+      error.recovery.cli
+        ? `Recovery: ${error.recovery.message} \`${error.recovery.cli}\``
+        : `Recovery: ${error.recovery.message}`,
+    );
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Render a {@link PragmaError} as the `{ ok: false, error }` JSON envelope.
+ *
+ * @param error - The structured error to render.
+ * @returns Serialized failure envelope, identical to the MCP error envelope.
+ */
+function renderErrorJson(error: PragmaError): string {
+  return JSON.stringify({ ok: false, error: serializeError(error) });
+}
+
+export { renderErrorJson, renderErrorLlm, renderErrorPlain };

package/src/kernel/error/serialize.ts

@@ -0,0 +1,28 @@
+/**
+ * Serialize a {@link PragmaError} into the covenant's error payload.
+ *
+ * The payload is the `error` field of the `{ ok: false, error }` envelope and
+ * is shared verbatim by the CLI (`--format json`) and MCP projectors, so both
+ * emit byte-identical error output. Optional fields are omitted rather than set
+ * to `undefined`, keeping the JSON minimal and stable.
+ */
+
+import type { PragmaError } from "./PragmaError.js";
+import type { ErrorPayload } from "./types.js";
+
+/**
+ * Project a {@link PragmaError} onto the frozen {@link ErrorPayload} shape.
+ *
+ * @param error - The structured error to serialize.
+ * @returns The payload embedded under `error` in the failure envelope.
+ */
+export function serializeError(error: PragmaError): ErrorPayload {
+  return {
+    code: error.code,
+    message: error.message,
+    ...(error.suggestions.length > 0 && { suggestions: error.suggestions }),
+    ...(error.recovery && { recovery: error.recovery }),
+    ...(error.validOptions && { validOptions: error.validOptions }),
+    ...(error.filters && { filters: error.filters }),
+  };
+}

package/src/kernel/error/types.ts

@@ -0,0 +1,62 @@
+/**
+ * Error type definitions for the pragma error system.
+ *
+ * Separated from the {@link PragmaError} class so consumers that only need the
+ * shapes (renderers, the MCP envelope, the exit-code mapper) can import types
+ * without pulling in the class or its factories.
+ */
+
+import type { ERROR_CODES } from "./constants.js";
+
+/** Union of all recognized error code literals. */
+type ErrorCode = (typeof ERROR_CODES)[number];
+
+/**
+ * Structured recovery hint attached to a {@link PragmaError}.
+ *
+ * `cli` — when present — is the exact command the user can run to recover; it
+ * always begins with the literal `pragma ` prefix (D5), enforced by
+ * {@link assertRecoveryCli}.
+ */
+interface Recovery {
+  /** Human-readable recovery guidance. */
+  message: string;
+  /** CLI command the user can run to recover (starts with `pragma `). */
+  cli?: string;
+  /** MCP tool invocation an agent can call to recover. */
+  mcp?: { tool: string; params?: Record<string, unknown> };
+}
+
+/** Raw data payload used to construct a {@link PragmaError}. */
+interface PragmaErrorData {
+  /** Machine-readable error classification. */
+  code: ErrorCode;
+  /** Human-readable error message. */
+  message: string;
+  /** Entity that triggered the error, if applicable. */
+  entity?: { type: string; name: string };
+  /** Fuzzy-matched alternative names. */
+  suggestions?: string[];
+  /** Recovery hint for CLI and MCP adapters. */
+  recovery?: Recovery;
+  /** Active filters at the time of the error. */
+  filters?: Record<string, string>;
+  /** Enumerated valid options when input was rejected. */
+  validOptions?: string[];
+}
+
+/**
+ * The serialized error payload embedded in the `{ ok: false, error }`
+ * envelope — the exact shape the surface covenant freezes. Optional fields
+ * are omitted (never `undefined`) so CLI-JSON and MCP output are byte-equal.
+ */
+interface ErrorPayload {
+  readonly code: ErrorCode;
+  readonly message: string;
+  readonly suggestions?: readonly string[];
+  readonly recovery?: Recovery;
+  readonly validOptions?: readonly string[];
+  readonly filters?: Record<string, string>;
+}
+
+export type { ErrorCode, ErrorPayload, PragmaErrorData, Recovery };

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

@@ -0,0 +1,138 @@
+/**
+ * Dynamic pack precedence + uniqueness (PROTECTED).
+ *
+ * Default config ⇒ effective == static (the golden holds, no config read cost on
+ * the fast path). A config story overrides a bundled-pack noun or introduces a
+ * new one; a story claiming a non-pack authored noun, a duplicate noun, or any
+ * surviving `(noun, verb)` collision is rejected.
+ */
+
+import { describe, expect, it } from "vitest";
+import type { ConfigLayers } from "../config/types.js";
+import type { CapabilityModule, VerbSpec } from "../spec/types.js";
+import { assembleEffectiveModules } from "./collect.js";
+import { assertUniqueVerbs } from "./uniqueness.js";
+
+/** A trivial storeless verb for a fake authored module. */
+function fakeVerb(noun: string, verb?: string): VerbSpec {
+  return {
+    path: verb ? [noun, verb] : [noun],
+    summary: `${noun} ${verb ?? ""}`.trim(),
+    params: [],
+    output: {
+      formatters: { plain: () => "", llm: () => "", json: () => "{}" },
+    },
+    capability: {
+      needsStore: false,
+      mutates: false,
+      mcp: { expose: false, reason: "fake" },
+    },
+    run: async () => ({}),
+  };
+}
+
+const STATIC: CapabilityModule[] = [
+  { name: "config", verbs: [fakeVerb("config", "show")] },
+  { name: "standard", verbs: [fakeVerb("standard", "list")] },
+];
+
+function layers(stories: unknown[]): ConfigLayers {
+  return {
+    config: { channel: "normal", stories },
+    origins: {
+      tier: "default",
+      channel: "default",
+      detail: "default",
+      packages: "default",
+      stories: stories.length > 0 ? "project" : "default",
+      prefixes: "default",
+      prompts: "default",
+    },
+    global: { path: "", exists: false },
+    project: { exists: false },
+  };
+}
+
+const validPack = (noun: string) => ({
+  noun,
+  list: {
+    query: "SELECT ?uri WHERE { ?uri a ex:Thing }",
+    columns: [{ field: "uri" }],
+  },
+});
+
+describe("assembleEffectiveModules (PROTECTED)", () => {
+  it("default config (no stories) returns the static modules unchanged", () => {
+    expect(assembleEffectiveModules(STATIC, layers([]))).toBe(STATIC);
+  });
+
+  it("a config story overrides a bundled-pack noun", () => {
+    const effective = assembleEffectiveModules(
+      STATIC,
+      layers([validPack("standard")]),
+    );
+    const standard = effective.find((m) => m.name === "standard");
+    // The bundled `standard` module was replaced by the config pack (source
+    // "config"); it still owns exactly `standard list`.
+    expect(standard?.verbs.map((v) => v.path.join(" "))).toEqual([
+      "standard list",
+    ]);
+    expect(effective.filter((m) => m.name === "standard")).toHaveLength(1);
+  });
+
+  it("a config story introduces a new noun", () => {
+    const effective = assembleEffectiveModules(
+      STATIC,
+      layers([validPack("recipe")]),
+    );
+    expect(effective.map((m) => m.name).sort()).toEqual([
+      "config",
+      "recipe",
+      "standard",
+    ]);
+  });
+
+  it("carries a config story's colophon onto its module (for `pragma colophon`)", () => {
+    const effective = assembleEffectiveModules(
+      STATIC,
+      layers([{ ...validPack("recipe"), colophon: "How recipes are made." }]),
+    );
+    const recipe = effective.find((m) => m.name === "recipe");
+    expect(recipe?.colophon).toBe("How recipes are made.");
+    // A story without a colophon carries `undefined` (the field is optional).
+    const plain = assembleEffectiveModules(STATIC, layers([validPack("stew")]));
+    expect(plain.find((m) => m.name === "stew")?.colophon).toBeUndefined();
+  });
+
+  it("rejects a story claiming a non-pack authored noun", () => {
+    expect(() =>
+      assembleEffectiveModules(STATIC, layers([validPack("config")])),
+    ).toThrow(/built-in command/);
+  });
+
+  it("rejects a duplicate story noun", () => {
+    expect(() =>
+      assembleEffectiveModules(
+        STATIC,
+        layers([validPack("recipe"), validPack("recipe")]),
+      ),
+    ).toThrow(/Duplicate/);
+  });
+
+  it("rejects an invalid story pack (via the zod validator)", () => {
+    expect(() =>
+      assembleEffectiveModules(STATIC, layers([{ noun: "Bad Noun" }])),
+    ).toThrow(/Invalid story/);
+  });
+});
+
+describe("assertUniqueVerbs (PROTECTED)", () => {
+  it("passes disjoint verbs and catches a collision", () => {
+    expect(() =>
+      assertUniqueVerbs([fakeVerb("a", "list"), fakeVerb("b", "list")]),
+    ).not.toThrow();
+    expect(() =>
+      assertUniqueVerbs([fakeVerb("a", "list"), fakeVerb("a", "list")]),
+    ).toThrow(/duplicate command "a list"/);
+  });
+});

package/src/kernel/packs/collect.ts

@@ -0,0 +1,108 @@
+/**
+ * Assemble the EFFECTIVE capability modules at dispatch.
+ *
+ * The `--help`/`__complete` fast paths use the STATIC capabilities (bundled +
+ * authored) only. When a real command runs and the project config declares
+ * `stories`, this merges them in: a config story overrides a bundled-pack noun
+ * (replacing that module) or introduces a new noun; a config story that claims a
+ * non-pack authored noun (config, ontology, …) is a hard error, and any
+ * surviving `(noun, verb)` collision is caught by uniqueness.
+ *
+ * Precedence is config > package > bundled. Package-shipped stories are a future
+ * source (the new kernel does not yet discover package `stories/*.json`); the
+ * seam is here so wiring them later is additive.
+ *
+ * zod is reached only through {@link parsePackDefinition} (lazy) — this module
+ * is imported at dispatch, never on the fast path, so validating config stories
+ * costs nothing on `--help`/`__complete`.
+ */
+
+import type { ConfigLayers } from "../config/types.js";
+import { PragmaError } from "../error/PragmaError.js";
+import type { CapabilityModule } from "../spec/types.js";
+import { compilePack } from "./compile.js";
+import { parsePackDefinition } from "./schema.js";
+import type { PackDefinition } from "./types.js";
+import { assertUniqueVerbs } from "./uniqueness.js";
+
+/** The bundled-pack nouns a config/package story may override. */
+export const BUNDLED_PACK_NOUNS: readonly string[] = [
+  "standard",
+  "tier",
+  "modifier",
+  "token",
+  "block",
+];
+
+/**
+ * Merge dynamic (config-declared) story packs into the static capabilities.
+ *
+ * @param staticModules - The static capabilities (bundled + authored).
+ * @param layers - The resolved config layers (its `config.stories`, `prefixes`).
+ * @returns The effective modules, uniqueness-checked.
+ * @throws PragmaError CONFIG_ERROR on an invalid story, a story claiming a
+ *   non-pack authored noun, or a duplicate story noun.
+ */
+export function assembleEffectiveModules(
+  staticModules: readonly CapabilityModule[],
+  layers: ConfigLayers,
+): readonly CapabilityModule[] {
+  const stories = layers.config.stories ?? [];
+  if (stories.length === 0) return staticModules;
+
+  const prefixes = layers.config.prefixes ?? {};
+  const overridable = new Set(BUNDLED_PACK_NOUNS);
+  const staticNouns = new Set(staticModules.map((module) => module.name));
+
+  const seen = new Set<string>();
+  const dynamic: CapabilityModule[] = [];
+  for (const raw of stories) {
+    const definition: PackDefinition = parsePackDefinition(raw, "config");
+    if (seen.has(definition.noun)) {
+      throw PragmaError.configError(
+        `Duplicate story noun "${definition.noun}" in config.`,
+      );
+    }
+    if (staticNouns.has(definition.noun) && !overridable.has(definition.noun)) {
+      throw PragmaError.configError(
+        `Story noun "${definition.noun}" collides with a built-in command.`,
+      );
+    }
+    seen.add(definition.noun);
+    dynamic.push({
+      name: definition.noun,
+      verbs: compilePack(definition, "config", prefixes),
+      colophon: definition.colophon,
+    });
+  }
+
+  // Drop the bundled module for any noun a config story overrides, then append
+  // the dynamic modules.
+  const kept = staticModules.filter((module) => !seen.has(module.name));
+  const effective = [...kept, ...dynamic];
+  assertUniqueVerbs(effective.flatMap((module) => [...module.verbs]));
+  return effective;
+}
+
+/**
+ * Load the effective modules for a real invocation: read the layered config and
+ * merge its story packs into the static capabilities.
+ *
+ * Reached only at DISPATCH (real command / MCP serve), never on the
+ * `--help`/`__complete` fast path, so the config read and zod validation never
+ * cost the storeless paths. The config reader is dynamic-imported to keep even
+ * this module's static graph free of it.
+ *
+ * @param staticModules - The static capabilities (bundled + authored).
+ * @param cwd - The directory to resolve project config against.
+ * @returns The effective modules (static when no config stories are declared).
+ * @note Impure — reads the project/global config.
+ */
+export async function loadEffectiveModules(
+  staticModules: readonly CapabilityModule[],
+  cwd: string,
+): Promise<readonly CapabilityModule[]> {
+  const { readConfig } = await import("../config/readConfig.js");
+  const layers = await readConfig(cwd);
+  return assembleEffectiveModules(staticModules, layers);
+}

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

@@ -0,0 +1,229 @@
+/**
+ * Compiler invariants (PROTECTED) — the single pack compiler.
+ *
+ * Closes fork F3: one grammar, one compiler. Asserts the round-trip
+ * (validate∘serialize is identity), the projected verb shapes and
+ * `(noun, verb)` uniqueness (storeless), and the SPARQL fetch path end to end
+ * against a fixture store (list filter/search, lookup by name, sample).
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
+import type { PragmaRuntime } from "../runtime/types.js";
+import { compilePack } from "./compile.js";
+import type { LookupOutput } from "./resolveEntity.js";
+import { parsePackDefinition } from "./schema.js";
+import type { PackDefinition, PackRow } from "./types.js";
+import { assertUniqueVerbs, verbKey } from "./uniqueness.js";
+
+const PREFIXES = {
+  ex: "https://example.org/widgets#",
+  owl: "http://www.w3.org/2002/07/owl#",
+  rdfs: "http://www.w3.org/2000/01/rdf-schema#",
+  xsd: "http://www.w3.org/2001/XMLSchema#",
+};
+
+const TTL = `
+@prefix ex: <https://example.org/widgets#> .
+@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:Widget a owl:Class .
+ex:name a owl:DatatypeProperty ; rdfs:domain ex:Widget ; rdfs:range xsd:string .
+ex:kind a owl:DatatypeProperty ; rdfs:domain ex:Widget ; rdfs:range xsd:string .
+ex:description a owl:DatatypeProperty ; rdfs:domain ex:Widget ; rdfs:range xsd:string .
+ex:hasPart a owl:ObjectProperty ; rdfs:domain ex:Widget ; rdfs:range ex:Widget .
+
+ex:button a ex:Widget ; ex:name "Button" ; ex:kind "input" ;
+  ex:description "A button." ; ex:hasPart ex:label .
+ex:label a ex:Widget ; ex:name "Label" ; ex:kind "display" ;
+  ex:description "A label." .
+`;
+
+/** A SPARQL-sourced fixture pack exercising list, filter, search, lookup, sample. */
+const WIDGET_PACK: PackDefinition = {
+  noun: "widget",
+  description: "List widgets.",
+  list: {
+    query: [
+      "SELECT ?uri ?name ?kind WHERE {",
+      "  ?uri a ex:Widget ; ex:name ?name .",
+      "  OPTIONAL { ?uri ex:kind ?kind }",
+      "} ORDER BY ?name",
+    ].join("\n"),
+    columns: [
+      { field: "uri", label: "IRI" },
+      { field: "name", label: "Name" },
+      { field: "kind", label: "Kind" },
+    ],
+    filters: [
+      { param: "kind", variable: "kind", values: ["input", "display"] },
+    ],
+    search: { variables: ["name"] },
+  },
+  lookup: {
+    source: "sparql",
+    by: "ex:name",
+    type: "ex:Widget",
+    fields: [
+      { name: "description", property: "ex:description", level: "standard" },
+    ],
+    expand: [
+      {
+        name: "parts",
+        heading: "Parts",
+        relation: "ex:hasPart",
+        level: "detailed",
+        select: [{ name: "name", property: "ex:name" }],
+      },
+    ],
+    disclosure: {
+      levels: ["summary", "standard", "detailed"],
+      default: "summary",
+    },
+    sample: true,
+  },
+};
+
+describe("pack compiler — round-trip + shape (PROTECTED, storeless)", () => {
+  it("validate∘serialize is identity (JSON round-trips to the same pack)", () => {
+    const raw: unknown = JSON.parse(JSON.stringify(WIDGET_PACK));
+    expect(parsePackDefinition(raw, "test:widget")).toEqual(WIDGET_PACK);
+  });
+
+  it("projects list, lookup, and sample verbs with unique keys", () => {
+    const verbs = compilePack(WIDGET_PACK, "bundled:widget", PREFIXES);
+    expect(verbs.map((v) => verbKey(v.path))).toEqual([
+      "widget list",
+      "widget lookup",
+      "widget sample",
+    ]);
+    expect(() => assertUniqueVerbs(verbs)).not.toThrow();
+  });
+
+  it("projects list filters as params (enum) + a search flag", () => {
+    const [list] = compilePack(WIDGET_PACK, "bundled:widget", PREFIXES);
+    expect(list?.params.map((p) => p.name)).toEqual(["kind", "search"]);
+    const kind = list?.params.find((p) => p.name === "kind");
+    expect(kind?.kind).toBe("enum");
+    expect(list?.capability.needsStore).toBe(true);
+    expect(list?.capability.mcp.expose).toBe(true);
+  });
+
+  it("projects the lookup as a variadic name-completing positional + disclosure", () => {
+    const verbs = compilePack(WIDGET_PACK, "bundled:widget", PREFIXES);
+    const lookup = verbs.find((v) => verbKey(v.path) === "widget lookup");
+    const name = lookup?.params.at(0);
+    expect(name?.kind).toBe("string[]");
+    expect(name?.positional).toBe(true);
+    expect(name?.complete).toEqual({
+      kind: "names",
+      source: { from: "index", type: "ex:Widget" },
+    });
+    expect(lookup?.disclosure).toEqual({
+      levels: ["summary", "standard", "detailed"],
+      default: "summary",
+    });
+  });
+
+  it("honors the pack completion override (opt-out + tune)", () => {
+    const baseLookup = WIDGET_PACK.lookup as NonNullable<
+      PackDefinition["lookup"]
+    >;
+    const nameParam = (def: PackDefinition) =>
+      compilePack(def, "bundled:widget", PREFIXES)
+        .find((v) => verbKey(v.path) === "widget lookup")
+        ?.params.at(0);
+
+    // enabled:false opts the family out of completion entirely.
+    expect(
+      nameParam({
+        ...WIDGET_PACK,
+        lookup: { ...baseLookup, completion: { enabled: false } },
+      })?.complete,
+    ).toBeUndefined();
+
+    // match/minChars tune the derived index heuristic.
+    expect(
+      nameParam({
+        ...WIDGET_PACK,
+        lookup: {
+          ...baseLookup,
+          completion: { match: "prefix", minChars: 3 },
+        },
+      })?.complete,
+    ).toEqual({
+      kind: "names",
+      source: { from: "index", type: "ex:Widget" },
+      match: "prefix",
+      minChars: 3,
+    });
+  });
+});
+
+describe("pack compiler — SPARQL fetch path (PROTECTED)", () => {
+  let rt: PragmaRuntime;
+
+  beforeAll(async () => {
+    ({ rt } = await buildFixtureRuntime({
+      ttl: TTL,
+      prefixes: PREFIXES,
+      detail: "detailed",
+    }));
+  });
+
+  afterAll(async () => {
+    (await rt.store.get()).store.dispose();
+  });
+
+  const run = <R>(verbLabel: string, params: Record<string, unknown>) => {
+    const verb = compilePack(WIDGET_PACK, "bundled:widget", PREFIXES).find(
+      (v) => verbKey(v.path) === `widget ${verbLabel}`,
+    );
+    if (!verb) throw new Error(`no widget ${verbLabel}`);
+    return verb.run(params, rt) as Promise<R>;
+  };
+
+  it("lists rows in the uniform pack shape", async () => {
+    const rows = await run<PackRow[]>("list", {});
+    expect(rows.map((r) => r.name)).toEqual(["Button", "Label"]);
+    expect(rows[0]?.uri).toBe("https://example.org/widgets#button");
+  });
+
+  it("filters by an enum value (post-query row predicate)", async () => {
+    const rows = await run<PackRow[]>("list", { kind: "input" });
+    expect(rows.map((r) => r.name)).toEqual(["Button"]);
+  });
+
+  it("searches case-insensitively", async () => {
+    const rows = await run<PackRow[]>("list", { search: "lab" });
+    expect(rows.map((r) => r.name)).toEqual(["Label"]);
+  });
+
+  it("looks up an entity by name with its fields and expands (detailed)", async () => {
+    const output = await run<LookupOutput>("lookup", { name: ["Button"] });
+    expect(output.errors).toEqual([]);
+    const entity = output.results.at(0);
+    expect(entity?.name).toBe("Button");
+    expect(entity?.description).toBe("A button.");
+    expect(entity?.parts).toEqual([{ name: "Label" }]);
+  });
+
+  it("resolves a name case-insensitively and reports misses with suggestions", async () => {
+    const hit = await run<LookupOutput>("lookup", { name: ["bUTTON"] });
+    expect(hit.results.at(0)?.name).toBe("Button");
+    await expect(
+      run<LookupOutput>("lookup", { name: ["Buton"] }),
+    ).rejects.toThrow(/not found/i);
+  });
+
+  it("samples N full exemplars with the population size", async () => {
+    const data = await run<{ samples: PackRow[]; totalCount: number }>(
+      "sample",
+      { count: "2" },
+    );
+    expect(data.samples).toHaveLength(2);
+    expect(data.totalCount).toBe(2);
+  });
+});