Initial public ModelForge release

docs/architecture/PLACEMENT_EXPLAINABILITY.md

@@ -0,0 +1,20 @@
+# Placement Explainability
+
+`PlacementPlan` is the first-class explanation for both a dry-run and a real request. Both paths call
+the same planner. A plan records the requested capability/deployment, node and accelerator,
+eligibility, priority, current residents, external use, reserve, authoritative envelope requirement,
+headroom before and after, selected managed evictions, queue impact, verdict and typed reasons.
+
+Verdicts are `ADMIT`, `ADMIT_AFTER_EVICTION`, `QUEUE`, `REJECT_CAPACITY`, `REJECT_HEALTH`, and
+`REJECT_POLICY`. Reason codes include `INSUFFICIENT_SCHEDULABLE_VRAM`, `EXTERNAL_GPU_PRESSURE`,
+`RESIDENCY_CONFLICT`, `EVICTION_NOT_ALLOWED`, `DEADLINE_CANNOT_BE_MET`, `LEASE_CONFLICT`,
+`GPU_MEMORY_NOT_RECLAIMED`, and `SCHEDULER_STATE_STALE`.
+
+The operator dry-run answers “what if I invoke this capability now?” without loading a model. The UI
+shows the actual budget, pressure, residency, possible eviction, expected reclaimed bytes, cold-load
+cost and final reasons. Recent placement history is capped at 500 records. It contains safe request
+shape metadata only—never text, image, audio or client-supplied placement commands.
+
+Co-residency arithmetic yields at most `EXPECTED_SAFE`. `PROVEN_SAFE` requires two exact residents
+on the same worker generation, KNOWN attribution and a measured combined footprint. Promotion and
+scheduling readiness remain separate lifecycle decisions.