ThothII/docs/research/2026-08-23-legacy-thothai-metadata-capabilities.md

Inventario delle funzionalità legacy di gestione metadati di ThothAI

Data dell'inventario: 2026-08-23

Ultima verifica rispetto a ThothII: 2026-08-31

Stato: inventario storico verificato; non è una specifica dello stato corrente.

Issue originaria: mptyl/ThothII#6

Fonte primaria: repository legacy annidato Thoth/ThothAI, commit 55855de0f18e5cb4bc72f0a2ab0a7317995186dd.

Le citazioni che iniziano con /Thoth/ThothAI/ sono relative alla radice di quella copia legacy fissata al commit indicato. Alla verifica del 2026-08-31 tutti i 68 riferimenti univoci puntavano a file esistenti e a intervalli di righe validi.

Questo documento conserva l'inventario e le evidenze degli anti-pattern di ThothAI. Le frasi di requisito nelle sezioni successive descrivono la baseline proposta il 2026-08-23; non prevalgono su ADR, contratti, codice o PROJECT_STATE.md correnti.

Stato rispetto al codice corrente

Fonti autorevoli correnti

Per capire cosa esiste oggi, usare nell'ordine:

• PROJECT_STATE.md, per lo snapshot operativo aggiornato;
• CONTEXT.md, per il modello di dominio corrente;
• il piano accettato del Metadata Catalog e il contratto dello schema snapshot;
• gli ADR del catalogo, in particolare 0001, 0004, 0006, 0007, 0008, 0009, 0010 e 0011;
• l'implementazione, soprattutto backend/src/catalog/types.ts, backend/src/routes/catalog-databases.ts, backend/src/routes/catalog-schema.ts, backend/src/routes/catalog-description-generation.ts, backend/src/routes/catalog-description-consolidation.ts e frontend/src/shell/DatabaseManagementPage.tsx.

Disposizione della baseline storica

Capacità inventariata	Disposizione al 2026-08-31	Evidenza corrente o nota
Configurazione per workspace, secret separati e test connessione	Adottata e implementata	PostgreSQL interno, binding postgres_direct, rest_api o ssh_tunnel, secret write-only; ADR 0001–0004 e backend/src/routes/catalog-databases.ts.
Inventario fisico di tabelle, colonne, PK e FK	Adottato e implementato	La struttura osservata è distinta dai contenuti curati; backend/src/catalog/types.ts, backend/src/routes/catalog-schema.ts e ADR 0006.
Riconciliazione completa e osservabile dello schema	Implementata; semantica storica parzialmente superata	I durable Catalog Sync Runs sono autoritativi, fail-closed, atomici e richiedono conferma per diff distruttivi. Non esiste il lifecycle drift/removed proposto qui: la sincronizzazione riconcilia la membership e ADR 0008 consente anche cleanup manuale esplicito, superando ADR-0005.
Descrizione curata e Generated Description separate	Adottata e implementata	Tabelle e colonne espongono entrambi i campi in backend/src/catalog/types.ts; la copia selettiva AI → curato è in backend/src/routes/catalog-description-consolidation.ts.
Generazione AI selettiva con run, stato e log	Adottata e implementata	Un run asincrono installazione-wide, sequenziale, con eventi persistiti e senza resume automatico; ADR 0009 e backend/src/routes/catalog-description-generation.ts. I thread daemon legacy sono esclusi.
Campioni reali per la generazione e protezione dei campi sensibili	Implementata come estensione correttiva	ADR 0010 e 0011: campioni bounded per colonne non sensibili e valori sintetici deterministici per quelle sensibili.
Proposte persistenti, diff e versioni dei testi AI	Escluse	Resta un solo Generated Description modificabile. La cronologia dei run è operativa: non conserva prompt, output grezzo, proposta per colonna o audit della decisione umana.
Relazioni fisiche	Adottate e implementate	Sono constraint immutabili con coppie ordinate di colonne; ADR 0006.
Relazioni logiche curate o inferite	Differite/aperto	ADR-0006 riserva un modello e un lifecycle separati; non sono ancora parte del catalogo corrente.
Alias semantici, descrizioni dei valori, sinonimi e concetti	Differiti/aperti	PROJECT_STATE.md li assegna a slice dedicate; non vanno dedotti dai campi fisici già implementati.
Scope AI, ERD Mermaid e documentazione aggregata	Differiti/aperti	Restano capacità legacy inventariate, non una feature corrente del Metadata Catalog. Un eventuale lavoro dovrà avere contratto e gate propri.
Export CSV e script SQL dei commenti	Differiti/aperti; varianti insicure escluse	Non risultano nella API corrente. Export di segreti, CSV incoerenti e SQL ricostruito da tipi incompleti restano vietati dagli anti-pattern sotto.
Inferenza euristica e validazione di relazioni candidate	Differita/aperta	Non va confusa con la sincronizzazione delle FK fisiche; dipende dal futuro lifecycle delle relazioni logiche.
Pubblicazione del catalogo al core/schema-linking/Qdrant	Differita e richiesta come design gate successivo	Il runtime NL→SQL continua a usare configurazione e annotations del workspace; il cutover è esplicitamente rinviato in PROJECT_STATE.md.
Sette motori database del legacy	Baseline superata	La prima versione corrente supporta PostgreSQL; l'aggiunta di altri dialetti è una decisione futura, non parità automatica.
GDPR e import da installazioni ThothAI	Fuori dalla baseline iniziale; import differito	GDPR resta escluso. Un eventuale import richiede una iniziativa idempotente e un cutover separati, non il riuso degli ID Django.
Django Admin, modifica manuale della struttura sorgente, password nel catalogo, duplicazione opaca dei database	Esclusi	La UI e le API correnti amministrano il catalogo e non eseguono DDL sul DWH esterno; binding e segreti hanno ownership separata.

Sintesi storica

La baseline di parità proposta il 2026-08-23 comprende un catalogo dei database, l'inventario completo di tabelle, colonne e relazioni fisiche, metadati descrittivi modificabili, relazioni logiche, introspezione dello schema, generazione AI di descrizioni, scope, ERD Mermaid, documentazione ed esportazioni operative. La UI Django Admin è soltanto l'interfaccia legacy: non è un requisito architetturale da riprodurre.

Il flusso AI per le descrizioni individuato come baseline è volutamente semplice:

1. l'AI scrive nel campo generated_comment della tabella o colonna;
2. l'utente seleziona gli elementi desiderati;
3. un'azione copia il testo generato nel campo descrittivo canonico, sovrascrivendolo.

Nel codice esaminato non esiste un'azione inversa che copi la descrizione canonica in generated_comment. Le due azioni inverse presenti sulle colonne copiano invece il nome originale nel nome espanso e viceversa. Non risultano proposal, versioni, diff o workflow di approvazione: aggiungerli non sarebbe parità con ThothAI.

La parità deve essere di capacità e comportamento utile, non dei difetti del legacy. In particolare non vanno replicate esportazioni di password, SQL costruito con identificatori non quotati, job in thread daemon, incoerenze CSV e azioni admin non funzionanti.

1. Modello dati legacy

Database

SqlDb contiene:

• identità e connessione (name, host, tipo motore, nome database, porta, schema, utente e password);
• configurazione SSH e ambiente (dev, test, prod);
• lingua per database, scope testuale e JSON, ERD Mermaid, direttive e report GDPR;
• stato e log separati per generazione commenti tabella/colonna, introspezione, scope, ERD, documentazione e GDPR.

Evidenze: /Thoth/ThothAI/backend/thoth_core/models.py:298-350, /Thoth/ThothAI/backend/thoth_core/models.py:355-439.

I motori dichiarati sono sette: Informix, MariaDB, MySQL, Oracle, PostgreSQL, SQL Server e SQLite (/Thoth/ThothAI/backend/thoth_core/models.py:116-123).

Il modello Workspace collega un solo SqlDb; contiene inoltre configurazioni degli agenti e duplica parte degli stati operativi (/Thoth/ThothAI/backend/thoth_core/models.py:731-754, /Thoth/ThothAI/backend/thoth_core/models.py:847-877).

Tabelle e colonne

SqlTable contiene nome, descrizione canonica, commento generato e riferimento al database (/Thoth/ThothAI/backend/thoth_core/models.py:454-465).

SqlColumn contiene nome originale, nome espanso, formato dati normalizzato, descrizione canonica, commento generato, descrizione dei valori e indicazioni PK/FK testuali (/Thoth/ThothAI/backend/thoth_core/models.py:468-485).

La cancellazione usa le cascade Django: database → tabelle → colonne e relazioni. Nei modelli non sono definite unicità composte per database/tabella/colonna. Ogni database ha un solo campo schema; tabelle e colonne non portano una propria identità di schema. Questi limiti non devono diventare vincoli del nuovo catalogo.

Relazioni

Relationship collega tabella e colonna sorgente a tabella e colonna destinazione (/Thoth/ThothAI/backend/thoth_core/models.py:488-503). Il metodo update_pk_fk_fields ricostruisce stringhe descrittive PK/FK sulle colonne coinvolte (/Thoth/ThothAI/backend/thoth_core/models.py:505-526).

Il form admin verifica che le due tabelle appartengano allo stesso database e che ogni colonna appartenga alla tabella selezionata (/Thoth/ThothAI/backend/thoth_core/admin_models/admin_relationship.py:19-165).

Per ThothII occorre distinguere:

• struttura fisica importata dal database, da trattare come inventario non modificabile;
• descrizioni e metadati semantici, modificabili con CRUD completo;
• relazioni logiche aggiunte dall'utente, modificabili con CRUD completo.

Questa separazione conserva le capacità utili del legacy senza permettere che la UI alteri o falsifichi accidentalmente lo schema fisico osservato.

2. Capacità esposte dal Django Admin

La registrazione degli admin fornisce il CRUD Django standard per database, tabelle, colonne e relazioni (/Thoth/ThothAI/backend/thoth_core/admin.py:13-24). Oltre al CRUD, le azioni specifiche sono le seguenti.

Database

L'admin di SqlDb espone:

• export/import CSV;
• scansione delle tabelle, creazione delle relazioni e introspezione completa;
• validazione FK e inferenza di relazioni candidate;
• test della connessione;
• duplicazione della configurazione;
• generazione commenti AI per tabelle e colonne;
• generazione sincrona o asincrona di scope, ERD e documentazione;
• report GDPR;
• export della struttura e script SQL dei commenti.

Evidenza: /Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqldb.py:237-274.

I campi di configurazione, contenuto e stato sono esposti in fieldset distinti (/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqldb.py:275-462). In ThothII i segreti di connessione non devono essere campi ordinari del catalogo né essere restituiti dalle API di gestione metadati.

Tabelle

L'admin delle tabelle permette export/import CSV, introspezione colonne, validazione e pulizia PK/FK, copia del commento AI nella descrizione, generazione commenti sincrona/asincrona e download dello script SQL (/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqltable.py:133-150).

L'azione di applicazione AI opera solo sulle righe selezionate, ignora commenti generati vuoti e sovrascrive direttamente description (/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqltable.py:165-190).

Colonne

L'admin delle colonne permette export/import CSV, copia del commento AI nella descrizione, copia bidirezionale fra nome originale e nome espanso, validazione FK e generazione AI sulle colonne selezionate (/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqlcolumn.py:167-196).

L'applicazione AI sovrascrive column_description soltanto per le colonne selezionate con generated_comment valorizzato (/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqlcolumn.py:219-245). Le azioni inverse riguardano esclusivamente i due campi nome (/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqlcolumn.py:247-261).

Relazioni

L'admin delle relazioni offre il CRUD standard, filtri e ricerca, export/import e dichiara un'azione per aggiornare i campi PK/FK (/Thoth/ThothAI/backend/thoth_core/admin_models/admin_relationship.py:219-245). L'ultima azione è però un difetto: RelationshipAdmin non implementa il metodo dichiarato; esiste soltanto il metodo statico sul model. La capacità da conservare è la ricostruzione coerente degli indicatori, non l'azione admin rotta.

3. Introspezione e riconciliazione dello schema

Il factory del database manager associa i sette motori ai rispettivi adapter e gestisce anche il tunnel SSH (/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:77-227).

L'introspezione legacy:

• riduce i tipi nativi a un insieme generico limitato, con fallback VARCHAR (/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:237-266);
• legge e crea le colonne mancanti, ma non aggiorna tipo o commento di quelle già note (/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:269-351);
• crea le tabelle mancanti e aggiorna la descrizione di quelle esistenti (/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:431-481);
• legge le foreign key fisiche, crea al bisogno colonne mancanti e crea relazioni assenti (/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:484-641);
• esegue l'intero processo nell'ordine tabelle → colonne → relazioni (/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:718-891).

Il comportamento è additivo: gli oggetti scomparsi dal database sorgente non sono eliminati o marcati come obsoleti. Per ThothII la capacità richiesta è una scansione completa e riconciliabile, con provenienza, data dell'osservazione e stato degli oggetti rimossi o cambiati; non la semantica incompleta del refresh legacy.

L'inferenza di relazioni candidate combina convenzioni sui nomi, individuazione euristica delle PK e campionamento dei valori, con soglia di corrispondenza del 70% (/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqldb.py:605-801). Deve rimanere una proposta esplicita da convalidare, non essere confusa con una foreign key fisica.

4. Generazione AI delle descrizioni

Tabelle

La generazione procede in batch da dieci, utilizza lingua e contesto del database, schema osservato, descrizioni disponibili e fino a cinque righe di esempio; il risultato JSON aggiorna soltanto table.generated_comment (/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_table_comments.py:181-267, /Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_table_comments.py:269-482).

Colonne

La generazione usa contesto della tabella, nomi delle colonne selezionate ed esempi reali, e scrive soltanto column.generated_comment (/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_column_comments.py:185-280, /Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_column_comments.py:283-487).

Provider e modello AI provengono dalla configurazione globale del backend; la lingua è invece per database (/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/comment_generation_utils.py:156-219).

Comportamento di parità proposto il 2026-08-23

Il contratto funzionale minimo è esattamente questo:

• due campi per elemento: descrizione canonica e commento generato;
• comando AI su elementi selezionati o su un insieme più ampio esplicitamente scelto;
• scrittura/sovrascrittura del solo commento generato;
• azione separata, su selezione dell'utente, che copia il generato nel canonico;
• nessuna proposta persistente aggiuntiva, diff obbligatorio, approvazione multilivello o versionamento del testo.

Non è stata trovata una copia descrizione → commento generato. Se si desiderasse in futuro, sarebbe una nuova capacità, non parità legacy.

5. Scope, Mermaid e documentazione

Scope

La generazione dello scope raccoglie nomi e descrizioni di tabelle e colonne, nome e lingua del database, richiede JSON al modello e persiste sia il JSON sia una resa Markdown. Se il JSON non è valido conserva il testo grezzo e svuota scope_json (/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_db_scope.py:25-163).

ERD Mermaid

L'ERD è prodotto dall'AI usando tabelle, colonne, PK/FK e relazioni. Il codice estrae un blocco Mermaid oppure usa la risposta grezza e la salva in SqlDb.erd, senza una validazione sintattica o semantica preventiva (/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/generate_db_erd.py:18-145).

Il rendering attivo usa un servizio Mermaid locale: health check, POST a /svg o /png, timeout e file temporanei (/Thoth/ThothAI/backend/thoth_ai_backend/mermaid_utils.py:29-72, /Thoth/ThothAI/backend/thoth_ai_backend/mermaid_utils.py:281-464). Il servizio Express espone /health, /svg e /png ed applica un limite al body (/Thoth/ThothAI/docker/mermaid-service/src/server.js:13-23, /Thoth/ThothAI/docker/mermaid-service/src/server.js:70-115). È distribuito come servizio Compose autonomo con health check (/Thoth/ThothAI/docker-compose.yml:184-201).

La vista ERD renderizza il Mermaid memorizzato in SVG tramite tale servizio e poi elimina il file temporaneo (/Thoth/ThothAI/backend/thoth_ai_backend/views.py:227-288).

Documento del database

La documentazione HTML combina scope, relazioni, tabelle e colonne. Per le descrizioni usa il campo canonico e, quando vuoto, il commento generato (/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/generate_db_documentation.py:35-188).

Il processo di generazione chiede all'AI il diagramma Mermaid, lo salva nell'ERD e costruisce deterministicamente l'HTML corrente; l'HTML generato non incorpora il diagramma (/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/generate_db_documentation.py:767-922). La UI espone il documento del database del workspace corrente e le route per HTML/PDF ed ERD/PDF (/Thoth/ThothAI/backend/thoth_ai_backend/views.py:86-179, /Thoth/ThothAI/backend/thoth_ai_backend/urls.py:179-188).

Per la parità ThothII servono quindi contenuto documentale strutturato, sorgente Mermaid persistita e rendering locale. La validazione Mermaid prima della pubblicazione è una correzione necessaria, non un cambiamento di scopo.

6. Export e comandi operativi

Le capacità utili rilevate sono:

• CSV di tabelle e colonne selezionate (/Thoth/ThothAI/backend/thoth_core/utilities/utils.py:150-195);
• export CSV generico dei modelli e della struttura completa (/Thoth/ThothAI/backend/thoth_core/utilities/utils.py:198-261, /Thoth/ThothAI/backend/thoth_core/utilities/utils.py:399-569);
• script SQL dei commenti per PostgreSQL, SQL Server, MySQL e MariaDB (/Thoth/ThothAI/backend/thoth_core/admin_utils/sql_comment_script.py:25-316);
• comandi generate_scope e generate_documentation, indirizzabili per workspace, database o tutti i database (/Thoth/ThothAI/backend/thoth_core/management/commands/generate_scope.py:12-89, /Thoth/ThothAI/backend/thoth_core/management/commands/generate_documentation.py:12-89);
• export globale e per workspace (/Thoth/ThothAI/backend/thoth_core/management/commands/export_models.py:19-64, /Thoth/ThothAI/backend/thoth_core/management/commands/export_workspace.py:19-96);
• aggiornamento delle descrizioni colonna da CSV per workspace (/Thoth/ThothAI/backend/thoth_ai_backend/management/commands/update_column_descriptions.py:24-92).

I comandi di importazione dalla produzione legacy sono deliberatamente esclusi da questo inventario di parità: costituiscono un progetto CLI tht separato, con mapping, validazione e cutover propri.

7. Esecuzioni asincrone e stato

Scope, ERD, documentazione e commenti possono essere lanciati in background. Il legacy crea thread daemon e memorizza task id, stato e log sui modelli (/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/async_scope.py:21-62, /Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/async_erd.py:21-30, /Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/async_documentation.py:21-30, /Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/async_table_comments.py:39-87).

La capacità da mantenere è: operazione lunga non bloccante, esclusione di esecuzioni confliggenti, stato osservabile e log. Il meccanismo daemon non è durevole, non permette recovery o cancellazione e non deve essere replicato letteralmente.

8. Difetti e comportamenti da non replicare

Area	Evidenza legacy	Decisione di parità
Segreti negli export	L'export struttura include password in chiaro (/Thoth/ThothAI/backend/thoth_core/utilities/utils.py:516-559); l'export generico serializza tutti i campi (/Thoth/ThothAI/backend/thoth_core/management/commands/export_models.py:19-64).	Escludere sempre credenziali e segreti.
SQL euristico	Il campionamento per inferire FK interpola identificatori senza quoting e usa query costruite come stringhe (/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqldb.py:697-750).	Usare adapter sicuri, quoting per dialetto e query read-only con limiti.
Refresh incompleto	L'introspezione aggiunge oggetti ma non riconcilia rimozioni e non aggiorna tutte le proprietà (/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:318-351, /Thoth/ThothAI/backend/thoth_core/dbmanagement.py:459-481).	Scansioni versionate e stato drift/removed.
Relazioni denormalizzate	L'aggiornamento ricostruisce stringhe PK/FK solo sulle colonne partecipanti e non ripulisce esplicitamente valori obsoleti (/Thoth/ThothAI/backend/thoth_core/models.py:505-526).	Derivare indicatori dalle relazioni correnti.
Azione relazione rotta	L'admin dichiara update_pk_fk_fields ma non lo implementa (/Thoth/ThothAI/backend/thoth_core/admin_models/admin_relationship.py:219-245).	Esporre un comando applicativo testato.
CSV colonne incoerente	L'header ha sei colonne, le righe ne emettono otto incluse PK/FK (/Thoth/ThothAI/backend/thoth_core/utilities/utils.py:165-195).	Contratto CSV versionato e testato.
Comando export rotto	export_single_model usa l'app label toth_be e un attributo non definito (/Thoth/ThothAI/backend/thoth_core/management/commands/export_single_model.py:19-67).	Non portare il comando; sostituirlo con export catalogo coerente.
Batch AI colonne	Un batch usa la prima tabella selezionata come contesto per tutte le colonne (/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_column_comments.py:230-268).	Raggruppare sempre per database e tabella.
Contesto AI tabelle	Il fallback al commento generato è calcolato ma non incluso nel dataframe finale (/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_table_comments.py:485-525).	Costruire il contesto dal valore effettivamente visibile.
Duplicazione DB	Duplica configurazione e vector DB, azzerando soltanto una data di aggiornamento (/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqldb.py:514-569).	Se mantenuta, duplicare soltanto metadati esplicitamente scelti, mai segreti o stati.
Scope non JSON	Il generatore intercetta internamente il JSON non valido, mentre l'azione può comunque mostrare successo (/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_db_scope.py:92-192).	Stato failed o needs_review, senza falso successo.
Mermaid non validato	La risposta AI viene salvata dopo la sola estrazione del blocco (/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/generate_db_erd.py:88-121).	Validare prima di pubblicare e conservare l'errore di rendering.
HTML non escapato	I valori descrittivi sono interpolati direttamente nell'HTML (/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/generate_db_documentation.py:35-188).	Escape/sanitizzazione obbligatori.
Job daemon	I task sono thread in-process (/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/async_scope.py:21-62).	Esecuzione durevole o almeno recuperabile, con idempotenza.
Script MySQL	I commenti colonna usano ALTER ... MODIFY COLUMN basandosi sul tipo normalizzato (/Thoth/ThothAI/backend/thoth_core/admin_utils/sql_comment_script.py:244-316).	Generare solo con tipo nativo completo oppure bloccare l'export rischioso.

Il modulo contiene anche un helper verso mermaid.ink, ma non risultano call site nel tree legacy; il percorso attivo è il servizio locale. Non va quindi considerata una dipendenza funzionale da conservare.

9. Baseline di parità proposta il 2026-08-23

Necessario

• database gestiti derivati dalla configurazione dei workspace;
• inventario completo del database, anche oltre il sottoinsieme usato dal workflow core;
• scansione di tabelle, colonne, chiavi e relazioni fisiche con drift osservabile;
• descrizioni canoniche e commenti AI separati per tabelle e colonne;
• generazione AI selettiva e copia selettiva AI → descrizione, senza workflow aggiuntivo;
• CRUD dei metadati semantici e delle relazioni logiche;
• scope strutturato, documento generale strutturato ed ERD Mermaid;
• servizio locale per validazione/rendering Mermaid in SVG/PNG/PDF;
• test connessione, inferenza/validazione delle relazioni e operazioni lunghe con stato/log;
• export CSV sicuro e script SQL commenti solo quando il dialetto può essere ricostruito senza perdita;
• API e UI dedicate, separate dal workflow NL→SQL;
• pubblicazione esplicita e controllata del sottoinsieme utile al core/Qdrant.

Estensione, non requisito di parità iniziale

• analisi e report GDPR;
• importazione dei dati da installazioni ThothAI in produzione, da progettare come iniziativa CLI tht separata.

Esplicitamente escluso

• replica del Django Admin o del suo modello di permessi implicito;
• modifica manuale della struttura fisica osservata;
• memorizzazione o export di password nel catalogo;
• dipendenza del workflow SQL dalla disponibilità della nuova UI;
• proposal/versioning/diff per i commenti AI;
• copia descrizione → commento AI, non presente nelle fonti;
• difetti tecnici e comportamenti insicuri elencati sopra.

Conclusione

ThothAI fornisce già il perimetro funzionale di un catalogo metadati, ma lo realizza mescolando configurazione di connessione, inventario fisico, contenuti semantici, job e UI nel modello Django. ThothII può raggiungere la parità separando questi aspetti e mantenendo invariato il workflow SQL: il catalogo gestisce l'intero database, mentre il core continua a consumare soltanto il sottoinsieme dichiarato dal workspace e pubblicato nel proprio indice Qdrant.

La regola di Q6 è semplice e verificata nelle fonti: generazione nel campo AI, selezione esplicita dell'utente, copia nel campo canonico. Ogni meccanismo ulteriore sarebbe una nuova funzionalità e non è necessario per la parità.