ThothII/docs/operations/server-handoff-260906-preprocessing-complete.md

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:

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:

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

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

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 è:

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.

"${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:

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:

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:

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.