@intentius/chant 0.124.45 → 0.124.46

package/src/workspace/capabilities-contract.test.ts

@@ -0,0 +1,88 @@
+/**
+ * The `capabilities` document of the read contract (#4375): its schema, the
+ * document `chant search --capabilities --json` prints, and its failure.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { contract, validSchema } from "./__fixtures__/contract-repo";
+import { READ_CONTRACT_FLOOR, READ_CONTRACT_VERSION, REASONS } from "./reason-codes";
+import { CAPABILITIES_OUTPUT_SCHEMA_ID, CAPABILITY_SUPPORT_CODES, capabilitiesDocument, capabilitiesFailure, formatCapabilities } from "./capabilities-contract";
+import { READ_CONTRACT_COMMANDS, READ_CONTRACT_SCHEMAS, MCP_READ_TOOLS, mcpToolCall } from "./conformance";
+import schema from "./capabilities.schema.json";
+
+const { expectValid } = contract(schema);
+
+/** The lexicons' mappings as they ship them, read as data: loading a lexicon's plugin takes seconds. */
+const LEXICONS = join(import.meta.dirname, "..", "..", "..", "..", "lexicons");
+const load = async (name: string) => {
+  if (name !== "aws" && name !== "terraform") throw new Error(`no lexicon ${name}`);
+  return { capabilityPack: { mapping: JSON.parse(readFileSync(join(LEXICONS, name, "src", "capabilities", "mapping.json"), "utf-8")) } };
+};
+
+describe("capabilities.schema.json", () => {
+  test("is a valid draft 2020-12 document at the contract version, naming the floor", () => {
+    expect(validSchema(schema)).toBe(true);
+    expect(schema.$id).toBe(CAPABILITIES_OUTPUT_SCHEMA_ID);
+    expect(schema.$id).toBe(`https://intentius.io/chant/schemas/workspace/capabilities/v${READ_CONTRACT_VERSION}/capabilities.schema.json`);
+    for (const branch of ["result", "failure"] as const) {
+      const props = (schema.$defs as Record<string, { properties: Record<string, unknown> }>)[branch].properties;
+      expect(props.contract).toEqual({ const: READ_CONTRACT_VERSION });
+      expect(props.$schema).toEqual({ const: schema.$id });
+    }
+    expect(schema.description).toContain(`chant ${READ_CONTRACT_FLOOR} and newer`);
+  });
+
+  test("names each support code in the closed list", () => {
+    for (const code of CAPABILITY_SUPPORT_CODES) expect(Object.keys(REASONS)).toContain(code);
+  });
+
+  test("is in the conformance suite as workspace search --capabilities, served by the capabilities MCP tool", () => {
+    expect(READ_CONTRACT_COMMANDS).toContain("search --capabilities");
+    expect(READ_CONTRACT_SCHEMAS["search --capabilities"]).toBe("capabilities.schema.json");
+    expect(MCP_READ_TOOLS["search --capabilities"]).toBe("capabilities");
+    expect(mcpToolCall(["workspace", "search", "--capabilities", "--json"])).toEqual({ name: "capabilities", arguments: {} });
+    expect(mcpToolCall(["workspace", "search", "app", "--capabilities", "--json"])).toBeUndefined();
+  });
+});
+
+describe("the document", () => {
+  test("lists the fifteen capabilities with a support statement for each lexicon asked about", async () => {
+    const doc = await capabilitiesDocument(["aws", "terraform", "no-such-lexicon"], load);
+    expectValid(doc);
+    expect(doc.contract).toBe(1);
+    expect(doc.capabilities).toHaveLength(16);
+    const reaches = doc.capabilities.find((c) => c.name === "reaches")!;
+    expect(reaches).toMatchObject({
+      shape: "edge",
+      search: "->[cap=reaches]",
+      depth: "declared",
+      params: [{ name: "action", optional: true }],
+      uses: ["can-assume", "grants"],
+      lexicons: {
+        aws: "supported",
+        terraform: "supported",
+        "no-such-lexicon": { code: "lexicon-not-loaded" },
+      },
+    });
+    expect(reaches.rule).toBe("reaches(r, x; action?) := r:Role ->{0,}can-assume ->grants($action) x");
+    expect(reaches.notEvaluated).toContain('Resource "*"');
+    expect(doc.helpers.map((h) => h.name)).toEqual(["in-sg", "ingress-of", "world-open", "allows", "denies", "pivot"]);
+    for (const c of doc.capabilities) {
+      expect(c.answers.length, c.name).toBeGreaterThan(0);
+      expect(c.search, c.name).toBe(c.shape === "set" ? `cap:${c.name}` : `->[cap=${c.name}]`);
+    }
+  });
+
+  test("prints as text, a line per capability with its parameters", async () => {
+    const lines = formatCapabilities(await capabilitiesDocument([], load));
+    expect(lines[0]).toMatch(/^cap:internet-facing +set +its subnet routes 0\.0\.0\.0\/0 to an internet gateway$/);
+    expect(lines).toContainEqual(expect.stringMatching(/^ +port\?: a port the open rule must cover, such as 22$/));
+    expect(lines.at(-1)).toBe("— 16 capabilities · --json prints each rule");
+  });
+
+  test("a refusal is a failure document with a code", async () => {
+    const doc = await capabilitiesFailure({ code: "usage-invalid", message: "m" });
+    expectValid(doc);
+  });
+});

package/src/workspace/capabilities-contract.ts

@@ -0,0 +1,132 @@
+/**
+ * The `capabilities` document of the read contract (#4375, ws-017): the
+ * capability catalog `chant search` answers `cap:` terms with, described by
+ * `capabilities.schema.json` beside this file.
+ *
+ * `chant search --capabilities --json` prints it for one project, with a
+ * support statement for each lexicon the project loads. `chant workspace
+ * search --capabilities --json` prints it from the workspace root's chant,
+ * for every lexicon a member loads (a terraform member's reader lexicon
+ * included, #4380): capability rules run once, under
+ * the workspace's chant, so the catalog is that chant's. chant's MCP
+ * `capabilities` tool returns whichever of the two applies where the server
+ * runs, unchanged.
+ */
+
+import { resolve } from "node:path";
+import type { ReasonCode } from "./reason-codes";
+import type { CapabilityEntry } from "../capabilities/catalog";
+
+/** The version of the `capabilities` document this chant writes. */
+export const CAPABILITIES_CONTRACT_VERSION = 1;
+
+/** `$id` of the JSON Schema for the document, shipped beside this file. */
+export const CAPABILITIES_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/capabilities/v1/capabilities.schema.json";
+
+/** Why no catalog was printed. */
+export const CAPABILITIES_ERROR_CODES = ["usage-invalid"] as const satisfies readonly ReasonCode[];
+export type CapabilitiesErrorCode = (typeof CAPABILITIES_ERROR_CODES)[number];
+
+/** Why a lexicon can't supply a capability. */
+export const CAPABILITY_SUPPORT_CODES = ["lexicon-has-no-mapping", "capability-not-derivable", "lexicon-not-loaded"] as const satisfies readonly ReasonCode[];
+
+interface CapabilitiesHead {
+  $schema: typeof CAPABILITIES_OUTPUT_SCHEMA_ID;
+  contract: typeof CAPABILITIES_CONTRACT_VERSION;
+  /** The chant that wrote the document. */
+  chant: string;
+}
+
+export interface CapabilitiesResult extends CapabilitiesHead {
+  capabilities: CapabilityEntry[];
+  helpers: { name: string; rule: string }[];
+}
+
+export interface CapabilitiesFailure extends CapabilitiesHead {
+  error: { code: CapabilitiesErrorCode; message: string; hint?: string };
+}
+
+export type CapabilitiesDocument = CapabilitiesResult | CapabilitiesFailure;
+
+async function head(): Promise<CapabilitiesHead> {
+  const { readChantPackageVersion } = await import("../package-version");
+  return { $schema: CAPABILITIES_OUTPUT_SCHEMA_ID, contract: CAPABILITIES_CONTRACT_VERSION, chant: readChantPackageVersion() };
+}
+
+/**
+ * The catalog, with a support statement for each lexicon named. Each is
+ * loaded on its own, so one that isn't installed is said to be, and the rest
+ * still read.
+ */
+export async function capabilitiesDocument(
+  lexicons: string[],
+  load?: (name: string) => Promise<{ capabilityPack?: { mapping: unknown } }>,
+): Promise<CapabilitiesResult> {
+  const loadPlugin = load ?? (await import("../cli/plugins")).loadPlugin;
+  const { capabilityCatalog } = await import("../capabilities/catalog");
+  const mappings: Record<string, Parameters<typeof capabilityCatalog>[0][string]> = {};
+  const notLoaded: string[] = [];
+  for (const name of [...new Set(lexicons)].sort()) {
+    try {
+      mappings[name] = (await loadPlugin(name)).capabilityPack?.mapping as (typeof mappings)[string];
+    } catch {
+      notLoaded.push(name);
+      mappings[name] = undefined;
+    }
+  }
+  const catalog = capabilityCatalog(mappings);
+  for (const c of catalog.capabilities) {
+    for (const name of notLoaded) {
+      c.lexicons[name] = { code: "lexicon-not-loaded", message: `the ${name} lexicon isn't installed where this chant runs, so its mapping wasn't read` };
+    }
+  }
+  return { ...(await head()), ...catalog };
+}
+
+export async function capabilitiesFailure(error: CapabilitiesFailure["error"]): Promise<CapabilitiesFailure> {
+  return { ...(await head()), error };
+}
+
+/**
+ * The lexicons the members of the workspace at `cwd` load, for its catalog:
+ * each chant member's own, and for a member of a package's kind, such as
+ * `terraform`, the lexicon its reader project declares (#4380).
+ */
+export async function workspaceLexicons(cwd: string): Promise<string[]> {
+  const { listWorkspace } = await import("./ls");
+  const { findWorkspaceRoot } = await import("../project-root");
+  const { resolveProjectLexicons } = await import("../cli/plugins");
+  const { loadKindRegistry } = await import("./kinds");
+  const located = findWorkspaceRoot(cwd);
+  const doc = listWorkspace({ cwd });
+  if (!located || "error" in doc) return [];
+  const out = new Set<string>();
+  const kinds = doc.members.some((m) => m.kind !== "chant" && m.readable) ? loadKindRegistry(doc.workspace.pins, located.dir).registry : undefined;
+  for (const m of doc.members) {
+    if (!m.readable) continue;
+    const reader = m.kind === "chant" ? undefined : kinds?.get(m.kind)?.graph?.lexicon;
+    if (reader) out.add(reader);
+    if (m.kind !== "chant") continue;
+    try {
+      for (const l of await resolveProjectLexicons(resolve(located.dir, m.dir))) out.add(l);
+    } catch {
+      // A member whose lexicons can't be resolved adds none; its own search says why.
+    }
+  }
+  return [...out];
+}
+
+/** The catalog as text: one capability per line, its search term and meaning, then its parameters. */
+export function formatCapabilities(doc: CapabilitiesResult): string[] {
+  const width = Math.max(...doc.capabilities.map((c) => c.search.length));
+  const lines: string[] = [];
+  for (const c of doc.capabilities) {
+    lines.push(`${c.search.padEnd(width)}  ${c.shape.padEnd(4)}  ${c.meaning}`);
+    for (const p of c.params) lines.push(`${"".padEnd(width)}        ${p.name}${p.optional ? "?" : ""}: ${p.meaning}`);
+    const unsupported = Object.entries(c.lexicons).filter(([, s]) => s !== "supported");
+    for (const [lex, s] of unsupported) lines.push(`${"".padEnd(width)}        not in ${lex}: ${(s as { message: string }).message}`);
+  }
+  const lexicons = Object.keys(doc.capabilities[0]?.lexicons ?? {});
+  lines.push(`— ${doc.capabilities.length} capabilities${lexicons.length ? ` · lexicons ${lexicons.join(", ")}` : ""} · --json prints each rule`);
+  return lines;
+}

package/src/workspace/capabilities.schema.json

@@ -0,0 +1,229 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/capabilities/v1/capabilities.schema.json",
+  "title": "chant capabilities catalog",
+  "description": "What `chant search --capabilities --json` prints (#4375): the capability catalog `chant search` answers `cap:` terms and `->[cap=...]` edges with, each capability's rule, and whether each lexicon the project loads can supply it. chant's MCP `capabilities` tool returns the same document. Version 1 of the read contract. Readers ignore fields they do not know; a field is only ever added within a version. The codes are a closed list, each in the one closed list of `reason-codes.ts`. Contract version 1 of this document is written by chant 0.124.46 and newer; the read contract as a whole by chant 0.81.0 and newer.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "type": "object",
+      "description": "Exit code 0.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "capabilities",
+        "helpers"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/capabilities/v1/capabilities.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": false,
+        "capabilities": {
+          "type": "array",
+          "description": "Every capability the catalog lists, in the order the rule file defines them.",
+          "items": {
+            "$ref": "#/$defs/capability"
+          }
+        },
+        "helpers": {
+          "type": "array",
+          "description": "Rules the capabilities use that the catalog does not list as capabilities of their own.",
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "rule"
+            ],
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "rule": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "capability": {
+      "type": "object",
+      "required": [
+        "name",
+        "meaning",
+        "shape",
+        "params",
+        "search",
+        "answers",
+        "depth",
+        "lexicons",
+        "notEvaluated",
+        "uses",
+        "rule"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "meaning": {
+          "type": "string",
+          "description": "What the capability says, in one line."
+        },
+        "shape": {
+          "enum": [
+            "set",
+            "edge"
+          ],
+          "description": "set: a set of nodes, tested with cap:<name>. edge: pairs of nodes, walked with ->[cap=<name>] or <-[cap=<name>]."
+        },
+        "params": {
+          "type": "array",
+          "description": "Arguments, in order: cap:<name>(<a>, <b>). An optional one left out drops the test that reads it.",
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "optional",
+              "meaning"
+            ],
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "optional": {
+                "type": "boolean"
+              },
+              "meaning": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "search": {
+          "type": "string",
+          "description": "The search term that asks for it: cap:<name> for a set, ->[cap=<name>] for an edge."
+        },
+        "answers": {
+          "type": "array",
+          "description": "Questions it serves, in people's words.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "depth": {
+          "enum": [
+            "declared",
+            "live",
+            "either"
+          ],
+          "description": "Which observation can supply its facts: declared source, a live read or snapshot, or either."
+        },
+        "lexicons": {
+          "type": "object",
+          "description": "Each lexicon the project loads: supported, or why it can't supply the capability.",
+          "additionalProperties": {
+            "oneOf": [
+              {
+                "const": "supported"
+              },
+              {
+                "type": "object",
+                "required": [
+                  "code",
+                  "message"
+                ],
+                "properties": {
+                  "code": {
+                    "enum": [
+                      "lexicon-has-no-mapping",
+                      "capability-not-derivable",
+                      "lexicon-not-loaded"
+                    ]
+                  },
+                  "message": {
+                    "type": "string"
+                  }
+                }
+              }
+            ]
+          }
+        },
+        "notEvaluated": {
+          "type": "array",
+          "description": "What the rule leaves out. chant search prints this under every answer that uses the capability.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "uses": {
+          "type": "array",
+          "description": "The capabilities and helpers its rule refers to.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "rule": {
+          "type": "string",
+          "description": "The rule as written, one alternative per line."
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "description": "Exit code 1.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/capabilities/v1/capabilities.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "usage-invalid"
+              ]
+            },
+            "message": {
+              "type": "string"
+            },
+            "hint": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/workspace/compose-graph.ts

@@ -41,6 +41,7 @@ import type { KindLinkRead } from "./kind-link-readers";
 import type { RecordLinkRow } from "./record-assets";
 import type { ReasonCode } from "./reason-codes";
 import { GRAPH_IR_VERSION, type GraphIR, type IRExport, type IRDanglingRef, type IRGroups, type IRImport, type IREdge, type IRNode } from "../graph-ir";
+import type { ViewDocument } from "../capabilities/view";
 
 /** The version of the composed document `chant workspace graph` writes. */
 export const WORKSPACE_GRAPH_VERSION = 1;
@@ -105,6 +106,12 @@ export interface ComposedMember {
    * `chant workspace graph` on every member; null when the box declares neither.
    */
   box?: { factory: FactoryView | null; listing: ListingView | null } | null;
+  /**
+   * With `--capability-view` (#4378): the lexicon-neutral view the member's
+   * own chant mapped through its own lexicons, with `<member>/<id>` ids. null
+   * when the member's chant predates the view and printed none.
+   */
+  capabilityView?: ViewDocument | null;
   /** Whole-read facts the member's IR carried (`meta`, `pipeline`), kept apart from the composed sections. */
   meta?: Record<string, unknown>;
   pipeline?: unknown;
@@ -249,7 +256,9 @@ export interface ComposeInput {
   ir?: GraphIR;
 }
 
-const prefix = (member: string, id: string): string => `${member}/${id}`;
+/** A member's node id as the composed workspace documents give it: `<member>/<id>`. `workspace search` uses the same rule (#4374). */
+export const composedId = (member: string, id: string): string => `${member}/${id}`;
+const prefix = composedId;
 
 const strings = (v: unknown): string[] => (Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : []);
 const records = (v: unknown): Record<string, unknown>[] =>

package/src/workspace/conformance/conformance.e2e.test.ts

@@ -39,6 +39,8 @@ const JSON_FLAG: Record<ReadContractCommand, string[]> = {
   "graph --composites": ["--json"],
   runs: ["--json"],
   wip: ["--json"],
+  search: ["--json"],
+  "search --capabilities": ["--json"],
 };
 
 /** The smallest reader that conforms, with a hook to misbehave. */
@@ -65,6 +67,17 @@ describe("the generated conformance workspace (#2679)", () => {
     expect(report.skipped).toEqual([]);
   }, 300_000);
 
+  test("search answers over the chant member with workspace graph's ids, and lists the others (#4374)", async () => {
+    const docs: Record<string, unknown>[] = [];
+    const report = await runWorkspaceReaderConformance(reader((doc) => (docs.push(doc), doc)), { workspaceDir: ws.dir, commands: ["search"] });
+    expect(report.problems).toEqual([]);
+    const doc = docs[0] as { at: null; matches: { id: string; member: string }[]; members: { name: string; status: string; alone?: boolean }[] };
+    expect(doc.at).toBeNull();
+    expect(doc.matches.length).toBeGreaterThan(0);
+    for (const m of doc.matches) expect(m.id.startsWith(`${m.member}/`), m.id).toBe(true);
+    expect(doc.members.find((m) => m.name === "delivery")).toMatchObject({ status: "searched", alone: true });
+  }, 300_000);
+
   test("graph --composites joins the fixture's composite to its component", async () => {
     const docs: Record<string, unknown>[] = [];
     await runWorkspaceReaderConformance(reader((doc) => (docs.push(doc), doc)), { workspaceDir: ws.dir, commands: ["graph --composites"] });
@@ -120,7 +133,7 @@ describe("commands (#2679)", () => {
     expect(report.problems).toEqual([]);
     expect(read).toEqual(["ls", "status", "graph --composites"]);
     expect(report.checked).toEqual(["ls", "status", "graph --composites"]);
-    expect(report.skipped).toEqual(["graph", "check", "records", "records --uncommitted", "graph --intent", "runs", "wip"]);
+    expect(report.skipped).toEqual(["graph", "check", "records", "records --uncommitted", "graph --intent", "runs", "wip", "search", "search --capabilities"]);
   }, 300_000);
 
   test("a name that is not a contract command, or an empty list, is refused", () => {

package/src/workspace/conformance/index.ts

@@ -56,7 +56,7 @@ import { isDeepStrictEqual } from "node:util";
 import { READ_CONTRACT_VERSION } from "../reason-codes";
 
 /** The read-contract commands, as a reader names them. */
-export const READ_CONTRACT_COMMANDS = ["ls", "graph", "check", "status", "records", "records --uncommitted", "graph --intent", "graph --composites", "runs", "wip"] as const;
+export const READ_CONTRACT_COMMANDS = ["ls", "graph", "check", "status", "records", "records --uncommitted", "graph --intent", "graph --composites", "runs", "wip", "search", "search --capabilities"] as const;
 export type ReadContractCommand = (typeof READ_CONTRACT_COMMANDS)[number];
 
 /**
@@ -75,6 +75,10 @@ export const READ_CONTRACT_SCHEMAS: Record<ReadContractCommand, string> = {
   "graph --composites": "composites.schema.json",
   runs: "runs.schema.json",
   wip: "wip.schema.json",
+  // `workspace search` (#4374). Plain `chant search --json` prints the same document for one project.
+  search: "search.schema.json",
+  // The capability catalog (#4375), from the workspace's chant.
+  "search --capabilities": "capabilities.schema.json",
 };
 
 /** The flags that ask each command for its JSON document. A reader adds one of these and nothing else. */
@@ -89,6 +93,8 @@ export const READ_CONTRACT_JSON_FLAGS: Record<ReadContractCommand, readonly (rea
   "graph --composites": [[], ["--json"]],
   runs: [["--json"]],
   wip: [["--json"]],
+  search: [["--json"]],
+  "search --capabilities": [["--json"]],
 };
 
 /** The arguments the suite passes each read, on the reference workspace or the generated one. */
@@ -103,6 +109,9 @@ export const REFERENCE_READS: Record<ReadContractCommand, string[]> = {
   "graph --composites": [],
   runs: [],
   wip: [],
+  // A bare word: on either workspace it searches the chant member, delivery, and lists the others.
+  search: ["app"],
+  "search --capabilities": [],
 };
 
 /** One chant run: the arguments after `chant`, what it was given on stdin, and what it printed. */
@@ -344,6 +353,8 @@ export const MCP_READ_TOOLS: Partial<Record<ReadContractCommand, string>> = {
   "graph --intent": "workspace-graph",
   "graph --composites": "workspace-graph",
   runs: "workspace-runs",
+  search: "workspace-search",
+  "search --capabilities": "capabilities",
 };
 
 /**
@@ -359,9 +370,14 @@ export function mcpToolCall(argv: readonly string[]): { name: string; arguments:
   const args: Record<string, unknown> = {};
   const positional: string[] = [];
   const kinds: string[] = [];
+  const members: string[] = [];
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
     const value = (): string | undefined => rest[++i];
+    if (a === "--") {
+      positional.push(...rest.slice(i + 1));
+      break;
+    }
     if (a === "--json") continue;
     if (a === "--format" && rest[i + 1] === "json") {
       i++;
@@ -381,7 +397,14 @@ export function mcpToolCall(argv: readonly string[]): { name: string; arguments:
     else if (a === "--by") args.by = value();
     else if (a === "--uncommitted") args.uncommitted = true;
     else if (a === "--composites") args.composites = true;
-    else if (a.startsWith("-")) return undefined;
+    else if (verb === "search" && a === "--member") members.push(value() ?? "");
+    else if (verb === "search" && a === "--env") args.env = value();
+    else if (verb === "search" && a === "--snapshot") args.snapshot = value();
+    else if (verb === "search" && a === "--count-by") args.countBy = value();
+    else if (verb === "search" && a === "--show") args.show = value();
+    else if (verb === "search" && a === "--explain") args.explain = true;
+    else if (verb === "search" && a === "--capabilities") args.capabilities = true;
+    else if (/^-[A-Za-z-]/.test(a)) return undefined;
     else positional.push(a);
   }
   switch (verb) {
@@ -397,6 +420,12 @@ export function mcpToolCall(argv: readonly string[]): { name: string; arguments:
       return positional.length === 0 ? { name: "workspace-graph", arguments: { ...args, ...(kinds.length ? { kind: kinds } : {}) } } : undefined;
     case "runs":
       return positional.length === 0 && kinds.length === 0 ? { name: "workspace-runs", arguments: args } : undefined;
+    case "search":
+      // The catalog (#4375) is its own tool, and takes nothing.
+      if (args.capabilities) return positional.length === 0 && Object.keys(args).length === 1 && kinds.length === 0 && members.length === 0 ? { name: "capabilities", arguments: {} } : undefined;
+      return positional.length <= 1 && kinds.length === 0
+        ? { name: "workspace-search", arguments: { ...args, query: positional[0] ?? "", ...(members.length ? { member: members } : {}) } }
+        : undefined;
     default:
       return undefined;
   }

package/src/workspace/graph-cache.ts

@@ -368,9 +368,7 @@ export function splitCached(plan: MemberPlan, args: ParsedArgs, cache: GraphCach
       // A member read through a generated reader project (#2874) is also keyed on
       // the kind's graph block and the version of the package that reads it.
       const reader = unit.reader ? readerStamp(unit.reader) : "";
-      const abs = unit.dir === "." ? plan.workspace.root : join(plan.workspace.root, ...unit.dir.split("/"));
-      const revision = at ? { commit: at, dir: unit.dir } : undefined;
-      const stamp = memberStamp(abs, unit.exclude, revision);
+      const { abs, revision, stamp } = unitStamp(plan, unit, at);
       if (!stamp) continue;
       stamps.set(unit.id, stamp.value);
       const key = cacheKey({ member: unit.member, dir: unit.dir, stamp: stamp.value, toolchain: `${tool}\0${reader}`, argv, env });
@@ -385,6 +383,32 @@ export function splitCached(plan: MemberPlan, args: ParsedArgs, cache: GraphCach
   return { hits, stamps, pending, started };
 }
 
+/** One unit's stamp, and what it was taken over: the member's directory on disk, and the commit for `--at`. */
+function unitStamp(plan: MemberPlan, unit: RunUnit, at: string | null): { abs: string; revision?: { commit: string; dir: string }; stamp: Stamp | undefined } {
+  const abs = unit.dir === "." ? plan.workspace.root : join(plan.workspace.root, ...unit.dir.split("/"));
+  const revision = at ? { commit: at, dir: unit.dir } : undefined;
+  return { abs, ...(revision ? { revision } : {}), stamp: memberStamp(abs, unit.exclude, revision) };
+}
+
+/**
+ * Every member unit's stamp, by unit id, by the rule {@link splitCached} keys
+ * the cache on (ws-059), with no cache read. A read that is never cached, such
+ * as `chant workspace search` (#4374), still stamps its members this way, so a
+ * reader compares stamps across documents with one meaning. A unit whose stamp
+ * can't be taken is left out.
+ */
+export function planStamps(plan: MemberPlan, at: string | null): Map<string, string> {
+  const stamps = new Map<string, string>();
+  for (const group of plan.groups) {
+    for (const unit of group.units) {
+      if (unit.group) continue;
+      const { stamp } = unitStamp(plan, unit, at);
+      if (stamp) stamps.set(unit.id, stamp.value);
+    }
+  }
+  return stamps;
+}
+
 /** The plan without the units in `ids`; a toolchain left with no units is dropped. */
 export function withoutUnits(plan: MemberPlan, ids: ReadonlySet<string>): MemberPlan {
   if (ids.size === 0) return plan;