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

package/src/universe/graph.js

@@ -0,0 +1,1619 @@
+/**
+ * @fileoverview Multi-pass resolver for building UniverseGraph from parsed AST
+ * Consumes NEW parser AST format (FileAST with kind:'file', decls:[...])
+ */
+
+import { normalizeProseBlock } from '../util/text.js';
+
+/**
+ * @typedef {import('../ir.js').UniverseGraph} UniverseGraph
+ * @typedef {import('../ir.js').NodeModel} NodeModel
+ * @typedef {import('../ir.js').EdgeModel} EdgeModel
+ * @typedef {import('../ir.js').UniverseModel} UniverseModel
+ * @typedef {import('../ir.js').TextBlock} TextBlock
+ * @typedef {import('../ir.js').UnknownBlock} UnknownBlock
+ * @typedef {import('../ir.js').Diagnostic} Diagnostic
+ * @typedef {import('../ir.js').FromView} FromView
+ * @typedef {import('../ir.js').EdgeAssertedModel} EdgeAssertedModel
+ * @typedef {import('../ir.js').NormalizedEdgeModel} NormalizedEdgeModel
+ * @typedef {import('../ir.js').RepositoryModel} RepositoryModel
+ * @typedef {import('../ir.js').ReferenceModel} ReferenceModel
+ * @typedef {import('../ir.js').NamedDocumentModel} NamedDocumentModel
+ * @typedef {import('../ir.js').RelationshipDeclModel} RelationshipDeclModel
+ * @typedef {import('../ir.js').SourceSpan} SourceSpan
+ */
+
+/**
+ * @typedef {string} DeclId - Declaration identifier
+ * @typedef {string} ScopeKey - Scope identifier
+ * @typedef {string} SeriesDeclId - Series declaration identifier
+ */
+
+/**
+ * @typedef {Object} NormalizedDecl
+ * @property {DeclId} id - Declaration ID
+ * @property {string} kind - Normalized kind ('universe', 'anthology', 'series', 'book', 'chapter', 'concept', 'container', 'repository', 'referenceDecl', 'relates', 'relationshipDecl')
+ * @property {string} spelledKind - Original spelled kind (may be alias)
+ * @property {string} name - Declaration name
+ * @property {string} [parentName] - Explicit parent name from 'in' clause
+ * @property {any[]} body - Body declarations/blocks
+ * @property {SourceSpan} source - Source span
+ * @property {DeclId} [syntacticParentId] - Syntactic parent from AST tree
+ * @property {Map<string, string>} [aliases] - Alias table for this scope
+ */
+
+/**
+ * @typedef {Object} DeclInfo
+ * @property {string} name - Declaration name
+ * @property {string} kindSpelled - Spelled kind
+ * @property {string} [kindResolved] - Resolved base kind
+ * @property {string} [parentRef] - Parent reference name
+ * @property {DeclId} [parentDeclId] - Resolved parent declaration ID
+ * @property {ScopeKey} scopeKey - Scope key
+ * @property {SourceSpan} span - Source span
+ */
+
+/**
+ * @typedef {Object} DeclIndex
+ * @property {Map<DeclId, DeclInfo>} declIndex - Declaration index
+ * @property {Map<ScopeKey, Map<string, DeclId>>} scopeIndex - Scope index (scope -> name -> declId)
+ * @property {Map<SeriesDeclId, Map<string, DeclId>>} seriesIndex - Series index (seriesId -> name -> declId)
+ * @property {Map<ScopeKey, Map<string, string>>} aliasTablesByScope - Alias tables (scope -> aliasName -> targetBaseKind)
+ * @property {Diagnostic[]} diagnostics - Diagnostics from indexing
+ */
+
+/**
+ * @typedef {Object} BoundDecl
+ * @property {DeclId} id - Declaration ID
+ * @property {DeclInfo} info - Declaration info with resolved kind and parent
+ * @property {NormalizedDecl} decl - Original normalized declaration
+ * @property {DeclId[]} children - Child declaration IDs
+ */
+
+/**
+ * @typedef {Object} RelationshipSchema
+ * @property {string} id - Schema identifier
+ * @property {'symmetric' | 'paired'} type - Schema type
+ * @property {string} [leftId] - Left ID for paired
+ * @property {string} [rightId] - Right ID for paired
+ * @property {any} decl - Original declaration
+ * @property {ScopeKey} scopeKey - Scope where schema is defined
+ */
+
+/**
+ * @typedef {Object} SchemaRegistry
+ * @property {Map<string, RelationshipSchema>} schemas - Schemas by ID
+ * @property {ScopeKey} scopeKey - Scope key
+ */
+
+/**
+ * Extract raw text from contentSpan using sourceText
+ * @param {{ startOffset: number, endOffset: number }} contentSpan
+ * @param {string} sourceText
+ * @returns {string}
+ */
+function extractRawText(contentSpan, sourceText) {
+  return sourceText.slice(contentSpan.startOffset, contentSpan.endOffset);
+}
+
+/**
+ * Pass 0: Normalize AST - normalize alias/aliases blocks and container declarations
+ * @param {Array<{ kind: string, decls: any[], source?: SourceSpan, sourceText?: string }>} fileASTs
+ * @returns {Array<{ normalized: NormalizedDecl[], sourceText: string, filePath: string }>}
+ */
+function normalizeAst(fileASTs) {
+  const normalized = [];
+  
+  for (const fileAST of fileASTs) {
+    if (fileAST.kind !== 'file') {
+      continue;
+    }
+    
+    const sourceText = fileAST.sourceText || '';
+    const filePath = fileAST.source?.file || '';
+    const normalizedDecls = [];
+    
+    // Track aliases per scope (will be attached to container decls)
+    const aliasStack = [new Map()]; // Root scope
+    
+    /**
+     * Normalize a declaration recursively
+     * @param {any} decl
+     * @param {Map<string, string>} currentAliases
+     * @param {DeclId} [syntacticParentId]
+     * @returns {NormalizedDecl | null}
+     */
+    function normalizeDecl(decl, currentAliases, syntacticParentId) {
+      if (!decl || !decl.kind) {
+        return null;
+      }
+      
+      // Handle alias declarations
+      if (decl.kind === 'alias') {
+        currentAliases.set(decl.name, decl.targetKind);
+        return null; // Don't create a decl for alias itself
+      }
+      
+      // Handle aliases block
+      if (decl.kind === 'aliases') {
+        for (const alias of decl.aliases || []) {
+          currentAliases.set(alias.name, alias.targetKind);
+        }
+        return null; // Don't create a decl for aliases block itself
+      }
+      
+      // Handle container declarations (including aliased ones)
+      const containerKinds = ['universe', 'anthology', 'series', 'book', 'chapter', 'concept'];
+      const passthroughBlockKinds = new Set([
+        'describe',
+        'title',
+        'note',
+        'relationships',
+        'from',
+        'references',
+        'reference',
+        'label',
+        'ordering',
+        'documentation',
+        'document',
+        'namedDocument',
+        'unknown',
+      ]);
+      if (containerKinds.includes(decl.kind) || decl.kind === 'container') {
+        const normalizedKind = decl.kind === 'container' ? 'container' : decl.kind;
+        const spelledKind = decl.spelledKind || decl.kind;
+        
+        // Create new alias map for this scope (inherits parent)
+        const scopeAliases = new Map(currentAliases);
+        
+        // Normalize body - collect aliases and normalize children
+        const normalizedBody = [];
+        for (const child of decl.body || []) {
+          if (child.kind === 'alias') {
+            scopeAliases.set(child.name, child.targetKind);
+            continue;
+          }
+          if (child.kind === 'aliases') {
+            for (const alias of (child.aliases || [])) {
+              scopeAliases.set(alias.name, alias.targetKind);
+            }
+            continue;
+          }
+          if (child.kind && passthroughBlockKinds.has(child.kind)) {
+            normalizedBody.push(child);
+            continue;
+          }
+          const normalizedChild = normalizeDecl(child, scopeAliases, undefined); // Will set parent later
+          if (normalizedChild) {
+            normalizedBody.push(normalizedChild);
+          }
+        }
+        
+        // Generate ID (temporary, will be regenerated in Pass 1)
+        const tempId = `${decl.kind}:${decl.name}`;
+        
+        return {
+          id: tempId,
+          kind: normalizedKind,
+          spelledKind,
+          name: decl.name,
+          parentName: decl.parentName,
+          body: normalizedBody,
+          source: decl.source || decl.span,
+          syntacticParentId,
+          aliases: scopeAliases.size > 0 ? scopeAliases : undefined,
+        };
+      }
+      
+      // Handle relates declarations
+      if (decl.kind === 'relates') {
+        const tempId = `relates:${decl.a}:${decl.b}`;
+        return {
+          id: tempId,
+          kind: 'relates',
+          spelledKind: decl.spelledKind || 'relates',
+          name: `${decl.a} and ${decl.b}`,
+          parentName: undefined,
+          body: decl.body || [],
+          source: decl.source || decl.span,
+          syntacticParentId,
+        };
+      }
+      
+      // Handle relationship declarations
+      if (decl.kind === 'relationshipDecl') {
+        const tempId = `relationship:${decl.ids.join(':')}`;
+        return {
+          id: tempId,
+          kind: 'relationshipDecl',
+          spelledKind: 'relationship',
+          name: decl.ids.join(' and '),
+          parentName: undefined,
+          body: decl.body || [],
+          source: decl.span,
+          syntacticParentId,
+          relationshipIds: decl.ids, // Preserve original IDs
+        };
+      }
+      
+      // Handle repository declarations
+      if (decl.kind === 'repository') {
+        const tempId = `repository:${decl.name}`;
+        return {
+          id: tempId,
+          kind: 'repository',
+          spelledKind: decl.spelledKind || 'repository',
+          name: decl.name,
+          parentName: decl.parentName,
+          body: decl.children || [],
+          source: decl.source || decl.span,
+          syntacticParentId,
+        };
+      }
+      
+      // Handle reference declarations
+      if (decl.kind === 'referenceDecl') {
+        const tempId = `reference:${decl.name}`;
+        return {
+          id: tempId,
+          kind: 'referenceDecl',
+          spelledKind: 'reference',
+          name: decl.name,
+          repositoryName: decl.repositoryName,
+          parentName: undefined,
+          body: decl.children || [],
+          source: decl.source || decl.span,
+          syntacticParentId,
+        };
+      }
+      
+      // Unknown/other - skip for now
+      return null;
+    }
+    
+    // Normalize all top-level declarations
+    for (const decl of fileAST.decls || []) {
+      const normalizedDecl = normalizeDecl(decl, aliasStack[0], undefined);
+      if (normalizedDecl) {
+        // Set syntactic parents for children
+        setSyntacticParents(normalizedDecl);
+        normalizedDecls.push(normalizedDecl);
+      }
+    }
+    
+    normalized.push({
+      normalized: normalizedDecls,
+      sourceText,
+      filePath,
+    });
+  }
+  
+  return normalized;
+}
+
+/**
+ * Set syntactic parent IDs recursively
+ * @param {NormalizedDecl} decl
+ */
+function setSyntacticParents(decl) {
+  const declId = decl.id;
+  for (const child of decl.body || []) {
+    if (child.kind && ['universe', 'anthology', 'series', 'book', 'chapter', 'concept', 'container', 'relates', 'relationshipDecl', 'repository', 'referenceDecl'].includes(child.kind)) {
+      child.syntacticParentId = declId;
+      setSyntacticParents(child);
+    }
+  }
+}
+
+/**
+ * Generate a deterministic DeclId
+ * @param {string} universeName
+ * @param {string} kind
+ * @param {string} name
+ * @param {string} [containerPath]
+ * @returns {DeclId}
+ */
+function makeDeclId(universeName, kind, name, containerPath) {
+  if (containerPath) {
+    return `${universeName}:${kind}:${containerPath}:${name}`;
+  }
+  return `${universeName}:${kind}:${name}`;
+}
+
+/**
+ * Pass 1: Index declarations - create DeclIds and build indexes
+ * @param {Array<{ normalized: NormalizedDecl[], sourceText: string, filePath: string }>} normalized
+ * @returns {{ index: DeclIndex, normalizedDecls: NormalizedDecl[] }}
+ */
+function indexDecls(normalized) {
+  const declIndex = new Map();
+  const scopeIndex = new Map();
+  const seriesIndex = new Map();
+  const aliasTablesByScope = new Map();
+  const diagnostics = [];
+  const idMap = new Map(); // old temp ID -> new proper ID
+  
+  // First pass: collect all universe names
+  const universeNames = new Set();
+  for (const file of normalized) {
+    for (const decl of file.normalized) {
+      if (decl.kind === 'universe') {
+        universeNames.add(decl.name);
+      }
+    }
+  }
+  
+  // Collect all normalized decls
+  const allNormalizedDecls = [];
+  
+  // Validate: exactly one universe
+  if (universeNames.size === 0) {
+    diagnostics.push({
+      severity: 'error',
+      message: 'No universe declaration found',
+      source: undefined,
+    });
+    return { index: { declIndex, scopeIndex, seriesIndex, aliasTablesByScope, diagnostics }, normalizedDecls: [] };
+  }
+  
+  if (universeNames.size > 1) {
+    const names = Array.from(universeNames).join(', ');
+    diagnostics.push({
+      severity: 'error',
+      message: `Multiple distinct universes found: ${names}. All files must declare the same universe name.`,
+      source: undefined,
+    });
+  }
+  
+  const universeName = Array.from(universeNames)[0];
+  
+  /**
+   * Index a declaration recursively
+   * @param {NormalizedDecl} decl
+   * @param {ScopeKey} currentScopeKey
+   * @param {SeriesDeclId | null} currentSeriesId
+   */
+  function indexDecl(decl, currentScopeKey, currentSeriesId) {
+    allNormalizedDecls.push(decl);
+    const oldId = decl.id; // Store old temp ID before we change it
+    // Generate proper DeclId
+    let declId;
+    if (decl.kind === 'universe') {
+      declId = makeDeclId(decl.name, 'universe', decl.name);
+    } else if (decl.kind === 'relates') {
+      declId = makeDeclId(universeName, 'relates', `${decl.name}`);
+    } else if (decl.kind === 'relationshipDecl') {
+      declId = makeDeclId(universeName, 'relationship', decl.name);
+    } else if (decl.kind === 'repository') {
+      declId = makeDeclId(universeName, 'repository', decl.name);
+    } else if (decl.kind === 'referenceDecl') {
+      declId = makeDeclId(universeName, 'reference', decl.name);
+    } else {
+      declId = makeDeclId(universeName, decl.kind, decl.name);
+    }
+    
+    // Update decl with proper ID and map old -> new
+    idMap.set(oldId, declId);
+    decl.id = declId;
+    
+    // Determine scope key
+    let scopeKey = currentScopeKey;
+    if (decl.kind === 'universe') {
+      scopeKey = `universe:${decl.name}`;
+    } else if (decl.kind === 'anthology' || decl.kind === 'series') {
+      scopeKey = `${decl.kind}:${decl.name}`;
+    }
+    
+    // Update series ID if this is a series
+    let seriesId = currentSeriesId;
+    if (decl.kind === 'series') {
+      seriesId = declId;
+    }
+    
+    // Store alias table for this scope
+    if (decl.aliases && decl.aliases.size > 0) {
+      aliasTablesByScope.set(scopeKey, decl.aliases);
+    }
+    
+    // Create DeclInfo
+    const info = {
+      name: decl.name,
+      kindSpelled: decl.spelledKind,
+      parentRef: decl.parentName,
+      scopeKey,
+      span: decl.source,
+    };
+    
+    // Check for duplicate names in scope
+    if (!scopeIndex.has(scopeKey)) {
+      scopeIndex.set(scopeKey, new Map());
+    }
+    const scopeMap = scopeIndex.get(scopeKey);
+    if (scopeMap.has(decl.name)) {
+      const existingId = scopeMap.get(decl.name);
+      const existingInfo = declIndex.get(existingId);
+      diagnostics.push({
+        severity: 'error',
+        message: `Duplicate name "${decl.name}" in scope "${scopeKey}": already defined as ${existingInfo?.kindSpelled || 'unknown'}, now also defined as ${decl.spelledKind}`,
+        source: decl.source,
+      });
+      diagnostics.push({
+        severity: 'error',
+        message: `First declaration of "${decl.name}" was here.`,
+        source: existingInfo?.span,
+      });
+    } else {
+      scopeMap.set(decl.name, declId);
+    }
+    
+    // Add to series index if inside a series
+    if (seriesId) {
+      if (!seriesIndex.has(seriesId)) {
+        seriesIndex.set(seriesId, new Map());
+      }
+      seriesIndex.get(seriesId).set(decl.name, declId);
+    }
+    
+    // Store in declIndex
+    declIndex.set(declId, info);
+    
+    // Index children
+    for (const child of decl.body || []) {
+      if (child.kind && ['universe', 'anthology', 'series', 'book', 'chapter', 'concept', 'container', 'relates', 'relationshipDecl', 'repository', 'referenceDecl'].includes(child.kind)) {
+        indexDecl(child, scopeKey, seriesId);
+      }
+    }
+  }
+  
+  // Index all declarations
+  // First pass: index universe and its children
+  for (const file of normalized) {
+    for (const decl of file.normalized) {
+      if (decl.kind === 'universe') {
+        indexDecl(decl, `universe:${decl.name}`, null);
+      }
+    }
+  }
+  
+  // Second pass: index top-level declarations that reference the universe
+  // These are declarations with 'in' clauses that eventually reference universe entities
+  const universeScopeKey = `universe:${universeName}`;
+  for (const file of normalized) {
+    for (const decl of file.normalized) {
+      // Skip universe (already indexed) and declarations that are children of universe
+      if (decl.kind === 'universe') continue;
+      if (decl.syntacticParentId) continue; // Already indexed as child
+      
+      // Index top-level declarations (they're in universe scope by default)
+      indexDecl(decl, universeScopeKey, null);
+    }
+  }
+  
+  // Update all syntacticParentId references to use new IDs
+  function updateSyntacticParents(decl) {
+    if (decl.syntacticParentId) {
+      const newParentId = idMap.get(decl.syntacticParentId);
+      if (newParentId) {
+        decl.syntacticParentId = newParentId;
+      } else {
+        // Parent not found - might be an error, but don't crash
+        decl.syntacticParentId = undefined;
+      }
+    }
+    // Recursively update children
+    for (const child of decl.body || []) {
+      if (child.kind && ['universe', 'anthology', 'series', 'book', 'chapter', 'concept', 'container', 'relates', 'relationshipDecl', 'repository', 'referenceDecl'].includes(child.kind)) {
+        updateSyntacticParents(child);
+      }
+    }
+  }
+  
+  for (const file of normalized) {
+    for (const decl of file.normalized) {
+      updateSyntacticParents(decl);
+    }
+  }
+  
+  return { index: { declIndex, scopeIndex, seriesIndex, aliasTablesByScope, diagnostics }, normalizedDecls: allNormalizedDecls };
+}
+
+/**
+ * Find nearest enclosing series for a declaration
+ * @param {DeclId} declId
+ * @param {Map<DeclId, DeclInfo>} declIndex
+ * @param {Map<DeclId, DeclId>} parentMap
+ * @returns {SeriesDeclId | null}
+ */
+function findNearestSeries(declId, declIndex, parentMap) {
+  let current = declId;
+  const visited = new Set();
+  
+  while (current && !visited.has(current)) {
+    visited.add(current);
+    const info = declIndex.get(current);
+    if (info && info.kindResolved === 'series') {
+      return current;
+    }
+    current = parentMap.get(current);
+  }
+  
+  return null;
+}
+
+/**
+ * Resolve unqualified name using series-scoped → global disambiguation
+ * @param {string} name
+ * @param {DeclId} currentDeclId
+ * @param {DeclIndex} index
+ * @param {Map<DeclId, DeclId>} parentMap
+ * @param {SourceSpan} [source]
+ * @returns {{ declId: DeclId | null, ambiguous: boolean }}
+ */
+function resolveUnqualified(name, currentDeclId, index, parentMap, source) {
+  const { declIndex, scopeIndex, seriesIndex } = index;
+  
+  // Find nearest enclosing series
+  const seriesId = findNearestSeries(currentDeclId, declIndex, parentMap);
+  
+  // If inside a series, check series index first
+  if (seriesId) {
+    const seriesMap = seriesIndex.get(seriesId);
+    if (seriesMap && seriesMap.has(name)) {
+      return { declId: seriesMap.get(name), ambiguous: false };
+    }
+  }
+  
+  // Search all scopes for the name
+  const matches = [];
+  for (const [scopeKey, scopeMap] of scopeIndex.entries()) {
+    if (scopeMap.has(name)) {
+      const declId = scopeMap.get(name);
+      matches.push({ scopeKey, declId });
+    }
+  }
+  
+  if (matches.length === 0) {
+    return { declId: null, ambiguous: false };
+  }
+  
+  if (matches.length === 1) {
+    // Single unique match - return it
+    return { declId: matches[0].declId, ambiguous: false };
+  }
+  
+  // Multiple matches - check if they're all the same declId (can happen if name appears in multiple scopes)
+  const uniqueDeclIds = new Set(matches.map(m => m.declId));
+  if (uniqueDeclIds.size === 1) {
+    // All matches point to the same declaration - return it
+    return { declId: matches[0].declId, ambiguous: false };
+  }
+  
+  // Multiple distinct matches - require qualified path
+  if (source) {
+    // Note: diagnostics will be added by caller
+  }
+  return { declId: null, ambiguous: true };
+}
+
+/**
+ * Resolve qualified path (e.g., "Series.Book.Chapter")
+ * @param {string[]} pathSegments
+ * @param {DeclIndex} index
+ * @param {SourceSpan} [source]
+ * @returns {{ declId: DeclId | null, error?: string }}
+ */
+function resolveQualified(pathSegments, index, source) {
+  const { scopeIndex, declIndex } = index;
+  
+  if (pathSegments.length === 0) {
+    return { declId: null, error: 'Empty qualified path' };
+  }
+  
+  // Start from universe root
+  const universeScopeKey = Array.from(scopeIndex.keys()).find(k => k.startsWith('universe:'));
+  if (!universeScopeKey) {
+    return { declId: null, error: 'No universe scope found' };
+  }
+  
+  let currentScopeKey = universeScopeKey;
+  let currentDeclId = null;
+  
+  for (let i = 0; i < pathSegments.length; i++) {
+    const segment = pathSegments[i];
+    const scopeMap = scopeIndex.get(currentScopeKey);
+    
+    if (!scopeMap || !scopeMap.has(segment)) {
+      return { declId: null, error: `Segment "${segment}" not found in scope "${currentScopeKey}"` };
+    }
+    
+    currentDeclId = scopeMap.get(segment);
+    const info = declIndex.get(currentDeclId);
+    
+    if (!info) {
+      return { declId: null, error: `Declaration "${segment}" not found in index` };
+    }
+    
+    // Update scope for next segment
+    if (info.kindResolved === 'universe' || info.kindResolved === 'anthology' || info.kindResolved === 'series') {
+      currentScopeKey = info.scopeKey;
+    } else {
+      // For non-scope containers, use their parent's scope
+      // This handles cases like book.chapter where book doesn't introduce a scope
+      currentScopeKey = info.scopeKey;
+    }
+  }
+  
+  return { declId: currentDeclId };
+}
+
+/**
+ * Pass 2: Bind parents and resolve kinds
+ * @param {DeclIndex} index
+ * @param {NormalizedDecl[]} normalizedDecls
+ * @returns {{ boundDecls: BoundDecl[], diagnostics: Diagnostic[] }}
+ */
+function bindParentsAndKinds(index, normalizedDecls) {
+  const { declIndex, scopeIndex, seriesIndex, aliasTablesByScope } = index;
+  const boundDecls = [];
+  const diagnostics = [...index.diagnostics];
+  const parentMap = new Map(); // declId -> parentDeclId
+  const declMap = new Map(); // declId -> NormalizedDecl
+  
+  // Build decl map
+  for (const decl of normalizedDecls) {
+    declMap.set(decl.id, decl);
+  }
+  
+  /**
+   * Resolve kind via alias tables
+   * @param {string} spelledKind
+   * @param {ScopeKey} scopeKey
+   * @returns {string}
+   */
+  function resolveKind(spelledKind, scopeKey) {
+    const baseKinds = ['universe', 'anthology', 'series', 'book', 'chapter', 'concept', 'relates', 'relationship', 'repository', 'reference'];
+    if (baseKinds.includes(spelledKind)) {
+      return spelledKind;
+    }
+    
+    // Walk up scope chain to find alias
+    let currentScope = scopeKey;
+    while (currentScope) {
+      const aliasTable = aliasTablesByScope.get(currentScope);
+      if (aliasTable && aliasTable.has(spelledKind)) {
+        return aliasTable.get(spelledKind);
+      }
+      
+      // Move to parent scope (extract parent from scope key)
+      if (currentScope.startsWith('series:')) {
+        // Parent would be anthology or universe - need to find it
+        break; // For now, just check current scope
+      } else if (currentScope.startsWith('anthology:')) {
+        // Parent is universe
+        const universeName = currentScope.split(':')[1];
+        currentScope = `universe:${universeName}`;
+      } else {
+        break;
+      }
+    }
+    
+    return 'unknown';
+  }
+  
+  // First pass: resolve kinds
+  for (const [declId, info] of declIndex.entries()) {
+    const resolvedKind = resolveKind(info.kindSpelled, info.scopeKey);
+    info.kindResolved = resolvedKind;
+    
+    if (resolvedKind === 'unknown' && !['relates', 'relationshipDecl', 'repository', 'referenceDecl'].includes(info.kindSpelled)) {
+      diagnostics.push({
+        severity: 'error',
+        message: `Unknown kind "${info.kindSpelled}" - not a base kind and no alias found`,
+        source: info.span,
+      });
+    }
+  }
+  
+  const universeDeclId = Array.from(declIndex.entries()).find(([, info]) => info.kindResolved === 'universe')?.[0];
+  
+  // Second pass: bind parents
+  for (const [declId, info] of declIndex.entries()) {
+    const decl = declMap.get(declId);
+    if (!decl) continue;
+    
+    let parentDeclId = null;
+    
+    // If explicit parentName via 'in', resolve it
+    if (decl.parentName) {
+      const pathSegments = decl.parentName.split('.');
+      if (pathSegments.length === 1) {
+        const resolved = resolveUnqualified(pathSegments[0], declId, index, parentMap, info.span);
+        if (resolved.declId) {
+          parentDeclId = resolved.declId;
+        } else if (resolved.ambiguous) {
+          diagnostics.push({
+            severity: 'error',
+            message: `Parent "${decl.parentName}" is ambiguous; use a qualified path like "Anthology.Book".`,
+            source: info.span,
+          });
+        } else {
+          diagnostics.push({
+            severity: 'error',
+            message: `Cannot resolve parent "${decl.parentName}": not found in any scope`,
+            source: info.span,
+          });
+        }
+      } else {
+        const resolved = resolveQualified(pathSegments, index, info.span);
+        if (resolved.declId) {
+          parentDeclId = resolved.declId;
+        } else {
+          diagnostics.push({
+            severity: 'error',
+            message: `Cannot resolve parent "${decl.parentName}": ${resolved.error || 'not found'}`,
+            source: info.span,
+          });
+        }
+      }
+    } else if (decl.syntacticParentId) {
+      // Use syntactic parent
+      parentDeclId = decl.syntacticParentId;
+    }
+    
+    // Top-level declarations default to the universe parent when no explicit parent is provided.
+    if (!parentDeclId && !decl.parentName && !decl.syntacticParentId && universeDeclId && info.kindResolved !== 'universe') {
+      parentDeclId = universeDeclId;
+    }
+    
+    info.parentDeclId = parentDeclId;
+    if (parentDeclId) {
+      parentMap.set(declId, parentDeclId);
+    }
+    
+    // Validate containment rules
+    const parentInfo = parentDeclId ? declIndex.get(parentDeclId) : null;
+    
+    // RULE A: Chapters must belong to a Book
+    if (info.kindResolved === 'chapter') {
+      if (!parentInfo || parentInfo.kindResolved !== 'book') {
+        const parentKind = parentInfo ? parentInfo.kindResolved : 'none';
+        const parentName = parentInfo ? parentInfo.name : 'none';
+        diagnostics.push({
+          severity: 'error',
+          message: `chapter ${info.name} must be defined under a book (found parent ${parentKind} ${parentName})`,
+          source: info.span,
+        });
+      }
+    }
+    
+    // RULE B: Concepts are leaf nodes (check if has children)
+    if (info.kindResolved === 'concept') {
+      const hasChildren = (decl.body || []).some(child => 
+        child.kind && ['universe', 'anthology', 'series', 'book', 'chapter', 'concept', 'container'].includes(child.kind)
+      );
+      if (hasChildren) {
+        diagnostics.push({
+          severity: 'error',
+          message: `concept ${info.name} cannot contain declarations`,
+          source: info.span,
+        });
+      }
+    }
+    
+    // Additional containment rules (relaxed - only chapters have strict requirements)
+    // Books, series, anthologies, and concepts can be under any parent
+    // The only strict rule is: chapters must be under books (already checked above)
+    
+    boundDecls.push({
+      id: declId,
+      info,
+      decl,
+      children: [],
+    });
+  }
+  
+  // Build children lists from resolved parent map, preserving source order
+  const childrenByParent = new Map();
+  for (const decl of normalizedDecls) {
+    const info = declIndex.get(decl.id);
+    if (!info || !info.parentDeclId) continue;
+    if (!childrenByParent.has(info.parentDeclId)) {
+      childrenByParent.set(info.parentDeclId, []);
+    }
+    childrenByParent.get(info.parentDeclId).push(decl.id);
+  }
+  
+  for (const bound of boundDecls) {
+    bound.children = childrenByParent.get(bound.id) || [];
+  }
+  
+  return { boundDecls, diagnostics, parentMap };
+}
+
+/**
+ * Pass 3: Compile relationship schemas
+ * @param {BoundDecl[]} boundDecls
+ * @param {DeclIndex} index
+ * @returns {{ schemas: Map<ScopeKey, SchemaRegistry>, diagnostics: Diagnostic[] }}
+ */
+function compileSchemas(boundDecls, index) {
+  const schemas = new Map();
+  const diagnostics = [];
+  
+  // Build scope key -> registry map
+  for (const bound of boundDecls) {
+    const { decl, info } = bound;
+    
+    // Handle relationship declarations
+    if (decl.kind === 'relationshipDecl') {
+      const scopeKey = info.scopeKey;
+      if (!schemas.has(scopeKey)) {
+        schemas.set(scopeKey, { schemas: new Map(), scopeKey });
+      }
+      const registry = schemas.get(scopeKey);
+      
+      // Determine type: symmetric (1 id) or paired (2 ids)
+      // Need to get the original decl to access ids
+      // For now, assume we can extract from body or store ids in normalized decl
+      // Actually, the original parser AST has ids array - we need to preserve it
+      // Let me check the structure... the normalized decl should have the original data
+      
+      // Extract relationship IDs from the normalized decl
+      const ids = decl.relationshipIds || decl.name.split(' and ');
+      
+      if (ids.length === 1) {
+        // Symmetric relationship
+        const schemaId = ids[0];
+        if (registry.schemas.has(schemaId)) {
+          diagnostics.push({
+            severity: 'error',
+            message: `Duplicate relationship schema "${schemaId}" in scope "${scopeKey}"`,
+            source: info.span,
+          });
+        } else {
+          registry.schemas.set(schemaId, {
+            id: schemaId,
+            type: 'symmetric',
+            decl,
+            scopeKey,
+          });
+        }
+      } else if (ids.length === 2) {
+        // Paired relationship
+        const leftId = ids[0];
+        const rightId = ids[1];
+        if (registry.schemas.has(leftId) || registry.schemas.has(rightId)) {
+          diagnostics.push({
+            severity: 'error',
+            message: `Duplicate relationship schema "${leftId}" or "${rightId}" in scope "${scopeKey}"`,
+            source: info.span,
+          });
+        } else {
+          const schema = {
+            id: leftId, // Store under leftId
+            type: 'paired',
+            leftId,
+            rightId,
+            decl,
+            scopeKey,
+          };
+          registry.schemas.set(leftId, schema);
+          registry.schemas.set(rightId, schema); // Also store under rightId for lookup
+        }
+      }
+    }
+    
+    // Handle relates declarations (these are schemas too, but simpler)
+    if (decl.kind === 'relates') {
+      // Relates don't need schema registry - they're handled differently
+      // But we could store them for validation
+    }
+  }
+  
+  return { schemas, diagnostics };
+}
+
+/**
+ * Extract raw text from contentSpan
+ * @param {{ startOffset: number, endOffset: number } | undefined} contentSpan
+ * @param {string} sourceText
+ * @returns {string}
+ */
+function getRawText(contentSpan, sourceText) {
+  if (!contentSpan) return '';
+  return sourceText.slice(contentSpan.startOffset, contentSpan.endOffset);
+}
+
+/**
+ * Pass 4: Build nodes
+ * @param {BoundDecl[]} boundDecls
+ * @param {Map<ScopeKey, SchemaRegistry>} schemas
+ * @param {Array<{ sourceText: string, filePath: string }>} fileData
+ * @returns {{ nodes: Map<DeclId, NodeModel>, repositories: Map<DeclId, RepositoryModel>, references: Map<DeclId, ReferenceModel>, diagnostics: Diagnostic[] }}
+ */
+function buildNodes(boundDecls, schemas, fileData) {
+  const nodes = new Map();
+  const repositories = new Map();
+  const references = new Map();
+  const diagnostics = [];
+  
+  // Build file data map
+  const fileDataMap = new Map();
+  for (const file of fileData) {
+    fileDataMap.set(file.filePath, file.sourceText);
+  }
+  
+  /**
+   * Build a text block from describe/title/note block
+   * @param {any} block
+   * @param {string} sourceText
+   * @returns {TextBlock | undefined}
+   */
+  function buildTextBlock(block, sourceText) {
+    if (!block || !block.contentSpan) return undefined;
+    const raw = getRawText(block.contentSpan, sourceText);
+    return {
+      raw,
+      normalized: normalizeProseBlock(raw),
+      source: block.span,
+    };
+  }
+  
+  for (const bound of boundDecls) {
+    const { id, info, decl } = bound;
+    const sourceText = fileDataMap.get(info.span?.file || '') || '';
+    
+    // Build container/concept nodes
+    if (['universe', 'anthology', 'series', 'book', 'chapter', 'concept', 'relates'].includes(info.kindResolved)) {
+      const node = {
+        id,
+        kind: info.kindResolved,
+        name: info.name,
+        parent: info.parentDeclId || undefined,
+        children: bound.children,
+        source: info.span,
+      };
+      
+      if (decl.spelledKind && decl.spelledKind !== info.kindResolved) {
+        node.spelledKind = decl.spelledKind;
+      }
+      
+      if (decl.aliases && decl.aliases.size > 0) {
+        node.aliases = Object.fromEntries(decl.aliases);
+      }
+      
+      // Extract describe block
+      const describeBlock = (decl.body || []).find(b => b.kind === 'describe');
+      if (describeBlock) {
+        node.describe = buildTextBlock(describeBlock, sourceText);
+      }
+      
+      // Extract title block
+      const titleBlock = (decl.body || []).find(b => b.kind === 'title');
+      if (titleBlock) {
+        const raw = getRawText(titleBlock.contentSpan, sourceText);
+        const titleValue = raw.trim();
+        if (titleValue.length > 0) {
+          node.title = titleValue;
+        }
+      }
+      
+      // Extract relationships block (for concepts)
+      const relationshipsBlock = (decl.body || []).find(b => b.kind === 'relationships');
+      if (relationshipsBlock) {
+        // Handle new entry-based syntax
+        if (relationshipsBlock.entries) {
+          node.relationships = {
+            entries: relationshipsBlock.entries.map(entry => ({
+              relationshipId: entry.relationshipId,
+              targets: entry.targets.map(target => ({
+                id: target.id,
+                metadata: target.metadata ? buildTextBlock(target.metadata, sourceText) : undefined,
+              })),
+            })),
+            source: relationshipsBlock.source,
+          };
+        } else if (relationshipsBlock.values) {
+          // Legacy string values syntax
+          node.relationships = {
+            values: relationshipsBlock.values,
+            source: relationshipsBlock.source,
+          };
+        }
+      }
+      
+      // Handle relates nodes specially
+      if (info.kindResolved === 'relates') {
+        // Extract endpoints (will be resolved in Pass 5)
+        const a = decl.name.split(' and ')[0];
+        const b = decl.name.split(' and ')[1] || '';
+        node.unresolvedEndpoints = [a, b];
+        node.endpoints = [];
+        
+        // Extract from blocks
+        const fromBlocks = (decl.body || []).filter(b => b.kind === 'from');
+        node.from = {};
+        for (const fromBlock of fromBlocks) {
+          const endpoint = fromBlock.endpoint;
+          const fromView = {
+            source: fromBlock.source,
+          };
+          
+          // Extract relationships block from from block
+          const fromRelBlock = (fromBlock.body || []).find(b => b.kind === 'relationships');
+          if (fromRelBlock && fromRelBlock.values) {
+            fromView.relationships = {
+              values: fromRelBlock.values,
+              source: fromRelBlock.source,
+            };
+          }
+          
+          // Extract describe block from from block
+          const fromDescribeBlock = (fromBlock.body || []).find(b => b.kind === 'describe');
+          if (fromDescribeBlock) {
+            fromView.describe = buildTextBlock(fromDescribeBlock, sourceText);
+          }
+          
+          // Extract unknown blocks
+          const unknownBlocks = (fromBlock.body || []).filter(b => 
+            b.kind && !['relationships', 'describe'].includes(b.kind)
+          );
+          if (unknownBlocks.length > 0) {
+            fromView.unknownBlocks = unknownBlocks.map(ub => ({
+              keyword: ub.kind || 'unknown',
+              raw: getRawText(ub.contentSpan, sourceText),
+              normalized: normalizeProseBlock(getRawText(ub.contentSpan, sourceText)),
+              source: ub.span || ub.source,
+            }));
+          }
+          
+          node.from[endpoint] = fromView;
+        }
+        
+        // Extract top-level relationships block for relates
+        if (relationshipsBlock && relationshipsBlock.values) {
+          node.relationships = {
+            values: relationshipsBlock.values,
+            source: relationshipsBlock.source,
+          };
+        }
+      }
+      
+      // Extract unknown blocks (non-container, non-standard blocks)
+      const unknownBlocks = (decl.body || []).filter(b => {
+        if (!b.kind) return false;
+        const knownKinds = ['describe', 'title', 'note', 'relationships', 'from', 'references', 'reference'];
+        return !knownKinds.includes(b.kind);
+      });
+      if (unknownBlocks.length > 0) {
+        node.unknownBlocks = unknownBlocks.map(ub => ({
+          keyword: ub.kind,
+          raw: getRawText(ub.contentSpan, sourceText),
+          normalized: normalizeProseBlock(getRawText(ub.contentSpan, sourceText)),
+          source: ub.span || ub.source,
+        }));
+      }
+      
+      // Extract references block
+      const referencesBlock = (decl.body || []).find(b => b.kind === 'references');
+      if (referencesBlock && referencesBlock.items) {
+        node.references = referencesBlock.items.map(item => {
+          // Will be resolved in Pass 5
+          return item.ref || item.name || '';
+        });
+      }
+      
+      nodes.set(id, node);
+    }
+    
+    // Build repository nodes
+    if (info.kindResolved === 'repository') {
+      const repo = {
+        id,
+        name: info.name,
+        url: '',
+        source: info.span,
+      };
+      
+      // Extract url block
+      const urlBlock = (decl.body || []).find(b => b.kind === 'url');
+      if (urlBlock && urlBlock.value) {
+        repo.url = urlBlock.value;
+      }
+      
+      // Extract title block
+      const titleBlock = (decl.body || []).find(b => b.kind === 'title');
+      if (titleBlock) {
+        const raw = getRawText(titleBlock.contentSpan, sourceText);
+        const titleValue = raw.trim().replace(/^['"]|['"]$/g, '').trim();
+        if (titleValue.length > 0) {
+          repo.title = titleValue;
+        }
+      }
+      
+      // Extract describe block
+      const describeBlock = (decl.body || []).find(b => b.kind === 'describe');
+      if (describeBlock) {
+        repo.describe = buildTextBlock(describeBlock, sourceText);
+      }
+      
+      // Extract note block
+      const noteBlock = (decl.body || []).find(b => b.kind === 'note');
+      if (noteBlock) {
+        repo.note = buildTextBlock(noteBlock, sourceText);
+      }
+      
+      repositories.set(id, repo);
+    }
+    
+    // Build reference nodes
+    if (info.kindResolved === 'reference') {
+      const ref = {
+        id,
+        name: info.name,
+        urls: [],
+        source: info.span,
+      };
+      
+      // Extract url block
+      const urlBlock = (decl.body || []).find(b => b.kind === 'url');
+      if (urlBlock && urlBlock.value) {
+        ref.urls = [urlBlock.value];
+      }
+      
+      // Extract repository reference
+      const repositoryBlock = (decl.body || []).find(b => b.kind === 'reference' && b.repositoryName);
+      if (repositoryBlock && repositoryBlock.repositoryName) {
+        // Will be resolved later
+        ref.repositoryName = repositoryBlock.repositoryName;
+      } else if (decl.repositoryName) {
+        // Named reference with "in <RepoName>"
+        ref.repositoryName = decl.repositoryName;
+      }
+      
+      // Extract paths block
+      const pathsBlock = (decl.body || []).find(b => b.kind === 'paths');
+      if (pathsBlock && pathsBlock.paths) {
+        ref.paths = pathsBlock.paths;
+      }
+      
+      // Extract title block
+      const titleBlock = (decl.body || []).find(b => b.kind === 'title');
+      if (titleBlock) {
+        const raw = getRawText(titleBlock.contentSpan, sourceText);
+        const titleValue = raw.trim().replace(/^['"]|['"]$/g, '').trim();
+        if (titleValue.length > 0) {
+          ref.title = titleValue;
+        }
+      }
+      
+      // Extract describe block
+      const describeBlock = (decl.body || []).find(b => b.kind === 'describe');
+      if (describeBlock) {
+        ref.describe = buildTextBlock(describeBlock, sourceText);
+      }
+      
+      // Extract note block
+      const noteBlock = (decl.body || []).find(b => b.kind === 'note');
+      if (noteBlock) {
+        ref.note = buildTextBlock(noteBlock, sourceText);
+      }
+      
+      references.set(id, ref);
+    }
+  }
+  
+  return { nodes, repositories, references, diagnostics };
+}
+
+/**
+ * Pass 5: Build edges from relationship usage
+ * @param {BoundDecl[]} boundDecls
+ * @param {Map<DeclId, NodeModel>} nodes
+ * @param {Map<ScopeKey, SchemaRegistry>} schemas
+ * @param {DeclIndex} index
+ * @param {Map<DeclId, DeclId>} parentMap
+ * @param {Array<{ sourceText: string, filePath: string }>} fileData
+ * @returns {{ edges: EdgeAssertedModel[], diagnostics: Diagnostic[] }}
+ */
+function buildEdges(boundDecls, nodes, schemas, index, parentMap, fileData) {
+  const edges = [];
+  const diagnostics = [];
+  
+  const fileDataMap = new Map();
+  for (const file of fileData) {
+    fileDataMap.set(file.filePath, file.sourceText);
+  }
+  
+  for (const bound of boundDecls) {
+    const { id, decl, info } = bound;
+    const node = nodes.get(id);
+    if (!node) continue;
+    
+    const sourceText = fileDataMap.get(info.span?.file || '') || '';
+    
+    // Handle relationships block entries (new syntax)
+    if (node.relationships && node.relationships.entries) {
+      for (const entry of node.relationships.entries) {
+        for (const target of entry.targets) {
+          const pathSegments = target.id.split('.');
+          let targetDeclId = null;
+          
+          if (pathSegments.length === 1) {
+            const resolved = resolveUnqualified(pathSegments[0], id, index, parentMap, node.relationships.source);
+            if (resolved.ambiguous) {
+              diagnostics.push({
+                severity: 'error',
+                message: `Ambiguous reference "${pathSegments[0]}" - use qualified path`,
+                source: node.relationships.source,
+              });
+            } else if (resolved.declId) {
+              targetDeclId = resolved.declId;
+            }
+          } else {
+            const resolved = resolveQualified(pathSegments, index, node.relationships.source);
+            if (resolved.declId) {
+              targetDeclId = resolved.declId;
+            }
+          }
+          
+          if (targetDeclId) {
+            edges.push({
+              from: id,
+              via: entry.relationshipId,
+              to: targetDeclId,
+              meta: target.metadata,
+              source: node.relationships.source,
+            });
+          }
+        }
+      }
+    }
+  }
+  
+  // Handle relates nodes - create bidirectional edges
+  for (const bound of boundDecls) {
+    const { id, decl, info } = bound;
+    if (info.kindResolved !== 'relates') continue;
+    
+    const node = nodes.get(id);
+    if (!node || !node.endpoints || node.endpoints.length !== 2) continue;
+    
+    const [endpointA, endpointB] = node.endpoints;
+    const viaLabel = (node.relationships && node.relationships.values && node.relationships.values[0]) || 'related to';
+    
+    edges.push({
+      from: endpointA,
+      via: viaLabel,
+      to: endpointB,
+      meta: node.from?.[endpointA]?.describe,
+      source: node.source,
+      bidirectional: true,
+    });
+  }
+  
+  return { edges, diagnostics };
+}
+
+/**
+ * Pass 6: Normalize edges - add inverse edges for paired/symmetric relationships
+ * @param {EdgeAssertedModel[]} edges
+ * @param {Map<ScopeKey, SchemaRegistry>} schemas
+ * @param {string} universeName
+ * @returns {NormalizedEdgeModel[]}
+ */
+function normalizeEdges(edges, schemas, universeName) {
+  const normalized = [];
+  const seenEdges = new Set();
+  
+  for (const asserted of edges) {
+    const edgeKey = `${asserted.from}:${asserted.via}:${asserted.to}`;
+    
+    if (seenEdges.has(edgeKey)) continue;
+    seenEdges.add(edgeKey);
+    
+    // Add asserted edge
+    normalized.push({
+      from: asserted.from,
+      via: asserted.via,
+      to: asserted.to,
+      asserted: true,
+      sourceRefs: [asserted.source],
+      meta: asserted.meta,
+      bidirectional: asserted.bidirectional || false,
+    });
+    
+    // Find relationship schema (check all scopes)
+    let relDecl = null;
+    for (const registry of schemas.values()) {
+      if (registry.schemas.has(asserted.via)) {
+        relDecl = registry.schemas.get(asserted.via);
+        break;
+      }
+    }
+    
+    // Add inverse edge if applicable (only for declared relationships, not relates)
+    if (relDecl && !asserted.bidirectional) {
+      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}`;
+          if (!seenEdges.has(inverseKey)) {
+            normalized.push({
+              from: asserted.to,
+              via: inverseVia,
+              to: asserted.from,
+              asserted: false,
+              sourceRefs: [asserted.source],
+              meta: asserted.meta,
+            });
+            seenEdges.add(inverseKey);
+          }
+        }
+      } else if (relDecl.type === 'symmetric') {
+        // Symmetric: add reverse edge with same relationship ID
+        const reverseKey = `${asserted.to}:${asserted.via}:${asserted.from}`;
+        if (!seenEdges.has(reverseKey)) {
+          normalized.push({
+            from: asserted.to,
+            via: asserted.via,
+            to: asserted.from,
+            asserted: false,
+            sourceRefs: [asserted.source],
+            meta: asserted.meta,
+          });
+          seenEdges.add(reverseKey);
+        }
+      }
+    }
+  }
+  
+  return normalized;
+}
+
+/**
+ * Resolve relates node endpoints
+ * @param {Map<DeclId, NodeModel>} nodes
+ * @param {DeclIndex} index
+ * @param {Map<DeclId, DeclId>} parentMap
+ * @param {BoundDecl[]} boundDecls
+ * @returns {Diagnostic[]}
+ */
+function resolveRelatesEndpoints(nodes, index, parentMap, boundDecls) {
+  const diagnostics = [];
+  
+  for (const bound of boundDecls) {
+    const { id, decl, info } = bound;
+    if (info.kindResolved !== 'relates') continue;
+    
+    const node = nodes.get(id);
+    if (!node || !node.unresolvedEndpoints) continue;
+    
+    const resolvedEndpoints = [];
+    const unresolved = [];
+    
+    for (const endpointName of node.unresolvedEndpoints) {
+      const resolved = resolveUnqualified(endpointName, id, index, parentMap, info.span);
+      if (resolved.declId && !resolved.ambiguous) {
+        resolvedEndpoints.push(resolved.declId);
+      } else {
+        unresolved.push(endpointName);
+        if (!resolved.ambiguous) {
+          diagnostics.push({
+            severity: 'warning',
+            message: `Unresolved relates endpoint "${endpointName}"`,
+            source: info.span,
+          });
+        } else {
+          diagnostics.push({
+            severity: 'error',
+            message: `Ambiguous relates endpoint "${endpointName}" - use qualified path`,
+            source: info.span,
+          });
+        }
+      }
+    }
+    
+    node.endpoints = resolvedEndpoints;
+    if (unresolved.length > 0) {
+      node.unresolvedEndpoints = unresolved;
+    } else {
+      delete node.unresolvedEndpoints;
+    }
+    
+    // Resolve from blocks: convert endpoint names to node IDs
+    if (node.from) {
+      const resolvedFrom = {};
+      for (const endpointName in node.from) {
+        const resolved = resolveUnqualified(endpointName, id, index, parentMap, info.span);
+        if (resolved.declId && !resolved.ambiguous) {
+          resolvedFrom[resolved.declId] = node.from[endpointName];
+        } else {
+          // Keep unresolved from blocks keyed by name
+          resolvedFrom[endpointName] = node.from[endpointName];
+        }
+      }
+      node.from = resolvedFrom;
+    }
+  }
+  
+  return diagnostics;
+}
+
+/**
+ * Main function: Build UniverseGraph from parsed AST files
+ * @param {Array<{ kind: string, decls: any[], source?: SourceSpan, sourceText?: string }> | { kind: string, decls: any[], source?: SourceSpan, sourceText?: string }} fileAstOrFileAsts
+ * @param {Object} [options]
+ * @returns {UniverseGraph}
+ */
+export function buildGraph(fileAstOrFileAsts, options) {
+  // Normalize input to array
+  const fileASTs = Array.isArray(fileAstOrFileAsts) ? fileAstOrFileAsts : [fileAstOrFileAsts];
+  
+  // Pass 0: Normalize AST
+  const normalized = normalizeAst(fileASTs);
+  
+  // Pass 1: Index declarations
+  const { index, normalizedDecls } = indexDecls(normalized);
+  
+  // Extract universe name
+  const universeNames = Array.from(new Set(normalizedDecls.filter(d => d.kind === 'universe').map(d => d.name)));
+  const universeName = universeNames[0] || 'Unknown';
+  
+  // Pass 2: Bind parents and resolve kinds
+  const { boundDecls, diagnostics: bindDiags, parentMap } = bindParentsAndKinds(index, normalizedDecls);
+  
+  // Pass 3: Compile schemas
+  const { schemas, diagnostics: schemaDiags } = compileSchemas(boundDecls, index);
+  
+  // Pass 4: Build nodes
+  const fileData = normalized.map(n => ({ sourceText: n.sourceText, filePath: n.filePath }));
+  const { nodes, repositories, references, diagnostics: nodeDiags } = buildNodes(boundDecls, schemas, fileData);
+  
+  // Resolve relates endpoints
+  const relatesDiags = resolveRelatesEndpoints(nodes, index, parentMap, boundDecls);
+  
+  // Pass 5: Build edges
+  const { edges: assertedEdges, diagnostics: edgeDiags } = buildEdges(boundDecls, nodes, schemas, index, parentMap, fileData);
+  
+  // Pass 6: Normalize edges
+  const normalizedEdges = normalizeEdges(assertedEdges, schemas, universeName);
+  
+  // Collect all diagnostics
+  const allDiagnostics = [
+    ...index.diagnostics,
+    ...bindDiags,
+    ...schemaDiags,
+    ...nodeDiags,
+    ...relatesDiags,
+    ...edgeDiags,
+  ];
+  
+  // Build relationshipDecls object
+  const relationshipDecls = {};
+  relationshipDecls[universeName] = {};
+  for (const registry of schemas.values()) {
+    for (const [schemaId, schema] of registry.schemas.entries()) {
+      if (schema.type === 'symmetric') {
+        relationshipDecls[universeName][schemaId] = {
+          type: 'symmetric',
+          id: schemaId,
+          describe: undefined, // TODO: extract from schema.decl.body
+          label: undefined, // TODO: extract from schema.decl.body
+          source: schema.decl.source,
+        };
+      } else if (schema.type === 'paired') {
+        relationshipDecls[universeName][schema.leftId] = {
+          type: 'paired',
+          leftId: schema.leftId,
+          rightId: schema.rightId,
+          describe: undefined, // TODO: extract from schema.decl.body
+          from: {}, // TODO: extract from schema.decl.body
+          source: schema.decl.source,
+        };
+        relationshipDecls[universeName][schema.rightId] = relationshipDecls[universeName][schema.leftId];
+      }
+    }
+  }
+  
+  // Build nodes object (convert Map to Record)
+  const nodesObj = {};
+  for (const [id, node] of nodes.entries()) {
+    nodesObj[id] = node;
+  }
+  
+  // Build repositories object
+  const reposObj = {};
+  for (const [id, repo] of repositories.entries()) {
+    reposObj[id] = repo;
+  }
+  
+  // Build references object
+  const refsObj = {};
+  for (const [id, ref] of references.entries()) {
+    refsObj[id] = ref;
+  }
+  
+  // Build universes object
+  const universes = {};
+  const universeNode = Array.from(nodes.values()).find(n => n.kind === 'universe');
+  if (universeNode) {
+    universes[universeName] = {
+      name: universeName,
+      root: universeNode.id,
+    };
+  }
+  
+  return {
+    version: 1,
+    universes,
+    nodes: nodesObj,
+    edges: normalizedEdges,
+    edgesAsserted: assertedEdges,
+    diagnostics: allDiagnostics,
+    repositories: reposObj,
+    references: refsObj,
+    documentsByName: {}, // TODO: implement
+    relationshipDecls,
+  };
+}
+
+// Debug helpers (not exported, for testing)
+/**
+ * @param {DeclIndex} index
+ * @returns {string}
+ */
+function debugIndex(index) {
+  const lines = [];
+  lines.push('=== DeclIndex ===');
+  lines.push(`Declarations: ${index.declIndex.size}`);
+  lines.push(`Scopes: ${index.scopeIndex.size}`);
+  lines.push(`Series: ${index.seriesIndex.size}`);
+  lines.push(`Alias tables: ${index.aliasTablesByScope.size}`);
+  return lines.join('\n');
+}
+
+/**
+ * @param {BoundDecl[]} boundDecls
+ * @returns {string}
+ */
+function debugBound(boundDecls) {
+  const lines = [];
+  lines.push('=== BoundDecls ===');
+  for (const bound of boundDecls) {
+    lines.push(`${bound.id}: ${bound.info.kindResolved} ${bound.info.name} (parent: ${bound.info.parentDeclId || 'none'})`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * @param {Map<ScopeKey, SchemaRegistry>} schemas
+ * @returns {string}
+ */
+function debugSchemas(schemas) {
+  const lines = [];
+  lines.push('=== Schemas ===');
+  for (const [scopeKey, registry] of schemas.entries()) {
+    lines.push(`Scope: ${scopeKey}`);
+    for (const [schemaId, schema] of registry.schemas.entries()) {
+      lines.push(`  ${schemaId}: ${schema.type}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+/**
+ * @param {EdgeAssertedModel[]} edges
+ * @returns {string}
+ */
+function debugEdges(edges) {
+  const lines = [];
+  lines.push('=== Edges ===');
+  for (const edge of edges) {
+    lines.push(`${edge.from} --[${edge.via}]--> ${edge.to}`);
+  }
+  return lines.join('\n');
+}
+