feature: object file reference to a generic peer by HFID and kind #1428

Component

infrahubctl CLI

Describe the Feature Request

Allow an object file to reference an existing peer by HFID together with its concrete kind, when the relationship's peer is a generic:

parent_interface:
  kind: InfraPhysicalInterface
  hfid: ["router1", "Gi0/0/3"]

The object loader would send this as {"hfid": [...], "kind": "..."} in the mutation. The GraphQL RelatedNodeInput already accepts kind, and the Python SDK client already sends it (#277). Only the object file format has no way to express it.

Describe the Use Case

A user models two node kinds that can both be the parent of a sub-interface, such as a physical interface and a port-channel interface. Both nodes inherit from a generic, and the sub-interface's parent_interface relationship points at that generic. Each node defines human_friendly_id: [device__name__value, name__value]. The generic does not define an HFID, because device and name are defined on the nodes and not on the generic.

The user then loads a sub-interface from an object file and references its parent by HFID:

---
apiVersion: infrahub.app/v1
kind: Object
spec:
  kind: InfraSubInterface
  data:
    - name: Gi0/0/3.10
      device: router1
      parent_interface: ["router1", "Gi0/0/3"]
      vlan_id: 10

infrahubctl object load fails:

['InfraSubInterfaceUpsert'] Unable to lookup node by HFID, schema 'InfraSubInterfaceParent' does not have a HFID defined.

The parent node exists and has an HFID. The server looks up the HFID on the generic because the request does not include the concrete kind. Today, the user must either load these objects with a Python script that uses the SDK client, or move attributes and relationships onto the generic so that the generic can define an HFID.

Additional Information

How the object loader handles relationship values today (SDK stable at 0c7aca5):

• A mapping without a data key is rejected, so {kind, hfid} cannot be used as a reference (spec/object.py#L152-L154).
• A string or list reference is passed to the mutation as an HFID with no kind (spec/object.py#L487-L492).
• A mapping with kind and data creates or updates the peer. It does not reference an existing peer.
• The client already adds kind next to hfid when it is set (node/related_node.py#L263-L266).

On the server, when the peer schema is a generic and the input includes kind, the HFID lookup uses that kind (relationship/model.py#L589-L600).

The same limit affects opsmill/infrahub#7653. There, loading roles from an object file fails because CoreBasePermission has no HFID. With this feature, that object file could name the concrete permission kind.

Not tested: whether the same change is needed for cardinality-many references, such as a list of {kind, hfid} mappings.