typekro 0.33.10 → 0.34.0

package/dist/core/kubernetes/api-capability.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Cluster API capability resolution.
+ *
+ * Some resources can only be rendered once the target cluster has said which
+ * group version it actually serves for a kind. `MutatingAdmissionPolicy` is the
+ * motivating case: beta on Kubernetes 1.34/1.35
+ * (`admissionregistration.k8s.io/v1beta1`), GA from 1.36
+ * (`admissionregistration.k8s.io/v1`), never both on the same server, and
+ * absent entirely below 1.34. Guessing produces an apply failure for the whole
+ * graph, so nothing here ever guesses: a capability is either resolved against
+ * a cluster or reported as unresolved, and the caller skips the resource.
+ *
+ * "Unresolved" is itself two different things, and they are kept apart. The
+ * cluster answering "I do not serve that" is a fact worth caching and worth
+ * telling the user. Failing to reach the cluster at all is not a fact about the
+ * cluster, and reporting it as one — then caching it for five minutes — is how
+ * a transient RBAC or network error turns into a confident lie. Hence the
+ * three-way {@link ClusterCapabilityResolution}.
+ *
+ * Two pieces make that work:
+ *
+ * - {@link resolveClusterCapability} runs discovery once per cluster and caches
+ *   the answer under the **cluster's identity**, never globally. A process that
+ *   talks to two clusters — a test suite with two fakes, multi-cluster
+ *   tooling — gets an independent answer for each.
+ * - {@link runWithDeployTarget} publishes the cluster a deployment is currently
+ *   targeting, so synchronous code further down (a composition body re-executed
+ *   at deploy time) can read the answer resolved for *that* cluster without
+ *   threading a `KubeConfig` through every call.
+ */
+import type * as k8s from '@kubernetes/client-node';
+import { type ApiReadFailure } from '../deployment/k8s-helpers.js';
+/**
+ * A kind whose served group version has to come from the cluster.
+ *
+ * `versions` is bare version names in preference order — the first one the
+ * cluster serves the kind at wins.
+ */
+export interface ClusterCapabilityRequirement {
+    /** Stable id; forms half of the cache key (the cluster identity is the other half). */
+    id: string;
+    group: string;
+    kind: string;
+    versions: readonly string[];
+}
+/**
+ * Why discovery could not answer. `notFound` is excluded on purpose: a 404 *is*
+ * an answer ("not served"), everything here is the absence of one.
+ */
+export type DiscoveryFailure = Exclude<ApiReadFailure, 'notFound'>;
+/**
+ * The outcome of asking a cluster about a kind.
+ *
+ * Three-way, not two-way, because "the cluster does not serve this" and "we
+ * could not find out" have opposite consequences: the first is a durable fact
+ * worth caching and reporting to the user, the second is a transient failure
+ * that must never be reported as a fact about the cluster.
+ */
+export type ClusterCapabilityResolution = {
+    status: 'served';
+    apiVersion: string;
+} | {
+    status: 'unserved';
+    reason: string;
+} | {
+    status: 'unknown';
+    reason: string;
+    failure: DiscoveryFailure;
+};
+/**
+ * What a single `GET /apis/<group>/<version>` told us.
+ *
+ * - `served` — the server answered with a resource list; `kinds` is what it holds.
+ * - `unserved` — the server answered 404: this group version is definitively not served.
+ * - `unknown` — no answer (unreachable, RBAC, timeout, TLS). Says nothing about the cluster.
+ */
+export type ApiGroupProbe = {
+    status: 'served';
+    kinds: readonly string[];
+} | {
+    status: 'unserved';
+} | {
+    status: 'unknown';
+    failure: DiscoveryFailure;
+    message: string;
+};
+/**
+ * The one cluster call capability resolution needs.
+ *
+ * Narrow on purpose: a test supplies a fake with a literal map of group
+ * versions to kinds and never touches `@kubernetes/client-node`.
+ */
+export interface ApiGroupDiscovery {
+    /** What the cluster says about `<group>/<version>`. */
+    servedKinds(group: string, version: string): Promise<ApiGroupProbe>;
+}
+/**
+ * A stable fingerprint for the cluster a `KubeConfig` currently points at.
+ *
+ * Server URL plus CA material plus the context's cluster name: two kubeconfigs
+ * that reach the same API server with the same trust root are the same cluster,
+ * and two contexts that differ in any of those are not. Returns `undefined`
+ * when the config names no current cluster — there is nothing to key on, so
+ * nothing may be cached.
+ */
+export declare function clusterIdentity(kubeConfig: k8s.KubeConfig): string | undefined;
+/** How long a resolved capability stays good. A cluster can be upgraded under us. */
+export declare const CLUSTER_CAPABILITY_CACHE_TTL_MS: number;
+/**
+ * How long an `unknown` outcome is retained — a **failure note**, not an answer.
+ *
+ * An `unknown` is recorded so that the build which follows a resolve step in the
+ * same deployment can say *why* it has no capability ("discovery failed: RBAC")
+ * instead of the far weaker "no cluster was asked". It is deliberately not an
+ * answer: {@link resolveClusterCapability} treats a stored `unknown` as a cache
+ * miss and re-probes, so a transient failure never suppresses the next real
+ * attempt, and this short lifetime bounds how long the note can linger at all.
+ */
+export declare const CLUSTER_CAPABILITY_UNKNOWN_CACHE_TTL_MS: number;
+/** Ceiling on cached entries so long-lived multi-cluster tooling cannot grow unbounded. */
+export declare const CLUSTER_CAPABILITY_CACHE_MAX_ENTRIES = 64;
+/**
+ * Read a previously resolved capability without touching the cluster.
+ *
+ * May return an `unknown` entry: the reporting path *wants* to see that
+ * discovery was attempted and failed, so it can say so rather than claim the
+ * cluster lacks the API. {@link resolveClusterCapability} ignores those entries.
+ */
+export declare function getCachedClusterCapability(requirement: ClusterCapabilityRequirement, clusterId: string): ClusterCapabilityResolution | undefined;
+/** Drop every cached capability. Test seam. */
+export declare function resetClusterCapabilityCache(): void;
+/** Number of live cache entries. Test seam for the bounded-lifetime contract. */
+export declare function clusterCapabilityCacheSize(): number;
+/**
+ * Discovery backed by a real cluster.
+ *
+ * `GET /apis/<group>/<version>` is the definitive test, and is why this is
+ * discovery rather than a list call: 1.32 and 1.33 serve
+ * `admissionregistration.k8s.io/v1` for webhook configurations while not
+ * serving `MutatingAdmissionPolicy` at all, so "the group version exists" is
+ * not the same question as "the kind is served".
+ */
+export declare function kubeConfigApiGroupDiscovery(kubeConfig: k8s.KubeConfig): ApiGroupDiscovery;
+/**
+ * Ask a cluster which group version serves a kind, memoized per cluster.
+ *
+ * Never falls back to a preferred or assumed version, and never turns a
+ * discovery failure into a claim about the cluster:
+ *
+ * - `served` — a candidate version's resource list contains the kind.
+ * - `unserved` — every candidate was *answered for* (404, or a 200 list without
+ *   the kind) and none serves it. A durable fact; cached for the full TTL.
+ * - `unknown` — no candidate served the kind and at least one could not be
+ *   checked. The kind may well be served at the version we could not reach, so
+ *   nothing may be concluded. Retained only as a short-lived failure note, and
+ *   treated as a cache miss by the next call.
+ */
+export declare function resolveClusterCapability(requirement: ClusterCapabilityRequirement, options: {
+    clusterId: string;
+    discovery: ApiGroupDiscovery;
+    /** Skip the cache read. The write still happens. */
+    refresh?: boolean;
+    ttlMs?: number;
+    /** Lifetime for an `unknown` failure note. */
+    unknownTtlMs?: number;
+}): Promise<ClusterCapabilityResolution>;
+/** Register a requirement to be resolved before each deployment. Idempotent. */
+export declare function registerDeployTimeCapability(requirement: ClusterCapabilityRequirement): void;
+/** Every registered deploy-time requirement. */
+export declare function listDeployTimeCapabilities(): ClusterCapabilityRequirement[];
+/**
+ * Resolve every registered requirement against a cluster and return that
+ * cluster's identity, or `undefined` when the config names no cluster (nothing
+ * was resolved, and callers must treat every capability as unavailable).
+ *
+ * Resolution failures are not fatal: a requirement that cannot be resolved
+ * comes back `unknown`, which makes the caller skip the resource just as
+ * `unserved` does — the whole point of the seam is that an unverified API is
+ * never assumed to be present. The two are kept distinct so the caller can say
+ * which happened rather than blaming the cluster for a network error.
+ */
+export declare function resolveDeployTimeCapabilities(kubeConfig: k8s.KubeConfig, options?: {
+    discovery?: ApiGroupDiscovery;
+}): Promise<string | undefined>;
+/**
+ * Run `fn` with `clusterId` published as the cluster this deployment targets.
+ *
+ * Synchronous code inside — notably a composition body re-executed at deploy
+ * time — can then read capabilities resolved for exactly that cluster. Nested
+ * and concurrent deployments to different clusters do not see each other's
+ * target.
+ */
+export declare function runWithDeployTarget<T>(clusterId: string, fn: () => T): T;
+/** The cluster the current deployment targets, if any. */
+export declare function getCurrentDeployTarget(): string | undefined;
+//# sourceMappingURL=api-capability.d.ts.map

package/dist/core/kubernetes/api-capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-capability.d.ts","sourceRoot":"","sources":["../../../src/core/kubernetes/api-capability.ts"],"names":[],"mappings":"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"}

package/dist/core/kubernetes/api-capability.js

@@ -0,0 +1,301 @@
+/**
+ * Cluster API capability resolution.
+ *
+ * Some resources can only be rendered once the target cluster has said which
+ * group version it actually serves for a kind. `MutatingAdmissionPolicy` is the
+ * motivating case: beta on Kubernetes 1.34/1.35
+ * (`admissionregistration.k8s.io/v1beta1`), GA from 1.36
+ * (`admissionregistration.k8s.io/v1`), never both on the same server, and
+ * absent entirely below 1.34. Guessing produces an apply failure for the whole
+ * graph, so nothing here ever guesses: a capability is either resolved against
+ * a cluster or reported as unresolved, and the caller skips the resource.
+ *
+ * "Unresolved" is itself two different things, and they are kept apart. The
+ * cluster answering "I do not serve that" is a fact worth caching and worth
+ * telling the user. Failing to reach the cluster at all is not a fact about the
+ * cluster, and reporting it as one — then caching it for five minutes — is how
+ * a transient RBAC or network error turns into a confident lie. Hence the
+ * three-way {@link ClusterCapabilityResolution}.
+ *
+ * Two pieces make that work:
+ *
+ * - {@link resolveClusterCapability} runs discovery once per cluster and caches
+ *   the answer under the **cluster's identity**, never globally. A process that
+ *   talks to two clusters — a test suite with two fakes, multi-cluster
+ *   tooling — gets an independent answer for each.
+ * - {@link runWithDeployTarget} publishes the cluster a deployment is currently
+ *   targeting, so synchronous code further down (a composition body re-executed
+ *   at deploy time) can read the answer resolved for *that* cluster without
+ *   threading a `KubeConfig` through every call.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createHash } from 'node:crypto';
+import { classifyApiReadError, describeApiReadError, isNotFoundError, } from '../deployment/k8s-helpers.js';
+import { getComponentLogger } from '../logging/index.js';
+import { createBunCompatibleApiClient } from './bun-api-client.js';
+const logger = getComponentLogger('api-capability');
+// ---------------------------------------------------------------------------
+// Cluster identity
+// ---------------------------------------------------------------------------
+/**
+ * A stable fingerprint for the cluster a `KubeConfig` currently points at.
+ *
+ * Server URL plus CA material plus the context's cluster name: two kubeconfigs
+ * that reach the same API server with the same trust root are the same cluster,
+ * and two contexts that differ in any of those are not. Returns `undefined`
+ * when the config names no current cluster — there is nothing to key on, so
+ * nothing may be cached.
+ */
+export function clusterIdentity(kubeConfig) {
+    let cluster;
+    try {
+        cluster = kubeConfig.getCurrentCluster();
+    }
+    catch {
+        return undefined;
+    }
+    if (!cluster?.server)
+        return undefined;
+    const material = [
+        cluster.name ?? '',
+        cluster.server,
+        cluster.caData ?? '',
+        cluster.caFile ?? '',
+        String(cluster.skipTLSVerify ?? false),
+    ].join('|');
+    return createHash('sha256').update(material).digest('hex').slice(0, 32);
+}
+// ---------------------------------------------------------------------------
+// Cache
+// ---------------------------------------------------------------------------
+/** How long a resolved capability stays good. A cluster can be upgraded under us. */
+export const CLUSTER_CAPABILITY_CACHE_TTL_MS = 5 * 60 * 1000;
+/**
+ * How long an `unknown` outcome is retained — a **failure note**, not an answer.
+ *
+ * An `unknown` is recorded so that the build which follows a resolve step in the
+ * same deployment can say *why* it has no capability ("discovery failed: RBAC")
+ * instead of the far weaker "no cluster was asked". It is deliberately not an
+ * answer: {@link resolveClusterCapability} treats a stored `unknown` as a cache
+ * miss and re-probes, so a transient failure never suppresses the next real
+ * attempt, and this short lifetime bounds how long the note can linger at all.
+ */
+export const CLUSTER_CAPABILITY_UNKNOWN_CACHE_TTL_MS = 10 * 1000;
+/** Ceiling on cached entries so long-lived multi-cluster tooling cannot grow unbounded. */
+export const CLUSTER_CAPABILITY_CACHE_MAX_ENTRIES = 64;
+/** Keyed by `<cluster identity>|<requirement id>` — never by requirement alone. */
+const cache = new Map();
+function cacheKey(clusterId, requirementId) {
+    return `${clusterId}|${requirementId}`;
+}
+function readCache(clusterId, requirementId) {
+    const key = cacheKey(clusterId, requirementId);
+    const entry = cache.get(key);
+    if (!entry)
+        return undefined;
+    if (entry.expiresAt <= Date.now()) {
+        cache.delete(key);
+        return undefined;
+    }
+    return entry.resolution;
+}
+function writeCache(clusterId, requirementId, resolution, ttlMs) {
+    const key = cacheKey(clusterId, requirementId);
+    // Re-insert so iteration order is insertion recency; the oldest entry is the
+    // first key Map yields.
+    cache.delete(key);
+    cache.set(key, { resolution, expiresAt: Date.now() + ttlMs });
+    while (cache.size > CLUSTER_CAPABILITY_CACHE_MAX_ENTRIES) {
+        const oldest = cache.keys().next();
+        if (oldest.done)
+            break;
+        cache.delete(oldest.value);
+    }
+}
+/**
+ * Read a previously resolved capability without touching the cluster.
+ *
+ * May return an `unknown` entry: the reporting path *wants* to see that
+ * discovery was attempted and failed, so it can say so rather than claim the
+ * cluster lacks the API. {@link resolveClusterCapability} ignores those entries.
+ */
+export function getCachedClusterCapability(requirement, clusterId) {
+    return readCache(clusterId, requirement.id);
+}
+/** Drop every cached capability. Test seam. */
+export function resetClusterCapabilityCache() {
+    cache.clear();
+}
+/** Number of live cache entries. Test seam for the bounded-lifetime contract. */
+export function clusterCapabilityCacheSize() {
+    return cache.size;
+}
+/**
+ * Discovery backed by a real cluster.
+ *
+ * `GET /apis/<group>/<version>` is the definitive test, and is why this is
+ * discovery rather than a list call: 1.32 and 1.33 serve
+ * `admissionregistration.k8s.io/v1` for webhook configurations while not
+ * serving `MutatingAdmissionPolicy` at all, so "the group version exists" is
+ * not the same question as "the kind is served".
+ */
+export function kubeConfigApiGroupDiscovery(kubeConfig) {
+    return {
+        async servedKinds(group, version) {
+            try {
+                const clientNode = await import('@kubernetes/client-node');
+                const api = createBunCompatibleApiClient(kubeConfig, clientNode.CustomObjectsApi);
+                const list = await api.getAPIResources({ group, version });
+                return {
+                    status: 'served',
+                    kinds: (list.resources ?? [])
+                        .filter((resource) => typeof resource.name === 'string' && !resource.name.includes('/'))
+                        .map((resource) => resource.kind)
+                        .filter((kind) => typeof kind === 'string'),
+                };
+            }
+            catch (error) {
+                // Only a 404 is an answer. The server was asked and said this group
+                // version does not exist, which is a durable fact about the cluster.
+                if (isNotFoundError(error)) {
+                    logger.debug('API group version is not served', { group, version });
+                    return { status: 'unserved' };
+                }
+                // Everything else — unreachable server, RBAC, timeout, TLS — means the
+                // question never reached the server. Reporting that as "not served"
+                // would put a false claim about the cluster in front of the user (and,
+                // before this split, into a five-minute cache).
+                const failure = classifyApiReadError(error);
+                const message = describeApiReadError(error);
+                logger.debug('API group version discovery failed', { group, version, failure, message });
+                return { status: 'unknown', failure, message };
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+/**
+ * Ask a cluster which group version serves a kind, memoized per cluster.
+ *
+ * Never falls back to a preferred or assumed version, and never turns a
+ * discovery failure into a claim about the cluster:
+ *
+ * - `served` — a candidate version's resource list contains the kind.
+ * - `unserved` — every candidate was *answered for* (404, or a 200 list without
+ *   the kind) and none serves it. A durable fact; cached for the full TTL.
+ * - `unknown` — no candidate served the kind and at least one could not be
+ *   checked. The kind may well be served at the version we could not reach, so
+ *   nothing may be concluded. Retained only as a short-lived failure note, and
+ *   treated as a cache miss by the next call.
+ */
+export async function resolveClusterCapability(requirement, options) {
+    const { clusterId, discovery, refresh = false, ttlMs = CLUSTER_CAPABILITY_CACHE_TTL_MS, unknownTtlMs = CLUSTER_CAPABILITY_UNKNOWN_CACHE_TTL_MS, } = options;
+    if (!refresh) {
+        const cached = readCache(clusterId, requirement.id);
+        // A stored `unknown` is a note about a past failure, never an answer, so it
+        // must not short-circuit a fresh attempt.
+        if (cached && cached.status !== 'unknown')
+            return cached;
+    }
+    const groupVersions = requirement.versions.map((version) => `${requirement.group}/${version}`);
+    const failures = [];
+    let resolution;
+    for (const version of requirement.versions) {
+        const probe = await discovery.servedKinds(requirement.group, version);
+        if (probe.status === 'served' && probe.kinds.includes(requirement.kind)) {
+            resolution = { status: 'served', apiVersion: `${requirement.group}/${version}` };
+            break;
+        }
+        if (probe.status === 'unknown') {
+            failures.push({
+                groupVersion: `${requirement.group}/${version}`,
+                failure: probe.failure,
+                message: probe.message,
+            });
+        }
+    }
+    if (!resolution) {
+        const firstFailure = failures[0];
+        resolution = firstFailure
+            ? {
+                status: 'unknown',
+                failure: firstFailure.failure,
+                reason: `${requirement.kind} discovery against the cluster failed for ` +
+                    `${failures.map((entry) => entry.groupVersion).join(', ')} ` +
+                    `(${firstFailure.message}), so whether the cluster serves the kind is unknown`,
+            }
+            : {
+                status: 'unserved',
+                reason: `the cluster does not serve ${requirement.kind} at any of ${groupVersions.join(', ')}`,
+            };
+    }
+    writeCache(clusterId, requirement.id, resolution, resolution.status === 'unknown' ? unknownTtlMs : ttlMs);
+    return resolution;
+}
+// ---------------------------------------------------------------------------
+// Deploy-time registry
+// ---------------------------------------------------------------------------
+/**
+ * Requirements the deployment path resolves before it materializes a graph.
+ *
+ * A module that renders a capability-gated resource registers its requirement
+ * on load; the direct deployment path resolves whatever is registered against
+ * the cluster it is about to deploy to. Keeping the list here rather than in
+ * the deployment layer is what stops the engine from having to know about any
+ * particular kind.
+ */
+const deployTimeRequirements = new Map();
+/** Register a requirement to be resolved before each deployment. Idempotent. */
+export function registerDeployTimeCapability(requirement) {
+    deployTimeRequirements.set(requirement.id, requirement);
+}
+/** Every registered deploy-time requirement. */
+export function listDeployTimeCapabilities() {
+    return [...deployTimeRequirements.values()];
+}
+/**
+ * Resolve every registered requirement against a cluster and return that
+ * cluster's identity, or `undefined` when the config names no cluster (nothing
+ * was resolved, and callers must treat every capability as unavailable).
+ *
+ * Resolution failures are not fatal: a requirement that cannot be resolved
+ * comes back `unknown`, which makes the caller skip the resource just as
+ * `unserved` does — the whole point of the seam is that an unverified API is
+ * never assumed to be present. The two are kept distinct so the caller can say
+ * which happened rather than blaming the cluster for a network error.
+ */
+export async function resolveDeployTimeCapabilities(kubeConfig, options = {}) {
+    const clusterId = clusterIdentity(kubeConfig);
+    if (!clusterId)
+        return undefined;
+    const requirements = listDeployTimeCapabilities();
+    if (requirements.length === 0)
+        return clusterId;
+    const discovery = options.discovery ?? kubeConfigApiGroupDiscovery(kubeConfig);
+    for (const requirement of requirements) {
+        await resolveClusterCapability(requirement, { clusterId, discovery });
+    }
+    return clusterId;
+}
+// ---------------------------------------------------------------------------
+// Deploy target context
+// ---------------------------------------------------------------------------
+const DEPLOY_TARGET = new AsyncLocalStorage();
+/**
+ * Run `fn` with `clusterId` published as the cluster this deployment targets.
+ *
+ * Synchronous code inside — notably a composition body re-executed at deploy
+ * time — can then read capabilities resolved for exactly that cluster. Nested
+ * and concurrent deployments to different clusters do not see each other's
+ * target.
+ */
+export function runWithDeployTarget(clusterId, fn) {
+    return DEPLOY_TARGET.run(clusterId, fn);
+}
+/** The cluster the current deployment targets, if any. */
+export function getCurrentDeployTarget() {
+    return DEPLOY_TARGET.getStore();
+}
+//# sourceMappingURL=api-capability.js.map

package/dist/core/kubernetes/api-capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-capability.js","sourceRoot":"","sources":["../../../src/core/kubernetes/api-capability.ts"],"names":[],"mappings":"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"}

package/dist/core/kubernetes/index.d.ts

@@ -8,6 +8,8 @@
  * - Error handling utilities for consistent error management
  */
 export { KubernetesApi } from './api.js';
+export type { ApiGroupDiscovery, ApiGroupProbe, ClusterCapabilityRequirement, ClusterCapabilityResolution, DiscoveryFailure, } from './api-capability.js';
+export { CLUSTER_CAPABILITY_CACHE_MAX_ENTRIES, CLUSTER_CAPABILITY_CACHE_TTL_MS, CLUSTER_CAPABILITY_UNKNOWN_CACHE_TTL_MS, clusterCapabilityCacheSize, clusterIdentity, getCachedClusterCapability, getCurrentDeployTarget, kubeConfigApiGroupDiscovery, listDeployTimeCapabilities, registerDeployTimeCapability, resetClusterCapabilityCache, resolveClusterCapability, resolveDeployTimeCapabilities, runWithDeployTarget, } from './api-capability.js';
 export { createBunCompatibleApiClient, createBunCompatibleApiextensionsV1Api, createBunCompatibleAppsV1Api, createBunCompatibleBatchV1Api, createBunCompatibleCoreV1Api, createBunCompatibleCustomObjectsApi, createBunCompatibleKubernetesObjectApi, createBunCompatibleNetworkingV1Api, createBunCompatibleRbacAuthorizationV1Api, createBunCompatibleStorageV1Api, } from './bun-api-client.js';
 export type { HttpTimeoutConfig } from './bun-http-library.js';
 export { BunCompatibleHttpLibrary, getHttpLibraryForRuntime, isBunRuntime, } from './bun-http-library.js';

package/dist/core/kubernetes/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/kubernetes/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EACL,4BAA4B,EAC5B,qCAAqC,EACrC,4BAA4B,EAC5B,6BAA6B,EAC7B,4BAA4B,EAC5B,mCAAmC,EACnC,sCAAsC,EACtC,kCAAkC,EAClC,yCAAyC,EACzC,+BAA+B,GAChC,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAI/D,OAAO,EACL,wBAAwB,EACxB,wBAAwB,EACxB,YAAY,GACb,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,wBAAwB,EACxB,kBAAkB,EAClB,2BAA2B,EAC3B,4BAA4B,EAC5B,qBAAqB,EACrB,sBAAsB,EACtB,YAAY,GACb,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,8BAA8B,EAC9B,4CAA4C,EAC5C,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,2BAA2B,EAC3B,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,OAAO,EACP,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/kubernetes/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,4BAA4B,EAC5B,2BAA2B,EAC3B,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,oCAAoC,EACpC,+BAA+B,EAC/B,uCAAuC,EACvC,0BAA0B,EAC1B,eAAe,EACf,0BAA0B,EAC1B,sBAAsB,EACtB,2BAA2B,EAC3B,0BAA0B,EAC1B,4BAA4B,EAC5B,2BAA2B,EAC3B,wBAAwB,EACxB,6BAA6B,EAC7B,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,4BAA4B,EAC5B,qCAAqC,EACrC,4BAA4B,EAC5B,6BAA6B,EAC7B,4BAA4B,EAC5B,mCAAmC,EACnC,sCAAsC,EACtC,kCAAkC,EAClC,yCAAyC,EACzC,+BAA+B,GAChC,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAI/D,OAAO,EACL,wBAAwB,EACxB,wBAAwB,EACxB,YAAY,GACb,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,wBAAwB,EACxB,kBAAkB,EAClB,2BAA2B,EAC3B,4BAA4B,EAC5B,qBAAqB,EACrB,sBAAsB,EACtB,YAAY,GACb,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,8BAA8B,EAC9B,4CAA4C,EAC5C,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,2BAA2B,EAC3B,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,OAAO,EACP,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC"}

package/dist/core/kubernetes/index.js

@@ -9,6 +9,8 @@
  */
 // API utilities
 export { KubernetesApi } from './api.js';
+// Cluster API capability resolution — group versions are discovered, never assumed
+export { CLUSTER_CAPABILITY_CACHE_MAX_ENTRIES, CLUSTER_CAPABILITY_CACHE_TTL_MS, CLUSTER_CAPABILITY_UNKNOWN_CACHE_TTL_MS, clusterCapabilityCacheSize, clusterIdentity, getCachedClusterCapability, getCurrentDeployTarget, kubeConfigApiGroupDiscovery, listDeployTimeCapabilities, registerDeployTimeCapability, resetClusterCapabilityCache, resolveClusterCapability, resolveDeployTimeCapabilities, runWithDeployTarget, } from './api-capability.js';
 export { createBunCompatibleApiClient, createBunCompatibleApiextensionsV1Api, createBunCompatibleAppsV1Api, createBunCompatibleBatchV1Api, createBunCompatibleCoreV1Api, createBunCompatibleCustomObjectsApi, createBunCompatibleKubernetesObjectApi, createBunCompatibleNetworkingV1Api, createBunCompatibleRbacAuthorizationV1Api, createBunCompatibleStorageV1Api, } from './bun-api-client.js';
 // Bun compatibility utilities
 // These provide workarounds for Bun's fetch TLS issues

package/dist/core/kubernetes/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/kubernetes/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,gBAAgB;AAChB,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EACL,4BAA4B,EAC5B,qCAAqC,EACrC,4BAA4B,EAC5B,6BAA6B,EAC7B,4BAA4B,EAC5B,mCAAmC,EACnC,sCAAsC,EACtC,kCAAkC,EAClC,yCAAyC,EACzC,+BAA+B,GAChC,MAAM,qBAAqB,CAAC;AAE7B,8BAA8B;AAC9B,uDAAuD;AACvD,mDAAmD;AACnD,OAAO,EACL,wBAAwB,EACxB,wBAAwB,EACxB,YAAY,GACb,MAAM,uBAAuB,CAAC;AAU/B,oCAAoC;AACpC,OAAO,EACL,8BAA8B,EAC9B,4CAA4C,EAC5C,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,2BAA2B,EAC3B,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAE9B,2BAA2B;AAC3B,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAKrB,cAAc;AACd,OAAO,EACL,OAAO,EACP,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/kubernetes/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,gBAAgB;AAChB,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAQzC,mFAAmF;AACnF,OAAO,EACL,oCAAoC,EACpC,+BAA+B,EAC/B,uCAAuC,EACvC,0BAA0B,EAC1B,eAAe,EACf,0BAA0B,EAC1B,sBAAsB,EACtB,2BAA2B,EAC3B,0BAA0B,EAC1B,4BAA4B,EAC5B,2BAA2B,EAC3B,wBAAwB,EACxB,6BAA6B,EAC7B,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,4BAA4B,EAC5B,qCAAqC,EACrC,4BAA4B,EAC5B,6BAA6B,EAC7B,4BAA4B,EAC5B,mCAAmC,EACnC,sCAAsC,EACtC,kCAAkC,EAClC,yCAAyC,EACzC,+BAA+B,GAChC,MAAM,qBAAqB,CAAC;AAE7B,8BAA8B;AAC9B,uDAAuD;AACvD,mDAAmD;AACnD,OAAO,EACL,wBAAwB,EACxB,wBAAwB,EACxB,YAAY,GACb,MAAM,uBAAuB,CAAC;AAU/B,oCAAoC;AACpC,OAAO,EACL,8BAA8B,EAC9B,4CAA4C,EAC5C,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,2BAA2B,EAC3B,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAE9B,2BAA2B;AAC3B,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAKrB,cAAc;AACd,OAAO,EACL,OAAO,EACP,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC"}

package/dist/core/kubernetes/naming.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Kubernetes and Helm name-length limits, and the derivation that turns them
+ * into a bound on the name a caller hands a composition.
+ *
+ * A composition rarely uses `spec.name` verbatim and nothing else: it — or the
+ * chart it installs, or a controller downstream of it — derives further object
+ * names from it by appending a suffix (`<name>-udp`) or by counting up from it
+ * (`<name>-<ordinal>`). Each of those derived names has to satisfy a limit of
+ * its own, so the real bound on `spec.name` is `min(limit - reserved)` across
+ * every name the composition can produce.
+ *
+ * Writing that minimum into a schema as a literal (`'string <= 40'`) hides
+ * which name produced it, so nobody can tell whether the number is still right
+ * after a chart bump adds a longer suffix. {@link deriveNameLengthLimit} takes
+ * the derived names instead and computes the bound, keeping the reasoning in
+ * the source and putting the binding constraint into the validation message.
+ *
+ * **Only names that can actually FAIL belong in a derivation.** A name the API
+ * server produces through `metadata.generateName` — a ReplicaSet's Pods, a
+ * Job's Pods — cannot fail on a long prefix: the generator truncates the base
+ * to `MaxGeneratedNameLength = 63 - 5` before appending its random suffix, so
+ * the result is always within the limit no matter how long the prefix was. See
+ * `staging/src/k8s.io/apiserver/pkg/storage/names/generate.go` in
+ * kubernetes/kubernetes. Reserving room for a suffix Kubernetes will truncate
+ * anyway only makes the schema reject names that would have worked.
+ */
+/**
+ * RFC 1123 (and RFC 1035) DNS label limit.
+ *
+ * The ceiling for a Service name, for the hostname a Pod gets from its name,
+ * and for every `metadata.name` a controller turns into a label.
+ */
+export declare const DNS_LABEL_MAX_LENGTH = 63;
+/**
+ * RFC 1123 DNS subdomain limit — the general `metadata.name` ceiling for
+ * objects whose names are not required to be labels.
+ */
+export declare const DNS_SUBDOMAIN_MAX_LENGTH = 253;
+/**
+ * Helm's release-name limit (`releaseNameMaxLen`, `helm.sh/helm/v3/pkg/action`).
+ *
+ * Tighter than the DNS label limit because Helm reserves room for the suffixes
+ * it appends to a release's own bookkeeping Secrets
+ * (`sh.helm.release.v1.<release>.v<revision>`).
+ */
+export declare const HELM_RELEASE_NAME_MAX_LENGTH = 53;
+/** One name a composition derives from the name its caller supplies. */
+export interface GeneratedNameConstraint {
+    /**
+     * What the derived name is and who generates it, e.g.
+     * `'<name>-udp (the chart\'s UDP Service)'`. Quoted in the validation
+     * message when this constraint is the binding one.
+     */
+    readonly describedAs: string;
+    /** Literal suffix appended to the caller's name. Omit when there is none. */
+    readonly suffix?: string;
+    /**
+     * Characters a controller appends on top of {@link suffix} that are not a
+     * literal — a StatefulSet ordinal, a revision counter, a timestamp.
+     *
+     * Count characters only where an over-long result would be REJECTED. Names
+     * the API server builds with `metadata.generateName` do not qualify: its
+     * generator truncates the base to `MaxGeneratedNameLength = 63 - 5` first
+     * (`staging/src/k8s.io/apiserver/pkg/storage/names/generate.go`), so those
+     * names always fit and reserving for them only over-constrains the caller.
+     */
+    readonly generatedChars?: number;
+    /** Length limit the derived name has to satisfy. */
+    readonly limit: number;
+}
+/** The bound {@link deriveNameLengthLimit} computed, and why. */
+export interface DerivedNameLimit {
+    /** Longest name a caller may supply. */
+    readonly maxLength: number;
+    /** The constraint that produced {@link maxLength}. */
+    readonly binding: GeneratedNameConstraint;
+    /**
+     * Validation message naming the limit and the constraint behind it, ready to
+     * hand to ArkType's `.configure({ message })`.
+     */
+    readonly message: string;
+}
+/**
+ * Compute the longest name a caller may supply, given every name derived from
+ * it.
+ *
+ * Ties go to the constraint declared first, so list the constraints in the
+ * order a reader should meet them.
+ *
+ * @param constraints - Every name the composition (or its chart, or a
+ *   controller downstream of it) derives from the caller's name. Include the
+ *   bare name itself as a constraint with no suffix wherever it is used as-is
+ *   under a limit of its own — a Helm release name, say.
+ * @returns The bound, the constraint that produced it, and a message naming
+ *   both.
+ * @throws If `constraints` is empty, or if a constraint reserves at least as
+ *   many characters as its own limit, which would leave no name at all.
+ */
+export declare function deriveNameLengthLimit(constraints: readonly GeneratedNameConstraint[]): DerivedNameLimit;
+//# sourceMappingURL=naming.d.ts.map