Merge remote-tracking branch 'origin/main'
# Conflicts: # mkdocs.yml
This commit is contained in:
Codex
@@ -0,0 +1,492 @@
|
||||
# Progetto: Evidence management
|
||||
|
||||
Data: 2026-09-08. Stato: archivio locale Markdown, editor esterni e consolidamento
|
||||
manuale con commit/push dell'operatore accettati per la release 0;
|
||||
restanti semplificazioni confermate, con chiarimenti su impatto core e controllo Git;
|
||||
E1, E2, E3 e il collegamento ai gate X1 implementati il 2026-09-09.
|
||||
Il contratto X1 è in [Session corrections](../contracts/archive-repair.md). Risultati e limiti in
|
||||
[E1 — validazione](2026-09-09-evidence-e1-validation.md) e
|
||||
[E2 — validazione](2026-09-09-evidence-e2-validation.md) e
|
||||
[E3 — validazione](2026-09-09-evidence-e3-validation.md).
|
||||
|
||||
La [revisione di semplicità](2026-09-08-memory-evidence-simplification-review.md)
|
||||
registra il riesame di Q1–Q15. Il flusso principale è draft scritta dallo specialista
|
||||
indipendentemente dall'installazione, raffinamento da parte del sistema e
|
||||
conservazione locale per uso e manutenzione. La proposta tecnica aggiornata
|
||||
distingue le fonti esterne dall'archivio canonico locale, evita PostgreSQL per le
|
||||
Evidence e toglie commit/push dal normale CRUD. La contemporaneità con attività core
|
||||
durante l'amministrazione non è più un requisito da supportare.
|
||||
|
||||
Il progetto rende consultabili le Evidence dall'applicazione e modificabili nei
|
||||
file locali tramite l'editor scelto dall'operatore.
|
||||
Segue le [decisioni comuni di Administration](2026-09-08-memory-evidence-administration.md)
|
||||
ed è consegnabile separatamente da [Memory management](2026-09-08-memory-management.md).
|
||||
|
||||
## Risultato richiesto
|
||||
|
||||
Un amministratore apre Evidence management direttamente da Administration, cerca e
|
||||
filtra le Evidence registrate, consulta il documento completo e trova il percorso
|
||||
del file Markdown da modificare con un editor esterno. La voce segue Memory management e si trova allo stesso
|
||||
livello di Database management, senza appartenere alle sue funzionalità.
|
||||
|
||||
La consultazione è indipendente da una sessione e dalla disponibilità dell'indice
|
||||
semantico. Mostra le Evidence Unit complete, senza limitarsi ai frammenti o ai
|
||||
risultati più simili restituiti dal recall.
|
||||
|
||||
## Accesso e modifica nella release 0
|
||||
|
||||
Il proprietario richiede file facilmente raggiungibili e modificabili anche da uno
|
||||
specialista non tecnico, con Markdown come formato di lavoro e senza JSONL per la
|
||||
gestione delle Evidence. Ha scelto editor esterni per la release 0: l'editor
|
||||
preferito sul Mac o PC, oppure vim, nano o equivalenti sul server. Questa scelta
|
||||
sostituisce la proposta di editor e form di contenuto dentro Evidence management.
|
||||
Non si integra un prodotto di editing né si costruisce un editor applicativo.
|
||||
|
||||
Evidence management mantiene elenco, ricerca, filtri e dettaglio. Mostra il percorso
|
||||
assoluto della cartella del workspace e di ciascun file, con possibilità di copiarlo,
|
||||
risolto dalla configurazione effettiva dell'installazione. Indica su quale host si
|
||||
trova: per Docker occorre il percorso persistente accessibile sull'host, non soltanto
|
||||
quello interno al container. Le istruzioni distinguono draft originali e file delle
|
||||
Evidence raffinate da manutenere; includono un esempio Markdown per crearne una.
|
||||
|
||||
Chi lavora sul server modifica direttamente i file; chi lavora su una copia sul
|
||||
Mac o PC la riporta nello stesso archivio con i propri strumenti. Non è richiesto
|
||||
costruire upload/download nell'applicazione o predisporre una cartella condivisa.
|
||||
Un percorso sul server non viene presentato come un file apribile dal browser locale.
|
||||
|
||||
Dopo aver salvato, aggiunto o rimosso i file, l'operatore controlla lo stato Git,
|
||||
esegue il consolidamento ed esegue commit e push; il normale diff Git è disponibile
|
||||
per approfondire le modifiche. La pagina mostra
|
||||
le istruzioni e i comandi con i percorsi effettivi. La richiesta più recente
|
||||
sostituisce la proposta intermedia del pulsante `Apply file changes`: non sono
|
||||
necessari un pulsante di esecuzione, watcher o operazioni Git automatiche.
|
||||
Il semplice salvataggio nell'editor, o di una copia fuori dall'archivio, non aggiorna
|
||||
il recall. Il consolidamento e il seguito Git sono descritti sotto.
|
||||
|
||||
Il Markdown canonico attuale non è già un formato di editing libero: il parser
|
||||
controlla marker e corrispondenza fra testo canonico e presentazione. Per le regole
|
||||
di dominio il testo codificato viene letto prima di verificare il rendering; cambiare
|
||||
la sola frase visibile può produrre un errore di canonicalità. E1 deve quindi rendere
|
||||
il Markdown locale realmente editabile: il testo leggibile è autorevole, i campi
|
||||
richiesti sono documentati e i metadati derivati sono aggiornati dal sistema.
|
||||
Non si chiede all'operatore di correggere marker, hash o una copia codificata del
|
||||
testo. Non si introduce un secondo archivio di scambio da sincronizzare.
|
||||
|
||||
## Funzioni
|
||||
|
||||
- Elenco paginato e ordinabile; ricerca per testo, titolo e identificatore stabile.
|
||||
- Filtri combinabili per workspace, kind, purpose, concetti, tabelle/colonne,
|
||||
Source Evidence, Review item e stato di pubblicazione.
|
||||
- Dettaglio leggibile della card: contenuto tipizzato, ambito di applicazione,
|
||||
Supporting excerpt, provenienza e accesso alla Source Evidence disponibile.
|
||||
- Creazione e modifica tramite file Markdown ed editor esterno, con esempio dei
|
||||
campi richiesti per kind. In assenza di documento esterno, l'applicazione registra
|
||||
una dichiarazione manuale come fonte quando acquisisce la modifica.
|
||||
- Risoluzione dei Review item e gestione delle unità orfane o da ritirare.
|
||||
- Cancellazione tramite rimozione del file, riconosciuta dal consolidamento
|
||||
nell'archivio locale verificato come accessibile; un errore di lettura non prova
|
||||
una cancellazione. La rimozione dal corpus e dall'indice è persistente.
|
||||
- Un comando manuale di consolidamento per acquisire e validare le modifiche locali
|
||||
e renderle disponibili al core, con esito esplicito e possibilità di riesecuzione.
|
||||
- Istruzioni per controllo del diff, commit e push dei file Evidence e dei relativi
|
||||
metadati necessari, eseguiti dall'operatore nel repository indicato.
|
||||
|
||||
Il servizio acquisisce il Markdown editabile e aggiorna la rappresentazione
|
||||
tipizzata e i metadati derivati, preservando gli identificatori delle unità esistenti.
|
||||
La cancellazione di una Evidence Unit non elimina automaticamente la sua Source
|
||||
Evidence o altre unità derivate dalla stessa fonte.
|
||||
|
||||
## Salvataggio — Q12 semplificata
|
||||
|
||||
Il proprietario rifiuta la separazione ordinaria fra salvataggio della bozza e
|
||||
pubblicazione: le modifiche durante una sessione sono considerate rare e non
|
||||
giustificano un workflow editoriale separato. La scelta successiva dell'editor esterno
|
||||
sostituisce il `Save` della form con il salvataggio del file e un comando manuale
|
||||
di consolidamento. Questo acquisisce, valida e attiva insieme aggiunte, modifiche e
|
||||
cancellazioni, senza un successivo `Publish` o un secondo revisore. Commit e push
|
||||
sono il seguito manuale per versionare e trasferire il lavoro nel repository.
|
||||
L'operatore autorizza l'attivazione con il consolidamento. Le correzioni approvate nei
|
||||
gate chiamano direttamente lo stesso servizio e non richiedono un editor esterno.
|
||||
|
||||
L'ultimo chiarimento del proprietario sostituisce il requisito iniziale di aggiornare
|
||||
le sessioni aperte mentre un amministratore modifica le Evidence. Si assume che il
|
||||
core sia fermo o si ignora la contemporaneità: non servono aggiornamenti a caldo,
|
||||
notifiche, ricalcoli, attese delle sessioni o una modalità manutenzione dedicata.
|
||||
Il risultato di una modifica completata è usato nelle successive elaborazioni.
|
||||
|
||||
Restano le correzioni deliberate dalla sessione stessa secondo Q4: chiamano lo
|
||||
stesso servizio, attendono l'esito e permettono alla sessione di usare la correzione
|
||||
approvata. Il collegamento fra configurazione della ricerca e contenuto locale
|
||||
deve quindi funzionare senza richiedere un nuovo commit della fonte per ogni modifica;
|
||||
non richiede un sistema generale di aggiornamento delle altre sessioni.
|
||||
|
||||
Nel seguito, salvataggio applicativo indica questa acquisizione delle modifiche o
|
||||
la scrittura deliberata dal core. Il feedback ordinario è operazione in corso,
|
||||
completata oppure errore. Un successo
|
||||
completo significa che il contenuto è disponibile al core; se la persistenza riesce
|
||||
ma l'aggiornamento del corpus o dell'indice fallisce, l'esito deve dirlo e indicare
|
||||
come rieseguire il comando. Un errore tecnico non diventa una bozza che attende una nuova decisione
|
||||
editoriale di pubblicazione. Dopo un errore o un riavvio, un corpus parziale non
|
||||
deve essere dichiarato pronto per la successiva elaborazione.
|
||||
|
||||
Le decisioni Q11–Q15 e il successivo chiarimento sui vincoli sono registrati
|
||||
nell'[ADR 0019](../adr/0019-author-evidence-in-app-with-automatic-activation.md).
|
||||
|
||||
## Consolidamento manuale e seguito Git — release 0 {#consolidamento-manuale-e-seguito-git--release-0}
|
||||
|
||||
Il proprietario richiede un flusso KISS affidato alla disciplina dell'operatore.
|
||||
Il comando proposto è `tht evidence consolidate <workspace-root>` nel harness:
|
||||
è da implementare, non è un comando già disponibile. Riutilizza parser, validazione
|
||||
e indicizzazione esistenti, adattati al Markdown editabile. La documentazione
|
||||
operativa e la pagina mostreranno l'invocazione effettiva per l'installazione,
|
||||
compreso l'accesso al core se il comando gira in Docker.
|
||||
|
||||
Il consolidamento svolge in sequenza questi passaggi:
|
||||
|
||||
1. Legge l'archivio locale e confronta aggiunte, modifiche e rimozioni con l'ultimo
|
||||
contenuto consolidato. Se l'archivio non è accessibile, si ferma: non interpreta
|
||||
il problema come cancellazione delle Evidence.
|
||||
2. Verifica struttura e sezioni previste per kind, campi obbligatori, identificatori
|
||||
univoci, tipi, riferimenti e provenienza coerenti. Segnala file, campo o sezione,
|
||||
problema e correzione richiesta. Non valuta automaticamente la verità del contenuto
|
||||
e non riscrive il significato delle regole con un nuovo raffinamento del modello.
|
||||
3. Se ci sono errori, termina con esito non riuscito prima dell'attivazione; lascia
|
||||
all'operatore i file da correggere e il comando da rieseguire. Se i controlli
|
||||
passano, aggiorna metadati derivati e manifest, inclusa la protezione delle
|
||||
correzioni e delle cancellazioni, poi prepara e verifica il candidato completo
|
||||
prima di renderlo attivo nel corpus e nell'indice Evidence locale.
|
||||
4. Riporta un riepilogo testuale breve di file aggiunti, modificati e cancellati,
|
||||
l'esito locale, gli eventuali errori di indicizzazione e i file primari
|
||||
da includere nel commit. Dopo un errore tecnico si riesegue lo stesso comando,
|
||||
senza duplicare unità o perdere il contenuto modificato. Non dichiara pronto un
|
||||
aggiornamento incompleto e non avvia commit, push, pull o merge.
|
||||
|
||||
Il core legge soltanto il contenuto consolidato attivo, mai direttamente i file in
|
||||
corso di modifica. Una modifica salvata ma non consolidata, o un tentativo fallito,
|
||||
non deve mescolare testo nuovo e vecchi risultati di ricerca. Si conserva l'ultimo
|
||||
corpus valido; se un errore tecnico non permette di garantirne l'integrità, si
|
||||
segnala l'indisponibilità invece di usare uno stato parziale. Si riusa il percorso
|
||||
esistente di preparazione del candidato e attivazione, senza creare un secondo
|
||||
archivio autorevole o un sistema di coordinamento delle sessioni.
|
||||
|
||||
L'archivio mantenuto è una working tree persistente, versionabile nel repository
|
||||
che contiene quelle Evidence; può riusare il repository del workspace. Draft e
|
||||
unità curate restano contenuti distinti anche se ospitati nello stesso repository.
|
||||
Non si modifica una materializzazione temporanea o uno snapshot runtime ricreato
|
||||
dal preprocessing. Setup e pagina indicano working tree, cartella delle Evidence,
|
||||
branch e remoto configurati; non si creano automaticamente repository o remoti.
|
||||
|
||||
Il seguito manuale, documentato come sequenza da eseguire nel repository corretto, è:
|
||||
|
||||
```text
|
||||
git -C <repository-root> status --short
|
||||
tht evidence consolidate <workspace-root> # comando previsto, da implementare
|
||||
git -C <repository-root> add -- <file-evidence-e-metadati-indicati>
|
||||
git -C <repository-root> commit -m "Update Evidence"
|
||||
git -C <repository-root> push
|
||||
```
|
||||
|
||||
Il controllo umano usa i normali comandi Git nel terminale. `git status --short`
|
||||
mostra quali file sono cambiati; `git diff HEAD` permette, quando serve, di vedere
|
||||
le righe cambiate prima del consolidamento. `git diff --cached` è disponibile per
|
||||
controllare ciò che si sta per committare. Non sono richiesti un visualizzatore
|
||||
nell'applicazione, uno strumento grafico, due revisioni obbligatorie o un nuovo gate.
|
||||
I controlli strutturali del consolidamento vengono invece sempre eseguiti.
|
||||
|
||||
Si includono aggiunte, modifiche e cancellazioni dei dati primari necessari alla
|
||||
ricostruzione, compresi manifest e informazioni di cura manuale quando cambiano.
|
||||
Indici, cache, sessioni e segreti non fanno parte del commit Evidence. L'operatore
|
||||
controlla aggiunte, modifiche e cancellazioni prima di consolidare; i file nuovi
|
||||
segnalati da status vanno letti, perché non compaiono ancora nel diff dei file
|
||||
tracciati. L'output del consolidamento indica anche i metadati generati da includere
|
||||
nel commit. Errori Git, credenziali, branch senza upstream e conflitti vengono
|
||||
risolti con i normali strumenti Git, senza retry o risoluzioni automatiche.
|
||||
|
||||
L'ordine ha una conseguenza esplicita: un consolidamento riuscito aggiorna il core
|
||||
locale prima di commit e push. Se il push manca o fallisce, la modifica rimane locale
|
||||
e non è ancora trasferita al remoto; l'operatore completa il seguito Git. Un push
|
||||
riuscito, da solo, non aggiorna altre installazioni. Nessun processo sorveglia i file
|
||||
o impone che l'operatore abbia completato la sequenza prima di riprendere il lavoro.
|
||||
|
||||
## Persistenza e contratto da evolvere
|
||||
|
||||
Il proprietario ha approvato la risoluzione persistente dei conflitti fra Memory ed
|
||||
Evidence nel round Q4 della discussione Memory. Quando la decisione richiede correggere
|
||||
un'Evidence, il core prepara una proposta che identifica l'unità e mostra il testo
|
||||
o l'ambito risultante. La correzione passa attraverso l'authoring e la pubblicazione
|
||||
di questo modulo, con le relative autorizzazioni e validazioni. L'accettazione della
|
||||
correzione da parte di un utente autorizzato avvia lo stesso salvataggio con attivazione
|
||||
automatica. L'interfaccia distingue una proposta da approvare, un aggiornamento in
|
||||
corso o fallito e una correzione già attiva; non basta risolvere soltanto
|
||||
la domanda corrente. È sempre possibile dichiarare inadeguate le opzioni proposte.
|
||||
|
||||
Oggi il [lifecycle Evidence](../evidence.md) attribuisce l'authoring al repository
|
||||
del workspace: ThothII non lo modifica, non crea commit e non esegue push.
|
||||
Il [contratto Workspace Evidence v3](../contracts/workspace-evidence-v3.md) lega la
|
||||
pubblicazione a una revisione coerente del workspace. La manutenzione dei file locali
|
||||
richiede un'evoluzione esplicita di questo percorso e del formato editabile.
|
||||
|
||||
**Q11, riesaminata e accettata per l'archivio locale:** la draft dello specialista deve restare producibile e
|
||||
consegnabile senza accesso al PostgreSQL o alla stessa installazione. La
|
||||
scelta aggiornata conserva le fonti in file/repository esterni e le
|
||||
Evidence raffinate in un archivio locale persistente su file Markdown, gestito dal sistema.
|
||||
Il CRUD modifica tale archivio e aggiorna l'indice senza commit/push verso le fonti.
|
||||
L'alternativa di rendere PostgreSQL autorevole anche per Evidence, suggerita nella
|
||||
prima parte della revisione, è ritirata. PostgreSQL rimane l'archivio delle Memory.
|
||||
|
||||
I file locali curati sono dati primari: sopravvivono a Clear e reindicizzazione e
|
||||
devono essere inclusi nelle copie di sicurezza dell'installazione. Una loro modifica
|
||||
non aggiorna automaticamente i documenti dello specialista o altre installazioni;
|
||||
un eventuale trasferimento dei file resta esplicito, senza sincronizzazione bidirezionale.
|
||||
|
||||
Il comportamento deve coprire le origini supportate dal prodotto: filesystem/Git,
|
||||
HTTP e S3. Nella proposta riveduta sono origini di acquisizione delle fonti e dei
|
||||
contenuti già disponibili. Servono importazione e provenienza coerenti; le unità
|
||||
raffinate e le modifiche manuali vengono conservate nell'archivio locale.
|
||||
La gestione delle Evidence non richiede di aggiungere scritture sui server HTTP o S3
|
||||
di origine. Non si può dichiarare completato il CRUD lasciando queste unità in sola
|
||||
lettura senza un percorso di importazione utilizzabile.
|
||||
|
||||
Il descriptor `evidence.source` indica oggi l'origine acquisita dal preprocessing:
|
||||
non è già un importatore di documenti nel repository di authoring. Inoltre il
|
||||
runtime normalizza HTTP/S3 come documenti generici, mentre il parser canonico delle
|
||||
unità tipizzate viene applicato ai file sotto `curated/<kind>/`. La provenienza
|
||||
canonica ammette solo un percorso locale sotto `source/`; URI e fingerprint remoti
|
||||
esistono invece nel corpus acquisito. L'importazione deve collegare questi due
|
||||
livelli senza fingere che il percorso tipizzato sia già uniforme fra i trasporti.
|
||||
|
||||
Modifiche e ritiri devono sopravvivere alla successiva preparazione, sincronizzazione
|
||||
e reindicizzazione. La rigenerazione da una fonte non deve ripristinare silenziosamente
|
||||
una unità cancellata o sovrascrivere la correzione del curatore. La semantica di
|
||||
conflitto fra nuova Source Evidence e cura manuale è approvata in Q13.
|
||||
|
||||
Il runtime attuale non garantisce questa protezione durevole: `evidence prepare`
|
||||
rifiuta modifiche non committate ai file curati e al manifest, ma una fonte cambiata
|
||||
può rigenerare anche unità corrette manualmente e già committate. Il ritiro esplicito
|
||||
rimuove l'unità e i riferimenti nel manifest, senza conservare una soppressione che
|
||||
impedisca a una successiva generazione di riproporla. Questi comportamenti sono
|
||||
verificati in `harness/tht/evidence/authoring.py`; la gestione amministrativa richiede
|
||||
di evolverli, non solo di esporli come comandi dell'editor.
|
||||
|
||||
**Q13, approvata:** se la fonte aggiornata contraddice una correzione
|
||||
manuale, conservare in uso l'Evidence salvata dall'amministratore e mostrare il
|
||||
confronto in Evidence management. Una sostituzione richiede una scelta esplicita,
|
||||
seguita dalla stessa operazione di attivazione. La conseguenza è che la regola manuale può restare
|
||||
attiva anche se la fonte più recente dice altro, finché il conflitto non viene
|
||||
risolto. Il proprietario accetta questa conseguenza. La decisione comprende la
|
||||
permanenza delle cancellazioni e la protezione da sovrascritture silenziose: una
|
||||
nuova preparazione non deve riproporre automaticamente conoscenze eliminate.
|
||||
|
||||
Validazione e pubblicazione sono passaggi interni dell'unica operazione di salvataggio;
|
||||
un errore non dichiara attivo il nuovo contenuto. Il sistema continua a rispettare
|
||||
provenienza e coerenza del contenuto; il salvataggio esplicito dell'amministratore
|
||||
costituisce l'approvazione della modifica manuale. La decisione sullo storico delle
|
||||
Memory non elimina questi requisiti del dominio Evidence.
|
||||
|
||||
## Creazione manuale e aggiornamento delle fonti — Q14 e Q15 approvate
|
||||
|
||||
**Q14, approvata:** consentire di scrivere una
|
||||
Evidence senza dover fornire un documento esterno. In release 0 la si scrive in un
|
||||
nuovo file Markdown nell'archivio indicato, usando l'esempio documentato.
|
||||
Il sistema registra una dichiarazione manuale come fonte gestita e la distingue
|
||||
dall'informazione derivata da documenti. Lo stesso criterio vale per una correzione
|
||||
che cambia il significato del contenuto: la dichiarazione dell'amministratore
|
||||
sostiene il testo corrente, mentre il documento originario resta collegato come
|
||||
origine e per rilevarne gli aggiornamenti. Non deve essere mostrato come prova di
|
||||
una regola che non contiene. Il consolidamento acquisisce anche le nuove unità manuali.
|
||||
|
||||
Oggi la provenienza canonica richiede fonte locale, hash ed estratti: non esiste
|
||||
un'origine manuale esplicita. La validazione verifica integrità e presenza testuale
|
||||
degli estratti, ma non dimostra la verità o il supporto semantico della regola.
|
||||
Attuare Q14 richiede distinguere nel contratto la fonte del testo corrente dal
|
||||
documento originario; non richiede inventare estratti o una validazione semantica
|
||||
automatica presentata come garanzia di correttezza.
|
||||
|
||||
**Q15, approvata:** riacquisire le fonti esterne su richiesta
|
||||
esplicita dell'amministratore, senza controlli periodici o accessi alle fonti a ogni
|
||||
domanda o salvataggio di una card. Fra due aggiornamenti richiesti, il sistema usa
|
||||
quanto già acquisito. Il consolidamento continua ad attivare la modifica locale
|
||||
senza richiedere prima un aggiornamento della fonte remota; eventuali conflitti
|
||||
scoperti alla successiva acquisizione seguono Q13.
|
||||
|
||||
Il proprietario ha approvato entrambe le raccomandazioni il 2026-09-08. Il successivo
|
||||
riesame conserva questi comportamenti e rende esplicita l'autonomia dello specialista
|
||||
che produce le draft. I dettagli tecnici seguenti descrivono la proposta semplificata.
|
||||
|
||||
## Piano esecutivo
|
||||
|
||||
### E1 — Raffinamento e archivio canonico locale
|
||||
|
||||
**Modifica del sottosistema Evidence core.** Rendere editabile il Markdown cambia
|
||||
il contratto che il codice attuale legge e scrive. Questa attività precede la
|
||||
pagina amministrativa: non è una modifica limitata alla presentazione o all'editor.
|
||||
Il nuovo formato conserva contenuti tipizzati, ambito e provenienza richiesti dal
|
||||
core, ma usa il testo visibile come unica rappresentazione autorevole del contenuto
|
||||
umano. Va identificato come una nuova versione del contratto Curated unit, distinta
|
||||
dalla versione del descriptor del workspace.
|
||||
|
||||
L'intervento coordinato comprende:
|
||||
|
||||
- parser, renderer e validazione in `harness/tht/evidence/canonical.py`;
|
||||
- preparazione, scritture e migrazione in `harness/tht/evidence/authoring.py`,
|
||||
con adeguamento delle istruzioni e degli esempi usati nel raffinamento;
|
||||
- acquisizione e normalizzazione in `harness/tht/evidence/corpus/normalize.py`,
|
||||
consolidamento e preprocessing, affinché producano il contenuto tipizzato atteso
|
||||
dall'indicizzazione e dal recall;
|
||||
- correzioni deliberate dal core, provenienza e citazioni, che devono consumare
|
||||
e aggiornare coerentemente la nuova rappresentazione;
|
||||
- contratto documentato e test del percorso completo: modifica del testo visibile,
|
||||
consolidamento, contenuto indicizzato e successivo utilizzo da parte del core.
|
||||
|
||||
Le Evidence esistenti devono essere convertite esplicitamente al nuovo formato
|
||||
e reindicizzate, verificando il mantenimento del contenuto e degli identificatori.
|
||||
La fase di sviluppo permette un passaggio unico; non è richiesto mantenere due
|
||||
formati di authoring concorrenti. Una conversione non rappresentabile fedelmente
|
||||
va segnalata. Si preserva il modello tipizzato interno dove possibile, per contenere
|
||||
la modifica nei componenti che dipendono dal documento senza ridisegnare le fasi
|
||||
del workflow NL→SQL.
|
||||
|
||||
Estendere i contratti in `harness/tht/evidence/` per distinguere fonte corrente,
|
||||
dichiarazione manuale e documento originario. La dichiarazione viene gestita
|
||||
dall'applicazione insieme all'unità locale; chi scrive il Markdown non deve
|
||||
creare un file sorgente separato o gestire hash ed estratti. I campi per kind
|
||||
mantengono la validazione deterministica, senza attribuirle una verifica della
|
||||
verità della regola. Aggiornare il glossario e il contratto canonico con il codice.
|
||||
|
||||
Riutilizzare raffinamento, parser, renderer e validazione esistenti, distinguendo
|
||||
la working tree locale persistente dagli snapshot acquisiti e adattando il formato al testo Markdown
|
||||
editabile come fonte autorevole, senza duplicazione nascosta del contenuto umano.
|
||||
Documentare posizione dei file, campi richiesti e un esempio per la creazione.
|
||||
L'applicazione acquisisce le draft e
|
||||
conserva il risultato in file locali persistenti. Le mutazioni aggiornano contenuto
|
||||
canonico, presentazione Markdown e manifest; le scritture sono serializzate per
|
||||
workspace e controllano la versione corrente del record; una modifica concorrente
|
||||
non viene risolta sovrascrivendo silenziosamente il contenuto altrui.
|
||||
|
||||
Il salvataggio non richiede commit, push o un database condiviso con lo specialista.
|
||||
L'archivio locale è distinto dalla materializzazione runtime ricostruita da Git e
|
||||
dal corpus derivato. Consolidamento e preprocessing acquisiscono i contenuti locali
|
||||
curati; il core consulta soltanto il corpus attivo validato. Clear preserva i file
|
||||
e la ricostruzione dell'indice riparte da essi, senza sovrascriverli
|
||||
con nuove copie delle draft originali.
|
||||
|
||||
La persistenza conserva la cura manuale e le esclusioni necessarie a impedire la
|
||||
ricomparsa delle unità eliminate. La rigenerazione confronta le proposte con tale
|
||||
stato: assegnare un nuovo ID a un contenuto derivato non deve essere un modo per
|
||||
riattivarlo automaticamente aggirando una cancellazione. Le nuove proposte e i
|
||||
conflitti restano distinti dal corpus già approvato e attivo.
|
||||
|
||||
Verificare con archivi locali temporanei draft esterne e raffinamento, creazione
|
||||
manuale, cambiamento di significato
|
||||
con provenienza corretta, round trip del formato canonico, aggiornamento del manifest,
|
||||
cancellazione, conflitto fra scritture e retry. La validazione di un estratto
|
||||
presente nella fonte non viene usata come prova automatica di supporto semantico.
|
||||
|
||||
### E2 — Pagina amministrativa e consolidamento manuale
|
||||
|
||||
Esporre API amministrative per elenco completo, filtri, dettaglio, mutazioni ed
|
||||
esito delle operazioni. Il backend applica autorizzazioni e isolamento, poi chiama
|
||||
il servizio di authoring del harness. Realizzare la pagina autonoma nell'AppShell
|
||||
con provenienza leggibile, percorsi effettivi dei file sull'host e istruzioni per
|
||||
modificarli con editor esterni, consolidarli e completare commit/push manualmente.
|
||||
Il comando di consolidamento acquisisce aggiunte, modifiche e rimozioni locali
|
||||
tramite lo stesso servizio. Nessun editor, form di contenuto o
|
||||
trasferimento file web è richiesto in R0; non serve una sessione del core.
|
||||
|
||||
Evolvere lo stage interno `runEvidenceStage` e il percorso harness
|
||||
`tht preprocess evidence` per attivare il contenuto canonico locale autorizzato.
|
||||
Il salvataggio non avvia una riacquisizione HTTP/S3, una nuova estrazione dalle
|
||||
Source Evidence o una scansione DWH. Il nuovo comando manuale Evidence riusa questo
|
||||
stage interno senza richiedere un preprocessing completo per ogni modifica.
|
||||
|
||||
Preparare e verificare il candidato Evidence prima di attivarlo. L'indicizzazione
|
||||
e la rimozione devono essere circoscritte al workspace e alle generazioni Evidence
|
||||
interessate nella collezione Reference condivisa. Preservare Schema, relazioni,
|
||||
LSH e Memory: il salvataggio non usa Preprocessing Clear e non ricrea l'intera
|
||||
collezione. Se l'attivazione fallisce, mostrare l'esito parziale e rendere ripetibile
|
||||
il completamento della stessa modifica, senza chiedere una nuova approvazione.
|
||||
|
||||
Adeguare la ricerca perché consumi l'archivio locale aggiornato, senza richiedere
|
||||
commit della fonte o cambiare configurazioni estranee. Adeguare il calcolo della
|
||||
readiness: aggiornare Evidence non dichiara risolto un blocco
|
||||
di Schema o Catalog. Dopo un Clear, l'eventuale necessità di preprocessing completo
|
||||
rimane esplicita; il solo consolidamento non ricostruisce tutti i derivati mancanti.
|
||||
|
||||
Verificare che i percorsi mostrati portino ai file effettivi anche su installazioni
|
||||
Docker e che una modifica alla frase visibile sia acquisita senza editing di metadati
|
||||
tecnici. Verificare creazione/modifica/cancellazione con esito disponibile al core, errore
|
||||
di indicizzazione dopo persistenza, retry e isolamento delle altre componenti
|
||||
della collezione. Le successive elaborazioni devono usare il contenuto corrente
|
||||
senza recuperare unità cancellate. Verificare le correzioni deliberate dalla sessione
|
||||
stessa, senza aggiungere prove di CRUD amministrativo concorrente al core. Un
|
||||
problema preesistente di Catalog deve continuare a impedire una falsa readiness.
|
||||
Verificare che errori strutturali impediscano l'attivazione e producano indicazioni
|
||||
correggibili, che il comando sia rieseguibile e che non esegua operazioni Git.
|
||||
Verificare che file modificati senza consolidamento e tentativi falliti non cambino
|
||||
il contenuto usato dal core né combinino versioni differenti di testo e indice.
|
||||
Provare la sequenza documentata di commit/push con repository temporanei e remoto
|
||||
locale, verificando l'inclusione delle cancellazioni e dei metadati necessari.
|
||||
|
||||
### E3 — Importazione, refresh esplicito e conflitti con le fonti
|
||||
|
||||
Fornire un percorso di importazione locale per le origini già supportate,
|
||||
conservando contenuto acquisito e provenienza remota. Uniformare il passaggio alle
|
||||
unità canoniche: i documenti HTTP/S3 oggi normalizzati genericamente devono diventare
|
||||
file locali editabili. Le unità importate restano gestibili senza credenziali di
|
||||
scrittura sui server fonte.
|
||||
|
||||
L'azione amministrativa di aggiornamento delle fonti riacquisisce il contenuto e
|
||||
confronta le impronte con quanto già acquisito. Per le unità curate interessate,
|
||||
prepara il confronto con le proposte risultanti senza sostituire la dichiarazione
|
||||
manuale attiva. Questa protezione non dipende dalla capacità del modello di
|
||||
riconoscere ogni contraddizione semantica. La scelta dell'amministratore usa poi
|
||||
lo stesso salvataggio con attivazione; fonti invariate non richiedono nuova cura.
|
||||
|
||||
Verificare con origini controllate che la riacquisizione avvenga soltanto su richiesta,
|
||||
che un errore di accesso non venga scambiato per una cancellazione e che consolidamento/recall
|
||||
non chiamino i connettori di acquisizione remota. Verificare aggiornamento di una
|
||||
fonte collegata a una correzione manuale, permanenza della versione curata, decisione
|
||||
di sostituzione e mancata ricomparsa automatica delle unità eliminate.
|
||||
|
||||
La lettura può essere consegnata come incremento intermedio di E2, ma il progetto
|
||||
è completo soltanto con CRUD, attivazione e gestione delle origini previste. X1 nel
|
||||
piano comune collega le proposte provenienti dai conflitti con Memory e verifica
|
||||
che raggiungano questi stessi servizi con autorizzazioni ed esiti coerenti.
|
||||
|
||||
## Criteri di completamento
|
||||
|
||||
- Tutte le unità sono raggiungibili mediante elenco e filtri, senza una sessione.
|
||||
- La pagina mostra cartella e percorso effettivo sull'host per ogni unità. Markdown,
|
||||
campi richiesti ed esempi permettono creazione e modifica con editor esterni;
|
||||
i dati invalidi non vengono attivati e gli errori indicano il file da correggere.
|
||||
- Una draft prodotta fuori dall'installazione può essere acquisita, raffinata e
|
||||
conservata localmente senza accesso dello specialista a PostgreSQL.
|
||||
- Creazione, modifica e ritiro aggiornano l'archivio locale e il corpus usato dal core;
|
||||
non richiedono commit/push nel repository delle fonti.
|
||||
- Una Evidence può essere creata senza documento esterno; la dichiarazione manuale
|
||||
è riconoscibile e il documento originario di una correzione non è mostrato come
|
||||
supporto di un'affermazione che non contiene.
|
||||
- Una modifica o cancellazione completata resta valida dopo una nuova preparazione
|
||||
e reindicizzazione; non rimangono frammenti ricercabili della versione rimossa.
|
||||
- Una fonte aggiornata in conflitto con la cura manuale non sostituisce l'Evidence
|
||||
attiva: il confronto resta disponibile all'amministratore fino alla sua decisione.
|
||||
- Il consolidamento manuale completa anche l'attivazione, senza un successivo `Publish`; l'esito
|
||||
distingue operazione in corso, completata ed eventuali errori con retry.
|
||||
- Il core usa soltanto l'ultimo corpus consolidato valido. File in lavorazione o
|
||||
consolidamenti falliti non diventano disponibili attraverso letture dirette.
|
||||
- Dopo una modifica completata, le successive elaborazioni recuperano il contenuto
|
||||
corrente. Dopo una cancellazione completata non recuperano l'unità rimossa.
|
||||
Nessuna delle due operazioni riscrive decisioni, artefatti o SQL già prodotti.
|
||||
- Clear e ricostruzione degli indici preservano le Evidence canoniche locali,
|
||||
incluse le correzioni e le esclusioni dovute a cancellazioni.
|
||||
- Le correzioni originate da conflitti con Memory raggiungono lo stesso percorso
|
||||
autorevole delle modifiche amministrative e mostrano il proprio stato di pubblicazione.
|
||||
- Le origini senza scrittura dispongono di un percorso utilizzabile verso l'authoring.
|
||||
- Le fonti esterne vengono riacquisite solo su richiesta dell'amministratore;
|
||||
il consolidamento e il recall usano il contenuto locale già acquisito.
|
||||
- API e pagina applicano accesso amministrativo e isolamento dei workspace.
|
||||
- Le istruzioni identificano working tree e file effettivi; il seguito manuale
|
||||
include verifica del diff, commit e push. Nessun watcher o comando Git automatico
|
||||
è introdotto. L'esito distingue disponibilità locale e trasferimento al remoto.
|
||||
- Il salvataggio delle Evidence preserva Memory, Schema, relazioni, LSH e Catalog
|
||||
Metadata; non elimina blocchi di readiness estranei all'aggiornamento Evidence.
|
||||
@@ -0,0 +1,261 @@
|
||||
# Amministrazione di Memory ed Evidence
|
||||
|
||||
Data del piano: 2026-09-08. Aggiornamento 2026-09-09: M1–M3, E1–E3 e X1
|
||||
implementati. Risultati e limiti della verifica finale sono raccolti nel
|
||||
[rapporto X1](2026-09-09-archive-repair-x1-validation.md).
|
||||
|
||||
La [revisione di semplicità](2026-09-08-memory-evidence-simplification-review.md)
|
||||
riesamina tutte le decisioni Q1–Q15 alla luce degli ultimi chiarimenti del
|
||||
proprietario e confronta le conseguenze con il piano precedente. Per Evidence R0
|
||||
sono scelti file Markdown locali, editor esterni e consolidamento manuale con
|
||||
controllo della struttura, seguito da diff, commit e push dell'operatore. La pagina
|
||||
deve indicare chiaramente percorsi e comandi. Le restanti semplificazioni sono
|
||||
confermate. Il cambio del formato richiede adeguare il sottosistema core Evidence,
|
||||
convertire i file e reindicizzare; E1 precede la pagina. Il controllo umano usa
|
||||
lo stato Git nel terminale, con diff delle righe quando serve, senza una UI dedicata.
|
||||
Si ignora la contemporaneità fra amministrazione e core. Lo
|
||||
specialista scrive draft indipendentemente dall'installazione; il sistema le
|
||||
raffina e le conserva localmente. La proposta aggiornata usa file canonici locali
|
||||
per le Evidence e toglie commit/push automatici dal CRUD; questa revisione tecnica di Q11
|
||||
sostituisce la raccomandazione precedente ed è stata attuata negli incrementi E1–E3.
|
||||
|
||||
## Obiettivo e decisioni del proprietario
|
||||
|
||||
L'amministratore deve poter accedere in qualsiasi momento alle Memory e alle Evidence
|
||||
registrate, cercarle, filtrarle, aprirle, crearle, modificarle e cancellarle. L'accesso
|
||||
non richiede una sessione del core o una fase del workflow.
|
||||
|
||||
Il lavoro è diviso in due progetti autonomi:
|
||||
|
||||
- [Memory management](2026-09-08-memory-management.md);
|
||||
- [Evidence management](2026-09-08-evidence-management.md).
|
||||
|
||||
I progetti condividono l'esperienza di gestione e i componenti appropriati, mantenendo
|
||||
distinti i contenuti, le regole di validazione e i percorsi di persistenza.
|
||||
|
||||
### Collocazione dei due accessi
|
||||
|
||||
L'ordine previsto nell'accordion Administration è:
|
||||
|
||||
```text
|
||||
Administration
|
||||
Database management
|
||||
Memory management
|
||||
Evidence management
|
||||
────────────────────
|
||||
Workspace management
|
||||
Pi management
|
||||
```
|
||||
|
||||
Memory management ed Evidence management sono due voci autonome, allo stesso livello
|
||||
di Database management. «Sotto» indica soltanto la posizione fisica nella navigazione.
|
||||
Non sono sottopagine, tab o funzionalità di Database management. Ciascuna apre la
|
||||
propria pagina e possiede il proprio stato di navigazione.
|
||||
|
||||
### Decisioni già acquisite sulla Memory
|
||||
|
||||
- La Memory serve a migliorare schema linking e generazione SQL di domande future.
|
||||
- Il perimetro comprende chiarimenti di dominio riutilizzabili, regole corrette per
|
||||
join, filtri e aggregazioni, domande risolte consultabili ed errori da evitare
|
||||
quando il motivo è stato compreso e approvato. Le scelte occasionali non diventano
|
||||
regole generali; possono restare nel contesto di un exemplar.
|
||||
- Il formato della memory card è allineato per analogia a quello delle Evidence;
|
||||
origine e dominio restano separati. Le Memory non entrano nel canone Evidence.
|
||||
- La gestione avviene tramite CRUD e form interni a ThothII.
|
||||
- L'evoluzione del modulo Memory è interna a ThothII, riusando l'infrastruttura
|
||||
dell'installazione e senza adottare un framework esterno per governarne il comportamento.
|
||||
- Il progetto comprende ricerca semantica e lessicale ibrida in Qdrant, filtri
|
||||
sull'ambito e collegamenti espliciti fra card percorsi dal core. Non introduce
|
||||
un database a grafi dedicato e non rinvia il grafo a una successiva sperimentazione.
|
||||
- PostgreSQL, già presente nell'installazione, è l'archivio autorevole di card,
|
||||
collegamenti e dipendenze, in tabelle proprie del modulo Memory. Sostituisce il
|
||||
registro JSONL; Qdrant è una proiezione rigenerabile, con sincronizzazione esplicita.
|
||||
- I collegamenti sono proposti e approvati insieme alle card nel riepilogo finale
|
||||
e gestibili manualmente da Administration. Cancellare una card elimina anche i
|
||||
collegamenti che la coinvolgono, conservando le altre card.
|
||||
- Gli exemplar `solved_question` usano il formato card con consumo consultativo.
|
||||
- Il core prepara durante il lavoro un riepilogo finale modificabile delle nuove
|
||||
Memory e degli aggiornamenti proposti. Il reviewer seleziona cosa salvare; la
|
||||
cancellazione resta nel CRUD amministrativo.
|
||||
- Le Memory vengono proposte nei gate pertinenti: chiarimenti all'inizio, regole di
|
||||
collegamento nello schema linking e regole di calcolo durante la costruzione SQL.
|
||||
Le approvazioni sono integrate nei gate, senza una domanda separata per ogni card.
|
||||
- Una modifica sostituisce il contenuto corrente: non è richiesta una cronologia
|
||||
aggiuntiva delle revisioni delle Memory o una ricostruibilità storica dedicata.
|
||||
- Se un riferimento allo schema rende una Memory inutilizzabile, il proprietario
|
||||
sceglie la cancellazione anziché lo stato «Needs review». Dopo una sincronizzazione
|
||||
riuscita dello schema fisico, il backend comunica gli elementi rimossi al modulo
|
||||
Memory, che cancella le card dipendenti e le proiezioni. La relazione fra card ed
|
||||
elementi dello schema deve essere strutturata; cleanup del Catalog ed errori di
|
||||
connessione non sono prove di rimozione fisica.
|
||||
- I conflitti fra Memory ed Evidence si risolvono con azioni chiuse, specifiche e
|
||||
accompagnate dal contenuto risultante. La scelta alimenta una correzione degli
|
||||
archivi attraverso i rispettivi percorsi, con stato di pubblicazione esplicito;
|
||||
è sempre possibile dichiarare inadeguate le proposte e richiederne la riformulazione.
|
||||
- La verifica usa test funzionali automatici e regressioni per casi concreti; non
|
||||
promette un miglioramento qualitativo generale o un benchmark con/senza Memory.
|
||||
- Le sessioni esistenti non vincolano il design. Il loro azzeramento durante lo
|
||||
sviluppo, se necessario, è autorizzato; non è un'operazione eseguita da questi documenti.
|
||||
|
||||
La decisione di non conservare uno storico riguarda le Memory. Non modifica
|
||||
automaticamente il contratto di authoring e pubblicazione delle Evidence.
|
||||
|
||||
### Salvataggio delle Evidence
|
||||
|
||||
In Q12 il proprietario rifiuta la separazione fra `Save draft` e `Publish`.
|
||||
La scelta successiva dell'editor esterno sostituisce il Save della form con il
|
||||
salvataggio dei file e un comando manuale di consolidamento: verifica la struttura,
|
||||
indica le correzioni necessarie e, se valido, aggiorna metadati, corpus e indice.
|
||||
Acquisisce anche aggiunte e cancellazioni. Segue il controllo del diff con commit e
|
||||
push manuali dell'operatore; non sono previsti watcher, Git automatico o un editor
|
||||
in Evidence management. La pagina mostra cartella, percorsi sull'host e comandi;
|
||||
il [piano Evidence](2026-09-08-evidence-management.md) specifica la sequenza.
|
||||
Il consolidamento attiva localmente il contenuto; un push mancante o fallito lascia
|
||||
il trasferimento al remoto da completare manualmente. L'ultimo chiarimento
|
||||
elimina il requisito di aggiornare sessioni aperte a seguito di modifiche
|
||||
amministrative: durante tali modifiche il core è fermo o la contemporaneità può
|
||||
essere ignorata. Rimangono le correzioni deliberate dalla sessione stessa.
|
||||
La review di Q11 distingue le draft dello specialista dalle Evidence raffinate
|
||||
locali; raccomanda di preservare le prime e gestire le seconde su file persistenti,
|
||||
senza PostgreSQL condiviso o scritture automatiche nel repository delle fonti.
|
||||
In Q13 è approvata
|
||||
la precedenza della correzione manuale quando una fonte aggiornata la contraddice:
|
||||
resta attiva fino alla risoluzione esplicita del confronto in Evidence management.
|
||||
Le Evidence cancellate non ricompaiono automaticamente durante la rigenerazione.
|
||||
Q14 consente di crearle senza documento esterno, in R0 tramite un nuovo Markdown: una
|
||||
dichiarazione manuale sostiene il testo corrente, con l'eventuale documento
|
||||
originario conservato come provenienza distinta. Q15 limita la riacquisizione
|
||||
delle fonti esterne a una richiesta esplicita dell'amministratore; il normale
|
||||
salvataggio e il recall usano il contenuto già acquisito.
|
||||
L'[ADR 0019](../adr/0019-author-evidence-in-app-with-automatic-activation.md) registra
|
||||
l'evoluzione del contratto, ancora da implementare.
|
||||
|
||||
## Stato verificato nel repository
|
||||
|
||||
`frontend/src/shell/AppShell.tsx` contiene Administration con Database management,
|
||||
Workspace management e Pi management. Non contiene le due pagine richieste.
|
||||
|
||||
Il modulo Memory espone già comandi CLI per elenco, dettaglio, aggiornamento,
|
||||
cancellazione e ricerca, ma manca una superficie CRUD amministrativa web.
|
||||
Il riepilogo di una sessione mostra soltanto le Memory collegate alla sessione.
|
||||
Il [contratto attuale della Memory](../gestione-memory.md) descrive registro JSONL
|
||||
canonico e indice Qdrant derivato.
|
||||
|
||||
Le Evidence hanno già un percorso di consultazione e modifica dei documenti nel
|
||||
repository di authoring, descritto in [Evidence: sources, preparation, and review](../evidence.md).
|
||||
Manca una pagina amministrativa per queste operazioni dentro ThothII. Il contratto
|
||||
attuale prevede che ThothII legga e pubblichi il repository, senza modificarlo,
|
||||
creare commit o eseguire push: l'editing amministrativo richiede evolvere questo
|
||||
confine, come esplicitato nel progetto Evidence.
|
||||
|
||||
## Esperienza comune
|
||||
|
||||
L'amministratore lavora nell'interfaccia operativa esistente, con una lista densa
|
||||
e leggibile e un'area di dettaglio. Si riusano tema, controlli, focus e navigazione
|
||||
già definiti in PRODUCT.md e DESIGN.md.
|
||||
|
||||
- Selettore di workspace, ricerca testuale, filtri combinabili, ordinamento e paginazione.
|
||||
- Elenco completo dei record persistiti, indipendente dalla disponibilità della
|
||||
ricerca semantica. Una ricerca per similarità può affiancarlo, senza limitarlo ai
|
||||
pochi risultati del recall del core.
|
||||
- Apertura del contenuto completo, dell'ambito di applicazione e della provenienza.
|
||||
- Creazione e modifica Memory mediante form; per Evidence R0, percorsi ed esempi
|
||||
Markdown per editor esterni, consolidamento e seguito Git manuali.
|
||||
- Cancellazione con indicazione precisa dell'oggetto e del suo effetto; per Evidence
|
||||
R0 la rimozione del file è acquisita dal consolidamento.
|
||||
- Stato esplicito di salvataggio e disponibilità per il core, con recupero dagli errori.
|
||||
- Filtri e posizione nell'elenco conservati quando si apre e si chiude un record.
|
||||
- Controlli utilizzabili da tastiera; stato vuoto, nessun risultato e indisponibilità
|
||||
del servizio distinguibili. Chrome in inglese, contenuti nella lingua del workspace.
|
||||
|
||||
Le due pagine non dipendono dalla selezione di un database in Database management.
|
||||
Eventuali filtri su tabelle e colonne usano riferimenti al catalogo quando disponibili;
|
||||
la loro assenza non impedisce di consultare i contenuti registrati.
|
||||
|
||||
Componenti condivisibili: barra di ricerca e filtri, lista, paginazione, struttura
|
||||
del dettaglio, campi comuni della card, provenienza e feedback delle operazioni.
|
||||
Form Memory, istruzioni di manutenzione Evidence, autorizzazione, validazione, pubblicazione e
|
||||
persistenza rimangono responsabilità dei rispettivi moduli. Il riuso del frontend
|
||||
non introduce un archivio canonico unico per Memory ed Evidence.
|
||||
|
||||
## Confini e integrazione
|
||||
|
||||
Entrambe le pagine appartengono ad Administration e devono applicare il controllo
|
||||
amministrativo anche nelle API. La collocazione visiva non assegna automaticamente
|
||||
le autorizzazioni di Database management ai nuovi moduli.
|
||||
|
||||
Il progetto Memory può essere consegnato senza attendere il progetto Evidence.
|
||||
I componenti comuni si estraggono quando servono ai flussi reali di entrambi.
|
||||
La verifica finale congiunta copre ordine della navigazione, accesso indipendente,
|
||||
filtri, percorsi di manutenzione e feedback coerenti, isolamento fra workspace e assenza di effetti
|
||||
incrociati fra i due domini.
|
||||
|
||||
La separazione fra Reference Vector Collection e Memory Vector Collection rimane
|
||||
quella dell'[ADR 0017](../adr/0017-separate-reference-vectors-from-runtime-memory.md).
|
||||
Un'operazione amministrativa sulle Evidence non cancella le Memory; una cancellazione
|
||||
di Memory non elimina Evidence, Schema o metadati del database.
|
||||
|
||||
## Piano esecutivo dei due progetti
|
||||
|
||||
Il riesame mantiene i requisiti funzionali Q1–Q15 e semplifica le scelte tecniche
|
||||
secondo le condizioni descritte sopra. L'ordine di lavoro parte dalla Memory e
|
||||
riusa poi i componenti effettivamente comuni per Evidence management. Le API e
|
||||
il coordinamento delle scritture attuano questi vincoli; la distinzione fra draft
|
||||
esterne e archivio locale sostituisce l'ipotesi di un unico archivio Git da modificare.
|
||||
|
||||
| Ordine | Incremento | Risultato verificabile | Dipendenze |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | M1 — Archivio e CRUD Memory | PostgreSQL autorevole, API e pagina con elenco completo, filtri, form e cancellazione; collegamenti e dipendenze persistiti, proiezioni aggiornate o invalidate | Nessuna dipendenza dal progetto Evidence |
|
||||
| 2 | M2 — Ricerca Memory | Ricerca ibrida con filtri ed espansione limitata dei collegamenti; risultati coerenti con il contenuto corrente | M1 |
|
||||
| 3 | M3 — Memory nel workflow | Riepilogo finale, uso delle categorie nei gate e cancellazione dopo sincronizzazione fisica riuscita | M1 e M2 |
|
||||
| 4 | E1 — Preparazione e archivio Evidence | Draft esterne, raffinamento del sistema, file canonici locali persistenti e protezione delle correzioni/cancellazioni | Q11–Q15 riesaminate; non richiede il runtime Memory |
|
||||
| 5 | E2 — Manutenzione e consolidamento Evidence | Pagina con percorsi dei Markdown; comando manuale di verifica e attivazione; istruzioni per diff, commit e push | E1 |
|
||||
| 6 | E3 — Fonti e conflitti di aggiornamento | Importazione delle origini supportate, refresh esplicito, confronto con le correzioni manuali | E1 ed E2 |
|
||||
| 7 | X1 — Integrazione finale | Correzioni persistenti dei conflitti Memory/Evidence e verifica congiunta delle due pagine | M3 ed E3 |
|
||||
|
||||
E1–E3 sono un progetto separato: la sequenza è l'ordine operativo scelto per questa
|
||||
consegna, non una dipendenza tecnica dal modulo Memory. Il CRUD Memory è utilizzabile
|
||||
come primo incremento; M2 e M3 restano obbligatori nel progetto attuale. La correzione
|
||||
completa dei conflitti fra i due archivi si considera consegnata soltanto con X1.
|
||||
|
||||
### Responsabilità di implementazione
|
||||
|
||||
- Il harness possiede contratti, persistenza e operazioni dei moduli Memory ed
|
||||
Evidence. Il backend applica autorizzazioni, espone le API e orchestra le
|
||||
operazioni; non introduce una seconda implementazione delle stesse scritture.
|
||||
- Il Metadata Catalog rimane responsabilità del backend. Una sincronizzazione
|
||||
fisica riuscita chiama la pulizia Memory nello stesso flusso, con gli elementi
|
||||
effettivamente rimossi nell'ambito controllato e un recupero dopo interruzione.
|
||||
La pulizia non dipende dalla UI e non richiede un bus di eventi.
|
||||
- Le pagine condividono controlli di consultazione e feedback; logica dei kind, fonte autorevole e
|
||||
attivazione rimangono nei rispettivi moduli. L'AppShell ospita le due voci autonome
|
||||
nell'ordine concordato.
|
||||
- Le modifiche coordinate hanno gestione esplicita di errori e retry. I controlli
|
||||
sulla versione corrente impediscono sovrascritture inconsapevoli senza richiedere
|
||||
uno storico delle Memory. I retry non duplicano card o collegamenti. Il normale
|
||||
salvataggio è sequenziale, con un esito persistente da recuperare se incompleto;
|
||||
non richiede nuovi worker, code generiche o coordinamento delle sessioni aperte.
|
||||
|
||||
### Verifiche e chiusura della consegna
|
||||
|
||||
Ogni incremento esegue i test delle operazioni che cambia e i controlli dei layer
|
||||
coinvolti: pytest/ruff per il harness, vitest e typecheck per backend/frontend.
|
||||
Le pagine sono verificate anche nel browser per navigazione, filtri, form, errori
|
||||
e uso da tastiera. I contratti e i test specifici sono nei due piani di progetto.
|
||||
|
||||
X1 verifica sia i conflitti che correggono Memory sia quelli che correggono Evidence,
|
||||
inclusi utente privo dell'autorizzazione necessaria, proposta rifiutata, errore di
|
||||
attivazione e retry. Il gate deve mostrare lo stato reale dell'archivio: la sola
|
||||
risoluzione della domanda corrente non dimostra che la correzione sia persistita.
|
||||
La verifica congiunta copre inoltre isolamento dei workspace, ordine dei link e
|
||||
assenza di cancellazioni incrociate.
|
||||
|
||||
I contratti correnti vengono aggiornati insieme al relativo codice. Alla fine si
|
||||
aggiornano PROJECT_STATE.md e documentazione operativa e si esegue la build strict.
|
||||
La verifica della generazione con un modello reale rimane distinta dai test
|
||||
deterministici; non si promette un benchmark generale di miglioramento qualitativo.
|
||||
|
||||
Gli incrementi approvati sono implementati e disponibili nel Docker locale.
|
||||
I rapporti di validazione distinguono i test deterministici, i servizi reali e le
|
||||
prove con il modello configurato. Le verifiche sintetiche non modificano la
|
||||
conoscenza PSD; la valutazione dei contenuti reali rimane una decisione del reviewer.
|
||||
@@ -0,0 +1,253 @@
|
||||
# Revisione di semplicità: Memory ed Evidence
|
||||
|
||||
Data: 2026-09-08. Stato: archivio locale Markdown, editor esterni e consolidamento
|
||||
manuale con seguito Git scelti per la release 0; conseguenze esplicitate,
|
||||
restanti semplificazioni confermate, chiariti impatto core e controllo Git.
|
||||
Nessuna modifica applicativa.
|
||||
|
||||
## Condizioni che guidano la revisione
|
||||
|
||||
Chi amministra il sistema è competente e deve vedere chiaramente cosa produce ogni
|
||||
azione. Durante il CRUD amministrativo di Memory ed Evidence si può assumere che
|
||||
non ci siano attività core in corso; la loro eventuale contemporaneità non è un
|
||||
caso da supportare con meccanismi dedicati.
|
||||
|
||||
Lo specialista di contesto può essere una persona diversa da chi gestisce
|
||||
l'installazione. Scrive le draft delle Evidence senza dover accedere a PostgreSQL,
|
||||
amministrarlo o disporre della stessa installazione. Il flusso fondamentale resta:
|
||||
|
||||
1. Lo specialista scrive e consegna le draft in documenti accessibili al sistema.
|
||||
2. Il sistema le acquisisce e le raffina in Evidence strutturate.
|
||||
3. Il sistema conserva localmente le Evidence per consultazione e manutenzione.
|
||||
|
||||
La proposta avanzata durante la revisione di usare PostgreSQL come archivio
|
||||
autorevole anche delle Evidence è ritirata. Confrontava il costo del solo CRUD
|
||||
interno, senza rappresentare adeguatamente l'autonomia di chi produce le fonti.
|
||||
Un database dietro un'interfaccia non richiederebbe di per sé accesso SQL agli autori,
|
||||
né un database condiviso; questo però non risolve da solo il flusso di redazione e
|
||||
consegna esterno. Non propongo di introdurre tale dipendenza.
|
||||
|
||||
## Archivio locale delle Evidence accettato dopo il chiarimento
|
||||
|
||||
Il proprietario ha accettato i file locali e richiede una gestione facile da trovare
|
||||
e usare anche per uno specialista non tecnico. Il formato di lavoro è Markdown;
|
||||
JSONL non è una superficie di gestione delle Evidence. Il proprietario ha scelto
|
||||
editor esterni per la release 0, chiedendo di indicare chiaramente dove sono i file.
|
||||
|
||||
| Contenuto | Responsabile | Conservazione e uso |
|
||||
| --- | --- | --- |
|
||||
| Draft originali | Specialista di contesto | File o repository delle fonti, redigibili e consegnabili indipendentemente dall'installazione |
|
||||
| Evidence raffinate e correzioni locali | Sistema e persone autorizzate alla manutenzione del contenuto | File Markdown in un archivio locale persistente dell'installazione, consultabili dall'applicazione e modificabili con editor esterni |
|
||||
| Indice di ricerca | Sistema | Qdrant, ricostruibile dalle Evidence locali correnti |
|
||||
|
||||
Questa è una revisione della parte tecnica di Q11: distingue l'autorità delle draft
|
||||
esterne dall'archivio delle Evidence raffinate usate dalla singola installazione.
|
||||
Il repository delle fonti rimane utilizzabile; il consolidamento delle Evidence
|
||||
locali non esegue commit o push e non richiede un PostgreSQL condiviso. Il seguito
|
||||
manuale ora richiesto comprende controllo del diff, commit e push nel repository
|
||||
che contiene i file curati. L'archivio è una working tree persistente; draft e unità
|
||||
curate possono stare nello stesso repository, mantenendo distinta la loro funzione.
|
||||
|
||||
Le conseguenze devono essere esplicite. Una correzione locale cambia ciò che usa
|
||||
quell'installazione e non viene rispedita automaticamente allo specialista o ad
|
||||
altre installazioni. I file restano trasferibili per un passaggio esplicito; non
|
||||
si costruisce una sincronizzazione bidirezionale. L'archivio locale va conservato
|
||||
e incluso nelle copie di sicurezza: dopo una correzione non è più un semplice
|
||||
output eliminabile e rigenerabile dalle draft senza perdita di lavoro.
|
||||
|
||||
Memory mantiene PostgreSQL locale come archivio già concordato. Le due pagine
|
||||
restano separate e riusano controlli comuni; la scelta della persistenza segue il
|
||||
flusso di produzione dei rispettivi contenuti.
|
||||
|
||||
## Gestione della release 0: editor esterni scelti
|
||||
|
||||
Il proprietario sceglie il proprio editor sul Mac o PC, oppure vim, nano o
|
||||
equivalenti sul server. La proposta di editor applicativo è ritirata; non si
|
||||
integra una libreria di editing né si sviluppano form di contenuto Evidence.
|
||||
|
||||
`Evidence management` conserva lista, ricerca, filtri e dettaglio. Mostra la cartella
|
||||
del workspace e il percorso assoluto di ogni file, copiabile e risolto dalla
|
||||
configurazione effettiva. Indica l'host su cui si trova; con Docker mostra il percorso
|
||||
persistente accessibile sull'host. Le istruzioni distinguono draft originali e
|
||||
Evidence raffinate da manutenere e includono un esempio Markdown per crearne una.
|
||||
|
||||
Si modificano direttamente i file nell'archivio locale dell'installazione. Chi
|
||||
lavora su una copia sul proprio computer la riporta lì con i propri strumenti.
|
||||
Non sono richiesti upload/download web, nuove cartelle condivise o sincronizzazione.
|
||||
|
||||
Dopo aver salvato, aggiunto o rimosso file, l'operatore controlla lo stato Git,
|
||||
poi esegue un comando manuale di
|
||||
consolidamento: controlla la struttura attesa, segnala file e correzioni necessarie
|
||||
e, solo se i controlli passano, aggiorna metadati, corpus e indice. Il comando è
|
||||
rieseguibile dopo correzioni o errori tecnici. Seguono commit e
|
||||
push manuali, con le istruzioni della pagina e della documentazione operativa.
|
||||
Il core consulta solo l'ultimo corpus consolidato valido; i file in lavorazione
|
||||
e gli aggiornamenti falliti non devono introdurre contenuto parziale nella ricerca.
|
||||
La richiesta più recente sostituisce la proposta intermedia del pulsante
|
||||
`Apply file changes`; non servono un'esecuzione dalla UI, watcher o operazioni Git
|
||||
automatiche. Il salvataggio nell'editor da solo non aggiorna il recall. Il controllo
|
||||
dei file usa `git status --short` nel terminale; il normale `git diff` è disponibile
|
||||
per approfondire le righe cambiate, senza visualizzatore web o doppia revisione
|
||||
obbligatoria. Il comando riporta un breve riepilogo testuale delle modifiche.
|
||||
|
||||
Il Markdown locale deve essere realmente editabile: il testo visibile è autorevole,
|
||||
i campi richiesti sono documentati e i metadati derivati sono gestiti dal sistema.
|
||||
Il formato v3 attuale, che verifica il rendering contro una copia codificata del
|
||||
testo, va quindi adattato. Non basta indicare i percorsi dei file attuali e non si
|
||||
introduce un secondo archivio di scambio da sincronizzare. Questo comporta una
|
||||
modifica effettiva dei componenti core Evidence: parser, renderer, preparazione,
|
||||
validazione, normalizzazione e collegamento a indicizzazione/recall. E1 comprende
|
||||
nuova versione del contratto, conversione dei file esistenti e verifica del percorso
|
||||
completo; il formato interno tipizzato viene conservato dove possibile.
|
||||
|
||||
Creazione, modifica e cancellazione delle unità raffinate passano dai file e dallo
|
||||
stesso consolidamento. Un errore di accesso all'archivio non è una prova di
|
||||
cancellazione. Le correzioni approvate dal core continuano a chiamare direttamente
|
||||
il servizio di scrittura. Il proprietario ha confermato le restanti semplificazioni
|
||||
chiedendo di esplicitare impatto core e semplicità del controllo Git.
|
||||
Il [piano Evidence](2026-09-08-evidence-management.md#consolidamento-manuale-e-seguito-git--release-0)
|
||||
specifica controlli, comando previsto e sequenza Git. Dopo il consolidamento il
|
||||
contenuto è disponibile localmente; finché commit/push non sono completati, non è
|
||||
versionato/trasferito al remoto. Il sistema si affida alla disciplina dell'operatore
|
||||
e non tenta di completare o riparare automaticamente la sequenza Git.
|
||||
|
||||
## Conseguenze rispetto al piano precedente alla revisione
|
||||
|
||||
Il confronto riguarda il piano concordato prima del riesame: form strutturate per
|
||||
le unità, repository Git autorevole con scritture applicative e supporto alle
|
||||
modifiche amministrative durante sessioni aperte. Le funzionalità non erano ancora
|
||||
implementate: si confrontano due progetti, non una regressione già introdotta.
|
||||
|
||||
| Aspetto | Cosa cambia | Conseguenza pratica |
|
||||
| --- | --- | --- |
|
||||
| Gestione R0 delle Evidence | Editor esterno scelto al posto di editor e form nell'applicazione | Si usano strumenti già disponibili. La pagina indica i file; servono un Markdown realmente editabile, esempi e validazione in acquisizione. Si rinuncia alla guida e ai controlli durante la digitazione. |
|
||||
| Applicazione delle modifiche esterne | Salvare i file nell'archivio ed eseguire il consolidamento manuale | Una copia sul Mac o PC va riportata nell'archivio con gli strumenti dell'operatore. Fino al consolidamento riuscito la modifica non è disponibile al core. Gli errori strutturali indicano il seguito necessario. Non si sviluppano trasferimenti file web o watcher. |
|
||||
| Autorità delle Evidence raffinate | Archivio locale, distinto dalle draft esterne | Una correzione agisce su quell'installazione. Lo specialista che lavora alle draft e altre installazioni non la ricevono automaticamente. |
|
||||
| Cronologia e distribuzione Git | Controllo del diff, commit e push manuali dopo il consolidamento | Git conserva e trasferisce quanto l'operatore committa e pubblica. La sequenza non è imposta né completata dal sistema: se il push manca o fallisce, il core locale può già usare modifiche non trasferite. Non c'è rollback applicativo o gestione automatica dei conflitti Git. |
|
||||
| Ripristino dei dati | Le Evidence locali curate sono dati primari | Il backup deve comprenderle. Ricostruire tutto dalle sole draft recupererebbe la base, ma potrebbe perdere correzioni e cancellazioni locali; Clear deve preservare l'archivio. |
|
||||
| Attività core contemporanee | Non vengono più gestite le modifiche amministrative durante il lavoro core | Se avvengono comunque, non è garantita la coerenza della sessione in corso. Non si aggiornano contesti o SQL già prodotti. Le successive elaborazioni usano il contenuto aggiornato dopo il completamento dell'operazione. |
|
||||
| Salvataggio e indice | Operazione sequenziale con recupero minimo persistente | L'utente attende l'esito dell'indicizzazione. Un problema può richiedere Retry; il contenuto già salvato viene conservato e un esito incompleto non viene presentato come pieno successo. Il piano precedente già prevedeva questi esiti, non garantiva retry automatici. |
|
||||
| Pulizia Memory dopo sync | Chiamata diretta nel flusso esistente | Stesso effetto funzionale, con meno coordinamento interno. Rimangono il recupero dopo interruzione, i limiti dell'ambito controllato e l'esclusione di errori di connessione o cleanup del solo Catalog. |
|
||||
| Verifica semantica | Nessuna nuova valutazione generale o revisione obbligatoria a ogni Save | La responsabilità del significato resta allo specialista; i test verificano contratti e casi mirati. La validazione strutturale non garantiva la correttezza del dominio neppure nel piano precedente. |
|
||||
|
||||
Sono invariati il riepilogo Memory, le categorie ammesse, i gate esistenti, la
|
||||
ricerca ibrida e i collegamenti, le correzioni persistenti dei conflitti e la
|
||||
protezione delle modifiche manuali. Le fonti vengono aggiornate su richiesta come
|
||||
già concordato. Le scritture deliberate dal core stesso restano supportate tramite
|
||||
lo stesso servizio: l'assenza di amministrazione concomitante non le elimina.
|
||||
|
||||
Non è prevista una rinuncia alle capacità di ricerca o al contenuto delle Evidence.
|
||||
Conservare gli stessi contenuti tipizzati, ambiti e indicizzazione evita una perdita
|
||||
di qualità dovuta a un taglio di funzionalità, ma l'equivalenza del nuovo percorso
|
||||
deve essere verificata. Il formato Markdown e un editor più semplice non sono,
|
||||
da soli, una garanzia di qualità o di assenza di errori.
|
||||
|
||||
## Riesame di tutte le decisioni Q1–Q15
|
||||
|
||||
| Decisione | Esito della revisione | Approccio più semplice e conseguenza |
|
||||
| --- | --- | --- |
|
||||
| Q1 — Riepilogo Memory | Mantengo | Un riepilogo finale editabile, con selezione di cosa salvare. Nessuna approvazione ripetuta per ogni card durante la sessione. |
|
||||
| Q2 — Aggiunte e aggiornamenti | Mantengo | Mostrare contenuto risultante e record sostituito. La somiglianza non avvia fusioni automatiche; la cancellazione semantica resta esplicita nel CRUD. |
|
||||
| Q3 — Consumo nei gate | Mantengo | Usare i gate già previsti. Nessun nuovo percorso di approvazione per la sola consultazione di una Memory; exemplar consultativi. |
|
||||
| Q4 — Conflitti Memory/Evidence | Semplifico l'esecuzione | La scelta mostra quale archivio cambia e con quale testo. Chiamare lo stesso servizio di salvataggio del CRUD, con un esito unico; niente secondo sistema di pubblicazione. Le correzioni deliberate dal core restano un caso da supportare. |
|
||||
| Q5 — Dipendenze fisiche eliminate | Mantengo, con chiamata diretta | Alla fine della sincronizzazione fisica riuscita, chiamare la pulizia Memory nello stesso flusso. Mostrare le conseguenze nella conferma della sincronizzazione già esistente e il conteggio finale. Non introdurre bus di eventi o un nuovo controllo continuo del DWH. |
|
||||
| Q6 — Verifiche | Mantengo il perimetro limitato | CRUD, filtri, persistenza, cancellazioni, recupero dall'errore e casi mirati di ricerca. Nessuna valutazione qualitativa generale a ogni salvataggio, nessun secondo modello giudice obbligatorio. |
|
||||
| Q7 — Evoluzione interna | Mantengo | Riutilizzare componenti e servizi dell'installazione. Nessun framework esterno o ulteriore servizio per governare Memory. |
|
||||
| Q8 — Ibrido e collegamenti | Mantengo entrambe le capacità | Riutilizzare la ricerca ibrida; collegamenti in una lista modificabile ed espansione limitata nel core. Nessun database a grafi, editor visuale di grafi o deduzione automatica di una rete di relazioni. Le capacità restano nel progetto attuale. |
|
||||
| Q9 — PostgreSQL per Memory | Mantengo | Il database è già locale all'installazione; card, collegamenti e dipendenze restano coordinati. Qdrant è ricostruibile. Il flusso Memory non richiede un autore esterno indipendente. |
|
||||
| Q10 — Cura dei collegamenti | Mantengo | Gestirli nello stesso riepilogo e dettaglio della card. Cancellare una card elimina i collegamenti incidenti e conserva le altre card. |
|
||||
| Q11 — Archivio Evidence | Rivedo la soluzione tecnica | Draft esterne indipendenti e Evidence raffinate in file locali persistenti. Togliere commit/push dal CRUD. La modifica locale non aggiorna automaticamente la fonte dello specialista. La proposta PostgreSQL autorevole per Evidence è ritirata. |
|
||||
| Q12 — Save e sessioni aperte | Adatto agli editor esterni | Dopo il salvataggio dei file, un comando manuale consolida e attiva le modifiche; l'operatore completa poi commit/push. Nessun workflow editoriale aggiuntivo, watcher, aggiornamento delle sessioni aperte o modalità manutenzione. |
|
||||
| Q13 — Fonte cambiata e cura manuale | Mantengo, con confronto semplice | La correzione manuale prevale finché una persona decide altrimenti. Un cambiamento della fonte collegata rende disponibile il confronto; non serve dimostrare automaticamente una contraddizione semantica. Le cancellazioni non vengono annullate dalla rigenerazione. |
|
||||
| Q14 — Creazione manuale | Mantengo tramite file | Un nuovo Markdown secondo l'esempio documentato consente una Evidence manuale con provenienza dichiarata e senza documento esterno obbligatorio. Il flusso principale draft dello specialista → raffinamento locale rimane disponibile e indipendente. |
|
||||
| Q15 — Refresh delle fonti | Mantengo | Acquisizione e raffinamento delle fonti aggiornate su richiesta esplicita. Consolidamento e recall usano il contenuto locale; non cercano nuove versioni remote. |
|
||||
|
||||
Restano confermati due link autonomi sotto Database management, CRUD completo con
|
||||
filtri, assenza di storico aggiuntivo delle Memory e assenza di vincoli sulle
|
||||
sessioni di sviluppo già esistenti.
|
||||
|
||||
## Riduzioni trasversali del piano
|
||||
|
||||
**Un'operazione alla volta, con esito comprensibile.** Save per Memory e
|
||||
consolidamento manuale per Evidence validano e aggiornano l'indice in sequenza.
|
||||
L'interfaccia mostra operazione in corso,
|
||||
completata oppure errore con azione di recupero. Non espone un workflow editoriale
|
||||
di stati `draft`, `approved`, `published` per il normale CRUD. La draft dello
|
||||
specialista è il documento di ingresso della preparazione, non un secondo pulsante
|
||||
di salvataggio dell'editor delle unità locali.
|
||||
|
||||
**Recupero minimo dopo errore.** Se l'archivio è stato aggiornato ma Qdrant no, va
|
||||
detto e deve essere possibile riprovare, per Evidence rieseguendo il comando.
|
||||
Serve un'indicazione persistente del lavoro
|
||||
incompleto, sufficiente anche per ripulire una card già cancellata dopo un riavvio.
|
||||
La ricerca non deve usare contenuti rimossi o superati alla domanda successiva.
|
||||
Il piano non imponeva già una outbox o nuovi worker: la revisione rende esplicito
|
||||
che non sono richiesti né code generiche né sincronizzazioni continue.
|
||||
|
||||
**Pulizia schema diretta e ripetibile.** Il flusso esistente del Catalog può
|
||||
richiamare Memory dopo l'applicazione dello schema. Occorre coprire il crash fra
|
||||
le due scritture: conservare la pulizia pendente sul run oppure verificare di nuovo
|
||||
le dipendenze contro lo snapshot fisico riuscito e il suo ambito. Ricalcolare solo
|
||||
il nuovo diff perderebbe le rimozioni già applicate. La rimozione manuale di
|
||||
metadati Catalog o un errore di connessione non autorizzano a cancellare Memory.
|
||||
|
||||
**Nessuna gestione delle sessioni amministrate contemporaneamente.** Non progettare
|
||||
aggiornamenti a caldo, ripristino dei contesti già letti, invalidazione dello SQL,
|
||||
notifiche alle sessioni o generazioni aggiuntive per lettori paralleli. Rimangono le
|
||||
scritture esplicitamente richieste dalla sessione stessa: il riepilogo Memory e una
|
||||
correzione Evidence approvata chiamano il medesimo servizio e ne gestiscono l'esito
|
||||
prima di proseguire. Questo caso non richiede coordinare tutte le altre sessioni.
|
||||
|
||||
**Pagine essenziali.** Ricerca testuale, filtri e lista completa permettono di trovare
|
||||
i contenuti; la ricerca semantica appartiene anzitutto al core. Memory conserva le
|
||||
form; Evidence espone dettaglio, percorsi e istruzioni per la modifica esterna.
|
||||
Hash e manifest restano gestiti dal sistema. Si riusano i controlli di accesso
|
||||
esistenti; chi modifica i file necessita dei permessi sul relativo filesystem,
|
||||
senza accesso a PostgreSQL o un nuovo sistema generale di ruoli.
|
||||
|
||||
## Conseguenze delle azioni da rendere visibili
|
||||
|
||||
| Azione | Conseguenza da comunicare |
|
||||
| --- | --- |
|
||||
| Save riuscito | Il contenuto corrente è conservato ed è disponibile per le successive elaborazioni. |
|
||||
| Save con errore dell'indice | Il contenuto è conservato; la disponibilità alla ricerca non è completata. Retry completa il lavoro senza richiedere di riscrivere la modifica. |
|
||||
| Salvataggio nell'editor esterno | Cambia il file, ma non aggiorna il recall. Una copia esterna va prima riportata nell'archivio dell'installazione. |
|
||||
| Consolidamento Evidence | Acquisisce aggiunte, modifiche e cancellazioni locali; verifica la struttura e, se valida, aggiorna metadati e indice. Un errore indica cosa correggere; si riesegue il comando dopo la correzione o un errore tecnico. |
|
||||
| Commit e push manuali | Versionano e trasferiscono al repository remoto i file consolidati. Un errore Git si risolve manualmente; il consolidamento locale già riuscito non viene annullato. |
|
||||
| Delete di una Memory | La card e i collegamenti che la coinvolgono vengono rimossi; le altre card restano. |
|
||||
| Delete di una Evidence | L'unità locale non viene più usata né ricreata automaticamente; la draft originale e le altre unità derivate restano. |
|
||||
| Refresh sources | Si acquisiscono nuove versioni delle fonti e si preparano le Evidence interessate; le correzioni locali protette non vengono sovrascritte. |
|
||||
| Sincronizzazione fisica | Le Memory dipendenti da elementi effettivamente eliminati vengono cancellate; l'ambito e il conteggio dell'effetto sono visibili. |
|
||||
| Preprocessing Clear | Si eliminano i dati derivati previsti dal comando; le Evidence canoniche locali e le Memory rimangono. |
|
||||
|
||||
Non sono necessarie conferme ripetute su Save. Per le cancellazioni si usa una
|
||||
conferma concreta sull'oggetto e sulle conseguenze, integrando gli effetti nella
|
||||
conferma già presente quando l'azione è una sincronizzazione distruttiva.
|
||||
|
||||
## Cosa va comunque implementato
|
||||
|
||||
Il raffinamento locale e la scrittura di Markdown canonico/manifest esistono in
|
||||
`harness/tht/evidence/authoring.py`. Preparano e validano gli output prima della
|
||||
sostituzione con staging e rollback; non eseguono commit/push. Va separato il
|
||||
requisito di Git worktree dalla preparazione del contenuto e va integrata
|
||||
l'acquisizione delle draft esterne.
|
||||
|
||||
La materializzazione corrente in `backend/src/workspaces/evidence/materialization.ts`
|
||||
è invece ricostruita da una revisione Git: non è già l'archivio locale scrivibile
|
||||
proposto. Il renderer e il preprocessing devono consumare il nuovo archivio
|
||||
persistente. Una modifica locale non deve richiedere un nuovo commit della fonte.
|
||||
|
||||
Si riusa l'attivazione Evidence esistente dove serve a verificare un candidato e
|
||||
a recuperare da errori; l'assenza di lettori contemporanei non rende atomici file
|
||||
e Qdrant. La mutazione resta circoscritta alle Evidence e preserva Schema, relazioni,
|
||||
LSH e Memory. Il suo successo non cancella blocchi di readiness del Catalog.
|
||||
|
||||
Le verifiche prioritarie coprono il percorso draft → raffinamento → elenco/CRUD
|
||||
locale → ricerca, persistenza dopo riavvio, retry dopo errore, mancata ricomparsa
|
||||
delle unità eliminate, refresh con correzioni locali, isolamento dei workspace e
|
||||
conservazione dell'archivio locale dopo Clear. Le prove di aggiornamento live da
|
||||
amministrazione vengono eliminate; resta la verifica delle correzioni deliberate
|
||||
dal core stesso.
|
||||
|
||||
L'ordine resta Memory, Evidence e integrazione finale. I dettagli degli incrementi
|
||||
nei due piani sono lavoro interno; per l'utente rimangono due gestioni autonome.
|
||||
@@ -0,0 +1,343 @@
|
||||
# M1 — Archivio autorevole e amministrazione delle Memory Card
|
||||
|
||||
Data: 2026-09-08. Stato: M1 implementato e verificato localmente;
|
||||
confini di test confermati dal proprietario il 2026-09-08.
|
||||
|
||||
Primo incremento del progetto Memory management. Attua le decisioni già approvate
|
||||
nel piano del 2026-09-08 e nell'ADR 0018. Le scelte tecniche di dettaglio qui
|
||||
proposte derivano dalla ricognizione del runtime. Gli esiti dell'implementazione
|
||||
sono riportati nel [rapporto di verifica](2026-09-08-memory-m1-validation.md).
|
||||
|
||||
## Problem Statement
|
||||
|
||||
L'amministratore deve poter trovare, leggere e curare tutta la conoscenza
|
||||
riutilizzabile di un workspace: chiarimenti di dominio, regole SQL, domande
|
||||
risolte ed errori compresi da evitare. Oggi manca una pagina amministrativa
|
||||
dedicata e l'archivio è frammentato: le Memory sono registrate in JSONL, mentre
|
||||
gli exemplar delle domande risolte sono indicizzati attraverso un percorso distinto.
|
||||
|
||||
Questa situazione non offre un unico archivio completo di card, collegamenti e
|
||||
dipendenze strutturate. La disponibilità dell'indice non deve determinare se una
|
||||
card è consultabile o modificabile. Una modifica o cancellazione deve inoltre
|
||||
impedire che una ricerca successiva utilizzi contenuti superati, anche se
|
||||
l'aggiornamento dell'indice fallisce.
|
||||
|
||||
## Solution
|
||||
|
||||
Consegnare la pagina **Memory management** in Administration e un archivio
|
||||
PostgreSQL autorevole, appartenente al modulo Memory. La pagina consente elenco
|
||||
completo, ricerca testuale, filtri, dettaglio, creazione, modifica, cancellazione
|
||||
e gestione dei collegamenti. I contenuti restano consultabili con embedding o
|
||||
Qdrant indisponibili, purché PostgreSQL sia disponibile.
|
||||
|
||||
Un salvataggio aggiorna insieme card, collegamenti e dipendenze, poi propaga la
|
||||
modifica a Qdrant. L'amministratore vede se il contenuto è stato salvato e se è
|
||||
disponibile al recall. Se la propagazione fallisce può riprovarla, anche dopo un
|
||||
riavvio. I contenuti rimossi o superati non sono utilizzati dal recall.
|
||||
|
||||
M1 consegna l'amministrazione e la coerenza dell'archivio. La ricerca ibrida con
|
||||
espansione dei collegamenti e il nuovo riepilogo del workflow sono gli incrementi
|
||||
M2 e M3, entrambi ancora obbligatori per completare il progetto Memory.
|
||||
|
||||
## User Stories
|
||||
|
||||
1. Come amministratore, voglio aprire Memory management da Administration, così
|
||||
da curare la conoscenza senza avviare una sessione.
|
||||
2. Come amministratore, voglio scegliere esplicitamente il workspace da
|
||||
amministrare, così da sapere a quale archivio appartiene ogni operazione.
|
||||
3. Come amministratore, voglio elencare tutte le card del workspace, così da
|
||||
raggiungere anche quelle che non compaiono nel recall semantico.
|
||||
4. Come amministratore, voglio cercare per testo o identificatore e ordinare i
|
||||
risultati, così da trovare una card senza conoscerne la formulazione esatta.
|
||||
5. Come amministratore, voglio combinare filtri per famiglia, concetti, riferimenti
|
||||
a tabelle o colonne, provenienza e aggiornamento, così da restringere l'intero
|
||||
archivio prima della paginazione.
|
||||
6. Come amministratore, voglio leggere contenuto completo, ambito, motivazione e
|
||||
provenienza disponibile, così da capire quando una card è applicabile.
|
||||
7. Come amministratore, voglio creare una card manuale senza inventare una sessione
|
||||
o una decisione di origine, così da registrare conoscenza curata direttamente.
|
||||
8. Come amministratore, voglio rappresentare chiarimenti, regole SQL, domande
|
||||
risolte ed errori compresi, così da conservare i contenuti concordati.
|
||||
9. Come amministratore, voglio conservare domanda, SQL e contesto di un exemplar,
|
||||
così da distinguerlo da una regola generale.
|
||||
10. Come amministratore, voglio associare dipendenze esplicite a database, tabelle
|
||||
e colonne, così da non affidare l'identificazione degli oggetti al testo libero.
|
||||
11. Come amministratore, voglio correggere i campi consentiti dalla famiglia e
|
||||
annullare una modifica non salvata, così da controllare il contenuto corrente.
|
||||
12. Come amministratore, voglio ricevere errori di validazione comprensibili senza
|
||||
perdere il testo inserito, così da poterlo correggere.
|
||||
13. Come amministratore, voglio creare, modificare e cancellare collegamenti con
|
||||
destinazione e significato espliciti, così da curare le relazioni fra card.
|
||||
14. Come amministratore, voglio salvare card e modifiche correlate come un'unica
|
||||
operazione, così da non lasciare collegamenti o dipendenze parziali.
|
||||
15. Come amministratore, voglio cancellare una card e i suoi collegamenti
|
||||
incidenti conservando le altre card, così da rimuovere solo il contenuto scelto.
|
||||
16. Come amministratore, voglio ritrovare le modifiche dopo riapertura della pagina
|
||||
e riavvio del servizio, così da verificare che il salvataggio sia persistente.
|
||||
17. Come amministratore, voglio consultare e curare l'archivio quando embedding o
|
||||
Qdrant sono indisponibili, così da proseguire il lavoro amministrativo.
|
||||
18. Come amministratore, voglio distinguere archivio vuoto e archivio non
|
||||
disponibile, così da non interpretare un guasto come perdita dei dati.
|
||||
19. Come amministratore, voglio distinguere salvataggio fallito e contenuto
|
||||
salvato con indicizzazione incompleta, così da scegliere il recupero corretto.
|
||||
20. Come amministratore, voglio riprovare una propagazione incompleta anche dopo
|
||||
un riavvio o una cancellazione, così da completare la pulizia dell'indice.
|
||||
21. Come reviewer, voglio che una nuova ricerca escluda card eliminate o contenuti
|
||||
superati, così da ricevere soltanto conoscenza corrente.
|
||||
22. Come reviewer, voglio che gli exemplar rimangano consultativi e che una Memory
|
||||
recuperata non costituisca approvazione, così da conservare il controllo del workflow.
|
||||
23. Come amministratore, voglio che reindicizzazione e preprocessing rispettino le
|
||||
cancellazioni e le correzioni, così da non doverle ripetere.
|
||||
24. Come operatore dell'installazione, voglio preparare lo schema e configurare
|
||||
l'accesso Memory con i meccanismi esistenti, così da avviarlo senza nuovi servizi.
|
||||
25. Come proprietario del workspace, voglio che API e comandi rispettino il
|
||||
contesto autorizzato, così da evitare accessi o collegamenti fra archivi diversi.
|
||||
26. Come proprietario del workspace, voglio che il CRUD Memory lasci invariati
|
||||
Evidence e metadati del database, così da mantenere distinte le responsabilità.
|
||||
|
||||
## Implementation Decisions
|
||||
|
||||
### Responsabilità e punti d'ingresso
|
||||
|
||||
- Il modulo Memory del harness possiede modello, validazione, repository,
|
||||
mutazioni, collegamenti, dipendenze e coerenza delle proiezioni. PostgreSQL è
|
||||
autorevole; Qdrant contiene una proiezione ricostruibile.
|
||||
- I comandi Memory esistenti diventano adattatori del medesimo servizio. La
|
||||
superficie viene completata con creazione manuale, gestione dei collegamenti,
|
||||
elenco delle propagazioni incomplete e retry. Nessuna logica di persistenza
|
||||
Memory viene duplicata nel backend.
|
||||
- Il backend espone API amministrative attraverso il runner del harness,
|
||||
associando principal attendibile e configurazione del workspace alla richiesta.
|
||||
Si conservano opzioni di configurazione per comando e output JSON puro.
|
||||
- La ricognizione conferma che il harness usa già SQLAlchemy e PostgreSQL per le
|
||||
sessioni. Se ne riusano i meccanismi adatti, mantenendo separati modello,
|
||||
migrazioni e proprietà dei dati Memory. Il repository in memoria del Metadata
|
||||
Catalog è un test double del Catalog, non il modulo Memory.
|
||||
|
||||
### Modello e transazioni
|
||||
|
||||
- La card ha identità stabile, workspace, famiglia/contenuto, titolo o soggetto,
|
||||
ambito, motivazione, provenienza, concetti e date di creazione/aggiornamento.
|
||||
Le domande risolte conservano anche domanda, SQL e contesto. L'identità di una
|
||||
card manuale non dipende da una sessione né dal solo testo.
|
||||
- Il modello rappresenta le quattro categorie di contenuto approvate senza
|
||||
imporre quattro nuovi kind vettoriali o la corrispondenza con i tipi del ledger.
|
||||
Le origini manuali sono distinguibili; sessione e decisione sono riferimenti
|
||||
opzionali quando effettivamente disponibili.
|
||||
- I collegamenti sono record propri del modulo con sorgente, destinazione e
|
||||
significato. Le due card devono esistere nello stesso workspace. La cancellazione
|
||||
di una card elimina i collegamenti incidenti, senza propagarsi alle altre card.
|
||||
- Le dipendenze identificano esplicitamente database, schema, tabella e colonna
|
||||
secondo l'ambito applicabile. Il contratto consente il futuro confronto con
|
||||
lo schema fisico. Un cleanup dei metadati Catalog non deve poter cancellare
|
||||
card attraverso una cascata implicita di chiavi esterne.
|
||||
- Le tabelle logiche necessarie sono card, collegamenti, dipendenze e stato
|
||||
operativo delle proiezioni. Card e modifiche correlate si aggiornano nella
|
||||
stessa transazione. Una validazione o scrittura fallita non lascia aggiornamenti
|
||||
parziali. Non si conserva una storia delle revisioni del contenuto.
|
||||
- Le modifiche ordinarie non spostano una card in un altro workspace. Tutti gli
|
||||
identificatori ricevuti vengono verificati nel workspace dell'operazione,
|
||||
inclusi estremi dei collegamenti e riferimenti delle azioni di retry.
|
||||
|
||||
### Salvataggio, cancellazione e recall
|
||||
|
||||
- Il servizio valida l'intera mutazione, registra il nuovo stato autorevole e
|
||||
il lavoro di propagazione nella stessa transazione PostgreSQL, poi aggiorna
|
||||
Qdrant nello stesso flusso di salvataggio. Si completa un'operazione alla volta;
|
||||
non occorrono una coda generale, un worker o una sincronizzazione continua.
|
||||
- Lo stato persistente è sufficiente a distinguere la proiezione del contenuto
|
||||
corrente da una proiezione precedente e a ritentare l'azione dopo un riavvio.
|
||||
Può usare una versione tecnica o un'impronta interna; non è una cronologia
|
||||
editoriale né un ulteriore stato che l'utente debba gestire.
|
||||
- Un risultato Qdrant è utilizzabile solo se corrisponde a una card autorevole
|
||||
corrente del workspace e a una proiezione valida. Il contenuto restituito
|
||||
viene dall'archivio autorevole. La verifica si applica anche agli exemplar.
|
||||
In assenza di verifica autorevole il recall non restituisce il vecchio payload.
|
||||
- Dopo il commit PostgreSQL, una propagazione fallita lascia il contenuto
|
||||
consultabile nell'amministrazione e la sua proiezione non utilizzabile dal
|
||||
recall fino al recupero. L'esito distingue chiaramente questo caso da un
|
||||
salvataggio fallito prima del commit.
|
||||
- La cancellazione rimuove card, collegamenti incidenti e dipendenze e conserva
|
||||
soltanto i dati operativi necessari a eliminare la proiezione. La card non è
|
||||
più richiamabile anche se il punto Qdrant esiste ancora. La pulizia pendente
|
||||
resta raggiungibile dalla pagina, senza richiedere il dettaglio della card eliminata.
|
||||
- Il retry è esplicito e ripetibile. Usa lo stato corrente del repository, non
|
||||
il contenuto di una vecchia richiesta. Un retry superato non può sovrascrivere
|
||||
una correzione successiva né ricreare una card cancellata.
|
||||
- La ricostruzione degli indici Memory e solved-question usa esclusivamente
|
||||
le card autorevoli. Non reimporta automaticamente il registro JSONL, i payload
|
||||
Qdrant o le sessioni di origine. Il preprocessing delle reference mantiene
|
||||
la separazione delle collezioni stabilita nell'ADR 0017.
|
||||
- Anche i produttori attuali di Memory ed exemplar scrivono attraverso il
|
||||
servizio autorevole. Si adeguano promozione, salvataggio singolo e percorso di
|
||||
finalizzazione quanto necessario a evitare scritture dirette al solo indice.
|
||||
Un errore successivo al commit della sessione non deve annullarne la finalizzazione;
|
||||
l'esito e il recupero Memory restano espliciti. Questa transizione non introduce
|
||||
il nuovo riepilogo di approvazione previsto da M3.
|
||||
|
||||
### API, autorizzazione e configurazione
|
||||
|
||||
- Il contratto amministrativo comprende elenco, dettaglio, creazione,
|
||||
aggiornamento, cancellazione, manutenzione dei collegamenti, stato delle
|
||||
propagazioni incomplete e retry. Le mutazioni restituiscono identità interessata,
|
||||
esito del salvataggio ed esito della propagazione; gli errori non espongono segreti.
|
||||
- L'elenco restituisce pagina, conteggio totale filtrato e ordinamento stabile
|
||||
con identificatore come discriminante. Ricerca testuale e filtri combinabili
|
||||
agiscono sull'intero archivio prima della paginazione, senza embedding.
|
||||
- Il backend distingue input invalido, accesso negato, record assente nel
|
||||
workspace richiesto, archivio indisponibile e propagazione incompleta dopo
|
||||
salvataggio. Un archivio indisponibile non produce una lista vuota riuscita.
|
||||
- Si riusano autenticazione, controlli di accesso e trasmissione del principal.
|
||||
Il catalogo attuale non ha un permesso Memory dedicato: la proposta è aggiungere
|
||||
la capability amministrativa Memory al ruolo admin esistente, senza introdurre
|
||||
ruoli nuovi. Il controllo copre anche letture amministrative e retry.
|
||||
- Le operazioni amministrative e i comandi esposti non permettono bypass del
|
||||
controllo nel harness. Le scritture già previste dal workflow conservano il
|
||||
proprio contesto autorizzato di sessione; non diventano CRUD amministrativo
|
||||
liberamente accessibile a un utente ordinario. Il recall rimane accessibile
|
||||
secondo le regole del workflow.
|
||||
- M1 include configurazione della connessione al PostgreSQL dell'installazione,
|
||||
distribuzione protetta delle credenziali al harness, migrazioni versionate e
|
||||
privilegi runtime necessari alle sole tabelle Memory. Si riusano i meccanismi
|
||||
di configurazione generata, segreti e provisioning esistenti; non si usano le
|
||||
credenziali di lettura del DWH. I nomi fisici di schema, tabelle e parametri
|
||||
vengono fissati nell'implementazione rispettando questi contratti.
|
||||
- Le migrazioni sono eseguite dal percorso di preparazione dell'installazione,
|
||||
non da una richiesta HTTP ordinaria. Schema mancante o non aggiornato produce
|
||||
un errore operativo comprensibile. La transizione non prevede doppie scritture
|
||||
permanenti o conservazione del comportamento delle sessioni storiche.
|
||||
|
||||
### Pagina amministrativa
|
||||
|
||||
- Memory management è un accesso indipendente nell'Administration dell'AppShell,
|
||||
immediatamente dopo Database management, senza richiedere una sessione attiva
|
||||
o l'ingresso in Database management.
|
||||
- La pagina rende esplicito il workspace e offre lista paginata, ricerca,
|
||||
filtri, ordinamento, dettaglio completo e form. Le modifiche hanno salvataggio,
|
||||
annullamento e validazione. La cancellazione rende chiari contenuto interessato
|
||||
e rimozione dei collegamenti, seguendo le convenzioni UI esistenti.
|
||||
- Il feedback distingue operazione in corso, salvataggio fallito, contenuto
|
||||
salvato con indice incompleto e operazione completata. Il recupero delle
|
||||
cancellazioni pendenti è disponibile anche quando la card non compare più in lista.
|
||||
- I controlli sono accessibili da tastiera e hanno etichette comprensibili.
|
||||
Chrome e messaggi UI sono in inglese; il contenuto resta nella lingua del workspace.
|
||||
Hash, versioni tecniche e dettagli delle tabelle non sono esposti nel flusso ordinario.
|
||||
|
||||
## Testing Decisions
|
||||
|
||||
Confini confermati dal proprietario: usare tre confini già presenti nel
|
||||
repository, concentrando la maggior parte dei casi sul servizio pubblico Memory
|
||||
del harness. I test osservano risultati, persistenza ed errori; non vincolano
|
||||
metodi privati, numero di query o disposizione interna delle tabelle.
|
||||
|
||||
### 1. Servizio pubblico Memory e suoi comandi
|
||||
|
||||
Usare PostgreSQL reale in testcontainers, come nei test del repository delle
|
||||
sessioni, e gli adapter vettoriali sostituibili già impiegati nei test di recall
|
||||
e del ciclo di vita solved-question. Gli embedding dei casi deterministici sono
|
||||
controllati. Un gruppo mirato con Qdrant reale verifica aggiornamento, cancellazione
|
||||
e ricostruzione della proiezione; non richiede DWH remoto o un modello generativo.
|
||||
|
||||
Questo confine verifica il comportamento di archivio, propagazione e recall:
|
||||
|
||||
| Caso | Risultato osservabile richiesto |
|
||||
| --- | --- |
|
||||
| Creare e riaprire il repository | La card completa, i collegamenti e le dipendenze sono persistiti; l'origine manuale non contiene sessioni inventate. |
|
||||
| Salvare una card di ciascuna categoria | Contenuto, ambito e dati specifici sono rappresentabili e leggibili senza dipendere dai tipi del ledger. |
|
||||
| Cercare un record fuori dalla prima pagina | Filtri combinati, totale e ordinamento si riferiscono all'intero archivio. |
|
||||
| Fallire una scrittura correlata | Card, collegamenti e dipendenze mantengono tutti lo stato precedente. |
|
||||
| Indicare una card di un altro workspace | Lettura, mutazione, collegamento e retry non accedono al contenuto estraneo. |
|
||||
| Cancellare una card collegata | Scompaiono card e collegamenti incidenti; le altre card restano intatte. |
|
||||
| Rendere embedding o Qdrant indisponibili | Elenco e dettaglio funzionano; il CRUD persiste e distingue la propagazione incompleta. |
|
||||
| Fallire PostgreSQL prima del commit | Nessun falso salvataggio riuscito e nessun nuovo contenuto propagato. |
|
||||
| Fallire Qdrant dopo un aggiornamento | Il dettaglio contiene la correzione; il recall esclude il vecchio risultato. |
|
||||
| Fallire Qdrant dopo una cancellazione | La card non è richiamabile; il lavoro di pulizia resta visibile e recuperabile. |
|
||||
| Riavviare fra commit e propagazione | Il lavoro incompleto permane e un retry lo completa. |
|
||||
| Ritentare dopo un errore o un esito incerto | Non si creano duplicati; si applica lo stato corrente senza ripristinare contenuti superati. |
|
||||
| Indice con punto orfano o versione superata | Recall Memory ed exemplar lo escludono anche se ha il punteggio più alto. |
|
||||
| PostgreSQL indisponibile durante il recall | Il servizio segnala l'indisponibilità senza servire payload non verificati. |
|
||||
| Ricostruire dopo modifica o cancellazione | Il contenuto corretto è conservato; nessuna card viene ricreata dalle sessioni o da vecchi indici. |
|
||||
| Eseguire promozione o finalizzazione corrente | I nuovi contenuti passano dall'archivio; un errore Memory successivo non annulla una sessione già finalizzata. |
|
||||
| Applicare migrazioni e riavviare | Lo schema è utilizzabile con il ruolo runtime previsto; la preparazione è ripetibile e non richiede privilegi di migrazione nelle richieste ordinarie. |
|
||||
|
||||
I test CLI coprono solo l'adattamento che il servizio non prova: parsing, principal,
|
||||
workspace, esiti macchina e JSON puro. I test di integrazione riusano le convenzioni
|
||||
L0 del harness. I test di recall esistenti continuano a verificare che decisioni
|
||||
già registrate nella sessione e famiglie non ammesse non vengano riproposte.
|
||||
|
||||
### 2. API amministrative Fastify
|
||||
|
||||
Usare l'iniezione HTTP e il runner sostituibile già presenti nei test backend,
|
||||
seguendo i test delle route Catalog e dell'autorizzazione. Verificare principal
|
||||
autenticato, admin e utente ordinario; validazione; selezione del workspace;
|
||||
contratto delle risposte e mappatura degli errori. Includere letture, collegamenti
|
||||
e retry, non soltanto le mutazioni delle card.
|
||||
|
||||
Questi test provano il confine HTTP e il passaggio al harness. Non si considera
|
||||
il runner simulato una prova della transazione PostgreSQL o della coerenza Qdrant.
|
||||
La normale policy CSRF dell'applicazione resta applicata alle nuove mutazioni.
|
||||
|
||||
### 3. Pagina nell'AppShell
|
||||
|
||||
Usare React Testing Library, MSW e le convenzioni dei test di AppShell e Database
|
||||
management. Verificare ingresso amministrativo, scelta workspace, lista completa,
|
||||
filtri, dettaglio, form, annullamento, errori, collegamenti e retry dopo cancellazione.
|
||||
Controllare il comportamento tramite elementi accessibili e contenuto visibile.
|
||||
|
||||
Un percorso browser mirato sullo stack reale collega i tre confini: amministratore
|
||||
autenticato, creazione manuale, modifica, riapertura della pagina, cancellazione
|
||||
e verifica dell'assenza nel recall. I test browser con API intercettate provano
|
||||
interazione e presentazione; non vengono dichiarati prova della persistenza.
|
||||
|
||||
Non si replica l'intera matrice su tutti e tre i confini. PostgreSQL, indice e
|
||||
recupero sono verificati nel harness; autenticazione e trasporto nel backend;
|
||||
interazione e feedback nella UI. Il percorso integrato copre il collegamento reale.
|
||||
|
||||
### Verifica della consegna
|
||||
|
||||
Eseguire i test interessati e i gate documentati dei layer modificati, inclusi
|
||||
typecheck TypeScript, lint Python e build documentale strict. Le verifiche con
|
||||
PostgreSQL, Qdrant e browser reale hanno esito riportato separatamente; se un
|
||||
servizio necessario manca, il relativo gate resta aperto.
|
||||
|
||||
M1 non richiede una valutazione della qualità SQL generata da un LLM. I test
|
||||
deterministici non sono presentati come prova di tale capacità: gli eventuali
|
||||
casi reali appartengono agli incrementi che cambiano generazione e workflow.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Ricerca ibrida, nuova selezione per ambito ed espansione dei collegamenti: M2.
|
||||
- Riepilogo finale modificabile, nuove categorie nei gate e pulizia dopo una
|
||||
sincronizzazione fisica del Catalog: M3. M1 ne prepara card e dipendenze.
|
||||
- Authoring, consolidamento e manutenzione Evidence: E1–E3; risoluzione persistente
|
||||
congiunta dei conflitti fra Memory ed Evidence: X1.
|
||||
- Revisione storica delle card, snapshot per vecchie sessioni, migrazione dei dati
|
||||
di sviluppo o compatibilità con il registro JSONL come archivio operativo.
|
||||
- Aggiornamento a caldo delle altre sessioni, nuove invalidazioni dello SQL già
|
||||
generato, coordinamento generale dei lettori paralleli e modalità manutenzione.
|
||||
- Nuovi servizi PostgreSQL o graph database, code generiche, worker e polling continuo.
|
||||
- Promozione automatica di rifiuti senza spiegazione o scelte occasionali,
|
||||
consolidamento automatico e benchmark generale della qualità del modello.
|
||||
- Deploy o pulizia dell'installazione PSD: restano soggetti ai rispettivi piani e gate.
|
||||
|
||||
## Further Notes
|
||||
|
||||
Fonti: progetto **Memory management** del 2026-09-08; piano comune
|
||||
**Amministrazione di Memory ed Evidence**; **Revisione di semplicità: Memory ed
|
||||
Evidence**; glossario di dominio; ADR 0017 sulla separazione delle collezioni e
|
||||
ADR 0018 su PostgreSQL autorevole e Qdrant per il retrieval.
|
||||
|
||||
La ricognizione ha verificato MemoryRecord, recall ordinario, ricerca degli
|
||||
exemplar, comandi Memory, repository PostgreSQL delle sessioni, runner del harness,
|
||||
autorizzazione backend e navigazione amministrativa. Il recall ordinario oggi
|
||||
risolve già i risultati nel registro autorevole, mentre gli exemplar leggono
|
||||
contenuti dal payload vettoriale: M1 deve uniformare entrambe le garanzie.
|
||||
|
||||
Le scelte tecniche da fissare durante l'implementazione sono nomi e DDL delle
|
||||
tabelle, firma esatta dei nuovi comandi/API e parametri generati di connessione.
|
||||
Devono rispettare i contratti e i casi di accettazione di questa specifica;
|
||||
non riaprono le decisioni di prodotto approvate.
|
||||
|
||||
La destinazione della specifica è il tracker Gitea canonico di ThothII, con
|
||||
etichetta **ready-for-agent**. Il proprietario ha confermato i confini di test
|
||||
e autorizzato la pubblicazione il 2026-09-08. L'implementazione resta da eseguire.
|
||||
@@ -0,0 +1,103 @@
|
||||
# M1 — Implementazione e verifica
|
||||
|
||||
Data: 2026-09-08. Implementazione locale della
|
||||
[specifica approvata](2026-09-08-memory-m1-spec.md), associata all'
|
||||
[issue 27](https://git.tylconsulting.it/mptyl/ThothII/issues/27).
|
||||
|
||||
## Risultato
|
||||
|
||||
La pagina **Memory management** è disponibile nell'Administration dopo Database
|
||||
management. Gestisce le quattro famiglie di card, elenco completo, ricerca e filtri,
|
||||
ordinamento, dettaglio, creazione, modifica, cancellazione, collegamenti e dipendenze.
|
||||
Richiede un amministratore autenticato e una selezione esplicita del workspace;
|
||||
non richiede una sessione o un database DWH configurato.
|
||||
|
||||
Il harness possiede l'archivio PostgreSQL `thoth_memory`. Card, collegamenti,
|
||||
dipendenze e lavoro di propagazione sono salvati nella stessa transazione.
|
||||
La pagina distingue salvataggio fallito e contenuto salvato con indice incompleto,
|
||||
offrendo retry anche per le cancellazioni. Recall Memory ed exemplar verificano
|
||||
esistenza, workspace e proiezione corrente nell'archivio prima di restituire contenuto.
|
||||
|
||||
Promozione, salvataggio singolo e finalizzazione corrente passano dal servizio
|
||||
autorevole. Le ricevute della sorgente impediscono duplicati e ricreazione di card
|
||||
cancellate. Reindicizzazione e preprocessing non importano vecchi payload o sessioni.
|
||||
L'errore Memory non annulla una sessione già finalizzata; il gate segnala anche
|
||||
una promozione salvata con indicizzazione incompleta.
|
||||
|
||||
Le migrazioni sono versionate, controllate tramite checksum e incluse nel wheel
|
||||
e nell'immagine core. Il servizio di preparazione `catalog-migrate` le esegue dopo
|
||||
quelle del Catalog. Il runtime assume il ruolo limitato `thoth_memory_runtime`,
|
||||
con isolamento del workspace tramite RLS e senza privilegi DDL.
|
||||
|
||||
## Verifiche eseguite
|
||||
|
||||
| Confine | Esito |
|
||||
| --- | --- |
|
||||
| Harness, test senza L0/L2 | 1.134 passati; i 9 test dei percorsi portabili sono stati eseguiti separatamente e sono passati. |
|
||||
| Servizio Memory, PostgreSQL e Qdrant reali | 17 passati, inclusi CLI, migrazioni, ruolo runtime, isolamento, transazioni, outage, retry, cancellazioni, cambio famiglia e rebuild. |
|
||||
| Gate Pi | 190 passati, inclusi identità UUID e avviso dopo salvataggio con indice incompleto. |
|
||||
| Backend | 1.345 passati nella suite completa, 40 esclusi dalle condizioni previste dai test; un test di autenticazione ha superato il timeout sotto carico. Il relativo file è stato rieseguito isolato: tutti i 17 test passati. |
|
||||
| Frontend | 632 passati, inclusi ingresso dall'AppShell, form, filtri, collegamenti, dipendenze e retry delle cancellazioni. |
|
||||
| Browser integrato | Passato: autenticazione amministratore, creazione, modifica, riavvio del backend, rilettura, cancellazione e assenza nel recall. |
|
||||
| Build e tipi | Build backend e frontend, typecheck TypeScript e build documentale strict superati. |
|
||||
| Lint e diff | Ruff sui file Python modificati e `git diff --check` superati. Il lint globale segnala tre rilievi in file non modificati, elencati sotto. |
|
||||
|
||||
Il browser utilizza autenticamente frontend, login locale, Fastify, ThtRunner,
|
||||
CLI Python, PostgreSQL e Qdrant. Gli embedding sono deterministici e le attività
|
||||
Pi/sessione estranee al percorso Memory usano le fixture esistenti. Non sono state
|
||||
intercettate le API Memory. Sono stati usati container temporanei PostgreSQL 16 e
|
||||
Qdrant 1.18.2, senza accesso a un DWH remoto o a un modello generativo.
|
||||
|
||||
Il test browser ha consentito di correggere etichette accessibili instabili nei
|
||||
campi compilati e la sovrapposizione del pannello di recupero ai comandi del dettaglio.
|
||||
La selezione del workspace e l'uscita dalla pagina sono bloccate durante le operazioni.
|
||||
|
||||
Il lint globale preesistente riguarda soltanto:
|
||||
|
||||
- ordinamento import in `harness/tests/test_effective_relationships.py`;
|
||||
- ordinamento import in `harness/tests/test_p3_dwh_binding.py`;
|
||||
- uso di `datetime.UTC` in `harness/tht/mschema/catalog_snapshot.py`.
|
||||
|
||||
## Riproduzione
|
||||
|
||||
Usare Node 24 e le dipendenze installate dei tre layer. Per eseguire il harness
|
||||
in un ambiente con home non scrivibile si può impostare `THT_HOME` su una directory
|
||||
di prova. I test dei percorsi portabili devono essere eseguiti senza questo override,
|
||||
perché verificano deliberatamente la risoluzione dell'home e di `THT_DATA_ROOT`.
|
||||
|
||||
```sh
|
||||
cd harness
|
||||
THT_HOME=/private/tmp/thothii-m1-test-home .venv/bin/pytest -m 'not l0 and not l2' --ignore=tests/test_portable_paths.py -q
|
||||
.venv/bin/pytest tests/test_portable_paths.py -q
|
||||
.venv/bin/pytest tests/memory/test_administration.py -q
|
||||
npm test
|
||||
```
|
||||
|
||||
```sh
|
||||
cd backend
|
||||
npx vitest run
|
||||
npx tsc --noEmit -p .
|
||||
npm run build
|
||||
```
|
||||
|
||||
```sh
|
||||
cd frontend
|
||||
npx vitest run
|
||||
npx tsc -b
|
||||
npm run build
|
||||
THT_MEMORY_BROWSER_E2E=1 npx playwright test e2e/memory-real.spec.ts
|
||||
```
|
||||
|
||||
Il percorso browser richiede Docker, Python del harness, Go per il bridge di
|
||||
autenticazione e Chromium di Playwright. Avvia risorse isolate e le rimuove alla
|
||||
fine. Su macOS il browser deve poter avviare i processi Chromium fuori dalle
|
||||
restrizioni della sandbox. La build documentale si esegue dalla radice con
|
||||
`./scripts/build-docs.sh`.
|
||||
|
||||
## Stato della consegna
|
||||
|
||||
Le modifiche sono nel worktree locale. Nessuno stack già attivo è stato aggiornato
|
||||
e nessun dato esistente è stato migrato o eliminato. Prima di usare M1 su
|
||||
un'installazione occorrono il nuovo core e la preparazione `catalog-migrate`.
|
||||
M2 (retrieval ibrido ed espansione dei collegamenti), M3 (integrazione estesa nel
|
||||
workflow) ed Evidence management restano incrementi successivi.
|
||||
@@ -0,0 +1,342 @@
|
||||
# Progetto: Memory management
|
||||
|
||||
Data del piano: 2026-09-08. Aggiornamento 2026-09-09: M1–M3 implementati,
|
||||
con integrazione X1 per le correzioni persistenti dei conflitti. Risultati e limiti
|
||||
sono raccolti nel [rapporto X1](2026-09-09-archive-repair-x1-validation.md).
|
||||
|
||||
La [revisione di semplicità](2026-09-08-memory-evidence-simplification-review.md)
|
||||
mantiene il perimetro Memory e precisa un salvataggio sequenziale e una pulizia
|
||||
diretta dopo sincronizzazione. Non si progetta l'amministrazione contemporanea
|
||||
all'attività core.
|
||||
|
||||
Il progetto realizza il CRUD amministrativo previsto dalla discussione sull'evoluzione
|
||||
della Memory. Segue le [decisioni comuni di Administration](2026-09-08-memory-evidence-administration.md)
|
||||
e rimane distinto dal [progetto Evidence management](2026-09-08-evidence-management.md).
|
||||
|
||||
## Risultato richiesto
|
||||
|
||||
Un amministratore apre Memory management direttamente da Administration, cerca e
|
||||
filtra l'intero archivio di un workspace e gestisce le card senza avviare una sessione.
|
||||
La voce è immediatamente sotto Database management, allo stesso livello.
|
||||
|
||||
L'elenco comprende le Memory riutilizzabili e gli exemplar `solved_question`,
|
||||
distinguibili per famiglia. La modifica di un exemplar non riscrive gli artefatti
|
||||
della sessione da cui deriva e non lo trasforma in una decisione applicabile al gate.
|
||||
|
||||
## Contenuti ammessi: decisione del proprietario
|
||||
|
||||
Il perimetro concordato il 2026-09-08 comprende quattro categorie di contenuto.
|
||||
La classificazione descrive il valore della conoscenza; non impone quattro nuovi
|
||||
kind tecnici o una corrispondenza con i tipi delle decisioni del ledger.
|
||||
|
||||
| Contenuto | Cosa conserva | Esempio inventato |
|
||||
| --- | --- | --- |
|
||||
| Chiarimento di dominio | Significato riutilizzabile di un termine, con il suo ambito | «In questo workspace, ordine evaso significa che tutte le righe sono state spedite.» |
|
||||
| Regola SQL | Regola corretta per join, filtri o aggregazioni, con condizioni e motivazione | «Il codice commessa è univoco solo all'interno dell'esercizio: collegare movimenti e commesse usando codice ed esercizio.» |
|
||||
| Domanda risolta | Domanda, SQL approvato e contesto, come exemplar consultativo | «Totale degli ordini del 2024 per cliente», con la query che lo calcola. |
|
||||
| Errore da evitare | Errore compreso, motivo e comportamento corretto approvato | «Il join fra ordini e righe moltiplica il totale di testata: calcolare il totale una sola volta per ordine.» |
|
||||
|
||||
Il criterio di ammissione è l'utilità per altre domande nello stesso ambito.
|
||||
Una scelta come «questa volta usa il 2024» non è una regola riutilizzabile; il 2024
|
||||
può rimanere nel contesto della domanda risolta. Analogamente, la selezione di una
|
||||
tabella per una domanda non diventa automaticamente una regola di schema linking.
|
||||
|
||||
La categoria «errore da evitare» richiede una spiegazione verificata e approvata.
|
||||
Un timeout, una query rifiutata senza motivo o una proposta non selezionata non
|
||||
bastano a produrre conoscenza. Quando errore e correzione esprimono la stessa
|
||||
regola, una sola card conserva la regola e la sua motivazione.
|
||||
|
||||
## Formazione, aggiornamento e uso delle card
|
||||
|
||||
### Decisioni del primo round di grill-with-docs
|
||||
|
||||
Il proprietario ha approvato le tre raccomandazioni il 2026-09-08:
|
||||
|
||||
- **Q1, approvazione del salvataggio:** riepilogo finale modificabile, preparato
|
||||
durante il lavoro. Il reviewer corregge le card e sceglie quali salvare; la
|
||||
creazione manuale da Administration resta sempre disponibile.
|
||||
- **Q2, operazioni proposte dal core:** aggiunte e aggiornamenti espliciti. Il
|
||||
riepilogo distingue una nuova card dalla modifica di una card esistente e ne
|
||||
spiega il cambiamento. La sostituzione richiede la selezione del reviewer;
|
||||
la cancellazione semantica resta un'operazione del CRUD amministrativo. La pulizia
|
||||
automatica dei riferimenti invalidi è disciplinata separatamente da Q5.
|
||||
- **Q3, momento del consumo:** i chiarimenti sono proposti all'inizio, le regole di
|
||||
collegamento durante lo schema linking e le regole di calcolo durante la costruzione
|
||||
SQL. Le approvazioni entrano nei gate pertinenti, senza una domanda separata per
|
||||
ciascuna card; gli exemplar rimangono consultativi.
|
||||
|
||||
Queste sono decisioni di prodotto; i contratti runtime non sono ancora aggiornati.
|
||||
|
||||
### Decisioni del secondo round di grill-with-docs
|
||||
|
||||
Il proprietario ha approvato i chiarimenti su Q4–Q6 il 2026-09-08:
|
||||
|
||||
- **Q4, risoluzione persistente dei conflitti:** il gate propone azioni chiuse e
|
||||
specifiche per il caso, mostrando record interessati, azione e testo o ambito
|
||||
risultante. Le opzioni possono confermare l'Evidence e correggere la Memory,
|
||||
confermare la Memory e preparare una correzione dell'Evidence, oppure precisare
|
||||
gli ambiti distinti di entrambe. È sempre disponibile «Nessuna proposta è adeguata»,
|
||||
che richiede una riformulazione. Le modifiche Memory confluiscono nel riepilogo
|
||||
finale; quelle Evidence seguono l'authoring e la pubblicazione del rispettivo
|
||||
modulo. Come approvato in Q12, accettare la correzione Evidence con le autorizzazioni
|
||||
necessarie avvia anche l'attivazione automatica, senza un ulteriore `Publish`.
|
||||
Il sistema distingue proposte da approvare, aggiornamenti in corso o falliti e
|
||||
archivio già aggiornato. La sola risoluzione della domanda corrente non esaurisce il flusso.
|
||||
- **Q5, cancellazione dopo modifiche allo schema:** dopo una sincronizzazione
|
||||
riuscita dello schema fisico, il backend comunica al modulo Memory gli elementi
|
||||
rimossi. Il modulo identifica tramite dipendenze strutturate le card non più
|
||||
valide e cancella record e proiezioni ricercabili. Non si introduce lo stato
|
||||
«Needs review» per conservarle. Il controllo avviene alla sincronizzazione, senza
|
||||
scansione continua del DWH o interrogazioni aggiuntive a ogni domanda. Un cleanup
|
||||
manuale del Catalog o un errore di accesso al database non prova una rimozione
|
||||
fisica e non avvia questa pulizia. Essa è distinta dalle proposte semantiche del
|
||||
core in Q2. Oggi mancano sia i riferimenti strutturati a colonne nelle Memory sia
|
||||
il collegamento fra sincronizzazione e pulizia: devono essere implementati.
|
||||
- **Q6, verifiche concrete:** lo sviluppatore prepara ed esegue test automatici
|
||||
funzionali per CRUD, filtri, approvazioni, aggiornamenti e cancellazioni. Quando
|
||||
cambia la ricerca, verifica casi mirati con card necessarie e card fuori ambito;
|
||||
quando emerge un errore SQL riproducibile, aggiunge una regressione su dati
|
||||
controllati confrontando i risultati, senza richiedere un identico testo SQL.
|
||||
L'esperto di dominio conferma inizialmente regola e risultato atteso soltanto per
|
||||
i casi reali che lo richiedono. La verifica della generazione necessita di un
|
||||
modello reale ed è separata dalla suite deterministica: una query scritta a mano
|
||||
non prova che il modello sappia generarla. Non si introduce una valutazione umana
|
||||
permanente o un benchmark generale con percentuali di miglioramento promesse.
|
||||
|
||||
### Terzo round: direzione tecnica e capacità di ricerca
|
||||
|
||||
- **Q7, deciso:** il proprietario ha approvato l'evoluzione interna di ThothII.
|
||||
Il modulo riusa l'infrastruttura dell'installazione e integra card, CRUD, mutazioni
|
||||
e recall con i gate; non adotta un framework esterno per governare la Memory.
|
||||
- **Q8, deciso:** il proprietario ha approvato ricerca ibrida in Qdrant e collegamenti
|
||||
espliciti fra card gestiti dal core, senza un database a grafi aggiuntivo. Entrambe
|
||||
le capacità sono incluse nella pianificazione attuale; la presenza dei collegamenti
|
||||
non è rinviata alla futura comparsa di casi concreti.
|
||||
|
||||
La configurazione approvata comprende:
|
||||
|
||||
- ricerca semantica e lessicale ibrida in Qdrant, con filtri sull'ambito;
|
||||
- collegamenti espliciti fra card, proposti e revisionabili, percorsi nel core con
|
||||
espansione limitata e riordinamento dei risultati insieme a quelli della ricerca;
|
||||
- persistenza dei collegamenti coordinata con le card, con rimozione dei riferimenti
|
||||
a contenuti cancellati e rispetto dei confini fra workspace e dei gate;
|
||||
- nessun servizio di database a grafi aggiuntivo.
|
||||
|
||||
La scelta include il grafo logico, senza introdurre un servizio di graph DB.
|
||||
La qualità non è garantita dalla scelta di un motore: mantenere queste capacità
|
||||
evita una rinuncia architetturale ai collegamenti, ma non dimostra equivalenza
|
||||
qualitativa con qualsiasi soluzione basata su graph DB.
|
||||
Qdrant è il motore di ricerca; l'archivio autorevole è PostgreSQL, scelto in Q9.
|
||||
|
||||
Le [query ibride di Qdrant](https://qdrant.tech/documentation/search/hybrid-queries/)
|
||||
e i [filtri sui metadati](https://qdrant.tech/documentation/search/filtering/)
|
||||
coprono le capacità di ricerca indicate. La logica dei collegamenti di dominio
|
||||
nel core è lavoro applicativo da implementare.
|
||||
|
||||
### Decisioni del quarto round di grill-with-docs
|
||||
|
||||
- **Q9, archivio autorevole:** il proprietario ha approvato PostgreSQL, già presente
|
||||
nell'installazione, con tabelle proprie del modulo Memory per card, collegamenti
|
||||
e dipendenze dallo schema. Sostituisce il registro JSONL; Qdrant è l'indice
|
||||
rigenerabile. Le modifiche correlate vengono coordinate in PostgreSQL e la
|
||||
propagazione a Qdrant deve gestire esplicitamente errori e cancellazioni.
|
||||
- **Q10, gestione dei collegamenti:** il core propone i collegamenti insieme alle
|
||||
card, indicando destinazione e significato. Il reviewer li approva nello stesso
|
||||
riepilogo finale, senza un gate aggiuntivo. Administration ne consente creazione,
|
||||
modifica e cancellazione manuali. Quando una card è cancellata vengono rimossi
|
||||
anche i collegamenti che la coinvolgono, conservando le altre card. I collegamenti
|
||||
contribuiscono al recupero e non applicano automaticamente i contenuti.
|
||||
|
||||
La decisione architetturale è registrata nell'[ADR 0018](../adr/0018-use-postgres-for-memory-and-qdrant-for-retrieval.md).
|
||||
|
||||
### Flusso da implementare
|
||||
|
||||
Il flusso seguente traduce le decisioni approvate. I payload e l'integrazione con
|
||||
i gate sono dettagli da definire nell'implementazione, senza altre decisioni di
|
||||
prodotto pendenti.
|
||||
|
||||
1. Durante il lavoro il core individua possibili conoscenze riutilizzabili a partire
|
||||
da decisioni e artefatti registrati. Una candidata esplicita cosa afferma, dove
|
||||
vale, perché è utile e su quale correzione o decisione si basa.
|
||||
2. Prima di proporne il salvataggio confronta la candidata con le card correnti.
|
||||
Un doppione esatto non richiede una nuova card; una somiglianza semantica non
|
||||
autorizza da sola a eliminare o sovrascrivere una conoscenza.
|
||||
3. Alla conclusione del lavoro presenta un riepilogo editabile delle aggiunte e
|
||||
degli aggiornamenti proposti. Il reviewer può correggere il contenuto, restringere
|
||||
l'ambito e scegliere cosa salvare; approvare la query non equivale ad approvare
|
||||
ogni generalizzazione ricavata dalla query.
|
||||
4. Una correzione alla stessa regola nello stesso ambito propone un aggiornamento
|
||||
esplicito della card esistente. Regole valide in ambiti diversi restano distinte;
|
||||
un conflitto irrisolto non viene risolto silenziosamente dal modello.
|
||||
5. Le card salvate sono subito consultabili in Memory management; la loro
|
||||
disponibilità al recall segue lo stato di indicizzazione. La scrittura sostituisce
|
||||
il contenuto corrente senza introdurre una cronologia delle Memory.
|
||||
|
||||
La creazione manuale da Memory management resta disponibile in qualsiasi momento
|
||||
e non dipende dal riepilogo finale di una sessione. La form richiede contenuto e
|
||||
ambito adeguati alla famiglia e identifica l'origine amministrativa.
|
||||
|
||||
Gli exemplar conservano domanda e soluzione approvata come materiale consultativo.
|
||||
Il loro salvataggio non applica le scelte di quella soluzione a domande successive.
|
||||
La distribuzione del consumo nei passaggi pertinenti è decisa in Q3. Restano da
|
||||
definire i payload e l'integrazione con i gate esistenti, compreso il contesto necessario
|
||||
a proporre una regola di collegamento o di calcolo e a registrarne l'approvazione.
|
||||
|
||||
### Scenari per verificare il design
|
||||
|
||||
| Evento | Esito atteso |
|
||||
| --- | --- |
|
||||
| Il reviewer corregge un join perché il codice commessa si ripete fra esercizi e approva la spiegazione. | Proporre la regola con entrambe le chiavi e l'ambito delle tabelle interessate. |
|
||||
| Il reviewer chiede di limitare solo la domanda corrente al 2024. | Nessuna regola generale; mantenere il periodo nell'eventuale exemplar. |
|
||||
| Una query conta più volte lo stesso ordine e la correzione viene spiegata e approvata. | Proporre una card che descrive la granularità corretta e il rischio di duplicazione. |
|
||||
| Una query fallisce per timeout o una memory non viene selezionata. | Nessuna nuova regola dedotta automaticamente dall'evento. |
|
||||
| La candidata ripete esattamente una regola già presente nello stesso ambito. | Evitare una nuova card duplicata. |
|
||||
| Una nuova regola corregge una card dello stesso ambito. | Mostrare la sostituzione proposta prima del salvataggio; conservare poi solo il contenuto corrente. |
|
||||
| Due regole differenti valgono per processi o tabelle differenti. | Conservare entrambe con ambiti espliciti, senza generalizzarle al workspace intero. |
|
||||
| Il reviewer risolve un contrasto fra Memory ed Evidence. | Mostrare una correzione esplicita degli archivi; applicare i percorsi distinti per Memory ed Evidence. L'accettazione autorizzata della correzione Evidence avvia anche l'attivazione; indicare esito, operazione in corso o errore. |
|
||||
| Una sincronizzazione riuscita accerta la rimozione di una colonna da cui dipende una card. | Cancellare la card dipendente e rimuoverla dai risultati di ricerca. |
|
||||
| La connessione al DWH fallisce oppure vengono puliti solo metadati del Catalog. | Non interpretare l'evento come prova di rimozione della colonna e non cancellare Memory per quel motivo. |
|
||||
|
||||
## Differenza rispetto al runtime corrente
|
||||
|
||||
`harness/tht/memory/core.py` limita `REUSABLE_TYPES` a `concept_clarified`.
|
||||
Anche il contratto Pi di F2 ammette soltanto questi chiarimenti; gli exemplar
|
||||
`solved_question` hanno già un percorso distinto di consultazione.
|
||||
|
||||
Il perimetro concordato amplia quindi il modulo Memory. Il design deve distinguere
|
||||
la conoscenza riutilizzabile dall'evento di workflow che l'ha originata, e aggiornare
|
||||
insieme estrazione, validazione, persistenza, recall e gate. Aggiungere alla whitelist
|
||||
tutti i tipi delle decisioni SQL o sulle tabelle promuoverebbe anche scelte occasionali
|
||||
e non realizza il requisito.
|
||||
|
||||
## Funzioni
|
||||
|
||||
- Elenco paginato e ordinabile, ricerca per testo o identificatore.
|
||||
- Filtri combinabili per workspace, famiglia/kind, concetti, tabelle e colonne
|
||||
quando presenti, provenienza e data di aggiornamento.
|
||||
- Dettaglio completo: titolo, contenuto, ambito, motivazione e provenienza disponibile.
|
||||
- Creazione manuale di una card, distinguibile da una card prodotta dal workflow;
|
||||
la creazione manuale non inventa una sessione o una decisione di origine.
|
||||
- Modifica dei campi consentiti dalla famiglia, con validazione e annullamento.
|
||||
- Cancellazione del record e rimozione delle sue proiezioni ricercabili.
|
||||
- Indicazione di contenuti salvati ma non ancora disponibili al recall, con retry
|
||||
dell'operazione necessaria a renderli disponibili.
|
||||
|
||||
L'elenco amministrativo legge i record persistiti senza richiedere embedding o
|
||||
ricerca per similarità. Un'indisponibilità dell'archivio deve produrre un errore
|
||||
esplicito, distinguibile da un elenco vuoto. I filtri sono applicati sull'intero
|
||||
archivio, prima della paginazione, e non sui soli risultati del recall.
|
||||
|
||||
## Comportamento delle modifiche
|
||||
|
||||
Una modifica sostituisce il contenuto corrente. Non si introducono revisioni storiche,
|
||||
snapshot dedicati alle vecchie sessioni o migrazioni per conservarne il comportamento.
|
||||
La cancellazione toglie la card dall'archivio e dal recall ordinario.
|
||||
|
||||
La mutazione deve aggiornare o invalidare ogni proiezione interessata. Un errore
|
||||
dell'indice non può essere presentato come piena disponibilità del nuovo contenuto,
|
||||
né permettere di usare silenziosamente il contenuto eliminato o sostituito.
|
||||
La strategia di consistenza e di retry appartiene al design tecnico del modulo.
|
||||
|
||||
Il salvataggio esplicito dell'amministratore cura il contenuto condiviso. Il suo
|
||||
successivo consumo nel core mantiene la semantica della famiglia: le Memory vengono
|
||||
proposte secondo i gate del workflow, gli exemplar restano consultativi.
|
||||
|
||||
## Piano esecutivo
|
||||
|
||||
### M1 — Archivio e CRUD amministrativo
|
||||
|
||||
Definire nel modulo `harness/tht/memory/` il contratto delle card: identità stabile,
|
||||
workspace, contenuto, famiglia, ambito, motivazione, provenienza e dati specifici
|
||||
delle domande risolte. I riferimenti allo schema identificano database, tabella e
|
||||
colonna senza affidarsi alla sola presenza di nomi nel testo. Le card manuali
|
||||
non richiedono sessioni inventate.
|
||||
|
||||
Implementare un repository PostgreSQL del modulo con card, collegamenti e dipendenze.
|
||||
La transazione aggiorna insieme il contenuto e le modifiche correlate; la propagazione
|
||||
a Qdrant avviene nello stesso flusso di salvataggio. Conservare un'indicazione
|
||||
persistente dell'operazione incompleta, sufficiente anche a ripulire cancellazioni
|
||||
dopo un riavvio; il recupero usa un retry esplicito. Non servono una coda generale,
|
||||
un nuovo worker o una sincronizzazione continua. Un risultato indicizzato
|
||||
con contenuto superato o privo di card autorevole non può essere usato dal recall.
|
||||
Gli exemplar passano anch'essi dall'archivio autorevole. La transizione dal registro
|
||||
JSONL non introduce scritture doppie permanenti o compatibilità storica delle sessioni.
|
||||
|
||||
Esporre attraverso il backend elenco filtrato prima della paginazione, dettaglio,
|
||||
creazione, aggiornamento, cancellazione, gestione dei collegamenti ed esito della
|
||||
propagazione. Le operazioni chiamano la logica del harness e applicano controllo
|
||||
amministrativo e isolamento del workspace. La UI legge il repository attraverso
|
||||
queste API anche quando il servizio di embedding o Qdrant è indisponibile.
|
||||
|
||||
Consegnare Memory management nell'AppShell con form, contenuto completo, gestione
|
||||
dei collegamenti e feedback di salvataggio/indicizzazione. Verificare persistenza
|
||||
PostgreSQL, rollback delle mutazioni correlate, aggiornamento e rimozione dal recall,
|
||||
retry dopo errore dell'indice, filtri sull'intero archivio e autorizzazioni. Una
|
||||
cancellazione elimina i collegamenti incidenti conservando le altre card.
|
||||
|
||||
### M2 — Ricerca ibrida e collegamenti
|
||||
|
||||
Estendere l'adapter Qdrant alla ricerca dense e lessicale della Memory e applicare
|
||||
l'ambito anche ai risultati raggiunti attraverso collegamenti. Le card iniziali
|
||||
alimentano l'espansione limitata nel core; deduplicazione, gestione dei cicli e
|
||||
limiti espliciti impediscono una visita incontrollata dell'archivio. I risultati
|
||||
vengono riordinati insieme e risolti contro il contenuto autorevole corrente.
|
||||
|
||||
Verificare card attese, esclusioni per ambito, cicli, collegamenti verso card rimosse
|
||||
e rigenerazione dell'indice da PostgreSQL. Quando si verifica il recupero effettivo,
|
||||
usare il percorso di embedding e ricerca configurato su un indice isolato: un fake
|
||||
che restituisce gli ID predisposti verifica soltanto il contratto applicativo.
|
||||
La separazione fra le collezioni Reference e Memory rimane quella degli ADR 0017 e 0018.
|
||||
|
||||
### M3 — Workflow e sincronizzazione fisica
|
||||
|
||||
Aggiornare insieme contratti, CLI, regole Pi e widget necessari al riepilogo finale
|
||||
modificabile. Il salvataggio applica soltanto card e collegamenti selezionati; le
|
||||
nuove categorie entrano nei gate pertinenti. Il recupero di una regola non ne
|
||||
costituisce approvazione, e l'exemplar continua a essere consultativo.
|
||||
|
||||
Collegare la sincronizzazione fisica del Catalog alla pulizia delle dipendenze nel
|
||||
modulo Memory con una chiamata diretta dopo l'applicazione riuscita dello schema,
|
||||
con copertura del controllo e riferimenti rimossi. Per recuperare un'interruzione
|
||||
fra applicazione e pulizia, conservarne lo stato pendente oppure verificare di
|
||||
nuovo le dipendenze contro lo snapshot fisico riuscito e il suo ambito: il nuovo
|
||||
diff da solo perderebbe le rimozioni già applicate. La pulizia è ripetibile e
|
||||
non richiede un sistema generale di consegna eventi.
|
||||
Un confronto parziale non prova la rimozione di elementi fuori dall'ambito controllato.
|
||||
La pulizia aggiorna archivio, collegamenti e proiezioni senza un'azione manuale ulteriore.
|
||||
|
||||
Verificare selezioni e rifiuti nel riepilogo, contenuto manuale, categorie ammesse,
|
||||
notifica di rimozione fisica, errore di connessione e cleanup del solo Catalog.
|
||||
Integrare le correzioni che riguardano Evidence nell'incremento congiunto X1, dopo
|
||||
il completamento del relativo servizio di authoring e attivazione.
|
||||
|
||||
L'evoluzione interna è decisa in Q7; ricerca ibrida e grafo nel core in Q8;
|
||||
PostgreSQL autorevole in Q9; gestione dei collegamenti in Q10. I contratti tecnici
|
||||
di persistenza, indicizzazione e API devono attuare queste decisioni. Apprendimento
|
||||
automatico da rifiuti non spiegati e consolidamento automatico restano fuori dal
|
||||
perimetro concordato; gli errori compresi e approvati rientrano nei contenuti decisi.
|
||||
|
||||
## Criteri di completamento
|
||||
|
||||
- Accesso amministrativo indipendente da sessioni e da Database management.
|
||||
- Tutti i record sono raggiungibili con elenco, filtri e paginazione, senza dipendere
|
||||
dalla disponibilità di embedding e recall semantico.
|
||||
- Creazione, modifica e cancellazione persistono dopo riapertura della pagina.
|
||||
- Dopo una mutazione completata il recall usa il contenuto corrente; i record
|
||||
cancellati non riappaiono dopo reindicizzazione o preprocessing.
|
||||
- Errori di salvataggio e indicizzazione sono distinguibili e recuperabili.
|
||||
- API e interfaccia rispettano isolamento dei workspace e accesso amministrativo.
|
||||
- Nessuna operazione del CRUD modifica Evidence o metadati del database.
|
||||
- Non vengono richieste compatibilità storica o conservazione delle sessioni esistenti.
|
||||
- Le quattro categorie concordate sono rappresentabili senza promuovere le scelte
|
||||
occasionali a regole generali; gli scenari di ammissione verificano il confine.
|
||||
- La rimozione fisica accertata di una dipendenza elimina le card interessate;
|
||||
errori di connessione e cleanup del Catalog non vengono scambiati per rimozioni.
|
||||
- Le scelte sui conflitti producono correzioni persistenti esplicite secondo Q4.
|
||||
- La verifica rispetta Q6, separando contratti funzionali e casi di generazione reale.
|
||||
- Il recupero combina ricerca ibrida, filtri d'ambito e collegamenti espliciti fra
|
||||
card; la gestione del grafo non richiede un servizio di database aggiuntivo.
|
||||
- Card, collegamenti e dipendenze hanno un'unica fonte autorevole PostgreSQL;
|
||||
la rigenerazione di Qdrant conserva il contenuto corrente e le cancellazioni.
|
||||
- I collegamenti sono curabili nel riepilogo e in Administration; cancellare una
|
||||
card elimina i suoi collegamenti senza cancellare altre card.
|
||||
@@ -0,0 +1,112 @@
|
||||
# X1 — validation of session archive corrections
|
||||
|
||||
Date: 2026-09-09. The joint Memory/Evidence repair increment is implemented.
|
||||
The authoritative contract is [Session archive corrections](../contracts/archive-repair.md).
|
||||
|
||||
## Delivered behavior
|
||||
|
||||
The session gate shows complete before/after content for specific alternatives targeting
|
||||
Memory or Evidence. The reviewer chooses one correction or rejects all proposals as
|
||||
inadequate and requests reformulation. The resulting receipt survives interruption;
|
||||
saved content and index activation are reported separately. Pending activation offers
|
||||
retry of the same chosen operation. A subsequent curator change blocks replay.
|
||||
|
||||
Application requires an administrator in the harness and the responding browser
|
||||
principal's archive-management permission. Cross-principal runtime responses cannot
|
||||
misattribute the correction. A non-administrator can decline or continue the current
|
||||
question without modifying shared archives. The gate does not advance a workflow phase.
|
||||
|
||||
Memory and Evidence remain separate domains. The integration coordinator reuses their
|
||||
canonical persistence and activation operations. A session Evidence correction requires
|
||||
a consolidated archive, preserves source lineage, and cannot publish unrelated external
|
||||
edits. Existing administration, source import, dependency cleanup and final Memory review
|
||||
remain available. No automatic Git commit or push was added.
|
||||
|
||||
## Verification
|
||||
|
||||
- Harness regression: **1,264 passed**, one skipped, five deselected. All **nine**
|
||||
portable-path checks passed separately without `THT_HOME`. Python lint passed on changed modules.
|
||||
- Backend: **1,366 passed**, 40 skipped. Tests include actual session-response routes
|
||||
for both target archives, unauthorized response, malformed choice and runtime ownership.
|
||||
- Frontend: complete suite **645 passed**; the final display adjustment passed all four
|
||||
focused widget tests. Backend and frontend TypeScript checks passed.
|
||||
- Pi extension: **199 passed**, including closed human choices, rejection, failure/retry,
|
||||
forged selections and the updated public tool schema. The modular skill projection is
|
||||
byte-identical to its updated approved template.
|
||||
- PostgreSQL/Qdrant integration traverses the actual Python CLI for preparation,
|
||||
application and recovery inspection. Corrected Memory and Evidence are retrieved from
|
||||
real indexes, and Evidence activation preserves the Memory card. Session loading is a
|
||||
controlled fixture and embeddings are deterministic; this is not an LLM quality test.
|
||||
- Failure tests cover both targets, index outage, replay, later edits, workspace/session
|
||||
isolation, changed session context, rejection, non-admin writes, and interruption after
|
||||
the Evidence file write but before its saved receipt.
|
||||
- Playwright desktop/mobile: **one passed**. The real widget renders both alternatives,
|
||||
accepts an Evidence choice, displays pending activation and allows retry to active.
|
||||
No page errors or mobile horizontal overflow. Screenshots are
|
||||
`/private/tmp/thothii-x1-repair-desktop.png` and `/private/tmp/thothii-x1-repair-mobile.png`.
|
||||
This browser fixture controls operation outcomes; persistent behavior is tested above.
|
||||
- Strict MkDocs build and `git diff --check` passed.
|
||||
|
||||
## Local installation and reviewer acceptance
|
||||
|
||||
Core and frontend images were rebuilt from this worktree using the existing local
|
||||
preview launcher. Migration `004_archive_repairs.sql` was applied to the existing
|
||||
installation catalog. The new gate is available to session workflows; it is not an
|
||||
always-visible administration panel. Existing PSD archive content was not changed by
|
||||
the synthetic validation cases.
|
||||
All five local services are healthy at `http://127.0.0.1:8080/`.
|
||||
|
||||
The technical increments and their planned checks are complete. The end-user acceptance
|
||||
check remains a real session containing a meaningful domain conflict, with the reviewer
|
||||
evaluating the proposed correction. Automated browser validation uses temporary accounts
|
||||
and data, not the user's authenticated PSD session. Source import retains its E3
|
||||
validation boundaries; no broader model-quality benchmark was added.
|
||||
|
||||
## Follow-up acceptance: configured model
|
||||
|
||||
The opt-in `test_real_model_proposes_a_reviewable_persistent_archive_correction`
|
||||
passed with the installation's **zai/glm-5.3** model. Synthetic Memory asserted an
|
||||
order-ID-only join; synthetic Evidence required the financial year too. The model
|
||||
returned two schema-valid, specific alternatives with complete content and the exact
|
||||
target revisions. The test reviewer selected Memory, persisted the correction through
|
||||
the real coordinator and PostgreSQL, and retrieved the updated rule. Evidence stayed
|
||||
unchanged. This test uses deterministic vectors and the configured completion helper;
|
||||
it does not claim a full autonomous Pi session or human acceptance of PSD semantics.
|
||||
|
||||
The run log is `/private/tmp/x1-acceptance-model.log`. Reproduce with
|
||||
`THT_MEMORY_L2_INSTALLATION=<installation.yaml>` and `THT_MEMORY_L2_CORE=<core-container>`
|
||||
using `pytest -q -s -m l2 tests/memory/test_administration.py -k real_model_proposes`.
|
||||
Credentials are resolved inside core and are not returned to the test runner.
|
||||
|
||||
## Follow-up acceptance: both administration pages
|
||||
|
||||
The opt-in `frontend/e2e/memory-real.spec.ts` passed through real authentication,
|
||||
Fastify, ThtRunner, Python, isolated PostgreSQL and Qdrant. It verifies:
|
||||
|
||||
- Database management, Memory management and Evidence management appear as peers in
|
||||
that order, with no active core session or DWH binding required.
|
||||
- Memory creation, editing, persistence across backend restart, deletion and absence
|
||||
from subsequent recall.
|
||||
- Canonical Evidence remains intact after the Memory deletion. Its full rule is read
|
||||
through the real Evidence administration worker; content filtering finds it and an
|
||||
unmatched filter produces the empty state.
|
||||
- Requests for an unregistered workspace return 404 for both archives.
|
||||
- Desktop and mobile Evidence views render without horizontal document overflow.
|
||||
On phones, both archive pages have at least 380px of usable width at a 390px viewport.
|
||||
Navigation opens in the shared accessible dialog, closes with Escape or archive selection,
|
||||
and returns focus to the trigger after Escape.
|
||||
|
||||
The temporary PostgreSQL readiness probe now waits for TCP, avoiding the image's
|
||||
socket-only initialization server. The browser waits for Memory refresh to finish
|
||||
before leaving its page, matching the existing navigation guard. Visual inspection
|
||||
also exposed a real mobile layout issue: the fixed sidebar left only 134px for the
|
||||
Evidence page. `ArchiveNavigation` now moves that sidebar into the shared dialog below
|
||||
768px on Memory/Evidence pages. Desktop behavior is unchanged. The frontend image
|
||||
was rebuilt for the local preview.
|
||||
|
||||
Run log: `/private/tmp/x1-acceptance-browser7.log` (**one passed**).
|
||||
Screenshots: `/private/tmp/thothii-acceptance-evidence-desktop.png` and
|
||||
`/private/tmp/thothii-acceptance-evidence-mobile.png`. Reproduce with
|
||||
`THT_MEMORY_BROWSER_E2E=1 npx playwright test e2e/memory-real.spec.ts` from `frontend/`.
|
||||
The fixture removes its temporary containers, accounts and checkout on completion.
|
||||
The TypeScript check, Python lint, strict documentation build and diff check also pass.
|
||||
@@ -0,0 +1,67 @@
|
||||
# Evidence E1 — validation
|
||||
|
||||
Date: 2026-09-09. Scope: editable Curated Evidence v4 and the persistent local archive.
|
||||
|
||||
## Implemented behavior
|
||||
|
||||
- Parser, renderer, authoring output and normalization share the existing typed payloads.
|
||||
Visible Markdown edits determine content for all eight kinds. Legacy v1–v3 conversion
|
||||
is explicit and lossless, with errors for content that cannot be represented exactly.
|
||||
- Manual declarations record the curator. A correction preserves the original document
|
||||
as lineage, separately from the current declaration. No source hash is needed to
|
||||
create a manual file.
|
||||
- The local archive records baselines, immutable candidates, active revisions and
|
||||
deletion/source suppression metadata. Unresolved review items and invalid edits block
|
||||
consolidation. Missing archive directories are availability failures, not deletions.
|
||||
- Activation failures preserve the previous active revision. Interrupted normalization
|
||||
replays only unchanged input bytes; later operator edits survive recovery.
|
||||
- Revision-checked correction methods reject stale workflow updates. Legacy preparation
|
||||
and resolution cannot overwrite an initialized local archive; explicit import/refresh
|
||||
integration is deferred to E3.
|
||||
|
||||
## Verification
|
||||
|
||||
The final harness suite excluding opt-in L0/L2 and portable-layout cases passed with
|
||||
**1,180 tests** (58 deselected). All **9 portable-layout tests** passed separately with
|
||||
`THT_HOME` unset. The dedicated real-Qdrant integration test passed, including the
|
||||
optional 35-unit PSD probe. Ruff passed on the changed Evidence implementation and
|
||||
tests, and the strict documentation build succeeded. No frontend or backend TypeScript
|
||||
changes are part of E1.
|
||||
|
||||
The integration test uses an isolated Qdrant 1.18.2 container, the actual corpus
|
||||
pipeline, semantic chunking, vector adapter and active Evidence searcher. Deterministic
|
||||
three-dimensional embeddings isolate file/content correctness from model behavior.
|
||||
It verifies that raw edits do not change recall, consolidation updates recalled content
|
||||
and curator identity, a blocked candidate preserves prior recall, and deletions remove
|
||||
recall. Existing schema and Memory records survive each operation.
|
||||
|
||||
All **35 PSD units** were copied from the owner's workspace into
|
||||
`/private/tmp/thothii-e1-psd.bsW4cp`. Deterministic conversion preserved every ID, payload,
|
||||
scope, provenance and review item. There were no unresolved review items. The optional
|
||||
integration probe then indexed all 35 converted units and compared their complete ID
|
||||
set to the original. It uses PSD's actual `max_chunk_chars: 5000`; a preliminary probe
|
||||
at 4000 correctly blocked an oversized atomic unit.
|
||||
|
||||
Reproduce the isolated real-corpus probe after creating a converted workspace copy:
|
||||
|
||||
```sh
|
||||
cd harness
|
||||
THT_E1_PSD_COPY=/absolute/path/to/converted-copy \
|
||||
.venv/bin/pytest -q -s tests/test_evidence_editable_integration.py
|
||||
```
|
||||
|
||||
The environment variable is optional. Ordinary CI uses only synthetic Evidence. No
|
||||
source refresh, external document download, DWH call or model request is involved.
|
||||
|
||||
## Delivery boundary
|
||||
|
||||
E1 is a core/library increment. E2 must add the installed manual consolidation command,
|
||||
connect runtime source selection to the active local snapshot, and build administrative
|
||||
list/filter/detail with real persistent host paths and manual Git instructions. E3
|
||||
adds source acquisition and explicit refresh/conflict handling. X1 later wires deliberate
|
||||
joint Memory/Evidence corrections into review gates.
|
||||
|
||||
The actual PSD Evidence checkout was not converted. The live Docker preview at
|
||||
`http://127.0.0.1:8080` remains the previously deployed M3 stack, with no new Evidence
|
||||
administration page. The corpus conversion and reindexing described here used copies
|
||||
and disposable test resources.
|
||||
@@ -0,0 +1,86 @@
|
||||
# Evidence E2 — validation
|
||||
|
||||
Date: 2026-09-09. E2 is implemented locally and installed on the existing Docker preview.
|
||||
E3 source imports/refresh and X1 deliberate Memory/Evidence workflow corrections remain open.
|
||||
|
||||
## Delivered behavior
|
||||
|
||||
- Independent **Administration → Evidence management**, after Memory, protected by
|
||||
`evidence.manage`: complete typed content, provenance and original excerpts, review items,
|
||||
pagination, search, kind/purpose/status and scope/source filters, sort, and refresh.
|
||||
- Working-file states distinguish active, modified, new, removed, invalid, legacy and review
|
||||
required. Detail shows the actual configured host path with copy controls. Instructions
|
||||
cover external editing, all eight Markdown templates, consolidation and manual Git.
|
||||
- Installed `tht workspace evidence consolidate --workspace <id> [--json]` uses a closed
|
||||
maintenance envelope. First use converts legacy units. Validation, immutable candidates,
|
||||
activation and retry run through the existing corpus pipeline without a DWH scan or Git.
|
||||
- Runtime and ordinary preprocessing consume the active local snapshot. Unconsolidated
|
||||
edits remain excluded. Catalog/Schema readiness is not advanced by this operation.
|
||||
Clear preserves curated files, archive metadata and Memory; full preprocessing must
|
||||
recreate the missing Reference/Schema derivations afterward.
|
||||
- Immutable runtime lease filenames now identify rendered bytes as well as logical input
|
||||
identity. This fixes upgrades colliding with old runtime files without changing Catalog
|
||||
fingerprints or removing the checks against tampered files.
|
||||
|
||||
## Automated checks
|
||||
|
||||
The complete backend suite passed: **1,355 tests**, 40 skipped. The complete frontend
|
||||
suite passed: **639 tests**. Both TypeScript checks passed. Native Go workspace operation
|
||||
and CLI tests passed, including rejection of arbitrary consolidation flags. Ruff passed
|
||||
for changed Python implementation and test files.
|
||||
|
||||
The harness run passed **1,248 tests**, with one skipped and five deselected. Its three
|
||||
portable-path tests failed because that run deliberately set `THT_HOME` to the test
|
||||
runtime; rerunning the portable tests with `THT_HOME` unset passed. The final focused
|
||||
administration/path suite passed all 18 tests, including actionable migration errors and invalid
|
||||
consolidation combinations rejected before cleanup or indexing.
|
||||
|
||||
The real-Qdrant integration test exercised the actual harness consolidation CLI with
|
||||
deterministic embeddings: all 35 PSD units converted and indexed with stable identities;
|
||||
active-only source selection; separate Schema and Memory canaries; Clear and rebuild
|
||||
from the retained snapshot. Unit tests cover validation, saved-but-unindexed failure,
|
||||
retry, browsing/filtering, no automatic Git, and no Catalog mutation from consolidation.
|
||||
|
||||
A temporary Git repository and bare local remote exercise the documented manual sequence:
|
||||
edit, add and remove files, consolidate, inspect, stage the complete Evidence tree,
|
||||
commit, push and clone. The clone retains changed content, additions, deletions, managed
|
||||
metadata and an accessible active snapshot. No remote user repository was pushed.
|
||||
|
||||
## Installed preview
|
||||
|
||||
The existing Compose project is `thothii-18998cca7b0a`, at `http://127.0.0.1:8080`.
|
||||
The persistent editable checkout is:
|
||||
|
||||
```text
|
||||
/Users/mp/projects/ThothII/deploy/psd/evidence-registry/repo/psd-clinical/evidence
|
||||
```
|
||||
|
||||
The original registry checkout was copied from its retained Docker volume. The original
|
||||
author repository was not changed. Core and maintenance share a nested host bind for
|
||||
`repo`; registry state/snapshots and all other existing data volumes were retained.
|
||||
The installation descriptor includes the existing workspace bindings and the new
|
||||
`evidence-host.yaml` override. The previous descriptor and native binary are backed up
|
||||
at `/private/tmp/thothii-installation-before-e2.yaml` and `/private/tmp/tht-before-e2`.
|
||||
|
||||
The real installed command succeeded with **35 documents, 35 chunks, 35 changed, zero
|
||||
removed**, using the configured embedding service and Qdrant. A second run succeeded
|
||||
with **35 unchanged, zero changed**. Reading the actual archive from core returned
|
||||
35 active units and no file errors. All five long-running services are healthy.
|
||||
Only the Evidence stage ran. The strict documentation build and `git diff --check`
|
||||
also passed. The stack launcher is `bash /private/tmp/thothii-memory-preview.sh`; keep its
|
||||
worktree image-build override until this branch is integrated into the main checkout.
|
||||
|
||||
Browser verification reached the local login page. The saved administrator password
|
||||
does not match the current account hash, so the authenticated visual check remains
|
||||
manual. No account or password was modified. React interaction tests cover navigation,
|
||||
detail, host paths, templates, filtering, pending activation and invalid files.
|
||||
|
||||
## Boundaries
|
||||
|
||||
There is no web content editor, watcher, automatic commit/push, or implicit source refresh.
|
||||
The API exposes administration reads and consolidation; the archive's revision-checked
|
||||
save/remove operations remain available for the later explicit workflow corrections.
|
||||
These gates are not claimed as implemented by E2. Initialized local archives retain
|
||||
structural/review checks but bypass the legacy fixed retrieval-evaluation fixture so
|
||||
its old expected IDs cannot veto deliberate deletions. A general retrieval benchmark
|
||||
is outside the agreed scope.
|
||||
@@ -0,0 +1,100 @@
|
||||
# Evidence E3 — validation
|
||||
|
||||
Date: 2026-09-09. Explicit source import/refresh and decisions are implemented. X1,
|
||||
the integration of deliberate Memory/Evidence corrections into workflow gates, remains next.
|
||||
|
||||
## Delivered behavior
|
||||
|
||||
The independent Evidence page now offers **Sources and imports**. An operator copies
|
||||
a specialist's draft into `evidence/incoming/`, then explicitly imports/refreshes.
|
||||
Original local Markdown and configured HTTP/S3 sources use existing read-only adapters.
|
||||
Acquisition retains raw bytes, source identity and versioned normalized documents.
|
||||
The existing Pi authoring refiner prepares typed, editable v4 proposals.
|
||||
|
||||
Unchanged hashes skip refinement. All source acquisitions/refinements must succeed
|
||||
before saving a new set of comparisons. Missing sources are recorded as unavailable,
|
||||
never interpreted as permission to delete. No runtime lookup, ordinary consolidation
|
||||
or preprocessing triggers remote refresh once the local archive is initialized.
|
||||
|
||||
The administrator sees current and proposed units, scope, content, excerpts, review
|
||||
items and explicit retirement IDs. **Keep local Evidence** records the retained wording
|
||||
as a manual declaration with original lineage. **Use proposed Evidence** adopts the
|
||||
proposal and its source version. Both save and activate through the existing archive
|
||||
and corpus pipeline; review items block adoption. Comparisons use optimistic checks
|
||||
on affected file bytes. Interrupted decisions have a durable replay journal and retry
|
||||
without reacquisition, while intervening external edits are preserved and reported.
|
||||
|
||||
Deleted IDs remain reserved. New model-generated identities from sources with curated
|
||||
deletions are also conservatively suppressed; surviving IDs can still receive reviewed
|
||||
updates. Deliberate new knowledge can be authored as a manual file. This mechanical
|
||||
protection does not depend on the model detecting semantic duplication or contradictions.
|
||||
|
||||
Installed commands are `workspace evidence refresh` and `workspace evidence decide`,
|
||||
alongside E2 consolidation. Decision envelopes carry a source identity, comparison
|
||||
revision and keep/replace choice. Extra URLs, arbitrary paths, forged actors and unknown
|
||||
fields are rejected at the public API/CLI boundary. HTTP requests bind the authenticated
|
||||
curator. Source operations do not mutate Catalog readiness or run DWH/schema stages.
|
||||
The Python source worker is internal; the workflow CLI's visible surface is preserved.
|
||||
|
||||
## Checks
|
||||
|
||||
- Complete backend suite: **1,359 passed**, 40 skipped. Complete frontend suite:
|
||||
**641 passed**. Both TypeScript checks passed; native Go CLI/workspace tests passed.
|
||||
- Harness regression run: **1,256 passed**, one skipped and five deselected, with
|
||||
portable-path tests run separately without `THT_HOME`. All **24 focused import,
|
||||
CLI-surface and portable-path checks** passed. These
|
||||
cover import, unchanged refresh, access failure, missing source, manual correction,
|
||||
keep/replace, deletion suppression, stale comparisons, failure/retry and interrupted
|
||||
journal writes. Ruff passed on the changed Python implementation and tests.
|
||||
- The real-Qdrant test traverses the actual harness source CLI with deterministic
|
||||
refinement/embedding boundaries: import is absent from recall before a decision,
|
||||
accepted content becomes searchable, refreshed proposals preserve active manual
|
||||
corrections, replacement removes the former text, deletion remains absent after
|
||||
another refresh, and unrelated Schema/Memory canaries survive.
|
||||
- Source contract fixtures cover controlled HTTP and S3 identities, exact acquired
|
||||
bytes, and acquisition call counts. Existing adapter tests retain transport/egress
|
||||
coverage. The test does not claim to exercise a live S3 account.
|
||||
- React interaction tests verify explicit refresh, comparison content, exact decisions,
|
||||
saved-decision retry and failure feedback. Route tests cover admin authorization,
|
||||
workspace isolation, strict inputs and principal attribution. Service tests verify
|
||||
the trusted config file descriptor and absence of Catalog mutation.
|
||||
|
||||
## Local preview
|
||||
|
||||
Core/frontend were rebuilt for the existing `thothii-18998cca7b0a` stack. Its persistent
|
||||
archive and data volumes are retained. The native `/usr/local/bin/tht` was updated;
|
||||
the previous executable is at `/private/tmp/tht-before-e3`.
|
||||
|
||||
The installed refresh command ran against `psd-clinical` successfully: **35 unchanged
|
||||
sources, zero changed, zero pending comparisons**. All 35 source hashes matched their
|
||||
existing units, so this probe required no refinement and changed no active Evidence.
|
||||
Source registry metadata was saved locally; no Git commit or push was performed.
|
||||
|
||||
A separate synthetic draft was passed to the configured Pi/model inside core. It
|
||||
produced one domain proposal with one review item, which was not activated. The probe
|
||||
exposed a deployment issue: Python wheel modules and Pi skills live in different
|
||||
directories. The refiner now resolves resources through `THT_HARNESS_DIR`, with the
|
||||
source-tree location as its development fallback; a regression test covers this layout.
|
||||
|
||||
The corrected installed worker was then exercised end to end in a temporary workspace
|
||||
inside core, using the real configured Pi/model and a synthetic `incoming/orders.md`.
|
||||
It returned success, one changed source, one comparison and one proposal with a review
|
||||
item. The active snapshot remained absent. The temporary directory was removed on exit;
|
||||
the probe did not open the DWH or activate an index. Strict docs build and
|
||||
`git diff --check` also passed.
|
||||
|
||||
The in-app browser still showed the login page with the prior credential error.
|
||||
Authenticated visual verification remains manual; no credentials were reset or retried.
|
||||
|
||||
## Operational instructions and boundaries
|
||||
|
||||
See [Import drafts and refresh sources](../contracts/curated-evidence-v4.md#import-drafts-and-refresh-sources)
|
||||
for commands, local paths, review, retry and backup/Git requirements. Preserve the
|
||||
complete Evidence tree, including source comparisons, journals and acquired versions.
|
||||
Local activation and transfer to the remote Git repository remain separate operator steps.
|
||||
|
||||
No web content editor, automatic Git, background watcher, new job queue, general
|
||||
retrieval benchmark or automatic source merge was introduced. Review/refinement is
|
||||
sequential and bounded by per-source limits plus 200 documents/100 MiB per refresh.
|
||||
New changed-source decisions and failure scenarios use isolated test data; live PSD
|
||||
curated content was kept unchanged. X1 is not included in this increment.
|
||||
@@ -0,0 +1,96 @@
|
||||
# M2 — Ricerca ibrida e collegamenti
|
||||
|
||||
Data: 2026-09-09. Implementazione locale dell'incremento M2 del
|
||||
[piano Memory approvato](2026-09-08-memory-management.md#piano-esecutivo).
|
||||
|
||||
## Risultato
|
||||
|
||||
La ricerca Memory ed exemplar usa embedding dense e BM25 in Qdrant. I filtri sono
|
||||
applicati in entrambi i rami prima della selezione dei candidati. Il core espande
|
||||
i collegamenti uscenti, deduplica, limita cicli e visite, riordina insieme i risultati
|
||||
e restituisce il contenuto corrente verificato in PostgreSQL. Non usa un database
|
||||
a grafo né una chiamata LLM per il riordinamento.
|
||||
|
||||
Il contesto fisico distingue database, schema, tabella e colonna e richiede che
|
||||
corrispondano alla stessa dipendenza strutturata. Le card senza dipendenze valgono
|
||||
per il workspace; un riferimento a un antenato fisico si applica ai suoi discendenti.
|
||||
Ambito descrittivo e concetti possono restringere ulteriormente la ricerca tramite
|
||||
`--filters`. La CLI impedisce di sostituire database/schema del runtime. Il dettaglio
|
||||
dei limiti e della formula di ranking è nel [contratto operativo](../gestione-memory.md#hybrid-recall-and-links).
|
||||
|
||||
L'incremento conserva i confini dei gate correnti: F2 riceve chiarimenti di dominio,
|
||||
gli exemplar restano consultativi. Un collegamento non autorizza a consumare una
|
||||
famiglia diversa o una card fuori ambito. Il riepilogo finale, i nuovi gate e la
|
||||
pulizia delle dipendenze dopo sincronizzazione fisica appartengono a M3.
|
||||
|
||||
## Transizione e recupero
|
||||
|
||||
La migrazione versionata `002_hybrid_projection.sql` aggiunge il formato delle
|
||||
proiezioni. Le card M1 restano autorevoli e consultabili; le loro proiezioni dense
|
||||
risultano pendenti e non possono alimentare il recall. Un retry esplicito o
|
||||
`tht memory index -c <runtime.yaml>` costruisce dense e BM25 dal contenuto corrente.
|
||||
Il formato della proiezione e la revisione della card sono verificati prima dell'uso.
|
||||
|
||||
Il salvataggio può aggiungere il vettore sparse mancante nella sola collezione
|
||||
Memory. Non sostituisce configurazioni incompatibili e non modifica Reference.
|
||||
Il rebuild esplicito ricrea anche una collezione Memory assente; il test elimina
|
||||
la collezione, ricostruisce da PostgreSQL e verifica il ritorno della sola card conservata.
|
||||
Fallimenti lasciano il lavoro di propagazione persistito e recuperabile. Nessuna
|
||||
importazione da JSONL, sessioni storiche o vecchi payload Qdrant.
|
||||
|
||||
## Verifiche
|
||||
|
||||
| Controllo | Esito |
|
||||
| --- | --- |
|
||||
| Suite harness senza L0/L2, escluso il file dei percorsi portabili | 1.152 test passati nell'esecuzione finale. |
|
||||
| Suite mirata Memory, adapter e CLI, con embedding reale | 78 test passati. |
|
||||
| Verifica aggiuntiva del rebuild con collezione assente e adapter | 54 passati; il solo test del modello reale era escluso in questa riesecuzione. |
|
||||
| API Fastify Memory | 13 test passati, compresa propagazione della lingua del workspace. |
|
||||
| Browser amministrativo integrato | Passato: creazione, modifica, riavvio, rilettura, cancellazione e verifica del recall. |
|
||||
| Wheel e casi CLI | 10 test passati; il wheel include entrambe le migrazioni Memory. |
|
||||
| Build e controlli statici | Build/typecheck backend, Ruff sui file Python interessati e build documentale strict passati. |
|
||||
|
||||
- Test deterministici: collegamenti necessari, contenuto corrente, duplicati,
|
||||
cicli, profondità e limiti, card mancanti o pendenti, rifiuti già registrati,
|
||||
famiglie e ambiti esclusi, dipendenze omonime e filtri CLI vincolati al runtime.
|
||||
- Adapter: stesso filtro nei prefetch dense/BM25 per Memory ed exemplar; restano
|
||||
coperti i contratti Evidence esistenti.
|
||||
- PostgreSQL/Qdrant: salvataggio, modifica, cambio famiglia, cancellazione,
|
||||
ricostruzione, riferimento separato, isolamento, RLS, errori, retry e transizione
|
||||
delle proiezioni M1 al formato ibrido.
|
||||
- Recupero effettivo: client Ollama di produzione con il modello configurato
|
||||
`qwen3-embedding:0.6b`, dimensione 1024, e Qdrant dell'immagine fissata in Compose.
|
||||
La domanda sulla chiave commessa fra esercizi recupera la regola attesa e la
|
||||
granularità collegata, escludendo un altro database, un altro ambito e dipendenze
|
||||
che corrispondono soltanto combinando riferimenti distinti. Verifica separatamente
|
||||
dense, BM25 e fusione, poi recall, cancellazione e rebuild.
|
||||
|
||||
Il test effettivo avvia un processo Ollama separato, montando il volume del modello
|
||||
installato in sola lettura. PostgreSQL e Qdrant sono container temporanei dedicati,
|
||||
eliminati a fine test. Non usa ID di risultati predisposti. Il browser amministrativo
|
||||
usa invece embedding deterministici: verifica il collegamento fra UI, autenticazione,
|
||||
Fastify, ThtRunner e persistenza, senza essere una misura di qualità del recupero.
|
||||
|
||||
Non è una valutazione generale della qualità semantica su un corpus di produzione;
|
||||
verifica i casi di recupero richiesti da M2, con il percorso reale configurato.
|
||||
|
||||
## Riproduzione
|
||||
|
||||
Dalla directory `harness`, con Docker disponibile:
|
||||
|
||||
```sh
|
||||
THT_HOME=/private/tmp/thothii-m2-test-home \
|
||||
THT_MEMORY_TEST_OLLAMA_VOLUME=<volume-modelli-installazione> \
|
||||
THT_MEMORY_TEST_MODEL=qwen3-embedding:0.6b \
|
||||
THT_MEMORY_TEST_DIMENSIONS=1024 \
|
||||
.venv/bin/pytest -q tests/memory/test_administration.py \
|
||||
tests/memory/test_retrieval.py tests/memory/test_recall.py \
|
||||
tests/test_qdrant_vector_store.py tests/test_solved_search_cli.py
|
||||
```
|
||||
|
||||
Senza il volume esplicito, il solo test con modello reale viene escluso; gli altri
|
||||
test restano eseguibili. Il volume deve contenere il modello indicato. Le immagini
|
||||
Qdrant e Ollama del test sono lette da `compose.yaml`.
|
||||
|
||||
Consegna locale: non sono stati eseguiti deploy, migrazioni delle installazioni
|
||||
attive o aggiornamenti remoti dell'issue tracker.
|
||||
@@ -0,0 +1,78 @@
|
||||
# Memory M3 — validation
|
||||
|
||||
Implemented on 2026-09-09 in the rapid-harbor worktree.
|
||||
|
||||
## Delivered behavior
|
||||
|
||||
- F8 presents an editable summary of proposed additions, explicit updates and links.
|
||||
Only selected content is saved, including the optional solved-question exemplar.
|
||||
- Proposals reference effective approved decisions. Exact existing content is reused.
|
||||
Concurrent edits invalidate an update; manual identities and origins are preserved.
|
||||
- Selected cards and links commit atomically. Durable receipts recover repeat delivery
|
||||
and the gap before the session review marker. Finalization does not add Memory.
|
||||
- F4/F6/F7 retrieve SQL rules and explained errors for the existing approval gates.
|
||||
Retrieval is consultative and does not write an approval decision.
|
||||
- Successful Catalog physical sync deletes cards with matching removed dependencies.
|
||||
The same Catalog transaction marks pending Memory cleanup. Retry keeps the original
|
||||
removals and does not rescan; deletion receipts and projection tombstones survive restarts.
|
||||
- Migration 003 adds minimal review and physical-cleanup receipts.
|
||||
|
||||
## Executed checks
|
||||
|
||||
| Check | Result |
|
||||
| --- | --- |
|
||||
| Harness deterministic suite, excluding portable-path environment cases | 1,152 passed |
|
||||
| Portable-path suite without the temporary THT_HOME override | 9 passed |
|
||||
| Memory service/retrieval with isolated PostgreSQL and Qdrant | 41 passed, 1 optional real-embedding case skipped, 1 L2 case excluded |
|
||||
| Pi gate suite | 195 passed |
|
||||
| Backend full suite | 1,346 passed; one auth timing test exceeded 5 seconds under concurrent load |
|
||||
| Isolated auth and Catalog route rerun | All 40 passed, including the timed-out case |
|
||||
| Catalog PostgreSQL integration after adding atomic cleanup-marker coverage | All 5 passed |
|
||||
| Frontend full suite | 635 passed |
|
||||
| Chromium summary review, desktop and 390px mobile | Passed; no page errors or horizontal overflow |
|
||||
| Configured real GLM 5.3 generation | Passed on synthetic PostgreSQL data |
|
||||
| Backend/frontend production builds, modified Python lint, strict docs build | Passed |
|
||||
|
||||
The existing local Docker preview was rebuilt from this worktree, migration 003
|
||||
was applied, and core/frontend were recreated with the existing persistent volumes.
|
||||
The preview remains at `http://127.0.0.1:8080`.
|
||||
|
||||
The browser check uses the production widget in an isolated Vite fixture. It edits
|
||||
the rule, declines the exemplar, submits only the selected card and checks responsive
|
||||
layout. Gate tests separately verify request ordering through the production Pi
|
||||
composition root; service and Catalog tests use real PostgreSQL. This is not a claim
|
||||
of an automated complete live Pi conversation.
|
||||
|
||||
The L2 case retrieves an approved SQL rule, excludes a card bound to another database,
|
||||
and asks the configured GLM 5.3 model to generate a query. Order IDs repeat between
|
||||
financial years; the correct composite join returns 120 on the synthetic fixture.
|
||||
The generated SQL is validated and executed in a read-only PostgreSQL transaction.
|
||||
No real DWH rows are sent. Embeddings in this case are deterministic; the real
|
||||
embedding/hybrid retrieval evidence remains documented in M2.
|
||||
|
||||
## Reproduction
|
||||
|
||||
From the harness:
|
||||
|
||||
```sh
|
||||
THT_HOME=/private/tmp/thothii-m1-harness-home .venv/bin/pytest -q -m 'not l0 and not l2' --ignore=tests/test_portable_paths.py
|
||||
.venv/bin/pytest -q tests/test_portable_paths.py
|
||||
THT_HOME=/private/tmp/thothii-m1-harness-home .venv/bin/pytest -q tests/memory/test_administration.py tests/memory/test_retrieval.py -m 'not l2'
|
||||
npm test
|
||||
```
|
||||
|
||||
The optional generation case requires an installation YAML path and its running
|
||||
core container. It resolves the model credential inside core without printing it:
|
||||
|
||||
```sh
|
||||
THT_MEMORY_L2_INSTALLATION=<installation.yaml> THT_MEMORY_L2_CORE=<core-container> \
|
||||
.venv/bin/pytest -q -s -m l2 tests/memory/test_administration.py -k real_model
|
||||
```
|
||||
|
||||
From frontend: `npx playwright test e2e/memory-review.spec.ts`.
|
||||
Screenshots are written to `/private/tmp/thothii-m3-summary-desktop.png` and
|
||||
`/private/tmp/thothii-m3-summary-mobile.png`.
|
||||
|
||||
Evidence authoring and the joint X1 persistent Memory/Evidence conflict repair remain
|
||||
outside M3. This increment does not infer knowledge from unexplained failures or
|
||||
promise general improvements in SQL-generation accuracy.
|
||||
Reference in New Issue
Block a user