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

package/src/ir.js

@@ -57,10 +57,12 @@
  * @typedef {Object} NodeModel
  * @property {NodeId} id - Node identifier
  * @property {'universe' | 'anthology' | 'series' | 'book' | 'chapter' | 'concept' | 'relates'} kind - Node kind (declaration kind, not contract kind)
+ * @property {string} [spelledKind] - Kind token as written (may be alias)
  * @property {string} name - Node name
  * @property {NodeId} [parent] - Tree parent node ID
  * @property {NodeId[]} children - Child node IDs
  * @property {NodeId} [container] - Container node ID (for book/chapter "in" relationship; always set for book/chapter nodes when resolved)
+ * @property {Record<string, string>} [aliases] - Alias mappings declared in this scope
  * @property {string[]} [ordering] - Optional ordering of direct children by identifier name
  * @property {TextBlock} [describe] - Describe block if present
  * @property {UnknownBlock[]} [unknownBlocks] - Unknown blocks if any
@@ -70,7 +72,7 @@
  * @property {NodeId[]} [endpoints] - Endpoint node IDs (for relates nodes)
  * @property {string[]} [unresolvedEndpoints] - Unresolved endpoint names (for relates nodes)
  * @property {Record<string, FromView>} [from] - From blocks keyed by endpoint node ID (for relates nodes)
- * @property {{ values: string[], source: SourceSpan }} [relationships] - Top-level relationships block (for relates nodes)
+ * @property {{ values: string[], source: SourceSpan } | { entries: Array<{ relationshipId: string, targets: Array<{ id: string, metadata?: TextBlock }> }>, source: SourceSpan }} [relationships] - Relationships block (for relates nodes: legacy string values; for concept nodes: new entry-based syntax)
  */
 
 /**
@@ -83,6 +85,27 @@
  * @property {SourceSpan} source - Source span
  */
 
+/**
+ * @typedef {Object} EdgeAssertedModel
+ * @property {string} from - Source node ID
+ * @property {string} via - Relationship ID used (e.g., "ledBy", "owns")
+ * @property {string} to - Target node ID
+ * @property {TextBlock} [meta] - Per-edge metadata (from target describe block)
+ * @property {SourceSpan} source - Source location
+ * @property {boolean} [bidirectional] - Whether this edge is bidirectional (for relates blocks)
+ */
+
+/**
+ * @typedef {Object} NormalizedEdgeModel
+ * @property {string} from - Source node ID
+ * @property {string} via - Relationship ID
+ * @property {string} to - Target node ID
+ * @property {boolean} asserted - Whether this edge was explicitly authored
+ * @property {SourceSpan[]} sourceRefs - Array of source locations (for inferred edges, points to asserted edge)
+ * @property {TextBlock} [meta] - Per-edge metadata
+ * @property {boolean} [bidirectional] - Whether this edge is bidirectional (for relates blocks)
+ */
+
 /**
  * @typedef {Object} UniverseModel
  * @property {string} name - Universe name
@@ -123,16 +146,31 @@
  * @property {SourceSpan} source - Source span
  */
 
+/**
+ * @typedef {Object} RelationshipDeclModel
+ * @property {'symmetric' | 'paired'} type - Type of relationship
+ * @property {string} [id] - Identifier for symmetric relationships
+ * @property {string} [leftId] - Left identifier for paired relationships
+ * @property {string} [rightId] - Right identifier for paired relationships
+ * @property {TextBlock} [describe] - Optional pair-level describe block
+ * @property {string} [label] - Optional label for symmetric relationships
+ * @property {Record<string, { label?: string, describe?: TextBlock }>} [from] - Per-side metadata for paired relationships
+ * @property {SourceSpan} source - Source span
+ */
+
 /**
  * @typedef {Object} UniverseGraph
  * @property {number} version - Graph version (1)
  * @property {Record<string, UniverseModel>} universes - Universes keyed by name
  * @property {Record<NodeId, NodeModel>} nodes - Nodes keyed by ID
- * @property {Record<EdgeId, EdgeModel>} edges - Edges keyed by ID
+ * @property {Record<EdgeId, EdgeModel> | NormalizedEdgeModel[]} [edges] - Either legacy relates edges object format OR normalized edges array (after normalization)
+ * @property {EdgeAssertedModel[]} [edgesAsserted] - Asserted edges from both relates nodes and relationships blocks
+ * @property {Record<EdgeId, EdgeModel>} [edgesByRelates] - Relates edges in object format (preserved from original edges before normalization)
  * @property {Diagnostic[]} diagnostics - Diagnostics
  * @property {Record<string, RepositoryModel>} [repositories] - Repositories by ID
  * @property {Record<string, ReferenceModel>} [references] - References by ID
  * @property {string} [generatedAt] - ISO timestamp when manifest was generated
  * @property {Record<string, Record<string, NamedDocumentModel>>} [documentsByName] - Named documents by universe name, then by document name
+ * @property {Record<string, Record<string, RelationshipDeclModel>>} [relationshipDecls] - Relationship declarations by universe name, then by relationship ID
  */