ThothII/docs/plans/2026-09-27-example-databases-prd.md

# PRD — Database di esempio per ThothII

Data: 2026-09-27. Stato: requisiti D1–D8 approvati tramite `grill-with-docs`;
implementazione rinviata su richiesta dell'utente; non iniziata.
Branch di progettazione: `codex/benchmark-examples`.

Il branch conserva la progettazione per una ripresa successiva. La definizione
della procedura di installazione prosegue separatamente su
`codex/guided-standalone-install`; non deve presumere che la CLI o i database di
esempio descritti qui siano già disponibili.

Questo PRD raccoglie i requisiti correnti e sostituisce, in caso di divergenza,
le proposte nella [nota esplorativa](2026-09-27-benchmark-examples.md).
Gli aspetti tecnici da verificare prima del rilascio sono distinti dalle decisioni
di prodotto approvate e non attestano funzionalità già implementate.

## Problema e risultato desiderato

Chi installa ThothII deve poter scegliere e caricare uno, due o tre database di
esempio, ottenendo dati reali, schema commentato, Evidence disponibili e un documento
di domande per esercitarsi. Il percorso deve funzionare anche dopo l'installazione,
senza obbligare a reinstallare ThothII o a conoscere la sua architettura interna.

La distribuzione avviene dal repository dei workspace: oltre alle definizioni dei
workspace, il repository ospita una cartella `examples/` con la CLI e quanto serve
a scaricare e predisporre gli esempi su richiesta. Il normale aggiornamento del
repository non deve eseguire importazioni.

Il repository pubblico ThothII su `git.tylconsulting.it` deve rimandare al repository
pubblico dedicato agli esempi, ospitato su Gitea e gestito da TYL Consulting.
L'URL esatto di destinazione resta da definire; non si presume che debba coincidere
con l'istanza Gitea del repository ThothII. README e documentazione di installazione
devono rendere reperibili CLI, workspace e istruzioni dal repository principale.

ThothII ha un processo human in the loop. Le domande sono spunti didattici, senza
risposte SQL da riprodurre, punteggi, classifiche o confronto automatico col benchmark.

## Requisiti confermati

| ID | Requisito |
| --- | --- |
| R1 | Tre esempi: BIRD Financial, BIRD European Football, Spider 2.0-Lite F1. |
| R2 | Selezione di uno, due o tutti e tre; gli esempi sono facoltativi. |
| R3 | Caricare dati e schema PostgreSQL, inclusi commenti di tabelle e colonne. |
| R4 | Accompagnare ogni esempio con le Evidence disponibili e la loro provenienza, curate prima del rilascio e indicizzate durante il caricamento. |
| R5 | Fornire le domande disponibili in un documento leggibile per esercitarsi. |
| R6 | Escludere gli SQL target dei benchmark dal prodotto distribuito agli utenti. |
| R7 | Verificare esplicitamente la conversione dei tipi e dei valori verso PostgreSQL. |
| R8 | Distribuire una CLI attraverso il repository dei workspace, nella cartella degli esempi. |
| R9 | Consentire il caricamento tramite CLI autonoma dopo l'installazione e richiamare la stessa procedura come ultimo passo facoltativo del setup. |
| R10 | Collaudare Windows, poi Omarchy, infine macOS, in tre passaggi separati. |
| R11 | Distribuire pacchetti PostgreSQL già convertiti e verificati, con ricetta di conversione riproducibile. Valutare conversione locale solo per fonti non redistribuibili. |
| R12 | Concludere con workspace subito utilizzabili: dati, commenti, Evidence curate, metadati sincronizzati e indicizzazione completata. |
| R13 | La procedura deve prevedere una copia indipendente del repository degli esempi, senza memoria Git dell'originale, oppure uno scaricamento con accesso al repository pubblico in sola lettura. Workspace ed Evidence locali restano modificabili; nessuna credenziale o operazione di scrittura verso l'originale. |

DDL, comandi di importazione e controlli tecnici SQL fanno parte del caricatore;
R6 riguarda le soluzioni alle domande dei benchmark.

## Perimetro dei tre esempi

| Esempio | Percorso didattico | Materiale semantico disponibile |
| --- | --- | --- |
| Financial | Iniziale | Descrizioni BIRD, codifiche, annotazioni Evidence associate ai quesiti. |
| European Football | Intermedio | Descrizioni BIRD, significato degli indicatori e annotazioni Evidence. |
| F1 | Avanzato | Metadati Spider 2.0-Lite e documenti di dominio, fra cui sorpassi e tipi di giro. |

Questa progressione è didattica, non una misura delle prestazioni di ThothII.
La maggiore complessità di F1 non implica una copertura semantica completa:
le lacune vanno dichiarate nel materiale di accompagnamento.

Le fonti sono SQLite e documentazione separata. I CSV BIRD delle descrizioni non
sono i dati delle tabelle. La dimensione PostgreSQL, inclusi indici e spazio
temporaneo di caricamento, deve essere misurata durante la preparazione; non si
deduce dalla sola dimensione SQLite. Le misure sorgente sono nella
[ricerca sulle dimensioni](../research/2026-09-27-example-database-sizes.md).

## Architettura di riferimento

ThothII include già il servizio PostgreSQL `catalog-db`; il database applicativo
è `thothii_catalog`. Il progetto propone di usare la stessa istanza per tre database
di esempio distinti, senza mescolare le loro tabelle con quelle applicative.

Il contratto corrente associa un database a un workspace: il pacchetto contiene
quindi tre workspace, ciascuno con il proprio database e un singolo schema
applicativo. Non è previsto un cambiamento verso workspace multi-database.

La CLI di importazione usa credenziali di caricamento separate dalle credenziali
in sola lettura con cui ThothII interroga gli esempi. Non riutilizza il ruolo runtime
del Metadata Catalog per creare o caricare database. I segreti restano locali,
fuori dal repository, dai manifest pubblici e dai log.

Il PostgreSQL interno non richiede l'esposizione di una porta sull'host: il
caricatore deve poter operare nella rete dello stack. Una connessione a un server
PostgreSQL alternativo è un'eventuale estensione, non un requisito iniziale.

## Distribuzione e contenuti

Struttura illustrativa, da adattare alle convenzioni del repository prescelto:

```text
thoth-workspaces.yaml
examples/
  README.md
  cli/
  manifests/
    financial.yaml
    european-football.yaml
    f1.yaml
  docs/
    financial-practice.md
    european-football-practice.md
    f1-practice.md
example-financial/
  workspace.yaml
  evidence/
    source/
    curated/
example-football/...
example-f1/...
```

La Source Evidence rimane nel percorso canonico `<workspace-id>/evidence`;
il documento di esercitazione è esterno al corpus delle Evidence. Il solo fatto
di trovarsi nel repository non deve rendere le domande regole di dominio ricercabili.

**Adeguamento necessario in ThothII:** il lettore attuale considera workspace tutte
le directory alla radice, eccetto `workspace-docs`, e ne verifica la corrispondenza
con il catalogo. Una nuova `examples/` non è quindi accettata automaticamente.
Il sottoprogetto deve estendere esplicitamente questo contratto per riconoscerla
come directory ausiliaria, preservando la validazione dei veri workspace;
non deve registrarla come workspace fittizio. Riferimenti:
`backend/src/workspaces/git-repository.ts:212` e
`backend/src/workspaces/registry.ts:515`.

Nel repository Git risiedono CLI, manifest, documentazione e definizioni dei
workspace. Gli archivi voluminosi dei dati sono scaricati su richiesta da URL
versionati, con checksum, cache e attribuzioni. Il luogo di pubblicazione dei
pacchetti derivati dipende dalla decisione sulla modalità di conversione e dai
diritti di redistribuzione delle singole fonti: la licenza del codice di un
benchmark non prova da sola la licenza di tutti i dati inclusi.

Ogni manifest identifica almeno: esempio e workspace, versione del pacchetto,
revisioni e URL delle fonti, file da estrarre, checksum, licenze/attribuzioni,
versione della conversione, compatibilità PostgreSQL/ThothII, inventario degli
artefatti e risultati attesi dei controlli. Versioni e nomi non sono ricavati
silenziosamente da un riferimento mobile come `main`.

La verifica delle fonti del 2026-09-27 ha rilevato CC BY-SA 4.0 nella dataset card
BIRD e MIT per software/documentazione nel repository Spider2. Questo non chiarisce
da solo la redistribuibilità di ciascun database fornito negli archivi esterni:
per i tre dump PostgreSQL lo stato è ancora da verificare, non un divieto accertato.
Registrare licenza dichiarata, fonte e stato della verifica separatamente per dati,
descrizioni, Evidence, domande e codice. La verifica sulla versione esatta è una
condizione di pubblicazione dei pacchetti; la conversione locale rimane l'eccezione
prevista da D2. Fonti: [card BIRD](https://huggingface.co/datasets/birdsql/bird_mini_dev),
[repository BIRD](https://github.com/bird-bench/mini_dev),
[licenza Spider2](https://github.com/xlang-ai/Spider2/blob/main/LICENSE) e
[download Spider2-Lite](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/README.md).

## Schema commentato e conversione

Per ogni database si prepara un contratto di conversione per tabella e colonna,
fondato sull'ispezione sia dello schema sia dei valori effettivi. Non basta
tradurre il tipo dichiarato da SQLite, che può contenere valori eterogenei.

| Area | Regola di accettazione |
| --- | --- |
| Interi e identificatori | Range compatibili, nessun overflow; i codici con zeri iniziali restano codici. |
| Decimali e floating point | Precisione e scala dichiarate; nessun arrotondamento silenzioso. |
| Date e orari | Formato, granularità e timezone documentati; non inventare una timezone. |
| Durate | Non confonderle con orari del giorno; rappresentazione e unità esplicite. |
| Booleani e categorie | Conversione solo con codifiche verificate; distinguere sconosciuto e falso. |
| Null e testo | Distinguere NULL, stringa vuota e sentinelle; preservare Unicode, virgole e newline. |
| Colonne senza tipo o miste | Profilazione completa e decisione esplicita; errore comprensibile se non conformi. |
| Identificatori SQL | Mapping stabile e quoting coerente per maiuscole, parole riservate e caratteri speciali. |
| PK, FK e indici | Separare vincoli presenti, relazioni documentate e relazioni inferite; verificare prima di imporre. |
| Contenuti strutturati | Conservare il significato di XML/JSON/testi complessi senza trasformazioni non documentate. |

Ogni cambiamento rispetto alla sorgente compare in un rapporto di conversione.
Per casi anomali non sono ammessi scarto di righe o sostituzione con NULL senza
una regola esplicita e verificata. I controlli confrontano conteggi e valori
normalizzati per tabella; un solo confronto dei conteggi non basta.

Le descrizioni disponibili diventano veri `COMMENT ON TABLE` e
`COMMENT ON COLUMN` nel database PostgreSQL, mantenendo provenienza e segnalando
le descrizioni mancanti. Eventuali integrazioni redazionali sono distinte dalle
descrizioni originali. Questi commenti devono essere visibili anche nel Metadata
Catalog usato da ThothII; la sola presenza dei commenti in PostgreSQL non soddisfa
il requisito se la sincronizzazione del Catalog li ignora.

Il percorso esiste già: `backend/src/catalog/schema-introspector.ts:84` e `:106`
leggono `pg_description`; `metadata-snapshot.ts:52` applica la precedenza
descrizione curata, descrizione generata, commento sorgente. Il collaudo deve
considerare questa precedenza: non cancellare una descrizione curata per far
apparire un commento importato.

## Evidence e documento di esercitazione

Le fonti documentali e le annotazioni Evidence sono raccolte senza introdurre
regole inventate. Un'annotazione specifica di una domanda conserva il contesto
necessario: non diventa automaticamente una regola valida per tutto il database.
Duplicati e conflitti vengono riconciliati conservando i riferimenti originali.

L'archivio distingue Source Evidence e Curated Evidence nel formato supportato
da ThothII. La curation avviene prima del rilascio: il pacchetto contiene le fonti
e le unità curate, con riferimenti verificabili e lacune dichiarate. I file originali
non vengono presentati come Evidence già revisionate. Qdrant contiene la proiezione
ricercabile, non sostituisce l'archivio delle Evidence. L'utente finale può modificare
e arricchire la curation, ma non deve completarla per iniziare a usare l'esempio.

Il documento di esercitazione contiene domande disponibili, fonte e identificativo,
raggruppamento tematico, eventuali note sui limiti dei dati e riferimenti utili.
Non contiene soluzioni SQL né risposte attese per il confronto automatico.
Se necessario, si adattano i riferimenti ai nomi PostgreSQL, rendendo riconoscibile
la modifica. Guide, domande e contenuti semantici curati sono disponibili in italiano
e inglese, conservando gli originali e rendendo riconoscibili le traduzioni;
gli identificatori SQL restano invariati. Le rappresentazioni linguistiche di una
stessa Evidence non devono duplicarne il risultato nella ricerca.

Gli archivi originali possono includere SQL target. L'estrazione per il prodotto
ammette solo i campi necessari a schema, documentazione, Evidence e domande;
gli SQL target non entrano nei workspace, negli indici o nei documenti didattici.

## Comportamento della CLI

L'interfaccia esatta sarà definita dopo le decisioni di questo PRD. Le capacità
richieste sono: elencare gli esempi e i prerequisiti, scegliere un sottoinsieme,
scaricare/verificare, caricare, collegare i workspace e mostrare lo stato per esempio.

1. Individuare l'installazione e verificare compatibilità, servizi e spazio.
2. Risolvere i manifest e mostrare cosa verrà caricato per gli esempi scelti.
3. Scaricare solo i pacchetti necessari; riutilizzare gli archivi condivisi in cache.
4. Verificare ed estrarre il pacchetto PostgreSQL già convertito; l'eventuale
   conversione locale eccezionale deve essere dichiarata dal manifest.
5. Caricare in un database di preparazione e verificarne dati, tipi, vincoli e commenti.
6. Rendere disponibile il database verificato e registrare il binding nel Catalog.
7. Sincronizzare metadati, importare le Evidence già curate ed eseguire
   consolidamento/preprocessing per rendere il workspace subito utilizzabile.
8. Fornire un riepilogo per esempio, il documento con le domande e il prossimo passo.

Lo stato deve distinguere almeno dati caricati, metadati sincronizzati, Evidence
disponibili, indicizzazione completata e workspace pronto. Un download concluso
non equivale a un esempio utilizzabile. Se gli esempi hanno esiti diversi, il
riepilogo deve mostrare successi e fallimenti separatamente.

La riesecuzione della stessa versione non duplica dati e non sovrascrive le
Evidence modificate dall'utente. Un errore non sostituisce un database funzionante;
lo stato permette di riprendere dalle fasi completate. Il preprocessing corrente
non è internamente resumable: in caso di errore quella fase viene rieseguita.
Aggiornamento di versione, ripristino e rimozione distruttiva richiedono operazioni
esplicite distinte dalla normale installazione e sono esclusi dalla prima versione
della CLI, che comprende elenco/selezione, installazione, verifica e ripresa dopo errore.

L'integrazione deve usare le API esistenti per creazione del database nel Catalog,
binding e secret store (`backend/src/routes/catalog-databases.ts`), con
autenticazione e permessi appropriati. La sincronizzazione dello schema è un
run distinto, con conferma esplicita (`backend/src/routes/catalog-schema.ts:189`
e `:223`): il progetto deve definire come presentare o gestire quella conferma
senza aggirarne il contratto. `workspace preprocess run` ed Evidence consolidate
sono già disponibili come CLI, ma non creano binding o credenziali per conto del
caricatore. Si veda [il contratto preprocessing](../contracts/workspace-preprocessing-cli.md).

## Collaudo e condizioni di completamento

- Ogni esempio ha un inventario verificato di schema, dati, commenti, Evidence e domande.
- Il repository con `examples/` supera la validazione e mantiene i controlli
  sulle directory dei workspace; nessun file della CLI viene eseguito dal pull.
- Tutte le sette selezioni non vuote producono esclusivamente gli esempi scelti.
- La selezione di nessun esempio non ostacola l'installazione di ThothII.
- Si verificano conversione dei valori, vincoli, commenti e propagazione al Catalog.
- Il ruolo di interrogazione può leggere i dati e non può modificarli.
- Interruzione del download, checksum errato, errore d'importazione e spazio
  insufficiente producono uno stato recuperabile e non danneggiano esempi esistenti.
- Ripetere un'installazione completata non altera dati né curation locale.
- La copia indipendente non contiene storia Git o relazione di fork dell'originale,
  né remote verso di esso; mantiene versione, checksum, licenze e attribuzioni.
- Il percorso di download non richiede credenziali di scrittura verso il repository
  pubblico e non esegue push. In entrambe le modalità l'utente può modificare
  workspace ed Evidence locali e continuare a usarli dopo il riavvio.
- Una sessione reale può interrogare ciascun esempio, con Evidence reperibili;
  non è richiesto riprodurre l'SQL di un benchmark.
- Ogni workspace risulta subito utilizzabile anche dopo riavvio; le Evidence
  curate sono effettivamente reperibili e non solo presenti sul filesystem.
- Primo rilascio verificato su Windows/WSL2 e Docker Desktop; secondo su Omarchy;
  terzo su macOS. Nessuna dichiarazione di supporto a una tappa non ancora verificata.

La proposta è eseguire conversione/caricamento in container, senza introdurre
Python o Node obbligatori sull'host dell'utente. Il metodo di avvio/download della
CLI resta da precisare in base alla scelta dei pacchetti.

## Decisioni approvate con grill-with-docs

Approvazione dell'utente del 2026-09-27: «ok a tutto», riferita a D1, D2 e D3.
Nel round successivo l'utente approva D4 con precisazione della distribuzione Gitea,
D5 e D7. Dopo il chiarimento approva anche D6, ribadendo che chi installa deve
trovare tutto pronto, e aggiunge D8 sulla copia autonoma o sul download in sola lettura.

| ID | Decisione | Esito approvato |
| --- | --- | --- |
| D1 | Quando proporre il caricamento? | CLI autonoma dopo il setup, richiamabile anche come ultimo passo facoltativo dello stesso setup. |
| D2 | Dove convertire le sorgenti verso PostgreSQL? | Preparare e verificare pacchetti PostgreSQL versionati nella fase di rilascio; la CLI dell'utente scarica e carica. Conservare la ricetta di conversione riproducibile. Se una fonte non è redistribuibile, valutarne la conversione locale. |
| D3 | Quanto deve essere pronto l'esempio dopo il caricamento? | Dati, commenti e Evidence curate in anticipo, già sincronizzate e indicizzate, per consentire subito una sessione; curation successiva resta disponibile all'utente. |
| D4 | Repository di distribuzione | Il repository pubblico ThothII su git.tylconsulting.it rimanda a un repository pubblico dedicato agli esempi su Gitea gestito da TYL Consulting. Per installazioni con un repository proprio, il curatore integra i contenuti degli esempi in quel repository. Nessun nuovo supporto multi-repository in questo sottoprogetto. |
| D5 | Lingua dei contenuti | Guide, domande e contenuti semantici curati in italiano e inglese; originali conservati, traduzioni riconoscibili e identificatori SQL invariati. Nessuna duplicazione della stessa Evidence nella ricerca. |
| D6 | Preparazione e verifica delle Evidence | Il progetto prepara e controlla i contenuti; all'utente vengono sottoposte solo ambiguità o conflitti non risolvibili dalle fonti, con una proposta concreta. Chi installa riceve tutto pronto e non deve revisionare le Evidence per iniziare. |
| D7 | Prima versione della CLI | Elenco/selezione, installazione, verifica e ripresa dopo errore. Aggiornamento di versione, reset e disinstallazione rimandati; nessuna sostituzione automatica di esempi modificati. |
| D8 | Copia autonoma e sola lettura | Copia indipendente senza storia/remote/relazione di fork dell'originale, oppure scaricamento dal repository pubblico in sola lettura. Il limite riguarda la scrittura sul repository originale: workspace ed Evidence locali rimangono modificabili. Versioni, licenze e attribuzioni sono conservate. |

La risposta «1» dell'utente conferma per D8 la sola lettura remota e la modificabilità locale.
Nome e URL del repository destinazione saranno definiti prima della pubblicazione.
Interfaccia CLI, autenticazione e custodia dei segreti saranno definite nella
specifica tecnica coerentemente con i contratti esistenti. Le verifiche tecniche
e dei diritti sulle fonti sono lavoro del progetto e non domande demandate all'utente.

## Contesto del secondo round e chiarimento D6

La verifica locale ha individuato il repository PSD privato, mentre i template
generici riportano un URL esemplificativo. Non è stato individuato un repository
concreto già destinato agli esempi. L'installazione supporta una sola sorgente Git:
la scelta di un repository per gli esempi non deve sostituire implicitamente il
repository già configurato in un'installazione esistente.

D6 riguarda la verifica del significato delle Evidence adattate dalle fonti:
per esempio, un'annotazione riferita a una singola domanda non può diventare una
regola generale senza supporto documentale. Non riguarda la scrittura da zero delle
Evidence da parte dell'utente o una revisione a ogni installazione.

Chiarimento approvato per D6: il progetto prepara i contenuti, ne
controlla provenienza, coerenza e adattamento a PostgreSQL; all'utente vengono
sottoposte solo ambiguità o conflitti non risolvibili dalle fonti, con una proposta
concreta. I punti irrisolti restano segnalati ed esclusi dalle regole pubblicate
come verificate. L'utilizzatore finale riceve il materiale già curato.

## D8 — Copia del repository e permessi

Richiesta dell'utente: «fork del repository senza memoria dell'originale, o lo
scarico in locale ma senza diritti di scrittura». Il risultato deve restare pronto
all'uso e non richiedere un lavoro di curation a chi installa.

La proposta tecnica per la copia indipendente è estrarre un rilascio verificato
senza la directory `.git` originaria; se il runtime richiede Git, inizializzare
una nuova storia locale, senza remote verso l'originale né associazione di fork
sulla piattaforma. Un fork ordinario che conserva storia e relazione col repository
originario non soddisfa questo significato di indipendenza. L'eventuale pubblicazione
in un repository personale è un'operazione separata, non implicita nell'installazione.

Versione del pacchetto, checksum, licenze e attribuzioni rimangono nel manifest e
nella documentazione: l'assenza di memoria Git non elimina la provenienza dei dati
e delle Evidence. Nessun aggiornamento automatico deve sovrascrivere una copia
personalizzata.

Per il percorso di download, la scelta approvata è accesso anonimo in sola
lettura al repository pubblico, senza credenziali di scrittura e senza operazioni
di push. File e archivio locale delle Evidence restano modificabili dall'utente.
Il filesystem locale non è reso globalmente in sola lettura.

**Adeguamento necessario nel runtime:** la copia senza `.git` non è oggi una sorgente
completa per ThothII. Il lettore richiede `HEAD` e file committati
(`backend/src/workspaces/git-repository.ts:198`); il refresh esegue fetch del branch
da `origin` e rifiuta checkout sporchi o divergenze (`:467–485`). Il solo `git init`
senza remote non completa quindi il percorso corrente.

La specifica deve prevedere una sorgente locale autonoma, oppure una nuova copia
Git locale usata come sorgente del checkout gestito: eventuali riferimenti Git
interni all'installazione non devono puntare al repository pubblico originale.
Il backend già accetta percorsi Git locali assoluti/file URL (`:60–64`), ma setup,
configurazione e aggiornamento devono supportare coerentemente il percorso scelto.
Le due modalità devono funzionare senza chiedere all'utente di configurare Git.

Il download HTTPS anonimo è compatibile con il consumo remoto del backend; va
verificato anche nel bootstrap dell'installazione. Il checkout gestito non è la
cartella da sporcare con modifiche manuali: la procedura deve rendere esplicita una
copia locale modificabile dei workspace e gestirne l'attivazione senza push verso
l'originale. L'archivio locale delle Evidence è già separato e modificabile.
Riferimenti: `docs/contracts/workspace-evidence-v3.md:218` e il contratto delle
Evidence curate. I controlli di integrità del checkout non vanno disabilitati per
ottenere la modificabilità richiesta.

## Passaggio alla specifica tecnica

La definizione dei requisiti è conclusa con D1–D8. La specifica dovrà tradurli in
questi blocchi verificabili, prima dell'implementazione:

1. Contratto del repository: cartella `examples/`, distribuzione pubblica e copia
   autonoma o accesso remoto in sola lettura, con personalizzazioni locali persistenti.
2. Preparazione dei tre pacchetti: fonti e diritti verificati, conversione di
   schema/dati/tipi, commenti, Evidence curate e materiale didattico bilingue.
3. CLI: download, verifica, importazione isolata, binding, sincronizzazione e
   indicizzazione, stato e ripresa dopo errore, senza push verso l'originale.
4. Integrazione facoltativa nel setup, collegamenti fra repository e documentazione.
5. Collaudo Windows, successivamente Omarchy, infine macOS.

## Riferimenti

- [BIRD mini-dev: dati e documentazione](https://github.com/bird-bench/mini_dev).
- [Dataset card BIRD](https://huggingface.co/datasets/birdsql/bird_mini_dev).
- [Spider 2.0-Lite: download e formati](https://github.com/xlang-ai/Spider2/tree/main/spider2-lite).
- [Ricerca sui candidati e sulle Evidence](../research/2026-09-27-spider2-lite-evidence-candidates.md).
- [Contratto workspace/Evidence](../contracts/workspace-evidence-v3.md),
  [modulo Evidence](../evidence.md), [glossario](../../CONTEXT.md),
  [ADR 0001 — Metadata Catalog](../adr/0001-postgres-metadata-catalog.md),
  [ADR 0003 — binding locali](../adr/0003-installation-local-database-bindings.md).