Vault: SPEC-052 Invest exit-to-base sandbox

Invest-MyVexx/SPEC-052-TRADE-SPEC-EXIT-TO-BASE-SANDBOX.md

@@ -0,0 +1,76 @@
+# SPEC-052 — Invest Trade Specs + Alice Monitor + Exit-to-Base (paper sandbox)
+
+**SPEC-ID:** 052-MYVEXX  
+**Vincula:** 049, 050, 051  
+**Org Forgejo:** `myvexx` (≠ ligbox)  
+**Status:** 🧪 Sandbox paper (2026-08-05)  
+**Para:** Roger  
+
+## Objectivo
+
+Permitir: escolher índice/crypto → Alice investiga → **spec no Invest** (alvo, alavancagem simulada, modo de saída) → motor monitoriza → ao atingir alvo **fecha e volta à conta base** (paper).
+
+## Contrato da Spec (Invest)
+
+```json
+{
+  "symbol": "NVDA",
+  "asset_class": "equity",
+  "entry_price": 100.0,
+  "target_pct": 1.20,
+  "leverage_sim": 1.0,
+  "exit_mode": "aviso|semi|auto_paper",
+  "stop_pct": null,
+  "fill_timeout_sec": 300,
+  "on_fill_fail": "abort_alert"
+}
+```
+
+- `target_pct` = **+1,20%** sobre `entry_price` (lucro percentual).  
+- `leverage_sim` = factor só para P&L **simulado** (não broker live).  
+- `exit_mode`: ver tabela abaixo.
+
+## Modos de saída (aplicar todos)
+
+| Modo | Comportamento sandbox |
+|------|------------------------|
+| **aviso** | Ao alvo → `alerted`; não fecha sozinho |
+| **semi** | Ao alvo → `ready_to_close`; exige `POST .../confirm_close` |
+| **auto_paper** | Ao alvo → fecha já → `closed_to_base` |
+
+Live broker: **proibido** neste bridge (`ALLOW_LIVE_BROKER=0`).
+
+## Constraints (o “não realista” → regras)
+
+1. Alvo % = trigger, não garantia de fill.  
+2. Alavancagem = simulada até paper broker explícito.  
+3. Auto só em paper; live = degrau futuro + gate humano.  
+4. Spec no Invest/bridge = fonte da verdade (Alice lê, não inventa).  
+5. Equity vs crypto = mesmo contrato, adapters depois.  
+6. Polling sandbox; websocket = Fase B+.
+
+## API sandbox (bridge `:3100`)
+
+| Método | Path | Função |
+|--------|------|--------|
+| POST | `/sandbox/specs` | Criar spec |
+| GET | `/sandbox/specs` | Listar |
+| GET | `/sandbox/specs/{id}` | Detalhe |
+| POST | `/sandbox/specs/{id}/tick` | Actualizar preço (manual) |
+| POST | `/sandbox/specs/{id}/simulate` | Simular path até alvo |
+| POST | `/sandbox/specs/{id}/confirm_close` | Semi: confirmar fecho |
+
+Traefik: `https://invest.myvexx.com/api/agents/sandbox/...` (strip `/api/agents`).
+
+## Critério de done (sandbox)
+
+1. Criar spec NVDA alvo 1,20% modo `auto_paper`.  
+2. `simulate` sobe preço ≥ +1,20%.  
+3. Estado final `closed_to_base` + `pnl_pct` ≥ 1,20.  
+4. Modos `aviso` e `semi` testados no mesmo motor.
+
+## Fora de escopo 052
+
+- Ordem live / UTA funded  
+- UI React completa `/agents` (pode seguir em paralelo Fase A 051)  
+- Fork profundo OpenAlice (bridge consome specs; Alice UI depois)