chore: promote next to main

[ss-o]

Promotion readiness record

Candidate identity

• Prior main SHA: 9b6ab3502d69c214d58efecb2312b0495211d4b8

• Candidate next SHA: a3f2e76b23286c8f115009023b897ab039a265df

• Candidate tree SHA: 69e715a4b3304768c58cef4caa9de0fee78447b0

• Complete compare:
  main...next

• git diff --name-only a3f2e76...9b6ab35 produces no output.

• git rev-parse 'a3f2e76^{tree}' equals 69e715a4b3304768c58cef4caa9de0fee78447b0.

git log --oneline a3f2e76..9b6ab35 contains 9b6ab35 and 8675819, both prior promotion merges that exist only on main by design. The template calls this out. No stable-only content commit is stranded.

Required validation

Validation	Stable job name	Result
Zsh syntax and compile	Zsh syntax and compile	Pass
ZD ZUnit integration	ZD integration	Pass
Trunk	Trunk	Pass
CodeQL	CodeQL	Pass
Exact-candidate clean install and startup	Clean install and startup	Pass
Aggregate	Promotion gate	Pass

• The candidate SHA has not changed since every required check completed. Re-fetched at merge time: base 9b6ab35, head a3f2e76.
• The Guard main branch source and Promotion gate required contexts pass. 175 checks green, none failing or skipped.
• The complete file and commit compare contains only reviewed work: five commits, each from a merged pull request.

Readiness review

Contents

Five commits, three of them user-facing.

Commit	Effect
#500	.zi-load-object returned an undefined parameter, which zsh evaluates as 0, so every load reported success. A failed immediate load counted as successful and turbo scheduling proceeded anyway.
#502	The Plugin Standard unload function was unreachable for hyphenated repositories and for path-loaded plug-ins.
#503	Adds @zi-unregister-annex. Annexes previously had no correct way to unload: a handler removed without unregistering leaves a stale ZI_EXTS entry, and the resulting 127 shifts the argument list so later plug-ins stop loading entirely.
#501	Removes a duplicate .zi-at-eval, corrects two drifted # FUNCTION: headers, adds tests/source-hygiene.zsh. No behaviour change.
#504	Pins the unload ownership contracts that already hold. Test only.

Unresolved issues

None blocking. Open issues are #113, #386, #387, #388, #429, #430, #445, #447, #448, #468, #499, #505. None is a regression introduced by this candidate. #113 and #505 are open on design decisions and both gained measured evidence during this work.

User-facing and migration notes

No migration required. #500 and #502 restore intended behaviour that was broken. #503 is additive.

One behavioural consequence worth stating plainly: before #500, a failed load reported success, so any caller or user script that inspected zi load's status was reading a constant 0. After this promotion that status is real, so a load that was always silently failing will now report non-zero. That is the fix working, not a regression, but it can surface pre-existing failures that were invisible.

Public-contract follow-ups

#503 adds a new public function, @zi-unregister-annex. The Public contract impact check passed on that pull request. The annex API is documented in the wiki at ecosystem/annexes/0_overview.mdx, which has no entry for it yet; that documentation is being prepared separately and does not gate this promotion.

z-shell/z-a-meta-plugins currently leaves an inert stub behind on unload as a workaround for the missing API, and can drop that once this reaches main.

• If the candidate introduces monitoring for a contract surface absent from the base, manually inventory that surface across the complete compare.

Merge contract

Promotion uses Create a merge commit. Never squash or rebase.

• The resulting commit message has no bot, AI-agent, or automation Co-authored-by trailer.
• delete_branch_on_merge is false; remote next will survive the merge.
• The main ruleset allows only merge commits and does not require linear history.
• The next ruleset does not require linear history.

Rollback readiness

• Rollback owner: @ss-o
• Observable rollback criteria:
  • A plug-in or annex that loaded on v2.0.1 fails to load at the new main head.
  • An unload leaves state behind that v2.0.1 removed, or removes state it kept.
  • Any ZD ZUnit job fails against the new main.
• The owner can open a same-repository hotfix-* pull request that reverts the promotion merge through protected main.
• The revert pull request will run Guard main branch source and Promotion gate.
• After a revert, clean install and startup will be confirmed at the new main head, then the hotfix will be merged forward into next.

Stable consumption boundary

This updates the Git-consumed stable main ref. It creates no semantic tag or GitHub release. v2.0.1 remains the newest tag. The open proposal #499 predates these commits and will refresh once main moves; any tag is a separately approved action.