@intentius/chant 0.38.0 → 0.41.0

package/src/lexicon-config.ts

@@ -0,0 +1,92 @@
+/**
+ * The config namespace a lexicon owns (#1344).
+ *
+ * Three lexicons read a top-level `chant.config.ts` key named after themselves —
+ * `k8s.profiles.<env>.context`, `temporal.profiles`, `forgejo.runnerLabels` and
+ * `forgejo.actionsRoot` — all documented for users, none declared anywhere.
+ * `ChantConfigSchema` is `.passthrough()`, so at runtime any key is accepted and
+ * a typo is silently ignored: write `runnerLabel` and the Forgejo dialect just
+ * uses its defaults, with nothing said. The `ChantConfig` interface is closed,
+ * so the documented forgejo example did not even compile:
+ *
+ *     error TS2353: Object literal may only specify known properties,
+ *     and 'forgejo' does not exist in type 'ChantConfig'.
+ *
+ * Three lexicons had arrived at three different workarounds: temporal exported
+ * its own widened `TemporalChantConfig`, k8s's docs dropped `satisfies`, and
+ * forgejo's kept it and were wrong.
+ *
+ * A lexicon now declares the shape of its namespace. The declaration is both
+ * halves of the fix at once: core validates against it at load, and the lexicon
+ * derives the type it augments `ChantConfig` with from the same schema, so the
+ * runtime rule and the compile-time one cannot disagree.
+ */
+
+import type { ZodObject, ZodRawShape } from "zod";
+import type { ChantConfig } from "./config";
+
+/**
+ * A lexicon's config schema. A `ZodObject` specifically, so core can apply
+ * `.strict()` itself rather than trusting each lexicon to remember — an unknown
+ * key at the top of a declared namespace is a typo, and silently ignoring it is
+ * the behavior this replaces.
+ *
+ * Nested objects are the lexicon's own responsibility: author them with
+ * `z.strictObject` so a typo in `k8s.profiles.prod.contxt` fails too. `.strict()`
+ * applies to one level.
+ */
+export type LexiconConfigSchema = ZodObject<ZodRawShape>;
+
+/** What a lexicon needs to expose for its namespace to be validated. */
+export interface ConfigOwningLexicon {
+  name: string;
+  configSchema?: LexiconConfigSchema;
+}
+
+export interface LexiconConfigProblem {
+  /** The lexicon whose namespace failed. */
+  lexicon: string;
+  /** Dotted path to the offending value, e.g. `forgejo.runnerLabel`. */
+  path: string;
+  message: string;
+}
+
+/**
+ * Validate each lexicon's own namespace against the schema it declares.
+ *
+ * A lexicon that declares nothing keeps today's passthrough — silence for an
+ * unknown key — because tightening a namespace nobody described would fail
+ * configs that are working. Declaring is the opt-in.
+ *
+ * An absent namespace is not a problem: every one of them is optional.
+ */
+export function validateLexiconConfig(
+  lexicons: readonly ConfigOwningLexicon[],
+  config: ChantConfig | undefined,
+): LexiconConfigProblem[] {
+  if (!config) return [];
+  const problems: LexiconConfigProblem[] = [];
+  const raw = config as unknown as Record<string, unknown>;
+
+  for (const lexicon of lexicons) {
+    const schema = lexicon.configSchema;
+    if (!schema) continue;
+    const value = raw[lexicon.name];
+    if (value === undefined) continue;
+
+    const result = schema.strict().safeParse(value);
+    if (result.success) continue;
+
+    for (const issue of result.error.issues) {
+      const path = [lexicon.name, ...issue.path.map(String)].join(".");
+      problems.push({ lexicon: lexicon.name, path, message: issue.message });
+    }
+  }
+
+  return problems;
+}
+
+/** One line per problem, for a CLI error. */
+export function formatLexiconConfigProblems(problems: readonly LexiconConfigProblem[]): string {
+  return problems.map((p) => `  ${p.path}: ${p.message}`).join("\n");
+}

package/src/lexicon.ts

@@ -10,6 +10,7 @@ import type { McpToolContribution, McpResourceContribution } from "./mcp/types";
 import type { DriverComponent } from "./components/driver";
 import type { EmulatorDeclaration } from "./op/emulator-lifecycle";
 import type { OwnershipChannel } from "./ownership";
+import type { LexiconConfigSchema } from "./lexicon-config";
 import type { RuleMeta } from "./audit/catalog";
 import type { ReferenceCatalog } from "./graph-refs";
 import type { IREdge } from "./graph-ir";
@@ -440,6 +441,25 @@ export interface LexiconPlugin {
   /** Package lexicon into distributable tarball */
   package(options?: { verbose?: boolean; force?: boolean }): Promise<void>;
 
+  /**
+   * The shape of this lexicon's own `chant.config.ts` namespace — the top-level
+   * key named after the lexicon (#1344).
+   *
+   * k8s reads `k8s.profiles.<env>.context`, temporal `temporal.profiles`,
+   * forgejo `forgejo.runnerLabels` and `forgejo.actionsRoot`. All were
+   * documented for users and declared nowhere: the config schema is
+   * `.passthrough()`, so a typo was accepted and silently ignored, and the
+   * `ChantConfig` interface is closed, so the documented examples did not
+   * compile.
+   *
+   * Declaring the schema makes an unknown key inside the namespace an error
+   * rather than a default, and gives the lexicon a single source to derive the
+   * type it augments `ChantConfig` with — so the runtime rule and the
+   * compile-time one cannot disagree. Omit it and the namespace keeps today's
+   * passthrough.
+   */
+  readonly configSchema?: LexiconConfigSchema;
+
   /**
    * Local emulator(s) (#920), if this lexicon has any: Floci for aws, floci-az
    * for azure, floci-gcp for gcp, mudflaps and spritzer for fly. Drives

package/src/lifecycle/deep-diff.test.ts

@@ -4,7 +4,7 @@ import { UNRESOLVED, type NormalizedDeepObservation } from "../deep-observation"
 import type { BaselineLexicon } from "./observation-baseline";
 
 const live = (
-  resources: Record<string, { type: string; properties: Record<string, unknown> }>,
+  resources: Record<string, { type: string; properties: Record<string, unknown>; fieldOwners?: Record<string, string> }>,
   unobserved: NormalizedDeepObservation["unobserved"] = {},
 ): NormalizedDeepObservation => ({ resources, unobserved });
 
@@ -155,3 +155,50 @@ describe("diffDeep with an accepted baseline", () => {
     expect(result.drifted[0].changes.map((c) => c.path)).toEqual(["Extra"]);
   });
 });
+
+// #1189 — `kind` says a path is undeclared or changed; `owner` says who did it.
+// The two are independent: `hpa-controller` owning `spec.replicas` and somebody
+// running `kubectl edit` are the same kind and opposite situations.
+describe("diffDeep — owning field manager (#1189)", () => {
+  const declared = { web: { type: "K8s::Apps::Deployment", properties: { spec: { replicas: 2 } } } };
+
+  test("names the manager on a drifted path", () => {
+    const result = diffDeep({
+      declared,
+      live: live({
+        web: {
+          type: "K8s::Apps::Deployment",
+          properties: { spec: { replicas: 5 } },
+          fieldOwners: { "spec.replicas": "hpa-controller" },
+        },
+      }),
+    });
+    expect(result.drifted[0].changes[0]).toMatchObject({
+      path: "spec.replicas",
+      kind: "changed",
+      owner: "hpa-controller",
+    });
+  });
+
+  test("is absent when the substrate records no per-field ownership", () => {
+    // Every substrate but k8s. The field must not appear at all rather than
+    // appear empty — a consumer branches on its presence.
+    const result = diffDeep({
+      declared,
+      live: live({ web: { type: "K8s::Apps::Deployment", properties: { spec: { replicas: 5 } } } }),
+    });
+    expect(result.drifted[0].changes[0]).not.toHaveProperty("owner");
+  });
+
+  test("is absent for a path with no live value — nobody owns a field that is not there", () => {
+    const result = diffDeep({
+      declared,
+      live: live({
+        web: { type: "K8s::Apps::Deployment", properties: {}, fieldOwners: { "spec.replicas": "someone" } },
+      }),
+    });
+    const change = result.drifted[0].changes.find((c) => c.path === "spec.replicas")!;
+    expect(change.kind).toBe("absent");
+    expect(change).not.toHaveProperty("owner");
+  });
+});

package/src/lifecycle/deep-diff.ts

@@ -59,6 +59,17 @@ export interface PropertyDrift {
    * accepted value there would lose the most useful column in the report.
    */
   baseline?: unknown;
+  /**
+   * The field manager that owns this path live, where the substrate records one
+   * (#1189) — Kubernetes' `managedFields`, and nowhere else today.
+   *
+   * `kind` says a path is `undeclared` or `changed`; this says who did it.
+   * "Owned by `kubectl-client-side-apply`" and "owned by `hpa-controller`" are
+   * the same `kind` and mean opposite things: one is somebody bypassing the
+   * pipeline, the other is a controller doing its job. Absent on a substrate
+   * with no per-field ownership, which is every substrate but k8s.
+   */
+  owner?: string;
 }
 
 /** Property-level drift for one declared entity. */
@@ -173,11 +184,16 @@ export function diffDeep(input: DiffDeepInput): DeepDiffResult {
       if (hasDeclared && hasLive && deepValueEqual(declaredValue, liveValue)) continue;
 
       const kind: PropertyDriftKind = !hasDeclared ? "undeclared" : !hasLive ? "absent" : "changed";
+      // Who owns the path live, where the substrate records it (#1189). Only
+      // meaningful for a path that exists live — an `absent` drift has no live
+      // field for anyone to own.
+      const owner = hasLive ? liveEntity.fieldOwners?.[path] : undefined;
       const drift: PropertyDrift = {
         path,
         kind,
         ...(hasDeclared ? { declared: declaredValue } : {}),
         ...(hasLive ? { live: liveValue } : {}),
+        ...(owner ? { owner } : {}),
       };
 
       const acceptedEntry = acceptedDeviation(baseline, name, path);

package/src/lifecycle/digest.test.ts

@@ -115,3 +115,84 @@ describe("diffDigests", () => {
     expect(result.removed.sort()).toEqual(["c"]);
   });
 });
+
+/**
+ * chant #1442 — a digest records what interpreted the declarations, not only
+ * what was declared.
+ */
+function withVersions(versions: Record<string, string> | undefined): BuildResult {
+  const result = makeBuildResult({ k8s: [{ name: "app", type: "K8s::Apps::Deployment", props: { replicas: 2 } }] });
+  return { ...result, lexiconVersions: versions } as unknown as BuildResult;
+}
+
+describe("computeBuildDigest — lexicon versions (#1442)", () => {
+  test("records the version of each lexicon that served the build", () => {
+    expect(computeBuildDigest(withVersions({ k8s: "0.38.0" })).lexiconVersions).toEqual({ k8s: "0.38.0" });
+  });
+
+  test("records once per lexicon, not once per resource", () => {
+    const many = makeBuildResult({
+      k8s: [
+        { name: "a", type: "K8s::Apps::Deployment", props: {} },
+        { name: "b", type: "K8s::Core::Service", props: {} },
+      ],
+    });
+    const digest = computeBuildDigest({ ...many, lexiconVersions: { k8s: "0.38.0" } } as unknown as BuildResult);
+    expect(Object.keys(digest.resources)).toHaveLength(2);
+    expect(digest.lexiconVersions).toEqual({ k8s: "0.38.0" });
+  });
+
+  test("a build with no plugins records an empty map, not absence", () => {
+    // Absent and empty mean different things when read back: absent is
+    // "recorded before #1442", empty is "recorded, nothing loaded".
+    expect(computeBuildDigest(withVersions(undefined)).lexiconVersions).toEqual({});
+  });
+
+  test("the recorded map is a copy, so later mutation cannot rewrite history", () => {
+    const versions = { k8s: "0.38.0" };
+    const digest = computeBuildDigest(withVersions(versions));
+    versions.k8s = "0.39.0";
+    expect(digest.lexiconVersions).toEqual({ k8s: "0.38.0" });
+  });
+});
+
+describe("diffDigests — lexicon version changes (#1442)", () => {
+  const resources = { app: { type: "K8s::Apps::Deployment", lexicon: "k8s", propsHash: "same" } };
+  const digest = (lexiconVersions?: Record<string, string>): BuildDigest =>
+    ({ resources, dependencies: {}, outputs: {}, deployOrder: ["k8s"], lexiconVersions }) as BuildDigest;
+
+  test("reports a bump even when every resource is unchanged", () => {
+    const diff = diffDigests(digest({ k8s: "0.39.0" }), digest({ k8s: "0.38.0" }));
+    expect(diff.changed).toEqual([]);
+    expect(diff.unchanged).toEqual(["app"]);
+    expect(diff.lexiconVersionChanges).toEqual([{ lexicon: "k8s", previous: "0.38.0", current: "0.39.0" }]);
+  });
+
+  test("reports nothing when versions match", () => {
+    expect(diffDigests(digest({ k8s: "0.38.0" }), digest({ k8s: "0.38.0" })).lexiconVersionChanges).toEqual([]);
+  });
+
+  test("reports a lexicon added to or dropped from the build", () => {
+    const added = diffDigests(digest({ k8s: "0.38.0", aws: "0.38.0" }), digest({ k8s: "0.38.0" }));
+    expect(added.lexiconVersionChanges).toEqual([{ lexicon: "aws", previous: undefined, current: "0.38.0" }]);
+
+    const dropped = diffDigests(digest({ k8s: "0.38.0" }), digest({ k8s: "0.38.0", aws: "0.38.0" }));
+    expect(dropped.lexiconVersionChanges).toEqual([{ lexicon: "aws", previous: "0.38.0", current: undefined }]);
+  });
+
+  test("a pre-#1442 snapshot reports no change rather than inventing one", () => {
+    // The older digest never recorded versions. Every lexicon would otherwise
+    // look newly-added on the first comparison after upgrading chant.
+    expect(diffDigests(digest({ k8s: "0.38.0" }), digest(undefined)).lexiconVersionChanges).toEqual([]);
+    expect(diffDigests(digest(undefined), digest({ k8s: "0.38.0" })).lexiconVersionChanges).toEqual([]);
+  });
+
+  test("with no previous digest at all, there is no version change", () => {
+    expect(diffDigests(digest({ k8s: "0.38.0" }), undefined).lexiconVersionChanges).toEqual([]);
+  });
+
+  test("changes are ordered by lexicon name, so output is stable", () => {
+    const diff = diffDigests(digest({ k8s: "2", aws: "2", gcp: "2" }), digest({ k8s: "1", aws: "1", gcp: "1" }));
+    expect(diff.lexiconVersionChanges.map((c) => c.lexicon)).toEqual(["aws", "gcp", "k8s"]);
+  });
+});

package/src/lifecycle/digest.ts

@@ -41,6 +41,10 @@ export function computeBuildDigest(buildResult: BuildResult): BuildDigest {
 
   return {
     resources,
+    // chant #1442 — what interpreted the declarations, alongside what was
+    // declared. Always present on a freshly computed digest, so "absent"
+    // unambiguously means "recorded before #1442".
+    lexiconVersions: { ...buildResult.lexiconVersions },
     dependencies,
     outputs: buildResult.manifest.outputs,
     deployOrder: buildResult.manifest.deployOrder,
@@ -60,9 +64,10 @@ export function diffDigests(
   const unchanged: string[] = [];
 
   if (!previous) {
-    // No previous digest — everything is added
+    // No previous digest — everything is added, and there is no version to
+    // have moved away from.
     added.push(...Object.keys(current.resources));
-    return { added, removed, changed, unchanged };
+    return { added, removed, changed, unchanged, lexiconVersionChanges: [] };
   }
 
   // Check current resources against previous
@@ -84,5 +89,31 @@ export function diffDigests(
     }
   }
 
-  return { added, removed, changed, unchanged };
+  return { added, removed, changed, unchanged, lexiconVersionChanges: diffLexiconVersions(current, previous) };
+}
+
+/**
+ * Lexicons whose version moved between two digests (chant #1442).
+ *
+ * A digest recorded before this existed has no `lexiconVersions` at all. That
+ * is reported as no change rather than as every lexicon appearing — comparing
+ * against an older snapshot must not manufacture a difference that the older
+ * build simply never recorded.
+ */
+function diffLexiconVersions(
+  current: BuildDigest,
+  previous: BuildDigest,
+): Array<{ lexicon: string; previous?: string; current?: string }> {
+  if (!current.lexiconVersions || !previous.lexiconVersions) return [];
+
+  const changes: Array<{ lexicon: string; previous?: string; current?: string }> = [];
+  for (const lexicon of new Set([
+    ...Object.keys(current.lexiconVersions),
+    ...Object.keys(previous.lexiconVersions),
+  ])) {
+    const now = current.lexiconVersions[lexicon];
+    const before = previous.lexiconVersions[lexicon];
+    if (now !== before) changes.push({ lexicon, previous: before, current: now });
+  }
+  return changes.sort((a, b) => a.lexicon.localeCompare(b.lexicon));
 }

package/src/lifecycle/identity.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from "vitest";
+import { regionOf, unqualifiedKey } from "./identity";
+
+describe("regionOf", () => {
+  it("reads the region a lexicon stamped", () => {
+    expect(regionOf({ attributes: { region: "us-west-1" } })).toBe("us-west-1");
+  });
+
+  it("treats a missing, empty or non-string region as none", () => {
+    expect(regionOf({})).toBeUndefined();
+    expect(regionOf({ attributes: {} })).toBeUndefined();
+    expect(regionOf({ attributes: { region: "" } })).toBeUndefined();
+    expect(regionOf({ attributes: { region: 1 } })).toBeUndefined();
+  });
+});
+
+describe("unqualifiedKey", () => {
+  it("carries the region when there is one", () => {
+    expect(unqualifiedKey("sg-1", { attributes: { region: "us-east-1" } })).toBe("us-east-1::sg-1");
+  });
+
+  it("leaves an id with no region bare", () => {
+    expect(unqualifiedKey("arn:aws:iam::1:policy/p", {})).toBe("arn:aws:iam::1:policy/p");
+  });
+
+  it("is idempotent, so a second pass does not double-qualify", () => {
+    const meta = { attributes: { region: "us-east-1" } };
+    expect(unqualifiedKey(unqualifiedKey("sg-1", meta), meta)).toBe("us-east-1::sg-1");
+  });
+
+  it("qualifies an id that already carries a DIFFERENT region", () => {
+    // Not a case the readers produce, but the guard is a prefix test and it
+    // should not silently accept `us-west-1::sg-1` as already being in
+    // us-east-1.
+    expect(unqualifiedKey("us-west-1::sg-1", { attributes: { region: "us-east-1" } })).toBe(
+      "us-east-1::us-west-1::sg-1",
+    );
+  });
+});

package/src/lifecycle/identity.ts

@@ -0,0 +1,61 @@
+/**
+ * What makes an unqualified resource one resource (#1416).
+ *
+ * Managed resources are stack-qualified (`${stack}::${id}`, #1162) and cannot
+ * collide. Everything else — dependencies (#1273) and ambient resources (#1278)
+ * — is keyed by physical id and merged across stacks, because the account's
+ * default VPC route table is one resource however many stacks route through it.
+ *
+ * That is right for a resource that really is account-level, and wrong for a
+ * regional one. A VPC, subnet or security group in `us-west-1` is a different
+ * resource from one in `us-east-1`, and merging them by id drops all but the
+ * first sighting.
+ *
+ * On AWS the difference is invisible: VPC, subnet and security-group ids are
+ * globally unique, so keying by id and keying by (region, id) give the same
+ * answer. It shows up against an emulator that reuses ids across regions
+ * (lex00/floci#21), where a three-region estate's nine default subnets merged
+ * to three and "how many subnets are empty" came back 2 instead of 8.
+ *
+ * The rule is deliberately not a table of regional kinds. A lexicon stamps a
+ * region on a resource when region is part of that resource's identity — the
+ * AWS lexicon does it in `stampRegion` for ambient resources and its own
+ * property reads — and this reads that stamp back. A genuinely account-level
+ * resource carries no region and keeps merging as it always did, which is why
+ * dependencies (never stamped) are untouched by this.
+ */
+
+import type { ResourceMetadata } from "../lexicon";
+
+/**
+ * The region a resource records itself as being in, if it records one.
+ *
+ * Read from `attributes.region`, which is where a lexicon stamps it. Absent
+ * means the resource is account-level, or the lexicon has no region to give —
+ * both of which are read the same way, as "region is not part of this id".
+ */
+export function regionOf(meta: Pick<ResourceMetadata, "attributes">): string | undefined {
+  const region = meta.attributes?.region;
+  return typeof region === "string" && region.length > 0 ? region : undefined;
+}
+
+/**
+ * The key an unqualified resource merges under.
+ *
+ * `${region}::${id}` for a resource that carries a region, matching the shape
+ * stack qualification already uses, and the bare id for one that does not.
+ *
+ * Applied only where results from more than one region are actually merged —
+ * `collectAmbient` across stacks, `replaySnapshots` across recorded stacks.
+ * Recording one region's observation qualifies nothing, so a stored snapshot
+ * keeps the keys it has always had and the first snapshot taken after this
+ * lands does not diff as "every ambient resource replaced".
+ *
+ * Idempotent, so an id that already carries this region survives a second pass
+ * unchanged rather than becoming `us-east-1::us-east-1::sg-1`.
+ */
+export function unqualifiedKey(id: string, meta: Pick<ResourceMetadata, "attributes">): string {
+  const region = regionOf(meta);
+  if (!region) return id;
+  return id.startsWith(`${region}::`) ? id : `${region}::${id}`;
+}

package/src/lifecycle/observe.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from "vitest";
-import { observeResources } from "./observe";
+import { observeResources, collectAmbient } from "./observe";
 import { observation } from "../observation";
 import type { ObservationLexicon, ResourceMetadata } from "../lexicon";
 import type { BuildResult } from "../build";
@@ -246,3 +246,77 @@ describe("observeResources", () => {
     expect(calls[0]).not.toHaveProperty("stack");
   });
 });
+
+describe("collectAmbient — one resource per region, not per account (#1416)", () => {
+  const subnets = (region: string): Record<string, ResourceMetadata> =>
+    Object.fromEntries(
+      ["subnet-default-a", "subnet-default-b"].map((id) => [
+        id,
+        {
+          type: "AWS::EC2::Subnet",
+          status: "OBSERVED",
+          physicalId: id,
+          ambient: true,
+          attributes: { region },
+        } as ResourceMetadata,
+      ]),
+    );
+
+  function ambientPlugin(): ObservationLexicon {
+    return {
+      name: "aws",
+      describeResources: async () => ({}),
+      observeAmbient: async (opts: { region?: string }) => subnets(opts.region ?? "us-east-1"),
+    } as unknown as ObservationLexicon;
+  }
+
+  it("keeps every region's copy when the ids collide across regions", async () => {
+    const found = await collectAmbient(ambientPlugin(), {
+      environment: "prod",
+      kinds: ["AWS::EC2::Subnet"],
+      observed: {},
+      stacks: [
+        { name: "east", region: "us-east-1" },
+        { name: "west1", region: "us-west-1" },
+        { name: "west2", region: "us-west-2" },
+      ],
+      warnings: [],
+    });
+    expect(Object.keys(found).sort()).toEqual([
+      "us-east-1::subnet-default-a",
+      "us-east-1::subnet-default-b",
+      "us-west-1::subnet-default-a",
+      "us-west-1::subnet-default-b",
+      "us-west-2::subnet-default-a",
+      "us-west-2::subnet-default-b",
+    ]);
+  });
+
+  it("still merges two stacks in the same region to one resource each", async () => {
+    const found = await collectAmbient(ambientPlugin(), {
+      environment: "prod",
+      kinds: ["AWS::EC2::Subnet"],
+      observed: {},
+      stacks: [
+        { name: "web", region: "us-east-1" },
+        { name: "api", region: "us-east-1" },
+      ],
+      warnings: [],
+    });
+    expect(Object.keys(found).sort()).toEqual([
+      "us-east-1::subnet-default-a",
+      "us-east-1::subnet-default-b",
+    ]);
+  });
+
+  it("leaves a single stack's ids bare — one region is not a merge", async () => {
+    const found = await collectAmbient(ambientPlugin(), {
+      environment: "prod",
+      kinds: ["AWS::EC2::Subnet"],
+      observed: {},
+      stacks: [{ name: "main", region: "us-east-1" }],
+      warnings: [],
+    });
+    expect(Object.keys(found).sort()).toEqual(["subnet-default-a", "subnet-default-b"]);
+  });
+});

package/src/lifecycle/observe.ts

@@ -24,6 +24,7 @@ import {
   type NormalizedObservation,
 } from "../observation";
 import { zeroResourcesWarning } from "../live-endpoint";
+import { unqualifiedKey } from "./identity";
 
 export interface ObserveResult {
   observations: LiveObservation[];
@@ -208,7 +209,21 @@ export async function observeResources(
             warnings,
           })
         : {};
-      for (const [id, meta] of Object.entries(ambient)) dependencies.resources[id] ??= meta;
+      // A resource can be reached as a dependency AND enumerated as ambient —
+      // the default VPC an instance sits in is both. It is one resource, and
+      // the dependency entry is the one carrying `referencedBy`, so it wins.
+      // Matched on physical id rather than on key, because ambient keys carry a
+      // region (#1416) and dependency keys do not, so the keys no longer
+      // collide even when the resource is the same one.
+      const dependedOn = new Set(
+        Object.values(dependencies.resources)
+          .map((m) => m.physicalId)
+          .filter((id): id is string => typeof id === "string"),
+      );
+      for (const [id, meta] of Object.entries(ambient)) {
+        if (meta.physicalId && dependedOn.has(meta.physicalId)) continue;
+        dependencies.resources[id] ??= meta;
+      }
       pushObservation(
         observations,
         warnings,
@@ -268,6 +283,11 @@ function scopeToStack(
  * Ask a lexicon what exists of the kinds it manages, beyond what is declared
  * (#1278). Once per stack for the region, merged by physical id — the same
  * ambient resource seen from two stacks is one resource.
+ *
+ * "The same" is per region (#1416). Two stacks in one region reporting the
+ * account's default security group is one group; two regions' default security
+ * groups are two, whatever their ids look like, so the merge key carries the
+ * region a resource records itself in.
  */
 export async function collectAmbient(
   plugin: ObservationLexicon,
@@ -282,6 +302,10 @@ export async function collectAmbient(
   if (!plugin.observeAmbient || opts.kinds.length === 0) return {};
   const found: Record<string, ResourceMetadata> = {};
   const refs = opts.stacks.length > 0 ? opts.stacks : [{ name: undefined, region: undefined }];
+  // Only a merge needs region-qualified keys, and one ref is not a merge. This
+  // is what keeps a single-region project's ids exactly what they were, and a
+  // recorded snapshot — always one stack, so always one ref — bare.
+  const merging = refs.length > 1;
   for (const ref of refs) {
     try {
       const part = await plugin.observeAmbient({
@@ -291,7 +315,9 @@ export async function collectAmbient(
         ...(ref.name ? { stack: ref.name } : {}),
         ...(ref.region ? { region: ref.region } : {}),
       });
-      for (const [id, meta] of Object.entries(part)) found[id] ??= meta;
+      for (const [id, meta] of Object.entries(part)) {
+        found[merging ? unqualifiedKey(id, meta) : id] ??= meta;
+      }
     } catch (err) {
       opts.warnings.push(
         `${plugin.name}: ambient resources not read${ref.name ? ` for stack "${ref.name}"` : ""} — ${err instanceof Error ? err.message : String(err)}`,