11 KiB
Phase 13 — Production Evidence Gate for Indexed Retrieval
وضعیت: Canary ۵٪ مسلح است. ترافیک زنده این فرآیند صفر است → HOLD. Promotion به ۱۰٪ ممنوع است. Adaptive K / Hybrid / Progressive خاموش می‌مانند.
تاریخ: ۲۱ اوت ۲۰۲۶
نتایج: evals/phase-13/latest.json
No live evidence, no promotion.
Gold proves the design is plausible; production evidence proves the feature is safe and useful.
Candidate indexing must be independently measurable from ranking, Adaptive K, Hybrid Search, and Schema Loading.
INDEXED_CANDIDATE_RETRIEVAL = False
INDEXED_CANDIDATE_ROLLOUT_PERCENT = 5
INDEXED_CANDIDATE_FALLBACK = True
ADAPTIVE_DISCOVERY_K = False
HYBRID_TOOL_DISCOVERY = False
PROGRESSIVE_SCHEMA_LOADING = False
Final K: Analyzer = 48 / Autonomous = 128
Candidate N = 100
این Phase معماری Retrieval جدید نمی‌سازد. Hybrid، embedding، Adaptive K، Progressive Schema و تغییر N ممنوع‌اند.
1. Production Evidence Model
دو منبع کاملاً جدا:
| منبع | برچسب | چه چیزی را ثابت می‌کند |
|---|---|---|
| Offline Gold | offline_gold |
طراحی قابل‌قبول است (Recall روی مجموعهٔ برچسب‌خورده) |
| Production Live | production_live |
ویژگی روی ترافیک واقعی امن و مفید است |
Gold Recall@100 = 100% ← فقط Offline Gold
Production Recall@100 ← وجود ندارد مگر از ترافیک زنده اندازه‌گیری شود
هرگز Gold را به‌جای Production گزارش نکن. در این فرآیند Live Control = 0 و Live Experiment = 0؛ نرخ‌ها null هستند نه صفرِ ساختگی.
۱۰k bench (~۶ms indexed / ~۱۱۰ms full rank) فقط Offline Performance Evidence است.
Indexing ≠ کاهش توکن. K هنوز ۴۸/۱۲۸ است. Indexing باید latency retrieval، CPU و مقیاس را بهتر کند. توکن بعداً با Adaptive K + Progressive Schema.
2. Control / Experiment
Assignment پایدار است و بین درخواست‌ها عوض نمی‌شود:
SHA256("indexed-retrieval-v1" + business_id + user_id) % 100 → bucket
bucket < INDEXED_CANDIDATE_ROLLOUT_PERCENT → experiment
Salt = indexed-retrieval-v1. مستقل از Adaptive (adaptive-k-v1). تغییر Salt = آزمایش جدید.
| Arm | رفتار |
|---|---|
| Control | Authorized set → Phase 6 Ranker → K=48/128 |
| Experiment | Authorized set → Indexed N=100 → همان Ranker → همان K |
شناسه‌ها لاگ نمی‌شوند. Kill switch بدون restart کد: HESABIX_INDEXED_CANDIDATE_KILL=1 → همان tenant/user به Control برمی‌گردد.
3. Exposure
هر درخواست زنده یک رویداد:
indexed_candidate_exposure
فیلدها: arm, channel, mode, effective_candidate_retrieval.
ذخیره نمی‌شود: user_id, business_id, متن کامل query، دادهٔ مالی.
effective_candidate_retrieval:
indexed— ایندکس مجموعهٔ قابل‌استفاده دادfull_authorized— Control، یا Experiment پس از Fallback
4. Telemetry
شمارنده‌های زنده:
control_requests
experiment_requests
experiment_enabled_requests
experiment_fallback_requests
وضعیت ایندکس (جدا از Adaptive K retrieval_miss):
| Event | معنی |
|---|---|
indexed_retrieval_hit |
مجموعهٔ کاندید قابل‌استفاده از ایندکس |
indexed_retrieval_miss |
ابزار لازم در candidate set نبود |
indexed_retrieval_empty |
ایندکس نتیجهٔ خالی داد |
indexed_retrieval_stale |
ایندکس کهنه / غیرقابل‌استفاده |
Fallback reasons (کاننیکال Phase 13):
empty | low_candidate_quality | stale_index | index_error | index_inconsistency | unknown
fallback_rate و fallback_reason ثبت می‌شوند.
Fallback Success ≠ Index Success
Index Miss / empty → Fallback → Task Success
task_success = TRUE
index_success = FALSE
هر دو همزمان مجازند. تکمیل Task را با موفقیت Retrieval یکی نکن.
Task completion مصنوعی ساخته نمی‌شود. فقط سیگنال‌های موجود:
- first-pass بدون rediscovery (
tool executionمسیر) - موفقیت اجرای ابزار
- در آینده: workflow completion / explicit agent success / user confirmation اگر واقعاً موجود باشند
اگر سیگنالی نباشد، task_success = null.
Latency جدا:
discovery_latency | index_latency | rank_latency | total_ai_request_latency
p50 / p95 / p99 per arm
هدف اصلی end-to-end است، نه فقط lookup ایندکس.
candidate_count (معمولاً نزدیک N=100 یا کمتر) جدا از final_tool_count (K نهایی روی سیم).
کانال‌ها: chat / subagent / crm / ticket / workflow.
عملیات پرخطر per arm: delete / write / export / execute / financial_mutation × success / failure / approval / unexpected_rejection.
Health:
tool_index_health:
active_tool_count
indexed_tool_count
stale_tool_count
disabled_tool_count
last_refresh
healthy
اگر ایندکس ناسالم باشد (مثلاً last_refresh صفر یا inconsistency) → fallback به full authorized rank.
قرارداد رویداد Production (privacy-safe):
timestamp, arm, channel, mode, candidate_count, final_tool_count,
index_hit, index_miss, fallback, fallback_reason,
discovery_miss, schema_miss, tool_execution_success,
task_success, index_success, latency, effective_candidate_retrieval
5. Security Gate (Gate A)
authorization bypass = 0
tenant leakage = 0
permission violation = 0
هر مقدار غیرصفر → IMMEDIATE ROLLBACK (Case D). Fallback هرگز Global Registry نیست.
6. Task Gate (Gate B)
Control و Experiment با دو نسبت (Wilson score interval، ۹۵٪) مقایسه می‌شوند.
آستانهٔ درصدی ساختگی («اگر ۵٪ افت کرد») استفاده نمی‌شود.
پس از n ≥ 500 در هر بازو: اگر CI آزمایش کاملاً زیر CI کنترل باشد و نرخ آزمایش کمتر باشد → ROLLBACK (Case C).
قبل از ۵۰۰ نمونه: HOLD.
7. Retrieval Gate (Gate C)
indexed_retrieval_miss_rate جدا از tool_discovery_miss / Adaptive retrieval_miss گزارش می‌شود.
این Metric موفقیت ایندکس را می‌سنجد، نه موفقیت Ranker یا Schema.
8. Fallback Gate (Gate D)
اگر Fallback زیاد باشد، ایندکس سریع که اکثر درخواست‌ها را به full rank برمی‌گرداند موفقیت نیست.
پس از ۵۰۰ نمونه: اگر حد پایین CI نرخ Fallback آزمایش > 0.5 باشد → HOLD و اصلاح ایندکس (Case B). آستانهٔ درصدی اختیاری دیگر ساخته نمی‌شود.
9. Latency Gate (Gate E)
مقایسه:
Control p95 vs Experiment p95
Control p99 vs Experiment p99
اگر Experiment p95 از Control p99 بدتر باشد (پس از نمونهٔ کافی) → HOLD. ROLLBACK به‌خاطر latency تنها نیست.
هدف: end-to-end. ۱۰k bench آفلاین جایگزین Production latency نمی‌شود.
10. Kill Switch
HESABIX_INDEXED_CANDIDATE_KILL=1
یا HESABIX_INDEXED_CANDIDATE_RETRIEVAL=0. Adaptive K / Hybrid / Schema را عوض نمی‌کند. بدون restart غیرضروری: assignment در هر درخواست خوانده می‌شود.
canary active → kill switch → requests become control
11. Rollout
5% → 10% → 25% → 50% → 100%
نردبان مستقل است. propose_indexed_rollout ثابت‌ها را نمی‌نویسد. Auto-promotion ممنوع است. Promotion فقط با تصمیم صریح اپراتور (INDEXED_CANDIDATE_ROLLOUT_PERCENT).
حداقل قبل از هر پله: ۵۰۰ live request در هر بازو.
12. Statistical Method
- نسبت‌ها: Wilson score interval با
z=1.96(۹۵٪). - مقایسهٔ دو بازو: همپوشانی CI؛ regression معنادار = CI آزمایش کاملاً زیر کنترل و
delta < 0. enough_for_significanceفقط وقتی هر بازوn ≥ 500.- بدون آستانهٔ درصدی اختراعی برای «چند درصد افت مجاز است».
13. Privacy
رویدادها و snapshot نباید شامل این‌ها باشند:
user_id/business_id/session_id- متن query
- مبلغ، شناسهٔ فاکتور/شخص، ایمیل، تلفن
Assignment از شناسه استفاده می‌کند ولی آن‌ها را لاگ نمی‌کند.
14. Current Status
این فرآیند / این محیط:
| Metric | Value |
|---|---|
| Live control | 0 |
| Live experiment | 0 |
| Exposure | 0 |
| Indexed hit/miss/fallback rates | null (no live samples) |
| Task completion | null (no live signal) |
| Tool execution success | null |
| Security | clean (0 bypass in this process) |
| p50 / p95 / p99 | null |
| Index health | manifest vs postings (offline-observable) |
| Kill switch | armed (HESABIX_INDEXED_CANDIDATE_KILL=1 works) |
| Current rollout | 5% |
| Promotion | HOLD |
| Adaptive K | OFF |
| Hybrid | OFF |
| Progressive Schema | OFF |
15. Promotion Criteria
قبل از ۵٪ → ۱۰٪:
>= 500 control
>= 500 experiment
Security clean
Task no material regression (Wilson CI)
Fallback acceptable
Index miss acceptable (reported, not substituted)
p95 acceptable
Explicit operator decision
اگر همه برقرار باشند، helper حداکثر REVIEW + allow_operator_promote می‌دهد — هرگز auto-promote نمی‌کند.
16. Rollback Criteria
| Case | معنی | اقدام |
|---|---|---|
| A | Healthy + ۵۰۰/بازو + Gateها | اجازهٔ Promotion به ۱۰٪ با تصمیم صریح |
| B | مشکل ایندکس / Fallback زیاد / latency بد | HOLD و اصلاح ایندکس |
| C | افت معنادار Task Success | ROLLBACK |
| D | Security / tenant leakage / permission | IMMEDIATE ROLLBACK |
17. Next Phase
Phase 14 فقط بعد از شواهد زنده معنا دارد: جمع‌آوری ترافیک واقعی روی Canary ۵٪، پر کردن Gateها، سپس تصمیم صریح برای ۱۰٪.
تا آن زمان:
- Adaptive K را روشن نکن (حتی اگر Indexed به ۱۰۰٪ برسد؛ آزمایش جدا است).
- Hybrid و Progressive را روشن نکن.
- N را عوض نکن.
- Gold را به‌جای Production مصرف نکن.
Recommended Phase 14: Live traffic collection on the 5% canary (observability + Gate fill). Not Adaptive K. Not Hybrid. Not 10% promotion.