@sprig-and-prose/sprig-universe 0.4.4 → 0.4.5

package/package.json

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

package/src/universe/.sprig/manifest.json

@@ -15,6 +15,7 @@
         "CanonicalUniverse:anthology:NestedAnthology",
         "CanonicalUniverse:relates:NestedConcept and ExternalConcept",
         "CanonicalUniverse:anthology:AnthologyWithRelationships",
+        "CanonicalUniverse:reference:GlobalReference",
         "CanonicalUniverse:anthology:ExternalAnthology",
         "CanonicalUniverse:repository:ExternalRepository"
       ],
@@ -931,7 +932,10 @@
       },
       "aliases": {
         "other": "book"
-      }
+      },
+      "references": [
+        "CanonicalUniverse:reference:CanonicalUniverse:concept:ConceptWithDirectReference:main"
+      ]
     },
     "CanonicalUniverse:concept:ConceptWithReferences": {
       "id": "CanonicalUniverse:concept:ConceptWithReferences",
@@ -981,7 +985,10 @@
       },
       "aliases": {
         "other": "book"
-      }
+      },
+      "references": [
+        "CanonicalUniverse:reference:CanonicalUniverse:concept:ConceptWithReferenceInRepository:file1"
+      ]
     },
     "CanonicalUniverse:anthology:ExternalAnthology": {
       "id": "CanonicalUniverse:anthology:ExternalAnthology",
@@ -995,14 +1002,14 @@
       "source": {
         "file": "/home/grumpy/git/sprig-universe/src/universe/universe.prose",
         "start": {
-          "line": 147,
+          "line": 151,
           "col": 1,
-          "offset": 3023
+          "offset": 3112
         },
         "end": {
-          "line": 163,
+          "line": 169,
           "col": 2,
-          "offset": 3340
+          "offset": 3463
         }
       },
       "aliases": {
@@ -1017,14 +1024,14 @@
           "source": {
             "file": "/home/grumpy/git/sprig-universe/src/universe/universe.prose",
             "start": {
-              "line": 153,
+              "line": 157,
               "col": 3,
-              "offset": 3145
+              "offset": 3234
             },
             "end": {
-              "line": 160,
+              "line": 164,
               "col": 4,
-              "offset": 3284
+              "offset": 3373
             }
           }
         },
@@ -1035,17 +1042,20 @@
           "source": {
             "file": "/home/grumpy/git/sprig-universe/src/universe/universe.prose",
             "start": {
-              "line": 162,
+              "line": 166,
               "col": 3,
-              "offset": 3288
+              "offset": 3377
             },
             "end": {
-              "line": 162,
+              "line": 166,
               "col": 53,
-              "offset": 3338
+              "offset": 3427
             }
           }
         }
+      ],
+      "references": [
+        "CanonicalUniverse:reference:GlobalReference"
       ]
     },
     "CanonicalUniverse:container:BookAlias": {
@@ -1060,14 +1070,14 @@
       "source": {
         "file": "/home/grumpy/git/sprig-universe/src/universe/universe.prose",
         "start": {
-          "line": 153,
+          "line": 157,
           "col": 3,
-          "offset": 3145
+          "offset": 3234
         },
         "end": {
-          "line": 160,
+          "line": 164,
           "col": 4,
-          "offset": 3284
+          "offset": 3373
         }
       },
       "spelledKind": "bookAlias",
@@ -1083,14 +1093,14 @@
           "source": {
             "file": "/home/grumpy/git/sprig-universe/src/universe/universe.prose",
             "start": {
-              "line": 154,
+              "line": 158,
               "col": 5,
-              "offset": 3171
+              "offset": 3260
             },
             "end": {
-              "line": 154,
+              "line": 158,
               "col": 40,
-              "offset": 3206
+              "offset": 3295
             }
           }
         }
@@ -1109,14 +1119,14 @@
       "source": {
         "file": "/home/grumpy/git/sprig-universe/src/universe/universe.prose",
         "start": {
-          "line": 154,
+          "line": 158,
           "col": 5,
-          "offset": 3171
+          "offset": 3260
         },
         "end": {
-          "line": 154,
+          "line": 158,
           "col": 40,
-          "offset": 3206
+          "offset": 3295
         }
       },
       "spelledKind": "chapterAlias",
@@ -1134,14 +1144,14 @@
       "source": {
         "file": "/home/grumpy/git/sprig-universe/src/universe/universe.prose",
         "start": {
-          "line": 162,
+          "line": 166,
           "col": 3,
-          "offset": 3288
+          "offset": 3377
         },
         "end": {
-          "line": 162,
+          "line": 166,
           "col": 53,
-          "offset": 3338
+          "offset": 3427
         }
       },
       "spelledKind": "chapterAlias",
@@ -1161,16 +1171,20 @@
       "source": {
         "file": "/home/grumpy/git/sprig-universe/src/universe/universe.prose",
         "start": {
-          "line": 165,
+          "line": 171,
           "col": 1,
-          "offset": 3342
+          "offset": 3465
         },
         "end": {
-          "line": 165,
-          "col": 47,
-          "offset": 3388
+          "line": 175,
+          "col": 2,
+          "offset": 3612
         }
-      }
+      },
+      "references": [
+        "CanonicalUniverse:reference:CanonicalUniverse:series:ExternalSeries:external-series",
+        "CanonicalUniverse:reference:GlobalReference"
+      ]
     },
     "CanonicalUniverse:book:ExternalBook": {
       "id": "CanonicalUniverse:book:ExternalBook",
@@ -1183,16 +1197,20 @@
       "source": {
         "file": "/home/grumpy/git/sprig-universe/src/universe/universe.prose",
         "start": {
-          "line": 167,
+          "line": 177,
           "col": 1,
-          "offset": 3390
+          "offset": 3614
         },
         "end": {
-          "line": 167,
-          "col": 40,
-          "offset": 3429
+          "line": 181,
+          "col": 2,
+          "offset": 3752
         }
-      }
+      },
+      "references": [
+        "CanonicalUniverse:reference:CanonicalUniverse:book:ExternalBook:external-book",
+        "CanonicalUniverse:reference:GlobalReference"
+      ]
     },
     "CanonicalUniverse:chapter:ExternalChapter": {
       "id": "CanonicalUniverse:chapter:ExternalChapter",
@@ -1205,16 +1223,20 @@
       "source": {
         "file": "/home/grumpy/git/sprig-universe/src/universe/universe.prose",
         "start": {
-          "line": 169,
+          "line": 183,
           "col": 1,
-          "offset": 3431
+          "offset": 3754
         },
         "end": {
-          "line": 169,
-          "col": 44,
-          "offset": 3474
+          "line": 187,
+          "col": 2,
+          "offset": 3899
         }
-      }
+      },
+      "references": [
+        "CanonicalUniverse:reference:CanonicalUniverse:chapter:ExternalChapter:external-chapter",
+        "CanonicalUniverse:reference:GlobalReference"
+      ]
     },
     "CanonicalUniverse:concept:ExternalConcept": {
       "id": "CanonicalUniverse:concept:ExternalConcept",
@@ -1225,16 +1247,20 @@
       "source": {
         "file": "/home/grumpy/git/sprig-universe/src/universe/universe.prose",
         "start": {
-          "line": 171,
+          "line": 189,
           "col": 1,
-          "offset": 3476
+          "offset": 3901
         },
         "end": {
-          "line": 171,
-          "col": 47,
-          "offset": 3522
+          "line": 193,
+          "col": 2,
+          "offset": 4049
         }
-      }
+      },
+      "references": [
+        "CanonicalUniverse:reference:CanonicalUniverse:concept:ExternalConcept:external-concept",
+        "CanonicalUniverse:reference:GlobalReference"
+      ]
     }
   },
   "edges": [
@@ -1761,14 +1787,14 @@
       "source": {
         "file": "/home/grumpy/git/sprig-universe/src/universe/universe.prose",
         "start": {
-          "line": 173,
+          "line": 195,
           "col": 1,
-          "offset": 3524
+          "offset": 4051
         },
         "end": {
-          "line": 176,
+          "line": 198,
           "col": 2,
-          "offset": 3655
+          "offset": 4182
         }
       },
       "title": "GitHub"
@@ -1810,7 +1836,8 @@
             "offset": 2292
           }
         }
-      }
+      },
+      "scopeDeclId": "CanonicalUniverse:anthology:AnthologyWithRelationships"
     },
     "CanonicalUniverse:reference:NamedReference2": {
       "id": "CanonicalUniverse:reference:NamedReference2",
@@ -1847,7 +1874,8 @@
             "offset": 2476
           }
         }
-      }
+      },
+      "scopeDeclId": "CanonicalUniverse:anthology:AnthologyWithRelationships"
     },
     "CanonicalUniverse:reference:NamedReferenceInRepository": {
       "id": "CanonicalUniverse:reference:NamedReferenceInRepository",
@@ -1874,7 +1902,163 @@
         "path/to/file1.md",
         "path/to/file2.md"
       ],
+      "scopeDeclId": "CanonicalUniverse:anthology:AnthologyWithRelationships",
       "repositoryRef": "CanonicalUniverse:repository:InternalRepository"
+    },
+    "CanonicalUniverse:reference:CanonicalUniverse:concept:ConceptWithDirectReference:main": {
+      "id": "CanonicalUniverse:reference:CanonicalUniverse:concept:ConceptWithDirectReference:main",
+      "name": "main",
+      "urls": [
+        "https://github.com/owner/repository/tree/main"
+      ],
+      "source": {
+        "file": "/home/grumpy/git/sprig-universe/src/universe/universe.prose",
+        "start": {
+          "line": 127,
+          "col": 5,
+          "offset": 2645
+        },
+        "end": {
+          "line": 129,
+          "col": 6,
+          "offset": 2724
+        }
+      },
+      "scopeDeclId": "CanonicalUniverse:concept:ConceptWithDirectReference"
+    },
+    "CanonicalUniverse:reference:CanonicalUniverse:concept:ConceptWithReferenceInRepository:file1": {
+      "id": "CanonicalUniverse:reference:CanonicalUniverse:concept:ConceptWithReferenceInRepository:file1",
+      "name": "file1",
+      "urls": [
+        "https://github.com/owner/repository/tree/main/path/to/file1.md",
+        "https://github.com/owner/repository/tree/main/path/to/file2.md"
+      ],
+      "source": {
+        "file": "/home/grumpy/git/sprig-universe/src/universe/universe.prose",
+        "start": {
+          "line": 137,
+          "col": 5,
+          "offset": 2869
+        },
+        "end": {
+          "line": 143,
+          "col": 6,
+          "offset": 3015
+        }
+      },
+      "repositoryName": "ExternalRepository",
+      "kind": "documentation",
+      "paths": [
+        "path/to/file1.md",
+        "path/to/file2.md"
+      ],
+      "scopeDeclId": "CanonicalUniverse:concept:ConceptWithReferenceInRepository",
+      "repositoryRef": "CanonicalUniverse:repository:ExternalRepository"
+    },
+    "CanonicalUniverse:reference:GlobalReference": {
+      "id": "CanonicalUniverse:reference:GlobalReference",
+      "name": "GlobalReference",
+      "urls": [
+        "https://github.com/owner/repository/tree/main"
+      ],
+      "source": {
+        "file": "/home/grumpy/git/sprig-universe/src/universe/universe.prose",
+        "start": {
+          "line": 147,
+          "col": 1,
+          "offset": 3023
+        },
+        "end": {
+          "line": 149,
+          "col": 2,
+          "offset": 3110
+        }
+      },
+      "scopeDeclId": "CanonicalUniverse:universe:CanonicalUniverse"
+    },
+    "CanonicalUniverse:reference:CanonicalUniverse:series:ExternalSeries:external-series": {
+      "id": "CanonicalUniverse:reference:CanonicalUniverse:series:ExternalSeries:external-series",
+      "name": "external-series",
+      "urls": [
+        "http://localhost:6336/external-series.md"
+      ],
+      "source": {
+        "file": "/home/grumpy/git/sprig-universe/src/universe/universe.prose",
+        "start": {
+          "line": 174,
+          "col": 3,
+          "offset": 3546
+        },
+        "end": {
+          "line": 174,
+          "col": 67,
+          "offset": 3610
+        }
+      },
+      "scopeDeclId": "CanonicalUniverse:series:ExternalSeries"
+    },
+    "CanonicalUniverse:reference:CanonicalUniverse:book:ExternalBook:external-book": {
+      "id": "CanonicalUniverse:reference:CanonicalUniverse:book:ExternalBook:external-book",
+      "name": "external-book",
+      "urls": [
+        "http://localhost:6336/external-book.md"
+      ],
+      "source": {
+        "file": "/home/grumpy/git/sprig-universe/src/universe/universe.prose",
+        "start": {
+          "line": 180,
+          "col": 3,
+          "offset": 3688
+        },
+        "end": {
+          "line": 180,
+          "col": 65,
+          "offset": 3750
+        }
+      },
+      "scopeDeclId": "CanonicalUniverse:book:ExternalBook"
+    },
+    "CanonicalUniverse:reference:CanonicalUniverse:chapter:ExternalChapter:external-chapter": {
+      "id": "CanonicalUniverse:reference:CanonicalUniverse:chapter:ExternalChapter:external-chapter",
+      "name": "external-chapter",
+      "urls": [
+        "http://localhost:6336/external-chapter.md"
+      ],
+      "source": {
+        "file": "/home/grumpy/git/sprig-universe/src/universe/universe.prose",
+        "start": {
+          "line": 186,
+          "col": 3,
+          "offset": 3832
+        },
+        "end": {
+          "line": 186,
+          "col": 68,
+          "offset": 3897
+        }
+      },
+      "scopeDeclId": "CanonicalUniverse:chapter:ExternalChapter"
+    },
+    "CanonicalUniverse:reference:CanonicalUniverse:concept:ExternalConcept:external-concept": {
+      "id": "CanonicalUniverse:reference:CanonicalUniverse:concept:ExternalConcept:external-concept",
+      "name": "external-concept",
+      "urls": [
+        "http://localhost:6336/external-concept.md"
+      ],
+      "source": {
+        "file": "/home/grumpy/git/sprig-universe/src/universe/universe.prose",
+        "start": {
+          "line": 192,
+          "col": 3,
+          "offset": 3982
+        },
+        "end": {
+          "line": 192,
+          "col": 68,
+          "offset": 4047
+        }
+      },
+      "scopeDeclId": "CanonicalUniverse:concept:ExternalConcept"
     }
   },
   "documentsByName": {},
@@ -1937,5 +2121,5 @@
       }
     }
   },
-  "generatedAt": "2026-01-27T17:35:36.143Z"
+  "generatedAt": "2026-01-28T00:15:11.192Z"
 }

package/src/universe/graph.js

@@ -920,6 +920,18 @@ function getRawText(contentSpan, sourceText) {
   return sourceText.slice(contentSpan.startOffset, contentSpan.endOffset);
 }
 
+/**
+ * @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 {string} base
  * @param {string} path
@@ -935,6 +947,63 @@ function joinRepositoryUrl(base, path) {
   return base + path;
 }
 
+/**
+ * @param {{ title?: string, paths?: string[], urls?: string[] }} ref
+ * @returns {string}
+ */
+function deriveReferenceName(ref) {
+  if (ref.title) {
+    return ref.title;
+  }
+  if (ref.paths && ref.paths.length > 0) {
+    const rawPath = ref.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 (ref.urls && ref.urls.length > 0) {
+    try {
+      const parsed = new URL(ref.urls[0]);
+      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';
+}
+
+/**
+ * @param {Map<string, true>} nameMap
+ * @param {string} baseName
+ * @returns {string}
+ */
+function pickUniqueInlineReferenceName(nameMap, baseName) {
+  if (!nameMap.has(baseName)) {
+    nameMap.set(baseName, true);
+    return baseName;
+  }
+  let suffix = 2;
+  let candidate = `${baseName}-${suffix}`;
+  while (nameMap.has(candidate)) {
+    suffix += 1;
+    candidate = `${baseName}-${suffix}`;
+  }
+  nameMap.set(candidate, true);
+  return candidate;
+}
+
 /**
  * Pass 4: Build nodes
  * @param {BoundDecl[]} boundDecls
@@ -942,11 +1011,12 @@ function joinRepositoryUrl(base, path) {
  * @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) {
+function buildNodes(boundDecls, schemas, fileData, universeName) {
   const nodes = new Map();
   const repositories = new Map();
   const references = new Map();
   const diagnostics = [];
+  const inlineReferenceNamesByScope = new Map();
   
   // Build file data map
   const fileDataMap = new Map();
@@ -969,6 +1039,47 @@ function buildNodes(boundDecls, schemas, fileData) {
       source: block.span,
     };
   }
+
+  /**
+   * @param {any} block
+   * @param {string} sourceText
+   * @returns {ReferenceModel}
+   */
+  function buildReferenceFromBlock(block, sourceText) {
+    const ref = {
+      id: '',
+      name: '',
+      urls: [],
+      source: block.source || block.span,
+    };
+
+    if (block.repositoryName) {
+      ref.repositoryName = block.repositoryName;
+    }
+
+    const children = block.children || [];
+    for (const child of children) {
+      if (child.kind === 'url' && child.value) {
+        ref.urls = [child.value];
+      } else if (child.kind === 'paths' && child.paths) {
+        ref.paths = child.paths;
+      } else if (child.kind === 'kind' && child.value) {
+        ref.kind = child.value;
+      } else if (child.kind === 'title') {
+        const raw = getRawText(child.contentSpan, sourceText);
+        const titleValue = normalizeTitleValue(raw);
+        if (titleValue) {
+          ref.title = titleValue;
+        }
+      } else if (child.kind === 'describe') {
+        ref.describe = buildTextBlock(child, sourceText);
+      } else if (child.kind === 'note') {
+        ref.note = buildTextBlock(child, sourceText);
+      }
+    }
+
+    return ref;
+  }
   
   for (const bound of boundDecls) {
     const { id, info, decl } = bound;
@@ -1116,6 +1227,27 @@ function buildNodes(boundDecls, schemas, fileData) {
           .filter(item => item.name);
       }
 
+      // Extract inline reference blocks and attach directly
+      const inlineReferenceBlocks = (decl.body || []).filter(b => b.kind === 'reference' && b.children);
+      if (inlineReferenceBlocks.length > 0) {
+        const nameMap = inlineReferenceNamesByScope.get(id) || new Map();
+        inlineReferenceNamesByScope.set(id, nameMap);
+        for (const block of inlineReferenceBlocks) {
+          const refModel = buildReferenceFromBlock(block, sourceText);
+          const baseName = deriveReferenceName(refModel);
+          const uniqueName = pickUniqueInlineReferenceName(nameMap, baseName);
+          const refId = makeDeclId(universeName, 'reference', `${id}:${uniqueName}`);
+          refModel.id = refId;
+          refModel.name = uniqueName;
+          refModel.scopeDeclId = id;
+          references.set(refId, refModel);
+          if (!node.references) {
+            node.references = [];
+          }
+          node.references.push(refId);
+        }
+      }
+
       // Extract ordering block (applied after all nodes are built)
       const orderingBlocks = (decl.body || []).filter(b => b.kind === 'ordering');
       if (orderingBlocks.length > 0) {
@@ -1230,6 +1362,8 @@ function buildNodes(boundDecls, schemas, fileData) {
       if (noteBlock) {
         ref.note = buildTextBlock(noteBlock, sourceText);
       }
+
+      ref.scopeDeclId = info.parentDeclId || id;
       
       references.set(id, ref);
     }
@@ -1274,13 +1408,10 @@ function resolveReferenceModels(boundDecls, references, repositories, index, par
   const diagnostics = [];
   const unknownRepoCounts = new Map();
 
-  for (const bound of boundDecls) {
-    const { id, info } = bound;
-    if (info.kindResolved !== 'reference') continue;
-    const ref = references.get(id);
-    if (!ref) continue;
-
-    const displayName = ref.name || info.name || 'unnamed reference';
+  for (const ref of references.values()) {
+    const scopeDeclId = ref.scopeDeclId || ref.id;
+    const source = ref.source;
+    const displayName = ref.name || 'unnamed reference';
     const hasUrl = Array.isArray(ref.urls) && ref.urls.length > 0;
     const repositoryName = ref.repositoryName;
     let urls = hasUrl ? [...ref.urls] : [];
@@ -1290,19 +1421,19 @@ function resolveReferenceModels(boundDecls, references, repositories, index, par
       diagnostics.push({
         severity: 'error',
         message: `Reference "${displayName}" cannot include both url { ... } and in <Repository>`,
-        source: info.span,
+        source,
       });
     }
 
     if (!hasUrl && repositoryName) {
       const pathSegments = repositoryName.split('.');
       if (pathSegments.length === 1) {
-        const resolved = resolveUnqualified(pathSegments[0], id, index, parentMap, info.span);
+        const resolved = resolveUnqualified(pathSegments[0], scopeDeclId, index, parentMap, source);
         if (resolved.ambiguous) {
           diagnostics.push({
             severity: 'error',
             message: `Ambiguous repository "${repositoryName}" - use qualified path`,
-            source: info.span,
+            source,
           });
         } else if (resolved.declId) {
           const repo = repositories.get(resolved.declId);
@@ -1310,13 +1441,13 @@ function resolveReferenceModels(boundDecls, references, repositories, index, par
             diagnostics.push({
               severity: 'error',
               message: `Reference "${displayName}" uses "${repositoryName}" which is not a repository`,
-              source: info.span,
+              source,
             });
           } else if (!repo.url) {
             diagnostics.push({
               severity: 'error',
               message: `Repository "${repo.name}" is missing url { '...' }`,
-              source: info.span,
+              source,
             });
           } else {
             repositoryRef = repo.id;
@@ -1326,7 +1457,7 @@ function resolveReferenceModels(boundDecls, references, repositories, index, par
               diagnostics.push({
                 severity: 'error',
                 message: `Reference "${displayName}" has an empty paths block`,
-                source: info.span,
+                source,
               });
             } else {
               urls = [repo.url];
@@ -1335,29 +1466,29 @@ function resolveReferenceModels(boundDecls, references, repositories, index, par
         } else {
           const entry = unknownRepoCounts.get(repositoryName) || {
             count: 0,
-            source: info.span,
+            source,
           };
           entry.count += 1;
-          if (!entry.source && info.span) {
-            entry.source = info.span;
+          if (!entry.source && source) {
+            entry.source = source;
           }
           unknownRepoCounts.set(repositoryName, entry);
         }
       } else {
-        const resolved = resolveQualified(pathSegments, index, info.span);
+        const resolved = resolveQualified(pathSegments, index, source);
         if (resolved.declId) {
           const repo = repositories.get(resolved.declId);
           if (!repo) {
             diagnostics.push({
               severity: 'error',
               message: `Reference "${displayName}" uses "${repositoryName}" which is not a repository`,
-              source: info.span,
+              source,
             });
           } else if (!repo.url) {
             diagnostics.push({
               severity: 'error',
               message: `Repository "${repo.name}" is missing url { '...' }`,
-              source: info.span,
+              source,
             });
           } else {
             repositoryRef = repo.id;
@@ -1367,7 +1498,7 @@ function resolveReferenceModels(boundDecls, references, repositories, index, par
               diagnostics.push({
                 severity: 'error',
                 message: `Reference "${displayName}" has an empty paths block`,
-                source: info.span,
+                source,
               });
             } else {
               urls = [repo.url];
@@ -1376,11 +1507,11 @@ function resolveReferenceModels(boundDecls, references, repositories, index, par
         } else {
           const entry = unknownRepoCounts.get(repositoryName) || {
             count: 0,
-            source: info.span,
+            source,
           };
           entry.count += 1;
-          if (!entry.source && info.span) {
-            entry.source = info.span;
+          if (!entry.source && source) {
+            entry.source = source;
           }
           unknownRepoCounts.set(repositoryName, entry);
         }
@@ -1391,7 +1522,7 @@ function resolveReferenceModels(boundDecls, references, repositories, index, par
       diagnostics.push({
         severity: 'error',
         message: `Reference "${displayName}" must have url { ... } or declared as reference ${displayName} in <Repository>`,
-        source: info.span,
+        source,
       });
     }
 
@@ -1430,6 +1561,7 @@ function resolveReferenceAttachments(nodes, references, index, parentMap) {
   for (const node of nodes.values()) {
     if (!node._pendingReferences) continue;
     const resolvedReferences = [];
+    const existingReferences = Array.isArray(node.references) ? node.references : [];
 
     for (const item of node._pendingReferences) {
       const name = item.name;
@@ -1465,7 +1597,8 @@ function resolveReferenceAttachments(nodes, references, index, parentMap) {
       }
     }
 
-    node.references = resolvedReferences;
+    const combined = [...existingReferences, ...resolvedReferences];
+    node.references = Array.from(new Set(combined));
     delete node._pendingReferences;
   }
 
@@ -1789,7 +1922,12 @@ export function buildGraph(fileAstOrFileAsts, options) {
   
   // 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);
+  const { nodes, repositories, references, diagnostics: nodeDiags } = buildNodes(
+    boundDecls,
+    schemas,
+    fileData,
+    universeName,
+  );
 
   // Resolve reference models and attachments
   addImplicitReferenceAttachments(boundDecls, nodes);

package/src/universe/universe.prose

@@ -144,6 +144,10 @@ anthology AnthologyWithRelationships in CanonicalUniverse {
   }
 }
 
+reference GlobalReference {
+  url { 'https://github.com/owner/repository/tree/main' }
+}
+
 anthology ExternalAnthology in CanonicalUniverse {
   aliases {
     bookAlias { book }
@@ -160,15 +164,33 @@ anthology ExternalAnthology in CanonicalUniverse {
   }
 
   chapterAlias ExternalChapterAlias in BookAlias { }
+
+  references { GlobalReference }
+}
+
+series ExternalSeries in ExternalAnthology {
+  references { GlobalReference }
+
+  reference { url { 'http://localhost:6336/external-series.md' } }
+}
+
+book ExternalBook in ExternalSeries {
+  references { GlobalReference }
+
+  reference { url { 'http://localhost:6336/external-book.md' } }
 }
 
-series ExternalSeries in ExternalAnthology { }
+chapter ExternalChapter in ExternalBook {
+  references { GlobalReference }
 
-book ExternalBook in ExternalSeries { }
+  reference { url { 'http://localhost:6336/external-chapter.md' } }
+}
 
-chapter ExternalChapter in ExternalBook { }
+concept ExternalConcept in ExternalChapter {
+  references { GlobalReference }
 
-concept ExternalConcept in ExternalChapter { }
+  reference { url { 'http://localhost:6336/external-concept.md' } }
+}
 
 repository ExternalRepository in CanonicalUniverse {
   title { GitHub }