wirely 0.1.2__tar.gz → 0.1.3__tar.gz

{wirely-0.1.2 → wirely-0.1.3}/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.1.3 - 2026-10-12
+
+### Breaking changes and migration
+
+#### Schedule and Timer namespaces
+
+Replace `Time` with `Schedule` for `IsInDailyInterval`, `TriggerAt`,
+`TimeOfDayMinute`, and `IsValidDailyInterval`, and with `Timer` for
+`DebounceStable` and `MonotonicTimeReached`.
+
+### Added
+
+- `Timer.MonotonicTimestamp` emits the step's monotonic time while an input
+  event is present.
+- Bitwise operators `&`, `|`, `^`, `!`, `<<`, and `>>` for integers.
+- Procedure ports can be declared with a type and wired with `connect`.
+  Refer to a port as `procedure.port`, also in reference ports of other
+  procedures:
+
+  ```wirely
+  procedure invert
+    depends on value: value boolean
+    produces inverted: value boolean
+  {
+    inverted = !value;
+  }
+  connect default input -> invert.value;
+  connect invert.inverted -> default output;
+  ```
+- Connections can target temporaries and state; state takes its value from
+  a procedure output port. Reference output ports can target child inputs.
+- `wirely edit` edits programs as source text and as diagrams, kept in
+  sync. `wirely export-image` draws a diagram as a PDF or PNG file. Install
+  the `editor` extra to use them.
+
 ## 0.1.2 - 2026-10-10
 
 ### Breaking changes and migration
@@ -171,7 +206,7 @@ Replace integration-specific connector kinds in custom node declarations:
 | `two_n_device` | `resource TwoN.Device` |
 
 Custom libraries can declare their own opaque resources with
-`resource type Name;`. See [resource connectors](doc/language.md#opaque-resource-connectors).
+`resource type Name;`. See [resource connectors](doc/language.md#opaque-resource-ports).
 
 #### Runtime types
 

{wirely-0.1.2/wirely.egg-info → wirely-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wirely
-Version: 0.1.2
+Version: 0.1.3
 Summary: Node-based language and runtime for low-level home automation
 Author: Steffen Kieß
 License: MIT
@@ -23,6 +23,8 @@ Provides-Extra: graphviz
 Requires-Dist: graphviz>=0.20.1; extra == "graphviz"
 Provides-Extra: gpio
 Requires-Dist: gpiod<3,>=2.1; extra == "gpio"
+Provides-Extra: editor
+Requires-Dist: PySide6-Essentials>=6.8; extra == "editor"
 Provides-Extra: all
 Requires-Dist: wirely[gpio,graphviz,knx,mqtt,two-n]; extra == "all"
 Provides-Extra: test
@@ -79,8 +81,35 @@ python3 -m pip install 'wirely[two-n]'         # 2N devices
 python3 -m pip install 'wirely[graphviz]'      # show-graph
 python3 -m pip install 'wirely[gpio]'          # GPIO
 python3 -m pip install 'wirely[all]'           # all optional integrations
+python3 -m pip install 'wirely[editor]'        # graphical editor
 ```
 
+`wirely edit program.wrl` opens a program in a graphical editor with tabs
+for its source files and diagrams. Edits in either view update the other.
+Right-click a tab to split the view, move it to another pane, or detach it
+into a window. You can also drag tabs between panes, onto pane edges to
+split, or outside the editor to detach. Closing a detached window returns
+its tabs to the main window. Layouts last for the current session.
+A diagram is read-only while its source has syntax errors. In a diagram:
+
+- Drag a node to store its position in the source; right-click it and choose
+  Reset to Automatic Position to remove it again. Use View → Snap to Grid
+  to toggle snapping for all diagrams. A selected group snaps its movement
+  while keeping its relative positions.
+- Drag from a port to another port to connect them. Drag a connection away
+  from an input to move or remove it.
+- Press Delete to remove the selection and F2 to rename it.
+- Right-click the background to add nodes and declarations.
+- Double-click a node to open the diagram of its node type.
+- Press Ctrl+E to show the source of the selection, and Ctrl+Shift+E in the
+  source to show the element at the cursor in its diagram.
+
+`wirely export-image program.wrl -o diagram.pdf` draws the program diagram as
+the editor shows it, as a PDF or PNG file. Use `--scope Name` for the diagram
+of a node type and `--scale` for the PNG resolution. Diagrams use the DejaVu
+Sans font, or a fallback font if it is not installed. See
+[diagram layout](doc/diagram-layout.md) for how layouts are stored.
+
 The `test` extra adds dependencies used only by the test suite. Install
 `wirely[all,test]` to include both integrations and test dependencies.
 
@@ -92,7 +121,7 @@ checkout launchers:
 
 ```
 tools/setup-venv
-tools/wirely compile test/wrl/simple.wrl
+tools/wirely compile test/compiler/simple.wrl
 tools/run-tests
 ```
 
@@ -105,16 +134,16 @@ Pass test names to run a selection, and add `--timings` to list durations
 slowest first:
 
 ```
-tools/run-tests --timings unit/types unit/equality
+tools/run-tests --timings unit/types wrl/equality
 ```
 
 To check that compilation does not depend on declaration order, set
 `WIRELY_COMPILER_SHUFFLE_SEED` to an integer. The compiler then shuffles
-declarations, node parameters, struct literal fields, and procedure
-bindings with that seed; connections keep their relative order. Also set
-`WIRELY_COMPILER_SHUFFLE_LAYOUT=1` to shuffle struct fields and enum
-members, which changes serialization and enum default values. Negative
-tests may report different diagnostics in this mode.
+declarations, node parameters, struct literal fields, procedure ports,
+and `uses` bindings with that seed; connections keep their relative order.
+Also set `WIRELY_COMPILER_SHUFFLE_LAYOUT=1` to shuffle struct fields and
+enum members, which changes serialization and enum default values.
+Negative tests may report different diagnostics in this mode.
 
 ```
 WIRELY_COMPILER_SHUFFLE_SEED=1 tools/run-tests

{wirely-0.1.2 → wirely-0.1.3}/README.md

@@ -43,8 +43,35 @@ python3 -m pip install 'wirely[two-n]'         # 2N devices
 python3 -m pip install 'wirely[graphviz]'      # show-graph
 python3 -m pip install 'wirely[gpio]'          # GPIO
 python3 -m pip install 'wirely[all]'           # all optional integrations
+python3 -m pip install 'wirely[editor]'        # graphical editor
 ```
 
+`wirely edit program.wrl` opens a program in a graphical editor with tabs
+for its source files and diagrams. Edits in either view update the other.
+Right-click a tab to split the view, move it to another pane, or detach it
+into a window. You can also drag tabs between panes, onto pane edges to
+split, or outside the editor to detach. Closing a detached window returns
+its tabs to the main window. Layouts last for the current session.
+A diagram is read-only while its source has syntax errors. In a diagram:
+
+- Drag a node to store its position in the source; right-click it and choose
+  Reset to Automatic Position to remove it again. Use View → Snap to Grid
+  to toggle snapping for all diagrams. A selected group snaps its movement
+  while keeping its relative positions.
+- Drag from a port to another port to connect them. Drag a connection away
+  from an input to move or remove it.
+- Press Delete to remove the selection and F2 to rename it.
+- Right-click the background to add nodes and declarations.
+- Double-click a node to open the diagram of its node type.
+- Press Ctrl+E to show the source of the selection, and Ctrl+Shift+E in the
+  source to show the element at the cursor in its diagram.
+
+`wirely export-image program.wrl -o diagram.pdf` draws the program diagram as
+the editor shows it, as a PDF or PNG file. Use `--scope Name` for the diagram
+of a node type and `--scale` for the PNG resolution. Diagrams use the DejaVu
+Sans font, or a fallback font if it is not installed. See
+[diagram layout](doc/diagram-layout.md) for how layouts are stored.
+
 The `test` extra adds dependencies used only by the test suite. Install
 `wirely[all,test]` to include both integrations and test dependencies.
 
@@ -56,7 +83,7 @@ checkout launchers:
 
 ```
 tools/setup-venv
-tools/wirely compile test/wrl/simple.wrl
+tools/wirely compile test/compiler/simple.wrl
 tools/run-tests
 ```
 
@@ -69,16 +96,16 @@ Pass test names to run a selection, and add `--timings` to list durations
 slowest first:
 
 ```
-tools/run-tests --timings unit/types unit/equality
+tools/run-tests --timings unit/types wrl/equality
 ```
 
 To check that compilation does not depend on declaration order, set
 `WIRELY_COMPILER_SHUFFLE_SEED` to an integer. The compiler then shuffles
-declarations, node parameters, struct literal fields, and procedure
-bindings with that seed; connections keep their relative order. Also set
-`WIRELY_COMPILER_SHUFFLE_LAYOUT=1` to shuffle struct fields and enum
-members, which changes serialization and enum default values. Negative
-tests may report different diagnostics in this mode.
+declarations, node parameters, struct literal fields, procedure ports,
+and `uses` bindings with that seed; connections keep their relative order.
+Also set `WIRELY_COMPILER_SHUFFLE_LAYOUT=1` to shuffle struct fields and
+enum members, which changes serialization and enum default values.
+Negative tests may report different diagnostics in this mode.
 
 ```
 WIRELY_COMPILER_SHUFFLE_SEED=1 tools/run-tests

{wirely-0.1.2 → wirely-0.1.3}/doc/README.md

@@ -4,14 +4,18 @@ Wirely programs are graphs of typed nodes written in `.wrl` files. Start with
 the [language guide](language.md) to learn how to declare nodes and connect
 them. Then use the [library reference](libraries.md) to find the nodes supplied
 with Wirely. The [value type reference](value-types.md) describes the types
-used by parameters, connectors, and state.
+used by parameters, ports, and state.
 
 The [binary program format proposal](bytecode-format.md) describes program
 tables, value encodings, and optional debugging information.
 
 For `.wrl` formatting and naming, follow the
-[Wirely style guide](wirely-style.md).
+[Wirely style guide](wirely-style.md). The [diagram layout](diagram-layout.md)
+document defines how diagrams of programs are laid out and stored.
 
 To implement nodes and procedures in Python, use the
 [native Python implementation guide](native-python.md). For Python
 contributions, follow the [Python style guide](python-style.md).
+
+For compiler development, read the [compiler stages guide](compiler-stages.md).
+For test categories, execution, and authoring, read the [test guide](tests.md).

{wirely-0.1.2 → wirely-0.1.3}/doc/bytecode-format.md

@@ -95,13 +95,11 @@ their contents.
 | [`ResourceInterfaces`](#resourceinterfaces) | `ResourceInterface` | Table |
 | [`StaticBindings`](#staticbindings) | `StaticBinding` | Table |
 | [`ResourceInputs`](#resourceinputs) | `ResourceInput` | Table |
-| [`ResourceProviders`](#resourceproviders) | `ResourceProvider` | Table |
 | [`Stages`](#stages) | `Stage` | Table |
 | [`Procedures`](#procedures) | `Procedure` | Table |
 | [`NativeProcedures`](#nativeprocedures) | `NativeProcedure` | Table |
 | [`InputInterfaces`](#inputinterfaces) | `InputInterface` | Table |
 | [`ValueInputs`](#valueinputs) | `ValueInput` | Table |
-| [`InputSources`](#inputsources) | `InputSource` | Table |
 | [`Outputs`](#outputs) | `Output` | Table |
 | [`ProcedureBodies`](#procedurebodies) | `ProcedureBody` | Table |
 | [`NativeFunctions`](#nativefunctions) | `NativeFunction` | Table |
@@ -381,12 +379,12 @@ struct type Variable {
 ```
 
 Static values describe the resolved values bound by `uses` clauses of
-native procedures and initializers, and constants read by procedure
-bodies. Bindings and `const` operands reference these entries, which can
-be shared for equal typed values. Their data and referenced payloads are
-stored in `ProgramData`. Only values bound by `uses` clauses or read by
-procedure bodies are stored; node parameters, constants, and expressions
-supply those values.
+native procedures and initializers, constants read by procedure bodies,
+and parameters and constants connected to procedure inputs. Bindings,
+`const` operands, and static input sources reference these entries, which
+can be shared for equal typed values. Their data and referenced payloads
+are stored in `ProgramData`. Only values used in one of these ways are
+stored; node parameters, constants, and expressions supply those values.
 
 ### ProgramData
 
@@ -525,14 +523,11 @@ struct type ResourceInterface {
   Name: StringRef,
   // Qualified resource type name in Names, such as KNX.Bus.
   Type: StringRef,
-  // 0 = one provider, 1 = ordered provider list.
-  IsList: uint8,
 }
 ```
 
-Each range contains unique names in UTF-8 bytewise lexical order. Resource
-outputs have `IsList = 0`. Until resource outputs are named in the
-language, a node type's default output is named `default`.
+Each range contains unique names in UTF-8 bytewise lexical order.
+A node type's default resource output is named `default`.
 
 ### StaticBindings
 
@@ -555,27 +550,11 @@ bound option value.
 ### ResourceInputs
 
 ```wirely
-// Binds native state providers to one resource interface.
+// Binds one native state provider to one resource interface.
 // ResourceInputs table.
 struct type ResourceInput {
   // Index into ResourceInterfaces; the resource input being bound.
   Interface: Ref,
-  // Range into ResourceProviders.
-  Providers: Range,
-}
-```
-
-The interface belongs to the native state type's
-`ResourceInputInterfaces` range for construction or the native
-procedure's `ResourceInputInterfaces` range for procedure calls. An
-interface with `IsList = 0` has one provider; with `IsList = 1`, the
-providers form an ordered sequence, which can be empty.
-
-### ResourceProviders
-
-```wirely
-// One resource provided by a native state. ResourceProviders table.
-struct type ResourceProvider {
   // Index into NativeStates.
   NativeState: Ref,
   // Index within the provider type's ResourceOutputInterfaces range.
@@ -583,8 +562,10 @@ struct type ResourceProvider {
 }
 ```
 
-The provided resource has the type of the resource interface it is bound
-to.
+The interface belongs to the native state type's
+`ResourceInputInterfaces` range for construction or the native
+procedure's `ResourceInputInterfaces` range for procedure calls.
+Each input binds one provider with the resource type of that interface.
 
 ## Execution
 
@@ -674,8 +655,6 @@ duplicates.
 struct type InputInterface {
   // Input name in Names.
   Name: StringRef,
-  // 0 = one connection, 1 = ordered connection list.
-  IsList: uint8,
 }
 ```
 
@@ -684,35 +663,29 @@ Each range contains unique names in UTF-8 bytewise lexical order.
 ### ValueInputs
 
 ```wirely
-// Binds variable sources to one procedure input. ValueInputs table.
+// Binds one variable or static value to a procedure input.
+// ValueInputs table.
 struct type ValueInput {
   // Index into InputInterfaces; the input being bound. No entry for
   // procedure bodies.
   Interface: OptionalRef,
-  // Range into InputSources.
-  Sources: Range,
-}
-```
-
-The interface belongs to the native procedure's `InputInterfaces` range.
-An interface with `IsList = 0` has one source; with `IsList = 1`, the
-sources form an ordered sequence, which can be empty.
-
-### InputSources
-
-```wirely
-// One variable supplying a procedure input. InputSources table.
-struct type InputSource {
-  // Old state, new state, or temporaries.
+  // Old state, new state, temporaries, or static values.
   Bank: uint8,
-  // Index into StateVariables or Temporaries, selected by Bank.
+  // Index into StateVariables, Temporaries, or StaticValues, selected by
+  // Bank.
   Variable: Ref,
 }
 ```
 
+For native calls, the interface belongs to the native procedure's
+`InputInterfaces` range. Each value input binds exactly one source.
+Procedure body inputs follow dependency declaration order; multi value
+inputs expand into scalar inputs in connection order.
+
 An old-state input reads the step's old-state snapshot. A new-state input
 reads the state value written earlier in the step. A temporary input reads
-a temporary computed during the step.
+a temporary computed during the step. A static input reads a value from
+`ProgramData`.
 
 Old-state inputs compare the step's old-state snapshot with the snapshot
 read by the previous step, using the variable's value-type equality.
@@ -720,8 +693,9 @@ New-state inputs compare this step's new state with the step's old state,
 which the previous step produced. Temporary inputs compare this step's
 values with the previous step's cached values. A difference requires
 procedure execution. On the first step, procedures execute without
-previous values. Triggers and wakeups also require execution. A skipped
-procedure preserves its state and temporary outputs.
+previous values. Static inputs never change and are not compared.
+Triggers and wakeups also require execution. A skipped procedure preserves
+its state and temporary outputs.
 
 ### Outputs
 
@@ -777,6 +751,14 @@ The runtime matches the qualified names of native state types, native
 procedures, and native functions to native code, and binds interface names
 to static values, inputs, outputs, and resources. Linking also checks that
 each procedure's native state has the type its native procedure expects.
+
+The reserved linking name for a native procedure with multi value/event
+dependencies is `Namespace.BlockType:procedure.2.3.4`. The decimal suffixes
+are member counts in dependency declaration order, including zero counts;
+scalar and resource dependencies contribute no suffix. Native multi
+value/event specialization is not currently supported. Procedure debug
+symbols remain instance names such as `someblock:procedure`.
+
 Embedded adapters can retain numeric bindings and function pointers after
 linking. Native trigger names resolve to the same native procedure indices.
 
@@ -868,9 +850,12 @@ Each name below denotes a value operand except `field`, `offset`,
 | `MAKE_SOME destination, source` | Copy a value of type `T` into a destination of type `Option[T]` as `Some`. |
 | `GET_OPTION_VALUE destination, source` | Copy the value of `Some`, or assign the contained type's default for `None`. The destination has that contained type. |
 | `IS_SOME destination, source` | Assign a boolean indicating whether the option is `Some`. |
-| `NOT destination, source` | Negate a boolean. |
-| `AND destination, left, right` | Compute boolean conjunction. |
-| `OR destination, left, right` | Compute boolean disjunction. |
+| `NOT destination, source` | Complement an integer within its width, or negate a boolean. |
+| `AND destination, left, right` | Compute bitwise or Boolean conjunction. |
+| `OR destination, left, right` | Compute bitwise or Boolean disjunction. |
+| `XOR destination, left, right` | Compute bitwise or Boolean exclusive disjunction. |
+| `SHIFT_LEFT destination, value, shift_count` | Shift left, discarding outgoing bits and filling with zeros. |
+| `SHIFT_RIGHT destination, value, shift_count` | Shift right, extending the sign for signed integers and filling with zeros for unsigned integers. |
 | `EQUAL destination, left, right` | Compare same-type values for equality, assigning a boolean. |
 | `LESS destination, left, right` | Assign whether `left` orders before `right`. Both have the same integer type, or the same ordered built-in type. |
 | `ADD_WRAPPING`, `SUB_WRAPPING`, `MUL_WRAPPING` `destination, left, right` | Compute the integer result modulo 2^bits within the operand type's range. |
@@ -885,7 +870,12 @@ Each name below denotes a value operand except `field`, `offset`,
 | `CALL destination, function, count, arguments…` | Call a native function with `count` argument operands and assign its result. |
 | `RETURN` | End the procedure with its current output values. |
 
-`NOT`, `AND`, and `OR` require boolean operands and destinations.
+`NOT`, `AND`, `OR`, and `XOR` require matching integer or boolean sources
+and destinations. Binary operations evaluate both sources.
+For shifts, `value` and the destination share one integer type;
+`shift_count` is an ordinary `uint32` value operand. Counts at least the
+value's width produce zero, except that right-shifting a negative signed
+value produces minus one. Counts are not masked.
 Arithmetic sources share one integer type `T`. The destination has type
 `T`, or `Option[T]` for `_CHECKED` instructions. Division truncates toward
 zero, and the remainder has the dividend's sign.
@@ -970,7 +960,7 @@ same order:
 | --- | --- | --- |
 | `NodeSymbols` | `NativeStates` | Node path, such as `a.b` |
 | `StateVariableSymbols` | `StateVariables` | Variable path, such as `a.b.count` |
-| `TemporarySymbols` | `Temporaries` | Variable path, or for output storage the procedure symbol and output key joined by `.`, such as `a.b:run.output` |
+| `TemporarySymbols` | `Temporaries` | Procedure symbol and output port joined by `.`, such as `a.b:run.output` |
 | `ProcedureSymbols` | `Procedures` | Owning node path and procedure name joined by `:`, such as `a.b:run` |
 
 Symbols identify nodes, variables, and procedures in diagnostics and when
@@ -979,21 +969,22 @@ building [state transitions](#state-transitions).
 ### VariableAliases
 
 ```wirely
-// An alias referring to a state or temporary variable.
+// An alias referring to a state or temporary variable or a static value.
 // VariableAliases table.
 struct type VariableAlias {
   // Alias name in SymbolData.
   Name: StringRef,
-  // Old state, new state, or temporaries.
+  // Old state, new state, temporaries, or static values.
   Bank: uint8,
-  // Index into StateVariables or Temporaries, selected by Bank.
+  // Index into StateVariables, Temporaries, or StaticValues, selected by
+  // Bank.
   Variable: Ref,
 }
 ```
 
 Aliases map source names, including the inputs and outputs of nodes, to
-the variable that stores their value. They are sorted by UTF-8 name bytes.
-Multiple aliases can refer to one variable.
+the variable or static value that supplies their value. They are sorted by
+UTF-8 name bytes. Multiple aliases can refer to one variable.
 
 ### SymbolData
 
@@ -1073,8 +1064,8 @@ Bytes not referenced by any record are not checked. This includes bytes of
 
 Every reference fits its target: `Ref` and `OptionalRef` indices, ranges,
 `ByteRange` byte ranges, and `StringRef` byte ranges, whose bytes are valid
-UTF-8. Small enumerated fields such as `Bank` and `IsList` have listed
-values, and padding is zero.
+UTF-8. Small enumerated fields such as `Bank` have listed values, and
+padding is zero.
 
 ### Types and values
 
@@ -1096,7 +1087,8 @@ when lists share bytes.
 starts at or after the end of the previous one. Comparing each entry with
 its predecessor therefore shows that slots do not overlap and gives the
 buffer size. Their types, and those of locals, constant and immediate
-operands, and native function parameters and results, are runtime types.
+operands, static input sources and aliases, and native function
+parameters and results, are runtime types.
 
 ### Names and bindings
 
@@ -1104,11 +1096,11 @@ Sorting turns uniqueness into a comparison with the predecessor. This
 applies to ranges into `InterfaceNames`, `InputInterfaces`, and
 `ResourceInterfaces`, to `NativeStateTypes`, `NativeProcedures`, and
 `NativeFunctions`, and to aliases. Bindings refer to entries in the
-matching range of their native procedure or native state type, and their
-source and provider counts match `IsList`. A resource provider's output
-lies within its type's `ResourceOutputInterfaces` and has the resource
-type of the interface it is bound to. Each symbol table has as many
-entries as its target table.
+matching range of their native procedure or native state type.
+Each value input binds one source, and each resource input binds one
+provider. A resource provider's output lies within its type's
+`ResourceOutputInterfaces` and has the resource type of the interface it
+is bound to. Each symbol table has as many entries as its target table.
 
 ### Procedures and code
 

wirely-0.1.3/doc/compiler-stages.md

@@ -0,0 +1,112 @@
+# Compiler stages
+
+The compiler first builds graphs describing node types and their connections.
+It then uses those graphs to generate a runtime program. Use the Python API
+in two steps:
+
+- `wirely.compiler.compile_files()` reads `.wrl` files; `compile_strs()`
+  accepts filename/text pairs. Both return the graph of top-level
+  declarations, called the global graph, after resolving declarations,
+  connecting ports, and checking the graphs.
+- `wirely.compiler.program.compile()` takes that graph, evaluates each
+  instance's parameters, and generates a runtime program.
+
+Both parts report language errors through `on_diagnostic`, or print them
+when no callback is supplied, and return `None` on failure. For example,
+`compile_files()` reports an unknown node type or a connection with the
+wrong value type. `program.compile()` reports a failed assertion that depends
+on an instance's parameters or a cycle in procedure execution dependencies.
+
+## Read and parse sources
+
+1. **Load sources.** `compile_files()` reads the requested files.
+   `compile_strs()` accepts their contents directly. Both include standard
+   library sources when `add_std` is enabled.
+2. **Parse sources.** `parser.parse_sources()` splits each file into tokens,
+   checks its grammar, and builds a syntax tree of declarations and
+   expressions. The tree retains attributes and source positions so later
+   stages can report errors at the relevant text.
+3. **Validate source metadata.** `validate_source_metadata()` checks file
+   attributes and native function name collisions.
+
+The source outline and editing helpers use
+`parser.parse_str()` directly. They stop at parsing and syntax-tree
+construction, so they can read and edit files with errors that would be
+detected by later compiler stages.
+
+## Build node type graphs
+
+`CompilerCoordinator` runs the following stages for all declared node types,
+including unused ones. Top-level declarations go through the same stages.
+A type's graph describes its ports, storage, procedures, and child nodes;
+parameter values can still depend on how the type will be instantiated.
+
+1. **`collect_declarations`.** Register names and check duplicates and
+   restrictions on where declarations may appear. Combine repeated namespace
+   blocks into the same scope. Collect nested node types for processing
+   independently of the types that enclose them.
+2. **`prepare_interfaces`.** Resolve parameter types, struct fields, and
+   function signatures. Create objects for declared node ports, procedure
+   ports, and local storage. A procedure port declared by reference gets its
+   type from the referenced port during `bind_bodies`. This stage prepares
+   each type's own declarations; the node instances inside its body are
+   resolved next.
+3. **`resolve_instance_declarations`.** Find the type of each child node and
+   check its parameter assignments. Keep references to enclosing parameters
+   for later evaluation. Record which types instantiate other types.
+4. **`check_containment_cycles`.** Reject a type that directly or indirectly
+   instantiates itself, including in unused types. Report the declarations
+   forming the cycle. Declaring a type inside another type does not itself
+   instantiate it.
+5. **`create_child_interfaces`.** Create child instance objects and their
+   input and output ports with `NodeType.create_instance_interface()`.
+   All child ports exist before `bind_bodies` resolves references and makes
+   connections. Storage and procedures inside those instances are filled in
+   later.
+6. **`bind_bodies`.** Resolve procedure port references and the types they
+   inherit. Check parameter defaults, constants, and assertion expressions.
+   Resolve initializer dependencies and connect ports named in procedure
+   dependency and output declarations. Then apply explicit `connect`
+   statements in their relative source order. This order preserves
+   multi-input ordering and the choice of storage for procedure outputs.
+7. **`validate_bodies`.** Check that procedure inputs and local storage have
+   sources. Reject local aliases that refer back to themselves. Each body,
+   including the top-level body, is now connected and checked.
+8. **`populate_instances`.** Fill in existing child instances with storage,
+   procedures, aliases, state-copy sources, and initializer dependencies
+   from their type graphs, using `NodeType.populate_instance()`. Process
+   child types before the types that instantiate them. Keep the same port
+   objects so previously established connections remain valid.
+
+The coordinator controls this order. Creating or populating an instance
+never starts another compiler stage. Each preparation operation is marked
+complete only after it succeeds. Types and constants that depend on other
+declarations can resolve those dependencies when first needed, with separate
+checks for cycles in those references.
+
+`wirely.compiler.analysis.analyze()` runs the stages through
+`create_child_interfaces` to resolve the port and parameter types of
+programs that do not compile. It continues after an error in a
+declaration, instance, or parameter binding and reports all errors with
+their source offsets. Its connection checks apply the rules of
+`bind_bodies` to single connections without binding the program.
+
+## Generate the runtime program
+
+`program.compile()` calls `program.lower_program()` with the global graph.
+If there are top-level storage declarations, procedures, constants, or
+assertions, it creates an instance representing those top-level declarations.
+
+`program.specialize_instances()` visits each use of a node type. Through
+`InstanceNode.specialize()`, it evaluates parameters, defaults, constants,
+and assertions, resolves parameter-dependent types, and allocates state
+storage. It also assigns instance paths and shares singleton instances.
+For example, two nodes using the same type can have different parameter
+values and separate storage even though they use the same type graph.
+
+The remaining work in `lower_program()` maps connection sources to runtime
+storage, orders procedures and native node construction after their
+dependencies, translates Wirely procedure bodies into instructions, and
+builds the runtime program tables. Checks that require an instance's actual
+parameter values or procedure port types happen during this part of
+`program.compile()`.