@intentius/chant 0.37.2 → 0.38.0

package/src/cli/commands/check-lexicon-plugin.ts

@@ -0,0 +1,115 @@
+/**
+ * Loading a lexicon's plugin so completeness checks can look at what it
+ * actually registers (#1342).
+ *
+ * `check-lexicon`'s checks were almost all existence assertions over the
+ * directory: `src/lsp/completions.ts exists`, `At least 1 lint rule in
+ * src/lint/rules/`. A file with the right name is not the contract — the
+ * contract is the member the plugin exposes, because that is what core
+ * dispatches through. helm is the proof: it ships `src/lsp/completions.ts` and
+ * `src/lsp/hover.ts`, both with passing tests, exports `helmCompletions` and
+ * `helmHover` from its index, and never sets `completionProvider` or
+ * `hoverProvider` on the plugin. `cli/lsp/server.ts` dispatches through exactly
+ * those fields, so helm's LSP support is unreachable in an editor — while tier 1
+ * (the files) and tier 2 (the tests) both passed.
+ *
+ * Resolution is directory-local rather than by package name: `chant dev
+ * check-lexicon <dir>` should work on a lexicon that is not installed, and
+ * `loadPlugin` in ../plugins.ts imports `@intentius/chant-lexicon-<name>`,
+ * which requires it to be.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { isAbsolute, join, resolve } from "path";
+import { pathToFileURL } from "url";
+import { isLexiconPlugin, type LexiconPlugin } from "../../lexicon";
+
+export interface LoadedLexicon {
+  /** The plugin, when the package exported one. */
+  plugin?: LexiconPlugin;
+  /** Why loading failed, for a check's `detail`. */
+  error?: string;
+  /** The entry point that was imported, for diagnostics. */
+  entry?: string;
+}
+
+/**
+ * The module a lexicon package presents to consumers.
+ *
+ * Tier 1 requires `exports["."].default` to be `./src/index.ts`, so that is the
+ * first choice — it is the module core itself imports. The fallbacks keep this
+ * usable on a lexicon that has not reached that check yet.
+ */
+export function pluginEntryFor(dir: string): string | undefined {
+  const candidates: string[] = [];
+  try {
+    const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")) as {
+      exports?: { "."?: { default?: string } };
+      main?: string;
+    };
+    for (const declared of [pkg.exports?.["."]?.default, pkg.main]) {
+      if (typeof declared === "string") candidates.push(declared);
+    }
+  } catch {
+    // no package.json, or unreadable — fall through to the conventional paths
+  }
+  candidates.push("./src/index.ts", "./src/plugin.ts");
+
+  for (const candidate of candidates) {
+    const path = isAbsolute(candidate) ? candidate : resolve(dir, candidate);
+    if (existsSync(path)) return path;
+  }
+  return undefined;
+}
+
+/**
+ * Import a lexicon directory and return the `LexiconPlugin` it exports.
+ *
+ * Never throws: a lexicon that cannot be loaded is a finding, not a crash, and
+ * every caller reports it as a failed check rather than aborting the run.
+ */
+export async function loadLexiconFromDir(dir: string): Promise<LoadedLexicon> {
+  const entry = pluginEntryFor(dir);
+  if (!entry) {
+    return { error: "no importable entry point (looked for package.json exports, src/index.ts, src/plugin.ts)" };
+  }
+
+  let mod: Record<string, unknown>;
+  try {
+    mod = (await import(pathToFileURL(entry).href)) as Record<string, unknown>;
+  } catch (error) {
+    return { entry, error: `import failed: ${error instanceof Error ? error.message : String(error)}` };
+  }
+
+  for (const value of Object.values(mod)) {
+    if (isLexiconPlugin(value)) return { plugin: value, entry };
+  }
+  // A default export whose own members are the plugin (some lexicons re-export
+  // a namespace rather than the object itself).
+  const fallback = (mod.default ?? {}) as Record<string, unknown>;
+  for (const value of Object.values(fallback)) {
+    if (isLexiconPlugin(value)) return { plugin: value, entry };
+  }
+
+  return { entry, error: "the module exports no LexiconPlugin" };
+}
+
+/** Whether the plugin exposes a callable member under `name`. */
+export function registers(plugin: LexiconPlugin | undefined, name: keyof LexiconPlugin): boolean {
+  return typeof plugin?.[name] === "function";
+}
+
+/**
+ * Call a plugin member that returns a list, treating a throw as an empty list.
+ *
+ * A member that throws is not a registration — it is worse than an absent one,
+ * and the check that counts its results should fail rather than the whole run.
+ */
+export function safeList<T>(fn: (() => T[]) | undefined): { items: T[]; error?: string } {
+  if (typeof fn !== "function") return { items: [] };
+  try {
+    return { items: fn() ?? [] };
+  } catch (error) {
+    return { items: [], error: error instanceof Error ? error.message : String(error) };
+  }
+}

package/src/cli/commands/check-lexicon.ts

@@ -3,6 +3,9 @@ import { join, basename } from "path";
 import { auditIntrinsics } from "./check-lexicon-intrinsics";
 import { checkExamplesBuild } from "./check-lexicon-examples";
 import { auditDocsReachability } from "./check-lexicon-docs";
+import { auditMcpNames } from "./check-lexicon-mcp";
+import { loadLexiconFromDir, registers, safeList } from "./check-lexicon-plugin";
+import { RULE_CATALOG } from "../../audit/catalog";
 
 // ── Types ────────────────────────────────────────────────────────────
 
@@ -73,45 +76,100 @@ export async function checkLexicon(dir: string): Promise<CheckResult> {
 
   // ── Tier 1: Required ───────────────────────────────────────────
 
+  // #1342 — a capability is present when the plugin exposes it, not when a file
+  // with the right name sits on disk. The checks below used to be existence
+  // assertions, which is how helm shipped `src/lsp/completions.ts` and
+  // `src/lsp/hover.ts` (with tests) while registering neither provider, and
+  // passed every tier. `cli/lsp/server.ts` dispatches through the plugin
+  // members, so those files were unreachable in an editor.
+  const loaded = await loadLexiconFromDir(dir);
+  const plugin = loaded.plugin;
+
+  items.push({
+    name: "The package exports a LexiconPlugin",
+    tier: 1,
+    pass: plugin !== undefined,
+    detail: loaded.error ?? (loaded.entry ? `exported by ${basename(loaded.entry)}` : undefined),
+  });
+
+  const serializer = plugin?.serializer as { name?: unknown; rulePrefix?: unknown; serialize?: unknown } | undefined;
+  const serializerOk =
+    typeof serializer?.name === "string" &&
+    typeof serializer?.rulePrefix === "string" &&
+    typeof serializer?.serialize === "function";
   items.push({
-    name: "src/plugin.ts exists",
+    name: "The plugin exposes a Serializer with a name and rule prefix",
     tier: 1,
-    pass: existsSync(join(dir, "src/plugin.ts")),
+    pass: serializerOk,
+    detail: serializerOk
+      ? `${String(serializer?.name)} (${String(serializer?.rulePrefix)})`
+      : plugin
+        ? "serializer is missing name, rulePrefix, or serialize"
+        : undefined,
   });
 
+  const lintRules = safeList(plugin?.lintRules?.bind(plugin));
   items.push({
-    name: "src/serializer.ts exists",
+    name: "lintRules() returns at least 1 rule",
     tier: 1,
-    pass: existsSync(join(dir, "src/serializer.ts")),
+    pass: lintRules.items.length > 0,
+    detail: lintRules.error ? `threw: ${lintRules.error}` : `${lintRules.items.length} rule(s)`,
   });
 
-  const ruleFiles = listTsFiles(join(dir, "src/lint/rules"), ["index.ts"]);
+  const postSynthChecks = safeList(plugin?.postSynthChecks?.bind(plugin));
   items.push({
-    name: "At least 1 lint rule in src/lint/rules/",
+    name: "postSynthChecks() returns at least 1 check",
     tier: 1,
-    pass: ruleFiles.length > 0,
-    detail: ruleFiles.length > 0 ? `${ruleFiles.length} rule(s)` : undefined,
+    pass: postSynthChecks.items.length > 0,
+    detail: postSynthChecks.error
+      ? `threw: ${postSynthChecks.error}`
+      : `${postSynthChecks.items.length} check(s)`,
+  });
+
+  // #1349 — `rulePrefix` exists so ids do not collide when several lexicons are
+  // loaded together (forgejo wraps github's rules as `WFJ-GHA0xx` for exactly
+  // that reason), and it was checked by nothing. k8s shipped five `ARGO0xx`
+  // checks outside its declared `WK8`. Core's cross-cutting ids are exempt:
+  // they belong to core, not to whichever lexicon surfaces them.
+  const declaredPrefixes = [
+    typeof serializer?.rulePrefix === "string" ? serializer.rulePrefix : "",
+    ...((plugin?.serializer as { extraRulePrefixes?: readonly string[] } | undefined)?.extraRulePrefixes ?? []),
+  ].filter((p) => p.length > 0);
+  const allRuleIds = [
+    ...lintRules.items.map((r) => (r as { id?: string }).id),
+    ...postSynthChecks.items.map((c) => (c as { id?: string }).id),
+  ].filter((id): id is string => typeof id === "string");
+  const offPrefix = allRuleIds.filter(
+    (id) => !(id in RULE_CATALOG) && !declaredPrefixes.some((p) => id.startsWith(p)),
+  );
+  items.push({
+    name: "Every rule id starts with a declared rule prefix",
+    tier: 1,
+    pass: declaredPrefixes.length > 0 && offPrefix.length === 0,
+    detail:
+      offPrefix.length > 0
+        ? `${offPrefix.length} outside ${declaredPrefixes.join("/")}: ${[...new Set(offPrefix)].slice(0, 6).join(", ")}`
+        : declaredPrefixes.length > 0
+          ? `${allRuleIds.length} id(s) under ${declaredPrefixes.join("/")}`
+          : "no rule prefix declared",
   });
 
-  const postSynthFiles = listTsFiles(join(dir, "src/lint/post-synth"), ["index.ts"])
-    .filter((f) => !f.endsWith("-helpers.ts") && f !== "helpers.ts");
   items.push({
-    name: "At least 1 post-synth check",
+    name: "The plugin registers completionProvider",
     tier: 1,
-    pass: postSynthFiles.length > 0,
-    detail: postSynthFiles.length > 0 ? `${postSynthFiles.length} check(s)` : undefined,
+    pass: registers(plugin, "completionProvider"),
   });
 
   items.push({
-    name: "src/lsp/completions.ts exists",
+    name: "The plugin registers hoverProvider",
     tier: 1,
-    pass: existsSync(join(dir, "src/lsp/completions.ts")),
+    pass: registers(plugin, "hoverProvider"),
   });
 
   items.push({
-    name: "src/lsp/hover.ts exists",
+    name: "The plugin registers docs()",
     tier: 1,
-    pass: existsSync(join(dir, "src/lsp/hover.ts")),
+    pass: registers(plugin, "docs"),
   });
 
   items.push({
@@ -262,6 +320,24 @@ export async function checkLexicon(dir: string): Promise<CheckResult> {
           : undefined,
   });
 
+  // #1341 — core namespaces MCP contributions, and so do the shared helpers and
+  // most lexicons, so the names agents actually saw were `gitlab:gitlab:diff`
+  // and `chant://azure/chant://lexicon/azure/catalog`. The check is on the
+  // registered name rather than the declared one: three authored forms are in
+  // use and all of them are fine, but only one registered shape is.
+  const mcpNames = await auditMcpNames(dir);
+  items.push({
+    name: "MCP tools and resources register under one well-formed namespace",
+    tier: 1,
+    pass: mcpNames.violations.length === 0,
+    detail:
+      mcpNames.violations.length > 0
+        ? mcpNames.violations.join(" | ")
+        : mcpNames.loaded
+          ? `${mcpNames.checked} contribution(s) checked`
+          : "lexicon could not be loaded — not checked",
+  });
+
   const hasPluginTest = findFiles(join(dir, "src"), (n) => n === "plugin.test.ts").length > 0;
   items.push({
     name: "plugin.test.ts exists",
@@ -302,21 +378,76 @@ export async function checkLexicon(dir: string): Promise<CheckResult> {
 
   const pluginContent = readOr(join(dir, "src/plugin.ts"));
 
+  // #1342 — these were a regex over plugin.ts source text, which passed on a
+  // method declared in a form the regex happened to match and on one that
+  // throws when called. Ask the plugin instead.
   for (const method of ["mcpTools", "mcpResources", "skills", "detectTemplate", "initTemplates"] as const) {
-    // Check for uncommented method: line starts with optional whitespace, then the method name
-    // Exclude lines that start with // or * (comment blocks)
-    const lines = pluginContent.split("\n");
-    const hasUncommented = lines.some((line) => {
-      const trimmed = line.trim();
-      return trimmed.startsWith(`${method}(`) || trimmed.startsWith(`${method} (`);
-    });
     items.push({
-      name: `plugin.ts has uncommented ${method}`,
+      name: `The plugin registers ${method}`,
       tier: 2,
-      pass: hasUncommented,
+      pass: registers(plugin, method),
     });
   }
 
+  // #1346 — `resolveAuditCatalog` contributes nothing for a lexicon that omits
+  // the method, silently, so its checks surface in `chant audit` with no title,
+  // tier, fix kind, or category. Tier 2 rather than tier 1: the lexicon builds
+  // and lints correctly without it; what suffers is one command's output.
+  const auditCatalog = (() => {
+    try {
+      return plugin?.auditCatalog?.() ?? {};
+    } catch {
+      return {};
+    }
+  })();
+  const uncatalogued = postSynthChecks.items
+    .map((c) => (c as { id?: string }).id)
+    .filter((id): id is string => typeof id === "string" && !(id in auditCatalog) && !(id in RULE_CATALOG));
+  items.push({
+    name: "auditCatalog() covers every post-synth check",
+    tier: 2,
+    pass: uncatalogued.length === 0,
+    detail:
+      uncatalogued.length > 0
+        ? `${uncatalogued.length} without metadata: ${uncatalogued.slice(0, 6).join(", ")}`
+        : `${Object.keys(auditCatalog).length} entry/entries`,
+  });
+
+  // #1348 — the marker channel is a claim: declaring `reads: ["exportResources"]`
+  // while not implementing `exportResources` promises a verdict from a path
+  // that does not exist. The behavioral half lives in the observation
+  // conformance suite, which holds a declared path to a real verdict and an
+  // undeclared one to `unknown`; this is the static half.
+  const channel = plugin?.ownershipChannel;
+  const channelProblems: string[] = [];
+  if (channel) {
+    for (const path of channel.reads) {
+      if (!registers(plugin, path as keyof typeof plugin)) {
+        channelProblems.push(`declares a marker channel on ${path}, which the plugin does not implement`);
+      }
+    }
+    const keys = channel.keys as { managedBy?: unknown; stack?: unknown; env?: unknown } | undefined;
+    for (const key of ["managedBy", "stack", "env"] as const) {
+      if (typeof keys?.[key] !== "string" || (keys[key] as string).length === 0) {
+        channelProblems.push(`marker keys are missing ${key}`);
+      }
+    }
+    if (channel.reads.length === 0) {
+      channelProblems.push("declares marker keys but no read path — nothing can resolve a verdict");
+    }
+  }
+  items.push({
+    name: "Any declared ownership channel names paths the plugin implements",
+    tier: 2,
+    pass: channelProblems.length === 0,
+    detail:
+      channelProblems.length > 0
+        ? channelProblems.join("; ")
+        : channel
+          ? `marker on ${channel.reads.join(", ")}`
+          : "no marker channel — every verdict must be unknown",
+  });
+
   const compositeFiles = listTsFiles(join(dir, "src/composites"), ["index.ts"]);
   items.push({
     name: "At least 1 composite in src/composites/",

package/src/cli/handlers/components.test.ts

@@ -4,6 +4,18 @@ import type { LexiconPlugin, ResourceMetadata } from "../../lexicon";
 import type { BuildResult } from "../../build";
 import type { ParsedArgs } from "../registry";
 
+/**
+ * The aws emulator capability, as the real plugin declares it. `--live`
+ * endpoint injection reads the endpoint var off this rather than off a map
+ * keyed by lexicon name (#1345), so a mock that omits it gets no injection —
+ * the same thing that would happen in production.
+ */
+const awsEmulatorStub = {
+  spec: { name: "chant-floci", image: "floci/floci:1.5.34", containerPort: 4566, healthPath: "/_localstack/health" },
+  env: (endpoint: string) => ({ AWS_ENDPOINT_URL: endpoint, AWS_ACCESS_KEY_ID: "test" }),
+};
+
+
 const getHeadCommitMock = vi.fn();
 const fetchLifecycleMock = vi.fn();
 const pushLifecycleMock = vi.fn();
@@ -256,6 +268,7 @@ describe("components handlers", () => {
       const plugins: LexiconPlugin[] = [
         createMockPlugin({
           name: "aws",
+          emulator: awsEmulatorStub,
           describeResources: staticDescribeResources({ svc: meta() }),
         }),
       ];
@@ -306,6 +319,7 @@ describe("components handlers", () => {
         const plugins: LexiconPlugin[] = [
           createMockPlugin({
             name: "aws",
+            emulator: awsEmulatorStub,
             describeResources: async () => {
               seenDuringDescribe = process.env.AWS_ENDPOINT_URL;
               return { svc: meta() };
@@ -339,6 +353,7 @@ describe("components handlers", () => {
       const plugins: LexiconPlugin[] = [
         createMockPlugin({
           name: "aws",
+          emulator: awsEmulatorStub,
           describeResources: staticDescribeResources({ mystery: meta() }),
         }),
       ];
@@ -391,6 +406,7 @@ describe("components handlers", () => {
       const plugins: LexiconPlugin[] = [
         createMockPlugin({
           name: "aws",
+          emulator: awsEmulatorStub,
           describeResources: staticDescribeResources({ "search-service-v2": meta() }),
         }),
       ];
@@ -434,6 +450,7 @@ describe("components handlers", () => {
       const plugins: LexiconPlugin[] = [
         createMockPlugin({
           name: "aws",
+          emulator: awsEmulatorStub,
           describeResources: staticDescribeResources({ svc: meta() }),
         }),
       ];

package/src/cli/handlers/components.ts

@@ -350,7 +350,7 @@ export async function runComponentsStatus(ctx: CommandContext): Promise<number>
       const endpointResult = applyLiveEndpoint(
         config.environments,
         environment,
-        plugins.filter((p) => p.describeResources || p.describeStackStatus).map((p) => p.name),
+        plugins.filter((p) => p.describeResources || p.describeStackStatus),
       );
       if (endpointResult.notice) console.error(formatWarning({ message: endpointResult.notice }));
       try {

package/src/cli/handlers/emulator.ts

@@ -1,6 +1,6 @@
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
-import { emulatorLifecycle } from "../../op";
+import { emulatorLifecycle, emulatorsOf } from "../../op";
 import { formatError, formatWarning, formatSuccess } from "../format";
 import type { CommandContext } from "../registry";
 
@@ -48,8 +48,13 @@ export async function runEmulator(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
-  const withEmulator = plugins.filter((p) => p.emulator && (!args.lexicon || p.name === args.lexicon));
-  if (withEmulator.length === 0) {
+  // One entry per emulator, not per lexicon (#1345): fly ships two — mudflaps
+  // for the Machines API and spritzer for Sprites — and reporting a lexicon
+  // would have to pick one of them.
+  const targets = plugins
+    .filter((p) => !args.lexicon || p.name === args.lexicon)
+    .flatMap((p) => emulatorsOf(p.emulator).map((cap) => ({ lexicon: p.name, cap })));
+  if (targets.length === 0) {
     if (args.json) {
       console.log(JSON.stringify({ emulators: [] }));
       return 0;
@@ -63,19 +68,18 @@ export async function runEmulator(ctx: CommandContext): Promise<number> {
   }
 
   const reports: EmulatorReport[] = [];
-  for (const p of withEmulator) {
-    const cap = p.emulator!;
+  for (const { lexicon, cap } of targets) {
     const lc = emulatorLifecycle(cap.spec);
     if (action === "up") {
       const { endpoint } = await lc.up();
-      reports.push({ lexicon: p.name, name: cap.spec.name, endpoint, env: cap.env(endpoint) });
+      reports.push({ lexicon, name: cap.spec.name, endpoint, env: cap.env(endpoint) });
     } else if (action === "down") {
       await lc.down();
-      reports.push({ lexicon: p.name, name: cap.spec.name, endpoint: "", env: {} });
+      reports.push({ lexicon, name: cap.spec.name, endpoint: "", env: {} });
     } else {
       const running = await isRunning(cap.spec.name);
       const endpoint = running ? lc.endpoint(cap.spec.containerPort) : "";
-      reports.push({ lexicon: p.name, name: cap.spec.name, endpoint, env: endpoint ? cap.env(endpoint) : {} });
+      reports.push({ lexicon, name: cap.spec.name, endpoint, env: endpoint ? cap.env(endpoint) : {} });
     }
   }
 

package/src/cli/handlers/graph.test.ts

@@ -3,6 +3,18 @@ import type { ParsedArgs } from "../registry";
 import { DECLARABLE_MARKER, type Declarable } from "../../declarable";
 import { AttrRef } from "../../attrref";
 
+/**
+ * The aws emulator capability, as the real plugin declares it. `--live`
+ * endpoint injection reads the endpoint var off this rather than off a map
+ * keyed by lexicon name (#1345), so a mock that omits it gets no injection —
+ * which is the same thing that would happen in production.
+ */
+const awsEmulatorStub = {
+  spec: { name: "chant-floci", image: "floci/floci:1.5.34", containerPort: 4566, healthPath: "/_localstack/health" },
+  env: (endpoint: string) => ({ AWS_ENDPOINT_URL: endpoint, AWS_ACCESS_KEY_ID: "test" }),
+};
+
+
 const discoverOpsMock = vi.fn();
 vi.mock("../../op/discover", () => ({
   discoverOps: () => discoverOpsMock(),
@@ -10,7 +22,9 @@ vi.mock("../../op/discover", () => ({
 
 const discoverMock = vi.fn();
 vi.mock("../../discovery/index", () => ({
-  discover: () => discoverMock(),
+  // Forwards its arguments so a test can assert what the handler passed —
+  // `buildParams` in particular (#1359).
+  discover: (...a: unknown[]) => discoverMock(...a),
 }));
 
 const lintMock = vi.fn();
@@ -62,11 +76,13 @@ vi.mock("../../components/discover", () => ({
   discoverComponents: (...a: unknown[]) => discoverComponentsMock(...a),
 }));
 const loadChantConfigMock = vi.fn();
+const loadChantConfigUpwardMock = vi.fn();
 vi.mock("../../config", async () => {
   const actual = await vi.importActual<typeof import("../../config")>("../../config");
   return {
     ...actual,
     loadChantConfig: (...a: unknown[]) => loadChantConfigMock(...a),
+    loadChantConfigUpward: (...a: unknown[]) => loadChantConfigUpwardMock(...a),
   };
 });
 vi.mock("../../build", () => ({
@@ -124,6 +140,8 @@ describe("runGraph", () => {
     resolveLexMock.mockReset();
     loadChantConfigMock.mockReset();
     loadChantConfigMock.mockResolvedValue({ config: {} });
+    loadChantConfigUpwardMock.mockReset();
+    loadChantConfigUpwardMock.mockResolvedValue({ config: {} });
   });
 
   describe("Op graph (default)", () => {
@@ -186,6 +204,47 @@ describe("runGraph", () => {
       expect(ir.edges).toContainEqual({ from: "subnet", to: "vpc", kind: "ref", viaAttr: "network" });
     });
 
+    // #1339 — `chant graph` discovered source with `params.*` empty, so a
+    // declaration conditioned on a build parameter always took its default:
+    // the graph showed one shape whatever `--param` or a declared `env:`
+    // mapping said, while `chant build` on the same source showed another.
+    describe("build-time parameters reach discovery (#1359)", () => {
+      const withTierParam = (): void => {
+        loadChantConfigUpwardMock.mockResolvedValue({
+          config: { buildParams: { tier: { type: "string", enum: ["light", "prod"], default: "light" } } },
+        });
+      };
+
+      test("--param is resolved and passed to discover", async () => {
+        lintClean(); discovered(); withTierParam();
+        const exit = await runGraph({
+          args: makeArgs({ format: "ir", param: ["tier=prod"] }),
+          plugins: [],
+          serializers: [],
+        });
+        expect(exit).toBe(0);
+        const [, options] = discoverMock.mock.calls[0] as [string, { buildParams?: Array<{ name: string; value: unknown }> }];
+        expect(options.buildParams).toContainEqual(expect.objectContaining({ name: "tier", value: "prod" }));
+      });
+
+      test("a declared default is passed too, so discovery never sees an empty params object", async () => {
+        lintClean(); discovered(); withTierParam();
+        await runGraph({ args: makeArgs({ format: "ir" }), plugins: [], serializers: [] });
+        const [, options] = discoverMock.mock.calls[0] as [string, { buildParams?: Array<{ name: string; value: unknown }> }];
+        expect(options.buildParams).toContainEqual(expect.objectContaining({ name: "tier", value: "light" }));
+      });
+
+      test("an unresolvable parameter stops the graph rather than emitting a default one", async () => {
+        lintClean(); discovered();
+        loadChantConfigUpwardMock.mockResolvedValue({
+          config: { buildParams: { tier: { type: "string", required: true } } },
+        });
+        const exit = await runGraph({ args: makeArgs({ format: "ir" }), plugins: [], serializers: [] });
+        expect(exit).toBe(1);
+        expect(stdoutBuf.join("\n")).toBe("");
+      });
+    });
+
     test("lint gate: refuses to emit when source has lint errors", async () => {
       lintMock.mockResolvedValue({ success: false });
       const exit = await runGraph({ args: makeArgs({ format: "ir" }), plugins: [], serializers: [] });
@@ -427,7 +486,7 @@ describe("runGraph", () => {
     test("loads plugins for --live when ctx.plugins is empty", async () => {
       resolveLexMock.mockResolvedValue(["aws"]);
       loadPluginsMock.mockResolvedValue([
-        { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}) },
+        { name: "aws", serializer: {}, emulator: awsEmulatorStub, describeResources: () => Promise.resolve({}) },
       ]);
       observeMock.mockResolvedValue({
         observations: [{ lexicon: "aws", resources: { "web-vpc": { type: "AWS::EC2::VPC", status: "OK" } } }],
@@ -448,7 +507,7 @@ describe("runGraph", () => {
     test("--at graphs the recorded snapshot without reading the estate", async () => {
       resolveLexMock.mockResolvedValue(["aws"]);
       loadPluginsMock.mockResolvedValue([
-        { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}),
+        { name: "aws", serializer: {}, emulator: awsEmulatorStub, describeResources: () => Promise.resolve({}),
           enrichLiveAttrs: () => Promise.reject(new Error("must not be called on a replay")) },
       ]);
       replayMock.mockResolvedValue({
@@ -473,7 +532,7 @@ describe("runGraph", () => {
       hasSnapshotMock.mockResolvedValue(true);
       resolveLexMock.mockResolvedValue(["aws"]);
       loadPluginsMock.mockResolvedValue([
-        { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}) },
+        { name: "aws", serializer: {}, emulator: awsEmulatorStub, describeResources: () => Promise.resolve({}) },
       ]);
       observeMock.mockResolvedValue({ observations: [], errors: ["could not connect"], warnings: [] });
       const errs: string[] = [];
@@ -489,7 +548,7 @@ describe("runGraph", () => {
       hasSnapshotMock.mockResolvedValue(false);
       resolveLexMock.mockResolvedValue(["aws"]);
       loadPluginsMock.mockResolvedValue([
-        { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}) },
+        { name: "aws", serializer: {}, emulator: awsEmulatorStub, describeResources: () => Promise.resolve({}) },
       ]);
       observeMock.mockResolvedValue({ observations: [], errors: ["could not connect"], warnings: [] });
       const errs: string[] = [];
@@ -515,7 +574,7 @@ describe("runGraph", () => {
     test("single-stack project (no components): observeResources gets an empty stacks list", async () => {
       resolveLexMock.mockResolvedValue(["aws"]);
       loadPluginsMock.mockResolvedValue([
-        { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}) },
+        { name: "aws", serializer: {}, emulator: awsEmulatorStub, describeResources: () => Promise.resolve({}) },
       ]);
       observeMock.mockResolvedValue({ observations: [], errors: [], warnings: [] });
       const exit = await runGraph({ args: makeArgs({ format: "ir", live: true, env: "prod" }), plugins: [], serializers: [] });
@@ -533,7 +592,7 @@ describe("runGraph", () => {
     test("multi-stack component project: resolves each component's cfn-deploy stack(s) and passes them to observeResources", async () => {
       resolveLexMock.mockResolvedValue(["aws"]);
       loadPluginsMock.mockResolvedValue([
-        { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}) },
+        { name: "aws", serializer: {}, emulator: awsEmulatorStub, describeResources: () => Promise.resolve({}) },
       ]);
       discoverComponentsMock.mockResolvedValue({
         errors: [],
@@ -580,7 +639,7 @@ describe("runGraph", () => {
     test("ChantConfig.stacks: observeResources gets every declared stack, with its region and src", async () => {
       resolveLexMock.mockResolvedValue(["aws"]);
       loadPluginsMock.mockResolvedValue([
-        { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}) },
+        { name: "aws", serializer: {}, emulator: awsEmulatorStub, describeResources: () => Promise.resolve({}) },
       ]);
       loadChantConfigMock.mockResolvedValue({
         config: {
@@ -609,7 +668,7 @@ describe("runGraph", () => {
     test("ChantConfig.stacks: a stack also derived from a component is not observed twice", async () => {
       resolveLexMock.mockResolvedValue(["aws"]);
       loadPluginsMock.mockResolvedValue([
-        { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}) },
+        { name: "aws", serializer: {}, emulator: awsEmulatorStub, describeResources: () => Promise.resolve({}) },
       ]);
       discoverComponentsMock.mockResolvedValue({
         errors: [],
@@ -636,7 +695,7 @@ describe("runGraph", () => {
     test("component discovery errors: falls back to the single-stack path with a warning", async () => {
       resolveLexMock.mockResolvedValue(["aws"]);
       loadPluginsMock.mockResolvedValue([
-        { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}) },
+        { name: "aws", serializer: {}, emulator: awsEmulatorStub, describeResources: () => Promise.resolve({}) },
       ]);
       discoverComponentsMock.mockResolvedValue({ errors: [{ message: "bad component" }], sourceFiles: [], components: new Map() });
       observeMock.mockResolvedValue({ observations: [], errors: [], warnings: [] });
@@ -667,7 +726,7 @@ describe("runGraph", () => {
         });
         resolveLexMock.mockResolvedValue(["aws"]);
         loadPluginsMock.mockResolvedValue([
-          { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}) },
+          { name: "aws", serializer: {}, emulator: awsEmulatorStub, describeResources: () => Promise.resolve({}) },
         ]);
         let seenDuringObserve: string | undefined;
         observeMock.mockImplementation(async () => {
@@ -688,7 +747,7 @@ describe("runGraph", () => {
         });
         resolveLexMock.mockResolvedValue(["aws"]);
         loadPluginsMock.mockResolvedValue([
-          { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}) },
+          { name: "aws", serializer: {}, emulator: awsEmulatorStub, describeResources: () => Promise.resolve({}) },
         ]);
         let seenDuringObserve: string | undefined;
         observeMock.mockImplementation(async () => {