The public API should explicitly show that objects are write-only or read-only

[matheusd]

This wasn't immediately clear to me and led me somewhat astray: capnproto messages are not safe for both decoding and writing.

To be clear: this is not a limitation of go-capnp itself, it's a limitation of the capnproto serialization format. In particular, decoding/unmarshalling a message and then attempting to modify it is not safe.

The original capnproto C++ API solves this by using two different object types for reading from unmarshalled data and creating data: a Builder hierarchy, used to build new objects and a Reader hierarchy, used after unmarshalling/decoding a byte stream.

While the current go-capnp API implicitly also somewhat encapsulates this behavior (attempting to use a byte slice as a message without going through unmarshalling will error), IMO this should be an explicit design element of the public-facing API.

I haven't thought this through significantly, but my initial opinion would be for something like ResetForRead() and ResetForWrite() marking the message as read-only or write-only, then erroring out when the wrong method is called (still mulling over this).