docs: revalidate metadata catalog research

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

@@ -1,21 +1,80 @@
 # Inventario delle funzionalità legacy di gestione metadati di ThothAI
 
-Data: 2026-08-23
+Data dell'inventario: 2026-08-23
 
-Issue: `mptyl/ThothII#6`
+Ultima verifica rispetto a ThothII: 2026-08-31
+
+Stato: **inventario storico verificato; non è una specifica dello stato corrente**.
+
+Issue originaria: [mptyl/ThothII#6](https://git.tylconsulting.it/mptyl/ThothII/issues/6)
 
 Fonte primaria: repository legacy annidato `Thoth/ThothAI`, commit
 `55855de0f18e5cb4bc72f0a2ab0a7317995186dd`.
 
-## Sintesi
+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.
 
-La parità funzionale richiesta a ThothII comprende un catalogo dei database, l'inventario
+> 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](../plans/2026-08-26-metadata-catalog-from-thothai.md)
+  e il [contratto dello schema snapshot](../contracts/catalog-schema-snapshot.md);
+- gli ADR del catalogo, in particolare
+  [0001](../adr/0001-postgres-metadata-catalog.md),
+  [0004](../adr/0004-fastify-kysely-metadata-catalog.md),
+  [0006](../adr/0006-separate-physical-and-logical-relationships.md),
+  [0007](../adr/0007-durable-authoritative-schema-synchronization.md),
+  [0008](../adr/0008-allow-manual-catalog-metadata-cleanup.md),
+  [0009](../adr/0009-use-one-sequential-description-generation-run.md),
+  [0010](../adr/0010-allow-bounded-real-source-samples-for-description-generation.md) e
+  [0011](../adr/0011-gate-source-samples-with-a-sensitive-data-flag.md);
+- 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](../adr/0001-postgres-metadata-catalog.md)–[0004](../adr/0004-fastify-kysely-metadata-catalog.md) 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](../adr/0006-separate-physical-and-logical-relationships.md). |
+| 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](../adr/0008-allow-manual-catalog-metadata-cleanup.md) 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](../adr/0009-use-one-sequential-description-generation-run.md) 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](../adr/0010-allow-bounded-real-source-samples-for-description-generation.md) e [0011](../adr/0011-gate-source-samples-with-a-sensitive-data-flag.md): 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](../adr/0006-separate-physical-and-logical-relationships.md). |
+| 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 è volutamente semplice e va mantenuto tale:
+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;
@@ -193,7 +252,7 @@ scrive soltanto `column.generated_comment`
 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à da implementare
+### Comportamento di parità proposto il 2026-08-23
 
 Il contratto funzionale minimo è esattamente questo:
 
@@ -314,7 +373,7 @@ Il modulo contiene anche un helper verso `mermaid.ink`, ma non risultano call si
 legacy; il percorso attivo è il servizio locale. Non va quindi considerata una dipendenza
 funzionale da conservare.
 
-## 9. Baseline di parità per il Metadata Catalog di ThothII
+## 9. Baseline di parità proposta il 2026-08-23
 
 ### Necessario