Thanks for the work on this proposal. It looks like this is really coming together. I haven't fully thought about everything yet but one thing stood out that IMHO should be fixed.
There are tolerance parameters which are of type Instant.Interval?, e.g.
func sleep(until deadline: Instant, tolerance: Instant.Interval?) async throws
The tolerance parameters are later documented as
Not specifying a tolerance infers to the implementor of the clock that the tolerance is up to the implementation details of that clock to choose an appropriate value.
which to me sounds like not passing tolerance or passing nil effectively means "default tolerance". But .none is one of the values of Optionals and this leads to this issue
sleep(until: .now.advanced(by: .seconds(3)), tolerance: .none)
to me reads like there is no tolerance, ie. the system must try as much as it can to hit the deadline exactly. Unfortunately, the real meaning is likely quite the opposite because the "default" tolerance is probably not trying to be as exact as possible.
In AsyncHTTPClient we hit a similar issue with redirectConfiguration: RedirectConfiguration? = nil where redirectConfiguration: .none does not mean "don't follow redirects" but rather means "default". So redirectConfiguration: .none means to follow something like "up to 5 redirects" which is super confusing.
So whilst most people would usually write nil over .none, Xcode's completion system actually offers .none above nil:
So typically I now recommend making the parameter non-optional and to instead provide a public static var default: Self = ... to the type which serves as the default value.
Something like
func sleep(until deadline: Instant, tolerance: Instant.Interval = .default) async throws