Why coordinated versioning matters
A dosing recommendation is produced by a chain of components, not by model code alone. A model may use a parameter set; incoming clinical records may be interpreted and transformed by data mappings; and an interface may determine which values are requested, submitted, or shown. Changing any of these can change the meaning or result of a recommendation—even when the model code has not changed.
For a recommendation to be reconstructable, its record must identify the exact components used, the input data as received or a retrievable reference to them, and the relevant execution context. A label such as “current dosing model” is not sufficient: it may point to a different artifact tomorrow, and it does not say which mapping or interface was in effect.
The key design choice is to version components separately and bind their exact versions together in a release manifest. Separate versions make changes visible and support controlled reuse. The manifest makes clear which combination was actually deployed. Neither part replaces the other.
Define what is versioned and what a change means
Give each artifact type its own identifier namespace. For example, model code might be labeled \(M\), a parameter set \(P\), a data mapping \(D\), and an interface \(I\). These labels are illustrative; a production system should define its own stable naming convention. Record a human-readable version and an integrity identifier, such as a cryptographic hash, for each immutable artifact.
A versioning policy should state how versions change. One common policy uses three numbers: major, minor, and patch. A major increment indicates an incompatible change; a minor increment indicates a backward-compatible addition; and a patch increment indicates a backward-compatible correction. The policy must define “compatible” for each artifact type. For a clinical mapping, for example, changing a field’s units or meaning is not a patch merely because a software interface still accepts the field. It can alter the clinical input to the model.
Version labels communicate a change under the stated policy; they do not prove that two components are compatible or that their clinical behavior is equivalent. A model-code change that alters the equations, a parameter change that alters fitted values, or a transformation change that alters dose or time interpretation must be explicitly identified. A release process should assess those effects and document its decision, rather than relying on the version number to imply safety.
A release manifest binds together the actual dependencies. It should include exact artifact versions, immutable artifact references or hashes, and declared compatibility constraints. It should also identify other configuration that can affect the output, such as a dosing policy or model execution configuration, where applicable. “Use the latest mapping” is not an exact dependency.
Here \(R\) denotes a release, while \(M_i\), \(P_j\), \(D_k\), and \(I_\ell\) identify particular model, parameter, mapping, and interface artifacts. \(E_q\) stands for a specified execution environment or configuration when it can affect the result. The tuple is a coordination record, not a claim that any arbitrary combination is valid.
Make compatibility explicit
Compatibility is a relationship among versions, not a property of a version number in isolation. A parameter set may be valid only for a specific model structure or parameterization. A mapping may emit data in a schema the model service does not accept. An interface may collect values that a mapping interprets differently than the interface author intended.
For each artifact, document its input and output contract: names, units, allowed values, time conventions, required fields, and relevant meanings. Then declare which versions or contract ranges it supports. For example, a model artifact may declare that it accepts data schema \(D\) versions 3.1 and 3.2, while a particular parameter set may be qualified only for model \(M\) versions 2.1. A release is eligible only if all stated constraints are satisfied and the combination has been reviewed through the release process.
| Artifact | Record at minimum | Compatibility concern |
|---|---|---|
| Model code | Version, immutable build or source reference, input and output contract | Parameterization and accepted input schema |
| Parameter set | Version, values or immutable reference, intended model identifier | Correct model structure, units, and parameter meanings |
| Data mapping | Version, source and target schemas, transformation rules | Field meaning, units, missing-value handling, and time alignment |
| Interface | Version, request and response contract, relevant display configuration | Fields collected and interpretation of returned values |
The manifest should be stored with the deployed release and referenced by each recommendation record. The record should also capture enough information to identify the relevant input snapshot or source records and their transformation path. Protect patient information according to applicable policy; reconstructability does not justify retaining unnecessary identifiable data. A content hash can help detect whether an artifact has changed, but cannot by itself explain its meaning, show that it is compatible, or recover a missing artifact.
Worked Example: Pinning a Release Manifest
Consider a hypothetical service with model \(M_{2.1.0}\), parameter set \(P_{4.0.0}\), data mapping \(D_{3.2.0}\), and interface \(I_{1.5.0}\). The release team records that \(P_{4.0.0}\) is intended for \(M_{2.1.0}\), that the model accepts the output schema from \(D_{3.2.0}\), and that \(I_{1.5.0}\) sends the request contract expected by the service. These statements are checked against the documented contracts; the matching version numbers alone would not establish compatibility.
The team creates release \(R_{2026.04.1}\) and records the four exact versions, each artifact’s immutable registry reference and hash, plus the execution image identifier. The deployment configuration points to that release identifier rather than to independent “latest” versions. A recommendation record then stores \(R_{2026.04.1}\), a reference to the relevant input snapshot, and the execution timestamp.
If the service must be investigated later, the release identifier resolves to one exact set of artifacts. The input reference identifies the data presented to that release, and the execution record identifies the relevant environment. The team can therefore distinguish a change in model code from a change in data interpretation or interface contract. This is a traceability claim; it does not, by itself, demonstrate that the output is clinically correct.
Worked examples of changes and reconstruction
Worked Example: A Data-Mapping Change Alters Meaning
Suppose a hypothetical mapping \(D_{3.2.0}\) converts a source dose of 0.25 g to 250 mg before sending it to the model. A later source system begins sending the dose in milligrams, but the old mapping remains active. It interprets 250 as grams and converts it to 250,000 mg. The model code and parameters have not changed, yet the model receives a dose one thousand times larger than intended.
The correct response is not to describe this as a model update. The data mapping’s input contract has changed: the source field’s unit differs. The mapping must be revised and assigned a new version, with its expected source units and transformation documented. The release manifest must then bind the revised mapping to a compatible model and interface. Until that release is available and approved, the affected combination should not be represented as the new supported configuration.
The arithmetic makes the risk concrete: \(0.25\text{ g}\times1000\text{ mg/g}=250\text{ mg}\), whereas interpreting the source value 250 as grams yields \(250\text{ g}\times1000\text{ mg/g}=250{,}000\text{ mg}\). The discrepancy arises before model execution. Checking only the model-code version would miss it.
Worked Example: Managing a Parameter-Set Update
A hypothetical release uses model \(M_{2.1.0}\) and parameter set \(P_{4.0.0}\). A new analysis produces proposed parameters \(P_{4.1.0}\), with the same parameter names, units, and model structure. The versioning policy treats this as a distinct parameter-set revision; the unchanged interface does not make the new parameter values interchangeable with the old ones.
The release team first checks the parameter set’s declared model compatibility and its units and meanings. It then creates a new release identifier that pins \(M_{2.1.0}\) together with \(P_{4.1.0}\), as well as the exact mapping, interface, and execution configuration. The earlier release remains available for interpreting recommendations made under it; it is not overwritten.
If an investigation concerns a recommendation created under \(P_{4.0.0}\), resolving the recorded release must retrieve that set, not the current parameter set. A pointer that silently resolves to \(P_{4.1.0}\) would substitute a different input to the model and would not reconstruct the original calculation.
Worked Example: Detecting an Interface and Mapping Mismatch
A hypothetical interface \(I_{1.5.0}\) submits a sample time as elapsed hours after a dose. A new interface \(I_{2.0.0}\) submits the same field as a clock timestamp. The existing mapping \(D_{3.2.0}\) still interprets the field as elapsed hours. Both components may accept a numeric value, but their contracts assign it different meanings.
To assess the proposed release, compare the interface’s request contract with the mapping’s expected input contract. The time-field definitions do not match, so the combination is incompatible even if a request passes basic type checks. The team must either retain a compatible interface, revise the mapping to handle the new timestamp convention, or provide an explicit conversion component. It must then assign appropriate versions and pin the compatible combination in a new manifest.
This example shows why checking only field names or data types is inadequate. “Time” could mean elapsed hours, local clock time, or an absolute timestamp; compatibility requires shared meaning and conventions, not merely a field that can be parsed.
Justifying the coordinated approach
The need to record each component separately follows from how the recommendation is produced. Let \(x\) denote source data, \(T_D\) the transformation implemented by mapping version \(D\), and \(F_{M,P}\) the model calculation for code version \(M\) and parameter set \(P\). Abstractly, the displayed recommendation can be represented as:
Here \(I\) represents the interface’s handling or presentation of the result. If any component changes, the overall result or its interpretation can change. In particular, holding \(M\) fixed does not ensure \(y\) is unchanged when \(P\), \(D\), or \(I\) changes. Therefore, identifying only \(M\) cannot identify the full computation or user-facing recommendation. Recording the exact tuple and input reference is necessary to identify what was used; keeping the referenced artifacts immutable makes that record resolvable later.
This is a traceability argument, not a guarantee that a system will always reproduce bit-for-bit identical output. Some computations may depend on execution environment, time-sensitive external data, or nondeterministic behavior. Such dependencies should be recorded or explicitly bounded by the system’s reproducibility requirements. If an artifact or input snapshot is not retained, its identifier may document what was used without making reconstruction possible.
Operational checks, alternatives, and limitations
Common warning signs include a recommendation record containing only a product name, a manifest that points to mutable “latest” tags, an unversioned unit conversion, or a parameter set without a stated compatible model. Other warning signs are a version change that lacks a description of what changed, an interface that changes field meaning without a contract update, and artifacts that can no longer be retrieved by their recorded identifiers. These are traceability failures even when the service appears to run normally.
A single version number for the entire product is simple to communicate, but can conceal which component changed and make it difficult to reuse or investigate an unchanged component. Independent component versions without a release manifest preserve detail but leave ambiguity about which combination was deployed. A source-code commit identifier alone cannot identify parameter files, transformations, interface behavior, or deployment configuration. Semantic versioning can help communicate intended compatibility, but only when the policy is explicit and applied consistently; the label is not a compatibility test.
A practical scheme combines both approaches: give each artifact a separate, immutable version; publish an immutable release identifier that pins the compatible combination; and store that release identifier with each recommendation record. Keep human-readable change descriptions alongside machine-readable manifests, since neither serves the other’s purpose. Maintain access to released artifacts for the retention period required for audit and clinical review.
Versioning has limits. It cannot repair incorrect source data, establish that a model is clinically appropriate, or guarantee that a deployment has captured every dependency. It also does not replace controlled change review or deployment governance. Its contribution is narrower and essential: it makes the components and contracts behind a recommendation identifiable, reviewable, and, when the inputs and artifacts are retained, reconstructable.
Check Your Understanding
Answer each question, then compare your reasoning with the solutions.
- Why does recording a model-code version alone not identify the complete recommendation process?
- A mapping changes a source concentration from micrograms per milliliter to milligrams per milliliter. What should be versioned, and what should the release record specify?
- What does a cryptographic hash establish about an artifact, and what does it not establish?
- An interface changes a time field from elapsed hours to a timestamp, while retaining the same field name. Why might the existing mapping be incompatible?
- Explain the difference between a component version and a release identifier.
Solutions. (1) The parameter set, transformed input, interface behavior, and potentially execution configuration can also affect the result or its interpretation; these must be identified too. (2) Assign a new mapping version and document the source and target units and conversion. Pin that version in a release manifest with the exact compatible model, parameters, interface, and relevant configuration. (3) A hash can identify or detect a change to the exact artifact bytes. It does not explain the artifact’s meaning, prove compatibility or correctness, or recover an artifact that is no longer available. (4) The mapping may interpret the value as a duration when the interface now supplies a clock time. Matching field names or data types does not ensure matching semantics. (5) A component version identifies one artifact revision; a release identifier binds exact versions of multiple compatible artifacts into the deployed combination.