Which metamodel roles are specced; which ought to be?

[cfa]

Following the discussion at Raku/doc#1846, I'm raising this ticket to ask which metamodel roles ought to be specced (but currently aren't) so that we can distinguish Rakudo-specific implementation details from the language specification proper.

The PR/issue linked above can be summarised as an attempt to (sparsely) document Metamodel::ModuleHOW and its roles (Metamodel::PackageHOW is effectively a subset). These are:

• Metamodel::Documenting
• Metamodel::MethodDelegation
• Metamodel::Naming
• Metamodel::Stashing
• Metamodel::TypePretense
• Metamodel::Versioning

It's not clear to me whether decomposition of metaclasses into named roles is specced or a Rakudo implementation detail. So: Should we be documenting the individual roles at all?

• If so, cursory grepping through roast suggests that the following might be indirectly specced ("might" because I'm not really familiar with the details of the test suite, sorry):
  • Metamodel::Documenting
    • WHY
  • Metamodel::MethodDelegation
    • find_method
  • Metamodel::Naming
    • name
  • Metamodel::Versioning
    • auth and ver
  • Metamodel::TypePretense
    • type_check
• If not, we can probably simplify the existing MOP docs, removing role cross references and hiding implementation (i.e. declaration) details for ClassHOW and EnumHOW.
  • I can then push some simplified docs for ModuleHOW and PackageHOW which avoid referencing Rakudo-specific details.

Thanks!

[zoffixznet]

@jnthn would you be able to say which of these should be part of the spec?

[jnthn]

Well, per Hyrum's law, they'll probably all converge on being de facto spec if they don't change for long enough. :-)

That aside, I'm a bit conflicted on this matter. Points for putting these in spec and doc are:

• The role structure has been stable for a long time. That either means it's right, or that metamodels are too mind-bending for there to be enough people about who can see it's wrong.
• Our meta-objects being composed out of roles means that we get a bunch of re-use. Maybe users writing custom meta-objects should be able to take advantage of that, rather than be restricted to subclassing or just doing the whole thing from scratch. And if you're developing sufficiently interesting new kinds of type, subclassing won't be an option, because they'll be too different.

Points against putting these in spec/doc are:

• We'd committing to this factoring, and enforcing it on all future Perl 6 implementations. On the other hand, that could happen whether we spec/document it or not. Doubly so for metamodel stuff, because anybody who is off meta-programming is probably more than capable of reading the Rakudo source and using them anyway. That and such modules are infrastructural and are liable to end up with a lot of dependencies (such as OO::Monitors for example).
• I can't say I spent vast amounts of time thinking through all of the role and method names. I didn't know if I was writing The Thing or something that'd be thrown away on the way to what made it into production. There's names like composalizable and inheritalizable in there, which are either brilliant use of English derivational morphology or just terribly confusing. But when the alternative is able_to_be_turned_into_something_that_can_be_composed, perhaps I chose well...
• There's very few examples of meta-programming out there to give us much feedback on if the design is right. Not that I'd expect there to be that much of it anyway. But would more people trying this stuff out over time give us valuable feedback, such that we'd end up changing things and specifying something better? I don't know.

None of these points feels to me to give a clear answer either way. I can argue all of "let's spec/doc it, to make meta-programming more accessible", "let's wait until we've more concrete usages to see if this is right", and "let's not tie our hands for the future and put off specifying it indefinitely". I suspect my opening point means the latter isn't an option we get to pick, though, which leaves "do it now" or "agree it should happen at some unspecified time in the future".

7ish years on from doing the original metamodel design, I don't really look at it and see a bunch of things that I wish were different. I do wonder if method caching needs a revisit, because the pre-computation of caches is expensive at startup time (deserializing those is probably the second biggest chunk of startup deserialization cost). But that wouldn't be especially disruptive to do within the current design anyway, and perhaps we can put more laziness smarts into MoarVM anyway and so not touch things at the Rakudo level at all. So even there I don't feel like specifying this would be tying my hands on changes I'd like to see.

So, perhaps we shouldn't let the perfect be the enemy of the good and spec the roles. Who knows, maybe having people base their custom meta-objects around of set of core roles we have control over will afford the Rakudo team, and future implementations, more flexibility in the long run anyway.