ThothII/CONTEXT.md

# Contesto di dominio di ThothII

## Architettura del workflow

**Workflow Kernel** — Il coordinatore deterministico che possiede lo stato del workflow,
le transizioni, il rollback, la finalizzazione e l'applicazione atomica degli esiti dei
moduli.

**Workflow Module** — Una capacità incapsulata che espone un contratto versionato. Un
modulo può partecipare a più stage e non modifica direttamente lo stato del workflow.

**Stage** — Un punto del workflow, identificato semanticamente, nel quale viene invocato
un modulo. L'identità dello stage è indipendente dalla sua posizione visiva.

**Display code** — L'etichetta di presentazione associata a uno stage, per esempio da
`F1` a `F8`. I display code alimentano gli indicatori di avanzamento nel frontend, ma non
sono usati come identità del workflow o chiavi di dipendenza.

**Module outcome** — Il risultato proposto da un modulo: eventi tipizzati, modifiche agli
artifact, un'eventuale richiesta di revisione umana e uno stato di esecuzione. Il
Workflow Kernel valida e applica l'esito.

**Revision request** — La proposta tipizzata con cui un modulo segnala che lo stage
corrente non può concludersi validamente senza rieseguire lo stesso stage o uno stage
precedente. Non produce direttamente una transizione: il Workflow Kernel valida la
richiesta, sospende l'avanzamento e, per riaprire uno stage già completato, attende una
decisione umana tipizzata. Il Kernel, non il modulo, determina gli eventi e gli artifact
causalmente da rendere stale.

**Question Admission** — Il controllo preliminare eseguito prima delle fasi da `F1` a
`F8`. Nella prima release distingue una domanda utilizzabile da input garbage e verifica
che la domanda appartenga allo scope dichiarato dal workspace. Il suo stato è mostrato
separatamente dagli otto indicatori di fase.

**Workspace scope** — La dichiarazione gestita e versionata di ciò che il database di un
workspace rappresenta e delle domande alle quali è destinato a rispondere. Question
Admission la usa come riferimento per valutare la pertinenza di una domanda.

**Datamart Plugin** — Il modulo sostituibile che implementa lo stage semantico
`datamart`, presentato con display code `F8`. La promozione della memory e la
finalizzazione della sessione non appartengono al Datamart Plugin.

**Ordered workflow** — La pipeline deterministica composta dal preflight Admission,
dagli otto stage principali ordinati da `F1` a `F8` e dalla finalizzazione. L'ordine
degli stage è esplicito; il workflow non è un DAG generale.

**Extension point** — Una posizione semantica nel lifecycle dell'Ordered workflow alla
quale possono contribuire uno o più moduli senza diventare nuovi stage visibili. Un
extension point non possiede un display code.

**Stage state** — La proiezione deterministica degli eventi del workflow che descrive
uno stage come `pending`, `ready`, `running`, `awaiting_human`, `completed`, `skipped` o
`failed`. Non è un valore corrente memorizzato separatamente dal ledger.

**Required contribution** — Il contributo di un modulo a un extension point che deve
concludersi o essere esplicitamente saltato secondo policy prima che il workflow possa
avanzare.

**Best-effort contribution** — Il contributo di un modulo il cui fallimento viene
registrato e mostrato come warning, ma non impedisce al workflow di avanzare.

**Blocked workflow** — La proiezione complessiva di un workflow che non può avanzare a
causa di uno stage o di un contributo required fallito o non disponibile. `Blocked` non
è uno Stage state autonomo.

**Module invocation** — Una singola richiesta del Workflow Kernel a un modulo in uno
stage o extension point. Conserva la stessa identità attraverso eventuali retry, che
sono tentativi distinti della medesima invocation.

**Stage skip** — La conclusione esplicita di uno stage senza eseguirne il comportamento.
È ammessa soltanto dalla policy dello stage e registra motivo e attore; un fallimento non
equivale mai implicitamente a uno skip.

**Stage reopen** — La riapertura di uno stage non finalizzato che rende stale gli esiti
causalmente successivi. Gli effetti esterni già prodotti richiedono una marcatura o una
compensazione esplicita e non sono presentati come automaticamente annullati. Può essere
applicata dal Workflow Kernel in seguito all'approvazione di una Revision request, ma
non può essere eseguita direttamente da Pi o da un Workflow Module.

**Completion policy** — La regola con cui uno stage si conclude: `automatic` quando il
kernel può verificarne deterministicamente l'esito, oppure `review_required` quando è
necessaria un'approvazione umana tipizzata.

**Paused session** — Una sessione interrotta intenzionalmente ma resumibile. L'azione
“Stop and save” mette la sessione in pausa; non la completa e non la marca come fallita.

**Finalized session** — Una sessione completata con esito canonico e immutabile. Una
correzione successiva crea una nuova sessione derivata, collegata a quella precedente.

**After-finalize hook** — Una notifica o attività best-effort eseguita tramite outbox
dopo la finalizzazione. Non può modificare il ledger, gli artifact canonici o lo stato
terminale della sessione.

## Memory

**Memory Module** — Il modulo che possiede le conoscenze ed esperienze curate per
migliorare schema linking e generazione SQL di domande future. Le Memory appartengono
a un workspace e rimangono distinte dalle Evidence.

**Memory Card** — L'unità di contenuto gestibile del Memory Module, con identità,
ambito di applicazione e provenienza. Il formato è allineato per analogia alle
Evidence, senza implicare la stessa origine o lo stesso percorso di pubblicazione.

**Reusable Memory** — Una Memory Card che esprime un chiarimento di dominio, una
regola di costruzione SQL o un errore da evitare con motivo compreso e approvato.
La sua validità è circoscritta a un ambito esplicito e non deriva dalla sola
approvazione di una scelta occasionale in una domanda.

**Solved Question** — Una Memory Card che conserva una domanda risolta con la
relativa soluzione SQL e il contesto necessario a interpretarla. È un exemplar
consultativo: i parametri e le scelte del caso non diventano regole generali.

**Memory Graph** — L'insieme dei collegamenti espliciti fra card che contribuisce
al recupero di conoscenze pertinenti oltre alla somiglianza del contenuto. Il
ritrovamento di una card tramite un collegamento non ne implica l'approvazione.

**Memory Link** — Un collegamento curato fra card, con destinazione e significato
espliciti, che contribuisce alla consultazione di contenuti pertinenti. La sua
rimozione non comporta la cancellazione delle card collegate.

## Evidence

**Context specialist** — La persona competente sul dominio che redige e cura il
contenuto delle Evidence. Può essere distinta da chi amministra l'installazione;
il suo lavoro di redazione non richiede accesso al database applicativo.

**Evidence draft** — Il documento iniziale scritto dallo specialista di contesto,
che il sistema acquisisce e raffina in Evidence Unit. Può essere redatto e
consegnato indipendentemente dall'installazione che userà le Evidence risultanti.

**Evidence Module** — Il modulo autonomo che possiede la preparazione delle Evidence e
la loro consultazione durante il workflow. La preparazione avviene fuori dalle singole
sessioni; il workflow usa soltanto contenuti già pubblicati. A runtime contribuisce agli
stage semantici esistenti, senza diventare uno stage visibile e senza modificare ledger,
artifact o stato del workflow.

**Source Evidence** — Il documento o la dichiarazione che sostiene il contenuto
corrente di una Evidence Unit. Un documento acquisito viene conservato come
riferimento umano; una dichiarazione manuale attribuisce il contenuto alla persona
che lo ha scritto e approvato.

**Manual Evidence declaration** — Una dichiarazione esplicita dell'amministratore
che sostiene una Evidence creata direttamente o una correzione del suo significato.
Non implica una verifica indipendente da parte di una fonte documentale esterna.

**Evidence origin** — Il documento da cui una Evidence Unit è stata inizialmente
derivata. Può restare collegato per provenienza e confronto con gli aggiornamenti
anche quando una dichiarazione manuale sostiene il testo corrente. La sola origine
non dimostra il supporto semantico di una successiva correzione.

**Local Evidence archive** — L'insieme delle Evidence curate custodite
dall'installazione, distinto dalle draft originali e dai contenuti derivati per
la ricerca. Comprende le correzioni manuali e i ritiri deliberati.

**Consolidated Evidence** — Una versione delle Evidence locali controllata come
insieme coerente e pronta per l'attivazione. I file ancora in modifica non ne
cambiano il contenuto.

**Active Evidence** — La versione consolidata disponibile alla consultazione del
core. Un tentativo di aggiornamento fallito conserva la versione attiva precedente.

**Evidence Unit** — La più piccola unità semantica coerente, revisionabile e ricercabile
fondata su una Source Evidence corrente, anche manuale, e con eventuale origine
documentale distinta. Possiede un identificatore stabile indipendente dal kind,
assegnato una volta nella forma `evidence:<slug>`; fonti diverse non vengono fuse
automaticamente.

**Evidence kind** — La categoria semantica di una Evidence Unit, che ne determina i
campi specifici e ne orienta l'uso. Ogni unità ha un solo kind primario; i tipi iniziali
sono `glossary`, `domain`, `enum`, `example`, `mapping`, `normalization`, `formula` e
`reference`.

**Glossary Evidence** — Una Evidence Unit che definisce il significato linguistico, i
sinonimi o le varianti di un termine.

**Domain Evidence** — Una Evidence Unit che esprime una regola o un vincolo del dominio
non rappresentato da un kind più specifico.

**Enum Evidence** — Una Evidence Unit che collega un insieme finito di valori
memorizzati ai relativi significati.

**Example Evidence** — Una Evidence Unit che associa un input o una domanda alla sua
interpretazione o al risultato atteso.

**Mapping Evidence** — Una Evidence Unit che collega un concetto logico agli elementi
del relativo schema fisico.

**Normalization Evidence** — Una Evidence Unit che descrive la trasformazione di una
rappresentazione in una forma canonica.

**Formula Evidence** — Una Evidence Unit che contiene una singola espressione PostgreSQL
componibile e ne dichiara gli input. Una query SQL completa non è una Formula Evidence.

**Reference Evidence** — Una Evidence Unit che rappresenta un collegamento esterno da
restituire come contenuto autonomo, anziché come semplice provenienza.

**Evidence purpose** — La destinazione dichiarata di una Evidence Unit nel workflow:
disambiguation, rewriting, schema linking o SQL generation. È distinta dall'Evidence
kind: il tipo descrive cosa contiene, il purpose quando può essere utile; durante la
ricerca il purpose richiesto è un filtro obbligatorio. Il recupero di esperienze e
soluzioni precedenti appartiene al Memory Module e non è un Evidence purpose.

**Evidence Search Outcome** — Il risultato tipizzato di una consultazione del modulo
Evidence. Distingue una ricerca disponibile, che può legittimamente non trovare
corrispondenze, da un'indisponibilità tecnica che impedisce allo stage chiamante di
avanzare fino a un retry riuscito.

**Evidence receipt** — La traccia minima di una consultazione disponibile conservata
nella sessione: stage semantico, purpose, generazione interrogata e identificatori delle
Evidence restituite. Non duplica il contenuto delle Evidence.

**Curated Evidence** — Una o più Evidence Unit preparate da documenti o curate
manualmente. La presenza nell'archivio curato non implica da sola che il contenuto
sia già attivo per il workflow.

**Published Evidence** — Le Curated Evidence valide appartenenti alla revisione attiva
del workspace e alla generazione Evidence pubblicata. L'approvazione umana precede
l'attivazione, ma non viene duplicata come stato nel manifest.

**Evidence Index** — La proiezione ricercabile e ricostruibile delle Published Evidence.
Accelera il recupero delle informazioni, ma non è una fonte di verità.

**Evidence preparation** — Il processo di authoring che trasforma Source Evidence in
Curated Evidence mediante estrazione e normalizzazione deterministiche, una singola
ristrutturazione assistita dal modello e una validazione finale deterministica. Nella
prima versione accetta Markdown o testo UTF-8 e non acquisisce automaticamente il
contenuto di URL o documenti esterni. Prepara l'intero insieme delle modifiche in
un'area temporanea e lo applica atomicamente soltanto se tutti gli output sono validi;
non ritenta automaticamente una chiamata al modello fallita.

**Supporting excerpt** — Un breve estratto presente nel Source Evidence che sostiene
una Evidence Unit. Il sistema ne verifica deterministicamente la presenza dopo la
normalizzazione meccanica; il curatore resta responsabile di verificarne la sufficienza
semantica.

**Evidence resolution** — La decisione esplicita con cui un curatore risolve un
problema di una Evidence Unit, correggendola, ritirandola oppure ricollegandola a
una fonte adeguata.

**Source update conflict** — Un contrasto fra una fonte aggiornata e una correzione
manuale già approvata. La correzione resta in uso fino alla risoluzione esplicita
del confronto da parte dell'amministratore.

**Evidence source refresh** — La riacquisizione delle fonti esterne richiesta
dall'amministratore per rilevarne le modifiche. Fra due aggiornamenti il contenuto
già acquisito resta il riferimento per preparazione e consultazione.

**Review item** — Un blocco di revisione descritto da codice stabile, messaggio umano e
campo opzionale. Finché viene mantenuto nell'Evidence Unit, ne impedisce la
pubblicazione; la sua storia è conservata da Git, non da uno stato interno all'item.

**Retirement candidate** — Una Curated Evidence che il Source Evidence esistente non
sostiene più. Rimane visibile con un Review item e blocca la pubblicazione finché il
curatore non la elimina oppure la rende nuovamente coerente con il sorgente.

**Evidence evaluation set** — Un piccolo insieme versionato di domande rappresentative
e relativi risultati attesi. La baseline è accettabile quando ogni domanda recupera
almeno un risultato atteso nei primi dieci risultati della fusione RRF; il risultato
nei primi cinque è informativo. Comprende almeno un caso lessicale, uno semantico e uno
misto e conserva, a fini diagnostici, le posizioni dense, BM25 e fused.

**Candidate Evidence Generation** — Una generazione completa dell'Evidence Index che
può essere valutata ma non è ancora visibile alle sessioni. Diventa attiva soltanto se
supera l'Evidence evaluation set.

**Evidence manifest** — Il file versionato e gestito dal sistema che collega ogni
Source Evidence al suo hash e alle Evidence Unit derivate. Conserva gli identificatori
stabili, permette l'elaborazione incrementale e segnala le unità rimaste orfane senza
cancellarle automaticamente.

**Orphaned Evidence Unit** — Una Curated Evidence il cui Source Evidence non esiste più.
Rimane disponibile per la revisione, ma blocca la pubblicazione finché non viene
eliminata, ricollegata oppure ne viene ripristinato il sorgente.

**Evidence Fragment** — Una proiezione ricercabile di una sezione semanticamente
coerente di una Published Evidence. La divisione segue intestazioni e confini di
paragrafo; formule, coppie valore/significato, mapping, regole e URL non vengono mai
tagliati. Il testo completo reso per il frammento usa il solo limite esistente
`max_chunk_chars`, pari per default a 4.000 caratteri; un elemento atomico troppo grande
produce un Review item bloccante. Qdrant indicizza i frammenti, mentre l'Evidence Module
li raggruppa per Evidence Unit.

**Evidence Result** — La rappresentazione di una singola Evidence Unit restituita dalla
ricerca con metadati, migliori estratti, provenienza e riferimento al documento completo.

**Hybrid Evidence retrieval** — La ricerca che combina in Qdrant una graduatoria
semantica dense e una graduatoria lessicale BM25 sparse mediante Reciprocal Rank
Fusion. I metadati tipizzati restringono o orientano i risultati senza creare una
collezione separata per ogni Evidence kind.

**Evidence query text** — La rappresentazione deterministica condivisa dalla ricerca
dense e BM25: domanda originale, concetti, tabelle e colonne in ordine fisso. I campi
vuoti sono omessi; domanda e contesto ricevono soltanto normalizzazione Unicode NFC,
conversione degli a-capo e rimozione degli spazi esterni. Gli elementi contestuali sono
poi deduplicati e ordinati senza conversione delle maiuscole, mentre punteggiatura e
spazi interni della domanda non vengono riscritti.

**Reference Vector Collection** — La collezione Qdrant ricostruibile di un workspace che
contiene Schema, relazioni ed Evidence. Possiede il vettore dense predefinito e il vettore
sparse `bm25`; soltanto gli Evidence Fragment ricevono valori BM25. Il preprocessing può
sostituirla o eliminarla integralmente.

**Memory Vector Collection** — La collezione Qdrant persistente di un workspace che contiene
`memory` e `solved_question`. Non è un output del preprocessing e non viene eliminata dal
Preprocessing Clear.

**Preprocessing Clear** — L'operazione amministrativa che elimina Reference Vector Collection,
LSH, corpus e checkpoint derivati e rende il workspace non pronto. Conserva Memory Vector
Collection, sessioni, Catalog Metadata e database sorgente; non offre history o rollback.

**Formula proposal** — Una formula individuata durante una sessione e conservata come
artefatto della sessione. Non diventa Published Evidence finché non viene importata,
revisionata e approvata nel repository del workspace.

**Fail-closed Evidence retrieval** — Il comportamento per cui un indice assente,
incompatibile o non aggiornato produce nessuna Evidence e un avviso esplicito. Il
workflow può continuare, ma non usa mai silenziosamente contenuti di una revisione
precedente o di un altro workspace.

## Configurazione dei modelli

**Workspace Descriptor** — La dichiarazione versionata dell'identità del workspace e dello
scope delle sue Evidence. Non contiene identità o configurazione del Workspace Database,
Database Binding, fatti strutturali o metadati semantici: il Metadata Catalog associa il
workspace al relativo database.

**Installation Model Catalog** — L'insieme dichiarativo, proprio di un'installazione, dei
modelli disponibili, dei loro Model Usage e dei relativi default. È l'unica autorità per i
modelli di sessione, generazione dei metadati ed embedding e non appartiene a un workspace.
_Avoid_: Model Catalog, Metadata Generation Model Configuration

**Model Usage** — Lo scopo per cui un modello dell'Installation Model Catalog può essere
usato: `session`, `metadata_generation` oppure `embedding`. L'ammissibilità e il default
dipendono dall'uso, non dal workspace.

**Model Selection** — La scelta runtime, a livello di installazione, di un modello del
catalogo per uno specifico Model Usage. Riferisce l'identità canonica del modello senza
ridefinirne provider, endpoint o capacità.

**Model Runtime Projection** — La rappresentazione derivata e non autoritativa
dell'Installation Model Catalog richiesta da uno specifico runtime. Può essere rigenerata
integralmente dalla configurazione dell'installazione.

## Distribuzione del prodotto

**Customer-Hosted Installation** — Un'installazione eseguita interamente nel trust boundary
controllato dall'organizzazione cliente, inclusi eventuali tenant cloud privati. Credenziali,
domande, prompt, metadati e risultati non attraversano quel boundary.
_Avoid_: on-premise deployment, self-managed deployment

**Community Edition** — La distribuzione open source utilizzabile gratuitamente anche in
produzione e capace di eseguire il workflow fondamentale completo.
_Avoid_: free tier, trial edition

**Enterprise Edition** — La distribuzione con licenza commerciale che aggiunge governance
organizzativa, esercizio production-grade e industrializzazione alla Community Edition.
_Avoid_: paid tier, pro edition

## Catalogo dei metadati

**Workspace Database** — Il database che appartiene a un solo workspace e non può essere
condiviso con altri workspace; un workspace può averne al massimo uno. È considerato nella
coppia composta dal database PostgreSQL e da un solo schema: tutte le tabelle, le colonne e
le relazioni catalogate appartengono a quello schema. Il Metadata Catalog conserva
l'associazione, ma non crea né possiede l'identità del workspace.

**Database Binding** — La configurazione specifica di un'installazione che seleziona un
trasporto e fornisce i riferimenti necessari a raggiungere un Workspace Database. Non è una
seconda identità del database e non viene condivisa automaticamente fra installazioni.

**Thoth REST Connector** — Il trasporto REST tipizzato con cui ThothII interroga ed
introspeziona un Workspace Database attraverso il contratto RPC DWH supportato. Non è un
client configurabile per API REST arbitrarie.

**Orphaned Workspace Database** — Un Workspace Database il cui workspace non è più presente
nel catalogo autorevole. Rimane conservato per il recupero amministrativo, ma non può essere
usato dal workflow finché non viene riassegnato a un workspace esistente.

**Metadata Catalog** — L'autorità per l'associazione fra workspace e Workspace Database, la
relativa Database Binding, i fatti strutturali osservati e i metadati semantici curati. Ogni
uso downstream dei metadati del database deriva da questo catalogo.

**Database Profile** — L'insieme curato di scope, descrizioni e metadati semantici
associato a un Workspace Database.

**Physical Table** — Una tabella osservata nello schema esterno di un Workspace Database.
La sua identità e il suo nome appartengono al database esterno, non al Metadata Catalog.

**Catalog Table** — La rappresentazione persistita di una Physical Table nel Metadata Catalog.
La sua appartenenza e identità fisica derivano dall'introspezione: non può essere creata o
rinominata manualmente, ma può essere rimossa tramite Catalog Metadata Cleanup.
_Avoid_: SqlTable, managed table

**Physical Column** — Una colonna osservata in una Physical Table, inclusi nome, posizione,
tipo e appartenenza a chiavi dichiarate. La sua identità e i suoi fatti strutturali appartengono
al database esterno.

**Catalog Column** — La rappresentazione persistita di una Physical Column nel Metadata Catalog.
I fatti osservati sono governati dalla sincronizzazione; Description e Generated Description
sono metadati amministrativi modificabili e la rappresentazione può essere rimossa tramite
Catalog Metadata Cleanup.
_Avoid_: SqlColumn, managed column

**Physical Relationship** — Un vincolo foreign key dichiarato nel database esterno. La sua
identità comprende il vincolo e la sequenza ordinata delle coppie di colonne che lo compongono.

**Catalog Relationship** — La rappresentazione persistita di una Physical Relationship nel
Metadata Catalog. Non è creata o modificata manualmente, ma può essere rimossa tramite Catalog
Metadata Cleanup.
_Avoid_: denormalized FK, relationship string

**Logical Relationship** — Una relazione modificabile fra due Catalog Column che non corrisponde
necessariamente a un vincolo fisico. Può essere Generated o Manual e rimane distinta dalla Catalog
Relationship osservata nel database.

**Generated Relationship** — Una Logical Relationship ricavata dai nomi delle colonne, dalle
primary key e dalla compatibilità dei tipi mediante regole deterministiche, senza LLM, embedding o
campionamento dei dati. Una ricostruzione non riattiva una Generated Relationship cancellata
logicamente, ma può ricrearne una cancellata fisicamente.

**Manual Relationship** — Una Logical Relationship aggiunta dall'utente. La ricostruzione delle
Generated Relationship non la modifica.

**Logical Relationship Deletion** — L'esclusione persistente di una Logical Relationship che ne
conserva l'identità per impedirne la ricreazione automatica finché esistono entrambe le Catalog
Column alle quali è collegata.

**Permanent Relationship Deletion** — La rimozione completa di una Logical Relationship. Una
ricostruzione successiva può ricrearla quando soddisfa nuovamente le regole di inferenza. Anche il
cleanup distruttivo di una tabella o colonna endpoint rimuove permanentemente le relative esclusioni.

**Relationship Reconstruction** — L'operazione amministrativa esplicita che scopre e aggiunge le
Generated Relationship mancanti. Conserva le Manual Relationship e le relationship già presenti e
non riattiva quelle cancellate logicamente.

**Relationship Restore** — La riattivazione esplicita di una Logical Relationship cancellata
logicamente.

**Effective Relationship Map** — La vista unificata delle Catalog Relationship fisiche e delle
Logical Relationship, con origine e stato espliciti. È l'interfaccia usata dall'amministrazione e
dalla comprensione dello schema, non un ulteriore modello persistito.

**Catalog Metadata Snapshot** — La proiezione immutabile e versionata della struttura catalogata,
delle descrizioni pubblicabili e delle relazioni effettive attive di un Workspace Database che il
core consuma. È derivata esclusivamente dal Metadata Catalog e non è un archivio autoritativo.

**Schema Index** — La proiezione vettoriale ricostruibile dei metadati del Workspace Database nel
Metadata Catalog. Il preprocessing la sostituisce integralmente e non è una fonte di verità.

**Description** — Il testo curato e consolidato che descrive una Catalog Table o Catalog Column
per gli usi downstream. Quando presente, prevale sulla relativa Generated Description.

**Generated Description** — Il testo modificabile prodotto dall'AI per una Catalog Table o Catalog
Column. È pubblicabile per gli usi downstream quando manca una Description, anche senza essere
prima consolidato, e rimane distinto dal commento osservato nel database.
_Avoid_: generated comment, source comment

**Description Consolidation** — L'azione amministrativa esplicita che copia la Generated
Description di Catalog Table o Catalog Column selezionate nella relativa Description. Opera sulla
selezione corrente, conserva la Generated Description e non modifica il commento osservato o il
database esterno.

**Table Synchronization** — La riconciliazione esplicita che rende le Catalog Table di un
Workspace Database uguali alle Physical Table osservate: crea quelle nuove, aggiorna i metadati
di origine ed elimina definitivamente quelle assenti. Non modifica mai il database esterno.
_Avoid_: table import

**Schema Synchronization** — La riconciliazione esplicita e autorevole di tabelle, colonne e
Catalog Relationship di un Workspace Database. Può operare su uno scope specifico oppure su
un unico snapshot completo tramite Synchronize All.

**Catalog Sync Run** — L'esecuzione durevole in background di una Schema Synchronization, con
scope, stato, avanzamento e log propri. Al massimo un run per Workspace Database può essere attivo.

**Description Generation Run** — L'esecuzione asincrona e sequenziale che usa il modello scelto
per produrre Generated Description di Catalog Table o Catalog Column. Al massimo una run è attiva
nell'intera installazione e ogni risultato valido viene salvato appena disponibile. Dopo
un'interruzione il recupero è manuale tramite una nuova generazione dei soli elementi mancanti.

**Description Generation Event** — Una riga testuale ordinata che registra avanzamento, risultato
o errore di una Description Generation Run e alimenta il log visibile all'amministratore.

**Non-generatable Description** — L'esito valido con cui il modello dichiara di non disporre di
informazioni sufficienti per descrivere il target. Produce una Generated Description standard
nella lingua del workspace e non rappresenta un timeout, un errore del provider o una risposta
non valida.

**Description Generation Unlock** — Il recupero amministrativo che marca come interrotta una
Description Generation Run registrata come attiva quando il backend non ha alcun processo di
generazione vivo. Non è un meccanismo di lock distribuito.

**Catalog Metadata Cleanup** — La rimozione amministrativa esplicita di Catalog Table, Catalog
Column o Catalog Relationship selezionate. Non modifica il Workspace Database, la Database Binding
o i segreti, e può lasciare il Metadata Catalog intenzionalmente incompleto fino alla prossima
Schema Synchronization.

**Catalog Freshness** — La corrispondenza fra uno scope sincronizzato e la versione corrente
della Database Binding. Uno scope rimane consultabile ma è stale finché non viene sincronizzato
con la binding corrente.

**Metadata Content Revision** — La revisione monotona di tutto lo stato del Metadata Catalog che
può modificare il comportamento del core. Ogni mutazione rilevante produce una nuova revisione
nella stessa transazione che la rende durevole.

**Preprocessing State** — Lo stato corrente `running`, `succeeded` o `failed` del preprocessing di
un workspace, insieme all'identità dei suoi input. Il core può usare il workspace soltanto quando
lo stato è `succeeded` e gli input coincidono ancora.

**Catalog Metadata** — I campi mutabili che descrivono database, tabelle, colonne e relazioni,
distinti dai fatti strutturali governati dalla sincronizzazione. Possono essere popolati dall'AI,
o da una modifica amministrativa senza cambiare il database esterno.

**Model Completion Helper** — Il processo Python interno ed effimero che esegue una singola
richiesta LiteLLM per conto del backend. Non è un servizio HTTP, non possiede il lifecycle della
Description Generation Run e non è una CLI esposta agli utenti.

**Catalog Sample** — Un input transitorio composto da un massimo di cinque righe e da valori di
esempio bounded di una Catalog Table per la generazione delle descrizioni. Può contenere valori
reali oppure sintetici in base alla Source Value Disclosure Decision; non viene persistito e non
diventa Catalog Metadata.

**Sensitive Data Flag** — La classificazione binaria umana applicata a una Catalog Column. Può
essere impostata liberamente dall'amministratore anche in contrasto con una valutazione automatica.

**Sensitivity Reason** — La motivazione sanificata persistita insieme al Sensitive Data Flag
quando l'amministratore salva una Sensitivity Review Draft. È Catalog Metadata della colonna, non
history della run; viene rimossa quando il flag torna non-sensitive e può essere assente per una
classificazione manuale priva di valutazione locale.
_Avoid_: AI reasoning, source evidence

**Local Sensitivity Assessment** — La valutazione locale, non autoritativa e priva di LLM di una
Catalog Column, basata su metadati e contenuto sorgente, con esito `sensitive`, `non_sensitive`
oppure `unknown`.
_Avoid_: AI suggestion, automatic flag

**Local NER Detector** — Il componente NLP opzionale e CPU-only che esamina soltanto testo ancora
ambiguo e restituisce evidenze al Local Sensitivity Assessment. Non decide lo stato della colonna,
non usa un LLM generativo e non persiste valori sorgente.
_Avoid_: AI classifier, local LLM fallback

**Model Data Boundary** — La qualificazione amministrativa di un modello come `internal` oppure
`external` rispetto al confine entro cui i valori sorgente possono essere comunicati.
_Avoid_: local model, remote model

**Source Value Disclosure Decision** — L'unica decisione effettiva che stabilisce se un modello
riceve valori sorgente reali oppure sostituti sintetici, combinando Model Data Boundary e Sensitive
Data Flag.
_Avoid_: sample filter, export flag

**Sensitive Data Policy** — L'insieme versionato di regole locali generali e specifiche che produce
una Local Sensitivity Assessment. Un singolo riscontro blocca l'intera colonna e qualsiasi valore
testuale più lungo di 500 caratteri rende sensibile la colonna.
_Avoid_: PII filter, sample filter

**Sensitivity Analysis Run** — Il tentativo amministrativo esplicito e tracciato che valuta una
selezione di colonne mediante la Sensitive Data Policy. Conserva stato, copertura e conteggi
aggregati, ma non valori sorgente né esiti per colonna.
_Avoid_: Sensitive Data Suggestion Run, AI analysis

**Sensitivity Review Draft** — La proposta transitoria che associa alle colonne selezionate una
Local Sensitivity Assessment e le relative evidenze sanificate. Non modifica il Sensitive Data Flag
né la Sensitivity Reason finché l'amministratore non salva le proprie decisioni e viene scartata al
reload.
_Avoid_: automatic flag

**Sensitivity Analysis Event** — Una riga testuale ordinata e sanificata che registra l'avvio,
l'avanzamento per fase e batch, l'esito o l'errore di una Sensitivity Analysis Run senza conservare
contenuti sorgente, output grezzi del detector o proposte per colonna.
_Avoid_: Sensitive Data Suggestion Event

**Introspection Capability** — Una categoria di struttura fisica che una Database Binding
può osservare, come tabelle, colonne, relazioni, indici o enum. Una capability non disponibile
è distinta da una capability osservata che non ha restituito elementi.

## Amministrazione e integrazione

**Workspace Readiness** — La preparazione di uno specifico Workspace per l'uso nel
workflow, comprensiva della disponibilità degli artefatti derivati dai suoi metadati
Database e dalle sue Evidence. Il preprocessing appartiene a questa preparazione;
la configurazione e la sincronizzazione del catalogo restano responsabilità Database.

**Administration Surface** — Una superficie amministrativa autonoma per configurare o curare una
parte dell'installazione. Workspace, Evidence, Memory, Database e Pi sono superfici peer e non
dipendono dall'esistenza di una sessione attiva.

**Administration Page** — La rappresentazione a pagina intera di una Administration Surface, con
una gerarchia condivisa per identità, stato, azioni e contenuto. Un form amministrativo appartiene
alla pagina e non a una popup come contenitore principale.
_Avoid_: management popup, settings modal

**Administration Route** — L'identità navigabile di una Administration Surface nel browser. Deve
essere ripristinabile con refresh e cronologia e non contiene valori transitori o segreti dei form.

**Embedded Thoth Shell** — L'esperienza Thoth ospitata dentro il documento e il contesto visuale di
un portale host. Conserva la propria gerarchia funzionale, ma deve rispettare la geometria,
l'autenticazione e le regole responsive del portale host.

**Full Thoth Shell** — L'esperienza Thoth autonoma che possiede il proprio header e il proprio
layout di pagina. Non replica la navigazione amministrativa del portale host e non dipende dal suo
template visuale.

**Shell mode** — La scelta di installazione fra `embedded` e `full`. Determina chi possiede il
chrome globale, i comandi di identità e le integrazioni visuali, ma non cambia il workflow o la
persistenza delle sessioni.

**Fullscreen state** — Lo stato temporaneo in cui il documento applicativo occupa il fullscreen
del browser. È distinto da `Shell mode`: una Full Thoth Shell può essere aperta senza fullscreen;
il passaggio è attivato da un comando esplicito e può essere annullato con la stessa azione o con
il comando nativo del browser.

**Portal Shell Adapter** — Il confine sostituibile che traduce lo stato e i comandi del chrome di
un portale host nel modello semantico usato da Thoth. L'adapter non possiede autorizzazione,
sessioni di workflow o contenuti del modello.

**Host Shell State** — Il minimo stato visuale fornito dal portale host: locale UI, tema e stato
fullscreen. In una Embedded Thoth Shell è la fonte autorevole per queste preferenze;
non include identità, token o stato di autenticazione, che restano responsabilità dell'accesso.

**UI locale** — La lingua delle label, dei messaggi, dei tooltip, degli stati e delle istruzioni
non generate dal modello nell'interfaccia Thoth. È distinta dalla lingua dei contenuti di un
workspace.

**Interaction language** — La lingua in cui il modello presenta domande, spiegazioni e proposte
al revisore durante una sessione. Viene fissata alla creazione della sessione e rimane invariata
durante una ripresa, anche se la UI locale corrente cambia.

**Administrative Page Family** — L'insieme delle cinque Administration Page che condividono shell,
navigazione, tipografia e regole responsive, pur mantenendo contenuti e operazioni specifici:
Workspace, Evidence, Memory, Database e Pi.

## Installazione

**Manual standalone installation** — Una copia di ThothII predisposta per l'uso autonomo da una
persona che possiede il computer, con una Full Thoth Shell e servizi applicativi locali. La
procedura non implica che DWH o provider LLM siano locali o disponibili offline.

**Installation bootstrap** — L'insieme delle attività iniziali che rende disponibile una
installazione manuale: verifica dell'host, generazione della configurazione, predisposizione
delle credenziali protette e avvio dei servizi. Non è un installer dell'applicazione.

**Platform acceptance** — La verifica che una Manual standalone installation possa essere
predisposta e avviata su una specifica combinazione di sistema operativo, architettura e runtime,
distinta dalla verifica funzionale del collegamento a DWH e provider LLM.