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.

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.