@intentius/chant 0.59.0 → 0.61.0

package/src/graph-ir.test.ts

@@ -224,3 +224,66 @@ describe("buildGraphIr", () => {
     expect(JSON.stringify(buildGraphIr(reordered))).toEqual(JSON.stringify(ir));
   });
 });
+
+/**
+ * The two duck-typed channels an entity may carry beside its `props` (#2265,
+ * #2266), for a lexicon whose references are strings in someone else's syntax
+ * rather than `AttrRef` objects. Asserted here with a made-up lexicon rather
+ * than terraform's, because what is being checked is that this module reads
+ * the channels without knowing anything about who filled them.
+ */
+describe("entity-declared references and stacks", () => {
+  test("turns a declared reference into an edge, with both attribute names", () => {
+    const vpc = decl({ lexicon: "hcl", entityType: "Vpc" });
+    const subnet = decl({
+      lexicon: "hcl",
+      entityType: "Subnet",
+      props: { vpc_id: "${aws_vpc.main.id}" },
+      references: [{ to: "vpc", viaAttr: "vpc_id", toAttr: "id" }],
+    });
+    const entities = new Map<string, Declarable>([
+      ["vpc", vpc],
+      ["subnet", subnet],
+    ]);
+    resolveAttrRefs(entities);
+
+    const ir = buildGraphIr(entities);
+    expect(ir.edges).toEqual([{ from: "subnet", to: "vpc", kind: "ref", viaAttr: "vpc_id", toAttr: "id" }]);
+    // The reference channel is metadata about the graph, not declared config,
+    // so it never lands in attrs; the string it was resolved from still does.
+    expect(ir.nodes.find((n) => n.id === "subnet")!.attrs).toEqual({ vpc_id: "${aws_vpc.main.id}" });
+  });
+
+  test("drops a declared reference to a self or to something that is not a node", () => {
+    const a = decl({
+      lexicon: "hcl",
+      entityType: "Vpc",
+      references: [
+        { to: "a", viaAttr: "self" },
+        { to: "nowhere", viaAttr: "gone" },
+      ],
+    });
+    const entities = new Map<string, Declarable>([["a", a]]);
+    resolveAttrRefs(entities);
+    expect(buildGraphIr(entities).edges).toEqual([]);
+  });
+
+  test("keys byStack by the unit an entity names, and leaves byLexicon alone", () => {
+    const app = decl({ lexicon: "hcl", entityType: "Vpc", stack: "app" });
+    const net = decl({ lexicon: "hcl", entityType: "Vpc", stack: "network" });
+    // An entity that names no unit still falls back to the lexicon partition,
+    // which is every other lexicon's behaviour and stays unchanged.
+    const plain = decl({ lexicon: "gcp", entityType: "Vpc" });
+    const entities = new Map<string, Declarable>([
+      ["app/vpc", app],
+      ["network/vpc", net],
+      ["plain", plain],
+    ]);
+    resolveAttrRefs(entities);
+
+    const ir = buildGraphIr(entities);
+    expect(ir.groups.byStack).toEqual({ app: ["app/vpc"], gcp: ["plain"], network: ["network/vpc"] });
+    expect(ir.groups.byLexicon).toEqual({ gcp: ["plain"], hcl: ["app/vpc", "network/vpc"] });
+    expect(ir.nodes.find((n) => n.id === "app/vpc")!.attrs).not.toHaveProperty("stack");
+  });
+});

package/src/graph-ir.ts

@@ -13,7 +13,8 @@ import type { UnobservedEntity } from "./observation";
  * resolved infrastructure graph. Painters (mermaid, graphviz, custom SVG) and
  * the agentic diagrammer consume this; it is a pure function of lint-clean
  * source. Every node traces to the file that declared it; every edge is a real
- * cross-resource reference (AttrRef).
+ * cross-resource reference, either an `AttrRef` this module resolves itself or
+ * an {@link EntityReference} the producing lexicon resolved (#2265).
  *
  * Emitted by `chant graph --format ir`. See issue #493 / epic #492.
  */
@@ -90,6 +91,88 @@ export interface IREdge {
   toAttr?: string;
 }
 
+/**
+ * One reference an entity declares in a vocabulary this module cannot read
+ * (#2265), already resolved to the entity key it points at.
+ *
+ * `collectEdges` below finds references two ways: an {@link AttrRef} object a
+ * typed lexicon puts in its props, and a `Ref`-shaped intrinsic. Both are
+ * objects with a resolvable target, which is what makes them findable by a
+ * walk that knows no lexicon. A lexicon that PARSES someone else's source has
+ * neither: the terraform lexicon's entities keep their block body verbatim
+ * from hcl2json, where a reference to another block is the string
+ * `"${aws_vpc.main.id}"` and nothing else. The walk finds nothing, correctly,
+ * and a 247-node estate graphs with zero edges.
+ *
+ * The reference is not missing, it is just in the producer's vocabulary, and
+ * resolving it needs an HCL expression parser and the lexicon's own key shape.
+ * So the lexicon resolves it and says so here, on the entity, in the one
+ * vocabulary this module does understand: an entity key, plus the two
+ * attribute names {@link IREdge} already carries.
+ *
+ * The hook is a plain duck-typed optional field any entity MAY carry beside
+ * its `props`, read through {@link entityReferences}. That is the same shape
+ * (and the same reasoning) as `suppressions`, ../lint/suppressions.ts: a
+ * reference is a fact ABOUT one entity, `Declarable` already lets each lexicon
+ * carry its own fields beside `props`, and nothing that constructs or merges
+ * an entity map had to change for it. A lexicon that wants edges adopts the
+ * convention on its own entities; every other lexicon keeps the AttrRef walk
+ * it already had, and the two sources of edges merge in one place.
+ *
+ * An entry whose `to` is not a node in this graph is dropped rather than kept
+ * as a dangling endpoint, the same rule {@link buildLiveGraphIr} applies to an
+ * observed edge.
+ */
+export interface EntityReference {
+  /** The referenced entity's key, in the same space as the IR's node ids. */
+  to: string;
+  /** The consumer-side attribute the reference flows through (`IREdge.viaAttr`). */
+  viaAttr?: string;
+  /** The producer-side attribute referenced (`IREdge.toAttr`), when the reference named exactly one. */
+  toAttr?: string;
+}
+
+/** True when `value` has the {@link EntityReference} shape. */
+function isEntityReference(value: unknown): value is EntityReference {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { to?: unknown }).to === "string"
+  );
+}
+
+/**
+ * The references an entity declared for itself (#2265), or an empty list.
+ * Duck-typed on purpose, see {@link EntityReference}.
+ */
+export function entityReferences(entity: Declarable): readonly EntityReference[] {
+  const declared = (entity as unknown as { references?: unknown }).references;
+  if (!Array.isArray(declared)) return [];
+  return declared.filter(isEntityReference);
+}
+
+/**
+ * The deployable unit an entity says it belongs to (#2266), or undefined.
+ *
+ * Same duck-typed channel as {@link entityReferences}, for the other half of
+ * the same problem. `groups.byStack` keys by lexicon partition when nothing
+ * says otherwise, on the reasoning that one lexicon serialises to one
+ * deployable stack. That reasoning is exactly wrong for a lexicon reading an
+ * estate that already has several: a terraform project declaring five
+ * `terraform.roots` has five things `terraform apply` runs against, and each
+ * one is a stack in every sense `byStack` means, so five roots landed in one
+ * bucket named `terraform`.
+ *
+ * The root is not inferable here and should not be: it is the producer's own
+ * name for its own unit. A consumer could recover it from the node id prefix
+ * the terraform lexicon mints, but an id convention is not a promise, and
+ * `byStack` is the field whose whole job is saying which box a node goes in.
+ */
+export function entityStack(entity: Declarable): string | undefined {
+  const stack = (entity as unknown as { stack?: unknown }).stack;
+  return typeof stack === "string" && stack.length > 0 ? stack : undefined;
+}
+
 /** Grouping metadata for cluster/subgraph rendering. Maps group name -> node ids. */
 export interface IRGroups {
   byLexicon?: Record<string, string[]>;
@@ -99,11 +182,15 @@ export interface IRGroups {
    * boundary boxes) read this rather than inferring stacks — which is the point,
    * so it should never require one.
    *
-   * Two sources, depending on how the project is shaped:
+   * Three sources, depending on how the project is shaped:
    *
    *  - **side-by-side stacks**, declared in config and composed by
    *    `buildDeclaredPerStack` — keys are the declared stack names. Nothing is
    *    inferred; the project stated both the names and the membership.
+   *  - **entities that name their own unit** ({@link entityStack}, #2266) —
+   *    keys are those names, one entry per unit. A terraform root is the case
+   *    this exists for: five `terraform.roots` are five `terraform apply`s and
+   *    five boundary boxes, not one bucket called `terraform`.
    *  - **one source tree** — keys are lexicon partitions, since each lexicon
    *    serialises to one deployable stack.
    *
@@ -315,7 +402,12 @@ function project(value: unknown, seen: Set<unknown>, reverse: Map<object, string
   return out;
 }
 
-const SKIP_KEYS = new Set(["lexicon", "entityType", "kind", "attributes", "Ref"]);
+// `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
+// directly, so projecting them into `attrs` would only restate an edge and a
+// group key the IR already carries.
+const SKIP_KEYS = new Set(["lexicon", "entityType", "kind", "attributes", "Ref", "references", "stack"]);
 
 /** The config bag of a node, paired with each key. Lexicon entities keep their
  * declared props in a (usually non-enumerable) `props` object; simpler entities
@@ -349,7 +441,17 @@ function projectConfig(
   return out;
 }
 
-/** Collect ref edges from one node, labelling each with its consumer property. */
+/**
+ * Collect ref edges from one node, labelling each with its consumer property.
+ *
+ * Two sources, merged here. First the references the entity resolved for
+ * itself ({@link EntityReference}), which is how a lexicon that parses HCL,
+ * YAML or any other foreign source says what its strings point at. Then the
+ * walk over the config bag for {@link AttrRef} objects and `Ref` intrinsics,
+ * which is how a typed lexicon's props carry the same fact. A lexicon uses one
+ * or the other; nothing stops it using both, and the dedup in `buildGraphIr`
+ * collapses an edge two sources agree on.
+ */
 function collectEdges(
   entity: Declarable,
   from: string,
@@ -357,6 +459,16 @@ function collectEdges(
   reverse: Map<object, string>,
 ): IREdge[] {
   const edges: IREdge[] = [];
+  for (const ref of entityReferences(entity)) {
+    if (ref.to === from || !nodeIds.has(ref.to)) continue;
+    edges.push({
+      from,
+      to: ref.to,
+      kind: "ref",
+      ...(ref.viaAttr ? { viaAttr: ref.viaAttr } : {}),
+      ...(ref.toAttr ? { toAttr: ref.toAttr } : {}),
+    });
+  }
   const seen = new Set<unknown>();
   const visit = (value: unknown, viaAttr: string): void => {
     if (value === null || typeof value !== "object") return;
@@ -440,9 +552,14 @@ export function buildGraphIr(
     nodes.push(node);
 
     (byLexicon[entity.lexicon] ??= []).push(name);
-    // Within ONE source tree a stack is a lexicon partition — each lexicon
-    // serialises to one deployable stack (a CloudFormation template, a CI
-    // config) — so that is what `byStack` reports here. It stays a distinct axis
+    // An entity that names its own deployable unit is taken at its word
+    // (#2266): a terraform root is one `terraform apply`, and a project
+    // declaring five of them has five stacks whatever the lexicon count says.
+    // See {@link entityStack}.
+    //
+    // Otherwise, within ONE source tree a stack is a lexicon partition — each
+    // lexicon serialises to one deployable stack (a CloudFormation template, a
+    // CI config) — so that is what `byStack` reports. It stays a distinct axis
     // from `byLexicon` (which is for provenance/colouring), emitted separately
     // even where the two coincide.
     //
@@ -455,7 +572,7 @@ export function buildGraphIr(
     // child-project". #513 is closed, that phase was never filed, and directory
     // partitioning is the exception rather than the rule — so the promise is
     // withdrawn rather than left pointing at a closed issue.
-    (byStack[entity.lexicon] ??= []).push(name);
+    (byStack[entityStack(entity) ?? entity.lexicon] ??= []).push(name);
     if (prov?.composite) (byComposite[prov.composite] ??= []).push(name);
   }
 

package/src/lexicon.ts

@@ -494,10 +494,11 @@ export interface ComponentPipelineResult {
  * the generated job needs to act on a finding — elevated write access for
  * `issue`/`comment`/`pull-request`/`merge-request`, none for `report`.
  *
- * `comment` posts the finding on the pull request that triggered the run
- * (#2231), so unlike every other mode it constrains the trigger: the github
- * generator refuses it by name on anything but `pull_request`, and the gitlab
- * and forgejo generators refuse it outright.
+ * `comment` posts the finding on the pull request — or, on GitLab, the merge
+ * request (#2256) — that triggered the run, so unlike every other mode it
+ * constrains the trigger: the github and gitlab generators both refuse it by
+ * name on anything but `pull_request`. The forgejo generator refuses it
+ * outright, having no forge client to post the equivalent comment with.
  */
 export type OpFindingMode = "report" | "issue" | "comment" | "pull-request" | "merge-request";
 
@@ -525,7 +526,9 @@ export type OpTrigger =
  *
  * A CI provider with no action concept degrades by name rather than
  * silently: the gitlab generator refuses a `uses` entry at build time and
- * emits a `run` entry as an ordinary script line.
+ * emits a `run` entry as an ordinary script line. The additive `permissions`
+ * map degrades the same way there, with one exception: `id-token: write`
+ * becomes GitLab's own `id_tokens:` declaration (#2256).
  */
 export type OpSetupStep = OpSetupUsesStep | OpSetupRunStep;
 
@@ -551,6 +554,38 @@ export interface OpSetupRunStep {
   env?: Record<string, string>;
 }
 
+/**
+ * The deployment environment a generated Op job runs in (#2257) — a forge
+ * object rather than a chant one. On GitHub Actions an environment carries
+ * its own protection rules (required reviewers, a wait timer, a branch
+ * restriction) and its own secrets and variables, so naming one on a job is
+ * how a generated apply is put behind a human before the job starts. GitLab
+ * has the same key with the same two fields and its own protected-environment
+ * approvals behind it. Forgejo Actions has no environments at all, so its
+ * dialect drops the key and says so in the generated file's header.
+ *
+ * This is not a chant gate and does not replace one. The environment reviewer
+ * stops the job before any step runs; chant's own gate (#2119) stops the apply
+ * inside a run that already started, on a fact recorded on the
+ * `chant/lifecycle` branch, and is cleared by `chant approve`. A project may
+ * have either, both, or neither per environment.
+ */
+export interface OpEnvironment {
+  /**
+   * The environment's name, exactly as the forge spells it. Nothing creates
+   * it: an environment is repository configuration, and a job naming one that
+   * does not exist yet gets an unprotected environment created on first run
+   * rather than an error, which is precisely why the name is not guessed here.
+   */
+  name: string;
+  /**
+   * The URL shown against the resulting deployment. Absolute, or an
+   * expression the forge resolves (`${{ ... }}`) — a relative path renders as
+   * a dead link on the deployments page rather than failing anywhere.
+   */
+  url?: string;
+}
+
 /** One scheduled Op to generate CI for — the cron-triggered counterpart to a component (generate mode). */
 export interface ScheduledOpSpec {
   /** Op name (`*.op.ts`'s `Op({ name })`) — what `chant run <name>` targets. */
@@ -594,6 +629,15 @@ export interface ScheduledOpSpec {
    * grants and OIDC cannot work without.
    */
   permissions?: Record<string, "read" | "write">;
+  /**
+   * The forge deployment environment this Op's generated job runs in
+   * (#2257). Per Op, beside `setup` and `permissions`, and for the same
+   * reason: which environment a job deploys to is a property of that job — a
+   * pull-request plan touches none, and only the push apply belongs behind
+   * the reviewer. See {@link OpEnvironment} for how it composes with chant's
+   * own gate.
+   */
+  environment?: OpEnvironment;
 }
 
 /**

package/src/lifecycle/assert-live.ts

@@ -121,6 +121,7 @@ export async function assertLiveEntity(opts: AssertLiveEntityOptions): Promise<R
       resources: {},
       unobserved: unobservedAll([name], "read-failed", detail, { [name]: entityType }),
       queried: {},
+      sources: {},
       notes: [],
     };
   }

package/src/lifecycle/observe.test.ts

@@ -204,8 +204,8 @@ describe("observeResources", () => {
         const stack = (opts as { stack?: string }).stack;
         calls.push(stack);
         // Different resources per stack — the multi-stack, per-component case
-        // (#57 loomster). Bare-string stacks keep BARE ids (no `src` scope), so
-        // the union is `db-a`+`db-b`, not stack-qualified: per-component ids are
+        // (#57). Bare-string stacks keep BARE ids (no `src` scope), so the
+        // union is `db-a`+`db-b`, not stack-qualified: per-component ids are
         // already unique and behold reads them bare. Qualification is a scoped
         // (`src`) feature — see the per-stack src test below.
         const resources: Record<string, ResourceMetadata> =

package/src/lifecycle/observe.ts

@@ -55,6 +55,8 @@ function qualifyObservation(obs: NormalizedObservation, stackName: string): Norm
     resources: q(obs.resources),
     unobserved: q(obs.unobserved),
     queried: q(obs.queried),
+    // Which read answered (#2267) is per entity, so it re-keys with them.
+    sources: q(obs.sources),
     notes: obs.notes,
     // Exports are already keyed by stack (#1279); nothing to qualify.
     ...(obs.stackExports ? { stackExports: obs.stackExports } : {}),
@@ -71,10 +73,10 @@ function qualifyObservation(obs: NormalizedObservation, stackName: string): Norm
  * (`read-failed`, #1089) rather than dropped, so a failed read is visibly a
  * hole instead of a silent absence.
  *
- * `stacks` (#57) is for a multi-stack, per-component project (e.g. loomster)
- * where there is no single stack named after the environment — AWS's
- * single-stack convention (`lexicons/aws/src/plugin.ts`'s `describeResources`,
- * absent an explicit `stack`) queries a stack that simply doesn't exist there,
+ * `stacks` (#57) is for a multi-stack, per-component project, where there is no
+ * single stack named after the environment — AWS's single-stack convention
+ * (`lexicons/aws/src/plugin.ts`'s `describeResources`, absent an explicit
+ * `stack`) queries a stack that simply doesn't exist there,
  * so the single-call path always observes zero nodes. When `stacks` is
  * present and non-empty, each observing plugin's `describeResources` is
  * called once per stack and the returned observations are merged. A stack entry
@@ -197,10 +199,10 @@ export async function observeResources(
           // Qualify ids by stack ONLY for a scoped (`src`) stack (#1162): that
           // is the multi-region case where the SAME bare LogicalResourceId
           // (e.g. `vpc`) exists in every stack, so a bare union would collide.
-          // A bare-string stack (#57 loomster) has unique per-component ids and
-          // is asked the whole-project entity set, so it keeps the bare-id
-          // tri-state merge (present > not-observed > absent) that behold and
-          // other consumers read.
+          // A bare-string stack (#57) has unique per-component ids and is asked
+          // the whole-project entity set, so it keeps the bare-id tri-state
+          // merge (present > not-observed > absent) that behold and other
+          // consumers read.
           parts.push(stack.src ? qualifyObservation(norm, stack.name) : norm);
         }
         observed = mergeObservations(parts);
@@ -283,6 +285,7 @@ export async function observeResources(
           resources: {},
           unobserved: unobservedAll(entityNames, "read-failed", message, entities),
           queried: {},
+          sources: {},
           notes: [],
         },
         environment,

package/src/lifecycle/release-ledger.test.ts

@@ -256,10 +256,10 @@ describe("release-ledger", () => {
     test("a Forgejo instance resolves through the same env contract to its own host", () => {
       const env = {
         GITHUB_RUN_ID: "42",
-        GITHUB_REPOSITORY: "intentius/loomster",
+        GITHUB_REPOSITORY: "acme/widgets",
         GITHUB_SERVER_URL: "https://forge.example.dev",
       };
-      expect(resolveRunId(undefined, env).runOrigin!.url).toBe("https://forge.example.dev/intentius/loomster/actions/runs/42");
+      expect(resolveRunId(undefined, env).runOrigin!.url).toBe("https://forge.example.dev/acme/widgets/actions/runs/42");
     });
 
     test("GitLab CI env records the project path and takes CI_PIPELINE_URL verbatim", () => {

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: {}, queried: {}, notes: [] });
+    expect(normalizeObservation({ a: meta() })).toEqual({ resources: { a: meta() }, unobserved: {}, queried: {}, sources: {}, notes: [] });
   });
 
   test("the envelope carries both halves", () => {
@@ -38,6 +38,7 @@ describe("normalizeObservation", () => {
       resources: { a: meta() },
       unobserved: { b: { reason: "read-failed" } },
       queried: {},
+      sources: {},
       notes: [],
     });
   });
@@ -50,7 +51,7 @@ describe("normalizeObservation", () => {
   });
 
   test("undefined normalizes to empty maps", () => {
-    expect(normalizeObservation(undefined)).toEqual({ resources: {}, unobserved: {}, queried: {}, notes: [] });
+    expect(normalizeObservation(undefined)).toEqual({ resources: {}, unobserved: {}, queried: {}, sources: {}, notes: [] });
   });
 
   test("the envelope carries the queried addresses through normalization (#1620)", () => {
@@ -92,8 +93,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" } }, queried: {}, notes: [] },
-      { resources: { a: meta() }, unobserved: {}, queried: {}, notes: [] },
+      { resources: {}, unobserved: { a: { reason: "read-failed" }, b: { reason: "no-binding" } }, queried: {}, sources: {}, notes: [] },
+      { resources: { a: meta() }, unobserved: {}, queried: {}, sources: {}, notes: [] },
     ]);
     expect(Object.keys(merged.resources)).toEqual(["a"]);
     expect(Object.keys(merged.unobserved)).toEqual(["b"]);
@@ -102,26 +103,37 @@ describe("mergeObservations (multi-stack)", () => {
   test("the same note from four stacks is one note (#1265)", () => {
     const note = "ownership filter unavailable";
     const merged = mergeObservations(
-      ["a", "b", "c", "d"].map((k) => ({ resources: { [k]: meta() }, unobserved: {}, queried: {}, notes: [note] })),
+      ["a", "b", "c", "d"].map((k) => ({ resources: { [k]: meta() }, unobserved: {}, queried: {}, sources: {}, notes: [note] })),
     );
     expect(merged.notes).toEqual([note]);
   });
 
   test("an entity nobody looked for in any stack stays absent", () => {
     const merged = mergeObservations([
-      { resources: { a: meta() }, unobserved: {}, queried: {}, notes: [] },
-      { resources: { b: meta() }, unobserved: {}, queried: {}, notes: [] },
+      { resources: { a: meta() }, unobserved: {}, queried: {}, sources: {}, notes: [] },
+      { resources: { b: meta() }, unobserved: {}, queried: {}, sources: {}, notes: [] },
     ]);
     expect(merged.unobserved).toEqual({});
   });
 
   test("queried addresses union across stacks (#1620)", () => {
     const merged = mergeObservations([
-      { resources: {}, unobserved: {}, queried: { a: "stack-1/a" }, notes: [] },
-      { resources: { b: meta() }, unobserved: {}, queried: { b: "stack-2/b" }, notes: [] },
+      { resources: {}, unobserved: {}, queried: { a: "stack-1/a" }, sources: {}, notes: [] },
+      { resources: { b: meta() }, unobserved: {}, queried: { b: "stack-2/b" }, sources: {}, notes: [] },
     ]);
     expect(merged.queried).toEqual({ a: "stack-1/a", b: "stack-2/b" });
   });
+
+  test("which read answered unions across parts (#2267)", () => {
+    // Parts read disjoint entity sets (one per stack, or per terraform root),
+    // so the union is the whole answer and there is nothing to reconcile. A
+    // project mixing a stock root and a live one gets both values here.
+    const merged = mergeObservations([
+      { resources: { a: meta() }, unobserved: {}, queried: {}, sources: { a: "state" }, notes: [] },
+      { resources: { b: meta() }, unobserved: {}, queried: {}, sources: { b: "live" }, notes: [] },
+    ]);
+    expect(merged.sources).toEqual({ a: "state", b: "live" });
+  });
 });
 
 describe("reason totality", () => {

package/src/observation.ts

@@ -112,6 +112,24 @@ export interface ObservationResult {
    * namespace, endpoint or region was read, not the one the resource lives in.
    */
   queried?: Record<string, string>;
+  /**
+   * Which read answered for each declared entity (#2267), keyed by chant
+   * entity name. The value is a short token the lexicon defines and documents;
+   * core carries it and never interprets it, so nothing here switches on one.
+   *
+   * Additive metadata over the tri-state, exactly like {@link queried}, and
+   * present for every verdict including OBSERVED-ABSENT and NOT-OBSERVED,
+   * since which read was attempted is a fact whatever the read came back with.
+   *
+   * A lexicon with one read path has nothing to say here and omits it. This is
+   * for a lexicon with two, where the two answer different questions: a stock
+   * Terraform root is read with `terraform show -json` over its state, which
+   * says what the last apply recorded, and a live root is read with
+   * `choudoufu live-plan -json`, which says what the account holds. A renderer
+   * that paints an overlay as drift must not paint the first one green, and
+   * before this field an observation gave it no way to tell them apart.
+   */
+  sources?: Record<string, string>;
   /**
    * 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
@@ -144,6 +162,8 @@ export interface NormalizedObservation {
   unobserved: Record<string, UnobservedEntity>;
   /** Resolved query address per entity name (#1620). Empty when the lexicon reported none. */
   queried: Record<string, string>;
+  /** Which read answered, per entity name (#2267). Empty when the lexicon reported none. */
+  sources: Record<string, string>;
   /** 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. */
@@ -169,12 +189,14 @@ export function observation(
   queried?: Record<string, string>,
   notes?: string[],
   stackExports?: Record<string, Record<string, unknown>>,
+  sources?: Record<string, string>,
 ): ObservationResult {
   return {
     observation: "v1",
     resources,
     ...(unobserved && Object.keys(unobserved).length > 0 ? { unobserved } : {}),
     ...(queried && Object.keys(queried).length > 0 ? { queried } : {}),
+    ...(sources && Object.keys(sources).length > 0 ? { sources } : {}),
     ...(notes && notes.length > 0 ? { notes } : {}),
     ...(stackExports && Object.keys(stackExports).length > 0 ? { stackExports } : {}),
   };
@@ -187,17 +209,18 @@ export function observation(
  * {@link unobservedAll} rather than returning nothing.
  */
 export function normalizeObservation(value: DescribeResourcesResult | undefined): NormalizedObservation {
-  if (!value) return { resources: {}, unobserved: {}, queried: {}, notes: [] };
+  if (!value) return { resources: {}, unobserved: {}, queried: {}, sources: {}, notes: [] };
   if (isObservationResult(value)) {
     return {
       resources: value.resources ?? {},
       unobserved: value.unobserved ?? {},
       queried: value.queried ?? {},
+      sources: value.sources ?? {},
       notes: [...new Set(value.notes ?? [])],
       ...(value.stackExports && Object.keys(value.stackExports).length > 0 ? { stackExports: value.stackExports } : {}),
     };
   }
-  return { resources: value, unobserved: {}, queried: {}, notes: [] };
+  return { resources: value, unobserved: {}, queried: {}, sources: {}, notes: [] };
 }
 
 /**
@@ -237,6 +260,10 @@ export function mergeObservations(parts: Iterable<NormalizedObservation>): Norma
   const resources: Record<string, ResourceMetadata> = {};
   const unobserved: Record<string, UnobservedEntity> = {};
   const queried: Record<string, string> = {};
+  // Which read answered (#2267) merges the same way `queried` does: it is a
+  // fact about one entity's read, and the parts being merged are reads of
+  // disjoint entity sets (one per stack, or per terraform root).
+  const sources: Record<string, string> = {};
   // A note is about the read, not a stack; four stacks saying the same thing
   // is one note (#1265).
   const notes = new Set<string>();
@@ -245,6 +272,7 @@ export function mergeObservations(parts: Iterable<NormalizedObservation>): Norma
     Object.assign(resources, part.resources);
     Object.assign(unobserved, part.unobserved);
     Object.assign(queried, part.queried);
+    Object.assign(sources, part.sources);
     for (const n of part.notes) notes.add(n);
     Object.assign(stackExports, part.stackExports ?? {});
   }
@@ -255,6 +283,7 @@ export function mergeObservations(parts: Iterable<NormalizedObservation>): Norma
     resources,
     unobserved,
     queried,
+    sources,
     notes: [...notes],
     ...(Object.keys(stackExports).length > 0 ? { stackExports } : {}),
   };

package/src/op/activities/index.ts

@@ -43,7 +43,14 @@ export type { EnvTeardownArgs, EnvTeardownResult, EnvTeardownDeps } from "./env-
 // the registry imports this module statically, so a project that installs
 // nothing but chant still resolves every step below.
 
-export { reconcilePr, commentMarker, pullRequestContextFrom, resolvePullRequestContext } from "./reconcile";
+export {
+  reconcilePr,
+  commentMarker,
+  pullRequestContextFrom,
+  resolvePullRequestContext,
+  mergeRequestContextFrom,
+  gitlabNoteTokenFrom,
+} from "./reconcile";
 export type { ReconcilePrArgs, ReconcileResult, ReconcileMode, ReconcileEntry, PullRequestContext } from "./reconcile";
 
 export { nativeApply, compensateApply, hasNativeRollback } from "./apply";