Add runs entry type and provenance relationships

[giovannipizzi]

In this commit we introduce the following additions to the OPTIMADE specification:

• Entry Type Categories: classifies every entry type as data,
  execution, or metadata. Standard types:
  runs/calculations → execution; references → metadata;
  structures/trajectories/files → data. An OPTIONAL category
  field is added to the Entry Listing Info Endpoint response.

• Reserved provenance relationship keys (in Entry Listing JSON Response Schema): inputs, outputs, output_of, input_for, source_of, derived_from are reserved and exempt from the grouping-by-entry-type rule. Category constraints, cardinality, and acyclicity rules are defined.

• Provenance Relation Objects (§ Provenance Relation Objects): the six provenance relationships resolve to reified edge objects (input_rel, output_rel, derived_rel) carrying a mandatory label and an optional workflow_uri (on derived_rel). The target key is reserved. Relationships can be filtered by label/workflow_uri via a standard OPTIMADE filters; fetching, pagination, and
  include=target conventions are specified.

• Runs Entries: new execution-category entry type representing a specific workflow execution (could also be experimental). Properties: workflow_uri (REQUIRED, nullable), inputs/outputs relationships.

• Provenance relationships on data entries: output_of (to-one, exclusive creator rule), input_for (unbounded to-many), source_of (unbounded to-many, per-source label uniqueness), derived_from (unbounded to-many, label non-uniqueness on incoming side, optional workflow_uri on edge).

• Calculations classified as execution category (potentially to be deprecated?)

• Worked examples (in Sec. Provenance Examples) illustrating all new relationships.

Note: all these changes are backward compatible.

Please follow the guidelines here to create a new pull request.
If your pull request requires discussion, make sure the OPTIMADE developer list is alerted (for more info see the link above.)

[giovannipizzi]

Open issues for discussion

The following points were flagged in the draft and might require explicit approval or discussion:

1. workflow_uri nullability (currently: REQUIRED-but-nullable): allows for providers to avoid creating an artificial URI just to respect the specs. -> DECISION: OK

2. Filter/sort support on relation objects beyond label and workflow_uri: the current text leaves broader query support unspecified (neither required nor prohibited). Should a minimum set of filter features be mandated for relation-object endpoints? -> DECISION: not decided, keep as is for now.

3. available_endpoints and entry_types_by_format: no wording change to Sec. 5.3/5.5.1 is needed (both already require implemented entry-listing endpoints to be reflected in the Base Info Endpoint). Implementers should add "runs" to available_endpoints and entry_types_by_format.json, and expose /info/runs. The three new relation types (input_rel/output_rel/derived_rel) are deliberately not added to available_endpoints. -> DECISION: OK

4. calculations classified as execution — future deprecation: the role of calculations is now unclear given the introduction of runs. Options: (a) deprecate in favour of runs; (b) give it non-overlapping semantics (e.g. its own inputs/outputs). This PR classifies it as execution and removes the old "future work" note. We should decide if we want to deprecate or remove in this PR directly. -> DECISION: deprecate

5. output_of single-and-exclusive-creator rule: a consequence is that two runs genuinely producing a byte-identical artifact MUST model them as two distinct data entries. The source_of/derived_from mechanism (unbounded) is the designated way to instead represent "returning" rather than "creating". Is this OK? -> DECISION: OK as is, but we will add a RETURN/CREATE separation of the output links (with different semantics).

6. Promoting relation types to top-level entry types: input_rel/output_rel/derived_rel are currently embedded-only (no /v1/input_rel endpoint). A future version MAY promote them to top-level entry points (in a backward-compatible way) if use cases for global cross-node queries emerge. For now, this does not seem needed. -> DECISION: Do NOT promote for now.

7. Acyclicity is required but server-unenforceable: the spec requires acyclicity but cannot mandate server-side verification. Clients MUST guard against cycles when traversing (this is written now as a note in the specs). -> DECISION: use SHOULD NOT for the requirement on the server (since it's not enforceable), but keep the discussion, and keep MUST NOT for the client recommendation.

8. meta fields on the to-one output_of related response: the output_of related endpoint returns a single relation object rather than a list. This PR treats it like a single-entry fetch (omits data_returned/data_available, shows only optional more_data_available). To be confirmed if this matches how the OPTIMADE spec usually populates meta fields on single-resource responses. -> DECISION: OK as is.

[rartino]

I have started to work through this in tandem with a mock-implementation.

Quite a bit of this PR is centered around the new "categorization" concept now declared via x-optimade-category- which thus comes with a non-negligible complexity cost for the specification. Two questions:

• Why does this not rather live in the top x-optimade-defintion field as simply category? We have all the other declarative information about the entity being defined there.

• This might be me dimmed by a couple of weeks of vacation, but did we discuss these category-based provenance limitations during the workshop? Do we need them?

What is a use-case for an OPTIMADE server implementer and/or an OPTIMADE API user that is served by these category declarations, vs., them just not being there? Meaning: without them, a database is allowed to represent provenance relationships between any entry types for which it deems it makes sense to declare such relationships for.