docs(adr): ADR 0116 revision V7 — component-scoped weighted HAC with highest-valid-cut #1316

Merged
chris merged 1 commit from docs/adr-0116-highest-valid-cut into main 2026-10-19 23:21:57 +02:00
Owner

Summary

Amends ADR 0116 with decision V7 (revision, 2026-10-19): the first live v4 run (job fc05c137, ~31 min at pool 21194) showed that medoid nodes bridge previously separate U×U components into giant U∪R instances — and since HAC cost is quadratic in instance size ((a+b)²/(a²+b²) ≤ 2 per bridge), the global-HAC wording is unworkable at production scale.

V7: keep v4's identity-aware weighted HAC, but scoped per U×U component (the fine decomposition v3 uses) with only the representatives adjacent to it (rᵢ ≪ nᵢ), and replace the fixed cut with the highest-valid-cut: h* = the highest merge height ≤ clustering_max_distance at which every cut subset carries ≤ 1 identity bit (backward linear scan with bit-OR tracking, O(k)); if nothing ≤ threshold is valid, the deepest valid height anywhere. Mixed remainders surface via V6 margin demotion. Runtime returns to v3-class (Θ(d·Σ(nᵢ+rᵢ)²) ≈ Θ(d·Σ nᵢ²)) — honestly stated as NO speedup vs v3; the gain is quality (mixed components split into correct per-identity cards instead of ambiguous discard).

Also amends the validation plan: new G-A′ gate (CV re-run for the V7 lane; ambiguous target ≤ 100; same-person splits benign majority; harness runtime ≤ 2× v3 lane) + G-B fixtures 9–11 (cut unit tests, component-scoped equivalence incl. the rep-touching-two-components counter-case, runtime regression pin). Former V7 (Rollout) renumbered V8.

ISSUE-169/PR #1315 (compatiblePersonIds) is part of this baseline (merged before the revision).

Test plan

  • docs-only; JSON validated (python3 -m json.tool); programmatic assertions over status/date/title/links/decision blocks; word-diff reviewed.
  • G-A′ measurement runs in parallel (separate PR follows).
## Summary Amends ADR 0116 with decision **V7** (revision, 2026-10-19): the first live v4 run (job `fc05c137`, ~31 min at pool 21194) showed that medoid nodes bridge previously separate U×U components into giant U∪R instances — and since HAC cost is quadratic in instance size (`(a+b)²/(a²+b²) ≤ 2` per bridge), the global-HAC wording is unworkable at production scale. **V7:** keep v4's identity-aware weighted HAC, but scoped per **U×U component** (the fine decomposition v3 uses) with only the representatives adjacent to it (rᵢ ≪ nᵢ), and replace the fixed cut with the **highest-valid-cut**: h* = the highest merge height ≤ clustering_max_distance at which every cut subset carries ≤ 1 identity bit (backward linear scan with bit-OR tracking, O(k)); if nothing ≤ threshold is valid, the deepest valid height anywhere. Mixed remainders surface via V6 margin demotion. Runtime returns to v3-class (Θ(d·Σ(nᵢ+rᵢ)²) ≈ Θ(d·Σ nᵢ²)) — honestly stated as NO speedup vs v3; the gain is quality (mixed components split into correct per-identity cards instead of ambiguous discard). Also amends the validation plan: new **G-A′** gate (CV re-run for the V7 lane; ambiguous target ≤ 100; same-person splits benign majority; harness runtime ≤ 2× v3 lane) + G-B fixtures 9–11 (cut unit tests, component-scoped equivalence incl. the rep-touching-two-components counter-case, runtime regression pin). Former V7 (Rollout) renumbered V8. ISSUE-169/PR #1315 (compatiblePersonIds) is part of this baseline (merged before the revision). ## Test plan - docs-only; JSON validated (`python3 -m json.tool`); programmatic assertions over status/date/title/links/decision blocks; word-diff reviewed. - G-A′ measurement runs in parallel (separate PR follows).
docs(adr): ADR 0116 revision V7 — component-scoped weighted HAC with highest-valid-cut
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 3s
Build and Deploy / Run scoped PR tests (push) Has been skipped
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build Android CI image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
73aaca0b4a
chris merged commit 9d9977bf73 into main 2026-10-19 23:21:57 +02:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
chris/memories!1316
No description provided.