RFD-0026 — Living diagrams — diagram blocks as graduated language extension

Question

Ontology engineers think visually. UML-style class diagrams, state machine diagrams, dependency graphs — these are how the domain reads. Should Argon support them, and if so, how does the visualization stay in sync with the source-of-truth declarations?

Decision

Text is truth, visuals are lenses. The authoritative representation is the text source. Diagrams are derived views — generated from the source, regenerated when the source changes. There is no diagram-first modeling surface where the diagram is canonical and text is generated.

diagram blocks are first-class language items. A diagram block declares a view: which concepts to include, which relations to render, which layout algorithm to apply, which metadata to surface. The block evaluates against the current source state and produces SVG / PNG / PDF output.

Diagram blocks compose with the rest of the language. The same expression grammar (RFD-0005) selects which concepts and relations to include. Filter expressions, aggregate over the diagram’s contents, mark concepts with metatype-derived styling — all use the standard expression vocabulary.

Per-diagram layout selection. Sugiyama-style hierarchical layout for taxonomies; force-directed for relation-dense graphs. The block declares the layout algorithm; future algorithms register without changing the block grammar.

Rationale

Diagram-first modeling drifts. Tools that treat the diagram as canonical (Visio, Enterprise Architect, some OntoUML editors) accumulate inconsistencies: the visual layer encodes information the underlying model doesn’t capture, or vice versa. Source-of-truth-as-text means the diagram cannot disagree with the model — it’s regenerated.

Diagrams as language items, not external configuration. A diagram block lives in the same source file as the concepts it visualizes. A change to the concept structure that breaks the diagram surfaces immediately at compile time, not when the diagram regenerates next week.

Graduated extension. A simple diagram block just lists concepts: diagram concepts { Person, Organization }. A complex one filters, aggregates, applies styling rules driven by metatype membership, composes with patterns. The simple case is approachable; the complex case is expressible in the same grammar.

Layout as a parameter, not the language. Different visualizations need different layouts. Hardcoding one layout would have constrained the language to one rendering model. Letting the block declare the layout means new algorithms (graphviz-style, custom application-specific) plug in without grammar changes.

Consequences

• diagram is a reserved item kind with its own AST node and Core IR variant.
• diagram blocks evaluate during compile, producing renderable artifacts as build outputs.
• Layout algorithms ship in the compiler core (Sugiyama, force-directed) with a registration seam for additions.
• Diagrams compose with where clauses and aggregates for selecting contents.
• Editor surfaces (LSP InfoView, vscode extension) render diagram blocks live during editing.