docs: define example database subproject and defer implementation

docs/plans/2026-09-27-benchmark-examples.md

@@ -0,0 +1,175 @@
+# Tre esempi locali per l'installazione guidata
+
+Stato: nota esplorativa conservata; requisiti definiti nel PRD e implementazione
+rinviata su richiesta dell'utente.
+Requisiti correnti e decisioni aperte sono ora raccolti nel
+[PRD dei database di esempio](2026-09-27-example-databases-prd.md), che prevale
+su questa nota esplorativa in caso di divergenza.
+Branch: `codex/benchmark-examples`, derivato da `codex/guided-standalone-install`
+al commit `67ee5262`. Collegamento al progetto installazione:
+`docs/plans/2026-09-27-guided-installation-resumption.md` sul branch di origine.
+
+## Requisiti dell'utente
+
+- Tre database pubblicamente scaricabili da BIRD o altro benchmark, con evidence.
+- Tre livelli di complessità crescente; preferenza per dati in CSV.
+- Esempi da implementare in locale.
+- Caricamento opzionale tramite CLI dal repository dei workspace: selezione di
+  uno, due o tutti e tre i database, dopo il setup; integrazione nel setup da valutare.
+- Dati, schema PostgreSQL commentato ed Evidence disponibili per ogni esempio.
+- Domande in un documento di accompagnamento per esercitarsi, senza SQL target.
+- Collaudo in tre tappe: Windows, Linux Omarchy, macOS.
+
+### Criterio chiarito dall'utente
+
+ThothII viene usato con human in the loop: questo progetto non serve a misurarlo
+contro un benchmark. I benchmark sono soltanto fonti di database e documentazione.
+Numero di domande, gold SQL, percentuali di correttezza e copertura delle annotazioni
+per domanda non sono criteri di selezione o di accettazione.
+Le domande sono invece utili come materiale didattico: il prodotto le include in
+un documento separato dalle Evidence, senza soluzioni SQL o valutazione automatica.
+
+Si cercano complessità relazionale e semantica e documentazione sostanziale da
+curare come Source Evidence: significati, regole aziendali, formule, codifiche,
+granularità e relazioni. Documenti non collegati ai quesiti del benchmark contano
+quanto quelli collegati. DDL, righe di esempio e numero di file da soli non
+dimostrano una buona documentazione di dominio. Dopo il confronto delle alternative,
+il trio per cui l'utente richiede ora la procedura è Financial, European Football e F1.
+
+## Dataset proposti
+
+California Schools è escluso per richiesta dell'utente. European Football è richiesto;
+l'utente ha inoltre chiesto di valutare Spider 2.0 e la disponibilità di evidence.
+La proposta corrente comprende Financial e European Football da BIRD e F1 da
+Spider 2.0-Lite. Shopify, QuickBooks e Workday restano alternative documentate.
+I livelli sono una progressione didattica proposta per ThothII.
+
+| Livello | Database | Motivo | Fonti per le Evidence |
+| --- | --- | --- | --- |
+| Primo percorso | BIRD `financial` | Conti, clienti, prestiti e movimenti | Codifiche di dominio e regole nelle annotazioni BIRD |
+| Intermedio | BIRD `european_football_2` | Campionati, squadre, giocatori e partite | Stagioni, significato degli indicatori e aggregazioni nelle annotazioni BIRD |
+| Avanzato | Spider 2.0-Lite `f1` | Stagioni, gare, piloti, giri, pit stop e cambi di posizione; 29 tabelle dichiarate | Documenti di dominio sui sorpassi e sui tipi di giro, da curare e integrare dove insufficienti |
+
+Revisione Hugging Face BIRD osservata:
+`f65faf4ae3b638c1fa6df1d3370c8d92c8366301`.
+
+Le evidence BIRD comprendono spiegazioni di codici, significati di colonne e regole di
+calcolo. Sono annotazioni legate alle domande; richiedono adattamento e revisione
+per diventare Source Evidence di ThothII. Non sono già un archivio ThothII pronto.
+
+Le definizioni dbt sono fonti da curare, non Evidence Unit già importate in ThothII.
+Non contare ogni descrizione di colonna come un'evidence distinta. I file tecnici
+delle librerie dbt non rientrano nel materiale semantico del database.
+Revisione Spider2 osservata: `cafb867313aab4e674652054198f383cf4018943`.
+
+Le ricerche motivate e le alternative sono in
+`docs/research/2026-09-27-spider2-lite-evidence-candidates.md` e
+`docs/research/2026-09-27-spider2-dbt-evidence-candidates.md`.
+
+## Fonti e formati
+
+- [Dataset ufficiale e licenza dichiarata CC BY-SA 4.0](https://huggingface.co/datasets/birdsql/bird_mini_dev).
+- [Domande PostgreSQL, evidence e SQL di riferimento](https://huggingface.co/datasets/birdsql/bird_mini_dev/blob/f65faf4ae3b638c1fa6df1d3370c8d92c8366301/data/mini_dev_pg-00000-of-00001.json).
+- [Istruzioni ufficiali e pacchetto database](https://github.com/bird-bench/mini_dev).
+- [Pacchetto completo indicato dalla dataset card](https://drive.google.com/file/d/13VLWIwpw5E3d5DUkMvzw7hvHE67a4XkG/view?usp=sharing).
+- [Archivio ZIP collegato dal repository ufficiale](https://bird-bench.oss-cn-beijing.aliyuncs.com/minidev.zip):
+  risposta HEAD 200, 800943648 byte al controllo; contenuto non ancora scaricato né
+  confrontato con il pacchetto aggiornato della dataset card.
+
+I CSV `database_description` descrivono schema e valori, non contengono le righe
+delle tabelle. I dati sono forniti come database SQLite e materiale per PostgreSQL/
+MySQL. Proposta: mantenere PostgreSQL come destinazione locale e, se utile, produrre
+CSV riproducibili insieme a DDL, tipi e vincoli. Non usare CSV senza schema come
+unica rappresentazione del database. Conservare provenienza, versione, attribuzione
+e licenza con gli artefatti derivati.
+
+Fonti Spider 2.0-Lite per F1:
+
+- [Istruzioni per scaricare i database SQLite locali](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/README.md).
+- [Schema e metadati F1](https://github.com/xlang-ai/Spider2/tree/main/spider2-lite/resource/databases/sqlite/f1).
+- [Classificazione dei sorpassi](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/f1_overtake.md).
+- [Tipi di giro](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/lap_type.md).
+
+I tre database sorgente sono SQLite. Esportazione CSV e caricamento PostgreSQL
+dovranno preservare tipi, relazioni, granularità e contenuto dei dati selezionati.
+I file sono stati individuati negli archivi; i dati completi non sono stati scaricati
+né convertiti durante la progettazione.
+
+## Proposta di download e caricamento PostgreSQL
+
+Questa sezione risponde alla richiesta di fattibilità e non autorizza né attesta
+un'implementazione già eseguita.
+
+### Destinazione
+
+Il Compose include `catalog-db`, PostgreSQL 17.6, con volume `catalog-data` e database
+`thothii_catalog`. Quest'ultimo ospita le informazioni applicative del Catalog e
+la persistenza Memory. Proposta per le installazioni dimostrative: riutilizzare lo
+stesso servizio PostgreSQL, creando tre database separati, con nomi da finalizzare:
+`example_financial`, `example_football`, `example_f1`. Ogni database avrà un solo
+schema applicativo, un workspace associato e un ruolo di interrogazione in sola
+lettura. L'importazione userà un ruolo distinto con permessi di scrittura.
+
+La creazione degli esempi deve essere una manutenzione esplicita rieseguibile, non
+un'aggiunta affidata unicamente agli script di inizializzazione del volume PostgreSQL.
+Le migrazioni Catalog e i suoi ruoli runtime rimangono separati dal caricatore.
+La condivisione del servizio implica condivisione di risorse, volume e gestione
+backup; non equivale a isolamento fra istanze PostgreSQL indipendenti.
+
+### Sequenza prevista
+
+1. Selezione esplicita di uno, due o tre esempi, anche dopo il primo setup.
+2. Manifest versionato per ciascun esempio: URL ufficiali, revisione/checksum,
+   file nell'archivio, fonti documentali, licenze e versione della conversione.
+   Cache dei pacchetti comuni per evitare download duplicati.
+3. Download ed estrazione dei SQLite e della documentazione. BIRD: descrizioni CSV
+   e annotazioni evidence, conservando il contesto necessario a interpretarle.
+   F1: metadati dello schema e documenti di dominio. Nessuna generazione automatica
+   di nuove regole presentate come se fossero evidence originali.
+4. Ispezione dello schema e dei dati effettivi; conversione SQLite verso DDL
+   PostgreSQL e CSV, con mapping espliciti per tipi, date, booleani, valori null,
+   identificatori e colonne prive di tipo. Rilevare PK/FK presenti e distinguere
+   relazioni documentate o proposte da quelle effettivamente vincolate nella sorgente.
+5. Caricamento in database di preparazione dedicati; creazione degli indici e
+   vincoli verificati, confronto delle righe e dei valori e controlli relazionali.
+   Un fallimento lascia l'esempio non pronto senza sostituire una versione funzionante.
+6. Pubblicazione dei database validati e registrazione dei binding nel Catalog;
+   creazione dei workspace e sincronizzazione degli schemi via servizi esistenti.
+7. Importazione separata: descrizioni nel Catalog; documenti e regole nelle Source
+   Evidence del workspace, con provenienza. Le Evidence restano artefatti del
+   modulo Evidence; la proiezione ricercabile appartiene a Qdrant.
+8. Revisione umana/consolidamento delle Evidence e delle relazioni proposte,
+   preprocessing e controlli di utilizzabilità. La disponibilità dei file scaricati
+   non equivale a un workspace pronto.
+
+Il processo conserva stato e versioni per riprendere dopo errori, evita duplicazioni
+e non sovrascrive Evidence curate o dati esistenti durante una normale riesecuzione.
+Download ed elaborazione devono usare componenti containerizzati, mantenendo il
+percorso Windows/WSL2 senza richiedere Python o Node aggiuntivi sull'host.
+
+## Decisione architetturale aperta
+
+Gli ADR 0001 e 0003 e il glossario corrente prevedono un database per workspace.
+La richiesta di un workspace con tre database richiede quindi una scelta esplicita.
+Proposta: un pacchetto/repository di esempi con tre workspace indipendenti, ognuno
+associato al proprio database. Nessuna modifica multi-database è approvata finora.
+
+## Lavoro previsto dopo la definizione
+
+1. Fissare versione e checksum dei dati, ispezionare schema, tipi, chiavi e
+   documentazione di dominio; definire percorsi dimostrativi di complessità crescente.
+2. Preparare il caricamento locale selettivo dei tre dataset, con dati e ruoli
+   distinti dal Catalog applicativo, ripresa e riesecuzione senza duplicazioni.
+3. Preparare descriptor e Source Evidence con provenienza per ogni esempio;
+   esplicitare ciò che è documentato e ciò che richiede una decisione del curatore.
+4. Registrare binding nel Catalog, sincronizzare schema e predisporre il percorso
+   di revisione/consolidamento e preprocessing dei workspace selezionati.
+5. Integrare nel setup la scelta opzionale dei dataset e mostrare per ciascuno
+   caricamento, configurazione, Evidence e stato di utilizzabilità.
+6. Verificare tutte le sette selezioni non vuote dei tre esempi, la riesecuzione e
+   gli errori di download/importazione. Collaudare una domanda reale per ciascun
+   esempio installato, poi arresto e riavvio, prima su Windows.
+
+La selezione opzionale comprende anche la possibilità di installare ThothII senza
+esempi. Nessun download massivo, caricamento database o implementazione del setup
+è stato eseguito durante questa proposta.