@intentius/chant 0.72.3 → 0.72.5

package/src/cli/mcp/docs-parity.test.ts

@@ -0,0 +1,133 @@
+import { describe, test, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import { McpServer, SUPPORTED_PROTOCOL_VERSIONS } from "./server";
+import type { ToolDefinition, ResourceDefinition } from "./types";
+
+/**
+ * The MCP docs say what this server offers; this test says they are right.
+ *
+ * `docs/src/content/docs/cli/mcp.mdx` is a hand-written list of tools,
+ * resources, methods and protocol revisions, and the server is the thing that
+ * actually registers them. Nothing connected the two, so the page fell two
+ * revisions behind twice over (#2385): it advertised six tools while the
+ * constructor registered thirteen, left `lifecycle-snapshot` and
+ * `lifecycle-diff` undocumented anywhere, omitted `server/discover` (#1194)
+ * and `chant://knowledge` (#1867), and claimed protocol version 2024-11-05
+ * long after #1194 made 2026-07-28 the preferred one.
+ *
+ * Each claim here is read back against the running server rather than against
+ * source text: the tool and resource lists come from a real `McpServer`
+ * answering `tools/list` and `resources/list`, which is what a client sees.
+ * The dispatch methods are the exception and are read out of `server.ts` by
+ * regex, because a switch statement has no listing API; that regex fails
+ * loudly if the switch is ever restructured.
+ *
+ * Same shape as `scripts/fold-depth-bound-claims.test.ts` (#2367) and
+ * `scripts/lexicon-count-claims.test.ts` (#2316): a doc claim pinned to
+ * ground truth, with a message that says what to edit.
+ */
+
+const repoRoot = fileURLToPath(new URL("../../../../../", import.meta.url));
+const MCP_DOC = join("docs", "src", "content", "docs", "cli", "mcp.mdx");
+const GUIDE_DOC = join("docs", "src", "content", "docs", "guide", "agent-integration.mdx");
+const SERVER_SRC = join("packages", "core", "src", "cli", "mcp", "server.ts");
+
+const mcpDoc = readFileSync(join(repoRoot, MCP_DOC), "utf8");
+const guideDoc = readFileSync(join(repoRoot, GUIDE_DOC), "utf8");
+const serverSrc = readFileSync(join(repoRoot, SERVER_SRC), "utf8");
+
+/** What a client is told when it asks, built from a server with no plugins loaded. */
+async function servedListing(method: "tools/list" | "resources/list"): Promise<string[]> {
+  const response = await new McpServer().handleRequest({ jsonrpc: "2.0", id: 1, method });
+  const result = response.result as { tools?: ToolDefinition[]; resources?: ResourceDefinition[] };
+  const names = result.tools?.map((t) => t.name) ?? result.resources?.map((r) => r.uri);
+  if (!names || names.length === 0) {
+    throw new Error(`mcp docs parity: ${method} returned nothing to compare the docs against`);
+  }
+  return names;
+}
+
+/** The lines of one `##`/`###` section, up to the next heading at any level. */
+function section(doc: string, heading: string, label: string): string {
+  const start = doc.indexOf(heading);
+  if (start < 0) throw new Error(`mcp docs parity: no "${heading}" heading in ${label} — was it renamed? Update this test to match.`);
+  const rest = doc.slice(start + heading.length);
+  const end = rest.search(/\n#{1,4} /);
+  return end < 0 ? rest : rest.slice(0, end);
+}
+
+/** Every `` | `thing` | `` first column of a markdown table in `text`. */
+function firstColumnCells(text: string): string[] {
+  return [...text.matchAll(/^\| `([^`]+)` \|/gm)].map((m) => m[1]);
+}
+
+function sorted(values: readonly string[]): string[] {
+  return [...values].sort();
+}
+
+describe("the MCP docs describe the server that ships (#2385)", () => {
+  test("cli/mcp.mdx documents exactly the tools the server registers", async () => {
+    const registered = await servedListing("tools/list");
+    // Every core tool gets its own `### \`name\`` heading. The `#### ` heading
+    // under op-approve and the un-backticked "### Plugin Tools" are not tools.
+    const documented = [...mcpDoc.matchAll(/^### `([^`]+)`$/gm)].map((m) => m[1]);
+    expect(documented.length, `${MCP_DOC}: found no "### \`tool-name\`" headings — was the Tools section reformatted?`).toBeGreaterThan(0);
+    expect(
+      sorted(documented),
+      `${MCP_DOC} and the McpServer constructor disagree about the core tools. ` +
+        `Registered: ${sorted(registered).join(", ")}. Documented: ${sorted(documented).join(", ")}. ` +
+        `Give every registered tool a "### \`name\`" section on that page, and delete the sections for tools that no longer exist.`,
+    ).toEqual(sorted(registered));
+  });
+
+  test("guide/agent-integration.mdx lists exactly the tools the server registers", async () => {
+    const registered = await servedListing("tools/list");
+    const listed = firstColumnCells(section(guideDoc, "### Available Tools", GUIDE_DOC));
+    expect(
+      sorted(listed),
+      `${GUIDE_DOC}'s "Available Tools" table and the McpServer constructor disagree. ` +
+        `Registered: ${sorted(registered).join(", ")}. Listed: ${sorted(listed).join(", ")}. ` +
+        `Add or remove rows so the table matches; the parameter detail lives on the cli/mcp reference page.`,
+    ).toEqual(sorted(registered));
+  });
+
+  test("cli/mcp.mdx documents exactly the resources the server serves", async () => {
+    const served = await servedListing("resources/list");
+    // Rows of the Resources table: `| `chant://...` | `mime` | description |`.
+    const documented = [...mcpDoc.matchAll(/^\| `(chant:\/\/[^`]+)` \| `[^`]+` \|/gm)].map((m) => m[1]);
+    expect(
+      sorted(documented),
+      `${MCP_DOC}'s Resources table and the server's resources/list disagree. ` +
+        `Served: ${sorted(served).join(", ")}. Documented: ${sorted(documented).join(", ")}. ` +
+        `A URI the server reads but never lists (chant://examples/{name}) belongs in prose under the table, not in it.`,
+    ).toEqual(sorted(served));
+  });
+
+  test("cli/mcp.mdx states the protocol revisions the server negotiates, preferred first", () => {
+    const documented = [...mcpDoc.matchAll(/^\| `(\d{4}-\d{2}-\d{2})` \|/gm)].map((m) => m[1]);
+    expect(
+      documented,
+      `${MCP_DOC} claims protocol revisions ${documented.join(", ") || "(none found)"}, but server.ts ` +
+        `negotiates ${SUPPORTED_PROTOCOL_VERSIONS.join(", ")}. The first row is the preferred revision, ` +
+        `the one a client that names no version gets back.`,
+    ).toEqual([...SUPPORTED_PROTOCOL_VERSIONS]);
+  });
+
+  test("cli/mcp.mdx lists exactly the JSON-RPC methods dispatch answers", () => {
+    const dispatched = [...serverSrc.matchAll(/^      case "([^"]+)":$/gm)].map((m) => m[1]);
+    if (dispatched.length === 0) {
+      throw new Error(
+        `mcp docs parity: no \`case "method":\` labels found in ${SERVER_SRC} — the dispatch switch was ` +
+          `restructured, so this test can no longer read the method list out of it. Update the test to match.`,
+      );
+    }
+    const documented = firstColumnCells(section(mcpDoc, "### Supported Methods", MCP_DOC));
+    expect(
+      sorted(documented),
+      `${MCP_DOC}'s "Supported Methods" table and the dispatch switch in ${SERVER_SRC} disagree. ` +
+        `Dispatched: ${sorted(dispatched).join(", ")}. Documented: ${sorted(documented).join(", ")}.`,
+    ).toEqual(sorted(dispatched));
+  });
+});

package/src/cli/mcp/server.ts

@@ -17,8 +17,12 @@ 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).
+ *
+ * Exported because `docs-parity.test.ts` reads it: `cli/mcp.mdx` states these
+ * revisions in prose, and stating them twice is how the page came to claim
+ * 2024-11-05 for two releases after this list moved past it (#2385).
  */
-const SUPPORTED_PROTOCOL_VERSIONS = ["2026-07-28", "2024-11-05"] as const;
+export const SUPPORTED_PROTOCOL_VERSIONS = ["2026-07-28", "2024-11-05"] as const;
 const LATEST_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS[0];
 
 /**

package/src/cli/mcp-config.test.ts

@@ -0,0 +1,168 @@
+import { describe, test, expect } from "vitest";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { initCommand } from "./commands/init";
+import { doctorCommand } from "./commands/doctor";
+import { updateCommand } from "./commands/update";
+import { parseArgs, commandRegistry } from "./main";
+import { MCP_CONFIG_FILENAME, MCP_SETUP_COMMAND, mcpConfigPath } from "./mcp-config";
+
+/**
+ * chant #2383. `chant init` used to write `mcp.json` into the user's home
+ * directory while `chant doctor` looked for `<project>/.mcp.json` and told
+ * you to run `chant agent setup`, a command the registry never had. Three
+ * sites, three answers, and a project chant had just scaffolded failed
+ * chant's own doctor with an unrunnable fix.
+ *
+ * These tests are written against the agreement rather than against today's
+ * string: the round trip below fails if init and doctor ever pick different
+ * paths again, and the registry check fails if the remediation ever names a
+ * command that is not registered. Neither can be satisfied by editing one
+ * site in isolation.
+ */
+describe("MCP config: one location, three agreeing sites (#2383)", () => {
+  test("init then doctor round-trips: mcp-config passes with no manual step", async () => {
+    await withTestDir(async (testDir) => {
+      const result = await initCommand({
+        path: testDir,
+        lexicon: "aws",
+        skipInstall: true,
+      });
+      expect(result.success).toBe(true);
+
+      const report = await doctorCommand(testDir);
+      const check = report.checks.find((c) => c.name === "mcp-config");
+      expect(check).toBeDefined();
+      expect(check!.status).toBe("pass");
+    });
+  });
+
+  test("init writes the MCP config inside the project it was pointed at", async () => {
+    await withTestDir(async (testDir) => {
+      const result = await initCommand({
+        path: testDir,
+        lexicon: "aws",
+        skipInstall: true,
+      });
+
+      expect(existsSync(mcpConfigPath(testDir))).toBe(true);
+      expect(result.createdFiles).toContain(MCP_CONFIG_FILENAME);
+
+      const config = JSON.parse(readFileSync(mcpConfigPath(testDir), "utf-8"));
+      expect(config.mcpServers.chant.args).toEqual(["chant", "serve", "mcp"]);
+
+      // Every path init reports as created is relative to the project. A
+      // `~/` or absolute entry means init reached outside the directory it
+      // was handed, which is the half of #2383 worth not regressing.
+      for (const file of result.createdFiles) {
+        expect(file.startsWith("~"), `${file} escapes the project`).toBe(false);
+        expect(file.startsWith("/"), `${file} escapes the project`).toBe(false);
+        expect(file.includes(homedir()), `${file} escapes the project`).toBe(false);
+      }
+    });
+  });
+
+  test("--skip-mcp parses and suppresses the write", async () => {
+    // The flag was documented and typed long before anything parsed it, so
+    // assert the parse and the effect together — either one alone passed
+    // while `chant init --skip-mcp` still wrote the file.
+    expect(parseArgs(["init", ".", "--lexicon", "aws", "--skip-mcp"]).skipMcp).toBe(true);
+    expect(parseArgs(["init", ".", "--lexicon", "aws"]).skipMcp).toBeUndefined();
+
+    await withTestDir(async (testDir) => {
+      const result = await initCommand({
+        path: testDir,
+        lexicon: "aws",
+        skipMcp: true,
+        skipInstall: true,
+      });
+      expect(existsSync(mcpConfigPath(testDir))).toBe(false);
+      expect(result.createdFiles).not.toContain(MCP_CONFIG_FILENAME);
+    });
+  });
+
+  test("the doctor's remediation names a registered command", async () => {
+    // Reconstruct the warning the doctor actually emits, then check that the
+    // command inside it exists. `chant agent setup` satisfied neither.
+    await withTestDir(async (testDir) => {
+      writeFileSync(join(testDir, "chant.config.json"), JSON.stringify({ lexicons: ["aws"] }));
+      const report = await doctorCommand(testDir);
+      const check = report.checks.find((c) => c.name === "mcp-config");
+      expect(check!.status).toBe("warn");
+      expect(check!.message).toContain(MCP_SETUP_COMMAND);
+
+      const named = check!.message!.match(/run ([a-z][a-z -]*)/)?.[1].trim();
+      expect(named).toBeDefined();
+      expect(named!.startsWith("chant ")).toBe(true);
+      const registered = commandRegistry.map((c) => c.name);
+      expect(registered).toContain(named!.slice("chant ".length));
+    });
+  });
+
+  test("the remediation command restores a deleted config", async () => {
+    await withTestDir(async (testDir) => {
+      // A project that has everything except the MCP config: exactly the
+      // state the doctor warns about. `chant init` refuses this directory
+      // without --force, so the remediation has to be something else.
+      mkdirSync(join(testDir, "src"), { recursive: true });
+      writeFileSync(join(testDir, "chant.config.json"), JSON.stringify({ lexicons: ["aws"] }));
+      writeFileSync(join(testDir, "package.json"), JSON.stringify({ name: "p", type: "module" }));
+
+      expect(MCP_SETUP_COMMAND).toBe("chant update");
+      const result = await updateCommand({ path: testDir });
+      expect(result.success).toBe(true);
+
+      const report = await doctorCommand(testDir);
+      expect(report.checks.find((c) => c.name === "mcp-config")!.status).toBe("pass");
+    });
+  });
+
+  test("update leaves an existing config alone", async () => {
+    await withTestDir(async (testDir) => {
+      writeFileSync(join(testDir, "chant.config.json"), JSON.stringify({ lexicons: ["aws"] }));
+      writeFileSync(join(testDir, "package.json"), JSON.stringify({ name: "p", type: "module" }));
+      const hand = JSON.stringify({ mcpServers: { chant: { command: "custom" } } }, null, 2);
+      writeFileSync(mcpConfigPath(testDir), hand);
+
+      await updateCommand({ path: testDir });
+
+      expect(readFileSync(mcpConfigPath(testDir), "utf-8")).toBe(hand);
+    });
+  });
+
+  test("every chant command a doctor check tells you to run is registered", async () => {
+    // Broader than the mcp-config check that prompted #2383: whatever the
+    // doctor prints as `run chant <something>`, the registry has to have it.
+    // `chant agent setup` shipped as advice for a command that never existed;
+    // this fails the moment any check does that again.
+    const registered = commandRegistry.map((c) => c.name);
+    expect(registered).not.toContain("agent");
+    expect(registered).not.toContain("agent setup");
+
+    const messages: string[] = [];
+    await withTestDir(async (empty) => {
+      messages.push(...(await doctorCommand(empty)).checks.flatMap((c) => c.message ?? []));
+    });
+    await withTestDir(async (partial) => {
+      writeFileSync(join(partial, "chant.config.json"), JSON.stringify({ lexicons: ["aws"] }));
+      writeFileSync(join(partial, "package.json"), JSON.stringify({ name: "p" }));
+      mkdirSync(join(partial, "src"), { recursive: true });
+      messages.push(...(await doctorCommand(partial)).checks.flatMap((c) => c.message ?? []));
+    });
+
+    const named = messages.flatMap((m) => [...m.matchAll(/run `?(chant [a-z][a-z0-9 -]*)/g)].map((x) => x[1]));
+    expect(named.length).toBeGreaterThan(0);
+    for (const advice of named) {
+      // Drop flags and the trailing prose the regex may have swept up, then
+      // keep the longest registered name that prefixes what was advised.
+      const words = advice.slice("chant ".length).split(/\s+/).filter((w) => w && !w.startsWith("-"));
+      const match = registered.find((name) => {
+        const parts = name.split(" ");
+        return parts.every((p, i) => words[i] === p);
+      });
+      expect(match, `doctor advises "${advice}", which no registered command matches`).toBeDefined();
+    }
+  });
+});

package/src/cli/mcp-config.ts

@@ -0,0 +1,76 @@
+import { existsSync, writeFileSync } from "fs";
+import { join } from "path";
+
+/**
+ * The one place chant decides where a project's MCP server registration
+ * lives, what goes in it, and which command writes it (chant #2383).
+ *
+ * Before this module the three sites disagreed: `chant init` wrote
+ * `mcp.json` into the user's home directory (picking a harness directory
+ * that happened to exist), `chant doctor` looked for `<project>/.mcp.json`,
+ * and the doctor's remediation named `chant agent setup`, which was never
+ * registered in `./main.ts`. A project chant had just scaffolded therefore
+ * failed chant's own doctor, and the fix the warning named could not be run.
+ *
+ * Project scope wins. The file versions with the project it describes, it
+ * keeps `chant init <dir>` from writing outside `<dir>`, and it is already
+ * what `../agents/discover.ts` treats as the project-scope location when
+ * chant audits an agent installation it did not create. Every consumer must
+ * go through the constants here rather than rebuilding the path, so the
+ * three sites cannot drift apart again without the shared test in
+ * ./mcp-config.test.ts noticing.
+ */
+
+/** Filename of the project-scoped MCP server registration. */
+export const MCP_CONFIG_FILENAME = ".mcp.json";
+
+/**
+ * The command a user runs to (re)write a missing {@link MCP_CONFIG_FILENAME}
+ * in an existing project. `chant init` also writes it, but init refuses a
+ * non-empty directory without `--force`, so the remediation an already
+ * scaffolded project needs is `chant update` — which is also what the
+ * doctor's neighbouring skills check tells you to run for the same reason.
+ * Kept as a constant so ./mcp-config.test.ts can assert it is a command
+ * `commandRegistry` actually registers.
+ */
+export const MCP_SETUP_COMMAND = "chant update";
+
+/** Absolute (or caller-relative) path to a project's MCP config. */
+export function mcpConfigPath(projectDir: string): string {
+  return join(projectDir, MCP_CONFIG_FILENAME);
+}
+
+/**
+ * Detect whether a project uses bun or npm, from its lock file. Lives here
+ * because the package manager is the only variable in the generated config.
+ */
+export function detectPackageManager(dir?: string): "bun" | "npm" {
+  if (dir && (existsSync(join(dir, "bun.lockb")) || existsSync(join(dir, "bun.lock")))) return "bun";
+  return "npm";
+}
+
+/** The MCP registration chant writes: one stdio server named `chant`. */
+export function generateMcpConfig(pm: "bun" | "npm"): string {
+  const config = {
+    mcpServers: {
+      chant: {
+        command: pm === "bun" ? "bunx" : "npx",
+        args: ["chant", "serve", "mcp"],
+      },
+    },
+  };
+
+  return JSON.stringify(config, null, 2);
+}
+
+/**
+ * Write `<projectDir>/.mcp.json` unless one is already there. Returns the
+ * relative path when a file was created, `undefined` when an existing config
+ * was left alone — callers report that difference to the user.
+ */
+export function writeProjectMcpConfig(projectDir: string): string | undefined {
+  const path = mcpConfigPath(projectDir);
+  if (existsSync(path)) return undefined;
+  writeFileSync(path, generateMcpConfig(detectPackageManager(projectDir)));
+  return MCP_CONFIG_FILENAME;
+}

package/src/cli/registry.ts

@@ -101,6 +101,12 @@ export interface ParsedArgs {
   reportFile?: string;
   /** `chant init --skill <name>` filter (added in #95 commit) */
   skill?: string;
+  /**
+   * `chant init --skip-mcp` (#2383) — scaffold without writing the project's
+   * `.mcp.json`. The option existed on `InitOptions` and was documented long
+   * before anything parsed it, so there was no way to decline the write.
+   */
+  skipMcp?: boolean;
   /** `chant import --type <ResourceType>` selector */
   selectType?: string;
   /** `chant import --name <name>` selector */

package/src/declarable-host-marker.test.ts

@@ -0,0 +1,88 @@
+import { describe, test, expect } from "vitest";
+import { isDeclarable, DECLARABLE_MARKER } from "./declarable";
+import { INTRINSIC_MARKER } from "./intrinsic";
+import { STACK_OUTPUT_MARKER } from "./stack-output";
+import { COMPOSITE_MARKER } from "./composite";
+
+/**
+ * chant#2444 — `isDeclarable` accepts an entity a HOST built.
+ *
+ * `F-Host-Interface` item 1 says an entity carries a non-enumerable declarable
+ * marker, and a host supplies its own. Testing identity against chant's symbol
+ * alone refused those for not being chant's rather than for being malformed —
+ * which is what chant#2442 hit inside composite member validation, and what
+ * would otherwise keep biting in the entity tallies and the revival
+ * pass-through, where it fails silently rather than loudly.
+ *
+ * The interesting half of this test file is the second describe block. The
+ * reference implementation reads the same rule as "any own symbol or
+ * non-enumerable own property", which is right for a domain with one marker and
+ * wrong for chant, which has seven. Those cases pin the narrowing.
+ */
+function marked(symbol: symbol, value: unknown = true): object {
+  const o = {};
+  Object.defineProperty(o, symbol, { value, enumerable: false });
+  return o;
+}
+
+describe("isDeclarable accepts a host's marker (chant#2444)", () => {
+  test("chant's own marker, which is every entity a chant build makes", () => {
+    expect(isDeclarable(marked(DECLARABLE_MARKER))).toBe(true);
+  });
+
+  test("the specification host's marker", () => {
+    // The exact symbol `@tsad/shapes` uses. This is the case chant#2442 hit.
+    expect(isDeclarable(marked(Symbol.for("tsad.conformance.declarable")))).toBe(true);
+  });
+
+  test("any implementation's, as long as the marker says declarable", () => {
+    expect(isDeclarable(marked(Symbol.for("some.other.tool.declarable")))).toBe(true);
+  });
+
+  test("a plain object is not one", () => {
+    expect(isDeclarable({})).toBe(false);
+    expect(isDeclarable({ entityType: "Bucket", props: {} })).toBe(false);
+    expect(isDeclarable(null)).toBe(false);
+    expect(isDeclarable("Bucket")).toBe(false);
+  });
+});
+
+describe("the narrowing, and why the reference's reading is unsafe here", () => {
+  test("chant's OTHER markers are not declarable markers", () => {
+    // The measurement that decided the implementation. Under "any own symbol",
+    // every one of these classifies as an entity and enters the tallies — a
+    // worse bug than the one chant#2444 fixes.
+    expect(isDeclarable(marked(INTRINSIC_MARKER))).toBe(false);
+    expect(isDeclarable(marked(STACK_OUTPUT_MARKER))).toBe(false);
+    expect(isDeclarable(marked(COMPOSITE_MARKER))).toBe(false);
+  });
+
+  test("a non-enumerable own NAME is not a marker either", () => {
+    // A real chant entity's non-enumerable own names are `lexicon`,
+    // `entityType`, `kind`, `props`, `attributes` and `Ref`. Reading "any
+    // non-enumerable own property" as the marker is close to "any chant object".
+    const o = {};
+    Object.defineProperty(o, "props", { value: {}, enumerable: false });
+    Object.defineProperty(o, "entityType", { value: "Bucket", enumerable: false });
+    expect(isDeclarable(o)).toBe(false);
+  });
+
+  test("an ENUMERABLE declarable symbol is refused", () => {
+    // F-Host-Interface item 1 says non-enumerable, and it matters: an
+    // enumerable marker travels through a spread and would reach an artifact.
+    const o = {};
+    Object.defineProperty(o, Symbol.for("x.declarable"), { value: true, enumerable: true });
+    expect(isDeclarable(o)).toBe(false);
+  });
+
+  test("a declarable symbol whose value is not true is refused", () => {
+    expect(isDeclarable(marked(Symbol.for("x.declarable"), false))).toBe(false);
+    expect(isDeclarable(marked(Symbol.for("x.declarable"), "yes"))).toBe(false);
+  });
+
+  test("a symbol that merely contains the word is refused", () => {
+    // Suffix, not substring: `declarable.thing` is not a declarable marker.
+    expect(isDeclarable(marked(Symbol.for("x.declarable.thing")))).toBe(false);
+    expect(isDeclarable(marked(Symbol.for("notdeclarable")))).toBe(false);
+  });
+});

package/src/declarable.ts

@@ -48,15 +48,80 @@ export interface CoreOutput extends Declarable {
 }
 
 /**
- * Type guard to check if a value is a Declarable
+ * The suffix a declarable marker's symbol description ends with.
+ *
+ * chant#2444 — what makes a marker mean "entity" rather than "some other kind
+ * of chant value". `Symbol.for("chant.declarable")` has it; so does the
+ * specification host's `Symbol.for("tsad.conformance.declarable")`.
+ */
+const DECLARABLE_MARKER_SUFFIX = ".declarable";
+
+/**
+ * Type guard to check if a value is a Declarable.
+ *
+ * chant#2444 — accepts an entity a HOST built, not only one chant built.
+ *
+ * `F-Host-Interface` item 1 says an entity carries a non-enumerable declarable
+ * marker, and a host supplies its own: the specification's conformance host
+ * marks with `Symbol.for("tsad.conformance.declarable")`. Testing identity
+ * against chant's symbol alone refused those for not being chant's rather than
+ * for being malformed, which is what chant#2442 hit inside composite member
+ * validation and what would otherwise keep biting in the entity tallies and the
+ * revival pass-through.
+ *
+ * ## Why NOT the reference implementation's reading
+ *
+ * The reference reads L6.1 as "any own symbol or non-enumerable own property",
+ * which is right in its domain and **unsafe in chant's**. Two measurements say
+ * so, and both were taken rather than assumed:
+ *
+ *   - A real chant entity's non-enumerable own NAMES are `lexicon`,
+ *     `entityType`, `kind`, `props`, `attributes`, `Ref`. "Any non-enumerable
+ *     own property" is therefore close to "any chant object at all".
+ *   - chant has SEVEN marker symbols, not one — `chant.intrinsic`,
+ *     `chant.composite`, `chant.stackOutput`, `chant.lexiconOutput`,
+ *     `chant.effect-receipt`, `chant.secret-declaration`, `chant.childProject`
+ *     — each a non-enumerable own symbol set to `true`. Under "any own symbol"
+ *     an Intrinsic and a StackOutput both classify as Declarable, which is a
+ *     worse bug than the one being fixed: they would enter the entity tallies.
+ *
+ * The reference can read any symbol because its domain has one. chant
+ * distinguishes seven kinds BY symbol identity, so it needs the marker's name.
+ * Hence the suffix: the marker must say `declarable`, whoever owns it.
+ *
+ * ## What the suffix cannot do
+ *
+ * It is a convention, not a registry. A host that marks with, say,
+ * `Symbol.for("acme.entity")` carries a perfectly good non-enumerable marker
+ * and is refused here, because nothing in this function knows that package is
+ * one the caller named. The context that would settle it —
+ * `FoldProjectOptions.lexiconPackages`, chant#2438 — lives in the fold path and
+ * does not reach a type guard called from a dozen places.
+ *
+ * That is a deliberate trade, not an oversight: a convention that refuses an
+ * unknown-but-valid marker costs a host one symbol name, while a rule loose
+ * enough to accept any marker miscounts chant's own seven kinds on every build.
+ * If a real host ever needs the other side of it, the fix is to thread the
+ * named packages through rather than to widen the test.
  */
 export function isDeclarable(value: unknown): value is Declarable {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    DECLARABLE_MARKER in value &&
-    (value as Record<symbol, unknown>)[DECLARABLE_MARKER] === true
-  );
+  if (typeof value !== "object" || value === null) return false;
+  // chant's own, which is every entity a chant build makes.
+  if ((value as Record<symbol, unknown>)[DECLARABLE_MARKER] === true) return true;
+  return carriesForeignDeclarableMarker(value);
+}
+
+/** A declarable marker some other implementation owns — see {@link isDeclarable}. */
+function carriesForeignDeclarableMarker(value: object): boolean {
+  for (const marker of Object.getOwnPropertySymbols(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, marker);
+    // Non-enumerable and `true`, per F-Host-Interface item 1. An enumerable
+    // symbol would travel through a spread and reach an artifact, which a
+    // marker must not.
+    if (descriptor === undefined || descriptor.enumerable || descriptor.value !== true) continue;
+    if (marker.description?.endsWith(DECLARABLE_MARKER_SUFFIX) === true) return true;
+  }
+  return false;
 }
 
 /**

package/src/discovery/sandbox/driver.ts

@@ -85,6 +85,7 @@ export function generateDriverSource(options: GenerateDriverOptions): string {
     `import { classifyChildError } from ${lit(CHILD_ERRORS_MODULE)};`,
     `import { getProvenance } from ${lit(PROVENANCE_MODULE)};`,
     `import { setBuildParams } from ${lit(PARAMS_MODULE)};`,
+    `import { writeSync } from "node:fs";`,
     ``,
     `const BUILD_ROOT = ${lit(buildRoot)};`,
     ``,
@@ -95,7 +96,29 @@ export function generateDriverSource(options: GenerateDriverOptions): string {
     // them exactly. Bound before any project import below.
     `setBuildParams(${lit({ ...currentBuildParams })});`,
     ``,
+    // chant#2461 — which file was being imported when the loop drained.
+    //
+    // A project file whose module scope awaits something that never settles
+    // makes its `await import(...)` never complete. Nothing keeps the loop
+    // alive, so Node exits 0 having sent nothing, and `main().catch` never
+    // fires because an unsettled promise is not a rejection. The parent then
+    // knows only that the child vanished.
+    //
+    // The child DOES know, right up to the moment it exits. `process.on("exit")`
+    // runs synchronously, so it cannot `process.send` — that is asynchronous and
+    // the channel will never be serviced — but a synchronous `writeSync` to fd 2
+    // lands, and the parent already captures and forwards stderr.
+    `let importing;`,
+    `let reported = false;`,
+    `process.on("exit", () => {`,
+    `  if (reported || importing === undefined) return;`,
+    `  writeSync(2, "chant: this file's module scope never finished evaluating, so the build could not " +`,
+    `    "report anything: " + importing + "\\n  A top-level \`await\` that never settles does this. " +`,
+    `    "Nothing is thrown, so nothing else can name it (chant#2461).\\n");`,
+    `});`,
+    ``,
     `function send(payload) {`,
+    `  reported = true;`,
     `  if (typeof process.send === "function") process.send(payload);`,
     `  else console.log(JSON.stringify(payload));`,
     `}`,
@@ -115,12 +138,14 @@ export function generateDriverSource(options: GenerateDriverOptions): string {
 
   for (const file of files) {
     lines.push(
+      `  importing = ${lit(file)};`,
       `  try {`,
       `    const mod = await import(${lit(file)});`,
       `    modules.push({ file: ${lit(file)}, exports: mod });`,
       `  } catch (err) {`,
       `    errors.push(classifyChildError(${lit(file)}, err).toJSON());`,
       `  }`,
+      `  importing = undefined;`,
     );
   }