Resolves a %PtcRunner.Lisp.Prelude.ValidationError{} to the byte span of the top-level form it blames.

PtcRunner.Lisp.Prelude.Compiler walks PARSED forms, which carry no source positions; PtcRunner.Lisp.Prelude.FormScanner walks the RAW TEXT and carries nothing else. This module is the single seam between them, applied once at the compile boundary so no error site has to know about byte offsets.

How a failure is located

In order of precision, using whichever locator the error already carries:

1. form_index — the position of the top-level form the compiler was processing. FormScanner.scan/1 cross-checks its own form list against PtcRunner.Lisp.Parser head-by-head and refuses to return at all on any disagreement, so a successful scan is positionally aligned with the parsed forms the compiler walked. That check is what makes indexing by position safe.
2. ref ("namespace/symbol") — for failures raised after the walk, when only the offending definition is known. Resolved to the def, defn, or defn- form with that name under that namespace, but only when exactly one form matches: a name is unique only once duplicates have been rejected, and some ref-carrying failures are raised before that check runs. :duplicate_ref is the one exception, because it IS the duplicate report — it resolves to the last matching form, the redefinition that collided.
3. namespace — resolved to the (ns ...) form that declares it.

Top-level-form resolution is best-effort and fails OPEN: a source this module cannot scan, an out-of-range index, or an unresolvable name leaves the error exactly as it was. That also preserves an explicit parser-position span, which does not depend on a successful form scan. A diagnostic without a span is safer than one with a WRONG span pointing at innocent code.