1 ADR 0105 quality score c isolation absolute floor
Forgejo Actions edited this page 2026-10-05 16:59:20 +00:00

ADR 0105: Quality score C-isolation uses an absolute floor on the shared cosine scale

Status: accepted Date: 2026-10-05

Context

ADR 0103 defined the new_person_cluster isolation feature as the group's relational margin clamp01((d_nearest_external_identity - mean_intra_cluster_distance) / 0.15). Owner evaluation on the real production library (26,619 faces, threshold 0.45, 2026-10-05) invalidated that design: because a dense group's internal spread is small, the relational margin saturated — median C isolation was 1.0 while 771 of 3418 emitted C groups sat CLOSER than 0.50 (the old 0.35 threshold + safety margin) to the nearest confirmed person's centroid, and 103 had effectively zero margin. In the shared weights (0.35 cohesion + 0.25 isolation + 0.25 ambiguity + 0.15 size) this handed coherent identity-adjacent splinter groups ~0.13 points over merge cards: the run's 381 cluster_person_match cards ranked behind 192 weaker new_person_cluster cards (best merge card at carousel rank 193), reproducing the exact 'only New person suggestions' complaint ADR 0103 was written to fix. The user's review raised the semantic objection that both card types must be graded by the SAME standard: a new-person proposal must demonstrably NOT belong to any existing cluster, on the same scale the merge proposal's confidence lives on.

Decision

Change ONLY the C isolation feature to an absolute margin on the shared cosine-distance scale: clamp01((d_nearest_external_identity - 0.50) / 0.35). A group within 0.50 of the nearest confirmed person's centroid earns ZERO isolation credit regardless of internal coherence; full credit from 0.85. The 0.50 floor sits one step above the production clustering_max_distance (0.45): a group the clustering itself could plausibly have attached to a person must not earn an isolation bonus for exactly that proximity. mean_intra no longer enters the feature (the helper signature keeps the parameter for call-site stability); ambiguity (0.10 runner-up margin), cohesion, size and all ADR 0103 weights are unchanged; grouping, outcome gates, card shapes and validators are untouched — the change affects ONLY the persisted ranking score. Offline measurement with the changed code on the same library: best merge card rank 193 → 1, top-30 composition 0/30 → 15/15 B/C, while genuinely distant stranger groups keep their isolation credit (their d_nearest exceeds the old effective bar too). Because existing pending cards carry scores from the old formula, a clustering reset + rerun is required after deploy to re-score the board.

Consequences

New-person cards adjacent to known people no longer outrank merge cards; the owner sees family merge suggestions at the top of the carousel. The relational-margin semantics (a group graded against its own spread) are gone — a future outcome-based refit (ADR 0103's planned Platt-style recalibration over the owner accept/reject log) supersedes both anchors. 0.50/0.35 are documented worker constants (C_ISOLATION_FLOOR / C_ISOLATION_RANGE) and revisitable without contract changes; the score remains optional in the envelope and does not bump the clustering contract version.