@grafema/util 0.3.0-beta

package/dist/notation/lodExtractor.d.ts

@@ -0,0 +1,32 @@
+/**
+ * LOD (Level of Detail) Subgraph Extractor
+ *
+ * Extracts a SubgraphData from the graph backend using BFS from a root node.
+ * Different depth levels control how much of the graph neighborhood is fetched.
+ *
+ * - LOD 0: Root + direct containment children (names only in renderer)
+ * - LOD 1: Same + outgoing non-containment edges for each child, resolved targets
+ * - LOD 2: Same + expand children that have their own CONTAINS children
+ *
+ * @module notation/lodExtractor
+ */
+import type { BaseNodeRecord, EdgeRecord } from '@grafema/types';
+import type { SubgraphData } from './types.js';
+/**
+ * Minimal backend interface — matches the project pattern of loose coupling.
+ */
+interface GraphBackend {
+    getNode(id: string): Promise<BaseNodeRecord | null>;
+    getOutgoingEdges(nodeId: string, edgeTypes?: string[] | null): Promise<EdgeRecord[]>;
+    getIncomingEdges(nodeId: string, edgeTypes?: string[] | null): Promise<EdgeRecord[]>;
+}
+/**
+ * Extract a subgraph from the backend, rooted at the given node.
+ *
+ * @param backend  Graph backend
+ * @param rootNodeId  Semantic ID of the root node
+ * @param depth  LOD level (0, 1, or 2)
+ */
+export declare function extractSubgraph(backend: GraphBackend, rootNodeId: string, depth?: number): Promise<SubgraphData>;
+export {};
+//# sourceMappingURL=lodExtractor.d.ts.map

package/dist/notation/lodExtractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lodExtractor.d.ts","sourceRoot":"","sources":["../../src/notation/lodExtractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C;;GAEG;AACH,UAAU,YAAY;IACpB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACpD,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IACrF,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;CACtF;AAYD;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,MAAM,EAClB,KAAK,GAAE,MAAU,GAChB,OAAO,CAAC,YAAY,CAAC,CAqFvB"}

package/dist/notation/lodExtractor.js

@@ -0,0 +1,149 @@
+/**
+ * LOD (Level of Detail) Subgraph Extractor
+ *
+ * Extracts a SubgraphData from the graph backend using BFS from a root node.
+ * Different depth levels control how much of the graph neighborhood is fetched.
+ *
+ * - LOD 0: Root + direct containment children (names only in renderer)
+ * - LOD 1: Same + outgoing non-containment edges for each child, resolved targets
+ * - LOD 2: Same + expand children that have their own CONTAINS children
+ *
+ * @module notation/lodExtractor
+ */
+import { lookupEdge } from './archetypes.js';
+/**
+ * Containment edge types that define the nesting tree.
+ */
+const CONTAINMENT_TYPES = [
+    'CONTAINS', 'HAS_SCOPE', 'HAS_MEMBER', 'HAS_BODY',
+    'HAS_PROPERTY', 'HAS_ELEMENT', 'HAS_INIT', 'HAS_UPDATE',
+    'HAS_CALLBACK', 'HAS_CATCH', 'HAS_FINALLY',
+    'DECLARES', 'DEFINES', 'MOUNTS', 'PROPERTY_KEY', 'PROPERTY_VALUE',
+];
+/**
+ * Extract a subgraph from the backend, rooted at the given node.
+ *
+ * @param backend  Graph backend
+ * @param rootNodeId  Semantic ID of the root node
+ * @param depth  LOD level (0, 1, or 2)
+ */
+export async function extractSubgraph(backend, rootNodeId, depth = 1) {
+    const nodeMap = new Map();
+    const allEdges = [];
+    const root = await backend.getNode(rootNodeId);
+    if (!root) {
+        return { rootNodes: [], edges: [], nodeMap };
+    }
+    nodeMap.set(root.id, root);
+    // Step 1: Get direct containment children
+    const containmentEdges = await backend.getOutgoingEdges(rootNodeId, CONTAINMENT_TYPES);
+    const childIds = [];
+    for (const edge of containmentEdges) {
+        allEdges.push(edge);
+        childIds.push(edge.dst);
+        if (!nodeMap.has(edge.dst)) {
+            const child = await backend.getNode(edge.dst);
+            if (child)
+                nodeMap.set(child.id, child);
+        }
+    }
+    // LOD 0: stop here (renderer shows names only)
+    if (depth <= 0) {
+        return { rootNodes: [root], edges: allEdges, nodeMap };
+    }
+    // Step 2: For each child (and root), get outgoing non-containment edges
+    const nodesToExpand = [rootNodeId, ...childIds];
+    for (const nodeId of nodesToExpand) {
+        const outgoing = await backend.getOutgoingEdges(nodeId);
+        for (const edge of outgoing) {
+            const mapping = lookupEdge(edge.type);
+            if (mapping.archetype === 'contains')
+                continue; // already handled
+            allEdges.push(edge);
+            // Resolve target nodes
+            if (!nodeMap.has(edge.dst)) {
+                const target = await backend.getNode(edge.dst);
+                if (target)
+                    nodeMap.set(target.id, target);
+            }
+        }
+    }
+    // LOD 1: stop here
+    if (depth <= 1) {
+        return { rootNodes: [root], edges: allEdges, nodeMap };
+    }
+    // Step 3 (LOD 2): Expand children that have their own containment children
+    for (const childId of childIds) {
+        const childContainment = await backend.getOutgoingEdges(childId, CONTAINMENT_TYPES);
+        for (const edge of childContainment) {
+            allEdges.push(edge);
+            if (!nodeMap.has(edge.dst)) {
+                const grandchild = await backend.getNode(edge.dst);
+                if (grandchild)
+                    nodeMap.set(grandchild.id, grandchild);
+            }
+        }
+        // Also get operator edges for grandchildren
+        const grandchildIds = childContainment.map(e => e.dst);
+        for (const gcId of grandchildIds) {
+            const gcOutgoing = await backend.getOutgoingEdges(gcId);
+            for (const edge of gcOutgoing) {
+                const mapping = lookupEdge(edge.type);
+                if (mapping.archetype === 'contains')
+                    continue;
+                allEdges.push(edge);
+                if (!nodeMap.has(edge.dst)) {
+                    const target = await backend.getNode(edge.dst);
+                    if (target)
+                        nodeMap.set(target.id, target);
+                }
+            }
+        }
+    }
+    // Step 4: Fetch incoming PASSES_ARGUMENT edges for anonymous functions
+    // so the renderer can resolve λ names via callback context.
+    // CALL nodes are often not in the containment tree, so their outgoing
+    // PASSES_ARGUMENT edges don't get picked up by the BFS above.
+    await fetchCallbackContext(backend, allEdges, nodeMap);
+    return { rootNodes: [root], edges: allEdges, nodeMap };
+}
+/**
+ * For each anonymous arrow/expression in nodeMap, fetch incoming
+ * PASSES_ARGUMENT edges and resolve the CALL source node + sibling args.
+ */
+async function fetchCallbackContext(backend, allEdges, nodeMap) {
+    const edgeSet = new Set(allEdges.map(e => `${e.src}|${e.dst}|${e.type}`));
+    for (const node of nodeMap.values()) {
+        if (node.name !== '<arrow>' && node.name !== '<expression>')
+            continue;
+        const incoming = await backend.getIncomingEdges(node.id, ['PASSES_ARGUMENT']);
+        for (const edge of incoming) {
+            const key = `${edge.src}|${edge.dst}|${edge.type}`;
+            if (edgeSet.has(key))
+                continue;
+            edgeSet.add(key);
+            allEdges.push(edge);
+            // Resolve the CALL node (edge source)
+            if (!nodeMap.has(edge.src)) {
+                const callNode = await backend.getNode(edge.src);
+                if (callNode)
+                    nodeMap.set(callNode.id, callNode);
+            }
+            // Fetch all PASSES_ARGUMENT from same CALL to find sibling args
+            const callOutgoing = await backend.getOutgoingEdges(edge.src, ['PASSES_ARGUMENT']);
+            for (const sibEdge of callOutgoing) {
+                const sibKey = `${sibEdge.src}|${sibEdge.dst}|${sibEdge.type}`;
+                if (edgeSet.has(sibKey))
+                    continue;
+                edgeSet.add(sibKey);
+                allEdges.push(sibEdge);
+                if (!nodeMap.has(sibEdge.dst)) {
+                    const sibNode = await backend.getNode(sibEdge.dst);
+                    if (sibNode)
+                        nodeMap.set(sibNode.id, sibNode);
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=lodExtractor.js.map

package/dist/notation/lodExtractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lodExtractor.js","sourceRoot":"","sources":["../../src/notation/lodExtractor.ts"],"names":[],"mappings":"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"}

package/dist/notation/nameShortener.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Name Shortener — shortest-unambiguous-name within scope
+ *
+ * Given a set of display names in a subgraph, shorten them to the
+ * minimum unique suffix. For example:
+ *
+ *   auth/login.ts -> UserDB.findByEmail  →  UserDB.findByEmail
+ *   auth/login.ts -> createToken         →  createToken
+ *   auth/utils.ts -> createToken         →  utils:createToken
+ *
+ * Phase 4 feature — placeholder for future implementation.
+ *
+ * @module notation/nameShortener
+ */
+/**
+ * Shorten a display name to its shortest unambiguous form
+ * within the given set of all names.
+ *
+ * Current implementation: return name as-is (no shortening).
+ */
+export declare function shortenName(name: string, _allNames: string[]): string;
+//# sourceMappingURL=nameShortener.d.ts.map

package/dist/notation/nameShortener.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nameShortener.d.ts","sourceRoot":"","sources":["../../src/notation/nameShortener.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAErE"}

package/dist/notation/nameShortener.js

@@ -0,0 +1,24 @@
+/**
+ * Name Shortener — shortest-unambiguous-name within scope
+ *
+ * Given a set of display names in a subgraph, shorten them to the
+ * minimum unique suffix. For example:
+ *
+ *   auth/login.ts -> UserDB.findByEmail  →  UserDB.findByEmail
+ *   auth/login.ts -> createToken         →  createToken
+ *   auth/utils.ts -> createToken         →  utils:createToken
+ *
+ * Phase 4 feature — placeholder for future implementation.
+ *
+ * @module notation/nameShortener
+ */
+/**
+ * Shorten a display name to its shortest unambiguous form
+ * within the given set of all names.
+ *
+ * Current implementation: return name as-is (no shortening).
+ */
+export function shortenName(name, _allNames) {
+    return name;
+}
+//# sourceMappingURL=nameShortener.js.map

package/dist/notation/nameShortener.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nameShortener.js","sourceRoot":"","sources":["../../src/notation/nameShortener.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,SAAmB;IAC3D,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/notation/perspectives.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Perspective Presets — archetype filters for describe tool
+ *
+ * Shared between MCP and CLI to keep perspectives in sync.
+ *
+ * @module notation/perspectives
+ */
+import type { Archetype } from './types.js';
+/** Perspective presets map to archetype filters */
+export declare const PERSPECTIVES: Record<string, Archetype[]>;
+//# sourceMappingURL=perspectives.d.ts.map

package/dist/notation/perspectives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perspectives.d.ts","sourceRoot":"","sources":["../../src/notation/perspectives.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,mDAAmD;AACnD,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAMpD,CAAC"}

package/dist/notation/perspectives.js

@@ -0,0 +1,16 @@
+/**
+ * Perspective Presets — archetype filters for describe tool
+ *
+ * Shared between MCP and CLI to keep perspectives in sync.
+ *
+ * @module notation/perspectives
+ */
+/** Perspective presets map to archetype filters */
+export const PERSPECTIVES = {
+    security: ['write', 'exception'],
+    data: ['flow_out', 'flow_in', 'write'],
+    errors: ['exception'],
+    api: ['flow_out', 'publishes', 'depends'],
+    events: ['publishes'],
+};
+//# sourceMappingURL=perspectives.js.map

package/dist/notation/perspectives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"perspectives.js","sourceRoot":"","sources":["../../src/notation/perspectives.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,mDAAmD;AACnD,MAAM,CAAC,MAAM,YAAY,GAAgC;IACvD,QAAQ,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC;IAChC,IAAI,EAAE,CAAC,UAAU,EAAE,SAAS,EAAE,OAAO,CAAC;IACtC,MAAM,EAAE,CAAC,WAAW,CAAC;IACrB,GAAG,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,SAAS,CAAC;IACzC,MAAM,EAAE,CAAC,WAAW,CAAC;CACtB,CAAC"}

package/dist/notation/renderer.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Notation Renderer — pure function: SubgraphData → DSL string
+ *
+ * Pipeline:
+ * 1. Classify edges via EDGE_ARCHETYPE_MAP
+ * 2. Separate containment from operator edges
+ * 3. Group operator edges by source node
+ * 4. Sort lines by sortOrder
+ * 5. Merge same-operator same-verb targets
+ * 6. Serialize to indented DSL text
+ *
+ * @module notation/renderer
+ */
+import type { DescribeOptions, SubgraphData } from './types.js';
+/**
+ * Render a subgraph as compact DSL notation.
+ *
+ * Example output:
+ * ```
+ * login {
+ *   o- imports bcrypt
+ *   > calls UserDB.findByEmail, createToken
+ *   < reads config.auth
+ *   => writes session
+ *   >x throws AuthError
+ *   ~>> emits 'auth:login'
+ * }
+ * ```
+ */
+export declare function renderNotation(input: SubgraphData, options?: DescribeOptions): string;
+//# sourceMappingURL=renderer.d.ts.map

package/dist/notation/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../src/notation/renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,eAAe,EAA+B,YAAY,EAAE,MAAM,YAAY,CAAC;AAK7F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE,eAAoB,GAC5B,MAAM,CAMR"}

package/dist/notation/renderer.js

@@ -0,0 +1,315 @@
+/**
+ * Notation Renderer — pure function: SubgraphData → DSL string
+ *
+ * Pipeline:
+ * 1. Classify edges via EDGE_ARCHETYPE_MAP
+ * 2. Separate containment from operator edges
+ * 3. Group operator edges by source node
+ * 4. Sort lines by sortOrder
+ * 5. Merge same-operator same-verb targets
+ * 6. Serialize to indented DSL text
+ *
+ * @module notation/renderer
+ */
+import { lookupEdge } from './archetypes.js';
+import { getNodeDisplayName } from '../queries/NodeContext.js';
+import { foldBlocks } from './fold.js';
+/**
+ * Render a subgraph as compact DSL notation.
+ *
+ * Example output:
+ * ```
+ * login {
+ *   o- imports bcrypt
+ *   > calls UserDB.findByEmail, createToken
+ *   < reads config.auth
+ *   => writes session
+ *   >x throws AuthError
+ *   ~>> emits 'auth:login'
+ * }
+ * ```
+ */
+export function renderNotation(input, options = {}) {
+    const { depth = 1, archetypeFilter, budget = 7, includeLocations = false } = options;
+    const blocks = buildBlocks(input, depth, archetypeFilter, budget, includeLocations);
+    const finalBlocks = depth === 2 ? foldBlocks(blocks) : blocks;
+    return serializeBlocks(finalBlocks, 0);
+}
+// ---------------------------------------------------------------------------
+// Block building
+// ---------------------------------------------------------------------------
+function buildBlocks(input, depth, archetypeFilter, budget, includeLocations) {
+    const { rootNodes, edges, nodeMap } = input;
+    // Index: src → edges, containment edges (src → child node IDs)
+    const outgoingBySource = new Map();
+    const childrenOf = new Map();
+    for (const edge of edges) {
+        const mapping = lookupEdge(edge.type);
+        if (mapping.archetype === 'contains') {
+            // Containment defines tree structure
+            if (!childrenOf.has(edge.src))
+                childrenOf.set(edge.src, []);
+            childrenOf.get(edge.src).push(edge.dst);
+        }
+        else {
+            if (!outgoingBySource.has(edge.src))
+                outgoingBySource.set(edge.src, []);
+            outgoingBySource.get(edge.src).push(edge);
+        }
+    }
+    // Build set of node IDs that are descendants of LOOP nodes in containment tree
+    const insideLoopNodes = buildLoopDescendants(childrenOf, nodeMap);
+    const resolvedNames = resolveAnonymousNames(edges, nodeMap);
+    return rootNodes.map(node => buildBlock(node, outgoingBySource, childrenOf, nodeMap, depth, archetypeFilter, budget, includeLocations, insideLoopNodes, resolvedNames));
+}
+/**
+ * Collect all node IDs that are descendants of LOOP-type nodes in the containment tree.
+ * Uses BFS from each LOOP node, traversing containment children recursively.
+ */
+function buildLoopDescendants(childrenOf, nodeMap) {
+    const result = new Set();
+    // Find all LOOP nodes and collect their descendants
+    for (const [parentId, children] of childrenOf) {
+        const parentNode = nodeMap.get(parentId);
+        if (parentNode?.type === 'LOOP') {
+            // BFS to collect all descendants of this LOOP node
+            const queue = [...children];
+            while (queue.length > 0) {
+                const id = queue.shift();
+                if (result.has(id))
+                    continue;
+                result.add(id);
+                const grandchildren = childrenOf.get(id);
+                if (grandchildren) {
+                    queue.push(...grandchildren);
+                }
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Resolve meaningful names for anonymous arrow functions and expressions.
+ *
+ * Priority:
+ * 1. Assignment: `const handler = () => {}` → "handler"
+ * 2. Callback: `setRequestHandler(Schema, λ)` → "λ → setRequestHandler(Schema)"
+ * 3. Fallback: "λ"
+ */
+function resolveAnonymousNames(edges, nodeMap) {
+    const resolved = new Map();
+    // Reverse index: dstId → edges (for ASSIGNED_FROM and PASSES_ARGUMENT)
+    const incomingByDst = new Map();
+    // Forward index: srcId → PASSES_ARGUMENT edges (for finding siblings)
+    const passArgBySrc = new Map();
+    for (const edge of edges) {
+        if (edge.type === 'ASSIGNED_FROM' || edge.type === 'PASSES_ARGUMENT') {
+            if (!incomingByDst.has(edge.dst))
+                incomingByDst.set(edge.dst, []);
+            incomingByDst.get(edge.dst).push(edge);
+        }
+        if (edge.type === 'PASSES_ARGUMENT') {
+            if (!passArgBySrc.has(edge.src))
+                passArgBySrc.set(edge.src, []);
+            passArgBySrc.get(edge.src).push(edge);
+        }
+    }
+    for (const [nodeId, node] of nodeMap) {
+        if (node.name !== '<arrow>' && node.name !== '<expression>')
+            continue;
+        const incoming = incomingByDst.get(nodeId) ?? [];
+        // Priority 1: Assignment — const handler = () => {}
+        const assignEdge = incoming.find(e => e.type === 'ASSIGNED_FROM');
+        if (assignEdge) {
+            const srcNode = nodeMap.get(assignEdge.src);
+            if (srcNode?.name && srcNode.name !== '<arrow>' && srcNode.name !== '<expression>') {
+                resolved.set(nodeId, srcNode.name);
+                continue;
+            }
+        }
+        // Priority 2: Callback — setRequestHandler(Schema, λ)
+        const passEdge = incoming.find(e => e.type === 'PASSES_ARGUMENT');
+        if (passEdge) {
+            const callNode = nodeMap.get(passEdge.src);
+            const callName = callNode ? getNodeDisplayName(callNode) : null;
+            if (callName && callName !== '<arrow>' && callName !== '<expression>' && callName !== 'λ') {
+                // Named sibling args (skip other anonymous ones)
+                const allSiblings = passArgBySrc.get(passEdge.src) ?? [];
+                const namedSiblings = allSiblings
+                    .filter(e => e.dst !== nodeId)
+                    .map(e => {
+                    const argNode = nodeMap.get(e.dst);
+                    if (!argNode?.name)
+                        return null;
+                    if (argNode.name === '<arrow>' || argNode.name === '<expression>')
+                        return null;
+                    return argNode.name;
+                })
+                    .filter((n) => n !== null);
+                // Multiple lambdas in same call → add index to distinguish
+                const lambdaCount = allSiblings.filter(e => {
+                    const n = nodeMap.get(e.dst);
+                    return n && (n.name === '<arrow>' || n.name === '<expression>');
+                }).length;
+                const indexSuffix = lambdaCount > 1
+                    ? String(passEdge.metadata?.index ?? passEdge.metadata?.argIndex ?? '')
+                    : '';
+                const argStr = namedSiblings.length > 0 ? `(${namedSiblings.join(', ')})` : '';
+                resolved.set(nodeId, `λ${indexSuffix} → ${callName}${argStr}`);
+                continue;
+            }
+        }
+        // Priority 3: Fallback
+        resolved.set(nodeId, 'λ');
+    }
+    return resolved;
+}
+function buildBlock(node, outgoingBySource, childrenOf, nodeMap, depth, archetypeFilter, budget, includeLocations, insideLoopNodes, resolvedNames) {
+    const displayName = resolvedNames.get(node.id) ?? getNodeDisplayName(node);
+    const location = includeLocations && node.file
+        ? `${node.file}${node.line ? ':' + node.line : ''}`
+        : undefined;
+    // LOD 0: names only — no edges, no children
+    if (depth <= 0) {
+        return { nodeId: node.id, displayName, nodeType: node.type, lines: [], children: [], location };
+    }
+    // LOD 1+: build edge lines
+    const nodeEdges = outgoingBySource.get(node.id) ?? [];
+    const lines = buildLines(nodeEdges, nodeMap, archetypeFilter, budget, resolvedNames);
+    // Apply [] loop modifier if this node is inside a LOOP
+    // Combines with existing modifiers: [] ?? > calls foo
+    if (insideLoopNodes.has(node.id)) {
+        for (const line of lines) {
+            line.modifier = line.modifier ? `[] ${line.modifier}` : '[]';
+        }
+    }
+    // LOD 2+: recurse into contained children
+    let children = [];
+    if (depth >= 2) {
+        const childIds = childrenOf.get(node.id) ?? [];
+        children = childIds
+            .map(id => nodeMap.get(id))
+            .filter((n) => n != null)
+            .map(child => buildBlock(child, outgoingBySource, childrenOf, nodeMap, depth - 1, archetypeFilter, budget, includeLocations, insideLoopNodes, resolvedNames));
+    }
+    return { nodeId: node.id, displayName, nodeType: node.type, lines, children, location };
+}
+// ---------------------------------------------------------------------------
+// Line building — group, sort, merge
+// ---------------------------------------------------------------------------
+function buildLines(edges, nodeMap, archetypeFilter, budget, resolvedNames) {
+    // Group by modifier+operator+verb key (modifier separates certain from uncertain)
+    const groups = new Map();
+    for (const edge of edges) {
+        const mapping = lookupEdge(edge.type);
+        // Apply archetype filter
+        if (archetypeFilter && !archetypeFilter.includes(mapping.archetype))
+            continue;
+        const targetNode = nodeMap.get(edge.dst);
+        const targetName = resolvedNames.get(edge.dst) ?? (targetNode ? getNodeDisplayName(targetNode) : edge.dst);
+        // Detect dynamic/uncertain edges
+        const modifier = isDynamicEdge(edge) ? '??' : undefined;
+        const key = `${modifier ?? ''}|${mapping.operator}|${mapping.verb}`;
+        if (!groups.has(key)) {
+            groups.set(key, {
+                operator: mapping.operator,
+                verb: mapping.verb,
+                targets: [],
+                sortOrder: mapping.sortOrder,
+                modifier,
+            });
+        }
+        groups.get(key).targets.push(targetName);
+    }
+    // Sort by sortOrder
+    const sorted = Array.from(groups.values()).sort((a, b) => a.sortOrder - b.sortOrder);
+    // Apply budget: show top-N, summarize rest
+    if (sorted.length > budget) {
+        const shown = sorted.slice(0, budget);
+        const hidden = sorted.slice(budget);
+        const hiddenCount = hidden.reduce((sum, g) => sum + g.targets.length, 0);
+        shown.push({
+            operator: '',
+            verb: `...+${hiddenCount} more`,
+            targets: [],
+            sortOrder: 999,
+        });
+        return shown.map(g => ({
+            operator: g.operator,
+            verb: g.verb,
+            targets: g.targets,
+            sortOrder: g.sortOrder,
+            modifier: g.modifier,
+        }));
+    }
+    return sorted.map(g => ({
+        operator: g.operator,
+        verb: g.verb,
+        targets: g.targets,
+        sortOrder: g.sortOrder,
+        modifier: g.modifier,
+    }));
+}
+// ---------------------------------------------------------------------------
+// Edge metadata helpers
+// ---------------------------------------------------------------------------
+/**
+ * Check if an edge is dynamic/uncertain based on its metadata.
+ *
+ * An edge is dynamic/uncertain if any of these hold:
+ * - metadata.resolved === false (unresolved reference)
+ * - metadata.confidence exists and is < 1.0 (low-confidence inference)
+ * - metadata.dynamic === true (dynamic dispatch)
+ */
+function isDynamicEdge(edge) {
+    const meta = edge.metadata;
+    if (!meta)
+        return false;
+    if (meta.resolved === false)
+        return true;
+    if (typeof meta.confidence === 'number' && meta.confidence < 1.0)
+        return true;
+    if (meta.dynamic === true)
+        return true;
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Serialization
+// ---------------------------------------------------------------------------
+function serializeBlocks(blocks, indentLevel) {
+    return blocks.map(block => serializeBlock(block, indentLevel)).join('\n');
+}
+function serializeBlock(block, indentLevel) {
+    const indent = '  '.repeat(indentLevel);
+    const hasContent = block.lines.length > 0 || block.children.length > 0;
+    // Header
+    const loc = block.location ? `  (${block.location})` : '';
+    let result;
+    if (!hasContent) {
+        // Leaf node — just name
+        result = `${indent}${block.displayName}${loc}`;
+    }
+    else {
+        result = `${indent}${block.displayName}${loc} {\n`;
+        // Lines
+        for (const line of block.lines) {
+            result += serializeLine(line, indentLevel + 1);
+        }
+        // Children
+        if (block.children.length > 0) {
+            result += serializeBlocks(block.children, indentLevel + 1) + '\n';
+        }
+        result += `${indent}}`;
+    }
+    return result;
+}
+function serializeLine(line, indentLevel) {
+    const indent = '  '.repeat(indentLevel);
+    const mod = line.modifier ? `${line.modifier} ` : '';
+    const prefix = line.operator ? `${line.operator} ` : '';
+    if (line.targets.length === 0) {
+        return `${indent}${mod}${prefix}${line.verb}\n`;
+    }
+    return `${indent}${mod}${prefix}${line.verb} ${line.targets.join(', ')}\n`;
+}
+//# sourceMappingURL=renderer.js.map