RFC: Specs as executable visual diagrams — researcher-first Spec UI #1649

Core idea

Every T27 specification should have a first-class visual representation. A spec is not merely text or source code: it defines inputs, outputs, constraints, and an algorithm/flow. T27 tooling should render that structure as an interactive, inspectable diagram made from reusable widgets.

The goal is a researcher- and engineer-first environment where opening a spec/file shows both its textual definition and a visual model of its architecture and behavior. Users can trace input data through an algorithm, inspect each stage, see dependencies and outputs, and connect the diagram to tests, benchmarks, and research evidence.

Product principle

One specification → one synchronized source model → multiple views. The visual view must derive from the actual spec/AST/IR and metadata, not a hand-maintained drawing that can drift away from implementation. If a spec does not expose enough semantic information to produce a faithful diagram, show an explicit unknown/not-represented state rather than inventing an algorithm.

User experience

• Open any supported spec and switch between source, architecture diagram, data-flow view, dependency graph, test/benchmark view, and documentation.
• Generate an initial diagram automatically from the spec.
• Select a node to inspect inputs, outputs, parameters, invariants, source span, dependencies, tests and implementation mapping.
• Trace data from inputs through transformations and branches to outputs.
• Expand/collapse nested functions, modules and sub-specifications.
• Use widgets for types, control flow, data flow, memory/compute cost where known, test coverage, benchmark measurements, provenance and unresolved questions.
• Compare spec versions visually and highlight changed nodes/edges.
• Keep diagram, source and metadata linked bidirectionally where mappings are available.
• Let researchers add annotations, hypotheses and evidence without silently modifying the canonical spec.
• Support saved perspectives for compiler engineers, hardware engineers, model researchers, reviewers and educators.
• Export diagrams and reports as stable artifacts for papers, reviews and issue discussions.

Graph model

Define a versioned intermediate graph schema with typed nodes and edges.

Candidate node types: spec/module/function/algorithm step; input/output/parameter/constant; type/numeric format/data structure; branch/loop/state transition; transformation/operator/kernel; API/external dependency/service; test/invariant/assertion/oracle; benchmark/measurement/hardware target; dataset/paper/citation/evidence; unknown or opaque implementation region.

Candidate edge types: data flow; control flow; calls/depends on; produces/consumes; constrains/validates; tested by; measured by; implemented by; derived from/cited by.

Preserve source locations and provenance for every inferred node/edge where possible.

Parsing and inference levels

1. Exact: information explicitly present in the spec AST/IR.
2. Derived: safely inferred from known syntax, symbol resolution and type information.
3. Suggested: AI-generated explanation or possible architecture, visibly labelled as a suggestion and linked to supporting source ranges.
4. Unknown: cannot be reliably determined from available source.

Never present a model-generated guess visually as a verified property of the program.

Architecture

• Parser/adapter for each supported spec language and version.
• Canonical graph IR, versioned and validated.
• Layout/rendering engine independent of language frontend.
• Widget registry for node inspectors and auxiliary views.
• Bidirectional source mapping.
• Diff engine for revisions.
• Connectors to tests, build results, benchmarks, repositories, papers and datasets.
• Optional agent assistant that explains selected nodes, proposes missing tests, or suggests alternative architectures while separating suggestions from verified facts.
• Persisted researcher workspaces and role-specific dashboards.

Research / engineering widgets

• Input/output contract
• Algorithm and control-flow diagram
• Data-flow trace
• Type and numeric-format inspector
• Dependency graph
• Source and symbol inspector
• Test/oracle status
• Benchmark chart and raw-run provenance
• Complexity/cost estimates, separating static estimates from measured results
• CPU/FPGA/hardware mapping
• Version diff
• Paper/dataset/citation links
• Assumptions, open questions and reviewer annotations

Initial scope

• Audit specs/numeric/gf16.t27 as the pilot alongside existing parser/AST/IR support in gHashTag/t27.
• Determine exactly which semantic details are available from parsing today.
• Produce a sample graph for GF16 with explicit exact/derived/suggested labels.
• Build a read-only diagram viewer with source-node linking and inspectors before full visual editing.
• Add a second pilot spec only after the graph schema works on GF16 and a structurally different example.
• Integrate with the T27F dashboard/widget engine rather than creating a separate incompatible UI stack.

Acceptance criteria

• Opening the pilot spec exposes source and diagram views based on the same canonical model.
• Every displayed algorithm node links to a source span or is explicitly labelled inferred/suggested/unknown.
• Inputs and outputs can be traced through the available graph.
• Selecting a node shows contracts, types, dependencies and associated tests where those facts exist.
• Graph/source navigation works in both directions where mappings are available.
• Diagram generation is deterministic for a fixed source version and toolchain.
• Spec changes produce a meaningful graph diff.
• Tests cover graph schema validation, source mappings, uncertainty labels and malformed/partial specs.
• No unsupported claim of complete algorithm visualization when the language or parser lacks the required semantic information.

Relationship to existing work

• T27F visual application engine: EPIC: T27F — Native generative UI and visual application engine #1648
• Widget-based customizable dashboards: RFC: Widget-based customizable dashboards for Trinity / T27 Desktop OS #1647
• GF16 conformance pilot is the first candidate spec.

Deliverables

• Current AST/IR capability audit for .t27 specs.
• Versioned canonical graph schema.
• UX sketches and interaction model.
• GF16 pilot diagram with source mapping.
• Prototype viewer and widget inspectors.
• Test plan, deterministic fixtures and extension guide for future spec-language adapters.

Status

This RFC defines the target and pilot; it does not claim that the visualizer already exists.