refactor(config): give the tuned constants a real provenance, and make them reachable

Two problems, both of which made a number look more settled than it is.

The provenance was a dead link. config.hpp cited
docs/rep4-optimizer-results.md for prob_threshold, extinction_sec,
anneal_sec and the expansion default. That file was renamed to
model-bakeoff.md and then rewritten; the comments were never repointed,
so the most consequential constant in the pipeline appeared to have no
source at all.

Following it up produced something worse than a broken link.
prob_threshold=0.754 comes from the ORIGINAL rep4 document (still
readable at `git show d340da7:docs/rep4-optimizer-results.md`). The
rewrite that replaced it reports finding "a real scoring bug in
optimize.py: a candidate whose hardest film's replay timed out was
averaged over survivors instead of penalized, silently rewarding partial
coverage. Affected 3 of 16 training combos". So 0.754 was fitted under
scoring that was later found wrong, the corrected sweep converged
elsewhere, and no corrected prob_threshold is recorded anywhere. The
comment now says that, along with the surviving document's own verdict
that the optimum "generalizes unevenly -- strong on 3 of 5 held-out
films, badly broken on 2".

Four constants were unreachable. ownership_logodds lived on
TrackRegistry::Config, and max_views/admit_below/rho_max on
EvidenceDiscounter::Config, which main built with the one-argument
constructor -- so nothing short of a recompile could move any of them.
rho_max's own comment defers to "the sweep (VR-007)" for where it
belongs, and that sweep could not reach it.

They now live in Config with CLI flags and are exposed to the replay
harness. ownership_logodds is worth singling out: below it a track makes
no presence claim at all, so it decides whether an actor is reported
rather than how confidently -- arguably the most consequential constant
after prob_threshold, and until now unswept and unsettable.

No behaviour change: every default is the value that was compiled in.

TRACES: AR-025, AR-017 | SR-002
This commit is contained in:
2026-08-05 17:43:51 +02:00
parent 88c42573a5
commit 06373817a2
5 changed files with 106 additions and 12 deletions
+22 -2
View File
@@ -36,7 +36,14 @@
// AR-011). Lowering it runs the model off-distribution.
// --dense-scale <f> downscale decoded frames in scene-detect mode (0<f≤1,
// default 1=off). Speeds decode; keep ≥0.5 on 1080p.
// --max-faces <N> max faces kept per frame (default: 10)
// --max-faces <N> max faces kept per frame (default: 0 = uncapped)
// --ownership-logodds <f> belief needed to own a track (default: 2.0 ≈ P 0.88).
// Below it a track makes no presence claim at all.
// --evidence-rho-max <f> ceiling on correlation between two observations of
// one track (default: 0.5 = a repeated view is worth
// at most two independent ones). AR-025.
// --evidence-admit-below <p> P(same view) under this counts as a new look
// --evidence-max-views <N> distinct views remembered per track
// --expand-gallery enable per-film gallery expansion from track continuity
// --expand-buffer <N> per-track diversity buffer size (default: 20)
// --expand-band-lo <p> store admission floor, P(same person) (default: 0.90)
@@ -166,6 +173,10 @@ static Config parse_args(int argc, char** argv) {
else if (arg("--track-min-iou")) cfg.track_min_iou = std::stof(next());
else if (arg("--track-min-prob")) cfg.track_assoc_min_prob = std::stof(next());
else if (arg("--track-extinction")) cfg.track_extinction_sec = std::stod(next());
else if (arg("--ownership-logodds")) cfg.ownership_logodds = std::stof(next());
else if (arg("--evidence-rho-max")) cfg.evidence_rho_max = std::stof(next());
else if (arg("--evidence-admit-below")) cfg.evidence_admit_below = std::stof(next());
else if (arg("--evidence-max-views")) cfg.evidence_max_views = std::stoi(next());
else if (arg("--expand-gallery")) cfg.expand_gallery = true;
else if (arg("--expand-buffer")) cfg.expand_buffer_size = std::stoi(next());
else if (arg("--expand-band-lo")) cfg.expand_band_lo = std::stof(next());
@@ -253,8 +264,17 @@ int main(int argc, char** argv) {
auto same_person = same_person_probability(matcher_fn.calibration());
TrackRegistry::Config reg_cfg;
reg_cfg.track_extinction_sec = cfg.track_extinction_sec;
reg_cfg.ownership_logodds = cfg.ownership_logodds;
/// TRACES: AR-025 | SR-002
// The discounter's parameters come from Config now. They used to be
// in-class defaults reached through the one-argument constructor, so the
// VR-007 sweep that rho_max's own comment defers to could not vary it.
EvidenceDiscounter::Config disc_cfg;
disc_cfg.max_views = cfg.evidence_max_views;
disc_cfg.admit_below = cfg.evidence_admit_below;
disc_cfg.rho_max = cfg.evidence_rho_max;
auto registry = std::make_shared<TrackRegistry>(
reg_cfg, EvidenceDiscounter(same_person));
reg_cfg, EvidenceDiscounter(same_person, disc_cfg));
matcher_fn.set_registry(registry);