Discussion: protocol specification

[Gozala]

I would like to discuss and decide how are we going to approach protocol specification, so all arguments are weighted and we arrive to a best compromise as team.

Long term I would like to embrace IPLD schema for it, but in practice we need something pragmatic sooner.

My vision was to use TS interfaces for describing capabilities and corresponding protocol as described here.

However @hugomrdias encountered problems in the past with this approach, because TS would complain about mismatching types due to some inference bugs in the ucanto. There may have been other problems, but probably @hugomrdias can fill us in on those.

As a result of the issues we moved to an approach where types and protocol is basically inferred from implementation

https://github.com/web3-storage/w3protocol/blob/9d4b5bec1f0e870233b071ecb1c7a1e09189624b/packages/access/src/capabilities/types.ts#L8-L22

After conversation with @yusefnapora I'm recognizing bunch of downsides with current approach:

1. There is no simple way to generate protocol spec from this ☝️, because InferInvokedCapability<typeof account> is pretty useless when reading protocol spec.
2. There is no single place to look at the protocol spec. Things are now scattered between .ts files that do bunch of Infer* stuff and there are bunch of capability defs from which actual types are derived (with some jsdoc comments that don't even stick to the corresponding fields)
   https://github.com/web3-storage/w3protocol/blob/9d4b5bec1f0e870233b071ecb1c7a1e09189624b/packages/access/src/capabilities/upload.js#L28-L50
3. Idea is that there could be multiple implementations of the same protocol & others should be able to take protocol spec and asses that their implementation is correct. Deriving protocol spec from the implementation is backwards and flawed.

Given all the above I think it would be a good idea to take a step back and identify:

1. What makes more sense (ignoring the issues and bugs)
2. What are the issues that need to be addressed to make what makes sense not be a pain.
3. What is the timeline we achieve that thing that makes more sense.

[yusefnapora]

I would love if there were a single interface definition - it seems like the best place to put docs that won't drift out of date.

While it would be cool to define the schema with IPLD, the typescript-first approach makes sense as a practical first step (assuming the bugs are squishable).

[gobengo]

I think it's a good idea to document the protocol separately from any given implementation (e.g. typescript).

Implementations drift. Sometimes this is on purpose, e.g. an update to the implementation that corresponds to an update to the protocol. But sometimes it's an accident, i.e. an accidental regression. If you derive your protocol definition from an implementation, the protocol definition may also 'accidentally' drift from its intended definition. Not good. If someone accidentally nudges the implementation to not match the protocol, I'd want that to fail CI, not regenerate docs with no-questions-asked.

[Gozala]

If you derive your protocol definition from an implementation, the protocol definition may also 'accidentally' drift from its intended definition.

That is a really good point!

[Gozala]

One other thing I forgot to mention is something I just ran into with #163

Ideally we should be able to iterate on the protocol without having to update all of the implementations everywhere. Put it differently we'll need to version protocol and some implementations may be implementing older spec. If we just derive protocol spec from implementation we no longer can iterate on the spec independent of the implementation.

[hugomrdias]

i agree with @gobengo, IMO we should write spec markdown docs and iterate there, and implementations can update/adjust deviations at their own pace.