Proposal: add structured SAPIENT version compatibility diagnostics

[sylvesterkaczmarek]

Problem

Apex supports multiple SAPIENT protocol versions and performs upgrade/downgrade translation between them. Some fields and enum values are not representable across versions, so translation can be lossy or fail.

Today these cases are primarily surfaced through logs. That makes it difficult for operators and integrators to know whether a message was translated exactly, translated with information loss, or could not be represented in the target version.

This is already visible with BSI Flex 335 v2.0 features such as extensible taxonomy docking and mobile-node command types that do not exist in v1.0.

Proposal

Add structured compatibility diagnostics to the translation layer while preserving the current translation API and routing behaviour.

A translation diagnostic could report:

• source and target SAPIENT versions
• status: exact, lossy, unsupported, or failed
• affected field path
• action taken, e.g. dropped, mapped, or defaulted
• human-readable reason

The initial implementation should be deliberately small:

1. add a diagnostics/result model
2. instrument the existing v1 ↔ v2 translators
3. add regression tests for known non-representable v2 fields
4. keep existing callers backward-compatible
5. emit structured warnings through the existing logging path

A later phase could expose this through the REST API or GUI as a compatibility inspector / dry-run check.

Why this is useful

• makes mixed-version SAPIENT deployments easier to debug
• prevents silent or opaque information loss during downgrade
• gives integrators an explicit compatibility story as the BSI Flex evolves
• provides a reusable framework for future SAPIENT versions instead of handling each incompatibility ad hoc
• does not require changing the SAPIENT wire standard

I would be happy to take ownership of an initial implementation if this direction is useful.