Workflow Registry و Qualified Packages

1. مسئله واقعی: نام نسخه، مدرک qualification نیست

فرض کن workflowای با نام support-summary:3 امروز همه آزمون‌ها را پاس کرده است. فردا prompt از p12 به p13 تغییر می‌کند، route policy یک مدل جدید را مجاز می‌کند یا dependencyای با همان semantic version ولی digest متفاوت جایگزین می‌شود. اگر Registry فقط نام، tag یا نسخه متنی را ببیند، ممکن است همان برچسب QUALIFIED را روی محتوایی نگه دارد که evidence قبلی هرگز آن را ندیده است.

هدف این درس ساخت Registryای است که هویت قابل اجرا را از alias انسانی جدا کند. package فقط وقتی QUALIFIED است که digest خودش و همه referenceهای تعیین‌کننده دقیقاً با qualification bundle ثبت‌شده match باشند. هر drift تعیین‌کننده یک candidate جدید می‌سازد؛ نه اینکه رکورد قبلی را بی‌صدا ویرایش کند.

2. سه لایه را از هم جدا کن: alias، package identity و evidence identity

invoice-v3، prod یا stable برای انسان مفیدند، اما immutable نیستند. این‌ها alias هستند. در مقابل، package identity باید به digest محتوای canonical manifest متصل باشد. لایه سوم، evidence identity است: qualification bundle باید دقیقاً بگوید کدام package digest، کدام model qualification، serving evidence و dependency digests را ارزیابی کرده است.

قاعده ساده: alias برای discoverability؛ digest برای identity؛ evidence bundle برای qualification. هیچ‌کدام جای دیگری را نمی‌گیرد.

3. Manifest حداقلی Qualified Workflow Package

Manifest عملی باید دست‌کم این فیلدها را نگه دارد: package_name, human_alias, package_digest, workflow_spec_version, prompt_version, schema_version, adapter_version, route_policy_version, cost_policy_version, model_qualification_ref, serving_evidence_ref, dependency_digests, environment_requirements, qualification_bundle_ref, status, promotion_record, requalification_triggers, و rollback_digest.

این فهرست فقط inventory نیست؛ یک decision boundary است. اگر هر field تعیین‌کننده عوض شود، package جدید باید دوباره evidence بگیرد. تغییرات presentation-only که وارد canonical digest نمی‌شوند باید صریحاً جدا و non-decisive تعریف شوند.

4. Digest و tag چه چیزی را ثابت می‌کنند؟

OCI Image Manifest برای content-addressable artifactها از descriptor/digest استفاده می‌کند و Distribution Spec نیز digest را شناسه مشتق از hash محتوا و tag را reference انسانی تعریف می‌کند. این الگو برای طراحی Registry بسیار مفید است: tag می‌تواند به manifest دیگری اشاره کند، ولی digest یک reference محتوایی دقیق است. cite:OCI-IMAGE-MANIFEST cite:OCI-DISTRIBUTION

اما MAKNOW از این استاندارد فقط الگوی هویت immutable را می‌گیرد. این درس نمی‌گوید workflow package باید OCI image باشد، و OCI هم state machine اختصاصی qualification ما را تعریف نمی‌کند.

5. Decisive dependency یعنی چه؟

هر چیزی که می‌تواند رفتار، safety، contract، route، cost یا نتیجه execution را تغییر دهد decisive است. نمونه‌ها: workflow spec، prompt، output schema، adapter، route policy، cost policy، model qualification reference، serving configuration و dependency digest. اگر route-policy-r7 به r8 تغییر کند و r8 مدل جدیدی را اجازه دهد، حتی اگر فایل workflow و prompt ثابت باشند، qualification قبلی کافی نیست.

Semantic version به‌تنهایی کافی نیست. اگر dependency با متن نسخه یکسان اما digest متفاوت جایگزین شود، identity واقعی تغییر کرده و باید requalification trigger فعال شود.

6. Qualification Bundle باید به چه چیزی bind شود؟

Bundle باید یک snapshot قابل ممیزی از package digest و تمام decisive refs داشته باشد. وضعیت QUALIFIED فقط وقتی مجاز است که observed package با snapshot evidence exact match داشته باشد و evidenceهای referenced خودشان معتبر، current و non-revoked باشند.

عبارت «این workflow قبلاً تست شده» کافی نیست. باید بتوانی نشان دهی: کدام bytes/configuration، در کدام environment، با کدام qualification refs، چه زمانی و تحت کدام policy ارزیابی شده است.

7. Lifecycle پیشنهادی Registry

Stateهای اصلی را جدا نگه دار: DRAFT برای بسته ناقص، CANDIDATE برای بسته کامل ولی هنوز بدون evidence کافی، QUALIFIED برای match کامل package/evidence، NEEDS_REQUALIFICATION برای drift تعیین‌کننده، SUSPENDED برای evidence موقتاً نامعتبر یا incident، و REVOKED برای بسته‌ای که دیگر نباید promotion/execute شود.

انتقال state باید event-driven و auditable باشد. هیچ stateای نباید فقط از روی tag انسانی یا آخرین successful run استنتاج شود.

8. Promotion: از Candidate تا Qualified

Promotion چهار gate دارد: 1) manifest کامل و canonical؛ 2) digest محاسبه و immutable؛ 3) decisive refs resolve و evidence قابل ردیابی؛ 4) qualification bundle exact-match. پس از PASS، Registry یک promotion record جدید می‌نویسد که candidate_digest → QUALIFIED را با evidence refs و زمان ثبت می‌کند.

رکورد qualified قبلی mutate نمی‌شود. اگر نسخه جدید آمد، رکورد جدید ساخته می‌شود و alias می‌تواند بعداً به digest جدید repoint شود؛ اما repoint شدن alias خودش qualification تولید نمی‌کند.

9. Mutable alias و خطای خطرناک «همان نسخه است»

فرض کن support-summary:3 دیروز به digest sha256:AAA اشاره می‌کرد و QUALIFIED بود. امروز alias همان است اما به sha256:BBB repoint شده. downstreamی که qualification را با alias lookup کند، ممکن است BBB را به اشتباه qualified بداند.

راه درست: downstream باید digest-qualified reference بگیرد. اگر alias resolve شد، digest نهایی باید با qualified digest مقایسه شود. mismatch = NEEDS_REQUALIFICATION یا BLOCK execution، نه silent inheritance.

10. Drift در dependency و model route

تغییر decisive ref حتی اگر package name یا top-level version ثابت باشد، candidate جدید می‌سازد. مثال انتقال این درس: workflow/prompt/schema ثابت‌اند، اما route policy حالا model جدیدی را مجاز می‌کند که qualification ref ندارد. نتیجه QUALIFIED نیست؛ package باید NEEDS_REQUALIFICATION شود تا model path جدید evidence بگیرد یا policy به وضعیت قبلی rollback شود.

این همان جایی است که «aggregate success» گمراه‌کننده است: یک run موفق روی model قبلی هیچ evidenceای برای path جدید ایجاد نمی‌کند.

11. Suspension، Revocation و Rollback

اگر qualification ref منقضی، revoked یا در incident review قرار گرفت، package می‌تواند SUSPENDED شود حتی اگر digest خودش تغییر نکرده باشد. REVOKED برای وضعیتی است که اجرای package دیگر نباید مجاز باشد. این دو state با NEEDS_REQUALIFICATION فرق دارند: requalification معمولاً به تغییر package/dependency مربوط است؛ suspension/revocation می‌تواند از تغییر اعتبار evidence بیرونی ناشی شود.

Rollback باید به یک digest قبلاً qualified اشاره کند، نه صرفاً tag قبلی. Registry باید rollback target و reason را ثبت کند و اجازه ندهد alias مبهم جای immutable rollback reference را بگیرد.

12. Lab: هشت fixture برای lifecycle واقعی

Lab هشت case deterministic دارد. baseline همه refs و evidence را match می‌کند و QUALIFIED می‌شود. سپس هر case یک بعد را تغییر می‌دهد: alias repoint، prompt drift، dependency digest drift، route-policy drift با model qualification مفقود، qualification bundle ناقص، alias rename بدون تغییر digest، و revoked evidence.

وظیفه learner پیاده‌سازی evaluate(case) است و باید هشت field را برگرداند: package_identity_state, alias_state, dependency_state, qualification_evidence_state, lifecycle_state, executable_state, rollback_state, reason_class.

13. Shortcutهای غلط

سه shortcut ممنوع‌اند: «tag ثابت است پس qualified است»، «آخرین run سبز بود پس همه dependencyها معتبرند»، و «semantic version یکی است پس bytes یکی‌اند». هر سه، evidence را از identity جدا می‌کنند.

همچنین Registry entry خودش quality یا safety را ثابت نمی‌کند. Registry فقط evidence را به package exact bind و lifecycle را enforce می‌کند؛ تولید evidence مسئولیت qualificationهای مالک هر domain است.

14. Audit Record باید چه چیزی را بازسازی کند؟

یک audit event خوب باید نشان دهد: alias در لحظه resolve به چه digestی رسید، canonical package digest چه بود، کدام decisive refs مقایسه شدند، qualification bundle چه digestی را پوشش می‌داد، mismatch دقیق کجا بود، state قبل/بعد چه بود، چه کسی/چه policy promotion یا suspension را ثبت کرد و rollback digest چیست.

اگر reviewer نتواند فقط با Registry record تصمیم را بازسازی کند، system هنوز evidence-closed نیست.

15. Exit checklist و تمرین انتقال

قبل از PASS نهایی پنج سؤال را جواب بده: آیا downstream با digest qualified اجرا می‌کند؟ آیا هر decisive change requalification trigger دارد؟ آیا alias rename از alias repoint تفکیک شده؟ آیا revoked/stale evidence state واقعی خودش را حفظ می‌کند؟ آیا rollback به digest ثابت اشاره دارد؟

تمرین انتقال: route policy را طوری تغییر بده که model جدیدی را بدون qualification ref مجاز کند، در حالی که workflow/prompt/schema bytes ثابت مانده‌اند. Registry باید نشان دهد چرا top-level tag نمی‌تواند QUALIFIED قبلی را به path جدید منتقل کند و چه evidenceای برای بازگشت به QUALIFIED لازم است.