@intentius/chant-lexicon-k8s 0.124.31 → 0.124.32

package/dist/project-kinds.js

@@ -0,0 +1,56 @@
+/**
+ * Kinds a project generated for itself with `chant generate` from `k8s.crds`
+ * (./crd/project-codegen.ts), as opposed to the kinds the lexicon ships in
+ * `generated/lexicon-k8s.json`.
+ *
+ * The serializer's GVK lookup and the CRD spec checks (WK8501/WK8502) consult
+ * this registry before the packaged JSON. Entries arrive two ways:
+ *
+ * - The generated module registers its kinds (type and GVK) when it is
+ *   imported, so a project's own tests that construct and serialize a
+ *   resource need nothing else.
+ * - A build registers every kind, spec schema included, from the committed
+ *   `kinds.json` beside the module before it serializes (the plugin's
+ *   `projectCodegen().load`). That covers a build whose discovery imported the
+ *   module somewhere else, such as the sandboxed child process.
+ *
+ * The store hangs off `globalThis` under a registered symbol, so two copies
+ * of this module (the plugin the CLI loaded and the one a project's import
+ * resolved) share it. No Node imports: the post-synth barrel reaches this
+ * through ./lint/post-synth/crd-schema-helpers.ts and must stay edge-safe.
+ */
+const STORE = Symbol.for("@intentius/chant-lexicon-k8s/project-kinds");
+function store() {
+    const g = globalThis;
+    g[STORE] ?? (g[STORE] = new Map());
+    return g[STORE];
+}
+/**
+ * Register project-generated kinds. A later registration of the same type
+ * replaces the earlier one, keeping its spec schema when the new entry has
+ * none (the module's import-time registration carries no schema).
+ */
+export function registerProjectKinds(kinds) {
+    const s = store();
+    for (const k of kinds) {
+        const previous = s.get(k.resourceType);
+        const specSchema = k.specSchema ?? (previous?.apiVersion === k.apiVersion && previous.kind === k.kind ? previous.specSchema : undefined);
+        s.set(k.resourceType, { ...k, ...(specSchema ? { specSchema } : {}) });
+    }
+}
+/** The project kind an entity type constructs, if a project registered one. */
+export function projectKindForType(resourceType) {
+    return store().get(resourceType);
+}
+/** The spec schema a project registered for `apiVersion`/`kind`, if any. */
+export function projectSpecSchema(apiVersion, kind) {
+    for (const k of store().values()) {
+        if (k.apiVersion === apiVersion && k.kind === kind && k.specSchema)
+            return k.specSchema;
+    }
+    return undefined;
+}
+/** Test seam: forget every registered kind. */
+export function clearProjectKinds() {
+    store().clear();
+}

package/dist/receipt-store.js

@@ -0,0 +1,216 @@
+/**
+ * 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 { loadChantConfigUpward, resolveOwnershipStack } from "@intentius/chant/config";
+import { LABEL_OWNERSHIP_KEYS, ownershipEntries, classifyOwnership, readOwnership, } from "@intentius/chant/ownership";
+import { defaultK8sConnector } from "./api/connect.js";
+import { classifyApiFailure } from "./api/classify.js";
+import { K8S_EFFECT_RECEIPT_ENTITY_TYPE, RECEIPT_CONFIGMAP_REF, RECEIPT_DATA_KEY, RECEIPT_LABEL_KEY, parseReceiptComment, receiptConfigMapRef, receiptNamespaceFrom, } from "./effect-receipt-row.js";
+async function resolveIdentity(options) {
+    const processEnv = options.env ?? process.env;
+    let stack = options.stack;
+    let env = options.environment ?? processEnv.CHANT_ENV;
+    let namespace = options.namespace;
+    if (!stack || !env || !namespace) {
+        let config;
+        try {
+            config = (await loadChantConfigUpward(options.cwd ?? process.cwd())).config;
+        }
+        catch {
+            config = undefined;
+        }
+        if (config) {
+            stack = stack ?? resolveOwnershipStack(config);
+            // Only a literal env can answer here: a `{ param }` reference resolves
+            // per build, and an op run has no build parameters, and `--env` does.
+            const configEnv = config.ownership?.env;
+            env = env ?? (typeof configEnv === "string" ? configEnv : undefined);
+            namespace = namespace ?? receiptNamespaceFrom(config);
+        }
+    }
+    if (!stack) {
+        throw new Error("k8s receipt store: no stack identity. The receipt ConfigMap is named " +
+            "chant-receipt.<stack>.<env>.<effect>, derived from the same ownership fields that stamp " +
+            "markers (chant #1703, decision 4). Set ownership: { stack } in chant.config.ts.");
+    }
+    if (!env) {
+        throw new Error("k8s receipt store: no environment resolved. The receipt name's <env> segment is explicit " +
+            "(chant #1703, decision 4). Run with --env <name>, set CHANT_ENV, or set a literal " +
+            "ownership.env in chant.config.ts.");
+    }
+    return { stack, env, namespace: namespace ?? receiptNamespaceFrom(undefined) };
+}
+/** The stored expectation on a live receipt ConfigMap, or undefined when the
+ * object holds none. */
+export function receiptValueOf(object) {
+    const data = object?.data;
+    const value = data?.[RECEIPT_DATA_KEY];
+    return typeof value === "string" ? value : 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 function k8sReceiptStore(options = {}) {
+    let identity;
+    const identityOf = () => (identity ?? (identity = resolveIdentity(options)));
+    let pending;
+    const clientOf = () => (pending ?? (pending = (options.connect ?? defaultK8sConnector)({
+        ...(options.environment !== undefined ? { environment: options.environment } : {}),
+        ...(options.context !== undefined ? { context: options.context } : {}),
+        ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+    }).then((connected) => connected.client)));
+    return {
+        async read(receipt) {
+            const { stack, env, namespace } = await identityOf();
+            const ref = receiptConfigMapRef(stack, env, receipt.effect, namespace);
+            const client = await clientOf();
+            const live = await client.readIfPresent({ ...RECEIPT_CONFIGMAP_REF, ...ref });
+            return receiptValueOf(live);
+        },
+        async write(receipt, expectation) {
+            const { stack, env, namespace } = await identityOf();
+            const ref = receiptConfigMapRef(stack, env, receipt.effect, namespace);
+            const client = await clientOf();
+            const configMap = {
+                ...RECEIPT_CONFIGMAP_REF,
+                metadata: {
+                    ...ref,
+                    labels: {
+                        ...ownershipEntries(LABEL_OWNERSHIP_KEYS, { stack, env }),
+                        [RECEIPT_LABEL_KEY]: receipt.effect,
+                    },
+                },
+                data: { [RECEIPT_DATA_KEY]: expectation },
+            };
+            await client.apply(configMap, { fieldManager: `chant:${stack}` });
+        },
+    };
+}
+/** The receipt rows a build output carries, keyed by entity name. Only the
+ * entities this observation was asked about. */
+export function receiptRowsFor(entityNames, buildOutput) {
+    const rows = parseReceiptComment(buildOutput ?? "");
+    const wanted = new Set(entityNames);
+    const out = new Map();
+    for (const [name, row] of Object.entries(rows)) {
+        if (!wanted.has(name))
+            continue;
+        if (typeof row?.name !== "string" || typeof row?.namespace !== "string")
+            continue;
+        out.set(name, row);
+    }
+    return out;
+}
+/**
+ * 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 async function observeReceiptRows(client, rows) {
+    const out = { resources: {}, unobserved: {} };
+    await client.concurrently([...rows], async ([entityName, row]) => {
+        try {
+            const live = await client.read({
+                ...RECEIPT_CONFIGMAP_REF,
+                name: row.name,
+                namespace: row.namespace,
+            });
+            out.resources[entityName] = {
+                type: K8S_EFFECT_RECEIPT_ENTITY_TYPE,
+                physicalId: live.metadata?.uid,
+                // Live outside anything the applier wrote, by design. The same word
+                // the aws row's observation uses for a receipt parameter (#1835).
+                status: "EXTERNAL",
+                ownership: classifyOwnership(live.metadata?.labels, LABEL_OWNERSHIP_KEYS),
+                marker: readOwnership(live.metadata?.labels, LABEL_OWNERSHIP_KEYS),
+                attributes: {
+                    namespace: row.namespace,
+                    // Core's RECEIPT_VALUE_ATTRIBUTE, which is what `readReceiptValue` reads.
+                    value: receiptValueOf(live) ?? "",
+                },
+            };
+        }
+        catch (err) {
+            const outcome = classifyApiFailure(err);
+            if (outcome.kind === "unobserved") {
+                out.unobserved[entityName] = {
+                    type: K8S_EFFECT_RECEIPT_ENTITY_TYPE,
+                    reason: outcome.reason,
+                    detail: `reading receipt ConfigMap ${row.namespace}/${row.name}: ${outcome.detail}`,
+                };
+            }
+            // `absent` records nothing: in neither map is how the contract spells
+            // "asked, and it is not there", which is what the plan reads as "the
+            // effect has not fired for these inputs".
+        }
+    });
+    return out;
+}
+/**
+ * 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 async function observeReceiptRowsDeep(client, rows) {
+    const thin = await observeReceiptRows(client, rows);
+    const resources = {};
+    for (const [name, meta] of Object.entries(thin.resources)) {
+        resources[name] = {
+            type: K8S_EFFECT_RECEIPT_ENTITY_TYPE,
+            ...(meta.physicalId ? { physicalId: meta.physicalId } : {}),
+            properties: {},
+        };
+    }
+    return { resources, unobserved: thin.unobserved };
+}

package/dist/rules/crd-schema-helpers.ts

@@ -12,6 +12,7 @@
  */
 
 import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
 import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
 import type { CrdFieldSchema } from "../../spec/parse";
 import { docsToManifests, type K8sManifest } from "./k8s-helpers";
@@ -44,7 +45,7 @@ export function getCrdSchemaRegistry(): Map<string, CrdFieldSchema> {
     // Built lazily so importing this module stays edge-safe: `createRequire`
     // throws where import.meta.url is undefined (bundled Workers), and there
     // the registry is simply empty.
-    const require = createRequire(import.meta.url);
+    const require = createRequire(moduleSourceUrl(import.meta.url));
     const lexicon = require("../../generated/lexicon-k8s.json") as Record<string, LexiconEntry>;
     for (const entry of Object.values(lexicon)) {
       if (entry.kind === "resource" && entry.apiVersion && entry.gvkKind && entry.specSchema) {

package/dist/secret-labels.js

@@ -0,0 +1,33 @@
+/**
+ * The `generated-once` marker label (chant #1830, epic #1365 decision 5).
+ *
+ * `k8sSecretStore` (./secret-store.ts) stamps this label onto every Secret it
+ * mints, next to the ownership marker. Both k8s prune paths key on it:
+ *
+ * - the apply-path prune (`applyManifest`'s owned-only sweep,
+ *   op/activities/kubectl.ts) excludes a labeled Secret from the prunable set
+ *   and reports it `retained` instead of deleting it;
+ * - env teardown (./teardown.ts `executeTeardown`) reports the same `retained`
+ *   outcome for it, loudly, and never deletes it.
+ *
+ * The rationale is the materialization contract: the stored bytes are the ONLY
+ * copy of material chant never held, so no sweep may destroy them. Deletion is
+ * an explicit human act — `kubectl delete secret <name>`, or a future gated
+ * op — never a side effect of "no longer declared".
+ *
+ * Dependency-light on purpose: no client import, so the constants are usable
+ * from the build path, the prune paths, and the docs/tests alike.
+ */
+/** The label key a generated-once Secret carries. */
+export const GENERATED_ONCE_LABEL_KEY = "chant.intentius.io/generated-once";
+/** The label value `k8sSecretStore` stamps. */
+export const GENERATED_ONCE_LABEL_VALUE = "true";
+/**
+ * True when a live object's labels mark it generated-once. Any non-empty
+ * value counts: the label's presence is the claim, and a sweep must err on
+ * the side of keeping.
+ */
+export function isGeneratedOnce(labels) {
+    const value = labels?.[GENERATED_ONCE_LABEL_KEY];
+    return typeof value === "string" && value.length > 0;
+}

package/dist/secret-store.js

@@ -0,0 +1,116 @@
+/**
+ * The Kubernetes row of the secret-store seam (chant #1830, epic #1365) — a
+ * `SecretStoreAdapter` over the typed client, for the `ensure-secret`
+ * capability verb and the `ensureSecret(...)` op step (both #1829, both
+ * surfaces over core's one materialization engine).
+ *
+ * The constitutional line, held structurally:
+ *
+ * - `exists` and `describe` read the live Secret and report key NAMES and
+ *   labels/annotations only. The `data` values are projected to their key
+ *   names inside one function frame and the object is dropped — nothing
+ *   value-shaped is returned, logged, or retained. The mismatch check in core
+ *   therefore has nothing to compare but names, by construction.
+ * - `create` is the only writer. It redeems each key's material through
+ *   `consumeSecretMaterial` AT the write — the engine hands the generator
+ *   through this seam and never calls it — and returns nothing.
+ *
+ * Every minted Secret carries chant's ownership marker plus the
+ * `chant.intentius.io/generated-once` label (./secret-labels.ts), which is
+ * what both prune paths key their `retained` outcome on: a generated-once
+ * Secret is never in any prunable set, because the stored bytes are the only
+ * copy of material chant never held.
+ *
+ * Not exported from the package entry point — like ./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/secret-store`.
+ */
+import { consumeSecretMaterial } from "@intentius/chant/secret-materialization";
+import { createEnsureSecretCapability, } from "@intentius/chant/components/verbs/ensure-secret";
+import { LABEL_OWNERSHIP_KEYS, OWNERSHIP_MANAGED_BY_VALUE, ownershipEntries, } from "@intentius/chant/ownership";
+import { defaultK8sConnector } from "./api/connect.js";
+import { GENERATED_ONCE_LABEL_KEY, GENERATED_ONCE_LABEL_VALUE } from "./secret-labels.js";
+const SECRET_REF = { apiVersion: "v1", kind: "Secret" };
+/**
+ * Build the k8s `SecretStoreAdapter` for one namespace.
+ *
+ * Pass a `client` where the caller already holds one (an activity that
+ * connected for the rest of its work); omit it and the adapter connects
+ * lazily through the same environment→cluster binding every other k8s path
+ * uses (./api/connect.ts).
+ */
+export function k8sSecretStore(namespace, client, options = {}) {
+    let pending = client ? Promise.resolve(client) : undefined;
+    const clientOf = () => (pending ?? (pending = (options.connect ?? defaultK8sConnector)({
+        ...(options.environment !== undefined ? { environment: options.environment } : {}),
+        ...(options.context !== undefined ? { context: options.context } : {}),
+        ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+    }).then((connected) => connected.client)));
+    return {
+        async exists(name) {
+            const c = await clientOf();
+            return (await c.readIfPresent({ ...SECRET_REF, name, namespace })) !== undefined;
+        },
+        async describe(name) {
+            const c = await clientOf();
+            const live = await c.read({ ...SECRET_REF, name, namespace });
+            // Project key names and drop the object in the same frame. The values
+            // exist only in `live`, which nothing below touches again — the return
+            // carries names and metadata, never a byte of `data`.
+            const keys = Object.keys(live.data ?? {}).sort();
+            const metadata = {
+                ...(live.metadata?.annotations ?? {}),
+                ...(live.metadata?.labels ?? {}),
+            };
+            return { keys, metadata };
+        },
+        async create(name, keys, generate) {
+            const c = await clientOf();
+            // Mint and consume per key, at the write. `consumeSecretMaterial` burns
+            // each handle, so the material cannot be redeemed a second time by
+            // anything, this adapter included.
+            const data = {};
+            for (const key of keys) {
+                data[key] = Buffer.from(consumeSecretMaterial(await generate(key)), "utf-8").toString("base64");
+            }
+            const secret = {
+                apiVersion: SECRET_REF.apiVersion,
+                kind: SECRET_REF.kind,
+                metadata: {
+                    name,
+                    namespace,
+                    labels: {
+                        ...(options.marker
+                            ? ownershipEntries(LABEL_OWNERSHIP_KEYS, options.marker)
+                            : { [LABEL_OWNERSHIP_KEYS.managedBy]: OWNERSHIP_MANAGED_BY_VALUE }),
+                        [GENERATED_ONCE_LABEL_KEY]: GENERATED_ONCE_LABEL_VALUE,
+                    },
+                },
+                type: "Opaque",
+                data,
+            };
+            // Server-side apply as chant's field manager — the same write path every
+            // other chant mutation takes. The result (which echoes `data`) is
+            // deliberately discarded.
+            await c.apply(secret, {
+                ...(options.marker ? { fieldManager: `chant:${options.marker.stack}` } : {}),
+            });
+        },
+    };
+}
+/**
+ * The real `ensure-secret` capability for a Kubernetes namespace — core's
+ * factory (#1829) over this module's adapter. Replaces the starter set's
+ * typed stub for a project whose secret store is the cluster:
+ *
+ * ```ts
+ * registry.register(k8sEnsureSecretCapability("prod", undefined, {
+ *   marker: { stack: "shop", env: "prod" },
+ *   environment: "prod",
+ * }));
+ * ```
+ */
+export function k8sEnsureSecretCapability(namespace, client, options = {}) {
+    return createEnsureSecretCapability({ store: k8sSecretStore(namespace, client, options) });
+}

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;AAoXlG,eAAO,MAAM,aAAa,EAAE,UAyO3B,CAAC"}
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAsC,MAAM,6BAA6B,CAAC;AAoXlG,eAAO,MAAM,aAAa,EAAE,UAyO3B,CAAC"}