feat(shared-data): command annotations schema v2

[jbleon95]

Overview

Closes AUTH-2549

This PR adds a new command annotation schema to shared data, adds this type to the existing protocol schema v8, and makes a small change in the previous and mostly unused version of command annotations to not break if it somehow encounters the new command annotations.

The major changes in V2 are removing commandKeys as a property (commands will now have reference to the annotation within them, this will be done in a future PR), adding an annotationId property that will be used by commands and potentially other annotations to reference the annotation, and creating a new userCommand type of annotation to represent annotations created by the user, so we can differentiate them if we ever automatically generate them.

In #15737 an earlier version of command annotations was implemented in analysis. This was not ever used in production, and was only supported in JSON protocols. This version of it would just cleanly translate any command annotations used in a JSON protocol and include that in the analysis. Although this was never made public and new JSON protocols are deprecated, this code is being left in with the change to keep the current behavior if the schema still has the V1 of command annotations.

Test Plan and Hands on Testing

Ensured this does not break any machine that happens to have a JSON protocol with command annotations, though this is most likely zero out in the field. Otherwise this is just a schema change so not much testing needed.

Changelog

• added opentronsCommandAnnotationSchemaV2 which removes commandKeys, adds annotationId and adds a new userCommand type
• protocol schema v8 can now use opentronsCommandAnnotationSchemaV2
• small change to JSON translator to recognize different command annotation schema types

Review requests

Am I forgetting anywhere else I need to update this? Future PRs will implement the pydantic objects for the new schema.

Risk assessment

Low, small change to an unused feature and still kept backwards compatibility for it.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 26.82%. Comparing base (6a4ba8e) to head (f044f47).
⚠️ Report is 3 commits behind head on edge.

Additional details and impacted files

@@            Coverage Diff             @@
##             edge   #20324      +/-   ##
==========================================
+ Coverage   25.63%   26.82%   +1.19%     
==========================================
  Files        3628     3636       +8     
  Lines      302060   302892     +832     
  Branches    42321    42334      +13     
==========================================
+ Hits        77429    81247    +3818     
+ Misses     224607   221615    -2992     
- Partials       24       30       +6     

Flag	Coverage Δ
protocol-designer	19.35% <ø> (+<0.01%)	⬆️
step-generation	5.57% <ø> (-0.02%)	⬇️

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

Files with missing lines	Coverage Δ
..._shared_data/protocol/models/protocol_schema_v8.py	100.00% <100.00%> (ø)

... and 89 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[jerader]

can you give me an example? so like this? has 3 commands

{
  "annotationId": "id",
  "annotationType": "secondOrderCommand",
  "parentAnnotation": "parentId",

  "commandKeys": [
    "commandKey1",
    "commandKey2",
    "commandKey3"
  ],

  "params": {}

  "machineReadableName": "transfer",

  "userSpecifiedName": "Transfer Sample from A1 to B1",
  "userSpecifiedDescription": "Perform a transfer"
}

[jbleon95]

We're not going to have commandKeys anymore. There were a couple references to them in the schema at the time of this comment but those have been removed. I'm not sure if we'll be using the second order type for PD or the user command ones I've added, but it'll look like they above except without commandKeys (and a userCommand wouldn't have machineReadableName). Then the commands themselves would have a command annotation field like:

{
  "id": "commandID,
  "createdAt": "2025-11-20T19:22:16.078608Z",
  "commandType": "dropTip",
  "status": "succeeded",
  ...
  "startedAt": "2025-11-20T19:22:16.078608Z",
  "completedAt": "2025-11-20T19:22:16.078894Z",
  "notes": [],
  "commandAnnotations": ["commandAnnotationID"]
}