@sprig-and-prose/sprig-universe 0.1.0 → 0.2.0

package/package.json

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

package/src/graph.js

@@ -38,6 +38,10 @@ import { normalizeProseBlock } from './util/text.js';
 
 /**
  * Builds a UniverseGraph from parsed AST files
+ * 
+ * Note: There is only ever one universe per manifest. All files must declare
+ * the same universe name, and they are merged into a single universe.
+ * 
  * @param {FileAST[]} fileASTs - Array of parsed file ASTs
  * @returns {UniverseGraph}
  */
@@ -52,8 +56,9 @@ export function buildGraph(fileASTs) {
     documentsByName: {},
   };
 
-  // Track node names within each universe for duplicate detection
-  const nameToNodeId = new Map(); // universeName -> Map<name, firstNodeId>
+  // Track node names within each scope (container) for scoped resolution
+  // Map<containerNodeId, Map<name, nodeId[]>> - allows multiple nodes with same name in different scopes
+  const scopeIndex = new Map(); // containerNodeId -> Map<name, nodeId[]>
   
   // Track named references and documents per universe for duplicate detection
   const namedReferencesByUniverse = new Map(); // universeName -> Map<name, { source }>
@@ -102,12 +107,6 @@ export function buildGraph(fileASTs) {
         };
       }
 
-      // Initialize name map for this universe (only once per universe)
-      if (!nameToNodeId.has(universeName)) {
-        nameToNodeId.set(universeName, new Map());
-      }
-      const nameMap = nameToNodeId.get(universeName);
-      
       // Initialize tracking maps for named references and documents (only once per universe)
       if (!namedReferencesByUniverse.has(universeName)) {
         namedReferencesByUniverse.set(universeName, new Map());
@@ -142,6 +141,13 @@ export function buildGraph(fileASTs) {
             message: `First describe block for universe "${universeName}" was declared here.`,
             source: existingDescribe.source,
           });
+        } else if (!existingDescribe && newDescribeBlock) {
+          // Add describe block if it doesn't exist yet
+          existingUniverseNode.describe = {
+            raw: newDescribeBlock.raw,
+            normalized: normalizeProseBlock(newDescribeBlock.raw),
+            source: newDescribeBlock.source,
+          };
         }
 
         // Check for conflicting title blocks
@@ -168,7 +174,7 @@ export function buildGraph(fileASTs) {
           universeName,
           universeNodeId,
           universeDecl.body,
-          nameMap,
+          scopeIndex,
           fileAST.file,
           universeNodeId,
           namedReferencesByUniverse.get(universeName),
@@ -185,7 +191,8 @@ export function buildGraph(fileASTs) {
           universeDecl,
         );
         graph.nodes[universeNodeId] = universeNode;
-        nameMap.set(universeName, universeNodeId);
+        // Add universe name to its own scope
+        addNameToScope(graph, scopeIndex, universeNodeId, universeName, universeNodeId);
 
         // Process universe body (universeNodeId is both parent and current node for UnknownBlocks)
         processBody(
@@ -193,7 +200,7 @@ export function buildGraph(fileASTs) {
           universeName,
           universeNodeId,
           universeDecl.body,
-          nameMap,
+          scopeIndex,
           fileAST.file,
           universeNodeId,
           namedReferencesByUniverse.get(universeName),
@@ -204,9 +211,10 @@ export function buildGraph(fileASTs) {
     }
   }
 
-  // Extract repositories from all universes and convert to config format
+  // Extract repositories and convert to config format
+  // Note: There's only one universe per manifest, so we iterate over the single entry
   graph.repositories = {};
-  for (const [universeName, reposMap] of repositoriesByUniverse.entries()) {
+  for (const reposMap of repositoriesByUniverse.values()) {
     for (const [repoName, repoDecl] of reposMap.entries()) {
       // Convert repository kind from package name to directory name
       // '@sprig-and-prose/sprig-repository-github' -> 'sprig-repository-github'
@@ -224,57 +232,205 @@ export function buildGraph(fileASTs) {
   }
 
   // Resolve edge endpoints
-  resolveEdges(graph, nameToNodeId);
+  resolveEdges(graph, scopeIndex);
 
   return graph;
 }
 
+/**
+ * Adds a name to a scope index and all ancestor scopes
+ * This allows names to be resolved from parent containers
+ * @param {UniverseGraph} graph - The graph
+ * @param {Map<string, Map<string, string[]>>} scopeIndex - Scope index: containerNodeId -> Map<name, nodeId[]>
+ * @param {string} scopeNodeId - Container node ID (scope)
+ * @param {string} name - Name to add
+ * @param {string} nodeId - Node ID to associate with the name
+ */
+function addNameToScope(graph, scopeIndex, scopeNodeId, name, nodeId) {
+  // Add to current scope and all ancestor scopes
+  let currentScope = scopeNodeId;
+  const visitedScopes = new Set();
+  
+  while (currentScope && !visitedScopes.has(currentScope)) {
+    visitedScopes.add(currentScope);
+    
+    if (!scopeIndex.has(currentScope)) {
+      scopeIndex.set(currentScope, new Map());
+    }
+    const scopeMap = scopeIndex.get(currentScope);
+    if (!scopeMap.has(name)) {
+      scopeMap.set(name, []);
+    }
+    scopeMap.get(name).push(nodeId);
+    
+    // Move to parent scope
+    const node = graph.nodes[currentScope];
+    if (node && node.parent) {
+      currentScope = node.parent;
+    } else {
+      break;
+    }
+  }
+}
+
+/**
+ * Resolves a name by walking the scope chain (current container -> parent -> ... -> universe)
+ * Returns the first matching node ID found, or null if not found
+ * Also checks for ambiguity (multiple matches at the same scope level)
+ * @param {UniverseGraph} graph - The graph
+ * @param {Map<string, Map<string, string[]>>} scopeIndex - Scope index
+ * @param {string} name - Name to resolve
+ * @param {string} startScopeNodeId - Starting scope (container node ID)
+ * @param {SourceSpan} [source] - Optional source span for error reporting
+ * @returns {{ nodeId: string | null, ambiguous: boolean, ambiguousNodes: string[] }}
+ */
+function resolveNameInScope(graph, scopeIndex, name, startScopeNodeId, source) {
+  // Handle qualified names (dot notation)
+  if (name.includes('.')) {
+    const parts = name.split('.');
+    // Start from universe and resolve each part
+    const universeName = startScopeNodeId.split(':')[0];
+    const universeNodeId = `${universeName}:universe:${universeName}`;
+    let currentScope = universeNodeId;
+    
+    for (const part of parts) {
+      const scopeMap = scopeIndex.get(currentScope);
+      if (!scopeMap || !scopeMap.has(part)) {
+        return { nodeId: null, ambiguous: false, ambiguousNodes: [] };
+      }
+      const candidates = scopeMap.get(part);
+      if (candidates.length === 0) {
+        return { nodeId: null, ambiguous: false, ambiguousNodes: [] };
+      }
+      if (candidates.length > 1) {
+        // Ambiguity at this level
+        if (source) {
+          graph.diagnostics.push({
+            severity: 'error',
+            message: `Ambiguous reference "${part}" in scope "${currentScope}": found ${candidates.length} matches`,
+            source,
+          });
+        }
+        return { nodeId: null, ambiguous: true, ambiguousNodes: candidates };
+      }
+      currentScope = candidates[0];
+    }
+    return { nodeId: currentScope, ambiguous: false, ambiguousNodes: [] };
+  }
+  
+  // Unqualified name - walk scope chain
+  let currentScope = startScopeNodeId;
+  const visitedScopes = new Set();
+  
+  while (currentScope) {
+    if (visitedScopes.has(currentScope)) {
+      break; // Prevent infinite loops
+    }
+    visitedScopes.add(currentScope);
+    
+    const scopeMap = scopeIndex.get(currentScope);
+    if (scopeMap && scopeMap.has(name)) {
+      const candidates = scopeMap.get(name);
+      if (candidates.length === 0) {
+        // Continue to parent scope
+      } else if (candidates.length === 1) {
+        return { nodeId: candidates[0], ambiguous: false, ambiguousNodes: [] };
+      } else {
+        // Ambiguity at this scope level
+        if (source) {
+          const scopeNode = graph.nodes[currentScope];
+          const scopeName = scopeNode ? (scopeNode.name || currentScope) : currentScope;
+          graph.diagnostics.push({
+            severity: 'error',
+            message: `Ambiguous reference "${name}" in scope "${scopeName}": found ${candidates.length} matches`,
+            source,
+          });
+        }
+        return { nodeId: null, ambiguous: true, ambiguousNodes: candidates };
+      }
+    }
+    
+    // Move to parent scope
+    const node = graph.nodes[currentScope];
+    if (node && node.parent) {
+      currentScope = node.parent;
+    } else {
+      // Reached universe root or no parent - check universe scope one more time if we haven't already
+      const universeName = startScopeNodeId.split(':')[0];
+      const universeNodeId = `${universeName}:universe:${universeName}`;
+      if (currentScope !== universeNodeId) {
+        // Check universe scope before giving up
+        const universeScopeMap = scopeIndex.get(universeNodeId);
+        if (universeScopeMap && universeScopeMap.has(name)) {
+          const candidates = universeScopeMap.get(name);
+          if (candidates.length === 1) {
+            return { nodeId: candidates[0], ambiguous: false, ambiguousNodes: [] };
+          } else if (candidates.length > 1) {
+            if (source) {
+              graph.diagnostics.push({
+                severity: 'error',
+                message: `Ambiguous reference "${name}" in universe scope: found ${candidates.length} matches`,
+                source,
+              });
+            }
+            return { nodeId: null, ambiguous: true, ambiguousNodes: candidates };
+          }
+        }
+      }
+      break;
+    }
+  }
+  
+  return { nodeId: null, ambiguous: false, ambiguousNodes: [] };
+}
+
 /**
  * Processes a body of declarations, creating nodes and edges
  * @param {UniverseGraph} graph
  * @param {string} universeName
  * @param {string} parentNodeId - Parent node ID (for tree relationships)
    * @param {Array<SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | DescribeBlock | ReferencesBlock | DocumentationBlock | NamedReferenceBlock | NamedDocumentBlock | UnknownBlock>} body
- * @param {Map<string, string>} nameMap
+ * @param {Map<string, Map<string, string[]>>} scopeIndex - Scope index: containerNodeId -> Map<name, nodeId[]>
  * @param {string} file
  * @param {string} currentNodeId - Current node ID (for attaching UnknownBlocks)
  * @param {Map<string, { source: SourceSpan }>} [namedRefsMap] - Map for tracking named references (universe scope only)
  * @param {Map<string, { source: SourceSpan }>} [namedDocsMap] - Map for tracking named documents (universe scope only)
  * @param {Map<string, RepositoryDecl>} [reposMap] - Map for tracking repository declarations (universe scope only)
  */
-function processBody(graph, universeName, parentNodeId, body, nameMap, file, currentNodeId, namedRefsMap, namedDocsMap, reposMap) {
+function processBody(graph, universeName, parentNodeId, body, scopeIndex, file, currentNodeId, namedRefsMap, namedDocsMap, reposMap) {
   for (const decl of body) {
     if (decl.kind === 'anthology') {
       const nodeId = makeNodeId(universeName, 'anthology', decl.name);
-      checkDuplicateName(graph, universeName, decl.name, nodeId, 'anthology', nameMap, decl.source);
+      checkDuplicateInScope(graph, scopeIndex, currentNodeId, decl.name, nodeId, 'anthology', decl.source);
       const node = createNode(nodeId, 'anthology', decl.name, parentNodeId, decl);
       graph.nodes[nodeId] = node;
       graph.nodes[parentNodeId].children.push(nodeId);
-      nameMap.set(decl.name, nodeId);
-      processBody(graph, universeName, nodeId, decl.body, nameMap, file, nodeId, namedRefsMap, namedDocsMap);
+      addNameToScope(graph, scopeIndex, currentNodeId, decl.name, nodeId);
+      processBody(graph, universeName, nodeId, decl.body, scopeIndex, file, nodeId, namedRefsMap, namedDocsMap);
     } else if (decl.kind === 'series') {
       const nodeId = makeNodeId(universeName, 'series', decl.name);
-      checkDuplicateName(graph, universeName, decl.name, nodeId, 'series', nameMap, decl.source);
+      checkDuplicateInScope(graph, scopeIndex, currentNodeId, decl.name, nodeId, 'series', decl.source);
       
       // Handle optional anthology parent
       let actualParentNodeId = parentNodeId;
       if (decl.parentName) {
-        const anthologyNodeId = nameMap.get(decl.parentName);
-        if (anthologyNodeId) {
-          actualParentNodeId = anthologyNodeId;
+        const resolved = resolveNameInScope(graph, scopeIndex, decl.parentName, currentNodeId, decl.source);
+        if (resolved.nodeId && !resolved.ambiguous) {
+          actualParentNodeId = resolved.nodeId;
         }
-        // If anthology not found, fall back to parentNodeId (tolerant parsing)
+        // If parent not found, fall back to parentNodeId (tolerant parsing)
       }
       
       const node = createNode(nodeId, 'series', decl.name, actualParentNodeId, decl);
       graph.nodes[nodeId] = node;
       graph.nodes[actualParentNodeId].children.push(nodeId);
-      nameMap.set(decl.name, nodeId);
-      processBody(graph, universeName, nodeId, decl.body, nameMap, file, nodeId, namedRefsMap, namedDocsMap);
+      addNameToScope(graph, scopeIndex, currentNodeId, decl.name, nodeId);
+      processBody(graph, universeName, nodeId, decl.body, scopeIndex, file, nodeId, namedRefsMap, namedDocsMap);
     } else if (decl.kind === 'book') {
       const nodeId = makeNodeId(universeName, 'book', decl.name);
-      checkDuplicateName(graph, universeName, decl.name, nodeId, 'book', nameMap, decl.source);
-      const containerNodeId = nameMap.get(decl.parentName);
+      checkDuplicateInScope(graph, scopeIndex, currentNodeId, decl.name, nodeId, 'book', decl.source);
+      const resolved = resolveNameInScope(graph, scopeIndex, decl.parentName, currentNodeId, decl.source);
+      const containerNodeId = resolved.nodeId && !resolved.ambiguous ? resolved.nodeId : null;
       // Always set container for book nodes (even if undefined when parentName doesn't resolve)
       const node = createNode(
         nodeId,
@@ -290,12 +446,13 @@ function processBody(graph, universeName, parentNodeId, body, nameMap, file, cur
       } else {
         graph.nodes[parentNodeId].children.push(nodeId);
       }
-      nameMap.set(decl.name, nodeId);
-      processBody(graph, universeName, nodeId, decl.body, nameMap, file, nodeId, namedRefsMap, namedDocsMap);
+      addNameToScope(graph, scopeIndex, currentNodeId, decl.name, nodeId);
+      processBody(graph, universeName, nodeId, decl.body, scopeIndex, file, nodeId, namedRefsMap, namedDocsMap);
     } else if (decl.kind === 'chapter') {
       const nodeId = makeNodeId(universeName, 'chapter', decl.name);
-      checkDuplicateName(graph, universeName, decl.name, nodeId, 'chapter', nameMap, decl.source);
-      const containerNodeId = nameMap.get(decl.parentName);
+      checkDuplicateInScope(graph, scopeIndex, currentNodeId, decl.name, nodeId, 'chapter', decl.source);
+      const resolved = resolveNameInScope(graph, scopeIndex, decl.parentName, currentNodeId, decl.source);
+      const containerNodeId = resolved.nodeId && !resolved.ambiguous ? resolved.nodeId : null;
       // Always set container for chapter nodes (even if undefined when parentName doesn't resolve)
       const node = createNode(
         nodeId,
@@ -311,18 +468,18 @@ function processBody(graph, universeName, parentNodeId, body, nameMap, file, cur
       } else {
         graph.nodes[parentNodeId].children.push(nodeId);
       }
-      nameMap.set(decl.name, nodeId);
-      processBody(graph, universeName, nodeId, decl.body, nameMap, file, nodeId, namedRefsMap, namedDocsMap);
+      addNameToScope(graph, scopeIndex, currentNodeId, decl.name, nodeId);
+      processBody(graph, universeName, nodeId, decl.body, scopeIndex, file, nodeId, namedRefsMap, namedDocsMap);
     } else if (decl.kind === 'concept') {
       const nodeId = makeNodeId(universeName, 'concept', decl.name);
-      checkDuplicateName(graph, universeName, decl.name, nodeId, 'concept', nameMap, decl.source);
+      checkDuplicateInScope(graph, scopeIndex, currentNodeId, decl.name, nodeId, 'concept', decl.source);
       
       // Handle optional parent
       let actualParentNodeId = parentNodeId;
       if (decl.parentName) {
-        const parentNodeIdFromName = nameMap.get(decl.parentName);
-        if (parentNodeIdFromName) {
-          actualParentNodeId = parentNodeIdFromName;
+        const resolved = resolveNameInScope(graph, scopeIndex, decl.parentName, currentNodeId, decl.source);
+        if (resolved.nodeId && !resolved.ambiguous) {
+          actualParentNodeId = resolved.nodeId;
         }
         // If parent not found, fall back to parentNodeId (tolerant parsing)
       }
@@ -330,8 +487,8 @@ function processBody(graph, universeName, parentNodeId, body, nameMap, file, cur
       const node = createNode(nodeId, 'concept', decl.name, actualParentNodeId, decl);
       graph.nodes[nodeId] = node;
       graph.nodes[actualParentNodeId].children.push(nodeId);
-      nameMap.set(decl.name, nodeId);
-      processBody(graph, universeName, nodeId, decl.body, nameMap, file, nodeId, namedRefsMap, namedDocsMap);
+      addNameToScope(graph, scopeIndex, currentNodeId, decl.name, nodeId);
+      processBody(graph, universeName, nodeId, decl.body, scopeIndex, file, nodeId, namedRefsMap, namedDocsMap);
     } else if (decl.kind === 'relates') {
       // Check for duplicate relates in reverse order
       checkDuplicateRelates(graph, universeName, decl.a, decl.b, decl.source);
@@ -759,26 +916,36 @@ function createNode(nodeId, kind, name, parentNodeId, decl, containerNodeId) {
 }
 
 /**
- * Checks for duplicate node names and emits warning if found
+ * Checks for duplicate node names within a scope and emits error if found
  * @param {UniverseGraph} graph
- * @param {string} universeName
+ * @param {Map<string, Map<string, string[]>>} scopeIndex - Scope index
+ * @param {string} scopeNodeId - Container node ID (scope)
  * @param {string} name
  * @param {string} nodeId
  * @param {string} kind - The kind of the current node being checked
- * @param {Map<string, string>} nameMap
  * @param {SourceSpan} source
  */
-function checkDuplicateName(graph, universeName, name, nodeId, kind, nameMap, source) {
-  if (nameMap.has(name)) {
-    const firstNodeId = nameMap.get(name);
-    const firstNode = graph.nodes[firstNodeId];
-    const firstKind = firstNode?.kind || 'unknown';
-    graph.diagnostics.push({
-      severity: 'warning',
-      message: `Duplicate concept name "${name}" in universe "${universeName}": already defined as ${firstKind} (${firstNodeId}), now also defined as ${kind}`,
-      source: source, // Current duplicate's source span
-    });
-    // Note: Resolution will choose the first encountered (already in nameMap)
+function checkDuplicateInScope(graph, scopeIndex, scopeNodeId, name, nodeId, kind, source) {
+  const scopeMap = scopeIndex.get(scopeNodeId);
+  if (scopeMap && scopeMap.has(name)) {
+    const existingNodeIds = scopeMap.get(name);
+    if (existingNodeIds.length > 0) {
+      const firstNodeId = existingNodeIds[0];
+      const firstNode = graph.nodes[firstNodeId];
+      const firstKind = firstNode?.kind || 'unknown';
+      const scopeNode = graph.nodes[scopeNodeId];
+      const scopeName = scopeNode ? (scopeNode.name || scopeNodeId) : scopeNodeId;
+      graph.diagnostics.push({
+        severity: 'error',
+        message: `Duplicate name "${name}" in scope "${scopeName}": already defined as ${firstKind}, now also defined as ${kind}`,
+        source: source,
+      });
+      graph.diagnostics.push({
+        severity: 'error',
+        message: `First declaration of "${name}" was here.`,
+        source: firstNode.source,
+      });
+    }
   }
 }
 
@@ -805,9 +972,9 @@ function checkDuplicateRelates(graph, universeName, a, b, source) {
 /**
  * Resolves edge endpoint references and relates node endpoints
  * @param {UniverseGraph} graph
- * @param {Map<string, Map<string, string>>} nameToNodeId
+ * @param {Map<string, Map<string, string[]>>} scopeIndex - Scope index
  */
-function resolveEdges(graph, nameToNodeId) {
+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();
@@ -822,34 +989,36 @@ function resolveEdges(graph, nameToNodeId) {
   for (const edgeId in graph.edges) {
     const edge = graph.edges[edgeId];
     const universeName = edgeId.split(':')[0];
-    const nameMap = nameToNodeId.get(universeName);
-
-    if (nameMap) {
-      // 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
-      const targetA = nameMap.get(edge.a.text);
-      if (targetA) {
-        edge.a.target = targetA;
-      } else if (!hasRelatesNode) {
-        // Only warn if there's no corresponding relates node (legacy edge-only format)
+    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 = resolveNameInScope(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
-      const targetB = nameMap.get(edge.b.text);
-      if (targetB) {
-        edge.b.target = targetB;
-      } else if (!hasRelatesNode) {
-        // Only warn if there's no corresponding relates node (legacy edge-only format)
+    // Resolve endpoint B - start from universe scope
+    const resolvedB = resolveNameInScope(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}"`,
@@ -864,18 +1033,21 @@ function resolveEdges(graph, nameToNodeId) {
     const node = graph.nodes[nodeId];
     if (node.kind === 'relates' && node.unresolvedEndpoints) {
       const universeName = nodeId.split(':')[0];
-      const nameMap = nameToNodeId.get(universeName);
+      const universeNodeId = `${universeName}:universe:${universeName}`;
+      
+      // Determine the scope where this relates block was declared (parent of relates node)
+      const relatesScope = node.parent || universeNodeId;
 
-      if (nameMap) {
-        const resolvedEndpoints = [];
-        const unresolved = [];
+      const resolvedEndpoints = [];
+      const unresolved = [];
 
-        for (const endpointName of node.unresolvedEndpoints) {
-          const targetId = nameMap.get(endpointName);
-          if (targetId) {
-            resolvedEndpoints.push(targetId);
-          } else {
-            unresolved.push(endpointName);
+      for (const endpointName of node.unresolvedEndpoints) {
+        const resolved = resolveNameInScope(graph, scopeIndex, endpointName, relatesScope, node.source);
+        if (resolved.nodeId && !resolved.ambiguous) {
+          resolvedEndpoints.push(resolved.nodeId);
+        } else {
+          unresolved.push(endpointName);
+          if (!resolved.ambiguous) {
             graph.diagnostics.push({
               severity: 'warning',
               message: `Unresolved relates endpoint "${endpointName}" in universe "${universeName}"`,
@@ -883,28 +1055,28 @@ function resolveEdges(graph, nameToNodeId) {
             });
           }
         }
+      }
 
-        node.endpoints = resolvedEndpoints;
-        if (unresolved.length > 0) {
-          node.unresolvedEndpoints = unresolved;
-        } else {
-          delete node.unresolvedEndpoints;
-        }
+      node.endpoints = resolvedEndpoints;
+      if (unresolved.length > 0) {
+        node.unresolvedEndpoints = unresolved;
+      } else {
+        delete node.unresolvedEndpoints;
+      }
 
-        // Resolve from blocks: convert from endpoint names to node IDs
-        if (node.from) {
-          const resolvedFrom = {};
-          for (const endpointName in node.from) {
-            const targetId = nameMap.get(endpointName);
-            if (targetId) {
-              resolvedFrom[targetId] = node.from[endpointName];
-            } else {
-              // Keep unresolved from blocks keyed by name
-              resolvedFrom[endpointName] = node.from[endpointName];
-            }
+      // Resolve from blocks: convert from endpoint names to node IDs
+      if (node.from) {
+        const resolvedFrom = {};
+        for (const endpointName in node.from) {
+          const resolved = resolveNameInScope(graph, scopeIndex, endpointName, relatesScope, node.source);
+          if (resolved.nodeId && !resolved.ambiguous) {
+            resolvedFrom[resolved.nodeId] = node.from[endpointName];
+          } else {
+            // Keep unresolved from blocks keyed by name
+            resolvedFrom[endpointName] = node.from[endpointName];
           }
-          node.from = resolvedFrom;
         }
+        node.from = resolvedFrom;
       }
     }
   }

package/src/parser.js

@@ -106,6 +106,8 @@ class Parser {
   parseFile() {
     const universes = [];
     const scenes = [];
+    const topLevelDeclsByUniverse = new Map();
+    const topLevelDeclsUnscoped = [];
     const startToken = this.peek();
 
     while (!this.match('EOF')) {
@@ -113,6 +115,38 @@ class Parser {
         universes.push(this.parseUniverse());
       } else if (this.match('KEYWORD') && this.peek()?.value === 'scene') {
         scenes.push(this.parseScene());
+      } else if (this.match('KEYWORD')) {
+        const keyword = this.peek()?.value;
+        let decl = null;
+        if (keyword === 'series') {
+          decl = this.parseSeries();
+        } else if (keyword === 'book') {
+          decl = this.parseBook();
+        } else if (keyword === 'chapter') {
+          decl = this.parseChapter();
+        } else if (keyword === 'concept') {
+          decl = this.parseConcept();
+        } else if (keyword === 'anthology') {
+          decl = this.parseAnthology();
+        }
+
+        if (decl) {
+          if (decl.parentName) {
+            const universeName = decl.parentName;
+            if (!topLevelDeclsByUniverse.has(universeName)) {
+              topLevelDeclsByUniverse.set(universeName, []);
+            }
+            topLevelDeclsByUniverse.get(universeName).push(decl);
+          } else {
+            topLevelDeclsUnscoped.push(decl);
+          }
+        } else {
+          // Skip unknown top-level content (tolerant parsing)
+          const token = this.advance();
+          if (token && token.type !== 'EOF') {
+            // Could emit warning here, but for now just skip
+          }
+        }
       } else {
         // Skip unknown top-level content (tolerant parsing)
         const token = this.advance();
@@ -122,6 +156,39 @@ class Parser {
       }
     }
 
+    // Merge top-level declarations into their target universes
+    if (topLevelDeclsByUniverse.size > 0 || topLevelDeclsUnscoped.length > 0) {
+      const universesByName = new Map();
+      for (const universe of universes) {
+        universesByName.set(universe.name, universe);
+      }
+
+      for (const [universeName, decls] of topLevelDeclsByUniverse.entries()) {
+        const universe = universesByName.get(universeName);
+        if (universe) {
+          universe.body.push(...decls);
+        } else {
+          const firstDecl = decls[0];
+          const lastDecl = decls[decls.length - 1];
+          universes.push({
+            kind: 'universe',
+            name: universeName,
+            body: decls,
+            source: {
+              file: this.file,
+              start: firstDecl.source.start,
+              end: lastDecl.source.end,
+            },
+          });
+          universesByName.set(universeName, universes[universes.length - 1]);
+        }
+      }
+
+      if (topLevelDeclsUnscoped.length > 0 && universes.length === 1) {
+        universes[0].body.push(...topLevelDeclsUnscoped);
+      }
+    }
+
     return {
       file: this.file,
       universes,