docs(deploy): document user-owned session cutover

PROJECT_STATE.md

@@ -3,6 +3,28 @@
 > Starting-point snapshot for new sessions. Last updated: 2026-07-15 (central live log and compact CTE density live).
 > Point a fresh session here ("read PROJECT_STATE.md") before substantial work.
 
+## User-owned sessions cutover — prepared, manual gate pending (2026-07-16)
+
+- **Target contract:** the public server runs `AUTH_MODE=upstream` with Task 4 portal identity
+  forwarding and Task 5 principal enforcement deployed together. Its session source of truth is
+  direct TLS-verified PostgreSQL `thoth_sessions`; local development remains loopback-only with
+  filesystem sessions under `THT_HOME`. The core never receives the migrator credential.
+- **Deployment material:** copy `deploy/compose.session-server.yaml.example` and
+  `deploy/workspaces/server-sessions.yaml.example` into reviewed, untracked operator files. The
+  runtime password, migrator password, and CA are three separate Docker secret mounts; server
+  startup rejects public/local storage and incomplete server DB/TLS configuration.
+- **Readiness behavior:** `/health` remains the unauthenticated process liveness endpoint. Any
+  route requiring unavailable session/preferences storage returns fixed HTTP 503 before starting
+  Pi; this is intentional and must not be hidden by changing liveness to a database check.
+- **Manual cutover only:** schedule maintenance, drain Pi work, run the one-shot migrator and
+  require `pending=[]` and `drifted=[]`, then replace core and perform an authenticated storage
+  smoke. Archive/checksum the three reviewed legacy filesystem session directories before deleting
+  exactly those three with `docker/cutover-legacy-sessions.sh --delete`; no deletion has been run
+  from this repository task. Do not import their untrusted ownership.
+- **Rollback:** PostgreSQL remains the single source of truth. Revert only to a compatible fixed
+  release; never re-enable filesystem persistence, restore the archive into production, or
+  dual-write during rollback.
+
 ## Deployment — Docker locale (Profile A, co-located) — LIVE 2026-07-12
 
 ThothII gira in Docker sul server co-locato, **embedded nel portale omics_portal** a `https://aritmolab.policlinicosandonato.it/datamart-builder` (backend invisibile, tutto same-origin via nginx del portale).