@intentius/chant 0.37.2 → 0.39.0

package/src/codegen/registry.ts

@@ -0,0 +1,69 @@
+/**
+ * Locating a lexicon's generated registry (#1367).
+ *
+ * The registry — every resource type the lexicon knows, keyed by class name —
+ * is written to two places by `npm run --prefix lexicons/<name> prepack`:
+ * `src/generated/lexicon-<name>.json` by the generate step, and `dist/meta.json`
+ * by the bundle step, byte-identical. Both are gitignored, so a fresh clone has
+ * neither until that command runs; CI runs it explicitly before anything else.
+ *
+ * That is a legitimate state. Being silent about it is not, and the two readers
+ * that needed the registry were silent in opposite directions:
+ *
+ * - AWS's import generator `require`d `dist/meta.json` with no catch, so a
+ *   fresh clone got `Cannot find module …/lexicons/aws/dist/meta.json` — from
+ *   `chant import`, and from twelve tests that mention neither modules nor
+ *   registries.
+ * - Azure's caught the failure and continued with an empty map, so the import
+ *   emitted `// Unknown resource type: Microsoft.Network/virtualNetworks` and
+ *   its round-trip tests failed as though the registry were incomplete. That is
+ *   the worse of the two: it looks like a coverage gap in the lexicon.
+ *
+ * Both now go through here, which tries the dev path first (matching what the
+ * azure serializer already did) and, failing both, says what to run.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Thrown when neither copy of the registry exists — carries the fix. */
+export class LexiconRegistryMissingError extends Error {
+  constructor(readonly lexicon: string) {
+    super(
+      `${lexicon} lexicon registry not found — it is a build artifact and this checkout has not built it.\n` +
+        `Run: npm run --prefix lexicons/${lexicon} prepack\n` +
+        `(generate writes src/generated/lexicon-${lexicon}.json; bundle writes dist/meta.json)`,
+    );
+    this.name = "LexiconRegistryMissingError";
+  }
+}
+
+/** One entry in a lexicon's generated registry. */
+export interface LexiconRegistryEntry {
+  resourceType: string;
+  kind: string;
+  apiVersion?: string;
+}
+
+/**
+ * Read a lexicon's generated registry, dev copy first.
+ *
+ * `pkgDir` is the lexicon PACKAGE directory (the one holding `src/` and
+ * `dist/`) — callers pass an `import.meta.dirname`-derived path, so this stays
+ * free of assumptions about where it is imported from. Throws
+ * {@link LexiconRegistryMissingError} when neither copy exists, rather than
+ * returning an empty map that reads downstream as a lexicon with no resource
+ * types at all.
+ */
+export function loadLexiconRegistry(pkgDir: string, lexicon: string): Record<string, LexiconRegistryEntry> {
+  for (const candidate of [
+    join(pkgDir, "src", "generated", `lexicon-${lexicon}.json`),
+    join(pkgDir, "dist", "meta.json"),
+  ]) {
+    try {
+      return JSON.parse(readFileSync(candidate, "utf-8")) as Record<string, LexiconRegistryEntry>;
+    } catch {
+      // Try the next candidate; only both failing is an error.
+    }
+  }
+  throw new LexiconRegistryMissingError(lexicon);
+}

package/src/components/SPRAWL-VALIDATION.md

@@ -16,7 +16,7 @@ generic `runInterpretDriver` (#556, [`../driver.ts`](./driver.ts)), unchanged.
 ## Before / after: the ALB/ECS pipeline glue this replaces
 
 The component model's whole reason for existing is visible in one concrete
-diff. [`examples/gitlab-aws-alb-api/src/pipeline.ts`](../../../../../examples/gitlab-aws-alb-api/src/pipeline.ts)
+diff. [`examples/gitlab-aws-alb-api/src/pipeline.ts`](../../../../examples/gitlab-aws-alb-api/src/pipeline.ts)
 hand-rolls a `deployService` job that shells out to CloudFormation and greps
 its own infra stack's outputs before it can deploy:
 
@@ -49,7 +49,7 @@ No `describe-stacks`, no `jq`, no shell string-building. `dependsOn:
 ["shared-alb"]` plus three `stackOutput()` references replace the whole glue
 block; `docker build`/`docker push` become the `docker-build`/`publish-image`
 capabilities the driver dispatches to. [`driver.test.ts`](./driver.test.ts)
-and [`pilots/pilots-e2e.test.ts`](./pilots/pilots-e2e.test.ts) exercise this
+and [`pilots/pilots.test.ts`](./pilots/pilots.test.ts) exercise this
 exact wiring end to end against a mock `CloudExecutor` — `cfn-deploy`
 resolves the `stackOutput` reference itself; no orchestrator code parses a
 CloudFormation output.
@@ -59,7 +59,7 @@ CloudFormation output.
 [`driver.test.ts`](./driver.test.ts)'s `"runs the three pilots through one
 driver instance with zero per-component driver code (sprawl metric)"` test
 (pre-existing from #556/#557, still green) and
-[`pilots-e2e.test.ts`](./pilots/pilots-e2e.test.ts)'s first `describe` block
+[`pilots.test.ts`](./pilots/pilots.test.ts)'s first `describe` block
 run Neo4j fan-out, DynamoDB (sticky apply), and ALB/ECS (cross-stack, build)
 through the same `runInterpretDriver` call, dispatching to the real,
 `MockCloudExecutor`-backed capability implementations from #557
@@ -103,7 +103,7 @@ uses carries the image reference into the apply step.
 
 ### The one new capability: `lambda-deploy`
 
-[`verbs/apply.ts`](./verbs/apply.ts)'s `createLambdaDeployCapability` is the
+[`lexicons/aws/src/components/apply.ts`](../../../../lexicons/aws/src/components/apply.ts)'s `createLambdaDeployCapability` is the
 only new leaf this component required, built the same way #557 built the
 other real leaves: typed input/output, an injectable `CloudExecutor`
 (extended with a `lambda` client — [`verbs/cloud-executor.ts`](./verbs/cloud-executor.ts)),
@@ -121,7 +121,7 @@ No other verb was touched or added. `driver.ts` was not edited.
 
 [`driver.test.ts`](./driver.test.ts)'s `"runs all four components ... through
 one driver instance with zero per-component driver code (sprawl metric,
-extended)"` test and [`pilots-e2e.test.ts`](./pilots/pilots-e2e.test.ts)'s
+extended)"` test and [`pilots.test.ts`](./pilots/pilots.test.ts)'s
 second `describe`-block test run all five components (`shared-alb`,
 `orders-table`, `neo4j-cluster`, `search-service`, `image-processor-lambda`)
 through one `runInterpretDriver` call, dispatching `image-processor-lambda`'s

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

@@ -0,0 +1,27 @@
+import { describe, test, expect, afterEach } from "vitest";
+import { resolve } from "node:path";
+import { generateComponentDriverSource } from "./driver";
+import { setBuildParams } from "../../params";
+
+/**
+ * chant #1108 — same re-binding the entity driver does (../../discovery/
+ * sandbox/driver.test.ts): a `*.component.ts` file imported in the sandboxed
+ * child must see the parent's resolved build-time parameters, not `{}`.
+ */
+describe("generateComponentDriverSource — build-time parameters (#1108)", () => {
+  afterEach(() => {
+    setBuildParams({});
+  });
+
+  test("embeds a snapshot of the parent's current params, bound before any component import", () => {
+    setBuildParams({ stage: "prod" });
+    const source = generateComponentDriverSource({ files: ["proj/svc.component.ts"] });
+
+    expect(source).toContain("import { setBuildParams } from ");
+    const bindAt = source.indexOf(`setBuildParams(${JSON.stringify({ stage: "prod" })});`);
+    const firstImportAt = source.indexOf(`await import(${JSON.stringify(resolve("proj/svc.component.ts"))})`);
+    expect(bindAt).toBeGreaterThan(-1);
+    expect(firstImportAt).toBeGreaterThan(-1);
+    expect(bindAt).toBeLessThan(firstImportAt);
+  });
+});

package/src/components/sandbox/driver.ts

@@ -1,4 +1,5 @@
 import { join, resolve } from "node:path";
+import { params as currentBuildParams } from "../../params";
 
 /**
  * chant #1051 — generates the source of the "driver" module that runs INSIDE
@@ -29,6 +30,12 @@ const COMPONENTS_DIR = join(HERE, "..");
 /** Absolute paths to chant's OWN trusted modules the generated driver imports — resolved relative to THIS file's own location on disk, exactly like `../../discovery/sandbox/driver.ts` does for the entity path (works whether chant runs from the monorepo or a consumer's `node_modules`). */
 const DISCOVER_MODULE = join(COMPONENTS_DIR, "discover.ts");
 const CHILD_ERRORS_MODULE = join(COMPONENTS_DIR, "..", "discovery", "sandbox", "child-errors.ts");
+// chant #1108 — same re-binding the entity driver does (see ../../discovery/
+// sandbox/driver.ts's PARAMS_MODULE doc): the child's copy of the shared
+// `params` object starts empty, so a `*.component.ts` file importing
+// `@intentius/chant/params` would otherwise see `{}` under sandboxed
+// discovery no matter what the parent resolved.
+const PARAMS_MODULE = join(COMPONENTS_DIR, "..", "params.ts");
 
 export interface GenerateComponentDriverOptions {
   /** Absolute paths to every discovered `*.component.ts` file for this build. */
@@ -52,6 +59,11 @@ export function generateComponentDriverSource(options: GenerateComponentDriverOp
   const lines: string[] = [
     `import { collectComponents } from ${lit(DISCOVER_MODULE)};`,
     `import { classifyChildError } from ${lit(CHILD_ERRORS_MODULE)};`,
+    `import { setBuildParams } from ${lit(PARAMS_MODULE)};`,
+    ``,
+    // chant #1108 — snapshot of the parent's resolved build-time parameter
+    // values (scalars only), bound before any component file is imported.
+    `setBuildParams(${lit({ ...currentBuildParams })});`,
     ``,
     `function send(payload) {`,
     `  if (typeof process.send === "function") process.send(payload);`,

package/src/composite.ts

@@ -7,14 +7,43 @@ import { setProvenance } from "./provenance";
 export const COMPOSITE_MARKER = Symbol.for("chant.composite");
 
 /**
- * A record of named Declarable members produced by a composite factory.
+ * A record of named members produced by a composite factory.
+ *
+ * What a consumer reads off `instance.members`. Deliberately narrow: every
+ * value here is a real Declarable, so `.entityType` and friends resolve without
+ * narrowing. What a factory may RETURN is wider — see
+ * {@link CompositeFactoryMembers}.
  */
 export type CompositeMembers = Record<string, Declarable>;
 
+/**
+ * What a factory is allowed to RETURN — {@link CompositeMembers} plus
+ * `undefined`, used only as the generic constraint.
+ *
+ * A member produced by a conditional spread (`...(cond ? { policy } : {})`) is
+ * typed optional, and an optional property is not assignable to a
+ * required-value record. Widening the constraint lets such a factory typecheck;
+ * widening `CompositeMembers` itself would make every member possibly-undefined
+ * for everyone reading `instance.members`, which is a worse trade.
+ *
+ * The key is absent at runtime rather than present-and-undefined, so nothing
+ * reaches the validation in `Composite` below.
+ */
+export type CompositeFactoryMembers =
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  | Record<string, Declarable | CompositeInstance<any> | undefined>
+  // A pass-through composite returns another composite's INSTANCE rather than
+  // building a record (`return FargateService({...})`). That works at runtime
+  // because `members` and `_definition` are defined non-enumerable below
+  // precisely so an instance exposes only its member resources — but a type
+  // cannot say "non-enumerable", so the instance has to be admitted directly.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  | CompositeInstance<any>;
+
 /**
  * The result of instantiating a composite — contains the marker and expanded members.
  */
-export interface CompositeInstance<M extends CompositeMembers = CompositeMembers> {
+export interface CompositeInstance<M extends CompositeFactoryMembers = CompositeMembers> {
   readonly [COMPOSITE_MARKER]: true;
   readonly members: M;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -24,7 +53,7 @@ export interface CompositeInstance<M extends CompositeMembers = CompositeMembers
 /**
  * A composite definition: a callable that produces a CompositeInstance.
  */
-export interface CompositeDefinition<P, M extends CompositeMembers = CompositeMembers> {
+export interface CompositeDefinition<P, M extends CompositeFactoryMembers = CompositeMembers> {
   (props: P): CompositeInstance<M> & M;
   readonly compositeName: string;
   readonly _id: symbol;
@@ -78,7 +107,7 @@ export class CompositeRegistry {
  * export const storage = SecureStorage({ name: "data" });
  * ```
  */
-export function Composite<P, M extends CompositeMembers = CompositeMembers>(
+export function Composite<P, M extends CompositeFactoryMembers = CompositeMembers>(
   factory: (props: P) => M,
   name?: string,
 ): CompositeDefinition<P, M> {

package/src/deep-observation.ts

@@ -56,6 +56,17 @@ export interface DeepResourceObservation {
   physicalId?: string;
   /** The normalized live property tree. JSON-safe. */
   properties: Record<string, unknown>;
+  /**
+   * Path → the field manager that owns it, where the substrate records one
+   * (#1189). Additive to the v1 envelope: a lexicon with no per-field ownership
+   * omits it, and every consumer behaves exactly as before.
+   *
+   * Only Kubernetes has this — the API server maintains `managedFields`
+   * server-side. It is the difference between "this field is foreign" and
+   * "`hpa-controller` owns `spec.replicas`", which are the same category and
+   * very different answers to an operator.
+   */
+  fieldOwners?: Record<string, string>;
 }
 
 /**

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/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) {