@intentius/chant 0.45.0 → 0.49.0

package/src/audit/discover.test.ts

@@ -42,6 +42,29 @@ describe("discoverByDetection (unified, detectTemplate-driven)", () => {
     expect(found.some((i) => i.lexicon === "k8s")).toBe(false);
   });
 
+  test("fountain wins over k8s in a mixed repo — each manifest classifies to its own lexicon (#1566)", async () => {
+    const plugins = await loadAuditPlugins();
+    const found = discoverByDetection(fixture("audit-fountain"), plugins);
+    expect(targets(found)).toEqual(["fountain:agents/fleet.yaml", "k8s:k8s/deploy.yaml"]);
+  });
+
+  test("a multi-document fountain file classifies as one fountain input (no document dropped)", async () => {
+    const plugins = await loadAuditPlugins();
+    const found = discoverByDetection(fixture("audit-fountain"), plugins);
+    const fountain = found.find((i) => i.lexicon === "fountain")!;
+    // All three documents ride along in the input's content.
+    expect(fountain.content.match(/apiVersion: fountain\.dev\/v1/g)).toHaveLength(3);
+  });
+
+  test("without the fountain plugin, fountain YAML falls to k8s (not-installed convention)", () => {
+    const files = [{ path: "fleet.yaml", content: "apiVersion: fountain.dev/v1\nkind: Environment\nmetadata:\n  name: dev\n" }];
+    const k8s = { name: "k8s", detectTemplate: (d: unknown) => !!d && typeof d === "object" && "apiVersion" in (d as object) && "kind" in (d as object) };
+    expect(classifyFiles(files, [k8s]).map((i) => i.lexicon)).toEqual(["k8s"]);
+    // with a fountain plugin present, fountain claims it first
+    const fountain = { name: "fountain", detectTemplate: (d: unknown) => (d as { apiVersion?: unknown })?.apiVersion === "fountain.dev/v1" };
+    expect(classifyFiles(files, [k8s, fountain]).map((i) => i.lexicon)).toEqual(["fountain"]);
+  });
+
   test("detects a Helm chart as a bundle, not loose manifests", async () => {
     const plugins = await loadAuditPlugins();
     const found = discoverByDetection(fixture("audit-helm"), plugins);
@@ -80,6 +103,7 @@ describe("lexicon hints for unclaimed files (#1623)", () => {
     expect(hintLexiconForFile("charts/x/Chart.yaml", "name: x\n")).toBe("helm");
     expect(hintLexiconForFile("infra/main.tf", "resource {}\n")).toBe("terraform");
     expect(hintLexiconForFile("k8s/deploy.yaml", "apiVersion: apps/v1\nkind: Deployment\n")).toBe("k8s");
+    expect(hintLexiconForFile("agents/fleet.yaml", "apiVersion: fountain.dev/v1\nkind: Environment\n")).toBe("fountain");
     expect(hintLexiconForFile("gcp/bucket.yaml", "apiVersion: storage.cnrm.cloud.google.com/v1beta1\nkind: StorageBucket\n")).toBe("gcp");
     expect(hintLexiconForFile("cfn/stack.yaml", "AWSTemplateFormatVersion: '2010-09-09'\nResources: {}\n")).toBe("aws");
     expect(hintLexiconForFile("cfn/stack.json", '{"Resources":{"B":{"Type":"AWS::S3::Bucket"}}}')).toBe("aws");

package/src/audit/discover.ts

@@ -22,7 +22,8 @@
  *   - Helm charts are a directory BUNDLE keyed by `Chart.yaml`; the helm checks
  *     read `output.files`, so the whole chart is one AuditInput.
  *   - k8s `detectTemplate` matches any `apiVersion`+`kind`, including GCP Config
- *     Connector (`cnrm.cloud.google.com`) resources, so gcp must be tried first.
+ *     Connector (`cnrm.cloud.google.com`) resources and fountain
+ *     (`fountain.dev/v1`) manifests, so gcp and fountain must be tried first.
  *   - aws/azure checks `JSON.parse` their input, so YAML/templated content is
  *     normalized to a JSON string here.
  */
@@ -34,7 +35,7 @@ import type { LexiconPlugin } from "../lexicon";
 import type { AuditInput, AuditLexicon } from "./core";
 
 /** Lexicons the auditor knows how to detect and run checks for. */
-export const AUDIT_LEXICONS = ["github", "gitlab", "forgejo", "k8s", "docker", "aws", "azure", "gcp", "helm"] as const;
+export const AUDIT_LEXICONS = ["github", "gitlab", "forgejo", "k8s", "docker", "aws", "azure", "gcp", "helm", "fountain"] as const;
 
 /**
  * Load the plugins used for detection. Each is loaded in isolation (no
@@ -170,6 +171,13 @@ const CONTENT_DETECTORS: ContentDetector[] = [
     accepts: isYaml,
     detect: (plugin, _name, content) => (anyDoc(plugin, content) ? content : null),
   },
+  {
+    // fountain (`apiVersion: fountain.dev/v1`) — must win over k8s, whose
+    // detectTemplate matches any apiVersion+kind document (#1566).
+    lexicon: "fountain",
+    accepts: isYaml,
+    detect: (plugin, _name, content) => (anyDoc(plugin, content) ? content : null),
+  },
   {
     lexicon: "k8s",
     accepts: isYaml,
@@ -263,6 +271,7 @@ export function hintLexiconForFile(path: string, content: string): LexiconHint |
   if (/\.tf$/i.test(name)) return "terraform";
   const head = content.slice(0, 64 * 1024);
   if (/cnrm\.cloud\.google\.com/.test(head)) return "gcp";
+  if (/fountain\.dev\/v1/.test(head)) return "fountain";
   if (/AWSTemplateFormatVersion|["']?Type["']?\s*:\s*["']AWS::/.test(head)) return "aws";
   if (/deploymentTemplate\.json/.test(head)) return "azure";
   if (isYaml(name)) {

package/src/audit/rules-doc.ts

@@ -20,14 +20,24 @@ const GROUPS: Array<{ heading: string; prefixes: string[]; blurb: string }> = [
   { heading: "Azure ARM (AZR)", prefixes: ["AZR"], blurb: "Run against ARM deployment templates (JSON)." },
   { heading: "GCP Config Connector (WGC)", prefixes: ["WGC"], blurb: "Run against Config Connector (cnrm.cloud.google.com) manifests." },
   { heading: "Helm (WHM)", prefixes: ["WHM"], blurb: "Run against Helm charts (Chart.yaml + templates)." },
+  { heading: "fountain (FTN)", prefixes: ["FTN"], blurb: "Run against fountain manifests (`apiVersion: fountain.dev/v1`) — standalone `fountain apply` YAML is parsed back into the entity graph, so the same rules fire on `chant build` and `chant audit`." },
 ];
 
+/**
+ * MDX treats `{expr}` as a JavaScript expression and `<x` as JSX, so rule
+ * text containing literal braces (`${VAR}` substitution references) or angle
+ * brackets must be escaped or the docs build fails at render time.
+ */
+function mdxEscape(text: string): string {
+  return text.replace(/\{/g, "\\{").replace(/</g, "\\<");
+}
+
 function ruleBlock(m: RuleMeta): string {
   const tags = `${m.tier} · ${m.fixKind}`;
   const authority = m.authority?.length
     ? `\n\nAuthority: ${m.authority.map((a) => `[${a.name}](${a.url})`).join(" · ")}`
     : "";
-  return `### ${m.id}\n\n**${m.title}** — ${tags}\n\n${m.remediation}${authority}`;
+  return `### ${m.id}\n\n**${mdxEscape(m.title)}** — ${tags}\n\n${mdxEscape(m.remediation)}${authority}`;
 }
 
 /**

package/src/build.test.ts

@@ -338,6 +338,47 @@ export const discovered = {
     expect(result.entities.get("discovered")?.entityType).toBe("Discovered");
   });
 
+  test("a contributor sees the discovered entities, read-only", async () => {
+    await writeFile(
+      join(testDir, "app.infra.ts"),
+      `
+export const discovered = {
+  lexicon: "test",
+  entityType: "Discovered",
+  props: {},
+  [Symbol.for("chant.declarable")]: true,
+};
+      `,
+    );
+
+    let seenNames: string[] = [];
+    const result = await build(testDir, [recordingSerializer([])], undefined, {
+      buildRoots: [
+        async (ctx) => {
+          seenNames = [...(ctx.entities?.keys() ?? [])];
+          return { entities: new Map() };
+        },
+      ],
+    });
+
+    expect(result.errors).toEqual([]);
+    expect(seenNames).toContain("discovered");
+  });
+
+  test("a later contributor sees what an earlier one contributed", async () => {
+    const seen: string[][] = [];
+    await build(testDir, [recordingSerializer([])], undefined, {
+      buildRoots: [
+        async () => ({ entities: new Map([["first", entity("First")]]) }),
+        async (ctx) => {
+          seen.push([...(ctx.entities?.keys() ?? [])]);
+          return { entities: new Map() };
+        },
+      ],
+    });
+    expect(seen[0]).toContain("first");
+  });
+
   test("contributors run exactly once per build", async () => {
     let calls = 0;
     await build(testDir, [], undefined, {

package/src/build.ts

@@ -2,10 +2,12 @@ import type { Declarable } from "./declarable";
 import type { Serializer, SerializerResult } from "./serializer";
 import type { OwnershipMarker } from "./ownership";
 import type { BuildError, DiscoveryErrorType } from "./errors";
-import type { IntrinsicDef, BuildRootContribution } from "./lexicon";
+import type { IntrinsicDef, BuildRootContribution, BuildRootContributor } from "./lexicon";
 import type { BuildParamProvenance } from "./provenance";
 import { DiscoveryError, BuildError as BuildErrorClass } from "./errors";
 import { LexiconOutput, isLexiconOutput } from "./lexicon-output";
+import { isSecretDeclaration } from "./secret-provenance";
+import { splitReceiptEntities } from "./effect-receipt";
 import { AttrRef } from "./attrref";
 import { isAttrRefLike } from "./utils";
 import { isChildProject, type ChildProjectInstance } from "./child-project";
@@ -112,7 +114,9 @@ export function computeStackGraph(
   // Dependency map: node → producers it depends on.
   const nodes = lexiconNames.length
     ? [...lexiconNames]
-    : [...new Set([...entities.values()].map((e) => e.lexicon))];
+    : // Secret provenance declarations (#1828) never form a stack — their
+      // pseudo-lexicon has no serializer and must not appear in the manifest.
+      [...new Set([...entities.values()].filter((e) => !isSecretDeclaration(e)).map((e) => e.lexicon))];
   const deps = new Map<string, Set<string>>();
   for (const n of nodes) deps.set(n, new Set());
   for (const { from, to } of edges) {
@@ -229,7 +233,7 @@ export interface BuildOptions {
    * binaries); a contributed name colliding with a discovered entity is a
    * build error, never a silent overwrite.
    */
-  buildRoots?: Array<() => Promise<BuildRootContribution>>;
+  buildRoots?: BuildRootContributor[];
 }
 
 export interface BuildResult {
@@ -294,6 +298,11 @@ export function partitionByLexicon(
   for (const [name, entity] of entities) {
     // LexiconOutput instances are collected separately; skip them here
     if (isLexiconOutput(entity)) continue;
+    // Secret provenance declarations (#1828) are serializer-neutral: data
+    // that lint and lexicons read from the entity map, never output. Keeping
+    // them out of every partition means no serializer sees them and no
+    // "No serializer found" warning fires for their pseudo-lexicon.
+    if (isSecretDeclaration(entity)) continue;
     const lexicon = entity.lexicon;
     if (!partitions.has(lexicon)) {
       partitions.set(lexicon, new Map());
@@ -590,13 +599,18 @@ export interface BuildRootMergeResult {
  */
 export async function mergeBuildRootEntities(
   entities: Map<string, Declarable>,
-  contributors: ReadonlyArray<() => Promise<BuildRootContribution>>,
+  contributors: ReadonlyArray<BuildRootContributor>,
 ): Promise<BuildRootMergeResult> {
   const warnings: string[] = [];
   const errors: string[] = [];
   for (const contribute of contributors) {
     try {
-      const contribution = await contribute();
+      // The discovered set, read-only, so a contributor can react to what the
+      // project DECLARED (a committed-encrypted `declareSecret()` naming a
+      // ciphertext file to resolve). Contributors run in order, so this also
+      // carries what earlier contributors added; the merge below is still the
+      // only writer, which is what keeps the collision refusal meaningful.
+      const contribution = await contribute({ entities });
       warnings.push(...(contribution.warnings ?? []));
       for (const [name, entity] of contribution.entities) {
         if (entities.has(name)) {
@@ -785,20 +799,34 @@ async function buildFromDiscoveryResult(
   const outputs = new Map<string, string | SerializerResult>();
   for (const [lexiconName, lexiconEntities] of partitions) {
     const serializer = serializersByName.get(lexiconName);
+    // #1832: effect receipts are withheld from the apply-bound entity set at
+    // this seam — the narrowest choke point every applier's input flows
+    // through, since appliers consume the serialized outputs assembled here.
+    // Receipts ride `SerializeContext.receipts` instead, so a lexicon can
+    // render them for visibility (#1835) without them ever entering the
+    // document an applier writes (or prunes) from. The `effect()` step is the
+    // sole receipt writer (epic #1703, decision 3).
+    const { applyBound, receipts } = splitReceiptEntities(lexiconEntities);
     if (serializer) {
       const lexiconLexiconOutputs = [
         ...(outputsByLexicon.get(lexiconName) ?? []),
         ...unassignedOutputs,
       ];
-      const serialized = serializer.serialize(lexiconEntities, lexiconLexiconOutputs, {
+      const serialized = serializer.serialize(applyBound, lexiconLexiconOutputs, {
         ownership: options?.ownership,
         config: options?.config,
+        ...(receipts.size > 0 ? { receipts } : {}),
       });
       // Collect any non-fatal serializer diagnostics into the build warnings.
       if (typeof serialized !== "string" && serialized.warnings) {
         for (const w of serialized.warnings) warnings.push(w);
       }
       outputs.set(lexiconName, serialized);
+    } else if (applyBound.size === 0 && receipts.size > 0) {
+      // A partition holding only receipts (the core factory's "chant"
+      // pseudo-lexicon) has nothing apply-bound to serialize; that is the
+      // designed shape until a lexicon materializes the receipt (#1835), not
+      // a missing-serializer problem.
     } else {
       warnings.push(`No serializer found for lexicon "${lexiconName}"`);
     }

package/src/cli/commands/__fixtures__/audit-fountain/agents/fleet.yaml

@@ -0,0 +1,27 @@
+apiVersion: fountain.dev/v1
+kind: Environment
+metadata:
+  name: dev
+spec:
+  networking_type: unrestricted
+  env_vars:
+    API_URL: https://api.example.com
+    AWS_SECRET_ACCESS_KEY: not-a-real-secret
+---
+apiVersion: fountain.dev/v1
+kind: Vault
+metadata:
+  name: staging
+spec:
+  secrets:
+    - key: API_URL
+      value: https://staging.example.com
+---
+apiVersion: fountain.dev/v1
+kind: Agent
+metadata:
+  name: researcher
+spec:
+  model: anthropic/claude-sonnet-4-6
+  runtime: claude
+  environment: dev

package/src/cli/commands/__fixtures__/audit-fountain/k8s/deploy.yaml

@@ -0,0 +1,16 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: web
+spec:
+  selector:
+    matchLabels:
+      app: web
+  template:
+    metadata:
+      labels:
+        app: web
+    spec:
+      containers:
+        - name: web
+          image: nginx:1.27

package/src/cli/commands/__fixtures__/audit-fountain-clean/fleet.yaml

@@ -0,0 +1,20 @@
+apiVersion: fountain.dev/v1
+kind: Environment
+metadata:
+  name: dev
+spec:
+  networking_type: limited
+  networking_config:
+    allowed_hosts:
+      - github.com
+  env_vars:
+    API_URL: https://api.example.com
+---
+apiVersion: fountain.dev/v1
+kind: Agent
+metadata:
+  name: researcher
+spec:
+  model: anthropic/claude-sonnet-4-6
+  runtime: claude
+  environment: dev

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

@@ -105,6 +105,59 @@ describe("auditCommand", () => {
     expect([...ids].some((id) => id.startsWith("WK8"))).toBe(false);
   });
 
+  test("discovers and audits fountain manifests (not misclassified as k8s) — FTN rules fire (#1566/#1567)", async () => {
+    const repo = fileURLToPath(new URL("./__fixtures__/audit-fountain", import.meta.url));
+    const fountain = await discoverLexicon(repo, "fountain");
+    expect(fountain.map((f) => f.path)).toEqual(["agents/fleet.yaml"]);
+    // The fountain manifest is NOT also picked up as k8s; the plain k8s manifest still is.
+    expect((await discoverLexicon(repo, "k8s")).map((f) => f.path)).toEqual(["k8s/deploy.yaml"]);
+
+    const result = await auditCommand({ path: repo, format: "stylish" });
+    expect(result.success).toBe(true);
+    const ftn = result.findings.filter((f) => f.checkId.startsWith("FTN"));
+    const ids = new Set(ftn.map((f) => f.checkId));
+    expect(ids).toContain("FTN011"); // unrestricted networking
+    expect(ids).toContain("FTN012"); // credential-shaped env_vars key
+    expect(ids).toContain("FTN014"); // vault key shadows an environment key
+    expect(ftn.find((f) => f.checkId === "FTN012")!.severity).toBe("error");
+    for (const f of ftn) {
+      expect(f.lexicon).toBe("fountain");
+      expect(f.file).toBe("agents/fleet.yaml");
+    }
+    // No k8s check ran against the fountain manifest.
+    for (const f of result.findings.filter((f) => f.lexicon === "k8s")) {
+      expect(f.file).not.toBe("agents/fleet.yaml");
+    }
+  });
+
+  test("fountain findings carry their authority citations in json, sarif, and markdown", async () => {
+    const repo = fileURLToPath(new URL("./__fixtures__/audit-fountain", import.meta.url));
+
+    const json = await auditCommand({ path: repo, format: "json" });
+    const envelope = JSON.parse(json.output) as { findings: Array<{ checkId: string; authority: Array<{ url: string }>; severity: string }> };
+    const ftn11 = envelope.findings.find((f) => f.checkId === "FTN011")!;
+    expect(ftn11.authority.length).toBeGreaterThan(0);
+    expect(ftn11.authority[0].url).toContain("fountain");
+    expect(envelope.findings.find((f) => f.checkId === "FTN012")!.severity).toBe("error");
+
+    const sarif = await auditCommand({ path: repo, format: "sarif" });
+    const run = (JSON.parse(sarif.output) as { runs: Array<{ tool: { driver: { rules: Array<{ id: string; helpUri?: string }> } }; results: Array<{ ruleId: string }> }> }).runs[0];
+    expect(run.results.some((r) => r.ruleId === "FTN011")).toBe(true);
+    expect(run.tool.driver.rules.find((r) => r.id === "FTN011")!.helpUri).toContain("fountain");
+
+    const md = await auditCommand({ path: repo, format: "markdown" });
+    expect(md.output).toContain("FTN011");
+    expect(md.output).toContain("FTN014");
+  });
+
+  test("a clean fountain manifest set audits quiet", async () => {
+    const repo = fileURLToPath(new URL("./__fixtures__/audit-fountain-clean", import.meta.url));
+    const result = await auditCommand({ path: repo, format: "stylish" });
+    expect(result.success).toBe(true);
+    expect(result.findings).toEqual([]);
+    expect(result.scanned).toEqual(["fleet.yaml"]);
+  });
+
   test("discovers and audits a Helm chart (as a bundle, not loose manifests)", async () => {
     const repo = fileURLToPath(new URL("./__fixtures__/audit-helm", import.meta.url));
     const charts = await discoverLexicon(repo, "helm");

package/src/cli/commands/audit.ts

@@ -123,7 +123,7 @@ function renderNoLexicons(target: string, unclaimed: UnclaimedFile[]): string {
       lines.push(`  ${u.path}  ->  ${note}`);
     }
   } else {
-    lines.push("", "No file under the target looked like CI, Kubernetes, Helm, Docker, CloudFormation, ARM, or Config Connector either.");
+    lines.push("", "No file under the target looked like CI, Kubernetes, Helm, Docker, CloudFormation, ARM, Config Connector, or fountain either.");
   }
   lines.push("", "Run it with the lexicons those files need:");
   lines.push(`  ${installLine(wanted.length > 0 ? wanted : [...AUDIT_LEXICONS], target)}`);

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

@@ -309,6 +309,137 @@ export const testEntity = {
     });
   });
 
+  describe("#1221 — dynamic-env legality against declared environments", () => {
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    const runtimePath = resolvePath(thisDir, "../../runtime");
+    const paramsPath = resolvePath(thisDir, "../../params");
+
+    // Serializer exposing the physical name (from params.env interpolation)
+    // next to the ownership marker, so one test can assert both are disjoint
+    // across two builds.
+    const namingSerializer: Serializer = {
+      name: "aws",
+      rulePrefix: "TEST",
+      serialize: (entities, _outputs, context) =>
+        JSON.stringify(
+          [...entities.values()].map((e) => ({
+            name: (e as unknown as { props: { name: string } }).props.name,
+            marker: context?.ownership,
+          })),
+        ),
+    };
+
+    async function writeProject(environments: string) {
+      await writeFile(
+        join(testDir, "chant.config.ts"),
+        `
+          export default {
+            environments: ${environments},
+            ownership: { stack: "billing", env: { param: "env" } },
+            buildParams: {
+              env: { type: "string", default: "dev" },
+            },
+          };
+        `,
+      );
+      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)};
+          export const uploads = new Bucket({ name: \`billing-\${params.env}-uploads\` });
+        `,
+      );
+    }
+
+    function built(): Array<{ name: string; marker?: { stack: string; env?: string } }> {
+      return JSON.parse(readFileSync(outputFile, "utf-8"));
+    }
+
+    async function buildWithEnv(env: string) {
+      return buildCommand({
+        path: testDir,
+        output: outputFile,
+        format: "json",
+        serializers: [namingSerializer],
+        params: { env },
+      });
+    }
+
+    test("--param env=pr-42 is legal when a pr-* pattern entry is declared", async () => {
+      await writeProject(`["dev", "prod", "pr-*"]`);
+      const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+      try {
+        const result = await buildWithEnv("pr-42");
+        expect(result.errors).toEqual([]);
+        expect(result.success).toBe(true);
+        expect(built()).toEqual([{ name: "billing-pr-42-uploads", marker: { stack: "billing", env: "pr-42" } }]);
+      } finally {
+        errorSpy.mockRestore();
+      }
+    });
+
+    test("--param env outside the declared entries (no pattern covers it) fails the build", async () => {
+      await writeProject(`["dev", "prod"]`);
+      const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+      try {
+        const result = await buildWithEnv("pr-42");
+        expect(result.success).toBe(false);
+        expect(result.errors.some((e) => e.includes('Unknown environment "pr-42"'))).toBe(true);
+      } finally {
+        errorSpy.mockRestore();
+      }
+    });
+
+    test("a literal entry still matches by equality", async () => {
+      await writeProject(`["dev", "prod", "pr-*"]`);
+      const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+      try {
+        const result = await buildWithEnv("prod");
+        expect(result.errors).toEqual([]);
+        expect(built()).toEqual([{ name: "billing-prod-uploads", marker: { stack: "billing", env: "prod" } }]);
+      } finally {
+        errorSpy.mockRestore();
+      }
+    });
+
+    test("two builds with different --param env yield disjoint names and disjoint markers", async () => {
+      await writeProject(`["dev", "prod", "pr-*"]`);
+      const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+      try {
+        expect((await buildWithEnv("pr-1")).success).toBe(true);
+        const first = built();
+        expect((await buildWithEnv("pr-2")).success).toBe(true);
+        const second = built();
+        expect(first).toEqual([{ name: "billing-pr-1-uploads", marker: { stack: "billing", env: "pr-1" } }]);
+        expect(second).toEqual([{ name: "billing-pr-2-uploads", marker: { stack: "billing", env: "pr-2" } }]);
+        expect(first[0].name).not.toBe(second[0].name);
+        expect(first[0].marker?.env).not.toBe(second[0].marker?.env);
+      } finally {
+        errorSpy.mockRestore();
+      }
+    });
+
+    test("a project with no declared environments accepts any dynamic value, as before", async () => {
+      await writeProject(`undefined`);
+      const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+      try {
+        const result = await buildWithEnv("anything-goes");
+        expect(result.errors).toEqual([]);
+        expect(built()).toEqual([{ name: "billing-anything-goes-uploads", marker: { stack: "billing", env: "anything-goes" } }]);
+      } 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");
@@ -574,6 +705,86 @@ export const testEntity = {
     expect(existsSync(join(testDir, "dist", "ops", "alb-deploy", "worker.ts"))).toBe(true);
   });
 
+  describe("committed-encrypted secret sidecars", () => {
+    const CIPHERTEXT = 'apiVersion: v1\nkind: Secret\nstringData:\n  T: ENC[AES256_GCM,data:xx]\nsops:\n  version: 3.9.4\n';
+
+    /** A serializer standing in for the k8s one: a sidecar plus a primary doc. */
+    const sidecarSerializer: Serializer = {
+      name: "multi",
+      rulePrefix: "MULTI",
+      serialize: () => ({ primary: "kind: Deployment\n", files: { "db.sops.yaml": CIPHERTEXT } }),
+    };
+
+    async function writeProject(fileValue: string): Promise<void> {
+      const modulePath = resolvePath(
+        dirname(fileURLToPath(import.meta.url)),
+        "..",
+        "..",
+        "secret-provenance",
+      );
+      await writeFile(
+        join(testDir, "infra.ts"),
+        `import { declareSecret } from ${JSON.stringify(modulePath)};
+export const dbCredentials = declareSecret({ name: "db-credentials", provenance: "committed-encrypted", file: ${JSON.stringify(fileValue)} });
+export const x = { [Symbol.for("chant.declarable")]: true, entityType: "X", lexicon: "multi", kind: "resource", props: {}, attributes: {} };`,
+      );
+    }
+
+    test("a build with no --output refuses, naming the flag", async () => {
+      await writeProject("secrets/db.sops.yaml");
+
+      const result = await buildCommand({
+        path: testDir,
+        format: "yaml",
+        serializers: [sidecarSerializer],
+        // no `output` — the sidecar would be echoed to stderr and lost
+      } as BuildOptions);
+
+      expect(result.success).toBe(false);
+      expect(result.errors.join("\n")).toContain("--output");
+      expect(result.errors.join("\n")).toContain("db.sops.yaml");
+    });
+
+    test("with --output the sidecar lands beside the primary, byte for byte", async () => {
+      await writeProject("secrets/db.sops.yaml");
+      const outputPath = join(testDir, "dist", "manifests.yaml");
+
+      const result = await buildCommand({
+        path: testDir,
+        output: outputPath,
+        format: "yaml",
+        serializers: [sidecarSerializer],
+      });
+
+      expect(result.errors).toEqual([]);
+      expect(readFileSync(join(testDir, "dist", "db.sops.yaml"), "utf-8")).toBe(CIPHERTEXT);
+    });
+
+    test("a declared sidecar is never round-tripped through JSON.parse", async () => {
+      // YAML is a JSON superset, so a ciphertext file that happens to parse as
+      // JSON would otherwise be rewritten key-sorted (or re-emitted as YAML),
+      // breaking the `sops` MAC. Declared files skip that path entirely.
+      const jsonish = '{"b": 1, "a": 2}\n';
+      const jsonSidecar: Serializer = {
+        name: "multi",
+        rulePrefix: "MULTI",
+        serialize: () => ({ primary: "kind: Deployment\n", files: { "db.sops.yaml": jsonish } }),
+      };
+      await writeProject("secrets/db.sops.yaml");
+      const outputPath = join(testDir, "dist", "manifests.yaml");
+
+      const result = await buildCommand({
+        path: testDir,
+        output: outputPath,
+        format: "yaml",
+        serializers: [jsonSidecar],
+      });
+
+      expect(result.errors).toEqual([]);
+      expect(readFileSync(join(testDir, "dist", "db.sops.yaml"), "utf-8")).toBe(jsonish);
+    });
+  });
+
   test("op worker files go to <project>/dist/ops even with no --output (#878)", async () => {
     // The generated Op worker must land where `chant run <op> --temporal` reads it
     // (`<project>/dist/ops/<name>/worker.ts`) even when the build has no --output