Progetto:BridgeShape Editor e Laboratorio

Documentazione BridgeShape: API e sintassi DSL · Motore e frontend · Ricette DSL · Smazzate di gioco

BridgeShape — Editor avanzato e Laboratorio di test (brief per Play)

Integra DEAL_ENGINE_SPEC.md §8.4 (editor) e §5.8 (statistiche). Origine: la scrittura degli scenari di "Gioco di eliminazione" (E1–E5) ha mostrato che il DSL è espressivo ma **non si vede come vengono generate le mani**: gli scenari risultavano sbilanciati (es. apertore 24 PO, risponditore 5; avversari a 0 PO che ricevono tutti i punti residui) e ce ne si accorge solo guardando mani a caso.

1. Il DSL è abbastanza generale? Lacune da colmare

Coperto bene: lunghezze, forma, PO totali/per seme, onori esatti (S=AKQJ, x), pattern, pairhcp, fermate, controlli, carte chiave, LTC, any/not, variabili, macro, contesto (dealer, contratto, attacco).

Lacune (in ordine di priorità):

1. Nessun controllo su come si distribuisce il resto. Le carte non vincolate vanno a caso alle mani libere. Servono:
   • default-opp: realistic (o quiet già esistente) con soglie ragionevoli per gli avversari;
   • hcp: e pairhcp: per ogni posizione anche come intervallo "tipico" (non solo filtro);
   • opzione spread: even che, dopo i vincoli, ripartisce gli onori residui senza concentrarli in una mano.
2. Vincoli di esito (post-filtro double-dummy): makes: 4S by opener, tricks: 10-11, lead-fails. Fondamentali per le tecniche di gioco (eliminazione, messa in presa, squeeze). Opzionali, con budget di tempo; se il solver non c'è → requires: dd e unsupported_feature. Il solver va eseguito solo dopo i filtri economici.
3. Vincoli di relazione fra mani (es. "i due avversari hanno insieme 8+ carte di ♥", "atout 3-2 / 4-1 fra i difensori"): oggi si ottengono solo fissando le lunghezze di entrambi.
4. Vincoli "morbidi"/pesati: preferenze (peso 0–1) invece di filtri duri, per mani più naturali senza far esplodere il tasso di rifiuto.
5. Carte o vincoli fissati dall'utente nel test (fixed, già in §5.6) con override temporanei.

2. Editor "potentissimo" (estende §8.4)

• Pannello Mani con le 4 posizioni, per ciascuna: barre min-max di lunghezze per seme, PO, griglia onori (deve / non deve / indifferente / "uno fra"), sempre sincronizzato col DSL testuale.
• Indicatori in tempo reale di fattibilità: mentre si modifica, calcolo esatto/rapido di: somma minimi vs 13 carte, somma minimi PO vs 40, onori richiesti in conflitto (stessa carta a due mani), stima del tasso di successo (campionamento rapido a 200 tentativi con barra di avanzamento).
• Avvisi di sbilanciamento (punto chiave): avvisa se la distribuzione implicita dei PO fra le mani è anomala (es. una mano ≥ 22 e il compagno ≤ 6; un avversario a 0 con l'altro a ≥ 12; coppia fuori da 23–33 senza motivo) e proponi la correzione.
• Validazione live con shapeaction=validate (errori, avvisi, descrizioni, requires).
• Cronologia e confronto: versioni salvate, diff DSL + diff statistiche fra due versioni.
• Esportazione: "Copia per BridgePedia" (riga shape_constraints), JSON, link con seed.
• Modelli dalle convenzioni del wiki e dalle ricette (Progetto:BridgeShape Ricette DSL).

3. Laboratorio di test: capire come vengono generate le mani

Pulsante "Prova" → modale "Laboratorio" su N mani (default 1000, fino a 10.000, in background con progresso, seed fisso riproducibile). Output:

1. Esito del campionamento: tasso di successo, tentativi medi/p95, tempo medio/p95, mani generate/rifiutate.
2. Vincolo colpevole: per ogni vincolo la % di scarti che provoca (quale pezzo dello scenario rende lo scenario lento o raro).
3. Istogrammi per posizione (apertore/compagno/avv. sx/avv. dx): PO (0–37), lunghezza per seme, forma (classi), numero di assi/re/controlli, LTC. Con linee dei limiti richiesti, media, mediana, percentili 5/95.
4. Confronto con la base: stessi istogrammi su un mazzo non vincolato, per vedere di quanto lo scenario distorce (misura per seme: variazione rispetto al caso).
5. Frequenza onori per mano: matrice posizione × carta (A K Q J T) con % di presenza, per scoprire concentrazioni (es. "ogni volta l'avversario sx ha l'Asso di ♦").
6. Coppia: istogramma PO della coppia, distribuzione dei fit (lunghezza d'atout combinata), spaccature degli atout dei difensori (3-2, 4-1, 5-0).
7. Test di equità: verifica che il campionamento sia uniforme sullo spazio dei vincoli (confronto tra due seed e tra metodo a rifiuto e costruttivo; chi² sulle frequenze di carte/posizioni). Segnala bias (es. carte basse sempre nella stessa mano).
8. Se disponibile il solver: percentuale di mani in cui il contratto dichiarato si realizza, e distribuzione delle prese; elenco delle mani contro-esempio apribili con un clic.
9. Galleria: le prime 10 mani, un clic per aprirne il perché (§5.4) e per "fissa e rigenera".
10. Report esportabile (JSON + testo) da inviare a BridgePedia (§8.5), così gli editor del wiki tarano i vincoli. Accettiamo un campo labReport nello scenario problematico.

4. API richieste (aggiunte a DEAL_GENERATOR_API.md)

• POST /api/deals/lab {source, dsl, scenario, n, seed, solver?: bool} → jobId; GET /api/deals/lab/{jobId} → {status, progress, success, attempts, timing, rejectBy[], histograms{}, honors{}, balance{warnings[]}, fairness{}, dd?{}}.
• POST /api/deals/check (già in §5.5) per le mani contro-esempio.
• Tag requires: lab, dd, spread, relations, soft.

5. Criteri di accettazione

1. Per ogni scenario del wiki il laboratorio parte in < 2 s e fornisce i 10 punti sopra per N=1000 entro 30 s.
2. Gli avvisi di sbilanciamento segnalano E2 di "Gioco di eliminazione" (24/5 PO) prima della generazione.
3. Due esecuzioni con stesso seed danno identici istogrammi.
4. Test di equità: nessuno scarto > 3σ rispetto all'attesa sui vincoli non esplicitati.

---

Vedi anche

• Progetto:BridgeShape Motore e frontend
• Progetto:BridgeShape API
• Progetto:BridgeShape Ricette DSL
• Gioco di eliminazione

Fonti

• Esperienza di scrittura degli scenari di Gioco di eliminazione (ProgettoBridge, Lezione 18) e specifica interna BridgeShape