@intentius/chant 0.44.1 → 0.44.3

package/src/observation.test.ts

@@ -29,7 +29,7 @@ const meta = (over: Partial<ResourceMetadata> = {}): ResourceMetadata => ({
 
 describe("normalizeObservation", () => {
   test("a bare map means 'I looked at everything'", () => {
-    expect(normalizeObservation({ a: meta() })).toEqual({ resources: { a: meta() }, unobserved: {} });
+    expect(normalizeObservation({ a: meta() })).toEqual({ resources: { a: meta() }, unobserved: {}, queried: {} });
   });
 
   test("the envelope carries both halves", () => {
@@ -37,11 +37,27 @@ describe("normalizeObservation", () => {
     expect(normalizeObservation(value)).toEqual({
       resources: { a: meta() },
       unobserved: { b: { reason: "read-failed" } },
+      queried: {},
     });
   });
 
-  test("undefined normalizes to two empty maps", () => {
-    expect(normalizeObservation(undefined)).toEqual({ resources: {}, unobserved: {} });
+  test("undefined normalizes to empty maps", () => {
+    expect(normalizeObservation(undefined)).toEqual({ resources: {}, unobserved: {}, queried: {} });
+  });
+
+  test("the envelope carries the queried addresses through normalization (#1620)", () => {
+    const value = observation({}, {}, { web: "/apis/apps/v1/namespaces/default/deployments/web" });
+    expect(normalizeObservation(value).queried).toEqual({
+      web: "/apis/apps/v1/namespaces/default/deployments/web",
+    });
+    // Additive metadata only: an entity in `queried` and neither map is still
+    // OBSERVED-ABSENT — the tri-state does not shift.
+    expect(normalizeObservation(value).resources).toEqual({});
+    expect(normalizeObservation(value).unobserved).toEqual({});
+  });
+
+  test("the envelope omits an empty queried map (#1620)", () => {
+    expect(observation({ a: meta() }, {}, {})).toEqual({ observation: "v1", resources: { a: meta() } });
   });
 
   test("an entity literally named `observation` cannot be mistaken for the envelope", () => {
@@ -68,8 +84,8 @@ describe("unobservedAll", () => {
 describe("mergeObservations (multi-stack)", () => {
   test("present beats not-observed beats absent", () => {
     const merged = mergeObservations([
-      { resources: {}, unobserved: { a: { reason: "read-failed" }, b: { reason: "no-binding" } } },
-      { resources: { a: meta() }, unobserved: {} },
+      { resources: {}, unobserved: { a: { reason: "read-failed" }, b: { reason: "no-binding" } }, queried: {} },
+      { resources: { a: meta() }, unobserved: {}, queried: {} },
     ]);
     expect(Object.keys(merged.resources)).toEqual(["a"]);
     expect(Object.keys(merged.unobserved)).toEqual(["b"]);
@@ -77,11 +93,19 @@ describe("mergeObservations (multi-stack)", () => {
 
   test("an entity nobody looked for in any stack stays absent", () => {
     const merged = mergeObservations([
-      { resources: { a: meta() }, unobserved: {} },
-      { resources: { b: meta() }, unobserved: {} },
+      { resources: { a: meta() }, unobserved: {}, queried: {} },
+      { resources: { b: meta() }, unobserved: {}, queried: {} },
     ]);
     expect(merged.unobserved).toEqual({});
   });
+
+  test("queried addresses union across stacks (#1620)", () => {
+    const merged = mergeObservations([
+      { resources: {}, unobserved: {}, queried: { a: "stack-1/a" } },
+      { resources: { b: meta() }, unobserved: {}, queried: { b: "stack-2/b" } },
+    ]);
+    expect(merged.queried).toEqual({ a: "stack-1/a", b: "stack-2/b" });
+  });
 });
 
 describe("reason totality", () => {
@@ -98,6 +122,12 @@ describe("reason totality", () => {
       formatUnobserved("widget", { type: "K8s::X::Widget", reason: "unsupported-kind", detail: "no mapping" }),
     ).toBe("widget (K8s::X::Widget) — no reader for this resource kind: no mapping");
   });
+
+  test("formatUnobserved appends the queried address when the entry carries one (#1620)", () => {
+    expect(
+      formatUnobserved("web", { reason: "read-failed", detail: "HTTP 500", queried: "/apis/apps/v1/namespaces/default/deployments/web" }),
+    ).toBe("web — read failed: HTTP 500 [queried /apis/apps/v1/namespaces/default/deployments/web]");
+  });
 });
 
 describe("boundedConcurrently", () => {
@@ -163,6 +193,23 @@ describe("observeEntities harness (#1201)", () => {
     });
   });
 
+  test("collects the queried address from every variant — the absent one especially (#1620)", async () => {
+    const result = await observeEntities(
+      [entity("a"), entity("b"), entity("c")],
+      adapterOf({
+        a: { present: meta(), queried: "region-1/a" },
+        b: { absent: true, queried: "region-1/b" },
+        c: { unobserved: { reason: "read-failed", detail: "boom" }, queried: "region-1/c" },
+      }),
+    );
+    // The absent entity stays in neither map — additive metadata, tri-state unshifted.
+    expect(Object.keys(result.resources)).toEqual(["a"]);
+    expect(Object.keys(result.unobserved ?? {})).toEqual(["c"]);
+    expect(result.queried).toEqual({ a: "region-1/a", b: "region-1/b", c: "region-1/c" });
+    // The unobserved entry carries its own copy, so a row renders without a join.
+    expect(result.unobserved?.c.queried).toBe("region-1/c");
+  });
+
   test("a bind failure marks every entity NOT-OBSERVED with the typed reason and declared type", async () => {
     const result = await observeEntities(
       [entity("a", "AWS::S3::Bucket"), entity("b", "AWS::S3::Bucket")],

package/src/observation.ts

@@ -79,6 +79,14 @@ export interface UnobservedEntity {
   reason: UnobservedReason;
   /** Human-readable detail: the command that failed, the missing binding key, the unsupported kind. */
   detail?: string;
+  /**
+   * The resolved address the read was issued against (#1620) — for k8s the
+   * request path (`/apis/apps/v1/namespaces/default/deployments/web`), for
+   * other substrates whatever names the endpoint/region/account actually
+   * asked. Optional and purely diagnostic: it never changes the verdict, it
+   * lets a consumer tell "looked in the wrong place" from "not there".
+   */
+  queried?: string;
 }
 
 /**
@@ -92,6 +100,18 @@ export interface ObservationResult {
   resources: Record<string, ResourceMetadata>;
   /** NOT-OBSERVED, keyed by chant entity name. Omit or leave empty when everything asked about was looked at. */
   unobserved?: Record<string, UnobservedEntity>;
+  /**
+   * The resolved query address per declared entity (#1620), keyed by chant
+   * entity name — what was actually asked of the provider, whatever the
+   * verdict came back as. Additive metadata over the tri-state, never part of
+   * it: classification still reads only `resources` and `unobserved`, and an
+   * entity in neither map is still OBSERVED-ABSENT whether or not it appears
+   * here. This map is the only place an ABSENT entity can carry its address —
+   * absence is spelled "in neither map", so there is no row to hang it on —
+   * which is exactly the entry that lets a consumer see that a defaulted
+   * namespace, endpoint or region was read, not the one the resource lives in.
+   */
+  queried?: Record<string, string>;
 }
 
 /**
@@ -100,10 +120,12 @@ export interface ObservationResult {
  */
 export type DescribeResourcesResult = Record<string, ResourceMetadata> | ObservationResult;
 
-/** Normalized form every consumer works with. Both maps always present. */
+/** Normalized form every consumer works with. All maps always present. */
 export interface NormalizedObservation {
   resources: Record<string, ResourceMetadata>;
   unobserved: Record<string, UnobservedEntity>;
+  /** Resolved query address per entity name (#1620). Empty when the lexicon reported none. */
+  queried: Record<string, string>;
 }
 
 /** True when `value` is the versioned {@link ObservationResult} envelope. */
@@ -122,11 +144,13 @@ export function isObservationResult(value: unknown): value is ObservationResult
 export function observation(
   resources: Record<string, ResourceMetadata>,
   unobserved?: Record<string, UnobservedEntity>,
+  queried?: Record<string, string>,
 ): ObservationResult {
   return {
     observation: "v1",
     resources,
     ...(unobserved && Object.keys(unobserved).length > 0 ? { unobserved } : {}),
+    ...(queried && Object.keys(queried).length > 0 ? { queried } : {}),
   };
 }
 
@@ -137,11 +161,11 @@ export function observation(
  * {@link unobservedAll} rather than returning nothing.
  */
 export function normalizeObservation(value: DescribeResourcesResult | undefined): NormalizedObservation {
-  if (!value) return { resources: {}, unobserved: {} };
+  if (!value) return { resources: {}, unobserved: {}, queried: {} };
   if (isObservationResult(value)) {
-    return { resources: value.resources ?? {}, unobserved: value.unobserved ?? {} };
+    return { resources: value.resources ?? {}, unobserved: value.unobserved ?? {}, queried: value.queried ?? {} };
   }
-  return { resources: value, unobserved: {} };
+  return { resources: value, unobserved: {}, queried: {} };
 }
 
 /**
@@ -180,14 +204,16 @@ export function unobservedAll(
 export function mergeObservations(parts: Iterable<NormalizedObservation>): NormalizedObservation {
   const resources: Record<string, ResourceMetadata> = {};
   const unobserved: Record<string, UnobservedEntity> = {};
+  const queried: Record<string, string> = {};
   for (const part of parts) {
     Object.assign(resources, part.resources);
     Object.assign(unobserved, part.unobserved);
+    Object.assign(queried, part.queried);
   }
   // Present wins: a stack that could not be read does not un-observe a resource
   // another stack returned.
   for (const name of Object.keys(resources)) delete unobserved[name];
-  return { resources, unobserved };
+  return { resources, unobserved, queried };
 }
 
 /** One-line human phrasing of a reason, for CLI output. */
@@ -206,10 +232,11 @@ export function unobservedReasonText(reason: UnobservedReason): string {
   }
 }
 
-/** `name — reason (detail)`, the shared rendering for CLI and plan output. */
+/** `name — reason (detail) [queried address]`, the shared rendering for CLI and plan output. */
 export function formatUnobserved(name: string, entry: UnobservedEntity): string {
   const base = `${name}${entry.type ? ` (${entry.type})` : ""} — ${unobservedReasonText(entry.reason)}`;
-  return entry.detail ? `${base}: ${entry.detail}` : base;
+  const detailed = entry.detail ? `${base}: ${entry.detail}` : base;
+  return entry.queried ? `${detailed} [queried ${entry.queried}]` : detailed;
 }
 
 /* ------------------------------------------------------------------------- *
@@ -246,11 +273,16 @@ export interface DeclaredEntity {
  * - `present` — a key in `resources`.
  * - `absent` — in neither map (the provider was asked and reported it missing).
  * - `unobserved` — a typed NOT-OBSERVED (unsupported kind, filtered, read error).
+ *
+ * Every variant may carry `queried` (#1620): the resolved address the read was
+ * issued against. The harness collects it into the result's `queried` map (and
+ * onto the unobserved entry), so even an absent verdict — which records
+ * nothing else — says where the provider was asked.
  */
 export type EntityObservation =
-  | { present: ResourceMetadata }
-  | { absent: true }
-  | { unobserved: { reason: UnobservedReason; detail?: string } };
+  | { present: ResourceMetadata; queried?: string }
+  | { absent: true; queried?: string }
+  | { unobserved: { reason: UnobservedReason; detail?: string }; queried?: string };
 
 /** What a lexicon supplies to drive the harness. `Client` is its transport handle. */
 export interface ObserverAdapter<Client> {
@@ -338,6 +370,7 @@ export async function observeEntities<Client>(
 
   const resources: Record<string, ResourceMetadata> = {};
   const unobserved: Record<string, UnobservedEntity> = {};
+  const queried: Record<string, string> = {};
   const run = adapter.concurrently ?? ((items, fn) => boundedConcurrently(items, fn));
 
   await run(declared, async (entity) => {
@@ -352,13 +385,20 @@ export async function observeEntities<Client>(
         },
       };
     }
+    if (result.queried) queried[entity.name] = result.queried;
     if ("present" in result) {
       resources[entity.name] = result.present;
     } else if ("unobserved" in result) {
-      unobserved[entity.name] = { type: entity.type, ...result.unobserved };
+      unobserved[entity.name] = {
+        type: entity.type,
+        ...result.unobserved,
+        ...(result.queried ? { queried: result.queried } : {}),
+      };
     }
-    // `absent`: record nothing — in neither map is how the contract spells absence.
+    // `absent`: the verdict records nothing — in neither map is how the
+    // contract spells absence — but its address, when the adapter supplied
+    // one, lands in `queried` (#1620) so the absence can explain itself.
   });
 
-  return observation(resources, unobserved);
+  return observation(resources, unobserved, queried);
 }

package/src/reconcile.ts

@@ -7,7 +7,7 @@
  * the plan renderer, and the guardrail framework (rename resolution + a removal
  * cap + a pluggable check runner).
  *
- * A "warden" (e.g. github-warden) builds its provider-specific resource diffing,
+ * A consumer application (e.g. github-warden) builds its provider-specific resource diffing,
  * live-state types, and domain guardrails on top of this, and drives them with
  * the generic `runReconcile` loop + `Cycle` interface (below). It complements
  * chant's `ownership.ts` marker contract: ownership markers make a `delete`
@@ -41,7 +41,7 @@ export interface ChangeSetEntry {
   /** High-level resource category (e.g. "team", "member", "branch-protection"). */
   resourceType: string;
   /**
-   * Cross-provider governance category (#790). `resourceType` stays the
+   * Cross-provider governance category. `resourceType` stays the
    * provider-specific display string; the verb is the shared grammar SCM and
    * cloud plans group by. Stamped by `runReconcile` from the cycle's `verb`.
    */
@@ -221,7 +221,7 @@ export function renderChangeSet(cs: ChangeSet): string {
   for (const kind of ORDER) {
     let group = byKind[kind];
     if (group.length === 0) continue;
-    // Verb-aware grouping (#790): when entries carry governance verbs, order
+    // Verb-aware grouping: when entries carry governance verbs, order
     // each section by verb (vocabulary order, unverbed entries last) so mixed
     // plans read category-by-category. Stable, and line format is unchanged —
     // a verbless change set renders exactly as before.
@@ -417,8 +417,8 @@ export interface Cycle<TClient, TConfig, TLive, TScope = unknown> {
   /** Human-readable name, e.g. "branch-protection". */
   name: string;
   /**
-   * Cross-provider governance category this cycle reconciles (#790). Every
-   * SCM warden cycle stamps one; cloud cycles (epic #787 C2) must. Optional
+   * Cross-provider governance category this cycle reconciles. Every
+   * SCM reconciler cycles stamp one; cloud cycles must. Optional
    * only so provider-external Cycle implementations don't break.
    */
   verb?: GovernanceVerb;
@@ -436,7 +436,7 @@ export interface Cycle<TClient, TConfig, TLive, TScope = unknown> {
 /** Per-cycle outcome recorded in the run result. */
 export interface CycleResult {
   name: string;
-  /** The cycle's governance verb (#790), when it stamps one. */
+  /** The cycle's governance verb, when it stamps one. */
   verb?: GovernanceVerb;
   /** Scope id this result is for (e.g. an org login). */
   org: string;
@@ -560,7 +560,7 @@ export async function runReconcile<TClient, TConfig, TLive, TScope = unknown>(
       }
 
       const changeSet = diffFn(scopeId, desired, live, diffOptions);
-      // Stamp the cycle's governance verb (#790) onto entries that don't
+      // Stamp the cycle's governance verb onto entries that don't
       // carry one, so provider diffs stay verb-unaware.
       if (cycle.verb) {
         for (const e of changeSet.entries) e.verb ??= cycle.verb;