Unify hierarchy and relationship edges into a single labelled graph

[mindsocket]

Summary

• Generalises resolveHierarchyEdges → resolveGraphEdges to handle both hierarchy levels and relationship definitions in a single post-parse pass
• ResolvedParentRef gains source: 'hierarchy' | 'relationship' so downstream consumers can route edges without re-inspecting the schema
• validate-hierarchy → validate-graph, with explicit source filtering (hierarchy → structural checks, relationship → ref checks)
• classifyNodes, show, diagram, Miro sync all filter to source: 'hierarchy' for tree/structural purposes
• Fixes multi → multiple rename in metadata contract and all configured space schemas
• Docs updated throughout: concepts (unified graph section), schemas reference, schema-authoring, architecture boundary table
• Repro test replaced with permanent source-aware regression tests

What's still open (tracked in #56 / #54)

• Hierarchy nodes still can't use heading/list/table embedding patterns — parse-embedded still has separate traversal logic for hierarchy vs relationship nodes
• The parse-embedded refactor (Refactor parse-embedded to use clean mdast traversal with explicit signal tracking #54) and remaining Reconcile overlap between relationships and hierarchy #56 work will be tackled together in a follow-up

Test plan

• bun run test — 207 tests pass
• bun run test:smoke — validate all configured spaces (pre-existing failures unaffected)
• Review resolvedParents output via dump on a space with relationships to confirm source field is correct
• Verify Miro sync only creates connectors for hierarchy edges (not relationship edges)

Closes part of #56

[claude]

Claude finished @mindsocket's task in 1m 34s —— View job

---

Code Review: PR #57 - Unify hierarchy and relationship edges into a single labelled graph

Overall Assessment: ✅ APPROVED with minor suggestions

This is a well-executed refactoring that unifies the hierarchy and relationship edge resolution into a single, coherent graph model. The architectural decisions are sound, the implementation is clean, and the test coverage is excellent.

---

✅ Strengths

1. Clean Architecture

• The source: 'hierarchy' | 'relationship' field on ResolvedParentRef is an elegant solution that lets downstream consumers filter edges without re-inspecting the schema
• resolveGraphEdges successfully generalizes the previous resolveHierarchyEdges while maintaining clarity
• The separation of concerns in validateGraph is excellent: hierarchy edges → structural checks, relationship edges → reference checks

2. Comprehensive Test Coverage

• All 207 tests pass ✅
• New tests in resolve-hierarchy-edges.test.ts thoroughly cover the source field behavior
• Tests verify both hierarchy and relationship edge resolution with proper source attribution
• Edge cases like selfRefField, fieldOn: 'parent', and mixed hierarchies are well-covered

3. Thoughtful Consumer Updates

• classifyNodes correctly filters to source: 'hierarchy' for tree/structural purposes (src/util/graph-helpers.ts:47)
• show, diagram commands properly filter to hierarchy edges only
• Miro sync correctly filters connectors to hierarchy edges (src/integrations/miro/sync.ts:329)
• Validation command properly routes different edge types

4. Good Documentation Updates

• docs/concepts.md has a comprehensive new "Graph edges" section explaining the unified model
• The ResolvedParentRef structure is well-documented with clear field descriptions
• Architecture and schema-authoring docs updated appropriately

---

🔍 Issues Found

Minor: Stray Statement

• src/read/read-space.ts:144: There's a stray resolveGraphEdges; statement that does nothing. This appears to be an accidental line leftover from editing.
  Fix this →

---

💡 Suggestions (Optional)

1. Type Safety
The source field on ResolvedParentRef is a string union. Consider using a const assertion or enum for better type safety if this pattern grows:

export type EdgeSource = 'hierarchy' | 'relationship';
export interface ResolvedParentRef {
  source: EdgeSource;
  // ...
}

2. Documentation Enhancement
Consider adding a visual diagram to docs/concepts.md showing how hierarchy and relationship edges both flow into the unified resolvedParents array, similar to the existing space parsing diagram.

---

📊 Test Results

• ✅ Unit Tests: 207/207 passing
• ✅ Coverage: New source field behavior thoroughly tested
• ✅ Edge Cases: selfRefField, fieldOn: 'parent', mixed hierarchies all covered

---

🎯 Summary

This refactoring successfully unifies the edge resolution model while maintaining backward compatibility for all consumers. The addition of the source field is a clean, extensible solution that enables proper filtering without sacrificing performance or clarity.

Recommendation: Merge after addressing the minor stray statement issue. The overall implementation is solid and ready for production.