@sprig-and-prose/sprig-universe 0.3.4 → 0.4.1

package/src/graph.js

@@ -22,6 +22,7 @@ import { normalizeProseBlock } from './util/text.js';
  * @typedef {import('./ast.js').ChapterDecl} ChapterDecl
  * @typedef {import('./ast.js').ConceptDecl} ConceptDecl
  * @typedef {import('./ast.js').RelatesDecl} RelatesDecl
+ * @typedef {import('./ast.js').RelationshipDecl} RelationshipDecl
  * @typedef {import('./ast.js').DescribeBlock} DescribeBlock
  * @typedef {import('./ast.js').TitleBlock} TitleBlock
  * @typedef {import('./ast.js').FromBlock} FromBlock
@@ -49,7 +50,7 @@ export function buildGraph(fileASTs) {
     version: 1,
     universes: {},
     nodes: {},
-    edges: {},
+    edges: [],
     diagnostics: [],
     documentsByName: {},
     repositories: {},
@@ -66,6 +67,15 @@ export function buildGraph(fileASTs) {
   // Track repositories and references per universe for scoped resolution
   const repositoriesByUniverse = new Map(); // universeName -> Map<id, RepositoryDecl>
   const referencesByUniverse = new Map(); // universeName -> Map<id, ReferenceDecl>
+  
+  // Track relationship declarations per scope (containerNodeId -> Map<relationshipId, RelationshipDecl>)
+  const relationshipsByScope = new Map(); // containerNodeId -> Map<relationshipId, RelationshipDecl>
+  
+  // Store relationship declarations by universe for UI access
+  const relationshipDeclsByUniverse = new Map(); // universeName -> Map<relationshipId, RelationshipDecl>
+  
+  // Initialize relationshipDecls in graph
+  graph.relationshipDecls = {};
 
   // Track entity kinds for duplicate detection (references/repositories)
   const entityKinds = new Map(); // id -> kind
@@ -190,6 +200,8 @@ export function buildGraph(fileASTs) {
           repositoriesByUniverse.get(universeName),
           referencesByUniverse.get(universeName),
           entityKinds,
+          relationshipsByScope,
+          relationshipDeclsByUniverse,
           pendingReferenceDecls,
           pendingReferenceAttachments,
           pendingContainerResolutions,
@@ -220,6 +232,8 @@ export function buildGraph(fileASTs) {
           repositoriesByUniverse.get(universeName),
           referencesByUniverse.get(universeName),
           entityKinds,
+          relationshipsByScope,
+          relationshipDeclsByUniverse,
           pendingReferenceDecls,
           pendingReferenceAttachments,
           pendingContainerResolutions,
@@ -256,6 +270,7 @@ export function buildGraph(fileASTs) {
               continue;
             }
           }
+          // Process the declaration itself first
           processBody(
             graph,
             universeName,
@@ -268,6 +283,8 @@ export function buildGraph(fileASTs) {
             repositoriesByUniverse.get(universeName),
             referencesByUniverse.get(universeName),
             entityKinds,
+            relationshipsByScope,
+            relationshipDeclsByUniverse,
             pendingReferenceDecls,
             pendingReferenceAttachments,
             pendingContainerResolutions,
@@ -298,6 +315,31 @@ export function buildGraph(fileASTs) {
   // Validate and apply ordering blocks after all nodes and relationships are established
   validateOrderingBlocks(graph);
 
+  // Extract asserted edges from both relationships blocks and relates nodes
+  graph.edgesAsserted = extractAssertedEdges(graph, scopeIndex);
+
+  // Normalize edges (add inverse edges for paired/symmetric relationships)
+  const universeNames = Array.from(universeNameToFiles.keys());
+  if (universeNames.length > 0) {
+    // For now, assume single universe (as per buildGraph contract)
+    const universeName = universeNames[0];
+    graph.edges = normalizeEdges(
+      graph.edgesAsserted,
+      relationshipDeclsByUniverse,
+      universeName,
+    );
+  } else {
+    graph.edges = [];
+  }
+
+  // Convert relationshipDeclsByUniverse Maps to plain objects for JSON serialization
+  // (already done above, but ensure all universes are initialized)
+  for (const [universeName, declsMap] of relationshipDeclsByUniverse.entries()) {
+    if (!graph.relationshipDecls[universeName]) {
+      graph.relationshipDecls[universeName] = {};
+    }
+  }
+
   return graph;
 }
 
@@ -337,6 +379,46 @@ function addNameToScope(graph, scopeIndex, scopeNodeId, name, nodeId) {
   }
 }
 
+/**
+ * Finds the series containing a given node by walking up the parent chain
+ * @param {UniverseGraph} graph - The graph
+ * @param {string} nodeId - Node ID to find series for
+ * @returns {string | null} - Series node ID, or null if not found
+ */
+function findSeriesForNode(graph, nodeId) {
+  const node = graph.nodes[nodeId];
+  if (!node) return null;
+  
+  let checkNode = node;
+  while (checkNode && checkNode.parent) {
+    checkNode = graph.nodes[checkNode.parent];
+    if (checkNode && checkNode.kind === 'series') {
+      return checkNode.id;
+    }
+  }
+  return null;
+}
+
+/**
+ * Prefers a candidate from the same series as the starting node when multiple candidates exist
+ * @param {UniverseGraph} graph - The graph
+ * @param {string} startScopeNodeId - Starting node ID
+ * @param {string[]} candidates - Array of candidate node IDs
+ * @returns {string | null} - Preferred candidate node ID, or null if none found
+ */
+function preferSameSeriesCandidate(graph, startScopeNodeId, candidates) {
+  const seriesNodeId = findSeriesForNode(graph, startScopeNodeId);
+  if (!seriesNodeId) return null;
+  
+  for (const candidateId of candidates) {
+    const candidateSeriesNodeId = findSeriesForNode(graph, candidateId);
+    if (candidateSeriesNodeId === seriesNodeId) {
+      return candidateId;
+    }
+  }
+  return null;
+}
+
 /**
  * Resolves a name by walking the scope chain (current container -> parent -> ... -> universe)
  * Returns the first matching node ID found, or null if not found
@@ -350,7 +432,7 @@ function addNameToScope(graph, scopeIndex, scopeNodeId, name, nodeId) {
  */
 function resolveNameInScope(graph, scopeIndex, name, startScopeNodeId, source) {
   // Handle qualified names (dot notation)
-  if (name.includes('.')) {
+  if (name && name.includes('.')) {
     const parts = name.split('.');
     // Start from universe and resolve each part
     const universeName = startScopeNodeId.split(':')[0];
@@ -400,7 +482,14 @@ function resolveNameInScope(graph, scopeIndex, name, startScopeNodeId, source) {
       } else if (candidates.length === 1) {
         return { nodeId: candidates[0], ambiguous: false, ambiguousNodes: [] };
       } else {
-        // Ambiguity at this scope level
+        // Ambiguity at this scope level - try to disambiguate by preferring same series
+        const preferredCandidate = preferSameSeriesCandidate(graph, startScopeNodeId, candidates);
+        
+        if (preferredCandidate) {
+          return { nodeId: preferredCandidate, ambiguous: false, ambiguousNodes: [] };
+        }
+        
+        // No preferred candidate found - report ambiguity
         if (source) {
           const scopeNode = graph.nodes[currentScope];
           const scopeName = scopeNode ? (scopeNode.name || currentScope) : currentScope;
@@ -430,6 +519,14 @@ function resolveNameInScope(graph, scopeIndex, name, startScopeNodeId, source) {
           if (candidates.length === 1) {
             return { nodeId: candidates[0], ambiguous: false, ambiguousNodes: [] };
           } else if (candidates.length > 1) {
+            // Multiple matches at universe scope - try to disambiguate by preferring same series
+            const preferredCandidate = preferSameSeriesCandidate(graph, startScopeNodeId, candidates);
+            
+            if (preferredCandidate) {
+              return { nodeId: preferredCandidate, ambiguous: false, ambiguousNodes: [] };
+            }
+            
+            // No preferred candidate found - report ambiguity
             if (source) {
               graph.diagnostics.push({
                 severity: 'error',
@@ -506,6 +603,8 @@ function resolveRelatesEndpoint(graph, scopeIndex, name, startScopeNodeId, sourc
  * @param {Map<string, RepositoryDecl>} [reposMap] - Map for tracking repository declarations (universe scope only)
  * @param {Map<string, ReferenceDecl>} [refsMap] - Map for tracking reference declarations (universe scope only)
  * @param {Map<string, string>} [entityKinds] - Map for tracking non-node entity kinds by ID
+ * @param {Map<string, Map<string, RelationshipDecl>>} relationshipsByScope - Map for tracking relationship declarations per scope (required)
+ * @param {Map<string, Map<string, RelationshipDecl>>} relationshipDeclsByUniverse - Map for storing relationship declarations by universe for UI access
  * @param {Array} [pendingReferenceDecls] - Reference declarations to resolve after indexing
  * @param {Array} [pendingReferenceAttachments] - Reference attachments to resolve after indexing
  * @param {Array} [pendingContainerResolutions] - Container resolutions to resolve after all nodes are created
@@ -522,6 +621,8 @@ function processBody(
   reposMap,
   refsMap,
   entityKinds,
+  relationshipsByScope,
+  relationshipDeclsByUniverse,
   pendingReferenceDecls,
   pendingReferenceAttachments,
   pendingContainerResolutions,
@@ -529,8 +630,88 @@ function processBody(
   // Collect ordering blocks to process after all children are added
   const orderingBlocks = [];
   
+  // Ensure relationshipsByScope is initialized as a Map
+  // This should always be provided, but check to prevent runtime errors
+  if (!relationshipsByScope) {
+    throw new Error(`relationshipsByScope is required but was ${relationshipsByScope}`);
+  }
+  if (typeof relationshipsByScope.has !== 'function' || typeof relationshipsByScope.set !== 'function' || typeof relationshipsByScope.get !== 'function') {
+    throw new Error(`relationshipsByScope must be a Map, got ${typeof relationshipsByScope} with has: ${typeof relationshipsByScope.has}, set: ${typeof relationshipsByScope.set}, get: ${typeof relationshipsByScope.get}`);
+  }
+  
+  // Initialize relationship scope for current container if not exists
+  if (!relationshipsByScope.has(currentNodeId)) {
+    relationshipsByScope.set(currentNodeId, new Map());
+  }
+  // Inherit parent relationships
+  if (parentNodeId && relationshipsByScope.has(parentNodeId)) {
+    const parentRelationships = relationshipsByScope.get(parentNodeId);
+    const currentRelationships = relationshipsByScope.get(currentNodeId);
+    if (parentRelationships && currentRelationships) {
+      for (const [id, rel] of parentRelationships) {
+        if (!currentRelationships.has(id)) {
+          currentRelationships.set(id, rel);
+        }
+      }
+    }
+  }
+  
   for (const decl of body) {
-    if (decl.kind === 'anthology') {
+    if (decl.kind === 'relationship' && relationshipsByScope) {
+      // Track relationship declaration in current scope
+      const currentRelationships = relationshipsByScope.get(currentNodeId);
+      if (currentRelationships) {
+        if (decl.type === 'symmetric' && decl.id) {
+          currentRelationships.set(decl.id, decl);
+          // Also store in universe-level map for UI access
+          if (!relationshipDeclsByUniverse.has(universeName)) {
+            relationshipDeclsByUniverse.set(universeName, new Map());
+            graph.relationshipDecls[universeName] = {};
+          }
+          const universeDecls = relationshipDeclsByUniverse.get(universeName);
+          if (universeDecls) {
+            universeDecls.set(decl.id, {
+              type: decl.type,
+              id: decl.id,
+              describe: decl.describe,
+              label: decl.label,
+              source: decl.source,
+            });
+            graph.relationshipDecls[universeName][decl.id] = {
+              type: decl.type,
+              id: decl.id,
+              describe: decl.describe,
+              label: decl.label,
+              source: decl.source,
+            };
+          }
+        } else if (decl.type === 'paired') {
+          if (decl.leftId) currentRelationships.set(decl.leftId, decl);
+          if (decl.rightId) currentRelationships.set(decl.rightId, decl);
+          // Also store in universe-level map for UI access (store once per pair)
+          if (!relationshipDeclsByUniverse.has(universeName)) {
+            relationshipDeclsByUniverse.set(universeName, new Map());
+            graph.relationshipDecls[universeName] = {};
+          }
+          const universeDecls = relationshipDeclsByUniverse.get(universeName);
+          if (universeDecls && decl.leftId && decl.rightId) {
+            // Store under both IDs for easy lookup
+            const declModel = {
+              type: decl.type,
+              leftId: decl.leftId,
+              rightId: decl.rightId,
+              describe: decl.describe,
+              from: decl.from,
+              source: decl.source,
+            };
+            universeDecls.set(decl.leftId, declModel);
+            universeDecls.set(decl.rightId, declModel);
+            graph.relationshipDecls[universeName][decl.leftId] = declModel;
+            graph.relationshipDecls[universeName][decl.rightId] = declModel;
+          }
+        }
+      }
+    } else if (decl.kind === 'anthology') {
       const nodeId = makeNodeId(universeName, 'anthology', decl.name);
       checkDuplicateInScope(graph, scopeIndex, currentNodeId, decl.name, nodeId, 'anthology', decl.source);
       let actualParentNodeId = parentNodeId;
@@ -556,6 +737,8 @@ function processBody(
         reposMap,
         refsMap,
         entityKinds,
+        relationshipsByScope,
+        relationshipDeclsByUniverse,
         pendingReferenceDecls,
         pendingReferenceAttachments,
         pendingContainerResolutions,
@@ -590,6 +773,8 @@ function processBody(
         reposMap,
         refsMap,
         entityKinds,
+        relationshipsByScope,
+        relationshipDeclsByUniverse,
         pendingReferenceDecls,
         pendingReferenceAttachments,
         pendingContainerResolutions,
@@ -633,41 +818,89 @@ function processBody(
         reposMap,
         refsMap,
         entityKinds,
+        relationshipsByScope,
+        relationshipDeclsByUniverse,
         pendingReferenceDecls,
         pendingReferenceAttachments,
         pendingContainerResolutions,
       );
     } else if (decl.kind === 'chapter') {
-      const nodeId = makeNodeId(universeName, 'chapter', decl.name);
-      checkDuplicateInScope(graph, scopeIndex, currentNodeId, decl.name, nodeId, 'chapter', decl.source);
-      
-      // Validate: chapter must have an "in" block
-      if (!decl.parentName) {
-        graph.diagnostics.push({
-          severity: 'error',
-          message: `Chapter "${decl.name}" must belong to a book. Use "chapter ${decl.name} in <BookName> { ... }"`,
-          source: decl.source,
-        });
-        // Continue processing but mark as invalid
-      }
-      
-      const resolved = resolveNameInScope(graph, scopeIndex, decl.parentName, currentNodeId, decl.source);
-      const containerNodeId = resolved.nodeId && !resolved.ambiguous ? resolved.nodeId : null;
+      let containerNodeId = undefined;
       
-      // Validate: chapter container must be a book (if found)
-      // Note: We defer "not found" validation until after all nodes are created
-      // to allow forward references (book defined after chapter)
-      if (containerNodeId) {
-        const containerNode = graph.nodes[containerNodeId];
-        if (containerNode && containerNode.kind !== 'book') {
+      if (decl.parentName) {
+        // Explicit "in" clause - resolve the parent name
+        const resolved = resolveNameInScope(graph, scopeIndex, decl.parentName, currentNodeId, decl.source);
+        containerNodeId = resolved.nodeId && !resolved.ambiguous ? resolved.nodeId : undefined;
+        
+        // Validate: chapter container must be a book (if found)
+        // Note: We defer "not found" validation until after all nodes are created
+        // to allow forward references (book defined after chapter)
+        if (containerNodeId) {
+          const containerNode = graph.nodes[containerNodeId];
+          if (containerNode && containerNode.kind !== 'book') {
+            graph.diagnostics.push({
+              severity: 'error',
+              message: `Chapter "${decl.name}" must belong to a book, but "${decl.parentName}" is a ${containerNode.kind}`,
+              source: decl.source,
+            });
+          }
+        }
+      } else {
+        // Nested chapter - parentName is undefined, check if parentNodeId is a book
+        if (parentNodeId) {
+          const parentNode = graph.nodes[parentNodeId];
+          if (parentNode && parentNode.kind !== 'book') {
+            graph.diagnostics.push({
+              severity: 'error',
+              message: `Chapter "${decl.name}" must belong to a book, but it's nested inside a ${parentNode.kind}`,
+              source: decl.source,
+            });
+          } else if (parentNode && parentNode.kind === 'book') {
+            // Valid nested chapter - use parentNodeId as container
+            containerNodeId = parentNodeId;
+          }
+        } else {
+          // No parent at all - error
           graph.diagnostics.push({
             severity: 'error',
-            message: `Chapter "${decl.name}" must belong to a book, but "${decl.parentName}" is a ${containerNode.kind}`,
+            message: `Chapter "${decl.name}" must belong to a book. Use "chapter ${decl.name} in <BookName> { ... }"`,
             source: decl.source,
           });
         }
-      } else if (decl.parentName && pendingContainerResolutions) {
+      }
+      
+      // Build unique node ID including container path
+      let containerPath = null;
+      if (containerNodeId) {
+        // Container is resolved - build path from container node
+        containerPath = buildContainerPath(graph, containerNodeId);
+      } else if (parentNodeId) {
+        // Nested chapter - use parent (book) to build path
+        containerPath = buildContainerPath(graph, parentNodeId);
+      } else if (decl.parentName) {
+        // Forward reference - build path from current scope to include series
+        // Walk up from currentNodeId to find series, then use book name
+        // This ensures uniqueness even when the container isn't resolved yet
+        const pathParts = [];
+        const seriesNodeId = findSeriesForNode(graph, currentNodeId);
+        if (seriesNodeId) {
+          const seriesNode = graph.nodes[seriesNodeId];
+          if (seriesNode) {
+            pathParts.push('series', seriesNode.name);
+          }
+        }
+        // Always include book name - if series wasn't found, we'll still have book name
+        // which should be unique within the current processing context
+        pathParts.push('book', decl.parentName);
+        containerPath = pathParts.length > 0 ? pathParts.join(':') : null;
+      }
+      
+      const nodeId = makeNodeId(universeName, 'chapter', decl.name, containerPath);
+      checkDuplicateInScope(graph, scopeIndex, currentNodeId, decl.name, nodeId, 'chapter', decl.source);
+      
+      if (decl.parentName && !containerNodeId && pendingContainerResolutions) {
         // Container not found yet - may be a forward reference, track for later resolution
+        // Note: nodeId already includes the parent name, so it's unique even if container isn't resolved yet
         pendingContainerResolutions.push({
           nodeId,
           parentName: decl.parentName,
@@ -705,6 +938,8 @@ function processBody(
         reposMap,
         refsMap,
         entityKinds,
+        relationshipsByScope,
+        relationshipDeclsByUniverse,
         pendingReferenceDecls,
         pendingReferenceAttachments,
         pendingContainerResolutions,
@@ -727,6 +962,27 @@ function processBody(
       graph.nodes[nodeId] = node;
       graph.nodes[actualParentNodeId].children.push(nodeId);
       addNameToScope(graph, scopeIndex, currentNodeId, decl.name, nodeId);
+      
+      // Validate relationships blocks in concept body
+      const relationshipsBlocks = decl.body.filter((b) => b.kind === 'relationships');
+      for (const relBlock of relationshipsBlocks) {
+        if (relBlock.entries && relationshipsByScope) {
+          // New syntax: validate relationship IDs
+          const currentRelationships = relationshipsByScope.get(currentNodeId);
+          if (currentRelationships) {
+            for (const entry of relBlock.entries) {
+              if (!currentRelationships.has(entry.relationshipId)) {
+                graph.diagnostics.push({
+                  severity: 'error',
+                  message: `Undeclared relationship identifier "${entry.relationshipId}" in relationships block`,
+                  source: relBlock.source,
+                });
+              }
+            }
+          }
+        }
+      }
+      
       processBody(
         graph,
         universeName,
@@ -739,8 +995,10 @@ function processBody(
         reposMap,
         refsMap,
         entityKinds,
+        relationshipsByScope,
         pendingReferenceDecls,
         pendingReferenceAttachments,
+        pendingContainerResolutions,
       );
     } else if (decl.kind === 'relates') {
       // Check for duplicate relates in reverse order
@@ -825,6 +1083,8 @@ function processBody(
         source: decl.source,
         endpoints: [], // Will be populated during resolution
         unresolvedEndpoints: [decl.a, decl.b], // Will be cleared during resolution
+        spelledKind: decl.spelledKind,
+        aliases: decl.aliases && Object.keys(decl.aliases).length > 0 ? decl.aliases : undefined,
       };
 
       // Add top-level describe if present
@@ -925,32 +1185,15 @@ function processBody(
 
       graph.nodes[finalRelatesNodeId] = relatesNode;
       graph.nodes[parentNodeId].children.push(finalRelatesNodeId);
-
-      // Also create edge for backward compatibility
-      const edgeId = makeEdgeId(universeName, decl.a, decl.b, index);
-      const edge = {
-        id: edgeId,
-        kind: 'relates',
-        a: { text: decl.a },
-        b: { text: decl.b },
-        source: decl.source,
-      };
-
-      if (describeBlocks.length > 0) {
-        edge.describe = {
-          raw: describeBlocks[0].raw,
-          normalized: normalizeProseBlock(describeBlocks[0].raw),
-          source: describeBlocks[0].source,
-        };
-      }
-
-      graph.edges[edgeId] = edge;
     } else if (decl.kind === 'describe') {
       // Describe blocks are attached to their parent node
       // This is handled in createNode
     } else if (decl.kind === 'title') {
       // Title blocks are attached to their parent node
       // This is handled in createNode
+    } else if (decl.kind === 'relationships') {
+      // Relationships blocks are attached to their parent node
+      // This is handled in createNode
     } else if (decl.kind === 'references') {
       if (pendingReferenceAttachments) {
         pendingReferenceAttachments.push({
@@ -1112,18 +1355,27 @@ function processBody(
           graph.documentsByName[universeName][docName] = docModel;
         }
       }
+    } else if (decl.kind === 'relationship') {
+      // Relationship declarations are tracked in relationshipsByScope but don't create nodes
+      // They're just declarations that can be referenced in relationships blocks
     } else {
       // UnknownBlock - attach to current node (the node whose body contains this block)
-      const currentNode = graph.nodes[currentNodeId];
-      if (!currentNode.unknownBlocks) {
-        currentNode.unknownBlocks = [];
+      // Only process if it's actually an UnknownBlock (has keyword property, not kind)
+      // Blocks with 'kind' property are known block types that should be handled above
+      if (decl.keyword && !decl.kind) {
+        const currentNode = graph.nodes[currentNodeId];
+        if (!currentNode.unknownBlocks) {
+          currentNode.unknownBlocks = [];
+        }
+        currentNode.unknownBlocks.push({
+          keyword: decl.keyword,
+          raw: decl.raw,
+          normalized: normalizeProseBlock(decl.raw),
+          source: decl.source,
+        });
       }
-      currentNode.unknownBlocks.push({
-        keyword: decl.keyword,
-        raw: decl.raw,
-        normalized: normalizeProseBlock(decl.raw),
-        source: decl.source,
-      });
+      // If it has a 'kind' property, it's a known block type that should have been handled above
+      // Skip it silently (it may have been handled elsewhere, e.g., in createNode)
     }
   }
 
@@ -1170,6 +1422,8 @@ function createNode(nodeId, kind, name, parentNodeId, decl, containerNodeId) {
     parent: parentNodeId,
     children: [],
     source: decl.source,
+    spelledKind: decl.spelledKind,
+    aliases: decl.aliases && Object.keys(decl.aliases).length > 0 ? decl.aliases : undefined,
   };
 
   // Always set container for book/chapter nodes (may be undefined if not resolved)
@@ -1200,6 +1454,34 @@ function createNode(nodeId, kind, name, parentNodeId, decl, containerNodeId) {
     }
   }
 
+  // Extract relationships block if present
+  const relationshipsBlock = decl.body?.find((b) => b.kind === 'relationships');
+  if (relationshipsBlock) {
+    if (relationshipsBlock.entries) {
+      // New syntax: relationship ID + targets
+      node.relationships = {
+        entries: relationshipsBlock.entries.map((entry) => ({
+          relationshipId: entry.relationshipId,
+          targets: entry.targets.map((target) => ({
+            id: target.id,
+            metadata: target.metadata ? {
+              raw: target.metadata.raw,
+              normalized: normalizeProseBlock(target.metadata.raw),
+              source: target.metadata.source,
+            } : undefined,
+          })),
+        })),
+        source: relationshipsBlock.source,
+      };
+    } else if (relationshipsBlock.values) {
+      // String literals syntax (for relates blocks)
+      node.relationships = {
+        values: relationshipsBlock.values,
+        source: relationshipsBlock.source,
+      };
+    }
+  }
+
   // Note: UnknownBlocks are handled in processBody and attached to the parent node
   // They are not extracted here to avoid duplication
 
@@ -1267,60 +1549,7 @@ function checkDuplicateRelates(graph, universeName, a, b, source) {
  * @param {Map<string, Map<string, string[]>>} scopeIndex - Scope index
  */
 function resolveEdges(graph, scopeIndex) {
-  // Build a set of relates node names to avoid duplicate warnings
-  // (edges are created for backward compatibility alongside relates nodes)
-  const relatesNodeNames = new Set();
-  for (const nodeId in graph.nodes) {
-    const node = graph.nodes[nodeId];
-    if (node.kind === 'relates') {
-      relatesNodeNames.add(node.name);
-    }
-  }
-
-  // Resolve edges (for backward compatibility)
-  for (const edgeId in graph.edges) {
-    const edge = graph.edges[edgeId];
-    const universeName = edgeId.split(':')[0];
-    const universeNodeId = `${universeName}:universe:${universeName}`;
-
-    // Check if this edge corresponds to a relates node
-    // If so, skip warnings here (they'll be generated during relates node resolution)
-    const edgeName = `${edge.a.text} and ${edge.b.text}`;
-    const reverseEdgeName = `${edge.b.text} and ${edge.a.text}`;
-    const hasRelatesNode = relatesNodeNames.has(edgeName) || relatesNodeNames.has(reverseEdgeName);
-
-    // Resolve endpoint A - start from universe scope
-    const resolvedA = resolveRelatesEndpoint(graph, scopeIndex, edge.a.text, universeNodeId, edge.source);
-    if (resolvedA.nodeId && !resolvedA.ambiguous) {
-      edge.a.target = resolvedA.nodeId;
-    } else if (!hasRelatesNode) {
-      // Only warn if there's no corresponding relates node (legacy edge-only format)
-      if (!resolvedA.ambiguous) {
-        graph.diagnostics.push({
-          severity: 'warning',
-          message: `Unresolved relates endpoint "${edge.a.text}" in universe "${universeName}"`,
-          source: edge.source,
-        });
-      }
-    }
-
-    // Resolve endpoint B - start from universe scope
-    const resolvedB = resolveRelatesEndpoint(graph, scopeIndex, edge.b.text, universeNodeId, edge.source);
-    if (resolvedB.nodeId && !resolvedB.ambiguous) {
-      edge.b.target = resolvedB.nodeId;
-    } else if (!hasRelatesNode) {
-      // Only warn if there's no corresponding relates node (legacy edge-only format)
-      if (!resolvedB.ambiguous) {
-        graph.diagnostics.push({
-          severity: 'warning',
-          message: `Unresolved relates endpoint "${edge.b.text}" in universe "${universeName}"`,
-          source: edge.source,
-        });
-      }
-    }
-  }
-
-  // Resolve relates nodes
+  // Resolve relates node endpoints
   for (const nodeId in graph.nodes) {
     const node = graph.nodes[nodeId];
     if (node.kind === 'relates' && node.unresolvedEndpoints) {
@@ -1433,6 +1662,162 @@ function resolveContainers(graph, scopeIndex, pending) {
   }
 }
 
+/**
+ * Extracts asserted edges from both relationships {} blocks and relates nodes
+ * @param {UniverseGraph} graph - The graph
+ * @param {Map<string, Map<string, string[]>>} scopeIndex - Scope index
+ * @returns {import('./ir.js').EdgeAssertedModel[]}
+ */
+function extractAssertedEdges(graph, scopeIndex) {
+  /** @type {import('./ir.js').EdgeAssertedModel[]} */
+  const assertedEdges = [];
+
+  // Extract from relationships {} blocks (new-style adjacency lists)
+  for (const nodeId in graph.nodes) {
+    const node = graph.nodes[nodeId];
+    if (!node.relationships || !node.relationships.entries) continue;
+
+    // Resolve each target and create asserted edge
+    for (const entry of node.relationships.entries) {
+      for (const target of entry.targets) {
+        // Resolve target ID using scope resolution
+        const resolved = resolveNameInScope(
+          graph,
+          scopeIndex,
+          target.id,
+          nodeId,
+          node.relationships.source,
+        );
+        const targetNodeId = resolved.nodeId && !resolved.ambiguous ? resolved.nodeId : null;
+        if (!targetNodeId) continue;
+
+        assertedEdges.push({
+          from: nodeId,
+          via: entry.relationshipId,
+          to: targetNodeId,
+          meta: target.metadata,
+          source: node.relationships.source,
+        });
+      }
+    }
+  }
+
+  // Extract from relates nodes (bidirectional relationships)
+  // Note: Relates are bidirectional, but we create only ONE edge entry
+  // The UI should traverse edges bidirectionally to show the relationship from both perspectives
+  //
+  // Metadata behavior: edge.meta contains metadata from endpointA's perspective (from block at endpointA).
+  // When viewing endpointB, the UI should look up endpointB-specific metadata from the relates node's
+  // from[endpointB] block. This allows different descriptions for the same relationship from each endpoint's view.
+  for (const nodeId in graph.nodes) {
+    const node = graph.nodes[nodeId];
+    if (node.kind !== 'relates' || !node.endpoints || node.endpoints.length !== 2) continue;
+
+    const [endpointA, endpointB] = node.endpoints;
+
+    // Use the relationship label from the relates node if available
+    const viaLabel = node.relationships?.values?.[0] || 'related to';
+
+    // Create a single bidirectional edge (A -> B)
+    // The UI should show this relationship when viewing either endpoint
+    // Metadata is from endpointA's perspective; UI will look up endpointB-specific metadata when needed
+    assertedEdges.push({
+      from: endpointA,
+      via: viaLabel, // Note: relates don't use relationship declarations, they use string labels
+      to: endpointB,
+      meta: node.from?.[endpointA]?.describe, // Metadata from endpointA's perspective
+      source: node.source,
+      bidirectional: true, // Mark as bidirectional so UI can traverse both directions
+    });
+  }
+
+  return assertedEdges;
+}
+
+/**
+ * Normalizes edges by adding inverse edges for paired/symmetric relationships
+ * @param {import('./ir.js').EdgeAssertedModel[]} assertedEdges - Asserted edges
+ * @param {Map<string, Map<string, import('./ast.js').RelationshipDecl>>} relationshipDecls - Relationship declarations by universe
+ * @param {string} universeName - Universe name
+ * @returns {import('./ir.js').NormalizedEdgeModel[]}
+ */
+function normalizeEdges(assertedEdges, relationshipDecls, universeName) {
+  /** @type {import('./ir.js').NormalizedEdgeModel[]} */
+  const normalizedEdges = [];
+  const relDeclsMap = relationshipDecls.get(universeName);
+  const relDecls = relDeclsMap ? Object.fromEntries(relDeclsMap) : {};
+  const seenEdges = new Set(); // Track edges to avoid duplicates
+
+  for (const asserted of assertedEdges) {
+    const edgeKey = `${asserted.from}:${asserted.via}:${asserted.to}`;
+
+    // Skip if we've already added this exact edge (can happen with relates bidirectional edges)
+    if (seenEdges.has(edgeKey)) continue;
+    seenEdges.add(edgeKey);
+
+    // Get relationship declaration if this is a declared relationship
+    // Note: relates edges use string labels, not relationship IDs, so they won't have a relDecl
+    const relDecl = relDecls[asserted.via];
+
+    // Add asserted edge
+    normalizedEdges.push({
+      from: asserted.from,
+      via: asserted.via,
+      to: asserted.to,
+      asserted: true,
+      sourceRefs: [asserted.source],
+      meta: asserted.meta,
+      bidirectional: asserted.bidirectional || false, // Preserve bidirectional flag for relates edges
+    });
+
+    // Add inverse edge if applicable (only for declared relationships, not relates)
+    // Relates are already bidirectional, so both directions are in assertedEdges
+    if (relDecl) {
+      if (relDecl.type === 'paired') {
+        // Determine inverse side
+        const inverseVia =
+          asserted.via === relDecl.leftId ? relDecl.rightId : relDecl.leftId;
+
+        if (inverseVia) {
+          const inverseKey = `${asserted.to}:${inverseVia}:${asserted.from}`;
+          // Only add inverse if not already present as an asserted edge
+          if (!seenEdges.has(inverseKey)) {
+            normalizedEdges.push({
+              from: asserted.to,
+              via: inverseVia,
+              to: asserted.from,
+              asserted: false,
+              sourceRefs: [asserted.source], // Points back to asserted edge
+              meta: asserted.meta, // Copy metadata
+            });
+            seenEdges.add(inverseKey);
+          }
+        }
+      } else if (relDecl.type === 'symmetric') {
+        // Symmetric: add reverse edge with same relationship ID
+        const reverseKey = `${asserted.to}:${asserted.via}:${asserted.from}`;
+        // Only add reverse if not already present as an asserted edge
+        if (!seenEdges.has(reverseKey)) {
+          normalizedEdges.push({
+            from: asserted.to,
+            via: asserted.via,
+            to: asserted.from,
+            asserted: false,
+            sourceRefs: [asserted.source],
+            meta: asserted.meta,
+          });
+          seenEdges.add(reverseKey);
+        }
+      }
+    }
+    // Note: If no relDecl found, it's likely a relates edge (string label, not declared relationship)
+    // Relates edges are bidirectional - the UI should traverse them bidirectionally
+    // by checking both from/to fields, so we only create one edge entry
+  }
+
+  return normalizedEdges;
+}
+
 /**
  * @param {string | undefined} raw
  * @returns {string | undefined}
@@ -1761,10 +2146,47 @@ function deriveReferenceName(decl) {
  * @param {string} name
  * @returns {string}
  */
-function makeNodeId(universeName, kind, name) {
+function makeNodeId(universeName, kind, name, containerPath = null) {
+  if (containerPath) {
+    return `${universeName}:${kind}:${containerPath}:${name}`;
+  }
   return `${universeName}:${kind}:${name}`;
 }
 
+/**
+ * Builds a container path string from a node's parent chain
+ * @param {UniverseGraph} graph
+ * @param {string} containerNodeId - The container node ID
+ * @returns {string | null} - Container path like "series:Alchemy:book:Materials" or null if no container
+ */
+function buildContainerPath(graph, containerNodeId) {
+  if (!containerNodeId) return null;
+  
+  const containerNode = graph.nodes[containerNodeId];
+  // If container node doesn't exist yet (e.g., forward reference), return null
+  // The caller should handle this case appropriately
+  if (!containerNode) return null;
+  
+  const pathParts = [];
+  let current = containerNode;
+  
+  // Walk up the parent chain, collecting series and book names
+  while (current) {
+    if (current.kind === 'series' || current.kind === 'book') {
+      pathParts.unshift(current.kind, current.name);
+    }
+    if (current.parent) {
+      current = graph.nodes[current.parent];
+      // Safety check: if parent node doesn't exist, stop walking
+      if (!current) break;
+    } else {
+      break;
+    }
+  }
+  
+  return pathParts.length > 0 ? pathParts.join(':') : null;
+}
+
 /**
  * Creates a relates node ID (deterministic, endpoints in source order)
  * @param {string} universeName