0029: Node capabilities are role interfaces, and pins carry roles that decide purity
Status
Accepted (2026-10-16, P3 spec specs/006-editor-extension-host/, research R9 and R11; lands in sub-phase B). It builds on
ADR-0025, whose generator sets the roles.
Context
- The editor decided what a node could do by testing its class: the +/- pin buttons for
MakeArrayNode,MethodEntryNode,ReturnNodeandClassReturnNode, the overload list forCallMethodNode,ConstructorNodeandMakeArrayNode, editable pin names for entry and return nodes, and the inspector target for call and variable nodes. An extension node could not take part in any of these. - Whether a node could be made pure was a per-class override of
CanSetPure. Each override restated the same idea (the node produces a value somebody can need), and a call to avoidmethod with anoutparameter was refused although its output is exactly such a value. - An
outorrefparameter was only an input pin. Its value after the call could not be wired to anything.
Decision
- Role interfaces.
IPinListEditor(the +/- buttons and the edit they run),IOverloadableNode(the current overload and the switch to another),IPinNameEditor(which pins the user renames) and the existingIMemberReferencingNode(which member the node names) are the capabilities. The editor asks for a role, never for a class. The built-in nodes implement the interfaces explicitly, so their own surface does not grow. The list of overloads still comes from the reflection provider in the editor; the header role keeps falling back to the node's visual kind by convention. - Pin roles.
PinRole(Argument,Target,Result,OutParam,Exception) is a property of every pin. The generator sets it from[Pin(Role = ...)]on a data pin where the convention cannot tell;CallMethodNodesets it for its dynamic pins:Target,Resultfor each return value,OutParamfor eachoutorrefparameter (input and output),Exceptionfor the pin that exists while the catch pin is connected. - One purity rule.
Node.CanSetPureis true exactly when an output data pin has theResultorOutParamrole. TheExceptionpin never counts. The per-class overrides of calls, constructors, ternaries and casts are gone; those kinds mark their value pinResult.AwaitNodekeeps its override because its result pin comes and goes with the task type. outandrefoutput pins. Everyoutandrefparameter of a call also gets an output data pin, after the return values, keyedout.data.<parameterName>and carrying the parameter's value after the call. The translator assigns it from the variable passed to the parameter. Anoutorrefinput with no variable connected stays a translation error (NPT008), now decided from the pin role. Constructors keep their input-only check.- The file format stays version 1. The new pins are derived from the method specifier when a graph loads, so no stored
field is added and no stored pin key changes. A graph that wired nothing to the new pins saves byte-identical. The graphs
whose generated C# changes are those that call a method with an
outorrefparameter: the call gains one assignment after it.
Consequences
- An extension node gets the +/- buttons, editable names and the inspector link by implementing a role, with no change
to the editor. The overload button does not follow yet:
IOverloadableNodecan change an overload but cannot list them, so the editor builds the list only forMakeArrayNode,CallMethodNodeandConstructorNode. A member that lists the overloads comes with the settled shape of the role interfaces. IPinListEditor,IOverloadableNodeandIPinNameEditorare public Core API but not yet on research R16's stable list and under no NPXE id: their shape (objectoverloads, EnglishAddPinLabelstrings ahead ofLocalizedText) is unsettled. They are classified, or changed, in the C1 publish-gate review.- A void method with an
outparameter can be made pure, and its output can be wired onward. - A pure call with
outparameters runs when a consumer needs one of its outputs, like any other pure node. CallMethodNode.ReturnValuePinsnow means theResultpins only; callers that wanted every output readOutputDataPins.- The role of a pin is not stored in a graph; a node kind must set it the same way every time.