feat: enhanced experiment and operator versioning support

[michael-johnston]

Introduce a first-class Algorithm Version (Major.Minor) that operator and experiment developers declare independently of the Python package version, governed by these rules (related to #936 ):

Change type	Action
Logging, refactoring, memory/performance optimisation, comments	No version bump
Adding new outputs or inputs while keeping existing behaviour identical	Minor bump (e.g. v1.0 → v1.1)
Any change to the mathematical definition or computation	Major bump (e.g. v1.1 → v2.0)

From a developer perspective:

• Every operator declares an Algorithm Version as part of its metadata, independently of its package version.
• Every experiment (including custom experiments registered via decorator) declares an Algorithm Version.
• The Algorithm Version is the developer's assertion of semantic sameness: same major version means "results computed by this algorithm are interchangeable regardless of what package version produced them."

From a user perspective:

• When a discoveryspace is created, the algorithm versions of all experiments in its measurement space are frozen at creation time. Old spaces remain valid historical artefacts even after an algorithm is upgraded.
• When an algorithm major version is bumped, new spaces created will automatically use the new version and existing memoised results from the old version are not reused — re-measurement happens automatically without any user action.
• When only a minor version bump occurs (extension), existing memoised results remain valid and are reused.
• Users do not need to specify algorithm versions in space YAML; they are resolved from the experiment catalog at space creation time.

NOTE: With the versioning scheme you can only have ONE installed version of an experiment/operator. This is already the case for operators. For experiments to maintain multiple executable versions you would need to adopt a different method

---

Describe alternatives you've considered.

• Embedding the algorithm version in the experiment base name (e.g. solve_mip_v2): one of the current solutions. This makes versioning explicit in the identifier but ties the algorithm generation to the human-readable name, requiring users to change YAML when upgrading. For decorated experiments it also requires changing the function name. Rejected in favour of a separate version field that is encoded automatically into memoisation keys.

• Supporting multiple algorithm versions coexisting in the catalog simultaneously (e.g. allowing a space YAML to explicitly request solve_mip at v1 even after v2 is deployed): this would allow controlled migration and side-by-side comparison. Deferred because it requires significant changes to catalog internals and is incompatible with the decorator-based experiment registration pattern. The "frozen space at creation time" behaviour covers the most common need without this complexity.

---

Additional context.

The major algorithm version is the only component that affects memoisation. The minor version is informational — it records that an experiment was extended — but does not break compatibility with existing results. Both components should be stored on created resources as a frozen-at-creation-time snapshot for reproducibility auditing.

Operators without a declared Algorithm Version should produce a deprecation warning at registration time to drive adoption.

[michael-johnston]

---

Examples.

(a) Declaring algorithm version in an actuator experiment YAML

Actuator experiments are defined in YAML files loaded into ExperimentCatalog. The new algorithmVersion field sits alongside metadata:

peptide_mineralization:
  identifier: peptide_mineralization
  actuatorIdentifier: robotic_lab
  algorithmVersion:
    major: 1
    minor: 0
  requiredProperties:
    # ... unchanged
  targetProperties:
    - identifier: adsorption_timeseries
    - identifier: adsorption_plateau_value
  metadata:
    description: Measures adsorption of peptide lanthanide combinations

When declared in code (e.g. when constructing an Experiment directly), the same field is passed to the model constructor:

Experiment(
    identifier="peptide_mineralization",
    actuatorIdentifier="robotic_lab",
    algorithmVersion=AlgorithmVersion(major=1, minor=0),
    requiredProperties=[...],
    targetProperties=[...],
)

(b) Declaring algorithm version in a custom experiment

Custom experiments use the @custom_experiment decorator. Algorithm version is passed as a new argument:

@custom_experiment(
    required_properties=[MpsFile],
    optional_properties=[TimeLimit, NThreads, ProgressInterval, ...],
    output_property_identifiers=["solve_times", "mip_gaps", ...],
    algorithm_version=AlgorithmVersion(major=1, minor=0),
    metadata={"description": "Solve a MIP instance using CPLEX"},
)
def solve_mip(entity, experiment_reference, ...):
    ...

Parameterised experiment identifier used for memoization

The major algorithm version is embedded into the identifier using an @v separator. This identifier appears in memoisation keys and observed property names.

Without parameterisation:

peptide_mineralization@v1

With optional properties overridden:

peptide_mineralization@v1-temperature.37-replicas.3

After a major algorithm bump (major: 2), the same parameterisation produces a different identifier, causing a memoisation cache miss automatically:

peptide_mineralization@v2-temperature.37-replicas.3

Observed property names embed the same identifier, so they change correspondingly:

# v1
peptide_mineralization@v1-adsorption_plateau_value

# v2 — distinct stored result, no accidental reuse
peptide_mineralization@v2-adsorption_plateau_value

New information in a created discoveryspace resource

After ado create discoveryspace, the stored resource contains fully resolved Experiment objects (not bare references). These now carry algorithmVersion. Existing provenance fields (actuatorProvenance) are unchanged. The relevant excerpt from the stored YAML:

config:
  experiments:
    experiments:
      - identifier: peptide_mineralization
        actuatorIdentifier: robotic_lab
        algorithmVersion:
          major: 1
          minor: 0
        # ... targetProperties, requiredProperties etc. unchanged
actuatorProvenance:
  robotic_lab:
    distributionName: ado-robotic-lab
    distributionVersion: 0.3.1

The algorithm version is frozen at space creation time. If the actuator later ships major: 2, this space continues to produce memoisation keys containing @v1, ensuring old results are still found for entities measured against this space.

[michael-johnston]

@danielelotito @VassilisVassiliadis @mgazz

[danielelotito]

I like the proposed solution more than the alternatives listed.

I would also consider offloading the version declaration to the .toml file that refers to the resources created.
You get exactly the same functionalities but you change the version at the plugin level.

Downside:
This means that if you have multiple experiments and/or operations they will inherit the same versioning to it is responsibility of the developer organize his code into plugins properly.

Upside: It is more pythonic and makes the user experience better. Ado plugins are special python packages that integrate with a well designed harness to help the scientific discoveries.
You do not have to worries about having versioning both in plugin tomls and in the code.

[michael-johnston]

Yes we could can have a fall through to plugin version

However the key point is that plugin versions track "code semantic sameness" which is often too fine-grained e.g. code can change due to major structural refactoring, but scientifically, the experiment does exactly the same thing.

So this allows defining a "scientific semantic sameness" separate from code.

This becomes more pressing if you have an actuator with multiple experiments or want to package multiple operators together (to reduce packaging proliferation)

[michael-johnston]

A sketch of implementation

New pydantic model

• Add AlgorithmVersion(major: int, minor: int) to orchestrator/core/metadata.py

Schema changes

• Add algorithmVersion: AlgorithmVersion | None to Experiment in orchestrator/schema/experiment.py
• Add algorithmMajorVersion: int | None to ExperimentReference in orchestrator/schema/reference.py; update parameterizedExperimentIdentifier to encode major version as {base}@v{major} when set
• Add algorithmVersion: AlgorithmVersion | None to OperatorMetadata in orchestrator/core/operation/config.py

Declaration API

• Add algorithm_version parameter to @custom_experiment decorator in orchestrator/modules/actuators/custom_experiments.py
• Emit a deprecation warning at registration time for operators/experiments that do not declare algorithmVersion

Version resolution at space creation

• In convert_experiments_to_measurement_space_config and measurementSpaceFromSelection, populate algorithmMajorVersion on each resolved ExperimentReference from the catalog experiment's algorithmVersion.major; this freezes the version into the stored space

Catalog enforcement

• Add ExperimentCatalog.resolve_reference(reference) -> Experiment | ParameterizedExperiment which performs base-name lookup, raises AlgorithmVersionMismatchError if reference.algorithmMajorVersion differs from the catalog experiment's algorithmVersion.major, wraps in ParameterizedExperiment if parameterization is present, and checks deprecation
• Add AlgorithmVersionMismatchError to orchestrator/modules/actuators/catalog.py
• Update ActuatorRegistry.checkMeasurementSpaceSupported to call resolve_reference so version mismatches surface as pre-flight issues

Actuator updates

• Replace the experimentForReference + conditional ParameterizedExperiment + deprecation check pattern in all actuator submit methods with a single catalog.resolve_reference(experimentReference) call
• Update the example actuator in plugins/actuators/example_actuator as the reference implementation

Resource provenance

• Add operatorAlgorithmVersion: AlgorithmVersion | None to OperationResource; populate at operation creation time from OperatorMetadata.algorithmVersion

Catalog integrity

• Tighten ExperimentCatalog.addExperiment to raise an error (rather than warn and overwrite) when a duplicate base identifier is added with a different algorithmVersion.major

[AlessandroPomponio]

I think we should stick to a semver-style versioning system, since we have multiple instances of it in the code already (see skeleton in #1004).

I would create two classes: SemVer and StrictSemVer: SemVer would accept a version from the SemVer standard (https://semver.org/) including pre-release versions, while StrictSemVer wouldn't accept them. This would give us a MAJOR.MINOR.PATCH system which could also incorporate changes that with the system proposed in this issue would result in no version change at all. We could then include a before validator for the model which could interpret strings to the contents of this model.

I also think that algorithmVersion is a field name that's specific but for no real reason. We can keep it generic and try to have everything fall under this umbrella, even the already existing versions

[mgazz]

This would give us a MAJOR.MINOR.PATCH system which could also incorporate changes that with the system proposed in this issue would result in no version change at all.

I tend to agree on having such approach. This way we increase MINOR version for each new functionality and PATCH for bugfixes or refactoring. As a byproduct, most changes (PR) will trigger an bump in the algorithm version and we need to remember to do this. (or automate this check as part of the CICD pipeline).

[AlessandroPomponio]

As a byproduct, most changes (PR) will trigger an bump in the algorithm version and we need to remember to do this. (or automate this check as part of the CICD pipeline).

I think it's the developer that should take care of that, we shouldn't be policing if people follow the rules or not

[michael-johnston]

Fine with Semver,

We can keep it generic and try to have everything fall under this umbrella, even the already existing versions

The thing to consider is we will have two versions to store/track. The plugin version (code sameness - #1002 ) and the experiment/operator version (scientific sameness)

The first so we can id the exact code that executed an experiment or find out what version of a plugin supplied a given "science semantic version".

The second for the reasons outlined above.

[AlessandroPomponio]

The thing to consider is we will have two versions to store/track. The plugin version (code sameness - #1002 ) and the experiment/operator version (scientific sameness)

The first so we can id the exact code that executed an experiment or find out what version of a plugin supplied a given "science semantic version".

The second for the reasons outlined above.

I didn't quite understand this here. For the plugin version we will need to have a slightly different type of versioning that is compatible with PEP440 (we already have something in OperatorMetadata (c.f. validate_version_is_pep440)

What I meant above is to have e.g., model versioning adopt this StrictSemVer versioning instead of having an arbitrary v1 or v2