From b5db0cd3c12a4184a91933f6cf9d4ee13241ba65 Mon Sep 17 00:00:00 2001 From: mptyl Date: Sun, 23 Aug 2026 14:03:20 +0200 Subject: [PATCH] docs: define modular workflow domain semantics --- CONTEXT.md | 110 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 CONTEXT.md diff --git a/CONTEXT.md b/CONTEXT.md new file mode 100644 index 00000000..e244e670 --- /dev/null +++ b/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.