1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
//! Where the `VERSIONED_OBJECT` spec functions are realized — and why none of
//! them is realized HERE (hand-written spec behaviour; documentation only, by
//! design).
//!
//! Spec: RM
//! `docs/specs/openehr/RM/docs/UML/classes/org.openehr.rm.common.versioned_object.adoc`
//! §Functions declares fourteen operations on a version container:
//! `version_count`, `all_version_ids`, `all_versions`, `has_version_at_time`,
//! `has_version_id`, `version_with_id`, `is_original_version`,
//! `version_at_time`, `revision_history`, `latest_version`,
//! `latest_trunk_version`, `trunk_lifecycle_state`, plus the four committal
//! operations `commit_original_version`, `commit_original_merged_version`,
//! `commit_imported_version` and `commit_attestation`.
//!
//! NONE of them is a function of the generated value. `VERSIONED_OBJECT`
//! declares exactly three attributes — `uid`, `owner_id`, `time_created` — and
//! the versions themselves are not among them: the container's contents are
//! held by the repository, not by the object. Every function above therefore
//! needs repository context (a read of the version set, or a write into it)
//! that no in-memory `VersionedObject` value can supply, and an implementation
//! over the three attributes could only fabricate an answer — for instance a
//! `version_count` of zero on a container that in fact holds versions, which is
//! precisely the silent wrong answer this codebase refuses to produce.
//!
//! They ARE realized, in the CDR's own layers, over the stored version set:
//!
//! - the twelve query functions by `ferroehr::versioning` (the `read` and
//! `wire` modules: current / by-`VERSION_TREE_ID` / by-ordinal / as-of-instant
//! reads, the `VERSIONED_OBJECT` container body, and the `REVISION_HISTORY`
//! assembly) over `ferroehr::storage::version_repo`;
//! - three of the four committal functions: `commit_original_version` by
//! `ferroehr::versioning::change` (the shared commit engine behind the direct
//! writes and the CONTRIBUTION route), `commit_imported_version` by
//! `ferroehr::versioning::import` (the wrapping of a received
//! `ORIGINAL_VERSION` in an `IMPORTED_VERSION`), and `commit_attestation` by
//! `ferroehr::versioning::attestation`.
//!
//! NOTE: the fourth, `commit_original_merged_version`, has NO realization —
//! deliberately. It is the merge commit whose `an_other_input_uids:
//! List<OBJECT_VERSION_ID>[1]` becomes
//! `ORIGINAL_VERSION.other_input_version_uids` (§Functions;
//! `master06-change_control_package.adoc` §Version Merging), and the released
//! REST wire declares no shape for it at all: `UpdateVersion.yaml` has no such
//! property and `NewContribution.versions` items are `UpdateVersion` with no
//! discriminator, so no client can ask for a merge commit. Merge provenance is
//! PRODUCE-only — `OriginalVersion.yaml` declares it on reads, and it reaches
//! storage only through the routes that reproduce a FOREIGN `ORIGINAL_VERSION`
//! verbatim (§Copying: "the `ORIGINAL_VERSION` instance is never modified"),
//! which is `commit_imported_version`'s path, not this one. The absence is the
//! conformant behaviour, not a gap.
//!
//! This module exists so that fact is written down beside the class it belongs
//! to, rather than left as an unexplained absence next to the sibling
//! `version_impl` / `original_version_impl` / `imported_version_impl` files —
//! whose functions ARE value-realizable and are realized there.