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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprig-and-prose/sprig-universe",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "type": "module",
   "description": "Minimal universe parser for sprig",
   "main": "src/index.js",

package/src/ast.js

@@ -113,25 +113,31 @@
 /**
  * @typedef {Object} UniverseDecl
  * @property {string} kind - Always 'universe'
+ * @property {string} spelledKind - Kind token as written (may be alias)
  * @property {string} name - Universe name
- * @property {Array<AnthologyDecl | SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | DescribeBlock | TitleBlock | ReferencesBlock | OrderingBlock | RepositoryDecl | ReferenceDecl | NamedDocumentBlock | UnknownBlock>} body - Body declarations
+ * @property {Record<string, string>} [aliases] - Alias mappings declared in this scope
+ * @property {Array<AnthologyDecl | SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | RelationshipDecl | DescribeBlock | TitleBlock | ReferencesBlock | OrderingBlock | RepositoryDecl | ReferenceDecl | NamedDocumentBlock | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
 
 /**
  * @typedef {Object} AnthologyDecl
  * @property {string} kind - Always 'anthology'
+ * @property {string} spelledKind - Kind token as written (may be alias)
  * @property {string} name - Anthology name
  * @property {string} [parentName] - Optional parent universe name (from "in UniverseName")
- * @property {Array<SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | DescribeBlock | TitleBlock | ReferencesBlock | OrderingBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
+ * @property {Record<string, string>} [aliases] - Alias mappings declared in this scope
+ * @property {Array<SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | RelationshipDecl | DescribeBlock | TitleBlock | ReferencesBlock | OrderingBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
 
 /**
  * @typedef {Object} SeriesDecl
  * @property {string} kind - Always 'series'
+ * @property {string} spelledKind - Kind token as written (may be alias)
  * @property {string} name - Series name
  * @property {string} [parentName] - Optional parent anthology name (from "in AnthologyName")
+ * @property {Record<string, string>} [aliases] - Alias mappings declared in this scope
  * @property {Array<BookDecl | ChapterDecl | DescribeBlock | TitleBlock | ReferencesBlock | OrderingBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
@@ -139,8 +145,10 @@
 /**
  * @typedef {Object} BookDecl
  * @property {string} kind - Always 'book'
+ * @property {string} spelledKind - Kind token as written (may be alias)
  * @property {string} name - Book name
  * @property {string} [parentName] - Optional parent name (from "in ParentName")
+ * @property {Record<string, string>} [aliases] - Alias mappings declared in this scope
  * @property {Array<ChapterDecl | DescribeBlock | TitleBlock | ReferencesBlock | OrderingBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
@@ -148,8 +156,10 @@
 /**
  * @typedef {Object} ChapterDecl
  * @property {string} kind - Always 'chapter'
+ * @property {string} spelledKind - Kind token as written (may be alias)
  * @property {string} name - Chapter name
  * @property {string} parentName - Parent name (from "in ParentName")
+ * @property {Record<string, string>} [aliases] - Alias mappings declared in this scope
  * @property {Array<DescribeBlock | ReferencesBlock | OrderingBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
@@ -157,16 +167,31 @@
 /**
  * @typedef {Object} ConceptDecl
  * @property {string} kind - Always 'concept'
+ * @property {string} spelledKind - Kind token as written (may be alias)
  * @property {string} name - Concept name
  * @property {string} [parentName] - Optional parent name (from "in ParentName")
+ * @property {Record<string, string>} [aliases] - Alias mappings declared in this scope
  * @property {Array<DescribeBlock | ReferencesBlock | OrderingBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
 
+/**
+ * @typedef {Object} RelationshipTarget
+ * @property {string} id - Target identifier
+ * @property {DescribeBlock} [metadata] - Optional metadata block (describe) attached to this target
+ */
+
+/**
+ * @typedef {Object} RelationshipEntry
+ * @property {string} relationshipId - Relationship identifier being used
+ * @property {RelationshipTarget[]} targets - Array of target identifiers with optional metadata
+ */
+
 /**
  * @typedef {Object} RelationshipsBlock
  * @property {string} kind - Always 'relationships'
- * @property {string[]} values - Array of string literal values
+ * @property {RelationshipEntry[]} entries - Array of relationship entries (new syntax)
+ * @property {string[]} [values] - Array of string literal values (legacy syntax for relates blocks)
  * @property {SourceSpan} source - Source span
  */
 
@@ -178,11 +203,33 @@
  * @property {SourceSpan} source - Source span
  */
 
+/**
+ * @typedef {Object} RelationshipFromSide
+ * @property {string} [label] - Optional label string
+ * @property {DescribeBlock} [describe] - Optional describe block
+ */
+
+/**
+ * @typedef {Object} RelationshipDecl
+ * @property {string} kind - Always 'relationship'
+ * @property {string} spelledKind - Kind token as written (may be alias)
+ * @property {'symmetric' | 'paired'} type - Relationship type
+ * @property {string} [id] - Relationship identifier (for symmetric)
+ * @property {string} [leftId] - Left side identifier (for paired)
+ * @property {string} [rightId] - Right side identifier (for paired)
+ * @property {DescribeBlock} [describe] - Optional pair-level describe block
+ * @property {string} [label] - Optional label (for symmetric)
+ * @property {Record<string, RelationshipFromSide>} [from] - Per-side metadata (for paired)
+ * @property {SourceSpan} source - Source span
+ */
+
 /**
  * @typedef {Object} RelatesDecl
  * @property {string} kind - Always 'relates'
+ * @property {string} spelledKind - Kind token as written (may be alias)
  * @property {string} a - First endpoint text
  * @property {string} b - Second endpoint text
+ * @property {Record<string, string>} [aliases] - Alias mappings declared in this scope
  * @property {Array<DescribeBlock | TitleBlock | FromBlock | RelationshipsBlock | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
@@ -248,7 +295,7 @@
  */
 
 /**
- * @typedef {UniverseDecl | AnthologyDecl | SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | DescribeBlock | NoteBlock | TitleBlock | FromBlock | RelationshipsBlock | ReferencesBlock | ReferenceDecl | DocumentationBlock | DocumentBlock | NamedDocumentBlock | RepositoryDecl | UnknownBlock | SceneDecl | UsingBlock | ActorDecl | TypeBlock | IdentityBlock | SourceBlock | TransformsBlock | TransformBlock} ASTNode
+ * @typedef {UniverseDecl | AnthologyDecl | SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | RelationshipDecl | DescribeBlock | NoteBlock | TitleBlock | FromBlock | RelationshipsBlock | ReferencesBlock | ReferenceDecl | DocumentationBlock | DocumentBlock | NamedDocumentBlock | RepositoryDecl | UnknownBlock | SceneDecl | UsingBlock | ActorDecl | TypeBlock | IdentityBlock | SourceBlock | TransformsBlock | TransformBlock} ASTNode
  */
 
 /**

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
@@ -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,34 @@ 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);
+
+  // Preserve existing edges object format for relates (for code that still uses it)
+  graph.edgesByRelates = graph.edges;
+
+  // 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;
 }
 
@@ -350,7 +395,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];
@@ -506,6 +551,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 +569,8 @@ function processBody(
   reposMap,
   refsMap,
   entityKinds,
+  relationshipsByScope,
+  relationshipDeclsByUniverse,
   pendingReferenceDecls,
   pendingReferenceAttachments,
   pendingContainerResolutions,
@@ -529,8 +578,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 +685,8 @@ function processBody(
         reposMap,
         refsMap,
         entityKinds,
+        relationshipsByScope,
+        relationshipDeclsByUniverse,
         pendingReferenceDecls,
         pendingReferenceAttachments,
         pendingContainerResolutions,
@@ -590,6 +721,8 @@ function processBody(
         reposMap,
         refsMap,
         entityKinds,
+        relationshipsByScope,
+        relationshipDeclsByUniverse,
         pendingReferenceDecls,
         pendingReferenceAttachments,
         pendingContainerResolutions,
@@ -633,6 +766,8 @@ function processBody(
         reposMap,
         refsMap,
         entityKinds,
+        relationshipsByScope,
+        relationshipDeclsByUniverse,
         pendingReferenceDecls,
         pendingReferenceAttachments,
         pendingContainerResolutions,
@@ -705,6 +840,8 @@ function processBody(
         reposMap,
         refsMap,
         entityKinds,
+        relationshipsByScope,
+        relationshipDeclsByUniverse,
         pendingReferenceDecls,
         pendingReferenceAttachments,
         pendingContainerResolutions,
@@ -727,6 +864,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 +897,10 @@ function processBody(
         reposMap,
         refsMap,
         entityKinds,
+        relationshipsByScope,
         pendingReferenceDecls,
         pendingReferenceAttachments,
+        pendingContainerResolutions,
       );
     } else if (decl.kind === 'relates') {
       // Check for duplicate relates in reverse order
@@ -825,6 +985,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
@@ -951,6 +1113,9 @@ function processBody(
     } 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 +1277,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 +1344,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 +1376,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
 
@@ -1277,7 +1481,7 @@ function resolveEdges(graph, scopeIndex) {
     }
   }
 
-  // Resolve edges (for backward compatibility)
+  // Resolve edges (relates edges in object format)
   for (const edgeId in graph.edges) {
     const edge = graph.edges[edgeId];
     const universeName = edgeId.split(':')[0];
@@ -1433,6 +1637,161 @@ 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)
+  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;
+
+    // Relates are bidirectional - extract both directions as asserted edges
+    // Use the relationship label from the relates node if available
+    const viaLabel = node.relationships?.values?.[0] || 'related to';
+
+    // Create edge A -> B
+    assertedEdges.push({
+      from: endpointA,
+      via: viaLabel, // Note: relates don't use relationship declarations, they use string labels
+      to: endpointB,
+      meta: node.from?.[endpointA]?.describe,
+      source: node.source,
+    });
+
+    // Create edge B -> A (relates are bidirectional)
+    assertedEdges.push({
+      from: endpointB,
+      via: viaLabel,
+      to: endpointA,
+      meta: node.from?.[endpointB]?.describe,
+      source: node.source,
+    });
+  }
+
+  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,
+    });
+
+    // 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 already bidirectional in assertedEdges, so no inverse needed
+  }
+
+  return normalizedEdges;
+}
+
 /**
  * @param {string | undefined} raw
  * @returns {string | undefined}