# Reconcilix Scoring

Dieser Bereich enthält die versionierten Spezifikationen für das
Candidate Scoring in Reconcilix.

## Zweck

Discovery und Scoring werden bewusst voneinander getrennt.

Discovery beantwortet:

> Welche Candidates wurden durch welchen Discovery Step und mit welcher
> Provider Evidence gefunden?

Scoring beantwortet:

> Wie stark bewertet Reconcilix die normalisierte Evidence für einen
> Candidate?

Ein Provider Score oder Provider Rank ist daher nicht automatisch ein
Reconcilix Score oder Rank.

## Evidence Layers

### DiscoveryResponseSnapshot

`DiscoveryResponseSnapshot` bewahrt die rohe Provider Response für
Auditierbarkeit und technische Analyse auf.

### CandidateDiscoveryEvidence

`CandidateDiscoveryEvidence` enthält normalisierte, Step-spezifische
Evidence. Im aktuellen Stand gehören dazu unter anderem:

-   `step_score`
-   `step_rank`
-   `matched_value`
-   `matched_value_role`
-   `matched_value_language`

`step_score` und `step_rank` bleiben Provider-/Step-Evidence. Das
Scoring darf diese Werte nicht überschreiben.

### CandidateItem

Im aktuellen Entwicklungsstand gilt:

-   `CandidateItem.score` enthält den von Reconcilix verwendeten
    konsolidierten Candidate Score.
-   `CandidateItem.rank` enthält den daraus resultierenden Candidate
    Rank.

Die endgültige Benennung und die Cross-Family Semantics dieser Attribute
sind bewusst **noch nicht festgelegt**. Sie werden erneut bewertet,
sobald Erfahrungen mit mehreren Discovery Families vorliegen.

## Grundsätze

1.  Scoring Rules werden versioniert.
2.  Eine Scoring Rule muss aus persistierter Evidence deterministisch
    und nachvollziehbar herleitbar sein.
3.  Die Discovery Method ist Evidence für das Scoring, aber nicht selbst
    der Score.
4.  Raw Provider Evidence bleibt von normalisierter Evidence getrennt.
5.  Provider Scores und Provider Ranks bleiben erhalten und werden nicht
    stillschweigend in Reconcilix Scores umgedeutet.
6.  Scoring Rules dürfen nicht voraussetzen, dass Scores verschiedener
    Discovery Families oder Provider unmittelbar vergleichbar sind.
7.  Regelmäßig benötigte semantische Evidence soll durch typisierte
    Attribute und nicht versteckt in generischen JSON-Strukturen
    repräsentiert werden.
8.  Eine Scoring Specification dokumentiert sowohl verwendete Regeln als
    auch Signale, die bewusst noch nicht verwendet werden.
9.  Änderungen an einer Scoring Formula erzeugen eine neue Version,
    statt eine bereits evaluierte Version nachträglich umzudefinieren.
10. Cross-Family Consolidation wird erst spezifiziert, nachdem mehrere
    Discovery Families praktisch evaluiert wurden.

## Aktuelle Specifications

  ---------------------------------------------------------------------------------------
  Discovery Family  Version           Specification                     Status
  ----------------- ----------------- --------------------------------- -----------------
  `LEXICAL`         `v0.1`            `lexical/LEXICAL_SCORE_v0.1.md`   implementiert /
                                                                        Evaluation
                                                                        Baseline

  ---------------------------------------------------------------------------------------

## Offene Architekturfragen

Folgende Punkte bleiben bewusst offen:

-   endgültige Benennung von `CandidateItem.score` und
    `CandidateItem.rank`
-   Aggregation von Evidence, wenn derselbe Candidate durch mehrere
    Methods oder Families gefunden wird
-   Verhältnis zwischen Family-specific Scores und einem zukünftigen
    Cross-Family Score bzw. Confidence
-   Rolle von ContextItems und Qualifiers
-   Kalibrierung Provider-spezifischer Scores
-   Scoring Semantics zukünftiger Families wie Vector Discovery