@intentius/chant 0.124.52 → 0.124.54

package/src/lifecycle/index-store-load-bearing.test.ts

@@ -0,0 +1,187 @@
+/**
+ * The index is never load-bearing (#4519, rule 1).
+ *
+ * Every snapshot and every other index is derived and safe to lose: removing
+ * the store costs history and the cost of observing again, never a decision.
+ * Two checks hold that:
+ *
+ * 1. Behaviour. `buildChangeSet`, which `lifecycle plan` feeds from the store
+ *    (`observedThen`), proposes the same create, delete, adopt, runtime and
+ *    unobserved entries, with the same ownership, whether the last snapshot is
+ *    there, absent (store `none`), or says something else entirely. The only
+ *    thing a snapshot may move is evidence: an `update` row's deltas are drift
+ *    since the last read, and with no last read there is none to show.
+ *    A BREAK that lets the snapshot decide a delete is caught by the same
+ *    check, which the second test proves.
+ * 2. Imports. The modules that decide what to mutate (the change set, the
+ *    unobserved gate, teardown, apply, the gate and its decision) do not load
+ *    the store, the snapshot writer or the replay, so they cannot read an index.
+ */
+import { describe, expect, test } from "vitest";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildChangeSet, type ChangeSet } from "./change-set";
+import { createSnapshotStore } from "./snapshot-store";
+import { fakeSnapshotStore } from "./snapshot-store-fake";
+import type { DiffLiveInput } from "./live-diff";
+import type { ResourceMetadata } from "../lexicon";
+import type { SnapshotStore } from "./snapshot-store";
+
+const meta = (over: Partial<ResourceMetadata> = {}): ResourceMetadata => ({ type: "Fake::Resource", status: "OK", ...over });
+
+type Build = (env: string, input: DiffLiveInput) => ChangeSet;
+
+/** The live side of each case. The snapshot side is varied below. */
+const cases: Array<{ name: string; input: Omit<DiffLiveInput, "observedThen"> }> = [
+  {
+    name: "declared and live, declared and absent, owned orphan, foreign orphan",
+    input: {
+      declared: new Set(["kept", "missing"]),
+      observedNow: {
+        kept: meta({ ownership: "owned" }),
+        orphanOwned: meta({ ownership: "owned" }),
+        orphanForeign: meta({ ownership: "foreign" }),
+        orphanUnknown: meta(),
+      },
+    },
+  },
+  {
+    name: "a runtime child and an unobserved declaration",
+    input: {
+      declared: new Set(["owner", "hole"]),
+      observedNow: {
+        owner: meta({ ownership: "owned" }),
+        child: meta({ ownerChain: { root: "declared", entity: "owner" } } as Partial<ResourceMetadata>),
+      },
+      unobserved: { hole: { type: "Fake::Resource", reason: "no-credentials" } },
+    },
+  },
+];
+
+/** Snapshots that disagree with the live read in every way a snapshot can. */
+const snapshotsFor = (input: Omit<DiffLiveInput, "observedThen">): Array<Record<string, ResourceMetadata> | undefined> => {
+  const names = [...new Set([...input.declared, ...Object.keys(input.observedNow), "gone"])];
+  return [
+    undefined,
+    {},
+    Object.fromEntries(names.map((n) => [n, meta({ ownership: "owned", status: "STALE" })])),
+    Object.fromEntries(names.map((n) => [n, meta({ ownership: "foreign", status: "OTHER", physicalId: `old-${n}` })])),
+  ];
+};
+
+const DECISIONS = new Set(["create", "delete", "adopt", "runtime", "unobserved", "effect"]);
+
+/**
+ * Every way `build` lets a snapshot change a decision, as text, empty when
+ * none does. A name only the snapshot knows is never a decision.
+ */
+function loadBearing(build: Build): string[] {
+  const found: string[] = [];
+  for (const c of cases) {
+    const without = build("prod", { ...c.input, observedThen: undefined });
+    const decided = new Map(without.entries.map((e) => [e.name, e]));
+    for (const then of snapshotsFor(c.input)) {
+      const withSnap = build("prod", { ...c.input, observedThen: then });
+      for (const e of withSnap.entries) {
+        const base = decided.get(e.name);
+        if (!base) {
+          if (e.action !== "noop") found.push(`${c.name}: ${e.name} exists only in the snapshot and became ${e.action}`);
+          continue;
+        }
+        if (e.ownership !== base.ownership) found.push(`${c.name}: ${e.name} ownership ${base.ownership} -> ${e.ownership}`);
+        const decisionMoved = (DECISIONS.has(e.action) || DECISIONS.has(base.action)) && e.action !== base.action;
+        if (decisionMoved) found.push(`${c.name}: ${e.name} ${base.action} -> ${e.action}`);
+        // Drift since the last read is the one thing a snapshot adds, and only between update and noop.
+        if (!decisionMoved && e.action !== base.action && !(base.action === "noop" && e.action === "update")) {
+          found.push(`${c.name}: ${e.name} ${base.action} -> ${e.action}`);
+        }
+      }
+    }
+  }
+  return found;
+}
+
+describe("the index is never load-bearing", () => {
+  test("no snapshot, an empty one or a contradicting one changes a decision", () => {
+    expect(loadBearing(buildChangeSet)).toEqual([]);
+  });
+
+  test("a BREAK that lets the snapshot decide a delete is caught", () => {
+    // The break: an undeclared resource the last snapshot called owned is deleted.
+    const broken: Build = (env, input) => {
+      const cs = buildChangeSet(env, input);
+      return {
+        ...cs,
+        entries: cs.entries.map((e) =>
+          e.action === "adopt" && input.observedThen?.[e.name]?.ownership === "owned" ? { ...e, action: "delete" as const, ownership: "owned" as const } : e,
+        ),
+      };
+    };
+    expect(loadBearing(broken).some((f) => f.includes("adopt -> delete"))).toBe(true);
+  });
+
+  test("lifecycle plan's read through the store: store none and a populated store decide alike", async () => {
+    const input = cases[0].input;
+    const populated: SnapshotStore = fakeSnapshotStore({
+      readLatest: async () => JSON.stringify({ resources: snapshotsFor(input)[2] }),
+    });
+    const none = createSnapshotStore({ store: "none" });
+    // What runLifecyclePlan does with the store's answer.
+    const plan = async (store: SnapshotStore) => {
+      const content = await store.readLatest("prod", "fake");
+      const observedThen = content ? (JSON.parse(content) as { resources: Record<string, ResourceMetadata> }).resources : undefined;
+      return buildChangeSet("prod", { ...input, observedThen });
+    };
+    const decisions = (cs: ChangeSet) => cs.entries.filter((e) => DECISIONS.has(e.action)).map((e) => `${e.name}:${e.action}:${e.ownership}`);
+    expect(decisions(await plan(populated))).toEqual(decisions(await plan(none)));
+  });
+});
+
+describe("the modules that decide what to mutate never load the index store", () => {
+  const SRC = fileURLToPath(new URL("..", import.meta.url));
+  const FORBIDDEN = /lifecycle\/(snapshot-store|snapshot-store-s3|snapshot|replay)\.ts$/;
+  const DECIDERS = [
+    "lifecycle/change-set.ts",
+    "lifecycle/unobserved-gate.ts",
+    "lifecycle/teardown.ts",
+    "lifecycle/green-apply.ts",
+    "apply.ts",
+    "op/gate.ts",
+    "gate-decision.ts",
+  ];
+  // Runtime imports only: `import type`, `export type` and `import("...")` in a type position load nothing.
+  const STATIC = /(?:^|\n)\s*(?:import|export)\s+(?!type\s)[^;]*?from\s+["'](\.[^"']+)["']/g;
+  const DYNAMIC = /await\s+import\(\s*["'](\.[^"']+)["']\s*\)/g;
+
+  function resolveSpec(from: string, spec: string): string | null {
+    const base = resolve(dirname(from), spec);
+    for (const c of [base, `${base}.ts`, join(base, "index.ts"), base.replace(/\.js$/, ".ts")]) {
+      if (c.endsWith(".ts") && existsSync(c)) return c;
+    }
+    return null;
+  }
+
+  test.each(DECIDERS)("%s", (entry) => {
+    const start = join(SRC, entry);
+    const parent = new Map<string, string | null>([[start, null]]);
+    const queue = [start];
+    while (queue.length > 0) {
+      const file = queue.shift()!;
+      const text = readFileSync(file, "utf8");
+      for (const m of [...text.matchAll(STATIC), ...text.matchAll(DYNAMIC)]) {
+        const target = resolveSpec(file, m[1]);
+        if (target && !parent.has(target)) {
+          parent.set(target, file);
+          queue.push(target);
+        }
+      }
+    }
+    const reached = [...parent.keys()].filter((f) => FORBIDDEN.test(f)).map((f) => {
+      const chain: string[] = [];
+      for (let c: string | null | undefined = f; c; c = parent.get(c)) chain.push(relative(SRC, c));
+      return chain.reverse().join(" -> ");
+    });
+    expect(reached).toEqual([]);
+  });
+});

package/src/lifecycle/index.ts

@@ -2,6 +2,10 @@ export * from "./types";
 export * from "./git";
 export * from "./digest";
 export * from "./snapshot";
+export * from "./snapshot-store";
+export * from "./snapshot-store-s3";
+export * from "./index-document";
+export * from "./index-diff";
 export * from "./live-diff";
 export * from "./deep-diff";
 export * from "./deep-observe";

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

@@ -10,7 +10,7 @@
 
 import { afterAll, beforeEach, describe, expect, test } from "vitest";
 import { spawnSync } from "node:child_process";
-import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { clearMemberLedgerCache, memberLedgerPrefix, MemberLedgerError, resolveMemberLedger } from "./member-ledger";
@@ -192,19 +192,37 @@ describe("every lifecycle store writes under the member path (#2538)", () => {
     const web = join(root, "services/web");
     await writeSnapshot("prod", "k8s", '{"from":"api"}', { cwd: api });
     await writeSnapshot("prod", "k8s", '{"from":"web"}', { cwd: web });
-    await writeObservationBaseline(emptyBaseline("prod"), { cwd: api });
+    // Written from a subdirectory of the member: the baseline still lands under the member.
+    await writeObservationBaseline(emptyBaseline("prod"), { cwd: join(api, "src") });
 
     const files = branchFiles(root);
-    expect(files).toContain("_members/api/prod/k8s.json");
-    expect(files).toContain("_members/web/prod/k8s.json");
-    expect(files.filter((f) => f.startsWith("_members/api/prod/") && f !== "_members/api/prod/k8s.json")).toHaveLength(1);
-    expect(files.every((f) => f.startsWith("_members/"))).toBe(true);
+    expect(files).toEqual(["_members/api/prod/k8s.json", "_members/web/prod/k8s.json"]);
     expect([...(await readEnvironmentSnapshots("prod", { cwd: web })).values()]).toEqual(['{"from":"web"}']);
+    // The baseline's home is a file under the project since #4519
+    // (.chant/observation-baseline/<env>.json), and the project is the member's directory.
+    expect(existsSync(join(api, ".chant/observation-baseline/prod.json"))).toBe(true);
+    expect(existsSync(join(api, "src/.chant"))).toBe(false);
+    expect(existsSync(join(web, ".chant"))).toBe(false);
+    expect(existsSync(join(root, ".chant"))).toBe(false);
     expect(await readObservationBaseline("prod", { cwd: api })).toMatchObject({ environment: "prod" });
     expect(await readObservationBaseline("prod", { cwd: web })).toBeNull();
+    expect(await readObservationBaseline("prod", { cwd: root })).toBeNull();
     // A member's history lists only the commits that touched its ledger.
     expect(await listSnapshots({ cwd: web })).toHaveLength(1);
-    expect(await listSnapshots({ cwd: root })).toHaveLength(3);
+    expect(await listSnapshots({ cwd: root })).toHaveLength(2);
+  });
+
+  test("an observation baseline on the git-ref home is under the member path", async () => {
+    const root = workspace();
+    const api = join(root, "services/api");
+    const web = join(root, "services/web");
+    const store = { store: "git-ref" as const };
+    await writeObservationBaseline(emptyBaseline("prod"), { cwd: api, store });
+    const onRef = git(["ls-tree", "-r", "--name-only", "refs/chant/observation-baseline"], root).split("\n").filter(Boolean);
+    expect(onRef).toEqual(["_members/api/prod.json"]);
+    expect(await readObservationBaseline("prod", { cwd: api, store })).toMatchObject({ environment: "prod" });
+    expect(await readObservationBaseline("prod", { cwd: web, store })).toBeNull();
+    expect(await readObservationBaseline("prod", { cwd: root, store })).toBeNull();
   });
 
   test("runs and converge records", async () => {

package/src/lifecycle/observation-baseline.test.ts

@@ -1,5 +1,14 @@
-import { describe, test, expect } from "vitest";
+import { afterEach, describe, test, expect } from "vitest";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync as readFile, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { writeBlobToPath } from "./git";
 import {
+  observationBaselineStoreConfig,
+  readObservationBaseline,
+  saveObservationBaseline,
+  OBSERVATION_BASELINE_FILE,
   acceptDeviations,
   acceptedDeviation,
   baselineForLexicon,
@@ -143,3 +152,65 @@ describe("acceptDeviations refuses effect receipts (#1833)", () => {
     expect(baselineForLexicon(b, "aws").Role.accepted).toHaveLength(1);
   });
 });
+
+// ── Where it lives (#4519) ──────────────────────────────────────────────────
+
+describe("the baseline's home", () => {
+  const dirs: string[] = [];
+  afterEach(() => {
+    for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+  });
+  const repo = (): string => {
+    const dir = realpathSync(mkdtempSync(join(tmpdir(), "baseline-home-")));
+    dirs.push(dir);
+    const git = (args: string[]) => execFileSync("git", args, { cwd: dir, encoding: "utf8" });
+    git(["init", "-q", "-b", "main"]);
+    git(["config", "user.email", "test@chant.dev"]);
+    git(["config", "user.name", "Test"]);
+    writeFileSync(join(dir, "README.md"), "fixture\n");
+    git(["add", "README.md"]);
+    git(["commit", "-q", "-m", "init"]);
+    return dir;
+  };
+  const accepted = () =>
+    acceptDeviations(emptyBaseline("prod"), "aws", [{ entity: "Assets", path: "Tags[0].Value", value: "platform" }], { now: "2026-10-26T00:00:00.000Z" });
+
+  test("the default is a file under .chant/observation-baseline/, written for review and never on the orphan branch", async () => {
+    const cwd = repo();
+    const saved = await saveObservationBaseline(accepted(), { cwd, config: {} });
+    expect(saved).toMatchObject({ where: join(".chant", "observation-baseline", "prod.json"), published: "file" });
+    const file = join(cwd, ".chant", "observation-baseline", "prod.json");
+    expect(parseBaseline(readFile(file, "utf8"))).toEqual(accepted());
+    expect(await readObservationBaseline("prod", { cwd, config: {} })).toEqual(accepted());
+    expect(() => execFileSync("git", ["rev-parse", "--verify", "-q", "refs/heads/chant/lifecycle"], { cwd })).toThrow();
+  });
+
+  test("a baseline written on chant/lifecycle before #4519 is still read when no file holds one", async () => {
+    const cwd = repo();
+    await writeBlobToPath("prod", OBSERVATION_BASELINE_FILE, serializeBaseline(accepted()), "legacy", { cwd });
+    expect(await readObservationBaseline("prod", { cwd, config: {} })).toEqual(accepted());
+  });
+
+  test("none keeps nothing and reads nothing", async () => {
+    const cwd = repo();
+    const store = { store: "none" as const };
+    expect((await saveObservationBaseline(accepted(), { cwd, store })).published).toBe("none");
+    expect(existsSync(join(cwd, ".chant"))).toBe(false);
+    expect(await readObservationBaseline("prod", { cwd, store })).toBeNull();
+  });
+
+  test("git-ref writes refs/chant/observation-baseline and reads it back", async () => {
+    const cwd = repo();
+    const store = { store: "git-ref" as const };
+    const saved = await saveObservationBaseline(accepted(), { cwd, store });
+    expect(saved.where).toBe("refs/chant/observation-baseline:prod.json");
+    expect(saved.published).toBe("local");
+    expect(await readObservationBaseline("prod", { cwd, store })).toEqual(accepted());
+  });
+
+  test("the environment overrides chant.config.ts", () => {
+    expect(observationBaselineStoreConfig(undefined, {})).toEqual({ store: "file" });
+    expect(observationBaselineStoreConfig({ store: "git-ref" }, { CHANT_OBSERVATION_BASELINE_STORE: "none" })).toEqual({ store: "none" });
+    expect(() => observationBaselineStoreConfig({ store: "branch" }, {})).toThrow(/not one of/);
+  });
+});

package/src/lifecycle/observation-baseline.ts

@@ -23,25 +23,40 @@
  *
  * ## Where it lives
  *
- * `<environment>/observation-baseline.json` on the `chant/lifecycle` orphan
- * branch — the epic's named candidate home, and the same storage the snapshots
- * (`<env>/<lexicon>.json`), the release ledger (`<env>/releases.jsonl`) and the
- * build archive (`_builds/<digest>.json`) already use, through the same
- * `writeBlobToPath`/`readBlobFromPath` plumbing. One env-keyed namespace for
- * everything chant records *about* an environment rather than *for* it.
+ * A file in the repository, `.chant/observation-baseline/<env>.json` under
+ * the project (#4519). An acceptance is then a commit in an ordinary pull
+ * request, reviewed with the change that needed it. It is not derivable and
+ * not critical, and it is meant to be reviewed: that is the rule that puts a
+ * record here rather than in the index store.
  *
- * The parse/serialize/update half below is pure and storage-free, so the
- * decision is one function call deep if a repo-committed file (`.chant/`) turns
- * out to be the better review surface.
+ * Other homes, through `observationBaseline` in chant.config.ts or
+ * `CHANT_OBSERVATION_BASELINE_STORE`: `git-ref` (`refs/chant/observation-baseline`),
+ * `s3` (`<prefix>/observation-baseline/<env>.json`, with the s3 settings of
+ * `observationBaseline.s3`, else of `snapshots`), or `none`.
+ *
+ * A baseline written before #4519, `<environment>/observation-baseline.json`
+ * on the `chant/lifecycle` orphan branch, is still read when the configured
+ * home has none. It is never written there again.
+ *
+ * The parse/serialize/update half below is pure and storage-free.
  */
 
-import { readBlobFromPath, writeBlobToPath } from "./git";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { ledgerDir, readBlobFromPath } from "./git";
+import { encodeIndexSegment } from "./index-document";
 import { sortedJsonReplacer } from "../utils";
 import { EFFECT_RECEIPT_ENTITY_TYPE } from "../effect-receipt";
 
-/** The file name under `<environment>/` on the orphan branch. */
+/** The file name under `<environment>/` on the orphan branch, where a baseline written before #4519 is read from. */
 export const OBSERVATION_BASELINE_FILE = "observation-baseline.json";
 
+/** The directory, relative to the project, that holds one baseline file per environment (#4519). */
+export const OBSERVATION_BASELINE_DIR = ".chant/observation-baseline";
+
+/** The ref a `git-ref` baseline is written to. */
+export const OBSERVATION_BASELINE_REF = "refs/chant/observation-baseline";
+
 /** One deviation somebody accepted, bound to the value they accepted. */
 export interface AcceptedDeviation {
   /** Property path within the entity's normalized tree (`Tags[0].Value`, `Policy.Statement[1].Effect`). */
@@ -219,31 +234,179 @@ export function countAccepted(baseline: ObservationBaseline | null | undefined):
   return n;
 }
 
-// ── Storage (chant/lifecycle orphan branch) ─────────────────────────────────
+// ── Storage ─────────────────────────────────────────────────────────────────
+
+export type ObservationBaselineStoreKind = "file" | "git-ref" | "s3" | "none";
+
+/** `observationBaseline` in chant.config.ts. */
+export interface ObservationBaselineStoreConfig {
+  store: ObservationBaselineStoreKind;
+  /** `file`: the directory, relative to the project. Default {@link OBSERVATION_BASELINE_DIR}. */
+  dir?: string;
+  /** `git-ref`: the ref. Default {@link OBSERVATION_BASELINE_REF}. */
+  ref?: string;
+  /** `s3`: where. Default: the `snapshots` store's s3 settings. */
+  s3?: import("./snapshot-store-s3").S3StoreSettings;
+}
+
+const BASELINE_KINDS: readonly ObservationBaselineStoreKind[] = ["file", "git-ref", "s3", "none"];
+
+/** Where to read and write a baseline: the project directory, and its config when the caller has it loaded. */
+export interface ObservationBaselineLocation {
+  cwd?: string;
+  /** The project's loaded chant.config. Loaded from `cwd` upward when absent. */
+  config?: { observationBaseline?: unknown; snapshots?: unknown };
+  /** Overrides the configured home. */
+  store?: ObservationBaselineStoreConfig;
+}
+
+/** The home in effect: `CHANT_OBSERVATION_BASELINE_STORE` over `observationBaseline` over `file`. */
+export function observationBaselineStoreConfig(
+  configured?: unknown,
+  env: Record<string, string | undefined> = process.env,
+): ObservationBaselineStoreConfig {
+  const base = (configured && typeof configured === "object" ? configured : {}) as Partial<ObservationBaselineStoreConfig>;
+  const kind = (env.CHANT_OBSERVATION_BASELINE_STORE?.trim() || base.store || "file") as ObservationBaselineStoreKind;
+  if (!BASELINE_KINDS.includes(kind)) {
+    throw new Error(`observation baseline store "${kind}" is not one of ${BASELINE_KINDS.join(", ")}`);
+  }
+  return { ...(base.store === kind ? base : {}), store: kind };
+}
+
+async function resolveLocation(
+  opts?: ObservationBaselineLocation,
+): Promise<{ cwd: string; projectDir: string; store: ObservationBaselineStoreConfig; snapshots?: unknown }> {
+  const cwd = resolve(opts?.cwd ?? process.cwd());
+  const { findProjectConfigPastFragments, loadChantConfigUpward } = await import("../config");
+  let config: ObservationBaselineLocation["config"] = opts?.config;
+  if (!opts?.store && config === undefined) {
+    try {
+      config = (await loadChantConfigUpward(cwd)).config;
+    } catch {
+      config = undefined;
+    }
+  }
+  // The `file` home is relative to the project, not to wherever the command
+  // ran: a run from a member's subdirectory writes under that member's own
+  // directory, as every other store writes under its member path (#2538).
+  const projectDir = findProjectConfigPastFragments(cwd).dir;
+  return { cwd, projectDir, store: opts?.store ?? observationBaselineStoreConfig(config?.observationBaseline), snapshots: config?.snapshots };
+}
+
+/** The `file` home's path for one environment, under the project directory. */
+function baselineFile(projectDir: string, store: ObservationBaselineStoreConfig, env: string): string {
+  return join(projectDir, store.dir ?? OBSERVATION_BASELINE_DIR, `${env}.json`);
+}
+
+async function s3For(store: ObservationBaselineStoreConfig, snapshots: unknown) {
+  const { S3Medium } = await import("./snapshot-store-s3");
+  const { snapshotStoreConfig } = await import("./snapshot-store");
+  let settings = store.s3;
+  if (!settings) {
+    const snap = snapshotStoreConfig(snapshots);
+    if (snap.store !== "s3") throw new Error("the s3 observation baseline store needs observationBaseline.s3, or a snapshots store that is s3");
+    const { store: _s, ...rest } = snap;
+    settings = rest;
+  }
+  return new S3Medium(settings);
+}
+
+/** Where a baseline for `environment` lives in the configured home, for messages. */
+export async function observationBaselineWhere(environment: string, opts?: ObservationBaselineLocation): Promise<string> {
+  const { cwd, store, snapshots } = await resolveLocation(opts);
+  switch (store.store) {
+    case "file":
+      return join(store.dir ?? OBSERVATION_BASELINE_DIR, `${encodeIndexSegment(environment)}.json`);
+    case "git-ref":
+      return `${store.ref ?? OBSERVATION_BASELINE_REF}:${await ledgerDir(encodeIndexSegment(environment), { cwd })}.json`;
+    case "s3":
+      return `${(await s3For(store, snapshots)).where}/observation-baseline/${await ledgerDir(encodeIndexSegment(environment), { cwd })}.json`;
+    case "none":
+      return "nowhere (the observation baseline store is none)";
+  }
+}
 
 /**
- * Read the accepted baseline for an environment. Returns `null` when the branch,
- * the environment, or the file does not exist — every one of which means
- * "nothing accepted yet", the normal state before anyone runs
- * `--update-baseline`.
+ * Read the accepted baseline for an environment. Returns `null` when there is
+ * none, the normal state before anyone runs `--update-baseline`. When the
+ * configured home has none, a baseline written before #4519 on the
+ * `chant/lifecycle` branch is read instead.
  */
 export async function readObservationBaseline(
   environment: string,
-  opts?: { cwd?: string },
+  opts?: ObservationBaselineLocation,
 ): Promise<ObservationBaseline | null> {
-  return parseBaseline(await readBlobFromPath(environment, OBSERVATION_BASELINE_FILE, opts));
+  const { cwd, projectDir, store, snapshots } = await resolveLocation(opts);
+  let text: string | null = null;
+  switch (store.store) {
+    case "none":
+      return null;
+    case "file":
+      try {
+        text = readFileSync(baselineFile(projectDir, store, encodeIndexSegment(environment)), "utf8");
+      } catch {
+        text = null;
+      }
+      break;
+    case "git-ref": {
+      const { getRuntime } = await import("../runtime-adapter");
+      const path = `${await ledgerDir(encodeIndexSegment(environment), { cwd })}.json`;
+      const r = await getRuntime().spawn(["git", "cat-file", "blob", `${store.ref ?? OBSERVATION_BASELINE_REF}:${path}`], { cwd });
+      text = r.exitCode === 0 ? r.stdout : null;
+      break;
+    }
+    case "s3":
+      text = await (await s3For(store, snapshots)).get(`observation-baseline/${await ledgerDir(encodeIndexSegment(environment), { cwd })}.json`);
+      break;
+  }
+  return parseBaseline(text ?? (await readBlobFromPath(environment, OBSERVATION_BASELINE_FILE, { cwd })));
 }
 
-/** Write the accepted baseline to the orphan branch. Returns the new commit SHA. */
+/** What {@link saveObservationBaseline} did. `file` means written in the working tree, for the caller to commit. */
+export interface SavedObservationBaseline {
+  where: string;
+  published: "file" | "pushed" | "local" | "failed" | "none";
+  detail?: string;
+}
+
+/** Write the accepted baseline to its home, and push it when the home is a ref. */
+export async function saveObservationBaseline(
+  baseline: ObservationBaseline,
+  opts?: ObservationBaselineLocation,
+): Promise<SavedObservationBaseline> {
+  const { cwd, projectDir, store, snapshots } = await resolveLocation(opts);
+  const where = await observationBaselineWhere(baseline.environment, { cwd, store, ...(snapshots !== undefined ? { config: { snapshots } } : {}) });
+  const content = serializeBaseline(baseline);
+  const env = encodeIndexSegment(baseline.environment);
+  switch (store.store) {
+    case "none":
+      return { where, published: "none" };
+    case "file": {
+      const file = baselineFile(projectDir, store, env);
+      mkdirSync(dirname(file), { recursive: true });
+      const tmp = `${file}.${process.pid}.tmp`;
+      writeFileSync(tmp, content);
+      renameSync(tmp, file);
+      return { where, published: "file" };
+    }
+    case "git-ref": {
+      const { commitFilesToRef, publishRef } = await import("./snapshot-store");
+      const ref = store.ref ?? OBSERVATION_BASELINE_REF;
+      const path = `${await ledgerDir(env, { cwd })}.json`;
+      await commitFilesToRef(ref, [{ path, content }], "Accepted observation baseline", { cwd });
+      const pushed = await publishRef(ref, new Map([[path, content]]), "Accepted observation baseline", { cwd });
+      return { where, published: pushed.status === "pushed" ? "pushed" : pushed.status === "local" ? "local" : "failed", ...(pushed.detail ? { detail: pushed.detail } : {}) };
+    }
+    case "s3":
+      await (await s3For(store, snapshots)).put(`observation-baseline/${await ledgerDir(env, { cwd })}.json`, content);
+      return { where, published: "pushed" };
+  }
+}
+
+/** Write the accepted baseline to its home. Returns where it went. */
 export async function writeObservationBaseline(
   baseline: ObservationBaseline,
-  opts?: { cwd?: string },
+  opts?: ObservationBaselineLocation,
 ): Promise<string> {
-  return writeBlobToPath(
-    baseline.environment,
-    OBSERVATION_BASELINE_FILE,
-    serializeBaseline(baseline),
-    "Accepted observation baseline",
-    opts,
-  );
+  return (await saveObservationBaseline(baseline, opts)).where;
 }

package/src/lifecycle/observe.ts

@@ -96,6 +96,8 @@ function qualifyObservation(obs: NormalizedObservation, stackName: string): Norm
     notes: obs.notes,
     // Exports are already keyed by stack (#1279); nothing to qualify.
     ...(obs.stackExports ? { stackExports: obs.stackExports } : {}),
+    // Edge endpoints are resource ids, so they re-key with them (#4528).
+    ...(obs.edges ? { edges: obs.edges.map((e) => ({ ...e, from: `${stackName}::${e.from}`, to: `${stackName}::${e.to}` })) } : {}),
   };
 }
 
@@ -518,13 +520,16 @@ function pushObservation(
   // Dependencies ride alongside the managed resources so they become nodes, and
   // carry `referencedBy` so every consumer can still tell the two apart.
   const hasDependencies = Object.keys(dependencies.resources).length > 0;
+  // The read's own edges (#4528, an engine's graph) and the dependency
+  // closure's ride together; `buildLiveGraphIr` dedupes them.
+  const edges = [...(observed.edges ?? []), ...dependencies.edges];
   observations.push({
     lexicon,
     resources: hasDependencies
       ? { ...observed.resources, ...dependencies.resources }
       : observed.resources,
     ...(unobservedNames.length > 0 ? { unobserved: observed.unobserved } : {}),
-    ...(dependencies.edges.length > 0 ? { edges: dependencies.edges } : {}),
+    ...(edges.length > 0 ? { edges } : {}),
     ...(observed.stackExports && Object.keys(observed.stackExports).length > 0
       ? { stackExports: observed.stackExports }
       : {}),