Parameter data model (DCM2/CDFX) for synarius-core v0.5

Status

Status:

Draft concept (hardening iteration)

Supersedes:

parameters_data_model_dcm2_cdfx_v0_4.rst

Scope:

ownership and mutation safety hardening

1. Purpose of this iteration

This iteration keeps the existing architecture and hardens two critical rules:

  • data_set ownership of mutable state.

  • ndarray exposure safety for guarded-write integrity.

No redesign is introduced.

2. Hard ownership rule (normative, unambiguous)

Definitions:

  • data_source: imported external artifact metadata.

  • data_set: mutable working parameter state.

Normative ownership:

  • All mutable parameter state MUST be owned by data_set_id.

  • data_source MUST NEVER own mutable parameter state.

  • Any schema/API path that implies mutable-state ownership by data_source is invalid in this model.

Operational implications:

  • All mutable parameter rows (base + detail tables) MUST be addressable by data_set_id.

  • data_source references are informational/provenance linkage only.

  • Query and mutation APIs MUST resolve mutable state through dataset scope.

Rationale:

  • Prevents dual ownership, inconsistent updates, and ambiguous query semantics.

3. Guarded-write integrity vs ndarray mutability

Problem statement:

  • numpy.ndarray is mutable.

  • Returning mutable ndarray references can bypass setter/guard logic.

Normative safety rule:

  • Repository MUST NOT expose mutable ndarray references that can bypass guarded mutation.

Allowed read return modes:

  • read-only ndarray view (arr.flags.writeable = False), or

  • defensive copy.

Forbidden behavior:

  • Returning writable references to repository-owned arrays.

  • Any mutation path that changes persistent state without guarded setters/commands.

Mutation contract:

  • Persistent updates MUST occur only through guarded mutation APIs (CLI/GUI parity unchanged).

  • CLI and GUI MUST use the same guarded setter paths.

4. Deterministic error behavior (applies to both hardening points)

  • Violations of ownership or ndarray safety rules MUST raise deterministic errors.

  • Silent fallback, implicit correction, or hidden mutation MUST NOT occur.

5. Compatibility with prior iteration

All v0.4 rules remain in force unless tightened by this document.

In particular, unchanged:

  • parameters as API/facade,

  • repository abstraction,

  • virtual cal_param attributes,

  • guarded writes,

  • dataset-centric consistency,

  • replayable deterministic command logging.

6. Current implementation alignment

Current core implementation aligns with this hardening as follows:

  • ParametersRepository is DuckDB-backed and used as the canonical mutable-state backend.

  • Runtime default is process-local in-memory DuckDB (no shared external DB handle in normal operation).

  • ndarray reads at repository boundaries are returned as copy or explicitly read-only arrays.

  • Guarded mutation path remains mandatory for persistent changes.

7. DCM metadata mapping (implemented subset)

The current DCM importer intentionally supports a focused subset for deterministic ingest. Besides numeric payload and axis points, the following metadata is mapped:

  • Parameter-level

    • LANGNAME -> display_name

    • EINHEIT -> unit

    • VAR / FUNKTION -> source_identifier (concatenated key/value parts)

  • Axis-level

    • LANGNAME_X -> axis 0 name

    • LANGNAME_Y -> axis 1 name

    • EINHEIT_X -> axis 0 unit

    • EINHEIT_Y -> axis 1 unit

Storage/model surface:

  • Parameter metadata remains in parameters_all.

  • Axis metadata is stored in parameter_axis_meta keyed by (parameter_id, axis_index).

  • Runtime virtual attributes expose these fields as xN_name and xN_unit (with N in 1..5) for CLI/GUI parity.

Behavior rules:

  • Missing metadata is represented as empty string.

  • Metadata parse is case-insensitive by keyword.

  • For malformed recognized metadata lines (keyword without value), parsing fails deterministically.

  • Existing DCM files without metadata remain valid and import-compatible.