@sprig-and-prose/sprig-universe 0.1.1 → 0.3.0

package/src/graph.js

@@ -27,9 +27,7 @@ import { normalizeProseBlock } from './util/text.js';
  * @typedef {import('./ast.js').FromBlock} FromBlock
  * @typedef {import('./ast.js').RelationshipsBlock} RelationshipsBlock
  * @typedef {import('./ast.js').ReferencesBlock} ReferencesBlock
- * @typedef {import('./ast.js').ReferenceBlock} ReferenceBlock
- * @typedef {import('./ast.js').NamedReferenceBlock} NamedReferenceBlock
- * @typedef {import('./ast.js').UsingInReferencesBlock} UsingInReferencesBlock
+ * @typedef {import('./ast.js').ReferenceDecl} ReferenceDecl
  * @typedef {import('./ast.js').DocumentationBlock} DocumentationBlock
  * @typedef {import('./ast.js').DocumentBlock} DocumentBlock
  * @typedef {import('./ast.js').NamedDocumentBlock} NamedDocumentBlock
@@ -38,6 +36,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}
  */
@@ -48,19 +50,30 @@ export function buildGraph(fileASTs) {
     nodes: {},
     edges: {},
     diagnostics: [],
-    referencesByName: {},
     documentsByName: {},
+    repositories: {},
+    references: {},
   };
 
-  // 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 }>
+  // Track named documents per universe for duplicate detection
   const namedDocumentsByUniverse = new Map(); // universeName -> Map<name, { source }>
   
-  // Track repositories per universe
-  const repositoriesByUniverse = new Map(); // universeName -> Map<name, RepositoryDecl>
+  // 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 entity kinds for duplicate detection (references/repositories)
+  const entityKinds = new Map(); // id -> kind
+
+  // Pending resolutions
+  /** @type {Array<{ refId: string, decl: ReferenceDecl, universeName: string, scopeNodeId: string }>} */
+  const pendingReferenceDecls = [];
+  /** @type {Array<{ nodeId: string, items: Array<{ name: string, source: SourceSpan }>, universeName: string }>} */
+  const pendingReferenceAttachments = [];
 
   // First pass: collect all universe names with their file locations for validation
   const universeNameToFiles = new Map(); // universeName -> Set<file>
@@ -102,17 +115,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());
-        graph.referencesByName[universeName] = {};
-      }
       if (!namedDocumentsByUniverse.has(universeName)) {
         namedDocumentsByUniverse.set(universeName, new Map());
         graph.documentsByName[universeName] = {};
@@ -120,6 +122,9 @@ export function buildGraph(fileASTs) {
       if (!repositoriesByUniverse.has(universeName)) {
         repositoriesByUniverse.set(universeName, new Map());
       }
+      if (!referencesByUniverse.has(universeName)) {
+        referencesByUniverse.set(universeName, new Map());
+      }
 
       // Check if universe node already exists (from a previous file)
       const existingUniverseNode = graph.nodes[universeNodeId];
@@ -175,12 +180,15 @@ export function buildGraph(fileASTs) {
           universeName,
           universeNodeId,
           universeDecl.body,
-          nameMap,
+          scopeIndex,
           fileAST.file,
           universeNodeId,
-          namedReferencesByUniverse.get(universeName),
           namedDocumentsByUniverse.get(universeName),
           repositoriesByUniverse.get(universeName),
+          referencesByUniverse.get(universeName),
+          entityKinds,
+          pendingReferenceDecls,
+          pendingReferenceAttachments,
         );
       } else {
         // First time seeing this universe - create node and process body
@@ -192,7 +200,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(
@@ -200,88 +209,377 @@ export function buildGraph(fileASTs) {
           universeName,
           universeNodeId,
           universeDecl.body,
-          nameMap,
+          scopeIndex,
           fileAST.file,
           universeNodeId,
-          namedReferencesByUniverse.get(universeName),
           namedDocumentsByUniverse.get(universeName),
           repositoriesByUniverse.get(universeName),
+          referencesByUniverse.get(universeName),
+          entityKinds,
+          pendingReferenceDecls,
+          pendingReferenceAttachments,
         );
       }
     }
   }
 
-  // Extract repositories from all universes and convert to config format
-  graph.repositories = {};
-  for (const [universeName, reposMap] of repositoriesByUniverse.entries()) {
-    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'
-      let kindValue = String(repoDecl.repositoryKind);
-      if (kindValue.startsWith('@') && kindValue.includes('/')) {
-        const parts = kindValue.split('/');
-        kindValue = parts[parts.length - 1];
+  // Attach unscoped top-level declarations to the single universe if present
+  if (universeNameToFiles.size === 1) {
+    const [universeName] = universeNameToFiles.keys();
+    const universeModel = graph.universes[universeName];
+    const universeNodeId = universeModel?.root;
+    if (universeNodeId) {
+      for (const fileAST of fileASTs) {
+        if (!fileAST.topLevelDecls || fileAST.topLevelDecls.length === 0) {
+          continue;
+        }
+        for (const decl of fileAST.topLevelDecls) {
+          if (decl.parentName) {
+            const resolved = resolveNameInScope(
+              graph,
+              scopeIndex,
+              decl.parentName,
+              universeNodeId,
+              decl.source,
+            );
+            if (!resolved.nodeId && !resolved.ambiguous) {
+              graph.diagnostics.push({
+                severity: 'error',
+                message: `Top-level ${decl.kind} "${decl.name}" references unknown container "${decl.parentName}"`,
+                source: diagnosticSource(decl.source),
+              });
+              continue;
+            }
+          }
+          processBody(
+            graph,
+            universeName,
+            universeNodeId,
+            [decl],
+            scopeIndex,
+            fileAST.file,
+            universeNodeId,
+            namedDocumentsByUniverse.get(universeName),
+            repositoriesByUniverse.get(universeName),
+            referencesByUniverse.get(universeName),
+            entityKinds,
+            pendingReferenceDecls,
+            pendingReferenceAttachments,
+          );
+        }
       }
-      
-      graph.repositories[repoName] = {
-        kind: kindValue,
-        options: repoDecl.options,
-      };
     }
   }
 
+  // Resolve reference declarations and attach references after all names are indexed
+  resolveReferenceDecls(
+    graph,
+    pendingReferenceDecls,
+    scopeIndex,
+  );
+  resolveReferenceAttachments(
+    graph,
+    pendingReferenceAttachments,
+    scopeIndex,
+  );
+
   // 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: [] };
+}
+
+/**
+ * Resolve relates endpoints with a universe-wide fallback.
+ * @param {UniverseGraph} graph
+ * @param {Map<string, Map<string, string[]>>} scopeIndex
+ * @param {string} name
+ * @param {string} startScopeNodeId
+ * @param {SourceSpan} [source]
+ * @returns {{ nodeId: string | null, ambiguous: boolean, ambiguousNodes: string[] }}
+ */
+function resolveRelatesEndpoint(graph, scopeIndex, name, startScopeNodeId, source) {
+  const resolved = resolveNameInScope(graph, scopeIndex, name, startScopeNodeId, source);
+  if (resolved.nodeId || resolved.ambiguous) {
+    return resolved;
+  }
+
+  const universeName = startScopeNodeId.split(':')[0];
+  const matches = [];
+  for (const nodeId in graph.nodes) {
+    if (!nodeId.startsWith(`${universeName}:`)) {
+      continue;
+    }
+    const node = graph.nodes[nodeId];
+    if (node && node.name === name) {
+      matches.push(nodeId);
+    }
+  }
+
+  if (matches.length === 1) {
+    return { nodeId: matches[0], ambiguous: false, ambiguousNodes: [] };
+  }
+
+  if (matches.length > 1) {
+    if (source) {
+      graph.diagnostics.push({
+        severity: 'error',
+        message: `Ambiguous relates endpoint "${name}" in universe "${universeName}": found ${matches.length} matches`,
+        source,
+      });
+    }
+    return { nodeId: null, ambiguous: true, ambiguousNodes: matches };
+  }
+
+  return resolved;
+}
+
 /**
  * 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 {Array<SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | DescribeBlock | ReferencesBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | NamedDocumentBlock | UnknownBlock>} body
+ * @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)
+ * @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 {Array} [pendingReferenceDecls] - Reference declarations to resolve after indexing
+ * @param {Array} [pendingReferenceAttachments] - Reference attachments to resolve after indexing
  */
-function processBody(graph, universeName, parentNodeId, body, nameMap, file, currentNodeId, namedRefsMap, namedDocsMap, reposMap) {
+function processBody(
+  graph,
+  universeName,
+  parentNodeId,
+  body,
+  scopeIndex,
+  file,
+  currentNodeId,
+  namedDocsMap,
+  reposMap,
+  refsMap,
+  entityKinds,
+  pendingReferenceDecls,
+  pendingReferenceAttachments,
+) {
   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);
-      const node = createNode(nodeId, 'anthology', decl.name, parentNodeId, decl);
+      checkDuplicateInScope(graph, scopeIndex, currentNodeId, decl.name, nodeId, 'anthology', decl.source);
+      let actualParentNodeId = parentNodeId;
+      if (decl.parentName) {
+        const resolved = resolveNameInScope(graph, scopeIndex, decl.parentName, currentNodeId, decl.source);
+        if (resolved.nodeId && !resolved.ambiguous) {
+          actualParentNodeId = resolved.nodeId;
+        }
+      }
+      const node = createNode(nodeId, 'anthology', decl.name, actualParentNodeId, 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);
+      graph.nodes[actualParentNodeId].children.push(nodeId);
+      addNameToScope(graph, scopeIndex, currentNodeId, decl.name, nodeId);
+      processBody(
+        graph,
+        universeName,
+        nodeId,
+        decl.body,
+        scopeIndex,
+        file,
+        nodeId,
+        namedDocsMap,
+        reposMap,
+        refsMap,
+        entityKinds,
+        pendingReferenceDecls,
+        pendingReferenceAttachments,
+      );
     } 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,
+        namedDocsMap,
+        reposMap,
+        refsMap,
+        entityKinds,
+        pendingReferenceDecls,
+        pendingReferenceAttachments,
+      );
     } 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,
@@ -297,12 +595,27 @@ 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,
+        namedDocsMap,
+        reposMap,
+        refsMap,
+        entityKinds,
+        pendingReferenceDecls,
+        pendingReferenceAttachments,
+      );
     } 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,
@@ -318,18 +631,32 @@ 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,
+        namedDocsMap,
+        reposMap,
+        refsMap,
+        entityKinds,
+        pendingReferenceDecls,
+        pendingReferenceAttachments,
+      );
     } 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)
       }
@@ -337,8 +664,22 @@ 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,
+        namedDocsMap,
+        reposMap,
+        refsMap,
+        entityKinds,
+        pendingReferenceDecls,
+        pendingReferenceAttachments,
+      );
     } else if (decl.kind === 'relates') {
       // Check for duplicate relates in reverse order
       checkDuplicateRelates(graph, universeName, decl.a, decl.b, decl.source);
@@ -520,51 +861,12 @@ function processBody(graph, universeName, parentNodeId, body, nameMap, file, cur
       // Title blocks are attached to their parent node
       // This is handled in createNode
     } else if (decl.kind === 'references') {
-      // ReferencesBlock - attach to current node
-      const currentNode = graph.nodes[currentNodeId];
-      if (!currentNode.references) {
-        currentNode.references = [];
-      }
-      // Serialize references block - handle both inline references and using blocks
-      for (const item of decl.references) {
-        if (item.kind === 'reference') {
-          // Inline reference block - convert as before
-          currentNode.references.push({
-            repository: item.repository,
-            paths: item.paths,
-            kind: item.referenceKind,
-            describe: item.describe
-              ? {
-                  raw: item.describe.raw,
-                  normalized: normalizeProseBlock(item.describe.raw),
-                  source: item.describe.source,
-                }
-              : undefined,
-            source: item.source,
-          });
-        } else if (item.kind === 'using-in-references') {
-          // Using block - resolve each name against named references registry
-          for (const name of item.names) {
-            const namedRef = graph.referencesByName[universeName]?.[name];
-            if (namedRef) {
-              // Resolved: expand to reference object
-              currentNode.references.push({
-                repository: namedRef.repository,
-                paths: namedRef.paths,
-                kind: namedRef.kind,
-                describe: namedRef.describe,
-                source: namedRef.source, // Use the named reference's source, not the using block's
-              });
-            } else {
-              // Not resolved: emit error diagnostic
-              graph.diagnostics.push({
-                severity: 'error',
-                message: `Unknown reference '${name}' used in references block`,
-                source: item.source,
-              });
-            }
-          }
-        }
+      if (pendingReferenceAttachments) {
+        pendingReferenceAttachments.push({
+          nodeId: currentNodeId,
+          items: decl.items,
+          universeName,
+        });
       }
     } else if (decl.kind === 'documentation') {
       // DocumentationBlock - attach to current node
@@ -588,35 +890,75 @@ function processBody(graph, universeName, parentNodeId, body, nameMap, file, cur
           source: doc.source,
         });
       }
-    } else if (decl.kind === 'named-reference') {
-      // NamedReferenceBlock - store in universe-level registry
-      // Only process at universe scope (when namedRefsMap is provided)
-      if (namedRefsMap && parentNodeId === currentNodeId) {
-        const refName = decl.name;
-        
-        // Check for duplicate name
-        if (namedRefsMap.has(refName)) {
-          const firstOccurrence = namedRefsMap.get(refName);
-          graph.diagnostics.push({
-            severity: 'error',
-            message: `Duplicate named reference "${refName}" in universe "${universeName}". First declared at ${firstOccurrence.source.file}:${firstOccurrence.source.start.line}:${firstOccurrence.source.start.col}`,
-            source: decl.source,
-          });
-          graph.diagnostics.push({
-            severity: 'error',
-            message: `First declaration of named reference "${refName}" was here.`,
-            source: firstOccurrence.source,
+    } else if (decl.kind === 'reference') {
+      if (refsMap && entityKinds && pendingReferenceDecls) {
+        const baseName = decl.name || deriveReferenceName(decl);
+        const uniqueName = decl.name
+          ? baseName
+          : pickUniqueName(scopeIndex, currentNodeId, baseName);
+        const qualifiedName = makeQualifiedName(graph, currentNodeId, uniqueName);
+        const refId = makeEntityId(universeName, 'reference', qualifiedName);
+        if (decl.name) {
+          checkDuplicateInScope(graph, scopeIndex, currentNodeId, decl.name, refId, 'reference', decl.source, entityKinds);
+        }
+
+        if (!refsMap.has(refId)) {
+          refsMap.set(refId, decl);
+          entityKinds.set(refId, 'reference');
+          addNameToScope(graph, scopeIndex, currentNodeId, uniqueName, refId);
+          if (!graph.references[refId]) {
+            graph.references[refId] = {
+              id: refId,
+              name: uniqueName,
+              urls: [],
+              source: decl.source,
+            };
+          }
+          pendingReferenceDecls.push({
+            refId,
+            decl,
+            universeName,
+            scopeNodeId: currentNodeId,
           });
-        } else {
-          // Store first occurrence
-          namedRefsMap.set(refName, { source: decl.source });
-          
-          // Convert to model and store in registry
-          const refModel = {
-            name: refName,
-            repository: decl.repository,
-            paths: decl.paths,
-            kind: decl.referenceKind,
+
+          if (pendingReferenceAttachments && currentNodeId !== makeNodeId(universeName, 'universe', universeName)) {
+            pendingReferenceAttachments.push({
+              nodeId: currentNodeId,
+              items: [
+                {
+                  name: uniqueName,
+                  source: decl.source,
+                },
+              ],
+              universeName,
+            });
+          }
+        }
+      }
+    } else if (decl.kind === 'repository') {
+      // RepositoryDecl - store in universe-level registry
+      if (reposMap && entityKinds) {
+        const scopeNodeId = resolveContainerScope(graph, scopeIndex, currentNodeId, decl.parentName, decl.source);
+        const qualifiedName = makeQualifiedName(graph, scopeNodeId, decl.name);
+        const repoId = makeEntityId(universeName, 'repository', qualifiedName);
+        checkDuplicateInScope(graph, scopeIndex, scopeNodeId, decl.name, repoId, 'repository', decl.source, entityKinds);
+
+        if (!reposMap.has(repoId)) {
+          reposMap.set(repoId, decl);
+          entityKinds.set(repoId, 'repository');
+          addNameToScope(graph, scopeIndex, scopeNodeId, decl.name, repoId);
+          if (!decl.url) {
+            graph.diagnostics.push({
+              severity: 'error',
+              message: `Repository "${decl.name}" is missing url { '...' }`,
+              source: decl.source,
+            });
+          }
+          graph.repositories[repoId] = {
+            id: repoId,
+            name: decl.name,
+            url: decl.url || '',
+            title: normalizeTitleValue(decl.title?.raw),
             describe: decl.describe
               ? {
                   raw: decl.describe.raw,
@@ -624,34 +966,15 @@ function processBody(graph, universeName, parentNodeId, body, nameMap, file, cur
                   source: decl.describe.source,
                 }
               : undefined,
+            note: decl.note
+              ? {
+                  raw: decl.note.raw,
+                  normalized: normalizeProseBlock(decl.note.raw),
+                  source: decl.note.source,
+                }
+              : undefined,
             source: decl.source,
           };
-          
-          graph.referencesByName[universeName][refName] = refModel;
-        }
-      }
-    } else if (decl.kind === 'repository') {
-      // RepositoryDecl - store in universe-level registry
-      // Only process at universe scope (when reposMap is provided)
-      if (reposMap && parentNodeId === currentNodeId) {
-        const repoName = decl.name;
-        
-        // Check for duplicate name
-        if (reposMap.has(repoName)) {
-          const firstOccurrence = reposMap.get(repoName);
-          graph.diagnostics.push({
-            severity: 'error',
-            message: `Duplicate repository "${repoName}" in universe "${universeName}". First declared at ${firstOccurrence.source.file}:${firstOccurrence.source.start.line}:${firstOccurrence.source.start.col}`,
-            source: decl.source,
-          });
-          graph.diagnostics.push({
-            severity: 'error',
-            message: `First declaration of repository "${repoName}" was here.`,
-            source: firstOccurrence.source,
-          });
-        } else {
-          // Store repository declaration
-          reposMap.set(repoName, decl);
         }
       }
     } else if (decl.kind === 'named-document') {
@@ -718,7 +1041,7 @@ function processBody(graph, universeName, parentNodeId, body, nameMap, file, cur
  * @param {string} name
  * @param {string | undefined} parentNodeId
  * @param {UniverseDecl | AnthologyDecl | SeriesDecl | BookDecl | ChapterDecl} decl
- * @param {string | undefined} containerNodeId
+ * @param {string | undefined} [containerNodeId]
  * @returns {NodeModel}
  */
 function createNode(nodeId, kind, name, parentNodeId, decl, containerNodeId) {
@@ -766,26 +1089,37 @@ 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
+ * @param {Map<string, string>} [entityKinds]
  */
-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, entityKinds) {
+  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 || entityKinds?.get(firstNodeId) || '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,
+      });
+    }
   }
 }
 
@@ -812,9 +1146,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();
@@ -829,34 +1163,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 = 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
-      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 = 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}"`,
@@ -871,18 +1207,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 = resolveRelatesEndpoint(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}"`,
@@ -890,31 +1229,345 @@ function resolveEdges(graph, nameToNodeId) {
             });
           }
         }
+      }
 
-        node.endpoints = resolvedEndpoints;
-        if (unresolved.length > 0) {
-          node.unresolvedEndpoints = unresolved;
+      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 resolved = resolveRelatesEndpoint(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;
+      }
+    }
+  }
+}
+
+/**
+ * @param {string | undefined} raw
+ * @returns {string | undefined}
+ */
+function normalizeTitleValue(raw) {
+  if (!raw) return undefined;
+  const trimmed = raw.trim();
+  if (!trimmed) return undefined;
+  const unquoted = trimmed.replace(/^['"]|['"]$/g, '');
+  return unquoted.trim() || undefined;
+}
+
+/**
+ * @param {UniverseGraph} graph
+ * @param {Array<{refId: string, decl: ReferenceDecl, universeName: string, scopeNodeId: string}>} pending
+ * @param {Map<string, Map<string, string[]>>} scopeIndex
+ */
+function resolveReferenceDecls(graph, pending, scopeIndex) {
+  /** @type {Map<string, { count: number, source: SourceSpan | undefined }>} */
+  const unknownRepoCounts = new Map();
+  for (const item of pending) {
+    const { refId, decl, scopeNodeId } = item;
+    const model = graph.references[refId] || { id: refId, name: decl.name, urls: [], source: decl.source };
+    const displayName = model.name || decl.name || 'unnamed reference';
+    let urls = [];
+    let repositoryRef = undefined;
+
+    if (decl.url && decl.repositoryName) {
+      graph.diagnostics.push({
+        severity: 'error',
+        message: `Reference "${displayName}" cannot include both url { ... } and in <Repository>`,
+        source: diagnosticSource(decl.source),
+      });
+    }
+
+    if (decl.url) {
+      urls = [decl.url];
+    } else if (decl.repositoryName) {
+      const resolved = resolveNameInScope(graph, scopeIndex, decl.repositoryName, scopeNodeId, decl.source);
+      if (resolved.nodeId && !resolved.ambiguous) {
+        const repo = graph.repositories[resolved.nodeId];
+        if (!repo) {
+          graph.diagnostics.push({
+            severity: 'error',
+            message: `Reference "${displayName}" uses "${decl.repositoryName}" which is not a repository`,
+            source: diagnosticSource(decl.source),
+          });
+        } else if (!repo.url) {
+          graph.diagnostics.push({
+            severity: 'error',
+            message: `Repository "${repo.name}" is missing url { '...' }`,
+            source: decl.source,
+          });
         } else {
-          delete node.unresolvedEndpoints;
+          repositoryRef = repo.id;
+          if (decl.paths && decl.paths.length > 0) {
+            urls = decl.paths.map((path) => joinRepositoryUrl(repo.url, path));
+          } else if (decl.paths && decl.paths.length === 0) {
+          graph.diagnostics.push({
+              severity: 'error',
+              message: `Reference "${displayName}" has an empty paths block`,
+            source: diagnosticSource(decl.source),
+            });
+          } else {
+            urls = [repo.url];
+          }
+        }
+      } else if (!resolved.ambiguous) {
+        const entry = unknownRepoCounts.get(decl.repositoryName) || {
+          count: 0,
+          source: decl.source,
+        };
+        entry.count += 1;
+        if (!entry.source && decl.source) {
+          entry.source = decl.source;
+        }
+        unknownRepoCounts.set(decl.repositoryName, entry);
+      }
+    } else {
+      graph.diagnostics.push({
+        severity: 'error',
+        message: `Reference "${displayName}" must have url { ... } or in <Repository>`,
+        source: diagnosticSource(decl.source),
+      });
+    }
+
+    model.name = decl.name || model.name || displayName;
+    model.kind = decl.referenceKind || undefined;
+    model.title = normalizeTitleValue(decl.title?.raw);
+    model.describe = decl.describe
+      ? {
+          raw: decl.describe.raw,
+          normalized: normalizeProseBlock(decl.describe.raw),
+          source: decl.describe.source,
+        }
+      : undefined;
+    model.note = decl.note
+      ? {
+          raw: decl.note.raw,
+          normalized: normalizeProseBlock(decl.note.raw),
+          source: decl.note.source,
         }
+      : undefined;
+    model.urls = urls;
+    model.repositoryRef = repositoryRef;
+    model.paths = decl.paths && decl.paths.length > 0 ? decl.paths : undefined;
+    model.source = decl.source;
+    graph.references[refId] = model;
+  }
 
-        // 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];
-            }
+  for (const [repoName, info] of unknownRepoCounts.entries()) {
+    const countText = info.count > 1 ? ` (${info.count} occurrences)` : '';
+    graph.diagnostics.push({
+      severity: 'error',
+      message: `Unknown repository "${repoName}" used by references${countText}.`,
+      source: diagnosticSource(info.source),
+    });
+  }
+}
+
+/**
+ * @param {UniverseGraph} graph
+ * @param {Array<{nodeId: string, items: Array<{ name: string, source: SourceSpan }>, universeName: string}>} pending
+ * @param {Map<string, Map<string, string[]>>} scopeIndex
+ */
+function resolveReferenceAttachments(graph, pending, scopeIndex) {
+  /** @type {Map<string, { count: number, source: SourceSpan | undefined }>} */
+  const unknownReferenceCounts = new Map();
+
+  for (const item of pending) {
+    const node = graph.nodes[item.nodeId];
+    if (!node) {
+      continue;
+    }
+    if (!node.references) {
+      node.references = [];
+    }
+
+    for (const entry of item.items) {
+      const name = entry.name;
+      const resolved = resolveNameInScope(graph, scopeIndex, name, item.nodeId, entry.source);
+      if (resolved.nodeId && !resolved.ambiguous) {
+        if (graph.references[resolved.nodeId]) {
+          node.references.push(resolved.nodeId);
+        } else {
+          const existing = unknownReferenceCounts.get(name) || { count: 0, source: entry.source };
+          existing.count += 1;
+          if (!existing.source && entry.source) {
+            existing.source = entry.source;
           }
-          node.from = resolvedFrom;
+          unknownReferenceCounts.set(name, existing);
+        }
+      } else if (!resolved.ambiguous) {
+        const existing = unknownReferenceCounts.get(name) || { count: 0, source: entry.source };
+        existing.count += 1;
+        if (!existing.source && entry.source) {
+          existing.source = entry.source;
         }
+        unknownReferenceCounts.set(name, existing);
+      }
+    }
+  }
+
+  for (const [name, info] of unknownReferenceCounts.entries()) {
+    const countText = info.count > 1 ? ` (${info.count} occurrences)` : '';
+    graph.diagnostics.push({
+      severity: 'error',
+      message: `Unknown reference "${name}" in references list${countText}. References must use reference names, not paths.`,
+      source: diagnosticSource(info.source),
+    });
+  }
+}
+
+/**
+ * @param {SourceSpan | undefined} source
+ * @returns {SourceSpan | { file: string, line?: number, col?: number, start?: any, end?: any } | undefined}
+ */
+function diagnosticSource(source) {
+  if (!source) return undefined;
+  return {
+    file: source.file,
+    line: source.start?.line,
+    col: source.start?.col,
+    start: source.start,
+    end: source.end,
+  };
+}
+
+/**
+ * @param {string} base
+ * @param {string} path
+ * @returns {string}
+ */
+function joinRepositoryUrl(base, path) {
+  if (base.endsWith('/') && path.startsWith('/')) {
+    return base + path.slice(1);
+  }
+  if (!base.endsWith('/') && !path.startsWith('/')) {
+    return `${base}/${path}`;
+  }
+  return base + path;
+}
+
+/**
+ * @param {UniverseGraph} graph
+ * @param {string} containerNodeId
+ * @param {string} name
+ * @returns {string}
+ */
+function makeQualifiedName(graph, containerNodeId, name) {
+  const path = [];
+  let current = containerNodeId;
+  const visited = new Set();
+  while (current && !visited.has(current)) {
+    visited.add(current);
+    const node = graph.nodes[current];
+    if (!node) break;
+    if (node.kind !== 'universe') {
+      path.push(node.name);
+    }
+    current = node.parent;
+  }
+  path.reverse();
+  path.push(name);
+  return path.join('.');
+}
+
+/**
+ * @param {string} universeName
+ * @param {string} kind
+ * @param {string} qualifiedName
+ * @returns {string}
+ */
+function makeEntityId(universeName, kind, qualifiedName) {
+  return `${universeName}:${kind}:${qualifiedName}`;
+}
+
+/**
+ * @param {UniverseGraph} graph
+ * @param {Map<string, Map<string, string[]>>} scopeIndex
+ * @param {string} currentNodeId
+ * @param {string | undefined} parentName
+ * @param {SourceSpan} source
+ * @returns {string}
+ */
+function resolveContainerScope(graph, scopeIndex, currentNodeId, parentName, source) {
+  if (!parentName) {
+    return currentNodeId;
+  }
+  const resolved = resolveNameInScope(graph, scopeIndex, parentName, currentNodeId, source);
+  if (resolved.nodeId && !resolved.ambiguous) {
+    return resolved.nodeId;
+  }
+  return currentNodeId;
+}
+
+/**
+ * @param {Map<string, Map<string, string[]>>} scopeIndex
+ * @param {string} scopeNodeId
+ * @param {string} baseName
+ * @returns {string}
+ */
+function pickUniqueName(scopeIndex, scopeNodeId, baseName) {
+  const scopeMap = scopeIndex.get(scopeNodeId);
+  if (!scopeMap || !scopeMap.has(baseName)) {
+    return baseName;
+  }
+  let suffix = 2;
+  let candidate = `${baseName}-${suffix}`;
+  while (scopeMap.has(candidate)) {
+    suffix += 1;
+    candidate = `${baseName}-${suffix}`;
+  }
+  return candidate;
+}
+
+/**
+ * @param {ReferenceDecl} decl
+ * @returns {string}
+ */
+function deriveReferenceName(decl) {
+  const title = normalizeTitleValue(decl.title?.raw);
+  if (title) {
+    return title;
+  }
+  if (decl.paths && decl.paths.length > 0) {
+    const rawPath = decl.paths[0];
+    const trimmed = rawPath.replace(/\/+$/, '');
+    const parts = trimmed.split('/').filter(Boolean);
+    if (parts.length > 0) {
+      const lastPart = parts[parts.length - 1];
+      const withoutExt = lastPart.replace(/\.[^/.]+$/, '');
+      return withoutExt.replace(/\./g, '-');
+    }
+  }
+  if (decl.url) {
+    try {
+      const parsed = new URL(decl.url);
+      const segments = parsed.pathname.split('/').filter(Boolean);
+      if (segments.length > 0) {
+        const lastSegment = segments[segments.length - 1];
+        const withoutExt = lastSegment.replace(/\.[^/.]+$/, '');
+        return withoutExt.replace(/\./g, '-');
+      }
+      if (parsed.hostname) {
+        return parsed.hostname.replace(/\./g, '-');
       }
+    } catch {
+      // Ignore malformed URLs here; validation handles required fields
     }
   }
+  return 'reference';
 }
 
 /**