docs(evidence): finalize restructuring design

This commit is contained in:
2026-08-24 14:57:53 +02:00
parent 6062cb010e
commit d970e10264
8 changed files with 2133 additions and 0 deletions
+67
View File
@@ -91,6 +91,73 @@ correzione successiva crea una nuova sessione derivata, collegata a quella prece
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.
**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. 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. I tipi iniziali sono `glossary`, `domain`, `enum`,
`example`, `mapping`, `normalization`, `formula` e `reference`.
**Evidence purpose** — La destinazione dichiarata di una Evidence Unit nel workflow:
disambiguation, rewriting, schema linking, SQL generation o memory. È distinta
dall'Evidence kind: il tipo descrive cosa contiene, il purpose quando può essere utile.
**Curated Evidence** — Una o più Evidence Unit ristrutturate a partire da una Source
Evidence e conservate nel repository del workspace per la revisione umana. Non sono
ancora contenuto autorevole del runtime.
**Published Evidence** — Le Curated Evidence appartenenti a una revisione Git approvata
e attivata del workspace. Sono le sole Evidence utilizzabili dalle sessioni ThothII.
**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.
**Review item** — Un'ambiguità o un'informazione incompleta segnalata durante l'Evidence
preparation. Finché un Review item non viene risolto, oppure trasformato dal revisore in
una limitazione esplicita del contenuto, l'Evidence Unit non può essere indicizzata.
**Evidence evaluation set** — Un piccolo insieme versionato di domande rappresentative
e relativi risultati attesi, usato per verificare in modo ripetibile la qualità della
ricerca senza introdurre una piattaforma di valutazione separata.
**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.
**Evidence Fragment** — Una proiezione ricercabile di una sezione semanticamente
coerente di una Published Evidence. Qdrant indicizza i frammenti, mentre l'Evidence
Module li raggruppa e restituisce al workflow l'Evidence Unit completa.
**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.
**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