@intentius/chant 0.38.0 → 0.41.0

package/src/discovery/index.ts

@@ -11,6 +11,64 @@ import { getProvenance } from "../provenance";
 import type { BuildParamProvenance } from "../provenance";
 import { buildParamValues } from "../build-params";
 import { setBuildParams } from "../params";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, parse } from "node:path";
+
+/**
+ * Warn when resolved build parameters cannot reach project source (#1421).
+ *
+ * chant's core is ESM. When the project is CommonJS — `"type": "commonjs"`, or
+ * no `type` field — tsx loads project source through the CommonJS transform, so
+ * the project's `require` of `params.ts` and core's `import` of it produce two
+ * separate module records. {@link setBuildParams} mutates one object in place;
+ * project source reads the other, and sees `{}`.
+ *
+ * The failure is silence. chant prints `[param] tier = "prod" (cli)` and then
+ * emits the graph for the default branch. `chant graph` is always affected
+ * because it always takes the run path; `chant build --no-fold` likewise. Plain
+ * `chant build` usually escapes because folding substitutes parameters
+ * statically — but a file that falls back to run inside a folded build is wrong
+ * the same way, which is why this warns regardless of `fold`.
+ *
+ * Only fires when parameters were actually resolved, so a CJS project that uses
+ * none is never nagged. `chant doctor`'s `package-type-module` check is the
+ * ambient version of the same advice.
+ *
+ * Best-effort and never throws: a project whose `package.json` cannot be found
+ * or parsed gets no warning rather than a failed build.
+ */
+function warnIfParamsCannotReachProject(path: string, values: Record<string, unknown>): void {
+  if (Object.keys(values).length === 0) return;
+  try {
+    const pkgPath = findPackageJsonUpward(path);
+    if (!pkgPath) return;
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { type?: string };
+    if (pkg.type === "module") return;
+    const found = pkg.type ? `"type": "${pkg.type}"` : "no `type` field";
+    const names = Object.keys(values).sort().join(", ");
+    console.error(
+      `warning: ${pkgPath} has ${found}, but chant is ESM — build parameters (${names}) ` +
+        `will read as empty in project source on the run path, so declarations conditioned ` +
+        `on them take their default branch. Set "type": "module". (chant #1421)`,
+    );
+  } catch {
+    // Unreadable or unparseable package.json — say nothing rather than fail.
+  }
+}
+
+/** Nearest `package.json` at or above `startDir`, or undefined. */
+function findPackageJsonUpward(startDir: string): string | undefined {
+  let dir = startDir;
+  const { root } = parse(dir);
+  for (;;) {
+    const candidate = join(dir, "package.json");
+    if (existsSync(candidate)) return candidate;
+    if (dir === root) return undefined;
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
 
 /**
  * Per-file fold-vs-run outcome (chant #1022, epic #1019), populated only
@@ -150,6 +208,7 @@ export async function discover(path: string, options?: DiscoveryOptions): Promis
   // `--watch`) never leaks into a build that supplied none.
   const buildParamValuesMap = buildParamValues(options?.buildParams ?? []);
   setBuildParams(buildParamValuesMap);
+  warnIfParamsCannotReachProject(path, buildParamValuesMap);
 
   // Step 1: Scan for TypeScript files
   const files = await findInfraFiles(path);

package/src/discovery/params-cjs-warning.test.ts

@@ -0,0 +1,75 @@
+import { describe, test, expect, vi, afterEach } from "vitest";
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { discover } from "./index";
+
+/**
+ * #1421 — chant's core is ESM. A CommonJS project's `require` of `params.ts`
+ * and core's `import` of it are two module records, so `setBuildParams`'s
+ * in-place mutation never reaches project source: it reads `{}` and every
+ * declaration conditioned on a parameter takes its default branch, silently.
+ *
+ * The fix is to stop it being silent. These assert the warning fires exactly
+ * when the hazard exists and stays quiet otherwise.
+ */
+describe("build params that cannot reach a CommonJS project (#1421)", () => {
+  const dirs: string[] = [];
+  const project = (type: string | undefined): string => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-1421-"));
+    dirs.push(dir);
+    writeFileSync(
+      join(dir, "package.json"),
+      JSON.stringify(type === undefined ? { name: "p" } : { name: "p", type }),
+    );
+    mkdirSync(join(dir, "src"));
+    writeFileSync(join(dir, "src", "main.ts"), "export const x = 1;\n");
+    return dir;
+  };
+
+  afterEach(() => {
+    for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  const warnings = async (dir: string, params: Array<{ name: string; value: unknown }>): Promise<string[]> => {
+    const seen: string[] = [];
+    vi.spyOn(console, "error").mockImplementation((...a: unknown[]) => void seen.push(a.join(" ")));
+    await discover(join(dir, "src"), {
+      buildParams: params as never,
+    });
+    return seen.filter((s) => s.includes("#1421"));
+  };
+
+  test('warns for "type": "commonjs" when parameters were resolved', async () => {
+    const out = await warnings(project("commonjs"), [{ name: "tier", value: "prod" }]);
+    expect(out).toHaveLength(1);
+    expect(out[0]).toMatch(/"type": "commonjs"/);
+    expect(out[0]).toMatch(/tier/);
+    expect(out[0]).toMatch(/Set "type": "module"/);
+  });
+
+  // The sneakier half: no `type` field at all is also CommonJS.
+  test("warns when package.json declares no type at all", async () => {
+    const out = await warnings(project(undefined), [{ name: "tier", value: "prod" }]);
+    expect(out).toHaveLength(1);
+    expect(out[0]).toMatch(/no `type` field/);
+  });
+
+  test('stays quiet for "type": "module"', async () => {
+    expect(await warnings(project("module"), [{ name: "tier", value: "prod" }])).toEqual([]);
+  });
+
+  // A CJS project using no parameters is not at risk, and must not be nagged.
+  test("stays quiet when no parameters were resolved", async () => {
+    expect(await warnings(project("commonjs"), [])).toEqual([]);
+  });
+
+  test("names every resolved parameter, sorted", async () => {
+    const out = await warnings(project("commonjs"), [
+      { name: "zone", value: "b" },
+      { name: "tier", value: "prod" },
+    ]);
+    expect(out[0]).toMatch(/\(tier, zone\)/);
+  });
+});

package/src/discovery/sandbox/driver.test.ts

@@ -0,0 +1,34 @@
+import { describe, test, expect, afterEach } from "vitest";
+import { generateDriverSource } from "./driver";
+import { setBuildParams } from "../../params";
+
+/**
+ * chant #1108 — the generated child driver must re-bind the parent's resolved
+ * build-time parameters BEFORE importing any project file: the child process
+ * starts with its own empty copy of ../../params.ts's `params` object, so
+ * without this a run-fallback file reading `params.<name>` saw `undefined`
+ * under `--sandbox` while the fold path (substituting in the parent) saw the
+ * resolved value.
+ */
+describe("generateDriverSource — build-time parameters (#1108)", () => {
+  afterEach(() => {
+    setBuildParams({});
+  });
+
+  test("embeds a snapshot of the parent's current params, bound before any project import", () => {
+    setBuildParams({ tier: "production-ha", replicas: 3, ha: true });
+    const source = generateDriverSource({ files: ["/tmp/project/a.ts"], buildRoot: "/tmp/project" });
+
+    expect(source).toContain("import { setBuildParams } from ");
+    const bindAt = source.indexOf(`setBuildParams(${JSON.stringify({ tier: "production-ha", replicas: 3, ha: true })});`);
+    const firstImportAt = source.indexOf(`await import("/tmp/project/a.ts")`);
+    expect(bindAt).toBeGreaterThan(-1);
+    expect(firstImportAt).toBeGreaterThan(-1);
+    expect(bindAt).toBeLessThan(firstImportAt);
+  });
+
+  test("with no params resolved, binds an empty snapshot (explicit, not absent)", () => {
+    const source = generateDriverSource({ files: ["/tmp/project/a.ts"], buildRoot: "/tmp/project" });
+    expect(source).toContain("setBuildParams({});");
+  });
+});

package/src/discovery/sandbox/driver.ts

@@ -1,4 +1,5 @@
 import { dirname, join } from "node:path";
+import { params as currentBuildParams } from "../../params";
 
 /**
  * chant #1045 Phase 2 — generates the source of the "driver" module that runs
@@ -46,6 +47,16 @@ const CONFIG_WIRE_MODULE = join(HERE, "config-wire.ts");
 // chant #1131 — the policy driver's build-result decoding + diagnostics contract.
 const POLICY_WIRE_MODULE = join(HERE, "policy-wire.ts");
 const POST_SYNTH_MODULE = join(dirname(DISCOVERY_DIR), "lint", "post-synth.ts");
+// chant #1108 — the shared build-time params module (../params.ts). The child
+// process starts with its own, EMPTY copy of that module's `params` object;
+// without re-binding, every run-fallback file imported in the child would see
+// `params.* === undefined` while the fold path (which substitutes values in
+// the PARENT) sees the resolved values — the exact split-brain #1064 exists
+// to prevent. esbuild resolves a project file's own
+// `import { params } from "@intentius/chant/params"` to this same absolute
+// file, so the driver's `setBuildParams` call below mutates the one object
+// every bundled import observes.
+const PARAMS_MODULE = join(dirname(DISCOVERY_DIR), "params.ts");
 
 export interface GenerateDriverOptions {
   /** Absolute paths to the run-fallback files this build decided NOT to fold — see `discover()`'s fold/taint loop in `../index.ts`. */
@@ -73,9 +84,17 @@ export function generateDriverSource(options: GenerateDriverOptions): string {
     `import { encodeEntitySet } from ${lit(ENTITY_WIRE_CODEC_MODULE)};`,
     `import { classifyChildError } from ${lit(CHILD_ERRORS_MODULE)};`,
     `import { getProvenance } from ${lit(PROVENANCE_MODULE)};`,
+    `import { setBuildParams } from ${lit(PARAMS_MODULE)};`,
     ``,
     `const BUILD_ROOT = ${lit(buildRoot)};`,
     ``,
+    // chant #1108 — a snapshot of the PARENT's resolved build-time parameter
+    // values, embedded as a literal at generation time (the parent bound them
+    // via applyBuildParams/discover() before this source was generated).
+    // Values are declared-scalar only (BuildParamValue), so JSON round-trips
+    // them exactly. Bound before any project import below.
+    `setBuildParams(${lit({ ...currentBuildParams })});`,
+    ``,
     `function send(payload) {`,
     `  if (typeof process.send === "function") process.send(payload);`,
     `  else console.log(JSON.stringify(payload));`,

package/src/graph-declared.test.ts

@@ -0,0 +1,86 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { buildDeclaredPerStack } from "./graph-declared";
+
+/**
+ * Side-by-side stacks (#1433) — several stacks declared in config, each with its
+ * own `src`, composed into one graph.
+ *
+ * This is chant's ordinary multi-stack shape, as distinct from directory
+ * partitioning (subdirectories of one `src/`), and it is the one where stack
+ * membership is *declared* rather than inferred: the caller passes the names, and
+ * `buildDeclaredPerStack` already renames every node `${stack}::${id}`. The
+ * grouping was being discarded, so `groups.byStack` — the axis a boundary-box
+ * renderer reads — came back empty for exactly the projects that have real
+ * stacks to box.
+ */
+let dir: string;
+
+// The shape discovery actually recognises — a plain object carrying the
+// declarable marker, as `env.test.ts`'s fixtures do.
+const stackSrc = (resource: string) =>
+  `export const ${resource} = { entityType: "Thing", lexicon: "aws", kind: "resource", [Symbol.for("chant.declarable")]: true };\n`;
+
+beforeAll(() => {
+  dir = mkdtempSync(join(tmpdir(), "chant-side-by-side-"));
+  for (const [stack, resource] of [
+    ["network", "vpc"],
+    ["app", "service"],
+  ] as const) {
+    mkdirSync(join(dir, stack, "src"), { recursive: true });
+    writeFileSync(join(dir, stack, "src", "main.ts"), stackSrc(resource));
+  }
+});
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+describe("buildDeclaredPerStack groups by declared stack (#1433)", () => {
+  test("every node lands in the stack that declared it", async () => {
+    const ir = await buildDeclaredPerStack(
+      [
+        { name: "network", src: "network/src" },
+        { name: "app", src: "app/src" },
+      ],
+      dir,
+    );
+    const byStack = ir.groups.byStack ?? {};
+    expect(Object.keys(byStack).sort()).toEqual(["app", "network"]);
+    // Membership uses the SAME qualified ids the nodes carry — a consumer joins
+    // the two without re-deriving anything.
+    const ids = new Set(ir.nodes.map((n) => n.id));
+    for (const members of Object.values(byStack)) {
+      for (const id of members) expect(ids.has(id)).toBe(true);
+    }
+    // Every node is in exactly one stack: a boundary-box renderer that drew from
+    // this would otherwise leave resources outside every box.
+    expect(Object.values(byStack).flat().sort()).toEqual([...ids].sort());
+  });
+
+  test("a stack with no src contributes no group, as it contributes no nodes", async () => {
+    const ir = await buildDeclaredPerStack(
+      [{ name: "network", src: "network/src" }, { name: "unbuilt" }],
+      dir,
+    );
+    expect(Object.keys(ir.groups.byStack ?? {})).toEqual(["network"]);
+  });
+
+  test("no stacks with src means no grouping at all, not an empty box", async () => {
+    const ir = await buildDeclaredPerStack([{ name: "unbuilt" }], dir);
+    expect(ir.groups.byStack).toBeUndefined();
+    expect(ir.nodes).toEqual([]);
+  });
+
+  test("members are sorted, so the IR stays byte-stable across runs", async () => {
+    const stacks = [
+      { name: "network", src: "network/src" },
+      { name: "app", src: "app/src" },
+    ];
+    const a = await buildDeclaredPerStack(stacks, dir);
+    const b = await buildDeclaredPerStack(stacks, dir);
+    expect(a.groups.byStack).toEqual(b.groups.byStack);
+    for (const members of Object.values(a.groups.byStack ?? {})) {
+      expect(members).toEqual([...members].sort());
+    }
+  });
+});

package/src/graph-declared.ts

@@ -22,12 +22,24 @@ export async function buildDeclaredPerStack(
 ): Promise<GraphIR> {
   const nodes: IRNode[] = [];
   const edges: GraphIR["edges"] = [];
+  // Which nodes belong to which stack (#1433). This is not derived or guessed:
+  // the stack is declared in config and every node here is being renamed with
+  // its name on the line below. The membership was always known and thrown
+  // away, which left `byStack` — the axis consumers draw boundary boxes from —
+  // empty for the one project shape that genuinely has side-by-side stacks.
+  const byStack: Record<string, string[]> = {};
   for (const st of stacks) {
     if (!st.src) continue;
     const g = buildGraphIr((await discover(resolve(projectPath, st.src))).entities, projectPath);
     const q = (id: string) => `${st.name}::${id}`;
-    for (const n of g.nodes) nodes.push({ ...n, id: q(n.id) });
+    for (const n of g.nodes) {
+      const id = q(n.id);
+      nodes.push({ ...n, id });
+      (byStack[st.name] ??= []).push(id);
+    }
     for (const e of g.edges) edges.push({ ...e, from: q(e.from), to: q(e.to) });
   }
-  return { nodes, edges, groups: {} };
+  for (const ids of Object.values(byStack)) ids.sort();
+  const groups: GraphIR["groups"] = Object.keys(byStack).length ? { byStack } : {};
+  return { nodes, edges, groups };
 }

package/src/graph-ir.ts

@@ -94,9 +94,23 @@ export interface IREdge {
 export interface IRGroups {
   byLexicon?: Record<string, string[]>;
   byComposite?: Record<string, string[]>;
-  /** Deployable-stack grouping (`stackName → nodeIds`). A stack is a lexicon
-   * partition today; #513 phase 2 regroups by nested child-project. Consumers
-   * (e.g. pinhole's boundary boxes) read this rather than inferring stacks. */
+  /**
+   * Deployable-stack grouping (`stackName → nodeIds`). Consumers (e.g. pinhole's
+   * boundary boxes) read this rather than inferring stacks — which is the point,
+   * so it should never require one.
+   *
+   * Two sources, depending on how the project is shaped:
+   *
+   *  - **side-by-side stacks**, declared in config and composed by
+   *    `buildDeclaredPerStack` — keys are the declared stack names. Nothing is
+   *    inferred; the project stated both the names and the membership.
+   *  - **one source tree** — keys are lexicon partitions, since each lexicon
+   *    serialises to one deployable stack.
+   *
+   * Formerly documented as awaiting "#513 phase 2" to regroup by nested
+   * child-project. #513 is closed and that phase was never filed; directory
+   * partitioning is the exception rather than the rule (#1433).
+   */
   byStack?: Record<string, string[]>;
   /** Live containment (#779): a container node id → the node ids directly inside
    * it (VPC → subnets/SGs, subnet → instances/service). Nested *flatly* — a
@@ -415,11 +429,21 @@ export function buildGraphIr(
     nodes.push(node);
 
     (byLexicon[entity.lexicon] ??= []).push(name);
-    // A stack is a lexicon partition (each lexicon serialises to one deployable
-    // stack — a CloudFormation template, a CI config). `byStack` mirrors that
-    // today; #513 phase 2 will regroup it by nested child-project. It's a
-    // distinct axis from `byLexicon` (which is for provenance/colouring), so it's
-    // emitted separately even where the two currently coincide.
+    // Within ONE source tree a stack is a lexicon partition — each lexicon
+    // serialises to one deployable stack (a CloudFormation template, a CI
+    // config) — so that is what `byStack` reports here. It stays a distinct axis
+    // from `byLexicon` (which is for provenance/colouring), emitted separately
+    // even where the two coincide.
+    //
+    // A project with genuinely separate, side-by-side stacks declares them in
+    // config, and `buildDeclaredPerStack` (./graph-declared.ts) groups those by
+    // their declared names — no inference, since the project already said. That
+    // is the multi-stack shape chant steers toward (#1433).
+    //
+    // This previously promised that "#513 phase 2 will regroup it by nested
+    // child-project". #513 is closed, that phase was never filed, and directory
+    // partitioning is the exception rather than the rule — so the promise is
+    // withdrawn rather than left pointing at a closed issue.
     (byStack[entity.lexicon] ??= []).push(name);
     if (prov?.composite) (byComposite[prov.composite] ??= []).push(name);
   }

package/src/graph-refs.test.ts

@@ -188,3 +188,59 @@ describe("traversal name vs rendering label (#1275)", () => {
     expect(edges).toEqual([]);
   });
 });
+
+describe("containment is traversable without being drawn", () => {
+  // "What is inside this" is a query, not a picture. The two had been decided
+  // by one field: a containment rule became a real edge only if it set
+  // `viaAttr`, which a renderer also reads. So making a relationship queryable
+  // meant drawing it, and the list of which ones had been remembered was the
+  // list of which questions could be asked.
+  const catalog: ReferenceCatalog = {
+    identities: [
+      { kind: "Subnet", ids: ["SubnetId"] },
+      { kind: "Vpc", ids: ["VpcId"] },
+    ],
+    refs: [
+      { from: "Eni", path: "SubnetId", targetKind: "Subnet", relation: "containment", label: "in subnet" },
+      { from: "Subnet", path: "VpcId", targetKind: "Vpc", relation: "containment", label: "in VPC" },
+    ],
+  };
+  const nodes = [
+    { id: "vpc-1", kind: "Vpc", lexicon: "x", attrs: { VpcId: "vpc-1" } },
+    { id: "sub-1", kind: "Subnet", lexicon: "x", attrs: { SubnetId: "sub-1", VpcId: "vpc-1" } },
+    { id: "sub-2", kind: "Subnet", lexicon: "x", attrs: { SubnetId: "sub-2", VpcId: "vpc-1" } },
+    { id: "eni-1", kind: "Eni", lexicon: "x", attrs: { SubnetId: "sub-1" } },
+  ];
+
+  it("still draws no containment lines — the boundary stays a boundary", () => {
+    const { edges } = reconstructEdges(nodes, catalog);
+    expect(edges).toEqual([]);
+  });
+
+  it("still reports the boundary pairs a renderer groups by", () => {
+    const { containment } = reconstructEdges(nodes, catalog);
+    expect(containment).toContainEqual({ child: "eni-1", parent: "sub-1", label: "in subnet" });
+    expect(containment).toContainEqual({ child: "sub-1", parent: "vpc-1", label: "in VPC" });
+  });
+
+  it("offers the same pairs as edges a query can walk", () => {
+    const { containmentEdges } = reconstructEdges(nodes, catalog);
+    expect(containmentEdges).toContainEqual({ from: "eni-1", to: "sub-1", kind: "ref", viaAttr: "SubnetId" });
+    expect(containmentEdges).toContainEqual({ from: "sub-1", to: "vpc-1", kind: "ref", viaAttr: "VpcId" });
+  });
+
+  it("no rule had to opt in — neither declares viaAttr", () => {
+    // The point of the change. Both rules above are plain containment; the
+    // traversal name is derived from the attribute the containment was read
+    // through, so a new kind is queryable the day its rule is written.
+    expect(catalog.refs.every((r) => r.viaAttr === undefined)).toBe(true);
+    // eni-1 -> sub-1, and both subnets -> vpc-1.
+    const { containmentEdges } = reconstructEdges(nodes, catalog);
+    expect(containmentEdges).toHaveLength(3);
+  });
+
+  it("an empty container is reached by nothing, which is the whole question", () => {
+    const { containmentEdges } = reconstructEdges(nodes, catalog);
+    expect(containmentEdges.some((e) => e.to === "sub-2")).toBe(false);
+  });
+});

package/src/graph-refs.ts

@@ -86,6 +86,30 @@ export interface DanglingRef {
 export interface ReconstructedEdges {
   edges: IREdge[];
   containment: ContainmentPair[];
+  /**
+   * The same containment pairs, as edges a query can walk.
+   *
+   * Containment is a boundary when you are drawing it and a relationship when
+   * you are asking about it, and those two consumers had been served by one
+   * decision. `edges` is what a renderer draws as lines, so putting "is in this
+   * VPC" there would draw a line from every resource to its VPC and undo the
+   * boxes; that is why containment is kept out of it, and why it stays out.
+   *
+   * But `->`/`<-` is asking which nodes reach which, and being inside something
+   * is a way of reaching it. "Which subnets have no network interfaces in them"
+   * and "which VPCs have no instances in them" are the same question, and both
+   * are containment. With only `edges` to walk, the negation matched everything
+   * and reported an estate where nothing is anywhere.
+   *
+   * The escape hatch this replaces was per-rule: a containment rule could set
+   * `viaAttr` and become a real edge. That put the query layer's needs in a
+   * field the renderer also reads, and it had to be remembered per rule —
+   * `AWS::EC2::Instance -> Subnet` had it and `AWS::EC2::NetworkInterface ->
+   * Subnet` did not, which is the kind of gap hand-maintained lists always
+   * develop. Deriving them here means a containment rule is traversable because
+   * it is a containment rule, not because someone remembered.
+   */
+  containmentEdges: IREdge[];
   dangling: DanglingRef[];
 }
 
@@ -158,6 +182,8 @@ export function reconstructEdges(nodes: IRNode[], catalog: ReferenceCatalog): Re
 
   const edges: IREdge[] = [];
   const containment: ContainmentPair[] = [];
+  const containmentEdges: IREdge[] = [];
+  const seenContEdge = new Set<string>();
   const dangling: DanglingRef[] = [];
   const seenEdge = new Set<string>();
   const seenCont = new Set<string>();
@@ -185,6 +211,15 @@ export function reconstructEdges(nodes: IRNode[], catalog: ReferenceCatalog): Re
             seenCont.add(k);
             containment.push({ child: node.id, parent: match.id, ...(rule.label ? { label: rule.label } : {}) });
           }
+          // Traversable by construction. The attribute the containment was read
+          // through is its traversal name, so `<-attr:` can still discriminate
+          // between two ways of being inside something.
+          const via = rule.viaAttr ?? rule.path;
+          const ke = `${node.id}|${match.id}|${via}`;
+          if (!seenContEdge.has(ke)) {
+            seenContEdge.add(ke);
+            containmentEdges.push({ from: node.id, to: match.id, kind: "ref", viaAttr: via });
+          }
           // A containment relation is a boundary hint, not an edge — unless the
           // rule declares a traversal name (#1275). A fold's first hop is
           // sometimes exactly a containment ("an instance is in a subnet"), and
@@ -202,10 +237,11 @@ export function reconstructEdges(nodes: IRNode[], catalog: ReferenceCatalog): Re
   }
 
   edges.sort((a, b) => `${a.from}|${a.to}|${a.viaAttr}`.localeCompare(`${b.from}|${b.to}|${b.viaAttr}`));
+  containmentEdges.sort((a, b) => `${a.from}|${a.to}|${a.viaAttr}`.localeCompare(`${b.from}|${b.to}|${b.viaAttr}`));
   containment.sort((a, b) => `${a.child}|${a.parent}`.localeCompare(`${b.child}|${b.parent}`));
   dangling.sort((a, b) => `${a.from}|${a.path}|${a.value}`.localeCompare(`${b.from}|${b.path}|${b.value}`));
 
-  return { edges, containment, dangling };
+  return { edges, containment, containmentEdges, dangling };
 }
 
 /**

package/src/index.ts

@@ -49,6 +49,7 @@ export * from "./import/parser";
 export * from "./import/generator";
 export * from "./lexicon";
 export * from "./observation";
+export * from "./apply";
 export * from "./deep-observation";
 export * from "./owner-chain";
 export * from "./lexicon-integrity";

package/src/kubectl-context.ts

@@ -126,7 +126,10 @@ export async function resolveClusterTarget(
   lexiconName: string,
   options: ResolveClusterTargetOptions = {},
 ): Promise<ResolvedClusterTarget> {
-  const k8sConfig = config.k8s as K8sConfigShape | undefined;
+  // #1344 — the k8s lexicon declares this namespace and core validates it at
+  // load, so the shape is checked rather than asserted. `K8sConfigShape` stays
+  // as core's local description for the case where the lexicon is absent.
+  const k8sConfig = (config as { k8s?: K8sConfigShape }).k8s;
   const bound = k8sConfig?.profiles?.[environment]?.context;
 
   if (!bound) {

package/src/lexicon-config.test.ts

@@ -0,0 +1,111 @@
+import { describe, test, expect } from "vitest";
+import { z } from "zod";
+import { validateLexiconConfig, formatLexiconConfigProblems } from "./lexicon-config";
+import type { ChantConfig } from "./config";
+
+const forgejo = {
+  name: "forgejo",
+  configSchema: z.strictObject({
+    runnerLabels: z.record(z.string(), z.string()).optional(),
+    actionsRoot: z.string().optional(),
+  }),
+};
+
+const undeclared = { name: "docker" };
+
+const cfg = (extra: Record<string, unknown>): ChantConfig =>
+  ({ lexicons: ["forgejo"], ...extra }) as unknown as ChantConfig;
+
+describe("validateLexiconConfig (#1344)", () => {
+  test("accepts a namespace matching the declared shape", () => {
+    const problems = validateLexiconConfig(
+      [forgejo],
+      cfg({ forgejo: { runnerLabels: { "ubuntu-latest": "docker" }, actionsRoot: "https://x" } }),
+    );
+    expect(problems).toEqual([]);
+  });
+
+  test("rejects an unknown key — the typo that used to be silently ignored", () => {
+    const problems = validateLexiconConfig([forgejo], cfg({ forgejo: { runnerLabel: {} } }));
+    expect(problems).toHaveLength(1);
+    expect(problems[0].path).toBe("forgejo");
+    expect(problems[0].message).toContain("runnerLabel");
+  });
+
+  test("names the dotted path of a bad value, not just the namespace", () => {
+    const problems = validateLexiconConfig([forgejo], cfg({ forgejo: { actionsRoot: 42 } }));
+    expect(problems[0].path).toBe("forgejo.actionsRoot");
+  });
+
+  test("an absent namespace is fine — every one of them is optional", () => {
+    expect(validateLexiconConfig([forgejo], cfg({}))).toEqual([]);
+  });
+
+  test("an empty namespace is fine", () => {
+    expect(validateLexiconConfig([forgejo], cfg({ forgejo: {} }))).toEqual([]);
+  });
+
+  test("a lexicon that declares nothing keeps passthrough", () => {
+    // Tightening a namespace nobody described would fail configs that work.
+    expect(validateLexiconConfig([undeclared], cfg({ docker: { anything: true } }))).toEqual([]);
+  });
+
+  test("another lexicon's namespace is not this lexicon's to reject", () => {
+    expect(validateLexiconConfig([forgejo], cfg({ somethingElse: { a: 1 } }))).toEqual([]);
+  });
+
+  test("core's own keys are untouched", () => {
+    expect(validateLexiconConfig([forgejo], cfg({ sourceDir: "src", build: { fold: true } }))).toEqual([]);
+  });
+
+  test("reports every problem, not just the first", () => {
+    const problems = validateLexiconConfig(
+      [forgejo],
+      cfg({ forgejo: { runnerLabel: {}, actionsRoot: 42 } }),
+    );
+    expect(problems.length).toBeGreaterThanOrEqual(2);
+  });
+
+  test("validates each declaring lexicon independently", () => {
+    const temporal = {
+      name: "temporal",
+      configSchema: z.strictObject({ defaultProfile: z.string().optional() }),
+    };
+    const problems = validateLexiconConfig(
+      [forgejo, temporal],
+      cfg({ forgejo: { actionsRoot: "https://x" }, temporal: { defaultProfil: "local" } }),
+    );
+    expect(problems.map((p) => p.lexicon)).toEqual(["temporal"]);
+  });
+
+  test("no config at all is not a problem", () => {
+    expect(validateLexiconConfig([forgejo], undefined)).toEqual([]);
+  });
+
+  test("a nested strictObject catches a typo one level down", () => {
+    const k8s = {
+      name: "k8s",
+      configSchema: z.strictObject({
+        profiles: z.record(z.string(), z.strictObject({ context: z.string() })).optional(),
+      }),
+    };
+    const problems = validateLexiconConfig(
+      [k8s],
+      cfg({ k8s: { profiles: { prod: { contxt: "prod-eks" } } } }),
+    );
+    // Two, and both are right: the key it does not recognize, and the required
+    // one that is now missing because of the typo.
+    expect(problems.map((p) => p.path).sort()).toEqual(["k8s.profiles.prod", "k8s.profiles.prod.context"]);
+  });
+});
+
+describe("formatLexiconConfigProblems", () => {
+  test("one indented line per problem", () => {
+    const problems = validateLexiconConfig([forgejo], cfg({ forgejo: { actionsRoot: 42 } }));
+    expect(formatLexiconConfigProblems(problems)).toMatch(/^ {2}forgejo\.actionsRoot: /);
+  });
+
+  test("empty for no problems", () => {
+    expect(formatLexiconConfigProblems([])).toBe("");
+  });
+});