@intentius/chant-lexicon-k8s 0.30.0 → 0.32.0

package/dist/spec/parse.d.ts

@@ -41,6 +41,25 @@ export interface GroupVersionKind {
     version: string;
     kind: string;
 }
+/**
+ * How this resource is addressed over the API — chant #1074.
+ *
+ * Read out of the same document the resource's types come from (the OpenAPI
+ * `paths` for core kinds, the CRD's `spec.names` / `spec.scope` for custom
+ * ones), so the operation surface and the declarable surface cannot drift
+ * apart the way a hand-maintained `kind → kubectl resource` table did.
+ *
+ * It is a starting point, not the authority: the live client confirms plural
+ * and scope against the cluster's own discovery, which is the only thing that
+ * knows what a given cluster actually serves.
+ */
+export interface ParsedOperation {
+    /** Plural path segment, e.g. `deployments`. */
+    plural: string;
+    scope: "Namespaced" | "Cluster";
+    /** Verbs the schema documents for the named resource, e.g. `get`, `patch`. */
+    verbs: string[];
+}
 export interface K8sParseResult {
     resource: ParsedResource;
     propertyTypes: ParsedPropertyType[];
@@ -48,12 +67,35 @@ export interface K8sParseResult {
     gvk: GroupVersionKind;
     /** Whether this entity is a property type (nested inside resources) */
     isProperty?: boolean;
+    /** How the API addresses this resource. Absent for property types. */
+    operation?: ParsedOperation;
 }
+interface SwaggerOperation {
+    "x-kubernetes-group-version-kind"?: GroupVersionKind;
+    "x-kubernetes-action"?: string;
+}
+type SwaggerPathItem = Record<string, SwaggerOperation | unknown>;
 /**
  * Parse the Kubernetes OpenAPI swagger.json into multiple resource results.
  * Returns one result per top-level resource identified by x-kubernetes-group-version-kind.
  */
 export declare function parseK8sSwagger(data: string | Buffer): K8sParseResult[];
+/** Stable key for a GVK, used to join the `paths` pass onto the `definitions` pass. */
+export declare function gvkKey(gvk: GroupVersionKind): string;
+/**
+ * Derive the operation surface from the OpenAPI `paths` — chant #1074.
+ *
+ * Every Kubernetes operation carries `x-kubernetes-group-version-kind` and
+ * `x-kubernetes-action`, and the path itself carries the two facts a REST call
+ * needs and a definition does not have: the plural segment, and whether the
+ * resource is namespaced (`/namespaces/{namespace}/` appears in its path).
+ *
+ * Only paths addressing a single named object (`.../{plural}/{name}`) are read,
+ * so subresource paths (`.../{name}/status`, `.../{name}/scale`) and collection
+ * paths do not supply the plural — but their verbs are collected, because
+ * "this kind can be listed" is worth knowing.
+ */
+export declare function parseOperations(paths: Record<string, SwaggerPathItem> | undefined): Map<string, ParsedOperation>;
 /**
  * Convert GVK to our type name convention: K8s::{Group}::{Kind}
  */

package/dist/spec/parse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/spec/parse.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAShF,YAAY,EAAE,mBAAmB,EAAE,CAAC;AAEpC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,mBAAmB,CAAC;CAClC;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,cAAc,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,cAAc,CAAC;IACzB,aAAa,EAAE,kBAAkB,EAAE,CAAC;IACpC,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,GAAG,EAAE,gBAAgB,CAAC;IACtB,uEAAuE;IACvE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AA8FD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,cAAc,EAAE,CA+BvE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAG3D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAK7D;AA6PD;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGvD"}
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/spec/parse.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAShF,YAAY,EAAE,mBAAmB,EAAE,CAAC;AAEpC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,mBAAmB,CAAC;CAClC;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,cAAc,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,YAAY,GAAG,SAAS,CAAC;IAChC,8EAA8E;IAC9E,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,cAAc,CAAC;IACzB,aAAa,EAAE,kBAAkB,EAAE,CAAC;IACpC,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,GAAG,EAAE,gBAAgB,CAAC;IACtB,uEAAuE;IACvE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,sEAAsE;IACtE,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAkCD,UAAU,gBAAgB;IACxB,iCAAiC,CAAC,EAAE,gBAAgB,CAAC;IACrD,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,KAAK,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,CAAC;AA+DlE;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,cAAc,EAAE,CAoCvE;AAED,uFAAuF;AACvF,wBAAgB,MAAM,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAEpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,SAAS,GAAG,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAqChH;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAG3D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAK7D;AA6PD;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGvD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-k8s",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "Kubernetes lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -70,12 +70,15 @@
     "js-yaml": "^4.1.1",
     "@types/js-yaml": "^4.0.9"
   },
+  "optionalDependencies": {
+    "@intentius/chant-k8s-client": "^0.32.0"
+  },
   "devDependencies": {
     "@intentius/chant": "*",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.30.0",
+    "@intentius/chant": "^0.32.0",
     "typescript": "^5.9.3"
   }
 }

package/src/api/classify.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Typed failure → observation tri-state (chant #1074 over #1089).
+ *
+ * The point of the move is that these verdicts are read off `code` and
+ * `reason` rather than matched against English. The cases below are the same
+ * ones `classifyKubectlFailure` covers in core, driven by the client's real
+ * error objects, so the contract can be compared side by side.
+ */
+
+import { describe, test, expect } from "vitest";
+import {
+  ExecCredentialNotAllowedError,
+  K8sApiError,
+  K8sClientUnavailableError,
+  K8sTransportError,
+  KubeConfigError,
+  UnknownResourceError,
+} from "@intentius/chant-k8s-client";
+import { classifyApiFailure, isMissingClientPackage, isWholeLexiconFailure, MISSING_CLIENT_DETAIL } from "./classify";
+
+const status = (code: number, reason: string) => new K8sApiError(code, reason, "message", "apps/v1 Deployment prod/web");
+
+describe("classifyApiFailure", () => {
+  test("a NotFound is an absence — the only shape that may become a create", () => {
+    expect(classifyApiFailure(status(404, "NotFound"))).toEqual({ kind: "absent" });
+  });
+
+  test("a kind the cluster does not serve is an absence too — no instance of it can exist", () => {
+    // The rule core already had for `the server doesn't have a resource type`,
+    // and the reason it had it: the usual cause is a CRD this very plan has not
+    // applied yet, and calling it a hole would suppress the needed create.
+    expect(classifyApiFailure(new UnknownResourceError("widgets.example.com/v1 Widget"))).toEqual({ kind: "absent" });
+  });
+
+  test.each([
+    [401, "Unauthorized"],
+    [403, "Forbidden"],
+  ])("HTTP %i proves nothing about existence → no-credentials", (code, reason) => {
+    expect(classifyApiFailure(status(code, reason))).toMatchObject({ kind: "unobserved", reason: "no-credentials" });
+  });
+
+  test.each([
+    [409, "Conflict"],
+    [429, "TooManyRequests"],
+    [500, "InternalError"],
+    [503, "ServiceUnavailable"],
+  ])("HTTP %i → read-failed", (code, reason) => {
+    expect(classifyApiFailure(status(code, reason))).toMatchObject({ kind: "unobserved", reason: "read-failed" });
+  });
+
+  test("a transport failure is no-binding — the same verdict kubectl's 'unable to connect' produced", () => {
+    const err = new K8sTransportError("connect ECONNREFUSED 127.0.0.1:6443", "apps/v1 Deployment prod/web");
+    expect(classifyApiFailure(err)).toMatchObject({ kind: "unobserved", reason: "no-binding" });
+  });
+
+  test("an unusable kubeconfig is no-binding", () => {
+    expect(classifyApiFailure(new KubeConfigError("no context named prod-eks"))).toMatchObject({
+      kind: "unobserved",
+      reason: "no-binding",
+    });
+  });
+
+  test("a refused credential plugin is no-credentials", () => {
+    expect(classifyApiFailure(new ExecCredentialNotAllowedError("harvest", ["aws"]))).toMatchObject({
+      kind: "unobserved",
+      reason: "no-credentials",
+    });
+  });
+
+  test("a missing client package is read-failed, never an absence", () => {
+    expect(classifyApiFailure(new K8sClientUnavailableError())).toMatchObject({
+      kind: "unobserved",
+      reason: "read-failed",
+    });
+  });
+
+  test("anything unrecognized is read-failed rather than assumed absent", () => {
+    expect(classifyApiFailure(new Error("something else entirely"))).toMatchObject({
+      kind: "unobserved",
+      reason: "read-failed",
+    });
+    expect(classifyApiFailure("a string")).toMatchObject({ kind: "unobserved", reason: "read-failed" });
+    expect(classifyApiFailure(undefined)).toMatchObject({ kind: "unobserved", reason: "read-failed" });
+  });
+
+  test("the detail is one line, capped", () => {
+    const long = new K8sApiError(500, "InternalError", "x".repeat(500));
+    const outcome = classifyApiFailure(long);
+    expect(outcome.kind).toBe("unobserved");
+    if (outcome.kind === "unobserved") {
+      expect(outcome.detail.length).toBeLessThanOrEqual(200);
+      expect(outcome.detail).not.toContain("\n");
+    }
+  });
+
+  test("classification survives a duplicated copy of the client package", () => {
+    // Discrimination is by `name`, not `instanceof`, so an error from a second
+    // physical copy of the package in a consumer's tree still classifies.
+    const foreign = Object.assign(new Error("not found"), { name: "K8sApiError", statusCode: 404, reason: "NotFound" });
+    expect(classifyApiFailure(foreign)).toEqual({ kind: "absent" });
+  });
+});
+
+describe("whole-lexicon failures", () => {
+  test.each([
+    [new KubeConfigError("no cluster"), true],
+    [new ExecCredentialNotAllowedError("harvest", ["aws"]), true],
+    [new K8sClientUnavailableError(), true],
+    [status(404, "NotFound"), false],
+    [new K8sTransportError("refused"), false],
+  ])("%s", (err, expected) => {
+    expect(isWholeLexiconFailure(err)).toBe(expected);
+  });
+});
+
+describe("missing client package detection", () => {
+  test("a module-resolution failure naming either package is recognized", () => {
+    for (const spec of ["@intentius/chant-k8s-client", "@kubernetes/client-node"]) {
+      const err = Object.assign(new Error(`Cannot find package '${spec}'`), { code: "ERR_MODULE_NOT_FOUND" });
+      expect(isMissingClientPackage(err)).toBe(true);
+    }
+  });
+
+  test("an unrelated module error is not", () => {
+    const err = Object.assign(new Error("Cannot find package 'left-pad'"), { code: "ERR_MODULE_NOT_FOUND" });
+    expect(isMissingClientPackage(err)).toBe(false);
+    expect(isMissingClientPackage(new Error("nope"))).toBe(false);
+  });
+
+  test("the detail names the install command", () => {
+    expect(MISSING_CLIENT_DETAIL).toContain("npm i @intentius/chant-k8s-client");
+  });
+});

package/src/api/classify.ts

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

package/src/api/connect.ts

@@ -0,0 +1,104 @@
+/**
+ * Getting from a chant environment to a live API client — chant #1074.
+ *
+ * The cluster binding (chant #1100, landed in #1155) is unchanged by the move
+ * off `kubectl`, and deliberately so: `resolveClusterTarget` in core stays the
+ * single resolver, shared with the GCP lexicon's Config Connector observation,
+ * and the refusal it throws on a bound-but-mismatched context still aborts
+ * before any resource is touched. What changes is only *how the ambient
+ * context is read*: the typed client parses the kubeconfig it is about to use
+ * rather than shelling `kubectl config current-context`, so a worker image with
+ * no `kubectl` in it can still check the binding. Same question, same three
+ * outcomes:
+ *
+ * - **Bound and ambient agrees** — the bound context is passed explicitly to
+ *   the client, never left to the ambient default.
+ * - **Bound and ambient disagrees** — `ClusterBindingMismatchError`, thrown
+ *   before the first request. Core turns the throw into NOT-OBSERVED for every
+ *   declared entity (chant #1089), which is what stops a wrong-cluster read
+ *   becoming a confident list of creates.
+ * - **Unbound** — the kubeconfig's own current-context, with the same visible
+ *   warning naming the environment and the missing binding.
+ */
+
+import { loadChantConfig } from "@intentius/chant/config";
+import { resolveClusterTarget, type ResolvedClusterTarget } from "@intentius/chant/kubectl-context";
+import type { K8sClient, K8sClientOptions } from "@intentius/chant-k8s-client";
+import type { K8sChantConfig } from "../config";
+
+/**
+ * Build a client for an environment. Injectable so tests drive the real client
+ * against a fake request layer, and so `describeResources` and the Op
+ * activities share one connection story rather than each inventing one.
+ */
+export type K8sConnector = (options: ConnectOptions) => Promise<ConnectedClient>;
+
+export interface ConnectOptions {
+  /**
+   * chant environment being observed or applied to. Omitting it skips the
+   * config lookup and the binding check — which is what an Op activity called
+   * with no environment and no explicit context has always done: use whatever
+   * the kubeconfig selects.
+   */
+  environment?: string;
+  /** Directory whose `chant.config.ts` carries `k8s.profiles`. Defaults to cwd. */
+  cwd?: string;
+  /**
+   * An explicit context, for the Op write path whose activity contract has
+   * always taken one. Skips the config lookup and the binding check entirely.
+   */
+  context?: string;
+  /** Extra client options — the request-layer seam, concurrency. */
+  client?: Partial<K8sClientOptions>;
+}
+
+export interface ConnectedClient {
+  client: K8sClient;
+  target: ResolvedClusterTarget;
+}
+
+/**
+ * The production connector: read the project's config, resolve the binding,
+ * build a client honoring it.
+ */
+export const defaultK8sConnector: K8sConnector = async (options) => {
+  const { createK8sClient, readAmbientContext } = await import("@intentius/chant-k8s-client");
+
+  if (options.context !== undefined) {
+    const client = await createK8sClient({
+      context: options.context,
+      contextSource: "bound",
+      ...options.client,
+    });
+    return { client, target: { context: options.context, source: "bound" } };
+  }
+
+  if (options.environment === undefined) {
+    const client = await createK8sClient({ contextSource: "ambient", ...options.client });
+    return { client, target: { source: "ambient" } };
+  }
+
+  const { config } = await loadChantConfig(options.cwd ?? process.cwd());
+  const k8sConfig = (config as { k8s?: K8sChantConfig }).k8s;
+  const execAllowlist = k8sConfig?.execCredentialPlugins;
+
+  // The binding check reads the kubeconfig's current-context directly. Only a
+  // context name is needed, and requiring a *usable* ambient cluster to check a
+  // binding would defeat the binding: pointing an environment at a specific
+  // context is how you recover from an ambient one that is wrong or broken.
+  const target = await resolveClusterTarget(config as Record<string, unknown>, options.environment, "k8s", {
+    ambientContext: () =>
+      readAmbientContext({
+        kubeconfig: options.client?.kubeconfig,
+        kubeconfigPath: options.client?.kubeconfigPath,
+      }),
+  });
+
+  const client = await createK8sClient({
+    ...options.client,
+    ...(target.context ? { context: target.context } : {}),
+    contextSource: target.source,
+    ...(execAllowlist ? { execAllowlist } : {}),
+  });
+  return { client, target };
+};