Clarify object/value sharing limitations in explainer

[joliss]

I just learned about this proposal today, and am very intrigued by it -- I could see ShadowRealms being an incredibly useful feature!

When I was reading the explainer, the biggest question on my mind was what kind of objects you can pass between a shadow realm and its host realm. I Cmd+F'ed for "object", "shar", and "transfer", and checked the Security section, but couldn't find anything that clearly spelled out the semantics. It took me a while to find the following note in the API section (bold mine):

The get ShadowRealm#evaluate method promotes an indirect eval in the shadowRealm but only allows the return of primitive or callable values.

May I suggest filling in the details of the currently-proposed value sharing limitations a little? Perhaps they deserve their own subsection, and it might be worth linking to it from the Security section as well. My question as a reader is both (a) what can I do with this, and (b) what are the security implications.

From what I'm gleaning from the above sentence, you can return the following types of values:

• any primitive
• any callable, which includes
  • function objects
    • but presumably properties on the function object (fn.foo) are not preserved?
  • bound methods
  • proxy objects that implement apply?
  • builtin and host callables, like the eval function?
• but not objects (including arrays)

And when you return a callable, I'm wondering if the same restrictions are imposed on:

• what types of values you can pass as arguments
• what types of values it can return

P.S. I also don't know what "promotes" means in the sentence I quoted, but I assume it roughly means "initiates"? It might be worth clarifying this as well.