Editorially distinguish host and implementation

[syg]

Closes #1524

[syg]

Here is a concrete PR we can discuss for #1524

This PR editorially distinguishes hosts from implementations while normatively defining them to be the same thing.

The general editorial convention I'm proposing here is that what we call hosts is just the set of things that interact with ecma262 via things with the word "host" in them, like host hooks or [[HostDefined]]. Everything else is implementation.

One way to look at this is that ecma262's "public API" is the set of all places that ecma262 currently refers to as implementation-defined or host-defined. Where there is an explicity named API, we call that a host hook, and these are added for the sake of other specifications so they have a structured way of hooking in behavior. Where there is no explicitly named API, we'll continue saying implementation-defined. A host is a special consumer that only interacts with the host subset of the public API. An implementation can interact with both the host subset and the unnamed subset.

The TC39 editors have the right to add host hooks to implementation-defined places and make them host-defined without any normative changes, since from an observable behavior point of view, ecma262 can't tell a host from an implementation. This will be done when an upstream spec needs it for easier layering. To contrast, this won't usually be done for the needs of implementations, since implementations aren't directly consuming ecma262 spec mechanisms (Records, execution contexts, whatever) via named hooks.

[erights]

The TC39 editors have the right to add host hooks to implementation-defined places and make them host-defined without any normative changes, since from an observable behavior point of view, ecma262 can't tell a host from an implementation.

I strongly disagree. Perhaps add it to the next incubator call?

[syg]

I strongly disagree. Perhaps add it to the next incubator call?

I'm very surprised by this. Are you of the opinion ecma262 is able to distinguish hosts and implementations today?

(As for process, let's try to resolve via this issue. I'd rather leave incubator call time for proposals.)

[syg]

Also @erights, to clarify with a concrete example:

Today, debugger is specified as doing an implementation-defined debugging action. In the future, if an external specification arises that would like debugger to call into itself via a HostPerformDebugAction hook to explicitly trigger a debugging action, this is not a normative change but a layering one. The allowed observable behavior of debugger has not changed. The editors consider the addition of such a host hook to be an editorial judgment.

[jmdyck]

Editorial: implementation-dependent -> implementation-defined

That isn't an editorial change. At least, not by the definitions of those terms that I'm familiar with: "Implementation-defined" requires the implementation to convey (to its users) how it defines the thing; "implementation-dependent" doesn't. (See e.g. definitions from @allenwb here or the XQuery spec here.)

[syg]

That isn't an editorial change. At least, not by the definitions of those terms that I'm familiar with: "Implementation-defined" requires the implementation to convey (to its users) how it defines the thing; "implementation-dependent" doesn't. (See e.g. definitions from @allenwb here or the XQuery spec here.)

I get the intention, but is that a normative requirement? Like, are we saying that an implementation doesn't "convey how it defines the thing" is non-conformant? What does it mean to convey in a conformant way?

Edit: Judging from the XQuery spec, it sounds like "implementation-defined" means "a spec exists and defines it somewhere else", and "implementation-dependent" means "whatever an implementation does", which is the distinction I'm trying to draw here between host-defined for the former, and implementation-defined for the latter.

[jmdyck]

I get the intention, but is that a normative requirement? Like, are we saying that an implementation doesn't "convey how it defines the thing" is non-conformant?

I believe that's usually the idea.

What does it mean to convey in a conformant way?

I think most specs leave that up to the implementation.

Edit: Judging from the XQuery spec, it sounds like "implementation-defined" means "a spec exists and defines it somewhere else",

That depends on what you mean by "a spec". If a sentence in the implementation's documentation is "a spec", then okay, but that's not what the phrase suggests to me.

and "implementation-dependent" means "whatever an implementation does",

Roughly, yeah.

which is the distinction I'm trying to draw here between host-defined for the former, and implementation-defined for the latter.

So this PR is using "implementation-defined" to mean what is elsewhere signified by "implementation-dependent"? That doesn't seem like a good choice. (It's also arguably a normative change for the things currently labelled "implementation-defined".)

But I don't think I agree that that's the distinction you're trying to draw here. This PR says that "host-defined" and "implementation-defined" are normatively indistinguishable, but the usual meanings of "implementation-defined" and "implementation-dependent" are definitely normatively different.

[ljharb]

Suggested change

<p>In common use, hosts and implementations refer to different sets of entities. An implementation usually refers to a concrete artefact, such as a particular web browser, that is capable of executing ECMAScript. A host refers to the set of all implementations that interface with this specification in the same way for a subset of facilities, such as the set of all web browsers. Thus, a host is often an external specification, such as WHATWG HTML, that normatively references and interacts with the this specification. Facilities that are host-defined here are further defined in that external specification.</p>

<p>In common use, hosts and implementations refer to different sets of entities. An implementation usually refers to a concrete artifact, such as a particular web browser, that is capable of executing ECMAScript. A host refers to the set of all implementations that interface with this specification in the same way for a subset of facilities, such as the set of all web browsers. Thus, a host is often an external specification, such as WHATWG HTML, that normatively references and interacts with the this specification. Facilities that are host-defined here are further defined in that external specification.</p>

i much prefer "artifact" but there's 0 occurrences of it, and 6 of artefact, so, ugh, feel free to ignore this.

[ljharb]

Suggested change

	1. If the host requires that the `this` binding in _realm_'s global scope return an object other than the global object, let _thisValue_ be such an object created in an host-defined manner. Otherwise, let _thisValue_ be *undefined*, indicating that _realm_'s global `this` binding should be the global object.
	1. If the host requires that the `this` binding in _realm_'s global scope return an object other than the global object, let _thisValue_ be such an object created in a host-defined manner. Otherwise, let _thisValue_ be *undefined*, indicating that _realm_'s global `this` binding should be the global object.

Suggested change

	1. If the host requires that the `this` binding in _realm_'s global scope return an object other than the global object, let _thisValue_ be such an object created in an host-defined manner. Otherwise, let _thisValue_ be *undefined*, indicating that _realm_'s global `this` binding should be the global object.
	1. If the host requires that the `this` binding in _realm_'s global scope return an object other than the global object, let _thisValue_ be such an object created in an host-defined manner. Otherwise, let _thisValue_ be *undefined*, indicating that _realm_'s global `this` binding should be the global object.

[ljharb]

Suggested change

	<p>HostGetImportMetaProperties is an host-defined abstract operation that allows hosts to provide property keys and values for the object returned from `import.meta`.</p>
	<p>HostGetImportMetaProperties is a host-defined abstract operation that allows hosts to provide property keys and values for the object returned from `import.meta`.</p>

[ljharb]

Suggested change

	<p>HostFinalizeImportMeta is an host-defined abstract operation that allows hosts to perform any extraordinary operations to prepare the object returned from `import.meta`.</p>
	<p>HostFinalizeImportMeta is a host-defined abstract operation that allows hosts to perform any extraordinary operations to prepare the object returned from `import.meta`.</p>

[ljharb]

Suggested change

<p>HostImportModuleDynamically is an host-defined abstract operation that performs any necessary setup work in order to make available the module corresponding to the |ModuleSpecifier| String, _specifier_, occurring within the context of the script or module represented by the Script Record or Module Record _referencingScriptOrModule_. (_referencingScriptOrModule_ may also be *null*, if there is no active script or module when the <emu-xref href="#sec-import-calls">`import()`</emu-xref> expression occurs.) It then performs FinishDynamicImport to finish the dynamic import process.</p>

<p>HostImportModuleDynamically is a host-defined abstract operation that performs any necessary setup work in order to make available the module corresponding to the |ModuleSpecifier| String, _specifier_, occurring within the context of the script or module represented by the Script Record or Module Record _referencingScriptOrModule_. (_referencingScriptOrModule_ may also be *null*, if there is no active script or module when the <emu-xref href="#sec-import-calls">`import()`</emu-xref> expression occurs.) It then performs FinishDynamicImport to finish the dynamic import process.</p>

[ljharb]

Suggested change

	<p>HostHasSourceTextAvailable is an host-defined abstract operation that allows host environments to prevent the source text from being provided for a given function.</p>
	<p>HostHasSourceTextAvailable is a host-defined abstract operation that allows host environments to prevent the source text from being provided for a given function.</p>

[ljharb]

@jmdyck if this spec does not define them as normatively different, they aren't. Does it, and if so, where?

[jmdyck]

if this spec does not define them as normatively different, they aren't.

(One could just as easily say that if it doesn't define them as being normatively the same, they aren't.)

(And as a counter-example, the spec doesn't define "normative" and "informative" as normatively different. But I don't think anyone would claim that they aren't.)

The current spec doesn't define "implementation-defined" or "implementation-dependent" at all. And yet it certainly treats them as if they have meaning. It's been that way for a while. So if readers have been inferring meaning for these terms, how have they done so? My impression is that these are terms of art in the world of programming language specification (perhaps moreso in the early days of ECMAScript's standardization). @allenwb says that they have 'de facto standard meaning ... among language people". There are several language standards that use both these terms with more-or-less the given meanings: Pascal, SQL, Ada, Modula-2, Forth, PL/1. (Note that the are not open specs, so good links are hard to come by.)

TC39 can certainly decide that, for the purposes of the ES spec, these two terms mean the same thing, but that would invalidate a reasonable past interpretation in which they had different normative implications, so that sounds like a normative change to me.

[erights]

@syg said:

The TC39 editors have the right to add host hooks to implementation-defined places and make them host-defined without any normative changes, since from an observable behavior point of view, ecma262 can't tell a host from an implementation.

I said:

I strongly disagree. Perhaps add it to the next incubator call?

@syg said:

I'm very surprised by this. Are you of the opinion ecma262 is able to distinguish hosts and implementations today?

(As for process, let's try to resolve via this issue. I'd rather leave incubator call time for proposals.)

Is #1524 where we should discuss this?

Posting here in the meantime. Gives context about specifically what I want to discuss. I'll copy this to wherever we agree to.

Warning. I am not a formalist. @brabalan , I'd love your corrections on the following. Attn also @allenwb of course.

---

Equivalence

When reasoning about program equivalence, when are two programs, A and B, equivalent?

Implementation defined

The spec, by leaving some issues underspecified, and thereby implementation defined, allows some set of executions for a given program. Any implementation that only performs an execution within this set is conforming. Any implementation that ever performs an execution outside of this set is non-conforming. Two programs A and B are equivalent when their sets of possible allowed executions are identical. Program B is a correctness preserving transform of program A when the set of possible allowed executions for B is a subset of the set of possible allowed executions for A.

Example: WeakRefs make GC decisions observable. Say that A and B are actually the same in the part of the program that uses WeakRefs and that WeakRefs observe. Say that A and B differ in a completely unrelated part of their programs, such that their allocation behavior differs, provoking GC at different times. Clearly, the set of allowed weakref observations for the two programs are equivalent. Clearly, on a given implementation, the specific execution and weakref observations provoked by A may differ from that provoked by B.

Host hooks

By contrast, host hooks are observations. Calling a host hook is a form of I/O. The spec does place some requirements on any given host hook, but allows the host some set of choices within those constraints. An example is whether to allow a given call to eval. The spec allows any host to either allow or disallow any given call to eval. Say that A calls eval once and B calls eval twice. These programs are not equivalent because they ask the host different questions. A and B are no more equivalent than are two programs that print different strings.

[syg]

@erights Ah, I think I see your objection.

By making implementation-defined facilities to host-defined with host hooks, I did not mean without qualification. The editors can only add explicit host hooks to implementation-defined facilities if it does not change the observational equivalence. If the particular thing that is defined by implementation is very narrowly scoped, like GC timing, the editors certainly cannot non-normatively add host hooks there that may change what is observable.

In the case of GC timing, the only host hook that would make sense is a hook that is only allowed to change GC timing (which isn't very useful and probably won't be added). In the case of debugger;, the implementation-definedness is already "anything goes" and is already an allowed observation, and adding a host hook there would be allowed as it won't change any observations.

[syg]

@jmdyck I'm not against normatively distinguishing implementation-dependent and implementation-defined, but I don't think there's agreement that they are normatively different today.

An example that's come up is the following. Currently, Number::exponentiate is defined as an "implementation-dependent approximation". Suppose that an upstream specification for JS in embedded devices define that Number::exponentiate must use fdlibm's implementation verbatim. Is that a normative change? The editors are of the opinion that it is not a normative change, but it seems like you are of the opinion it is a normative change. How do other folks feel?

[allenwb]

An example that's come up is the following. Currently, Number::exponentiate is defined as an "implementation-dependent approximation". Suppose that an upstream specification for JS in embedded devices define that Number::exponentiate must use fdlibm's implementation verbatim. Is that a normative change? The editors are of the opinion that it is not a normative change

That is not a normative change to ECMA-262 because it isn't a change to ECMA-262 at all. An upstream spec. requiring fdlibm does not conflict the ECMA-262's "implementation-dependent approximation" statement. In this case the "implementation" has chosen to conform to both the upstream spec and ECMA-262. It's the implementor's choice.

But if ECMA-262 was changed to say something like an "implementation-dependent approximation that is accurate to at least 10 significant digits" that would be a normative change to ECMA-262 because it adds additional requirements for conforming implementations. If fdlibm did not satisfy that requirement then it would be impossible to an ECMAScript implementation to fully conform to both ECMA-262 and the hypothetical upstream spec. (of course, requiring use of a particular library in a standard is usually a bad short-sited idea.)

[syg]

@allenwb The distinction @jmdyck is pointing out isn't implementation vs spec, but implementation-defined vs implementation-dependent. He's saying the former is about having a place where the additional definition is conveyed, and a latter about not needing additional conveying of information. So for implementation-dependent places like exponentiate, changing it to implementation-defined where an external spec defines it is a normative change.

Do you think defined vs dependent have that normative distinction?

[allenwb]

I don't think a change between "implementation-defined" and "implementation-dependent" is normatively significant. In both cases, the relevant behavior is un- or under-specified (although often restricted by normative requirements) by ECMA-262 and many differ among conforming implementations. However, stating that a behavior is "implementation-defined" implies that the implications of an implementations choice is both observable and significant enough to ECMAScript programmers that an implementation's actual behavior should be clearly communicated to its users (for example, in a document or webpage).

It is a judgement call whether a specific ECMA-262 unspecified behavior should be described as implementation-defined or implementation-dependent. The criteria I applied included considering how likely a typical ES programmer would need to know the actual behavior provided by an implementation. The implementation's interpretation of a module specifier is certainly important to most programmers and needs to be documented. The order in which early errors within a script or module are detected and reported probably isn't important enough for the vast majority of programmers to describe it as implementation-defined. The algorithm used to implement exponentiate is in a grey area. It it is probably unimportant to the majority of ES programmers but is important to a class of ES programmers. But the class members are generally sophisticated enough that when it matters to them they will do their own analysis. For this case I come down on the side of implementation-dependent. But other might reasonably decide implementation-defined.

You could decide to say implementation-defined in all cases. But I think that dilutes ECMA-262's communications to implementors. They aren't likely to obey and it removes the identification of which unspecified behaviors are really important to document.

[jmdyck]

Currently, Number::exponentiate is defined as an "implementation-dependent approximation". Suppose that an upstream specification for JS in embedded devices define that Number::exponentiate must use fdlibm's implementation verbatim. Is that a normative change? The editors are of the opinion that it is not a normative change, but it seems like you are of the opinion it is a normative change.

Nope, not of that opinion. (Not even sure how you got there.)

The distinction @jmdyck is pointing out [is] implementation-defined vs implementation-dependent. He's saying the former is about having a place where the additional definition is conveyed, and a latter about not needing additional conveying of information.

That "having a place" phrase sounds a bit odd. Given a under-defined 'gap' in the 262 spec, the imp-def/imp-dep distinction isn't about about whether there exists some external spec that fills in that gap, but rather about whether 262 requires implementations to say how they fill that gap.

So for implementation-dependent places like exponentiate, changing it to implementation-defined where an external spec defines it is a normative change.

Well, yes, if you changed the text of ECMA-262 from "imp-dep" to "imp-def", that would be a normative change, in that it requires more of implementations (not in how they behave, but in what they document).

But that wasn't your example. You said "Suppose that an upstream specification [...] define that Number::exponentiate must use fdlibm's implementation verbatim." That isn't a change to ECMA-262. Nor does it require a change to ECMA-262, if that's what you were thinking.

[ljharb]

I'm not clear on how 262 requires any documentation by any implementation, host, or whatever term you want - 262 is a spec defining the evaluation of JS, not about documentation.

[devsnek]

if implementations don't define their implementation defined behaviour it becomes undefined behaviour. in most specifications when something is "implementation defined" its normatively binding the implementation to document it.

[syg]

Well, yes, if you changed the text of ECMA-262 from "imp-dep" to "imp-def", that would be a normative change, in that it requires more of implementations (not in how they behave, but in what they document).

I am not aware of an interpretation of "normative" that puts constraints on what implementations document.

[ljharb]

@devsnek Sure, anything that's not documented by a runtime or by 262 is UB, but that applies to custom host hooks, implementation-defined things, and implementation-dependent things identically. There's nothing about the word "defined" versus "dependent" that changes that "either the runtime specifies it, or it's unspecified".

[syg]

Let's please refocus on the conversation to be about hosts and implementations and table the phrasing of defined or dependent to later or another thread. Assume for this discussion no "dependent" will be changed to "defined".

[allenwb]

I am not aware of an interpretation of "normative" that puts constraints on what implementations document.

The appreciate way to make documentation requirements of "implementation-defined" normative would be to add such a requirement to clause 2.

[syg]

Rewrote the PR given the consensus that was reached at the June 2020 meeting. Please take a look @tc39/ecma262-editors

@waldemarhorwat Does this match what you had in mind for "implementation-approximated"?

@annevk @domenic Am I missing things from the list of things that HTML further defines in ecma262?

[annevk]

I didn't do a detailed check, but that looks accurate. There's remaining open issues on agents which a host also needs to setup, but that's probably best tackled independently.

(It does seem that since ECMAScript appears to be written in en-US, you need to use artifact, not artefact, throughout.)

[bakkot]

ECMAScript appears to be written in en-US

It's intended to be Oxford spelling, which I believe implies "artefact".

[domenic]

Just curious, is a "host hook" a type of "host-defined facility"? The taxonomy here is a bit unclear.

[syg]

A host hook is any abstract operation that's not 100% defined in ecma262. The taxonomy is:

• A facility is a thing that ecma262 defines.
• Any facility that isn't 100% defined in ecma262 is called implementation-defined.
• There's an annex that lists a subset of implementation-defined facilities.
• A host-defined facility is any facility that's listed in that annex.
• A host hook is an implementation-defined abstract operation. All such AOs must be listed in that annex.
• All host-defined things are by definition implementation-defined, but should be referred to as host-defined to be specific.

The idea is HTML can leverage this taxonomy to say it is a host, since it doesn't further define things like Math.exp. Conforming implementations of HTML itself aren't free to redefine the host-defined parts (but are free to redefine implementation-defined/approximated parts). While ecma262 alone allows an implementation to redefine host-defined parts, those implementations must conform to both HTML and ecma262.

[domenic]

FYI I can't find any definition of HostHasSourceTextAvailable in HTML; instead hosts use CreateBuiltinFunction to create a function which automatically has no source text. I don't remember the history here...

[ljharb]

HostHasSourceTextAvailable is pretty new, and iirc was added so engines like xs have a way to shut off source text for all functions.

[syg]

Btw this is the intended taxonomy. The most specific term should always be used.

Edit: why are people using the laughing emoji this is no joking matter