production-analytics/docs/material-calibrations.md

Material calibrations

Process calibration values live in the version-controlled config/material-calibrations.yaml. Calculations refer to opaque IDs; IDs have no special meaning to the parser. The current entry is:

calibrations:
  bento1-spreader-1-2:
    type: rotational_discharge
    value: 2.75
    unit: kg_per_rev_m
    calibrated_at: 2026-09-08
    method: gravimetric_tray
    description: Bento 1 fresh-bentonite spreaders 1 and 2
    reference:
      measured_application_g_m2: 4068
      line_speed_m_min: 2.3
      signal_values:
        left: 1.65
        right: 1.75

All entry fields are required. Type, unit, method and description are non-empty strings; value must be a finite number (booleans are rejected); calibrated_at is a calendar date in YYYY-MM-DD format, quoted or unquoted. Reference is a non-empty mapping whose contents preserve source-specific measurement provenance. Unknown entry fields and duplicate YAML keys are rejected. The generic registry permits other types and units; each consuming calculation checks its own compatibility.

config/bento1-material-consumption.yaml contains calibration_ref: bento1-spreader-1-2. During configuration loading, references resolve from material-calibrations.yaml in the calculation file's directory, independently of the working directory. The entire registry is validated when a reference is used. Rotational discharge requires type rotational_discharge, unit kg_per_rev_m and a positive value. Resolution supplies the existing specific_discharge_kg_per_rev_m runtime field for both application and consumption; the calculation algorithms are unchanged. There is no unit conversion.

Missing/unreadable files, missing IDs, invalid metadata and incompatible type or unit raise CalculationConfigError before a runner starts. Existing direct numeric configurations remain supported; specifying both a reference and a direct factor is rejected. References are currently supported by rotational discharge consumers. K7 uses direct mass rate and does not load or require a calibration file.

Updating a calibration

After a physical measurement, edit only the central entry's value, date, method and reference details, and keep its ID stable. Review and version-control the change. Additional machines can add new IDs using the same structure. A new calculation type needs an explicit consumer compatibility contract.

Ship the central YAML alongside the calculation YAML and restart the consuming process to load changes. No new CLI flag, environment variable, database migration or UI is required. There is no hot reload or historical date-based selection. Changes affect future calculations and explicitly rebuilt calculations. Historical persisted snapshots are not automatically recalculated. Existing checkpoints retain accumulated totals, so subsequent increments use the newly loaded factor; a complete historical rebuild requires a separately planned replay. Persisted snapshots do not gain calibration-version provenance through this change.

Current Bento provenance

On 2026-09-08, an independent gravimetric tray measurement found 4068 g/m² at 2.3 m/min with actual rotational signals left 1.65 and right 1.75. (4068 / 1000) × 2.3 / (1.65 + 1.75) ≈ 2.75188 kg/(rev*m) gives the configured rounded factor 2.75 kg/(rev*m). The original measurement remains recorded, without fitting or adjusting the runtime value to reproduce it exactly.

Only fresh-bentonite spreaders 1 and 2 are included. Before adding spreader 3, confirm its material scope, actual signal units, independent calibration and whether its output belongs in the fresh-material KPIs. No spreader 3 support is included here.