@intentius/chant-lexicon-k8s 0.44.4 → 0.44.6

package/dist/describe-resources.d.ts

@@ -62,6 +62,34 @@ import { type K8sConnector } from "./api/connect.js";
  */
 export declare function statusFromObject(obj: K8sObject): string;
 export declare function unhappyConditions(obj: K8sObject): string[] | undefined;
+/**
+ * The revisions a GitOps controller writes onto its own object (#1632).
+ *
+ * Conditions lag. A Flux Kustomization mid-rollout still reports the previous
+ * reconcile's `Ready=True` for as long as the new one takes, so a consumer
+ * reading only conditions calls a half-applied estate converged. The
+ * controller's own definition of converged is a revision comparison:
+ * `lastAppliedRevision` against `lastAttemptedRevision` on the same object
+ * (attempted-but-not-applied is in flight), and a Kustomization's
+ * `lastAppliedRevision` against its source's `artifact.revision` (the
+ * cross-object half, which a consumer joins once both ends are on the wire).
+ * None of the three reached an observed entity's attributes before this.
+ *
+ * Read by path rather than by kind, which is the module's standing rule
+ * everywhere else: `status.lastAppliedRevision` / `status.lastAttemptedRevision`
+ * are what kustomize-controller and helm-controller write, and
+ * `status.artifact.revision` is what every source kind (GitRepository,
+ * OCIRepository, Bucket, HelmChart) writes. An object that has none of them —
+ * every non-GitOps kind — contributes nothing, so no kind table has to name
+ * which kinds those are, and a CRD speaking the same convention is carried for
+ * free. `artifactRevision` flattens the one nested path so every revision on
+ * the wire is a plain string next to the others.
+ */
+export declare function revisionAttributes(obj: K8sObject): {
+    lastAppliedRevision?: string;
+    lastAttemptedRevision?: string;
+    artifactRevision?: string;
+};
 export interface DescribeResourcesOptions {
     environment: string;
     buildOutput: string;
@@ -73,6 +101,25 @@ export interface DescribeResourcesOptions {
     owned?: boolean;
     /** Directory whose `chant.config.ts` carries the cluster binding. Defaults to cwd. */
     cwd?: string;
+    /**
+     * Namespace to read a namespaced entity from when it declares none (#1629).
+     *
+     * A GitOps estate splits the binding from the objects: the control-plane
+     * project declares a Kustomization with `spec.targetNamespace: app-b`, the
+     * app project declares bare Deployments and Services with no
+     * `metadata.namespace` at all — the controller stamps it at apply time. The
+     * live read of the app project had no way to be told that, so it fell
+     * through to the client's `default` and reported an estate that is running
+     * as entirely absent (#1620's `queried` line is what made that visible).
+     *
+     * A DEFAULT, never a rewrite: an entity with an explicit
+     * `metadata.namespace` reads from the namespace it declares, override or
+     * not — that declaration is the estate's own statement of where the object
+     * lives, and overruling it would make the option a way to read the wrong
+     * object rather than the right one. Cluster-scoped kinds are untouched:
+     * they have no namespace to default.
+     */
+    namespace?: string;
 }
 export declare function describeResources(options: DescribeResourcesOptions, connect?: K8sConnector): 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAwD,MAAM,0BAA0B,CAAC;AAGxH,OAAO,KAAK,EAAa,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAmBvE;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,CA2CvD;AA4FD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,EAAE,GAAG,SAAS,CAetE;AAQD,MAAM,WAAW,wBAAwB;IACvC,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;IAChB,sFAAsF;IACtF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,EACjC,OAAO,GAAE,YAAkC,GAC1C,OAAO,CAAC,iBAAiB,CAAC,CAoJ5B"}
+{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAwD,MAAM,0BAA0B,CAAC;AAGxH,OAAO,KAAK,EAAa,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAmBvE;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,CA2CvD;AA4FD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,EAAE,GAAG,SAAS,CAetE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,SAAS,GAAG;IAClD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAUA;AAQD,MAAM,WAAW,wBAAwB;IACvC,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;IAChB,sFAAsF;IACtF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,EACjC,OAAO,GAAE,YAAkC,GAC1C,OAAO,CAAC,iBAAiB,CAAC,CA6J5B"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "994f303cfb6edefd9d0eb5d18406f784172b3fb0bd5b524e7e3255a96f4bf338",
+    "manifest.json": "c4b378460b192f75c29f7daad4779c0cf63d5ab56edc9ae31431e90833f71e18",
     "meta.json": "f568fb8a0cbd4adf041baccaa3e1164c2e3c5c0090186236f887f0084f5521a8",
     "types/index.d.ts": "ef2c9df6a4d1ebfbe33f96c094fbbe3fc7909522ea38e086666fbf3c8ac477fd",
     "rules/argo-appset-single-project.ts": "afa9f310753aa2d475f35012b13135b2dfaebed2a35d44edbe185ebc07673674",
@@ -54,5 +54,5 @@
     "skills/chant-k8s-argo.md": "b1a0b826559d8c5033a479c5781efaf650320f0aee4419d8841170bd3393cea5",
     "skills/chant-k8s-flux.md": "9670efc2e9854bd14686b5adeb707396b9030a4dcaee6529b30abf56efe2c50c"
   },
-  "composite": "815ab02fe7f7325c6fbec07be9f9f8423df8d9771ddd23babef1af5ae60c0acd"
+  "composite": "3e4f2e1e01baea8c1204bde8b257bbab0c1508eb1a1718f883a93b664ffc202f"
 }

package/dist/manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-k8s",
-  "version": "0.44.4",
+  "version": "0.44.6",
   "description": "Kubernetes lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -76,7 +76,7 @@
     "@types/js-yaml": "^4.0.9"
   },
   "optionalDependencies": {
-    "@intentius/chant-k8s-client": "^0.44.4"
+    "@intentius/chant-k8s-client": "^0.44.6"
   },
   "devDependencies": {
     "@intentius/chant": "*",
@@ -84,7 +84,7 @@
   },
   "peerDependencies": {
     "zod": "^4.3.6",
-    "@intentius/chant": "^0.44.4",
+    "@intentius/chant": "^0.44.6",
     "typescript": "^5.9.3"
   }
 }

package/src/describe-resources.test.ts

@@ -15,7 +15,7 @@ vi.mock("@intentius/chant/config", () => ({
   loadChantConfig: (...args: unknown[]) => loadChantConfigMock(...args),
 }));
 
-const { describeResources, statusFromObject, unhappyConditions } = await import("./describe-resources");
+const { describeResources, statusFromObject, unhappyConditions, revisionAttributes } = await import("./describe-resources");
 const { fakeCluster, objectKey, ownedObject } = await import("./api/fake-cluster");
 const { defaultK8sConnector } = await import("./api/connect");
 const { fakeKubeconfig, statusBody } = await import("@intentius/chant-k8s-client/testing");
@@ -1399,3 +1399,277 @@ describe("unhappyConditions (#1401)", () => {
     expect(unhappyConditions({} as never)).toBeUndefined();
   });
 });
+
+describe("revisionAttributes — the GitOps convergence fields (#1632)", () => {
+  test("carries a Kustomization's applied and attempted revisions", () => {
+    expect(
+      revisionAttributes({
+        status: {
+          lastAppliedRevision: "main@sha1:1a2b3c4d",
+          lastAttemptedRevision: "main@sha1:5e6f7a8b",
+          conditions: [{ type: "Ready", status: "True" }],
+        },
+      } as never),
+    ).toMatchObject({ lastAppliedRevision: "main@sha1:1a2b3c4d", lastAttemptedRevision: "main@sha1:5e6f7a8b" });
+  });
+
+  test("flattens a source kind's status.artifact.revision", () => {
+    expect(revisionAttributes({ status: { artifact: { revision: "main@sha1:1a2b3c4d" } } } as never)).toMatchObject({
+      artifactRevision: "main@sha1:1a2b3c4d",
+    });
+  });
+
+  test("says nothing for an object that carries none of them", () => {
+    // Every field undefined, so `pruneUndefined` drops all three and the
+    // attributes of a Deployment or a Service are byte-for-byte what they were.
+    expect(revisionAttributes({ status: { readyReplicas: 1, replicas: 1 } } as never)).toEqual({
+      lastAppliedRevision: undefined,
+      lastAttemptedRevision: undefined,
+      artifactRevision: undefined,
+    });
+    expect(revisionAttributes({} as never)).toEqual({
+      lastAppliedRevision: undefined,
+      lastAttemptedRevision: undefined,
+      artifactRevision: undefined,
+    });
+  });
+
+  test("ignores non-string and empty revisions", () => {
+    expect(
+      revisionAttributes({ status: { lastAppliedRevision: "", lastAttemptedRevision: 7, artifact: { revision: null } } } as never),
+    ).toEqual({ lastAppliedRevision: undefined, lastAttemptedRevision: undefined, artifactRevision: undefined });
+  });
+});
+
+describe("observed attributes carry the Flux revisions (#1632)", () => {
+  const applied = "main@sha1:1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b";
+  const attempted = "main@sha1:5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d";
+
+  test("a Kustomization mid-rollout reports applied != attempted even with Ready=True", async () => {
+    const kustomization = {
+      apiVersion: "kustomize.toolkit.fluxcd.io/v1",
+      kind: "Kustomization",
+      metadata: { name: "apps", namespace: "flux-system", uid: "ks-uid", resourceVersion: "42" },
+      status: {
+        lastAppliedRevision: applied,
+        lastAttemptedRevision: attempted,
+        conditions: [{ type: "Ready", status: "True", reason: "ReconciliationSucceeded" }],
+      },
+    };
+    const source = {
+      apiVersion: "source.toolkit.fluxcd.io/v1",
+      kind: "GitRepository",
+      metadata: { name: "infra", namespace: "flux-system", uid: "gr-uid" },
+      status: {
+        artifact: { revision: attempted, path: "gitrepository/flux-system/infra/x.tar.gz" },
+        conditions: [{ type: "Ready", status: "True" }],
+      },
+    };
+    const cluster = fakeCluster({
+      objects: {
+        [objectKey("kustomize.toolkit.fluxcd.io/v1", "Kustomization", "apps", "flux-system")]: kustomization,
+        [objectKey("source.toolkit.fluxcd.io/v1", "GitRepository", "infra", "flux-system")]: source,
+      },
+    });
+
+    const result = await describeResources(
+      {
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["apps", "infra"],
+        entities: makeEntities([
+          {
+            name: "apps",
+            entityType: "K8s::Flux::Kustomization",
+            props: { metadata: { name: "apps", namespace: "flux-system" } },
+          },
+          {
+            name: "infra",
+            entityType: "K8s::Flux::GitRepository",
+            props: { metadata: { name: "infra", namespace: "flux-system" } },
+          },
+        ]),
+      },
+      cluster.connector,
+    );
+
+    // The per-node half: attempted is ahead of applied, so this object is
+    // mid-flight however cheerful its Ready condition is.
+    expect(result.resources.apps?.attributes).toMatchObject({
+      lastAppliedRevision: applied,
+      lastAttemptedRevision: attempted,
+    });
+    // The cross-node half: the source's artifact revision, which a consumer
+    // joins against the Kustomization's applied revision.
+    expect(result.resources.infra?.attributes).toMatchObject({ artifactRevision: attempted });
+    expect(result.resources.apps?.status).toBe("READY");
+  });
+
+  test("a HelmRelease's revisions ride the same path, and other kinds are untouched", async () => {
+    const helmRelease = {
+      apiVersion: "helm.toolkit.fluxcd.io/v2",
+      kind: "HelmRelease",
+      metadata: { name: "podinfo", namespace: "prod", uid: "hr-uid" },
+      status: { lastAppliedRevision: "6.5.4", lastAttemptedRevision: "6.5.4", conditions: [{ type: "Ready", status: "True" }] },
+    };
+    const cluster = fakeCluster({
+      objects: {
+        [objectKey("helm.toolkit.fluxcd.io/v2", "HelmRelease", "podinfo", "prod")]: helmRelease,
+        [objectKey("apps/v1", "Deployment", "web", "prod")]: web,
+      },
+    });
+
+    const result = await describeResources(
+      {
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["podinfo", "web"],
+        entities: makeEntities([
+          {
+            name: "podinfo",
+            entityType: "K8s::Flux::HelmRelease",
+            props: { metadata: { name: "podinfo", namespace: "prod" } },
+          },
+          { name: "web", entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web", namespace: "prod" } } },
+        ]),
+      },
+      cluster.connector,
+    );
+
+    expect(result.resources.podinfo?.attributes).toMatchObject({
+      lastAppliedRevision: "6.5.4",
+      lastAttemptedRevision: "6.5.4",
+    });
+    // The string wire form for every other kind is what it was — no empty
+    // revision keys appear on a Deployment (#1401's shape, unchanged).
+    expect(result.resources.web?.attributes).toEqual({
+      namespace: "prod",
+      labels: { app: "web" },
+      resourceVersion: "7",
+    });
+  });
+});
+
+// The behold#221 shape (#1629): the estate's control-plane project declares
+// the Kustomization carrying `spec.targetNamespace`, and the app project
+// declares bare objects the controller stamps at apply time. Reading the app
+// project alone, `metadata.namespace` is absent everywhere and the read
+// defaults to `default` — a running estate reported entirely absent. The
+// caller that knows the binding can now say where to look.
+describe("a per-read namespace override for entities that declare none (#1629)", () => {
+  const inAppB = {
+    apiVersion: "apps/v1",
+    kind: "Deployment",
+    metadata: { name: "web", namespace: "app-b", uid: "uid-b", resourceVersion: "11" },
+    status: { readyReplicas: 1, replicas: 1 },
+  };
+
+  test("replaces the `default` fallback for a namespaced entity that declares no namespace", async () => {
+    const cluster = fakeCluster({ objects: { [objectKey("apps/v1", "Deployment", "web", "app-b")]: inAppB } });
+    const result = await describeResources(
+      {
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["web"],
+        entities: makeEntities([
+          { name: "web", entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web" } } },
+        ]),
+        namespace: "app-b",
+      },
+      cluster.connector,
+    );
+
+    expect(result.resources.web).toMatchObject({ type: "K8s::Apps::Deployment", physicalId: "uid-b" });
+    // The `queried` diagnosis line (#1620) reflects the overridden address —
+    // whatever the read did, the report says where it looked.
+    expect(result.queried?.web).toBe("/apis/apps/v1/namespaces/app-b/deployments/web");
+  });
+
+  test("an explicitly declared namespace still wins — the override is a default, not a rewrite", async () => {
+    const cluster = fakeCluster({
+      objects: {
+        [objectKey("apps/v1", "Deployment", "web", "prod")]: web,
+        [objectKey("apps/v1", "Deployment", "web", "app-b")]: inAppB,
+      },
+    });
+    const result = await describeResources(
+      {
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["web"],
+        entities: makeEntities([
+          { name: "web", entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web", namespace: "prod" } } },
+        ]),
+        namespace: "app-b",
+      },
+      cluster.connector,
+    );
+
+    // Both objects exist; the declared namespace decides which one was read.
+    expect(result.resources.web).toMatchObject({ physicalId: "uid-1" });
+    expect(result.queried?.web).toBe("/apis/apps/v1/namespaces/prod/deployments/web");
+  });
+
+  test("without the override the read still defaults to `default` — nothing changed for a caller that passes none", async () => {
+    const cluster = fakeCluster({ objects: { [objectKey("apps/v1", "Deployment", "web", "app-b")]: inAppB } });
+    const result = await describeResources(
+      {
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["web"],
+        entities: makeEntities([
+          { name: "web", entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web" } } },
+        ]),
+      },
+      cluster.connector,
+    );
+
+    expect(result.resources).toEqual({});
+    expect(result.queried?.web).toBe("/apis/apps/v1/namespaces/default/deployments/web");
+  });
+
+  test("a cluster-scoped kind is untouched — it has no namespace to default", async () => {
+    const ns = { apiVersion: "v1", kind: "Namespace", metadata: { name: "app-b", uid: "ns-uid" } };
+    const cluster = fakeCluster({ objects: { [objectKey("v1", "Namespace", "app-b")]: ns } });
+    const result = await describeResources(
+      {
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["appB"],
+        entities: makeEntities([
+          { name: "appB", entityType: "K8s::Core::Namespace", props: { metadata: { name: "app-b" } } },
+        ]),
+        namespace: "app-b",
+      },
+      cluster.connector,
+    );
+
+    expect(result.resources.appB).toMatchObject({ physicalId: "ns-uid" });
+    expect(result.queried?.appB).toBe("/api/v1/namespaces/app-b");
+  });
+
+  test("the override reaches every declared entity, not just the first", async () => {
+    const svc = { apiVersion: "v1", kind: "Service", metadata: { name: "web-svc", namespace: "app-b", uid: "svc-b" } };
+    const cluster = fakeCluster({
+      objects: {
+        [objectKey("apps/v1", "Deployment", "web", "app-b")]: inAppB,
+        [objectKey("v1", "Service", "web-svc", "app-b")]: svc,
+      },
+    });
+    const result = await describeResources(
+      {
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["web", "webSvc"],
+        entities: makeEntities([
+          { name: "web", entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web" } } },
+          { name: "webSvc", entityType: "K8s::Core::Service", props: { metadata: { name: "web-svc" } } },
+        ]),
+        namespace: "app-b",
+      },
+      cluster.connector,
+    );
+
+    expect(Object.keys(result.resources).sort()).toEqual(["web", "webSvc"]);
+  });
+});

package/src/describe-resources.ts

@@ -233,6 +233,45 @@ export function unhappyConditions(obj: K8sObject): string[] | undefined {
   return out.length > 0 ? out : undefined;
 }
 
+/**
+ * The revisions a GitOps controller writes onto its own object (#1632).
+ *
+ * Conditions lag. A Flux Kustomization mid-rollout still reports the previous
+ * reconcile's `Ready=True` for as long as the new one takes, so a consumer
+ * reading only conditions calls a half-applied estate converged. The
+ * controller's own definition of converged is a revision comparison:
+ * `lastAppliedRevision` against `lastAttemptedRevision` on the same object
+ * (attempted-but-not-applied is in flight), and a Kustomization's
+ * `lastAppliedRevision` against its source's `artifact.revision` (the
+ * cross-object half, which a consumer joins once both ends are on the wire).
+ * None of the three reached an observed entity's attributes before this.
+ *
+ * Read by path rather than by kind, which is the module's standing rule
+ * everywhere else: `status.lastAppliedRevision` / `status.lastAttemptedRevision`
+ * are what kustomize-controller and helm-controller write, and
+ * `status.artifact.revision` is what every source kind (GitRepository,
+ * OCIRepository, Bucket, HelmChart) writes. An object that has none of them —
+ * every non-GitOps kind — contributes nothing, so no kind table has to name
+ * which kinds those are, and a CRD speaking the same convention is carried for
+ * free. `artifactRevision` flattens the one nested path so every revision on
+ * the wire is a plain string next to the others.
+ */
+export function revisionAttributes(obj: K8sObject): {
+  lastAppliedRevision?: string;
+  lastAttemptedRevision?: string;
+  artifactRevision?: string;
+} {
+  const status = obj.status as
+    | { lastAppliedRevision?: unknown; lastAttemptedRevision?: unknown; artifact?: { revision?: unknown } }
+    | undefined;
+  const str = (v: unknown): string | undefined => (typeof v === "string" && v.length > 0 ? v : undefined);
+  return {
+    lastAppliedRevision: str(status?.lastAppliedRevision),
+    lastAttemptedRevision: str(status?.lastAttemptedRevision),
+    artifactRevision: str(status?.artifact?.revision),
+  };
+}
+
 interface Declared {
   entityName: string;
   entityType: string;
@@ -247,6 +286,25 @@ export interface DescribeResourcesOptions {
   owned?: boolean;
   /** Directory whose `chant.config.ts` carries the cluster binding. Defaults to cwd. */
   cwd?: string;
+  /**
+   * Namespace to read a namespaced entity from when it declares none (#1629).
+   *
+   * A GitOps estate splits the binding from the objects: the control-plane
+   * project declares a Kustomization with `spec.targetNamespace: app-b`, the
+   * app project declares bare Deployments and Services with no
+   * `metadata.namespace` at all — the controller stamps it at apply time. The
+   * live read of the app project had no way to be told that, so it fell
+   * through to the client's `default` and reported an estate that is running
+   * as entirely absent (#1620's `queried` line is what made that visible).
+   *
+   * A DEFAULT, never a rewrite: an entity with an explicit
+   * `metadata.namespace` reads from the namespace it declares, override or
+   * not — that declaration is the estate's own statement of where the object
+   * lives, and overruling it would make the option a way to read the wrong
+   * object rather than the right one. Cluster-scoped kinds are untouched:
+   * they have no namespace to default.
+   */
+  namespace?: string;
 }
 
 export async function describeResources(
@@ -331,11 +389,17 @@ export async function describeResources(
       return;
     }
 
+    // The declared namespace wins; the caller's override only fills the hole a
+    // declaration left, and only for a kind that HAS a namespace (#1629). With
+    // neither, the client defaults to `default` exactly as it did.
+    const namespace =
+      metadata?.namespace ?? (operation.scope === "Namespaced" ? options.namespace : undefined);
+
     const ref = {
       apiVersion: operation.apiVersion,
       kind: operation.kind,
       name,
-      ...(metadata?.namespace ? { namespace: metadata.namespace } : {}),
+      ...(namespace ? { namespace } : {}),
     };
 
     // Resolve the address BEFORE the read, so every verdict below — present,
@@ -379,6 +443,9 @@ export async function describeResources(
           resourceVersion: obj.metadata?.resourceVersion,
           // What the object's own controller says is wrong with it (#1401).
           conditions: unhappyConditions(obj),
+          // What a GitOps controller says it has applied and is applying
+          // (#1632) — the convergence signal conditions cannot carry.
+          ...revisionAttributes(obj),
         }),
       };
     } catch (err) {