Shadow Mode Before Direct Publish

1. Problem: staging is not production intent

A payload can look correct in staging while the production target account, policy snapshot, quota, capability, or duplicate risk is different. Jumping from a green local test to a live publish collapses several uncertainties into one external side effect. The lesson artifact is Shadow Publish Evaluation Packet v1.

2. Lesson boundary

PLN-022 materializes and evaluates the exact intended publish request with zero external side effect. PLN-021 owns capability registry evidence; PLN-023 owns the bounded direct-publish/idempotency transaction. This lab performs no network call and no real publish.

3. External FACT versus MAKNOW DESIGN

Kubernetes provides an official server-side dry-run pattern where normal validation/admission stages run but the object is not persisted and side effects are prevented. GitHub recommends testing an integration after adapting it to a new REST API version and its breaking changes. The SHADOW_PASS / SHADOW_FAIL / UNVERIFIED_EXTERNAL states and gates are MAKNOW DESIGN.

4. Bind intent and target before validation

publish_intent_id, target_account, target_resource, and operation identify one intended action. If the target changes after the payload hash is computed, the old shadow conclusion is invalid even when the text looks identical.

5. Canonical payload and hash must be exact

Shadow mode evaluates the same canonical request that could later become the direct-publish candidate. payload_hash must remain bound to payload and target. A similar preview is not equivalent evidence.

6. Keep snapshots separate

adapter_snapshot_id, capability_snapshot_id, policy_snapshot_id, and quota_snapshot_id represent distinct evidence. A healthy adapter cannot compensate for stale policy or unknown quota. Each decisive snapshot needs freshness and provenance.

7. Local validation is necessary, not sufficient

Schema, required fields, payload size, and target-diff can be checked locally. A local failure supports SHADOW_FAIL. A local pass without an official provider dry-run still leaves provider acceptance UNVERIFIED_EXTERNAL.

8. Use provider dry-run only when officially documented

When a provider exposes an official validate-only/dry-run mechanism, evaluate the exact request through it and record provider_validation_result. A local mock or staging account does not create provider authority.

9. Zero external side effect is a gate

external_side_effect must remain NONE. If the validation path creates a real post, message, file, or resource, it is no longer shadow mode and must fail closed.

10. Target diff and duplicate risk come before publish

target_diff makes target mismatch explicit. duplicate_risk records risk before the direct-publish lesson. Shadow mode does not create a duplicate merely to test duplicate behavior.

11. Bounded state machine

SHADOW_PASS requires exact binding, current snapshots, passing local validation, and authoritative provider validation where available, with zero side effect. Clear mismatch/failure yields SHADOW_FAIL. If provider acceptance cannot be officially tested, preserve UNVERIFIED_EXTERNAL; do not coerce UNKNOWN/STALE_EVIDENCE/BLOCKED into success.

12. Baseline: locally clean, externally unverified

The baseline has exact request binding, current snapshots, and passing local checks, but the provider does not document a publish dry-run. The correct state is UNVERIFIED_EXTERNAL, not SHADOW_PASS.

13. Dangerous shortcuts

Do not change target after hashing; do not equate staging with the production target; do not invent unsupported dry-run semantics; do not override stale policy with a green local check; and do not reuse a provider result from another target.

14. Transfer: provider with official validate-only

The transfer provider documents a no-persist dry-run. The exact target/payload is evaluated, result and provenance are recorded, and SHADOW_PASS becomes possible when all gates pass. That still does not authorize PLN-023 execution or a live publish.

15. Lab, assessment, and freshness

Run python run_checks.py under lab/PLN-022-LAB1/learner/. Eight fixtures cover baseline, target mismatch, stale policy, local failure, official dry-run pass/fail, missing provenance, and transfer. Kubernetes and GitHub sources were rechecked on 2026-09-16. Canonical byte changes require a new package version.