Module neighbor_roles 

Connectivity-based neighbour-role inference and compile-time completeness validation for active devices.

What this is (and is NOT)

Stage boundaries are currently set by a role-blind topology heuristic that can, for example, evict a tube’s plate-load resistor and collapse a multi-stage amp. The durable fix is to let components declare — per terminal — what neighbours they need (see Component::terminal_requirements and NeighborRole), so a later “arbitration” phase can set boundaries by circuit meaning rather than topology shape.

This module builds only the declaration-driven inference + a completeness diagnostic. It does NOT change boundary formation, stage ordering, or arbitration — those are a separate later phase that will consume these roles. The only runtime-visible behaviour added here is a compile-time completeness error, which is gated to be false-positive-free on the entire working .pedal corpus.

Role inference rules (per active terminal, on the compiled netlist)

For an active device terminal node, each incident passive (or transformer / active) neighbour edge is classified by a directed, rail-aware walk:

• NeighborRole::Load — the neighbour develops the device’s output: a passive path from the far side reaches a supply rail (vcc / named supply), OR the neighbour edge is a transformer winding, OR the far side is another active device’s terminal acting as the load. Recognised on an output terminal (plate/cathode, collector/emitter, drain/source).
• NeighborRole::Signal — a series element whose far side reaches ANOTHER active device’s INPUT terminal (grid / base / gate) by a passive path. This is the future stage boundary / ordering edge.
• NeighborRole::Ref — DC operating-point / AC-grounded support: the far side reaches ground or an AC-ground (supply rail or large-cap bypass).

Inference operates on the netlist and is INDEPENDENT of stage formation.

Structs

InferredNeighbor

An inferred role for one neighbour of one active-device terminal.

Functions

completeness_errors

Public completeness errors for a parsed pedal (returns the rendered messages). Ok with an empty vec means the circuit is complete.

infer_neighbor_roles

Infer neighbour roles for every active device terminal in pedal.