Editorial: remove implicit wrapping/unwrapping of completion records

[michaelficarra]

Ready for review. Based on #2546. Fixes #1796. Fixes #497. Fixes #496. Closes #1916. Fixes #253. Fixes #1572. Closes #486. Closes #2612. Fixes #2645.

1. remove the provision for implicit wrapping in normal completion
2. remove the provision for treating normal completions as their [[Value]]
3. annotate return types
4. make sure every AO has a return type specified; figure out what to do with any remaining explicit "unknown" returns
5. see if we can replace any ~empty~ returns with ~unused~
6. make sure all internal methods with the same name have matching return types
7. make sure all concrete methods with the same name have matching return types
8. call sites for AOs that return completion records should use ?/!/Completion(); call sites for AOs that do not return completion records should not use !/?/Completion()
9. make sure that each AO that doesn't return a completion record also doesn't contain a step that uses ReturnIfAbrupt/?/throw
10. make sure that each AO that does return a completion record might plausibly return an abrupt completion, i.e. it uses ? or throw or ReturnIfAbrupt or returns a completion explicitly
11. make sure that all AOs that return ~unused~ are always invoked using "Perform". if it's a completion record that normally contains ~unused~, make sure only its [[Type]] is relied upon.
12. If an AO is only ever invoked using "Perform", it should return ~unused~ or a completion record that normally contains ~unused~
13. find any AOs that return completion records but are always called using ! and make them not return completion records
14. add notational convention for wrapping of returns in NormalCompletion in AOs that return completion records; except Completion or ThrowCompletion or NormalCompletion
15. replace return Completion(X) with return ? X in AOs that return a completion record
16. make sure that all uses of Completion() are on the call of an AO that returns a completion, field accesses, or some other opaque source
17. go through each AO that returns a completion record with unknown normal type and see if we can further refine it
18. make sure we're not returning Completion(...) or Completion Record { ... } or NormalCompletion(...) or ThrowCompletion(...) in algorithms that don't return completion records
19. check as many of the above as possible in ecmarkup and bump ecmarkup
20. go through effect suppressions and make sure they are still valid and necessary
21. go through issues mentioned in Editorial: Can-call-user-code annotation #2548 and make sure they are addressed here
22. add visual indicator to AO headers when the AO returns a completion record
23. explain what "a Completion Record normally containing an X" means; maybe think of better phrasing?

[arhadthedev]

The PR introduces a term a Completion Record normally containing [a Type]. I think it would be useful to explicitly define it in https://tc39.es/ecma262/#sec-completion-record-specification-type via a normal completion (probably with no <dfn> to avoid visual clutter). Otherwise it may seem that "normally" means "sometimes it can be violated and another type may appear".

[jmdyck]

(You should probably also update the PR description where it says "Not ready for review".)

[jmdyck]

replace return Completion(X) with return ? X in AOs that return a completion record

Why?

[michaelficarra]

@jmdyck No reason, we just thought it was stylistically neater and semantically it's equivalent.

[bakkot]

In particular, we already have lots of Return ? Foo(), which is equivalent to Return Completion(Foo()); we might as well pick one of those two forms and stick to it. And the former is less noisy (and, to my mind, clearer).

[jmdyck]

In particular, we already have lots of Return ? Foo(), which is equivalent to Return Completion(Foo()); we might as well pick one of those two forms and stick to it.

Okay. Given those choices, I'd vote for Return Completion(Foo()).

And the former is less noisy (and, to my mind, clearer).

I might agree that Return ? X is less noisy than Return Completion(X), but

• not much, and
• if noise is a concern, you could invent a less noisy notation for Completion(X).

As for "clearer", I strongly disagree. To me,

• Return Completion(X) says: X is a CR, which is returned.
• Return ? X says: X is a CR. If it's an abrupt CR, then it's [implicitly] returned (via the semantics of ?). Otherwise (i.e., if it's a normal CR), the CR's [[Value]] is extracted and becomes the argument of the Return, at which point that value is implicitly passed to NormalCompletion(), and the resulting normal CR is [explicitly] returned.

Also, in a lot of cases of Return ? _cr_, the _cr_ is never a normal CR, so the abrupt 'path' is always taken and the Return is never actually executed, which feels odd. But there's no corresponding problem for Return Completion(_cr_).

[bakkot]

It's true that if you think about what the spec looks like after applying the rewrite rules, that thing ends up being a fairly awkward sequence of steps.

But most readers are not thinking about what the spec looks like after applying rewrite rules, and they already encounter ? AO() all the time. Return ? AO() looks like Let _a_ be ? AO() and requires no further thought. Using a different construct than the usual one here obscures that fundamental similarity.

I stand by "clearer" here.