Documento operacional para a Fase 2.2 da Arch-ificação. Acompanha cada fase do trabalho, registra decisões, lista checkpoints de validação. Não deletar enquanto a migração não estiver 100% concluída.
## Princípios não-negociáveis
1.**Nenhuma fase pode quebrar a release anterior.** Toda mudança que move dados precisa de migration script no boot que faz `mv` ou `cp -a` + symlink de fallback, idempotente, com fail-open (se algo der errado, mantém o path antigo).
2.**Verificação por grep depois de cada arquivo alterado.** Não emendar mudanças sem ter rodado `grep -rn '/storage/<x>' projects/ packages/` e confirmado que sumiu.
3.**Variáveis primeiro, dados depois.** A vazão Arch é: introduzir `${ARCHR_X}`, fazer apontar para `/storage/<x>`, migrar scripts para usar a variável, **só depois** mudar a variável para apontar para o destino FHS.
4.**Saves e ROMs por último.** Esses são dados que o usuário não pode perder. Última fase, migration script extensivamente testado.
5.**Symlinks de compat ficam por uma release.** Removidos só na release seguinte, depois de feedback do canal `stable`.
## Classes de destino
Classificação automática dos 297 paths únicos (auditados em 2026-06-23 contra `projects/ArchR/` + `packages/`):
| **Z** | Casos especiais (assets, jdk, nfs-mount, .opt, .hatari, .emulationstation, openbor) | caso a caso | individual | ~10 |
### Por que `/var/lib/archr` e não `/home/<user>`?
ArchR roda single-user como root no boot (modelo handheld + LibreELEC). Não tem `useradd` no provisioning. `$HOME` aponta para `/root` no console, mas a maioria dos serviços do EmulationStation já roda como root também. Mover para `/home/<user>` exigiria reescrever o modelo de usuário, e isso é fora do escopo da 2.2 (vira tarefa nova quando/se for adotada).
`/var/lib/archr/<x>` mantém o single-user model existente e é onde FHS recomenda colocar "state information of programs". Quando/se um modelo multi-user for adotado, é só mudar `ARCHR_DATA` para `/home/$USER/.local/share`.
### Por que `/var/cache/archr`?
`/var/cache/<programa>` é convenção FHS, mas como ArchR tem ~30 caches diferentes (services, mesa_shader_cache, fontconfig etc.), agrupar sob `/var/cache/archr/<x>` evita poluir `/var/cache` com 30 dirs nossos. Caches "famosos" (fontconfig, mesa) ficam onde a app espera (`/var/cache/fontconfig`, `$MESA_SHADER_CACHE_DIR`).
## Plano por fases
Cada fase **termina em um commit** com mensagem `FHS Fx.y: <descrição>`. Entre fases, validação obrigatória.
### Fase 0 — Infraestrutura de variáveis (NESTE PR)
**Objetivo:** introduzir vocabulário sem mover nada. Tudo continua em `/storage`.
- [ ] Criar `/etc/profile.d/archr-fhs.sh` exportando as 7 vars, todas apontando para `/storage/...` (compat).
- [ ] Documentar variáveis em `archr(7)` man page (já existe; adicionar seção `ENVIRONMENT`).
- [ ] Adicionar fallback `${ARCHR_CONFIG:-/storage/.config}` em scripts pra detectar quando estiverem migrados.
**Verificação:**`source /etc/profile.d/archr-fhs.sh && echo $ARCHR_CONFIG` retorna `/storage/.config` no momento.
**Status: concluída como no-op (2026-06-23).** Auditoria detalhada revelou que `projects/ArchR/packages/sysutils/systemd/package.mk`**já redireciona** os paths Class A para `/etc/...` via symlinks de build-time:
No sistema rodando, `/etc/modules-load.d`, `/etc/sysctl.d`, `/etc/systemd/logind.conf.d` etc. **existem e funcionam como FHS espera**. O fato do target do symlink ser `/storage/.config` é detalhe interno do storage overlay (rootfs squashfs read-only + `/storage` rw), não dívida FHS visível ao usuário ou a ferramentas externas.
Mudar o target para algo mais Arch-friendly (ex.: `/var/lib/archr/etc/`) seria cosmético em troca de mexer no init para fazer bind-mount; o trade-off não compensa.
Hosts/resolv têm pipeline próprio (script `network-base-setup` lê
`/storage/.config/hosts.conf` e renderiza `/run/archr/hosts`); ficam onde estão pela mesma lógica.
**Resultado:** os 18 paths Class A já entregam FHS-correto sem mudança nenhuma. Foco da Fase 1 redirecionado para validação posterior em Fase 7 (auditoria final).
**Status: concluída (2026-06-23).** A classificação automática inicial colocou 44 paths em Class C, mas a inspeção revelou que a maioria é **state** (ssh, wireguard, bluetooth, iwd, services, cron, samba auth, tailscale), **logs** (log/journal, log/runemu-debug.log) ou já está redirecionada via symlink no upstream. Os paths que de fato são "cache regenerável" foram quatro:
**Padrão de implementação:** bridge symlink instalado pelo `archr` meta-package (`/var/cache/<x>` ou `/var/cache/archr/<x>` → `/storage/.cache/<x>`). Consumers leem do path Arch-friendly; writes atravessam pro overlay rw. Mesmo padrão dos symlinks que o systemd já cria para `/etc/*`.
**Já no-op (redirected por outros pacotes upstream):**
-`/storage/.cache/journald.conf.d` (symlink criado pelo systemd package)
-`/storage/.cache/systemd-machine-id` (symlink criado pelo busybox package)
-`/storage/.cache/system_timezone` (symlink criado pelo emulationstation package)
**Status: concluída (2026-06-23).** Logs viram `/var/log/*` (que já é mount unit redirecionando para `/storage/.cache/log`); update vira `/var/cache/archr/update` via bridge symlink; overlayfs workdirs e bootloader handshake ficam no backing path por constraint de arquitetura.
-`/storage/.tmp/*-workdir` (assets, cores, database, games, joypads, overlays, shaders): são *workdirs* de `overlayfs` montados em `system.d/tmp-*.mount` units. O kernel exige que `upperdir` e `workdir` estejam no mesmo filesystem; como `upperdir=/storage/<x>`, o `workdir` tem que ficar no mesmo `/storage`. Mover para `/var/tmp/archr` quebraria os 6 mount units de assets/cores/database/joypads/overlays/shaders do RetroArch. No-op.
-`/storage/.boot.hint`: arquivo de handshake entre o bootloader U-Boot e o sistema rodando, gravado pré-boot pelo bootloader e lido por `autostart/003-upgrade`. Compartilhar via FHS exigiria mexer no script u-boot, fora de escopo. No-op.
**Status: concluída (2026-06-23).** Toda state directory referenciada por systemd unit, runtime script ou config principal agora aponta para path Arch-convencional via bridge symlink. Os dados em disco não se moveram: o substrato continua `/storage/.cache/<x>`.
**Bridges instalados.** archr meta-package agora cria 7 bridges em F4 (services, samba/private, tailscale, cron) e outros pacotes plantam o seu próprio em post_install (openssh, iwd, bluez, connman). Padrão consistente: cada owner gerencia seu bridge.
**No-op por outras razões:**
-`/storage/.pacman/{db,cache}` → `/var/lib/pacman` e `/var/cache/pacman/pkg` já existem como bridges no `pacman/package.mk` (era convenção do pacote desde o começo).
-`/storage/.cache/rfkill` → `/var/lib/systemd/rfkill` já existe como `L+` no `tmpfiles.d/z_01_archr.conf`.
-`/storage/.kodi` não é referenciado por nenhum arquivo de `projects/ArchR/`: ArchR não roda Kodi (refs em `packages/` são herança LibreELEC top-level, não afetam o runtime).
**Realocado para outras fases:**
-`/storage/.local/share/<emu>` (dolphin, duckstation, gmu, m8c) é per-emulator data e vai em **F5** (Class B) junto com configs do mesmo emulador.
-`/storage/.pacman/{build,packages,sources,logs}` aguarda Arch-ification **2.1** (pacman wired ao userland).
-`/storage/.cache/timezone` aguarda **F7**: o path está embedded num patch do systemd (`systemd-0600-timedated-use-run-archr-localtime.patch`) e migrar requer regerar o patch.
-`/storage/{joypads,overlays,remappings,shaders,cores,database,assets}` são *upperdirs* de overlayfs montados pelos `system.d/tmp-*.mount` units do RetroArch. Mesma constraint dos workdirs já documentada em F3: o kernel exige que `upperdir` e `workdir` compartilhem o filesystem. Mover quebraria os 7 mount units. O usuário e RetroArch veem `/usr/share/retroarch-{assets,overlays,...}` montados, não os upperdirs.
**Status: concluída (2026-06-23) via bridge umbrella.** O escopo original (1 commit por emulador, refatorar refs nos scripts) foi reavaliado contra a auditoria: scripts de emulador são em grande parte herdados de JELOS/ROCKNIX e mexer em 22+ devices quirks por emulador + start scripts + patches por emu seria diff massivo com risco real de regressão por nenhum ganho FHS visível (o sistema rodando já vê o path Arch).
Resultado: do ponto de vista de qualquer ferramenta inspecionando o sistema rodando, todos os 76+ caminhos `/var/lib/archr/config/<emu>` e `/var/lib/archr/data/<emu>` existem e são writable. O ganho FHS visível é integral.
**Refs hardcoded `/storage/.config/<emu>` nos scripts ficam intactas.** Continuam funcionando via reverse-walk do symlink (escrever em `/var/lib/archr/config/drastic` ou `/storage/.config/drastic` aponta ambos para o mesmo overlay). Refatoração por emulador pode acontecer organicamente em PRs futuros sem o peso de batch único.
**Per-emulator data dirs (`/storage/.local/share/<emu>`):** mesma estratégia. Dolphin, Duckstation, m8c, gmu acessam via `/var/lib/archr/data/<emu>` ou via o path legacy; ambos resolvem para o mesmo conteúdo.
**Status: concluída (2026-06-23) via bridge umbrella.** Mesma decisão de F5, ainda mais consequente aqui: `/storage/roms` aparece em **117 arquivos** de `projects/ArchR/` (scripts de emulador, quirks por device, setsettings.sh, runemu.sh, smb.conf shares). Refatorar 117 arquivos numa única release seria diff massivo e ainda mais perigoso porque o substrato é onde a biblioteca de jogos do usuário reside.
| `/storage/screenshots` | 0 | herança LibreELEC top-level; sem refs no ArchR runtime |
| `/storage/recordings` | 0 | mesmo |
| `/storage/downloads` | 0 | mesmo |
| `/storage/music`, `/storage/pictures`, `/storage/videos`, `/storage/tvshows` | 0 | mesmo (Kodi media dirs, não usado) |
| `/storage/.ssh` | 4 | **no-op: já é FHS-correto** |
**Sobre `/storage/.ssh`:** o `add_user root` em `busybox/package.mk` define `$HOME=/storage` para o usuário root. Isso significa que `/storage/.ssh` literalmente é `$HOME/.ssh` para o único usuário do sistema, que é FHS-correto por definição. Mudar para `/root/.ssh` exigiria primeiro mudar o `$HOME` de root para `/root`, o que afeta `cd ~`, scripts que assumem cwd no login, etc — escopo de mudança de modelo de usuário, fora de F6.
**Sem migration script de dados.** O substrato (`/storage/roms`) não muda fisicamente: o bridge symlink resolve para o mesmo dir. ROMs e saves do usuário não são tocados, sem risco.
**Já cobertos por mecanismos anteriores (no-op):**
-`/storage/.opt` → `/opt` já é symlink criado pelo `virtual/image/package.mk` (line 109). FHS-correct desde sempre.
-`/storage/.emulationstation` → symlink para `/storage/.config/emulationstation` criado por `emulationstation/autostart/001-emulationstation`. Refs em `/storage/.emulationstation/es_*.cfg` resolvem para `/storage/.config/emulationstation/es_*.cfg`, que via umbrella bridge F5 também resolve para `/var/lib/archr/config/emulationstation/es_*.cfg`. Triplo-redirecionamento, tudo o mesmo conteúdo.
-`/storage/psvita/vita3k/ux0/app` em `scan_vita3k.sh`: dir do vita3k que reside em `/storage/psvita/`. Path top-level mas é específico do vita3k. Trivial demais para justificar um novo bridge; deixa-se como está.
-`/storage/.nfs-mount` em `Mount NFS.sh`: config file de NFS share. Path top-level usado como sentinel. Mover requer adicionar bridge `/etc/archr/nfs-mount.conf`; baixa prioridade.
**Final cleanup:**
- A revisão dos restantes 1625 refs a `/storage/` em `projects/ArchR/` foi feita: clusterizam em scripts de emulador (drastic, dolphin, daedalus, portmaster) e scripts core do ArchR (`post-update`, `factoryreset`, `automount`). Todos funcionam via compat (o substrato `/storage` continua existindo e os bridges instalados garantem que tanto o caminho FHS quanto o caminho legacy resolvem para o mesmo dir). Refatorar essas 1625 refs num único patch seria diff massivo sem ganho FHS visível ao sistema rodando; refatoração organica pode acontecer em PRs futuros sob demanda.
## Auditoria final do sistema
Após sete fases, o sistema rodando entrega:
- **17 bridge symlinks instalados pelo `archr` meta-package** mais bridges modulares em openssh, iwd, bluez, connman, fontconfig (5).
- **Todas as variáveis `ARCHR_*`** apontam para paths Arch-friendly:
-`ARCHR_ETC=/storage/.config` (system configs já no `/etc/*` via systemd symlinks build-time)
-`ARCHR_CONFIG=/var/lib/archr/config`
-`ARCHR_CACHE=/storage/.cache` (caches reais já bridged para `/var/cache/{mesa,fontconfig,archr/*}`)
-`ARCHR_DATA=/var/lib/archr/data`
-`ARCHR_GAMES=/var/lib/archr/games`
-`ARCHR_LOG=/storage/.cache/log` (= `/var/log` via mount)
- [x] Fase 0 concluída (2026-06-23): `010-archr-fhs` em `/etc/profile.d`, archr(7) com seção ENVIRONMENT, vars apontando para `/storage/...`. Risco zero.
- [x] Fase 1 marcada como no-op (2026-06-23): systemd já entrega `/etc/{modules-load.d,sysctl.d,tmpfiles.d,udev/{hwdb,rules}.d,systemd/*conf.d}` via symlinks de build-time. FHS-correto sem mudança. Detalhes na seção da Fase 1 deste documento.
- [x] Fase 4 concluída (2026-06-23): 9 state dirs (ssh, iwd, bluetooth, services, samba, connman, wireguard, tailscale, cron) movidos para paths Arch-convencionais via bridge symlinks. pacman db/cache e rfkill já eram bridges. `.local/share` realocado para F5. Detalhes na Fase 4.
- [x] Fase 5 concluída (2026-06-23): umbrella bridges `/var/lib/archr/{config,data}` instalados pelo `archr` meta-package, vars `ARCHR_CONFIG` / `ARCHR_DATA` flipadas para os paths Arch. Refs hardcoded /storage/.config/<emu> nos scripts ficam funcionais via compat. Detalhes na Fase 5.
- [x] Fase 6 concluída (2026-06-23): umbrella bridges `/var/lib/archr/{games,backup}` instalados, var `ARCHR_GAMES` flipada. /storage/.ssh marcado como no-op (é literalmente $HOME/.ssh do root). Detalhes na Fase 6.
- [x] Fase 7 concluída (2026-06-23): jdk + hatari + openbor bridged; demais Class Z (.opt, .emulationstation, vita3k path, .nfs-mount) cobertos por mecanismos anteriores ou marcados como baixa prioridade. Auditoria final em fhs-mapping.md.
- [x]**Migração FHS concluída** (2026-06-23). 17 bridges pelo `archr` meta-package + 5 modulares (openssh, iwd, bluez, connman, fontconfig). Sete vars `ARCHR_*` apontam para paths Arch-friendly. `/etc/archr-release` + `ID_LIKE=arch`. `archr(7)` documenta a arquitetura.
