feat: complete catalog-driven preprocessing
Publish documentation / publish (push) Successful in 2m12s
Publish documentation / publish (push) Successful in 2m12s
This commit is contained in:
Codex
@@ -0,0 +1,221 @@
|
||||
# Server handoff — preprocessing complete
|
||||
|
||||
Questo documento è un'istruzione operativa per il Codex eseguito sul server ThothII. Quando
|
||||
l'operatore chiede di applicarlo, eseguire i passi nell'ordine indicato e consegnare il report
|
||||
finale. La release autorizzata è il tag annotato `260906-preprocessing-complete`.
|
||||
|
||||
## Obiettivo verificabile
|
||||
|
||||
Al termine devono essere vere tutte queste condizioni:
|
||||
|
||||
- il checkout server è esattamente il commit puntato dal tag;
|
||||
- il binario host `tht` proviene dallo stesso checkout;
|
||||
- la migrazione PostgreSQL del catalogo `013_catalog_preprocessing_state` è terminata con exit 0
|
||||
prima dell'avvio del nuovo Core;
|
||||
- immagini `core` e `frontend` sono state ricostruite e i servizi sono healthy;
|
||||
- il workspace PSD ha completato il preprocessing catalog-driven;
|
||||
- Schema, relazioni ed Evidence sono in `<workspace>-reference`, mentre `memory` e
|
||||
`solved_question` restano in `<workspace>-memory`;
|
||||
- login e nuovo caricamento aprono la superficie Core.
|
||||
|
||||
## Confini operativi
|
||||
|
||||
- Conservare descriptor, env, secret, catalogo PostgreSQL, Qdrant, Memory, sessioni e repository
|
||||
workspace esistenti.
|
||||
- Non stampare descriptor completi, env, secret, connection string o log non sanitizzati.
|
||||
- Non usare `reset`, rebase, stash, prune, `down --volumes` o cancellazioni manuali.
|
||||
- Non eseguire `workspace preprocess clear`: l'upgrade richiede soltanto il normale `run`, che è
|
||||
idempotente, sostituisce i dati derivati e conserva la Memory.
|
||||
- Fermarsi davanti a worktree sporco, tag non verificabile, branch divergente, descriptor ambiguo,
|
||||
operazioni attive, migrazione fallita o servizi non healthy. Riportare l'evidenza redatta senza
|
||||
tentare correzioni distruttive.
|
||||
|
||||
## 1. Risolvere i target e fare l'inventario
|
||||
|
||||
Posizionarsi nel checkout server e valorizzare percorsi assoluti reali:
|
||||
|
||||
```bash
|
||||
THTII_REPO=$(git rev-parse --show-toplevel)
|
||||
THTII_INSTALLATION=/percorso/assoluto/thothii-installation.yaml
|
||||
THTII_RELEASE_TAG=260906-preprocessing-complete
|
||||
THTII_WORKSPACE_ID=psd-clinical
|
||||
cd "$THTII_REPO"
|
||||
```
|
||||
|
||||
Se il descriptor attivo non è identificabile univocamente dai comandi già usati sul server,
|
||||
chiederne il percorso all'operatore. Non cercare secret e non scegliere un file per somiglianza.
|
||||
|
||||
Eseguire l'inventario in sola lettura:
|
||||
|
||||
```bash
|
||||
git status --short --branch
|
||||
git branch --show-current
|
||||
git rev-parse HEAD
|
||||
git remote -v
|
||||
test -f "$THTII_INSTALLATION"
|
||||
tht --installation "$THTII_INSTALLATION" status
|
||||
```
|
||||
|
||||
Registrare il vecchio hash. Il branch deve essere `main`, il worktree deve essere pulito e `origin`
|
||||
deve puntare al Gitea autorizzato `https://git.tylconsulting.it/mptyl/ThothII.git`. Verificare che
|
||||
non siano in corso sessioni Core o preprocessing; in caso contrario fermarsi.
|
||||
|
||||
**Completamento:** checkout, descriptor, installation Compose e workspace ID sono identificati
|
||||
senza ambiguità; il server è inattivo dal punto di vista applicativo e il worktree è pulito.
|
||||
|
||||
## 2. Integrare l'esatta release
|
||||
|
||||
```bash
|
||||
cd "$THTII_REPO"
|
||||
git fetch --prune origin main
|
||||
git fetch origin tag "$THTII_RELEASE_TAG"
|
||||
test "$(git cat-file -t "$THTII_RELEASE_TAG")" = tag
|
||||
THTII_RELEASE_COMMIT=$(git rev-parse "$THTII_RELEASE_TAG^{commit}")
|
||||
git switch main
|
||||
git merge --ff-only "$THTII_RELEASE_COMMIT"
|
||||
test "$(git rev-parse HEAD)" = "$THTII_RELEASE_COMMIT"
|
||||
git status --short --branch
|
||||
```
|
||||
|
||||
Il merge deve essere fast-forward e il worktree deve restare pulito. Se `origin/main` contiene
|
||||
commit successivi al tag, non integrarli in questa esecuzione: il tag è il confine della release.
|
||||
|
||||
**Completamento:** `HEAD` coincide byte per byte con il commit del tag annotato.
|
||||
|
||||
## 3. Installare il CLI della release e validare la configurazione
|
||||
|
||||
```bash
|
||||
cd "$THTII_REPO"
|
||||
./scripts/install-tht.sh
|
||||
tht version --json
|
||||
tht --installation "$THTII_INSTALLATION" update --check-only
|
||||
```
|
||||
|
||||
Leggere strutturalmente dal descriptor i valori `projectDirectory`, `envFile`, `profile` e la lista
|
||||
ordinata `overrides`, senza mostrare contenuti protetti. Devono descrivere il checkout corrente e il
|
||||
profilo `server`. Il descriptor e l'env esistenti sono configurazione autorevole: non rigenerarli e
|
||||
non sostituirli con gli esempi del repository.
|
||||
|
||||
Se esiste `.tht/<compose-project>/current-image.yaml`, fermarsi e segnalarlo: un pin immagine
|
||||
esplicito renderebbe ambiguo il deploy dal checkout.
|
||||
|
||||
**Completamento:** il nuovo `tht` è installato, il descriptor corrente è valido e nessun pin
|
||||
immagine impedisce la ricostruzione.
|
||||
|
||||
## 4. Preparare il comando Compose dell'installation
|
||||
|
||||
Costruire un array shell `THTII_COMPOSE` con lo stesso ordine usato da `tht`:
|
||||
|
||||
1. `docker compose`;
|
||||
2. `--project-name thothii-<prime 12 cifre sha256 del percorso canonico del descriptor>`;
|
||||
3. `--project-directory <projectDirectory>`;
|
||||
4. `--env-file <envFile>`;
|
||||
5. `-f <projectDirectory>/compose.yaml`;
|
||||
6. `-f <projectDirectory>/deploy/compose.server.yaml`;
|
||||
7. ogni override dichiarato, nello stesso ordine;
|
||||
8. `-f <directory descriptor>/generated/compose.models.yaml`;
|
||||
9. `-f <projectDirectory>/deploy/compose.auth-runtime-projection.yaml` quando il descriptor ha
|
||||
`authentication.runtimeProjection`.
|
||||
|
||||
Per una installation server con Git SSH e senza altri overlay, la forma è:
|
||||
|
||||
```bash
|
||||
THTII_INSTALLATION=$(realpath "$THTII_INSTALLATION")
|
||||
THTII_INSTALL_DIR=$(dirname "$THTII_INSTALLATION")
|
||||
THTII_ENV=/percorso/assoluto/letto-da-envFile
|
||||
THTII_COMPOSE_PROJECT="thothii-$(printf '%s' "$THTII_INSTALLATION" | sha256sum | cut -c1-12)"
|
||||
THTII_COMPOSE=(
|
||||
docker compose
|
||||
--project-name "$THTII_COMPOSE_PROJECT"
|
||||
--project-directory "$THTII_REPO"
|
||||
--env-file "$THTII_ENV"
|
||||
-f "$THTII_REPO/compose.yaml"
|
||||
-f "$THTII_REPO/deploy/compose.server.yaml"
|
||||
-f "$THTII_REPO/deploy/compose.git-ssh.yaml"
|
||||
-f "$THTII_INSTALL_DIR/generated/compose.models.yaml"
|
||||
-f "$THTII_REPO/deploy/compose.auth-runtime-projection.yaml"
|
||||
)
|
||||
"${THTII_COMPOSE[@]}" config --quiet
|
||||
```
|
||||
|
||||
Adattare l'array agli override realmente dichiarati. Non usare il blocco di esempio se il
|
||||
descriptor differisce.
|
||||
|
||||
**Completamento:** `config --quiet` termina con exit 0 usando esattamente l'identità e i file della
|
||||
installation già attiva.
|
||||
|
||||
## 5. Costruire, migrare e riavviare
|
||||
|
||||
La build può avvenire mentre i vecchi container sono ancora in esecuzione: i container mantengono
|
||||
il loro image ID. Fermare Core e frontend soltanto dopo una build riuscita.
|
||||
|
||||
```bash
|
||||
"${THTII_COMPOSE[@]}" build core frontend
|
||||
"${THTII_COMPOSE[@]}" stop frontend core
|
||||
"${THTII_COMPOSE[@]}" up --detach catalog-db qdrant embedding
|
||||
"${THTII_COMPOSE[@]}" run --rm catalog-migrate
|
||||
"${THTII_COMPOSE[@]}" run --rm embedding-model-init
|
||||
tht --installation "$THTII_INSTALLATION" start
|
||||
tht --installation "$THTII_INSTALLATION" status
|
||||
tht --installation "$THTII_INSTALLATION" doctor --json
|
||||
```
|
||||
|
||||
`catalog-migrate` deve terminare con exit 0. `embedding-model-init` è one-shot: `exited (0)` è il
|
||||
suo stato corretto. Se un passo fallisce dopo lo stop, lasciare i container e i volumi disponibili
|
||||
per diagnosi e raccogliere soltanto:
|
||||
|
||||
```bash
|
||||
tht --installation "$THTII_INSTALLATION" status
|
||||
tht --installation "$THTII_INSTALLATION" logs
|
||||
```
|
||||
|
||||
**Completamento:** migrazione completata, servizi persistenti healthy e job embedding terminato con
|
||||
exit 0.
|
||||
|
||||
## 6. Eseguire una volta il preprocessing completo
|
||||
|
||||
Ispezionare prima le precondizioni:
|
||||
|
||||
```bash
|
||||
tht --installation "$THTII_INSTALLATION" \
|
||||
workspace inspect --workspace "$THTII_WORKSPACE_ID" --json
|
||||
```
|
||||
|
||||
Lo stato atteso dopo l'upgrade è `required`. Se è `blocked`, correggere soltanto il prerequisito
|
||||
indicato. Se è `running`, fermarsi perché esiste un'operazione concorrente. Se è `failed`, leggere
|
||||
il solo ultimo diagnostico e i log sanitizzati del Core prima di ritentare.
|
||||
|
||||
Quando le precondizioni sono soddisfatte, eseguire:
|
||||
|
||||
```bash
|
||||
tht --installation "$THTII_INSTALLATION" \
|
||||
workspace preprocess run --workspace "$THTII_WORKSPACE_ID" --json
|
||||
|
||||
tht --installation "$THTII_INSTALLATION" \
|
||||
workspace inspect --workspace "$THTII_WORKSPACE_ID" --json
|
||||
```
|
||||
|
||||
Il secondo inspect deve riportare il workspace pronto e la revisione metadati processata uguale a
|
||||
quella corrente. Il run legge tabelle, colonne, descrizioni, sensibilità e foreign key dal Catalogo
|
||||
PostgreSQL; il workspace YAML fornisce soltanto identità ed eventuale Evidence. Un workspace senza
|
||||
Evidence è valido. Il run effettua anche il cutover dall'eventuale collezione Qdrant legacy,
|
||||
preservando `memory` e `solved_question`.
|
||||
|
||||
**Completamento:** preprocessing riuscito una volta, Core ammesso e Memory preservata.
|
||||
|
||||
## 7. Accettazione e report
|
||||
|
||||
Verificare, senza creare una sessione reale se non richiesto dall'operatore:
|
||||
|
||||
- `git rev-parse HEAD` uguale a `git rev-parse 260906-preprocessing-complete^{commit}`;
|
||||
- worktree pulito;
|
||||
- `tht doctor --json` con esito positivo;
|
||||
- `catalog-db`, Qdrant, embedding, Core e frontend healthy;
|
||||
- ultimo `workspace inspect` pronto;
|
||||
- login o hard refresh posizionati sulla pagina Core;
|
||||
- **Administration → Preprocessing** mostra `Status: Ready` e **Run again**;
|
||||
- **New session** è abilitato.
|
||||
|
||||
Consegnare un report breve con vecchio hash, nuovo hash, tag, versione `tht`, exit della migrazione,
|
||||
stato servizi e risultato preprocessing. Redigere URL interni, nomi utente e qualsiasi dato
|
||||
operativo sensibile.
|
||||
Reference in New Issue
Block a user