refactor(core): consolidate duplicate helpers and naming drift

[ss-o]

Current limitation

The audit found low-severity duplication and naming drift that make ownership and future maintenance less reliable:

• .zi-at-eval is independently defined in both lib/zsh/autoload.zsh and lib/zsh/install.zsh.
• The header above @zsh-plugin-run-on-unload names the update callback.
• The parallel updater header names .zi-update-in-parallel, while the function is .zi-update-all-parallel.
• .zi-load-ices contains an unresolved snippet-directory computation TODO that needs an ID-collision test before it can be classified as a defect.

Evidence at commit 795662792e70af6cd36155b019b775796a9fdbee:

• zi/lib/zsh/autoload.zsh

  Lines 259 to 266 in 7956627

  	# FUNCTION: .zi-at-eval [[[
  	.zi-at-eval() {
  	local atclone="$2" atpull="$1"
  	integer retval
  	@zi-substitute atclone atpull
  	[[ $atpull = "%atclone" ]] && { eval "$atclone"; retval=$?; } || { eval "$atpull"; retval=$?; }
  	return $retval
  	} # ]]]

• zi/lib/zsh/install.zsh

  Lines 2046 to 2055 in 7956627

  	# FUNCTION: .zi-at-eval [[[
  	.zi-at-eval() {
  	local atpull="$1" atclone="$2"
  	integer retval
  	@zi-substitute atclone atpull
  	local cmd="$atpull"
  	[[ $atpull == "%atclone" ]] && cmd="$atclone"
  	eval "$cmd"
  	return "$?"
  	} # ]]]

• zi/zi.zsh

  Lines 1154 to 1166 in 7956627

  	# FUNCTION: @zsh-plugin-run-on-update. [[[
  	# The Plugin Standard required mechanism, see:
  	# https://wiki.zshell.dev/community/zsh_plugin_standard
  	@zsh-plugin-run-on-unload() {
  	ICE[ps-on-unload]="${(j.; .)@}"
  	.zi-pack-ice "$id_as" ""
  	} # ]]]
  	# FUNCTION: @zsh-plugin-run-on-update. [[[
  	# The Plugin Standard required mechanism
  	@zsh-plugin-run-on-update() {
  	ICE[ps-on-update]="${(j.; .)@}"
  	.zi-pack-ice "$id_as" ""
  	} # ]]]

• zi/lib/zsh/autoload.zsh

  Lines 1846 to 1848 in 7956627

  	# FUNCTION: .zi-update-in-parallel [[[
  	.zi-update-all-parallel() {
  	builtin emulate -LR zsh ${=${options[xtrace]:#off}:+-o xtrace}

• zi/zi.zsh

  Lines 2025 to 2044 in 7956627

  	# second-next command (that's why it's called "ice" - it melts), however they glue to the object (plugin
  	# or snippet) mentioned in the next command – for later use with e.g. `zi update ...'.
  	.zi-pack-ice() {
  	ZI_SICE[$1${1:+${2:+/}}$2]+="${(j: :)${(qkv)ICE[@]}} "
  	ZI_SICE[$1${1:+${2:+/}}$2]="${ZI_SICE[$1${1:+${2:+/}}$2]# }"
  	return 0
  	} # ]]]
  	# FUNCTION: .zi-load-ices. [[[
  	.zi-load-ices() {
  	local id_as="$1" ___key ___path
  	local -a ice_order
  	ice_order=(
  	${(As:|:)ZI[ice-list]}
  	${(@)${(@Akons:|:u)${ZI_EXTS[ice-mods]//\'\'/}}/(#s)<->-/}
  	)
  	___path="${ZI[PLUGINS_DIR]}/${id_as//\//---}"/._zi
  	# TODO Snippet's dir computation…
  	if [[ ! -d $___path ]] {
  	if ! .zi-get-object-path snippet "${id_as//\//---}"; then
  	return 1

Proposed improvement

• Establish one owning definition for .zi-at-eval and source it consistently.
• Correct function headers as part of the owning behavioral fixes.
• Add a focused test for plugin/snippet effective-ID collisions before deciding whether .zi-load-ices needs a type-aware API.
• Keep compatibility aliases separate from accidental duplicate implementations.

Acceptance criteria

• One canonical .zi-at-eval implementation remains.
• Function headers match their definitions.
• The snippet ICE TODO is either resolved with a regression test or replaced by a precise tracked limitation.
• Existing syntax, load, update, and extraction tests remain green.

Next action

Write the effective-ID collision test first, then consolidate only the duplication proven unnecessary.

[ss-o]

Agent handoff

Status: Option spelling cleanup published, ready for review
Repository: z-shell/zi, with canonical guidance in z-shell/.github
Branch/PR: bug-449; commit 2949f94c53976cf2a605004ca9fcb909c81e5df4; PR #455
Base: next at 795662792e70af6cd36155b019b775796a9fdbee
Tracker/Issue: #449 and z-shell/.github#565

Current state

• All 428 separator-free multiword option spellings present at the base revision are normalized across 31 equivalent spelling pairs.
• Dynamic names from runtime state or user input remain unchanged.
• No narrow CI guard was added. Canonical guidance is published in docs(zsh): require canonical option spellings .github#566.
• The remote branch SHA was verified after push.

Verification

• All 31 spelling pairs were semantically equivalent in Zsh.
• The scan against 197 official canonical names found no remaining compact multiword spellings.
• Native syntax and isolated compilation: all 31 Zsh files passed; the pre-existing lib/zsh/rpm2cpio.zsh:54 warning remains.
• Existing Zi integration suites: 61 scenarios passed.
• git diff --check and the local commit hook passed.

Next steps

1. Review refactor(zsh): normalize option spellings #455 after fix(update): make parallel updater deterministic #453, fix(callbacks): persist Plugin Standard callbacks by effective ID #454, and docs(zsh): require canonical option spellings .github#566.
2. Rebase if upstream overlap requires it after the earlier Zi PRs merge.
3. Continue the remaining duplicate-helper and snippet-ID work in refactor(core): consolidate duplicate helpers and naming drift #449 separately.
4. Merge remains a separate maintainer action.

[ss-o]

Agent handoff

Merged the option-spelling subtask through PR #455 into next as 548fbe58932588377bafd87d05a578e8621bddb8.

• Integrated the preceding fix(update): wait for parallel jobs and propagate failures #114 and fix(plugin-standard): persist lifecycle callbacks under the current object #444 changes without rewriting history.
• Canonical underscore-separated Zsh option names are used consistently in the affected source.
• The option scan, syntax checks, workflow validation, full top-level local test suite, and every fresh active PR check passed.
• Issue refactor(core): consolidate duplicate helpers and naming drift #449 remains open and In Progress for the duplicate-helper and effective-ID collision work outside this subtask.

[ss-o]

Fixed by #501, merged to next.

The .zi-at-eval duplicate is removed, keeping the install.zsh definition next to its only two call sites. Both drifted headers are corrected: .zi-update-in-parallel to .zi-update-all-parallel, and +zi-parse-opts to .zi-parse-opts. The second was not listed here; a systematic sweep of every # FUNCTION: header against the definition it precedes found it.

tests/source-hygiene.zsh now asserts both properties structurally over zi.zsh and lib/zsh/*.zsh, 175 functions, and was observed failing with each defect reintroduced separately. Neither is reachable behaviourally, which is why they survived this long.

Two items here are not addressed:

• Item 2 is not reproducible. The header above @zsh-plugin-run-on-unload at zi.zsh:1309 names that function correctly. Either it was fixed after the audit or the audit was slightly off. The new test would catch it if it regressed.
• Item 4 is untouched. The .zi-load-ices snippet-directory TODO still needs the ID-collision test this issue asks for before it can be classified as a defect. Worth its own issue rather than remaining a loose end here.

Closing here rather than on merge, since Closes only fires against the default branch and this landed on next.