@intentius/chant 0.46.0 → 0.49.0

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

@@ -705,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

package/src/cli/commands/build.ts

@@ -7,7 +7,9 @@ import {
   isOwnershipParamRef,
   resolveFoldEnabled,
   resolveSandboxEnabled,
+  resolveKnowledgeDir,
 } from "../../config";
+import { loadOkfBundle } from "../../okf-read";
 import { unknownEnvError } from "../../env";
 import type { OwnershipMarker } from "../../ownership";
 import { resolveCliBuildParams } from "../build-params-cli";
@@ -15,6 +17,10 @@ import type { Serializer, SerializerResult } from "../../serializer";
 import type { LexiconPlugin } from "../../lexicon";
 import { resolveLexiconVersions, collectBuildRootContributors } from "../plugins";
 import { runPostSynthChecks } from "../../lint/post-synth";
+import { collectSecretDeclarations } from "../../secret-provenance";
+import { coreReceiptChecks } from "../../lint/receipt-checks";
+import { coreOutputChecks } from "../../lint/output-checks";
+import { coreKnowledgeChecks } from "../../lint/knowledge-checks";
 import { applyConfiguredSeverity } from "../../lint/config";
 import { loadPolicyChecks } from "../../lint/policy";
 import { armSandboxPolicyExecution, runProjectPolicies } from "../../lint/policy-sandbox";
@@ -382,6 +388,66 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
   // finding just as it suppresses a pre-synth one. A finding it suppresses is
   // counted, not dropped silently — see `suppressedPostSynthCount` below.
   let suppressedPostSynthCount = 0;
+
+  // Core-owned post-synth checks over effect receipts (#1833). Receipts are
+  // recognized by marker, lexicon-independently, so this set runs over the
+  // FULL build result — unscoped, and regardless of which plugins loaded.
+  // Same severity-resolution funnel as every other post-synth finding.
+  if (result.errors.length === 0) {
+    const receiptDiags = runPostSynthChecks(coreReceiptChecks(), result, env);
+    const { diagnostics: activeDiags, suppressed } = applyConfiguredSeverity(receiptDiags, config.lint?.rules);
+    suppressedPostSynthCount += suppressed.length;
+    for (const diag of activeDiags) {
+      const prefix = diag.entity ? `[${diag.entity}] ` : "";
+      const lexiconSuffix = diag.lexicon ? ` (${diag.lexicon})` : "";
+      if (diag.severity === "error") {
+        errors.push(formatError({ message: `${prefix}${diag.message}${lexiconSuffix}` }));
+      } else {
+        warnings.push(formatWarning({ message: `${prefix}${diag.message}${lexiconSuffix}` }));
+      }
+    }
+  }
+
+  // Core-owned post-synth check over serialized output text (#1526). The
+  // "[object Object]" marker means a reference got stringified instead of
+  // resolved; it can appear in any lexicon's emitted text, so this runs over
+  // the FULL build result the same way the receipt checks above do.
+  if (result.errors.length === 0) {
+    const outputDiags = runPostSynthChecks(coreOutputChecks(), result, env);
+    const { diagnostics: activeDiags, suppressed } = applyConfiguredSeverity(outputDiags, config.lint?.rules);
+    suppressedPostSynthCount += suppressed.length;
+    for (const diag of activeDiags) {
+      const prefix = diag.entity ? `[${diag.entity}] ` : "";
+      const lexiconSuffix = diag.lexicon ? ` (${diag.lexicon})` : "";
+      if (diag.severity === "error") {
+        errors.push(formatError({ message: `${prefix}${diag.message}${lexiconSuffix}` }));
+      } else {
+        warnings.push(formatWarning({ message: `${prefix}${diag.message}${lexiconSuffix}` }));
+      }
+    }
+  }
+
+  // Core-owned post-synth check over the project's OKF knowledge bundle
+  // (#1865, design #1059): a concept's `binds` naming no discovered entity is
+  // a stale binding, surfaced as a COR026 warning. `resolveKnowledgeDir` +
+  // `loadOkfBundle` never fail — a missing/absent `knowledge/` directory
+  // loads an empty bundle, so this is a no-op for a project that has none.
+  if (result.errors.length === 0) {
+    const bundle = await loadOkfBundle(resolveKnowledgeDir(config, configDir));
+    const knowledgeDiags = runPostSynthChecks(coreKnowledgeChecks(bundle), result, env);
+    const { diagnostics: activeDiags, suppressed } = applyConfiguredSeverity(knowledgeDiags, config.lint?.rules);
+    suppressedPostSynthCount += suppressed.length;
+    for (const diag of activeDiags) {
+      const prefix = diag.entity ? `[${diag.entity}] ` : "";
+      const lexiconSuffix = diag.lexicon ? ` (${diag.lexicon})` : "";
+      if (diag.severity === "error") {
+        errors.push(formatError({ message: `${prefix}${diag.message}${lexiconSuffix}` }));
+      } else {
+        warnings.push(formatWarning({ message: `${prefix}${diag.message}${lexiconSuffix}` }));
+      }
+    }
+  }
+
   if (result.errors.length === 0 && options.plugins) {
     for (const plugin of options.plugins) {
       if (!plugin.postSynthChecks) continue;
@@ -482,6 +548,20 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
     // Extract primary content and collect additional files from SerializerResult
     const additionalFiles = new Map<string, string>();
 
+    // Sidecar files that must reach disk BYTE-FOR-BYTE: committed ciphertext
+    // (`declareSecret({ provenance: "committed-encrypted", file })`). The
+    // additional-file writer below round-trips anything JSON.parse accepts,
+    // key-sorting it and possibly re-emitting it as YAML — which would break
+    // the `sops` MAC. `file` is restricted to .yaml/.yml, so that parse fails
+    // in practice, but naming the files here makes byte identity structural
+    // rather than a lucky accident.
+    const verbatimFiles = new Set<string>();
+    for (const decl of collectSecretDeclarations(result.entities).values()) {
+      if (decl.provenance === "committed-encrypted") {
+        verbatimFiles.add(decl.file.split(/[\\/]/).pop()!);
+      }
+    }
+
     function getPrimaryContent(raw: string | SerializerResult): string {
       if (typeof raw === "string") return raw;
       if (raw.files) {
@@ -587,15 +667,18 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
           const outputDir = dirname(outputPath);
           for (const [filename, content] of additionalFiles) {
             let fileContent = content;
-            // Format additional files consistently
-            try {
-              const fileParsed = JSON.parse(content);
-              fileContent = JSON.stringify(fileParsed, sortedJsonReplacer, 2);
-              if (options.format === "yaml") {
-                fileContent = jsonToYaml(JSON.parse(fileContent));
+            // Format additional files consistently — except the ones declared
+            // verbatim, which are copied exactly as they were committed.
+            if (!verbatimFiles.has(filename)) {
+              try {
+                const fileParsed = JSON.parse(content);
+                fileContent = JSON.stringify(fileParsed, sortedJsonReplacer, 2);
+                if (options.format === "yaml") {
+                  fileContent = jsonToYaml(JSON.parse(fileContent));
+                }
+              } catch {
+                // If not JSON, write as-is
               }
-            } catch {
-              // If not JSON, write as-is
             }
             const targetPath = join(outputDir, filename);
             mkdirSync(dirname(targetPath), { recursive: true });
@@ -609,6 +692,21 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
           })
         );
       }
+    } else if (verbatimFiles.size > 0) {
+      // A build carrying committed ciphertext and no --output has nowhere to
+      // put the sidecar. Echoing it to a terminal is not useful and dropping
+      // it silently is worse: the primary output would reference a Secret
+      // whose file never got written, and the miss would surface as a pod
+      // failing to start, far from its cause. Refuse, naming the flag.
+      const names = [...verbatimFiles].sort().join(", ");
+      errors.push(
+        formatError({
+          message:
+            `This build emits committed-encrypted secret file(s) (${names}) as sidecars, ` +
+            `which need a directory to be written into. Re-run with --output <path> ` +
+            `(the sidecars land beside it).`,
+        }),
+      );
     } else {
       // Print to stdout
       console.log(output);

package/src/cli/commands/lint.ts

@@ -20,8 +20,9 @@ import { GENERATED_MARKER } from "../../discovery/files";
 
 // Import config loader
 import { loadConfig, resolveRulesForFile, resolveConfiguredSeverity, findProjectRoot } from "../../lint/config";
-import { loadChantConfig } from "../../config";
+import { loadChantConfig, resolveKnowledgeDir } from "../../config";
 import type { LintProjectConfig } from "../../lint/rule";
+import { loadOkfBundle, type OkfBundle } from "../../okf-read";
 
 /**
  * Type guard to check if a value conforms to the LintRule interface.
@@ -454,10 +455,21 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
   // runLint() call below via LintContext.projectConfig. Best-effort: a
   // directory with no project config lints with those rules silent.
   let projectConfig: LintProjectConfig | undefined;
+  // chant #1866 — the loaded OKF knowledge bundle, threaded into
+  // `formatStylish` below so its suppressed section can resolve `okf:`
+  // citations. Best-effort like `projectConfig` above (same
+  // `loadChantConfig` call): a directory with no chant config, or no
+  // `knowledge/` bundle, lints with citations rendering unresolved rather
+  // than a failure — `loadOkfBundle` already treats a missing directory as
+  // an empty bundle.
+  let knowledgeBundle: OkfBundle | undefined;
   try {
-    projectConfig = (await loadChantConfig(projectRoot)).config as LintProjectConfig;
+    const chantConfig = (await loadChantConfig(projectRoot)).config;
+    projectConfig = chantConfig as LintProjectConfig;
+    knowledgeBundle = await loadOkfBundle(resolveKnowledgeDir(chantConfig, projectRoot));
   } catch {
     projectConfig = undefined;
+    knowledgeBundle = undefined;
   }
 
   // Load all rules from lexicon plugins (core "chant" + lexicon-specific)
@@ -588,7 +600,7 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
       break;
     case "stylish":
     default:
-      output = formatStylish(diagnostics);
+      output = formatStylish(diagnostics, suppressed, knowledgeBundle);
       break;
   }
 

package/src/cli/handlers/explain.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
-import { mkdtemp, readFile, rm, stat } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { DECLARABLE_MARKER, type Declarable } from "../../declarable";
@@ -90,4 +90,73 @@ describe("runExplain", () => {
     const code = await runExplain(ctx({ format: "okf" }));
     expect(code).toBe(1);
   });
+
+  describe("knowledge sections (#1867)", () => {
+    let projectDir: string;
+
+    beforeEach(async () => {
+      projectDir = await mkdtemp(join(tmpdir(), "chant-explain-knowledge-"));
+    });
+
+    afterEach(async () => {
+      await rm(projectDir, { recursive: true, force: true });
+    });
+
+    test("omits the Knowledge section cleanly when no bundle exists", async () => {
+      const code = await runExplain(ctx({ path: projectDir }));
+      expect(code).toBe(0);
+      expect(logSpy.mock.calls[0][0]).not.toContain("## Knowledge");
+    });
+
+    test("json omits the knowledge field cleanly when no bundle exists", async () => {
+      const code = await runExplain(ctx({ path: projectDir, format: "json" }));
+      expect(code).toBe(0);
+      const parsed = JSON.parse(logSpy.mock.calls[0][0] as string);
+      expect(parsed.knowledge).toBeUndefined();
+    });
+
+    test("markdown includes a per-entity Knowledge section for bound concepts", async () => {
+      await mkdir(join(projectDir, "knowledge", "decisions"), { recursive: true });
+      await writeFile(
+        join(projectDir, "knowledge", "decisions", "public-vpc.md"),
+        "---\ntype: decision\ntitle: Public VPC\nbinds: vpc\n---\nWhy the VPC is public.\n",
+      );
+
+      const code = await runExplain(ctx({ path: projectDir }));
+      expect(code).toBe(0);
+      const out = logSpy.mock.calls[0][0] as string;
+      expect(out).toContain("## Knowledge");
+      expect(out).toContain("### `vpc`");
+      expect(out).toContain("decision: Public VPC (`decisions/public-vpc.md`)");
+      expect(out).not.toContain("### `subnet`");
+    });
+
+    test("json carries type/title/path per bound entity", async () => {
+      await mkdir(join(projectDir, "knowledge", "decisions"), { recursive: true });
+      await writeFile(
+        join(projectDir, "knowledge", "decisions", "public-vpc.md"),
+        "---\ntype: decision\ntitle: Public VPC\nbinds: vpc\n---\nWhy the VPC is public.\n",
+      );
+
+      const code = await runExplain(ctx({ path: projectDir, format: "json" }));
+      expect(code).toBe(0);
+      const parsed = JSON.parse(logSpy.mock.calls[0][0] as string);
+      expect(parsed.knowledge).toEqual({
+        vpc: [{ type: "decision", title: "Public VPC", path: "decisions/public-vpc.md" }],
+      });
+    });
+
+    test("--format okf output is untouched by a present bundle", async () => {
+      await mkdir(join(projectDir, "knowledge"), { recursive: true });
+      await writeFile(
+        join(projectDir, "knowledge", "note.md"),
+        "---\ntype: decision\ntitle: Note\nbinds: vpc\n---\nBody.\n",
+      );
+
+      const code = await runExplain(ctx({ path: projectDir, format: "okf" }));
+      expect(code).toBe(0);
+      const parsed = JSON.parse(logSpy.mock.calls[0][0] as string);
+      expect(Object.keys(parsed.files).sort()).toEqual(["gcp/subnet.md", "gcp/vpc.md", "index.md"]);
+    });
+  });
 });

package/src/cli/handlers/graph.ts

@@ -77,7 +77,7 @@ async function graphBuildParams(
 async function graphBuildRootContributors(
   ctx: CommandContext,
   projectPath: string,
-): Promise<Array<() => Promise<import("../../lexicon").BuildRootContribution>>> {
+): Promise<Array<import("../../lexicon").BuildRootContributor>> {
   const { config, configPath } = await loadChantConfigUpward(projectPath).catch(
     () => ({ config: {} as ChantConfig, configPath: undefined }),
   );
@@ -109,7 +109,7 @@ async function graphBuildRootContributors(
  */
 async function mergeGraphBuildRoots(
   entities: Map<string, import("../../declarable").Declarable>,
-  contributors: Array<() => Promise<import("../../lexicon").BuildRootContribution>>,
+  contributors: Array<import("../../lexicon").BuildRootContributor>,
 ): Promise<boolean> {
   if (contributors.length === 0) return true;
   const merged = await mergeBuildRootEntities(entities, contributors);

package/src/cli/handlers/lifecycle.test.ts

@@ -821,6 +821,120 @@ describe("runLifecyclePlan", () => {
     expect(byName["sg-0abc123"].name).toBe("sg-0abc123");
   });
 
+  // #1832 — effect receipts are declared, diffed, and observed like any
+  // resource, but observe-only to the generic apply path: the plan compares
+  // live value to resolved expectation and proposes the fire, never a create.
+  describe("effect receipts (#1832)", () => {
+    const receiptEntity = (lexicon: string) => ({
+      lexicon,
+      entityType: lexicon === "chant" ? "Chant::EffectReceipt" : `${lexicon}::Receipt`,
+      name: "dbMigrated",
+      effect: "db-migrate",
+      flavor: "existence" as const,
+      inputs: {},
+      [Symbol.for("chant.declarable")]: true,
+      [Symbol.for("chant.effect-receipt")]: true,
+    });
+
+    const buildWithReceipt = (lexicon: string): BuildResult => {
+      const base = makeBuildResult({ aws: ["bucket"] });
+      base.entities.set("dbMigrated", receiptEntity(lexicon) as unknown as Parameters<typeof base.entities.set>[1]);
+      if (lexicon !== "aws") (base.manifest.lexicons as string[]).push(lexicon);
+      return base;
+    };
+
+    test("an absent receipt is an effect row, never a create", async () => {
+      buildMock.mockResolvedValue(buildWithReceipt("aws"));
+      const plugins: LexiconPlugin[] = [
+        createMockPlugin({
+          name: "aws",
+          emulator: awsEmulatorStub,
+          describeResources: async () => ({
+            observation: "v1" as const,
+            resources: { bucket: meta() },
+            // dbMigrated neither returned nor unobserved: confirmed absent.
+          }),
+        }),
+      ];
+      const exit = await runLifecyclePlan({
+        args: makeArgs({ path: "plan", extraPositional: "prod", json: true }),
+        plugins,
+        serializers: plugins.map((p) => p.serializer),
+      });
+      expect(exit).toBe(0);
+      const plan = JSON.parse(stdoutBuf.join("\n"));
+      const row = plan.entries.find((e: { name: string }) => e.name === "dbMigrated");
+      expect(row).toMatchObject({ action: "effect", effect: "db-migrate", effectReason: "receipt-absent", lexicon: "aws" });
+      expect(plan.entries.filter((e: { name: string; action: string }) => e.name === "dbMigrated")).toHaveLength(1);
+    });
+
+    test("a live receipt carrying the existence marker is a clean noop, and the render says nothing fires", async () => {
+      buildMock.mockResolvedValue(buildWithReceipt("aws"));
+      const plugins: LexiconPlugin[] = [
+        createMockPlugin({
+          name: "aws",
+          emulator: awsEmulatorStub,
+          describeResources: async () => ({
+            observation: "v1" as const,
+            resources: {
+              bucket: meta(),
+              dbMigrated: meta({ type: "aws::Receipt", attributes: { value: "chant.effect-receipt:exists" } }),
+            },
+          }),
+        }),
+      ];
+      const exit = await runLifecyclePlan({
+        args: makeArgs({ path: "plan", extraPositional: "prod" }),
+        plugins,
+        serializers: plugins.map((p) => p.serializer),
+      });
+      expect(exit).toBe(0);
+      expect(stdoutBuf.join("\n")).toContain("0 effect");
+      expect(stdoutBuf.join("\n")).not.toContain("effect will fire");
+    });
+
+    test("a stale receipt renders effect will fire", async () => {
+      buildMock.mockResolvedValue(buildWithReceipt("aws"));
+      const plugins: LexiconPlugin[] = [
+        createMockPlugin({
+          name: "aws",
+          emulator: awsEmulatorStub,
+          describeResources: async () => ({
+            observation: "v1" as const,
+            resources: {
+              bucket: meta(),
+              dbMigrated: meta({ type: "aws::Receipt", attributes: { value: "something-else" } }),
+            },
+          }),
+        }),
+      ];
+      const exit = await runLifecyclePlan({
+        args: makeArgs({ path: "plan", extraPositional: "prod" }),
+        plugins,
+        serializers: plugins.map((p) => p.serializer),
+      });
+      expect(exit).toBe(0);
+      expect(stdoutBuf.join("\n")).toContain("effect will fire: db-migrate");
+    });
+
+    test("a receipt no loaded lexicon observes is unobserved, loudly", async () => {
+      buildMock.mockResolvedValue(buildWithReceipt("chant"));
+      const plugins: LexiconPlugin[] = [
+        createMockPlugin({ name: "aws", emulator: awsEmulatorStub, describeResources: staticDescribeResources({ bucket: meta() }) }),
+      ];
+      const exit = await runLifecyclePlan({
+        args: makeArgs({ path: "plan", extraPositional: "prod", json: true }),
+        plugins,
+        serializers: plugins.map((p) => p.serializer),
+      });
+      expect(exit).toBe(0);
+      const plan = JSON.parse(stdoutBuf.join("\n"));
+      const row = plan.entries.find((e: { name: string }) => e.name === "dbMigrated");
+      expect(row).toMatchObject({ action: "unobserved", unobservedReason: "unsupported-kind" });
+      expect(stderrBuf.join("\n")).toContain("could not be observed");
+    });
+  });
+
   // #1166 — plan is always a live read (no `--live` flag of its own), so a
   // declared environment endpoint applies here exactly as it does for
   // `chant graph --live` / `chant lifecycle diff --live`.
@@ -1279,7 +1393,7 @@ describe("runLifecycleTeardown (#1222 — plan only)", () => {
     const out = stdoutBuf.join("\n");
     expect(out).toContain("Outcomes:");
     expect(out).toContain("deleted");
-    expect(out).toContain("1 deleted, 0 failed, 0 not prunable, 0 skipped");
+    expect(out).toContain("1 deleted, 0 failed, 0 not prunable, 0 retained, 0 skipped");
     expect(out).not.toContain("plan only");
   });