@intentius/chant 0.124.13 → 0.124.14

package/dist/graph-ir.js

@@ -0,0 +1,623 @@
+import { relative, isAbsolute } from "node:path";
+import { isAttrRefLike } from "./utils.js";
+import { isDeclarable } from "./declarable.js";
+import { isLexiconOutput } from "./lexicon-output.js";
+import { getProvenance } from "./provenance.js";
+import { INTRINSIC_MARKER } from "./intrinsic.js";
+/** True when `value` has the {@link EntityReference} shape. */
+function isEntityReference(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.to === "string");
+}
+/**
+ * The references an entity declared for itself (#2265), or an empty list.
+ * Duck-typed on purpose, see {@link EntityReference}.
+ */
+export function entityReferences(entity) {
+    const declared = entity.references;
+    if (!Array.isArray(declared))
+        return [];
+    return declared.filter(isEntityReference);
+}
+/**
+ * The deployable unit an entity says it belongs to (#2266), or undefined.
+ *
+ * Same duck-typed channel as {@link entityReferences}, for the other half of
+ * the same problem. `groups.byStack` keys by lexicon partition when nothing
+ * says otherwise, on the reasoning that one lexicon serialises to one
+ * deployable stack. That reasoning is exactly wrong for a lexicon reading an
+ * estate that already has several: a terraform project declaring five
+ * `terraform.roots` has five things `terraform apply` runs against, and each
+ * one is a stack in every sense `byStack` means, so five roots landed in one
+ * bucket named `terraform`.
+ *
+ * The root is not inferable here and should not be: it is the producer's own
+ * name for its own unit. A consumer could recover it from the node id prefix
+ * the terraform lexicon mints, but an id convention is not a promise, and
+ * `byStack` is the field whose whole job is saying which box a node goes in.
+ */
+export function entityStack(entity) {
+    const stack = entity.stack;
+    return typeof stack === "string" && stack.length > 0 ? stack : undefined;
+}
+/**
+ * The version `chant graph --format ir` writes on its output (#2529, #2524 D8).
+ * The format changes only additively: a new field or edge kind never bumps
+ * it, and a consumer ignores the fields and edge kinds it does not know. The
+ * number moves only for a change a consumer could not ignore.
+ */
+export const GRAPH_IR_VERSION = 1;
+/** A node is anything that serializes to a resource — not a property or output. */
+function isNodeEntity(entity) {
+    if (isLexiconOutput(entity))
+        return false;
+    if (entity.kind === "property")
+        return false;
+    return true;
+}
+function relFile(file, projectPath) {
+    if (!file)
+        return undefined;
+    if (projectPath && isAbsolute(file)) {
+        const rel = relative(projectPath, file);
+        return rel.startsWith("..") ? file : rel;
+    }
+    return file;
+}
+/** The logical name a `Ref`-style intrinsic points at, or undefined. Lexicon-
+ * agnostic: reads the intrinsic's `toJSON()` for the CloudFormation `{ Ref: name }`
+ * shape (aws `RefIntrinsic` etc.). A `Ref` to a node is a real dependency edge,
+ * not an opaque intrinsic (#513) — so we resolve it rather than flatten it. */
+function refIntrinsicTarget(value) {
+    try {
+        const json = value.toJSON?.();
+        if (json && typeof json === "object" && typeof json.Ref === "string") {
+            return json.Ref;
+        }
+    }
+    catch {
+        // Unresolvable at graph-build time — leave it as an opaque intrinsic.
+    }
+    return undefined;
+}
+/** Resolve the producer (logical name) an AttrRef points at. */
+function refTarget(ref, reverse) {
+    // Nested refs (under `props`) aren't assigned a logical name by resolveAttrRefs,
+    // which only resolves top-level own props — so fall back to the parent's name.
+    const parent = ref.parent.deref();
+    return ref.getLogicalName() ?? (parent ? reverse.get(parent) : undefined);
+}
+/**
+ * The node id a whole declarable held in a config bag stands for, or undefined
+ * when it is not a node of this graph (an inlined property-kind resource, say,
+ * which is config of the holder and gets walked instead). An entity can name
+ * another entity directly rather than through an AttrRef, as the sql lexicon's
+ * enumerable `dependsOn` does with the tables, views and databases a statement
+ * mentions (#3257); that is a reference to the node, not a nested bag.
+ */
+function nodeReference(value, reverse, nodeIds) {
+    const id = reverse.get(value);
+    return id !== undefined && nodeIds.has(id) ? id : undefined;
+}
+/** Project a value into a JSON-safe, scrubbed form. References become `{ $ref }`. */
+function project(value, seen, reverse, nodeIds) {
+    if (value === null)
+        return null;
+    const t = typeof value;
+    if (t === "string" || t === "number" || t === "boolean")
+        return value;
+    if (t !== "object")
+        return undefined; // functions, symbols, undefined
+    // Duck-type, not `instanceof`: a lexicon built against a different copy of
+    // `@intentius/chant` produces AttrRefs that fail `instanceof AttrRef` but carry
+    // the same shape. Without this, a real cross-resource reference falls through to
+    // the intrinsic branch below and is silently flattened to `{$intrinsic}` (#511).
+    if (isAttrRefLike(value)) {
+        const to = refTarget(value, reverse);
+        return { $ref: to ? `${to}.${value.attribute}` : value.attribute };
+    }
+    if (value[INTRINSIC_MARKER] === true) {
+        // A `Ref` to a known node is a real reference — surface it as `$ref` so attrs
+        // match the edge (#513). Other intrinsics (interpolations, pseudo-parameters,
+        // Ref to a non-node) stay opaque.
+        const to = refIntrinsicTarget(value);
+        if (to && nodeIds.has(to))
+            return { $ref: to };
+        return { $intrinsic: true };
+    }
+    if (seen.has(value))
+        return undefined; // break cycles
+    seen.add(value);
+    // Nested declarables (e.g. an inlined property-kind resource) keep their
+    // config in a non-enumerable `props` bag, like top-level nodes — project that.
+    if (isDeclarable(value)) {
+        // Another node held whole is a reference to it, not config to inline.
+        const to = nodeReference(value, reverse, nodeIds);
+        if (to)
+            return { $ref: to };
+        const out = projectConfig(value, seen, reverse, nodeIds);
+        seen.delete(value);
+        return out;
+    }
+    if (Array.isArray(value)) {
+        const out = value.map((v) => project(v, seen, reverse, nodeIds)).filter((v) => v !== undefined);
+        seen.delete(value);
+        return out;
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        const p = project(v, seen, reverse, nodeIds);
+        if (p !== undefined)
+            out[k] = p;
+    }
+    seen.delete(value);
+    return out;
+}
+// `references` and `stack` are the two duck-typed channels above
+// ({@link entityReferences}, {@link entityStack}). They are metadata about the
+// entity's place in the graph, not declared configuration, and both are read
+// directly, so projecting them into `attrs` would only restate an edge and a
+// group key the IR already carries.
+const SKIP_KEYS = new Set(["lexicon", "entityType", "kind", "attributes", "Ref", "references", "stack"]);
+/** The config bag of a node, paired with each key. Lexicon entities keep their
+ * declared props in a (usually non-enumerable) `props` object; simpler entities
+ * carry config as enumerable own properties. We surface both, flattening `props`
+ * so a field reads as e.g. `network`, not `props.network`. */
+function configRoots(entity) {
+    const out = [];
+    for (const [k, v] of Object.entries(entity)) {
+        if (SKIP_KEYS.has(k) || k === "props")
+            continue;
+        out.push([k, v]);
+    }
+    const props = entity.props;
+    if (props && typeof props === "object" && !Array.isArray(props)) {
+        for (const [k, v] of Object.entries(props))
+            out.push([k, v]);
+    }
+    return out;
+}
+/** Project a declarable's config bag (flattened props + enumerable own props). */
+function projectConfig(entity, seen, reverse, nodeIds) {
+    const out = {};
+    for (const [k, v] of configRoots(entity)) {
+        const p = project(v, seen, reverse, nodeIds);
+        if (p !== undefined)
+            out[k] = p;
+    }
+    return out;
+}
+/**
+ * Collect ref edges from one node, labelling each with its consumer property.
+ *
+ * Two sources, merged here. First the references the entity resolved for
+ * itself ({@link EntityReference}), which is how a lexicon that parses HCL,
+ * YAML or any other foreign source says what its strings point at. Then the
+ * walk over the config bag for {@link AttrRef} objects and `Ref` intrinsics,
+ * which is how a typed lexicon's props carry the same fact. A lexicon uses one
+ * or the other; nothing stops it using both, and the dedup in `buildGraphIr`
+ * collapses an edge two sources agree on.
+ */
+function collectEdges(entity, from, nodeIds, reverse) {
+    const edges = [];
+    for (const ref of entityReferences(entity)) {
+        if (ref.to === from || !nodeIds.has(ref.to))
+            continue;
+        edges.push({
+            from,
+            to: ref.to,
+            kind: "ref",
+            ...(ref.viaAttr ? { viaAttr: ref.viaAttr } : {}),
+            ...(ref.toAttr ? { toAttr: ref.toAttr } : {}),
+        });
+    }
+    const seen = new Set();
+    const visit = (value, viaAttr) => {
+        if (value === null || typeof value !== "object")
+            return;
+        if (isAttrRefLike(value)) {
+            const to = refTarget(value, reverse);
+            if (to && to !== from && nodeIds.has(to)) {
+                edges.push({ from, to, kind: "ref", viaAttr });
+            }
+            return;
+        }
+        if (value[INTRINSIC_MARKER] === true) {
+            // A `Ref` to a known node (a Parameter, or a resource) is a real dependency
+            // — resolve it to an edge instead of dropping it as an opaque intrinsic (#513).
+            const to = refIntrinsicTarget(value);
+            if (to && to !== from && nodeIds.has(to))
+                edges.push({ from, to, kind: "ref", viaAttr });
+            return;
+        }
+        // A whole node held in props or an enumerable field (the sql lexicon's
+        // `dependsOn`) is a reference to it: draw the edge, and do not walk its
+        // config, whose refs belong to that node's own edges (#3257). Checked
+        // before `seen` so the same node under two attributes yields both edges.
+        const held = nodeReference(value, reverse, nodeIds);
+        if (held) {
+            if (held !== from)
+                edges.push({ from, to: held, kind: "ref", viaAttr });
+            return;
+        }
+        if (seen.has(value))
+            return;
+        seen.add(value);
+        // A nested declarable (an inlined property-kind resource, e.g. a listener's
+        // `DefaultActions: [Listener_Action{ TargetGroupArn: tg.TargetGroupArn }]`)
+        // keeps its config in a NON-enumerable `props` bag, so `Object.values`
+        // below would walk right past the ref inside it and drop the edge. Descend
+        // via `configRoots` (which reads `props`), mirroring `project`'s handling —
+        // the ref then resolves to a real from→to edge on the containing node.
+        if (isDeclarable(value)) {
+            for (const [, v] of configRoots(value))
+                visit(v, viaAttr);
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item, viaAttr);
+            return;
+        }
+        for (const v of Object.values(value))
+            visit(v, viaAttr);
+    };
+    for (const [k, v] of configRoots(entity))
+        visit(v, k);
+    return edges;
+}
+/** Stable key for deduping and sorting an edge. */
+function edgeKey(e) {
+    return `${e.from}\0${e.to}\0${e.viaAttr ?? ""}`;
+}
+/**
+ * Build the graph IR from resolved entities (the output of `discover`). Pure and
+ * deterministic: nodes and edges are sorted, so the same source yields identical
+ * IR. `projectPath` relativizes source-file paths for portable output.
+ */
+export function buildGraphIr(entities, projectPath) {
+    var _a, _b, _c;
+    // Reverse lookup for producers whose AttrRef logical name wasn't resolved.
+    const reverse = new Map();
+    for (const [name, entity] of entities)
+        reverse.set(entity, name);
+    const nodeIds = new Set();
+    for (const [name, entity] of entities) {
+        if (isNodeEntity(entity))
+            nodeIds.add(name);
+    }
+    const nodes = [];
+    const byLexicon = {};
+    const byComposite = {};
+    const byStack = {};
+    for (const [name, entity] of entities) {
+        if (!nodeIds.has(name))
+            continue;
+        const prov = getProvenance(entity);
+        const node = {
+            id: name,
+            kind: entity.entityType,
+            lexicon: entity.lexicon,
+            attrs: projectConfig(entity, new Set(), reverse, nodeIds),
+        };
+        if (prov?.composite)
+            node.compositeParent = prov.composite;
+        if (prov?.compositeInstance)
+            node.compositeInstance = prov.compositeInstance;
+        const file = relFile(prov?.sourceFile, projectPath);
+        if (file)
+            node.sourceLoc = { file };
+        nodes.push(node);
+        (byLexicon[_a = entity.lexicon] ?? (byLexicon[_a] = [])).push(name);
+        // An entity that names its own deployable unit is taken at its word
+        // (#2266): a terraform root is one `terraform apply`, and a project
+        // declaring five of them has five stacks whatever the lexicon count says.
+        // See {@link entityStack}.
+        //
+        // Otherwise, within ONE source tree a stack is a lexicon partition — each
+        // lexicon serialises to one deployable stack (a CloudFormation template, a
+        // CI config) — so that is what `byStack` reports. It stays a distinct axis
+        // from `byLexicon` (which is for provenance/colouring), emitted separately
+        // even where the two coincide.
+        //
+        // A project with genuinely separate, side-by-side stacks declares them in
+        // config, and `buildDeclaredPerStack` (./graph-declared.ts) groups those by
+        // their declared names — no inference, since the project already said. That
+        // is the multi-stack shape chant steers toward (#1433).
+        //
+        // This previously promised that "#513 phase 2 will regroup it by nested
+        // child-project". #513 is closed, that phase was never filed, and directory
+        // partitioning is the exception rather than the rule — so the promise is
+        // withdrawn rather than left pointing at a closed issue.
+        (byStack[_b = entityStack(entity) ?? entity.lexicon] ?? (byStack[_b] = [])).push(name);
+        if (prov?.composite)
+            (byComposite[_c = prov.composite] ?? (byComposite[_c] = [])).push(name);
+    }
+    const edgeMap = new Map();
+    for (const [name, entity] of entities) {
+        if (!nodeIds.has(name))
+            continue;
+        for (const e of collectEdges(entity, name, nodeIds, reverse)) {
+            edgeMap.set(edgeKey(e), e);
+        }
+    }
+    nodes.sort((a, b) => a.id.localeCompare(b.id));
+    const edges = [...edgeMap.values()].sort((a, b) => edgeKey(a).localeCompare(edgeKey(b)));
+    for (const ids of Object.values(byLexicon))
+        ids.sort();
+    for (const ids of Object.values(byComposite))
+        ids.sort();
+    for (const ids of Object.values(byStack))
+        ids.sort();
+    const groups = {};
+    if (Object.keys(byLexicon).length)
+        groups.byLexicon = sortKeys(byLexicon);
+    if (Object.keys(byComposite).length)
+        groups.byComposite = sortKeys(byComposite);
+    if (Object.keys(byStack).length)
+        groups.byStack = sortKeys(byStack);
+    // Cross-stack exports: a stack's `output(ref, name)` LexiconOutputs are dropped
+    // from the node set (they're not resources), but their name + producing node is
+    // the handle another stack imports by. Surface them so a viewer can draw the
+    // cross-stack edge (#513). Resolve the producer via the output's source entity.
+    const exports = [];
+    for (const entity of entities.values()) {
+        if (!isLexiconOutput(entity))
+            continue;
+        const lo = entity;
+        if (!lo.outputName)
+            continue;
+        const parent = lo._sourceParent?.deref();
+        const node = (parent ? reverse.get(parent) : undefined) ?? (lo.sourceEntity || undefined);
+        exports.push({ name: lo.outputName, ...(node ? { node } : {}), ...(lo.sourceAttribute ? { attr: lo.sourceAttribute } : {}) });
+    }
+    exports.sort((a, b) => a.name.localeCompare(b.name));
+    // Cross-stack imports: parameter nodes are the handles this stack imports by,
+    // matched to another stack's export names (#513). Detected by kind — the aws
+    // `Parameter` is the cross-stack input mechanism.
+    const imports = nodes
+        .filter((n) => /(^|::)Parameter$/i.test(n.kind))
+        .map((n) => ({ name: n.id, node: n.id }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const ir = { nodes, edges, groups };
+    if (exports.length)
+        ir.exports = exports;
+    if (imports.length)
+        ir.imports = imports;
+    return ir;
+}
+function sortKeys(rec) {
+    const out = {};
+    for (const k of Object.keys(rec).sort())
+        out[k] = rec[k];
+    return out;
+}
+/**
+ * Build the graph IR from **live-observed** resources (`chant graph --live`) —
+ * the provisioned graph, not the declared one. This is the C1 half of epic #776:
+ * nodes only. Edges are reconstructed separately by the per-lexicon reference
+ * resolver (#778); containment grouping by #779. Pure and deterministic given a
+ * fixed observation set (nodes and group ids sorted), so the same snapshot yields
+ * identical IR.
+ *
+ * Each node carries the observed `physicalId` (the reference resolver's index
+ * key) and `ownership` marker. `attrs` is the resource's observed attributes.
+ */
+export function buildLiveGraphIr(observations) {
+    const nodes = [];
+    const byLexicon = {};
+    const byStack = {};
+    for (const { lexicon, resources } of observations) {
+        for (const [name, meta] of Object.entries(resources)) {
+            const node = {
+                id: name,
+                kind: meta.type,
+                lexicon,
+                attrs: meta.attributes ?? {},
+            };
+            if (meta.physicalId)
+                node.physicalId = meta.physicalId;
+            // `unknown` is a legitimate verdict on the metadata (#1089) but carries no
+            // information for a painter, and the IR's `ownership` field means "a
+            // verdict was reached" — so only owned/foreign land on the node.
+            if (meta.ownership === "owned" || meta.ownership === "foreign")
+                node.ownership = meta.ownership;
+            // Owner-reference chain (#1077): only a resolved `declared` root is
+            // carried onto the node — the same "a verdict was reached" rule as
+            // ownership above, since `unowned`/`foreign`/`unknown` all mean "no
+            // declared owner", which is simply the absence of this field.
+            if (meta.ownerChain?.root === "declared")
+                node.runtimeOwner = meta.ownerChain.entity;
+            nodes.push(node);
+            (byLexicon[lexicon] ?? (byLexicon[lexicon] = [])).push(name);
+            // A live lexicon maps to one deployable stack, same as the source IR.
+            (byStack[lexicon] ?? (byStack[lexicon] = [])).push(name);
+        }
+    }
+    nodes.sort((a, b) => a.id.localeCompare(b.id));
+    for (const ids of Object.values(byLexicon))
+        ids.sort();
+    for (const ids of Object.values(byStack))
+        ids.sort();
+    const groups = {};
+    if (Object.keys(byLexicon).length)
+        groups.byLexicon = sortKeys(byLexicon);
+    if (Object.keys(byStack).length)
+        groups.byStack = sortKeys(byStack);
+    // Observed relationships (#1271). An edge whose endpoints were not both
+    // observed is dropped rather than kept as a dangling reference: the fold
+    // resolves ids to nodes, and a half-edge would silently traverse to nothing.
+    // Deduped and sorted for the same reason nodes are — the IR is compared and
+    // committed, so it has to be stable across reads.
+    const observedIds = new Set(nodes.map((n) => n.id));
+    const seen = new Set();
+    const edges = [];
+    for (const observation of observations) {
+        for (const edge of observation.edges ?? []) {
+            if (!observedIds.has(edge.from) || !observedIds.has(edge.to))
+                continue;
+            const key = `${edge.from}\u0000${edge.to}\u0000${edge.viaAttr ?? ""}\u0000${edge.toAttr ?? ""}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            edges.push(edge);
+        }
+    }
+    edges.sort((a, b) => a.from.localeCompare(b.from) ||
+        a.to.localeCompare(b.to) ||
+        (a.viaAttr ?? "").localeCompare(b.viaAttr ?? ""));
+    // Stack exports (#1279) land on the IR's `exports`, the same place the
+    // declared graph keeps what a stack publishes — not on the member nodes.
+    const exports = [];
+    for (const observation of observations) {
+        for (const [stack, values] of Object.entries(observation.stackExports ?? {})) {
+            for (const [name, value] of Object.entries(values))
+                exports.push({ name, value, stack });
+        }
+    }
+    exports.sort((a, b) => a.name.localeCompare(b.name) || (a.stack ?? "").localeCompare(b.stack ?? ""));
+    return { nodes, edges, groups, ...(exports.length > 0 ? { exports } : {}) };
+}
+/** The union of every observation's unobserved entities — the input to the overlays. */
+export function collectUnobserved(observations) {
+    const out = {};
+    for (const o of observations)
+        Object.assign(out, o.unobserved ?? {});
+    return out;
+}
+function tagStatus(n, status, unobserved) {
+    return {
+        ...n,
+        attrs: {
+            ...n.attrs,
+            _status: status,
+            ...(unobserved ? { _unobserved: unobserved.reason } : {}),
+        },
+    };
+}
+/**
+ * Overlay the declared graph on the provisioned one (#780, `chant graph --live
+ * --overlay`) and classify each resource, tagging a `_status` a renderer colours:
+ *   - **managed** (declared + provisioned) → `good`
+ *   - **runtime** (provisioned, not declared, owner chain reaches a declared
+ *     entity — #1077) → `runtime`, e.g. a Pod a declared Deployment's
+ *     controller created — expected, not a foreign resource needing attention
+ *   - **foreign** (provisioned, not declared, no declared owner) → `warn`
+ *   - **pending** (declared, provider confirmed absent) → `accent`
+ *   - **unobserved** (declared, chant could not look — #1089) → `neutral`,
+ *     plus an `_unobserved` attr carrying the reason
+ * Live nodes keep their edges/containment; pending nodes are appended (they have
+ * no live edges). Sorted; the live groups pass through unchanged.
+ */
+export function overlayGraphs(live, declared, opts) {
+    const declaredIds = new Set(declared.nodes.map((n) => n.id));
+    const liveIds = new Set(live.nodes.map((n) => n.id));
+    const unobserved = opts?.unobserved ?? {};
+    const nodes = live.nodes.map((n) => tagStatus(n, declaredIds.has(n.id) ? "good" : n.runtimeOwner ? "runtime" : "warn"));
+    for (const n of declared.nodes) {
+        if (liveIds.has(n.id))
+            continue;
+        const u = unobserved[n.id];
+        nodes.push(u ? tagStatus(n, "neutral", u) : tagStatus(n, "accent"));
+    }
+    nodes.sort((a, b) => a.id.localeCompare(b.id));
+    return { ...live, nodes };
+}
+/**
+ * Source-anchored overlay (#821) — the inverse of {@link overlayGraphs}. The
+ * **declared** graph is the canvas, so its edges are kept: cross-substrate edges
+ * (an ECS service wired to a k8s workload) are a source-graph property, since live
+ * reconstruction is per-substrate (identifier value-match) and never crosses
+ * providers. Use this when the overlay must keep the mixed topology; use
+ * `overlayGraphs` when the provisioned graph itself is the subject.
+ *
+ * Each declared node is classified against live observation and tagged `_status`:
+ *   - **managed** (declared + provisioned) → `good`, carrying the observed
+ *     `physicalId` / `ownership` onto the declared node
+ *   - **pending** (declared, provider confirmed absent) → `accent`
+ *   - **unobserved** (declared, chant could not look — #1089) → `neutral`, with
+ *     the reason on `_unobserved`. A wrong-cluster or unsupported-kind read used
+ *     to paint the whole estate "pending", which is the diagram equivalent of
+ *     planning a create for something that already exists.
+ * **Foreign** resources (provisioned, not declared, no declared owner) are
+ * appended and tagged `warn`; a provisioned-but-undeclared resource whose
+ * owner chain reaches a declared entity (#1077) is tagged `runtime` instead —
+ * both carry any live-reconstructed edges that touch them, since a declared
+ * edge cannot describe an undeclared resource. Declared groups/exports pass
+ * through unchanged; nodes and edges are sorted for deterministic output.
+ */
+export function sourceOverlayGraphs(declared, live, opts) {
+    const liveById = new Map(live.nodes.map((n) => [n.id, n]));
+    const declaredIds = new Set(declared.nodes.map((n) => n.id));
+    const foreignIds = new Set(live.nodes.filter((n) => !declaredIds.has(n.id)).map((n) => n.id));
+    const unobserved = opts?.unobserved ?? {};
+    const nodes = declared.nodes.map((n) => {
+        const obs = liveById.get(n.id);
+        if (!obs) {
+            const u = unobserved[n.id];
+            // unobserved — declared, and nobody looked; not "pending"
+            return u ? tagStatus(n, "neutral", u) : tagStatus(n, "accent");
+        }
+        const merged = { ...n }; // managed — carry the observed identity
+        if (obs.physicalId)
+            merged.physicalId = obs.physicalId;
+        if (obs.ownership)
+            merged.ownership = obs.ownership;
+        // ...and what was observed ABOUT it (#1279). The declared canvas holds what
+        // the source says; the observation holds what the account says, and a fact
+        // like `VpcId` exists only on the second. Dropping it here made every
+        // observed property invisible to anything reading the overlaid graph —
+        // `search --show VpcId` printed six blank columns, which reads as an estate
+        // with no VPCs rather than a read that never happened.
+        //
+        // Observed wins a collision. The declared value for something like `VpcId`
+        // is an unresolved reference to another entity, not an id — the account has
+        // the id. Same precedence `enrichLiveAttrs` already uses when it folds live
+        // facts onto this graph, so both paths agree on what a name means.
+        if (obs.attrs && Object.keys(obs.attrs).length > 0)
+            merged.attrs = { ...n.attrs, ...obs.attrs };
+        return tagStatus(merged, "good");
+    });
+    for (const n of live.nodes) {
+        if (!foreignIds.has(n.id))
+            continue;
+        nodes.push(tagStatus(n, n.runtimeOwner ? "runtime" : "warn")); // runtime child or foreign
+    }
+    nodes.sort((a, b) => a.id.localeCompare(b.id));
+    // Declared edges are the canvas (the cross-substrate topology). Add only the
+    // live edges that touch a foreign node — declared edges already cover every
+    // declared relationship, so keeping all live edges would double managed ones.
+    const seen = new Set(declared.edges.map(edgeKey));
+    const edges = [...declared.edges];
+    for (const e of live.edges) {
+        if (!(foreignIds.has(e.from) || foreignIds.has(e.to)))
+            continue;
+        const k = edgeKey(e);
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        edges.push(e);
+    }
+    edges.sort((a, b) => edgeKey(a).localeCompare(edgeKey(b)));
+    // Observed export values (#1279) join the declared exports by name: the
+    // declaration says which node publishes it, the observation says what it
+    // currently is. An export only the stack carries is appended.
+    const liveExports = live.exports ?? [];
+    let exports = declared.exports;
+    if (liveExports.length > 0) {
+        const byName = new Map(liveExports.map((e) => [e.name, e]));
+        const merged = (declared.exports ?? []).map((e) => {
+            const obs = byName.get(e.name);
+            if (!obs)
+                return e;
+            byName.delete(e.name);
+            return { ...e, value: obs.value, ...(obs.stack ? { stack: obs.stack } : {}) };
+        });
+        for (const e of byName.values())
+            merged.push(e);
+        merged.sort((a, b) => a.name.localeCompare(b.name));
+        exports = merged;
+    }
+    return { ...declared, nodes, edges, ...(exports ? { exports } : {}) };
+}