@intentius/chant 0.46.0 → 0.50.0

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

@@ -47,7 +47,8 @@ describe("McpServer", () => {
 
       expect(response.error).toBeUndefined();
       const result = response.result as Record<string, unknown>;
-      expect(result.protocolVersion).toBe("2024-11-05");
+      // No requested version → negotiates to the latest supported revision (#1194).
+      expect(result.protocolVersion).toBe("2026-07-28");
       expect(result.capabilities).toBeDefined();
       expect((result.serverInfo as Record<string, unknown>).name).toBe("chant");
       expect((result.serverInfo as Record<string, unknown>).version).toBe("0.1.0");
@@ -60,11 +61,273 @@ describe("McpServer", () => {
         method: "initialize",
         params: {},
       });
-      const result = response.result as Record<string, unknown>;
+      const result = response!.result as Record<string, unknown>;
       const caps = result.capabilities as Record<string, unknown>;
       expect(caps.tools).toBeDefined();
       expect(caps.resources).toBeDefined();
     });
+
+    // -----------------------------------------------------------------------
+    // Dual-revision negotiation (#1194)
+    // -----------------------------------------------------------------------
+
+    test("a 2024-11-05 client requesting its own version gets it back unchanged", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: { protocolVersion: "2024-11-05", clientInfo: { name: "old-client", version: "1.0" } },
+      });
+      expect(response!.error).toBeUndefined();
+      const result = response!.result as Record<string, unknown>;
+      expect(result.protocolVersion).toBe("2024-11-05");
+    });
+
+    test("a 2026-07-28 client requesting its version gets the latest revision", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: { _meta: { protocolVersion: "2026-07-28" } },
+      });
+      expect(response!.error).toBeUndefined();
+      const result = response!.result as Record<string, unknown>;
+      expect(result.protocolVersion).toBe("2026-07-28");
+    });
+
+    test("an unrecognized requested version falls back to the latest supported", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: { protocolVersion: "1999-01-01" },
+      });
+      const result = response!.result as Record<string, unknown>;
+      expect(result.protocolVersion).toBe("2026-07-28");
+    });
+
+    test("no requested version at all defaults to the latest supported", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {},
+      });
+      const result = response!.result as Record<string, unknown>;
+      expect(result.protocolVersion).toBe("2026-07-28");
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // _meta parsing (#1194)
+  // -----------------------------------------------------------------------
+
+  describe("_meta parsing", () => {
+    test("reads requested protocol version from _meta on initialize", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: { _meta: { protocolVersion: "2024-11-05" } },
+      });
+      const result = response!.result as Record<string, unknown>;
+      expect(result.protocolVersion).toBe("2024-11-05");
+    });
+
+    test("_meta protocolVersion takes precedence over a legacy top-level one", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: { protocolVersion: "2024-11-05", _meta: { protocolVersion: "2026-07-28" } },
+      });
+      const result = response!.result as Record<string, unknown>;
+      expect(result.protocolVersion).toBe("2026-07-28");
+    });
+
+    test("client identity in _meta does not interfere with tool dispatch", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: {
+          name: "search",
+          arguments: { query: "bucket" },
+          _meta: {
+            protocolVersion: "2026-07-28",
+            "io.modelcontextprotocol/clientInfo": { name: "some-agent", version: "3.0" },
+          },
+        },
+      });
+      expect(response!.error).toBeUndefined();
+      const result = response!.result as { content: Array<{ text: string }>; isError?: boolean };
+      expect(result.isError).toBeUndefined();
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.query).toBe("bucket");
+    });
+
+    test("a request with no _meta and no legacy fields is unaffected", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/list",
+        params: {},
+      });
+      expect(response!.error).toBeUndefined();
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // Notification silence (#1194)
+  // -----------------------------------------------------------------------
+
+  describe("notifications", () => {
+    test("a message with no id gets no response", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        method: "notifications/initialized",
+        params: {},
+      });
+      expect(response).toBeNull();
+    });
+
+    test("an id-less message is not routed through dispatch as Unknown method", async () => {
+      // notifications/initialized isn't a dispatch case; silence must come
+      // from the id check, not from swallowing a dispatch error.
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        method: "notifications/anything",
+      });
+      expect(response).toBeNull();
+    });
+
+    test("a message with id 0 (falsy but present) still gets a response", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 0,
+        method: "tools/list",
+      });
+      expect(response).not.toBeNull();
+      expect(response!.id).toBe(0);
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // server/discover (#1194)
+  // -----------------------------------------------------------------------
+
+  describe("server/discover", () => {
+    test("a 2026-07-28 client can discover capabilities without calling initialize", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "server/discover",
+        params: { _meta: { protocolVersion: "2026-07-28" } },
+      });
+      expect(response!.error).toBeUndefined();
+      const result = response!.result as Record<string, unknown>;
+      expect(result.protocolVersion).toBe("2026-07-28");
+      expect(result.serverInfo).toBeDefined();
+      expect(result.capabilities).toBeDefined();
+      expect(Array.isArray(result.tools)).toBe(true);
+      expect(Array.isArray(result.resources)).toBe(true);
+    });
+
+    test("discover's tools list matches tools/list", async () => {
+      const discover = await server.handleRequest({ jsonrpc: "2.0", id: 1, method: "server/discover", params: {} });
+      const list = await server.handleRequest({ jsonrpc: "2.0", id: 2, method: "tools/list" });
+      const discoverNames = (discover!.result as { tools: Array<{ name: string }> }).tools.map((t) => t.name).sort();
+      const listNames = (list!.result as { tools: Array<{ name: string }> }).tools.map((t) => t.name).sort();
+      expect(discoverNames).toEqual(listNames);
+    });
+
+    test("discover's resources list matches resources/list, including plugin contributions", async () => {
+      const plugin = createMockPlugin({
+        name: "test-lex",
+        mcpResources: () => [
+          {
+            uri: "catalog",
+            name: "Test Catalog",
+            description: "Test resource catalog",
+            mimeType: "application/json",
+            handler: async () => "[]",
+          },
+        ],
+      });
+      const s = new McpServer([plugin]);
+      const discover = await s.handleRequest({ jsonrpc: "2.0", id: 1, method: "server/discover", params: {} });
+      const list = await s.handleRequest({ jsonrpc: "2.0", id: 2, method: "resources/list" });
+      const discoverUris = (discover!.result as { resources: Array<{ uri: string }> }).resources.map((r) => r.uri).sort();
+      const listUris = (list!.result as { resources: Array<{ uri: string }> }).resources.map((r) => r.uri).sort();
+      expect(discoverUris).toEqual(listUris);
+      expect(discoverUris).toContain("chant://test-lex/catalog");
+    });
+
+    test("negotiates protocol version the same way as initialize", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "server/discover",
+        params: { protocolVersion: "2024-11-05" },
+      });
+      const result = response!.result as Record<string, unknown>;
+      expect(result.protocolVersion).toBe("2024-11-05");
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // Structured tool output (#1194)
+  // -----------------------------------------------------------------------
+
+  describe("structured tool output", () => {
+    test("an object-returning handler gets structuredContent alongside text", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "search", arguments: { query: "bucket" } },
+      });
+      const result = response!.result as { content: Array<{ text: string }>; structuredContent?: Record<string, unknown> };
+      expect(result.structuredContent).toBeDefined();
+      expect(result.structuredContent!.query).toBe("bucket");
+      const parsedText = JSON.parse(result.content[0].text);
+      expect(result.structuredContent).toEqual(parsedText);
+    });
+
+    test("a string-returning handler has no structuredContent", async () => {
+      const plugin = createMockPlugin({
+        name: "test-lex",
+        mcpTools: () => [
+          {
+            name: "greet",
+            description: "Greet",
+            inputSchema: { type: "object", properties: {} },
+            handler: async () => "hello from plugin",
+          },
+        ],
+      });
+      const s = new McpServer([plugin]);
+      const response = await s.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "test-lex:greet", arguments: {} },
+      });
+      const result = response!.result as { structuredContent?: unknown };
+      expect(result.structuredContent).toBeUndefined();
+    });
+
+    test("an isError response has no structuredContent", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "unknown-tool", arguments: {} },
+      });
+      const result = response!.result as { isError: boolean; structuredContent?: unknown };
+      expect(result.isError).toBe(true);
+      expect(result.structuredContent).toBeUndefined();
+    });
   });
 
   describe("error handling", () => {
@@ -590,6 +853,7 @@ describe("McpServer", () => {
       expect(uris).toContain("chant://ops");
       expect(uris).toContain("chant://ops/{name}/runs");
       expect(uris).toContain("chant://ops/{name}/runs/latest");
+      expect(uris).toContain("chant://knowledge");
 
       // Each resource has required fields
       for (const resource of result.resources) {
@@ -735,6 +999,62 @@ describe("McpServer", () => {
         expect(data.error).toBeDefined();
       });
     });
+
+    describe("chant://knowledge", () => {
+      test("empty gracefully when no bundle exists", async () => {
+        const originalCwd = process.cwd();
+        process.chdir(testDir);
+        try {
+          const response = await server.handleRequest({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "resources/read",
+            params: { uri: "chant://knowledge" },
+          });
+          expect(response.error).toBeUndefined();
+          const result = response.result as { contents: Array<{ text: string; mimeType: string }> };
+          expect(result.contents[0].mimeType).toBe("application/json");
+          const data = JSON.parse(result.contents[0].text);
+          expect(data.index).toBeNull();
+          expect(data.concepts).toEqual([]);
+        } finally {
+          process.chdir(originalCwd);
+        }
+      });
+
+      test("serves the bundle index and concepts when present", async () => {
+        const originalCwd = process.cwd();
+        process.chdir(testDir);
+        try {
+          await mkdir(join(testDir, "knowledge", "decisions"), { recursive: true });
+          await writeFile(join(testDir, "knowledge", "index.md"), "# Knowledge index\n");
+          await writeFile(
+            join(testDir, "knowledge", "decisions", "public-assets.md"),
+            "---\ntype: decision\ntitle: Public assets\nbinds: bucket\n---\nBody text.\n",
+          );
+
+          const response = await server.handleRequest({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "resources/read",
+            params: { uri: "chant://knowledge" },
+          });
+          expect(response.error).toBeUndefined();
+          const result = response.result as { contents: Array<{ text: string }> };
+          const data = JSON.parse(result.contents[0].text);
+          expect(data.index).toBe("# Knowledge index\n");
+          expect(data.concepts).toHaveLength(1);
+          expect(data.concepts[0]).toMatchObject({
+            path: "decisions/public-assets.md",
+            type: "decision",
+            title: "Public assets",
+            binds: ["bucket"],
+          });
+        } finally {
+          process.chdir(originalCwd);
+        }
+      });
+    });
   });
 
   // -----------------------------------------------------------------------
@@ -1157,7 +1477,7 @@ describe("McpServer", () => {
 
       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(7);
+      expect(resources).toHaveLength(8);
     });
 
     test("server with empty plugins array works", async () => {

package/src/cli/mcp/server.ts

@@ -7,11 +7,50 @@ import { explainTool, handleExplain } from "./tools/explain";
 import { scaffoldTool, createScaffoldHandler } from "./tools/scaffold";
 import { searchTool, createSearchHandler } from "./tools/search";
 import type { LexiconPlugin } from "../../lexicon";
-import type { McpRequest, McpResponse, ToolDefinition, ToolHandler, ResourceDefinition } from "./types";
+import type { McpRequest, McpResponse, McpRequestMeta, ToolDefinition, ToolHandler, ResourceDefinition } from "./types";
 import { createSnapshotTool, createDiffTool } from "./lifecycle-tools";
 import { createOpListTool, createOpRunTool, createOpStatusTool, createOpSignalTool, createOpReportTool } from "./op-tools";
 import { buildResourcesList, handleResourcesRead } from "./resource-handlers";
 
+/**
+ * Protocol versions this server understands, newest first. `initialize` and
+ * `server/discover` both negotiate against this list rather than assuming
+ * the client's revision (#1194).
+ */
+const SUPPORTED_PROTOCOL_VERSIONS = ["2026-07-28", "2024-11-05"] as const;
+const LATEST_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS[0];
+
+/**
+ * Pick the protocol version to answer with: the client's requested version
+ * when we support it, otherwise our latest. A 2024-11-05 client that asks
+ * for `2024-11-05` gets it back unchanged; a 2026-07-28 client — or one
+ * that never says — gets the latest revision (#1194).
+ */
+export function negotiateProtocolVersion(requested: string | undefined): string {
+  if (requested && (SUPPORTED_PROTOCOL_VERSIONS as readonly string[]).includes(requested)) {
+    return requested;
+  }
+  return LATEST_PROTOCOL_VERSION;
+}
+
+/**
+ * Parse the `_meta` envelope the 2026-07-28 revision puts on every request
+ * (client identity, requested protocol version), falling back to the
+ * top-level `protocolVersion`/`clientInfo` fields a prior-revision client
+ * sends on `initialize`. Read-side only — the server holds no handshake
+ * state to update (#1194).
+ */
+export function parseMeta(params: Record<string, unknown>): { protocolVersion?: string; clientInfo?: { name: string; version?: string } } {
+  const meta = (params._meta ?? {}) as McpRequestMeta;
+  const protocolVersion =
+    (typeof meta.protocolVersion === "string" ? meta.protocolVersion : undefined) ??
+    (typeof params.protocolVersion === "string" ? params.protocolVersion : undefined);
+  const clientInfo =
+    meta["io.modelcontextprotocol/clientInfo"] ??
+    (params.clientInfo as { name: string; version?: string } | undefined);
+  return { protocolVersion, clientInfo };
+}
+
 /**
  * The name a lexicon's MCP tool is registered under: `<lexicon>:<verb>`,
  * whether or not the lexicon already wrote the prefix itself (#1341).
@@ -135,9 +174,19 @@ export class McpServer {
   }
 
   /**
-   * Handle incoming MCP request
+   * Handle incoming MCP request.
+   *
+   * A message with no `id` is a notification — `notifications/initialized`
+   * being the one every client sends — and gets no response in any
+   * protocol revision (#1194). Returns `null` for those; callers (see
+   * {@link start}) simply skip writing anything back.
    */
-  async handleRequest(request: McpRequest): Promise<McpResponse> {
+  async handleRequest(request: McpRequest & { id: string | number }): Promise<McpResponse>;
+  async handleRequest(request: McpRequest): Promise<McpResponse | null>;
+  async handleRequest(request: McpRequest): Promise<McpResponse | null> {
+    if (request.id === undefined) {
+      return null;
+    }
     try {
       const result = await this.dispatch(request.method, request.params ?? {});
       return {
@@ -157,16 +206,35 @@ export class McpServer {
     }
   }
 
+  /**
+   * The `initialize` result — also the basis of `server/discover` below.
+   */
+  private buildInitializeResult(params: Record<string, unknown>): Record<string, unknown> {
+    const { protocolVersion } = parseMeta(params);
+    return {
+      protocolVersion: negotiateProtocolVersion(protocolVersion),
+      capabilities: { tools: {}, resources: {} },
+      serverInfo: { name: "chant", version: "0.1.0" },
+    };
+  }
+
   /**
    * Dispatch request to appropriate handler
    */
   private async dispatch(method: string, params: Record<string, unknown>): Promise<unknown> {
     switch (method) {
       case "initialize":
+        // Answered for prior-revision clients too — negotiated, not hard-coded (#1194).
+        return this.buildInitializeResult(params);
+
+      case "server/discover":
+        // On-demand capability discovery (#1194): the initialize result
+        // merged with the tools/resources listings, so a 2026-07-28 client
+        // never has to call `initialize` at all.
         return {
-          protocolVersion: "2024-11-05",
-          capabilities: { tools: {}, resources: {} },
-          serverInfo: { name: "chant", version: "0.1.0" },
+          ...this.buildInitializeResult(params),
+          tools: Array.from(this.tools.values()),
+          resources: buildResourcesList(this.pluginResources).resources,
         };
 
       case "tools/list":
@@ -203,6 +271,7 @@ export class McpServer {
 
     try {
       const result = await handler(toolParams);
+      const isStructured = typeof result === "object" && result !== null;
       return {
         content: [
           {
@@ -210,6 +279,11 @@ export class McpServer {
             text: typeof result === "string" ? result : JSON.stringify(result, null, 2),
           },
         ],
+        // Structured output (2025-06-18+): handlers already return plain
+        // objects that get stringified above, so agents that want the
+        // parsed shape directly get it here too, alongside the text block
+        // kept for backward compatibility (#1194).
+        ...(isStructured ? { structuredContent: result } : {}),
       };
     } catch (error) {
       return {
@@ -238,7 +312,10 @@ export class McpServer {
       try {
         const request = JSON.parse(line) as McpRequest;
         const response = await this.handleRequest(request);
-        console.log(JSON.stringify(response));
+        // Notifications (#1194) get no response at all — not even an empty one.
+        if (response !== null) {
+          console.log(JSON.stringify(response));
+        }
       } catch (error) {
         const errorResponse: McpResponse = {
           jsonrpc: "2.0",

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

@@ -1,6 +1,19 @@
-import { resolve } from "path";
+import { resolve, dirname } from "path";
 import { discover } from "../../../discovery/index";
 import { buildOkfBundle, OKF_VERSION } from "../../../okf";
+import { loadOkfBundle, bindConcepts, type OkfConcept } from "../../../okf-read";
+import { loadChantConfigUpward, resolveKnowledgeDir } from "../../../config";
+
+/** One bound concept as surfaced in an explain knowledge section — the trio the #1867 design calls for, not the full {@link OkfConcept}. */
+export interface ExplainKnowledgeEntry {
+  type: string;
+  title?: string;
+  path: string;
+}
+
+function toKnowledgeEntry(concept: OkfConcept): ExplainKnowledgeEntry {
+  return { type: concept.type, title: concept.title, path: concept.path };
+}
 
 /**
  * Explain tool definition for MCP
@@ -46,6 +59,25 @@ export async function handleExplain(params: Record<string, unknown>): Promise<un
     };
   }
 
+  // Authored knowledge (#1867, design #1059): bind the project's OKF bundle
+  // (if any) to the discovered entities and carry each bound concept's
+  // type/title/path into the summary. A project with no `knowledge/` yet
+  // binds nothing — `bound` is empty — so the section is omitted below
+  // rather than rendered empty; this is the CLI and MCP tool's one shared
+  // code path, so both surfaces match by construction.
+  // `loadChantConfigUpward` walks up from `infraPath` (chant #1117) — a
+  // `chant explain src/<stack>` two levels below `chant.config.ts` must find
+  // the same `knowledge/` a `chant explain .` at the root would, matching
+  // `build.ts`'s `configDir` derivation for the same reason.
+  const loaded = await loadChantConfigUpward(infraPath);
+  const projectRoot = loaded.configPath ? dirname(loaded.configPath) : infraPath;
+  const knowledgeDir = resolveKnowledgeDir(loaded.config, projectRoot);
+  const bundle = await loadOkfBundle(knowledgeDir);
+  const { bound } = bindConcepts(bundle, result.entities);
+  const knowledge = new Map<string, ExplainKnowledgeEntry[]>(
+    Array.from(bound.entries()).map(([name, concepts]) => [name, concepts.map(toKnowledgeEntry)]),
+  );
+
   // Group entities by lexicon and kind
   const byLexicon = new Map<string, { resources: string[]; properties: string[] }>();
 
@@ -89,7 +121,11 @@ export async function handleExplain(params: Record<string, unknown>): Promise<un
   };
 
   if (format === "json") {
-    return summary;
+    // Omitted entirely when no entity bound a concept — "cleanly absent" per
+    // #1867's AC, not an empty `{}`.
+    return knowledge.size > 0
+      ? { ...summary, knowledge: Object.fromEntries(knowledge) }
+      : summary;
   }
 
   // Markdown format
@@ -133,6 +169,19 @@ export async function handleExplain(params: Record<string, unknown>): Promise<un
     lines.push("");
   }
 
+  if (knowledge.size > 0) {
+    lines.push("## Knowledge");
+    lines.push("");
+    for (const [name, entries] of knowledge) {
+      lines.push(`### \`${name}\``);
+      for (const entry of entries) {
+        const title = entry.title ? `${entry.title} ` : "";
+        lines.push(`- ${entry.type || "concept"}: ${title}(\`${entry.path}\`)`);
+      }
+      lines.push("");
+    }
+  }
+
   if (result.errors.length > 0) {
     lines.push("## Errors");
     lines.push("");

package/src/cli/mcp/types.ts

@@ -1,9 +1,13 @@
 /**
  * MCP message types
+ *
+ * `id` is optional per JSON-RPC 2.0: a message with no `id` is a
+ * notification (e.g. `notifications/initialized`) and gets no response,
+ * in every protocol revision (#1194).
  */
 export interface McpRequest {
   jsonrpc: "2.0";
-  id: string | number;
+  id?: string | number;
   method: string;
   params?: Record<string, unknown>;
 }
@@ -19,6 +23,18 @@ export interface McpResponse {
   };
 }
 
+/**
+ * The `_meta` envelope the 2026-07-28 revision puts on every request so it
+ * is self-contained: client identity and the client's requested protocol
+ * version travel here instead of living in handshake state (#1194). A
+ * prior-revision client instead sends `protocolVersion`/`clientInfo` as
+ * top-level `initialize` params — both forms are read by {@link parseMeta}.
+ */
+export interface McpRequestMeta {
+  protocolVersion?: string;
+  "io.modelcontextprotocol/clientInfo"?: { name: string; version?: string };
+}
+
 /**
  * Tool definition for MCP
  */
@@ -30,6 +46,16 @@ export interface ToolDefinition {
     properties: Record<string, unknown>;
     required?: string[];
   };
+  /**
+   * JSON schema for `structuredContent` (2025-06-18+), when a tool's result
+   * shape is obvious and stable enough to declare. Optional and additive —
+   * most tools omit it (#1194).
+   */
+  outputSchema?: {
+    type: "object";
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
 }
 
 /**

package/src/cli/plugins.ts

@@ -106,10 +106,12 @@ export function collectBuildRootContributors(
   plugins: readonly LexiconPlugin[] | undefined,
   config: Record<string, unknown>,
   projectRoot: string,
-): Array<() => Promise<import("../lexicon").BuildRootContribution>> {
+): Array<import("../lexicon").BuildRootContributor> {
   return (plugins ?? [])
     .filter((plugin) => typeof plugin.buildRoots === "function")
-    .map((plugin) => () => plugin.buildRoots!({ projectRoot, config }));
+    // `entities` is not bindable here — discovery has not run — so the merge
+    // hands it in when it calls the closure (#1828 / SOPS provenance).
+    .map((plugin) => (ctx) => plugin.buildRoots!({ projectRoot, config, entities: ctx?.entities }));
 }
 
 /**