fix: consume empty before-load hook replacements successfully

[ss-o]

Problem

A before-load annex hook that consumes its final request successfully cannot return an empty replacement. The dispatcher converts an empty ZI[annex-before-load:new-@] into an array with one empty string, then reports No plugin or snippet ID given.

Verified in next 9278795 and stable main 56715fd. This blocks the repeated-group no-op contract in z-shell/z-a-meta-plugins#60.

Change

After parsing the replacement, clear the argument array when the replacement string is empty. Preserve quoted arguments in non-empty replacements and odd hook failure statuses. This is a narrow dispatcher correction with a focused runtime regression, without a new dependency or API.

Acceptance

• Empty successful replacement returns zero and loads no object.
• Empty failed replacement preserves the hook error.
• A following request and a quoted non-empty replacement retain their arguments and execute normally.
• Native Zsh syntax and the focused dispatcher/load tests pass.
• Recheck meta-plugins first expansion, retry, and repeated-group behavior against the corrected dispatcher.

Delivery

Approved local implementation, issue creation, and Project 28 tracking. Intended integration target: next. No commit, push, or PR requested. Recommended triage: Bug, High impact, S effort, P1 - High priority, Human delivery.

[ss-o]

Agent handoff

Status: Ready for review
Repository: z-shell/zi
Branch/PR: Uncommitted local changes on existing checkout; intended target next; no PR
Tracker/Issue: #511, Project 28

Current state

Applied the one-line empty-replacement guard in zi.zsh. Extended the existing CI-covered tests/load-object-status.zsh regression to verify empty success, empty failure status 3, preservation of a following request, quoted IDs with spaces, and a later empty replacement after a non-empty one. No new test framework or workflow required.

Verification

• New regression reproduced No plugin or snippet ID given before the fix and passes afterward on Zsh 5.9.2.
• Six focused scripts pass: load-object-status, annex-unregister, nested-load-state, atinit-deferred-marker, disk-ice-resolution, plugin-standard-callbacks. The callback test prints existing global match-array warnings.
• Native syntax, temporary byte compilation, and git diff --check pass.
• Real meta-plugins @annexes installation and repeat-load pass against an isolated copy of this corrected checkout. All four annex updates succeed; an actual bin-gem-node installer handler creates a runnable fixture shim.
• Native macOS and remote CI were not run; no performance claim.

Blockers

No local implementation blocker. The correction is not committed or published. Dependent meta-plugins changes require this correction in the deployed Zi version.

Next steps

Review the two-file diff, then publish through the normal next-branch workflow when separately authorized. Continue z-shell/z-a-meta-plugins#60 using the locally corrected dispatcher.

[ss-o]

Acceptance item 5 recheck, against the corrected dispatcher

Rechecked against next at 917b7a5, which carries #512, #514 and #517.

Zi side: satisfied

tests/load-object-status.zsh passes on merged next. It exercises real
dispatch and asserts that a before-load hook returning an even status with an
empty ZI[annex-before-load:new-@] returns zero and loads no object, that an
odd status still surfaces the hook error, and that a following request and a
quoted non-empty replacement are unaffected. Whitespace-only replacements are
covered too, since (z) yields the same single blank word for them.

Annex side: still needs its counterpart change

The annex decides the status at what is line 130 on main (c889e34):

integer retval_part="${${ZI[annex-before-load:new-@]:+2}:-1}"

An empty replacement yields 1, which is odd, so the corrected dispatcher
correctly reports it as a hook error. Calling the handler directly, the way this
repository's own tests do, with all four @annexes members in
zsh_loaded_plugins and their ice capabilities present in ZI_EXTS[ice-mods]:

Handler	Status	new-@
main c889e34	1	empty
local working tree	2	empty

The local working tree already carries the counterpart, integer retval_part=2
with a comment explaining that an empty replacement is successful. That change
is unlanded and belongs to #60.

Note the provisioner interaction that makes this reachable at all: the handler
strips a provisioner from loaded_plugins unless its ice capability is
registered, so a group is a genuine no-op only when every member is both loaded
and provisioned. A fixture that only sets zsh_loaded_plugins never reaches the
empty-replacement path.

Scope of this evidence

The evidence above is the direct handler call plus Zi's own dispatch tests, not a
single end-to-end run. An end-to-end fixture I built kept resolving the handler
from a different copy than the one it was pointed at, confirmed by an xtrace
showing main's line numbers while a modified copy was configured, so its
results are not reported here. Whoever lands #60 should add the end-to-end case
to this repository's suite, where the annex is loaded normally and the load path
is not in question.

Conclusion

Zi's half of this issue is done and verified. What remains is landing the annex
retval_part=2 change under #60, after which this issue can close.

[ss-o]

Both halves have landed and the contract holds.

Zi side

b7e4584 on next, released through #512. tests/load-object-status.zsh exercises real dispatch and asserts that a before-load hook returning an even status with an empty ZI[annex-before-load:new-@] returns zero and loads no object, that an odd status still surfaces the hook error, and that a following request and a quoted non-empty replacement are unaffected. Whitespace-only replacements are covered too, since (z) yields the same single blank word for them.

Passes against the merged next.

Annex side

z-shell/z-a-meta-plugins#82, merged as 46b34ad. The handler returned 1 for a fully consumed group, which Zi reads as an error. That value was deliberate, and its comment said why:

# Setting to 1 here will prevent the error message on no plugin/snippet ID given.

It was suppressing the very message this issue fixed, so once the dispatcher was corrected the workaround produced the error it had been written to avoid. It now returns 2.

That repository gained tests/consumed-group-status.zsh, covering a first expansion, a fully consumed repeat, a group consumed entirely through skip'', and an unrecognised id. Passes against the merged main, and its CI is green.

Acceptance item 5

Covered by those two committed suites rather than by a one-off script, which is the better outcome: each side now owns a test for its half of the contract, and both run in CI.

Worth recording for anyone extending them. A fixture only reaches the empty-replacement path when every member is both loaded and provisioned, because the handler strips a provisioner from loaded_plugins unless its ice capability is registered in ZI_EXTS[ice-mods]. Setting zsh_loaded_plugins alone never gets there. There are also two distinct routes to an empty replacement, already loaded and filtered by skip'', and the annex test covers both.

What is not claimed

An end-to-end fixture driving zi light @annexes against both merged trees was attempted and is not reported here. It proved unreliable: with the handler definition pinned and the meta-plugin map populated, the hook still did not fire on some runs, so its results say more about the fixture than about the code. The committed suites above are the evidence.

Closing. The provisioning work this unblocked continues in z-shell/z-a-meta-plugins#60.