@intentius/chant 0.84.0 → 0.86.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.84.0",
+  "version": "0.86.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -50,6 +50,16 @@
       "default": "./src/cli/index.ts"
     },
     "./workspace/*.schema.json": "./src/workspace/*.schema.json",
+    "./workspace/conformance": {
+      "development": "./src/workspace/conformance/index.ts",
+      "types": "./dist/workspace/conformance/index.d.ts",
+      "default": "./src/workspace/conformance/index.mjs"
+    },
+    "./workspace/conformance/vitest": {
+      "development": "./src/workspace/conformance/vitest.ts",
+      "types": "./dist/workspace/conformance/vitest.d.ts",
+      "default": "./src/workspace/conformance/vitest.ts"
+    },
     "./cli/*": {
       "development": "./src/cli/*.ts",
       "types": "./dist/cli/*.d.ts",
@@ -104,6 +114,14 @@
   "devDependencies": {
     "@cdktn/hcl2json": "^0.24.0"
   },
+  "peerDependencies": {
+    "vitest": ">=2"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
   "overrides": {
     "esbuild": "^0.28.1"
   }

package/src/cli/handlers/graph.ts

@@ -619,6 +619,10 @@ async function runComponentGraphView(
         wave: waveOf.get(name) ?? null,
         liveNames: graph.liveNames?.[name] ?? [name],
         ...(graph.composites?.[name] ? { composites: graph.composites[name] } : {}),
+        // The archetype (#2662), declared or inferred, so a reader such as
+        // `chant workspace graph --composites` labels a component without
+        // importing its source.
+        ...(graph.archetypes?.[name] ? { archetype: graph.archetypes[name] } : {}),
       },
       // Deep-link the node to its `*.component.ts` (behold's inspect panel).
       ...(graph.files?.[name] ? { sourceLoc: { file: graph.files[name] } } : {}),

package/src/cli/main.test.ts

@@ -688,6 +688,15 @@ describe("workspace records (#2546)", () => {
   });
 });
 
+describe("workspace graph --composites (#2662)", () => {
+  test("parses as a boolean on workspace graph", () => {
+    const args = parseArgs(["workspace", "graph", "--composites", "--at", "HEAD", "--json"]);
+    expect(args).toMatchObject({ command: "workspace", path: "graph", composites: true, at: "HEAD", json: true });
+    expect(() => parseArgs(["workspace", "graph", "--composites=yes"])).toThrow();
+    expect(resolveCommand(args, commandRegistry)?.def.name).toBe("workspace graph");
+  });
+});
+
 describe("workspace graph --intent (#2651)", () => {
   test("parses the region and every --kind, in order", () => {
     const args = parseArgs(["workspace", "graph", "--intent", "app/server.mjs:3-7", "--kind", "a.kind.mjs", "--kind", "b.kind.mjs", "--at", "HEAD", "--json"]);

package/src/cli/main.ts

@@ -69,6 +69,7 @@ const BOOLEAN_FLAGS = new Set([
   "--strict",
   "--validate",
   "--use-composites",
+  "--composites",
   "--stacks",
   "--components",
   "--up",
@@ -365,12 +366,35 @@ export function parseArgs(args: string[]): ParsedArgs {
       if (!result.kind || result.kind.startsWith("-")) throw new Error("--kind needs a kind file: --kind <path>");
       // Repeatable for `workspace graph --intent` (#2651); the others read the last one.
       (result.kinds ??= []).push(result.kind);
+    } else if (arg === "--composites") {
+      // `chant workspace graph --composites` (#2662)
+      result.composites = true;
     } else if (arg === "--intent") {
       // `chant workspace graph --intent <path[:start-end]>` (#2651)
       result.intent = args[++i];
       if (!result.intent || result.intent.startsWith("-")) throw new Error("--intent needs a region: --intent <path[:start-end]>");
     } else if (arg === "--current") {
       result.current = true;
+    } else if (arg === "--set") {
+      // `chant workspace records amend <id> --set <file|->` (#2670)
+      result.set = args[++i];
+      if (!result.set || (result.set.startsWith("-") && result.set !== "-")) throw new Error("--set needs a JSON file, or - for standard input: --set <file|->");
+    } else if (arg === "--verdict") {
+      // `chant workspace records review <id> --verdict agree|dissent|abstain` (#2670)
+      result.verdict = args[++i];
+      if (!result.verdict || result.verdict.startsWith("-")) throw new Error("--verdict needs agree, dissent or abstain");
+    } else if (arg === "--by") {
+      // `chant workspace records review <id> --by <principal>` (#2670): whoever the caller says.
+      result.by = args[++i];
+      if (!result.by || result.by.startsWith("-")) throw new Error("--by needs the reviewer: --by <principal>");
+    } else if (arg === "--session") {
+      // `chant workspace records review <id> --session <id>` (#2670)
+      result.session = args[++i];
+      if (!result.session || result.session.startsWith("-")) throw new Error("--session needs a session id: --session <id>");
+    } else if (arg === "--prefix") {
+      // `chant workspace records new <kind> --prefix <prefix>` (#2670): the id prefix to allocate under.
+      result.prefix = args[++i];
+      if (!result.prefix || result.prefix.startsWith("-")) throw new Error("--prefix needs an id prefix: --prefix <prefix>");
     } else if (arg === "--require") {
       // `chant workspace records|verify --require attested` (#2547)
       result.require = args[++i];
@@ -717,8 +741,9 @@ Workspace (level 1, #2524):
                         beside it and marks the members whose digests differ.
                         Read only; never fetches. --json prints the
                         read-contract document
-  workspace records --kind <kind file> [--current] [--at <rev>] [--base <rev>] [--require attested] [--json]
-                        Read the records a record kind locates, validated
+  workspace records [--kind <kind file>] [--current] [--at <rev>] [--base <rev>] [--require attested] [--json]
+                        Without --kind, every record kind the declaration
+                        names. Read the records a record kind locates, validated
                         against its schema, with reason codes for invalid
                         ones. --current leaves out superseded records; --at
                         reads a commit's git objects. Needs no workspace file.
@@ -727,9 +752,32 @@ Workspace (level 1, #2524):
                         --require attested exits 2 if any record is not
                         attested. A pinned file that changed is a warning,
                         asset-drift or asset-missing
+  workspace records [--kind <kind file>] --since <rev> [--at <rev>] [--json]
+                        What changed in the records between <rev> and --at
+                        (default: the working tree): new and removed records,
+                        state transitions, new verdicts, new supersessions
+                        and changed pins
   workspace records pin <path>
                         Print the path from the workspace root and the
                         sha256 of a file, for a decision's evidence pin
+  workspace records new [<kind file>] --from <file|-> [--prefix <prefix>] [--dry-run]
+                        Write one new record in the kind's directory from
+                        the JSON fields given, after validating them as
+                        records would read them. Without a kind file, the one
+                        kind the declaration names. Allocates the next id when
+                        the fields hold none. Prints {path, id} as JSON and
+                        never commits
+  workspace records amend <id> [--kind <kind file>] --set <file|-> [--dry-run]
+                        Set top-level fields of one record. A closed record
+                        never changes, and an approved one changes only its
+                        state (upward), pins and reviews; anything else is
+                        refused with amend-supersede-instead. Prints
+                        {path, id, changed}
+  workspace records review <id> [--kind <kind file>] --verdict agree|dissent|abstain --by <principal> [--note <text>] [--session <id>] [--dry-run]
+                        Append a review to one record, dated and bound to
+                        the digest of the record text. A dissent needs
+                        --note. The principal is not checked; attestation is
+                        the seal's job. Prints {path, id, review}
   workspace verify [--base <rev>] [--head <rev>] [--require attested]
                         Check the commits in base..head against the signers
                         and roles read from base. A change to the signers file
@@ -773,10 +821,15 @@ Workspace (level 1, #2524):
                         read-contract document. --at <rev> runs each member's
                         source as it was at that commit; --kind adds the
                         records' asset and constrains links
+  workspace graph --composites [--at <rev>] [--member <name>] [-o <file>]
+                        Each composite instance the members declare, with the
+                        components whose contract can deploy it; an instance
+                        with none lists an empty set
   workspace graph --intent <path[:start-end]> [--at <rev>] [--kind <kind file>...] [--json]
                         The intent graph over one region: the commits that
                         touched it, the decisions whose constrains cover it,
-                        the artifacts they pin, and findings with closed codes
+                        the artifacts they pin, and findings with closed codes.
+                        Without --kind, every record kind the declaration names
 
 Lifecycle (alias: lc):
   lifecycle snapshot <env>  Query API, save metadata to orphan branch

package/src/cli/mcp/resource-handlers.ts

@@ -1,6 +1,8 @@
 import { resolve, join, dirname } from "node:path";
 import { readFile } from "node:fs/promises";
 import type { ResourceDefinition } from "./types";
+import type { LexiconPlugin } from "../../lexicon";
+import { collectComposites } from "./tools/composites";
 import { getContext } from "./resources/context";
 import { readSnapshot, readEnvironmentSnapshots } from "../../lifecycle/git";
 import { discoverOps } from "../../op/discover";
@@ -44,6 +46,12 @@ export const coreResourceDefinitions: ResourceDefinition[] = [
     description: "Latest run state for a named Op",
     mimeType: "application/json",
   },
+  {
+    uri: "chant://composites",
+    name: "Composite catalog",
+    description: "Every composite the loaded lexicons export, with what each bundles and its parameters (#2662)",
+    mimeType: "application/json",
+  },
   {
     uri: "chant://knowledge",
     name: "Knowledge bundle",
@@ -99,9 +107,18 @@ export function collectExamples(
 export async function handleResourcesRead(
   params: Record<string, unknown>,
   pluginResources: Map<string, PluginResourceEntry>,
+  plugins: LexiconPlugin[] = [],
 ): Promise<unknown> {
   const uri = params.uri as string;
 
+  // The whole composite catalog (#2662), static data from each lexicon's
+  // `composites()`; the `composites` tool filters the same list.
+  if (uri === "chant://composites") {
+    return {
+      contents: [{ uri, mimeType: "application/json", text: JSON.stringify(collectComposites(plugins), null, 2) }],
+    };
+  }
+
   if (uri === "chant://context") {
     return {
       contents: [

package/src/cli/mcp/server.test.ts

@@ -778,6 +778,142 @@ describe("McpServer", () => {
     });
   });
 
+  // -----------------------------------------------------------------------
+  // Composite catalog (#2662)
+  // -----------------------------------------------------------------------
+
+  describe("composite catalog", () => {
+    const awsLike = createMockPlugin({
+      name: "aws",
+      composites: () => [
+        {
+          name: "LambdaSqs",
+          lexicon: "aws",
+          description: "A Lambda function fed by an SQS queue through an event source mapping.",
+          bundles: ["EventSourceMapping", "Function", "Queue", "Role"],
+          params: [{ name: "queueName", type: "Value<string>", required: false }],
+        },
+        {
+          name: "VpcDefault",
+          lexicon: "aws",
+          description: "A VPC with public and private subnets.",
+          bundles: ["Subnet", "Vpc"],
+          params: [{ name: "cidr", type: "string", required: false }],
+        },
+      ],
+      mcpResources: () => [
+        {
+          uri: "resource-catalog",
+          name: "Catalog",
+          description: "Resource catalog",
+          mimeType: "application/json",
+          handler: async () => JSON.stringify([
+            { className: "Queue", resourceType: "AWS::SQS::Queue", kind: "resource" },
+          ]),
+        },
+      ],
+    });
+    const k8sLike = createMockPlugin({
+      name: "k8s",
+      composites: () => [
+        {
+          name: "WebApp",
+          lexicon: "k8s",
+          description: "A Deployment and Service.",
+          bundles: ["Deployment", "Service"],
+          params: [{ name: "image", type: "string", required: true }],
+        },
+      ],
+    });
+    const noComposites = createMockPlugin({ name: "cedar" });
+
+    async function call(s: McpServer, name: string, args: Record<string, unknown>) {
+      const response = await s.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name, arguments: args },
+      });
+      return JSON.parse((response.result as { content: Array<{ text: string }> }).content[0].text);
+    }
+
+    test("the composites tool answers what a lexicon has, with bundles and params", async () => {
+      const s = new McpServer([awsLike, k8sLike, noComposites]);
+      const parsed = await call(s, "composites", { lexicon: "aws" });
+      expect(parsed.total).toBe(2);
+      expect(parsed.composites.map((c: { name: string }) => c.name)).toEqual(["LambdaSqs", "VpcDefault"]);
+      expect(parsed.composites[0].bundles).toContain("Queue");
+      expect(parsed.composites[0].params[0].name).toBe("queueName");
+      expect(parsed.lexicons).toEqual(["aws", "k8s", "cedar"]);
+    });
+
+    test("with no filter it lists every lexicon's composites; a lexicon with none adds nothing", async () => {
+      const s = new McpServer([awsLike, k8sLike, noComposites]);
+      const parsed = await call(s, "composites", {});
+      expect(parsed.total).toBe(3);
+      expect((await call(s, "composites", { lexicon: "cedar" })).total).toBe(0);
+    });
+
+    test("query matches a bundled kind, and a name match ranks first", async () => {
+      const s = new McpServer([awsLike, k8sLike]);
+      const byKind = await call(s, "composites", { query: "queue" });
+      expect(byKind.composites.map((c: { name: string }) => c.name)).toEqual(["LambdaSqs"]);
+      const byName = await call(s, "composites", { query: "vpc" });
+      expect(byName.composites[0].name).toBe("VpcDefault");
+      expect((await call(s, "composites", { limit: 1 })).composites).toHaveLength(1);
+    });
+
+    test("chant://composites lists the whole catalog", async () => {
+      const s = new McpServer([awsLike, k8sLike, noComposites]);
+      const list = await s.handleRequest({ jsonrpc: "2.0", id: 1, method: "resources/list" });
+      const uris = (list.result as { resources: Array<{ uri: string }> }).resources.map((r) => r.uri);
+      expect(uris).toContain("chant://composites");
+
+      const read = await s.handleRequest({
+        jsonrpc: "2.0",
+        id: 2,
+        method: "resources/read",
+        params: { uri: "chant://composites" },
+      });
+      const contents = (read.result as { contents: Array<{ mimeType: string; text: string }> }).contents;
+      expect(contents[0].mimeType).toBe("application/json");
+      const catalog = JSON.parse(contents[0].text);
+      expect(catalog.map((c: { lexicon: string; name: string }) => `${c.lexicon}:${c.name}`)).toEqual([
+        "aws:LambdaSqs", "aws:VpcDefault", "k8s:WebApp",
+      ]);
+    });
+
+    test("chant://composites is an empty list with no plugins", async () => {
+      const read = await new McpServer().handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "resources/read",
+        params: { uri: "chant://composites" },
+      });
+      const contents = (read.result as { contents: Array<{ text: string }> }).contents;
+      expect(JSON.parse(contents[0].text)).toEqual([]);
+    });
+
+    test("search finds a resource type and the composite that bundles it", async () => {
+      const s = new McpServer([awsLike, k8sLike]);
+      const parsed = await call(s, "search", { query: "queue" });
+      expect(parsed.total).toBe(2);
+      const kinds = parsed.results.map((r: { kind: string }) => r.kind).sort();
+      expect(kinds).toEqual(["composite", "resource"]);
+      const composite = parsed.results.find((r: { kind: string }) => r.kind === "composite");
+      expect(composite).toMatchObject({ name: "LambdaSqs", lexicon: "aws", bundles: expect.arrayContaining(["Queue"]) });
+      expect(composite.params).toBeUndefined();
+    });
+
+    test("search's lexicon filter applies to composites too", async () => {
+      const s = new McpServer([awsLike, k8sLike]);
+      const parsed = await call(s, "search", { query: "deployment", lexicon: "aws" });
+      expect(parsed.total).toBe(0);
+      const k8s = await call(s, "search", { query: "deployment", lexicon: "k8s" });
+      expect(k8s.results.map((r: { name: string }) => r.name)).toEqual(["WebApp"]);
+    });
+  });
+
   // -----------------------------------------------------------------------
   // Scaffold tool with plugins
   // -----------------------------------------------------------------------
@@ -1466,23 +1602,23 @@ describe("McpServer", () => {
 
       const toolsRes = await s.handleRequest({ jsonrpc: "2.0", id: 2, method: "tools/list" });
       const tools = (toolsRes.result as { tools: Array<{ name: string }> }).tools;
-      expect(tools).toHaveLength(13);
+      expect(tools).toHaveLength(14);
       expect(tools.map((t) => t.name).sort()).toEqual([
-        "build", "explain", "import", "lifecycle-diff", "lifecycle-snapshot", "lint",
+        "build", "composites", "explain", "import", "lifecycle-diff", "lifecycle-snapshot", "lint",
         "op-approve", "op-list", "op-report", "op-run", "op-status",
         "scaffold", "search",
       ]);
 
       const resourcesRes = await s.handleRequest({ jsonrpc: "2.0", id: 3, method: "resources/list" });
       const resources = (resourcesRes.result as { resources: Array<{ uri: string }> }).resources;
-      expect(resources).toHaveLength(8);
+      expect(resources).toHaveLength(9);
     });
 
     test("server with empty plugins array works", async () => {
       const s = new McpServer([]);
       const toolsRes = await s.handleRequest({ jsonrpc: "2.0", id: 1, method: "tools/list" });
       const tools = (toolsRes.result as { tools: Array<{ name: string }> }).tools;
-      expect(tools).toHaveLength(13);
+      expect(tools).toHaveLength(14);
     });
   });
 });

package/src/cli/mcp/server.ts

@@ -6,6 +6,7 @@ import { importTool, handleImport } from "./tools/import";
 import { explainTool, handleExplain } from "./tools/explain";
 import { scaffoldTool, createScaffoldHandler } from "./tools/scaffold";
 import { searchTool, createSearchHandler } from "./tools/search";
+import { compositesTool, createCompositesHandler } from "./tools/composites";
 import type { LexiconPlugin } from "../../lexicon";
 import type { McpRequest, McpResponse, McpRequestMeta, ToolDefinition, ToolHandler, ResourceDefinition } from "./types";
 import { createSnapshotTool, createDiffTool } from "./lifecycle-tools";
@@ -90,8 +91,10 @@ export class McpServer {
   private tools: Map<string, ToolDefinition> = new Map();
   private toolHandlers: Map<string, ToolHandler> = new Map();
   private pluginResources: Map<string, { definition: ResourceDefinition; handler: () => Promise<string> }> = new Map();
+  private plugins: LexiconPlugin[];
 
   constructor(plugins?: LexiconPlugin[]) {
+    this.plugins = plugins ?? [];
     // Register core tools
     this.registerTool(buildTool, handleBuild);
     this.registerTool(lintTool, handleLint);
@@ -99,6 +102,7 @@ export class McpServer {
     this.registerTool(explainTool, handleExplain);
     this.registerTool(scaffoldTool, createScaffoldHandler(plugins ?? []));
     this.registerTool(searchTool, createSearchHandler(plugins ?? []));
+    this.registerTool(compositesTool, createCompositesHandler(plugins ?? []));
 
     // Register state tools
     const snapshot = createSnapshotTool(plugins ?? []);
@@ -252,7 +256,7 @@ export class McpServer {
         return buildResourcesList(this.pluginResources);
 
       case "resources/read":
-        return handleResourcesRead(params, this.pluginResources);
+        return handleResourcesRead(params, this.pluginResources, this.plugins);
 
       default:
         throw new Error(`Unknown method: ${method}`);

package/src/cli/mcp/tools/composites.ts

@@ -0,0 +1,98 @@
+import type { CompositeEntry, LexiconPlugin } from "../../../lexicon";
+
+/**
+ * The `composites` tool (#2662): what composites the loaded lexicons export,
+ * what each one bundles and what it takes. "What composites do you have for
+ * aws?" is `{ lexicon: "aws" }`.
+ *
+ * Everything here reads `LexiconPlugin.composites()`, which is static catalog
+ * data. No composite is loaded or called and no provider is asked anything.
+ */
+export const compositesTool = {
+  name: "composites",
+  description:
+    "List the composites the loaded lexicons export: what each builds, the resource kinds it bundles, and its parameters",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      lexicon: {
+        type: "string",
+        description: "Only composites from this lexicon (e.g. 'aws', 'k8s')",
+      },
+      query: {
+        type: "string",
+        description: "Keyword matched against the composite's name, description, bundled resource kinds and parameter names",
+      },
+      limit: {
+        type: "number",
+        description: "Maximum number of composites to return (default: 50)",
+      },
+    },
+  },
+};
+
+/**
+ * Every composite the plugins contribute, in plugin order. A plugin whose
+ * `composites()` throws contributes nothing rather than failing the listing.
+ */
+export function collectComposites(plugins: LexiconPlugin[]): CompositeEntry[] {
+  const entries: CompositeEntry[] = [];
+  for (const plugin of plugins) {
+    let contributed: CompositeEntry[] = [];
+    try {
+      contributed = plugin.composites?.() ?? [];
+    } catch {
+      contributed = [];
+    }
+    for (const entry of contributed) entries.push({ ...entry, lexicon: entry.lexicon || plugin.name });
+  }
+  return entries;
+}
+
+/**
+ * How well an entry matches a lowercased keyword: 0 for no match, higher for
+ * better. A name match beats a bundled kind, which beats a word in the
+ * description or a parameter name, so `queue` lists `LambdaSqs` ahead of a
+ * composite that merely mentions queues.
+ */
+export function compositeMatchScore(entry: CompositeEntry, lowerQuery: string): number {
+  const name = entry.name.toLowerCase();
+  if (name.startsWith(lowerQuery)) return 4;
+  if (name.includes(lowerQuery)) return 3;
+  if (entry.bundles.some((b) => b.toLowerCase().includes(lowerQuery))) return 2;
+  if (entry.description.toLowerCase().includes(lowerQuery)) return 1;
+  if (entry.params.some((p) => p.name.toLowerCase().includes(lowerQuery))) return 1;
+  return 0;
+}
+
+export function createCompositesHandler(
+  plugins: LexiconPlugin[],
+): (params: Record<string, unknown>) => Promise<unknown> {
+  return async (params) => {
+    const lexicon = typeof params.lexicon === "string" && params.lexicon !== "" ? params.lexicon : undefined;
+    const query = typeof params.query === "string" && params.query !== "" ? params.query : undefined;
+    const limit = typeof params.limit === "number" ? params.limit : 50;
+
+    let entries = collectComposites(plugins);
+    if (lexicon) entries = entries.filter((e) => e.lexicon === lexicon);
+
+    if (query) {
+      const lowerQuery = query.toLowerCase();
+      entries = entries
+        .map((entry) => ({ entry, score: compositeMatchScore(entry, lowerQuery) }))
+        .filter(({ score }) => score > 0)
+        .sort((a, b) => b.score - a.score || a.entry.name.localeCompare(b.entry.name))
+        .map(({ entry }) => entry);
+    }
+
+    return {
+      ...(lexicon ? { lexicon } : {}),
+      ...(query ? { query } : {}),
+      // The loaded lexicons, so an empty answer for `lexicon: "cedar"` reads
+      // as "cedar exports none" when cedar is listed, and "not loaded" when not.
+      lexicons: plugins.map((p) => p.name),
+      total: entries.length,
+      composites: entries.slice(0, limit),
+    };
+  };
+}

package/src/cli/mcp/tools/search.ts

@@ -1,17 +1,20 @@
 import type { LexiconPlugin } from "../../../lexicon";
+import { collectComposites, compositeMatchScore } from "./composites";
 
 /**
  * Search tool definition for MCP
  */
 export const searchTool = {
   name: "search",
-  description: "Search the resource catalog across loaded lexicons by keyword",
+  description:
+    "Search the resource catalog and the composite catalog across loaded lexicons by keyword; a composite comes back with kind 'composite'",
   inputSchema: {
     type: "object" as const,
     properties: {
       query: {
         type: "string",
-        description: "Search query — matches against resource type, class name, and kind",
+        description:
+          "Search query: matches a resource's type, class name and kind, and a composite's name, description and the resource kinds it bundles",
       },
       lexicon: {
         type: "string",
@@ -32,6 +35,20 @@ interface CatalogEntry {
   kind?: string;
 }
 
+/** A composite in search results (#2662): `kind` is always `"composite"`. */
+interface CompositeResult {
+  kind: "composite";
+  name: string;
+  description: string;
+  bundles: string[];
+}
+
+type SearchResult = (CatalogEntry | CompositeResult) & { lexicon: string; score: number };
+
+function sortKey(result: SearchResult): string {
+  return "resourceType" in result ? result.resourceType ?? "" : result.name;
+}
+
 /**
  * Create a search handler with access to loaded plugins
  */
@@ -44,7 +61,7 @@ export function createSearchHandler(
     const limit = (params.limit as number) ?? 20;
 
     const lowerQuery = query.toLowerCase();
-    const results: Array<CatalogEntry & { lexicon: string; score: number }> = [];
+    const results: SearchResult[] = [];
 
     const candidates = lexiconFilter
       ? plugins.filter((p) => p.name === lexiconFilter)
@@ -86,10 +103,35 @@ export function createSearchHandler(
       }
     }
 
-    // Sort: prefix matches first, then alphabetical by resourceType
+    // Composites (#2662), so one query finds both a resource type and the
+    // composite that bundles it. A name or bundled-kind prefix ranks with the
+    // resource prefix matches. The full entry (params included) is the
+    // `composites` tool's answer; search keeps a result short.
+    for (const entry of collectComposites(candidates)) {
+      const score = compositeMatchScore(entry, lowerQuery);
+      if (score === 0) continue;
+      const isPrefix =
+        entry.name.toLowerCase().startsWith(lowerQuery) ||
+        entry.bundles.some((b) => b.toLowerCase().startsWith(lowerQuery));
+      results.push({
+        kind: "composite",
+        name: entry.name,
+        description: entry.description,
+        bundles: entry.bundles,
+        lexicon: entry.lexicon,
+        score: isPrefix ? 1 : 0,
+      });
+    }
+
+    // Sort: prefix matches first; within a tier composites ahead of resource
+    // types, since a handful of composites would otherwise sort behind every
+    // `AWS::...` type the same word prefixes; then alphabetical.
     results.sort((a, b) => {
       if (a.score !== b.score) return b.score - a.score;
-      return (a.resourceType ?? "").localeCompare(b.resourceType ?? "");
+      const aComposite = a.kind === "composite" ? 0 : 1;
+      const bComposite = b.kind === "composite" ? 0 : 1;
+      if (aComposite !== bComposite) return aComposite - bComposite;
+      return sortKey(a).localeCompare(sortKey(b));
     });
 
     const limited = results.slice(0, limit);

package/src/cli/registry.ts

@@ -285,10 +285,22 @@ export interface ParsedArgs {
   kind?: string;
   /** Every `--kind` given, in order: `chant workspace graph --intent` reads each (#2651). */
   kinds?: string[];
+  /** `chant workspace graph --composites` (#2662): print each composite instance with the components that can deploy it. */
+  composites?: boolean;
   /** `chant workspace graph --intent <path[:start-end]>` (#2651): the region the intent graph is over. */
   intent?: string;
   /** `chant workspace records --current` (#2546): leave out records a closed record supersedes. */
   current?: boolean;
+  /** `chant workspace records amend <id> --set <file|->` (#2670): the JSON fields to set. */
+  set?: string;
+  /** `chant workspace records review <id> --verdict <v>` (#2670): agree, dissent or abstain. */
+  verdict?: string;
+  /** `chant workspace records review <id> --by <principal>` (#2670): the reviewer, as the caller names them. */
+  by?: string;
+  /** `chant workspace records review <id> --session <id>` (#2670): the review session the verdict was given in. */
+  session?: string;
+  /** `chant workspace records new <kind> --prefix <prefix>` (#2670): the id prefix to allocate under. */
+  prefix?: string;
   /** `chant workspace records|verify --require attested` (#2547): the provenance level a gate requires. */
   require?: string;
   /**
@@ -414,7 +426,7 @@ export interface ParsedArgs {
   plan?: string;
   /** `chant operator log --op <name>` (#2029) — restrict the tick history to one ConvergeOp by name. Omitted, every discovered ConvergeOp's ticks are merged into one timeline. */
   op?: string;
-  /** `chant operator log --since <iso>` (#2029) — only entries at or after this ISO-8601 instant. */
+  /** `chant operator log --since <iso>` (#2029) — only entries at or after this ISO-8601 instant. `chant workspace records --since <rev>` (#2673) — the revision to compare the records with. */
   since?: string;
   /** `chant operator log --limit <n>` (#2029) — keep only the newest n entries (still printed oldest-first). */
   limit?: number;