@intentius/chant-lexicon-k8s 0.57.0 → 0.59.0

package/src/deep-observe.test.ts

@@ -36,6 +36,7 @@ const { statusBody } = await import("@intentius/chant-k8s-client/testing");
 const { isChantFieldManager } = await import("@intentius/chant-k8s-client");
 const { diffDeepObservation, observeDeep } = await import("@intentius/chant/lifecycle/deep-observe");
 const { normalizeDeepObservation, normalizeDeepProperties } = await import("@intentius/chant/deep-observation");
+const { heldElsewhere } = await import("@intentius/chant/held-elsewhere");
 
 type Entity = { name: string; entityType: string; props: Record<string, unknown> };
 function makeEntities(records: Entity[]): Map<string, { entityType: string; props: Record<string, unknown> }> {
@@ -687,19 +688,20 @@ describe("end to end: managed-fields-derived drift (#1076)", () => {
     },
   };
 
-  test("genuine, undeclared and contested drift surface; accepted deviations and controller-stamped metadata do not", async () => {
+  test("contested drift surfaces; fields nobody declared are unclaimed and accepted deviations are held back", async () => {
     const live = normalizeDeepObservation(
       await observeResourcesDeepK8s({ environment: "prod", entityNames: [...declared.keys()], entities: declared }, cluster().connector),
     );
     const result = diffDeepObservation(declared, live, k8sDeepNormalizationHooks, baseline);
 
+    // Only a path chant's source declares can be drift (#2160). `tier` is
+    // declared and holds a different value live, which is the whole point of
+    // the contested case: a foreign write over a field chant asks for.
     expect(result.drifted).toEqual([
       {
         name: "web",
         type: "K8s::Apps::Deployment",
         changes: [
-          // The #1191 case: foreign-owned, undeclared, not accepted — and the owner says who.
-          { path: "metadata.labels.team", kind: "undeclared", live: "platform", owner: "kubectl-edit" },
           { path: "metadata.labels.tier", kind: "changed", declared: "backend", live: "frontend", owner: "chant:web" },
         ],
       },
@@ -710,16 +712,39 @@ describe("end to end: managed-fields-derived drift (#1076)", () => {
       },
     ]);
 
-    // The accepted HPA replicas and sidecar are held back, not hidden.
+    // Everything source never set, with the manager where managedFields has one
+    // and the claim where it does not. The `team` label needs no baseline entry
+    // to stay quiet now, and `kubectl-edit` still says who put it there.
+    expect(result.unclaimed).toEqual([
+      {
+        name: "web",
+        type: "K8s::Apps::Deployment",
+        fields: [
+          { path: "metadata.labels.team", live: "platform", heldBy: "kubectl-edit", source: "field-manager" },
+          { path: "spec.replicas", live: 7, heldBy: "kube-controller-manager", source: "field-manager", baseline: 7 },
+          {
+            path: "spec.template.spec.containers[#istio-proxy].image",
+            live: "istio/proxyv2:1.20",
+            source: "claimed-fields",
+            baseline: "istio/proxyv2:1.20",
+          },
+          {
+            path: "spec.template.spec.containers[#istio-proxy].name",
+            live: "istio-proxy",
+            source: "claimed-fields",
+            baseline: "istio-proxy",
+          },
+        ],
+      },
+    ]);
+
+    // The accepted build-id is held back, not hidden.
     expect(result.accepted).toEqual([
       {
         name: "web",
         type: "K8s::Apps::Deployment",
         changes: [
           { path: "metadata.annotations.build-id", kind: "changed", declared: "42", live: "43", baseline: "43", owner: "chant:web" },
-          { path: "spec.replicas", kind: "undeclared", live: 7, baseline: 7, owner: "kube-controller-manager" },
-          { path: "spec.template.spec.containers[#istio-proxy].image", kind: "undeclared", live: "istio/proxyv2:1.20", baseline: "istio/proxyv2:1.20" },
-          { path: "spec.template.spec.containers[#istio-proxy].name", kind: "undeclared", live: "istio-proxy", baseline: "istio-proxy" },
         ],
       },
     ]);
@@ -739,7 +764,10 @@ describe("end to end: managed-fields-derived drift (#1076)", () => {
     ]);
   });
 
-  test("without the baseline every foreign-owned undeclared field is drift too; accepting is what silences it", async () => {
+  test("without the baseline only the declared paths are drift; the rest are still unclaimed", async () => {
+    // The baseline was the noise valve before #2160. It is no longer load
+    // bearing for a field nobody declared: the claim answers first, so an HPA's
+    // replica count and an injected sidecar are quiet with no baseline at all.
     const live = normalizeDeepObservation(
       await observeResourcesDeepK8s({ environment: "prod", entityNames: [...declared.keys()], entities: declared }, cluster().connector),
     );
@@ -747,8 +775,10 @@ describe("end to end: managed-fields-derived drift (#1076)", () => {
     const web = result.drifted.find((d) => d.name === "web");
     expect(web?.changes.map((c) => c.path).sort()).toEqual([
       "metadata.annotations.build-id",
-      "metadata.labels.team",
       "metadata.labels.tier",
+    ]);
+    expect(result.unclaimed.find((d) => d.name === "web")?.fields.map((f) => f.path)).toEqual([
+      "metadata.labels.team",
       "spec.replicas",
       "spec.template.spec.containers[#istio-proxy].image",
       "spec.template.spec.containers[#istio-proxy].name",
@@ -756,38 +786,40 @@ describe("end to end: managed-fields-derived drift (#1076)", () => {
     expect(result.accepted).toEqual([]);
   });
 
-  test("the same out-of-band label in the accepted baseline is not drift, at that value (#1191)", async () => {
+  test("managedFields names the manager where it has one, and the claim answers where it does not (#2160)", async () => {
+    // The k8s row is the only substrate where both sources are available, so
+    // it is the one place the fallback can be tested against real data. The
+    // `team` label has a managedFields entry addressed by a plain path, so the
+    // API server answers. The injected sidecar's fields are inside a list the
+    // diff addresses by key (`[#istio-proxy]`), which no managedFields entry
+    // names in that form, so the claimed-field set answers instead.
     const live = normalizeDeepObservation(
       await observeResourcesDeepK8s({ environment: "prod", entityNames: [...declared.keys()], entities: declared }, cluster().connector),
     );
-    const withTeam = {
-      web: { ...baseline.web, accepted: [...baseline.web.accepted, { path: "metadata.labels.team", value: "platform" }] },
-    };
-    const result = diffDeepObservation(declared, live, k8sDeepNormalizationHooks, withTeam);
-    const web = result.drifted.find((d) => d.name === "web");
-    expect(web?.changes).toEqual([
-      { path: "metadata.labels.tier", kind: "changed", declared: "backend", live: "frontend", owner: "chant:web" },
-    ]);
-    expect(result.accepted.find((d) => d.name === "web")?.changes).toContainEqual({
+    const result = diffDeepObservation(declared, live, k8sDeepNormalizationHooks);
+    const web = result.unclaimed.find((d) => d.name === "web");
+
+    const byManager = web?.fields.find((f) => f.path === "metadata.labels.team");
+    expect(byManager).toEqual({
       path: "metadata.labels.team",
-      kind: "undeclared",
       live: "platform",
-      baseline: "platform",
-      owner: "kubectl-edit",
+      heldBy: "kubectl-edit",
+      source: "field-manager",
     });
 
-    // Value-bound: accepting `team=platform` does not bless `team=security`.
-    const moved = {
-      web: { ...baseline.web, accepted: [...baseline.web.accepted, { path: "metadata.labels.team", value: "security" }] },
-    };
-    const movedResult = diffDeepObservation(declared, live, k8sDeepNormalizationHooks, moved);
-    expect(movedResult.drifted.find((d) => d.name === "web")?.changes).toContainEqual({
-      path: "metadata.labels.team",
-      kind: "undeclared",
-      live: "platform",
-      baseline: "security",
-      owner: "kubectl-edit",
+    const byClaim = web?.fields.find((f) => f.path === "spec.template.spec.containers[#istio-proxy].image");
+    expect(byClaim).toEqual({
+      path: "spec.template.spec.containers[#istio-proxy].image",
+      live: "istio/proxyv2:1.20",
+      source: "claimed-fields",
     });
+    expect(byClaim).not.toHaveProperty("heldBy");
+
+    // Both sources agree on the verdict; they differ only in how much they can
+    // say about it. Neither is drift, and neither is proposed for update.
+    expect(result.drifted.find((d) => d.name === "web")?.changes.map((c) => c.path)).not.toContain(
+      "metadata.labels.team",
+    );
   });
 
   test("a whole-lexicon failure (no client) is a hole for every declared entity, never a clean report", async () => {
@@ -814,6 +846,142 @@ describe("end to end: managed-fields-derived drift (#1076)", () => {
   });
 });
 
+/**
+ * #2162's honest example, driven through the real reader and core's real
+ * `diffDeepObservation` the same way the "end to end" suite above does — the
+ * declared alternative to the `accepted` baseline dance that suite's own
+ * `web` fixture needs for the very same field: an HPA owns `spec.replicas`
+ * on a Deployment source never sets a literal value for. Before this, the
+ * only way to stop hearing about it was `--update-baseline`, and a later
+ * scale event (7 -> 12) reported as drift again the moment the accepted
+ * value moved. `heldElsewhere()` needs no baseline entry at all, and does
+ * not re-alert when the HPA changes its mind.
+ */
+describe("heldElsewhere(): the HPA/replicas case without a baseline entry (#2162)", () => {
+  const declared = makeEntities([
+    {
+      name: "web",
+      entityType: "K8s::Apps::Deployment",
+      props: {
+        metadata: { name: "web", namespace: "prod", labels: { app: "web" } },
+        spec: {
+          replicas: heldElsewhere<number>({ by: "hpa", reason: "the autoscaler owns replicas after the first apply" }),
+          selector: { matchLabels: { app: "web" } },
+          template: { metadata: { labels: { app: "web" } }, spec: { containers: [{ name: "app", image: "web:1.0" }] } },
+        },
+      },
+    },
+  ]);
+
+  const webLiveAt = (replicas: number) => ({
+    apiVersion: "apps/v1",
+    kind: "Deployment",
+    metadata: {
+      name: "web",
+      namespace: "prod",
+      uid: "uid-web",
+      labels: { app: "web" },
+      managedFields: [
+        {
+          manager: "chant:web",
+          operation: "Apply",
+          apiVersion: "apps/v1",
+          fieldsV1: {
+            "f:metadata": { "f:labels": { "f:app": {} } },
+            "f:spec": {
+              "f:selector": {},
+              "f:template": {
+                "f:spec": { "f:containers": { 'k:{"name":"app"}': { ".": {}, "f:name": {}, "f:image": {} } } },
+              },
+            },
+          },
+        },
+        {
+          // The autoscaler: chant's own manifest never mentions `replicas`,
+          // so nothing here contests it — the HPA is the only writer.
+          manager: "kube-controller-manager",
+          operation: "Update",
+          apiVersion: "apps/v1",
+          fieldsV1: { "f:spec": { "f:replicas": {} } },
+        },
+      ],
+    },
+    spec: {
+      replicas,
+      selector: { matchLabels: { app: "web" } },
+      template: { metadata: { labels: { app: "web" } }, spec: { containers: [{ name: "app", image: "web:1.0" }] } },
+    },
+  });
+
+  const clusterAt = (replicas: number) =>
+    fakeCluster({ objects: { [objectKey("apps/v1", "Deployment", "web", "prod")]: webLiveAt(replicas) } });
+
+  test("reports held with the HPA as owner — no drift, no baseline entry needed", async () => {
+    const live = normalizeDeepObservation(
+      await observeResourcesDeepK8s({ environment: "prod", entityNames: [...declared.keys()], entities: declared }, clusterAt(7).connector),
+    );
+    const result = diffDeepObservation(declared, live, k8sDeepNormalizationHooks);
+
+    expect(result.drifted).toEqual([]);
+    expect(result.accepted).toEqual([]);
+    expect(result.held).toEqual([
+      {
+        name: "web",
+        type: "K8s::Apps::Deployment",
+        held: [
+          {
+            path: "spec.replicas",
+            by: "hpa",
+            reason: "the autoscaler owns replicas after the first apply",
+            live: 7,
+            suspicious: false,
+            owner: "kube-controller-manager",
+          },
+        ],
+      },
+    ]);
+  });
+
+  test("a later scale event does not re-alert — unlike the accepted baseline, held is not value-bound", async () => {
+    const live = normalizeDeepObservation(
+      await observeResourcesDeepK8s({ environment: "prod", entityNames: [...declared.keys()], entities: declared }, clusterAt(12).connector),
+    );
+    const result = diffDeepObservation(declared, live, k8sDeepNormalizationHooks);
+
+    expect(result.drifted).toEqual([]);
+    expect(result.held[0].held[0]).toMatchObject({ live: 12, suspicious: false });
+  });
+
+  test("no live value at all is suspicious — the declared hand-over never showed up", async () => {
+    // No managedFields entry for replicas, and the live object carries none
+    // either — a Deployment where the HPA was never actually wired up.
+    const neverScaled = {
+      apiVersion: "apps/v1",
+      kind: "Deployment",
+      metadata: { name: "web", namespace: "prod", uid: "uid-web", labels: { app: "web" } },
+      spec: {
+        selector: { matchLabels: { app: "web" } },
+        template: { metadata: { labels: { app: "web" } }, spec: { containers: [{ name: "app", image: "web:1.0" }] } },
+      },
+    };
+    const live = normalizeDeepObservation(
+      await observeResourcesDeepK8s(
+        { environment: "prod", entityNames: [...declared.keys()], entities: declared },
+        fakeCluster({ objects: { [objectKey("apps/v1", "Deployment", "web", "prod")]: neverScaled } }).connector,
+      ),
+    );
+    const result = diffDeepObservation(declared, live, k8sDeepNormalizationHooks);
+
+    expect(result.held).toEqual([
+      {
+        name: "web",
+        type: "K8s::Apps::Deployment",
+        held: [{ path: "spec.replicas", by: "hpa", reason: "the autoscaler owns replicas after the first apply", suspicious: true }],
+      },
+    ]);
+  });
+});
+
 /**
  * The managed-fields case named in #1076's acceptance, re-decided by #1191:
  * the same live mutation on the same field is `changed` when chant owns it
@@ -873,27 +1041,29 @@ describe("the managed-fields twist: ownership names the writer, the declared tre
     ]);
   });
 
-  test("a controller owns the field and source is silent: the same mutated value is undeclared drift until accepted (#1191)", async () => {
+  test("a controller owns the field and source is silent: the same mutated value is unclaimed, never drift (#2160)", async () => {
+    // The mirror of the test above, and the whole claim in one pair: the same
+    // live value, the same manager, and the declaration is what decides
+    // whether it is chant's problem.
     const cluster = fakeCluster({ objects: { [objectKey("apps/v1", "Deployment", "app", "prod")]: liveWith("controller") } });
     const entities = declaredWith(false);
     const live = normalizeDeepObservation(
       await observeResourcesDeepK8s({ environment: "prod", entityNames: ["app"], entities }, cluster.connector),
     );
     const result = diffDeepObservation(entities, live, k8sDeepNormalizationHooks);
-    expect(result.drifted).toEqual([
+    expect(result.drifted).toEqual([]);
+    expect(result.unclaimed).toEqual([
       {
         name: "app",
         type: "K8s::Apps::Deployment",
-        changes: [{ path: "spec.template.spec.containers[#app].image", kind: "undeclared", live: "app:2.0" }],
+        fields: [
+          { path: "spec.template.spec.containers[#app].image", live: "app:2.0", source: "claimed-fields" },
+        ],
       },
     ]);
-
-    const accepted = {
-      app: { accepted: [{ path: "spec.template.spec.containers[#app].image", value: "app:2.0" }] },
-    };
-    const quiet = diffDeepObservation(entities, live, k8sDeepNormalizationHooks, accepted);
-    expect(quiet.drifted).toEqual([]);
-    expect(quiet.accepted.map((d) => d.name)).toEqual(["app"]);
+    // No baseline entry needed to silence it, which is what #1191's valve was
+    // being used for.
+    expect(result.unchanged).toEqual(["app"]);
   });
 });
 
@@ -954,9 +1124,12 @@ describe("secret masking — diff --live never holds a Secret data value (#1830,
     // MASTER_KEY is present on both sides: both values collapse to the mask,
     // so a value-only difference is NOT drift — that is the contract, chant
     // cannot know and must not learn whether the bytes moved.
-    expect(changes.map((c) => `${c.path}:${c.kind}`).sort()).toEqual([
-      "data.INJECTED_KEY:undeclared",
-      "data.PENDING_KEY:absent",
+    expect(changes.map((c) => `${c.path}:${c.kind}`).sort()).toEqual(["data.PENDING_KEY:absent"]);
+
+    // The injected key is a key source never declared, so it is unclaimed
+    // (#2160). Presence still classifies; the value is still the mask.
+    expect(result.unclaimed.find((d) => d.name === "master-key")?.fields).toEqual([
+      { path: "data.INJECTED_KEY", live: "[REDACTED]", source: "claimed-fields" },
     ]);
 
     // The hard line, asserted over the whole serialized result: no data

package/src/deep-observe.ts

@@ -9,10 +9,10 @@
  *
  * ## What managedFields decides, and what it does not
  *
- * AWS, Azure and Temporal's rows all prune by a **static, entityType-keyed**
- * table: an ARN always looks like an ARN, `provisioningState` is always
- * server-populated, a namespace's retention default is always the same
- * value. None of that needs the specific live object in hand — it is exactly
+ * The AWS and Azure rows both prune by a **static, entityType-keyed** table
+ * (`AWS_SERVICE_DEFAULTS`, `AZURE_SERVICE_DEFAULTS`): an ARN always looks like
+ * an ARN, `provisioningState` is always server-populated. Neither needs the
+ * specific live object in hand — it is exactly
  * what `./deep-observe-hooks.ts`'s `k8sDeepNormalizationHooks` is, and it
  * covers Kubernetes' *equivalent* static noise (`status`,
  * `metadata.{uid,resourceVersion,generation,creationTimestamp}`, a handful of
@@ -31,7 +31,7 @@
  * was controller noise. It silenced exactly the case the deep read exists
  * for — `kubectl label deploy web team=platform` is foreign-owned
  * (`kubectl-edit`) and undeclared, and never appeared in fieldDrift. The
- * policy now (recorded on #1202) is:
+ * policy now (recorded on #1202, refined by #2160) is:
  *
  * 1. **Chant-owned** (`chant`, `chant:<stack>` — chant #1075, matched on the
  *    family so a stack rename does not stop recognizing its own history) is
@@ -41,18 +41,25 @@
  *    write currently holds the field, and a foreign write that overrides a
  *    value chant's manifest asks for is the thing `lifecycle diff --live`
  *    exists to surface. It reports as `changed`.
- * 3. **Foreign-owned and undeclared** is reported as `undeclared` drift,
- *    unless the accepted baseline already carries it at that value. The
- *    baseline (`--update-baseline`) is the noise valve: an HPA that owns
- *    `spec.replicas` on a Deployment whose source is silent about replicas
- *    reports once, gets accepted, and stays quiet until the value moves.
+ * 3. **Undeclared** — a path outside the declaration's claimed-field set
+ *    (`@intentius/chant/claimed-fields`) — is reported as unclaimed and
+ *    is not drift at all. Before #2160 it was `undeclared` drift that the
+ *    accepted baseline had to absorb one path at a time; the declaration
+ *    answers on the first read instead, so an HPA that owns `spec.replicas`
+ *    on a Deployment whose source is silent about replicas is quiet with
+ *    nothing recorded anywhere.
  *
- * So ownership decides nothing about *whether* a path is compared. What it
- * contributes is `fieldOwners` (#1189): every reported drift names the
- * manager that holds the field live, which is how an operator tells
- * `hpa-controller` doing its job from somebody running `kubectl edit`. The
- * only fields subtracted because a foreign manager wrote them are the
- * well-known system ones on the static allowlist.
+ * So ownership decides nothing about *whether* a path is compared, and since
+ * #2160 it no longer decides the verdict either — the declaration does. What
+ * it contributes is `fieldOwners` (#1189), and that is worth more here than
+ * anywhere else: on every other substrate a held field can only be reported
+ * as "not chant's", while here it is reported as `hpa-controller`'s or
+ * `kubectl-edit`'s by name, which is the difference between a controller
+ * doing its job and somebody bypassing the pipeline. Core takes the manager
+ * where this reader supplies one and falls back to the claim where it does
+ * not (a path inside a key-addressed list, which no `fieldsV1` entry names in
+ * that form). The only fields subtracted because a foreign manager wrote them
+ * are the well-known system ones on the static allowlist.
  *
  * ## Resolving a managedFields entry against a live array
  *
@@ -111,10 +118,11 @@ import {
 } from "./api/classify";
 import { operationFor } from "./api/operation-surface";
 import { k8sDeepNormalizationHooks } from "./deep-observe-hooks";
+import { observeReceiptRowsDeep, receiptRowsFor } from "./receipt-store";
 
 // Re-exported so a dynamic importer of this module (plugin.ts's
 // `observeResourcesDeep`, a test) can get the reader and its hooks from one
-// place, the same shape AWS/Azure/Temporal's single deep-observe.ts offers.
+// place, the same shape the AWS and Azure deep-observe.ts modules offer.
 // `plugin.ts`'s own `deepNormalizationHooks` field imports the hooks
 // separately, directly from `./deep-observe-hooks` — that file has no
 // dependency on `@intentius/chant-k8s-client`, so it is safe to import
@@ -152,11 +160,23 @@ export async function observeResourcesDeepK8s(
 ): Promise<DeepObservationResult> {
   const { managedFieldsOf, isChantFieldManager } = await import("@intentius/chant-k8s-client");
 
-  const declared = [...options.entities].map(([entityName, entity]) => ({
-    entityName,
-    entityType: entity.entityType,
-    props: entity.props,
-  }));
+  // Effect receipts (#2074) are read by their own leg at the end: they carry
+  // no declared props, so every live path would be an unclaimed field (#2160)
+  // and their staleness is an `effect` row from the plan (#1832), never
+  // property drift. Reading them here keeps the deep read from calling a
+  // declared entity a hole; contributing an empty tree keeps it from calling
+  // one drift.
+  const receiptRows = receiptRowsFor(options.entityNames, options.buildOutput);
+
+  const declared = [...options.entities]
+    .filter(([entityName]) => !receiptRows.has(entityName))
+    .map(([entityName, entity]) => ({
+      entityName,
+      entityType: entity.entityType,
+      props: entity.props,
+    }));
+
+  const everyName = [...declared.map((d) => d.entityName), ...receiptRows.keys()];
 
   let client;
   try {
@@ -166,7 +186,7 @@ export async function observeResourcesDeepK8s(
       return deepObservation(
         {},
         unobservedAll(
-          declared.map((d) => d.entityName),
+          everyName,
           "read-failed",
           MISSING_CLIENT_DETAIL,
           options.entities,
@@ -178,7 +198,7 @@ export async function observeResourcesDeepK8s(
       return deepObservation(
         {},
         unobservedAll(
-          declared.map((d) => d.entityName),
+          everyName,
           outcome.kind === "unobserved" ? outcome.reason : "read-failed",
           outcome.kind === "unobserved" ? outcome.detail : undefined,
           options.entities,
@@ -244,10 +264,10 @@ export async function observeResourcesDeepK8s(
           hooks: k8sDeepNormalizationHooks,
         }),
         // Who owns each path (#1189). Nothing is pruned by ownership any more
-        // (#1191), so a foreign-owned undeclared field reaches the diff as
-        // `undeclared` — and naming the manager is the whole question there:
-        // an operator needs to tell `hpa-controller` doing its job from
-        // somebody running `kubectl edit`.
+        // (#1191), so a foreign-owned undeclared field still reaches the diff
+        // — as a held field since #2160 — and naming the manager is the whole
+        // question there: an operator needs to tell `hpa-controller` doing its
+        // job from somebody running `kubectl edit`.
         ...(sets.owners.size > 0 ? { fieldOwners: Object.fromEntries(sets.owners) } : {}),
       };
     } catch (err) {
@@ -260,5 +280,11 @@ export async function observeResourcesDeepK8s(
     }
   });
 
+  if (receiptRows.size > 0) {
+    const receiptObs = await observeReceiptRowsDeep(client, receiptRows);
+    Object.assign(resources, receiptObs.resources);
+    Object.assign(unobserved, receiptObs.unobserved);
+  }
+
   return deepObservation(resources, unobserved);
 }

package/src/describe-resources.ts

@@ -68,6 +68,7 @@ import {
 import { operationFor } from "./api/operation-surface";
 import { resolveK8sOwnerChain } from "./api/owner-chain";
 import { gvkToTypeName } from "./spec/parse";
+import { observeReceiptRows, receiptRowsFor } from "./receipt-store";
 
 function pruneUndefined<T extends Record<string, unknown>>(obj: T): Record<string, unknown> {
   const out: Record<string, unknown> = {};
@@ -357,11 +358,26 @@ export async function describeResources(
   // looked for where it lives".
   const queried: Record<string, string> = {};
 
-  const declared: Declared[] = [...options.entities].map(([entityName, entity]) => ({
-    entityName,
-    entityType: entity.entityType,
-    props: entity.props,
-  }));
+  // Effect receipt rows (#2074) are read by their own leg below: the applier
+  // never wrote them (#1832), and their declaration carries no props, so the
+  // generic sweep has no `metadata.name` to query by and would report a hole
+  // where the receipt leg has a real answer. Their addresses come from the
+  // build output's receipt comment, which is the serializer's one rendering of
+  // the derivation (./effect-receipt-row.ts).
+  const receiptRows = receiptRowsFor(options.entityNames, options.buildOutput);
+
+  const declared: Declared[] = [...options.entities]
+    .filter(([entityName]) => !receiptRows.has(entityName))
+    .map(([entityName, entity]) => ({
+      entityName,
+      entityType: entity.entityType,
+      props: entity.props,
+    }));
+
+  // A whole-lexicon failure below is a hole for the receipts too: nobody
+  // looked at those either, and a connect that never happened proves nothing
+  // about a receipt's presence.
+  const everyName = [...declared.map((d) => d.entityName), ...receiptRows.keys()];
 
   // Connect first. The binding check lives here, so a bound-but-mismatched
   // context throws before any resource is read — core turns that into
@@ -374,7 +390,7 @@ export async function describeResources(
       return observation(
         {},
         unobservedAll(
-          declared.map((d) => d.entityName),
+          everyName,
           "read-failed",
           MISSING_CLIENT_DETAIL,
           options.entities,
@@ -386,7 +402,7 @@ export async function describeResources(
       return observation(
         {},
         unobservedAll(
-          declared.map((d) => d.entityName),
+          everyName,
           outcome.kind === "unobserved" ? outcome.reason : "read-failed",
           outcome.kind === "unobserved" ? outcome.detail : undefined,
           options.entities,
@@ -507,6 +523,14 @@ export async function describeResources(
 
   await addRuntimeChildren(client, resources, unobserved, options.owned, declared);
 
+  // The receipt leg last, so its answers are the ones that stand for the
+  // receipt entities, because nothing above ever looked at one.
+  if (receiptRows.size > 0) {
+    const receiptObs = await observeReceiptRows(client, receiptRows);
+    Object.assign(resources, receiptObs.resources);
+    Object.assign(unobserved, receiptObs.unobserved);
+  }
+
   return observation(resources, unobserved, queried);
 }