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.

Evidence

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 — Un documento originale del workspace, conservato senza modifiche come riferimento umano e origine della successiva ristrutturazione.

Evidence Unit — La più piccola unità semantica coerente, revisionabile e ricercabile derivata da una sola Source Evidence. 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 ristrutturate a partire da una Source Evidence e conservate nel repository del workspace come proposte per la revisione umana. Git conserva la versione precedente e rende visibile ogni modifica; una Curated Evidence non è ancora contenuto autorevole del runtime.

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 — L'operazione esplicita con cui un curatore ritira una Evidence Unit oppure la ricollega a un Source Evidence esistente. Aggiorna documento e manifest insieme, lascia un diff Git revisionabile e non pubblica né crea commit.

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.

Additive BM25 upgrade — L'estensione non distruttiva della collezione semantica di un workspace che conserva il vettore dense predefinito e aggiunge il solo vettore sparse bm25. Soltanto gli Evidence Fragment ricevono valori BM25; Schema e Memory mantengono invariati dati e ricerca dense.

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.

Catalogo dei metadati

Workspace Database — Il database associato a un workspace, considerato nella sua interezza fisica: tutte le tabelle, le colonne e le relazioni disponibili, anche quando solo un loro sottoinsieme è destinato al core di ThothII.

Metadata Catalog — Il contesto amministrativo che raccoglie e cura i metadati di un Workspace Database. Non definisce quali elementi partecipano al workflow SQL.

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

AI Proposal — Un contenuto generato con l'ausilio dell'AI che non è ancora stato approvato come contenuto canonico.

Publication — Una versione approvata e immutabile dei contenuti del Metadata Catalog resa disponibile ai suoi consumatori.