reader.unresolved_symbol

What it is ¶

reader.unresolved_symbol(ref_des, symref) yields one row per PLACEMENT, when the reader could not open or parse that placement’s symbol (WS1-052). ref_des is the affected component’s reference designator; symref is the reference exactly as the source spelled it (an xschem or gEDA res.sym, a KiCad Library:Symbol lib_id). One missing file usually produces several rows, one per part drawn with it.

The relation is keyed by ref_des rather than by symref, because every other netlist relation joins on a ref-des. A ref-des key answers “what did it cost me”, and a file key cannot.

An empty result means every symbol resolved. It does not mean the design has no external symbol references.

For hardware engineers ¶

A symbol file carries a part’s pins. When the reader cannot find it, the part still appears on the sheet with its designator, but it has no terminals, so it joins no nets. The drawing shows the part wired up; the netlist behind it does not.

You query this when a check comes back clean and you want to know whether it was clean because the design is right or because the reader never saw half the connections. A row means some part’s connectivity is missing from the read, so any conclusion about that part is unsupported. The usual cause is a library that was not on the search path, not a mistake on the schematic.

For software engineers ¶

The front end records a resolution failure here instead of swallowing it. The parse succeeded; a transitive dependency of the parse did not, and the result is a smaller graph rather than an error. The failure removes edges instead of raising, so every downstream query returns a confident answer over incomplete input.

It is a projection over Model.UnresolvedSymbols(), flattened from one entry per reference to one row per affected placement so it joins on ref_des. Note the asymmetry with the symbol-unresolved rule. The rule reports one finding per REFERENCE (one cause, one finding). The relation is per placement (one row per victim), because it joins at that granularity.

Go projector ¶

unresolvedSymbolFacts in stdlib/relations/facts.go iterates Model.UnresolvedSymbols() (the reader-emitted ir.UnresolvedSymbol list off InputDiagnostics) and emits one row per entry in each record’s ref_des list, with the reference’s provenance as the citation. Every symbol-resolving reader populates the same channel, so the relation is format-neutral.

Datalog ¶

List every part that lost its pins, and to what:

reader.unresolved_symbol(?ref, ?sym) => ?ref, ?sym

Whether anything that MATTERS lost its pins. The ref-des key exists to answer this question:

reader.unresolved_symbol(?ref, ?sym), component.class(?ref, "fpga") => ?ref, ?sym

Everything affected by one specific missing library:

reader.unresolved_symbol(?ref, "Device:R") => ?ref