livrare lot 2

backend/services/orchestration-layer/agent-v3/SCALING.md

@@ -0,0 +1,51 @@
+# Scalare workeri — as code (Modul 9)
+
+Livrează cerința ofertei §3.9: **„Număr de replici per worker configurabil"** +
+recuperarea/scalarea pe bază de metrici. Fără autoscaler extern — semnalul de
+backpressure este gauge-ul Prometheus `didi_queue_depth` (alimentat de
+queue-depth poller din agent-v3). Aceasta este orchestrarea „echivalentă"
+permisă de caiet la E3 („orchestrare/deploy … sau echivalent").
+
+## Utilizare
+
+```bash
+cd backend/services/orchestration-layer/agent-v3
+
+./scale-workers.sh status              # replici curente + backlog live per worker
+./scale-workers.sh set worker-claims 5 # scalare manuală a unui worker
+./scale-workers.sh auto                # plan metric-driven (dry-run)
+./scale-workers.sh auto --apply        # aplică planul
+```
+
+## Politica de scalare
+
+`desired = clamp( ceil(backlog / TARGET_PER_REPLICA), MIN, MAX )`
+
+| Worker | component (metric) | MIN | MAX | Target msgs/replica |
+|---|---|---|---|---|
+| worker-techniques | techniques | 2 | 8 | 25 |
+| worker-ai-tampered | ai_tampered | 2 | 8 | 25 |
+| worker-claims | claims | 3 | 12 | 20 |
+| worker-domain | domain | 2 | 6 | 30 |
+| worker-media-preprocess | media_preprocess | 2 | 6 | 5 |
+
+Praguri editabile în blocul `POLICY` din `scale-workers.sh`. `claims` are
+target mai mic + MAX mai mare (verificarea web e cea mai lentă); media-preprocess
+target 5 (job-uri grele: yt-dlp/Whisper/vision).
+
+## Rulare periodică (auto-scaling continuu)
+
+Cron pe host, la fiecare minut:
+
+```cron
+* * * * * cd /home/admin365/didi_mono/didi_mono/backend/services/orchestration-layer/agent-v3 && ./scale-workers.sh auto --apply >> /var/log/didi-scale.log 2>&1
+```
+
+Alertă complementară: `RabbitMQQueueBacklog` (Prometheus) se declanșează la
+backlog >100 pentru 10 min — semnal că MAX-ul politicii trebuie ridicat.
+
+## Verificat live (2026-07-02)
+
+`status` citește replici reale + backlog din Prometheus; `set worker-domain 4`
+pornește 2 containere noi; `set worker-domain 2` le oprește. `auto` calculează
+corect desired din backlog.