# Ön-kayıt — Proje 01: Regression gate istatistiği

Bu dosya ilk tam koşudan önce yazıldı (2026-10-17). Her koşu, dosyanın SHA-256 özetini `results/env.json` içine yazar. Koşudan sonra bu dosyada yapılan her değişiklik makalede "ön-kayıttan sapma" olarak raporlanır.

## 1. Sabitler

| Parametre | Değer |
|---|---|
| Ana seed | `20261017` |
| Veri | BEIR NFCorpus, FiQA-2018, SCIDOCS; `test` qrels |
| Popülasyon | Test qrels'te `score > 0` olan en az bir belgesi bulunan sorgular |
| Belge metni | `title + " " + text` |
| Dense modeller | `BAAI/bge-small-en-v1.5` (sorgu öneki: model kartındaki retrieval talimatı), `sentence-transformers/all-MiniLM-L6-v2`, `intfloat/e5-small-v2` (`query: ` / `passage: `); `max_seq_length = 256`; L2-normalize, iç çarpım |
| BM25 | `bm25s`, İngilizce stopword listesi, stemmer yok, varsayılan k1/b |
| Exact sistemler | `bm25`, `bge`, `minilm`, `e5`; FAISS `IndexFlatIP`; top-100 |
| HNSW sistemleri | `hnsw_ef{16,32,64,128}_s{0..9}`: bge-small vektörleri, FAISS `IndexHNSWFlat`, M=16, efConstruction=200, tek iş parçacığıyla inşa, ekleme sırası seed'e göre permütasyon; top-10 (FAISS `ef = max(efSearch, k)` kullandığı için k=10) |
| Türetilmiş sistemler | `del05`, `del10`: `bge` top-100'den korpusun seed'li %5 / %10'u çıkarılır, kalan ilk 10 kullanılır. `ctl01`, `ctl02`, `ctl03`, `ctl05`: `bge`'den seed'li sırayla seçilen ve Recall@5 > 0 olan sorgularda ilgili belgeler top-10 dışına itilir (o sorgunun metrikleri 0 olur); popülasyon ΔRecall@5 hedefe (−0.01 / −0.02 / −0.03 / −0.05) ulaşınca durulur |
| Metrikler | Recall@5 (birincil), nDCG@10 (ikincil), Recall@10 ve MRR@10 (rapor) |
| Golden set boyutu | n ∈ {25, 50, 100, 200, 300}, yalnız n ≤ N/2 |
| Alt örnek | R = 2000, iadesiz; aynı alt örnekler bütün senaryo ve gate'lerde kullanılır |
| Bootstrap | B = 2000, percentile yöntemi; tek yönlü α = 0.05 |
| Non-inferiority marjı | m ∈ {0.01, 0.02, 0.03} |
| Eşiğe uzaklık | d ∈ {−0.05, −0.04, …, +0.05}; τ = m_gerçek − d |
| Headroom (G1, senaryo çiftleri) | h ∈ {0.02, 0.05}; τ = m_gerçek(A) − h |
| Gerçek tanımları | (a) sonlu popülasyon: tüm N sorgu. (b) yarı bölme: seed'li permütasyonla iki yarı; alt örnek A yarısından, gerçek B yarısında ölçülür |
| Latency | Yalnız FiQA; 2 iş parçacığı (HF CPU Basic profili); sistemler `bm25`, `bge`, `minilm`, `e5`, `hnsw_ef16_s0`, `hnsw_ef128_s0`; her koşu öncesi 20 sorgu ısınma; 10 koşu; her koşuda sorgu sırası seed'li karıştırılır |

## 2. Gate tanımları

- **G1 mutlak eşik:** PASS ⇔ m̂_B ≥ τ.
- **G2 naif delta:** PASS ⇔ m̂_B − m̂_A ≥ −m.
- **G3 paired non-inferiority:** dᵢ = metrik_B,ᵢ − metrik_A,ᵢ; PASS ⇔ dᵢ ortalamasının tek yönlü %95 percentile bootstrap alt sınırı ≥ −m.
- **G3u unpaired:** A ve B bağımsız bootstrap ağırlıklarıyla yeniden örneklenir; ortalama farkının alt sınırı ≥ −m ise PASS.
- **G3′ sign-flip:** H0: ortalama(d) ≤ −m. d + m üzerinde 2000 işaret çevirmesi; p < 0.05 ise PASS.
- **GL latency:** PASS ⇔ P95'in tek yönlü %95 quantile bootstrap üst sınırı ≤ SLA.

Bir senaryo çifti için "kabul edilebilir" gerçeği: Δ_gerçek ≥ −m. Yanlış FAIL = kabul edilebilir iken FAIL; yanlış PASS (kaçırma) = kabul edilemez iken PASS.

## 3. Hipotezler ve karar kuralları

Birincil analiz: Recall@5, gerçek tanımı (a). Gerçek tanımı (b) ve nDCG@10 aynı kurallarla ikincil olarak raporlanır.

| # | Hipotez | Destek kuralı |
|---|---|---|
| H1 | Küçük golden sette, gerçek değer eşiğe yakınken G1 sık yanılır. | n = 100 ve \|d\| = 0.02 (iki işaret) için `bm25`, `bge`, `minilm`, `e5` havuzlanmış G1 hata oranının Wilson %95 alt sınırı ≥ 0.15; en az 2/3 veri setinde. |
| H2 | Baseline eşiğin rahatça üstündeyken G1 gerçek regresyonu kaçırır (headroom maskeleme). | Senaryo `bge → ctl03`, h = 0.05, n = 100: G1 PASS oranı ≥ 0.50 **ve** alt örnek başına (G1 PASS − G3 PASS, m = 0.02) farkının ortalamasının %95 normal CI alt sınırı > 0; en az 2/3 veri setinde. |
| H3 | Aynı α'da eşleştirme, kabul edilebilir değişikliklerde yanlış FAIL'i azaltır. | No-op ailesi (`hnsw_ef16_s0 → s1..s9` ve `hnsw_ef128_s0 → s1..s9`, havuzlanmış), m = 0.02, n ∈ {50, 100}: alt örnek başına (G3u FAIL − G3 FAIL) farkının ortalamasının %95 CI alt sınırı > 0; her iki n için, en az 2/3 veri setinde. |
| H4 | HNSW ekleme sırası exact aramada olmayan bir metrik oynaması yaratır ve bu oynama ef_search arttıkça azalır. | (i) ef = 16'da seed'ler arası ikili \|ΔRecall@10\| dağılımının 95. persentili > 0, bütün veri setlerinde; (ii) bu persentil ef ∈ {16, 32, 64, 128} boyunca artmaz (monoton azalan veya sabit), en az 2/3 veri setinde. |
| H5 | P95 tahmini P50'den belirgin şekilde daha belirsizdir. | 6 sistemin en az 4'ünde: (i) koşu içi göreli CI genişliği oranı (P95 / P50) medyanı ≥ 2; (ii) koşular arası CV(P95) > CV(P50). |

Raporlanan ama hipotez olmayan analizler: G2'nin yanlış PASS oranı; G3′ ile G3 uyumu; analitik MDE ile simülasyon gücü arasındaki sapma; GL ve nokta-tahminli latency gate'inin yanlış FAIL oranları; gerçek tanımı (b) sonuçları.

## 4. Spec v0.1'den sapmalar (koşudan önce)

1. **H3 yeniden tanımlandı.** G2 hata oranını kontrol etmediği için "aynı α'da G3 vs G2" karşılaştırması tanımsız. H3 artık eşleştirmenin etkisini (G3 vs G3u) ölçüyor; G2 betimsel raporlanıyor.
2. **HNSW için hnswlib yerine FAISS `IndexHNSWFlat`.** hnswlib'in Windows için hazır wheel'i yok; FAISS zaten bağımlılık. "Seed" = ekleme sırası permütasyonu; inşa tek iş parçacığıyla yapılır.
3. **Python 3.12** (uv ile kurulu; 3.11 yerine).
4. **Karar kayıtları özet olarak saklanır:** (k PASS, R) ve seed. Alt örnek indeksleri seed'den yeniden üretilebilir; satır satır karar tablosu yayımlanmaz.
5. **Latency yalnız FiQA'da** ölçülür (en büyük korpus; süre bütçesi).
6. **`max_seq_length = 256`** bütün dense modellerde (CPU süresi). Model kalitesi bu projenin iddiası değil.
7. **HNSW top-10** (FAISS ef = max(efSearch, k); top-100 istenirse ef_search etkisiz kalır).