@intentius/chant 0.38.0 → 0.39.0

package/src/cli/param-flag-scope.test.ts

@@ -0,0 +1,69 @@
+import { describe, test, expect } from "vitest";
+import { readFileSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * `--param`/`--params-file` started as build-only flags and grew: `chant graph`
+ * gained them with #1359 (graph and build disagreed about the same source),
+ * `chant run --components` with #1108. The help text in `./main.ts` kept saying
+ * "(build)", so the CLI's own documentation told users the flag did nothing on
+ * the two commands that had just learned it.
+ *
+ * Asserting the property rather than the wording: every handler that actually
+ * reads `args.param` must be named in the flag's help annotation. A new handler
+ * honoring the flag fails this test until the help is updated with it.
+ */
+const here = dirname(fileURLToPath(import.meta.url));
+const handlersDir = join(here, "handlers");
+
+/** The command name a handler file implements — `handlers/graph.ts` backs `chant graph`. */
+function commandOf(file: string): string {
+  return file.replace(/\.ts$/, "");
+}
+
+function handlersReadingParamFlags(): string[] {
+  return readdirSync(handlersDir)
+    .filter((f) => f.endsWith(".ts") && !f.endsWith(".test.ts"))
+    .filter((f) => /\bargs\.param\b/.test(readFileSync(join(handlersDir, f), "utf-8")))
+    .map(commandOf)
+    .sort();
+}
+
+/**
+ * The help text for one flag: everything from its marker up to the next flag
+ * entry or the end of the options block, whichever comes first. Both bounds
+ * matter — the LAST flag in a block has no `--` after it, and without the
+ * blank-line bound its "block" would run to the end of the file and match
+ * every command name incidentally.
+ */
+function helpBlockFor(flag: string): string {
+  const source = readFileSync(join(here, "main.ts"), "utf-8");
+  const start = source.indexOf(`  ${flag}`);
+  expect(start, `${flag} is not documented in main.ts's help`).toBeGreaterThan(-1);
+  const rest = source.slice(start + flag.length);
+  const ends = [rest.search(/\n {2}--/), rest.search(/\n\s*\n/)].filter((i) => i !== -1);
+  expect(ends.length, `${flag}'s help block has no terminator`).toBeGreaterThan(0);
+  return rest.slice(0, Math.min(...ends));
+}
+
+describe("--param help annotation tracks the handlers that honor it", () => {
+  test("at least build, graph and run read the flag", () => {
+    // Guards the test itself: if the detection regex ever stops matching, the
+    // assertions below would pass vacuously against an empty set.
+    expect(handlersReadingParamFlags()).toEqual(expect.arrayContaining(["build", "graph", "run"]));
+  });
+
+  test.each(["--param <name=value>", "--params-file <path>"])(
+    "%s names every command that honors it",
+    (flag) => {
+      const block = helpBlockFor(flag);
+      for (const command of handlersReadingParamFlags()) {
+        expect(
+          block.includes(command),
+          `handlers/${command}.ts reads args.param, but ${flag}'s help does not mention "${command}"`,
+        ).toBe(true);
+      }
+    },
+  );
+});

package/src/cli/plugins.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "vitest";
-import { loadPlugin, loadPlugins } from "./plugins";
+import { loadPlugin, loadPlugins, resolveLexiconVersions } from "./plugins";
 import { isLexiconPlugin } from "../lexicon";
 
 describe("loadPlugin", () => {
@@ -29,3 +29,35 @@ describe("loadPlugins", () => {
     expect(plugins).toHaveLength(0);
   });
 });
+
+/**
+ * chant #1442 — the installed version of each lexicon package, read for the
+ * build digest.
+ */
+describe("resolveLexiconVersions", () => {
+  test("reads the real installed version of a workspace lexicon", () => {
+    const versions = resolveLexiconVersions(["k8s"]);
+    expect(versions.k8s).toMatch(/^\d+\.\d+\.\d+/);
+  });
+
+  test("resolves several lexicons in one call", () => {
+    const versions = resolveLexiconVersions(["k8s", "aws"]);
+    expect(Object.keys(versions).sort()).toEqual(["aws", "k8s"]);
+  });
+
+  test("omits a lexicon that is not installed rather than inventing a version", () => {
+    // "unknown" would compare unequal to itself across builds and report a
+    // version change on every diff.
+    expect(resolveLexiconVersions(["definitely-not-a-lexicon"])).toEqual({});
+  });
+
+  test("an unresolvable name does not prevent the resolvable ones", () => {
+    const versions = resolveLexiconVersions(["definitely-not-a-lexicon", "k8s"]);
+    expect(versions.k8s).toBeDefined();
+    expect(versions["definitely-not-a-lexicon"]).toBeUndefined();
+  });
+
+  test("no names yields an empty map", () => {
+    expect(resolveLexiconVersions([])).toEqual({});
+  });
+});

package/src/cli/plugins.ts

@@ -1,3 +1,6 @@
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
 import { isLexiconPlugin, type LexiconPlugin } from "../lexicon";
 import { loadChantConfigUpward } from "../config";
 import { findInfraFiles, detectLexicons } from "../index";
@@ -40,6 +43,58 @@ export async function loadPlugin(lexiconName: string): Promise<LexiconPlugin> {
   throw new Error(`Package ${packageName} does not export a LexiconPlugin or Serializer`);
 }
 
+/**
+ * The installed version of each named lexicon package (chant #1442).
+ *
+ * A `LexiconPlugin` does not carry its own version — `LexiconManifest` does,
+ * but that is an artifact type describing generated output, not something the
+ * plugin object exposes. The version wanted here is a property of the
+ * *installed package*, so it is read from the package's own `package.json`.
+ *
+ * Resolved by walking up from the package's entry point rather than resolving
+ * `<pkg>/package.json` directly: lexicon packages declare an `exports` map
+ * that does not include `./package.json`, so the direct specifier is blocked
+ * by Node. `./manifest` (→ `dist/manifest.json`) is not used either — it is a
+ * `prepack` build artifact, absent in a monorepo dev tree, and its absence
+ * once read as four unrelated bugs (#1367).
+ *
+ * A lexicon whose version cannot be determined is omitted rather than
+ * recorded as `"unknown"`: a digest that says nothing is honest, one that
+ * says `unknown` compares unequal to itself across builds.
+ */
+export function resolveLexiconVersions(lexiconNames: readonly string[]): Record<string, string> {
+  const require_ = createRequire(import.meta.url);
+  const versions: Record<string, string> = {};
+
+  for (const name of lexiconNames) {
+    const packageName = `@intentius/chant-lexicon-${name}`;
+    try {
+      let dir = dirname(require_.resolve(packageName));
+      // Bounded walk — a resolved entry point is never deeply nested inside
+      // its own package, and an unbounded loop here would climb to `/`.
+      for (let depth = 0; depth < 10; depth++) {
+        const candidate = join(dir, "package.json");
+        if (existsSync(candidate)) {
+          const pkg = JSON.parse(readFileSync(candidate, "utf-8")) as { name?: string; version?: string };
+          // Only the lexicon's OWN package.json — a nested dependency's
+          // manifest would otherwise be read as the lexicon's version.
+          if (pkg.name === packageName && pkg.version) {
+            versions[name] = pkg.version;
+            break;
+          }
+        }
+        const parent = dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+      }
+    } catch {
+      // Not installed, or not resolvable from here — omit it.
+    }
+  }
+
+  return versions;
+}
+
 /**
  * Load plugins for all detected lexicon names.
  * Calls `init()` on each plugin if present.

package/src/codegen/registry.test.ts

@@ -0,0 +1,56 @@
+import { describe, test, expect } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadLexiconRegistry, LexiconRegistryMissingError } from "./registry";
+
+const REGISTRY = { Bucket: { resourceType: "AWS::S3::Bucket", kind: "resource" } };
+
+function pkg(): string {
+  return mkdtempSync(join(tmpdir(), "chant-registry-"));
+}
+
+describe("loadLexiconRegistry (#1367)", () => {
+  test("reads the dev copy — src/generated, which is what a working checkout has", () => {
+    const dir = pkg();
+    mkdirSync(join(dir, "src", "generated"), { recursive: true });
+    writeFileSync(join(dir, "src", "generated", "lexicon-aws.json"), JSON.stringify(REGISTRY));
+    expect(loadLexiconRegistry(dir, "aws")).toEqual(REGISTRY);
+  });
+
+  test("falls back to dist/meta.json — what an installed package ships", () => {
+    const dir = pkg();
+    mkdirSync(join(dir, "dist"), { recursive: true });
+    writeFileSync(join(dir, "dist", "meta.json"), JSON.stringify(REGISTRY));
+    expect(loadLexiconRegistry(dir, "aws")).toEqual(REGISTRY);
+  });
+
+  test("prefers the dev copy when both exist", () => {
+    const dir = pkg();
+    mkdirSync(join(dir, "src", "generated"), { recursive: true });
+    mkdirSync(join(dir, "dist"), { recursive: true });
+    writeFileSync(join(dir, "src", "generated", "lexicon-aws.json"), JSON.stringify({ Dev: REGISTRY.Bucket }));
+    writeFileSync(join(dir, "dist", "meta.json"), JSON.stringify({ Dist: REGISTRY.Bucket }));
+    expect(Object.keys(loadLexiconRegistry(dir, "aws"))).toEqual(["Dev"]);
+  });
+
+  test("throws with the command to run, rather than a module-not-found or an empty map", () => {
+    // The whole point. An empty map reads downstream as a lexicon with no
+    // resource types, which is how azure's import came to emit
+    // `// Unknown resource type: Microsoft.…` and look like a coverage gap.
+    const dir = pkg();
+    expect(() => loadLexiconRegistry(dir, "azure")).toThrow(LexiconRegistryMissingError);
+    expect(() => loadLexiconRegistry(dir, "azure")).toThrow(/npm run --prefix lexicons\/azure prepack/);
+  });
+
+  test("names the lexicon that is missing, not a generic one", () => {
+    const dir = pkg();
+    try {
+      loadLexiconRegistry(dir, "gcp");
+      throw new Error("should have thrown");
+    } catch (err) {
+      expect((err as LexiconRegistryMissingError).lexicon).toBe("gcp");
+      expect((err as Error).message).toContain("lexicons/gcp");
+    }
+  });
+});

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());
+    }
+  });
+});