@intentius/chant-lexicon-k8s 0.58.0 → 0.60.0

package/src/describe-resources.ts

@@ -68,6 +68,7 @@ import {
 import { operationFor } from "./api/operation-surface";
 import { resolveK8sOwnerChain } from "./api/owner-chain";
 import { gvkToTypeName } from "./spec/parse";
+import { observeReceiptRows, receiptRowsFor } from "./receipt-store";
 
 function pruneUndefined<T extends Record<string, unknown>>(obj: T): Record<string, unknown> {
   const out: Record<string, unknown> = {};
@@ -357,11 +358,26 @@ export async function describeResources(
   // looked for where it lives".
   const queried: Record<string, string> = {};
 
-  const declared: Declared[] = [...options.entities].map(([entityName, entity]) => ({
-    entityName,
-    entityType: entity.entityType,
-    props: entity.props,
-  }));
+  // Effect receipt rows (#2074) are read by their own leg below: the applier
+  // never wrote them (#1832), and their declaration carries no props, so the
+  // generic sweep has no `metadata.name` to query by and would report a hole
+  // where the receipt leg has a real answer. Their addresses come from the
+  // build output's receipt comment, which is the serializer's one rendering of
+  // the derivation (./effect-receipt-row.ts).
+  const receiptRows = receiptRowsFor(options.entityNames, options.buildOutput);
+
+  const declared: Declared[] = [...options.entities]
+    .filter(([entityName]) => !receiptRows.has(entityName))
+    .map(([entityName, entity]) => ({
+      entityName,
+      entityType: entity.entityType,
+      props: entity.props,
+    }));
+
+  // A whole-lexicon failure below is a hole for the receipts too: nobody
+  // looked at those either, and a connect that never happened proves nothing
+  // about a receipt's presence.
+  const everyName = [...declared.map((d) => d.entityName), ...receiptRows.keys()];
 
   // Connect first. The binding check lives here, so a bound-but-mismatched
   // context throws before any resource is read — core turns that into
@@ -374,7 +390,7 @@ export async function describeResources(
       return observation(
         {},
         unobservedAll(
-          declared.map((d) => d.entityName),
+          everyName,
           "read-failed",
           MISSING_CLIENT_DETAIL,
           options.entities,
@@ -386,7 +402,7 @@ export async function describeResources(
       return observation(
         {},
         unobservedAll(
-          declared.map((d) => d.entityName),
+          everyName,
           outcome.kind === "unobserved" ? outcome.reason : "read-failed",
           outcome.kind === "unobserved" ? outcome.detail : undefined,
           options.entities,
@@ -507,6 +523,14 @@ export async function describeResources(
 
   await addRuntimeChildren(client, resources, unobserved, options.owned, declared);
 
+  // The receipt leg last, so its answers are the ones that stand for the
+  // receipt entities, because nothing above ever looked at one.
+  if (receiptRows.size > 0) {
+    const receiptObs = await observeReceiptRows(client, receiptRows);
+    Object.assign(resources, receiptObs.resources);
+    Object.assign(unobserved, receiptObs.unobserved);
+  }
+
   return observation(resources, unobserved, queried);
 }
 

package/src/effect-receipt-row.test.ts

@@ -0,0 +1,285 @@
+/**
+ * The k8s effect-receipt materialization row (#2074, epic #1703): the
+ * declaration, the ConfigMap address derivation, what the serializer renders,
+ * and the #1833 guards over the row.
+ *
+ * The shape mirrors lexicons/aws/src/effect-receipt-row.test.ts, which covers
+ * the SSM row, so the two rows can be read against each other.
+ */
+
+import { describe, it, expect } from "vitest";
+import * as ts from "typescript";
+import { loadAll } from "js-yaml";
+import {
+  EffectReceipt,
+  receiptConfigMapName,
+  receiptConfigMapRef,
+  receiptNamespaceFrom,
+  isEffectReceiptObject,
+  parseReceiptComment,
+  renderReceiptComment,
+  EFFECT_RECEIPTS_COMMENT_MARKER,
+  K8S_EFFECT_RECEIPT_ENTITY_TYPE,
+  RECEIPT_DATA_KEY,
+  RECEIPT_DEFAULT_NAMESPACE,
+  RECEIPT_LABEL_KEY,
+  RECEIPT_UNRESOLVED_VALUE_NOTE,
+} from "./effect-receipt-row";
+import { k8sSerializer } from "./serializer";
+import {
+  EXISTENCE_EXPECTATION,
+  isEffectReceipt,
+  receiptExpectation,
+  EFFECT_RECEIPT_MARKER,
+} from "@intentius/chant/effect-receipt";
+import { receiptCheckInput } from "@intentius/chant/op/receipt-store";
+import { coreReceiptChecks, RECEIPT_PLAIN_STORE_CHECK_ID } from "@intentius/chant/lint/receipt-checks";
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { cor022ReceiptLeafRule } from "@intentius/chant/lint/rules/cor022-receipt-leaf";
+import type { LintContext } from "@intentius/chant/lint/rule";
+
+/** A minimal deploy-time reference, for the placeholder-value case. */
+const someRef = { [INTRINSIC_MARKER]: true as const, toJSON: () => ({ ref: "other" }) };
+
+const ownership = { stack: "demo", env: "dev" };
+
+function serializeReceipts(
+  receipts: Map<string, Declarable>,
+  marker?: { stack: string; env?: string },
+  config?: Record<string, unknown>,
+): string {
+  const out = k8sSerializer.serialize(new Map(), [], {
+    ...(marker ? { ownership: marker } : {}),
+    ...(config ? { config } : {}),
+    receipts,
+  });
+  return typeof out === "string" ? out : out.primary;
+}
+
+function receiptRows(output: string) {
+  return parseReceiptComment(output);
+}
+
+describe("EffectReceipt (k8s materialization row)", () => {
+  it("declares under the k8s lexicon with the real resource kind, carrying the marker", () => {
+    const r = EffectReceipt("seeded", { effect: "db-seed", flavor: "existence" });
+    expect(r.lexicon).toBe("k8s");
+    expect(r.entityType).toBe(K8S_EFFECT_RECEIPT_ENTITY_TYPE);
+    expect(r.entityType).toBe("K8s::Core::ConfigMap");
+    expect(isEffectReceipt(r)).toBe(true);
+  });
+
+  it("is accepted by the effect() step's receiptCheckInput, expectation stamped when static", () => {
+    const r = EffectReceipt("seeded", { effect: "db-seed", flavor: "hash", inputs: { v: 1 } });
+    const input = receiptCheckInput(r);
+    expect(input.receipt.effect).toBe("db-seed");
+    expect(input.expectation).toBe(receiptExpectation(r));
+  });
+
+  it("validates the effect as a name segment at declaration", () => {
+    expect(() => EffectReceipt("bad", { effect: "db/seed", flavor: "existence" })).toThrow(/DNS-1123/);
+    expect(() => EffectReceipt("bad", { effect: "DbSeed", flavor: "existence" })).toThrow(/DNS-1123/);
+    expect(() => EffectReceipt("bad", { effect: "", flavor: "existence" })).toThrow(/non-empty/);
+  });
+});
+
+describe("receiptConfigMapName", () => {
+  it("derives chant-receipt.<stack>.<env>.<effect>", () => {
+    expect(receiptConfigMapName("demo", "dev", "db-seed")).toBe("chant-receipt.demo.dev.db-seed");
+  });
+
+  it("refuses a segment that is not a DNS-1123 label, so the identity stays unambiguous", () => {
+    expect(() => receiptConfigMapName("a.b", "dev", "seed")).toThrow(/stack/);
+    expect(() => receiptConfigMapName("demo", "", "seed")).toThrow(/env/);
+    expect(() => receiptConfigMapName("demo", "dev", "Seed")).toThrow(/effect/);
+  });
+
+  it("refuses a name over Kubernetes' 253-character ceiling", () => {
+    expect(() => receiptConfigMapName("a".repeat(63), "b".repeat(63), "c".repeat(63))).not.toThrow();
+    expect(() => receiptConfigMapName("a".repeat(64), "dev", "seed")).toThrow(/DNS-1123/);
+  });
+
+  it("addresses the receipt in the project's namespace, `default` when none is set", () => {
+    expect(receiptConfigMapRef("demo", "dev", "db-seed")).toEqual({
+      name: "chant-receipt.demo.dev.db-seed",
+      namespace: RECEIPT_DEFAULT_NAMESPACE,
+    });
+    expect(receiptConfigMapRef("demo", "dev", "db-seed", "chant-system").namespace).toBe("chant-system");
+    expect(receiptNamespaceFrom({ k8s: { receipts: { namespace: "chant-system" } } })).toBe("chant-system");
+    expect(receiptNamespaceFrom(undefined)).toBe("default");
+    expect(receiptNamespaceFrom({ k8s: {} })).toBe("default");
+  });
+});
+
+describe("k8sSerializer receipt rows", () => {
+  it("renders each receipt as a ConfigMap row at the derived address, expectation under data", () => {
+    const seeded = EffectReceipt("seeded", { effect: "db-seed", flavor: "hash", inputs: { v: 1 } });
+    const rows = receiptRows(serializeReceipts(new Map([["seeded", seeded]]), ownership));
+    expect(rows.seeded).toEqual({
+      kind: "ConfigMap",
+      namespace: "default",
+      name: "chant-receipt.demo.dev.db-seed",
+      data: { [RECEIPT_DATA_KEY]: receiptExpectation(seeded) },
+    });
+  });
+
+  it("takes the namespace from k8s.receipts.namespace", () => {
+    const seeded = EffectReceipt("seeded", { effect: "db-seed", flavor: "existence" });
+    const output = serializeReceipts(new Map([["seeded", seeded]]), ownership, {
+      k8s: { receipts: { namespace: "chant-system" } },
+    });
+    expect(receiptRows(output).seeded.namespace).toBe("chant-system");
+  });
+
+  it("keeps the receipt out of the documents, the only thing an applier applies", () => {
+    const seeded = EffectReceipt("seeded", { effect: "db-seed", flavor: "existence" });
+    const output = serializeReceipts(new Map([["seeded", seeded]]), ownership);
+    const documents = loadAll(output).filter((d) => d && typeof d === "object");
+    expect(documents).toEqual([]);
+    expect(output).toContain(EFFECT_RECEIPTS_COMMENT_MARKER);
+    expect(receiptRows(output).seeded).toBeDefined();
+  });
+
+  it("leaves a real manifest applyable with the comment appended", () => {
+    const configMap = {
+      [DECLARABLE_MARKER]: true as const,
+      lexicon: "k8s",
+      entityType: "K8s::Core::ConfigMap",
+      props: { metadata: { name: "app-config" }, data: { a: "1" } },
+    };
+    const seeded = EffectReceipt("seeded", { effect: "db-seed", flavor: "existence" });
+    const out = k8sSerializer.serialize(
+      new Map<string, Declarable>([["appConfig", configMap as unknown as Declarable]]),
+      [],
+      { ownership, receipts: new Map<string, Declarable>([["seeded", seeded]]) },
+    );
+    const output = typeof out === "string" ? out : out.primary;
+    const documents = loadAll(output).filter((d): d is Record<string, unknown> => !!d && typeof d === "object");
+    expect(documents).toHaveLength(1);
+    expect((documents[0].metadata as { name: string }).name).toBe("app-config");
+    expect(receiptRows(output).seeded.name).toBe("chant-receipt.demo.dev.db-seed");
+  });
+
+  it("renders the existence expectation for an existence receipt", () => {
+    const r = EffectReceipt("booted", { effect: "bootstrap", flavor: "existence" });
+    const rows = receiptRows(serializeReceipts(new Map([["booted", r]]), ownership));
+    expect(rows.booted.data[RECEIPT_DATA_KEY]).toBe(EXISTENCE_EXPECTATION);
+  });
+
+  it("renders the placeholder note, never a placeholder digest, for reference inputs", () => {
+    const r = EffectReceipt("wired", { effect: "wire-up", flavor: "hash", inputs: { target: someRef } });
+    const rows = receiptRows(serializeReceipts(new Map([["wired", r]]), ownership));
+    expect(rows.wired.data[RECEIPT_DATA_KEY]).toBe(RECEIPT_UNRESOLVED_VALUE_NOTE);
+  });
+
+  it("errors when no ownership marker resolves", () => {
+    const r = EffectReceipt("seeded", { effect: "db-seed", flavor: "existence" });
+    expect(() => serializeReceipts(new Map([["seeded", r]]))).toThrow(/ownership/);
+  });
+
+  it("errors when ownership resolves no env, because the segment is explicit and never guessed", () => {
+    const r = EffectReceipt("seeded", { effect: "db-seed", flavor: "existence" });
+    expect(() => serializeReceipts(new Map([["seeded", r]]), { stack: "demo" })).toThrow(/env/);
+  });
+
+  it("emits no receipt block when the context carries no receipts", () => {
+    const out = k8sSerializer.serialize(new Map(), [], { ownership });
+    const output = typeof out === "string" ? out : out.primary;
+    expect(output).not.toContain(EFFECT_RECEIPTS_COMMENT_MARKER);
+    expect(parseReceiptComment(output)).toEqual({});
+  });
+
+  it("round-trips the block deterministically, and reads an output that has none as none", () => {
+    const rows = {
+      b: { kind: "ConfigMap" as const, namespace: "default", name: "chant-receipt.demo.dev.b", data: { expectation: "x" } },
+      a: { kind: "ConfigMap" as const, namespace: "default", name: "chant-receipt.demo.dev.a", data: { expectation: "y" } },
+    };
+    const line = renderReceiptComment(rows);
+    expect(line.indexOf('"a"')).toBeLessThan(line.indexOf('"b"'));
+    expect(parseReceiptComment(`${line}\n`)).toEqual(rows);
+    expect(parseReceiptComment("apiVersion: v1\nkind: Namespace\n")).toEqual({});
+    expect(parseReceiptComment(`${EFFECT_RECEIPTS_COMMENT_MARKER}not json\n`)).toEqual({});
+  });
+});
+
+describe("the receipt label", () => {
+  it("recognizes a live receipt ConfigMap by its label alone", () => {
+    expect(isEffectReceiptObject({ [RECEIPT_LABEL_KEY]: "db-seed" })).toBe(true);
+    expect(isEffectReceiptObject({ [RECEIPT_LABEL_KEY]: "" })).toBe(false);
+    expect(isEffectReceiptObject({ "app.kubernetes.io/managed-by": "chant" })).toBe(false);
+    expect(isEffectReceiptObject(undefined)).toBe(false);
+  });
+});
+
+describe("#1833's plain-store guard over the k8s row", () => {
+  const check = coreReceiptChecks().find((c) => c.id === RECEIPT_PLAIN_STORE_CHECK_ID)!;
+
+  function runCheck(entities: Map<string, Declarable>) {
+    const ctx: PostSynthContext = {
+      outputs: new Map(),
+      entities,
+      buildResult: { outputs: new Map(), entities, warnings: [], errors: [], sourceFileCount: 0 },
+    };
+    return check.check(ctx);
+  }
+
+  it("passes the factory's row, a plain ConfigMap", () => {
+    const r = EffectReceipt("seeded", { effect: "db-seed", flavor: "existence" });
+    expect(runCheck(new Map([["seeded", r]]))).toEqual([]);
+  });
+
+  it("fails a Secret-kind fixture, the same way it fails SSM SecureString", () => {
+    const sneaky = {
+      [DECLARABLE_MARKER]: true as const,
+      [EFFECT_RECEIPT_MARKER]: true as const,
+      lexicon: "k8s",
+      entityType: "K8s::Core::Secret",
+      name: "sneaky",
+      effect: "db-seed",
+      flavor: "existence" as const,
+      inputs: {},
+    };
+    const diagnostics = runCheck(new Map([["sneaky", sneaky as unknown as Declarable]]));
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].checkId).toBe(RECEIPT_PLAIN_STORE_CHECK_ID);
+    expect(diagnostics[0].severity).toBe("error");
+    expect(diagnostics[0].message).toMatch(/K8s::Core::Secret/);
+  });
+});
+
+describe("#1833's leaf rule over a ConfigMap receipt", () => {
+  /** The k8s source fixture: the row's own factory, referenced the way COR022
+   * refuses. Recognition is by factory name, so the rule fires here exactly as
+   * it fires on the aws SSM row. */
+  function lintContext(code: string): LintContext {
+    const sourceFile = ts.createSourceFile("infra.ts", code, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    return { sourceFile, entities: [], filePath: "infra.ts", lexicon: "k8s" };
+  }
+
+  it("fires when a ConfigMap derives a value from the receipt", () => {
+    const diags = cor022ReceiptLeafRule.check(
+      lintContext(`
+        import { EffectReceipt, ConfigMap } from "@intentius/chant-lexicon-k8s";
+        export const seeded = EffectReceipt("seeded", { effect: "db-seed", flavor: "existence" });
+        export const app = new ConfigMap({ data: { seededBy: seeded.effect } });
+      `),
+    );
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("COR022");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].message).toContain('"seeded" is an effect receipt');
+  });
+
+  it("passes when the receipt is only handed to the effect() step whole", () => {
+    const diags = cor022ReceiptLeafRule.check(
+      lintContext(`
+        import { EffectReceipt } from "@intentius/chant-lexicon-k8s";
+        export const seeded = EffectReceipt("seeded", { effect: "db-seed", flavor: "existence" });
+        export const migrate = effect(seeded, [shell({ run: "./seed.sh" })]);
+      `),
+    );
+    expect(diags).toEqual([]);
+  });
+});

package/src/effect-receipt-row.ts

@@ -0,0 +1,268 @@
+/**
+ * The k8s effect-receipt materialization row (#2074, epic #1703): an effect
+ * receipt stored as a core `ConfigMap`, named
+ * `chant-receipt.<stack>.<env>.<effect>`, holding the expectation under
+ * `data.expectation`.
+ *
+ * Core's `EffectReceipt` factory (#1831) declares a receipt under the `chant`
+ * pseudo-lexicon, which no serializer claims. This module is the k8s
+ * materialization, built to the same shape as the aws SSM row (#1835,
+ * `lexicons/aws/src/effect-receipt-row.ts`): the {@link EffectReceipt} factory
+ * here produces core's declaration under `lexicon: "k8s"`, so the build
+ * partitions it to the k8s serializer, #1832's write-exclusion seam withholds
+ * it from the apply-bound entity set, and the serializer renders it for
+ * visibility through `SerializeContext.receipts` (see ./serializer.ts).
+ *
+ * Where the aws row parks its rendered rows in the CloudFormation template's
+ * `Metadata` (deliberately outside `Resources`, the section an applier writes
+ * from), this row parks them in a YAML COMMENT at the end of the manifest
+ * stream. Kubernetes YAML has no metadata channel outside the documents
+ * themselves, and a document is exactly what an applier applies: `loadAll`
+ * yields no object for a comment, so the receipt block is structurally
+ * unreachable from `applyManifest` while still riding the one build output the
+ * observation leg is handed. See {@link EFFECT_RECEIPTS_COMMENT_MARKER}.
+ *
+ * ## Name and namespace
+ *
+ * Path identity (epic decision 4): the ConfigMap name derives from the SAME
+ * ownership-block fields that stamp markers, `ownership.stack` and an explicit
+ * `ownership.env`, plus the receipt's `effect`. The separator is `.`, which no
+ * segment may contain, so `stack=a-b env=c` and `stack=a env=b-c` cannot
+ * produce the same name. The result is a valid RFC 1123 DNS subdomain, which
+ * is what a ConfigMap name has to be.
+ *
+ * The namespace is the project's `k8s.receipts.namespace`, and `default` when
+ * the project sets none, which is where every other namespace-less k8s read
+ * and write in this lexicon already lands. It is never invented from the stack
+ * or the environment: a namespace chant guessed would be a namespace chant has
+ * to create, and the receipt row creates nothing but the receipt.
+ *
+ * ## Ownership, and why the prune leaves it alone
+ *
+ * Every receipt ConfigMap carries chant's ownership marker labels plus
+ * {@link RECEIPT_LABEL_KEY}. The marker is what makes `chant kube get` and the
+ * observation classify it as chant's rather than foreign. The receipt label is
+ * what keeps `delete: "owned-only"` from pruning it: the receipt is owned and
+ * is never in any apply set (the effect step is its sole writer), which is the
+ * exact shape the owned-only sweep deletes. `pruneOrphans`
+ * (./op/activities/kubectl.ts) reports it `retained` instead, the same
+ * treatment a generated-once Secret gets (./secret-labels.ts) and for the same
+ * reason: destroying it silently converts at-least-once into a re-run nobody
+ * asked for, or worse, into never.
+ *
+ * Plain store (#1833's COR023): a ConfigMap is the plain half of the
+ * ConfigMap/Secret pair, and the entityType alone is what the guard reads. A
+ * receipt value is a witness (an existence marker or a `sha256:` digest),
+ * never a secret; materializing one into a `K8s::Core::Secret` fails COR023.
+ */
+
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import {
+  EffectReceipt as CoreEffectReceipt,
+  EFFECT_RECEIPT_MARKER,
+  type EffectReceiptFlavor,
+  type EffectReceiptOptions,
+} from "@intentius/chant/effect-receipt";
+
+/** The entityType of the k8s materialization row, the real resource kind the
+ * receipt is stored as, which is what lint's plain-store guard checks. */
+export const K8S_EFFECT_RECEIPT_ENTITY_TYPE = "K8s::Core::ConfigMap";
+
+/** apiVersion/kind of the materialized row, for the client reads and writes. */
+export const RECEIPT_CONFIGMAP_REF = { apiVersion: "v1", kind: "ConfigMap" } as const;
+
+/**
+ * The line prefix the serializer renders receipt rows behind, and the
+ * observation leg reads them back from. A YAML comment: an applier's `loadAll`
+ * produces no document for it, so a receipt can never enter an apply set, and
+ * `kubectl apply -f` ignores it exactly as it ignores every other comment.
+ * The remainder of the line is one JSON object keyed by entity name.
+ */
+export const EFFECT_RECEIPTS_COMMENT_MARKER = "# chant:effect-receipts ";
+
+/** First segment of every receipt ConfigMap name. */
+export const RECEIPT_NAME_PREFIX = "chant-receipt";
+
+/** The `data` key the expectation is stored under. One key, the same single
+ * value the aws row puts in the SSM parameter's `Value`. */
+export const RECEIPT_DATA_KEY = "expectation";
+
+/** The label a live receipt ConfigMap carries, valued with the effect it
+ * witnesses. Recognition for the observation leg and, more importantly, the
+ * exclusion the owned-only prune keys on. */
+export const RECEIPT_LABEL_KEY = "chant.intentius.io/effect-receipt";
+
+/** Where receipts live when the project names no namespace. */
+export const RECEIPT_DEFAULT_NAMESPACE = "default";
+
+/**
+ * The rendered value of a hash-flavor receipt that still carries reference
+ * inputs at synthesis. References resolve at plan and at run, never at
+ * synthesis (epic decision 5), so the row carries this note instead of a
+ * digest hashed over placeholders.
+ */
+export const RECEIPT_UNRESOLVED_VALUE_NOTE =
+  "unresolved at synthesis, reference inputs; the expectation resolves at plan and at run (chant #1703, decision 5)";
+
+/** One segment of the receipt name. RFC 1123 DNS label, which is what each
+ * dot-separated piece of a ConfigMap name has to be, and the `.` separator is
+ * excluded from it so the identity stays unambiguous. */
+const NAME_SEGMENT = /^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/;
+
+/** Kubernetes' own ceiling on a DNS subdomain, which a ConfigMap name is. */
+const MAX_NAME_LENGTH = 253;
+
+function checkSegment(field: string, value: string): string {
+  if (value.length > 63 || !NAME_SEGMENT.test(value)) {
+    throw new Error(
+      `receipt name: ${field} "${value}" is not a valid DNS-1123 label, ` +
+        `use lowercase letters, digits and "-" (the segment becomes one dot-separated piece of ` +
+        `${RECEIPT_NAME_PREFIX}.<stack>.<env>.<effect>, which must be a valid ConfigMap name)`,
+    );
+  }
+  return value;
+}
+
+/**
+ * The ConfigMap name of one effect's receipt:
+ * `chant-receipt.<stack>.<env>.<effect>`, from the resolved ownership marker
+ * fields (epic decision 4). The single source of the name identity: the
+ * serializer's rendered row, the receipt store's reads and writes, and the
+ * observation leg all call this.
+ */
+export function receiptConfigMapName(stack: string, env: string, effect: string): string {
+  const name = `${RECEIPT_NAME_PREFIX}.${checkSegment("stack", stack)}.${checkSegment("env", env)}.${checkSegment("effect", effect)}`;
+  if (name.length > MAX_NAME_LENGTH) {
+    throw new Error(
+      `receipt name: "${name}" is ${name.length} characters, over Kubernetes' ${MAX_NAME_LENGTH}-character ` +
+        `limit for a ConfigMap name. Shorten the stack, the environment, or the effect.`,
+    );
+  }
+  return name;
+}
+
+/** The project's receipt namespace: `k8s.receipts.namespace`, else `default`.
+ * The serializer reads it off `SerializeContext.config` and the store reads it
+ * off the project config, so both derive one namespace from one setting. */
+export function receiptNamespaceFrom(config: Record<string, unknown> | undefined): string {
+  const k8s = config?.k8s as { receipts?: { namespace?: unknown } } | undefined;
+  const declared = k8s?.receipts?.namespace;
+  return typeof declared === "string" && declared.length > 0 ? declared : RECEIPT_DEFAULT_NAMESPACE;
+}
+
+/** Name and namespace of one effect's receipt ConfigMap. */
+export interface ReceiptConfigMapRef {
+  name: string;
+  namespace: string;
+}
+
+/** The full address of one effect's receipt ConfigMap. */
+export function receiptConfigMapRef(
+  stack: string,
+  env: string,
+  effect: string,
+  namespace: string = RECEIPT_DEFAULT_NAMESPACE,
+): ReceiptConfigMapRef {
+  return { name: receiptConfigMapName(stack, env, effect), namespace };
+}
+
+/** True when a live object's labels mark it a chant effect receipt. Any
+ * non-empty value counts: the label's presence is the claim, and a sweep must
+ * err on the side of keeping. */
+export function isEffectReceiptObject(labels: Record<string, unknown> | undefined): boolean {
+  const value = labels?.[RECEIPT_LABEL_KEY];
+  return typeof value === "string" && value.length > 0;
+}
+
+/** One rendered receipt row, as the comment block carries it. */
+export interface RenderedReceiptRow {
+  kind: typeof RECEIPT_CONFIGMAP_REF.kind;
+  namespace: string;
+  name: string;
+  data: Record<string, string>;
+}
+
+/**
+ * Render the receipt block the serializer appends to the manifest stream.
+ * Deterministic: one line, entity names sorted.
+ */
+export function renderReceiptComment(rows: Record<string, RenderedReceiptRow>): string {
+  const sorted: Record<string, RenderedReceiptRow> = {};
+  for (const name of Object.keys(rows).sort()) sorted[name] = rows[name];
+  return `${EFFECT_RECEIPTS_COMMENT_MARKER}${JSON.stringify(sorted)}`;
+}
+
+/**
+ * Read the receipt rows back out of a build output. Returns an empty record
+ * for an output that carries no block, which is every project that declares no
+ * receipt. Never throws: an unparseable block is no block, and the observation
+ * leg reports the receipts it could not address as absent rather than
+ * inventing one.
+ */
+export function parseReceiptComment(buildOutput: string): Record<string, RenderedReceiptRow> {
+  const start = buildOutput.lastIndexOf(EFFECT_RECEIPTS_COMMENT_MARKER);
+  if (start < 0) return {};
+  const end = buildOutput.indexOf("\n", start);
+  const line = buildOutput.slice(start + EFFECT_RECEIPTS_COMMENT_MARKER.length, end < 0 ? undefined : end);
+  try {
+    const parsed = JSON.parse(line) as unknown;
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {};
+    return parsed as Record<string, RenderedReceiptRow>;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * A k8s-materialized effect receipt: core's declaration shape (so
+ * `isEffectReceipt`, `effect(...)`, lint, and the plan engine all recognize it
+ * through the marker), under the k8s lexicon and the real resource kind.
+ */
+export interface K8sEffectReceiptDeclaration extends Declarable {
+  readonly [EFFECT_RECEIPT_MARKER]: true;
+  readonly lexicon: "k8s";
+  readonly entityType: typeof K8S_EFFECT_RECEIPT_ENTITY_TYPE;
+  /** The receipt's own name (the export-level identity of the witness). */
+  readonly name: string;
+  /** The effect this receipt witnesses, the name's final segment. */
+  readonly effect: string;
+  /** How the receipt is compared: mere presence, or a digest of the inputs. */
+  readonly flavor: EffectReceiptFlavor;
+  /** The effect's inputs as recorded at synthesis (references as placeholders). */
+  readonly inputs: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Declare a k8s-materialized effect receipt. Same signature and semantics as
+ * core's `EffectReceipt` (#1831), whose factory validates and freezes the
+ * options, but the declaration lands in the k8s partition, so the k8s
+ * serializer renders the ConfigMap row and the receipt store
+ * (./receipt-store.ts) is its writer. Pass the returned const straight to the
+ * `effect(...)` op step.
+ */
+export function EffectReceipt(name: string, options: EffectReceiptOptions): K8sEffectReceiptDeclaration {
+  // Fail at declaration, not at serialize: the effect is the name's final
+  // segment, and a name that cannot become a segment has no receipt address.
+  if (typeof options?.effect === "string" && options.effect.length > 0) {
+    checkSegment("effect", options.effect);
+  }
+  const core = CoreEffectReceipt(name, options);
+  const decl: K8sEffectReceiptDeclaration = {
+    [DECLARABLE_MARKER]: true,
+    [EFFECT_RECEIPT_MARKER]: true,
+    lexicon: "k8s",
+    entityType: K8S_EFFECT_RECEIPT_ENTITY_TYPE,
+    name: core.name,
+    effect: core.effect,
+    flavor: core.flavor,
+    // The same frozen structure the core factory built: intrinsic inputs stay
+    // live so discovery can stamp logical names onto attr-refs.
+    inputs: core.inputs,
+  };
+  // Declared fields immutable, object extensible for discovery's own
+  // symbol-keyed metadata, the same lock the core factory applies.
+  for (const key of Object.keys(decl)) {
+    Object.defineProperty(decl, key, { writable: false, configurable: false });
+  }
+  return decl;
+}

package/src/index.ts

@@ -27,6 +27,28 @@ export { DEFAULT_LABELS_MARKER, DEFAULT_ANNOTATIONS_MARKER } from "./default-lab
 // Variables / label constants
 export { K8sLabels, K8sAnnotations } from "./variables";
 
+// Effect receipts (#2074, epic #1703): the k8s materialization row, meaning the
+// factory a project declares (core's shape under the k8s lexicon, carrying
+// the marker) and the name/label constants. The ConfigMap-backed store itself
+// lives at the `/receipt-store` subpath, off the build path (#1074).
+export {
+  EffectReceipt,
+  receiptConfigMapName,
+  receiptConfigMapRef,
+  receiptNamespaceFrom,
+  isEffectReceiptObject,
+  K8S_EFFECT_RECEIPT_ENTITY_TYPE,
+  EFFECT_RECEIPTS_COMMENT_MARKER,
+  RECEIPT_NAME_PREFIX,
+  RECEIPT_DATA_KEY,
+  RECEIPT_LABEL_KEY,
+  RECEIPT_DEFAULT_NAMESPACE,
+  RECEIPT_UNRESOLVED_VALUE_NOTE,
+  parseReceiptComment,
+  renderReceiptComment,
+} from "./effect-receipt-row";
+export type { K8sEffectReceiptDeclaration, ReceiptConfigMapRef, RenderedReceiptRow } from "./effect-receipt-row";
+
 // Generated-once secret marker (#1830) — constants only; the store adapter
 // itself lives at the `/secret-store` subpath, off the build path (#1074).
 export { GENERATED_ONCE_LABEL_KEY, GENERATED_ONCE_LABEL_VALUE, isGeneratedOnce } from "./secret-labels";

package/src/lint/audit-catalog.ts

@@ -45,7 +45,7 @@ export const k8sAuditCatalog: Record<string, RuleMeta> = {
   WK8502: auditRule("WK8502", "merge-worthy", "guidance", "Custom resource spec field has the wrong type or enum value", "Match the CRD schema: use the declared scalar type and one of the enum values.", { category: "correctness" }),
   WK8503: auditRule("WK8503", "merge-worthy", "guidance", "Workload consumes a Secret nothing in the output produces", "Produce the Secret in the same build (Secret, ExternalSecret, InfisicalSecret, cert-manager Certificate), or declare its provenance with declareSecret() if it exists out of band.", { category: "correctness" }),
   WK8504: auditRule("WK8504", "merge-worthy", "guidance", "committed-encrypted secret declaration does not resolve", "Point `file` at the committed ciphertext, make its metadata.name match the declaration, and re-run `sops -e -i` so every data/stringData value is ENC[...].", { authority: [K8S_SECRETS] }),
-  WK8505: auditRule("WK8505", "report-only", "guidance", "committed-encrypted secret with no Flux decryption wiring", "Add decryption: \"sops\" to the FluxAppFor reconciling the path that carries the ciphertext sidecar, or ignore if that Kustomization is declared in a different build.", { category: "correctness" }),
+  WK8505: auditRule("WK8505", "report-only", "guidance", "committed-encrypted secret with no Flux decryption wiring", "Add decryption: \"sops\" to the FluxAppFor reconciling the path that carries the ciphertext sidecar, or ignore if that Kustomization is declared in a different build. This check sees one build root at a time, so it goes silent once the secret and the Kustomization live in different build roots (chant #1939).", { category: "correctness" }),
 };
 
 // Prior art credits live beside the rules in ./audit-lineage.ts (see core audit/prior-art.ts).