Transition from Kinds to Exo Classes and Instances

[erights]

Prior to #5960, virtual and durable far objects could be written using the various "kind" definers

• virtual vs durable (defineKind* vs defineDurableKind*)
• single object vs cohort of facets (define*Kind vs define*KindMulti)
• whether durables are automatically registered with baggage (defineDurableKind* vs vivifyKind*)
• there is also a special case for durable singletons (vivifySingleton)

In practice we expect only three to be common (See #5708 )

• vivifyDurableKind
• vivifyDurableKindMulti
• vivifySingleton

#5960 introduces replacements for these, in order to address two problems:

• Kind definers require their methods to take an additional context first argument for receiving the object state and access to self or cohort of facets. This shifts the argument types by one, which creates a painful IDE experience (See fix: far classes with interface guards, used by ERTP #5960 (comment) below. (Note that singletons do not have this problem.)
• As far objects, these may be exposed to malicious messages, both intra-vat (eventually) and inter-vat. Thus they must be defensively consistent, which requires strong input validation. Experience shows that it is tricky to write adequate input validation manually and to review for adequacy. (This applies to normal non-virtual far objects as well, which will be addressed by fix: heap far classes #6107 .)

The replacements

• virtual vs durable (defineVirtualFarClass* vs defineDurableFarClass*)
• single object vs cohort of facets (define*FarClass vs define*FarClassKit)
• are durables auto registered in baggage (defineDurableFarClass* vs vivifyFarClass*)
• special case for singletons (vivifyFarInstance)

Its worth noting that we expect conversion from Kind style to Far Class style not to effect which are common in practice:

• vivifyFarClass
• vivifyFarClassKit
• vivifyFarInstance

It addresses the two problems mentioned above

• The methods provided to the FarClass definers take their context as their this argument, leaving their function type unaffected. This requires that these methods be written as functions that receive their this binding dynamically. We chose to use concise method syntax, where all these methods are written inline within the call to the FarClass definer. Note that these constraints are familiar to JS class programmers, whose methods must also be written in concise method syntax that must appear inline within the class definition.
• fix: far classes with interface guards, used by ERTP #5960 extends our pattern sublanguage with M.interface and helpers M.call, M.callWhen, and M.await for defining protective interfaceGuards that can express and enforce type-like constraints on incoming arguments and return results. This sublanguage needs to be separately documented. The FarClass definer functions all take an interfaceGuard argument. The methods exposed as the API will check all their incoming arguments before calling the raw methods provided in the same call to the FarClass definer.

The raw methods can thus assume that all the validation expressed by the interfaceGuard for this method has already been checked. It is still the responsibility of the raw method to validate all issues that remain after the interfaceGuard has done its part of the job. For example, for a payment argument, the interfaceGuard can only validate that it is a remotable. It remains to the raw method to manually check, for example, that it is a live payment of the correct brand containing enough assets.

This raises the other reason we need to write these methods inline: By themselves, they are fragile. Also, by themselves, they are this-sensitive functions. For both of those reasons, we'd like to avoid the possibility of them floating around as first-class values. By having them appear inline in the FarClass definer call, we successfully encapsulate them. Afterward, they can only be reached by the protective outer shell described by the interfaceGuard.

After #5960 is merged and we have experience using it, we hope to decide to deprecate the Kind functions and style in favor of the Far Class style. But since this decision should follow experience, we leave it to the follow on PR #6106 .

[gibson042]

The referenced PRs have merged; can this be closed? I don't know how to address a discussion that has concluded... do we convert to an issue and close, migrate to docs and delete, apply some kind of "done" label?

[erights]

Are there any remaining uses of the Kind interfaces? If not, then we need some issue open to keep track of the need to do so. Either way, once there are no more uses, we need to delete the Kind implementations, and we need some issue open to keep track of that need. Can this issue stay open to serve those purposes?

[erights]

Oh, this is a discussion rather than an issue. Since we've already made the decision, I think we can close any discussion of it at this point and only need an open issue.

[turadg]

close any discussion of it at this point

Discussions can't be closed . If it's really an issue that is complete, it can be turned into an issue, but we have others already. IMO this is valuable to keep as a discussion and docs can refer to it for anyone curious about how the design was arrived at.

You could lock this discussion if you don't want to allow other comments. I don't see the value in doing that.

[erights]

I don't see the value in doing that.

Agreed. Thanks for the clarifications.