Guarantee public APIs under caller-selected Bash options #216

Parent: #214

Train position: 2 of 26
Phase: P0 — Trustworthy runtime and release baseline

Problem

Source-time expansions and public functions can abort under caller-selected errexit, nounset, or pipefail, and pass-by-name APIs can corrupt results when output variables alias one another. A sourceable framework must behave predictably inside shells whose option state it does not own.

Acceptance criteria

• Source every public module under default mode and all supported independent and combined errexit, nounset, and pipefail settings.
• Validate arity and optional values before positional-parameter expansion so malformed calls return documented statuses instead of aborting under nounset.
• Preserve caller set, shopt, IFS, OPTIND, cwd, umask, traps, and positional parameters unless an API explicitly documents a scoped mutation.
• Reject aliases among every caller-owned input and output before mutation, including positional, scalar, repeatable, and specification variables.
• Exercise every public API's success, usage-error, and recoverable-failure paths under the supported option contract on Bash 4.2 and current Bash.
• Publish the caller shell-option and named-result ownership contract.

Dependencies

• None