@x12i/memorix-retrieval 1.35.0 → 1.37.0

package/dist/graphs/build-graph-document.js

@@ -0,0 +1,888 @@
+import { getByPath } from "../data/path.js";
+import { loadMemorixEntityDescriptorByName } from "../descriptors/discover-entities.js";
+import { resolveMemorixGraphDescriptor } from "./load-graph-descriptor.js";
+import { resolveEntityGraphCapability, } from "./fallback-graph-capabilities.js";
+import { conceptFromRecord, fetchContentLenses, findSnapshotByIdentifierKey, findSnapshotByRecordId, focusLookupObjectTypes, listSnapshots, recordIdOf, } from "./record-access.js";
+function parseTiers(tiers) {
+    if (tiers == null)
+        return null;
+    const list = Array.isArray(tiers)
+        ? tiers
+        : tiers.split(",").map((t) => t.trim()).filter(Boolean);
+    return list.length ? new Set(list) : null;
+}
+function upsertNode(map, node) {
+    const existing = map.get(node.id);
+    if (!existing) {
+        map.set(node.id, node);
+        return;
+    }
+    if (!existing.recordId && node.recordId)
+        existing.recordId = node.recordId;
+    if (!existing.objectType && node.objectType)
+        existing.objectType = node.objectType;
+    if (!existing.content && node.content)
+        existing.content = node.content;
+}
+function addEdge(edges, edge) {
+    const id = edge.id ?? `${edge.type}:${edge.from}->${edge.to}`;
+    if (edges.some((e) => (e.id ?? `${e.type}:${e.from}->${e.to}`) === id))
+        return;
+    edges.push({ ...edge, id });
+}
+function tierForObjectType(descriptor, objectType) {
+    return (descriptor.nodes.find((n) => n.objectType === objectType)?.tier ??
+        descriptor.tiers.find((t) => t.objectTypes.includes(objectType))?.id);
+}
+function nodeSpecFor(descriptor, objectType) {
+    return descriptor.nodes.find((n) => n.objectType === objectType);
+}
+function buildId(kind, value) {
+    const v = value.trim();
+    if (!v)
+        return "";
+    return `${kind}:${v}`;
+}
+function titleForId(id, kind) {
+    if (id.startsWith(`${kind}:`))
+        return id.slice(kind.length + 1);
+    return id;
+}
+function syntheticConcept(kind, value) {
+    const id = buildId(kind, value);
+    return {
+        identifier: { kind, [kind]: value, identifierKey: id },
+        title: value,
+    };
+}
+function passesWhen(emission, item) {
+    const when = emission.when;
+    if (!when)
+        return true;
+    if (!item) {
+        return (!when.itemFieldExists &&
+            !when.itemArrayIncludes &&
+            !when.itemFieldMissing);
+    }
+    if (when.itemFieldExists) {
+        const v = item[when.itemFieldExists];
+        if (v == null || v === "")
+            return false;
+    }
+    if (when.itemFieldMissing) {
+        const v = item[when.itemFieldMissing];
+        if (v != null && v !== "")
+            return false;
+    }
+    if (when.itemArrayIncludes) {
+        const arr = item[when.itemArrayIncludes.field];
+        if (!Array.isArray(arr) || !arr.map(String).includes(when.itemArrayIncludes.value)) {
+            return false;
+        }
+    }
+    return true;
+}
+function readDataObject(doc) {
+    return (doc.data && typeof doc.data === "object" ? doc.data : {});
+}
+function asStringList(value) {
+    if (value == null || value === "")
+        return [];
+    if (Array.isArray(value)) {
+        return value.map((v) => String(v).trim()).filter(Boolean);
+    }
+    return [String(value).trim()].filter(Boolean);
+}
+function readVulnerabilityFamily(doc) {
+    if (!doc)
+        return "";
+    const data = readDataObject(doc);
+    const raw = data.vulnerabilityFamily ??
+        data.pluginFamily ??
+        getByPath(doc, "data.vulnerabilityFamily") ??
+        getByPath(doc, "data.pluginFamily");
+    return raw == null || raw === "" ? "" : String(raw).trim();
+}
+function collectTopologyGap(doc, opts) {
+    const data = readDataObject(doc);
+    const classifications = Array.isArray(data.assetIpClassifications)
+        ? data.assetIpClassifications
+        : [];
+    const subnetCidrs = asStringList(data.subnetCidrs);
+    const zones = asStringList(data.zones);
+    const gapReasons = classifications
+        .map((c) => String(c.reason ?? "").trim())
+        .filter((r) => r.includes("NO_CANONICAL_SUBNET_MATCH") || r === "UNPARSEABLE_IP");
+    if (opts.hadRealAssociatedTopology && !gapReasons.length)
+        return null;
+    if (!opts.hadRealAssociatedTopology ||
+        gapReasons.length ||
+        (!subnetCidrs.length && classifications.length)) {
+        return {
+            reasons: [
+                ...new Set(gapReasons.length
+                    ? gapReasons
+                    : opts.projectedTopology
+                        ? ["OBSERVED_ZONES_WITHOUT_CANONICAL_SUBNET"]
+                        : ["MISSING_ASSOCIATED_TOPOLOGY"]),
+            ],
+            classifications: classifications.map((c) => ({
+                ip: c.ip,
+                scope: c.scope,
+                confidence: c.confidence,
+                reason: c.reason,
+                reasoning: c.reasoning,
+            })),
+            hasAssociatedTopology: opts.hadRealAssociatedTopology,
+            hasSubnetCidrs: subnetCidrs.length > 0,
+            hasObservedZones: zones.length > 0 || opts.projectedTopology,
+        };
+    }
+    return null;
+}
+function normalizePathFacts(raw) {
+    if (!raw)
+        return [];
+    const list = Array.isArray(raw)
+        ? raw
+        : Array.isArray(raw.items)
+            ? raw.items
+            : Array.isArray(raw.paths)
+                ? raw.paths
+                : [];
+    const out = [];
+    for (const entry of list) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const e = entry;
+        const hops = asStringList(e.hops ?? e.zones ?? e.path);
+        const from = e.from != null ? String(e.from) : hops[0];
+        const to = e.to != null
+            ? String(e.to)
+            : hops.length > 1
+                ? hops[hops.length - 1]
+                : undefined;
+        // When from/to are explicit, `hops` are intermediate zones.
+        // When only a zone list is provided, intermediates are the middle entries.
+        const mid = e.from != null || e.to != null
+            ? hops
+            : hops.length > 2
+                ? hops.slice(1, -1)
+                : asStringList(e.hop);
+        if (!from || !to)
+            continue;
+        out.push({
+            title: e.title != null
+                ? String(e.title)
+                : [from, ...mid, to].filter(Boolean).join(" → "),
+            from,
+            to,
+            hops: mid,
+            viaAsset: typeof e.viaAsset === "boolean" || typeof e.viaAsset === "string"
+                ? e.viaAsset
+                : e.via != null
+                    ? String(e.via)
+                    : undefined,
+        });
+    }
+    return out;
+}
+function resolveIdRef(ref, ctx) {
+    switch (ref.source) {
+        case "concept":
+            return ctx.concept?.identifier.identifierKey
+                ? [ctx.concept.identifier.identifierKey]
+                : [];
+        case "relatedConcept":
+            return ctx.relatedConcept?.identifier.identifierKey
+                ? [ctx.relatedConcept.identifier.identifierKey]
+                : [];
+        case "literal":
+            return [buildId(ref.kind, ref.value)].filter(Boolean);
+        case "itemField": {
+            if (!ctx.item)
+                return [];
+            const raw = ctx.item[ref.field];
+            if (raw == null || raw === "")
+                return [];
+            return [buildId(ref.kind, String(raw))].filter(Boolean);
+        }
+        case "itemArrayField": {
+            if (!ctx.item)
+                return [];
+            const arr = ctx.item[ref.field];
+            if (!Array.isArray(arr))
+                return [];
+            return arr
+                .map((v) => buildId(ref.kind, String(v)))
+                .filter(Boolean);
+        }
+        default:
+            return [];
+    }
+}
+function readJoinValue(doc, sourcePath) {
+    let value = getByPath(doc, sourcePath);
+    if (value != null && value !== "")
+        return value;
+    // Fallbacks for common identity shapes
+    if (sourcePath === "data.assetIp" || sourcePath.endsWith(".assetIp")) {
+        value = getByPath(doc, "data.assetIps");
+        if (Array.isArray(value) && value.length)
+            return value[0];
+        const concept = conceptFromRecord(doc);
+        if (concept?.identifier.kind === "ipAddress" && concept.identifier.ipAddress) {
+            return concept.identifier.ipAddress;
+        }
+    }
+    if (sourcePath === "data.pluginId") {
+        const concept = conceptFromRecord(doc);
+        if (concept?.identifier.pluginId)
+            return concept.identifier.pluginId;
+    }
+    return value;
+}
+async function loadEntitySafe(client, objectType) {
+    try {
+        return await loadMemorixEntityDescriptorByName(client, objectType);
+    }
+    catch {
+        return null;
+    }
+}
+async function maybeAttachContent(client, node, objectType, recordId, lenses, enabled) {
+    if (!enabled || !recordId || !lenses?.length)
+        return;
+    node.content = await fetchContentLenses(client, objectType, recordId, lenses);
+}
+function ensureSyntheticNode(nodes, id, kind, objectType, tier) {
+    if (nodes.has(id))
+        return;
+    const value = titleForId(id, kind);
+    upsertNode(nodes, {
+        id,
+        tier,
+        concept: syntheticConcept(kind, value),
+        objectType,
+    });
+}
+export async function buildMemorixGraphDocument(client, input) {
+    const resolved = input.descriptor != null
+        ? {
+            descriptor: input.descriptor,
+            defined: true,
+            source: "catalox",
+        }
+        : await resolveMemorixGraphDescriptor(client, input.graphId ?? "asset-topology-vulnerabilities-graph");
+    const descriptor = resolved.descriptor;
+    const tierFilter = parseTiers(input.tiers);
+    const loadLenses = Boolean(input.lenses);
+    const defaultFocusObjectType = descriptor.focusObjectType ?? "assets";
+    const maxDepth = descriptor.maxDepth ?? 2;
+    const includeTemplates = descriptor.includeEdgeTemplates
+        ? new Set(descriptor.includeEdgeTemplates)
+        : null;
+    const nodes = new Map();
+    const edges = [];
+    const notes = {
+        graphId: descriptor.id,
+        descriptorDefined: resolved.defined,
+        descriptorSource: resolved.source,
+    };
+    if (resolved.inferenceWarnings?.length) {
+        notes.inferenceWarnings = resolved.inferenceWarnings;
+    }
+    const inferredCaps = resolved.inferredCapabilities ?? {};
+    const entityCache = new Map();
+    const getEntity = async (objectType) => {
+        if (!entityCache.has(objectType)) {
+            entityCache.set(objectType, await loadEntitySafe(client, objectType));
+        }
+        return entityCache.get(objectType) ?? null;
+    };
+    // Directory lists every descriptor node type; Focus must resolve the same set.
+    // Prefer kind prefix from identifierKey (cidr: → subnets), then fall back across types.
+    // Also: when Directory passes recordId + identifierKey, a miss on the default
+    // focusObjectType must not block identifierKey / other collections.
+    const kindByObjectType = {};
+    for (const n of descriptor.nodes) {
+        const cap = resolveEntityGraphCapability(n.objectType, null, inferredCaps[n.objectType]);
+        kindByObjectType[n.objectType] = n.kind ?? cap?.node.kind;
+    }
+    const lookupTypes = focusLookupObjectTypes({
+        focusObjectType: defaultFocusObjectType,
+        focusIdentifierKey: input.focusIdentifierKey,
+        nodes: descriptor.nodes,
+        kindByObjectType,
+    });
+    let focusDoc = null;
+    let focusObjectType = defaultFocusObjectType;
+    if (input.focusRecordId) {
+        for (const ot of lookupTypes) {
+            try {
+                const doc = await findSnapshotByRecordId(client, ot, input.focusRecordId);
+                if (doc) {
+                    focusDoc = doc;
+                    focusObjectType = ot;
+                    break;
+                }
+            }
+            catch {
+                /* entity/collection missing for this type — try next */
+            }
+        }
+    }
+    if (!focusDoc && input.focusIdentifierKey) {
+        for (const ot of lookupTypes) {
+            try {
+                const doc = await findSnapshotByIdentifierKey(client, ot, input.focusIdentifierKey);
+                if (doc) {
+                    focusDoc = doc;
+                    focusObjectType = ot;
+                    break;
+                }
+            }
+            catch {
+                /* entity/collection missing for this type — try next */
+            }
+        }
+    }
+    if (!focusDoc) {
+        return {
+            focus: input.focusRecordId
+                ? { recordId: input.focusRecordId }
+                : input.focusIdentifierKey
+                    ? {
+                        concept: {
+                            identifier: {
+                                kind: "unknown",
+                                identifierKey: input.focusIdentifierKey,
+                                unknown: input.focusIdentifierKey,
+                            },
+                            title: input.focusIdentifierKey,
+                        },
+                    }
+                    : undefined,
+            nodes: [],
+            edges: [],
+            notes: { ...notes, warning: "focus_not_found" },
+        };
+    }
+    const focusConcept = conceptFromRecord(focusDoc);
+    const focusRecordId = recordIdOf(focusDoc);
+    if (!focusConcept) {
+        return { nodes: [], edges: [], notes: { ...notes, warning: "focus_missing_concept" } };
+    }
+    const focusTier = tierForObjectType(descriptor, focusObjectType);
+    if (tierFilter && focusTier && !tierFilter.has(focusTier)) {
+        return {
+            focus: { recordId: focusRecordId || undefined, concept: focusConcept },
+            nodes: [],
+            edges: [],
+            notes: { ...notes, warning: "focus_tier_filtered" },
+        };
+    }
+    const focusEntity = await getEntity(focusObjectType);
+    const focusCap = resolveEntityGraphCapability(focusObjectType, focusEntity, inferredCaps[focusObjectType]);
+    const focusSpec = nodeSpecFor(descriptor, focusObjectType);
+    const focusLenses = focusSpec?.contentLenses ?? focusCap?.node.contentLenses ?? ["snapshot"];
+    const focusNode = {
+        id: focusConcept.identifier.identifierKey,
+        tier: focusTier,
+        concept: focusConcept,
+        objectType: focusObjectType,
+        recordId: focusRecordId || undefined,
+    };
+    await maybeAttachContent(client, focusNode, focusObjectType, focusRecordId || undefined, focusLenses, loadLenses);
+    upsertNode(nodes, focusNode);
+    const focusAssetZones = new Set();
+    {
+        const data = readDataObject(focusDoc);
+        for (const z of asStringList(data.zones))
+            focusAssetZones.add(z);
+        const topo = Array.isArray(focusDoc.associatedTopology)
+            ? focusDoc.associatedTopology
+            : [];
+        for (const item of topo) {
+            if (item.zone != null && String(item.zone).trim()) {
+                focusAssetZones.add(String(item.zone).trim());
+            }
+        }
+    }
+    let hadRealAssociatedTopology = false;
+    let projectedTopology = false;
+    const emitInFamily = (pluginId, familyValue, tier) => {
+        if (!familyValue || !pluginId)
+            return;
+        const familyId = buildId("vulnerabilityFamily", familyValue);
+        if (!familyId)
+            return;
+        if (tierFilter && tier && !tierFilter.has(tier))
+            return;
+        ensureSyntheticNode(nodes, familyId, "vulnerabilityFamily", "vulnerabilities-groups", tier);
+        const familyNode = nodes.get(familyId);
+        if (familyNode?.concept) {
+            familyNode.concept = {
+                ...familyNode.concept,
+                title: familyValue === "pending"
+                    ? "pending (data.vulnerabilityFamily not in sampled reports for this finding)"
+                    : familyValue,
+            };
+        }
+        addEdge(edges, {
+            type: "inFamily",
+            from: pluginId,
+            to: familyId,
+            tier,
+        });
+    };
+    const attachPathViaAsset = (pathId, targetZoneId, pathTier, explicitVia) => {
+        const targetZone = titleForId(targetZoneId, "zoneName");
+        const viaKey = typeof explicitVia === "string" && explicitVia.trim()
+            ? explicitVia.trim().startsWith("ipAddress:")
+                ? explicitVia.trim()
+                : buildId("ipAddress", explicitVia.trim())
+            : explicitVia === true ||
+                (explicitVia == null && focusAssetZones.has(targetZone))
+                ? focusConcept.identifier.identifierKey
+                : "";
+        if (!viaKey)
+            return;
+        if (!nodes.has(viaKey) && viaKey === focusConcept.identifier.identifierKey) {
+            upsertNode(nodes, focusNode);
+        }
+        if (!nodes.has(viaKey))
+            return;
+        addEdge(edges, {
+            type: "pathViaAsset",
+            from: pathId,
+            to: viaKey,
+            tier: pathTier,
+        });
+    };
+    const queue = [{ objectType: focusObjectType, doc: focusDoc, depth: 0 }];
+    const visited = new Set([
+        `${focusObjectType}:${focusConcept.identifier.identifierKey}`,
+    ]);
+    const emitEdgesForItem = async (template, frame, frameConcept, item, relatedDoc, relatedObjectType) => {
+        const relatedConcept = relatedDoc ? conceptFromRecord(relatedDoc) : null;
+        for (const emission of template.edges) {
+            if (!passesWhen(emission, item))
+                continue;
+            const fromIds = resolveIdRef(emission.from, {
+                concept: frameConcept,
+                relatedConcept,
+                item,
+            });
+            const toIds = resolveIdRef(emission.to, {
+                concept: frameConcept,
+                relatedConcept,
+                item,
+            });
+            if (!fromIds.length || !toIds.length)
+                continue;
+            const neighborSide = emission.neighbor ?? "to";
+            const neighborObjectType = neighborSide === "from"
+                ? relatedObjectType ?? emission.toObjectType
+                : emission.toObjectType;
+            const neighborKind = emission.toKind;
+            const neighborTier = tierForObjectType(descriptor, neighborObjectType);
+            if (tierFilter && neighborTier && !tierFilter.has(neighborTier)) {
+                continue;
+            }
+            for (const fromId of fromIds) {
+                for (const toId of toIds) {
+                    if (!fromId || !toId || fromId === toId)
+                        continue;
+                    // Upsert endpoint nodes
+                    for (const [endpointId, side] of [
+                        [fromId, "from"],
+                        [toId, "to"],
+                    ]) {
+                        if (nodes.has(endpointId))
+                            continue;
+                        const isNeighbor = side === neighborSide;
+                        if (isNeighbor && relatedDoc && relatedConcept) {
+                            const relatedRecordId = recordIdOf(relatedDoc);
+                            upsertNode(nodes, {
+                                id: endpointId,
+                                tier: neighborTier,
+                                concept: relatedConcept,
+                                objectType: neighborObjectType,
+                                recordId: relatedRecordId || undefined,
+                            });
+                        }
+                        else if (isNeighbor) {
+                            ensureSyntheticNode(nodes, endpointId, neighborKind, neighborObjectType, neighborTier);
+                        }
+                        else {
+                            // Other endpoint — synthetic from id kind
+                            const kindGuess = endpointId.includes(":")
+                                ? endpointId.slice(0, endpointId.indexOf(":"))
+                                : "unknown";
+                            const ot = descriptor.nodes.find((n) => (n.kind ?? "") === kindGuess)?.objectType ??
+                                frame.objectType;
+                            ensureSyntheticNode(nodes, endpointId, kindGuess, ot, tierForObjectType(descriptor, ot));
+                        }
+                    }
+                    if (emission.synthesizePath) {
+                        const fromTitle = titleForId(fromId, emission.from.source === "literal" ? emission.from.kind : neighborKind);
+                        const toTitle = titleForId(toId, emission.toKind);
+                        const title = (emission.synthesizePath.titleTemplate ?? "{from} → {to}")
+                            .replace("{from}", fromTitle)
+                            .replace("{to}", toTitle);
+                        const pathId = `pathId:${title}`;
+                        const pathTier = neighborTier ?? focusTier;
+                        if (!tierFilter || !pathTier || tierFilter.has(pathTier)) {
+                            upsertNode(nodes, {
+                                id: pathId,
+                                tier: pathTier,
+                                concept: {
+                                    identifier: {
+                                        kind: "pathId",
+                                        pathId: title,
+                                        identifierKey: pathId,
+                                    },
+                                    title,
+                                },
+                            });
+                            addEdge(edges, {
+                                type: "pathSource",
+                                from: pathId,
+                                to: fromId,
+                                tier: pathTier,
+                            });
+                            addEdge(edges, {
+                                type: "pathTarget",
+                                from: pathId,
+                                to: toId,
+                                tier: pathTier,
+                            });
+                            attachPathViaAsset(pathId, toId, pathTier);
+                        }
+                    }
+                    else {
+                        addEdge(edges, {
+                            type: emission.type,
+                            from: fromId,
+                            to: toId,
+                            tier: neighborTier ?? focusTier,
+                        });
+                        if (emission.type === "inGroup" &&
+                            (neighborKind === "pluginId" ||
+                                relatedConcept?.identifier.kind === "pluginId")) {
+                            const pluginId = neighborSide === "to" ? toId : fromId;
+                            const family = readVulnerabilityFamily(relatedDoc) ||
+                                readVulnerabilityFamily(frame.doc);
+                            emitInFamily(pluginId, family || "pending", neighborTier ?? focusTier);
+                        }
+                        if (emission.type === "inZone" && item?.zone != null) {
+                            focusAssetZones.add(String(item.zone).trim());
+                        }
+                        if (emission.type === "observedInZone" && item?.zone != null) {
+                            focusAssetZones.add(String(item.zone).trim());
+                        }
+                    }
+                }
+            }
+            // Enqueue related record for further template expansion
+            if (relatedDoc && relatedConcept && relatedObjectType && frame.depth + 1 < maxDepth) {
+                const key = `${relatedObjectType}:${relatedConcept.identifier.identifierKey}`;
+                if (!visited.has(key)) {
+                    visited.add(key);
+                    queue.push({
+                        objectType: relatedObjectType,
+                        doc: relatedDoc,
+                        depth: frame.depth + 1,
+                    });
+                }
+            }
+        }
+    };
+    const runTemplate = async (template, frame, frameConcept) => {
+        const src = template.source;
+        if (src.kind === "associatedArray") {
+            let items = Array.isArray(frame.doc[src.key])
+                ? frame.doc[src.key]
+                : [];
+            const hadRealItems = items.length > 0;
+            // Fallback: synthesize topology items from data fields when associated bucket missing
+            if (!items.length && src.key === "associatedTopology") {
+                const data = readDataObject(frame.doc);
+                // Subnet focus: expose zone/reachability in the same item shape assets use.
+                if (frame.objectType === "subnets") {
+                    const cidr = data.cidr != null
+                        ? String(data.cidr).trim()
+                        : frameConcept.identifier.kind === "cidr"
+                            ? String(frameConcept.identifier.cidr ??
+                                frameConcept.identifier.identifierKey.replace(/^cidr:/, "")).trim()
+                            : "";
+                    if (cidr) {
+                        items = [
+                            {
+                                cidr,
+                                zone: data.zone != null ? String(data.zone).trim() : "",
+                                reachableFromZones: asStringList(data.reachableFromZones),
+                            },
+                        ];
+                    }
+                }
+                const subnetCidrs = asStringList(data.subnetCidrs);
+                if (!items.length && subnetCidrs.length) {
+                    const cidr = subnetCidrs[0];
+                    let zone = asStringList(data.zones)[0] ?? "";
+                    let reachableFromZones = [];
+                    try {
+                        const matched = await listSnapshots(client, "subnets", {
+                            query: { "data.cidr": cidr },
+                            limit: 1,
+                        });
+                        const subnet = matched[0];
+                        if (subnet) {
+                            const subnetData = readDataObject(subnet);
+                            if (!zone && subnetData.zone != null)
+                                zone = String(subnetData.zone);
+                            reachableFromZones = asStringList(subnetData.reachableFromZones);
+                        }
+                    }
+                    catch {
+                        /* ignore lookup failures — keep empty reachability */
+                    }
+                    items = [{ cidr, zone, reachableFromZones }];
+                }
+                else if (!items.length) {
+                    const zones = asStringList(data.zones);
+                    if (zones.length) {
+                        items = zones.map((zone) => ({ zone }));
+                    }
+                }
+            }
+            if (src.key === "associatedTopology" && items.length) {
+                if (hadRealItems)
+                    hadRealAssociatedTopology = true;
+                else
+                    projectedTopology = true;
+                for (const item of items) {
+                    if (item.zone != null && String(item.zone).trim()) {
+                        focusAssetZones.add(String(item.zone).trim());
+                    }
+                }
+            }
+            for (const item of items) {
+                await emitEdgesForItem(template, frame, frameConcept, item, null, null);
+            }
+            // Enqueue real subnet snapshots so subnet-path-facts / possiblePaths can expand.
+            if (src.key === "associatedTopology" && frame.depth + 1 < maxDepth) {
+                for (const item of items) {
+                    const cidr = item.cidr != null ? String(item.cidr).trim() : "";
+                    if (!cidr)
+                        continue;
+                    try {
+                        const matched = await listSnapshots(client, "subnets", {
+                            query: { "data.cidr": cidr },
+                            limit: 1,
+                        });
+                        const subnet = matched[0];
+                        if (!subnet)
+                            continue;
+                        const subnetConcept = conceptFromRecord(subnet);
+                        if (!subnetConcept)
+                            continue;
+                        const key = `subnets:${subnetConcept.identifier.identifierKey}`;
+                        if (visited.has(key))
+                            continue;
+                        visited.add(key);
+                        const subnetRecordId = recordIdOf(subnet);
+                        upsertNode(nodes, {
+                            id: subnetConcept.identifier.identifierKey,
+                            tier: tierForObjectType(descriptor, "subnets"),
+                            concept: subnetConcept,
+                            objectType: "subnets",
+                            recordId: subnetRecordId || undefined,
+                        });
+                        queue.push({
+                            objectType: "subnets",
+                            doc: subnet,
+                            depth: frame.depth + 1,
+                        });
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+            }
+            return;
+        }
+        if (src.kind === "queryByField") {
+            const joinValue = readJoinValue(frame.doc, src.sourcePath);
+            if (joinValue == null || joinValue === "")
+                return;
+            const query = Array.isArray(joinValue)
+                ? { [src.targetPath]: { $in: joinValue } }
+                : { [src.targetPath]: joinValue };
+            let related = [];
+            try {
+                related = await listSnapshots(client, src.objectType, {
+                    query,
+                    limit: src.limit ?? 50,
+                });
+            }
+            catch {
+                related = [];
+            }
+            if (src.objectType === "vulnerabilities") {
+                notes.vulnerabilityCount = related.length;
+            }
+            for (const rel of related) {
+                await emitEdgesForItem(template, frame, frameConcept, null, rel, src.objectType);
+            }
+            return;
+        }
+        if (src.kind === "relation") {
+            const entity = await getEntity(frame.objectType);
+            const relation = entity?.relations?.[src.key];
+            if (!relation)
+                return;
+            const targetEntity = relation.targetEntity ?? relation.targetObjectType;
+            if (!targetEntity)
+                return;
+            const joinValue = readJoinValue(frame.doc, relation.source.path);
+            if (joinValue == null || joinValue === "")
+                return;
+            const query = Array.isArray(joinValue)
+                ? { [relation.target.path]: { $in: joinValue } }
+                : { [relation.target.path]: joinValue };
+            let related = [];
+            try {
+                related = await listSnapshots(client, targetEntity, {
+                    query,
+                    limit: 50,
+                });
+            }
+            catch {
+                related = [];
+            }
+            for (const rel of related) {
+                await emitEdgesForItem(template, frame, frameConcept, null, rel, targetEntity);
+            }
+            return;
+        }
+        if (src.kind === "pathFacts") {
+            const factsRaw = frame.doc[src.key];
+            if (!factsRaw)
+                return;
+            const facts = normalizePathFacts(factsRaw);
+            if (!facts.length) {
+                notes.pathFactsPresent = true;
+                return;
+            }
+            notes.pathFactsPresent = true;
+            const pathTier = tierForObjectType(descriptor, "topology-zones") ?? focusTier;
+            if (tierFilter && pathTier && !tierFilter.has(pathTier))
+                return;
+            const subnetZone = String(readDataObject(frame.doc).zone ?? "").trim() ||
+                [...focusAssetZones][0] ||
+                "";
+            for (const fact of facts) {
+                const fromZone = String(fact.from ?? "").trim();
+                const toZone = String(fact.to ?? "").trim();
+                if (!fromZone || !toZone)
+                    continue;
+                const hops = (fact.hops ?? []).map((h) => String(h).trim()).filter(Boolean);
+                const title = fact.title?.trim() ||
+                    [fromZone, ...hops, toZone].join(" → ");
+                const pathId = `pathId:${title}`;
+                upsertNode(nodes, {
+                    id: pathId,
+                    tier: pathTier,
+                    concept: {
+                        identifier: {
+                            kind: "pathId",
+                            pathId: title,
+                            identifierKey: pathId,
+                        },
+                        title,
+                    },
+                });
+                const fromId = buildId("zoneName", fromZone);
+                const toId = buildId("zoneName", toZone);
+                ensureSyntheticNode(nodes, fromId, "zoneName", "topology-zones", pathTier);
+                ensureSyntheticNode(nodes, toId, "zoneName", "topology-zones", pathTier);
+                addEdge(edges, {
+                    type: "pathSource",
+                    from: pathId,
+                    to: fromId,
+                    tier: pathTier,
+                });
+                for (const hop of hops) {
+                    const hopId = buildId("zoneName", hop);
+                    ensureSyntheticNode(nodes, hopId, "zoneName", "topology-zones", pathTier);
+                    addEdge(edges, {
+                        type: "pathHop",
+                        from: pathId,
+                        to: hopId,
+                        tier: pathTier,
+                    });
+                }
+                addEdge(edges, {
+                    type: "pathTarget",
+                    from: pathId,
+                    to: toId,
+                    tier: pathTier,
+                });
+                const viaExplicit = fact.viaAsset ??
+                    (subnetZone && (toZone === subnetZone || hops.includes(subnetZone))
+                        ? true
+                        : undefined);
+                attachPathViaAsset(pathId, toId, pathTier, viaExplicit);
+            }
+        }
+    };
+    while (queue.length) {
+        const frame = queue.shift();
+        const frameConcept = conceptFromRecord(frame.doc);
+        if (!frameConcept)
+            continue;
+        const entity = await getEntity(frame.objectType);
+        const cap = resolveEntityGraphCapability(frame.objectType, entity, inferredCaps[frame.objectType]);
+        const templates = (cap?.edgeTemplates ?? []).filter((t) => includeTemplates ? includeTemplates.has(t.id) : true);
+        for (const template of templates) {
+            await runTemplate(template, frame, frameConcept);
+        }
+    }
+    const focusKey = focusConcept.identifier.identifierKey;
+    notes.focusAssetId = focusKey;
+    notes.focusObjectType = focusObjectType;
+    notes.joinPoint = `${focusKey} connects topology tier ↔ vulnerabilities tier`;
+    const analytics = focusDoc.analytics;
+    if (analytics && typeof analytics === "object") {
+        const a = analytics;
+        const vulns = a.vulnerabilities;
+        if (vulns && typeof vulns === "object") {
+            notes.assetAnalytics = vulns;
+        }
+        else {
+            notes.assetAnalytics = analytics;
+        }
+    }
+    const namedInReports = getByPath(focusDoc, "data.namedInReports");
+    if (Array.isArray(namedInReports) && namedInReports.length) {
+        notes.namedInReports = namedInReports;
+    }
+    const topologyGap = collectTopologyGap(focusDoc, {
+        hadRealAssociatedTopology,
+        projectedTopology,
+    });
+    if (topologyGap)
+        notes.topologyGap = topologyGap;
+    return {
+        focus: {
+            recordId: focusRecordId || undefined,
+            concept: focusConcept,
+        },
+        nodes: [...nodes.values()],
+        edges,
+        notes,
+    };
+}
+//# sourceMappingURL=build-graph-document.js.map