@intentius/chant-lexicon-k8s 0.27.0 → 0.29.0

package/dist/config.d.ts

@@ -0,0 +1,62 @@
+/**
+ * K8s environment → cluster binding — chant #1100.
+ *
+ * Every cloud lexicon binds an environment to a scope: AWS resolves `<env>`
+ * to a CloudFormation stack, Azure treats `<env>` as the resource group,
+ * Temporal looks up `temporal.profiles.<env>`. Before this, k8s bound
+ * nothing — `describeResources` shelled out to `kubectl get` with no
+ * `--context`, so `chant lifecycle diff prod --live` read whichever cluster
+ * `kubectl config current-context` happened to point at.
+ *
+ * Add this to `chant.config.ts` to pin an environment to a cluster:
+ *
+ * ```ts
+ * import type { K8sChantConfig } from "@intentius/chant-lexicon-k8s";
+ *
+ * export default {
+ *   lexicons: ["k8s"],
+ *   k8s: {
+ *     profiles: {
+ *       prod: { context: "prod-eks" },
+ *       staging: { context: "staging-eks" },
+ *     },
+ *   } satisfies K8sChantConfig,
+ * };
+ * ```
+ *
+ * `describeResources` (in `./describe-resources.ts`, and the GCP lexicon's
+ * Config Connector equivalent, which observes through the same kubectl path)
+ * resolves this via `@intentius/chant/kubectl-context`'s
+ * `resolveClusterTarget`:
+ *
+ * - A declared binding is passed explicitly as `kubectl ... --context <bound>`
+ *   on every invocation, and checked against the ambient context first — a
+ *   mismatch refuses loudly (naming the environment, the expected context,
+ *   and the ambient one) instead of silently reading the wrong cluster.
+ * - No binding for the environment keeps today's behavior — the ambient
+ *   context — but logs a visible note that nothing is pinned, so the
+ *   fallback is never silent.
+ *
+ * `ChantConfig` uses `.passthrough()` in its Zod schema so the `k8s` key is
+ * accepted at runtime without core changes, exactly like `temporal.profiles`
+ * (see `lexicons/temporal/src/config.ts`).
+ *
+ * Deliberately out of scope here (see the issue for the full proposal):
+ * deriving the binding automatically from a declared `AWS::EKS::Cluster` /
+ * AKS / GKE cluster resource, and threading the resolved context into the
+ * Op write path (`op/activities/kubectl.ts`, `wait-for-ready.ts`) — both
+ * already accept an optional `context` a workflow author can pass, and can
+ * call `resolveClusterTarget` themselves to agree with what the read path
+ * resolved. This also keeps the binding available for #1073/#1074's future
+ * typed API client to inherit, rather than re-deriving it.
+ */
+/** A single environment's cluster binding. */
+export interface K8sClusterProfile {
+    /** kubectl context name this environment is bound to. */
+    context: string;
+}
+export interface K8sChantConfig {
+    /** Named environment → cluster bindings, keyed by environment name. */
+    profiles?: Record<string, K8sClusterProfile>;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC9C"}

package/dist/describe-resources.d.ts

@@ -7,11 +7,24 @@
  * name (using the props.metadata.name + props.metadata.namespace from #39's
  * entity-prop pass-through).
  *
- * Resource-not-found is silent — `state diff --live` then reports it as
- * missing (declared, not in cloud). Unknown entity types are warn-skipped;
- * extending the KUBECTL_RESOURCE map covers more.
+ * The observation tri-state (#1089) is what the return value carries. A genuine
+ * `NotFound` from the API server is an absence, and only that becomes a `create`
+ * downstream. An entity type with no entry in `KUBECTL_RESOURCE` — every CRD —
+ * was never looked at, and comes back `unsupported-kind`: it may well be running
+ * in the cluster, and proposing to create it would be a guess. Auth failures and
+ * unreachable API servers come back `no-credentials` / `no-binding` for the same
+ * reason. Extending the KUBECTL_RESOURCE map converts unsupported-kind holes into
+ * real reads; until then they are holes chant admits to.
+ *
+ * Before touching any resource, the environment is resolved to a cluster
+ * identity (chant #1100) via `resolveClusterTarget` — see `./config.ts` for
+ * the `k8s.profiles.<env>.context` binding shape. A declared binding is
+ * passed explicitly as `--context` on every kubectl call below; an ambient
+ * context that disagrees with it aborts the whole describe with a loud
+ * error rather than silently reading the wrong cluster. No binding keeps
+ * today's behavior (ambient context), with a visible warning.
  */
-import type { ResourceMetadata } from "@intentius/chant/lexicon";
+import type { ObservationResult } from "@intentius/chant/lexicon";
 /**
  * Map chant entity types to `kubectl get` resource names. Add entries here
  * as new types are needed.
@@ -26,5 +39,5 @@ export declare function describeResources(options: {
         props: Record<string, unknown>;
     }>;
     owned?: boolean;
-}): Promise<Record<string, ResourceMetadata>>;
+}): Promise<ObservationResult>;
 //# sourceMappingURL=describe-resources.d.ts.map

package/dist/describe-resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAKjE;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAoBnD,CAAC;AAsCF,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAmD5C"}
+{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAsC,MAAM,0BAA0B,CAAC;AAQtG;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAoBnD,CAAC;AAsCF,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAyF7B"}

package/dist/index.d.ts

@@ -17,4 +17,5 @@ export type { PackageOptions, PackageResult } from "./codegen/package.js";
 export type { CRDSource, CRDSpec } from "./crd/types.js";
 export { parseCRD, parseCRDSpec } from "./crd/parser.js";
 export { loadCRDs, loadMultipleCRDs } from "./crd/loader.js";
+export type { K8sChantConfig, K8sClusterProfile } from "./config.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "8a7018cadb51107c42bba4cc99824ae8c0cbf77ffa904361ce90ef9cadc7cc38",
+    "manifest.json": "bea5120e32340b17c1c92685893306ca70028b56c4a2bf79da7ad99917a99b4f",
     "meta.json": "6d112006daa7196eb28619ac5a3893b709dc2b845edbd537db7d7b471e8dc104",
     "types/index.d.ts": "7b873148146a5512c22baabfde6cfcc3248c24c2c7578f68a19544af5dc675f6",
     "rules/argo-appset-single-project.ts": "afa9f310753aa2d475f35012b13135b2dfaebed2a35d44edbe185ebc07673674",
@@ -45,10 +45,10 @@
     "skills/chant-k8s-patterns.md": "683148e9f0f9da6879bd65d97c82cc29dbff897e31bc11b3c1de654cd6baeea3",
     "skills/chant-k8s-deployment-strategies.md": "c4cc93cba064230567baa755b5a3493dc69bfc6e74a62e1990d12039ffaaf5f8",
     "skills/chant-k8s-security.md": "f4250284000fde0d380192ba4cd73f2190471da2142e3bf77d848881552807f7",
-    "skills/chant-k8s-eks.md": "c391217039b35d1c9d88214e2cb7b8c1166331d6ab26996f5f7d907027508ab9",
+    "skills/chant-k8s-eks.md": "9e953d6a2c39518c4b797a2bf54ff5b4a33530503e5b6d66e35921e8f952432f",
     "skills/chant-k8s-gke.md": "8938840bf9ef5ed58d6333fdd773b3dd54ecaf25a9df35e58f7f5c3355d4928f",
     "skills/chant-k8s-aks.md": "e18f0e2b055f72cd7a37deaf258d7027c2d4d3e286e8fd4975b27a1f981a3ad9",
     "skills/chant-k8s-argo.md": "b1a0b826559d8c5033a479c5781efaf650320f0aee4419d8841170bd3393cea5"
   },
-  "composite": "9ed36c6a5b40d86a9d06183827b6efdcf082deff14a890cc0f1281ce0d464d84"
+  "composite": "52fb1f56f334cf400a0544278a42f1d85d52aa9f49f55b4d845b9844e2e42aa4"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "k8s",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "chantVersion": ">=0.1.0",
   "namespace": "K8s",
   "intrinsics": [],

package/dist/op/activities/index.d.ts

@@ -19,4 +19,6 @@ export { waitForArgoSync, defaultArgoStatusFetcher, ArgoSyncFailedError } from "
 export type { WaitForArgoSyncArgs, ArgoAppStatus, ArgoStatusFetcher } from "./argo.js";
 export { waitForReady, defaultResourceFetcher, ReadinessFailedError, readinessFor, isReady, firstTerminal, DEFAULT_READINESS, READINESS_OVERRIDES, } from "./wait-for-ready.js";
 export type { WaitForReadyArgs, ResourceFetcher, ReadinessSpec, ReadinessMatch, ConditionMatch, PathMatch, } from "./wait-for-ready.js";
+export { resolveClusterTarget, ClusterBindingMismatchError } from "@intentius/chant/kubectl-context";
+export type { ResolvedClusterTarget, K8sClusterProfile, K8sConfigShape } from "@intentius/chant/kubectl-context";
 //# sourceMappingURL=index.d.ts.map

package/dist/op/activities/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/op/activities/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AACvF,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAEpD,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AACxF,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAEpF,OAAO,EACL,YAAY,EACZ,sBAAsB,EACtB,oBAAoB,EACpB,YAAY,EACZ,OAAO,EACP,aAAa,EACb,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,cAAc,EACd,cAAc,EACd,SAAS,GACV,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/op/activities/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AACvF,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAEpD,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AACxF,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAEpF,OAAO,EACL,YAAY,EACZ,sBAAsB,EACtB,oBAAoB,EACpB,YAAY,EACZ,OAAO,EACP,aAAa,EACb,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,cAAc,EACd,cAAc,EACd,SAAS,GACV,MAAM,kBAAkB,CAAC;AAW1B,OAAO,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,MAAM,kCAAkC,CAAC;AACrG,YAAY,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC"}

package/dist/op/activities/kubectl.d.ts

@@ -1,6 +1,11 @@
 export interface KubectlApplyArgs {
     manifest: string;
-    /** kubectl context name. Uses current context if omitted. */
+    /**
+     * kubectl context name. Uses the ambient context if omitted. To target the
+     * same cluster the read path (`describeResources`) resolved for an
+     * environment — chant #1100 — resolve it with `resolveClusterTarget` from
+     * `./index.ts` and pass `.context` through.
+     */
     context?: string;
 }
 /**

package/dist/op/activities/kubectl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kubectl.d.ts","sourceRoot":"","sources":["../../../src/op/activities/kubectl.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB9F"}
+{"version":3,"file":"kubectl.d.ts","sourceRoot":"","sources":["../../../src/op/activities/kubectl.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB9F"}

package/dist/op/activities/wait-for-ready.d.ts

@@ -65,7 +65,12 @@ export interface WaitForReadyArgs {
     name: string;
     /** Namespace (omit for cluster-scoped). */
     namespace?: string;
-    /** kubectl context. */
+    /**
+     * kubectl context. To target the same cluster the read path
+     * (`describeResources`) resolved for an environment — chant #1100 —
+     * resolve it with `resolveClusterTarget` from `./index.ts` and pass
+     * `.context` through.
+     */
     context?: string;
     /** API group, used to pick a readiness override when `spec` is not given. */
     group?: string;

package/dist/op/activities/wait-for-ready.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wait-for-ready.d.ts","sourceRoot":"","sources":["../../../src/op/activities/wait-for-ready.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;GAUG;AAIH,sEAAsE;AACtE,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,2DAA2D;AAC3D,MAAM,WAAW,SAAS;IACxB,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACnC,4CAA4C;IAC5C,KAAK,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;CAEhC;AAED,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG,SAAS,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAC;IAC5B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,aAG/B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAS7D,CAAC;AAEF,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAEnF;AAwCD,qFAAqF;AACrF,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAGlE;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,GAAG,cAAc,GAAG,SAAS,CAE3F;AAID,6EAA6E;AAC7E,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,gGAAgG;IAChG,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uBAAuB;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,mEAAmE;AACnE,MAAM,MAAM,eAAe,GAAG,CAC5B,IAAI,EAAE,gBAAgB,EACtB,MAAM,CAAC,EAAE,WAAW,KACjB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAUtC,eAAO,MAAM,sBAAsB,EAAE,eAAiE,CAAC;AAEvG;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,gBAAgB,EACtB,MAAM,CAAC,EAAE,WAAW,EACpB,OAAO,GAAE,eAAwC,GAChD,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAuBlC"}
+{"version":3,"file":"wait-for-ready.d.ts","sourceRoot":"","sources":["../../../src/op/activities/wait-for-ready.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;GAUG;AAIH,sEAAsE;AACtE,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,2DAA2D;AAC3D,MAAM,WAAW,SAAS;IACxB,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACnC,4CAA4C;IAC5C,KAAK,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;CAEhC;AAED,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG,SAAS,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAC;IAC5B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,aAG/B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAS7D,CAAC;AAEF,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAEnF;AAwCD,qFAAqF;AACrF,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAGlE;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,GAAG,cAAc,GAAG,SAAS,CAE3F;AAID,6EAA6E;AAC7E,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,gGAAgG;IAChG,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,mEAAmE;AACnE,MAAM,MAAM,eAAe,GAAG,CAC5B,IAAI,EAAE,gBAAgB,EACtB,MAAM,CAAC,EAAE,WAAW,KACjB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAUtC,eAAO,MAAM,sBAAsB,EAAE,eAAiE,CAAC;AAEvG;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,gBAAgB,EACtB,MAAM,CAAC,EAAE,WAAW,EACpB,OAAO,GAAE,eAAwC,GAChD,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAuBlC"}

package/dist/skills/chant-k8s-eks.md

@@ -127,13 +127,28 @@ For Pod Identity, no K8s-side composite is needed — configure the association
 
 ## Karpenter
 
-Karpenter replaces Cluster Autoscaler for node provisioning. Karpenter NodePool and EC2NodeClass are simple CRDs — use CRD import rather than composites:
+Karpenter replaces Cluster Autoscaler for node provisioning. Karpenter's `NodePool` and `EC2NodeClass` are simple CRDs — add them to the k8s lexicon's CRD source list rather than importing per-project. There is no `chant import --url` flag; CRD-from-URL is lexicon-authoring-time codegen, done once in `lexicons/k8s/src/crd/crd-sources.ts`, not a per-project command:
+
+```typescript
+// lexicons/k8s/src/crd/crd-sources.ts
+const KARPENTER_VERSION = "v1.0.0"; // pin an operator release, not `main`
+const KARPENTER_CRD_BASE = `https://raw.githubusercontent.com/aws/karpenter-provider-aws/${KARPENTER_VERSION}/pkg/apis/crds`;
+
+export const CRD_SOURCES: CRDSource[] = [
+  // ...existing sources
+  { type: "url", url: `${KARPENTER_CRD_BASE}/karpenter.sh_nodepools.yaml` },
+  { type: "url", url: `${KARPENTER_CRD_BASE}/karpenter.k8s.aws_ec2nodeclasses.yaml` },
+];
+```
+
+Then regenerate the lexicon so the new kinds are typed:
 
 ```bash
-# Import Karpenter CRDs into your chant project
-chant import --url https://raw.githubusercontent.com/aws/karpenter/main/pkg/apis/crds/karpenter.sh_nodepools.yaml
+npm run generate -w @intentius/chant-lexicon-k8s
 ```
 
+See [Add a Third-Party CRD](/chant/lexicon-authoring/crd-sources/) for the full workflow (namespace mapping, verifying the generated type, adding rules).
+
 ## Fargate Considerations
 
 When running on EKS Fargate:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-k8s",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Kubernetes lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -75,7 +75,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.27.0",
+    "@intentius/chant": "^0.29.0",
     "typescript": "^5.9.3"
   }
 }

package/src/config.ts

@@ -0,0 +1,63 @@
+/**
+ * K8s environment → cluster binding — chant #1100.
+ *
+ * Every cloud lexicon binds an environment to a scope: AWS resolves `<env>`
+ * to a CloudFormation stack, Azure treats `<env>` as the resource group,
+ * Temporal looks up `temporal.profiles.<env>`. Before this, k8s bound
+ * nothing — `describeResources` shelled out to `kubectl get` with no
+ * `--context`, so `chant lifecycle diff prod --live` read whichever cluster
+ * `kubectl config current-context` happened to point at.
+ *
+ * Add this to `chant.config.ts` to pin an environment to a cluster:
+ *
+ * ```ts
+ * import type { K8sChantConfig } from "@intentius/chant-lexicon-k8s";
+ *
+ * export default {
+ *   lexicons: ["k8s"],
+ *   k8s: {
+ *     profiles: {
+ *       prod: { context: "prod-eks" },
+ *       staging: { context: "staging-eks" },
+ *     },
+ *   } satisfies K8sChantConfig,
+ * };
+ * ```
+ *
+ * `describeResources` (in `./describe-resources.ts`, and the GCP lexicon's
+ * Config Connector equivalent, which observes through the same kubectl path)
+ * resolves this via `@intentius/chant/kubectl-context`'s
+ * `resolveClusterTarget`:
+ *
+ * - A declared binding is passed explicitly as `kubectl ... --context <bound>`
+ *   on every invocation, and checked against the ambient context first — a
+ *   mismatch refuses loudly (naming the environment, the expected context,
+ *   and the ambient one) instead of silently reading the wrong cluster.
+ * - No binding for the environment keeps today's behavior — the ambient
+ *   context — but logs a visible note that nothing is pinned, so the
+ *   fallback is never silent.
+ *
+ * `ChantConfig` uses `.passthrough()` in its Zod schema so the `k8s` key is
+ * accepted at runtime without core changes, exactly like `temporal.profiles`
+ * (see `lexicons/temporal/src/config.ts`).
+ *
+ * Deliberately out of scope here (see the issue for the full proposal):
+ * deriving the binding automatically from a declared `AWS::EKS::Cluster` /
+ * AKS / GKE cluster resource, and threading the resolved context into the
+ * Op write path (`op/activities/kubectl.ts`, `wait-for-ready.ts`) — both
+ * already accept an optional `context` a workflow author can pass, and can
+ * call `resolveClusterTarget` themselves to agree with what the read path
+ * resolved. This also keeps the binding available for #1073/#1074's future
+ * typed API client to inherit, rather than re-deriving it.
+ */
+
+/** A single environment's cluster binding. */
+export interface K8sClusterProfile {
+  /** kubectl context name this environment is bound to. */
+  context: string;
+}
+
+export interface K8sChantConfig {
+  /** Named environment → cluster bindings, keyed by environment name. */
+  profiles?: Record<string, K8sClusterProfile>;
+}

package/src/describe-resources.test.ts

@@ -11,6 +11,11 @@ vi.mock("node:child_process", async () => {
   } };
 });
 
+const loadChantConfigMock = vi.fn();
+vi.mock("@intentius/chant/config", () => ({
+  loadChantConfig: (...args: unknown[]) => loadChantConfigMock(...args),
+}));
+
 const { describeResources } = await import("./describe-resources");
 
 function makeEntities(records: Array<{ name: string; entityType: string; props: Record<string, unknown> }>) {
@@ -20,6 +25,10 @@ function makeEntities(records: Array<{ name: string; entityType: string; props:
 describe("k8s describeResources", () => {
   beforeEach(() => {
     execMock.mockReset();
+    loadChantConfigMock.mockReset();
+    // No binding declared by default — matches every test below except the
+    // dedicated cluster-binding tests, which override this per case.
+    loadChantConfigMock.mockResolvedValue({ config: {} });
   });
 
   test("queries kubectl for each declared K8s entity and maps response to ResourceMetadata", async () => {
@@ -51,13 +60,13 @@ describe("k8s describeResources", () => {
 
     const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["web", "webSvc"], entities });
 
-    expect(result["web"]).toMatchObject({
+    expect(result.resources["web"]).toMatchObject({
       type: "K8s::Apps::Deployment",
       physicalId: "uid-1",
       status: "READY",
       attributes: expect.objectContaining({ namespace: "prod", labels: { app: "web" } }),
     });
-    expect(result["webSvc"]).toMatchObject({
+    expect(result.resources["webSvc"]).toMatchObject({
       type: "K8s::Core::Service",
       physicalId: "uid-2",
       status: "PRESENT",
@@ -73,10 +82,12 @@ describe("k8s describeResources", () => {
 
     const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["missing"], entities });
 
-    expect(result).toEqual({});
+    // A real NotFound is an absence: neither present nor unobserved.
+    expect(result.resources).toEqual({});
+    expect(result.unobserved ?? {}).toEqual({});
   });
 
-  test("entity types without kubectl mapping are warn-skipped", async () => {
+  test("entity types without kubectl mapping are reported unobserved, not absent (#1089)", async () => {
     const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
     const entities = makeEntities([
       { name: "exotic", entityType: "K8s::Custom::CRD::SomeOperator", props: { metadata: { name: "x" } } },
@@ -84,12 +95,69 @@ describe("k8s describeResources", () => {
 
     const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["exotic"], entities });
 
-    expect(result).toEqual({});
-    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("kubectl mapping"));
-    expect(warnSpy.mock.calls[0][0]).toContain("K8s::Custom::CRD::SomeOperator");
+    expect(result.resources).toEqual({});
+    expect(result.unobserved?.exotic).toMatchObject({
+      type: "K8s::Custom::CRD::SomeOperator",
+      reason: "unsupported-kind",
+    });
+    expect(execMock).not.toHaveBeenCalled();
+    const mappingWarning = warnSpy.mock.calls.find((c) => String(c[0]).includes("kubectl mapping"));
+    expect(mappingWarning?.[0]).toContain("K8s::Custom::CRD::SomeOperator");
     warnSpy.mockRestore();
   });
 
+  // #1089 — a kubectl failure that is not a NotFound proves nothing about the
+  // object's existence, and must not reach the change set as an absence.
+  test.each([
+    ["error: You must be logged in to the server (Unauthorized)", "no-credentials"],
+    ["The connection to the server 127.0.0.1:6443 was refused - did you specify the right host or port?", "no-binding"],
+    ["error: unexpected EOF while parsing", "read-failed"],
+  ])("kubectl failure %j is reported unobserved (%s)", async (stderr, reason) => {
+    execMock.mockImplementation(() => { throw Object.assign(new Error("kubectl failed"), { stderr }); });
+    const entities = makeEntities([
+      { name: "web", entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web", namespace: "prod" } } },
+    ]);
+
+    const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["web"], entities });
+
+    expect(result.resources).toEqual({});
+    expect(result.unobserved?.web?.reason).toBe(reason);
+  });
+
+  test("a CRD kind the server does not serve is a real absence (nothing of that kind can exist)", async () => {
+    execMock.mockImplementation(() => {
+      throw Object.assign(new Error("kubectl failed"), {
+        stderr: 'error: the server doesn\'t have a resource type "widgets"',
+      });
+    });
+    const entities = makeEntities([
+      { name: "web", entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web", namespace: "prod" } } },
+    ]);
+
+    const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["web"], entities });
+
+    expect(result.resources).toEqual({});
+    expect(result.unobserved ?? {}).toEqual({});
+  });
+
+  test("--owned withholds an unmarked live object as `filtered`, never as absent (#1089)", async () => {
+    execMock.mockResolvedValue({
+      stdout: JSON.stringify({
+        metadata: { name: "web", namespace: "prod", uid: "uid-1", creationTimestamp: "t", labels: { app: "web" } },
+        status: { readyReplicas: 1, replicas: 1 },
+      }),
+      stderr: "",
+    });
+    const entities = makeEntities([
+      { name: "web", entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web", namespace: "prod" } } },
+    ]);
+
+    const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["web"], entities, owned: true });
+
+    expect(result.resources).toEqual({});
+    expect(result.unobserved?.web?.reason).toBe("filtered");
+  });
+
   test("Deployment with replicas != readyReplicas reports PROGRESSING", async () => {
     execMock.mockResolvedValue({
       stdout: JSON.stringify({
@@ -105,7 +173,7 @@ describe("k8s describeResources", () => {
 
     const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["web"], entities });
 
-    expect(result["web"].status).toBe("PROGRESSING(1/3)");
+    expect(result.resources["web"].status).toBe("PROGRESSING(1/3)");
   });
 
   test("Pod uses status.phase as the status", async () => {
@@ -123,7 +191,7 @@ describe("k8s describeResources", () => {
 
     const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["p"], entities });
 
-    expect(result["p"].status).toBe("Running");
+    expect(result.resources["p"].status).toBe("Running");
   });
 
   test("namespace-less resource omits the -n flag", async () => {
@@ -149,14 +217,83 @@ describe("k8s describeResources", () => {
     expect(receivedCmd).toContain("namespace mynamespace");
   });
 
-  test("entity without metadata.name is silently skipped", async () => {
+  test("entity without metadata.name is unobserved — nothing was queried", async () => {
     const entities = makeEntities([
       { name: "broken", entityType: "K8s::Apps::Deployment", props: {} },
     ]);
 
     const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["broken"], entities });
 
-    expect(result).toEqual({});
+    expect(result.resources).toEqual({});
+    expect(result.unobserved?.broken?.reason).toBe("read-failed");
     expect(execMock).not.toHaveBeenCalled();
   });
+
+  // chant #1100 — environment→cluster binding: bound-and-matching,
+  // bound-and-mismatched (loud refusal), and unbound (unchanged) paths.
+  describe("cluster binding (chant #1100)", () => {
+    function deploymentEntities() {
+      return makeEntities([
+        { name: "web", entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web", namespace: "prod" } } },
+      ]);
+    }
+
+    const deploymentStdout = JSON.stringify({
+      metadata: { name: "web", namespace: "prod", uid: "uid-1", creationTimestamp: "2026-05-01T00:00:00Z" },
+      status: { readyReplicas: 1, replicas: 1 },
+    });
+
+    test("bound and ambient context matches: observes explicitly via --context", async () => {
+      loadChantConfigMock.mockResolvedValue({ config: { k8s: { profiles: { prod: { context: "prod-eks" } } } } });
+      let receivedCmd = "";
+      execMock.mockImplementation((cmd: string) => {
+        if (cmd.includes("current-context")) return { stdout: "prod-eks\n", stderr: "" };
+        receivedCmd = cmd;
+        return { stdout: deploymentStdout, stderr: "" };
+      });
+
+      const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["web"], entities: deploymentEntities() });
+
+      expect(receivedCmd).toContain("--context prod-eks");
+      expect(result.resources["web"]).toMatchObject({ type: "K8s::Apps::Deployment", physicalId: "uid-1", status: "READY" });
+    });
+
+    test("bound and ambient context mismatches: refuses loudly instead of observing the wrong cluster", async () => {
+      loadChantConfigMock.mockResolvedValue({ config: { k8s: { profiles: { prod: { context: "prod-eks" } } } } });
+      execMock.mockImplementation((cmd: string) => {
+        if (cmd.includes("current-context")) return { stdout: "staging-eks\n", stderr: "" };
+        throw new Error(`unexpected cmd (should have refused before any kubectl get): ${cmd}`);
+      });
+
+      await expect(
+        describeResources({ environment: "prod", buildOutput: "", entityNames: ["web"], entities: deploymentEntities() }),
+      ).rejects.toThrow(/environment "prod".*"prod-eks".*"staging-eks"/s);
+
+      // Only the ambient-context probe ran — no per-entity kubectl get was attempted.
+      expect(execMock).toHaveBeenCalledTimes(1);
+    });
+
+    test("unbound: ambient context is used unchanged, but the fallback is visible (not silent)", async () => {
+      loadChantConfigMock.mockResolvedValue({ config: {} });
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+      let receivedCmd = "";
+      execMock.mockImplementation((cmd: string) => {
+        receivedCmd = cmd;
+        return { stdout: deploymentStdout, stderr: "" };
+      });
+
+      const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["web"], entities: deploymentEntities() });
+
+      // Unchanged: no ambient-context probe, no --context flag, same result shape as today.
+      expect(receivedCmd).not.toContain("--context");
+      expect(receivedCmd).not.toContain("current-context");
+      expect(result.resources["web"]).toMatchObject({ type: "K8s::Apps::Deployment", physicalId: "uid-1", status: "READY" });
+
+      // Visible, not silent: a warning names the environment and the missing binding.
+      const bindingWarning = warnSpy.mock.calls.find((c) => String(c[0]).includes("no cluster binding"));
+      expect(bindingWarning?.[0]).toContain('environment "prod"');
+      expect(bindingWarning?.[0]).toContain("k8s.profiles.prod.context");
+      warnSpy.mockRestore();
+    });
+  });
 });

package/src/describe-resources.ts

@@ -7,15 +7,31 @@
  * name (using the props.metadata.name + props.metadata.namespace from #39's
  * entity-prop pass-through).
  *
- * Resource-not-found is silent — `state diff --live` then reports it as
- * missing (declared, not in cloud). Unknown entity types are warn-skipped;
- * extending the KUBECTL_RESOURCE map covers more.
+ * The observation tri-state (#1089) is what the return value carries. A genuine
+ * `NotFound` from the API server is an absence, and only that becomes a `create`
+ * downstream. An entity type with no entry in `KUBECTL_RESOURCE` — every CRD —
+ * was never looked at, and comes back `unsupported-kind`: it may well be running
+ * in the cluster, and proposing to create it would be a guess. Auth failures and
+ * unreachable API servers come back `no-credentials` / `no-binding` for the same
+ * reason. Extending the KUBECTL_RESOURCE map converts unsupported-kind holes into
+ * real reads; until then they are holes chant admits to.
+ *
+ * Before touching any resource, the environment is resolved to a cluster
+ * identity (chant #1100) via `resolveClusterTarget` — see `./config.ts` for
+ * the `k8s.profiles.<env>.context` binding shape. A declared binding is
+ * passed explicitly as `--context` on every kubectl call below; an ambient
+ * context that disagrees with it aborts the whole describe with a loud
+ * error rather than silently reading the wrong cluster. No binding keeps
+ * today's behavior (ambient context), with a visible warning.
  */
 
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
-import type { ResourceMetadata } from "@intentius/chant/lexicon";
+import type { ObservationResult, ResourceMetadata, UnobservedEntity } from "@intentius/chant/lexicon";
+import { observation } from "@intentius/chant/observation";
 import { hasOwnershipMarker, classifyOwnership, LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
+import { loadChantConfig } from "@intentius/chant/config";
+import { resolveClusterTarget, classifyKubectlFailure } from "@intentius/chant/kubectl-context";
 
 const execAsync = promisify(exec);
 
@@ -87,29 +103,62 @@ export async function describeResources(options: {
   entityNames: string[];
   entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
   owned?: boolean;
-}): Promise<Record<string, ResourceMetadata>> {
+}): Promise<ObservationResult> {
   const result: Record<string, ResourceMetadata> = {};
+  const unobserved: Record<string, UnobservedEntity> = {};
   const skippedTypes = new Set<string>();
 
+  // Resolve the cluster identity for this environment before touching any
+  // resource — a declared-but-mismatched binding throws here, aborting the
+  // whole describe rather than letting a per-entity try/catch below absorb
+  // it as an ordinary "not found".
+  const { config } = await loadChantConfig(process.cwd());
+  const target = await resolveClusterTarget(config as Record<string, unknown>, options.environment, "k8s");
+  const ctxArg = target.context ? ["--context", target.context] : [];
+
   for (const [entityName, { entityType, props }] of options.entities) {
     const kubectlResource = KUBECTL_RESOURCE[entityType];
     if (!kubectlResource) {
+      // No reader for this kind (every CRD). The object may exist; chant has no
+      // way to ask. Reporting it as unobserved is what stops `lifecycle plan`
+      // proposing to create a CRD that is already in the cluster (#1089).
       skippedTypes.add(entityType);
+      unobserved[entityName] = {
+        type: entityType,
+        reason: "unsupported-kind",
+        detail: `no kubectl mapping for ${entityType} — extend KUBECTL_RESOURCE to observe it`,
+      };
       continue;
     }
 
     const metadata = props.metadata as { name?: string; namespace?: string } | undefined;
     const name = metadata?.name;
-    if (!name) continue;
+    if (!name) {
+      // Nothing to query by. Not an absence — chant never issued a read.
+      unobserved[entityName] = {
+        type: entityType,
+        reason: "read-failed",
+        detail: "declared entity has no metadata.name to query by",
+      };
+      continue;
+    }
 
     const nsArg = metadata.namespace ? ["-n", metadata.namespace] : [];
-    const cmd = ["kubectl", "get", kubectlResource, name, ...nsArg, "-o", "json"].join(" ");
+    const cmd = ["kubectl", "get", kubectlResource, name, ...nsArg, ...ctxArg, "-o", "json"].join(" ");
 
     try {
       const { stdout } = await execAsync(cmd);
       const obj: KubectlResponse = JSON.parse(stdout);
-      // owned filter: skip resources not carrying chant's marker label.
+      // owned filter: withhold resources not carrying chant's marker label.
+      // Withheld is not absent (#1089) — this object exists, it just isn't
+      // chant's, and dropping it silently is how `--owned` used to turn a
+      // declared-but-foreign resource into a proposed `create`.
       if (options.owned && !hasOwnershipMarker(obj.metadata?.labels, LABEL_OWNERSHIP_KEYS)) {
+        unobserved[entityName] = {
+          type: entityType,
+          reason: "filtered",
+          detail: "live object carries no chant ownership marker and --owned was requested",
+        };
         continue;
       }
       result[entityName] = {
@@ -124,18 +173,23 @@ export async function describeResources(options: {
           resourceVersion: obj.metadata?.resourceVersion,
         }),
       };
-    } catch {
-      // Resource not found / kubectl error — leave it out so state diff
-      // can report it as missing. Don't fail the whole snapshot.
+    } catch (err) {
+      // Only a real NotFound leaves the entity out (an absence the diff may
+      // read as missing and the plan as create). Auth, connectivity, and every
+      // other failure prove nothing about existence and are reported as such.
+      const outcome = classifyKubectlFailure(err);
+      if (outcome.kind === "unobserved") {
+        unobserved[entityName] = { type: entityType, reason: outcome.reason, detail: outcome.detail };
+      }
     }
   }
 
   if (skippedTypes.size > 0) {
     // eslint-disable-next-line no-console
     console.warn(
-      `[k8s] skipped ${skippedTypes.size} entity type(s) without kubectl mapping: ${[...skippedTypes].join(", ")}`,
+      `[k8s] no kubectl mapping for ${skippedTypes.size} entity type(s): ${[...skippedTypes].join(", ")} — reported as unobserved (not absent), so no create is proposed for them`,
     );
   }
 
-  return result;
+  return observation(result, unobserved);
 }

package/src/index.ts

@@ -85,3 +85,6 @@ export type { PackageOptions, PackageResult } from "./codegen/package";
 export type { CRDSource, CRDSpec } from "./crd/types";
 export { parseCRD, parseCRDSpec } from "./crd/parser";
 export { loadCRDs, loadMultipleCRDs } from "./crd/loader";
+
+// Environment → cluster binding config shape (chant #1100)
+export type { K8sChantConfig, K8sClusterProfile } from "./config";

package/src/lifecycle-integration.test.ts

@@ -31,6 +31,9 @@ vi.mock("node:child_process", async () => {
 const { k8sPlugin } = await import("./plugin");
 const { liveImportFromPlugins } = await import("@intentius/chant/cli/commands/import");
 const { buildChangeSet } = await import("@intentius/chant/lifecycle/change-set");
+const { normalizeObservation } = await import("@intentius/chant/observation");
+const { liveEvidenceFromChangeSet, reconcileStatus } = await import("@intentius/chant/lifecycle/status");
+const { describeObservationConformance } = await import("@intentius/chant-test-utils");
 
 const liveDeployment = {
   apiVersion: "apps/v1",
@@ -82,14 +85,16 @@ describe("k8s lifecycle integration (#163)", () => {
         : new Error("not found"),
     );
 
-    const observedNow = await k8sPlugin.describeResources!({
-      environment: "prod",
-      buildOutput: "",
-      entityNames: ["web"],
-      entities: new Map([
-        ["web", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web", namespace: "prod" } } }],
-      ]),
-    });
+    const { resources: observedNow } = normalizeObservation(
+      await k8sPlugin.describeResources!({
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["web"],
+        entities: new Map([
+          ["web", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web", namespace: "prod" } } }],
+        ]),
+      }),
+    );
     expect(observedNow.web?.type).toBe("K8s::Apps::Deployment");
 
     const cs = buildChangeSet("prod", {
@@ -108,4 +113,130 @@ describe("k8s lifecycle integration (#163)", () => {
     });
     expect(cs2.entries.find((e) => e.name === "web")!.action).toBe("noop");
   });
+
+  /**
+   * The #1089 chain, end to end on the real plugin: a declared CRD the lexicon
+   * has no reader for goes describe → plan → component status without ever
+   * turning into a create or a "stale" component.
+   */
+  test("tri-state chain: an unreadable CRD stays unobserved through describe → plan → status (#1089)", async () => {
+    execMock.mockImplementation((cmd?: string) =>
+      cmd?.includes("deployment.apps web")
+        ? {
+            stdout: JSON.stringify({
+              metadata: { name: "web", namespace: "prod", uid: "uid-1" },
+              status: { readyReplicas: 3, replicas: 3 },
+            }),
+            stderr: "",
+          }
+        : new Error('Error from server (NotFound): deployments.apps "gone" not found'),
+    );
+
+    const entities = new Map([
+      ["web", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web", namespace: "prod" } } }],
+      ["gone", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "gone", namespace: "prod" } } }],
+      ["widget", { entityType: "K8s::Example::Widget", props: { metadata: { name: "widget", namespace: "prod" } } }],
+    ]);
+
+    // 1. describe — three declared entities, three different verdicts.
+    const observed = normalizeObservation(
+      await k8sPlugin.describeResources!({
+        environment: "prod",
+        buildOutput: "",
+        entityNames: [...entities.keys()],
+        entities,
+      }),
+    );
+    expect(Object.keys(observed.resources)).toEqual(["web"]);
+    expect(observed.unobserved.widget.reason).toBe("unsupported-kind");
+    expect(observed.unobserved.gone).toBeUndefined(); // NotFound is an absence
+
+    // 2. plan — the CRD is `unobserved`; only the confirmed-absent one is a create.
+    const cs = buildChangeSet("prod", {
+      declared: new Set(entities.keys()),
+      observedNow: observed.resources,
+      observedThen: undefined,
+      unobserved: observed.unobserved,
+    });
+    const byName = Object.fromEntries(cs.entries.map((e) => [e.name, e.action]));
+    expect(byName).toEqual({ web: "noop", gone: "create", widget: "unobserved" });
+
+    // 3. status — a recorded component whose entity was never read reports
+    // `unknown`, not `stale`, and carries no `live` boolean at all.
+    const rows = reconcileStatus("prod", [
+      { component: "widget", env: "prod", digest: "sha256:abc", gitSha: "g", runId: "r", timestamp: "2026-01-01T00:00:00Z", actor: "ci" },
+    ], { liveEvidence: liveEvidenceFromChangeSet(cs) });
+    const widgetRow = rows.find((r) => r.component === "widget")!;
+    expect(widgetRow.reconciliation).toBe("unknown");
+    expect(widgetRow.live).toBeUndefined();
+    expect(widgetRow.unobserved?.reason).toBe("unsupported-kind");
+    expect(widgetRow.detail).toContain("could not be observed");
+  });
+});
+
+// The shared conformance suite (#1089) — every observing lexicon runs it.
+describeObservationConformance({
+  lexicon: "k8s",
+  scenarios: [
+    {
+      name: "a CRD kind with no reader",
+      declared: ["widget", "gone"],
+      expectUnobserved: ["widget"],
+      expectAbsent: ["gone"],
+      run: () => {
+        execMock.mockImplementation(() => new Error('Error from server (NotFound): deployments.apps "gone" not found'));
+        return k8sPlugin.describeResources!({
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["widget", "gone"],
+          entities: new Map([
+            ["widget", { entityType: "K8s::Example::Widget", props: { metadata: { name: "widget" } } }],
+            ["gone", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "gone" } } }],
+          ]),
+        });
+      },
+    },
+    {
+      name: "an unreachable API server",
+      declared: ["web"],
+      expectUnobserved: ["web"],
+      run: () => {
+        execMock.mockImplementation(() =>
+          Object.assign(new Error("kubectl failed"), {
+            stderr: "The connection to the server 127.0.0.1:6443 was refused - did you specify the right host or port?",
+          }),
+        );
+        return k8sPlugin.describeResources!({
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["web"],
+          entities: new Map([
+            ["web", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web" } } }],
+          ]),
+        });
+      },
+    },
+    {
+      name: "a healthy read",
+      declared: ["web"],
+      expectPresent: ["web"],
+      run: () => {
+        execMock.mockImplementation(() => ({
+          stdout: JSON.stringify({
+            metadata: { name: "web", namespace: "prod", uid: "uid-1", labels: { "app.kubernetes.io/managed-by": "chant" } },
+            status: { readyReplicas: 1, replicas: 1 },
+          }),
+          stderr: "",
+        }));
+        return k8sPlugin.describeResources!({
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["web"],
+          entities: new Map([
+            ["web", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web" } } }],
+          ]),
+        });
+      },
+    },
+  ],
 });

package/src/op/activities/index.ts

@@ -38,3 +38,15 @@ export type {
   ConditionMatch,
   PathMatch,
 } from "./wait-for-ready";
+
+// Environment→cluster binding (chant #1100) — the same resolver
+// `describeResources` (the read path) uses. `kubectlApply` and `waitForReady`
+// above already accept an optional `context`; a workflow author who wants the
+// write path to target the environment's bound cluster (rather than an
+// ambient one, closing the read/write split) resolves it here and passes the
+// result through, e.g. `kubectlApply({ manifest, context: (await
+// resolveClusterTarget(config, environment, "k8s")).context })`. Re-exported
+// from core rather than duplicated so both paths agree on one source of
+// truth — see `lexicons/k8s/src/config.ts` for the config shape.
+export { resolveClusterTarget, ClusterBindingMismatchError } from "@intentius/chant/kubectl-context";
+export type { ResolvedClusterTarget, K8sClusterProfile, K8sConfigShape } from "@intentius/chant/kubectl-context";

package/src/op/activities/kubectl.ts

@@ -6,7 +6,12 @@ const execAsync = promisify(exec);
 
 export interface KubectlApplyArgs {
   manifest: string;
-  /** kubectl context name. Uses current context if omitted. */
+  /**
+   * kubectl context name. Uses the ambient context if omitted. To target the
+   * same cluster the read path (`describeResources`) resolved for an
+   * environment — chant #1100 — resolve it with `resolveClusterTarget` from
+   * `./index.ts` and pass `.context` through.
+   */
   context?: string;
 }
 

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

@@ -147,7 +147,12 @@ export interface WaitForReadyArgs {
   name: string;
   /** Namespace (omit for cluster-scoped). */
   namespace?: string;
-  /** kubectl context. */
+  /**
+   * kubectl context. To target the same cluster the read path
+   * (`describeResources`) resolved for an environment — chant #1100 —
+   * resolve it with `resolveClusterTarget` from `./index.ts` and pass
+   * `.context` through.
+   */
   context?: string;
   /** API group, used to pick a readiness override when `spec` is not given. */
   group?: string;

package/src/skills/chant-k8s-eks.md

@@ -127,13 +127,28 @@ For Pod Identity, no K8s-side composite is needed — configure the association
 
 ## Karpenter
 
-Karpenter replaces Cluster Autoscaler for node provisioning. Karpenter NodePool and EC2NodeClass are simple CRDs — use CRD import rather than composites:
+Karpenter replaces Cluster Autoscaler for node provisioning. Karpenter's `NodePool` and `EC2NodeClass` are simple CRDs — add them to the k8s lexicon's CRD source list rather than importing per-project. There is no `chant import --url` flag; CRD-from-URL is lexicon-authoring-time codegen, done once in `lexicons/k8s/src/crd/crd-sources.ts`, not a per-project command:
+
+```typescript
+// lexicons/k8s/src/crd/crd-sources.ts
+const KARPENTER_VERSION = "v1.0.0"; // pin an operator release, not `main`
+const KARPENTER_CRD_BASE = `https://raw.githubusercontent.com/aws/karpenter-provider-aws/${KARPENTER_VERSION}/pkg/apis/crds`;
+
+export const CRD_SOURCES: CRDSource[] = [
+  // ...existing sources
+  { type: "url", url: `${KARPENTER_CRD_BASE}/karpenter.sh_nodepools.yaml` },
+  { type: "url", url: `${KARPENTER_CRD_BASE}/karpenter.k8s.aws_ec2nodeclasses.yaml` },
+];
+```
+
+Then regenerate the lexicon so the new kinds are typed:
 
 ```bash
-# Import Karpenter CRDs into your chant project
-chant import --url https://raw.githubusercontent.com/aws/karpenter/main/pkg/apis/crds/karpenter.sh_nodepools.yaml
+npm run generate -w @intentius/chant-lexicon-k8s
 ```
 
+See [Add a Third-Party CRD](/chant/lexicon-authoring/crd-sources/) for the full workflow (namespace mapping, verifying the generated type, adding rules).
+
 ## Fargate Considerations
 
 When running on EKS Fargate: