Official Platform Adapters و Policy Snapshot

1. مسئله: پاسخ موفق، قرارداد جاری را ثابت نمی‌کند

ممکن است یک Adapter ماه‌ها بدون خطای واضح کار کند و هنوز نسخه API، permission scope، schema یا policy آن از مستندات رسمی عقب افتاده باشد. خروجی این درس Official Platform Adapter & Policy Snapshot v1 است: رکوردی که دقیقاً می‌گوید چه Provider/Product/Version/Operation/Policy را با چه شواهدی پذیرفته‌ایم.

2. مرز درس

PLN-020 مالک Adapter و Policy Snapshot است. Capacity Advisor درس PLN-019 و Capability Registry درس PLN-021 جدا می‌مانند. این درس هیچ publish واقعی، credential واقعی یا تماس شبکه‌ای انجام نمی‌دهد.

3. FACT خارجی و MAKNOW DESIGN

GitHub REST API نسخه‌دار است و X-GitHub-Api-Version نسخه درخواست را pin می‌کند؛ breaking changeها در نسخه جدید عرضه می‌شوند. GitHub همچنین OpenAPI ماشین‌خوان برای محصول/نسخه ارائه می‌کند. LinkedIn Marketing API نیز Version Header و چرخه نسخه مستقل دارد. اما stateهای SUPPORTED / CONDITIONAL / UNSUPPORTED / STALE_EVIDENCE / UNKNOWN و قواعد تصمیم این درس MAKNOW DESIGN هستند.

4. Platform و Product Surface را دقیق نام‌گذاری کن

platform_id و product_surface نباید به «GitHub» یا «LinkedIn» کلی بسنده کنند. مشخص کن Adapter برای کدام API family و سطح محصول است؛ چون یک Provider می‌تواند چند API، چند product و چند support window متفاوت داشته باشد.

5. API Version و Version Header را Pin کن

نسخه باید در snapshot ثبت شود. Endpoint ثابت به معنی رفتار ثابت نیست. اگر Header لازم غایب باشد یا نسخه مستند با نسخه اجراشده نخواند، قرارداد current نیست و نباید صرفاً به‌خاطر 2xx SUPPORTED بماند.

6. Auth Mode و Permission Scope را از Version جدا نگه دار

ممکن است نسخه صحیح باشد ولی scope موردنیاز تغییر کرده باشد. permission_scope یک Gate مستقل است. نبود scope لازم → CONDITIONAL و مسیر REAUTH_REQUIRED؛ نه حدس زدن permission و نه اجرای واقعی.

7. Operation و Endpoint کافی نیستند؛ Schema هم Snapshot می‌خواهد

operation_id، endpoint و request/response schema ref را با Evidence رسمی ثبت کن. OpenAPI می‌تواند shape را کمک کند، اما policy، permission یا account eligibility را ثابت نمی‌کند.

8. Policy Snapshot باید Identity مستقل داشته باشد

policy_snapshot_id و policy_locator باید مشخص کنند کدام policy را در چه زمانی خوانده‌ایم. «لینک همان صفحه قبلی» کافی نیست؛ provider ممکن است محتوا را عوض کرده باشد.

9. Freshness: Retrieved At و Review Due

برای API/Policy volatile باید retrieved_at و review_due داشته باشی. اگر review_due گذشته است، حتی Endpoint سالم و پاسخ موفق هم evidence جاری محسوب نمی‌شود؛ نتیجه STALE_EVIDENCE و POLICY_RECHECK است.

10. Deprecation و Sunset را پنهان نکن

deprecation_notice و sunset_state بخشی از قراردادند. Adapter می‌تواند امروز کار کند اما روی نسخه‌ای باشد که در مسیر shutdown است. اگر نسخه خارج از support باشد، تصمیم UNSUPPORTED/MIGRATE_VERSION است؛ اگر deprecation فعال ولی هنوز قابل استفاده است، تصمیم ممکن است CONDITIONAL/REVIEW_DEPRECATION باشد.

11. State machine محدود

SUPPORTED فقط وقتی صادر می‌شود که version/header، permission، schema، policy freshness، deprecation/sunset و provenance همگی قابل دفاع باشند. CONDITIONAL یعنی Provider surface وجود دارد اما یک Gate اصلاح‌پذیر باز است. STALE_EVIDENCE یعنی evidence زمان‌دار دیگر current نیست. UNSUPPORTED برای evidence صریح منفی یا version خارج از support است. نبود evidence را UNKNOWN نگه دار.

12. Baseline: GitHub Adapter با Snapshot جاری

Baseline نسخه جاری مستندشده GitHub را با X-GitHub-Api-Version, endpoint/schema refs, policy snapshot, retrieval/review dates و provenance کامل ثبت می‌کند. نتیجه SUPPORTED است و فقط به مرحله Capability Registry می‌رود؛ این درس publish را مجاز نمی‌کند.

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

2xx == current contract غلط است. Endpoint ثابت == schema ثابت نیست. Version header مفقود را «default قابل قبول» فرض نکن. Policy قدیمی را به‌خاطر همان URL reuse نکن. Permission قدیمی را به نسخه جدید carry نکن. OpenAPI را معادل authorization یا business policy نگیر.

14. Transfer: Endpoint ثابت، Scope و Deprecation جدید

در Transfer، LinkedIn همان base path/endpoint family را نگه می‌دارد اما scope لازم و deprecation notice تغییر می‌کند. Snapshot باید از Evidence جدید بازسازی شود. اگر deprecation فعال است یا scope جدید هنوز آماده نیست، baseline state را کپی نکن؛ CONDITIONAL و مسیر migration/re-auth را ثبت کن.

15. Lab، Assessment و Freshness

در lab/PLN-020-LAB1/learner/ دستور python run_checks.py را اجرا کن. هشت Fixture شامل baseline، missing version header، stale policy، changed permission، unsupported/sunset version، 2xx بدون snapshot، missing provenance و transfer هستند. منابع رسمی GitHub و LinkedIn در 2026-09-16 دوباره بررسی شده‌اند؛ تغییر bytes پذیرفته‌شده نیازمند package version جدید است.