docs: define modular workflow domain semantics

CONTEXT.md

@@ -0,0 +1,110 @@
+# 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.