Provenance-defined build recipe

[msuozzo]

Now that #141 has created the need for the provenance to represent fully-specified build definitions, we should try to make this experience better. Currently, the recipe definition is as follows:

recipe:
  type: string
  definedInMaterial: int
  entryPoint: string
  arguments: object
  environments: object

Given the presence of fields like definedInMaterial, where would a new user think to put / look for a build definition? Maybe arguments (where I think it's currently intended to be) but perhaps after needing to read the docs thoroughly and perhaps not even then.

The justification for separating out the build definition for entryPoint is given as:

Design rationale: The entryPoint is distinct from arguments to make it easier to write secure policies without having to parse arguments.

I'd argue that a similar treatment deserves to be given to the build definition.

One nice consequence of this would be that arguments would be of a uniform structure for a builder that supports both dynamic and static configuration (e.g. the cloud build example which could mean the recipe type need not differ between the two variants (would be easier to implement+maintain for the builder).

Proposal

This could be addressed by pulling out another type-defined field to the top level:

recipe:
  type: string
  definedAs: object  # <---- NEW
  definedInMaterial: int
  entryPoint: string
  arguments: object
  environments: object

Another alternative would be to add even more structure:

recipe:
  type: string
  definition:
    content: object
    # OR
    materialsIndex: int
    entryPoint: string
  arguments: object
  environments: object

[TomHennen]

Design rationale: The entryPoint is distinct from arguments to make it easier to write secure policies without having to parse arguments.

I'd argue that a similar treatment deserves to be given to the build definition.

At the moment we have a distinct plan for using the entryPoint in policy checks. As far as I know we have no such plan for using the build definition.

The build instructions at lower levels are there, for the most part, to enable people to review and understand what was done, and attempt to reproduce the build.

[MarkLodato]

I believe this is a duplicate of #176 (and sub-issues) and was addressed by #179.