# PSD Clean ThothII Replacement Design

**Date:** 2026-08-21
**Status:** Approved by the owner

## Decision

The existing PSD ThothII installation is disposable. Its sessions, settings, Pi state, derived
artifacts, indexes, images, source checkout, and application data are not migration inputs for the
new installation. They remain present only until the replacement has passed the real Aritmolab
journey; this temporary retention is a cutover safeguard, not a legacy-support requirement.

The replacement does not create a host `thothii` user or group. The image keeps its internal
UID/GID `10001:10001`. Host bind trees that the container must write may use that numeric ownership
without corresponding `/etc/passwd` or `/etc/group` entries. Source and operator-controlled files
remain owned by the existing operator `admlocforn1` (UID 1013) and the existing `chirone` group
(GID 1006).

## Boundaries

The following old ThothII resources become deletion candidates only after Project B human
acceptance proves the production Aritmolab route:

- containers `thothii-core-1` and `thothii-frontend-1`;
- images `thothii-core:local` and `thothii-frontend:local`, after proving no other container uses
  their immutable IDs;
- checkout `/home/chirone/ThothII`;
- application bind tree `/home/chirone/thothii-data`.

The following resources are shared and are never deletion candidates in the ThothII cleanup:

- Docker networks `omics_portal_omics_network` and `localllm_default`;
- `/home/chirone/chirone/etl/docs/evidence` and the ETL project;
- Omics Portal/Aritmolab source, Nginx, web, worker, sidebar, and capability configuration;
- LocalLLM API and vLLM services;
- `dwh-auth`, its credential registry, and the `/dwh/` Nginx route;
- Supabase/DWH, Authentik, Superset, and their data or configuration.

No global Docker prune, network removal, broad recursive deletion, or Compose volume deletion is
permitted. Cleanup resolves and revalidates every exact target immediately before removal.

## Sequence

1. Project A preparation creates a distinct installation under `/srv/thothii`; it does not reuse
   `/home/chirone/thothii-data`.
2. Immediately before creating bind roots, verify that UID and GID 10001 still have no host account
   mapping. A newly observed mapping is a stop condition requiring owner review.
3. Project A may stop the old containers only under its separate mutation authorization. The old
   source, data, containers, and images remain intact while the new private stack is tested.
4. Project B changes the production integration and proves the complete path:
   `Aritmolab -> sidebar -> Nginx/load balancer -> ThothII`, including frontend assets, API, SSE,
   authentication, and a completed workflow.
5. Only after the Project B automated report, human report, and owner decision are PASS may the
   exact old ThothII resources be deleted.

If Project A fails, stop the new private stack and restart the still-present old containers. If
Project B fails, close the new ingress and restore the prior route while the old resources still
exist. After Project B PASS and legacy deletion there is deliberately no promise to restore old
ThothII sessions or state.

## Host ownership model

No command may call `useradd`, `groupadd`, `usermod`, or modify the host identity databases.

- `/srv/thothii/source` and `/srv/thothii/operator`: `1013:1006`.
- `/srv/thothii/data`, `/srv/thothii/pi-state`, and `/srv/thothii/workspace-registry`:
  numeric `10001:10001`.
- protected files mounted read-only by the core: operator-owned with a narrowly selected numeric
  group/owner mode that permits UID/GID 10001 to read only the required file.
- `/srv/thothii-backups`: operator/root protected and outside the runtime write boundary.

Numeric ownership does not create or preserve a host user. It is confined to the new installation
tree and exists solely to match the non-root identity already embedded in the container image.

## Acceptance

The design is satisfied only when evidence proves all of the following:

- no host account or group was created for 10001;
- the new core runs non-root and can write only its intended runtime trees;
- the shared networks and external Evidence tree remain unchanged;
- Project A and Project B pass their independent automated and human gates;
- Aritmolab no longer resolves production traffic to `thothii-core` or `thothii-frontend` legacy
  containers before those containers are removed;
- the cleanup inventory contains only exact legacy ThothII targets and excludes every shared
  resource listed above.