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. 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.

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:

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, repository BIRD, licenza Spider2 e download Spider2-Lite.

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.

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.
• Dataset card BIRD.
• Spider 2.0-Lite: download e formati.
• Ricerca sui candidati e sulle Evidence.
• Contratto workspace/Evidence, modulo Evidence, glossario, ADR 0001 — Metadata Catalog, ADR 0003 — binding locali.