@intentius/chant-lexicon-k8s 0.124.31 → 0.124.33

package/dist/actions/apps.js

@@ -0,0 +1,18 @@
+/**
+ * RBAC verb constants for apps API group resources.
+ */
+import { StandardVerbs } from "./core.js";
+export const DeploymentActions = {
+    ...StandardVerbs,
+    rollback: "create", // deployments/rollback subresource
+    scale: "update", // deployments/scale subresource
+};
+export const StatefulSetActions = {
+    ...StandardVerbs,
+    scale: "update",
+};
+export const DaemonSetActions = { ...StandardVerbs };
+export const ReplicaSetActions = {
+    ...StandardVerbs,
+    scale: "update",
+};

package/dist/actions/batch.js

@@ -0,0 +1,6 @@
+/**
+ * RBAC verb constants for batch API group resources.
+ */
+import { StandardVerbs } from "./core.js";
+export const JobActions = { ...StandardVerbs };
+export const CronJobActions = { ...StandardVerbs };

package/dist/actions/core.js

@@ -0,0 +1,48 @@
+/**
+ * RBAC verb constants for core API group resources.
+ */
+/** Standard RBAC verbs applicable to most resources. */
+export const StandardVerbs = {
+    get: "get",
+    list: "list",
+    watch: "watch",
+    create: "create",
+    update: "update",
+    patch: "patch",
+    delete: "delete",
+};
+export const PodActions = {
+    ...StandardVerbs,
+    exec: "create", // pods/exec subresource
+    portForward: "create", // pods/portforward subresource
+    log: "get", // pods/log subresource
+};
+export const ServiceActions = {
+    ...StandardVerbs,
+    proxy: "create",
+};
+export const ConfigMapActions = { ...StandardVerbs };
+export const SecretActions = { ...StandardVerbs };
+export const NamespaceActions = { ...StandardVerbs };
+export const ServiceAccountActions = {
+    ...StandardVerbs,
+    impersonate: "impersonate",
+};
+export const PersistentVolumeActions = { ...StandardVerbs };
+export const PersistentVolumeClaimActions = { ...StandardVerbs };
+export const NodeActions = {
+    get: "get",
+    list: "list",
+    watch: "watch",
+    update: "update",
+    patch: "patch",
+};
+export const EventActions = {
+    get: "get",
+    list: "list",
+    watch: "watch",
+    create: "create",
+};
+export const ResourceQuotaActions = { ...StandardVerbs };
+export const LimitRangeActions = { ...StandardVerbs };
+export const EndpointsActions = { ...StandardVerbs };

package/dist/actions/index.js

@@ -0,0 +1,13 @@
+/**
+ * Kubernetes RBAC verb constants — organized by API group.
+ */
+// Core
+export { StandardVerbs, PodActions, ServiceActions, ConfigMapActions, SecretActions, NamespaceActions, ServiceAccountActions, PersistentVolumeActions, PersistentVolumeClaimActions, NodeActions, EventActions, ResourceQuotaActions, LimitRangeActions, EndpointsActions, } from "./core.js";
+// Apps
+export { DeploymentActions, StatefulSetActions, DaemonSetActions, ReplicaSetActions, } from "./apps.js";
+// RBAC
+export { RoleActions, ClusterRoleActions, RoleBindingActions, ClusterRoleBindingActions, } from "./rbac.js";
+// Batch
+export { JobActions, CronJobActions, } from "./batch.js";
+// Networking
+export { IngressActions, IngressClassActions, NetworkPolicyActions, } from "./networking.js";

package/dist/actions/networking.js

@@ -0,0 +1,11 @@
+/**
+ * RBAC verb constants for networking.k8s.io API group resources.
+ */
+import { StandardVerbs } from "./core.js";
+export const IngressActions = { ...StandardVerbs };
+export const IngressClassActions = {
+    get: "get",
+    list: "list",
+    watch: "watch",
+};
+export const NetworkPolicyActions = { ...StandardVerbs };

package/dist/actions/rbac.js

@@ -0,0 +1,8 @@
+/**
+ * RBAC verb constants for rbac.authorization.k8s.io API group.
+ */
+import { StandardVerbs } from "./core.js";
+export const RoleActions = { ...StandardVerbs };
+export const ClusterRoleActions = { ...StandardVerbs };
+export const RoleBindingActions = { ...StandardVerbs };
+export const ClusterRoleBindingActions = { ...StandardVerbs };

package/dist/api/classify.js

@@ -0,0 +1,123 @@
+/**
+ * Typed API failure → the observation tri-state (chant #1089, #1074).
+ *
+ * `classifyKubectlFailure` in core does this by matching English on stderr,
+ * because that was all `kubectl` gave it. The API server has always sent a
+ * `Status` object with a numeric code and a `reason` enum; the typed client
+ * carries it through, so classification here reads fields rather than
+ * searching for substrings. The verdicts are deliberately the same ones the
+ * kubectl path produced — this replaces the evidence, not the contract.
+ *
+ * The one that reads as a surprise, and is not: **a kind the cluster does not
+ * serve is an absence, not a hole.** No instance of an unserved kind can exist
+ * there, and the usual cause is a CRD the very plan being computed has not
+ * applied yet. Calling it NOT-OBSERVED would suppress the create that is
+ * genuinely needed. That is core's existing rule (`classifyKubectlFailure`
+ * treats "the server doesn't have a resource type" as absent) and it survives
+ * the move intact.
+ *
+ * Errors are discriminated by `name`, not `instanceof`. The client is an
+ * optional dependency reached through a dynamic import, so this module must
+ * not carry a static value import of it — and `name` is set explicitly by
+ * every one of its error classes, which also makes the classification survive
+ * a duplicated copy of the package in a consumer's tree.
+ */
+/** The client's error names, as its classes stamp them. */
+const NAMES = {
+    api: "K8sApiError",
+    transport: "K8sTransportError",
+    unavailable: "K8sClientUnavailableError",
+    execRefused: "ExecCredentialNotAllowedError",
+    kubeconfig: "KubeConfigError",
+    unknownResource: "UnknownResourceError",
+};
+function shapeOf(err) {
+    return (typeof err === "object" && err !== null ? err : {});
+}
+/** Classify a failure from the typed client into the observation tri-state. */
+export function classifyApiFailure(err) {
+    const e = shapeOf(err);
+    switch (e.name) {
+        // The cluster's discovery does not serve this kind, so no instance of it
+        // exists here. A real absence — see the module comment.
+        case NAMES.unknownResource:
+            return { kind: "absent" };
+        case NAMES.api: {
+            const code = e.statusCode;
+            if (code === 404 || e.reason === "NotFound")
+                return { kind: "absent" };
+            if (code === 401 || code === 403 || e.reason === "Unauthorized" || e.reason === "Forbidden") {
+                return { kind: "unobserved", reason: "no-credentials", detail: detailOf(err) };
+            }
+            return { kind: "unobserved", reason: "read-failed", detail: detailOf(err) };
+        }
+        // Never reached an API server: DNS, TCP, TLS, proxy, abort. Says nothing
+        // about what is running there. Same verdict the kubectl path gave
+        // "unable to connect to the server".
+        case NAMES.transport:
+            return { kind: "unobserved", reason: "no-binding", detail: detailOf(err) };
+        // No usable kubeconfig / cluster / context for this environment.
+        case NAMES.kubeconfig:
+            return { kind: "unobserved", reason: "no-binding", detail: detailOf(err) };
+        // The credential path itself was refused, so nothing was ever authorized.
+        case NAMES.execRefused:
+            return { kind: "unobserved", reason: "no-credentials", detail: detailOf(err) };
+        // The client package is not installed — chant could not look, which is a
+        // hole and emphatically not an empty cluster.
+        case NAMES.unavailable:
+            return { kind: "unobserved", reason: "read-failed", detail: detailOf(err) };
+        default:
+            return { kind: "unobserved", reason: "read-failed", detail: detailOf(err) };
+    }
+}
+/**
+ * The cluster's own discovery reports no such kind at all — distinct from a
+ * kind that exists but currently has zero live instances. `classifyApiFailure`
+ * folds both into `absent` for the declared-entity read path, where "no
+ * instance can exist" is exactly the signal a `create` needs. `chant kube get`
+ * (chant #1079) needs the finer distinction: an ad hoc `chant kube get
+ * widgets` against a kind the cluster has never heard of should say so, not
+ * print "No resources found." as if `widgets` were a real, empty kind.
+ */
+export function isUnknownResource(err) {
+    return shapeOf(err).name === NAMES.unknownResource;
+}
+/**
+ * Whether a failure kills the whole observation rather than one entity. A
+ * refused binding, a missing client package and a rejected credential plugin
+ * are all true of every entity, so they propagate and core marks the lot
+ * NOT-OBSERVED with one reason instead of repeating the same failure N times.
+ */
+export function isWholeLexiconFailure(err) {
+    const name = shapeOf(err).name;
+    return name === NAMES.kubeconfig || name === NAMES.execRefused || name === NAMES.unavailable;
+}
+/**
+ * A dynamic import of the optional client package that failed to resolve looks
+ * like an ordinary module error. Recognizing it lets `describeResources` report
+ * a missing dependency as a missing dependency rather than as a broken cluster.
+ */
+export function isMissingClientPackage(err) {
+    const e = shapeOf(err);
+    if (e.name === NAMES.unavailable)
+        return true;
+    if (e.code !== "ERR_MODULE_NOT_FOUND" && e.code !== "MODULE_NOT_FOUND")
+        return false;
+    return (e.message ?? "").includes("@intentius/chant-k8s-client") || (e.message ?? "").includes("@kubernetes/client-node");
+}
+/** The message a missing client package should produce. */
+export const MISSING_CLIENT_DETAIL = "the Kubernetes API client is not installed — run `npm i @intentius/chant-k8s-client` " +
+    "(it is an optional dependency of @intentius/chant-lexicon-k8s, so `--omit=optional` installs skip it)";
+function detailOf(err) {
+    const text = err instanceof Error ? err.message : String(err);
+    const line = text.split("\n").find((l) => l.trim().length > 0)?.trim() ?? text.trim();
+    const capped = line.length > 200 ? `${line.slice(0, 197)}...` : line;
+    // #1488 — a reason that does not say which cluster was read turned an
+    // ambient-context switch into an afternoon. The client stamps the context it
+    // resolved onto every failure. The note LEADS the detail (#1620): consumers
+    // truncate a reason to its first line and ~160 chars, and a note appended
+    // after a long error is cut off exactly when the error is long enough to
+    // need it. Leading, it survives any suffix truncation.
+    const note = shapeOf(err).contextNote;
+    return note ? `${note} — ${capped}` : capped;
+}

package/dist/api/connect.js

@@ -0,0 +1,62 @@
+/**
+ * Getting from a chant environment to a live API client — chant #1074.
+ *
+ * The cluster binding (chant #1100/#1155, revised by #1488):
+ * `resolveClusterTarget` in core stays the single resolver, and a declared
+ * binding is now *used*, never policed against the ambient context. Two
+ * outcomes:
+ *
+ * - **Bound** — the bound context is passed explicitly to the client,
+ *   regardless of what `kubectl` is ambiently pointed at. A binding that
+ *   names a context the kubeconfig does not have fails in the client with an
+ *   error naming both the context and the `k8s.profiles.<env>.context`
+ *   binding — never by falling back to ambient. (#1488: the old
+ *   ambient-mismatch refusal meant any other project's k3d cluster stealing
+ *   the current-context turned a healthy estate grey with `read-failed` as
+ *   the only explanation.)
+ * - **Unbound** — the kubeconfig's own current-context, with a visible
+ *   warning naming the environment and the missing binding.
+ */
+import { loadChantConfig } from "@intentius/chant/config";
+import { resolveClusterTarget } from "@intentius/chant/kubectl-context";
+/**
+ * The production connector: read the project's config, resolve the binding,
+ * build a client honoring it.
+ */
+export const defaultK8sConnector = async (options) => {
+    const { createK8sClient } = await import("@intentius/chant-k8s-client");
+    if (options.context !== undefined) {
+        const client = await createK8sClient({
+            context: options.context,
+            contextSource: "bound",
+            contextLabel: "explicit --context",
+            ...options.client,
+        });
+        return { client, target: { context: options.context, source: "bound" } };
+    }
+    if (options.environment === undefined) {
+        const client = await createK8sClient({ contextSource: "ambient", ...options.client });
+        return { client, target: { source: "ambient" } };
+    }
+    const { config } = await loadChantConfig(options.cwd ?? process.cwd());
+    const k8sConfig = config.k8s;
+    const execAllowlist = k8sConfig?.execCredentialPlugins;
+    // #1488 — the resolver returns the declared binding (or ambient-with-warning
+    // when unbound); it no longer reads the ambient context at all, so no reader
+    // is supplied.
+    const target = await resolveClusterTarget(config, options.environment, "k8s");
+    // #1488 — every failure the client throws names the cluster it read and how
+    // that cluster was selected, so a `read-failed` against the wrong context is
+    // legible from the reason alone.
+    const contextLabel = target.source === "bound"
+        ? `bound by k8s.profiles.${options.environment}.context`
+        : `ambient; no k8s.profiles.${options.environment} binding`;
+    const client = await createK8sClient({
+        ...options.client,
+        ...(target.context ? { context: target.context } : {}),
+        contextSource: target.source,
+        contextLabel,
+        ...(execAllowlist ? { execAllowlist } : {}),
+    });
+    return { client, target };
+};

package/dist/api/fake-cluster.js

@@ -0,0 +1,175 @@
+/**
+ * A fake cluster to point the k8s lexicon at, for tests (chant #1074).
+ *
+ * It builds a **real** `@intentius/chant-k8s-client` over a literal kubeconfig
+ * with `@kubernetes/client-node`'s HTTP send replaced. So kubeconfig parsing,
+ * context selection, the credential policy, API discovery, path construction
+ * and the auth path all run for real; the only thing that does not happen is
+ * the socket. Nothing reads `~/.kube/config` or `$KUBECONFIG`, and nothing can
+ * reach a cluster the developer happens to have a context for.
+ *
+ * Shipped rather than kept in a test file because the lexicon's own tests, the
+ * cross-lexicon lifecycle suite and a consumer wiring chant into their harness
+ * all need the same thing.
+ */
+import { apiResourceList, fakeKubeconfig, fakeRequestLayer, statusBody } from "@intentius/chant-k8s-client/testing";
+import { createK8sClient } from "@intentius/chant-k8s-client";
+import { operationTable } from "./operation-surface.js";
+/** Key an object the way {@link fakeCluster} indexes them. */
+export function objectKey(apiVersion, kind, name, namespace) {
+    return `${apiVersion}/${kind}/${namespace ?? "_"}/${name}`;
+}
+/** Build a live object with chant's ownership marker already on it. */
+export function ownedObject(apiVersion, kind, name, namespace, extra = {}) {
+    return {
+        apiVersion,
+        kind,
+        metadata: {
+            name,
+            ...(namespace ? { namespace } : {}),
+            uid: `uid-${name}`,
+            resourceVersion: "1",
+            labels: { "app.kubernetes.io/managed-by": "chant" },
+            ...(extra.metadata ?? {}),
+        },
+        ...(extra.status ? { status: extra.status } : {}),
+    };
+}
+function servedResources(serves) {
+    const table = operationTable();
+    const entries = serves
+        ? serves.map((s) => table[s]).filter((d) => d !== undefined)
+        : Object.values(table);
+    return entries
+        .filter((d) => d.verbs.length > 0)
+        .map((d) => ({
+        apiVersion: d.apiVersion,
+        kind: d.kind,
+        plural: d.plural,
+        namespaced: d.scope === "Namespaced",
+    }));
+}
+/**
+ * A cluster that answers discovery for the kinds it serves and holds the
+ * objects it was given. Anything else 404s with a real `Status` body, which is
+ * how a test drives the absent branch of the observation tri-state.
+ */
+export function fakeCluster(options = {}) {
+    const resources = servedResources(options.serves);
+    const byApiVersion = new Map();
+    for (const r of resources) {
+        const list = byApiVersion.get(r.apiVersion) ?? [];
+        list.push(r);
+        byApiVersion.set(r.apiVersion, list);
+    }
+    // Path → the object it addresses, and list path → its members, precomputed
+    // so the responder below is a pair of lookups.
+    const byPath = new Map();
+    const listPaths = new Map();
+    const addToList = (path, object) => {
+        const list = listPaths.get(path) ?? [];
+        list.push(object);
+        listPaths.set(path, list);
+    };
+    for (const [key, object] of Object.entries(options.objects ?? {})) {
+        const [group, version, kind, namespace, name] = splitKey(key);
+        const apiVersion = group ? `${group}/${version}` : version;
+        const resource = resources.find((r) => r.apiVersion === apiVersion && r.kind === kind);
+        if (!resource)
+            continue;
+        const base = apiVersion.includes("/") ? `/apis/${apiVersion}` : `/api/${apiVersion}`;
+        if (resource.namespaced) {
+            const ns = namespace === "_" ? "default" : namespace;
+            byPath.set(`${base}/namespaces/${ns}/${resource.plural}/${name}`, object);
+            addToList(`${base}/namespaces/${ns}/${resource.plural}`, object);
+        }
+        else {
+            byPath.set(`${base}/${resource.plural}/${name}`, object);
+        }
+        // Cluster-wide list, which is what `chant import` sweeps.
+        addToList(`${base}/${resource.plural}`, object);
+    }
+    const groups = new Map();
+    for (const apiVersion of byApiVersion.keys()) {
+        if (!apiVersion.includes("/"))
+            continue;
+        const group = apiVersion.slice(0, apiVersion.indexOf("/"));
+        if (!groups.has(group))
+            groups.set(group, apiVersion);
+    }
+    const layer = fakeRequestLayer((request) => {
+        const custom = options.respond?.(request);
+        if (custom !== undefined)
+            return custom;
+        if (request.path === "/api")
+            return { body: { kind: "APIVersions", versions: ["v1"] } };
+        if (request.path === "/apis") {
+            return {
+                body: {
+                    kind: "APIGroupList",
+                    groups: [...groups].map(([name, apiVersion]) => ({
+                        name,
+                        preferredVersion: { groupVersion: apiVersion, version: apiVersion.split("/")[1] },
+                        versions: [{ groupVersion: apiVersion }],
+                    })),
+                },
+            };
+        }
+        const apiVersion = apiVersionFromDiscoveryPath(request.path);
+        if (apiVersion) {
+            const served = byApiVersion.get(apiVersion);
+            if (!served)
+                return { status: 404, body: statusBody(404, "NotFound", "the server could not find the requested resource") };
+            return {
+                body: apiResourceList(apiVersion, served.map((r) => ({ name: r.plural, kind: r.kind, namespaced: r.namespaced }))),
+            };
+        }
+        const object = byPath.get(request.path);
+        if (object)
+            return { body: object };
+        if (isListPath(request.path, resources)) {
+            // 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`) };
+    });
+    const connects = [];
+    const connector = async (connectOptions) => {
+        connects.push(connectOptions);
+        const client = await createK8sClient({
+            kubeconfig: options.kubeconfig ?? fakeKubeconfig(),
+            requestLayer: layer,
+            ...(connectOptions.context ? { context: connectOptions.context } : {}),
+            ...connectOptions.client,
+        });
+        return { client, target: { source: "ambient" } };
+    };
+    return { connector, layer, connects };
+}
+function splitKey(key) {
+    const parts = key.split("/");
+    // `apps/v1/Deployment/prod/web` (5) or `v1/Service/prod/web` (4)
+    if (parts.length === 5)
+        return [parts[0], parts[1], parts[2], parts[3], parts[4]];
+    return ["", parts[0], parts[1], parts[2], parts[3]];
+}
+function apiVersionFromDiscoveryPath(path) {
+    if (/^\/api\/[^/]+$/.test(path))
+        return path.slice("/api/".length);
+    if (/^\/apis\/[^/]+\/[^/]+$/.test(path))
+        return path.slice("/apis/".length);
+    return undefined;
+}
+/** True when the path addresses a collection of a kind this cluster serves. */
+function isListPath(path, resources) {
+    const plural = path.split("/").pop();
+    return resources.some((r) => r.plural === plural);
+}

package/dist/api/operation-surface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operation-surface.d.ts","sourceRoot":"","sources":["../../src/api/operation-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,2EAA2E;AAC3E,MAAM,WAAW,sBAAsB;IACrC,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,YAAY,GAAG,SAAS,CAAC;IAChC,4DAA4D;IAC5D,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,4DAA4D;AAC5D,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;AAEvE;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKlD;AAqBD,+EAA+E;AAC/E,wBAAgB,cAAc,IAAI,iBAAiB,CAQlD;AAED,4CAA4C;AAC5C,wBAAgB,2BAA2B,IAAI,IAAI,CAElD;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS,CAKnF;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS,CAatF;AAED,2DAA2D;AAC3D,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAEjD"}
+{"version":3,"file":"operation-surface.d.ts","sourceRoot":"","sources":["../../src/api/operation-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,2EAA2E;AAC3E,MAAM,WAAW,sBAAsB;IACrC,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,YAAY,GAAG,SAAS,CAAC;IAChC,4DAA4D;IAC5D,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,4DAA4D;AAC5D,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;AAEvE;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKlD;AAqBD,+EAA+E;AAC/E,wBAAgB,cAAc,IAAI,iBAAiB,CAQlD;AAED,4CAA4C;AAC5C,wBAAgB,2BAA2B,IAAI,IAAI,CAElD;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS,CAKnF;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS,CAatF;AAED,2DAA2D;AAC3D,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAEjD"}

package/dist/api/operation-surface.js

@@ -0,0 +1,109 @@
+/**
+ * Reading the generated operation surface — chant #1074.
+ *
+ * The table itself is written by `chant generate` (see
+ * `../codegen/generate-operations.ts`); this is the runtime side, and it is
+ * deliberately the only place in the lexicon that knows how an entity type
+ * becomes an API address.
+ *
+ * Loading mirrors the serializer's handling of `lexicon-k8s.json`: a `require`
+ * behind a try/catch, so a checkout that has not run `chant generate` yet
+ * degrades to derivation rather than failing to import. Nothing here touches
+ * the filesystem at module load (chant #1081) — the first call does, and caches.
+ */
+import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
+const require = createRequire(moduleSourceUrl(import.meta.url));
+/**
+ * Fallback plural for a kind whose schema documented no named-object path.
+ *
+ * Kubernetes' own pluralization for resource names is the lowercased kind with
+ * English plural rules applied — the three cases `kubectl` implements. It only
+ * fires for kinds the OpenAPI paths do not cover, and the live client overrides
+ * it from the cluster's discovery regardless, so it is a placeholder rather
+ * than a second table to maintain.
+ */
+export function pluralizeKind(kind) {
+    const lower = kind.toLowerCase();
+    if (/(s|x|z|ch|sh)$/.test(lower))
+        return `${lower}es`;
+    if (/[^aeiou]y$/.test(lower))
+        return `${lower.slice(0, -1)}ies`;
+    return `${lower}s`;
+}
+/**
+ * Well-known API group → apiVersion, for a checkout with no generated table.
+ * Deliberately the same list the serializer falls back to, so a lexicon
+ * running without generated artifacts addresses what it serializes.
+ */
+const FALLBACK_GROUP_VERSIONS = {
+    Core: "v1",
+    Apps: "apps/v1",
+    Batch: "batch/v1",
+    Networking: "networking.k8s.io/v1",
+    Policy: "policy/v1",
+    Rbac: "rbac.authorization.k8s.io/v1",
+    Storage: "storage.k8s.io/v1",
+    Autoscaling: "autoscaling/v2",
+    Admissionregistration: "admissionregistration.k8s.io/v1",
+};
+let cached = null;
+/** The generated table, loaded once. Empty when nothing has been generated. */
+export function operationTable() {
+    if (cached)
+        return cached;
+    try {
+        cached = require("../generated/operations.json");
+    }
+    catch {
+        cached = {};
+    }
+    return cached;
+}
+/** Reset the memoized table. Tests only. */
+export function resetOperationTableForTests() {
+    cached = null;
+}
+/**
+ * How to address a declared entity type over the API.
+ *
+ * Returns undefined only for a type the generated surface does not carry and
+ * whose `K8s::<Group>::<Kind>` shape yields no known group — which is the one
+ * case where chant genuinely does not know what to ask for. Every generated
+ * resource type, including every CRD baked in at generation time, is in the
+ * table; that is the difference between this and the twenty-entry map it
+ * replaces.
+ */
+export function operationFor(entityType) {
+    const table = operationTable();
+    const found = table[entityType];
+    if (found)
+        return found;
+    return deriveOperation(entityType);
+}
+/**
+ * Last-resort derivation from the entity type's own shape, for a lexicon
+ * running without generated artifacts. It cannot invent an API group it has
+ * never seen, so an unknown group returns undefined rather than a guess that
+ * would address the wrong thing.
+ */
+export function deriveOperation(entityType) {
+    const parts = entityType.split("::");
+    if (parts.length !== 3 || parts[0] !== "K8s")
+        return undefined;
+    const apiVersion = FALLBACK_GROUP_VERSIONS[parts[1]];
+    if (!apiVersion)
+        return undefined;
+    return {
+        entityType,
+        apiVersion,
+        kind: parts[2],
+        plural: pluralizeKind(parts[2]),
+        scope: "Namespaced",
+        verbs: [],
+    };
+}
+/** Every entity type the generated surface can address. */
+export function addressableEntityTypes() {
+    return Object.keys(operationTable()).sort();
+}