docs(api,robot-server): Document errors list as having no more than 1 element

[SyntaxColoring]

Overview

In the public (HTTP-facing) models for runs and analyses, you can access the errors of individual commands. In addition, there's an array of top-level errors. That top-level array is used to indicate fatal errors, including those that happen in between commands.

This documents, officially, that the top-level array will only ever have zero elements or one element. It will never contain multiple errors. The fact that it's an array, instead of a nullable object, is just a historical quirk.

This goes towards RSS-146 by clarifying how we should expose different kinds of run failures.

Rationale

• There is no use for errors to have multiple elements today.

  This array is left over from a time before individual commands held their own errors. Today, commands have a self-contained error field, but in þe olden tymes, they had an errorId reference that pointed into this array. This was problematic for a few reasons, such as inherent duplication.

  PR #9715 fixed this. Since then, errors has only had up to 1 element.

• Having multiple elements is confusing, and muddies what the field is supposed to be doing, conceptually. One internal comment describes it as "a list of fatal errors." But there can only be one fatal error, by definition.

• For the case where multiple things contributed to a run's failure, and we want to convey them all, we now have @sfoster1's EnumeratedError architecture. We should commit to that tree-based API instead of keeping around a competing array-based API.

• According to @shlokamin, the app just does, and has always just done, something like errors[0].

• If we really need to have multiple elements in this list later on, we can just revert this documentation change. We can do that revert without breaking any clients.

Test Plan

None needed.

Changelog

Update the public HTTP documentation in run and analysis models, and internal comments.

Review requests

Do we agree with this?

Risk assessment

No risk.

[codecov]

Codecov Report

Merging #13191 (3fe2149) into edge (9a499f9) will decrease coverage by 0.01%.
Report is 2 commits behind head on edge.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             edge   #13191      +/-   ##
==========================================
- Coverage   72.55%   72.55%   -0.01%     
==========================================
  Files        2398     2398              
  Lines       66084    66083       -1     
  Branches     7368     7368              
==========================================
- Hits        47950    47949       -1     
  Misses      16370    16370              
  Partials     1764     1764              

Flag	Coverage Δ
g-code-testing	96.44% <ø> (ø)
notify-server	89.13% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files Changed	Coverage Δ
...t-server/robot_server/protocols/analysis_models.py	100.00% <ø> (ø)
robot-server/robot_server/runs/run_models.py	100.00% <ø> (ø)

[sfoster1]

Looks good to me!

[SyntaxColoring]

Got an in-person approval from @sanni-t.