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

package/src/graph.js

@@ -22,11 +22,13 @@ import { normalizeProseBlock } from './util/text.js';
  * @typedef {import('./ast.js').ChapterDecl} ChapterDecl
  * @typedef {import('./ast.js').ConceptDecl} ConceptDecl
  * @typedef {import('./ast.js').RelatesDecl} RelatesDecl
+ * @typedef {import('./ast.js').RelationshipDecl} RelationshipDecl
  * @typedef {import('./ast.js').DescribeBlock} DescribeBlock
  * @typedef {import('./ast.js').TitleBlock} TitleBlock
  * @typedef {import('./ast.js').FromBlock} FromBlock
  * @typedef {import('./ast.js').RelationshipsBlock} RelationshipsBlock
  * @typedef {import('./ast.js').ReferencesBlock} ReferencesBlock
+ * @typedef {import('./ast.js').OrderingBlock} OrderingBlock
  * @typedef {import('./ast.js').ReferenceDecl} ReferenceDecl
  * @typedef {import('./ast.js').DocumentationBlock} DocumentationBlock
  * @typedef {import('./ast.js').DocumentBlock} DocumentBlock
@@ -65,6 +67,15 @@ export function buildGraph(fileASTs) {
   // Track repositories and references per universe for scoped resolution
   const repositoriesByUniverse = new Map(); // universeName -> Map<id, RepositoryDecl>
   const referencesByUniverse = new Map(); // universeName -> Map<id, ReferenceDecl>
+  
+  // Track relationship declarations per scope (containerNodeId -> Map<relationshipId, RelationshipDecl>)
+  const relationshipsByScope = new Map(); // containerNodeId -> Map<relationshipId, RelationshipDecl>
+  
+  // Store relationship declarations by universe for UI access
+  const relationshipDeclsByUniverse = new Map(); // universeName -> Map<relationshipId, RelationshipDecl>
+  
+  // Initialize relationshipDecls in graph
+  graph.relationshipDecls = {};
 
   // Track entity kinds for duplicate detection (references/repositories)
   const entityKinds = new Map(); // id -> kind
@@ -189,6 +200,8 @@ export function buildGraph(fileASTs) {
           repositoriesByUniverse.get(universeName),
           referencesByUniverse.get(universeName),
           entityKinds,
+          relationshipsByScope,
+          relationshipDeclsByUniverse,
           pendingReferenceDecls,
           pendingReferenceAttachments,
           pendingContainerResolutions,
@@ -219,6 +232,8 @@ export function buildGraph(fileASTs) {
           repositoriesByUniverse.get(universeName),
           referencesByUniverse.get(universeName),
           entityKinds,
+          relationshipsByScope,
+          relationshipDeclsByUniverse,
           pendingReferenceDecls,
           pendingReferenceAttachments,
           pendingContainerResolutions,
@@ -255,6 +270,7 @@ export function buildGraph(fileASTs) {
               continue;
             }
           }
+          // Process the declaration itself first
           processBody(
             graph,
             universeName,
@@ -267,6 +283,8 @@ export function buildGraph(fileASTs) {
             repositoriesByUniverse.get(universeName),
             referencesByUniverse.get(universeName),
             entityKinds,
+            relationshipsByScope,
+            relationshipDeclsByUniverse,
             pendingReferenceDecls,
             pendingReferenceAttachments,
             pendingContainerResolutions,
@@ -294,6 +312,37 @@ export function buildGraph(fileASTs) {
   // Resolve container references (books/chapters) that may have forward references
   resolveContainers(graph, scopeIndex, pendingContainerResolutions);
 
+  // Validate and apply ordering blocks after all nodes and relationships are established
+  validateOrderingBlocks(graph);
+
+  // Extract asserted edges from both relationships blocks and relates nodes
+  graph.edgesAsserted = extractAssertedEdges(graph, scopeIndex);
+
+  // Preserve existing edges object format for relates (for code that still uses it)
+  graph.edgesByRelates = graph.edges;
+
+  // Normalize edges (add inverse edges for paired/symmetric relationships)
+  const universeNames = Array.from(universeNameToFiles.keys());
+  if (universeNames.length > 0) {
+    // For now, assume single universe (as per buildGraph contract)
+    const universeName = universeNames[0];
+    graph.edges = normalizeEdges(
+      graph.edgesAsserted,
+      relationshipDeclsByUniverse,
+      universeName,
+    );
+  } else {
+    graph.edges = [];
+  }
+
+  // Convert relationshipDeclsByUniverse Maps to plain objects for JSON serialization
+  // (already done above, but ensure all universes are initialized)
+  for (const [universeName, declsMap] of relationshipDeclsByUniverse.entries()) {
+    if (!graph.relationshipDecls[universeName]) {
+      graph.relationshipDecls[universeName] = {};
+    }
+  }
+
   return graph;
 }
 
@@ -346,7 +395,7 @@ function addNameToScope(graph, scopeIndex, scopeNodeId, name, nodeId) {
  */
 function resolveNameInScope(graph, scopeIndex, name, startScopeNodeId, source) {
   // Handle qualified names (dot notation)
-  if (name.includes('.')) {
+  if (name && name.includes('.')) {
     const parts = name.split('.');
     // Start from universe and resolve each part
     const universeName = startScopeNodeId.split(':')[0];
@@ -502,6 +551,8 @@ function resolveRelatesEndpoint(graph, scopeIndex, name, startScopeNodeId, sourc
  * @param {Map<string, RepositoryDecl>} [reposMap] - Map for tracking repository declarations (universe scope only)
  * @param {Map<string, ReferenceDecl>} [refsMap] - Map for tracking reference declarations (universe scope only)
  * @param {Map<string, string>} [entityKinds] - Map for tracking non-node entity kinds by ID
+ * @param {Map<string, Map<string, RelationshipDecl>>} relationshipsByScope - Map for tracking relationship declarations per scope (required)
+ * @param {Map<string, Map<string, RelationshipDecl>>} relationshipDeclsByUniverse - Map for storing relationship declarations by universe for UI access
  * @param {Array} [pendingReferenceDecls] - Reference declarations to resolve after indexing
  * @param {Array} [pendingReferenceAttachments] - Reference attachments to resolve after indexing
  * @param {Array} [pendingContainerResolutions] - Container resolutions to resolve after all nodes are created
@@ -518,12 +569,97 @@ function processBody(
   reposMap,
   refsMap,
   entityKinds,
+  relationshipsByScope,
+  relationshipDeclsByUniverse,
   pendingReferenceDecls,
   pendingReferenceAttachments,
   pendingContainerResolutions,
 ) {
+  // Collect ordering blocks to process after all children are added
+  const orderingBlocks = [];
+  
+  // Ensure relationshipsByScope is initialized as a Map
+  // This should always be provided, but check to prevent runtime errors
+  if (!relationshipsByScope) {
+    throw new Error(`relationshipsByScope is required but was ${relationshipsByScope}`);
+  }
+  if (typeof relationshipsByScope.has !== 'function' || typeof relationshipsByScope.set !== 'function' || typeof relationshipsByScope.get !== 'function') {
+    throw new Error(`relationshipsByScope must be a Map, got ${typeof relationshipsByScope} with has: ${typeof relationshipsByScope.has}, set: ${typeof relationshipsByScope.set}, get: ${typeof relationshipsByScope.get}`);
+  }
+  
+  // Initialize relationship scope for current container if not exists
+  if (!relationshipsByScope.has(currentNodeId)) {
+    relationshipsByScope.set(currentNodeId, new Map());
+  }
+  // Inherit parent relationships
+  if (parentNodeId && relationshipsByScope.has(parentNodeId)) {
+    const parentRelationships = relationshipsByScope.get(parentNodeId);
+    const currentRelationships = relationshipsByScope.get(currentNodeId);
+    if (parentRelationships && currentRelationships) {
+      for (const [id, rel] of parentRelationships) {
+        if (!currentRelationships.has(id)) {
+          currentRelationships.set(id, rel);
+        }
+      }
+    }
+  }
+  
   for (const decl of body) {
-    if (decl.kind === 'anthology') {
+    if (decl.kind === 'relationship' && relationshipsByScope) {
+      // Track relationship declaration in current scope
+      const currentRelationships = relationshipsByScope.get(currentNodeId);
+      if (currentRelationships) {
+        if (decl.type === 'symmetric' && decl.id) {
+          currentRelationships.set(decl.id, decl);
+          // Also store in universe-level map for UI access
+          if (!relationshipDeclsByUniverse.has(universeName)) {
+            relationshipDeclsByUniverse.set(universeName, new Map());
+            graph.relationshipDecls[universeName] = {};
+          }
+          const universeDecls = relationshipDeclsByUniverse.get(universeName);
+          if (universeDecls) {
+            universeDecls.set(decl.id, {
+              type: decl.type,
+              id: decl.id,
+              describe: decl.describe,
+              label: decl.label,
+              source: decl.source,
+            });
+            graph.relationshipDecls[universeName][decl.id] = {
+              type: decl.type,
+              id: decl.id,
+              describe: decl.describe,
+              label: decl.label,
+              source: decl.source,
+            };
+          }
+        } else if (decl.type === 'paired') {
+          if (decl.leftId) currentRelationships.set(decl.leftId, decl);
+          if (decl.rightId) currentRelationships.set(decl.rightId, decl);
+          // Also store in universe-level map for UI access (store once per pair)
+          if (!relationshipDeclsByUniverse.has(universeName)) {
+            relationshipDeclsByUniverse.set(universeName, new Map());
+            graph.relationshipDecls[universeName] = {};
+          }
+          const universeDecls = relationshipDeclsByUniverse.get(universeName);
+          if (universeDecls && decl.leftId && decl.rightId) {
+            // Store under both IDs for easy lookup
+            const declModel = {
+              type: decl.type,
+              leftId: decl.leftId,
+              rightId: decl.rightId,
+              describe: decl.describe,
+              from: decl.from,
+              source: decl.source,
+            };
+            universeDecls.set(decl.leftId, declModel);
+            universeDecls.set(decl.rightId, declModel);
+            graph.relationshipDecls[universeName][decl.leftId] = declModel;
+            graph.relationshipDecls[universeName][decl.rightId] = declModel;
+          }
+        }
+      }
+    } else if (decl.kind === 'anthology') {
       const nodeId = makeNodeId(universeName, 'anthology', decl.name);
       checkDuplicateInScope(graph, scopeIndex, currentNodeId, decl.name, nodeId, 'anthology', decl.source);
       let actualParentNodeId = parentNodeId;
@@ -549,6 +685,8 @@ function processBody(
         reposMap,
         refsMap,
         entityKinds,
+        relationshipsByScope,
+        relationshipDeclsByUniverse,
         pendingReferenceDecls,
         pendingReferenceAttachments,
         pendingContainerResolutions,
@@ -583,6 +721,8 @@ function processBody(
         reposMap,
         refsMap,
         entityKinds,
+        relationshipsByScope,
+        relationshipDeclsByUniverse,
         pendingReferenceDecls,
         pendingReferenceAttachments,
         pendingContainerResolutions,
@@ -626,6 +766,8 @@ function processBody(
         reposMap,
         refsMap,
         entityKinds,
+        relationshipsByScope,
+        relationshipDeclsByUniverse,
         pendingReferenceDecls,
         pendingReferenceAttachments,
         pendingContainerResolutions,
@@ -698,6 +840,8 @@ function processBody(
         reposMap,
         refsMap,
         entityKinds,
+        relationshipsByScope,
+        relationshipDeclsByUniverse,
         pendingReferenceDecls,
         pendingReferenceAttachments,
         pendingContainerResolutions,
@@ -720,6 +864,27 @@ function processBody(
       graph.nodes[nodeId] = node;
       graph.nodes[actualParentNodeId].children.push(nodeId);
       addNameToScope(graph, scopeIndex, currentNodeId, decl.name, nodeId);
+      
+      // Validate relationships blocks in concept body
+      const relationshipsBlocks = decl.body.filter((b) => b.kind === 'relationships');
+      for (const relBlock of relationshipsBlocks) {
+        if (relBlock.entries && relationshipsByScope) {
+          // New syntax: validate relationship IDs
+          const currentRelationships = relationshipsByScope.get(currentNodeId);
+          if (currentRelationships) {
+            for (const entry of relBlock.entries) {
+              if (!currentRelationships.has(entry.relationshipId)) {
+                graph.diagnostics.push({
+                  severity: 'error',
+                  message: `Undeclared relationship identifier "${entry.relationshipId}" in relationships block`,
+                  source: relBlock.source,
+                });
+              }
+            }
+          }
+        }
+      }
+      
       processBody(
         graph,
         universeName,
@@ -732,8 +897,10 @@ function processBody(
         reposMap,
         refsMap,
         entityKinds,
+        relationshipsByScope,
         pendingReferenceDecls,
         pendingReferenceAttachments,
+        pendingContainerResolutions,
       );
     } else if (decl.kind === 'relates') {
       // Check for duplicate relates in reverse order
@@ -818,6 +985,8 @@ function processBody(
         source: decl.source,
         endpoints: [], // Will be populated during resolution
         unresolvedEndpoints: [decl.a, decl.b], // Will be cleared during resolution
+        spelledKind: decl.spelledKind,
+        aliases: decl.aliases && Object.keys(decl.aliases).length > 0 ? decl.aliases : undefined,
       };
 
       // Add top-level describe if present
@@ -944,6 +1113,9 @@ function processBody(
     } else if (decl.kind === 'title') {
       // Title blocks are attached to their parent node
       // This is handled in createNode
+    } else if (decl.kind === 'relationships') {
+      // Relationships blocks are attached to their parent node
+      // This is handled in createNode
     } else if (decl.kind === 'references') {
       if (pendingReferenceAttachments) {
         pendingReferenceAttachments.push({
@@ -952,6 +1124,9 @@ function processBody(
           universeName,
         });
       }
+    } else if (decl.kind === 'ordering') {
+      // Collect ordering blocks to process after all children are added
+      orderingBlocks.push(decl);
     } else if (decl.kind === 'documentation') {
       // DocumentationBlock - attach to current node
       const currentNode = graph.nodes[currentNodeId];
@@ -1102,19 +1277,52 @@ function processBody(
           graph.documentsByName[universeName][docName] = docModel;
         }
       }
+    } else if (decl.kind === 'relationship') {
+      // Relationship declarations are tracked in relationshipsByScope but don't create nodes
+      // They're just declarations that can be referenced in relationships blocks
     } else {
       // UnknownBlock - attach to current node (the node whose body contains this block)
-      const currentNode = graph.nodes[currentNodeId];
-      if (!currentNode.unknownBlocks) {
-        currentNode.unknownBlocks = [];
+      // Only process if it's actually an UnknownBlock (has keyword property, not kind)
+      // Blocks with 'kind' property are known block types that should be handled above
+      if (decl.keyword && !decl.kind) {
+        const currentNode = graph.nodes[currentNodeId];
+        if (!currentNode.unknownBlocks) {
+          currentNode.unknownBlocks = [];
+        }
+        currentNode.unknownBlocks.push({
+          keyword: decl.keyword,
+          raw: decl.raw,
+          normalized: normalizeProseBlock(decl.raw),
+          source: decl.source,
+        });
       }
-      currentNode.unknownBlocks.push({
-        keyword: decl.keyword,
-        raw: decl.raw,
-        normalized: normalizeProseBlock(decl.raw),
-        source: decl.source,
+      // If it has a 'kind' property, it's a known block type that should have been handled above
+      // Skip it silently (it may have been handled elsewhere, e.g., in createNode)
+    }
+  }
+
+  // Store ordering blocks for later validation (after all nodes are created)
+  // We'll validate them in a separate pass after the entire graph is built
+  // This is necessary because children may be defined outside their parent's body
+  // (e.g., "book X in Y" defined at anthology level, not inside series Y's body)
+  if (orderingBlocks.length > 0) {
+    const currentNode = graph.nodes[currentNodeId];
+    if (!currentNode) {
+      return;
+    }
+
+    // Validate: only one ordering block per container
+    if (orderingBlocks.length > 1) {
+      graph.diagnostics.push({
+        severity: 'warning',
+        message: `Multiple ordering blocks in ${currentNode.kind} "${currentNode.name}". Using the first one.`,
+        source: orderingBlocks[1].source,
       });
     }
+
+    // Store ordering block temporarily on the node for later validation
+    // We'll process this in validateOrderingBlocks() after all nodes are created
+    currentNode._pendingOrdering = orderingBlocks[0];
   }
 }
 
@@ -1136,6 +1344,8 @@ function createNode(nodeId, kind, name, parentNodeId, decl, containerNodeId) {
     parent: parentNodeId,
     children: [],
     source: decl.source,
+    spelledKind: decl.spelledKind,
+    aliases: decl.aliases && Object.keys(decl.aliases).length > 0 ? decl.aliases : undefined,
   };
 
   // Always set container for book/chapter nodes (may be undefined if not resolved)
@@ -1166,6 +1376,34 @@ function createNode(nodeId, kind, name, parentNodeId, decl, containerNodeId) {
     }
   }
 
+  // Extract relationships block if present
+  const relationshipsBlock = decl.body?.find((b) => b.kind === 'relationships');
+  if (relationshipsBlock) {
+    if (relationshipsBlock.entries) {
+      // New syntax: relationship ID + targets
+      node.relationships = {
+        entries: relationshipsBlock.entries.map((entry) => ({
+          relationshipId: entry.relationshipId,
+          targets: entry.targets.map((target) => ({
+            id: target.id,
+            metadata: target.metadata ? {
+              raw: target.metadata.raw,
+              normalized: normalizeProseBlock(target.metadata.raw),
+              source: target.metadata.source,
+            } : undefined,
+          })),
+        })),
+        source: relationshipsBlock.source,
+      };
+    } else if (relationshipsBlock.values) {
+      // String literals syntax (for relates blocks)
+      node.relationships = {
+        values: relationshipsBlock.values,
+        source: relationshipsBlock.source,
+      };
+    }
+  }
+
   // Note: UnknownBlocks are handled in processBody and attached to the parent node
   // They are not extracted here to avoid duplication
 
@@ -1243,7 +1481,7 @@ function resolveEdges(graph, scopeIndex) {
     }
   }
 
-  // Resolve edges (for backward compatibility)
+  // Resolve edges (relates edges in object format)
   for (const edgeId in graph.edges) {
     const edge = graph.edges[edgeId];
     const universeName = edgeId.split(':')[0];
@@ -1399,6 +1637,161 @@ function resolveContainers(graph, scopeIndex, pending) {
   }
 }
 
+/**
+ * Extracts asserted edges from both relationships {} blocks and relates nodes
+ * @param {UniverseGraph} graph - The graph
+ * @param {Map<string, Map<string, string[]>>} scopeIndex - Scope index
+ * @returns {import('./ir.js').EdgeAssertedModel[]}
+ */
+function extractAssertedEdges(graph, scopeIndex) {
+  /** @type {import('./ir.js').EdgeAssertedModel[]} */
+  const assertedEdges = [];
+
+  // Extract from relationships {} blocks (new-style adjacency lists)
+  for (const nodeId in graph.nodes) {
+    const node = graph.nodes[nodeId];
+    if (!node.relationships || !node.relationships.entries) continue;
+
+    // Resolve each target and create asserted edge
+    for (const entry of node.relationships.entries) {
+      for (const target of entry.targets) {
+        // Resolve target ID using scope resolution
+        const resolved = resolveNameInScope(
+          graph,
+          scopeIndex,
+          target.id,
+          nodeId,
+          node.relationships.source,
+        );
+        const targetNodeId = resolved.nodeId && !resolved.ambiguous ? resolved.nodeId : null;
+        if (!targetNodeId) continue;
+
+        assertedEdges.push({
+          from: nodeId,
+          via: entry.relationshipId,
+          to: targetNodeId,
+          meta: target.metadata,
+          source: node.relationships.source,
+        });
+      }
+    }
+  }
+
+  // Extract from relates nodes (bidirectional relationships)
+  for (const nodeId in graph.nodes) {
+    const node = graph.nodes[nodeId];
+    if (node.kind !== 'relates' || !node.endpoints || node.endpoints.length !== 2) continue;
+
+    const [endpointA, endpointB] = node.endpoints;
+
+    // Relates are bidirectional - extract both directions as asserted edges
+    // Use the relationship label from the relates node if available
+    const viaLabel = node.relationships?.values?.[0] || 'related to';
+
+    // Create edge A -> B
+    assertedEdges.push({
+      from: endpointA,
+      via: viaLabel, // Note: relates don't use relationship declarations, they use string labels
+      to: endpointB,
+      meta: node.from?.[endpointA]?.describe,
+      source: node.source,
+    });
+
+    // Create edge B -> A (relates are bidirectional)
+    assertedEdges.push({
+      from: endpointB,
+      via: viaLabel,
+      to: endpointA,
+      meta: node.from?.[endpointB]?.describe,
+      source: node.source,
+    });
+  }
+
+  return assertedEdges;
+}
+
+/**
+ * Normalizes edges by adding inverse edges for paired/symmetric relationships
+ * @param {import('./ir.js').EdgeAssertedModel[]} assertedEdges - Asserted edges
+ * @param {Map<string, Map<string, import('./ast.js').RelationshipDecl>>} relationshipDecls - Relationship declarations by universe
+ * @param {string} universeName - Universe name
+ * @returns {import('./ir.js').NormalizedEdgeModel[]}
+ */
+function normalizeEdges(assertedEdges, relationshipDecls, universeName) {
+  /** @type {import('./ir.js').NormalizedEdgeModel[]} */
+  const normalizedEdges = [];
+  const relDeclsMap = relationshipDecls.get(universeName);
+  const relDecls = relDeclsMap ? Object.fromEntries(relDeclsMap) : {};
+  const seenEdges = new Set(); // Track edges to avoid duplicates
+
+  for (const asserted of assertedEdges) {
+    const edgeKey = `${asserted.from}:${asserted.via}:${asserted.to}`;
+
+    // Skip if we've already added this exact edge (can happen with relates bidirectional edges)
+    if (seenEdges.has(edgeKey)) continue;
+    seenEdges.add(edgeKey);
+
+    // Get relationship declaration if this is a declared relationship
+    // Note: relates edges use string labels, not relationship IDs, so they won't have a relDecl
+    const relDecl = relDecls[asserted.via];
+
+    // Add asserted edge
+    normalizedEdges.push({
+      from: asserted.from,
+      via: asserted.via,
+      to: asserted.to,
+      asserted: true,
+      sourceRefs: [asserted.source],
+      meta: asserted.meta,
+    });
+
+    // Add inverse edge if applicable (only for declared relationships, not relates)
+    // Relates are already bidirectional, so both directions are in assertedEdges
+    if (relDecl) {
+      if (relDecl.type === 'paired') {
+        // Determine inverse side
+        const inverseVia =
+          asserted.via === relDecl.leftId ? relDecl.rightId : relDecl.leftId;
+
+        if (inverseVia) {
+          const inverseKey = `${asserted.to}:${inverseVia}:${asserted.from}`;
+          // Only add inverse if not already present as an asserted edge
+          if (!seenEdges.has(inverseKey)) {
+            normalizedEdges.push({
+              from: asserted.to,
+              via: inverseVia,
+              to: asserted.from,
+              asserted: false,
+              sourceRefs: [asserted.source], // Points back to asserted edge
+              meta: asserted.meta, // Copy metadata
+            });
+            seenEdges.add(inverseKey);
+          }
+        }
+      } else if (relDecl.type === 'symmetric') {
+        // Symmetric: add reverse edge with same relationship ID
+        const reverseKey = `${asserted.to}:${asserted.via}:${asserted.from}`;
+        // Only add reverse if not already present as an asserted edge
+        if (!seenEdges.has(reverseKey)) {
+          normalizedEdges.push({
+            from: asserted.to,
+            via: asserted.via,
+            to: asserted.from,
+            asserted: false,
+            sourceRefs: [asserted.source],
+            meta: asserted.meta,
+          });
+          seenEdges.add(reverseKey);
+        }
+      }
+    }
+    // Note: If no relDecl found, it's likely a relates edge (string label, not declared relationship)
+    // Relates edges are already bidirectional in assertedEdges, so no inverse needed
+  }
+
+  return normalizedEdges;
+}
+
 /**
  * @param {string | undefined} raw
  * @returns {string | undefined}
@@ -1746,6 +2139,56 @@ function makeRelatesNodeId(universeName, a, b, index = 0) {
   return `${universeName}:relates:${a}:${b}:${index}`;
 }
 
+/**
+ * Validates and applies ordering blocks after all nodes and relationships are established
+ * This must run after all nodes are created because children may be defined outside their parent's body
+ * (e.g., "book X in Y" defined at anthology level, not inside series Y's body)
+ * @param {UniverseGraph} graph
+ */
+function validateOrderingBlocks(graph) {
+  for (const nodeId in graph.nodes) {
+    const node = graph.nodes[nodeId];
+    if (!node._pendingOrdering) {
+      continue;
+    }
+
+    const orderingBlock = node._pendingOrdering;
+    const orderingIdentifiers = orderingBlock.identifiers;
+
+    // Build a map of child names to node IDs for validation
+    const childNameToNodeId = new Map();
+    for (const childId of node.children) {
+      const childNode = graph.nodes[childId];
+      if (childNode) {
+        childNameToNodeId.set(childNode.name, childId);
+      }
+    }
+
+    // Validate ordering identifiers against actual children
+    const validOrdering = [];
+    for (const identifier of orderingIdentifiers) {
+      if (childNameToNodeId.has(identifier)) {
+        validOrdering.push(identifier);
+      } else {
+        // Unknown identifier - emit gentle warning
+        graph.diagnostics.push({
+          severity: 'warning',
+          message: `Ordering block in ${node.kind} "${node.name}" references unknown child "${identifier}". This identifier will be ignored.`,
+          source: orderingBlock.source,
+        });
+      }
+    }
+
+    // Store ordering if there are any valid identifiers
+    if (validOrdering.length > 0) {
+      node.ordering = validOrdering;
+    }
+
+    // Clean up temporary field
+    delete node._pendingOrdering;
+  }
+}
+
 /**
  * Creates an edge ID
  * @param {string} universeName