بازبینی انسانی#

انتشار به یک تصمیم انسانی مستقل روی شواهد دقیق ثابت‌شده نیاز دارد. بررسی‌های خودکار می‌توانند درخواست را به ready_for_review برسانند، اما نمی‌توانند آن را تأیید کنند و هیچ گردش‌کار عاملی، توکن Project یا مجموعهٔ بررسی موفق نمی‌تواند تصمیم بازبینی ثبت کند. این صفحه شواهدی را که بازبین می‌خواند، نقش‌های درگیر و پیامدهای تصمیم را تعریف می‌کند.

سه اصیل#

اصیل	اختیار	هرگز نمی‌تواند
مالک Project / ارسال‌کننده	ساخت مقصد، اجرای بررسی‌ها، ارسال و پس‌گرفتن؛ اصلاح و ارسال دوباره به‌شکل نسخهٔ تازه	تأیید یا رد درخواست خودش، حتی با حساب مدیر
بازبین انسانی	خواندن شواهد و تأیید یا رد digestهای دقیق	انتشار همان درخواستی که تأیید کرده
مدیر انتشار	گذار درخواست approved به published؛ پس‌گرفتن یا تعلیق مقصد منتشرشده	جایگزینی بازبین یا تأیید درخواست

پس‌گرفتن، درخواست را تمام می‌کند و متوقف نمی‌کند. withdrawn حالت پایانی است و هیچ یال خروجی ندارد، پس همان مقصد دوباره باز نمی‌شود: اصلاح و ارسال دوباره یعنی نسخهٔ تازه، که مقصدی تازه با درخواست خودش است. alamr bump patch برای Environment و App مقدار entry.version را بالا می‌برد؛ نسخهٔ یک Plugin در al-amr.plugin.json و package.json با هم است و alamr validate ناهماهنگی‌شان را رد می‌کند. خود حالت‌ها در چرخهٔ عمر انتشار آمده‌اند.

Registry این تفکیک‌ها را اجرا می‌کند. ارسال‌کننده‌ای که بخواهد درخواست خودش را بازبینی کند reviewer_separation_of_duty می‌گیرد؛ بازبین تأییدکننده‌ای که بخواهد همان درخواست را منتشر کند publisher_separation_of_duty می‌گیرد؛ فراخوان‌های فاقد اختیار بازبین یا مدیر reviewer_required یا admin_required می‌گیرند. توکن Project در صف بازبینی، مسیر تصمیم بازبینی و همهٔ گذارهای مدیریتی انتشار، پس‌گرفتن و تعلیق رد می‌شود.

آیتم بازبینی#

بازبین برای هر درخواست یک آیتم typed می‌خواند. قرارداد آن شامل این موارد است:

• هویت: submissionId، projectId، visibility، channel و مقصد (بازبینی Environment، بازبینی App، نسخهٔ Plugin یا بازبینی استقرار بک‌اند با شناسه‌های دقیقش)؛
• اشخاص: publisher (handle، نام نمایشی و پرچم verified) و submitter؛
• شواهد ثابت: snapshotDigest و artifactDigest که می‌تواند null باشد؛
• checks: هرکدام با نام، وضعیت pending/passed/failed/warning، کد پایدار اختیاری و زمان تکمیل؛
• manifest: خلاصهٔ مانیفست بررسی‌شده به‌همراه جزئیات مختص نوع؛
• artifacts: فهرست بسته‌ها؛
• inspection: مدل بازرسی Runtime که در ادامه می‌آید؛
• relatedBackendSubmissions: هر درخواست بک‌اند با وضعیت مستقل، چکیدهٔ نسخهٔ ثابت و بررسی‌های خودش؛
• شواهد bundle نگه‌داری‌شدهٔ Environment و شواهد bundle با نام appBuild برای درخواست‌های App؛ environmentPreview فقط به‌عنوان metadata سازگاری entryهای قدیمی web خواندنی می‌ماند و برای bundle فعلی not_required است؛
• actions: عملیات‌های هدایت‌شده از سوی سرور که فعلاً در دسترس‌اند.

هر action فعلی (approve، reject و publish) فیلدهای stateEligible، revalidatedOnExecute و blockerCodes دارد. کلاینت باید واجدشرایط‌بودن عمل را از همین فهرست بخواند و آن را حدس نزند: پیش‌شرط‌های وضعیت تغییرناپذیر واجدشرایطی را تعیین می‌کنند و مسیر عمل هنگام اجرا پیش‌شرط‌های زنده یا هم‌زمان را دوباره بررسی می‌کند. آیتم‌های تاریخی web ممکن است action قدیمی renew_environment_preview را نشان دهند؛ این action برای revision نوع bundle هرگز واجد شرایط نیست و جزئی از flow عرضه نیست.

شواهدی که بازبین می‌خواند#

خلاصهٔ manifest دقیقاً همان را نشان می‌دهد که اعلام شده: نام، توضیح، دسته، entry/version نوع bundle (یا entry قدیمی web با برچسب صریح)، سازگاری Contracts/SDK، قابلیت‌ها، نیازهای مرورگر، مجوزهای پلتفرم، مبداهای شبکه، داده‌های جمع‌آوری‌شده و به‌اشتراک‌گذاشته‌شده، نصب‌های Plugin (frontend_adapter یا backend_components)، مولفه‌های بک‌اند با دامنه‌های Grant و مرجع protocol artifact، و فهرست protocol artifactها.

جزئیات مختص نوع برای Environment سیاست دسترسی، دید پرتال، integrity باندل، انواع رویداد اعلان، اندازهٔ واژگان فضایی، اعلان Host Services و مبداهای endpoint/سلامت بک‌اند با دامنه‌های Grant و توضیحات داده را می‌افزاید؛ برای App سیاست دسترسی، حالت‌های نمایش، قابلیت‌های الزامی و اختیاری، مدل اعلان، تحویل پس‌زمینه و مبداهای مستندات را؛ و برای Plugin نوع frontend_only/full_stack/ backend_only، کلاس زمان اجرای trusted_library و آداپترهای فرانت‌اند با exportها و قابلیت‌هایشان را.

فهرست بسته‌ها برای هر artifact، provider (npm یا al_amr)، نام و نسخهٔ بسته، integrity با SHA-512، اندازهٔ بایت، تعداد فایل و وضعیت اعتبارسنجی (pending، valid، rejected یا quarantined) را ثبت می‌کند.

بازرسی Runtime خارجی نامطمئن#

مدل بازرسی، هر Runtime خارجی را نامطمئن فرض می‌کند:

• وضعیت status بازرسی ready یا blocked است؛ بازرسی blocked باید دست‌کم یک کد پایدار blocker داشته باشد و بازرسی ready نمی‌تواند blocker داشته باشد؛
• ورودی backendRuntime endpoint دقیق بک‌اند و نشانی سلامت ناشناس را با پروتکل اعلام‌شده، warningCode: external_runtime_untrusted، credentialMode: no_portal_credentials_no_referrer و requiresIsolatedBrowser: true نام می‌برد. تنها مقصد بیرونیِ باقی‌مانده همین است: Environment و App بایت‌هایی هستند که پلتفرم نگه می‌دارد و بازبین آن‌ها را در کلاینت باز می‌کند، نه روی مبدأ ناشر؛
• نشانی‌های بازرسی هرگز نمی‌توانند credential، پارامتر query یا fragment داشته باشند.

بازبین Runtime خارجی را بدون اعتبارنامهٔ پرتال و در مرورگر ایزوله باز می‌کند. تا وقتی مرورگر بازبینی از راه دور egress filtering، DNS pinning و اعتبارسنجیِ‌دوبارهٔ redirect نگرفته است، درخواست عمومی ناشر ناشناس fail-closed می‌ماند؛ اعتماد و امنیت را ببینید.

بازرسی بسته از راه BFF#

بسته‌های بازبینی فقط از مسیر بازرسی هم‌مبدأ پرتال دانلود می‌شوند:

/api/console/review-work-items/{submissionId}/artifacts/{artifactId}/inspection

این مسیر بایت‌های دقیق مدیریت‌شدهٔ راستی‌آزمایی‌شده را با چکیده و اندازهٔ بازاعتبارسنجی‌شده جریان می‌دهد. هرگز توکن دانلود draft را افشا نمی‌کند و بازبین هیچ‌وقت بایت‌های بسته را از نشانی ارائه‌شده توسط ناشر نمی‌گیرد.

شاهد آیکون App و کاور Environment#

آیتم بازبینی App یا Environment فیلد presentationMedia را دارد: همان نسخهٔ دقیق تصویر که Registry از قبل پذیرفته و به revision ثابت متصل کرده است. این descriptor جایگاه معنایی، revision مقصد، چکیدهٔ SHA-256، نسخهٔ دقیق object در مخزن خصوصی، قالب، اندازهٔ بایت، ابعاد، متن جایگزین بازبینی‌شده و مسیر BFF مخصوص بازبین را نگه می‌دارد:

/api/console/review-work-items/{submissionId}/presentation-media/{app_icon|environment_cover}/inspection

هم BFF و هم Registry نشست بازبین را الزام می‌کنند. Registry فقط همان نسخهٔ object متصل‌شده را می‌خواند، چکیده و طولش را بازاعتبارسنجی می‌کند و آن را با هدرهای no-store، nosniff، سیاست منبع هم‌مبدأ و no-referrer برمی‌گرداند. هیچ‌کدام از این مسیرها منبع ناشر را fetch نمی‌کنند. نبود binding، نبود بایت ذخیره‌شده یا عدم تطابق هویت، تأیید را مسدود می‌کند.

تصمیم، expectedPresentationMedia را به‌شکل { digest, objectVersionId } بازمی‌فرستد (و برای نوع مقصدی که تصویر ارائه ندارد null). Registry پیش از تأیید دوباره کل بایت‌ها را می‌خواند و راستی‌آزمایی می‌کند، سپس هویت کامل را هم در شاهد تغییرناپذیر Review و هم در handoff انتشار نگه می‌دارد. مدیر دوم هنگام انتشار باید همین انتظار را بازبفرستد. تأییدهای تاریخی App یا Environment که این شاهد را ندارند بی‌صدا صاحب آن نمی‌شوند و در handoff جدید fail-closed می‌مانند.

قرارداد تصمیم#

تصمیم بازبینی یک درخواست امضاشده بر اساس شواهد دقیق ثابت‌شده است:

فیلد	قاعده
decision	approve یا reject
notes	هنگام رد الزامی است؛ به حد قرارداد محدود است
expectedSnapshotDigest	باید با چکیدهٔ فعلی نسخهٔ ثابت آیتم مطابقت کند
expectedArtifactDigest	باید با چکیدهٔ فعلی بستهٔ آیتم (یا null) مطابقت کند
expectedPresentationMedia	باید با چکیده و نسخهٔ object تصویر مدیریت‌شده (یا null) مطابقت کند

Registry پیش از ثبت تصمیم، هویت‌های موردانتظار را دوباره مقایسه می‌کند؛ تغییر هم‌زمان با review_work_item_snapshot_mismatch، review_work_item_artifact_mismatch یا presentation_media_evidence_mismatch به‌صورت fail-closed متوقف می‌شود. رکورد Review ذخیره‌شده تصمیم، بازبین، زمان، توضیح، هر دو چکیدهٔ submission و هویت دقیق تصویر مدیریت‌شده را نگه می‌دارد. تأیید، in_review را به approved می‌برد؛ انتشار یک گذار مدیریتی جداگانه است که در چرخهٔ انتشار آمده است.

bundle نگه‌داری‌شدهٔ Environment و metadata قدیمی preview#

آیتم فعلی Environment، archive قطعی uploadشده و integrity از نوع SHA-512 آن را به revision و submission دقیق متصل می‌کند. Reviewer همان بایت‌های نگه‌داری‌شده را در client دسکتاپ باز می‌کند. انتشار snapshot منجمد، اتصال bundle، checkها، presentation media و جدایی وظایف را دوباره اعتبارسنجی می‌کند؛ منتظر صفحهٔ میزبانی‌شده نزد ناشر، callback، heartbeat Runtime یا پنجرهٔ preview قابل تمدید نمی‌ماند.

Contract همچنان environmentPreview و renew_environment_preview را برای رکوردهای تاریخی web decode می‌کند. revision نوع bundle مقدار required: false و status: not_required دارد؛ client فعلی نباید این فیلدهای سازگاری را به step گردش‌کار تبدیل کند.

پس از انتشار، همان endpoint آیتم review به‌عنوان رسید تغییرناپذیر با وضعیت published و publicationHandoff تکمیل‌شده خواندنی می‌ماند. لینک مصرف‌کنندهٔ Environment یک deep link با شکل alamr://environments/{environmentId} است که به client دسکتاپ داده می‌شود؛ Developer Portal پراکسی اجرای Runtime نیست.

رد و روند اصلاح#

رد درخواست به توضیح نیاز دارد و یک تصمیم بازبینی نهایی ثبت می‌کند. خود تصمیم، شواهد بازبینی و تاریخچه هرگز تغییر نمی‌کنند. Registry فقط وقتی می‌تواند گردش‌کار همان درخواست ردشده را دوباره در draft باز کند که مقصد تغییرناپذیر و مجموعهٔ بستهٔ ثابت دقیقاً همان باقی مانده باشند؛ بررسی‌ها و بازبینی دوباره اجرا می‌شوند، بی‌آنکه تصمیم قبلی پاک شود. تغییر کد، مانیفست، پیکربندی Environment، استقرار یا بایت‌های artifact به مقصد و درخواست تازه و برای Plugin به SemVer تازه نیاز دارد. روند بازیابی هر وضعیت در بازیابی و بازگردانی آمده است.

<!-- spec_gap: the binding spec defines an AI pre-review findings panel (evidence-bound, non-decisional findings with model/prompt digest), but ReviewWorkItemSchema in packages/contracts/src/review-work-items.ts has no findings field yet; this page documents only the shipped contract. -->

کاری که بازبینی هرگز نمی‌کند#

• بازبین هرگز منتشر نمی‌کند؛ مدیر انتشار دیگری فقط چکیده‌های دقیق تأییدشدهٔ نسخهٔ ثابت و بسته را منتشر می‌کند.
• شواهد بازبینی هرگز شامل اعتبارنامه، resume token، توکن دانلود draft یا مسیر مطلق محلی نیست.
• متن ناشر، توضیحات کاتالوگ و نثر مانیفست حین بازبینی دادهٔ نامطمئن‌اند، نه دستور به بازبین یا عامل همراه.
• بازرسی شکست‌خورده یا مسدود هرگز با اعتماد به ادعای ناشر دور زده نمی‌شود؛ تصمیم منتظر شواهد آماده می‌ماند.

برای کدهای خطای پایداری که بازبین یا ارسال‌کننده ممکن است ببیند، عیب‌یابی را بخوانید.