Repair Diagnostics و Isolated Reproduction

1. مسئله: Fix کردن در Full System می‌تواند علت را پنهان کند

وقتی یک Failure را مستقیم در سیستم کامل «درست» می‌کنیم، ممکن است هم‌زمان چند متغیر عوض شوند و دیگر نفهمیم کدام تغییر واقعاً علت را حذف کرده است. خروجی این درس Isolated Reproduction & Diagnostic Evidence Packet v1 است: یک بسته‌ی تشخیصی که Failing Input، Environment، Oracle، Trace، Suspect Range و Boundary Owner را جدا و قابل‌ممیزی نگه می‌دارد.

2. مرز درس

PLN-027 مالک Release/Canary نیست؛ آن مرحله متعلق به PLN-028 است. همچنین Canon Boundary درس PLN-026 را جذب نمی‌کند. اینجا فقط باید Failure را به کوچک‌ترین مرز قابل‌تکرار برسانیم و مشخص کنیم رفتار مشاهده‌شده متعلق به Application/SDK است یا به Model/Network/Sandbox Provider نیاز دارد.

3. FACT خارجی و DESIGN داخلی

git bisect با binary search بین revisionهای معلومِ old/good و new/bad، دامنه‌ی تغییر را کوچک می‌کند؛ ولی اگر Test Oracle نتواند candidateها را پایدار classify کند، bisect هم نتیجه قابل‌اتکا نمی‌دهد. OpenAI Agents SDK Testing نیز test doubleهای deterministic و provider-neutral دارد که رفتار application/SDK را بدون model یا sandbox-provider واقعی تمرین می‌دهند. این ابزارها رفتار provider واقعی را اثبات نمی‌کنند. ساختار Packet و Stateهای این درس MAKNOW DESIGN هستند.

4. Incident و Symptom را از Hypothesis جدا کن

incident_id و symptom_id واقعیت مشاهده‌شده را نام‌گذاری می‌کنند؛ diagnostic_hypothesis فقط توضیح موقت است. اگر Hypothesis عوض شد، Identity حادثه نباید بازنویسی شود. تشخیص خوب از «چه دیدیم؟» شروع می‌شود، نه از «فکر می‌کنیم علت چیست؟».

5. Failing Input را Freeze کن

ورودی شکست باید hash یا identity پایدار داشته باشد. اگر Prompt، Tool Input، Attachment یا Event sequence هنگام آزمون تغییر کند، نتیجه‌ی جدید دیگر reproduction همان Failure نیست. failing_input_hash باید با Fixture و Trace پیوند داشته باشد.

6. Environment Fingerprint و Dependency Lock

حداقل Environment باید runtime، dependency lock، config hash، agent-definition hash و tool-contract hash را ثبت کند. تغییر دو dependency در یک مرحله Attribution را خراب می‌کند. اگر Environment آزمایش با Environment شکست یکی نیست، State موفق صادر نمی‌شود و نتیجه HOLD می‌ماند.

7. Oracle باید صریح و پایدار باشد

Oracle می‌گوید چه خروجی‌ای Expected و چه چیزی Actual است. «به نظرم جواب بد است» Oracle نیست. Oracle باید آن‌قدر deterministic باشد که candidateهای bisect را به‌طور قابل‌تکرار classify کند. Oracle flaky → INCONCLUSIVE.

8. Trace و Fixture، Evidence قابل replay

fixture_id و trace_id باید قابل ردیابی باشند. Trace باید نشان دهد چه callها و state transitionهایی قبل از Failure رخ داده‌اند. Fixture باید کمترین داده لازم را حمل کند؛ Copy کردن کل production state هم ریسک حریم خصوصی دارد و هم Diagnosis را شلوغ می‌کند.

9. Last Known Good و First Bad Candidate

وقتی revision boundary معتبر داریم، last_known_good و first_bad_candidate دامنه suspect_range را شکل می‌دهند. git bisect برای کوچک‌کردن همین بازه مفید است، اما فقط اگر هر commit قابل build/test باشد و Oracle جواب پایدار بدهد.

10. Boundary Owner را نام ببر

حداقل Ownerهای عملی این درس: APPLICATION_SDK، MODEL_PROVIDER، SANDBOX_PROVIDER، NETWORK/PROTOCOL یا UNKNOWN. اگر scripted test double Failure را reproduce نکند ولی provider واقعی reproduce کند، مرز باید به external/provider منتقل شود؛ offline green test حق ندارد provider را تبرئه کند.

11. Test Double چه چیزی را اثبات می‌کند؟

Test double برای tool routing، handoff، guardrail، retry، normalized sandbox call و orchestration عالی است. اما lifecycle واقعی sandbox، filesystem fidelity، process execution، resource limit و isolation متعلق به integration test با provider واقعی است. پس SESSION_LOCAL یا offline success را به production/provider proof تبدیل نکن.

12. Baseline — Failure داخل Application/SDK Boundary

Incident INC-517 بعد از dependency upgrade با همان input، همان env fingerprint و Oracle پایدار reproduce می‌شود. ScriptedModel همان Failure در tool-argument normalization را نشان می‌دهد؛ last-known-good=r140 و first-bad=r147 است. چون Environment match است، فقط یک متغیر تغییر کرده و Oracle پایدار است، Packet به REPRODUCED می‌رسد و bisect آماده است.

13. Shortcutهای خطرناک

1. دو dependency را هم‌زمان عوض کنی → INCONCLUSIVE. ۲) با scripted sandbox نتیجه بگیری provider واقعی سالم/خراب است → EXTERNAL_UNTRUSTED/HOLD. ۳) Oracle flaky را به bisect بدهی → دامنه ظاهراً کوچک می‌شود ولی causal claim معتبر نیست. ۴) Environment mismatch را نادیده بگیری → HOLD.

14. Transfer — Failure فقط با Sandbox Provider واقعی

در Transfer، scripted test double همه‌چیز را سبز نشان می‌دهد ولی همان fixture در sandbox provider واقعی Failure دارد. نتیجه Offline را copy نمی‌کنیم. boundary_owner به SANDBOX_PROVIDER تغییر می‌کند، integration_required=true می‌شود و کوچک‌ترین integration reproduction باید lifecycle/filesystem/process/isolation لازم را با provider واقعی نگه دارد. تا آن زمان State HOLD است.

15. Lab، Assessment و Freshness

در lab/PLN-027-LAB1/learner/ دستور python run_checks.py را اجرا کن. ۸ Fixture شامل Baseline، Two Dependencies Changed، Provider-double Overclaim، Flaky Oracle، Environment Mismatch، Missing Provenance، Stale Evidence و Real-provider Transfer هستند. FACTهای Git و OpenAI Agents SDK در 2026-09-16 دوباره بررسی شده‌اند؛ تغییر Canonical Package نیازمند Version جدید است.