Documentation Monitoring و Semantic Diff

وقتی «صفحه عوض شده» مدرک تغییر درس نیست

یک صفحه‌ی مستندات provider با ETag و Last-Modified جدید برمی‌گردد. navigation صفحه redesign شده، اما در یک پاراگرافی که به آن استناد کرده‌ایم مقدار retry limit هم از ۳ به ۵ تغییر کرده است. اگر updater به هر تغییر byte/hash واکنش نشان دهد، review noise می‌سازد؛ اگر فقط timestamp یا URL را ببیند، ممکن است تغییر واقعی claim را از دست بدهد.

در این درس Documentation Change Detection & Semantic Review Contract v1 را می‌سازیم. قرارداد هویت منبع، validatorهای HTTP، نتیجه‌ی fetch شرطی، هویت raw و normalized content، lineage snapshotها، نوع diff، semantic class، claimهای متاثر، severity، review state/owner، next check و provenance را ثبت می‌کند. تغییر transport فقط مدرک تغییر representation است؛ به‌تنهایی مدرک تغییر claim آموزشی نیست.

مرز درس و مسیرهای یادگیری

MKN-008 مالک Documentation Monitoring و Semantic Diff است. MKN-007 prerequisite مفهومی سخت است. MKN-009 زمان‌بندی background updater را مالک است؛ بنابراین اینجا cron، lease یا retry scheduling را تعریف نمی‌کنیم. همچنین هیچ source، search index یا Lesson Bible زنده‌ای mutate نمی‌شود.

در مسیر Foundation نقشه‌ی فیلدها و یک سناریوی mixed-change کامل داریم. در Repair اولین evidence متناقض یا گمشده را جدا می‌کنیم. در Experienced باید مرز normalization، validator و claim impact بدون تبدیل hash comparison یا خلاصه‌ی AI به oracle معنایی دفاع شود.

مدل ذهنی: source registry → conditional fetch → validator → normalization → diff → semantic class → affected claims → review

زنجیره‌ی تصمیم:

هویت منبع → درخواست شرطی → fetch/304 evidence → raw snapshot → normalization profile → normalized identity → structural/semantic diff → نگاشت claim → severity → review/promote/hold → next check

لایه‌ی transport می‌گوید representation از نگاه HTTP عوض شده یا قابل reuse است. لایه‌ی content snapshot خام و normalized را نگه می‌دارد. لایه‌ی semantic می‌پرسد آیا معنایی که برای یک claim آموزشی مهم است تغییر کرده. لایه‌ی governance تعیین می‌کند چه کسی review می‌کند و آیا اصلاً artifact canonical اجازه‌ی تغییر دارد. مخلوط‌کردن این لایه‌ها false positive و false confidence می‌سازد.

قرارداد پایه: هفده بُعد قابل ممیزی

source_id و canonical_locator منبع را مشخص می‌کنند. etag و last_modified شواهد validator هستند. fetch_status نتیجه‌ی retrieval شرطی را ثبت می‌کند. content_hash fingerprint representation دریافت‌شده و normalized_hash fingerprint محتوای relevant بعد از normalization است.

previous_snapshot_ref و current_snapshot_ref lineage را حفظ می‌کنند. diff_type نوع تغییر را توضیح می‌دهد. semantic_change_class مشخص می‌کند تغییر claim-affecting، non-semantic، equivalent relocation، unknown یا no-change است. affected_claim_ids تغییر معنایی را به claimهای واقعی وصل می‌کند. severity، review_state، review_owner، next_check_at و provenance نتیجه را محدود و قابل بازتولید می‌کنند.

یک row کامل «شواهد» است، نه مجوز خودکار برای promotion.

توضیح عمیق: FACT، INFERENCE و DESIGN را یکی نکن

HTTP validators — FACT. RFC 9110 validatorهایی مثل ETag و Last-Modified را برای validation و conditional request تعریف می‌کند. strong و weak validator semantics مقایسه متفاوت دارند؛ weak validator گواه exact byte equality نیست.

تفسیر pipeline — INFERENCE. تغییر transport باید جدا از semantic learning change ذخیره شود. entity tag ممکن است به‌خاطر markup، navigation تولیدی، timestamp یا یک پاراگراف واقعاً مهم تغییر کند. normalization می‌تواند noise را کم کند، اما normalized hash فقط identity تحت همان profile است؛ مدرک قطعی برابری آموزشی نیست.

سیاست MAKNOW — DESIGN. semantic category، affected-claim mapping، severity، reviewer ownership، HOLD و promotion rule تصمیم محلی هستند. مستندات خارجی fact می‌دهند؛ اجازه‌ی rewrite کردن Lesson Bible را نمی‌دهند.

مثال‌های حل‌شده: mixed change، navigation-only و انتقال معادل

Baseline mixed change. ETag و Last-Modified عوض می‌شوند، raw hash تغییر می‌کند و normalization navigation جدید را حذف می‌کند. پاراگراف retry-limit بعد از normalization هنوز متفاوت است، پس normalized_hash هم تغییر می‌کند. semantic class برابر CLAIM_AFFECTING، affected claim برابر MKN-008-DEMO-RETRY-LIMIT، severity برابر MAJOR و state برابر CLAIM_AFFECTING_CHANGE_REVIEW_REQUIRED می‌شود. این state درس را خودکار update نمی‌کند؛ فقط review obligation می‌سازد.

Navigation-only. raw hash و validatorها تغییر می‌کنند اما normalized relevant content یکی است. state درست NON_SEMANTIC_CHANGE_REVIEW_REQUIRED است. اگر فقط به‌خاطر raw hash آن را claim-affecting بنامیم، قرارداد باید رد کند.

Transfer: URL جدید با معنای یکسان. منبع رسمی دوم همان semantics را با redesign و locator جدید منتشر می‌کند. source identity و provenance از نو محاسبه می‌شوند. نتیجه می‌تواند SOURCE_RELOCATION_EQUIVALENCE_REVIEW_REQUIRED باشد، اما فقط از evidence جدید؛ label baseline oracle نیست.

failure modeهایی که باید fail-closed باشند

وقتی تمام validator evidenceها غایب‌اند، fetch شکست خورده، raw/normalized content identity یا diff type برابر UNKNOWN است، snapshot reference لازم ناقص/متناقض است، بعد از normalized change semantic class نامعلوم است، claim-affecting change affected claim ندارد، review state به‌جای bounded review حالت نامعتبر/approving دارد، review owner/provenance خالی است یا transfer تصمیم baseline را reuse می‌کند، نتیجه باید HOLD بماند.

classification متناقض هم باید fail شود: row نمی‌تواند هم semantic_change_class=NONE/NON_SEMANTIC داشته باشد و هم affected claim و severity=MAJOR. همچنین وقتی normalized content تغییر نکرده، claim-affecting اعلام‌کردن بدون evidence مستقل قابل دفاع نیست. Lab این تناقض‌ها را evidence defect می‌داند، نه فرصتی برای حدس.

گزینه‌ها و trade-offها: validator، normalization و semantic review

ETag-first conditional retrieval وقتی source tag پایدار دارد کارآمد است، اما weak tag semantics متفاوت دارد. Last-Modified مفید است ولی resolution زمان و کیفیت server می‌تواند دقتش را محدود کند. نبود ETag لزوماً failure نیست اگر evidence محدود دیگری داریم، اما degraded-validator state باید آشکار باشد.

Normalization تهاجمی layout noise را کم می‌کند ولی ممکن است example، code block، warning یا numeric limit واقعی را حذف کند. Normalization حداقلی اطلاعات بیشتری حفظ می‌کند اما review noise را بالا می‌برد. مدل semantic/LLM می‌تواند candidate diff را مرتب کند، ولی نباید oracle پنهان باشد. claim change پراثر به evidence قابل مشاهده و review owner نیاز دارد.

پل مسیر Experienced: semantic diff مسئله‌ی provenance هم هست

هر snapshot را یک observation با content identity و provenance ببین. علاوه بر raw representation identity، نسخه‌ی normalization profile را هم حفظ کن؛ وگرنه تغییر rule normalization ممکن است خودش را به شکل source change نشان دهد.

semantic classification باید از excerpt/rule قابل مشاهده یا human review record بازتولید شود. اگر مدل AI affected claim پیشنهاد می‌دهد، آن را candidate evidence نگه دار نه authority canonical. pipeline خوب می‌تواند جواب دهد: در transport چه عوض شد، بعد از normalization چه باقی ماند، کدام claim ممکن است متاثر باشد و چه کسی این تفسیر را پذیرفت؟

تمرین هدایت‌شده و مستقل

1. baseline را باز کن و content_hash را از normalized_hash جدا کن. 2. فقط navigation markup را تغییر بده و مطمئن شو raw identity عوض می‌شود ولی affected claim ساخته نمی‌شود. 3. numeric retry limit را داخل پاراگراف cited عوض کن و claim mapping + severity را الزام کن. 4. ETag را حذف ولی Last-Modified را نگه دار؛ exact equality را اختراع نکن و degraded-validator review state را حفظ کن. 5. هر دو validator را حذف کن و توضیح بده چرا conditional-validation evidence دیگر کافی نیست. 6. محتوای equivalent را به canonical locator جدید منتقل کن و provenance را از نو بساز.

برای تمرین مستقل expected state را حذف کن و فقط از ۱۷ فیلد visible و learner-visible gate rule تصمیم را بازسازی کن.

شواهد verification: reviewer باید چه چیزی را بازتولید کند؟

Reviewer باید بتواند source identity، validator evidence، conditional fetch status، raw/normalized identity، lineage snapshot، diff type، semantic class، affected claims، severity، review state/owner، next-check time و provenance را بازسازی کند. همچنین باید توضیح دهد چرا تغییر validator/hash به تغییر claim منجر شده یا نشده است.

Lab deterministic baseline claim change، navigation-only churn، false-positive semantic classification، numeric-limit change، claim mapping ناقص، validator degraded/missing، fetch failure، semantic class نامعلوم، owner/provenance گمشده، snapshot lineage defect، relocation transfer و reuse ممنوع baseline oracle را پوشش می‌دهد.

ارزیابی و Transfer: URL جدید و redesign با semantics معادل

Assessment چهار بخش blocking دارد: مرز درس و یک non-goal را توضیح بده؛ Contract baseline را بساز؛ false positive ناشی از navigation-only را diagnose کن؛ و سپس transfer را برای منبع دوم با semantics یکسان، redesign و URL جدید از نو محاسبه کن.

Transfer فقط وقتی pass است که source/provenance و snapshot identity از context جدید ساخته شوند و برای relevant content معادل affected claim خالی بماند. کپی‌کردن label baseline حتی اگر تصادفاً درست به نظر برسد، مردود است.

منابع، تازگی و مرز authority

RFC 9110 در ۱۳ سپتامبر ۲۰۲۶ برای validator fieldها، strong/weak semantics، ETag، Last-Modified و conditional request دوباره بررسی شد. این semantics پروتکلی پایدارند، اما حداکثر تا 2027-01-15 یا زودتر در صورت تغییر مادی استاندارد requalify می‌شوند.

قواعد normalization، semantic class، claim-impact severity و stateهای promotion/HOLD در MAKNOW DESIGN authority هستند و الزام RFC نیستند. این مرز عمداً داخل درس visible مانده است.