Apêndice — Tecnologias do MVP V1
O que é isto: descrição resumida das tecnologias que sustentam os entregáveis E1–E11, com prós e contras no contexto deste projeto e referências aos documentos reais (ADRs do dev-machine, docs e código do pinha) que as adotam. Escopo: só o que os dossiês citam. Companheiro do
governance-mvp-v1.mde do dossiêDOSSIER-MVP-V1-e2-ambiente-alugado.md.
1. FreeBSD (host NeoTek)
Sistema operacional do host que provê os serviços de infraestrutura (NeoTek), com jails VNET isoladas por serviço e PF como firewall.
| Prós | Contras |
|---|---|
| Jails nativas (isolamento forte, custo baixo, sem hypervisor) | Ecossistema menor que Linux para tooling moderno (ex.: bb ausente no host) |
| PF: firewall stateful simples e auditável | Menos mão de obra no mercado; debugging menos popular |
| release/upgrade previsíveis por source | Alguns softwares só testados em Linux (ex.: containers Docker não nativos) |
Onde entra no MVP: host dos jails do small-pine (dev/prod interno) e do agente-hub; mise run check valida Ansible contra o FreeBSD real. Referências reais: ADR-0037 *per-pipeline CI jails* docs/adr/0037-per-pipeline-ci-jails.md, ADR-0057 *arch-tools VM on Chatsubo bhyve* docs/adr/0057-arch-tools-vm-on-chatsubo-bhyve.md, e a topologia no README do dev-machine.
2. Datomic (small-pine)
Banco de dados imutável (append-only), consultável via Datalog, usado como *authority store* de RBAC, auditoria e knowledge store do RAG.
| Prós | Contras |
|---|---|
| Imutabilidade nativa → trilha de auditoria natural (E9) | Requer processo JVM + transactor separado (jail datomic-jail) |
| Consultas Datalog expressivas para o modelo de acesso | Licença proprietária (não é OSS na versão usada) |
| Time-travel gratuito (query de estados passados) | Curva de aprendizado Datalog; ecossistema menor que SQL |
| "Sovereign Store": seed re-transacionado a cada boot (idempotente) |
Onde entra no MVP: service/authority.clj (RBAC seed de ::roles-config), trilha de auditoria E9 (hash-chain consultada por /v1/admin/audit/integrity), knowledge store do RAG (chunks com UUID próprio — §2 do governance). Referências reais: ADR-0003 *signed EDN transaction journal* e ADR-0046 *audit access facts in a derived Datomic read model* (dev-machine docs/adr/), além de apps/small-pine/src/small_pine/service/authority.clj no pinha (fonte da verdade de runtime) e docs/rag/rag-projeto-prod-implementacao.md.
3. Keycloak (OIDC / SSO)
Identity provider OIDC do Chatsubo; emite os tokens JWT que o small-pine valida por introspection (RFC 7662).
| Prós | Contras |
|---|---|
| Padrão aberto (OIDC), amplamente interoperável | Operação é um serviço a mais (jail/keycloak, upgrade, backup do realm) |
| Fluxos SSO + logout + introspection prontos (E3/E4) | Mapeamento de role depende de merge por email (causa raiz do FINDING-1) |
| Client confidential p/ introspection e público p/ browser | Configuração de realm é externa ao git (export/import manual) |
Onde entra no MVP: SSO de todo o aceite E3/E4 (sso-through-keycloak-oidc, signing-out-invalidates-the-session), introspection no gate de autenticação (§1.3). Referências reais: dossiê DOSSIER-MVP-V1-admin-access.md (§3 — mecanismo de role no OWUI), apps/small-pine/src/small_pine/service/keycloak.clj (pinha), scripts/operator/t3-keycloak-realm.sh (realm como código).
4. Open WebUI (frontend de chat)
Frontend de chat do Chatsubo, na frente do small-pine via proxy OIDC.
| Prós | Contras |
|---|---|
| UI madura (chat, upload, seleção de modelo) sem build próprio | Bugs do upstream vazam para o prod (ex.: streaming de 2026-09-14) |
| Integração OIDC + merge de contas por email | Comportamento sensível a config implícita (ui.default_models CSV → multi-select) |
| Build/customização precisa ser re-verificada a cada upgrade (build stale já ocorreu) |
Onde entra no MVP: superfície de chat aceita em E3/E4; o admin surface do OWUI (/admin/users) foi objeto do FINDING-1 (não é rota do small-pine). Referências reais: dossiê DOSSIER-MVP-V1-admin-access.md (§2/§3), role openwebui-jail-prod no Ansible do dev-machine, e a role openwebui-jail-prod no Ansible do dev-machine no pinha.
5. Slurm + vLLM (serving de LLM no Enverge/DGX Spark)
Fila de jobs (Slurm) orquestra instâncias vLLM nos nós GPU (DGX Spark); o small-pine adota os jobs :ready como backends quentes.
| Prós | Contras |
|---|---|
| Agendamento/fila multiusuário maduro | Complexidade operacional alta (trust domains, keys, enrollment) |
| vLLM: throughput de referência com batching contínuo | Cold-start de ~370 s (bench 05/09) — motivou o prewarm |
| Separação de domínios: prod nunca fala direto com a GPU | Versões de vLLM/CUDA presas ao venv do job |
Onde entra no MVP: E10 (baseline de desempenho — TTFT p50 ≤ 1 s, M4), hot ∪ was-hot (§1.1 do governance), prewarm via :schedule-model. Referências reais: ADR-0018/0029 *slurm engine & enverge gateway*, ADR-0025 *two slurm trust domains*, ADR-0055 *DGX Spark inference capacity*, enverge-model-bench.sh (dev-machine), logs evidence/20260905T055900Z-bench-m5/ e caderno M5-medicoes.
6. Pathom 3 (grafo de resolvers)
Camada de leitura EQL do small-pine: resolvers compõem o grafo de dados que atende o frontend e as superfícies administrativas.
| Prós | Contras |
|---|---|
| EQL: o cliente declara o que quer, não de onde | Debug de grafo exige ferramenta própria (pathom-viz) |
Permissões por atributo integram com RBAC (:read cobre o grafo) | Curva de aprendizado para quem vem de REST |
| Index híbrido eager/graph para hot paths |
Onde entra no MVP: todas as leituras (:read na §1.1), index do Pathom (pathom_index.clj), superfícies admin (E9). Referências reais: apps/small-pine/src/small_pine/service/pathom_index.clj, ADR-0004 *babashka+pathom control plane* (dev-machine), doc docs/architecture/architecture-target.md do pinha.
7. WireGuard (malha de acesso)
VPN de gerência (relay Vultr + NeoTek + clientes) — o plano de acesso protegido que os E2Es e operações de prod atravessam.
| Prós | Contras |
|---|---|
| Criptografia moderna, superfície mínima (UDP) | Sem descubimento dinâmico de peers (gestão manual) |
| Performance de kernel; roaming transparente | UDP 51820 pode ser bloqueado por redes hostis (hotspot) |
Endpoints .wg / .lan explícitos no config SSH |
Onde entra no MVP: acesso operacional a NeoTek/Chatsubo, túneis dos E2Es (e2e-small-pine-chatsubo.sh abre túnel SSH via WG). Referências reais: ADR-0009 *management VPN address space*, ADR-0054 *spark node firewall per bastion hop* (dev-machine docs/adr/).
8. Babashka (automação)
Clojure interpretado de boot rápido para scripts de operação ( runner de E2E, manifest de runs, catálogo).
| Prós | Contras |
|---|---|
| Clojure real em script (interop Java, libs bb) | Interpreted — não substitui JVM em serviço de longa vida |
| Boot instantâneo, ideal para CI/ansible callbacks | Não existe no FreeBSD host nativamente (limitação conhecida) |
Onde entra no MVP: e2e-run-manifest.bb (manifest das runs), scripts de migração (export_catalog.bb), control-plane do agent-hub (ADR-0004). Referências reais: ADR-0004 *babashka+pathom control plane*, ADR-0030 *babashka on neotek linux ABI* (dev-machine docs/adr/).
9. Presidio + OpenMed (scrub de PII)
Serviço Python (analyzer/anonymizer) + modelo NER pt-BR na fronteira do RAG.
| Prós | Contras |
|---|---|
Especializado em PII com perfis pt-BR (analyzer-pt.yaml etc.) | Serviço externo extra na fronteira (latência, operação) |
| Integrado ao fluxo quarantine (E7) | NER não é 100% — existe como barreira estrutural, não garantia |
Onde entra no MVP: E7 (pii-is-redacted-in-the-assistant-turn, privacy-visibility-scrubs-pii), entities_scrubbed na métrica M3. Referências reais: §2.3 do governance-mvp-v1.md, config ::rag-presidio-*/::rag-openmed-* no config.clj do pinha, run evidence/20260904T044108Z-da114ad.html.
*Apêndice gerado para o bundle de aceite MVP V1 — 2026-09-22. Os ADRs e docs referenciados foram copiados para este bundle (adr/, pinha-docs/) e todos os links internos são clicáveis.*