Bash Nameref (declare -n) Indirect-Variable Script Prompt

You are a senior Bash library author. My shell functions currently fake "pass by reference" with `eval` and `${!var}` indirect expansion, which is fragile and hard to read — especially when passing arrays or associative arrays in and out. I want to refactor to Bash namerefs (`declare -n` / `local -n`, Bash 4.3+) so functions can accept a variable *name* and mutate the caller's array directly, and return structured data without echoing and re-parsing.

I will provide:
- The function(s) to refactor and their current `eval`/`${!ref}` indirection
- The data shapes involved (scalars, indexed arrays, associative arrays)
- The minimum Bash version I must support

Your job:

1. **Introduce namerefs** — rewrite each function to take an output variable name and bind it with `local -n ref="$1"`, then read/write `ref` as if it were the caller's variable. Show how this works for an indexed array, an associative array, and a plain scalar.
2. **Return structured results** — demonstrate the "output parameter" pattern: the caller declares `declare -A result`, passes `result` by name, the function populates it, and the caller reads it back — no command substitution, no re-parsing.
3. **Avoid the circular-reference trap** — namerefs break loudly when the local nameref name collides with the caller's variable name (`local -n ref=ref`). Show the naming convention (e.g., prefix the nameref, `local -n _out="$1"`) that prevents `circular name reference` errors, and explain why it happens.
4. **Guard the Bash version** — add a preflight check that fails with a clear message on Bash < 4.3, since namerefs don't exist there; note the macOS default-Bash caveat.
5. **Compare with the old way** — keep strict mode (`set -Eeuo pipefail`), and include a short side-by-side of the `eval` version vs the nameref version so the safety and readability win is obvious.
6. **Note the sharp edges** — call out that namerefs follow the name at use-time (dynamic scope surprises) and that passing an unset name is still an error under `set -u`.

Output: the refactored functions, a caller example exercising scalar + indexed + associative cases, the circular-reference gotcha with its fix, and the version-guard snippet.