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
@@ -27,3 +27,27 @@ Task 9: PASS at frozen SHA `0c4ff3750d3ecd3fc514e50e511cf7475fbe0446`. Built and
 Task 10: NOT STARTED and requires a second explicit authorization. Public Nginx cutover, Mac-key delivery/configuration, and legacy revocation have not occurred. Activity 1 remains `IN_DISCUSSION`; external deployment remains `SURVEY_NO_GO`.

 Final clarification (bookkeeping): initial authorization at `6499d24` stopped before installation because the protected legacy file was missing and a journal-scan finding remained. A secret-safe legacy file was prepared without emit/hash; Nginx metadata remained unchanged and `nginx -t` PASS. Fix commits `6fb4886`, `dee0f9c`, `0c4ff37` received Terra PASS, followed by a detached complete re-freeze PASS at full `0c4ff3750d3ecd3fc514e50e511cf7475fbe0446`. The owner then explicitly authorized Gate 9 at that exact SHA; Gate 9 completed as recorded above. Task 10 remains a separate gate.
+
+## Project A authentication runtime projection
+
+Plan: `docs/superpowers/plans/2026-08-21-project-a-server-auth-runtime-projection.md`
+Plan commit: `64f46c7019e11a74dae35a7cdb447cd881e17061`
+Implementation baseline: `64f46c7019e11a74dae35a7cdb447cd881e17061`
+Runtime constraint: source, synthetic tests, and documentation only; Project A, `/srv`, Nginx,
+the legacy stack, and shared services remain untouched.
+
+Task 1: complete (commits `8a8f2c2`, `f9e2950`, `de86760`; independent Terra review PASS after descriptor-relative rewrite, full-history validation, crash recovery, destructive replacement guards, deterministic failure seams, and interrupted-retention recovery).
+Task 2: complete (commits `05f8615`, `da2f4a6`, `1e2c4e6`; independent review PASS after exact GID enforcement, bounded descriptor-bound namespace enumeration, strict trailing-slash parity, OIDC coverage, and complete one-retry `CURRENT` publication linearization).
+Task 3: complete (commit `903c0b4`; independent Terra review PASS after retained-FD outer locking, cancellable runtime/canonical waits, public transaction-context propagation, deterministic swap/metadata/creator-race tests, and fail-closed pre/post-commit error handling).
+Task 4: complete (commit `3d9a9f0`; independent Terra review PASS after moving the Linux/root restore gate before secret-bearing checkpoint creation). Exact focused Go, race, vet, Node 24 focused/full, TypeScript, projected Compose, secret-policy, Windows backup compile, and full serialized tools/tht gates PASS. Historical canonical/unified Compose failures were reproduced as baseline-only documentation/path coupling failures and were not weakened.
+Task 5: complete (commit `ef7ae70`; independent Terra review PASS after read-only Vitest gate repair,
+remote-Docker/context hardening, and adversarial canonical-mount/`sudo printenv` verifier fixes).
+All 14 cross-layer acceptance cases, documentation verifiers, shell syntax, full Go/race/vet,
+backend Node 24 Vitest/typecheck, projected Compose, and secret-policy gates PASS. The three known
+default/canonical/unified Compose policy failures were reproduced at `a21e2c1` and remain
+unmodified baseline debt. Project A has not been started; applying the descriptor or any runtime
+root under `/srv/thothii` still requires a new explicit authorization.
+Final Project A source review: PASS for `a21e2c1..ef7ae70`; independent Terra review found no
+remaining Critical or Important issue after validating restore admission/order, backend path and
+identity controls, transaction cancellation, lifecycle gating, portability, dependency scope, and
+redaction. Pre-live stop boundary remains in force.
@@ -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]]