@intentius/chant-lexicon-k8s 0.57.0 → 0.59.0

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.57.0",
+  "version": "0.59.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.57.0"
+    "@intentius/chant-k8s-client": "^0.59.0"
   },
   "devDependencies": {
     "@intentius/chant": "*",
@@ -84,7 +84,7 @@
   },
   "peerDependencies": {
     "zod": "^4.3.6",
-    "@intentius/chant": "^0.57.0",
+    "@intentius/chant": "^0.59.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/api/sweep-types.ts

@@ -10,8 +10,7 @@
  *
  * It lives in its own module, with no imports of its own, because both
  * consumers reach it from different directions — `../export-resources.ts`
- * pulls in the whole import parser, and a Temporal worker loading the apply
- * activity should not.
+ * pulls in the whole import parser, and the apply activity should not.
  */
 export const DEFAULT_IMPORT_TYPES: readonly string[] = [
   "K8s::Apps::Deployment",

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 ──────────────────────────────────────────────
@@ -3868,7 +3894,7 @@ describe("OperatorStack", () => {
     }
   });
 
-  test("observe-dial ConvergeOp with a mutating dispatch target still gets read-only RBAC — observe never dispatches, per TMP014/convergeTick", () => {
+  test("observe-dial ConvergeOp with a mutating dispatch target still gets read-only RBAC — observe never dispatches, per OPS014/convergeTick", () => {
     const result: any = OperatorStack({
       name: "chant-operator",
       image: "chant:latest",
@@ -3880,7 +3906,7 @@ describe("OperatorStack", () => {
     }
   });
 
-  test("reconcile-dial ConvergeOp with a mutating dispatch target still gets read-only RBAC — TMP014 only lets apply free-run a mutating dispatch", () => {
+  test("reconcile-dial ConvergeOp with a mutating dispatch target still gets read-only RBAC — OPS014 only lets apply free-run a mutating dispatch", () => {
     const result: any = OperatorStack({
       name: "chant-operator",
       image: "chant:latest",
@@ -3979,6 +4005,17 @@ describe("OperatorStack", () => {
     expect(() => deriveHostVerbClass("x", "observe", [DESTRUCTIVE_OP])).toThrow(/destructive/);
   });
 
+  // #2192 — the refusal cites the rule that actually owns it (OPS014), and
+  // gives OPS014's own reason. The old message argued from the local
+  // executor's inability to honour a gate, which #2119 retired: a gated op
+  // now ends the run `gated` rather than being refused, so the refusal stands
+  // on the unattended-approval ground instead.
+  test("deriveHostVerbClass: the destructive refusal names OPS014 and the unattended-approval reason", () => {
+    expect(() => deriveHostVerbClass("x", "apply", [DESTRUCTIVE_OP])).toThrow(/OPS014/);
+    expect(() => deriveHostVerbClass("x", "apply", [DESTRUCTIVE_OP])).toThrow(/unattended/);
+    expect(() => deriveHostVerbClass("x", "apply", [DESTRUCTIVE_OP])).not.toThrow(/TMP014/);
+  });
+
   // ── Build-time refusals ──────────────────────────────────────────────
 
   test("refuses an empty converge array", () => {
@@ -4005,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

@@ -16,39 +16,40 @@
  * (lease fencing, `chant operator status`, durable gate-as-fact semantics).
  * `OperatorStack`'s container command is deliberately `chant run <name>`,
  * the one-shot local tick `ConvergeOp` (#1484) already ships and tests
- * against (`lexicons/temporal/src/composites/converge-op.ts`'s own doc:
+ * against (`packages/core/src/op/composites/converge-op.ts`'s own doc:
  * "one-shot runnable locally for a single tick"). When #1485 lands, a
  * caller can override `command` to shell out to `chant operator tick`
  * instead — this composite doesn't need to change for that; only the
  * command a caller passes does.
  *
  * `concurrencyPolicy: "Forbid"` is the k8s-native analogue of
- * `ConvergeOp`'s own Temporal schedule `overlap: "Skip"` policy — never
- * queue a second tick behind one still running.
+ * `ConvergeOp`'s own `schedule.overlap: "skip"` policy — never queue a
+ * second tick behind one still running.
  *
  * ## RBAC derivation
  *
  * `ConvergeOp` adds no authority an environment did not already grant
  * (#1484's Autonomy table). `OperatorStack` re-derives the same bound at the
- * k8s RBAC layer, independently of the temporal lexicon (this module has no
- * dependency on it — see the layering note below): for each hosted
+ * k8s RBAC layer, from the Op configs alone (see the Layering note below for
+ * what this module imports and what it restates): for each hosted
  * ConvergeOp, walk its `dispatchTargets` (the OpConfigs its rule table's
  * `run()` actions may name) through `classifyOpVerbClass`
  * (`packages/core/src/op/op-verb-class.ts`, #1954), then keep only the
  * highest verb class this host's `dial` could ever actually free-run —
  * exactly `convergeTick`'s own `verbClassAllowedToDispatch` gate and
- * `TMP014`'s build-time refusal, restated as an RBAC ceiling:
+ * `OPS014`'s build-time refusal, restated as an RBAC ceiling:
  *
  * - `dial: "observe"` never dispatches (report-only) → read-only RBAC,
  *   regardless of what the rule table's targets could otherwise do.
- * - `dial: "reconcile"` only free-runs a read-only target (TMP014 refuses a
+ * - `dial: "reconcile"` only free-runs a read-only target (OPS014 refuses a
  *   mutating dispatch under reconcile in v1) → read-only RBAC.
  * - `dial: "apply"` free-runs read-only and mutating targets → RBAC gains
  *   create/update/patch, never delete.
  * - A `dispatchTargets` entry that itself classifies `destructive` is
- *   refused outright, at construction — TMP014 already refuses a
- *   destructive `run()` target under any dial in v1 (the local dispatch
- *   executor can't honor its required gate), so a `destructive` target
+ *   refused outright, at construction — OPS014 already refuses a
+ *   destructive `run()` target under any dial in v1 (a converge tick runs
+ *   unattended, and a destructive dispatch needs a person's approval before
+ *   it is attempted, not a gate read after the fact), so a `destructive` target
  *   reaching this composite is either a config bypassing that build check
  *   or a target `OperatorStack` should never grant permission toward.
  *   `never delete`, unconditionally, in v1 — no verb class here ever grants
@@ -61,11 +62,11 @@
  *
  * ## Layering
  *
- * `lexicons/k8s` has no workspace dependency on `lexicons/temporal` (nor
- * the reverse — see both packages' `package.json`), so this module doesn't
- * import `ConvergeOpConfig`/`ConvergeRule` types. `OperatorStackConvergeHost`
- * restates the handful of `ConvergeOp` fields this composite actually needs
- * (`name`, `schedule`, `env`, `dial`) structurally; `dispatchTargets` takes
+ * `OperatorStackConvergeHost` restates the handful of `ConvergeOp` fields
+ * this composite actually needs (`name`, `schedule`, `env`, `dial`)
+ * structurally rather than importing `ConvergeOpConfig`: the CronJob is
+ * built from a host description, not from an Op config, and a caller that
+ * has neither should still be able to describe one. `dispatchTargets` takes
  * plain `OpConfig`-shaped values from `@intentius/chant/op` (a dependency
  * this lexicon already has via the `@intentius/chant` peer dependency),
  * the same type `classifyOpVerbClass` itself takes.
@@ -75,12 +76,13 @@ 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 ────────────────────────────────────────────────────────────────
 
 /**
  * Mirrors `ConvergeOp`'s own `ConvergeDial`
- * (`lexicons/temporal/src/composites/converge-op.ts`) structurally — see
+ * (`packages/core/src/op/composites/converge-op.ts`) structurally — see
  * this module's Layering doc for why it's restated rather than imported.
  */
 export type OperatorDial = "observe" | "reconcile" | "apply";
@@ -95,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;
@@ -104,7 +106,7 @@ export interface OperatorStackConvergeHost {
   /**
    * OpConfigs for every op this ConvergeOp's rule table may `run()` — the
    * sibling `*.op.ts` declarations its `run()` actions name. Used to derive
-   * least-privilege RBAC the same way `TMP014` derives its build-time
+   * least-privilege RBAC the same way `OPS014` derives its build-time
    * refusals. Omit or leave empty when every rule only `report()`s; the
    * host still gets read-only RBAC for its own observation.
    */
@@ -183,7 +185,7 @@ function rbacVerbsFor(verbClass: OpVerbClass): string[] {
 /**
  * Whether `dial` ever actually free-runs a dispatch classified `verbClass` —
  * restates `convergeTick`'s own `verbClassAllowedToDispatch`
- * (`lexicons/temporal/src/op/activities/converge.ts`) so the RBAC ceiling
+ * (`packages/core/src/op/activities/converge.ts`) so the RBAC ceiling
  * this composite grants matches the ceiling the tick itself enforces at
  * runtime, without importing across the lexicon boundary (see this module's
  * Layering doc).
@@ -198,7 +200,7 @@ function dialAllowsVerbClass(dial: OperatorDial, verbClass: OpVerbClass): boolea
  * Derive the highest verb class a host's ServiceAccount actually needs:
  * the max, across `dispatchTargets`, of each target's own class — but only
  * counting a target `dial` could ever actually dispatch (one it can't just
- * gets reported, per `TMP014`/`convergeTick`, and needs no elevated grant).
+ * gets reported, per `OPS014`/`convergeTick`, and needs no elevated grant).
  * A `dispatchTargets` entry that classifies `destructive` is refused
  * outright rather than silently ignored — see this module's RBAC
  * derivation doc on why a destructive target reaching this composite is
@@ -211,7 +213,8 @@ export function deriveHostVerbClass(hostName: string, dial: OperatorDial, dispat
     if (verbClass === "destructive") {
       throw new Error(
         `OperatorStack host "${hostName}": a dispatchTargets entry classifies as destructive — ConvergeOp v1 refuses a destructive run() target under any dial ` +
-          `(TMP014; the local dispatch executor can't honor its required gate). Remove it from dispatchTargets, or remediate manually via a gated op.`,
+          `(OPS014; a converge tick runs unattended, and a destructive dispatch needs a person's approval before it is attempted, not a gate the tick reads after it has already committed to the run). ` +
+          `Remove it from dispatchTargets, and run the destructive op yourself through its gate.`,
       );
     }
     if (!dialAllowsVerbClass(dial, verbClass)) continue; // dial refuses this dispatch — reported, not run; needs no elevated RBAC
@@ -266,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

@@ -2,8 +2,8 @@
  * K8s environment → cluster binding — chant #1100.
  *
  * Every cloud lexicon binds an environment to a scope: AWS resolves `<env>`
- * to a CloudFormation stack, Azure treats `<env>` as the resource group,
- * Temporal looks up `temporal.profiles.<env>`. Before this, k8s bound
+ * to a CloudFormation stack, Azure treats `<env>` as the resource group.
+ * Before this, k8s bound
  * nothing — `describeResources` shelled out to `kubectl get` with no
  * `--context`, so `chant lifecycle diff prod --live` read whichever cluster
  * `kubectl config current-context` happened to point at.
@@ -40,8 +40,8 @@
  *   and the missing binding.
  *
  * `ChantConfig` uses `.passthrough()` in its Zod schema so the `k8s` key is
- * accepted at runtime without core changes, exactly like `temporal.profiles`
- * (see `lexicons/temporal/src/config.ts`). The type side is the declaration
+ * accepted at runtime without core changes, exactly like the `terraform` key
+ * (see `lexicons/terraform/src/config.ts`). The type side is the declaration
  * merge at the bottom of this file — without it the snippet above compiles
  * only until someone adds `satisfies ChantConfig`, which every example
  * project does and which is the only thing type-checking the rest of the
@@ -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/crd/crd-sources.ts

@@ -26,7 +26,7 @@ const KUBERAY_CRD_BASE = `https://raw.githubusercontent.com/ray-project/kuberay/
  * Argo CD CRDs — argoproj.io/v1alpha1
  *
  * Produces (the `argoproj.io` group is mapped to the `Argo` namespace —
- * see GROUP_NAMESPACE_OVERRIDES in crd/parser.ts):
+ * see GROUP_NAMESPACE_OVERRIDES in group-namespace.ts):
  *   K8s::Argo::Application     → apiVersion: argoproj.io/v1alpha1, kind: Application
  *   K8s::Argo::ApplicationSet  → apiVersion: argoproj.io/v1alpha1, kind: ApplicationSet
  *   K8s::Argo::AppProject      → apiVersion: argoproj.io/v1alpha1, kind: AppProject
@@ -221,7 +221,7 @@ const PROM_OPERATOR_CRD_BASE = `https://raw.githubusercontent.com/prometheus-ope
  * also carries `ExternalArtifact` and `ArtifactGenerator` (experimental, and a
  * separate `source.extensions.fluxcd.io` group), which are intentionally left
  * out. All groups map to the `Flux` namespace (see GROUP_NAMESPACE_OVERRIDES in
- * crd/parser.ts):
+ * group-namespace.ts):
  *   K8s::Flux::GitRepository / OCIRepository / HelmRepository / HelmChart / Bucket
  *                                          → source.toolkit.fluxcd.io/v1
  *   K8s::Flux::Kustomization               → kustomize.toolkit.fluxcd.io/v1
@@ -259,7 +259,7 @@ const FLUX_OPERATOR_INSTALL = `https://github.com/controlplaneio-fluxcd/flux-ope
  * KubeMicroVM CRDs — lambda.aws.amazon.com/v1alpha1
  *
  * Produces (the group is mapped to the `KubeMicroVM` namespace — see
- * GROUP_NAMESPACE_OVERRIDES in crd/parser.ts):
+ * GROUP_NAMESPACE_OVERRIDES in group-namespace.ts):
  *   K8s::KubeMicroVM::MicroVM            → kind: MicroVM
  *   K8s::KubeMicroVM::MicroVMImage       → kind: MicroVMImage
  *   K8s::KubeMicroVM::MicroVMNetwork     → kind: MicroVMNetwork
@@ -287,7 +287,7 @@ const KUBEMICROVM_VERSION = "1.0.11";
  * k3s estate's GitOps surface is written in.
  *
  * Produces (both groups map to the `K3s` namespace — see
- * GROUP_NAMESPACE_OVERRIDES in crd/parser.ts):
+ * GROUP_NAMESPACE_OVERRIDES in group-namespace.ts):
  *   K8s::K3s::HelmChart        → apiVersion: helm.cattle.io/v1, kind: HelmChart
  *   K8s::K3s::HelmChartConfig  → apiVersion: helm.cattle.io/v1, kind: HelmChartConfig
  *   K8s::K3s::Addon            → apiVersion: k3s.cattle.io/v1,  kind: Addon

package/src/deep-observe-hooks.ts

@@ -61,7 +61,8 @@ import { GENERATED_ONCE_LABEL_KEY } from "./secret-labels";
  * Kubernetes-defaulted fields, per entity type, as index-erased property
  * paths. Subtracted only where source never declared the property
  * (`side === "live" && counterpart === "absent"`) — cdk-real-drift's default
- * subtraction, same convention as AWS/Azure/Temporal's tables.
+ * subtraction, same convention as the AWS and Azure tables
+ * (`AWS_SERVICE_DEFAULTS`, `AZURE_SERVICE_DEFAULTS`).
  *
  * Sparse and evidence-based rather than derived from the generated schema:
  * the k8s OpenAPI spec this lexicon's codegen consumes
@@ -70,9 +71,8 @@ import { GENERATED_ONCE_LABEL_KEY } from "./secret-labels";
  * actually expressible today. Widening this table is additive and needs no
  * contract change.
  *
- * `spec.strategy` is listed whole, not as `spec.strategy.type`, for the same
- * reason Temporal's `TEMPORAL_SCHEDULE_DEFAULTS` lists `state` whole: pruning
- * only the leaf would still recurse into the object, and a nested default the
+ * `spec.strategy` is listed whole rather than as `spec.strategy.type`, because
+ * pruning only the leaf would still recurse into the object, and a nested default the
  * table does not separately name (`rollingUpdate.maxSurge`/`maxUnavailable`,
  * both `"25%"` when `spec.strategy` is omitted entirely) would leave behind an
  * empty `strategy: {}` — a value distinct from no `strategy` key at all, and