@intentius/chant 0.19.1 → 0.21.0

package/src/build-params.ts

@@ -0,0 +1,207 @@
+import type { BuildParamProvenance } from "./provenance";
+
+/**
+ * Build-time parameter declaration + resolution (chant #1064, follow-up to
+ * epic #1019's fold work — see issue #1064's "DECISION: option 1" comment).
+ *
+ * A build-time parameter is declared in `chant.config.ts`'s `buildParams`
+ * (name, type, optional `default`/`enum`/`env` mapping), supplied to `chant
+ * build` (a `--param name=value` flag, a `--params-file` JSON file, or a
+ * declared `env` var), and referenced from source as `params.<name>` (see
+ * ./params.ts) — never as an ambient `process.env` read. This module owns
+ * declaration + precedence + validation; ./params.ts is the plain runtime
+ * object source references; ../discovery/fold-import.ts is what makes a
+ * `params.<name>` reference fold to a literal instead of a symbolic node.
+ *
+ * This is NOT the deploy-time `Parameter` class (`lexicons/aws/src/parameter.ts`)
+ * — that resolves when a CloudFormation stack deploys; this resolves before
+ * the template is even synthesized, so its value can change which resources
+ * are produced at all. See ./params.ts's module doc for the full distinction.
+ */
+
+/** A build-time parameter's resolved (and declared-default/enum) value — always a scalar. */
+export type BuildParamValue = string | number | boolean;
+
+/**
+ * One declared build-time parameter (`chant.config.ts`'s `buildParams.<name>`).
+ */
+export interface BuildParamDef {
+  /** The value's declared type — supplied strings (CLI flags, env vars, JSON-file strings) are coerced to it. */
+  type: "string" | "number" | "boolean";
+  /** Value used when no `--param`/`--params-file`/declared `env` var supplies one. Omit to require an explicit value every build. */
+  default?: BuildParamValue;
+  /**
+   * Allowed values — a resolved value outside this list is a build error
+   * naming the parameter (never a thrown error from user source). Replaces
+   * the hand-written `if (!VALID.includes(raw)) throw ...` pattern loomster's
+   * `params.ts` files used before migrating to this mechanism.
+   */
+  enum?: readonly BuildParamValue[];
+  /**
+   * Opt-in, EXPLICITLY declared environment-variable fallback — e.g. `env:
+   * "LOOM_TIER"`. This is the only place an env var may feed a build-time
+   * parameter: reading `process.env` directly from project source is never
+   * supported (see ./params.ts's module doc and ../fold/fold.ts's pointed
+   * error for a bare `process` reference). Consulted only when no
+   * `--param`/`--params-file` value was supplied for this parameter.
+   */
+  env?: string;
+  /**
+   * Set `false` to make an unresolved value NOT a build error: `params.<name>`
+   * is simply omitted (reads as plain JS `undefined` — a normal, un-erroring
+   * property access on an object missing that key), instead of the default
+   * behavior of requiring every declared parameter to resolve to something.
+   * For a value that is genuinely optional with no meaningful default (an ARN
+   * that references an existing resource only on some deploys, a CIDR
+   * override, a JSON blob) — the same "unset means the composite decides"
+   * shape a hand-written `process.env.X || undefined` used to express.
+   * Default `true` (a declared parameter must resolve to a value).
+   */
+  required?: boolean;
+  /** Human-readable description, surfaced in error messages and docs generation. */
+  description?: string;
+}
+
+/** A project's full set of declared build-time parameters, keyed by name. */
+export type BuildParamsConfig = Record<string, BuildParamDef>;
+
+/** Raw, not-yet-validated inputs {@link resolveBuildParams} resolves against a project's declared {@link BuildParamsConfig}. */
+export interface BuildParamsInput {
+  /** `--param name=value` flags, repeated — highest precedence. */
+  cli?: Record<string, string>;
+  /** Parsed contents of a `--params-file` JSON file — second precedence. */
+  fromFile?: Record<string, unknown>;
+  /** The process environment, consulted only for a parameter that declares an `env` mapping, and only once `cli`/`fromFile` have no value for it. */
+  env?: Record<string, string | undefined>;
+}
+
+/** Result of resolving a project's declared parameters against one build invocation's inputs. */
+export interface BuildParamsResolution {
+  /** Every successfully resolved parameter — see {@link BuildParamProvenance}. Empty when the project declares none. */
+  provenance: BuildParamProvenance[];
+  /**
+   * Validation failures, each naming the offending parameter — an unknown
+   * `--param`/`--params-file` key, a missing required value, a type mismatch,
+   * or a value outside a declared `enum`. Reported by the CLI as a build
+   * error (chant #1064's acceptance criterion: "not a thrown error inside
+   * user source"); never thrown from here.
+   */
+  errors: string[];
+}
+
+function formatValue(value: unknown): string {
+  return typeof value === "string" ? `"${value}"` : String(value);
+}
+
+/** Coerce `raw` to `def.type`, appending a located error and returning `undefined` on failure. */
+function coerce(name: string, raw: BuildParamValue, def: BuildParamDef, errors: string[]): BuildParamValue | undefined {
+  if (def.type === "string") return String(raw);
+
+  if (def.type === "number") {
+    const n = typeof raw === "number" ? raw : Number(raw);
+    if (Number.isNaN(n)) {
+      errors.push(`build parameter "${name}" must be a number, got ${formatValue(raw)}`);
+      return undefined;
+    }
+    return n;
+  }
+
+  // def.type === "boolean"
+  if (typeof raw === "boolean") return raw;
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  errors.push(`build parameter "${name}" must be a boolean ("true" or "false"), got ${formatValue(raw)}`);
+  return undefined;
+}
+
+/**
+ * Resolve a project's declared build-time parameters against one build's
+ * supplied inputs. Precedence per parameter, most to least specific:
+ * `cli` (`--param name=value`) > `fromFile` (`--params-file`) > the
+ * parameter's own declared `env` mapping (only if set) > `def.default`.
+ *
+ * A parameter with no declared `default` and no value from any source is a
+ * build error, not a silently-`undefined` value — a build-time parameter
+ * exists specifically so a project never has an invisible dependency on
+ * ambient state; leaving one unresolved would just reintroduce that under a
+ * different name. Every failure is collected (not thrown), each naming the
+ * offending parameter, so a single invocation reports every problem at once.
+ *
+ * The one opt-out is `def.required: false` — for a parameter that is
+ * genuinely optional with no meaningful default (an ARN that only applies to
+ * a reference-existing deploy, a CIDR override), an unresolved value is
+ * simply omitted from `provenance`/`params` rather than an error; source
+ * reads it as plain `undefined`, same as before migrating off
+ * `process.env.X || undefined`.
+ */
+export function resolveBuildParams(defs: BuildParamsConfig | undefined, input: BuildParamsInput): BuildParamsResolution {
+  const declared = defs ?? {};
+  const cli = input.cli ?? {};
+  const fromFile = input.fromFile ?? {};
+  const env = input.env ?? {};
+  const errors: string[] = [];
+  const provenance: BuildParamProvenance[] = [];
+
+  for (const key of Object.keys(cli)) {
+    if (!(key in declared)) {
+      errors.push(`unknown build parameter "${key}" (from --param) — not declared in chant.config.ts's buildParams`);
+    }
+  }
+  for (const key of Object.keys(fromFile)) {
+    if (!(key in declared)) {
+      errors.push(`unknown build parameter "${key}" (from --params-file) — not declared in chant.config.ts's buildParams`);
+    }
+  }
+
+  for (const [name, def] of Object.entries(declared)) {
+    let raw: BuildParamValue | undefined;
+    let source: BuildParamProvenance["source"] | undefined;
+
+    if (name in cli) {
+      raw = cli[name];
+      source = "cli";
+    } else if (name in fromFile) {
+      const fileValue = fromFile[name];
+      if (typeof fileValue !== "string" && typeof fileValue !== "number" && typeof fileValue !== "boolean") {
+        errors.push(`build parameter "${name}" (from --params-file) must be a string, number, or boolean`);
+        continue;
+      }
+      raw = fileValue;
+      source = "params-file";
+    } else if (def.env && env[def.env] !== undefined) {
+      raw = env[def.env];
+      source = "env";
+    } else if (def.default !== undefined) {
+      raw = def.default;
+      source = "default";
+    }
+
+    if (raw === undefined || source === undefined) {
+      if (def.required === false) continue; // omitted entirely — params.<name> reads as undefined, not an error
+      const envHint = def.env ? `, set ${def.env}` : "";
+      errors.push(
+        `build parameter "${name}" has no value — pass --param ${name}=<value>, use --params-file${envHint}, or add a default in chant.config.ts's buildParams`,
+      );
+      continue;
+    }
+
+    const value = coerce(name, raw, def, errors);
+    if (value === undefined) continue;
+
+    if (def.enum && !def.enum.includes(value)) {
+      errors.push(
+        `build parameter "${name}" must be one of ${def.enum.map(formatValue).join(", ")}, got ${formatValue(value)}`,
+      );
+      continue;
+    }
+
+    provenance.push({ name, value, source });
+  }
+
+  return { provenance, errors };
+}
+
+/** Project the resolved provenance records down to a plain `{ name: value }` map — what actually gets bound to `params.<name>` (see ./params.ts). */
+export function buildParamValues(provenance: readonly BuildParamProvenance[]): Record<string, BuildParamValue> {
+  return Object.fromEntries(provenance.map((p) => [p.name, p.value]));
+}

package/src/build.test.ts

@@ -64,6 +64,44 @@ export const testEntity = {
     expect(result.entities.size).toBe(1);
     expect(result.entities.has("testEntity")).toBe(true);
     expect(result.errors.length).toBe(0);
+    expect(result.foldDecisions).toEqual([]);
+  });
+
+  test("#1022 — --fold folds a leaf-only module and surfaces foldDecisions", async () => {
+    const { dirname, resolve: resolvePath } = await import("node:path");
+    const { fileURLToPath } = await import("node:url");
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    const runtimePath = resolvePath(thisDir, "runtime");
+
+    await writeFile(
+      join(testDir, "resources.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        export const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });
+      `
+    );
+    await writeFile(
+      join(testDir, "main.ts"),
+      `
+        import { Bucket } from "./resources";
+        throw new Error("must never execute — sentinel for #1022 fold verification");
+        export const bucket = new Bucket({ name: "my-bucket" });
+      `
+    );
+
+    const mockSerializer: Serializer = {
+      name: "aws",
+      rulePrefix: "TEST",
+      serialize: (entities) => JSON.stringify([...entities.keys()]),
+    };
+
+    const result = await build(testDir, [mockSerializer], undefined, { fold: true });
+
+    expect(result.errors).toEqual([]);
+    expect(result.entities.size).toBe(1);
+    expect(result.entities.has("bucket")).toBe(true);
+    const mainDecision = result.foldDecisions.find((d) => d.file.endsWith("main.ts"));
+    expect(mainDecision?.mode).toBe("fold");
   });
 
   test("handles discovery errors", async () => {

package/src/build.ts

@@ -1,12 +1,16 @@
 import type { Declarable } from "./declarable";
 import type { Serializer, SerializerResult } from "./serializer";
 import type { OwnershipMarker } from "./ownership";
-import type { DiscoveryError, BuildError } from "./errors";
-import { BuildError as BuildErrorClass } from "./errors";
+import type { BuildError, DiscoveryErrorType } from "./errors";
+import type { IntrinsicDef } from "./lexicon";
+import type { BuildParamProvenance } from "./provenance";
+import { DiscoveryError, BuildError as BuildErrorClass } from "./errors";
 import { LexiconOutput, isLexiconOutput } from "./lexicon-output";
 import { AttrRef } from "./attrref";
 import { isChildProject, type ChildProjectInstance } from "./child-project";
-import { discover } from "./discovery/index";
+import { discover, type DiscoveryResult, type FoldDecision } from "./discovery/index";
+import { decodeEntitySet, type DiscoveredEntitiesJson } from "./discovery/entity-wire";
+import { buildDependencyGraph } from "./discovery/graph";
 import { topologicalSort } from "./sort";
 import { resolve } from "node:path";
 
@@ -149,6 +153,45 @@ export interface BuildOptions {
    * {@link SerializeContext} so a dialect can read its lexicon-scoped settings.
    */
   config?: Record<string, unknown>;
+
+  /**
+   * chant #1022 (epic #1019) — opt-in: fold source modules statically
+   * instead of importing/running them, falling back to run per-file for
+   * anything the folder can't represent. Default `false` (unchanged
+   * behavior). See {@link DiscoveryOptions.fold} in `./discovery/index`.
+   */
+  fold?: boolean;
+
+  /**
+   * chant #1039 — lexicon-registered intrinsic tags (e.g. AWS's `Sub`) to
+   * recognize while folding. Passed straight through to
+   * {@link DiscoveryOptions.intrinsics}; ignored unless {@link fold} is set.
+   * The CLI populates this from `options.plugins.flatMap(p => p.intrinsics?.() ?? [])`.
+   */
+  intrinsics?: IntrinsicDef[];
+
+  /**
+   * chant #1045 Phase 2 — opt-in: run-fallback files (or, when {@link fold}
+   * isn't set, every file) execute together, isolated, in one sandboxed
+   * child process instead of in-process. Passed straight through to
+   * {@link DiscoveryOptions.sandbox} in `./discovery/index`. Default `false`
+   * (unchanged behavior/performance).
+   */
+  sandbox?: boolean;
+
+  /**
+   * chant #1064 — this build's resolved build-time parameter values (see
+   * ./build-params.ts's `resolveBuildParams`, driven by the CLI's
+   * `--param`/`--params-file`/declared `env` mapping/`chant.config.ts`
+   * `buildParams` defaults). Threaded through to `discover()`, which
+   * populates `./params.ts`'s shared `params` object before any project file
+   * is imported or folded, and into the fold session so a `params.<name>`
+   * reference resolves to a literal. Passed through verbatim onto
+   * {@link BuildResult.buildParams} — `build()` itself does no
+   * declaration/validation (that's the CLI/config layer's job); it only
+   * carries the already-resolved records for provenance.
+   */
+  buildParams?: BuildParamProvenance[];
 }
 
 export interface BuildResult {
@@ -166,6 +209,20 @@ export interface BuildResult {
   manifest: BuildManifest;
   /** Number of source files processed */
   sourceFileCount: number;
+  /**
+   * Per-file fold-vs-run decisions (#1022). Empty unless
+   * {@link BuildOptions.fold} was set.
+   */
+  foldDecisions: FoldDecision[];
+
+  /**
+   * This build's resolved build-time parameters (#1064) — the build
+   * provenance record for `params.<name>` values, alongside the existing
+   * entity-level provenance (./provenance.ts). Passed through verbatim from
+   * {@link BuildOptions.buildParams}; empty when the project declares/
+   * supplies none.
+   */
+  buildParams: BuildParamProvenance[];
 }
 
 /**
@@ -451,13 +508,43 @@ export async function build(
   serializers: Serializer[],
   parentBuildStack?: Set<string>,
   options?: BuildOptions,
+): Promise<BuildResult> {
+  // Step 1: Discover entities and dependencies
+  const discoveryResult = await discover(path, {
+    fold: options?.fold,
+    intrinsics: options?.intrinsics,
+    sandbox: options?.sandbox,
+    buildParams: options?.buildParams,
+  });
+
+  return buildFromDiscoveryResult(discoveryResult, path, serializers, parentBuildStack, options);
+}
+
+/**
+ * chant #1045 (Phase 1) — build from a discovery result produced OUTSIDE the
+ * normal `discover(path)` call, i.e. decoded from {@link DiscoveredEntitiesJson}
+ * (see {@link buildFromEntitiesJson}). Everything from here on (topological
+ * sort, recursive child-project builds, partitioning, output detection,
+ * serialization, manifest) is exactly what `build()` already does after its
+ * own `discover()` call — extracted so the JSON path reuses it verbatim
+ * instead of forking it.
+ *
+ * @param resolvedPathForChildStack - Used only to seed the circular-nested-
+ *   stack detection (`buildStack`); the JSON path has no single directory a
+ *   decoded entity set came from, so callers without one may pass any stable
+ *   label (child projects aren't supported by the JSON boundary yet — see
+ *   `discovery/entity-wire.ts` — so this is inert for that path today).
+ */
+async function buildFromDiscoveryResult(
+  discoveryResult: DiscoveryResult,
+  resolvedPathForChildStack: string,
+  serializers: Serializer[],
+  parentBuildStack?: Set<string>,
+  options?: BuildOptions,
 ): Promise<BuildResult> {
   const warnings: string[] = [];
   const errors: Array<DiscoveryError | BuildError> = [];
 
-  // Step 1: Discover entities and dependencies
-  const discoveryResult = await discover(path);
-
   // Collect discovery errors
   errors.push(...discoveryResult.errors);
 
@@ -486,7 +573,7 @@ export async function build(
   }
 
   // Step 4: Recursively build child projects
-  const resolvedPath = resolve(path);
+  const resolvedPath = resolve(resolvedPathForChildStack);
   const buildStack = parentBuildStack
     ? new Set(parentBuildStack)
     : new Set<string>();
@@ -596,5 +683,55 @@ export async function build(
     errors,
     manifest,
     sourceFileCount: discoveryResult.sourceFiles.length,
+    foldDecisions: discoveryResult.foldDecisions,
+    buildParams: options?.buildParams ?? [],
   };
 }
+
+/**
+ * chant #1045 (Phase 1) — build directly from a JSON-encoded discovery
+ * result (see {@link discoverEntitySetJson} in `./discovery/entity-wire.ts`)
+ * instead of pointing `build()` at a directory.
+ *
+ * Decodes the wire entity set back into a live entities map — see
+ * `decodeEntitySet`'s doc for why the decoded entities are functionally
+ * indistinguishable from what `discover()` produces in-process (real
+ * `AttrRef` instances, whole-entity identity preserved by reference, not by
+ * clone) — then runs the exact same post-discovery pipeline `build()` uses
+ * ({@link buildFromDiscoveryResult}), so partitioning, output detection,
+ * serialization, and the manifest are the SAME code path, not a fork of it.
+ *
+ * Dependencies aren't part of the wire format: unlike entities, a dependency
+ * graph is plain name-to-name data with no identity problem, so it's cheaper
+ * and more honest to recompute it from the decoded entities via the same
+ * `buildDependencyGraph()` `discover()` itself uses than to carry a second,
+ * redundant wire shape across the boundary.
+ *
+ * @param label - Used only to seed circular-nested-stack detection; a JSON
+ *   entity set has no single source directory the way a `build(path, …)`
+ *   call does. Inert today — child projects (`nestedStack()`) aren't
+ *   supported by the JSON boundary yet (see `discovery/entity-wire.ts`).
+ */
+export async function buildFromEntitiesJson(
+  json: DiscoveredEntitiesJson,
+  serializers: Serializer[],
+  label = "<json-entity-set>",
+  parentBuildStack?: Set<string>,
+  options?: BuildOptions,
+): Promise<BuildResult> {
+  const entities = decodeEntitySet(json.entitySet);
+  const dependencies = buildDependencyGraph(entities);
+  const errors: DiscoveryError[] = json.errors.map(
+    (e) => new DiscoveryError(e.file, e.message, e.type as DiscoveryErrorType),
+  );
+
+  const discoveryResult: DiscoveryResult = {
+    entities,
+    dependencies,
+    sourceFiles: json.sourceFiles,
+    errors,
+    foldDecisions: json.foldDecisions,
+  };
+
+  return buildFromDiscoveryResult(discoveryResult, label, serializers, parentBuildStack, options);
+}

package/src/cli/commands/build.test.ts

@@ -1,11 +1,12 @@
-import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
 import { buildCommand, resolveBuildFormat, type BuildOptions } from "./build";
 import type { Serializer } from "../../serializer";
 import { parseYAML } from "../../yaml";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, dirname, resolve as resolvePath } from "node:path";
 import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
 
 describe("buildCommand", () => {
   let testDir: string;
@@ -133,6 +134,223 @@ export const testEntity = {
     expect(result.fileCount).toBeDefined();
   });
 
+  test("#1022 — --fold folds a leaf-only module and logs the fold decision", async () => {
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    const runtimePath = resolvePath(thisDir, "../../runtime");
+
+    await writeFile(
+      join(testDir, "resources.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        export const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });
+      `
+    );
+    await writeFile(
+      join(testDir, "main.ts"),
+      `
+        import { Bucket } from "./resources";
+        throw new Error("must never execute — sentinel for #1022 fold verification");
+        export const bucket = new Bucket({ name: "my-bucket" });
+      `
+    );
+
+    const awsSerializer: Serializer = {
+      name: "aws",
+      rulePrefix: "TEST",
+      serialize: (entities) => JSON.stringify([...entities.keys()]),
+    };
+
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const result = await buildCommand({
+        path: testDir,
+        format: "json",
+        serializers: [awsSerializer],
+        fold: true,
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.resourceCount).toBe(1);
+
+      const loggedFoldLine = errorSpy.mock.calls
+        .map((call) => String(call[0]))
+        .some((line) => line.includes("[fold:fold]") && line.includes("main.ts"));
+      expect(loggedFoldLine).toBe(true);
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  test("#1064 — a declared build-time parameter binds to params.<name> and folds to a literal", async () => {
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    const runtimePath = resolvePath(thisDir, "../../runtime");
+    const paramsPath = resolvePath(thisDir, "../../params");
+
+    await writeFile(
+      join(testDir, "chant.config.ts"),
+      `
+        export default {
+          buildParams: {
+            tier: { type: "string", enum: ["light", "production"], default: "light" },
+          },
+        };
+      `,
+    );
+    await writeFile(
+      join(testDir, "resources.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        export const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });
+      `,
+    );
+    await writeFile(
+      join(testDir, "main.ts"),
+      `
+        import { Bucket } from "./resources";
+        import { params } from ${JSON.stringify(paramsPath)};
+        throw new Error("must never execute — sentinel for #1064 fold verification");
+        export const bucket = new Bucket({ name: params.tier });
+      `,
+    );
+
+    const awsSerializer: Serializer = {
+      name: "aws",
+      rulePrefix: "TEST",
+      serialize: (entities) => JSON.stringify([...entities.values()].map((e) => (e as unknown as { props: unknown }).props)),
+    };
+
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const result = await buildCommand({
+        path: testDir,
+        format: "json",
+        serializers: [awsSerializer],
+        fold: true,
+        params: { tier: "production" },
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.resourceCount).toBe(1);
+      expect(result.buildParams).toEqual([{ name: "tier", value: "production", source: "cli" }]);
+
+      const loggedParamLine = errorSpy.mock.calls
+        .map((call) => String(call[0]))
+        .some((line) => line.includes("[param] tier") && line.includes("production") && line.includes("cli"));
+      expect(loggedParamLine).toBe(true);
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  test("#1064 — an unresolved required build-time parameter is a build error naming the parameter, not a thrown error", async () => {
+    await writeFile(
+      join(testDir, "chant.config.ts"),
+      `
+        export default {
+          buildParams: { tier: { type: "string" } },
+        };
+      `,
+    );
+
+    const result = await buildCommand({
+      path: testDir,
+      format: "json",
+      serializers: [mockSerializer],
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.errors.some((e) => e.includes('"tier"') && e.includes("--param"))).toBe(true);
+  });
+
+  test("#1064 — an enum violation is a build error naming the parameter and the allowed values", async () => {
+    await writeFile(
+      join(testDir, "chant.config.ts"),
+      `
+        export default {
+          buildParams: { tier: { type: "string", enum: ["light", "production"] } },
+        };
+      `,
+    );
+
+    const result = await buildCommand({
+      path: testDir,
+      format: "json",
+      serializers: [mockSerializer],
+      params: { tier: "bogus" },
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.errors.some((e) => e.includes('"tier"') && e.includes("bogus"))).toBe(true);
+  });
+
+  test("#1064 — --params-file supplies values from a JSON file, second precedence after --param", async () => {
+    await writeFile(
+      join(testDir, "chant.config.ts"),
+      `
+        export default {
+          buildParams: {
+            tier: { type: "string", default: "light" },
+            env: { type: "string", default: "dev" },
+          },
+        };
+      `,
+    );
+    await writeFile(
+      join(testDir, "test.infra.ts"),
+      `
+        export const testEntity = {
+          lexicon: "test",
+          entityType: "TestEntity",
+          [Symbol.for("chant.declarable")]: true,
+        };
+      `,
+    );
+    const paramsFilePath = join(testDir, "params.json");
+    await writeFile(paramsFilePath, JSON.stringify({ tier: "production", env: "from-file" }));
+
+    const result = await buildCommand({
+      path: testDir,
+      format: "json",
+      serializers: [mockSerializer],
+      params: { tier: "from-cli" },
+      paramsFile: paramsFilePath,
+    });
+
+    expect(result.success).toBe(true);
+    const byName = new Map((result.buildParams ?? []).map((p) => [p.name, p]));
+    expect(byName.get("tier")).toEqual({ name: "tier", value: "from-cli", source: "cli" });
+    expect(byName.get("env")).toEqual({ name: "env", value: "from-file", source: "params-file" });
+  });
+
+  test("--fold is opt-in: omitting it builds via the unchanged run path", async () => {
+    await writeFile(
+      join(testDir, "test.infra.ts"),
+      `
+        export const testEntity = {
+          lexicon: "test",
+          entityType: "TestEntity",
+          [Symbol.for("chant.declarable")]: true,
+        };
+      `
+    );
+
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const result = await buildCommand({
+        path: testDir,
+        format: "json",
+        serializers: [mockSerializer],
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.resourceCount).toBe(1);
+      const anyFoldLine = errorSpy.mock.calls.map((call) => String(call[0])).some((line) => line.includes("[fold:"));
+      expect(anyFoldLine).toBe(false);
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
   test("creates parent directories for the primary output path (#38)", async () => {
     // Write into a nested temp path whose parent dirs don't yet exist —
     // chant build should mkdir -p the parents rather than fail with ENOENT.