Lease Protocol: Ack, Renew, Cancel, Progress

1. مسئله واقعی: delivery به معنی مالکیت دائمی نیست

Coordinator ممکن است job را تحویل دهد اما هنوز هیچ evidence پایداری نداشته باشد که worker همچنان مجاز به اجرای آن است. قطع شبکه، retry، پیام stale، reassignment و cancellation می‌توانند دو مالک ظاهری بسازند یا کار منقضی‌شده را دوباره زنده کنند. خروجی این درس Lease Lifecycle & Progress State Machine v1 است: قراردادی auditable که delivery، ACK، authority فعال، renew، progress، cancel، expiry و terminal result را از هم جدا می‌کند.

2. مرز مالکیت LOC-011

LOC-011 مالک lease identity، generation، holder binding، ACK deadline، expiry، renew sequence، progress sequence، cancellation state و terminal reconciliation است. Enrollment و credential generation در LOC-009، heartbeat/inventory health در LOC-010 و durable offline spool/replay در LOC-012 قرار دارند. Kubernetes Lease فقط یک coordination reference است و semantic کامل job lease در MAKNOW را تعریف نمی‌کند.

3. Lease باید identity، holder و زمان محدود داشته باشد

حداقل job_id، lease_id، lease_generation، holder_identity، issued_at، lease_duration و expires_at را ثبت کنید. Holder فقط برای همان generation و همان بازه محدود authority دارد. اگر lease id بدون generation تکرار شود یا اسم worker را مالکیت دائمی فرض کنید، traffic قدیمی از authority فعلی قابل تشخیص نخواهد بود.

4. Kubernetes یک reference model می‌دهد، نه کل protocol

در LeaseSpec کوبرنتیز فیلدهایی مثل holderIdentity، acquireTime، renewTime، leaseDurationSeconds و leaseTransitions وجود دارد و duration نسبت به آخرین renewTime مشاهده‌شده سنجیده می‌شود. این semantics برای explicit holder و renewal timing مفیدند. ACK، progress، cancellation، generation و terminal-result در این درس طراحی خود MAKNOW هستند و نباید به Kubernetes نسبت داده شوند.

5. Delivery و ACK دو state متفاوت‌اند

Job تحویل‌شده فقط offer است. ACK یعنی worker پیش از ack_deadline offer را دریافت و قبول کرده؛ به معنی موفقیت job نیست. مسیر پایه می‌تواند OFFERED → ACKED → ACTIVE باشد. اگر ACK تا deadline نرسد، coordinator طبق policy می‌تواند lease را expire یا reassign کند. ACK هرگز مستقیم به COMPLETED تبدیل نمی‌شود.

6. Renew فقط generation جاری را تمدید می‌کند

هر renew باید به lease_id + lease_generation + holder_identity + renew_sequence bind باشد. Renew معتبر پیش از expiry می‌رسد، متعلق به holder/generation جاری است و sequence پذیرفته‌شده را جلو می‌برد. بعد renew_time و expiry جدید طبق contract محاسبه می‌شود. اگر generation 8 فعال شده، renew دیرهنگام generation 7 حق ندارد generation 7 را دوباره تمدید کند.

7. Expiry مرز authority است

وقتی lease منقضی شد، holder قبلی طبق این contract دیگر execution authority جاری ندارد. اگر generation جدید assign شود، پیام‌های قدیمی می‌توانند برای audit حفظ شوند اما مالکیت را revive نمی‌کنند. Clock source و provenance timestamp مهم است: تصمیم expiry باید بر time policy اعلام‌شده coordinator متکی باشد، نه صرفاً ساعت worker.

8. Progress evidence ترتیبی است، نه authority

Progress باید به lease generation فعال bind شود و progress_sequence داشته باشد. فقط وقتی update را بپذیرید که generation جاری باشد و sequence از آخرین sequence پذیرفته‌شده جلوتر برود. اگر sequence 12 بعد از 14 برسد، state جدیدتر را نگه دارید و پیام عقب‌افتاده را ثبت کنید. Progress به‌خودی‌خود lease را renew نمی‌کند؛ این درس این دو action را جدا نگه می‌دارد.

9. Cancellation به request، ACK و reconciliation نیاز دارد

cancel_requested intent coordinator را ثبت می‌کند و cancel_ack acknowledgement worker را. هیچ‌کدام به‌تنهایی ثابت نمی‌کند process متوقف شده است. اگر worker هنگام disconnect late progress بفرستد، آن را به‌عنوان late/stale evidence نگه دارید، cancellation/expiry policy را authoritative بدانید و برای پایان کار terminal reconciliation صریح مثل CANCELLED، FAILED یا state محدودِ unresolved بخواهید.

10. Terminal result کار را می‌بندد؛ ACK نه

Terminal result باید به lease identity/generation فعال bind باشد و فقط در صورت رعایت contract پذیرفته شود. SUCCESS، FAILED و CANCELLED با delivery ACK فرق دارند. اگر lease ACK شده ولی پیش از terminal result معتبر expire شود، نتیجه success نیست؛ authority منقضی شده و completion هنوز اثبات نشده است.

11. پیام Stale و Duplicate باید outcome صریح داشته باشند

Evidence را بی‌صدا حذف یا current تفسیر نکنید. stale_generation، late_progress، duplicate renew و duplicate terminal attempt باید audit event صریح داشته باشند. Duplicate idempotent برای همان sequence پذیرفته‌شده می‌تواند بدون mutation نادیده گرفته شود، اما generation پایین‌تر یا holder متناقض نباید active lease را تغییر دهد.

12. Ownership conflict باید optimistic execution را متوقف کند

اگر دو holder متفاوت یک generation فعال را claim کنند یا state coordinator دو holder متناقض داشته باشد، ownership_conflict را حفظ کنید و auto-promotion را متوقف کنید. تا زمانی که record authoritative حل نشده، execution بیشتر نباید معتبر فرض شود. Heartbeat قوی یک worker هم contradiction در lease evidence را پاک نمی‌کند.

13. Evidence matrix تصمیم را قابل بازتولید می‌کند

برای هر case این فیلدها را نگه دارید: Job ID، Lease ID، Generation، Holder Identity، Issued At، Lease Duration، Expires At، ACK Deadline/State، Renew Sequence/Time، Progress Sequence/Value، Cancel Requested/ACK، Terminal Result، Stale Generation، Late Progress، Lease Expired، Ownership Conflict، Decision و Reason. Reviewer باید بدون hidden reasoning بتواند transition را بازسازی کند.

14. Failure Probeهای تعیین‌کننده

چهار shortcut را رد کنید: (1) generation 7 منقضی شده و بعد از فعال‌شدن generation 8 late renew می‌فرستد → generation 8 حفظ و stale rejection ثبت شود؛ (2) worker ACK می‌کند ولی terminal result ندارد → ACK completion نیست و expiry authoritative می‌ماند؛ (3) progress sequence 12 بعد از 14 می‌رسد → progress عقب نرود؛ (4) هنگام disconnect cancel درخواست شده و late progress می‌رسد → cancellation/expiry policy حفظ و terminal reconciliation لازم باشد. Lab label نهایی را از learner پنهان نگه می‌دارد.

15. Transfer به streaming transport با reorder

Polling request/response را با streaming channelی عوض کنید که progress و renew را reorder می‌کند. Lease identity/generation، holder binding، expiry، monotonic progress، cancellation و terminal semantics باید ثابت بمانند. هر پیام از identity، generation، sequence و timestamp خودش دوباره ارزیابی شود؛ arrival order شبکه authority نیست. Reorder ممکن است audit timing را تغییر دهد، اما مالک lease را تغییر نمی‌دهد.