@intentius/chant-lexicon-k8s 0.42.1 → 0.44.1

package/src/generated/index.d.ts

@@ -2,6 +2,18 @@
 
 // --- Kubernetes Resource classes ---
 
+export declare class Addon {
+  constructor(props: {
+    /** Standard object's metadata. */
+    metadata?: ObjectMeta;
+    /** Spec provides information about the on-disk manifest backing this resource. */
+    spec?: Record<string, unknown>;
+  });
+  readonly name: string;
+  readonly namespace: string;
+  readonly uid: string;
+}
+
 export declare class Alert {
   constructor(props: {
     /** Standard object's metadata. */
@@ -920,6 +932,19 @@ export declare class FlowSchemaList {
   readonly uid: string;
 }
 
+export declare class FluxHelmChart {
+  constructor(props: {
+    /** Standard object's metadata. */
+    metadata?: ObjectMeta;
+    /** HelmChartSpec specifies the desired state of a Helm chart. */
+    spec?: Record<string, unknown>;
+  });
+  readonly name: string;
+  readonly namespace: string;
+  readonly status: Record<string, unknown>;
+  readonly uid: string;
+}
+
 export declare class FluxInstance {
   constructor(props: {
     /** Standard object's metadata. */
@@ -999,16 +1024,16 @@ export declare class GRPCRoute {
   readonly uid: string;
 }
 
-export declare class HelmChart {
+export declare class HelmChartConfig {
   constructor(props: {
     /** Standard object's metadata. */
     metadata?: ObjectMeta;
-    /** HelmChartSpec specifies the desired state of a Helm chart. */
+    /** HelmChartConfigSpec represents additional user-configurable details of an installed and configured Helm chart release.
+These fields are merged with or override the corresponding fields on the related HelmChart resource. */
     spec?: Record<string, unknown>;
   });
   readonly name: string;
   readonly namespace: string;
-  readonly status: Record<string, unknown>;
   readonly uid: string;
 }
 
@@ -1325,6 +1350,19 @@ export declare class JobList {
   readonly uid: string;
 }
 
+export declare class K3sHelmChart {
+  constructor(props: {
+    /** Standard object's metadata. */
+    metadata?: ObjectMeta;
+    /** HelmChartSpec represents the user-configurable details for installation and upgrade of a Helm chart release. */
+    spec?: Record<string, unknown>;
+  });
+  readonly name: string;
+  readonly namespace: string;
+  readonly status: Record<string, unknown>;
+  readonly uid: string;
+}
+
 export declare class Kustomization {
   constructor(props: {
     /** Standard object's metadata. */

package/src/generated/index.ts

@@ -1,6 +1,7 @@
 // Code generated by chant generate. DO NOT EDIT.
 import { createResource, createProperty } from "./runtime";
 
+export const Addon = createResource("K8s::K3s::Addon", "k8s", {"name":"name","namespace":"namespace","uid":"uid"});
 export const Alert = createResource("K8s::Flux::Alert", "k8s", {"name":"name","namespace":"namespace","uid":"uid"});
 export const APIGroup = createResource("K8s::Core::APIGroup", "k8s", {"name":"name","namespace":"namespace","uid":"uid"});
 export const APIGroupList = createResource("K8s::Core::APIGroupList", "k8s", {"name":"name","namespace":"namespace","uid":"uid"});
@@ -68,13 +69,14 @@ export const EventsEventList = createResource("K8s::Events::EventList", "k8s", {
 export const Eviction = createResource("K8s::Policy::Eviction", "k8s", {"name":"name","namespace":"namespace","uid":"uid"});
 export const FlowSchema = createResource("K8s::Flowcontrol::FlowSchema", "k8s", {"name":"name","namespace":"namespace","uid":"uid"});
 export const FlowSchemaList = createResource("K8s::Flowcontrol::FlowSchemaList", "k8s", {"name":"name","namespace":"namespace","uid":"uid"});
+export const FluxHelmChart = createResource("K8s::Flux::HelmChart", "k8s", {"name":"name","namespace":"namespace","uid":"uid","status":"status"});
 export const FluxInstance = createResource("K8s::Flux::FluxInstance", "k8s", {"name":"name","namespace":"namespace","uid":"uid","status":"status"});
 export const FluxReport = createResource("K8s::Flux::FluxReport", "k8s", {"name":"name","namespace":"namespace","uid":"uid","status":"status"});
 export const Gateway = createResource("K8s::Gateway::Gateway", "k8s", {"name":"name","namespace":"namespace","uid":"uid","status":"status"});
 export const GatewayClass = createResource("K8s::Gateway::GatewayClass", "k8s", {"name":"name","namespace":"namespace","uid":"uid","status":"status"});
 export const GitRepository = createResource("K8s::Flux::GitRepository", "k8s", {"name":"name","namespace":"namespace","uid":"uid","status":"status"});
 export const GRPCRoute = createResource("K8s::Gateway::GRPCRoute", "k8s", {"name":"name","namespace":"namespace","uid":"uid","status":"status"});
-export const HelmChart = createResource("K8s::Flux::HelmChart", "k8s", {"name":"name","namespace":"namespace","uid":"uid","status":"status"});
+export const HelmChartConfig = createResource("K8s::K3s::HelmChartConfig", "k8s", {"name":"name","namespace":"namespace","uid":"uid"});
 export const HelmRelease = createResource("K8s::Flux::HelmRelease", "k8s", {"name":"name","namespace":"namespace","uid":"uid","status":"status"});
 export const HelmRepository = createResource("K8s::Flux::HelmRepository", "k8s", {"name":"name","namespace":"namespace","uid":"uid","status":"status"});
 export const HorizontalPodAutoscaler = createResource("K8s::Autoscaling::HorizontalPodAutoscaler", "k8s", {"name":"name","namespace":"namespace","uid":"uid"});
@@ -100,6 +102,7 @@ export const IPAddressList = createResource("K8s::Networking::IPAddressList", "k
 export const Issuer = createResource("K8s::CertManager::Issuer", "k8s", {"name":"name","namespace":"namespace","uid":"uid","status":"status"});
 export const Job = createResource("K8s::Batch::Job", "k8s", {"name":"name","namespace":"namespace","uid":"uid"});
 export const JobList = createResource("K8s::Batch::JobList", "k8s", {"name":"name","namespace":"namespace","uid":"uid"});
+export const K3sHelmChart = createResource("K8s::K3s::HelmChart", "k8s", {"name":"name","namespace":"namespace","uid":"uid","status":"status"});
 export const Kustomization = createResource("K8s::Flux::Kustomization", "k8s", {"name":"name","namespace":"namespace","uid":"uid","status":"status"});
 export const Lease = createResource("K8s::Coordination::Lease", "k8s", {"name":"name","namespace":"namespace","uid":"uid"});
 export const LeaseCandidate = createResource("K8s::Coordination::LeaseCandidate", "k8s", {"name":"name","namespace":"namespace","uid":"uid"});
@@ -332,6 +335,9 @@ export const EnvVar = createProperty("K8s::Core::EnvVar", "k8s");
 export const EnvVarSource = createProperty("K8s::Core::EnvVarSource", "k8s");
 export const EphemeralContainer = createProperty("K8s::Core::EphemeralContainer", "k8s");
 export const ExecAction = createProperty("K8s::Core::ExecAction", "k8s");
+export const FluxHelmChart_SourceRef = createProperty("K8s::Flux::HelmChart.sourceRef", "k8s");
+export const FluxHelmChart_Status = createProperty("K8s::Flux::HelmChart.status", "k8s");
+export const FluxHelmChart_Verify = createProperty("K8s::Flux::HelmChart.verify", "k8s");
 export const FluxInstance_Cluster = createProperty("K8s::Flux::FluxInstance.cluster", "k8s");
 export const FluxInstance_CommonMetadata = createProperty("K8s::Flux::FluxInstance.commonMetadata", "k8s");
 export const FluxInstance_Distribution = createProperty("K8s::Flux::FluxInstance.distribution", "k8s");
@@ -362,9 +368,7 @@ export const GitRepository_Verify = createProperty("K8s::Flux::GitRepository.ver
 export const GRPCRoute_ParentRef = createProperty("K8s::Gateway::GRPCRoute.parentRefs", "k8s");
 export const GRPCRoute_Rule = createProperty("K8s::Gateway::GRPCRoute.rules", "k8s");
 export const GRPCRoute_Status = createProperty("K8s::Gateway::GRPCRoute.status", "k8s");
-export const HelmChart_SourceRef = createProperty("K8s::Flux::HelmChart.sourceRef", "k8s");
-export const HelmChart_Status = createProperty("K8s::Flux::HelmChart.status", "k8s");
-export const HelmChart_Verify = createProperty("K8s::Flux::HelmChart.verify", "k8s");
+export const HelmChartConfig_ValuesSecret = createProperty("K8s::K3s::HelmChartConfig.valuesSecrets", "k8s");
 export const HelmRelease_Chart = createProperty("K8s::Flux::HelmRelease.chart", "k8s");
 export const HelmRelease_ChartRef = createProperty("K8s::Flux::HelmRelease.chartRef", "k8s");
 export const HelmRelease_CommonMetadata = createProperty("K8s::Flux::HelmRelease.commonMetadata", "k8s");
@@ -440,6 +444,13 @@ export const Issuer_SelfSigned = createProperty("K8s::CertManager::Issuer.selfSi
 export const Issuer_Status = createProperty("K8s::CertManager::Issuer.status", "k8s");
 export const Issuer_Vault = createProperty("K8s::CertManager::Issuer.vault", "k8s");
 export const Issuer_Venafi = createProperty("K8s::CertManager::Issuer.venafi", "k8s");
+export const K3sHelmChart_AuthSecret = createProperty("K8s::K3s::HelmChart.authSecret", "k8s");
+export const K3sHelmChart_DockerRegistrySecret = createProperty("K8s::K3s::HelmChart.dockerRegistrySecret", "k8s");
+export const K3sHelmChart_PodSecurityContext = createProperty("K8s::K3s::HelmChart.podSecurityContext", "k8s");
+export const K3sHelmChart_RepoCAConfigMap = createProperty("K8s::K3s::HelmChart.repoCAConfigMap", "k8s");
+export const K3sHelmChart_SecurityContext = createProperty("K8s::K3s::HelmChart.securityContext", "k8s");
+export const K3sHelmChart_Status = createProperty("K8s::K3s::HelmChart.status", "k8s");
+export const K3sHelmChart_ValuesSecret = createProperty("K8s::K3s::HelmChart.valuesSecrets", "k8s");
 export const KeyToPath = createProperty("K8s::Core::KeyToPath", "k8s");
 export const Kustomization_CommonMetadata = createProperty("K8s::Flux::Kustomization.commonMetadata", "k8s");
 export const Kustomization_Decryption = createProperty("K8s::Flux::Kustomization.decryption", "k8s");

package/src/generated/lexicon-k8s.json

@@ -51,6 +51,13 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "Addon": {
+    "resourceType": "K8s::K3s::Addon",
+    "kind": "resource",
+    "lexicon": "k8s",
+    "apiVersion": "k3s.cattle.io/v1",
+    "gvkKind": "Addon"
+  },
   "Address": {
     "resourceType": "K8s::Gateway::Gateway.addresses",
     "kind": "property",
@@ -229,6 +236,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "AuthSecret": {
+    "resourceType": "K8s::K3s::HelmChart.authSecret",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "AutoscalerOptions": {
     "resourceType": "K8s::Ray::RayCluster.autoscalerOptions",
     "kind": "property",
@@ -1066,6 +1078,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "DockerRegistrySecret": {
+    "resourceType": "K8s::K3s::HelmChart.dockerRegistrySecret",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "DriftDetection": {
     "resourceType": "K8s::Flux::HelmRelease.driftDetection",
     "kind": "property",
@@ -1241,6 +1258,28 @@
     "apiVersion": "flowcontrol.apiserver.k8s.io/v1",
     "gvkKind": "FlowSchemaList"
   },
+  "FluxHelmChart": {
+    "resourceType": "K8s::Flux::HelmChart",
+    "kind": "resource",
+    "lexicon": "k8s",
+    "apiVersion": "source.toolkit.fluxcd.io/v1",
+    "gvkKind": "HelmChart"
+  },
+  "FluxHelmChart_SourceRef": {
+    "resourceType": "K8s::Flux::HelmChart.sourceRef",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "FluxHelmChart_Status": {
+    "resourceType": "K8s::Flux::HelmChart.status",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "FluxHelmChart_Verify": {
+    "resourceType": "K8s::Flux::HelmChart.verify",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "FluxInstance": {
     "resourceType": "K8s::Flux::FluxInstance",
     "kind": "resource",
@@ -1527,25 +1566,15 @@
     "kind": "property",
     "lexicon": "k8s"
   },
-  "HelmChart": {
-    "resourceType": "K8s::Flux::HelmChart",
+  "HelmChartConfig": {
+    "resourceType": "K8s::K3s::HelmChartConfig",
     "kind": "resource",
     "lexicon": "k8s",
-    "apiVersion": "source.toolkit.fluxcd.io/v1",
-    "gvkKind": "HelmChart"
+    "apiVersion": "helm.cattle.io/v1",
+    "gvkKind": "HelmChartConfig"
   },
-  "HelmChart_SourceRef": {
-    "resourceType": "K8s::Flux::HelmChart.sourceRef",
-    "kind": "property",
-    "lexicon": "k8s"
-  },
-  "HelmChart_Status": {
-    "resourceType": "K8s::Flux::HelmChart.status",
-    "kind": "property",
-    "lexicon": "k8s"
-  },
-  "HelmChart_Verify": {
-    "resourceType": "K8s::Flux::HelmChart.verify",
+  "HelmChartConfig_ValuesSecret": {
+    "resourceType": "K8s::K3s::HelmChartConfig.valuesSecrets",
     "kind": "property",
     "lexicon": "k8s"
   },
@@ -2145,6 +2174,48 @@
     "apiVersion": "batch/v1",
     "gvkKind": "JobList"
   },
+  "K3sHelmChart": {
+    "resourceType": "K8s::K3s::HelmChart",
+    "kind": "resource",
+    "lexicon": "k8s",
+    "apiVersion": "helm.cattle.io/v1",
+    "gvkKind": "HelmChart"
+  },
+  "K3sHelmChart_AuthSecret": {
+    "resourceType": "K8s::K3s::HelmChart.authSecret",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "K3sHelmChart_DockerRegistrySecret": {
+    "resourceType": "K8s::K3s::HelmChart.dockerRegistrySecret",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "K3sHelmChart_PodSecurityContext": {
+    "resourceType": "K8s::K3s::HelmChart.podSecurityContext",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "K3sHelmChart_RepoCAConfigMap": {
+    "resourceType": "K8s::K3s::HelmChart.repoCAConfigMap",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "K3sHelmChart_SecurityContext": {
+    "resourceType": "K8s::K3s::HelmChart.securityContext",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "K3sHelmChart_Status": {
+    "resourceType": "K8s::K3s::HelmChart.status",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "K3sHelmChart_ValuesSecret": {
+    "resourceType": "K8s::K3s::HelmChart.valuesSecrets",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "KeyToPath": {
     "resourceType": "K8s::Core::KeyToPath",
     "kind": "property",
@@ -3416,6 +3487,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "RepoCAConfigMap": {
+    "resourceType": "K8s::K3s::HelmChart.repoCAConfigMap",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "Resource": {
     "resourceType": "K8s::Flux::Receiver.resources",
     "kind": "property",

package/src/generated/operations.json

@@ -1665,6 +1665,54 @@
       "watch"
     ]
   },
+  "K8s::K3s::Addon": {
+    "entityType": "K8s::K3s::Addon",
+    "apiVersion": "k3s.cattle.io/v1",
+    "kind": "Addon",
+    "plural": "addons",
+    "scope": "Namespaced",
+    "verbs": [
+      "delete",
+      "get",
+      "list",
+      "patch",
+      "post",
+      "put",
+      "watch"
+    ]
+  },
+  "K8s::K3s::HelmChart": {
+    "entityType": "K8s::K3s::HelmChart",
+    "apiVersion": "helm.cattle.io/v1",
+    "kind": "HelmChart",
+    "plural": "helmcharts",
+    "scope": "Namespaced",
+    "verbs": [
+      "delete",
+      "get",
+      "list",
+      "patch",
+      "post",
+      "put",
+      "watch"
+    ]
+  },
+  "K8s::K3s::HelmChartConfig": {
+    "entityType": "K8s::K3s::HelmChartConfig",
+    "apiVersion": "helm.cattle.io/v1",
+    "kind": "HelmChartConfig",
+    "plural": "helmchartconfigs",
+    "scope": "Namespaced",
+    "verbs": [
+      "delete",
+      "get",
+      "list",
+      "patch",
+      "post",
+      "put",
+      "watch"
+    ]
+  },
   "K8s::KubeMicroVM::MicroVM": {
     "entityType": "K8s::KubeMicroVM::MicroVM",
     "apiVersion": "lambda.aws.amazon.com/v1alpha1",

package/src/index.ts

@@ -34,6 +34,7 @@ export {
   GceIngress, CockroachDbCluster, CockroachDbRegionStack,
   RayCluster, RayJob, RayService,
   ArgoAppFor, ArgoAppSetForRegions, registerArgoCluster,
+  FluxGitSource, FluxAppFor,
   AgicIngress, AzureDiskStorageClass, AzureFileStorageClass, AzureMonitorCollector,
   AksWorkloadIdentityServiceAccount,
   GkeFluentBitAgent, GkeOtelCollector, GkeExternalDnsAgent, AksExternalDnsAgent,
@@ -64,6 +65,9 @@ export type {
   ArgoAppForOptions, ArgoAppForResult,
   ArgoRegionTarget, ArgoAppSetForRegionsOptions, ArgoAppSetForRegionsResult,
   RegisterArgoClusterOptions, RegisterArgoClusterResult,
+  FluxSourceKind, FluxSourceRef,
+  FluxGitSourceOptions, FluxGitSourceResult,
+  FluxAppForOptions, FluxAppForResult,
   AgicIngressProps, AgicIngressResult,
   AzureDiskStorageClassProps, AzureDiskStorageClassResult,
   AzureFileStorageClassProps, AzureFileStorageClassResult,

package/src/kube/connect.ts

@@ -1,10 +1,11 @@
 /**
  * Connecting to a cluster on `chant kube`'s behalf (chant #1079), honoring
  * the exact same environment→cluster binding every other observing path
- * does (chant #1100/#1155): `--env` resolves `k8s.profiles.<env>.context`
- * and refuses loudly on a mismatch, `--context` is an explicit override that
- * skips the binding entirely, and neither given falls back to the ambient
- * kubeconfig context — the same three modes `describeResources` and the Op
+ * does (chant #1100/#1155, revised by #1488): `--env` resolves
+ * `k8s.profiles.<env>.context` and uses it regardless of the ambient
+ * context, `--context` is an explicit override that skips the binding
+ * entirely, and neither given falls back to the ambient kubeconfig
+ * context — the same three modes `describeResources` and the Op
  * activities already use, via the same `defaultK8sConnector`. Nothing here
  * reimplements that resolution; this only turns a connect failure into the
  * observation tri-state so a verb can render NOT-OBSERVED-with-reason

package/src/kube/get.ts

@@ -3,10 +3,10 @@
  * chant verdict column the issue's acceptance criterion names.
  *
  * The cluster edge is the typed client (chant #1074/#1177), reached the same
- * way every other read does: `--env` resolves and honors the cluster
- * binding (chant #1100/#1155, refusing loudly on a mismatch), `--context` is
- * an explicit override, neither given falls back to the ambient kubeconfig
- * context. A connect failure, an RBAC-denied read, or a kind the cluster's
+ * way every other read does: `--env` resolves and uses the cluster
+ * binding (chant #1100/#1155, revised by #1488 — the declared context is
+ * used regardless of what is ambient), `--context` is an explicit override,
+ * neither given falls back to the ambient kubeconfig context. A connect failure, an RBAC-denied read, or a kind the cluster's
  * discovery has never heard of all render as an honest message rather than
  * an empty table — "No resources found." is reserved for the one case that
  * actually means it: the kind is real and there are zero live instances.

package/src/kustomize/render.ts

@@ -0,0 +1,84 @@
+/**
+ * The kustomize renderer (#1548) — one implementation, two consumers.
+ *
+ * Piece 1 (`components/kustomize-apply.ts`) renders at DEPLOY time in front
+ * of the server-side applier; piece 3 (`./root.ts`) renders at BUILD time to
+ * give an overlay estate a declared side. Both run the same command with the
+ * same fallback through the same injectable runner, so a test asserts the
+ * exact invocation without either binary installed and the two paths cannot
+ * drift apart on how an overlay is rendered.
+ *
+ * Renderer resolution: `kustomize build`, falling back to `kubectl
+ * kustomize` (the same renderer vendored into kubectl) when the standalone
+ * binary is absent. When NEITHER binary exists the failure names both — a
+ * missing renderer is an environment problem the operator can fix in one
+ * install, and it must read as that, not as a stack trace. A render failure
+ * from an existing binary (a broken overlay, a missing base) propagates
+ * untouched: that error text is kustomize's own diagnosis and is strictly
+ * better than anything this module could wrap it in.
+ *
+ * The 64MiB maxBuffer mirrors helm-upgrade's — a big overlay renders
+ * megabytes.
+ */
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { loadAll } from "js-yaml";
+
+const execAsync = promisify(exec);
+
+/** Injectable shell runner — the helm-upgrade seam, same buffer bound. */
+export type KustomizeRunner = (command: string) => Promise<{ stdout: string }>;
+
+export const defaultKustomizeRunner: KustomizeRunner = (command) =>
+  execAsync(command, { maxBuffer: 64 * 1024 * 1024 });
+
+/** Single-quote shell escaping, as helm-upgrade quotes its argv. */
+function q(v: string): string {
+  return `'${v.replace(/'/g, "'\\''")}'`;
+}
+
+/** The exact render command, standalone binary first. Pure; exported for tests. */
+export function renderCommand(dir: string, tool: "kustomize" | "kubectl" = "kustomize"): string {
+  return tool === "kustomize" ? `kustomize build ${q(dir)}` : `kubectl kustomize ${q(dir)}`;
+}
+
+/** Does this error mean "the binary is not installed" (vs "the render failed")? */
+function isMissingBinary(err: unknown): boolean {
+  const message = err instanceof Error ? err.message : String(err);
+  return /ENOENT|not found|command not found|127/.test(message);
+}
+
+/**
+ * Render the kustomization at `dir` and parse the emitted YAML into document
+ * objects. Falls back to kubectl's vendored kustomize when the standalone
+ * binary is missing; when both binaries are missing, fails with a message
+ * naming them.
+ */
+export async function renderKustomizeDocuments(
+  dir: string,
+  run: KustomizeRunner = defaultKustomizeRunner,
+): Promise<Array<Record<string, unknown>>> {
+  let stdout: string;
+  try {
+    ({ stdout } = await run(renderCommand(dir, "kustomize")));
+  } catch (err) {
+    if (!isMissingBinary(err)) throw err;
+    try {
+      ({ stdout } = await run(renderCommand(dir, "kubectl")));
+    } catch (err2) {
+      if (isMissingBinary(err2)) {
+        throw new Error(
+          `Cannot render kustomization "${dir}": neither the \`kustomize\` binary nor \`kubectl\` ` +
+            `(whose vendored \`kubectl kustomize\` is the fallback) was found on PATH. ` +
+            `Install kustomize or kubectl and retry.`,
+        );
+      }
+      throw err2;
+    }
+  }
+  const documents: Array<Record<string, unknown>> = [];
+  for (const doc of loadAll(stdout)) {
+    if (doc && typeof doc === "object" && !Array.isArray(doc)) documents.push(doc as Record<string, unknown>);
+  }
+  return documents;
+}

package/src/kustomize/rendered-entity.ts

@@ -0,0 +1,72 @@
+/**
+ * A rendered kustomize document as a chant entity (#1548 piece 3).
+ *
+ * A kustomize build root's output is a set of finished manifests, not typed
+ * chant source — the overlay already decided every field. So the entity that
+ * carries one into the build is deliberately verbatim: `props` IS the
+ * document, and the serializer emits it as-is (plus the same default-label /
+ * ownership merge every discovered resource gets) instead of running the
+ * spec-inference heuristics built for typed declarables. The marker is what
+ * tells the serializer to take that path — `Symbol.for`, so a lexicon built
+ * against a separate copy of core still matches (the #1137 lesson).
+ *
+ * `entityType` uses the same `K8s::{Group}::{Kind}` convention the generated
+ * operation surface speaks, so `lifecycle diff --live` observes a rendered
+ * Deployment through exactly the reader a declared one uses. A kind the
+ * surface doesn't know reports NOT-OBSERVED with the existing "no generated
+ * operation surface" reason — the honest verdict, not a silent hole.
+ *
+ * Provenance: every rendered document is stamped with an annotation naming
+ * the overlay dir it came from, so a consumer (behold#171's overlay boxes)
+ * can group by declared origin instead of guessing from paths.
+ */
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import { gvkToTypeName } from "../spec/parse";
+
+/** Marks an entity whose `props` are a complete, render-final manifest. */
+export const RENDERED_MANIFEST_MARKER = Symbol.for("chant.k8s.renderedManifest");
+
+/** Annotation stamped on every rendered document, valued with the root dir. */
+export const KUSTOMIZE_ROOT_ANNOTATION = "chant.intentius.io/kustomize-root";
+
+export interface RenderedManifestEntity extends Declarable {
+  readonly kind: "resource";
+  readonly props: Record<string, unknown>;
+  readonly [RENDERED_MANIFEST_MARKER]: true;
+}
+
+export function isRenderedManifestEntity(entity: Declarable): entity is RenderedManifestEntity {
+  return (entity as unknown as Record<symbol, unknown>)[RENDERED_MANIFEST_MARKER] === true;
+}
+
+/**
+ * Wrap one rendered document. Returns null when the document has no string
+ * `apiVersion`/`kind` — not a Kubernetes object, nothing to declare.
+ */
+export function renderedManifestEntity(
+  doc: Record<string, unknown>,
+  root: string,
+): RenderedManifestEntity | null {
+  const apiVersion = doc.apiVersion;
+  const kind = doc.kind;
+  if (typeof apiVersion !== "string" || typeof kind !== "string" || !apiVersion || !kind) return null;
+
+  const slash = apiVersion.indexOf("/");
+  const group = slash === -1 ? "" : apiVersion.slice(0, slash);
+  const version = slash === -1 ? apiVersion : apiVersion.slice(slash + 1);
+
+  const metadata = { ...((doc.metadata as Record<string, unknown> | undefined) ?? {}) };
+  metadata.annotations = {
+    ...((metadata.annotations as Record<string, unknown> | undefined) ?? {}),
+    [KUSTOMIZE_ROOT_ANNOTATION]: root,
+  };
+
+  return {
+    lexicon: "k8s",
+    entityType: gvkToTypeName({ group, version, kind }),
+    kind: "resource",
+    props: { ...doc, metadata },
+    [DECLARABLE_MARKER]: true,
+    [RENDERED_MANIFEST_MARKER]: true,
+  };
+}