# 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 `-reference`, mentre `memory` e `solved_question` restano in `-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//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-`; 3. `--project-directory `; 4. `--env-file `; 5. `-f /compose.yaml`; 6. `-f /deploy/compose.server.yaml`; 7. ogni override dichiarato, nello stesso ordine; 8. `-f /generated/compose.models.yaml`; 9. `-f /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.