@intentius/chant 0.44.13 → 0.45.0

package/src/graph-ops.ts

@@ -0,0 +1,42 @@
+import { basename, resolve } from "node:path";
+import type { Declarable } from "./declarable";
+import { discoverOps } from "./op/discover";
+import { Op } from "./op/builders";
+import { setProvenance } from "./provenance";
+
+/**
+ * #1675 — the graph IR is built from `discover(sourceDir)`, but the Op
+ * convention keeps `*.op.ts` files OUTSIDE `sourceDir` (`ops/` or the project
+ * root beside `sourceDir: "src"`), and `chant op` / `chant graph` find them via
+ * {@link discoverOps}, which scans from the git root. Join the two scopes: every
+ * Op `discoverOps` finds that discovery did not already load becomes a
+ * `Temporal::Op` entity in the map, keyed the way discovery keys a default
+ * export (the file's basename sans `.op.ts`), so the IR carries the declared
+ * DAG whatever the layout. Ops discovery already loaded (same file) are left
+ * alone. Returns the op-discovery errors for the caller to surface.
+ */
+export async function mergeProjectOps(
+  entities: Map<string, Declarable>,
+  sourceFiles: readonly string[],
+  projectPath: string,
+): Promise<{ added: string[]; errors: string[] }> {
+  const added: string[] = [];
+  let found: Awaited<ReturnType<typeof discoverOps>>;
+  try {
+    found = await discoverOps({ cwd: projectPath });
+  } catch (err) {
+    // Not a git checkout — nothing beyond sourceDir to join.
+    return { added, errors: [err instanceof Error ? err.message : String(err)] };
+  }
+  const loaded = new Set(sourceFiles.map((f) => resolve(f)));
+  for (const { config, filePath } of found.ops.values()) {
+    if (loaded.has(resolve(filePath))) continue;
+    const key = basename(filePath).replace(/\.ts$/, "").replace(/\.op$/, "");
+    if (entities.has(key)) continue;
+    const entity = Op(config) as unknown as Declarable;
+    setProvenance(entity, { sourceFile: resolve(filePath) });
+    entities.set(key, entity);
+    added.push(key);
+  }
+  return { added, errors: found.errors };
+}

package/src/lifecycle/change-set.test.ts

@@ -346,6 +346,47 @@ describe("buildChangeSet: not-observed is not absent (#1089)", () => {
     expect(e.queried).toBe("from-entry");
   });
 
+  // #1674 — lexicon attribution and the provider's physical id per entry.
+  test("stamps every entry with the lexicon it was built for, when given one", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["web", "api"]),
+      observedNow: { web: meta(), "sg-0abc123": meta({ ownership: "foreign" }) },
+      observedThen: undefined,
+    }, { lexicon: "aws" });
+    expect(cs.entries.map((e) => e.lexicon)).toEqual(["aws", "aws", "aws"]);
+    const without = buildChangeSet("prod", { declared: new Set(["web"]), observedNow: {}, observedThen: undefined });
+    expect(without.entries[0]).not.toHaveProperty("lexicon");
+  });
+
+  test("physicalId comes from the live observation — name stays the lexicon's key", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["web"]),
+      observedNow: {
+        web: meta({ physicalId: "arn:aws:elasticloadbalancing:us-east-1:123:loadbalancer/app/web/abc" }),
+        "sg-0abc123": meta({ physicalId: "sg-0abc123", ownership: "foreign" }),
+        "pod-xyz": meta({ physicalId: "default/pod-xyz", ownerChain: { root: "declared", entity: "web" } }),
+        owned: meta({ physicalId: "i-0deadbeef", ownership: "owned" }),
+      },
+      observedThen: undefined,
+    });
+    const byName = Object.fromEntries(cs.entries.map((e) => [e.name, e]));
+    expect(byName.web.physicalId).toBe("arn:aws:elasticloadbalancing:us-east-1:123:loadbalancer/app/web/abc");
+    expect(byName["sg-0abc123"]).toMatchObject({ action: "adopt", physicalId: "sg-0abc123", name: "sg-0abc123" });
+    expect(byName["pod-xyz"]).toMatchObject({ action: "runtime", physicalId: "default/pod-xyz" });
+    expect(byName.owned).toMatchObject({ action: "delete", physicalId: "i-0deadbeef" });
+  });
+
+  test("physicalId is absent when no side reported one, and falls back to the snapshot's when the resource is gone", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["web"]),
+      observedNow: {},
+      observedThen: { gone: meta({ physicalId: "i-gone" }) },
+    });
+    const byName = Object.fromEntries(cs.entries.map((e) => [e.name, e]));
+    expect(byName.web).not.toHaveProperty("physicalId");
+    expect(byName.gone).toMatchObject({ action: "noop", physicalId: "i-gone" });
+  });
+
   test("a returned resource wins over an unobserved claim for the same name", () => {
     const cs = buildChangeSet("prod", {
       declared: new Set(["queue"]),

package/src/lifecycle/change-set.ts

@@ -45,10 +45,27 @@ export type ChangeAction = "create" | "update" | "delete" | "adopt" | "runtime"
 export type Ownership = "owned" | "foreign" | "unknown";
 
 export interface ChangeSetEntry {
-  /** chant entity name. */
+  /**
+   * chant entity name for a declared entity. For an undeclared live resource
+   * (`adopt`, `delete`, `runtime`) this is the lexicon's live key — not an
+   * IR-joinable entity name; read `physicalId` for the provider id (#1674).
+   */
   name: string;
   /** Resource type, when known from either side. */
   type?: string;
+  /**
+   * The lexicon whose observation produced this entry (#1674). Set when the
+   * change set is built for one lexicon; `lifecycle plan` merges every
+   * lexicon's change set into one `entries[]`, and this is what keeps the
+   * attribution through the merge.
+   */
+  lexicon?: string;
+  /**
+   * Provider-assigned physical id (ARN, resource id, pod name) from the live
+   * observation's `ResourceMetadata.physicalId`, falling back to the snapshot's
+   * when the resource is gone (#1674). Absent when neither side reported one.
+   */
+  physicalId?: string;
   action: ChangeAction;
   /** The three-way evidence the classification was derived from. */
   evidence: {
@@ -101,7 +118,12 @@ export interface ChangeSet {
  * classifies as `unobserved` and nothing else: no `create` is ever synthesized
  * from a read that did not happen.
  */
-export function buildChangeSet(env: string, input: DiffLiveInput): ChangeSet {
+export interface ChangeSetOptions {
+  /** Stamp every entry with the lexicon it was observed by (#1674). */
+  lexicon?: string;
+}
+
+export function buildChangeSet(env: string, input: DiffLiveInput, options?: ChangeSetOptions): ChangeSet {
   const diff = diffLive(input);
   const { declared, observedNow } = input;
   const observedThen = input.observedThen ?? {};
@@ -184,9 +206,15 @@ export function buildChangeSet(env: string, input: DiffLiveInput): ChangeSet {
     // classification above never reads it.
     const queried = unobservedEntry?.queried ?? input.queried?.[name];
 
+    // The provider's id for the row (#1674). Live first; the snapshot's only
+    // when the resource is no longer live (a snapshot-only noop).
+    const physicalId = observedNow[name]?.physicalId ?? observedThen[name]?.physicalId;
+
     entries.push({
       name,
       type,
+      ...(options?.lexicon ? { lexicon: options.lexicon } : {}),
+      ...(physicalId ? { physicalId } : {}),
       action,
       evidence,
       deltas,

package/src/lifecycle/deep-observe.ts

@@ -143,6 +143,10 @@ export function diffDeepObservation(
       normalizedLive[name] = {
         type: liveEntity.type || entity.entityType,
         ...(liveEntity.physicalId ? { physicalId: liveEntity.physicalId } : {}),
+        // Per-path owners (#1189) ride through unchanged; the diff looks them
+        // up by the flattened path, so a keyed list element (`[#name]`) has
+        // no owner today — its raw index path is what the reader recorded.
+        ...(liveEntity.fieldOwners ? { fieldOwners: liveEntity.fieldOwners } : {}),
         properties: normalizeDeepProperties(liveRaw, {
           entityType: liveEntity.type || entity.entityType,
           side: "live",

package/src/lifecycle/observe.ts

@@ -31,6 +31,14 @@ export interface ObserveResult {
   observations: LiveObservation[];
   warnings: string[];
   errors: string[];
+  /**
+   * Run-level notices from the lexicons (#1265), each said once however many
+   * stacks or lexicons reported it — "ownership filter unavailable on this
+   * read path" is the canonical one. Kept apart from `warnings`, which are
+   * per-entity, so a caller can print them where a note belongs: after the
+   * answer, not ahead of it.
+   */
+  notes: string[];
 }
 
 /**
@@ -43,7 +51,14 @@ export interface ObserveResult {
 function qualifyObservation(obs: NormalizedObservation, stackName: string): NormalizedObservation {
   const q = <T>(m: Record<string, T>): Record<string, T> =>
     Object.fromEntries(Object.entries(m).map(([k, v]) => [`${stackName}::${k}`, v]));
-  return { resources: q(obs.resources), unobserved: q(obs.unobserved), queried: q(obs.queried) };
+  return {
+    resources: q(obs.resources),
+    unobserved: q(obs.unobserved),
+    queried: q(obs.queried),
+    notes: obs.notes,
+    // Exports are already keyed by stack (#1279); nothing to qualify.
+    ...(obs.stackExports ? { stackExports: obs.stackExports } : {}),
+  };
 }
 
 /**
@@ -110,6 +125,7 @@ export async function observeResources(
   const observations: LiveObservation[] = [];
   const warnings: string[] = [];
   const errors: string[] = [];
+  const notes: string[] = [];
 
   for (const plugin of plugins) {
     if (!plugin.describeResources) continue;
@@ -200,6 +216,13 @@ export async function observeResources(
           }),
         );
       }
+      // Run-level notices (#1265): one line per distinct note per run,
+      // whatever the stack count. `mergeObservations` already folded the
+      // per-stack copies; this folds across lexicons.
+      for (const note of observed.notes) {
+        const line = `[${plugin.name}] ${note}`;
+        if (!notes.includes(line)) notes.push(line);
+      }
       // What the estate depends on but does not declare (#1273). Read after the
       // managed resources, because the declared observation is the closure's
       // roots — there is nothing to reference out from until it exists.
@@ -260,6 +283,7 @@ export async function observeResources(
           resources: {},
           unobserved: unobservedAll(entityNames, "read-failed", message, entities),
           queried: {},
+          notes: [],
         },
         environment,
         entityNames.length,
@@ -267,7 +291,7 @@ export async function observeResources(
     }
   }
 
-  return { observations, warnings, errors };
+  return { observations, warnings, errors, notes };
 }
 
 /**
@@ -451,5 +475,8 @@ function pushObservation(
       : observed.resources,
     ...(unobservedNames.length > 0 ? { unobserved: observed.unobserved } : {}),
     ...(dependencies.edges.length > 0 ? { edges: dependencies.edges } : {}),
+    ...(observed.stackExports && Object.keys(observed.stackExports).length > 0
+      ? { stackExports: observed.stackExports }
+      : {}),
   });
 }

package/src/lifecycle/replay.ts

@@ -177,6 +177,9 @@ export async function replaySnapshots(
       lexicon,
       resources,
       ...(edges.length > 0 ? { edges } : {}),
+      ...(snapshot.stackExports && Object.keys(snapshot.stackExports).length > 0
+        ? { stackExports: snapshot.stackExports }
+        : {}),
     });
     commit ||= snapshot.commit ?? "";
     // Report the OLDEST timestamp across stacks: a caller asking how stale this

package/src/lifecycle/snapshot.ts

@@ -140,6 +140,7 @@ export async function takeSnapshot(
     let resources: Record<string, ResourceMetadata> = {};
     let artifacts: Record<string, ArtifactMetadata> = {};
     let unobserved: Record<string, UnobservedEntity> = {};
+    let stackExports: Record<string, Record<string, unknown>> | undefined;
 
     try {
       if (plugin.describeResources) {
@@ -163,6 +164,7 @@ export async function takeSnapshot(
         // entity nobody could read must not be recorded as "was not there",
         // because the next diff would then read it back as absent.
         unobserved = observed.unobserved;
+        stackExports = observed.stackExports;
         for (const [name, entry] of Object.entries(unobserved)) {
           warnings.push(`${plugin.name}: not observed — ${formatUnobserved(name, entry)}`);
         }
@@ -258,6 +260,7 @@ export async function takeSnapshot(
         timestamp,
         resources: withDependencies,
         ...(dependencies.edges.length > 0 ? { edges: dependencies.edges } : {}),
+        ...(stackExports && Object.keys(stackExports).length > 0 ? { stackExports } : {}),
         ...(Object.keys(unobserved).length > 0 && { unobserved }),
         ...(Object.keys(artifacts).length > 0 && { artifacts }),
         // Only written when deep. An absent field means identity, which is what

package/src/lifecycle/types.ts

@@ -75,6 +75,13 @@ export interface LifecycleSnapshot {
    * relationships recorded" rather than "no relationships existed".
    */
   edges?: IREdge[];
+  /**
+   * What the deployed stack publishes (#1279), keyed by stack name — a
+   * CloudFormation stack's outputs. Recorded once here rather than on every
+   * resource's `attributes`, which is where they used to be copied. Absent on
+   * every snapshot written before this, and on a lexicon with no such notion.
+   */
+  stackExports?: Record<string, Record<string, unknown>>;
   /** Build digest at snapshot time — what was declared when this snapshot was taken */
   digest?: BuildDigest;
 }

package/src/lint/policy.ts

@@ -4,7 +4,8 @@
  * `policyGate` Op step runs this to gate an apply on the same checks.
  */
 import { resolve, dirname } from "node:path";
-import { loadChantConfigUpward } from "../config";
+import { loadChantConfigUpward, resolveOwnershipEnv, resolveOwnershipMarker } from "../config";
+import { resolveBuildParams } from "../build-params";
 import { resolveProjectLexicons, loadPlugins } from "../cli/plugins";
 import { build } from "../build";
 import { runPostSynthChecks, isPostSynthCheck } from "./post-synth";
@@ -86,9 +87,19 @@ export async function evaluateProjectPolicies(opts: {
   const loaded = await loadChantConfigUpward(buildPath);
   const config = loaded.config;
   const configDir = loaded.configPath ? dirname(loaded.configPath) : buildPath;
-  const env = opts.env ?? config.ownership?.env;
+  // #1396 — `ownership.env` may reference a build parameter, so the declared
+  // parameters are resolved first (from their env mappings and defaults, the
+  // same inputs an Op step has) and the build sees them too.
+  const params = resolveBuildParams(config.buildParams, { env: process.env });
+  if (params.errors.length > 0) {
+    throw new Error(`Build parameters did not resolve — cannot evaluate policy:\n  ${params.errors.join("\n  ")}`);
+  }
+  const env = opts.env ?? resolveOwnershipEnv(config, params.provenance);
 
-  const result = await build(buildPath, serializers);
+  const result = await build(buildPath, serializers, undefined, {
+    ownership: resolveOwnershipMarker(config, params.provenance),
+    buildParams: params.provenance,
+  });
   if (result.errors.length > 0) {
     throw new Error("Build failed — cannot evaluate policy on a broken build");
   }

package/src/managed-fields.test.ts

@@ -2,28 +2,16 @@ import { describe, test, expect } from "vitest";
 import {
   K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS,
   k8sListMapOrderKey,
+  K8S_SYSTEM_METADATA_PRUNE_PATTERNS,
   buildOwnershipSets,
-  pruneByOwnership,
-  type OwnershipSets,
 } from "./managed-fields";
-import { normalizeDeepProperties, type DeepNode } from "./deep-observation";
+import { normalizeDeepProperties } from "./deep-observation";
 
 /** The naming scheme both the k8s lexicon (via `@intentius/chant-k8s-client`'s `isChantFieldManager`) and gcp restate use in their own tests. */
 function isChantManager(manager: string | undefined): boolean {
   return !!manager && (manager === "chant" || manager.startsWith("chant:"));
 }
 
-function node(partial: Partial<DeepNode> & Pick<DeepNode, "path" | "pattern">): DeepNode {
-  return {
-    entityType: "Test::Entity",
-    key: partial.pattern,
-    value: undefined,
-    side: "live",
-    counterpart: "unknown",
-    ...partial,
-  };
-}
-
 describe("K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS — the generic Kubernetes object envelope", () => {
   test("covers status and the server-minted metadata fields", () => {
     for (const p of [
@@ -150,36 +138,21 @@ describe("buildOwnershipSets — resolving managedFields against live and declar
   });
 });
 
-describe("pruneByOwnership — the shared three-question rule", () => {
-  const sets: OwnershipSets = {
-    chantOwned: new Set(["metadata.labels.tier"]),
-    foreignOwned: new Set(["spec.replicas", "metadata.annotations.noise"]),
-    foreignContested: new Set(["spec.replicas"]),
-    owners: new Map([
-      ["metadata.labels.tier", "chant"],
-      ["spec.replicas", "hpa-controller"],
-      ["metadata.annotations.noise", "kube-controller-manager"],
-    ]),
-  };
-
-  test("never prunes the declared side", () => {
-    expect(pruneByOwnership(node({ path: "spec.replicas", pattern: "spec.replicas", side: "declared" }), sets)).toBe(false);
-  });
-
-  test("never prunes a chant-owned path", () => {
-    expect(pruneByOwnership(node({ path: "metadata.labels.tier", pattern: "metadata.labels.tier" }), sets)).toBe(false);
-  });
-
-  test("prunes a foreign-owned, uncontested (undeclared) path", () => {
-    expect(pruneByOwnership(node({ path: "metadata.annotations.noise", pattern: "metadata.annotations.noise" }), sets)).toBe(true);
-  });
-
-  test("keeps a foreign-owned, contested (declared) path", () => {
-    expect(pruneByOwnership(node({ path: "spec.replicas", pattern: "spec.replicas" }), sets)).toBe(false);
+describe("K8S_SYSTEM_METADATA_PRUNE_PATTERNS — what the controllers stamp, not what a human labels (#1191)", () => {
+  test("covers client-side apply bookkeeping, the Deployment controller's rollout counters and the controllers' selector labels", () => {
+    for (const p of [
+      "metadata.annotations.kubectl.kubernetes.io/last-applied-configuration",
+      "metadata.annotations.deployment.kubernetes.io/revision",
+      "metadata.labels.pod-template-hash",
+      "metadata.labels.controller-revision-hash",
+    ]) {
+      expect(K8S_SYSTEM_METADATA_PRUNE_PATTERNS.has(p)).toBe(true);
+    }
   });
 
-  test("leaves a path with no ownership information alone (never pruned by this rule)", () => {
-    expect(pruneByOwnership(node({ path: "spec.selector", pattern: "spec.selector" }), sets)).toBe(false);
+  test("an out-of-band user label is not on the list — it has to reach the diff as undeclared", () => {
+    expect(K8S_SYSTEM_METADATA_PRUNE_PATTERNS.has("metadata.labels.team")).toBe(false);
+    expect(K8S_SYSTEM_METADATA_PRUNE_PATTERNS.has("metadata.annotations.kubernetes.io/change-cause")).toBe(false);
   });
 });
 

package/src/managed-fields.ts

@@ -142,17 +142,18 @@ export interface OwnershipSets {
   chantOwned: ReadonlySet<string>;
   /** Paths owned by a manager that is not chant. */
   foreignOwned: ReadonlySet<string>;
-  /** The subset of `foreignOwned` where the declared manifest also sets the path — drift-relevant despite foreign ownership. */
+  /** The subset of `foreignOwned` where the declared manifest also sets the path — a contested field. */
   foreignContested: ReadonlySet<string>;
   /**
    * Path → the name of the manager that owns it (#1189).
    *
-   * The three sets above answer *which category* owns a path, which is all the
-   * prune rule needs. A reader needs the other question — "owned by
-   * `kubectl-client-side-apply`" and "owned by `hpa-controller`" are the same
-   * category and mean very different things to an operator. Last writer wins
-   * where several managers touch one path, matching what the API server itself
-   * reports.
+   * The three sets above answer *which category* owns a path. A reader needs
+   * the other question — "owned by `kubectl-client-side-apply`" and "owned by
+   * `hpa-controller`" are the same category and mean very different things to
+   * an operator. Since chant #1191 no category is pruned from the diff, so
+   * this map is what tells the two apart in the report. Last writer wins
+   * where several managers touch one path, matching what the API server
+   * itself reports.
    */
   owners: ReadonlyMap<string, string>;
 }
@@ -323,25 +324,41 @@ export function buildOwnershipSets(
 }
 
 /**
- * The three-question managed-fields prune rule, as a predicate over a
- * {@link DeepNode} plus one object's precomputed {@link OwnershipSets} —
- * shared by every lexicon layering a per-resource managed-fields prune on
- * top of its own static rules (k8s's `perResourceHooks`, gcp's equivalent):
+ * Well-known metadata the control plane writes on an object regardless of
+ * who applied it — matched on the exact index-erased pattern, like
+ * {@link K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS}, but gated by the caller on
+ * `side === "live" && counterpart === "absent"` so a manifest that *does*
+ * declare one of these (a hand-pinned `change-cause`, say) is still compared.
  *
- * 1. Chant owns the path (any chant manager) → never pruned by this rule.
- * 2. A different manager owns it, chant does not, and it is not declared →
- *    controller-managed noise, pruned.
- * 3. It is declared, regardless of who owns it live → never pruned by this
- *    rule, because chant's source is a statement of intent independent of
- *    which write currently holds the field.
+ * This list is the noise valve that replaced the managed-fields prune
+ * (chant #1191). Until then a foreign-owned, undeclared path was dropped
+ * before the diff ever saw it, which silenced `kubectl label deploy web
+ * team=platform` — the exact console-edit class the `undeclared` drift kind
+ * exists for. Now a foreign-owned path nobody declared is reported as
+ * `undeclared` (with its owner named, #1189) unless the accepted baseline
+ * already carries it — and what remains to subtract statically is only the
+ * handful of annotations and labels Kubernetes' own controllers stamp on
+ * every object of a kind. Widening this set is additive; each entry must be
+ * something *no* human writes out of band.
  *
- * Only applies to the live side — the declared tree carries no managedFields
- * to prune by.
+ * - `kubectl.kubernetes.io/last-applied-configuration` — client-side apply's
+ *   bookkeeping, a JSON copy of whatever was last applied.
+ * - `deployment.kubernetes.io/revision` (+ `revision-history`,
+ *   `desired-replicas`, `max-replicas`) — the Deployment controller's
+ *   rollout counters, written to Deployments and their ReplicaSets.
+ * - `pod-template-hash` / `controller-revision-hash` /
+ *   `statefulset.kubernetes.io/pod-name` — the selector labels the
+ *   ReplicaSet, DaemonSet and StatefulSet controllers add to what they own.
  */
-export function pruneByOwnership(node: DeepNode, sets: OwnershipSets): boolean {
-  if (node.side !== "live") return false;
-  if (sets.chantOwned.has(node.path)) return false;
-  if (!sets.foreignOwned.has(node.path)) return false;
-  if (sets.foreignContested.has(node.path)) return false;
-  return true;
-}
+export const K8S_SYSTEM_METADATA_PRUNE_PATTERNS: ReadonlySet<string> = new Set([
+  "metadata.annotations.kubectl.kubernetes.io/last-applied-configuration",
+  "metadata.annotations.deployment.kubernetes.io/revision",
+  "metadata.annotations.deployment.kubernetes.io/revision-history",
+  "metadata.annotations.deployment.kubernetes.io/desired-replicas",
+  "metadata.annotations.deployment.kubernetes.io/max-replicas",
+  "metadata.labels.pod-template-hash",
+  "metadata.labels.controller-revision-hash",
+  "metadata.labels.statefulset.kubernetes.io/pod-name",
+  "spec.template.metadata.labels.pod-template-hash",
+  "spec.template.metadata.labels.controller-revision-hash",
+]);

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: {} });
+    expect(normalizeObservation({ a: meta() })).toEqual({ resources: { a: meta() }, unobserved: {}, queried: {}, notes: [] });
   });
 
   test("the envelope carries both halves", () => {
@@ -38,11 +38,19 @@ describe("normalizeObservation", () => {
       resources: { a: meta() },
       unobserved: { b: { reason: "read-failed" } },
       queried: {},
+      notes: [],
     });
   });
 
+  test("run-level notes ride the envelope, distinct (#1265)", () => {
+    const value = observation({ a: meta() }, undefined, undefined, ["ownership unknown", "ownership unknown"]);
+    expect(value.notes).toEqual(["ownership unknown", "ownership unknown"]);
+    expect(normalizeObservation(value).notes).toEqual(["ownership unknown"]);
+    expect(observation({}).notes).toBeUndefined();
+  });
+
   test("undefined normalizes to empty maps", () => {
-    expect(normalizeObservation(undefined)).toEqual({ resources: {}, unobserved: {}, queried: {} });
+    expect(normalizeObservation(undefined)).toEqual({ resources: {}, unobserved: {}, queried: {}, notes: [] });
   });
 
   test("the envelope carries the queried addresses through normalization (#1620)", () => {
@@ -84,25 +92,33 @@ 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: {} },
-      { resources: { a: meta() }, unobserved: {}, queried: {} },
+      { resources: {}, unobserved: { a: { reason: "read-failed" }, b: { reason: "no-binding" } }, queried: {}, notes: [] },
+      { resources: { a: meta() }, unobserved: {}, queried: {}, notes: [] },
     ]);
     expect(Object.keys(merged.resources)).toEqual(["a"]);
     expect(Object.keys(merged.unobserved)).toEqual(["b"]);
   });
 
+  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] })),
+    );
+    expect(merged.notes).toEqual([note]);
+  });
+
   test("an entity nobody looked for in any stack stays absent", () => {
     const merged = mergeObservations([
-      { resources: { a: meta() }, unobserved: {}, queried: {} },
-      { resources: { b: meta() }, unobserved: {}, queried: {} },
+      { resources: { a: meta() }, unobserved: {}, queried: {}, notes: [] },
+      { resources: { b: meta() }, unobserved: {}, queried: {}, notes: [] },
     ]);
     expect(merged.unobserved).toEqual({});
   });
 
   test("queried addresses union across stacks (#1620)", () => {
     const merged = mergeObservations([
-      { resources: {}, unobserved: {}, queried: { a: "stack-1/a" } },
-      { resources: { b: meta() }, unobserved: {}, queried: { b: "stack-2/b" } },
+      { resources: {}, unobserved: {}, queried: { a: "stack-1/a" }, notes: [] },
+      { resources: { b: meta() }, unobserved: {}, queried: { b: "stack-2/b" }, notes: [] },
     ]);
     expect(merged.queried).toEqual({ a: "stack-1/a", b: "stack-2/b" });
   });