Reconcile overlap between relationships and hierarchy

[mindsocket]

Problem

hierarchy and relationships in the schema metadata serve overlapping purposes but are implemented separately, creating complexity and inconsistency.

A hierarchy level is conceptually a relationship with:

• Structural ordering (position in the type chain)
• A resolvedParents resolution phase (post-parse link following)
• Optional selfRef/selfRefField for same-type parent links

Relationships have:

• Embedding format hints (heading, list, table, page)
• Matchers for heading text
• fieldOn to control which side holds the link

Both support field, fieldOn, and multi. But hierarchy goes through resolveHierarchyEdges() post-parse, while relationships are resolved inline during extractEmbeddedNodes(). This split means:

• Hierarchy nodes can't use heading/list/table embedding patterns
• Relationships don't get resolvedParents — making cross-node queries harder
• parse-embedded has to maintain separate logic paths for hierarchy-typed nodes vs. relationship-typed nodes, even though they often appear in the same markdown structure

What to investigate / decide

1. Can hierarchy be modelled as a constrained subset of relationships? — Specifically, can we add ordering + resolvedParents semantics to relationships without losing the distinction that hierarchy imposes (strict type chain, depth inference, no arbitrary embedding)?

2. Should resolvedParents apply to relationship-typed nodes too? — If a node is embedded via a relationship (e.g. Application inside a Solution), it would be useful to have resolvedParents populated, just as hierarchy nodes do.

3. Where should the resolution phase live? — Currently resolveHierarchyEdges() is a separate post-parse pass only for hierarchy. If relationships also needed resolution, this pass would need to generalise.

4. What stays distinct? — Hierarchy's depth-based type inference and structural ordering are specific to the tree metaphor. These probably shouldn't bleed into general relationships. The goal is to reduce duplicated logic, not to collapse the concepts entirely.

Expected outcome

• Reduced duplication between resolveHierarchyEdges, validate-hierarchy, and the relationship parsing/validation code
• A clearer mental model: hierarchy is the primary type chain; relationships are lateral or embedded associations, some of which also warrant parent resolution
• parse-embedded can use a single traversal path that handles both, gated by which metadata is active

Related

• Companion issue: Refactor parse-embedded to use clean mdast traversal with explicit signal tracking
• This is likely a blocker for that refactor — the traversal design depends on how these two concepts relate

[mindsocket]

Decisions made (partial resolution)

What was done

Unified resolvedParents for both hierarchy and relationship edges.
resolveHierarchyEdges was generalised into resolveGraphEdges, which now handles both hierarchy levels and relationship definitions in a single post-parse pass. Relationship-typed nodes now get resolvedParents populated, resolving question 2.

ResolvedParentRef carries a source field.
Each entry in resolvedParents now includes source: 'hierarchy' | 'relationship', allowing downstream consumers (validation, tree rendering, Miro sync) to route edges correctly without re-inspecting the schema.

Downstream consumers updated accordingly:

• validate-hierarchy explicitly skips source: 'relationship' edges (routes to ref validation instead)
• classifyNodes filters to source: 'hierarchy' for tree structure
• show and diagram use classifyNodes, so correctly show hierarchy-only structure
• miro-sync connector building and cache hashing now filter to source: 'hierarchy'

multi → multiple rename fixed across all schemas in configured spaces.

$metadata docs and schema-authoring reference updated to reflect the unified graph model and ResolvedParentRef shape.

---

Still unresolved

Hierarchy nodes can't use heading/list/table embedding patterns — the original limitation stands. Hierarchy-typed nodes are still resolved in a separate phase from relationship-typed nodes within extractEmbeddedNodes. The parsing logic paths remain separate. This is the core structural problem described in the issue and is now explicitly tracked in #54.

Question 1 — Can hierarchy be modelled as a constrained subset of relationships? — Not pursued. The approach taken was to unify the resolution phase while keeping the metadata concepts distinct. Whether hierarchy levels could eventually be expressed as relationships with ordering constraints remains open.

Question 4 — What stays distinct? — Depth-based type inference (space-on-a-page) and structural ordering remain hierarchy-only. These were not affected by this work.

parse-embedded still has separate traversal logic for hierarchy vs relationship nodes. The unified resolution phase reduces one layer of duplication, but the traversal itself is not yet clean. That work belongs in #54.