@intentius/chant-lexicon-k8s 0.30.0 → 0.32.0

package/src/op/activities/kubectl.ts

@@ -1,10 +1,61 @@
-import { exec } from "node:child_process";
-import { promisify } from "node:util";
+/**
+ * `kubectlApply` — apply a rendered manifest to a cluster.
+ *
+ * chant #1074 moved this off `kubectl apply -f`. The activity contract is
+ * unchanged (a manifest path, an optional context, `Promise<void>`, the
+ * `longInfra` profile's 15s heartbeat) because Temporal workers register it by
+ * that signature; what changed is underneath. The name is kept for the same
+ * reason.
+ *
+ * chant #1075 finished the job on two axes:
+ *
+ * - **Identity.** The field manager is no longer the bare `chant` but
+ *   `chant:<stack>`, derived from the project's `ownership.stack` — the same
+ *   identity the ownership label already carries. See
+ *   `@intentius/chant-k8s-client`'s `field-manager.ts`.
+ * - **Deletes.** `nativeApply`'s kubectl branch used to shell
+ *   `kubectl apply --prune --selector <marker>`; that branch now routes here,
+ *   so the prune had to come with it. {@link applyManifest} implements it
+ *   against the typed client, scoped to the ownership marker exactly as the
+ *   shelled prune was, and never touching an object that does not carry it.
+ *
+ * Consequences worth knowing:
+ *
+ * - **A worker image needs no `kubectl` binary.** That was the point.
+ * - **It is a server-side apply**, rather than the client-side three-way merge
+ *   `kubectl apply` performs by default. A conflict with another field manager
+ *   arrives as a `FieldManagerConflictError` naming the competing manager and
+ *   the contested paths — never as a silent overwrite, and never force-resolved
+ *   on chant's initiative.
+ * - **Documents apply in file order**, as `kubectl apply -f` does, and a
+ *   directory's files are read in sorted order.
+ */
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { loadAll } from "js-yaml";
 import { safeHeartbeat } from "@intentius/chant/op";
+import { loadChantConfig, resolveOwnershipMarker } from "@intentius/chant/config";
+import {
+  hasOwnershipMarker,
+  LABEL_OWNERSHIP_KEYS,
+  OWNERSHIP_MANAGED_BY_VALUE,
+} from "@intentius/chant/ownership";
+import type { K8sClient, K8sObject } from "@intentius/chant-k8s-client";
+import { defaultK8sConnector, type K8sConnector } from "../../api/connect";
+import { operationFor } from "../../api/operation-surface";
+import { DEFAULT_IMPORT_TYPES } from "../../api/sweep-types";
 
-const execAsync = promisify(exec);
+/**
+ * How the apply treats chant-owned objects that are no longer declared. The
+ * same three values `nativeApply` has always taken; `gated` differs from
+ * `owned-only` only in that the workflow pauses for approval first, which is
+ * the composite's business, not this activity's.
+ */
+export type ApplyDeleteMode = "never" | "owned-only" | "gated";
 
 export interface KubectlApplyArgs {
+  /** Path to a manifest file, or a directory of them. */
   manifest: string;
   /**
    * kubectl context name. Uses the ambient context if omitted. To target the
@@ -13,26 +64,341 @@ export interface KubectlApplyArgs {
    * `./index.ts` and pass `.context` through.
    */
   context?: string;
+  /**
+   * chant environment, used to resolve `k8s.profiles.<env>.context` when no
+   * explicit `context` is given. Optional and additive: omitting both keeps
+   * the previous behavior of using whatever the kubeconfig selects.
+   */
+  environment?: string;
+  /**
+   * Field manager recorded on the applied fields. Omitted derives it from the
+   * project's `ownership.stack` (chant #1075) — `chant:<stack>`, or the bare
+   * `chant` when the project sets none.
+   */
+  fieldManager?: string;
+  /**
+   * Ownership stack, when the caller already knows it and would rather not
+   * have the project config read. Ignored if `fieldManager` is set.
+   */
+  stack?: string;
+  /**
+   * Take ownership of fields another manager owns instead of failing with a
+   * `FieldManagerConflictError`. **Never defaulted on** — see chant #1075.
+   */
+  force?: boolean;
+  /**
+   * Delete chant-owned objects that are no longer declared. Default `never`.
+   * Deletes are scoped to the ownership marker, so an object chant did not
+   * stamp is never a candidate.
+   */
+  deleteMode?: ApplyDeleteMode;
+  /**
+   * Server-side dry run — every document is validated and would-be-applied,
+   * nothing is persisted, and pruning is skipped entirely (a prune candidate
+   * list computed from a state that was never written would be misleading).
+   * Optional and additive (chant #1079): `chant kube apply`'s confirmation
+   * gate uses this to preview an apply before anything mutates the cluster;
+   * Op callers keep the previous behavior by leaving it unset.
+   */
+  dryRun?: boolean;
+  /** Project directory whose `chant.config.ts` carries `ownership`. Defaults to cwd. */
+  cwd?: string;
+}
+
+/** One object the apply touched. */
+export interface AppliedRef {
+  apiVersion: string;
+  kind: string;
+  name: string;
+  namespace?: string;
+}
+
+/** What {@link applyManifest} did. */
+export interface ApplyManifestResult {
+  /** The field manager every object was applied as. */
+  fieldManager: string;
+  applied: AppliedRef[];
+  /** Objects deleted because they carried chant's marker and are no longer declared. */
+  pruned: AppliedRef[];
+}
+
+/** Read a manifest path — one file, or every YAML/JSON file in a directory. */
+export function readManifestDocuments(path: string): Record<string, unknown>[] {
+  const files = statSync(path).isDirectory()
+    ? readdirSync(path)
+        .filter((f) => /\.(ya?ml|json)$/i.test(f))
+        .sort()
+        .map((f) => join(path, f))
+    : [path];
+
+  const documents: Record<string, unknown>[] = [];
+  for (const file of files) {
+    for (const doc of loadAll(readFileSync(file, "utf-8"))) {
+      // Multi-document YAML files routinely carry empty documents between
+      // separators; they are not objects to apply.
+      if (doc && typeof doc === "object") documents.push(doc as Record<string, unknown>);
+    }
+  }
+  return documents;
 }
 
 /**
- * Run `kubectl apply -f <manifest>`.
- * Uses longInfra profile — 20m timeout, heartbeat every 15s.
+ * The field manager to apply as: an explicit one, else `chant:<stack>` from a
+ * caller-supplied stack, else `chant:<stack>` from the project's `ownership`
+ * config, else the bare `chant`.
+ *
+ * A project config that cannot be read falls back to the bare `chant` with a
+ * warning rather than failing the apply — an activity handed a manifest path
+ * and nothing else is a supported way to call this, and its cwd need not be a
+ * chant project at all. The warning is there because a *silent* downgrade
+ * would change which fields chant owns without saying so.
+ */
+export async function resolveFieldManager(args: KubectlApplyArgs): Promise<string> {
+  return (await resolveApplyIdentity(args)).fieldManager;
+}
+
+/**
+ * The stack and the field manager together, resolved once. The prune needs the
+ * stack for its selector and the apply needs the manager; reading the project
+ * config twice for one apply would be silly, and could disagree with itself if
+ * the file changed in between.
+ */
+async function resolveApplyIdentity(
+  args: KubectlApplyArgs,
+): Promise<{ fieldManager: string; stack?: string }> {
+  const { fieldManagerFor, assertValidFieldManager } = await import("@intentius/chant-k8s-client");
+
+  let stack = args.stack;
+  if (stack === undefined) {
+    try {
+      const { config } = await loadChantConfig(args.cwd ?? process.cwd());
+      stack = resolveOwnershipMarker(config)?.stack;
+    } catch (err) {
+      console.warn(
+        `[k8s] could not read the project config to derive a field manager ` +
+          `(${err instanceof Error ? err.message : String(err)}); applying as the unqualified "chant"`,
+      );
+    }
+  }
+
+  if (args.fieldManager !== undefined) {
+    assertValidFieldManager(args.fieldManager);
+    return { fieldManager: args.fieldManager, ...(stack !== undefined ? { stack } : {}) };
+  }
+  return {
+    fieldManager: fieldManagerFor(stack !== undefined ? { stack } : undefined),
+    ...(stack !== undefined ? { stack } : {}),
+  };
+}
+
+/**
+ * Apply every document in `args.manifest`, then prune when asked.
+ *
+ * Returns what it did. `kubectlApply` is the registered activity and keeps its
+ * `Promise<void>` contract; this is the function `nativeApply` calls, because a
+ * dispatcher that reports "applied 12, pruned 2" is worth more than one that
+ * reports the shell command it ran.
  */
-export async function kubectlApply(args: KubectlApplyArgs, signal?: AbortSignal): Promise<void> {
-  const ctx = args.context ? `--context ${args.context}` : "";
+export async function applyManifest(
+  args: KubectlApplyArgs,
+  signal?: AbortSignal,
+  connect: K8sConnector = defaultK8sConnector,
+): Promise<ApplyManifestResult> {
+  const documents = readManifestDocuments(args.manifest);
+  const { fieldManager, stack } = await resolveApplyIdentity(args);
   const heartbeatInterval = setInterval(() => {
     safeHeartbeat({ step: "kubectl apply", manifest: args.manifest });
   }, 15_000);
 
   try {
-    const { stdout, stderr } = await execAsync(
-      `kubectl apply -f ${args.manifest} ${ctx} --wait=true`,
-      { signal },
-    );
-    if (stdout) console.log(stdout);
-    if (stderr) console.error(stderr);
+    const { client } = await connect({
+      ...(args.environment !== undefined ? { environment: args.environment } : {}),
+      ...(args.context !== undefined ? { context: args.context } : {}),
+      ...(args.cwd !== undefined ? { cwd: args.cwd } : {}),
+    });
+
+    const applied: AppliedRef[] = [];
+    for (const document of documents) {
+      const result = await client.apply(document as K8sObject, {
+        fieldManager,
+        force: args.force ?? false,
+        dryRun: args.dryRun,
+        signal,
+      });
+      const ref: AppliedRef = {
+        apiVersion: String(result.apiVersion ?? document.apiVersion ?? ""),
+        kind: String(result.kind ?? document.kind ?? ""),
+        name: String(result.metadata?.name ?? ""),
+        ...(result.metadata?.namespace !== undefined
+          ? { namespace: String(result.metadata.namespace) }
+          : {}),
+      };
+      applied.push(ref);
+      safeHeartbeat({
+        step: "kubectl apply",
+        manifest: args.manifest,
+        applied: `${ref.kind}/${ref.name}`,
+      });
+      console.log(`${ref.apiVersion} ${ref.kind}/${ref.name} applied${args.dryRun ? " (dry run — nothing persisted)" : ""}`);
+    }
+
+    const deleteMode = args.deleteMode ?? "never";
+    const pruned =
+      deleteMode === "never" || args.dryRun
+        ? []
+        : await pruneOrphans(client, applied, {
+            ...(stack !== undefined ? { stack } : {}),
+            signal,
+          });
+
+    return { fieldManager, applied, pruned };
   } finally {
     clearInterval(heartbeatInterval);
   }
 }
+
+/**
+ * Apply every document in `args.manifest`.
+ * Uses longInfra profile — 20m timeout, heartbeat every 15s.
+ */
+export async function kubectlApply(
+  args: KubectlApplyArgs,
+  signal?: AbortSignal,
+  connect: K8sConnector = defaultK8sConnector,
+): Promise<void> {
+  await applyManifest(args, signal, connect);
+}
+
+/**
+ * Delete chant-owned objects that the apply set no longer declares.
+ *
+ * This replaces `kubectl apply --prune --selector <marker>=chant`, and keeps
+ * its two safety properties exactly:
+ *
+ * - **Marker-scoped.** Only objects carrying chant's managed-by label are
+ *   candidates; the label selector is sent to the server, and the marker is
+ *   re-checked on every object before it is deleted. An unmarked resource is
+ *   never a candidate, so a hand-made object in the same namespace is safe.
+ * - **Namespace-scoped to the apply.** Namespaced kinds are swept only in the
+ *   namespaces the apply set touched (the context's default namespace when it
+ *   named none), which is what kubectl's prune does. A manifest that mentions
+ *   `prod` never reaches into `staging`. Whether a kind *is* namespaced comes
+ *   from the cluster's own discovery, never from whether a document happened
+ *   to name a namespace — guessing that wrong is the one way this could widen
+ *   into a cluster-wide sweep.
+ *
+ * Which *kinds* get swept is the union of the kinds the apply set contains and
+ * chant's default sweep set (`DEFAULT_IMPORT_TYPES` — the same list `chant
+ * import` uses when nothing narrows it). The union matters: a kind removed
+ * from source entirely appears nowhere in the apply set, and pruning only what
+ * is still declared would leave it behind forever. Per-namespace lists rather
+ * than one cluster-wide list per kind, so a namespace-scoped service account
+ * can still prune.
+ */
+async function pruneOrphans(
+  client: K8sClient,
+  applied: readonly AppliedRef[],
+  options: { stack?: string; signal?: AbortSignal },
+): Promise<AppliedRef[]> {
+  const stack = options.stack;
+  const selector = [
+    `${LABEL_OWNERSHIP_KEYS.managedBy}=${OWNERSHIP_MANAGED_BY_VALUE}`,
+    ...(stack ? [`${LABEL_OWNERSHIP_KEYS.stack}=${stack}`] : []),
+  ].join(",");
+
+  const namespaces = [...new Set(applied.map((a) => a.namespace).filter((n): n is string => !!n))];
+  if (namespaces.length === 0 && applied.length > 0) namespaces.push(client.defaultNamespace);
+  const declared = new Set(applied.map(refKey));
+
+  // Every kind that could hold an orphan: the apply set's own, plus the
+  // default sweep set so a kind deleted from source entirely is still reached.
+  const sweeps = new Map<string, { apiVersion: string; kind: string }>();
+  for (const entityType of DEFAULT_IMPORT_TYPES) {
+    const operation = operationFor(entityType);
+    if (!operation) continue;
+    sweeps.set(`${operation.apiVersion}/${operation.kind}`, {
+      apiVersion: operation.apiVersion,
+      kind: operation.kind,
+    });
+  }
+  for (const ref of applied) {
+    if (!ref.apiVersion || !ref.kind) continue;
+    sweeps.set(`${ref.apiVersion}/${ref.kind}`, { apiVersion: ref.apiVersion, kind: ref.kind });
+  }
+
+  // (kind, namespace) pairs to list. Scope comes from the cluster's discovery,
+  // which is the only thing that knows it for the version this cluster serves;
+  // a kind discovery does not report is dropped rather than swept blindly.
+  const resolved = await client.concurrently([...sweeps.values()], async (sweep) => {
+    const info = await client
+      .resolve({ apiVersion: sweep.apiVersion, kind: sweep.kind }, options.signal)
+      .catch(() => undefined);
+    return info ? { ...sweep, namespaced: info.namespaced } : undefined;
+  });
+
+  const targets: Array<{ apiVersion: string; kind: string; namespace?: string }> = [];
+  for (const sweep of resolved) {
+    if (!sweep) continue;
+    if (!sweep.namespaced) {
+      targets.push({ apiVersion: sweep.apiVersion, kind: sweep.kind });
+      continue;
+    }
+    for (const namespace of namespaces) {
+      targets.push({ apiVersion: sweep.apiVersion, kind: sweep.kind, namespace });
+    }
+  }
+
+  const found = await client.concurrently(targets, async (target) => {
+    try {
+      const items = await client.list(
+        { apiVersion: target.apiVersion, kind: target.kind },
+        {
+          labelSelector: selector,
+          ...(target.namespace !== undefined ? { namespace: target.namespace } : {}),
+          ...(options.signal ? { signal: options.signal } : {}),
+        },
+      );
+      return items.map((item) => ({ target, item }));
+    } catch {
+      // Kind not served here, or the read was denied. Neither is evidence that
+      // something should be deleted, so the sweep skips it rather than failing
+      // the apply that already succeeded.
+      return [];
+    }
+  });
+
+  const candidates: AppliedRef[] = [];
+  const seen = new Set<string>();
+  for (const { target, item } of found.flat()) {
+    const name = item.metadata?.name;
+    if (!name) continue;
+    // The server filtered by label already; this re-check is the one that
+    // matters, because a delete is not undoable.
+    if (!hasOwnershipMarker(item.metadata?.labels, LABEL_OWNERSHIP_KEYS)) continue;
+    // Already terminating — deleting again is noise, not progress.
+    if (item.metadata?.deletionTimestamp !== undefined) continue;
+    const ref: AppliedRef = {
+      apiVersion: target.apiVersion,
+      kind: target.kind,
+      name,
+      ...(item.metadata?.namespace !== undefined ? { namespace: item.metadata.namespace } : {}),
+    };
+    const key = refKey(ref);
+    if (declared.has(key) || seen.has(key)) continue;
+    seen.add(key);
+    candidates.push(ref);
+  }
+
+  const pruned: AppliedRef[] = [];
+  for (const ref of candidates) {
+    await client.delete(ref, { ...(options.signal ? { signal: options.signal } : {}) });
+    pruned.push(ref);
+    safeHeartbeat({ step: "prune", pruned: `${ref.kind}/${ref.name}` });
+    console.log(`${ref.apiVersion} ${ref.kind}/${ref.name} pruned (chant-owned, no longer declared)`);
+  }
+  return pruned;
+}
+
+function refKey(ref: AppliedRef): string {
+  return `${ref.apiVersion}/${ref.kind}/${ref.namespace ?? ""}/${ref.name}`;
+}

package/src/op/activities/wait-for-ready.test.ts

@@ -1,6 +1,7 @@
 import { describe, test, expect } from "vitest";
 import {
   waitForReady,
+  apiResourceFetcher,
   ReadinessFailedError,
   readinessFor,
   isReady,
@@ -11,6 +12,7 @@ import {
 } from "./wait-for-ready";
 // The k8sWait profile marks ReadinessFailedError non-retryable for this activity.
 import { TEMPORAL_ACTIVITY_PROFILES } from "@intentius/chant-lexicon-temporal/config";
+import { fakeCluster, objectKey } from "../../api/fake-cluster";
 
 /** A fetcher returning a scripted sequence of objects, repeating the last. */
 function scriptedFetcher(sequence: Array<Record<string, unknown>>): ResourceFetcher {
@@ -103,3 +105,95 @@ describe("waitForReady", () => {
     expect((obj as any).status.state).toBe("running");
   });
 });
+
+/**
+ * chant #1074 — the reader underneath. The activity's contract is unchanged
+ * (`kind` is still whatever `kubectl get` accepts), so what has to be proven is
+ * that the same strings still resolve, now through the cluster's own API
+ * discovery rather than by handing them to a `kubectl` process.
+ */
+describe("apiResourceFetcher (chant #1074)", () => {
+  const readyObject = (apiVersion: string, kind: string, name: string, namespace?: string) => ({
+    apiVersion,
+    kind,
+    metadata: { name, ...(namespace ? { namespace } : {}), generation: 1 },
+    status: { observedGeneration: 1, conditions: [{ type: "Ready", status: "True" }] },
+  });
+
+  test.each([
+    ["raycluster.ray.io", "ray.io/v1", "RayCluster", "rayclusters", "K8s::Ray::RayCluster"],
+    ["certificates", "cert-manager.io/v1", "Certificate", "certificates", "K8s::CertManager::Certificate"],
+    ["Certificate", "cert-manager.io/v1", "Certificate", "certificates", "K8s::CertManager::Certificate"],
+    ["deployments", "apps/v1", "Deployment", "deployments", "K8s::Apps::Deployment"],
+  ])("`%s` resolves to %s %s via discovery", async (kindArg, apiVersion, kind, plural, entityType) => {
+    const cluster = fakeCluster({
+      serves: [entityType],
+      objects: { [objectKey(apiVersion, kind, "thing", "prod")]: readyObject(apiVersion, kind, "thing", "prod") },
+    });
+
+    const obj = await waitForReady(
+      { kind: kindArg, name: "thing", namespace: "prod", intervalMs: 0 },
+      undefined,
+      apiResourceFetcher(cluster.connector),
+    );
+
+    expect((obj as Record<string, unknown>).kind).toBe(kind);
+    expect(cluster.layer.paths()).toContain(
+      `${apiVersion.includes("/") ? `/apis/${apiVersion}` : `/api/${apiVersion}`}/namespaces/prod/${plural}/thing`,
+    );
+  });
+
+  test("resolution and the connection are done once, not once per poll", async () => {
+    const notReady = {
+      apiVersion: "cert-manager.io/v1",
+      kind: "Certificate",
+      metadata: { name: "tls", namespace: "prod", generation: 1 },
+      status: { observedGeneration: 1, conditions: [{ type: "Ready", status: "False" }] },
+    };
+    let polls = 0;
+    const cluster = fakeCluster({
+      serves: ["K8s::CertManager::Certificate"],
+      objects: { [objectKey("cert-manager.io/v1", "Certificate", "tls", "prod")]: notReady },
+      respond: (req) => {
+        if (!req.path.endsWith("/certificates/tls")) return undefined;
+        polls++;
+        return polls < 3
+          ? { body: notReady }
+          : { body: { ...notReady, status: { observedGeneration: 1, conditions: [{ type: "Ready", status: "True" }] } } };
+      },
+    });
+
+    await waitForReady(
+      { kind: "certificate", name: "tls", namespace: "prod", intervalMs: 0 },
+      undefined,
+      apiResourceFetcher(cluster.connector),
+    );
+
+    expect(polls).toBe(3);
+    expect(cluster.connects).toHaveLength(1);
+    // Discovery once; the three object reads reuse the cached resource list.
+    expect(cluster.layer.paths().filter((p) => p === "/apis/cert-manager.io/v1")).toHaveLength(1);
+  });
+
+  test("a kind the cluster does not serve fails loudly instead of polling forever", async () => {
+    const cluster = fakeCluster({ serves: ["K8s::Apps::Deployment"] });
+    await expect(
+      waitForReady({ kind: "widgets", name: "w", intervalMs: 0 }, undefined, apiResourceFetcher(cluster.connector)),
+    ).rejects.toThrow(/no resource matching "widgets"/);
+  });
+
+  test("an explicit context is passed to the connector, closing the read/write split", async () => {
+    const cluster = fakeCluster({
+      serves: ["K8s::Apps::Deployment"],
+      objects: { [objectKey("apps/v1", "Deployment", "web", "prod")]: readyObject("apps/v1", "Deployment", "web", "prod") },
+    });
+
+    await waitForReady(
+      { kind: "deployments", name: "web", namespace: "prod", context: "test-context", intervalMs: 0 },
+      undefined,
+      apiResourceFetcher(cluster.connector),
+    );
+
+    expect(cluster.connects[0]).toMatchObject({ context: "test-context" });
+  });
+});

package/src/op/activities/wait-for-ready.ts

@@ -1,8 +1,5 @@
-import { exec } from "node:child_process";
-import { promisify } from "node:util";
 import { safeHeartbeat, sleep } from "@intentius/chant/op";
-
-const execAsync = promisify(exec);
+import { defaultK8sConnector, type K8sConnector } from "../../api/connect";
 
 /**
  * waitForReady — block until any operator-backed Kubernetes resource reports
@@ -11,9 +8,16 @@ const execAsync = promisify(exec);
  * Like `waitForArgoSync`, this activity is intentionally **dependency-light**:
  * its signature is primitives + a plain readiness spec, so a Temporal worker
  * loads it without importing the generated CRD declarable surface. It reads the
- * resource via `kubectl get -o json` (injectable for tests) and evaluates the
- * spec's predicates. It generalizes the bespoke `waitForArgoSync` /
- * `waitForStack` waits — see #365.
+ * resource and evaluates the spec's predicates. It generalizes the bespoke
+ * `waitForArgoSync` / `waitForStack` waits — see #365.
+ *
+ * chant #1074 moved the read from `kubectl get -o json` to the typed API
+ * client, so a worker image needs no `kubectl` binary. The signature is
+ * unchanged — `kind` is still whatever `kubectl get` accepts, because that is
+ * what every existing caller passes, and the client resolves it through the
+ * cluster's own API discovery exactly as kubectl does: plural, then singular,
+ * then kind, then short name, with anything after the first dot read as the
+ * API group.
  */
 
 // ── Readiness spec (plain data — no generated-type imports) ──────────
@@ -154,6 +158,11 @@ export interface WaitForReadyArgs {
    * `.context` through.
    */
   context?: string;
+  /**
+   * chant environment, used to resolve `k8s.profiles.<env>.context` when no
+   * explicit `context` is given. Optional and additive.
+   */
+  environment?: string;
   /** API group, used to pick a readiness override when `spec` is not given. */
   group?: string;
   /** Explicit readiness spec — wins over the registry/default. */
@@ -168,15 +177,57 @@ export type ResourceFetcher = (
   signal?: AbortSignal,
 ) => Promise<Record<string, unknown>>;
 
-/** Read the resource via `kubectl get -o json`. */
-async function fetchViaKubectl(args: WaitForReadyArgs, signal?: AbortSignal): Promise<Record<string, unknown>> {
-  const ns = args.namespace ? `-n ${args.namespace}` : "";
-  const ctx = args.context ? `--context ${args.context}` : "";
-  const { stdout } = await execAsync(`kubectl get ${args.kind} ${args.name} ${ns} ${ctx} -o json`, { signal });
-  return JSON.parse(stdout) as Record<string, unknown>;
+/**
+ * Read the resource through the typed API client.
+ *
+ * A client is built once per `waitForReady` call and reused for every poll, so
+ * a 20-minute wait does not re-parse the kubeconfig or re-invoke an exec
+ * credential plugin on each iteration — and neither does it re-run discovery,
+ * which the client caches per API version.
+ */
+export function apiResourceFetcher(connect: K8sConnector = defaultK8sConnector): ResourceFetcher {
+  let connection: ReturnType<K8sConnector> | undefined;
+  let resolved: { apiVersion: string; kind: string } | undefined;
+
+  return async (args, signal) => {
+    connection ??= connect({
+      ...(args.environment !== undefined ? { environment: args.environment } : {}),
+      ...(args.context !== undefined ? { context: args.context } : {}),
+    });
+    const { client } = await connection;
+
+    if (!resolved) {
+      const info = await client.resolve(
+        { resource: args.kind, ...(args.group ? { group: args.group } : {}) },
+        signal,
+      );
+      if (!info) {
+        throw new Error(
+          `waitForReady: the cluster's API discovery reports no resource matching "${args.kind}"` +
+            `${args.group ? ` in group "${args.group}"` : ""} — nothing to wait for`,
+        );
+      }
+      resolved = { apiVersion: info.apiVersion, kind: info.kind };
+    }
+
+    return (await client.read(
+      {
+        apiVersion: resolved.apiVersion,
+        kind: resolved.kind,
+        name: args.name,
+        ...(args.namespace ? { namespace: args.namespace } : {}),
+      },
+      { signal },
+    )) as Record<string, unknown>;
+  };
 }
 
-export const defaultResourceFetcher: ResourceFetcher = (args, signal) => fetchViaKubectl(args, signal);
+/**
+ * The production reader. Each call builds its own fetcher, so nothing is
+ * shared between two unrelated waits; a single `waitForReady` passes one
+ * fetcher through all of its polls, which is where the caching matters.
+ */
+export const defaultResourceFetcher: ResourceFetcher = (args, signal) => apiResourceFetcher()(args, signal);
 
 /**
  * Poll until the resource satisfies its readiness spec. Throws
@@ -189,7 +240,7 @@ export const defaultResourceFetcher: ResourceFetcher = (args, signal) => fetchVi
 export async function waitForReady(
   args: WaitForReadyArgs,
   signal?: AbortSignal,
-  fetcher: ResourceFetcher = defaultResourceFetcher,
+  fetcher: ResourceFetcher = apiResourceFetcher(),
 ): Promise<Record<string, unknown>> {
   const spec = args.spec ?? readinessFor(args.group, args.kind);
   const interval = args.intervalMs ?? 15_000;