feat: draft wrap 0.2 specification

[Niraj-Kamdar]

No description provided.

[dOrgJelli]

What were your reasons for removing the "wrap" prefix? I do like the look of this, just curious. Maybe have a section in the doc that covers the considerations & design choices made from 0.1 -> 0.2, like we did in the ABI PR.

[nerfZael]

I'm torn, we can talk about it on the ACDC

[dOrgJelli]

I think this sentence can be rewritten for better understanding. Maybe "The invoke export function receives the length of the invocation arguments buffer as its first and only argument. The invocation arguments buffer resides in an external host-controlled memory space, and must be copied into the receiving wasm module. To do this, the invoke export function's job is to allocate a new buffer of this size, and return a pointer to it, such that the host can copy the invocations arguments into it.

^^^ this might not be accurate, but you get my point, I think the wording of this paragraph can be massaged.

[dOrgJelli]

Note: it doesn't return the buffer ptr, but instead it uses the __fill_buffer import fn.

[nerfZael]

Reworded this. The full explanation is in the invocation process below.

[dOrgJelli]

This function feels too generic, and lacks context as to "what buffer is being filled". I think we could add a "bufferId" alongside the "bufferPtr" here. Also would need to add "bufferId" alongside the "bufferLen" in the _invoke export.

[nerfZael]

Reworded this a bit. But it is still a generic function, it can be either the invOptBuffer or subInvResBuffer that the host is sending to the wasm module. It doesn't need an ID to identify it because there can be only one type depending on context

[Niraj-Kamdar]

This function can also be named load_buffer
What do you guys prefer: fill_buffer 🍏 vs load_buffer 🍎

[dOrgJelli]

Should we rename "bufferLen" to "argsLen"? I think this buffer-use-case-specific naming is helpful for readers.

[nerfZael]

Renamed to optBufferLen to match the convention we have in the rest of the document.
It's the invoke options buffer length not the args buffer. Args buffer is inside of the invoke options as we defined below.

[dOrgJelli]

Would be great to specify here that subinvokes are "calls to other wrap module functions, where the invocation method and arguments are packed into a buffer". Being specific about how the buffer is packed here is necessary IMO. Sure this could change, but that'd require a new minor version rev of WRAP (0.3 for ex).

[nerfZael]

Reworded this. It's still not calls to other wrap module functions, it's calls to the host functions.
We have the buffer structure defined below, these are just the export/import signatures and their descriptions.