برنامه‌ریزی، تحلیل و عملیات پلتفرم · فصل ۴ — Adapter، Capability، Shadow/Direct Publish و Quota · 213

Shadow Mode قبل از Direct Publish

داده و event دارد اما آن‌ها را به مدل تصمیم، attention، experiment یا platform policy قابل توضیح تبدیل نمی‌کند. موضوع جاری: «Shadow Mode قبل از Direct Publish». می‌تواند برای «Shadow Mode قبل از Direct Publish» model، signal و guardrail لازم را در یک workflow محدود تعریف و ارزیابی کند.

خلاصهٔ درس

داده و event دارد اما آن‌ها را به مدل تصمیم، attention، experiment یا platform policy قابل توضیح تبدیل نمی‌کند. موضوع جاری: «Shadow Mode قبل از Direct Publish».

می‌تواند برای «Shadow Mode قبل از Direct Publish» model، signal و guardrail لازم را در یک workflow محدود تعریف و ارزیابی کند.

خروجی این درس

می‌تواند برای «Shadow Mode قبل از Direct Publish» model، signal و guardrail لازم را در یک workflow محدود تعریف و ارزیابی کند.

پیش‌نیازها

PLN-020 PLN-021

1. مسئله: Staging معادل Production Intent نیست

یک payload ممکن است در staging درست به نظر برسد اما target account، policy snapshot، quota، capability یا duplicate risk در production متفاوت باشد. اگر از «local test سبز» مستقیم به Publish واقعی بپریم، چند نوع uncertainty را در یک side effect خارجی ادغام کرده‌ایم. خروجی این درس Shadow Publish Evaluation Packet v1 است.

2. مرز درس

PLN-022 فقط درخواست دقیقِ intended publish را بدون side effect خارجی materialize و ارزیابی می‌کند. Capability Registry مربوط به PLN-021 و تراکنش Direct Publish و Idempotency مربوط به PLN-023 خارج از Scope هستند. این Lab هیچ درخواست شبکه‌ای یا Publish واقعی انجام نمی‌دهد.

3. FACT خارجی و MAKNOW DESIGN

Kubernetes نمونه رسمی server-side dry-run دارد: request معمولی از validation/admission عبور می‌کند اما persist یا side effect نمی‌شود. GitHub نیز هنگام تغییر نسخه REST API توصیه می‌کند integration پس از اعمال breaking changes تست شود. اما SHADOW_PASS / SHADOW_FAIL / UNVERIFIED_EXTERNAL و Gateهای این درس MAKNOW DESIGN هستند.

4. Intent و Target را قبل از Validation ببند

publish_intent_id، target_account، target_resource و operation یک Intent مشخص را هویت می‌دهند. اگر target بعد از محاسبه payload hash تغییر کند، نتیجه shadow قبلی معتبر نیست حتی اگر payload text یکسان بماند.

5. Canonical Payload و Hash باید دقیق باشند

Shadow باید همان canonical requestی را بررسی کند که بعداً candidate مستقیم خواهد بود. payload_hash باید با payload و target binding هم‌خوان باشد. Preview تقریبی یا payload دیگری که «شبیه» است evidence کافی نیست.

6. Snapshotها را جدا نگه دار

adapter_snapshot_id، capability_snapshot_id، policy_snapshot_id و quota_snapshot_id چهار حقیقت متفاوت‌اند. Adapter سبز نمی‌تواند policy منقضی یا quota نامعلوم را جبران کند. هر snapshot باید provenance و freshness قابل دفاع داشته باشد.

7. Local Validation لازم است، کافی نیست

Schema، required fields، payload size و target-diff را می‌توان محلی کنترل کرد. اگر local validation fail شود، SHADOW_FAIL روشن است. اگر local validation pass شود اما Provider هیچ dry-run رسمی ندارد، external acceptance هنوز UNVERIFIED_EXTERNAL است.

8. Dry-run رسمی را فقط وقتی استفاده کن که مستند است

اگر Provider validate-only/dry-run رسمی دارد، همان exact request را در آن مسیر بررسی کن و provider_validation_result را ثبت کن. وجود یک sandbox یا mock محلی به‌تنهایی Provider authority نیست.

9. Zero External Side Effect یک Gate است

external_side_effect در shadow باید NONE باشد. اگر validation path پیام، پست، فایل یا resource واقعی ایجاد کند، دیگر Shadow Mode نیست. چنین fixtureی باید fail-closed شود.

10. Target Diff و Duplicate Risk قبل از Publish

target_diff اختلاف target مورد انتظار و request materialized را نشان می‌دهد. duplicate_risk احتمال تکرار اثر را قبل از Direct Publish ثبت می‌کند. Shadow Mode duplicate را اجرا نمی‌کند؛ فقط risk را visible می‌کند.

11. State machine محدود

SHADOW_PASS فقط وقتی مجاز است که exact binding، snapshot freshness، local validation و در صورت نیاز official provider validation همگی قابل اتکا باشند و side effect صفر باشد. SHADOW_FAIL برای mismatch/failure روشن است. اگر provider acceptance قابل آزمون رسمی نیست، UNVERIFIED_EXTERNAL را حفظ کن. UNKNOWN/STALE_EVIDENCE/BLOCKED را به success تبدیل نکن.

12. Baseline: local clean، provider unverified

در baseline request دقیق است، snapshotها تازه‌اند و local checks پاس می‌شوند، اما provider publish dry-run رسمی ندارد. نتیجه درست UNVERIFIED_EXTERNAL است، نه SHADOW_PASS. این تفاوت هسته درس است.

case_id	target_account	operation	local_validation	provider_dry_run_support	provider_validation_result	target_diff	duplicate_risk	shadow_state	release_decision
baseline_no_official_dryrun	acct-prod-A	create_post	PASS	UNSUPPORTED	None	NONE	LOW	UNVERIFIED_EXTERNAL	DEFER_DIRECT_PUBLISH
target_changed_after_hash	acct-prod-B	create_post	PASS	UNSUPPORTED	None	TARGET_CHANGED	LOW	SHADOW_FAIL	BLOCKED
stale_policy_snapshot	acct-prod-A	create_post	PASS	UNSUPPORTED	None	NONE	LOW	STALE_EVIDENCE	BLOCKED
local_validation_failure	acct-prod-A	create_post	FAIL	UNSUPPORTED	None	NONE	LOW	SHADOW_FAIL	BLOCKED
official_dryrun_pass	cluster-A	apply	PASS	OFFICIAL_NO_SIDE_EFFECT	PASS	NONE	LOW	SHADOW_PASS	ELIGIBLE_FOR_SEPARATE_DIRECT_PUBLISH_GATE
official_dryrun_fail	cluster-A	apply	PASS	OFFICIAL_NO_SIDE_EFFECT	FAIL_ADMISSION	NONE	LOW	SHADOW_FAIL	BLOCKED
missing_provenance	acct-prod-A	create_post	PASS	OFFICIAL_NO_SIDE_EFFECT	PASS	NONE	LOW	UNKNOWN	BLOCKED
transfer_official_validate_only	cluster-B	apply	PASS	OFFICIAL_NO_SIDE_EFFECT	PASS	NONE	MEDIUM_REVIEWED	SHADOW_PASS	ELIGIBLE_FOR_SEPARATE_DIRECT_PUBLISH_GATE

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

Target را بعد از hash عوض نکن؛ staging account را معادل production account نگیر؛ dry-run پشتیبانی‌نشده را جعل نکن؛ snapshot قدیمی را با local green override نکن؛ و provider response یک محیط دیگر را برای target فعلی reuse نکن.

14. Transfer: Provider دارای validate-only رسمی

در transfer، Provider یک dry-run رسمی بدون persist دارد. همان exact target/payload وارد مسیر validate-only می‌شود، result و provenance ثبت می‌شوند و اگر همه Gateها پاس باشند SHADOW_PASS ممکن است. این هنوز اجازه اجرای PLN-023 یا Publish واقعی نیست.

15. Lab، Assessment و Freshness

در lab/PLN-022-LAB1/learner/ دستور python run_checks.py را اجرا کن. هشت fixture شامل baseline، target mismatch، stale policy، local failure، official dry-run pass/fail، missing provenance و transfer هستند. منابع Kubernetes و GitHub در 2026-09-16 دوباره بررسی شدند؛ تغییر canonical bytes نیازمند نسخه جدید است.

ارزیابی

پاسخ‌نامه‌ی این درس در بسته‌ی آموزش وجود ندارد؛ خودت جواب بده و صادقانه علامت بزن. «نیاز به مرور» درس را به صف تکرار می‌فرستد.

PLN-022-S1 retrieval

Why can local validation pass while external acceptance remains UNVERIFIED_EXTERNAL?

lesson ✗AI ✗notes ✗

PLN-022-S2 application

Build the shadow packet for an exact request when the provider has no documented dry-run.

lesson ✗AI ✗notes ✗

PLN-022-S3 diagnosis

Why does changing the target after payload hashing invalidate the prior shadow result?

lesson ✗AI ✗notes ✗

PLN-022-S4 transfer

Rebuild the packet for a provider with an official no-side-effect validate-only mechanism.

lesson ✗AI ✗notes ✗

ملاک‌های ارزیابی (rubric)

Blocking dimensions: lesson scope; exact intent/target binding; payload hash binding; snapshot freshness; local validation; official provider-validation boundary; zero external side effect; changed-context transfer. A passing answer must preserve UNVERIFIED_EXTERNAL when provider acceptance cannot be officially tested.

منابع و تازگی

Kubernetes API Concepts — Dry-run

Official server-side dry-run processes normal request stages without persistence or side effects; used as an example pattern, not a universal provider capability.

GitHub REST API — API Versions / Breaking Changes

GitHub advises integration testing when upgrading API versions; this is validation discipline, not evidence of a publish dry-run.