Versioned Shared Interfaces

1. مسئله‌ای که این درس مالک آن است

داشتن v1 و v2 به‌تنهایی Consumerها را از شکستن Interface محافظت نمی‌کند. مشکل واقعی این است که هر Version دقیقاً به چه Public Surfaceی اشاره می‌کند، چه چیزی تغییر کرده، کدام Consumerها تحت‌تأثیرند و آیا Migration و Rollback آن‌ها واقعاً اثبات شده است. ARC-002 فقط همین Shared Interface Contract را مالک است؛ Venture Separation در ARC-001 و Resource Broker Metadata در ARC-003 جدا می‌مانند.

2. خروجی قابل تحویل

خروجی شما Shared Interface Version & Compatibility Contract v1 است. برای هر Interface/Consumer باید Version، Public Surface Hash، Change Set، Producer Owner، Compatibility، Breaking Flag، Deprecation State، Support Window، Migration Target/Evidence، Contract Test، Rollback، Adoption، Exception، Timestamp و Provenance ثبت شود.

3. مدل ذهنی: Surface → Change → Compatibility → Consumers

ترتیب تصمیم این است: public surface → change set → compatibility classification → required version class → consumer inventory → tests/migration → deprecation/rollback → bounded decision. Version number در ابتدای تصمیم نیست؛ نتیجه‌ی Classification است. اگر Public Surface نامعلوم باشد، هیچ Version label نمی‌تواند آن کمبود را جبران کند.

4. SemVer چه می‌گوید و چه نمی‌گوید

Semantic Versioning می‌گوید Public API باید تعریف شود؛ تغییر ناسازگار به Major، قابلیت backward-compatible به Minor و bug fix backward-compatible به Patch می‌رود. همچنین یک Version منتشرشده نباید بی‌صدا تغییر کند. اما SemVer نمی‌گوید Consumer شما تست شده، Migration انجام شده یا Rollback آماده است؛ این‌ها Evidenceهای جدا هستند.

5. Version باید به Surface دقیق Bind شود

contract_version بدون public_surface_hash مبهم است. اگر فیلد required، type، default behavior یا error contract عوض شد، Change Set باید دقیقاً همان Surface را نشان دهد. Release قبلی immutable فرض می‌شود؛ برای Surface جدید Version جدید می‌سازیم، نه اینکه محتوای Version قبلی را تغییر دهیم.

6. Compatibility را قبل از Version انتخاب کنید

اول بپرسید تغییر backward-compatible است یا breaking. افزودن optional field معمولاً می‌تواند compatible باشد، ولی rename کردن required field یا تغییر semantic default می‌تواند Consumer قدیمی را بشکند. اگر Change breaking است و Version Major تغییر نکرده، State باید REJECT شود؛ نام زیبا یا Release note این Gate را override نمی‌کند.

7. Consumer Inventory بخشی از Contract است

Shared Interface یعنی چند Consumer واقعی. برای هر Consumer، Owner، Payload/Client version، Migration Target، Contract Test و Adoption State را جدا ثبت کنید. Producer deployment به معنی Consumer migration نیست. Consumerی که هنوز payload قدیمی می‌فرستد باید در Decision دیده شود، حتی اگر اکثر Consumerها migrate شده باشند.

8. Baseline کارشده: v2 با یک Consumer باقی‌مانده روی v1

Producer از 1.4.2 به 2.0.0 می‌رود چون required field rename یک Breaking Change است. Venture A و B روی v2 Contract Test را PASS کرده و Migration Evidence دارند. Venture C هنوز در Embedded Workflow روی v1 است؛ v1 تا تاریخ مشخص پشتیبانی می‌شود، Owner برای Deprecation داریم و Rollback به 1.4.2 موجود است. نتیجه MIGRATION_REQUIRED است، نه Failure و نه «همه‌چیز Compatible».

9. Shortcut ممنوع: Breaking Change با همان Version

اگر customer_id به profile_id rename شود ولی Producer همچنان 1.4.2 را اعلام کند، Public Surface عوض شده ولی Version/Semantics نه. این Mutation باید REJECT شود. Released Version را درجا mutate نمی‌کنیم؛ Version جدید لازم است.

10. «MIGRATED» بدون Contract Test معتبر نیست

Adoption State یک Label دستی نیست. Consumer فقط وقتی MIGRATED محسوب می‌شود که Migration Evidence و Contract Test مربوط به همان Target Version موجود و PASS باشد. اگر تیم صرفاً Flag را تغییر دهد ولی Test replay نشده باشد، Decision باید HOLD شود تا Evidence بازسازی شود.

11. Deprecation Window باید Owner داشته باشد

حفظ نسخه قدیمی ممکن است تصمیم درست باشد، اما Support Window نامحدود یا بی‌مالک Hidden Debt می‌سازد. support_window_end، deprecation_owner و Review باید معلوم باشند. تمدید تاریخ بدون Owner/Authority، HOLD است؛ تمدید silent، Compatibility Strategy نیست.

12. Fork اختصاصی Venture بدون Convergence ممنوع است

اگر برای یک Venture نسخه اختصاصی ساخته شود و Plan مشخصی برای بازگشت به Shared Contract وجود نداشته باشد، سیستم عملاً Interface مشترک را شکسته است. این درس چنین Forkی را REJECT می‌کند. Exception موقت فقط وقتی قابل قبول است که Owner، Expiry و Convergence Path روشن باشد.

13. Transfer: Consumer مهاجرت‌شده دوباره Payload قدیمی می‌فرستد

در Transfer، Delayed Worker یک Consumer که قبلاً MIGRATED ثبت شده بود دوباره payload v1 می‌فرستد. Adoption باید از نو محاسبه شود. نتیجه می‌تواند MIGRATION_REQUIRED شود و تیم بین ادامه Support قدیمی، Compatibility Adapter یا Rollback producer تصمیم بگیرد. Baseline Verdict قابل Copy نیست چون Evidence تغییر کرده است.

14. Lab و روش اجرا

به lab/ARC-002-LAB1/learner/ بروید و python run_checks.py را Offline اجرا کنید. هشت Fixture شامل Baseline، Breaking change بدون Major، Migration بدون Contract Test، Deprecation بی‌Owner، Venture Fork، Evidence stale، Surface Hash گمشده و Transfer delayed payload هستند. هدف حفظ Verdict نیست؛ اولین Gate کنترل‌کننده را توضیح دهید.

15. ارزیابی، Freshness و مرز ادعا

ارزیابی شامل Boundary، ساخت Baseline Contract، تشخیص Breaking shortcut و Transfer است. SemVer فقط FACTهای Public API و Version increment/immutability را محدود می‌کند. Consumer inventory، migration evidence، deprecation governance، rollback و typed states طراحی MAKNOW هستند. تغییر Canonical پذیرفته‌شده فقط با Package Version جدید مجاز است.