@intentius/chant-lexicon-k8s 0.124.31 → 0.124.32

package/dist/api/owner-chain.js

@@ -0,0 +1,100 @@
+/**
+ * Resolving a live Kubernetes object's `ownerReferences` chain up to a
+ * declared, chant-observed entity (chant #1077).
+ *
+ * There is no server-side "who ultimately owns this object" query — Kubernetes'
+ * own garbage collector does not have one either; it walks the same chain one
+ * hop at a time, reading each intermediate owner. A Pod's `ownerReferences`
+ * names its ReplicaSet, which chant never declared; the ReplicaSet's own
+ * `ownerReferences` names the Deployment, which is declared. Reaching that
+ * declared entity takes reading the ReplicaSet in between.
+ *
+ * This module's only job is assembling that chain — fetching each hop through
+ * the typed client, bounded and cycle-guarded so a corrupt or adversarial
+ * chain cannot hang an observation. The bounded/cycle-safe *interpretation* of
+ * the assembled chain (declared / unowned / foreign / unknown) is core's
+ * `classifyOwnerChain` (`@intentius/chant/owner-chain`) — the issue's own
+ * division of labor: core owns the category, the lexicon supplies the chain.
+ */
+import { classifyOwnerChain, DEFAULT_MAX_OWNER_CHAIN_DEPTH, } from "@intentius/chant/owner-chain";
+function ownerRefs(obj) {
+    const refs = obj.metadata?.ownerReferences;
+    return Array.isArray(refs) ? refs : [];
+}
+/**
+ * The reference Kubernetes' own garbage collector treats as the controlling
+ * parent: the entry with `controller: true`, else the first. An object with
+ * several owner references (rare — usually a shared, non-controller owner
+ * alongside the controlling one) is walked through its controller, matching
+ * what actually recreates the object were it deleted.
+ */
+function controllingRef(obj) {
+    const refs = ownerRefs(obj);
+    return refs.find((r) => r.controller === true) ?? refs[0];
+}
+/**
+ * Walk `obj`'s owner-reference chain up to a declared entity, a foreign root,
+ * or a bound (#1077). Fetches at most `maxDepth + 1` objects (the starting
+ * object plus up to `maxDepth` ancestors) — the same bound `classifyOwnerChain`
+ * enforces when interpreting the result, so nothing is fetched that the
+ * interpretation would not have used anyway.
+ */
+export async function resolveK8sOwnerChain(obj, options) {
+    const startUid = obj.metadata?.uid;
+    if (!startUid)
+        return { root: "unknown" };
+    const maxDepth = options.maxDepth ?? DEFAULT_MAX_OWNER_CHAIN_DEPTH;
+    const nodes = new Map();
+    const visited = new Set();
+    let uid = startUid;
+    let object = obj;
+    for (let depth = 0; uid !== undefined && depth <= maxDepth; depth++) {
+        if (visited.has(uid))
+            break; // cycle — classifyOwnerChain reads it off `nodes`
+        visited.add(uid);
+        const declaredEntity = options.declaredByUid.get(uid);
+        if (declaredEntity) {
+            nodes.set(uid, { declaredEntity });
+            break;
+        }
+        if (!object) {
+            nodes.set(uid, { ownerUnreadable: true });
+            break;
+        }
+        const ref = controllingRef(object);
+        if (!ref?.uid || !ref.kind || !ref.apiVersion || !ref.name) {
+            nodes.set(uid, {}); // no further owner — a real, live root
+            break;
+        }
+        nodes.set(uid, { ownerId: ref.uid });
+        if (visited.has(ref.uid)) {
+            // About to cycle back to an already-visited node — let the loop's own
+            // check classify it next iteration rather than issuing a wasted read.
+            uid = ref.uid;
+            continue;
+        }
+        if (options.declaredByUid.has(ref.uid)) {
+            // Already known to be a declared entity from this observation's own
+            // resolved set — no need to read it, the next iteration resolves it
+            // from `declaredByUid` directly.
+            uid = ref.uid;
+            object = undefined;
+            continue;
+        }
+        try {
+            object = await options.reader.readIfPresent({
+                apiVersion: ref.apiVersion,
+                kind: ref.kind,
+                name: ref.name,
+                namespace: options.namespace,
+            });
+        }
+        catch {
+            object = undefined;
+        }
+        if (!object)
+            nodes.set(ref.uid, { ownerUnreadable: true });
+        uid = ref.uid;
+    }
+    return classifyOwnerChain(startUid, nodes, maxDepth);
+}

package/dist/api/sweep-types.js

@@ -0,0 +1,35 @@
+/**
+ * The kinds chant sweeps when nothing narrows the question.
+ *
+ * A *product* decision — what a bare `chant import` should pull back, and
+ * (chant #1075) which kinds an ownership-scoped prune has to look at to notice
+ * that a whole kind was removed from source. Not an addressing limit: since
+ * chant #1074 removed `KUBECTL_RESOURCE`, a `--selector type=<entity type>`
+ * import can name any of the ~180 types the generated operation surface
+ * carries, CRDs included.
+ *
+ * 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 the apply activity should not.
+ */
+export const DEFAULT_IMPORT_TYPES = [
+    "K8s::Apps::Deployment",
+    "K8s::Apps::StatefulSet",
+    "K8s::Apps::DaemonSet",
+    "K8s::Apps::ReplicaSet",
+    "K8s::Core::Service",
+    "K8s::Core::ConfigMap",
+    "K8s::Core::Secret",
+    "K8s::Core::Namespace",
+    "K8s::Core::Pod",
+    "K8s::Core::PersistentVolumeClaim",
+    "K8s::Core::ServiceAccount",
+    "K8s::Batch::Job",
+    "K8s::Batch::CronJob",
+    "K8s::Networking::Ingress",
+    "K8s::Networking::NetworkPolicy",
+    "K8s::Rbac::Role",
+    "K8s::Rbac::RoleBinding",
+    "K8s::Rbac::ClusterRole",
+    "K8s::Rbac::ClusterRoleBinding",
+];

package/dist/behaviour-kinds.js

@@ -0,0 +1,82 @@
+/**
+ * What this lexicon's entity types are worth to a behaviour engine (#2382).
+ *
+ * Contributed as rows through the plugin's `behaviourKinds` field; the
+ * vocabulary, the resolution and the prediction are
+ * `packages/core/src/behaviour-kinds.ts`. These rows were a section of one
+ * cross-lexicon table in one lexicon until #2382 moved each substrate's
+ * rows to the lexicon that owns the types — this file can say what
+ * `K8s::Apps::Deployment` means because it is the file that defines it.
+ *
+ * A table rather than a heuristic over type names: a heuristic would map
+ * `K8s::Rbac::RoleBinding` to storage and price a join table.
+ */
+/** Types an engine prices, with the declared property its size is read from. */
+const MAPPED = {
+    // No `sizeProp` on the five workload kinds. A workload's size is its pod
+    // template's container resource requests — an object, per container, over an
+    // array — and this contract's `size` is one string in the provider's own
+    // vocabulary. Kubernetes has no such string for a workload. Naming
+    // `spec.template.spec.containers` here, as the first version did, advertised
+    // a column that resolved to an array and therefore to nothing, on every
+    // Kubernetes workload in the repository.
+    "K8s::Apps::Deployment": { kind: "compute" },
+    "K8s::Apps::StatefulSet": { kind: "compute" },
+    "K8s::Apps::DaemonSet": { kind: "compute" },
+    "K8s::Core::Pod": { kind: "compute" },
+    "K8s::Batch::Job": { kind: "serverless" },
+    "K8s::Batch::CronJob": { kind: "serverless" },
+    // These two do state a size, as a single string in Kubernetes' own
+    // vocabulary: a quantity (`20Gi`) and a service type (`LoadBalancer`).
+    "K8s::Core::PersistentVolumeClaim": { kind: "block-store", sizeProp: "spec.resources.requests.storage", sizeType: "string" },
+    "K8s::Core::Service": { kind: "load-balancer", sizeProp: "spec.type", sizeType: "string" },
+    "K8s::Networking::Ingress": { kind: "load-balancer" },
+};
+/**
+ * Types considered and declared unsendable, each with the reason it carries no
+ * rate. The fifth family core's contributor guidance names is this lexicon's
+ * own: a controller's request is not the thing it creates. A `Certificate`
+ * costs nothing; the issuer's work and the Secret it writes are elsewhere in
+ * the graph or outside the cluster entirely.
+ */
+const UNMAPPED = {
+    "K8s::Rbac::Role": "an RBAC role is a grant; the workloads it admits are what cost and saturate",
+    "K8s::Rbac::RoleBinding": "an RBAC binding is a grant; the workloads it admits are what cost and saturate",
+    "K8s::Rbac::ClusterRole": "the cluster-scoped twin of an RBAC role, and a grant for the same reason",
+    "K8s::Rbac::ClusterRoleBinding": "the cluster-scoped twin of an RBAC binding, and a grant for the same reason",
+    "K8s::Core::ServiceAccount": "an identity, not a workload",
+    "K8s::Core::Namespace": "a boundary the workloads sit inside, and the workloads carry the figures",
+    "K8s::Networking::IngressClass": "names which controller handles an Ingress; the controller and the load balancer it creates carry the figures",
+    "K8s::Networking::NetworkPolicy": "a filter on edges that already exist, not a thing at either end of one",
+    "K8s::Storage::StorageClass": "the kind of disk a claim may ask for; the PersistentVolumeClaim carries the figures",
+    "K8s::Autoscaling::HorizontalPodAutoscaler": "an instruction about how many replicas to run; the workload it scales carries the figures, and a prediction is at one stated traffic level rather than across a scaling range",
+    "K8s::HorizontalPodAutoscaler": "an instruction about how many replicas to run; the workload it scales carries the figures, and a prediction is at one stated traffic level rather than across a scaling range",
+    "K8s::Policy::PodDisruptionBudget": "a constraint on voluntary eviction. It shapes what a lost zone does to a workload and has no rate of its own; expressing that constraint to an engine is a resilience input this contract has no field for",
+    "K8s::Core::LimitRange": "a default and a ceiling for workloads in a namespace; the workloads carry the figures",
+    "K8s::Core::ResourceQuota": "a ceiling on a namespace's total requests; the workloads under it carry the figures",
+    // ── A controller's request is not the thing it creates ───────────
+    "K8s::Argo::Application": "a request to Argo CD to reconcile a source; whatever it creates is priced where that lands",
+    "K8s::Flux::GitRepository": "a source Flux polls; the workloads it reconciles carry the figures",
+    "K8s::Flux::Kustomization": "a request to Flux to apply a source; whatever it creates is priced where that lands",
+    "K8s::CertManager::Certificate": "a request to an issuer. The certificate costs nothing; the issuer's work and the Secret it writes are elsewhere",
+    "K8s::CertManager::ClusterIssuer": "the issuer a certificate request names; it holds no capacity and serves no traffic",
+    "K8s::ExternalSecrets::ExternalSecret": "a request to copy a value from an external store into a Secret; neither end is a rate",
+    "K8s::ExternalSecrets::ClusterSecretStore": "names where secrets are fetched from; it holds no capacity and serves no traffic",
+    "K8s::Monitoring::ServiceMonitor": "tells Prometheus what to scrape; Prometheus is a workload elsewhere in the graph and carries the figures",
+    "K8s::Monitoring::PrometheusRule": "alerting and recording rules evaluated by Prometheus, which carries the figures",
+    "K8s::Traefik::IngressRoute": "routing handled by the Traefik workload, which carries the figures",
+    "K8s::Calico::FelixConfiguration": "tuning for the CNI agent on every node; the nodes carry the figures",
+    "K8s::GKE::BackendConfig": "tuning for a Google load balancer an Ingress creates; the gcp substrate is not modelled here, so neither end is priced here",
+    "K8s::NetworkingGKE::ManagedCertificate": "a certificate Google issues for an Ingress; the gcp substrate is not modelled here",
+    "K8s::NetworkingGKEBeta::FrontendConfig": "tuning for a Google load balancer an Ingress creates; the gcp substrate is not modelled here",
+    // ── Configuration and secrets: real, declared, carrying no rate ──
+    "K8s::Core::ConfigMap": "configuration the workloads read; it has no rate and no saturation axis of its own",
+    "K8s::Core::Secret": "configuration the workloads read; it has no rate and no saturation axis of its own",
+};
+/** This lexicon's answer for its own types. */
+export const k8sBehaviourKinds = {
+    provider: "kubernetes",
+    prefixes: ["K8s::"],
+    mapped: MAPPED,
+    unmapped: UNMAPPED,
+};

package/dist/codegen/docs-cli.js

@@ -0,0 +1,2 @@
+import { generateDocs } from "./docs.js";
+await generateDocs({ verbose: true });

package/dist/codegen/docs.js

@@ -0,0 +1,146 @@
+/**
+ * Documentation generation for the Kubernetes lexicon.
+ *
+ * Generates Starlight MDX pages for K8s entities using the core docs pipeline.
+ */
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { docsPipeline, writeDocsSite } from "@intentius/chant/codegen/docs";
+/**
+ * Extract service name from K8s type: "K8s::Apps::Deployment" → "Apps"
+ */
+function serviceFromType(resourceType) {
+    const parts = resourceType.split("::");
+    return parts.length >= 2 ? parts[1] : "Core";
+}
+const overview = `The **Kubernetes** lexicon provides typed constructors for Kubernetes resource
+manifests. It covers Deployments, Services, ConfigMaps, StatefulSets, Jobs,
+Ingress, RBAC, and 147 resources and 50 property types.
+
+New? Start with the [Getting Started](/chant/lexicons/k8s/getting-started/) guide.
+
+Install it with:
+
+\`\`\`bash
+npm install --save-dev @intentius/chant-lexicon-k8s
+\`\`\`
+
+## Quick Start
+
+\`\`\`typescript
+import { Deployment, Service, Container, Probe } from "@intentius/chant-lexicon-k8s";
+
+export const deployment = new Deployment({
+  metadata: { name: "my-app", labels: { "app.kubernetes.io/name": "my-app" } },
+  spec: {
+    replicas: 2,
+    selector: { matchLabels: { "app.kubernetes.io/name": "my-app" } },
+    template: {
+      metadata: { labels: { "app.kubernetes.io/name": "my-app" } },
+      spec: {
+        containers: [
+          new Container({
+            name: "app",
+            image: "my-app:1.0",
+            ports: [{ containerPort: 8080, name: "http" }],
+            livenessProbe: new Probe({ httpGet: { path: "/healthz", port: 8080 } }),
+            readinessProbe: new Probe({ httpGet: { path: "/readyz", port: 8080 } }),
+          }),
+        ],
+      },
+    },
+  },
+});
+
+export const service = new Service({
+  metadata: { name: "my-app" },
+  spec: {
+    selector: { "app.kubernetes.io/name": "my-app" },
+    ports: [{ port: 80, targetPort: 8080, name: "http" }],
+  },
+});
+\`\`\`
+
+The lexicon provides **147 resource types** (Deployment, Service, ConfigMap, StatefulSet, and more), **50 property types** (Container, Probe, Volume, SecurityContext, etc.), and composites (WebApp, StatefulApp, CronWorkload, AutoscaledService, WorkerPool, NamespaceEnv, NodeAgent) for common patterns.
+`;
+const outputFormat = `The Kubernetes lexicon serializes resources into **multi-document YAML** with
+\`---\` separators between resources. Each resource gets the standard K8s
+structure: \`apiVersion\`, \`kind\`, \`metadata\`, and \`spec\`.
+
+## Building
+
+Run \`chant build\` to produce Kubernetes manifests from your declarations:
+
+\`\`\`bash
+chant build src/ --output dist/manifests.yaml
+# Writes dist/manifests.yaml
+\`\`\`
+
+The generated file includes:
+
+- Multi-document YAML with \`---\` separators
+- Correct \`apiVersion\` and \`kind\` for each resource
+- \`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 |
+|--------------------|-------------|------|
+| \`export const myApp = new Deployment({...})\` | \`metadata.name: my-app\` | Export name → kebab-case |
+| \`new Container({...})\` | Inline container spec | Property types expanded inline |
+| \`defaultLabels({...})\` | Merged into all resources | Project-wide label injection |
+
+## Applying
+
+The output is standard Kubernetes YAML. Apply with kubectl:
+
+\`\`\`bash
+# Dry run first
+kubectl apply -f dist/manifests.yaml --dry-run=server
+
+# Apply
+kubectl apply -f dist/manifests.yaml
+
+# Diff before applying
+kubectl diff -f dist/manifests.yaml
+\`\`\`
+
+## Compatibility
+
+The output is compatible with:
+- kubectl apply/diff
+- Helm (as raw manifests)
+- ArgoCD / Flux GitOps controllers
+- Kustomize (as a base)
+- Any tool that processes Kubernetes YAML`;
+/**
+ * Generate documentation for the Kubernetes lexicon.
+ */
+export async function generateDocs(opts) {
+    const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+    const config = {
+        name: "k8s",
+        displayName: "Kubernetes",
+        description: "Typed constructors for Kubernetes resource manifests",
+        distDir: join(pkgDir, "dist"),
+        outDir: join(pkgDir, "docs"),
+        overview,
+        outputFormat,
+        serviceFromType,
+        suppressPages: ["pseudo-parameters"],
+        basePath: "/chant/lexicons/k8s/",
+    };
+    const result = await docsPipeline(config);
+    writeDocsSite(config, result);
+    if (opts?.verbose) {
+        console.error(`Generated docs: ${result.stats.resources} resources, ${result.stats.properties} properties, ${result.stats.services} services, ${result.stats.rules} rules`);
+    }
+}

package/dist/codegen/generate-cli.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env tsx
+/**
+ * CLI entry point for Kubernetes lexicon generation.
+ */
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { generate, writeGeneratedFiles } from "./generate.js";
+import { K8S_SCHEMA_VERSION } from "../spec/fetch.js";
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+async function main() {
+    const verbose = process.argv.includes("--verbose") || process.argv.includes("-v");
+    const force = process.argv.includes("--force") || process.argv.includes("-f");
+    // Parse --schema-version <ref>
+    const versionIdx = process.argv.indexOf("--schema-version");
+    const schemaVersion = versionIdx !== -1 ? process.argv[versionIdx + 1] : undefined;
+    console.error(`Generating Kubernetes lexicon (schema: ${schemaVersion ?? K8S_SCHEMA_VERSION})...`);
+    const result = await generate({ verbose, force, schemaVersion });
+    writeGeneratedFiles(result, pkgDir);
+    console.error(`Generated ${result.resources} resources, ${result.properties} property types, ${result.enums} enums`);
+    if (result.warnings.length > 0) {
+        console.error(`${result.warnings.length} warnings:`);
+        for (const w of result.warnings) {
+            console.error(`  ${w.file}: ${w.error}`);
+        }
+    }
+}
+main().catch((err) => {
+    console.error("Generation failed:", err);
+    process.exit(1);
+});

package/dist/codegen/generate-lexicon.js

@@ -0,0 +1,74 @@
+/**
+ * Lexicon JSON generator — produces lexicon-k8s.json with metadata
+ * for all Kubernetes resource and property types.
+ */
+import { k8sShortName, gvkToApiVersion } from "../spec/parse.js";
+import { buildRegistry, serializeRegistry, } from "@intentius/chant/codegen/generate-registry";
+/**
+ * Generate the lexicon-k8s.json content.
+ */
+export function generateLexiconJSON(results, naming) {
+    const registryResources = results.map((r) => ({
+        typeName: r.resource.typeName,
+        attributes: r.resource.attributes,
+        properties: r.resource.properties,
+        propertyTypes: r.propertyTypes.map((pt) => ({ name: pt.name, specType: pt.defType })),
+    }));
+    const entries = buildRegistry(registryResources, naming, {
+        shortName: k8sShortName,
+        buildEntry: (resource, _tsName, _attrs, propConstraints) => {
+            const r = results.find((res) => res.resource.typeName === resource.typeName);
+            const entry = {
+                resourceType: resource.typeName,
+                kind: (r?.isProperty ? "property" : "resource"),
+                lexicon: "k8s",
+            };
+            if (r && !r.isProperty) {
+                entry.apiVersion = gvkToApiVersion(r.gvk);
+                entry.gvkKind = r.gvk.kind;
+            }
+            if (r?.resource.deprecatedProperties?.length) {
+                entry.deprecatedProperties = r.resource.deprecatedProperties;
+            }
+            if (propConstraints && Object.keys(propConstraints).length > 0) {
+                entry.constraints = propConstraints;
+            }
+            if (r?.specSchema) {
+                entry.specSchema = r.specSchema;
+            }
+            return entry;
+        },
+        buildPropertyEntry: (resourceType, propertyType) => ({
+            resourceType: `${resourceType}.${propertyType}`,
+            kind: "property",
+            lexicon: "k8s",
+        }),
+    });
+    return serializeWithCompactSchemas(entries);
+}
+/**
+ * Pretty-print the registry the way every lexicon does, but keep each
+ * `specSchema` on one line (chant #1372). A CRD schema nests deeply — an
+ * ApplicationSet or RayCluster embeds a whole PodTemplateSpec — and two-space
+ * indentation on that tree quadruples the file for no reader's benefit.
+ * Compact, the schemas add ~0.8 MB to the registry; pretty, ~3.9 MB.
+ */
+export function serializeWithCompactSchemas(entries) {
+    const compact = new Map();
+    const stripped = {};
+    for (const [name, entry] of Object.entries(entries)) {
+        if (!entry.specSchema) {
+            stripped[name] = entry;
+            continue;
+        }
+        const { specSchema, ...rest } = entry;
+        const token = `__chant_spec_schema_${compact.size}__`;
+        compact.set(token, JSON.stringify(specSchema));
+        stripped[name] = { ...rest, specSchema: token };
+    }
+    let out = serializeRegistry(stripped);
+    for (const [token, json] of compact) {
+        out = out.replace(`"${token}"`, json);
+    }
+    return out;
+}

package/dist/codegen/generate-list-map-keys.js

@@ -0,0 +1,88 @@
+/**
+ * Associative-list key table, derived from the spec rather than hardcoded
+ * (chant #1441).
+ *
+ * The Kubernetes OpenAPI spec states, per property, how the API server merges
+ * a list: `x-kubernetes-list-type: map` plus `x-kubernetes-list-map-keys`
+ * naming the fields that jointly identify one element. chant's drift engine
+ * needs exactly that to compare `containers` by name rather than by index.
+ * Before this, `k8sListMapOrderKey` (core's `managed-fields.ts`) hardcoded six
+ * properties; the spec annotates 32.
+ *
+ * ## Why the table is keyed by property name
+ *
+ * The consumer is `DeepNormalizationHooks.orderKey`, which receives an
+ * index-erased `pattern` (`spec.template.spec.containers`) and keys off its
+ * LAST segment. A by-name table matches that lookup exactly and needs no
+ * resolution of the definition graph at generation time.
+ *
+ * The cost is that two definitions declaring the same property name with
+ * different keys collapse into one entry. That is real but small, and it is
+ * represented rather than lost: each name maps to a LIST of candidate key
+ * sets, and the consumer picks the first whose fields are all present on the
+ * element. In v1.36.2 exactly one property needs it — `ports`, keyed
+ * `(containerPort, protocol)` on a container and `(port, protocol)` on a
+ * Service — which is the same dual shape the hardcoded implementation already
+ * special-cased by hand.
+ *
+ * ## Two sources
+ *
+ * The whole spec is read directly, because chant emits types for 257 of
+ * roughly a thousand definitions and the merge semantics of a definition are
+ * worth having whether or not it becomes a type. Reading only the parsed
+ * results finds 18 of the 32 properties and misses `ServicePort.port`.
+ *
+ * Parsed results are read too, because CRDs arrive that way — an operator CRD
+ * that declares these extensions contributes its keys for free.
+ */
+function everyProperty(results) {
+    const out = [];
+    for (const r of results) {
+        out.push(...r.resource.properties);
+        for (const pt of r.propertyTypes)
+            out.push(...pt.properties);
+    }
+    return out;
+}
+/** The `(name, keys)` pairs carried on parsed properties — core types and every CRD. */
+export function parsedListMapKeyPairs(results) {
+    const pairs = [];
+    for (const p of everyProperty(results)) {
+        if (p.listType === "map" && p.listMapKeys?.length)
+            pairs.push([p.name, p.listMapKeys]);
+    }
+    return pairs;
+}
+/**
+ * Fold `(name, keys)` pairs into a by-name table.
+ *
+ * Candidate sets are deduplicated by content and ordered longest-first, so a
+ * more specific key set is tried before a shorter one whose fields a longer
+ * element would also satisfy.
+ */
+export function buildListMapKeyTable(...sources) {
+    const byName = new Map();
+    for (const pairs of sources) {
+        for (const [name, rawKeys] of pairs) {
+            const keys = [...rawKeys].sort();
+            const seen = byName.get(name) ?? new Map();
+            seen.set(keys.join(" "), keys);
+            byName.set(name, seen);
+        }
+    }
+    const table = {};
+    for (const name of [...byName.keys()].sort()) {
+        const variants = byName.get(name);
+        if (!variants)
+            continue;
+        const sets = [...variants.values()];
+        sets.sort((a, b) => b.length - a.length || a.join().localeCompare(b.join()));
+        table[name] = sets;
+    }
+    return table;
+}
+/** Serialize the `list-map-keys.json` generated artifact. */
+export function generateListMapKeysJSON(specPairs, results) {
+    const table = buildListMapKeyTable(specPairs, parsedListMapKeyPairs(results));
+    return `${JSON.stringify(table, null, 2)}\n`;
+}

package/dist/codegen/generate-operations.js

@@ -0,0 +1,53 @@
+/**
+ * The generated operation surface — chant #1074.
+ *
+ * `describeResources` used to reach the cluster through a hand-written
+ * `entityType → kubectl resource` map with twenty entries in it. Every one of
+ * the other ~180 generated resource types, and every CRD, fell off the end of
+ * it. The map was hand-maintained precisely because nothing derived it, and
+ * nothing derived it because the codegen pass that produces the types never
+ * emitted the addressing half.
+ *
+ * It does now. This artifact is written by the same `generate()` run that
+ * writes `lexicon-k8s.json` and `index.d.ts`, out of the same parsed results,
+ * so a resource that has a declarable class necessarily has an operation entry
+ * with the same apiVersion and kind. `operation-surface.test.ts` asserts that
+ * correspondence rather than trusting it.
+ *
+ * What it is not: an authority on what a given cluster serves. `plural` and
+ * `scope` are what the schema says; the live client confirms both against the
+ * cluster's own discovery before addressing anything, because a cluster can
+ * serve a different version of a CRD than the one chant generated from.
+ */
+import { gvkToApiVersion } from "../spec/parse.js";
+import { pluralizeKind } from "../api/operation-surface.js";
+/** Build the operation table from the same parsed results the types come from. */
+export function buildOperationTable(results) {
+    const table = {};
+    for (const result of results) {
+        if (result.isProperty)
+            continue;
+        const entityType = result.resource.typeName;
+        // A later result for the same type wins nothing — the first parse of a
+        // preferred version is canonical, matching the registry's own precedence.
+        if (table[entityType])
+            continue;
+        table[entityType] = {
+            entityType,
+            apiVersion: gvkToApiVersion(result.gvk),
+            kind: result.gvk.kind,
+            plural: result.operation?.plural ?? pluralizeKind(result.gvk.kind),
+            scope: result.operation?.scope ?? "Namespaced",
+            verbs: result.operation?.verbs ?? [],
+        };
+    }
+    return table;
+}
+/** Serialize the table, key-sorted so regeneration produces a stable diff. */
+export function generateOperationsJSON(results) {
+    const table = buildOperationTable(results);
+    const sorted = {};
+    for (const key of Object.keys(table).sort())
+        sorted[key] = table[key];
+    return `${JSON.stringify(sorted, null, 2)}\n`;
+}