@intentius/chant 0.45.0 → 0.49.0

package/src/lint/knowledge-checks.ts

@@ -0,0 +1,74 @@
+import type { PostSynthCheck, PostSynthDiagnostic } from "./post-synth";
+import type { OkfBundle } from "../okf-read";
+import { bindConcepts } from "../okf-read";
+
+/**
+ * COR026: Stale Knowledge Binding (#1865, design #1059, epic #1057)
+ *
+ * A concept's `binds` frontmatter key names a discovered entity's logical
+ * name (#1864, `../okf-read.ts`'s `bindConcepts`). A name that resolves to
+ * nothing is a stale binding — the entity was renamed or removed, or the
+ * concept was authored against a name that never existed — and per #1059's
+ * stated failure posture ("the spec permits broken links, which argues for
+ * warn") that is a warning, never a build failure: knowledge is deliberately
+ * softer than the typed graph it describes, and OKF itself tolerates broken
+ * links (epic #1057).
+ *
+ * The converse is deliberately silent: a concept with no `binds` at all is
+ * orphaned knowledge, not an omission (a runbook, a decision about the
+ * project as a whole), and `bindConcepts` never reports it as unresolved in
+ * the first place — see its own doc comment. A project with no knowledge
+ * bundle loads an empty one (`loadOkfBundle`), so this check produces no
+ * diagnostics either.
+ *
+ * Wired into `chant build` (`../cli/commands/build.ts`) alongside
+ * `coreReceiptChecks` — same reasons COR023/COR024 are build-owned rather
+ * than a per-file `LintRule`: the check needs the full discovered entity map
+ * (`ctx.entities`), not one `ts.SourceFile`, and that map only exists after
+ * discovery has run. Unlike COR023/024 it never reads `ctx.outputs` — the
+ * bundle is loaded once, up front (async — `loadOkfBundle` reads the
+ * filesystem), and closed over here so the check itself stays the same sync
+ * shape every other `PostSynthCheck` has.
+ */
+
+export const STALE_KNOWLEDGE_BINDING_CHECK_ID = "COR026";
+
+/**
+ * Build the COR026 check for one loaded bundle. A factory, not a bare
+ * constant, because — unlike `coreReceiptChecks`, which needs nothing but
+ * `ctx.entities` — this check needs the bundle loaded from disk, and
+ * `loadOkfBundle` is async while `PostSynthCheck#check` is not. The caller
+ * loads the bundle once (`resolveKnowledgeDir` + `loadOkfBundle`) and passes
+ * it in; see `../cli/commands/build.ts`.
+ */
+export function staleKnowledgeBindingCheck(bundle: OkfBundle): PostSynthCheck {
+  return {
+    id: STALE_KNOWLEDGE_BINDING_CHECK_ID,
+    description:
+      "A knowledge concept's `binds` entry must name a discovered entity — a name that resolves to nothing is a stale binding",
+    check(ctx) {
+      const { unresolved } = bindConcepts(bundle, ctx.entities);
+      return unresolved.map(
+        ({ concept, name }): PostSynthDiagnostic => ({
+          checkId: STALE_KNOWLEDGE_BINDING_CHECK_ID,
+          severity: "warning",
+          message:
+            `Knowledge concept "${concept.path}" binds "${name}", but no discovered entity has that name — ` +
+            `a stale binding. The entity may have been renamed or removed, or the concept was authored ` +
+            `against a name that never existed. Update the concept's \`binds\` frontmatter, or remove the ` +
+            `entry if the concept no longer applies.`,
+        }),
+      );
+    },
+  };
+}
+
+/**
+ * Core's own post-synth check over knowledge bindings, run by `chant build`
+ * over the full build result — unscoped, like `coreReceiptChecks`, since a
+ * concept's `binds` can name any discovered entity regardless of which
+ * lexicon owns it.
+ */
+export function coreKnowledgeChecks(bundle: OkfBundle): PostSynthCheck[] {
+  return [staleKnowledgeBindingCheck(bundle)];
+}

package/src/lint/output-checks.test.ts

@@ -0,0 +1,85 @@
+import { describe, test, expect } from "vitest";
+import { coreOutputChecks, STRINGIFIED_REFERENCE_CHECK_ID } from "./output-checks";
+import { runPostSynthChecks } from "./post-synth";
+import type { SerializerResult } from "../serializer";
+import type { Declarable } from "../declarable";
+
+function run(outputs: Map<string, string | SerializerResult>) {
+  return runPostSynthChecks(coreOutputChecks(), {
+    outputs,
+    entities: new Map<string, Declarable>(),
+    warnings: [],
+    errors: [],
+    sourceFileCount: 1,
+  });
+}
+
+describe("COR025: stringified reference in serialized output (#1526)", () => {
+  test("check id", () => {
+    expect(STRINGIFIED_REFERENCE_CHECK_ID).toBe("COR025");
+    expect(coreOutputChecks().map((c) => c.id)).toContain("COR025");
+  });
+
+  test("fires when a string output contains the [object Object] marker", () => {
+    const outputs = new Map<string, string | SerializerResult>([
+      ["aws", '{"Resource": "arn:aws:s3:::bucket-[object Object]/*"}'],
+    ]);
+    const diags = run(outputs);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("COR025");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].lexicon).toBe("aws");
+    expect(diags[0].message).toContain("[object Object]");
+  });
+
+  test("fires when a SerializerResult's primary content contains the marker", () => {
+    const outputs = new Map<string, string | SerializerResult>([
+      ["aws", { primary: 'Resource: "[object Object]/*"' } satisfies SerializerResult],
+    ]);
+    const diags = run(outputs);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain('Resource: "[object Object]/*"');
+  });
+
+  test("fires when a SerializerResult's nested file contains the marker, and names the file", () => {
+    const outputs = new Map<string, string | SerializerResult>([
+      [
+        "aws",
+        {
+          primary: "clean template",
+          files: { "network.template.json": '{"Resource": "[object Object]"}' },
+        } satisfies SerializerResult,
+      ],
+    ]);
+    const diags = run(outputs);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("network.template.json");
+    expect(diags[0].message).toContain("[object Object]");
+  });
+
+  test("dedupes repeated occurrences of the same line within a file", () => {
+    const line = 'Resource: "[object Object]/*"';
+    const outputs = new Map<string, string | SerializerResult>([["aws", `${line}\n${line}\n${line}`]]);
+    const diags = run(outputs);
+    expect(diags).toHaveLength(1);
+  });
+
+  test("reports one diagnostic per distinct offending line", () => {
+    const outputs = new Map<string, string | SerializerResult>([
+      ["aws", 'Resource: "[object Object]/*"\nPolicy: "[object Object]"'],
+    ]);
+    const diags = run(outputs);
+    expect(diags).toHaveLength(2);
+  });
+
+  test("passes: output with no stringified reference", () => {
+    const outputs = new Map<string, string | SerializerResult>([
+      ["aws", '{"Resource": "arn:aws:s3:::my-bucket/*"}'],
+    ]);
+    expect(run(outputs)).toHaveLength(0);
+  });
+
+  test("passes: empty outputs", () => {
+    expect(run(new Map())).toHaveLength(0);
+  });
+});

package/src/lint/output-checks.ts

@@ -0,0 +1,99 @@
+import type { SerializerResult } from "../serializer";
+import type { PostSynthCheck, PostSynthDiagnostic } from "./post-synth";
+import { getPrimaryOutput } from "./post-synth";
+
+/**
+ * COR025: Stringified Reference in Serialized Output (#1526)
+ *
+ * kubemicrovm-ops composed a bucket policy's resource ARN with a template
+ * literal — `` `${bucket.Arn}/*` `` — over an `AttrRef`, not a string.
+ * JavaScript stringifies any non-primitive interpolated into a template
+ * literal via `Object.prototype.toString`, so the emitted policy carried the
+ * literal substring `"[object Object]/*"` in place of the resolved ARN. That
+ * built clean and linted clean — nothing upstream of serialization sees a
+ * type error, because `AttrRef` IS an object and a template literal accepts
+ * any coercible value — and it deployed clean on floci, which does no
+ * policy validation. It failed the first real deploy with S3 rejecting the
+ * policy's `Resource` and rolling back the stack.
+ *
+ * `[object Object]` (and its array-of-objects sibling `[object Object,object
+ * Object]`) never appears in a serialized template/manifest on purpose: no
+ * lexicon's serializer ever emits it, and no cloud provider's schema ever
+ * expects it as a literal value. Its presence is only ever a reference that
+ * got coerced to a string instead of resolved. That makes this check cheap,
+ * universal across lexicons (it scans the emitted text, not any one
+ * lexicon's schema), and free of false positives worth caring about — see
+ * `stringifiedReferenceCheck` below.
+ *
+ * Scans `ctx.outputs` (the SYNTHESIZED text) rather than `ctx.entities`
+ * because the coercion already happened in the user's own declaration code,
+ * upstream of anything chant's model retains structurally — by the time an
+ * entity reaches `ctx.entities` its prop is already a plain string containing
+ * the marker, indistinguishable from any other string prop. The only place
+ * left to catch it lexicon-independently is the text chant actually emits.
+ */
+
+const MARKER = "[object Object]";
+
+export const STRINGIFIED_REFERENCE_CHECK_ID = "COR025";
+
+/** Trim a matched line down to a readable snippet without truncating mid-marker. */
+const MAX_SNIPPET_LENGTH = 200;
+
+function lineContaining(text: string, index: number): string {
+  const lineStart = text.lastIndexOf("\n", index) + 1;
+  const nextNewline = text.indexOf("\n", index);
+  const lineEnd = nextNewline === -1 ? text.length : nextNewline;
+  const line = text.slice(lineStart, lineEnd).trim();
+  return line.length > MAX_SNIPPET_LENGTH ? `${line.slice(0, MAX_SNIPPET_LENGTH)}…` : line;
+}
+
+/** Every serialized file for one lexicon's output: the primary plus any nested files. */
+function serializedFiles(output: string | SerializerResult): Record<string, string> {
+  const files: Record<string, string> = { primary: getPrimaryOutput(output) };
+  if (typeof output !== "string" && output.files) {
+    Object.assign(files, output.files);
+  }
+  return files;
+}
+
+const stringifiedReferenceCheck: PostSynthCheck = {
+  id: STRINGIFIED_REFERENCE_CHECK_ID,
+  description:
+    'A serialized output contains the literal substring "[object Object]" — a reference that was ' +
+    "stringified (e.g. through a template literal or string concatenation) instead of resolved. " +
+    "Always an authoring error, never intentional output.",
+  check(ctx) {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const [lexicon, output] of ctx.outputs) {
+      for (const [fileLabel, content] of Object.entries(serializedFiles(output))) {
+        const seenLines = new Set<string>();
+        let index = content.indexOf(MARKER);
+        while (index !== -1) {
+          const line = lineContaining(content, index);
+          const dedupeKey = `${fileLabel}::${line}`;
+          if (!seenLines.has(dedupeKey)) {
+            seenLines.add(dedupeKey);
+            const location = fileLabel === "primary" ? "" : ` (${fileLabel})`;
+            diagnostics.push({
+              checkId: STRINGIFIED_REFERENCE_CHECK_ID,
+              severity: "error",
+              lexicon,
+              message:
+                `Serialized output${location} contains "${MARKER}" — a reference was stringified ` +
+                `instead of resolved (a template literal or string concatenation over an object, ` +
+                `not the raw value/ref). Emitted line: ${line}`,
+            });
+          }
+          index = content.indexOf(MARKER, index + MARKER.length);
+        }
+      }
+    }
+    return diagnostics;
+  },
+};
+
+/** Core-owned post-synth checks over serialized output text (#1526). */
+export function coreOutputChecks(): PostSynthCheck[] {
+  return [stringifiedReferenceCheck];
+}

package/src/lint/pipeline-change-gate.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, test } from "vitest";
+import type { Component, Phase } from "../components/component";
+import {
+  classifyComponentPipelineChange,
+  classifyPipelineChange,
+  componentVerbSet,
+  evaluatePipelineChangeGate,
+} from "./pipeline-change-gate";
+
+const KNOWN: ReadonlySet<string> = new Set(["cfn-deploy", "publish-image", "wait-for-stack"]);
+
+const component = (deploy: Phase[]): Component => ({
+  name: "widget",
+  dependsOn: [],
+  deploy,
+});
+
+const ordinary = (): Component =>
+  component([{ phase: "Deploy", steps: [{ kind: "cfn-deploy" }, { kind: "wait-for-stack" }] }]);
+
+const withShell = (): Component =>
+  component([{ phase: "Deploy", steps: [{ kind: "shell", cmd: "echo hi", reason: "no capability yet" }] }]);
+
+const withUnregisteredVerb = (): Component =>
+  component([{ phase: "Deploy", steps: [{ kind: "some-new-verb" }] }]);
+
+describe("classifyComponentPipelineChange (#1569)", () => {
+  test("a composition of only registry verbs is not a pipeline change", () => {
+    const result = classifyComponentPipelineChange(ordinary(), { knownKinds: KNOWN });
+    expect(result).toEqual({ pipelineChange: false, reasons: [] });
+  });
+
+  test("any shell step trips the class unconditionally, even with a declared reason", () => {
+    const result = classifyComponentPipelineChange(withShell(), { knownKinds: KNOWN });
+    expect(result.pipelineChange).toBe(true);
+    expect(result.reasons).toEqual([{ kind: "shell-step", phaseName: "Deploy" }]);
+  });
+
+  test("a verb outside the known registry trips the class", () => {
+    const result = classifyComponentPipelineChange(withUnregisteredVerb(), { knownKinds: KNOWN });
+    expect(result.pipelineChange).toBe(true);
+    expect(result.reasons).toEqual([{ kind: "unregistered-verb", stepKind: "some-new-verb", phaseName: "Deploy" }]);
+  });
+
+  test("gate steps are never mistaken for an escape hatch", () => {
+    const withGate = component([
+      { phase: "Approve", steps: [{ kind: "gate", signalName: "release-approved" }] },
+    ]);
+    expect(classifyComponentPipelineChange(withGate, { knownKinds: KNOWN })).toEqual({
+      pipelineChange: false,
+      reasons: [],
+    });
+  });
+
+  test("nested fan-out phases are walked, same as COMP005/COMP006", () => {
+    const nested = component([
+      {
+        phase: "Fanout",
+        steps: [{ phase: "per-region", steps: [{ kind: "shell", cmd: "aws sts get-caller-identity", reason: "no capability" }] }],
+      },
+    ]);
+    const result = classifyComponentPipelineChange(nested, { knownKinds: KNOWN });
+    expect(result.pipelineChange).toBe(true);
+    expect(result.reasons).toEqual([{ kind: "shell-step", phaseName: "per-region" }]);
+  });
+
+  test("without an explicit registry, falls back to core's starter verbs (same fallback as COMP005)", () => {
+    // cfn-deploy is not in core's starter set (it's an aws-lexicon leaf), so
+    // this asserts the fallback is core's own set, not "everything passes".
+    const result = classifyComponentPipelineChange(ordinary());
+    expect(result.pipelineChange).toBe(true);
+    expect(result.reasons.some((r) => r.kind === "unregistered-verb" && r.stepKind === "cfn-deploy")).toBe(true);
+  });
+});
+
+describe("componentVerbSet (#1569)", () => {
+  test("collects every non-gate step kind, excluding gate steps", () => {
+    const c = component([
+      {
+        phase: "Deploy",
+        steps: [{ kind: "cfn-deploy" }, { kind: "gate", signalName: "go" }, { kind: "wait-for-stack" }],
+      },
+    ]);
+    expect(componentVerbSet(c)).toEqual(new Set(["cfn-deploy", "wait-for-stack"]));
+  });
+});
+
+describe("classifyPipelineChange (#1569)", () => {
+  test("no `before` (a brand-new component): reports only the single-composition findings, no verb-set-changed", () => {
+    const result = classifyPipelineChange(undefined, ordinary(), { knownKinds: KNOWN });
+    expect(result).toEqual({ pipelineChange: false, reasons: [] });
+  });
+
+  test("identical verb set before and after is not a pipeline change even with `before` present", () => {
+    const result = classifyPipelineChange(ordinary(), ordinary(), { knownKinds: KNOWN });
+    expect(result).toEqual({ pipelineChange: false, reasons: [] });
+  });
+
+  test("adding a verb to the composition trips verb-set-changed", () => {
+    const after = component([
+      { phase: "Deploy", steps: [{ kind: "cfn-deploy" }, { kind: "wait-for-stack" }, { kind: "publish-image" }] },
+    ]);
+    const result = classifyPipelineChange(ordinary(), after, { knownKinds: KNOWN });
+    expect(result.pipelineChange).toBe(true);
+    expect(result.reasons).toEqual([{ kind: "verb-set-changed", added: ["publish-image"], removed: [] }]);
+  });
+
+  test("removing a verb from the composition trips verb-set-changed", () => {
+    const after = component([{ phase: "Deploy", steps: [{ kind: "cfn-deploy" }] }]);
+    const result = classifyPipelineChange(ordinary(), after, { knownKinds: KNOWN });
+    expect(result.reasons).toEqual([{ kind: "verb-set-changed", added: [], removed: ["wait-for-stack"] }]);
+  });
+
+  test("a verb-set change composes with a shell finding on the same change, both reported", () => {
+    const after = withShell();
+    const result = classifyPipelineChange(ordinary(), after, { knownKinds: KNOWN });
+    expect(result.pipelineChange).toBe(true);
+    expect(result.reasons).toContainEqual({ kind: "shell-step", phaseName: "Deploy" });
+    expect(result.reasons).toContainEqual({
+      kind: "verb-set-changed",
+      added: ["shell"],
+      removed: ["cfn-deploy", "wait-for-stack"],
+    });
+  });
+});
+
+describe("evaluatePipelineChangeGate (#1569)", () => {
+  test("an ordinary composition routes nowhere", () => {
+    const verdict = evaluatePipelineChangeGate(undefined, ordinary(), "human-always", { knownKinds: KNOWN });
+    expect(verdict.route).toBe("none");
+    expect(verdict.pipelineChange).toBe(false);
+  });
+
+  test('defaults to "human-always" — a pipeline change never free-runs unless the caller opts into "stricter-gate"', () => {
+    const verdict = evaluatePipelineChangeGate(undefined, withShell(), undefined, { knownKinds: KNOWN });
+    expect(verdict.route).toBe("human-always");
+    expect(verdict.pipelineChange).toBe(true);
+  });
+
+  test('"stricter-gate" routes a pipeline change to the named stricter class instead', () => {
+    const verdict = evaluatePipelineChangeGate(undefined, withShell(), "stricter-gate", { knownKinds: KNOWN });
+    expect(verdict.route).toBe("stricter-gate");
+  });
+});

package/src/lint/pipeline-change-gate.ts

@@ -0,0 +1,153 @@
+/**
+ * The pipeline-change gate class (#1569): changes to the pipeline itself
+ * route to a stricter gate.
+ *
+ * The honest concession in the PR-flow teardown (rubric-product-research,
+ * 06-objections §1): chant Ops have a `shell` step, so a governed plane is
+ * not automatically immune to "the change edits the machinery that applies
+ * changes." What chant *can* claim — and a plain PR flow structurally cannot
+ * — is that pipeline changes are distinguishable: a composition is data over
+ * a bounded verb registry, and the COMP rules already police the escape
+ * hatches (COMP006 — every `shell` step carries a declared reason;
+ * COMP005 — no noun-shaped escape hatches, `./rules/comp/`). What was missing
+ * was the routing: nothing classified a change as "touches the pipeline" and
+ * required a stricter gate for it, so a change to a composition rode through
+ * the same gate as a replica-count bump.
+ *
+ * This is the cheap first cut #1569 asks for: the registry-only predicate.
+ * A composition that contains only registry verbs is ordinary; a `shell`
+ * step (the deliberate escape hatch) or a change to the set of verbs a
+ * composition invokes trips the stricter class. comp005/comp006 already make
+ * both decidable from the text — this module reuses the same walk
+ * (`./rules/comp/support.ts`) rather than re-deriving it.
+ *
+ * Like #1568's `evaluateUnobservedGate`
+ * (../lifecycle/unobserved-gate.ts), this is a reusable predicate, not a
+ * runtime: classify a change and get back a verdict; the caller (a
+ * `lint.policies` check routed through `policyGate`, an Op step, #1487's
+ * gate-as-fact once it lands) decides what "stricter" means in its own
+ * context. The stricter class composes with #1487's principle that
+ * destructive verbs always wait for a person — pipeline changes are the
+ * second category that should never free-run, because they change what
+ * "gated" means for everything after them. That is why the default policy
+ * below is `"human-always"`, not `"stricter-gate"`.
+ */
+import type { Component } from "../components/component";
+import { STARTER_VERB_FAMILIES } from "../components/starter-plugin";
+import { walkComponent } from "./rules/comp/support";
+
+/**
+ * Fallback registry when no project registry is supplied: core's own starter
+ * verbs, the same fallback COMP005 uses for a direct unit test
+ * (`./rules/comp/comp005-capability-kind-is-noun.ts`). A real `chant lint` /
+ * gate run passes the project's resolved `knownKinds` (core's starter set
+ * plus the active lexicons' leaves) so a real project's cloud verbs are never
+ * mistaken for an out-of-registry escape hatch.
+ */
+const CORE_STARTER_KINDS: ReadonlySet<string> = new Set(Object.values(STARTER_VERB_FAMILIES).flat());
+
+/** Why a composition (or a change to one) tripped the pipeline-change class. */
+export type PipelineChangeReason =
+  | { kind: "shell-step"; phaseName: string }
+  | { kind: "unregistered-verb"; stepKind: string; phaseName: string }
+  | { kind: "verb-set-changed"; added: string[]; removed: string[] };
+
+export interface PipelineChangeClassification {
+  /** True when any reason below applies. */
+  pipelineChange: boolean;
+  reasons: PipelineChangeReason[];
+}
+
+/** Every non-gate step kind a component's composition invokes, across `deploy` and `rollback` (nested fan-out phases included, via `walkComponent`). `gate` steps are excluded — they are not a capability verb. */
+export function componentVerbSet(component: Component): Set<string> {
+  const { steps } = walkComponent(component);
+  return new Set(steps.map((s) => s.step.kind));
+}
+
+/**
+ * Classify a single component's composition (the "cheap first cut", no
+ * before/after needed): a `shell` step trips the class unconditionally — it
+ * is the escape hatch by construction (COMP006) — and any step whose `kind`
+ * is outside `knownKinds` trips it too, since an unregistered verb is,
+ * structurally, the same kind of hole a `shell` step is: something the
+ * bounded registry does not account for.
+ */
+export function classifyComponentPipelineChange(
+  component: Component,
+  opts?: { knownKinds?: ReadonlySet<string> },
+): PipelineChangeClassification {
+  const knownKinds = opts?.knownKinds ?? CORE_STARTER_KINDS;
+  const { steps } = walkComponent(component);
+
+  const reasons: PipelineChangeReason[] = [];
+  for (const { step, phaseName } of steps) {
+    if (step.kind === "shell") {
+      reasons.push({ kind: "shell-step", phaseName });
+    } else if (!knownKinds.has(step.kind)) {
+      reasons.push({ kind: "unregistered-verb", stepKind: step.kind, phaseName });
+    }
+  }
+
+  return { pipelineChange: reasons.length > 0, reasons };
+}
+
+/**
+ * Classify a *change* to a component's composition between two revisions
+ * (#1569's "add or modify a shell step ... or the composition graph
+ * itself"): on top of `classifyComponentPipelineChange`'s single-composition
+ * check on `after`, a change also trips the class when the verb set itself
+ * changed — a verb added or removed changes what the composition can invoke,
+ * which is the routing signal even when every individual verb, before and
+ * after, is registry-clean. `before: undefined` (a brand-new component) never
+ * reports a verb-set change — there is nothing to diff against, and the
+ * single-composition check already covers a new component's own shell/
+ * unregistered-verb findings.
+ */
+export function classifyPipelineChange(
+  before: Component | undefined,
+  after: Component,
+  opts?: { knownKinds?: ReadonlySet<string> },
+): PipelineChangeClassification {
+  const base = classifyComponentPipelineChange(after, opts);
+  if (!before) return base;
+
+  const beforeVerbs = componentVerbSet(before);
+  const afterVerbs = componentVerbSet(after);
+  const added = [...afterVerbs].filter((v) => !beforeVerbs.has(v)).sort();
+  const removed = [...beforeVerbs].filter((v) => !afterVerbs.has(v)).sort();
+
+  if (added.length === 0 && removed.length === 0) return base;
+
+  return {
+    pipelineChange: true,
+    reasons: [...base.reasons, { kind: "verb-set-changed", added, removed }],
+  };
+}
+
+/**
+ * How the gate routes a classified pipeline change.
+ *
+ * - `"human-always"` (the recommended default — see this module's doc
+ *   comment) — a pipeline change never free-runs, mirroring #1487's "a
+ *   destructive verb always waits for a person."
+ * - `"stricter-gate"` — route to a named stricter gate class rather than
+ *   requiring a person on every run; the caller supplies what "stricter"
+ *   means (an additional approval, a narrower blast-radius budget, ...).
+ */
+export type PipelineChangeGatePolicy = "stricter-gate" | "human-always";
+
+export interface PipelineChangeGateVerdict extends PipelineChangeClassification {
+  /** What the policy says to do about it. `"none"` when the change is not a pipeline change at all. */
+  route: PipelineChangeGatePolicy | "none";
+}
+
+/** Evaluate a component composition change against a routing policy. Pure — no I/O. */
+export function evaluatePipelineChangeGate(
+  before: Component | undefined,
+  after: Component,
+  policy: PipelineChangeGatePolicy = "human-always",
+  opts?: { knownKinds?: ReadonlySet<string> },
+): PipelineChangeGateVerdict {
+  const classification = classifyPipelineChange(before, after, opts);
+  return { ...classification, route: classification.pipelineChange ? policy : "none" };
+}

package/src/lint/post-synth.ts

@@ -33,6 +33,21 @@ export function getPrimaryOutput(output: string | SerializerResult): string {
   return typeof output === "string" ? output : output.primary;
 }
 
+/**
+ * Extract the ADDITIONAL files from a serializer output — everything
+ * {@link getPrimaryOutput} discards.
+ *
+ * Every post-synth check shipped before this one reads the primary output
+ * only, which means a sidecar file (a nested stack template, committed SOPS
+ * ciphertext) is invisible to all of them. That is the right default — the
+ * primary output is what appliers read — but a rule ABOUT a sidecar has to
+ * be able to see it, and `PostSynthContext.outputs` has carried the data all
+ * along. WK8504 (k8s) is the first caller.
+ */
+export function getAdditionalFiles(output: string | SerializerResult): Record<string, string> {
+  return typeof output === "string" ? {} : (output.files ?? {});
+}
+
 /**
  * A diagnostic from a post-synthesis check.
  *

package/src/lint/receipt-checks.test.ts

@@ -0,0 +1,101 @@
+import { describe, test, expect } from "vitest";
+import { coreReceiptChecks, RECEIPT_PLAIN_STORE_CHECK_ID } from "./receipt-checks";
+import { runPostSynthChecks } from "./post-synth";
+import { EffectReceipt, EFFECT_RECEIPT_MARKER } from "../effect-receipt";
+import { DECLARABLE_MARKER, type Declarable } from "../declarable";
+
+/** A lexicon-materialized receipt row: its own entityType, the receipt marker. */
+function materializedReceipt(opts: {
+  lexicon: string;
+  entityType: string;
+  props?: Record<string, unknown>;
+}): Declarable {
+  return {
+    [DECLARABLE_MARKER]: true,
+    [EFFECT_RECEIPT_MARKER]: true,
+    lexicon: opts.lexicon,
+    entityType: opts.entityType,
+    ...(opts.props ? { props: opts.props } : {}),
+  } as unknown as Declarable;
+}
+
+function run(entities: Map<string, Declarable>) {
+  return runPostSynthChecks(coreReceiptChecks(), {
+    outputs: new Map(),
+    entities,
+    warnings: [],
+    errors: [],
+    sourceFileCount: 1,
+  });
+}
+
+describe("COR023: receipt materializes into a plain store (#1833)", () => {
+  test("check id", () => {
+    expect(RECEIPT_PLAIN_STORE_CHECK_ID).toBe("COR023");
+    expect(coreReceiptChecks().map((c) => c.id)).toContain("COR023");
+  });
+
+  test("fires when a receipt is materialized into a Secret kind", () => {
+    const entities = new Map<string, Declarable>([
+      ["seededReceipt", materializedReceipt({ lexicon: "k8s", entityType: "K8s::Core::Secret" })],
+    ]);
+    const diags = run(entities);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("COR023");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].entity).toBe("seededReceipt");
+    expect(diags[0].message).toContain("K8s::Core::Secret");
+    expect(diags[0].message).toContain("plain store");
+  });
+
+  test("fires when a plain kind selects a secret-capable variant (SSM SecureString)", () => {
+    const entities = new Map<string, Declarable>([
+      [
+        "migratedReceipt",
+        materializedReceipt({
+          lexicon: "aws",
+          entityType: "AWS::SSM::Parameter",
+          props: { Name: "/receipts/migrated", Type: "SecureString" },
+        }),
+      ],
+    ]);
+    const diags = run(entities);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain('Type: "SecureString"');
+    expect(diags[0].entity).toBe("migratedReceipt");
+  });
+
+  test("passes: a receipt materialized into a plain store", () => {
+    const entities = new Map<string, Declarable>([
+      [
+        "migratedReceipt",
+        materializedReceipt({
+          lexicon: "aws",
+          entityType: "AWS::SSM::Parameter",
+          props: { Name: "/receipts/migrated", Type: "String" },
+        }),
+      ],
+    ]);
+    expect(run(entities)).toHaveLength(0);
+  });
+
+  test("passes: the core Chant::EffectReceipt declaration itself", () => {
+    const receipt = EffectReceipt("seeded", {
+      effect: "db-seed",
+      flavor: "hash",
+      inputs: { schema: "v3" },
+    });
+    const entities = new Map<string, Declarable>([["seeded", receipt]]);
+    expect(run(entities)).toHaveLength(0);
+  });
+
+  test("passes: a Secret-kind entity that is NOT a receipt is not this check's concern", () => {
+    const secret: Declarable = {
+      [DECLARABLE_MARKER]: true,
+      lexicon: "k8s",
+      entityType: "K8s::Core::Secret",
+    } as unknown as Declarable;
+    const entities = new Map<string, Declarable>([["dbSecret", secret]]);
+    expect(run(entities)).toHaveLength(0);
+  });
+});