@intentius/chant-lexicon-k8s 0.124.31 → 0.124.32

package/dist/subscribe-changes.js

@@ -0,0 +1,168 @@
+/**
+ * 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 { defaultK8sConnector } from "./api/connect.js";
+import { operationFor } from "./api/operation-surface.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 const MAX_WATCHES = 32;
+/**
+ * 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 function watchTargets(entities, defaultNamespace) {
+    const byKey = new Map();
+    const unaddressable = new Set();
+    for (const [, entity] of entities) {
+        const operation = operationFor(entity.entityType);
+        if (!operation) {
+            // chant knows no API address for this type, the same hole
+            // `describeResources` reports as `unsupported-kind`. Nothing to watch,
+            // and never a reason to widen to something else.
+            unaddressable.add(entity.entityType);
+            continue;
+        }
+        const declared = entity.props.metadata?.namespace;
+        const namespace = operation.scope === "Namespaced" ? (declared ?? defaultNamespace) : undefined;
+        const key = `${operation.apiVersion}|${operation.kind}|${namespace ?? ""}`;
+        if (!byKey.has(key)) {
+            byKey.set(key, {
+                apiVersion: operation.apiVersion,
+                kind: operation.kind,
+                ...(namespace ? { namespace } : {}),
+            });
+        }
+    }
+    return {
+        targets: [...byKey.values()].sort((a, b) => `${a.apiVersion}|${a.kind}|${a.namespace ?? ""}`.localeCompare(`${b.apiVersion}|${b.kind}|${b.namespace ?? ""}`)),
+        unaddressable: [...unaddressable].sort(),
+    };
+}
+/** Human phrasing of one target, for a log line. */
+function targetText(target) {
+    return `${target.apiVersion} ${target.kind}${target.namespace ? ` in ${target.namespace}` : ""}`;
+}
+/**
+ * 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 async function subscribeChanges(options, connect = defaultK8sConnector) {
+    const entities = options.entities;
+    if (!entities || entities.size === 0) {
+        throw new Error("no declared k8s entities in scope. A change signal watches what the project declares, and there is nothing to watch");
+    }
+    // The same connect path the read takes, so the cluster a signal comes from
+    // is the cluster a tick would read. A binding that refuses, refuses here.
+    const { client } = await connect({
+        environment: options.environment,
+        cwd: options.cwd,
+    });
+    const { targets, unaddressable } = watchTargets(entities, client.defaultNamespace);
+    if (unaddressable.length > 0) {
+        // A hole in the signal, reported the way a hole in an observation is:
+        // named, not swallowed. The timer still covers these kinds.
+        options.onError?.(`no API address for ${unaddressable.join(", ")}, so changes to those kinds are found on the timer alone`);
+    }
+    if (targets.length === 0) {
+        throw new Error("no watchable k8s kinds among the declared entities");
+    }
+    if (targets.length > MAX_WATCHES) {
+        throw new Error(`the declared estate needs ${targets.length} watch connections, past the ${MAX_WATCHES} ceiling, so it is ` +
+            "running on the operator's timer rather than opening a partial watch that would go quiet for the rest");
+    }
+    const handles = [];
+    /** Reported once for the whole subscription: the operator re-subscribes as a whole. */
+    let reported = false;
+    const reportOnce = (message) => {
+        if (reported)
+            return;
+        reported = true;
+        options.onError?.(message);
+    };
+    const stopOnAbort = () => {
+        void closeAll();
+    };
+    let closing;
+    const closeAll = () => {
+        if (!closing) {
+            options.signal.removeEventListener("abort", stopOnAbort);
+            const open = handles.splice(0, handles.length);
+            closing = Promise.allSettled(open.map((h) => h.close())).then(() => undefined);
+        }
+        return closing;
+    };
+    try {
+        for (const target of targets) {
+            handles.push(await client.watch({ apiVersion: target.apiVersion, kind: target.kind }, {
+                ...(target.namespace ? { namespace: target.namespace } : {}),
+                signal: options.signal,
+                // The whole consumption of a watch event, in one line: it happened,
+                // so look again. The frame is not read, not stored, not passed on.
+                onEvent: () => options.onChange(),
+                onError: (message) => reportOnce(`watch on ${targetText(target)} ended: ${message}`),
+            }));
+        }
+    }
+    catch (err) {
+        // A partial open is not a subscription. Unwind what did open, and let the
+        // operator report one failure and keep its timer.
+        await closeAll();
+        throw err;
+    }
+    if (options.signal.aborted)
+        await closeAll();
+    else
+        options.signal.addEventListener("abort", stopOnAbort, { once: true });
+    return { close: closeAll };
+}

package/dist/teardown.js

@@ -0,0 +1,197 @@
+/**
+ * Env teardown for the k8s lexicon (chant #1222) — both halves of the
+ * `teardownOwned` / `executeTeardown` capability pair.
+ *
+ * Selection is the prune's marker selector (op/activities/kubectl.ts) with the
+ * env dimension added: `app.kubernetes.io/managed-by=chant` +
+ * `chant.intentius.io/stack=<stack>` + `chant.intentius.io/env=<env>`, sent to
+ * the server as a label selector and re-checked object by object with
+ * `readOwnership` — the server-side filter narrows the read, the client-side
+ * re-check is the one that matters, because a delete is not undoable.
+ *
+ * Swept kinds are chant's default sweep set (`DEFAULT_IMPORT_TYPES`, the same
+ * list the ownership-scoped prune unions in), listed cluster-wide: env
+ * teardown has no apply set to scope namespaces by, and the marker selector is
+ * the scope. A kind the cluster's discovery does not serve cannot hold a
+ * marked object and is skipped; a kind that resolves but fails to list is a
+ * hole (#1089) — unknown, never absent.
+ *
+ * Execution deletes the handed-over candidates through the typed client's own
+ * `delete()` — the identical delete the prune and `chant kube delete` use —
+ * with namespaces last, so a namespace's own members get individual outcomes
+ * before the cascade would have swallowed them. Before each delete the live
+ * object is re-read and its marker re-verified; an object that vanished is
+ * `deleted` (teardown is idempotent), one whose identity no longer matches is
+ * `not-prunable`, never deleted.
+ */
+import { LABEL_OWNERSHIP_KEYS, OWNERSHIP_MANAGED_BY_VALUE, readOwnership, } from "@intentius/chant/ownership";
+import { DEFAULT_IMPORT_TYPES } from "./api/sweep-types.js";
+import { operationFor } from "./api/operation-surface.js";
+import { defaultK8sConnector } from "./api/connect.js";
+import { isGeneratedOnce } from "./secret-labels.js";
+const NAMESPACE_TYPE = "K8s::Core::Namespace";
+/** The label selector that scopes everything here: managed-by + stack + env. */
+function markerSelector(marker) {
+    return [
+        `${LABEL_OWNERSHIP_KEYS.managedBy}=${OWNERSHIP_MANAGED_BY_VALUE}`,
+        `${LABEL_OWNERSHIP_KEYS.stack}=${marker.stack}`,
+        ...(marker.env ? [`${LABEL_OWNERSHIP_KEYS.env}=${marker.env}`] : []),
+    ].join(",");
+}
+/** True when a live object's own labels carry exactly the requested identity. */
+function matchesMarker(labels, marker) {
+    const read = readOwnership(labels, LABEL_OWNERSHIP_KEYS);
+    return read !== undefined && read.stack === marker.stack && read.env === marker.env;
+}
+/**
+ * Enumerate the cluster's marker-matching objects — the k8s half of
+ * `chant lifecycle teardown <env>` planning.
+ */
+export async function teardownOwned(options, connect = defaultK8sConnector) {
+    const { client } = await connect({ environment: options.environment });
+    const selector = markerSelector(options.marker);
+    const candidates = [];
+    const holes = [];
+    for (const entityType of DEFAULT_IMPORT_TYPES) {
+        const operation = operationFor(entityType);
+        if (!operation)
+            continue;
+        const ref = { apiVersion: operation.apiVersion, kind: operation.kind };
+        let served;
+        try {
+            served = (await client.resolve(ref)) !== undefined;
+        }
+        catch (err) {
+            holes.push({
+                name: entityType,
+                type: entityType,
+                reason: "read-failed",
+                detail: err instanceof Error ? err.message : String(err),
+            });
+            continue;
+        }
+        // A kind this cluster's discovery does not serve cannot hold a marked
+        // object — absence of the kind is knowledge, not a hole.
+        if (!served)
+            continue;
+        let items;
+        try {
+            items = await client.list(ref, { labelSelector: selector });
+        }
+        catch (err) {
+            holes.push({
+                name: entityType,
+                type: entityType,
+                reason: "read-failed",
+                detail: err instanceof Error ? err.message : String(err),
+            });
+            continue;
+        }
+        for (const item of items) {
+            const name = item.metadata?.name;
+            if (!name)
+                continue;
+            // The re-check that matters: a server (or fake) that ignored the label
+            // selector must not widen the set past the requested identity.
+            if (!matchesMarker(item.metadata?.labels, options.marker))
+                continue;
+            // Already terminating — deleting again is noise, not progress.
+            if (item.metadata?.deletionTimestamp !== undefined)
+                continue;
+            const namespace = item.metadata?.namespace;
+            candidates.push({
+                name: namespace ? `${namespace}/${name}` : name,
+                type: entityType,
+                ...(item.metadata?.uid ? { physicalId: String(item.metadata.uid) } : {}),
+                marker: readOwnership(item.metadata?.labels, LABEL_OWNERSHIP_KEYS),
+            });
+        }
+    }
+    return { candidates, ...(holes.length > 0 ? { holes } : {}) };
+}
+/**
+ * Delete the handed-over candidates, namespaces last. One outcome per
+ * candidate, always.
+ */
+export async function executeTeardown(options, connect = defaultK8sConnector) {
+    const { client } = await connect({ environment: options.environment });
+    // Namespaces last: their members get individual deletes (and individual
+    // outcomes) before the namespace cascade sweeps whatever is left.
+    const ordered = [
+        ...options.candidates.filter((c) => c.type !== NAMESPACE_TYPE),
+        ...options.candidates.filter((c) => c.type === NAMESPACE_TYPE),
+    ];
+    const outcomes = [];
+    for (const candidate of ordered) {
+        outcomes.push(await deleteCandidate(client, candidate, options.marker));
+    }
+    return { outcomes };
+}
+async function deleteCandidate(client, candidate, marker) {
+    const base = {
+        name: candidate.name,
+        type: candidate.type,
+        ...(candidate.physicalId ? { physicalId: candidate.physicalId } : {}),
+    };
+    const operation = operationFor(candidate.type);
+    if (!operation) {
+        return { ...base, outcome: "not-prunable", detail: `no operation mapping for type ${candidate.type}` };
+    }
+    let info;
+    try {
+        info = await client.resolve({ apiVersion: operation.apiVersion, kind: operation.kind });
+    }
+    catch (err) {
+        return { ...base, outcome: "failed", detail: err instanceof Error ? err.message : String(err) };
+    }
+    if (!info) {
+        return { ...base, outcome: "not-prunable", detail: `the cluster does not serve ${operation.kind}` };
+    }
+    const slash = candidate.name.indexOf("/");
+    const namespace = info.namespaced && slash > 0 ? candidate.name.slice(0, slash) : undefined;
+    const name = info.namespaced && slash > 0 ? candidate.name.slice(slash + 1) : candidate.name;
+    const ref = {
+        apiVersion: operation.apiVersion,
+        kind: operation.kind,
+        name,
+        ...(namespace !== undefined ? { namespace } : {}),
+    };
+    // Re-read and re-verify the identity right before deleting: the enumeration
+    // is a moment old at best, and a delete is not undoable.
+    let live;
+    try {
+        live = await client.readIfPresent(ref);
+    }
+    catch (err) {
+        return { ...base, outcome: "failed", detail: err instanceof Error ? err.message : String(err) };
+    }
+    if (live === undefined) {
+        return { ...base, outcome: "deleted", detail: "already absent" };
+    }
+    if (!matchesMarker(live.metadata?.labels, marker)) {
+        return {
+            ...base,
+            outcome: "not-prunable",
+            detail: "the live object no longer carries the requested marker identity",
+        };
+    }
+    // A generated-once Secret survives every sweep, env teardown included
+    // (#1830, epic #1365 decision 5): the stored bytes are the only copy of
+    // material chant never held. `retained` is the loud keep — the row says the
+    // env is not clean and why. Deletion is an explicit act (`kubectl delete
+    // secret <name>`, or a future gated op), never a teardown's.
+    if (operation.kind === "Secret" && isGeneratedOnce(live.metadata?.labels)) {
+        return {
+            ...base,
+            outcome: "retained",
+            detail: "generated-once secret — deliberately kept, never swept; delete it explicitly (kubectl delete) if you mean to",
+        };
+    }
+    try {
+        await client.delete(ref);
+    }
+    catch (err) {
+        return { ...base, outcome: "failed", detail: err instanceof Error ? err.message : String(err) };
+    }
+    return { ...base, outcome: "deleted" };
+}

package/dist/telemetry-release.js

@@ -0,0 +1,86 @@
+/**
+ * Where a workload keeps its pod spec, and the release attributes a deploy
+ * writes onto it (#3059, #3061, ws-081).
+ *
+ * The build stamps each container of a workload with `OTEL_SERVICE_NAME` and
+ * `OTEL_RESOURCE_ATTRIBUTES` (the serializer), and with
+ * `CHANT_RELEASE_ATTRIBUTES` read through the downward API from the pod
+ * annotation `chant.intentius.io/release-attributes`, which
+ * `OTEL_RESOURCE_ATTRIBUTES` ends with as `$(CHANT_RELEASE_ATTRIBUTES)`. An
+ * absent annotation reads as empty, so the built manifest works as it is. A
+ * release deploy (`kubectl-apply` with a release on its context) sets the
+ * annotation on the pod template of each stamped workload in what it applies,
+ * leaving the committed manifest the same bytes.
+ *
+ * Kept free of the API client and the serializer so the capability module can
+ * import it without loading either.
+ */
+import { RELEASE_ATTRIBUTES_ANNOTATION, RELEASE_ATTRIBUTES_VARIABLE } from "@intentius/chant/telemetry-attribution";
+/** Where each workload kind keeps its pod spec. */
+export const POD_SPEC_PATHS = {
+    Pod: ["spec"],
+    Deployment: ["spec", "template", "spec"],
+    StatefulSet: ["spec", "template", "spec"],
+    DaemonSet: ["spec", "template", "spec"],
+    ReplicaSet: ["spec", "template", "spec"],
+    Job: ["spec", "template", "spec"],
+    CronJob: ["spec", "jobTemplate", "spec", "template", "spec"],
+};
+/** The core API groups those kinds live in; a CRD that reuses a kind name is not a workload. */
+const WORKLOAD_API_VERSIONS = new Set(["v1", "apps/v1", "batch/v1"]);
+function isObj(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function at(value, path) {
+    let cur = value;
+    for (const key of path) {
+        if (!isObj(cur))
+            return undefined;
+        cur = cur[key];
+    }
+    return cur;
+}
+/** A workload's pod spec, or undefined for anything else. */
+export function podSpecOf(manifest) {
+    const path = POD_SPEC_PATHS[manifest.kind];
+    if (!path || !WORKLOAD_API_VERSIONS.has(manifest.apiVersion))
+        return undefined;
+    const spec = at(manifest, path);
+    return isObj(spec) ? spec : undefined;
+}
+/** The env entry that reads the release attributes from the pod annotation. */
+export function releaseAttributesEnv() {
+    return {
+        name: RELEASE_ATTRIBUTES_VARIABLE,
+        valueFrom: { fieldRef: { fieldPath: `metadata.annotations['${RELEASE_ATTRIBUTES_ANNOTATION}']` } },
+    };
+}
+/** True when some container of the workload reads the release attributes, i.e. the build stamped it. */
+function readsRelease(podSpec) {
+    const containers = podSpec.containers;
+    if (!Array.isArray(containers))
+        return false;
+    return containers.some((c) => isObj(c) && Array.isArray(c.env) && c.env.some((e) => isObj(e) && e.name === RELEASE_ATTRIBUTES_VARIABLE && isObj(e.valueFrom)));
+}
+/**
+ * Set the release-attributes annotation on the pod template (or the Pod) of
+ * every stamped workload in `documents`, in place, and return how many it
+ * set. A workload the build did not stamp is left alone.
+ */
+export function annotateRelease(documents, suffix) {
+    let count = 0;
+    for (const doc of documents) {
+        const podSpec = podSpecOf(doc);
+        if (!podSpec || !readsRelease(podSpec))
+            continue;
+        const path = POD_SPEC_PATHS[doc.kind];
+        const owner = path.length === 1 ? doc : at(doc, path.slice(0, -1));
+        if (!isObj(owner))
+            continue;
+        const metadata = isObj(owner.metadata) ? owner.metadata : {};
+        const annotations = isObj(metadata.annotations) ? metadata.annotations : {};
+        owner.metadata = { ...metadata, annotations: { ...annotations, [RELEASE_ATTRIBUTES_ANNOTATION]: suffix } };
+        count++;
+    }
+    return count;
+}

package/dist/validate-cli.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env tsx
+/**
+ * CLI entry point for Kubernetes lexicon validation.
+ */
+import { validate } from "./validate.js";
+import { printValidationResult } from "@intentius/chant/codegen/validate";
+async function main() {
+    const result = await validate();
+    printValidationResult(result);
+    if (!result.success) {
+        process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error("Validation failed:", err);
+    process.exit(1);
+});

package/dist/validate.js

@@ -0,0 +1,47 @@
+/**
+ * Validate generated lexicon-k8s artifacts.
+ *
+ * Thin wrapper around the core validation framework
+ * with Kubernetes-specific configuration.
+ */
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { validateLexiconArtifacts } from "@intentius/chant/codegen/validate";
+const REQUIRED_NAMES = [
+    // Core resources
+    "Pod", "Service", "ConfigMap", "Secret", "Namespace",
+    "ServiceAccount", "PersistentVolume", "PersistentVolumeClaim",
+    // Apps
+    "Deployment", "StatefulSet", "DaemonSet", "ReplicaSet",
+    // Batch
+    "Job", "CronJob",
+    // Networking
+    "Ingress", "NetworkPolicy",
+    // RBAC
+    "Role", "ClusterRole", "RoleBinding", "ClusterRoleBinding",
+    // Autoscaling
+    "HorizontalPodAutoscaler",
+    // Policy
+    "PodDisruptionBudget",
+    // Property types
+    "Container", "Volume", "VolumeMount", "EnvVar", "ServicePort",
+    "Probe", "ResourceRequirements", "SecurityContext",
+];
+/**
+ * Validate the generated lexicon-k8s artifacts.
+ */
+export async function validate(opts) {
+    const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+    return validateLexiconArtifacts({
+        lexiconJsonFilename: "lexicon-k8s.json",
+        requiredNames: REQUIRED_NAMES,
+        basePath,
+        // chant #1475 — the baseline was re-baselined with the k3s CRD work
+        // (#1605). k8s generates from a pinned kubernetes release tag plus CRDs
+        // vendored in this repo, so a fresh generate is deterministic and the
+        // surface can only move through a change here. Gate on every validate,
+        // not just under CHANT_RELEASE_GATE, so a CRD batch can no longer leave
+        // the snapshot behind the way #1319/#1320/#1321 did.
+        checkSurfaceSnapshot: "always",
+    });
+}

package/dist/variables.js

@@ -0,0 +1,34 @@
+/**
+ * Kubernetes pseudo-parameters / well-known variables.
+ *
+ * Unlike AWS which has built-in pseudo-parameters (AWS::Region, etc.),
+ * Kubernetes doesn't have equivalent built-in variables. This module
+ * provides common label key constants for use in resource definitions.
+ */
+/**
+ * Well-known Kubernetes label keys from the standard label taxonomy.
+ * These are string constants, not runtime-resolved pseudo-parameters.
+ */
+export const K8sLabels = {
+    /** app.kubernetes.io/name */
+    AppName: "app.kubernetes.io/name",
+    /** app.kubernetes.io/instance */
+    AppInstance: "app.kubernetes.io/instance",
+    /** app.kubernetes.io/version */
+    AppVersion: "app.kubernetes.io/version",
+    /** app.kubernetes.io/component */
+    AppComponent: "app.kubernetes.io/component",
+    /** app.kubernetes.io/part-of */
+    AppPartOf: "app.kubernetes.io/part-of",
+    /** app.kubernetes.io/managed-by */
+    AppManagedBy: "app.kubernetes.io/managed-by",
+};
+/**
+ * Well-known Kubernetes annotation keys.
+ */
+export const K8sAnnotations = {
+    /** kubernetes.io/change-cause */
+    ChangeCause: "kubernetes.io/change-cause",
+    /** kubernetes.io/description */
+    Description: "kubernetes.io/description",
+};

package/dist/whoami.js

@@ -0,0 +1,109 @@
+/**
+ * Who chant would act as in a cluster — the lexicon half of `chant lifecycle
+ * whoami` (chant #1982).
+ *
+ * The connector already resolves all of this and hands it back on every
+ * observation: `defaultK8sConnector` picks a context from
+ * `k8s.profiles.<env>.context` or from the ambient kubeconfig, the client
+ * records the server it resolved and which credential path authorized it, and
+ * `describeResources` then throws the lot away. This reports it, and reports
+ * it BEFORE a read rather than after a wrong one.
+ *
+ * Same connector, same environment, same options, so the server named here is
+ * the server the read talks to. A test pins that: a whoami that names a
+ * cluster the read does not use would be worse than no whoami at all.
+ *
+ * ## The principal is the API server's answer, not the kubeconfig's
+ *
+ * A kubeconfig `user` entry is a local alias. The cluster may map that
+ * credential onto any subject it likes, which is exactly why "am I acting as
+ * the identity I think I am" is a real question. So the principal comes from
+ * `SelfSubjectReview` — the call behind `kubectl auth whoami` — which the API
+ * server answers with the subject it authenticated. It creates nothing.
+ *
+ * A cluster older than the review API serves no version of it. That is
+ * `read-failed` with a detail saying so, not a fallback to the local alias
+ * dressed up as an identity.
+ *
+ * ## No credential in the answer
+ *
+ * The credential path is reported by NAME — `exec-plugin` and its command,
+ * `token`, `client-certificate`. A kubeconfig holding a static bearer token is
+ * the case where the identity signal IS a secret, and the report says
+ * `credential: token` and stops there. The token, the client key and the exec
+ * plugin's output never leave the client.
+ */
+import { defaultK8sConnector } from "./api/connect.js";
+import { classifyApiFailure, isMissingClientPackage, MISSING_CLIENT_DETAIL } from "./api/classify.js";
+/** Everything about the caller's credential except the credential. */
+function credentialNote(credential, execCommand) {
+    return execCommand ? `credential ${credential} (${execCommand})` : `credential ${credential}`;
+}
+/**
+ * The k8s `describeIdentity`. Connects the way the read connects, asks the API
+ * server who it is talking to, and reports the context that binding came from.
+ */
+export async function describeIdentity(options, connect = defaultK8sConnector) {
+    let connected;
+    try {
+        connected = await connect({ environment: options.environment, cwd: options.cwd });
+    }
+    catch (err) {
+        if (isMissingClientPackage(err)) {
+            return { unresolved: { reason: "read-failed", detail: MISSING_CLIENT_DETAIL } };
+        }
+        const outcome = classifyApiFailure(err);
+        return {
+            unresolved: outcome.kind === "unobserved"
+                ? { reason: outcome.reason, detail: outcome.detail }
+                : { reason: "no-binding", detail: err instanceof Error ? err.message : String(err) },
+        };
+    }
+    const { client, target } = connected;
+    const provenance = client.provenance;
+    const context = provenance.context ?? "(unset)";
+    const scope = `${context} ns=${client.defaultNamespace}`;
+    // Where the context came from, in the project's own vocabulary. An ambient
+    // context is not a failure — but it is the one an operator most often did
+    // not mean, so it says which binding is missing.
+    const binding = target.source === "bound"
+        ? `k8s.profiles.${options.environment}.context`
+        : `ambient kubeconfig current-context (no k8s.profiles.${options.environment} binding)`;
+    const source = [
+        binding,
+        credentialNote(provenance.credential, provenance.execCommand),
+        `kubeconfig ${provenance.kubeconfigSource}`,
+    ].join("; ");
+    let subject;
+    try {
+        subject = await client.selfSubjectReview();
+    }
+    catch (err) {
+        const outcome = classifyApiFailure(err);
+        return {
+            unresolved: {
+                reason: outcome.kind === "unobserved" ? outcome.reason : "read-failed",
+                detail: outcome.kind === "unobserved"
+                    ? `SelfSubjectReview against ${provenance.server}: ${outcome.detail}`
+                    : `SelfSubjectReview against ${provenance.server} did not answer`,
+            },
+        };
+    }
+    if (!subject) {
+        return {
+            unresolved: {
+                reason: "read-failed",
+                detail: `${provenance.server} serves no authentication.k8s.io SelfSubjectReview, so the API server ` +
+                    `cannot be asked who it authenticated (the API landed in Kubernetes 1.26). The kubeconfig ` +
+                    `context is "${context}" with ${credentialNote(provenance.credential, provenance.execCommand)}, ` +
+                    `which names a local credential entry, not the subject the cluster resolves it to.`,
+            },
+        };
+    }
+    return {
+        identity: subject.username,
+        scope,
+        source,
+        endpoint: provenance.server,
+    };
+}