@intentius/chant 0.124.45 → 0.124.46

package/src/graph-ir.ts

@@ -5,9 +5,12 @@ import { type Declarable, isDeclarable } from "./declarable";
 import { isLexiconOutput, type LexiconOutput } from "./lexicon-output";
 import { getProvenance } from "./provenance";
 import { INTRINSIC_MARKER } from "./intrinsic";
+import { subTemplateRefs } from "./graph-sub-template";
 import type { ResourceMetadata } from "./lexicon";
 import type { UnobservedEntity } from "./observation";
 
+export { subTemplateRefs };
+
 /**
  * Graph IR — the engine-neutral, lint-gated representation of a project's
  * resolved infrastructure graph. Painters (mermaid, graphviz, custom SVG) and
@@ -35,6 +38,21 @@ export interface AttrRefEnvelope {
   $ref: string;
 }
 
+/**
+ * A CloudFormation `Fn::Sub` in an attribute projection (#4373), in place of
+ * `{ $intrinsic: true }`. `$sub` is the template exactly as it serializes, so
+ * `${assets.Arn}/*` names the producer and attribute a reader would otherwise
+ * have to guess. `$vars` is the two-argument form's variable map, each value
+ * projected like any other attr. Every `${Name}` or `${Name.Attr}` in the
+ * template that names a node, and every reference in `$vars`, is also an edge.
+ * `${!Literal}` (CloudFormation's escape), pseudo-parameters (`${AWS::Region}`)
+ * and names `$vars` binds are not.
+ */
+export interface SubEnvelope {
+  $sub: string;
+  $vars?: Record<string, unknown>;
+}
+
 /** One resource in the graph. */
 export interface IRNode {
   /** Logical name (the export name, or composite-expanded name). */
@@ -465,6 +483,13 @@ export interface GraphIR {
    * the passes produced, not a list maintained by hand.
    */
   derivedAttrs?: Record<string, string[]>;
+  /**
+   * With `chant graph --format ir --capability-view` (#4378): the
+   * lexicon-neutral view capability rules read, built by this chant through
+   * the project's own lexicon mappings and adapters. A `ViewDocument`
+   * (`capabilities/view.ts`). Absent unless asked for.
+   */
+  capabilityView?: unknown;
 }
 
 /** A node is anything that serializes to a resource — not a property or output. */
@@ -499,6 +524,80 @@ function refIntrinsicTarget(value: unknown): string | undefined {
   return undefined;
 }
 
+/** A CloudFormation `Fn::Sub`: its template, and the variable map of the two-argument form. */
+interface SubForm {
+  template: string;
+  vars?: Record<string, unknown>;
+}
+
+/** Read `{ "Fn::Sub": "..." }` or `{ "Fn::Sub": ["...", { ... }] }`, or undefined. */
+function subForm(json: unknown): SubForm | undefined {
+  if (json === null || typeof json !== "object" || Array.isArray(json)) return undefined;
+  const keys = Object.keys(json);
+  if (keys.length !== 1 || keys[0] !== "Fn::Sub") return undefined;
+  const arg = (json as Record<string, unknown>)["Fn::Sub"];
+  if (typeof arg === "string") return { template: arg };
+  if (Array.isArray(arg) && typeof arg[0] === "string") {
+    const vars = arg[1];
+    return vars !== null && typeof vars === "object" && !Array.isArray(vars)
+      ? { template: arg[0], vars: vars as Record<string, unknown> }
+      : { template: arg[0] };
+  }
+  return undefined;
+}
+
+/** The `Fn::Sub` an intrinsic serializes to (the aws `Sub` tag), or undefined. */
+function subIntrinsicForm(value: unknown): SubForm | undefined {
+  try {
+    return subForm((value as { toJSON?: () => unknown }).toJSON?.());
+  } catch {
+    // An AttrRef inside whose logical name is not set yet: no template to read.
+    return undefined;
+  }
+}
+
+/** False when an intrinsic's `toJSON()` throws (an AttrRef inside it has no logical name yet). */
+function serializes(value: unknown): boolean {
+  try {
+    (value as { toJSON?: () => unknown }).toJSON?.();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The logical names serialized CloudFormation JSON references: `{ Ref }`,
+ * `{ "Fn::GetAtt" }` in either encoding, and a nested `Fn::Sub`. Reads a
+ * two-argument `Sub`'s variable map after `toJSON()` has turned its live
+ * references into JSON.
+ */
+function cfnJsonRefNames(json: unknown, out: string[]): void {
+  if (json === null || typeof json !== "object") return;
+  if (Array.isArray(json)) {
+    for (const item of json) cfnJsonRefNames(item, out);
+    return;
+  }
+  const obj = json as Record<string, unknown>;
+  if (typeof obj.Ref === "string") {
+    out.push(obj.Ref);
+    return;
+  }
+  const getAtt = obj["Fn::GetAtt"];
+  if (getAtt !== undefined) {
+    const id = Array.isArray(getAtt) ? getAtt[0] : typeof getAtt === "string" ? getAtt.split(".")[0] : undefined;
+    if (typeof id === "string") out.push(id);
+    return;
+  }
+  const sub = subForm(obj);
+  if (sub) {
+    for (const r of subTemplateRefs(sub.template, new Set(Object.keys(sub.vars ?? {})))) out.push(r.name);
+    if (sub.vars) cfnJsonRefNames(Object.values(sub.vars), out);
+    return;
+  }
+  for (const v of Object.values(obj)) cfnJsonRefNames(v, out);
+}
+
 /** Resolve the producer (logical name) an AttrRef points at. */
 function refTarget(ref: AttrRef, reverse: Map<object, string>): string | undefined {
   // Nested refs (under `props`) aren't assigned a logical name by resolveAttrRefs,
@@ -545,6 +644,9 @@ function project(value: unknown, seen: Set<unknown>, reverse: Map<object, string
     // Ref to a non-node) stay opaque.
     const to = refIntrinsicTarget(value);
     if (to && nodeIds.has(to)) return { $ref: to } satisfies AttrRefEnvelope;
+    // A Sub keeps its template, so a reader sees which node and attribute it names (#4373).
+    const sub = subIntrinsicForm(value);
+    if (sub) return subEnvelope(sub, seen, reverse, nodeIds);
     return { $intrinsic: true };
   }
 
@@ -568,6 +670,14 @@ function project(value: unknown, seen: Set<unknown>, reverse: Map<object, string
     return out;
   }
 
+  // A Sub written as plain CloudFormation JSON reads the same as the `Sub` tag's.
+  const plainSub = subForm(value);
+  if (plainSub) {
+    const out = subEnvelope(plainSub, seen, reverse, nodeIds);
+    seen.delete(value);
+    return out;
+  }
+
   const out: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
     const p = project(v, seen, reverse, nodeIds);
@@ -577,6 +687,17 @@ function project(value: unknown, seen: Set<unknown>, reverse: Map<object, string
   return out;
 }
 
+/** Project a {@link SubForm} into its {@link SubEnvelope}. */
+function subEnvelope(sub: SubForm, seen: Set<unknown>, reverse: Map<object, string>, nodeIds: Set<string>): SubEnvelope {
+  if (!sub.vars) return { $sub: sub.template };
+  const vars: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(sub.vars)) {
+    const p = project(v, seen, reverse, nodeIds);
+    if (p !== undefined) vars[k] = p;
+  }
+  return { $sub: sub.template, $vars: vars };
+}
+
 // `references` and `stack` are the two duck-typed channels above
 // ({@link entityReferences}, {@link entityStack}). They are metadata about the
 // entity's place in the graph, not declared configuration, and both are read
@@ -645,6 +766,9 @@ function collectEdges(
     });
   }
   const seen = new Set<unknown>();
+  const edgeTo = (to: string, viaAttr: string): void => {
+    if (to !== from && nodeIds.has(to)) edges.push({ from, to, kind: "ref", viaAttr });
+  };
   const visit = (value: unknown, viaAttr: string): void => {
     if (value === null || typeof value !== "object") return;
     if (isAttrRefLike(value)) {
@@ -659,8 +783,31 @@ function collectEdges(
       // — resolve it to an edge instead of dropping it as an opaque intrinsic (#513).
       const to = refIntrinsicTarget(value);
       if (to && to !== from && nodeIds.has(to)) edges.push({ from, to, kind: "ref", viaAttr });
+      // A Sub's interpolations are references too (#4373): each `${Name}` or
+      // `${Name.Attr}` naming a node, and each reference in a variable map.
+      const sub = subIntrinsicForm(value);
+      if (sub) {
+        const names = subTemplateRefs(sub.template, new Set(Object.keys(sub.vars ?? {}))).map((r) => r.name);
+        if (sub.vars) cfnJsonRefNames(Object.values(sub.vars), names);
+        for (const name of names) edgeTo(name, viaAttr);
+      }
+      // The live values the aws `Sub` tag interpolated. Covers an AttrRef whose
+      // logical name was not set, where `toJSON()` throws and leaves no
+      // template to read above. Any other intrinsic stays opaque.
+      const interpolated = (value as { values?: unknown }).values;
+      if (Array.isArray(interpolated) && (sub || !serializes(value))) {
+        for (const v of interpolated) visit(v, viaAttr);
+      }
       return;
     }
+    // A Sub written as plain CloudFormation JSON in props: the template's names
+    // here, then the variable map's live values through the walk below.
+    const plainSub = subForm(value);
+    if (plainSub) {
+      for (const r of subTemplateRefs(plainSub.template, new Set(Object.keys(plainSub.vars ?? {})))) {
+        edgeTo(r.name, viaAttr);
+      }
+    }
     // A whole node held in props or an enumerable field (the sql lexicon's
     // `dependsOn`) is a reference to it: draw the edge, and do not walk its
     // config, whose refs belong to that node's own edges (#3257). Checked

package/src/graph-sub-template.ts

@@ -0,0 +1,22 @@
+// Kept apart from ./graph-ir so ./graph-detail, which runs in the browser
+// bundle, can read a Sub template without pulling in node:path.
+
+/**
+ * The names a `Sub` template interpolates (#4373): `${Name}` and
+ * `${Name.Attr}`, in order. Skips CloudFormation's `${!Literal}` escape,
+ * pseudo-parameters (`${AWS::Region}`, anything with `::`), and names the
+ * two-argument form's variable map binds, which are not resources.
+ */
+export function subTemplateRefs(
+  template: string,
+  bound: ReadonlySet<string> = new Set(),
+): Array<{ name: string; attr?: string }> {
+  const out: Array<{ name: string; attr?: string }> = [];
+  for (const match of template.matchAll(/\$\{([^}]*)\}/g)) {
+    const token = match[1].trim();
+    if (!token || token.startsWith("!") || token.includes("::") || bound.has(token)) continue;
+    const dot = token.indexOf(".");
+    out.push(dot > 0 ? { name: token.slice(0, dot), attr: token.slice(dot + 1) } : { name: token });
+  }
+  return out;
+}

package/src/lexicon.ts

@@ -1,3 +1,4 @@
+import type { CapabilityPack } from "./capabilities/view";
 import type { Serializer } from "./serializer";
 import type { Declarable } from "./declarable";
 import type { LintRule } from "./lint/rule";
@@ -2082,6 +2083,15 @@ export interface LexiconPlugin {
    */
   referenceCatalog?: ReferenceCatalog;
 
+  /**
+   * This lexicon's capability pack (#4375): its mapping onto the
+   * lexicon-neutral view the capability rules read (labels, edge names,
+   * attributes, policy documents, inline blocks, link resources), as data,
+   * plus an adapter for what the mapping can't say as data. `chant search`'s
+   * `cap:` terms and `--capabilities` read it. Opt-in.
+   */
+  capabilityPack?: CapabilityPack;
+
   /**
    * Enrich live IR node attributes for edge reconstruction (#784). Returns
    * `nodeId → attributes` with cross-resource references resolved to the

package/src/lifecycle/observe.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from "vitest";
-import { observeResources, collectAmbient } from "./observe";
+import { observeResources, collectAmbient, carryAnnotations } from "./observe";
 import { observation } from "../observation";
 import type { ObservationLexicon, ResourceMetadata } from "../lexicon";
 import type { BuildResult } from "../build";
@@ -59,6 +59,32 @@ describe("observeResources", () => {
     expect(Object.keys(observations[0].resources)).toEqual(["web-vpc"]);
   });
 
+  it("returns what a lexicon learned about an absent entity as annotations, outside the observations (#4372)", async () => {
+    const plugins = [
+      {
+        name: "aws",
+        serializer: {} as ObservationLexicon["serializer"],
+        describeResources: async () =>
+          observation({}, undefined, undefined, undefined, undefined, undefined, { "web-vpc": { planAction: "create" } }),
+      } as unknown as ObservationLexicon,
+    ];
+    const { observations, annotations } = await observeResources("prod", plugins, mockBuild());
+    // Absent: no observation row anywhere, so nothing that classifies sees it.
+    expect(observations.flatMap((o) => Object.keys(o.resources))).toEqual([]);
+    expect(annotations).toEqual({ "web-vpc": { planAction: "create" } });
+  });
+
+  it("carryAnnotations sets attributes by id and touches nothing else (#4372)", () => {
+    const nodes = [
+      { id: "a", kind: "K", lexicon: "x", attrs: { _status: "accent", name: "a" } },
+      { id: "b", kind: "K", lexicon: "x", attrs: { _status: "good" } },
+    ];
+    const out = carryAnnotations(nodes, { a: { planAction: "create" } });
+    expect(out[0]).toEqual({ id: "a", kind: "K", lexicon: "x", attrs: { _status: "accent", name: "a", planAction: "create" } });
+    expect(out[1]).toBe(nodes[1]);
+    expect(carryAnnotations(nodes, undefined)).toBe(nodes);
+  });
+
   it("passes the declared entity names for scoping", async () => {
     let names: string[] = [];
     const plugins = [awsPlugin(({ entityNames }) => { names = entityNames; return {}; })];

package/src/lifecycle/observe.ts

@@ -22,6 +22,7 @@ import {
   unobservedAll,
   formatUnobserved,
   type NormalizedObservation,
+  type RootRead,
 } from "../observation";
 import { zeroResourcesWarning } from "../live-endpoint";
 import { unqualifiedKey } from "./identity";
@@ -39,6 +40,40 @@ export interface ObserveResult {
    * answer, not ahead of it.
    */
   notes: string[];
+  /**
+   * Facts about declared entities beside their verdict (#4372), keyed like
+   * the observations' resources (stack-qualified where those are). A planned
+   * create is the case: absent, with the plan's attributes. Never part of
+   * `observations`, so nothing that classifies or paints presence sees it;
+   * {@link carryAnnotations} puts it on the declared nodes of an overlay.
+   */
+  annotations?: Record<string, Record<string, unknown>>;
+  /**
+   * Which read answered each declared entity (#2267), keyed like the
+   * observations' resources: `"state"`, `"live"`, `"plan"` or `"live+plan"`
+   * from the terraform lexicon. Present only for lexicons that report it.
+   */
+  sources?: Record<string, string>;
+  /** Which read answered each root, and why it fell back (structured, from the lexicon). */
+  rootReads?: Record<string, RootRead>;
+}
+
+/**
+ * Put each entity's annotations (#4372) on its node, by id. Only attributes
+ * are touched: `_status`, `physicalId` and `ownership` stay what the overlay
+ * decided, so a planned create is still painted pending and still absent to
+ * every consumer that asks. An annotation wins a collision with a declared
+ * attribute, the same precedence an observed attribute has in the overlay.
+ */
+export function carryAnnotations<N extends { id: string; attrs: Record<string, unknown> }>(
+  nodes: N[],
+  annotations: Record<string, Record<string, unknown>> | undefined,
+): N[] {
+  if (!annotations || Object.keys(annotations).length === 0) return nodes;
+  return nodes.map((n) => {
+    const a = annotations[n.id];
+    return a && Object.keys(a).length > 0 ? { ...n, attrs: { ...n.attrs, ...a } } : n;
+  });
 }
 
 /**
@@ -57,6 +92,7 @@ function qualifyObservation(obs: NormalizedObservation, stackName: string): Norm
     queried: q(obs.queried),
     // Which read answered (#2267) is per entity, so it re-keys with them.
     sources: q(obs.sources),
+    ...(obs.annotations ? { annotations: q(obs.annotations) } : {}),
     notes: obs.notes,
     // Exports are already keyed by stack (#1279); nothing to qualify.
     ...(obs.stackExports ? { stackExports: obs.stackExports } : {}),
@@ -131,6 +167,9 @@ export async function observeResources(
   const warnings: string[] = [];
   const errors: string[] = [];
   const notes: string[] = [];
+  const annotations: Record<string, Record<string, unknown>> = {};
+  const sources: Record<string, string> = {};
+  const rootReads: Record<string, RootRead> = {};
 
   for (const plugin of plugins) {
     if (!plugin.describeResources) continue;
@@ -230,6 +269,9 @@ export async function observeResources(
         const line = `[${plugin.name}] ${note}`;
         if (!notes.includes(line)) notes.push(line);
       }
+      Object.assign(annotations, observed.annotations ?? {});
+      Object.assign(sources, observed.sources);
+      Object.assign(rootReads, observed.rootReads ?? {});
       // What the estate depends on but does not declare (#1273). Read after the
       // managed resources, because the declared observation is the closure's
       // roots — there is nothing to reference out from until it exists.
@@ -299,7 +341,7 @@ export async function observeResources(
     }
   }
 
-  return { observations, warnings, errors, notes };
+  return { observations, warnings, errors, notes, annotations, ...(Object.keys(sources).length > 0 ? { sources } : {}), ...(Object.keys(rootReads).length > 0 ? { rootReads } : {}) };
 }
 
 /**

package/src/lint/rule.ts

@@ -45,6 +45,12 @@ export interface LintDiagnostic {
   severity: Severity;
   /** Human-readable message */
   message: string;
+  /**
+   * The entity a post-synth check reported against, when it named one: the
+   * same name the message leads with in brackets, and the graph node's id
+   * (behold#919). Absent for a source-file rule.
+   */
+  entity?: string;
   /** Optional fix that can be applied */
   fix?: LintFix;
 }

package/src/live-endpoint.ts

@@ -35,7 +35,7 @@
  * `--live --env floci` read against azure silently went to real Azure.
  */
 
-import { environmentEndpoint, type EnvironmentDeclaration } from "./config";
+import { environmentEndpoint, type EnvironmentDeclaration } from "./config-environments";
 import { emulatorsOf, endpointEnvVars, type EmulatorDeclaration } from "./op/emulator-lifecycle";
 
 /**

package/src/observation.test.ts

@@ -221,6 +221,31 @@ describe("observeEntities harness (#1201)", () => {
     });
   });
 
+  test("an absent entity's annotations are collected, and it stays in neither map (#4372)", async () => {
+    const result = await observeEntities(
+      [entity("a"), entity("b"), entity("c")],
+      adapterOf({
+        a: { present: meta() },
+        b: { absent: true, annotations: { planAction: "create", planAfterUnknown: ["id"] } },
+        c: { absent: true, annotations: {} },
+      }),
+    );
+    expect(Object.keys(result.resources)).toEqual(["a"]);
+    expect(result.unobserved).toBeUndefined();
+    expect(result.annotations).toEqual({ b: { planAction: "create", planAfterUnknown: ["id"] } });
+    // Through the normalizer and a merge with another part, unchanged.
+    const merged = mergeObservations([normalizeObservation(result), normalizeObservation({ other: meta() })]);
+    expect(merged.annotations).toEqual({ b: { planAction: "create", planAfterUnknown: ["id"] } });
+    expect(Object.keys(merged.resources).sort()).toEqual(["a", "other"]);
+  });
+
+  test("no annotations means no annotations key, on the envelope and the normalized form", async () => {
+    const result = await observeEntities([entity("b")], adapterOf({ b: { absent: true } }));
+    expect("annotations" in result).toBe(false);
+    expect("annotations" in normalizeObservation(result)).toBe(false);
+    expect("annotations" in mergeObservations([normalizeObservation(result)])).toBe(false);
+  });
+
   test("collects the queried address from every variant — the absent one especially (#1620)", async () => {
     const result = await observeEntities(
       [entity("a"), entity("b"), entity("c")],

package/src/observation.ts

@@ -149,6 +149,31 @@ export interface ObservationResult {
    * before this field an observation gave it no way to tell them apart.
    */
   sources?: Record<string, string>;
+  /**
+   * Facts the read learned about an entity beside its verdict (#4372), keyed
+   * by chant entity name, as attribute name -> value. The case it exists for
+   * is a Terraform plan's planned create: the plan says the block will be
+   * created and which of its values stay unknown until apply, but the block
+   * has no row in the plan's prior state, so it is OBSERVED-ABSENT, and
+   * absence is spelled "in neither map". Without this map those facts had
+   * nowhere to go.
+   *
+   * Additive metadata over the tri-state, like {@link queried} and
+   * {@link sources}: classification never reads it, ownership never comes
+   * from it, and an entity with annotations and no `resources` row is still
+   * absent. A renderer or search carries the attributes onto the declared
+   * node (`carryAnnotations` in ./lifecycle/observe.ts), where they read like
+   * any other attribute without making the node present.
+   */
+  annotations?: Record<string, Record<string, unknown>>;
+  /**
+   * Which read answered each root, and why it fell back when it did (#4384
+   * follow-up), keyed by a lexicon-chosen root key (terraform uses
+   * `terraform.roots.<root>`). Structured beside {@link notes}, which say the
+   * same thing in prose: a consumer reads this field and never matches note
+   * text, so rewording a note cannot change what it reports.
+   */
+  rootReads?: Record<string, RootRead>;
   /**
    * Notices about the read as a whole, not about any one entity (#1265) —
    * "the ownership filter could not be applied on this surface" is the
@@ -169,6 +194,20 @@ export interface ObservationResult {
   stackExports?: Record<string, Record<string, unknown>>;
 }
 
+/**
+ * The read a root was asked for and the one that answered. `depth` is the read
+ * asked for (`"plan"` for a plan-depth root, `"live+plan"` for a live root at
+ * the plan depth). `fellBackTo` is set only when that read failed: the read that
+ * answered instead (`"live"` is live-plan alone, for a live root), or
+ * `"declared"` when none did.
+ * `reason` is a short machine-stable cause, not prose to match on.
+ */
+export interface RootRead {
+  depth: string;
+  fellBackTo?: "state" | "live" | "declared";
+  reason?: string;
+}
+
 /**
  * What `describeResources()` may return: the bare map (pre-#1089, still valid —
  * "I looked at everything") or the {@link ObservationResult} envelope.
@@ -183,6 +222,10 @@ export interface NormalizedObservation {
   queried: Record<string, string>;
   /** Which read answered, per entity name (#2267). Empty when the lexicon reported none. */
   sources: Record<string, string>;
+  /** Facts beside the verdict, per entity name (#4372). Absent when the lexicon reported none. */
+  annotations?: Record<string, Record<string, unknown>>;
+  /** Which read answered each root, structured. Absent when the lexicon reported none. */
+  rootReads?: Record<string, RootRead>;
   /** Run-level notices (#1265), distinct. Empty when the lexicon reported none. */
   notes: string[];
   /** Per-stack exports (#1279), keyed by stack name. Absent when the lexicon reported none. */
@@ -209,6 +252,8 @@ export function observation(
   notes?: string[],
   stackExports?: Record<string, Record<string, unknown>>,
   sources?: Record<string, string>,
+  annotations?: Record<string, Record<string, unknown>>,
+  rootReads?: Record<string, RootRead>,
 ): ObservationResult {
   return {
     observation: "v1",
@@ -216,6 +261,8 @@ export function observation(
     ...(unobserved && Object.keys(unobserved).length > 0 ? { unobserved } : {}),
     ...(queried && Object.keys(queried).length > 0 ? { queried } : {}),
     ...(sources && Object.keys(sources).length > 0 ? { sources } : {}),
+    ...(annotations && Object.keys(annotations).length > 0 ? { annotations } : {}),
+    ...(rootReads && Object.keys(rootReads).length > 0 ? { rootReads } : {}),
     ...(notes && notes.length > 0 ? { notes } : {}),
     ...(stackExports && Object.keys(stackExports).length > 0 ? { stackExports } : {}),
   };
@@ -236,6 +283,8 @@ export function normalizeObservation(value: DescribeResourcesResult | undefined)
       queried: value.queried ?? {},
       sources: value.sources ?? {},
       notes: [...new Set(value.notes ?? [])],
+      ...(value.annotations && Object.keys(value.annotations).length > 0 ? { annotations: value.annotations } : {}),
+      ...(value.rootReads && Object.keys(value.rootReads).length > 0 ? { rootReads: value.rootReads } : {}),
       ...(value.stackExports && Object.keys(value.stackExports).length > 0 ? { stackExports: value.stackExports } : {}),
     };
   }
@@ -287,11 +336,16 @@ export function mergeObservations(parts: Iterable<NormalizedObservation>): Norma
   // is one note (#1265).
   const notes = new Set<string>();
   const stackExports: Record<string, Record<string, unknown>> = {};
+  // Annotations (#4372) merge like `sources`: per entity, disjoint parts.
+  const annotations: Record<string, Record<string, unknown>> = {};
+  const rootReads: Record<string, RootRead> = {};
   for (const part of parts) {
     Object.assign(resources, part.resources);
     Object.assign(unobserved, part.unobserved);
     Object.assign(queried, part.queried);
     Object.assign(sources, part.sources);
+    Object.assign(annotations, part.annotations ?? {});
+    Object.assign(rootReads, part.rootReads ?? {});
     for (const n of part.notes) notes.add(n);
     Object.assign(stackExports, part.stackExports ?? {});
   }
@@ -304,6 +358,8 @@ export function mergeObservations(parts: Iterable<NormalizedObservation>): Norma
     queried,
     sources,
     notes: [...notes],
+    ...(Object.keys(annotations).length > 0 ? { annotations } : {}),
+    ...(Object.keys(rootReads).length > 0 ? { rootReads } : {}),
     ...(Object.keys(stackExports).length > 0 ? { stackExports } : {}),
   };
 }
@@ -370,10 +426,14 @@ export interface DeclaredEntity {
  * 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.
+ *
+ * An absent verdict may also carry `annotations` (#4372): attributes the read
+ * learned about the entity without finding it, collected into the result's
+ * `annotations` map. They never make it present.
  */
 export type EntityObservation =
   | { present: ResourceMetadata; queried?: string }
-  | { absent: true; queried?: string }
+  | { absent: true; queried?: string; annotations?: Record<string, unknown> }
   | { unobserved: { reason: UnobservedReason; detail?: string }; queried?: string };
 
 /** What a lexicon supplies to drive the harness. `Client` is its transport handle. */
@@ -463,6 +523,7 @@ export async function observeEntities<Client>(
   const resources: Record<string, ResourceMetadata> = {};
   const unobserved: Record<string, UnobservedEntity> = {};
   const queried: Record<string, string> = {};
+  const annotations: Record<string, Record<string, unknown>> = {};
   const run = adapter.concurrently ?? ((items, fn) => boundedConcurrently(items, fn));
 
   await run(declared, async (entity) => {
@@ -486,11 +547,14 @@ export async function observeEntities<Client>(
         ...result.unobserved,
         ...(result.queried ? { queried: result.queried } : {}),
       };
+    } else if (result.annotations && Object.keys(result.annotations).length > 0) {
+      // `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, and
+      // what the read learned about it lands in `annotations` (#4372).
+      annotations[entity.name] = result.annotations;
     }
-    // `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, queried);
+  return observation(resources, unobserved, queried, undefined, undefined, undefined, annotations);
 }