First stab at system API design

[nomeata]

This is a first stab, please review.

Note that this is just to get started working on the document in branch design/system. So please do comment and complain about anything that goes in a fundamentally wrong direction, but maybe propose refinements and extensions (e.g. time) in a separate PR against the design/system. The grand acceptance is only when we merge design/system into master.

[ggreif]

First reading. Makes sense to me. I assume msgref and i32 are IDL types, not ActorScript types?

> 333 : i32;
stdin:1.7-1.10: type error, unbound type identifier i32

Also, this document is supposed to mention the system libraries? Possible candidates could be:

• bignum
• CBOR serialisation (part of V8)

It might be interesting to have a debugger : () -> () system call, too.

[ggreif]

Suggested change

	immediatelly send a response. It traps if `msg.reject` or `msg.reply` has been
	immediately send a response. It traps if `msg.reject` or `msg.reply` has been

[crusso]

This is actually a pretty radical change from the existing System.API in that the system no longer has much or indeed any insight into the structure of the messages. While I know @nomeata has been advocating that for a while now, we do need to discuss what, if anything, we lose with this approach. IIUC the main suggestion to me that the message payload is now just a binary blob of app/IDL interpreted data plus a side-table of reference, presumably referenced (at most) by index from within the blob. This actually might be a very convenient separation in that the system can easily track the flow of references (should we continue to support them) without having to parse the structure of the binary data. But are we losing anything?

[nomeata]

the system no longer has much or indeed any insight into the structure of the messages

There is the IDL…

IUC the main suggestion to me that the message payload is now just a binary blob of app/IDL interpreted data plus a side-table of reference, presumably referenced (at most) by index from within the blob.

Correct. That is how serialization works at the moment, so it is inspired by our (well, my) experience there, in that it is always a elembuf with always a databuf in the last element.

But are we losing anything?

We are losing the ability to send primitive DFINITY types (i32, actorref) directly, without any serialization to a binary+table format.

[nomeata]

First reading. Makes sense to me. I assume msgref and i32 are IDL types, not ActorScript types

Neither, they are WebAssembly types.

Also, this document is supposed to mention the system libraries?

No, I don’t think they are part of the System API. What should be added here (separately) is dynamic linking, maybe following https://github.com/dfinity-lab/discussion/issues/65 or https://github.com/WebAssembly/tool-conventions/blob/master/DynamicLinking.md.

It might be interesting to have a debugger : () -> () system call, too.

Yes, that would be on scope for this document. Feel free to make a PR again design/system (once this is merged, I guess, so that there is a file to extend). Maybe also chat with the SDK people what semantics they expect here.

[nomeata]

I’ll merge this into design/system, and then everyone is invited to propose changes there, for example by clicking the edit button on
https://github.com/dfinity-lab/actorscript/blob/design/system/design/system-api.md