@intentius/chant-lexicon-k8s 0.58.0 → 0.60.0

package/dist/receipt-store.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The k8s `ReceiptStore` (#2074, epic #1703): core's injectable receipt seam
+ * (#1834, `@intentius/chant/op/receipt-store`) implemented over a core
+ * `ConfigMap`, at the address ./effect-receipt-row.ts derives from the
+ * ownership marker fields, plus the plan-side live read of the same rows.
+ *
+ * The transport is the lexicon's own typed client (./api/connect.ts), so a
+ * receipt read and write take the same environment-to-cluster binding
+ * (#1100/#1155), the same credential policy and the same field manager as
+ * every other k8s mutation. No `kubectl` binary is involved.
+ *
+ * Write discipline (epic decision 3): `write` exists for the `effect()` step
+ * alone, because the step's read-compare-run-write is the only path that reaches it,
+ * on success, last. It is a server-side apply as `chant:<stack>`, stamping the
+ * ownership marker labels and {@link RECEIPT_LABEL_KEY}, so a later write
+ * updates the value in place and the owned-only prune retains rather than
+ * deletes it (./op/activities/kubectl.ts).
+ *
+ * Identity: the ConfigMap name needs `<stack>` and `<env>`, which the activity
+ * args deliberately do not carry (the `EffectReceiptRef` is
+ * identity-of-the-effect, not identity-of-the-deployment). The store resolves
+ * them once, lazily, at first use: an explicit option, else `CHANT_ENV` (what
+ * `chant run --env` sets) and the project's `ownership` block, the same fields
+ * that stamp markers (epic decision 4). Nothing resolving is an error, never a
+ * guessed segment.
+ *
+ * Not exported from the package entry point. Like ./secret-store.ts and
+ * ./teardown.ts, this module names the API client, which must stay off the
+ * build path (chant #1074, examples/k8s-client-boundary.test.ts). Consumers
+ * reach it by subpath: `@intentius/chant-lexicon-k8s/receipt-store`.
+ */
+import type { ReceiptStore } from "@intentius/chant/op/receipt-store";
+import type { ResourceMetadata, UnobservedEntity } from "@intentius/chant/lexicon";
+import type { DeepResourceObservation } from "@intentius/chant/deep-observation";
+import type { K8sClient, K8sObject } from "@intentius/chant-k8s-client";
+import { type K8sConnector } from "./api/connect.js";
+import { type RenderedReceiptRow } from "./effect-receipt-row.js";
+/** Options for {@link k8sReceiptStore}. All optional: the default store reads
+ * its identity and its namespace from the project, and its cluster from the
+ * environment binding. */
+export interface K8sReceiptStoreOptions {
+    /** The name's `<stack>` segment. Omitted, the project's `ownership.stack`
+     * (chant.config.ts, found upward from `cwd`) answers. */
+    stack?: string;
+    /** The name's `<env>` segment, explicit by decision 4. Omitted, `CHANT_ENV`
+     * (set by `chant run --env`) answers, then a literal `ownership.env`. */
+    environment?: string;
+    /** Namespace the receipts live in. Omitted, `k8s.receipts.namespace`
+     * answers, then `default`. */
+    namespace?: string;
+    /** Where to look for chant.config.ts. Defaults to the working directory. */
+    cwd?: string;
+    /** Explicit kubectl context, for a caller that already resolved one. */
+    context?: string;
+    /** The connector to build a client with. Test seam. */
+    connect?: K8sConnector;
+    /** Environment record the identity fallback reads. Defaults to `process.env`. */
+    env?: Record<string, string | undefined>;
+}
+/** The stored expectation on a live receipt ConfigMap, or undefined when the
+ * object holds none. */
+export declare function receiptValueOf(object: K8sObject | undefined): string | undefined;
+/**
+ * The `ReceiptStore` over ConfigMaps. Bind it once in the op activities barrel
+ * as `receiptActivities(k8sReceiptStore())`, and the registry resolves
+ * `receiptRead`/`receiptWrite`/`receiptStaleness` by name, exactly like
+ * `ensureSecret` (#1830). Identity and cluster resolve lazily at first use, so
+ * module load never reads the project or connects to anything.
+ */
+export declare function k8sReceiptStore(options?: K8sReceiptStoreOptions): ReceiptStore;
+/** What the observation leg learned about the declared receipt rows. */
+export interface ReceiptRowObservation {
+    resources: Record<string, ResourceMetadata>;
+    unobserved: Record<string, UnobservedEntity>;
+}
+/** The receipt rows a build output carries, keyed by entity name. Only the
+ * entities this observation was asked about. */
+export declare function receiptRowsFor(entityNames: readonly string[], buildOutput: string | undefined): Map<string, RenderedReceiptRow>;
+/**
+ * The plan-side live read of the receipt rows (#2074's observation leg).
+ *
+ * A receipt is not a document the applier ever wrote (#1832), and it carries
+ * no `props` on the declared side, so the generic declared-entity sweep in
+ * ./describe-resources.ts has neither a `metadata.name` to query by nor an
+ * honest verdict to give. The serializer rendered each receipt's derived
+ * ConfigMap address into the build output's receipt comment, so this leg reads
+ * the addresses back from there, one derivation, decision 4, and asks the
+ * cluster for each.
+ *
+ * Present maps the stored value onto `attributes.value` (core's
+ * `RECEIPT_VALUE_ATTRIBUTE`); a genuine 404 is a real absence and stays one; a
+ * failed read is an `unobserved` hole, never a wrong answer: a receipt nobody
+ * could read must not arrive downstream as "the effect never ran".
+ */
+export declare function observeReceiptRows(client: K8sClient, rows: ReadonlyMap<string, RenderedReceiptRow>): Promise<ReceiptRowObservation>;
+/**
+ * The deep read's answer for the receipt rows.
+ *
+ * A receipt is read back here for the same reason the thin path reads it: a
+ * declared entity nobody looked at is a hole, and a hole in the deep read is
+ * noise on every `lifecycle diff --live --deep` a project with receipts runs.
+ * What it deliberately contributes is an EMPTY property tree: the declaration
+ * has no `props`, so every live path would land outside the claimed-field set
+ * (`@intentius/chant/claimed-fields`) and be reported unclaimed, and the
+ * receipt's stored value is not drift on any reading, because a stale receipt is an
+ * `effect` row from `planReceipts` (#1832), never an update. Presence and the
+ * uid are the whole of what the deep read has to say about a receipt.
+ */
+export declare function observeReceiptRowsDeep(client: K8sClient, rows: ReadonlyMap<string, RenderedReceiptRow>): Promise<{
+    resources: Record<string, DeepResourceObservation>;
+    unobserved: Record<string, UnobservedEntity>;
+}>;
+//# sourceMappingURL=receipt-store.d.ts.map

package/dist/receipt-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt-store.d.ts","sourceRoot":"","sources":["../src/receipt-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AASH,OAAO,KAAK,EAAoB,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AACjF,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAEvE,OAAO,EAQL,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAE9B;;0BAE0B;AAC1B,MAAM,WAAW,sBAAsB;IACrC;6DACyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;6EACyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;kCAC8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,iFAAiF;IACjF,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC1C;AA+CD;wBACwB;AACxB,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAIhF;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,YAAY,CAuClF;AAED,wEAAwE;AACxE,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC5C,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC9C;AAED;gDACgD;AAChD,wBAAgB,cAAc,CAC5B,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAUjC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAC5C,OAAO,CAAC,qBAAqB,CAAC,CAsChC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAC5C,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;CAAE,CAAC,CAW/G"}

package/dist/rules/wk8505.ts

@@ -15,7 +15,9 @@
  * invocations, so "no Kustomization in THIS build sets spec.decryption" can
  * mean "wired up in the other build" as easily as "forgotten" — the design
  * doc's §4 explains why no path-to-build-target join exists to tell those
- * apart. Promote to error if that join ever becomes available.
+ * apart. Single-build-root scoped, tracked by chant #1939 as a candidate for
+ * an opt-in project-level mode; promote to error if that join ever becomes
+ * available.
  *
  * Fires only on claims that actually resolved (`problems.length === 0`, via
  * `resolveEncryptedSecretClaims`), not on every raw declaration. An
@@ -39,7 +41,7 @@ function fluxKustomizations(manifests: K8sManifest[]): K8sManifest[] {
 export const wk8505: PostSynthCheck = {
   id: "WK8505",
   description:
-    "committed-encrypted secret with no Flux decryption wiring — add decryption: 'sops' to the FluxAppFor reconciling the path that carries it",
+    "committed-encrypted secret with no Flux decryption wiring — add decryption: 'sops' to the FluxAppFor reconciling the path that carries it. Sees one build root at a time, so it goes silent when that Kustomization lives in a different build root (chant #1939).",
 
   check(ctx: PostSynthContext): PostSynthDiagnostic[] {
     const kustomizations = fluxKustomizations(allManifests(ctx));

package/dist/serializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAsC,MAAM,6BAA6B,CAAC;AA+MlG;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,UAiN3B,CAAC"}
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAsC,MAAM,6BAA6B,CAAC;AAyRlG;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,UAkO3B,CAAC"}

package/dist/subscribe-changes.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The k8s change signal, `LexiconPlugin.subscribeChanges` (chant #1981).
+ *
+ * Kubernetes is the one substrate chant reaches where a change stream is
+ * complete, trustworthy, and needs nothing deployed into the cluster being
+ * observed: the Watch API is served for every kind the API server serves, is
+ * `resourceVersion`-based so a reconnect has a defined resume point, and is
+ * authorized by the same read credentials `describeResources` already uses.
+ * Every cloud substrate fails on that last point. Subscribing to EventBridge,
+ * Cloud Asset Inventory or Event Grid means writing infrastructure into the
+ * account being watched, which inverts the property that makes a read-only
+ * watch safe to point at production. The verdict table in the operator guide
+ * records that per lexicon; this file is the one place it came out `yes`.
+ *
+ * ## What this is allowed to conclude: nothing
+ *
+ * A watch event never becomes an observation. The frames are read, and then
+ * discarded. The only thing that leaves this module is a no-argument
+ * `onChange()`, which wakes an operator tick that re-observes the estate from
+ * scratch through the ordinary read path. There is no code here that could
+ * turn a `DELETED` frame into a proposed `create`, because there is no channel
+ * from a frame to anything but a function call with no parameters.
+ *
+ * That is also why a missed event costs nothing. A `410 Gone`, a dropped
+ * connection, a subscription that never got established: all of them slow
+ * detection back to the operator's timer, and none of them make the estate
+ * read as clean.
+ *
+ * ## Scope
+ *
+ * One watch per (kind, namespace) the declared entities name. The kinds come
+ * from the same generated operation surface `describeResources` addresses
+ * entities through; the namespaces come from the declarations themselves,
+ * falling back to the client's own default for a namespaced entity that
+ * declares none. Nothing widens that: a project declaring three Deployments in
+ * one namespace opens one connection, not a cluster-wide firehose.
+ */
+import type { ChangeSubscription, SubscribeChangesOptions } from "@intentius/chant/lexicon";
+import { type K8sConnector } from "./api/connect.js";
+/**
+ * The most connections one subscription will hold open.
+ *
+ * A watch is a long-lived HTTP/2 stream against the API server, and one per
+ * (kind, namespace) is cheap right up until an estate declares eighty kinds
+ * across a dozen namespaces. Past this ceiling the honest move is to refuse
+ * the whole subscription and say so, rather than to open some arbitrary
+ * prefix of it: a partial watch is a signal that goes quiet for exactly the
+ * resources nobody chose to drop. The operator then runs on its timer, which
+ * is what it did before this existed.
+ */
+export declare const MAX_WATCHES = 32;
+/** One thing to watch: a kind, and the namespace to watch it in. */
+interface WatchTarget {
+    apiVersion: string;
+    kind: string;
+    /** Absent for a cluster-scoped kind. */
+    namespace?: string;
+}
+/**
+ * The distinct (kind, namespace) pairs a declared estate implies.
+ *
+ * Deterministic order, so a refusal past {@link MAX_WATCHES} names the same
+ * scope every time and a test can assert on it.
+ */
+export declare function watchTargets(entities: Map<string, {
+    entityType: string;
+    props: Record<string, unknown>;
+}>, defaultNamespace: string): {
+    targets: WatchTarget[];
+    unaddressable: string[];
+};
+/**
+ * Open one watch per declared (kind, namespace) and report every event as a
+ * bare `onChange()`.
+ *
+ * Throws only for a failure that makes the whole subscription impossible: no
+ * entities in scope, a cluster binding that will not resolve, a scope past the
+ * ceiling. The operator turns that into one logged line and keeps polling.
+ * Once the subscription is live, nothing throws: a watch that dies reports
+ * through `onError` and the operator re-subscribes on its next round.
+ */
+export declare function subscribeChanges(options: SubscribeChangesOptions, connect?: K8sConnector): Promise<ChangeSubscription>;
+export {};
+//# sourceMappingURL=subscribe-changes.d.ts.map

package/dist/subscribe-changes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscribe-changes.d.ts","sourceRoot":"","sources":["../src/subscribe-changes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAE5F,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAGvE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,KAAK,CAAC;AAE9B,oEAAoE;AACpE,UAAU,WAAW;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,EAC7E,gBAAgB,EAAE,MAAM,GACvB;IAAE,OAAO,EAAE,WAAW,EAAE,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAE,CAkCrD;AAOD;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,EAChC,OAAO,GAAE,YAAkC,GAC1C,OAAO,CAAC,kBAAkB,CAAC,CAkF7B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-k8s",
-  "version": "0.58.0",
+  "version": "0.60.0",
   "description": "Kubernetes lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -76,7 +76,7 @@
     "@types/js-yaml": "^4.0.9"
   },
   "optionalDependencies": {
-    "@intentius/chant-k8s-client": "^0.58.0"
+    "@intentius/chant-k8s-client": "^0.60.0"
   },
   "devDependencies": {
     "@intentius/chant": "*",
@@ -84,7 +84,7 @@
   },
   "peerDependencies": {
     "zod": "^4.3.6",
-    "@intentius/chant": "^0.58.0",
+    "@intentius/chant": "^0.60.0",
     "typescript": "^5.9.3"
   }
 }

package/src/api/fake-cluster.ts

@@ -15,7 +15,7 @@
 
 import type { K8sObject } from "@intentius/chant-k8s-client";
 import { apiResourceList, fakeKubeconfig, fakeRequestLayer, statusBody } from "@intentius/chant-k8s-client/testing";
-import type { FakeRequestLayer, RecordedRequest } from "@intentius/chant-k8s-client/testing";
+import type { FakeRequestLayer, FakeResponse, RecordedRequest } from "@intentius/chant-k8s-client/testing";
 import { createK8sClient } from "@intentius/chant-k8s-client";
 import type { ConnectedClient, ConnectOptions, K8sConnector } from "./connect";
 import { operationTable } from "./operation-surface";
@@ -33,8 +33,12 @@ export interface FakeClusterOptions {
    * CRD resolvable in a test without registering anything.
    */
   serves?: readonly string[];
-  /** Full control: return a response for a request, or undefined to fall through. */
-  respond?: (request: RecordedRequest) => { status?: number; body?: unknown } | undefined;
+  /**
+   * Full control: return a response for a request, or undefined to fall
+   * through. A `stream` on the response is what a watch reads (chant #1981);
+   * see `fakeWatchStream` in the client's testing harness.
+   */
+  respond?: (request: RecordedRequest) => FakeResponse | undefined;
   /** Kubeconfig to hand the client. Defaults to a single-context one. */
   kubeconfig?: string;
 }
@@ -177,7 +181,16 @@ export function fakeCluster(options: FakeClusterOptions = {}): FakeCluster {
     if (object) return { body: object };
 
     if (isListPath(request.path, resources)) {
-      return { body: { kind: "List", items: listPaths.get(request.path) ?? [], metadata: {} } };
+      // A `resourceVersion` on every list: it is what a watch resumes from
+      // (chant #1981), and a list without one is not a shape any API server
+      // produces.
+      return {
+        body: {
+          kind: "List",
+          items: listPaths.get(request.path) ?? [],
+          metadata: { resourceVersion: "1" },
+        },
+      };
     }
 
     return { status: 404, body: statusBody(404, "NotFound", `${request.path} not found`) };

package/src/codegen/docs.ts

@@ -87,6 +87,13 @@ The generated file includes:
 - \`metadata.name\` auto-generated from export names (camelCase → kebab-case)
 - Default labels and annotations injected from \`defaultLabels()\`/\`defaultAnnotations()\`
 
+The lexicon also materializes [effect receipts](/chant/concepts/effect-receipts/) as
+ConfigMaps named \`chant-receipt.<stack>.<env>.<effect>\` in \`k8s.receipts.namespace\`
+(\`default\` when unset), holding the expectation under \`data.expectation\`. A receipt is
+never a document in the manifest stream: the rows ride a trailing
+\`# chant:effect-receipts\` comment, which \`kubectl apply\` ignores, because the
+\`effect()\` step is a receipt's sole writer.
+
 ## Key conversions
 
 | Chant (TypeScript) | YAML output | Rule |

package/src/composites/composites.test.ts

@@ -340,6 +340,32 @@ describe("CronWorkload", () => {
     expect((p(result.role).metadata as any).labels["app.kubernetes.io/component"]).toBe("rbac");
     expect((p(result.roleBinding).metadata as any).labels["app.kubernetes.io/component"]).toBe("rbac");
   });
+
+  // ── schedule validation (#2071 item 4) ────────────────────────────
+
+  test("accepts a valid five-field schedule", () => {
+    expect(() =>
+      CronWorkload({ name: "backup", image: "backup:1.0", schedule: "0 2 * * *" }),
+    ).not.toThrow();
+  });
+
+  test("refuses a 6-field (seconds) schedule, naming the field, the value, and the CronJob limit", () => {
+    expect(() =>
+      CronWorkload({ name: "backup", image: "backup:1.0", schedule: "0 0 2 * * *" }),
+    ).toThrow(/schedule "0 0 2 \* \* \*" is 6-field cron.*five fields/s);
+  });
+
+  test("refuses a malformed schedule", () => {
+    expect(() =>
+      CronWorkload({ name: "backup", image: "backup:1.0", schedule: "not a cron" }),
+    ).toThrow(/schedule "not a cron" is not valid cron syntax/);
+  });
+
+  test("refuses a blank schedule", () => {
+    expect(() =>
+      CronWorkload({ name: "backup", image: "backup:1.0", schedule: "" }),
+    ).toThrow(/schedule is required/);
+  });
 });
 
 // ── AutoscaledService ──────────────────────────────────────────────
@@ -4016,7 +4042,39 @@ describe("OperatorStack", () => {
         image: "chant:latest",
         converge: [{ name: "fountain-observe", schedule: "", env: "staging" }],
       }),
-    ).toThrow(/schedule/);
+    ).toThrow(/schedule is required/);
+  });
+
+  // ── schedule validation (#2071 item 4) ────────────────────────────
+
+  test("accepts a valid five-field schedule", () => {
+    expect(() =>
+      OperatorStack({
+        name: "chant-operator",
+        image: "chant:latest",
+        converge: [{ name: "fountain-observe", schedule: "*/10 * * * *", env: "staging" }],
+      }),
+    ).not.toThrow();
+  });
+
+  test("refuses a host with a 6-field (seconds) schedule, naming the field, the value, and the CronJob limit", () => {
+    expect(() =>
+      OperatorStack({
+        name: "chant-operator",
+        image: "chant:latest",
+        converge: [{ name: "fountain-observe", schedule: "0 */10 * * * *", env: "staging" }],
+      }),
+    ).toThrow(/schedule "0 \*\/10 \* \* \* \*" is 6-field cron.*five fields/s);
+  });
+
+  test("refuses a host with a malformed schedule", () => {
+    expect(() =>
+      OperatorStack({
+        name: "chant-operator",
+        image: "chant:latest",
+        converge: [{ name: "fountain-observe", schedule: "not a cron", env: "staging" }],
+      }),
+    ).toThrow(/schedule "not a cron" is not valid cron syntax/);
   });
 
   test("refuses a blank image", () => {

package/src/composites/cron-schedule.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared CronJob schedule validation (issue #2071 item 4).
+ *
+ * `OperatorStack` and `CronWorkload` both hand their `schedule` field
+ * straight to a k8s `CronJob`, which parses only five fields (minute hour
+ * day-of-month month day-of-week). Core's own cron parser
+ * (`isValidCronExpression`, `packages/core/src/op/cron.ts`, #2120) is
+ * deliberately more permissive: it also accepts the 6-field Quartz form
+ * (`second minute hour dom month dow`) that a `ConvergeOp`'s own `schedule`
+ * may legitimately carry, since the final word on cron syntax belongs to
+ * whichever scheduler runs the string. A k8s CronJob is that scheduler here,
+ * and it is stricter than core's parser, so a 6-field `ConvergeOp` schedule
+ * reused as-is on a CronJob fails at `kubectl apply`, not at build time.
+ *
+ * This module gives both composites one place to catch that at construction,
+ * reusing core's parser rather than a second copy of it.
+ */
+
+import { isValidCronExpression } from "@intentius/chant/op";
+
+/**
+ * Validate `schedule` for a k8s CronJob, throwing before a bad value ever
+ * reaches `kubectl apply`. `context` names the composite (and host, for
+ * `OperatorStack`) so the thrown message reads like the rest of that
+ * composite's build-time refusals, e.g. `OperatorStack "chant-operator",
+ * host "fountain-observe"` or `CronWorkload "backup"`.
+ */
+export function validateCronJobSchedule(context: string, schedule: string): void {
+  if (!schedule || schedule.trim().length === 0) {
+    throw new Error(`${context}: schedule is required. A CronJob with no schedule never ticks.`);
+  }
+
+  const fields = schedule.trim().split(/\s+/);
+
+  if (!isValidCronExpression(schedule)) {
+    throw new Error(
+      `${context}: schedule "${schedule}" is not valid cron syntax. A Kubernetes CronJob takes five fields: minute hour day-of-month month day-of-week.`,
+    );
+  }
+
+  if (fields.length === 6) {
+    throw new Error(
+      `${context}: schedule "${schedule}" is 6-field cron. A Kubernetes CronJob takes five fields (minute hour day-of-month month day-of-week) and has no seconds column. ` +
+        `A ConvergeOp schedule string in that form must be converted before it reaches a CronJob: drop the leading seconds field and keep the remaining five.`,
+    );
+  }
+}

package/src/composites/cron-workload.ts

@@ -8,13 +8,14 @@
 import { Composite, mergeDefaults } from "@intentius/chant";
 import { CronJob, ServiceAccount, Role, RoleBinding } from "../generated";
 import type { ContainerSecurityContext } from "./security-context";
+import { validateCronJobSchedule } from "./cron-schedule";
 
 export interface CronWorkloadProps {
   /** Workload name — used in metadata and labels. */
   name: string;
   /** Container image. */
   image: string;
-  /** Cron schedule expression (e.g., "0 * * * *"). */
+  /** Cron schedule expression (e.g., "0 * * * *"). Validated at construction: a k8s CronJob takes five fields only, so a 6-field (seconds) form is refused (`./cron-schedule.ts`, #2071). */
   schedule: string;
   /** Command to run in the container. */
   command?: string[];
@@ -92,6 +93,8 @@ export const CronWorkload = Composite((props: CronWorkloadProps) => {
     defaults: defs,
   } = props;
 
+  validateCronJobSchedule(`CronWorkload "${name}"`, schedule);
+
   const saName = `${name}-sa`;
   const roleName = `${name}-role`;
   const bindingName = `${name}-binding`;

package/src/composites/operator-stack.ts

@@ -76,6 +76,7 @@ import { Composite, mergeDefaults } from "@intentius/chant";
 import { classifyOpVerbClass } from "@intentius/chant/op";
 import type { OpConfig, OpVerbClass } from "@intentius/chant/op";
 import { Namespace, CronJob, ServiceAccount, Role, RoleBinding } from "../generated";
+import { validateCronJobSchedule } from "./cron-schedule";
 
 // ── Types ────────────────────────────────────────────────────────────────
 
@@ -96,7 +97,7 @@ export interface OperatorRbacResourceRule {
 export interface OperatorStackConvergeHost {
   /** ConvergeOp's own name (`ConvergeOpConfig.name`) — the CronJob, ServiceAccount, Role, and RoleBinding name stem for this host. */
   name: string;
-  /** Cron expression driving the tick — the same string passed to `ConvergeOp`'s own `schedule`. */
+  /** Cron expression driving the tick — the same string passed to `ConvergeOp`'s own `schedule`. Validated at construction: a 6-field (seconds) form, which `ConvergeOp` accepts, is refused here since a k8s CronJob takes five fields only (`./cron-schedule.ts`, #2071). */
   schedule: string;
   /** Environment this ConvergeOp converges (`ConvergeOpConfig.env`) — carried onto the container as `CHANT_CONVERGE_ENV`, for log/estate readability only (`chant run <name>` needs no `--env`: the target op already carries it). */
   env: string;
@@ -268,9 +269,7 @@ export const OperatorStack = Composite((props: OperatorStackConfig) => {
       throw new Error(`OperatorStack "${name}": duplicate hosted ConvergeOp name "${host.name}" — CronJob/ServiceAccount names would collide.`);
     }
     seen.add(host.name);
-    if (!host.schedule || host.schedule.trim().length === 0) {
-      throw new Error(`OperatorStack "${name}", host "${host.name}": schedule is required — an operator CronJob with no schedule never ticks.`);
-    }
+    validateCronJobSchedule(`OperatorStack "${name}", host "${host.name}"`, host.schedule);
   }
   if (!image || image.trim().length === 0) {
     throw new Error(`OperatorStack "${name}": image is required — the CronJob has nothing to run.`);

package/src/config-schema.ts

@@ -28,6 +28,11 @@ export const k8sConfigSchema = z.strictObject({
       roots: z.array(z.string()).optional(),
     })
     .optional(),
+  receipts: z
+    .strictObject({
+      namespace: z.string().optional(),
+    })
+    .optional(),
 });
 
 declare module "@intentius/chant/config" {

package/src/config.ts

@@ -111,6 +111,29 @@ export interface K8sChantConfig {
     /** Kustomization directories to render into the build. */
     roots?: string[];
   };
+
+  /**
+   * Effect receipt settings (#2074, epic #1703).
+   *
+   * `namespace` is where this project's receipt ConfigMaps live. The name is
+   * derived from the ownership fields (`chant-receipt.<stack>.<env>.<effect>`,
+   * see `./effect-receipt-row.ts`); the namespace is the one part of the
+   * address the ownership block cannot answer, so it is declared here. Unset,
+   * receipts land in `default`, the same namespace every other namespace-less
+   * k8s read and write in this lexicon falls through to. It is never derived
+   * from the stack or the environment: a guessed namespace is one chant would
+   * have to create, and the receipt row creates nothing but the receipt.
+   *
+   * ```ts
+   * k8s: {
+   *   receipts: { namespace: "chant-system" },
+   * } satisfies K8sChantConfig
+   * ```
+   */
+  receipts?: {
+    /** Namespace the receipt ConfigMaps live in. Defaults to `default`. */
+    namespace?: string;
+  };
 }
 
 declare module "@intentius/chant/config" {

package/src/deep-observe.ts

@@ -118,6 +118,7 @@ import {
 } from "./api/classify";
 import { operationFor } from "./api/operation-surface";
 import { k8sDeepNormalizationHooks } from "./deep-observe-hooks";
+import { observeReceiptRowsDeep, receiptRowsFor } from "./receipt-store";
 
 // Re-exported so a dynamic importer of this module (plugin.ts's
 // `observeResourcesDeep`, a test) can get the reader and its hooks from one
@@ -159,11 +160,23 @@ export async function observeResourcesDeepK8s(
 ): Promise<DeepObservationResult> {
   const { managedFieldsOf, isChantFieldManager } = await import("@intentius/chant-k8s-client");
 
-  const declared = [...options.entities].map(([entityName, entity]) => ({
-    entityName,
-    entityType: entity.entityType,
-    props: entity.props,
-  }));
+  // Effect receipts (#2074) are read by their own leg at the end: they carry
+  // no declared props, so every live path would be an unclaimed field (#2160)
+  // and their staleness is an `effect` row from the plan (#1832), never
+  // property drift. Reading them here keeps the deep read from calling a
+  // declared entity a hole; contributing an empty tree keeps it from calling
+  // one drift.
+  const receiptRows = receiptRowsFor(options.entityNames, options.buildOutput);
+
+  const declared = [...options.entities]
+    .filter(([entityName]) => !receiptRows.has(entityName))
+    .map(([entityName, entity]) => ({
+      entityName,
+      entityType: entity.entityType,
+      props: entity.props,
+    }));
+
+  const everyName = [...declared.map((d) => d.entityName), ...receiptRows.keys()];
 
   let client;
   try {
@@ -173,7 +186,7 @@ export async function observeResourcesDeepK8s(
       return deepObservation(
         {},
         unobservedAll(
-          declared.map((d) => d.entityName),
+          everyName,
           "read-failed",
           MISSING_CLIENT_DETAIL,
           options.entities,
@@ -185,7 +198,7 @@ export async function observeResourcesDeepK8s(
       return deepObservation(
         {},
         unobservedAll(
-          declared.map((d) => d.entityName),
+          everyName,
           outcome.kind === "unobserved" ? outcome.reason : "read-failed",
           outcome.kind === "unobserved" ? outcome.detail : undefined,
           options.entities,
@@ -267,5 +280,11 @@ export async function observeResourcesDeepK8s(
     }
   });
 
+  if (receiptRows.size > 0) {
+    const receiptObs = await observeReceiptRowsDeep(client, receiptRows);
+    Object.assign(resources, receiptObs.resources);
+    Object.assign(unobserved, receiptObs.unobserved);
+  }
+
   return deepObservation(resources, unobserved);
 }