@intentius/chant-k8s-client 0.42.1 → 0.44.2

package/dist/client.d.ts

@@ -125,6 +125,18 @@ export interface K8sClient {
     resolve(selector: ResourceSelector, signal?: AbortSignal): Promise<ApiResourceInfo | undefined>;
     /** GET one object. Throws {@link K8sApiError} with `notFound` when absent. */
     read(ref: ObjectRef, options?: ReadOptions): Promise<K8sObject>;
+    /**
+     * The exact request path {@link read} would GET for this ref — apiVersion and
+     * kind resolved against the cluster's own discovery (which supplies the
+     * plural and the scope), and the namespace defaulted from the resolved
+     * context when the ref carries none. `undefined` when discovery does not
+     * serve the kind, where no path exists.
+     *
+     * This is the observation wire's resolved query address (chant #1620): the
+     * per-entity record of what was actually asked of the cluster, so a
+     * consumer can tell "looked in the wrong place" from "not there".
+     */
+    pathFor(ref: ObjectRef, signal?: AbortSignal): Promise<string | undefined>;
     /** GET one object, returning undefined instead of throwing on a 404. */
     readIfPresent(ref: ObjectRef, options?: ReadOptions): Promise<K8sObject | undefined>;
     /** LIST a kind, optionally namespaced and label-filtered. Follows `continue` tokens. */
@@ -153,6 +165,15 @@ export interface K8sClient {
      * such groupVersion — an answer, not a failure. Cached like `resolve`.
      */
     resources(apiVersion: string, signal?: AbortSignal): Promise<ApiResourceInfo[]>;
+    /**
+     * One groupVersion per API group the cluster serves — each group's own
+     * `preferredVersion` (falling back to its first listed version), with the
+     * core group's `v1` first (chant #1517). This is the discovery-driven
+     * sweep's enumeration unit: one version per group names every kind exactly
+     * once, without re-listing the same resources at a second served version.
+     * Cached for the client's lifetime, like the rest of discovery.
+     */
+    preferredGroupVersions(signal?: AbortSignal): Promise<string[]>;
     /** The API resource lists discovery has been asked for so far, for tests and diagnostics. */
     discoveryCacheKeys(): string[];
 }

package/dist/client.d.ts.map

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

package/dist/errors.d.ts

@@ -30,6 +30,14 @@ export declare class K8sApiError extends Error {
     /** What was being addressed, e.g. `apps/v1 Deployment prod/web`. */
     readonly target?: string | undefined;
     readonly status?: K8sStatus | undefined;
+    /**
+     * Which cluster the failing read actually talked to, e.g.
+     * `context "k3d-fountain-local" (bound by k8s.profiles.local.context)`.
+     * Stamped by the client that issued the request (chant #1488) — a
+     * `read-failed` that does not name the cluster it read cost an afternoon on
+     * a laptop with two k3d clusters, so the failure carries it from birth.
+     */
+    contextNote?: string;
     constructor(statusCode: number, reason: string | undefined, apiMessage: string, 
     /** What was being addressed, e.g. `apps/v1 Deployment prod/web`. */
     target?: string | undefined, status?: K8sStatus | undefined);
@@ -58,6 +66,8 @@ export declare class K8sApiError extends Error {
  */
 export declare class K8sTransportError extends Error {
     readonly target?: string | undefined;
+    /** Which cluster context the failed request was aimed at — see {@link K8sApiError.contextNote}. */
+    contextNote?: string;
     constructor(message: string, target?: string | undefined, options?: {
         cause?: unknown;
     });

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,+EAA+E;AAC/E,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;aAElB,UAAU,EAAE,MAAM;aAClB,MAAM,EAAE,MAAM,GAAG,SAAS;aAC1B,UAAU,EAAE,MAAM;IAClC,oEAAoE;aACpD,MAAM,CAAC,EAAE,MAAM;aACf,MAAM,CAAC,EAAE,SAAS;gBALlB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,UAAU,EAAE,MAAM;IAClC,oEAAoE;IACpD,MAAM,CAAC,EAAE,MAAM,YAAA,EACf,MAAM,CAAC,EAAE,SAAS,YAAA;IASpC,0EAA0E;IAC1E,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,4EAA4E;IAC5E,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,8CAA8C;IAC9C,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED;;;;OAIG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;OAGG;IACH,MAAM,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW;CAapF;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;aAGxB,MAAM,CAAC,EAAE,MAAM;gBAD/B,OAAO,EAAE,MAAM,EACC,MAAM,CAAC,EAAE,MAAM,YAAA,EAC/B,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAMhC;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,KAAK,CAAC,EAAE,OAAO;CAS5B;AAED;;;;;;;GAOG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;aAEpC,OAAO,EAAE,MAAM;aACf,OAAO,EAAE,SAAS,MAAM,EAAE;gBAD1B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,SAAS,MAAM,EAAE;CAU7C;AAED;;;;;GAKG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED,4EAA4E;AAC5E,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;aAE3B,YAAY,EAAE,MAAM;gBAApB,YAAY,EAAE,MAAM,EACpC,OAAO,CAAC,EAAE,MAAM;CAKnB"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,+EAA+E;AAC/E,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;aAWlB,UAAU,EAAE,MAAM;aAClB,MAAM,EAAE,MAAM,GAAG,SAAS;aAC1B,UAAU,EAAE,MAAM;IAClC,oEAAoE;aACpD,MAAM,CAAC,EAAE,MAAM;aACf,MAAM,CAAC,EAAE,SAAS;IAfpC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;gBAGH,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,UAAU,EAAE,MAAM;IAClC,oEAAoE;IACpD,MAAM,CAAC,EAAE,MAAM,YAAA,EACf,MAAM,CAAC,EAAE,SAAS,YAAA;IASpC,0EAA0E;IAC1E,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,4EAA4E;IAC5E,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,8CAA8C;IAC9C,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED;;;;OAIG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;OAGG;IACH,MAAM,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW;CAapF;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;aAMxB,MAAM,CAAC,EAAE,MAAM;IALjC,mGAAmG;IACnG,WAAW,CAAC,EAAE,MAAM,CAAC;gBAGnB,OAAO,EAAE,MAAM,EACC,MAAM,CAAC,EAAE,MAAM,YAAA,EAC/B,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAMhC;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,KAAK,CAAC,EAAE,OAAO;CAS5B;AAED;;;;;;;GAOG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;aAEpC,OAAO,EAAE,MAAM;aACf,OAAO,EAAE,SAAS,MAAM,EAAE;gBAD1B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,SAAS,MAAM,EAAE;CAU7C;AAED;;;;;GAKG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED,4EAA4E;AAC5E,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;aAE3B,YAAY,EAAE,MAAM;gBAApB,YAAY,EAAE,MAAM,EACpC,OAAO,CAAC,EAAE,MAAM;CAKnB"}

package/dist/types.d.ts

@@ -115,6 +115,15 @@ export interface K8sClientOptions {
     concurrency?: number;
     /** Where the context came from, for provenance. Default `ambient`. */
     contextSource?: "bound" | "ambient";
+    /**
+     * How the context was selected, in words — e.g.
+     * `bound by k8s.profiles.prod.context` or
+     * `ambient; no k8s.profiles.local binding`. Stamped (with the resolved
+     * context name) onto every API/transport failure the client throws, so a
+     * `read-failed` reason names the cluster it read (chant #1488). Defaults to
+     * the bare `contextSource`.
+     */
+    contextLabel?: string;
 }
 /**
  * `@kubernetes/client-node`'s promise-shaped HTTP library: it receives the

package/dist/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-k8s-client",
-  "version": "0.42.1",
+  "version": "0.44.2",
   "description": "Typed Kubernetes API client for chant — the read/write path of the k8s lexicon, kept out of the build path",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant/lexicons/k8s/api-client/",

package/src/client.test.ts

@@ -117,6 +117,47 @@ describe("createK8sClient — kubeconfig and credential policy", () => {
     expect(layer.requests).toHaveLength(0);
   });
 
+  test("an API failure names the context it read (#1488)", async () => {
+    const layer = cluster({}, (req) =>
+      req.path.endsWith("/deployments/web")
+        ? { status: 500, body: statusBody(500, "InternalError", "etcdserver: leader changed") }
+        : undefined,
+    );
+    const c = await client(layer);
+    const err = await c.read({ apiVersion: "apps/v1", kind: "Deployment", name: "web", namespace: "prod" }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(K8sApiError);
+    expect((err as K8sApiError).contextNote).toBe('context "test-context" (ambient)');
+  });
+
+  test("a bound client's failures carry the binding story via contextLabel (#1488)", async () => {
+    const layer = cluster({}, (req) =>
+      req.path.endsWith("/deployments/web") ? { status: 503, body: statusBody(503, "ServiceUnavailable", "apiserver down") } : undefined,
+    );
+    const c = await createK8sClient({
+      kubeconfig: fakeKubeconfig({
+        contexts: [{ name: "staging-eks" }, { name: "prod-eks", cluster: "prod", user: "prod-user" }],
+        currentContext: "staging-eks",
+      }),
+      context: "prod-eks",
+      contextSource: "bound",
+      contextLabel: "bound by k8s.profiles.prod.context",
+      requestLayer: layer,
+    });
+    const err = await c.read({ apiVersion: "apps/v1", kind: "Deployment", name: "web", namespace: "prod" }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(K8sApiError);
+    expect((err as K8sApiError).contextNote).toBe('context "prod-eks" (bound by k8s.profiles.prod.context)');
+  });
+
+  test("a transport failure names the context it was aimed at (#1488)", async () => {
+    const layer = fakeRequestLayer(() => {
+      throw new Error("connect ECONNREFUSED 127.0.0.1:6443");
+    });
+    const c = await createK8sClient({ kubeconfig: fakeKubeconfig(), requestLayer: layer });
+    const err = await c.read({ apiVersion: "apps/v1", kind: "Deployment", name: "web" }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(K8sTransportError);
+    expect((err as K8sTransportError).contextNote).toBe('context "test-context" (ambient)');
+  });
+
   test("an exec credential plugin off the allowlist refuses before it can run", async () => {
     const layer = cluster();
     await expect(
@@ -201,6 +242,39 @@ describe("resource resolution through the cluster's own discovery", () => {
     expect(c.discoveryCacheKeys()).toEqual(["apps/v1"]);
   });
 
+  // chant #1517 — the runtime-children sweep's enumeration unit: one version
+  // per group, so every kind is named exactly once.
+  test("preferredGroupVersions returns core v1 plus each group's own preferredVersion, once", async () => {
+    const layer = fakeRequestLayer((req) => {
+      if (req.path === "/api") return { body: { kind: "APIVersions", versions: ["v1"] } };
+      if (req.path === "/apis") {
+        return {
+          body: {
+            kind: "APIGroupList",
+            groups: [
+              {
+                name: "apps",
+                preferredVersion: { groupVersion: "apps/v1", version: "v1" },
+                versions: [{ groupVersion: "apps/v1" }, { groupVersion: "apps/v1beta1" }],
+              },
+              // A group reporting no preferredVersion falls back to its first
+              // listed version rather than being dropped.
+              { name: "widgets.example.com", versions: [{ groupVersion: "widgets.example.com/v1alpha1" }] },
+            ],
+          },
+        };
+      }
+      return { status: 404, body: statusBody(404, "NotFound", `${req.path} not found`) };
+    });
+    const c = await client(layer);
+
+    expect(await c.preferredGroupVersions()).toEqual(["v1", "apps/v1", "widgets.example.com/v1alpha1"]);
+
+    // Cached: a second call issues no further discovery requests.
+    await c.preferredGroupVersions();
+    expect(layer.paths().filter((p) => p === "/apis")).toHaveLength(1);
+  });
+
   test("kubectl-style resource strings resolve the way kubectl resolves them", async () => {
     const c = await client(cluster());
     // plural.group — how waitForReady's callers have always spelled CRDs
@@ -304,6 +378,28 @@ describe("reads", () => {
       c.readIfPresent({ apiVersion: "apps/v1", kind: "Deployment", name: "denied", namespace: "prod" }),
     ).rejects.toThrow(K8sApiError);
   });
+
+  test("pathFor returns the exact path read would GET, with the namespace defaulted (chant #1620)", async () => {
+    const c = await client(cluster());
+    // No namespace on the ref: the resolved path shows where the read actually
+    // went — the context's default — which is the whole diagnostic point.
+    expect(await c.pathFor({ apiVersion: "apps/v1", kind: "Deployment", name: "web" })).toBe(
+      "/apis/apps/v1/namespaces/default/deployments/web",
+    );
+    expect(await c.pathFor({ apiVersion: "apps/v1", kind: "Deployment", name: "web", namespace: "prod" })).toBe(
+      "/apis/apps/v1/namespaces/prod/deployments/web",
+    );
+  });
+
+  test("pathFor on a cluster-scoped kind carries no namespace segment", async () => {
+    const c = await client(cluster());
+    expect(await c.pathFor({ apiVersion: "v1", kind: "Namespace", name: "ns-a" })).toBe("/api/v1/namespaces/ns-a");
+  });
+
+  test("pathFor is undefined for a kind discovery does not serve — no path exists", async () => {
+    const c = await client(cluster());
+    expect(await c.pathFor({ apiVersion: "widgets.example.com/v1", kind: "Widget", name: "w" })).toBeUndefined();
+  });
 });
 
 describe("concurrency", () => {

package/src/client.ts

@@ -187,6 +187,18 @@ export interface K8sClient {
   resolve(selector: ResourceSelector, signal?: AbortSignal): Promise<ApiResourceInfo | undefined>;
   /** GET one object. Throws {@link K8sApiError} with `notFound` when absent. */
   read(ref: ObjectRef, options?: ReadOptions): Promise<K8sObject>;
+  /**
+   * The exact request path {@link read} would GET for this ref — apiVersion and
+   * kind resolved against the cluster's own discovery (which supplies the
+   * plural and the scope), and the namespace defaulted from the resolved
+   * context when the ref carries none. `undefined` when discovery does not
+   * serve the kind, where no path exists.
+   *
+   * This is the observation wire's resolved query address (chant #1620): the
+   * per-entity record of what was actually asked of the cluster, so a
+   * consumer can tell "looked in the wrong place" from "not there".
+   */
+  pathFor(ref: ObjectRef, signal?: AbortSignal): Promise<string | undefined>;
   /** GET one object, returning undefined instead of throwing on a 404. */
   readIfPresent(ref: ObjectRef, options?: ReadOptions): Promise<K8sObject | undefined>;
   /** LIST a kind, optionally namespaced and label-filtered. Follows `continue` tokens. */
@@ -215,6 +227,15 @@ export interface K8sClient {
    * such groupVersion — an answer, not a failure. Cached like `resolve`.
    */
   resources(apiVersion: string, signal?: AbortSignal): Promise<ApiResourceInfo[]>;
+  /**
+   * One groupVersion per API group the cluster serves — each group's own
+   * `preferredVersion` (falling back to its first listed version), with the
+   * core group's `v1` first (chant #1517). This is the discovery-driven
+   * sweep's enumeration unit: one version per group names every kind exactly
+   * once, without re-listing the same resources at a second served version.
+   * Cached for the client's lifetime, like the rest of discovery.
+   */
+  preferredGroupVersions(signal?: AbortSignal): Promise<string[]>;
   /** The API resource lists discovery has been asked for so far, for tests and diagnostics. */
   discoveryCacheKeys(): string[];
 }
@@ -231,6 +252,14 @@ interface ApiResourceListResponse {
   }>;
 }
 
+/** The `/api` + `/apis` root discovery documents, kept structured so both the
+ * flat enumeration (`servedGroupVersions`) and the one-per-group enumeration
+ * (`preferredGroupVersions`, chant #1517) derive from a single cached fetch. */
+interface RootDiscovery {
+  coreVersions: string[];
+  groups: Array<{ preferred?: string; versions: string[] }>;
+}
+
 /**
  * Build a client. Nothing is read from the network here — the kubeconfig is
  * parsed, the context resolved, and the credential policy enforced, all before
@@ -301,12 +330,23 @@ export async function createK8sClient(options: K8sClientOptions = {}): Promise<K
   const defaultNamespace = kc.getContextObject(kc.getCurrentContext())?.namespace || "default";
   const concurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
 
+  // Which cluster this client reads, in words, stamped onto every failure it
+  // throws (chant #1488). A `read-failed` that does not say which context it
+  // read turned "the ambient context moved" into an afternoon of debugging;
+  // naming it here — at construction, once — means every read path's
+  // classification carries it without each caller remembering to.
+  const contextNote = `context "${provenance.context ?? "(unset)"}" (${options.contextLabel ?? provenance.contextSource})`;
+  function noted<T extends { contextNote?: string }>(err: T): T {
+    err.contextNote = contextNote;
+    return err;
+  }
+
   // apiVersion → its APIResourceList, or null when the cluster does not serve
   // that group/version at all. Promises are cached, not values, so N entities
   // resolved concurrently issue one discovery request between them rather
   // than N identical ones.
   const discoveryCache = new Map<string, Promise<ApiResourceListResponse | null>>();
-  let groupVersionsCache: Promise<string[]> | undefined;
+  let rootDiscoveryCache: Promise<RootDiscovery> | undefined;
 
   async function send(
     path: string,
@@ -338,10 +378,10 @@ export async function createK8sClient(options: K8sClientOptions = {}): Promise<K
         .send(ctx)
         .toPromise()) as unknown as ResponseContextLike;
     } catch (err) {
-      throw new K8sTransportError(
-        err instanceof Error ? err.message : String(err),
-        opts.target ?? `${method} ${path}`,
-        { cause: err },
+      throw noted(
+        new K8sTransportError(err instanceof Error ? err.message : String(err), opts.target ?? `${method} ${path}`, {
+          cause: err,
+        }),
       );
     }
 
@@ -349,10 +389,12 @@ export async function createK8sClient(options: K8sClientOptions = {}): Promise<K
     try {
       text = await response.body.text();
     } catch (err) {
-      throw new K8sTransportError(
-        `response body could not be read: ${err instanceof Error ? err.message : String(err)}`,
-        opts.target ?? `${method} ${path}`,
-        { cause: err },
+      throw noted(
+        new K8sTransportError(
+          `response body could not be read: ${err instanceof Error ? err.message : String(err)}`,
+          opts.target ?? `${method} ${path}`,
+          { cause: err },
+        ),
       );
     }
     return { status: response.httpStatusCode, body: text };
@@ -365,15 +407,17 @@ export async function createK8sClient(options: K8sClientOptions = {}): Promise<K
   ): Promise<T> {
     const { status, body } = await send(path, method, opts);
     if (status < 200 || status > 299) {
-      throw K8sApiError.fromResponse(status, body, opts.target);
+      throw noted(K8sApiError.fromResponse(status, body, opts.target));
     }
     try {
       return JSON.parse(body) as T;
     } catch (err) {
-      throw new K8sTransportError(
-        `the API server returned HTTP ${status} with a body that is not JSON`,
-        opts.target ?? `${method} ${path}`,
-        { cause: err },
+      throw noted(
+        new K8sTransportError(
+          `the API server returned HTTP ${status} with a body that is not JSON`,
+          opts.target ?? `${method} ${path}`,
+          { cause: err },
+        ),
       );
     }
   }
@@ -399,15 +443,13 @@ export async function createK8sClient(options: K8sClientOptions = {}): Promise<K
     return pending;
   }
 
-  async function servedGroupVersions(signal?: AbortSignal): Promise<string[]> {
-    if (groupVersionsCache) return groupVersionsCache;
-    groupVersionsCache = (async () => {
-      const out: string[] = [];
+  async function rootDiscovery(signal?: AbortSignal): Promise<RootDiscovery> {
+    if (rootDiscoveryCache) return rootDiscoveryCache;
+    rootDiscoveryCache = (async (): Promise<RootDiscovery> => {
       const core = await sendJson<{ versions?: string[] }>("/api", "GET", {
         signal,
         target: "discovery /api",
       });
-      out.push(...(core.versions ?? ["v1"]));
       const groups = await sendJson<{
         groups?: Array<{
           name?: string;
@@ -415,19 +457,43 @@ export async function createK8sClient(options: K8sClientOptions = {}): Promise<K
           versions?: Array<{ groupVersion?: string }>;
         }>;
       }>("/apis", "GET", { signal, target: "discovery /apis" });
-      for (const group of groups.groups ?? []) {
-        const preferred = group.preferredVersion?.groupVersion;
-        if (preferred) out.push(preferred);
-        for (const v of group.versions ?? []) {
-          if (v.groupVersion && v.groupVersion !== preferred) out.push(v.groupVersion);
-        }
-      }
-      return [...new Set(out)];
+      return {
+        coreVersions: core.versions ?? ["v1"],
+        groups: (groups.groups ?? []).map((group) => ({
+          preferred: group.preferredVersion?.groupVersion,
+          versions: (group.versions ?? [])
+            .map((v) => v.groupVersion)
+            .filter((gv): gv is string => typeof gv === "string" && gv.length > 0),
+        })),
+      };
     })().catch((err: unknown) => {
-      groupVersionsCache = undefined;
+      rootDiscoveryCache = undefined;
       throw err;
     });
-    return groupVersionsCache;
+    return rootDiscoveryCache;
+  }
+
+  async function servedGroupVersions(signal?: AbortSignal): Promise<string[]> {
+    const root = await rootDiscovery(signal);
+    const out: string[] = [...root.coreVersions];
+    for (const group of root.groups) {
+      if (group.preferred) out.push(group.preferred);
+      for (const gv of group.versions) {
+        if (gv !== group.preferred) out.push(gv);
+      }
+    }
+    return [...new Set(out)];
+  }
+
+  async function preferredGroupVersions(signal?: AbortSignal): Promise<string[]> {
+    const root = await rootDiscovery(signal);
+    const core = root.coreVersions.includes("v1") ? "v1" : root.coreVersions[0];
+    const out: string[] = core ? [core] : [];
+    for (const group of root.groups) {
+      const gv = group.preferred ?? group.versions[0];
+      if (gv) out.push(gv);
+    }
+    return [...new Set(out)];
   }
 
   function toInfo(apiVersion: string, entry: NonNullable<ApiResourceListResponse["resources"]>[number]): ApiResourceInfo {
@@ -518,6 +584,12 @@ export async function createK8sClient(options: K8sClientOptions = {}): Promise<K
     return parts.join("/");
   }
 
+  async function pathFor(ref: ObjectRef, signal?: AbortSignal): Promise<string | undefined> {
+    const info = await resolve({ apiVersion: ref.apiVersion, kind: ref.kind }, signal);
+    if (!info) return undefined;
+    return objectPath(info, ref.name, ref.namespace);
+  }
+
   async function read(ref: ObjectRef, opts: ReadOptions = {}): Promise<K8sObject> {
     const info = await resolveOrThrow({ apiVersion: ref.apiVersion, kind: ref.kind }, opts.signal);
     return sendJson<K8sObject>(objectPath(info, ref.name, ref.namespace), "GET", {
@@ -618,7 +690,7 @@ export async function createK8sClient(options: K8sClientOptions = {}): Promise<K
       target,
     });
     if (status < 200 || status > 299) {
-      throw K8sApiError.fromResponse(status, body, target);
+      throw noted(K8sApiError.fromResponse(status, body, target));
     }
     return body;
   }
@@ -648,6 +720,7 @@ export async function createK8sClient(options: K8sClientOptions = {}): Promise<K
     defaultNamespace,
     resolve,
     read,
+    pathFor,
     readIfPresent,
     list,
     readLog,
@@ -655,6 +728,7 @@ export async function createK8sClient(options: K8sClientOptions = {}): Promise<K
     delete: remove,
     concurrently: (items, fn) => mapConcurrent(items, fn, concurrency),
     resources: resourcesOf,
+    preferredGroupVersions,
     discoveryCacheKeys: () => [...discoveryCache.keys()].sort(),
   };
 }

package/src/errors.ts

@@ -26,6 +26,15 @@ export interface K8sStatus {
  * `reason` come from the response, not from parsing text.
  */
 export class K8sApiError extends Error {
+  /**
+   * Which cluster the failing read actually talked to, e.g.
+   * `context "k3d-fountain-local" (bound by k8s.profiles.local.context)`.
+   * Stamped by the client that issued the request (chant #1488) — a
+   * `read-failed` that does not name the cluster it read cost an afternoon on
+   * a laptop with two k3d clusters, so the failure carries it from birth.
+   */
+  contextNote?: string;
+
   constructor(
     public readonly statusCode: number,
     public readonly reason: string | undefined,
@@ -90,6 +99,9 @@ export class K8sApiError extends Error {
  * connect" and "the server said no" are different observations.
  */
 export class K8sTransportError extends Error {
+  /** Which cluster context the failed request was aimed at — see {@link K8sApiError.contextNote}. */
+  contextNote?: string;
+
   constructor(
     message: string,
     public readonly target?: string,

package/src/types.ts

@@ -125,6 +125,15 @@ export interface K8sClientOptions {
   concurrency?: number;
   /** Where the context came from, for provenance. Default `ambient`. */
   contextSource?: "bound" | "ambient";
+  /**
+   * How the context was selected, in words — e.g.
+   * `bound by k8s.profiles.prod.context` or
+   * `ambient; no k8s.profiles.local binding`. Stamped (with the resolved
+   * context name) onto every API/transport failure the client throws, so a
+   * `read-failed` reason names the cluster it read (chant #1488). Defaults to
+   * the bare `contextSource`.
+   */
+  contextLabel?: string;
 }
 
 /**