@intentius/chant-lexicon-fountain 0.33.0

package/src/import/parser.ts

@@ -0,0 +1,83 @@
+/**
+ * Fountain template parser.
+ *
+ * Turns fountain manifests (the `fountain apply -f` YAML, single or
+ * multi-document) or the serializer's fountain-plan.json into the import IR
+ * for conversion to chant TypeScript. Server-written read-only fields are
+ * dropped so the IR is the declared shape. `logicalId` is `metadata.name`
+ * (manifests) or the plan's entity name.
+ */
+
+import type { TemplateParser, TemplateIR, ResourceIR } from "@intentius/chant/import/parser";
+import { BaseValueParser } from "@intentius/chant/import/base-parser";
+import { parseYAML } from "@intentius/chant/yaml";
+import { isFountainPlan } from "../detect";
+
+/** Server-written read-only fields — never part of the authored shape. */
+export const SERVER_FIELDS = ["id", "inserted_at", "updated_at", "user_id", "conversation_count", "avatar_media_type"];
+
+const KIND_TO_TYPE: Record<string, string> = {
+  Environment: "Fountain::V1::Environment",
+  Vault: "Fountain::V1::Vault",
+  Agent: "Fountain::V1::Agent",
+};
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+export class FountainParser extends BaseValueParser implements TemplateParser {
+  protected dispatchIntrinsic(): unknown | null {
+    // fountain manifests have no intrinsic functions; `${VAR}` substitution
+    // is fountain's own runtime concern and passes through as a string.
+    return null;
+  }
+
+  parse(input: string): TemplateIR {
+    const trimmed = input.trim();
+    if (!trimmed) return { resources: [], parameters: [] };
+
+    // fountain-plan.json
+    if (trimmed.startsWith("{")) {
+      try {
+        const data = JSON.parse(trimmed) as unknown;
+        if (isFountainPlan(data)) {
+          const resources: ResourceIR[] = [];
+          for (const [entityName, entry] of Object.entries(data as Record<string, { kind: string; spec: Record<string, unknown> }>)) {
+            const type = KIND_TO_TYPE[entry.kind];
+            if (!type) continue;
+            resources.push(this.resource(type, entityName, entry.spec));
+          }
+          return { resources, parameters: [] };
+        }
+      } catch {
+        // fall through to YAML
+      }
+    }
+
+    // Manifest YAML (single or multi-document).
+    const resources: ResourceIR[] = [];
+    for (const docText of trimmed.split(/^---\s*$/m)) {
+      if (!docText.trim()) continue;
+      const doc = parseYAML(docText);
+      const kind = typeof doc.kind === "string" ? doc.kind : "";
+      const type = KIND_TO_TYPE[kind];
+      if (!type) continue;
+      const meta = isRecord(doc.metadata) ? doc.metadata : {};
+      const name = typeof meta.name === "string" ? meta.name : kind.toLowerCase();
+      const spec = isRecord(doc.spec) ? doc.spec : {};
+      resources.push(this.resource(type, name, spec));
+    }
+    return { resources, parameters: [] };
+  }
+
+  private resource(type: string, logicalId: string, spec: Record<string, unknown>): ResourceIR {
+    const properties: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(spec)) {
+      if (SERVER_FIELDS.includes(key)) continue;
+      if (value === undefined) continue;
+      properties[key] = this.parseValue(value);
+    }
+    return { logicalId, type, properties };
+  }
+}

package/src/import/roundtrip.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from "vitest";
+import { FountainParser } from "./parser";
+import { FountainGenerator } from "./generator";
+import { detectFountainTemplate } from "../detect";
+import { exportResources } from "../export-resources";
+import type { FountainHttp } from "../op/activities/fountain-apply";
+
+const MANIFESTS = `apiVersion: fountain.dev/v1
+kind: Environment
+metadata:
+  name: concierge-env
+spec:
+  name: concierge-env
+  networking_type: limited
+  networking_config:
+    allowed_hosts:
+      - github.com
+  repositories:
+    - url: https://github.com/org/repo
+      mount_path: /app
+---
+apiVersion: fountain.dev/v1
+kind: Agent
+metadata:
+  name: researcher
+spec:
+  name: researcher
+  model: anthropic/claude-sonnet-4-6
+  runtime: claude
+  environment: concierge-env
+`;
+
+describe("detect", () => {
+  it("detects manifest YAML and plan JSON, rejects noise", () => {
+    expect(detectFountainTemplate(MANIFESTS)).toBe(true);
+    expect(detectFountainTemplate('{"e":{"kind":"Environment","spec":{}}}')).toBe(true);
+    expect(detectFountainTemplate("apiVersion: v1\nkind: Pod")).toBe(false);
+    expect(detectFountainTemplate("{}")).toBe(false);
+  });
+});
+
+describe("parser", () => {
+  it("parses multi-document manifests into IR", () => {
+    const ir = new FountainParser().parse(MANIFESTS);
+    expect(ir.resources.map((r) => r.type)).toEqual([
+      "Fountain::V1::Environment",
+      "Fountain::V1::Agent",
+    ]);
+    expect(ir.resources[0].logicalId).toBe("concierge-env");
+    expect(ir.resources[0].properties.networking_type).toBe("limited");
+  });
+
+  it("parses the fountain-plan.json sidecar", () => {
+    const ir = new FountainParser().parse(
+      JSON.stringify({ v: { kind: "Vault", spec: { name: "staging", id: "drop-me" } } }),
+    );
+    expect(ir.resources).toHaveLength(1);
+    expect(ir.resources[0].properties.name).toBe("staging");
+    expect(ir.resources[0].properties.id).toBeUndefined();
+  });
+});
+
+describe("generator", () => {
+  it("emits typed constructors with Repository wrapping", () => {
+    const ir = new FountainParser().parse(MANIFESTS);
+    const [file] = new FountainGenerator().generate(ir);
+    expect(file.content).toContain('from "@intentius/chant-lexicon-fountain"');
+    expect(file.content).toContain("export const conciergeEnv = new Environment({");
+    expect(file.content).toContain("new Repository({");
+    expect(file.content).toContain("export const researcher = new Agent({");
+  });
+});
+
+describe("exportResources", () => {
+  it("strips server fields, resolves env refs, and warns on secrets", async () => {
+    const warnings: string[] = [];
+    const http: FountainHttp = async (_m, path) => {
+      if (path === "/api/environments")
+        return {
+          status: 200,
+          json: { data: [{ id: "env-1", name: "e", inserted_at: "x", metadata: { "managed-by": "chant" } }] },
+        };
+      if (path === "/api/environments/env-1/secrets")
+        return { status: 200, json: { data: [{ key: "K" }] } };
+      if (path === "/api/vaults") return { status: 200, json: { data: [] } };
+      if (path === "/api/agents")
+        return {
+          status: 200,
+          json: { data: [{ id: "a-1", name: "r", environment_id: "env-1", model: "a/m", runtime: "claude" }] },
+        };
+      throw new Error(`unrouted ${path}`);
+    };
+
+    const ir = await exportResources({ environment: "local", http, warn: (m) => warnings.push(m) });
+    const agent = ir.resources.find((r) => r.type === "Fountain::V1::Agent")!;
+    expect(agent.properties.environment).toBe("e");
+    expect(agent.properties.environment_id).toBeUndefined();
+    expect(agent.properties.id).toBeUndefined();
+    expect(warnings.some((w) => w.includes("1 secret"))).toBe(true);
+  });
+
+  it("owned filter drops unmarked resources", async () => {
+    const http: FountainHttp = async (_m, path) => {
+      if (path === "/api/environments") return { status: 200, json: { data: [] } };
+      if (path === "/api/vaults") return { status: 200, json: { data: [] } };
+      if (path === "/api/agents")
+        return { status: 200, json: { data: [{ id: "a-1", name: "r", metadata: {} }] } };
+      throw new Error(`unrouted ${path}`);
+    };
+    const ir = await exportResources({ environment: "local", owned: true, http });
+    expect(ir.resources).toHaveLength(0);
+  });
+});

package/src/index.ts

@@ -0,0 +1,17 @@
+// Plugin
+export { fountainPlugin } from "./plugin";
+
+// Serializer
+export { fountainSerializer } from "./serializer";
+
+// Generated resources — Environment, Vault, Agent, and property types.
+export * from "./generated/index";
+
+// Op activities — the native applier and conversation runner. Also
+// resolvable by name via loadActivities(["fountain"]).
+export { fountainApply, fountainRun, DEFAULT_FOUNTAIN_BASE_URL } from "./op/activities";
+export type { FountainApplyArgs, FountainApplySummary, FountainRunArgs, FountainRunResult } from "./op/activities";
+
+// Composites — secure-by-construction bundles.
+export { ConciergeStack } from "./composites/concierge-stack";
+export type { ConciergeStackOpts, ConciergeStackResources } from "./composites/concierge-stack";

package/src/init-templates.ts

@@ -0,0 +1,60 @@
+/**
+ * `chant init` scaffolding for fountain projects.
+ *
+ * Two templates. The default is the concierge posture — a locked sandbox
+ * declared through `ConciergeStack`, since an agent environment that reaches
+ * anything real should start closed and be opened by explicit parameter. The
+ * `open` template is the loose counterpart for a research sandbox that touches
+ * nothing sensitive, and says so in a comment rather than leaving a reader to
+ * infer that the difference was deliberate.
+ */
+
+import type { InitTemplateSet } from "@intentius/chant/lexicon";
+
+const CONCIERGE = `import { ConciergeStack } from "@intentius/chant-lexicon-fountain";
+
+// A locked-down Environment + Agent pair. The defaults are the closed ones:
+// deny-all egress (limited networking with an empty allowlist), no vault may
+// override the reviewed environment at spawn, and the managed-by: chant marker
+// on both so owned-only reconcile and drift see them.
+//
+// Loosening any of it is an explicit, reviewable parameter — add hosts to
+// allowedHosts, ids to allowedVaultIds. Give the sandbox no cloud credentials:
+// anything readable inside it is exfiltratable by prompt injection. Services
+// the agent needs live outside the sandbox behind their own auth.
+export const { environment, agent } = ConciergeStack({
+  name: "concierge",
+  model: "anthropic/claude-sonnet-4-6",
+  allowedHosts: ["registry.npmjs.org", "github.com"],
+});
+`;
+
+const OPEN = `import { Environment, Agent } from "@intentius/chant-lexicon-fountain";
+
+// A research sandbox that touches nothing sensitive. networking_type is set
+// explicitly because FTN010 requires the choice to be a reviewed one, not a
+// default nobody looked at; FTN011 will still warn on unrestricted, which is
+// the intended nudge — switch to limited with an allowed_hosts allowlist as
+// soon as this environment holds anything worth stealing.
+export const env = new Environment({
+  name: "research-env",
+  networking_type: "unrestricted",
+  packages: { node: "24" },
+  metadata: { "managed-by": "chant" },
+});
+
+export const researcher = new Agent({
+  name: "researcher",
+  model: "anthropic/claude-sonnet-4-6",
+  runtime: "claude",
+  environment: env,
+  metadata: { "managed-by": "chant" },
+});
+`;
+
+export function fountainInitTemplates(template?: string): InitTemplateSet {
+  if (template === "open") {
+    return { src: { "fountain.ts": OPEN } };
+  }
+  return { src: { "fountain.ts": CONCIERGE } };
+}

package/src/lint/audit-catalog.ts

@@ -0,0 +1,107 @@
+/**
+ * The fountain lexicon's chant audit catalog — metadata for the FTN rules,
+ * contributed via `fountainPlugin.auditCatalog()` (#687).
+ *
+ * Every entry carries `yamlBased: false`, which is not an oversight: all of
+ * fountain's checks read the chant model (`ctx.entities`), not the emitted
+ * manifests (`ctx.outputs`), because the facts they need — which Environment
+ * an Agent references, which keys a Vault shadows — live in the typed graph
+ * and are flattened by the time YAML exists. So they fire on `chant build`
+ * and cannot fire on an audit of standalone fountain YAML. `auditRule()`
+ * hardcodes `yamlBased: true`, so these are constructed directly.
+ */
+
+import type { Authority, RuleMeta } from "@intentius/chant/audit/catalog";
+
+const FOUNTAIN_PRIMITIVES: Authority = {
+  name: "fountain — Environment, Vault, and Agent primitives",
+  url: "https://github.com/BinaryBourbon/fountain/blob/main/docs/primitives.md",
+};
+
+const OWASP_LLM_INJECTION: Authority = {
+  name: "OWASP Top 10 for LLM Applications — LLM01: Prompt Injection",
+  url: "https://owasp.org/www-project-top-10-for-large-language-model-applications/",
+};
+
+/** Entity-based rule: everything fountain ships. */
+function rule(
+  id: string,
+  tier: RuleMeta["tier"],
+  category: RuleMeta["category"],
+  title: string,
+  remediation: string,
+  authority?: Authority[],
+): RuleMeta {
+  return { id, tier, fixKind: "guidance", category, title, remediation, authority, yamlBased: false };
+}
+
+export const fountainAuditCatalog: Record<string, RuleMeta> = {
+  FTN001: rule(
+    "FTN001",
+    "merge-worthy",
+    "security",
+    "Literal credential in a fountain declaration",
+    "Use a ${VAR} substitution reference or an environment secret; never a literal in source.",
+    [OWASP_LLM_INJECTION],
+  ),
+  FTN010: rule(
+    "FTN010",
+    "merge-worthy",
+    "security",
+    "Environment does not set networking_type explicitly",
+    "Set networking_type — an open sandbox by silence is not a reviewed decision.",
+    [FOUNTAIN_PRIMITIVES],
+  ),
+  FTN011: rule(
+    "FTN011",
+    "merge-worthy",
+    "security",
+    "Environment uses networking_type: unrestricted",
+    "Prefer limited with an allowed_hosts allowlist; an empty list denies all egress.",
+    [FOUNTAIN_PRIMITIVES],
+  ),
+  FTN012: rule(
+    "FTN012",
+    "merge-worthy",
+    "security",
+    "Cloud-credential-shaped key or value in Environment env_vars",
+    "env_vars is plaintext config — move credentials to a secret, or serve the capability outside the sandbox.",
+    [OWASP_LLM_INJECTION],
+  ),
+  FTN013: rule(
+    "FTN013",
+    "report-only",
+    "correctness",
+    "Agent ${VAR} reference does not resolve against its environment",
+    "Declare the key on the environment, or confirm a vault supplies it at conversation create.",
+  ),
+  FTN014: rule(
+    "FTN014",
+    "report-only",
+    "correctness",
+    "Vault key shadows a declared Environment key",
+    "Vault values win on key collision silently — rename the key or confirm the override is intended.",
+  ),
+  FTN015: rule(
+    "FTN015",
+    "merge-worthy",
+    "security",
+    "Secret-shaped MCP env key is a literal, not a ${VAR} reference",
+    "Reference the value with ${VAR} so it resolves at spawn instead of living in source.",
+    [OWASP_LLM_INJECTION],
+  ),
+  FTN016: rule(
+    "FTN016",
+    "merge-worthy",
+    "correctness",
+    "Agent runtime or model is not a valid value",
+    "Use a known runtime and a canonical provider/model_id.",
+  ),
+  FTN017: rule(
+    "FTN017",
+    "merge-worthy",
+    "correctness",
+    "Two declarations of one kind resolve to the same fountain name",
+    "fountain reconciles by name — rename one, or the second silently overwrites the first.",
+  ),
+};

package/src/lint/post-synth/ftn010-networking-explicit.ts

@@ -0,0 +1,37 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { propsOf } from "../../entity-props";
+
+/**
+ * FTN010: Environments must state their networking intent.
+ *
+ * Fountain defaults `networking_type` to `unrestricted` when omitted —
+ * an open-network sandbox by silence. Every declared Environment must set
+ * `networking_type` explicitly so the security posture is a reviewed,
+ * diffable decision.
+ */
+export const networkingExplicitCheck: PostSynthCheck = {
+  id: "FTN010",
+  description: "Environment declarations must set networking_type explicitly",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of ctx.entities) {
+      if (entity.entityType !== "Fountain::V1::Environment") continue;
+      const props = propsOf(entity);
+      if (props.networking_type === undefined) {
+        diagnostics.push({
+          checkId: "FTN010",
+          severity: "warning",
+          message:
+            `Environment "${name}" does not set networking_type — fountain defaults to ` +
+            `"unrestricted" (open network). State the intent explicitly.`,
+          entity: name,
+          lexicon: "fountain",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/ftn011-no-unrestricted-networking.ts

@@ -0,0 +1,36 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { propsOf } from "../../entity-props";
+
+/**
+ * FTN011: `unrestricted` networking is a warning by default.
+ *
+ * Fountain sandboxes run untrusted agent code; an open-network sandbox is
+ * a real posture some workloads need, but it should read as a deliberate
+ * exception in review. Projects hosting untrusted-agent environments
+ * (concierge-class) should promote this to error via project rules.
+ */
+export const noUnrestrictedNetworkingCheck: PostSynthCheck = {
+  id: "FTN011",
+  description: "Environments should prefer networking_type: limited over unrestricted",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const [name, entity] of ctx.entities) {
+      if (entity.entityType !== "Fountain::V1::Environment") continue;
+      const props = propsOf(entity);
+      if (props.networking_type === "unrestricted") {
+        diagnostics.push({
+          checkId: "FTN011",
+          severity: "warning",
+          message:
+            `Environment "${name}" uses networking_type: unrestricted — an open-network ` +
+            `sandbox. Prefer "limited" with allowed_hosts; keep unrestricted only as a ` +
+            `reviewed exception.`,
+          entity: name,
+          lexicon: "fountain",
+        });
+      }
+    }
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/ftn012-no-cloud-credential-env.ts

@@ -0,0 +1,58 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { propsOf } from "../../entity-props";
+
+/**
+ * FTN012: no cloud-credential-shaped values in Environment env_vars.
+ *
+ * Everything materialized into a sandbox must be presumed exfiltrated the
+ * moment untrusted agent code starts. `env_vars` is plaintext config —
+ * anything credential-shaped belongs in secrets at minimum, and long-lived
+ * cloud credentials should not enter the sandbox at all (see
+ * BinaryBourbon/fountain#148 for the token-only model).
+ */
+
+const CREDENTIAL_KEYS = /^(AWS_SECRET_ACCESS_KEY|AWS_ACCESS_KEY_ID|AWS_SESSION_TOKEN|GOOGLE_APPLICATION_CREDENTIALS|AZURE_CLIENT_SECRET)$/i;
+const CREDENTIAL_VALUES = /^(AKIA[0-9A-Z]{16}|(ghp|gho|ghs|ghu)_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|sk-[A-Za-z0-9_-]{20,}|xox[baprs]-[A-Za-z0-9-]{10,})$/;
+
+export const noCloudCredentialEnvCheck: PostSynthCheck = {
+  id: "FTN012",
+  description: "Environment env_vars must not carry cloud-credential-shaped keys or values",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of ctx.entities) {
+      if (entity.entityType !== "Fountain::V1::Environment") continue;
+      const envVars = propsOf(entity).env_vars as Record<string, unknown> | undefined;
+      if (!envVars || typeof envVars !== "object") continue;
+
+      for (const [key, value] of Object.entries(envVars)) {
+        if (CREDENTIAL_KEYS.test(key)) {
+          diagnostics.push({
+            checkId: "FTN012",
+            severity: "error",
+            message:
+              `Environment "${name}" env_vars carries cloud-credential key "${key}" — ` +
+              `credentials must not be materialized into the sandbox`,
+            entity: name,
+            lexicon: "fountain",
+          });
+          continue;
+        }
+        if (typeof value === "string" && CREDENTIAL_VALUES.test(value)) {
+          diagnostics.push({
+            checkId: "FTN012",
+            severity: "error",
+            message:
+              `Environment "${name}" env_vars["${key}"] looks like a literal credential — ` +
+              `use secrets or a \${VAR} reference, never a plaintext value`,
+            entity: name,
+            lexicon: "fountain",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/ftn013-substitution-resolvable.ts

@@ -0,0 +1,93 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { propsOf } from "../../entity-props";
+
+/**
+ * FTN013: `${VAR}` references in an Agent's config should resolve against
+ * its Environment's declared keys.
+ *
+ * Fountain validates substitution fail-complete at *spawn* time; this
+ * moves the same check to build time. Warning severity: a vault attached
+ * at conversation create can legitimately supply keys the environment
+ * does not declare (vault values win on collision), so an unresolved
+ * reference is suspicious, not certainly wrong.
+ */
+
+const VAR_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+function collectVars(node: unknown, acc: Set<string>): void {
+  if (typeof node === "string") {
+    for (const m of node.matchAll(VAR_RE)) acc.add(m[1]);
+    return;
+  }
+  if (Array.isArray(node)) {
+    for (const item of node) collectVars(item, acc);
+    return;
+  }
+  if (node && typeof node === "object") {
+    for (const v of Object.values(node)) collectVars(v, acc);
+  }
+}
+
+function declaredKeys(env: Record<string, unknown>): Set<string> {
+  const keys = new Set<string>();
+  const envVars = env.env_vars;
+  if (envVars && typeof envVars === "object") {
+    for (const k of Object.keys(envVars)) keys.add(k);
+  }
+  const secrets = env.secrets;
+  if (Array.isArray(secrets)) {
+    for (const s of secrets) {
+      const key = (s as { key?: unknown })?.key;
+      if (typeof key === "string") keys.add(key);
+    }
+  }
+  return keys;
+}
+
+export const substitutionResolvableCheck: PostSynthCheck = {
+  id: "FTN013",
+  description: "Agent ${VAR} references should resolve against the environment's declared keys",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of ctx.entities) {
+      if (entity.entityType !== "Fountain::V1::Agent") continue;
+      const agent = propsOf(entity);
+
+      // Resolve the referenced environment entity when it is declared here.
+      const envRef = agent.environment;
+      let envEntity: Record<string, unknown> | undefined;
+      if (envRef && typeof envRef === "object") {
+        envEntity = propsOf(envRef);
+      } else if (typeof envRef === "string") {
+        const byName = ctx.entities.get(envRef);
+        if (byName?.entityType === "Fountain::V1::Environment") {
+          envEntity = propsOf(byName);
+        }
+      }
+      if (!envEntity) continue; // external environment — nothing to check against
+
+      const keys = declaredKeys(envEntity);
+      const used = new Set<string>();
+      collectVars(agent.mcp_servers, used);
+      collectVars(agent.system, used);
+
+      for (const v of used) {
+        if (!keys.has(v)) {
+          diagnostics.push({
+            checkId: "FTN013",
+            severity: "warning",
+            message:
+              `Agent "${name}" references \${${v}} but its environment declares no such ` +
+              `key — it will only resolve if a vault supplies it at conversation create`,
+            entity: name,
+            lexicon: "fountain",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/ftn014-vault-shadowing.ts

@@ -0,0 +1,61 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { propsOf } from "../../entity-props";
+
+/**
+ * FTN014: a Vault key that collides with a declared Environment key.
+ *
+ * Vault values win on key collision at spawn — silently. Shadowing a
+ * reviewed environment value is sometimes exactly the point (staging
+ * overrides) and sometimes an accident; either way it should be visible
+ * in review, so collisions warn.
+ */
+
+function keysOf(spec: Record<string, unknown>): Set<string> {
+  const keys = new Set<string>();
+  const envVars = spec.env_vars;
+  if (envVars && typeof envVars === "object") for (const k of Object.keys(envVars)) keys.add(k);
+  const secrets = spec.secrets;
+  if (Array.isArray(secrets)) {
+    for (const s of secrets) {
+      const key = (s as { key?: unknown })?.key;
+      if (typeof key === "string") keys.add(key);
+    }
+  }
+  return keys;
+}
+
+export const vaultShadowingCheck: PostSynthCheck = {
+  id: "FTN014",
+  description: "Vault keys shadowing a declared Environment key should be visible in review",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const environments: Array<[string, Set<string>]> = [];
+    const vaults: Array<[string, Set<string>]> = [];
+
+    for (const [name, entity] of ctx.entities) {
+      const spec = propsOf(entity);
+      if (entity.entityType === "Fountain::V1::Environment") environments.push([name, keysOf(spec)]);
+      if (entity.entityType === "Fountain::V1::Vault") vaults.push([name, keysOf(spec)]);
+    }
+
+    for (const [vaultName, vaultKeys] of vaults) {
+      for (const [envName, envKeys] of environments) {
+        const shadowed = [...vaultKeys].filter((k) => envKeys.has(k));
+        if (shadowed.length > 0) {
+          diagnostics.push({
+            checkId: "FTN014",
+            severity: "warning",
+            message:
+              `Vault "${vaultName}" shadows ${shadowed.map((k) => `"${k}"`).join(", ")} from ` +
+              `environment "${envName}" — vault values win silently on collision at spawn`,
+            entity: vaultName,
+            lexicon: "fountain",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};