docs: record PSD runtime and DWH transport state

2026-08-22 22:24:02 +02:00
parent c476c5551b
commit 09f43139d3
3 changed files with 45 additions and 0 deletions
@@ -0,0 +1,20 @@
+# PSD DWH transport
+
+- Il workspace PSD supporta `rest_api` e `postgres_direct`; il trasporto è scelto dall'installazione.
+- Il Mac usa REST/PostgREST; il ThothII installato sul server PSD usa PostgreSQL diretto.
+- Il server deve usare un ruolo DWH dedicato: `USAGE` sullo schema e `SELECT` soltanto, verificati sui grant reali.
+- La difesa read-only applicativa aggiunge: SQL strutturalmente SELECT-only, transazione `READ ONLY`, timeout, limite e rollback.
+- La credenziale DWH REST `X-API-Key` non deve essere fornita al ThothII server.
+- REST è il trasporto stabile per il Mac e per future installazioni remote che non possono aprire tunnel SSH.
+- L'autenticazione REST target deve dare a ogni installazione un'identità separata, revocabile e auditabile; una chiave globale condivisa non scala.
+- La rotazione della chiave globale esposta richiede una finestra dual-key che preservi il Mac prima della revoca.
+- Il certificato REST corrente resta invariato: è self-issued e viene presentato anche dall'endpoint esterno; i client che non lo considerano già trusted richiedono `TLS_CA_FILE`.
+- Il manuale deve coprire consegna e fingerprint della CA, scadenza/rinnovo coordinato e il fatto che i SAN correnti coprono `.it`, non `.com`.
+- Non esiste un ambiente di test PSD: le rotazioni devono usare backup, dual-key, probe read-only e rollback sull'endpoint di produzione.
+- Supabase Studio è un pannello amministrativo loopback, non un data-plane o un trasporto per ThothII.
+- Le credenziali DWH, session storage e amministrazione Supabase devono restare separate.
+- Il collegamento container→PostgreSQL deve usare un endpoint host/rete esplicito e ristretto; il loopback dell'host non è il loopback del container.
+- Il nightly ETL PSD delle 03:00 usa PostgreSQL diretto; non è un consumer della route REST `/dwh/`.
+- Un preprocessing REST Thoth genera `1 + 3T + Ct + Ce` richieste: una lista tabelle, tre RPC per tabella e due famiglie di campionamento testuale.
+- Per PSD nel run 2026-08-13: `T=163` e `Ct+Ce=1180`, quindi 1670 richieste per ciclo; undici rerun spiegano 18.370 richieste.
+- I repository server esistenti contengono materiale sensibile hardcoded: non copiarlo; inventariare, rimuovere dal tracking e ruotare i segreti coinvolti.
@@ -2,4 +2,5 @@

 - [[codebase/datamart-builder-deployment-gotchas]]
 - [[codebase/pi-model-selection]]
+- [[codebase/psd-dwh-transport]]
 - [[codebase/workflow-ui-contracts]]