@intentius/chant 0.60.0 → 0.62.0

package/src/lifecycle/git.ts

@@ -8,6 +8,69 @@ import { getRuntime } from "../runtime-adapter";
 
 const STATE_BRANCH = "chant/lifecycle";
 
+/**
+ * The identity chant's ledger commits fall back to when the checkout has none
+ * of its own (#2301).
+ *
+ * A CI checkout is the ordinary case here, not an exotic one: GitLab CI,
+ * GitHub Actions and Forgejo Actions all clone without `user.email` or
+ * `user.name`, and `git commit-tree` refuses outright rather than inventing
+ * one — `fatal: unable to auto-detect email address`. Every write in this
+ * module goes through `commit-tree`, so before #2301 a gate's pending fact,
+ * a run record, a snapshot and a release record all died the same way the
+ * moment they ran anywhere but a developer's laptop.
+ *
+ * This is a *fallback*, applied per-invocation via `git -c` and field by
+ * field: only the half the checkout cannot supply is filled in. A configured
+ * `user.name` or `user.email` — a developer's, or a CI job that sets one
+ * deliberately — is left exactly as it is and still authors these commits, and
+ * nothing is written to the repository's config either way. Override the
+ * fallback with `CHANT_LIFECYCLE_COMMITTER_NAME` / `_EMAIL` when a project
+ * wants its ledger commits attributed to a bot account it controls.
+ */
+const LEDGER_COMMITTER_NAME = "chant";
+const LEDGER_COMMITTER_EMAIL = "chant@localhost";
+
+/**
+ * `git -c` arguments that give {@link writeBlobToPath}'s `commit-tree` a
+ * committer when — and only when — the checkout cannot supply one itself.
+ * Empty for any checkout that has an identity, which keeps every existing
+ * caller's commits byte-identical to what they were before #2301.
+ */
+async function ledgerCommitIdentityArgs(cwd?: string): Promise<string[]> {
+  const rt = getRuntime();
+  const probe = await rt.spawn(["git", "var", "GIT_COMMITTER_IDENT"], { cwd, env: C_LOCALE_ENV });
+  if (probe.exitCode === 0) return [];
+
+  // Per-field, not all-or-nothing (#2309 review). `git var` fails if *either*
+  // half is missing, so filling in both would overwrite a configured
+  // `user.name` in the checkout that has a name but no email — which is not
+  // what "a configured identity is left exactly as it is" promises.
+  const args: string[] = [];
+  for (const [key, envVar, fallback] of [
+    ["user.name", "CHANT_LIFECYCLE_COMMITTER_NAME", LEDGER_COMMITTER_NAME],
+    ["user.email", "CHANT_LIFECYCLE_COMMITTER_EMAIL", LEDGER_COMMITTER_EMAIL],
+  ] as const) {
+    const configured = await rt.spawn(["git", "config", "--get", key], { cwd, env: C_LOCALE_ENV });
+    if (configured.exitCode === 0 && configured.stdout.trim() !== "") continue;
+    args.push("-c", `${key}=${process.env[envVar]?.trim() || fallback}`);
+  }
+  return args;
+}
+
+/**
+ * Prefix every failure out of the ledger write path with what was being
+ * written and where (#2301 deliverable 2). `git commit-tree failed: <stderr>`
+ * on its own does not say that the thing that failed was chant recording a
+ * fact on its own branch, and the caller that swallows it is one stack frame
+ * away from printing nothing at all.
+ */
+function ledgerWriteError(stage: string, path: string, stderr: string): Error {
+  return new Error(
+    `cannot write ${path} on the ${STATE_BRANCH} branch: ${stage} failed: ${(stderr ?? "").trim()}`,
+  );
+}
+
 /**
  * Write a blob to an arbitrary `<environment>/<filename>` path on the orphan
  * branch, preserving every other env/file entry already on the branch.
@@ -56,13 +119,42 @@ export async function writeBlobToPath(
   // annotation) and no shell-quoting dance around embedded single quotes.
   // Content-addressed and idempotent, so this stays outside the retry loop
   // below — nothing about a CAS conflict on the ref ever invalidates it.
+  //
+  // `path` is resolved first only so every failure below can name it (#2301).
+  const path = `${environment}/${filename}`;
+
   const blobResult = await rt.spawn(["git", "hash-object", "-w", "--stdin"], { cwd, stdin: content });
   if (blobResult.exitCode !== 0) {
-    throw new Error(`git hash-object failed: ${blobResult.stderr}`);
+    throw ledgerWriteError("git hash-object", path, blobResult.stderr);
   }
   const blobSha = blobResult.stdout.trim();
 
-  const path = `${environment}/${filename}`;
+  // Resolved once, outside the retry loop: whether the checkout can name a
+  // committer does not change between attempts (#2301).
+  const identityArgs = await ledgerCommitIdentityArgs(cwd);
+
+  // Creating the ledger branch is a different act from extending it, and only
+  // one of them is safe to do blind (#2309 review). With no local
+  // `chant/lifecycle`, everything below builds a tree from an empty read and
+  // commits it with no parent — a brand-new root commit that *replaces* the
+  // branch rather than appending to it, which `updateRefCAS` cannot catch
+  // because "the ref does not exist" is perfectly true locally.
+  //
+  // Until #2301 this was mostly hidden: `commit-tree` died for want of a
+  // committer before it could happen. Supplying an identity turned that loud
+  // failure into a silent branch fabrication on every writer that reaches
+  // here without a ledger — a run record, a snapshot, a release, a build
+  // manifest — and a fabricated branch is precisely the fork the guard above
+  // exists to refuse. So the guard runs here, at the one seam they all pass
+  // through, rather than at each of their call sites.
+  //
+  // Only when the branch is absent: an extend costs no fetch, and the check
+  // that matters is whether the history this is about to discard exists
+  // somewhere. `requireLifecycleLedger` allows `no-remote` and `absent`, so a
+  // genuinely first write still creates the branch.
+  if ((await getStateBranchTip(cwd)) === null) {
+    await requireLifecycleLedger({ ...(cwd ? { cwd } : {}) });
+  }
 
   // 2-5. Read tree, build the commit, and CAS-update the branch ref — retried
   // on a conflict (#1959 finding 1). `writeBlobToPath` had no retry of its
@@ -127,7 +219,7 @@ export async function writeBlobToPath(
 
     const envTreeResult = await rt.spawn(["git", "mktree"], { cwd, stdin: `${envEntries}\n` });
     if (envTreeResult.exitCode !== 0) {
-      throw new Error(`git mktree (env) failed: ${envTreeResult.stderr}`);
+      throw ledgerWriteError("git mktree (env)", path, envTreeResult.stderr);
     }
     const envTreeSha = envTreeResult.stdout.trim();
 
@@ -150,7 +242,7 @@ export async function writeBlobToPath(
       stdin: `${rootEntries.join("\n")}\n`,
     });
     if (rootTreeResult.exitCode !== 0) {
-      throw new Error(`git mktree (root) failed: ${rootTreeResult.stderr}`);
+      throw ledgerWriteError("git mktree (root)", path, rootTreeResult.stderr);
     }
     const rootTreeSha = rootTreeResult.stdout.trim();
 
@@ -160,11 +252,11 @@ export async function writeBlobToPath(
     const parentRef = tip;
     const parentArgs = parentRef ? ["-p", parentRef] : [];
     const commitResult = await rt.spawn(
-      ["git", "commit-tree", ...parentArgs, "-m", commitMessage, rootTreeSha],
+      ["git", ...identityArgs, "commit-tree", ...parentArgs, "-m", commitMessage, rootTreeSha],
       { cwd },
     );
     if (commitResult.exitCode !== 0) {
-      throw new Error(`git commit-tree failed: ${commitResult.stderr}`);
+      throw ledgerWriteError("git commit-tree", path, commitResult.stderr);
     }
     const commitSha = commitResult.stdout.trim();
 
@@ -534,16 +626,225 @@ export async function pushLifecycle(opts?: { cwd?: string }): Promise<boolean> {
  * Fetch the state branch from remote.
  */
 export async function fetchLifecycle(opts?: { cwd?: string }): Promise<boolean> {
+  return (await fetchLifecycleStatus(opts)).status === "fetched";
+}
+
+/**
+ * Why a fetch of the ledger branch did or did not produce local history
+ * (#2303).
+ *
+ * `fetchLifecycle`'s boolean cannot answer the question the gate actually
+ * needs answered. "No local `chant/lifecycle`" has two causes that a reader
+ * of an empty ledger cannot tell apart, and they call for opposite
+ * behaviour: on a project whose ledger has never been written, an empty
+ * ledger is the truth; in a CI checkout that fetched only the pipeline's own
+ * ref, an empty ledger is history the checkout simply cannot see. Reading the
+ * second as the first is what makes a second pending fact look correct, so
+ * these are separate outcomes:
+ *
+ * - `fetched` — the branch is now in this checkout (or already was, and is
+ *   up to date). Whatever the ledger says is the whole truth.
+ * - `no-remote` — nothing to fetch from. A single-machine project; local is
+ *   authoritative by construction, the same assumption `chant operator`'s
+ *   lease already documents.
+ * - `absent` — the remote answered and has no `chant/lifecycle`. The ledger
+ *   is genuinely empty; this is a project's first gate.
+ * - `diverged` — both sides have the branch and neither contains the other.
+ *   Appending here would drop one side's facts.
+ * - `unreachable` — a remote is configured and did not answer (no network,
+ *   no credentials, a shallow-clone refspec that cannot resolve). Whether
+ *   anything is on the branch is unknown, which is exactly the state that
+ *   must not be read as "nothing has been approved".
+ */
+export type LifecycleFetchStatus =
+  | { status: "fetched" }
+  | { status: "no-remote" }
+  | { status: "absent"; remote: string }
+  | { status: "ahead"; remote: string }
+  | { status: "diverged"; remote: string; stderr: string }
+  | { status: "unreachable"; remote: string; stderr: string };
+
+/**
+ * git's wording when the remote answered and simply does not carry the ref.
+ *
+ * Matched against output forced to `LC_ALL=C` ({@link C_LOCALE_ENV}) — both of
+ * these strings are in git's translation catalogs, so on a distro git built
+ * with NLS and a non-C `LANG` an unpinned locale would fail to match and send
+ * a project's genuine first gate down the `unreachable` path, refusing it.
+ */
+const NO_SUCH_REMOTE_REF_RE = /couldn't find remote ref|no such ref was fetched/i;
+/** git's wording when the refspec would not fast-forward the local branch. Same locale caveat. */
+const NON_FAST_FORWARD_RE = /non-fast-forward|rejected/i;
+
+/**
+ * `git` invocations here are parsed by their output, so they are pinned to the
+ * C locale. `LC_ALL` alone is enough — it outranks `LC_MESSAGES` and `LANG` —
+ * but `LANGUAGE` is GNU gettext's own override and outranks all of them, so it
+ * is cleared too.
+ */
+const C_LOCALE_ENV = { LC_ALL: "C", LANGUAGE: "" };
+
+/**
+ * The remote the ledger lives on.
+ *
+ * `origin` when it exists, rather than whichever name sorts first — a repo
+ * with a `backup` remote alongside `origin` would otherwise fetch the ledger
+ * from `backup`. A non-zero exit is *not* read as "no remote": a git that
+ * failed to answer is not evidence that a project is single-machine, and
+ * treating it as one is what lets an unreadable ledger look empty.
+ */
+async function ledgerRemote(cwd?: string): Promise<{ remote: string } | { failed: true; stderr: string } | null> {
   const rt = getRuntime();
-  const remoteResult = await rt.spawn(["git", "remote"], { cwd: opts?.cwd });
-  if (remoteResult.exitCode !== 0 || !remoteResult.stdout.trim()) return false;
+  const result = await rt.spawn(["git", "remote"], { cwd, env: C_LOCALE_ENV });
+  if (result.exitCode !== 0) return { failed: true, stderr: (result.stderr ?? "").trim() };
+  const names = result.stdout.trim().split("\n").map((n) => n.trim()).filter(Boolean);
+  if (names.length === 0) return null;
+  return { remote: names.includes("origin") ? "origin" : names[0] };
+}
+
+/** A scratch ref this module owns, used to resolve the remote tip without touching the ledger branch. */
+const PROBE_REF = "refs/chant/lifecycle-probe";
+
+/**
+ * Fetch `chant/lifecycle` and say what happened, in the terms
+ * {@link LifecycleFetchStatus} defines.
+ *
+ * The refspec is deliberately un-forced (`chant/lifecycle:chant/lifecycle`,
+ * no leading `+`), so a local branch holding facts the remote does not have is
+ * never rewound by a read.
+ *
+ * git reports "non-fast-forward" for two states that could not be more
+ * different, which is why the rejection is not taken at face value (#2309
+ * review): a local branch *ahead* of the remote — the ordinary state right
+ * after an append whose push has not landed yet — and a local branch that has
+ * genuinely *forked*. Resolving the remote tip into a scratch ref and asking
+ * whether it is an ancestor of the local tip separates them. Reading a fork as
+ * the ledger is what destroys approvals; refusing an append that is merely
+ * ahead would break the retry that is supposed to repair a failed push.
+ */
+export async function fetchLifecycleStatus(opts?: { cwd?: string }): Promise<LifecycleFetchStatus> {
+  const rt = getRuntime();
+  const cwd = opts?.cwd;
+  const found = await ledgerRemote(cwd);
+  if (found === null) return { status: "no-remote" };
+  if ("failed" in found) {
+    return { status: "unreachable", remote: "(unknown)", stderr: found.stderr };
+  }
+  const { remote } = found;
 
-  const remote = remoteResult.stdout.trim().split("\n")[0];
   const fetchResult = await rt.spawn(
     ["git", "fetch", remote, `${STATE_BRANCH}:${STATE_BRANCH}`],
-    { cwd: opts?.cwd },
+    { cwd, env: C_LOCALE_ENV },
   );
-  return fetchResult.exitCode === 0;
+  if (fetchResult.exitCode === 0) return { status: "fetched" };
+
+  const stderr = (fetchResult.stderr ?? "").trim();
+  if (NO_SUCH_REMOTE_REF_RE.test(stderr)) return { status: "absent", remote };
+  if (!NON_FAST_FORWARD_RE.test(stderr)) return { status: "unreachable", remote, stderr };
+
+  // Rejected. Resolve the remote tip into our own scratch ref (forced: the ref
+  // is this module's, and nothing reads it but the next two lines) and ask
+  // whether the local branch already contains it.
+  const probe = await rt.spawn(
+    ["git", "fetch", "--force", remote, `${STATE_BRANCH}:${PROBE_REF}`],
+    { cwd, env: C_LOCALE_ENV },
+  );
+  if (probe.exitCode !== 0) {
+    return { status: "unreachable", remote, stderr: (probe.stderr ?? "").trim() || stderr };
+  }
+  const contains = await rt.spawn(
+    ["git", "merge-base", "--is-ancestor", PROBE_REF, `refs/heads/${STATE_BRANCH}`],
+    { cwd, env: C_LOCALE_ENV },
+  );
+  await rt.spawn(["git", "update-ref", "-d", PROBE_REF], { cwd, env: C_LOCALE_ENV });
+  if (contains.exitCode === 0) return { status: "ahead", remote };
+  return { status: "diverged", remote, stderr };
+}
+
+/**
+ * Thrown when the ledger branch cannot be read, rather than being reported as
+ * empty (#2303).
+ */
+export class LifecycleLedgerUnreadableError extends Error {
+  constructor(
+    public readonly reason: "unreachable" | "diverged",
+    public readonly remote: string,
+    public readonly stderr: string,
+    detail: string,
+  ) {
+    super(
+      `the ${STATE_BRANCH} ledger branch ${detail}, so what is on it cannot be read. ` +
+        `Refusing rather than treating an unreadable ledger as an empty one.` +
+        (reason === "diverged"
+          ? `\n  Two histories claim to be the ledger; appending to either one drops the other's facts. ` +
+            `Inspect both before doing anything else:\n` +
+            `    git fetch ${remote} ${STATE_BRANCH}:refs/chant/remote-ledger\n` +
+            `    git log --oneline ${STATE_BRANCH} refs/chant/remote-ledger`
+          : `\n  Fetch it and retry: git fetch ${remote} ${STATE_BRANCH}:${STATE_BRANCH}`) +
+        (stderr ? `\n  git said: ${stderr.split("\n")[0]}` : ""),
+    );
+    this.name = "LifecycleLedgerUnreadableError";
+  }
+}
+
+/**
+ * Bring the ledger branch into this checkout before reading or appending to
+ * it, and refuse when it cannot be (#2303).
+ *
+ * The gate's read is the one that has to be right: `evaluateGate` decides
+ * whether to walk through or to record a *new* pending fact purely from what
+ * the ledger says, so a read that reports history it cannot see as an empty
+ * ledger makes the second run of an already-approved commit record a second
+ * pending fact and gate again. That is what a GitLab CI retry did on
+ * INTENTIUS/choudoufu#1026 — two pending records for one commit, with
+ * different expiries — because a GitLab checkout fetches the pipeline's own
+ * ref at depth 20 and nothing else. `GIT_DEPTH: 0` does not help: GitLab
+ * fetches refspecs, not all branches.
+ *
+ * There was a separate, laxer guard for the read until #2309's review, on the
+ * reasoning that a checkout which already has the branch "has real history to
+ * read". That reasoning is only sound when the local branch *is* the remote's
+ * history, and it let the worst case through: on a fork, the gate read a
+ * ledger missing every remote approval, recorded a fresh pending fact, and
+ * pushed. The push was not protected either — a rejected non-fast-forward
+ * fetch still updates `refs/remotes/<remote>/chant/lifecycle` opportunistically
+ * in a full clone, so `pushLifecycle`'s `--force-with-lease` matched the tip
+ * it had just learned and forced. Verified on git 2.50.1: a remote holding a
+ * pending fact and an approval ended up holding neither.
+ *
+ * So there is one rule now, for readers and writers alike:
+ *
+ * - `diverged` always refuses. A fork is not the ledger, and nothing good
+ *   comes of reading one as if it were.
+ * - `unreachable` refuses only when the checkout has no local history at all,
+ *   which is the case that would otherwise read as an empty ledger. With
+ *   local history and no answer from the remote, the read proceeds and the
+ *   push's lease fails safely on its own — refusing there would strand every
+ *   offline run.
+ * - `fetched`, `no-remote`, `absent` and `ahead` all proceed. `ahead` is the
+ *   ordinary state right after an append whose push has not landed, and is
+ *   exactly what a retry needs to be able to repair.
+ */
+export async function requireLifecycleLedger(opts?: { cwd?: string }): Promise<void> {
+  const hadLocal = (await getStateBranchTip(opts?.cwd)) !== null;
+  const result = await fetchLifecycleStatus(opts);
+
+  if (result.status === "diverged") {
+    throw new LifecycleLedgerUnreadableError(
+      "diverged",
+      result.remote,
+      result.stderr,
+      `has diverged from the copy on "${result.remote}" — neither contains the other`,
+    );
+  }
+  if (result.status === "unreachable" && !hadLocal) {
+    throw new LifecycleLedgerUnreadableError(
+      "unreachable",
+      result.remote,
+      result.stderr,
+      `is not in this checkout and could not be fetched from "${result.remote}"`,
+    );
+  }
 }
 
 // ── Generic ref CAS (#1485) ──────────────────────────────────────────────────

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 } : {}),
@@ -283,6 +285,7 @@ export async function observeResources(
           resources: {},
           unobserved: unobservedAll(entityNames, "read-failed", message, entities),
           queried: {},
+          sources: {},
           notes: [],
         },
         environment,

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 } : {}),
   };