@intentius/chant 0.46.0 → 0.49.0

package/dist/secret-provenance.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Secret provenance vocabulary (chant #1828, epic #1365).
+ *
+ * A secret's PROVENANCE is where its value comes from — never what the value
+ * is. chant's constitutional line on secrets: no code path may hold, log,
+ * hash, or compare a secret value. This module makes that structural: the
+ * declaration types have no field that could carry material, the factory
+ * rejects material-shaped fields at both the type level (`never` fields) and
+ * at runtime (own-property check, naming only the offending KEY), and
+ * "mismatch" anywhere downstream means presence, declared key-set, and
+ * metadata — never a value or a value-derived hash (#1365 decision 6).
+ *
+ * The closed kind set:
+ *
+ * - `referenced` — the value exists out of band (a human or an external
+ *   process put it where consumers read it). chant records only that the
+ *   estate depends on it, which is what lets the consumed-but-unproduced
+ *   check (#1382) ship as an error instead of a guess.
+ * - `from-provider` — a declared provider binding materializes it (the
+ *   operator/CRD seam; `K8s::Infisical::InfisicalSecret` from #1321 is the
+ *   exemplar). The declaration POINTS at that binding, it does not re-model
+ *   it.
+ * - `generated-once` — minted on first materialization, then never
+ *   regenerated (present means done). The declaration carries contract flags
+ *   only — e.g. the declared key-set — never mint parameters holding
+ *   material. `generated-once` secrets never enter the prunable set (#1365
+ *   decision 5).
+ * - `committed-encrypted` — sops-style ciphertext committed in the repo,
+ *   decrypted by the delivery system (Flux) straight into the target. The
+ *   declaration records a repo-relative PATH to the ciphertext, never the
+ *   bytes: the factory is pure and touches no filesystem, so it still folds
+ *   under `--sandbox`. The bytes are read at `buildRoots()` — the one
+ *   sanctioned impure seam — and emitted as a sidecar file, never as a
+ *   document in the primary output. See
+ *   `docs/design/committed-encrypted-sops-provenance.md`.
+ *
+ * Declarations are serializer-neutral: discovery collects them like any
+ * entity (they are Declarables), but `partitionByLexicon` (../build.ts)
+ * excludes them from every serializer partition, so no lexicon ever emits
+ * them. They are data that lint rules and lexicons READ (via
+ * {@link collectSecretDeclarations}), not output.
+ */
+import { type Declarable } from "./declarable.js";
+/** The closed union of secret origins. */
+export type SecretProvenance = "referenced" | "from-provider" | "generated-once" | "committed-encrypted";
+/** Every provenance kind, for exhaustiveness checks. */
+export declare const SECRET_PROVENANCE_KINDS: readonly SecretProvenance[];
+/**
+ * Encryption tools a {@link CommittedEncryptedSecretDeclaration} understands.
+ * A closed union with one member, not a free string: a second tool later is a
+ * deliberate widening with a detection rule attached, not an unvalidated
+ * string that silently means nothing.
+ */
+export type SecretEncryption = "sops";
+/** Every encryption tool, for exhaustiveness checks. */
+export declare const SECRET_ENCRYPTION_TOOLS: readonly SecretEncryption[];
+/** Marker symbol identifying a secret provenance declaration. `Symbol.for` so
+ * it survives the entity-wire codec (../discovery/entity-wire-codec.ts). */
+export declare const SECRET_DECLARATION_MARKER: unique symbol;
+/** The `entityType` every secret declaration carries. */
+export declare const SECRET_DECLARATION_ENTITY_TYPE = "Chant::SecretProvenance";
+/**
+ * Points a `from-provider` declaration at the provider binding that
+ * materializes the secret — the CRD seam, not a re-model of it. The binding
+ * itself is an ordinary declarable in its own lexicon (e.g. an
+ * `InfisicalSecret` instance, #1321); this ref names it so lint can resolve
+ * the pair without core depending on any lexicon.
+ */
+export interface SecretProviderRef {
+    /** Entity name (export name) of the provider binding declarable in this project. */
+    readonly binding: string;
+    /**
+     * Expected `entityType` of the binding (e.g.
+     * `"K8s::Infisical::InfisicalSecret"`). Optional; when present, lint can
+     * verify the named binding is actually the kind of seam the declaration
+     * claims.
+     */
+    readonly entityType?: string;
+}
+/**
+ * Fields that would carry secret material, forbidden by construction. Typed
+ * as `never` on every factory input so they fail to compile even when the
+ * input object was widened or spread (plain excess-property checks only catch
+ * object literals). The runtime check in {@link declareSecret} is the same
+ * list, for untyped callers.
+ */
+interface NoSecretMaterial {
+    readonly value?: never;
+    readonly data?: never;
+    readonly stringData?: never;
+    readonly material?: never;
+    readonly plaintext?: never;
+    readonly ciphertext?: never;
+}
+/** Fields shared by every secret declaration. */
+interface SecretDeclarationBase extends Declarable {
+    readonly [SECRET_DECLARATION_MARKER]: true;
+    readonly lexicon: "chant";
+    readonly entityType: typeof SECRET_DECLARATION_ENTITY_TYPE;
+    /** The secret's name as consumers know it (e.g. the k8s Secret name). */
+    readonly name: string;
+    /** Which of the closed kind set this declaration is. */
+    readonly provenance: SecretProvenance;
+}
+/** A secret whose value exists out of band. */
+export interface ReferencedSecretDeclaration extends SecretDeclarationBase {
+    readonly provenance: "referenced";
+    /** Where consumers find it — free-form (a namespace, a vault path, a doc link). */
+    readonly scope?: string;
+}
+/** A secret a declared provider binding materializes. */
+export interface FromProviderSecretDeclaration extends SecretDeclarationBase {
+    readonly provenance: "from-provider";
+    readonly provider: SecretProviderRef;
+}
+/** A secret minted on first materialization and never regenerated. */
+export interface GeneratedOnceSecretDeclaration extends SecretDeclarationBase {
+    readonly provenance: "generated-once";
+    /**
+     * The declared key-set of the materialized secret. This is the contract a
+     * materializer (#1830) checks for mismatch — presence and keys, never
+     * values.
+     */
+    readonly keys?: readonly string[];
+}
+/**
+ * A secret whose ciphertext is committed to the repo and decrypted by the
+ * delivery system on the way into the target.
+ *
+ * The declaration is a POINTER: `file` is a repo-relative path, and nothing
+ * here carries bytes. That is what keeps the factory pure — the ciphertext is
+ * read at `buildRoots()` and emitted as a sidecar, never inlined into the
+ * primary output an applier reads.
+ */
+export interface CommittedEncryptedSecretDeclaration extends SecretDeclarationBase {
+    readonly provenance: "committed-encrypted";
+    /** Repo-relative path to the committed ciphertext file. */
+    readonly file: string;
+    /** Encryption tool. Defaults to `"sops"` when omitted. */
+    readonly encryption: SecretEncryption;
+    /**
+     * Public recipient identifiers — age recipients or PGP fingerprints. Public
+     * by definition, which is the opposite of material; a private key here is
+     * refused by the factory.
+     */
+    readonly recipients?: readonly string[];
+    /**
+     * The declared key-set of the decrypted Secret — the same contract meaning
+     * as {@link GeneratedOnceSecretDeclaration.keys}: presence and key names,
+     * never values. SOPS leaves key NAMES cleartext, so this is checkable
+     * against the file itself.
+     */
+    readonly keys?: readonly string[];
+}
+/** A secret provenance declaration — the discriminant is `provenance`. */
+export type SecretDeclaration = ReferencedSecretDeclaration | FromProviderSecretDeclaration | GeneratedOnceSecretDeclaration | CommittedEncryptedSecretDeclaration;
+/** Narrow a declaration to the committed-encrypted kind. */
+export declare function isCommittedEncryptedSecret(decl: SecretDeclaration): decl is CommittedEncryptedSecretDeclaration;
+/** Factory input for a `referenced` secret. */
+export interface ReferencedSecretInput extends NoSecretMaterial {
+    readonly name: string;
+    readonly provenance: "referenced";
+    readonly scope?: string;
+}
+/** Factory input for a `from-provider` secret. */
+export interface FromProviderSecretInput extends NoSecretMaterial {
+    readonly name: string;
+    readonly provenance: "from-provider";
+    readonly provider: SecretProviderRef;
+}
+/** Factory input for a `generated-once` secret. */
+export interface GeneratedOnceSecretInput extends NoSecretMaterial {
+    readonly name: string;
+    readonly provenance: "generated-once";
+    readonly keys?: readonly string[];
+}
+/** Factory input for a `committed-encrypted` secret. */
+export interface CommittedEncryptedSecretInput extends NoSecretMaterial {
+    readonly name: string;
+    readonly provenance: "committed-encrypted";
+    /**
+     * Repo-relative path to the committed ciphertext file — `file`, never
+     * `ciphertext`: the declaration points at bytes, it does not carry them,
+     * and `ciphertext` is a forbidden material field.
+     */
+    readonly file: string;
+    /** Encryption tool. Closed union; `"sops"` is its only member today. */
+    readonly encryption?: SecretEncryption;
+    /** Public recipient identifiers — age recipients or PGP fingerprints. */
+    readonly recipients?: readonly string[];
+    /** The declared key-set of the decrypted Secret. Names only, never values. */
+    readonly keys?: readonly string[];
+}
+export type SecretDeclarationInput = ReferencedSecretInput | FromProviderSecretInput | GeneratedOnceSecretInput | CommittedEncryptedSecretInput;
+/**
+ * Declare a secret's provenance. The returned object is a locked Declarable:
+ * discovery collects it like any entity, `chant list` shows it, lint and
+ * lexicons read it — and no serializer ever emits it.
+ *
+ * Only the fields the kind defines are copied onto the declaration; anything
+ * else on the input — in particular anything that could carry material — is
+ * either a compile error ({@link NoSecretMaterial}) or a thrown error here.
+ * The thrown message names the offending KEY only, never its value.
+ */
+export declare function declareSecret(input: ReferencedSecretInput): ReferencedSecretDeclaration;
+export declare function declareSecret(input: FromProviderSecretInput): FromProviderSecretDeclaration;
+export declare function declareSecret(input: GeneratedOnceSecretInput): GeneratedOnceSecretDeclaration;
+export declare function declareSecret(input: CommittedEncryptedSecretInput): CommittedEncryptedSecretDeclaration;
+/** Type guard for a secret provenance declaration. */
+export declare function isSecretDeclaration(value: unknown): value is SecretDeclaration;
+/**
+ * Extract the secret declarations from a discovered entity map — the read
+ * surface for lint rules (#1382) and lexicon materializers (#1830). Keyed by
+ * entity name (export name), the same key `DiscoveryResult.entities` uses.
+ */
+export declare function collectSecretDeclarations(entities: ReadonlyMap<string, Declarable>): Map<string, SecretDeclaration>;
+export {};
+//# sourceMappingURL=secret-provenance.d.ts.map

package/dist/secret-provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-provenance.d.ts","sourceRoot":"","sources":["../src/secret-provenance.ts"],"names":[],"mappings":"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"}

package/dist/serializer.d.ts

@@ -18,6 +18,17 @@ export interface SerializeContext {
      * ad-hoc builds (e.g. context tools) that pass no config.
      */
     config?: Record<string, unknown>;
+    /**
+     * Effect receipts (#1832, epic #1703) declared in this lexicon's partition.
+     * Withheld from the `entities` map by the build: receipts are observe-only
+     * to the generic apply path, and the serialized output is what feeds
+     * appliers, so a receipt must never enter the apply-bound document. A
+     * serializer that wants to render receipts for visibility (#1835) reads
+     * them here and puts them anywhere BUT the section an applier writes from;
+     * a serializer that ignores this field emits nothing for them, which is the
+     * safe default.
+     */
+    receipts?: ReadonlyMap<string, Declarable>;
 }
 /**
  * Result of serialization that may include additional files (e.g. nested stack templates).

package/dist/serializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAE5B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;;;;;;;;;;OAaG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEtC;;;;;OAKG;IACH,SAAS,CACP,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EACjC,OAAO,CAAC,EAAE,aAAa,EAAE,EACzB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,gBAAgB,CAAC;IAE7B;;;;;OAKG;IACH,iBAAiB,CAAC,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC;CACpD"}
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAE5B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEjC;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;;;;;;;;;;OAaG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEtC;;;;;OAKG;IACH,SAAS,CACP,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EACjC,OAAO,CAAC,EAAE,aAAa,EAAE,EACzB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,gBAAgB,CAAC;IAE7B;;;;;OAKG;IACH,iBAAiB,CAAC,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC;CACpD"}

package/dist/yaml.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"yaml.d.ts","sourceRoot":"","sources":["../src/yaml.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA0BH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAgH/D;AAMD,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASlE;AAiFD;;GAEG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EAAE,EACf,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,WAAW,CA8Eb;AA0GD;;GAEG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EAAE,EACf,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,WAAW,CAqGb;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAelD"}
+{"version":3,"file":"yaml.d.ts","sourceRoot":"","sources":["../src/yaml.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA0BH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAgH/D;AAMD,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASlE;AAiFD;;GAEG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EAAE,EACf,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,WAAW,CA8Eb;AA0GD;;GAEG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EAAE,EACf,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,WAAW,CAqGb;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAwBlD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.46.0",
+  "version": "0.49.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -91,5 +91,8 @@
   "devDependencies": {
     "@cdktf/hcl2json": "^0.21.0",
     "ajv": "^8.20.0"
+  },
+  "overrides": {
+    "esbuild": "^0.28.1"
   }
 }

package/src/audit/core.test.ts

@@ -187,4 +187,61 @@ describe("auditFiles", () => {
     });
     expect(findings.map((f) => f.checkId)).toEqual(["OK001"]);
   });
+
+  test("parse-to-graph: an injected entities parser lets entity-reading checks fire per file (#1567)", async () => {
+    const entityCheck: PostSynthCheck = {
+      id: "ENT001",
+      description: "reads ctx.entities, not ctx.outputs",
+      check: (ctx) =>
+        [...ctx.entities.keys()].map((name) => ({ checkId: "ENT001", severity: "warning" as const, message: `saw ${name}`, entity: name })),
+    };
+    const findings = await auditFiles(
+      [
+        { path: "a.yaml", content: "one", lexicon: "custom" },
+        { path: "b.yaml", content: "two", lexicon: "custom" },
+      ],
+      {
+        checksProvider: async () => [entityCheck],
+        entitiesProvider: async () => (content) => new Map([[content, { entityType: "T::X" } as never]]),
+      },
+    );
+    expect(findings.map((f) => `${f.file}:${f.entity}`).sort()).toEqual(["a.yaml:one", "b.yaml:two"]);
+  });
+
+  test("parse-to-graph merge: the same entity name in two files keeps both — a duplicate check sees the collision cross-file", async () => {
+    const dupCheck: PostSynthCheck = {
+      id: "DUP001",
+      description: "fires when more than one entity is present",
+      check: (ctx) => (ctx.entities.size > 1 ? [{ checkId: "DUP001", severity: "error" as const, message: "name declared twice" }] : []),
+    };
+    const findings = await auditFiles(
+      [
+        { path: "a.yaml", content: "x", lexicon: "custom" },
+        { path: "b.yaml", content: "y", lexicon: "custom" },
+      ],
+      {
+        checksProvider: async () => [dupCheck],
+        // both files declare the entity name "dev" — the merged pass must keep both
+        entitiesProvider: async () => () => new Map([["dev", { entityType: "T::X" } as never]]),
+      },
+    );
+    const dup = findings.find((f) => f.checkId === "DUP001");
+    expect(dup).toBeDefined();
+    expect(dup!.file).toBe(CROSS_FILE);
+  });
+
+  test("an entities parser that throws contributes no entities and does not abort the audit", async () => {
+    const entityCheck: PostSynthCheck = {
+      id: "ENT002",
+      description: "counts entities",
+      check: (ctx) => (ctx.entities.size > 0 ? [{ checkId: "ENT002", severity: "warning" as const, message: "saw entities" }] : []),
+    };
+    const findings = await auditFiles([{ path: "a.yaml", content: "x", lexicon: "custom" }], {
+      checksProvider: async () => [entityCheck],
+      entitiesProvider: async () => () => {
+        throw new Error("unparseable");
+      },
+    });
+    expect(findings).toEqual([]);
+  });
 });

package/src/audit/detect-bundle.test.ts

@@ -9,7 +9,7 @@ import { fileURLToPath } from "url";
  * service content-detect all lexicons on Workers.
  */
 const repoRoot = fileURLToPath(new URL("../../../../", import.meta.url));
-const LEXICONS = ["k8s", "docker", "aws", "azure", "gcp", "helm"];
+const LEXICONS = ["k8s", "docker", "aws", "azure", "gcp", "helm", "fountain"];
 
 describe("detectTemplate modules are edge-bundle clean", () => {
   test("importing every lexicon's /detect pulls in no typescript or plugin.ts", async () => {

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