[API] setup_pointblank_agent : paramètre cols_reference mort, vecteur de référence embarqué dans chaque step, exemple roxygen trompeur

[VincentGuyader]

Contexte

setup_pointblank_agent() (R/pointblank_setup.R) est exportée mais présente plusieurs défauts d'API et de coût :

1. Paramètre mort : cols_reference (2e position, documenté) n'apparaît nulle part dans le corps — vérifié par grep (seules occurrences : signature + doc). L'appelant calcule et passe cette valeur pour rien ; la variable locale cols_candidate de l'appelant est morte en cascade.
2. Mémoire : sur le chemin local, chaque step d'égalité fait col_vals_equal(columns = c, value = cmp[[paste0(c, ref_suffix)]]) — le vecteur de référence entier est embarqué dans l'agent pour chaque colonne (O(n_rows) par step, sérialisé avec le rapport), et repose sur un value non scalaire hors du contrat documenté de pointblank.
3. Exemple roxygen trompeur : l'exemple passe tol_cols = "b" alors que cmp n'a pas de colonne b__ok — l'agent produit échouerait à l'interrogation. Il masque le vrai contrat (booléens __ok précalculés par le pipeline).
4. Export discutable : 15 paramètres dont 5 obligatoires sans défaut, couplage fort aux conventions internes (__ok, __eq, __missing_col_) ; en interne elle n'est plus appelée que sur le chemin d'échec avec add_col_exists_steps = FALSE. Par ailleurs get_col_names(cmp) est recalculé à chaque itération de la boucle des colonnes d'égalité.
5. Les colonnes d'égalité défaillantes (fail$eq) sont passées dans le paramètre nommé common_cols — la sémantique du nom ment.

Reprex

library(datadiff)
# 1. paramètre mort : la valeur passée n'a aucun effet
cmp <- data.frame(a = 1:3, a__reference = 1:3)
r1 <- setup_pointblank_agent(cmp, cols_reference = c("a"),        common_cols = "a",
                             tol_cols = character(0), NULL, "__reference", .1, .1, "x", TRUE)
r2 <- setup_pointblank_agent(cmp, cols_reference = c("INEXISTANT"), common_cols = "a",
                             tol_cols = character(0), NULL, "__reference", .1, .1, "x", TRUE)
# aucune différence de comportement

Critères de succès

• cols_reference retiré (dépréciation propre puisque exporté : warning une version, puis suppression) ; cols_candidate mort supprimé chez l'appelant.
• Steps d'égalité locaux basés sur un booléen précalculé (cf. issue perf sur la mémoïsation __eq) au lieu d'embarquer le vecteur de référence.
• Exemple roxygen exécutable et représentatif (avec __ok présent).
• Décision documentée sur l'export : @keywords internal ou maintien assumé avec doc du contrat ; paramètre renommé ou documenté pour common_cols/fail$eq.
• get_col_names(cmp) hissé hors boucle.